paperlint 3.1.3 → 3.2.0

package/dist/lib/agent-cli-version.js

@@ -0,0 +1,77 @@
+/**
+ * OBSERVE the `claude` CLI version instead of merely probing for the binary.
+ *
+ * ── THE DEFECT THIS EXISTS FOR (issue #7, measured) ─────────────────────────────
+ * `plan-paper-timeline.effects.harness.mjs` is a CHARACTERIZATION test: its job is to go red
+ * when the upstream CLI changes under it. It named the version it characterized — 2.1.227 —
+ * in prose, and then threw away the version it actually saw:
+ *
+ *     spawnSync("claude", ["--version"], { stdio: "ignore" })   // ← only `status` was read
+ *
+ * `stdio: "ignore"` discards the output, so `claude --version` ran as a PRESENCE probe. The
+ * string it printed was never read, never reported and never compared with the prose. Measured
+ * on this machine: the binary is **2.1.273**, the docblock says **2.1.227** — forty-six patch
+ * releases of drift, invisible to a reader of a green log.
+ *
+ * 🔴 WHY NOT PIN THE VERSION. A pin defeats the test: it is SUPPOSED to see upstream move. The
+ * repair is not to stop the drift but to stop the SILENCE about it — observe what is already
+ * spawned, carry the characterized number as a VALUE beside it, and let a reader see the two
+ * diverge instead of inferring it. CI installs `@anthropic-ai/claude-code` unpinned on purpose.
+ *
+ * ── WHY A MODULE AND NOT THREE LINES IN THE HARNESS ─────────────────────────────
+ * The three lines the issue suggests are correct and untestable where they were proposed. The
+ * harness that would exercise them spawns the real CLI, so its assertions about the observation
+ * depend on which version the machine happens to carry — and the one case that matters most,
+ * "the probe discards its output", cannot be staged at all when the spawn is hard-wired. With
+ * the spawner INJECTED, every case becomes deterministic: absent binary, drifted version,
+ * matching version, and the discarding probe itself.
+ */
+/**
+ * The version the effects harness's characterization was written against.
+ *
+ * 🔴 A VALUE, NOT A SENTENCE, and that is the whole point of this constant. The number lived in
+ * a docblock, where nothing could compare it with anything. Here it is compared on every run.
+ * Moving it means deliberately re-characterizing — which is the edit that should be conscious.
+ */
+export const CHARACTERIZED_CLI = "2.1.227";
+/** What `claude --version` prints: `2.1.273 (Claude Code)`. */
+const VERSION_IN = /\b(\d+\.\d+\.\d+)\b/;
+export function observeAgentCli({ spawnSync, program = "claude", characterized = CHARACTERIZED_CLI, }) {
+    // 🔴 `encoding: "utf8"` IS THE FIX. With `stdio: "ignore"` — the shape this replaces — the
+    // child's output goes nowhere and `probe.stdout` comes back null, so everything downstream
+    // would be describing a string that was never read.
+    const probe = spawnSync(program, ["--version"], { encoding: "utf8" });
+    if (probe.status !== 0)
+        return {
+            present: false,
+            raw: "",
+            version: "",
+            characterized,
+            drifted: false,
+            note: `the \`${program}\` CLI is not installed, so no run can be observed`,
+        };
+    const raw = (probe.stdout ?? "").trim();
+    const version = VERSION_IN.exec(raw)?.[1] ?? "";
+    // ⚠️ EXIT 0 AND NOTHING ON STDOUT IS NOT A CLEAN OBSERVATION — it is exactly what the discarded
+    // probe looked like, and reporting `characterized against ""` would be the same lie in a new
+    // place. This is rule 4 of CLAUDE.md applied to the check that enforces it.
+    if (version === "")
+        throw new Error(`\`${program} --version\` exited 0 but printed no version on stdout (got ${JSON.stringify(raw)}` +
+            `${probe.stderr ? `, stderr ${JSON.stringify(probe.stderr.trim().slice(0, 200))}` : ""}). ` +
+            `A presence probe is not an observation: this is the \`stdio: "ignore"\` shape that issue #7 ` +
+            `is about, and a version nobody read must not be reported as one.`);
+    const drifted = version !== characterized;
+    return {
+        present: true,
+        raw,
+        version,
+        characterized,
+        drifted,
+        note: drifted
+            ? `observed \`${program}\` ${version} — the assertions here were characterized against ` +
+                `${characterized}. They still hold, which is itself the result: a characterization test that ` +
+                `silently still holds is indistinguishable from one nobody re-checked.`
+            : `observed \`${program}\` ${version} — the version these assertions were characterized against.`,
+    };
+}
+//# sourceMappingURL=agent-cli-version.js.map

