@voke-sh/voke 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,727 @@
+import { Severity, DimensionId } from '@voke/core';
+import { Command } from 'commander';
+
+/**
+ * Version source-of-truth for Voke and MTQS (SCORE-02 / D-08).
+ *
+ * VOKE_VERSION: the current linter package version (hardcoded; build-time injection
+ * from package.json is out of scope for Phase 4 — a plain const keeps the value
+ * deterministic and import-cheap).
+ *
+ * MTQS_VERSION: the MTQS spec version this linter implements (matches spec/mtqs-v0.1.yaml
+ * and the existing snapshot mtqsVersion field).
+ *
+ * versionString(): returns the canonical CLI --version string.
+ */
+/** The current linter package version. Update when package.json version changes. */
+declare const VOKE_VERSION = "0.1.0";
+/** The MTQS spec version implemented by this linter. */
+declare const MTQS_VERSION = "0.1";
+/**
+ * Returns the canonical version string used by the CLI --version flag.
+ * Format: "voke {VOKE_VERSION} (MTQS v{MTQS_VERSION})"
+ * Example: "voke 0.0.0 (MTQS v0.1)"
+ */
+declare const versionString: () => string;
+
+/**
+ * Ingestion data model types — verbatim from ARCHITECTURE.md (lines 127-164).
+ *
+ * These are plain TS interfaces; no Zod here (Zod validation of snapshots-on-read
+ * goes in snapshot-reader.ts).
+ *
+ * Determinism notes:
+ * - D-02: capturedAt lives in meta (separate from hashed body), excluded from
+ *   snapshotContentHash and the byte-identical determinism test.
+ * - D-03: toolId = tool.name; tools sorted ascending by toolId at ingest time.
+ * - D-07: $ref strings are kept as-written (never dereferenced at ingestion time).
+ */
+/** Server identity captured at connect time. */
+interface ServerIdentity {
+    url: string | null;
+    name: string;
+    version: string;
+    protocolVersion: string;
+}
+/**
+ * Per-tool snapshot — the stable serialized form both L1 (lint) and L2 (diff) operate on.
+ * contentHash enables O(1) change detection across snapshot versions.
+ */
+interface ToolSnapshot {
+    toolId: string;
+    contentHash: string;
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+}
+/**
+ * Top-level snapshot produced by ingestion (live or offline).
+ *
+ * D-02: meta.capturedAt is provenance — excluded from hashing and the x3 determinism test.
+ * D-01: VokeSnapshot is the raw tool surface; LintReport is the separate scored artifact.
+ */
+interface VokeSnapshot {
+    snapshotVersion: '1';
+    mtqsVersion: string;
+    server: ServerIdentity;
+    meta: {
+        capturedAt: string;
+    };
+    tools: ToolSnapshot[];
+}
+
+/**
+ * VokeConfig — the resolved configuration object passed into every RuleContext.
+ *
+ * Full Zod loader + ConfigError (exit 7) are deferred to Phase 4.
+ * Phase 2 only needs the type so RuleContext.config typechecks.
+ */
+interface VokeConfig {
+    severityOverrides?: Record<string, Severity>;
+    minScore?: number;
+}
+
+/**
+ * RuleTarget — whether a rule fires per-tool or once for the full server surface (ENG-02).
+ * The only server-scoped rule in MTQS v0.1 is MTQS-N03 (duplicate name check).
+ */
+type RuleTarget = 'tool' | 'server';
+/**
+ * FindingLocation — points to the exact location in the tool definition that triggered the finding.
+ *
+ * tool: toolId of the tool (or '' for server-scoped findings)
+ * path: JSON path within the tool definition, e.g. ['inputSchema', 'properties', 'user']
+ */
+interface FindingLocation {
+    tool: string;
+    path: string[];
+}
+/**
+ * Finding — the runtime finding produced by rule functions.
+ *
+ * NOTE: This intentionally extends the scoring-facing @voke/core Finding ({ruleId, severity, dimension})
+ * with location, message, and fixHint. Do NOT re-export this under the same name from the engine
+ * barrel as @voke/core's Finding — they serve different purposes and must remain distinguishable.
+ *
+ * severity: the RESOLVED severity (after config.severityOverrides) — scoring uses resolved values.
+ */
+interface Finding {
+    ruleId: string;
+    dimension: DimensionId;
+    severity: Severity;
+    message: string;
+    location: FindingLocation;
+    fixHint: string;
+}
+/**
+ * RuleContext — the frozen object passed to every rule function (D-14).
+ *
+ * tool: the ToolSnapshot being evaluated (null for server-scoped rules — ENG-02)
+ * surface: the full sorted server surface (ReadonlyArray for type-level purity enforcement)
+ * config: resolved VokeConfig including any severity overrides (Readonly for compile-time safety)
+ *
+ * Object.freeze in the runner provides the runtime immutability guarantee on top of TypeScript
+ * readonly annotations (RESEARCH.md Pattern 11).
+ */
+interface RuleContext {
+    readonly tool: ToolSnapshot | null;
+    readonly surface: ReadonlyArray<ToolSnapshot>;
+    readonly config: Readonly<VokeConfig>;
+}
+/**
+ * RuleFunction — the pure synchronous contract every MTQS rule must satisfy (ENG-01).
+ *
+ * Rules MUST NOT: call Date.now(), Math.random(), fetch(), fs.*,
+ * or mutate the context. All such violations are caught at test time by the
+ * frozen context + network-blocked test infrastructure (D-14).
+ */
+type RuleFunction = (ctx: RuleContext) => Finding[];
+/**
+ * RuleDefinition — the full descriptor for a single MTQS rule registered in the RuleRegistry.
+ */
+interface RuleDefinition {
+    id: string;
+    description: string;
+    dimension: DimensionId;
+    target: RuleTarget;
+    defaultSeverity: Severity;
+    fixHint: string;
+    mtqsVersion: string;
+    fn: RuleFunction;
+}
+
+/**
+ * Tier — A-F quality tier assigned to a tool or server score.
+ * Cuts: A>=90, B>=80, C>=70, D>=60, F<60 (from @voke/core tierFor).
+ */
+type Tier = 'A' | 'B' | 'C' | 'D' | 'F';
+/**
+ * ToolReport — scored result for a single tool in a LintReport.
+ *
+ * contentHash: from the ToolSnapshot (ING-04 / D-03) — enables L2 delta detection.
+ * findings: the runtime findings for this tool (includes message, location, fixHint).
+ * score: capped integer score (0-100) using @voke/core applyCaps.
+ * tier: A-F from @voke/core tierFor.
+ */
+interface ToolReport {
+    toolId: string;
+    contentHash: string;
+    findings: Finding[];
+    score: number;
+    tier: Tier;
+}
+/**
+ * LintReport — the top-level scored artifact produced by buildReport.
+ *
+ * D-01: LintReport is a separate artifact from VokeSnapshot. The raw surface
+ * (VokeSnapshot) stays independent of rule/score changes; this is the scored output.
+ *
+ * D-02: meta.generatedAt is wall-clock provenance — excluded from serializeReportBody
+ * and the byte-identical determinism test. The canonical hashed/compared body covers
+ * only server identity, snapshotContentHash, tool scores, and server aggregate.
+ */
+interface LintReport {
+    vokeVersion: string;
+    mtqsVersion: string;
+    /** D-02: provenance block excluded from serializeReportBody / determinism test */
+    meta: {
+        generatedAt: string;
+    };
+    server: ServerIdentity;
+    /** SHA-256 of canonical sorted tools surface (surfaceContentHash) */
+    snapshotContentHash: string;
+    tools: ToolReport[];
+    serverScore: number;
+    serverTier: Tier;
+}
+
+/**
+ * Options for a single lint run.
+ */
+interface RunLintOpts {
+    /** MCP server URL (http/https) or path to a saved snapshot JSON file. */
+    target: string;
+    /** Output format: 'human' for terminal display; 'json' for parseable LintReport. */
+    output: 'human' | 'json';
+    /** Raw header strings "Key: Value" passed to ingestLive (ignored for file targets). */
+    headers: string[];
+    /** Per-request timeout in ms for live targets (threaded to ingestLive.timeoutMs). */
+    timeout: number;
+    /** If set: exit 1 when serverScore < minScore; exit 0 otherwise (D-13). */
+    minScore?: number;
+    /** Print per-finding detail lines under each below-A tool. */
+    verbose: boolean;
+    /** Enable ANSI color codes in human output. Score line is never colored (D-03). */
+    color: boolean;
+    /** If set: also write the raw VokeSnapshot to this path (D-11 — distinct from LintReport). */
+    saveSnapshot?: string;
+    /**
+     * If set and non-empty: launch an MCP subprocess via StdioClientTransport instead of
+     * resolveTarget. stdioArgs[0] is the command; the rest are args. Bypasses resolveTarget.
+     */
+    stdioArgs?: string[];
+    /**
+     * Extra environment variables for the stdio subprocess (from --env KEY=VAL).
+     * Values are NEVER echoed in output (D-09/Pitfall 4).
+     */
+    extraEnv?: Record<string, string>;
+}
+/**
+ * Result from a lint run.
+ */
+interface RunLintResult {
+    /** The assembled LintReport with per-tool + server scores. */
+    report: LintReport;
+    /** Formatted output string (human or JSON depending on opts.output). */
+    text: string;
+    /** Process exit code: 0 = pass; 1 = minScore not met; errors throw (not exit code here). */
+    exitCode: number;
+}
+/**
+ * Run the full lint pipeline for a target.
+ *
+ * For file targets: readSnapshot (sync, no network).
+ * For live targets: ingestLive with opts.timeout threaded as timeoutMs.
+ *
+ * If opts.saveSnapshot is set, writes the raw VokeSnapshot to that path before linting.
+ * The VokeSnapshot is the re-lint input artifact (has snapshotVersion, tools[].toolId,
+ * meta.capturedAt) — it does NOT contain serverScore or per-tool scores (D-11).
+ *
+ * @throws UsageError (exitCode=3) — bad target string
+ * @throws ConnectError (exitCode=2) — both transports failed
+ * @throws PartialPageError (exitCode=4) — pagination page failed
+ * @throws DepthExceededError (exitCode=6) — schema too deep
+ * @throws RuleExecutionError — rule fn threw (internal error)
+ */
+declare const runLint: (opts: RunLintOpts) => Promise<RunLintResult>;
+
+/**
+ * Returns a copy of the headers object with every value replaced by "[MASKED]".
+ * Use this before including headers in any log, error message, or serialized output.
+ * Raw header values must NEVER appear in a VokeSnapshot, LintReport, or log.
+ */
+declare const maskHeaders: (headers: Record<string, string>) => Record<string, string>;
+/**
+ * Options for live ingestion.
+ */
+interface IngestLiveOptions {
+    /** Full URL of the MCP server endpoint (e.g., "http://localhost:3000/mcp") */
+    url: string;
+    /**
+     * Raw header strings in "Key: Value" format (mirrors curl --header).
+     * Used for bearer token auth and custom headers.
+     * Values are NEVER stored on the returned VokeSnapshot (D-09).
+     */
+    rawHeaders?: string[];
+    /**
+     * Per-listTools-page timeout in ms; defaults to LIST_TOOLS_TIMEOUT_MS (30000).
+     * Threaded through to fetchAllTools — controls how long each paginated request waits.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Connects to a live MCP server, fetches the complete paginated tool surface,
+ * and returns a sorted, content-hashed VokeSnapshot.
+ *
+ * Determinism enforced:
+ * - Tools sorted ascending by toolId via localeCompare('en', {sensitivity:'variant'}) (#1/#5)
+ * - Per-tool contentHash = SHA-256 of canonical {name,description,inputSchema,outputSchema,annotations} (#6)
+ * - meta.capturedAt is the ONLY wall-clock value; excluded from hashing (D-02)
+ * - Raw header values never included in snapshot (D-09)
+ *
+ * Failure modes:
+ * - ConnectError (exit 2): both transports fail to connect
+ * - PartialPageError (exit 4): any listTools page fails
+ * - DepthExceededError (exit 6): any tool inputSchema exceeds DEPTH_HARD_CAP
+ */
+declare const ingestLive: (opts: IngestLiveOptions) => Promise<VokeSnapshot>;
+
+/**
+ * Commander v15 program definition for the voke CLI (CLI-01/02/03, D-07/08/13/15/16).
+ *
+ * Exports:
+ * - buildProgram(): builds a fresh Command instance (used by bin entrypoint and tests)
+ * - resolveLintOpts(): pure flag-resolution helper (unit-testable; no network, no IO)
+ *
+ * Design:
+ * - Flag resolution and validation is isolated in resolveLintOpts so program.test.ts
+ *   can test color-disabling, NO_COLOR, and invalid-flag rejection without invoking runLint.
+ * - The lint action handler calls resolveLintOpts then runLint and then sets process.exitCode.
+ *   It does NOT call process.exit on success — the bin entrypoint's main().catch handles errors.
+ *
+ * Token masking (D-15/16):
+ * - maskHeaders is called in any echoed diagnostic line that would include header values.
+ * - Raw header values must NEVER appear in stderr (injected via buildHeaders/maskHeaders).
+ */
+
+/**
+ * Resolves and validates the raw commander-parsed options into a RunLintOpts object.
+ *
+ * Validates:
+ * - --output must be 'human' or 'json' (throws UsageError on unknown format)
+ * - --min-score must be an integer 0-100 (throws UsageError if out of range)
+ * - --timeout must be a positive integer (throws UsageError if invalid)
+ * - color: disabled if --ci, NO_COLOR env var, or --no-color flag is set (D-03/D-16)
+ * - --env: each entry must be KEY=VAL (throws UsageError if missing '=')
+ *
+ * This function has no side effects and performs no IO. It is the unit-testable
+ * boundary between commander's parsed options and the runLint pipeline.
+ *
+ * @param target - the positional [target] argument (may be empty string if stdio mode)
+ * @param opts - the raw commander option object (typed loosely for test flexibility)
+ * @returns validated RunLintOpts ready for runLint
+ * @throws UsageError (exitCode=3) on invalid flag values
+ */
+declare const resolveLintOpts: (target: string, opts: Record<string, unknown>) => RunLintOpts;
+/**
+ * Build a fresh commander v15 Command instance for the voke CLI.
+ *
+ * Always returns a NEW instance (test isolation — no module-level singleton).
+ *
+ * The program is structured as:
+ *   voke [options]
+ *     --version / -v: print "voke X.Y.Z (MTQS v0.1)" (D-08)
+ *   voke lint [target] [flags...] [-- <cmd> [args...]]
+ *     D-07 flags: --output, -H/--header, --timeout, --min-score, --ci, --no-color, --save-snapshot, --verbose
+ *     ING-06 flags: --env KEY=VAL (repeatable; values masked in output, D-09)
+ *
+ * @param stdioArgs - pre-split args after '--' in process.argv (see cli/index.ts).
+ *   When set and non-empty, lint target becomes optional and stdio mode is used.
+ */
+declare const buildProgram: (stdioArgs?: string[]) => Command;
+
+/**
+ * Extensible target resolver for the voke CLI (D-04 / D-05 / D-06).
+ *
+ * Dispatches a target string to a transport kind (live | file) via a SCHEME_HANDLERS
+ * registry. This is the extension seam: Phase 5 stdio support adds an 'stdio:' entry
+ * here without requiring a resolver rewrite (D-05 extensibility guarantee).
+ *
+ * D-06: schemeless host:port strings (e.g. "localhost:3000/mcp") are REJECTED with
+ * a did-you-mean hint rather than silently treated as file paths.
+ *
+ * Exit codes:
+ *   UsageError.exitCode = 3 (D-13: usage / argument error)
+ */
+/** The kind of transport to use for the resolved target. */
+type TransportKind = 'live' | 'file' | 'stdio';
+/** Resolved target with its transport kind. */
+interface ResolvedTarget {
+    kind: TransportKind;
+    target: string;
+    /** Only present when kind === 'stdio'. Contains the command + args for StdioClientTransport. */
+    stdioArgs?: string[];
+}
+/**
+ * Thrown when the target string is malformed (bad scheme, schemeless host:port, etc.).
+ * Exit code 3 per D-13 (usage / argument error).
+ *
+ * Kept in this file for Phase 4 Wave 1 to avoid editing errors.ts in a parallel wave.
+ * Plan 02 may re-home this to errors.ts if a shared UsageError is needed.
+ */
+declare class UsageError extends Error {
+    readonly exitCode = 3;
+    constructor(msg: string);
+}
+/**
+ * Resolves a target string to a transport kind and canonical target.
+ *
+ * Dispatch order:
+ * 1. URL with scheme ("https://...") → look up in SCHEME_HANDLERS
+ *    - Known scheme: dispatch to handler (live for http/https)
+ *    - Unknown scheme: throw UsageError listing supported schemes
+ * 2. Schemeless host:port pattern ("localhost:3000/mcp") → throw UsageError with did-you-mean
+ * 3. Everything else → treat as a local file path
+ *
+ * @param raw - the target string provided by the user
+ * @returns ResolvedTarget with kind and canonical target string
+ * @throws UsageError (exitCode=3) for invalid/unsupported targets
+ */
+declare const resolveTarget: (raw: string) => ResolvedTarget;
+
+/** Options controlling human output rendering. */
+interface HumanFormatOpts {
+    /** Whether to emit ANSI color codes for severity labels. The score line is NEVER colored. */
+    color: boolean;
+    /** Whether to print per-finding detail lines under each below-A tool. */
+    verbose: boolean;
+}
+/**
+ * Format a LintReport as a human-readable string.
+ *
+ * The output is a newline-joined string of lines:
+ *   1. Score banner (never colored, D-03)
+ *   2. Dimension weight breakdown (fixed order, D-01)
+ *   3. Table of below-A tools sorted by score ascending (D-01)
+ *   4. [verbose] Per-finding detail lines for each below-A tool (D-02)
+ *
+ * @param report - the LintReport to format
+ * @param opts - rendering options (color, verbose)
+ * @returns a newline-joined string; never empty
+ */
+declare const formatHuman: (report: LintReport, opts: HumanFormatOpts) => string;
+
+/**
+ * Serialize a LintReport to a canonical JSON string.
+ *
+ * The full report including meta.generatedAt is included (D-10: full consumption doc).
+ * Keys are sorted for stability — repeated calls on the same object yield identical output.
+ *
+ * @param report - the LintReport to serialize
+ * @returns a canonical JSON string representing the full report
+ */
+declare const formatJson: (report: LintReport) => string;
+
+/**
+ * Deterministic sorted-key JSON serializer.
+ *
+ * Invariants:
+ * - Object keys are sorted with localeCompare('en', { sensitivity: 'variant' }) for
+ *   locale-independent, byte-stable output (Pitfall 2 guard).
+ * - Arrays are NEVER reordered (order is semantic in JSON Schema prefixItems, enum, etc.).
+ * - undefined-valued keys are omitted (mirrors JSON.stringify behavior, Pitfall 7 guard).
+ * - Internal $ref strings (D-07) are kept byte-for-byte — no dereferencing before hashing.
+ *
+ * This is the single source of byte-stable serialization used by:
+ * - toolContentHash (per-tool identity, ING-04)
+ * - surfaceContentHash (snapshotContentHash, ARCHITECTURE point #6)
+ * - x3 byte-identical determinism test (ENG-04, D-12)
+ */
+declare const canonicalJson: (value: unknown) => string;
+
+/**
+ * Deterministic SHA-256 hash helper.
+ *
+ * Returns a 64-char lowercase hex digest of the UTF-8 encoded input string.
+ * Uses node:crypto (built-in, synchronous, deterministic) — no external dep.
+ */
+declare const sha256: (input: string) => string;
+/**
+ * Per-tool content hash (ING-04, D-03).
+ *
+ * Hashes exactly the 5 canonical fields: name, description, inputSchema, outputSchema, annotations.
+ * Key order is normalized via canonicalJson so the hash is stable regardless of JS object key
+ * insertion order. undefined fields are omitted (canonicalJson mirrors JSON.stringify).
+ */
+declare const toolContentHash: (tool: {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+    annotations?: unknown;
+}) => string;
+/**
+ * Surface content hash (ARCHITECTURE determinism point #6).
+ *
+ * Sorts tools ascending by toolId (locale-independent) before hashing, so the hash is
+ * independent of the input array order (MCP protocol does not guarantee tool ordering).
+ */
+declare const surfaceContentHash: (tools: ReadonlyArray<{
+    toolId: string;
+}>) => string;
+
+/**
+ * Reads a VokeSnapshot JSON file from disk.
+ * Validates the parsed JSON against VokeSnapshotSchema (Zod).
+ * Throws a ZodError with a clear message if the file is malformed.
+ *
+ * Guarantees ING-03: no network, no MCP SDK, no fetch.
+ *
+ * @param path - absolute or relative path to the .json snapshot file
+ * @returns Validated VokeSnapshot
+ * @throws ZodError if the snapshot fails validation
+ * @throws Error if the file cannot be read or parsed as JSON
+ */
+declare const readSnapshot: (path: string) => VokeSnapshot;
+
+/**
+ * Serializes a VokeSnapshot to disk.
+ *
+ * The output uses canonicalJson (sorted keys) on the entire snapshot object
+ * to ensure byte-identical re-writes of the same surface.
+ * meta.capturedAt is preserved as written (D-02 provenance).
+ *
+ * @param path - destination file path (will overwrite if exists)
+ * @param snapshot - the VokeSnapshot to write
+ */
+declare const writeSnapshot: (path: string, snapshot: VokeSnapshot) => void;
+
+/**
+ * RuleRegistry — the startup-time plugin boundary for the MTQS rule engine (ENG-03).
+ *
+ * Lifecycle:
+ *   1. register() rules during module initialization
+ *   2. seal() before the runner executes — rejects any further registration
+ *   3. list() returns rules sorted deterministically by id for the runner
+ *   4. applyOverrides() returns a NEW sealed RuleRegistry with adjusted severities —
+ *      never mutates the original (D-ENG-03 no-mutation guarantee)
+ *
+ * Anti-Pattern guard: never create a module-level singleton RuleRegistry.
+ * Use createDefaultRegistry() to get a fresh instance per run, preserving test isolation.
+ */
+declare class RuleRegistry {
+    private readonly rules;
+    private sealed;
+    /**
+     * Register a rule definition.
+     * Throws if the registry is sealed or if the same id has already been registered.
+     */
+    register(def: RuleDefinition): void;
+    /**
+     * Seal the registry. After sealing, register() throws.
+     * Returns `this` for fluent chaining: `const r = new RuleRegistry(); r.seal();`
+     */
+    seal(): this;
+    /**
+     * Return all registered rules sorted ascending by id.
+     *
+     * Sort uses localeCompare('en', {sensitivity:'variant'}) for determinism across
+     * environments — avoids LC_ALL variation (RESEARCH.md Pitfall 2, ARCHITECTURE.md D-pt-#4).
+     */
+    list(): ReadonlyArray<RuleDefinition>;
+    /**
+     * Return a NEW sealed RuleRegistry with severity overrides applied.
+     *
+     * This method NEVER mutates the current registry — it constructs a fresh one
+     * and registers cloned rule definitions with adjusted defaultSeverity where
+     * an override exists. (ENG-03 / D-ENG-03)
+     *
+     * @param overrides - Map of ruleId → Severity. Unknown rule ids are silently ignored.
+     */
+    applyOverrides(overrides: Record<string, Severity>): RuleRegistry;
+}
+/**
+ * createDefaultRegistry — factory that returns a fresh sealed RuleRegistry.
+ *
+ * In Phase 2, returns an empty sealed registry.
+ * Phase 3 will import './rules/index.js' here to register all MTQS rules.
+ *
+ * Always use this factory rather than a module-level singleton to preserve test isolation.
+ */
+declare const createDefaultRegistry: () => RuleRegistry;
+
+/**
+ * RuleExecutionError — thrown when a rule's fn() call throws (D-13: fail-fast).
+ *
+ * This is the exit-code-5 failure class (RESEARCH.md Pattern 12).
+ * The numeric exit code mapping lives in the CLI layer (Phase 4);
+ * the error type is defined here in the engine.
+ *
+ * Carries ruleId + toolId so CI output can pinpoint exactly which rule
+ * and which tool caused the failure — directly actionable.
+ */
+declare class RuleExecutionError extends Error {
+    readonly ruleId: string;
+    readonly toolId: string;
+    readonly cause: unknown;
+    constructor(ruleId: string, toolId: string, cause: unknown);
+}
+/**
+ * runRules — the pure runner that executes all registered rules against a tool surface.
+ *
+ * Determinism guarantees (RESEARCH.md Pattern 9):
+ * 1. surface sorted ascending by toolId (localeCompare 'en' variant) before iteration
+ * 2. rules iterated in registry.list() order (sorted ascending by id)
+ * 3. each RuleContext is Object.freeze'd to prevent mutation (D-14)
+ * 4. returned findings sorted toolId → ruleId → path.join('.') (spec §4.4 fixed evaluation order)
+ * 5. severity resolved via config.severityOverrides[id] ?? defaultSeverity; 'off' → skip
+ *
+ * Fail-fast (D-13): any rule fn() that throws is wrapped in RuleExecutionError and
+ * rethrown immediately — no silent swallow, no partial finding set.
+ *
+ * @param surface - the tool surface (will be sorted internally; does not mutate the array)
+ * @param registry - sealed RuleRegistry (from createDefaultRegistry or applyOverrides)
+ * @param config - resolved VokeConfig (severityOverrides applied upstream or default {})
+ * @returns Finding[] sorted deterministically per spec
+ */
+declare const runRules: (surface: ReadonlyArray<ToolSnapshot>, registry: RuleRegistry, config: VokeConfig) => Finding[];
+
+/**
+ * buildReport — assembles a LintReport from a VokeSnapshot + engine findings.
+ *
+ * Scoring is entirely delegated to @voke/core (scoreTool, applyCaps, tierFor, serverScore).
+ * No scoring arithmetic is reimplemented here.
+ *
+ * Determinism guarantees:
+ * 1. snapshot.tools assumed already sorted ascending by toolId (ingestion guarantees this)
+ * 2. findings grouped by location.tool; CoreFinding map strips location/message/fixHint
+ * 3. snapshotContentHash = surfaceContentHash(snapshot.tools) — surface hash, sort-stable
+ * 4. serverScore = coreServerScore(toolScores) — mean of toolId-sorted scores
+ * 5. meta.generatedAt = new Date().toISOString() — the ONLY wall-clock call (D-02)
+ *
+ * @param snapshot - the VokeSnapshot (tools already sorted ascending by toolId)
+ * @param findings - all runtime findings from runRules (sorted toolId→ruleId→path)
+ * @param opts - optional vokeVersion override (defaults to '0.0.0')
+ */
+declare const buildReport: (snapshot: VokeSnapshot, findings: Finding[], opts?: {
+    vokeVersion?: string;
+}) => LintReport;
+/**
+ * serializeReportBody — produces the canonical, meta-stripped string that the
+ * byte-identical determinism test (ENG-04 / D-12) compares.
+ *
+ * D-02: strips `meta` (which contains generatedAt, the only wall-clock value)
+ * before serializing. The compared body is deterministic because it contains no
+ * wall-clock or provenance data.
+ *
+ * Uses canonicalJson for sorted-key, locale-stable serialization (Pitfall 1/2 guard).
+ */
+declare const serializeReportBody: (report: LintReport) => string;
+
+/**
+ * Schema Correctness rules (MTQS-S01 through MTQS-S08).
+ *
+ * These 8 rules cover RULE-01 in full and form the T1 (1.5x weight) correctness floor.
+ * A broken inputSchema means the tool literally cannot be used by an agent.
+ *
+ * All rules:
+ * - target: 'tool' (per-tool evaluation)
+ * - dimension: 'schema'
+ * - mtqsVersion: '0.1'
+ * - pure synchronous functions with ZERO IO (no fetch, no Date.now, no Math.random)
+ *
+ * Helpers from schema-checks.ts are REUSED (never reimplemented):
+ * - isValidJsonSchema2020: S03, S06
+ * - hasExternalRef: S04
+ * - schemaDepth: S05
+ */
+
+declare const schemaRules: RuleDefinition[];
+
+/**
+ * descriptionRules — exported array of all Description-as-Prompt rules.
+ * Order: D01, D02, D03 (alphabetical by ID, matching spec evaluation order §4.4).
+ */
+declare const descriptionRules: RuleDefinition[];
+
+/**
+ * namingRules — exported array of all Naming rules.
+ * Order: N01, N02, N03 (alphabetical by ID, matching spec evaluation order §4.4).
+ * N03 has target: 'server' — the engine routes it differently from N01/N02.
+ */
+declare const namingRules: RuleDefinition[];
+
+/**
+ * parameters.ts — MTQS Parameter Semantics rules (dimension: 'parameters', weight: 1.2×)
+ *
+ * Exports `parameterRules: RuleDefinition[]` containing P01 and P02.
+ * Both rules operate per-tool, are pure synchronous functions, and perform zero IO.
+ *
+ * Sources:
+ *   - Anthropic "Writing effective tools for agents" (Sep 2025)
+ *   - arxiv:2602.14878 — Opaque Parameters smell at 84.3% prevalence
+ *   - spec/MTQS-v0.1.md §3 MTQS-P01 and MTQS-P02
+ *   - spec/mtqs-v0.1.yaml (fixHints copied VERBATIM)
+ */
+
+declare const parameterRules: RuleDefinition[];
+
+/**
+ * annotations.ts — MTQS Annotation Transparency rules (A01–A06), dimension 'annotations' (weight 1.5x).
+ *
+ * These rules evaluate the MCP tool annotations object and its four hint booleans:
+ * readOnlyHint, destructiveHint, idempotentHint, openWorldHint.
+ *
+ * All rule functions are pure: no IO, no Date.now(), no Math.random(), no fetch.
+ * Network-blocked test (D-14) enforces this at test time.
+ *
+ * Rule coverage:
+ *   A01 (info)    — annotations object absent → tool defaults to riskiest posture
+ *   A02 (warning) — readOnlyHint not a boolean within annotations
+ *   A03 (warning) — destructiveHint not a boolean within annotations
+ *   A04 (info)    — idempotentHint not a boolean within annotations
+ *   A05 (info)    — openWorldHint not a boolean within annotations
+ *   A06 (error)   — readOnlyHint:true AND destructiveHint:true contradiction
+ */
+
+declare const annotationRules: RuleDefinition[];
+
+/**
+ * rules/index.ts — MTQS v0.1 rule aggregator.
+ *
+ * Combines all five dimension rule arrays into a single `allRules` export
+ * that is consumed by createDefaultRegistry() to populate the sealed registry.
+ *
+ * Wave 1 dimension modules:
+ *   schemaRules      — 8 rules (03-01)
+ *   descriptionRules — 3 rules (03-02)
+ *   namingRules      — 3 rules (03-02)
+ *   parameterRules   — 2 rules (03-03)
+ *   annotationRules  — 6 rules (03-04)
+ *
+ * Total: 22 rules.
+ */
+
+/**
+ * allRules — the complete ordered set of 22 MTQS v0.1 rule definitions.
+ *
+ * Order: schema, description, naming, parameters, annotations.
+ * The registry sorts by id internally on list() — insertion order does not
+ * affect determinism, but a stable source order aids review.
+ */
+declare const allRules: RuleDefinition[];
+
+export { type Finding, type FindingLocation, type HumanFormatOpts, type IngestLiveOptions, type LintReport, MTQS_VERSION, type ResolvedTarget, type RuleContext, type RuleDefinition, RuleExecutionError, type RuleFunction, RuleRegistry, type RuleTarget, type RunLintOpts, type RunLintResult, type ServerIdentity, type Tier, type ToolReport, type ToolSnapshot, type TransportKind, UsageError, VOKE_VERSION, type VokeConfig, type VokeSnapshot, allRules, annotationRules, buildProgram, buildReport, canonicalJson, createDefaultRegistry, descriptionRules, formatHuman, formatJson, ingestLive, maskHeaders, namingRules, parameterRules, readSnapshot, resolveLintOpts, resolveTarget, runLint, runRules, schemaRules, serializeReportBody, sha256, surfaceContentHash, toolContentHash, versionString, writeSnapshot };