paperlint 2.0.0

package/dist/latex-log.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Reading what pdflatex and bibtex leave behind — PURE functions, text in, data out.
+ *
+ * `latex-loop.ts` decides what to run next; this module turns the files a pass wrote into the
+ * facts that decision needs. Nothing here touches the disk: the caller reads the file and hands
+ * over its text, so every function below is testable on a string.
+ *
+ * 🔴 WHY LINE MATCHING IS LEGITIMATE HERE. A `.log` has no grammar a parser could give us: it is
+ * the terminal transcript of a TeX run. What it does have is a small set of DOCUMENTED marker
+ * lines that LaTeX and its packages print word for word, and that every build tool (latexmk,
+ * arara, texlab) keys on. Those markers are the interface. The `.aux` is similar: TeX writes one
+ * command per line, and the three we read (`\citation`, `\bibdata`, `\bibstyle`) always start a
+ * line. Neither file is prose-with-structure that a parser would read better.
+ *
+ * 🔴 THE 79-COLUMN WRAP. TeX breaks every line it writes to the log at `max_print_line` (79 in
+ * TeX Live), counting BYTES. A marker that happens to straddle the break — "Rerun to get
+ * cross-references right." is the usual victim, since it closes a long warning — is not on any
+ * one physical line. `unwrapLog` rejoins a line of exactly 79 bytes with the next one. The caller
+ * must therefore read the log as `latin1`, so one character is one byte and `length` counts what
+ * TeX counted.
+ */
+/** TeX Live's `max_print_line`. A physical log line of exactly this many bytes was broken by TeX. */
+export declare const MAX_PRINT_LINE = 79;
+/**
+ * Log lines that ask for another pass, or report on references. Each is a documented message,
+ * not a guess about wording:
+ *   - `rerun-requested`   — any "Rerun to get …" (LaTeX core, natbib, hyperref's outlines, …)
+ *   - `labels-changed`    — "LaTeX Warning: Label(s) may have changed."
+ *   - `rerunfilecheck`    — "Package rerunfilecheck Warning: File `…' has changed."
+ *   - `undefined-references` / `undefined-citations` — the end-of-run summaries. These do NOT
+ *     request a rerun by themselves: on a converged document they mean a genuinely undefined key.
+ */
+export type LogMarker = "rerun-requested" | "labels-changed" | "rerunfilecheck" | "undefined-references" | "undefined-citations";
+/** Markers that mean "the output of this pass is not final yet". */
+export declare const RERUN_MARKERS: readonly LogMarker[];
+/**
+ * Rejoin the lines TeX broke at column 79. A line of exactly 79 bytes continues on the next one.
+ *
+ * ⚠️ A line that is 79 bytes long BY ITSELF gets joined too — TeX gives no way to tell the two
+ * apart. The cost is one false join, which can only merge two lines, never split a marker; for
+ * the substring checks below that is harmless.
+ */
+export declare function unwrapLog(text: string): string[];
+/** Which markers a log carries, in a fixed order, each at most once. */
+export declare function logMarkers(lines: readonly string[]): LogMarker[];
+/**
+ * Is this the line a TeX error starts on? Two spellings exist and `-file-line-error` produces
+ * both: most errors become `./paper.tex:4: Undefined control sequence.`, while some keep the
+ * classic `! LaTeX Error: File `x.sty' not found.` (measured on TeX Live 2023). The path part must
+ * contain a dot or a slash, so an ordinary warning ending in a number and a colon cannot pass.
+ */
+export declare function isErrorLine(line: string): boolean;
+/** The `l.NNN …` line TeX prints to show where in the source it stopped. */
+export declare const isContextLine: (line: string) => boolean;
+/** At most this many lines are quoted from a log: enough for the error and its context. */
+export declare const MAX_EXCERPT = 12;
+/**
+ * The first error of a pass and the source context after it: the error line, the lines up to
+ * and including `l.NNN`, and the one line after it (TeX splits the source line at the point of
+ * the error, so the rest of it sits on the next line). Blank lines are dropped. Empty when the
+ * log carries no error line — the caller then says so rather than printing nothing.
+ */
+export declare function errorExcerpt(lines: readonly string[]): string[];
+/** What bibtex said beyond its banner — the explanation of a failed run. */
+export declare function bibtexExcerpt(stdout: string): string[];
+/** What the `.aux` tells bibtex: the cited keys, the databases and the style. */
+export interface AuxBib {
+    /** Sorted, unique. `*` (`\nocite{*}`) is a key like any other. */
+    readonly citations: readonly string[];
+    /** The names in `\bibdata{…}`, as written — without `.bib`. */
+    readonly databases: readonly string[];
+    readonly style: string | null;
+}
+/**
+ * Read `\citation`, `\bibdata` and `\bibstyle` out of an `.aux`, following `\@input{sub.aux}` —
+ * `\include` writes each chapter's citations into its own aux file, and bibtex follows them too.
+ * `readInput` returns the text of a nested aux, or null when it does not exist.
+ */
+export declare function auxBib(text: string, readInput?: (name: string) => string | null, seen?: Set<string>): AuxBib;
+//# sourceMappingURL=latex-log.d.ts.map

