paperlint 3.2.0 → 4.1.0

package/src/rules-config.ts

@@ -39,11 +39,40 @@ export interface RuleBlock {
   readonly rules: Readonly<Record<string, RuleEntry>>;
 }
 
+/**
+ * A plugin as a config block registers it, typed to what paperlint reads of it: its rules, and the
+ * languages it brings (`tex` brings LaTeX).
+ */
+export interface ConfigPlugin {
+  readonly rules?: Readonly<Record<string, unknown>>;
+  readonly languages?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * An ESLint config block as paperlint builds and reads one. Not `Linter.Config`: ESLint types a
+ * plugin's rule as one that runs on ANY language, and paperlint's rules are written for the language
+ * they read (LaTeX, markdown), so none of them is assignable to it. ESLint checks a block when it
+ * loads it; `eslintConfig` in cli.ts is the one place these blocks become `Linter.Config`.
+ */
+export interface ConfigBlock {
+  readonly name?: string;
+  readonly basePath?: string;
+  readonly files?: readonly (string | readonly string[])[];
+  readonly ignores?: readonly string[];
+  readonly plugins?: Readonly<Record<string, ConfigPlugin>>;
+  readonly language?: string;
+  readonly languageOptions?: Readonly<Record<string, unknown>>;
+  readonly linterOptions?: Readonly<Record<string, unknown>>;
+  readonly rules?: Readonly<Record<string, unknown>>;
+}
+
 export type Parsed<T> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly error: string };
 
-const SEVERITIES: readonly unknown[] = ["off", "warn", "error", 0, 1, 2];
+const SEVERITIES: readonly Severity[] = ["off", "warn", "error", 0, 1, 2];
+const isSeverity = (v: unknown): v is Severity =>
+  SEVERITIES.some((s) => s === v);
 
 const BLOCK_KEYS = new Set(["files", "ignores", "rules"]);
 
@@ -61,9 +90,10 @@ const isStringList = (v: unknown): v is string[] =>
 
 /** A severity, or `[severity, ...options]`. */
 function parseEntry(v: unknown): RuleEntry | null {
-  const sev: unknown = Array.isArray(v) ? v[0] : v;
-  if (!SEVERITIES.includes(sev)) return null;
-  return v as RuleEntry;
+  const entry: readonly unknown[] = Array.isArray(v) ? v : [v];
+  const [sev, ...options] = entry;
+  if (!isSeverity(sev)) return null;
+  return Array.isArray(v) ? [sev, ...options] : sev;
 }
 
 /**
@@ -105,8 +135,8 @@ function badGlobs(o: Record<string, unknown>, at: string): string | null {
 
 /** The block's `files`/`ignores`, present only when given. */
 const globsOf = (o: Record<string, unknown>) => ({
-  ...(o["files"] ? { files: o["files"] as string[] } : {}),
-  ...(o["ignores"] ? { ignores: o["ignores"] as string[] } : {}),
+  ...(isStringList(o["files"]) ? { files: o["files"] } : {}),
+  ...(isStringList(o["ignores"]) ? { ignores: o["ignores"] } : {}),
 });
 
 const isRecord = (v: unknown): v is Record<string, unknown> =>
