@titan-design/code-graph 0.6.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) {
@@ -1685,6 +2011,234 @@ import { createHash } from "crypto";
 import * as fs2 from "fs/promises";
 import { getLanguageFromPath as getLanguageFromPath2 } from "@titan-design/code-parser";
 
+// src/analysis/comment-lines.ts
+function commentLineStats(fn, body, lines) {
+  const docstring = pythonDocstring(body);
+  const comments = functionComments(fn, body);
+  const commentLines = rowsOf(comments).size;
+  const bodyLines = codeRows(body, docstring, comments, lines);
+  return {
+    commentLines,
+    docstringLines: docstring ? rowSpan(docstring) : jsDocLines(fn),
+    bodyLines,
+    commentRatio: commentLines / Math.max(bodyLines, 1)
+  };
+}
+function pythonDocstring(body) {
+  if (body.type !== "block") return null;
+  const first = body.namedChildren.find((c) => c !== null && c.type !== "comment");
+  if (first?.type !== "expression_statement" || first.namedChildCount !== 1) return null;
+  return first.namedChildren[0]?.type === "string" ? first : null;
+}
+function bodyStatements(body, docstring = pythonDocstring(body)) {
+  if (body.type !== "block" && body.type !== "statement_block") return [body];
+  return body.namedChildren.filter(
+    (c) => c !== null && c.type !== "comment" && c.id !== docstring?.id
+  );
+}
+function functionComments(fn, body) {
+  if (body.type !== "block") return descendantsOfType(body, "comment");
+  const signatureEnd = fn.childForFieldName("parameters")?.endIndex ?? body.startIndex;
+  return descendantsOfType(fn, "comment").filter((c) => c.startIndex >= signatureEnd);
+}
+function descendantsOfType(root, type) {
+  const out = [];
+  const visit = (node) => {
+    if (node.type === type) out.push(node);
+    for (const child of node.namedChildren) if (child) visit(child);
+  };
+  visit(root);
+  return out;
+}
+function rowSpan(node) {
+  return node.endPosition.row - node.startPosition.row + 1;
+}
+function rowsOf(nodes) {
+  const rows = /* @__PURE__ */ new Set();
+  for (const n of nodes) {
+    for (let r = n.startPosition.row; r <= n.endPosition.row; r++) rows.add(r);
+  }
+  return rows;
+}
+function codeRows(body, docstring, comments, lines) {
+  let count = 0;
+  for (const row of rowsOf(bodyStatements(body, docstring))) {
+    if (codeOnRow(row, lines[row] ?? "", comments).trim() !== "") count++;
+  }
+  return count;
+}
+function codeOnRow(row, text, comments) {
+  let out = text;
+  for (const c of comments) {
+    if (row < c.startPosition.row || row > c.endPosition.row) continue;
+    const from = row === c.startPosition.row ? c.startPosition.column : 0;
+    const to = row === c.endPosition.row ? c.endPosition.column : out.length;
+    out = out.slice(0, from) + " ".repeat(Math.max(to - from, 0)) + out.slice(to);
+  }
+  return out;
+}
+function jsDocLines(fn) {
+  const anchor = declarationAnchor(fn);
+  const prev = anchor.previousNamedSibling;
+  if (prev?.type !== "comment" || !prev.text.startsWith("/**")) return 0;
+  const gap = anchor.startPosition.row - prev.endPosition.row;
+  return gap === 0 || gap === 1 ? rowSpan(prev) : 0;
+}
+function declarationAnchor(fn) {
+  let anchor = fn;
+  if (fn.parent?.type === "variable_declarator") anchor = fn.parent.parent ?? fn;
+  while (anchor.parent?.type === "export_statement") anchor = anchor.parent;
+  return anchor;
+}
+
+// src/analysis/narrating-comments.ts
+var MIN_SHARED = 2;
+var MIN_SHARE_OF_COMMENT = 0.5;
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "this",
+  "that",
+  "with",
+  "from",
+  "into",
+  "then",
+  "else",
+  "when",
+  "not",
+  "are",
+  "was",
+  "has",
+  "have",
+  "its",
+  "our",
+  "all",
+  "any",
+  "can",
+  "will",
+  "just",
+  "now",
+  "return",
+  "const",
+  "let",
+  "var",
+  "def",
+  "self",
+  "none",
+  "true",
+  "false",
+  "null",
+  "undefined",
+  "new",
+  "await",
+  "async",
+  "function"
+]);
+var IDENTIFIER_TYPES = /* @__PURE__ */ new Set([
+  "identifier",
+  "property_identifier",
+  "shorthand_property_identifier",
+  "type_identifier"
+]);
+function countNarratingComments(fn, body) {
+  let count = 0;
+  for (const comment of functionComments(fn, body)) {
+    const target = trailedStatement(comment) ?? nextStatement(comment);
+    if (target && narrates(comment.text, target)) count++;
+  }
+  return count;
+}
+function trailedStatement(comment) {
+  const prev = comment.previousNamedSibling;
+  if (!prev || prev.type === "comment") return null;
+  return prev.endPosition.row === comment.startPosition.row ? prev : null;
+}
+function identifierTokens(text) {
+  const words = text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/);
+  const out = /* @__PURE__ */ new Set();
+  for (const w of words) {
+    const t = w.toLowerCase();
+    if (t.length >= 3 && !STOPWORDS.has(t)) out.add(t);
+  }
+  return out;
+}
+function nextStatement(comment) {
+  let next = comment.nextNamedSibling;
+  while (next?.type === "comment") next = next.nextNamedSibling;
+  if (next?.type !== "block") return next;
+  return next.namedChildren.find((c) => c !== null && c.type !== "comment") ?? null;
+}
+function narrates(commentText, statement) {
+  const said = identifierTokens(commentText);
+  if (said.size === 0) return false;
+  const code = identifierTokens(statementIdentifiers(statement).join(" "));
+  let shared = 0;
+  for (const t of said) if (code.has(t)) shared++;
+  return shared >= MIN_SHARED || shared / said.size >= MIN_SHARE_OF_COMMENT;
+}
+function statementIdentifiers(statement) {
+  const out = [];
+  const visit = (node) => {
+    if (IDENTIFIER_TYPES.has(node.type)) out.push(node.text);
+    for (const child of node.namedChildren) if (child) visit(child);
+  };
+  visit(statement);
+  return out;
+}
+
+// src/analysis/exception-handling.ts
+var EXCEPTION_METRIC_NAMES = ["except_count", "except_density", "swallowed_except"];
+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;
+  return [
+    { nodeId, name: "except_count", value: handlers.length, unit: "count" },
+    { nodeId, name: "except_density", value: loc === 0 ? 0 : handlers.length * 100 / loc, unit: "per100loc" },
+    { nodeId, name: "swallowed_except", value: swallowed, unit: "count" }
+  ];
+}
+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];
+  if (statement.type === "return_statement") return !value || EMPTY_VALUES.has(value.text);
+  if (statement.type !== "expression_statement" || !value) return false;
+  if (value.type === "ellipsis") return true;
+  return isLoggingCall(value);
+}
+function isLoggingCall(node) {
+  if (node.type !== "call" && node.type !== "call_expression") return false;
+  const callee = node.childForFieldName("function");
+  if (!callee) return false;
+  for (const token of identifierTokens(callee.text)) if (LOGGING_TOKENS.has(token)) return true;
+  return false;
+}
+
 // src/cognitive-complexity.ts
 function cognitiveComplexityOf(body, language) {
   const handler = language === "python" ? PY_HANDLER : TS_HANDLER;
@@ -1937,12 +2491,97 @@ function areLinked(a, b) {
   return false;
 }
 
+// src/analysis/pass-through.ts
+var RECEIVERS = /* @__PURE__ */ new Set(["self", "cls"]);
+var CALL_TYPES = /* @__PURE__ */ new Set(["call", "call_expression"]);
+var WRAPPER_TYPES = /* @__PURE__ */ new Set(["return_statement", "expression_statement"]);
+var PY_NAMED_PARAMS = /* @__PURE__ */ new Set(["default_parameter", "typed_default_parameter"]);
+var PY_SEPARATORS = /* @__PURE__ */ new Set(["keyword_separator", "positional_separator"]);
+function isPassThrough(fn, body) {
+  const call = soleCall(body);
+  if (!call) return false;
+  const params = parameterShapes(fn);
+  if (!params || params.length === 0) return false;
+  const args = argumentShapes(call);
+  return args !== null && args.length === params.length && args.every((a, i) => a === params[i]);
+}
+function soleCall(body) {
+  const statements = bodyStatements(body);
+  if (statements.length !== 1) return null;
+  const only = statements[0];
+  if (CALL_TYPES.has(only.type)) return only;
+  if (!WRAPPER_TYPES.has(only.type) || only.namedChildCount !== 1) return null;
+  const value = only.namedChildren[0];
+  return CALL_TYPES.has(value.type) ? value : null;
+}
+function parameterShapes(fn) {
+  const bare = fn.childForFieldName("parameter");
+  if (bare) return [bare.text];
+  const list = fn.childForFieldName("parameters");
+  if (!list) return null;
+  const shapes = [];
+  for (const p of list.namedChildren) {
+    if (!p || p.type === "comment" || PY_SEPARATORS.has(p.type)) continue;
+    const shape = parameterShape(p);
+    if (shape === null) return null;
+    shapes.push(shape);
+  }
+  return RECEIVERS.has(shapes[0] ?? "") ? shapes.slice(1) : shapes;
+}
+function parameterShape(p) {
+  if (p.type === "identifier") return p.text;
+  if (p.type === "list_splat_pattern" || p.type === "dictionary_splat_pattern") return p.text;
+  if (PY_NAMED_PARAMS.has(p.type)) return p.childForFieldName("name")?.text ?? null;
+  if (p.type === "typed_parameter") return parameterShape(p.namedChildren[0]);
+  if (p.type === "required_parameter" || p.type === "optional_parameter") {
+    const pattern = p.childForFieldName("pattern");
+    return pattern ? tsPatternShape(pattern) : null;
+  }
+  return tsPatternShape(p);
+}
+function tsPatternShape(pattern) {
+  if (pattern.type === "identifier") return pattern.text;
+  if (pattern.type === "rest_pattern") return `...${pattern.namedChildren[0]?.text ?? ""}`;
+  if (pattern.type === "assignment_pattern") {
+    const left = pattern.childForFieldName("left");
+    return left ? tsPatternShape(left) : null;
+  }
+  return null;
+}
+function argumentShapes(call) {
+  const list = call.childForFieldName("arguments");
+  if (!list || list.type !== "argument_list" && list.type !== "arguments") return null;
+  const shapes = [];
+  for (const a of list.namedChildren) {
+    if (!a || a.type === "comment") continue;
+    const shape = argumentShape(a);
+    if (shape === null) return null;
+    shapes.push(shape);
+  }
+  return shapes;
+}
+function argumentShape(a) {
+  if (a.type === "identifier") return a.text;
+  const inner = a.namedChildren[0];
+  if (inner?.type !== "identifier") return null;
+  if (a.type === "list_splat") return `*${inner.text}`;
+  if (a.type === "dictionary_splat") return `**${inner.text}`;
+  if (a.type === "spread_element") return `...${inner.text}`;
+  return null;
+}
+
 // src/symbol-metrics.ts
 var SYMBOL_METRICS = [
   { name: "symbol_cognitive", stat: "cognitive", unit: "count" },
   { name: "symbol_cyclomatic", stat: "cyclomatic", unit: "count" },
   { name: "symbol_loc", stat: "loc", unit: "lines" },
-  { name: "symbol_max_nesting", stat: "nestingDepth", unit: "count" }
+  { name: "symbol_max_nesting", stat: "nestingDepth", unit: "count" },
+  { name: "symbol_comment_lines", stat: "commentLines", unit: "lines" },
+  { name: "symbol_docstring_lines", stat: "docstringLines", unit: "lines" },
+  { name: "symbol_body_lines", stat: "bodyLines", unit: "lines" },
+  { name: "symbol_comment_ratio", stat: "commentRatio", unit: "ratio" },
+  { name: "symbol_narrating_comments", stat: "narratingComments", unit: "count" },
+  { name: "symbol_pass_through", stat: "passThrough", unit: "count" }
 ];
 var SYMBOL_METRIC_NAMES = SYMBOL_METRICS.map((m) => m.name);
 function symbolMetrics(fileId2, stats, symbolNames) {
@@ -1966,6 +2605,13 @@ function symbolMetrics(fileId2, stats, symbolNames) {
   }
   return out;
 }
+function functionShapeStats(fn, body, lines) {
+  return {
+    ...commentLineStats(fn, body, lines),
+    narratingComments: countNarratingComments(fn, body),
+    passThrough: isPassThrough(fn, body) ? 1 : 0
+  };
+}
 
 // src/source-metrics.ts
 var TS_FUNCTION_TYPES = /* @__PURE__ */ new Set([
@@ -2016,7 +2662,8 @@ var SOURCE_METRIC_NAMES = /* @__PURE__ */ new Set([
   "max_nesting_depth",
   "class_count",
   "lcom4_max",
-  // Per-symbol complexity, loc and nesting (C-58, C-64, TP-317), keyed
+  ...EXCEPTION_METRIC_NAMES,
+  // Per-symbol complexity, size, comments and shape (C-58, C-64, TP-317, TP-322), keyed
   // to `symbol` node ids. Source-local like the file-level metrics above, so an
   // unchanged file carries them forward — but their nodeId is `<fileId>#<name>`,
   // so the reuse basis buckets them under the symbol's parent file (incremental.ts).
@@ -2076,6 +2723,7 @@ function metricsForFile(nodeId, file, symbolNames) {
   }
   out.push(...symbolMetrics(nodeId, stats, symbolNames));
   out.push(...computeLcomMetrics(file, nodeId));
+  out.push(...exceptionMetrics(nodeId, file.tree.rootNode, loc));
   return out;
 }
 function countLoc(content) {
@@ -2084,6 +2732,7 @@ function countLoc(content) {
 function analyzeFunctions(file) {
   const stats = [];
   const fnTypes = file.language === "python" ? PY_FUNCTION_TYPES : TS_FUNCTION_TYPES;
+  const lines = file.content.split("\n");
   walkScopes(file.tree.rootNode, file.language === "python", (node, scope) => {
     const fn = functionAt(node, fnTypes);
     if (!fn) return;
@@ -2092,7 +2741,8 @@ function analyzeFunctions(file) {
       cyclomatic: cyclomaticOf(fn.body, file.language),
       cognitive: cognitiveComplexityOf(fn.body, file.language),
       nestingDepth: nestingDepthOf(fn.body, file.language, 0),
-      loc: fn.node.endPosition.row - fn.node.startPosition.row + 1
+      loc: fn.node.endPosition.row - fn.node.startPosition.row + 1,
+      ...functionShapeStats(fn.node, fn.body, lines)
     });
   });
   return stats;
@@ -2149,7 +2799,7 @@ var TERMINALS = /* @__PURE__ */ new Set([
 ]);
 var SCOPE_TYPES = /* @__PURE__ */ new Set(["function_definition", "lambda", "class_definition"]);
 var SPLAT_TYPES = /* @__PURE__ */ new Set(["list_splat_pattern", "dictionary_splat_pattern"]);
-var RECEIVERS = /* @__PURE__ */ new Set(["self", "cls"]);
+var RECEIVERS2 = /* @__PURE__ */ new Set(["self", "cls"]);
 function pythonDeadCode(root) {
   const out = { unreachable: 0, locals: 0, params: 0 };
   const visit = (node) => {
@@ -2211,7 +2861,7 @@ function ownParamNames(fn) {
   for (const p of params.namedChildren) {
     if (!p || p.type === "keyword_separator" || p.type === "positional_separator") continue;
     const id = paramIdentifier(p);
-    out.push(id && !RECEIVERS.has(id.text) ? id.text : null);
+    out.push(id && !RECEIVERS2.has(id.text) ? id.text : null);
   }
   return out;
 }
@@ -2680,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)) {
@@ -2801,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;
@@ -2831,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)(\.[^./]+)$/;
@@ -3040,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),
@@ -3118,7 +3823,7 @@ function qualifiedByName(file) {
 }
 
 // src/indexer.ts
-var INDEX_VERSION = "0.16.0";
+var INDEX_VERSION = "0.18.0";
 var LANGUAGES = ["typescript", "python"];
 function canonicalizePath(p) {
   try {
@@ -3129,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 = {};
@@ -3233,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";
@@ -3252,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;
   }
@@ -3294,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;
 }
@@ -3313,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) {
@@ -3322,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) {
@@ -3348,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}` : ""}`);
   }
@@ -4106,6 +4811,126 @@ var SOURCE = [
     source: "source-metrics",
     description: "Deepest block nesting inside the function a symbol names; the max when several share the name."
   },
+  {
+    name: "symbol_comment_lines",
+    unit: "lines",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "neutral",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Rows holding a comment inside the function a symbol names, the docstring excluded; the max when several share the name."
+  },
+  {
+    name: "symbol_docstring_lines",
+    unit: "lines",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "neutral",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Rows of the function's docstring: the Python docstring, or the JSDoc block attached to a TypeScript declaration."
+  },
+  {
+    name: "symbol_body_lines",
+    unit: "lines",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Non-blank rows of the function's body that hold code, comments and the docstring excluded."
+  },
+  {
+    name: "symbol_comment_ratio",
+    unit: "ratio",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "neutral",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "symbol_comment_lines / max(symbol_body_lines, 1). High values suggest narration; zero is not a defect."
+  },
+  {
+    name: "symbol_narrating_comments",
+    unit: "count",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Comments in the body whose words overlap the next statement's identifiers by 2 tokens or half the comment. A candidate signal."
+  },
+  {
+    name: "symbol_pass_through",
+    unit: "count",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    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",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "neutral",
+    absent: "zero",
+    source: "exception-handling",
+    description: "Python except clauses and TypeScript catch clauses in the file."
+  },
+  {
+    name: "except_density",
+    unit: "per100loc",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "exception-handling",
+    description: "except_count per 100 non-blank lines. Recompute from the sums for a group."
+  },
+  {
+    name: "swallowed_except",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    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. Exempts Python's `except ImportError`/`ModuleNotFoundError` (alone or paired), the standard optional-dependency idiom."
+  },
   {
     name: "class_count",
     unit: "count",
@@ -4529,6 +5354,45 @@ function locateNode(node) {
   return location;
 }
 
+// src/check/outlier-rule.ts
+var DEFAULT_OUTLIER_MIN_SAMPLE = 20;
+function runMetricOutlierRule(rule, ctx) {
+  const pool = rule.kind === "symbol" ? ctx.symbolNodes : ctx.nodes;
+  const carriers = [];
+  for (const node of pool) {
+    if (node.kind !== rule.kind) continue;
+    const value = ctx.metricsByNode.get(node.id)?.get(rule.metric);
+    if (value !== void 0) carriers.push({ node, value });
+  }
+  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);
+  const rank = percentile / 100 * (sorted.length - 1);
+  const lower = Math.floor(rank);
+  const upper = Math.min(lower + 1, sorted.length - 1);
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (rank - lower);
+}
+function toViolation(rule, node, value, 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),
+    nodeId: node.id,
+    metric: rule.metric,
+    value,
+    threshold,
+    message: `${rule.metric}=${formatNumber(value)} > ${bound}`,
+    ...locateNode(node),
+    evidence: `${rule.metric}=${formatNumber(value)} (${bound})`,
+    tool: CODE_GRAPH_TOOL
+  };
+}
+
 // src/check/metric-rules.ts
 function nodeFilter(rule) {
   return {
@@ -4548,7 +5412,7 @@ function candidateNodes(rule, ctx) {
   const pool = rule.kind === "symbol" ? ctx.symbolNodes : ctx.nodes;
   return pool.filter((node) => passesFilter(node, filter));
 }
-function toViolation(rule, breach) {
+function toViolation2(rule, breach) {
   return {
     ruleId: rule.id,
     severity: severityOf(rule),
@@ -4578,7 +5442,7 @@ function runMetricMaxRule(rule, ctx) {
   for (const node of candidateNodes(rule, ctx)) {
     const value = ctx.metricsByNode.get(node.id)?.get(rule.metric);
     if (value === void 0 || value <= rule.max) continue;
-    out.push(toViolation(rule, thresholdBreach(node, rule.metric, value, "max", rule.max)));
+    out.push(toViolation2(rule, thresholdBreach(node, rule.metric, value, "max", rule.max)));
   }
   return out;
 }
@@ -4587,7 +5451,7 @@ function runMetricMinRule(rule, ctx) {
   for (const node of candidateNodes(rule, ctx)) {
     const value = ctx.metricsByNode.get(node.id)?.get(rule.metric);
     if (value === void 0 || value >= rule.min) continue;
-    out.push(toViolation(rule, thresholdBreach(node, rule.metric, value, "min", rule.min)));
+    out.push(toViolation2(rule, thresholdBreach(node, rule.metric, value, "min", rule.min)));
   }
   return out;
 }
@@ -4600,7 +5464,7 @@ function runMetricProductMaxRule(rule, ctx) {
     if (!components) continue;
     const product = components.reduce((a, b) => a * b, 1);
     if (product <= rule.max) continue;
-    out.push(toViolation(rule, productBreach(rule, node, components, product)));
+    out.push(toViolation2(rule, productBreach(rule, node, components, product)));
   }
   return out;
 }
@@ -4634,6 +5498,8 @@ function runRule(rule, ctx) {
       return runMetricMinRule(rule, ctx);
     case "metric-product-max":
       return runMetricProductMaxRule(rule, ctx);
+    case "metric-outlier":
+      return runMetricOutlierRule(rule, ctx);
     case "forbid-import":
       return runForbidImportRule(rule, ctx);
     case "layered-deps":
@@ -4778,6 +5644,8 @@ function validateRule(raw, index, warn) {
       return assertMetricMin(r, warn);
     case "metric-product-max":
       return assertMetricProductMax(r, warn);
+    case "metric-outlier":
+      return assertMetricOutlier(r, warn);
     case "forbid-import":
       return assertForbidImport(r);
     case "layered-deps":
@@ -4887,6 +5755,37 @@ function assertMetricMin(r, warn) {
     excludeRoles: parseRoleArray(ruleId, r.excludeRoles, warn)
   };
 }
+var NODE_KINDS = /* @__PURE__ */ new Set(["package", "module", "file", "symbol", "external"]);
+function assertMetricOutlier(r, warn) {
+  if (typeof r.metric !== "string") throw new Error(`${r.id}: metric must be a string`);
+  if (typeof r.kind !== "string" || !NODE_KINDS.has(r.kind)) {
+    throw new Error(`${r.id}: kind must be one of ${[...NODE_KINDS].join(", ")}`);
+  }
+  if (typeof r.percentile !== "number" || r.percentile < 50 || r.percentile > 100) {
+    throw new Error(`${r.id}: percentile must be a number from 50 to 100`);
+  }
+  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",
+    id: ruleId,
+    metric: healMetricName(r.metric, ruleId, warn),
+    kind: r.kind,
+    percentile: r.percentile,
+    minSample: r.minSample,
+    floor: r.floor,
+    rankNonZero: r.rankNonZero,
+    severity: r.severity
+  };
+}
 function assertForbidImport(r) {
   if (typeof r.from !== "string") throw new Error(`${r.id}: from must be a string`);
   if (typeof r.to !== "string") throw new Error(`${r.id}: to must be a string`);
@@ -4955,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);
 }
@@ -5378,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;
@@ -5462,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));
@@ -5587,7 +6486,9 @@ export {
   CodeGraphStore,
   DEAD_CODE_METRIC_NAMES,
   DEFAULT_CHURN_WINDOWS,
+  DEFAULT_OUTLIER_MIN_SAMPLE,
   DOMAIN_DDL,
+  EXCEPTION_METRIC_NAMES,
   GROWTH_RISK_METRIC_NAMES,
   INDEX_VERSION,
   KIT,
@@ -5600,6 +6501,7 @@ export {
   SOURCE_METRIC_NAMES,
   SYMBOL_EMBEDDING_NAMESPACE,
   SYMBOL_ID_SEP,
+  SYMBOL_METRIC_NAMES,
   TsMorphGraphExtractor,
   aggregateMetrics,
   aliasChain,
@@ -5682,6 +6584,7 @@ export {
   parseFile2 as parseFile,
   parseSymbolId,
   patternToRegex,
+  percentileOf,
   planPrune,
   priorSnapshotForRef,
   pruneDanglingReferences,