sfora-cli 0.10.0 → 0.12.0

package/dist/format/formatAxes.js

@@ -0,0 +1,454 @@
+/**
+ * The list. Sorted by id, because a list nobody can scan is not reviewable and
+ * reviewable is the entire point.
+ */
+export const FORMAT_AXES = [
+    {
+        id: "blank-lines:doc-edge",
+        layer: "blank-runs",
+        dataKeys: ["sourceEdgeBlankLines"],
+        rationale: "blank runs at the document's own two ends; `emitMarkdown` strips the terminator and writes no leading run, so without the plan an author's deliberate breathing room at the top or bottom of a body is gone on the first save",
+        witnesses: [
+            {
+                a: "A",
+                b: "A\n\n\n",
+                note: "a bare body against one with a trailing blank run",
+            },
+        ],
+    },
+    {
+        id: "blank-lines:interior",
+        layer: "blank-runs",
+        dataKeys: ["sourceBlankLinesBefore"],
+        rationale: "how many blank lines the author left between two root blocks; mdast-util-to-markdown writes exactly one and mdast has no field for the rest, so a double gap used as a section break closes on every save",
+        witnesses: [
+            {
+                a: "A\n\nB",
+                b: "A\n\n\nB",
+                note: "one blank line between two paragraphs against two",
+            },
+        ],
+    },
+    {
+        id: "block-gap:after-heading",
+        layer: "mdast-geometry",
+        captures: ["heading.sourceContiguousNext"],
+        rationale: "whether a heading is followed by a blank line before its first block; remark writes one unconditionally, so without this axis every contiguous heading in a document reflows on the first save",
+        witnesses: [
+            {
+                a: "# T\nbody",
+                b: "# T\n\nbody",
+                note: "the gap between the heading and the paragraph under it",
+            },
+        ],
+    },
+    {
+        id: "blockquote:marker-spacing",
+        layer: "mdast-geometry",
+        captures: ["blockquote.sourceMarkerSpacings"],
+        rationale: "how many spaces followed each `>`; CommonMark strips one and the rest are the author's, per line",
+        witnesses: [
+            {
+                a: "> q",
+                b: ">q",
+                note: "one space after the marker against none",
+            },
+        ],
+    },
+    {
+        id: "code-block:style",
+        layer: "mdast-geometry",
+        captures: ["code.sourceStyle"],
+        rationale: "fenced against indented; the same four lines of code, spelled two ways that CommonMark reads identically",
+        witnesses: [
+            {
+                a: "```\nx\n```",
+                b: "    x",
+                note: "a fence against a four-space indent — the widest spelling gap on the list",
+            },
+        ],
+    },
+    {
+        id: "code-fence:char",
+        layer: "mdast-geometry",
+        captures: ["code.sourceFenceChar"],
+        rationale: "backtick against tilde; the choice matters to an author whose body contains the other one",
+        witnesses: [
+            {
+                a: "```\nx\n```",
+                b: "~~~\nx\n~~~",
+                note: "the fence character",
+            },
+        ],
+    },
+    {
+        id: "code-fence:info-padding",
+        layer: "mdast-geometry",
+        captures: ["code.sourceInfoPadding"],
+        rationale: "spaces between the fence and its info string; CommonMark discards them and some authors line their fences up with them",
+        witnesses: [
+            {
+                a: "```ts\nx\n```",
+                b: "```   ts\nx\n```",
+                note: "the gap before the language",
+            },
+        ],
+    },
+    {
+        id: "code-fence:length",
+        layer: "mdast-geometry",
+        captures: ["code.sourceFenceLength"],
+        rationale: "how many fence characters; three is the minimum and more is a deliberate widening around a body that contains a closer-shaped line",
+        witnesses: [
+            {
+                a: "```\nx\n```",
+                b: "````\nx\n````",
+                note: "three characters against four",
+            },
+        ],
+    },
+    {
+        id: "definition:layout",
+        layer: "mdast-geometry",
+        captures: ["definition.sourceLayout"],
+        rationale: "whether a link reference definition sits on one line or wraps after the colon",
+        witnesses: [
+            {
+                a: "[a]: u",
+                b: "[a]:\n  u",
+                note: "the destination on the label's line against the line below it",
+            },
+        ],
+    },
+    {
+        id: "definition:title-quote",
+        layer: "mdast-geometry",
+        captures: ["definition.sourceTitleMarker"],
+        rationale: "which of the three title containers a definition used — `\"`, `'` or `()`",
+        witnesses: [
+            {
+                a: '[a]: u "t"',
+                b: "[a]: u 't'",
+                note: "double quotes against single",
+            },
+        ],
+    },
+    {
+        id: "emphasis:delimiter",
+        layer: "mdast-geometry",
+        captures: ["emphasis.sourceDelimiter"],
+        rationale: "`*` against `_` for a single-delimiter emphasis run",
+        witnesses: [
+            { a: "*em*", b: "_em_", note: "the delimiter character" },
+        ],
+    },
+    {
+        id: "hard-break:style",
+        layer: "mdast-geometry",
+        captures: ["break.sourceStyle"],
+        rationale: "a hard break spelled as a trailing backslash or as two trailing spaces; one of them is invisible in every editor ever written",
+        witnesses: [
+            {
+                a: "a\\\nb",
+                b: "a  \nb",
+                note: "backslash against two spaces",
+            },
+        ],
+    },
+    {
+        id: "heading:style",
+        layer: "mdast-geometry",
+        captures: ["heading.sourceStyle"],
+        rationale: "atx (`# T`) against setext (`T` over `=`); the same heading, and the only two spellings CommonMark has for depth one and two",
+        witnesses: [
+            {
+                a: "# T",
+                b: "T\n=",
+                note: "atx against setext — moves the underline length with it, which is the next axis's business",
+            },
+        ],
+    },
+    {
+        id: "heading:trailing-hashes",
+        layer: "mdast-geometry",
+        captures: ["heading.sourceTrailingHashes"],
+        rationale: "the optional closing run on an atx heading, which CommonMark discards entirely",
+        witnesses: [
+            { a: "# T", b: "# T #", note: "the closing hash" },
+        ],
+    },
+    {
+        id: "inline-code:fence-length",
+        layer: "mdast-geometry",
+        captures: ["inlineCode.sourceFenceLength"],
+        rationale: "how many backticks open and close a code span; more than one is how an author writes a backtick inside one",
+        witnesses: [
+            { a: "`x`", b: "``x``", note: "one backtick against two" },
+        ],
+    },
+    {
+        id: "inline-code:padding",
+        layer: "mdast-geometry",
+        captures: ["inlineCode.sourcePadded"],
+        rationale: "the one space either side that CommonMark strips, which is how `` ` `` itself is written inside a span",
+        witnesses: [
+            { a: "`x`", b: "` x `", note: "the stripped padding" },
+        ],
+    },
+    {
+        id: "lexical:backslash-escape",
+        layer: "mdast-geometry",
+        captures: ["text.escapedChars"],
+        rationale: "where the author put a backslash in front of a character that did not need one; the value is the same string either way, and re-deriving the escapes from it is how a serializer starts escaping things nobody typed",
+        witnesses: [
+            {
+                a: "a\\*b",
+                b: "a*b",
+                note: "an escaped asterisk against a bare one that opens nothing",
+            },
+        ],
+    },
+    {
+        id: "link:angle-url",
+        layer: "mdast-geometry",
+        captures: ["link.sourceUrlForm"],
+        rationale: "`[a](<u>)` against `[a](u)`; the angle form is what an author reaches for when the destination has a space in it, and keeping it is how the habit survives an edit elsewhere",
+        witnesses: [
+            { a: "[a](u)", b: "[a](<u>)", note: "the angle brackets around the destination" },
+        ],
+    },
+    {
+        id: "link:autolink-form",
+        layer: "mdast-geometry",
+        captures: ["link.sourceStyle"],
+        rationale: "a bare GFM literal autolink against the same url in angle brackets; both are one link node with the same href",
+        witnesses: [
+            {
+                a: "https://e.com",
+                b: "<https://e.com>",
+                note: "the gfm literal form against the angle form",
+            },
+        ],
+    },
+    {
+        id: "link:title-quote",
+        layer: "mdast-geometry",
+        captures: ["link.sourceTitleMarker"],
+        rationale: "which of the three title containers an inline link used — `\"`, `'` or `()`",
+        witnesses: [
+            { a: '[a](u "t")', b: "[a](u 't')", note: "double quotes against single" },
+        ],
+    },
+    {
+        id: "list:bullet-marker",
+        layer: "mdast-geometry",
+        captures: ["list.bulletMarker"],
+        rationale: "`-`, `*` or `+`; mdast-util-to-markdown picks one globally and alternates it between adjacent lists, so without the axis a document converges on whichever the serializer likes",
+        witnesses: [
+            { a: "- a", b: "* a", note: "the bullet character" },
+        ],
+    },
+    {
+        id: "list:item-marker-spacing",
+        layer: "mdast-geometry",
+        captures: ["listItem.sourceMarkerSpacing"],
+        rationale: "spaces between a list marker and its content; one to four all mean the same item and set different continuation indents",
+        witnesses: [
+            { a: "- a", b: "-   a", note: "one space after the bullet against three" },
+        ],
+    },
+    {
+        id: "list:item-ordinal",
+        layer: "mdast-geometry",
+        captures: ["listItem.sourceOrdinal"],
+        rationale: "the number each ordered item was actually typed with; mdast keeps the list's `start` and nothing else, so `1. 1. 1.` and `1. 2. 3.` are the same tree",
+        witnesses: [
+            {
+                a: "1. a\n1. b",
+                b: "1. a\n2. b",
+                note: "all-ones against counting up",
+            },
+        ],
+    },
+    {
+        id: "list:ordered-delimiter",
+        layer: "mdast-geometry",
+        captures: ["list.listMarkerDelimiter"],
+        rationale: "`1.` against `1)` for an ordered list",
+        witnesses: [
+            { a: "1. a", b: "1) a", note: "the character after the ordinal" },
+        ],
+    },
+    {
+        id: "setext:underline-length",
+        layer: "mdast-geometry",
+        captures: ["heading.sourceUnderlineLength"],
+        rationale: "how long the `=` or `-` run under a setext heading is; one character is enough and authors rule the whole width",
+        witnesses: [
+            { a: "T\n=", b: "T\n===", note: "the underline run" },
+        ],
+    },
+    {
+        id: "strike:delimiter",
+        layer: "mdast-geometry",
+        captures: ["delete.sourceDelimiter"],
+        rationale: "GFM's `~x~` against `~~x~~`; the single-tilde form is not in every reader's dialect, which is why the capture lands and the replay is a rendering decision",
+        witnesses: [
+            { a: "~~x~~", b: "~x~", note: "two tildes against one" },
+        ],
+    },
+    {
+        id: "strong:delimiter",
+        layer: "mdast-geometry",
+        captures: ["strong.sourceDelimiter"],
+        rationale: "`**` against `__` for a double-delimiter run",
+        witnesses: [
+            { a: "**s**", b: "__s__", note: "the delimiter run" },
+        ],
+    },
+    {
+        id: "structured-block:entry-bullet",
+        layer: "structured-block",
+        ledgerReasons: ["entry-bullet-marker"],
+        rationale: "a status or chat entry may be authored bare, with `-`, or with `*`; the block grammars strip the marker before reading the entry, so all three parse to the same timeline and which one was typed is a spelling rather than content",
+        witnesses: [
+            {
+                lang: "chat",
+                a: "- @mara: on it\n",
+                b: "* @mara: on it\n",
+                note: "the entry bullet — the id the wave-1 drop ledger already spends",
+            },
+            {
+                lang: "status",
+                a: "state: building\n- @ada: on it\n",
+                b: "state: building\n* @ada: on it\n",
+                note: "the same axis one block language over, because the ledger entry is not chat-specific",
+            },
+        ],
+    },
+    {
+        id: "table:cell-padding",
+        layer: "mdast-geometry",
+        captures: ["tableCell.sourcePadding"],
+        rationale: "the spaces inside each cell's pipes, which is what makes a hand-aligned table a grid instead of a wall",
+        witnesses: [
+            {
+                a: "| a |\n| - |",
+                b: "|a|\n| - |",
+                note: "padded cells against tight ones",
+            },
+        ],
+    },
+    {
+        id: "table:delimiter-dashes",
+        layer: "mdast-geometry",
+        captures: ["table.sourceDashCounts"],
+        rationale: "how many dashes each delimiter cell holds; one is legal and authors widen them to the column",
+        witnesses: [
+            {
+                a: "| a |\n| - |",
+                b: "| a |\n| --- |",
+                note: "a one-dash delimiter against a three-dash one",
+            },
+        ],
+    },
+    {
+        id: "table:delimiter-padding",
+        layer: "mdast-geometry",
+        captures: ["table.sourceAlignmentPadding"],
+        rationale: "the spaces around the dashes in the delimiter row, captured apart from the dash count because the two move independently",
+        witnesses: [
+            {
+                a: "| a |\n|---|",
+                b: "| a |\n| --- |",
+                note: "the same three dashes, padded and not",
+            },
+        ],
+    },
+    {
+        id: "table:outer-pipes",
+        layer: "mdast-geometry",
+        captures: ["table.sourceOuterPipes"],
+        rationale: "whether the rows carry their leading and trailing pipes; GFM makes both optional and the pipe-less form is a real authoring style",
+        witnesses: [
+            {
+                a: "| a | b |\n| :-- | --: |\n| 1 | 2 |",
+                b: "a | b\n:-- | --:\n1 | 2",
+                note: "edge pipes against none — the alignment colons keep the delimiter row from reading as a setext underline",
+            },
+        ],
+    },
+    {
+        id: "task-list:checkbox-char",
+        layer: "mdast-geometry",
+        captures: ["listItem.sourceCheckboxChar"],
+        rationale: "`[x]` against `[X]`; GFM checks the box either way and one of them is what the author's other tool writes",
+        witnesses: [
+            { a: "- [x] a", b: "- [X] a", note: "the checkbox character's case" },
+        ],
+    },
+    {
+        id: "thematic-break:marker",
+        layer: "mdast-geometry",
+        captures: ["thematicBreak.sourceRaw"],
+        rationale: "the whole authored run — `***`, `---`, `- - -`, `___` and every spaced variant are one thematic break",
+        witnesses: [
+            { a: "***", b: "- - -", note: "the marker run, verbatim" },
+        ],
+    },
+];
+/** Every id on the list, for a cheap membership test. */
+export const FORMAT_AXIS_IDS = new Set(FORMAT_AXES.map((axis) => axis.id));
+/**
+ * The axis with this id.
+ *
+ * Throws rather than returning undefined: every call site here is spending an
+ * id that the type system already proved exists, so a miss means the list and
+ * the union disagree, which is a bug in this file and not a case a caller
+ * should be writing a branch for.
+ */
+export function formatAxis(id) {
+    const found = FORMAT_AXES.find((axis) => axis.id === id);
+    if (!found)
+        throw new Error(`no format axis with id ${id}`);
+    return found;
+}
+/**
+ * The axis that owns a captured geometry key, spelled `<nodeType>.<dataKey>`.
+ *
+ * Undefined here is the interesting answer, not an error: it means the capture
+ * layer records a spelling the vocabulary cannot name, which is exactly what
+ * the closure test is looking for.
+ */
+export function axisForCapture(key) {
+    return FORMAT_AXES.find((axis) => axis.layer === "mdast-geometry" && axis.captures.includes(key));
+}
+/** Every `<nodeType>.<dataKey>` the vocabulary claims, deduplicated. */
+export function claimedCaptureKeys() {
+    const out = new Set();
+    for (const axis of FORMAT_AXES) {
+        if (axis.layer !== "mdast-geometry")
+            continue;
+        for (const key of axis.captures)
+            out.add(key);
+    }
+    return [...out].sort();
+}
+/**
+ * Every blank-run `data` key the vocabulary claims, deduplicated.
+ *
+ * Kept apart from {@link claimedCaptureKeys} rather than merged into it because
+ * the two are spelled differently on purpose — one carries a node type and the
+ * other cannot — and a single list would have to pick one spelling and be wrong
+ * about half its entries.
+ */
+export function claimedBlankRunKeys() {
+    const out = new Set();
+    for (const axis of FORMAT_AXES) {
+        if (axis.layer !== "blank-runs")
+            continue;
+        for (const key of axis.dataKeys)
+            out.add(key);
+    }
+    return [...out].sort();
+}

