@titan-design/code-graph 0.4.0 → 0.6.0

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",
@@ -4177,11 +4353,13 @@ function describeMetrics(names) {
 
 // src/check/context.ts
 function buildRuleContext(store, snapshotId) {
-  const nodes = store.listNodes(snapshotId);
+  const all = store.listNodes(snapshotId, { includeSymbols: true });
+  const nodes = all.filter((n) => n.kind !== "symbol");
+  const symbolNodes2 = all.filter((n) => n.kind === "symbol");
   const edges = store.listEdges(snapshotId);
   const nodesById = /* @__PURE__ */ new Map();
   for (const n of nodes) nodesById.set(n.id, n);
-  return { nodes, nodesById, metricsByNode: indexMetrics(store.listMetrics(snapshotId)), edges };
+  return { nodes, symbolNodes: symbolNodes2, nodesById, metricsByNode: indexMetrics(store.listMetrics(snapshotId)), edges };
 }
 function indexMetrics(metrics) {
   const metricsByNode = /* @__PURE__ */ new Map();
@@ -4339,6 +4517,18 @@ function barrelMessage(barrelPkg, importerCount) {
   return importerCount === 0 ? `barrel in package "${barrelPkg}" has no importers` : `barrel in package "${barrelPkg}" has ${importerCount} internal importer(s) but zero external`;
 }
 
+// src/check/violation-location.ts
+var CODE_GRAPH_TOOL = "code-graph";
+function locateNode(node) {
+  if (node.kind !== "symbol") return { path: node.id };
+  const location = { path: node.parentId ?? node.id, symbol: node.name };
+  const startLine = node.attrs?.startLine;
+  const endLine = node.attrs?.endLine;
+  if (typeof startLine === "number") location.lineStart = startLine;
+  if (typeof endLine === "number") location.lineEnd = endLine;
+  return location;
+}
+
 // src/check/metric-rules.ts
 function nodeFilter(rule) {
   return {
@@ -4353,71 +4543,76 @@ function passesFilter(node, filter) {
   if (node.role && filter.excludedRoles.has(node.role)) return false;
   return true;
 }
-function runMetricMaxRule(rule, ctx) {
+function candidateNodes(rule, ctx) {
   const filter = nodeFilter(rule);
+  const pool = rule.kind === "symbol" ? ctx.symbolNodes : ctx.nodes;
+  return pool.filter((node) => passesFilter(node, filter));
+}
+function toViolation(rule, breach) {
+  return {
+    ruleId: rule.id,
+    severity: severityOf(rule),
+    nodeId: breach.node.id,
+    metric: breach.metric,
+    value: breach.value,
+    threshold: breach.threshold,
+    message: breach.message,
+    ...locateNode(breach.node),
+    evidence: breach.evidence,
+    tool: CODE_GRAPH_TOOL
+  };
+}
+function thresholdBreach(node, metric, value, bound, threshold) {
+  const op = bound === "max" ? ">" : "<";
+  return {
+    node,
+    metric,
+    value,
+    threshold,
+    message: `${metric}=${formatNumber(value)} ${op} ${formatNumber(threshold)}`,
+    evidence: `${metric}=${formatNumber(value)} (${bound} ${formatNumber(threshold)})`
+  };
+}
+function runMetricMaxRule(rule, ctx) {
   const out = [];
-  for (const node of ctx.nodes) {
-    if (!passesFilter(node, filter)) continue;
+  for (const node of candidateNodes(rule, ctx)) {
     const value = ctx.metricsByNode.get(node.id)?.get(rule.metric);
-    if (value === void 0) continue;
-    if (value <= rule.max) continue;
-    out.push({
-      ruleId: rule.id,
-      severity: severityOf(rule),
-      nodeId: node.id,
-      metric: rule.metric,
-      value,
-      threshold: rule.max,
-      message: `${rule.metric}=${formatNumber(value)} > ${formatNumber(rule.max)}`
-    });
+    if (value === void 0 || value <= rule.max) continue;
+    out.push(toViolation(rule, thresholdBreach(node, rule.metric, value, "max", rule.max)));
   }
   return out;
 }
 function runMetricMinRule(rule, ctx) {
-  const filter = nodeFilter(rule);
   const out = [];
-  for (const node of ctx.nodes) {
-    if (!passesFilter(node, filter)) continue;
+  for (const node of candidateNodes(rule, ctx)) {
     const value = ctx.metricsByNode.get(node.id)?.get(rule.metric);
-    if (value === void 0) continue;
-    if (value >= rule.min) continue;
-    out.push({
-      ruleId: rule.id,
-      severity: severityOf(rule),
-      nodeId: node.id,
-      metric: rule.metric,
-      value,
-      threshold: rule.min,
-      message: `${rule.metric}=${formatNumber(value)} < ${formatNumber(rule.min)}`
-    });
+    if (value === void 0 || value >= rule.min) continue;
+    out.push(toViolation(rule, thresholdBreach(node, rule.metric, value, "min", rule.min)));
   }
   return out;
 }
 function runMetricProductMaxRule(rule, ctx) {
-  const filter = nodeFilter(rule);
   const out = [];
-  for (const node of ctx.nodes) {
-    if (!passesFilter(node, filter)) continue;
+  for (const node of candidateNodes(rule, ctx)) {
     const inner = ctx.metricsByNode.get(node.id);
     if (!inner) continue;
     const components = collectComponents(rule.metrics, inner);
     if (!components) continue;
     const product = components.reduce((a, b) => a * b, 1);
     if (product <= rule.max) continue;
-    out.push(productViolation(rule, node.id, components, product));
+    out.push(toViolation(rule, productBreach(rule, node, components, product)));
   }
   return out;
 }
-function productViolation(rule, nodeId, components, product) {
+function productBreach(rule, node, components, product) {
   const detail = rule.metrics.map((m, i) => `${m}=${formatNumber(components[i])}`).join(" * ");
   return {
-    ruleId: rule.id,
-    severity: severityOf(rule),
-    nodeId,
+    node,
     metric: rule.metrics.join(" * "),
     value: product,
     threshold: rule.max,
-    message: `${detail} = ${formatNumber(product)} > ${formatNumber(rule.max)}`
+    message: `${detail} = ${formatNumber(product)} > ${formatNumber(rule.max)}`,
+    evidence: `${detail} = ${formatNumber(product)} (max ${formatNumber(rule.max)})`
   };
 }
 function collectComponents(metrics, values) {
@@ -4507,6 +4702,43 @@ function countByOriginAndSeverity(violations) {
   return counts;
 }
 
+// src/check/findings.ts
+function toFindings(result) {
+  return result.violations.map(violationToFinding);
+}
+function violationToFinding(v) {
+  const tool = v.tool ?? CODE_GRAPH_TOOL;
+  const target = v.destinationId ? `${v.nodeId}->${v.destinationId}` : v.nodeId;
+  return withoutUndefined({
+    id: `${tool}:${v.ruleId}:${target}`,
+    path: v.path ?? v.nodeId,
+    lineStart: v.lineStart,
+    lineEnd: v.lineEnd,
+    symbol: v.symbol,
+    signal: v.ruleId,
+    value: v.value,
+    threshold: v.threshold,
+    severity: v.severity,
+    evidence: v.evidence ?? v.message,
+    tool
+  });
+}
+function externalToFinding(input) {
+  return withoutUndefined({
+    id: `${input.tool}:${input.rule}:${input.file}:${input.line}`,
+    path: input.file,
+    lineStart: input.line,
+    lineEnd: input.endLine,
+    signal: input.rule,
+    severity: input.severity,
+    evidence: input.message,
+    tool: input.tool
+  });
+}
+function withoutUndefined(finding) {
+  return Object.fromEntries(Object.entries(finding).filter(([, v]) => v !== void 0));
+}
+
 // src/check/validate.ts
 function validateRules(input, options = {}) {
   if (!input || typeof input !== "object") {
@@ -5414,6 +5646,7 @@ export {
   embedSnapshot,
   embedTextsCached,
   externalId,
+  externalToFinding,
   fileId,
   findConventions,
   findSimilarCapability,
@@ -5472,6 +5705,7 @@ export {
   summarizeConventions,
   symbolId,
   testCoverageCountMetrics,
+  toFindings,
   tryEmbedSnapshot,
   validateRules,
   violationKey,