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

package/dist/lib/catalogue/builders/repositories.js

@@ -0,0 +1,458 @@
+// Repositories discoverer — emits `repositories.csv` rows from
+// `orchestration/repo-config/<domain>/<repo>.yaml` (recursive).
+//
+// Per ADR 0134 + Q7.1 resolution: `service_type` is constrained to the
+// canonical `enums.service_type` set (api_service, worker, gateway,
+// frontend, mobile, library, infrastructure, documentation). Unknown
+// values log a `[finding] convention` and are kept verbatim — the FK
+// validator doesn't enforce enum membership today, but a coverage
+// report can flag drift.
+//
+// Each repo's primary_key (`id`) is the bare repo slug (after the org
+// prefix if present). `name` keeps the full `org/slug` form when the
+// config declares it.
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join, relative } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { readCatalogueCsv } from "../csv-reader.js";
+import { runtimeServiceTypes, } from "../schema-loader.js";
+const REPO_CONFIG_DIR_REL = join("orchestration", "repo-config");
+// LOC metrics report, produced out-of-band by the `measure-loc` skill.
+// Keyed by repo slug (`repo_name`), which equals repositories.id. Optional:
+// only the platform-profile SDD carries it; absence leaves the LOC columns
+// empty (logged once as a coverage finding).
+const LOC_REPORT_REL = join("docs", "platform", "reference", "loc-report.csv");
+// Per-repo reverse metadata, written by the reverse tooling at
+// `repos/<slug>/reverse-metadata.yaml`. Carries that repo's OWN `profile`,
+// which is not the SDD's: an integration SDD routinely mirrors a
+// `support-repo` (a shared library, a vendor proto, device firmware) next to
+// its `integration-product` components. Optional — absent for SDDs whose
+// components are generated rather than cloned, and for forward SDDs with no
+// mirrored source, where the manifest profile remains the honest answer.
+const REPOS_DIR_REL = "repos";
+const REVERSE_METADATA_BASENAME = "reverse-metadata.yaml";
+const ContractsBlockSchema = z
+    .object({
+    openapi: z.array(z.string()).optional(),
+    proto: z.array(z.string()).optional(),
+    avro: z.array(z.string()).optional(),
+})
+    .optional();
+const EventEntrySchema = z.object({
+    topic: z.string().optional(),
+    schema: z.string().optional(),
+});
+const EventsBlockSchema = z
+    .object({
+    produces: z.array(EventEntrySchema).optional(),
+    consumes: z.array(EventEntrySchema).optional(),
+})
+    .optional();
+// `capability_exemption` (M-ADR 0188 §4.2) is typed loosely ON PURPOSE.
+//
+// A schema violation here does not reject the block — it rejects the whole
+// repo-config, and `buildRepositories` then `continue`s past it, so the
+// repository never reaches `repositories.csv` at all. A repo that vanishes
+// from the catalogue also vanishes from the coverage invariant, which would
+// make a malformed exemption the most effective silencer in the method.
+//
+// So: parse permissively, validate in the exemption builder, and drop only
+// the exemption row. The repository survives, resolves to nothing, and is
+// reported as an orphan. Failing open on the row and closed on the
+// repository is the only ordering that cannot be abused.
+const CapabilityExemptionSchema = z
+    .object({
+    reason: z.unknown().optional(),
+    note: z.unknown().optional(),
+})
+    .optional();
+// `service_capability_exemption` (M-ADR 0133 §4.2b) — same shape and same
+// permissive-parse reasoning as `capability_exemption` above, one tier down.
+const ServiceCapabilityExemptionSchema = z
+    .object({
+    reason: z.unknown().optional(),
+    note: z.unknown().optional(),
+})
+    .optional();
+// `services` (M-ADR 0197) is typed loosely ON PURPOSE, same reasoning as
+// `capability_exemption` above: a schema violation here must not reject the
+// whole repo-config. Shape and per-entry validation happen in the services
+// builder, which drops only the malformed block or entry and reports an
+// orphan finding — the repository always survives.
+const ServicesBlockSchema = z.unknown().optional();
+// `additional_context` accepts strings OR loosely-parsed key:value
+// objects (which arise when adopters leave colons unquoted in their
+// YAML — e.g. `- docs/.../ADR 0017: Use WorkOS for Auth.md`). The
+// canonical builder reconstructs the original string downstream.
+const RepoConfigSchema = z.object({
+    repo: z.string(),
+    // Explicit repositories.id. Without it the id is the last segment of
+    // `repo:`, so an existing repository and a generated replacement that shares
+    // its short name (M-ADR 0214 §4.2 qualified member keys) would collide.
+    id: z.string().optional(),
+    domain: z.string().optional(),
+    service_type: z.string().optional(),
+    description: z.string().optional(),
+    tier: z.string().optional(),
+    group: z.string().optional(),
+    category: z.string().optional(),
+    additional_context: z.array(z.unknown()).optional(),
+    // Forward-declared capability edges (M-ADR 0188 §6.1). Capability spec
+    // paths, relative to the SDD root. Unlike `additional_context`, this block
+    // is single-purpose, so an entry that resolves to no capability is an
+    // error worth reporting rather than a non-match to skip silently.
+    capabilities: z.array(z.string()).optional(),
+    capability_exemption: CapabilityExemptionSchema,
+    service_capability_exemption: ServiceCapabilityExemptionSchema,
+    contracts: ContractsBlockSchema,
+    events: EventsBlockSchema,
+    services: ServicesBlockSchema,
+    // Build-time and generation-time dependencies on other repositories (M-ADR 0217 §4.2).
+    // Shape-checked loosely here; buildRepoDependencies validates each entry and reports
+    // a bad one, so one malformed entry does not drop the whole repo-config.
+    depends_on: z.array(z.unknown()).optional(),
+});
+/**
+ * Reconstruct a string from a possibly-mis-parsed YAML list entry.
+ *
+ * Adopters sometimes write list entries with unquoted colons like:
+ *   - docs/.../ADR 0017: Use WorkOS for Auth.md
+ *
+ * The YAML parser reads each such entry as a single-key object whose key
+ * is the part before the first colon and whose value is the part after.
+ * This helper rejoins them so the consuming code sees a plain string.
+ *
+ * Returns null if the entry isn't a string and can't be rejoined cleanly.
+ */
+export function normaliseAdditionalContextEntry(entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+        const keys = Object.keys(entry);
+        if (keys.length === 1) {
+            const k = keys[0];
+            const v = entry[k];
+            if (typeof v === "string")
+                return `${k}: ${v}`;
+            if (v === null)
+                return k;
+        }
+    }
+    return null;
+}
+export async function buildRepositories(inputs) {
+    const configs = await loadRepoConfigs(inputs.sddPath, inputs.findings);
+    const validServiceTypes = canonicalServiceTypeValues(inputs.schema);
+    // Only attempt the LOC join when there are repos to annotate — avoids a
+    // spurious second coverage finding for SDDs with no repo-config at all.
+    const locByRepo = configs.length > 0
+        ? await loadLocReport(inputs.sddPath, inputs.findings)
+        : new Map();
+    const repoMeta = configs.length > 0
+        ? await loadRepoProfiles(inputs.sddPath, inputs.findings, inputs.manifest.profile)
+        : new Map();
+    const rows = [];
+    for (const cfg of configs) {
+        const repoFull = cfg.data.repo;
+        const repoId = cfg.repoId;
+        const serviceType = cfg.data.service_type ?? "";
+        const domain = cfg.data.domain ?? "";
+        if (serviceType !== "" && !validServiceTypes.has(serviceType)) {
+            inputs.findings.add("convention", `${cfg.relPath}: service_type "${serviceType}" not in canonical enum (${[...validServiceTypes].join(", ")})`);
+        }
+        let resolvedDomain = domain;
+        if (domain === "") {
+            inputs.findings.add("convention", `${cfg.relPath}: missing required \`domain\` field`);
+        }
+        else if (!inputs.knownDomainIds.has(domain)) {
+            // Per ADR 0136: leave domain_id empty when the declared domain
+            // doesn't resolve locally (typical for app/integration SDDs whose
+            // repo-config declares "applications"/"integrations").
+            //
+            // NOT `orphan`, and the argument is about TIER rather than a relabelling
+            // of the same claim. A locally-unresolvable domain is two different
+            // things and THIS TIER CANNOT TELL THEM APART: ADR 0136 externality (the
+            // domain is owned by a sibling SDD — correct, expected, nothing to fix)
+            // or a genuinely dangling domain name (a typo). The discriminator lives
+            // at estate scope, not here. Measured across two estates: 137
+            // locally-unresolvable declarations, of which 137 resolve in a sibling
+            // and 0 resolve nowhere — and none in a platform-profile SDD.
+            //
+            // So `orphan` — which the gate acts on per M-ADR 0132 §4.3 — asserted a
+            // defect at a tier that cannot establish one, the failure M-ADR 0199
+            // §4.2 names. `inferred` records the builder's documented resolution
+            // (empty the column, keep the repository) without claiming a defect this
+            // build cannot see.
+            inputs.findings.add("inferred", `${cfg.relPath}: domain "${domain}" has no docs/domains/${domain}/ directory — domain_id left empty per ADR 0136. Whether that is external ownership or a dangling name is decidable only at estate scope`);
+            resolvedDomain = "";
+        }
+        const loc = locByRepo.get(repoId);
+        rows.push({
+            id: repoId,
+            name: repoFull,
+            domain_id: resolvedDomain,
+            product_id: inputs.productId,
+            // The repo's own profile where the reverse tooling recorded one;
+            // the SDD's only as a fallback. Stamping the SDD's profile onto every
+            // row typed a mirrored support-repo as an `integration-product`
+            // component — a wrong value in a populated column, which reads as
+            // authoritative and makes a filter on it return the same set as no
+            // filter at all.
+            profile: repoMeta.get(repoId)?.profile ?? inputs.manifest.profile,
+            // M-ADR 0213: whether the repository is inside this SDD's scope; empty when it has no reverse
+            // metadata (a forward SDD's generated components) or cannot be decided.
+            repo_scope: repoMeta.get(repoId)?.scope ?? "",
+            group: cfg.data.group ?? "",
+            category: cfg.data.category ?? "",
+            tier: cfg.data.tier ?? "",
+            component_type: serviceType,
+            files: loc?.files ?? "",
+            code: loc?.code ?? "",
+            comment: loc?.comment ?? "",
+            blank: loc?.blank ?? "",
+            total_lines: loc?.total_lines ?? "",
+            languages: loc?.languages ?? "",
+            doc_path: cfg.relPath,
+            source_sdd_id: "",
+        });
+    }
+    return { rows, configs };
+}
+async function loadRepoConfigs(sddPath, findings) {
+    const baseDir = join(sddPath, REPO_CONFIG_DIR_REL);
+    let yamlPaths;
+    try {
+        yamlPaths = await collectYamlPaths(baseDir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            findings.add("coverage", `${REPO_CONFIG_DIR_REL}/ not found — emitting empty repositories.csv`);
+            return [];
+        }
+        throw err;
+    }
+    const configs = [];
+    for (const path of yamlPaths) {
+        if (path.endsWith("schema.yaml") || path.endsWith("schema.yml")) {
+            // schema files are tooling, not repo config
+            continue;
+        }
+        const text = await readFile(path, "utf-8");
+        let raw;
+        try {
+            raw = parseYaml(text);
+        }
+        catch (err) {
+            findings.add("convention", `failed to parse YAML at ${relative(sddPath, path)}: ${err.message}`);
+            continue;
+        }
+        if (!raw || typeof raw !== "object") {
+            findings.add("convention", `${relative(sddPath, path)}: not an object — skipped`);
+            continue;
+        }
+        const parsed = RepoConfigSchema.safeParse(raw);
+        if (!parsed.success) {
+            const issues = parsed.error.issues
+                .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+                .join("; ");
+            findings.add("convention", `${relative(sddPath, path)}: schema violation — ${issues}`);
+            continue;
+        }
+        const repoFull = parsed.data.repo;
+        const explicitId = parsed.data.id?.trim() ?? "";
+        const repoId = explicitId !== ""
+            ? explicitId
+            : repoFull.includes("/")
+                ? (repoFull.split("/").slice(-1)[0] ?? repoFull)
+                : repoFull;
+        configs.push({
+            path,
+            relPath: relative(sddPath, path),
+            data: parsed.data,
+            repoId,
+        });
+    }
+    // Deterministic order by relative path (for sorted repo IDs).
+    configs.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    // Two configs deriving one id would silently lose a row downstream; keep the
+    // first and say which one went.
+    const byId = new Map();
+    const kept = [];
+    for (const cfg of configs) {
+        const prior = byId.get(cfg.repoId);
+        if (prior !== undefined) {
+            findings.add("convention", `${cfg.relPath}: repository id '${cfg.repoId}' is already derived by ${prior} — the first is kept; set an explicit \`id:\` on one of them`);
+            continue;
+        }
+        byId.set(cfg.repoId, cfg.relPath);
+        kept.push(cfg);
+    }
+    return kept;
+}
+const REPO_SCOPES = ["component", "support"];
+/**
+ * The legacy per-repo `profile` recorded only a binary (M-ADR 0213 §1: 662 of 663
+ * measured repositories): the SDD's own profile means a component, `support-repo`
+ * means support. Any other value is not mapped — it needs a human (§4.5 step 3).
+ */
+export function scopeFromLegacyProfile(profile, sddProfile) {
+    if (profile === "support-repo")
+        return "support";
+    if (profile === sddProfile)
+        return "component";
+    return undefined;
+}
+/**
+ * Every folder under `repos/` that holds a reverse-metadata.yaml, relative to `repos/`,
+ * sorted. A docs-corpus SDD groups its mirrors (`repos/<group>/<id>/`), and reading only
+ * `repos/<id>/` left all of one estate's 221 grouped files unread — their repo_scope
+ * silently empty in the catalogue. A folder that holds the file is a repository's own
+ * doc set, so the walk does not descend below it; dot-folders are skipped.
+ */
+async function metadataDirs(root, rel = "") {
+    let entries;
+    try {
+        entries = await readdir(join(root, rel), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries.filter((x) => x.isDirectory() && !x.name.startsWith(".")).sort((a, b) => a.name.localeCompare(b.name))) {
+        const child = rel === "" ? e.name : join(rel, e.name);
+        try {
+            await readFile(join(root, child, REVERSE_METADATA_BASENAME), "utf8");
+            out.push(child);
+        }
+        catch {
+            out.push(...(await metadataDirs(root, child)));
+        }
+    }
+    return out;
+}
+async function loadRepoProfiles(sddPath, findings, sddProfile) {
+    const out = new Map();
+    const root = join(sddPath, REPOS_DIR_REL);
+    const keyedFrom = new Map();
+    for (const dirRel of await metadataDirs(root)) {
+        let raw;
+        try {
+            raw = await readFile(join(root, dirRel, REVERSE_METADATA_BASENAME), "utf8");
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseYaml(raw);
+        }
+        catch (err) {
+            // A file that EXISTS and cannot be parsed is not the same fact as a
+            // file that is absent, and the fallback treats them identically — the
+            // row silently keeps the SDD's profile and looks exactly like a repo
+            // that was never reverse-analysed. Say so, or the next reader debugs
+            // the builder instead of the one malformed line.
+            findings.add("convention", `${join(REPOS_DIR_REL, dirRel, REVERSE_METADATA_BASENAME)}: not parseable as YAML (${err.code ?? "parse error"}) — profile falls back to the SDD's, which may mistype this repo`);
+            continue;
+        }
+        const file = join(REPOS_DIR_REL, dirRel, REVERSE_METADATA_BASENAME);
+        // The repository this file describes: its own canonical_repo_key, else its folder
+        // name. Measured across both estates: no file carries a key that disagrees with
+        // its folder, so every file read before keys exactly as before.
+        const rawKey = parsed?.canonical_repo_key;
+        const repoKey = typeof rawKey === "string" && rawKey.trim() !== "" ? rawKey.trim() : basename(dirRel);
+        const prior = keyedFrom.get(repoKey);
+        if (prior !== undefined) {
+            // Report-only for now (convention, not divergence): reading grouped metadata surfaces
+            // duplicates that were always there (2 in the one estate that groups), and a new
+            // gate-acting finding would turn a regression baseline red on old facts. It gates
+            // once both estates read zero, as the recorded-path check does.
+            findings.add("convention", `${file}: describes repository '${repoKey}', already described by ${prior} — the first is kept; one of the two is misfiled`);
+            continue;
+        }
+        keyedFrom.set(repoKey, file);
+        const rawRole = parsed?.repo_scope;
+        const rawProfile = parsed?.profile;
+        const profile = typeof rawProfile === "string" && rawProfile.trim() !== "" ? rawProfile.trim() : undefined;
+        let scope;
+        if (typeof rawRole === "string" && rawRole.trim() !== "") {
+            if (REPO_SCOPES.includes(rawRole.trim())) {
+                scope = rawRole.trim();
+            }
+            else {
+                findings.add("convention", `${file}: repo_scope '${rawRole.trim()}' is not one of ${REPO_SCOPES.join(", ")} (M-ADR 0213 §4.2)`);
+            }
+        }
+        else if (profile !== undefined) {
+            scope = scopeFromLegacyProfile(profile, sddProfile);
+            if (scope === undefined) {
+                findings.add("convention", `${file}: legacy profile '${profile}' is neither this SDD's profile nor support-repo, so it maps to no repo_scope — decide component or support by hand (M-ADR 0213 §4.5)`);
+            }
+        }
+        if (profile === undefined && scope === undefined) {
+            findings.add("convention", `${file}: no usable \`repo_scope\` or legacy \`profile\` — profile falls back to the SDD's, which may mistype this repo`);
+            continue;
+        }
+        // A repository migrated to repo_scope keeps the deprecated column consistent
+        // until its removal: support reads support-repo, component the SDD's profile.
+        out.set(repoKey, {
+            profile: profile ?? (scope === "support" ? "support-repo" : sddProfile),
+            ...(scope ? { scope } : {}),
+        });
+    }
+    return out;
+}
+async function loadLocReport(sddPath, findings) {
+    const out = new Map();
+    const path = join(sddPath, LOC_REPORT_REL);
+    let parsed;
+    try {
+        parsed = await readCatalogueCsv(path);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            findings.add("coverage", `${LOC_REPORT_REL} not found — LOC columns left empty (run the measure-loc skill to populate)`);
+            return out;
+        }
+        throw err;
+    }
+    for (const row of parsed.rows) {
+        const repo = (row["repo_name"] ?? "").trim();
+        if (repo === "")
+            continue;
+        out.set(repo, {
+            files: row["files"] ?? "",
+            code: row["code"] ?? "",
+            comment: row["comment"] ?? "",
+            blank: row["blank"] ?? "",
+            total_lines: row["total_lines"] ?? "",
+            languages: row["languages"] ?? "",
+        });
+    }
+    return out;
+}
+async function collectYamlPaths(dir) {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...(await collectYamlPaths(full)));
+        }
+        else if (entry.isFile() &&
+            (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml"))) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+function canonicalServiceTypeValues(schema) {
+    const enumDef = schema.enums["service_type"];
+    if (!enumDef) {
+        // Fall back to runtime types if the canonical enum is missing
+        return new Set(runtimeServiceTypes(schema));
+    }
+    return new Set(enumDef.values.map((v) => v.value));
+}
+//# sourceMappingURL=repositories.js.map

package/dist/lib/catalogue/builders/scaffolds.js

@@ -0,0 +1,197 @@
+/**
+ * Scaffold declarations walker (M-ADR 0207 §4.1, schema 3.4.0).
+ *
+ * Reads `orchestration/scaffolds/*.yaml` — the authored surface for forward
+ * scaffold declarations — and derives `scaffolds` + `scaffold_items` rows.
+ * The manifest declares intent; this builder's RESOLUTION PASS derives each
+ * item's `state` against the same build's catalogue rows, which is why it
+ * runs after every target-bearing catalogue (the quality-scores ordering
+ * constraint, for the same reason).
+ *
+ * The conditional-FK rule (a `declared` item's target must not resolve, a
+ * `realised` item's must) holds by construction: resolution is what computes
+ * `state`, so conforming output cannot disagree with it. An authored `state:`
+ * key is therefore a convention finding — the manifest has no business
+ * asserting a verdict the builder derives.
+ *
+ * Absent or empty `orchestration/scaffolds/` emits NOTHING and SAYS nothing:
+ * zero adoption is the designed state (M-ADR 0207 §4.4), not a coverage gap.
+ * This walker deliberately differs from the repo-config family, whose absent
+ * surface is a coverage finding.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+const SCAFFOLDS_DIR_REL = join("orchestration", "scaffolds");
+/**
+ * Top-level manifest shape. Loose (`passthrough`) so an unknown key is
+ * detectable rather than a rejection; per-item validation is manual because
+ * each defect must produce a finding naming file, item and value — a zod
+ * issue path would not.
+ */
+const ScaffoldManifestSchema = z
+    .object({
+    scaffold_schema: z.string(),
+    id: z.string(),
+    name: z.string(),
+    status: z.string(),
+    corpus_ref: z.string(),
+    items: z.array(z.unknown()).optional(),
+})
+    .passthrough();
+function enumValues(schema, enumName) {
+    const def = schema.enums[enumName];
+    return def ? def.values.map((v) => v.value) : [];
+}
+function catalogueByName(schema, name) {
+    return schema.catalogues.find((c) => c.name === name);
+}
+/**
+ * Resolve one declared item against the build's rows. Returns null when the
+ * declaration itself is defective (a finding has already been logged).
+ */
+function resolveItem(args) {
+    const { raw, relPath, index, schema, rowsByCatalogue, findings } = args;
+    const where = `${relPath} item ${index + 1}`;
+    const itemKind = typeof raw["kind"] === "string" ? raw["kind"] : "";
+    const validKinds = enumValues(schema, "scaffold_item_kind");
+    if (!validKinds.includes(itemKind)) {
+        findings.add("convention", `${where}: unknown item kind '${itemKind || "(missing)"}' — expected one of ${validKinds.join(" | ")}; item dropped`);
+        return null;
+    }
+    if ("state" in raw) {
+        findings.add("convention", `${where}: authored 'state' ignored — state is derived by the resolution pass, never authored (M-ADR 0207 §4.1)`);
+    }
+    // contract items default target_kind to `contracts` and must not name
+    // anything else — the spec-path vocabulary belongs to that one catalogue.
+    const targetKind = typeof raw["target_kind"] === "string" && raw["target_kind"] !== ""
+        ? raw["target_kind"]
+        : itemKind === "contract"
+            ? "contracts"
+            : "";
+    if (itemKind === "contract" && targetKind !== "contracts") {
+        findings.add("convention", `${where}: contract items resolve against 'contracts' (spec_path vocabulary), not '${targetKind}'; item dropped`);
+        return null;
+    }
+    const targetCat = catalogueByName(schema, targetKind);
+    if (!targetCat) {
+        findings.add("convention", `${where}: unknown target_kind '${targetKind || "(missing)"}' — not a catalogue in schema ${schema.schemaVersion}; item dropped`);
+        return null;
+    }
+    const rows = rowsByCatalogue.get(targetKind) ?? [];
+    if (itemKind === "edge") {
+        const sourceRef = typeof raw["edge_source_ref"] === "string" ? raw["edge_source_ref"] : "";
+        const targetRefEnd = typeof raw["edge_target_ref"] === "string" ? raw["edge_target_ref"] : "";
+        if (sourceRef === "" || targetRefEnd === "") {
+            findings.add("convention", `${where}: edge items declare edge_source_ref and edge_target_ref; item dropped`);
+            return null;
+        }
+        const [srcFk, dstFk] = [targetCat.foreignKeys[0], targetCat.foreignKeys[1]];
+        if (!srcFk || !dstFk) {
+            findings.add("convention", `${where}: '${targetKind}' declares ${targetCat.foreignKeys.length} FK column(s) — endpoint mapping needs two (schema declaration order); item dropped`);
+            return null;
+        }
+        const [srcCol, dstCol] = [srcFk.column, dstFk.column];
+        const realised = rows.some((r) => r[srcCol] === sourceRef && r[dstCol] === targetRefEnd);
+        return {
+            itemKind,
+            targetKind,
+            targetRef: `${sourceRef}__${targetRefEnd}`,
+            edgeSourceRef: sourceRef,
+            edgeTargetRef: targetRefEnd,
+            realised,
+        };
+    }
+    const targetRef = typeof raw["target_ref"] === "string" ? raw["target_ref"] : "";
+    if (targetRef === "") {
+        findings.add("convention", `${where}: missing target_ref; item dropped`);
+        return null;
+    }
+    const matchCol = itemKind === "contract" ? "spec_path" : targetCat.primaryKey;
+    const realised = rows.some((r) => r[matchCol] === targetRef);
+    return { itemKind, targetKind, targetRef, edgeSourceRef: null, edgeTargetRef: null, realised };
+}
+export async function buildScaffolds(inputs) {
+    const { sddPath, findings, sddId, schema, rowsByCatalogue } = inputs;
+    const dir = join(sddPath, SCAFFOLDS_DIR_REL);
+    let files;
+    try {
+        files = (await readdir(dir)).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            // Zero adoption is the designed state — headers-only, no finding.
+            return { scaffolds: [], scaffoldItems: [] };
+        }
+        throw err;
+    }
+    files.sort();
+    const validStatuses = enumValues(schema, "scaffold_status");
+    const scaffolds = [];
+    const scaffoldItems = [];
+    for (const file of files) {
+        const relPath = `${SCAFFOLDS_DIR_REL}/${file}`;
+        let parsed;
+        try {
+            parsed = parseYaml(await readFile(join(dir, file), "utf8"));
+        }
+        catch (err) {
+            findings.add("convention", `${relPath}: YAML parse failure (${err.message}); manifest dropped`);
+            continue;
+        }
+        const result = ScaffoldManifestSchema.safeParse(parsed);
+        if (!result.success) {
+            for (const issue of result.error.issues) {
+                findings.add("convention", `${relPath}: ${issue.path.join(".") || "(root)"}: ${issue.message}; manifest dropped`);
+            }
+            continue;
+        }
+        const manifest = result.data;
+        if (!validStatuses.includes(manifest.status)) {
+            findings.add("convention", `${relPath}: status '${manifest.status}' not in scaffold_status (${validStatuses.join(" | ")}); manifest dropped`);
+            continue;
+        }
+        scaffolds.push({
+            id: manifest.id,
+            name: manifest.name,
+            status: manifest.status,
+            source_path: relPath,
+            corpus_ref: manifest.corpus_ref,
+            manifest_schema: manifest.scaffold_schema,
+            sdd_id: sddId,
+            source_sdd_id: "",
+        });
+        const rawItems = manifest.items ?? [];
+        rawItems.forEach((rawItem, index) => {
+            if (typeof rawItem !== "object" || rawItem === null || Array.isArray(rawItem)) {
+                findings.add("convention", `${relPath} item ${index + 1}: not a mapping; item dropped`);
+                return;
+            }
+            const resolved = resolveItem({
+                raw: rawItem,
+                relPath,
+                index,
+                schema,
+                rowsByCatalogue,
+                findings,
+            });
+            if (!resolved)
+                return;
+            scaffoldItems.push({
+                id: `${manifest.id}__${resolved.itemKind}__${resolved.targetKind}__${resolved.targetRef}`,
+                scaffold_id: manifest.id,
+                item_kind: resolved.itemKind,
+                target_kind: resolved.targetKind,
+                target_ref: resolved.targetRef,
+                edge_source_ref: resolved.edgeSourceRef ?? "",
+                edge_target_ref: resolved.edgeTargetRef ?? "",
+                state: resolved.realised ? "realised" : "declared",
+                source_sdd_id: "",
+            });
+        });
+    }
+    return { scaffolds, scaffoldItems };
+}
+//# sourceMappingURL=scaffolds.js.map