@sdd-method/maintain-cli 0.0.0-stage → 0.1.0

package/dist/lib/catalogue/cli-version.js

@@ -0,0 +1,10 @@
+/**
+ * sdd-cli version constant, used in error messages from the catalogue
+ * builder + aggregator + validate subcommands.
+ *
+ * Read from package.json via getSddCliVersion() (the ENGINE version, also in a persona package) to guarantee the
+ * constant cannot drift from the published version.
+ */
+import { getSddCliVersion } from "../package-version.js";
+export const CLI_VERSION = getSddCliVersion();
+//# sourceMappingURL=cli-version.js.map

package/dist/lib/catalogue/contract-id.js

@@ -0,0 +1,49 @@
+// Contract row identity (schema 3.0.0) and the legacy-id migration map —
+// M-ADR 0203 §4.4, the cut's acid test.
+//
+// From 3.0.0 a contract id carries its KIND component: `{domain}-{stem}-{kind}`
+// (kind ∈ rest | graphql | rpc | event | authz). The kindless 2.x form made one
+// measured collision class unrepresentable: a service published as two contract
+// families (`calendar-service.yaml` + `calendar_service.proto`) minted one id,
+// costing a live estate one row and two edges permanently, and mislabelling
+// legitimate shared-contract citation as divergence.
+//
+// The map is mechanical in both directions: new id = `${old id}-${kind}`, from
+// two columns every committed catalogue carries (`id`, `kind`). It ships via
+// `sdd-cli catalogue migration-map`; the alias-file re-key (M-ADR 0147 targets
+// are authored copies of tool-minted ids — regenerable, not drift, the same
+// rule as external_system_exemption) consults the in-build form of it.
+/** The 3.0.0 contract id: the kindless slug with its kind appended. */
+export function contractIdWithKind(kindlessSlug, kind) {
+    return kindlessSlug === "" ? "" : `${kindlessSlug}-${kind}`;
+}
+/**
+ * legacy (2.x, kindless) id → the 3.0.0 kind-suffixed ids it maps to, from
+ * built rows. More than one target means the id was a measured collision
+ * under 2.x (two families sharing one kindless slug) — the consumer decides
+ * which family is meant, loudly, never by guess.
+ */
+export function buildLegacyContractIdMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const id = String(row["id"] ?? "");
+        const kind = String(row["kind"] ?? "");
+        if (id === "" || kind === "" || !id.endsWith(`-${kind}`))
+            continue;
+        const legacy = id.slice(0, -(kind.length + 1));
+        if (legacy === "")
+            continue;
+        const ids = map.get(legacy);
+        if (ids) {
+            if (!ids.includes(id))
+                ids.push(id);
+        }
+        else {
+            map.set(legacy, [id]);
+        }
+    }
+    for (const ids of map.values())
+        ids.sort((a, b) => a.localeCompare(b));
+    return map;
+}
+//# sourceMappingURL=contract-id.js.map

package/dist/lib/catalogue/contract-path-resolution.js

