paperlint 7.2.0 → 9.0.0

package/dist/paper-record.js

@@ -0,0 +1,39 @@
+/**
+ * `paperRecord(dir)` — what every consumer of the build's record asks first: is there a record of
+ * this paper, and is it still about the files on disk? The answer is one of three states, and the
+ * rules that depend on the record are silent in two of them (docs/design/paper-sources.md §1):
+ *
+ *   none    no `_build/sources.json`, or one this paperlint cannot read — the paper was not built
+ *   stale   a file the build read has other bytes now (`changed` names them)
+ *   fresh   every file is as the build hashed it; the record is TeX's answer for this paper
+ *
+ * Reads through the `Files` port alone; the one paperlint-specific question — which files make a
+ * record stale — is `changesSince` (`src/domain/sources-record.ts`).
+ */
+import { resolve } from "node:path";
+import { callerPath } from "./caller-path.js";
+import { sha256Hex } from "./domain/sha256.js";
+import { changesSince, } from "./domain/sources-record.js";
+import { sourcesPath } from "./sources-record.js";
+/** The digest of the file at `path` in the paper directory now, or null when there is none. */
+const digestOf = (dir, files) => (path) => {
+    const b = files.readBytes(callerPath(resolve(dir, path)));
+    return b === null ? null : sha256Hex(b);
+};
+export function paperRecord(dir, deps) {
+    const raw = deps.files.readBytes(callerPath(sourcesPath(dir)));
+    if (raw === null)
+        return { kind: "none", unreadable: null };
+    const parsed = deps.codec.parse(new TextDecoder().decode(raw));
+    if (!parsed.ok)
+        return { kind: "none", unreadable: parsed.why };
+    const changed = changesSince(parsed.record, digestOf(dir, deps.files));
+    return changed.length === 0
+        ? { kind: "fresh", record: parsed.record }
+        : { kind: "stale", changed };
+}
+/** The files of `role` the record lists, as absolute paths, in the order TeX first read them. */
+export const recordedFiles = (dir, record, role) => record.inputs
+    .filter((i) => i.role === role)
+    .map((i) => callerPath(resolve(dir, i.path)));
+//# sourceMappingURL=paper-record.js.map

package/dist/paper-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paper-record.js","sourceRoot":"","sources":["../src/paper-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,SAAS,EAAe,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EACL,YAAY,GAIb,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAQlD,+FAA+F;AAC/F,MAAM,QAAQ,GACZ,CAAC,GAAW,EAAE,KAAY,EAAE,EAAE,CAC9B,CAAC,IAAY,EAAiB,EAAE;IAC9B,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1D,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC,CAAC;AAQJ,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,IAAoB;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC/D,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;IAChE,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC;QACzB,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAC1C,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACjC,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,GAAW,EACX,MAAqB,EACrB,IAAe,EACU,EAAE,CAC3B,MAAM,CAAC,MAAM;KACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;KAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}

package/dist/paper-sources.d.ts