@@ -182,16 +212,15 @@ export function parseRuleBlocks(
  * `foreign` (a dependency's plugin, such as `@eslint/markdown`) are not paperlint's and are skipped.
  */
 export function shippedRuleIds(
-  config: readonly unknown[],
+  config: readonly ConfigBlock[],
   foreign: readonly unknown[],
 ): Set<string> {
   const ids = new Set<string>();
   for (const block of config) {
-    const plugins = (block as { plugins?: Record<string, unknown> }).plugins;
-    for (const [name, plugin] of Object.entries(plugins ?? {})) {
+    for (const [name, plugin] of Object.entries(block.plugins ?? {})) {
       if (foreign.includes(plugin)) continue;
-      const rules = (plugin as { rules?: Record<string, unknown> }).rules;
-      for (const rule of Object.keys(rules ?? {})) ids.add(`${name}/${rule}`);
+      for (const rule of Object.keys(plugin.rules ?? {}))
+        ids.add(`${name}/${rule}`);
     }
   }
   return ids;

package/src/tex-requirements.harness.ts

@@ -16,22 +16,12 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import ts from "typescript";
-import { z } from "zod";
+import { join } from "node:path";
 import { createChecker } from "../lib/check.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-const VENUES = join(
-  HERE,
-  "..",
-  "skills",
-  "submit-paper",
-  "references",
-  "venues",
-);
 const R = await import("./tex-requirements.ts");
+const { parseTemplate } = await import("./adapters/latex/index.ts");
+const VENUES = (await import("./package-dirs.ts")).presetsDir();
 
 const check = createChecker();
 const throws = (fn: () => unknown): string => {
@@ -70,15 +60,15 @@ check(
   "cm-super" in base.packages,
 );
 
-// The whole profile, parsed the way the other harnesses read these files — never a line of text.
-const TemplateField = z.object({ template: z.unknown().optional() });
-const templateOf = (v: string): unknown =>
-  TemplateField.parse(
-    ts.parseConfigFileTextToJson(
-      v,
-      readFileSync(join(VENUES, `${v}.jsonc`), "utf8"),
-    ).config,
-  ).template;
+// The class each profile's template names, as the parser reads it — never a line of text.
+const presetOf = (v: string) =>
+  R.parsePreset(
+    readFileSync(join(VENUES, `${v}.jsonc`), "utf8"),
+    `${v}.jsonc`,
+    VENUES,
+  );
+const templateOf = (v: string): string | undefined =>
+  parseTemplate(presetOf(v).template ?? "")?.cls;
 const acm = venues.filter((v) => templateOf(v) === "acmart");
 check(
   "at least one acmart venue is shipped (else the next checks see nothing)",
@@ -108,7 +98,7 @@ for (const v of acm) {
 // declares the template's packages, so this holds by construction; the check stays for any two
 // standalone presets that name the same template.
 const byTemplate = new Map<unknown, string[]>();
-for (const v of venues) {
+for (const v of venues.filter((x) => presetOf(x).extends === null)) {
   const t = templateOf(v);
   byTemplate.set(t, [...(byTemplate.get(t) ?? []), v]);
 }

package/src/tex-requirements.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { loadTypescript } from "./tex-requirements.ts";
+
+test("loadTypescript refuses a module without the two functions a profile is read with", () => {
+  assert.throws(
+    () => loadTypescript(() => ({})),
+    /loaded without parseConfigFileTextToJson/,
+  );
+});
+
+test("loadTypescript hands back what `require` loaded when it has them", () => {
+  const ts = {
+    parseConfigFileTextToJson: () => ({ config: {} }),
+    flattenDiagnosticMessageText: () => "",
+  };
+  assert.equal(
+    loadTypescript(() => ts),
+    ts,
+  );
+});

package/src/tex-requirements.ts

@@ -16,8 +16,8 @@
  * `TexRequirements` and never looks at the text again; a malformed profile throws with the path
  * of every violation, it is never read as "no packages".
  *
- * Where the profiles live is answered by `packageVenuesDir()` in consumer.mjs — the one module
- * allowed to know where this package is installed (rule 10).
+ * Where the profiles live is answered by `presetsDir()` in `package-dirs.ts` — the one module
+ * allowed to know where this package's data is installed (rule 10).
  */
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { readFileSync, readdirSync } from "node:fs";
@@ -25,8 +25,9 @@ import { createRequire } from "node:module";
 import { join } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import Ajv from "ajv";
-import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { presetsDir } from "./package-dirs.ts";
 import { CONFIG_FILE } from "#lib/paper-config";
+import { fieldOf } from "./domain/record.ts";
 
 /** CTAN package name → the names that prove it is installed. */
 export type PackageProofs = Readonly<Record<string, readonly string[]>>;
@@ -51,15 +52,37 @@ const PROFILE_EXT = ".jsonc";
 
 export const NO_REQUIREMENTS: TexRequirements = { packages: {}, tools: {} };
 
-type Ts = typeof import("typescript");
-let ts: Ts | null = null;
+/** The two functions of `typescript` a profile is read with. */
+type TsJsonc = Pick<
+  typeof import("typescript"),
+  "parseConfigFileTextToJson" | "flattenDiagnosticMessageText"
+>;
+
+const isTsJsonc = (m: unknown): m is TsJsonc =>
+  typeof fieldOf(m, "parseConfigFileTextToJson") === "function" &&
+  typeof fieldOf(m, "flattenDiagnosticMessageText") === "function";
+
+/** `typescript` as `load` returns it — `require` answers `any` — checked for the two functions used. */
+export function loadTypescript(load: (id: string) => unknown): TsJsonc {
+  const m = load("typescript");
+  if (!isTsJsonc(m))
+    throw new Error(
+      "`typescript` loaded without parseConfigFileTextToJson — reinstall this package",
+    );
+  return m;
+}
+
+let ts: TsJsonc | null = null;
 /** TypeScript is loaded only when a profile is read: `paperlint lint` never pays for it. */
-function typescript(): Ts {
-  ts ??= createRequire(import.meta.url)("typescript") as Ts;
+function typescript(): TsJsonc {
+  ts ??= loadTypescript(createRequire(import.meta.url));
   return ts;
 }
 
 type Validate = ReturnType<Ajv.Ajv["compile"]>;
+/** `PresetJson` is the TypeScript side of the profile schema: a document the schema accepts is one. */
+const matchesSchema = (v: unknown, validate: Validate): v is PresetJson =>
+  validate(v) === true;
 const validators = new Map<string, Validate>();
 function validatorFor(dir: string): Validate {
   const known = validators.get(dir);
@@ -125,6 +148,13 @@ export const NO_FORMAT: VenueFormat = {
   kinds: new Map(),
 };
 
+/** A section a venue requires: its exact title, and whether it must close the paper. */
+export interface RequiredSection {
+  readonly title: string;
+  /** "last": after every section of the body; null: anywhere. */
+  readonly position: "last" | null;
+}
+
 /**
  * One preset FILE, parsed — before its `extends` chain is resolved (`src/presets.ts` does that).
  * A preset is a venue or a template family: `{ extends?, name?, template?, format?, tex?, rules? }`.
@@ -134,7 +164,12 @@ export interface PresetFile {
   readonly extends: string | null;
   /** A display name for messages; the file name otherwise. */
   readonly name: string | null;
+  /** The `\\documentclass` the venue's template uses, as the file spells it; null when it names none. */
   readonly template: string | null;
+  /** Other names the venue goes by in a paper's text; empty when the file names none. */
+  readonly aliases: readonly string[];
+  /** Sections the venue requires; null when the file names none (a child's list replaces its parent's). */
+  readonly requiredSections: readonly RequiredSection[] | null;
   /** Null when the file declares no `tex` block (allowed only with `extends`). */
   readonly tex: TexRequirements | null;
   readonly format: VenueFormat;
@@ -165,6 +200,11 @@ interface PresetJson {
   readonly extends?: string;
   readonly name?: string;
   readonly template?: string;
+  readonly aliases?: readonly string[];
+  readonly required_sections?: readonly {
+    readonly title: string;
+    readonly position?: "last";
+  }[];
   /** The schema requires `packages` in a `tex` block; `tools` is optional. */
   readonly tex?: Pick<TexRequirements, "packages"> &
     Partial<Pick<TexRequirements, "tools">>;
@@ -202,6 +242,14 @@ function formatOf(j: FormatJson = {}): VenueFormat {
   };
 }
 
+/** A preset's `required_sections`, or null when it names none. */
+const sectionsOf = (
+  r: PresetJson["required_sections"],
+): readonly RequiredSection[] | null =>
+  r === undefined
+    ? null
+    : r.map((x) => ({ title: x.title, position: orNull(x.position) }));
+
 /**
  * The text of one preset file → the typed file, or an Error naming every problem. The ONE parser
  * of a preset: the toolchain reads its `tex`, the venue rules its `format`, the config its `rules`.
@@ -213,7 +261,7 @@ function formatOf(j: FormatJson = {}): VenueFormat {
 export function parsePreset(
   text: string,
   file: string,
-  dir: string = packageVenuesDir(),
+  dir: string = presetsDir(),
 ): PresetFile {
   const parsed = typescript().parseConfigFileTextToJson(file, text);
   const config: unknown = parsed.config;
@@ -223,15 +271,17 @@ export function parsePreset(
       `${file}: not valid JSONC — ${typescript().flattenDiagnosticMessageText(error.messageText, " ")}`,
     );
   const validate = validatorFor(dir);
-  if (!validate(config))
+  if (!matchesSchema(config, validate))
     throw new Error(
       `${file} does not match ${SCHEMA_FILE}:\n  ${violations(file, validate).join("\n  ")}`,
     );
-  const j = config as PresetJson;
+  const j = config;
   return {
     extends: orNull(j.extends),
     name: orNull(j.name),
     template: orNull(j.template),
+    aliases: j.aliases ?? [],
+    requiredSections: sectionsOf(j.required_sections),
     tex: j.tex ? { packages: j.tex.packages, tools: j.tex.tools ?? {} } : null,
     format: formatOf(j.format),
     rules: j.rules ?? {},
@@ -242,7 +292,7 @@ export function parsePreset(
 export function parseProfile(
   text: string,
   file: string,
-  dir: string = packageVenuesDir(),
+  dir: string = presetsDir(),
 ): TexRequirements {
   return parsePreset(text, file, dir).tex ?? NO_REQUIREMENTS;
 }
@@ -264,7 +314,7 @@ function readProfile(dir: string, file: string): TexRequirements {
 }
 
 /** The venues that have a profile — every `.jsonc` in the directory except the base set. */
-export function venueNames(dir: string = packageVenuesDir()): string[] {
+export function venueNames(dir: string = presetsDir()): string[] {
   return readdirSync(dir)
     .filter((f) => f.endsWith(PROFILE_EXT) && f !== BASE_PROFILE)
     .map((f) => f.slice(0, -PROFILE_EXT.length))
@@ -302,7 +352,7 @@ export function packageNames(tex: TexRequirements): string[] {
  */
 export function requirementsFor(
   preset: { readonly label: string; readonly tex: TexRequirements } | null,
-  dir: string = packageVenuesDir(),
+  dir: string = presetsDir(),
 ): PaperRequirements {
   const base = readProfile(dir, BASE_PROFILE);
   return preset === null
@@ -322,7 +372,7 @@ export function requirementsFor(
  * builds any paper.
  */
 export function declaredUnion(
-  dir: string = packageVenuesDir(),
+  dir: string = presetsDir(),
   extra: readonly TexRequirements[] = [],
 ): {
   readonly tex: TexRequirements;