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

package/dist/lib/catalogue/builders/feature-tree-walker.js

@@ -0,0 +1,295 @@
+/**
+ * Shared walker for `feature-tree.md` files. Used by:
+ *   - `buildFeatureGroups` — consumes H2/H3 events to emit `feature_groups.csv`.
+ *   - `buildFeatures` (bullet branch, schema 2.2.0+) — consumes bullet
+ *     events to emit `features.csv` rows with `source: "feature-tree"`.
+ *
+ * Both consumers need:
+ *   - in-fence detection (skip headings/bullets inside ``` blocks),
+ *   - the same H2/H3 slug derivation,
+ *   - the same group-id format (`{productId}-group-{h2}[-{h3}]`),
+ *   - the same candidate-paths order (`<root>/feature-tree.md` then
+ *     `<root>/docs/platform/feature-tree.md`).
+ *
+ * Lifting these into one module keeps both builders honest about the
+ * exact shape of the file they read.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+const CANDIDATE_PATHS_REL = [
+    "feature-tree.md",
+    join("docs", "platform", "feature-tree.md"),
+];
+/** Resolve the first existing `feature-tree.md` candidate at the SDD root. */
+export async function findFeatureTreeFile(sddPath) {
+    for (const rel of CANDIDATE_PATHS_REL) {
+        const full = join(sddPath, rel);
+        try {
+            await readFile(full, "utf-8");
+            return full;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT")
+                continue;
+            throw err;
+        }
+    }
+    return null;
+}
+/** Lowercase-hyphenated slug used by feature-group ids and bullet ids. */
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/&/g, " and ")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Build a feature-group id from a product id and one or two heading
+ * slugs. Single-arg form returns the H2-level id; two-arg form returns
+ * the nested H3-level id. Matches `feature-groups.ts` row emission so
+ * the bullet parser's `parent_group_id` resolves cleanly.
+ */
+export function featureGroupId(productId, h2Slug, h3Slug) {
+    const base = `${productId}-group-${h2Slug}`;
+    return h3Slug !== undefined && h3Slug !== "" ? `${base}-${h3Slug}` : base;
+}
+/**
+ * Walk a `feature-tree.md` text body and emit headings + bullets in
+ * source order. Inside fenced code blocks (```), nothing is emitted.
+ *
+ * Heading rules (mirror `feature-groups.ts` for compatibility):
+ *   - H2/H3 lines emit a HeadingEvent. Numeric prefixes (`1.`, `1.1`)
+ *     and trailing `[Tag]` markers are stripped from the displayed
+ *     text and from the slug.
+ *   - An H3 without an enclosing H2 emits with `parentH2Slug: ""`.
+ *
+ * Bullet rules (canonical form per
+ * `reverse/templates/application-product/feature-tree.md`):
+ *
+ *     - `{slug}` — {description} `[runway: {marker}]`
+ *
+ *   - Required: leading `-` or `*`, slug-in-backticks.
+ *   - Optional: em-dash + description (description may be empty).
+ *   - Optional trailing `` `[runway: ...]` `` token; captured verbatim
+ *     into `runway` and stripped from `description`.
+ *   - Optional Markdown footnote markers `[^...]` anywhere on the
+ *     line (`- \`{slug}\`[^x] — {description} \`[runway: ...]\`[^y]`).
+ *     Markers are stripped before regex matching so they don't break
+ *     bullet detection or runway-tail extraction. Authors typically
+ *     place a single end-of-line marker pointing at the matching
+ *     entry in `reverse-evidence/feature-grounding-evidence.yaml`.
+ *
+ * The walker does NOT enforce a description-length cap — that's a
+ * builder concern. Slugs not matching `[a-z0-9][a-z0-9-]*` are
+ * skipped (defensive: avoids accidentally claiming free-form
+ * backtick-wrapped prose like inline code refs).
+ */
+export function walkFeatureTree(text) {
+    const out = [];
+    let inFence = false;
+    let currentH2Slug = "";
+    let currentH3Slug = "";
+    let inDataRequirements = false;
+    // A bullet's description may wrap onto indented continuation lines. Reading one line per
+    // bullet cut it at the first break (a KPI list lost mid-sentence), so wrapped lines are
+    // joined into the bullet before it is parsed.
+    const lines = joinContinuations(text.split(/\r?\n/));
+    for (const rawLine of lines) {
+        const line = rawLine.trimEnd();
+        if (line.startsWith("```")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const heading = matchHeading(line);
+        // A `## Data Requirements` section (M-ADR 0216 §4.3) is method-defined content inside the feature
+        // tree, not a feature group: skip the heading and everything under it until the next `##`.
+        // Without this, every adopter declaring tree demand got a spurious group (found by the first
+        // adopter to do so).
+        if (heading !== null && heading.level === 2)
+            inDataRequirements = /^Data Requirements\b/i.test(heading.text.trim());
+        if (inDataRequirements)
+            continue;
+        if (heading !== null) {
+            const slug = slugify(heading.text);
+            if (slug === "")
+                continue;
+            if (heading.level === 2) {
+                currentH2Slug = slug;
+                currentH3Slug = "";
+                out.push({
+                    kind: "h2",
+                    text: heading.text,
+                    slug,
+                    parentH2Slug: "",
+                });
+            }
+            else {
+                currentH3Slug = slug;
+                out.push({
+                    kind: "h3",
+                    text: heading.text,
+                    slug,
+                    parentH2Slug: currentH2Slug,
+                });
+            }
+            continue;
+        }
+        const bullet = matchBullet(line);
+        if (bullet !== null) {
+            out.push({
+                kind: "bullet",
+                slug: bullet.slug,
+                description: bullet.description,
+                runway: bullet.runway,
+                parentH2Slug: currentH2Slug,
+                parentH3Slug: currentH3Slug,
+            });
+        }
+    }
+    return out;
+}
+const FEATURE_SERVICES_ROW_RE = /^\|\s*`([a-z0-9][a-z0-9-]*)`\s*\|\s*(.+?)\s*\|\s*$/;
+// The Services column holds SERVICE ids, whose alphabet is services.csv's —
+// which admits `_` (e.g. a service named for its repository). It is NOT the
+// feature-slug alphabet above: slugs are a documented convention and become
+// primary keys, so FEATURE_SERVICES_ROW_RE's slug group stays strict.
+const BACKTICKED_SPAN_RE = /`([^`]*)`/g;
+const SERVICE_ID_RE = /^[a-z0-9][a-z0-9_-]*$/;
+/**
+ * Parse the `## Feature Services` section of a `feature-tree.md` body (the
+ * application-product authoring surface for `feature_service`, per M-ADR
+ * 0157 — see WS0c of `catalogue-coverage-invariants.md`). Table shape:
+ *
+ *     | Feature | Services |
+ *     |---------|----------|
+ *     | `{feature-slug}` | `{service-id}`, `{service-id}` |
+ *
+ * Returns one entry per table row (not one per feature-service pair) so the
+ * caller can resolve/validate each service id independently. A malformed or
+ * absent section yields an empty array — the caller decides whether that's
+ * a finding.
+ */
+export function parseFeatureServicesTable(text) {
+    const out = [];
+    let inSection = false;
+    let inTable = false;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trimEnd();
+        if (/^##\s+Feature Services\s*$/.test(line)) {
+            inSection = true;
+            inTable = false;
+            continue;
+        }
+        if (inSection && /^##\s+/.test(line))
+            break;
+        if (!inSection)
+            continue;
+        const trimmed = line.trim();
+        if (trimmed.startsWith("| Feature") || /^\|[-\s|]+\|$/.test(trimmed)) {
+            inTable = true;
+            continue;
+        }
+        if (!inTable)
+            continue;
+        if (trimmed === "")
+            continue;
+        if (!trimmed.startsWith("|")) {
+            inTable = false;
+            continue;
+        }
+        const m = FEATURE_SERVICES_ROW_RE.exec(line);
+        if (m === null || m[1] === undefined || m[2] === undefined)
+            continue;
+        const serviceIds = [];
+        const rejectedSpans = [];
+        for (const span of m[2].matchAll(BACKTICKED_SPAN_RE)) {
+            const value = span[1];
+            (SERVICE_ID_RE.test(value) ? serviceIds : rejectedSpans).push(value);
+        }
+        if (serviceIds.length === 0 && rejectedSpans.length === 0)
+            continue;
+        out.push(rejectedSpans.length > 0
+            ? { featureSlug: m[1], serviceIds, rejectedSpans }
+            : { featureSlug: m[1], serviceIds });
+    }
+    return out;
+}
+function matchHeading(line) {
+    const m = /^(#{2,3})\s+(.+?)\s*$/.exec(line);
+    if (!m || m[1] === undefined || m[2] === undefined)
+        return null;
+    const level = m[1].length === 2 ? 2 : 3;
+    const text = m[2]
+        .replace(/^[\d.]+\s*/, "")
+        .replace(/\s*\[.+?\]\s*$/, "")
+        .trim();
+    if (text === "")
+        return null;
+    return { level, text };
+}
+const BULLET_RE = /^\s*[-*]\s+`([a-z0-9][a-z0-9-]*)`(?:\s*[—–-]\s*(.*))?\s*$/;
+const RUNWAY_TAIL_RE = /\s*`\[runway:\s*([^\]]+?)\s*\]`\s*$/;
+const FOOTNOTE_MARKER_RE = /\s*\[\^[^\]]+\]/g;
+/**
+ * Strip Markdown footnote markers (`[^...]`) from a line. Markers can
+ * appear anywhere — immediately after the slug, mid-description, or
+ * trailing after the runway tag. They are rendering aids that point
+ * authors at evidence files; they don't carry feature semantics, so
+ * strip-before-match keeps the bullet/runway regexes simple.
+ */
+function stripFootnoteMarkers(line) {
+    return line.replace(FOOTNOTE_MARKER_RE, "");
+}
+/**
+ * Join a bullet's wrapped continuation lines onto it: an indented, non-blank line that is not
+ * itself a list item, heading, table row or fence, directly following a bullet (or another
+ * continuation). Fenced blocks are passed through untouched.
+ */
+function joinContinuations(lines) {
+    const out = [];
+    let inFence = false;
+    let joinable = false;
+    for (const raw of lines) {
+        const t = raw.trim();
+        if (t.startsWith("```")) {
+            inFence = !inFence;
+            joinable = false;
+            out.push(raw);
+            continue;
+        }
+        if (inFence) {
+            out.push(raw);
+            continue;
+        }
+        const isContinuation = joinable &&
+            /^\s+\S/.test(raw) &&
+            !/^([-*+]\s|\d+[.)]\s|#|\||>)/.test(t);
+        if (isContinuation) {
+            out[out.length - 1] = `${out[out.length - 1].trimEnd()} ${t}`;
+            continue;
+        }
+        joinable = /^\s*[-*+]\s/.test(raw);
+        out.push(raw);
+    }
+    return out;
+}
+function matchBullet(line) {
+    const stripped = stripFootnoteMarkers(line);
+    const m = BULLET_RE.exec(stripped);
+    if (!m || m[1] === undefined)
+        return null;
+    const slug = m[1];
+    let rest = (m[2] ?? "").trim();
+    let runway = "";
+    const r = RUNWAY_TAIL_RE.exec(rest);
+    if (r !== null && r[1] !== undefined) {
+        runway = r[1];
+        rest = rest.slice(0, r.index).trim();
+    }
+    return { slug, description: rest, runway };
+}
+//# sourceMappingURL=feature-tree-walker.js.map

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

