sfora-cli 0.10.0 → 0.12.0

package/dist/format/callout.js

@@ -11,10 +11,25 @@
  *     > [!WARNING] Ship blocker
  *     > The migration has to run before the deploy.
  *
- * Five types, matching GitHub: note, tip, important, warning, caution. The
- * marker is written uppercase and read case-insensitively, because people type
- * `[!note]` and pasted GitHub markdown says `[!NOTE]` — both are the same
- * callout, and the first save canonicalizes.
+ * Fifteen types. The first five are GitHub's alert set — note, tip, important,
+ * warning, caution — and the other ten are the Obsidian set every vault and
+ * every other markdown tool already writes, so a document pasted in from one of
+ * them keeps its tone instead of falling back to a plain quote. The marker is
+ * written uppercase and read case-insensitively, because people type `[!note]`
+ * and pasted GitHub markdown says `[!NOTE]` — both are the same callout, and
+ * the first save canonicalizes.
+ *
+ * Two things beyond the type sit on the marker line, and both are round-tripped
+ * rather than normalised away:
+ *
+ *   - an ALIAS. `[!WARN]`, `[!SUMMARY]`, `[!ERROR]` name a type by another
+ *     word. They resolve to the canonical type for rendering, and the word the
+ *     author actually typed is carried on `authoredAs` so the bytes come back
+ *     unchanged. Normalising the spelling would rewrite a line the author did
+ *     not touch, which is churn in a file two agents and a person share.
+ *   - a FOLD marker. Obsidian's `[!NOTE]+` and `[!NOTE]-` say the callout is
+ *     collapsible and whether it starts open. It is one character of grammar
+ *     and it is the whole difference between a callout and a details block.
  *
  * Pure functions over lines: no DOM, no ProseMirror, no React. The reader
  * (`src/lib/utils/markdown.ts`), the Tiptap node
@@ -22,20 +37,83 @@
  * grammar from here so they cannot disagree about what a callout is.
  */
 export const CALLOUT_TYPES = [
+    // GitHub's five.
     "note",
     "tip",
     "important",
     "warning",
     "caution",
+    // Obsidian's ten.
+    "abstract",
+    "info",
+    "todo",
+    "success",
+    "question",
+    "failure",
+    "danger",
+    "bug",
+    "example",
+    "quote",
 ];
