@mmerterden/multi-agent-pipeline 16.12.0 → 16.13.0

package/pipeline/scripts/code-graph-rules/android.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "android",
+  "description": "Kotlin + Java code-graph rules. Adds what the graph needs on top of test-gap-rules/android.json, which already owns sourceExtensions, excludePathGlobs and the test-path predicates. Definition patterns here are deliberately broader than the test-gap publicApiPatterns: the graph wants internal types too, because Phase 1 narrows scope on the whole module, not just its public surface.",
+  "comments": {
+    "line": [
+      "//"
+    ],
+    "block": [
+      [
+        "/*",
+        "*/"
+      ]
+    ],
+    "string": [
+      "\"\"\"",
+      "\""
+    ]
+  },
+  "definitionPatterns": [
+    {
+      "id": "enum",
+      "kind": "enum",
+      "regex": "\\benum\\s+(?:class\\s+)?([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "record",
+      "kind": "record",
+      "regex": "\\brecord\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "typealias",
+      "kind": "typealias",
+      "regex": "\\btypealias\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "object",
+      "kind": "object",
+      "regex": "\\bobject\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "interface",
+      "kind": "interface",
+      "regex": "\\binterface\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "class",
+      "kind": "class",
+      "regex": "\\bclass\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "fun",
+      "kind": "fun",
+      "regex": "\\bfun\\s+(?:<[^>]*>\\s*)?([a-zA-Z_][A-Za-z0-9_]*)"
+    }
+  ],
+  "importPatterns": [
+    {
+      "id": "import",
+      "regex": "^\\s*import\\s+(?:static\\s+)?(?:[A-Za-z_][A-Za-z0-9_]*\\.)+([A-Z][A-Za-z0-9_]*)"
+    }
+  ],
+  "referenceKinds": [
+    "class",
+    "interface",
+    "object",
+    "enum",
+    "record",
+    "typealias"
+  ],
+  "referenceKindsNote": "fun is deliberately absent, for the reason Swift's rules record for func: a bare lowercase name matched across files is almost never a call to that exact declaration, and on a large app the generic ones (invoke, build, create, get) take the top god-node slots purely because each happened to be declared once. Composables are the tempting exception - they are capitalised and behave like types - but they are declared with fun, so including them means including every other fun with them.",
+  "ignoredIdentifiers": [
+    "this",
+    "super",
+    "it",
+    "init",
+    "constructor",
+    "companion",
+    "class",
+    "interface",
+    "object",
+    "enum",
+    "record",
+    "fun",
+    "val",
+    "var",
+    "return",
+    "when",
+    "where",
+    "is",
+    "as",
+    "in",
+    "out",
+    "by",
+    "import",
+    "package",
+    "public",
+    "private",
+    "protected",
+    "internal",
+    "static",
+    "final",
+    "abstract",
+    "open",
+    "override",
+    "sealed",
+    "data",
+    "inline",
+    "suspend",
+    "lateinit",
+    "throws",
+    "try",
+    "catch",
+    "finally",
+    "null",
+    "true",
+    "false",
+    "void",
+    "int",
+    "long",
+    "boolean",
+    "String",
+    "Int",
+    "Long",
+    "Boolean",
+    "Unit",
+    "Any"
+  ],
+  "note": "Kotlin declaration modifiers are not separate patterns: `data class Foo`, `sealed class Foo` and `annotation class Foo` all still contain `class Foo`, so one pattern covers them. `enum` allows an optional `class` between keyword and name, which is the only shape that differs between Java (`enum Foo`) and Kotlin (`enum class Foo`). `object` matches the named form only - `companion object {` and the anonymous `object : Iface {` carry no name and correctly produce nothing. Imports are fully qualified on the JVM, so the pattern captures the final segment: `import com.example.ui.Button` resolves against the file named Button.kt, which is how the engine links a file-level import edge. A star import (`import com.example.ui.*`) captures nothing, deliberately - it names a package, and pointing every star import at an arbitrary file in that package would invent an edge nobody wrote. Pattern ORDER is load-bearing: `enum class Cabin` matches both the enum pattern and the class pattern, and the first match to register the name decides its kind, so the more specific patterns are listed first. With class first, every Kotlin enum was filed as a class and the report's symbol-kind census was wrong."
+}