@@ -0,0 +1,66 @@
+import { type BibText } from "./domain/paper-sources.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import { type Result } from "./domain/result.ts";
+import type { PaperRecord } from "./paper-record.ts";
+import { type RecordedDeps } from "./recorded-bibliography.ts";
+/** What a path a person gave comes to: where the paper is, and the texts to read. */
+export interface PathBibliography {
+    /** The `.bib`'s directory, the `.tex`'s, or the directory named. */
+    readonly paperDir: AbsolutePath;
+    readonly texts: readonly [BibText, ...BibText[]];
+}
+/** Why a path a person gave has no bibliography to read. One vocabulary for every caller. */
+export type BibliographyUnread = 
+/** A `.bib` or `.tex` named that is not there. */
+{
+    readonly kind: "missing";
+    readonly path: AbsolutePath;
+}
+/** A file that is neither a `.bib` nor a `.tex`. */
+ | {
+    readonly kind: "not-bib-or-tex";
+    readonly path: AbsolutePath;
+}
+/** Not a file, and no `paper.tex` in it. */
+ | {
+    readonly kind: "no-paper";
+    readonly path: AbsolutePath;
+}
+/** A paper with no current record of a build: what bibtex read is not known (`state` says why). */
+ | {
+    readonly kind: "not-built";
+    readonly dir: AbsolutePath;
+    readonly state: Exclude<PaperRecord, {
+        readonly kind: "fresh";
+    }>;
+}
+/** A paper whose last build's bibtex read no database, or whose databases are not on disk now. */
+ | {
+    readonly kind: "no-database";
+    readonly dir: AbsolutePath;
+    /** The databases bibtex opened: none when it ran none. */
+    readonly opened: readonly string[];
+}
+/**
+ * A paper whose last build's bibtex also opened databases the paper directory does not hold — found
+ * on its search path (BIBINPUTS). Reading the others alone would leave every entry of these out.
+ */
+ | {
+    readonly kind: "outside-paper";
+    readonly dir: AbsolutePath;
+    /** As bibtex names them. */
+    readonly unread: readonly [string, ...string[]];
+};
+/**
+ * THE answer to "a path a person gave → the bibliography to read", for every script that takes one: a
+ * `.bib` is read alone, as named; a `.tex`, or a directory holding `paper.tex`, is the bibliography the
+ * last build's bibtex opened for that paper (`_build/sources.json`) — never a guess by file name, and
+ * never read out of TeX source. A paper with no current record is refused: run `npx paperlint build`
+ * first, and so is one whose bibtex also opened a database outside the paper directory — a part of the
+ * bibliography is not given as the whole. Anything else is refused in the words `bibliographyUnreadWhy`
+ * gives.
+ */
+export declare function bibliographyAt(path: AbsolutePath, deps: RecordedDeps): Result<PathBibliography, BibliographyUnread>;
+/** One sentence: why `bibliographyAt` refused, naming the path and what to give instead. */
+export declare function bibliographyUnreadWhy(e: BibliographyUnread): string;
+//# sourceMappingURL=paper-sources.d.ts.map

package/dist/paper-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paper-sources.d.ts","sourceRoot":"","sources":["../src/paper-sources.ts"],"names":[],"mappings":"AASA,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,4BAA4B,CAAC;AAMpC,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;CAClD;AAED,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB;AAC5B,kDAAkD;AAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE;AAC3D,oDAAoD;GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE;AAClE,4CAA4C;GAC1C;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE;AAC5D,mGAAmG;GACjG;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAClE;AACH,kGAAkG;GAChG;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AACH;;;GAGG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;CACjD,CAAC;AAwBN;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,YAAY,GACjB,MAAM,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAgB9C;AAmBD,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAiBnE"}

package/dist/paper-sources.js