package/dist/latex-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latex-log.d.ts","sourceRoot":"","sources":["../src/latex-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,qGAAqG;AACrG,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,sBAAsB,GACtB,qBAAqB,CAAC;AAE1B,oEAAoE;AACpE,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAI7C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAchD;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,CAqBhE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIjD;AAED,4EAA4E;AAC5E,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,OAA+B,CAAC;AAE7E,2FAA2F;AAC3F,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAe/D;AAWD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAOtD;AAED,iFAAiF;AACjF,MAAM,WAAW,MAAM;IACrB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAqDD;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAiB,EACvD,IAAI,GAAE,GAAG,CAAC,MAAM,CAAa,GAC5B,MAAM,CASR"}

package/dist/latex-log.js

@@ -0,0 +1,187 @@
+/**
+ * Reading what pdflatex and bibtex leave behind — PURE functions, text in, data out.
+ *
+ * `latex-loop.ts` decides what to run next; this module turns the files a pass wrote into the
+ * facts that decision needs. Nothing here touches the disk: the caller reads the file and hands
+ * over its text, so every function below is testable on a string.
+ *
+ * 🔴 WHY LINE MATCHING IS LEGITIMATE HERE. A `.log` has no grammar a parser could give us: it is
+ * the terminal transcript of a TeX run. What it does have is a small set of DOCUMENTED marker
+ * lines that LaTeX and its packages print word for word, and that every build tool (latexmk,
+ * arara, texlab) keys on. Those markers are the interface. The `.aux` is similar: TeX writes one
+ * command per line, and the three we read (`\citation`, `\bibdata`, `\bibstyle`) always start a
+ * line. Neither file is prose-with-structure that a parser would read better.
+ *
+ * 🔴 THE 79-COLUMN WRAP. TeX breaks every line it writes to the log at `max_print_line` (79 in
+ * TeX Live), counting BYTES. A marker that happens to straddle the break — "Rerun to get
+ * cross-references right." is the usual victim, since it closes a long warning — is not on any
+ * one physical line. `unwrapLog` rejoins a line of exactly 79 bytes with the next one. The caller
+ * must therefore read the log as `latin1`, so one character is one byte and `length` counts what
+ * TeX counted.
+ */
+/** TeX Live's `max_print_line`. A physical log line of exactly this many bytes was broken by TeX. */
+export const MAX_PRINT_LINE = 79;
+/** Markers that mean "the output of this pass is not final yet". */
+export const RERUN_MARKERS = [
+    "rerun-requested",
+    "labels-changed",
+    "rerunfilecheck",
+];
+/**
+ * Rejoin the lines TeX broke at column 79. A line of exactly 79 bytes continues on the next one.
+ *
+ * ⚠️ A line that is 79 bytes long BY ITSELF gets joined too — TeX gives no way to tell the two
+ * apart. The cost is one false join, which can only merge two lines, never split a marker; for
+ * the substring checks below that is harmless.
+ */
+export function unwrapLog(text) {
+    const physical = text.split(/\r?\n/);
+    const out = [];
+    let carry = "";
+    for (const line of physical) {
+        if (line.length === MAX_PRINT_LINE) {
+            carry += line;
+            continue;
+        }
+        out.push(carry + line);
+        carry = "";
+    }
+    if (carry)
+        out.push(carry);
+    return out;
+}
+/** Which markers a log carries, in a fixed order, each at most once. */
+export function logMarkers(lines) {
+    const found = new Set();
+    for (const line of lines) {
+        if (line.includes("Rerun to get"))
+            found.add("rerun-requested");
+        if (line.startsWith("LaTeX Warning: Label(s) may have changed"))
+            found.add("labels-changed");
+        if (line.startsWith("Package rerunfilecheck Warning:"))
+            found.add("rerunfilecheck");
+        if (line.includes("There were undefined references"))
+            found.add("undefined-references");
+        if (line.includes("There were undefined citations"))
+            found.add("undefined-citations");
+    }
+    const order = [
+        "rerun-requested",
+        "labels-changed",
+        "rerunfilecheck",
+        "undefined-references",
+        "undefined-citations",
+    ];
+    return order.filter((m) => found.has(m));
+}
+/**
+ * Is this the line a TeX error starts on? Two spellings exist and `-file-line-error` produces
+ * both: most errors become `./paper.tex:4: Undefined control sequence.`, while some keep the
+ * classic `! LaTeX Error: File `x.sty' not found.` (measured on TeX Live 2023). The path part must
+ * contain a dot or a slash, so an ordinary warning ending in a number and a colon cannot pass.
+ */
+export function isErrorLine(line) {
+    if (line.startsWith("!"))
+        return true;
+    const m = /^([^\s:]+):(\d+): /.exec(line);
+    return m !== null && /[./]/.test(m[1] ?? "");
+}
+/** The `l.NNN …` line TeX prints to show where in the source it stopped. */
+export const isContextLine = (line) => /^l\.\d+/.test(line);
+/** At most this many lines are quoted from a log: enough for the error and its context. */
+export const MAX_EXCERPT = 12;
+/**
+ * The first error of a pass and the source context after it: the error line, the lines up to
+ * and including `l.NNN`, and the one line after it (TeX splits the source line at the point of
+ * the error, so the rest of it sits on the next line). Blank lines are dropped. Empty when the
+ * log carries no error line — the caller then says so rather than printing nothing.
+ */
+export function errorExcerpt(lines) {
+    const start = lines.findIndex(isErrorLine);
+    if (start < 0)
+        return [];
+    const out = [];
+    for (let i = start; i < lines.length && out.length < MAX_EXCERPT; i++) {
+        const line = lines[i] ?? "";
+        if (line.trim() === "")
+            continue;
+        out.push(line);
+        if (isContextLine(line)) {
+            const next = lines[i + 1];
+            if (next !== undefined && next.trim() !== "")
+                out.push(next);
+            break;
+        }
+    }
+    return out;
+}
+/** The lines bibtex prints before it has anything to say; never an explanation of a failure. */
+const BIBTEX_PREAMBLE = [
+    "This is BibTeX",
+    "Capacity:",
+    "The top-level auxiliary file:",
+    "The style file:",
+    "Database file #",
+];
+/** What bibtex said beyond its banner — the explanation of a failed run. */
+export function bibtexExcerpt(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .filter((l) => l.trim() !== "" && !BIBTEX_PREAMBLE.some((p) => l.startsWith(p)))
+        .slice(0, MAX_EXCERPT);
+}
+/** The argument of `\name{…}` when a line is exactly that command, else null. */
+function argOf(line, name) {
+    const open = `\\${name}{`;
+    if (!line.startsWith(open) || !line.endsWith("}"))
+        return null;
+    return line.slice(open.length, -1);
+}
+const list = (arg) => arg
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+/**
+ * Fold one aux line into the walk. Order is load-bearing: a nested aux's databases land where
+ * its `\@input` stands, and its style counts only while no `\bibstyle` has been read yet — a
+ * later one in the parent still overrides it.
+ */
+function readAuxLine(line, acc, walk) {
+    for (const k of list(argOf(line, "citation") ?? ""))
+        acc.citations.add(k);
+    acc.databases.push(...list(argOf(line, "bibdata") ?? ""));
+    const st = argOf(line, "bibstyle");
+    if (st !== null)
+        acc.style = st.trim();
+    followInput(argOf(line, "@input"), acc, walk);
+}
+/** Merge an `\@input` aux into the walk — once per name, and only when it exists. */
+function followInput(input, acc, walk) {
+    if (input === null || walk.seen.has(input))
+        return;
+    walk.seen.add(input);
+    const nested = walk.readInput(input);
+    if (nested === null)
+        return;
+    const sub = auxBib(nested, walk.readInput, walk.seen);
+    for (const k of sub.citations)
+        acc.citations.add(k);
+    acc.databases.push(...sub.databases);
+    acc.style ??= sub.style;
+}
+/**
+ * Read `\citation`, `\bibdata` and `\bibstyle` out of an `.aux`, following `\@input{sub.aux}` —
+ * `\include` writes each chapter's citations into its own aux file, and bibtex follows them too.
+ * `readInput` returns the text of a nested aux, or null when it does not exist.
+ */
+export function auxBib(text, readInput = () => null, seen = new Set()) {
+    const acc = { citations: new Set(), databases: [], style: null };
+    for (const raw of text.split(/\r?\n/))
+        readAuxLine(raw.trim(), acc, { readInput, seen });
+    return {
+        citations: [...acc.citations].sort(),
+        databases: acc.databases,
+        style: acc.style,
+    };
+}
+//# sourceMappingURL=latex-log.js.map

