resumectl 0.0.0-stage → 0.1.0

package/src/project/config.ts

@@ -0,0 +1,265 @@
+import { dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { InputError } from "../errors.ts";
+import { resolveInputs, sectionKey, stripComments } from "../content/tex.ts";
+
+export interface LayoutOptions {
+  style: "serif" | "sans";
+  paper: "a4" | "letter";
+  scale: number;
+  tracking: number;
+  ratio: number;
+  margins: { top: string; bottom: string; left: string; right: string };
+  bulletSpacing: string;
+  bulletIndent: string;
+  sectionSpacing: { before: string; after: string };
+}
+export interface BulletOptions { maxLines: number; minLastLineFill: number }
+export interface SectionOptions {
+  editable: boolean;
+  checks: BulletOptions | false;
+}
+export interface SectionInput {
+  editable?: boolean;
+  checks?: Partial<BulletOptions> | false;
+}
+export interface CheckOptions {
+  section?: string;
+  bullets: BulletOptions;
+  maxPages: number;
+}
+export interface ResumeConfig {
+  version: 1;
+  layout: LayoutOptions;
+  checks: CheckOptions;
+  sections: Record<string, SectionOptions>;
+  build: { outDir?: string; keepLogs: boolean };
+}
+export interface ConfigInput {
+  $schema?: string;
+  version?: 1;
+  layout?: Partial<Omit<LayoutOptions, "margins" | "sectionSpacing">> & {
+    margins?: Partial<LayoutOptions["margins"]>;
+    sectionSpacing?: Partial<LayoutOptions["sectionSpacing"]>;
+  };
+  checks?: Partial<Omit<CheckOptions, "bullets">> & { bullets?: Partial<CheckOptions["bullets"]> };
+  sections?: Record<string, SectionInput>;
+  build?: Partial<ResumeConfig["build"]>;
+}
+export const CONFIG_NAME = "resume.config.yaml";
+export const SCHEMA_PATH = resolve(import.meta.dir, "../../resume.config.schema.json");
+export const DEFAULT_CHECKS: CheckOptions = {
+  bullets: { maxLines: 2, minLastLineFill: 0.8 }, maxPages: 1,
+};
+export const DEFAULT_LAYOUT: LayoutOptions = {
+  style: "serif", paper: "a4", scale: 0.86, tracking: -1.5, ratio: 1.125,
+  margins: { top: "0.4in", bottom: "0.3in", left: "0.35in", right: "0.35in" },
+  bulletSpacing: "0.15em", bulletIndent: "1.5pc",
+  sectionSpacing: { before: "*1", after: "*1" },
+};
+
+type Shape = Record<string, unknown>;
+function object(value: unknown, path: string, keys: string[]): Shape {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new InputError(`${path} must be an object`);
+  for (const key of Object.keys(value)) if (!keys.includes(key)) throw new InputError(`unknown config field: ${path}.${key}`);
+  return value as Shape;
+}
+function number(value: unknown, path: string, min: number, max: number, integer = false) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max || (integer && !Number.isInteger(value))) {
+    throw new InputError(`${path} must be ${integer ? "an integer" : "a number"} between ${min} and ${max}`);
+  }
+}
+function text(value: unknown, path: string) {
+  if (typeof value !== "string" || !value.trim() || /[\x00-\x1f]/.test(value)) throw new InputError(`${path} must be a non-empty string without control characters`);
+}
+function dimension(value: unknown, path: string, absolute = false, multiplier = false) {
+  const units = absolute ? "pt|mm|cm|in|pc" : "pt|mm|cm|in|pc|em|ex";
+  if (typeof value !== "string" || !(new RegExp(`^(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:${units})$`).test(value)
+    || (multiplier && /^\*(?:\d+(?:\.\d+)?|\.\d+)$/.test(value)))) {
+    throw new InputError(`${path} must be a non-negative length with units${multiplier ? " or a * multiplier" : ""}`);
+  }
+}
+function bulletOptions(value: unknown, path: string) {
+  const b = object(value, path, ["maxLines", "minLastLineFill"]);
+  if (b.maxLines !== undefined) number(b.maxLines, `${path}.maxLines`, 1, 100, true);
+  if (b.minLastLineFill !== undefined) number(b.minLastLineFill, `${path}.minLastLineFill`, 0, 1);
+}
+/** Validate both files and CLI/API overrides before any value reaches TeX. */
+export function validateConfig(value: unknown): ConfigInput {
+  const root = object(value, "config", ["$schema", "version", "layout", "checks", "sections", "build"]);
+  if (root.version !== undefined && root.version !== 1) throw new InputError("config.version must be 1");
+  if (root.$schema !== undefined) text(root.$schema, "$schema");
+  if (root.layout !== undefined) {
+    const l = object(root.layout, "layout", ["style", "paper", "scale", "tracking", "ratio", "margins", "bulletSpacing", "bulletIndent", "sectionSpacing"]);
+    for (const [key, choices] of [["style", ["serif", "sans"]], ["paper", ["a4", "letter"]]] as const) {
+      if (l[key] !== undefined && !(choices as readonly unknown[]).includes(l[key])) throw new InputError(`layout.${key} must be ${choices.join(" or ")}`);
+    }
+    for (const [key, min, max] of [["scale", 0.1, 4], ["tracking", -10, 20], ["ratio", 1, 2]] as const) {
+      if (l[key] !== undefined) number(l[key], `layout.${key}`, min, max);
+    }
+    if (l.margins !== undefined) {
+      const m = object(l.margins, "layout.margins", ["top", "bottom", "left", "right"]);
+      for (const [k, v] of Object.entries(m)) dimension(v, `layout.margins.${k}`, true);
+    }
+    for (const key of ["bulletSpacing", "bulletIndent"]) if (l[key] !== undefined) dimension(l[key], `layout.${key}`);
+    if (l.sectionSpacing !== undefined) {
+      const s = object(l.sectionSpacing, "layout.sectionSpacing", ["before", "after"]);
+      for (const [k, v] of Object.entries(s)) dimension(v, `layout.sectionSpacing.${k}`, false, true);
+    }
+  }
+  if (root.checks !== undefined) {
+    const c = object(root.checks, "checks", ["section", "bullets", "maxPages"]);
+    if (c.section !== undefined) text(c.section, "checks.section");
+    if (c.maxPages !== undefined) number(c.maxPages, "checks.maxPages", 1, 100, true);
+    if (c.bullets !== undefined) bulletOptions(c.bullets, "checks.bullets");
+  }
+  if (root.sections !== undefined) {
+    const sections = object(root.sections, "sections", Object.keys(root.sections ?? {}));
+    const seen = new Set<string>();
+    for (const [name, value] of Object.entries(sections)) {
+      text(name, "section name");
+      const key = sectionKey(name);
+      if (!key || ["__PROTO__", "CONSTRUCTOR", "PROTOTYPE"].includes(key)) throw new InputError(`invalid section name: ${name}`);
+      if (seen.has(key)) throw new InputError(`duplicate section name: ${name}`);
+      seen.add(key);
+      const s = object(value, `sections.${name}`, ["editable", "checks"]);
+      if (s.editable !== undefined && typeof s.editable !== "boolean") throw new InputError(`sections.${name}.editable must be a boolean`);
+      if (s.checks !== undefined && s.checks !== false) bulletOptions(s.checks, `sections.${name}.checks`);
+    }
+  }
+  if (root.build !== undefined) {
+    const b = object(root.build, "build", ["outDir", "keepLogs"]);
+    if (b.outDir !== undefined) text(b.outDir, "build.outDir");
+    if (b.keepLogs !== undefined && typeof b.keepLogs !== "boolean") throw new InputError("build.keepLogs must be a boolean");
+  }
+  return value as ConfigInput;
+}
+
+const CLASS_KEYS: Record<string, string> = {
+  style: "style", paper: "paper", scale: "scale", tracking: "tracking", ratio: "ratio",
+  marginTop: "margins.top", marginBottom: "margins.bottom", marginLeft: "margins.left", marginRight: "margins.right",
+  bulletSpacing: "bulletSpacing", bulletIndent: "bulletIndent", sectionBefore: "sectionSpacing.before", sectionAfter: "sectionSpacing.after",
+};
+function setPath(target: Shape, path: string, value: unknown) {
+  const parts = path.split(".");
+  const last = parts.pop()!;
+  let node = target;
+  for (const part of parts) node = (node[part] ??= {}) as Shape;
+  node[last] = value;
+}
+export function readSourceLayout(tex: string): ConfigInput["layout"] {
+  const match = stripComments(tex).match(/\\documentclass\s*(?:\[([^\]]*)\])?\s*\{\s*resume\s*\}/);
+  if (!match) throw new InputError("expected \\documentclass{resume} with literal class options");
+  const layout: Shape = {};
+  for (const part of (match[1] ?? "").split(",").filter(p => p.trim())) {
+    const [name, raw] = part.split("=").map(p => p.trim());
+    const key = CLASS_KEYS[name];
+    if (!key || raw === undefined) throw new InputError(`unsupported resume class option: ${part.trim()}`);
+    setPath(layout, key, ["scale", "tracking", "ratio"].includes(name) ? Number(raw) : raw);
+  }
+  return validateConfig({ layout }).layout;
+}
+export function layoutToClassOptions(layout: LayoutOptions): string {
+  const l = layout as unknown as Shape;
+  return Object.entries(CLASS_KEYS).map(([key, path]) => {
+    let value: unknown = l;
+    for (const part of path.split(".")) value = (value as Shape)[part];
+    return `${key}=${value}`;
+  }).join(",");
+}
+async function discover(start: string): Promise<string | undefined> {
+  let dir = resolve(start);
+  for (;;) {
+    const candidates = [join(dir, CONFIG_NAME), join(dir, "resume.config.yml")];
+    const found = [];
+    for (const candidate of candidates) if (await Bun.file(candidate).exists()) found.push(candidate);
+    if (found.length > 1) throw new InputError(`both resume.config.yaml and resume.config.yml exist in ${dir}; select one with --config`);
+    if (found.length) return found[0];
+    // A repository's configuration must not accidentally inherit a sibling project's defaults.
+    if (existsSync(join(dir, ".git")) || dirname(dir) === dir) return undefined;
+    dir = dirname(dir);
+  }
+}
+export interface ResolvedConfig {
+  config: ResumeConfig;
+  configPath?: string;
+  sources: Record<string, string>;
+}
+export async function resolveConfig(options: { texPath?: string; configPath?: string | null; overrides?: ConfigInput; cwd?: string } = {}): Promise<ResolvedConfig> {
+  const cwd = options.cwd ?? process.cwd();
+  const texPath = options.texPath ? resolve(cwd, options.texPath) : undefined;
+  const configPath = options.configPath === null ? undefined : options.configPath ? resolve(cwd, options.configPath) : await discover(texPath ? dirname(texPath) : cwd);
+  let file: ConfigInput = {};
+  if (configPath) {
+    if (!/\.ya?ml$/i.test(configPath)) throw new InputError("config files must use .yaml or .yml");
+    if (!Bun.YAML) throw new InputError("YAML configuration requires Bun >= 1.3; upgrade Bun first");
+    if (!await Bun.file(configPath).exists()) throw new InputError(`config not found: ${configPath}`);
+    try { file = validateConfig(Bun.YAML.parse(await Bun.file(configPath).text()) ?? {}); }
+    catch (error) { throw new InputError(`${configPath}: ${(error as Error).message}`); }
+  }
+  let source: ConfigInput = {};
+  if (texPath) {
+    if (!await Bun.file(texPath).exists()) throw new InputError(`TeX source not found: ${texPath}`);
+    source = { layout: readSourceLayout(await resolveInputs(await Bun.file(texPath).text(), texPath)) };
+  }
+  const overrides = validateConfig(options.overrides ?? {});
+  const style = overrides.layout?.style ?? file.layout?.style ?? source.layout?.style ?? "serif";
+  const config: ResumeConfig = {
+    version: 1,
+    layout: structuredClone(DEFAULT_LAYOUT),
+    checks: structuredClone(DEFAULT_CHECKS),
+    sections: {},
+    build: { keepLogs: false },
+  };
+  if (style === "sans") config.layout.sectionSpacing = { before: "*2", after: "*0.8" };
+  const sources: Record<string, string> = {};
+  function merge(input: Shape, target: Shape, prefix: string, origin: string) {
+    for (const [key, value] of Object.entries(input)) {
+      if (key === "$schema") continue;
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (value && typeof value === "object") {
+        if (!Object.hasOwn(target, key) || !target[key] || typeof target[key] !== "object") target[key] = {};
+        merge(value as Shape, target[key] as Shape, path, origin);
+      } else { target[key] = value; sources[path] = origin; }
+    }
+  }
+  // Section names are literal keys (including dots), normalized just like rendered headings.
+  const normalize = (input: ConfigInput): Shape => ({ ...input, ...(input.sections ? {
+    sections: Object.fromEntries(Object.entries(input.sections).map(([name, policy]) => [sectionKey(name), policy])),
+  } : {}) });
+  const target = config as unknown as Shape;
+  const normalizedOverrides = normalize(overrides);
+  merge(structuredClone(config) as unknown as Shape, target, "", "default");
+  merge(source as Shape, target, "", "documentclass");
+  merge(normalize(file), target, "", configPath ?? "config");
+  if (file.build?.outDir) config.build.outDir = resolve(dirname(configPath!), file.build.outDir);
+  merge(normalizedOverrides, target, "", "override");
+  for (const [name, policy] of Object.entries(config.sections)) {
+    policy.editable ??= false;
+    sources[`sections.${name}.editable`] ??= "default";
+    if (policy.checks === false) continue;
+    policy.checks = { ...config.checks.bullets, ...policy.checks };
+    for (const field of ["maxLines", "minLastLineFill"] as const) {
+      const path = `sections.${name}.checks.${field}`;
+      sources[path] ??= sources[`checks.bullets.${field}`];
+      // CLI/global API overrides apply to selected sections, above file-specific rules.
+      if (overrides.checks?.bullets?.[field] !== undefined) {
+        policy.checks[field] = overrides.checks.bullets[field]!;
+        sources[path] = "override";
+      }
+      const specific = (normalizedOverrides.sections as Record<string, SectionInput> | undefined)?.[name]?.checks;
+      if (specific && specific[field] !== undefined) policy.checks[field] = specific[field]!;
+    }
+  }
+  if (overrides.build?.outDir) config.build.outDir = resolve(cwd, overrides.build.outDir);
+  config.build.outDir ??= texPath ? dirname(texPath) : cwd;
+  sources["build.outDir"] ??= "source directory";
+  const pt = (length: string) => {
+    const [, value, unit] = length.match(/^([\d.]+)(\w+)$/)!;
+    return Number(value) * ({ pt: 1, in: 72.27, cm: 72.27 / 2.54, mm: 72.27 / 25.4, pc: 12 }[unit]!);
+  };
+  const m = config.layout.margins;
+  const [width, height] = config.layout.paper === "a4" ? [597.508, 845.047] : [614.295, 794.97];
+  if (pt(m.left) + pt(m.right) >= width || pt(m.top) + pt(m.bottom) >= height) throw new InputError("layout.margins leave no printable area");
+  return { config, configPath, sources };
+}

