ai-code-map 0.0.0-stage → 0.1.0-alpha.3

package/schemas/project.schema.json

@@ -0,0 +1,192 @@
+{
+  "$defs": {
+    "__schema0": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "__schema1": {
+      "$ref": "#/$defs/__schema0"
+    },
+    "__schema2": {
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "$id": "urn:ai-code-map:project:4",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "compilerUnits": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "config": {
+            "$ref": "#/$defs/__schema1"
+          },
+          "extends": {
+            "items": {
+              "$ref": "#/$defs/__schema1"
+            },
+            "type": "array"
+          },
+          "id": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "configured",
+              "fallback"
+            ],
+            "type": "string"
+          },
+          "pathAliases": {
+            "additionalProperties": {
+              "items": {
+                "$ref": "#/$defs/__schema0"
+              },
+              "type": "array"
+            },
+            "propertyNames": {
+              "$ref": "#/$defs/__schema2"
+            },
+            "type": "object"
+          },
+          "references": {
+            "items": {
+              "$ref": "#/$defs/__schema1"
+            },
+            "type": "array"
+          },
+          "root": {
+            "$ref": "#/$defs/__schema0"
+          }
+        },
+        "required": [
+          "id",
+          "kind",
+          "root",
+          "references",
+          "extends",
+          "pathAliases"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "counts": {
+      "additionalProperties": false,
+      "properties": {
+        "diagnostics": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "files": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "relations": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "symbols": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "files",
+        "symbols",
+        "relations",
+        "diagnostics"
+      ],
+      "type": "object"
+    },
+    "entryPoints": {
+      "items": {
+        "$ref": "#/$defs/__schema1"
+      },
+      "type": "array"
+    },
+    "frameworks": {
+      "items": {
+        "enum": [
+          "typescript",
+          "node",
+          "react",
+          "nextjs",
+          "nestjs"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "name": {
+      "type": "string"
+    },
+    "packageManager": {
+      "type": "string"
+    },
+    "pathAliases": {
+      "additionalProperties": {
+        "items": {
+          "$ref": "#/$defs/__schema0"
+        },
+        "type": "array"
+      },
+      "propertyNames": {
+        "$ref": "#/$defs/__schema2"
+      },
+      "type": "object"
+    },
+    "schemaVersion": {
+      "const": 4,
+      "type": "number"
+    },
+    "tsconfig": {
+      "$ref": "#/$defs/__schema1"
+    },
+    "workspaces": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "entryPoints": {
+            "items": {
+              "$ref": "#/$defs/__schema1"
+            },
+            "type": "array"
+          },
+          "name": {
+            "type": "string"
+          },
+          "path": {
+            "$ref": "#/$defs/__schema1"
+          }
+        },
+        "required": [
+          "name",
+          "path",
+          "entryPoints"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "name",
+    "frameworks",
+    "compilerUnits",
+    "pathAliases",
+    "entryPoints",
+    "workspaces",
+    "counts"
+  ],
+  "title": "ai-code-map project record",
+  "type": "object"
+}

package/schemas/relation.schema.json

@@ -0,0 +1,142 @@
+{
+  "$defs": {
+    "__schema0": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "__schema1": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "__schema2": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "__schema3": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    }
+  },
+  "$id": "urn:ai-code-map:relation:4",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "confidence": {
+      "maximum": 1,
+      "minimum": 0,
+      "type": "number"
+    },
+    "from": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "origin": {
+      "additionalProperties": false,
+      "properties": {
+        "analyzer": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "classification": {
+          "enum": [
+            "exact",
+            "framework-derived",
+            "heuristic",
+            "derived"
+          ],
+          "type": "string"
+        },
+        "explanation": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "file": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "line": {
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991,
+          "type": "integer"
+        },
+        "range": {
+          "additionalProperties": false,
+          "properties": {
+            "endColumn": {
+              "$ref": "#/$defs/__schema3"
+            },
+            "endLine": {
+              "$ref": "#/$defs/__schema2"
+            },
+            "startColumn": {
+              "$ref": "#/$defs/__schema1"
+            },
+            "startLine": {
+              "$ref": "#/$defs/__schema0"
+            }
+          },
+          "required": [
+            "startLine",
+            "startColumn",
+            "endLine",
+            "endColumn"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "file",
+        "line",
+        "range",
+        "explanation",
+        "classification",
+        "analyzer"
+      ],
+      "type": "object"
+    },
+    "schemaVersion": {
+      "const": 4,
+      "type": "number"
+    },
+    "to": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "type": {
+      "enum": [
+        "imports",
+        "exports",
+        "reexports",
+        "calls",
+        "instantiates",
+        "renders",
+        "uses-hook",
+        "reads-state",
+        "depends-on",
+        "used-by",
+        "contains",
+        "references",
+        "injects",
+        "handles-route",
+        "consumes-dto",
+        "belongs-to-module",
+        "uses-layout"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "from",
+    "type",
+    "to",
+    "confidence",
+    "origin"
+  ],
+  "title": "ai-code-map relation record",
+  "type": "object"
+}

package/schemas/symbol.schema.json

@@ -0,0 +1,165 @@
+{
+  "$defs": {
+    "__schema0": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "__schema1": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "__schema2": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "__schema3": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "__schema4": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        },
+        {
+          "items": {
+            "$ref": "#/$defs/__schema4"
+          },
+          "type": "array"
+        },
+        {
+          "additionalProperties": {
+            "$ref": "#/$defs/__schema4"
+          },
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        }
+      ]
+    }
+  },
+  "$id": "urn:ai-code-map:symbol:4",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "defaultExport": {
+      "type": "boolean"
+    },
+    "documentation": {
+      "type": "string"
+    },
+    "exported": {
+      "type": "boolean"
+    },
+    "facts": {
+      "additionalProperties": {
+        "$ref": "#/$defs/__schema4"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "file": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "id": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "function",
+        "class",
+        "method",
+        "interface",
+        "type-alias",
+        "variable",
+        "react-component",
+        "react-hook",
+        "react-context",
+        "next-page",
+        "next-layout",
+        "next-route-handler",
+        "next-special-file",
+        "nest-module",
+        "nest-controller",
+        "nest-provider",
+        "nest-guard",
+        "nest-interceptor",
+        "nest-pipe",
+        "nest-filter",
+        "nest-gateway",
+        "dto",
+        "route"
+      ],
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "range": {
+      "additionalProperties": false,
+      "properties": {
+        "endColumn": {
+          "$ref": "#/$defs/__schema3"
+        },
+        "endLine": {
+          "$ref": "#/$defs/__schema2"
+        },
+        "startColumn": {
+          "$ref": "#/$defs/__schema1"
+        },
+        "startLine": {
+          "$ref": "#/$defs/__schema0"
+        }
+      },
+      "required": [
+        "startLine",
+        "startColumn",
+        "endLine",
+        "endColumn"
+      ],
+      "type": "object"
+    },
+    "schemaVersion": {
+      "const": 4,
+      "type": "number"
+    },
+    "signature": {
+      "type": "string"
+    },
+    "sourceHash": {
+      "pattern": "^[a-f0-9]{64}$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "id",
+    "name",
+    "kind",
+    "file",
+    "range",
+    "exported",
+    "facts",
+    "sourceHash"
+  ],
+  "title": "ai-code-map symbol record",
+  "type": "object"
+}

package/skills/ai-code-map/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ai-code-map
+description: Use when tracing TypeScript or JavaScript behavior in a project indexed by ai-code-map, or when the user requests map-guided navigation.
+---
+
+# Retrieve source through the map
+
+Run from the source project root with its installed CLI. Do not install or upgrade
+it just to navigate. Source establishes behavior; graph relations are navigation
+hints, and missing edges do not prove absence.
+
+For an unknown flow, start with `ai-code-map context 'action subject words'`.
+Include the action as well as the subject, for example `notification mark read`.
+This command checks freshness and returns matching
+source plus direct neighbors, merging ranges under one shared budget. A separate
+`check` or overview is unnecessary before it. Partial matches name unmatched words;
+judge relevance from the returned source.
+
+Use that packet to answer or identify a specific missing fact. Reuse its source.
+Read a printed omitted range only if it matters. For one dependency outside the
+packet, use `read '<stable-id>'` or its bounded source range. If its ID and source
+location are unknown, use `find 'qualified symbol name'` first. Do not use another
+`context` call merely to read a helper: it also expands callers and neighbors.
+Batch independent
+reads; combine needed ranges in the same file. Avoid traversing every neighbor or
+splitting one useful file window into many tiny symbol reads.
+
+Use targeted `rg` for file-level facts such as route registration, configuration
+and test discovery, or for a failed/irrelevant lookup. Discover paths with
+`rg --files -g 'pattern'` before reading them. Use
+`show '<id>'` only for an unresolved relation question. Do not dump the complete
+map for an ordinary source task. Stop when the requested claims have evidence.
+In the answer, connect each requested entry point to its inputs, state changes,
+error path and caller effects. Keep navigation-status commentary brief.
+
+If `context` is unavailable, check freshness once, then use `find` and `read` or
+bounded source ranges. If stale, scan only when writing generated artifacts is
+allowed; otherwise use source search. Cite original file and line numbers.
+Do not claim token savings without a measured comparison.