package/dist/latex-log.js.map

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

package/dist/latex-loop.d.ts

@@ -0,0 +1,129 @@
+/**
+ * THE DECISION of the LaTeX build loop: given what the runs so far observed, what runs next.
+ *
+ * PURE. No disk, no process, no clock. The shell in `build.ts` runs a step, records what it saw
+ * as an `Observation`, appends it to the history and asks `nextStep(summarize(history))` again.
+ * Both halves are table tests (`latex-loop.harness.mjs`), not scenarios that need TeX.
+ *
+ * ── THE LOOP: `summarize` reduces the history to a `State`, and `nextStep` asks four questions ──
+ *   1. did the last program fail?                          → fail, with its error lines
+ *   2. did the citations, a .bib or the style change since
+ *      bibtex last ran?                                    → bibtex
+ *   3. did the last pass change a tracked file, or did the
+ *      log ask for a rerun?                                → latex (fail after MAX_PASSES)
+ *   4. otherwise                                           → one FINAL latex pass, then done
+ *
+ * 🔴 WHY A FINAL PASS AFTER CONVERGENCE. `paper-guards.tex`, shipped by this package, turns an
+ * undefined `\ref` or `\cite` into a BUILD FAILURE — but only on a pass that defines
+ * `\finalpass`, because on the first pass every reference is undefined by construction. Measured
+ * on 2026-08-26 with the unconditional form: pass 1 fails, the `.aux` is never written, pass 2
+ * fails the same way and no PDF ever appears. So the guards need to know which pass is the last,
+ * and only the loop knows it. The price is one extra pdflatex run per build, paid for turning
+ * "?? in the PDF" into a red build.
+ *
+ * 🔴 WHY A CAP. A document can keep changing its own aux on every pass — the textbook case is a
+ * page reference whose own wording moves its target to the other page, and back — and the aux never
+ * settles. Without a cap the loop runs forever; with a silent cap it stops and ships an
+ * unconverged PDF with wrong cross-references. It stops, and it FAILS, naming the file that kept
+ * changing.
+ *
+ * ⚠️ `filecontents` with `[overwrite]` is NOT such a case, though this comment said so until
+ * 2026-09-24. The environment body is verbatim, so every pass writes the same bytes, and the loop
+ * compares CONTENT digests, not modification times. Measured with `paperlint build` on TeX Live 2026: a
+ * real acmart paper embedding its `refs.bib` that way converged in 3 pdflatex passes, and an
+ * `article` with an overwritten `\input` file carrying `\label`/`\ref`, a `\tableofcontents` and
+ * an overwritten `.bib` converged in 4.
+ */
+/** Files a pdflatex pass writes and the next pass reads. A change means the output is stale. */
+export type Tracked = "aux" | "toc" | "out" | "bbl";
+export declare const TRACKED: readonly Tracked[];
+/** Content digests of the tracked files; `null` = the file does not exist. */
+export type Hashes = {
+    readonly [K in Tracked]: string | null;
+};
+/** Log markers, as `latex-log.ts` reads them. Re-declared as a type so this module has no imports. */
+export type LogMarker = "rerun-requested" | "labels-changed" | "rerunfilecheck" | "undefined-references" | "undefined-citations";
+/**
+ * What bibtex would be run on. `none` — the aux names no `\bibdata`, so there is nothing for
+ * bibtex to do. Two `needed` states are the same input exactly when every field is equal: the
+ * citation set moved, a database was added, or a `.bib` file's content changed ⇒ bibtex again.
+ */
+export type BibInput = {
+    readonly kind: "none";
+} | {
+    readonly kind: "needed";
+    /** Sorted, unique cited keys. */
+    readonly citations: readonly string[];
+    readonly databases: readonly string[];
+    readonly style: string | null;
+    /** A digest over the content of every database file that exists; null when none was found. */
+    readonly bibHash: string | null;
+};
+export type Observation = {
+    readonly step: "latex";
+    /** Whether this pass defined `\finalpass`. */
+    readonly final: boolean;
+    readonly exitCode: number;
+    readonly before: Hashes;
+    readonly after: Hashes;
+    readonly markers: readonly LogMarker[];
+    /** The bibliography input as the aux stood after this pass. */
+    readonly bib: BibInput;
+    /** The first error and its source context, from the log. Empty on success. */
+    readonly errorLines: readonly string[];
+} | {
+    readonly step: "bibtex";
+    readonly exitCode: number;
+    readonly before: Hashes;
+    readonly after: Hashes;
+    /** The input bibtex was run on. */
+    readonly bib: BibInput;
+    readonly errorLines: readonly string[];
+};
+export type FailCause = {
+    readonly kind: "exit";
+    readonly code: number;
+} | {
+    readonly kind: "no-convergence";
+    readonly unsettled: readonly string[];
+};
+export type Step = {
+    readonly kind: "latex";
+    readonly final: boolean;
+} | {
+    readonly kind: "bibtex";
+} | {
+    readonly kind: "done";
+    /** Undefined-reference summaries still in the final log — a converged doc with a bad key. */
+    readonly warnings: readonly LogMarker[];
+} | {
+    readonly kind: "fail";
+    readonly step: "latex" | "bibtex";
+    readonly cause: FailCause;
+    /** What to show the human: the log excerpt, or the non-convergence explanation. */
+    readonly lines: readonly string[];
+};
+/** Non-final pdflatex passes allowed before the build is declared non-converging. */
+export declare const MAX_PASSES = 5;
+/** The history, reduced to the four questions `nextStep` asks. */
+export type State = {
+    readonly failed: {
+        readonly step: "latex" | "bibtex";
+        readonly cause: FailCause;
+        readonly lines: readonly string[];
+    } | null;
+    /** Citations, databases, style or `.bib` content changed since bibtex last ran. */
+    readonly bibOutdated: boolean;
+    /** Tracked files the last pass changed (`paper.aux`), or the rerun markers its log printed. */
+    readonly unsettled: readonly string[];
+    /** Non-final pdflatex passes so far. */
+    readonly latexPasses: number;
+    readonly finalDone: boolean;
+    /** Undefined-reference summaries in the log of the final pass. */
+    readonly warnings: readonly LogMarker[];
+};
+export declare function nextStep(s: State): Step;
+/** The tracked files whose digest differs between two snapshots. */
+export declare function changedFiles(before: Hashes, after: Hashes): Tracked[];
+export declare function summarize(history: readonly Observation[]): State;
+//# sourceMappingURL=latex-loop.d.ts.map

