paperlint 2.0.0

package/dist/cli.d.ts

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * `paperlint lint [paths…]` — run every rule over the corpus of papers.
+ *
+ * 🔴 WHY THIS UTILITY EXISTS. Before it, "installation" meant: install the package AND WRITE BY
+ * HAND sixty lines of ESLint flat config, listing ten rules, three languages and four `files`
+ * blocks. That is, the tool dumped its own implementation onto the user: to count the bytes of a
+ * pdf you first had to learn what `language: "tex/latex"` is. The rules still run under ESLint —
+ * but that is INTERNAL machinery, and you no longer need to know it in order to run them.
+ *
+ * Two entry points into the tool, and both are whole now:
+ *     npx paperlint lint              ← here
+ *     uses: zernie/research-paper-pipeline@<sha>    ← action.yml
+ *
+ * ⚠️ THE BOUNDARY THIS UTILITY HAS NO RIGHT TO ERASE: the consumer's data stays with the consumer.
+ * The typography debt, the marker of the author-list check run, the field dictionary — all of that
+ * is about ONE corpus, and wiring it into the package would repeat the defect that put the path
+ * `.claude/skills/verify-citations/...` into a rule's message. So they live in the consumer's
+ * `rpp.json`.
+ *
+ * 🔴 WHY THE COMMAND IS CALLED `lint` AND NOT `check`. It does exactly what everyone else calls by
+ * that word: reads files, changes nothing, prints findings, exits non-zero. `check` is taken in the
+ * ecosystem by another meaning — `cargo check`, `tsc --noEmit`, `npm run check` — it means "build,
+ * but do not emit the artifact", that is, half of a BUILD. A package whose paper build comes first
+ * has no right to occupy that word with a linter. `check` stays as an alias and prints what
+ * replaced it: silently breaking someone else's workflow is worse than asking them to fix a line.
+ */
+import { ESLint } from "eslint";
+import { spawnSync } from "node:child_process";
+import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
+export { isMain };
+import type { Args, RppConfig, ConfigRead } from "./types.ts";
+import { init } from "./init.ts";
+import { type PaperFormat } from "./new-paper.ts";
+import { type Parsed } from "./rules-config.ts";
+export { init };
+export { nextSteps } from "./init.ts";
+/** The config the user would otherwise write by hand. The data comes from `opts`, the mechanism is here. */
+export declare function buildConfig(opts: RppConfig | undefined, texLanguage: unknown): unknown[];
+/**
+ * The rule ids a consumer may name in `rules`: every rule rpp's own config defines, read off that
+ * config rather than listed again. `@eslint/markdown` is a dependency's plugin, not rpp's.
+ */
+export declare const SHIPPED_RULES: ReadonlySet<string>;
+/**
+ * Rules paperlint ships and turns on for no file itself — the ones a consumer opts into with `rules`.
+ * Derived: every shipped rule that no block of rpp's own config names.
+ */
+export declare const OPTIONAL_RULES: ReadonlySet<string>;
+/**
+ * 🔴 AN OPTIONAL RULE THAT IS ON AND REACHES NO PAPER IS A GREEN ZERO. A `files` glob that matches
+ * nothing — a typo, a path relative to the wrong directory — leaves the rule never invoked, and a
+ * rule that never runs reports exactly like a rule that passed. So for every optional rule the
+ * consumer turned on, some linted `paper.tex` must actually have it enabled; the ones none has are
+ * returned, for the caller to refuse.
+ */
+export declare function silentOptionalRules(eslint: ESLint, lintedFiles: readonly string[], opts: RppConfig): Promise<string[]>;
+/**
+ * The settings after the boundary: an unknown key is refused by name, and `rules` becomes parsed
+ * config blocks. Nothing after this sees the raw object.
+ */
+export declare function parseSettings(opts: RppConfig, where: string, baseDir: string): Parsed<RppConfig>;
+export declare function parseArgs(argv: readonly string[]): Args;
+export declare const CONFIG_NAME = "rpp.json";
+export declare const PKG_NAME = "package.json";
+/** Where the consumer's settings were found, and in which of the two carriers. */
+export interface Declaration {
+    readonly path: string;
+    readonly kind: "package.json" | "rpp.json";
+}
+/**
+ * 🔴 THE CLI HAD TO LEARN TO READ `package.json`, AND THAT IS NOT A SIDE ERRAND. `paperlint init` now
+ * writes ONE declaration, into the `package.json` key that the three hooks and `eslint-rules`
+ * already read. Without this walker the install it produces would not work at all: `paperlint lint`
+ * would find no `rpp.json`, report "nothing to lint", and the consumer would be back to
+ * declaring the same directory twice — the defect the single declaration removes (issue #33,
+ * `docs/install.md`).
+ *
+ * `rpp.json` stays readable as a DEPRECATED fallback, and the read says so out loud. Silently
+ * dropping a file this command used to write would break working setups on upgrade.
+ *
+ * The walk goes up to the filesystem root, the way eslint, prettier and tsc find theirs, so a run
+ * from inside one paper sees the same settings as a run from the repository root. At each level
+ * `package.json` wins over `rpp.json`: it is the carrier every other reader uses, so preferring
+ * it is what keeps "one declaration" true rather than merely intended.
+ */
+export declare function findDeclaration(startDir: string): Declaration | null;
+/** Kept as the one-line question "which file holds the settings" — callers that only need a path. */
+export declare function findConfig(startDir: string): string | null;
+/**
+ * Reading the config, ONE reader for all commands. Pulled out of `run()` the moment a second
+ * command needed the same config (`build`): two copies of this block would have drifted apart on
+ * the very first edit — exactly the class that already cost us the empty-set guard in two places.
+ *
+ * @returns `{ opts, configPath }` on success, or `{ code }` — and then the caller exits with it.
+ */
+export declare function readConfig(a: Args, { log, err, cwd, }?: {
+    log?: typeof console.log;
+    err?: typeof console.error;
+    cwd?: string;
+}): ConfigRead;
+/** The papers directory field of the settings, read by its one declared name. */
+export declare function papersDirOf(opts: RppConfig): unknown;
+/** The papers directory may be one directory or several; both spellings normalise to a list. */
+export declare function toPaths(papers: unknown): string[];
+/**
+ * `paperlint hook <name>` — run an editor hook. It exists for ONE thing: so that the wiring does not
+ * address the runtime from the project root.
+ *
+ * 🔴 WHAT IT WAS AND WHY IT BROKE. `hooks.json` called
+ *     node "${CLAUDE_PROJECT_DIR}/node_modules/vigiles/dist/cli.js" hook-runtime run-program …
+ * While `vigiles` was a PEER dependency this path was GUARANTEED: a peer is installed by the
+ * consumer itself, into its own root. After the move to ordinary dependencies the guarantee was
+ * gone, and a measurement showed it — one tarball, two managers:
+ *     npm:  node_modules/vigiles/dist/cli.js   PRESENT
+ *     pnpm: node_modules/vigiles/dist/cli.js   ABSENT (only paperlint in the root)
+ * The cost of the failure is asymmetric: `|| exit 2` stood on PreToolUse(Bash), that is, ANY
+ * command was denied, including the one you fix it with.
+ *
+ * WHAT IT IS NOW. The wiring calls ITS OWN bin — `paperlint` is a direct dependency,
+ * so it lies in the root under any manager — and the runtime is resolved FROM THE POSITION OF THIS
+ * FILE via `createRequire`. Wherever the manager laid the tree out, the resolver finds the same
+ * thing an `import` from inside the package would.
+ *
+ * 🔴 AND `|| exit 2` IS REMOVED FROM THE SHELL. The decision to stop is a decision, and it is taken
+ * here, in code. In the shell it meant "any mishap = block everything": the runtime was not found —
+ * work stopped. Now a runtime that is not found complains LOUDLY and returns 0, while the hook's
+ * real verdict (2 included) passes through. Silent degradation is worse than explicit degradation,
+ * but blocking everything is worse than both.
+ */
+export declare function runHook(name: string | undefined, { err, run, resolve, }?: {
+    err?: typeof console.error;
+    run?: typeof spawnSync;
+    resolve?: (spec: string) => string;
+}): number;
+/**
+ * Create one paper and lint it — shared by `paperlint new` and `paperlint init --paper`, so the two cannot
+ * become two implementations. The lint runs on THAT folder, so the first thing printed after the
+ * file list is its verdict rather than the old "missing PIPELINE-STATUS.md".
+ */
+export declare function createPaperAt(papersRoot: string, name: string, format: PaperFormat, { log, err, cwd, }: {
+    log: typeof console.log;
+    err: typeof console.error;
+    cwd: string;
+}): Promise<number>;
+export declare function run(argv: readonly string[], { log, err, cwd, }?: {
+    log?: typeof console.log;
+    err?: typeof console.error;
+    cwd?: string;
+}): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,MAAM,EAAe,MAAM,QAAQ,CAAC;AAG7C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAK/C,OAAO,EAAE,MAAM,EAAE,MAAM,+CAA+C,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,CAAC;AAClB,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA2B9D,OAAO,EAAE,IAAI,EAAuC,MAAM,WAAW,CAAC;AACtE,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAYxB,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,IAAI,EAAE,CAAC;AAChB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAgFtC,4GAA4G;AAC5G,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,YAAK,EACpB,WAAW,EAAE,OAAO,GACnB,OAAO,EAAE,CAgGX;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAG7C,CAAC;AAQF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAO9C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,SAAS,CAAC,CAanB;AAoBD,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CA4DvD;AAED,eAAO,MAAM,WAAW,aAAa,CAAC;AACtC,eAAO,MAAM,QAAQ,iBAAiB,CAAC;AAkBvC,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAYpE;AAgBD,qGAAqG;AACrG,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,IAAI,EACP,EACE,GAAiB,EACjB,GAAmB,EACnB,GAAmB,GACpB,GAAE;IACD,GAAG,CAAC,EAAE,OAAO,OAAO,CAAC,GAAG,CAAC;IACzB,GAAG,CAAC,EAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACT,GACL,UAAU,CAiGZ;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEpD;AAED,gGAAgG;AAChG,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAKjD;AAKD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,EACE,GAAmB,EACnB,GAAe,EAUf,OAC8C,GAC/C,GAAE;IACD,GAAG,CAAC,EAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IAC3B,GAAG,CAAC,EAAE,OAAO,SAAS,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/B,GACL,MAAM,CAiCR;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,EACE,GAAG,EACH,GAAG,EACH,GAAG,GACJ,EAAE;IAAE,GAAG,EAAE,OAAO,OAAO,CAAC,GAAG,CAAC;IAAC,GAAG,EAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrE,OAAO,CAAC,MAAM,CAAC,CAOjB;AA8LD,wBAAsB,GAAG,CACvB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EACE,GAAiB,EACjB,GAAmB,EACnB,GAAmB,GACpB,GAAE;IACD,GAAG,CAAC,EAAE,OAAO,OAAO,CAAC,GAAG,CAAC;IACzB,GAAG,CAAC,EAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACT,GACL,OAAO,CAAC,MAAM,CAAC,CA0KjB"}