@@ -0,0 +1,92 @@
+/**
+ * `bibliographyAt(path)` — the one answer to "a path a person gave → the bibliography to read", for
+ * every script that takes one (`extract-ref-facts`, `bib-authors`, `verify-cites`). A `.bib` is read
+ * alone, as named; a `.tex`, or a directory holding `paper.tex`, is the bibliography the last build's
+ * bibtex opened for that paper — TeX's answer, from `_build/sources.json` (docs/design/paper-sources.md
+ * §1), never read out of TeX source.
+ */
+import { dirname, extname, join } from "node:path";
+import { callerPath } from "./caller-path.js";
+import { MAIN_FILE } from "./domain/paper-sources.js";
+import { err, ok } from "./domain/result.js";
+import { describeChanges } from "./domain/sources-record.js";
+import { authoredTexts, recordedBibliography, } from "./recorded-bibliography.js";
+const decoded = (b) => new TextDecoder().decode(b);
+/** The texts of the paper in `dir` the last build's bibtex read, or why there are none. */
+function ofPaper(dir, deps) {
+    const r = recordedBibliography(dir, deps);
+    if (r.kind === "unrecorded")
+        return err({ kind: "not-built", dir, state: r.record });
+    const [first, ...rest] = authoredTexts(dir, r, deps);
+    if (first === undefined)
+        return err({
+            kind: "no-database",
+            dir,
+            opened: r.record.bibtex.ran ? r.record.bibtex.databases : [],
+        });
+    // Some databases read and some not is no bibliography: a script would report on part of it as on all.
+    const [outside, ...more] = r.unread;
+    return outside === undefined
+        ? ok({ paperDir: dir, texts: [first, ...rest] })
+        : err({ kind: "outside-paper", dir, unread: [outside, ...more] });
+}
+/**
+ * THE answer to "a path a person gave → the bibliography to read", for every script that takes one: a
+ * `.bib` is read alone, as named; a `.tex`, or a directory holding `paper.tex`, is the bibliography the
+ * last build's bibtex opened for that paper (`_build/sources.json`) — never a guess by file name, and
+ * never read out of TeX source. A paper with no current record is refused: run `npx paperlint build`
+ * first, and so is one whose bibtex also opened a database outside the paper directory — a part of the
+ * bibliography is not given as the whole. Anything else is refused in the words `bibliographyUnreadWhy`
+ * gives.
+ */
+export function bibliographyAt(path, deps) {
+    const ext = extname(path).toLowerCase();
+    if (ext === ".bib" || ext === ".tex") {
+        const bytes = deps.files.readBytes(path);
+        if (bytes === null)
+            return err({ kind: "missing", path });
+        return ext === ".bib"
+            ? ok({
+                paperDir: callerPath(dirname(path)),
+                texts: [deps.bib.readFile(path, decoded(bytes))],
+            })
+            : ofPaper(callerPath(dirname(path)), deps);
+    }
+    if (deps.files.isFile(path))
+        return err({ kind: "not-bib-or-tex", path });
+    return deps.files.readBytes(callerPath(join(path, MAIN_FILE))) === null
+        ? err({ kind: "no-paper", path })
+        : ofPaper(path, deps);
+}
+const BUILD = "run `npx paperlint build` first";
+/** Why a paper has no current record, in words a person can act on. */
+function notBuiltWhy(dir, s) {
+    switch (s.kind) {
+        case "none":
+            return s.unreadable === null
+                ? `${dir} has not been built — ${BUILD}, which records the databases bibtex reads`
+                : `the last build's record of ${dir} cannot be used (${s.unreadable}) — ${BUILD}`;
+        case "stale":
+            return `${dir} changed since the last build (${describeChanges(s.changed)}) — ${BUILD}`;
+    }
+}
+/** One sentence: why `bibliographyAt` refused, naming the path and what to give instead. */
+export function bibliographyUnreadWhy(e) {
+    switch (e.kind) {
+        case "missing":
+            return `${e.path} does not exist — nowhere to take a bibliography from`;
+        case "not-bib-or-tex":
+            return `${e.path} is neither a .bib nor a .tex — name the paper's directory, its .tex, or a .bib`;
+        case "no-paper":
+            return `no paper.tex in ${e.path} — name the paper's .tex, or a .bib to read it alone`;
+        case "not-built":
+            return notBuiltWhy(e.dir, e.state);
+        case "no-database":
+            return e.opened.length === 0
+                ? `bibtex read no database in the last build of ${e.dir} — there is nothing to read`
+                : `bibtex opened ${e.opened.join(", ")} in the last build of ${e.dir}, and none of them is on disk now`;
+        case "outside-paper":
+            return `bibtex opened ${e.unread.join(", ")} in the last build of ${e.dir} from outside it (its search path, BIBINPUTS), and paperlint reads only the paper's own databases — copy it into ${e.dir}, or name each .bib to read it alone`;
+    }
+}
+//# sourceMappingURL=paper-sources.js.map

package/dist/paper-sources.js.map

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

