@azure-id/orc 1.7.1 → 1.8.1

package/bin/graph-resolve.js

@@ -0,0 +1,178 @@
+"use strict";
+// ── orc graph — the RESOLUTION CACHE (v1.8.0 EW2) ───────────────────────────
+//
+// W3 decided "resolution is computed on read, never stored". That was right for
+// correctness and wrong for cost: on django/django ONE file card spent 437 ms
+// working out who calls what, and `impact` up to 520 ms — every single time.
+//
+// EW2 measured what is worth storing, and the answer is narrower than the plan
+// assumed. Two things were built, measured, and thrown away:
+//
+//   · the resolver's whole MEMO — 21.7 MB, ~120 ms to read and parse, to save
+//     less than that. A net loss. Not stored.
+//   · CLOSURE REPAIR (re-resolve only the changed file and its dependents) —
+//     measured 2,669 ms against 2,695 ms for a plain full re-resolve on the
+//     same one-line edit. **One percent.** On a JSON store the fixed costs
+//     (change detection, loading the index, and rewriting the whole file) drown
+//     the resolve, so an incremental resolve cannot pay. It was three
+//     correctness bugs deep by the time the numbers came in, so it is gone.
+//
+// What IS stored is the REVERSE direction — who calls this symbol — which is
+// the half the 437 ms walk was computing. 13 MB on django/django, and it turns
+// a file card into 458 ms from 727 ms, and `impact` into 397 ms from 631 ms.
+//
+// The rules that keep W3's correctness:
+//
+//   1. `index.json` is still the only SOURCE. `resolved.json` is DERIVED, and
+//      throwing it away costs speed and nothing else.
+//   2. Only `update` writes it, inside the same lock. A reader never writes, so
+//      readers stay lock-free.
+//   3. A reader uses it ONLY when `resolved.generation === meta.generation`.
+//      Any other answer — a crash between two writes, an older engine, a hand
+//      deletion — falls back to computing on read. Stale is impossible: it is
+//      not "probably fine", it is not used at all.
+//   4. A cached answer must be BYTE-IDENTICAL to a computed one, order
+//      included. `test/cli/graph-resolve.test.js` drives a seeded random edit
+//      script and compares the two after every step.
+//
+// WHAT IS STORED
+//
+//   callers target symbol id → the confident callers of it, as
+//           `[caller symbol id, line, state, ref]`.
+//   maybe   target symbol id → how many AMBIGUOUS calls list this target, by
+//           CALLER FILE. Per file, not per call site: 5 MB on django/django
+//           instead of 45 MB, and the card only ever shows the total.
+
+const fs = require("fs");
+const path = require("path");
+const G = require("./graph.js");
+
+const RESOLVE_SCHEMA = 2;
+const CONFIDENT = new Set(["LOCAL", "IMPORT", "UNIQUE"]);
+const NAMES_PER_KEY = 5;
+
+function resolvedPath(claudeDir) {
+  return path.join(G.graphPaths(claudeDir).dir, "resolved.json");
+}
+function namesPath(claudeDir) {
+  return path.join(G.graphPaths(claudeDir).dir, "names.json");
+}
+
+// Every map here is keyed by data from the repository — a bare symbol name can
+// be `constructor`, `toString` or `__proto__`. A plain object would hand back
+// `Object.prototype`'s member instead of "nothing here", so maps are built with
+// a null prototype and read through this.
+function own(o, k) {
+  return o && Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined;
+}
+const bare = () => Object.create(null);
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+// ── build ───────────────────────────────────────────────────────────────────
+// Called by `graphUpdate` INSIDE the lock, after index.json is on disk. It
+// never throws into the update: a cache that cannot be written is a slower
+// graph, not a broken one.
+function build(claudeDir, root) {
+  const t0 = Date.now();
+  const Q = require("./graph-query.js");
+  try {
+    // `noCache` matters: the writer must COMPUTE, never read back the cache it
+    // is about to replace.
+    const model = Q.loadModel(claudeDir, root, { noCache: true });
+    if (!model) return { route: "skipped", reason: "no-index", ms: Date.now() - t0 };
+
+    const callers = bare();
+    const maybe = bare();
+    for (const [rel, f] of Object.entries(model.byFile)) {
+      for (const s of f.symbols || []) {
+        s.file = rel;
+        for (const c of s.calls || []) {
+          const r = Q.resolveCall(model, rel, s, c);
+          if (r.target && CONFIDENT.has(r.state)) {
+            (own(callers, r.target) || (callers[r.target] = [])).push([s.id, c.line, r.state, c.ref ? 1 : 0]);
+          } else if (r.state === "AMBIGUOUS") {
+            for (const cand of r.candidates || []) {
+              const m = own(maybe, cand) || (maybe[cand] = bare());
+              m[rel] = (own(m, rel) || 0) + 1;
+            }
+          }
+        }
+      }
+    }
+
+    // One stable order, so the same tree always produces the same bytes.
+    const out = {
+      schema: RESOLVE_SCHEMA,
+      engine: G.ENGINE,
+      generation: model.meta.generation,
+      gen_id: model.meta.gen_id,
+      callers: sortedRows(callers),
+      maybe: sortedCounts(maybe),
+    };
+    G.atomicWrite(resolvedPath(claudeDir), JSON.stringify(out));
+    writeNames(claudeDir, model, out.callers);
+    return { route: "full", ms: Date.now() - t0 };
+  } catch (e) {
+    // A cache is an optimisation. Losing it must never lose the update — and a
+    // HALF-written one must never be read, so it goes.
+    try {
+      fs.rmSync(resolvedPath(claudeDir), { force: true });
+      fs.rmSync(namesPath(claudeDir), { force: true });
+    } catch (_) {}
+    return { route: "failed", reason: String((e && e.message) || e), ms: Date.now() - t0 };
+  }
+}
+
+function sortedObject(o) {
+  const out = bare();
+  for (const k of Object.keys(o).sort()) out[k] = o[k];
+  return out;
+}
+function sortedRows(o) {
+  const out = bare();
+  for (const k of Object.keys(o).sort()) {
+    out[k] = o[k].slice().sort((a, b) => String(a[0]).localeCompare(String(b[0])) || a[1] - b[1]);
+  }
+  return out;
+}
+// target → [[caller file, count], …], both levels in a stable order.
+function sortedCounts(o) {
+  const out = bare();
+  for (const k of Object.keys(o).sort()) out[k] = Object.keys(o[k]).sort().map((f) => [f, o[k][f]]);
+  return out;
+}
+
+// ── names.json ──────────────────────────────────────────────────────────────
+// A bare name → the few symbols worth showing for it. This is the ONLY file a
+// delivery hook is allowed to read: a name lookup, no index parse, no resolve.
+function writeNames(claudeDir, model, callers) {
+  const out = bare();
+  for (const [name, syms] of model.byName) {
+    const rows = syms
+      .map((s) => ({ s, fan: (own(callers, s.id) || []).length }))
+      .sort((a, b) => b.fan - a.fan || a.s.file.localeCompare(b.s.file))
+      .slice(0, NAMES_PER_KEY)
+      .map(({ s, fan }) => [s.qname, s.kind, s.file, s.lines[0], s.lines[1], fan]);
+    if (rows.length) out[name] = rows;
+  }
+  G.atomicWrite(namesPath(claudeDir), JSON.stringify({ schema: RESOLVE_SCHEMA, generation: model.meta.generation, names: sortedObject(out) }));
+}
+
+// ── read ────────────────────────────────────────────────────────────────────
+// Used ONLY when the generation matches. Anything else returns null and the
+// reader computes, exactly as it did before this file existed.
+function load(claudeDir, meta) {
+  const r = readJson(resolvedPath(claudeDir));
+  if (!r || r.schema !== RESOLVE_SCHEMA || r.engine !== G.ENGINE) return null;
+  if (!meta || !meta.generation || r.generation !== meta.generation) return null;
+  return r;
+}
+
+module.exports = { own, RESOLVE_SCHEMA, resolvedPath, namesPath, build, load };

