@titan-design/code-graph 0.5.0 → 0.6.0

package/README.md

@@ -27,8 +27,8 @@ In: the parser (tree-sitter WASM for TypeScript, TSX and Python, since moved to
 `@titan-design/code-parser` and still re-exported here), the walk, the ts-morph
 extractor and its symbol layer, role classification, generated-file detection, id aliasing
 across git renames, the three-tier incremental reuse, and the metrics computed at index time
-(degree, utilization, loc, cyclomatic, cognitive, nesting, class count, lcom4, per-symbol
-complexity). `lcom.ts` came along despite being an analysis: `source-metrics.ts` calls it
+(degree, utilization, loc, cyclomatic, cognitive, nesting, class count, lcom4, and per
+symbol `symbol_cognitive`, `symbol_cyclomatic`, `symbol_loc` and `symbol_max_nesting`). `lcom.ts` came along despite being an analysis: `source-metrics.ts` calls it
 directly and lcom4 is a pure function of a file's bytes, so it belongs with the metrics that
 carry forward under reuse.
 
@@ -307,8 +307,11 @@ Dead-code and growth-risk metrics are computed at index time, like the source me
 carry forward for unchanged files. Both are sparse: a file gets a row only when a count is
 above zero.
 
-- Dead code, TypeScript only: `unreachable_statements` (after a `return`, `throw`, `break`
-  or `continue` in the same block), `unused_locals`, and `unused_params` (trailing run only).
+- Dead code, TypeScript and Python: `unreachable_statements` (after a `return`, `throw` or
+  `raise`, `break` or `continue` in the same block), `unused_locals`, and `unused_params`
+  (trailing run only). Python skips `self`, `cls`, `_`-prefixed names, `global` and
+  `nonlocal` names, and the parameters of stub bodies such as `@overload` signatures; a
+  `*args` or `**kwargs` ends the trailing run.
 - Growth risk, TypeScript and Python: `loop_depth` (at 2 or more), `recursive_functions`,
   and `search_in_loop` (`.includes`, `.find` and similar inside a loop). These are smells,
   not complexity bounds. Recursion and search match TypeScript call nodes only, so Python

package/dist/index.d.ts