package/dist/lib/agent-cli-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-cli-version.js","sourceRoot":"","sources":["../../lib/agent-cli-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE3C,+DAA+D;AAC/D,MAAM,UAAU,GAAG,qBAAqB,CAAC;AA6BzC,MAAM,UAAU,eAAe,CAAC,EAC9B,SAAS,EACT,OAAO,GAAG,QAAQ,EAClB,aAAa,GAAG,iBAAiB,GAKlC;IACC,2FAA2F;IAC3F,2FAA2F;IAC3F,oDAAoD;IACpD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QACpB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,GAAG,EAAE,EAAE;YACP,OAAO,EAAE,EAAE;YACX,aAAa;YACb,OAAO,EAAE,KAAK;YACd,IAAI,EAAE,SAAS,OAAO,oDAAoD;SAC3E,CAAC;IAEJ,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAEhD,gGAAgG;IAChG,6FAA6F;IAC7F,4EAA4E;IAC5E,IAAI,OAAO,KAAK,EAAE;QAChB,MAAM,IAAI,KAAK,CACb,KAAK,OAAO,+DAA+D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;YAC9F,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK;YAC3F,8FAA8F;YAC9F,kEAAkE,CACrE,CAAC;IAEJ,MAAM,OAAO,GAAG,OAAO,KAAK,aAAa,CAAC;IAC1C,OAAO;QACL,OAAO,EAAE,IAAI;QACb,GAAG;QACH,OAAO;QACP,aAAa;QACb,OAAO;QACP,IAAI,EAAE,OAAO;YACX,CAAC,CAAC,cAAc,OAAO,MAAM,OAAO,oDAAoD;gBACtF,GAAG,aAAa,8EAA8E;gBAC9F,uEAAuE;YACzE,CAAC,CAAC,cAAc,OAAO,MAAM,OAAO,6DAA6D;KACpG,CAAC;AACJ,CAAC"}

package/dist/lib/check.d.ts

@@ -0,0 +1,19 @@
+/** A failure detail: text, any value (rendered with `util.inspect`), or a thunk producing one. */
+export type Detail = unknown;
+/** `check(label, cond, detail?)`, and how many times it has been called. */
+export interface Check {
+    (label: string, cond: unknown, detail?: Detail): void;
+    readonly count: number;
+}
+/** A failure detail as text: strings verbatim, other values through `util.inspect`, a thunk called. */
+export declare function renderDetail(detail: Detail): string;
+/** The label, then the detail: on the same line when it is one line, below it when it is many. */
+export declare function failureMessage(label: string, detail: Detail): string;
+/**
+ * A fresh `check(label, cond, detail?)`. `check.count` is how many times it has been called.
+ * `log` is where a failure is printed — stderr unless this module's own test injects one.
+ */
+export declare function createChecker({ log, }?: {
+    log?: (line: string) => void;
+}): Check;
+//# sourceMappingURL=check.d.ts.map

package/dist/lib/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../lib/check.ts"],"names":[],"mappings":"AAmBA,kGAAkG;AAClG,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC;AAE7B,4EAA4E;AAC5E,MAAM,WAAW,KAAK;IACpB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAKD,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAC5B,GAAmB,GACpB,GAAE;IAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAAG,KAAK,CAW/C"}

package/dist/lib/check.js