package/dist/ports/bib-reader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * THE BIBTEX READER — the one way paperlint reads a `.bib` database. Every consumer (`recordedBibliography`,
+ * `bib/reachable-entry`, the build's reference check, `extract-ref-facts`, `bib-authors`) reads
+ * through it; the adapter is `src/adapters/bibtex/`.
+ *
+ * A database is read as bibtex reads it in its place among the paper's: `inherited` is the `@string`s
+ * the databases before it left in force (the previous one's `strings`), none for a database read alone.
+ */
+import type { BibStrings, BibText } from "../domain/paper-sources.ts";
+import type { AbsolutePath } from "../domain/paths.ts";
+import type { Span } from "../domain/tex-document.ts";
+export interface BibReader {
+    /** The database in `body` of `text`, the text of the file at `path`: a block in a `.tex`. */
+    readonly read: (path: AbsolutePath, text: string, body: Span, inherited?: BibStrings) => BibText;
+    /** A whole `.bib` file. */
+    readonly readFile: (path: AbsolutePath, text: string, inherited?: BibStrings) => BibText;
+}
+//# sourceMappingURL=bib-reader.d.ts.map

package/dist/ports/bib-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bib-reader.d.ts","sourceRoot":"","sources":["../../src/ports/bib-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AAEtD,MAAM,WAAW,SAAS;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,CACb,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,EACV,SAAS,CAAC,EAAE,UAAU,KACnB,OAAO,CAAC;IACb,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,CACjB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,UAAU,KACnB,OAAO,CAAC;CACd"}

package/dist/ports/bib-reader.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bib-reader.js.map

package/dist/ports/bib-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bib-reader.js","sourceRoot":"","sources":["../../src/ports/bib-reader.ts"],"names":[],"mappings":""}

package/dist/ports/check-references.d.ts

@@ -4,8 +4,10 @@
  * passes a function.
  */
 import type { LookupCache } from "../domain/lookup-cache.ts";
+import type { BibEntry } from "../domain/paper-sources.ts";
 /** What one bibliography entry came to. */
 export interface EntryVerdict {
+    /** The entry's key: a name for people, not its identity — two entries may share it. */
     readonly key: string;
     /**
      * Does the cited work exist, and does its title match? `false` only on a positive disproof (an
@@ -18,7 +20,9 @@ export interface EntryVerdict {
     /** Why, in one line, when either is not a plain pass. */
     readonly why?: string;
 }
-export type ReferencesCheck = {
+export type ReferencesCheck = 
+/** One verdict per entry given, in the order given: verdict `i` is about entry `i`. */
+{
     readonly kind: "checked";
     readonly entries: readonly EntryVerdict[];
 }
@@ -34,8 +38,9 @@ export interface ReferencesRun {
     readonly cache: LookupCache;
 }
 /**
- * The bibliography's text (BibTeX) and the paper's lookup cache → the verdicts, derived afresh from
- * cached and newly fetched answers. Never throws: a failure is `not-checked`.
+ * The bibliography's entries (as the bibtex reader read them) and the paper's lookup cache → the
+ * verdicts, one per entry in its order, derived afresh from cached and newly fetched answers. Never
+ * throws: a failure is `not-checked`.
  */
-export type CheckReferences = (bib: string, cache: LookupCache) => Promise<ReferencesRun>;
+export type CheckReferences = (entries: readonly BibEntry[], cache: LookupCache) => Promise<ReferencesRun>;
 //# sourceMappingURL=check-references.d.ts.map

package/dist/ports/check-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-references.d.ts","sourceRoot":"","sources":["../../src/ports/check-references.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,cAAc,CAAC;IACnD,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACjE,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE;AACzE,6EAA6E;GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,uGAAuG;IACvG,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,WAAW,KACf,OAAO,CAAC,aAAa,CAAC,CAAC"}
+{"version":3,"file":"check-references.d.ts","sourceRoot":"","sources":["../../src/ports/check-references.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAE3D,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,cAAc,CAAC;IACnD,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACjE,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,eAAe;AACzB,uFAAuF;AACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE;AACzE,6EAA6E;GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,uGAAuG;IACvG,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,KAAK,EAAE,WAAW,KACf,OAAO,CAAC,aAAa,CAAC,CAAC"}

package/dist/ports/latex.d.ts

@@ -4,6 +4,15 @@
  */
 import type { Include } from "../domain/paper-source.ts";
 import type { ClassLine, DocumentClass, Emphasis, LayoutOverride, Outline, Passage, Span, TextRun, TitledHeading } from "../domain/tex-document.ts";
+/** A `filecontents` block of a source: the file it writes, `[overwrite]`/`[force]` or not, where it is. */
+export interface Filecontents {
+    readonly writes: string;
+    readonly overwrite: boolean;
+    /** The whole environment, `\begin` to `\end`. */
+    readonly span: Span;
+    /** What it writes: from the line after `\begin{…}{…}` to `\end`. */
+    readonly body: Span;
+}
 export interface LatexReader {
     /** The source's `\documentclass`, as one of its states. */
     readonly documentClass: (src: string) => ClassLine;
@@ -44,5 +53,11 @@ export interface LatexReader {
     readonly withDocumentClass: (src: string, want: DocumentClass) => string;
     /** Every command that changes the page layout the class sets: margins, text block, line spacing. */
     readonly layoutOverrides: (src: string) => readonly LayoutOverride[];
+    /**
+     * Every live `filecontents` block of `src`, in source order, where each stands: a lookup of the text
+     * that wrote a `.bib`, never a decision of what TeX wrote (that is `_build/sources.json`). `jobname`
+     * is what `\jobname` names in a block's file name.
+     */
+    readonly filecontents: (src: string, jobname: string) => readonly Filecontents[];
 }
 //# sourceMappingURL=latex.d.ts.map

package/dist/ports/latex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"latex.d.ts","sourceRoot":"","sources":["../../src/ports/latex.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,QAAQ,EACR,cAAc,EACd,OAAO,EACP,OAAO,EACP,IAAI,EACJ,OAAO,EACP,aAAa,EACd,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IACnD,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,aAAa,EAAE,CAAC;IAC7D,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,OAAO,EAAE,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,OAAO,EAAE,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,QAAQ,EAAE,CAAC;IAC5D,wGAAwG;IACxG,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,OAAO,EAAE,CAAC;IACvD,uFAAuF;IACvF,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,GAAG,IAAI,CAAC;IAC1D;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,KAAK,MAAM,CAAC;IACzE,oGAAoG;IACpG,QAAQ,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,cAAc,EAAE,CAAC;CACtE"}
+{"version":3,"file":"latex.d.ts","sourceRoot":"","sources":["../../src/ports/latex.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,QAAQ,EACR,cAAc,EACd,OAAO,EACP,OAAO,EACP,IAAI,EACJ,OAAO,EACP,aAAa,EACd,MAAM,2BAA2B,CAAC;AAEnC,2GAA2G;AAC3G,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IACnD,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,aAAa,EAAE,CAAC;IAC7D,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,OAAO,EAAE,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,OAAO,EAAE,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,QAAQ,EAAE,CAAC;IAC5D,wGAAwG;IACxG,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,OAAO,EAAE,CAAC;IACvD,uFAAuF;IACvF,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,GAAG,IAAI,CAAC;IAC1D;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,KAAK,MAAM,CAAC;IACzE,oGAAoG;IACpG,QAAQ,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,cAAc,EAAE,CAAC;IACrE;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,CACrB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,KACZ,SAAS,YAAY,EAAE,CAAC;CAC9B"}

package/dist/ports/sources-codec.d.ts

@@ -0,0 +1,11 @@
+/**
+ * How a `sources.json` becomes a value: its text parsed once, where it enters, against the schema of
+ * `SourcesRecord` (`src/domain/sources-record.ts`). The one implementation is
+ * `src/adapters/sources-record/` (zod); `src/cli.ts` wires it.
+ */
+import type { ParsedRecord } from "../domain/sources-record.ts";
+export interface SourcesCodec {
+    /** A `sources.json`'s text: the record, or the one reason it is not one of this schema. */
+    readonly parse: (text: string) => ParsedRecord;
+}
+//# sourceMappingURL=sources-codec.d.ts.map

package/dist/ports/sources-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources-codec.d.ts","sourceRoot":"","sources":["../../src/ports/sources-codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,CAAC;CAChD"}

package/dist/ports/sources-codec.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sources-codec.js.map

package/dist/ports/sources-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources-codec.js","sourceRoot":"","sources":["../../src/ports/sources-codec.ts"],"names":[],"mappings":""}

package/dist/ports/tex-output.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What paperlint reads from the files TeX writes beside a paper, shaped by what the record of a build
+ * needs (`src/domain/sources-record.ts`) — not by the formats. The one implementation is
+ * `src/adapters/tex-output/`; `src/cli.ts` wires it.
+ *
+ * What the build's `.aux`, `.blg` and `.bbl` hold about the bibliography is read by `src/latex-log.ts`,
+ * which the build loop already reads them with.
+ */
+import type { BibtexError } from "../domain/sources-record.ts";
+import type { Fls } from "../domain/tex-run.ts";
+export interface TexOutput {
+    /** An `.fls`'s text. */
+    readonly fls: (text: string) => Fls;
+    /** The errors a bibtex `.blg` reports, in order; warnings are not errors. */
+    readonly blgErrors: (blg: string) => readonly BibtexError[];
+}
+//# sourceMappingURL=tex-output.d.ts.map

package/dist/ports/tex-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tex-output.d.ts","sourceRoot":"","sources":["../../src/ports/tex-output.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,WAAW,EAAE,CAAC;CAC7D"}

package/dist/ports/tex-output.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tex-output.js.map

package/dist/ports/tex-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tex-output.js","sourceRoot":"","sources":["../../src/ports/tex-output.ts"],"names":[],"mappings":""}

package/dist/recorded-bibliography.d.ts

@@ -0,0 +1,89 @@
+import { type BibEntry, type BibText } from "./domain/paper-sources.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import type { Span } from "./domain/tex-document.ts";
+import { type SourcesRecord } from "./domain/sources-record.ts";
+import { type PaperRecord, type RecordReadDeps } from "./paper-record.ts";
+import type { BibReader } from "./ports/bib-reader.ts";
+import type { LatexReader } from "./ports/latex.ts";
+/** What reading the recorded bibliography needs: the disk, the record's schema, the bibtex reader. */
+export interface RecordedReadDeps extends RecordReadDeps {
+    readonly bib: BibReader;
+}
+/** And what finding where a `.bib` TeX wrote stands needs besides: the reader of `filecontents` blocks. */
+export interface RecordedDeps extends RecordedReadDeps {
+    readonly latex: Pick<LatexReader, "filecontents">;
+}
+/** A database bibtex opened that is on disk now, as the bibtex reader reads it. */
+export interface ReadDatabase {
+    /** As bibtex names it: `refs.bib`, `bibs/x.bib`. */
+    readonly name: string;
+    /** A `.bib` TeX wrote (a `filecontents` block), not one the author keeps. */
+    readonly written: boolean;
+    readonly bib: BibText;
+}
+export type RecordedBibliography = {
+    readonly kind: "unrecorded";
+    readonly record: Exclude<PaperRecord, {
+        readonly kind: "fresh";
+    }>;
+} | {
+    readonly kind: "recorded";
+    readonly record: SourcesRecord;
+    /** In the order bibtex opened them, each once. */
+    readonly databases: readonly ReadDatabase[];
+    /**
+     * As bibtex names them: the databases it opened that the paper directory does not hold — found on
+     * its search path (BIBINPUTS). One that was there when the build recorded it and is gone now made
+     * the record stale instead: every database bibtex opened is hashed.
+     */
+    readonly unread: readonly string[];
+};
+/** The bibliography the last build of the paper in `dir` read. */
+export declare function recordedBibliography(dir: string, deps: RecordedReadDeps): RecordedBibliography;
+/** An entry of a database bibtex opened, and where it stands in that database. */
+export interface RecordedEntry {
+    readonly database: ReadDatabase;
+    readonly entry: BibEntry;
+    /** Its place among the database's entries: what pairs it with the same entry of a block. */
+    readonly index: number;
+}
+/** Every entry of the databases, in the order bibtex opened them and the entries stand. */
+export declare const entriesOfDatabases: (databases: readonly ReadDatabase[]) => readonly RecordedEntry[];
+/** Where a finding about an entry is reported in paper.tex. */
+export type EntryReport = {
+    readonly kind: "here";
+    readonly span: Span;
+}
+/** At the top of paper.tex; `where` names the entry (`refs.bib:12:1`). */
+ | {
+    readonly kind: "elsewhere";
+    readonly span: Span;
+    readonly where: string;
+};
+/** A text of the paper that may hold a block: a file of the record, the main file as the editor has it. */
+interface Holder {
+    readonly path: AbsolutePath;
+    readonly text: string;
+}
+/** The paper being linted: where it is, the record of its build, and its main file as the editor holds it. */
+export interface LintedPaper {
+    readonly dir: string;
+    readonly record: SourcesRecord;
+    readonly main: Holder;
+}
+/**
+ * Where each finding about `found` is reported, in the same order. The main file is read as the editor
+ * holds it; the record's other `.tex` files are read from disk.
+ */
+export declare function entryReports(paper: LintedPaper, found: readonly RecordedEntry[], deps: RecordedDeps): readonly EntryReport[];
+/**
+ * The text the author edits for each database bibtex opened, in the order it opened them: for a `.bib`
+ * TeX wrote, the block of `paper.tex` or of an included file that holds what bibtex read; for any other
+ * database, and for a written one no block holds, the file itself. What a script reads, so its entries
+ * stand where the author finds them.
+ */
+export declare function authoredTexts(dir: string, recorded: Extract<RecordedBibliography, {
+    readonly kind: "recorded";
+}>, deps: RecordedDeps): readonly BibText[];
+export {};
+//# sourceMappingURL=recorded-bibliography.d.ts.map

package/dist/recorded-bibliography.d.ts.map

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

package/dist/recorded-bibliography.js

@@ -0,0 +1,136 @@
+/**
+ * THE BIBLIOGRAPHY THE LAST BUILD READ — the entries of the databases bibtex opened, from the build's
+ * record (`_build/sources.json`, docs/design/paper-sources.md §1), through the one bibtex reader. Nothing
+ * here reads TeX source to decide which bibliography a paper has: TeX answered, the build wrote it
+ * down, and `paperRecord` says whether the paper is still the one it was written for.
+ *
+ *   unrecorded   no record, or a stale one — the rules that need it are silent (`paper/sources-fresh`
+ *                speaks), the scripts refuse ("run `npx paperlint build` first")
+ *   recorded     a current record, and the databases bibtex opened that are on disk now (none when
+ *                bibtex ran none), and the names of those that are not
+ *
+ * The databases are read in the order bibtex opened them, each with the `@string`s the ones before it
+ * left in force — bibtex keeps one table of them across its databases, so `\\bibliography{abbrev,refs}`
+ * expands an entry of `refs.bib` with a `@string` of `abbrev.bib`. A database that is not on disk adds
+ * none: its `@string`s are bibtex's alone.
+ *
+ * WHERE A FINDING ABOUT AN ENTRY GOES (`entryReports`). ESLint lints `paper.tex` only, so every finding
+ * is a place in it. An entry of a `.bib` TeX wrote (a `filecontents` block) is reported on its own line
+ * in the block of `paper.tex` whose body bibtex takes as the same database (`sameDatabase`) — a lookup
+ * of where the text stands, which decides nothing: the record said what TeX read. When no block of
+ * `paper.tex` is that database — the block is in an included file, or `paper.tex` was edited after the
+ * build — and for the entry of every other `.bib`, the finding is at the top of `paper.tex`, the file,
+ * line and column of the entry at the front of the message (`refs.bib:12:1:`).
+ */
+import { extname, posix, relative, resolve } from "node:path";
+import { callerPath } from "./caller-path.js";
+import { sameDatabase, } from "./domain/paper-sources.js";
+import { JOBNAME, spelledIn, } from "./domain/sources-record.js";
+import { paperRecord, } from "./paper-record.js";
+import { decoded, lineColumn } from "./tex-paper.js";
+/**
+ * The databases `names`, in this order, each read with the `@string`s the ones before it left in force,
+ * as bibtex reads them. One that is not on disk adds none.
+ */
+const readInSequence = (dir, names, deps) => names.reduce((acc, name) => {
+    const path = callerPath(resolve(dir, name));
+    const text = decoded(deps.files.readBytes(path));
+    const bib = text === null ? null : deps.bib.readFile(path, text, acc.inForce);
+    return {
+        inForce: bib?.strings ?? acc.inForce,
+        read: [...acc.read, { name, bib }],
+    };
+}, { inForce: {}, read: [] }).read;
+/** The bibliography the last build of the paper in `dir` read. */
+export function recordedBibliography(dir, deps) {
+    const r = paperRecord(dir, deps);
+    if (r.kind !== "fresh")
+        return { kind: "unrecorded", record: r };
+    const { bibtex, written } = r.record;
+    const opened = readInSequence(dir, (bibtex.ran ? bibtex.databases : []).filter((d, i, all) => all.findIndex((o) => resolve(dir, o) === resolve(dir, d)) === i), deps);
+    return {
+        kind: "recorded",
+        record: r.record,
+        databases: opened.flatMap(({ name, bib }) => bib === null ? [] : [{ name, written: written.includes(name), bib }]),
+        unread: opened.filter((d) => d.bib === null).map((d) => d.name),
+    };
+}
+/** Every entry of the databases, in the order bibtex opened them and the entries stand. */
+export const entriesOfDatabases = (databases) => databases.flatMap((database) => database.bib.entries.map((entry, index) => ({ database, entry, index })));
+/** The first line of an entry: `@misc{key,` — what a finding underlines. */
+const headOf = (bib, e) => {
+    const first = bib.text
+        .slice(e.span.start, e.span.end)
+        .split("\n", 1)
+        .join("");
+    return { start: e.span.start, end: e.span.start + first.length };
+};
+const TOP = { start: 0, end: 0 };
+/**
+ * The text of every `.tex` the record lists, in the order TeX first read them: from disk, except
+ * `override` (the main file as the editor holds it), which stands for its own path. A record is only
+ * current while every file it lists is on disk, so none is skipped for being absent.
+ */
+function holders(dir, record, override, deps) {
+    return record.inputs
+        .map((i) => callerPath(resolve(dir, i.path)))
+        .filter((p) => extname(p) === ".tex")
+        .map((path) => override !== null && override.path === path
+        ? override
+        : { path, text: decoded(deps.files.readBytes(path)) })
+        .filter((h) => h.text !== null);
+}
+/** The block, in some text of the paper, that holds what bibtex read of `db`. */
+const blockHolding = (db, texts, deps) => texts
+    .flatMap((holder) => deps.latex
+    .filecontents(holder.text, JOBNAME)
+    // The block that wrote this database: its file, then its text.
+    .filter((b) => spelledIn([posix.normalize(b.writes)], db.name) !== null)
+    // Read as bibtex read the database: with the `@string`s in force before it.
+    .map((b) => ({
+    holder,
+    bib: deps.bib.read(holder.path, holder.text, b.body, db.bib.inherited),
+})))
+    .find((b) => sameDatabase(b.bib, db.bib)) ?? null;
+/** Where a finding about `f` is reported, given the block of a text of the paper that holds its database (or none). */
+function reportOf(paper, block, f) {
+    const there = block?.bib.entries[f.index];
+    if (block === null || there?.key !== f.entry.key)
+        return {
+            kind: "elsewhere",
+            span: TOP,
+            where: `${f.database.name}:${lineColumn(f.database.bib.text, headOf(f.database.bib, f.entry).start)}`,
+        };
+    const span = headOf(block.bib, there);
+    return block.holder.path === paper.main.path
+        ? { kind: "here", span }
+        : {
+            kind: "elsewhere",
+            span: TOP,
+            where: `${relative(paper.dir, block.holder.path)}:${lineColumn(block.holder.text, span.start)}`,
+        };
+}
+/**
+ * Where each finding about `found` is reported, in the same order. The main file is read as the editor
+ * holds it; the record's other `.tex` files are read from disk.
+ */
+export function entryReports(paper, found, deps) {
+    const texts = holders(paper.dir, paper.record, paper.main, deps);
+    // Only the written databases that have a finding are searched for their block.
+    const blocks = new Map(found
+        .map((f) => f.database)
+        .filter((d, i, all) => d.written && all.indexOf(d) === i)
+        .map((d) => [d, blockHolding(d, texts, deps)]));
+    return found.map((f) => reportOf(paper, blocks.get(f.database) ?? null, f));
+}
+/**
+ * The text the author edits for each database bibtex opened, in the order it opened them: for a `.bib`
+ * TeX wrote, the block of `paper.tex` or of an included file that holds what bibtex read; for any other
+ * database, and for a written one no block holds, the file itself. What a script reads, so its entries
+ * stand where the author finds them.
+ */
+export function authoredTexts(dir, recorded, deps) {
+    const texts = holders(dir, recorded.record, null, deps);
+    return recorded.databases.map((d) => (d.written ? blockHolding(d, texts, deps)?.bib : undefined) ?? d.bib);
+}
+//# sourceMappingURL=recorded-bibliography.js.map