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

package/dist/lib/catalogue/application-archetype/vocabulary.js

@@ -0,0 +1,177 @@
+/**
+ * Application-archetype vocabulary resolution (M-ADR 0191 §4.2).
+ *
+ * The `application_archetype` manifest trait is a *classification* over a
+ * tiered vocabulary. This module resolves a declared value against the union
+ * of:
+ *   - the **method tier** — `unclassified` only, built into sdd-cli (mirrors
+ *     how the ADR 0173/0176 method-tier scaffold archetypes are built in);
+ *   - the **reference-architecture / adopter bundle tiers** — seedless
+ *     vocabulary files (`application-archetypes.yaml`) shipped in consumed
+ *     bundles and extracted to the local bundle cache
+ *     (`.sdd/bundle-cache/<bundle>@<version>/`);
+ *   - an optional **adopter-local** extension file at
+ *     `.sdd/application-archetypes.yaml` in the SDD repo.
+ *
+ * This deliberately does NOT reuse the ADR 0176 scaffold registry resolver
+ * (`scaffold/registry.ts`): that resolver is seed-oriented and drops any
+ * entry with no `seeds[]`, whereas a classification archetype is seedless by
+ * design. It DOES share the same bundle-cache distribution substrate — this
+ * is a distinct data type over a shared substrate, not a second distribution
+ * mechanism (M-ADR 0191 §6).
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { BUNDLE_CACHE_REL, VOCAB_FILE } from "../../sync/bundle-cache.js";
+/** The sentinel that lives in the method tier — the back-compat default. */
+export const UNCLASSIFIED = "unclassified";
+export { VOCAB_FILE };
+/** Adopter-local extension file, relative to the SDD repo root. */
+export const ADOPTER_VOCAB_REL = join(".sdd", VOCAB_FILE);
+const VALID_PRESENCE = new Set([
+    "required",
+    "typical",
+    "optional",
+    "absent-by-shape",
+]);
+/** The built-in method tier (M-ADR 0191 §4.2 — `unclassified` only). */
+const METHOD_TIER = [
+    {
+        id: UNCLASSIFIED,
+        tier: "method",
+        shape: "the back-compat default; a product that has not declared a shape",
+        source: "method",
+    },
+];
+function parseVocabFile(raw, source) {
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return []; // malformed vocab — skip rather than break the build
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return [];
+    if (!Array.isArray(parsed.archetypes))
+        return [];
+    const tier = typeof parsed.tier === "string" ? parsed.tier : "unknown";
+    const out = [];
+    for (const a of parsed.archetypes) {
+        if (a === null || typeof a !== "object")
+            continue;
+        const rec = a;
+        const id = typeof rec.id === "string" ? rec.id : undefined;
+        if (!id)
+            continue;
+        const expectedBindings = parseExpectedBindings(rec.expected_bindings);
+        const conformanceExpectations = parseStringList(rec.conformance);
+        out.push({
+            id,
+            tier,
+            source,
+            ...(typeof rec.layer === "string" && { layer: rec.layer }),
+            ...(typeof rec.shape === "string" && { shape: rec.shape }),
+            ...(expectedBindings.length > 0 && { expectedBindings }),
+            ...(conformanceExpectations.length > 0 && { conformanceExpectations }),
+        });
+    }
+    return out;
+}
+/** Parse an archetype's `expected_bindings:` list, dropping malformed entries
+ *  (an unknown presence or a missing pattern is skipped, not fatal). */
+function parseExpectedBindings(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const e of raw) {
+        if (e === null || typeof e !== "object")
+            continue;
+        const rec = e;
+        const pattern = typeof rec.pattern === "string" ? rec.pattern : undefined;
+        const presence = typeof rec.presence === "string" ? rec.presence : undefined;
+        if (!pattern || !presence || !VALID_PRESENCE.has(presence))
+            continue;
+        out.push({ pattern, presence: presence });
+    }
+    return out;
+}
+/** Parse a `conformance:` list of opaque string tags, dropping non-strings. */
+function parseStringList(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((v) => typeof v === "string" && v.trim() !== "");
+}
+/** readdir(withFileTypes) that yields [] on any error, sorted by name. */
+async function readDirSafe(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch {
+        return [];
+    }
+}
+/** Find every application-archetypes.yaml within a cached bundle (root + nested). */
+async function findVocabFiles(dir, depth = 0) {
+    const found = [];
+    for (const e of await readDirSafe(dir)) {
+        if (e.isFile() && e.name === VOCAB_FILE) {
+            found.push(join(dir, e.name));
+        }
+        else if (e.isDirectory() && depth < 4) {
+            found.push(...(await findVocabFiles(join(dir, e.name), depth + 1)));
+        }
+    }
+    return found;
+}
+/**
+ * Discover the active vocabulary for an SDD repo: method tier ∪ every bundle
+ * vocab file in the bundle cache ∪ the adopter-local extension file.
+ */
+export async function discoverVocabulary(targetRepo) {
+    const terms = [...METHOD_TIER];
+    // Bundle tiers (RA + adopter bundles both land in the cache).
+    const cacheRoot = join(targetRepo, BUNDLE_CACHE_REL);
+    for (const e of await readDirSafe(cacheRoot)) {
+        if (!e.isDirectory())
+            continue;
+        const bundleCacheDir = join(cacheRoot, e.name);
+        const at = e.name.lastIndexOf("@");
+        const bundleName = at > 0 ? e.name.slice(0, at) : e.name;
+        for (const vocabPath of await findVocabFiles(bundleCacheDir)) {
+            let raw;
+            try {
+                raw = await readFile(vocabPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            terms.push(...parseVocabFile(raw, bundleName));
+        }
+    }
+    // Adopter-local extension.
+    try {
+        const raw = await readFile(join(targetRepo, ADOPTER_VOCAB_REL), "utf8");
+        terms.push(...parseVocabFile(raw, "adopter-local"));
+    }
+    catch {
+        // absent — fine
+    }
+    return { terms, ids: new Set(terms.map((t) => t.id)) };
+}
+/**
+ * Resolve a declared archetype value against a vocabulary. `undefined`
+ * defaults to `unclassified` (always resolved). A declared value that is not
+ * in the vocabulary is unresolved (the caller emits an error finding).
+ */
+export function resolveArchetype(declared, vocab) {
+    const value = declared ?? UNCLASSIFIED;
+    return {
+        value,
+        resolved: vocab.ids.has(value),
+        unclassified: value === UNCLASSIFIED,
+    };
+}
+//# sourceMappingURL=vocabulary.js.map

package/dist/lib/catalogue/archetype/maps/android.yaml

@@ -0,0 +1,66 @@
+# Default archetype map — android (ADR 0169 §4.2). Method-owned.
+#
+# Android View + Material toolkit. These names are industry-standard (Google/AndroidX/Material)
+# and identical across every Android app — never an adopter's bespoke vocabulary.
+# Resolution order (ADR 0169 §4.3): adopter overlay override -> by_token -> by_suffix_heuristic -> default.
+# Selected per screen by `platform: android` frontmatter.
+
+map_version: "1.0.0"
+platform: android
+
+# Material/AndroidX vendor prefixes, stripped before token lookup.
+strip_prefixes: [Material, Appcompat, AppCompat, Androidx]
+
+by_token:
+  ConstraintLayout: stack
+  FrameLayout: stack
+  LinearLayout: stack
+  RelativeLayout: stack
+  CoordinatorLayout: scaffold
+  NestedScrollView: scroll
+  ScrollView: scroll
+  RecyclerView: list
+  ListView: list
+  GridLayout: grid
+  GridView: grid
+  ViewPager: paged-panes
+  ViewPager2: paged-panes
+  TabLayout: tab-strip
+  BottomNavigationView: tab-bar
+  NavigationView: sidebar
+  NavigationRailView: sidebar
+  Toolbar: app-bar
+  AppBarLayout: app-bar
+  ActionBar: app-bar
+  CollapsingToolbarLayout: app-bar
+  Button: button
+  MaterialButton: button
+  ImageButton: button
+  FloatingActionButton: fab
+  ExtendedFloatingActionButton: fab
+  Chip: tab
+  ChipGroup: button-group
+  ToggleButton: segmented-control
+  TextView: text
+  EditText: text
+  MaterialTextView: text
+  ImageView: image
+  ImageFilterView: image
+  CardView: card
+  MaterialCardView: card
+  Snackbar: banner
+  BottomSheetDialog: sheet
+  AlertDialog: modal
+  DialogFragment: modal
+
+by_suffix_heuristic:
+  Layout: stack
+  View: panel
+  Button: button
+  Bar: app-bar
+  Dialog: modal
+  Card: card
+  Text: text
+  Image: image
+
+default: panel

package/dist/lib/catalogue/archetype/maps/swiftui.yaml

@@ -0,0 +1,58 @@
+# Default archetype map — swiftui (ADR 0169 §4.2). Method-owned.
+#
+# Apple SwiftUI toolkit. Industry-standard Apple names, identical across every SwiftUI app —
+# never an adopter's bespoke vocabulary.
+# Resolution order (ADR 0169 §4.3): adopter overlay override -> by_token -> by_suffix_heuristic -> default.
+# Selected per screen by `platform: swiftui` frontmatter.
+
+map_version: "1.0.0"
+platform: swiftui
+
+strip_prefixes: []
+
+by_token:
+  VStack: stack
+  HStack: row
+  ZStack: stack
+  LazyVStack: stack
+  LazyHStack: row
+  Grid: grid
+  LazyVGrid: grid
+  LazyHGrid: grid
+  ScrollView: scroll
+  List: list
+  Section: panel
+  ForEach: list-item       # repeated child marker; rendered as a list-item row
+  Form: list
+  NavigationView: nav-bar
+  NavigationStack: nav-bar
+  NavigationSplitView: sidebar
+  NavigationLink: button
+  TabView: tab-bar
+  Button: button
+  Menu: list
+  Toolbar: app-bar
+  ToolbarItem: button
+  Text: text
+  Label: text
+  TextField: text
+  SecureField: text
+  Image: image
+  AsyncImage: image
+  Spacer: text             # decorative; flagged by screen-styling-primitive-as-structure
+  Divider: text            # decorative; flagged by screen-styling-primitive-as-structure
+  GroupBox: card
+  Sheet: sheet
+  Alert: modal
+  Picker: segmented-control
+
+by_suffix_heuristic:
+  Stack: stack
+  View: panel
+  Button: button
+  Link: button
+  Field: text
+  Image: image
+  Text: text
+
+default: panel

package/dist/lib/catalogue/archetype/maps/uikit.yaml

@@ -0,0 +1,48 @@
+# Default archetype map — uikit (ADR 0169 §4.2). Method-owned.
+#
+# Apple UIKit toolkit. Industry-standard Apple names (UI- prefixed), identical across every
+# UIKit app — never an adopter's bespoke vocabulary.
+# Resolution order (ADR 0169 §4.3): adopter overlay override -> by_token -> by_suffix_heuristic -> default.
+# Selected per screen by `platform: uikit` frontmatter.
+
+map_version: "1.0.0"
+platform: uikit
+
+# The `UI` vendor prefix is stripped, so the `by_token` keys are unprefixed.
+strip_prefixes: [UI, NS]
+
+by_token:
+  View: panel
+  StackView: stack
+  ScrollView: scroll
+  TableView: list
+  TableViewCell: list-item
+  CollectionView: grid
+  CollectionViewCell: card
+  NavigationBar: nav-bar
+  NavigationController: nav-bar
+  TabBar: tab-bar
+  TabBarController: tab-bar
+  Toolbar: app-bar
+  BarButtonItem: button
+  Button: button
+  Label: text
+  TextField: text
+  TextView: text
+  ImageView: image
+  PageViewController: paged-panes
+  SegmentedControl: segmented-control
+  ActivityIndicatorView: text
+  AlertController: modal
+  Stack: stack
+
+by_suffix_heuristic:
+  View: panel
+  Controller: panel
+  Button: button
+  Bar: app-bar
+  Label: text
+  Field: text
+  Image: image
+
+default: panel

package/dist/lib/catalogue/archetype/maps/web-generic.yaml

@@ -0,0 +1,86 @@
+# Default archetype map — web-generic (ADR 0169 §4.2). Method-owned.
+#
+# Keys off component NAMES (which the builder already parses), not design-system source.
+# Vendor-standard / common-DS tokens ONLY — never an adopter's bespoke vocabulary.
+# Resolution order (ADR 0169 §4.3): adopter overlay override -> by_token -> by_suffix_heuristic -> default.
+# Selected per screen by `platform: web-generic` (or web) frontmatter.
+
+map_version: "1.0.0"
+platform: web-generic
+
+# Stripped (case-insensitive) before token lookup, so `MuiButton`/`ChButton` -> `Button`.
+strip_prefixes: [Mui, Ch, Ds, Ui, App, Base, Core, V]
+
+by_token:
+  Container: grid
+  Grid: grid
+  Row: row
+  Col: col
+  Column: col
+  Stack: stack
+  Flex: row
+  Scroll: scroll
+  ScrollArea: scroll
+  Tabs: tab-strip
+  Tab: tab
+  TabPanel: pane
+  Table: table
+  DataGrid: table
+  List: list
+  ListItem: list-item
+  Menu: list
+  Card: card
+  Panel: panel
+  Dialog: modal
+  Modal: modal
+  Popup: modal
+  Popover: modal
+  Drawer: sidebar
+  SidePanel: sidebar
+  Sidebar: sidebar
+  Nav: nav-bar
+  Navbar: nav-bar
+  AppBar: app-bar
+  Header: app-bar
+  Toolbar: app-bar
+  Alert: banner
+  Banner: banner
+  Toast: banner
+  Snackbar: banner
+  Sheet: sheet
+  BottomSheet: sheet
+  Btn: button
+  Button: button
+  IconButton: button
+  Fab: fab
+  ButtonGroup: button-group
+  SegmentedControl: segmented-control
+  Stat: text
+  StatCard: card
+  KpiBar: kpi-bar
+  Text: text
+  Typography: text
+  Label: text
+  Heading: text
+  Image: image
+  Img: image
+  Avatar: image
+  Icon: image
+
+# Applied when no token matches. First matching suffix wins.
+by_suffix_heuristic:
+  Button: button
+  Bar: app-bar
+  List: list
+  Grid: grid
+  Card: card
+  Panel: panel
+  Dialog: modal
+  Modal: modal
+  Layout: stack
+  Container: grid
+  Text: text
+  Image: image
+  Icon: image
+
+default: panel

package/dist/lib/catalogue/archetype/openui-archetype-vocabulary.yaml

@@ -0,0 +1,46 @@
+# OpenUI Archetype Vocabulary — method-owned (ADR 0169 §4.1)
+#
+# A closed, platform-tagged superset of visual archetypes. An archetype assigns a
+# component a VISUAL SHAPE + slots/orientation — never geometry or styling (stays inside
+# the compose-only boundary, ADR 0166 §3). Default archetype maps
+# (archetype-maps/*.yaml) resolve adopter component NAMES to entries here; the
+# render-screen-wireframe skill lowers a resolved tree to SVG using `render`.
+#
+# `is_container` feeds ADR 0168 §4.1 isContainer when a resolved map is present.
+
+vocabulary_version: "1.0.0"
+
+archetypes:
+
+  # --- structural containers -------------------------------------------------
+  scaffold:        { is_container: true,  render: { slots: [header, main, footer], orientation: vertical } }
+  app-bar:         { is_container: true,  render: { shape: bar, position: top } }
+  nav-bar:         { is_container: true,  render: { shape: bar, position: top } }
+  tab-bar:         { is_container: true,  render: { shape: bar, position: bottom } }
+  sidebar:         { is_container: true,  render: { shape: rail, position: left } }
+  stack:           { is_container: true,  render: { orientation: vertical } }
+  row:             { is_container: true,  render: { orientation: horizontal } }
+  col:             { is_container: true,  render: { orientation: vertical } }
+  grid:            { is_container: true,  render: { shape: grid } }
+  scroll:          { is_container: true,  render: { orientation: vertical, scroll: true } }
+  list:            { is_container: true,  render: { orientation: vertical, repeat: true } }
+  table:           { is_container: true,  render: { shape: grid, header_row: true } }
+  card:            { is_container: true,  render: { shape: card } }
+  panel:           { is_container: true,  render: { shape: panel } }          # opaque fallback
+  paged-panes:     { is_container: true,  render: { shape: paged, active_first: true } }
+  pane:            { is_container: true,  render: { shape: panel } }
+  tab-strip:       { is_container: true,  render: { orientation: horizontal, shape: chips } }
+  button-group:    { is_container: true,  render: { orientation: horizontal } }
+  segmented-control: { is_container: true, render: { orientation: horizontal, shape: chips } }
+  kpi-bar:         { is_container: true,  render: { orientation: horizontal, shape: chips } }
+  modal:           { is_container: true,  render: { shape: floating, overlay: true } }
+  sheet:           { is_container: true,  render: { shape: floating, position: bottom } }
+  banner:          { is_container: true,  render: { shape: bar } }
+
+  # --- leaves ----------------------------------------------------------------
+  tab:             { is_container: false, render: { shape: chip } }
+  list-item:       { is_container: false, render: { shape: row } }
+  button:          { is_container: false, render: { shape: button } }
+  fab:             { is_container: false, render: { shape: circle, position: bottom-right } }
+  text:            { is_container: false, render: { shape: text } }
+  image:           { is_container: false, render: { shape: image } }

package/dist/lib/catalogue/archetype/resolver.js

@@ -0,0 +1,103 @@
+// OpenUI archetype resolver (per ADR 0169).
+//
+// Binds an adopter component NAME to a visual ARCHETYPE via a method-shipped
+// platform default map plus an optional adopter overlay. The binding is what
+// makes a shape-blind openui-lang block renderable as a wireframe, and it
+// supplies the container/leaf classification the ADR 0168 `screen-root-is-leaf`
+// check consumes (isContainerArchetype).
+//
+// Resolution order (ADR 0169 §4.3): adopter override -> default by_token (after
+// stripping a vendor prefix) -> by_suffix_heuristic -> default (panel).
+//
+// The vocabulary + the four default maps are method-owned reference data,
+// VENDORED from sdd-method (docs/method/methods/guides/openui-archetype-*.yaml /
+// archetype-maps/) — the same vendoring relationship as canonical-schema.yaml.
+// They use vendor-standard names only; never an adopter's bespoke vocabulary.
+// copy-yaml-assets.mjs copies them next to the compiled JS at build time.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PLATFORMS = new Set(["web-generic", "android", "swiftui", "uikit"]);
+const FALLBACK_ARCHETYPE = "panel";
+// Loaded once, cached. Reference data is immutable at runtime.
+let vocabularyCache;
+const mapCache = new Map();
+function loadVocabulary() {
+    if (vocabularyCache === undefined) {
+        const raw = readFileSync(join(__dirname, "openui-archetype-vocabulary.yaml"), "utf-8");
+        const parsed = parseYaml(raw);
+        vocabularyCache = { archetypes: parsed?.archetypes ?? {} };
+    }
+    return vocabularyCache;
+}
+function loadMap(platform) {
+    let m = mapCache.get(platform);
+    if (m === undefined) {
+        const raw = readFileSync(join(__dirname, "maps", `${platform}.yaml`), "utf-8");
+        m = parseYaml(raw) ?? {};
+        mapCache.set(platform, m);
+    }
+    return m;
+}
+/** True when `platform` has a method-shipped default map. */
+export function isKnownPlatform(platform) {
+    return platform !== undefined && PLATFORMS.has(platform);
+}
+function stripPrefix(name, prefixes) {
+    for (const p of prefixes ?? []) {
+        if (name.length > p.length && name.startsWith(p))
+            return name.slice(p.length);
+    }
+    return name;
+}
+/**
+ * Resolve a component name to a visual archetype for a platform, honouring an
+ * optional adopter overlay. Always resolves (panel fallback) — never throws.
+ */
+export function resolveArchetype(name, platform, overlay) {
+    const override = overlay?.overrides?.[name];
+    if (override !== undefined)
+        return { archetype: override, provenance: "override" };
+    const map = loadMap(platform);
+    const token = stripPrefix(name, map.strip_prefixes);
+    const byToken = map.by_token?.[token] ?? map.by_token?.[name];
+    if (byToken !== undefined)
+        return { archetype: byToken, provenance: "default" };
+    // First suffix the name ends with wins.
+    for (const [suffix, archetype] of Object.entries(map.by_suffix_heuristic ?? {})) {
+        if (name.endsWith(suffix))
+            return { archetype, provenance: "heuristic" };
+    }
+    return { archetype: map.default ?? FALLBACK_ARCHETYPE, provenance: "fallback" };
+}
+/**
+ * Whether a component classifies as a container archetype for a platform.
+ * Used by ADR 0168 §4.1 isContainer to refine the appears-with-children
+ * heuristic. Returns undefined when the platform has no map (caller falls back
+ * to the heuristic) so an absent map never mis-classifies a known container.
+ */
+export function isContainerArchetype(name, platform, overlay) {
+    if (!isKnownPlatform(platform))
+        return undefined;
+    const { archetype } = resolveArchetype(name, platform, overlay);
+    return loadVocabulary().archetypes[archetype]?.is_container === true;
+}
+/**
+ * The vendor name prefixes the platform's default map strips (e.g. `UI`/`NS` for
+ * uikit, `Mui`/`Ch`/… for web-generic). The renderer combines these with the
+ * adopter overlay's `strip_prefixes` to humanise component names into labels.
+ * Returns `[]` for an unknown platform.
+ */
+export function mapStripPrefixes(platform) {
+    if (!isKnownPlatform(platform))
+        return [];
+    return loadMap(platform).strip_prefixes ?? [];
+}
+/** Vocabulary metadata for an archetype: container flag + render hints. */
+export function archetypeInfo(archetype) {
+    const entry = loadVocabulary().archetypes[archetype];
+    return { isContainer: entry?.is_container === true, render: entry?.render ?? {} };
+}
+//# sourceMappingURL=resolver.js.map