@@ -0,0 +1,52 @@
+/**
+ * The one assertion helper every harness uses.
+ *
+ * Until #52 each harness defined its own `check()`, and the copies had drifted: some printed a
+ * detail on failure and some dropped it, some joined it with " — " and some with a newline, and two
+ * passed the LABEL to vigiles' `recordCheck(n)`, which adds its argument to a number — so the
+ * recorded count became a string. One helper removes the drift instead of documenting it.
+ *
+ * What it guarantees:
+ *   - a failure names the label AND the detail, on stderr and in the thrown assertion — the detail
+ *     is what makes a red run diagnosable without re-running it;
+ *   - `detail` may be a function, so an expensive rendering is paid only on failure;
+ *   - every call is counted (`check.count`) and reported to the vigiles runner (`recordCheck`), so
+ *     a harness's summary line and the runner's check count come from the same place.
+ */
+import assert from "node:assert/strict";
+import { inspect } from "node:util";
+import { recordCheck } from "vigiles";
+/** A detail given as a function, so it is only built on failure. */
+const isThunk = (d) => typeof d === "function";
+/** A failure detail as text: strings verbatim, other values through `util.inspect`, a thunk called. */
+export function renderDetail(detail) {
+    const value = isThunk(detail) ? detail() : detail;
+    if (value === undefined || value === null || value === "")
+        return "";
+    return typeof value === "string" ? value : inspect(value, { depth: 6 });
+}
+/** The label, then the detail: on the same line when it is one line, below it when it is many. */
+export function failureMessage(label, detail) {
+    const shown = renderDetail(detail);
+    if (!shown)
+        return label;
+    return shown.includes("\n") ? `${label}\n${shown}` : `${label} — ${shown}`;
+}
+/**
+ * A fresh `check(label, cond, detail?)`. `check.count` is how many times it has been called.
+ * `log` is where a failure is printed — stderr unless this module's own test injects one.
+ */
+export function createChecker({ log = console.error, } = {}) {
+    const check = (label, cond, detail) => {
+        check.count++;
+        recordCheck();
+        if (cond)
+            return;
+        const message = failureMessage(label, detail);
+        log(`✗ ${message}`);
+        assert.fail(message);
+    };
+    check.count = 0;
+    return check;
+}
+//# sourceMappingURL=check.js.map

package/dist/lib/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../lib/check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAWtC,oEAAoE;AACpE,MAAM,OAAO,GAAG,CAAC,CAAS,EAAsB,EAAE,CAAC,OAAO,CAAC,KAAK,UAAU,CAAC;AAE3E,uGAAuG;AACvG,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,KAAK,GAAY,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IACrE,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,MAAc;IAC1D,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,KAAK,EAAE,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAC5B,GAAG,GAAG,OAAO,CAAC,KAAK,MACiB,EAAE;IACtC,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,IAAa,EAAE,MAAe,EAAQ,EAAE;QACpE,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,WAAW,EAAE,CAAC;QACd,IAAI,IAAI;YAAE,OAAO;QACjB,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC9C,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC,CAAC;IACF,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib/markdown.d.ts

