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

package/dist/core/diff/victims.js

@@ -0,0 +1,247 @@
+/**
+ * Who, in the CURRENT fleet, still depends on a thing the diff says was
+ * removed or deprecated — the joins that turn "an operation left the
+ * contract" into "and these named consumers break".
+ *
+ * THREE SOURCES answer that, and only the first two are copies of anything.
+ *
+ * The first two are deliberately a SECOND copy of the consumer join the
+ * coherence gate asks, built on the same shared primitives, and both copies
+ * say so:
+ *
+ *  - the operation half mirrors `core/coherence/lookups.ts`'s
+ *    `edgeConsumers`/`requirementConsumers` (landscape edges with
+ *    `metadata { op }` resolved through `serviceResolver` WITH the enumerated
+ *    fleet — the container lesson recorded there — plus other services'
+ *    living `Operations:` lines, spec.md only, exactly as that module scans);
+ *  - the message half mirrors `core/coherence/events/lookups.ts`'s
+ *    `messageConsumers` (every `consumes` edge naming the message except one
+ *    INTO the provider, plus other services' `Consumes:` lines over BOTH spec
+ *    axes — the outbox requirement lives in arch.spec.md as often as in
+ *    spec.md, that module's lesson).
+ *
+ * The copies cannot be one module today: coherence's lookups are closures
+ * over a feature's `DeltaScope` and its lazy caches; this one is an index
+ * over an already-read fleet. Rule 13 (docs/DESIGN.md) governs — a THIRD
+ * copy of this join forces the shared extraction, and whoever changes the
+ * victim strings or the scan rules in either module owes the other the same
+ * change. The victim string spellings are kept byte-compatible with the
+ * coherence findings on purpose, so a reader meets one vocabulary.
+ *
+ * The THIRD source is not a copy and does not fall under that rule: the fleet's
+ * USE CASES, joined in `core/usecases/operations.ts`. A hop of a
+ * capability-tagged `dynamic view` that the model attributes to the operation
+ * being removed is a business flow that stops working, and saying so — "step 4
+ * of Checkout breaks" — is the only one of the three that names a consequence a
+ * human weighs rather than a document they then have to open. It has its own
+ * module because it asks a different question of a different reader (an
+ * attribution over the whole `architecture/` PROJECT, not a scan of one
+ * landscape file), and because the attributed/contested distinction it turns on
+ * belongs beside `attributeStep`, not beside a requirement scan. Coherence has
+ * no equivalent to keep in step with, so nothing here owes it a mirror.
+ */
+import { existsSync } from "node:fs";
+import {} from "../c4/likec4.js";
+import { serviceResolver } from "../c4/resolve/service.js";
+import { landscapePath } from "../repo/paths.js";
+import { readUseCases } from "../usecases/fleet.js";
+import { hopsConsuming, hopsExercising } from "../usecases/operations.js";
+/** The requirements one current service contributes to a scan, per axis rule. */
+function reqsOf(state, axes) {
+    return axes.flatMap((axis) => {
+        const a = state[axis];
+        return a.kind === "read" ? a.value : [];
+    });
+}
+const EDGE = (resolve, r) => `edge ${resolve(r.source)} → ${resolve(r.target)}${r.title === undefined ? "" : ` ("${r.title}")`}`;
+/** Entry comparator by map key — deterministic suspension order. */
+const byFirst = (a, b) => (a[0] < b[0] ? -1 : 1);
+export function victimIndex(snap) {
+    // Lazy on purpose, the coherence lookups' own discipline: the landscape is
+    // a full LikeC4 workspace spin-up, and a diff that removes nothing must not
+    // pay for it. An absent landscape proves nothing; an unreadable one proves
+    // nothing either way — `landscape.invalid` is validate's finding to make,
+    // and inventing victims out of a parse error would point the reader at the
+    // wrong file (core/coherence/lookups.ts's doctrine, verbatim).
+    let drawn;
+    const landscape = () => (drawn ??= (async () => {
+        const path = landscapePath(snap.docsDir);
+        const doc = existsSync(path) ? await snap.context.loadLikeC4(path) : null;
+        const usable = doc !== null && doc.errors.length === 0 ? doc : null;
+        // The enumerated fleet rides into the resolver so a landscape that
+        // models CONTAINERS stays visible: without `known`, an edge into
+        // `payment.api` resolves to a service called "api" that has never
+        // existed and the join finds nobody — the exact defect DESIGN's
+        // serviceResolver-known row records.
+        return {
+            usable,
+            resolve: usable === null ? null : serviceResolver(usable.elements, new Set(snap.current.keys())),
+        };
+    })());
+    // Sorted, so victim order never depends on the enumeration's walk order.
+    const ids = [...snap.current.keys()].sort();
+    /**
+     * The use-case half, lazy for the same reason and one step further.
+     *
+     * `readUseCases` carries its own cheap gate — a byte scan for the reserved
+     * tag prefix — so a fleet that declares no use case never starts LikeC4 here
+     * at all, and a fleet that does pays for the `architecture/` project exactly
+     * once per `loam diff`, at the first removal that asks. The fleet set is the
+     * same one the landscape resolver above is built from, so the two halves
+     * cannot disagree about which service an element stands for.
+     */
+    let flows;
+    const useCases = () => (flows ??= readUseCases({ docsDir: snap.docsDir, known: new Set(snap.current.keys()) }));
+    /**
+     * The requirement half of one scan, `tupleVisible`'s own discipline applied
+     * to victims: an unreadable consumer axis contributes a SUSPENSION, never a
+     * silent nothing — "consuming nothing" and "loam refused to read the file"
+     * are opposite facts, and collapsing them is how a breaking removal used to
+     * grade down to a confident warning.
+     */
+    const scanRequirements = (unit) => {
+        const out = { victims: [], suspended: [] };
+        for (const other of ids.filter((id) => id !== unit.provider)) {
+            const state = snap.current.get(other);
+            for (const axis of unit.axes) {
+                const a = state[axis];
+                if (a.kind === "unreadable") {
+                    out.suspended.push(`${other} — ${a.path} could not be read, so its requirements could not be scanned`);
+                    continue;
+                }
+                if (a.kind !== "read")
+                    continue;
+                for (const r of a.value)
+                    if (unit.hit(r))
+                        out.victims.push(`${other}'s living requirement '${r.name}'`);
+            }
+        }
+        for (const [id, dirs] of [...snap.ambiguous].sort(byFirst)) {
+            if (id !== unit.provider)
+                out.suspended.push(`${id} — claimed by ${dirs.join(" and ")}, so its documents could not be scanned`);
+        }
+        return out;
+    };
+    const opConsumers = async (provider, op) => {
+        const { usable, resolve } = await landscape();
+        const scan = scanRequirements({ provider, axes: ["spec"], hit: (r) => r.operations.includes(op) });
+        const edges = [];
+        if (usable !== null && resolve !== null) {
+            for (const r of usable.relationships) {
+                if (r.op === op && resolve(r.target) === provider)
+                    edges.push(EDGE(resolve, r));
+            }
+        }
+        // Flows last in each list, deliberately: the edge and the requirement say
+        // WHICH document to open, and the flow says what the reader is about to
+        // break — so a `details[]` scanned top-down ends on the consequence.
+        const hops = hopsExercising(await useCases(), { provider, op });
+        return {
+            victims: [...edges, ...scan.victims, ...hops.breaks],
+            suspended: [...scan.suspended, ...hops.unsure],
+        };
+    };
+    const messageConsumers = async (provider, name) => {
+        const { usable, resolve } = await landscape();
+        const scan = scanRequirements({ provider, axes: ["spec", "archSpec"], hit: (r) => r.consumes.includes(name) });
+        const edges = [];
+        if (usable !== null && resolve !== null) {
+            for (const r of usable.relationships) {
+                // The message join is fleet-global, so every edge naming it counts —
+                // except one into the provider itself, whose consumption leaves with
+                // the same change (events/lookups.ts's exclusion, verbatim).
+                if (r.consumes === name && resolve(r.target) !== provider)
+                    edges.push(EDGE(resolve, r));
+            }
+        }
+        const hops = hopsConsuming(await useCases(), { provider, name });
+        return { victims: [...edges, ...scan.victims, ...hops], suspended: scan.suspended };
+    };
+    const declarers = (name) => ids.filter((id) => {
+        const axis = snap.current.get(id).asyncapi;
+        return axis.kind === "read" && axis.value.some((m) => m.name === name);
+    });
+    return { opConsumers, messageConsumers, declarers };
+}
+/** 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.
+ * Axis rules mirror the two consumer scans above: `Operations:` from spec.md
+ * only, `Consumes:` from both spec axes. Unreadable axes simply contribute
+ * nothing here — `semantic.ts` guards the GRADING so a join is never called
+ * added or removed off a side nobody could read.
+ */
+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, ["spec"])) {
+            for (const op of r.operations) {
+                for (const p of opProviders.get(op) ?? [])
+                    if (p !== consumer)
+                        add({ kind: "op", consumer, provider: p, token: op });
+            }
+        }
+        for (const r of reqsOf(state, ["spec", "archSpec"])) {
+            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");
+    };
+    return (readable(t.consumer, t.kind === "op" ? ["spec"] : ["spec", "archSpec"]) &&
+        readable(t.provider, [t.kind === "op" ? "openapi" : "asyncapi"]));
+}
+/**
+ * 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.
+ */
+export function consumerJoinChanges(input) {
+    const baseTuples = consumerTuples(input.base);
+    const currentTuples = consumerTuples(input.current);
+    const graded = [];
+    for (const [key, t] of currentTuples) {
+        if (!baseTuples.has(key) && tupleVisible(input.base, input.baseAmbiguous, t))
+            graded.push({ t, change: "added" });
+    }
+    for (const [key, t] of baseTuples) {
+        if (!currentTuples.has(key) && 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=victims.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"victims.js","sourceRoot":"","sources":["../../../src/core/diff/victims.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Who, in the CURRENT fleet, still depends on a thing the diff says was\n * removed or deprecated — the joins that turn \"an operation left the\n * contract\" into \"and these named consumers break\".\n *\n * THREE SOURCES answer that, and only the first two are copies of anything.\n *\n * The first two are deliberately a SECOND copy of the consumer join the\n * coherence gate asks, built on the same shared primitives, and both copies\n * say so:\n *\n *  - the operation half mirrors `core/coherence/lookups.ts`'s\n *    `edgeConsumers`/`requirementConsumers` (landscape edges with\n *    `metadata { op }` resolved through `serviceResolver` WITH the enumerated\n *    fleet — the container lesson recorded there — plus other services'\n *    living `Operations:` lines, spec.md only, exactly as that module scans);\n *  - the message half mirrors `core/coherence/events/lookups.ts`'s\n *    `messageConsumers` (every `consumes` edge naming the message except one\n *    INTO the provider, plus other services' `Consumes:` lines over BOTH spec\n *    axes — the outbox requirement lives in arch.spec.md as often as in\n *    spec.md, that module's lesson).\n *\n * The copies cannot be one module today: coherence's lookups are closures\n * over a feature's `DeltaScope` and its lazy caches; this one is an index\n * over an already-read fleet. Rule 13 (docs/DESIGN.md) governs — a THIRD\n * copy of this join forces the shared extraction, and whoever changes the\n * victim strings or the scan rules in either module owes the other the same\n * change. The victim string spellings are kept byte-compatible with the\n * coherence findings on purpose, so a reader meets one vocabulary.\n *\n * The THIRD source is not a copy and does not fall under that rule: the fleet's\n * USE CASES, joined in `core/usecases/operations.ts`. A hop of a\n * capability-tagged `dynamic view` that the model attributes to the operation\n * being removed is a business flow that stops working, and saying so — \"step 4\n * of Checkout breaks\" — is the only one of the three that names a consequence a\n * human weighs rather than a document they then have to open. It has its own\n * module because it asks a different question of a different reader (an\n * attribution over the whole `architecture/` PROJECT, not a scan of one\n * landscape file), and because the attributed/contested distinction it turns on\n * belongs beside `attributeStep`, not beside a requirement scan. Coherence has\n * no equivalent to keep in step with, so nothing here owes it a mirror.\n */\nimport { existsSync } from \"node:fs\";\nimport { type LoadedDoc, type Rel } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { readUseCases, type UseCaseScan } from \"../usecases/fleet.js\";\nimport { hopsConsuming, hopsExercising } from \"../usecases/operations.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { Requirement } from \"../document/spec.js\";\nimport type { ServiceState } from \"./base-state.js\";\n\n/**\n * One consumer scan's answer, honest about its own coverage. `victims` is\n * positive evidence; `suspended` names the consumers whose relevant document\n * could not be read (or whose identity is ambiguous), because a scan that\n * skipped a file loam REFUSED to read must never let the caller assert\n * \"nobody names it\" — the fail-open shape this type exists to forbid.\n */\nexport interface ConsumerScan {\n  victims: string[];\n  suspended: string[];\n}\n\n/** The current-state consumer questions `semantic.ts` asks per removal. */\nexport interface VictimIndex {\n  /** Current consumers of `provider`'s operation `op`: landscape edges into the provider, then other services' living requirements, then the use-case hops the model attributes to it (contested hops ride as suspensions). */\n  opConsumers(provider: string, op: string): Promise<ConsumerScan>;\n  /** Current consumers of message `name` a `provider` is dropping: consumes-edges (not into the provider), then other services' `Consumes:` lines over both spec axes, then the use-case hops backed by such an edge. */\n  messageConsumers(provider: string, name: string): Promise<ConsumerScan>;\n  /** Current services whose asyncapi declares `name` — positive evidence only; a message still declared elsewhere is not orphaned by one producer dropping it. */\n  declarers(name: string): string[];\n}\n\n/** The requirements one current service contributes to a scan, per axis rule. */\nfunction reqsOf(state: ServiceState, axes: readonly (\"spec\" | \"archSpec\")[]): Requirement[] {\n  return axes.flatMap((axis) => {\n    const a = state[axis];\n    return a.kind === \"read\" ? a.value : [];\n  });\n}\n\nconst EDGE = (resolve: (id: string) => string, r: Rel): string =>\n  `edge ${resolve(r.source)} → ${resolve(r.target)}${r.title === undefined ? \"\" : ` (\"${r.title}\")`}`;\n\n/** Entry comparator by map key — deterministic suspension order. */\nconst byFirst = <T>(a: [string, T], b: [string, T]): number => (a[0] < b[0] ? -1 : 1);\n\n/** The landscape half of the index, loaded at most once and only when a removal actually asks. */\ninterface Drawn {\n  usable: LoadedDoc | null;\n  resolve: ((id: string) => string) | null;\n}\n\nexport function victimIndex(snap: {\n  docsDir: DocsDir;\n  context: FleetContext;\n  current: ReadonlyMap<string, ServiceState>;\n  /** Ids the working tree claims twice (current-state.ts) — their documents cannot be scanned, so they ride as suspended consumers. */\n  ambiguous: ReadonlyMap<string, string[]>;\n}): VictimIndex {\n  // Lazy on purpose, the coherence lookups' own discipline: the landscape is\n  // a full LikeC4 workspace spin-up, and a diff that removes nothing must not\n  // pay for it. An absent landscape proves nothing; an unreadable one proves\n  // nothing either way — `landscape.invalid` is validate's finding to make,\n  // and inventing victims out of a parse error would point the reader at the\n  // wrong file (core/coherence/lookups.ts's doctrine, verbatim).\n  let drawn: Promise<Drawn> | undefined;\n  const landscape = (): Promise<Drawn> =>\n    (drawn ??= (async (): Promise<Drawn> => {\n      const path = landscapePath(snap.docsDir);\n      const doc: LoadedDoc | null = existsSync(path) ? await snap.context.loadLikeC4(path) : null;\n      const usable = doc !== null && doc.errors.length === 0 ? doc : null;\n      // The enumerated fleet rides into the resolver so a landscape that\n      // models CONTAINERS stays visible: without `known`, an edge into\n      // `payment.api` resolves to a service called \"api\" that has never\n      // existed and the join finds nobody — the exact defect DESIGN's\n      // serviceResolver-known row records.\n      return {\n        usable,\n        resolve: usable === null ? null : serviceResolver(usable.elements, new Set(snap.current.keys())),\n      };\n    })());\n\n  // Sorted, so victim order never depends on the enumeration's walk order.\n  const ids = [...snap.current.keys()].sort();\n\n  /**\n   * The use-case half, lazy for the same reason and one step further.\n   *\n   * `readUseCases` carries its own cheap gate — a byte scan for the reserved\n   * tag prefix — so a fleet that declares no use case never starts LikeC4 here\n   * at all, and a fleet that does pays for the `architecture/` project exactly\n   * once per `loam diff`, at the first removal that asks. The fleet set is the\n   * same one the landscape resolver above is built from, so the two halves\n   * cannot disagree about which service an element stands for.\n   */\n  let flows: Promise<UseCaseScan> | undefined;\n  const useCases = (): Promise<UseCaseScan> =>\n    (flows ??= readUseCases({ docsDir: snap.docsDir, known: new Set(snap.current.keys()) }));\n\n  /**\n   * The requirement half of one scan, `tupleVisible`'s own discipline applied\n   * to victims: an unreadable consumer axis contributes a SUSPENSION, never a\n   * silent nothing — \"consuming nothing\" and \"loam refused to read the file\"\n   * are opposite facts, and collapsing them is how a breaking removal used to\n   * grade down to a confident warning.\n   */\n  const scanRequirements = (unit: { provider: string; axes: readonly (\"spec\" | \"archSpec\")[]; hit: (r: Requirement) => boolean }): ConsumerScan => {\n    const out: ConsumerScan = { victims: [], suspended: [] };\n    for (const other of ids.filter((id) => id !== unit.provider)) {\n      const state = snap.current.get(other)!;\n      for (const axis of unit.axes) {\n        const a = state[axis];\n        if (a.kind === \"unreadable\") {\n          out.suspended.push(`${other} — ${a.path} could not be read, so its requirements could not be scanned`);\n          continue;\n        }\n        if (a.kind !== \"read\") continue;\n        for (const r of a.value) if (unit.hit(r)) out.victims.push(`${other}'s living requirement '${r.name}'`);\n      }\n    }\n    for (const [id, dirs] of [...snap.ambiguous].sort(byFirst)) {\n      if (id !== unit.provider) out.suspended.push(`${id} — claimed by ${dirs.join(\" and \")}, so its documents could not be scanned`);\n    }\n    return out;\n  };\n\n  const opConsumers = async (provider: string, op: string): Promise<ConsumerScan> => {\n    const { usable, resolve } = await landscape();\n    const scan = scanRequirements({ provider, axes: [\"spec\"], hit: (r) => r.operations.includes(op) });\n    const edges: string[] = [];\n    if (usable !== null && resolve !== null) {\n      for (const r of usable.relationships) {\n        if (r.op === op && resolve(r.target) === provider) edges.push(EDGE(resolve, r));\n      }\n    }\n    // Flows last in each list, deliberately: the edge and the requirement say\n    // WHICH document to open, and the flow says what the reader is about to\n    // break — so a `details[]` scanned top-down ends on the consequence.\n    const hops = hopsExercising(await useCases(), { provider, op });\n    return {\n      victims: [...edges, ...scan.victims, ...hops.breaks],\n      suspended: [...scan.suspended, ...hops.unsure],\n    };\n  };\n\n  const messageConsumers = async (provider: string, name: string): Promise<ConsumerScan> => {\n    const { usable, resolve } = await landscape();\n    const scan = scanRequirements({ provider, axes: [\"spec\", \"archSpec\"], hit: (r) => r.consumes.includes(name) });\n    const edges: string[] = [];\n    if (usable !== null && resolve !== null) {\n      for (const r of usable.relationships) {\n        // The message join is fleet-global, so every edge naming it counts —\n        // except one into the provider itself, whose consumption leaves with\n        // the same change (events/lookups.ts's exclusion, verbatim).\n        if (r.consumes === name && resolve(r.target) !== provider) edges.push(EDGE(resolve, r));\n      }\n    }\n    const hops = hopsConsuming(await useCases(), { provider, name });\n    return { victims: [...edges, ...scan.victims, ...hops], suspended: scan.suspended };\n  };\n\n  const declarers = (name: string): string[] =>\n    ids.filter((id) => {\n      const axis = snap.current.get(id)!.asyncapi;\n      return axis.kind === \"read\" && axis.value.some((m) => m.name === name);\n    });\n\n  return { opConsumers, messageConsumers, declarers };\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 * index above answers per removal, asked here of a WHOLE state — base or\n * current — so `semantic.ts` can report 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 * Axis rules mirror the two consumer scans above: `Operations:` from spec.md\n * only, `Consumes:` from both spec axes. Unreadable axes simply contribute\n * nothing here — `semantic.ts` guards the GRADING so a join is never called\n * added or removed off a side nobody could read.\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, [\"spec\"])) {\n      for (const op of r.operations) {\n        for (const p of opProviders.get(op) ?? []) if (p !== consumer) add({ kind: \"op\", consumer, provider: p, token: op });\n      }\n    }\n    for (const r of reqsOf(state, [\"spec\", \"archSpec\"])) {\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  return (\n    readable(t.consumer, t.kind === \"op\" ? [\"spec\"] : [\"spec\", \"archSpec\"]) &&\n    readable(t.provider, [t.kind === \"op\" ? \"openapi\" : \"asyncapi\"])\n  );\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.\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  for (const [key, t] of currentTuples) {\n    if (!baseTuples.has(key) && tupleVisible(input.base, input.baseAmbiguous, t)) graded.push({ t, change: \"added\" });\n  }\n  for (const [key, t] of baseTuples) {\n    if (!currentTuples.has(key) && 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/docs.js

@@ -11,8 +11,10 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { AGENTS_MD } from "./agent.js";
-import { AGENTS_FILENAME } from "./repo.js";
+import { AGENTS_MD } from "./agent/agents-md.js";
+import { LANDSCAPE_STUB } from "./scaffold/landscape.js";
+import { README_FILENAME, README_MD } from "./scaffold/readme.js";
+import { AGENTS_FILENAME } from "./repo/paths.js";
 /**
  * Top-level layout of the shared docs repo, and part of its identity rather
  * than a convenience: `services/` is what makes a directory a docs repo —
@@ -30,68 +32,6 @@ const EMPTY_SUBDIRS = [
     ["services", ".gitkeep"],
     ["features", ".gitkeep"],
 ];
-/**
- * The fleet map, empty but valid.
- *
- * Nobody writes this file automatically — `adopt` deliberately does not touch
- * it, because who calls whom is a human judgement and a generated landscape
- * would be a guess presented as the map. But "nobody writes it" used to mean
- * "it is simply absent", and an absent landscape is the one artifact whose
- * absence silences the fleet-wide checks entirely: every cross-service breach
- * `validate` exists to find is invisible on a repo with no landscape.
- *
- * So the scaffold lays down the empty map instead: the four element kinds a
- * fleet actually uses are declared, the model is empty, and the comments say
- * what to add and why. The first `loam adopt` then has somewhere to be drawn.
- *
- * No `views` block, deliberately. loam reads elements and relationships and
- * never a view, so the scaffolded `view index { include * }` was a diagram loam
- * planted on every repo and then never drew — and views are the expensive half
- * of LikeC4: computing them is superlinear in edge count (120 services / 300
- * calls does not finish in three minutes; parsing the same file takes 11 ms).
- * loam stopped computing views, so the block is free for loam itself now, but
- * scaffolding one still hands the user a fleet-sized bill for the first tool
- * that does compute it. Teams who want diagrams declare their own.
- */
-const LANDSCAPE_STUB = `// The fleet map: every service in services/ appears here, and every call
-// between two of them is an edge. This file is written by hand — loam never
-// guesses it, because "who calls whom" is the one fact no generator can read
-// off a repository.
-//
-// After \`loam adopt --service <id>\`, add the service here:
-//
-//   paymentService = softwareSystem 'payment-service' {
-//     description 'Owns payment authorization/capture'
-//     metadata { service 'payment-service' }   // binds the box to services/<id>/
-//   }
-//
-// and give each call the operationId it uses, so requirements, C4 and OpenAPI
-// can be cross-checked:
-//
-//   checkoutWeb -> paymentService 'Authorizes' {
-//     metadata { op 'authorizePayment' }
-//   }
-//
-// There is no \`views\` block, on purpose: loam reads the model and never a
-// view, so it would draw nothing. Add views here if you want diagrams, and
-// render them with LikeC4's own tooling — \`npx likec4 start\` from the docs
-// repo root, which likec4.config.json scopes to this directory. (A service
-// model or a feature delta renders from its OWN directory, e.g.
-// \`npx likec4 start services/<id>\`: each declares its own \`specification\`
-// block, so the renderer can only be given one of them at a time.) Scope your
-// views, because computing one is superlinear in the number of edges and an
-// \`include *\` over a whole fleet takes minutes.
-
-specification {
-  element person
-  element softwareSystem
-  element container
-  element database
-}
-
-model {
-}
-`;
 /**
  * The LikeC4 project file, and the one thing in the docs repo loam writes for a
  * tool other than itself.
@@ -183,6 +123,9 @@ export async function scaffoldDocs(docsDir) {
 export function docsRepoFiles(opts = {}) {
     const preamble = opts.landscapePreamble === undefined ? "" : `${opts.landscapePreamble.trimEnd()}\n//\n`;
     return [
+        // The one file addressed to a person, first because a forge renders it as
+        // the landing page and a reader meets it before anything else here.
+        [README_FILENAME, README_MD],
         // The process contract lives with the docs it describes, so an agent handed
         // only the docs repo still knows the cycle.
         [AGENTS_FILENAME, AGENTS_MD],

package/dist/core/docs.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/core/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,cAAc,EAAE,UAAU,EAAE,UAAU,CAAU,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,aAAa,GAAG;IACpB,CAAC,UAAU,EAAE,UAAU,CAAC;IACxB,CAAC,UAAU,EAAE,UAAU,CAAC;CAChB,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAE5D,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,IAAI,CAAC,SAAS,CACpD;IACE,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,iBAAiB;IACxB,OAAO,EAAE,CAAC,oBAAoB,EAAE,aAAa,EAAE,aAAa,CAAC;CAC9D,EACD,IAAI,EACJ,CAAC,CACF,IAAI,CAAC;AAEN;;;;;;;;GAQG;AACH,MAAM,OAAO,GAAG,EAAE,CAAC;AAEnB;;;;;;;;;GASG;AACH,MAAM,gBAAgB,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAO1E,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAe;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YACnB,MAAM,KAAK,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,6EAA6E;IAC7E,mEAAmE;IACnE,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,aAAa,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YACvC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAiBD;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,IAAI,GAAwB,EAAE;IAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC;IACzG,OAAO;QACL,4EAA4E;QAC5E,4CAA4C;QAC5C,CAAC,eAAe,EAAE,SAAS,CAAC;QAC5B,CAAC,IAAI,CAAC,cAAc,EAAE,kBAAkB,CAAC,EAAE,GAAG,QAAQ,GAAG,cAAc,EAAE,CAAC;QAC1E,CAAC,WAAW,EAAE,gBAAgB,CAAC;QAC/B,CAAC,uBAAuB,EAAE,qBAAqB,CAAC;QAChD,sEAAsE;QACtE,oEAAoE;QACpE,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,CAAqB,CAAC;KACtF,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO;QACL,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACzC,GAAG,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;KACnD,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Scaffolding for the shared docs repo.\n *\n * There is deliberately no manifest. `init` used to write a `loam.docs.json`\n * listing the repo's services; nothing ever read it — `repo.ts` enumerates from\n * the filesystem, because files are the source of truth — and nothing ever\n * updated it, so it named an empty fleet forever. A second list of services is\n * exactly the drift `loam validate` now cross-checks the landscape for; the\n * cheapest way to keep it honest is not to have it.\n */\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { AGENTS_MD } from \"./agent.js\";\nimport { AGENTS_FILENAME } from \"./repo.js\";\n\n/**\n * Top-level layout of the shared docs repo, and part of its identity rather\n * than a convenience: `services/` is what makes a directory a docs repo —\n * `init` will not join one without it, and every enumerating command refuses a\n * `docsDir` that has none. So it is laid down even when nothing is in it yet.\n */\nexport const DOCS_SUBDIRS = [\"architecture\", \"services\", \"features\"] as const;\n\n/**\n * The scaffolded directories that start out empty, and the file that keeps each\n * of them in version control. See {@link GITKEEP}. Spelled as pairs so the\n * marker's name is written once — `listServices` and `listFeatures` enumerate\n * subdirectories only, so a file here is invisible to both.\n */\nconst EMPTY_SUBDIRS = [\n  [\"services\", \".gitkeep\"],\n  [\"features\", \".gitkeep\"],\n] as const;\n\n/**\n * The fleet map, empty but valid.\n *\n * Nobody writes this file automatically — `adopt` deliberately does not touch\n * it, because who calls whom is a human judgement and a generated landscape\n * would be a guess presented as the map. But \"nobody writes it\" used to mean\n * \"it is simply absent\", and an absent landscape is the one artifact whose\n * absence silences the fleet-wide checks entirely: every cross-service breach\n * `validate` exists to find is invisible on a repo with no landscape.\n *\n * So the scaffold lays down the empty map instead: the four element kinds a\n * fleet actually uses are declared, the model is empty, and the comments say\n * what to add and why. The first `loam adopt` then has somewhere to be drawn.\n *\n * No `views` block, deliberately. loam reads elements and relationships and\n * never a view, so the scaffolded `view index { include * }` was a diagram loam\n * planted on every repo and then never drew — and views are the expensive half\n * of LikeC4: computing them is superlinear in edge count (120 services / 300\n * calls does not finish in three minutes; parsing the same file takes 11 ms).\n * loam stopped computing views, so the block is free for loam itself now, but\n * scaffolding one still hands the user a fleet-sized bill for the first tool\n * that does compute it. Teams who want diagrams declare their own.\n */\nconst LANDSCAPE_STUB = `// The fleet map: every service in services/ appears here, and every call\n// between two of them is an edge. This file is written by hand — loam never\n// guesses it, because \"who calls whom\" is the one fact no generator can read\n// off a repository.\n//\n// After \\`loam adopt --service <id>\\`, add the service here:\n//\n//   paymentService = softwareSystem 'payment-service' {\n//     description 'Owns payment authorization/capture'\n//     metadata { service 'payment-service' }   // binds the box to services/<id>/\n//   }\n//\n// and give each call the operationId it uses, so requirements, C4 and OpenAPI\n// can be cross-checked:\n//\n//   checkoutWeb -> paymentService 'Authorizes' {\n//     metadata { op 'authorizePayment' }\n//   }\n//\n// There is no \\`views\\` block, on purpose: loam reads the model and never a\n// view, so it would draw nothing. Add views here if you want diagrams, and\n// render them with LikeC4's own tooling — \\`npx likec4 start\\` from the docs\n// repo root, which likec4.config.json scopes to this directory. (A service\n// model or a feature delta renders from its OWN directory, e.g.\n// \\`npx likec4 start services/<id>\\`: each declares its own \\`specification\\`\n// block, so the renderer can only be given one of them at a time.) Scope your\n// views, because computing one is superlinear in the number of edges and an\n// \\`include *\\` over a whole fleet takes minutes.\n\nspecification {\n  element person\n  element softwareSystem\n  element container\n  element database\n}\n\nmodel {\n}\n`;\n\n/**\n * The LikeC4 project file, and the one thing in the docs repo loam writes for a\n * tool other than itself.\n *\n * LikeC4's workspace loader merges EVERY `.likec4` file under a directory tree\n * into one model. loam's layout is the opposite by design: the landscape,\n * each `services/<id>/model.likec4` and each `features/<FEAT>/delta.likec4` is\n * parsed in isolation (`loadSource`, one file, one throwaway workspace), so\n * every one of them legitimately declares its own `specification { … }` block\n * and re-declares the elements it needs to talk about. Point the real renderer\n * at the repository root and those declarations collide: on loam's own\n * `examples/docs` — four files — `npx likec4 start` reported 16 errors, sixteen\n * duplicate kinds and names, while `loam validate --all` reported none. Both\n * were right; only one of them was reading the tree as a workspace.\n *\n * So the root is declared as one LikeC4 project holding the landscape, and the\n * two directories whose files are meant to be read alone are excluded from it.\n * That makes `npx likec4 start` in the docs repo — the command loam's own docs\n * have always recommended — render the fleet map instead of failing. A service\n * model or a feature delta is still rendered by pointing the renderer at its own\n * directory, which is what parsing them in isolation meant all along.\n *\n * `**\\/node_modules/**` is repeated because naming `exclude` replaces LikeC4's\n * default rather than adding to it. loam reads none of this file: it is written\n * once, never re-read, and a team that wants a different project layout owns it\n * like every other scaffolded file.\n */\nexport const LIKEC4_PROJECT_FILENAME = \"likec4.config.json\";\n\nexport const LIKEC4_PROJECT_CONFIG = `${JSON.stringify(\n  {\n    name: \"fleet\",\n    title: \"Fleet landscape\",\n    exclude: [\"**/node_modules/**\", \"services/**\", \"features/**\"],\n  },\n  null,\n  2,\n)}\\n`;\n\n/**\n * The placeholder that makes an empty scaffolded directory survive a clone.\n *\n * git tracks files, not directories, so `services/` and `features/` — created\n * empty by `loam init --create` — were absent for everyone after the first push:\n * the person who ran init had a green repo, and the second person to clone it\n * got `doctor.services-missing`, a BLOCKER, on a repository nobody had touched.\n * A repo that cannot survive being cloned is not a shared docs repo.\n */\nconst GITKEEP = \"\";\n\n/**\n * The docs repo's own loam.json. It makes the docs repo self-describing: a\n * command run from inside it (or from any directory under it) finds this file\n * first and resolves the fleet to the repo it is standing in, instead of\n * walking out to whatever service repo happens to be above.\n *\n * `\".\"` and not an absolute path for the same reason every other docsDir is\n * stored as written: this file is committed and cloned to machines whose\n * directory layout nobody here can predict.\n */\nconst DOCS_SELF_CONFIG = `${JSON.stringify({ docsDir: \".\" }, null, 2)}\\n`;\n\nexport interface ScaffoldResult {\n  root: string;\n  created: string[];\n}\n\n/** Idempotently create the docs-repo skeleton. Existing files/dirs are left untouched. */\nexport async function scaffoldDocs(docsDir: string): Promise<ScaffoldResult> {\n  const root = resolve(docsDir);\n  const created: string[] = [];\n\n  await mkdir(root, { recursive: true });\n\n  for (const dir of DOCS_SUBDIRS) {\n    const p = join(root, dir);\n    if (!existsSync(p)) {\n      await mkdir(p, { recursive: true });\n      created.push(p);\n    }\n  }\n\n  // Never overwritten, all three of them — a team's own house rules, their own\n  // map and their own config outrank the template. The order here IS the order\n  // `init` probes for what it will skip; keep the two lists in step.\n  for (const [rel, content] of docsRepoFiles()) {\n    const path = join(root, rel);\n    if (!existsSync(path)) {\n      await writeFile(path, content, \"utf8\");\n      created.push(path);\n    }\n  }\n\n  return { root, created };\n}\n\nexport interface DocsRepoFileOptions {\n  /**\n   * Comment lines prepended to the landscape stub, for a scaffold with a reason\n   * of its own to hand over an empty map — `migrate-openspec` stages a docs repo\n   * out of a corpus that HAS no topology, and says so where the migrator reads.\n   *\n   * A parameter and not a second template on purpose. The rest of the stub —\n   * how to declare a service, how to bind an edge to an operationId, why there\n   * is no `views` block — is the same advice however the repo came to exist, and\n   * the migration used to carry its own shorter copy of it: two files that were\n   * both correct on the day they were written and could only diverge after.\n   */\n  landscapePreamble?: string;\n}\n\n/**\n * The files every docs repo starts with, relative to its root, in creation\n * order. `init` scaffolds them directly; `migrate-openspec` stages the same\n * bytes into its target, because the whole point of migrating into a docs repo\n * is that it be the docs repo `loam init` makes.\n *\n * Exported as paths only (via `plannedDocsFiles`) where `init` reports what it\n * will skip — a duplicate list is exactly the drift that made `created +\n * skipped` disagree with reality.\n */\nexport function docsRepoFiles(opts: DocsRepoFileOptions = {}): Array<[string, string]> {\n  const preamble = opts.landscapePreamble === undefined ? \"\" : `${opts.landscapePreamble.trimEnd()}\\n//\\n`;\n  return [\n    // The process contract lives with the docs it describes, so an agent handed\n    // only the docs repo still knows the cycle.\n    [AGENTS_FILENAME, AGENTS_MD],\n    [join(\"architecture\", \"landscape.likec4\"), `${preamble}${LANDSCAPE_STUB}`],\n    [\"loam.json\", DOCS_SELF_CONFIG],\n    [LIKEC4_PROJECT_FILENAME, LIKEC4_PROJECT_CONFIG],\n    // The two directories git would otherwise drop on the way to the next\n    // clone. `architecture/` needs none — the landscape above is in it.\n    ...EMPTY_SUBDIRS.map(([dir, keep]) => [join(dir, keep), GITKEEP] as [string, string]),\n  ];\n}\n\n/** Everything `scaffoldDocs(docsDir)` would create, in the order it creates it. */\nexport function plannedDocsFiles(docsDir: string): string[] {\n  const root = resolve(docsDir);\n  return [\n    ...DOCS_SUBDIRS.map((d) => join(root, d)),\n    ...docsRepoFiles().map(([rel]) => join(root, rel)),\n  ];\n}\n"]}
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/core/docs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Scaffolding for the shared docs repo.\n *\n * There is deliberately no manifest. `init` used to write a `loam.docs.json`\n * listing the repo's services; nothing ever read it — `repo.ts` enumerates from\n * the filesystem, because files are the source of truth — and nothing ever\n * updated it, so it named an empty fleet forever. A second list of services is\n * exactly the drift `loam validate` now cross-checks the landscape for; the\n * cheapest way to keep it honest is not to have it.\n */\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { AGENTS_MD } from \"./agent/agents-md.js\";\nimport { LANDSCAPE_STUB } from \"./scaffold/landscape.js\";\nimport { README_FILENAME, README_MD } from \"./scaffold/readme.js\";\nimport { AGENTS_FILENAME } from \"./repo/paths.js\";\n\n/**\n * Top-level layout of the shared docs repo, and part of its identity rather\n * than a convenience: `services/` is what makes a directory a docs repo —\n * `init` will not join one without it, and every enumerating command refuses a\n * `docsDir` that has none. So it is laid down even when nothing is in it yet.\n */\nexport const DOCS_SUBDIRS = [\"architecture\", \"services\", \"features\"] as const;\n\n/**\n * The scaffolded directories that start out empty, and the file that keeps each\n * of them in version control. See {@link GITKEEP}. Spelled as pairs so the\n * marker's name is written once — `listServices` and `listFeatures` enumerate\n * subdirectories only, so a file here is invisible to both.\n */\nconst EMPTY_SUBDIRS = [\n  [\"services\", \".gitkeep\"],\n  [\"features\", \".gitkeep\"],\n] as const;\n\n/**\n * The LikeC4 project file, and the one thing in the docs repo loam writes for a\n * tool other than itself.\n *\n * LikeC4's workspace loader merges EVERY `.likec4` file under a directory tree\n * into one model. loam's layout is the opposite by design: the landscape,\n * each `services/<id>/model.likec4` and each `features/<FEAT>/delta.likec4` is\n * parsed in isolation (`loadSource`, one file, one throwaway workspace), so\n * every one of them legitimately declares its own `specification { … }` block\n * and re-declares the elements it needs to talk about. Point the real renderer\n * at the repository root and those declarations collide: on loam's own\n * `examples/docs` — four files — `npx likec4 start` reported 16 errors, sixteen\n * duplicate kinds and names, while `loam validate --all` reported none. Both\n * were right; only one of them was reading the tree as a workspace.\n *\n * So the root is declared as one LikeC4 project holding the landscape, and the\n * two directories whose files are meant to be read alone are excluded from it.\n * That makes `npx likec4 start` in the docs repo — the command loam's own docs\n * have always recommended — render the fleet map instead of failing. A service\n * model or a feature delta is still rendered by pointing the renderer at its own\n * directory, which is what parsing them in isolation meant all along.\n *\n * `**\\/node_modules/**` is repeated because naming `exclude` replaces LikeC4's\n * default rather than adding to it. loam reads none of this file: it is written\n * once, never re-read, and a team that wants a different project layout owns it\n * like every other scaffolded file.\n */\nexport const LIKEC4_PROJECT_FILENAME = \"likec4.config.json\";\n\nexport const LIKEC4_PROJECT_CONFIG = `${JSON.stringify(\n  {\n    name: \"fleet\",\n    title: \"Fleet landscape\",\n    exclude: [\"**/node_modules/**\", \"services/**\", \"features/**\"],\n  },\n  null,\n  2,\n)}\\n`;\n\n/**\n * The placeholder that makes an empty scaffolded directory survive a clone.\n *\n * git tracks files, not directories, so `services/` and `features/` — created\n * empty by `loam init --create` — were absent for everyone after the first push:\n * the person who ran init had a green repo, and the second person to clone it\n * got `doctor.services-missing`, a BLOCKER, on a repository nobody had touched.\n * A repo that cannot survive being cloned is not a shared docs repo.\n */\nconst GITKEEP = \"\";\n\n/**\n * The docs repo's own loam.json. It makes the docs repo self-describing: a\n * command run from inside it (or from any directory under it) finds this file\n * first and resolves the fleet to the repo it is standing in, instead of\n * walking out to whatever service repo happens to be above.\n *\n * `\".\"` and not an absolute path for the same reason every other docsDir is\n * stored as written: this file is committed and cloned to machines whose\n * directory layout nobody here can predict.\n */\nconst DOCS_SELF_CONFIG = `${JSON.stringify({ docsDir: \".\" }, null, 2)}\\n`;\n\nexport interface ScaffoldResult {\n  root: string;\n  created: string[];\n}\n\n/** Idempotently create the docs-repo skeleton. Existing files/dirs are left untouched. */\nexport async function scaffoldDocs(docsDir: string): Promise<ScaffoldResult> {\n  const root = resolve(docsDir);\n  const created: string[] = [];\n\n  await mkdir(root, { recursive: true });\n\n  for (const dir of DOCS_SUBDIRS) {\n    const p = join(root, dir);\n    if (!existsSync(p)) {\n      await mkdir(p, { recursive: true });\n      created.push(p);\n    }\n  }\n\n  // Never overwritten, all three of them — a team's own house rules, their own\n  // map and their own config outrank the template. The order here IS the order\n  // `init` probes for what it will skip; keep the two lists in step.\n  for (const [rel, content] of docsRepoFiles()) {\n    const path = join(root, rel);\n    if (!existsSync(path)) {\n      await writeFile(path, content, \"utf8\");\n      created.push(path);\n    }\n  }\n\n  return { root, created };\n}\n\nexport interface DocsRepoFileOptions {\n  /**\n   * Comment lines prepended to the landscape stub, for a scaffold with a reason\n   * of its own to hand over an empty map — `migrate-openspec` stages a docs repo\n   * out of a corpus that HAS no topology, and says so where the migrator reads.\n   *\n   * A parameter and not a second template on purpose. The rest of the stub —\n   * how to declare a service, how to bind an edge to an operationId, why there\n   * is no `views` block — is the same advice however the repo came to exist, and\n   * the migration used to carry its own shorter copy of it: two files that were\n   * both correct on the day they were written and could only diverge after.\n   */\n  landscapePreamble?: string;\n}\n\n/**\n * The files every docs repo starts with, relative to its root, in creation\n * order. `init` scaffolds them directly; `migrate-openspec` stages the same\n * bytes into its target, because the whole point of migrating into a docs repo\n * is that it be the docs repo `loam init` makes.\n *\n * Exported as paths only (via `plannedDocsFiles`) where `init` reports what it\n * will skip — a duplicate list is exactly the drift that made `created +\n * skipped` disagree with reality.\n */\nexport function docsRepoFiles(opts: DocsRepoFileOptions = {}): Array<[string, string]> {\n  const preamble = opts.landscapePreamble === undefined ? \"\" : `${opts.landscapePreamble.trimEnd()}\\n//\\n`;\n  return [\n    // The one file addressed to a person, first because a forge renders it as\n    // the landing page and a reader meets it before anything else here.\n    [README_FILENAME, README_MD],\n    // The process contract lives with the docs it describes, so an agent handed\n    // only the docs repo still knows the cycle.\n    [AGENTS_FILENAME, AGENTS_MD],\n    [join(\"architecture\", \"landscape.likec4\"), `${preamble}${LANDSCAPE_STUB}`],\n    [\"loam.json\", DOCS_SELF_CONFIG],\n    [LIKEC4_PROJECT_FILENAME, LIKEC4_PROJECT_CONFIG],\n    // The two directories git would otherwise drop on the way to the next\n    // clone. `architecture/` needs none — the landscape above is in it.\n    ...EMPTY_SUBDIRS.map(([dir, keep]) => [join(dir, keep), GITKEEP] as [string, string]),\n  ];\n}\n\n/** Everything `scaffoldDocs(docsDir)` would create, in the order it creates it. */\nexport function plannedDocsFiles(docsDir: string): string[] {\n  const root = resolve(docsDir);\n  return [\n    ...DOCS_SUBDIRS.map((d) => join(root, d)),\n    ...docsRepoFiles().map(([rel]) => join(root, rel)),\n  ];\n}\n"]}