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

package/dist/core/diff/semantic.js

@@ -0,0 +1,312 @@
+/**
+ * The diff computation: join the base fleet (`./base-state.ts`) against the
+ * working tree (`core/consumers/current.ts`) and say, per service, what changed in
+ * FLEET-MEANINGFUL terms — requirements by identity and digest, operations
+ * and messages by their join tokens and their `$ref`-closure digests,
+ * cross-service joins by tuple — with the authored consumers of every
+ * removal, deprecation and modification named (`core/consumers/consumers.ts`),
+ * and the cross-service joins that appeared or went away (`./joins.ts`).
+ *
+ * Two disciplines rule every branch here. Removal is graded against who still
+ * depends on it: a removal nobody names is a warning, a removal the fleet
+ * still joins to is an error and sets `breaking`. A MODIFICATION is never an
+ * error, whoever is joined to it: whether a changed schema breaks its readers
+ * is a field-level question loam hands to oasdiff on purpose, so the finding
+ * names the consumers and the tool, and stops there. And "nobody could look" is
+ * never "nothing changed": an unreadable artifact on EITHER side suspends
+ * that subject's axis — recorded in `unreadable[]`, counted in the summary,
+ * carried into the exit code by the command — instead of letting an
+ * unreadable base read as everything-added or an unreadable working file
+ * read as everything-removed. The one thing that is not a suspension is a
+ * contract the base held byte-for-byte: somebody COULD look, at the bytes,
+ * and they did not change (`comparable`, `UNTOUCHED_SKIPS`).
+ */
+import { requirementDigest } from "../document/spec.js";
+import { rawServiceId } from "../kernel/ids/service.js";
+import { consumerStance, scanDetails } from "../consumers/scan.js";
+import { consumerJoinChanges } from "./joins.js";
+/** Severity is a fact about the code, not a call-site choice — one table, no drift. */
+const DIFF_SEVERITY = {
+    "diff.service-added": "ok",
+    "diff.service-removed": "warn",
+    "diff.requirement-added": "ok",
+    "diff.requirement-removed": "warn",
+    "diff.requirement-modified": "ok",
+    "diff.op-added": "ok",
+    "diff.op-removed": "warn",
+    "diff.op-removed-consumed": "error",
+    "diff.op-deprecated": "warn",
+    "diff.op-modified": "warn",
+    "diff.message-added": "ok",
+    "diff.message-removed": "warn",
+    "diff.message-removed-consumed": "error",
+    "diff.message-modified": "warn",
+    "diff.consumer-added": "ok",
+    "diff.consumer-removed": "ok",
+};
+function found(code, message, details) {
+    const carry = details !== undefined && details.length > 0;
+    return { severity: DIFF_SEVERITY[code], code, message, ...(carry ? { details } : {}) };
+}
+/**
+ * A side the service does not exist on: absence everywhere, honestly. The id is
+ * a key of one of the two sides' maps, each keyed by a directory's leaf name.
+ */
+const ABSENT = { kind: "absent" };
+const emptyState = (id) => ({ id: rawServiceId(id), dir: "", spec: ABSENT, archSpec: ABSENT, openapi: ABSENT, asyncapi: ABSENT });
+/**
+ * The axes on which an unreadable document the branch left byte-identical is
+ * SKIPPED rather than suspended: the two contracts. Identical bytes are a
+ * proof, not a guess — the same parser over the same bytes cannot read
+ * differently on the two sides, so there is nothing of this document's own
+ * to diff, and suspending it anyway made every `loam diff` exit 1 over a
+ * fleet that holds one AsyncAPI 2.x file (unreadable by policy since
+ * core/asyncapi/read.ts refused pre-3.0), whatever the branch changed.
+ *
+ * Not the spec axes, and that is the victims scan's doing, not an oversight:
+ * an unreadable spec.md or arch.spec.md is also the document ANOTHER
+ * service's removal could not be checked against (`core/consumers/consumers.ts`'s
+ * `scanRequirements`), and its `unreadable[]` entry here is what carries that
+ * suspension to exit 1 (`opsDiff`'s removal branch says so). No scan reads a
+ * contract it could not parse as evidence of anything — `producers` takes
+ * positive evidence only — so skipping one hides no other answer.
+ */
+const UNTOUCHED_SKIPS = new Set(["openapi", "asyncapi"]);
+/**
+ * Guard one axis pair: record unreadable sides on the sink and say whether
+ * the axis may be compared at all. Reading one good side against a suspended
+ * one would grade absence it never proved. A contract unreadable on BOTH
+ * sides with one byte hash is the branch's untouched file: not compared and
+ * not recorded either (`UNTOUCHED_SKIPS`). A changed one, or one only one
+ * side cannot read, still suspends.
+ */
+function comparable(sink, axis, pair) {
+    const { base, current } = pair;
+    if (UNTOUCHED_SKIPS.has(axis) && base.kind === "unreadable" && current.kind === "unreadable" &&
+        base.bytes !== undefined && base.bytes === current.bytes)
+        return false;
+    for (const side of ["base", "current"]) {
+        const state = pair[side];
+        if (state.kind === "unreadable")
+            sink.unreadable.push({ side, axis, path: state.path, error: state.error });
+    }
+    return pair.base.kind !== "unreadable" && pair.current.kind !== "unreadable";
+}
+const valueOr = (axis) => (axis.kind === "read" ? axis.value : []);
+/** Identity: `Requirement-ID:` when authored, the heading otherwise — the same join `loam rebase` pins against. */
+const reqKey = (r) => (r.id !== undefined ? `id:${r.id}` : `name:${r.name}`);
+const reqLabel = (r) => (r.id !== undefined ? `${r.name} [${r.id}]` : r.name);
+/** First declaration wins a duplicated key — the same arbitrary-but-stated pick every join on these axes makes. */
+function firstWins(items, key) {
+    const map = new Map();
+    for (const item of items)
+        if (!map.has(key(item)))
+            map.set(key(item), item);
+    return map;
+}
+/** Entry comparator by map key — explicit, because the default sort stringifies whole entries. */
+const byKey = (a, b) => (a[0] < b[0] ? -1 : 1);
+function requirementsDiff(sink, pair) {
+    // v1 diffs spec.md's requirements only; arch.spec.md is read for the
+    // Consumes: join but its requirement inventory is deferred (the two axes
+    // are separate namespaces, and diffing both doubles the surface). Both
+    // pairs are guarded BEFORE the early return, so a service whose two spec
+    // files are both unreadable reports both suspensions, not just the first.
+    const specComparable = comparable(sink, "spec", { base: pair.base.spec, current: pair.current.spec });
+    comparable(sink, "archSpec", { base: pair.base.archSpec, current: pair.current.archSpec });
+    if (!specComparable)
+        return;
+    const base = firstWins(valueOr(pair.base.spec), reqKey);
+    const current = firstWins(valueOr(pair.current.spec), reqKey);
+    for (const [key, r] of [...current].sort(byKey)) {
+        const before = base.get(key);
+        if (before === undefined)
+            sink.findings.push(found("diff.requirement-added", `living requirement added since base: '${reqLabel(r)}'`));
+        else if (requirementDigest(before) !== requirementDigest(r)) {
+            sink.findings.push(found("diff.requirement-modified", `living requirement modified since base: '${reqLabel(r)}'`));
+        }
+    }
+    for (const [key, r] of [...base].sort(byKey)) {
+        if (!current.has(key))
+            sink.findings.push(found("diff.requirement-removed", `living requirement removed since base: '${reqLabel(r)}'`));
+    }
+}
+/**
+ * The second half of every modification message. loam joins consumers to the
+ * thing that moved; it does not read what a schema SAYS (core/brief/unchecked.ts
+ * lists that as unchecked), so a breaking rename and a new optional field are
+ * the same finding here — the specialist diff tells them apart.
+ */
+const notGraded = (tool) => `loam does not grade whether the change is breaking — run ${tool} on the two states of this contract`;
+async function opsDiff(sink, pair, victims) {
+    if (!comparable(sink, "openapi", { base: pair.base.openapi, current: pair.current.openapi }))
+        return;
+    const base = firstWins(valueOr(pair.base.openapi), (op) => op.id);
+    const current = firstWins(valueOr(pair.current.openapi), (op) => op.id);
+    for (const [id, op] of [...current].sort(byKey)) {
+        const before = base.get(id);
+        if (before === undefined) {
+            sink.findings.push(found("diff.op-added", `operation '${id}' added since base (${op.method.toUpperCase()} ${op.path})`));
+        }
+        else if (!before.deprecated && op.deprecated) {
+            const scan = await victims.opConsumers(sink.id, id);
+            sink.findings.push(found("diff.op-deprecated", `operation '${id}' is deprecated since base — ${consumerStance(scan)}`, scanDetails(scan)));
+        }
+        else if (before.closureDigest !== op.closureDigest || before.path !== op.path || before.method !== op.method) {
+            // `else`, because setting the flag moves the digest by itself (it is a
+            // key of the node): a deprecation already names the same consumers, and
+            // a second finding over them would say nothing new. The digest covers
+            // the `$ref` closure — a field renamed in a shared component is exactly
+            // the change this code exists for, and the operation's own bytes never
+            // move for it. A relocated slot is a change too, though the node is not.
+            const scan = await victims.opConsumers(sink.id, id);
+            sink.findings.push(found("diff.op-modified", `operation '${id}' (${op.method.toUpperCase()} ${op.path}) changed since base, in its own definition or a schema it references — ${consumerStance(scan)}; ${notGraded("`oasdiff breaking`")}`, scanDetails(scan)));
+        }
+    }
+    for (const [id] of [...base].sort(byKey)) {
+        if (current.has(id))
+            continue;
+        const scan = await victims.opConsumers(sink.id, id);
+        if (scan.victims.length > 0) {
+            sink.findings.push(found("diff.op-removed-consumed", `operation '${id}' was removed since base and the current fleet still names it — these joins break`, scanDetails(scan)));
+        }
+        else if (scan.suspended.length > 0) {
+            // "Nobody could be checked" is not "nobody names it", so this message
+            // must not assert a negative the scan never proved. An unreadable
+            // consumer document carries the run to exit 1 through its own
+            // unreadable[] entry; a caller drawn with no op does not — it stays this
+            // warning, so a seeded, op-less map does not fail every removal.
+            sink.findings.push(found("diff.op-removed", `operation '${id}' was removed since base; whether the current fleet still names it could NOT be fully answered — ${scan.suspended.length} possible consumer(s) could not be checked`, scanDetails(scan)));
+        }
+        else {
+            sink.findings.push(found("diff.op-removed", `operation '${id}' was removed since base; no current edge, requirement or use-case hop names it`));
+        }
+    }
+}
+async function messagesDiff(sink, pair, victims) {
+    if (!comparable(sink, "asyncapi", { base: pair.base.asyncapi, current: pair.current.asyncapi }))
+        return;
+    const base = firstWins(valueOr(pair.base.asyncapi), (m) => m.name);
+    const current = firstWins(valueOr(pair.current.asyncapi), (m) => m.name);
+    for (const [name, message] of [...current].sort(byKey)) {
+        const before = base.get(name);
+        if (before === undefined) {
+            sink.findings.push(found("diff.message-added", `message '${name}' added since base`));
+        }
+        else if (before.closureDigest !== message.closureDigest) {
+            const scan = await victims.messageConsumers(sink.id, name);
+            sink.findings.push(found("diff.message-modified", `message '${name}' changed since base, in its declaration or a schema its payload references — ${consumerStance(scan)}; ${notGraded("`asyncapi diff`")}`, scanDetails(scan)));
+        }
+    }
+    for (const [name] of [...base].sort(byKey)) {
+        if (current.has(name))
+            continue;
+        // Fleet-global join: a name another current service still SENDS is not
+        // orphaned (positive evidence only — an unreadable contract never vouches,
+        // and a service that only receives it is one of its consumers, never its
+        // producer: `producers` says why that distinction is the gate's too). Nor
+        // is one an #external element still publishes, by validate's own rule
+        // (`externalProducer` says why): counting the fleet's senders alone made
+        // this removal an error that the next `validate --all` called clean.
+        const elsewhere = (await victims.producers(name)).filter((d) => d !== sink.id);
+        const outside = await victims.externalProducer(name);
+        const senders = outside === null ? elsewhere : [...elsewhere, `${outside} (#external)`];
+        if (senders.length > 0) {
+            sink.findings.push(found("diff.message-removed", `message '${name}' was removed since base; still sent by ${senders.join(", ")}`));
+            continue;
+        }
+        const scan = await victims.messageConsumers(sink.id, name);
+        if (scan.victims.length > 0) {
+            sink.findings.push(found("diff.message-removed-consumed", `message '${name}' was removed since base and the current fleet still consumes it — these joins break`, scanDetails(scan)));
+        }
+        else if (scan.suspended.length > 0) {
+            sink.findings.push(found("diff.message-removed", `message '${name}' was removed since base; whether anything still consumes it could NOT be fully answered — ${scan.suspended.length} consumer document(s) were not scannable`, scanDetails(scan)));
+        }
+        else {
+            sink.findings.push(found("diff.message-removed", `message '${name}' was removed since base; nothing currently consumes it`));
+        }
+    }
+}
+/** The graded join changes (`./joins.ts`) as findings on each PROVIDER — the service whose surface the join lands on. */
+function consumerFindings(input) {
+    const changes = consumerJoinChanges({
+        base: input.base.services,
+        baseAmbiguous: new Set(input.base.ambiguous.keys()),
+        current: input.current.services,
+        currentAmbiguous: new Set(input.current.ambiguous.keys()),
+    });
+    const byProvider = new Map();
+    for (const { t, change } of changes) {
+        const what = t.kind === "op" ? `operation '${t.token}'` : `message '${t.token}'`;
+        const message = change === "added"
+            ? `${t.consumer}'s living requirements now name this service's ${what} — a cross-service join appeared since base`
+            : `${t.consumer}'s living requirements no longer name this service's ${what} — a cross-service join went away`;
+        // The call sits directly in the push — assigned to a `const x = found(…)`
+        // it reads as an arrow-function DECLARATION to the stable-code collector,
+        // and both consumer codes silently leave the guarded set.
+        byProvider.set(t.provider, [
+            ...(byProvider.get(t.provider) ?? []),
+            found(change === "added" ? "diff.consumer-added" : "diff.consumer-removed", message),
+        ]);
+    }
+    return byProvider;
+}
+async function diffService(unit) {
+    const sink = { id: unit.id, change: "unchanged", findings: [], unreadable: [] };
+    if (unit.base === undefined)
+        sink.findings.push(found("diff.service-added", `service '${unit.id}' added since base`));
+    if (unit.current === undefined && unit.base !== undefined) {
+        sink.findings.push(found("diff.service-removed", `service '${unit.id}' (${unit.base.dir}) is gone from the working tree`));
+    }
+    const pair = { base: unit.base ?? emptyState(unit.id), current: unit.current ?? emptyState(unit.id) };
+    requirementsDiff(sink, pair);
+    await opsDiff(sink, pair, unit.victims);
+    await messagesDiff(sink, pair, unit.victims);
+    return sink;
+}
+export async function computeDiff(input) {
+    const sides = [input.base.services, input.base.ambiguous, input.current.services, input.current.ambiguous];
+    const ids = [...new Set(sides.flatMap((side) => [...side.keys()]))].sort();
+    const joins = consumerFindings({ base: input.base, current: input.current });
+    const services = [];
+    // Sequential on purpose: the report's order IS the contract (identical
+    // states must emit identical bytes), the work per service is in-memory
+    // joins, and the one expensive read — the victim index's landscape — is
+    // memoised behind its first ask, so a fan-out would buy nothing.
+    for (const id of ids) {
+        const claimants = [...(input.base.ambiguous.get(id) ?? []), ...(input.current.ambiguous.get(id) ?? [])];
+        if (claimants.length > 0) {
+            // An id two directories claim — either side — has no single state to
+            // diff; the whole subject suspends (containment), and the live walk's
+            // `subsystem.name-collision` names the same defect for validate.
+            services.push({ id, change: "changed", findings: [], unreadable: [], ambiguous: claimants });
+            continue;
+        }
+        const sink = await diffService({ id, base: input.base.services.get(id), current: input.current.services.get(id), victims: input.victims });
+        sink.findings.push(...(joins.get(id) ?? []));
+        if (input.base.services.has(id) && !input.current.services.has(id))
+            sink.change = "removed";
+        else if (!input.base.services.has(id))
+            sink.change = "added";
+        else
+            sink.change = sink.findings.length > 0 || sink.unreadable.length > 0 ? "changed" : "unchanged";
+        services.push(sink);
+    }
+    const all = services.flatMap((s) => s.findings);
+    const count = (codes) => all.filter(codes).length;
+    return {
+        services,
+        breaking: all.some((f) => f.severity === "error"),
+        summary: {
+            added: count((f) => f.code.endsWith("-added")),
+            removed: count((f) => f.code.endsWith("-removed") || f.code.endsWith("-removed-consumed")),
+            // Requirements, operations and messages alike: a reader scanning the one
+            // summary line must not see "0 modified" over a PR that renamed a field.
+            modified: count((f) => f.code.endsWith("-modified")),
+            deprecated: count((f) => f.code === "diff.op-deprecated"),
+            unreadable: services.reduce((n, s) => n + s.unreadable.length, 0) +
+                services.filter((s) => s.ambiguous !== undefined).length,
+        },
+    };
+}
+//# sourceMappingURL=semantic.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../../../src/core/diff/semantic.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The diff computation: join the base fleet (`./base-state.ts`) against the\n * working tree (`core/consumers/current.ts`) and say, per service, what changed in\n * FLEET-MEANINGFUL terms — requirements by identity and digest, operations\n * and messages by their join tokens and their `$ref`-closure digests,\n * cross-service joins by tuple — with the authored consumers of every\n * removal, deprecation and modification named (`core/consumers/consumers.ts`),\n * and the cross-service joins that appeared or went away (`./joins.ts`).\n *\n * Two disciplines rule every branch here. Removal is graded against who still\n * depends on it: a removal nobody names is a warning, a removal the fleet\n * still joins to is an error and sets `breaking`. A MODIFICATION is never an\n * error, whoever is joined to it: whether a changed schema breaks its readers\n * is a field-level question loam hands to oasdiff on purpose, so the finding\n * names the consumers and the tool, and stops there. And \"nobody could look\" is\n * never \"nothing changed\": an unreadable artifact on EITHER side suspends\n * that subject's axis — recorded in `unreadable[]`, counted in the summary,\n * carried into the exit code by the command — instead of letting an\n * unreadable base read as everything-added or an unreadable working file\n * read as everything-removed. The one thing that is not a suspension is a\n * contract the base held byte-for-byte: somebody COULD look, at the bytes,\n * and they did not change (`comparable`, `UNTOUCHED_SKIPS`).\n */\nimport { requirementDigest, type Requirement } from \"../document/spec.js\";\nimport type { Severity, Finding } from \"../vocabulary/report.js\";\nimport type { BaseFleet } from \"./base-state.js\";\nimport { rawServiceId } from \"../kernel/ids/service.js\";\nimport type { AxisState, ServiceState } from \"../consumers/state.js\";\nimport type { CurrentFleet } from \"../consumers/current.js\";\nimport { consumerStance, scanDetails } from \"../consumers/scan.js\";\nimport type { ConsumerIndex } from \"../consumers/consumers.js\";\nimport { consumerJoinChanges } from \"./joins.js\";\n\n/**\n * The stable finding codes `loam diff` emits. Codes are the machine contract;\n * prose may be reworded, these may not. Documented (backticked) in the\n * generated AGENTS.md's diff section — codes-drift enforces that.\n */\nexport type DiffCode =\n  /** A `services/<id>/` directory exists now that did not at the base ref. */\n  | \"diff.service-added\"\n  /** A service present at the base ref is gone from the working tree. */\n  | \"diff.service-removed\"\n  /** A living requirement (by `Requirement-ID:`, else heading) not present at base. */\n  | \"diff.requirement-added\"\n  /** A base requirement no longer in the living spec. */\n  | \"diff.requirement-removed\"\n  /** Same requirement identity on both sides, `requirementDigest` moved — rebase pins never move it. */\n  | \"diff.requirement-modified\"\n  /** An operationId in the living contract absent at base. */\n  | \"diff.op-added\"\n  /** A base operationId gone from the living contract, and no current consumer names it. */\n  | \"diff.op-removed\"\n  /** Removed since base AND the current fleet still names it — landscape edge or foreign living requirement; details list the victims. Sets `breaking`. */\n  | \"diff.op-removed-consumed\"\n  /** `deprecated: true` introduced since base; details name the current consumers. */\n  | \"diff.op-deprecated\"\n  /** Same operationId on both sides, and its node or anything its internal `$ref`s reach moved; details name the authored consumers. Whether it BREAKS them is oasdiff's question, not loam's. */\n  | \"diff.op-modified\"\n  /** An AsyncAPI message name absent at base. */\n  | \"diff.message-added\"\n  /** A base message gone, nothing currently consumes it (or another service still sends it — the message says). */\n  | \"diff.message-removed\"\n  /** Removed since base AND still consumed — a `Consumes:` line or a consumes-edge; details list the victims. Sets `breaking`. */\n  | \"diff.message-removed-consumed\"\n  /** Same message name on both sides, and its declaration or anything its internal `$ref`s reach moved; details name the authored consumers. Whether it BREAKS them is not graded. */\n  | \"diff.message-modified\"\n  /** A cross-service join appeared since base: another service's living requirement now names this service's operation or message. */\n  | \"diff.consumer-added\"\n  /** A cross-service join present at base is gone. */\n  | \"diff.consumer-removed\";\n\n/** Severity is a fact about the code, not a call-site choice — one table, no drift. */\nconst DIFF_SEVERITY: Record<DiffCode, Severity> = {\n  \"diff.service-added\": \"ok\",\n  \"diff.service-removed\": \"warn\",\n  \"diff.requirement-added\": \"ok\",\n  \"diff.requirement-removed\": \"warn\",\n  \"diff.requirement-modified\": \"ok\",\n  \"diff.op-added\": \"ok\",\n  \"diff.op-removed\": \"warn\",\n  \"diff.op-removed-consumed\": \"error\",\n  \"diff.op-deprecated\": \"warn\",\n  \"diff.op-modified\": \"warn\",\n  \"diff.message-added\": \"ok\",\n  \"diff.message-removed\": \"warn\",\n  \"diff.message-removed-consumed\": \"error\",\n  \"diff.message-modified\": \"warn\",\n  \"diff.consumer-added\": \"ok\",\n  \"diff.consumer-removed\": \"ok\",\n};\n\nfunction found(code: DiffCode, message: string, details?: string[]): Finding {\n  const carry = details !== undefined && details.length > 0;\n  return { severity: DIFF_SEVERITY[code], code, message, ...(carry ? { details } : {}) };\n}\n\n/** One suspended axis: which side could not be read, and why. */\nexport interface UnreadableEntry {\n  side: \"base\" | \"current\";\n  axis: \"spec\" | \"archSpec\" | \"openapi\" | \"asyncapi\";\n  path: string;\n  error: string;\n}\n\nexport interface ServiceDiff {\n  id: string;\n  change: \"added\" | \"removed\" | \"changed\" | \"unchanged\";\n  findings: Finding[];\n  unreadable: UnreadableEntry[];\n  /** Directories claiming this id when more than one does, on either side — every finding suspended. */\n  ambiguous?: string[];\n}\n\nexport interface FleetDiff {\n  services: ServiceDiff[];\n  /** True iff any error-severity finding — a removal the fleet still consumes. */\n  breaking: boolean;\n  /** `unreadable` counts suspended axes plus ambiguous base identities: places nobody could look. */\n  summary: { added: number; removed: number; modified: number; deprecated: number; unreadable: number };\n}\n\n/**\n * A side the service does not exist on: absence everywhere, honestly. The id is\n * a key of one of the two sides' maps, each keyed by a directory's leaf name.\n */\nconst ABSENT = { kind: \"absent\" } as const;\nconst emptyState = (id: string): ServiceState => ({ id: rawServiceId(id), dir: \"\", spec: ABSENT, archSpec: ABSENT, openapi: ABSENT, asyncapi: ABSENT });\n\n/**\n * The axes on which an unreadable document the branch left byte-identical is\n * SKIPPED rather than suspended: the two contracts. Identical bytes are a\n * proof, not a guess — the same parser over the same bytes cannot read\n * differently on the two sides, so there is nothing of this document's own\n * to diff, and suspending it anyway made every `loam diff` exit 1 over a\n * fleet that holds one AsyncAPI 2.x file (unreadable by policy since\n * core/asyncapi/read.ts refused pre-3.0), whatever the branch changed.\n *\n * Not the spec axes, and that is the victims scan's doing, not an oversight:\n * an unreadable spec.md or arch.spec.md is also the document ANOTHER\n * service's removal could not be checked against (`core/consumers/consumers.ts`'s\n * `scanRequirements`), and its `unreadable[]` entry here is what carries that\n * suspension to exit 1 (`opsDiff`'s removal branch says so). No scan reads a\n * contract it could not parse as evidence of anything — `producers` takes\n * positive evidence only — so skipping one hides no other answer.\n */\nconst UNTOUCHED_SKIPS: ReadonlySet<UnreadableEntry[\"axis\"]> = new Set([\"openapi\", \"asyncapi\"]);\n\n/**\n * Guard one axis pair: record unreadable sides on the sink and say whether\n * the axis may be compared at all. Reading one good side against a suspended\n * one would grade absence it never proved. A contract unreadable on BOTH\n * sides with one byte hash is the branch's untouched file: not compared and\n * not recorded either (`UNTOUCHED_SKIPS`). A changed one, or one only one\n * side cannot read, still suspends.\n */\nfunction comparable(sink: ServiceDiff, axis: UnreadableEntry[\"axis\"], pair: { base: AxisState<unknown>; current: AxisState<unknown> }): boolean {\n  const { base, current } = pair;\n  if (UNTOUCHED_SKIPS.has(axis) && base.kind === \"unreadable\" && current.kind === \"unreadable\" &&\n    base.bytes !== undefined && base.bytes === current.bytes) return false;\n  for (const side of [\"base\", \"current\"] as const) {\n    const state = pair[side];\n    if (state.kind === \"unreadable\") sink.unreadable.push({ side, axis, path: state.path, error: state.error });\n  }\n  return pair.base.kind !== \"unreadable\" && pair.current.kind !== \"unreadable\";\n}\n\nconst valueOr = <T>(axis: AxisState<T[]>): T[] => (axis.kind === \"read\" ? axis.value : []);\n\n/** Identity: `Requirement-ID:` when authored, the heading otherwise — the same join `loam rebase` pins against. */\nconst reqKey = (r: Requirement): string => (r.id !== undefined ? `id:${r.id}` : `name:${r.name}`);\nconst reqLabel = (r: Requirement): string => (r.id !== undefined ? `${r.name} [${r.id}]` : r.name);\n\n/** First declaration wins a duplicated key — the same arbitrary-but-stated pick every join on these axes makes. */\nfunction firstWins<T>(items: T[], key: (item: T) => string): Map<string, T> {\n  const map = new Map<string, T>();\n  for (const item of items) if (!map.has(key(item))) map.set(key(item), item);\n  return map;\n}\n\n/** Entry comparator by map key — explicit, because the default sort stringifies whole entries. */\nconst byKey = <T>(a: [string, T], b: [string, T]): number => (a[0] < b[0] ? -1 : 1);\n\nfunction requirementsDiff(sink: ServiceDiff, pair: { base: ServiceState; current: ServiceState }): void {\n  // v1 diffs spec.md's requirements only; arch.spec.md is read for the\n  // Consumes: join but its requirement inventory is deferred (the two axes\n  // are separate namespaces, and diffing both doubles the surface). Both\n  // pairs are guarded BEFORE the early return, so a service whose two spec\n  // files are both unreadable reports both suspensions, not just the first.\n  const specComparable = comparable(sink, \"spec\", { base: pair.base.spec, current: pair.current.spec });\n  comparable(sink, \"archSpec\", { base: pair.base.archSpec, current: pair.current.archSpec });\n  if (!specComparable) return;\n  const base = firstWins(valueOr(pair.base.spec), reqKey);\n  const current = firstWins(valueOr(pair.current.spec), reqKey);\n  for (const [key, r] of [...current].sort(byKey)) {\n    const before = base.get(key);\n    if (before === undefined) sink.findings.push(found(\"diff.requirement-added\", `living requirement added since base: '${reqLabel(r)}'`));\n    else if (requirementDigest(before) !== requirementDigest(r)) {\n      sink.findings.push(found(\"diff.requirement-modified\", `living requirement modified since base: '${reqLabel(r)}'`));\n    }\n  }\n  for (const [key, r] of [...base].sort(byKey)) {\n    if (!current.has(key)) sink.findings.push(found(\"diff.requirement-removed\", `living requirement removed since base: '${reqLabel(r)}'`));\n  }\n}\n\n/**\n * The second half of every modification message. loam joins consumers to the\n * thing that moved; it does not read what a schema SAYS (core/brief/unchecked.ts\n * lists that as unchecked), so a breaking rename and a new optional field are\n * the same finding here — the specialist diff tells them apart.\n */\nconst notGraded = (tool: string): string =>\n  `loam does not grade whether the change is breaking — run ${tool} on the two states of this contract`;\n\nasync function opsDiff(sink: ServiceDiff, pair: { base: ServiceState; current: ServiceState }, victims: ConsumerIndex): Promise<void> {\n  if (!comparable(sink, \"openapi\", { base: pair.base.openapi, current: pair.current.openapi })) return;\n  const base = firstWins(valueOr(pair.base.openapi), (op) => op.id);\n  const current = firstWins(valueOr(pair.current.openapi), (op) => op.id);\n  for (const [id, op] of [...current].sort(byKey)) {\n    const before = base.get(id);\n    if (before === undefined) {\n      sink.findings.push(found(\"diff.op-added\", `operation '${id}' added since base (${op.method.toUpperCase()} ${op.path})`));\n    } else if (!before.deprecated && op.deprecated) {\n      const scan = await victims.opConsumers(sink.id, id);\n      sink.findings.push(found(\"diff.op-deprecated\", `operation '${id}' is deprecated since base — ${consumerStance(scan)}`, scanDetails(scan)));\n    } else if (before.closureDigest !== op.closureDigest || before.path !== op.path || before.method !== op.method) {\n      // `else`, because setting the flag moves the digest by itself (it is a\n      // key of the node): a deprecation already names the same consumers, and\n      // a second finding over them would say nothing new. The digest covers\n      // the `$ref` closure — a field renamed in a shared component is exactly\n      // the change this code exists for, and the operation's own bytes never\n      // move for it. A relocated slot is a change too, though the node is not.\n      const scan = await victims.opConsumers(sink.id, id);\n      sink.findings.push(found(\n        \"diff.op-modified\",\n        `operation '${id}' (${op.method.toUpperCase()} ${op.path}) changed since base, in its own definition or a schema it references — ${consumerStance(scan)}; ${notGraded(\"`oasdiff breaking`\")}`,\n        scanDetails(scan),\n      ));\n    }\n  }\n  for (const [id] of [...base].sort(byKey)) {\n    if (current.has(id)) continue;\n    const scan = await victims.opConsumers(sink.id, id);\n    if (scan.victims.length > 0) {\n      sink.findings.push(found(\"diff.op-removed-consumed\", `operation '${id}' was removed since base and the current fleet still names it — these joins break`, scanDetails(scan)));\n    } else if (scan.suspended.length > 0) {\n      // \"Nobody could be checked\" is not \"nobody names it\", so this message\n      // must not assert a negative the scan never proved. An unreadable\n      // consumer document carries the run to exit 1 through its own\n      // unreadable[] entry; a caller drawn with no op does not — it stays this\n      // warning, so a seeded, op-less map does not fail every removal.\n      sink.findings.push(found(\"diff.op-removed\", `operation '${id}' was removed since base; whether the current fleet still names it could NOT be fully answered — ${scan.suspended.length} possible consumer(s) could not be checked`, scanDetails(scan)));\n    } else {\n      sink.findings.push(found(\"diff.op-removed\", `operation '${id}' was removed since base; no current edge, requirement or use-case hop names it`));\n    }\n  }\n}\n\nasync function messagesDiff(sink: ServiceDiff, pair: { base: ServiceState; current: ServiceState }, victims: ConsumerIndex): Promise<void> {\n  if (!comparable(sink, \"asyncapi\", { base: pair.base.asyncapi, current: pair.current.asyncapi })) return;\n  const base = firstWins(valueOr(pair.base.asyncapi), (m) => m.name);\n  const current = firstWins(valueOr(pair.current.asyncapi), (m) => m.name);\n  for (const [name, message] of [...current].sort(byKey)) {\n    const before = base.get(name);\n    if (before === undefined) {\n      sink.findings.push(found(\"diff.message-added\", `message '${name}' added since base`));\n    } else if (before.closureDigest !== message.closureDigest) {\n      const scan = await victims.messageConsumers(sink.id, name);\n      sink.findings.push(found(\n        \"diff.message-modified\",\n        `message '${name}' changed since base, in its declaration or a schema its payload references — ${consumerStance(scan)}; ${notGraded(\"`asyncapi diff`\")}`,\n        scanDetails(scan),\n      ));\n    }\n  }\n  for (const [name] of [...base].sort(byKey)) {\n    if (current.has(name)) continue;\n    // Fleet-global join: a name another current service still SENDS is not\n    // orphaned (positive evidence only — an unreadable contract never vouches,\n    // and a service that only receives it is one of its consumers, never its\n    // producer: `producers` says why that distinction is the gate's too). Nor\n    // is one an #external element still publishes, by validate's own rule\n    // (`externalProducer` says why): counting the fleet's senders alone made\n    // this removal an error that the next `validate --all` called clean.\n    const elsewhere = (await victims.producers(name)).filter((d) => d !== sink.id);\n    const outside = await victims.externalProducer(name);\n    const senders = outside === null ? elsewhere : [...elsewhere, `${outside} (#external)`];\n    if (senders.length > 0) {\n      sink.findings.push(found(\"diff.message-removed\", `message '${name}' was removed since base; still sent by ${senders.join(\", \")}`));\n      continue;\n    }\n    const scan = await victims.messageConsumers(sink.id, name);\n    if (scan.victims.length > 0) {\n      sink.findings.push(found(\"diff.message-removed-consumed\", `message '${name}' was removed since base and the current fleet still consumes it — these joins break`, scanDetails(scan)));\n    } else if (scan.suspended.length > 0) {\n      sink.findings.push(found(\"diff.message-removed\", `message '${name}' was removed since base; whether anything still consumes it could NOT be fully answered — ${scan.suspended.length} consumer document(s) were not scannable`, scanDetails(scan)));\n    } else {\n      sink.findings.push(found(\"diff.message-removed\", `message '${name}' was removed since base; nothing currently consumes it`));\n    }\n  }\n}\n\n/** The graded join changes (`./joins.ts`) as findings on each PROVIDER — the service whose surface the join lands on. */\nfunction consumerFindings(input: { base: BaseFleet; current: CurrentFleet }): Map<string, Finding[]> {\n  const changes = consumerJoinChanges({\n    base: input.base.services,\n    baseAmbiguous: new Set(input.base.ambiguous.keys()),\n    current: input.current.services,\n    currentAmbiguous: new Set(input.current.ambiguous.keys()),\n  });\n  const byProvider = new Map<string, Finding[]>();\n  for (const { t, change } of changes) {\n    const what = t.kind === \"op\" ? `operation '${t.token}'` : `message '${t.token}'`;\n    const message = change === \"added\"\n      ? `${t.consumer}'s living requirements now name this service's ${what} — a cross-service join appeared since base`\n      : `${t.consumer}'s living requirements no longer name this service's ${what} — a cross-service join went away`;\n    // The call sits directly in the push — assigned to a `const x = found(…)`\n    // it reads as an arrow-function DECLARATION to the stable-code collector,\n    // and both consumer codes silently leave the guarded set.\n    byProvider.set(t.provider, [\n      ...(byProvider.get(t.provider) ?? []),\n      found(change === \"added\" ? \"diff.consumer-added\" : \"diff.consumer-removed\", message),\n    ]);\n  }\n  return byProvider;\n}\n\nasync function diffService(unit: { id: string; base?: ServiceState; current?: ServiceState; victims: ConsumerIndex }): Promise<ServiceDiff> {\n  const sink: ServiceDiff = { id: unit.id, change: \"unchanged\", findings: [], unreadable: [] };\n  if (unit.base === undefined) sink.findings.push(found(\"diff.service-added\", `service '${unit.id}' added since base`));\n  if (unit.current === undefined && unit.base !== undefined) {\n    sink.findings.push(found(\"diff.service-removed\", `service '${unit.id}' (${unit.base.dir}) is gone from the working tree`));\n  }\n  const pair = { base: unit.base ?? emptyState(unit.id), current: unit.current ?? emptyState(unit.id) };\n  requirementsDiff(sink, pair);\n  await opsDiff(sink, pair, unit.victims);\n  await messagesDiff(sink, pair, unit.victims);\n  return sink;\n}\n\nexport async function computeDiff(input: { base: BaseFleet; current: CurrentFleet; victims: ConsumerIndex }): Promise<FleetDiff> {\n  const sides = [input.base.services, input.base.ambiguous, input.current.services, input.current.ambiguous];\n  const ids = [...new Set(sides.flatMap((side) => [...side.keys()]))].sort();\n  const joins = consumerFindings({ base: input.base, current: input.current });\n  const services: ServiceDiff[] = [];\n  // Sequential on purpose: the report's order IS the contract (identical\n  // states must emit identical bytes), the work per service is in-memory\n  // joins, and the one expensive read — the victim index's landscape — is\n  // memoised behind its first ask, so a fan-out would buy nothing.\n  for (const id of ids) {\n    const claimants = [...(input.base.ambiguous.get(id) ?? []), ...(input.current.ambiguous.get(id) ?? [])];\n    if (claimants.length > 0) {\n      // An id two directories claim — either side — has no single state to\n      // diff; the whole subject suspends (containment), and the live walk's\n      // `subsystem.name-collision` names the same defect for validate.\n      services.push({ id, change: \"changed\", findings: [], unreadable: [], ambiguous: claimants });\n      continue;\n    }\n    const sink = await diffService({ id, base: input.base.services.get(id), current: input.current.services.get(id), victims: input.victims });\n    sink.findings.push(...(joins.get(id) ?? []));\n    if (input.base.services.has(id) && !input.current.services.has(id)) sink.change = \"removed\";\n    else if (!input.base.services.has(id)) sink.change = \"added\";\n    else sink.change = sink.findings.length > 0 || sink.unreadable.length > 0 ? \"changed\" : \"unchanged\";\n    services.push(sink);\n  }\n  const all = services.flatMap((s) => s.findings);\n  const count = (codes: (f: Finding) => boolean): number => all.filter(codes).length;\n  return {\n    services,\n    breaking: all.some((f) => f.severity === \"error\"),\n    summary: {\n      added: count((f) => f.code.endsWith(\"-added\")),\n      removed: count((f) => f.code.endsWith(\"-removed\") || f.code.endsWith(\"-removed-consumed\")),\n      // Requirements, operations and messages alike: a reader scanning the one\n      // summary line must not see \"0 modified\" over a PR that renamed a field.\n      modified: count((f) => f.code.endsWith(\"-modified\")),\n      deprecated: count((f) => f.code === \"diff.op-deprecated\"),\n      unreadable:\n        services.reduce((n, s) => n + s.unreadable.length, 0) +\n        services.filter((s) => s.ambiguous !== undefined).length,\n    },\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, LIKEC4_PROJECT_FILENAME, LIKEC4_ROOT_PROJECT } 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,100 +32,47 @@ 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.
  *
  * LikeC4's workspace loader merges EVERY `.likec4` file under a directory tree