package/pipeline/scripts/code-graph-rules/ios.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "ios",
+  "description": "Swift code-graph rules. Adds what the graph needs on top of test-gap-rules/ios.json, which already owns sourceExtensions, excludePathGlobs and the test-path predicates. Definition patterns here are deliberately broader than the test-gap publicApiPatterns: the graph wants internal types too, because Phase 1 narrows scope on the whole module, not just its public surface.",
+  "comments": {
+    "line": ["//"],
+    "block": [["/*", "*/"]],
+    "string": ["\"\"\"", "\""]
+  },
+  "definitionPatterns": [
+    {
+      "id": "class",
+      "kind": "class",
+      "regex": "\\b(?:final\\s+)?class\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "struct",
+      "kind": "struct",
+      "regex": "\\bstruct\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "enum",
+      "kind": "enum",
+      "regex": "\\benum\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "protocol",
+      "kind": "protocol",
+      "regex": "\\bprotocol\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "actor",
+      "kind": "actor",
+      "regex": "\\bactor\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "typealias",
+      "kind": "typealias",
+      "regex": "\\btypealias\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "func",
+      "kind": "func",
+      "regex": "\\bfunc\\s+([a-zA-Z_][A-Za-z0-9_]*)"
+    }
+  ],
+  "importPatterns": [
+    {
+      "id": "import",
+      "regex": "^\\s*import\\s+(?:class|struct|enum|protocol|func|var|let|typealias)\\s+([A-Za-z_][A-Za-z0-9_]*)|^\\s*import\\s+([A-Za-z_][A-Za-z0-9_]*)"
+    }
+  ],
+  "referenceKinds": ["class", "struct", "enum", "protocol", "actor", "typealias"],
+  "referenceKindsNote": "func is deliberately absent. A bare lowercase method name matched across files is almost never a call to that exact declaration: on a large Swift app `with`, `size`, `name`, `image` and `model` took the top god-node slots purely because each happened to be declared in exactly one file. Functions still reach the graph through their `defines` edge, so they stay findable by name.",
+  "ignoredIdentifiers": [
+    "self",
+    "Self",
+    "super",
+    "init",
+    "deinit",
+    "body",
+    "some",
+    "any",
+    "func",
+    "class",
+    "struct",
+    "enum",
+    "protocol",
+    "extension",
+    "var",
+    "let",
+    "return",
+    "guard",
+    "where",
+    "case",
+    "default",
+    "import",
+    "public",
+    "private",
+    "internal",
+    "fileprivate",
+    "open",
+    "static",
+    "final",
+    "override",
+    "throws",
+    "async",
+    "await",
+    "try",
+    "nil",
+    "true",
+    "false"
+  ],
+  "note": "extension is intentionally NOT a definition pattern. `extension Foo` would register a second symbol named Foo alongside its declaring file, the name would become ambiguous, and buildGraph drops ambiguous references - so every reference to an extended type would vanish. Extensions still reach the graph as reference edges through the identifier pass."
+}

