@codyswann/lisa 4.48.0 → 4.50.0

package/scripts/cleanup-worktrees.sh

@@ -10,7 +10,12 @@
 #      ~/.codex/worktrees, .lisa-worktrees, /tmp) OR its branch matches an
 #      agent naming pattern (claude/*, worktree-*, codex/*) OR its branch is
 #      fully merged into an environment branch (main/dev/staging).
-#   3. No modified/staged TRACKED files ("real work" is never deleted).
+#   3. Git could actually REPORT on it, and reported no modified/staged TRACKED
+#      files ("real work" is never deleted). "I looked and it was clean" and "I
+#      could not look" are different answers: a `git status` that FAILS is kept
+#      in its own bucket, never treated as clean. This mirrors the TypeScript
+#      entitlement rule (src/cli/worktree-prune-policy.ts), which blocks on
+#      `unreadable` rather than defaulting an unproven worktree to eligible.
 #   4. Its HEAD commit is reachable from some remote ref (nothing unpushed).
 #   5. It is older than --min-age-days (default 7) by directory mtime.
 #   6. Its uncommitted content is reachable from some commit — asked of the
@@ -70,7 +75,7 @@ fi
 
 NOW=$(date +%s)
 MIN_AGE_SECS=$((MIN_AGE_DAYS * 86400))
-REMOVED=0 KEPT_DIRTY=0 KEPT_UNPUSHED=0 KEPT_YOUNG=0 KEPT_UNTRACKED=0 ORPHANS=0 ERRORS=0
+REMOVED=0 KEPT_DIRTY=0 KEPT_UNPUSHED=0 KEPT_YOUNG=0 KEPT_UNTRACKED=0 KEPT_UNREADABLE=0 ORPHANS=0 ERRORS=0
 KEPT_UNREACHABLE=0
 
 # Content-reachability guard. Absent node or an unresolvable script leaves the
