@de-otio/bibcheck 0.1.0

package/dist/suppression.js

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Finding-type vocabulary
+// ---------------------------------------------------------------------------
+/**
+ * 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 const FINDING_TYPES = [
+    'not-found',
+    'malformed-identifier',
+    'canonical-issue',
+    'metadata-mismatch',
+];
+function isFindingType(value) {
+    return FINDING_TYPES.includes(value);
+}
+// ---------------------------------------------------------------------------
+// Note parsing
+//
+// Convention (documented in docs/configuration.md):
+//   note: "bibcheck-allow: not-found (reason: 1680 pamphlet, Bodleian shelfmark X)"
+//
+// A single note may carry several directives (one per gateable finding). The
+// finding-type token is matched against the known vocabulary; an unknown token
+// is reported back so the caller can warn (a typo'd finding type must not
+// silently suppress nothing AND must not crash).
+// ---------------------------------------------------------------------------
+const ALLOW_DIRECTIVE_RE = /bibcheck-allow:\s*([\w-]+)\s*(?:\(\s*reason:\s*([^)]*)\)\s*)?/gi;
+/**
+ * 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 function parseAllows(citekey, note) {
+    const allows = [];
+    const unknownTypes = [];
+    if (note === undefined || note === '') {
+        return { allows, unknownTypes };
+    }
+    for (const m of note.matchAll(ALLOW_DIRECTIVE_RE)) {
+        const token = m[1];
+        if (token === undefined)
+            continue;
+        const raw = m[0].trim();
+        if (!isFindingType(token)) {
+            unknownTypes.push({ citekey, token, raw });
+            continue;
+        }
+        // m[2] is the reason capture (only present when `(reason: ...)` matched).
+        const reasonRaw = m[2];
+        const reason = reasonRaw !== undefined && reasonRaw.trim() !== '' ? reasonRaw.trim() : null;
+        allows.push({ citekey, findingType: token, reason, raw });
+    }
+    return { allows, unknownTypes };
+}
+/**
+ * Parse allows across a whole bibliography. Convenience wrapper used by
+ * `check.ts`; aggregates the per-entry results.
+ */
+export function parseAllowsForBibliography(entries) {
+    const allows = [];
+    const unknownTypes = [];
+    for (const e of entries) {
+        const r = parseAllows(e.citekey, e.note);
+        allows.push(...r.allows);
+        unknownTypes.push(...r.unknownTypes);
+    }
+    return { allows, unknownTypes };
+}
+/**
+ * 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 function isGated(input) {
+    const { citekey, findingType, cslType, config, allows } = input;
+    // 1. Per-entry allow with a valid (non-empty) reason wins.
+    const hasValidAllow = allows.some((a) => a.citekey === citekey && a.findingType === findingType && a.reason !== null);
+    if (hasValidAllow) {
+        return { gated: false, reason: 'allow' };
+    }
+    // 2. Source-type exemption — applies to the not-found gate only.
+    if (findingType === 'not-found' && cslType !== undefined) {
+        const rule = config.source_types[cslType];
+        if (rule?.gate_not_found === false) {
+            return { gated: false, reason: 'source-type' };
+        }
+    }
+    // 3. Secure default.
+    return { gated: true, reason: 'default' };
+}
+//# sourceMappingURL=suppression.js.map

package/dist/suppression.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Single source of the package version, read from the shipped package.json.
+ *
+ * `package.json` is always included in the npm tarball, and `createRequire`
+ * resolves it relative to this module (dist/version.js -> ../package.json),
+ * so this works both from the built package and from source under tests.
+ */
+export declare const VERSION: string;
+/** Polite-pool User-Agent base, e.g. `bibcheck/0.1.0`. */
+export declare const USER_AGENT_BASE: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,eAAO,MAAM,OAAO,EAAE,MAAoB,CAAC;AAE3C,0DAA0D;AAC1D,eAAO,MAAM,eAAe,QAAwB,CAAC"}

package/dist/version.js

