@de-otio/bibcheck 0.1.0

package/dist/schema/output.d.ts.map

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

package/dist/schema/output.js

@@ -0,0 +1,419 @@
+/**
+ * bibcheck output JSON schema — the contract consumers (LLM agents, CI tools,
+ * editor integrations) read.
+ *
+ * FROZEN. This schema is the contract every renderer and consumer reads;
+ * changes require a surfaced design decision (see tmp/design-review/) and a
+ * `SCHEMA_VERSION` bump. Do not edit ad hoc.
+ *
+ * Versioned independently of the package version via `SCHEMA_VERSION` below.
+ * Bumping rules:
+ *   - Additive changes (new optional fields, new enum members on otherwise-open
+ *     types) bump the minor part and remain backward-compatible.
+ *   - Renames, removals, or changed semantics bump the major part; consumers
+ *     pinning a major version are insulated.
+ *
+ * 0.3.0 (H2 — reverse-linkage / orphan detection): added the `'orphan'`
+ * member to `LinkageStatusSchema` (a bibliography citekey never referenced in
+ * any doc — the inverse of `'unresolved'`) and the OPTIONAL `orphanedEntries`
+ * summary counter. Orphans are INFORMATIONAL: they are surfaced but MUST NOT
+ * gate `bibcheck check` (an uncited bibliography entry is a smell, not proof of
+ * fabrication; gating would train users to disable checks). The change is
+ * purely additive — the `linkageFailures` invariant counts only `'unresolved'`
+ * entries, so orphans (status `'orphan'`) are naturally excluded — and the new
+ * summary counter is optional so existing Output builders that do not populate
+ * it keep emitting valid documents.
+ *
+ * 0.2.0 (Phase 5 — hallucination-hardening): added the existence evidence
+ * vocabulary (`ExistenceEvidenceSchema`) and verification-boundary fields
+ * (`evidence` / `checkedFor` / `notCheckedFor` / `error` on the existence
+ * layer); the per-entry `IdentifiersLayerSchema` (local DOI/ISBN/URL
+ * well-formedness); the `notFoundInDatabases` + `malformedIdentifiers`
+ * summary counters with existence-bucket reconciliation; and the optional
+ * `locator` / `authorSuppressed` linkage/worklist fields for the
+ * citation-parser swap. The new per-entry/summary fields are presently
+ * OPTIONAL so that the v0.1 producer (which does not yet populate them) keeps
+ * emitting valid documents; T21/T22/T25 populate them and a follow-up tightens
+ * them to required (see the `TODO(T22)` markers below).
+ *
+ * Authoritative documentation is the Zod schemas in this file. The published
+ * JSON Schema in `docs/output-schema.md` (when generated) is derived from
+ * these definitions, not maintained by hand.
+ */
+import { z } from 'zod';
+/** Current bibcheck output schema version. Independent of the package version. */
+export const SCHEMA_VERSION = '0.3.0';
+/**
+ * Accepts any URL whose scheme is http or https. Rejects non-web schemes
+ * such as `javascript:`, `file://`, `data:`, and `ftp://`.
+ */
+const httpUrl = () => z.string().url().refine((u) => /^https?:\/\//i.test(u), {
+    message: 'Only http/https URLs are accepted',
+});
+// ---------------------------------------------------------------------------
+// Tool info
+// ---------------------------------------------------------------------------
+export const ToolInfoSchema = z.object({
+    name: z.literal('bibcheck'),
+    version: z.string().min(1),
+});
+// ---------------------------------------------------------------------------
+// Summary counts
+// ---------------------------------------------------------------------------
+export const SummarySchema = z.object({
+    totalEntries: z.number().int().nonnegative(),
+    verified: z.number().int().nonnegative(),
+    metadataMismatches: z.number().int().nonnegative(),
+    /**
+     * Entries confirmed absent from every applicable database (a fabrication
+     * signal; gates by default per Q1). NEW in 0.2.0.
+     */
+    notFoundInDatabases: z.number().int().nonnegative(),
+    /**
+     * Entries with at least one malformed/bad-checksum identifier in the
+     * `identifiers` layer (a cheap fabrication signal; gates by default). NEW
+     * in 0.2.0.
+     */
+    malformedIdentifiers: z.number().int().nonnegative(),
+    unverifiable: z.number().int().nonnegative(),
+    canonicalIssues: z.number().int().nonnegative(),
+    linkageFailures: z.number().int().nonnegative(),
+    phraseFlags: z.number().int().nonnegative(),
+    worklistItems: z.number().int().nonnegative(),
+    /**
+     * Bibliography entries whose citekey is never referenced in any markdown doc
+     * (reverse linkage; the inverse of `linkageFailures`). INFORMATIONAL — an
+     * uncited entry is a smell (e.g. an LLM-padded reference list), not proof of
+     * fabrication, so it does NOT gate `bibcheck check`. OPTIONAL so the counter
+     * is additive: Output builders predating 0.3.0 that omit it stay valid. NEW
+     * in 0.3.0.
+     */
+    orphanedEntries: z.number().int().nonnegative().optional(),
+});
+// ---------------------------------------------------------------------------
+// Layer 1: existence (commodity convenience layer)
+//
+// DOI / ISBN / title-search lookup against CrossRef, OpenAlex, OpenLibrary.
+// A thin direct-fetch wrapper, not a heavyweight resolver. (WorldCat / OCLC
+// Classify was removed in 0.2.0 — the Classify endpoint was decommissioned in
+// 2019; see tmp/design-review/worldcat.md. ISBN existence is covered by
+// OpenLibrary.)
+// ---------------------------------------------------------------------------
+export const ExistenceCheckSourceSchema = z.enum([
+    'crossref',
+    'openalex',
+    'openlibrary',
+]);
+export const ExistenceCheckResultSchema = z.enum([
+    'no-doi',
+    'found',
+    'not-found',
+    'metadata-mismatch',
+    'error',
+]);
+export const ExistenceCheckSchema = z.object({
+    source: ExistenceCheckSourceSchema,
+    result: ExistenceCheckResultSchema,
+    /** Source-specific evidence. Shape varies per source; not strictly typed. */
+    evidence: z.unknown().nullable(),
+});
+export const ExistenceStatusSchema = z.enum([
+    'verified',
+    'metadata-mismatch',
+    'not-found-in-databases',
+    'unverifiable',
+]);
+/**
+ * Defined per-entry evidence vocabulary, distinct from the bare `status`
+ * rollup, so an LLM-agent consumer cannot read `verified` as "the citation's
+ * claim is sound" (Q2). Deliberately discrete — there is NO numeric confidence
+ * score anywhere in this schema (barred by the project's "no uncalibrated
+ * confidence scores" design default); the vocabulary is the calibrated
+ * alternative.
+ */
+export const ExistenceEvidenceSchema = z.enum([
+    'exists-metadata-match', // found + metadata agrees
+    'exists-metadata-mismatch', // found, but metadata differs
+    'absent', // confirmed not-found in all applicable databases
+    'unverifiable', // no applicable identifier, or all sources errored
+]);
+/**
+ * The verification dimensions bibcheck can report on. Used by the existence
+ * layer's `checkedFor` / `notCheckedFor` arrays to state explicitly what was
+ * and was NOT checked. `claim-support` (does the source actually support the
+ * prose's claim?) is never checked automatically — it is the manual worklist's
+ * job — so it always appears in `notCheckedFor` for v0.1.
+ */
+export const CheckDimensionSchema = z.enum([
+    'existence',
+    'metadata',
+    'canonical-url',
+    'claim-support',
+]);
+export const ExistenceLayerSchema = z.object({
+    status: ExistenceStatusSchema,
+    /** Defined evidence vocabulary (Q2). NEW in 0.2.0. */
+    evidence: ExistenceEvidenceSchema,
+    /** Dimensions that were checked, e.g. ['existence','metadata']. NEW in 0.2.0. */
+    checkedFor: z.array(CheckDimensionSchema),
+    /**
+     * Dimensions that were NOT checked. Always includes 'claim-support' for
+     * v0.1 (bibcheck never verifies whether the source supports the prose's
+     * claim; that is the manual worklist's job). NEW in 0.2.0.
+     */
+    notCheckedFor: z.array(CheckDimensionSchema),
+    checks: z.array(ExistenceCheckSchema),
+    /**
+     * Set when the layer crashed (vs. a clean unverifiable result), so consumers
+     * can distinguish "we ran and found nothing applicable" from "we failed to
+     * run." NEW in 0.2.0 (also addresses S1). Null when the layer ran cleanly.
+     */
+    error: z.string().nullable(),
+});
+// ---------------------------------------------------------------------------
+// Layer 0: identifiers (local, pre-network well-formedness)
+//
+// A pure, local check of DOI/ISBN/URL well-formedness, run BEFORE any network
+// existence lookup (Q5 / T21). Kept as its own per-entry layer — sibling to
+// `existence` and `canonical` — so "is the identifier well-formed" stays
+// cleanly distinct from "does the work exist," and so sibling bibliography-
+// hygiene checks can grow into the same space later. A malformed identifier is
+// a strong, cheap fabrication signal and gates by default (consistent with the
+// Q1 secure default).
+// ---------------------------------------------------------------------------
+export const IdentifierStatusSchema = z.enum([
+    'ok',
+    'malformed',
+    'bad-checksum',
+    'not-applicable',
+]);
+export const IdentifiersLayerSchema = z.object({
+    /** 'malformed' if the DOI fails `^10\.\d{4,}/\S+$`. */
+    doi: IdentifierStatusSchema,
+    /** 'bad-checksum' for a failed ISBN-10/13 check digit; 'malformed' for bad shape. */
+    isbn: IdentifierStatusSchema,
+    /** 'malformed' if the URL is not a well-formed http/https URL. */
+    url: IdentifierStatusSchema,
+});
+// ---------------------------------------------------------------------------
+// Layer 1: canonical-edition URL verification (differentiated)
+//
+// For pre-DOI primary sources, checks that each entry's `url:` field points
+// to a trusted canonical-edition host (HathiTrust, Internet Archive, Liberty
+// Fund OLL, plato.stanford.edu/archives, PhilPapers, national-library
+// catalogues, project-extensible) and that the URL is live.
+// ---------------------------------------------------------------------------
+export const CanonicalStatusSchema = z.enum([
+    'verified-canonical',
+    'wrong-host',
+    'dead-url',
+    'live-url-not-archived-snapshot',
+    'no-url-on-pre-doi-entry',
+    'not-applicable',
+]);
+export const CanonicalLayerSchema = z.object({
+    status: CanonicalStatusSchema,
+    url: httpUrl().nullable(),
+    /** Redirect chain, in order, if HEAD followed redirects. */
+    redirectChain: z.array(httpUrl()).optional(),
+});
+// ---------------------------------------------------------------------------
+// Per-entry record
+// ---------------------------------------------------------------------------
+export const EntrySchema = z.object({
+    citekey: z.string().min(1),
+    /**
+     * Layer 0 local identifier well-formedness (pre-network). Null when not run.
+     * NEW in 0.2.0 (Q5 / T21).
+     */
+    identifiers: IdentifiersLayerSchema.nullable(),
+    /** Layer 1 existence findings (commodity layer). Null when not run. */
+    existence: ExistenceLayerSchema.nullable(),
+    /** Layer 1 canonical-edition findings (differentiated layer). Null when not run. */
+    canonical: CanonicalLayerSchema.nullable(),
+});
+// ---------------------------------------------------------------------------
+// Layer 1 (structural): linkage
+//
+// Every `@citekey` reference in the docs has an entry in the bibliography.
+// Deterministic equivalent of pandoc-citeproc's render-time warning.
+// ---------------------------------------------------------------------------
+/**
+ * 'resolved'   — citekey appears in prose AND in the bibliography.
+ * 'unresolved' — citekey appears in prose but NOT in the bibliography (gates).
+ * 'orphan'     — citekey appears in the bibliography but is NOT referenced in
+ *                any prose doc (reverse linkage). INFORMATIONAL; never gates.
+ *                NEW in 0.3.0.
+ */
+export const LinkageStatusSchema = z.enum(['resolved', 'unresolved', 'orphan']);
+export const LinkageReferenceSchema = z.object({
+    file: z.string().min(1),
+    line: z.number().int().positive(),
+    /** Citation locator, e.g. 'p. 42', 'pp. 33-35'. NEW in 0.2.0 (T25 populates). */
+    locator: z.string().nullable().optional(),
+    /** True when the citation suppressed the author, e.g. '-@key'. NEW in 0.2.0 (T25). */
+    authorSuppressed: z.boolean().optional(),
+});
+export const LinkageEntrySchema = z.object({
+    citekey: z.string().min(1),
+    status: LinkageStatusSchema,
+    references: z.array(LinkageReferenceSchema),
+});
+// ---------------------------------------------------------------------------
+// Phrase denylist matches
+//
+// Regex pass over prose against a project-supplied phrase denylist (loaded
+// via `[phrases] file = "..."` in bibcheck.toml). bibcheck does not ship a
+// baseline; the feature is a configurable lint, not curated guidance.
+//
+// A match without an explicit `<!-- bibcheck-allow: <key> -->` acknowledgement
+// is reported as `flagged`; matches with the acknowledgement are reported as
+// `acknowledged` (informational).
+// ---------------------------------------------------------------------------
+export const PhraseFlagStatusSchema = z.enum([
+    'flagged',
+    'acknowledged',
+]);
+export const PhraseFlagSchema = z.object({
+    status: PhraseFlagStatusSchema,
+    /** Stable key naming the denylist pattern that matched. */
+    patternKey: z.string().min(1),
+    /** Optional project-supplied URL — typically a doc explaining why this phrase is denylisted. */
+    referenceUrl: httpUrl().nullable(),
+    file: z.string().min(1),
+    line: z.number().int().positive(),
+    /** The substring of the prose that matched the pattern. */
+    matchedText: z.string().min(1),
+});
+// ---------------------------------------------------------------------------
+// Layer 2 / Layer 3: human-triage worklist
+//
+// Items emitted by bibcheck for manual verification. The tool does not
+// attempt to resolve these; the worklist is the bridge between automated
+// and manual layers of the policy.
+// ---------------------------------------------------------------------------
+export const WorklistItemTypeSchema = z.enum([
+    /** A direct quotation needs to be verified verbatim against the source. */
+    'direct-quotation',
+    /** A paraphrase attached to a page or section reference needs to be checked. */
+    'paraphrase-with-page-ref',
+    /** Cited source is on a contested-coverage source-type (Wikipedia, blog, preprint). */
+    'contested-source-type',
+    /** Citation references a non-canonical edition where a canonical one exists. */
+    'non-canonical-edition',
+]);
+export const WorklistItemSchema = z.object({
+    type: WorklistItemTypeSchema,
+    file: z.string().min(1),
+    line: z.number().int().positive(),
+    /** The citation invocation in the prose, e.g., `@mill1859onliberty`. */
+    citation: z.string().min(1),
+    /** Excerpt of prose around the citation, for context. */
+    snippet: z.string().min(1),
+    /** Pre-filled URL the human can use to perform the manual check. */
+    verificationUrl: httpUrl().nullable(),
+    /** Human-readable description of what the manual check should establish. */
+    recommendedAction: z.string().min(1),
+    /** Citation locator, e.g. 'p. 42', 'pp. 33-35'. NEW in 0.2.0 (T25 populates). */
+    locator: z.string().nullable().optional(),
+});
+// ---------------------------------------------------------------------------
+// Top-level output
+//
+// schemaVersion: Validation accepts any `0.x.y` document; the runtime tool
+// emits the current `SCHEMA_VERSION`. Bumping rules: additive minor bump
+// remains backward-compatible (consumers continue to validate); a major bump
+// (1.x.y) breaks pinned consumers.
+// ---------------------------------------------------------------------------
+export const OutputSchema = z
+    .object({
+    schemaVersion: z.string().regex(/^0\.\d+\.\d+$/, 'Major version 0 expected'),
+    tool: ToolInfoSchema,
+    summary: SummarySchema,
+    entries: z.array(EntrySchema),
+    linkage: z.array(LinkageEntrySchema),
+    phraseFlags: z.array(PhraseFlagSchema),
+    worklist: z.array(WorklistItemSchema),
+})
+    .superRefine((o, ctx) => {
+    if (o.summary.verified > o.summary.totalEntries) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'verified'],
+            message: `verified (${o.summary.verified}) cannot exceed totalEntries (${o.summary.totalEntries})`,
+        });
+    }
+    if (o.summary.metadataMismatches > o.summary.totalEntries) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'metadataMismatches'],
+            message: `metadataMismatches (${o.summary.metadataMismatches}) cannot exceed totalEntries (${o.summary.totalEntries})`,
+        });
+    }
+    if (o.summary.unverifiable > o.summary.totalEntries) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'unverifiable'],
+            message: `unverifiable (${o.summary.unverifiable}) cannot exceed totalEntries (${o.summary.totalEntries})`,
+        });
+    }
+    if (o.summary.canonicalIssues > o.summary.totalEntries) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'canonicalIssues'],
+            message: `canonicalIssues (${o.summary.canonicalIssues}) cannot exceed totalEntries (${o.summary.totalEntries})`,
+        });
+    }
+    // 0.2.0 counters (required since T22).
+    if (o.summary.notFoundInDatabases > o.summary.totalEntries) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'notFoundInDatabases'],
+            message: `notFoundInDatabases (${o.summary.notFoundInDatabases}) cannot exceed totalEntries (${o.summary.totalEntries})`,
+        });
+    }
+    if (o.summary.malformedIdentifiers > o.summary.totalEntries) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'malformedIdentifiers'],
+            message: `malformedIdentifiers (${o.summary.malformedIdentifiers}) cannot exceed totalEntries (${o.summary.totalEntries})`,
+        });
+    }
+    // Existence-bucket reconciliation: every entry lands in exactly one of the
+    // four existence buckets, which must sum to totalEntries.
+    {
+        const bucketSum = o.summary.verified +
+            o.summary.metadataMismatches +
+            o.summary.notFoundInDatabases +
+            o.summary.unverifiable;
+        if (bucketSum !== o.summary.totalEntries) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['summary'],
+                message: `existence buckets (verified + metadataMismatches + notFoundInDatabases + unverifiable = ${bucketSum}) must sum to totalEntries (${o.summary.totalEntries})`,
+            });
+        }
+    }
+    if (o.summary.phraseFlags !== o.phraseFlags.filter(f => f.status === 'flagged').length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'phraseFlags'],
+            message: `summary.phraseFlags (${o.summary.phraseFlags}) must equal the count of flagged (not acknowledged) entries in phraseFlags array`,
+        });
+    }
+    if (o.summary.worklistItems !== o.worklist.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'worklistItems'],
+            message: `summary.worklistItems must equal worklist.length`,
+        });
+    }
+    if (o.summary.linkageFailures !== o.linkage.filter(l => l.status === 'unresolved').length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['summary', 'linkageFailures'],
+            message: `summary.linkageFailures must equal the count of unresolved linkage entries`,
+        });
+    }
+});
+//# sourceMappingURL=output.js.map

