@ybotok/loam 0.2.0-alpha.7 → 0.2.0-alpha.9

package/dist/core/diff/joins.js

@@ -0,0 +1,136 @@
+import { ownsOperation, REQUIREMENT_AXES } from "../consumers/consumers.js";
+/** The requirements one service contributes to a join — both spec files, a REMOVED one governing nothing. */
+function reqsOf(state) {
+    return REQUIREMENT_AXES.flatMap((axis) => {
+        const a = state[axis];
+        return a.kind === "read" ? a.value.filter((r) => r.kind !== "REMOVED") : [];
+    });
+}
+/** The map key a tuple is joined on between the two states. */
+function tupleKey(t) {
+    return `${t.kind}\0${t.consumer}\0${t.provider}\0${t.token}`;
+}
+/**
+ * Every cross-service join one state holds, keyed for the base/current join.
+ * The rules are the consumer index's, read off it rather than restated: both
+ * spec files for `Operations:` and `Consumes:` alike (`REQUIREMENT_AXES`), and
+ * an `Operations:` line naming an id the consumer's own contract defines is
+ * that consumer's own operation, no join onto anybody else's
+ * (`ownsOperation`). An unreadable axis simply contributes nothing here — no
+ * line from a spec file nobody could read, no ownership from a contract nobody
+ * could read — and `tupleVisible` below guards the GRADING, so a join is never
+ * called added or removed off a side nobody could read, and `ownershipFlicker`
+ * keeps one from being called so off a consumer's own contract that merely
+ * stopped or started parsing.
+ */
+export function consumerTuples(states) {
+    const providersOf = (pick) => {
+        const map = new Map();
+        for (const id of [...states.keys()].sort()) {
+            for (const token of pick(states.get(id)))
+                map.set(token, [...(map.get(token) ?? []), id]);
+        }
+        return map;
+    };
+    const opProviders = providersOf((s) => (s.openapi.kind === "read" ? s.openapi.value.map((op) => op.id) : []));
+    const msgProviders = providersOf((s) => (s.asyncapi.kind === "read" ? s.asyncapi.value.map((m) => m.name) : []));
+    const out = new Map();
+    const add = (t) => {
+        out.set(tupleKey(t), t);
+    };
+    for (const consumer of [...states.keys()].sort()) {
+        const state = states.get(consumer);
+        for (const r of reqsOf(state)) {
+            for (const op of r.operations) {
+                if (ownsOperation(state, op))
+                    continue;
+                for (const p of opProviders.get(op) ?? [])
+                    if (p !== consumer)
+                        add({ kind: "op", consumer, provider: p, token: op });
+            }
+            for (const name of r.consumes) {
+                for (const p of msgProviders.get(name) ?? [])
+                    if (p !== consumer)
+                        add({ kind: "message", consumer, provider: p, token: name });
+            }
+        }
+    }
+    return out;
+}
+/** May a tuple be graded off this side? Absence answers; unreadable does not; an ambiguous base identity answers nothing. */
+function tupleVisible(states, ambiguous, t) {
+    if (ambiguous.has(t.consumer) || ambiguous.has(t.provider))
+        return false;
+    const readable = (id, axes) => {
+        const state = states.get(id);
+        return state === undefined || axes.every((axis) => state[axis].kind !== "unreadable");
+    };
+    // Both spec files on the consumer's side, for either kind: a line in the file
+    // nobody could read may be the very one the join came or went by. NOT the
+    // consumer's own contract, although an operation join reads it: it is asked
+    // only whether the line names the consumer's OWN operation, and an
+    // unreadable contract proves no ownership (`ownsOperation`), so the line
+    // counts on that side — the index's own rule. A side holding it unread can
+    // only have MORE joins, never hide one, and suppressing the join there kept
+    // `diff.consumer-added` / `-removed` off a report whose victims named that
+    // very consumer (the contract review, finding 4). Those extra joins are a
+    // change of their own only when the readable side does not prove the
+    // ownership the unread one could not — `ownershipFlicker` below.
+    return readable(t.consumer, ["spec", "archSpec"]) && readable(t.provider, [t.kind === "op" ? "openapi" : "asyncapi"]);
+}
+/**
+ * Is this operation join held only because the consumer's own contract did not
+ * parse on the side that holds it, while on the other side it reads and
+ * defines the id? Then the line names the consumer's OWN operation — the
+ * readable side says so — and nothing about the join moved but the contract's
+ * readability: the line that never changed "went away" when the contract was
+ * fixed and "appeared" when it broke, once per provider of a shared id such as
+ * `healthCheck` (the verification of finding 4, N1). The unreadable contract
+ * is already its own `unreadable[]` entry on the consumer, which carries the
+ * run to exit 1; a second, false finding on every provider said nothing true.
+ *
+ * Only that shape is skipped. A readable side that defines no such id proves
+ * no ownership either, so the join is the line's and is graded as before; a
+ * message join asks no ownership at all (`ownsOperation` says why).
+ */
+function ownershipFlicker(sides, t) {
+    if (t.kind !== "op" || sides.holding.get(t.consumer)?.openapi.kind !== "unreadable")
+        return false;
+    const other = sides.other.get(t.consumer);
+    return other !== undefined && ownsOperation(other, t.token);
+}
+/**
+ * The joins that appeared or went away between base and current, sorted for
+ * deterministic output (provider, kind, token, consumer). The visibility
+ * guard is the containment rule: a join is never called "added" off a base
+ * side nobody could read, nor "removed" off an unreadable working file — the
+ * suspended axis already carries that fact. The flicker guard is its mirror on
+ * the side that HOLDS the join: one held only because the consumer's own
+ * contract did not read there, over an id the other side shows it owns, is no
+ * change either.
+ */
+export function consumerJoinChanges(input) {
+    const baseTuples = consumerTuples(input.base);
+    const currentTuples = consumerTuples(input.current);
+    const graded = [];
+    const added = { holding: input.current, other: input.base };
+    const removed = { holding: input.base, other: input.current };
+    for (const [key, t] of currentTuples) {
+        if (baseTuples.has(key) || ownershipFlicker(added, t))
+            continue;
+        if (tupleVisible(input.base, input.baseAmbiguous, t))
+            graded.push({ t, change: "added" });
+    }
+    for (const [key, t] of baseTuples) {
+        if (currentTuples.has(key) || ownershipFlicker(removed, t))
+            continue;
+        if (tupleVisible(input.current, input.currentAmbiguous, t))
+            graded.push({ t, change: "removed" });
+    }
+    return graded.sort((a, b) => {
+        const ka = `${a.t.provider}\0${a.t.kind}\0${a.t.token}\0${a.t.consumer}\0${a.change}`;
+        const kb = `${b.t.provider}\0${b.t.kind}\0${b.t.token}\0${b.t.consumer}\0${b.change}`;
+        return ka < kb ? -1 : 1;
+    });
+}
+//# sourceMappingURL=joins.js.map

