paperlint 6.1.0 → 6.2.0

package/src/domain/talk.ts

@@ -0,0 +1,274 @@
+/**
+ * THE TALK — what a venue asks a presenter to send, and what one paper declares about its talk.
+ *
+ * paperlint does not make a talk. It judges the finished files (the video, the one-slide image, the
+ * captions) against the venue's numbers: however the video was made, the venue limits the file.
+ *
+ *   venue preset `talk`    the modes the venue allows, what each mode owes, the slot of each kind
+ *                          of paper, the video's format, the one-slide's size
+ *   paper `talk`           the mode this paper presents in, the folder the files are in, and their
+ *                          names when they are not the defaults
+ */
+import { err, ok, type Result } from "./result.ts";
+import { fieldOf, isRecord } from "./record.ts";
+
+/** How a paper is presented. */
+export type TalkMode = "in-person" | "remote-video" | "remote-live";
+export const TALK_MODES: readonly TalkMode[] = [
+  "in-person",
+  "remote-video",
+  "remote-live",
+];
+
+/** A file a mode can owe. */
+export type TalkArtifact =
+  "video" | "one-slide" | "captions" | "slides-pdf" | "poster";
+export const TALK_ARTIFACTS: readonly TalkArtifact[] = [
+  "video",
+  "one-slide",
+  "captions",
+  "slides-pdf",
+  "poster",
+];
+
+/** What one mode owes. */
+export interface TalkObligation {
+  readonly required: readonly TalkArtifact[];
+  readonly optional: readonly TalkArtifact[];
+}
+
+/** The talk slot of one kind of paper, in seconds. */
+export interface TalkSlot {
+  /** The whole slot, talk and questions. Informational. */
+  readonly slotS: number;
+  /** The shortest talk the venue asks for; null when it sets no floor. */
+  readonly talkSMin: number | null;
+  /** The longest talk. */
+  readonly talkSMax: number;
+  /** The questions' share. Informational. */
+  readonly qaS: number | null;
+}
+
+/** A pixel size. */
+export interface PixelSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** The venue's limits on the video file. Every field null when the venue says nothing of it. */
+export interface VideoLimits {
+  readonly container: "mp4" | null;
+  readonly minHeightPx: number | null;
+  readonly maxBytes: number | null;
+  readonly captions: "required" | "optional" | null;
+}
+
+/** A venue preset's `talk` block, parsed. */
+export interface VenueTalk {
+  /** The modes the venue allows; empty when the block names none. */
+  readonly modes: readonly TalkMode[];
+  readonly artifacts: ReadonlyMap<TalkMode, TalkObligation>;
+  /** Slots by paper kind — the names of `format.kinds`. */
+  readonly kinds: ReadonlyMap<string, TalkSlot>;
+  readonly video: VideoLimits;
+  /** The one-slide image's size; null when the venue does not state one. */
+  readonly oneSlide: PixelSize | null;
+}
+
+/** The artifact → the file name it is looked for under, in the talk folder. */
+export type TalkFiles = Readonly<Record<TalkArtifact, string>>;
+
+/** The default talk folder, relative to the paper. */
+export const DEFAULT_TALK_DIR = "talk";
+
+/** The file each artifact is looked for under, unless the paper names another. */
+export const DEFAULT_TALK_FILES: TalkFiles = {
+  video: "talk.mp4",
+  "one-slide": "one-slide.png",
+  captions: "talk.srt",
+  "slides-pdf": "slides.pdf",
+  poster: "poster.pdf",
+};
+
+/** A paper's `talk` key, parsed. */
+export interface PaperTalk {
+  readonly mode: TalkMode;
+  /** The talk folder, relative to the paper. */
+  readonly dir: string;
+  readonly files: TalkFiles;
+  /** The one-slide's size when the paper states it (the venue did not); null otherwise. */
+  readonly oneSlide: PixelSize | null;
+}
+
+// ── measurements the rules judge ──────────────────────────────────────────────────────────
+
+/** What the video file says about itself. */
+export interface VideoProbe {
+  /** The container's duration (movie header), in seconds. */
+  readonly durationS: number;
+  /** The first audio track's duration, in seconds; null when the file has no audio track. */
+  readonly audioS: number | null;
+  /** The first video track's height in pixels; null when the file has no video track. */
+  readonly heightPx: number | null;
+  readonly widthPx: number | null;
+  /** The file's brands (ftyp): `isom`, `mp41`… for MP4, `qt  ` for QuickTime. */
+  readonly brands: readonly string[];
+}
+
+/** One caption cue, in seconds. */
+export interface Cue {
+  readonly startS: number;
+  readonly endS: number;
+}
+
+// ── the preset's `talk` block, as the schema admits it ───────────────────────────────────
+
+/** A preset's `talk` block after `venue-profile.schema.json` accepted it. */
+export interface VenueTalkJson {
+  readonly modes?: readonly TalkMode[];
+  readonly artifacts?: Readonly<
+    Partial<
+      Record<
+        TalkMode,
+        {
+          readonly required: readonly TalkArtifact[];
+          readonly optional?: readonly TalkArtifact[];
+        }
+      >
+    >
+  >;
+  readonly kinds?: Readonly<
+    Record<
+      string,
+      {
+        readonly slot_s: number;
+        readonly talk_s_min?: number;
+        readonly talk_s_max: number;
+        readonly qa_s?: number;
+      }
+    >
+  >;
+  readonly video?: {
+    readonly container?: "mp4";
+    readonly min_height_px?: number;
+    readonly max_bytes?: number;
+    readonly captions?: "required" | "optional";
+  };
+  readonly one_slide?: {
+    readonly width_px: number;
+    readonly height_px: number;
+  };
+}
+
+type ArtifactsJson = NonNullable<VenueTalkJson["artifacts"]>;
+type KindsJson = NonNullable<VenueTalkJson["kinds"]>;
+
+const artifactsOf = (j: ArtifactsJson): ReadonlyMap<TalkMode, TalkObligation> =>
+  new Map(
+    TALK_MODES.flatMap((mode) => {
+      const o = j[mode];
+      return o === undefined
+        ? []
+        : [[mode, { required: o.required, optional: o.optional ?? [] }]];
+    }),
+  );
+
+const kindsOf = (j: KindsJson): ReadonlyMap<string, TalkSlot> =>
+  new Map(
+    Object.entries(j).map(([name, k]) => [
+      name,
+      {
+        slotS: k.slot_s,
+        talkSMin: k.talk_s_min ?? null,
+        talkSMax: k.talk_s_max,
+        qaS: k.qa_s ?? null,
+      },
+    ]),
+  );
+
+const videoOf = (v: VenueTalkJson["video"] = {}): VideoLimits => ({
+  container: v.container ?? null,
+  minHeightPx: v.min_height_px ?? null,
+  maxBytes: v.max_bytes ?? null,
+  captions: v.captions ?? null,
+});
+
+/** The schema-checked block → the typed venue talk. Pure. */
+export const venueTalkOf = (j: VenueTalkJson): VenueTalk => ({
+  modes: j.modes ?? [],
+  artifacts: artifactsOf(j.artifacts ?? {}),
+  kinds: kindsOf(j.kinds ?? {}),
+  video: videoOf(j.video),
+  oneSlide:
+    j.one_slide === undefined
+      ? null
+      : { width: j.one_slide.width_px, height: j.one_slide.height_px },
+});
+
+// ── a paper's `talk` key ───────────────────────────────────────────────────────────────────
+
+const PAPER_TALK_KEYS = ["mode", "dir", "files", "one_slide"];
+
+const isMode = (v: unknown): v is TalkMode => TALK_MODES.some((m) => m === v);
+const isArtifact = (v: string): v is TalkArtifact =>
+  TALK_ARTIFACTS.some((a) => a === v);
+const isPlainName = (v: unknown): v is string =>
+  typeof v === "string" && v !== "" && !v.includes("/") && !v.includes("\\");
+const isPositiveInt = (v: unknown): v is number =>
+  typeof v === "number" && Number.isInteger(v) && v > 0;
+
+/** `files`: each key an artifact, each value a file name in the talk folder. */
+function filesOf(v: unknown): Result<TalkFiles, string> {
+  if (v === undefined) return ok(DEFAULT_TALK_FILES);
+  if (!isRecord(v)) return err(`"talk.files" must be an object`);
+  const bad = Object.entries(v).find(
+    ([k, name]) => !isArtifact(k) || !isPlainName(name),
+  );
+  if (bad !== undefined)
+    return err(
+      `"talk.files": "${bad[0]}" must be one of ${TALK_ARTIFACTS.join(", ")}, naming a file in the talk folder (no slashes)`,
+    );
+  const named = Object.fromEntries(
+    Object.entries(v).filter(
+      (e): e is [string, string] => typeof e[1] === "string",
+    ),
+  );
+  return ok({ ...DEFAULT_TALK_FILES, ...named });
+}
+
+/** `one_slide`: `{ width_px, height_px }`, both positive integers. */
+function oneSlideOf(v: unknown): Result<PixelSize | null, string> {
+  if (v === undefined) return ok(null);
+  const w = fieldOf(v, "width_px");
+  const h = fieldOf(v, "height_px");
+  return isPositiveInt(w) && isPositiveInt(h)
+    ? ok({ width: w, height: h })
+    : err(
+        `"talk.one_slide" must be { "width_px": <integer>, "height_px": <integer> }`,
+      );
+}
+
+/**
+ * A paper's `talk` value → the typed declaration; null when absent. Strict like the rest of the
+ * file: an unknown key is refused by name, or a typo would read as "not set".
+ */
+export function parsePaperTalk(v: unknown): Result<PaperTalk | null, string> {
+  if (v === undefined) return ok(null);
+  if (!isRecord(v)) return err(`"talk" must be an object with a "mode"`);
+  const unknown = Object.keys(v).find((k) => !PAPER_TALK_KEYS.includes(k));
+  if (unknown !== undefined)
+    return err(
+      `"talk" has an unknown key "${unknown}" — known: ${PAPER_TALK_KEYS.join(", ")}`,
+    );
+  const mode = v["mode"];
+  if (!isMode(mode))
+    return err(`"talk.mode" must be one of ${TALK_MODES.join(", ")}`);
+  const dir = v["dir"] ?? DEFAULT_TALK_DIR;
+  if (typeof dir !== "string" || dir === "")
+    return err(`"talk.dir" must be a folder relative to the paper`);
+  const files = filesOf(v["files"]);
+  if (!files.ok) return files;
+  const oneSlide = oneSlideOf(v["one_slide"]);
+  if (!oneSlide.ok) return oneSlide;
+  return ok({ mode, dir, files: files.value, oneSlide: oneSlide.value });
+}