- * into one model. loam's layout is the opposite by design: the landscape,
- * each `services/<id>/model.likec4` and each `features/<FEAT>/delta.likec4` is
- * parsed in isolation (`loadSource`, one file, one throwaway workspace), so
- * every one of them legitimately declares its own `specification { … }` block
- * and re-declares the elements it needs to talk about. Point the real renderer
- * at the repository root and those declarations collide: on loam's own
- * `examples/docs` — four files — `npx likec4 start` reported 16 errors, sixteen
- * duplicate kinds and names, while `loam validate --all` reported none. Both
- * were right; only one of them was reading the tree as a workspace.
+ * into one model, and whether that is what loam wants depends on the document.
+ * A feature's `features/<FEAT>/delta.likec4` is parsed in isolation and declares
+ * its own `specification { … }` block, so merging it into the root would report
+ * every declaration as a duplicate — measured on loam's own `examples/docs`:
+ * `npx likec4 start` reported 16 errors, sixteen duplicate kinds and names,
+ * while `loam validate --all` reported none. Both were right; only one of them
+ * was reading the tree as a workspace. That directory is therefore excluded
+ * here, permanently.
  *
- * So the root is declared as one LikeC4 project holding the landscape, and the
- * two directories whose files are meant to be read alone are excluded from it.
- * That makes `npx likec4 start` in the docs repo — the command loam's own docs
- * have always recommended — render the fleet map instead of failing. A service
- * model or a feature delta is still rendered by pointing the renderer at its own
- * directory, which is what parsing them in isolation meant all along.
+ * `services/**` is NOT, and that is this file's one substantive change since the
+ * axis that let a model EXTEND the fleet map. A model written that way declares
+ * no kinds of its own and says what is inside an element the map already draws,
+ * so the root project is the only place it parses — and excluding it renders the
+ * service as a box with nothing inside. A model that STANDS ALONE still has to
+ * be excluded, and `loam subsystem sync` is what adds `services/<tree>/**` for
+ * each one and removes the entry again when a model migrates. A fresh repo's
+ * models are extending, so the scaffold starts with no `services/` entry at all.
  *
  * `**\/node_modules/**` is repeated because naming `exclude` replaces LikeC4's
