@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/diff/scope/changed-paths.js

@@ -0,0 +1,204 @@
+/**
+ * Which targets a base git ref puts in scope — the narrowing behind
+ * `loam validate --all --base <ref>`.
+ *
+ * The defect this exists for: a partly-adopted fleet has no CI setting that is
+ * both passing today and tightening over time. `--all` is green over eleven
+ * undocumented services (they warn, and warnings do not gate) and `--strict` is
+ * red from the first minute of adoption until the last boundary is written, so
+ * a team installs either a gate that never notices adoption stalling at 8% or
+ * one it cannot turn on. `--base` is the third setting: grade what this branch
+ * TOUCHED, at full `--strict` severity if the caller wants it, and let the
+ * untouched majority stay untouched.
+ *
+ * A SUB-PACKAGE of `core/diff/` rather than a sixth file in it, because that
+ * directory is at the five-file limit and because this is a different subject
+ * from the semantic diff beside it: `diff` compares two states of the fleet and
+ * reports what moved, this one only decides WHICH SUBJECTS a run should look
+ * at. Nothing here reads a document; the one question that has to — which call
+ * edges on the fleet map are this branch's — is `./edges.ts`'s, and it reads
+ * only the map documents the branch changed.
+ *
+ * What it does NOT do, and the line is not negotiable: a diff-scoped validate
+ * cannot see a victim boundary the change did not touch. Removing an operation
+ * from `payment-service` puts `payment-service` in scope and leaves
+ * `checkout-web` — whose living requirement still names the operation — out of
+ * it. That join is `loam diff --base`'s question and it stays `loam diff`'s;
+ * the two gates answer "did you document what you touched" and "did you break a
+ * consumer", and neither substitutes for the other. Selling a green here that
+ * hides a broken join would be worse than shipping no flag at all.
+ *
+ * A join the branch WROTE is a different case, and it is graded: an edge the
+ * branch added or edited on the fleet map is checked against its provider's
+ * contract even with the provider out of scope (`edges` below), because the
+ * edge is the document this branch touched and the provider is only where its
+ * answer lives.
+ */
+import { declineDetail, gitText } from "../../provenance/git.js";
+import { repoPath } from "../../envelope/json.js";
+import { resolveBase } from "../base-git.js";
+import { edgesSince } from "./edges.js";
+/**
+ * Every path that differs between `ref` and the WORKING TREE, docs-relative.
+ *
+ * Two questions, not one, and the second is not optional: `git diff` compares
+ * the tree git tracks, so a service adopted five minutes ago — a brand new
+ * `services/<id>/spec.md` nobody has committed — is invisible to it. `validate`
+ * grades the working tree, so the scope has to be the working tree's, and an
+ * untracked new boundary that the run then skipped would be the flag's very
+ * first user reporting that it graded nothing.
+ *
+ * `--no-renames` on purpose: with rename detection on (git's default since
+ * 2.9) a service moved into a subsystem reports only its DESTINATION, and the
+ * checks that grade the fleet from the old placement would be out of scope.
+ * Two paths for a move is the honest answer.
+ *
+ * `-z` because git quotes non-ASCII and space-bearing paths in line output —
+ * the same reason `gitTrackedFiles` asks that way, and the same phantom
+ * directory named `"src` if it did not.
+ */
+async function changedPaths(docsDir, commit, prefix) {
+    // Both run from docsDir. `git diff` ignores cwd and answers for the whole
+    // repository with root-relative paths; `git ls-files` restricts itself to
+    // cwd, and `--full-name` makes ITS paths root-relative too — so one prefix
+    // strip below is correct for both, exactly as `listBaseTree` needs one.
+    const tracked = await gitText(docsDir, ["diff", "--name-only", "--no-renames", "-z", commit, "--"]);
+    if (tracked.spawnError !== undefined || tracked.code !== 0 || tracked.overflowed) {
+        return { detail: tracked.overflowed ? "the changed-path listing exceeded the output cap." : declineDetail(tracked) };
+    }
+    const untracked = await gitText(docsDir, ["ls-files", "--others", "--exclude-standard", "--full-name", "-z"]);
+    if (untracked.spawnError !== undefined || untracked.code !== 0 || untracked.overflowed) {
+        return { detail: untracked.overflowed ? "the untracked-path listing exceeded the output cap." : declineDetail(untracked) };
+    }
+    const seen = new Set();
+    for (const raw of [...tracked.out.split("\0"), ...untracked.out.split("\0")]) {
+        // A docs repo checked out as a subdirectory of a larger repository answers
+        // in the whole repository's paths; anything outside the docs dir is
+        // somebody else's change and is not a target here.
+        if (raw === "" || !raw.startsWith(prefix))
+            continue;
+        const rel = raw.slice(prefix.length);
+        if (rel !== "")
+            seen.add(rel);
+    }
+    return [...seen].sort();
+}
+/**
+ * Is `path` inside `dir`? Both docs-relative, forward-slashed.
+ *
+ * A prefix test on the directory plus a separator, never a split on "/" and a
+ * read of the second segment: a service filed under a subsystem lives at
+ * `services/platform/payment-service/`, not at `services/<id>/`, and a
+ * path-splitting implementation drops every filed service out of scope
+ * SILENTLY — the run stays green because it graded nothing, which is the exact
+ * failure this flag is not allowed to have. The separator is what stops
+ * `services/pay` from claiming `services/payments/spec.md`.
+ */
+function inside(path, dir) {
+    return dir !== "" && (path === dir || path.startsWith(`${dir}/`));
+}
+/** Did this branch change `rel` — a docs-relative file, or anything under a docs-relative directory? */
+export function touched(scope, rel) {
+    return scope.changed.some((path) => inside(path, rel));
+}
+/** The fleet's own documents — the landscape target's subject, which owns no service directory. */
+const ARCHITECTURE_DIR = "architecture";
+/**
+ * Narrow a `--all` run to what changed since `ref`.
+ *
+ * Targets are matched through the ENUMERATIONS' own directories
+ * (`ServiceEntry.dir`, `FeatureEntry.dir`), turned docs-relative by the same
+ * `repoPath` the JSON contract uses. That is the whole reason the enumerations
+ * are passed in rather than re-derived: they already know where each service
+ * sits, at whatever depth, and asking them is what makes a filed fleet work.
+ */
+export async function scopeSince(request) {
+    const { docsDir, ref } = request;
+    const base = await resolveBase(docsDir, ref);
+    if (base.kind === "no-git") {
+        return {
+            kind: "refused",
+            code: "repository-unavailable",
+            message: `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +
+                `--base narrows the run to what changed since a ref, which it reads with read-only git questions ` +
+                `(rev-parse/diff/ls-files). Clone the docs repo with its history, then re-run — or drop --base to grade every target.`,
+        };
+    }
+    if (base.kind === "no-ref") {
+        return {
+            kind: "refused",
+            code: "unknown-target",
+            message: `--base ${ref} does not resolve to a commit in the docs repo at ${docsDir}` +
+                `${base.detail === "" ? "" : ` (${base.detail})`}. ` +
+                `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`,
+        };
+    }
+    const changed = await changedPaths(docsDir, base.commit, base.prefix);
+    if (!Array.isArray(changed)) {
+        // Git resolved the ref and then would not say what moved. There is no
+        // partial answer to give: a scope built from half an answer grades a
+        // subset nobody chose and reports it as the branch's whole footprint.
+        return {
+            kind: "refused",
+            code: "repository-unavailable",
+            message: `git could not list what changed since ${ref} in the docs repo at ${docsDir} (${changed.detail}) — ` +
+                `without that list there is no honest scope, and a run over a guessed subset would report a green ` +
+                `for targets nobody graded. Re-run once git can answer, or drop --base to grade every target.`,
+        };
+    }
+    const dirOf = (abs) => repoPath(docsDir, abs);
+    // `architecture/` is the landscape target's whole directory: the fleet map,
+    // the permission/capability/obligation vocabularies and the fleet ADRs all
+    // live there, and every one of them is graded by the landscape target
+    // rather than by any service.
+    const architecture = changed.filter((path) => inside(path, ARCHITECTURE_DIR));
+    return {
+        kind: "scope",
+        ref,
+        commit: base.commit,
+        landscape: architecture.length > 0,
+        changed,
+        edges: await edgesSince({ docsDir, commit: base.commit, prefix: base.prefix }, architecture.filter((path) => path.endsWith(".likec4"))),
+        services: request.services.filter((svc) => changed.some((path) => inside(path, dirOf(svc.dir)))),
+        features: request.features.filter((feat) => changed.some((path) => inside(path, dirOf(feat.dir)))),
+        totals: { services: request.services.length, features: request.features.length },
+    };
+}
+/**
+ * The `scope` object the `--json` payload carries — the run saying out loud
+ * what it looked at.
+ *
+ * Additive, and emitted only under `--base`, so no consumer of today's payload
+ * moves. It exists because the alternative is a payload that is byte-shaped
+ * like a whole-fleet run and is not one: `summary.services` would report two
+ * where the fleet has twelve, `valid: true` would read as a claim about the
+ * fleet, and nothing in the document would say otherwise.
+ */
+export function scopeJson(scope) {
+    return {
+        base: scope.ref,
+        commit: scope.commit,
+        landscape: scope.landscape,
+        services: scope.services.map((svc) => svc.id),
+        features: scope.features.map((feat) => feat.id),
+        totals: scope.totals,
+    };
+}
+/**
+ * The one line both the text view and a reader of a CI log need: how much of
+ * the fleet this run actually graded, and against what.
+ *
+ * The "nothing was graded" clause is the load-bearing half. A `--base` run with
+ * no targets in scope has nothing to report and exits 0 — correctly, the branch
+ * touched no governed boundary — and a 0 that reads like a green over the
+ * system is the exact failure the docs-repo readiness gate exists to prevent.
+ * So the sentence says it, rather than letting an empty report say nothing.
+ */
+export function scopeLine(scope) {
+    const graded = scope.services.length + scope.features.length + (scope.landscape ? 1 : 0);
+    return (`${scope.services.length} of ${scope.totals.services} services, ` +
+        `${scope.features.length} of ${scope.totals.features} features in scope since ${scope.ref}` +
+        (scope.landscape ? ", plus the landscape" : "") +
+        (graded === 0 ? " — nothing was graded" : ""));
+}
+//# sourceMappingURL=changed-paths.js.map

package/dist/core/diff/scope/changed-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed-paths.js","sourceRoot":"","sources":["../../../../src/core/diff/scope/changed-paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which targets a base git ref puts in scope — the narrowing behind\n * `loam validate --all --base <ref>`.\n *\n * The defect this exists for: a partly-adopted fleet has no CI setting that is\n * both passing today and tightening over time. `--all` is green over eleven\n * undocumented services (they warn, and warnings do not gate) and `--strict` is\n * red from the first minute of adoption until the last boundary is written, so\n * a team installs either a gate that never notices adoption stalling at 8% or\n * one it cannot turn on. `--base` is the third setting: grade what this branch\n * TOUCHED, at full `--strict` severity if the caller wants it, and let the\n * untouched majority stay untouched.\n *\n * A SUB-PACKAGE of `core/diff/` rather than a sixth file in it, because that\n * directory is at the five-file limit and because this is a different subject\n * from the semantic diff beside it: `diff` compares two states of the fleet and\n * reports what moved, this one only decides WHICH SUBJECTS a run should look\n * at. Nothing here reads a document; the one question that has to — which call\n * edges on the fleet map are this branch's — is `./edges.ts`'s, and it reads\n * only the map documents the branch changed.\n *\n * What it does NOT do, and the line is not negotiable: a diff-scoped validate\n * cannot see a victim boundary the change did not touch. Removing an operation\n * from `payment-service` puts `payment-service` in scope and leaves\n * `checkout-web` — whose living requirement still names the operation — out of\n * it. That join is `loam diff --base`'s question and it stays `loam diff`'s;\n * the two gates answer \"did you document what you touched\" and \"did you break a\n * consumer\", and neither substitutes for the other. Selling a green here that\n * hides a broken join would be worse than shipping no flag at all.\n *\n * A join the branch WROTE is a different case, and it is graded: an edge the\n * branch added or edited on the fleet map is checked against its provider's\n * contract even with the provider out of scope (`edges` below), because the\n * edge is the document this branch touched and the provider is only where its\n * answer lives.\n */\nimport { declineDetail, gitText } from \"../../provenance/git.js\";\nimport { repoPath, type ErrorCode } from \"../../envelope/json.js\";\nimport { resolveBase } from \"../base-git.js\";\nimport { edgesSince } from \"./edges.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { FeatureEntry, ServiceEntry } from \"../../repo/entries.js\";\n\n/** Everything the narrowing needs: where to ask, what to ask about, and what there is to narrow. */\nexport interface ScopeRequest {\n  docsDir: DocsDir;\n  /** The ref as the caller spelled it — echoed in every message and in the payload. */\n  ref: string;\n  /** The run's full service enumeration, at whatever depth the tree walk found each one. */\n  services: readonly ServiceEntry[];\n  /** The run's full ACTIVE feature enumeration. */\n  features: readonly FeatureEntry[];\n}\n\n/** The narrowed run: which targets the branch touched, and what it narrowed from. */\nexport interface ValidateScope {\n  kind: \"scope\";\n  ref: string;\n  /** The 40-hex commit `ref` resolved to — what a rerun would have to pass to reproduce this scope. */\n  commit: string;\n  /** Did `architecture/` change? The landscape target is the fleet's own subject and has no directory of its own. */\n  landscape: boolean;\n  /**\n   * Every docs-relative path that differs from the base, untracked files\n   * included. Kept because the landscape target grades more files than the\n   * map — the fleet vocabularies, AGENTS.md — and `touched` is how the run asks\n   * which of them this branch changed.\n   */\n  changed: readonly string[];\n  /**\n   * The fleet-map call edges this branch introduced or changed, as\n   * `./edges.ts`'s `edgeKey`s. Empty unless `architecture/` changed.\n   */\n  edges: ReadonlySet<string>;\n  services: ServiceEntry[];\n  features: FeatureEntry[];\n  /** The denominators — what the run would have graded without `--base`. */\n  totals: { services: number; features: number };\n}\n\n/**\n * A refusal, already spelled. The code is one `loam diff` already emits for the\n * same two conditions and the message is in the same register, deliberately: a\n * second stable code for \"that ref does not resolve\" would be a second thing to\n * document, branch on and keep in step, for a condition that is identical.\n *\n * The prose is built here rather than in the command because it is the same\n * sentence for every caller and because `base-git.ts`'s `detail` — git's own\n * words, bounded — is what makes it diagnosable; a command that only received a\n * `kind` would have to reinvent the sentence to say why.\n */\nexport interface ScopeRefusal {\n  kind: \"refused\";\n  code: ErrorCode;\n  message: string;\n}\n\nexport type ScopeOutcome = ValidateScope | ScopeRefusal;\n\n/**\n * Every path that differs between `ref` and the WORKING TREE, docs-relative.\n *\n * Two questions, not one, and the second is not optional: `git diff` compares\n * the tree git tracks, so a service adopted five minutes ago — a brand new\n * `services/<id>/spec.md` nobody has committed — is invisible to it. `validate`\n * grades the working tree, so the scope has to be the working tree's, and an\n * untracked new boundary that the run then skipped would be the flag's very\n * first user reporting that it graded nothing.\n *\n * `--no-renames` on purpose: with rename detection on (git's default since\n * 2.9) a service moved into a subsystem reports only its DESTINATION, and the\n * checks that grade the fleet from the old placement would be out of scope.\n * Two paths for a move is the honest answer.\n *\n * `-z` because git quotes non-ASCII and space-bearing paths in line output —\n * the same reason `gitTrackedFiles` asks that way, and the same phantom\n * directory named `\"src` if it did not.\n */\nasync function changedPaths(docsDir: DocsDir, commit: string, prefix: string): Promise<string[] | { detail: string }> {\n  // Both run from docsDir. `git diff` ignores cwd and answers for the whole\n  // repository with root-relative paths; `git ls-files` restricts itself to\n  // cwd, and `--full-name` makes ITS paths root-relative too — so one prefix\n  // strip below is correct for both, exactly as `listBaseTree` needs one.\n  const tracked = await gitText(docsDir, [\"diff\", \"--name-only\", \"--no-renames\", \"-z\", commit, \"--\"]);\n  if (tracked.spawnError !== undefined || tracked.code !== 0 || tracked.overflowed) {\n    return { detail: tracked.overflowed ? \"the changed-path listing exceeded the output cap.\" : declineDetail(tracked) };\n  }\n  const untracked = await gitText(docsDir, [\"ls-files\", \"--others\", \"--exclude-standard\", \"--full-name\", \"-z\"]);\n  if (untracked.spawnError !== undefined || untracked.code !== 0 || untracked.overflowed) {\n    return { detail: untracked.overflowed ? \"the untracked-path listing exceeded the output cap.\" : declineDetail(untracked) };\n  }\n  const seen = new Set<string>();\n  for (const raw of [...tracked.out.split(\"\\0\"), ...untracked.out.split(\"\\0\")]) {\n    // A docs repo checked out as a subdirectory of a larger repository answers\n    // in the whole repository's paths; anything outside the docs dir is\n    // somebody else's change and is not a target here.\n    if (raw === \"\" || !raw.startsWith(prefix)) continue;\n    const rel = raw.slice(prefix.length);\n    if (rel !== \"\") seen.add(rel);\n  }\n  return [...seen].sort();\n}\n\n/**\n * Is `path` inside `dir`? Both docs-relative, forward-slashed.\n *\n * A prefix test on the directory plus a separator, never a split on \"/\" and a\n * read of the second segment: a service filed under a subsystem lives at\n * `services/platform/payment-service/`, not at `services/<id>/`, and a\n * path-splitting implementation drops every filed service out of scope\n * SILENTLY — the run stays green because it graded nothing, which is the exact\n * failure this flag is not allowed to have. The separator is what stops\n * `services/pay` from claiming `services/payments/spec.md`.\n */\nfunction inside(path: string, dir: string): boolean {\n  return dir !== \"\" && (path === dir || path.startsWith(`${dir}/`));\n}\n\n/** Did this branch change `rel` — a docs-relative file, or anything under a docs-relative directory? */\nexport function touched(scope: ValidateScope, rel: string): boolean {\n  return scope.changed.some((path) => inside(path, rel));\n}\n\n/** The fleet's own documents — the landscape target's subject, which owns no service directory. */\nconst ARCHITECTURE_DIR = \"architecture\";\n\n/**\n * Narrow a `--all` run to what changed since `ref`.\n *\n * Targets are matched through the ENUMERATIONS' own directories\n * (`ServiceEntry.dir`, `FeatureEntry.dir`), turned docs-relative by the same\n * `repoPath` the JSON contract uses. That is the whole reason the enumerations\n * are passed in rather than re-derived: they already know where each service\n * sits, at whatever depth, and asking them is what makes a filed fleet work.\n */\nexport async function scopeSince(request: ScopeRequest): Promise<ScopeOutcome> {\n  const { docsDir, ref } = request;\n  const base = await resolveBase(docsDir, ref);\n  if (base.kind === \"no-git\") {\n    return {\n      kind: \"refused\",\n      code: \"repository-unavailable\",\n      message:\n        `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +\n        `--base narrows the run to what changed since a ref, which it reads with read-only git questions ` +\n        `(rev-parse/diff/ls-files). Clone the docs repo with its history, then re-run — or drop --base to grade every target.`,\n    };\n  }\n  if (base.kind === \"no-ref\") {\n    return {\n      kind: \"refused\",\n      code: \"unknown-target\",\n      message:\n        `--base ${ref} does not resolve to a commit in the docs repo at ${docsDir}` +\n        `${base.detail === \"\" ? \"\" : ` (${base.detail})`}. ` +\n        `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`,\n    };\n  }\n\n  const changed = await changedPaths(docsDir, base.commit, base.prefix);\n  if (!Array.isArray(changed)) {\n    // Git resolved the ref and then would not say what moved. There is no\n    // partial answer to give: a scope built from half an answer grades a\n    // subset nobody chose and reports it as the branch's whole footprint.\n    return {\n      kind: \"refused\",\n      code: \"repository-unavailable\",\n      message:\n        `git could not list what changed since ${ref} in the docs repo at ${docsDir} (${changed.detail}) — ` +\n        `without that list there is no honest scope, and a run over a guessed subset would report a green ` +\n        `for targets nobody graded. Re-run once git can answer, or drop --base to grade every target.`,\n    };\n  }\n\n  const dirOf = (abs: string): string => repoPath(docsDir, abs);\n  // `architecture/` is the landscape target's whole directory: the fleet map,\n  // the permission/capability/obligation vocabularies and the fleet ADRs all\n  // live there, and every one of them is graded by the landscape target\n  // rather than by any service.\n  const architecture = changed.filter((path) => inside(path, ARCHITECTURE_DIR));\n  return {\n    kind: \"scope\",\n    ref,\n    commit: base.commit,\n    landscape: architecture.length > 0,\n    changed,\n    edges: await edgesSince(\n      { docsDir, commit: base.commit, prefix: base.prefix },\n      architecture.filter((path) => path.endsWith(\".likec4\")),\n    ),\n    services: request.services.filter((svc) => changed.some((path) => inside(path, dirOf(svc.dir)))),\n    features: request.features.filter((feat) => changed.some((path) => inside(path, dirOf(feat.dir)))),\n    totals: { services: request.services.length, features: request.features.length },\n  };\n}\n\n/**\n * The `scope` object the `--json` payload carries — the run saying out loud\n * what it looked at.\n *\n * Additive, and emitted only under `--base`, so no consumer of today's payload\n * moves. It exists because the alternative is a payload that is byte-shaped\n * like a whole-fleet run and is not one: `summary.services` would report two\n * where the fleet has twelve, `valid: true` would read as a claim about the\n * fleet, and nothing in the document would say otherwise.\n */\nexport function scopeJson(scope: ValidateScope): Record<string, unknown> {\n  return {\n    base: scope.ref,\n    commit: scope.commit,\n    landscape: scope.landscape,\n    services: scope.services.map((svc) => svc.id),\n    features: scope.features.map((feat) => feat.id),\n    totals: scope.totals,\n  };\n}\n\n/**\n * The one line both the text view and a reader of a CI log need: how much of\n * the fleet this run actually graded, and against what.\n *\n * The \"nothing was graded\" clause is the load-bearing half. A `--base` run with\n * no targets in scope has nothing to report and exits 0 — correctly, the branch\n * touched no governed boundary — and a 0 that reads like a green over the\n * system is the exact failure the docs-repo readiness gate exists to prevent.\n * So the sentence says it, rather than letting an empty report say nothing.\n */\nexport function scopeLine(scope: ValidateScope): string {\n  const graded = scope.services.length + scope.features.length + (scope.landscape ? 1 : 0);\n  return (\n    `${scope.services.length} of ${scope.totals.services} services, ` +\n    `${scope.features.length} of ${scope.totals.features} features in scope since ${scope.ref}` +\n    (scope.landscape ? \", plus the landscape\" : \"\") +\n    (graded === 0 ? \" — nothing was graded\" : \"\")\n  );\n}\n"]}

package/dist/core/diff/scope/edges.js

@@ -0,0 +1,82 @@
+/**
+ * Which fleet-map call edges a branch introduced — the one half of the `--base`
+ * narrowing that reads a document.
+ *
+ * The defect this exists for: `spine.op-undefined` is graded on the PROVIDER's
+ * service target, and an `architecture/` change only ever put the landscape in
+ * scope. So the hand edit the spine-first path is built on — naming the
+ * operation on a call edge — was graded by no gate a PR runs: README's own
+ * one-letter example (`authorisePayment` against a contract spelling it
+ * `authorizePayment`) merged green through `loam diff --base` and through
+ * `validate --all --base --strict`, on the adopted example fleet and on a
+ * freshly seeded one alike. This module answers the question that grade needs
+ * — which edges are this branch's — and `commands/validate/scope.ts` grades
+ * exactly those against their providers' contracts.
+ *
+ * AN EDGE IS ITS (source, target, op) TUPLE. A tuple present now and absent at
+ * the base is new or changed — a new edge, a re-pointed one, a renamed
+ * endpoint, an op named or re-spelled — and every one of those is a join the
+ * branch wrote. A tuple present at both ends is not, wherever in the file it
+ * moved and however it was re-indented: the key is what the edge MEANS, so a
+ * reformat grades nothing.
+ *
+ * TEXT, NOT A PARSE, at both ends. The base side would otherwise need a second
+ * LikeC4 workspace over bytes read out of git — the most expensive thing loam
+ * does, paid on every map PR to answer a question about a handful of lines.
+ * `scanModel` is the archive's splice map and resolves endpoints the way LikeC4
+ * does; `test/likec4-scan-parity.test.ts` pins the two readings together, and
+ * the key below is built from the same three fields the parsed `Rel` carries, so
+ * a scanned key names the edge the parsed map holds.
+ *
+ * ONLY THE DOCUMENTS THAT CHANGED are read, at both ends: an edge in an
+ * untouched document is by construction not this branch's, and an edge moved
+ * between two documents changes both, so its base key is still read.
+ *
+ * Which way a failure falls, and why: a base document git will not show — new
+ * on this branch, or a git that declines — contributes no base keys, so every
+ * edge in it reads as new and is graded. Grading an edge the branch did not
+ * write costs a reader one finding; skipping one it did write is the green this
+ * module exists to remove.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { scanModel } from "../../c4/source-scan.js";
+import { inOrder } from "../../kernel/concurrency.js";
+import { showBaseFile } from "../base-git.js";
+/**
+ * One edge's identity as a string a `Set` can hold. JSON rather than a joined
+ * string because an element id may legally carry any separator a join would
+ * pick, and two different tuples must never spell one key.
+ */
+export function edgeKey(edge) {
+    return JSON.stringify([edge.source, edge.target, edge.op ?? null]);
+}
+function keysOf(text) {
+    return text === null ? [] : (scanModel(text)?.rels ?? []).map(edgeKey);
+}
+/** The document as the base commit held it, or null when git will not show it (see the banner for why that is safe). */
+async function baseText(base, rel) {
+    const read = await showBaseFile(base, rel);
+    return read.kind === "ok" ? read.bytes.toString("utf8") : null;
+}
+/** The document as the working tree holds it, or null when the branch deleted it. */
+async function currentText(base, rel) {
+    const abs = join(base.docsDir, rel);
+    return existsSync(abs) ? readFile(abs, "utf8") : null;
+}
+/**
+ * The `edgeKey`s of every edge `documents` hold now and did not hold at the
+ * base. `documents` are docs-relative `.likec4` paths the branch changed —
+ * the caller's filter, so this module never has to know which directory the
+ * fleet map lives in.
+ */
+export async function edgesSince(base, documents) {
+    const sides = await inOrder(documents, async (rel) => {
+        const [before, after] = await Promise.all([baseText(base, rel), currentText(base, rel)]);
+        return { before: keysOf(before), after: keysOf(after) };
+    });
+    const before = new Set(sides.flatMap((side) => side.before));
+    return new Set(sides.flatMap((side) => side.after).filter((key) => !before.has(key)));
+}
+//# sourceMappingURL=edges.js.map

package/dist/core/diff/scope/edges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edges.js","sourceRoot":"","sources":["../../../../src/core/diff/scope/edges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACtD,OAAO,EAAE,YAAY,EAAqB,MAAM,gBAAgB,CAAC;AASjE;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAe;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,MAAM,CAAC,IAAmB;IACjC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACzE,CAAC;AAED,wHAAwH;AACxH,KAAK,UAAU,QAAQ,CAAC,IAAkB,EAAE,GAAW;IACrD,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3C,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC;AAED,qFAAqF;AACrF,KAAK,UAAU,WAAW,CAAC,IAAkB,EAAE,GAAW;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACpC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAkB,EAAE,SAA4B;IAC/E,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACnD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QACzF,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACxF,CAAC","sourcesContent":["/**\n * Which fleet-map call edges a branch introduced — the one half of the `--base`\n * narrowing that reads a document.\n *\n * The defect this exists for: `spine.op-undefined` is graded on the PROVIDER's\n * service target, and an `architecture/` change only ever put the landscape in\n * scope. So the hand edit the spine-first path is built on — naming the\n * operation on a call edge — was graded by no gate a PR runs: README's own\n * one-letter example (`authorisePayment` against a contract spelling it\n * `authorizePayment`) merged green through `loam diff --base` and through\n * `validate --all --base --strict`, on the adopted example fleet and on a\n * freshly seeded one alike. This module answers the question that grade needs\n * — which edges are this branch's — and `commands/validate/scope.ts` grades\n * exactly those against their providers' contracts.\n *\n * AN EDGE IS ITS (source, target, op) TUPLE. A tuple present now and absent at\n * the base is new or changed — a new edge, a re-pointed one, a renamed\n * endpoint, an op named or re-spelled — and every one of those is a join the\n * branch wrote. A tuple present at both ends is not, wherever in the file it\n * moved and however it was re-indented: the key is what the edge MEANS, so a\n * reformat grades nothing.\n *\n * TEXT, NOT A PARSE, at both ends. The base side would otherwise need a second\n * LikeC4 workspace over bytes read out of git — the most expensive thing loam\n * does, paid on every map PR to answer a question about a handful of lines.\n * `scanModel` is the archive's splice map and resolves endpoints the way LikeC4\n * does; `test/likec4-scan-parity.test.ts` pins the two readings together, and\n * the key below is built from the same three fields the parsed `Rel` carries, so\n * a scanned key names the edge the parsed map holds.\n *\n * ONLY THE DOCUMENTS THAT CHANGED are read, at both ends: an edge in an\n * untouched document is by construction not this branch's, and an edge moved\n * between two documents changes both, so its base key is still read.\n *\n * Which way a failure falls, and why: a base document git will not show — new\n * on this branch, or a git that declines — contributes no base keys, so every\n * edge in it reads as new and is graded. Grading an edge the branch did not\n * write costs a reader one finding; skipping one it did write is the green this\n * module exists to remove.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { scanModel } from \"../../c4/source-scan.js\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { showBaseFile, type ResolvedBase } from \"../base-git.js\";\n\n/** The fields of an edge that make it the same join — shared by a parsed `Rel` and a scanned one. */\ninterface EdgeTuple {\n  source: string;\n  target: string;\n  op?: string;\n}\n\n/**\n * One edge's identity as a string a `Set` can hold. JSON rather than a joined\n * string because an element id may legally carry any separator a join would\n * pick, and two different tuples must never spell one key.\n */\nexport function edgeKey(edge: EdgeTuple): string {\n  return JSON.stringify([edge.source, edge.target, edge.op ?? null]);\n}\n\nfunction keysOf(text: string | null): string[] {\n  return text === null ? [] : (scanModel(text)?.rels ?? []).map(edgeKey);\n}\n\n/** The document as the base commit held it, or null when git will not show it (see the banner for why that is safe). */\nasync function baseText(base: ResolvedBase, rel: string): Promise<string | null> {\n  const read = await showBaseFile(base, rel);\n  return read.kind === \"ok\" ? read.bytes.toString(\"utf8\") : null;\n}\n\n/** The document as the working tree holds it, or null when the branch deleted it. */\nasync function currentText(base: ResolvedBase, rel: string): Promise<string | null> {\n  const abs = join(base.docsDir, rel);\n  return existsSync(abs) ? readFile(abs, \"utf8\") : null;\n}\n\n/**\n * The `edgeKey`s of every edge `documents` hold now and did not hold at the\n * base. `documents` are docs-relative `.likec4` paths the branch changed —\n * the caller's filter, so this module never has to know which directory the\n * fleet map lives in.\n */\nexport async function edgesSince(base: ResolvedBase, documents: readonly string[]): Promise<ReadonlySet<string>> {\n  const sides = await inOrder(documents, async (rel) => {\n    const [before, after] = await Promise.all([baseText(base, rel), currentText(base, rel)]);\n    return { before: keysOf(before), after: keysOf(after) };\n  });\n  const before = new Set(sides.flatMap((side) => side.before));\n  return new Set(sides.flatMap((side) => side.after).filter((key) => !before.has(key)));\n}\n"]}