package/src/project/doctor.ts

@@ -0,0 +1,76 @@
+import { join } from "node:path";
+import { FONT_DIR, TEMPLATE_DIR } from "../rendering/assets.ts";
+import { texEngine } from "../rendering/compile.ts";
+
+export interface Diagnostic {
+  name: string;
+  ok: boolean;
+  detail: string;
+  fix?: string;
+}
+export interface DoctorReport { pass: boolean; checks: Diagnostic[] }
+
+const TEX_FILES = [
+  "article.cls", "fontspec.sty", "kvoptions.sty", "geometry.sty", "titlesec.sty",
+  "enumitem.sty", "hyperref.sty", "url.sty", "tabularx.sty", "tikz.sty",
+  "texgyretermes-regular.otf", "texgyretermes-bold.otf",
+  "texgyretermes-italic.otf", "texgyretermes-bolditalic.otf",
+];
+
+/** Inspect dependencies without installing anything or modifying the user's project. */
+export async function doctor(): Promise<DoctorReport> {
+  const [major, minor] = Bun.version.split(".").map(Number);
+  const checks: Diagnostic[] = [{
+    name: "Bun", ok: (major > 1 || (major === 1 && minor >= 3)) && !!Bun.YAML,
+    detail: Bun.version, fix: "Install Bun >= 1.3.",
+  }];
+  const engine = texEngine();
+  if (engine === "tectonic") {
+    const path = Bun.which("tectonic");
+    const ok = !!path && Bun.spawnSync([path, "--help"], { stdout: "pipe", stderr: "pipe", timeout: 10_000 }).exitCode === 0;
+    checks.push({
+      name: "tectonic", ok, detail: ok ? `${path} (downloads TeX packages on first build)` : `${path ?? "not found in PATH"}: failed to run`,
+      fix: "Reinstall Tectonic: brew install tectonic.",
+    });
+  } else if (!engine) {
+    checks.push({
+      name: "TeX engine", ok: false, detail: "neither tectonic nor xelatex found in PATH",
+      fix: "Install Tectonic (brew install tectonic; TeX packages download on first build) or TinyTeX-1 (see docs/setup.md).",
+    });
+  } else {
+    for (const command of ["xelatex", "kpsewhich"]) {
+      const path = Bun.which(command);
+      let ok = false;
+      let detail = "not found in PATH";
+      if (path) {
+        try {
+          const result = Bun.spawnSync([path, "--version"], { stdout: "pipe", stderr: "pipe", timeout: 10_000 });
+          ok = result.exitCode === 0;
+          detail = ok ? `${path}: ${result.stdout.toString().split("\n")[0]}` : `${path}: failed to run`;
+        } catch (error) { detail = `${path}: ${(error as Error).message}`; }
+      }
+      checks.push({ name: command, ok, detail, fix: "Install TinyTeX-1 or TeX Live and add its bin directory to PATH." });
+    }
+    if (checks.find(c => c.name === "kpsewhich")!.ok) {
+      const missing = TEX_FILES.filter(file => {
+        const result = Bun.spawnSync([Bun.which("kpsewhich")!, file], { stdout: "pipe", stderr: "pipe", timeout: 10_000 });
+        return result.exitCode !== 0 || !result.stdout.toString().trim();
+      });
+      checks.push({
+        name: "TeX dependencies", ok: missing.length === 0,
+        detail: missing.length ? `missing: ${missing.join(", ")}` : `${TEX_FILES.length} required files found`,
+        fix: "Install the README's TeX packages; with TinyTeX-1: tlmgr install titlesec enumitem pgf tex-gyre.",
+      });
+    }
+  }
+  for (const path of [join(TEMPLATE_DIR, "resume.cls"), join(TEMPLATE_DIR, "resume-measure.tex"),
+    ...[430, 500, 600].map(weight => join(FONT_DIR, `Inter-${weight}.ttf`))]) {
+    checks.push({ name: "Bundled asset", ok: await Bun.file(path).exists(), detail: path, fix: "Restore the template directory or reinstall resumectl." });
+  }
+  return { pass: checks.every(c => c.ok), checks };
+}
+
+export function formatDoctor(report: DoctorReport): string {
+  return report.checks.map(c => `${c.ok ? "PASS" : "FAIL"} ${c.name}: ${c.detail}${!c.ok && c.fix ? `\n  ${c.fix}` : ""}`).join("\n")
+    + `\n\n${report.pass ? "OK — build dependencies are available." : "Fix the failed checks before building."}`;
+}