package/dist/latex-loop.d.ts.map

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

package/dist/latex-loop.js

@@ -0,0 +1,113 @@
+/**
+ * THE DECISION of the LaTeX build loop: given what the runs so far observed, what runs next.
+ *
+ * PURE. No disk, no process, no clock. The shell in `build.ts` runs a step, records what it saw
+ * as an `Observation`, appends it to the history and asks `nextStep(summarize(history))` again.
+ * Both halves are table tests (`latex-loop.harness.mjs`), not scenarios that need TeX.
+ *
+ * ── THE LOOP: `summarize` reduces the history to a `State`, and `nextStep` asks four questions ──
+ *   1. did the last program fail?                          → fail, with its error lines
+ *   2. did the citations, a .bib or the style change since
+ *      bibtex last ran?                                    → bibtex
+ *   3. did the last pass change a tracked file, or did the
+ *      log ask for a rerun?                                → latex (fail after MAX_PASSES)
+ *   4. otherwise                                           → one FINAL latex pass, then done
+ *
+ * 🔴 WHY A FINAL PASS AFTER CONVERGENCE. `paper-guards.tex`, shipped by this package, turns an
+ * undefined `\ref` or `\cite` into a BUILD FAILURE — but only on a pass that defines
+ * `\finalpass`, because on the first pass every reference is undefined by construction. Measured
+ * on 2026-08-26 with the unconditional form: pass 1 fails, the `.aux` is never written, pass 2
+ * fails the same way and no PDF ever appears. So the guards need to know which pass is the last,
+ * and only the loop knows it. The price is one extra pdflatex run per build, paid for turning
+ * "?? in the PDF" into a red build.
+ *
+ * 🔴 WHY A CAP. A document can keep changing its own aux on every pass — the textbook case is a
+ * page reference whose own wording moves its target to the other page, and back — and the aux never
+ * settles. Without a cap the loop runs forever; with a silent cap it stops and ships an
+ * unconverged PDF with wrong cross-references. It stops, and it FAILS, naming the file that kept
+ * changing.
+ *
+ * ⚠️ `filecontents` with `[overwrite]` is NOT such a case, though this comment said so until
+ * 2026-09-24. The environment body is verbatim, so every pass writes the same bytes, and the loop
+ * compares CONTENT digests, not modification times. Measured with `paperlint build` on TeX Live 2026: a
+ * real acmart paper embedding its `refs.bib` that way converged in 3 pdflatex passes, and an
+ * `article` with an overwritten `\input` file carrying `\label`/`\ref`, a `\tableofcontents` and
+ * an overwritten `.bib` converged in 4.
+ */
+export const TRACKED = ["aux", "toc", "out", "bbl"];
+const RERUN = [
+    "rerun-requested",
+    "labels-changed",
+    "rerunfilecheck",
+];
+/** Non-final pdflatex passes allowed before the build is declared non-converging. */
+export const MAX_PASSES = 5;
+export function nextStep(s) {
+    if (s.failed)
+        return { kind: "fail", ...s.failed };
+    if (s.finalDone)
+        return { kind: "done", warnings: s.warnings };
+    if (s.bibOutdated)
+        return { kind: "bibtex" };
+    if (s.unsettled.length === 0)
+        return { kind: "latex", final: true };
+    if (s.latexPasses < MAX_PASSES)
+        return { kind: "latex", final: false };
+    return noConvergence(s.unsettled);
+}
+const noConvergence = (unsettled) => ({
+    kind: "fail",
+    step: "latex",
+    cause: { kind: "no-convergence", unsettled },
+    lines: [
+        `the build does not converge: after ${MAX_PASSES} pdflatex passes, the last one still changed or asked to rerun: ${unsettled.join(", ")}.`,
+        `A document whose aux keeps changing on every pass never settles; stopping here instead of`,
+        `shipping a PDF with stale cross-references.`,
+    ],
+});
+/** The tracked files whose digest differs between two snapshots. */
+export function changedFiles(before, after) {
+    return TRACKED.filter((f) => before[f] !== after[f]);
+}
+const sameBib = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * What the last run left unsettled. Walking back: a run that changed a tracked file answers with
+ * those files; a latex pass that changed none answers with the rerun markers in its log. A bibtex
+ * run that left the `.bbl` byte-identical changes nothing, so the pass before it answers.
+ */
+function unsettledBy(history) {
+    if (history.length === 0)
+        return ["paper.aux"]; // no pass has written it yet
+    for (const o of history.toReversed()) {
+        const files = changedFiles(o.before, o.after);
+        if (files.length > 0)
+            return files.map((f) => `paper.${f}`);
+        if (o.step === "latex")
+            return o.markers.filter((m) => RERUN.includes(m));
+    }
+    return [];
+}
+export function summarize(history) {
+    const last = history.at(-1);
+    const latexRuns = history.filter((o) => o.step === "latex");
+    const lastLatex = latexRuns.at(-1);
+    const lastBibtex = history.filter((o) => o.step === "bibtex").at(-1);
+    return {
+        failed: last && last.exitCode !== 0
+            ? {
+                step: last.step,
+                cause: { kind: "exit", code: last.exitCode },
+                lines: last.errorLines,
+            }
+            : null,
+        bibOutdated: lastLatex?.bib.kind === "needed" &&
+            !(lastBibtex && sameBib(lastBibtex.bib, lastLatex.bib)),
+        unsettled: unsettledBy(history),
+        latexPasses: latexRuns.filter((o) => !o.final).length,
+        finalDone: last?.step === "latex" && last.final,
+        warnings: last?.step === "latex"
+            ? last.markers.filter((m) => m === "undefined-references" || m === "undefined-citations")
+            : [],
+    };
+}
+//# sourceMappingURL=latex-loop.js.map

