sfora-cli 0.9.0 → 0.11.0

package/dist/format/blocks/dropClosure.js

@@ -0,0 +1,196 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// The drop ledger: every byte a structured-block parser throws away, signed
+// for.
+//
+// A block parser is a filter — it keeps the lines it understands and returns
+// the rest as nothing at all — so "the block rendered" has never been evidence
+// that everything in it did. The parsers now report what they consumed and
+// what they dropped (see `BlockAccounting` in ./parsers), and this file is the
+// other half of that contract: a closed inventory in which every drop reason
+// carries a verdict, a rationale, and a witness that RUNS.
+//
+// The four verdicts are open-knowledge's, and the discipline they encode is
+// that "lossy" is not one thing:
+//
+//   structural-only     the bytes carry no content — a blank line, a container
+//   format-dof-axis     the bytes are one spelling of a thing we keep; the
+//                       axis id names WHICH degree of freedom, and it is an id
+//                       from `../formatAxes` rather than a phrase — that file
+//                       is the finite list, and it carries the DISCRIMINATION
+//                       witness that proves the two spellings mean one thing.
+//                       Not a round-trip witness, which is what this line used
+//                       to call it: a discrimination witness shows the two
+//                       spellings parse alike and that the capture layer can
+//                       tell them apart, and says nothing about whether either
+//                       survives a save. `formatAxes.ts`'s replay scoreboard is
+//                       where that question is answered, and for most axes the
+//                       answer today is no
+//   retained-by-capture the bytes are gone from the line but present in the
+//                       parsed data, and `retained` says exactly where
+//   documented-residual real loss, admitted, witnessed. These — and only
+//                       these — are what lint tells an author about.
+//
+// Closure is checked in both directions. TypeScript proves no reason is
+// unadjudicated (the ledger is a total Record over the reason union); the
+// suite in __tests__/blockDropClosure.test.ts proves no entry is stale, that
+// every witness still provokes its drop, and that consumed plus dropped
+// accounts for every line of every fixture.
+export const BLOCK_DROP_ADJUDICATIONS = {
+    "blank-line": {
+        kind: "structural-only",
+        witness: {
+            lang: "chat",
+            source: "- @mara: on it\n\n- @ada: shipping\n",
+            dropped: "",
+        },
+        rationale: "the block grammars are line-based and read one entry per line, so a blank line separates nothing and carries nothing",
+    },
+    "block-unread": {
+        kind: "retained-by-capture",
+        witness: {
+            lang: "sheet",
+            source: "this is not a table\n",
+            dropped: "this is not a table",
+        },
+        retained: "the rendered code fence",
+        rationale: "a parser that returns null is the renderer's signal to draw a plain code fence, so every byte of an unreadable block stays on screen and copyable — the loss is the STRUCTURE, never the text",
+    },
+    "entry-bullet-marker": {
+        kind: "format-dof-axis",
+        axisIds: ["structured-block:entry-bullet"],
+        partial: true,
+        witness: {
+            lang: "chat",
+            source: "* @mara: on it\n",
+            dropped: "*",
+        },
+        rationale: "a status or chat entry may be authored bare, with `-`, or with `*`; all three render identically, so which one was typed is a spelling the entry-bullet axis owns rather than content",
+    },
+    "status:unsigned-line": {
+        kind: "documented-residual",
+        witnesses: [
+            {
+                lang: "status",
+                source: "state: building\n- @ada: on it\njust a loose note\n",
+                dropped: "just a loose note",
+            },
+        ],
+        rationale: "a status entry is `[time] @actor: message`; a line that is neither that nor the `state:` header has no field to land in, and the timeline would have to invent an author to show it",
+    },
+    "board:unparsed-line": {
+        kind: "documented-residual",
+        witnesses: [
+            {
+                lang: "board",
+                source: "## Todo\n- [ ] item one\nThis note vanishes\n",
+                dropped: "This note vanishes",
+            },
+        ],
+        rationale: "a board block holds column headings and cards; prose between them belongs to neither and there is no column to hang it under",
+    },
+    "chat:unparsed-line": {
+        kind: "documented-residual",
+        witnesses: [
+            {
+                lang: "chat",
+                source: "- @mara: on it\nplain note with no speaker\n",
+                dropped: "plain note with no speaker",
+            },
+        ],
+        rationale: "a chat entry is signed — `@actor: message` — and an unsigned line cannot be attributed without putting words in someone's mouth",
+    },
+    "sheet:non-row-line": {
+        kind: "documented-residual",
+        witnesses: [
+            {
+                lang: "sheet",
+                source: "| A | B |\n| --- | --- |\n| 1 | 2 |\njust a note\n",
+                dropped: "just a note",
+            },
+        ],
+        rationale: "GFM makes the outer pipes optional, so a row is a line carrying a pipe that would split it; a line with no unescaped, un-code-spanned pipe is not a row and has no cells",
+    },
+    "sheet:delimiter-row": {
+        kind: "retained-by-capture",
+        witness: {
+            lang: "sheet",
+            source: "| A | B |\n| --- | ---: |\n| 1 | 2 |\n",
+            dropped: "| --- | ---: |",
+        },
+        retained: "SheetData.columns[].alignment",
+        rationale: "the delimiter row is alignment, not data; its colons are read into every column and its dashes have nothing else to say",
+    },
+    "sheet:excess-cells": {
+        kind: "documented-residual",
+        partial: true,
+        witnesses: [
+            {
+                lang: "sheet",
+                source: "| A | B |\n| --- | --- |\n| 1 | 2 | 3 |\n",
+                dropped: "3",
+            },
+        ],
+        rationale: "a table is as wide as its header row, exactly as GFM has it — a cell past the last column is not a column a reader sees, and widening the table on its behalf would move every other cell",
+    },
+    "map:unparsed-line": {
+        kind: "documented-residual",
+        witnesses: [
+            {
+                lang: "map",
+                source: "destination: Ship it\n- [ ] Chart the first question\na stray note\n",
+                dropped: "a stray note",
+            },
+            {
+                // Only the FIRST destination line is the header; a second one is not a
+                // ticket either, so it falls here.
+                lang: "map",
+                source: "destination: Ship it\ndestination: Ship it twice\n- [ ] Chart it\n",
+                dropped: "destination: Ship it twice",
+            },
+        ],
+        rationale: "a map block holds one destination header and tickets in the wayfinder line grammar; anything else has no node to draw",
+    },
+};
+/**
+ * True when the drop takes the whole line with it. A partial drop happened on
+ * a line that rendered anyway — the bullet marker in front of a chat entry,
+ * the cells past the end of a sheet's header — and must NOT be subtracted from
+ * the consumed set.
+ */
+export function isWholeLineDrop(reason) {
+    return BLOCK_DROP_ADJUDICATIONS[reason].partial !== true;
+}
+/**
+ * True when an author should hear about the drop. Only a documented residual
+ * is real loss; the other three verdicts say the bytes were structure, a
+ * spelling, or captured elsewhere, and a diagnostic for those would be noise
+ * on a block that rendered exactly as written.
+ */
+export function isReportableDrop(reason) {
+    return BLOCK_DROP_ADJUDICATIONS[reason].kind === "documented-residual";
+}
+/** Every witness in the ledger, flattened, with the reason it belongs to. */
+export function dropWitnesses() {
+    const out = [];
+    for (const key of Object.keys(BLOCK_DROP_ADJUDICATIONS)) {
+        const entry = BLOCK_DROP_ADJUDICATIONS[key];
+        const witnesses = entry.kind === "documented-residual" ? entry.witnesses : [entry.witness];
+        for (const witness of witnesses)
+            out.push({ reason: key, witness });
+    }
+    return out;
+}
+/**
+ * Close the ledger against what the parsers actually did. `observed` is every
+ * reason seen across the whole fixture corpus — one document's drops are never
+ * enough to close anything.
+ */
+export function checkDropClosure(observed) {
+    const seen = new Set(observed);
+    const adjudicated = Object.keys(BLOCK_DROP_ADJUDICATIONS);
+    return {
+        unadjudicated: [...seen].filter((r) => !adjudicated.includes(r)).sort(),
+        stale: adjudicated.filter((r) => !seen.has(r)).sort(),
+    };
+}