@@ -205,7 +205,7 @@ declare function runPrune(store: CodeGraphStore, options?: PruneOptions & {
  * index version is never reused, so a change to node/edge shape or to a metric's
  * value for the same bytes can never be carried forward from an incompatible graph.
  */
-declare const INDEX_VERSION = "0.15.0";
+declare const INDEX_VERSION = "0.16.0";
 interface IndexOptions {
     /** Roots to walk. Node ids are still rooted at the git toplevel, so importers across roots share an id space. */
     paths: string[];
@@ -779,10 +779,10 @@ declare function buildIndexerMetrics(input: IndexerMetricsInput): GraphMetric[];
  */
 declare const DEAD_CODE_METRIC_NAMES: ReadonlySet<string>;
 /**
- * Per-file dead-code metrics for TypeScript files. Emitted sparsely — only when
- * a count is > 0 — so a clean file adds no rows (a full index and an incremental
- * re-index therefore produce the identical metric set). Non-TypeScript files are
- * skipped for now.
+ * Per-file dead-code metrics for TypeScript and Python files (Python since
+ * TP-318, in dead-code-python.ts). Emitted sparsely — only when a count is > 0 —
+ * so a clean file adds no rows (a full index and an incremental re-index
+ * therefore produce the identical metric set). Other languages are skipped.
  */
 declare function computeDeadCodeMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string): GraphMetric[];
 

package/dist/index.js

@@ -1937,6 +1937,36 @@ function areLinked(a, b) {
   return false;
 }
 
+// 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" }
+];
+var SYMBOL_METRIC_NAMES = SYMBOL_METRICS.map((m) => m.name);
+function symbolMetrics(fileId2, stats, symbolNames) {
+  if (symbolNames.size === 0) return [];
+  const byName = /* @__PURE__ */ new Map();
+  for (const s of stats) {
+    if (!s.name || !symbolNames.has(s.name)) continue;
+    const prev = byName.get(s.name);
+    if (!prev) {
+      byName.set(s.name, { ...s });
+      continue;
+    }
+    for (const { stat } of SYMBOL_METRICS) prev[stat] = Math.max(prev[stat], s[stat]);
+  }
+  const out = [];
+  for (const [name, values] of byName) {
+    const nodeId = symbolId(fileId2, name);
+    for (const m of SYMBOL_METRICS) {
+      out.push({ nodeId, name: m.name, value: values[m.stat], unit: m.unit });
+    }
+  }
+  return out;
+}
+
 // src/source-metrics.ts
 var TS_FUNCTION_TYPES = /* @__PURE__ */ new Set([
   "function_declaration",
@@ -1986,12 +2016,11 @@ var SOURCE_METRIC_NAMES = /* @__PURE__ */ new Set([
   "max_nesting_depth",
   "class_count",
   "lcom4_max",
-  // Per-symbol complexity (C-58; C-64 extends it to non-exported symbols), keyed
+  // Per-symbol complexity, loc and nesting (C-58, C-64, TP-317), 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).
-  "symbol_cognitive",
-  "symbol_cyclomatic"
+  ...SYMBOL_METRIC_NAMES
 ]);
 var EMPTY_NAMES = /* @__PURE__ */ new Set();
 function computeSourceMetrics(files, fileIdOf, symbolNamesByFile2 = /* @__PURE__ */ new Map()) {
@@ -2045,30 +2074,10 @@ function metricsForFile(nodeId, file, symbolNames) {
       unit: "count"
     });
   }
-  out.push(...symbolComplexityMetrics(nodeId, stats, symbolNames));
+  out.push(...symbolMetrics(nodeId, stats, symbolNames));
   out.push(...computeLcomMetrics(file, nodeId));
   return out;
 }
-function symbolComplexityMetrics(fileId2, stats, symbolNames) {
-  if (symbolNames.size === 0) return [];
-  const byName = /* @__PURE__ */ new Map();
-  for (const s of stats) {
-    if (!s.name || !symbolNames.has(s.name)) continue;
-    const prev = byName.get(s.name);
-    if (!prev) byName.set(s.name, { cognitive: s.cognitive, cyclomatic: s.cyclomatic });
-    else {
-      prev.cognitive = Math.max(prev.cognitive, s.cognitive);
-      prev.cyclomatic = Math.max(prev.cyclomatic, s.cyclomatic);
-    }
-  }
-  const out = [];
-  for (const [name, m] of byName) {
-    const sid = symbolId(fileId2, name);
-    out.push({ nodeId: sid, name: "symbol_cognitive", value: m.cognitive, unit: "count" });
-    out.push({ nodeId: sid, name: "symbol_cyclomatic", value: m.cyclomatic, unit: "count" });
-  }
-  return out;
-}
 function countLoc(content) {
   return content.split("\n").filter((l) => l.trim() !== "").length;
 }
@@ -2082,7 +2091,8 @@ function analyzeFunctions(file) {
       name: fn.name === null ? null : qualify(scope, fn.name),
       cyclomatic: cyclomaticOf(fn.body, file.language),
       cognitive: cognitiveComplexityOf(fn.body, file.language),
-      nestingDepth: nestingDepthOf(fn.body, file.language, 0)
+      nestingDepth: nestingDepthOf(fn.body, file.language, 0),
+      loc: fn.node.endPosition.row - fn.node.startPosition.row + 1
     });
   });
   return stats;
