@documentation-robotics/cli 0.1.13 → 0.3.0

package/dist/analyzers/cards/facts.js

@@ -0,0 +1,46 @@
+function decoratorName(text) {
+  return text.trim().replace(/^@/, "").replace(/\s*#.*$/, "").replace(/\(.*$/s, "").trim();
+}
+function parseList(v) {
+  if (Array.isArray(v))
+    return v.map(String);
+  if (typeof v != "string" || !v.trim())
+    return [];
+  try {
+    const p = JSON.parse(v);
+    return Array.isArray(p) ? p.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+async function buildFactsIndex(graph) {
+  const decorators = /* @__PURE__ */ new Map();
+  for (const [qn, decs] of await graph.rows("MATCH (b) WHERE b.decorators IS NOT NULL RETURN b.qualified_name, b.decorators"))
+    typeof qn == "string" && decorators.set(qn, parseList(decs));
+  const importers = /* @__PURE__ */ new Map();
+  for (const [afile, bfile] of await graph.rows("MATCH (a)-[r:IMPORTS]->(b) RETURN a.file_path, b.file_path"))
+    typeof afile != "string" || typeof bfile != "string" || !bfile || afile === bfile || (importers.has(bfile) || importers.set(bfile, /* @__PURE__ */ new Set()), importers.get(bfile).add(afile));
+  const methods = /* @__PURE__ */ new Map();
+  for (const [a] of await graph.rows("MATCH (a)-[r:DEFINES_METHOD]->(m) RETURN a.qualified_name, m.qualified_name"))
+    typeof a == "string" && methods.set(a, (methods.get(a) ?? 0) + 1);
+  const usage = /* @__PURE__ */ new Map();
+  for (const [afile, b, bfile] of await graph.rows("MATCH (a)-[r:USAGE]->(b) RETURN a.file_path, b.qualified_name, b.file_path"))
+    typeof afile != "string" || typeof b != "string" || afile === bfile || (usage.has(b) || usage.set(b, /* @__PURE__ */ new Set()), usage.get(b).add(afile));
+  return { decorators, importers, methods, usage };
+}
+function factsFor(idx, fullQualifiedName, filePath) {
+  const decorators = idx.decorators.get(fullQualifiedName) ?? [];
+  return {
+    decorators,
+    decorator_names: decorators.map(decoratorName),
+    file_importers: filePath ? idx.importers.get(filePath)?.size ?? 0 : 0,
+    methods: idx.methods.get(fullQualifiedName) ?? 0,
+    usage_files: idx.usage.get(fullQualifiedName)?.size ?? 0
+  };
+}
+export {
+  buildFactsIndex,
+  decoratorName,
+  factsFor
+};
+//# sourceMappingURL=facts.js.map

package/dist/analyzers/cards/facts.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/analyzers/cards/facts.ts"],
+  "sourcesContent": ["/**\n * Tier-0 structural facts: decorators and a few reuse counts, from one graph query per fact.\n */\nimport type { CardFacts, CardGraph } from \"./types.js\";\n\n/** `@field_validator(\"X\", mode=\"before\")` -> `field_validator`; `@router.get('/')` -> `router.get`. */\nexport function decoratorName(text: string): string {\n  return text.trim().replace(/^@/, \"\").replace(/\\s*#.*$/, \"\").replace(/\\(.*$/s, \"\").trim();\n}\n\n/** CBM stores decorators as a JSON-encoded list (or, in some builds, a real one). */\nfunction parseList(v: unknown): string[] {\n  if (Array.isArray(v)) return v.map(String);\n  if (typeof v !== \"string\" || !v.trim()) return [];\n  try {\n    const p = JSON.parse(v);\n    return Array.isArray(p) ? p.map(String) : [];\n  } catch {\n    return [];\n  }\n}\n\nexport interface FactsIndex {\n  /** full qualified name -> decorator texts */\n  decorators: Map<string, string[]>;\n  /** file path -> other files importing it */\n  importers: Map<string, Set<string>>;\n  /** full qualified name -> DEFINES_METHOD count */\n  methods: Map<string, number>;\n  /** full qualified name -> other files with USAGE edges into it */\n  usage: Map<string, Set<string>>;\n}\n\nexport async function buildFactsIndex(graph: CardGraph): Promise<FactsIndex> {\n  const decorators = new Map<string, string[]>();\n  for (const [qn, decs] of await graph.rows(\"MATCH (b) WHERE b.decorators IS NOT NULL RETURN b.qualified_name, b.decorators\")) {\n    if (typeof qn === \"string\") decorators.set(qn, parseList(decs));\n  }\n  const importers = new Map<string, Set<string>>();\n  for (const [afile, bfile] of await graph.rows(\"MATCH (a)-[r:IMPORTS]->(b) RETURN a.file_path, b.file_path\")) {\n    if (typeof afile !== \"string\" || typeof bfile !== \"string\" || !bfile || afile === bfile) continue;\n    if (!importers.has(bfile)) importers.set(bfile, new Set());\n    importers.get(bfile)!.add(afile);\n  }\n  const methods = new Map<string, number>();\n  for (const [a] of await graph.rows(\"MATCH (a)-[r:DEFINES_METHOD]->(m) RETURN a.qualified_name, m.qualified_name\")) {\n    if (typeof a === \"string\") methods.set(a, (methods.get(a) ?? 0) + 1);\n  }\n  const usage = new Map<string, Set<string>>();\n  for (const [afile, b, bfile] of await graph.rows(\"MATCH (a)-[r:USAGE]->(b) RETURN a.file_path, b.qualified_name, b.file_path\")) {\n    if (typeof afile !== \"string\" || typeof b !== \"string\" || afile === bfile) continue;\n    if (!usage.has(b)) usage.set(b, new Set());\n    usage.get(b)!.add(afile);\n  }\n  return { decorators, importers, methods, usage };\n}\n\n/** Facts for one symbol, by its full (project-prefixed) qualified name and file. */\nexport function factsFor(idx: FactsIndex, fullQualifiedName: string, filePath: string | null): CardFacts {\n  const decorators = idx.decorators.get(fullQualifiedName) ?? [];\n  return {\n    decorators,\n    decorator_names: decorators.map(decoratorName),\n    file_importers: filePath ? (idx.importers.get(filePath)?.size ?? 0) : 0,\n    methods: idx.methods.get(fullQualifiedName) ?? 0,\n    usage_files: idx.usage.get(fullQualifiedName)?.size ?? 0,\n  };\n}\n"],
+  "mappings": "AAMM,SAAU,cAAc,MAAY;AACxC,SAAO,KAAK,KAAI,EAAG,QAAQ,MAAM,EAAE,EAAE,QAAQ,WAAW,EAAE,EAAE,QAAQ,UAAU,EAAE,EAAE,KAAI;AACxF;AAGA,SAAS,UAAU,GAAU;AAC3B,MAAI,MAAM,QAAQ,CAAC;AAAG,WAAO,EAAE,IAAI,MAAM;AACzC,MAAI,OAAO,KAAM,YAAY,CAAC,EAAE,KAAI;AAAI,WAAO,CAAA;AAC/C,MAAI;AACF,UAAM,IAAI,KAAK,MAAM,CAAC;AACtB,WAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,IAAI,MAAM,IAAI,CAAA;EAC5C,QAAQ;AACN,WAAO,CAAA;EACT;AACF;AAaA,eAAsB,gBAAgB,OAAgB;AACpD,QAAM,aAAa,oBAAI,IAAG;AAC1B,aAAW,CAAC,IAAI,IAAI,KAAK,MAAM,MAAM,KAAK,gFAAgF;AACxH,IAAI,OAAO,MAAO,YAAU,WAAW,IAAI,IAAI,UAAU,IAAI,CAAC;AAEhE,QAAM,YAAY,oBAAI,IAAG;AACzB,aAAW,CAAC,OAAO,KAAK,KAAK,MAAM,MAAM,KAAK,4DAA4D;AACxG,IAAI,OAAO,SAAU,YAAY,OAAO,SAAU,YAAY,CAAC,SAAS,UAAU,UAC7E,UAAU,IAAI,KAAK,KAAG,UAAU,IAAI,OAAO,oBAAI,IAAG,CAAE,GACzD,UAAU,IAAI,KAAK,EAAG,IAAI,KAAK;AAEjC,QAAM,UAAU,oBAAI,IAAG;AACvB,aAAW,CAAC,CAAC,KAAK,MAAM,MAAM,KAAK,6EAA6E;AAC9G,IAAI,OAAO,KAAM,YAAU,QAAQ,IAAI,IAAI,QAAQ,IAAI,CAAC,KAAK,KAAK,CAAC;AAErE,QAAM,QAAQ,oBAAI,IAAG;AACrB,aAAW,CAAC,OAAO,GAAG,KAAK,KAAK,MAAM,MAAM,KAAK,4EAA4E;AAC3H,IAAI,OAAO,SAAU,YAAY,OAAO,KAAM,YAAY,UAAU,UAC/D,MAAM,IAAI,CAAC,KAAG,MAAM,IAAI,GAAG,oBAAI,IAAG,CAAE,GACzC,MAAM,IAAI,CAAC,EAAG,IAAI,KAAK;AAEzB,SAAO,EAAE,YAAY,WAAW,SAAS,MAAK;AAChD;AAGM,SAAU,SAAS,KAAiB,mBAA2B,UAAuB;AAC1F,QAAM,aAAa,IAAI,WAAW,IAAI,iBAAiB,KAAK,CAAA;AAC5D,SAAO;IACL;IACA,iBAAiB,WAAW,IAAI,aAAa;IAC7C,gBAAgB,WAAY,IAAI,UAAU,IAAI,QAAQ,GAAG,QAAQ,IAAK;IACtE,SAAS,IAAI,QAAQ,IAAI,iBAAiB,KAAK;IAC/C,aAAa,IAAI,MAAM,IAAI,iBAAiB,GAAG,QAAQ;;AAE3D;",
+  "names": []
+}

package/dist/analyzers/cards/graph.js

@@ -0,0 +1,42 @@
+import { CbmToolError } from "../cbm-responses.js";
+function graphNodeOf(node) {
+  const qualifiedName = String(node.qualified_name ?? node.name ?? "");
+  return {
+    ...node.properties ?? {},
+    label: node.label,
+    name: node.label === "Route" ? qualifiedName : String(node.name ?? ""),
+    qualified_name: qualifiedName,
+    file_path: typeof node.file_path == "string" ? node.file_path : ""
+  };
+}
+function cbmCardGraph(tools, project) {
+  return {
+    project,
+    async search(label, filePattern, fields) {
+      return (await tools.searchGraph({
+        project,
+        label,
+        ...filePattern ? { file_pattern: filePattern } : {},
+        ...fields.length ? { fields } : {}
+      })).map(graphNodeOf);
+    },
+    async rows(cypher) {
+      return (await tools.queryGraph(cypher, project)).rows;
+    },
+    async snippet(qualifiedName) {
+      try {
+        const raw = await tools.call("get_code_snippet", { project, qualified_name: qualifiedName, source_mode: "full" });
+        return raw && typeof raw.source == "string" ? { source: raw.source } : null;
+      } catch (error) {
+        if (error instanceof CbmToolError)
+          return null;
+        throw error;
+      }
+    }
+  };
+}
+export {
+  cbmCardGraph,
+  graphNodeOf
+};
+//# sourceMappingURL=graph.js.map

package/dist/analyzers/cards/graph.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/analyzers/cards/graph.ts"],
+  "sourcesContent": ["/**\n * The card builder's view of a CBM project, over the analyzer's {@link CbmTools}.\n */\nimport { CbmToolError, type CbmGraphNode, type CbmTools } from \"../cbm-responses.js\";\nimport type { CardGraph, GraphNode } from \"./types.js\";\n\n/**\n * Flatten a normalised search_graph node: its properties become top-level fields. A Route keeps\n * its full qualified name (`__route__GET__/owners`) as its name, since CBM's own name for it is\n * only the path, or a fragment of it.\n */\nexport function graphNodeOf(node: CbmGraphNode): GraphNode {\n  const qualifiedName = String(node.qualified_name ?? node.name ?? \"\");\n  const props = node.properties ?? {};\n  return {\n    ...props,\n    label: node.label,\n    name: node.label === \"Route\" ? qualifiedName : String(node.name ?? \"\"),\n    qualified_name: qualifiedName,\n    file_path: typeof node.file_path === \"string\" ? node.file_path : \"\",\n  };\n}\n\nexport function cbmCardGraph(tools: CbmTools, project: string): CardGraph {\n  return {\n    project,\n    async search(label, filePattern, fields) {\n      const nodes = await tools.searchGraph({\n        project,\n        label,\n        ...(filePattern ? { file_pattern: filePattern } : {}),\n        ...(fields.length ? { fields } : {}),\n      });\n      return nodes.map(graphNodeOf);\n    },\n    async rows(cypher) {\n      return (await tools.queryGraph(cypher, project)).rows;\n    },\n    async snippet(qualifiedName) {\n      try {\n        // CBM 0.12's default (\"auto\") outlines containers of 200+ lines and caps output at about\n        // 2,500 tokens; \"full\" returns the source (up to 500 lines, uncapped).\n        const raw = (await tools.call(\"get_code_snippet\", { project, qualified_name: qualifiedName, source_mode: \"full\" })) as { source?: unknown };\n        return raw && typeof raw.source === \"string\" ? { source: raw.source } : null;\n      } catch (error) {\n        // An unknown or source-less symbol comes back as an error payload: no source.\n        if (error instanceof CbmToolError) return null;\n        throw error;\n      }\n    },\n  };\n}\n"],
+  "mappings": "AAGA,SAAS,oBAAsD;AAQzD,SAAU,YAAY,MAAkB;AAC5C,QAAM,gBAAgB,OAAO,KAAK,kBAAkB,KAAK,QAAQ,EAAE;AAEnE,SAAO;IACL,GAFY,KAAK,cAAc,CAAA;IAG/B,OAAO,KAAK;IACZ,MAAM,KAAK,UAAU,UAAU,gBAAgB,OAAO,KAAK,QAAQ,EAAE;IACrE,gBAAgB;IAChB,WAAW,OAAO,KAAK,aAAc,WAAW,KAAK,YAAY;;AAErE;AAEM,SAAU,aAAa,OAAiB,SAAe;AAC3D,SAAO;IACL;IACA,MAAM,OAAO,OAAO,aAAa,QAAM;AAOrC,cANc,MAAM,MAAM,YAAY;QACpC;QACA;QACA,GAAI,cAAc,EAAE,cAAc,YAAW,IAAK,CAAA;QAClD,GAAI,OAAO,SAAS,EAAE,OAAM,IAAK,CAAA;OAClC,GACY,IAAI,WAAW;IAC9B;IACA,MAAM,KAAK,QAAM;AACf,cAAQ,MAAM,MAAM,WAAW,QAAQ,OAAO,GAAG;IACnD;IACA,MAAM,QAAQ,eAAa;AACzB,UAAI;AAGF,cAAM,MAAO,MAAM,MAAM,KAAK,oBAAoB,EAAE,SAAS,gBAAgB,eAAe,aAAa,OAAM,CAAE;AACjH,eAAO,OAAO,OAAO,IAAI,UAAW,WAAW,EAAE,QAAQ,IAAI,OAAM,IAAK;MAC1E,SAAS,OAAO;AAEd,YAAI,iBAAiB;AAAc,iBAAO;AAC1C,cAAM;MACR;IACF;;AAEJ;",
+  "names": []
+}

package/dist/analyzers/cards/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./graph.js";
+export * from "./edge-index.js";
+export * from "./facts.js";
+export * from "./build.js";
+export * from "./tier0.js";
+export * from "./classify.js";
+//# sourceMappingURL=index.js.map

package/dist/analyzers/cards/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/analyzers/cards/index.ts"],
+  "sourcesContent": ["export * from \"./types.js\";\nexport * from \"./graph.js\";\nexport * from \"./edge-index.js\";\nexport * from \"./facts.js\";\nexport * from \"./build.js\";\nexport * from \"./tier0.js\";\nexport * from \"./classify.js\";\n"],
+  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "names": []
+}

