create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/landing/radar.js

@@ -0,0 +1,489 @@
+'use strict';
+// WP-2 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §5 D-7, D-8, D-9 Tier B,
+// §6.3 `radar/` + `claims/`, §8 WP-2, §10 T-5): the ADVISORY pairwise conflict radar for the CLI.
+//
+// Three properties, in order of importance:
+//
+//  1. The radar never blocks. No verb here refuses a job, edits a file, or takes a lock. It returns
+//     levels; the caller decides nothing on their basis.
+//  2. The radar never writes into a session worktree. Every git child is `--no-optional-locks`
+//     (git.js), pair results go to `$(git-common-dir)/landing/radar/`, and the only worktree-side
+//     operation at all is the D-7 dirty-worktree snapshot, which goes through a TEMP index
+//     (`git.js#snapshotCommit`) so the real index and its lock are untouched.
+//  3. The radar is incremental. A pair's level is a pure function of (tipA, tipB, configHash), so it
+//     is cached per sha pair; a sweep recomputes only the pairs whose tips moved. Snapshot commits
+//     are deterministic for the same reason (D-7: "a sweep recomputes only pairs whose tip changed").
+//
+// Levels (§5 D-7 / §8 AC-2b):
+//   L3  `git merge-tree` reports a textual conflict
+//   L2  a file changed on both sides has the SAME non-empty -U0 hunk header context on both sides
+//       (git's own funcname, so `diff.*.xfuncname` drivers apply — language-independent, D-9 Tier B),
+//       or a common file matches a `landing.registries` glob (D-9 Tier B class)
+//   L1  the two sides changed at least one file in common
+//   L0  nothing in common
+//   `L1*` is L0 plus a live soft claim (§5 D-7): advisory, transient, never cached.
+//   `unknown` — `cacheOnly` asked about a pair that has never been computed.
+//
+// The `ledger` flag on an L3 pair says the conflict is machine-mergeable in principle: every
+// conflicted path is either driver-backed (`.gitattributes` `merge=<driver>`) or owned by a
+// `landing.regenerate[]` entry. It is a label, never an action — D-8 is what acts on it, and this
+// module never runs a driver or a regenerate command.
+//
+// Sync by design (§11 Risks): the `land` CLI is a synchronous, one-shot process, so every probe here
+// is synchronous and nothing is left running when the verb returns.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { CONTRACT, landingDir, readJsonSafe, writeJsonAtomic } = require('./state');
+const { globMatch, worktreeList, mergeBase, changedFilesBetween, hunkHeaders } = require('./train');
+const { landingError, runGitRaw, mergeTree, revParseOrNull, snapshotCommit } = require('./git');
+
+// §5 D-7: the CLI scope is "all named-branch worktrees, capped at 64 by recency of tip commit".
+const MAX_BRANCHES = 64;
+// Levels, ordered. `unknown` is not a level — it is "this sweep did not look".
+const LEVELS = Object.freeze(['L0', 'L1', 'L1*', 'L2', 'L3']);
+const CLAIM_DEFAULT_TTL_HOURS = 4;
+
+function levelRank(level) {
+  if (level === 'unknown') return -1;
+  const index = LEVELS.indexOf(level);
+  return index === -1 ? 0 : index;
+}
+
+// --- config ------------------------------------------------------------------------------------
+
+function registryPatterns(config) {
+  return config && Array.isArray(config.registries) ? config.registries : [];
+}
+
+function regenerateEntries(config) {
+  return config && Array.isArray(config.regenerate) ? config.regenerate : [];
+}
+
+// The pair cache key's second half (§5 D-7): a cached level is reusable only while the policy that
+// produced it is unchanged. Only the two keys the radar reads are hashed, so an unrelated policy
+// edit (a gate, the target) does not invalidate every pair.
+function configHash(config) {
+  return crypto.createHash('sha256').update(JSON.stringify({
+    registries: registryPatterns(config),
+    regenerate: regenerateEntries(config),
+  })).digest('hex');
+}
+
+// `landing.regenerate[].paths` (D-8) and `landing.registries[]` (D-9 Tier B) are both git-style
+// globs; `globMatch` is train.js's one implementation of them.
+function matchesAny(patterns, file) {
+  return patterns.some((pattern) => globMatch(pattern, file));
+}
+
+function ownedByRegenerate(config, file) {
+  return regenerateEntries(config).some((entry) => Array.isArray(entry.paths) && entry.paths.some((pattern) => globMatch(pattern, file)));
+}
+
+// `.gitattributes` `merge=<driver>`: `git check-attr` reports `unspecified` when nothing is set and
+// `unset` for a negative pattern. Anything else names a driver, so git — not the queue — owns the
+// merge of that path (D-8).
+function driverBacked(cwd, file) {
+  const res = runGitRaw(cwd, ['check-attr', 'merge', '--', file]);
+  if (res.status !== 0) return false;
+  const match = /merge:\s*(.*)$/m.exec(res.stdout);
+  if (!match) return false;
+  const value = match[1].trim();
+  return value !== '' && value !== 'unspecified' && value !== 'unset';
+}
+
+// --- levels ------------------------------------------------------------------------------------
+
+// "the text after the second `@@`" of a `git diff -U0` hunk header — git's funcname context. An
+// empty one carries no information and is never a match (`@@ -1 +1 @@`).
+function hunkContext(header) {
+  const parts = String(header).split('@@');
+  if (parts.length < 3) return null;
+  const context = parts[2].trim();
+  return context || null;
+}
+
+// D-9 Tier B: both sides moved a hunk inside the SAME funcname context, which is git's own,
+// language-independent "same region" signal (it honours `diff.*.xfuncname`).
+function sharesHunkContext(cwd, base, a, b, files) {
+  for (const file of files) {
+    const left = new Set();
+    for (const header of hunkHeaders(cwd, base, a, file)) {
+      const context = hunkContext(header);
+      if (context) left.add(context);
+    }
+    if (!left.size) continue;
+    for (const header of hunkHeaders(cwd, base, b, file)) {
+      const context = hunkContext(header);
+      if (context && left.has(context)) return true;
+    }
+  }
+  return false;
+}
+
+// `{ level, files, conflicts, ledger, registry }` for two commits (§5 D-7). Exactly ONE merge-tree
+// spawn (and one merge-base spawn) — the sweep counts them, so this must stay a single call each.
+function pairLevel(cwd, a, b, opts = {}) {
+  const config = opts.config || {};
+  const base = mergeBase(cwd, a, b);
+  // No merge base (unrelated histories) means no common ancestor to diff from; `files` stays empty
+  // and the merge-tree probe below still decides the level.
+  const files = base === null ? [] : intersection(changedFilesBetween(cwd, base, a), changedFilesBetween(cwd, base, b)).sort();
+
+  const merged = mergeTree(cwd, a, b);
+  let level;
+  let conflicts = [];
+  let ledger = false;
+  if (merged.conflicts.length) {
+    level = 'L3';
+    conflicts = merged.conflicts.slice().sort();
+    // Machine-mergeable in principle: a `.gitattributes` driver, or a `landing.regenerate[]` owner.
+    // (A driver attribute is set but its `merge.<driver>.driver` command may be missing or failing —
+    // that is exactly the case merge-tree still reports, and exactly what the flag is for.)
+    ledger = conflicts.every((file) => driverBacked(cwd, file) || ownedByRegenerate(config, file));
+  } else if (sharesHunkContext(cwd, base, a, b, files)) {
+    level = 'L2';
+  } else if (files.length) {
+    level = 'L1';
+  } else {
+    level = 'L0';
+  }
+
+  // `matchesAny` takes ONE path, so it must be applied per file: passing the array would coerce it to
+  // the comma-joined string and miss every registry path but the accidental whole-string match.
+  const registry = files.some((file) => matchesAny(registryPatterns(config), file));
+  // §5 D-9 Tier B: a shared registry path (routes, migrations, flags, protocol tables) is a
+  // collision class of its own and is flagged at least L2 even when the hunks do not line up.
+  if (registry && levelRank(level) < levelRank('L2')) level = 'L2';
+
+  return { level, files, conflicts, ledger, registry };
+}
+
+function intersection(left, right) {
+  const set = new Set(right);
+  return left.filter((file) => set.has(file));
+}
+
+// --- cache (§6.3 `radar/<tipA>-<tipB>.json`) ---------------------------------------------------
+
+function radarDir(cwd) {
+  return path.join(landingDir(cwd), 'radar');
+}
+
+function cacheFileFor(cwd, tipA, tipB) {
+  const [low, high] = tipA < tipB ? [tipA, tipB] : [tipB, tipA];
+  return path.join(radarDir(cwd), `${low}-${high}.json`);
+}
+
+// A record is reusable only when it was written by this contract, for these two tips, under this
+// exact policy. Anything else is a miss, never a guess.
+function readCachedPair(cwd, tipA, tipB, hash) {
+  const record = readJsonSafe(cacheFileFor(cwd, tipA, tipB));
+  if (!record || typeof record !== 'object') return null;
+  if (record.contract !== CONTRACT || record.configHash !== hash) return null;
+  if (typeof record.level !== 'string') return null;
+  return {
+    level: record.level,
+    files: Array.isArray(record.files) ? record.files : [],
+    conflicts: Array.isArray(record.conflicts) ? record.conflicts : [],
+    ledger: record.ledger === true,
+    registry: record.registry === true,
+  };
+}
+
+function writeCachedPair(cwd, tipA, tipB, hash, result) {
+  const [low, high] = tipA < tipB ? [tipA, tipB] : [tipB, tipA];
+  writeJsonAtomic(cacheFileFor(cwd, tipA, tipB), {
+    contract: CONTRACT,
+    a: low,
+    b: high,
+    level: result.level,
+    files: result.files,
+    conflicts: result.conflicts,
+    ledger: result.ledger,
+    registry: result.registry,
+    configHash: hash,
+    at: new Date().toISOString(),
+  });
+}
+
+// --- claims (§6.3 `claims/<session>.json`, §5 D-7 soft claims) ----------------------------------
+
+function claimsDir(cwd) {
+  return path.join(landingDir(cwd), 'claims');
+}
+
+// Live claims only. `until <= now` is expired; an unparseable `until` is expired too (a claim with
+// no readable expiry must never warn forever). A claim never blocks anything — it only ever adds an
+// `L1*` warning to a pair that is otherwise clean.
+function loadClaims(cwd, nowIso) {
+  let names;
+  try {
+    names = fs.readdirSync(claimsDir(cwd));
+  } catch (error) {
+    /* expected: no claim has ever been recorded in this repository (or the directory was pruned) —
+       "no claims" is exactly the empty list */
+    return [];
+  }
+  const now = Date.parse(nowIso);
+  const claims = [];
+  for (const name of names.slice().sort()) {
+    if (!name.endsWith('.json')) continue;
+    const record = readJsonSafe(path.join(claimsDir(cwd), name));
+    if (!record || typeof record !== 'object' || record.contract !== CONTRACT) continue;
+    if (typeof record.session !== 'string' || !record.session) continue;
+    if (typeof record.branch !== 'string' || !record.branch) continue;
+    if (!Array.isArray(record.paths) || !record.paths.length || !record.paths.every((entry) => typeof entry === 'string')) continue;
+    const until = Date.parse(record.until);
+    if (!Number.isFinite(until) || until <= now) continue;
+    claims.push({ session: record.session, branch: record.branch, paths: record.paths.slice(), until: record.until });
+  }
+  return claims;
+}
+
+// §5 D-7: a claim by the session owning one side warns the other side when it names a path that side
+// changed since the merge base. `claims` entries are `{ session, paths }`.
+function claimsForPair(cwd, base, pair, claims) {
+  const found = [];
+  // One changed-file list per side, computed at most once per pair and only if a claim names it.
+  const changed = new Map();
+  const changedOn = (side) => {
+    if (!changed.has(side.branch)) changed.set(side.branch, changedFilesBetween(cwd, base, side.tip));
+    return changed.get(side.branch);
+  };
+  for (const claim of claims) {
+    const other = claim.branch === pair.a.branch ? pair.b : (claim.branch === pair.b.branch ? pair.a : null);
+    if (!other) continue;
+    const files = changedOn(other);
+    if (!files.length) continue;
+    const matched = claim.paths.filter((pattern) => files.some((file) => globMatch(pattern, file)));
+    if (!matched.length) continue;
+    found.push({ session: claim.session, paths: matched });
+  }
+  return found;
+}
+
+// --- scope (§5 D-7: every worktree on a named branch other than the target) ---------------------
+
+// `git --no-optional-locks status --porcelain`: tracked changes or untracked-not-ignored files. A
+// worktree with uncommitted work is probed as a snapshot commit, so the radar sees it as it is now.
+function worktreeDirty(worktree) {
+  if (!worktree) return false;
+  let res;
+  try {
+    res = runGitRaw(worktree, ['status', '--porcelain']);
+  } catch (error) {
+    /* expected: the worktree directory vanished between `worktree list --porcelain` and this probe
+       (a session removed its worktree) — a directory that is gone holds no uncommitted work, so it
+       is not dirty and the branch's committed tip is used */
+    return false;
+  }
+  return res.status === 0 && res.stdout.trim() !== '';
+}
+
+// One entry per named-branch worktree other than the target, most recent tip first, capped at
+// MAX_BRANCHES. Bare and prunable worktrees are skipped: neither has a directory the dirty probe
+// could read, and a prunable path is by definition gone. Returns `{ branches, truncated }` where
+// `truncated` is how many worktrees the cap dropped, so a caller can say the scope was cut.
+//
+// `onlyBranches` (§8 WP-3, `land status --radar-for`) is applied HERE, before the dirty probe and
+// therefore before any snapshot commit: a worktree the caller did not name is never even read, so a
+// CTM sweep restricted to live sessions' branches cannot spend a snapshot on a stranger's checkout.
+function scopeBranches(cwd, target, onlyBranches = null) {
+  const entries = worktreeList(cwd);
+  const branches = [];
+  for (const entry of entries) {
+    if (!entry.branch || !entry.branch.startsWith('refs/heads/')) continue;
+    if (entry.bare || entry.prunable) continue;
+    const branch = entry.branch.slice('refs/heads/'.length);
+    if (branch === target) continue;
+    if (onlyBranches && !onlyBranches.has(branch)) continue;
+    const tip = revParseOrNull(cwd, entry.branch);
+    if (!tip) continue;
+    const dirty = worktreeDirty(entry.path);
+    branches.push({
+      branch,
+      worktree: entry.path,
+      tip,
+      dirty,
+      snapshot: false,
+      committerDate: commitCommitterDate(cwd, tip),
+    });
+  }
+  branches.sort((left, right) => (left.committerDate < right.committerDate ? 1 : left.committerDate > right.committerDate ? -1 : left.branch.localeCompare(right.branch)));
+  const scoped = branches.slice(0, MAX_BRANCHES);
+  for (const entry of scoped) {
+    if (!entry.dirty) continue;
+    // Deterministic by construction (git.js#snapshotCommit), so an unchanged dirty worktree keeps
+    // its cache key across sweeps (D-7).
+    entry.tip = snapshotCommit(entry.worktree, { deterministic: true });
+    entry.snapshot = true;
+  }
+  return { branches: scoped, truncated: branches.length - scoped.length };
+}
+
+function commitCommitterDate(cwd, tip) {
+  const res = runGitRaw(cwd, ['show', '-s', '--format=%cI', tip]);
+  return res.status === 0 ? res.stdout.trim() : '';
+}
+
+// Every unordered branch pair, plus every branch against the target (§5 D-7). A cross pair is laid
+// out in branch-name order so `a`/`b` do not depend on the tips' committer dates; a target pair is
+// always `<branch> × <target>`, which is how the CLI line reads.
+function buildPairs(branches, targetTip, targetName) {
+  const pairs = [];
+  for (let index = 0; index < branches.length; index += 1) {
+    for (let other = index + 1; other < branches.length; other += 1) {
+      const [a, b] = branches[index].branch < branches[other].branch
+        ? [branches[index], branches[other]]
+        : [branches[other], branches[index]];
+      pairs.push({ a, b });
+    }
+    pairs.push({
+      a: branches[index],
+      b: { branch: targetName, worktree: null, tip: targetTip, dirty: false, snapshot: false },
+    });
+  }
+  return pairs;
+}
+
+// --- sweep (§5 D-7, §8 AC-2a/AC-2d) ------------------------------------------------------------
+
+// The whole radar in one call: scope, pair levels (cached / computed / unknown), soft claims and the
+// spawn counters the tests assert on. `cacheOnly` is what makes `land status` cheap: uncached pairs
+// come back `level: 'unknown'` and no merge-tree (or diff, or merge-base) is spawned for them.
+//
+// Claims are applied to pairs whose level is KNOWN, only when `cacheOnly` is false, and only when a
+// live claim names one of the pair's two branches — judging a claim needs the changed-file list of the
+// warned side, which costs a merge-base and a diff, and `cacheOnly` promises no such spawn. A cached
+// pair therefore reports the level it was computed with, never an `L1*` derived on the fly; and a
+// sweep with no claims spawns no merge base for any cached pair (`stats.mergeBaseSpawns` stays 0).
+function sweep(cwd, opts = {}) {
+  const config = opts.config || {};
+  const target = config.target;
+  if (typeof target !== 'string' || !target) {
+    throw landingError('config_invalid', 'radar.sweep needs config.target (the branch work lands on)', { cwd });
+  }
+  const targetTip = revParseOrNull(cwd, `refs/heads/${target}`);
+  if (!targetTip) {
+    throw landingError('target_missing', `target branch ${JSON.stringify(target)} does not exist`, { target, cwd });
+  }
+  const hash = configHash(config);
+  // §8 WP-3: `opts.onlyBranches` (the CTM probe / `land status --radar-for`) restricts the swept
+  // branches to the listed names. The filter is applied in scopeBranches BEFORE any dirty probe, so
+  // an un-listed worktree is not snapshotted at all; every listed branch still gets its target pair.
+  // An EMPTY list is a real restriction ("sweep no branch"), never "no restriction": a caller that
+  // wants every branch simply omits the option. Getting this backwards would turn a probe with no
+  // live branches into a full-repo snapshot sweep.
+  const only = Array.isArray(opts.onlyBranches)
+    ? new Set(opts.onlyBranches.filter((branch) => typeof branch === 'string' && branch))
+    : null;
+  const scope = scopeBranches(cwd, target, only);
+  const branches = scope.branches;
+  let pairs = buildPairs(branches, targetTip, target);
+  if (typeof opts.withBranch === 'string' && opts.withBranch) {
+    pairs = pairs.filter((pair) => pair.a.branch === opts.withBranch || pair.b.branch === opts.withBranch);
+  }
+  const claims = opts.cacheOnly ? [] : loadClaims(cwd, typeof opts.claimsNow === 'string' && opts.claimsNow ? opts.claimsNow : new Date().toISOString());
+  // Claims are keyed by branch, so a pair can only be affected when a claim names one of its two
+  // branches. Precomputed once: with no claims at all (the common case) no pair ever needs a merge
+  // base, which is what keeps a fully cached sweep at ZERO merge-base spawns (D-7 incrementality).
+  const claimBranches = new Set(claims.map((claim) => claim.branch));
+
+  const stats = { pairs: pairs.length, computed: 0, cached: 0, mergeTreeSpawns: 0, mergeBaseSpawns: 0, truncated: scope.truncated };
+  const results = [];
+  for (const pair of pairs) {
+    let result;
+    let cached = false;
+    const hit = readCachedPair(cwd, pair.a.tip, pair.b.tip, hash);
+    if (hit) {
+      result = hit;
+      cached = true;
+      stats.cached += 1;
+    } else if (opts.cacheOnly) {
+      result = { level: 'unknown', files: [], conflicts: [], ledger: false, registry: false };
+    } else {
+      result = pairLevel(cwd, pair.a.tip, pair.b.tip, { config });
+      // pairLevel spawns exactly one merge-base and exactly one merge-tree; the counters are what the
+      // incremental-recompute acceptance criteria assert on (never seconds: §10 T-5).
+      stats.mergeBaseSpawns += 1;
+      stats.mergeTreeSpawns += 1;
+      stats.computed += 1;
+      writeCachedPair(cwd, pair.a.tip, pair.b.tip, hash, result);
+    }
+    let level = result.level;
+    let pairClaims = [];
+    // A claim can only name this pair when one of the pair's branches owns it; with no claim on
+    // either side there is nothing to compare, so neither the merge base nor the diff is spawned. On a
+    // fully cached sweep with no claims this is what keeps `mergeBaseSpawns` at 0 (D-7 incrementality).
+    if (!opts.cacheOnly && level !== 'unknown' && (claimBranches.has(pair.a.branch) || claimBranches.has(pair.b.branch))) {
+      stats.mergeBaseSpawns += 1;
+      const base = mergeBase(cwd, pair.a.tip, pair.b.tip);
+      // No merge base means the two sides share nothing, so no claim can name their disagreement.
+      pairClaims = base === null ? [] : claimsForPair(cwd, base, pair, claims);
+      // §5 D-7: claims only ever lift a clean pair to `L1*` — never above, never below.
+      if (pairClaims.length && level === 'L0') level = 'L1*';
+    }
+    results.push({
+      a: pair.a.branch,
+      b: pair.b.branch,
+      level,
+      files: result.files,
+      conflicts: result.conflicts,
+      ledger: result.ledger,
+      registry: result.registry,
+      claims: pairClaims,
+      cached,
+    });
+  }
+
+  return {
+    contract: CONTRACT,
+    target,
+    targetTip,
+    branches: branches.map((entry) => ({
+      branch: entry.branch,
+      worktree: entry.worktree,
+      tip: entry.tip,
+      dirty: entry.dirty,
+      snapshot: entry.snapshot,
+    })),
+    pairs: results,
+    stats,
+  };
+}
+
+// The `land status` / `land conflicts` one-line summaries: the worst known level, how many pairs are
+// at or above L2, and how many were never computed.
+function summarize(pairs) {
+  let max = null;
+  let atLeastL2 = 0;
+  let unknown = 0;
+  for (const pair of pairs) {
+    if (pair.level === 'unknown') {
+      unknown += 1;
+      continue;
+    }
+    if (levelRank(pair.level) >= levelRank('L2')) atLeastL2 += 1;
+    if (max === null || levelRank(pair.level) > levelRank(max)) max = pair.level;
+  }
+  return { max: max === null ? (unknown ? 'unknown' : 'L0') : max, atLeastL2, unknown };
+}
+
+module.exports = {
+  MAX_BRANCHES,
+  LEVELS,
+  CLAIM_DEFAULT_TTL_HOURS,
+  levelRank,
+  configHash,
+  hunkContext,
+  pairLevel,
+  radarDir,
+  claimsDir,
+  cacheFileFor,
+  loadClaims,
+  summarize,
+  sweep,
+};