package/pipeline/scripts/code-graph-rules/node.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "node",
+  "description": "TypeScript + JavaScript code-graph rules. Adds what the graph needs on top of test-gap-rules/node.json, which already owns sourceExtensions, excludePathGlobs and the test-path predicates. Definition patterns here are deliberately broader than the test-gap publicApiPatterns: the graph wants unexported declarations too, because Phase 1 narrows scope on the whole module, not just its public surface.",
+  "comments": {
+    "line": [
+      "//"
+    ],
+    "block": [
+      [
+        "/*",
+        "*/"
+      ]
+    ],
+    "string": [
+      "`",
+      "\"",
+      "'"
+    ]
+  },
+  "definitionPatterns": [
+    {
+      "id": "class",
+      "kind": "class",
+      "regex": "\\bclass\\s+([A-Za-z_$][A-Za-z0-9_$]*)"
+    },
+    {
+      "id": "interface",
+      "kind": "interface",
+      "regex": "\\binterface\\s+([A-Za-z_$][A-Za-z0-9_$]*)"
+    },
+    {
+      "id": "type",
+      "kind": "type",
+      "regex": "\\btype\\s+([A-Za-z_$][A-Za-z0-9_$]*)\\s*(?:<[^=>]*>\\s*)?="
+    },
+    {
+      "id": "enum",
+      "kind": "enum",
+      "regex": "\\benum\\s+([A-Za-z_$][A-Za-z0-9_$]*)"
+    },
+    {
+      "id": "const",
+      "kind": "const",
+      "regex": "^(?:export\\s+)?(?:declare\\s+)?const\\s+([A-Z][A-Za-z0-9_$]*)\\s*[:=]"
+    },
+    {
+      "id": "function",
+      "kind": "function",
+      "regex": "\\bfunction\\s*\\*?\\s+([A-Za-z_$][A-Za-z0-9_$]*)"
+    }
+  ],
+  "importPatterns": [
+    {
+      "id": "specifier",
+      "regex": "(?:\\bfrom|\\brequire\\s*\\(|\\bimport)\\s*\\(?\\s*[\"'](?:[^\"']*[\\/:])?([A-Za-z_$][A-Za-z0-9_$-]*)(?:\\.[A-Za-z0-9]+)*[\"']"
+    }
+  ],
+  "referenceKinds": [
+    "class",
+    "interface",
+    "type",
+    "enum",
+    "const"
+  ],
+  "referenceKindsNote": "function is deliberately absent, for the reason Swift's rules record for func: a bare name matched across files is almost never a call to that exact declaration, and the generic ones (run, main, get, parse, handler) would take the top god-node slots purely because each happened to be declared once. Functions still reach the graph through their defines edge, so they stay findable by name. const is present but narrowed to an uppercase-initial declaration at column 0, which is what a component, a singleton or an exported table looks like; a lowercase const is a local and is not a declaration anyone references across files. Measured on this repo (126 sources): including function put `ok` at degree 52, `f` at 38, `tokens` at 15 and `arg` at 12 - local helper names that happen to be declared exactly once, so the ambiguity rule does not catch them either. Excluding it leaves a thin symbol layer, and that is the honest shape of this stack: a JavaScript module's exported unit is usually a function, so the useful graph here is the import graph between files. `graph-affected \"<file>.mjs\"` answers who imports a module, which is the question this stack actually gets asked.",
+  "ignoredIdentifiers": [
+    "this",
+    "super",
+    "constructor",
+    "prototype",
+    "arguments",
+    "class",
+    "interface",
+    "type",
+    "enum",
+    "function",
+    "const",
+    "let",
+    "var",
+    "return",
+    "import",
+    "export",
+    "default",
+    "from",
+    "as",
+    "in",
+    "of",
+    "new",
+    "delete",
+    "typeof",
+    "instanceof",
+    "void",
+    "await",
+    "async",
+    "yield",
+    "if",
+    "else",
+    "switch",
+    "case",
+    "for",
+    "while",
+    "do",
+    "break",
+    "continue",
+    "try",
+    "catch",
+    "finally",
+    "throw",
+    "extends",
+    "implements",
+    "static",
+    "public",
+    "private",
+    "protected",
+    "readonly",
+    "declare",
+    "namespace",
+    "module",
+    "require",
+    "null",
+    "undefined",
+    "true",
+    "false",
+    "string",
+    "number",
+    "boolean",
+    "object",
+    "any",
+    "unknown",
+    "never",
+    "console",
+    "process",
+    "window",
+    "document",
+    "Promise",
+    "Array",
+    "Object",
+    "String",
+    "Number",
+    "Boolean",
+    "Error",
+    "JSON",
+    "Math",
+    "Date",
+    "Map",
+    "Set"
+  ],
+  "note": "A JavaScript module specifier IS a string literal, so `importSpecifiersAreStrings` tells the engine to run the import patterns over a text with comments stripped but strings intact. Without it every import edge in this stack would vanish silently, because the specifier is blanked before the pattern ever sees it. Only the import pass reads that text; definitions and the identifier set still come from the fully stripped body, so a name that appears only inside a string still produces no reference edge. Template literals are stripped whole, interpolations included: it is better to lose a real mention than to invent one from a string. The single specifier pattern captures the last path segment with any extension chain removed, which is what the engine resolves against a file basename: ./_retrieval.mjs and ../a/b/util and node:fs and @scope/pkg all reduce to one name.",
+  "importSpecifiersAreStrings": true
+}

