sfora-cli 0.9.0 → 0.11.0

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

@@ -0,0 +1,92 @@
+export type SuspiciousGlobReason = 
+/** `docs/` — a document path never ends in a separator, so this matches nothing. */
+"trailing-slash"
+/** `/docs/**` — sfora fs paths are relative; nothing starts with a separator. */
+ | "leading-slash"
+/** `docs\**` — a Windows separator in a path made of forward slashes. */
+ | "backslash"
+/** `docs**` — `**` only spans segments between separators; here it means `*`. */
+ | "undelimited-globstar"
+/** `docs` — no glob character and no extension, so it can only name a folder. */
+ | "folder-not-document";
+export interface InvalidGlob {
+    pattern: string;
+    detail: string;
+}
+export interface SuspiciousGlob {
+    pattern: string;
+    reason: SuspiciousGlobReason;
+    /** What the author probably meant, when there is one obvious answer. */
+    suggestion?: string;
+}
+export interface CompiledAppliesTo {
+    /** Patterns that are not globs at all. They match nothing and are reported. */
+    invalid: InvalidGlob[];
+    /** Patterns that compiled but almost certainly do not mean what they say. */
+    suspicious: SuspiciousGlob[];
+    /** True when no positive pattern was authored — the scope is "everything". */
+    matchesEverything: boolean;
+    /** Does `path` fall in scope? `undefined` and `""` never do. */
+    matches(path: string | undefined): boolean;
+}
+/**
+ * Translate one glob body to a regular expression.
+ *
+ * Supported: `*` (within a segment), `**` (across segments, only when it is a
+ * whole segment), `?` (one non-separator character), `[abc]` / `[!abc]`
+ * character classes, and one level of `{a,b}` alternation. Everything else is
+ * matched literally. Throws on a pattern that cannot be read — an unbalanced
+ * bracket or brace — because a half-read glob would match the wrong documents
+ * silently, and the caller turns the throw into a reported diagnostic.
+ */
+export declare function globToRegExp(body: string): RegExp;
+/** Everything doubtful about one already-compilable pattern body. */
+export declare function suspicionsOf(body: string): SuspiciousGlob[];
+/**
+ * Compile a rule's scope.
+ *
+ * A leading `!` negates: the pattern excludes rather than includes. With no
+ * positive pattern at all the scope is everything, so a config that lists only
+ * exclusions still means "every document except these" rather than "none".
+ */
+export declare function compileAppliesTo(appliesTo: string | readonly string[] | undefined): CompiledAppliesTo;
+/**
+ * INCLUDES that match none of the documents the workspace actually has.
+ *
+ * The strongest signal there is, and the only one that needs the world. A
+ * pattern can be perfectly formed and perfectly plausible and still be a typo
+ * — `doc` where the workspace spells the folder `docs` — and nothing but the
+ * corpus says so. Callers with no corpus to hand simply do not ask.
+ *
+ * Negations are NOT judged here, and that is the whole subtlety. An include
+ * that matches nothing turns the rule off; an exclusion that matches nothing
+ * turns nothing off — `["docs/**", "!docs/archive/**"]` on a workspace with no
+ * archive yet is not a mistake, it is a workspace that has not archived
+ * anything. Corpus emptiness is the author's caution, not their typo. What CAN
+ * be wrong about a negation is structural, and {@link findUnreachableNegations}
+ * is where that is asked.
+ */
+export declare function findZeroMatchPatterns(appliesTo: string | readonly string[] | undefined, knownPaths: readonly string[]): string[];
+/**
+ * Exclusions that could never subtract anything from this scope's includes.
+ *
+ * The question a negation answers to is not "does the workspace hold a file
+ * here today" but "could a document this scope includes ever land here". A
+ * scope of `["docs/**", "!notes/**"]` excludes a tree it never included: the
+ * two patterns cannot meet on any path at all, so the `!` is doing nothing and
+ * almost certainly names the wrong folder. That verdict needs no corpus, which
+ * is why it is reported whether or not one was given.
+ *
+ * With no include at all the scope is "everything", so every well-formed
+ * negation can reach something and none are reported.
+ */
+export declare function findUnreachableNegations(appliesTo: string | readonly string[] | undefined): string[];
+/**
+ * Could any one path be matched by both globs?
+ *
+ * Deliberately one-sided: it answers `false` only when the two are provably
+ * disjoint, and `true` for anything it cannot decide. Two globs meeting is the
+ * normal case, and a diagnostic that fires on a scope the author got right is
+ * worse than one that misses a scope they got wrong.
+ */
+export declare function globsCanIntersect(a: string, b: string): boolean;