package/bin/graph-signals.js

@@ -0,0 +1,277 @@
+"use strict";
+// ── orc graph — CHEAP SIGNALS for planners and reviewers (v1.8.0 EW5) ───────
+//
+// Four answers that cost NO model tokens, because every one of them is already
+// on disk: git's own history, and the index the parser already built.
+//
+//   changes    what this diff actually touched, who calls it, and how risky
+//              that is. A reviewer asking `impact` on the DECLARED files gets
+//              the whole file; this gets the symbols the HUNKS overlap.
+//   importance one number per symbol, so a card's rows are ordered by what
+//              matters instead of by raw fan-in. A helper called from forty
+//              places is not more important than the exported entry point.
+//   tests      the test files that reach a symbol — by CALL (the graph) and by
+//              NAME (`x.test.js` beside `x.js`). Both, because a test that
+//              imports a module without naming a symbol is still its test.
+//   cochange   the files that historically change together with this one. The
+//              planner's question "what else will I have to touch" is answered
+//              by history far better than by static edges.
+//
+// THE RULE THAT SHAPES ALL FOUR: a signal is a HINT with its evidence attached.
+// `changes` says WHY a symbol is high risk (exported, fan-in 4, no test caller),
+// never just "high". A number nobody can check is a number nobody should act on.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const G = require("./graph.js");
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+// A merge or a sweeping rename touches hundreds of files and would make every
+// pair look related. CBM's threshold, and the same reason: a commit that broad
+// carries no information about which two files belong together.
+const COCHANGE_MAX_FILES = 20;
+const COCHANGE_MIN = 3;
+const COCHANGE_SINCE = "6.months";
+const COCHANGE_ROWS = 12;
+
+function git(root, args) {
+  return spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: GIT_MAX_BUFFER });
+}
+
+const norm = (p) => String(p).split("\\").join("/").replace(/^\.\//, "");
+
+// ── importance ──────────────────────────────────────────────────────────────
+// sqrt of the confident in-edges, then knocked down by an order of magnitude for
+// each thing that makes a symbol less likely to be what you are looking for.
+// The square root matters: a symbol with 100 callers is not ten times more
+// important than one with 10, it is a utility.
+function importance(model, sym, fanIn) {
+  let v = Math.sqrt(Math.max(0, fanIn));
+  if (!sym.exported) v *= 0.1;
+  // A name defined in five or more files is a convention (`handler`, `index`,
+  // `run`), not a landmark.
+  const sameName = (model.byName.get(sym.name) || []).length;
+  if (sameName >= 5) v *= 0.1;
+  if (require("./graph-query.js").TEST_FILE.test(sym.file)) v *= 0.1;
+  return Math.round(v * 1000) / 1000;
+}
+
+// ── tests ───────────────────────────────────────────────────────────────────
+// The naming half. `src/order.js` is tested by `order.test.js`, `test_order.py`,
+// `order_test.go`, `OrderTest.java` — wherever they live.
+function testsByName(model, rel) {
+  const base = path.posix.basename(rel).replace(/\.[^.]+$/, "");
+  if (!base) return [];
+  const want = new Set([
+    `${base}.test`,
+    `${base}.spec`,
+    `test_${base}`,
+    `${base}_test`,
+    `${base}Test`,
+    `${base}Tests`,
+  ]);
+  const out = [];
+  for (const f of model.fileSet) {
+    if (f === rel) continue;
+    const stem = path.posix.basename(f).replace(/\.[^.]+$/, "");
+    if (want.has(stem)) out.push(f);
+  }
+  return out.sort();
+}
+
+// ── changes ─────────────────────────────────────────────────────────────────
+// exit 0 answered · 1 no graph or not a git repository
+//
+// `git diff -U0` gives the hunks. A symbol whose line range overlaps a hunk was
+// really touched; a symbol elsewhere in the same file was not, and saying it was
+// is what makes a whole-file `impact` noisy at review time.
+function parseDiff(text) {
+  const byFile = new Map();
+  let cur = null;
+  for (const line of String(text).split("\n")) {
+    const f = /^\+\+\+ b\/(.*)$/.exec(line);
+    if (f) {
+      cur = f[1] === "/dev/null" ? null : norm(f[1]);
+      if (cur && !byFile.has(cur)) byFile.set(cur, []);
+      continue;
+    }
+    if (!cur) continue;
+    const h = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (h) {
+      const start = Number(h[1]);
+      const count = h[2] === undefined ? 1 : Number(h[2]);
+      // A pure deletion has a zero-length new side; it still touched the line it
+      // was removed from, so record it as a one-line hunk there.
+      byFile.get(cur).push(count === 0 ? [start, start] : [start, start + count - 1]);
+    }
+  }
+  return byFile;
+}
+
+// The paths this diff touches, by name only — two cheap git calls, no parsing.
+// `changes` is a REVIEW-time command, so it heals on these before it answers:
+// a reviewer told "nothing depends on this" by a stale index is worse served
+// than one told nothing at all.
+function changedPaths(root, base) {
+  const out = [];
+  const d = git(root, base ? ["diff", "--name-only", "-z", base, "--"] : ["diff", "--name-only", "-z", "HEAD", "--"]);
+  if (d.status === 0) for (const f of d.stdout.split("\0")) if (f) out.push(norm(f));
+  const u = git(root, ["ls-files", "--others", "--exclude-standard", "-z"]);
+  if (u.status === 0) for (const f of u.stdout.split("\0")) if (f) out.push(norm(f));
+  return [...new Set(out)];
+}
+
+function graphChanges(claudeDir, root, opts) {
+  const Q = require("./graph-query.js");
+  const model = Q.loadModel(claudeDir, root);
+  if (!model) return { ok: false, state: "none", reason: "no-index", exit: 1 };
+  const base = opts.base || null;
+  const d = git(root, base ? ["diff", "-U0", base, "--"] : ["diff", "-U0", "HEAD", "--"]);
+  if (d.error || d.status !== 0) return { ok: false, state: "unavailable", reason: "git-diff-failed", exit: 1 };
+  const hunks = parseDiff(d.stdout);
+
+  // An untracked file is a change too, and `git diff` never mentions it. Its
+  // whole body is the hunk.
+  const un = git(root, ["ls-files", "--others", "--exclude-standard", "-z"]);
+  if (un.status === 0) {
+    for (const rel of un.stdout.split("\0")) {
+      if (!rel) continue;
+      const r = norm(rel);
+      if (!hunks.has(r)) hunks.set(r, [[1, Number.MAX_SAFE_INTEGER]]);
+    }
+  }
+
+  const rows = [];
+  const files = [...hunks.keys()].filter((f) => model.fileSet.has(f)).sort();
+  const indexable = new Set(Object.keys(G.LANG_BY_EXT));
+  const absent = [...hunks.keys()]
+    .filter((f) => !model.fileSet.has(f) && indexable.has(path.posix.extname(f).toLowerCase()))
+    .sort();
+  for (const rel of files) {
+    const ranges = hunks.get(rel);
+    for (const sym of (model.byFile[rel] || {}).symbols || []) {
+      if (sym.kind === "module") continue;
+      const touched = ranges.some((h) => sym.lines[0] <= h[1] && h[0] <= sym.lines[1]);
+      if (!touched) continue;
+      const c = Q.callersOf(model, sym);
+      const callerFiles = [...new Set(c.confident.map((x) => x.sym.file))];
+      const tests = [...new Set([...callerFiles.filter((f) => Q.TEST_FILE.test(f)), ...testsByName(model, rel)])];
+      // The reason is part of the answer. "high" with nothing behind it is a
+      // number nobody can check, and nobody should act on.
+      const why = [];
+      if (sym.exported) why.push("exported");
+      why.push(`fan-in ${c.confident.length}`);
+      if (!tests.length) why.push("no test reaches it");
+      if (c.maybe) why.push(`${c.maybe} ambiguous caller(s) not counted`);
+      const risk = sym.exported && c.confident.length >= 3 && !tests.length ? "high" : sym.exported || c.confident.length >= 1 ? "medium" : "low";
+      rows.push({
+        id: sym.id,
+        qname: sym.qname,
+        kind: sym.kind,
+        file: rel,
+        lines: sym.lines,
+        exported: !!sym.exported,
+        fan_in: c.confident.length,
+        maybe_callers: c.maybe,
+        caller_files: callerFiles.sort(),
+        tests: tests.sort(),
+        risk,
+        why,
+      });
+    }
+  }
+  const order = { high: 0, medium: 1, low: 2 };
+  rows.sort((a, b) => order[a.risk] - order[b.risk] || b.fan_in - a.fan_in || a.file.localeCompare(b.file) || a.lines[0] - b.lines[0]);
+  const counts = { high: 0, medium: 0, low: 0 };
+  for (const r of rows) counts[r.risk]++;
+  return {
+    ok: true,
+    state: "found",
+    base: base || "HEAD",
+    files,
+    not_in_graph: absent,
+    symbols: rows,
+    counts,
+    generation: model.meta.generation || 0,
+    exit: 0,
+  };
+}
+
+// ── cochange ────────────────────────────────────────────────────────────────
+// exit 0 answered · 1 no graph, or git could not answer · 4 nothing reaches the
+// threshold (an ANSWER: this file changes alone)
+//
+// Cached per HEAD. History does not move under a working-tree edit, so the cache
+// is valid for exactly as long as HEAD is.
+function cochangePath(claudeDir) {
+  return path.join(G.graphPaths(claudeDir).dir, "cochange.json");
+}
+
+function buildCochange(root) {
+  const r = git(root, ["log", `--since=${COCHANGE_SINCE}`, "--name-only", "--pretty=format:%x00", "--no-merges"]);
+  if (r.error || r.status !== 0) return null;
+  const pairs = Object.create(null);
+  const total = Object.create(null);
+  for (const commit of r.stdout.split("\0")) {
+    const files = commit.split("\n").map((x) => x.trim()).filter(Boolean).map(norm);
+    const uniq = [...new Set(files)];
+    if (uniq.length < 2 || uniq.length > COCHANGE_MAX_FILES) continue;
+    for (const f of uniq) total[f] = (total[f] || 0) + 1;
+    for (let i = 0; i < uniq.length; i++) {
+      for (let j = i + 1; j < uniq.length; j++) {
+        const k = uniq[i] < uniq[j] ? `${uniq[i]}\u0000${uniq[j]}` : `${uniq[j]}\u0000${uniq[i]}`;
+        pairs[k] = (pairs[k] || 0) + 1;
+      }
+    }
+  }
+  return { pairs, total };
+}
+
+function graphCochange(claudeDir, root, opts) {
+  const rel = norm(opts.file || "");
+  if (!rel) return { ok: false, reason: "missing-operand", exit: 1 };
+  const head = git(root, ["rev-parse", "HEAD"]);
+  if (head.status !== 0) return { ok: false, state: "unavailable", reason: "not-git", exit: 1 };
+  const at = head.stdout.trim();
+
+  let cache = null;
+  try {
+    cache = JSON.parse(fs.readFileSync(cochangePath(claudeDir), "utf8"));
+  } catch (_) {}
+  if (!cache || cache.head !== at || cache.schema !== 1) {
+    const built = buildCochange(root);
+    if (!built) return { ok: false, state: "unavailable", reason: "git-log-failed", exit: 1 };
+    cache = { schema: 1, head: at, since: COCHANGE_SINCE, ...built };
+    try {
+      G.atomicWrite(cochangePath(claudeDir), JSON.stringify(cache));
+    } catch (_) {}
+  }
+
+  const rows = [];
+  const pre = rel + "\u0000";
+  const suf = "\u0000" + rel;
+  for (const [k, n] of Object.entries(cache.pairs || {})) {
+    if (n < COCHANGE_MIN) continue;
+    let other = null;
+    if (k.startsWith(pre)) other = k.slice(pre.length);
+    else if (k.endsWith(suf)) other = k.slice(0, k.length - suf.length);
+    if (!other) continue;
+    const own = (cache.total || {})[rel] || 0;
+    rows.push({ file: other, together: n, of: own, share: own ? Math.round((n / own) * 100) / 100 : 0 });
+  }
+  rows.sort((a, b) => b.together - a.together || a.file.localeCompare(b.file));
+  return {
+    ok: true,
+    state: rows.length ? "found" : "none",
+    file: rel,
+    commits: (cache.total || {})[rel] || 0,
+    since: cache.since,
+    min: COCHANGE_MIN,
+    rows: rows.slice(0, COCHANGE_ROWS),
+    more: Math.max(0, rows.length - COCHANGE_ROWS),
+    exit: rows.length ? 0 : 4,
+  };
+}
+
+module.exports = { importance, testsByName, parseDiff, changedPaths, graphChanges, graphCochange, cochangePath, COCHANGE_MIN, COCHANGE_MAX_FILES };