package/src/project/init.ts

@@ -0,0 +1,78 @@
+import { lstat, mkdir, open, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { InputError } from "../errors.ts";
+import { CONFIG_NAME, DEFAULT_CHECKS, SCHEMA_PATH, validateConfig, type ConfigInput, type LayoutOptions } from "./config.ts";
+
+type StarterOptions = Pick<LayoutOptions, "style" | "paper">;
+
+function starterConfig(options: Partial<StarterOptions>): ConfigInput {
+  return validateConfig({
+    version: 1,
+    layout: { style: "serif", paper: "a4", ...options },
+    checks: structuredClone(DEFAULT_CHECKS),
+    sections: { "WORK EXPERIENCE": { editable: true, checks: { ...DEFAULT_CHECKS.bullets } } },
+    build: { outDir: "./output", keepLogs: false },
+  });
+}
+
+function configText(path: string, config: ConfigInput): string {
+  return `# yaml-language-server: $schema=${relative(dirname(path), SCHEMA_PATH)}\n`
+    + "# CLI > YAML > documentclass > defaults. Lengths include units.\n"
+    + Bun.YAML.stringify(config, null, 2).replace(/[ \t]+$/gm, "") + "\n";
+}
+
+async function writeNew(path: string, text: string): Promise<void> {
+  let file;
+  try { file = await open(path, "wx"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new InputError(`file already exists: ${path}`);
+    throw error;
+  }
+  try { await file.writeFile(text); }
+  catch (error) { await rm(path, { force: true }); throw error; }
+  finally { await file.close(); }
+}
+
+export async function initConfig(path = CONFIG_NAME): Promise<{ configPath: string; config: ConfigInput }> {
+  path = resolve(path);
+  if (!/\.ya?ml$/i.test(path)) throw new InputError("config files must use .yaml or .yml");
+  const config = starterConfig({});
+  await writeNew(path, configText(path, config));
+  return { configPath: path, config };
+}
+
+/** Create editable source and policy together; never replace an existing résumé or config. */
+export async function initProject(directory = ".", options: Partial<StarterOptions> = {}) {
+  const config = starterConfig(options);
+  const target = resolve(directory);
+  const texPath = join(target, "resume.tex");
+  const configPath = join(target, CONFIG_NAME);
+  for (const path of [texPath, configPath, join(target, "resume.config.yml")]) {
+    const existing = await lstat(path).catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") return undefined;
+      throw error;
+    });
+    if (existing) throw new InputError(`file already exists: ${path}`);
+  }
+  const source = String.raw`% Replace every placeholder with verified career facts before sharing.
+\documentclass[style=${config.layout!.style},paper=${config.layout!.paper}]{resume}
+\begin{document}
+\name{YOUR NAME}
+\basicInfo{\href{mailto:you@example.com}{you@example.com}\sep City, Country}
+
+\section{WORK EXPERIENCE}
+\datedsubsection{\textbf{Company}}{Dates}
+\datedline{\role{Role}}{Location}
+\begin{itemize}
+\item Replace this sample with a verified accomplishment: describe your action, technical approach, and measurable impact.
+\end{itemize}
+
+% Add other sections and their editing/checking policies in resume.config.yaml.
+\end{document}
+`;
+  await mkdir(target, { recursive: true });
+  await writeNew(texPath, source);
+  try { await writeNew(configPath, configText(configPath, config)); }
+  catch (error) { await rm(texPath, { force: true }); throw error; }
+  return { directory: target, texPath, configPath };
+}

