paperlint 9.0.1 → 10.0.0

package/dist/domain/scaffold-layout.js

@@ -0,0 +1,81 @@
+/**
+ * WHAT `paperlint new` PUTS IN A NEW PAPER FOLDER BESIDE ITS THREE FILES — the layout, visible from the
+ * first commit.
+ *
+ * The rules `paper/allowed-files-only` and `repro/allowed-files-only` say where every kind of material goes. A
+ * paper that starts with three files shows none of it, and the first reviewer's report, the first
+ * figure and the first script each land loose at the root. So a new folder already holds the places.
+ *
+ * ── ONE SOURCE OF TRUTH ──────────────────────────────────────────────────────────
+ * Nothing here lists a folder by hand. The folders are `ROOT_DIR_NOTES` (paper-layout.ts) minus the
+ * ones named in `NOT_SCAFFOLDED`, each with its reason; `repro/` gets its own shared folders from
+ * `REPRO_DIR_NOTES`. A folder added to the layout is scaffolded unless someone writes down why not,
+ * and a test fails on an excluded name the layout no longer has.
+ *
+ * ── `.gitkeep` ───────────────────────────────────────────────────────────────────
+ * Git keeps files, not folders: an empty folder is not in the first commit, which is the point of
+ * scaffolding. A folder that holds nothing else gets a `.gitkeep`; a folder that holds a real file
+ * (`repro/` with its README.md) gets none. `.gitkeep` is the convention, not a paperlint file, and no
+ * rule reads it: `paper/stages` looks for `*.pdf` in `versions/`, the review and sibling rules lint
+ * `*.md`, `repro/allowed-files-only` judges the top of `repro/` only, and neither `tools/` nor `data/` is
+ * listed by any rule.
+ *
+ * Pure: a list of paths and texts, written by `new-paper.ts`.
+ */
+import { ROOT_DIR_NOTES } from "./paper-layout.js";
+import { DATA_DIR, README, REPRO_DIR, REPRO_DIR_NOTES, TOOLS_DIR, } from "./repro-layout.js";
+/** The placeholder git needs to keep an otherwise empty folder. */
+export const GITKEEP = ".gitkeep";
+/**
+ * The folders of the layout that `paperlint new` does not create, each with why. A folder here is
+ * allowed at the root all the same; it appears when the work needs it.
+ */
+export const NOT_SCAFFOLDED = [
+    {
+        name: "_build",
+        why: "`paperlint build` writes it, and an empty one would claim a build that never ran",
+    },
+    {
+        name: "siblings",
+        why: "a card is written when a close competitor turns up (skill analyze-sibling-paper, which also writes the folder's README.md index); a paper may have none, and an empty folder reads as an unfinished analysis",
+    },
+    {
+        name: "sections",
+        why: "the body is split only when it outgrows `paper.tex`; the stub is one file, and an empty `sections/` suggests the split is expected",
+    },
+    {
+        name: "talk",
+        why: "only a paper that declares a talk (`talk` in paperlint.json) has one, and its folder is the declared `talk.dir`, which need not be `talk/`",
+    },
+    {
+        name: "extra",
+        why: "the escape hatch for material nothing else takes; it is never judged, so it has no place in a layout meant to be filled by kind",
+    },
+];
+/** The folders at the paper's root that a new paper holds from the first commit, in layout order. */
+export const SCAFFOLD_DIRS = ROOT_DIR_NOTES.map((d) => d.name).filter((name) => !NOT_SCAFFOLDED.some((n) => n.name === name));
+/**
+ * The stub index of `repro/`: it makes the folder non-empty (no `.gitkeep`) and says what the rule
+ * asks of it. A line per study is added when the first study is.
+ */
+export const REPRO_INDEX_STUB = `# Reproduction index
+
+One line per study: \`<slug>-YYYY-MM-DD/\` — what it asks and what it found. Scripts used across the
+paper go in \`${TOOLS_DIR}/\`, shared data in \`${DATA_DIR}/\`.
+`;
+/**
+ * Every file of the layout scaffold, relative to the paper folder, in a fixed order: a `.gitkeep` in
+ * each empty folder, and `repro/README.md` where `repro/` would otherwise hold only folders.
+ */
+export const SCAFFOLD_FILES = [
+    ...SCAFFOLD_DIRS.flatMap((dir) => dir === REPRO_DIR
+        ? [
+            { path: `${REPRO_DIR}/${README}`, text: REPRO_INDEX_STUB },
+            ...REPRO_DIR_NOTES.map((d) => ({
+                path: `${REPRO_DIR}/${d.name}/${GITKEEP}`,
+                text: "",
+            })),
+        ]
+        : [{ path: `${dir}/${GITKEEP}`, text: "" }]),
+];
+//# sourceMappingURL=scaffold-layout.js.map