package/pipeline/scripts/code-graph-rules/python.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "python",
+  "description": "Python code-graph rules. Adds what the graph needs on top of test-gap-rules/python.json, which already owns sourceExtensions, excludePathGlobs and the test-path predicates. Definition patterns here are deliberately broader than the test-gap publicApiPatterns: the graph wants private declarations too, because Phase 1 narrows scope on the whole package, not just its public surface.",
+  "comments": {
+    "line": ["#"],
+    "block": [],
+    "string": ["\"\"\"", "'''", "\"", "'"]
+  },
+  "definitionPatterns": [
+    {
+      "id": "class",
+      "kind": "class",
+      "regex": "\\bclass\\s+([A-Za-z_][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "def",
+      "kind": "def",
+      "regex": "\\bdef\\s+([A-Za-z_][A-Za-z0-9_]*)"
+    }
+  ],
+  "importPatterns": [
+    {
+      "id": "from-import",
+      "regex": "^\\s*from\\s+[.\\w]*?([A-Za-z_][A-Za-z0-9_]*)\\s+import\\b"
+    },
+    {
+      "id": "import",
+      "regex": "^\\s*import\\s+(?:[A-Za-z_][A-Za-z0-9_]*\\.)*([A-Za-z_][A-Za-z0-9_]*)"
+    }
+  ],
+  "referenceKinds": ["class"],
+  "referenceKindsNote": "def is deliberately absent, for the reason Swift's rules record for func and the node rules record with measurements: a bare lowercase name matched across files is almost never a call to that exact declaration, and Python's convention of short module-level helpers (main, run, load, parse, setup) makes it worse than most. Functions still reach the graph through their defines edge, so they stay findable by name.",
+  "ignoredIdentifiers": [
+    "self",
+    "cls",
+    "class",
+    "def",
+    "return",
+    "import",
+    "from",
+    "as",
+    "in",
+    "is",
+    "not",
+    "and",
+    "or",
+    "if",
+    "elif",
+    "else",
+    "for",
+    "while",
+    "break",
+    "continue",
+    "pass",
+    "try",
+    "except",
+    "finally",
+    "raise",
+    "with",
+    "yield",
+    "lambda",
+    "global",
+    "nonlocal",
+    "assert",
+    "del",
+    "async",
+    "await",
+    "None",
+    "True",
+    "False",
+    "print",
+    "len",
+    "str",
+    "int",
+    "float",
+    "bool",
+    "list",
+    "dict",
+    "set",
+    "tuple",
+    "type",
+    "range",
+    "open",
+    "super",
+    "property",
+    "staticmethod",
+    "classmethod"
+  ],
+  "note": "There is no block-comment token: a Python triple-quoted docstring is a string literal, and it is listed under `string` so the stripper removes it the same way it removes any other string. Longest tokens come first there, so \"\"\" and ''' are consumed whole before the single-quote forms get a chance to match their first character. Both import patterns capture the LAST dotted segment, which is what the engine resolves against a file basename: `from package.module import Thing` points at module.py, and `import package.module` does the same. `from . import x` and `from .. import x` capture nothing, deliberately - a bare relative package names a directory, and pointing it at an arbitrary file inside would invent an edge nobody wrote."
+}

