sfora-cli 0.10.0 → 0.11.0

package/dist/format/lint/index.d.ts

@@ -9,12 +9,41 @@
  * only allowed to point at places where sfora will read it differently than
  * they will.
  *
- * The core is pure: no CodeMirror, no unified. Diagnostics carry absolute
- * offsets and the editor adapter (src/components/notes/cm-lint.ts) translates
- * them; an mdast tree, when one is wanted, is injected. That is what lets the
- * same rules run in the CLI before an agent PUTs a file as run in the editor
- * while a human types it.
+ * The core is pure: no CodeMirror, no unified, no third-party import at all.
+ * Diagnostics carry absolute offsets and the editor adapter
+ * (src/components/notes/cm-lint.ts) translates them; an mdast tree, when one
+ * is wanted, is injected. That is what lets the same rules run in the CLI
+ * before an agent PUTs a file as run in the editor while a human types it.
+ *
+ * Five modules underneath the rules carry the mechanics, and all five exist so
+ * the same seven rules can be USED in more places rather than so there can be
+ * more of them:
+ *
+ *   ./severity   the four levels and what each one means. The ladder is by
+ *                what the document LOSES, not by how loud a rule feels.
+ *   ./textEdits  a fix is a list of ranged replacements over one document
+ *                state, applied reverse-sorted, all of it or none of it.
+ *   ./fixAll     every fix in a document composed into one atomic change,
+ *                with an account of what was applied, refused and left.
+ *   ./appliesTo  the path-glob dialect a scope is written in, and the
+ *                judgement that one of those globs is doubtful.
+ *   ./config     what a workspace may say about these rules — off, another
+ *                severity, a path scope — and the linter that reads its own
+ *                config back and flags the settings that silently cost it a
+ *                rule.
+ *   ./frontmatterSchema
+ *                the one dial that adds a check: a JSON Schema a workspace
+ *                declares for a kind of document, read against sfora's own
+ *                frontmatter value model, off until it is written down — and
+ *                linted itself, so a keyword sfora does not implement is
+ *                reported rather than quietly enforcing nothing.
  */
 export * from "./types.js";
+export * from "./severity.js";
+export * from "./textEdits.js";
+export * from "./appliesTo.js";
+export * from "./config.js";
+export * from "./frontmatterSchema.js";
 export * from "./lintSource.js";
+export * from "./fixAll.js";
 export * from "./rules/index.js";

package/dist/format/lint/index.js

@@ -11,12 +11,41 @@
  * only allowed to point at places where sfora will read it differently than
  * they will.
  *
- * The core is pure: no CodeMirror, no unified. Diagnostics carry absolute
- * offsets and the editor adapter (src/components/notes/cm-lint.ts) translates
- * them; an mdast tree, when one is wanted, is injected. That is what lets the
- * same rules run in the CLI before an agent PUTs a file as run in the editor
- * while a human types it.
+ * The core is pure: no CodeMirror, no unified, no third-party import at all.
+ * Diagnostics carry absolute offsets and the editor adapter
+ * (src/components/notes/cm-lint.ts) translates them; an mdast tree, when one
+ * is wanted, is injected. That is what lets the same rules run in the CLI
+ * before an agent PUTs a file as run in the editor while a human types it.
+ *
+ * Five modules underneath the rules carry the mechanics, and all five exist so
+ * the same seven rules can be USED in more places rather than so there can be
+ * more of them:
+ *
+ *   ./severity   the four levels and what each one means. The ladder is by
+ *                what the document LOSES, not by how loud a rule feels.
+ *   ./textEdits  a fix is a list of ranged replacements over one document
+ *                state, applied reverse-sorted, all of it or none of it.
+ *   ./fixAll     every fix in a document composed into one atomic change,
+ *                with an account of what was applied, refused and left.
+ *   ./appliesTo  the path-glob dialect a scope is written in, and the
+ *                judgement that one of those globs is doubtful.
+ *   ./config     what a workspace may say about these rules — off, another
+ *                severity, a path scope — and the linter that reads its own
+ *                config back and flags the settings that silently cost it a
+ *                rule.
+ *   ./frontmatterSchema
+ *                the one dial that adds a check: a JSON Schema a workspace
+ *                declares for a kind of document, read against sfora's own
+ *                frontmatter value model, off until it is written down — and
+ *                linted itself, so a keyword sfora does not implement is
+ *                reported rather than quietly enforcing nothing.
  */
 export * from "./types.js";