package/dist/domain/scaffold-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-layout.js","sourceRoot":"","sources":["../../src/domain/scaffold-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EACL,QAAQ,EACR,MAAM,EACN,SAAS,EACT,eAAe,EACf,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,mEAAmE;AACnE,MAAM,CAAC,MAAM,OAAO,GAAG,UAAU,CAAC;AAElC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAGrB;IACJ;QACE,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,kFAAkF;KACxF;IACD;QACE,IAAI,EAAE,UAAU;QAChB,GAAG,EAAE,8MAA8M;KACpN;IACD;QACE,IAAI,EAAE,UAAU;QAChB,GAAG,EAAE,oIAAoI;KAC1I;IACD;QACE,IAAI,EAAE,MAAM;QACZ,GAAG,EAAE,4IAA4I;KAClJ;IACD;QACE,IAAI,EAAE,OAAO;QACb,GAAG,EAAE,iIAAiI;KACvI;CACF,CAAC;AAEF,qGAAqG;AACrG,MAAM,CAAC,MAAM,aAAa,GAAsB,cAAc,CAAC,GAAG,CAChE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CACd,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC;AAEjE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;gBAGhB,SAAS,yBAAyB,QAAQ;CACzD,CAAC;AAQF;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,GAAG,EAA2B,EAAE,CACxD,GAAG,KAAK,SAAS;QACf,CAAC,CAAC;YACE,EAAE,IAAI,EAAE,GAAG,SAAS,IAAI,MAAM,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE;YAC1D,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC7B,IAAI,EAAE,GAAG,SAAS,IAAI,CAAC,CAAC,IAAI,IAAI,OAAO,EAAE;gBACzC,IAAI,EAAE,EAAE;aACT,CAAC,CAAC;SACJ;QACH,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAC9C;CACF,CAAC"}

