scip-query 0.20.0 → 0.21.0

package/dist/diff-gate-types-B0QYpDv1.d.ts

@@ -1,11 +0,0 @@
-type DiffGateActionTier = 'direct' | 'signal' | 'support';
-type DiffGateCheck = 'echo' | 'incomplete-migration' | 'co-change-partner' | 'twin-partner' | 'coverage-contract' | 'architecture' | 'doc-reference' | 'unused-params' | 'new-dead' | 'baseline';
-type DocCitationKind = 'behavioral-claim' | 'configuration-example' | 'guide-reference' | 'intentional-record';
-/** A contiguous changed line span within one file, as parsed from a diff. */
-interface ChangedLineRange {
-    file: string;
-    startLine: number;
-    endLine: number;
-}
-
-export type { ChangedLineRange as C, DiffGateCheck as D, DiffGateActionTier as a, DocCitationKind as b };

package/dist/direct-navigation-6YHV6IB5.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import{p as a}from"./chunk-F3Z4OUDS.js";import"./chunk-JFGGXWQF.js";export{a as directNavigationQueryCommandDescriptors};
-//# sourceMappingURL=direct-navigation-6YHV6IB5.js.map

package/dist/queries/diff-gate.d.ts

@@ -1,253 +0,0 @@
-import { S as ScipDatabase } from '../db-B5PM5yNk.js';
-import { C as CoChangeCommitScope, a as CoChangeRecency, b as CoChangeSubjectContext, G as GitHistoryMode } from '../git-history-ChNHbfZQ.js';
-import { CoChangePartnerClass, DeclaredCouplingSuggestion } from './co-change.js';
-import { AttributionNote, DiffImpactEvidenceTierStatus, DiffImpactPlan, BaseContentReader, BaseContentGitRuntime } from './diff-impact.js';
-import { D as DiffGateCheck, a as DiffGateActionTier, b as DocCitationKind } from '../diff-gate-types-B0QYpDv1.js';
-import { F as FindingSuppression } from '../config-types-jVM3D7MA.js';
-import 'better-sqlite3';
-import '../symbol-types-BIQwfoAx.js';
-
-type RecordCompatibilityState = 'legacy' | 'current' | 'unsupported-older' | 'unsupported-future' | 'malformed';
-interface RecordCompatibilityIssue {
-    path: string;
-    state: Exclude<RecordCompatibilityState, 'legacy' | 'current'>;
-    reason: string;
-}
-/**
- * Exact accounting for a set of persisted record candidates. A partial read
- * may still return accepted records, but it cannot represent that subset as a
- * complete repository history.
- */
-interface RecordCompatibilitySummary {
-    complete: boolean;
-    total: number;
-    accepted: number;
-    legacy: number;
-    current: number;
-    unsupportedOlder: number;
-    unsupportedFuture: number;
-    malformed: number;
-    omitted: number;
-    issues: RecordCompatibilityIssue[];
-}
-
-/** Canonical check list — the CLI validates `--skip` values against this. */
-declare const DIFF_GATE_CHECKS: readonly DiffGateCheck[];
-type DiffGateEvidence = 'graph-fact' | 'semantic' | 'heuristic' | 'change-graph' | 'baseline';
-type DiffGateSeverity = 'info' | 'warning' | 'error';
-
-interface DiffGateFinding {
-    id: string;
-    check: DiffGateCheck;
-    severity: DiffGateSeverity;
-    evidence: DiffGateEvidence;
-    /** Actionability tier for reviewers and automation. */
-    actionTier?: DiffGateActionTier;
-    /** Stable grouping key for multiple evidence rows behind one review item. */
-    groupKey?: string;
-    confidence?: number;
-    file?: string;
-    startLine?: number;
-    endLine?: number;
-    symbol?: string;
-    relatedFiles?: string[];
-    /**
-     * Advisory findings surface useful signal but must never be the sole
-     * cause of a nonzero diff-gate exit code (see `blockingFindings`). Used
-     * by twin-partner until calibration (remediation plan phase 21) says the
-     * check's precision earns a hard gate; also used by doc-reference (21.2)
-     * for bare file-mention citations — see `runDocReferenceCheck`.
-     */
-    advisory?: boolean;
-    /** Underlying analyzer family when one gate finding wraps another analyzer. */
-    sourceAnalyzer?: string;
-    /** Stable root-cause grouping key inside the source analyzer. */
-    rootCauseKey?: string;
-    /** Relationship label for co-change partner findings. */
-    partnerClass?: CoChangePartnerClass;
-    partnerClassReasons?: string[];
-    declaredCouplingSuggestion?: DeclaredCouplingSuggestion;
-    commitScope?: CoChangeCommitScope;
-    recency?: CoChangeRecency;
-    focusedTogether?: number;
-    broadTogether?: number;
-    broadCommitRatio?: number;
-    lastTogetherAt?: number;
-    recentTogether?: number;
-    subjectContext?: CoChangeSubjectContext;
-    /** Why a doc cites changed code, when check is doc-reference. */
-    citationKind?: DocCitationKind;
-    citationKindReasons?: string[];
-    /** Bounded nearby doc text that contains the changed-file citation. */
-    citedClaims?: string[];
-    /**
-     * Set only on a hub-file-cascade-damped doc-reference finding (21.2's
-     * successor damping step — see `clusterDocReferenceCitations`): total
-     * distinct docs citing the same hub file in this diff, before damping.
-     */
-    citationCount?: number;
-    /** Up to `DOC_REFERENCE_HUB_FILE_EXEMPLAR_LIMIT` sample citations shown for a damped hub-file finding. */
-    citationExemplars?: Array<{
-        doc: string;
-        citedClaims: string[];
-    }>;
-    /**
-     * Docs counted in `citationCount` but not individually reported —
-     * disclosed explicitly rather than silently dropped (still counted, just
-     * not each surfaced as its own finding).
-     */
-    suppressedCount?: number;
-    /**
-     * The per-doc finding ids a hub-file cluster replaced, kept for JSON
-     * addressability only. Deliberately NOT `legacySuppressionIds`: suppression
-     * matching honors that field, and a cluster carries N member ids — reusing
-     * it would let one pre-clustering per-doc suppression silently suppress the
-     * entire cluster (one acknowledged citation hiding eleven unacknowledged
-     * ones). To suppress the cluster, target the cluster's own `id`.
-     */
-    memberFindingIds?: string[];
-    message: string;
-    why: string[];
-    /** Concrete remediation an agent can act on without human triage. */
-    remediation: string;
-    suppressionHint?: string;
-    legacySuppressionIds?: string[];
-}
-interface DiffGateRootCauseGroup {
-    groupKey: string;
-    check: DiffGateCheck;
-    severity: DiffGateSeverity;
-    actionTier?: DiffGateActionTier;
-    sourceAnalyzer?: string;
-    rootCauseKey?: string;
-    count: number;
-    findingIds: string[];
-    files: string[];
-    relatedFiles: string[];
-    message: string;
-    remediation: string;
-}
-interface DiffGateResult {
-    base: string;
-    changedFiles: string[];
-    changedSymbols: number;
-    checksRun: DiffGateCheck[];
-    /** Checks that could not run (no git history, no baseline file, ...). */
-    skipped: Array<{
-        check: DiffGateCheck;
-        reason: string;
-    }>;
-    /** Findings accepted by structured .scipquery.json suppressions. */
-    suppressed: Array<{
-        finding: DiffGateFinding;
-        suppression: FindingSuppression;
-    }>;
-    /** Model-proposed decisions that could not enter the narrow automatic lane. */
-    policyEscalations?: Array<{
-        findingId: string;
-        check: DiffGateCheck;
-        suppressionId?: string;
-        reasons: string[];
-    }>;
-    /** Machine-visible distinction between a clean gate and an automatically adjudicated gate. */
-    outcome?: 'pass' | 'pass-with-suppressions' | 'findings';
-    suppressionSummary?: {
-        automaticSuppressionCount: number;
-        policyEscalationCount: number;
-        expiredCount: number;
-        invalidatedCount: number;
-        legacyUnadjudicatedCount: number;
-    };
-    findings: DiffGateFinding[];
-    attributionNotes: AttributionNote[];
-    evidenceTiers: DiffImpactEvidenceTierStatus[];
-    /** Root-cause review items derived from unsuppressed findings. */
-    rootCauseGroups?: DiffGateRootCauseGroup[];
-    /** Coverage of committed policy records consulted by this result. */
-    recordCompatibility?: {
-        suppressions: RecordCompatibilitySummary;
-    };
-    note?: string;
-}
-/**
- * Slop prevention at the moment of creation: every detector, scoped to what
- * THIS diff introduces. O(diff), no LLM calls, exit-code friendly — the
- * leading-indicator companion to the repo-wide ratchet.
- *
- * Checks:
- * - echo:               a symbol this diff touched closely resembles
- *                       established code elsewhere — likely re-implementation.
- * - incomplete-migration: a helper added in this diff was wired into some
- *                       sites, but similar un-migrated sites remain elsewhere
- *                       — the extraction stopped partway.
- * - co-change-partner:  a changed file's strong historical partner is NOT in
- *                       the diff — the change-graph contract says they move
- *                       together (auto-derived sync enforcement).
- * - twin-partner:       (advisory, never fails the gate alone) a changed
- *                       symbol has a same-(near-)name twin elsewhere that
- *                       was identical or already-divergent and is NOT in
- *                       the diff — a one-sided fix candidate.
- * - coverage-contract:  a configured `coverageContracts` entry drifted —
- *                       its declared key set no longer matches its
- *                       ground-truth source (enumeration rot).
- * - architecture:       a project-owned boundary rule now has a violation
- *                       absent from the committed health baseline.
- * - doc-reference:      a doc cites a changed file but isn't updated in the
- *                       diff — the drift starts here.
- * - unused-params:      changed files now contain trailing parameters no body
- *                       uses — speculative generality landing fresh.
- * - new-dead:           changed symbols with zero indexed consumers — possibly
- *                       a half-wired feature.
- * - baseline:           optional full health-baseline ratchet.
- */
-declare function diffGate(db: ScipDatabase, opts?: {
-    base?: string;
-    minTogether?: number;
-    minConfidence?: number;
-    maxEchoChecks?: number;
-    maxHelpers?: number;
-    minSimilarity?: number;
-    includeBaseline?: boolean;
-    scanLimit?: number;
-    semantic?: boolean;
-    historyMode?: GitHistoryMode;
-    skip?: readonly DiffGateCheck[];
-    baseContentRuntime?: BaseContentGitRuntime;
-}): DiffGateResult;
-/**
- * Findings that count toward the pass/fail decision. Advisory findings
- * (currently: twin-partner) still print and are still suppressible, but a
- * diff with only advisory findings must exit 0 — see the `advisory` field
- * doc comment on `DiffGateFinding`.
- */
-/**
- * True when the gate could not run at all (git diff unavailable — e.g. a
- * diff larger than the exec buffer, a bad --base ref, or git missing) and
- * therefore ran zero checks. Consumers MUST fail closed on this: a gate
- * that silently passes because it could not look is not a gate.
- * Discovered on the 2026-07-01 Vega calibration run (8,099-file commit).
- */
-declare function diffGateFailedClosed(result: DiffGateResult): boolean;
-declare function diffGateFailureReason(result: DiffGateResult): string | undefined;
-declare function blockingFindings(findings: readonly DiffGateFinding[]): DiffGateFinding[];
-interface SymbolPreexistenceCheckerOptions {
-    projectRoot: string;
-    base: string;
-    diffPlan: DiffImpactPlan;
-    baseContentAt?: BaseContentReader;
-}
-declare function symbolPreexistenceChecker(options: SymbolPreexistenceCheckerOptions): (changedSymbol: {
-    symbol: string;
-    file: string;
-}) => boolean;
-/**
- * @deprecated Use
- * `symbolPreexistenceChecker({ projectRoot, base, diffPlan, baseContentAt })`
- * so the project root and Git revision cannot be transposed.
- */
-declare function symbolPreexistenceChecker(projectRoot: string, base: string, diffPlan: DiffImpactPlan, baseContentAt?: BaseContentReader): (changedSymbol: {
-    symbol: string;
-    file: string;
-}) => boolean;
-
-export { DIFF_GATE_CHECKS, DiffGateActionTier, DiffGateCheck, type DiffGateEvidence, type DiffGateFinding, type DiffGateResult, type DiffGateRootCauseGroup, type DiffGateSeverity, DocCitationKind, type SymbolPreexistenceCheckerOptions, blockingFindings, diffGate, diffGateFailedClosed, diffGateFailureReason, symbolPreexistenceChecker };