package/dist/analyzers/cards/tier0.js

@@ -0,0 +1,18 @@
+import { declarationOf, evaluateTier0 } from "../tier0-rules.js";
+function tier0SymbolOf(card, facts) {
+  return {
+    label: card.label,
+    name: card.name,
+    file_path: card.file_path,
+    declaration: declarationOf(card.source, card.signature),
+    decorator_names: facts?.decorator_names ?? []
+  };
+}
+function tier0ForCard(card, facts, rules) {
+  return evaluateTier0(tier0SymbolOf(card, facts), rules);
+}
+export {
+  tier0ForCard,
+  tier0SymbolOf
+};
+//# sourceMappingURL=tier0.js.map

package/dist/analyzers/cards/tier0.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/analyzers/cards/tier0.ts"],
+  "sourcesContent": ["/**\n * Tier 0 on cards: the analyzer's rules (src/analyzers/tier0-rules.ts) applied to a card and its\n * facts. Used by `dr analyzer classify` and by the classify-eval harness.\n */\nimport { declarationOf, evaluateTier0, type Tier0Outcome, type Tier0Rule, type Tier0Symbol } from \"../tier0-rules.js\";\nimport type { CardFacts } from \"./types.js\";\n\n/** The card fields Tier 0 reads (a harness card, with its corpus field, also fits). */\nexport type Tier0Card = { label: string; name: string; file_path: string | null; source: string | null; signature: string | null };\n\nexport function tier0SymbolOf(card: Tier0Card, facts: CardFacts | undefined): Tier0Symbol {\n  return {\n    label: card.label,\n    name: card.name,\n    file_path: card.file_path,\n    declaration: declarationOf(card.source, card.signature),\n    decorator_names: facts?.decorator_names ?? [],\n  };\n}\n\nexport function tier0ForCard(card: Tier0Card, facts: CardFacts | undefined, rules: Tier0Rule[]): Tier0Outcome | null {\n  return evaluateTier0(tier0SymbolOf(card, facts), rules);\n}\n"],
+  "mappings": "AAIA,SAAS,eAAe,qBAA0E;AAM5F,SAAU,cAAc,MAAiB,OAA4B;AACzE,SAAO;IACL,OAAO,KAAK;IACZ,MAAM,KAAK;IACX,WAAW,KAAK;IAChB,aAAa,cAAc,KAAK,QAAQ,KAAK,SAAS;IACtD,iBAAiB,OAAO,mBAAmB,CAAA;;AAE/C;AAEM,SAAU,aAAa,MAAiB,OAA8B,OAAkB;AAC5F,SAAO,cAAc,cAAc,MAAM,KAAK,GAAG,KAAK;AACxD;",
+  "names": []
+}

package/dist/analyzers/cards/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/analyzers/cards/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}