package/src/new-paper.test.ts

@@ -57,6 +57,7 @@ describe("paperlint new — paperlint.json", () => {
         pdf: null,
         rules: null,
         identity: null,
+        talk: null,
       },
     });
   });

package/src/paper-settings.test.ts

@@ -31,6 +31,7 @@ describe("parsePaperSettings", () => {
         pdf: null,
         rules: null,
         identity: null,
+        talk: null,
       },
     });
     expect(parsePaperSettings({})).toEqual({
@@ -41,6 +42,7 @@ describe("parsePaperSettings", () => {
         pdf: null,
         rules: null,
         identity: null,
+        talk: null,
       },
     });
   });
@@ -54,6 +56,7 @@ describe("parsePaperSettings", () => {
         pdf: null,
         rules: null,
         identity: null,
+        talk: null,
       },
     });
   });
@@ -152,7 +155,7 @@ describe("readPaperSettings — a root paperlint.json that cannot be used", () =
 });
 
 /** The fields a case does not set. */
-const UNSET = { pdf: null, rules: null, identity: null };
+const UNSET = { pdf: null, rules: null, identity: null, talk: null };
 
 describe("readPaperSettings — the root paperlint.json's defaults, the paper's file over them", () => {
   const ROOT = "/work";
@@ -206,6 +209,7 @@ describe("readPaperSettings — the root paperlint.json's defaults, the paper's
       // The root's rules are the project's blocks (cli.ts), not this paper's.
       rules: { "pdf/fonts": "off" },
       identity: null,
+      talk: null,
     });
   });
 
