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

package/dist/lib/catalogue/builders/screen-tree.js

@@ -0,0 +1,222 @@
+// Screen composition-tree analysis for openui-lang blocks (per ADR 0168).
+//
+// The screens builder (screens.ts) lowers a ```openui-lang block into catalogue
+// rows by flat token-scanning. ADR 0168 adds a *fidelity floor*: the block must
+// be a faithful tree, not a flat / empty / mis-rooted "widget bag". That needs
+// the structural shape the flat scan throws away — so this module parses the
+// block into a tree and computes the metrics the depth findings reason about.
+//
+// Pure functions, no I/O. The metrics reason about TREE SHAPE only — never about
+// any component vocabulary (adopter-agnostic by construction, ADR 0168 §4.5).
+//
+// Grammar recap (ADR 0166 / openui-lang-grammar-reference.md): one
+// `identifier = Expression` statement per line; the first statement is `root`;
+// composition is by identifier reference inside list literals. A component is a
+// Capitalised call head (`Name(`); local references are lowercase ids that are
+// themselves defined as statements.
+/** First Capitalised call head in an expression (the component invoked). */
+const CALL_HEAD_RE = /\b([A-Z][A-Za-z0-9]*)\s*\(/;
+/** All Capitalised call heads (for componentCount). */
+const CALL_HEAD_RE_G = /\b([A-Z][A-Za-z0-9]*)\s*\(/g;
+/**
+ * All *lowercase* call heads — `name(` where `name` starts lowercase. These are
+ * malformed: the grammar invokes a component only via a Capitalised head, and a
+ * lowercase identifier is a pure reference that never takes arguments. Such a
+ * token is silently uncounted by componentCount, so it composes child-less in
+ * the tree and the catalogue — caught here as a convention finding.
+ */
+const LOWER_CALL_HEAD_RE_G = /\b([a-z][A-Za-z0-9_-]*)\s*\(/g;
+/** `identifier = Expression`, one per line. */
+const STATEMENT_RE = /^\s*([A-Za-z_][\w-]*)\s*=\s*(.+?)\s*$/;
+/** Quoted string literals (single or double) — masked before call-head / ref detection. */
+const STRING_RE = /"[^"]*"|'[^']*'/g;
+/**
+ * Mask string-literal interiors with spaces of equal length (offset- and
+ * line-structure-preserving) so call-head lexing can never fire on quoted
+ * content — `Table("Odometer (km)")` must not mint a phantom `Odometer`
+ * component, and `"total (sum)"` must not false-fire the lowercase-call-head
+ * finding (tomfosteruk/sdd-cli#1). Quote characters are kept; newlines inside
+ * a span survive. The grammar defines no escape sequences (a quote always
+ * closes the literal), matching STRING_RE and stripLineComment.
+ *
+ * Scope: call-head / identifier-reference scanning ONLY. Positional-arg and
+ * `action=` extraction read string contents, so they must always run on the
+ * real (unmasked) text.
+ */
+export function maskStringLiterals(text) {
+    return text.replace(STRING_RE, (lit) => lit[0] + lit.slice(1, -1).replace(/[^\r\n]/g, " ") + lit[lit.length - 1]);
+}
+/** Any identifier token. */
+const IDENT_RE = /\b([A-Za-z_][\w-]*)\b/g;
+/** `action="..."` attribute values on a statement (node-scoped CTA/messaging contract). */
+const ACTION_ATTR_RE_G = /\baction\s*=\s*"([^"]*)"/g;
+/** Any `key="..."` / `key='...'` named attribute — removed so its value isn't read as a positional arg. */
+const NAMED_ATTR_RE_G = /\b[\w-]+\s*=\s*("[^"]*"|'[^']*')/g;
+/**
+ * Split a call's RHS into its positional string args and its `action=` values.
+ * Render-only metadata (the deterministic wireframe renderer reads it to label
+ * nodes) — never feeds catalogue rows or the depth metrics. A `key="..."` named
+ * attribute's value is NOT a positional arg, so named attrs are removed first.
+ */
+function parseArgsActions(rhs) {
+    const actions = [];
+    for (const m of rhs.matchAll(ACTION_ATTR_RE_G))
+        actions.push(m[1]);
+    const positional = rhs.replace(NAMED_ATTR_RE_G, "");
+    const args = [];
+    for (const m of positional.matchAll(STRING_RE)) {
+        const inner = m[0].slice(1, -1);
+        if (inner.length > 0)
+            args.push(inner);
+    }
+    return { args, actions };
+}
+/**
+ * Strip openui-lang inline comments: from the first *unquoted* `#` to
+ * end-of-line, per line (ADR 0168 §4.4, defect g). A `Capitalised(` token inside
+ * a comment must not be lexed as a component. `#` inside a string literal is
+ * preserved.
+ */
+export function stripBlockComments(block) {
+    return block
+        .split(/\r?\n/)
+        .map(stripLineComment)
+        .join("\n");
+}
+function stripLineComment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (quote) {
+            if (c === quote)
+                quote = null;
+        }
+        else if (c === '"' || c === "'") {
+            quote = c;
+        }
+        else if (c === "#") {
+            return line.slice(0, i);
+        }
+    }
+    return line;
+}
+// Parse a (comment-stripped) block into statements with resolved child
+// references. Shared by analyzeComposition (metrics) and buildCompositionTree.
+function parseStatements(cleanBlock) {
+    const statements = new Map();
+    const order = [];
+    for (const raw of cleanBlock.split(/\r?\n/)) {
+        const m = STATEMENT_RE.exec(raw);
+        if (!m)
+            continue;
+        const id = m[1];
+        const rhs = m[2];
+        // A component statement's RHS is a call (`Text("Q4")`) or a reference — never a
+        // bare string literal. A line like `action="user-details-changed"` (the block-level
+        // screen_action messaging contract, ADR 0166) matches the statement shape with
+        // id=`action`; skip it so it isn't lexed as a phantom component (and so a node
+        // carrying an `action=` attr doesn't pick it up as a spurious child).
+        if (/^["']/.test(rhs))
+            continue;
+        if (!statements.has(id))
+            order.push(id);
+        // Last assignment wins (re-declaration is unusual; keep it deterministic).
+        // Head detection runs on the string-masked rhs so a `Capitalised(` inside a
+        // quoted arg can't be read as the call head; args/actions read the real rhs.
+        const { args, actions } = parseArgsActions(rhs);
+        statements.set(id, { id, rhs, head: CALL_HEAD_RE.exec(maskStringLiterals(rhs))?.[1] ?? "", args, actions, childIds: [] });
+    }
+    const definedIds = new Set(statements.keys());
+    // Resolve child references: a defined id (other than self) appearing in the
+    // expression, after masking string literals so quoted text can't match
+    // (masking, not stripping, so removal can't splice adjacent tokens together).
+    for (const st of statements.values()) {
+        const noStrings = maskStringLiterals(st.rhs);
+        const refs = new Set();
+        for (const tok of noStrings.matchAll(IDENT_RE)) {
+            const name = tok[1];
+            if (name !== st.id && definedIds.has(name))
+                refs.add(name);
+        }
+        st.childIds = [...refs];
+    }
+    return { statements, order };
+}
+/**
+ * Build the composition tree from a (comment-stripped) block, rooted at the
+ * first statement. Cycle-safe (a back-edge becomes a childless leaf). Returns
+ * null when the block declares no statements.
+ */
+export function buildCompositionTree(cleanBlock) {
+    const { statements, order } = parseStatements(cleanBlock);
+    const rootId = order[0];
+    if (rootId === undefined)
+        return null;
+    const build = (id, seen) => {
+        const st = statements.get(id);
+        if (st === undefined)
+            return { id, component: "", args: [], actions: [], children: [] }; // undefined ref → leaf
+        if (seen.has(id))
+            return { id, component: st.head, args: st.args, actions: st.actions, children: [] }; // cycle guard
+        const next = new Set(seen).add(id);
+        return { id, component: st.head, args: st.args, actions: st.actions, children: st.childIds.map((c) => build(c, next)) };
+    };
+    return build(rootId, new Set());
+}
+/**
+ * Parse a (comment-stripped) openui-lang block into a composition tree and
+ * compute its structural metrics. Cycle-safe.
+ */
+export function analyzeComposition(cleanBlock) {
+    const { statements, order } = parseStatements(cleanBlock);
+    const containers = new Set();
+    for (const st of statements.values()) {
+        if (st.head && st.childIds.length > 0)
+            containers.add(st.head);
+    }
+    // componentCount: distinct Capitalised call heads across the block (string
+    // literals masked so a `Foo(` inside a quoted label is not counted — #1).
+    // lowercaseCallHeads: distinct lowercase call heads (malformed invocations)
+    // over the same masked block, so `"total (sum)"` can't false-fire either.
+    const noStrings = maskStringLiterals(cleanBlock);
+    const heads = new Set();
+    for (const tok of noStrings.matchAll(CALL_HEAD_RE_G)) {
+        heads.add(tok[1]);
+    }
+    const componentCount = heads.size;
+    const lowerHeads = new Set();
+    for (const tok of noStrings.matchAll(LOWER_CALL_HEAD_RE_G)) {
+        lowerHeads.add(tok[1]);
+    }
+    const lowercaseCallHeads = [...lowerHeads].sort();
+    const rootId = order[0];
+    if (rootId === undefined) {
+        return { maxDepth: 0, maxBreadth: 0, rootChildCount: 0, componentCount, rootComponent: "", containers, lowercaseCallHeads };
+    }
+    const rootStmt = statements.get(rootId);
+    let maxDepth = 0;
+    let maxBreadth = 0;
+    const walk = (id, depth, seen) => {
+        const st = statements.get(id);
+        maxDepth = Math.max(maxDepth, depth);
+        if (st === undefined)
+            return; // reference to an undefined id → leaf
+        maxBreadth = Math.max(maxBreadth, st.childIds.length);
+        if (seen.has(id))
+            return; // cycle guard
+        const next = new Set(seen).add(id);
+        for (const child of st.childIds)
+            walk(child, depth + 1, next);
+    };
+    walk(rootId, 0, new Set());
+    return {
+        maxDepth,
+        maxBreadth,
+        rootChildCount: rootStmt.childIds.length,
+        componentCount,
+        rootComponent: rootStmt.head,
+        containers,
+        lowercaseCallHeads,
+    };
+}
+//# sourceMappingURL=screen-tree.js.map

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

@@ -0,0 +1,396 @@
+// Screens builder — emits the UI screens catalogue family (per ADR 0166):
+//   screens, ui_components, screen_component, screen_feature,
+//   persona_screen, screen_action.
+//
+// Source convention (per docs/method/methods/templates/screen-spec-template.md):
+//   screens/<slug>.md
+//   ---
+//   screen: <slug>            # optional; defaults to filename stem
+//   route: /path              # optional
+//   status: working           # optional (ADR 0165 maturity vocabulary)
+//   persona_access: [<persona-slug>, ...]   # -> persona_screen
+//   realises: [<feature-slug>, ...]         # -> screen_feature
+//   ---
+//   # Screen: {Name}
+//   ```openui-lang
+//   root    = Stack([header, refresh])
+//   header  = TextContent("Q4 Dashboard", "large-heavy")
+//   refresh = Button("Refresh", action="refresh-dashboard")
+//   ```
+//
+// The fenced ```openui-lang block is the normative structural core: component
+// invocations (Capitalised call heads) -> ui_components + screen_component;
+// `action="..."` declarations -> screen_action. The frontmatter supplies the
+// catalogue keys + FK lists. This is the forward / authored path; the reverse
+// toolkit projects an app's router + component tree into the same shape (the
+// upstream step that produces these artefacts — see
+// research/adr-0166-prototypes/ for the Phase Pre validation).
+//
+// Per ADR 0135 the rows are identical regardless of authoring direction; only
+// the `source` discriminator differs (screen-spec vs screen-extraction).
+//
+// Application-product profile. Like personas, the walker reads `screens/` at
+// the SDD root regardless of profile and emits empty when the directory is
+// absent (non-app profiles simply have none).
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { analyzeComposition, maskStringLiterals, stripBlockComments } from "./screen-tree.js";
+import { isContainerArchetype } from "../archetype/resolver.js";
+/** Method default for the flat-composition threshold (ADR 0168 §4.2). */
+const DEFAULT_FLAT_THRESHOLD = 6;
+/** The only maturity value that asserts a faithful, complete composition (ADR 0168 §4.3). */
+const COMPLETENESS_STATUS = "working";
+const SCREENS_DIR_REL = "screens";
+/** Subdir of screens/ holding rendered wireframe artifacts — never screen specs. */
+const WIREFRAMES_DIR = "wireframes";
+/** Reserved documentation files under screens/ that are not screen specs (e.g. a cross-reference index). */
+const isReservedDoc = (name) => /^(INDEX|README)\.md$/i.test(name);
+/**
+ * Collect screen-spec `*.md` files under `screens/`, recursively. Adopters with a
+ * single platform keep specs flat (`screens/<slug>.md`); multi-platform adopters
+ * may nest them (`screens/<platform>/<slug>.md`) — both are found. The screen id
+ * comes from frontmatter (`screen:`), not the path, so nesting is purely
+ * organisational. The `wireframes/` subtree (rendered SVGs) is skipped. Returns
+ * paths relative to `screens/`, sorted. Throws ENOENT if `screens/` is absent.
+ */
+async function collectScreenSpecFiles(dir) {
+    const out = [];
+    const walk = async (rel) => {
+        const entries = await readdir(rel ? join(dir, rel) : dir, { withFileTypes: true });
+        for (const e of entries) {
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (e.name === WIREFRAMES_DIR)
+                    continue;
+                await walk(r);
+            }
+            else if (e.isFile() && e.name.endsWith(".md") && !isTemplate(e.name) && !isReservedDoc(e.name)) {
+                out.push(r);
+            }
+        }
+    };
+    await walk("");
+    return out.sort();
+}
+// Recognised standard maturity vocabulary (ADR 0165); other values pass through.
+const STANDARD_MATURITY = new Set(["working", "provisional", "unknown", "absent"]);
+export async function buildScreens(inputs) {
+    const screens = [];
+    const uiById = new Map();
+    const screenComponent = new Map();
+    const screenFeature = new Map();
+    const personaScreen = new Map();
+    const screenAction = new Map();
+    const flatThreshold = inputs.flatThreshold ?? DEFAULT_FLAT_THRESHOLD;
+    const dir = join(inputs.sddPath, SCREENS_DIR_REL);
+    let files;
+    try {
+        files = await collectScreenSpecFiles(dir);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        inputs.findings.add("coverage", `${SCREENS_DIR_REL}/ not found — emitting empty screens family`);
+        return emptyResult();
+    }
+    for (const filename of files) {
+        const stem = basename(filename).replace(/\.md$/i, "");
+        const text = await readFile(join(dir, filename), "utf-8");
+        const fm = parseFrontmatter(text, inputs.findings, filename);
+        const slug = screenSlug(typeof fm.screen === "string" ? fm.screen : stem);
+        const screenId = `${inputs.productId}-${slug}`;
+        if (screens.some((s) => s["id"] === screenId)) {
+            inputs.findings.add("divergence", `screens: duplicate screen id ${screenId} (${filename}) — keeping first`);
+            continue;
+        }
+        const name = extractH1(text) || (typeof fm.name === "string" ? fm.name : stem);
+        const status = typeof fm.status === "string" && fm.status !== "" ? maturity(fm.status, inputs.findings, screenId) : "";
+        // Direction discriminator (ADR 0135): forward authoring is `screen-spec`,
+        // reverse extraction `screen-extraction`. Read from frontmatter, default
+        // forward; only these two are recognised (others pass through, flagged).
+        const source = screenSource(fm.source, inputs.findings, screenId);
+        screens.push({
+            id: screenId,
+            name,
+            product_id: inputs.productId,
+            route: typeof fm.route === "string" ? fm.route : "",
+            status,
+            source,
+            domain: typeof fm.domain === "string" ? fm.domain : "",
+            group: typeof fm.group === "string" ? fm.group : "",
+            context: typeof fm.context === "string" ? fm.context : "",
+            // Evidence class (M-ADR 0175, schema 2.42.0). Orthogonal to `source`
+            // above: `source` records the authoring DIRECTION, this records the
+            // claim's STRENGTH. A packaged-SaaS SDD carries the vendor's standard
+            // screens as `vendor-doc` (documentation-reversed from vendor
+            // publications) and its own customisations as `code-reverse`; a
+            // `screen-extraction` screen may be either class, since a documented
+            // vendor UI is extracted but not code-verified. The hyphen alias matches
+            // the events and data-model derivation sources.
+            evidence_class: evidenceClass(fm),
+            source_sdd_id: "",
+        });
+        // Evidence integrity (ADR 0168 §4.2, defect f): a reverse-extracted screen
+        // must cite its route + component evidence with a `[^…]` footnote. Forward-
+        // authored screens make no such claim, so the check is reverse-scoped.
+        if (source === "screen-extraction" && !/\[\^[^\]]+\]/.test(text)) {
+            inputs.findings.add("coverage", `screen ${screenId}: reverse-extracted but cites no evidence footnote (screen-evidence-missing)`);
+        }
+        const block = extractOpenUiLangBlock(text);
+        if (!block) {
+            inputs.findings.add("coverage", `screens: ${filename} has no \`\`\`openui-lang block — screen emitted, no components`);
+        }
+        else {
+            // Strip inline `#` comments before any scan so a `Capitalised(` token in a
+            // comment can't emit a phantom component (ADR 0168 §4.4, defect g).
+            const clean = stripBlockComments(block);
+            // Component invocations: Capitalised call heads (e.g. Stack(, StatCard().
+            // Local id references (lowercase, no parens) and list literals are skipped.
+            // String literals are masked first so a quoted label like "Odometer (km)"
+            // can't mint a phantom component (#1); the action= scan below reads the
+            // real (unmasked) block because it extracts string contents.
+            const componentNames = new Set(matchAll(maskStringLiterals(clean), /\b([A-Z][A-Za-z0-9]*)\s*\(/g));
+            for (const comp of componentNames) {
+                const cid = `${inputs.productId}-${screenSlug(comp)}`;
+                if (!uiById.has(cid)) {
+                    uiById.set(cid, {
+                        id: cid, name: comp, product_id: inputs.productId,
+                        kind: "", source, source_sdd_id: "",
+                    });
+                }
+                const scKey = `${screenId}__${cid}`;
+                if (!screenComponent.has(scKey)) {
+                    screenComponent.set(scKey, { id: scKey, screen_id: screenId, component_id: cid, source_sdd_id: "" });
+                }
+            }
+            // Action declarations: action="..." (single or double quoted).
+            for (const action of new Set(matchAll(clean, /\baction\s*=\s*["']([^"']+)["']/g))) {
+                const aKey = `${screenId}__${screenSlug(action)}`;
+                if (!screenAction.has(aKey)) {
+                    // event_id left empty: external-capable, resolved against the event
+                    // catalogue when an explicit mapping exists (best-effort per ADR 0166).
+                    screenAction.set(aKey, { id: aKey, screen_id: screenId, action, event_id: "", source_sdd_id: "" });
+                }
+            }
+            // Composition-depth validation (ADR 0168): structural fidelity floor +
+            // status gate + the archetype-aware root check (ADR 0169). The vocabulary-
+            // free checks reason about tree shape + status only; root-is-leaf consults
+            // the archetype map when the screen declares a `platform:`.
+            const platform = typeof fm.platform === "string" ? fm.platform : undefined;
+            const overlay = platform !== undefined ? inputs.archetypeOverlays?.get(platform) : undefined;
+            emitDepthFindings(inputs.findings, screenId, status, analyzeComposition(clean), {
+                flatThreshold,
+                platform,
+                overlay,
+                componentNames,
+                decorativePrimitives: inputs.decorativePrimitives,
+            });
+        }
+        // realises: -> screen_feature
+        for (const fref of toList(fm.realises)) {
+            const fid = inputs.featureIdBySlug.get(screenSlug(fref)) ?? inputs.featureIdByPath.get(fref);
+            if (!fid) {
+                // App/integration screens can realise a platform-resident feature
+                // (MFE-over-platform: the platform owns the capability tree and its
+                // features — ADR 0177 single-slug). Emit a deferred cross-SDD edge
+                // carrying the bare realises slug; the aggregator resolves it to the
+                // platform feature id, and the FK validator logs it `[finding] external`
+                // for this build (screen_feature.feature_id is external_for_profiles).
+                // For platform-profile a miss is a genuine local orphan — keep dropping.
+                if (inputs.profile === "application-product" ||
+                    inputs.profile === "integration-product") {
+                    const slug = screenSlug(fref);
+                    const key = `${screenId}__${slug}`;
+                    if (!screenFeature.has(key)) {
+                        screenFeature.set(key, {
+                            id: key,
+                            screen_id: screenId,
+                            feature_id: slug,
+                            source_sdd_id: "",
+                        });
+                    }
+                }
+                else {
+                    inputs.findings.add("orphan", `screen_feature: ${screenId} realises "${fref}" — no matching feature`);
+                }
+                continue;
+            }
+            const key = `${screenId}__${fid}`;
+            if (!screenFeature.has(key))
+                screenFeature.set(key, { id: key, screen_id: screenId, feature_id: fid, source_sdd_id: "" });
+        }
+        // persona_access: -> persona_screen
+        for (const pref of toList(fm.persona_access)) {
+            const pid = inputs.personaIdBySlug.get(screenSlug(pref)) ?? inputs.personaIdByName.get(normalise(pref));
+            if (!pid) {
+                inputs.findings.add("orphan", `persona_screen: ${screenId} persona_access "${pref}" — no matching persona`);
+                continue;
+            }
+            const key = `${pid}__${screenId}`;
+            if (!personaScreen.has(key))
+                personaScreen.set(key, { id: key, persona_id: pid, screen_id: screenId, source_sdd_id: "" });
+        }
+    }
+    return {
+        screens,
+        uiComponents: [...uiById.values()],
+        screenComponent: [...screenComponent.values()],
+        screenFeature: [...screenFeature.values()],
+        personaScreen: [...personaScreen.values()],
+        screenAction: [...screenAction.values()],
+    };
+}
+function emitDepthFindings(findings, screenId, status, m, ctx) {
+    const { flatThreshold, platform, overlay, componentNames, decorativePrimitives } = ctx;
+    const empty = m.componentCount <= 1;
+    const flat = !empty && m.maxDepth <= 1 && m.rootChildCount >= flatThreshold;
+    // Malformed invocation (vocabulary-free): a lowercase call head `name(`. The
+    // grammar invokes a component only via a Capitalised head; a lowercase id is a
+    // pure reference and never takes arguments. Such a token composes child-less and
+    // is uncounted by componentCount — so it can both *cause* a misleading
+    // `screen-empty-composition` and let a block render/lower with dropped subtrees.
+    // Surface it explicitly (warn) so the real cause is visible at build time.
+    if (m.lowercaseCallHeads.length > 0) {
+        const heads = m.lowercaseCallHeads.map((h) => `"${h}"`).join(", ");
+        findings.add("convention", `screen ${screenId}: lowercase call head${m.lowercaseCallHeads.length > 1 ? "s" : ""} ${heads} — a component must be Capitalised; a lowercase identifier is a reference and cannot take arguments (screen-lowercase-call-head)`);
+    }
+    if (empty) {
+        findings.add("coverage", `screen ${screenId}: composition is empty — root has no children (screen-empty-composition)`);
+    }
+    else if (flat) {
+        findings.add("coverage", `screen ${screenId}: composition is flat — root has ${m.rootChildCount} children at depth ${m.maxDepth} (screen-flat-composition)`);
+    }
+    // Status gate (keystone): `working` is the only maturity that asserts a
+    // faithful, complete composition (ADR 0168 §4.3). provisional/unknown/absent
+    // make no completeness claim and are not gated.
+    if (status === COMPLETENESS_STATUS && (empty || flat)) {
+        findings.add("convention", `screen ${screenId}: status "${COMPLETENESS_STATUS}" exceeds composition depth — block is ${empty ? "empty" : "flat"} (screen-status-exceeds-depth)`, "error");
+    }
+    // Mis-rooted (ADR 0168 §4.2 screen-root-is-leaf, archetype-aware per ADR 0169):
+    // root is a leaf/control rather than a screen container. isContainer combines
+    // the appears-with-children heuristic (containers) with the archetype map.
+    // Only fires when the screen declares a known `platform:` — without a map the
+    // heuristic alone can't distinguish an empty container root (Stack([])) from a
+    // genuine leaf root (Button([])), so the check no-ops (ADR 0168 §4.5).
+    if (m.rootComponent !== "" && m.rootChildCount === 0) {
+        const byMap = isContainerArchetype(m.rootComponent, platform, overlay);
+        if (byMap === false && !m.containers.has(m.rootComponent)) {
+            findings.add("convention", `screen ${screenId}: root component "${m.rootComponent}" is a leaf, not a container (screen-root-is-leaf)`, "error");
+        }
+    }
+    // Styling-primitive leakage (ADR 0168 §4.2 screen-styling-primitive-as-structure):
+    // an adopter-flagged decorative primitive composed as a structural component.
+    // No-ops when the adopter declares no decorative set.
+    if (decorativePrimitives !== undefined && decorativePrimitives.size > 0) {
+        const leaked = [...componentNames].filter((c) => decorativePrimitives.has(c)).sort();
+        if (leaked.length > 0) {
+            findings.add("convention", `screen ${screenId}: decorative primitive${leaked.length > 1 ? "s" : ""} ${leaked.map((c) => `"${c}"`).join(", ")} used as structure (screen-styling-primitive-as-structure)`);
+        }
+    }
+}
+function emptyResult() {
+    return { screens: [], uiComponents: [], screenComponent: [], screenFeature: [], personaScreen: [], screenAction: [] };
+}
+function isTemplate(name) {
+    if (/[{}]/.test(name))
+        return true; // `{placeholder}` scaffolding templates
+    // Skip the method-shipped screen boilerplate (`screen-spec-template.md`,
+    // `screen-template.md`, bare `template.md`) — but NOT domain screens whose
+    // name legitimately ends in "template" (script-template, config-template,
+    // email-template, …), which reverse extraction must catalogue.
+    const lower = name.toLowerCase();
+    return (lower === "template.md" ||
+        lower === "screen-template.md" ||
+        lower.endsWith("-spec-template.md"));
+}
+// entity-style slug: ALLCAPS-then-Pascal split so naming variation across
+// `MyEcoDrive` / `map_tracking_container` / `TE_driver` resolves stably
+// (per the Phase Pre real-menu finding; mirrors entitySlug).
+function screenSlug(s) {
+    return s
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function normalise(s) {
+    return s.trim().toLowerCase().replace(/\s+/g, " ");
+}
+// Recognised direction discriminators (ADR 0135). Others pass through flagged.
+const SCREEN_SOURCES = new Set(["screen-spec", "screen-extraction"]);
+function screenSource(value, findings, screenId) {
+    if (typeof value !== "string" || value.trim() === "")
+        return "screen-spec";
+    const v = value.trim();
+    if (!SCREEN_SOURCES.has(v)) {
+        findings.add("convention", `screens: ${screenId} source "${v}" outside the standard set {screen-spec, screen-extraction} — passed through`);
+    }
+    return v;
+}
+/**
+ * Evidence class from frontmatter (M-ADR 0175, schema 2.42.0). Free-form per the
+ * `context`-column precedent — conventional values are `code-reverse`,
+ * `vendor-doc`, `operational`, but the column is not an enum and an unrecognised
+ * value passes through silently rather than raising: the method does not own an
+ * adopter's evidence taxonomy. Accepts the `evidence-class` hyphen alias, as the
+ * events and data-model sources do.
+ */
+function evidenceClass(fm) {
+    const raw = fm["evidence_class"] ?? fm["evidence-class"];
+    return typeof raw === "string" ? raw.trim() : "";
+}
+function maturity(value, findings, screenId) {
+    const v = value.trim();
+    if (!STANDARD_MATURITY.has(v.toLowerCase())) {
+        findings.add("convention", `screens: ${screenId} status "${v}" outside standard maturity set — passed through`);
+    }
+    return v;
+}
+function parseFrontmatter(text, findings, filename) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!m)
+        return {};
+    try {
+        const parsed = parseYaml(m[1] ?? "");
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        findings.add("convention", `screens: ${filename} has an unparseable frontmatter block — ignored`);
+        return {};
+    }
+}
+function extractH1(text) {
+    for (const raw of text.replace(/^---\r?\n[\s\S]*?\r?\n---/, "").split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "")
+            continue;
+        const m = /^#\s+(.+)$/.exec(line);
+        if (!m)
+            return "";
+        const stripped = (m[1] ?? "").trim();
+        const prefix = /^Screen:\s*(.+)$/i.exec(stripped);
+        return prefix ? (prefix[1] ?? "").trim() : stripped;
+    }
+    return "";
+}
+function extractOpenUiLangBlock(text) {
+    const m = /```openui-lang\r?\n([\s\S]*?)```/.exec(text);
+    return m ? (m[1] ?? "") : null;
+}
+function matchAll(text, re) {
+    const out = [];
+    for (const m of text.matchAll(re))
+        if (m[1])
+            out.push(m[1]);
+    return out;
+}
+function toList(v) {
+    if (Array.isArray(v))
+        return v.map((x) => String(x).trim()).filter(Boolean);
+    if (typeof v === "string")
+        return v.split(",").map((x) => x.trim()).filter(Boolean);
+    return [];
+}
+//# sourceMappingURL=screens.js.map