@ybotok/loam 0.0.0 → 0.1.0-beta.2

package/dist/core/dependencies.js

@@ -0,0 +1,356 @@
+/**
+ * A read-only dependency/conflict index for active features.
+ *
+ * This is deliberately derived from parsed artifacts rather than validation
+ * messages: issue prose is for people and is not an API.  The graph answers a
+ * narrower question — which in-flight change must land before another because
+ * it introduces an identity or operation the latter already refers to.
+ */
+import { existsSync } from "node:fs";
+import { inOrder } from "./concurrency.js";
+import { FleetContext } from "./fleet-context.js";
+import { serviceResolver } from "./likec4.js";
+import { operations } from "./openapi.js";
+import { SPEC_AXES, compareIds, featurePaths, featureSpecPaths, listFeatures, servicePaths, } from "./repo.js";
+function reqKeys(requirement) {
+    return [
+        ...(requirement.id === undefined ? [] : [`id:${requirement.id}`]),
+        `name:${requirement.name}`,
+    ];
+}
+function reqIndexKey(at) {
+    return `${at.service}\0${at.axis}\0${at.identity}`;
+}
+function opIndexKey(at) {
+    return `${at.service}\0${at.operationId}`;
+}
+function addOwner(index, key, at, feature) {
+    const owners = index.get(key) ?? { at, features: new Set() };
+    owners.features.add(feature);
+    index.set(key, owners);
+}
+async function readFacts(docsDir, feature, context) {
+    const addedRequirements = [];
+    const changedRequirements = [];
+    const introducedOperations = [];
+    const requiredOperations = [];
+    /**
+     * The operationIds a service ALREADY has, per service.
+     *
+     * This is the whole difference between a dependency graph and a rumour mill.
+     * A feature's `openapi.yaml` is a COMPLETE document, not a patch — authors
+     * restate the living API around the slot they are changing — so every feature
+     * that so much as mentions `authorizePayment` used to be recorded as
+     * INTRODUCING it, and every other feature governing it as REQUIRING it. Two
+     * features quoting the same living operation therefore depended on each other
+     * in both directions: an invented cycle, an invented conflict, and an ordering
+     * for work that had none. `loam validate`'s coherence pass already subtracts
+     * the living contract this way (core/coherence.ts); this is the same
+     * subtraction, so the two cannot disagree about what "new" means.
+     *
+     * Cached per service inside the call and, through the FleetContext, across
+     * features: a fleet-wide graph asks about the same ten services N times.
+     */
+    const livingByService = new Map();
+    const living = async (service) => {
+        let ids = livingByService.get(service);
+        if (ids === undefined) {
+            ids = new Set((await operations(servicePaths(docsDir, service).openapi, context))
+                .filter((op) => !op.remove)
+                .map((op) => op.id));
+            livingByService.set(service, ids);
+        }
+        return ids;
+    };
+    for (const service of feature.services) {
+        const paths = featureSpecPaths(feature.dir, service);
+        const livingIds = await living(service);
+        for (const axis of SPEC_AXES) {
+            const path = paths[axis.key];
+            if (!existsSync(path))
+                continue;
+            const requirements = await context.readRequirements(path);
+            for (const requirement of requirements) {
+                const fact = { service, axis: axis.file, requirement };
+                if (requirement.kind === "ADDED")
+                    addedRequirements.push(fact);
+                if (requirement.kind === "MODIFIED" || requirement.kind === "REMOVED") {
+                    changedRequirements.push(fact);
+                }
+                for (const operationId of requirement.operations) {
+                    // Governing an operation the service already provides is not a
+                    // dependency on anybody: the contract it needs is already merged.
+                    if (livingIds.has(operationId))
+                        continue;
+                    requiredOperations.push({ service, operationId });
+                }
+            }
+        }
+        if (existsSync(paths.openapi)) {
+            const featureOperations = await operations(paths.openapi, context);
+            for (const operation of featureOperations) {
+                if (livingIds.has(operation.id))
+                    continue;
+                if (operation.remove)
+                    requiredOperations.push({ service, operationId: operation.id });
+                else
+                    introducedOperations.push({ service, operationId: operation.id });
+            }
+        }
+    }
+    // The C4 delta is the FOURTH place a feature names an operation, and it was
+    // the one the graph could not see: an edge carrying `metadata { op 'x' }` is
+    // a call this feature builds on `x`, which is exactly the "must land first"
+    // relation this module exists to compute. Validate already says so — it
+    // reports `c4-api.op-pending` when the op is defined by another feature in
+    // flight — so the graph disagreeing with the validator about the same pair of
+    // features was the graph being wrong, not quiet.
+    //
+    // Endpoints resolve through `serviceResolver` — the element's
+    // `metadata { service }` binding, title as fallback — the same join every
+    // other check uses, so renaming a box in a diagram cannot silently unhook it
+    // here either.
+    const deltaPath = featurePaths(feature.dir).delta;
+    if (existsSync(deltaPath)) {
+        const doc = await context.loadLikeC4(deltaPath);
+        // A delta that does not parse proves nothing about who depends on whom.
+        // `loam validate` owns that diagnosis (`delta.invalid`); inventing edges out
+        // of a half-read document would be worse than the silence.
+        if (doc.errors.length === 0) {
+            // One resolver for the whole delta: `serviceOf` rebuilds its id map on
+            // every call, and this loop asks once per edge.
+            const svcOf = serviceResolver(doc.elements);
+            for (const rel of doc.relationships) {
+                if (rel.op === undefined)
+                    continue;
+                const service = svcOf(rel.target);
+                if ((await living(service)).has(rel.op))
+                    continue;
+                requiredOperations.push({ service, operationId: rel.op });
+            }
+        }
+    }
+    return {
+        feature,
+        addedRequirements,
+        changedRequirements,
+        introducedOperations,
+        requiredOperations,
+    };
+}
+function compareReasons(a, b) {
+    const ak = a.kind === "requirement"
+        ? `${a.kind}\0${a.service}\0${a.axis}\0${a.identity}`
+        : `${a.kind}\0${a.service}\0${a.operationId}`;
+    const bk = b.kind === "requirement"
+        ? `${b.kind}\0${b.service}\0${b.axis}\0${b.identity}`
+        : `${b.kind}\0${b.service}\0${b.operationId}`;
+    return compareIds(ak, bk);
+}
+function edgeKey(from, to) {
+    return `${from}\0${to}`;
+}
+function appendReason(edges, from, to, reason) {
+    if (from === to)
+        return;
+    const key = edgeKey(from, to);
+    const edge = edges.get(key) ?? { from, to, reasons: [] };
+    const encoded = JSON.stringify(reason);
+    if (!edge.reasons.some((item) => JSON.stringify(item) === encoded))
+        edge.reasons.push(reason);
+    edges.set(key, edge);
+}
+function stronglyConnected(ids, edges) {
+    const adjacency = new Map(ids.map((id) => [id, []]));
+    for (const edge of edges)
+        adjacency.get(edge.from)?.push(edge.to);
+    for (const targets of adjacency.values())
+        targets.sort(compareIds);
+    let nextIndex = 0;
+    const indices = new Map();
+    const low = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const components = [];
+    const visit = (id) => {
+        indices.set(id, nextIndex);
+        low.set(id, nextIndex);
+        nextIndex += 1;
+        stack.push(id);
+        onStack.add(id);
+        for (const target of adjacency.get(id) ?? []) {
+            if (!indices.has(target)) {
+                visit(target);
+                low.set(id, Math.min(low.get(id), low.get(target)));
+            }
+            else if (onStack.has(target)) {
+                low.set(id, Math.min(low.get(id), indices.get(target)));
+            }
+        }
+        if (low.get(id) !== indices.get(id))
+            return;
+        const component = [];
+        while (stack.length > 0) {
+            const member = stack.pop();
+            onStack.delete(member);
+            component.push(member);
+            if (member === id)
+                break;
+        }
+        component.sort(compareIds);
+        const selfLoop = component.length === 1
+            && (adjacency.get(component[0]) ?? []).includes(component[0]);
+        if (component.length > 1 || selfLoop)
+            components.push(component);
+    };
+    for (const id of [...ids].sort(compareIds))
+        if (!indices.has(id))
+            visit(id);
+    return components.sort((a, b) => compareIds(a[0], b[0]));
+}
+function dependencyFirstOrder(ids, edges) {
+    const deps = new Map(ids.map((id) => [id, []]));
+    for (const edge of edges)
+        deps.get(edge.from)?.push(edge.to);
+    for (const values of deps.values())
+        values.sort(compareIds);
+    const visited = new Set();
+    const visiting = new Set();
+    const order = [];
+    const visit = (id) => {
+        if (visited.has(id) || visiting.has(id))
+            return;
+        visiting.add(id);
+        for (const dependency of deps.get(id) ?? [])
+            visit(dependency);
+        visiting.delete(id);
+        visited.add(id);
+        order.push(id);
+    };
+    for (const id of [...ids].sort(compareIds))
+        visit(id);
+    return order;
+}
+/** Derive the complete active-feature graph, or one feature and its transitive prerequisites. */
+export async function analyzeDependencies(docsDir, featureId, context = new FleetContext()) {
+    const features = await listFeatures(docsDir, {}, context);
+    // Bounded, not `Promise.all`: `readFacts` loads the feature's delta.likec4,
+    // and each of those is a whole Langium workspace held open until the read
+    // finishes — the same resource `validate --all` rations for the same measured
+    // reason (see core/concurrency.ts). This module fanned out over every active
+    // feature at once, and it is not only `loam dependencies` that pays: the fleet
+    // form of `loam status` calls in here too. `inOrder` returns results in input
+    // order, so the graph, the conflict list and their ordering are unchanged.
+    const facts = await inOrder(features, (feature) => readFacts(docsDir, feature, context));
+    const requirementOwners = new Map();
+    // The second index over the SAME identity: who MODIFIES or REMOVES it. Only
+    // the first index existed, so the graph could see "two features add the same
+    // requirement" and was blind to "two features rewrite the same requirement" —
+    // the collision that actually happens on a fleet, and the one whose loser
+    // loses their whole authored text without a word from any command.
+    const changedOwners = new Map();
+    const operationOwners = new Map();
+    for (const fact of facts) {
+        for (const added of fact.addedRequirements) {
+            for (const identity of reqKeys(added.requirement)) {
+                const at = { service: added.service, axis: added.axis, identity };
+                addOwner(requirementOwners, reqIndexKey(at), at, fact.feature.id);
+            }
+        }
+        for (const changed of fact.changedRequirements) {
+            for (const identity of reqKeys(changed.requirement)) {
+                const at = { service: changed.service, axis: changed.axis, identity };
+                addOwner(changedOwners, reqIndexKey(at), at, fact.feature.id);
+            }
+        }
+        for (const operation of fact.introducedOperations) {
+            addOwner(operationOwners, opIndexKey(operation), operation, fact.feature.id);
+        }
+    }
+    const edgeMap = new Map();
+    for (const fact of facts) {
+        for (const changed of fact.changedRequirements) {
+            for (const identity of reqKeys(changed.requirement)) {
+                const at = { service: changed.service, axis: changed.axis, identity };
+                for (const owner of requirementOwners.get(reqIndexKey(at))?.features ?? []) {
+                    appendReason(edgeMap, fact.feature.id, owner, { kind: "requirement", ...at });
+                }
+            }
+        }
+        for (const required of fact.requiredOperations) {
+            for (const owner of operationOwners.get(opIndexKey(required))?.features ?? []) {
+                appendReason(edgeMap, fact.feature.id, owner, { kind: "operation", ...required });
+            }
+        }
+    }
+    let edges = [...edgeMap.values()]
+        .map((edge) => ({ ...edge, reasons: edge.reasons.sort(compareReasons) }))
+        .sort((a, b) => compareIds(a.from, b.from) || compareIds(a.to, b.to));
+    const conflicts = [];
+    for (const [index, change] of [
+        [requirementOwners, "added"],
+        [changedOwners, "changed"],
+    ]) {
+        for (const { at, features } of index.values()) {
+            if (features.size < 2)
+                continue;
+            conflicts.push({
+                kind: "requirement",
+                change,
+                service: at.service,
+                axis: at.axis,
+                identity: at.identity,
+                features: [...features].sort(compareIds),
+            });
+        }
+    }
+    for (const { at, features } of operationOwners.values()) {
+        if (features.size < 2)
+            continue;
+        conflicts.push({
+            kind: "operation",
+            // Two features DEFINING the same operationId — the only way an operation
+            // collides, since removals address a living slot rather than claim one.
+            change: "added",
+            service: at.service,
+            identity: at.operationId,
+            features: [...features].sort(compareIds),
+        });
+    }
+    conflicts.sort((a, b) => compareIds(a.kind, b.kind)
+        || compareIds(a.change, b.change)
+        || compareIds(a.service, b.service)
+        || compareIds(a.axis ?? "", b.axis ?? "")
+        || compareIds(a.identity, b.identity));
+    let selected = new Set(features.map((feature) => feature.id));
+    if (featureId !== undefined) {
+        selected = new Set([featureId]);
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const edge of edges) {
+                if (selected.has(edge.from) && !selected.has(edge.to)) {
+                    selected.add(edge.to);
+                    changed = true;
+                }
+            }
+        }
+        edges = edges.filter((edge) => selected.has(edge.from) && selected.has(edge.to));
+    }
+    const selectedFeatures = features.filter((feature) => selected.has(feature.id));
+    const ids = selectedFeatures.map((feature) => feature.id);
+    const nodes = selectedFeatures.map((feature) => ({
+        id: feature.id,
+        dirName: feature.dirName,
+        services: [...feature.services],
+        dependsOn: edges.filter((edge) => edge.from === feature.id).map((edge) => edge.to).sort(compareIds),
+    }));
+    return {
+        nodes,
+        edges,
+        conflicts: conflicts.filter((conflict) => conflict.features.some((id) => selected.has(id))),
+        order: dependencyFirstOrder(ids, edges),
+        cycles: stronglyConnected(ids, edges),
+    };
+}
+//# sourceMappingURL=dependencies.js.map