package/dist/queries/diff-gate.js

@@ -1,2 +0,0 @@
-import{e as a,f as b,g as c,h as d,i as e,j as f}from"../chunk-RJT3TUUZ.js";import"../chunk-FKSELJQF.js";import"../chunk-KMKTIO2G.js";import"../chunk-PXY7F6Y4.js";import"../chunk-YLCJLTPL.js";import"../chunk-HX4GQPZP.js";import"../chunk-MKCDWWGV.js";import"../chunk-6YTSKJJ3.js";import"../chunk-6O5TICIZ.js";import"../chunk-N5W4YZMK.js";import"../chunk-EN3O7VJA.js";import"../chunk-MV7OWDUX.js";import"../chunk-EW2NTSFA.js";import"../chunk-7SQQWSY3.js";import"../chunk-FYLK2DEJ.js";import"../chunk-B2PX5I6M.js";import"../chunk-JVYA47YU.js";import"../chunk-ZHXX42OH.js";import"../chunk-QOKYJ33H.js";import"../chunk-GOUBFH5O.js";import"../chunk-6SHPK5ZE.js";import"../chunk-ZK26BAQL.js";import"../chunk-RUJURYSV.js";import"../chunk-ZTETIQ35.js";import"../chunk-Y2MVPNKY.js";import"../chunk-KMVGRIO2.js";import"../chunk-RXOXSKY3.js";import"../chunk-YTQVETEO.js";import"../chunk-QZ4JVECJ.js";import"../chunk-35NLDRZC.js";import"../chunk-UJCOIXDY.js";import"../chunk-26QA6FAI.js";import"../chunk-AQOFWNQJ.js";import"../chunk-DHEQMPLW.js";import"../chunk-B75HZHUP.js";import"../chunk-BGBBVSH4.js";import"../chunk-Z4N3MZYA.js";import"../chunk-7O5IKBTZ.js";import"../chunk-HX7M4BDI.js";import"../chunk-P5XHIJHI.js";import"../chunk-T7YQSHPQ.js";import"../chunk-7WPLAODU.js";import"../chunk-BS2NMXQZ.js";import"../chunk-C43RDDP4.js";import"../chunk-MTDBHTSF.js";import"../chunk-EKZTZXHZ.js";import"../chunk-UJPRPGCO.js";import"../chunk-GH74ASD6.js";import"../chunk-WCCFZ7V7.js";import"../chunk-NGEXCJJW.js";import"../chunk-7S5E7KWT.js";import"../chunk-2KAZEZ6M.js";import"../chunk-C3KV2II6.js";export{a as DIFF_GATE_CHECKS,e as blockingFindings,b as diffGate,c as diffGateFailedClosed,d as diffGateFailureReason,f as symbolPreexistenceChecker};
-//# sourceMappingURL=diff-gate.js.map