package/pipeline/scripts/graph-affected.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-affected.mjs  -  reverse traversal: what breaks if this changes.
+ *
+ * Phase 1's impact surface, feeding `analysis.touchedAreas[]`. Where
+ * graph-query.mjs answers "where does this live", this answers "who depends on
+ * it": it walks edges backwards from a named symbol, so the result is the blast
+ * radius of a change rather than its neighbourhood.
+ *
+ * Inputs:
+ *   "<symbol>"       Symbol name, exact or case-insensitive. Required.
+ *   --graph <path>   Graph file. Default: ~/.claude/knowledge/<cwd name>/code-graph.json
+ *   --depth N        Reverse traversal depth. Default: 2
+ *   --kind K         Restrict to one edge kind (repeatable via comma)
+ *   --json           Emit JSON instead of text
+ *
+ * Exit codes:
+ *   0  -  answered (possibly empty)
+ *   1  -  graph missing or unreadable
+ *   64 -  usage error
+ *
+ * @module pipeline/scripts/graph-affected
+ */
+
+import { resolve } from "node:path";
+import { parseFlags } from "./graph-build.mjs";
+import { loadGraph, defaultGraphPath } from "./graph-query.mjs";
+
+/**
+ * Nodes whose name matches, preferring an exact hit.
+ *
+ * A case-insensitive fallback keeps the command usable from a task description,
+ * where the symbol is often typed in prose casing.
+ *
+ * @param {object} graph
+ * @param {string} name
+ * @returns {object[]}
+ */
+export function findByName(graph, name) {
+  const exact = graph.nodes.filter((n) => n.name === name);
+  if (exact.length) return exact;
+  const lower = name.toLowerCase();
+  return graph.nodes.filter((n) => (n.name || "").toLowerCase() === lower);
+}
+
+/**
+ * Incoming adjacency only.
+ *
+ * @param {object} graph
+ * @param {Set<string>|null} kinds
+ * @returns {Map<string, Array<{id: string, kind: string}>>}
+ */
+export function incoming(graph, kinds = null) {
+  const adj = new Map();
+  for (const e of graph.edges) {
+    if (kinds && !kinds.has(e.kind)) continue;
+    if (!adj.has(e.to)) adj.set(e.to, []);
+    adj.get(e.to).push({ id: e.from, kind: e.kind });
+  }
+  return adj;
+}
+
+/**
+ * Walk backwards from each seed.
+ *
+ * @param {object} params
+ * @returns {Array<{id: string, dist: number, kind: string, node: object}>}
+ */
+export function affected({ graph, seeds, depth, kinds }) {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const adj = incoming(graph, kinds);
+  const seen = new Set(seeds.map((n) => n.id));
+  const out = [];
+  const queue = seeds.map((n) => ({ id: n.id, dist: 0, kind: "seed" }));
+
+  while (queue.length) {
+    const cur = queue.shift();
+    if (cur.dist > 0) out.push({ ...cur, node: byId.get(cur.id) });
+    if (cur.dist >= depth) continue;
+    for (const dep of adj.get(cur.id) || []) {
+      if (seen.has(dep.id)) continue;
+      seen.add(dep.id);
+      queue.push({ id: dep.id, dist: cur.dist + 1, kind: dep.kind });
+    }
+  }
+  return out;
+}
+
+function main() {
+  const { flags, positional } = parseFlags(process.argv.slice(2));
+  const name = positional.join(" ").trim();
+  if (!name) {
+    process.stderr.write(
+      'graph-affected: a symbol name is required, e.g. graph-affected "Flight"\n',
+    );
+    process.exit(64);
+  }
+
+  const path = flags.graph && flags.graph !== true ? resolve(flags.graph) : defaultGraphPath();
+  let graph;
+  try {
+    graph = loadGraph(path);
+  } catch (e) {
+    process.stderr.write(`graph-affected: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  const depth = Number(flags.depth) > 0 ? Number(flags.depth) : 2;
+  const kinds = flags.kind && flags.kind !== true ? new Set(String(flags.kind).split(",")) : null;
+
+  const seeds = findByName(graph, name);
+  if (seeds.length === 0) {
+    if (flags.json === true) {
+      process.stdout.write(
+        JSON.stringify({ symbol: name, seeds: [], affected: [] }, null, 2) + "\n",
+      );
+    } else {
+      process.stdout.write(`no node named '${name}'\n`);
+    }
+    return;
+  }
+
+  const hits = affected({ graph, seeds, depth, kinds });
+
+  if (flags.json === true) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          symbol: name,
+          seeds: seeds.map((s) => s.id),
+          affected: hits.map((h) => ({
+            id: h.id,
+            dist: h.dist,
+            edgeKind: h.kind,
+            path: h.node?.path || null,
+          })),
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  process.stdout.write(`# affected by ${name}\n\n`);
+  for (const seed of seeds) {
+    process.stdout.write(`* ${seed.name} (${seed.symbolKind || seed.kind}) ${seed.path || "-"}\n`);
+  }
+  process.stdout.write("\n");
+  const files = new Set();
+  for (const hit of hits) {
+    if (hit.node?.path) files.add(hit.node.path);
+    process.stdout.write(
+      `${" ".repeat(hit.dist)}- ${hit.node?.name || hit.id} [${hit.kind}] ${hit.node?.path || "-"}\n`,
+    );
+  }
+  process.stdout.write(`\n${hits.length} dependents across ${files.size} files\n`);
+}
+
+if (process.argv[1] && process.argv[1].endsWith("graph-affected.mjs")) main();