_index.yaml

version: "1.0"
namespace: code_graph

entries:
  - name: definition
    kind: ns.definition
    readme: file://README.md
    meta:
      title: Code Graph
      description: Cross-file PHP code analysis — dependency trees, call chains, usage search

  # ===========================================================================
  # Dependencies
  # ===========================================================================

  - name: dependency.mcp
    kind: ns.dependency
    component: butschster/mcp-server
    version: ">=0.1.0"

  # ===========================================================================
  # Shared Libraries
  # ===========================================================================

  - name: php_extractor
    kind: library.lua
    source: file://php_extractor.lua
    modules:
      - treesitter

  - name: resolver_lib
    kind: library.lua
    source: file://resolver_lib.lua

  - name: graph_lib
    kind: library.lua
    source: file://graph_lib.lua

  - name: index_lib
    kind: library.lua
    source: file://index_lib.lua
    modules:
      - fs
      - registry
      - treesitter
      - json
      - logger
    imports:
      extractor: code_graph:php_extractor
      resolver: code_graph:resolver_lib
      graph: code_graph:graph_lib

  - name: query_lib
    kind: library.lua
    source: file://query_lib.lua
    imports:
      graph: code_graph:graph_lib

  - name: format_lib
    kind: library.lua
    source: file://format_lib.lua

  - name: tool_lib
    kind: library.lua
    source: file://tool_lib.lua
    modules:
      - time

  # ===========================================================================
  # Index Process (Actor)
  # ===========================================================================

  - name: processes
    kind: process.host
    host:
      workers: 8
    lifecycle:
      auto_start: true

  - name: index_process
    kind: process.lua
    source: file://index_process.lua
    method: main
    modules:
      - fs
      - registry
      - treesitter
      - json
      - logger
      - time
    imports:
      index_lib: code_graph:index_lib
      query_lib: code_graph:query_lib
      graph: code_graph:graph_lib

  - name: index_service
    kind: process.service
    process: code_graph:index_process
    host: code_graph:processes
    lifecycle:
      auto_start: true
      stable_threshold: 3s
      restart:
        max_attempts: 5
        initial_delay: 2s
        backoff_factor: 2.0

  # ===========================================================================
  # MCP Tools
  # ===========================================================================

  # --- code_index: trigger project indexing ---

  - name: code_index
    kind: function.lua
    source: file://code_index.lua
    method: call
    modules:
      - time
    imports:
      tools: code_graph:tool_lib
      fmt: code_graph:format_lib
    meta:
      mcp.tool: true
      mcp.name: "code_index"
      mcp.description: >
        Index a PHP project for cross-file analysis. Scans all .php files,
        extracts classes, methods, functions, and all references (calls, type hints,
        inheritance, imports). Must be run before other code_graph tools.
      mcp.inputSchema:
        type: "object"
        properties:
          project:
            type: "string"
            description: "Project identifier (uses default if omitted)"
          path:
            type: "string"
            description: "Subdirectory to index (default: entire project)"
          force:
            type: "boolean"
            description: "Force re-index even if already indexed"
      mcp.annotations:
        readOnlyHint: true

  # --- code_deps: file dependency tree ---

  - name: code_deps
    kind: function.lua
    source: file://code_deps.lua
    method: call
    modules:
      - time
    imports:
      tools: code_graph:tool_lib
      fmt: code_graph:format_lib
    meta:
      mcp.tool: true
      mcp.name: "code_deps"
      mcp.description: >
        Show file/namespace dependency tree. Displays what a file imports
        (and transitively) and what files import it.
      mcp.inputSchema:
        type: "object"
        properties:
          file:
            type: "string"
            description: "File path or class/namespace name to analyze"
          direction:
            type: "string"
            enum: ["imports", "imported_by", "both"]
            description: "Direction: imports, imported_by, both (default: both)"
          depth:
            type: "integer"
            description: "Max transitive depth (default: 3, max: 10)"
            minimum: 1
            maximum: 10
          project:
            type: "string"
            description: "Project identifier"
        required:
          - "file"
      mcp.annotations:
        readOnlyHint: true

  # --- code_usages: find all references ---

  - name: code_usages
    kind: function.lua
    source: file://code_usages.lua
    method: call
    modules:
      - time
    imports:
      tools: code_graph:tool_lib
      fmt: code_graph:format_lib
    meta:
      mcp.tool: true
      mcp.name: "code_usages"
      mcp.description: >
        Find all references to a symbol (class, method, function) across the project.
        Like "Find All References" in an IDE. Groups results by file.
      mcp.inputSchema:
        type: "object"
        properties:
          symbol:
            type: "string"
            description: "Symbol name — short ('OrderService') or FQN ('App\\Services\\OrderService') or method ('OrderService::process')"
          kind:
            type: "string"
            enum: ["all", "instantiation", "static_call", "method_call", "type_hint", "extends", "implements", "import"]
            description: "Filter by reference kind (default: all)"
          project:
            type: "string"
        required:
          - "symbol"
      mcp.annotations:
        readOnlyHint: true

  # --- code_callers: call chain upward ---

  - name: code_callers
    kind: function.lua
    source: file://code_callers.lua
    method: call
    modules:
      - time
    imports:
      tools: code_graph:tool_lib
      fmt: code_graph:format_lib
    meta:
      mcp.tool: true
      mcp.name: "code_callers"
      mcp.description: >
        Find the call chain leading TO a function or method. Shows who calls it,
        who calls those callers, etc. Useful for understanding entry points.
      mcp.inputSchema:
        type: "object"
        properties:
          symbol:
            type: "string"
            description: "Function/method — 'processPayment', 'OrderService::process', or FQN"
          depth:
            type: "integer"
            description: "Levels of callers to trace (default: 3, max: 10)"
            minimum: 1
            maximum: 10
          project:
            type: "string"
        required:
          - "symbol"
      mcp.annotations:
        readOnlyHint: true

  # --- code_callees: call chain downward ---

  - name: code_callees
    kind: function.lua
    source: file://code_callees.lua
    method: call
    modules:
      - time
    imports:
      tools: code_graph:tool_lib
      fmt: code_graph:format_lib
    meta:
      mcp.tool: true
      mcp.name: "code_callees"
      mcp.description: >
        Find what a function or method calls internally. Shows outgoing call tree.
      mcp.inputSchema:
        type: "object"
        properties:
          symbol:
            type: "string"
            description: "Function/method to analyze"
          depth:
            type: "integer"
            description: "Depth to follow callees (default: 2, max: 10)"
            minimum: 1
            maximum: 10
          project:
            type: "string"
        required:
          - "symbol"
      mcp.annotations:
        readOnlyHint: true

  # --- code_hierarchy: inheritance tree ---

  - name: code_hierarchy
    kind: function.lua
    source: file://code_hierarchy.lua
    method: call
    modules:
      - time
    imports:
      tools: code_graph:tool_lib
      fmt: code_graph:format_lib
    meta:
      mcp.tool: true
      mcp.name: "code_hierarchy"
      mcp.description: >
        Show inheritance and implementation tree for a class or interface.
        Upward shows parent chain, downward shows all subclasses/implementations.
      mcp.inputSchema:
        type: "object"
        properties:
          symbol:
            type: "string"
            description: "Class or interface name"
          direction:
            type: "string"
            enum: ["up", "down", "both"]
            description: "up=ancestors, down=descendants, both (default)"
          project:
            type: "string"
        required:
          - "symbol"
      mcp.annotations:
        readOnlyHint: true

  # --- code_impacted: impact analysis ---

  - name: code_impacted
    kind: function.lua
    source: file://code_impacted.lua
    method: call
    modules:
      - time
    imports:
      tools: code_graph:tool_lib
      fmt: code_graph:format_lib
    meta:
      mcp.tool: true
      mcp.name: "code_impacted"
      mcp.description: >
        Impact analysis: what files would be affected by changing a given file or symbol.
        Follows reference chains transitively.
      mcp.inputSchema:
        type: "object"
        properties:
          file:
            type: "string"
            description: "File path or symbol name to analyze"
          depth:
            type: "integer"
            description: "Transitive depth (default: 2, max: 5)"
            minimum: 1
            maximum: 5
          project:
            type: "string"
        required:
          - "file"
      mcp.annotations:
        readOnlyHint: true

  # --- code_graph: visual graph export ---

  - name: code_graph_viz
    kind: function.lua
    source: file://code_graph_viz.lua
    method: call
    modules:
      - time
    imports:
      tools: code_graph:tool_lib
      fmt: code_graph:format_lib
    meta:
      mcp.tool: true
      mcp.name: "code_graph"
      mcp.description: >
        Generate a visual dependency or call graph in Mermaid format.
      mcp.inputSchema:
        type: "object"
        properties:
          symbol:
            type: "string"
            description: "Center of graph — file path or symbol name"
          type:
            type: "string"
            enum: ["dependencies", "callers", "callees", "hierarchy"]
            description: "Graph type (default: dependencies)"
          depth:
            type: "integer"
            description: "Graph depth (default: 2, max: 5)"
            minimum: 1
            maximum: 5
          project:
            type: "string"
        required:
          - "symbol"
      mcp.annotations:
        readOnlyHint: true