@@ -0,0 +1,180 @@
+import type { Token } from "markdown-it";
+/** One ATX heading: its level, its text without the hashes, its 0-based line and line offset. */
+export interface Heading {
+    readonly depth: number;
+    readonly text: string;
+    readonly line: number;
+    readonly offset: number;
+}
+/** A chunk of the document: the heading it starts with (`null` for the preamble), with and without it. */
+export interface Section {
+    readonly heading: Heading | null;
+    readonly raw: string;
+    readonly body: string;
+}
+/** A block tokenizer with markdown-it's shape — the default, or one a test passes. */
+export type Parse = (text: string) => readonly Token[];
+/**
+ * Whether the parser resolved. A linter must check this ITSELF and say out loud that
+ * its heading checks are off: with no parser `headings()` returns an empty list, and
+ * silent emptiness reads as "the document has no headings", that is, as a clean
+ * document. The nudge lives in the linters, because by contract (see the header) this
+ * file has no right to produce a single finding.
+ */
+export declare const MD_AVAILABLE: () => boolean;
+export declare function blankFrontmatter(text: string): string;
+/**
+ * The frontmatter body (between the fences), or `null` — if the file opens without one.
+ *
+ * Added 2026-08-20, when eight places in `.claude/**` cut the frontmatter with eight
+ * slightly different regexes: some knew about `\r\n`, some did not; some required a
+ * newline after the closing fence, some did not. The difference between them is not
+ * style, it is a different answer on one and the same file.
+ *
+ * ⚠️ This is NOT a parser and does not claim to be: `---` frontmatter is not markdown,
+ * no markdown parser models it (the analysis is in the root `CLAUDE.md`, "Considered
+ * and rejected: gray-matter"). The value here is one fence instead of eight, and the
+ * parsing of VALUES is done by `js-yaml` at the caller.
+ */
+export declare function frontmatterBlock(text: string): string | null;
+/**
+ * The document WITHOUT the frontmatter — the block is cut out together with the
+ * newline after it.
+ *
+ * Differs from {@link blankFrontmatter} in that the offsets SHIFT. Both forms are
+ * needed and both have been used already: blanking — where character positions are
+ * later shown to the user; cutting — where the text is merely counted. Choose by what
+ * the caller does, not by taste.
+ */
+export declare function stripFrontmatter(text: string): string;
+/**
+ * All the document's headings: `[{ depth, text, line, offset }]`, in order of occurrence.
+ *
+ * `offset` — the index of the start of the heading's line IN THE SAME text that was
+ * passed in, in `slice`/`indexOf` units (UTF-16), because those are exactly what the
+ * checks cut the document with. `line` — 0-based line number. `text` — without the
+ * hashes, trimmed at the edges.
+ *
+ * ⚠️ ATX ONLY (`## Heading`). Setext (`Heading\n---`) is deliberately NOT counted as a
+ * heading: in this knowledge base `---` is a prose separator, and a paragraph it stands
+ * under without a blank line would become a level-2 heading per CommonMark. The former
+ * regexps knew only ATX, so this preserves the contract rather than narrowing it.
+ */
+export declare function headings(text: string, { parse }?: {
+    parse?: Parse | null;
+}): Heading[];
+/**
+ * Slicing the document into chunks "a heading + everything up to the next heading FROM
+ * THE SAME RANGE of levels". → `[{ heading, raw, body }]`.
+ *
+ * This is exactly what four scripts did as `split(/^(?=## )/m)` and
+ * `split(/^(?=#{2,3} )/m)`. The shape of the expression lied about the intent: "two or
+ * three hashes" is about CHARACTERS, while what is needed is the LEVEL, and `#{2,3}`
+ * also caught a hash inside a ```-block, that is, it cut a quotation from someone
+ * else's paper as a section of its own.
+ *
+ * `heading` — `null` on the zeroth element (the preamble before the first heading). It
+ * is ALWAYS there, including empty: the former `split` also always returned the chunk
+ * before the first separator as its zeroth element, and callers rely on that
+ * (`sub === chunk` in `artifact-coverage` meant "there are no subsections").
+ *
+ * `raw` — WITH the heading line (it is used to count `§` references and bold numbers,
+ * which occur in the heading itself too), `body` — without it (it is used to count words).
+ *
+ * 2026-08-11: moved here rather than copied into every script, because the chunk
+ * boundary is the one place where an off-by-one is easy, and such a mistake has already
+ * happened (`recordBlock` in `skill-corpus.mjs` returned a single "#" character for all
+ * 21 skills).
+ */
+export declare function splitSections(text: string, { min, max }?: {
+    min?: number;
+    max?: number;
+}): Section[];
+/**
+ * The text without the contents of ```-blocks (the fence lines themselves go too).
+ *
+ * Through the parser, not `/```[\s\S]*?```/g`: that pattern glues the end of one block
+ * to the start of the next when the number of fences is odd, knows nothing about `~~~`
+ * fences or indented fences, and silently eats the prose between blocks.
+ *
+ * `blank: true` — the block's lines are NOT deleted but REPLACED with empty ones. The
+ * difference is not cosmetic: deleting the lines GLUES the paragraph before the block to
+ * the paragraph after it, and a code block is a block boundary — on the other side a
+ * different paragraph starts. Measured 2026-08-11 on `<papers-root>/<paper>/README.md`:
+ * `prose-lint` counted 82 sentences there, and after the lines were deleted it counted
+ * 81 — the lead paragraph "**Reproduction commands:**" merged with the text AFTER the
+ * block into one sentence. That is exactly the failure against which `prose-lint` itself
+ * says "Paragraph and heading boundaries END a sentence", and it inflates the
+ * claims-per-sentence counter — the threshold at which the file emits findings. The
+ * former regex preserved the boundary (it left one newline on each side), so `blank` is
+ * also a preservation of the former behaviour where that behaviour was right.
+ */
+/**
+ * The CONTENTS of fenced blocks — the other side of `stripFences`.
+ *
+ * Added 2026-09-08 for the check "a path as a command argument inside a ```-block"
+ * (the sixth form of a reference). A private regex for the fence there would have been
+ * the seventh instance of the class this knowledge base has already paid for:
+ * `/^```[\s\S]*?^```/gm` knows nothing about nested fences or about `~~~`, and the
+ * parser does — the `fence` token has a `content`.
+ *
+ * No parser — returns an empty list, and the caller must survive that: for hooks
+ * degradation is acceptable (see the module comment), while a silent fallback to a
+ * regex would mean a working degraded version that nobody notices.
+ */
+export declare function fences(text: string): string[];
+export declare function stripFences(text: string, { blank }?: {
+    blank?: boolean;
+}): string;
+/**
+ * For SCRIPTS, not for hooks: fails if there is no parser.
+ *
+ * For a linter degradation is acceptable — it is advisory and can say so out loud. A
+ * skill script hands numbers to a pipeline gate, and an empty list of headings there is
+ * indistinguishable from "the paper has no sections". A confident zero has already been
+ * read as a finding four times in this repo; here it is inexpressible.
+ */
+export declare function requireMarkdown({ from, }?: {
+    from?: string;
+}): void;
+/**
+ * GFM tables — rows, cells and the line range, WITH THE PARSER.
+ *
+ * The only consumer as of 2026-08-20 is `crosspost-article`, which needs to re-lay a
+ * table into a monospace block for a platform without tables (Medium). It lives here
+ * and not in the skill, by the rule "markup is parsed with a parser, and in one place":
+ * with a regex a table is told apart from a line of text with pipes only by its
+ * neighbours, and that is exactly the class that has already cost this repo 27 places.
+ *
+ * Returns `{ line, endLine, rows }`, where `rows[0]` is the header; the alignment row
+ * (`| --- |`) is thrown away, because in monospace output it has nothing to express.
+ */
+/**
+ * The document's paragraphs — `paragraph_open` line ranges, WITH THE PARSER.
+ * `[{ line, endLine }]`.
+ *
+ * The only consumer as of 2026-08-21 is `crosspost-article`: the blog's sources are
+ * hard-wrapped at a column (an editorial habit, not markdown), and the platforms render
+ * a single `\n` inside a paragraph DIFFERENTLY — dev.to (Redcarpet) keeps it as a
+ * literal line break, and the paragraph arrives torn into short lines exactly at the
+ * source file's boundaries. Medium has no such defect not because the platform is more
+ * honest, but because the paste goes through "Import a story" — the importer takes the
+ * ALREADY RENDERED page of the site (where the breaks were collapsed by the browser long
+ * ago), not the raw markdown.
+ *
+ * The range is EXACTLY the one `t.map` gives on `paragraph_open` — that is, a code
+ * fence, a heading, a table, a list (in a TIGHT list the item is not wrapped in a
+ * `paragraph_open` at all, it has no paragraph of its own) fall outside this function
+ * automatically, by the construction of the parser, and not by a separate line-type
+ * check.
+ */
+export declare function paragraphs(text: string): {
+    line: number;
+    endLine: number;
+}[];
+export declare function tables(text: string): {
+    line: number;
+    endLine: number;
+    rows: string[][];
+}[];
+//# sourceMappingURL=markdown.d.ts.map

