sfora-cli 0.10.0 → 0.12.0

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

@@ -0,0 +1,106 @@
+import { type CompiledAppliesTo } from "./appliesTo.js";
+import { type FrontmatterSchemaDeclaration } from "./frontmatterSchema.js";
+import { type LintSeverity } from "./severity.js";
+import type { LintRule } from "./types.js";
+/** A severity, or `off` to silence the rule entirely. */
+export type LintSeveritySetting = LintSeverity | "off";
+export interface LintRuleSettings {
+    /** Report this rule's diagnostics at another level, or not at all. */
+    severity?: LintSeveritySetting;
+    /**
+     * Path globs the rule is limited to. A leading `!` excludes. Absent means
+     * every document.
+     */
+    appliesTo?: string | readonly string[];
+}
+export interface LintConfig {
+    /** Keyed by rule id — `sfora/broken-wiki-link`, not `broken-wiki-link`. */
+    rules?: Readonly<Record<string, LintRuleSettings>>;
+    /**
+     * The frontmatter schemas this workspace holds its documents to — the third
+     * key the docblock above predicted, arrived at on card #299.
+     *
+     * It is the one dial that ADDS a check rather than moving or silencing one,
+     * and it does not contradict the decision above, because a schema is not a
+     * style layer: it is the workspace stating its own law for a kind of
+     * document, which is the only kind of rule sfora-law has ever carried. What
+     * makes it safe is that it is empty by default and that it cannot invent a
+     * rule id — the check runs under `sfora/frontmatter-schema`, which the
+     * registry declares and the two dials above can turn off and re-level like
+     * any other.
+     *
+     * The declarations get linted too, by `lintFrontmatterSchemas` in
+     * ./frontmatterSchema, for exactly the reason this file lints its own config.
+     */
+    frontmatterSchemas?: readonly FrontmatterSchemaDeclaration[];
+}
+/**
+ * A complaint about the CONFIG rather than about a document.
+ *
+ * Deliberately not a `SforaDiagnostic`: there are no byte offsets here,
+ * because the config is an object and may never have been text. `at` is a JSON
+ * path into it — `["rules", "sfora/broken-wiki-link", "appliesTo", 0]` — which
+ * a settings UI can turn into a field and an agent can turn into a sentence.
+ * A shape that faked `from`/`to` would be lying to every consumer that draws a
+ * squiggle at them.
+ */
+export interface LintConfigDiagnostic {
+    severity: LintSeverity;
+    /** Namespaced like a rule id, and stable: `sfora/config-suspicious-glob`. */
+    ruleId: string;
+    message: string;
+    at: (string | number)[];
+}
+export declare const CONFIG_RULE_IDS: {
+    readonly unknownRule: "sfora/config-unknown-rule";
+    readonly invalidSeverity: "sfora/config-invalid-severity";
+    readonly invalidGlob: "sfora/config-invalid-glob";
+    readonly suspiciousGlob: "sfora/config-suspicious-glob";
+    readonly emptyScope: "sfora/config-glob-matches-nothing";
+    readonly deadNegation: "sfora/config-negation-excludes-nothing";
+};
+export interface LintConfigOptions {
+    /** The registry the config's rule ids are checked against. */
+    rules?: readonly LintRule[];
+    /**
+     * Document paths the workspace actually holds. When given, a pattern that
+     * matches none of them is reported. Without it that check is skipped rather
+     * than guessed at.
+     */
+    knownPaths?: readonly string[];
+}
+/**
+ * Read the config back and report everything about it that will silently cost
+ * the workspace a rule.
+ *
+ * Ordered by config path so two runs over the same object agree, and so a UI
+ * can group the marks by field without sorting them itself: the `rules` map
+ * first, sorted by rule id, then `frontmatterSchemas` in declaration order.
+ */
+export declare function lintLintConfig(config: LintConfig | undefined, opts?: LintConfigOptions): LintConfigDiagnostic[];
+/** A rule paired with the settings that apply to it, scope already compiled. */
+export interface ResolvedLintRule {
+    rule: LintRule;
+    /** What its diagnostics report at, after any override. */
+    severity?: LintSeverity;
+    scope?: CompiledAppliesTo;
+}
+/**
+ * Apply the config to the registry.
+ *
+ * A rule set to `off` is dropped here rather than filtered later, so a
+ * disabled rule costs no work at all. A rule with a scope keeps it: whether it
+ * runs depends on the document's path, which the runner knows and this
+ * function does not.
+ */
+export declare function resolveLintRules(rules: readonly LintRule[], config: LintConfig | undefined): ResolvedLintRule[];
+/**
+ * Does a scoped rule run on this document?
+ *
+ * Fail-OPEN when the caller gave no path. A scope narrows a rule; a document
+ * whose path we do not know cannot be shown to fall outside one, and a linter
+ * of laws would rather post a mark the workspace scoped away than go quiet on
+ * a document it simply could not place. Every caller that HAS a path passes
+ * it, and the editor is the only one that sometimes does not.
+ */
+export declare function scopeAdmits(resolved: ResolvedLintRule, path: string | undefined): boolean;

