paperlint 2.0.0

package/dist/build-engine.js

@@ -0,0 +1,148 @@
+/**
+ * The shell around `resolveEngine` for `paperlint build`: gather the facts, act on the decision, and
+ * hand the build an environment whose PATH starts with the chosen TeX Live.
+ *
+ * One decision per run, not per paper: the question "install TeX Live?" is asked at most ONCE, for
+ * the union of what the targeted papers need. The install itself is `ensureTexLive` — the same code
+ * `paperlint toolchain` runs, so "yes" here and the command there cannot install different things.
+ */
+// eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+import { spawnSync } from "node:child_process";
+// eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { resolveEngine, probeTree, supportedPlatform, whichOnPath, } from "./engine.js";
+import { UNSUPPORTED, cacheRoot, cachedTrees, ensureTexLive, usableTree, } from "./toolchain.js";
+import { declaredUnion } from "./tex-requirements.js";
+/** The options a caller actually set — `undefined` must still get its default, so no plain spread. */
+const defined = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+function withDefaults(o) {
+    const r = {
+        dryRun: false,
+        interactive: false,
+        ask: async () => "",
+        log: console.log,
+        err: console.error,
+        // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
+        env: process.env,
+        run: spawnSync,
+        // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
+        platform: process.platform,
+        home: homedir(),
+        now: Date.now,
+        ...defined(o),
+        tex: o.tex,
+    };
+    return {
+        ...r,
+        install: o.install ?? (() => ensureTexLive(declaredUnion().tex, r)),
+    };
+}
+/**
+ * The facts `resolveEngine` decides on: rpp's cache and the PATH's TeX Live, each probed. The cache
+ * may hold one tree per TeX Live year; the one reported is the newest COMPLETE one, else the newest
+ * (so a new year whose install was interrupted never wins over a complete older year).
+ */
+export function gatherFacts(o) {
+    const probes = cachedTrees(cacheRoot(o.env, o.home)).map((tree) => ({
+        label: `TeX Live ${tree.year} — paperlint cache (${tree.dir})`,
+        bin: tree.bin,
+        missing: probeTree(tree.bin, o.tex.packages, o.run),
+    }));
+    const cache = usableTree(probes, (p) => p.missing.length === 0);
+    const dir = whichOnPath("pdflatex", o.env["PATH"]);
+    const system = dir
+        ? {
+            label: `TeX Live on PATH (${join(dir, "pdflatex")})`,
+            bin: dir,
+            missing: probeTree(dir, o.tex.packages, o.run),
+        }
+        : null;
+    return {
+        supported: supportedPlatform(o.platform),
+        cache,
+        system,
+        interactive: o.interactive && !o.dryRun,
+        required: Object.keys(o.tex.packages).sort(),
+    };
+}
+const names = (missing) => `${missing.length} package(s): ${missing.join(", ")}`;
+/** The one line a run without a human gets. It names the command and what is missing. */
+export function refusal(d, facts) {
+    const missing = d.kind === "refuse" || d.kind === "ask" ? d.missing : [];
+    const sys = facts.system && facts.system.missing.length
+        ? `; ${join(facts.system.bin, "pdflatex")} lacks: ${facts.system.missing.join(", ")}`
+        : "";
+    if (d.kind === "refuse" && d.reason === "unsupported")
+        return `✗ paperlint build: ${UNSUPPORTED} (missing: ${names(missing)}${sys})`;
+    return `✗ paperlint build: no TeX Live with every package these papers need — run \`npx paperlint toolchain\` (missing: ${names(missing)}${sys})`;
+}
+/** The question a terminal gets — once per run. */
+export function question(facts, root) {
+    if (facts.cache)
+        return `TeX Live in ${root} lacks ${names(facts.cache.missing)}. Install them now? [Y/n] `;
+    return `TeX Live is not installed (needed to compile paper.tex, ~230 MB, ~2 min). Install it now into ${root}? [Y/n] `;
+}
+/** "", "y", "yes" (any case) is yes — the default is to install. An unanswerable question is no. */
+export const isYes = (answer) => answer !== null && ["", "y", "yes"].includes(answer.trim().toLowerCase());
+const onPath = (env, bin) => ({
+    ...env,
+    PATH: [bin, env["PATH"] ?? ""].join(delimiter),
+});
+async function answerOf(o, q) {
+    try {
+        return await o.ask(q);
+    }
+    catch {
+        return null;
+    }
+}
+/** Ask, install on yes, and use the cache when the install verified. */
+async function askAndInstall(o, facts, d) {
+    const root = cacheRoot(o.env, o.home);
+    if (facts.system?.missing.length)
+        o.log(`${join(facts.system.bin, "pdflatex")} is not used: it lacks ${facts.system.missing.join(", ")}`);
+    if (!isYes(await answerOf(o, question(facts, root)))) {
+        o.err(refusal(d, facts));
+        return { ok: false, code: 1 };
+    }
+    const installed = o.install();
+    if (!installed.ok)
+        return { ok: false, code: 1 };
+    const after = gatherFacts(o).cache;
+    if (!after || after.missing.length) {
+        o.err(refusal({
+            kind: "refuse",
+            reason: "not-installed",
+            missing: after?.missing ?? [],
+        }, facts));
+        return { ok: false, code: 1 };
+    }
+    o.log(`engine: ${after.label}`);
+    return { ok: true, env: onPath(o.env, after.bin) };
+}
+/**
+ * Decide which TeX Live builds these papers. `--dry-run` decides and prints, and never asks or
+ * installs: a plan must not have side effects.
+ */
+export async function prepareEngine(options) {
+    const o = withDefaults(options);
+    const facts = gatherFacts(o);
+    const d = resolveEngine(facts);
+    if (d.kind === "use-cache" || d.kind === "use-system") {
+        o.log(`engine: ${d.tree.label}`);
+        return {
+            ok: true,
+            env: d.kind === "use-cache" ? onPath(o.env, d.tree.bin) : o.env,
+        };
+    }
+    if (o.dryRun) {
+        o.log(`engine: none — a real run would stop here: ${refusal(d, facts).slice(2)}`);
+        return { ok: true, env: o.env };
+    }
+    if (d.kind === "ask")
+        return askAndInstall(o, facts, d);
+    o.err(refusal(d, facts));
+    return { ok: false, code: 1 };
+}
+//# sourceMappingURL=build-engine.js.map