@@ -248,6 +252,7 @@ describe("paperRules — `rules` in paperlint.json", () => {
     pdf: null,
     rules,
     identity: null,
+    talk: null,
   });
 
   it("no rules: none", () => {
@@ -324,3 +329,15 @@ describe("readPaperSettings — identity, at both levels", () => {
     );
   });
 });
+
+describe("talk in a paper's paperlint.json", () => {
+  it("is parsed into the paper's settings", () => {
+    const r = parsePaperSettings({ talk: { mode: "remote-video" } });
+    expect(r.ok && r.value.talk?.mode).toBe("remote-video");
+  });
+
+  it("refuses a talk it cannot parse, naming the key", () => {
+    const r = parsePaperSettings({ talk: { mode: "zoom" } });
+    expect(r.ok ? "" : r.error).toMatch(/"talk.mode"/);
+  });
+});

package/src/paper-settings.ts

@@ -31,6 +31,7 @@ import {
   type RuleEntry,
 } from "./rules-config.ts";
 import { messageOf } from "./domain/text.ts";
+import { parsePaperTalk, type PaperTalk } from "./domain/talk.ts";
 
 /** What one paper declares. Every absent field is null. */
 export interface PaperSettings {
@@ -51,6 +52,8 @@ export interface PaperSettings {
    * and cannot drop them by accident. Null when neither declares one.
    */
   readonly identity: readonly string[] | null;
+  /** How this paper is presented (`talk/*`); null when it declares no talk. Never the root's. */
+  readonly talk: PaperTalk | null;
 }
 
 /** Why a paper's settings cannot be read. */
@@ -109,6 +112,19 @@ export function identityField(
       );
 }
 