-const MARKER = /^\[!([A-Za-z]+)\][ \t]*(.*)$/;
-/** The marker as written: uppercase, so `[!NOTE]` is what lands on disk. */
-export function calloutMarker(type) {
-    return `[!${type.toUpperCase()}]`;
+/**
+ * The other words people write for a type that already exists. Ported from
+ * open-knowledge's `callout-transformer.ts:41-71`, which took them from
+ * Obsidian, so a vault's markdown lands here meaning what it meant there.
+ *
+ * An alias is a spelling, not a type: it never widens `CalloutType`, and the
+ * authored word survives on `Callout.authoredAs` rather than in the enum.
+ */
+export const CALLOUT_ALIASES = {
+    summary: "abstract",
+    tldr: "abstract",
+    check: "success",
+    done: "success",
+    help: "question",
+    faq: "question",
+    fail: "failure",
+    missing: "failure",
+    error: "danger",
+    cite: "quote",
+    idea: "tip",
+    hint: "tip",
+    warn: "warning",
+    attention: "warning",
+};
+const MARKER = /^\[!([A-Za-z]+)\]([+-])?[ \t]*(.*)$/;
+/**
+ * The marker as written: uppercase, so `[!NOTE]` is what lands on disk — unless
+ * the author spelled the type another way, in which case their word goes back.
+ *
+ * `authoredAs` is checked, not trusted. It is an attribute by the time it gets
+ * here (the editor carries it on the node), and an attribute a paste or a
+ * command could have set to anything; a marker that no longer resolves to this
+ * callout's type would come back as a plain quote with a stray bracket. So a
+ * spelling that does not resolve to `type` is discarded and the canonical word
+ * is written instead — the tone is preserved and only the churn is paid.
+ */
+export function calloutMarker(type, options = {}) {
+    const authored = options.authoredAs?.trim();
+    const token = authored && resolveCalloutType(authored) === type
+        ? authored
+        : type.toUpperCase();
+    return `[!${token}]${options.fold ?? ""}`;
 }
+/** True for the fifteen canonical type names, in any case. Aliases are not types. */
 export function isCalloutType(value) {
     return CALLOUT_TYPES.includes(value.toLowerCase());
 }
+/**
+ * The token on a marker line — canonical or alias — resolved to the type that
+ * renders it, or null when it names nothing. Every caller that has to decide
+ * "is this a callout?" asks this rather than `isCalloutType`, because an alias
+ * IS a callout and only differs in how it is spelled.
+ */
+export function resolveCalloutType(token) {
+    const lower = token.toLowerCase();
+    if (isCalloutType(lower))
+        return lower;
+    return CALLOUT_ALIASES[lower] ?? null;
+}
 /**
  * Drop one level of `>` quoting. A single space after the marker is part of
  * the marker, not the content — `>  indented` keeps one space.
@@ -85,10 +163,17 @@ function readCallout(blockquoteLines) {
     const match = MARKER.exec(lines[first].trim());
     if (!match)
         return null;
-    const keyword = match[1].toLowerCase();
-    if (!isCalloutType(keyword))
+    const keyword = match[1];
+    const type = resolveCalloutType(keyword);
+    if (!type)
         return null;
-    const title = match[2].trim();
+    // The author's own spelling, kept only when it is not the canonical word.
+    // Same test open-knowledge makes (`callout-transformer.ts:223-224`): a
+    // lowercase `[!note]` is the canonical type spelled small, so it still
+    // canonicalizes on save and the existing law does not move.
+    const authoredAs = keyword.toLowerCase() === type ? undefined : keyword;
+    const fold = match[2] === "+" || match[2] === "-" ? match[2] : undefined;
+    const title = match[3].trim();
     // Same trim as `trimBlankEdges`, unrolled so the leading blanks it drops can
     // be added to the body's line index rather than silently lost.
     const rest = lines.slice(first + 1).map((line) => line.replace(/\s+$/, ""));
@@ -100,7 +185,13 @@ function readCallout(blockquoteLines) {
         end--;
     const body = rest.slice(start, end).join("\n");
     return {
-        callout: title ? { type: keyword, title, body } : { type: keyword, body },
+        callout: {
+            type,
+            ...(title ? { title } : {}),
+            body,
+            ...(authoredAs ? { authoredAs } : {}),
+            ...(fold ? { fold } : {}),
+        },
         bodyLine: first + 1 + start,
     };
 }
@@ -109,12 +200,18 @@ function readCallout(blockquoteLines) {
  * form, and the only place the serialized shape is spelled: one blockquote,
  * marker line first, body quoted line by line. A blank body line is a bare
  * `>` — no trailing space, so the bytes survive editors that strip them.
+ *
+ * The marker line is rebuilt from the three fields that spell it — type,
+ * authored word, fold — rather than kept as a string, so a callout the editor
+ * constructed by hand and one parsed off disk are written by the same code.
  */
 export function calloutToMarkdown(callout) {
     const title = callout.title?.trim();
-    const head = title
-        ? `> ${calloutMarker(callout.type)} ${title}`
-        : `> ${calloutMarker(callout.type)}`;
+    const marker = calloutMarker(callout.type, {
+        authoredAs: callout.authoredAs,
+        fold: callout.fold,
+    });
+    const head = title ? `> ${marker} ${title}` : `> ${marker}`;
     const body = trimBlankEdges(callout.body.split("\n"));
     if (body.length === 0)
         return head;

package/dist/format/checklist.js

@@ -26,6 +26,12 @@ const QUOTE_PREFIX_RE = /^(?:[ \t]{0,3}>[ \t]?)*/;
  * own container: an unclosed fence inside one ends with the quote and must not
  * swallow the real checkboxes that follow it at top level.
  *
+ * It is the whole mask that runs on the stripped lines, not just the fence
+ * half, and it cuts both ways: a `<code>` left open inside a blockquote hides
+ * the checkbox below it even where the raw scan sees the line plainly, and a
+ * ``` inside a quoted comment is comment text rather than a fence, so the task
+ * after the `-->` survives. Both are pinned in checklist.test.ts.
+ *
  * Depth 0 is left to the caller's raw mask, which already reads those lines
  * with their `>`-looking content intact.
  */
@@ -114,10 +120,11 @@ export function scanChecklist(body) {
         openIndent = indent;
         const raw = lineText(lines, i);
         const box = CHECKBOX_RE.exec(raw);
-        // The state box has to be one of the bytes that render. `- [ ] a` inside
-        // an inline code span survives the bullet test above — the marker is
-        // outside the span — but the box itself is masked, and a toggle would be
-        // rewriting someone's sample.
+        // The box has to be one of the bytes that render, and it has to be the
+        // box the grammar found. Both halves are reachable on one line: with a
+        // comment carried down from above, `- [ ] a --> - [ ] b` renders a
+        // checkbox, but not the one CHECKBOX_RE anchored at the head of the line,
+        // and that is the one a toggle would rewrite. No addressable box, no item.
         if (!box || line[box[1].length] !== "[")
             continue;
         out.push({

package/dist/format/formatAxes.d.ts

@@ -0,0 +1,228 @@
+/**
+ * The format degrees of freedom, as a finite list somebody can read in one
+ * sitting.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT AN AXIS IS
+ * ---------------------------------------------------------------------------
+ *
+ * A format axis is a dimension along which the BYTES of a document may vary
+ * while its MEANING does not. `*em*` and `_em_` are two points on one axis.
+ * So are ` ``` ` and `~~~`, `# T` and `# T #`, a table's `-` and its `---`.
+ * Nothing on this list changes what a reader sees; everything on it changes
+ * what the file says on disk.
+ *
+ * The list exists because "lossy" and "byte-identical" are both useless as
+ * verdicts on their own. A serializer that reflows a document is not corrupting
+ * it, and a round trip that changes six bytes has not necessarily lost
+ * anything — but until the six bytes have a NAME, nobody reviewing the diff can
+ * tell which of those two sentences is true. Card #288: byte fidelity as a
+ * finite reviewable vocabulary, each entry with a witness that runs.
+ *
+ * The names follow open-knowledge's, whose `parser-drop-closure.ts:22-289`
+ * already spends axis ids the same way — `code-fence:char`, `link:title-quote`,
+ * `list:item-marker-spacing`, `setext:underline`. Where a name diverges it is
+ * because sfora's capture layer draws the line somewhere else, and the axis
+ * says so.
+ *
+ * ---------------------------------------------------------------------------
+ * WHERE THE LIST COMES FROM, AND WHY IT CANNOT BE INVENTED
+ * ---------------------------------------------------------------------------
+ *
+ * The axes are not a taxonomy somebody sat down and wrote. They are DERIVED
+ * from what the capture layer already records: `GEOMETRY_KEYS` in
+ * `editorWalker/sourceGeometry.ts` is the ground truth, and every
+ * `<nodeType>.<dataKey>` in it is one axis's `captures` entry. That is the
+ * whole discipline — an axis with no capture is a word, and a capture with no
+ * axis is a field nobody can name in a review. `__tests__/formatAxes.test.ts`
+ * closes the two against each other in both directions, so neither can drift.
+ *
+ * This file deliberately does NOT import `GEOMETRY_KEYS`. The capture layer
+ * lives under `editorWalker/`, which pulls unified and remark-stringify in and
+ * is excluded from the CLI sync (`packages/sfora/scripts/sync-format.mjs`);
+ * the drop ledger that spends these ids is NOT excluded and must keep
+ * compiling in the tarball. So the coupling is a string in a test rather than
+ * an import, and the test is what makes the string true.
+ *
+ * ---------------------------------------------------------------------------
+ * THREE CAPTURE LAYERS, ONE VOCABULARY
+ * ---------------------------------------------------------------------------
+ *
+ * Sfora has three places where an author's spelling is read and set aside, and
+ * they are not the same machinery:
+ *
+ *   - the mdast geometry capture, which reads spellings off a POSITIONED parse
+ *     tree and stores them on `node.data` (`layer: "mdast-geometry"`);
+ *   - the structured-block parsers, which read a fence body line by line and
+ *     report what they did not keep (`layer: "structured-block"`);
+ *   - the blank-run plan, which reads the gaps BETWEEN blocks and the runs at
+ *     the document's own two ends (`layer: "blank-runs"`).
+ *
+ * The second is why this file is not simply a rename of `GEOMETRY_KEYS`. The
+ * wave-1 drop ledger already spends the id `structured-block:entry-bullet` on
+ * a chat entry authored `* @mara: …` rather than `- @mara: …`, and that
+ * spelling has no `node.data` anywhere — the bullet is dropped, not captured.
+ * An axis vocabulary that could not name it would leave the one verdict it was
+ * built for pointing at a string nobody defined.
+ *
+ * The third is here because the list has to cover what the walker REPLAYS, not
+ * what one module happens to declare. `blankRuns.ts` writes
+ * `sourceBlankLinesBefore` and `sourceEdgeBlankLines`, `emit.ts`'s join reads
+ * both back, and an author's double gap between two sections survives a save
+ * because of it — a degree of freedom as real as a fence character, and one the
+ * first version of this list was silently missing because those two keys are
+ * written by the WALKER onto the tree it builds rather than by
+ * `captureSourceGeometry` onto a parse, and so are structurally outside
+ * `GEOMETRY_KEYS`. Deriving the list from one module's export rather than from
+ * the behaviour is exactly how a vocabulary ends up with a hole in it.
+ *
+ * So the layer is a discriminant and the closure test grades each layer against
+ * its own ground truth: the geometry axes against `GEOMETRY_KEYS`, the block
+ * axes against the `format-dof-axis` entries of `BLOCK_DROP_ADJUDICATIONS`, and
+ * the blank-run axes against the keys a live `captureRootGaps` /
+ * `applyRootGaps` pair actually writes over a corpus. That third ground truth
+ * is BEHAVIOURAL rather than declarative, and the suite says so: the two keys
+ * are declared in a `declare module "mdast"` block, which erases at runtime, so
+ * there is no list to import. A key the corpus never provokes would be invisible
+ * to it, which is a real limit and not a hidden one.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT A WITNESS PROVES, AND WHAT IT DOES NOT
+ * ---------------------------------------------------------------------------
+ *
+ * Every axis carries at least one DISCRIMINATION WITNESS: two spellings, `a`
+ * and `b`. The name matters, because these are not round-trip witnesses and
+ * calling them that would claim the one thing they do not show. The suite
+ * asserts three things about each pair, and the third is what stops the list
+ * becoming decoration.
+ *
+ *   1. the bytes differ — otherwise there is no degree of freedom here;
+ *   2. an INDEPENDENT reparse reads both to the same tree, positions and
+ *      `data` stripped (`geometryReparsesTheSame`) — otherwise this is a
+ *      content difference wearing a formatting name;
+ *   3. the capture layer TELLS THEM APART — the set of captured keys that move
+ *      between `a` and `b` is non-empty, and across an axis's witnesses it
+ *      covers every key the axis claims.
+ *
+ * Three is the anti-vacuity clause. An axis whose witnesses no longer move its
+ * own capture key is an axis whose capture stopped happening, and the suite
+ * fails on the axis rather than on some distant serializer test six months
+ * later.
+ *
+ * What a discrimination witness does NOT prove is that the spelling survives a
+ * save. Most of these axes are captured and not yet replayed —
+ * `CAPTURED_NOT_REPLAYED` in `sourceGeometry.ts` says which, and names the card
+ * that owes each one. The suite pins the replayed SET rather than a total,
+ * because a total can hold still while the membership churns — and, for one
+ * axis in each replay FAMILY, it serializes an editor document through the real
+ * walker and asserts the author's bytes come back. A scoreboard read off a
+ * hand-maintained array is a scoreboard that can be wrong in the direction
+ * nobody checks.
+ */
+import type { BlockDropReason } from "./blocks/dropClosure.js";
+import type { StructuredBlockLanguage } from "./blocks/structured-block-schema.js";
+/**
+ * Every axis id, as a union so a ledger entry citing one that does not exist
+ * fails to compile rather than fails to mean anything.
+ *
+ * `namespace:name`, lower case, and the namespace is the CONSTRUCT rather than
+ * the mdast node type where the two disagree — `task-list:checkbox-char` sits
+ * on `listItem.sourceCheckboxChar`, and an author who has never heard of mdast
+ * still knows what a task list is.
+ */
+export type FormatAxisId = "blank-lines:doc-edge" | "blank-lines:interior" | "block-gap:after-heading" | "blockquote:marker-spacing" | "code-block:style" | "code-fence:char" | "code-fence:info-padding" | "code-fence:length" | "definition:layout" | "definition:title-quote" | "emphasis:delimiter" | "hard-break:style" | "heading:style" | "heading:trailing-hashes" | "inline-code:fence-length" | "inline-code:padding" | "lexical:backslash-escape" | "link:angle-url" | "link:autolink-form" | "link:title-quote" | "list:bullet-marker" | "list:item-marker-spacing" | "list:item-ordinal" | "list:ordered-delimiter" | "setext:underline-length" | "strike:delimiter" | "strong:delimiter" | "structured-block:entry-bullet" | "table:cell-padding" | "table:delimiter-dashes" | "table:delimiter-padding" | "table:outer-pipes" | "task-list:checkbox-char" | "thematic-break:marker";
+/**
+ * Two spellings of one meaning, for an axis the mdast geometry layer captures.
+ *
+ * Both are whole markdown documents rather than fragments, because the capture
+ * layer reads source OFFSETS and a fragment has none. They are kept as short as
+ * the axis allows so a reader can see the difference without diffing.
+ */
+export interface GeometryAxisWitness {
+    a: string;
+    b: string;
+    /** What moved, in the words a reviewer would use. */
+    note: string;
+}
+/** Two spellings of one meaning, for an axis a structured-block parser drops. */
+export interface BlockAxisWitness {
+    lang: StructuredBlockLanguage;
+    /** The spelling whose bytes survive. */
+    a: string;
+    /** The spelling that provokes the drop. */
+    b: string;
+    note: string;
+}
+export type FormatAxis = {
+    id: FormatAxisId;
+    layer: "mdast-geometry";
+    /**
+     * `<nodeType>.<dataKey>`, exactly as `GEOMETRY_KEYS` spells it. Every
+     * entry must be declared there and every entry there must appear on
+     * exactly one axis.
+     */
+    captures: readonly string[];
+    rationale: string;
+    witnesses: readonly GeometryAxisWitness[];
+} | {
+    id: FormatAxisId;
+    layer: "blank-runs";
+    /**
+     * The `data` keys `blankRuns.ts` writes, by NAME rather than as
+     * `<nodeType>.<dataKey>`.
+     *
+     * The node type is not part of the identity here and pretending it were
+     * would be a lie in the vocabulary: an interior gap belongs to whatever
+     * block happens to follow it, so `sourceBlankLinesBefore` lands on a
+     * paragraph, a code block or a table depending on the document. (The edge
+     * run is always on the root, and is spelled the same way for symmetry.)
+     */
+    dataKeys: readonly string[];
+    rationale: string;
+    witnesses: readonly GeometryAxisWitness[];
+} | {
+    id: FormatAxisId;
+    layer: "structured-block";
+    /**
+     * The drop reasons in `BLOCK_DROP_ADJUDICATIONS` whose `format-dof-axis`
+     * verdict spends this id. Closed both directions by the suite.
+     */
+    ledgerReasons: readonly BlockDropReason[];
+    rationale: string;
+    witnesses: readonly BlockAxisWitness[];
+};
+/**
+ * The list. Sorted by id, because a list nobody can scan is not reviewable and
+ * reviewable is the entire point.
+ */
+export declare const FORMAT_AXES: readonly FormatAxis[];
+/** Every id on the list, for a cheap membership test. */
+export declare const FORMAT_AXIS_IDS: ReadonlySet<FormatAxisId>;
+/**
+ * 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 declare function formatAxis(id: FormatAxisId): FormatAxis;
+/**
+ * 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 declare function axisForCapture(key: string): FormatAxis | undefined;
+/** Every `<nodeType>.<dataKey>` the vocabulary claims, deduplicated. */
+export declare function claimedCaptureKeys(): string[];
+/**
+ * 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 declare function claimedBlankRunKeys(): string[];