package/dist/format/blocks/markdown-block-catalog.d.ts

@@ -0,0 +1,18 @@
+import { MARKDOWN_BLOCK_IDS } from "./markdown-block-ids.mjs";
+export { MARKDOWN_BLOCK_IDS };
+export type MarkdownBlockId = (typeof MARKDOWN_BLOCK_IDS)[number];
+export interface MarkdownBlockSpec {
+    id: MarkdownBlockId;
+    label: string;
+    group: "Text" | "Structure" | "Rich blocks" | "References" | "Recovery";
+    description: string;
+    source: string;
+    renderMermaid?: boolean;
+    interactiveTasks?: boolean;
+}
+declare const POST_ID = "post000000000000000000000001";
+declare const CARD_ID = "card000000000000000000000001";
+export declare const MARKDOWN_BLOCK_CATALOG: readonly MarkdownBlockSpec[];
+export declare function getMarkdownBlockSpec(id?: string): MarkdownBlockSpec | undefined;
+export declare const MARKDOWN_BLOCK_FIXTURE_IDS: `markdown-block-${string}`[];
+export { CARD_ID as MARKDOWN_FIXTURE_CARD_ID, POST_ID as MARKDOWN_FIXTURE_POST_ID };

package/dist/format/blocks/markdown-block-catalog.js