package/dist/core/dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../src/core/dependencies.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A read-only dependency/conflict index for active features.\n *\n * This is deliberately derived from parsed artifacts rather than validation\n * messages: issue prose is for people and is not an API.  The graph answers a\n * narrower question — which in-flight change must land before another because\n * it introduces an identity or operation the latter already refers to.\n */\nimport { existsSync } from \"node:fs\";\nimport { inOrder } from \"./concurrency.js\";\nimport { FleetContext } from \"./fleet-context.js\";\nimport { serviceResolver } from \"./likec4.js\";\nimport { operations } from \"./openapi.js\";\nimport {\n  SPEC_AXES,\n  compareIds,\n  featurePaths,\n  featureSpecPaths,\n  listFeatures,\n  servicePaths,\n  type FeatureEntry,\n  type SpecAxis,\n} from \"./repo.js\";\nimport type { Requirement } from \"./spec.js\";\n\nexport type DependencyReason =\n  | {\n      kind: \"requirement\";\n      service: string;\n      axis: SpecAxis[\"file\"];\n      identity: string;\n    }\n  | { kind: \"operation\"; service: string; operationId: string };\n\nexport interface DependencyEdge {\n  /** The feature that consumes/modifies something. */\n  from: string;\n  /** The feature that introduces it and therefore has to land first. */\n  to: string;\n  reasons: DependencyReason[];\n}\n\nexport interface FeatureConflict {\n  kind: \"requirement\" | \"operation\";\n  /**\n   * How the owners collide.\n   *\n   * `added` — two features ADD the same identity (or define the same\n   * operationId): whichever archives second replaces the first outright.\n   *\n   * `changed` — two features MODIFY or REMOVE the same living requirement.\n   * That collision was invisible until now, and it is the more common one on a\n   * fleet: nobody adds \"Cancel an order\" twice, but two teams editing its text\n   * in the same week is a Tuesday. A MODIFIED requirement carries its FULL new\n   * text, so the second archive does not merge the first one's wording — it\n   * overwrites it, silently and completely.\n   */\n  change: \"added\" | \"changed\";\n  service: string;\n  axis?: SpecAxis[\"file\"];\n  identity: string;\n  features: string[];\n}\n\nexport interface DependencyNode {\n  id: string;\n  dirName: string;\n  services: string[];\n  dependsOn: string[];\n}\n\nexport interface DependencyGraph {\n  nodes: DependencyNode[];\n  edges: DependencyEdge[];\n  conflicts: FeatureConflict[];\n  /** Dependencies precede their consumers; cyclic members remain deterministic. */\n  order: string[];\n  /** Strongly connected components with more than one node (or a self-loop). */\n  cycles: string[][];\n}\n\ninterface FeatureFacts {\n  feature: FeatureEntry;\n  addedRequirements: Array<{\n    service: string;\n    axis: SpecAxis[\"file\"];\n    requirement: Requirement;\n  }>;\n  changedRequirements: Array<{\n    service: string;\n    axis: SpecAxis[\"file\"];\n    requirement: Requirement;\n  }>;\n  introducedOperations: Array<{ service: string; operationId: string }>;\n  requiredOperations: Array<{ service: string; operationId: string }>;\n}\n\nfunction reqKeys(requirement: Pick<Requirement, \"id\" | \"name\">): string[] {\n  return [\n    ...(requirement.id === undefined ? [] : [`id:${requirement.id}`]),\n    `name:${requirement.name}`,\n  ];\n}\n\n/**\n * WHERE a collision happens, kept as fields rather than as a string.\n *\n * An index needs one scalar per entry to hash on, so the fields get NUL-joined\n * into a key — but the conflict records want those fields back, and splitting\n * the key apart again means asserting the pieces back into their types. That\n * assertion is a claim about data loam does not own: a service directory or a\n * requirement name containing a NUL would hand `axis` a fragment of an identity\n * with nothing to notice. Carrying the structured value beside the owner set\n * means the key is only ever a key, and the record is read, not reconstructed.\n */\ninterface ReqAt {\n  service: string;\n  axis: SpecAxis[\"file\"];\n  identity: string;\n}\n\ninterface OpAt {\n  service: string;\n  operationId: string;\n}\n\ninterface Owners<T> {\n  readonly at: T;\n  readonly features: Set<string>;\n}\n\nfunction reqIndexKey(at: ReqAt): string {\n  return `${at.service}\\0${at.axis}\\0${at.identity}`;\n}\n\nfunction opIndexKey(at: OpAt): string {\n  return `${at.service}\\0${at.operationId}`;\n}\n\nfunction addOwner<T>(index: Map<string, Owners<T>>, key: string, at: T, feature: string): void {\n  const owners = index.get(key) ?? { at, features: new Set<string>() };\n  owners.features.add(feature);\n  index.set(key, owners);\n}\n\nasync function readFacts(\n  docsDir: string,\n  feature: FeatureEntry,\n  context: FleetContext,\n): Promise<FeatureFacts> {\n  const addedRequirements: FeatureFacts[\"addedRequirements\"] = [];\n  const changedRequirements: FeatureFacts[\"changedRequirements\"] = [];\n  const introducedOperations: FeatureFacts[\"introducedOperations\"] = [];\n  const requiredOperations: FeatureFacts[\"requiredOperations\"] = [];\n\n  /**\n   * The operationIds a service ALREADY has, per service.\n   *\n   * This is the whole difference between a dependency graph and a rumour mill.\n   * A feature's `openapi.yaml` is a COMPLETE document, not a patch — authors\n   * restate the living API around the slot they are changing — so every feature\n   * that so much as mentions `authorizePayment` used to be recorded as\n   * INTRODUCING it, and every other feature governing it as REQUIRING it. Two\n   * features quoting the same living operation therefore depended on each other\n   * in both directions: an invented cycle, an invented conflict, and an ordering\n   * for work that had none. `loam validate`'s coherence pass already subtracts\n   * the living contract this way (core/coherence.ts); this is the same\n   * subtraction, so the two cannot disagree about what \"new\" means.\n   *\n   * Cached per service inside the call and, through the FleetContext, across\n   * features: a fleet-wide graph asks about the same ten services N times.\n   */\n  const livingByService = new Map<string, Set<string>>();\n  const living = async (service: string): Promise<Set<string>> => {\n    let ids = livingByService.get(service);\n    if (ids === undefined) {\n      ids = new Set(\n        (await operations(servicePaths(docsDir, service).openapi, context))\n          .filter((op) => !op.remove)\n          .map((op) => op.id),\n      );\n      livingByService.set(service, ids);\n    }\n    return ids;\n  };\n\n  for (const service of feature.services) {\n    const paths = featureSpecPaths(feature.dir, service);\n    const livingIds = await living(service);\n    for (const axis of SPEC_AXES) {\n      const path = paths[axis.key];\n      if (!existsSync(path)) continue;\n      const requirements = await context.readRequirements(path);\n      for (const requirement of requirements) {\n        const fact = { service, axis: axis.file, requirement };\n        if (requirement.kind === \"ADDED\") addedRequirements.push(fact);\n        if (requirement.kind === \"MODIFIED\" || requirement.kind === \"REMOVED\") {\n          changedRequirements.push(fact);\n        }\n        for (const operationId of requirement.operations) {\n          // Governing an operation the service already provides is not a\n          // dependency on anybody: the contract it needs is already merged.\n          if (livingIds.has(operationId)) continue;\n          requiredOperations.push({ service, operationId });\n        }\n      }\n    }\n\n    if (existsSync(paths.openapi)) {\n      const featureOperations = await operations(paths.openapi, context);\n      for (const operation of featureOperations) {\n        if (livingIds.has(operation.id)) continue;\n        if (operation.remove) requiredOperations.push({ service, operationId: operation.id });\n        else introducedOperations.push({ service, operationId: operation.id });\n      }\n    }\n  }\n\n  // The C4 delta is the FOURTH place a feature names an operation, and it was\n  // the one the graph could not see: an edge carrying `metadata { op 'x' }` is\n  // a call this feature builds on `x`, which is exactly the \"must land first\"\n  // relation this module exists to compute. Validate already says so — it\n  // reports `c4-api.op-pending` when the op is defined by another feature in\n  // flight — so the graph disagreeing with the validator about the same pair of\n  // features was the graph being wrong, not quiet.\n  //\n  // Endpoints resolve through `serviceResolver` — the element's\n  // `metadata { service }` binding, title as fallback — the same join every\n  // other check uses, so renaming a box in a diagram cannot silently unhook it\n  // here either.\n  const deltaPath = featurePaths(feature.dir).delta;\n  if (existsSync(deltaPath)) {\n    const doc = await context.loadLikeC4(deltaPath);\n    // A delta that does not parse proves nothing about who depends on whom.\n    // `loam validate` owns that diagnosis (`delta.invalid`); inventing edges out\n    // of a half-read document would be worse than the silence.\n    if (doc.errors.length === 0) {\n      // One resolver for the whole delta: `serviceOf` rebuilds its id map on\n      // every call, and this loop asks once per edge.\n      const svcOf = serviceResolver(doc.elements);\n      for (const rel of doc.relationships) {\n        if (rel.op === undefined) continue;\n        const service = svcOf(rel.target);\n        if ((await living(service)).has(rel.op)) continue;\n        requiredOperations.push({ service, operationId: rel.op });\n      }\n    }\n  }\n\n  return {\n    feature,\n    addedRequirements,\n    changedRequirements,\n    introducedOperations,\n    requiredOperations,\n  };\n}\n\nfunction compareReasons(a: DependencyReason, b: DependencyReason): number {\n  const ak = a.kind === \"requirement\"\n    ? `${a.kind}\\0${a.service}\\0${a.axis}\\0${a.identity}`\n    : `${a.kind}\\0${a.service}\\0${a.operationId}`;\n  const bk = b.kind === \"requirement\"\n    ? `${b.kind}\\0${b.service}\\0${b.axis}\\0${b.identity}`\n    : `${b.kind}\\0${b.service}\\0${b.operationId}`;\n  return compareIds(ak, bk);\n}\n\nfunction edgeKey(from: string, to: string): string {\n  return `${from}\\0${to}`;\n}\n\nfunction appendReason(\n  edges: Map<string, DependencyEdge>,\n  from: string,\n  to: string,\n  reason: DependencyReason,\n): void {\n  if (from === to) return;\n  const key = edgeKey(from, to);\n  const edge = edges.get(key) ?? { from, to, reasons: [] };\n  const encoded = JSON.stringify(reason);\n  if (!edge.reasons.some((item) => JSON.stringify(item) === encoded)) edge.reasons.push(reason);\n  edges.set(key, edge);\n}\n\nfunction stronglyConnected(ids: string[], edges: DependencyEdge[]): string[][] {\n  const adjacency = new Map(ids.map((id) => [id, [] as string[]]));\n  for (const edge of edges) adjacency.get(edge.from)?.push(edge.to);\n  for (const targets of adjacency.values()) targets.sort(compareIds);\n\n  let nextIndex = 0;\n  const indices = new Map<string, number>();\n  const low = new Map<string, number>();\n  const stack: string[] = [];\n  const onStack = new Set<string>();\n  const components: string[][] = [];\n\n  const visit = (id: string): void => {\n    indices.set(id, nextIndex);\n    low.set(id, nextIndex);\n    nextIndex += 1;\n    stack.push(id);\n    onStack.add(id);\n\n    for (const target of adjacency.get(id) ?? []) {\n      if (!indices.has(target)) {\n        visit(target);\n        low.set(id, Math.min(low.get(id)!, low.get(target)!));\n      } else if (onStack.has(target)) {\n        low.set(id, Math.min(low.get(id)!, indices.get(target)!));\n      }\n    }\n    if (low.get(id) !== indices.get(id)) return;\n    const component: string[] = [];\n    while (stack.length > 0) {\n      const member = stack.pop()!;\n      onStack.delete(member);\n      component.push(member);\n      if (member === id) break;\n    }\n    component.sort(compareIds);\n    const selfLoop = component.length === 1\n      && (adjacency.get(component[0]!) ?? []).includes(component[0]!);\n    if (component.length > 1 || selfLoop) components.push(component);\n  };\n\n  for (const id of [...ids].sort(compareIds)) if (!indices.has(id)) visit(id);\n  return components.sort((a, b) => compareIds(a[0]!, b[0]!));\n}\n\nfunction dependencyFirstOrder(ids: string[], edges: DependencyEdge[]): string[] {\n  const deps = new Map(ids.map((id) => [id, [] as string[]]));\n  for (const edge of edges) deps.get(edge.from)?.push(edge.to);\n  for (const values of deps.values()) values.sort(compareIds);\n  const visited = new Set<string>();\n  const visiting = new Set<string>();\n  const order: string[] = [];\n  const visit = (id: string): void => {\n    if (visited.has(id) || visiting.has(id)) return;\n    visiting.add(id);\n    for (const dependency of deps.get(id) ?? []) visit(dependency);\n    visiting.delete(id);\n    visited.add(id);\n    order.push(id);\n  };\n  for (const id of [...ids].sort(compareIds)) visit(id);\n  return order;\n}\n\n/** Derive the complete active-feature graph, or one feature and its transitive prerequisites. */\nexport async function analyzeDependencies(\n  docsDir: string,\n  featureId?: string,\n  context = new FleetContext(),\n): Promise<DependencyGraph> {\n  const features = await listFeatures(docsDir, {}, context);\n  // Bounded, not `Promise.all`: `readFacts` loads the feature's delta.likec4,\n  // and each of those is a whole Langium workspace held open until the read\n  // finishes — the same resource `validate --all` rations for the same measured\n  // reason (see core/concurrency.ts). This module fanned out over every active\n  // feature at once, and it is not only `loam dependencies` that pays: the fleet\n  // form of `loam status` calls in here too. `inOrder` returns results in input\n  // order, so the graph, the conflict list and their ordering are unchanged.\n  const facts = await inOrder(features, (feature) => readFacts(docsDir, feature, context));\n  const requirementOwners = new Map<string, Owners<ReqAt>>();\n  // The second index over the SAME identity: who MODIFIES or REMOVES it. Only\n  // the first index existed, so the graph could see \"two features add the same\n  // requirement\" and was blind to \"two features rewrite the same requirement\" —\n  // the collision that actually happens on a fleet, and the one whose loser\n  // loses their whole authored text without a word from any command.\n  const changedOwners = new Map<string, Owners<ReqAt>>();\n  const operationOwners = new Map<string, Owners<OpAt>>();\n\n  for (const fact of facts) {\n    for (const added of fact.addedRequirements) {\n      for (const identity of reqKeys(added.requirement)) {\n        const at: ReqAt = { service: added.service, axis: added.axis, identity };\n        addOwner(requirementOwners, reqIndexKey(at), at, fact.feature.id);\n      }\n    }\n    for (const changed of fact.changedRequirements) {\n      for (const identity of reqKeys(changed.requirement)) {\n        const at: ReqAt = { service: changed.service, axis: changed.axis, identity };\n        addOwner(changedOwners, reqIndexKey(at), at, fact.feature.id);\n      }\n    }\n    for (const operation of fact.introducedOperations) {\n      addOwner(operationOwners, opIndexKey(operation), operation, fact.feature.id);\n    }\n  }\n\n  const edgeMap = new Map<string, DependencyEdge>();\n  for (const fact of facts) {\n    for (const changed of fact.changedRequirements) {\n      for (const identity of reqKeys(changed.requirement)) {\n        const at: ReqAt = { service: changed.service, axis: changed.axis, identity };\n        for (const owner of requirementOwners.get(reqIndexKey(at))?.features ?? []) {\n          appendReason(edgeMap, fact.feature.id, owner, { kind: \"requirement\", ...at });\n        }\n      }\n    }\n    for (const required of fact.requiredOperations) {\n      for (const owner of operationOwners.get(opIndexKey(required))?.features ?? []) {\n        appendReason(edgeMap, fact.feature.id, owner, { kind: \"operation\", ...required });\n      }\n    }\n  }\n\n  let edges = [...edgeMap.values()]\n    .map((edge) => ({ ...edge, reasons: edge.reasons.sort(compareReasons) }))\n    .sort((a, b) => compareIds(a.from, b.from) || compareIds(a.to, b.to));\n\n  const conflicts: FeatureConflict[] = [];\n  for (const [index, change] of [\n    [requirementOwners, \"added\"],\n    [changedOwners, \"changed\"],\n  ] as const) {\n    for (const { at, features } of index.values()) {\n      if (features.size < 2) continue;\n      conflicts.push({\n        kind: \"requirement\",\n        change,\n        service: at.service,\n        axis: at.axis,\n        identity: at.identity,\n        features: [...features].sort(compareIds),\n      });\n    }\n  }\n  for (const { at, features } of operationOwners.values()) {\n    if (features.size < 2) continue;\n    conflicts.push({\n      kind: \"operation\",\n      // Two features DEFINING the same operationId — the only way an operation\n      // collides, since removals address a living slot rather than claim one.\n      change: \"added\",\n      service: at.service,\n      identity: at.operationId,\n      features: [...features].sort(compareIds),\n    });\n  }\n  conflicts.sort((a, b) =>\n    compareIds(a.kind, b.kind)\n    || compareIds(a.change, b.change)\n    || compareIds(a.service, b.service)\n    || compareIds(a.axis ?? \"\", b.axis ?? \"\")\n    || compareIds(a.identity, b.identity));\n\n  let selected = new Set(features.map((feature) => feature.id));\n  if (featureId !== undefined) {\n    selected = new Set<string>([featureId]);\n    let changed = true;\n    while (changed) {\n      changed = false;\n      for (const edge of edges) {\n        if (selected.has(edge.from) && !selected.has(edge.to)) {\n          selected.add(edge.to);\n          changed = true;\n        }\n      }\n    }\n    edges = edges.filter((edge) => selected.has(edge.from) && selected.has(edge.to));\n  }\n\n  const selectedFeatures = features.filter((feature) => selected.has(feature.id));\n  const ids = selectedFeatures.map((feature) => feature.id);\n  const nodes = selectedFeatures.map((feature): DependencyNode => ({\n    id: feature.id,\n    dirName: feature.dirName,\n    services: [...feature.services],\n    dependsOn: edges.filter((edge) => edge.from === feature.id).map((edge) => edge.to).sort(compareIds),\n  }));\n\n  return {\n    nodes,\n    edges,\n    conflicts: conflicts.filter((conflict) => conflict.features.some((id) => selected.has(id))),\n    order: dependencyFirstOrder(ids, edges),\n    cycles: stronglyConnected(ids, edges),\n  };\n}\n"]}