- * default rather than adding to it. loam reads none of this file: it is written
- * once, never re-read, and a team that wants a different project layout owns it
- * like every other scaffolded file.
+ * default rather than adding to it.
+ *
+ * OWNERSHIP, corrected. This file is still the team's — written once by
+ * `loam init --create`, never regenerated, and a team that wants a different
+ * project layout keeps it. But loam is no longer blind to it: it reads ONE
+ * literal fact out of it (`core/c4/root-project/exclude.ts`, `readRootExclude`
+ * — the `exclude` list and nothing else), because that list decides whether an
+ * extending model is renderable at all, and it MAINTAINS the `services/` entries
+ * in it through `loam subsystem sync`. Every other key, and every entry that is
+ * not about `services/`, is left exactly as written. The filename and the root
+ * project's name are spelled in `repo/paths.ts`, beside every other file loam
+ * writes.
  */
-export const LIKEC4_PROJECT_FILENAME = "likec4.config.json";
 export const LIKEC4_PROJECT_CONFIG = `${JSON.stringify({
-    name: "fleet",
+    name: LIKEC4_ROOT_PROJECT,
     title: "Fleet landscape",
-    exclude: ["**/node_modules/**", "services/**", "features/**"],
+    exclude: ["**/node_modules/**", "features/**"],
 }, null, 2)}\n`;
 /**
  * The placeholder that makes an empty scaffolded directory survive a clone.
@@ -183,6 +132,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":"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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.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":"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,sBAAsB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEhG;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,IAAI,CAAC,SAAS,CACpD;IACE,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,iBAAiB;IACxB,OAAO,EAAE,CAAC,oBAAoB,EAAE,aAAa,CAAC;CAC/C,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,0EAA0E;QAC1E,oEAAoE;QACpE,CAAC,eAAe,EAAE,SAAS,CAAC;QAC5B,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/agents-md.js\";\nimport { LANDSCAPE_STUB } from \"./scaffold/landscape.js\";\nimport { README_FILENAME, README_MD } from \"./scaffold/readme.js\";\nimport { AGENTS_FILENAME, LIKEC4_PROJECT_FILENAME, LIKEC4_ROOT_PROJECT } 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, and whether that is what loam wants depends on the document.\n * A feature's `features/<FEAT>/delta.likec4` is parsed in isolation and declares\n * its own `specification { … }` block, so merging it into the root would report\n * every declaration as a duplicate — measured on loam's own `examples/docs`:\n * `npx likec4 start` reported 16 errors, sixteen duplicate kinds and names,\n * while `loam validate --all` reported none. Both were right; only one of them\n * was reading the tree as a workspace. That directory is therefore excluded\n * here, permanently.\n *\n * `services/**` is NOT, and that is this file's one substantive change since the\n * axis that let a model EXTEND the fleet map. A model written that way declares\n * no kinds of its own and says what is inside an element the map already draws,\n * so the root project is the only place it parses — and excluding it renders the\n * service as a box with nothing inside. A model that STANDS ALONE still has to\n * be excluded, and `loam subsystem sync` is what adds `services/<tree>/**` for\n * each one and removes the entry again when a model migrates. A fresh repo's\n * models are extending, so the scaffold starts with no `services/` entry at all.\n *\n * `**\\/node_modules/**` is repeated because naming `exclude` replaces LikeC4's\n * default rather than adding to it.\n *\n * OWNERSHIP, corrected. This file is still the team's — written once by\n * `loam init --create`, never regenerated, and a team that wants a different\n * project layout keeps it. But loam is no longer blind to it: it reads ONE\n * literal fact out of it (`core/c4/root-project/exclude.ts`, `readRootExclude`\n * — the `exclude` list and nothing else), because that list decides whether an\n * extending model is renderable at all, and it MAINTAINS the `services/` entries\n * in it through `loam subsystem sync`. Every other key, and every entry that is\n * not about `services/`, is left exactly as written. The filename and the root\n * project's name are spelled in `repo/paths.ts`, beside every other file loam\n * writes.\n */\nexport const LIKEC4_PROJECT_CONFIG = `${JSON.stringify(\n  {\n    name: LIKEC4_ROOT_PROJECT,\n    title: \"Fleet landscape\",\n    exclude: [\"**/node_modules/**\", \"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"]}