package/dist/latex-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"latex-loop.js","sourceRoot":"","sources":["../src/latex-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,MAAM,CAAC,MAAM,OAAO,GAAuB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAaxE,MAAM,KAAK,GAAyB;IAClC,iBAAiB;IACjB,gBAAgB;IAChB,gBAAgB;CACjB,CAAC;AA+DF,qFAAqF;AACrF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAoB5B,MAAM,UAAU,QAAQ,CAAC,CAAQ;IAC/B,IAAI,CAAC,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;IACnD,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC/D,IAAI,CAAC,CAAC,WAAW;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC7C,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACpE,IAAI,CAAC,CAAC,WAAW,GAAG,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACvE,OAAO,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,aAAa,GAAG,CAAC,SAA4B,EAAQ,EAAE,CAAC,CAAC;IAC7D,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE;IAC5C,KAAK,EAAE;QACL,sCAAsC,UAAU,mEAAmE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC1I,2FAA2F;QAC3F,6CAA6C;KAC9C;CACF,CAAC,CAAC;AAEH,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,KAAa;IACxD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,CAAW,EAAE,CAAW,EAAW,EAAE,CACpD,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAE1C;;;;GAIG;AACH,SAAS,WAAW,CAAC,OAA+B;IAClD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,6BAA6B;IAC7E,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAA+B;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO;QACL,MAAM,EACJ,IAAI,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC;YACzB,CAAC,CAAC;gBACE,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE;gBAC5C,KAAK,EAAE,IAAI,CAAC,UAAU;aACvB;YACH,CAAC,CAAC,IAAI;QACV,WAAW,EACT,SAAS,EAAE,GAAG,CAAC,IAAI,KAAK,QAAQ;YAChC,CAAC,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;QACzD,SAAS,EAAE,WAAW,CAAC,OAAO,CAAC;QAC/B,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM;QACrD,SAAS,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,KAAK;QAC/C,QAAQ,EACN,IAAI,EAAE,IAAI,KAAK,OAAO;YACpB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CACjB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,sBAAsB,IAAI,CAAC,KAAK,qBAAqB,CACnE;YACH,CAAC,CAAC,EAAE;KACT,CAAC;AACJ,CAAC"}