@@ -0,0 +1,14 @@
+/**
+ * Single source of the package version, read from the shipped package.json.
+ *
+ * `package.json` is always included in the npm tarball, and `createRequire`
+ * resolves it relative to this module (dist/version.js -> ../package.json),
+ * so this works both from the built package and from source under tests.
+ */
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const VERSION = pkg.version;
+/** Polite-pool User-Agent base, e.g. `bibcheck/0.1.0`. */
+export const USER_AGENT_BASE = `bibcheck/${VERSION}`;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAE9D,MAAM,CAAC,MAAM,OAAO,GAAW,GAAG,CAAC,OAAO,CAAC;AAE3C,0DAA0D;AAC1D,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,OAAO,EAAE,CAAC"}

package/dist/worklist.d.ts

@@ -0,0 +1,32 @@
+/**
+ * bibcheck worklist subcommand.
+ *
+ * Generates the manual-triage worklist for Layer 2 / Layer 3 verification.
+ * Each citation in the prose is examined for four categories:
+ *   A. direct-quotation
+ *   B. paraphrase-with-page-ref
+ *   C. contested-source-type
+ *   D. non-canonical-edition
+ *
+ * Items are informational — they do NOT cause a non-zero exit code.
+ */
+import type { CslEntry } from './schema/csl.js';
+import type { WorklistItem } from './schema/output.js';
+import type { Config } from './config.js';
+export interface RunWorklistDeps {
+    config: Config;
+    cwd: string;
+    bibliography: CslEntry[];
+    readFile: (path: string) => Promise<string>;
+    signal: AbortSignal;
+}
+export interface RunWorklistResult {
+    worklist: WorklistItem[];
+}
+/**
+ * Returns the first author's family name (surname) from a CSL entry, or
+ * undefined if no author information is available.
+ */
+export declare function getFirstAuthorSurname(entry: CslEntry): string | undefined;
+export declare function runWorklist(deps: RunWorklistDeps): Promise<RunWorklistResult>;
+//# sourceMappingURL=worklist.d.ts.map

package/dist/worklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worklist.d.ts","sourceRoot":"","sources":["../src/worklist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAU1C,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,QAAQ,EAAE,CAAC;IACzB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAuBD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAczE;AAyKD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAsC5B"}

package/dist/worklist.js