@@ -162,7 +167,23 @@ process_worktree() {
     return
   fi
 
-  if [ -n "$(git -C "$wt" status --porcelain --untracked-files=no 2>/dev/null)" ]; then
+  # Capture the OUTPUT and the EXIT STATUS separately. Written as
+  # `[ -n "$(git ... 2>/dev/null)" ]` — the way this and the untracked check
+  # below both used to be — a FAILED git collapses to the empty string, `-n ""`
+  # is false, and an unreadable worktree takes the same branch as a spotless
+  # one: it falls through every KEEP predicate to removal. A short/corrupt index
+  # (what a SIGKILLed git leaves behind, and the ordinary outcome of the
+  # concurrency pressure this script exists to relieve) reaches exactly that
+  # state: `git status` exits 128 while the ref queries below still answer.
+  local tracked_status tracked_rc
+  tracked_status=$(git -C "$wt" status --porcelain --untracked-files=no 2>/dev/null)
+  tracked_rc=$?
+  if [ "$tracked_rc" -ne 0 ]; then
+    KEPT_UNREADABLE=$((KEPT_UNREADABLE + 1))
+    log "KEEP (git could not report on it — unreadable, so nothing was proven)  $wt"
+    return
+  fi
+  if [ -n "$tracked_status" ]; then
     KEPT_DIRTY=$((KEPT_DIRTY + 1))
     log "KEEP (modified tracked files)  $wt"
     return
@@ -183,7 +204,15 @@ process_worktree() {
   fi
 
   local force_flag=()
-  if [ -n "$(git -C "$wt" status --porcelain 2>/dev/null)" ]; then
+  local full_status full_rc
+  full_status=$(git -C "$wt" status --porcelain 2>/dev/null)
+  full_rc=$?
+  if [ "$full_rc" -ne 0 ]; then
+    KEPT_UNREADABLE=$((KEPT_UNREADABLE + 1))
+    log "KEEP (git could not report on it — unreadable, so nothing was proven)  $wt"
+    return
+  fi
+  if [ -n "$full_status" ]; then
     if [ "$FORCE_UNTRACKED" = 1 ]; then
       force_flag=(--force)
     else
@@ -195,7 +224,12 @@ process_worktree() {
 
   act "$wt  [branch: ${branch:-detached}]"
   if [ "$APPLY" = 1 ]; then
-    if git -C "$REPO" worktree remove "${force_flag[@]}" "$wt" 2>/dev/null; then
+    # `${arr[@]+"${arr[@]}"}` rather than a plain `"${force_flag[@]}"`. Under
+    # `set -u`, bash before 4.4 — which includes the 3.2.57 that ships as
+    # /bin/bash on macOS, where this script mostly runs — treats an EMPTY array
+    # expansion as an unbound variable and aborts. The abort landed on the first
+    # removal candidate, so `--apply` exited 1 with no summary at all.
+    if git -C "$REPO" worktree remove ${force_flag[@]+"${force_flag[@]}"} "$wt" 2>/dev/null; then
       REMOVED=$((REMOVED + 1))
       if [ "$DELETE_BRANCHES" = 1 ] && [ -n "$branch" ] && ! is_env_branch "$branch"; then
         git -C "$REPO" branch -D "$branch" >/dev/null 2>&1 || true
@@ -232,24 +266,43 @@ while IFS= read -r line; do
 done < <(git -C "$REPO" worktree list --porcelain; echo)
 
 # Orphan directories under .claude/worktrees that git no longer tracks.
+#
+# This is the same "a failed read looks like a benign answer" hazard the status
+# guards above fix, with a worse ending: the removal here is `rm -rf`, which
+# bypasses `git worktree remove`'s own refusal to delete a dirty worktree. So
+# the enumeration is done ONCE, up front, with its exit status checked. An empty
+# result from a FAILED `git worktree list` would make `grep` match nothing, `!`
+# invert to true, and a live registered worktree be deleted outright — and empty
+# output from a killed git is the ordinary outcome of the very concurrency
+# pressure this script exists to relieve. Nothing proven means nothing swept.
 wtroot="$REPO/.claude/worktrees"
 if [ -d "$wtroot" ]; then
-  for d in "$wtroot"/*/; do
-    d=${d%/}
-    [ -d "$d" ] || continue
-    if ! git -C "$REPO" worktree list --porcelain | grep -qF "worktree $d"; then
-      if dir_age_ok "$d"; then
-        ORPHANS=$((ORPHANS + 1))
-        act "(orphan dir, not a registered worktree)  $d"
-        [ "$APPLY" = 1 ] && rm -rf "$d"
+  registered=$(git -C "$REPO" worktree list --porcelain 2>/dev/null)
+  registered_rc=$?
+  if [ "$registered_rc" -ne 0 ]; then
+    log "SKIP orphan sweep (git could not enumerate worktrees — nothing was proven)"
+  else
+    for d in "$wtroot"/*/; do
+      d=${d%/}
+      [ -d "$d" ] || continue
+      # `-x` anchors the whole line. A substring match let a registered
+      # `…/wt-280` mark a genuine orphan `…/wt-28` as registered forever; that
+      # direction only ever keeps too much, but the prefix collision is real and
+      # this repository has that collision class on record.
+      if ! printf '%s\n' "$registered" | grep -qxF "worktree $d"; then
+        if dir_age_ok "$d"; then
+          ORPHANS=$((ORPHANS + 1))
+          act "(orphan dir, not a registered worktree)  $d"
+          [ "$APPLY" = 1 ] && rm -rf "$d"
+        fi
       fi
-    fi
-  done
+    done
+  fi
 fi
 
 log ""
 log "=== summary ==="
 log "removed (or would remove): $REMOVED   orphan dirs: $ORPHANS"
-log "kept: $KEPT_DIRTY modified-tracked, $KEPT_UNPUSHED unpushed, $KEPT_UNTRACKED untracked-only, $KEPT_UNREACHABLE uncommitted-content, $KEPT_YOUNG too-young   errors: $ERRORS"
+log "kept: $KEPT_DIRTY modified-tracked, $KEPT_UNPUSHED unpushed, $KEPT_UNTRACKED untracked-only, $KEPT_UNREACHABLE uncommitted-content, $KEPT_YOUNG too-young, $KEPT_UNREADABLE unreadable   errors: $ERRORS"
 [ "$APPLY" = 0 ] && log "(dry run — rerun with --apply to delete)"
 exit 0

package/scripts/generate-export-surface.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * Record the public export surface this package ships, so a removal is an
+ * observation rather than an inference.
+ *
+ * ## The defect this exists against
+ *
+ * A release shipped a changelog declaring ZERO breaking changes across a range
+ * whose diff had removed a public export. The changelog was accurate about its
+ * own contents and useless as a safety signal: a downstream reader did the
+ * right check, carefully, with a positive control, and got a confident wrong
+ * answer. Two consumer repositories were about to upgrade on the strength of it
+ * (CodySwannGT/lisa#3718).
+ *
+ * The mechanism is that the attestation is **derived from something adjacent**.
+ * "No breaking changes" is computed from commit-message conventions — whether
+ * anyone wrote `!` or a `BREAKING CHANGE:` footer — and a template rewrite that
+ * drops an exported symbol carries neither. So the claim is about what authors
+ * typed, and it is read as a claim about what happened to the exported surface.
+ *
+ * A claim and an observation are different things. `"no breaking changes"` is a
+ * claim. `"these names were exported before and are exported now"` is an
+ * observation, and it is the one a consumer actually needs.
+ *
+ * ## Why the surface is recorded rather than computed at release time
+ *
+ * A committed artifact makes the removal **visible in the pull request that
+ * causes it**, not only in the release notes afterwards. The diff is the signal.
+ * It also means the comparison is a pure git operation with no network — which
+ * matters, because the release path already depends on registry availability
+ * that has failed under us.
+ *
+ * ## What it covers, and what it does not
+ *
+ * The shipped `.mjs` scripts under the `files` allowlist. That is deliberately
+ * where the incident happened: a `copy-overwrite` template is installed into a
+ * consumer's own `scripts/` directory, and the consumer's repo-owned code
+ * imports from it. Those files are invisible to an import graph on either side
+ * — Lisa cannot see the consumer's importer, and the consumer has no dependency
+ * to declare — so the exported names are the only shared contract there is.
+ *
+ * It reads exports **statically**, by their declaration form. It does not
+ * execute the modules, and it therefore cannot see a name attached at runtime.
+ * That limit is deliberate: importing 130 shipped scripts to enumerate them
+ * would run their top-level code during a build.
+ * @module scripts/generate-export-surface
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** Directories inside the `files` allowlist that ship executable `.mjs`. */
+const SHIPPED_ROOTS = [
+  "all",
+  "typescript",
+  "rails",
+  "expo",
+  "nestjs",
+  "cdk",
+  "phaser",
+  "harper-fabric",
+  "scripts",
+  "npm-package",
+];
+
+/**
+ * Where the recorded surface lives.
+ *
+ * JSON rather than a TypeScript module, and the reason is the diff. One
+ * exported name per line is what makes a removal show up as a DELETED line in
+ * the pull request that causes it — which is the entire point of recording the
+ * surface. At 974 names that is well past the 300-line ceiling `max-lines`
+ * applies to source, and the sibling generated artifacts buy their way past it
+ * with a file-wide `eslint-disable`. Data does not need to be source: as JSON
+ * the artifact keeps the per-name diff, needs no waiver, and its reader becomes
+ * `JSON.parse` instead of a hand-rolled line parser that could silently
+ * disagree with the renderer.
+ */
+const ARTIFACT = "src/core/export-surface.json";
+
+/**
+ * Declaration forms that introduce a named export.
+ *
+ * Anchored at line start, because an `export` inside a string or a comment is
+ * not a declaration and counting it would make the artifact disagree with the
+ * module. The corpus was surveyed before this list was written: 613 `function`,
+ * 306 `const`, 38 `async function`, 14 `class`, 4 brace-lists.
+ */
+const DECLARATION =
+  /^export\s+(?:async\s+)?(?:function|const|let|var|class)\s+([A-Za-z_$][\w$]*)/;
+
+/** `export { a, b as c }` — the re-export form. */
+const BRACE_LIST = /^export\s*\{([^}]*)\}/;
+
+/**
+ * Every tracked, shipped `.mjs` path.
+ * @param {string} cwd Repository root.
+ * @returns {string[]} Repo-relative paths, sorted.
+ */
+export function shippedScripts(cwd = process.cwd()) {
+  const listed = execFileSync("git", ["ls-files"], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  }).split("\n");
+  return listed
+    .filter(file => file.endsWith(".mjs"))
+    .filter(file => SHIPPED_ROOTS.includes(file.split("/")[0]))
+    .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+
+/**
+ * The names one module exports.
+ *
+ * `export default` is deliberately excluded: it has no name to compare, so
+ * recording it would add a row that can never change meaningfully.
+ * @param {string} source Module source.
+ * @returns {string[]} Exported names, sorted and deduplicated.
+ */
+export function exportedNames(source) {
+  const names = new Set();
+  for (const line of source.split("\n")) {
+    const declared = DECLARATION.exec(line);
+    if (declared) {
+      names.add(declared[1]);
+      continue;
+    }
+    const braced = BRACE_LIST.exec(line);
+    if (!braced) continue;
+    for (const clause of braced[1].split(",")) {
+      // `a as b` exports b; the local name is not part of the surface.
+      const parts = clause.trim().split(/\s+as\s+/);
+      const exported = (parts.at(-1) ?? "").trim();
+      if (exported && exported !== "default") names.add(exported);
+    }
+  }
+  return [...names].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0
+  );
+}
+
+/**
+ * The surface as it stands in the working tree.
+ * @param {string} cwd Repository root.
+ * @returns {Record<string, string[]>} Path to exported names.
+ */
+export function currentSurface(cwd = process.cwd()) {
+  const surface = {};
+  for (const file of shippedScripts(cwd)) {
+    const names = exportedNames(readFileSync(path.join(cwd, file), "utf8"));
+    if (names.length > 0) surface[file] = names;
+  }
+  return surface;
+}
+
+/**
+ * Render the artifact.
+ * @param {Record<string, string[]>} surface The recorded surface.
+ * @returns {string} Artifact JSON, newline-terminated.
+ */
+export function renderArtifact(surface) {
+  const total = Object.values(surface).reduce(
+    (sum, names) => sum + names.length,
+    0
+  );
+  return `${JSON.stringify(
+    {
+      $generatedBy: "scripts/generate-export-surface.mjs",
+      $doNotEdit:
+        "The public export surface this package ships, recorded so a removal is an OBSERVATION rather than an inference from commit-message conventions. This file's diff is what makes a removed export visible in the pull request that causes it (CodySwannGT/lisa#3718).",
+      $modules: Object.keys(surface).length,
+      $names: total,
+      surface,
+    },
+    null,
+    2
+  )}\n`;
+}
+
+/**
+ * Read the recorded surface out of an artifact's source.
+ *
+ * Parsed from text rather than imported, so the same reader works on a
+ * `git show` of an older revision — which is what comparing against a previous
+ * release requires.
+ * @param {string} source Artifact source.
+ * @returns {Record<string, string[]>} Path to exported names.
+ */
+export function parseArtifact(source) {
+  const parsed = JSON.parse(source);
+  return parsed.surface ?? {};
+}
+
+/**
+ * Names present in `before` and absent from `after`.
+ * @param {Record<string, string[]>} before Earlier surface.
+ * @param {Record<string, string[]>} after Later surface.
+ * @returns {Array<{file: string, name: string}>} Removals, sorted.
+ */
+export function removedExports(before, after) {
+  const gone = [];
+  for (const [file, names] of Object.entries(before)) {
+    const kept = new Set(after[file] ?? []);
+    for (const name of names) if (!kept.has(name)) gone.push({ file, name });
+  }
+  return gone.sort((left, right) =>
+    left.file === right.file
+      ? left.name < right.name
+        ? -1
+        : 1
+      : left.file < right.file
+        ? -1
+        : 1
+  );
+}
+
+/**
+ * The changelog section a release carries when it removes exports.
+ *
+ * Emits nothing when nothing was removed — a release that removed no export
+ * should not carry a paragraph saying so, or the section becomes noise that
+ * readers learn to skip, which is the failure this whole file exists against.
+ * @param {Array<{file: string, name: string}>} removals From {@link removedExports}.
+ * @returns {string} Markdown, or an empty string.
+ */
+export function changelogSection(removals) {
+  if (removals.length === 0) return "";
+  const rows = removals
+    .map(({ file, name }) => `- \`${name}\` — was exported by \`${file}\``)
+    .join("\n");
+  return `### ⚠ Removed public exports\n\n${String(removals.length)} exported name(s) present in the previous release are absent from this one. A consumer importing any of them will break on upgrade.\n\n${rows}\n`;
+}
+
+/**
+ * Read the artifact as it stood at a git revision.
+ * @param {string} ref Git revision.
+ * @param {string} cwd Repository root.
+ * @returns {Record<string, string[]>|null} The surface, or null when absent.
+ */
+function surfaceAt(ref, cwd) {
+  try {
+    const source = execFileSync("git", ["show", `${ref}:${ARTIFACT}`], {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return parseArtifact(source);
+  } catch {
+    // The artifact did not exist at that revision. That is not "no exports
+    // were removed" — it is "no comparison is possible", and the two must not
+    // render the same, so the caller is told rather than shown an empty list.
+    //
+    // probe-direction: fail-closed — `main` renders this null as exit 2 and
+    // says so in words, which any caller treating non-zero as a block reads
+    // as a refusal. An unreadable revision costs a false block, never a
+    // release that reports zero removals because it could not look.
+    return null;
+  }
+}
+
+/**
+ * CLI.
+ * @returns {number} Exit code.
+ */
+function main() {
+  const cwd = process.cwd();
+  const argv = process.argv.slice(2);
+  const since = argv.includes("--removed-since")
+    ? argv[argv.indexOf("--removed-since") + 1]
+    : null;
+
+  if (since) {
+    const before = surfaceAt(since, cwd);
+    if (before === null) {
+      // Exit 2, not 0. "I could not compare" and "nothing was removed" are
+      // opposite facts, and this whole file exists because a release reported
+      // the second while meaning something closer to the first. A caller that
+      // treats any non-zero as a block gets the safe reading by default; one
+      // that wants to allow the very first release — before any surface has
+      // been recorded — can distinguish 2 from 1 deliberately.
+      process.stdout.write(
+        `No export surface recorded at ${since}; nothing to compare. This is NOT a clean result — it is an unanswered question.\n`
+      );
+      return 2;
+    }
+    const removals = removedExports(before, currentSurface(cwd));
+    const section = changelogSection(removals);
+    process.stdout.write(
+      section === ""
+        ? `No public exports removed since ${since}. ${String(Object.values(before).reduce((sum, names) => sum + names.length, 0))} names compared.\n`
+        : section
+    );
+    return removals.length > 0 ? 1 : 0;
+  }
+
+  const rendered = renderArtifact(currentSurface(cwd));
+  const target = path.join(cwd, ARTIFACT);
+  if (argv.includes("--check")) {
+    let existing = "";
+    try {
+      existing = readFileSync(target, "utf8");
+    } catch {
+      existing = "";
+    }
+    if (existing === rendered) return 0;
+    process.stderr.write(
+      `${ARTIFACT} is stale. Regenerate it in this commit:\n  bun run build:export-surface\n`
+    );
+    return 1;
+  }
+  writeFileSync(target, rendered);
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main());
+}

package/scripts/lib/shipped-surface.mjs

@@ -0,0 +1,212 @@
+/**
+ * Pure parsing and classification helpers for the shipped-surface removal gate
+ * (`scripts/check-shipped-surface-removals.mjs`, CodySwannGT/lisa#3849).
+ *
+ * Everything here is a total function over strings and plain objects: no git,
+ * no filesystem, no clock. The gate keeps its I/O in one file so these can be
+ * mutation-tested by hand without a repository fixture, which matters because
+ * `stryker.conf.json`'s `mutate` is a ten-file allowlist that a new `scripts/`
+ * module does not join - an automated run over this file reports
+ * `nothing-to-mutate` and says nothing at all.
+ *
+ * @module scripts/lib/shipped-surface
+ */
+import path from "node:path";
+
+/**
+ * Extensions a consumer can put behind a `package.json` script entry.
+ *
+ * The list is deliberately broader than "things Lisa runs itself": the
+ * question this gate asks is not what upstream invokes, it is what a HOST
+ * could have wired. See `isConsumerBindable`.
+ */
+export const EXECUTABLE_EXTENSIONS = Object.freeze([
+  ".cjs",
+  ".js",
+  ".mjs",
+  ".py",
+  ".sh",
+  ".ts",
+]);
+
+/** Destination directory whose contents a host routinely names in scripts. */
+export const BINDABLE_ROOT = "scripts/";
+
+/**
+ * Whether a destination path is one a consumer may have bound into their own
+ * `package.json` - and therefore one that must NOT be propagated as a deletion
+ * by default (#3849, revised scenario 3).
+ *
+ * The rule is the ticket's, stated as a question about the host rather than
+ * about upstream: not "does upstream still need it" but "could a consumer have
+ * wired this into their own scripts?" For an executable under `scripts/` the
+ * answer is usually yes, and the reported instance is exactly that shape - an
+ * importer with three npm script entries, a workflow, and a test in the host.
+ *
+ * @param {string} destination - path in the consumer's tree.
+ * @returns {boolean} true when a host may have bound it.
+ */
+export function isConsumerBindable(destination) {
+  if (!destination.startsWith(BINDABLE_ROOT)) return false;
+  return EXECUTABLE_EXTENSIONS.includes(path.posix.extname(destination));
+}
+
+/** Declaration forms that name exactly one exported binding. */
+const DECLARED_EXPORT_PATTERNS = Object.freeze([
+  /^\s*export\s+(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/gm,
+  /^\s*export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/gm,
+  /^\s*export\s+class\s+([A-Za-z_$][\w$]*)/gm,
+]);
+
+/** `export { a, b as c }`, with or without a `from` clause. */
+const EXPORT_CLAUSE = /^\s*export\s*\{([^}]*)\}/gm;
+
+/** `export * from "./x.mjs"` - a re-export whose names live in the target. */
+const EXPORT_STAR = /^\s*export\s*\*\s*from\s*["']([^"']+)["']/gm;
+
+/** `import { a, b as c } from "./x.mjs"` - named imports only. */
+const IMPORT_CLAUSE = /^\s*import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/gm;
+
+/**
+ * The exported name a `{ ... }` clause member introduces: the alias when one
+ * is written, the original otherwise. `default` members are dropped - a
+ * default export is not a named one and the gate never asks about it.
+ *
+ * @param {string} member - one comma-separated clause member.
+ * @returns {string | null} the exported name, or null when there is none.
+ */
+export function clauseExportedName(member) {
+  const trimmed = member.trim().replace(/^type\s+/, "");
+  if (trimmed === "") return null;
+  const parts = trimmed.split(/\s+as\s+/);
+  const name = (parts.length > 1 ? parts[1] : parts[0]).trim();
+  return name === "" || name === "default" ? null : name;
+}
+
+/**
+ * The imported local binding a `{ ... }` clause member requests from the
+ * target module: always the name BEFORE any `as`, because that is the symbol
+ * the target must actually export.
+ *
+ * @param {string} member - one comma-separated clause member.
+ * @returns {string | null} the requested export name, or null when there is none.
+ */
+export function clauseImportedName(member) {
+  const trimmed = member.trim().replace(/^type\s+/, "");
+  if (trimmed === "") return null;
+  const name = trimmed.split(/\s+as\s+/)[0].trim();
+  return name === "" || name === "default" ? null : name;
+}
+
+/**
+ * Every named export a module source declares directly, plus the relative
+ * specifiers it re-exports wholesale.
+ *
+ * `export *` is returned rather than resolved: resolution needs the delivery
+ * view, which lives in the gate. Doing it here would make this module read the
+ * filesystem.
+ *
+ * @param {string} source - module source text.
+ * @returns {{ names: Set<string>, starFrom: string[] }} declared names and
+ *   the relative specifiers whose names are inherited.
+ */
+export function parseNamedExports(source) {
+  const names = new Set();
+  for (const pattern of DECLARED_EXPORT_PATTERNS) {
+    for (const match of source.matchAll(pattern)) names.add(match[1]);
+  }
+  for (const match of source.matchAll(EXPORT_CLAUSE)) {
+    for (const member of match[1].split(",")) {
+      const name = clauseExportedName(member);
+      if (name !== null) names.add(name);
+    }
+  }
+  const starFrom = [...source.matchAll(EXPORT_STAR)]
+    .map(match => match[1])
+    .filter(specifier => specifier.startsWith("."));
+  return { names, starFrom };
+}
+
+/**
+ * Every named import a module source requests from a RELATIVE specifier.
+ *
+ * Bare specifiers are skipped: they resolve through `node_modules` in the
+ * consumer's tree, which this repository cannot see and does not govern.
+ *
+ * @param {string} source - module source text.
+ * @returns {Array<{ specifier: string, names: string[] }>} one entry per
+ *   relative named-import statement, in source order.
+ */
+export function parseRelativeNamedImports(source) {
+  const requests = [];
+  for (const match of source.matchAll(IMPORT_CLAUSE)) {
+    const specifier = match[2];
+    if (!specifier.startsWith(".")) continue;
+    const names = match[1]
+      .split(",")
+      .map(member => clauseImportedName(member))
+      .filter(name => name !== null);
+    if (names.length > 0) requests.push({ names, specifier });
+  }
+  return requests;
+}
+
+/**
+ * The destination a relative specifier resolves to, given the destination
+ * path of the importing module.
+ *
+ * @param {string} importerDestination - the importer's path in the consumer tree.
+ * @param {string} specifier - a relative specifier from that importer.
+ * @returns {string} the resolved destination path.
+ */
+export function resolveRelative(importerDestination, specifier) {
+  return path.posix.normalize(
+    path.posix.join(path.posix.dirname(importerDestination), specifier)
+  );
+}
+
+/**
+ * The ledger key for one governed surface.
+ *
+ * A whole-file removal is keyed by path alone; an export removal is keyed
+ * `path symbol`. A shipped path never contains a space, so the two key spaces
+ * cannot collide.
+ *
+ * @param {string} shippedPath - repo-relative path inside a delivery lane.
+ * @param {string} [symbol] - the exported name, when a symbol rather than a file.
+ * @returns {string} the key.
+ */
+export function removalKey(shippedPath, symbol) {
+  return symbol === undefined ? shippedPath : `${shippedPath} ${symbol}`;
+}
+
+/**
+ * Index a removal ledger by the surface each entry governs.
+ *
+ * @param {ReadonlyArray<{ path: string, export?: string, note?: string }>} removals
+ *   ledger entries.
+ * @returns {Map<string, { path: string, export?: string, note?: string }>} the index.
+ */
+export function indexRemovals(removals) {
+  return new Map(
+    removals.map(entry => [removalKey(entry.path, entry.export), entry])
+  );
+}
+
+/**
+ * Whether a ledger entry actually records something an operator can act on.
+ *
+ * An entry with a blank note is treated as absent. A note that says nothing is
+ * the same silence the gate exists to break, and accepting it would let the
+ * ledger be satisfied by a placeholder.
+ *
+ * @param {{ note?: unknown } | undefined} entry - the indexed ledger entry.
+ * @returns {boolean} true when the entry carries a usable note.
+ */
+export function hasUsableNote(entry) {
+  return (
+    entry !== undefined &&
+    typeof entry.note === "string" &&
+    entry.note.trim() !== ""
+  );
+}