@@ -0,0 +1,149 @@
+// Contract-path resolution at aggregation tier (post-3.0.0-followons.md A2 step 5).
+//
+// WHY THIS LIVES AT AGGREGATE TIER AND NOWHERE ELSE
+//   `app-platform-dependencies.yaml` declares, per dependency, the contract the
+//   consuming app binds to. Both distributed templates say that path is relative
+//   to the platform repo root — and in a federation that rule cannot express the
+//   truth, because one app's dependencies span several platform SDDs. Measured in
+//   a 67-SDD reverse estate: 21 of 152 declared paths name a contract owned by a
+//   DIFFERENT platform SDD than the one the app would be validated against, and
+//   their authors compensated by prefixing `platform/<sdd-id>/` — writing the
+//   truth against a rule that could not hold it.
+//
+//   The app-tier gate therefore cannot resolve these at all: given one
+//   --platform-root it reports LOCKED UNMET for a contract that exists. That is a
+//   false failure of the instrument, and no amount of app-tier cleverness fixes it
+//   — the file is in a sibling the app repo cannot see. At aggregate tier every
+//   SDD root IS visible, so resolution becomes possible for the first time.
+//   Same argument as M-ADR 0198: a join that can span SDDs belongs where the SDDs
+//   are all present.
+//
+// WHAT IT DOES NOT DO
+//   It does not rewrite anything or pick a winner when a path is ambiguous. An
+//   ambiguous path is reported as a divergence and left alone, because guessing
+//   which sibling a contract came from is exactly the silent-wrong-answer this
+//   whole arc has been removing.
+/**
+ * True when the declared value is shaped like a repo-relative path, as opposed to
+ * a sentinel or a prose note.
+ *
+ * The reverse template types this field `<platform-relative-path-or-unknown>`,
+ * which openly admits a non-path value — so `n/a` is the template being followed
+ * and free text is that licence stretched. Both are reported, neither is treated
+ * as a path, and NEITHER is silently ignored: an unresolvable declaration that
+ * nothing mentions is indistinguishable from a resolved one in the output.
+ */
+export function isPathShaped(value) {
+    const v = value.trim();
+    if (v === "" || v === "null")
+        return false;
+    if (v.toLowerCase().startsWith("n/a"))
+        return false;
+    if (v.startsWith("["))
+        return false;
+    // Prose gives itself away with whitespace before the first separator
+    // ("Kafka (<vendor> bus): topic-a / topic-b", "Kinesis: <stream-name>").
+    const firstSegment = v.split("/")[0] ?? "";
+    if (/\s/.test(firstSegment))
+        return false;
+    // A path must actually have a directory part; a bare token is not a contract path.
+    return v.includes("/");
+}
+/**
+ * Strip a leading `platform/<name>/` when `<name>` identifies a known SDD — by its
+ * sdd_id OR by its directory basename, and the distinction is not cosmetic: an
+ * author writing this prefix is reading it off the filesystem, so it is the
+ * DIRECTORY they write. In one measured estate every such prefix is
+ * `platform/sdd-experience-platform/` while that SDD's declared sdd_id is
+ * `experience-platform` — matching on sdd_id alone therefore split nothing and
+ * reported 13 existing contracts as missing. Both keys are accepted.
+ *
+ * That prefix
+ * is the estate-relative form authors reached for when the declared
+ * platform-root-relative base could not name a sibling's contract. Returns the
+ * owning SDD id and the path relative to ITS root, or null when the value carries
+ * no such prefix.
+ */
+export function splitEstateRelative(value, roots) {
+    const parts = value.trim().split("/");
+    if (parts.length < 3)
+        return null;
+    if (parts[0] !== "platform")
+        return null;
+    const sddId = parts[1] ?? "";
+    if (!roots.has(sddId))
+        return null;
+    return { sddId, relPath: parts.slice(2).join("/") };
+}
+/**
+ * Resolve every declared contract_path against the SDD roots present in this
+ * aggregation, emitting one finding per unresolved declaration.
+ *
+ * `exists` is injected so this is testable without a filesystem, and so the
+ * caller owns the stat strategy.
+ */
+export async function resolveContractPaths(productPlatformDeps, roots, aliases, exists, findings) {
+    let resolved = 0;
+    let missing = 0;
+    let ambiguous = 0;
+    let nonPath = 0;
+    let absent = 0;
+    // One stat per (root, path) pair at worst. Cached because a shared platform
+    // contract is declared by many consumers — in the measured estate the same
+    // embedding contract is named by 21 dependencies.
+    const cache = new Map();
+    const existsCached = async (abs) => {
+        const hit = cache.get(abs);
+        if (hit !== undefined)
+            return hit;
+        const got = await exists(abs);
+        cache.set(abs, got);
+        return got;
+    };
+    for (const dep of productPlatformDeps) {
+        const declared = String(dep["contract_path"] ?? "").trim();
+        const who = `${String(dep["source_sdd_id"] ?? "")}/${String(dep["product_id"] ?? "")}`;
+        const target = String(dep["target_service_id"] ?? "") ||
+            String(dep["target_capability_id"] ?? "") ||
+            "(unnamed target)";
+        if (declared === "" || declared === "null") {
+            absent++;
+            continue;
+        }
+        if (!isPathShaped(declared)) {
+            nonPath++;
+            findings.add("convention", `contract_path: ${who} → ${target} declares contract_path="${declared}", which is not a path — it cannot be resolved, and the dependency has no verifiable contract`);
+            continue;
+        }
+        const estate = splitEstateRelative(declared, aliases);
+        if (estate !== null) {
+            const abs = `${aliases.get(estate.sddId)}/${estate.relPath}`;
+            if (await existsCached(abs)) {
+                resolved++;
+            }
+            else {
+                missing++;
+                findings.add("orphan", `contract_path: ${who} → ${target} declares contract_path="${declared}", naming SDD "${estate.sddId}", but no file exists there`);
+            }
+            continue;
+        }
+        const hits = [];
+        for (const [sddId, root] of roots) {
+            if (await existsCached(`${root}/${declared}`))
+                hits.push(sddId);
+        }
+        if (hits.length === 1) {
+            resolved++;
+        }
+        else if (hits.length === 0) {
+            missing++;
+            findings.add("orphan", `contract_path: ${who} → ${target} declares contract_path="${declared}" but it resolves under none of the ${roots.size} SDD root(s) in this aggregation`);
+        }
+        else {
+            ambiguous++;
+            findings.add("divergence", `contract_path: ${who} → ${target} declares contract_path="${declared}", which resolves under ${hits.length} SDD roots (${hits.join(", ")}) — not guessed; qualify the path or name the owning SDD`);
+        }
+    }
+    return { resolved, missing, ambiguous, nonPath, absent };
+}
+//# sourceMappingURL=contract-path-resolution.js.map