package/src/quality/gates.ts

@@ -0,0 +1,113 @@
+// Quality gates based on the actual rendered paragraphs, PDF pages and text maps.
+import { DEFAULT_CHECKS, layoutToClassOptions, validateConfig, type BulletOptions, type CheckOptions, type LayoutOptions, type SectionInput } from "../project/config.ts";
+import { InputError } from "../errors.ts";
+import { hash, readManifest, type RenderedBullet } from "../rendering/measurements.ts";
+import { countPdfPages, findPrivateUseMappings } from "./pdf.ts";
+import { type ClassOptions, extractSectionEntries, resolveInputs, sectionKey, stripToVisible } from "../content/tex.ts";
+
+export type GateOptions = CheckOptions & { sections?: Record<string, SectionInput> };
+export type GateOverrides = Partial<Omit<GateOptions, "bullets">> & { bullets?: Partial<GateOptions["bullets"]> };
+export const DEFAULT_GATE_OPTIONS = DEFAULT_CHECKS;
+
+export interface BulletResult extends RenderedBullet {
+  index: number;
+  text: string;
+  status: "ok" | "too-many-lines" | "sparse-last-line" | "overflow";
+}
+export interface GateReport {
+  classOptions: ClassOptions;
+  layout: LayoutOptions;
+  options: GateOptions;
+  bullets: BulletResult[];
+  sections: SectionResult[];
+  pages: number;
+  privateUse: number[];
+  overflows: string[];
+  bulletsPass: boolean;
+  pagesPass: boolean;
+  textPass: boolean;
+  pass: boolean;
+}
+export interface SectionResult {
+  section: string;
+  editable: boolean;
+  checks: BulletOptions | false;
+  bullets: BulletResult[];
+  pass: boolean;
+}
+export function checkBullets(rendered: RenderedBullet[], options: GateOptions, texts: string[] = []): BulletResult[] {
+  const section = options.section ?? "WORK EXPERIENCE";
+  const bullets = rendered.filter(b => sectionKey(b.section) === sectionKey(section));
+  return bullets.map((b, i) => {
+    if (b.unsupported) throw new InputError(`entry ${i + 1} in ${section} contains a nested list; use flat itemize bullets`);
+    const status = b.lastLineWidthPt > b.lineWidthPt + 0.1 ? "overflow"
+      : b.lines > options.bullets.maxLines ? "too-many-lines"
+      : b.lastLineFill + 1e-6 < options.bullets.minLastLineFill ? "sparse-last-line" : "ok";
+    return { ...b, index: i + 1, text: texts.length === bullets.length ? stripToVisible(texts[i]) : "", status };
+  });
+}
+export function parseLogPageCount(log: string): number | null {
+  const m = log.replace(/\r?\n/g, "").match(/Output written on .*?\((\d+) pages?\)/);
+  return m ? Number(m[1]) : null;
+}
+export async function runGates(texPath: string, pdfPath: string, overrides: GateOverrides = {}, expectedLayout?: LayoutOptions): Promise<GateReport> {
+  const { sections: sectionPolicies, ...checkOverrides } = overrides;
+  validateConfig({ checks: checkOverrides, ...(sectionPolicies !== undefined ? { sections: sectionPolicies } : {}) });
+  const options = { ...DEFAULT_CHECKS, ...overrides, bullets: { ...DEFAULT_CHECKS.bullets, ...overrides.bullets } };
+  if (!await Bun.file(texPath).exists()) throw new InputError(`TeX source not found: ${texPath}`);
+  if (!await Bun.file(pdfPath).exists()) throw new InputError(`PDF not found: ${pdfPath}`);
+  const tex = await resolveInputs(await Bun.file(texPath).text(), texPath);
+  const bytes = await Bun.file(pdfPath).bytes();
+  const manifest = await readManifest(pdfPath);
+  validateConfig({ layout: manifest.layout });
+  if (hash(bytes) !== manifest.pdfHash || hash(tex) !== manifest.sourceHash) {
+    throw new InputError("PDF/source no longer match the saved render measurements; rebuild the PDF");
+  }
+  if (expectedLayout && layoutToClassOptions(expectedLayout) !== layoutToClassOptions(manifest.layout)) {
+    throw new InputError("layout config differs from the PDF's build config; rebuild or use the same layout options");
+  }
+  const policies = new Map(Object.entries(sectionPolicies ?? {}).map(([name, policy]) => [sectionKey(name), policy]));
+  // A legacy selector (or --section) narrows the report; otherwise check every configured section.
+  const selected = options.section ? [sectionKey(options.section)] : policies.size ? [...policies.keys()] : ["WORK EXPERIENCE"];
+  const sections: SectionResult[] = selected.map(section => {
+    const policy = policies.get(section);
+    const editable = policy?.editable ?? false;
+    if (policy?.checks === false) return { section, editable, checks: false, bullets: [], pass: true };
+    const checks = { ...options.bullets, ...policy?.checks };
+    const bullets = checkBullets(manifest.bullets, { ...options, section, bullets: checks }, extractSectionEntries(tex, section));
+    if (!bullets.length) throw new InputError(`found no rendered bullets or entries in section "${section}"; check the section name or wrap prose/table descriptions in \\resumeentry{...}`);
+    return { section, editable, checks, bullets, pass: bullets.every(b => b.status === "ok") };
+  });
+  const bullets = sections.flatMap(s => s.bullets);
+  let pages = countPdfPages(bytes);
+  if (pages === null) {
+    const log = Bun.file(pdfPath.replace(/\.pdf$/i, ".log"));
+    if (await log.exists()) pages = parseLogPageCount(await log.text());
+  }
+  if (pages === null) throw new InputError(`could not read the page count of ${pdfPath}`);
+  const privateUse = findPrivateUseMappings(bytes);
+  const bulletsPass = bullets.every(b => b.status === "ok") && manifest.overflows.length === 0;
+  const pagesPass = pages <= options.maxPages;
+  const textPass = privateUse.length === 0;
+  const layout = manifest.layout;
+  const classOptions: ClassOptions = { style: layout.style, scale: layout.style === "sans" ? layout.scale : 1, tracking: layout.style === "sans" ? layout.tracking : 0 };
+  return { classOptions, layout, options, sections, bullets, pages, privateUse, overflows: manifest.overflows, bulletsPass, pagesPass, textPass, pass: bulletsPass && pagesPass && textPass };
+}
+export function formatReport(r: GateReport): string {
+  return [
+    `Gate 1 — rendered content length (${r.layout.style}, ${r.layout.paper})`,
+    ...r.sections.flatMap(s => s.checks === false ? [`  ${s.section}: SKIP (checks disabled; AI editable: ${s.editable})`] : [
+      `  ${s.section}: ≤ ${s.checks.maxLines} line${s.checks.maxLines === 1 ? "" : "s"}, last line ≥ ${Math.round(s.checks.minLastLineFill * 100)}% full; AI editable: ${s.editable}`,
+      `    ${s.bullets.length} ${s.bullets.length === 1 ? "entry" : "entries"} — ${s.pass ? "PASS" : "FAIL"}`,
+      ...s.bullets.filter(b => b.status !== "ok").map(b => `    ${b.status.toUpperCase()} ${s.section} #${b.index}: ${b.lines} lines, last line ${(b.lastLineFill * 100).toFixed(1)}% full${b.text ? ` — ${b.text.slice(0, 80)}${b.text.length > 80 ? "…" : ""}` : ""}`),
+    ]),
+    ...r.overflows.map(s => `  OVERFLOW: ${s}`),
+    `  ${r.bulletsPass ? "PASS" : "FAIL"}`, "",
+    `Gate 2 — at most ${r.options.maxPages} page${r.options.maxPages === 1 ? "" : "s"}`,
+    `  pages    ${r.pages}`, `  ${r.pagesPass ? "PASS" : "FAIL"}`, "",
+    "Gate 3 — text copies cleanly (no private-use characters)",
+    ...r.privateUse.map(cp => `  private-use mapping: U+${cp.toString(16).toUpperCase()}`),
+    `  ${r.textPass ? "PASS" : "FAIL"}`, "",
+    r.pass ? "OK — all gates passed." : "FAIL — revise the flagged content or layout, then rebuild.",
+  ].join("\n");
+}