+export * from "./severity.js";
+export * from "./textEdits.js";
+export * from "./appliesTo.js";
+export * from "./config.js";
+export * from "./frontmatterSchema.js";
 export * from "./lintSource.js";
+export * from "./fixAll.js";
 export * from "./rules/index.js";

package/dist/format/lint/lintSource.d.ts

@@ -1,18 +1,26 @@
 import { type WikiLink } from "../wikiLinks.js";
 import type { LintContext, LintFix, LintSourceOptions, SforaDiagnostic } from "./types.js";
-export { codeSpanMask, fenceMask, fencedRegions, frontmatterExtent, isNonRenderingRange, lineText, maskNonRenderingContexts, maskNonRenderingLines, type FenceRegion, } from "../lineGeometry.js";
-/** Lines a prose rule must not look at: fences and the frontmatter block. */
+export { codeSpanMask, fenceMask, fencedRegions, frontmatterExtent, isNonRenderingRange, lineText, markdownStart, maskNonRenderingContexts, maskNonRenderingLines, type FenceRegion, } from "../lineGeometry.js";
+/**
+ * Lines a prose rule must not look at: fences, the frontmatter block, and
+ * anything else the mask says never reaches a reader.
+ */
 export declare function isSkippableLine(ctx: LintContext, i: number): boolean;
 /** True when a `[` at `index` is escaped as `\[`. */
 export declare function isEscaped(line: string, index: number): boolean;
 export interface ScannedWikiToken extends WikiLink {
     lineIndex: number;
-    /** Absolute span of the whole `[[…]]` token. */
+    /**
+     * Absolute span of the whole token — INCLUDING the `!` when the token is an
+     * embed, because that is what a fix has to replace. A "remove link" edit
+     * measured from the bracket leaves the marker behind, and a bare `!` in front
+     * of the label it just inserted is not what anybody asked for.
+     */
     from: number;
     to: number;
 }
 /**
- * Every `[[…]]` token outside fences, frontmatter and inline code.
+ * Every `[[…]]` and `![[…]]` token outside fences, frontmatter and inline code.
  *
  * The engine's `wikiLinkPattern()` is the grammar of a WELL-FORMED token: it
  * needs a non-empty body and happily spans newlines. Lint needs the opposite
@@ -20,6 +28,13 @@ export interface ScannedWikiToken extends WikiLink {
  * open at the end of a line is someone mid-typing, not a link. So the span
  * matcher is local and one line wide; the meaning of what is inside the
  * brackets still comes from `parseWikiToken`, which owns the prefix table.
+ *
+ * The bang is the embed marker (card #298) and it is read with one wrinkle the
+ * rest of the reader does not have: an ESCAPED bang is not a marker. `\![[x]]`
+ * is a literal exclamation mark in front of an ordinary wiki link, so the
+ * escape test below is taken at the BRACKET — which is the character that
+ * decides whether there is a token here at all — while a second, separate test
+ * at the bang decides only whether that token is an embed.
  */
 export declare function scanWikiTokens(ctx: LintContext): ScannedWikiToken[];
 export declare function buildLintContext(source: string, opts?: LintSourceOptions): LintContext;
