nikos 0.0.0-stage → 0.0.1

package/dist/commands/show.js

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { STORY_ID, findIntentDir, read, rel, walk } from "../lib/project.js";
+import { parseFeature, scenariosOf } from "../lint/gherkin.js";
+import { featureFor } from "./clear.js";
+import { planVersions } from "./plan.js";
+import { parseBet } from "./bet.js";
+import { decisionEntries } from "./decisions.js";
+const yamlFile = (path) => (existsSync(path) ? parse(read(path)) : undefined);
+/** Everything the intent/ folder says about one story, in plain text. */
+export function show(story, dir) {
+    if (!STORY_ID.test(story))
+        throw new Error(`'${story}' is not a story id (expected e.g. HT-1)`);
+    const intentDir = findIntentDir(dir);
+    const file = featureFor(story, dir);
+    if (!file)
+        throw new Error(`No feature file is tagged @${story}`);
+    const feature = parseFeature(read(file));
+    if (!feature)
+        throw new Error(`${rel(intentDir, file)} has no Feature`);
+    const tags = feature.tags.map((t) => t.name.slice(1));
+    const priority = tags.find((t) => ["must", "should", "could", "wont"].includes(t));
+    const effort = tags.find((t) => t.startsWith("effort-"))?.slice(7);
+    const map = yamlFile(join(intentDir, "storymap.yaml"));
+    const release = (map?.releases ?? []).find((r) => (r?.stories ?? []).includes(story));
+    const entry = yamlFile(join(intentDir, "state.yaml"))?.stories?.[story];
+    const out = [`${story} — ${feature.name}`];
+    if (entry) {
+        const extra = [entry.claimed_by && `claimed by ${entry.claimed_by}`, entry.updated && `updated ${entry.updated}`].filter(Boolean);
+        out.push(`Status: ${entry.status}${extra.length ? ` (${extra.join(", ")})` : ""}`);
+        if (entry.blockers?.length)
+            out.push(`Blockers: ${entry.blockers.join("; ")}`);
+    }
+    else {
+        out.push("Status: not in state.yaml");
+    }
+    out.push([release ? `Release ${release.number}${release.title ? ` (${release.title})` : ""}` : "Not in a release", priority, effort && `effort ${effort}`]
+        .filter(Boolean)
+        .join(" · "));
+    out.push("", `Feature: intent/${rel(intentDir, file)}`);
+    for (const line of feature.description.split("\n").map((l) => l.trim()).filter(Boolean))
+        out.push(`  ${line}`);
+    out.push("", "Scenarios:");
+    for (const s of scenariosOf(feature))
+        out.push(`  ${s.name}`);
+    const versions = planVersions(intentDir, story);
+    out.push("");
+    if (versions.length) {
+        const v = versions.at(-1);
+        const plan = parseBet(read(join(intentDir, "plans", `${story}.v${v}.md`)));
+        out.push(`Plan: v${v} (intent/plans/${story}.v${v}.md)${plan?.meta?.summary ? ` — ${plan.meta.summary}` : ""}`);
+    }
+    else {
+        out.push("Plan: none yet");
+    }
+    const bets = walk(join(intentDir, "bets"), ".md")
+        .map((p) => parseBet(read(p))?.meta)
+        .filter((m) => Array.isArray(m?.stories) && m.stories.includes(story));
+    out.push(bets.length ? `Bets: ${bets.map((b) => `${b.id} (${b.status}, ends ${b.time_box}, intent/bets/${b.id}.md)`).join(", ")}` : "Bets: none");
+    const decisions = decisionEntries(dir).filter((e) => e.title.includes(`(${story})`));
+    out.push(decisions.length ? "Decisions:" : "Decisions: none recorded for this story");
+    for (const d of decisions)
+        out.push(`  intent/decisions.md:${d.start} ${d.title}`);
+    return out.join("\n");
+}
+export function runShow(args) {
+    const [story, ...rest] = args;
+    if (!story) {
+        console.error("Usage: nikos show <story-id> [--dir <path>]");
+        return 1;
+    }
+    const i = rest.indexOf("--dir");
+    try {
+        console.log(show(story, i >= 0 ? rest[i + 1] : process.cwd()));
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/state.js

@@ -0,0 +1,104 @@
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseDocument } from "yaml";
+import { STORY_ID, findIntentDir, read } from "../lib/project.js";
+import { formatResult, validate } from "./validate.js";
+import { verify } from "./verify.js";
+/** The moves docs/format.md allows. `done` also needs the story's scenarios to pass. */
+const MOVES = {
+    todo: ["in_progress"],
+    in_progress: ["needs_rework", "done"],
+    needs_rework: ["in_progress"],
+    done: ["needs_rework"],
+};
+/** Scenario names from a cucumber-js or behave run that didn't pass. */
+export function failingScenarios(output) {
+    const names = new Set();
+    // cucumber-js: "1) Scenario: AC1 — Title # intent/features/…"
+    for (const m of output.matchAll(/^\s*\d+\) Scenario: (.+?)\s+#/gm))
+        names.add(m[1]);
+    // behave: "Failing scenarios:" then "  intent/features/…:8  AC1 — Title"
+    const behave = /Failing scenarios:\n((?:\s+\S+:\d+\s+.+\n?)+)/.exec(output);
+    if (behave)
+        for (const line of behave[1].split("\n")) {
+            const m = /^\s+\S+:\d+\s+(.+?)\s*$/.exec(line);
+            if (m)
+                names.add(m[1]);
+        }
+    return [...names];
+}
+export class StateError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+    }
+}
+export function setState(story, to, opts = {}) {
+    if (!STORY_ID.test(story))
+        throw new StateError(`'${story}' is not a story id (expected e.g. HT-1)`);
+    if (!(to in MOVES))
+        throw new StateError(`'${to}' is not a status (todo, in_progress, needs_rework, done)`);
+    const intentDir = findIntentDir(opts.dir ?? process.cwd());
+    const path = join(intentDir, "state.yaml");
+    // A Document keeps comments and the order of everything we don't touch.
+    const doc = parseDocument(read(path));
+    const from = doc.getIn(["stories", story, "status"]);
+    if (!from)
+        throw new StateError(`${story} has no entry in state.yaml`);
+    if (!MOVES[from]?.includes(to)) {
+        throw new StateError(`${story} can't move from ${from} to ${to}. From ${from} it can move to: ${MOVES[from].join(", ")}`);
+    }
+    const result = { story, from, to, failing: [] };
+    if (to === "done") {
+        let run;
+        try {
+            run = verify(dirname(intentDir), story);
+        }
+        catch (err) {
+            throw new StateError(`${story} stays ${from}: its scenarios couldn't run. ${err.message}`, result);
+        }
+        if (run.status !== 0) {
+            result.failing = failingScenarios(run.output);
+            result.output = run.output;
+            const list = result.failing.length ? `:\n${result.failing.map((s) => `  ✗ ${s}`).join("\n")}` : ". See the runner output.";
+            throw new StateError(`${story} stays ${from}: its scenarios don't all pass${list}`, result);
+        }
+        result.output = run.output;
+    }
+    doc.setIn(["stories", story, "status"], to);
+    if (opts.by && to === "in_progress")
+        doc.setIn(["stories", story, "claimed_by"], opts.by);
+    doc.setIn(["stories", story, "updated"], opts.date ?? new Date().toISOString().slice(0, 10));
+    // No padding keeps "[A-1, A-2]" as written instead of "[ A-1, A-2 ]".
+    writeFileSync(path, doc.toString({ flowCollectionPadding: false }));
+    return result;
+}
+export function runState(args) {
+    const [sub, story, to, ...rest] = args;
+    if (sub !== "set" || !story || !to) {
+        console.error("Usage: nikos state set <story-id> <todo|in_progress|needs_rework|done> [--by <name>] [--dir <path>]");
+        return 1;
+    }
+    const opt = (n) => {
+        const i = rest.indexOf(`--${n}`);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    try {
+        const r = setState(story, to, { dir: opt("dir"), by: opt("by") });
+        console.log(`${r.story}: ${r.from} → ${r.to}`);
+    }
+    catch (err) {
+        const e = err;
+        if (e.result?.output && !e.result.failing.length)
+            console.error(e.result.output);
+        console.error(`✗ ${e.message}`);
+        return 1;
+    }
+    const v = validate(opt("dir") ?? process.cwd());
+    if (v.errors.length) {
+        console.error(formatResult(v));
+        return 1;
+    }
+    return 0;
+}

package/dist/commands/validate.js

@@ -0,0 +1,206 @@
+import Ajv2020Module from "ajv/dist/2020.js";
+const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
+import { existsSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+import { lintFeature } from "../lint/gherkin.js";
+import { lintConstitution } from "../lint/constitution.js";
+import { parseBet } from "./bet.js";
+import { featureStoryIds, findIntentDir, read, rel, walk } from "../lib/project.js";
+const here = dirname(fileURLToPath(import.meta.url));
+// Works from src/ (tests) and dist/ (published): schemas sit at the package root.
+const schemaDir = [join(here, "../../schemas"), join(here, "../schemas")].find((d) => existsSync(d));
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const checkStorymap = ajv.compile(JSON.parse(read(join(schemaDir, "storymap.schema.json"))));
+const checkState = ajv.compile(JSON.parse(read(join(schemaDir, "state.schema.json"))));
+const checkBet = ajv.compile(JSON.parse(read(join(schemaDir, "bet.schema.json"))));
+function pointer(e) {
+    return e.instancePath.replace(/^\//, "").split("/").filter(Boolean).join(".") || "(root)";
+}
+function describe(e, data) {
+    const at = pointer(e);
+    const value = e.instancePath
+        .split("/")
+        .filter(Boolean)
+        .reduce((v, k) => (v == null ? v : v[k]), data);
+    switch (e.keyword) {
+        case "enum":
+            return `${at} '${value}' is not one of ${e.params.allowedValues.join(", ")}`;
+        case "const":
+            return `${at} must be ${JSON.stringify(e.params.allowedValue)}`;
+        case "required":
+            return `${at === "(root)" ? "" : at + ": "}missing required field '${e.params.missingProperty}'`;
+        case "additionalProperties":
+            return `${at === "(root)" ? "" : at + ": "}unknown field '${e.params.additionalProperty}'`;
+        case "pattern":
+            return `${at} '${value}' is not in the expected format`;
+        case "propertyNames":
+            return `${at}: '${e.params.propertyName}' is not a valid story id (expected e.g. HT-1)`;
+        default:
+            return `${at} ${e.message}`;
+    }
+}
+function loadYaml(dir, name, issues) {
+    const path = join(dir, name);
+    if (!existsSync(path)) {
+        issues.push({ file: name, message: "file is missing", hint: "run `nikos init` to create it" });
+        return undefined;
+    }
+    try {
+        return parse(read(path));
+    }
+    catch (err) {
+        issues.push({ file: name, message: `is not valid YAML: ${err.message.split("\n")[0]}` });
+        return undefined;
+    }
+}
+export function validate(start) {
+    const dir = findIntentDir(start);
+    const errors = [];
+    const warnings = [];
+    const storymap = loadYaml(dir, "storymap.yaml", errors);
+    const state = loadYaml(dir, "state.yaml", errors);
+    if (storymap !== undefined && !checkStorymap(storymap)) {
+        for (const e of checkStorymap.errors ?? []) {
+            errors.push({ file: "storymap.yaml", message: describe(e, storymap) });
+        }
+    }
+    if (state !== undefined && !checkState(state)) {
+        for (const e of checkState.errors ?? []) {
+            // propertyNames also reports the inner pattern failure; the propertyNames message covers it.
+            if (e.keyword === "pattern" && e.propertyName)
+                continue;
+            errors.push({ file: "state.yaml", message: describe(e, state) });
+        }
+    }
+    // Cross-file checks only when both files parsed into objects.
+    const mapStories = new Map();
+    const activityIds = new Set();
+    if (storymap && typeof storymap === "object") {
+        for (const a of storymap.activities ?? [])
+            activityIds.add(a?.id);
+        const numbers = [];
+        for (const r of storymap.releases ?? []) {
+            numbers.push(r?.number);
+            for (const id of r?.stories ?? []) {
+                if (mapStories.has(id)) {
+                    errors.push({ file: "storymap.yaml", message: `${id} appears in more than one release`, hint: "keep each story in exactly one release" });
+                }
+                mapStories.set(id, r.number);
+                if (storymap.key && typeof id === "string" && !id.startsWith(`${storymap.key}-`)) {
+                    errors.push({ file: "storymap.yaml", message: `${id} doesn't use the project key '${storymap.key}'` });
+                }
+            }
+        }
+        const sorted = [...numbers].filter((n) => typeof n === "number").sort((a, b) => a - b);
+        if (sorted.some((n, i) => n !== i + 1)) {
+            errors.push({ file: "storymap.yaml", message: `release numbers must start at 1 with no gaps (found ${sorted.join(", ")})` });
+        }
+    }
+    const constitutionPath = join(dir, "constitution.md");
+    if (existsSync(constitutionPath)) {
+        for (const issue of lintConstitution(read(constitutionPath))) {
+            (issue.level === "error" ? errors : warnings).push({ file: "constitution.md", message: issue.message, hint: issue.hint });
+        }
+    }
+    // Features
+    const featureIds = new Map();
+    for (const path of walk(join(dir, "features"), ".feature")) {
+        const file = rel(dir, path);
+        const text = read(path);
+        for (const issue of lintFeature(text)) {
+            (issue.level === "error" ? errors : warnings).push({ file, message: issue.message, hint: issue.hint });
+        }
+        const ids = featureStoryIds(text);
+        if (ids.length === 0) {
+            errors.push({ file, message: "has no story id tag", hint: "add a tag like @HT-1 above `Feature:`" });
+            continue;
+        }
+        if (ids.length > 1) {
+            errors.push({ file, message: `has more than one story id tag (${ids.join(", ")})`, hint: "one feature file per story" });
+        }
+        const id = ids[0];
+        if (featureIds.has(id)) {
+            errors.push({ file, message: `${id} already has a feature file (${featureIds.get(id)})` });
+        }
+        featureIds.set(id, file);
+        const activity = basename(dirname(path));
+        if (activityIds.size && !activityIds.has(activity)) {
+            errors.push({ file, message: `is in folder '${activity}', which is not an activity in storymap.yaml` });
+        }
+        if (storymap && !mapStories.has(id)) {
+            errors.push({ file, message: `${id} is not in any release in storymap.yaml` });
+        }
+    }
+    const stateStories = (state && typeof state === "object" && state.stories) || {};
+    if (storymap && state) {
+        for (const id of mapStories.keys()) {
+            if (!featureIds.has(id)) {
+                errors.push({ file: "storymap.yaml", message: `${id} has no feature file`, hint: `add intent/features/<activity>/<slug>.feature tagged @${id}` });
+            }
+            if (!(id in stateStories)) {
+                errors.push({ file: "state.yaml", message: `${id} is in storymap.yaml but has no entry under stories`, hint: `add "${id}: { status: todo }"` });
+            }
+        }
+        for (const id of Object.keys(stateStories)) {
+            if (!mapStories.has(id)) {
+                errors.push({ file: "state.yaml", message: `stories.${id} is an unknown story id`, hint: "add it to a release in storymap.yaml or remove it" });
+            }
+        }
+        for (const id of state.run?.queue ?? []) {
+            if (!mapStories.has(id))
+                errors.push({ file: "state.yaml", message: `run.queue has unknown story id ${id}` });
+        }
+    }
+    // Bets: schema, id matches the file name, and every linked story is in the story map.
+    for (const path of walk(join(dir, "bets"), ".md")) {
+        const file = rel(dir, path);
+        let bet;
+        try {
+            bet = parseBet(read(path));
+        }
+        catch (err) {
+            errors.push({ file, message: `front matter isn't valid YAML: ${err.message.split("\n")[0]}` });
+            continue;
+        }
+        if (!bet) {
+            errors.push({ file, message: "has no front matter", hint: "create bets with `nikos bet new`" });
+            continue;
+        }
+        if (!checkBet(bet.meta)) {
+            for (const e of checkBet.errors ?? [])
+                errors.push({ file, message: describe(e, bet.meta) });
+            continue;
+        }
+        if (bet.meta.id !== basename(path, ".md")) {
+            errors.push({ file, message: `id '${bet.meta.id}' doesn't match the file name`, hint: `rename the file to bets/${bet.meta.id}.md` });
+        }
+        if (storymap) {
+            for (const id of bet.meta.stories) {
+                if (!mapStories.has(id))
+                    errors.push({ file, message: `links ${id}, which is not in storymap.yaml` });
+            }
+        }
+    }
+    return { dir, errors, warnings, stories: mapStories.size, releases: storymap?.releases?.length ?? 0 };
+}
+export function formatResult(r) {
+    const lines = [];
+    for (const e of r.errors)
+        lines.push(`✗ ${e.file}: ${e.message}${e.hint ? `\n    → ${e.hint}` : ""}`);
+    for (const w of r.warnings)
+        lines.push(`! ${w.file}: ${w.message}${w.hint ? `\n    → ${w.hint}` : ""}`);
+    if (r.errors.length === 0) {
+        lines.push(`✓ intent/ is valid — ${r.stories} ${r.stories === 1 ? "story" : "stories"}, ${r.releases} ${r.releases === 1 ? "release" : "releases"}`);
+    }
+    else {
+        lines.push(`\n${r.errors.length} ${r.errors.length === 1 ? "problem" : "problems"} found.`);
+    }
+    return lines.join("\n");
+}
+export function runValidate(args) {
+    const r = validate(args[0] ?? process.cwd());
+    console.log(formatResult(r));
+    return r.errors.length ? 1 : 0;
+}

package/dist/commands/verify.js

@@ -0,0 +1,95 @@
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { walk } from "../lib/project.js";
+import { detectStack } from "../verify/detect.js";
+import { featureFor } from "./clear.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const templateDir = [join(here, "../../templates/verify"), join(here, "../templates/verify")].find((d) => existsSync(d));
+const INSTALL = {
+    js: "npm install --save-dev @cucumber/cucumber@^12",
+    ts: "npm install --save-dev @cucumber/cucumber@^12 tsx",
+    python: "pip install behave",
+};
+const CONFIG = { js: "cucumber.mjs", ts: "cucumber.mjs", python: "behave.ini" };
+function stackOrThrow(root) {
+    const stack = detectStack(root);
+    if (!stack)
+        throw new Error("Couldn't tell the stack: no package.json, pyproject.toml or requirements.txt. Ask which runner to use.");
+    return stack;
+}
+/** Write the runner config and step stubs for the repo's stack. Never overwrites a file. */
+export function setupVerify(root) {
+    const stack = stackOrThrow(root);
+    const src = join(templateDir, stack === "python" ? "python" : stack);
+    const created = [];
+    const skipped = [];
+    // Step stubs are for the example story `nikos init` creates; skip them once it's gone.
+    const hasExample = existsSync(join(root, "intent/features/getting-started/first-story.feature"));
+    for (const file of walk(src)) {
+        const rel = relative(src, file);
+        if (!hasExample && /first[-_]story/.test(rel))
+            continue;
+        const dest = join(root, rel);
+        if (existsSync(dest)) {
+            skipped.push(rel);
+            continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(file, dest);
+        created.push(rel);
+    }
+    return { stack, created, skipped, install: INSTALL[stack] };
+}
+/** Run the story's scenarios (or all of them) with the repo's Cucumber runner. */
+export function verify(root, story, opts = {}) {
+    const stack = stackOrThrow(root);
+    if (!existsSync(join(root, CONFIG[stack])))
+        throw new Error(`No ${CONFIG[stack]} yet. Run \`nikos verify setup\` first.`);
+    // cucumber-js and behave both run zero scenarios and exit 0 for a tag that matches nothing.
+    if (story && !featureFor(story, root))
+        throw new Error(`No feature file is tagged @${story}`);
+    let cmd;
+    let args;
+    const env = { ...process.env };
+    if (stack === "python") {
+        cmd = process.env.PYTHON ?? "python3";
+        args = ["-m", "behave", ...(story ? [`--tags=@${story}`] : [])];
+    }
+    else {
+        cmd = join(root, "node_modules/.bin/cucumber-js");
+        if (!existsSync(cmd))
+            throw new Error(`cucumber-js isn't installed. Run: ${INSTALL[stack]}`);
+        args = story ? ["--tags", `@${story}`] : [];
+        // tsx lets Node versions without built-in type stripping load .ts step files.
+        if (stack === "ts")
+            env.NODE_OPTIONS = `${env.NODE_OPTIONS ?? ""} --import tsx`.trim();
+    }
+    const r = spawnSync(cmd, args, { cwd: root, env, encoding: "utf8", stdio: opts.inherit ? "inherit" : "pipe" });
+    if (r.error)
+        throw new Error(`Couldn't run ${cmd}: ${r.error.message}. Run: ${INSTALL[stack]}`);
+    return { stack, command: [cmd, ...args].join(" "), status: r.status ?? 1, output: `${r.stdout ?? ""}${r.stderr ?? ""}` };
+}
+export function runVerify(args) {
+    const i = args.indexOf("--dir");
+    const root = i >= 0 ? args[i + 1] : process.cwd();
+    const positional = args.filter((a, n) => a !== "--dir" && (i < 0 || n !== i + 1));
+    try {
+        if (positional[0] === "setup") {
+            const r = setupVerify(root);
+            console.log(`Stack: ${r.stack}`);
+            if (r.created.length)
+                console.log(`Created:\n${r.created.map((f) => `  + ${f}`).join("\n")}`);
+            if (r.skipped.length)
+                console.log(`Skipped (already there):\n${r.skipped.map((f) => `  = ${f}`).join("\n")}`);
+            console.log(`\nNext: ${r.install}\nThen: nikos verify <story-id>`);
+            return 0;
+        }
+        return verify(root, positional[0], { inherit: true }).status;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/lib/project.js

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+export const STORY_ID = /^[A-Z][A-Z0-9]{0,9}-[0-9]+$/;
+/** Resolve the intent/ folder from a repo root or the folder itself. */
+export function findIntentDir(start) {
+    if (existsSync(join(start, "storymap.yaml")))
+        return start;
+    return join(start, "intent");
+}
+export function walk(dir, ext) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).flatMap((f) => {
+        const p = join(dir, f);
+        if (statSync(p).isDirectory())
+            return walk(p, ext);
+        return !ext || p.endsWith(ext) ? [p] : [];
+    });
+}
+export function read(path) {
+    return readFileSync(path, "utf8");
+}
+export function rel(dir, path) {
+    return relative(dir, path) || path;
+}
+/** Story id tags on the lines above `Feature:`. */
+export function featureStoryIds(text) {
+    const ids = [];
+    for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (t.startsWith("Feature:"))
+            break;
+        if (!t.startsWith("@"))
+            continue;
+        for (const tag of t.split(/\s+/)) {
+            const name = tag.replace(/^@/, "");
+            if (STORY_ID.test(name))
+                ids.push(name);
+        }
+    }
+    return ids;
+}

package/dist/lint/constitution.js

@@ -0,0 +1,40 @@
+import { parse } from "yaml";
+/** The five vision sections every constitution has, in this order (docs/format.md). */
+export const VISION_SECTIONS = ["Users", "Problem", "Switch", "First", "Proof"];
+/** Check constitution.md has its front matter and the five vision sections, in order and filled in. */
+export function lintConstitution(text) {
+    const issues = [];
+    const m = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    let body = text;
+    if (!m) {
+        issues.push({ level: "error", message: "has no front matter", hint: "start with ---, name: and idea:, then ---" });
+    }
+    else {
+        body = text.slice(m[0].length);
+        let meta = {};
+        try {
+            meta = parse(m[1]) ?? {};
+        }
+        catch (err) {
+            issues.push({ level: "error", message: `front matter isn't valid YAML: ${err.message.split("\n")[0]}` });
+        }
+        for (const key of ["name", "idea"]) {
+            if (typeof meta[key] !== "string" || !meta[key].trim())
+                issues.push({ level: "error", message: `front matter is missing '${key}'` });
+        }
+    }
+    // Split into "## Heading" sections; anything before the first heading is ignored.
+    const sections = [...body.matchAll(/^## (.+)\n([\s\S]*?)(?=^## |(?![\s\S]))/gm)].map((s) => ({ title: s[1].trim(), text: s[2].trim() }));
+    const titles = sections.map((s) => s.title);
+    const missing = VISION_SECTIONS.filter((t) => !titles.includes(t));
+    if (missing.length) {
+        issues.push({ level: "error", message: `is missing ${missing.map((t) => `## ${t}`).join(", ")}`, hint: `the five vision sections are ${VISION_SECTIONS.join(", ")}` });
+    }
+    else if (VISION_SECTIONS.some((t, i) => titles[i] !== t)) {
+        issues.push({ level: "error", message: `vision sections are out of order (${titles.slice(0, 5).join(", ")})`, hint: `put ${VISION_SECTIONS.join(", ")} first, in that order; extra sections go after` });
+    }
+    for (const s of sections.filter((s) => VISION_SECTIONS.includes(s.title) && !s.text)) {
+        issues.push({ level: "error", message: `## ${s.title} is empty` });
+    }
+    return issues;
+}

package/dist/lint/gherkin.js

@@ -0,0 +1,99 @@
+import { AstBuilder, GherkinClassicTokenMatcher, Parser } from "@cucumber/gherkin";
+import { IdGenerator } from "@cucumber/messages";
+import { STORY_ID } from "../lib/project.js";
+/** Tags that describe progress, which belongs in state.yaml, not the spec. */
+const STATUS_TAGS = /^@(todo|done|wip|in[-_]?progress|doing|blocked|needs[-_]?rework|ready|review|approved|complete[d]?|skip|pending)$/i;
+const PRIORITY = /^@(must|should|could)$/;
+const AC_TAG = /^@AC\d+$/;
+const KNOWN_FEATURE_TAG = [STORY_ID, /^release-\d+$/, /^(must|should|could)$/, /^activity-[a-z0-9-]+$/, /^effort-(XS|S|M|L|XL)$/];
+function parser() {
+    return new Parser(new AstBuilder(IdGenerator.uuid()), new GherkinClassicTokenMatcher());
+}
+/** Parse a feature file. Throws on invalid Gherkin. */
+export function parseFeature(text) {
+    return parser().parse(text).feature;
+}
+/** Every scenario in a feature, including those inside Rules. */
+export function scenariosOf(feature) {
+    return feature.children.flatMap((c) => (c.scenario ? [c.scenario] : c.rule ? c.rule.children.flatMap((rc) => (rc.scenario ? [rc.scenario] : [])) : []));
+}
+export function lintFeature(text) {
+    const issues = [];
+    const featureLines = text.split("\n").filter((l) => /^\s*Feature:/.test(l)).length;
+    if (featureLines > 1) {
+        issues.push({ level: "error", message: `has ${featureLines} Features`, hint: "one Feature per file, one file per story" });
+    }
+    let doc;
+    try {
+        doc = parser().parse(text);
+    }
+    catch (err) {
+        issues.push({ level: "error", message: `isn't valid Gherkin: ${err.message.split("\n")[0]}` });
+        return issues;
+    }
+    const feature = doc.feature;
+    if (!feature) {
+        issues.push({ level: "error", message: "has no Feature", hint: "start the file with a story id tag and `Feature: <title>`" });
+        return issues;
+    }
+    const tags = feature.tags.map((t) => t.name);
+    for (const tag of tags) {
+        if (STATUS_TAGS.test(tag)) {
+            issues.push({ level: "error", message: `uses status tag ${tag}`, hint: "status lives in state.yaml, not in the feature" });
+        }
+        else if (!KNOWN_FEATURE_TAG.some((re) => re.test(tag.slice(1)))) {
+            issues.push({ level: "warning", message: `has unrecognised tag ${tag}`, hint: "allowed: story id, @release-N, @must/@should/@could, @activity-<id>, @effort-<size>" });
+        }
+    }
+    if (tags.filter((t) => PRIORITY.test(t)).length !== 1) {
+        issues.push({ level: "error", message: "needs exactly one priority tag on the Feature", hint: "add @must, @should or @could" });
+    }
+    if (!tags.some((t) => /^@release-\d+$/.test(t))) {
+        issues.push({ level: "error", message: "has no @release-N tag" });
+    }
+    const desc = feature.description ?? "";
+    // "As a", "As an" and "As the" all name a role; I want and So that are fixed.
+    const parts = [["As a", /^\s*As (?:an?|the)\s+\S/im], ["I want", /^\s*I want\b/im], ["So that", /^\s*So that\b/im]];
+    const missing = parts.filter(([, re]) => !re.test(desc)).map(([label]) => label);
+    if (missing.length) {
+        issues.push({
+            level: "error",
+            message: `user story is missing ${missing.map((m) => `"${m}"`).join(", ")}`,
+            hint: "put As a … / I want … / So that … on separate lines under Feature:",
+        });
+    }
+    const scenarios = scenariosOf(feature);
+    if (scenarios.length === 0) {
+        issues.push({ level: "warning", message: "has no scenarios yet", hint: "add one Scenario per acceptance criterion" });
+    }
+    const labels = new Set();
+    for (const s of scenarios) {
+        const sTags = s.tags.map((t) => t.name);
+        const ac = sTags.find((t) => AC_TAG.test(t));
+        for (const tag of sTags) {
+            if (STATUS_TAGS.test(tag)) {
+                issues.push({ level: "error", message: `scenario "${s.name}" uses status tag ${tag}`, hint: "status lives in state.yaml, not in the feature" });
+            }
+        }
+        if (!ac) {
+            issues.push({ level: "error", message: `scenario "${s.name}" has no @AC<n> tag`, hint: "tag each scenario with its criterion label, e.g. @AC1" });
+            continue;
+        }
+        if (labels.has(ac))
+            issues.push({ level: "error", message: `${ac} is used by more than one scenario` });
+        labels.add(ac);
+        if (!s.name.startsWith(`${ac.slice(1)} `)) {
+            issues.push({ level: "warning", message: `scenario "${s.name}" should start with its label`, hint: `e.g. "${ac.slice(1)} — ${s.name}"` });
+        }
+        if (sTags.filter((t) => PRIORITY.test(t)).length > 1) {
+            issues.push({ level: "error", message: `scenario "${s.name}" has more than one priority tag` });
+        }
+        // Given is optional (a scenario can start from nothing); When and Then are not.
+        const keywords = new Set(s.steps.map((st) => st.keyword.trim()));
+        for (const k of ["When", "Then"]) {
+            if (!keywords.has(k))
+                issues.push({ level: "error", message: `scenario "${s.name}" has no ${k} step` });
+        }
+    }
+    return issues;
+}