package/docs/COMMITTED_RECORD_COMPATIBILITY.md

@@ -1,154 +0,0 @@
-# Committed record compatibility
-
-scip-query stores two kinds of team-shared records in Git:
-
-- `.scipquery/suppressions/*.json` contains accepted detector-policy
-  decisions.
-- `.scipquery/events/*.json` contains immutable finding-transition
-  observations used by `effectiveness` and cross-HEAD repair verification.
-
-A committed record is a repository-owned JSON fact or policy whose value
-comes from surviving clones and branches. Unlike a local cache row, it cannot
-be silently dropped and rebuilt when a reader does not understand it.
-
-## Compatibility states
-
-Every JSON candidate is classified exactly once:
-
-| State                | Meaning                                                           | Included in conclusions? |
-| -------------------- | ----------------------------------------------------------------- | ------------------------ |
-| `legacy`             | A supported unversioned record from an earlier scip-query release | Yes                      |
-| `current`            | A record matching the current discriminator and schema            | Yes                      |
-| `unsupported-older`  | A versioned record older than the supported overlap window        | No                       |
-| `unsupported-future` | A record written by a newer incompatible schema                   | No                       |
-| `malformed`          | Invalid JSON, fields, discriminator, metadata, or stable identity | No                       |
-
-`complete` is true only when every candidate is `legacy` or `current`.
-Readers return accepted records together with `total`, `accepted`, `omitted`,
-the per-state counts, and path-specific issues. A subset may still support a
-conservative result, but it must not be represented as complete.
-
-## Current suppression records
-
-New records conform to
-[`schemas/suppression-record.schema.json`](schemas/suppression-record.schema.json).
-They carry:
-
-- `kind: "scip-query-suppression"`;
-- `schemaVersion: 2`;
-- the stable `suppressionIdentity`;
-- producer name/version and creation/update timestamps;
-- the exact suppression target and explanatory reason;
-- a controlled adjudication reason code;
-- inspectable counterevidence, including content hashes for file referents;
-- the policy version, decision provenance, and invalidation conditions.
-
-Current readers accept v1 and unversioned records as legacy policy so history
-is not lost. Legacy records do not have enough mechanically checkable evidence
-to authorize automatic acceptance: matching findings remain visible as policy
-escalations until the record is explicitly replaced with a v2 decision.
-Earlier readers classify v2 as unsupported-future and therefore fail closed
-instead of silently treating the new evidence fields as optional. The filename
-remains the conflict domain: different suppression identities merge as
-different paths, while policy changes to one identity require revision-aware
-replacement.
-
-If a legacy, future, malformed, expired, or content-invalidated suppression
-cannot pass current policy, it cannot waive a finding. `diff-gate` keeps the
-matching finding unsuppressed and reports incomplete coverage or the exact
-policy-escalation reason in JSON, human output, and Stop-hook feedback. A
-successful gate that did accept one or more v2 decisions reports
-`pass-with-suppressions`, preserving the difference between an ordinary clean
-pass and an adjudicated exception.
-
-## Current outcome-event records
-
-New records conform to
-[`schemas/outcome-event-record.schema.json`](schemas/outcome-event-record.schema.json).
-They retain all semantic event fields at the root and add:
-
-- `kind: "scip-query-outcome-event"`;
-- `schemaVersion: 1`;
-- `eventIdentity`, the JSON tuple of check, finding ID, transition, and
-  observed commit;
-- producer name/version;
-- `gateRunId`, the logical diff-gate observation shared by retries;
-- observer kind and whether its authority is repository-writable or protected
-  externally;
-- the index/worktree observation receipt;
-- the adjudication policy version on suppressed transitions.
-
-Keeping semantic fields at the root lets the immediately prior permissive
-reader consume new records. Current readers accept both these v1 records and
-the existing unversioned event files.
-
-The immutable filename is still a timestamp plus a hash of the complete
-record bytes. Deduplication does not use that path or producer metadata; it
-uses the semantic `eventIdentity`. If legacy and current records describe the
-same fact, comparable-base proof wins first, then protected/provenance-bearing
-evidence, and then the earliest timestamp.
-
-Observer kind says who originated the record: `local-agent`, `local-human`,
-or `protected-ci`. Observer authority says what conclusion the record can
-support. Both local kinds remain `repository-writable`, because the observer
-can edit the same event and suppression files being measured.
-`protected-external` is accepted only with `protected-ci` records produced by
-a separately controlled evaluator and a gate-run attestation delivered
-outside the writable event directory; a record field cannot attest itself
-and ordinary CLI environment settings cannot mint that authority.
-
-## Partial history is conservative
-
-`effectiveness --json` includes
-`recordCompatibility.outcomeEvents`. Human output prints the same incomplete
-coverage counts before any metrics. Metrics use only accepted records and are
-therefore explicitly partial when `complete` is false.
-
-`effectiveness` calls the ordinary local ratio
-`resolutionVsSuppressionRate`. It publishes `precision` only when every event
-in the evaluated population claims protected external authority and its
-gate-run ID appears in a separately supplied attestation set. Mixed,
-unattested, repository-writable, and legacy populations remain telemetry and
-carry a null precision field. Provenance gaps, unattested authority claims,
-mixed authority, missing gate-run identity, and anomalous suppression rates
-produce bounded sample reports, not a mandatory per-suppression human queue.
-Git preserves history that is present; deleting an event file cannot be
-detected from the remaining directory, so the command never describes
-repository-local totals as an independent grade.
-
-Cross-HEAD repair verification needs complete committed history to establish
-the prior lifecycle anchor. If any event candidate is incompatible, scip-query
-retains every missing local-ledger finding and defers resolution. An omitted
-record can therefore delay a verified fix, but it cannot manufacture one.
-
-## Legacy JSONL migration
-
-`.scipquery/ledger/events.jsonl` remains readable during the overlap window.
-On the next event append:
-
-1. every non-empty line is classified;
-2. compatible lines are copied to independent current event files;
-3. new observations are appended normally;
-4. the legacy ledger and its `merge=union` attribute are removed only if
-   every line was compatible.
-
-If even one line is unsupported or malformed, the original ledger stays
-byte-for-byte present and the append reports a warning. Repeating the append
-is safe: exclusive content-addressed event creation makes already-copied rows
-idempotent. Upgrade scip-query or repair the named malformed line before
-removing the legacy ledger.
-
-## Merge and rollback rules
-
-- Commit suppression and event files with the code or documentation change
-  that produced them.
-- Do not rewrite all legacy files just to make compatibility counters
-  “current.” Read overlap is the migration mechanism.
-- Resolve a same-suppression-path conflict by reviewing both policy decisions;
-  never choose a side mechanically.
-- Independent event files should normally keep both sides of a merge.
-- Do not delete an unsupported record to make a warning disappear. Use a
-  reader that supports it, or deliberately migrate it with verified tooling.
-- Rolling back remains fail-closed: older readers reject v2 suppressions as
-  unsupported-future, so they cannot accidentally waive a finding using a
-  policy they do not understand.