@@ -29,8 +44,13 @@ export declare function buildLintContext(source: string, opts?: LintSourceOption
  */
 export declare function lintSource(source: string, opts?: LintSourceOptions): SforaDiagnostic[];
 /**
- * Apply a fix to the source it was computed against. Edits are applied last
- * one first so earlier offsets stay valid — the same reason the editor
- * dispatches them as one transaction.
+ * Apply a fix to the source it was computed against.
+ *
+ * All of it or none of it. The edits are applied last-one-first so earlier
+ * offsets stay valid — the same reason the editor dispatches them as one
+ * transaction — and a fix whose edits do not compose (out of range, inverted,
+ * overlapping) returns the source untouched rather than landing the half of
+ * itself that happened to fit. See ./textEdits for the mechanics and
+ * `tryApplyEdits` for the version that says WHY it declined.
  */
 export declare function applyLintFix(source: string, fix: LintFix): string;

package/dist/format/lint/lintSource.js

@@ -3,23 +3,33 @@
 // The sfora-law runner, plus the document geometry every rule shares.
 //
 // One pass builds a LintContext — line starts, the fence map, the frontmatter
-// extent — and each rule reads it. Nothing here throws: a parser that blows up
+// extent, the non-rendering mask — and each rule reads it. The geometry itself
+// belongs to ../lineGeometry, which every other scanner in the package reads
+// too; lint owns none of it and re-exports all of it. Nothing here throws: a
+// parser that blows up
 // costs the AST, a rule that blows up costs that rule's diagnostics, and the
 // caller still gets a list. Lint is a background nicety in a text editor; it
 // is never allowed to be the reason a document will not open.
-import { codeSpanMask, fenceMask, frontmatterExtent, lineText, } from "../lineGeometry.js";
+import { codeSpanMask, fenceMask, frontmatterExtent, lineText, markdownStart, maskNonRenderingLines, } from "../lineGeometry.js";
 import { MAX_PARSE_INPUT_BYTES } from "../parseWithFallback.js";
 import { parseWikiToken } from "../wikiLinks.js";
+import { resolveLintRules, scopeAdmits } from "./config.js";
+import { selectFrontmatterSchemas } from "./frontmatterSchema.js";
 import { SFORA_LINT_RULES } from "./rules/index.js";
+import { severityRank } from "./severity.js";
+import { tryApplyEdits } from "./textEdits.js";
 // The fence/frontmatter geometry moved to ../lineGeometry once a second
 // caller (checklist.ts) needed it, and `codeSpanMask` followed it there once a
 // third (blocks/parsers.ts) had hand-copied it. Re-exported so the rules — and
 // everything importing through lint/index, the Convex shim included — keep
 // their existing import path.
-export { codeSpanMask, fenceMask, fencedRegions, frontmatterExtent, isNonRenderingRange, lineText, maskNonRenderingContexts, maskNonRenderingLines, } from "../lineGeometry.js";
-/** Lines a prose rule must not look at: fences and the frontmatter block. */
+export { codeSpanMask, fenceMask, fencedRegions, frontmatterExtent, isNonRenderingRange, lineText, markdownStart, maskNonRenderingContexts, maskNonRenderingLines, } from "../lineGeometry.js";
+/**
+ * Lines a prose rule must not look at: fences, the frontmatter block, and
+ * anything else the mask says never reaches a reader.
+ */
 export function isSkippableLine(ctx, i) {
-    return ctx.inFence(i) || ctx.inFrontmatter(i);
+    return ctx.inFence(i) || ctx.inFrontmatter(i) || ctx.nonRendering(i);
 }
 /** True when a `[` at `index` is escaped as `\[`. */
 export function isEscaped(line, index) {
@@ -29,7 +39,7 @@ export function isEscaped(line, index) {
     return slashes % 2 === 1;
 }
 /**
- * Every `[[…]]` token outside fences, frontmatter and inline code.
+ * Every `[[…]]` and `![[…]]` token outside fences, frontmatter and inline code.
  *
  * The engine's `wikiLinkPattern()` is the grammar of a WELL-FORMED token: it
  * needs a non-empty body and happily spans newlines. Lint needs the opposite
@@ -37,6 +47,13 @@ export function isEscaped(line, index) {
  * open at the end of a line is someone mid-typing, not a link. So the span
  * matcher is local and one line wide; the meaning of what is inside the
  * brackets still comes from `parseWikiToken`, which owns the prefix table.
+ *
+ * The bang is the embed marker (card #298) and it is read with one wrinkle the
+ * rest of the reader does not have: an ESCAPED bang is not a marker. `\![[x]]`
+ * is a literal exclamation mark in front of an ordinary wiki link, so the
+ * escape test below is taken at the BRACKET — which is the character that
+ * decides whether there is a token here at all — while a second, separate test
+ * at the bang decides only whether that token is an embed.
  */
 export function scanWikiTokens(ctx) {
     const out = [];
@@ -45,17 +62,19 @@ export function scanWikiTokens(ctx) {
             continue;
         const line = lineText(ctx.lines, i);
         const mask = codeSpanMask(line);
-        const re = /\[\[([^[\]\n]*)\]\]/g;
+        const re = /(!?)\[\[([^[\]\n]*)\]\]/g;
         let m;
         while ((m = re.exec(line)) !== null) {
-            if (mask[m.index] || isEscaped(line, m.index))
+            const bracket = m.index + m[1].length;
+            if (mask[bracket] || isEscaped(line, bracket))
                 continue;
-            const from = ctx.lineStart(i) + m.index;
+            const embed = m[1] === "!" && !isEscaped(line, m.index);
+            const start = embed ? m.index : bracket;
             out.push({
-                ...parseWikiToken(m[1]),
+                ...parseWikiToken(m[2], embed),
                 lineIndex: i,
-                from,
-                to: from + m[0].length,
+                from: ctx.lineStart(i) + start,
+                to: ctx.lineStart(i) + m.index + m[0].length,
             });
         }
     }
@@ -70,12 +89,9 @@ export function buildLintContext(source, opts = {}) {
         offset += lines[i].length + 1;
     }
     const frontmatter = frontmatterExtent(lines);
-    const fenceScanFrom = frontmatter === null
-        ? 0
-        : frontmatter.close === -1
-            ? lines.length
-            : frontmatter.close + 1;
+    const fenceScanFrom = markdownStart(lines);
     const fenced = fenceMask(lines, fenceScanFrom);
+    const masked = maskNonRenderingLines(lines, fenceScanFrom);
     const fmEnd = frontmatter === null
         ? -1
         : frontmatter.close === -1
@@ -86,8 +102,14 @@ export function buildLintContext(source, opts = {}) {
         lines,
         lineStart: (i) => starts[i] ?? source.length,
         inFence: (i) => fenced[i] === true,
+        // A line that was blank to begin with is not non-rendering, it is empty,
+        // and calling it non-rendering would skip every blank line in the file.
+        nonRendering: (i) => masked[i] !== undefined &&
+            lineText(masked, i).trim() === "" &&
+            lineText(lines, i).trim() !== "",
         inFrontmatter: (i) => frontmatter !== null && i >= 0 && i <= fmEnd,
         frontmatter,
+        frontmatterSchemas: selectFrontmatterSchemas(opts.config?.frontmatterSchemas, opts.path),
         ast: parseAstSafely(source, opts.parseAst),
         resolveLink: opts.resolveLink,
     };
@@ -119,36 +141,48 @@ function parseAstSafely(source, parseAst) {
  */
 export function lintSource(source, opts = {}) {
     const ctx = buildLintContext(source, opts);
-    const rules = opts.rules ?? SFORA_LINT_RULES;
+    const resolved = resolveLintRules(opts.rules ?? SFORA_LINT_RULES, opts.config);
     const out = [];
-    for (const rule of rules) {
-        if (rule.needsAst && !ctx.ast)
+    for (const entry of resolved) {
+        if (entry.rule.needsAst && !ctx.ast)
+            continue;
+        if (!scopeAdmits(entry, opts.path))
             continue;
         try {
-            out.push(...rule.run(ctx));
+            const produced = entry.rule.run(ctx);
+            // A severity override is applied HERE rather than inside the rule: a
+            // rule states what kind of loss it found, and the workspace states how
+            // loudly it wants to hear about that kind. Neither gets to be the other.
+            out.push(...(entry.severity === undefined
+                ? produced
+                : produced.map((d) => ({ ...d, severity: entry.severity }))));
         }
         catch {
             // A broken rule is a missing mark, never a broken editor.
         }
     }
+    // Document order first, and severity only to break a tie at the same span —
+    // a gutter reads top to bottom, and re-ordering by severity would move a
+    // mark away from the line it is about.
     return out.sort((a, b) => a.from !== b.from
         ? a.from - b.from
         : a.to !== b.to
             ? a.to - b.to
-            : a.ruleId.localeCompare(b.ruleId));
+            : severityRank(a.severity) !== severityRank(b.severity)
+                ? severityRank(a.severity) - severityRank(b.severity)
+                : a.ruleId.localeCompare(b.ruleId));
 }
 /**
- * Apply a fix to the source it was computed against. Edits are applied last
- * one first so earlier offsets stay valid — the same reason the editor
- * dispatches them as one transaction.
+ * Apply a fix to the source it was computed against.
+ *
+ * All of it or none of it. The edits are applied last-one-first so earlier
+ * offsets stay valid — the same reason the editor dispatches them as one
+ * transaction — and a fix whose edits do not compose (out of range, inverted,
+ * overlapping) returns the source untouched rather than landing the half of
+ * itself that happened to fit. See ./textEdits for the mechanics and
+ * `tryApplyEdits` for the version that says WHY it declined.
  */
 export function applyLintFix(source, fix) {
-    const edits = [...fix.edits].sort((a, b) => b.from - a.from);
-    let out = source;
-    for (const edit of edits) {
-        if (edit.from < 0 || edit.to > out.length || edit.from > edit.to)
-            continue;
-        out = out.slice(0, edit.from) + edit.insert + out.slice(edit.to);
-    }
-    return out;
+    const result = tryApplyEdits(source, fix.edits);
+    return result.ok ? result.text : source;
 }

package/dist/format/lint/rules/frontmatter-schema.d.ts

@@ -0,0 +1,2 @@
+import type { LintRule } from "../types.js";
+export declare const frontmatterSchemaRule: LintRule;

package/dist/format/lint/rules/frontmatter-schema.js

@@ -0,0 +1,92 @@
+// 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 frontmatter a workspace SAID this kind of document would carry.
+//
+// The sibling of `malformed-frontmatter`, and the seam that rule's docblock
+// named: "What the VALUES mean (a `status:` that is not a real status, a
+// missing required key) is schema validation, and it belongs to the frontmatter
+// schema, not here. The registry is the seam where that rule lands when it
+// exists." This is it (card #299).
+//
+// The split holds in both directions. That rule asks whether sfora's own parser
+// will READ a line; this one asks whether what it read is what the workspace
+// declared. A line with no colon is dropped by `parseYaml`, so this rule never
+// sees the key and never says a word about it — the other rule already did, and
+// two marks on one line for one mistake is how a gutter stops being read.
+//
+// OFF UNTIL DECLARED. With no `frontmatterSchemas` in the lint config this rule
+// costs one property lookup and returns nothing, which is the state every
+// workspace is in until it writes one down.
+import { frontmatterKeyLines, readFrontmatter, validateFrontmatter, } from "../frontmatterSchema.js";
+import { lineText } from "../lintSource.js";
+const RULE_ID = "sfora/frontmatter-schema";
+export const frontmatterSchemaRule = {
+    id: RULE_ID,
+    run(ctx) {
+        const schemas = ctx.frontmatterSchemas;
+        if (!schemas || schemas.length === 0)
+            return [];
+        const block = ctx.frontmatter;
+        // An UNCLOSED block is `malformed-frontmatter`'s error and nobody else's.
+        // Reading fields out of a block whose end nobody knows would report a
+        // missing `status` on a document whose entire body is being read as
+        // frontmatter — the exact misdirection open-knowledge documents as a sharp
+        // edge in its own stack (a YAML error yielding zero diagnostics and then a
+        // missing-property complaint). Declining is the honest answer.
+        if (block && block.close === -1)
+            return [];
+        // No block at all is still a document to grade: a `decision` that forgot
+        // its frontmatter entirely is missing every required key, and saying so at
+        // the top of the file is more use than silence. The values are empty, so
+        // only `required` can fire.
+        const data = block ? readFrontmatter(ctx.lines, block) : {};
+        const keyLines = block
+            ? frontmatterKeyLines(ctx.lines, block)
+            : new Map();
+        const openStart = ctx.lineStart(0);
+        const openEnd = openStart + lineText(ctx.lines, 0).length;
+        const out = [];
+        for (const violation of validateFrontmatter(data, schemas)) {
+            const line = keyLines.get(violation.key);
+            const from = line === undefined ? openStart : ctx.lineStart(line);
+            const to = line === undefined ? openEnd : from + lineText(ctx.lines, line).length;
+            out.push({
+                from,
+                to,
+                severity: violation.severity,
+                ruleId: RULE_ID,
+                message: violation.message,
+                // A fix only where there is exactly one thing to do: a value the
+                // schema all but named — a `const`, a one-member `enum`, or an enum
+                // entry the author spelled with the wrong case — replaced in place.
+                //
+                // What is deliberately absent is the other half somebody will ask for:
+                // INSERTING a missing required key. Where a key goes inside a metadata
+                // block is the author's ordering, and inventing a value for a field the
+                // document does not have is a validator writing the document. Worse for
+                // a document with no block at all, where the fix would have to insert
+                // the `---` fences and so reinterpret every byte under them. The mark
+                // stands; the author writes the line.
+                ...(violation.kind === "invalid" &&
+                    line !== undefined &&
+                    violation.suggestion !== undefined
+                    ? {
+                        fixes: [
+                            {
+                                label: `Set \`${violation.key}\` to \`${violation.suggestion}\``,
+                                edits: [
+                                    {
+                                        from,
+                                        to,
+                                        insert: `${violation.key}: ${violation.suggestion}`,
+                                    },
+                                ],
+                            },
+                        ],
+                    }
+                    : {}),
+            });
+        }
+        return out;
+    },
+};

package/dist/format/lint/rules/index.d.ts

@@ -1,4 +1,5 @@
 import { brokenWikiLinkRule } from "./broken-wiki-link.js";
+import { frontmatterSchemaRule } from "./frontmatter-schema.js";
 import { malformedCalloutRule } from "./malformed-callout.js";
 import { malformedChecklistRule } from "./malformed-checklist.js";
 import { malformedFrontmatterRule } from "./malformed-frontmatter.js";
@@ -7,4 +8,4 @@ import { malformedWikiLinkRule } from "./malformed-wiki-link.js";
 import { orphanReferenceRule } from "./orphan-reference.js";
 import type { LintRule } from "../types.js";
 export declare const SFORA_LINT_RULES: readonly LintRule[];
-export { brokenWikiLinkRule, malformedCalloutRule, malformedChecklistRule, malformedFrontmatterRule, malformedStructuredBlockRule, malformedWikiLinkRule, orphanReferenceRule, };
+export { brokenWikiLinkRule, frontmatterSchemaRule, malformedCalloutRule, malformedChecklistRule, malformedFrontmatterRule, malformedStructuredBlockRule, malformedWikiLinkRule, orphanReferenceRule, };

package/dist/format/lint/rules/index.js

@@ -8,6 +8,7 @@
 //
 // Adding a rule is adding a file and a line here. Nothing else knows the list.
 import { brokenWikiLinkRule } from "./broken-wiki-link.js";
+import { frontmatterSchemaRule } from "./frontmatter-schema.js";
 import { malformedCalloutRule } from "./malformed-callout.js";
 import { malformedChecklistRule } from "./malformed-checklist.js";
 import { malformedFrontmatterRule } from "./malformed-frontmatter.js";
@@ -22,5 +23,10 @@ export const SFORA_LINT_RULES = [
     orphanReferenceRule,
     malformedChecklistRule,
     malformedFrontmatterRule,
+    // After the structural frontmatter rule on purpose. A block whose SHAPE is
+    // wrong and a block whose VALUES are wrong are different complaints, and the
+    // gutter should read the shape first: a line the parser dropped is not a
+    // missing required key, even though it looks exactly like one.
+    frontmatterSchemaRule,
 ];
-export { brokenWikiLinkRule, malformedCalloutRule, malformedChecklistRule, malformedFrontmatterRule, malformedStructuredBlockRule, malformedWikiLinkRule, orphanReferenceRule, };
+export { brokenWikiLinkRule, frontmatterSchemaRule, malformedCalloutRule, malformedChecklistRule, malformedFrontmatterRule, malformedStructuredBlockRule, malformedWikiLinkRule, orphanReferenceRule, };

package/dist/format/lint/rules/malformed-callout.js

@@ -11,25 +11,30 @@
 // reading them off the mdast tree would only re-derive the same first line of
 // the same blockquote — with a chance of disagreeing with the reader, which is
 // the one thing a linter must never do.
-import { CALLOUT_TYPES, isCalloutType } from "../../callout.js";
+import { CALLOUT_TYPES, resolveCalloutType } from "../../callout.js";
 import { isSkippableLine, lineText } from "../lintSource.js";
 const RULE_ID = "sfora/malformed-callout";
-const QUOTED_MARKER = /^ {0,3}>[ \t]?[ \t]*(\[!([A-Za-z]+)\])/;
+const QUOTED_MARKER = /^ {0,3}>[ \t]?[ \t]*(\[!([A-Za-z]+)\]([+-])?)/;
 const QUOTE_LINE = /^ {0,3}>/;
 /**
- * What people write when they mean one of ours. A word maps to a single type
- * or to nothing: `info` reads as both "note" and "tip" depending on who is
- * writing, and a fix that guesses wrong silently changes the document's tone.
- * Ambiguous words still get the diagnostic — just no one-click answer.
+ * What people write when they mean one of ours and the grammar does NOT already
+ * accept it. The real alias table lives in `callout.ts` — `warn`, `error`,
+ * `summary` and the rest resolve to a type and never reach this rule — so what
+ * is left here is near-misses: plurals, and words that name a tone we spell
+ * differently.
+ *
+ * A word maps to a single type or to nothing: `alert` reads as both "warning"
+ * and "caution" depending on who is writing, and a fix that guesses wrong
+ * silently changes the document's tone. Ambiguous words still get the
+ * diagnostic — just no one-click answer.
  */
-const ALIASES = {
-    warn: ["warning"],
+const NEAR_MISSES = {
     warnings: ["warning"],
-    error: ["caution"],
-    danger: ["caution"],
-    attention: ["important"],
-    info: ["note", "tip"],
-    hint: ["note", "tip"],
+    notes: ["note"],
+    tips: ["tip"],
+    urgent: ["important"],
+    alert: ["warning", "caution"],
+    reminder: ["note", "todo"],
 };
 export const malformedCalloutRule = {
     id: RULE_ID,
@@ -47,10 +52,14 @@ export const malformedCalloutRule = {
             if (i > 0 && QUOTE_LINE.test(lineText(ctx.lines, i - 1)))
                 continue;
             const keyword = match[2];
-            if (isCalloutType(keyword))
+            if (resolveCalloutType(keyword))
                 continue;
+            // The fold marker is grammar, not part of the type, so a one-click fix
+            // rewrites the word and puts the `+`/`-` back — otherwise accepting the
+            // fix would quietly un-collapse the callout.
+            const fold = match[3] ?? "";
             const markerStart = ctx.lineStart(i) + line.indexOf(match[1]);
-            const candidates = ALIASES[keyword.toLowerCase()] ?? [];
+            const candidates = NEAR_MISSES[keyword.toLowerCase()] ?? [];
             const fixes = candidates.length === 1
                 ? [
                     {
@@ -59,7 +68,7 @@ export const malformedCalloutRule = {
                             {
                                 from: markerStart,
                                 to: markerStart + match[1].length,
-                                insert: `[!${candidates[0].toUpperCase()}]`,
+                                insert: `[!${candidates[0].toUpperCase()}]${fold}`,
                             },
                         ],
                     },

package/dist/format/lint/rules/malformed-checklist.js

@@ -4,8 +4,13 @@
 //
 // `- [] ship it`, `- [ x] ship it`, `- [x]ship it` — all three look like tasks
 // to a human and count as none to `checklistProgress`, so the card says 0/3
-// and nobody can see why. Info, not warning: the line still reads fine, it
-// just is not counted.
+// and nobody can see why.
+//
+// A HINT, the quietest of the four levels, and the only rule that sits there.
+// It is the level for "the render is exactly right and a derived number is
+// not": nothing on the page is missing or wrong — the line reads as the author
+// wrote it — and the only casualty is a progress count computed somewhere
+// else. Everything louder is reserved for bytes that do not reach the reader.
 //
 // Deliberately narrow. Only bullet lines, only brackets holding nothing but a
 // space or an `x`, and only when there is text after them — `- []` on its own
@@ -44,7 +49,7 @@ export const malformedChecklistRule = {
             out.push({
                 from,
                 to: from + line.length,
-                severity: "info",
+                severity: "hint",
                 ruleId: RULE_ID,
                 message: "This isn't a task checkbox, so it won't be counted. Tasks are exactly `- [ ] ` or `- [x] `.",
                 fixes: [

package/dist/format/lint/rules/malformed-frontmatter.js

@@ -27,7 +27,12 @@ export const malformedFrontmatterRule = {
                 {
                     from: openStart,
                     to: openStart + lineText(ctx.lines, 0).length,
-                    severity: "warning",
+                    // The one error in sfora-law. Every other rule costs the author a
+                    // sentence, a link or a count; this one costs the document its
+                    // entire identity — no title, no status, no id, and a body that
+                    // starts with three dashes. Nothing downstream of the mark means
+                    // what it says.
+                    severity: "error",
                     ruleId: RULE_ID,
                     // No fix: where the block was meant to end is the author's
                     // knowledge, and guessing turns their first paragraph into metadata.

package/dist/format/lint/severity.d.ts

@@ -0,0 +1,15 @@
+/** Most severe first. The order IS the rank. */
+export declare const LINT_SEVERITIES: readonly ["error", "warning", "info", "hint"];
+/**
+ * Nothing in sfora-law is an alarm. Even `error` only says "sfora will read
+ * this differently than you will" — the bytes on disk are always the user's to
+ * keep, and no rule here ever refuses a document.
+ */
+export type LintSeverity = (typeof LINT_SEVERITIES)[number];
+/** 0 for `error`, 3 for `hint`. Lower is more severe. */
+export declare function severityRank(severity: LintSeverity): number;
+/** Negative when `a` is more severe than `b`. Sorts most-severe-first. */
+export declare function compareSeverity(a: LintSeverity, b: LintSeverity): number;
+/** True when `severity` is at least as severe as `floor`. */
+export declare function atLeastAsSevere(severity: LintSeverity, floor: LintSeverity): boolean;
+export declare function isLintSeverity(value: unknown): value is LintSeverity;