@sdd-method/author-cli 0.10.0 → 0.12.0

package/dist/lib/catalogue/builders/entities-mermaid.js

@@ -14,20 +14,19 @@
 // - Files may mix `erDiagram` with other Mermaid diagram types (flowchart,
 //   sequenceDiagram). Each fenced block is independently checked for the
 //   erDiagram opener; non-ER blocks are skipped.
+// The file is read by the data-model parser (data-model.ts, schema 6.0.0), the
+// one parser every reader of a domain model shares; an entity on one line
+// (`NAME { type a; type b }`) is an entity too, and a `data-model.tql` in the
+// documented TypeQL subset gives its entities the same way.
 import { readFile } from "node:fs/promises";
+import { parseMermaidDataModel, parseTypeqlDataModel } from "./data-model.js";
 import { entitySlug } from "./entity-slug.js";
 import { extractFileEvidenceClass } from "./evidence-class.js";
-const RE_MERMAID_OPEN = /^```\s*mermaid\s*$/i;
-const RE_FENCE_CLOSE = /^```\s*$/;
-const RE_COMMENT = /^\s*%%/;
-const RE_ENTITY_OPEN = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\{\s*$/;
-const RE_REL_LINE = /^\s*[A-Za-z_][A-Za-z0-9_]*\s+\|?\|?[o|\-]+\{?\s+[A-Za-z]/;
-const MERMAID_KEYWORDS = new Set(["erdiagram", "subgraph", "classdef", "style", "class"]);
 export async function buildEntitiesFromMermaid(inputs) {
     const rows = [];
     const seenAcrossFiles = new Map(); // id → originating doc_path
     for (const dm of inputs.domainModels) {
-        if (!dm.doc_path.endsWith(".mermaid.md"))
+        if (!dm.doc_path.endsWith(".mermaid.md") && !dm.doc_path.endsWith(".tql"))
             continue;
         const docPath = dm.doc_path.startsWith("/")
             ? dm.doc_path
@@ -74,87 +73,21 @@ export async function buildEntitiesFromMermaid(inputs) {
     return rows;
 }
 function parseFile(text, dm, findings) {
-    const lines = text.split(/\r?\n/);
-    const out = [];
-    const seenInFile = new Set();
-    let inMermaid = false;
-    let isEr = false;
-    let firstKeywordSeen = false;
-    let inEntity = false;
-    let entityName = null;
-    let entityColumns = 0;
-    for (let i = 0; i < lines.length; i++) {
-        const raw = lines[i] ?? "";
-        if (!inMermaid) {
-            if (RE_MERMAID_OPEN.test(raw)) {
-                inMermaid = true;
-                isEr = false;
-                firstKeywordSeen = false;
-            }
-            continue;
-        }
-        // in_mermaid == true
-        if (RE_FENCE_CLOSE.test(raw)) {
-            inMermaid = false;
-            isEr = false;
-            firstKeywordSeen = false;
-            // If we exit mid-entity, drop it silently — malformed block.
-            inEntity = false;
-            entityName = null;
-            continue;
-        }
-        const stripped = raw.trim();
-        if (!firstKeywordSeen && stripped !== "" && !RE_COMMENT.test(raw)) {
-            firstKeywordSeen = true;
-            isEr = stripped.toLowerCase().startsWith("erdiagram");
-        }
-        if (!isEr)
-            continue;
-        if (inEntity) {
-            if (stripped.startsWith("}")) {
-                if (entityName !== null) {
-                    const slug = entitySlug(entityName);
-                    if (!seenInFile.has(slug)) {
-                        seenInFile.add(slug);
-                        out.push({
-                            name: entityName,
-                            domainId: dm.domain_id,
-                            sourceDomainModelId: dm.id,
-                            columnCount: entityColumns,
-                        });
-                    }
-                }
-                inEntity = false;
-                entityName = null;
-                entityColumns = 0;
-                continue;
-            }
-            if (RE_COMMENT.test(raw))
-                continue;
-            if (stripped)
-                entityColumns++;
-            continue;
-        }
-        // Not in an entity block — look for an opener.
-        if (RE_COMMENT.test(raw))
-            continue;
-        if (RE_REL_LINE.test(raw))
-            continue;
-        const m = RE_ENTITY_OPEN.exec(raw);
-        if (m) {
-            const ident = m[1] ?? "";
-            if (MERMAID_KEYWORDS.has(ident.toLowerCase()))
-                continue;
-            entityName = ident;
-            inEntity = true;
-            entityColumns = 0;
-        }
+    const parsed = dm.doc_path.endsWith(".tql") ? parseTypeqlDataModel(text, dm.doc_path) : parseMermaidDataModel(text, dm.doc_path);
+    if ("refused" in parsed) {
+        findings.add("extraction", `entities: ${dm.doc_path} is outside the documented TypeQL subset, so none of its entities is catalogued: ${parsed.refused}`, "warn", dm.doc_path);
+        return [];
     }
     // Defensive: if a block ended without closing an entity, log it once.
-    if (inEntity && entityName !== null) {
-        findings.add("convention", `entities-mermaid: ${dm.doc_path}: unclosed entity block for "${entityName}" — discarded`);
+    if (parsed.unclosed !== null) {
+        findings.add("convention", `entities-mermaid: ${dm.doc_path}: unclosed entity block for "${parsed.unclosed}" — discarded`);
     }
-    return out;
+    return parsed.entities.map((e) => ({
+        name: e.name,
+        domainId: dm.domain_id,
+        sourceDomainModelId: dm.id,
+        columnCount: e.columnCount,
+    }));
 }
 function resolveGlossaryTermBySlug(entityName, domainId, knownGlossaryIds) {
     const slug = entitySlug(entityName);

package/dist/lib/catalogue/builders/feature-grounding.js

@@ -153,6 +153,7 @@ export async function buildFeatureGrounding(inputs) {
                     status: "active",
                     source: "feature-grounding",
                     runway: "",
+                    kind: "feature",
                     source_sdd_id: "",
                 });
                 const cfId = `${capabilityId}__${featureId}`;

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

@@ -89,9 +89,10 @@ export async function buildFeatures(inputs) {
             parent_feature_id: "",
             description,
             maturity: "",
-            status: "active",
+            status: featureStatus(text),
             source: "feature-spec",
             runway: "",
+            kind: featureKind(text),
             source_sdd_id: "",
         });
         idByPath.set(relPath, id);
@@ -123,9 +124,10 @@ export async function buildFeatures(inputs) {
                 parent_feature_id: "",
                 description,
                 maturity: "",
-                status: "active",
+                status: featureStatus(text),
                 source: "feature-spec",
                 runway: "",
+                kind: featureKind(text),
                 source_sdd_id: "",
             });
             idByPath.set(relPath, id);
@@ -145,6 +147,24 @@ export async function buildFeatures(inputs) {
     }
     return { rows, idByPath, idBySlug };
 }
+/**
+ * A feature spec's catalogue status: `retired` when the spec says `**Status:** retired` (its behaviour retired by
+ * an archived change, the feature kept in the catalogue so its retired requirements still resolve), else
+ * `active`. A retired feature stays where it is; it does not have to move to withdrawn/ first.
+ */
+export function featureStatus(text) {
+    const m = /^\*\*Status:\*\*\s*([A-Za-z-]+)/m.exec(text) ?? /^>.*\bStatus:\s*([A-Za-z-]+)/m.exec(text);
+    return m?.[1]?.toLowerCase() === "retired" ? "retired" : "active";
+}
+/**
+ * A feature spec's kind (schema 4.4.0): the value of its `**Kind:**` line, lower-cased, else `feature`. An
+ * obligation (M-ADR 0226, Proposed) and a journey feature (M-ADR 0229 §4.2, Proposed) say so; any other value is written as given, so
+ * the catalogue's vocabulary gate names the spec rather than a default hiding the mistake.
+ */
+export function featureKind(text) {
+    const m = /^\*\*Kind:\*\*\s*([A-Za-z-]+)/m.exec(text);
+    return m?.[1]?.toLowerCase() ?? "feature";
+}
 async function emitBulletRows(ctx) {
     const featureTreePath = await findFeatureTreeFile(ctx.sddPath);
     if (!featureTreePath)
@@ -188,6 +208,7 @@ async function emitBulletRows(ctx) {
             status: "active",
             source: "feature-tree",
             runway: ev.runway,
+            kind: "feature",
             source_sdd_id: "",
         });
         if (!ctx.idBySlug.has(ev.slug))

package/dist/lib/catalogue/builders/integration-components.js

@@ -176,9 +176,8 @@ export async function buildIntegrationComponents(inputs) {
     }
     // SECOND HOME (§9.1): a full `integration-manifest.yaml` per component repo under
     // `repos/<component>/`. Read after the array form so `seen` already holds the
-    // array-form ids and a collision across the two homes is caught rather than
-    // silently duplicated — measured disjoint today, but the two forms are authored
-    // independently and nothing stops them meeting.
+    // array-form ids: a component in both homes that agrees on every tier field is
+    // one declaration stated twice, and one that disagrees is a divergence (below).
     rows.push(...(await readComponentManifests({
         sddPath: inputs.sddPath,
         findings: inputs.findings,
@@ -186,6 +185,7 @@ export async function buildIntegrationComponents(inputs) {
         knownRepoIds: inputs.knownRepoIds,
         knownServiceIds: inputs.knownServiceIds,
         seen,
+        arrayRows: new Map(rows.map((r) => [String(r["id"]), r])),
     })));
     checkAggregate({
         findings: inputs.findings,
@@ -196,6 +196,43 @@ export async function buildIntegrationComponents(inputs) {
     });
     return rows;
 }
+/** The fields the component tier reads, compared when a component is declared in both homes. */
+const TIER_FIELDS = [
+    "component_type",
+    "direction",
+    "frequency",
+    "transport",
+    "format",
+    "auth",
+    "ingestion_pattern",
+    "invocation_pattern",
+    "pattern_qualifier",
+    "primary_entities",
+];
+function tierValue(m, f) {
+    switch (f) {
+        case "component_type":
+            return (m.componentType ?? "").trim();
+        case "direction":
+            return (m.dataFlow?.direction ?? "").trim();
+        case "frequency":
+            return (m.dataFlow?.frequency ?? "").trim();
+        case "transport":
+            return (m.protocol?.transport ?? "").trim();
+        case "format":
+            return (m.protocol?.format ?? "").trim();
+        case "auth":
+            return (m.protocol?.auth ?? "").trim();
+        case "ingestion_pattern":
+            return (m.ingestionPattern ?? "").trim();
+        case "invocation_pattern":
+            return (m.invocationPattern ?? "").trim();
+        case "pattern_qualifier":
+            return (m.patternQualifier ?? "").trim();
+        case "primary_entities":
+            return (m.dataFlow?.primaryEntities ?? []).join(";");
+    }
+}
 /** `repos/` — where the per-component manifests live (M-ADR 0171 §9.1, second home). */
 const REPOS_DIR = "repos";
 /**
@@ -261,8 +298,15 @@ async function readComponentManifests(args) {
         const componentId = (parsed.data.integrationId ?? "").trim() || dir;
         const id = `${args.integrationId}__${componentId}`;
         if (args.seen.has(id)) {
-            args.findings.add("divergence", `integration_component: component id="${id}" declared in BOTH §9.1 homes (components array and ${rel}) — ` +
-                `one component cannot be declared twice; the per-component manifest is dropped. Remove whichever declaration is stale.`);
+            // The reverse template has the array mirror the per-component manifests, so a component in both homes is
+            // expected. A mirror that agrees on every field the tier reads is one declaration stated twice, and is not a
+            // finding; one that disagrees is, and the array's declaration is kept.
+            const mirrored = args.arrayRows.get(id);
+            const differs = mirrored === undefined ? ["(not an array row)"] : TIER_FIELDS.filter((f) => String(mirrored[f] ?? "") !== tierValue(parsed.data, f));
+            if (differs.length > 0) {
+                args.findings.add("divergence", `integration_component: component id="${id}" is declared in both §9.1 homes (components array and ${rel}) and they disagree on ${differs.join(", ")}; ` +
+                    `the components array's declaration is kept. Correct whichever is stale.`);
+            }
             continue;
         }
         args.seen.add(id);

package/dist/lib/catalogue/builders/journey-requirement.js

@@ -0,0 +1,144 @@
+// journey_requirement: the requirements a user journey cites for its steps (M-ADR 0229 §4.4, Proposed; schema 4.4.0).
+//
+// Derived, never authored, from either master (§4.2):
+//   tag       option A: the end-to-end `.feature` files under the manifest's `journeys.test_paths`. A file tagged
+//             `@journey:<journey-id>` cites every `@req:<feature-id>/<requirement-slug>` tag it carries.
+//   citation  option B: the living spec (openspec/specs/<feature-id>/spec.md) of a feature of kind journey names its
+//             journey with the same `@journey:<journey-id>` tag and cites each step's requirement with `@req:`.
+// One tag grammar for both, so the derivation needs only the files and the catalogue's rows. Both are read whenever
+// present, so an estate moving from A to B shows both while it moves.
+//
+// A requirement tag cannot carry spaces, so it names the requirement by slug: its name lower-cased, each run of
+// anything but a-z and 0-9 turned into one hyphen. A tag resolves when exactly one requirement of that feature,
+// living or agreed (not retired), has that slug; a tag naming a retired requirement names none, so it is a finding. A tag that resolves to none or to several, a file with two journey tags, or a test
+// path that does not exist is a finding and produces no row, so no foreign key dangles. A tag naming a feature or a
+// journey this catalogue does not hold is reported as external: journeys are often catalogued in application SDDs
+// and requirements in the platform's store, so the row is derived at aggregation, where both are merged
+// (catalogue aggregate re-runs this builder over each contributor). A journey with no row is untraced, which the
+// journey-impact check reports.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+const REQ_TAG = /@req:([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)/g;
+const JOURNEY_TAG = /@journey:([a-z0-9][a-z0-9-]*)/g;
+/** "Order shipped (REST)" -> "order-shipped-rest". */
+export function requirementSlug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+async function featureFiles(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (e.name === "node_modules" || e.name.startsWith("."))
+            continue;
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...(await featureFiles(p)));
+        else if (e.isFile() && e.name.endsWith(".feature"))
+            out.push(p);
+    }
+    return out.sort();
+}
+export async function buildJourneyRequirement(inputs) {
+    // At aggregation the member builds have already reported every finding about their own files and features.
+    const atAggregate = inputs.reportedFeatureIds !== undefined;
+    const { sddPath, findings } = inputs;
+    const bySlug = new Map();
+    for (const r of inputs.requirements) {
+        if (String(r["stage"] ?? "") === "retired")
+            continue; // a journey step cannot rely on behaviour that has been removed
+        const key = `${String(r["feature_id"])}/${requirementSlug(String(r["name"]))}`;
+        const ids = bySlug.get(key) ?? [];
+        if (!ids.includes(String(r["id"])))
+            ids.push(String(r["id"]));
+        bySlug.set(key, ids);
+    }
+    const rows = new Map();
+    const knownFeatures = new Set(inputs.features.map((f) => String(f["id"])));
+    const cite = (journeyId, text, where, basis) => {
+        for (const m of text.matchAll(REQ_TAG)) {
+            const quiet = atAggregate && inputs.reportedFeatureIds.has(m[1]);
+            if (!knownFeatures.has(m[1])) {
+                findings.add("external", `${where}: @req:${m[1]}/${m[2]} names a feature this catalogue does not hold; resolves at aggregation (M-ADR 0229 §4.4, Proposed)`);
+                continue;
+            }
+            const ids = bySlug.get(`${m[1]}/${m[2]}`) ?? [];
+            if (ids.length !== 1) {
+                if (!quiet)
+                    findings.add("orphan", `${where}: @req:${m[1]}/${m[2]} ${ids.length === 0 ? "names no requirement of that feature" : `matches ${ids.length} requirements of that feature`}; no journey_requirement row (M-ADR 0229 §4.4, Proposed)`);
+                continue;
+            }
+            const id = `${journeyId}__${ids[0]}`;
+            if (!rows.has(id))
+                rows.set(id, { id, journey_id: journeyId, requirement_id: ids[0], basis, source_sdd_id: "", platform_sdd_id: "" });
+        }
+    };
+    // Option A: tagged end-to-end files.
+    for (const rel of inputs.testPaths) {
+        const dir = join(sddPath, rel);
+        const exists = await stat(dir).then((s) => s.isDirectory(), () => false);
+        if (!exists) {
+            if (!atAggregate)
+                findings.add("orphan", `.sdd/sdd-manifest.yaml: journeys.test_paths names ${rel}, which is not a directory in this SDD`);
+            continue;
+        }
+        for (const file of await featureFiles(dir)) {
+            const where = relative(sddPath, file);
+            const text = await readFile(file, "utf8");
+            const journeys = [...new Set([...text.matchAll(JOURNEY_TAG)].map((m) => m[1]))];
+            if (journeys.length === 0)
+                continue;
+            if (journeys.length > 1) {
+                if (!atAggregate)
+                    findings.add("divergence", `${where}: tagged with ${journeys.length} journeys (${journeys.join(", ")}); one file is one journey's master (M-ADR 0229 §4.2, Proposed)`);
+                continue;
+            }
+            const journeyId = journeys[0];
+            if (!inputs.knownJourneyIds.has(journeyId)) {
+                findings.add("external", `${where}: @journey:${journeyId} is not a user journey this catalogue holds; resolves at aggregation`);
+                continue;
+            }
+            cite(journeyId, text, where, "tag");
+        }
+    }
+    // Option B: journey features in the store, each naming its journey in its living spec.
+    const kindById = new Map(inputs.features.map((f) => [String(f["id"]), String(f["kind"] ?? "")]));
+    let specDirs = [];
+    try {
+        specDirs = (await readdir(join(sddPath, "openspec", "specs"), { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        // no store here
+    }
+    for (const featureId of specDirs) {
+        if (kindById.get(featureId) !== "journey")
+            continue;
+        const where = join("openspec", "specs", featureId, "spec.md");
+        let spec;
+        try {
+            spec = await readFile(join(sddPath, where), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const journeys = [...new Set([...spec.matchAll(JOURNEY_TAG)].map((m) => m[1]))];
+        if (journeys.length !== 1) {
+            if (!atAggregate)
+                findings.add(journeys.length === 0 ? "orphan" : "divergence", `${where}: a journey feature's living spec ${journeys.length === 0 ? "names no journey (@journey:<journey-id>)" : `names ${journeys.length} journeys`}; one journey feature masters one journey (M-ADR 0229 §4.2, Proposed)`);
+            continue;
+        }
+        const journeyId = journeys[0];
+        if (!inputs.knownJourneyIds.has(journeyId)) {
+            findings.add("external", `${where}: @journey:${journeyId} is not a user journey this catalogue holds; resolves at aggregation`);
+            continue;
+        }
+        cite(journeyId, spec, where, "citation");
+    }
+    return [...rows.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+}
+//# sourceMappingURL=journey-requirement.js.map

package/dist/lib/catalogue/builders/quality-scores.js

@@ -118,6 +118,19 @@ const num = (v) => {
     }
     return null;
 };
+/**
+ * The review's other assessed inputs (M-ADR 0230 §4.9, Proposed): `inputs:` as a list of paths, or of `{path}`
+ * entries, each read at the review's corpus_ref. ';'-joined; null when the review names none.
+ */
+function inputPaths(v) {
+    if (!Array.isArray(v))
+        return null;
+    const paths = v
+        .map((x) => (typeof x === "string" ? x : isRecord(x) && typeof x["path"] === "string" ? x["path"] : ""))
+        .map((x) => x.trim())
+        .filter((x) => x !== "");
+    return paths.length > 0 ? paths.join(";") : null;
+}
 /**
  * Count raised flags across the two authored dialects:
  *   `flags: { over_scope_risk: true, ... }`  -> count the true ones
@@ -258,6 +271,7 @@ function bandedRows(block, ctx) {
         band_total: num(block["total"]),
         scored_at: ctx.scoredAt,
         corpus_ref: ctx.corpusRef,
+        input_paths: ctx.inputPaths,
         staleness_basis: stalenessBasis,
         review_run_id: null,
         selection_method: null,
@@ -371,6 +385,7 @@ export async function buildQualityScores(inputs) {
                             targetPath,
                             scoredAt: fileScoredAt,
                             corpusRef,
+                            inputPaths: inputPaths(unitVal["inputs"]),
                             assessedBy: fileAssessedBy,
                             sddId,
                         });
@@ -396,6 +411,7 @@ export async function buildQualityScores(inputs) {
                         targetPath: str(unitVal["doc_path"]),
                         scoredAt: str(current["scored_at"]) ?? fileScoredAt,
                         corpusRef,
+                        inputPaths: inputPaths(current["inputs"] ?? unitVal["inputs"]),
                         assessedBy: fileAssessedBy,
                         sddId,
                     });
@@ -540,6 +556,7 @@ export async function buildQualityScores(inputs) {
                 band_total: null,
                 scored_at: str(current["scored_at"]) ?? str(entryVal["scored_at"]),
                 corpus_ref: corpusRef,
+                input_paths: inputPaths(current["inputs"] ?? entryVal["inputs"]),
                 staleness_basis: stalenessBasis,
                 review_run_id: str(current["review_run_id"]),
                 selection_method: selectionMethod,