@@ -2090,12 +2100,12 @@ function analyzeFunctions(file) {
 function functionAt(node, fnTypes) {
   if (fnTypes.has(node.type)) {
     const body = node.childForFieldName("body");
-    return body ? { name: node.childForFieldName("name")?.text ?? null, body } : null;
+    return body ? { name: node.childForFieldName("name")?.text ?? null, body, node } : null;
   }
   if ((node.type === "arrow_function" || node.type === "function_expression") && node.parent?.type === "variable_declarator") {
     const body = node.childForFieldName("body");
     if (!body) return null;
-    return { name: node.parent.childForFieldName("name")?.text ?? null, body };
+    return { name: node.parent.childForFieldName("name")?.text ?? null, body, node };
   }
   return null;
 }
@@ -2130,6 +2140,146 @@ function cyclomaticOf(body, language) {
   return complexity;
 }
 
+// src/analysis/dead-code-python.ts
+var TERMINALS = /* @__PURE__ */ new Set([
+  "return_statement",
+  "raise_statement",
+  "break_statement",
+  "continue_statement"
+]);
+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"]);
+function pythonDeadCode(root) {
+  const out = { unreachable: 0, locals: 0, params: 0 };
+  const visit = (node) => {
+    if (node.type === "block") out.unreachable += unreachableInBlock(node);
+    if (node.type === "function_definition") {
+      const r = analyzeFunction(node);
+      out.locals += r.locals;
+      out.params += r.params;
+    }
+    for (const child of node.namedChildren) {
+      if (child) visit(child);
+    }
+  };
+  visit(root);
+  return out;
+}
+function unreachableInBlock(block) {
+  let seenTerminal = false;
+  let count = 0;
+  for (const child of block.namedChildren) {
+    if (!child) continue;
+    if (seenTerminal && child.type !== "comment") count++;
+    if (TERMINALS.has(child.type)) seenTerminal = true;
+  }
+  return count;
+}
+function analyzeFunction(fn) {
+  const own = ownBindings(fn);
+  const nested = nestedBindings(fn);
+  const refs = countReferences(fn, own.declIds);
+  const isUnused = (name) => !name.startsWith("_") && !nested.has(name) && !own.declared.has(name) && (refs.get(name) ?? 0) === 0;
+  let params = 0;
+  const paramNames = ownParamNames(fn);
+  for (let i = isStub(fn) ? -1 : paramNames.length - 1; i >= 0; i--) {
+    const name = paramNames[i] ?? null;
+    if (name !== null && isUnused(name)) params++;
+    else break;
+  }
+  const paramSet = new Set(paramNames);
+  let locals = 0;
+  for (const name of own.locals) {
+    if (!paramSet.has(name) && isUnused(name)) locals++;
+  }
+  return { locals, params };
+}
+function isStub(fn) {
+  const body = fn.childForFieldName("body");
+  return (body?.namedChildren ?? []).every((stmt) => {
+    if (!stmt || stmt.type === "comment" || stmt.type === "pass_statement") return true;
+    if (stmt.type === "raise_statement") return /^raise NotImplementedError\b/.test(stmt.text);
+    const expr = stmt.type === "expression_statement" ? stmt.namedChild(0) : null;
+    return expr?.type === "ellipsis" || expr?.type === "string";
+  });
+}
+function ownParamNames(fn) {
+  const params = fn.childForFieldName("parameters");
+  if (!params) return [];
+  const out = [];
+  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);
+  }
+  return out;
+}
+function paramIdentifier(p) {
+  if (p.type === "identifier") return p;
+  if (SPLAT_TYPES.has(p.type)) return null;
+  const inner = p.childForFieldName("name") ?? p.namedChild(0);
+  return inner?.type === "identifier" ? inner : null;
+}
+function assignedIdentifier(node) {
+  if (node.type !== "assignment" || !node.childForFieldName("right")) return null;
+  const left = node.childForFieldName("left");
+  return left?.type === "identifier" ? left : null;
+}
+function ownBindings(fn) {
+  const out = { locals: /* @__PURE__ */ new Set(), declared: /* @__PURE__ */ new Set(), declIds: /* @__PURE__ */ new Set() };
+  for (const p of fn.childForFieldName("parameters")?.namedChildren ?? []) {
+    const id = p ? paramIdentifier(p) : null;
+    if (id) out.declIds.add(id.id);
+  }
+  const walk2 = (node) => {
+    if (SCOPE_TYPES.has(node.type)) return;
+    const id = assignedIdentifier(node);
+    if (id) {
+      out.locals.add(id.text);
+      out.declIds.add(id.id);
+    }
+    if (node.type === "global_statement" || node.type === "nonlocal_statement") {
+      for (const n of node.namedChildren) if (n) out.declared.add(n.text);
+    }
+    for (const child of node.namedChildren) if (child) walk2(child);
+  };
+  const body = fn.childForFieldName("body");
+  if (body) walk2(body);
+  return out;
+}
+function nestedBindings(fn) {
+  const out = /* @__PURE__ */ new Set();
+  const walk2 = (node, nested) => {
+    const inner = nested || node !== fn && SCOPE_TYPES.has(node.type);
+    if (inner) {
+      const id = assignedIdentifier(node);
+      if (id) out.add(id.text);
+      if (node.type === "parameters" || node.type === "lambda_parameters") {
+        for (const p of node.namedChildren) {
+          const pid = p ? paramIdentifier(p) : null;
+          if (pid) out.add(pid.text);
+        }
+      }
+    }
+    for (const child of node.namedChildren) if (child) walk2(child, inner);
+  };
+  walk2(fn, false);
+  return out;
+}
+function countReferences(fn, declIds) {
+  const out = /* @__PURE__ */ new Map();
+  const walk2 = (node) => {
+    if (node.type === "identifier" && !declIds.has(node.id)) {
+      out.set(node.text, (out.get(node.text) ?? 0) + 1);
+    }
+    for (const child of node.namedChildren) if (child) walk2(child);
+  };
+  const body = fn.childForFieldName("body");
+  if (body) walk2(body);
+  return out;
+}
+
 // src/analysis/dead-code.ts
 var DEAD_CODE_METRIC_NAMES = /* @__PURE__ */ new Set([
   "unreachable_statements",
@@ -2145,7 +2295,7 @@ var FUNCTION_TYPES = /* @__PURE__ */ new Set([
   "generator_function"
 ]);
 var PARAM_TYPES = /* @__PURE__ */ new Set(["required_parameter", "optional_parameter"]);
-var TERMINALS = /* @__PURE__ */ new Set([
+var TERMINALS2 = /* @__PURE__ */ new Set([
   "return_statement",
   "throw_statement",
   "break_statement",
@@ -2154,13 +2304,13 @@ var TERMINALS = /* @__PURE__ */ new Set([
 function computeDeadCodeMetrics(files, fileIdOf) {
   const out = [];
   for (const file of files) {
-    if (file.language !== "typescript" && file.language !== "tsx") continue;
+    const counts = deadCodeOf(file);
+    if (!counts) continue;
     const id = fileIdOf(file.filePath);
-    const unreachable = countUnreachable(file.tree.rootNode);
+    const { unreachable, locals, params } = counts;
     if (unreachable > 0) {
       out.push({ nodeId: id, name: "unreachable_statements", value: unreachable, unit: "count" });
     }
-    const { locals, params } = countUnusedBindings(file.tree.rootNode);
     if (locals > 0) {
       out.push({ nodeId: id, name: "unused_locals", value: locals, unit: "count" });
     }
@@ -2170,10 +2320,16 @@ function computeDeadCodeMetrics(files, fileIdOf) {
   }
   return out;
 }
+function deadCodeOf(file) {
+  const root = file.tree.rootNode;
+  if (file.language === "python") return pythonDeadCode(root);
+  if (file.language !== "typescript" && file.language !== "tsx") return null;
+  return { unreachable: countUnreachable(root), ...countUnusedBindings(root) };
+}
 function countUnreachable(root) {
   let count = 0;
   const visit = (node) => {
-    if (node.type === "statement_block") count += unreachableInBlock(node);
+    if (node.type === "statement_block") count += unreachableInBlock2(node);
     for (const child of node.namedChildren) {
       if (child) visit(child);
     }
@@ -2181,7 +2337,7 @@ function countUnreachable(root) {
   visit(root);
   return count;
 }
-function unreachableInBlock(block) {
+function unreachableInBlock2(block) {
   let seenTerminal = false;
   let count = 0;
   for (const child of block.namedChildren) {
@@ -2189,7 +2345,7 @@ function unreachableInBlock(block) {
     if (seenTerminal && child.type !== "comment" && child.type !== "function_declaration") {
       count++;
     }
-    if (TERMINALS.has(child.type)) seenTerminal = true;
+    if (TERMINALS2.has(child.type)) seenTerminal = true;
   }
   return count;
 }
@@ -2198,7 +2354,7 @@ function countUnusedBindings(root) {
   let params = 0;
   const visit = (node) => {
     if (FUNCTION_TYPES.has(node.type)) {
-      const r = analyzeFunction(node);
+      const r = analyzeFunction2(node);
       locals += r.locals;
       params += r.params;
     }
@@ -2209,14 +2365,14 @@ function countUnusedBindings(root) {
   visit(root);
   return { locals, params };
 }
-function analyzeFunction(fn) {
+function analyzeFunction2(fn) {
   const declIds = /* @__PURE__ */ new Set();
   const nameCount = /* @__PURE__ */ new Map();
   collectBindingDecls(fn, declIds, nameCount);
   const refs = /* @__PURE__ */ new Map();
-  countReferences(fn, declIds, refs);
+  countReferences2(fn, declIds, refs);
   const isUnused = (name) => !name.startsWith("_") && (nameCount.get(name) ?? 0) <= 1 && (refs.get(name) ?? 0) === 0;
-  const paramNames = ownParamNames(fn);
+  const paramNames = ownParamNames2(fn);
   let params = 0;
   for (let i = paramNames.length - 1; i >= 0; i--) {
     const name = paramNames[i] ?? null;
@@ -2229,7 +2385,7 @@ function analyzeFunction(fn) {
   }
   return { locals, params };
 }
-function ownParamNames(fn) {
+function ownParamNames2(fn) {
   const params = fn.childForFieldName("parameters");
   if (!params) return [];
   const out = [];
@@ -2272,7 +2428,7 @@ function collectBindingDecls(fn, ids, nameCount) {
   };
   walk2(fn);
 }
-function countReferences(fn, declIds, out) {
+function countReferences2(fn, declIds, out) {
   const walk2 = (node) => {
     if ((node.type === "identifier" || node.type === "shorthand_property_identifier") && !declIds.has(node.id)) {
       out.set(node.text, (out.get(node.text) ?? 0) + 1);
@@ -2962,7 +3118,7 @@ function qualifiedByName(file) {
 }
 
 // src/indexer.ts
-var INDEX_VERSION = "0.15.0";
+var INDEX_VERSION = "0.16.0";
 var LANGUAGES = ["typescript", "python"];
 function canonicalizePath(p) {
   try {
@@ -3930,6 +4086,26 @@ var SOURCE = [
     source: "source-metrics",
     description: "Cyclomatic complexity of the function a symbol names; the max when several functions share the name."
   },
+  {
+    name: "symbol_loc",
+    unit: "lines",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Lines spanned by the function a symbol names, signature included; the max when several share the name."
+  },
+  {
+    name: "symbol_max_nesting",
+    unit: "count",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Deepest block nesting inside the function a symbol names; the max when several share the name."
+  },
   {
     name: "class_count",
     unit: "count",