package/dist/build-engine.js.map

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

package/dist/build.d.ts

@@ -0,0 +1,163 @@
+import { spawnSync } from "node:child_process";
+import { type PdfReader } from "./pdf-facts.ts";
+import type { Files } from "./ports/files.ts";
+import type { MeasureGeometry } from "./ports/measure-geometry.ts";
+import { type BibInput, type Step } from "./latex-loop.ts";
+import type { BuildResult, PlanLine } from "./types.ts";
+/** A directory counts as a paper by the same markers as `structure.ts` — one shared dictionary. */
+export declare const PAPER_MARKERS: string[];
+/** The source paperlint compiles, and the job name every output file carries. */
+export declare const MAIN = "paper.tex";
+export declare const JOB = "paper";
+/**
+ * Scripts that `paperlint build` USED to run. Their presence is reported and nothing more: running a
+ * file from the paper directory is exactly what this command stopped doing.
+ */
+export declare const IGNORED_SCRIPTS: string[];
+/** The pdflatex flags: never stop for input, stop at the first error, and say file:line. */
+export declare const PDFLATEX_FLAGS: string[];
+/** Everything the steps may know about a paper — parsed from it, not configured. */
+export interface PaperFacts {
+    /** `paper.tex` when it exists, else null. */
+    readonly main: string | null;
+    readonly documentclass: {
+        readonly name: string;
+        readonly options: readonly string[];
+    } | null;
+    /** The `venue` field of `venue.json`, or null. */
+    readonly venue: string | null;
+    /** Paper-supplied build scripts found on disk — reported as ignored. */
+    readonly ignoredScripts: readonly string[];
+}
+/** A process runner with `spawnSync`'s shape — the port the harness replaces. */
+export type Runner = typeof spawnSync;
+/** What a step's `run` receives. `env` is the environment accumulated by the steps before it. */
+export interface BuildContext {
+    readonly paperDir: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly run: Runner;
+    /** Reads a finished PDF — pdf.js by default; the harness passes a fake. */
+    readonly readPdf: PdfReader;
+    /** The page-geometry measurer the facts writer uses. */
+    readonly measure: MeasureGeometry;
+    /** Where the facts file is written. */
+    readonly files: Files;
+}
+export type StepOutcome = {
+    readonly ok: true;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly note?: string;
+} | {
+    readonly ok: false;
+    readonly lines: readonly string[];
+};
+export interface BuildStep {
+    readonly name: string;
+    /** A required step REFUSES the build when it does not apply; an optional one is skipped. */
+    readonly required: boolean;
+    applies(facts: PaperFacts): {
+        yes: boolean;
+        why: string;
+    };
+    run(ctx: BuildContext): StepOutcome | Promise<StepOutcome>;
+}
+/**
+ * `\documentclass[opts]{name}`, read by the unified-latex parser the lint rules already use —
+ * so a `\documentclass` inside a comment is a comment, not a class.
+ */
+export declare function parseDocumentclass(tex: string): PaperFacts["documentclass"];
+export declare function readFacts(paperDir: string): PaperFacts;
+/**
+ * `TEXINPUTS` with `dirs` in front. With nothing set before, the value ENDS in the separator, and
+ * that is load-bearing: an empty element tells kpathsea "and then the system tree", so without it
+ * `article.cls` stops resolving. A value the user already set is kept as they wrote it.
+ */
+export declare function withTexInputs(env: NodeJS.ProcessEnv, dirs: readonly string[]): NodeJS.ProcessEnv;
+export declare const inputsStep: BuildStep;
+/** What bibtex would be run on, as the `.aux` stands now. */
+export declare function bibInput(paperDir: string): BibInput;
+/** pdflatex arguments for a pass. The final pass defines `\finalpass` — see `latex-loop.ts`. */
+export declare function pdflatexArgs(final: boolean): string[];
+type Terminal = Extract<Step, {
+    kind: "done";
+} | {
+    kind: "fail";
+}>;
+/** Run the loop until `nextStep` says done or fail. */
+export declare function compile(ctx: BuildContext): {
+    end: Terminal;
+    latex: number;
+    bibtex: number;
+};
+export declare const compileStep: BuildStep;
+/**
+ * Measure the PDF the compile step wrote and write `_build/paper.facts.json`. A PDF pdf.js cannot
+ * read fails the build: a PDF nothing can measure is not one to hand in. banal (page geometry) is
+ * optional here: without it the geometry fields are null and the build still succeeds — but the
+ * note SAYS so, with the command that installs it (`paperlint toolchain`), because null geometry means
+ * the page-size, column and font-size rules have nothing to judge. A banal that fails is named too.
+ */
+export declare const measureStep: BuildStep;
+/** The build, in order. A new step is one entry here. */
+export declare const STEPS: readonly BuildStep[];
+export declare function planFor(facts: PaperFacts, steps?: readonly BuildStep[]): PlanLine[];
+export declare function formatPlan(plan: readonly PlanLine[]): string[];
+/** The one wording for "the PDF is gone", on every path that ends without a new one. */
+export declare const PDF_REMOVED = "paper.pdf removed \u2014 a stale PDF must not pass for this build";
+export interface BuildOptions {
+    run?: Runner;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    steps?: readonly BuildStep[];
+    log?: (line: string) => void;
+    dryRun?: boolean;
+    readPdf?: PdfReader;
+    /** Where a project's `vendor/banal` is looked for. Default: `$CLAUDE_PROJECT_DIR`, else `cwd`. */
+    projectRoot?: string;
+    /** The page-geometry measurer. Default: banal, as `env` and `projectRoot` configure it. */
+    measure?: MeasureGeometry;
+    /** Where the facts file is written. Default: the disk. */
+    files?: Files;
+}
+export declare function buildPaper(paperDir: string, options?: BuildOptions): Promise<BuildResult>;
+/** A command's run over its targets: stopped before any paper for want of an engine, or ran. */
+export type BuildRun = {
+    readonly kind: "no-engine";
+} | {
+    readonly kind: "ran";
+    readonly results: readonly BuildResult[];
+};
+/**
+ * `paperlint build` over its targets — the ONE path every outcome goes through.
+ *
+ * 🔴 A STALE PDF IS REMOVED HERE, FIRST, AND NOWHERE ELSE. Before the engine is resolved and before
+ * any step, every targeted paper's paper.pdf goes. Then no outcome can leave an old PDF looking
+ * current, including the ones that never reach a step: no qualifying TeX Live, no paper.tex, facts
+ * that do not parse. Removing it per failure path instead is how three of those paths once kept it.
+ * `--dry-run` removes nothing: a plan has no side effects.
+ */
+export declare function buildPapers(targets: readonly string[], { engine, ...options }: BuildOptions & {
+    engine: () => Promise<NodeJS.ProcessEnv | null>;
+}): Promise<BuildRun>;
+/** Immediate subdirectories that look like a paper. Hidden ones are not papers. */
+export declare function papersIn(root: string, markers?: readonly string[]): string[];
+/**
+ * The verdict for one paper, printed under its plan.
+ *
+ *   ✗ compile: pdflatex exited with 1
+ *       ./paper.tex:4: Undefined control sequence.
+ *       l.4 \foo
+ *                bar baz
+ *       full log: …/paper.log
+ *       paper.pdf removed — a stale PDF must not pass for this build
+ */
+export declare function formatResult(r: BuildResult): string;
+export declare function formatResults(results: readonly BuildResult[]): string;
+/**
+ * 🔴 "Nothing to compile" COUNTS AS A REFUSAL on a par with a failed build. Failing to tell these
+ * two apart is what once produced a green run over a paper no job had built.
+ */
+export declare const anyFailed: (results: readonly BuildResult[]) => boolean;
+export declare function remedyFor(results: readonly BuildResult[]): string;
+export {};
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

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