@@ -0,0 +1,211 @@
+/**
+ * bibcheck worklist subcommand.
+ *
+ * Generates the manual-triage worklist for Layer 2 / Layer 3 verification.
+ * Each citation in the prose is examined for four categories:
+ *   A. direct-quotation
+ *   B. paraphrase-with-page-ref
+ *   C. contested-source-type
+ *   D. non-canonical-edition
+ *
+ * Items are informational — they do NOT cause a non-zero exit code.
+ */
+import { discoverDocs } from './markdown/glob.js';
+import { extractCitekeys } from './markdown/citekeys.js';
+import { extractBlockquotes, extractDirectQuotes } from './markdown/blocks.js';
+import { extractProseLines } from './markdown/prose.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Regex matching page references like (p. 42), (pp. 42-44), (p.42), etc. */
+const PAGE_REF_RE = /\(\s*pp?\.?\s*\d+(?:[-–]\d+)?\s*\)/;
+/** Snippet target length in characters. */
+const SNIPPET_TARGET = 80;
+/** Source types treated as contested when warn_load_bearing is not explicitly false. */
+const CONTESTED_TYPES = new Set(['webpage', 'blog', 'preprint', 'wikipedia']);
+/** URL hosts that are considered archive/canonical for verificationUrl passthrough. */
+const CANONICAL_URL_HOSTS_RE = /archive\.org|hathitrust\.org|oll\.libertyfund\.org|plato\.stanford\.edu/i;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns the first author's family name (surname) from a CSL entry, or
+ * undefined if no author information is available.
+ */
+export function getFirstAuthorSurname(entry) {
+    const authors = entry.author;
+    if (!Array.isArray(authors) || authors.length === 0)
+        return undefined;
+    const first = authors[0];
+    if (first === undefined)
+        return undefined;
+    if (typeof first.family === 'string' && first.family.trim() !== '') {
+        return first.family.trim();
+    }
+    // Fall back to literal name — take the last word as surname
+    if (typeof first.literal === 'string' && first.literal.trim() !== '') {
+        const parts = first.literal.trim().split(/\s+/);
+        return parts[parts.length - 1];
+    }
+    return undefined;
+}
+/**
+ * Build a ~80-char snippet of surrounding prose around the citation on the
+ * given line. Strips the leading markdown blockquote marker (`> `) if present.
+ */
+function buildSnippet(text, target = SNIPPET_TARGET) {
+    // Strip leading blockquote markers
+    const cleaned = text.replace(/^(?:>\s*)+/, '').trim();
+    if (cleaned.length <= target)
+        return cleaned;
+    // Trim to target length with ellipsis on the right
+    return cleaned.slice(0, target - 1) + '…';
+}
+/**
+ * Returns a verification URL for the entry, or a Google Books fallback search
+ * URL using `quoteText` as the search term.
+ */
+function buildVerificationUrl(entry, quoteText) {
+    const entryUrl = entry.url;
+    if (typeof entryUrl === 'string' && entryUrl.trim() !== '') {
+        if (CANONICAL_URL_HOSTS_RE.test(entryUrl)) {
+            return entryUrl;
+        }
+    }
+    // Build a Google Books search URL using the first ~10 chars of the quote text
+    const searchTerm = quoteText.slice(0, 60).trim();
+    if (searchTerm === '')
+        return null;
+    return `https://www.google.com/search?tbm=bks&q=${encodeURIComponent(searchTerm)}`;
+}
+// ---------------------------------------------------------------------------
+// Per-file processing
+// ---------------------------------------------------------------------------
+function processFile(filePath, content, bibMap, config) {
+    const items = [];
+    const citekeys = extractCitekeys(content, filePath);
+    if (citekeys.length === 0)
+        return items;
+    // Build lookup structures for blockquote ranges and direct-quote lines
+    const blockquotes = extractBlockquotes(content);
+    const directQuotes = extractDirectQuotes(content);
+    const directQuoteLines = new Set(directQuotes.map((dq) => dq.line));
+    // Build a map from line number → prose text for snippet extraction
+    const proseLines = extractProseLines(content);
+    const proseMap = new Map(proseLines.map((pl) => [pl.line, pl.text]));
+    for (const ref of citekeys) {
+        const entry = bibMap.get(ref.citekey);
+        if (entry === undefined) {
+            // Not in bibliography — linkage handles this, skip
+            continue;
+        }
+        const lineText = proseMap.get(ref.line) ?? '';
+        const snippet = buildSnippet(lineText);
+        // Determine if line is inside a blockquote
+        const inBlockquote = blockquotes.some((bq) => ref.line >= bq.startLine && ref.line <= bq.endLine);
+        // Determine if line has a direct typographic/quoted span
+        const inDirectQuote = directQuoteLines.has(ref.line);
+        let isDirectQuotation = false;
+        // --- A. direct-quotation ---
+        if (inBlockquote || inDirectQuote) {
+            isDirectQuotation = true;
+            // For the verification URL, try to use the first direct quote text on this
+            // line as the search term, otherwise use the snippet
+            const quoteText = directQuotes.find((dq) => dq.line === ref.line)?.text ?? snippet;
+            const verificationUrl = buildVerificationUrl(entry, quoteText);
+            items.push({
+                type: 'direct-quotation',
+                file: filePath,
+                line: ref.line,
+                citation: ref.citekey,
+                snippet,
+                verificationUrl,
+                recommendedAction: 'Verify quotation wording verbatim against the named edition.',
+            });
+        }
+        // --- B. paraphrase-with-page-ref ---
+        // Only emit if not already classified as a direct quotation. Fires when the
+        // prose line has a page reference OR the parsed citation carries a locator.
+        if (!isDirectQuotation && (ref.locator !== null || PAGE_REF_RE.test(lineText))) {
+            const pageMatch = PAGE_REF_RE.exec(lineText);
+            const locator = ref.locator ?? (pageMatch !== null ? pageMatch[0] : null);
+            const pageRef = locator ?? '';
+            const verificationUrl = buildVerificationUrl(entry, snippet);
+            items.push({
+                type: 'paraphrase-with-page-ref',
+                file: filePath,
+                line: ref.line,
+                citation: ref.citekey,
+                snippet,
+                verificationUrl,
+                locator,
+                recommendedAction: `Verify paraphrase against page ${pageRef} of the named edition.`,
+            });
+        }
+        // --- C. contested-source-type ---
+        const entryType = entry.type ?? '';
+        if (CONTESTED_TYPES.has(entryType) &&
+            config.source_types[entryType]?.warn_load_bearing !== false) {
+            items.push({
+                type: 'contested-source-type',
+                file: filePath,
+                line: ref.line,
+                citation: ref.citekey,
+                snippet,
+                verificationUrl: entry.url ?? null,
+                recommendedAction: `${entryType} citation; confirm the claim is supported and the source is appropriate.`,
+            });
+        }
+        // --- D. non-canonical-edition ---
+        const surname = getFirstAuthorSurname(entry);
+        if (surname !== undefined) {
+            const lowerSurname = surname.toLowerCase();
+            const canonicalEdition = config.edition_discipline[lowerSurname];
+            if (canonicalEdition !== undefined) {
+                const noteText = entry.note ?? '';
+                if (!noteText.toLowerCase().includes(canonicalEdition.toLowerCase())) {
+                    items.push({
+                        type: 'non-canonical-edition',
+                        file: filePath,
+                        line: ref.line,
+                        citation: ref.citekey,
+                        snippet,
+                        verificationUrl: null,
+                        recommendedAction: `Use the ${canonicalEdition} for this author.`,
+                    });
+                }
+            }
+        }
+    }
+    return items;
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+export async function runWorklist(deps) {
+    const { config, cwd, bibliography, readFile, signal } = deps;
+    if (signal.aborted) {
+        throw new Error('AbortSignal already aborted before runWorklist started');
+    }
+    // Build O(1) bibliography lookup map
+    const bibMap = new Map(bibliography.map((entry) => [entry.citekey, entry]));
+    // Discover markdown documents
+    const docs = await discoverDocs({
+        cwd,
+        include: config.docs.include,
+        exclude: config.docs.exclude,
+    });
+    const worklist = [];
+    for (const doc of docs) {
+        if (signal.aborted) {
+            throw new Error('Operation aborted');
+        }
+        const content = await readFile(doc.path);
+        const items = processFile(doc.relativePath, content, bibMap, config);
+        worklist.push(...items);
+    }
+    // Deterministic output order (file, line, type) — stable CI diffs.
+    worklist.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.type.localeCompare(b.type));
+    return { worklist };
+}
+//# sourceMappingURL=worklist.js.map

