paperlint 3.1.0 → 3.1.2

package/docs/prior-art/test-tooling.md

@@ -1,12 +1,12 @@
-# What we test with, and why there is no test framework here
+# What we test with
 
-**Question this file answers:** this package has 57 `*.harness.mjs` files of plain
-`node:assert/strict`, three bespoke e2e scripts, and no jest, vitest, mocha, ava or `node:test`.
-Is that a gap? Should an npm package's install be tested through a local registry?
+**Question this file answers:** should an npm package's install be tested through a local
+registry, and which tests belong to which tool?
 
-**Verdict: change nothing.** A general-purpose runner would buy a reporter and a second answer to
-"do the tests pass". A local registry is what MULTI-package repositories reach for; a single-package
-CLI packs a tarball and installs it. Both conclusions have named triggers for revisiting, below.
+**Verdict.** Unit tests run on vitest (`*.test.ts` / `*.test.mjs`); agent-facing checks are vigiles
+harnesses; the install and build are end-to-end scripts. The install is tested by packing a
+tarball and installing it by path, not through a local registry: a registry is what
+MULTI-package repositories reach for. That conclusion has named triggers for revisiting, below.
 
 ---
 
@@ -27,10 +27,6 @@ So the genuinely agent-facing harnesses are three: `hooks/hooks.harness.mjs` (`r
 (`runHarnessTest`, which spawns the real `claude` binary against a scripted model), and the skill
 contract checks. Everything else is ordinary Node testing that happens to carry the suffix.
 
-⚠️ **The suffix is a CONTRACT, not a style choice.** `lib/mutation-driver.mjs` pairs batteries to
-harnesses by it. Renaming files for a new runner would break that, which has nothing to do with
-running tests.
-
 ## Why the install e2e stays a script
 
 `test/e2e/install.mjs` is one linear scenario per package manager with strictly dependent steps
@@ -81,25 +77,6 @@ answering. Recording this so the question "would it even run here" never has to
 documented install becoming a cold `npx <name>`. Then: verdaccio as a devDependency spawned by the
 script, Angular-style — not a Docker service in CI.
 
-## Why no vitest, and no `node:test` either
-
-vitest's value is its Vite transform pipeline, jsdom, module mocking and a watch UI. The tests here
-are plain `.mjs`, the sources are compiled by `tsc`, there is no DOM, and the design deliberately
-does not mock — it spawns real processes into temp directories, which is the right shape for a CLI.
-So vitest would add vite and a native esbuild binary to a package whose install weight is itself
-under scrutiny, and nothing breaks without it.
-
-`node:test` costs no dependency but creates the two-answers problem verbatim: a second discovery
-mechanism (`--test` globs against the `.harness.mjs` suffix) and a second exit code.
-
-**What staying honestly costs:** a top-level `assert` stops at the FIRST failure, so a table-driven
-test over many fixtures reports one row per run. Also no name-level filtering (file-level exists:
-`vigiles test <file>`).
-
-**Trigger to revisit:** when continue-after-failure is measurably costing iteration time on a
-table-driven test. The answer then is `node:test`, never vitest, and it must run under the same
-`npm test` line rather than beside it.
-
 ## One known limit, recorded so it is not claimed
 
 **Yarn Berry (PnP) cannot be supported as things stand.** `plugin/hooks/hooks.json` addresses

package/docs/references.md

@@ -0,0 +1,126 @@
+# The reference check
+
+`paperlint build` checks every entry of a paper's bibliography against the services that know
+about published work, after the PDF is built. `paperlint lint` then reports what the check found,
+offline. This page explains how the check works, the file it keeps in your paper's folder, and
+what happens in CI and without a network.
+
+## What is checked, and where
+
+For each entry in the bibliography (the `filecontents` block inside `paper.tex`, else `refs.bib`):
+
+| question                                                                                                 | asked of                                    |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| does the cited work exist, and does its title match?                                                     | Crossref, OpenAlex, Semantic Scholar, arXiv |
+| does a DOI that no registry knows really not exist?                                                      | doi.org, the DOI authority                  |
+| for an entry that claims a published venue, are the authors the published version's, not the preprint's? | DBLP                                        |
+
+CVE identifiers are not checked by `build`: a bibliography has no CVE field, so none is extracted.
+The verify-citations script checks a `cve` against NVD when it is given citations as JSON (see the
+skill), and that is the only place NVD is asked.
+
+A work that is simply not found is `unresolvable`, never a failure: plenty of real work is not
+indexed. Only a positive disproof fails an entry, for example a DOI that resolves to a different
+paper, or one the DOI authority says does not exist.
+
+The verdicts land in `<paper>/_build/references.json`. `paperlint lint` reads that file and reports:
+
+| rule                 | when                                                              |
+| -------------------- | ----------------------------------------------------------------- |
+| `paper/cite-exists`  | an entry's identifier provably does not resolve to the work cited |
+| `paper/author-list`  | an entry's authors are the preprint's under a published venue     |
+| `paper/refs-fresh`   | the bibliography changed since the build checked it — build again |
+| `paper/refs-checked` | no build has checked the references, or the last one could not    |
+
+The step never fails the build. Without a network the PDF is still built and lint warns that the
+references were not checked.
+
+## `repro/references-cache.json` — commit it
+
+Asking five services about every entry is slow. DBLP asks clients to pause between requests, and a
+slow service is retried. Before this cache existed, a 27-reference paper spent 217 seconds on the
+check, on every build, and a 51-reference paper did not finish inside a 12-minute CI job
+([#107](https://github.com/zernie/paperlint/issues/107)).
+
+So the build keeps every answer it receives in `<paper>/repro/references-cache.json`, and the next
+build asks only what that file cannot answer:
+
+- An unchanged bibliography whose answers are under 30 days old asks nothing and makes no network request at all, not even the check
+  for whether the services can be reached.
+- Adding or editing an entry asks only about that entry. Answers are stored per identifier (DOI,
+  arXiv id, or title), so changing an entry's DOI or title is what makes it be asked again.
+- A request that failed is not an answer and is not stored, so the next build asks it again.
+- "Does not exist" from doi.org is not stored either. A DOI cited before the authority has
+  registered it would otherwise stay "does not exist" in the file forever; it is asked again on each
+  build until the authority confirms it.
+
+## When a service refuses
+
+Free services rate-limit. From a CI runner or a shared network, Semantic Scholar answers `429`,
+DBLP answers an HTML page where JSON was asked, a registry stops answering. The check handles this
+within one build:
+
+- **A service that refuses stops being asked for the rest of the build.** The first request to
+  each service goes alone; once a service refuses (a `429` or `5xx`, HTML instead of JSON, a
+  timeout, no connection), no new request goes to it until the next build, and no retries or pauses
+  are spent on it. A service that refuses from the start costs one request. One that starts refusing
+  later costs at most the requests already in flight at that moment — six, the number of entries
+  checked at once.
+- **The entries it would have answered say so.** An entry no registry confirmed carries
+  `not asked: <service>: <reason>` in its reason. An entry whose authors DBLP could not check is
+  `authors: unchecked`, which `paper/refs-checked` reports and lint never treats as a pass.
+- **Once one registry confirms a work, the others are not asked.** A confirmation settles the
+  verdict, so the remaining registries (and doi.org) could only cost requests.
+- **DBLP's pace** — it asks clients to pause between queries — is kept between queries DBLP
+  actually answered, and not after a cached answer or once DBLP has refused.
+
+Measured 2026-09-27 from a sandboxed runner where Semantic Scholar, OpenAlex and Crossref answered
+`429` and DBLP answered HTML: a 30-reference paper built in 5.6 s cold and 5.4 s warm (the check
+used to take 475 s and 450 s). Its entries were recorded, with the refusals named, and each later
+build fills in more of the cache as the services let it.
+
+**Commit this file.** It sits in `repro/`, beside the paper's other reproduction files, and not in
+`_build/`, which is build output. Committed, it makes CI and every other clone start warm: a CI job
+that builds an unchanged paper spends no time on the check.
+
+It holds what the services answered, each answer with the day it was fetched, and never a verdict.
+The verdicts are worked out again from those answers on every build, so an improvement to the
+checker reaches every paper at once, instead of being frozen behind a stored "passed".
+
+### Refreshing it
+
+An answer is used for 30 days after the date in its `fetched` field; after that the next build asks
+again and re-dates it. This is what lets a work that a service had not indexed yet ("no record")
+be found once it is. An answer that could not be refreshed because the service refused stays, and is
+asked again on the next build. To ask sooner:
+
+- **one entry**: delete its lines from the file (the keys name the service and the identifier, and
+  DBLP answers carry the title they were asked for);
+- **everything**: delete the file.
+
+The next build asks again and writes the new answers.
+
+### A file that does not read
+
+The build refuses a cache file it cannot read (bad JSON, another schema version, a field of the
+wrong type) and says which part is wrong. It does not overwrite the file, and does not run the
+check over half a cache: the references are recorded as not checked, and lint says so. Fix the
+file, or delete it.
+
+## CI
+
+| the paper has                     | a CI build                                                         |
+| --------------------------------- | ------------------------------------------------------------------ |
+| a committed, up-to-date cache     | asks nothing, needs no network for the check                       |
+| a cache missing a few new entries | asks about those entries only                                      |
+| no cache committed                | asks about every entry, every run: commit the file after one build |
+
+A CI run writes new answers into its own checkout, which is thrown away. Build locally and commit
+the file to keep the answers.
+
+## Running a checker by hand
+
+The two checkers are scripts in the `verify-citations` skill and can be run on their own to read
+one verdict in full: `verify-cites.mjs` (existence and title) and `bib-authors.mjs` (authors). Run
+from the command line, `verify-cites.mjs` keeps its own cache in `~/.cache/paperlint/cite-cache.json`
+(`VERIFY_CITES_CACHE` overrides); it never reads or writes the paper's committed cache.

package/docs/testing.md

@@ -0,0 +1,118 @@
+# Testing
+
+The one map of the kinds of test in this repository: what each answers, where it lives, what it
+may touch, and how to run it. The rules that apply to every kind are at the end.
+
+## Which kind do I need?
+
+| you are testing                                                                               | kind            |
+| --------------------------------------------------------------------------------------------- | --------------- |
+| a pure function: a parser, a decision, a formatter                                            | **unit**        |
+| a use case or an adapter that reaches the disk, a process, the network or the clock           | **integration** |
+| what an agent sees or does: a hook's decision, a skill's contract                             | **harness**     |
+| the package as someone else gets it: the tarball installed elsewhere, a real TeX build, a PDF | **e2e**         |
+
+When in doubt between unit and integration: if the function takes a port (`Files`,
+`CheckReferences`, `RunProcess`, …) or calls `fetch`, it is integration.
+
+## Unit — vitest, pure functions
+
+- **Answers:** does this function return the right value for this input?
+- **Lives:** beside the module, `<module>.test.ts` for a `.ts` module, `<module>.test.mjs` for a
+  `.mjs` one (TypeScript has no types to check a JS module against, and `allowJs` was measured to
+  break a dozen existing `@ts-expect-error` imports).
+- **May touch:** nothing. No disk, no network, no process, no clock.
+- **Example:** `src/domain/lookup-cache.test.ts` — the reference cache's parse, serialize and key
+  functions, each refusal compared as a whole value.
+
+## Integration — vitest, with fakes through the ports
+
+- **Answers:** does this use case or adapter do the right thing with the world it talks to?
+- **Lives:** beside the module, named like a unit test.
+- **May touch:** a temp directory (`useTempDir` and `writeTree` in `test/support.mjs`), a child
+  process of this repository's own scripts (`runNode`). Never the real network.
+- **How fakes get in:** through the seams the code already has.
+  - a port the use case takes: `memoryFiles` and `scriptedProcess` in `src/adapters/memory/`, a
+    `CheckReferences` function, a `MeasureGeometry`;
+  - `fetch`, stubbed with `vi.stubGlobal` and routed by URL, which also records every request made;
+  - a clock or a pause, passed in (`referencesChecker({ today })`) or run under `vi.useFakeTimers`.
+- **Example:** `src/adapters/references/index.test.ts` — the reference checker over a fake
+  `fetch`: a cold run stores every answer, a warm run makes no request at all (the recorded list of
+  requests is empty), an edited entry asks only for itself.
+
+## Harness — vigiles, the agent-facing surface only
+
+- **Answers:** what does an agent see or cause? A hook's allow or deny on a given input, what a
+  skill's contract promises.
+- **Lives:** `<surface>.harness.mjs` beside what it tests; it imports `runHook`, `runHarnessTest`
+  or `runEval` from vigiles. Harnesses written before this rule that import none of the three are
+  frozen in `scripts/harness-api.frozen.json`, which only shrinks (`scripts/harness-api.test.ts`,
+  #77). A new test of anything else is a unit or integration test.
+- **Asserts through** `lib/check.mjs`: `const check = createChecker();` then
+  `check(label, cond, detail)`. A failure prints the label and the detail, every call is counted.
+  Do not define a local `check`.
+- **Example:** `hooks/hooks.harness.mjs`.
+- **Skills are tested through vigiles**, not a bespoke runner: a home-grown runner here once printed
+  byte-identical "clean" verdicts for three skills that had never loaded.
+
+## End-to-end — `test/e2e/*.mjs`
+
+- **Answers:** does the package work once it is somewhere else? The tarball installed into another
+  tree, a real `pdflatex` build, the PDF's fonts measured.
+- **May touch:** everything a user's machine has, except the network: a citation service is a
+  counting fake `fetch` even here (`test/e2e/build.mjs`).
+- **What each run proves, and when a change owes one:** [`e2e.md`](e2e.md).
+
+## Running
+
+```bash
+npx vitest run <file or folder>   # unit and integration tests
+npx vigiles test <file>           # one harness
+npm test                          # everything: vitest, then every harness
+npm run coverage                  # the same under c8, failing below the thresholds in .c8rc.json
+npm run test:e2e                  # the end-to-end runs
+npm run check                     # every gate CI runs, and the list of what it does not reproduce
+```
+
+While editing, run the tests you touched, `npx tsc --noEmit`, `npx eslint <files>` and
+`npm run fmt:check`. **Before every push, run `npm run check` and read its exit code** — the
+coverage gate cannot be judged from one file.
+
+⚠️ **Not `vigiles test .`**, and never drop `--min=1` from `npm test`. Measured 2026-09-11:
+
+| form                   | what happens                                                                | exit  |
+| ---------------------- | --------------------------------------------------------------------------- | ----- |
+| `vigiles test .`       | `.` is read as a FILE — `ERR_UNSUPPORTED_DIR_IMPORT`, uncaught, runner dies | **0** |
+| `vigiles test`         | `No **/*.harness.{mjs,cjs,js,mts,cts,ts} files found.`                      | **0** |
+| `vigiles test --min=1` | names the empty match and fails                                             | **1** |
+
+`--min=1` is the only thing between "every test passed" and "no test ran". vitest exits 1 when no
+file matches, and it transpiles without type-checking, so `npm run check` runs
+`tsc -p tsconfig.test.json` as its own gate.
+
+## Rules for every kind
+
+1. **Red first.** Run a new test on the code before the change and watch it fail at its own
+   assertion. A test that has only ever been green is indistinguishable from one that cannot fail.
+   Never add a file that patches source to prove a test can fail.
+2. **Assert the whole value** — `assert.deepEqual`, `expect(x).toEqual(…)` on the entire result,
+   not a substring or one field. A substring passes on output that is wrong everywhere else. The
+   exception is prose whose wording is not the subject; say so in a comment.
+3. **Test what the code does, never what its source says.** A test that reads a source file (a
+   `.mjs`, a `SKILL.md`, a README, a config) and asserts it contains some text restates the file:
+   rewording turns it red while a real regression stays green. Assert a return value, a run's output
+   and exit code, what landed on disk, the requests made. Text is the subject only when it is the
+   output — a message the program prints, a file it generates.
+4. **No test touches the real network.** A service is a fake `fetch` or a fake port. A test that
+   passes only while Crossref or DBLP answers is not a test of this package.
+5. **Coverage is 100% on lines, statements, functions and branches**, enforced by `npm run coverage`
+   in `npm run check` and CI. c8 reads `NODE_V8_COVERAGE`, so a CLI a test spawns is measured too,
+   unless the test hands the child a fresh `env` without it. vitest runs in the `threads` pool with
+   native `import` (`vitest.config.ts` says why), and the run preloads `test/coverage-src.mjs`, which
+   answers every import of `dist/*.js` with `src/*.ts`, so no module is measured twice.
+6. **No `c8 ignore`, and no guard deleted to reach 100%.** An effect a test cannot reach — a race, a
+   permission root is never denied, a broken install, a 270 MB download — is made injectable and the
+   test passes a fake. A precondition about an argument becomes the signature. A guard whose input can
+   really occur stays, with the test that reaches it. `scripts/coverage-config.test.ts` fails on any
+   coverage-ignore comment and pins `.c8rc.json`'s `exclude` list.
+7. **Say what an assertion guards** in a comment directly above it (`// Guards: …`).

package/docs/toolchain.md

@@ -141,12 +141,14 @@ bash node_modules/paperlint/skills/render-paper/ensure-checkers.sh
 
 ```
    ✅ aclpubcheck
-   ✅ rebiber
+   ✅ rebiber 1.4.0
    ✅ jinja2
    ✅ textidote (/opt/textidote/textidote.jar)
 ✅ all checkers are installed AND run
 ```
 
-It checks that the tools RUN, not that pip exited zero — `aclpubcheck --help` prints usage and
-exits zero on an interpreter where its own dependencies do not import, so "installed" and "works"
-are separate questions here.
+It checks that the tools RUN, not that pip exited zero: aclpubcheck's checker module is imported
+(which pulls in numpy and pandas) and its `python3 -m aclpubcheck` entry point must answer, and
+rebiber must convert a known arXiv entry to its official record. Both come from their GitHub
+sources pinned to a commit — each project's own instruction, and why is recorded in
+`checkers-requirements.txt`.

package/eslint-rules/install-path-literals.harness.mjs

@@ -118,4 +118,20 @@ const cases = [];
   cases.push("js quiet on a module that asks the port");
 }
 
-for (const c of cases) recordCheck(c);
+// ── 5. A TAGGED TEMPLATE WITH AN INVALID ESCAPE has no cooked value, only the raw one — and the
+//      path in it is still a path. (`String.raw` is exactly where such a template is legal.)
+{
+  const [res] = await jsLinter.lintText(
+    "export const p = String.raw`node_modules/paperlint/\\unicode`;\n",
+    { filePath: join(ROOT, "tagged.probe.mjs") },
+  );
+  const m = res.messages.filter((x) => x.ruleId === RULE_JS);
+  assert.equal(
+    m.length,
+    1,
+    `a raw-only template quasi must be read, got ${JSON.stringify(res.messages)}`,
+  );
+  cases.push("js fires on a tagged template whose quasi has no cooked value");
+}
+
+recordCheck(cases.length);

package/eslint-rules/latex-language.harness.mjs

@@ -11,9 +11,9 @@
  *       clean.tex` goes through the repository's real `eslint.config.mjs` and must be silent.
  *   II. THE PROJECTION ACTUALLY DID ITS WORK — headings (including SYNTHESISED ones), caption
  *       and footnote prose kept, float markup blanked, opaque macros blanked, math blanked,
- *       comments recognised. This is the half that a mutation battery can kill; without it the
- *       language could be gutted and part I would stay green, because a projection that blanks
- *       everything is also silent.
+ *       comments recognised. This is the half a gutted projection could still hide behind;
+ *       without it the language could be gutted and part I would stay green, because a
+ *       projection that blanks everything is also silent.
  *  III. FIRES ON A PLANTED DEFECT — `fixtures/latex-language/defect.tex`, through the real
  *       config, must produce findings, and at the right addresses.
  *   IV. THE LANGUAGE'S BOUNDARIES AS ASSERTIONS. A known limitation recorded only in prose

package/eslint-rules/latex-language.mjs

@@ -33,7 +33,7 @@
  * arguments of those two macros.
  * 🔴 Removing `table` / `figure` from `CODEISH` was NOT an option — rules would then receive
  * `&`, `\\`, the column specification and tikz nodes, i.e. findings on markup. That is pinned
- * by the harness and by a "naive fix" mutation which that part kills.
+ * by the harness.
  * Measured after the fix: nine new findings across three papers, all of them captions and
  * footnotes, reviewed one by one; zero false positives on markup.
  *
@@ -143,8 +143,13 @@ const argEnd = (node) => {
   return end;
 };
 
-export function texToMdast(src) {
-  const ast = getParser().parse(src);
+/**
+ * The projection of `src`. `parse` is unified-latex by default; a test passes one returning the
+ * node shapes today's parser never emits (a macro without `args`, an argument without `content`, an
+ * `env` given as nodes), which the fallbacks below keep reading instead of throwing on.
+ */
+export function texToMdast(src, { parse = (s) => getParser().parse(s) } = {}) {
+  const ast = parse(src);
   const chars = src.split("");
   const blank = (from, to) => {
     for (let i = from; i < to && i < chars.length; i++)
@@ -264,15 +269,13 @@ export function texToMdast(src) {
         return;
       }
       if (env === "thebibliography" && pos) {
-        const h = synthHeading(
+        // `\begin{thebibliography}` (23 characters) always holds `## References` (13).
+        synthHeading(
           pos.start.offset,
           pos.start.offset + "\\begin{thebibliography}".length,
           "References",
         );
-        blank(
-          pos.start.offset + (h ? "## References".length : 0),
-          pos.end.offset,
-        );
+        blank(pos.start.offset + "## References".length, pos.end.offset);
         children.push({
           type: "code",
           lang: env,
@@ -282,7 +285,7 @@ export function texToMdast(src) {
         return;
       }
       if (CODEISH.test(env) && pos) {
-        // 🔴 THERE WERE TWO LOCKS, AND LIFTING ONE DID NOT HELP (proved by mutation): a
+        // 🔴 THERE WERE TWO LOCKS, AND LIFTING ONE DID NOT HELP: a
         // caption was blanked by `OPAQUE` as a macro, and inside `table` / `figure` it was
         // blanked AGAIN by the whole environment. So what is blanked here is not the float's
         // borders but the float MINUS the arguments of `\caption{}` / `\footnote{}`.

package/eslint-rules/latex-language.test.mjs

@@ -0,0 +1,200 @@
+/**
+ * texToMdast / texLanguage on the shapes the harness does not carry: a `thebibliography`
+ * environment, a float on the file's last line with no newline after it, a heading whose title
+ * holds a macro, an unknown macro in prose, and a parse that fails (nesting deep enough to exhaust the parser).
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { texLanguage, texToMdast } from "./latex-language.mjs";
+
+/** The projection plus each node's type, lang/title and start–end offsets. */
+const project = (src) => {
+  const { root, text } = texToMdast(src);
+  return {
+    text,
+    nodes: root.children.map((c) => [
+      c.type,
+      c.lang ?? c.title,
+      c.position.start.offset,
+      c.position.end.offset,
+    ]),
+  };
+};
+
+test("thebibliography: a References heading over `\\begin`, the rest one blanked code node", () => {
+  assert.deepEqual(
+    project(
+      "\\begin{thebibliography}{9}\n\\bibitem{a} A.\n\\end{thebibliography}\n",
+    ),
+    {
+      text: "## References             \n              \n                     \n",
+      nodes: [
+        ["heading", "References", 0, 13],
+        ["code", "thebibliography", 14, 63],
+      ],
+    },
+  );
+});
+
+test("a float on the last line with no newline after it ends at the end of the file", () => {
+  assert.deepEqual(project("x\n\\begin{table}y\\end{table}"), {
+    text: "x\n                         ",
+    nodes: [["code", "table", 2, 27]],
+  });
+});
+
+test("a heading's title drops an argument-less macro inside it; an unknown macro in prose loses only its name", () => {
+  assert.deepEqual(
+    project("\\section{A \\LaTeX{} b}\nsome \\foo{bar} text\n"),
+    {
+      text: "##               A  b \nsome     {bar} text\n",
+      nodes: [["heading", "A  b", 0, 22]],
+    },
+  );
+});
+
+test("a heading's title keeps the text of a macro with an argument", () => {
+  assert.deepEqual(project("\\section{A \\emph{b} c}\n"), {
+    text: "##              A b c \n",
+    nodes: [["heading", "A b c", 0, 22]],
+  });
+});
+
+test("a body the parser cannot take (nesting deep enough to exhaust its stack) is a parse failure, not a throw", () => {
+  const r = texLanguage.parse({ body: "{".repeat(20_000) });
+  assert.deepEqual(
+    [r.ok, r.errors.map((e) => e.constructor.name)],
+    [false, ["RangeError"]],
+  );
+});
+
+/** A node position on line 1, from offset `a` to offset `b`. */
+const at = (a, b) => ({
+  start: { offset: a, line: 1, column: a + 1 },
+  end: { offset: b, line: 1, column: b + 1 },
+});
+
+test("node shapes today's parser never emits are read, not thrown on", () => {
+  // Each node lacks what unified-latex always gives: `args`, an argument's `content`, a string `env`.
+  const src = " ".repeat(200);
+  const ast = {
+    type: "root",
+    content: [
+      // a heading macro with no args at all: an empty title
+      { type: "macro", content: "section", position: at(0, 8) },
+      // a heading whose title holds a macro whose argument has no content
+      {
+        type: "macro",
+        content: "subsection",
+        position: at(10, 40),
+        args: [
+          {
+            type: "argument",
+            openMark: "{",
+            closeMark: "}",
+            content: [
+              { type: "string", content: "T", position: at(22, 23) },
+              { type: "macro", content: "emph", args: [{ type: "argument" }] },
+            ],
+          },
+        ],
+      },
+      // an environment named by nodes rather than a string
+      {
+        type: "environment",
+        env: [{ type: "string", content: "abstract" }],
+        content: [],
+        position: at(50, 80),
+      },
+      // a float whose caption has no args, and whose footnote's argument has no content
+      {
+        type: "environment",
+        env: "table",
+        position: at(90, 120),
+        content: [
+          { type: "macro", content: "caption", position: at(95, 100) },
+          {
+            type: "macro",
+            content: "footnote",
+            position: at(101, 110),
+            args: [{ type: "argument" }],
+          },
+        ],
+      },
+      // texttt and a first-column textbf with no args; an ordinary macro whose argument is empty
+      { type: "macro", content: "texttt", position: at(125, 132) },
+      {
+        type: "macro",
+        content: "textbf",
+        position: {
+          start: { offset: 133, line: 2, column: 1 },
+          end: { offset: 140, line: 2, column: 8 },
+        },
+      },
+      {
+        type: "macro",
+        content: "foo",
+        position: at(141, 150),
+        args: [{ type: "argument" }],
+      },
+      // the same macros with an argument that has no content
+      {
+        type: "macro",
+        content: "subsubsection",
+        position: at(170, 180),
+        args: [{ type: "argument", openMark: "{", closeMark: "}" }],
+      },
+      {
+        type: "macro",
+        content: "texttt",
+        position: at(181, 185),
+        args: [{ type: "argument" }],
+      },
+      {
+        type: "macro",
+        content: "emph",
+        position: {
+          start: { offset: 186, line: 3, column: 1 },
+          end: { offset: 190, line: 3, column: 5 },
+        },
+        args: [{ type: "argument" }],
+      },
+      // `\bibliography` squeezed into one character: too short for `## References`, so no heading
+      { type: "macro", content: "bibliography", position: at(160, 160) },
+      // a node the walk meets without a position
+      { type: "environment", env: "abstract", content: [] },
+    ],
+  };
+  const { root } = texToMdast(src, { parse: () => ast });
+  assert.deepEqual(
+    root.children.map((c) => [c.type, c.title ?? c.lang ?? ""]),
+    // Sorted by offset: the float's code node starts at its (single) line's start.
+    [
+      ["heading", ""],
+      ["code", "table"],
+      ["heading", "T"],
+      ["heading", "Abstract"],
+      ["strong", ""],
+      ["heading", ""],
+      ["strong", ""],
+    ],
+  );
+});
+
+test("a source code made from a parse result without the raw text reads the projection; parents are recorded", () => {
+  const body = "\\section{A}\n";
+  const parsed = texLanguage.parse({ body });
+  const code = texLanguage.createSourceCode(
+    { body },
+    { ast: parsed.ast, projected: parsed.projected },
+  );
+  const [heading] = parsed.ast.children;
+  assert.deepEqual(
+    [
+      code.raw === parsed.projected,
+      code.getParent(parsed.ast),
+      code.getParent(heading) === parsed.ast,
+    ],
+    [true, undefined, true],
+  );
+});