package/dist/format/lint/appliesTo.js

@@ -0,0 +1,369 @@
+// 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).
+// Path globs for scoping a rule, and the judgement that a glob is suspicious.
+//
+// A workspace narrows a rule with `appliesTo: ["projects/*/docs/**"]`. That is
+// a small feature with a large failure mode: a glob that matches nothing is
+// indistinguishable, from the outside, from a rule that found nothing to say.
+// The workspace turns a rule off by accident and the linter's silence looks
+// like a clean bill of health. So the compiler reports what it could not
+// compile AND what it compiled but doubts, and `lintLintConfig` turns both
+// into diagnostics — the linter linting its own config.
+//
+// The matcher is hand-rolled rather than picomatch. This module is copied
+// verbatim into the published CLI by `packages/sfora/scripts/sync-format.mjs`,
+// and the lint core's standing contract is that it carries no third-party
+// import; a glob dialect this small is not worth breaking that for. What it
+// supports is stated below and tested; anything outside it is a literal.
+//
+// The SUSPICION rules are sfora's, not a port. Open-knowledge flags a doc
+// extension in a pattern because their document names are extensionless —
+// every sfora fs path ends in `.md` (see `markdown/slug.ts:91`), so for us the
+// extension is normal and its ABSENCE, on a pattern with no glob character at
+// all, is the tell: `docs` names a folder that no document is ever called.
+/** Extensions a sfora document path ends in. `markdown/slug.ts` is the source. */
+const DOC_EXTENSIONS = [".md"];
+const GLOB_CHARS = /[*?[\]{}]/;
+/** `a/b/../c` and `./a` normalized the one way the fs surface writes them. */
+function normalizePath(path) {
+    let out = path.replace(/\\/g, "/");
+    while (out.startsWith("./"))
+        out = out.slice(2);
+    return out;
+}
+/**
+ * Translate one glob body to a regular expression.
+ *
+ * Supported: `*` (within a segment), `**` (across segments, only when it is a
+ * whole segment), `?` (one non-separator character), `[abc]` / `[!abc]`
+ * character classes, and one level of `{a,b}` alternation. Everything else is
+ * matched literally. Throws on a pattern that cannot be read — an unbalanced
+ * bracket or brace — because a half-read glob would match the wrong documents
+ * silently, and the caller turns the throw into a reported diagnostic.
+ */
+export function globToRegExp(body) {
+    let out = "";
+    let braceDepth = 0;
+    let i = 0;
+    while (i < body.length) {
+        const c = body[i];
+        if (c === "*") {
+            const doubled = body[i + 1] === "*";
+            if (doubled) {
+                // `**/` eats whole segments including none at all; a trailing `**`
+                // eats the rest of the path. `a**b` is not a globstar — the caller
+                // flags it and we read it as a single `*`.
+                const atSegmentStart = i === 0 || body[i - 1] === "/";
+                const followedBySlash = body[i + 2] === "/";
+                const atEnd = i + 2 === body.length;
+                if (atSegmentStart && followedBySlash) {
+                    out += "(?:[^/]*\\/)*";
+                    i += 3;
+                    continue;
+                }
+                if (atSegmentStart && atEnd) {
+                    out += ".*";
+                    i += 2;
+                    continue;
+                }
+                out += "[^/]*";
+                i += 2;
+                continue;
+            }
+            out += "[^/]*";
+            i += 1;
+            continue;
+        }
+        if (c === "?") {
+            out += "[^/]";
+            i += 1;
+            continue;
+        }
+        if (c === "[") {
+            const close = body.indexOf("]", i + 1);
+            if (close === -1)
+                throw new Error("unclosed `[`");
+            let body_ = body.slice(i + 1, close);
+            if (body_ === "")
+                throw new Error("empty character class");
+            const negated = body_.startsWith("!") || body_.startsWith("^");
+            if (negated)
+                body_ = body_.slice(1);
+            if (body_ === "")
+                throw new Error("empty character class");
+            out += `[${negated ? "^" : ""}${body_.replace(/\\/g, "\\\\")}]`;
+            i = close + 1;
+            continue;
+        }
+        if (c === "{") {
+            if (braceDepth > 0)
+                throw new Error("nested `{`");
+            braceDepth += 1;
+            out += "(?:";
+            i += 1;
+            continue;
+        }
+        if (c === "}") {
+            if (braceDepth === 0)
+                throw new Error("unmatched `}`");
+            braceDepth -= 1;
+            out += ")";
+            i += 1;
+            continue;
+        }
+        if (c === "," && braceDepth > 0) {
+            out += "|";
+            i += 1;
+            continue;
+        }
+        out += c.replace(/[.+^$()|\\]/g, "\\$&");
+        i += 1;
+    }
+    if (braceDepth > 0)
+        throw new Error("unclosed `{`");
+    return new RegExp(`^${out}$`);
+}
+/** Everything doubtful about one already-compilable pattern body. */
+export function suspicionsOf(body) {
+    const out = [];
+    if (body.includes("\\")) {
+        out.push({
+            pattern: body,
+            reason: "backslash",
+            suggestion: body.replace(/\\/g, "/"),
+        });
+    }
+    if (body.endsWith("/")) {
+        out.push({
+            pattern: body,
+            reason: "trailing-slash",
+            suggestion: `${body}**`,
+        });
+    }
+    if (body.startsWith("/")) {
+        out.push({
+            pattern: body,
+            reason: "leading-slash",
+            suggestion: body.slice(1),
+        });
+    }
+    for (let i = 0; i < body.length - 1; i++) {
+        if (body[i] !== "*" || body[i + 1] !== "*")
+            continue;
+        const atSegmentStart = i === 0 || body[i - 1] === "/";
+        const atSegmentEnd = i + 2 === body.length || body[i + 2] === "/";
+        if (atSegmentStart && atSegmentEnd) {
+            i += 1;
+            continue;
+        }
+        out.push({ pattern: body, reason: "undelimited-globstar" });
+        break;
+    }
+    if (!GLOB_CHARS.test(body) && !body.includes("\\")) {
+        const lower = body.toLowerCase();
+        const hasExtension = DOC_EXTENSIONS.some((ext) => lower.endsWith(ext));
+        if (!hasExtension && !body.endsWith("/") && !body.startsWith("/")) {
+            out.push({
+                pattern: body,
+                reason: "folder-not-document",
+                suggestion: `${body}/**`,
+            });
+        }
+    }
+    return out;
+}
+function authoredPatterns(appliesTo) {
+    const raw = appliesTo === undefined
+        ? []
+        : typeof appliesTo === "string"
+            ? [appliesTo]
+            : [...appliesTo];
+    return raw.map((pattern) => pattern.trim()).filter((p) => p.length > 0);
+}
+/**
+ * Compile a rule's scope.
+ *
+ * A leading `!` negates: the pattern excludes rather than includes. With no
+ * positive pattern at all the scope is everything, so a config that lists only
+ * exclusions still means "every document except these" rather than "none".
+ */
+export function compileAppliesTo(appliesTo) {
+    const invalid = [];
+    const suspicious = [];
+    const positive = [];
+    const negative = [];
+    let positiveCount = 0;
+    for (const pattern of authoredPatterns(appliesTo)) {
+        const negated = pattern.startsWith("!");
+        const body = negated ? pattern.slice(1) : pattern;
+        if (!negated)
+            positiveCount += 1;
+        if (body.length === 0) {
+            invalid.push({ pattern, detail: "empty pattern" });
+            continue;
+        }
+        let re;
+        try {
+            re = globToRegExp(body);
+        }
+        catch (err) {
+            invalid.push({
+                pattern,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        (negated ? negative : positive).push(re);
+        for (const doubt of suspicionsOf(body)) {
+            // `suspicionsOf` reads a BODY and so its repair is a body too. Handing
+            // `notes/**` back for `!notes/` would invert the author's exclusion into
+            // an inclusion — the one edit that changes which documents the rule runs
+            // on, offered as a typo fix. The `!` goes back on.
+            suspicious.push({
+                ...doubt,
+                pattern,
+                ...(negated && doubt.suggestion !== undefined
+                    ? { suggestion: `!${doubt.suggestion}` }
+                    : {}),
+            });
+        }
+    }
+    const matchesEverything = positiveCount === 0;
+    return {
+        invalid,
+        suspicious,
+        matchesEverything,
+        matches(path) {
+            if (path === undefined || path === "")
+                return false;
+            const normalized = normalizePath(path);
+            if (normalized === "")
+                return false;
+            const included = matchesEverything || positive.some((re) => re.test(normalized));
+            if (!included)
+                return false;
+            return !negative.some((re) => re.test(normalized));
+        },
+    };
+}
+/**
+ * INCLUDES that match none of the documents the workspace actually has.
+ *
+ * The strongest signal there is, and the only one that needs the world. A
+ * pattern can be perfectly formed and perfectly plausible and still be a typo
+ * — `doc` where the workspace spells the folder `docs` — and nothing but the
+ * corpus says so. Callers with no corpus to hand simply do not ask.
+ *
+ * Negations are NOT judged here, and that is the whole subtlety. An include
+ * that matches nothing turns the rule off; an exclusion that matches nothing
+ * turns nothing off — `["docs/**", "!docs/archive/**"]` on a workspace with no
+ * archive yet is not a mistake, it is a workspace that has not archived
+ * anything. Corpus emptiness is the author's caution, not their typo. What CAN
+ * be wrong about a negation is structural, and {@link findUnreachableNegations}
+ * is where that is asked.
+ */
+export function findZeroMatchPatterns(appliesTo, knownPaths) {
+    if (knownPaths.length === 0)
+        return [];
+    const normalized = knownPaths
+        .map(normalizePath)
+        .filter((path) => path !== "");
+    const out = [];
+    for (const pattern of authoredPatterns(appliesTo)) {
+        if (pattern.startsWith("!"))
+            continue;
+        if (pattern.length === 0)
+            continue;
+        let re;
+        try {
+            re = globToRegExp(pattern);
+        }
+        catch {
+            // Already reported as invalid; not reported twice as empty.
+            continue;
+        }
+        if (!normalized.some((path) => re.test(path)))
+            out.push(pattern);
+    }
+    return out;
+}
+/**
+ * Exclusions that could never subtract anything from this scope's includes.
+ *
+ * The question a negation answers to is not "does the workspace hold a file
+ * here today" but "could a document this scope includes ever land here". A
+ * scope of `["docs/**", "!notes/**"]` excludes a tree it never included: the
+ * two patterns cannot meet on any path at all, so the `!` is doing nothing and
+ * almost certainly names the wrong folder. That verdict needs no corpus, which
+ * is why it is reported whether or not one was given.
+ *
+ * With no include at all the scope is "everything", so every well-formed
+ * negation can reach something and none are reported.
+ */
+export function findUnreachableNegations(appliesTo) {
+    const patterns = authoredPatterns(appliesTo);
+    const includes = patterns.filter((p) => !p.startsWith("!"));
+    if (includes.length === 0)
+        return [];
+    const out = [];
+    for (const pattern of patterns) {
+        if (!pattern.startsWith("!"))
+            continue;
+        const body = pattern.slice(1);
+        if (body.length === 0)
+            continue;
+        if (!includes.some((include) => globsCanIntersect(body, include))) {
+            out.push(pattern);
+        }
+    }
+    return out;
+}
+/**
+ * Could any one path be matched by both globs?
+ *
+ * Deliberately one-sided: it answers `false` only when the two are provably
+ * disjoint, and `true` for anything it cannot decide. Two globs meeting is the
+ * normal case, and a diagnostic that fires on a scope the author got right is
+ * worse than one that misses a scope they got wrong.
+ */
+export function globsCanIntersect(a, b) {
+    return segmentsIntersect(normalizePath(a).split("/"), normalizePath(b).split("/"));
+}
+function segmentsIntersect(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return true;
+    // A `**` is the only segment that can stand for no segment at all, so it is
+    // the only thing a run-out list can still meet.
+    if (a.length === 0)
+        return b.every((seg) => seg === "**");
+    if (b.length === 0)
+        return a.every((seg) => seg === "**");
+    if (a[0] === "**") {
+        return (segmentsIntersect(a.slice(1), b) || segmentsIntersect(a, b.slice(1)));
+    }
+    if (b[0] === "**") {
+        return (segmentsIntersect(a, b.slice(1)) || segmentsIntersect(a.slice(1), b));
+    }
+    if (!segmentTokensIntersect(a[0], b[0]))
+        return false;
+    return segmentsIntersect(a.slice(1), b.slice(1));
+}
+/** One segment against one segment, same one-sided honesty as above. */
+function segmentTokensIntersect(a, b) {
+    const globA = GLOB_CHARS.test(a);
+    const globB = GLOB_CHARS.test(b);
+    if (!globA && !globB)
+        return a === b;
+    try {
+        if (!globA)
+            return globToRegExp(b).test(a);
+        if (!globB)
+            return globToRegExp(a).test(b);
+    }
+    catch {
+        return true;
+    }
+    // Two patterns. Deciding whether `*.md` and `plan.*` overlap is a language
+    // intersection, and we do not need the answer badly enough to build one.
+    return true;
+}

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;