package/dist/link-skills.d.ts

@@ -0,0 +1,51 @@
+import { PACKAGE_NAME } from "../skills/paper-pipeline/scripts/consumer.mjs";
+export { PACKAGE_NAME };
+/** Where Claude Code looks for project skills, relative to the project root. */
+export declare const SKILLS_HOME: string;
+export type Located = {
+    readonly dir: string;
+    readonly spelled: string;
+} | {
+    readonly error: string;
+};
+/**
+ * The installed package, asked of Node from the PROJECT, not from wherever this code runs. A copy
+ * run out of the npx cache is not the project's install, and a link into a cache is a link that
+ * disappears with it — so "does not resolve from here" is an answer, not something to paper over.
+ *
+ * @returns `dir` — the real directory; `spelled` — the same directory as the project names it.
+ */
+export declare function locatePackage(project: string): Located;
+/** The skills the package ships: every skill under its `SHIPPED_SKILLS_DIR`. */
+export declare function shippedSkills(pkgDir: string): {
+    readonly skillsDir: string;
+    readonly names: readonly string[];
+} | {
+    readonly error: string;
+};
+export type LinkStatus = "created" | "replaced" | "present" | "missing" | "foreign";
+export interface SkillLink {
+    readonly name: string;
+    readonly status: LinkStatus;
+    /** For `foreign`: what is there instead, in words. */
+    readonly reason?: string;
+}
+export type LinkReport = {
+    readonly ok: true;
+    readonly home: string;
+    /** The link target of the first skill, e.g. `../../node_modules/paperlint/skills/x`. */
+    readonly example: string | null;
+    readonly links: readonly SkillLink[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Link every shipped skill into `<project>/.claude/skills/`, or — with `write: false` — only
+ * report which ones are missing (that is what `paperlint doctor` asks).
+ */
+export declare function linkSkills(project: string, { write, locate, }?: {
+    write?: boolean;
+    locate?: (p: string) => Located;
+}): LinkReport;
+//# sourceMappingURL=link-skills.d.ts.map

package/dist/link-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-skills.d.ts","sourceRoot":"","sources":["../src/link-skills.ts"],"names":[],"mappings":"AA0CA,OAAO,EAGL,YAAY,EAEb,MAAM,+CAA+C,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,gFAAgF;AAChF,eAAO,MAAM,WAAW,QAA4B,CAAC;AAErD,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/B;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAyBtD;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,GAEZ;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAa7B;AAED,MAAM,MAAM,UAAU,GACpB,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,UAAU,GAClB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA+EnD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,EACE,KAAY,EACZ,MAAsB,GACvB,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;CAAO,GAC3D,UAAU,CAuCZ"}