+/** `rules` (checked for shape only) and `talk`, each null when absent. */
+function rulesAndTalk(
+  json: Readonly<Record<string, unknown>>,
+): Result<Pick<PaperSettings, "rules" | "talk">, string> {
+  const rules = json["rules"];
+  if (rules !== undefined && !isObject(rules) && !Array.isArray(rules))
+    return err(
+      `"rules" must be an object of rule id → severity, or a list of ESLint blocks`,
+    );
+  const talk = parsePaperTalk(json["talk"]);
+  return talk.ok ? ok({ rules: rules ?? null, talk: talk.value }) : talk;
+}
+
 /** The parsed JSON of `paperlint.json` → the settings, or one line saying what is wrong. Pure. */
 export function parsePaperSettings(
   json: unknown,
@@ -128,16 +144,9 @@ export function parsePaperSettings(
   if (!fields.ok) return fields;
   const identity = identityField(json);
   if (!identity.ok) return identity;
-  const rules = json["rules"];
-  if (rules !== undefined && !isObject(rules) && !Array.isArray(rules))
-    return err(
-      `"rules" must be an object of rule id → severity, or a list of ESLint blocks`,
-    );
-  return ok({
-    ...fields.value,
-    rules: rules ?? null,
-    identity: identity.value,
-  });
+  const rest = rulesAndTalk(json);
+  if (!rest.ok) return rest;
+  return ok({ ...fields.value, ...rest.value, identity: identity.value });
 }
 
 /** A JSON file through `files`: undefined when absent, the problem when it does not parse. */
@@ -223,13 +232,14 @@ function merge(
   paper: PaperSettings | null,
 ): PaperSettings | null {
   const r = root ?? NO_DEFAULTS;
-  const p = paper ?? { ...NO_DEFAULTS, rules: null };
+  const p = paper ?? { ...NO_DEFAULTS, rules: null, talk: null };
   const merged: PaperSettings = {
     extends: p.extends ?? r.extends,
     kind: p.kind ?? r.kind,
     pdf: p.pdf ?? r.pdf,
     rules: p.rules,
     identity: joined(r.identity, p.identity),
+    talk: p.talk,
   };
   return paper === null && Object.values(merged).every((v) => v === null)
     ? null

package/src/ports/talk-media.ts

@@ -0,0 +1,19 @@
+/**
+ * Reading a talk's files: what the talk rules need to know about a video, an image and captions.
+ * Shaped by the questions the rules ask, not by any tool: the adapters behind it are MP4Box.js,
+ * a PNG header reader and an SRT parser (`src/adapters/`).
+ */
+import type { AbsolutePath } from "../domain/paths.ts";
+import type { Cue, PixelSize, VideoProbe } from "../domain/talk.ts";
+
+export interface TalkMedia {
+  /** The video's durations, size and brands; null when the bytes are not an ISO media file. */
+  probeVideo(bytes: Uint8Array): VideoProbe | null;
+  /** The image's size; null when the bytes are not a PNG. */
+  imageSize(bytes: Uint8Array): PixelSize | null;
+  /** The cues of a captions file, in file order; empty when it holds none. */
+  captions(text: string): readonly Cue[];
+}
+
+/** The names in a directory; empty when there is no such directory. */
+export type ListDir = (dir: AbsolutePath) => readonly string[];

package/src/presets.ts

@@ -19,7 +19,7 @@
  *   tex        union — a child never removes a package its parent needs
  *   format     per key, the child wins; `kinds` by kind name, a child's kind replaces that kind
  *   rules      per rule id, the child wins
- *   template   the child wins; so does `name`, and `required_sections` and `register` (each whole)
+ *   template   the child wins; so does `name`, and `required_sections`, `register` and `talk` (each whole)
  *   aliases    union, with every `name` — what the venue is called along the chain
  *
  * ── THE LABEL ─────────────────────────────────────────────────────────────────────
@@ -52,6 +52,7 @@ import {
 import { CONFIG_FILE } from "#lib/paper-config";
 import { messageOf } from "./domain/text.ts";
 import type { RegisterAnchor } from "./domain/register.ts";
+import type { VenueTalk } from "./domain/talk.ts";
 
 /** The prefix of a shipped preset's spec. */
 export const SHIPPED_PREFIX = "paperlint:";
@@ -92,6 +93,8 @@ export interface Preset {
   readonly rules: Readonly<Record<string, unknown>>;
   /** The accepted papers the register rules measure a body against; empty when no file names any. */
   readonly registerAnchors: readonly RegisterAnchor[];
+  /** What the venue asks a presenter to send (`talk/*`); null when no file of the chain says. */
+  readonly talk: VenueTalk | null;
 }
 
 /** Why a spec does not resolve. */
@@ -223,6 +226,7 @@ function merged(
     format: NO_FORMAT,
     rules: {},
     registerAnchors: [],
+    talk: null,
   };
   const m = rootFirst.reduce(
     (acc, { preset: p, file }) => ({
@@ -241,20 +245,15 @@ function merged(
       format: mergeFormat(acc.format, p.format),
       rules: { ...acc.rules, ...p.rules },
       registerAnchors: p.registerAnchors ?? acc.registerAnchors,
+      talk: p.talk ?? acc.talk,
     }),
     base,
   );
+  const { name, ...rest } = m;
   return {
-    label: m.name ?? labelOf(spec),
+    label: name ?? labelOf(spec),
     chain: rootFirst.map((x) => x.file),
-    template: m.template,
-    aliases: m.aliases,
-    blind: m.blind,
-    requiredSections: m.requiredSections,
-    tex: m.tex,
-    format: m.format,
-    rules: m.rules,
-    registerAnchors: m.registerAnchors,
+    ...rest,
   };
 }
 

package/src/rule-cases.test.ts

@@ -145,10 +145,65 @@ const switched = (second: string): string =>
 const aidc = (body: string, cls = IEEE) =>
   paper(tex(`\\section{Introduction}\n${body}\n${STATEMENT}`, cls), AIDC);
 
+// ── a paper that declares a talk: a preset of its own over agenticdev, and synthetic media ───────
+
+const media = (name: string): Uint8Array =>
+  readFileSync(join(ROOT, "fixtures", "talk", name));
+/** The talk block of the tree's own preset: every limit the 3 s, 1280×720 fixture meets. */
+const TALK_VENUE = {
+  modes: ["remote-video"],
+  artifacts: {
+    "remote-video": { required: ["video", "one-slide", "captions"] },
+  },
+  kinds: { short: { slot_s: 10, talk_s_min: 2, talk_s_max: 4 } },
+  video: { container: "mp4", min_height_px: 720, max_bytes: 100_000 },
+  one_slide: { width_px: 16, height_px: 9 },
+};
+/** A paper declaring a talk, its preset's `talk` patched, its files replaced or (null) removed. */
+const talkPaper = (
+  venue: Record<string, unknown> = {},
+  talk: Record<string, unknown> | null = { mode: "remote-video" },
+  files: Record<string, string | Uint8Array | null> = {},
+): Record<string, string | Uint8Array> => {
+  const all: Record<string, string | Uint8Array | null> = {
+    [`${P}/talk/talk.mp4`]: media("talk.mp4"),
+    [`${P}/talk/one-slide.png`]: media("one-slide.png"),
+    [`${P}/talk/talk.srt`]: media("talk.srt"),
+    ...files,
+  };
+  return {
+    ...paper(ACM_TEX, {
+      [`${P}/talk-venue.jsonc`]: JSON.stringify({
+        extends: "paperlint:agenticdev",
+        talk: { ...TALK_VENUE, ...venue },
+      }),
+      [`${P}/paperlint.json`]: JSON.stringify({
+        extends: "./talk-venue.jsonc",
+        kind: "short",
+        ...(talk === null ? {} : { talk }),
+      }),
+    }),
+    ...Object.fromEntries(
+      Object.entries(all).filter(
+        (e): e is [string, string | Uint8Array] => e[1] !== null,
+      ),
+    ),
+  };
+};
+const onTalk = (
+  tree: Record<string, string | Uint8Array>,
+  severity: 1 | 2 = 2,
+) => ({
+  tree,
+  file: TEX_FILE,
+  severity,
+  line: 1,
+});
+
 // ── the case table ─────────────────────────────────────────────────────────────────────────────
 
 interface Reports {
-  readonly tree: Record<string, string>;
+  readonly tree: Record<string, string | Uint8Array>;
   /** The file the finding is on, relative to the project. */
   readonly file: string;
   readonly severity: 1 | 2;
@@ -157,7 +212,7 @@ interface Reports {
 interface RuleCases {
   readonly reports: Reports;
   /** A tree on which the rule says nothing, on any file. */
-  readonly silent: Record<string, string>;
+  readonly silent: Record<string, string | Uint8Array>;
 }
 
 const TEX_FILE = `${P}/paper.tex`;
@@ -463,6 +518,56 @@ const CASES: Readonly<Record<string, RuleCases>> = {
       { ...AGENTICDEV, rules: { "pdf/last-page-balance": "error" } },
     ),
   },
+  "talk/profile": {
+    reports: onTalk(talkPaper({}, { mode: "in-person" })),
+    silent: talkPaper(),
+  },
+  "talk/required-files": {
+    reports: onTalk(
+      talkPaper({}, undefined, { [`${P}/talk/one-slide.png`]: null }),
+    ),
+    silent: talkPaper(),
+  },
+  "talk/undeclared": {
+    reports: onTalk(talkPaper({}, null), 1),
+    silent: talkPaper(),
+  },
+  "talk/duration": {
+    reports: onTalk(
+      talkPaper({ kinds: { short: { slot_s: 10, talk_s_max: 2 } } }),
+    ),
+    silent: talkPaper(),
+  },
+  "talk/duration-floor": {
+    reports: onTalk(
+      talkPaper({
+        kinds: { short: { slot_s: 10, talk_s_min: 5, talk_s_max: 9 } },
+      }),
+      1,
+    ),
+    silent: talkPaper(),
+  },
+  "talk/video-format": {
+    reports: onTalk(
+      talkPaper({ video: { container: "mp4", min_height_px: 1080 } }),
+    ),
+    silent: talkPaper(),
+  },
+  "talk/one-slide-size": {
+    reports: onTalk(
+      talkPaper({ one_slide: { width_px: 1920, height_px: 1080 } }),
+    ),
+    silent: talkPaper(),
+  },
+  "talk/captions-cover": {
+    reports: onTalk(
+      talkPaper({}, undefined, {
+        [`${P}/talk/talk.srt`]: "1\n00:00:02,000 --> 00:00:02,900\nLate.\n",
+      }),
+      1,
+    ),
+    silent: talkPaper(),
+  },
 };
 
 /**
@@ -491,7 +596,9 @@ type Message = z.infer<typeof LintResults>[number]["messages"][number] & {
 };
 
 /** `paperlint lint --json` over the tree, in-process through the CLI: every message, by file. */
-async function lintTree(tree: Record<string, string>): Promise<Message[]> {
+async function lintTree(
+  tree: Record<string, string | Uint8Array>,
+): Promise<Message[]> {
   const dir = writeTree(useTempDir("paperlint-rule-cases-"), {
     "package.json": '{"name":"consumer","private":true}',
     ...tree,