@syv-ai/rulecast 0.1.1 → 0.3.0

package/dist/types-C8b7hrnG.d.ts

@@ -0,0 +1,776 @@
+import { ZodType, ZodTypeDef, z } from 'zod';
+
+type EventKind = "touch" | "edit" | "verify" | "prompt" | "reset" | "guard";
+type DetectorEvent = "edit" | "verify";
+type Severity = "error" | "warning";
+type ReferenceMode = "inject" | "read";
+/**
+ * What a `guard` event's write would do, as the agent's tool call describes it and before anything
+ * has touched the disk. The adapter reports the intent; the pipeline turns it into the file's
+ * proposed content, because only the pipeline may read the file it will be applied to.
+ */
+interface WriteIntent {
+    /** The whole file, for a tool that supplies it (Write).*/
+    content?: string;
+    /** A replacement inside the current file (Edit). */
+    edit?: {
+        find: string;
+        replace: string;
+        all: boolean;
+    };
+}
+interface Event {
+    kind: EventKind;
+    /** Repo-relative paths (adapters may give absolute ones; the hook command converts them). Empty for prompt and reset. */
+    files: string[];
+    /** guard only: what the agent is about to write to `files[0]`. */
+    intent?: WriteIntent;
+    /** touch from a read: the whole file was read. */
+    completeRead?: boolean;
+    /** verify from the CLI: the commit the baseline is read from (the merge base for --from-ref). */
+    baseCommit?: string;
+    session?: {
+        id: string;
+        agentId?: string;
+    };
+    cwd: string;
+}
+interface Match {
+    file: string;
+    /** 1-based. */
+    line: number;
+    endLine: number;
+    column: number;
+    text: string;
+    /** Exactly the names the detector declared for the rule. */
+    captures: Record<string, string>;
+}
+interface ChangeSet {
+    /** 1-based inclusive ranges in the current file. */
+    changedLines: [start: number, end: number][];
+}
+interface Cache {
+    get<T>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+}
+interface ResolvedReference {
+    /** "conventions/api-access.md#frontend-data-flow" */
+    ref: string;
+    content: string;
+}
+declare const LLM_PROVIDERS: readonly ["claude-code", "opencode", "anthropic", "openai-compatible"];
+type LlmProviderName = (typeof LLM_PROVIDERS)[number];
+/** Project-level `llm` settings from .rulecast-config.yaml (spec §6, §12). */
+interface LlmSettings {
+    provider: LlmProviderName;
+    /** Overrides the provider's own endpoint; the only way to reach Azure OpenAI or Ollama. */
+    baseUrl: string | null;
+    apiKeyEnv: string;
+    maxFilesPerVerify: number;
+}
+/** Project settings the core passes to every detector run; only `llm` reads them today. */
+interface DetectorSettings {
+    llm: LlmSettings;
+}
+declare function defaultDetectorSettings(): DetectorSettings;
+interface DetectorRuleInput<Config> {
+    id: string;
+    config: Config;
+    files: string[];
+    context: ResolvedReference[];
+}
+interface DetectorRun<Config> {
+    event: DetectorEvent;
+    rules: DetectorRuleInput<Config>[];
+    /**
+     * The file's content, null when it no longer exists. A detector that can read a file itself must
+     * use this instead: before a write, the content that matters is the one the agent proposed, which
+     * is not on disk and never will be if the write is refused.
+     */
+    read(file: string): Promise<string | null>;
+    /** File absent = no baseline, the whole file is new. */
+    changes: ReadonlyMap<string, ChangeSet>;
+    cache: Cache;
+    /** Project settings from .rulecast-config.yaml; a detector that needs none ignores them. */
+    settings: DetectorSettings;
+    cwd: string;
+    signal: AbortSignal;
+    /**
+     * `Date.now()` after which this run's results are discarded (§13). A detector whose work is
+     * synchronous must bound itself against this: `signal` cannot help it, because the timer that
+     * fires it only runs when the event loop is free, and synchronous work is what keeps it busy.
+     */
+    deadlineAt: number;
+}
+interface DetectorResult {
+    findings: {
+        rule: string;
+        match: Match;
+    }[];
+    /** rule null = the whole run failed. */
+    errors: {
+        rule: string | null;
+        message: string;
+    }[];
+}
+interface DetectorWarm<Config> {
+    /** Every rule of this detector kind in the project. */
+    rules: {
+        id: string;
+        config: Config;
+    }[];
+    cache: Cache;
+    cwd: string;
+    signal: AbortSignal;
+}
+interface DetectorCheck<Config> {
+    /** Every rule of this detector kind in the project. */
+    rules: {
+        id: string;
+        config: Config;
+    }[];
+    /** Project settings from .rulecast-config.yaml; the same value a run gets. */
+    settings: DetectorSettings;
+    /** The process environment, so a check can look for credentials without reaching for process.env. */
+    env: Readonly<Record<string, string | undefined>>;
+    cwd: string;
+    signal: AbortSignal;
+}
+/** One thing `rulecast doctor` asked a detector about, and the answer (spec §5). */
+interface CheckResult {
+    /** What was checked, as a person would name it: "ruff", "ast-grep", `model "haiku"`. */
+    what: string;
+    level: "ok" | "warning" | "error";
+    /** Why: a resolved path when it worked, the reason when it did not. */
+    detail: string;
+    /** The rules this result decides the fate of; empty when it is about the kind as a whole. */
+    rules: string[];
+}
+interface Detector<Config> {
+    kind: string;
+    /** Input is unknown: schemas may apply defaults and refinements. */
+    schema: ZodType<Config, ZodTypeDef, unknown>;
+    captures(config: Config): string[];
+    events(config: Config): DetectorEvent[];
+    /**
+     * Whether this detector reads only through `read`, and so can judge a write before it happens
+     * (`refuse_write`). False for anything that hands a path to another program: the proposed file is
+     * not on disk, so ruff, eslint, ast-grep's CLI or a `command` script would judge the old one.
+     */
+    guards?: boolean;
+    run(input: DetectorRun<Config>): Promise<DetectorResult>;
+    /** Optional: build expensive caches ahead of events (rulecast warm, §13). */
+    warm?(input: DetectorWarm<Config>): Promise<void>;
+    /** Optional: report what this detector's rules need from the environment (rulecast doctor, §5). */
+    check?(input: DetectorCheck<Config>): Promise<CheckResult[]>;
+}
+interface Finding {
+    rule: string;
+    severity: Severity;
+    status: "new" | "preexisting";
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+    count: number;
+    /** The detector's captures and the matched text, for a grouped rendering's per-site line. */
+    captures?: Record<string, string>;
+}
+interface DeliveredReference {
+    ref: string;
+    state: "full" | "pointer" | "read" | "missing";
+    content?: string;
+    reason?: "mode" | "budget" | "tooLarge";
+    /** State "read" of a reference from a rule repo: the absolute path of the file to read. */
+    location?: string;
+}
+/** What the context budget left out. A renderer says how much is missing; it never recomputes it. */
+interface Omitted {
+    /** Findings of a rule that is still delivered, and how many files they were in. */
+    findings: {
+        rule: string;
+        count: number;
+        files: number;
+    }[];
+    /** Rules dropped whole, with their findings: only when the floor itself did not fit. */
+    rules: number;
+    preexisting: number;
+}
+interface Delivery {
+    findings: Finding[];
+    preexistingSummary: {
+        rule: string;
+        file: string;
+        count: number;
+    }[];
+    references: DeliveredReference[];
+    touches: string[];
+    stop: "block" | "allow" | "capReached" | null;
+    warnings: string[];
+    /** `message` template per rule with findings: the skeleton a grouped rendering prints once. */
+    templates: Record<string, string>;
+    omitted: Omitted;
+    /** Absolute path of the untrimmed delivery, written when even the floor did not fit; null when it did. */
+    overflowPath: string | null;
+}
+interface AdapterInput {
+    /** The agent's directory; the project root is found from it. */
+    cwd: string;
+    /** null: nothing to run for this input. */
+    event: Event | null;
+    /** Start detector warm-up (§13). */
+    warmup: boolean;
+}
+type InstallScope = "shared" | "personal";
+interface AdapterInstall {
+    /** Paths whose presence means the project uses this agent (init); a trailing "/" means a directory. */
+    markers: string[];
+    /** Settings files, repo-relative, that hooks can be written to. */
+    scopes: {
+        scope: InstallScope;
+        file: string;
+    }[];
+    /** The hook command; local: rulecast is installed in the project's node_modules. */
+    command(local: boolean): string;
+    merge(settings: unknown, command: string, verifyMs: number): {
+        settings: unknown;
+        added: string[];
+    };
+    remove(settings: unknown): {
+        settings: unknown;
+        removed: string[];
+    };
+}
+interface Adapter {
+    name: string;
+    /** Shown to people: "Claude Code". */
+    label: string;
+    /** Budget handed to commit (§9); null = unlimited. */
+    maxContextChars: number | null;
+    /** Recently read or edited files the agent re-attaches to its context after compaction; reset re-delivers their touch context (§9). 0 = none. */
+    restoredFiles: number;
+    /** null: not an input this adapter handles. */
+    parse(input: unknown): AdapterInput | null;
+    format(delivery: Delivery, event: Event, options: {
+        maxMatchesPerRule: number;
+    }): {
+        stdout: string;
+        exitCode: number;
+    };
+    /** null: the agent has no hooks to install. */
+    install: AdapterInstall | null;
+}
+declare function emptyDelivery(): Delivery;
+
+declare const STAGES: readonly ["touch", "edit", "verify"];
+type Stage = (typeof STAGES)[number];
+declare const RULE_SCOPES: readonly ["instance", "container"];
+type RuleScope = (typeof RULE_SCOPES)[number];
+/**
+ * One inline example: a file the rule would see, and what is in it.
+ *
+ * `path` is required and has no useful default — `files`, `exclude`, the type tags and `ast-grep`'s
+ * language selection are all functions of it, so an example without one would be testing a
+ * different rule than the one that will run.
+ */
+declare const exampleSchema: z.ZodObject<{
+    path: z.ZodString;
+    code: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    path: string;
+}, {
+    code: string;
+    path: string;
+}>;
+type RuleExample = z.infer<typeof exampleSchema>;
+type RuleExamples = {
+    good: RuleExample[];
+    bad: RuleExample[];
+};
+/** A config entry selecting a rule from a rule repo; every key but id overrides the manifest rule's. */
+declare const overrideSchema: z.ZodObject<{
+    alias: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    files: z.ZodOptional<z.ZodString>;
+    exclude: z.ZodOptional<z.ZodString>;
+    types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    types_or: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    exclude_types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    stages: z.ZodOptional<z.ZodArray<z.ZodEnum<["touch", "edit", "verify"]>, "atleastone">>;
+    minimum_rulecast_version: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodEnum<["error", "warning"]>>;
+    /**
+     * What the convention belongs to (§8). `instance`: the token the detector matched, classified by
+     * whether the agent's edit touched it. `container`: the node the match spans, classified by
+     * whether that node already violated the rule at the baseline.
+     */
+    scope: z.ZodOptional<z.ZodEnum<["instance", "container"]>>;
+    refuse_write: z.ZodOptional<z.ZodBoolean>;
+    detect: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>;
+    message: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<["inject", "read"]>>;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        mode?: "inject" | "read" | undefined;
+    }, {
+        path: string;
+        mode?: "inject" | "read" | undefined;
+    }>]>, "many">>;
+    /** Code the rule must flag (`bad`) and must not (`good`), run by `rulecast test`. */
+    examples: z.ZodOptional<z.ZodObject<{
+        good: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            code: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            code: string;
+            path: string;
+        }, {
+            code: string;
+            path: string;
+        }>, "many">>;
+        bad: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            code: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            code: string;
+            path: string;
+        }, {
+            code: string;
+            path: string;
+        }>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        good: {
+            code: string;
+            path: string;
+        }[];
+        bad: {
+            code: string;
+            path: string;
+        }[];
+    }, {
+        good?: {
+            code: string;
+            path: string;
+        }[] | undefined;
+        bad?: {
+            code: string;
+            path: string;
+        }[] | undefined;
+    }>>;
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    name?: string | undefined;
+    message?: string | undefined;
+    alias?: string | undefined;
+    description?: string | undefined;
+    files?: string | undefined;
+    exclude?: string | undefined;
+    types?: string[] | undefined;
+    types_or?: string[] | undefined;
+    exclude_types?: string[] | undefined;
+    stages?: ["touch" | "edit" | "verify", ...("touch" | "edit" | "verify")[]] | undefined;
+    minimum_rulecast_version?: string | undefined;
+    severity?: "error" | "warning" | undefined;
+    scope?: "instance" | "container" | undefined;
+    refuse_write?: boolean | undefined;
+    detect?: Record<string, unknown> | undefined;
+    context?: (string | {
+        path: string;
+        mode?: "inject" | "read" | undefined;
+    })[] | undefined;
+    examples?: {
+        good: {
+            code: string;
+            path: string;
+        }[];
+        bad: {
+            code: string;
+            path: string;
+        }[];
+    } | undefined;
+}, {
+    id: string;
+    name?: string | undefined;
+    message?: string | undefined;
+    alias?: string | undefined;
+    description?: string | undefined;
+    files?: string | undefined;
+    exclude?: string | undefined;
+    types?: string[] | undefined;
+    types_or?: string[] | undefined;
+    exclude_types?: string[] | undefined;
+    stages?: ["touch" | "edit" | "verify", ...("touch" | "edit" | "verify")[]] | undefined;
+    minimum_rulecast_version?: string | undefined;
+    severity?: "error" | "warning" | undefined;
+    scope?: "instance" | "container" | undefined;
+    refuse_write?: boolean | undefined;
+    detect?: Record<string, unknown> | undefined;
+    context?: (string | {
+        path: string;
+        mode?: "inject" | "read" | undefined;
+    })[] | undefined;
+    examples?: {
+        good?: {
+            code: string;
+            path: string;
+        }[] | undefined;
+        bad?: {
+            code: string;
+            path: string;
+        }[] | undefined;
+    } | undefined;
+}>;
+type RuleEntry = z.infer<typeof overrideSchema>;
+declare const configSchema: z.ZodEffects<z.ZodObject<{
+    repos: z.ZodArray<z.ZodObject<{
+        repo: z.ZodString;
+        rev: z.ZodOptional<z.ZodString>;
+        /** Parsed rule by rule in compile, so one bad rule does not reject the config. */
+        rules: z.ZodArray<z.ZodUnknown, "many">;
+    }, "strict", z.ZodTypeAny, {
+        rules: unknown[];
+        repo: string;
+        rev?: string | undefined;
+    }, {
+        rules: unknown[];
+        repo: string;
+        rev?: string | undefined;
+    }>, "many">;
+    minimum_rulecast_version: z.ZodOptional<z.ZodString>;
+    files: z.ZodDefault<z.ZodString>;
+    exclude: z.ZodDefault<z.ZodString>;
+    default_stages: z.ZodOptional<z.ZodArray<z.ZodEnum<["touch", "edit", "verify"]>, "atleastone">>;
+    context: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<["inject", "read"]>>;
+        max_bytes: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        mode: "inject" | "read";
+        max_bytes: number;
+    }, {
+        mode?: "inject" | "read" | undefined;
+        max_bytes?: number | undefined;
+    }>>;
+    max_matches_per_rule: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Files above this many bytes are skipped by the in-process detectors on edit and guard, where
+     * an agent is waiting. `ast-grep` parses in native code, which the vm timeout that bounds
+     * `regex` cannot interrupt: a 2.6 MB TypeScript file measured 762 ms, and the cost is linear,
+     * so 26 MB would be 7.6 s of a blocked write. verify has seconds to spend and always runs.
+     */
+    max_file_bytes: z.ZodDefault<z.ZodNumber>;
+    timeouts: z.ZodDefault<z.ZodObject<{
+        edit_deadline_ms: z.ZodDefault<z.ZodNumber>;
+        verify_ms: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        edit_deadline_ms: number;
+        verify_ms: number;
+    }, {
+        edit_deadline_ms?: number | undefined;
+        verify_ms?: number | undefined;
+    }>>;
+    stop_gate: z.ZodDefault<z.ZodObject<{
+        max_blocks: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        max_blocks: number;
+    }, {
+        max_blocks?: number | undefined;
+    }>>;
+    refuse_gate: z.ZodDefault<z.ZodObject<{
+        max_refusals: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        max_refusals: number;
+    }, {
+        max_refusals?: number | undefined;
+    }>>;
+    llm: z.ZodDefault<z.ZodObject<{
+        provider: z.ZodDefault<z.ZodEnum<["claude-code", "opencode", "anthropic", "openai-compatible"]>>;
+        base_url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        api_key_env: z.ZodDefault<z.ZodString>;
+        max_files_per_verify: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        provider: "claude-code" | "opencode" | "anthropic" | "openai-compatible";
+        base_url: string | null;
+        api_key_env: string;
+        max_files_per_verify: number;
+    }, {
+        provider?: "claude-code" | "opencode" | "anthropic" | "openai-compatible" | undefined;
+        base_url?: string | null | undefined;
+        api_key_env?: string | undefined;
+        max_files_per_verify?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    llm: {
+        provider: "claude-code" | "opencode" | "anthropic" | "openai-compatible";
+        base_url: string | null;
+        api_key_env: string;
+        max_files_per_verify: number;
+    };
+    repos: {
+        rules: unknown[];
+        repo: string;
+        rev?: string | undefined;
+    }[];
+    files: string;
+    exclude: string;
+    context: {
+        mode: "inject" | "read";
+        max_bytes: number;
+    };
+    max_matches_per_rule: number;
+    max_file_bytes: number;
+    timeouts: {
+        edit_deadline_ms: number;
+        verify_ms: number;
+    };
+    stop_gate: {
+        max_blocks: number;
+    };
+    refuse_gate: {
+        max_refusals: number;
+    };
+    minimum_rulecast_version?: string | undefined;
+    default_stages?: ["touch" | "edit" | "verify", ...("touch" | "edit" | "verify")[]] | undefined;
+}, {
+    repos: {
+        rules: unknown[];
+        repo: string;
+        rev?: string | undefined;
+    }[];
+    llm?: {
+        provider?: "claude-code" | "opencode" | "anthropic" | "openai-compatible" | undefined;
+        base_url?: string | null | undefined;
+        api_key_env?: string | undefined;
+        max_files_per_verify?: number | undefined;
+    } | undefined;
+    files?: string | undefined;
+    exclude?: string | undefined;
+    minimum_rulecast_version?: string | undefined;
+    context?: {
+        mode?: "inject" | "read" | undefined;
+        max_bytes?: number | undefined;
+    } | undefined;
+    default_stages?: ["touch" | "edit" | "verify", ...("touch" | "edit" | "verify")[]] | undefined;
+    max_matches_per_rule?: number | undefined;
+    max_file_bytes?: number | undefined;
+    timeouts?: {
+        edit_deadline_ms?: number | undefined;
+        verify_ms?: number | undefined;
+    } | undefined;
+    stop_gate?: {
+        max_blocks?: number | undefined;
+    } | undefined;
+    refuse_gate?: {
+        max_refusals?: number | undefined;
+    } | undefined;
+}>, {
+    repos: {
+        rules: unknown[];
+        repo: string;
+        rev?: string | undefined;
+    }[];
+    minimumRulecastVersion: string | null;
+    files: string;
+    exclude: string;
+    defaultStages: ["touch" | "edit" | "verify", ...("touch" | "edit" | "verify")[]] | null;
+    context: {
+        mode: "inject" | "read";
+        maxBytes: number;
+    };
+    maxMatchesPerRule: number;
+    maxFileBytes: number;
+    timeouts: {
+        editDeadlineMs: number;
+        verifyMs: number;
+    };
+    stopGate: {
+        maxBlocks: number;
+    };
+    refuseGate: {
+        maxRefusals: number;
+    };
+    llm: {
+        provider: "claude-code" | "opencode" | "anthropic" | "openai-compatible";
+        baseUrl: string | null;
+        apiKeyEnv: string;
+        maxFilesPerVerify: number;
+    };
+}, {
+    repos: {
+        rules: unknown[];
+        repo: string;
+        rev?: string | undefined;
+    }[];
+    llm?: {
+        provider?: "claude-code" | "opencode" | "anthropic" | "openai-compatible" | undefined;
+        base_url?: string | null | undefined;
+        api_key_env?: string | undefined;
+        max_files_per_verify?: number | undefined;
+    } | undefined;
+    files?: string | undefined;
+    exclude?: string | undefined;
+    minimum_rulecast_version?: string | undefined;
+    context?: {
+        mode?: "inject" | "read" | undefined;
+        max_bytes?: number | undefined;
+    } | undefined;
+    default_stages?: ["touch" | "edit" | "verify", ...("touch" | "edit" | "verify")[]] | undefined;
+    max_matches_per_rule?: number | undefined;
+    max_file_bytes?: number | undefined;
+    timeouts?: {
+        edit_deadline_ms?: number | undefined;
+        verify_ms?: number | undefined;
+    } | undefined;
+    stop_gate?: {
+        max_blocks?: number | undefined;
+    } | undefined;
+    refuse_gate?: {
+        max_refusals?: number | undefined;
+    } | undefined;
+}>;
+type Config = z.output<typeof configSchema>;
+
+type AnyDetector = Detector<any>;
+interface DetectorRegistry {
+    get(kind: string): AnyDetector | undefined;
+    kinds(): string[];
+}
+declare function createRegistry(detectors: AnyDetector[]): DetectorRegistry;
+
+interface ReferenceSpec {
+    /** Identity and display. Project: "docs/api.md#errors". Rule repo: "syv-ai/rulecast@v0.2.0:docs/api.md#errors". */
+    ref: string;
+    /** Project references: repo-relative with forward slashes. Rule repo references: absolute path in the cache. */
+    path: string;
+    anchor: string | null;
+    mode: ReferenceMode;
+}
+
+interface CompiledDetector {
+    kind: string;
+    config: unknown;
+    captures: string[];
+}
+interface CompiledRule {
+    /** alias when set, else id: the name findings, dedupe and session state use. */
+    id: string;
+    name: string;
+    description: string | null;
+    /** "local", or the rule repo label ("syv-ai/rulecast@v0.2.0"). */
+    source: string;
+    severity: Severity;
+    /**
+     * How a finding of this rule is classified against the baseline (spec §8). `instance` — the
+     * default, and every rule before 0.2 — is new when the match touches a changed line. `container`
+     * is new when the node the match spans was not already violating the rule at the baseline.
+     */
+    scope: RuleScope;
+    /** Refuse the agent's write when this rule fires on what it is writing (spec §9, Guard). */
+    refuseWrite: boolean;
+    stages: Stage[];
+    matches(file: string): boolean;
+    detector: CompiledDetector | null;
+    message: string | null;
+    context: ReferenceSpec[];
+    /**
+     * Inline good/bad examples, run by `rulecast test`. `null` when the rule declared none, which
+     * `validate` and `test` report differently from a rule that declared an empty set.
+     */
+    examples: RuleExamples | null;
+}
+/**
+ * A rule that runs a detector. compileRule enforces the split — a rule with `detect` must also
+ * have a `message` and an edit or verify stage; one without must have neither and must have
+ * `context` — so selection can narrow to this and consumers stop asserting what it already knows.
+ */
+type DetectorRule = CompiledRule & {
+    detector: CompiledDetector;
+    message: string;
+};
+/** A rule with no detector: it delivers its `context` when a matching file is touched. */
+type TouchRule = CompiledRule & {
+    detector: null;
+};
+/** Whether this rule runs a detector, as a type guard so the narrowing survives a filter. */
+declare function isDetectorRule(rule: CompiledRule): rule is DetectorRule;
+
+/** What the model is asked to answer with (spec §6). */
+declare const responseSchema: z.ZodObject<{
+    findings: z.ZodArray<z.ZodObject<{
+        rule: z.ZodString;
+        line: z.ZodNumber;
+        /** The model's quote of the line. Asked for because quoting sharpens the line number; never rendered. */
+        text: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        rule: string;
+        line: number;
+        reason: string;
+        text?: string | undefined;
+    }, {
+        rule: string;
+        line: number;
+        reason: string;
+        text?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    findings: {
+        rule: string;
+        line: number;
+        reason: string;
+        text?: string | undefined;
+    }[];
+}, {
+    findings: {
+        rule: string;
+        line: number;
+        reason: string;
+        text?: string | undefined;
+    }[];
+}>;
+type LlmFinding = z.infer<typeof responseSchema>["findings"][number];
+interface LlmRequest {
+    /** The provider's own model name, already resolved from the rule's alias. */
+    model: string;
+    /** The whole prompt: rules, grounding and the marked-up file. */
+    prompt: string;
+    settings: LlmSettings;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    signal: AbortSignal;
+}
+/**
+ * The backend itself is unusable — no binary, no credentials. Spec §14 makes this a failure of the
+ * whole run (every llm rule disabled, one warning), not of one rule. Every other throw is §14's
+ * "malformed LLM output": an error for the rules in that call only.
+ */
+declare class LlmUnavailableError extends Error {
+}
+/** What `rulecast doctor` learns about a backend without calling it (spec §5). */
+interface LlmAvailability {
+    ok: boolean;
+    /** The resolved binary or the endpoint when ok; why not when it is not. */
+    detail: string;
+}
+interface LlmProvider {
+    name: string;
+    ask(request: LlmRequest): Promise<LlmFinding[]>;
+    /**
+     * Can this backend be reached at all — the binary exists, or the key is set. Environmental, so
+     * it never calls the model: a false answer here is the same situation ask() would report as
+     * LlmUnavailableError, found before anything is spent.
+     */
+    available(input: {
+        settings: LlmSettings;
+        env: NodeJS.ProcessEnv;
+        cwd: string;
+        /** Give up when doctor's deadline passes: a PATH lookup can block on a stalled mount. */
+        signal: AbortSignal;
+    }): Promise<LlmAvailability>;
+}
+
+export { type Adapter as A, type RuleScope as B, type Cache as C, type Delivery as D, type Event as E, type Finding as F, createRegistry as G, defaultDetectorSettings as H, type InstallScope as I, emptyDelivery as J, isDetectorRule as K, LLM_PROVIDERS as L, type Match as M, type Config as N, type Omitted as O, type RuleEntry as P, type Stage as Q, type ReferenceMode as R, type Severity as S, type TouchRule as T, type WriteIntent as W, type DetectorRuleInput as a, type DetectorRun as b, type Detector as c, type AnyDetector as d, type AdapterInput as e, type AdapterInstall as f, type ChangeSet as g, type CheckResult as h, type CompiledDetector as i, type CompiledRule as j, type DeliveredReference as k, type DetectorCheck as l, type DetectorEvent as m, type DetectorRegistry as n, type DetectorResult as o, type DetectorRule as p, type DetectorSettings as q, type DetectorWarm as r, type EventKind as s, type LlmFinding as t, type LlmProvider as u, type LlmProviderName as v, type LlmRequest as w, type LlmSettings as x, LlmUnavailableError as y, type ResolvedReference as z };