@@ -0,0 +1,162 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+import { MARKDOWN_BLOCK_IDS } from "./markdown-block-ids.mjs";
+export { MARKDOWN_BLOCK_IDS };
+const POST_ID = "post000000000000000000000001";
+const CARD_ID = "card000000000000000000000001";
+export const MARKDOWN_BLOCK_CATALOG = [
+    {
+        id: "typography",
+        label: "Typography",
+        group: "Text",
+        description: "Heading hierarchy and document rhythm.",
+        source: "# Document title\n\n## Section heading\n\n### Supporting heading\n\nA paragraph owns the primary reading measure. A second sentence proves wrapping and vertical rhythm without creating another surface.",
+    },
+    {
+        id: "inline-formatting",
+        label: "Inline formatting",
+        group: "Text",
+        description: "Emphasis, code, mentions, and links in one line flow.",
+        source: "Use **strong emphasis**, *considered emphasis*, ~~retired work~~, and `pnpm design:check` without disrupting the baseline. @[Mara Voss](member-mara) can review the [design evidence](https://developer.apple.com/design/human-interface-guidelines/).",
+    },
+    {
+        id: "lists",
+        label: "Lists",
+        group: "Structure",
+        description: "Sibling items remain one semantic run.",
+        source: "- Preserve the reading datum\n- Keep sibling items together\n- Use a boundary only when the object earns one\n\n1. Inspect the real route\n2. Capture compact and desktop\n3. Judge the rendered result",
+    },
+    {
+        id: "tasks",
+        label: "Task list",
+        group: "Structure",
+        description: "Interactive and completed task states.",
+        source: "- [x] Inventory the canonical blocks\n- [ ] Verify compact overflow\n- [ ] Review dark-mode boundaries",
+        interactiveTasks: true,
+    },
+    {
+        id: "quote",
+        label: "Quote",
+        group: "Structure",
+        description: "Quoted context is subordinate but still readable.",
+        source: "> The document is the primary field.\n> Controls explain state without competing with the argument.",
+    },
+    {
+        id: "callout",
+        label: "Callout",
+        group: "Structure",
+        description: "An aside earns a tinted surface, never a colored bar.",
+        source: "> [!NOTE]\n> A callout is a blockquote with a type marker, so it stays readable everywhere markdown is read.\n\n> [!WARNING] Run the migration first\n> The deploy assumes the new stage columns already exist.",
+    },
+    {
+        id: "divider",
+        label: "Divider",
+        group: "Structure",
+        description: "A quiet transition between related passages.",
+        source: "The evidence ends here.\n\n---\n\nThe decision begins on the same reading field.",
+    },
+    {
+        id: "table",
+        label: "Table",
+        group: "Structure",
+        description: "Aligned data with compact horizontal recovery.",
+        source: "| Route | State | Owner | Last review |\n| --- | :---: | --- | ---: |\n| Home | Ready | Product | Today |\n| Library workbench | Review | Design systems | Yesterday |\n| Post reader | Ready | Documents | 2 days |",
+    },
+    {
+        id: "code",
+        label: "Code block",
+        group: "Structure",
+        description: "Monospace source, syntax color, copy action, and overflow.",
+        source: "```typescript\ntype SurfaceRole = \"primary\" | \"grouped\" | \"module\"\n\nexport function ownsBoundary(role: SurfaceRole) {\n  return role === \"module\"\n}\n```",
+    },
+    {
+        id: "image",
+        label: "Image",
+        group: "Structure",
+        description: "Authored media keeps its alternative text and document measure.",
+        source: "![Sfora application icon](/sfora-icon.png)",
+    },
+    {
+        id: "mermaid",
+        label: "Mermaid",
+        group: "Rich blocks",
+        description: "Expandable diagram evidence inside the document flow.",
+        source: "```mermaid\nflowchart LR\n  Source[Markdown source] --> Parse[Canonical parser]\n  Parse --> Reader[Reader]\n  Parse --> Editor[Editor]\n  Reader --> Capture[Visual acceptance]\n```",
+        renderMermaid: true,
+    },
+    {
+        id: "summary-cards",
+        label: "Summary cards",
+        group: "Rich blocks",
+        description: "Legacy digest summaries resolve into one grouped surface.",
+        source: "- **Design graph is live** — Thijs Verreck\n> Every rendered state is now addressable from the system graph.\n- **Compact review passed** — Dogfood Bot\n> The reading hierarchy survives the narrow viewport.",
+    },
+    {
+        id: "status",
+        label: "Status timeline",
+        group: "Rich blocks",
+        description: "Current state followed by signed chronological updates.",
+        source: "```status #run\nstate: building\n- 2026-08-13T09:02Z integrator: renderer inventory complete\n- 2026-08-13T09:18Z reviewer: compact capture is ready\n```",
+    },
+    {
+        id: "board",
+        label: "Board",
+        group: "Rich blocks",
+        description: "Compact work columns with stable narrow-screen overflow.",
+        source: "```board #tickets\n## In progress\n- [ ] Fix status anatomy\n- [ ] Verify card references\n## Review\n- [ ] Inspect compact overflow\n## Done\n- [x] Build the state graph\n```",
+    },
+    {
+        id: "chat",
+        label: "Conversation",
+        group: "Rich blocks",
+        description: "Attributed messages remain sibling rows.",
+        source: "```chat #general\n- 2026-08-13T09:04Z @integrator (agent): the renderer matrix is live\n- @Alexandra Very Long Operator Name (reviewer): the reference evidence is attached and the compact reading order remains intact\n- 2026-08-13T09:11Z @Mara: review the dark-mode boundary next\n```",
+    },
+    {
+        id: "sheet",
+        label: "Data sheet",
+        group: "Rich blocks",
+        description: "Structured rows and columns with one owning frame.",
+        source: "```sheet #coverage\n| Block | Reader | Editor | Compact |\n| --- | --- | --- | --- |\n| Status | Ready | Ready | Review |\n| Board | Ready | Ready | Ready |\n| References | Review | Ready | Ready |\n```",
+    },
+    {
+        id: "map",
+        label: "Map",
+        group: "Rich blocks",
+        description: "Decision tickets and their blocking edges, drawn as the route to a destination.",
+        source: "```map #launch\ndestination: A locked launch checklist\n- [x] Name the destination\n- [~] Pick the payment provider (research) <- Name the destination\n- [ ] Do we need a waitlist page? (prototype) <- Name the destination\n- [ ] Settle the seat model <- Pick the payment provider, Do we need a waitlist page?\n- [-] Native mobile app\n```",
+    },
+    {
+        id: "post-reference",
+        label: "Post reference",
+        group: "References",
+        description: "A linked post previews before canonical navigation.",
+        source: `[[${POST_ID}|The reader becomes one intentional work surface]]`,
+    },
+    {
+        id: "card-reference",
+        label: "Card reference",
+        group: "References",
+        description: "A linked task exposes state and project context.",
+        source: `[[c:${CARD_ID}|Audit every rendered Markdown block]]`,
+    },
+    {
+        id: "unknown-reference",
+        label: "Unknown reference",
+        group: "Recovery",
+        description: "Unresolved work remains visibly unavailable and does not imply navigation.",
+        source: "The evidence points to [[missing000000000000000000001|a post that is no longer available]].",
+    },
+    {
+        id: "malformed-structured",
+        label: "Malformed structured source",
+        group: "Recovery",
+        description: "Invalid enhanced Markdown remains visible and copyable.",
+        source: "```sheet #broken\nthis is not a valid table\nand the source must not disappear\n```",
+    },
+];
+export function getMarkdownBlockSpec(id) {
+    return MARKDOWN_BLOCK_CATALOG.find((block) => block.id === id);
+}
+export const MARKDOWN_BLOCK_FIXTURE_IDS = MARKDOWN_BLOCK_IDS.map((id) => `markdown-block-${id}`);
+export { CARD_ID as MARKDOWN_FIXTURE_CARD_ID, POST_ID as MARKDOWN_FIXTURE_POST_ID };