package/src/quality/pdf.ts

@@ -0,0 +1,84 @@
+// Facts read straight from the compiled PDF, including PDFs whose objects live
+// in compressed object streams (xdvipdfmx's default).
+import { inflateSync } from "node:zlib";
+
+/** Every inflatable stream in the PDF, as latin1 text. Non-Flate streams (fonts, images) are skipped. */
+function* inflatedStreams(bytes: Uint8Array, raw: string): Generator<string> {
+  // (?<!end): "endstream\n" contains "stream\n"; matching it would misalign every stream after it.
+  const streamRe = /(?<!end)stream\r?\n/g;
+  for (let m = streamRe.exec(raw); m; m = streamRe.exec(raw)) {
+    const start = m.index + m[0].length;
+    const end = raw.indexOf("endstream", start);
+    if (end < 0) return;
+    try {
+      yield inflateSync(bytes.subarray(start, end)).toString("latin1");
+    } catch {
+      // Not a Flate stream.
+    }
+    streamRe.lastIndex = end;
+  }
+}
+
+const PAGES_COUNT = /\/Type\s*\/Pages\b[^]*?\/Count\s+(\d+)|\/Count\s+(\d+)[^]*?\/Type\s*\/Pages\b/g;
+
+function maxCount(text: string): number | null {
+  let best: number | null = null;
+  // Scan each dictionary separately so /Count never pairs with a neighbour's /Type.
+  for (const dict of text.split(/>>|<</)) {
+    for (const m of dict.matchAll(PAGES_COUNT)) {
+      const n = Number(m[1] ?? m[2]);
+      if (best === null || n > best) best = n;
+    }
+  }
+  return best;
+}
+
+/** The root /Pages node holds the total, so the largest /Count wins. */
+export function countPdfPages(bytes: Uint8Array): number | null {
+  const raw = Buffer.from(bytes).toString("latin1");
+  let best = maxCount(raw);
+  for (const text of inflatedStreams(bytes, raw)) {
+    const n = maxCount(text);
+    if (n !== null && (best === null || n > best)) best = n;
+  }
+  return best;
+}
+
+const isPrivateUse = (cp: number) => (cp >= 0xe000 && cp <= 0xf8ff) || cp >= 0xf0000;
+
+/** First code point of a UTF-16BE hex string from a ToUnicode CMap, e.g. "D83DDE00" → 0x1F600. */
+function firstCodePoint(hex: string): number {
+  const hi = parseInt(hex.slice(0, 4), 16);
+  if (hi >= 0xd800 && hi <= 0xdbff && hex.length >= 8) {
+    return 0x10000 + ((hi - 0xd800) << 10) + (parseInt(hex.slice(4, 8), 16) - 0xdc00);
+  }
+  return hi;
+}
+
+/**
+ * Private-use code points that glyphs map to in the PDF's ToUnicode CMaps.
+ * Text drawn with such glyphs looks right but copies out (and parses, for ATS)
+ * as garbage — typically OpenType alternates such as case-sensitive punctuation.
+ */
+export function findPrivateUseMappings(bytes: Uint8Array): number[] {
+  const raw = Buffer.from(bytes).toString("latin1");
+  const found = new Set<number>();
+  for (const cmap of inflatedStreams(bytes, raw)) {
+    if (!cmap.includes("begincmap")) continue;
+    for (const [, block] of cmap.matchAll(/beginbfchar([^]*?)endbfchar/g)) {
+      for (const [, , dst] of block.matchAll(/<([0-9A-Fa-f]+)>\s*<([0-9A-Fa-f]+)>/g)) {
+        const cp = firstCodePoint(dst);
+        if (isPrivateUse(cp)) found.add(cp);
+      }
+    }
+    for (const [, block] of cmap.matchAll(/beginbfrange([^]*?)endbfrange/g)) {
+      for (const [, lo, hi, dst, list] of block.matchAll(/<([0-9A-Fa-f]+)>\s*<([0-9A-Fa-f]+)>\s*(?:<([0-9A-Fa-f]+)>|\[([^\]]*)\])/g)) {
+        const targets = dst !== undefined
+          ? Array.from({ length: parseInt(hi, 16) - parseInt(lo, 16) + 1 }, (_, i) => firstCodePoint(dst) + i)
+          : [...list.matchAll(/<([0-9A-Fa-f]+)>/g)].map(m => firstCodePoint(m[1]));
+        for (const cp of targets) if (isPrivateUse(cp)) found.add(cp);
+      }
+    }
+  }
+  return [...found].sort((a, b) => a - b);
+}

package/src/rendering/assets.ts

@@ -0,0 +1,4 @@
+import { join, resolve } from "node:path";
+
+export const TEMPLATE_DIR = resolve(import.meta.dir, "../../template");
+export const FONT_DIR = join(TEMPLATE_DIR, "fonts");