package/dist/lib/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../lib/markdown.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,iGAAiG;AACjG,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,0GAA0G;AAC1G,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,sFAAsF;AACtF,MAAM,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,KAAK,EAAE,CAAC;AAUvD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,eAAoB,CAAC;AAgB9C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,EAAE,KAAsB,EAAE,GAAE;IAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAA;CAAO,GACxD,OAAO,EAAE,CAmBX;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,EAAE,GAAO,EAAE,GAAO,EAAE,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,EAAE,CAsBX;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM7C;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,EAAE,KAAa,EAAE,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,MAAM,CAUR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAC9B,IAAsB,GACvB,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAmB/B;AAED;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAS5E;AAED,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,EAAE,CAoBvD"}

package/dist/lib/markdown.js

@@ -0,0 +1,302 @@
+let md = null;
+try {
+    const { default: MarkdownIt } = await import("markdown-it");
+    md = new MarkdownIt();
+}
+catch {
+    md = null;
+}
+/**
+ * Whether the parser resolved. A linter must check this ITSELF and say out loud that
+ * its heading checks are off: with no parser `headings()` returns an empty list, and
+ * silent emptiness reads as "the document has no headings", that is, as a clean
+ * document. The nudge lives in the linters, because by contract (see the header) this
+ * file has no right to produce a single finding.
+ */
+export const MD_AVAILABLE = () => md !== null;
+/** markdown-it's block tokens for `text`, or null when it did not resolve. A test passes its own. */
+const defaultParse = () => {
+    const parser = md;
+    return parser === null ? null : (text) => parser.parse(text, {});
+};
+/**
+ * The frontmatter is BLANKED with spaces, not cut out: the offsets must stay the
+ * same, because the checks cut the document by offset. Blanking is necessary — inside
+ * a YAML block scalar a line indented by two spaces (`  ## Foo`) is a real ATX
+ * heading to CommonMark, and without blanking the frontmatter starts supplying
+ * sections.
+ */
+const FRONTMATTER_RE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?=\r?\n|$)/;
+export function blankFrontmatter(text) {
+    const m = FRONTMATTER_RE.exec(text);
+    return m ? m[0].replace(/[^\n]/g, " ") + text.slice(m[0].length) : text;
+}
+/**
+ * The frontmatter body (between the fences), or `null` — if the file opens without one.
+ *
+ * Added 2026-08-20, when eight places in `.claude/**` cut the frontmatter with eight
+ * slightly different regexes: some knew about `\r\n`, some did not; some required a
+ * newline after the closing fence, some did not. The difference between them is not
+ * style, it is a different answer on one and the same file.
+ *
+ * ⚠️ This is NOT a parser and does not claim to be: `---` frontmatter is not markdown,
+ * no markdown parser models it (the analysis is in the root `CLAUDE.md`, "Considered
+ * and rejected: gray-matter"). The value here is one fence instead of eight, and the
+ * parsing of VALUES is done by `js-yaml` at the caller.
+ */
+export function frontmatterBlock(text) {
+    const m = FRONTMATTER_RE.exec(text);
+    if (!m)
+        return null;
+    const inner = m[0]
+        .replace(/^---[ \t]*\r?\n/, "")
+        .replace(/\r?\n---[ \t]*$/, "");
+    return inner;
+}
+/**
+ * The document WITHOUT the frontmatter — the block is cut out together with the
+ * newline after it.
+ *
+ * Differs from {@link blankFrontmatter} in that the offsets SHIFT. Both forms are
+ * needed and both have been used already: blanking — where character positions are
+ * later shown to the user; cutting — where the text is merely counted. Choose by what
+ * the caller does, not by taste.
+ */
+export function stripFrontmatter(text) {
+    const m = FRONTMATTER_RE.exec(text);
+    return m ? text.slice(m[0].length).replace(/^\r?\n/, "") : text;
+}
+/** Line-start offsets — so that `token.map` becomes a position in the source string. */
+function lineStarts(text) {
+    const out = [0];
+    for (let i = 0; i < text.length; i++)
+        if (text[i] === "\n")
+            out.push(i + 1);
+    return out;
+}
+/**
+ * All the document's headings: `[{ depth, text, line, offset }]`, in order of occurrence.
+ *
+ * `offset` — the index of the start of the heading's line IN THE SAME text that was
+ * passed in, in `slice`/`indexOf` units (UTF-16), because those are exactly what the
+ * checks cut the document with. `line` — 0-based line number. `text` — without the
+ * hashes, trimmed at the edges.
+ *
+ * ⚠️ ATX ONLY (`## Heading`). Setext (`Heading\n---`) is deliberately NOT counted as a
+ * heading: in this knowledge base `---` is a prose separator, and a paragraph it stands
+ * under without a blank line would become a level-2 heading per CommonMark. The former
+ * regexps knew only ATX, so this preserves the contract rather than narrowing it.
+ */
+export function headings(text, { parse = defaultParse() } = {}) {
+    if (parse === null)
+        return [];
+    const toks = parse(blankFrontmatter(text));
+    const starts = lineStarts(text);
+    const out = [];
+    for (const [i, t] of toks.entries()) {
+        if (t.type !== "heading_open" || !t.map)
+            continue;
+        if (!t.markup || !t.markup.startsWith("#"))
+            continue; // setext — see the caveat above
+        // markdown-it follows `heading_open` with its `inline` token and maps blocks to lines of the
+        // parsed text; the fallbacks are for a token stream that does not (another parser version).
+        const inline = toks[i + 1];
+        out.push({
+            depth: Number(t.tag.slice(1)),
+            text: inline?.type === "inline" ? inline.content.trim() : "",
+            line: t.map[0],
+            offset: starts[t.map[0]] ?? 0,
+        });
+    }
+    return out;
+}
+/**
+ * Slicing the document into chunks "a heading + everything up to the next heading FROM
+ * THE SAME RANGE of levels". → `[{ heading, raw, body }]`.
+ *
+ * This is exactly what four scripts did as `split(/^(?=## )/m)` and
+ * `split(/^(?=#{2,3} )/m)`. The shape of the expression lied about the intent: "two or
+ * three hashes" is about CHARACTERS, while what is needed is the LEVEL, and `#{2,3}`
+ * also caught a hash inside a ```-block, that is, it cut a quotation from someone
+ * else's paper as a section of its own.
+ *
+ * `heading` — `null` on the zeroth element (the preamble before the first heading). It
+ * is ALWAYS there, including empty: the former `split` also always returned the chunk
+ * before the first separator as its zeroth element, and callers rely on that
+ * (`sub === chunk` in `artifact-coverage` meant "there are no subsections").
+ *
+ * `raw` — WITH the heading line (it is used to count `§` references and bold numbers,
+ * which occur in the heading itself too), `body` — without it (it is used to count words).
+ *
+ * 2026-08-11: moved here rather than copied into every script, because the chunk
+ * boundary is the one place where an off-by-one is easy, and such a mistake has already
+ * happened (`recordBlock` in `skill-corpus.mjs` returned a single "#" character for all
+ * 21 skills).
+ */
+export function splitSections(text, { min = 2, max = 6 } = {}) {
+    const hs = headings(text).filter((h) => h.depth >= min && h.depth <= max);
+    const out = [];
+    const [first] = hs;
+    const preEnd = first ? first.offset : text.length;
+    out.push({
+        heading: null,
+        raw: text.slice(0, preEnd),
+        body: text.slice(0, preEnd),
+    });
+    for (const [i, h] of hs.entries()) {
+        const next = hs[i + 1];
+        const end = next ? next.offset : text.length;
+        const nl = text.indexOf("\n", h.offset);
+        const bodyStart = nl === -1 || nl + 1 > end ? end : nl + 1;
+        out.push({
+            heading: h,
+            raw: text.slice(h.offset, end),
+            body: text.slice(bodyStart, end),
+        });
+    }
+    return out;
+}
+/**
+ * The text without the contents of ```-blocks (the fence lines themselves go too).
+ *
+ * Through the parser, not `/```[\s\S]*?```/g`: that pattern glues the end of one block
+ * to the start of the next when the number of fences is odd, knows nothing about `~~~`
+ * fences or indented fences, and silently eats the prose between blocks.
+ *
+ * `blank: true` — the block's lines are NOT deleted but REPLACED with empty ones. The
+ * difference is not cosmetic: deleting the lines GLUES the paragraph before the block to
+ * the paragraph after it, and a code block is a block boundary — on the other side a
+ * different paragraph starts. Measured 2026-08-11 on `<papers-root>/<paper>/README.md`:
+ * `prose-lint` counted 82 sentences there, and after the lines were deleted it counted
+ * 81 — the lead paragraph "**Reproduction commands:**" merged with the text AFTER the
+ * block into one sentence. That is exactly the failure against which `prose-lint` itself
+ * says "Paragraph and heading boundaries END a sentence", and it inflates the
+ * claims-per-sentence counter — the threshold at which the file emits findings. The
+ * former regex preserved the boundary (it left one newline on each side), so `blank` is
+ * also a preservation of the former behaviour where that behaviour was right.
+ */
+/**
+ * The CONTENTS of fenced blocks — the other side of `stripFences`.
+ *
+ * Added 2026-09-08 for the check "a path as a command argument inside a ```-block"
+ * (the sixth form of a reference). A private regex for the fence there would have been
+ * the seventh instance of the class this knowledge base has already paid for:
+ * `/^```[\s\S]*?^```/gm` knows nothing about nested fences or about `~~~`, and the
+ * parser does — the `fence` token has a `content`.
+ *
+ * No parser — returns an empty list, and the caller must survive that: for hooks
+ * degradation is acceptable (see the module comment), while a silent fallback to a
+ * regex would mean a working degraded version that nobody notices.
+ */
+export function fences(text) {
+    if (md === null)
+        return [];
+    const out = [];
+    for (const t of md.parse(blankFrontmatter(text), {}))
+        if (t.type === "fence" || t.type === "code_block")
+            out.push(t.content);
+    return out;
+}
+export function stripFences(text, { blank = false } = {}) {
+    if (md === null)
+        return text;
+    const lines = text.split("\n");
+    const drop = new Set();
+    for (const t of md.parse(blankFrontmatter(text), {}))
+        if ((t.type === "fence" || t.type === "code_block") && t.map)
+            for (let i = t.map[0]; i < t.map[1]; i++)
+                drop.add(i);
+    return blank
+        ? lines.map((l, i) => (drop.has(i) ? "" : l)).join("\n")
+        : lines.filter((_, i) => !drop.has(i)).join("\n");
+}
+/**
+ * For SCRIPTS, not for hooks: fails if there is no parser.
+ *
+ * For a linter degradation is acceptable — it is advisory and can say so out loud. A
+ * skill script hands numbers to a pipeline gate, and an empty list of headings there is
+ * indistinguishable from "the paper has no sections". A confident zero has already been
+ * read as a finding four times in this repo; here it is inexpressible.
+ */
+export function requireMarkdown({ from = import.meta.url, } = {}) {
+    if (MD_AVAILABLE())
+        return;
+    // 🔴 THE CURE DEPENDS ON WHERE THIS COPY RUNS FROM. Measured 2026-09-19: a Claude Code plugin
+    // copy is installed without dependencies (`npm pack` strips `package-lock.json`, and the plugin
+    // cache runs `npm ci` only with a lockfile). The plugin channel was removed in #82, but a copy
+    // installed before then still runs from there, and "npm i at the repo root" would point its user
+    // at a repository they do not have. The location is readable from this file's own URL (`from`,
+    // a parameter only so a test can name a plugin-cache location without copying the file there).
+    const fromPluginCache = from.includes("/.claude/plugins/");
+    console.error("markdown-it does not resolve — this script parses markup with a parser and without it " +
+        "would produce a confident zero instead of an error.\n" +
+        (fromPluginCache
+            ? "  Running from a PLUGIN copy, which is installed without dependencies. Install the npm\n" +
+                "  package in the project as well (`npm i paperlint`) and call it through\n" +
+                "  `npx paperlint`, which resolves from the project's own tree."
+            : "  Cured by `npm i` at the repo root."));
+    process.exit(2);
+}
+/**
+ * GFM tables — rows, cells and the line range, WITH THE PARSER.
+ *
+ * The only consumer as of 2026-08-20 is `crosspost-article`, which needs to re-lay a
+ * table into a monospace block for a platform without tables (Medium). It lives here
+ * and not in the skill, by the rule "markup is parsed with a parser, and in one place":
+ * with a regex a table is told apart from a line of text with pipes only by its
+ * neighbours, and that is exactly the class that has already cost this repo 27 places.
+ *
+ * Returns `{ line, endLine, rows }`, where `rows[0]` is the header; the alignment row
+ * (`| --- |`) is thrown away, because in monospace output it has nothing to express.
+ */
+/**
+ * The document's paragraphs — `paragraph_open` line ranges, WITH THE PARSER.
+ * `[{ line, endLine }]`.
+ *
+ * The only consumer as of 2026-08-21 is `crosspost-article`: the blog's sources are
+ * hard-wrapped at a column (an editorial habit, not markdown), and the platforms render
+ * a single `\n` inside a paragraph DIFFERENTLY — dev.to (Redcarpet) keeps it as a
+ * literal line break, and the paragraph arrives torn into short lines exactly at the
+ * source file's boundaries. Medium has no such defect not because the platform is more
+ * honest, but because the paste goes through "Import a story" — the importer takes the
+ * ALREADY RENDERED page of the site (where the breaks were collapsed by the browser long
+ * ago), not the raw markdown.
+ *
+ * The range is EXACTLY the one `t.map` gives on `paragraph_open` — that is, a code
+ * fence, a heading, a table, a list (in a TIGHT list the item is not wrapped in a
+ * `paragraph_open` at all, it has no paragraph of its own) fall outside this function
+ * automatically, by the construction of the parser, and not by a separate line-type
+ * check.
+ */
+export function paragraphs(text) {
+    if (md === null)
+        return [];
+    return md
+        .parse(blankFrontmatter(text), {})
+        .flatMap((t) => t.type === "paragraph_open" && t.map
+        ? [{ line: t.map[0], endLine: t.map[1] }]
+        : []);
+}
+export function tables(text) {
+    if (md === null)
+        return [];
+    const lines = blankFrontmatter(text).split("\n");
+    const out = [];
+    for (const t of md.parse(blankFrontmatter(text), {})) {
+        if (t.type !== "table_open" || !t.map)
+            continue;
+        const rows = [];
+        for (const raw of lines.slice(t.map[0], t.map[1])) {
+            if (/^\s*\|?[\s:|-]+\|?\s*$/.test(raw) && raw.includes("-"))
+                continue; // alignment
+            rows.push(raw
+                .replace(/^\s*\|/, "")
+                .replace(/\|\s*$/, "")
+                .split("|")
+                .map((c) => c.trim()));
+        }
+        out.push({ line: t.map[0], endLine: t.map[1], rows });
+    }
+    return out;
+}
+//# sourceMappingURL=markdown.js.map