package/dist/format/lint/config.js

@@ -0,0 +1,205 @@
+// 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).
+// What a workspace is allowed to say about sfora-law, and the linter that
+// reads it back.
+//
+// Two dials, deliberately: a rule can be turned OFF or moved to another
+// SEVERITY, and it can be SCOPED to a set of paths. Nothing else. There is no
+// dial that adds a rule, because there is no generic style layer behind these
+// seven to add (board card #225, decided: sfora lints its own laws, not user
+// style). What this file is for is the other half of that decision — the door
+// stays open. A workspace-level opt-in, if one is ever wanted, is a third key
+// in `LintConfig` and a second registry passed to `lintSource`; every consumer
+// downstream of here already reads severities it did not choose and scopes it
+// did not write. Nothing about that future costs anything today.
+//
+// The config is DATA, not a file format. This module never reads a file and
+// never parses YAML — where the object comes from (frontmatter, a Convex row,
+// a CLI flag) is the caller's business, and keeping it that way is what lets
+// the same resolution run in the editor, the CLI and a Convex mutation.
+//
+// And the config gets linted. A rule id with a typo in it, a severity that is
+// not one of the four, a glob that matches nothing — each of those turns a
+// rule off silently, which is the worst thing a linter can do, because the
+// symptom is a clean document. `lintLintConfig` is what makes that loud.
+import { compileAppliesTo, findUnreachableNegations, findZeroMatchPatterns, } from "./appliesTo.js";
+import { lintFrontmatterSchemas, } from "./frontmatterSchema.js";
+import { isLintSeverity, LINT_SEVERITIES } from "./severity.js";
+export const CONFIG_RULE_IDS = {
+    unknownRule: "sfora/config-unknown-rule",
+    invalidSeverity: "sfora/config-invalid-severity",
+    invalidGlob: "sfora/config-invalid-glob",
+    suspiciousGlob: "sfora/config-suspicious-glob",
+    emptyScope: "sfora/config-glob-matches-nothing",
+    deadNegation: "sfora/config-negation-excludes-nothing",
+};
+const SUSPICION_MESSAGE = {
+    "trailing-slash": "ends in `/`, and no document path does — this pattern matches nothing.",
+    "leading-slash": "starts with `/`, and sfora paths are relative — this pattern matches nothing.",
+    backslash: "uses `\\` as a separator; sfora paths are written with `/`.",
+    "undelimited-globstar": "has a `**` that is not a whole path segment, so it behaves as a plain `*`.",
+    "folder-not-document": "names a folder, and every sfora document path ends in a file extension — this pattern matches nothing.",
+};
+/**
+ * Read the config back and report everything about it that will silently cost
+ * the workspace a rule.
+ *
+ * Ordered by config path so two runs over the same object agree, and so a UI
+ * can group the marks by field without sorting them itself: the `rules` map
+ * first, sorted by rule id, then `frontmatterSchemas` in declaration order.
+ */
+export function lintLintConfig(config, opts = {}) {
+    const rules = opts.rules;
+    const known = rules ? new Set(rules.map((rule) => rule.id)) : null;
+    const out = [];
+    const entries = Object.entries(config?.rules ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    for (const [ruleId, settings] of entries) {
+        const at = ["rules", ruleId];
+        if (known && !known.has(ruleId)) {
+            out.push({
+                severity: "warning",
+                ruleId: CONFIG_RULE_IDS.unknownRule,
+                // Naming the near miss is the whole value of the mark: the typo is
+                // almost always a namespace that has been dropped or doubled.
+                message: `\`${ruleId}\` is not a sfora-law rule, so this setting does nothing.${nearest(ruleId, known)}`,
+                at,
+            });
+            // Still check the globs below: the id may be fixed later and the scope
+            // kept, and reporting one problem at a time is a slow way to fix two.
+        }
+        const severity = settings?.severity;
+        if (severity !== undefined && severity !== "off" && !isLintSeverity(severity)) {
+            out.push({
+                severity: "warning",
+                ruleId: CONFIG_RULE_IDS.invalidSeverity,
+                message: `\`${String(severity)}\` is not a severity. Use ${LINT_SEVERITIES.join(", ")} or \`off\`.`,
+                at: [...at, "severity"],
+            });
+        }
+        const appliesTo = settings?.appliesTo;
+        if (appliesTo === undefined)
+            continue;
+        const compiled = compileAppliesTo(appliesTo);
+        const patterns = patternList(appliesTo);
+        for (const bad of compiled.invalid) {
+            out.push({
+                severity: "warning",
+                ruleId: CONFIG_RULE_IDS.invalidGlob,
+                message: `\`${bad.pattern}\` is not a usable path pattern (${bad.detail}), so it matches nothing.`,
+                at: [...at, "appliesTo", ...indexOf(patterns, bad.pattern)],
+            });
+        }
+        for (const doubt of compiled.suspicious) {
+            const detail = SUSPICION_MESSAGE[doubt.reason] ?? "does not look like a path pattern.";
+            const hint = doubt.suggestion ? ` Did you mean \`${doubt.suggestion}\`?` : "";
+            out.push({
+                severity: "warning",
+                ruleId: CONFIG_RULE_IDS.suspiciousGlob,
+                message: `\`${doubt.pattern}\` ${detail}${hint}`,
+                at: [...at, "appliesTo", ...indexOf(patterns, doubt.pattern)],
+            });
+        }
+        const dead = new Set(compiled.invalid.map((bad) => bad.pattern));
+        // Structural, so it does not wait on a corpus: an exclusion that cannot
+        // meet any of this scope's includes subtracts nothing, whatever the
+        // workspace happens to hold. An exclusion that CAN meet them and matches
+        // no file today is a workspace with an empty archive folder, which is
+        // caution rather than error and is deliberately silent.
+        for (const pattern of findUnreachableNegations(appliesTo)) {
+            if (dead.has(pattern))
+                continue;
+            out.push({
+                severity: "warning",
+                ruleId: CONFIG_RULE_IDS.deadNegation,
+                message: `\`${pattern}\` excludes a path this rule never includes, so it changes nothing.`,
+                at: [...at, "appliesTo", ...indexOf(patterns, pattern)],
+            });
+        }
+        if (opts.knownPaths && opts.knownPaths.length > 0) {
+            for (const pattern of findZeroMatchPatterns(appliesTo, opts.knownPaths)) {
+                // An invalid pattern matches nothing BECAUSE it is invalid; saying so
+                // twice is noise.
+                if (dead.has(pattern))
+                    continue;
+                out.push({
+                    severity: "info",
+                    ruleId: CONFIG_RULE_IDS.emptyScope,
+                    message: `\`${pattern}\` matches none of this workspace's documents.`,
+                    at: [...at, "appliesTo", ...indexOf(patterns, pattern)],
+                });
+            }
+        }
+    }
+    // The schema declarations, graded by the module that reads them. Their `at`
+    // paths are indices into the declaration list, so they are re-rooted here to
+    // be paths into the CONFIG — a settings UI gets one address space, not two.
+    for (const diagnostic of lintFrontmatterSchemas(config?.frontmatterSchemas)) {
+        out.push({
+            ...diagnostic,
+            at: ["frontmatterSchemas", ...diagnostic.at],
+        });
+    }
+    return out;
+}
+/**
+ * Apply the config to the registry.
+ *
+ * A rule set to `off` is dropped here rather than filtered later, so a
+ * disabled rule costs no work at all. A rule with a scope keeps it: whether it
+ * runs depends on the document's path, which the runner knows and this
+ * function does not.
+ */
+export function resolveLintRules(rules, config) {
+    const settings = config?.rules;
+    if (!settings)
+        return rules.map((rule) => ({ rule }));
+    const out = [];
+    for (const rule of rules) {
+        const entry = settings[rule.id];
+        if (entry?.severity === "off")
+            continue;
+        out.push({
+            rule,
+            ...(entry?.severity !== undefined && isLintSeverity(entry.severity)
+                ? { severity: entry.severity }
+                : {}),
+            ...(entry?.appliesTo !== undefined
+                ? { scope: compileAppliesTo(entry.appliesTo) }
+                : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Does a scoped rule run on this document?
+ *
+ * Fail-OPEN when the caller gave no path. A scope narrows a rule; a document
+ * whose path we do not know cannot be shown to fall outside one, and a linter
+ * of laws would rather post a mark the workspace scoped away than go quiet on
+ * a document it simply could not place. Every caller that HAS a path passes
+ * it, and the editor is the only one that sometimes does not.
+ */
+export function scopeAdmits(resolved, path) {
+    if (!resolved.scope)
+        return true;
+    if (path === undefined || path === "")
+        return true;
+    return resolved.scope.matches(path);
+}
+function patternList(appliesTo) {
+    return typeof appliesTo === "string" ? [appliesTo] : [...appliesTo];
+}
+/** `["appliesTo", 2]`, or just `["appliesTo"]` when the pattern is not found. */
+function indexOf(patterns, pattern) {
+    const index = patterns.findIndex((p) => p.trim() === pattern.trim());
+    return index === -1 ? [] : [index];
+}
+/** The closest real rule id, when one is close enough to be worth naming. */
+function nearest(ruleId, known) {
+    const bare = ruleId.includes("/") ? ruleId.slice(ruleId.indexOf("/") + 1) : ruleId;
+    for (const candidate of known) {
+        if (candidate === `sfora/${bare}`)
+            return ` Did you mean \`${candidate}\`?`;
+    }
+    return "";
+}

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

@@ -0,0 +1,62 @@
+import type { LintFix, LintSourceOptions, SforaDiagnostic } from "./types.js";
+export interface AppliedFix {
+    ruleId: string;
+    label: string;
+    /** The diagnostic's own span, in the source this pass read. */
+    from: number;
+    to: number;
+}
+export interface SkippedFix extends AppliedFix {
+    /** `conflict`: an earlier fix already claimed these bytes.
+     *  `invalid`: the fix's edits do not compose over this source. */
+    reason: "conflict" | "invalid";
+}
+export interface FixAllResult {
+    text: string;
+    applied: AppliedFix[];
+    skipped: SkippedFix[];
+}
+export interface FixAllOptions {
+    /**
+     * Which fix to take when a diagnostic offers several. Defaults to the first,
+     * which every rule in this package orders as its preferred repair.
+     */
+    pick?: (diagnostic: SforaDiagnostic) => LintFix | undefined;
+}
+/**
+ * Compose every diagnostic's preferred fix over `source` in one pass.
+ *
+ * Diagnostics are taken in the order given — `lintSource` returns them in
+ * document order, which is what makes "the first one wins" a stable rule
+ * rather than a coin toss.
+ */
+export declare function fixAll(source: string, diagnostics: readonly SforaDiagnostic[], opts?: FixAllOptions): FixAllResult;
+export interface LintAndFixResult extends FixAllResult {
+    /** What is still wrong after the last pass. The honest bottom line. */
+    remaining: SforaDiagnostic[];
+}
+export interface LintAndFixOptions extends LintSourceOptions, FixAllOptions {
+    /**
+     * How many lint-then-fix rounds to run. More than one because a repair can
+     * uncover a fixable diagnostic that the broken bytes were hiding; a small
+     * cap because a rule pair that undoes each other's work would otherwise
+     * spin forever. A pass that changes nothing ends the loop early.
+     */
+    passes?: number;
+}
+/**
+ * Lint, fix everything fixable, and report what is left.
+ *
+ * The whole autofix surface in one call: give it bytes, get back better bytes
+ * plus an account of what happened to them.
+ *
+ * The two accounts are kept differently, on purpose. `applied` ACCUMULATES:
+ * every repair that landed, landed, and stays in the record. `skipped` is only
+ * the LAST round's refusals — a fix refused for conflict in pass one is
+ * usually applied in pass two, once the fix it collided with has moved out of
+ * the way, and carrying it forward would report the same repair as both done
+ * and refused. What `skipped` answers is "what did this call decline to do to
+ * the text it is handing back", which is a question about the end state.
+ * `remaining` is the final lint over the final text.
+ */
+export declare function lintAndFixAll(source: string, opts?: LintAndFixOptions): LintAndFixResult;

package/dist/format/lint/fixAll.js

@@ -0,0 +1,107 @@
+// 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).
+// Fix-all: every quick fix in a document, composed into one change.
+//
+// The naive version — apply a fix, re-lint, apply the next — is quadratic and
+// wrong in a subtler way: each re-lint sees a document the author never wrote,
+// so the second fix is computed against the first fix's opinion. What this
+// does instead is treat the whole pass as ONE atomic change over the ORIGINAL
+// source. Every fix's offsets stay valid because nothing has moved yet; the
+// accepted edits go in together, reverse-sorted, at the end.
+//
+// That leaves exactly one question: what happens when two rules want the same
+// bytes. `[[]]` inside a dropped `status` line has a fix from each. There is no
+// correct merge — the two edits were computed in ignorance of one another —
+// so the first in document order wins and the second is REPORTED as skipped
+// rather than dropped. A batch that silently discards half its work is how an
+// agent ends up believing a document is clean.
+//
+// The reporting is the point. `applied` and `skipped` are what make this
+// usable without a human watching: an agent PUTs a file, gets back what was
+// repaired, what was refused and why, and what is still wrong. Nothing here
+// touches the network — it is the mechanism such a surface would be four lines
+// of glue over.
+import { lintSource } from "./lintSource.js";
+import { checkEdits, editsConflict, tryApplyEdits } from "./textEdits.js";
+/**
+ * Compose every diagnostic's preferred fix over `source` in one pass.
+ *
+ * Diagnostics are taken in the order given — `lintSource` returns them in
+ * document order, which is what makes "the first one wins" a stable rule
+ * rather than a coin toss.
+ */
+export function fixAll(source, diagnostics, opts = {}) {
+    const pick = opts.pick ?? ((d) => d.fixes?.[0]);
+    const accepted = [];
+    const applied = [];
+    const skipped = [];
+    for (const diagnostic of diagnostics) {
+        const fix = pick(diagnostic);
+        // A diagnostic with no fix is not a skip — nothing was refused. It shows
+        // up in `remaining` instead, which is where an author looks for work.
+        if (!fix || fix.edits.length === 0)
+            continue;
+        const where = {
+            ruleId: diagnostic.ruleId,
+            label: fix.label,
+            from: diagnostic.from,
+            to: diagnostic.to,
+        };
+        if (checkEdits(source, fix.edits) !== null) {
+            skipped.push({ ...where, reason: "invalid" });
+            continue;
+        }
+        const clashes = fix.edits.some((edit) => accepted.some((taken) => editsConflict(edit, taken)));
+        if (clashes) {
+            skipped.push({ ...where, reason: "conflict" });
+            continue;
+        }
+        accepted.push(...fix.edits);
+        applied.push(where);
+    }
+    const result = tryApplyEdits(source, accepted);
+    // `accepted` is conflict-free and in range by construction, so the failure
+    // branch is unreachable — and it returns the untouched source rather than
+    // throwing, because a linter is never the reason a document is damaged.
+    return {
+        text: result.ok ? result.text : source,
+        applied,
+        skipped,
+    };
+}
+/**
+ * Lint, fix everything fixable, and report what is left.
+ *
+ * The whole autofix surface in one call: give it bytes, get back better bytes
+ * plus an account of what happened to them.
+ *
+ * The two accounts are kept differently, on purpose. `applied` ACCUMULATES:
+ * every repair that landed, landed, and stays in the record. `skipped` is only
+ * the LAST round's refusals — a fix refused for conflict in pass one is
+ * usually applied in pass two, once the fix it collided with has moved out of
+ * the way, and carrying it forward would report the same repair as both done
+ * and refused. What `skipped` answers is "what did this call decline to do to
+ * the text it is handing back", which is a question about the end state.
+ * `remaining` is the final lint over the final text.
+ */
+export function lintAndFixAll(source, opts = {}) {
+    const passes = Math.max(1, Math.min(opts.passes ?? 3, 10));
+    let text = source;
+    const applied = [];
+    let skipped = [];
+    let diagnostics = lintSource(text, opts);
+    for (let pass = 0; pass < passes; pass++) {
+        const round = fixAll(text, diagnostics, opts);
+        applied.push(...round.applied);
+        // Only the LAST round's refusals survive. A fix skipped for conflict in
+        // pass one is usually applied in pass two, once the fix it collided with
+        // has landed and moved out of the way; carrying the skip forward would
+        // report work that was refused and then done.
+        skipped = round.skipped;
+        if (round.text === text)
+            break;
+        text = round.text;
+        diagnostics = lintSource(text, opts);
+    }
+    return { text, applied, skipped, remaining: diagnostics };
+}

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

@@ -0,0 +1,181 @@
+import { type CompiledAppliesTo } from "./appliesTo.js";
+import { type LintSeverity } from "./severity.js";
+/**
+ * Every keyword this module reads, and what it does with it.
+ *
+ * The list is exported because it is the contract: {@link lintFrontmatterSchemas}
+ * reports anything outside it, and the test that keeps the two honest reads
+ * this object rather than a second copy of the list.
+ *
+ * `annotation` keywords are read by nobody and reported by nobody — they are
+ * documentation, and a schema that carries a `description` for its agents is
+ * doing the right thing.
+ */
+export declare const SUPPORTED_KEYWORDS: Readonly<Record<string, "constraint" | "annotation">>;
+/**
+ * The `format` values that mean something here.
+ *
+ * Deliberately five, and deliberately the five a sfora frontmatter block
+ * actually holds — a date, a timestamp, a link, an address, a slug. A `format`
+ * outside this set is reported rather than ignored, which is the whole policy
+ * of this file in one line.
+ */
+export declare const SUPPORTED_FORMATS: readonly ["date", "date-time", "uri", "email", "slug"];
+export type FrontmatterFormat = (typeof SUPPORTED_FORMATS)[number];
+/** A JSON Schema as authored. Untyped on purpose: it arrives as data. */
+export type FrontmatterSchema = Record<string, unknown>;
+/**
+ * A workspace's declaration: this schema, for this kind of document, on these
+ * paths.
+ *
+ * `kind` is not a scoping mechanism — `appliesTo` is. It is the WORD the
+ * diagnostic uses, so the author reads "a `decision` document needs a `status`"
+ * rather than "frontmatter property \"status\" is required". A rule that says
+ * which house rule it is enforcing is a rule somebody can go and read.
+ */
+export interface FrontmatterSchemaDeclaration {
+    /** `decision`, `runbook`, `post`. Appears in every message the schema makes. */
+    kind: string;
+    /** Path globs, the `appliesTo` dialect. Absent means every document. */
+    appliesTo?: string | readonly string[];
+    schema: FrontmatterSchema;
+    /**
+     * What this schema's marks report at.
+     *
+     * Absent means the per-constraint defaults in {@link severityFor}, which are
+     * the honest reading of the four-level ladder in ./severity: a key the
+     * document was supposed to carry and does not is a `warning` (the document
+     * will be read as saying something it does not say), and a key nothing in
+     * the schema knows about is an `info` (the author wrote it and nothing will
+     * ever read it — the ladder's definition of `info`, exactly).
+     */
+    severity?: LintSeverity;
+}
+/** A declaration with its scope compiled, ready to run on one document. */
+export interface SelectedFrontmatterSchema {
+    declaration: FrontmatterSchemaDeclaration;
+    scope: CompiledAppliesTo;
+}
+/**
+ * The declarations that apply to `path`.
+ *
+ * Fail-CLOSED where `scopeAdmits` fails open, and the asymmetry is deliberate.
+ * A scoped RULE narrows something that would otherwise run everywhere, so a
+ * document whose path we do not know keeps the rule (see `config.ts`). A
+ * frontmatter schema is the opposite: it exists only for a kind of document,
+ * and running a `decision` schema over an unknown document would report a
+ * missing `status` on a chat message. Silence is the cheaper failure here, and
+ * a declaration with NO `appliesTo` still runs on everything, which is the door
+ * for a workspace that means it.
+ */
+export declare function selectFrontmatterSchemas(declarations: readonly FrontmatterSchemaDeclaration[] | undefined, path: string | undefined): SelectedFrontmatterSchema[];
+/** Which constraint a violation came from. Keys the default severity map. */
+export type FrontmatterViolationKind = 
+/** A `required` key the document does not have. */
+"missing"
+/** A key the schema constrains, holding a value the constraint refuses. */
+ | "invalid"
+/** A key no `properties` entry names, under `additionalProperties: false`. */
+ | "unknown";
+export interface FrontmatterViolation {
+    kind: FrontmatterViolationKind;
+    /** The top-level frontmatter key, or `""` for a whole-block complaint. */
+    key: string;
+    /** The document kind the schema was declared for. */
+    documentKind: string;
+    /** The schema keyword that refused it — `required`, `enum`, `pattern`, … */
+    keyword: string;
+    message: string;
+    severity: LintSeverity;
+    /**
+     * A value that would satisfy the constraint, when there is exactly one
+     * obvious candidate. The rule turns it into a quick fix; nothing else reads
+     * it, and it is absent far more often than it is present.
+     */
+    suggestion?: string;
+}
+/** A YAML value as sfora parses it: a scalar or a flat list of scalars. */
+type FrontmatterValue = string | string[];
+/**
+ * Check one document's frontmatter against every schema declared for it.
+ *
+ * `data` is what `markdown/yaml.ts` read, so this function grades the values
+ * SFORA WILL ACTUALLY USE rather than a second reading of the same bytes. That
+ * matters more than it sounds: a key the tiny YAML drops (no colon, a nested
+ * map) is a key the workspace does not have, and a validator that read it with
+ * a fuller parser would pass a document whose `status` no consumer can see.
+ * The structural half of that — telling the author their line was dropped —
+ * belongs to `malformed-frontmatter`, which is why this rule stays silent about
+ * it instead of saying the same thing twice.
+ */
+export declare function validateFrontmatter(data: Readonly<Record<string, FrontmatterValue>>, schemas: readonly SelectedFrontmatterSchema[]): FrontmatterViolation[];
+/**
+ * Read a frontmatter block's key lines.
+ *
+ * Same reading as `parseYaml` — a top-level `key:` and nothing indented — so
+ * the line a mark lands on is the line the value came from. Duplicate keys
+ * resolve to the FIRST occurrence, which is where `malformed-frontmatter`
+ * already points its own duplicate mark, so the two rules agree about which
+ * line a key is on.
+ */
+export declare function frontmatterKeyLines(lines: readonly string[], block: {
+    open: number;
+    close: number;
+}): Map<string, number>;
+/** The block's body, for `parseYaml`. */
+export declare function frontmatterBody(lines: readonly string[], block: {
+    open: number;
+    close: number;
+}): string;
+/** Read a document's frontmatter the way sfora reads it. */
+export declare function readFrontmatter(lines: readonly string[], block: {
+    open: number;
+    close: number;
+}): Record<string, FrontmatterValue>;
+export declare const FRONTMATTER_SCHEMA_RULE_IDS: {
+    readonly unknownKeyword: "sfora/schema-unknown-keyword";
+    readonly unsupportedType: "sfora/schema-unsupported-type";
+    readonly unsupportedFormat: "sfora/schema-unsupported-format";
+    readonly invalidPattern: "sfora/schema-invalid-pattern";
+    readonly invalidSeverity: "sfora/schema-invalid-severity";
+    readonly invalidGlob: "sfora/schema-invalid-glob";
+    readonly suspiciousGlob: "sfora/schema-suspicious-glob";
+    readonly requiredNotDeclared: "sfora/schema-required-not-declared";
+    readonly emptyKind: "sfora/schema-no-kind";
+};
+/**
+ * A complaint about a SCHEMA rather than about a document.
+ *
+ * The same shape `lintLintConfig` returns, and for the same reason: a schema is
+ * an object and may never have been text, so there are no byte offsets to give.
+ * `at` is a JSON path into the declaration list — `[0, "schema", "properties",
+ * "status", "format"]` — which a settings UI turns into a field.
+ */
+export interface FrontmatterSchemaDiagnostic {
+    severity: LintSeverity;
+    ruleId: string;
+    message: string;
+    at: (string | number)[];
+}
+/**
+ * Types {@link matchesType} can answer for. `object` is deliberately absent.
+ *
+ * Exported for the same reason {@link SUPPORTED_FORMATS} is: it is a promise
+ * about behaviour, and its test drives the spelling each type accepts off this
+ * list rather than off a second copy of it. A type added here without a reading
+ * in `matchesType` fails that test.
+ */
+export declare const SUPPORTED_TYPES: readonly ["string", "array", "number", "integer", "boolean", "null"];
+/**
+ * Read the declarations back and report every part of them that will silently
+ * do nothing.
+ *
+ * This is the promise that makes a supported SUBSET honest. An author writes a
+ * schema, this module reads the keywords it knows, and without this function
+ * every keyword it does not know would be a constraint the author believes is
+ * being enforced and that nothing enforces. `config.ts` calls that "the worst
+ * thing a linter can do, because the symptom is a clean document"; a validator
+ * has the same failure mode one layer up.
+ */
+export declare function lintFrontmatterSchemas(declarations: readonly FrontmatterSchemaDeclaration[] | undefined): FrontmatterSchemaDiagnostic[];
+export {};