package/dist/format/index.d.ts

@@ -24,4 +24,5 @@ export * from "./lint/index.js";
 export * from "./blocks/structured-block-schema.js";
 export * from "./blocks/markdown-block-catalog.js";
 export * from "./blocks/dropClosure.js";
+export * from "./formatAxes.js";
 export * from "./wayfinder.js";

package/dist/format/index.js

@@ -26,6 +26,10 @@ export * from "./lint/index.js";
 export * from "./blocks/structured-block-schema.js";
 export * from "./blocks/markdown-block-catalog.js";
 export * from "./blocks/dropClosure.js";
+// The format-DOF vocabulary the ledger above spends (card #288). It is data
+// and types only — no parser, no walker — so it rides the CLI sync alongside
+// the ledger that would not compile without it.
+export * from "./formatAxes.js";
 export * from "./wayfinder.js";
 // htmlToMarkdown and parseMarkdownAst are deliberately NOT in the barrel:
 // they carry the package's only heavy dependencies (unified/rehype/remark)

package/dist/format/lineGeometry.d.ts

@@ -26,6 +26,16 @@ export declare function frontmatterExtent(lines: readonly string[]): {
     open: number;
     close: number;
 } | null;
+/**
+ * The first line of the document's markdown: 0, or the line after a leading
+ * frontmatter block. A frontmatter block that never closes takes the whole
+ * document with it, which is what a reader sees too.
+ *
+ * Lint and the mask both need this number and must not each compute it: one of
+ * them being wrong about where the YAML ends is exactly how a `<!--` in a
+ * summary field opens a comment over a whole file.
+ */
+export declare function markdownStart(lines: readonly string[]): number;
 /**
  * Every fenced code block in the document, in order. `from` skips the
  * frontmatter block, whose contents are not markdown either.
@@ -48,17 +58,37 @@ export declare function codeSpanMask(line: string): boolean[];
  * length of the line it masks, so `masked[i][k]` and `lines[i][k]` are the
  * same byte position.
  *
- * `from` skips a leading frontmatter block for the FENCE scan only, mirroring
- * {@link fenceMask} — whether the frontmatter itself renders is the caller's
- * question, and lint already answers it with `inFrontmatter`.
+ * `from` is where the document's markdown begins — everything above it is a
+ * frontmatter block, which is not markdown at all and is returned verbatim for
+ * whoever does read it (lint, with `inFrontmatter`). Scanning it would be
+ * worse than useless: a `<!--` in a YAML value would open a comment over the
+ * whole document. Callers holding a BODY pass 0 — a leading `---` there is a
+ * thematic break, not frontmatter — and `maskNonRenderingContexts` works the
+ * boundary out with `markdownStart`.
+ *
+ * A fence decides the whole line, but only where nothing is open already: a
+ * ``` line inside an unterminated comment is comment text, and the document
+ * below the `-->` renders. That ordering is CommonMark's — an HTML block ends
+ * at its closing condition, not at the next thing that looks like a fence —
+ * and it is the one place fence geometry does not go first. Where the line is
+ * clear, `fenceRegionAt` answers, so there is still exactly one idea in the
+ * package of where a fence starts and ends.
+ *
+ * Lines are whatever the caller split; a bare `\r` inside one is not a line
+ * ending here. `maskNonRenderingContexts` splits the way CommonMark does.
  */
 export declare function maskNonRenderingLines(lines: readonly string[], from?: number): string[];
 /**
  * The whole source, masked. `masked.length === source.length` always: the two
  * strings are the same document, one of them with the non-markdown blanked
  * out, and every offset holds across both.
+ *
+ * This is the DOCUMENT entry point — cm-lint and `demoteNonRenderingLinks`
+ * hand it whole files — so the frontmatter boundary is worked out here rather
+ * than assumed to be 0. Pass `from` explicitly when the caller knows better:
+ * 0 says "these bytes are all markdown", which is what a body is.
  */
-export declare function maskNonRenderingContexts(source: string): string;
+export declare function maskNonRenderingContexts(source: string, from?: number): string;
 /**
  * True when the source span `[start, end)` holds bytes but no rendering ones —
  * the predicate a consumer asks before trusting anything it found by scanning.