code-auditor-mcp 4.1.1 → 5.0.2

package/dist/phase/phaseModel.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Spec 68 §11.1 — the general phase-model runner behind the both-paths split.
+ *
+ * `runPhaseModel` drives Parse → Process → Analyze over `MIGRATED_RULES`. The
+ * three-phase ordering and the "rules read facts, never ASTs" property are
+ * fixed here; §6's fan-out is realized as a bounded in-process work queue over
+ * one task per file (`workerCount` on {@link PhaseInfra}), with a deterministic
+ * file-sorted fact merge so `workerCount` is a tuning threshold, never a source
+ * of output reordering (§6.4). Tree-sitter `parse()` is synchronous CPU-bound
+ * work in one JS thread, so the queue is a structural unit rather than a
+ * wall-clock parallelizer; the guarantees §6 exists to deliver — per-file
+ * isolation (§3.3), byte-identical output across worker counts (§6.4), and a
+ * bounded in-flight window (§6.5) — are what land here.
+ *
+ * The fact set is *derived* from the migrated rules' `needs`: the union of every
+ * declared fact kind, transitively widened by corpus processors' upstream
+ * `needs` (today that is the one `ddl-declarations → resolution` edge). File
+ * facts are built by parsing each file once and running every matching
+ * per-(kind, format) producer over it; corpus facts are reduced in dependency
+ * order. Each rule then runs against exactly the facts it declared — no more,
+ * no less — which is what makes a rule's coverage state computable (§8).
+ *
+ * Thresholds are resolved by the caller (§10's config surface) and passed as a
+ * per-rule map; a rule with no entry reads its documented fallback. The rule's
+ * own `analyze` never reaches a tree, an adapter, or a source string.
+ */
+import { type InputFile } from './runner.js';
+import type { ExternalTableDecl, FactKind, Finding, OracleShortfall, ThresholdValues, UnreadStyleSourceFact, UnresolvedImportFact, UnresolvedQuerySite } from './types.js';
+import type { IndexHandle } from '../types.js';
+import type { UnprovenQueryReceiver } from '../analyzers/receiverResolution.js';
+import type { UnparseableSql } from '../analyzers/universal/schema/codeAnalysis.js';
+import type { Dialect } from '../mcp-tools/discoveryQueries.js';
+/**
+ * The result of a phase-model run: the migrated rules' findings plus the
+ * per-file fact completeness map that feeds §8's fifth coverage state
+ * (`incomplete`). A file is recorded against a fact kind when its parse failed
+ * (no producer for that kind could run on it) or a producer threw on it (§3.3).
+ */
+export interface PhaseModelResult {
+    findings: Finding[];
+    /** Fact kind → files whose fact is incomplete (parse dropped or producer threw). */
+    incompleteFacts: ReadonlyMap<FactKind, ReadonlySet<string>>;
+    /** Spec 69 R1 — per-file completeness shortfalls: a counted oracle whose
+     *  processor emitted fewer fragments than expected. Each record names the
+     *  file, the processor, and both numbers. An empty list means every counted
+     *  oracle met its expected count for every file. */
+    oracleShortfalls: readonly OracleShortfall[];
+    /** Spec 70 2c — the unproven query-shaped DB-call sites, re-derived corpus-side
+     *  from the `data-access-calls-candidates` fact + the `receiver-provenance` fixed
+     *  point with no AST. Replaces the pre-pass's `unprovenQueryReceivers` half; the
+     *  `cannot-fire` coverage diagnostic is re-derived from these in the caller. Empty
+     *  when `receiver-provenance` was not needed (no receiver-consuming rule active). */
+    unprovenQueryReceivers: readonly UnprovenQueryReceiver[];
+    /** The `receiver-provenance` fixed point's unresolved DB-looking imports — the
+     *  pre-pass's `unresolvedImports` half, carried on the fact itself (never a
+     *  separate pre-pass field). Empty when `receiver-provenance` was not needed. */
+    unresolvedImports: readonly UnresolvedImportFact[];
+    /** Spec 70 1b — the re-admitted DB-calls whose SQL argument is held in an
+     *  unresolvable identifier, re-derived corpus-side from the raw
+     *  `schema-usage-candidates` fact + the `receiver-provenance` fixed point with
+     *  no AST (`identifyHandle` re-admits each, so only DB handles qualify). Feeds
+     *  the `unresolved-query` coverage diagnostic re-homed in the caller. Empty when
+     *  `schema-usage` was not needed. */
+    unresolvedQuerySites: readonly UnresolvedQuerySite[];
+    /** Spec 70 R2 — the re-admitted tagged-template/DB-call SQL arguments whose
+     *  static text the named dialect could not parse, re-derived corpus-side from
+     *  the raw `schema-usage-candidates` fact + the `receiver-provenance` fixed
+     *  point with no AST (`classifyUnparseableSql` mirrors
+     *  `classifyUnresolvedQuerySites`, collecting `parseSqlTables().unparseable`
+     *  that `classifySchemaUsage` discards). Feeds the `unparseable` cannot-fire
+     *  diagnostic re-homed in the caller; each record is stamped with its `file`
+     *  so the caller can group per file as the legacy visitor did. Empty when
+     *  `schema-usage` was not needed. */
+    unparseableSql: readonly (UnparseableSql & {
+        file: string;
+    })[];
+}
+/**
+ * The corpus-level inputs the phase model needs beyond the file list. §8's
+ * `reachability` processor reads the discovery list, virtual-module list,
+ * tsconfig aliases and package.json entry points — all derived from the
+ * project root — so the runner threads them here rather than leaking config
+ * into the fact shapes. Every field is optional: the slice tests run a single
+ * fixture with none of this, and the processor falls back to the same defaults
+ * the legacy reducer did.
+ */
+export interface PhaseInfra {
+    /** Absolute project root (Tailwind config + alias/entry resolution). */
+    projectRoot?: string;
+    /** True for a scoped (changed/files/git) run. Gates the full-project unread
+     *  dialect walk (`.less`/`.styl`/`.sass`) to full runs only — the same
+     *  `if (!scoped)` the legacy `findUnreadStyleFiles` walk carried. Absent in
+     *  the slice tests (no project root, so the walk is skipped regardless). */
+    scoped?: boolean;
+    /** Full corpus discovery list (unfiltered) for alias resolution. */
+    corpusFiles?: readonly string[];
+    /** Virtual-module specifiers (config, default DEFAULT_VIRTUAL_MODULES). */
+    importVirtualModules?: readonly string[];
+    /** tsconfig `paths` + `baseUrl` for alias classification + resolution. */
+    tsconfigAliases?: {
+        pathPatterns?: readonly string[];
+        paths?: Readonly<Record<string, readonly string[]>>;
+        baseUrl?: string;
+    };
+    /** package.json entry points (facade-expanded), absolute. */
+    packageEntryPoints?: readonly string[];
+    /** The read-only code-index handle the index-backed corpus producers
+     *  (`call-graph`) read their facts from. Optional: the slice tests run a
+     *  single fixture with no index, and the producer degrades to an empty fact
+     *  (matching the legacy graceful-degradation). */
+    indexHandle?: IndexHandle;
+    /** The migrated rule ids to run (already filtered to the enabled analyzers).
+     *  Undefined runs every migrated rule — the slice-test / full-pipeline path.
+     *  A scoped, analyzer-restricted audit passes its subset so disabled analyzers'
+     *  facts (e.g. cross-domain's `call-graph` whole-table `functions` read) are
+     *  never built. */
+    enabledRules?: ReadonlySet<string>;
+    /** §16.8 fault injection — a hook invoked (and awaited) before each (kind,
+     *  file) producer runs. If it throws, the run treats it as that producer
+     *  throwing: the file is recorded `incomplete` for `kind` and the run
+     *  continues. Real runs pass none; the per-file-failure-isolation test passes
+     *  a hook that throws for one file to prove a single failure does not abort
+     *  the run or poison its neighbors. It may be async — the §16.5 ordering test
+     *  awaits a delay for one file to seed a slow processor. */
+    beforeProcess?: (kind: FactKind, file: string) => void | Promise<void>;
+    /** §16.5 ordering seam — invoked (and awaited) once, before the first rule's
+     *  `analyze` runs. The ordering test uses it to observe that analysis does not
+     *  begin until every file has been parsed and every processor level has
+     *  completed: a slow `beforeProcess` must finish before this fires. */
+    beforeAnalyze?: () => void | Promise<void>;
+    /** Spec 70 2b — invoked once after every file fact is merged (so the
+     *  `code-block` fact is assembled) and before any corpus fact is reduced (so
+     *  the `clone-pair-history` read sees the write). Named for its one job, not
+     *  its timing: it persists the dry-pair history to the index. Persisting the
+     *  `dry_pair_history` write (`seedDryPairs` over the `code-block` fact → the
+     *  `dry_pair_history` table) is its ONLY legitimate use — a general-purpose
+     *  "after file facts" hook is how declared-input discipline erodes, so this
+     *  seam is deliberately single-purpose and single-consumer. Absent in the
+     *  slice tests (single fixture, no index). */
+    persistDryPairHistory?: (facts: ReadonlyMap<FactKind, unknown>) => void | Promise<void>;
+    /** Config-declared external tables (schema analyzer's `knownTables` +
+     *  `schemas`), threaded to the `resolution` corpus producer so its
+     *  known-table set matches the legacy reducer (see {@link ExternalTableDecl}). */
+    externalTables?: ReadonlyArray<ExternalTableDecl>;
+    /** §6.6 — the bounded work queue's width: how many files parse/process
+     *  concurrently. Defaults to 1 (serial) at this seam; the entry point sizes
+     *  the pool to `max(1, cpus - 1)`. A threshold, not a selection gate: the
+     *  fact merge is file-sorted, so the value never reorders findings (§6.4). */
+    workerCount?: number;
+    /** Spec 70 R1 — the corpus's named SQL dialect (or null when unnamed). Threaded
+     *  to every parsed file so the `data-access-calls` producer parses SQL-content
+     *  facts rather than regex. Absent in the slice tests (single fixture). */
+    sqlDialect?: Dialect | null;
+    /** Spec 70 R2 — the corpus's dialect-detection reason (non-null only when
+     *  `sqlDialect` is null), threaded to the `unparseable` re-derivation so an
+     *  unparseable SQL argument in a dialect-undetermined corpus reports the *why*
+     *  rather than the generic fallback string (mirrors the legacy `schema-code`
+     *  visitor's `config.sqlDialectReason`). */
+    sqlDialectReason?: string | null;
+    /** Spec 70 criterion 9 (Item 3) — the project's declared type packages
+     *  (package.json `dependencies`/`devDependencies` ∪ tsconfig `compilerOptions.types`),
+     *  the ambient-arm gate for an unbound handle-type name. Absent (undefined) the
+     *  gate abstains: an unbound `D1Database` without a declared dependency stays
+     *  `unproven` rather than being credited `handle`. */
+    declaredTypePackages?: ReadonlySet<string>;
+}
+/**
+ * Run the full phase model over the given absolute file paths and return the
+ * migrated rules' findings. A no-op while `MIGRATED_RULES` is empty (the legacy
+ * pipeline serves everything, so the tool is functionally unchanged).
+ *
+ * @param filePaths - The absolute file paths to read and run through the model.
+ * @param thresholdsByRule - The resolved per-rule threshold map.
+ * @param infra - The optional corpus-level inputs (project root, index, workers).
+ * @returns The migrated rules' findings and the per-file fact completeness map.
+ */
+export declare function runPhaseModel(filePaths: readonly string[], thresholdsByRule: ReadonlyMap<string, ThresholdValues>, infra?: PhaseInfra): Promise<PhaseModelResult>;
+/**
+ * The file/corpus-pipeline half, exposed for the slice tests.
+ *
+ * @param files - The already-read input files to parse, process, and analyze.
+ * @param thresholdsByRule - The resolved per-rule threshold map.
+ * @param infra - The optional corpus-level inputs (project root, index, workers).
+ * @param unread - The traverse phase's walk-level unread-source reasons (dialect,
+ *   read-failure, unknown-extension), merged into the `unread-style-sources`
+ *   fact ahead of the corpus producer's table-derived content-level reasons.
+ * @returns The migrated rules' findings and the per-file fact completeness map.
+ */
+export declare function runPhaseModelOverFiles(files: readonly InputFile[], thresholdsByRule: ReadonlyMap<string, ThresholdValues>, infra?: PhaseInfra, unread?: readonly UnreadStyleSourceFact[]): Promise<PhaseModelResult>;
+//# sourceMappingURL=phaseModel.d.ts.map

package/dist/phase/phaseModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phaseModel.d.ts","sourceRoot":"","sources":["../../src/phase/phaseModel.ts"],"names":[],"mappings":"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"}