package/dist/eslint-rules/prereg-coverage.d.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import type { RuleContext } from "./rule-context.ts";
+/**
+ * The folder of a paper that holds its studies, the folders in it that are shared rather than a
+ * study's, and the file a study pre-registers in. The first two are `repro/allowed-files-only`'s
+ * (`src/domain/repro-layout.ts`, `REPRO_DIR` and `REPRO_DIRS`), copied because a module here is
+ * compiled before `src/`; the test beside this file holds the copies equal.
+ */
+export declare const REPRO_DIR = "repro";
+export declare const SHARED_DIRS: readonly string[];
+export declare const PREREG_FILE = "prereg.json";
+/** The one sentence every finding ends with: why the fields exist. */
+export declare const WHY = "Why: a study once screened its sample down to rules that are easy to judge \u2014 its labeller found 93 % of the items designed as borderline clear-cut \u2014 and nothing in its design made anyone state what share of the real population the sample covered or which screens removed which kinds of units.";
+/** The answers to "is this what you meet in practice?"; any but the first needs a decision. */
+export declare const VERDICTS: string[];
+/** The declaration a `prereg.json` must carry. Every other key of the file is the author's. */
+export declare const PREREG: z.ZodObject<{
+    population: z.ZodObject<{
+        about: z.ZodString;
+        source: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$strip>;
+    strata: z.ZodObject<{
+        by: z.ZodString;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    screens: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        removed: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>>;
+    coverage: z.ZodObject<{
+        share: z.ZodNullable<z.ZodNumber>;
+        reason: z.ZodOptional<z.ZodString>;
+        unreachable: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    author_check: z.ZodObject<{
+        who: z.ZodString;
+        when: z.ZodISODate;
+        units_seen: z.ZodNumber;
+        units_drawn: z.ZodNumber;
+        verdict: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        decision: z.ZodOptional<z.ZodObject<{
+            proceed: z.ZodBoolean;
+            by: z.ZodString;
+            why: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Prereg = z.infer<typeof PREREG>;
+/** A zod path as it is written in the file: `screens[0].removed.vague`. */
+export declare const pathText: (path: readonly PropertyKey[]) => string;
+/** One problem: the field it is about, and what is wrong with it. */
+export interface Problem {
+    readonly at: string;
+    readonly text: string;
+}
+/** What a schema of one field cannot see: how the fields of a parsed declaration relate. */
+export declare function crossProblems(p: Readonly<Prereg>): readonly Problem[];
+/** Everything wrong with the parsed JSON of one `prereg.json`, in the file's field order. */
+export declare function judgePrereg(data: unknown): readonly Problem[];
+/** The problems of one `prereg.json` whose text is `source`: a parse failure, or the judgement. */
+export declare function preregProblems(source: string): readonly Problem[];
+/** The one text a problem in the file `file` (relative to the paper) is reported with. */
+export declare const problemMessage: (file: string, p: Problem) => string;
+/**
+ * The `prereg.json` of every study folder at the top of `<paperDir>/repro/`, relative to the paper:
+ * every folder there but the shared ones, whatever its name — a study folder misnamed is
+ * `repro/allowed-files-only`'s finding, and its pre-registration is still judged here.
+ */
+export declare function preregFiles(paperDir: string): readonly string[];
+/** Every finding for the paper folder `paperDir`, one text each. */
+export declare const paperFindings: (paperDir: string) => readonly string[];
+declare const _default: {
+    rules: {
+        "declare-sample": {
+            meta: {
+                type: "problem";
+                docs: {
+                    description: string;
+                    url: string;
+                };
+                schema: never[];
+                messages: {
+                    coverage: string;
+                };
+            };
+            create(context: RuleContext): {
+                root?: never;
+            } | {
+                root(): void;
+            };
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=prereg-coverage.d.ts.map

package/dist/eslint-rules/prereg-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prereg-coverage.d.ts","sourceRoot":"","sources":["../../eslint-rules/prereg-coverage.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,UAAU,CAAC;AACjC,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAAsB,CAAC;AAChE,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAKzC,sEAAsE;AACtE,eAAO,MAAM,GAAG,mTACwR,CAAC;AA2GzS,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,UAAqD,CAAC;AAoC3E,+FAA+F;AAC/F,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAWlB,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE5C,2EAA2E;AAC3E,eAAO,MAAM,QAAQ,GAAI,MAAM,SAAS,WAAW,EAAE,KAAG,MAIhC,CAAC;AAEzB,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAkDD,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,OAAO,EAAE,CAoBrE;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAQ7D;AAOD,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAiBjE;AAED,0FAA0F;AAC1F,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,GAAG,OAAO,KAAG,MAO7C,CAAC;AAEd;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAkB/D;AAUD,oEAAoE;AACpE,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,KAAG,SAAS,MAAM,EAO5D,CAAC;;;;;;;;;;;;;;;4BAeiB,WAAW;;;;;;;;AAbjC,wBA8BE"}

package/dist/eslint-rules/prereg-coverage.js

@@ -0,0 +1,274 @@
+/**
+ * `study/declare-sample` — a study's pre-registration says which population the paper's claim is
+ * about, what the screens between that population and the sample removed, what share of it the
+ * sample can represent, and that the author looked at the drawn units before the run.
+ *
+ * ── THE FAILURE IT PREVENTS ──────────────────────────────────────────────────────
+ * A measurement study of how language models read coding rules drew its rules from three pools,
+ * kept only the rules "judgeable from one code excerpt of at most 40 lines", restricted one pool to a
+ * classifier's "enforceable" lane, and let a model pick short excerpts. Each screen was reasonable
+ * alone; together they left a sample of crisp rules. The labeller found 93 % of the items designed as
+ * borderline clear-cut, and the rules looked nothing like the ones met in practice. A spot-check of
+ * ten items flagged it (seven of ten clear-cut) and the run went ahead: nothing in the design made
+ * anyone state what share of the population the sample covered, or which screens removed which kinds
+ * of rules. The four fields below are those statements, and this rule makes them part of the record.
+ *
+ * ── WHERE IT LOOKS ───────────────────────────────────────────────────────────────
+ * A study lives in a folder at the top of the paper's `repro/` (`repro/allowed-files-only` names the
+ * layout); `tools/` and `data/` beside them are shared, not studies. Every study folder that holds a
+ * `prereg.json` is judged; a study without one owes nothing here. The findings are reported on the paper's `PIPELINE-STATUS.md`, first line, as the other rules
+ * about a paper's folders are: `prereg.json` is not a file paperlint lints, and every paper has a
+ * status file.
+ *
+ * ── THE FIELDS ───────────────────────────────────────────────────────────────────
+ *   population    { about, source, size }            what the claim is about, where it comes from, how many
+ *   strata        { by, values }                     the one stratification the screens are counted by
+ *   screens       [{ name, removed: {value: n} }]    each screen, and what it removed per stratum value
+ *   coverage      { share, reason?, unreachable }    0–1, or null with a reason; strata it cannot reach
+ *   author_check  { who, when, units_seen, units_drawn, verdict, decision? }
+ *
+ * A pre-registration holds much more (hypotheses, arms, models, budget); every other key is the
+ * author's and is not read. The shape is `PREREG` below — a zod schema whose every field carries the
+ * text a finding gives for it — and the relations between fields that a schema of one field cannot
+ * see (`removed` keyed by the declared strata, a null share with a reason, a doubtful verdict with a
+ * decision) are `crossProblems`.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { z } from "zod";
+/**
+ * The folder of a paper that holds its studies, the folders in it that are shared rather than a
+ * study's, and the file a study pre-registers in. The first two are `repro/allowed-files-only`'s
+ * (`src/domain/repro-layout.ts`, `REPRO_DIR` and `REPRO_DIRS`), copied because a module here is
+ * compiled before `src/`; the test beside this file holds the copies equal.
+ */
+export const REPRO_DIR = "repro";
+export const SHARED_DIRS = ["tools", "data"];
+export const PREREG_FILE = "prereg.json";
+const STATUS_FILE = "PIPELINE-STATUS.md";
+const PAGE = "https://github.com/zernie/paperlint/blob/main/docs/rules/study/declare-sample.md";
+/** The one sentence every finding ends with: why the fields exist. */
+export const WHY = "Why: a study once screened its sample down to rules that are easy to judge — its labeller found 93 % of the items designed as borderline clear-cut — and nothing in its design made anyone state what share of the real population the sample covered or which screens removed which kinds of units.";
+/** A zod error option: `what` is the text a finding gives for the field, missing or malformed. */
+const field = (what) => ({
+    error: (iss) => iss.input === undefined
+        ? `is missing — add ${what}`
+        : `is not valid — it must be ${what}`,
+});
+/** Text that says something: a string with more than white space in it. */
+const text = (what) => z
+    .string(field(what))
+    .trim()
+    .min(1, { error: `is empty — write ${what}` });
+/** A whole number above 0. */
+const positive = (what) => z.number(field(what)).int(field(what)).positive(field(what));
+const POPULATION = z.object({
+    about: text("what the paper's claim is about, in the paper's own words (e.g. the rules written in agent instruction files of public repositories)"),
+    source: text("where the population's units come from — the census, crawl or registry, with its date"),
+    size: positive("the number of units in the population, a whole number above 0 (an estimate is fine; say how it was made in `source`)"),
+}, field("`population`: what the paper's claim is about (`about`), where its units come from (`source`) and how many there are (`size`)"));
+const STRATA = z.object({
+    by: text("the property the units are stratified by, e.g. rule type"),
+    values: z
+        .array(text("a value of the stratum"), field("the stratum's values, a list of names"))
+        .min(1, {
+        error: "is empty — list the stratum's values, at least one",
+    }),
+}, field("`strata`: the property the screens are counted by (`by`, e.g. rule type) and its values (`values`)"));
+const REMOVED_WHAT = "the number of candidates the screen removed in each declared stratum value, an object {<value>: <count>} with 0 where it removed none";
+const SCREEN = z.object({
+    name: text("what the screen keeps, as it was applied (e.g. judgeable from one code excerpt of at most 40 lines)"),
+    removed: z.record(z.string(), z
+        .number(field("a count, a whole number from 0"))
+        .int(field("a count, a whole number from 0"))
+        .nonnegative(field("a count, a whole number from 0")), field(REMOVED_WHAT)),
+}, field("a screen: `name` and `removed`"));
+const SCREENS = z.array(SCREEN, field("`screens`: one entry per screen applied between the population and the sample, each with `name` and `removed` — [] when none was"));
+const SHARE_WHAT = "the share of the population the sample can represent, a number from 0 to 1, or null with a `reason`";
+const COVERAGE = z.object({
+    share: z
+        .number(field(SHARE_WHAT))
+        .min(0, field(SHARE_WHAT))
+        .max(1, field(SHARE_WHAT))
+        .nullable(),
+    reason: text("why the share cannot be stated").optional(),
+    unreachable: z.array(text("a stratum or kind of unit"), field("the strata (or kinds of units) the sample cannot reach, a list of names — [] only when it reaches them all")),
+}, field("`coverage`: the share of the population the sample can represent (`share`, 0 to 1, or null with a `reason`) and the strata it cannot reach (`unreachable`)"));
+/** The answers to "is this what you meet in practice?"; any but the first needs a decision. */
+export const VERDICTS = ["representative", "partly", "not-representative"];
+const DECISION = z.object({
+    proceed: z.boolean(field("whether the study runs on this sample, true or false")),
+    by: text("who decided"),
+    why: text("why, in a sentence"),
+}, field("the decision taken after the verdict: `proceed` (true or false), `by` whom, and `why`"));
+const AUTHOR_CHECK = z.object({
+    who: text("who looked at the drawn units (a name or a role)"),
+    when: z.iso.date(field("the date of the check, YYYY-MM-DD")),
+    units_seen: positive("how many of the drawn units — the rules or cases drawn, not the items made from them — the author looked at, a whole number above 0"),
+    units_drawn: positive("how many units the sample drew"),
+    verdict: z.enum(VERDICTS, field(`the author's answer to "is this what you meet in practice?" — one of ${VERDICTS.join(", ")}`)),
+    decision: DECISION.optional(),
+}, field("`author_check`: who looked at the drawn units before the run (`who`), when (`when`), how many of how many (`units_seen`, `units_drawn`), and what they said (`verdict`)"));
+/** The declaration a `prereg.json` must carry. Every other key of the file is the author's. */
+export const PREREG = z.object({
+    population: POPULATION,
+    strata: STRATA,
+    screens: SCREENS,
+    coverage: COVERAGE,
+    author_check: AUTHOR_CHECK,
+}, field("a JSON object holding `population`, `strata`, `screens`, `coverage` and `author_check`"));
+/** A zod path as it is written in the file: `screens[0].removed.vague`. */
+export const pathText = (path) => path
+    .map((k) => (typeof k === "number" ? `[${String(k)}]` : `.${String(k)}`))
+    .join("")
+    .replace(/^\./u, "");
+/** The values that occur more than once in `values`, each once. */
+const repeated = (values) => [
+    ...new Set(values.filter((v, i) => values.indexOf(v) !== i)),
+];
+/** What one screen's `removed` lacks and holds beyond the declared strata. */
+const removedProblems = (removed, i, values) => [
+    ...values
+        .filter((v) => !Object.hasOwn(removed, v))
+        .map((v) => ({
+        at: `screens[${String(i)}].removed.${v}`,
+        text: `is missing — every screen states how many candidates it removed in each declared stratum value (${values.join(", ")}), 0 where it removed none`,
+    })),
+    ...Object.keys(removed)
+        .filter((k) => !values.includes(k))
+        .map((k) => ({
+        at: `screens[${String(i)}].removed.${k}`,
+        text: `is not a declared stratum value — \`strata.values\` declares ${values.join(", ")}; add it there or count it under one of them`,
+    })),
+];
+/** A problem when `when` holds, else none. */
+const problemIf = (when, at, text) => (when ? [{ at, text }] : []);
+/** The author's check against itself: no more units seen than drawn, a doubtful verdict decided. */
+const checkProblems = (check) => [
+    ...problemIf(check.units_seen > check.units_drawn, "author_check.units_seen", `is ${String(check.units_seen)}, more than the ${String(check.units_drawn)} units drawn (\`units_drawn\`)`),
+    ...problemIf(check.verdict !== "representative" && check.decision === undefined, "author_check.decision", `is missing — the verdict is «${check.verdict}», and a doubtful verdict with no recorded decision is how a sample the author doubted gets run anyway: add \`proceed\` (true or false), \`by\` whom and \`why\``),
+];
+/** What a schema of one field cannot see: how the fields of a parsed declaration relate. */
+export function crossProblems(p) {
+    const values = p.strata.values;
+    return [
+        ...repeated(values).map((v) => ({
+            at: "strata.values",
+            text: `names «${v}» more than once — each stratum value once`,
+        })),
+        ...p.screens.flatMap((s, i) => removedProblems(s.removed, i, values)),
+        ...problemIf(p.coverage.share === null && p.coverage.reason === undefined, "coverage.reason", "is missing — `share` is null, so say why the share cannot be stated"),
+        ...problemIf(p.coverage.share === 1 && p.coverage.unreachable.length > 0, "coverage.unreachable", `contradicts \`share\` 1 — a sample that cannot reach ${p.coverage.unreachable.map((u) => `«${u}»`).join(", ")} does not represent the whole population: lower \`share\`, or empty the list`),
+        ...checkProblems(p.author_check),
+    ];
+}
+/** Everything wrong with the parsed JSON of one `prereg.json`, in the file's field order. */
+export function judgePrereg(data) {
+    const parsed = PREREG.safeParse(data);
+    return parsed.success
+        ? crossProblems(parsed.data)
+        : parsed.error.issues.map((i) => ({
+            at: pathText(i.path),
+            text: i.message,
+        }));
+}
+/** What `JSON.parse` says about the text it refused. */
+const Thrown = z
+    .object({ message: z.string() })
+    .catch({ message: "unparseable" });
+/** The problems of one `prereg.json` whose text is `source`: a parse failure, or the judgement. */
+export function preregProblems(source) {
+    const parsed = (() => {
+        try {
+            const data = JSON.parse(source);
+            return { data };
+        }
+        catch (e) {
+            return { why: Thrown.parse(e).message };
+        }
+    })();
+    return "why" in parsed
+        ? [
+            {
+                at: "",
+                text: `does not parse as JSON (${parsed.why}) — there is no declaration to read`,
+            },
+        ]
+        : judgePrereg(parsed.data);
+}
+/** The one text a problem in the file `file` (relative to the paper) is reported with. */
+export const problemMessage = (file, p) => [
+    p.at === ""
+        ? `\`${file}\` ${p.text}.`
+        : `\`${file}\`: \`${p.at}\` ${p.text}.`,
+    WHY,
+    `Rule study/declare-sample: ${PAGE}`,
+].join(" ");
+/**
+ * The `prereg.json` of every study folder at the top of `<paperDir>/repro/`, relative to the paper:
+ * every folder there but the shared ones, whatever its name — a study folder misnamed is
+ * `repro/allowed-files-only`'s finding, and its pre-registration is still judged here.
+ */
+export function preregFiles(paperDir) {
+    const repro = join(paperDir, REPRO_DIR);
+    return existsSync(repro) && statSync(repro).isDirectory()
+        ? readdirSync(repro, { withFileTypes: true })
+            // stat, not the entry's own type: a study folder linked into repro/ is a folder to
+            // repro/allowed-files-only too, and must not escape the check by being a link
+            .filter((e) => !SHARED_DIRS.includes(e.name) &&
+            (statSync(join(repro, e.name), {
+                throwIfNoEntry: false,
+            })?.isDirectory() ??
+                false))
+            .map((e) => `${REPRO_DIR}/${e.name}/${PREREG_FILE}`)
+            .filter((rel) => existsSync(join(paperDir, rel)))
+            .sort()
+        : [];
+}
+/** A `prereg.json` that is not a regular file (a folder, a socket): reading it would abort the run. */
+const NOT_A_FILE = [
+    {
+        at: "",
+        text: "is not a file — the declaration is one JSON file; move what the folder holds elsewhere",
+    },
+];
+/** Every finding for the paper folder `paperDir`, one text each. */
+export const paperFindings = (paperDir) => preregFiles(paperDir).flatMap((rel) => {
+    const path = join(paperDir, rel);
+    const problems = statSync(path).isFile()
+        ? preregProblems(readFileSync(path, "utf8"))
+        : NOT_A_FILE;
+    return problems.map((p) => problemMessage(rel, p));
+});
+export default {
+    rules: {
+        "declare-sample": {
+            meta: {
+                type: "problem",
+                docs: {
+                    description: "every study's prereg.json declares its population, the screens and what each removed per stratum, the sample's coverage, and the author's check of the drawn units",
+                    url: PAGE,
+                },
+                schema: [],
+                messages: { coverage: "{{text}}" },
+            },
+            create(context) {
+                if (basename(context.filename) !== STATUS_FILE)
+                    return {};
+                return {
+                    root() {
+                        const at = context.sourceCode.getLocFromIndex(0);
+                        paperFindings(dirname(context.filename)).forEach((t) => {
+                            context.report({
+                                loc: { start: at, end: at },
+                                messageId: "coverage",
+                                data: { text: t },
+                            });
+                        });
+                    },
+                };
+            },
+        },
+    },
+};
+//# sourceMappingURL=prereg-coverage.js.map

package/dist/eslint-rules/prereg-coverage.js.map

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

package/dist/folder-layout-hook.d.ts

@@ -0,0 +1,21 @@
+import { type FolderLayoutDeps } from "./folder-layout-rule.ts";
+import type { Files } from "./ports/files.ts";
+/** What Claude Code reads from a PreToolUse hook's stdout to refuse the call, with the reason. */
+export interface HookOutput {
+    readonly hookSpecificOutput: {
+        readonly hookEventName: "PreToolUse";
+        readonly permissionDecision: "deny";
+        readonly permissionDecisionReason: string;
+    };
+}
+/** The target file's absolute path from the payload; null when there is none to read. */
+export declare function writtenPath(payload: unknown): string | null;
+/**
+ * The nearest folder above `file` holding `PIPELINE-STATUS.md`, up to the root; null when none, and
+ * null for anything under a folder named `extra/`, which lint never reads: an archived paper kept
+ * there carries its own status file and is not a paper to hold to the layout.
+ */
+export declare function paperFolderOf(file: string, files: Files): string | null;
+/** The hook: the payload of an Edit or a Write in, Claude Code's refusal out, or null to allow. */
+export declare function folderLayoutHook(payload: unknown, deps: FolderLayoutDeps): HookOutput | null;
+//# sourceMappingURL=folder-layout-hook.d.ts.map

package/dist/folder-layout-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-layout-hook.d.ts","sourceRoot":"","sources":["../src/folder-layout-hook.ts"],"names":[],"mappings":"AA8CA,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAM9C,kGAAkG;AAClG,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,kBAAkB,EAAE;QAC3B,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAC;QACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;QACpC,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;KAC3C,CAAC;CACH;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAO3D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CASvE;AAmCD,mGAAmG;AACnG,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,gBAAgB,GACrB,UAAU,GAAG,IAAI,CAenB"}

package/dist/folder-layout-hook.js

@@ -0,0 +1,117 @@
+/**
+ * The `paper-folder-layout` hook — `paper/allowed-files-only` and `repro/allowed-files-only` BEFORE a file is
+ * created, not at the next lint. PreToolUse on `Edit|Write|MultiEdit` (`plugin/hooks/hooks.json`):
+ * when the file about to be written does not exist yet and would add an entry the layout does not
+ * allow — at a paper folder's root, or at the top of its `repro/` — the call is denied, and the
+ * reason is the rule's own message: where the entry goes, and the layout drawn. The agent writes it
+ * where it belongs instead, in the same turn.
+ *
+ * ── WHAT IT NEVER BLOCKS ─────────────────────────────────────────────────────────
+ * - A file that already exists. Editing is never refused, wherever the file is: a paper whose
+ *   folder predates the layout keeps working, and the rule reports what is out of place.
+ * - A new file inside an entry that already exists, even one the layout does not allow: the entry is
+ *   not new, and the rule reports it once, by name. Only a NEW entry is refused.
+ * - Anything outside a paper folder (no `PIPELINE-STATUS.md` above it).
+ * A new study folder in `repro/` is created with its `README.md` first: any other first file in it
+ * is refused with `repro/allowed-files-only`'s "without a README.md" message.
+ *
+ * ── WHAT IT CANNOT SEE ───────────────────────────────────────────────────────────
+ * A shell command (`mv`, `cp`, a script writing files) is not an Edit or a Write, and this hook never
+ * sees it. The guarantee is the lint: both rules fail `paperlint lint`, in CI, whatever wrote the
+ * entry. The hook only saves the round trip. It does not read the paper's `rules` either: a paper
+ * that switched a layout rule off is still refused a new stray entry.
+ *
+ * ── ONE FUNCTION PER RULE, NOT TWO LISTS ─────────────────────────────────────────
+ * The texts are `strayTexts` (`src/folder-layout-rule.ts`) and `reproTexts`
+ * (`src/repro-layout-rule.ts`), the functions the rules report with.
+ *
+ * ── WHY IT IS NOT A VIGILES PROGRAM LIKE ITS NEIGHBOURS (measured 2026-10-12, vigiles 38) ──────
+ * A shipped `.hook.mjs` may import nothing but `vigiles/hook` (`checkHookImports`), so it cannot call
+ * this package's function; its only way to a tool is `run()`, whose output reaches stderr and never
+ * the hook's answer (`paper-status-gates.hook.mjs` measured that); and a `provide()` command runs
+ * before the reaction without the event, so it cannot know which file is written. Each of the three
+ * would mean a second copy of the layout. So `paperlint hook paper-folder-layout` runs this module
+ * in-process (`runHook`, src/cli.ts), behind the same wiring command as the other hooks, which is
+ * what `paperlint init` merges and `paperlint doctor` reads.
+ *
+ * ── THE CHEAP FIRST STEP ─────────────────────────────────────────────────────────
+ * Before reading any settings or listing any folder, the hook looks for the nearest folder above the
+ * file that holds `PIPELINE-STATUS.md` — the file every paper has and the rules are reported on — with
+ * one `isFile` per ancestor and nothing else: no git, no lint. No such folder: no output.
+ */
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { callerPath } from "./caller-path.js";
+import { ESCAPE_HATCH } from "./domain/paper-layout.js";
+import { README, REPRO_DIR, isStudyName } from "./domain/repro-layout.js";
+import { fieldOf } from "./domain/record.js";
+import { strayTexts } from "./folder-layout-rule.js";
+import { reproTexts } from "./repro-layout-rule.js";
+/** The file every paper folder has, and the rules are reported on. */
+const STATUS_FILE = "PIPELINE-STATUS.md";
+/** The target file's absolute path from the payload; null when there is none to read. */
+export function writtenPath(payload) {
+    const input = fieldOf(payload, "tool_input");
+    const raw = fieldOf(input, "file_path") ?? fieldOf(input, "notebook_path");
+    if (typeof raw !== "string" || raw === "")
+        return null;
+    if (isAbsolute(raw))
+        return resolve(raw);
+    const cwd = fieldOf(payload, "cwd");
+    return typeof cwd === "string" && isAbsolute(cwd) ? resolve(cwd, raw) : null;
+}
+/**
+ * The nearest folder above `file` holding `PIPELINE-STATUS.md`, up to the root; null when none, and
+ * null for anything under a folder named `extra/`, which lint never reads: an archived paper kept
+ * there carries its own status file and is not a paper to hold to the layout.
+ */
+export function paperFolderOf(file, files) {
+    // The same reach as lint's `**/extra/` ignore: a folder named extra/ anywhere above the file.
+    if (dirname(file).split(sep).includes(ESCAPE_HATCH))
+        return null;
+    const up = (dir) => {
+        if (files.isFile(callerPath(join(dir, STATUS_FILE))))
+            return dir;
+        const parent = dirname(dir);
+        return parent === dir ? null : up(parent);
+    };
+    return up(dirname(file));
+}
+/** The entry `segments` would add under `dir`, as the layout judges it; null when it exists. */
+const newEntry = (dir, [name = "", ...below], deps) => deps.listDir(callerPath(dir)).includes(name)
+    ? null
+    : { name, kind: below.length > 0 ? "dir" : "file" };
+/** Why creating `segments` (relative to the paper folder `dir`) breaks the layout; null when not. */
+function refusal(dir, segments, deps) {
+    const atRoot = newEntry(dir, segments, deps);
+    const [rootText] = atRoot === null ? [] : strayTexts(dir, [atRoot], deps.files);
+    if (rootText !== undefined)
+        return rootText;
+    const [top, ...inRepro] = segments;
+    if (top !== REPRO_DIR || inRepro.length === 0)
+        return null;
+    const entry = newEntry(join(dir, REPRO_DIR), inRepro, deps);
+    // A new study folder starts with its README.md: that write is what makes it complete.
+    if (entry === null ||
+        (isStudyName(entry.name) && inRepro.slice(1).join("/") === README))
+        return null;
+    const [text] = reproTexts(dir, [entry], deps.files);
+    return text ?? null;
+}
+/** The hook: the payload of an Edit or a Write in, Claude Code's refusal out, or null to allow. */
+export function folderLayoutHook(payload, deps) {
+    const file = writtenPath(payload);
+    const dir = file === null ? null : paperFolderOf(file, deps.files);
+    if (file === null || dir === null || deps.files.isFile(callerPath(file)))
+        return null;
+    const reason = refusal(dir, relative(dir, file).split(/[\\/]/), deps);
+    return reason === null
+        ? null
+        : {
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: reason,
+            },
+        };
+}
+//# sourceMappingURL=folder-layout-hook.js.map

package/dist/folder-layout-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-layout-hook.js","sourceRoot":"","sources":["../src/folder-layout-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAyB,MAAM,yBAAyB,CAAC;AAE5E,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,sEAAsE;AACtE,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAWzC,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;IAC3E,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACpC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,KAAY;IACtD,8FAA8F;IAC9F,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,EAAE,GAAG,CAAC,GAAW,EAAiB,EAAE;QACxC,IAAI,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACjE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC,CAAC;IACF,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED,gGAAgG;AAChG,MAAM,QAAQ,GAAG,CACf,GAAW,EACX,CAAC,IAAI,GAAG,EAAE,EAAE,GAAG,KAAK,CAAoB,EACxC,IAAsB,EAC2C,EAAE,CACnE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC1C,CAAC,CAAC,IAAI;IACN,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;AAExD,qGAAqG;AACrG,SAAS,OAAO,CACd,GAAW,EACX,QAA2B,EAC3B,IAAsB;IAEtB,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC7C,MAAM,CAAC,QAAQ,CAAC,GACd,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/D,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,MAAM,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,QAAQ,CAAC;IACnC,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5D,sFAAsF;IACtF,IACE,KAAK,KAAK,IAAI;QACd,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC;QAElE,OAAO,IAAI,CAAC;IACd,MAAM,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACpD,OAAO,IAAI,IAAI,IAAI,CAAC;AACtB,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,gBAAgB,CAC9B,OAAgB,EAChB,IAAsB;IAEtB,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACnE,IAAI,IAAI,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IACtE,OAAO,MAAM,KAAK,IAAI;QACpB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC;YACE,kBAAkB,EAAE;gBAClB,aAAa,EAAE,YAAY;gBAC3B,kBAAkB,EAAE,MAAM;gBAC1B,wBAAwB,EAAE,MAAM;aACjC;SACF,CAAC;AACR,CAAC"}