package/dist/format/blocks/markdown-block-ids.d.mts

@@ -0,0 +1 @@
+export const MARKDOWN_BLOCK_IDS: string[];

package/dist/format/blocks/markdown-block-ids.mjs

@@ -0,0 +1,25 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+export const MARKDOWN_BLOCK_IDS = [
+    "typography",
+    "inline-formatting",
+    "lists",
+    "tasks",
+    "quote",
+    "callout",
+    "divider",
+    "table",
+    "code",
+    "image",
+    "mermaid",
+    "summary-cards",
+    "status",
+    "board",
+    "chat",
+    "sheet",
+    "map",
+    "post-reference",
+    "card-reference",
+    "unknown-reference",
+    "malformed-structured",
+];

package/dist/format/blocks/parsers.d.ts

@@ -0,0 +1,105 @@
+import { type WayfinderMap } from "../wayfinder.js";
+import { type BlockDropReason } from "./dropClosure.js";
+import type { StructuredBlockLanguage } from "./structured-block-schema.js";
+export interface TimelineEntry {
+    time?: string;
+    actor: string;
+    message: string;
+    /**
+     * A `state:` line AFTER the header one: a state change, rendered as a
+     * marker row rather than a signed update. `actor` is empty for these.
+     */
+    kind?: "state";
+}
+export interface ChatEntry extends TimelineEntry {
+    role?: string;
+}
+export interface BoardColumn {
+    title: string;
+    items: Array<{
+        state: string;
+        text: string;
+    }>;
+}
+export type SheetAlignment = "left" | "center" | "right";
+export interface SheetData {
+    columns: Array<{
+        label: string;
+        alignment: SheetAlignment;
+    }>;
+    rows: string[][];
+}
+export interface TimelineData {
+    state?: string;
+    entries: TimelineEntry[];
+}
+export declare function cleanLines(source: string): string[];
+/** Bytes a parser did not keep. `line` indexes the block body, 0-based. */
+export interface BlockDrop {
+    line: number;
+    /** The dropped text, trimmed. Empty for a blank line. */
+    text: string;
+    reason: BlockDropReason;
+}
+/**
+ * What a parse produced and what it cost. `consumed` and the whole-line drops
+ * partition the body's lines exactly — that is the closure the fixture suite
+ * asserts, and the reason a parser can no longer quietly widen what it ignores.
+ */
+export interface BlockAccounting<T> {
+    data: T | null;
+    /** Body line indices that reached the rendered block, ascending. */
+    consumed: number[];
+    drops: BlockDrop[];
+}
+export declare function parseTimelineWithAccounting(source: string): BlockAccounting<TimelineData>;
+export declare function parseTimeline(source: string): TimelineData | null;
+/**
+ * True for a line parseBoard keeps: a column heading or a card. A convenience
+ * for callers holding one line — the parser's own accounting is what lint and
+ * the closure suite read, so this is never the second opinion.
+ */
+export declare function isBoardLine(line: string): boolean;
+export declare function parseBoardWithAccounting(source: string): BlockAccounting<BoardColumn[]>;
+export declare function parseBoard(source: string): BoardColumn[] | null;
+export declare function parseChatWithAccounting(source: string): BlockAccounting<ChatEntry[]>;
+export declare function parseChat(source: string): ChatEntry[] | null;
+/**
+ * True for a line parseSheet reads as a table row. GFM makes the outer pipes
+ * optional, so the test is "carries a pipe that would split it" — an escaped
+ * or code-spanned pipe is content, not structure.
+ */
+export declare function isSheetRow(line: string): boolean;
+export declare function parseSheetWithAccounting(source: string): BlockAccounting<SheetData>;
+export declare function parseSheet(source: string): SheetData | null;
+/**
+ * True for a line parseMapBlock keeps: the destination header or a ticket in
+ * the wayfinder line grammar. Same standing as {@link isBoardLine} — a
+ * convenience, not the authority.
+ */
+export declare function isMapLine(line: string): boolean;
+/**
+ * Parse a ```map block: an optional `destination:` header, then tickets in
+ * the wayfinder line grammar (`- [~] Name (type) <- Blocker`). Null when no
+ * ticket parses — the renderer's signal to fall back to a visible code fence,
+ * same contract as every other structured block.
+ */
+export declare function parseMapBlockWithAccounting(source: string): BlockAccounting<WayfinderMap>;
+/**
+ * Parse a ```map block: an optional `destination:` header, then tickets in
+ * the wayfinder line grammar (`- [~] Name (type) <- Blocker`). Null when no
+ * ticket parses — the renderer's signal to fall back to a visible code fence,
+ * same contract as every other structured block.
+ */
+export declare function parseMapBlock(source: string): WayfinderMap | null;
+/**
+ * Parse a fence body as the block its language names, with the ledger. The
+ * one door lint and the closure suite use, so neither carries its own table of
+ * which parser reads which language.
+ */
+export declare function parseStructuredBlock(language: StructuredBlockLanguage, source: string): BlockAccounting<unknown>;
+/**
+ * Body line indices whose bytes did not survive the parse at all. Partial
+ * drops are excluded by construction — their line rendered.
+ */
+export declare function droppedLineNumbers(accounting: BlockAccounting<unknown>): number[];