package/dist/worklist.js.map

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

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@de-otio/bibcheck",
+  "version": "0.1.0",
+  "description": "Humanities-aware citation verification for CSL-JSON bibliographies. Canonical-edition URL verification, Pandoc-citeproc-style linkage check, structured human-triage worklist generation, and an opt-in project-supplied phrase denylist.",
+  "keywords": [
+    "citations",
+    "bibliography",
+    "csl-json",
+    "verification",
+    "humanities",
+    "pandoc",
+    "research",
+    "academic",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Richard Myers <richard.myers@de-otio.org>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/de-otio/bibcheck.git"
+  },
+  "bugs": {
+    "url": "https://github.com/de-otio/bibcheck/issues"
+  },
+  "homepage": "https://github.com/de-otio/bibcheck#readme",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/output.d.ts",
+      "default": "./dist/schema/output.js"
+    }
+  },
+  "bin": {
+    "bibcheck": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/cli.js",
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "fastest-levenshtein": "^1.0.16",
+    "keyv": "^5.0.0",
+    "keyv-file": "^5.3.0",
+    "mdast-util-to-string": "^4.0.0",
+    "node-sarif-builder": "^4.0.0",
+    "p-queue": "^8.0.0",
+    "re2js": "^2.2.0",
+    "remark-parse": "^11.0.0",
+    "smol-toml": "^1.3.0",
+    "tinyglobby": "^0.2.0",
+    "unified": "^11.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "~20.14.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "ajv": "^8.17.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}