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

package/dist/core/diff/base-state.js

@@ -0,0 +1,237 @@
+/**
+ * The base side of `loam diff`: the fleet as the base commit held it, read
+ * entirely out of git's object store (`./base-git.ts`) and parsed with the
+ * SAME parsers the living files go through — `parseRequirements`,
+ * `openapiFromText`, `asyncapiFromText` — so a base document can never read
+ * differently from the identical bytes sitting on disk.
+ *
+ * CLASSIFICATION is a second, simplified spelling of `repo/tree/walk.ts`'s
+ * rule, and that is a recorded risk, not an accident: the walk classifies a
+ * LIVE filesystem (readdir, symlinks, marker files) and cannot walk a git
+ * ref. What keeps the two honest is sharing the artifact-name table
+ * (`ARTIFACT_FILES`/`isServiceArtifactName` from `repo/paths.ts`), the
+ * marker name (`SUBSYSTEM_MARKER`) and the reserved-interior set
+ * (`RESERVED_INTERIOR` from `repo/tree/walk.ts`) instead of respelling them, and restating
+ * — exactly — the walk's SERVICE branches: (0) a directory named for a
+ * service's own interior (`adrs/`, `usecases/`, `ui/`) is classified nowhere,
+ * counts as nothing beneath its parent, and hides everything under it, because
+ * the walk never descends into one; (1) a directory holding a service
+ * artifact is a service, marker present or not (artifacts win); (2) the leaf
+ * rule — neither marker nor artifact and nothing beneath (an empty or
+ * not-yet-adopted directory, a lone README.md, a lone `.gitkeep` — which is
+ * the whole content of a directory `loam seed` creates) is a service too; (3) nothing
+ * inside a PLAIN service is classified again (`examples/openapi.yaml` two
+ * levels down is interior, the walk stops there), but a service carrying the
+ * marker BESIDE its artifacts is still descended — minus artifact-named
+ * children like `adrs/` — so the services stranded beneath it stay
+ * enumerated, the walk's marker-misplaced branch. Subsystem and unmarked
+ * group directories need no restating: a flat file listing descends through
+ * them by construction. What is deliberately NOT restated: the walk's
+ * findings (`subsystem.marker-misplaced`, `subsystem.unmarked`,
+ * `subsystem.name-collision`) — those are validate's live diagnostics; here
+ * a name claimed twice suspends the subject (`ambiguous`) instead. If
+ * walk.ts's rule ever changes, this module owes the same change;
+ * test/diff.test.ts pins the visible agreement (subsystem move, not-adopted
+ * leaf, stranded-under-marker).
+ *
+ * Deliberate consequence of joining by leaf directory name: a service MOVED
+ * between subsystems keeps its id and diffs as UNCHANGED. Subsystem placement
+ * is navigation, not identity — SCHEMA's own position, and the reason
+ * `subsystem move` never touches a join key.
+ */
+import { isUtf8 } from "node:buffer";
+import { inOrder } from "../kernel/concurrency.js";
+import { rawServiceId } from "../kernel/ids/service.js";
+import { decodeDocument } from "../kernel/document-bytes.js";
+import { parseRequirements } from "../document/parse.js";
+import { openapiFromText } from "../openapi/doc.js";
+import { asyncapiFromText } from "../asyncapi/read.js";
+import { ARTIFACT_FILES, isServiceArtifactName } from "../repo/paths.js";
+import { SUBSYSTEM_MARKER } from "../repo/tree/marker.js";
+import { RESERVED_INTERIOR } from "../repo/tree/walk.js";
+import { listBaseTree, showBaseFile } from "./base-git.js";
+import { bytesDigest, collisions } from "../consumers/state.js";
+/**
+ * Classify the base tree's file listing into service directories — the module
+ * banner's three restated walk branches, in depth order so every ancestor is
+ * decided before anything beneath it.
+ */
+function classifyBaseDirs(paths) {
+    const fileChildren = new Map();
+    const dirChildren = new Map();
+    // Directories nothing VISIBLE lives in, so neither map above names them.
+    const bare = new Set();
+    for (const path of paths) {
+        const all = path.split("/");
+        // Dot-named entries are invisible to the live walk — but the walk still
+        // SEES the directory holding them, because readdir discovered the
+        // directory itself and only its CONTENTS are filtered (walk.ts's
+        // `subdirNames` and `visitDir`). So cut the path at its first dot-named
+        // segment rather than discarding the whole path: everything above the cut
+        // stays a visible directory, the cut segment and everything beneath it
+        // stay invisible. Discarding it outright hid every directory whose only
+        // file is dot-named — which is exactly what `loam seed` writes into a
+        // service directory it creates (`.gitkeep`, and nothing else), so a seeded
+        // service was absent from the base and diffed as `diff.service-added`
+        // against the unchanged tree that had just been committed.
+        const cut = all.findIndex((s) => s.startsWith(".") || s === "");
+        const segments = cut === -1 ? all : all.slice(0, cut);
+        // Only a whole path ends in a file; a cut one is a pure directory chain.
+        const fileAt = cut === -1 ? segments.length - 1 : -1;
+        for (let i = 1; i < segments.length; i += 1) {
+            const dir = segments.slice(0, i).join("/");
+            const child = segments[i];
+            const into = i === fileAt ? fileChildren : dirChildren;
+            let set = into.get(dir);
+            if (set === undefined)
+                into.set(dir, (set = new Set()));
+            set.add(child);
+        }
+        if (fileAt === -1 && segments.length > 1)
+            bare.add(segments.join("/"));
+    }
+    const hasMarker = (dir) => fileChildren.get(dir)?.has(SUBSYSTEM_MARKER) === true;
+    const hasArtifact = (dir) => [...(fileChildren.get(dir) ?? [])].some((f) => isServiceArtifactName(f, "file")) ||
+        [...(dirChildren.get(dir) ?? [])].some((d) => isServiceArtifactName(d, "dir"));
+    // The walk's `RESERVED_INTERIOR` rule, restated for a flat listing: a
+    // directory named for a service's own interior is never classified, and
+    // neither is anything beneath it, because the walk never descends into one.
+    // Segment 2 onward, matching where the walk applies it — to a directory's
+    // CHILDREN, so a directory literally at `services/usecases/` is still
+    // classified there.
+    const reserved = (dir) => dir.split("/").slice(2).some((s) => RESERVED_INTERIOR.has(s));
+    // …and, for the same reason, one of them is not the subdirectory that keeps
+    // its parent off the leaf rule: the walk filters them out of `dirs` before
+    // asking whether anything is beneath.
+    const classifiableChildren = (dir) => [...(dirChildren.get(dir) ?? [])].some((d) => !RESERVED_INTERIOR.has(d));
+    // The walk's leaf rule: neither marker nor artifact and nothing beneath is a
+    // service. (A truly EMPTY directory is unrepresentable in a git tree, so at
+    // the base this arm means "no visible entry of ours" — files none of which
+    // are artifacts, or nothing but dot-named entries, the `loam seed` shape.)
+    const isLeafService = (dir) => !hasMarker(dir) && !hasArtifact(dir) && !classifiableChildren(dir);
+    const candidates = [...new Set([...fileChildren.keys(), ...dirChildren.keys(), ...bare])]
+        .filter((dir) => dir !== "services" && dir.startsWith("services/") && !reserved(dir))
+        .filter((dir) => hasArtifact(dir) || isLeafService(dir))
+        .sort((a, b) => {
+        const depth = a.split("/").length - b.split("/").length;
+        return depth !== 0 ? depth : a < b ? -1 : 1;
+    });
+    const accepted = [];
+    const acceptedDirs = new Set();
+    // Is this candidate INTERIOR to the nearest service already accepted above
+    // it? A plain service swallows everything beneath (the walk stops there); a
+    // marker-beside-artifacts service is descended except through its
+    // artifact-named children (`adrs/`), so a service stranded under it stays.
+    const interior = (segments) => {
+        for (let i = segments.length - 1; i >= 2; i -= 1) {
+            const ancestor = segments.slice(0, i).join("/");
+            if (!acceptedDirs.has(ancestor))
+                continue;
+            return hasMarker(ancestor) ? isServiceArtifactName(segments[i], "dir") : true;
+        }
+        return false;
+    };
+    for (const dir of candidates) {
+        const segments = dir.split("/");
+        if (interior(segments))
+            continue;
+        acceptedDirs.add(dir);
+        accepted.push({ id: rawServiceId(segments[segments.length - 1]), dir, files: fileChildren.get(dir) ?? new Set() });
+    }
+    return { dirs: accepted, ambiguous: collisions(accepted) };
+}
+/**
+ * Lift one fetched file into an axis state through its parser. Absence is the
+ * listing's answer, a `show` failure is per-subject containment, and only
+ * then do the bytes reach a parser. A parser's refusal carries the hash of
+ * the bytes it refused (`AxisState`'s `bytes`); a `show` failure has none to
+ * hash.
+ */
+function axisFrom(raw, parse) {
+    if (raw === null)
+        return { kind: "absent" };
+    if (raw.read.kind === "failed")
+        return { kind: "unreadable", path: raw.rel, error: raw.read.detail };
+    const state = parse(raw.rel, raw.read.bytes);
+    return state.kind === "unreadable" ? { ...state, bytes: bytesDigest(raw.read.bytes) } : state;
+}
+/**
+ * The same refusal `readOpenapi`/`readAsyncapi` make on the living side for a
+ * CONTRACT: non-UTF-8 bytes would be silently rewritten as U+FFFD by
+ * `toString`, and a document nobody wrote must not be graded. Contracts only:
+ * the spec axis decodes through `decodeDocument` instead (`specState`), because
+ * that is what its living side does, and each axis must refuse at the base
+ * exactly the bytes its living reader refuses.
+ */
+function decodeBase(path, bytes) {
+    if (!isUtf8(bytes))
+        return { unreadable: { kind: "unreadable", path, error: "file is not valid UTF-8" } };
+    return { text: bytes.toString("utf8") };
+}
+/**
+ * A spec-axis file decodes through `decodeDocument` — the rule the living side
+ * applies to the same file (`FleetContext.readText`) — not through
+ * `decodeBase`'s `isUtf8`-only test. The difference is the NUL test: UTF-16LE
+ * of ASCII saved WITHOUT a byte-order mark is a valid UTF-8 sequence, so
+ * `isUtf8` alone let it through here and it parsed as zero requirements while
+ * the working tree refused the identical bytes. The base then read as a
+ * readable EMPTY spec: an untouched file diffed as one-sided containment, and
+ * a branch that re-saved it as UTF-8 reported every requirement in it as
+ * added. `decodeDocument`'s `NotUtf8DocumentError` lands in the catch below
+ * and becomes the unreadable arm like any parse failure.
+ */
+function specState(path, bytes) {
+    try {
+        return { kind: "read", value: parseRequirements(decodeDocument(bytes, path)) };
+    }
+    catch (e) {
+        return { kind: "unreadable", path, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function openapiState(path, bytes) {
+    const decoded = decodeBase(path, bytes);
+    if ("unreadable" in decoded)
+        return decoded.unreadable;
+    const doc = openapiFromText(decoded.text);
+    return doc.unreadable
+        ? { kind: "unreadable", path, error: doc.error ?? "not a readable OpenAPI document" }
+        : { kind: "read", value: doc.ops.filter((op) => !op.remove) };
+}
+function asyncapiState(path, bytes) {
+    const decoded = decodeBase(path, bytes);
+    if ("unreadable" in decoded)
+        return decoded.unreadable;
+    const doc = asyncapiFromText(decoded.text);
+    return doc.unreadable
+        ? { kind: "unreadable", path, error: doc.error ?? "not a readable AsyncAPI document" }
+        : { kind: "read", value: doc.messages.filter((m) => m.remove !== true) };
+}
+/** One base service's four axes. Sequential INSIDE the service on purpose: the pool below rations children at the service grain, and four spawns per in-flight worker would multiply past the cap it exists to hold. */
+async function readBaseService(base, d) {
+    const fetch = async (file) => d.files.has(file) ? { rel: `${d.dir}/${file}`, read: await showBaseFile(base, `${d.dir}/${file}`) } : null;
+    return {
+        id: d.id,
+        dir: d.dir,
+        spec: axisFrom(await fetch(ARTIFACT_FILES.spec), specState),
+        archSpec: axisFrom(await fetch(ARTIFACT_FILES.archSpec), specState),
+        openapi: axisFrom(await fetch(ARTIFACT_FILES.openapi), openapiState),
+        asyncapi: axisFrom(await fetch(ARTIFACT_FILES.asyncapi), asyncapiState),
+    };
+}
+/**
+ * The whole base fleet. `failed` only when git cannot LIST the tree — the
+ * whole-diff refusal; a single file that cannot be shown or parsed degrades
+ * its own subject's axis to `unreadable` and nothing else.
+ */
+export async function readBaseFleet(base) {
+    const listing = await listBaseTree(base);
+    if (listing.kind === "failed")
+        return listing;
+    const { dirs, ambiguous } = classifyBaseDirs(listing.paths);
+    const sorted = [...dirs].sort((a, b) => (a.id < b.id ? -1 : 1)).filter((d) => !ambiguous.has(d.id));
+    // Pooled, ordered reads: bounded children in flight, results by input index,
+    // so the same base state always assembles the same fleet.
+    const states = await inOrder(sorted, (d) => readBaseService(base, d));
+    return { kind: "ok", fleet: { services: new Map(states.map((s) => [s.id, s])), ambiguous } };
+}
+//# sourceMappingURL=base-state.js.map

package/dist/core/diff/base-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-state.js","sourceRoot":"","sources":["../../../src/core/diff/base-state.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The base side of `loam diff`: the fleet as the base commit held it, read\n * entirely out of git's object store (`./base-git.ts`) and parsed with the\n * SAME parsers the living files go through — `parseRequirements`,\n * `openapiFromText`, `asyncapiFromText` — so a base document can never read\n * differently from the identical bytes sitting on disk.\n *\n * CLASSIFICATION is a second, simplified spelling of `repo/tree/walk.ts`'s\n * rule, and that is a recorded risk, not an accident: the walk classifies a\n * LIVE filesystem (readdir, symlinks, marker files) and cannot walk a git\n * ref. What keeps the two honest is sharing the artifact-name table\n * (`ARTIFACT_FILES`/`isServiceArtifactName` from `repo/paths.ts`), the\n * marker name (`SUBSYSTEM_MARKER`) and the reserved-interior set\n * (`RESERVED_INTERIOR` from `repo/tree/walk.ts`) instead of respelling them, and restating\n * — exactly — the walk's SERVICE branches: (0) a directory named for a\n * service's own interior (`adrs/`, `usecases/`, `ui/`) is classified nowhere,\n * counts as nothing beneath its parent, and hides everything under it, because\n * the walk never descends into one; (1) a directory holding a service\n * artifact is a service, marker present or not (artifacts win); (2) the leaf\n * rule — neither marker nor artifact and nothing beneath (an empty or\n * not-yet-adopted directory, a lone README.md, a lone `.gitkeep` — which is\n * the whole content of a directory `loam seed` creates) is a service too; (3) nothing\n * inside a PLAIN service is classified again (`examples/openapi.yaml` two\n * levels down is interior, the walk stops there), but a service carrying the\n * marker BESIDE its artifacts is still descended — minus artifact-named\n * children like `adrs/` — so the services stranded beneath it stay\n * enumerated, the walk's marker-misplaced branch. Subsystem and unmarked\n * group directories need no restating: a flat file listing descends through\n * them by construction. What is deliberately NOT restated: the walk's\n * findings (`subsystem.marker-misplaced`, `subsystem.unmarked`,\n * `subsystem.name-collision`) — those are validate's live diagnostics; here\n * a name claimed twice suspends the subject (`ambiguous`) instead. If\n * walk.ts's rule ever changes, this module owes the same change;\n * test/diff.test.ts pins the visible agreement (subsystem move, not-adopted\n * leaf, stranded-under-marker).\n *\n * Deliberate consequence of joining by leaf directory name: a service MOVED\n * between subsystems keeps its id and diffs as UNCHANGED. Subsystem placement\n * is navigation, not identity — SCHEMA's own position, and the reason\n * `subsystem move` never touches a join key.\n */\nimport { isUtf8 } from \"node:buffer\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport { rawServiceId, type RawServiceId } from \"../kernel/ids/service.js\";\nimport { decodeDocument } from \"../kernel/document-bytes.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport type { Requirement } from \"../document/spec.js\";\nimport { openapiFromText, type Operation } from \"../openapi/doc.js\";\nimport { asyncapiFromText } from \"../asyncapi/read.js\";\nimport type { EventMessage } from \"../asyncapi/model.js\";\nimport { ARTIFACT_FILES, isServiceArtifactName } from \"../repo/paths.js\";\nimport { SUBSYSTEM_MARKER } from \"../repo/tree/marker.js\";\nimport { RESERVED_INTERIOR } from \"../repo/tree/walk.js\";\nimport { listBaseTree, showBaseFile, type ResolvedBase } from \"./base-git.js\";\nimport { bytesDigest, collisions, type AxisState, type ServiceState } from \"../consumers/state.js\";\n\nexport interface BaseFleet {\n  /** By service id, insertion-sorted by id — deterministic output depends on it. */\n  services: Map<string, ServiceState>;\n  /**\n   * Ids claimed by MORE than one base directory. The live walk grades this\n   * `subsystem.name-collision`; here the id's base state is unanswerable, so\n   * the subject is carried with every axis suspended rather than one claimant\n   * silently winning the join.\n   */\n  ambiguous: Map<string, string[]>;\n}\n\nexport type BaseFleetRead =\n  | { kind: \"ok\"; fleet: BaseFleet }\n  | { kind: \"failed\"; detail: string };\n\n/** A classified base service directory and which artifact files the base tree listed in it. */\ninterface BaseDir {\n  id: RawServiceId;\n  dir: string;\n  files: Set<string>;\n}\n\n/**\n * Classify the base tree's file listing into service directories — the module\n * banner's three restated walk branches, in depth order so every ancestor is\n * decided before anything beneath it.\n */\nfunction classifyBaseDirs(paths: string[]): { dirs: BaseDir[]; ambiguous: Map<string, string[]> } {\n  const fileChildren = new Map<string, Set<string>>();\n  const dirChildren = new Map<string, Set<string>>();\n  // Directories nothing VISIBLE lives in, so neither map above names them.\n  const bare = new Set<string>();\n  for (const path of paths) {\n    const all = path.split(\"/\");\n    // Dot-named entries are invisible to the live walk — but the walk still\n    // SEES the directory holding them, because readdir discovered the\n    // directory itself and only its CONTENTS are filtered (walk.ts's\n    // `subdirNames` and `visitDir`). So cut the path at its first dot-named\n    // segment rather than discarding the whole path: everything above the cut\n    // stays a visible directory, the cut segment and everything beneath it\n    // stay invisible. Discarding it outright hid every directory whose only\n    // file is dot-named — which is exactly what `loam seed` writes into a\n    // service directory it creates (`.gitkeep`, and nothing else), so a seeded\n    // service was absent from the base and diffed as `diff.service-added`\n    // against the unchanged tree that had just been committed.\n    const cut = all.findIndex((s) => s.startsWith(\".\") || s === \"\");\n    const segments = cut === -1 ? all : all.slice(0, cut);\n    // Only a whole path ends in a file; a cut one is a pure directory chain.\n    const fileAt = cut === -1 ? segments.length - 1 : -1;\n    for (let i = 1; i < segments.length; i += 1) {\n      const dir = segments.slice(0, i).join(\"/\");\n      const child = segments[i]!;\n      const into = i === fileAt ? fileChildren : dirChildren;\n      let set = into.get(dir);\n      if (set === undefined) into.set(dir, (set = new Set()));\n      set.add(child);\n    }\n    if (fileAt === -1 && segments.length > 1) bare.add(segments.join(\"/\"));\n  }\n  const hasMarker = (dir: string): boolean => fileChildren.get(dir)?.has(SUBSYSTEM_MARKER) === true;\n  const hasArtifact = (dir: string): boolean =>\n    [...(fileChildren.get(dir) ?? [])].some((f) => isServiceArtifactName(f, \"file\")) ||\n    [...(dirChildren.get(dir) ?? [])].some((d) => isServiceArtifactName(d, \"dir\"));\n  // The walk's `RESERVED_INTERIOR` rule, restated for a flat listing: a\n  // directory named for a service's own interior is never classified, and\n  // neither is anything beneath it, because the walk never descends into one.\n  // Segment 2 onward, matching where the walk applies it — to a directory's\n  // CHILDREN, so a directory literally at `services/usecases/` is still\n  // classified there.\n  const reserved = (dir: string): boolean => dir.split(\"/\").slice(2).some((s) => RESERVED_INTERIOR.has(s));\n  // …and, for the same reason, one of them is not the subdirectory that keeps\n  // its parent off the leaf rule: the walk filters them out of `dirs` before\n  // asking whether anything is beneath.\n  const classifiableChildren = (dir: string): boolean =>\n    [...(dirChildren.get(dir) ?? [])].some((d) => !RESERVED_INTERIOR.has(d));\n  // The walk's leaf rule: neither marker nor artifact and nothing beneath is a\n  // service. (A truly EMPTY directory is unrepresentable in a git tree, so at\n  // the base this arm means \"no visible entry of ours\" — files none of which\n  // are artifacts, or nothing but dot-named entries, the `loam seed` shape.)\n  const isLeafService = (dir: string): boolean =>\n    !hasMarker(dir) && !hasArtifact(dir) && !classifiableChildren(dir);\n  const candidates = [...new Set([...fileChildren.keys(), ...dirChildren.keys(), ...bare])]\n    .filter((dir) => dir !== \"services\" && dir.startsWith(\"services/\") && !reserved(dir))\n    .filter((dir) => hasArtifact(dir) || isLeafService(dir))\n    .sort((a, b) => {\n      const depth = a.split(\"/\").length - b.split(\"/\").length;\n      return depth !== 0 ? depth : a < b ? -1 : 1;\n    });\n  const accepted: BaseDir[] = [];\n  const acceptedDirs = new Set<string>();\n  // Is this candidate INTERIOR to the nearest service already accepted above\n  // it? A plain service swallows everything beneath (the walk stops there); a\n  // marker-beside-artifacts service is descended except through its\n  // artifact-named children (`adrs/`), so a service stranded under it stays.\n  const interior = (segments: string[]): boolean => {\n    for (let i = segments.length - 1; i >= 2; i -= 1) {\n      const ancestor = segments.slice(0, i).join(\"/\");\n      if (!acceptedDirs.has(ancestor)) continue;\n      return hasMarker(ancestor) ? isServiceArtifactName(segments[i]!, \"dir\") : true;\n    }\n    return false;\n  };\n  for (const dir of candidates) {\n    const segments = dir.split(\"/\");\n    if (interior(segments)) continue;\n    acceptedDirs.add(dir);\n    accepted.push({ id: rawServiceId(segments[segments.length - 1]!), dir, files: fileChildren.get(dir) ?? new Set() });\n  }\n  return { dirs: accepted, ambiguous: collisions(accepted) };\n}\n\n/** One shown base file, or `null` for a file the base tree never listed. */\ntype Fetched = { rel: string; read: Awaited<ReturnType<typeof showBaseFile>> } | null;\n\n/**\n * Lift one fetched file into an axis state through its parser. Absence is the\n * listing's answer, a `show` failure is per-subject containment, and only\n * then do the bytes reach a parser. A parser's refusal carries the hash of\n * the bytes it refused (`AxisState`'s `bytes`); a `show` failure has none to\n * hash.\n */\nfunction axisFrom<T>(raw: Fetched, parse: (path: string, bytes: Buffer) => AxisState<T>): AxisState<T> {\n  if (raw === null) return { kind: \"absent\" };\n  if (raw.read.kind === \"failed\") return { kind: \"unreadable\", path: raw.rel, error: raw.read.detail };\n  const state = parse(raw.rel, raw.read.bytes);\n  return state.kind === \"unreadable\" ? { ...state, bytes: bytesDigest(raw.read.bytes) } : state;\n}\n\n/**\n * The same refusal `readOpenapi`/`readAsyncapi` make on the living side for a\n * CONTRACT: non-UTF-8 bytes would be silently rewritten as U+FFFD by\n * `toString`, and a document nobody wrote must not be graded. Contracts only:\n * the spec axis decodes through `decodeDocument` instead (`specState`), because\n * that is what its living side does, and each axis must refuse at the base\n * exactly the bytes its living reader refuses.\n */\nfunction decodeBase(path: string, bytes: Buffer): { text: string } | { unreadable: AxisState<never> } {\n  if (!isUtf8(bytes)) return { unreadable: { kind: \"unreadable\", path, error: \"file is not valid UTF-8\" } };\n  return { text: bytes.toString(\"utf8\") };\n}\n\n/**\n * A spec-axis file decodes through `decodeDocument` — the rule the living side\n * applies to the same file (`FleetContext.readText`) — not through\n * `decodeBase`'s `isUtf8`-only test. The difference is the NUL test: UTF-16LE\n * of ASCII saved WITHOUT a byte-order mark is a valid UTF-8 sequence, so\n * `isUtf8` alone let it through here and it parsed as zero requirements while\n * the working tree refused the identical bytes. The base then read as a\n * readable EMPTY spec: an untouched file diffed as one-sided containment, and\n * a branch that re-saved it as UTF-8 reported every requirement in it as\n * added. `decodeDocument`'s `NotUtf8DocumentError` lands in the catch below\n * and becomes the unreadable arm like any parse failure.\n */\nfunction specState(path: string, bytes: Buffer): AxisState<Requirement[]> {\n  try {\n    return { kind: \"read\", value: parseRequirements(decodeDocument(bytes, path)) };\n  } catch (e) {\n    return { kind: \"unreadable\", path, error: e instanceof Error ? e.message : String(e) };\n  }\n}\n\nfunction openapiState(path: string, bytes: Buffer): AxisState<Operation[]> {\n  const decoded = decodeBase(path, bytes);\n  if (\"unreadable\" in decoded) return decoded.unreadable;\n  const doc = openapiFromText(decoded.text);\n  return doc.unreadable\n    ? { kind: \"unreadable\", path, error: doc.error ?? \"not a readable OpenAPI document\" }\n    : { kind: \"read\", value: doc.ops.filter((op) => !op.remove) };\n}\n\nfunction asyncapiState(path: string, bytes: Buffer): AxisState<EventMessage[]> {\n  const decoded = decodeBase(path, bytes);\n  if (\"unreadable\" in decoded) return decoded.unreadable;\n  const doc = asyncapiFromText(decoded.text);\n  return doc.unreadable\n    ? { kind: \"unreadable\", path, error: doc.error ?? \"not a readable AsyncAPI document\" }\n    : { kind: \"read\", value: doc.messages.filter((m) => m.remove !== true) };\n}\n\n/** One base service's four axes. Sequential INSIDE the service on purpose: the pool below rations children at the service grain, and four spawns per in-flight worker would multiply past the cap it exists to hold. */\nasync function readBaseService(base: ResolvedBase, d: BaseDir): Promise<ServiceState> {\n  const fetch = async (file: string): Promise<Fetched> =>\n    d.files.has(file) ? { rel: `${d.dir}/${file}`, read: await showBaseFile(base, `${d.dir}/${file}`) } : null;\n  return {\n    id: d.id,\n    dir: d.dir,\n    spec: axisFrom(await fetch(ARTIFACT_FILES.spec), specState),\n    archSpec: axisFrom(await fetch(ARTIFACT_FILES.archSpec), specState),\n    openapi: axisFrom(await fetch(ARTIFACT_FILES.openapi), openapiState),\n    asyncapi: axisFrom(await fetch(ARTIFACT_FILES.asyncapi), asyncapiState),\n  };\n}\n\n/**\n * The whole base fleet. `failed` only when git cannot LIST the tree — the\n * whole-diff refusal; a single file that cannot be shown or parsed degrades\n * its own subject's axis to `unreadable` and nothing else.\n */\nexport async function readBaseFleet(base: ResolvedBase): Promise<BaseFleetRead> {\n  const listing = await listBaseTree(base);\n  if (listing.kind === \"failed\") return listing;\n  const { dirs, ambiguous } = classifyBaseDirs(listing.paths);\n  const sorted = [...dirs].sort((a, b) => (a.id < b.id ? -1 : 1)).filter((d) => !ambiguous.has(d.id));\n  // Pooled, ordered reads: bounded children in flight, results by input index,\n  // so the same base state always assembles the same fleet.\n  const states = await inOrder(sorted, (d) => readBaseService(base, d));\n  return { kind: \"ok\", fleet: { services: new Map(states.map((s) => [s.id, s])), ambiguous } };\n}\n"]}

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"]}