@titan-design/code-graph 0.7.0 → 0.8.0

package/dist/index.js

@@ -189,6 +189,9 @@ function readMetricAggregates(stmts, snapshotId, name) {
 
 // src/store.ts
 var NODE_COLS = "id, kind, name, parent_id, language, role, attrs";
+function isStructuralLayer(edge) {
+  return edge.kind !== "references" && edge.kind !== "calls";
+}
 var CodeGraphStore = class {
   constructor(db) {
     this.db = db;
@@ -307,10 +310,10 @@ var CodeGraphStore = class {
     const nodes = this.statements.listNodes.all(snapshotId).map(rowToNode);
     return opts?.includeSymbols ? nodes : nodes.filter((n) => n.kind !== "symbol");
   }
-  /** See {@link listNodes}: `references` edges are the symbol layer, excluded by default. */
+  /** See {@link listNodes}: `references` and `calls` edges are the symbol layer, excluded by default. */
   listEdges(snapshotId, opts) {
     const edges = this.statements.listEdges.all(snapshotId).map(rowToEdge);
-    return opts?.includeReferences ? edges : edges.filter((e) => e.kind !== "references");
+    return opts?.includeReferences ? edges : edges.filter(isStructuralLayer);
   }
   listMetrics(snapshotId) {
     return this.statements.listMetrics.all(snapshotId).map(rowToMetric);
@@ -327,10 +330,10 @@ var CodeGraphStore = class {
   topByMetric(opts) {
     return readTopByMetric(this.targeted, opts);
   }
-  /** Edges into or out of one node; `references` edges are excluded unless asked, as in {@link listEdges}. */
+  /** Edges into or out of one node; symbol-layer edges are excluded unless asked, as in {@link listEdges}. */
   listEdgesTouching(snapshotId, nodeId, opts) {
     const edges = readEdgesTouching(this.targeted, snapshotId, nodeId);
-    return opts?.includeReferences ? edges : edges.filter((e) => e.kind !== "references");
+    return opts?.includeReferences ? edges : edges.filter(isStructuralLayer);
   }
   /** Count, sum, min, and max per metric name and node kind; pass `name` for one metric. */
   aggregateMetrics(snapshotId, opts) {
@@ -447,12 +450,10 @@ function runPrune(store, options = {}) {
 
 // src/indexer.ts
 import { realpathSync } from "fs";
-import * as path9 from "path";
+import * as path8 from "path";
 import { parseFile } from "@titan-design/code-parser";
 
 // src/extractors/ts-morph-extractor.ts
-import * as path4 from "path";
-import { existsSync } from "fs";
 import {
   Project,
   ScriptTarget,
@@ -664,20 +665,24 @@ var TS_DECL_TYPES = /* @__PURE__ */ new Set([
 ]);
 var PY_DECL_TYPES = /* @__PURE__ */ new Set(["function_definition", "class_definition"]);
 function collectDeclarations(file) {
-  const python = file.language === "python";
-  const declTypes = python ? PY_DECL_TYPES : TS_DECL_TYPES;
   const out = [];
-  walkScopes(file.tree.rootNode, python, (node, scope) => {
-    const named = declaredNodeAt(node, declTypes);
-    if (!named) return;
+  forEachDeclaration(file, (name, qualifiedName, node) => {
     out.push({
-      name: named.name,
-      qualifiedName: qualify(scope, named.name),
-      span: { startLine: named.node.startPosition.row + 1, endLine: named.node.endPosition.row + 1 }
+      name,
+      qualifiedName,
+      span: { startLine: node.startPosition.row + 1, endLine: node.endPosition.row + 1 }
     });
   });
   return out;
 }
+function forEachDeclaration(file, visit) {
+  const python = file.language === "python";
+  const declTypes = python ? PY_DECL_TYPES : TS_DECL_TYPES;
+  walkScopes(file.tree.rootNode, python, (node, scope) => {
+    const named = declaredNodeAt(node, declTypes);
+    if (named) visit(named.name, qualify(scope, named.name), named.node);
+  });
+}
 function collectDeclaredSpans(file) {
   const spans = /* @__PURE__ */ new Map();
   for (const d of collectDeclarations(file)) spans.set(d.qualifiedName, d.span);
@@ -698,6 +703,80 @@ function declaredNodeAt(node, declTypes) {
   return null;
 }
 
+// src/extractors/call-sites.ts
+function addCallSite(agg, srcId, dstId, site) {
+  const key = JSON.stringify([srcId, dstId]);
+  const existing = agg.get(key);
+  if (existing) existing.attrs.sites.push(site);
+  else agg.set(key, { srcId, dstId, kind: "calls", attrs: { sites: [site] } });
+}
+function paramAttrs(shape) {
+  if (!shape) return {};
+  return shape.positional === shape.params.length ? { params: shape.params } : { params: shape.params, positionalParams: shape.positional };
+}
+function readParamShape(attrs) {
+  const params = attrs?.params;
+  if (!Array.isArray(params)) return void 0;
+  const positional = typeof attrs?.positionalParams === "number" ? attrs.positionalParams : params.length;
+  return { params, positional };
+}
+
+// src/extractors/callable-params.ts
+var TS_PARAM_TYPES = /* @__PURE__ */ new Set(["required_parameter", "optional_parameter"]);
+function collectParamShapes(file) {
+  const out = /* @__PURE__ */ new Map();
+  forEachDeclaration(file, (_name, qualifiedName, node) => {
+    const shape = file.language === "python" ? pythonShape(node) : tsShape(node);
+    if (shape) out.set(qualifiedName, shape);
+  });
+  return out;
+}
+function tsShape(fn) {
+  if (fn.type === "class_declaration") return null;
+  const single = fn.childForFieldName("parameter");
+  if (single) return { params: [single.text], positional: 1 };
+  const params = [];
+  for (const param of fn.childForFieldName("parameters")?.namedChildren ?? []) {
+    if (!param || !TS_PARAM_TYPES.has(param.type)) continue;
+    const pattern = param.childForFieldName("pattern");
+    if (!pattern || pattern.type === "this") continue;
+    if (pattern.type === "rest_pattern") break;
+    params.push(pattern.type === "identifier" ? pattern.text : `$${params.length}`);
+  }
+  return { params, positional: params.length };
+}
+function pythonShape(fn) {
+  if (fn.type !== "function_definition") return null;
+  const names = [];
+  let positionalEnd = null;
+  for (const param of fn.childForFieldName("parameters")?.namedChildren ?? []) {
+    if (!param) continue;
+    if (param.type === "keyword_separator" || param.type === "list_splat_pattern") positionalEnd ??= names.length;
+    const name = pythonParamName(param);
+    if (name) names.push(name);
+  }
+  const receiver = hasReceiver(fn) && names.length > 0 ? 1 : 0;
+  return { params: names.slice(receiver), positional: Math.max((positionalEnd ?? names.length) - receiver, 0) };
+}
+function pythonParamName(param) {
+  if (param.type === "identifier") return param.text;
+  if (param.type === "default_parameter" || param.type === "typed_default_parameter") {
+    return param.childForFieldName("name")?.text ?? null;
+  }
+  if (param.type === "typed_parameter") {
+    const first = param.namedChildren[0];
+    return first?.type === "identifier" ? first.text : null;
+  }
+  return null;
+}
+function hasReceiver(fn) {
+  const decorated = fn.parent?.type === "decorated_definition" ? fn.parent : null;
+  const block = (decorated ?? fn).parent;
+  if (block?.type !== "block" || block.parent?.type !== "class_definition") return false;
+  const decorators = decorated?.namedChildren.filter((c) => c?.type === "decorator") ?? [];
+  return !decorators.some((d) => d?.text === "@staticmethod");
+}
+
 // src/extractors/symbol-signature.ts
 import {
   Node as Node2
@@ -776,8 +855,8 @@ function clamp(s, max = MAX_SIGNATURE) {
 }
 
 // src/extractors/symbol-nodes.ts
-function makeSymbolNode(fileId2, name, exported, span, text) {
-  const attrs = { exported };
+function makeSymbolNode(fileId2, name, exported, span, text, shape) {
+  const attrs = { exported, ...paramAttrs(shape) };
   if (span) {
     attrs.startLine = span.startLine;
     attrs.endLine = span.endLine;
@@ -796,18 +875,19 @@ function makeSymbolNode(fileId2, name, exported, span, text) {
 function buildSymbolNodes(repoRoot, sourceFile, file) {
   const fId = fileId(repoRoot, sourceFile.getFilePath());
   const spans = collectDeclaredSpans(file);
+  const shapes = collectParamShapes(file);
   const out = [];
   const exported = /* @__PURE__ */ new Set();
   for (const [name, decls] of sourceFile.getExportedDeclarations()) {
     const own = decls.find((d) => d.getSourceFile() === sourceFile);
     if (!own) continue;
     exported.add(name);
-    out.push(makeSymbolNode(fId, name, true, spans.get(name), declarationText(own)));
+    out.push(makeSymbolNode(fId, name, true, spans.get(name), declarationText(own), shapes.get(name)));
   }
   for (const [name, span] of spans) {
     if (exported.has(name)) continue;
     const decl = lookupDeclaration(sourceFile, name);
-    out.push(makeSymbolNode(fId, name, false, span, decl ? declarationText(decl) : {}));
+    out.push(makeSymbolNode(fId, name, false, span, decl ? declarationText(decl) : {}, shapes.get(name)));
   }
   return out;
 }
@@ -879,6 +959,7 @@ function recordDynamicSymbolRefEdges(sourceFile, srcFileId, agg, resolveSpecifie
 
 // src/extractors/module-resolution.ts
 import * as path3 from "path";
+import { existsSync } from "fs";
 var RESOLVABLE_EXTS = [
   ".ts",
   ".tsx",
@@ -916,6 +997,17 @@ function inRepoFileId(repoRoot, abs) {
   if (relative4.split(path3.sep).includes("node_modules")) return null;
   return fileId(repoRoot, abs);
 }
+function remapDistToSrc(abs) {
+  const m = /^(.*)[\\/]dist[\\/](.+)\.d\.ts$/.exec(abs);
+  if (!m) return abs;
+  const base = m[1];
+  const sub = m[2];
+  for (const ext of [".ts", ".tsx"]) {
+    const candidate = path3.join(base, "src", sub + ext);
+    if (existsSync(candidate)) return candidate;
+  }
+  return abs;
+}
 
 // src/extractors/reexport-resolve.ts
 function resolveReExportOrigin(ctx, importerAbs, specifier, name) {
@@ -962,6 +1054,125 @@ function reExportInwardName(ed, name) {
   return name;
 }
 
+// src/extractors/ts-calls.ts
+import { Node as Node5, SyntaxKind as SyntaxKind3 } from "ts-morph";
+
+// src/extractors/ts-scope.ts
+import { Node as Node4 } from "ts-morph";
+function bindingName2(node) {
+  const parent = node.getParent();
+  if (Node4.isVariableDeclaration(parent) || Node4.isPropertyDeclaration(parent)) return parent.getName();
+  if (Node4.isPropertyAssignment(parent)) return parent.getNameNode().getText();
+  if (Node4.isExportAssignment(parent)) return "default";
+  return null;
+}
+function declaredName(node) {
+  const name = node.getName();
+  if (name) return name;
+  return Node4.isExportable(node) && node.isDefaultExport() ? "default" : null;
+}
+function scopeSegment2(node) {
+  if (Node4.isClassDeclaration(node) || Node4.isFunctionDeclaration(node)) return declaredName(node);
+  if (Node4.isMethodDeclaration(node) || Node4.isGetAccessorDeclaration(node) || Node4.isSetAccessorDeclaration(node)) {
+    return node.getName();
+  }
+  if (Node4.isConstructorDeclaration(node)) return "constructor";
+  if (Node4.isModuleDeclaration(node)) return node.hasNamespaceKeyword() ? node.getName() : null;
+  if (Node4.isClassExpression(node) && node.getName()) return node.getName() ?? null;
+  const bound = Node4.isArrowFunction(node) || Node4.isFunctionExpression(node) || Node4.isClassExpression(node) || Node4.isObjectLiteralExpression(node);
+  return bound ? bindingName2(node) ?? ANONYMOUS_SCOPE : null;
+}
+function scopeOf(node) {
+  const segments = node.getAncestors().map(scopeSegment2).filter((s) => s !== null).reverse();
+  let scope = "";
+  for (const segment of segments) {
+    const repeatsAnonymous = segment === ANONYMOUS_SCOPE && (scope === ANONYMOUS_SCOPE || scope.endsWith(`.${ANONYMOUS_SCOPE}`));
+    if (!repeatsAnonymous) scope = qualify(scope, segment);
+  }
+  return scope;
+}
+function declarationQualifiedName(decl) {
+  if (Node4.isVariableDeclaration(decl)) {
+    const init = decl.getInitializer();
+    const callable = Node4.isArrowFunction(init) || Node4.isFunctionExpression(init);
+    return callable ? qualify(scopeOf(decl), decl.getName()) : null;
+  }
+  if (Node4.isArrowFunction(decl) || Node4.isFunctionExpression(decl)) {
+    const parent = decl.getParent();
+    return Node4.isVariableDeclaration(parent) ? qualify(scopeOf(parent), parent.getName()) : null;
+  }
+  const isDeclaration = Node4.isFunctionDeclaration(decl) || Node4.isClassDeclaration(decl) || Node4.isMethodDeclaration(decl) || Node4.isGetAccessorDeclaration(decl) || Node4.isSetAccessorDeclaration(decl) || Node4.isConstructorDeclaration(decl);
+  const own = isDeclaration ? scopeSegment2(decl) : null;
+  return own ? qualify(scopeOf(decl), own) : null;
+}
+
+// src/extractors/ts-calls.ts
+function collectTsCallEdges(sourceFile, ctx) {
+  const agg = /* @__PURE__ */ new Map();
+  sourceFile.forEachDescendant((node) => {
+    if (!Node5.isCallExpression(node) && !Node5.isNewExpression(node)) return;
+    const dstId = resolveCallee(node, ctx);
+    if (dstId) addCallSite(agg, callerId(node, ctx), dstId, tsCallSite(node));
+  });
+  return [...agg.values()];
+}
+function resolveCallee(call, ctx) {
+  const callee = call.getExpression();
+  if (callee.getKind() === SyntaxKind3.SuperKeyword) return null;
+  const symbol = callee.getSymbol();
+  if (!symbol) return null;
+  const target = symbol.isAlias() ? symbol.getAliasedSymbol() : symbol;
+  const ids = /* @__PURE__ */ new Set();
+  for (const decl of target?.getDeclarations() ?? []) {
+    const id = declarationId(decl, ctx);
+    if (id === null) return null;
+    ids.add(id);
+  }
+  return ids.size === 1 ? [...ids][0] : null;
+}
+function declarationId(decl, ctx) {
+  const sf = decl.getSourceFile();
+  const abs = remapDistToSrc(sf.getFilePath());
+  if (sf.isDeclarationFile() && abs === sf.getFilePath()) return null;
+  const fileId2 = inRepoFileId(ctx.repoRoot, abs);
+  const name = fileId2 ? declarationQualifiedName(decl) : null;
+  return fileId2 && name ? symbolId(fileId2, name) : null;
+}
+function callerId(call, ctx) {
+  for (const ancestor of call.getAncestors()) {
+    const name = declarationQualifiedName(ancestor);
+    if (name && ctx.localSymbols.has(name)) return symbolId(ctx.srcFileId, name);
+  }
+  return ctx.srcFileId;
+}
+function tsCallSite(call) {
+  const site = { args: [] };
+  for (const arg of call.getArguments()) {
+    if (Node5.isSpreadElement(arg)) {
+      site.spreadFrom ??= site.args.length;
+      break;
+    }
+    site.args.push(literalText(arg));
+  }
+  return site;
+}
+var LITERAL_KINDS = /* @__PURE__ */ new Set([
+  SyntaxKind3.NumericLiteral,
+  SyntaxKind3.StringLiteral,
+  SyntaxKind3.NoSubstitutionTemplateLiteral,
+  SyntaxKind3.TrueKeyword,
+  SyntaxKind3.FalseKeyword,
+  SyntaxKind3.NullKeyword
+]);
+function literalText(arg) {
+  if (LITERAL_KINDS.has(arg.getKind())) return arg.getText();
+  if (Node5.isIdentifier(arg) && arg.getText() === "undefined") return "undefined";
+  if (Node5.isPrefixUnaryExpression(arg) && arg.getOperatorToken() === SyntaxKind3.MinusToken) {
+    return Node5.isNumericLiteral(arg.getOperand()) ? arg.getText() : null;
+  }
+  return null;
+}
+
 // src/extractors/ts-morph-extractor.ts
 var TsMorphGraphExtractor = class {
   name = "ts-morph-graph";
@@ -980,7 +1191,12 @@ var TsMorphGraphExtractor = class {
     const nodes = this.buildFileAndModuleNodes(sourceFile);
     const symbolNodes2 = buildSymbolNodes(this.repoRoot, sourceFile, file);
     const { edges, externalNodes } = this.collectEdges(sourceFile);
-    return [{ nodes: [...nodes, ...symbolNodes2, ...externalNodes], edges }];
+    const calls = collectTsCallEdges(sourceFile, {
+      repoRoot: this.repoRoot,
+      srcFileId: fileId(this.repoRoot, sourceFile.getFilePath()),
+      localSymbols: new Set(symbolNodes2.map((n) => n.name))
+    });
+    return [{ nodes: [...nodes, ...symbolNodes2, ...externalNodes], edges: [...edges, ...calls] }];
   }
   ensureProject() {
     if (this.project) return this.project;
@@ -1146,27 +1362,129 @@ var TsMorphGraphExtractor = class {
     return inRepoFileId(this.repoRoot, abs);
   }
 };
-function remapDistToSrc(abs) {
-  const m = /^(.*)[\\/]dist[\\/](.+)\.d\.ts$/.exec(abs);
-  if (!m) return abs;
-  const base = m[1];
-  const sub = m[2];
-  for (const ext of [".ts", ".tsx"]) {
-    const candidate = path4.join(base, "src", sub + ext);
-    if (existsSync(candidate)) return candidate;
-  }
-  return abs;
-}
 function isTypeScriptFile(file) {
   return file.language === "typescript" || file.language === "tsx";
 }
 
 // src/extractors/python-extractor.ts
-import * as path5 from "path";
+import * as path4 from "path";
 import { existsSync as existsSync2 } from "fs";
+
+// src/extractors/python-calls.ts
+function collectPythonCallEdges(file, fileId2, resolve4) {
+  const declarations = /* @__PURE__ */ new Map();
+  forEachDeclaration(file, (_name, qualifiedName, node) => declarations.set(qualifiedName, node));
+  const ctx = { fileId: fileId2, declarations, imports: fromImports(file.tree.rootNode, resolve4) };
+  const agg = /* @__PURE__ */ new Map();
+  walkScopes(file.tree.rootNode, true, (node, scope) => {
+    if (node.type !== "call") return;
+    const dst = resolveCallee2(node.childForFieldName("function"), scope, ctx);
+    const args = node.childForFieldName("arguments");
+    if (!dst || args?.type !== "argument_list") return;
+    const srcId = declarations.has(scope) ? symbolId(fileId2, scope) : fileId2;
+    addCallSite(agg, srcId, dst, pythonCallSite(args));
+  });
+  return [...agg.values()];
+}
+function resolveCallee2(callee, scope, ctx) {
+  if (callee?.type === "identifier") return resolveBareName(callee.text, scope, ctx);
+  if (callee?.type === "attribute") return resolveSelfMethod(callee, scope, ctx);
+  return null;
+}
+function resolveBareName(name, scope, ctx) {
+  if (isShadowed(name, scope, ctx)) return null;
+  const local = ctx.declarations.has(name);
+  const imported = ctx.imports.get(name);
+  if (local && imported) return null;
+  if (local) return symbolId(ctx.fileId, name);
+  return imported ? symbolId(imported.fileId, imported.name) : null;
+}
+function isShadowed(name, scope, ctx) {
+  const segments = scope ? scope.split(".") : [];
+  for (let depth = segments.length; depth > 0; depth--) {
+    const enclosing = segments.slice(0, depth).join(".");
+    if (ctx.declarations.has(`${enclosing}.${name}`)) return true;
+    if (parameterNames(ctx.declarations.get(enclosing)).includes(name)) return true;
+  }
+  return false;
+}
+function resolveSelfMethod(callee, scope, ctx) {
+  const receiver = callee.childForFieldName("object");
+  const attr = callee.childForFieldName("attribute")?.text;
+  const method = ctx.declarations.get(scope);
+  if (receiver?.type !== "identifier" || !attr || !method || !hasReceiver(method)) return null;
+  if (parameterNames(method)[0] !== receiver.text) return null;
+  const owner = findMethodOwner(scope.slice(0, scope.lastIndexOf(".")), attr, ctx, /* @__PURE__ */ new Set());
+  return owner ? symbolId(ctx.fileId, `${owner}.${attr}`) : null;
+}
+function findMethodOwner(className, attr, ctx, seen) {
+  const cls = ctx.declarations.get(className);
+  if (cls?.type !== "class_definition" || seen.has(className)) return null;
+  seen.add(className);
+  if (ctx.declarations.get(`${className}.${attr}`)?.type === "function_definition") return className;
+  for (const base of cls.childForFieldName("superclasses")?.namedChildren ?? []) {
+    if (base?.type !== "identifier" || !ctx.declarations.has(base.text)) return null;
+    const owner = findMethodOwner(base.text, attr, ctx, seen);
+    if (owner) return owner;
+  }
+  return null;
+}
+function parameterNames(def) {
+  if (def?.type !== "function_definition") return [];
+  const out = [];
+  for (const param of def.childForFieldName("parameters")?.namedChildren ?? []) {
+    const id = param?.type === "identifier" ? param : param?.descendantsOfType("identifier")[0];
+    if (id) out.push(id.text);
+  }
+  return out;
+}
+function fromImports(root, resolve4) {
+  const out = /* @__PURE__ */ new Map();
+  for (const stmt of root.descendantsOfType("import_from_statement")) {
+    const moduleName = stmt?.childForFieldName("module_name")?.text;
+    const moduleFile = moduleName ? resolve4(moduleName) : null;
+    if (!stmt || !moduleFile) continue;
+    for (const imported of stmt.childrenForFieldName("name")) {
+      const alias = imported?.type === "aliased_import" ? imported.childForFieldName("alias")?.text : void 0;
+      const name = imported?.type === "aliased_import" ? imported.childForFieldName("name")?.text : imported?.text;
+      if (name && !name.includes(".")) out.set(alias ?? name, { fileId: moduleFile, name });
+    }
+  }
+  return out;
+}
+var LITERAL_TYPES = /* @__PURE__ */ new Set(["integer", "float", "true", "false", "none"]);
+function literalText2(arg) {
+  if (LITERAL_TYPES.has(arg.type)) return arg.text;
+  if (arg.type === "string") return arg.namedChildren.some((c) => c?.type === "interpolation") ? null : arg.text;
+  if (arg.type === "unary_operator" && arg.text.startsWith("-")) {
+    const operand = arg.childForFieldName("argument");
+    return operand && (operand.type === "integer" || operand.type === "float") ? arg.text : null;
+  }
+  return null;
+}
+function pythonCallSite(argumentList) {
+  const site = { args: [] };
+  for (const arg of argumentList.namedChildren) {
+    if (!arg || arg.type === "comment") continue;
+    if (arg.type === "list_splat") site.spreadFrom ??= site.args.length;
+    else if (arg.type === "dictionary_splat") site.kwSplat = true;
+    else if (arg.type === "keyword_argument") addKeyword(site, arg);
+    else if (site.spreadFrom === void 0) site.args.push(literalText2(arg));
+  }
+  return site;
+}
+function addKeyword(site, arg) {
+  const name = arg.childForFieldName("name")?.text;
+  const value = arg.childForFieldName("value");
+  if (!name || !value) return;
+  site.kwargs ??= {};
+  site.kwargs[name] = literalText2(value);
+}
+
+// src/extractors/python-extractor.ts
 function* candidates(base) {
   yield `${base}.py`;
-  yield path5.join(base, "__init__.py");
+  yield path4.join(base, "__init__.py");
 }
 var PythonGraphExtractor = class {
   constructor(repoRoot) {
@@ -1180,7 +1498,8 @@ var PythonGraphExtractor = class {
     const nodes = buildFileModuleNodes(this.repoRoot, file.filePath);
     nodes.push(...symbolNodes(fId, file));
     const { edges, externals } = this.collectImports(fId, file);
-    return [{ nodes: [...nodes, ...externals], edges }];
+    const calls = collectPythonCallEdges(file, fId, (specifier) => this.resolveDotted(file.filePath, specifier));
+    return [{ nodes: [...nodes, ...externals], edges: [...edges, ...calls] }];
   }
   collectImports(srcId, file) {
     const edges = /* @__PURE__ */ new Map();
@@ -1203,10 +1522,10 @@ var PythonGraphExtractor = class {
   resolveDotted(fromAbs, specifier) {
     const leadingDots = /^\.*/.exec(specifier)?.[0].length ?? 0;
     const parts = specifier.slice(leadingDots).split(".").filter(Boolean);
-    const relativeBase = path5.resolve(path5.dirname(fromAbs), "../".repeat(Math.max(leadingDots - 1, 0)));
-    const roots = leadingDots > 0 ? [relativeBase] : [path5.dirname(fromAbs), this.repoRoot];
+    const relativeBase = path4.resolve(path4.dirname(fromAbs), "../".repeat(Math.max(leadingDots - 1, 0)));
+    const roots = leadingDots > 0 ? [relativeBase] : [path4.dirname(fromAbs), this.repoRoot];
     for (const root of roots) {
-      for (const candidate of candidates(path5.join(root, ...parts))) {
+      for (const candidate of candidates(path4.join(root, ...parts))) {
         const id = inRepoFileId(this.repoRoot, candidate);
         if (id !== null && existsSync2(candidate)) return id;
       }
@@ -1218,13 +1537,19 @@ function isPublicName(qualifiedName) {
   return !qualifiedName.slice(qualifiedName.lastIndexOf(".") + 1).startsWith("_");
 }
 function symbolNodes(fId, file) {
+  const shapes = collectParamShapes(file);
   return [...collectDeclaredSpans(file)].map(([name, span]) => ({
     id: symbolId(fId, name),
     kind: "symbol",
     name,
     parentId: fId,
     language: "python",
-    attrs: { exported: isPublicName(name), startLine: span.startLine, endLine: span.endLine }
+    attrs: {
+      exported: isPublicName(name),
+      startLine: span.startLine,
+      endLine: span.endLine,
+      ...paramAttrs(shapes.get(name))
+    }
   }));
 }
 function importSpecifiers(root) {
@@ -1257,7 +1582,7 @@ var LanguageExtractor = class {
 };
 
 // src/git-renames.ts
-import * as path6 from "path";
+import * as path5 from "path";
 function detectGitHead(repoRoot) {
   return runGit(repoRoot, ["rev-parse", "HEAD"]);
 }
@@ -1298,12 +1623,12 @@ function parseRenameOutput(text) {
   return out;
 }
 function classifyRename(oldPath, newPath) {
-  return path6.posix.dirname(oldPath) === path6.posix.dirname(newPath) ? "rename" : "move";
+  return path5.posix.dirname(oldPath) === path5.posix.dirname(newPath) ? "rename" : "move";
 }
 function renameToAliases(repoRoot, pair) {
   const reason = classifyRename(pair.oldPath, pair.newPath);
-  const oldAbs = path6.join(repoRoot, pair.oldPath);
-  const newAbs = path6.join(repoRoot, pair.newPath);
+  const oldAbs = path5.join(repoRoot, pair.oldPath);
+  const newAbs = path5.join(repoRoot, pair.newPath);
   return [
     { oldId: fileId(repoRoot, oldAbs), newId: fileId(repoRoot, newAbs), reason },
     { oldId: moduleId(repoRoot, oldAbs), newId: moduleId(repoRoot, newAbs), reason }
@@ -1396,8 +1721,8 @@ function walk(requestedId, maps) {
 }
 function chainSteps(input) {
   if (input.from === null) return { steps: rootPath(input.lineage, input.to, input.maxHops), connected: true };
-  const path12 = lineagePath(input.lineage, input.from, input.to, input.maxHops);
-  if (path12) return { steps: path12, connected: true };
+  const path11 = lineagePath(input.lineage, input.from, input.to, input.maxHops);
+  if (path11) return { steps: path11, connected: true };
   return { steps: [{ snapshotId: input.to, direction: "forward" }], connected: false };
 }
 function createAliasChain(input) {
@@ -1478,7 +1803,7 @@ function computeAliasBridge(store, input) {
 
 // src/generated.ts
 import { readFileSync } from "fs";
-import * as path7 from "path";
+import * as path6 from "path";
 var HEURISTIC_FILE_RE = /(?:^|\/)[^/]*\.(?:gen|generated)\.[^/]*$/;
 var HEURISTIC_DIR_RE = /(?:^|\/)generated\//;
 function isGeneratedByHeuristic(id) {
@@ -1490,7 +1815,7 @@ function isGeneratedFile(id, patterns) {
 }
 function loadGeneratedPatterns(rootDir) {
   try {
-    const content = readFileSync(path7.join(rootDir, ".gitattributes"), "utf-8");
+    const content = readFileSync(path6.join(rootDir, ".gitattributes"), "utf-8");
     return parseGeneratedPatterns(content);
   } catch {
     return [];
@@ -1593,7 +1918,7 @@ function annotateRoles(nodes, options) {
 
 // src/file-walk.ts
 import * as fs from "fs/promises";
-import * as path8 from "path";
+import * as path7 from "path";
 import { isExcludedDir, shouldIncludeFile } from "@titan-design/code-parser";
 async function walkSourceFiles(rootDirs, languages) {
   const seen = /* @__PURE__ */ new Set();
@@ -1606,12 +1931,12 @@ async function walkSourceFiles(rootDirs, languages) {
 async function collectFiles(dir, rootDir, languages, seen, out) {
   const entries = await fs.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const full = path8.join(dir, entry.name);
+    const full = path7.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (isExcludedDir(entry.name)) continue;
       await collectFiles(full, rootDir, languages, seen, out);
     } else if (entry.isFile() && !seen.has(full)) {
-      const relative4 = path8.relative(rootDir, full);
+      const relative4 = path7.relative(rootDir, full);
       if (shouldIncludeFile(relative4, [...languages])) {
         seen.add(full);
         out.push(full);
@@ -1627,7 +1952,8 @@ function edgeWeight(e) {
 }
 function pruneDanglingReferences(nodes, edges) {
   for (const [key, edge] of edges) {
-    if (edge.kind === "references" && !nodes.has(edge.dstId)) edges.delete(key);
+    const symbolLayer = edge.kind === "references" || edge.kind === "calls";
+    if (symbolLayer && (!nodes.has(edge.dstId) || !nodes.has(edge.srcId))) edges.delete(key);
   }
 }
 function resolveBarrelEdges(nodes, edges) {
@@ -1867,6 +2193,8 @@ var HANDLER_TYPES = ["except_clause", "except_group_clause", "catch_clause"];
 var SILENT_STATEMENTS = /* @__PURE__ */ new Set(["pass_statement", "continue_statement", "empty_statement"]);
 var EMPTY_VALUES = /* @__PURE__ */ new Set(["None", "null", "undefined"]);
 var LOGGING_TOKENS = /* @__PURE__ */ new Set(["log", "logger", "logging", "warn", "warning", "warnings", "print", "console"]);
+var EXCEPT_CLAUSE_TYPES = /* @__PURE__ */ new Set(["except_clause", "except_group_clause"]);
+var OPTIONAL_IMPORT_EXCEPT_TYPES = /* @__PURE__ */ new Set(["ImportError", "ModuleNotFoundError"]);
 function exceptionMetrics(nodeId, root, loc) {
   const handlers = HANDLER_TYPES.flatMap((type) => descendantsOfType(root, type));
   const swallowed = handlers.filter((h) => isSwallowed(h)).length;
@@ -1877,12 +2205,24 @@ function exceptionMetrics(nodeId, root, loc) {
   ];
 }
 function isSwallowed(handler) {
+  if (isOptionalImportExcept(handler)) return false;
   const body = handler.childForFieldName("body") ?? handler.namedChildren.find((c) => c?.type === "block");
   if (!body) return false;
   const statements = bodyStatements(body, null);
   if (statements.length === 0) return true;
   return statements.length === 1 && isSilent(statements[0]);
 }
+function isOptionalImportExcept(handler) {
+  if (!EXCEPT_CLAUSE_TYPES.has(handler.type)) return false;
+  const value = handler.childForFieldName("value");
+  if (!value) return false;
+  const typeExpr = value.type === "as_pattern" ? value.namedChild(0) : value;
+  if (!typeExpr) return false;
+  if (typeExpr.type === "identifier") return OPTIONAL_IMPORT_EXCEPT_TYPES.has(typeExpr.text);
+  if (typeExpr.type !== "tuple") return false;
+  const names = typeExpr.namedChildren.filter((c) => c !== null);
+  return names.length > 0 && names.every((n) => n.type === "identifier" && OPTIONAL_IMPORT_EXCEPT_TYPES.has(n.text));
+}
 function isSilent(statement) {
   if (SILENT_STATEMENTS.has(statement.type)) return true;
   const value = statement.namedChildren[0];
@@ -2990,9 +3330,10 @@ function loadReuseBasis(db, indexVersion) {
     }
     const edgesBySrc = /* @__PURE__ */ new Map();
     for (const e of db.listEdges(snap.id, { includeReferences: true })) {
-      const bucket = edgesBySrc.get(e.srcId);
+      const fileKey = parseSymbolId(e.srcId)?.fileId ?? e.srcId;
+      const bucket = edgesBySrc.get(fileKey);
       if (bucket) bucket.push(e);
-      else edgesBySrc.set(e.srcId, [e]);
+      else edgesBySrc.set(fileKey, [e]);
     }
     const sourceMetricsByFile = /* @__PURE__ */ new Map();
     for (const m of db.listMetrics(snap.id)) {
@@ -3111,6 +3452,7 @@ function weightedInbound(nodes, edges) {
   const util = /* @__PURE__ */ new Map();
   for (const n of nodes) util.set(n.id, 0);
   for (const e of resolveBarrelEdges(nodes, edges)) {
+    if (e.kind === "calls") continue;
     if (util.has(e.dstId)) util.set(e.dstId, util.get(e.dstId) + edgeWeight(e));
   }
   return util;
@@ -3141,6 +3483,58 @@ function computeMetrics(nodes, edges) {
   return out;
 }
 
+// src/analysis/call-metrics.ts
+var ABSENT = "<absent>";
+function computeCallMetrics(nodes, edges) {
+  const inbound = collectInbound(edges);
+  const out = [];
+  for (const node of nodes) {
+    if (node.kind !== "symbol" || node.attrs?.startLine === void 0) continue;
+    const { callers, sites } = inbound.get(node.id) ?? { callers: /* @__PURE__ */ new Set(), sites: [] };
+    out.push({ nodeId: node.id, name: "symbol_caller_count", value: callers.size, unit: "count" });
+    const single = isPrivateHelper(node) && callers.size === 1 && isSymbolCaller(callers);
+    out.push({ nodeId: node.id, name: "symbol_single_caller_helper", value: single ? 1 : 0, unit: "count" });
+    const shape = readParamShape(node.attrs);
+    if (shape && sites.length >= 2) {
+      out.push({ nodeId: node.id, name: "symbol_constant_params", value: constantParams(shape, sites), unit: "count" });
+    }
+  }
+  return out;
+}
+function collectInbound(edges) {
+  const inbound = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (edge.kind !== "calls") continue;
+    let entry = inbound.get(edge.dstId);
+    if (!entry) inbound.set(edge.dstId, entry = { callers: /* @__PURE__ */ new Set(), sites: [] });
+    if (edge.srcId !== edge.dstId) entry.callers.add(edge.srcId);
+    entry.sites.push(...edge.attrs?.sites ?? []);
+  }
+  return inbound;
+}
+function isPrivateHelper(node) {
+  const own = node.name.slice(node.name.lastIndexOf(".") + 1);
+  return node.attrs?.exported === false && !(own.startsWith("__") && own.endsWith("__"));
+}
+function isSymbolCaller(callers) {
+  return [...callers].every((id) => parseSymbolId(id) !== null);
+}
+function constantParams(shape, sites) {
+  let count = 0;
+  shape.params.forEach((name, index) => {
+    const values = sites.map((site) => argumentAt(site, name, index < shape.positional ? index : -1));
+    if (values.every((v) => v !== null && v === values[0])) count++;
+  });
+  return count;
+}
+function argumentAt(site, name, position) {
+  if (position >= 0 && position < site.args.length) return site.args[position] ?? null;
+  if (site.kwargs && Object.hasOwn(site.kwargs, name)) return site.kwargs[name] ?? null;
+  if (site.kwSplat) return null;
+  if (position >= 0 && site.spreadFrom !== void 0 && position >= site.spreadFrom) return null;
+  return ABSENT;
+}
+
 // src/analysis/test-linker.ts
 var DEFAULT_MIN_CO_EDIT_COUNT = 2;
 var TEST_INFIX_RE = /\.(?:test|spec)(\.[^./]+)$/;
@@ -3350,6 +3744,7 @@ function buildIndexerMetrics(input) {
   const history = input.history ? loadHistoryMetrics(nodeList, input.idRoot, input.history) : null;
   return [
     ...computeMetrics(nodeList, [...input.edges.values()]),
+    ...computeCallMetrics(nodeList, input.edges.values()),
     ...computeSourceMetrics(
       input.parsedFiles,
       (p) => fileId(input.idRoot, p),
@@ -3428,7 +3823,7 @@ function qualifiedByName(file) {
 }
 
 // src/indexer.ts
-var INDEX_VERSION = "0.17.0";
+var INDEX_VERSION = "0.18.0";
 var LANGUAGES = ["typescript", "python"];
 function canonicalizePath(p) {
   try {
@@ -3439,7 +3834,7 @@ function canonicalizePath(p) {
 }
 function normalizePaths(paths) {
   if (paths.length === 0) throw new Error("indexPaths requires at least one path");
-  return [...new Set(paths.map((p) => path9.resolve(p)))];
+  return [...new Set(paths.map((p) => path8.resolve(p)))];
 }
 function countByKind(items) {
   const out = {};
@@ -3543,9 +3938,9 @@ import { getLanguageFromPath as getLanguageFromPath3, getSupportedLanguages, par
 
 // src/extractors/deep-ast.ts
 import { readFileSync as readFileSync2 } from "fs";
-import * as path10 from "path";
+import * as path9 from "path";
 import {
-  Node as Node4,
+  Node as Node6,
   Project as Project2,
   ScriptTarget as ScriptTarget2
 } from "ts-morph";
@@ -3562,7 +3957,7 @@ function loadSourceFile(absPath) {
       useInMemoryFileSystem: true,
       compilerOptions: { target: ScriptTarget2.Latest, allowJs: true }
     });
-    return project.createSourceFile(`f${path10.extname(absPath) || ".ts"}`, text);
+    return project.createSourceFile(`f${path9.extname(absPath) || ".ts"}`, text);
   } catch {
     return null;
   }
@@ -3604,10 +3999,10 @@ function empty(target, kind) {
   };
 }
 function callableOf(decl) {
-  if (Node4.isFunctionDeclaration(decl) || Node4.isMethodDeclaration(decl)) return decl;
-  if (Node4.isVariableDeclaration(decl)) {
+  if (Node6.isFunctionDeclaration(decl) || Node6.isMethodDeclaration(decl)) return decl;
+  if (Node6.isVariableDeclaration(decl)) {
     const init = decl.getInitializer();
-    if (init && (Node4.isArrowFunction(init) || Node4.isFunctionExpression(init))) return init;
+    if (init && (Node6.isArrowFunction(init) || Node6.isFunctionExpression(init))) return init;
   }
   return null;
 }
@@ -3623,8 +4018,8 @@ function returnTypeOf(decl) {
   return callableOf(decl)?.getReturnTypeNode()?.getText() ?? null;
 }
 function membersOf(decl) {
-  if (Node4.isClassDeclaration(decl)) return classMembers(decl);
-  if (Node4.isInterfaceDeclaration(decl)) return interfaceMembers(decl);
+  if (Node6.isClassDeclaration(decl)) return classMembers(decl);
+  if (Node6.isInterfaceDeclaration(decl)) return interfaceMembers(decl);
   return [];
 }
 function classMembers(cls) {
@@ -3632,7 +4027,7 @@ function classMembers(cls) {
     name: memberName(m),
     memberKind: m.getKindName(),
     signature: memberSignature(m),
-    isStatic: Node4.isStaticable(m) ? m.isStatic() : false
+    isStatic: Node6.isStaticable(m) ? m.isStatic() : false
   }));
 }
 function interfaceMembers(iface) {
@@ -3658,17 +4053,17 @@ function exportedDeclarations(sf) {
   return out;
 }
 function memberName(m) {
-  if (Node4.isConstructorDeclaration(m)) return "constructor";
-  return Node4.hasName(m) ? m.getName() : "";
+  if (Node6.isConstructorDeclaration(m)) return "constructor";
+  return Node6.hasName(m) ? m.getName() : "";
 }
 function memberSignature(m) {
-  if (Node4.isMethodDeclaration(m) || Node4.isMethodSignature(m) || Node4.isConstructorDeclaration(m)) {
+  if (Node6.isMethodDeclaration(m) || Node6.isMethodSignature(m) || Node6.isConstructorDeclaration(m)) {
     const params = m.getParameters().map((p) => oneLine2(p.getText())).join(", ");
     const ret = m.getReturnTypeNode()?.getText();
-    const name = Node4.isConstructorDeclaration(m) ? "constructor" : memberName(m);
+    const name = Node6.isConstructorDeclaration(m) ? "constructor" : memberName(m);
     return oneLine2(`${name}(${params})${ret ? `: ${ret}` : ""}`);
   }
-  if (Node4.isPropertyDeclaration(m) || Node4.isPropertySignature(m)) {
+  if (Node6.isPropertyDeclaration(m) || Node6.isPropertySignature(m)) {
     const type = m.getTypeNode()?.getText();
     return oneLine2(`${memberName(m)}${type ? `: ${type}` : ""}`);
   }
@@ -4476,6 +4871,36 @@ var SOURCE = [
     source: "source-metrics",
     description: "1 when the function's body is one call forwarding every parameter, in order, as a bare argument; else 0."
   },
+  {
+    name: "symbol_caller_count",
+    unit: "count",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "neutral",
+    absent: "exclude",
+    source: "call-graph",
+    description: "Distinct symbols, or files at module level, with a resolved call to this function, method or class. Unresolved calls are not counted."
+  },
+  {
+    name: "symbol_single_caller_helper",
+    unit: "count",
+    appliesTo: SYMBOL,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "call-graph",
+    description: "1 when a non-exported symbol has exactly one resolved caller and that caller is a symbol; else 0."
+  },
+  {
+    name: "symbol_constant_params",
+    unit: "count",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "call-graph",
+    description: "Parameters that every one of at least 2 resolved call sites passes the same literal, or never passes. Rest and keyword-splat parameters are ignored."
+  },
   {
     name: "except_count",
     unit: "count",
@@ -4504,7 +4929,7 @@ var SOURCE = [
     direction: "higher-worse",
     absent: "zero",
     source: "exception-handling",
-    description: "Handlers whose body is empty, pass, ..., continue, a bare or empty return, or a single logging call."
+    description: "Handlers whose body is empty, pass, ..., continue, a bare or empty return, or a single logging call. Exempts Python's `except ImportError`/`ModuleNotFoundError` (alone or paired), the standard optional-dependency idiom."
   },
   {
     name: "class_count",
@@ -4939,9 +5364,10 @@ function runMetricOutlierRule(rule, ctx) {
     const value = ctx.metricsByNode.get(node.id)?.get(rule.metric);
     if (value !== void 0) carriers.push({ node, value });
   }
-  if (carriers.length < (rule.minSample ?? DEFAULT_OUTLIER_MIN_SAMPLE)) return [];
-  const threshold = percentileOf(carriers.map((c) => c.value), rule.percentile);
-  return carriers.filter((c) => c.value > threshold).map((c) => toViolation(rule, c.node, c.value, threshold));
+  const ranked = rule.rankNonZero ? carriers.filter((c) => c.value > 0) : carriers;
+  if (ranked.length < (rule.minSample ?? DEFAULT_OUTLIER_MIN_SAMPLE)) return [];
+  const threshold = percentileOf(ranked.map((c) => c.value), rule.percentile);
+  return ranked.filter((c) => c.value > threshold && (rule.floor === void 0 || c.value > rule.floor)).map((c) => toViolation(rule, c.node, c.value, threshold));
 }
 function percentileOf(values, percentile) {
   const sorted = [...values].sort((a, b) => a - b);
@@ -4951,7 +5377,8 @@ function percentileOf(values, percentile) {
   return sorted[lower] + (sorted[upper] - sorted[lower]) * (rank - lower);
 }
 function toViolation(rule, node, value, threshold) {
-  const bound = `p${formatNumber(rule.percentile)} ${formatNumber(threshold)}`;
+  const floorSuffix = rule.floor === void 0 ? "" : `, floor ${formatNumber(rule.floor)}`;
+  const bound = `p${formatNumber(rule.percentile)} ${formatNumber(threshold)}${floorSuffix}`;
   return {
     ruleId: rule.id,
     severity: severityOf(rule),
@@ -5340,6 +5767,12 @@ function assertMetricOutlier(r, warn) {
   if (r.minSample !== void 0 && (!Number.isInteger(r.minSample) || r.minSample < 1)) {
     throw new Error(`${r.id}: minSample must be a positive integer`);
   }
+  if (r.floor !== void 0 && (typeof r.floor !== "number" || !Number.isFinite(r.floor) || r.floor < 0)) {
+    throw new Error(`${r.id}: floor must be a non-negative finite number`);
+  }
+  if (r.rankNonZero !== void 0 && typeof r.rankNonZero !== "boolean") {
+    throw new Error(`${r.id}: rankNonZero must be a boolean`);
+  }
   const ruleId = r.id;
   return {
     type: "metric-outlier",
@@ -5348,6 +5781,8 @@ function assertMetricOutlier(r, warn) {
     kind: r.kind,
     percentile: r.percentile,
     minSample: r.minSample,
+    floor: r.floor,
+    rankNonZero: r.rankNonZero,
     severity: r.severity
   };
 }
@@ -5419,18 +5854,18 @@ function checkSnapshot(store, options) {
   });
   return { snapshot, baselineSnapshot, result };
 }
-async function loadCheckRules(path12, options = {}) {
+async function loadCheckRules(path11, options = {}) {
   let raw;
   try {
-    raw = await readFile2(path12, "utf8");
+    raw = await readFile2(path11, "utf8");
   } catch (err) {
-    throw new Error(`Cannot read rules file at ${path12}: ${errorMessage(err)}`);
+    throw new Error(`Cannot read rules file at ${path11}: ${errorMessage(err)}`);
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    throw new Error(`Invalid JSON in ${path12}: ${errorMessage(err)}`);
+    throw new Error(`Invalid JSON in ${path11}: ${errorMessage(err)}`);
   }
   return validateRules(parsed, options);
 }
@@ -5842,7 +6277,7 @@ function pushMulti(map, key, value) {
 }
 
 // src/conventions/areas.ts
-import * as path11 from "path";
+import * as path10 from "path";
 import { contentHashOf as contentHashOf2 } from "@titan-design/store-sqlite";
 var DEFAULT_MIN_SIZE = 3;
 var PROMPT_FILE_CAP = 30;
@@ -5926,7 +6361,7 @@ function rankByDegree(members, edges) {
 function dominantDirectory(files) {
   const counts = /* @__PURE__ */ new Map();
   for (const f of files) {
-    const dir = path11.posix.dirname(f);
+    const dir = path10.posix.dirname(f);
     counts.set(dir, (counts.get(dir) ?? 0) + 1);
   }
   const dirs = [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));