@@ -0,0 +1,300 @@
+// Features discoverer — emits `features.csv` rows from three sources:
+//
+//   1. Capability-scoped specs at `docs/domains/<d>/product/features/<folder>/*.md`.
+//      Folder→capability mapping uses (a) the traceability manifest's
+//      `capability.feature_directory` field — authoritative when a
+//      capability spec uses a folder name that differs from the
+//      canonical capability_id (e.g. capability_id "alerts-rules-engine"
+//      with feature_directory pointing at "features/alerts-rules/") —
+//      then (b) the folder name itself when it equals a known capability_id.
+//      id format: `{capability_id}-{feature-slug}`.
+//
+//   2. Application-product profile only: standalone specs at
+//      `features/<group>/<file>.md` under the SDD root.
+//      id format: `{productId}-{stem}`.
+//
+//   3. Application-product profile only (schema 2.2.0+): bullets in
+//      `feature-tree.md`. Canonical form:
+//
+//          - `{slug}` — {description} `[runway: {marker}]`
+//
+//      id format: `{productId}-{slug}`. Source path resolved via the
+//      shared `feature-tree-walker` (same candidates that
+//      buildFeatureGroups walks).
+//
+// Dedup ordering matters: walker (1) runs first (capability features),
+// then walker (2) (standalone specs), then walker (3) (bullets). When
+// a bullet's id is already in `seen` from a standalone spec the spec
+// wins — divergence finding fires for the bullet. This matches the
+// "standalone is more authoritative than bullet inventory" rule from
+// plan extract-feature-tree-bullets.md §1.4.
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+import { featureGroupId, findFeatureTreeFile, walkFeatureTree, } from "./feature-tree-walker.js";
+// ADR 0165: the standard, cross-SDD-comparable `features.maturity` vocabulary
+// (canonical-schema §features). Feature-tree `[runway: X]` markers whose value
+// is in this set ARE the maturity signal — wire them to `maturity` (comparable)
+// while `runway` keeps the full marker (adopter-owned, incl. non-standard values
+// like migration codes). Markers outside the set leave `maturity` empty.
+const STANDARD_MATURITY = new Set(["working", "provisional", "unknown", "absent"]);
+/** Standard-set maturity from a feature-tree runway marker, else "". */
+function maturityFromRunway(runway) {
+    const v = runway.trim().toLowerCase();
+    return STANDARD_MATURITY.has(v) ? v : "";
+}
+const DOMAINS_DIR_REL = join("docs", "domains");
+const DESCRIPTION_MAX = 500;
+export async function buildFeatures(inputs) {
+    // Build folder→capability_id map from traceability feature_directory.
+    const folderToCap = new Map();
+    for (const m of inputs.manifests) {
+        const featDirs = m.capability.feature_directory;
+        if (!featDirs || featDirs.length === 0)
+            continue;
+        if (!inputs.knownCapabilityIds.has(m.capability.id))
+            continue;
+        for (const featDir of featDirs) {
+            const folder = basename(featDir.replace(/\/+$/, ""));
+            folderToCap.set(folder, m.capability.id);
+        }
+    }
+    const featurePaths = await collectFeatureSpecs(inputs.sddPath);
+    const rows = [];
+    const idByPath = new Map();
+    const idBySlug = new Map();
+    const seen = new Set();
+    for (const path of featurePaths) {
+        const relPath = relative(inputs.sddPath, path);
+        const folder = parentFolder(relPath);
+        const capId = folderToCap.get(folder)
+            ?? (inputs.knownCapabilityIds.has(folder) ? folder : "");
+        if (capId === "") {
+            inputs.findings.add("orphan", `${relPath}: feature folder "${folder}" has no matching capability (no traceability feature_directory + folder is not a capability id)`);
+            continue;
+        }
+        const stem = basename(relPath).replace(/\.md$/i, "");
+        const id = `${capId}-${stem}`;
+        if (seen.has(id)) {
+            inputs.findings.add("divergence", `${relPath}: feature id "${id}" already emitted by an earlier file`);
+            continue;
+        }
+        seen.add(id);
+        const text = await readFile(path, "utf-8");
+        const description = extractH1Title(text);
+        rows.push({
+            id,
+            name: stem,
+            product_id: "",
+            capability_id: capId,
+            parent_group_id: "",
+            parent_feature_id: "",
+            description,
+            maturity: "",
+            status: "active",
+            source: "feature-spec",
+            runway: "",
+            source_sdd_id: "",
+        });
+        idByPath.set(relPath, id);
+        if (!idBySlug.has(stem))
+            idBySlug.set(stem, id);
+    }
+    // App-product profile: also walk `features/<group>/<file>.md` at SDD root.
+    // These features are owned by the SDD's product (not by a capability) —
+    // capability_id is left empty; product_id carries the link.
+    if (inputs.profile === "application-product") {
+        const appFeatures = await collectAppFeatureSpecs(inputs.sddPath);
+        for (const path of appFeatures) {
+            const relPath = relative(inputs.sddPath, path);
+            const stem = basename(relPath).replace(/\.md$/i, "");
+            const id = `${inputs.productId}-${stem}`;
+            if (seen.has(id)) {
+                inputs.findings.add("divergence", `${relPath}: feature id "${id}" already emitted by an earlier file`);
+                continue;
+            }
+            seen.add(id);
+            const text = await readFile(path, "utf-8");
+            const description = extractH1Title(text);
+            rows.push({
+                id,
+                name: stem,
+                product_id: inputs.productId,
+                capability_id: "",
+                parent_group_id: "",
+                parent_feature_id: "",
+                description,
+                maturity: "",
+                status: "active",
+                source: "feature-spec",
+                runway: "",
+                source_sdd_id: "",
+            });
+            idByPath.set(relPath, id);
+            if (!idBySlug.has(stem))
+                idBySlug.set(stem, id);
+        }
+        // Bullet branch — feature-tree.md.
+        await emitBulletRows({
+            sddPath: inputs.sddPath,
+            productId: inputs.productId,
+            findings: inputs.findings,
+            runwayVocabulary: inputs.runwayVocabulary ?? null,
+            seen,
+            rows,
+            idBySlug,
+        });
+    }
+    return { rows, idByPath, idBySlug };
+}
+async function emitBulletRows(ctx) {
+    const featureTreePath = await findFeatureTreeFile(ctx.sddPath);
+    if (!featureTreePath)
+        return;
+    const text = await readFile(featureTreePath, "utf-8");
+    const events = walkFeatureTree(text);
+    const relPath = relative(ctx.sddPath, featureTreePath);
+    let bulletCount = 0;
+    for (const ev of events) {
+        if (ev.kind !== "bullet")
+            continue;
+        bulletCount++;
+        const id = `${ctx.productId}-${ev.slug}`;
+        if (ctx.seen.has(id)) {
+            ctx.findings.add("divergence", `${relPath}: feature-tree.md bullet "${ev.slug}" superseded by an earlier feature spec with id "${id}"`);
+            continue;
+        }
+        ctx.seen.add(id);
+        if (ev.runway !== "" &&
+            ctx.runwayVocabulary !== null &&
+            !ctx.runwayVocabulary.has(ev.runway)) {
+            ctx.findings.add("convention", `${relPath}: unrecognised runway value "${ev.runway}" in feature "${ev.slug}" — declare it in feature-runway-vocabulary.yaml`);
+        }
+        const parentGroupId = ev.parentH3Slug !== ""
+            ? featureGroupId(ctx.productId, ev.parentH2Slug !== "" ? ev.parentH2Slug : ev.parentH3Slug, ev.parentH2Slug !== "" ? ev.parentH3Slug : undefined)
+            : ev.parentH2Slug !== ""
+                ? featureGroupId(ctx.productId, ev.parentH2Slug)
+                : "";
+        const description = ev.description.length > DESCRIPTION_MAX
+            ? ev.description.slice(0, DESCRIPTION_MAX)
+            : ev.description;
+        ctx.rows.push({
+            id,
+            name: ev.slug,
+            product_id: ctx.productId,
+            capability_id: "",
+            parent_group_id: parentGroupId,
+            parent_feature_id: "",
+            description,
+            maturity: maturityFromRunway(ev.runway),
+            status: "active",
+            source: "feature-tree",
+            runway: ev.runway,
+            source_sdd_id: "",
+        });
+        if (!ctx.idBySlug.has(ev.slug))
+            ctx.idBySlug.set(ev.slug, id);
+    }
+    if (bulletCount === 0) {
+        ctx.findings.add("coverage", `${relPath}: feature-tree.md found but no recognisable feature bullets — features.csv populated only from features/ specs`);
+    }
+}
+const FEATURES_DIR_REL = "features";
+async function collectAppFeatureSpecs(sddPath) {
+    const out = [];
+    const featuresDir = join(sddPath, FEATURES_DIR_REL);
+    let groups;
+    try {
+        groups = await readdir(featuresDir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const g of groups) {
+        if (!g.isDirectory())
+            continue;
+        const groupDir = join(featuresDir, g.name);
+        let entries;
+        try {
+            entries = await readdir(groupDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!e.isFile())
+                continue;
+            if (!e.name.endsWith(".md"))
+                continue;
+            const lower = e.name.toLowerCase();
+            if (lower === "readme.md" || lower === "index.md")
+                continue;
+            out.push(join(groupDir, e.name));
+        }
+    }
+    return out.sort();
+}
+async function collectFeatureSpecs(sddPath) {
+    const out = [];
+    const domainsDir = join(sddPath, DOMAINS_DIR_REL);
+    let domains;
+    try {
+        domains = await readdir(domainsDir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const d of domains) {
+        if (!d.isDirectory())
+            continue;
+        const featuresDir = join(domainsDir, d.name, "product", "features");
+        let folders;
+        try {
+            folders = await readdir(featuresDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const f of folders) {
+            if (!f.isDirectory())
+                continue;
+            const folderPath = join(featuresDir, f.name);
+            let entries;
+            try {
+                entries = await readdir(folderPath, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const e of entries) {
+                if (!e.isFile())
+                    continue;
+                if (!e.name.endsWith(".md"))
+                    continue;
+                const lower = e.name.toLowerCase();
+                if (lower === "readme.md" || lower === "index.md")
+                    continue;
+                out.push(join(folderPath, e.name));
+            }
+        }
+    }
+    return out.sort();
+}
+function parentFolder(relPath) {
+    const parts = relPath.split(sep);
+    return parts[parts.length - 2] ?? "";
+}
+function extractH1Title(text) {
+    for (const line of text.split(/\r?\n/)) {
+        const t = line.trim();
+        if (t === "")
+            continue;
+        if (!t.startsWith("#"))
+            return "";
+        return t
+            .replace(/^#+\s*/, "")
+            .replace(/^(Feature Specification|Spec):\s*/i, "")
+            .trim();
+    }
+    return "";
+}
+//# sourceMappingURL=features.js.map