worldvm 0.0.0-stage → 0.1.0

package/dist/lints.d.ts

@@ -0,0 +1,8 @@
+import type { WorldIR } from "./_internal/forma/world/index.js";
+import type { CliDiagnostic } from "./project.js";
+import type { SourceText } from "./refine.js";
+/**
+ * Authoring lints for silent semantic traps. They run in the CLI only, never in the
+ * compiler, so compiled IR and lab goldens are unaffected.
+ */
+export declare const authoringLints: (ir: WorldIR, files: readonly SourceText[]) => CliDiagnostic[];

package/dist/lints.js

@@ -0,0 +1,154 @@
+import { catalogueEntry } from "./catalogue.js";
+/** Every expression a component or decision evaluates, with its owning component. */
+const roots = (ir) => {
+    const out = [];
+    const add = (component, expr, conjunctive = false) => {
+        if (expr)
+            out.push({ component, expr, conjunctive });
+    };
+    for (const c of ir.components) {
+        for (const r of c.requirements) {
+            add(c.name, r.appliesWhen);
+            add(c.name, r.satisfiedBy);
+            add(c.name, r.due);
+        }
+        for (const a of c.actions)
+            for (const n of a.needs)
+                add(c.name, n.expr, true);
+        for (const i of c.invariants)
+            add(c.name, i.while);
+        for (const m of c.milestones ?? [])
+            add(c.name, m.when);
+        for (const h of c.holds ?? [])
+            add(c.name, h.while);
+    }
+    for (const d of ir.decisions ?? [])
+        add(d.of, d.when);
+    return out;
+};
+const sourceOf = (files, at) => files.find((f) => f.id === at.src)?.text.slice(at.from, at.to);
+/**
+ * A requirement nobody can advance that applies when a fact has a particular value only
+ * detects that state. Suggest the invariant that would reject the labelled write instead.
+ */
+const detectOnly = (ir, files) => {
+    const out = [];
+    for (const c of ir.components) {
+        if (c.invariants.length)
+            continue;
+        const advanced = new Set(c.actions.flatMap((a) => (Array.isArray(a.advances) ? a.advances : [a.advances])));
+        for (const r of c.requirements) {
+            if (advanced.has(r.name) || !r.appliesWhen)
+                continue;
+            let found;
+            visit(r.appliesWhen, (call) => {
+                if (found || call.fn !== "=" || call.args.length !== 2)
+                    return;
+                const fact = call.args.find((a) => a.k === "attr" || a.k === "read");
+                const kw = call.args.find((a) => a.k === "kw");
+                if (fact?.meta?.path && kw?.v)
+                    found = { path: fact.meta.path, value: kw.v };
+            });
+            if (!found)
+                continue;
+            const [subject, ...fields] = found.path.split(".");
+            const guard = sourceOf(files, r.satisfiedBy.at) ?? "<condition>";
+            const kind = `set-${fields.join("-")}`;
+            const name = `guard-${r.name}`;
+            out.push({
+                code: "I_DETECT_ONLY",
+                severity: "info",
+                message: `${c.name}/${r.name} flags ${found.path} = :${found.value} after it is written; nothing prevents the write.`,
+                at: r.at,
+                help: `If the write should be blocked rather than flagged, add an invariant and label the write with its kind:\n  (invariant ${name}\n    :forbids (action-kind :${kind} :subject ${subject})\n    :while (not ${guard}))\nA scenario then checks it with (set alias :${fields.join(".")} :${found.value} :kind :${kind} :subject alias :by someone) and (expect (rejected 1) :${name}). Only writes submitted as commands with that kind are checked; Unknown conditions admit the write.`,
+                fix: null,
+            });
+        }
+    }
+    return out;
+};
+/** Visit call nodes, tracking whether an all? encloses them. */
+const visit = (e, f, inAll = false) => {
+    if (!e || typeof e !== "object")
+        return;
+    if (Array.isArray(e)) {
+        e.forEach((x) => visit(x, f, inAll));
+        return;
+    }
+    const node = e;
+    if (node.k === "call")
+        f(node, inAll);
+    const nested = inAll || (node.k === "call" && node.fn === "all?");
+    for (const [key, child] of Object.entries(node))
+        if (key !== "at")
+            visit(child, f, nested);
+};
+const headFix = (files, at, from, to) => {
+    const text = files.find((f) => f.id === at.src)?.text;
+    if (!text)
+        return null;
+    const m = /^\(\s*/.exec(text.slice(at.from, at.to));
+    if (!m)
+        return null;
+    const start = at.from + m[0].length;
+    return text.slice(start, start + from.length) === from
+        ? { src: at.src, from: start, to: start + from.length, text: to, expected: from }
+        : null;
+};
+const warning = (code, message, at, help, fix) => ({
+    code,
+    severity: "warning",
+    message,
+    at,
+    help: help || catalogueEntry(code).fix,
+    fix,
+});
+/** Whether every member of a local output can be NotApplicable at once. */
+const mayBeNotApplicable = (component, name, seen = new Set()) => {
+    if (seen.has(name))
+        return false;
+    seen.add(name);
+    const requirement = component.requirements.find((r) => r.name === name);
+    if (requirement)
+        return !!requirement.appliesWhen;
+    const output = component.outputs.find((o) => o.name === name);
+    return (!!output?.paths.length &&
+        output.paths.every((p) => p.segments.length === 1 && mayBeNotApplicable(component, p.segments[0], seen)));
+};
+/**
+ * Authoring lints for silent semantic traps. They run in the CLI only, never in the
+ * compiler, so compiled IR and lab goldens are unaffected.
+ */
+export const authoringLints = (ir, files) => {
+    const out = [];
+    const seen = new Set();
+    const components = new Map(ir.components.map((c) => [c.name, c]));
+    const once = (d) => {
+        const key = `${d.code}@${d.at?.src}:${d.at?.from}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push(d);
+        }
+    };
+    for (const { component, expr, conjunctive } of roots(ir))
+        visit(expr, (call, inAll) => {
+            const arg = call.args[0];
+            if (call.fn === "satisfied?") {
+                const name = arg?.k === "var"
+                    ? arg.name
+                    : arg?.k === "inst" && arg.of.k === "var" && arg.of.name === "self"
+                        ? arg.field
+                        : undefined;
+                const owner = components.get(component);
+                const requirement = owner?.requirements.find((r) => r.name === name);
+                const output = owner?.outputs.find((o) => o.name === name);
+                const fix = headFix(files, call.at, "satisfied?", "met?");
+                if (requirement?.appliesWhen && (inAll || conjunctive))
+                    once(warning("W_SATISFIED_NOT_APPLICABLE", `(satisfied? ${name}) is false whenever ${name} is NotApplicable, so this conjunction cannot hold when ${name} does not apply.`, call.at, `Use (met? ${name}) (Satisfied, Waived or NotApplicable), or group the requirements in an (output name (all-of … ${name})) and read it with (met? self.name).`, fix));
+                if (output && owner && mayBeNotApplicable(owner, output.name))
+                    once(warning("W_SATISFIED_NOT_APPLICABLE", `(satisfied? ${call.args[0]?.k === "inst" ? "self." : ""}${name}) is false when every member of output ${name} is NotApplicable, because the output is then NotApplicable too.`, call.at, `all-of ignores NotApplicable members but is itself NotApplicable when all of them are. Use (met? ${call.args[0]?.k === "inst" ? "self." : ""}${name}) if "nothing applies" should count as met.`, fix));
+            }
+        }, false);
+    out.push(...detectOnly(ir, files));
+    return out;
+};

package/dist/lsp.d.ts

@@ -0,0 +1,14 @@
+interface Position {
+    line: number;
+    character: number;
+}
+export declare const positionAt: (text: string, offset: number) => Position;
+/** Stateful, transport-independent LSP session. Notifications are emitted through send. */
+export declare const createLspServer: (send: (message: unknown) => void) => {
+    handle: (message: unknown) => Promise<unknown>;
+    readonly exited: boolean;
+    readonly shutdown: boolean;
+};
+/** LSP uses Content-Length byte framing, unlike MCP's newline-delimited transport. */
+export declare const serveLsp: (input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream) => Promise<void>;
+export {};

package/dist/lsp.js

@@ -0,0 +1,380 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, resolve, relative, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { formatForma, readForma } from "./_internal/forma-tools/index.js";
+import { TOP_LEVEL_FORMS, CHILD_FORMS, coreDiagnostics } from "./_internal/forma/world/index.js";
+import { compileProject, loadProject } from "./project.js";
+import { explain } from "./catalogue.js";
+export const positionAt = (text, offset) => {
+    const before = text.slice(0, Math.max(0, Math.min(offset, text.length)));
+    const lines = before.split("\n");
+    return { line: lines.length - 1, character: lines.at(-1).length };
+};
+const offsetAt = (text, p) => {
+    const lines = text.split("\n");
+    return (lines.slice(0, p.line).reduce((n, line) => n + line.length + 1, 0) +
+        Math.min(p.character, lines[p.line]?.length ?? 0));
+};
+const rangeAt = (text, from, to) => ({
+    start: positionAt(text, from),
+    end: positionAt(text, to),
+});
+const uriFor = (project, src) => pathToFileURL(resolve(project.directory, src)).href;
+const idFor = (directory, path) => relative(directory, path).split(sep).join("/");
+/** A source directory is the fallback for standalone documents. Prefer the nearest ancestor
+ * with an account header so library/scenario subdirectories see their sibling sources.
+ * A library-only project uses its nearest library header. */
+const projectRoot = async (path) => {
+    const fallback = dirname(path);
+    let directory = fallback;
+    let library = null;
+    while (true) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && !entry.name.startsWith(".") && entry.name.endsWith(".forma")) {
+                const text = await readFile(resolve(directory, entry.name), "utf8");
+                const heads = readForma(text)
+                    .forms.filter((f) => f.kind === "List")
+                    .map((f) => f.children.find((c) => c.kind !== "Comment")?.text);
+                if (heads.includes("account"))
+                    return directory;
+                if (!library && heads.includes("library"))
+                    library = directory;
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return library ?? fallback;
+        directory = parent;
+    }
+};
+const declarationKinds = new Set([
+    ...TOP_LEVEL_FORMS,
+    "requirement",
+    "action",
+    "output",
+    "invariant",
+]);
+const declarations = (project) => {
+    const result = [];
+    for (const file of project.files) {
+        const visit = (nodes, owner, top) => {
+            for (const node of nodes) {
+                if (node.kind !== "List")
+                    continue;
+                const atoms = node.children.filter((c) => c.kind !== "Comment");
+                const head = atoms[0]?.text ?? "", name = atoms[1];
+                if (name?.kind === "Atom" &&
+                    !name.text.startsWith('"') &&
+                    declarationKinds.has(head) &&
+                    (top || owner !== null)) {
+                    result.push({
+                        name: name.text,
+                        kind: head,
+                        owner,
+                        uri: uriFor(project, file.id),
+                        range: rangeAt(file.text, name.from, name.to),
+                    });
+                }
+                if (head === "component")
+                    visit(atoms.slice(2), name?.text ?? null, false);
+            }
+        };
+        visit(readForma(file.text).forms, null, true);
+    }
+    return result;
+};
+const atomAt = (text, offset) => {
+    const visit = (nodes, owner) => {
+        for (const node of nodes) {
+            if (offset < node.from || offset > node.to)
+                continue;
+            if (node.kind === "Atom")
+                return { atom: node, owner, head: false };
+            if (node.kind === "Comment")
+                return null;
+            const children = node.children.filter((c) => c.kind !== "Comment");
+            const found = visit(node.children, children[0]?.text === "component" ? (children[1]?.text ?? owner) : owner);
+            if (found)
+                return {
+                    ...found,
+                    head: found.head || (node.kind === "List" && found.atom === children[0]),
+                };
+        }
+        return null;
+    };
+    return visit(readForma(text).forms, null);
+};
+/** Stateful, transport-independent LSP session. Notifications are emitted through send. */
+export const createLspServer = (send) => {
+    const documents = new Map();
+    const published = new Map();
+    let core = false;
+    let shutdown = false, exited = false;
+    const projectFor = async (uri) => {
+        const path = fileURLToPath(uri), directory = await projectRoot(path);
+        const disk = await loadProject(directory);
+        const files = new Map(disk.files.map((f) => [f.id, f.text]));
+        for (const [openUri, doc] of documents) {
+            const id = idFor(directory, fileURLToPath(openUri));
+            if (id !== ".." && !id.startsWith("../") && id.endsWith(".forma"))
+                files.set(id, doc.text);
+        }
+        return compileProject(directory, [...files].sort(([a], [b]) => a.localeCompare(b)).map(([id, text]) => ({ id, text })));
+    };
+    const publish = async (uri) => {
+        const project = await projectFor(uri);
+        const uris = new Set([
+            uri,
+            ...project.files.map((f) => uriFor(project, f.id)),
+            ...(published.get(project.directory) ?? []),
+        ]);
+        published.set(project.directory, new Set(project.files.map((f) => uriFor(project, f.id))));
+        for (const target of uris) {
+            const file = project.files.find((f) => uriFor(project, f.id) === target);
+            const diagnostics = [...project.diagnostics, ...(core ? coreDiagnostics(project.files) : [])]
+                .filter((d) => (d.at ? uriFor(project, d.at.src) === target : target === uri))
+                .map((d) => ({
+                range: rangeAt(file?.text ?? "", d.at?.from ?? 0, d.at?.to ?? 0),
+                severity: { error: 1, warning: 2, info: 3 }[d.severity],
+                code: d.code,
+                source: "worldvm",
+                message: `${d.message}\n${d.help}`,
+            }));
+            send({
+                jsonrpc: "2.0",
+                method: "textDocument/publishDiagnostics",
+                params: {
+                    uri: target,
+                    ...(documents.has(target) ? { version: documents.get(target).version } : {}),
+                    diagnostics,
+                },
+            });
+        }
+    };
+    const handle = async (message) => {
+        const req = message;
+        if (!req || req.jsonrpc !== "2.0" || typeof req.method !== "string")
+            return { jsonrpc: "2.0", id: null, error: { code: -32600, message: "Invalid request." } };
+        const reply = (result) => "id" in req ? { jsonrpc: "2.0", id: req.id, result } : null;
+        const error = (code, message) => "id" in req ? { jsonrpc: "2.0", id: req.id, error: { code, message } } : null;
+        try {
+            if (req.method === "exit") {
+                exited = true;
+                return null;
+            }
+            if (req.method === "initialize") {
+                core =
+                    req.params
+                        ?.initializationOptions?.core === true;
+                return reply({
+                    capabilities: {
+                        positionEncoding: "utf-16",
+                        textDocumentSync: { openClose: true, change: 1 },
+                        hoverProvider: true,
+                        completionProvider: { triggerCharacters: ["(", ":", ".", "/"] },
+                        definitionProvider: true,
+                        codeActionProvider: true,
+                        documentFormattingProvider: true,
+                    },
+                    serverInfo: { name: "worldvm", version: "0.0.0" },
+                });
+            }
+            if (req.method === "shutdown") {
+                shutdown = true;
+                return reply(null);
+            }
+            if (shutdown)
+                return error(-32600, "Server has shut down.");
+            if (["initialized", "$/cancelRequest", "$/setTrace"].includes(req.method))
+                return null;
+            if (![
+                "textDocument/didOpen",
+                "textDocument/didChange",
+                "textDocument/didClose",
+                "textDocument/formatting",
+                "textDocument/codeAction",
+                "textDocument/completion",
+                "textDocument/hover",
+                "textDocument/definition",
+            ].includes(req.method))
+                return error(-32601, `Unsupported method ${req.method}.`);
+            const params = (req.params ?? {});
+            const uri = params.textDocument?.uri;
+            if (!uri || !uri.startsWith("file:"))
+                return error(-32602, "Expected a file URI.");
+            if (req.method === "textDocument/didOpen") {
+                documents.set(uri, {
+                    text: params.textDocument.text ?? "",
+                    version: params.textDocument.version ?? 0,
+                });
+                await publish(uri);
+                return null;
+            }
+            if (req.method === "textDocument/didChange") {
+                const current = documents.get(uri), version = params.textDocument.version ?? 0;
+                if (!current || version <= current.version)
+                    return null;
+                const changes = params.contentChanges ?? [];
+                if (changes.some((c) => c.range))
+                    return error(-32602, "Only full document sync is supported.");
+                if (changes.length)
+                    documents.set(uri, { text: changes.at(-1).text, version });
+                await publish(uri);
+                return null;
+            }
+            if (req.method === "textDocument/didClose") {
+                documents.delete(uri);
+                send({
+                    jsonrpc: "2.0",
+                    method: "textDocument/publishDiagnostics",
+                    params: { uri, diagnostics: [] },
+                });
+                // Recompile with disk contents and refresh other open documents in the project.
+                const project = await projectFor(uri);
+                for (const openUri of documents.keys())
+                    if (project.files.some((f) => uriFor(project, f.id) === openUri)) {
+                        await publish(openUri);
+                        break;
+                    }
+                return null;
+            }
+            const text = documents.get(uri)?.text ?? (await readFile(fileURLToPath(uri), "utf8"));
+            if (req.method === "textDocument/formatting")
+                return reply([{ range: rangeAt(text, 0, text.length), newText: formatForma(text) }]);
+            const project = await projectFor(uri);
+            if (req.method === "textDocument/codeAction") {
+                const requested = params.range ?? rangeAt(text, 0, text.length);
+                const from = offsetAt(text, requested.start), to = offsetAt(text, requested.end);
+                return reply(project.diagnostics.flatMap((d) => {
+                    if (!d.fix ||
+                        !d.at ||
+                        uriFor(project, d.at.src) !== uri ||
+                        d.at.to < from ||
+                        d.at.from > to)
+                        return [];
+                    const fix = d.fix, file = project.files.find((f) => f.id === fix.src);
+                    if (!file || file.text.slice(fix.from, fix.to) !== fix.expected)
+                        return [];
+                    const target = uriFor(project, fix.src);
+                    return [
+                        {
+                            title: `Fix ${d.code}: ${d.help}`,
+                            kind: "quickfix",
+                            edit: {
+                                documentChanges: [
+                                    {
+                                        textDocument: {
+                                            uri: target,
+                                            version: documents.get(target)?.version ?? null,
+                                        },
+                                        edits: [{ range: rangeAt(file.text, fix.from, fix.to), newText: fix.text }],
+                                    },
+                                ],
+                            },
+                        },
+                    ];
+                }));
+            }
+            const symbols = declarations(project);
+            if (req.method === "textDocument/completion")
+                return reply([
+                    ...[...new Set([...TOP_LEVEL_FORMS, ...[...CHILD_FORMS.values()].flat()])].map((label) => ({ label, kind: 14, detail: "Forma form" })),
+                    ...symbols.map((d) => ({
+                        label: d.name,
+                        kind: 6,
+                        detail: `${d.kind}${d.owner ? ` in ${d.owner}` : ""}`,
+                    })),
+                ]);
+            if (!params.position)
+                return error(-32602, "Expected position.");
+            const offset = offsetAt(text, params.position);
+            const found = atomAt(text, offset);
+            if (req.method === "textDocument/hover") {
+                const word = found?.atom.text ??
+                    (text.slice(0, offset).match(/[\w/-]*$/)?.[0] ?? "") +
+                        (text.slice(offset).match(/^[\w/-]*/)?.[0] ?? "");
+                const entry = explain(word);
+                const parents = [...CHILD_FORMS]
+                    .filter(([, children]) => children.includes(word))
+                    .map(([parent]) => parent);
+                const form = TOP_LEVEL_FORMS.includes(word)
+                    ? `Top-level Forma form: (${word} …).`
+                    : parents.length
+                        ? `Forma child form: (${word} …), inside ${parents.join(", ")}.`
+                        : null;
+                return reply(entry || form
+                    ? {
+                        contents: { kind: "plaintext", value: entry ?? form },
+                        ...(found ? { range: rangeAt(text, found.atom.from, found.atom.to) } : {}),
+                    }
+                    : null);
+            }
+            if (req.method === "textDocument/definition") {
+                if (!found || found.head || found.atom.text.startsWith('"'))
+                    return reply(null);
+                const name = found.atom.text.replace(/^self\./, "");
+                const candidates = symbols.filter((d) => d.name === name ||
+                    `${d.owner}/${d.name}` === name ||
+                    name.endsWith(`/${d.name}`) ||
+                    name === `${d.owner}.${d.name}`);
+                const local = candidates.filter((d) => d.owner && d.owner === found.owner);
+                return reply((local.length ? local : candidates).map((d) => ({ uri: d.uri, range: d.range })));
+            }
+            return error(-32601, `Unsupported method ${req.method}.`);
+        }
+        catch (cause) {
+            return error(-32603, String(cause));
+        }
+    };
+    return {
+        handle,
+        get exited() {
+            return exited;
+        },
+        get shutdown() {
+            return shutdown;
+        },
+    };
+};
+/** LSP uses Content-Length byte framing, unlike MCP's newline-delimited transport. */
+export const serveLsp = async (input = process.stdin, output = process.stdout) => {
+    const send = (message) => {
+        const body = JSON.stringify(message);
+        output.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+    };
+    const server = createLspServer(send);
+    let buffer = Buffer.alloc(0);
+    for await (const chunk of input) {
+        buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+        while (true) {
+            const end = buffer.indexOf("\r\n\r\n");
+            if (end < 0)
+                break;
+            const length = /^Content-Length:\s*(\d+)\s*$/im.exec(buffer.subarray(0, end).toString("ascii"));
+            if (!length || Number(length[1]) > 16 * 1024 * 1024)
+                throw new Error("Invalid LSP Content-Length.");
+            const size = Number(length[1]);
+            if (buffer.length < end + 4 + size)
+                break;
+            const body = buffer.subarray(end + 4, end + 4 + size).toString("utf8");
+            buffer = buffer.subarray(end + 4 + size);
+            let message;
+            try {
+                message = JSON.parse(body);
+            }
+            catch {
+                send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error." } });
+                continue;
+            }
+            const response = await server.handle(message);
+            if (response !== null)
+                send(response);
+            if (server.exited) {
+                if (input === process.stdin && !server.shutdown)
+                    process.exitCode = 1;
+                return;
+            }
+        }
+    }
+};

package/dist/manual/catalog.d.ts

@@ -0,0 +1,12 @@
+import type { Component, Requirement, Span, WorldIR } from "../_internal/forma/world/index.js";
+export interface RequirementCard {
+    readonly id: string;
+    readonly component: Component;
+    readonly requirement: Requirement;
+    readonly at: Span;
+}
+export declare const requirementCards: (ir: WorldIR) => readonly RequirementCard[];
+/** Account reachability is structural, not a claim about an individual worker's applicability. */
+export declare const accountComponents: (ir: WorldIR, account: string) => ReadonlySet<string>;
+export declare const contains: (at: Span, src: string, offset: number) => boolean;
+export declare const cardAt: (cards: readonly RequirementCard[], src: string, offset: number) => RequirementCard | undefined;

package/dist/manual/catalog.js

@@ -0,0 +1,23 @@
+export const requirementCards = (ir) => ir.components.flatMap((component) => component.requirements.map((requirement) => ({
+    id: `${component.name}/${requirement.name}`,
+    component,
+    requirement,
+    at: requirement.at,
+})));
+/** Account reachability is structural, not a claim about an individual worker's applicability. */
+export const accountComponents = (ir, account) => {
+    const names = new Set();
+    const visit = (name) => {
+        if (names.has(name))
+            return;
+        names.add(name);
+        for (const slot of ir.components.find((c) => c.name === name)?.slots ?? [])
+            visit(slot.component);
+    };
+    ir.accounts.find((a) => a.name === account)?.forEach.forEach((r) => visit(r.component));
+    return names;
+};
+export const contains = (at, src, offset) => at.src === src && at.from <= offset && offset < at.to;
+export const cardAt = (cards, src, offset) => cards
+    .filter((c) => contains(c.at, src, offset))
+    .sort((a, b) => a.at.to - a.at.from - (b.at.to - b.at.from))[0];

package/dist/manual/examples.d.ts

@@ -0,0 +1,15 @@
+import type { Span, WorldIR } from "../_internal/forma/world/index.js";
+export interface ExampleAssertion {
+    readonly kind: "status" | "due";
+    readonly text: string;
+    readonly at: Span;
+    readonly date: string;
+}
+export interface RequirementExample {
+    readonly name: string;
+    readonly doc: string;
+    readonly at: Span;
+    readonly assertions: readonly ExampleAssertion[];
+    readonly referenceOnly: boolean;
+}
+export declare const requirementExamples: (ir: WorldIR, component: string, requirement: string, references: readonly string[]) => readonly RequirementExample[];

package/dist/manual/examples.js

@@ -0,0 +1,39 @@
+export const requirementExamples = (ir, component, requirement, references) => references
+    .flatMap((name) => {
+    const scenario = ir.scenarios?.find((s) => s.name === name);
+    if (!scenario)
+        return [];
+    const assertions = scenario.steps
+        .flatMap((step) => step.expects.flatMap((expectation) => {
+        if (!["status", "due"].includes(expectation.kind) ||
+            !("target" in expectation) ||
+            !("name" in expectation) ||
+            expectation.target.component !== component ||
+            expectation.name !== requirement)
+            return [];
+        const kind = expectation.kind, value = expectation.expected === null ? "unknown" : String(expectation.expected);
+        return [
+            {
+                kind,
+                text: `expect ${requirement} ${kind} ${value} · ${expectation.at.src}:${expectation.at.line}`,
+                at: expectation.at,
+                date: step.date,
+            },
+        ];
+    }))
+        .sort((a, b) => Number(b.kind === "due") - Number(a.kind === "due"));
+    return [
+        {
+            name,
+            doc: scenario.doc ?? scenario.name,
+            at: scenario.at,
+            assertions,
+            referenceOnly: !assertions.length,
+        },
+    ];
+})
+    .sort((a, b) => Number(b.assertions.some((x) => x.kind === "due")) -
+    Number(a.assertions.some((x) => x.kind === "due")) ||
+    Number(a.referenceOnly) - Number(b.referenceOnly) ||
+    b.assertions.length - a.assertions.length ||
+    a.name.localeCompare(b.name));