@de-otio/bibcheck 0.1.0

package/dist/doctor.js

@@ -0,0 +1,386 @@
+/**
+ * bibcheck doctor — diagnostic runner.
+ *
+ * Runs a series of environment and configuration checks and returns a
+ * structured result. Each check emits a DoctorCheck entry with a name,
+ * status, and human-readable message. The CLI (T15) is responsible for
+ * rendering the output; this module does no I/O beyond what is needed
+ * to perform the checks.
+ *
+ * SECURITY: API keys, polite-pool email addresses, and full request URLs
+ * (which might contain ?mailto= query params) MUST NOT appear in any
+ * DoctorCheck.message or .details value.
+ */
+import { API_BASE_DEFAULTS } from './config.js';
+import { resolve, join } from 'node:path';
+import { rm } from 'node:fs/promises';
+import { loadBibliography, BibliographyParseError } from './schema/csl.js';
+import { loadDenylist, PhraseLoaderError } from './phrases/load.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Minimum supported Node major version. */
+const MIN_NODE_MAJOR = 20;
+/** Remove a single trailing slash so connectivity URLs join cleanly. */
+function trimTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+/** Regex for basic hostname validation. */
+const HOSTNAME_RE = /^[a-z0-9.-]+\.[a-z]{2,}$/;
+/** Resolve the injectable fs interface, falling back to node:fs/promises. */
+async function resolveFs(fsDep) {
+    if (fsDep !== undefined)
+        return fsDep;
+    const nodeFs = await import('node:fs/promises');
+    return {
+        stat: nodeFs.stat.bind(nodeFs),
+        access: nodeFs.access.bind(nodeFs),
+        readdir: (p) => nodeFs.readdir(p),
+    };
+}
+/**
+ * Walk a directory recursively and sum total file sizes.
+ * Returns 0 if the directory does not exist or is not accessible.
+ */
+async function sumDirBytes(dirPath, fsModule) {
+    try {
+        await fsModule.access(dirPath);
+    }
+    catch {
+        return 0;
+    }
+    let total = 0;
+    const stack = [dirPath];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = await fsModule.readdir(current);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const entryPath = join(current, entry);
+            try {
+                const s = await fsModule.stat(entryPath);
+                if (s.isDirectory()) {
+                    stack.push(entryPath);
+                }
+                else {
+                    total += s.size;
+                }
+            }
+            catch {
+                // ignore unreadable entries
+            }
+        }
+    }
+    return total;
+}
+/** Perform a connectivity check against an API endpoint. */
+async function checkApiConnectivity(name, url, http, signal) {
+    if (signal.aborted) {
+        throw signal.reason;
+    }
+    try {
+        const response = await http.head(url, { signal, timeoutMs: 5000, followRedirects: false });
+        const status = response.status;
+        // Any response (including 4xx) means the server is reachable.
+        // 5xx means the server responded but errored — we still count it as reachable
+        // for the purposes of this connectivity check, but report the code.
+        if (status >= 500) {
+            return {
+                name,
+                status: 'fail',
+                message: `fail (HTTP ${status})`,
+            };
+        }
+        return {
+            name,
+            status: 'ok',
+            message: `ok (HTTP ${status})`,
+        };
+    }
+    catch (err) {
+        if (signal.aborted) {
+            throw signal.reason;
+        }
+        // Check if error carries an HTTP status
+        if (err instanceof Error) {
+            // HttpError carries a status property
+            const httpErr = err;
+            if (typeof httpErr.status === 'number') {
+                return {
+                    name,
+                    status: 'fail',
+                    message: `fail (HTTP ${httpErr.status})`,
+                };
+            }
+        }
+        return {
+            name,
+            status: 'fail',
+            message: 'fail (network)',
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Main runner
+// ---------------------------------------------------------------------------
+export async function runDoctor(deps) {
+    const { config, cwd, http, signal } = deps;
+    const checks = [];
+    // Throw immediately if aborted at entry.
+    if (signal.aborted) {
+        throw signal.reason;
+    }
+    // -------------------------------------------------------------------------
+    // Optional: clear cache before running checks
+    // -------------------------------------------------------------------------
+    if (deps.clearCache === true) {
+        const cacheDir = resolve(cwd, config.cache.dir);
+        try {
+            await rm(cacheDir, { recursive: true, force: true });
+            checks.push({
+                name: 'cache-cleared',
+                status: 'ok',
+                message: 'Cache directory cleared.',
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            checks.push({
+                name: 'cache-cleared',
+                status: 'fail',
+                message: `Failed to clear cache directory: ${msg}`,
+            });
+        }
+    }
+    // Resolve the injectable fs module or fall back to node:fs/promises.
+    const fsModule = await resolveFs(deps.fs);
+    // -------------------------------------------------------------------------
+    // Check 1: Node version
+    // -------------------------------------------------------------------------
+    {
+        const version = process.version; // e.g. "v20.0.0"
+        const match = /^v(\d+)/.exec(version);
+        const major = match !== null && match[1] !== undefined ? parseInt(match[1], 10) : 0;
+        if (major >= MIN_NODE_MAJOR) {
+            checks.push({
+                name: 'node-version',
+                status: 'ok',
+                message: `Node ${version} satisfies >=v${MIN_NODE_MAJOR}.`,
+            });
+        }
+        else {
+            checks.push({
+                name: 'node-version',
+                status: 'fail',
+                message: `Node ${version} is below the required v${MIN_NODE_MAJOR}.0.0.`,
+            });
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Check 2: Config validity (always ok — config was already validated by caller)
+    // -------------------------------------------------------------------------
+    {
+        checks.push({
+            name: 'config-valid',
+            status: 'ok',
+            message: 'Configuration is valid.',
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Check 3: Bibliography file exists
+    // -------------------------------------------------------------------------
+    {
+        const bibPath = resolve(cwd, config.bibliography.file);
+        try {
+            await fsModule.access(bibPath);
+            checks.push({
+                name: 'bibliography-exists',
+                status: 'ok',
+                message: `Bibliography file found: ${config.bibliography.file}`,
+            });
+        }
+        catch {
+            checks.push({
+                name: 'bibliography-exists',
+                status: 'fail',
+                message: `Bibliography file not found: ${config.bibliography.file}`,
+            });
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Check 4: Bibliography parses as valid CSL-JSON
+    // -------------------------------------------------------------------------
+    {
+        try {
+            const entries = await loadBibliography({ path: config.bibliography.file, cwd });
+            checks.push({
+                name: 'bibliography-parses',
+                status: 'ok',
+                message: `Bibliography parsed successfully (${entries.length} entries).`,
+                details: { entryCount: entries.length },
+            });
+        }
+        catch (err) {
+            const msg = err instanceof BibliographyParseError ? err.message : String(err);
+            checks.push({
+                name: 'bibliography-parses',
+                status: 'fail',
+                message: `Bibliography parse error: ${msg}`,
+            });
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Check 5: Phrase denylist (if configured)
+    // -------------------------------------------------------------------------
+    if (config.phrases.file !== null) {
+        try {
+            const patterns = await loadDenylist({ path: config.phrases.file, cwd });
+            checks.push({
+                name: 'phrase-denylist',
+                status: 'ok',
+                message: `Phrase denylist loaded (${patterns.length} patterns).`,
+                details: { patternCount: patterns.length },
+            });
+        }
+        catch (err) {
+            if (err instanceof PhraseLoaderError) {
+                // Distinguish missing-file (warn) from parse/compile errors (fail).
+                const msg = err.message;
+                if (msg.includes('not found')) {
+                    checks.push({
+                        name: 'phrase-denylist',
+                        status: 'warn',
+                        message: `Phrase denylist file configured but not found: ${config.phrases.file}`,
+                    });
+                }
+                else {
+                    checks.push({
+                        name: 'phrase-denylist',
+                        status: 'fail',
+                        message: `Phrase denylist load error: ${msg}`,
+                    });
+                }
+            }
+            else {
+                checks.push({
+                    name: 'phrase-denylist',
+                    status: 'fail',
+                    message: `Phrase denylist load error: ${String(err)}`,
+                });
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Check 6: Cache directory writability
+    // -------------------------------------------------------------------------
+    {
+        const cacheDir = resolve(cwd, config.cache.dir);
+        try {
+            await fsModule.access(cacheDir);
+            // Directory exists — check if we can read it (proxy for write access in injectable fs)
+            checks.push({
+                name: 'cache-writable',
+                status: 'ok',
+                message: `Cache directory is accessible: ${config.cache.dir}`,
+                details: { cacheDir },
+            });
+        }
+        catch {
+            // Directory does not exist yet — that is fine; bibcheck creates it on first write.
+            checks.push({
+                name: 'cache-writable',
+                status: 'warn',
+                message: `Cache directory does not exist yet (will be created on first use): ${config.cache.dir}`,
+                details: { cacheDir },
+            });
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Check 7: Cache size
+    // -------------------------------------------------------------------------
+    {
+        const cacheDir = resolve(cwd, config.cache.dir);
+        const totalBytes = await sumDirBytes(cacheDir, fsModule);
+        const totalMb = totalBytes / (1024 * 1024);
+        const maxMb = config.cache.max_size_mb;
+        let cacheStatus = 'ok';
+        let cacheMsg;
+        if (maxMb !== null && totalMb > maxMb * 0.8) {
+            cacheStatus = 'warn';
+            cacheMsg = `Cache is using ${totalMb.toFixed(1)} MB of ${maxMb} MB limit (>80%).`;
+        }
+        else if (maxMb !== null) {
+            cacheMsg = `Cache is using ${totalMb.toFixed(1)} MB of ${maxMb} MB limit.`;
+        }
+        else {
+            cacheMsg = `Cache is using ${totalMb.toFixed(1)} MB (no limit configured).`;
+        }
+        checks.push({
+            name: 'cache-size',
+            status: cacheStatus,
+            message: cacheMsg,
+            details: { totalBytes, totalMb: parseFloat(totalMb.toFixed(3)) },
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Check 8: CrossRef API connectivity
+    // -------------------------------------------------------------------------
+    if (signal.aborted)
+        throw signal.reason;
+    checks.push(await checkApiConnectivity('crossref-connectivity', `${trimTrailingSlash(config.apis.crossref_base ?? API_BASE_DEFAULTS.crossref)}/works/10.1000/xyz123`, http, signal));
+    // -------------------------------------------------------------------------
+    // Check 9: OpenAlex API connectivity
+    // -------------------------------------------------------------------------
+    if (signal.aborted)
+        throw signal.reason;
+    checks.push(await checkApiConnectivity('openalex-connectivity', `${trimTrailingSlash(config.apis.openalex_base ?? API_BASE_DEFAULTS.openalex)}/`, http, signal));
+    // -------------------------------------------------------------------------
+    // Check 10: OpenLibrary API connectivity
+    // -------------------------------------------------------------------------
+    if (signal.aborted)
+        throw signal.reason;
+    checks.push(await checkApiConnectivity('openlibrary-connectivity', `${trimTrailingSlash(config.apis.openlibrary_base ?? API_BASE_DEFAULTS.openlibrary)}/api/books`, http, signal));
+    // -------------------------------------------------------------------------
+    // Check 11: Trusted host whitelist sanity
+    // -------------------------------------------------------------------------
+    {
+        const hosts = config.trusted_hosts.hosts;
+        if (hosts.length === 0) {
+            checks.push({
+                name: 'trusted-hosts',
+                status: 'warn',
+                message: 'trusted_hosts.hosts is empty — all canonical URL checks will be skipped.',
+            });
+        }
+        else {
+            const invalid = hosts.filter((h) => !HOSTNAME_RE.test(h));
+            if (invalid.length > 0) {
+                checks.push({
+                    name: 'trusted-hosts',
+                    status: 'warn',
+                    message: `Some trusted hosts do not look like valid hostnames: ${invalid.join(', ')}`,
+                    details: { invalidHosts: invalid },
+                });
+            }
+            else {
+                checks.push({
+                    name: 'trusted-hosts',
+                    status: 'ok',
+                    message: `Trusted host whitelist is valid (${hosts.length} hosts).`,
+                    details: { hostCount: hosts.length },
+                });
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Aggregate result
+    // -------------------------------------------------------------------------
+    const ok = checks.every((c) => c.status !== 'fail');
+    return { checks, ok };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/existence.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Existence subcommand — commodity convenience layer.
+ *
+ * For each CSL-JSON bibliography entry, performs DOI/ISBN/title-search
+ * lookups against CrossRef, OpenAlex, and OpenLibrary, then assigns an
+ * ExistenceStatus based on the best result across all tried sources. Each
+ * layer also carries the Q2 evidence vocabulary (`evidence` / `checkedFor` /
+ * `notCheckedFor`) and a sanitized `error` string when a source crashed.
+ *
+ * Title metadata-match rule (H3): a hand-rolled token-set ratio over the
+ * normalised title tokens, so subtitle presence ("Liberty" vs "Liberty: A
+ * Study") and word reordering do not cause a false metadata-mismatch.
+ * Normalised Levenshtein is kept only as a tiebreaker for near-identical
+ * titles where the token sets diverge. Ratio ≥ 0.85 → match.
+ *
+ * First-author match:
+ *   Case-insensitive substring of first-author surname in any metadata
+ *   author string.
+ *
+ * Identifier short-circuit (T21/T22): a malformed or bad-checksum DOI/ISBN is
+ * a strong, cheap fabrication signal and cannot be looked up; callers pass
+ * `identifierInvalid` so the network call is skipped and the entry is recorded
+ * as `unverifiable` with a note (it is already gating via
+ * `summary.malformedIdentifiers`).
+ *
+ * WorldCat (OCLC Classify) was removed in 0.2.0 — the endpoint was
+ * decommissioned in 2019 (see tmp/design-review/worldcat.md). ISBN existence
+ * is covered by OpenLibrary.
+ */
+import type { CslEntry } from './schema/csl.js';
+import type { ExistenceLayer } from './schema/output.js';
+import type { CrossRefClient } from './databases/crossref.js';
+import type { OpenAlexClient } from './databases/openalex.js';
+import type { OpenLibraryClient } from './databases/openlibrary.js';
+export interface RunExistenceDeps {
+    bibliography: CslEntry[];
+    clients: {
+        crossref: CrossRefClient;
+        openalex: OpenAlexClient;
+        openlibrary: OpenLibraryClient;
+    };
+    /**
+     * Citekeys whose local identifier validation (T21) failed
+     * (malformed/bad-checksum DOI or ISBN). These SKIP the network existence
+     * call and are recorded as `unverifiable` — a malformed identifier cannot
+     * be looked up and is already a gating finding via
+     * `summary.malformedIdentifiers`.
+     */
+    identifierInvalid?: ReadonlySet<string>;
+    signal: AbortSignal;
+}
+export interface RunExistenceResult {
+    entries: Array<Pick<{
+        citekey: string;
+        existence: ExistenceLayer;
+    }, 'citekey' | 'existence'>>;
+}
+export declare function getFirstAuthorSurname(entry: CslEntry): string | undefined;
+export declare function getAllAuthorNames(entry: CslEntry): string[];
+/**
+ * Returns true if the two title strings are close enough to be the same work.
+ *
+ * Primary metric is the token-set ratio (≥ 0.85), which is robust to subtitle
+ * presence and word reordering. As a tiebreaker (e.g. single-token titles with
+ * a small typo, where the token sets are disjoint but the strings are close),
+ * the normalised Levenshtein ratio (≥ 0.85) is consulted.
+ */
+export declare function titlesMatch(a: string, b: string): boolean;
+export declare function runExistence(deps: RunExistenceDeps): Promise<RunExistenceResult>;
+//# sourceMappingURL=existence.d.ts.map

package/dist/existence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"existence.d.ts","sourceRoot":"","sources":["../src/existence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAIV,cAAc,EAEf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAOpE,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,QAAQ,EAAE,CAAC;IACzB,OAAO,EAAE;QACP,QAAQ,EAAE,cAAc,CAAC;QACzB,QAAQ,EAAE,cAAc,CAAC;QACzB,WAAW,EAAE,iBAAiB,CAAC;KAChC,CAAC;IACF;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,cAAc,CAAA;KAAE,EAAE,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC;CAC/F;AAMD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAIzE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,EAAE,CAE3D;AA0CD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAgBzD;AA2OD,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiBtF"}