@titan-design/code-graph 0.5.0 → 0.7.0

package/dist/index.js

@@ -1685,6 +1685,220 @@ 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"]);
+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) {
+  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 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,6 +2151,128 @@ 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_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) {
+  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;
+}
+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([
   "function_declaration",
@@ -1986,12 +2322,12 @@ 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
+  ...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).
-  "symbol_cognitive",
-  "symbol_cyclomatic"
+  ...SYMBOL_METRIC_NAMES
 ]);
 var EMPTY_NAMES = /* @__PURE__ */ new Set();
 function computeSourceMetrics(files, fileIdOf, symbolNamesByFile2 = /* @__PURE__ */ new Map()) {
@@ -2045,28 +2381,9 @@ 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" });
-  }
+  out.push(...exceptionMetrics(nodeId, file.tree.rootNode, loc));
   return out;
 }
 function countLoc(content) {
@@ -2075,6 +2392,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;
@@ -2082,7 +2400,9 @@ 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,
+      ...functionShapeStats(fn.node, fn.body, lines)
     });
   });
   return stats;
@@ -2090,12 +2410,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 +2450,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 RECEIVERS2 = /* @__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 && !RECEIVERS2.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 +2605,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 +2614,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 +2630,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 +2647,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 +2655,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 +2664,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 +2675,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 +2695,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 +2738,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 +3428,7 @@ function qualifiedByName(file) {
 }
 
 // src/indexer.ts
-var INDEX_VERSION = "0.15.0";
+var INDEX_VERSION = "0.17.0";
 var LANGUAGES = ["typescript", "python"];
 function canonicalizePath(p) {
   try {
@@ -3930,6 +4396,116 @@ 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: "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: "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."
+  },
   {
     name: "class_count",
     unit: "count",
@@ -4353,6 +4929,43 @@ 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 });
+  }
+  if (carriers.length < (rule.minSample ?? DEFAULT_OUTLIER_MIN_SAMPLE)) return [];
+  const threshold = percentileOf(carriers.map((c) => c.value), rule.percentile);
+  return carriers.filter((c) => c.value > threshold).map((c) => toViolation(rule, c.node, c.value, threshold));
+}
+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 bound = `p${formatNumber(rule.percentile)} ${formatNumber(threshold)}`;
+  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 {
@@ -4372,7 +4985,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),
@@ -4402,7 +5015,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;
 }
@@ -4411,7 +5024,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;
 }
@@ -4424,7 +5037,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;
 }
@@ -4458,6 +5071,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":
@@ -4602,6 +5217,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":
@@ -4711,6 +5328,29 @@ 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`);
+  }
+  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,
+    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`);
@@ -5411,7 +6051,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,
@@ -5424,6 +6066,7 @@ export {
   SOURCE_METRIC_NAMES,
   SYMBOL_EMBEDDING_NAMESPACE,
   SYMBOL_ID_SEP,
+  SYMBOL_METRIC_NAMES,
   TsMorphGraphExtractor,
   aggregateMetrics,
   aliasChain,
@@ -5506,6 +6149,7 @@ export {
   parseFile2 as parseFile,
   parseSymbolId,
   patternToRegex,
+  percentileOf,
   planPrune,
   priorSnapshotForRef,
   pruneDanglingReferences,