package/dist/core/diff/joins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"joins.js","sourceRoot":"","sources":["../../../src/core/diff/joins.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The cross-service joins `loam diff` reports appearing or going away between\n * the base ref and the working tree — `diff.consumer-added` /\n * `diff.consumer-removed`.\n *\n * These lived in `./victims.ts` beside the per-removal victim index until that\n * index moved down to `core/consumers/` to become the one consumer answer the\n * coherence gate and the archive planner read too. The joins below stayed: they\n * compare two WHOLE states, which only the diff has, while the index answers\n * about one fleet.\n */\nimport type { Requirement } from \"../document/spec.js\";\nimport type { ServiceState } from \"../consumers/state.js\";\nimport { ownsOperation, REQUIREMENT_AXES } from \"../consumers/consumers.js\";\n\n/** The requirements one service contributes to a join — both spec files, a REMOVED one governing nothing. */\nfunction reqsOf(state: ServiceState): Requirement[] {\n  return REQUIREMENT_AXES.flatMap((axis) => {\n    const a = state[axis];\n    return a.kind === \"read\" ? a.value.filter((r) => r.kind !== \"REMOVED\") : [];\n  });\n}\n\n/**\n * One cross-service join: `consumer`'s living requirements name a `token` that\n * `provider`'s contract defines. The same \"who depends on what\" question the\n * consumer index (`core/consumers/consumers.ts`) answers per removal, asked\n * here of a WHOLE state — base or current — so `./semantic.ts` can report\n * joins that appeared or went away.\n */\nexport interface ConsumerTuple {\n  kind: \"op\" | \"message\";\n  consumer: string;\n  provider: string;\n  token: string;\n}\n\n/** The map key a tuple is joined on between the two states. */\nfunction tupleKey(t: ConsumerTuple): string {\n  return `${t.kind}\\0${t.consumer}\\0${t.provider}\\0${t.token}`;\n}\n\n/**\n * Every cross-service join one state holds, keyed for the base/current join.\n * The rules are the consumer index's, read off it rather than restated: both\n * spec files for `Operations:` and `Consumes:` alike (`REQUIREMENT_AXES`), and\n * an `Operations:` line naming an id the consumer's own contract defines is\n * that consumer's own operation, no join onto anybody else's\n * (`ownsOperation`). An unreadable axis simply contributes nothing here — no\n * line from a spec file nobody could read, no ownership from a contract nobody\n * could read — and `tupleVisible` below guards the GRADING, so a join is never\n * called added or removed off a side nobody could read, and `ownershipFlicker`\n * keeps one from being called so off a consumer's own contract that merely\n * stopped or started parsing.\n */\nexport function consumerTuples(states: ReadonlyMap<string, ServiceState>): Map<string, ConsumerTuple> {\n  const providersOf = (pick: (s: ServiceState) => string[]): Map<string, string[]> => {\n    const map = new Map<string, string[]>();\n    for (const id of [...states.keys()].sort()) {\n      for (const token of pick(states.get(id)!)) map.set(token, [...(map.get(token) ?? []), id]);\n    }\n    return map;\n  };\n  const opProviders = providersOf((s) => (s.openapi.kind === \"read\" ? s.openapi.value.map((op) => op.id) : []));\n  const msgProviders = providersOf((s) => (s.asyncapi.kind === \"read\" ? s.asyncapi.value.map((m) => m.name) : []));\n  const out = new Map<string, ConsumerTuple>();\n  const add = (t: ConsumerTuple): void => {\n    out.set(tupleKey(t), t);\n  };\n  for (const consumer of [...states.keys()].sort()) {\n    const state = states.get(consumer)!;\n    for (const r of reqsOf(state)) {\n      for (const op of r.operations) {\n        if (ownsOperation(state, op)) continue;\n        for (const p of opProviders.get(op) ?? []) if (p !== consumer) add({ kind: \"op\", consumer, provider: p, token: op });\n      }\n      for (const name of r.consumes) {\n        for (const p of msgProviders.get(name) ?? []) if (p !== consumer) add({ kind: \"message\", consumer, provider: p, token: name });\n      }\n    }\n  }\n  return out;\n}\n\n/** May a tuple be graded off this side? Absence answers; unreadable does not; an ambiguous base identity answers nothing. */\nfunction tupleVisible(states: ReadonlyMap<string, ServiceState>, ambiguous: ReadonlySet<string>, t: ConsumerTuple): boolean {\n  if (ambiguous.has(t.consumer) || ambiguous.has(t.provider)) return false;\n  const readable = (id: string, axes: (\"spec\" | \"archSpec\" | \"openapi\" | \"asyncapi\")[]): boolean => {\n    const state = states.get(id);\n    return state === undefined || axes.every((axis) => state[axis].kind !== \"unreadable\");\n  };\n  // Both spec files on the consumer's side, for either kind: a line in the file\n  // nobody could read may be the very one the join came or went by. NOT the\n  // consumer's own contract, although an operation join reads it: it is asked\n  // only whether the line names the consumer's OWN operation, and an\n  // unreadable contract proves no ownership (`ownsOperation`), so the line\n  // counts on that side — the index's own rule. A side holding it unread can\n  // only have MORE joins, never hide one, and suppressing the join there kept\n  // `diff.consumer-added` / `-removed` off a report whose victims named that\n  // very consumer (the contract review, finding 4). Those extra joins are a\n  // change of their own only when the readable side does not prove the\n  // ownership the unread one could not — `ownershipFlicker` below.\n  return readable(t.consumer, [\"spec\", \"archSpec\"]) && readable(t.provider, [t.kind === \"op\" ? \"openapi\" : \"asyncapi\"]);\n}\n\n/**\n * Is this operation join held only because the consumer's own contract did not\n * parse on the side that holds it, while on the other side it reads and\n * defines the id? Then the line names the consumer's OWN operation — the\n * readable side says so — and nothing about the join moved but the contract's\n * readability: the line that never changed \"went away\" when the contract was\n * fixed and \"appeared\" when it broke, once per provider of a shared id such as\n * `healthCheck` (the verification of finding 4, N1). The unreadable contract\n * is already its own `unreadable[]` entry on the consumer, which carries the\n * run to exit 1; a second, false finding on every provider said nothing true.\n *\n * Only that shape is skipped. A readable side that defines no such id proves\n * no ownership either, so the join is the line's and is graded as before; a\n * message join asks no ownership at all (`ownsOperation` says why).\n */\nfunction ownershipFlicker(sides: { holding: ReadonlyMap<string, ServiceState>; other: ReadonlyMap<string, ServiceState> }, t: ConsumerTuple): boolean {\n  if (t.kind !== \"op\" || sides.holding.get(t.consumer)?.openapi.kind !== \"unreadable\") return false;\n  const other = sides.other.get(t.consumer);\n  return other !== undefined && ownsOperation(other, t.token);\n}\n\n/** One graded cross-service join change between the two states. */\nexport interface ConsumerChange {\n  t: ConsumerTuple;\n  change: \"added\" | \"removed\";\n}\n\n/**\n * The joins that appeared or went away between base and current, sorted for\n * deterministic output (provider, kind, token, consumer). The visibility\n * guard is the containment rule: a join is never called \"added\" off a base\n * side nobody could read, nor \"removed\" off an unreadable working file — the\n * suspended axis already carries that fact. The flicker guard is its mirror on\n * the side that HOLDS the join: one held only because the consumer's own\n * contract did not read there, over an id the other side shows it owns, is no\n * change either.\n */\nexport function consumerJoinChanges(input: {\n  base: ReadonlyMap<string, ServiceState>;\n  baseAmbiguous: ReadonlySet<string>;\n  current: ReadonlyMap<string, ServiceState>;\n  currentAmbiguous: ReadonlySet<string>;\n}): ConsumerChange[] {\n  const baseTuples = consumerTuples(input.base);\n  const currentTuples = consumerTuples(input.current);\n  const graded: ConsumerChange[] = [];\n  const added = { holding: input.current, other: input.base };\n  const removed = { holding: input.base, other: input.current };\n  for (const [key, t] of currentTuples) {\n    if (baseTuples.has(key) || ownershipFlicker(added, t)) continue;\n    if (tupleVisible(input.base, input.baseAmbiguous, t)) graded.push({ t, change: \"added\" });\n  }\n  for (const [key, t] of baseTuples) {\n    if (currentTuples.has(key) || ownershipFlicker(removed, t)) continue;\n    if (tupleVisible(input.current, input.currentAmbiguous, t)) graded.push({ t, change: \"removed\" });\n  }\n  return graded.sort((a, b) => {\n    const ka = `${a.t.provider}\\0${a.t.kind}\\0${a.t.token}\\0${a.t.consumer}\\0${a.change}`;\n    const kb = `${b.t.provider}\\0${b.t.kind}\\0${b.t.token}\\0${b.t.consumer}\\0${b.change}`;\n    return ka < kb ? -1 : 1;\n  });\n}\n"]}

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

@@ -15,7 +15,9 @@
  * 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.
+ * 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
@@ -25,10 +27,17 @@
  * 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.
  *
@@ -88,6 +97,10 @@ async function changedPaths(docsDir, commit, prefix) {
 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";
 /**
@@ -134,15 +147,18 @@ export async function scopeSince(request) {
         };
     }
     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,
-        // `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.
-        landscape: changed.some((path) => inside(path, ARCHITECTURE_DIR)),
+        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 },

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

@@ -1 +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.\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 */\nimport { declineDetail, gitText } from \"../../provenance/git.js\";\nimport { repoPath, type ErrorCode } from \"../../envelope/json.js\";\nimport { resolveBase } from \"../base-git.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  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/** 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  return {\n    kind: \"scope\",\n    ref,\n    commit: base.commit,\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    landscape: changed.some((path) => inside(path, ARCHITECTURE_DIR)),\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"]}
+{"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"]}