package/dist/schema/output.js.map

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

package/dist/suppression.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Suppression & source-type gating (T23).
+ *
+ * Makes the secure default (Q1 — `not-found-in-databases` and malformed
+ * identifiers gate `bibcheck check` unconditionally) *usable* by giving a
+ * reviewer two precise, auditable escape hatches that suppress a single
+ * finding without disabling the whole check:
+ *
+ *   1. Source-type gating rules (broad, declarative). A CSL `type` can opt out
+ *      of the not-found gate via `[source_types] <type> = { gate_not_found =
+ *      false }` — e.g. a pre-DOI manuscript for which no DOI was ever expected.
+ *   2. Per-entry allow-with-reason (specific). An entry's CSL `note` carries a
+ *      `bibcheck-allow: <finding-type> (reason: ...)` convention, mirroring the
+ *      phrases `<!-- bibcheck-allow: <key> -->` mechanism.
+ *
+ * This module is PURE: no I/O, no clock, no network. `check.ts` parses the CSL
+ * notes into `ParsedAllow[]` and calls `isGated` once per finding; only gated
+ * findings count toward the non-zero exit. Suppressed findings are NOT dropped
+ * from the output document — they remain in the entries/summary and are
+ * reported as `acknowledged` (informational), exactly like an acknowledged
+ * phrase.
+ */
+import type { Config } from './config.js';
+/**
+ * The gating finding kinds a suppression can target. Mirrors the gateable
+ * reasons in `check.ts` (`CHECK_NON_ZERO_REASON`):
+ *   - 'not-found'            → existence.status === 'not-found-in-databases'
+ *   - 'malformed-identifier' → summary.malformedIdentifiers (per entry)
+ *   - 'canonical-issue'      → canonical.status in the problem set
+ *   - 'metadata-mismatch'    → existence.status === 'metadata-mismatch'
+ */
+export declare const FINDING_TYPES: readonly ["not-found", "malformed-identifier", "canonical-issue", "metadata-mismatch"];
+export type FindingType = (typeof FINDING_TYPES)[number];
+/**
+ * A single parsed `bibcheck-allow` directive from an entry's CSL `note`.
+ *
+ * `reason` is the trimmed text inside `(reason: ...)`. An allow with an empty
+ * or missing reason is NOT a valid suppression — it is captured here with
+ * `reason: null` so the caller can emit a warning and decline to suppress
+ * (reason is MANDATORY; see `parseAllows` / `isGated`).
+ */
+export interface ParsedAllow {
+    citekey: string;
+    findingType: FindingType;
+    reason: string | null;
+    /** The raw directive text, for diagnostics. */
+    raw: string;
+}
+export interface ParseAllowsResult {
+    allows: ParsedAllow[];
+    /** Directives whose finding-type token is not a known FindingType. */
+    unknownTypes: {
+        citekey: string;
+        token: string;
+        raw: string;
+    }[];
+}
+/**
+ * Parse every `bibcheck-allow` directive out of one entry's CSL `note`.
+ *
+ * Pure. Returns both the valid allows (which may still have `reason: null` when
+ * the reason was omitted — the caller decides how to warn) and any directives
+ * whose finding-type token is unrecognised.
+ */
+export declare function parseAllows(citekey: string, note: string | undefined): ParseAllowsResult;
+/**
+ * Parse allows across a whole bibliography. Convenience wrapper used by
+ * `check.ts`; aggregates the per-entry results.
+ */
+export declare function parseAllowsForBibliography(entries: {
+    citekey: string;
+    note?: string | undefined;
+}[]): ParseAllowsResult;
+export interface SuppressionInput {
+    citekey: string;
+    findingType: FindingType;
+    cslType: string | undefined;
+    config: Config;
+    allows: ParsedAllow[];
+}
+export type GateReason = 'default' | 'source-type' | 'allow';
+export interface GateResult {
+    gated: boolean;
+    reason: GateReason;
+}
+/**
+ * Decide whether a single finding gates the build.
+ *
+ * Precedence (an explicit allow or a source-type exemption beats the default
+ * gate):
+ *
+ *   1. A valid per-entry allow (matching citekey + findingType, with a
+ *      NON-EMPTY reason) → NOT gated, `reason: 'allow'`. Reason is mandatory:
+ *      an allow with an empty/missing reason does NOT suppress (it is dropped
+ *      here and warned about by the caller), so it falls through to the gate.
+ *   2. For `not-found` only, a source-type exemption
+ *      (`[source_types] <cslType> = { gate_not_found = false }`) → NOT gated,
+ *      `reason: 'source-type'`. Source-type rules govern only the not-found
+ *      gate (no DOI was ever expected for the type); they do not exempt
+ *      malformed identifiers, canonical issues, or metadata mismatches.
+ *   3. Otherwise the secure default applies → gated, `reason: 'default'`.
+ *
+ * Pure: depends only on its inputs.
+ */
+export declare function isGated(input: SuppressionInput): GateResult;
+//# sourceMappingURL=suppression.d.ts.map

package/dist/suppression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppression.d.ts","sourceRoot":"","sources":["../src/suppression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAM1C;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,wFAKhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAUzD;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;CACb;AAiBD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,sEAAsE;IACtE,YAAY,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,CAuBxF;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAAE,GACxD,iBAAiB,CASnB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAqB3D"}