package/dist/core/docs.js

@@ -0,0 +1,144 @@
+/**
+ * Scaffolding for the shared docs repo.
+ *
+ * There is deliberately no manifest. `init` used to write a `loam.docs.json`
+ * listing the repo's services; nothing ever read it — `repo.ts` enumerates from
+ * the filesystem, because files are the source of truth — and nothing ever
+ * updated it, so it named an empty fleet forever. A second list of services is
+ * exactly the drift `loam validate` now cross-checks the landscape for; the
+ * cheapest way to keep it honest is not to have it.
+ */
+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";
+/**
+ * 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 —
+ * `init` will not join one without it, and every enumerating command refuses a
+ * `docsDir` that has none. So it is laid down even when nothing is in it yet.
+ */
+export const DOCS_SUBDIRS = ["architecture", "services", "features"];
+/**
+ * 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\`) — but scope them,
+// because computing a view 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 docs repo's own loam.json. It makes the docs repo self-describing: a
+ * command run from inside it (or from any directory under it) finds this file
+ * first and resolves the fleet to the repo it is standing in, instead of
+ * walking out to whatever service repo happens to be above.
+ *
+ * `"."` and not an absolute path for the same reason every other docsDir is
+ * stored as written: this file is committed and cloned to machines whose
+ * directory layout nobody here can predict.
+ */
+const DOCS_SELF_CONFIG = `${JSON.stringify({ docsDir: "." }, null, 2)}\n`;
+/** Idempotently create the docs-repo skeleton. Existing files/dirs are left untouched. */
+export async function scaffoldDocs(docsDir) {
+    const root = resolve(docsDir);
+    const created = [];
+    await mkdir(root, { recursive: true });
+    for (const dir of DOCS_SUBDIRS) {
+        const p = join(root, dir);
+        if (!existsSync(p)) {
+            await mkdir(p, { recursive: true });
+            created.push(p);
+        }
+    }
+    // Never overwritten, all three of them — a team's own house rules, their own
+    // map and their own config outrank the template. The order here IS the order
+    // `init` probes for what it will skip; keep the two lists in step.
+    for (const [rel, content] of docsRepoFiles()) {
+        const path = join(root, rel);
+        if (!existsSync(path)) {
+            await writeFile(path, content, "utf8");
+            created.push(path);
+        }
+    }
+    return { root, created };
+}
+/**
+ * The files every docs repo starts with, relative to its root, in creation
+ * order. `init` scaffolds them directly; `migrate-openspec` stages the same
+ * bytes into its target, because the whole point of migrating into a docs repo
+ * is that it be the docs repo `loam init` makes.
+ *
+ * Exported as paths only (via `plannedDocsFiles`) where `init` reports what it
+ * will skip — a duplicate list is exactly the drift that made `created +
+ * skipped` disagree with reality.
+ */
+export function docsRepoFiles(opts = {}) {
+    const preamble = opts.landscapePreamble === undefined ? "" : `${opts.landscapePreamble.trimEnd()}\n//\n`;
+    return [
+        // 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],
+        [join("architecture", "landscape.likec4"), `${preamble}${LANDSCAPE_STUB}`],
+        ["loam.json", DOCS_SELF_CONFIG],
+    ];
+}
+/** Everything `scaffoldDocs(docsDir)` would create, in the order it creates it. */
+export function plannedDocsFiles(docsDir) {
+    const root = resolve(docsDir);
+    return [
+        ...DOCS_SUBDIRS.map((d) => join(root, d)),
+        ...docsRepoFiles().map(([rel]) => join(root, rel)),
+    ];
+}
+//# sourceMappingURL=docs.js.map

package/dist/core/docs.js.map

@@ -0,0 +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 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\\`) — but scope them,\n// because computing a view 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 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  ];\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"]}