@scinorandex/sparse 0.1.1 → 0.1.3

package/src/table/selfhosted.ts

@@ -1,7 +1,9 @@
-import { GrammarToken } from "../meta/common";
+import { GrammarToken, Production, describeThrowable, syntheticGrammarToken } from "../meta/common";
 import { BaseNode, getSelfHostedParserGenerator, grammarLexerGenerator, ListNode } from "../meta/selfhosted";
-import { TableAction, TableState } from "../parser";
+import { LR1ParserGraveError, TableAction, TableState } from "../parser";
 import { selfhosted } from "./states";
+import { Result } from "../utils/Result";
+import { TableFormatWarning, validateTableStates } from "./validate";
 
 class StateNode extends BaseNode {
   constructor(public readonly items: ListNode<ItemNode>) {
@@ -10,9 +12,11 @@ class StateNode extends BaseNode {
 
   toTableState(): TableState {
     const state = new TableState();
-    for (const item of this.items.getItems()) {
+    // The item list is built right-recursively (rest.add(item)), so it comes out reversed.
+    for (const item of this.items.getItemsReversed()) {
       const key = item.type === "terminal" ? `[${item.name.lexeme}]` : `<${item.name.lexeme}>`;
       state.actions.set(key, item.action);
+      state.rawActions.set(key, item.rawAction);
     }
     return state;
   }
@@ -23,6 +27,7 @@ class ItemNode extends BaseNode {
     public readonly type: "terminal" | "variable",
     public readonly name: GrammarToken,
     public readonly action: TableAction,
+    public readonly rawAction: string,
   ) {
     super();
   }
@@ -46,22 +51,53 @@ const reducers: { [key: string]: Reducer } = {
       type: bag.action.lexeme.startsWith("s") ? "shift" : "reduce",
       value: parseInt(bag.action.lexeme.substring(1)),
     };
-    return new ItemNode("terminal", bag.name, action);
+    return new ItemNode("terminal", bag.name, action, bag.action.lexeme);
   },
 
   variable: (bag: { name: GrammarToken; state: GrammarToken }) => {
     const action: TableAction = { type: "goto", value: parseInt(bag.state.lexeme) };
-    return new ItemNode("variable", bag.name, action);
+    return new ItemNode("variable", bag.name, action, bag.state.lexeme);
   },
 };
 
-export const buildStates = (grammar: string): TableState[] => {
-  const lexer = grammarLexerGenerator.generate(grammar, () => ({}));
+export type BuildStatesOptions = {
+  /** Pass the grammar's productions to also check every "reduce" action against them. */
+  productions?: Production[];
+  /** Name of the file the table was read from, used to make error messages actionable. */
+  source?: string;
+  onWarning?: (warning: TableFormatWarning) => void;
+};
+
+/**
+ * Reads a parsing table written by the CLI (`sparse --input=grammar.txt --output=table.txt`).
+ * Returns a `Result` instead of throwing so that table problems can be reported alongside the
+ * offending grammar line.
+ */
+export const tryBuildStates = (table: string, options: BuildStatesOptions = {}): Result<TableState[]> => {
+  const lexer = grammarLexerGenerator.generate(table, () => ({}));
   const parserGenerator = getSelfHostedParserGenerator(selfhosted as any);
-  const parser = parserGenerator.generate(lexer, {
-    reducer: ({ bag, name }) => reducers[name ?? ""](bag),
-  });
 
-  const parsingResult = (parser.parse().result as ListNode<StateNode>).getItemsReversed();
-  return parsingResult.map((state) => state.toTableState());
+  let states: ListNode<StateNode>;
+  try {
+    const parser = parserGenerator.generate(lexer, {
+      reducer: ({ bag, name }) => reducers[name ?? ""](bag),
+    });
+    states = parser.parse().result as ListNode<StateNode>;
+  } catch (err) {
+    if (err instanceof LR1ParserGraveError && err.currentToken != null)
+      return { success: false, reason: err.reason, token: err.currentToken as GrammarToken };
+    return { success: false, reason: describeThrowable(err), token: syntheticGrammarToken() };
+  }
+
+  const tableStates = states.getItemsReversed().map((state) => state.toTableState());
+  return validateTableStates(tableStates, options);
+};
+
+export const buildStates = (table: string, options: BuildStatesOptions = {}): TableState[] => {
+  const result = tryBuildStates(table, options);
+  if (result.success === false)
+    throw new Error(
+      `Encountered error "${result.reason}" while parsing the parsing table at ${result.token.line}:${result.token.column}`,
+    );
+  return result.value;
 };

package/src/table/validate.ts

@@ -0,0 +1,143 @@
+import { GrammarToken, syntheticGrammarToken } from "../meta/common";
+import type { Production } from "../meta/common";
+import type { TableAction, TableState } from "../parser";
+import { Result } from "../utils/Result";
+
+const SHIFT_REDUCE_RE = /^([sr])(\d+)$/;
+const GOTO_RE = /^(\d+)$/;
+
+const defaultRawAction = (action: TableAction): string =>
+  `${action.type === "goto" ? "" : action.type === "shift" ? "s" : "r"}${action.value}`;;
+
+const STATE_NAME_PATTERN = /^(\[[^\]]+\]|<[^>]+>)$/;
+
+export type TableFormatWarning = { reason: string; stateIndex: number };
+
+export type ValidateTableStatesOptions = {
+  /** When provided, every "reduce" action is checked against the number of productions. */
+  productions?: Production[];
+  /** Name of the file the table was read from, used to make error messages actionable. */
+  source?: string;
+  onWarning?: (warning: TableFormatWarning) => void;
+};
+
+/**
+ * Validates the shape of a parsing table: action syntax, and that every state a transition points
+ * at actually exists. Without this, a typo in a table file silently turns into nonsense behavior
+ * (`[A]=q3` becomes "reduce by production 3", `[A]=sX` becomes "shift to state NaN").
+ */
+export const validateTableStates = (
+  states: TableState[],
+  options: ValidateTableStatesOptions = {},
+): Result<TableState[]> => {
+  const { productions, source } = options;
+  const suffix = source == null ? "" : ` in ${source}`;
+  const stateCount = states.length;
+
+  const fail = (reason: string, stateIndex: number): Result<TableState[]> => ({
+    success: false,
+    reason: `${reason}${suffix}`,
+    token: tokenFor(stateIndex, productions),
+  });
+
+  if (stateCount === 0)
+    return {
+      success: false,
+      reason: `The parsing table${suffix} does not contain any states`,
+      token: syntheticGrammarToken(),
+    };
+
+  for (let stateIndex = 0; stateIndex < stateCount; stateIndex++) {
+    const state = states[stateIndex];
+    if (state == null) return fail(`State ${stateIndex} is missing`, stateIndex);
+
+    if (stateIndex === 0 && state.actions.size === 0)
+      return fail("State 0 has no actions, so the parser cannot read the first token", stateIndex);
+
+    for (const [key, action] of state.actions.entries()) {
+      const nameMatch = STATE_NAME_PATTERN.exec(key);
+      if (nameMatch == null)
+        return fail(
+          `State ${stateIndex} has the entry "${key}", which is neither a terminal "[NAME]" nor a variable "<NAME>"`,
+          stateIndex,
+        );
+
+      const isVariable = nameMatch[1].startsWith("<");
+      if (isVariable !== (action.type === "goto"))
+        return fail(
+          `State ${stateIndex} maps the variable "${key}" to a "${action.type}" action, but variables can only be reached by a "goto" action`,
+          stateIndex,
+        );
+
+      // Prefer the text the user actually wrote: "[A]=q3" parses into a "reduce 3" action that
+      // looks valid unless you remember that "q3" is not a valid action.
+      const raw = state.rawActions.get(key) ?? defaultRawAction(action);
+      const expected = isVariable ? GOTO_RE : SHIFT_REDUCE_RE;
+      if (expected.test(raw) === false || Number.isInteger(action.value) === false)
+        return fail(
+          `State ${stateIndex} has the action "${key}=${raw}" for ${isVariable ? "a variable" : "a terminal"}, but it should be ${
+            isVariable ? "a state number" : '"sN" (shift) or "rN" (reduce)'
+          }`,
+          stateIndex,
+        );
+
+      if (isVariable || action.type === "shift") {
+        if (action.value >= stateCount)
+          return fail(
+            `State ${stateIndex} sends "${key}" to state ${action.value}, but the table only has ${stateCount} states (0 to ${stateCount - 1})`,
+            stateIndex,
+          );
+      } else if (productions != null && action.value >= productions.length)
+        return fail(
+          `State ${stateIndex} reduces "${key}" by production ${action.value}, but the grammar only has ${productions.length} productions (0 to ${productions.length - 1}). Is the table stale?`,
+          stateIndex,
+        );
+    }
+
+    const shiftTargets = new Set<number>();
+    for (const action of state.actions.values()) {
+      if (action.type !== "shift") continue;
+      if (shiftTargets.has(action.value))
+        options.onWarning?.({
+          reason: `State ${stateIndex} has two terminals that shift to state ${action.value}`,
+          stateIndex,
+        });
+      shiftTargets.add(action.value);
+    }
+  }
+
+  return { success: true, value: states };
+};
+
+export type ValidateTableOptions = { source?: string };
+
+/**
+ * Cross-checks a prebuilt parsing table against the productions it is supposed to belong to.
+ * Catches the class of bug where a table is regenerated but the grammar is not (or vice versa),
+ * which otherwise shows up as an opaque crash in the middle of a parse.
+ */
+export const validateTable = (
+  productions: Production[],
+  states: TableState[],
+  options: ValidateTableOptions = {},
+): Result<TableState[]> => {
+  const statesResult = validateTableStates(states, { ...options, productions });
+  if (statesResult.success === false) return statesResult;
+
+  const suffix = options.source == null ? "" : ` in ${options.source}`;
+  if (productions.length === 0)
+    return {
+      success: false,
+      reason: `The grammar${suffix} does not contain any productions, so the table cannot belong to it`,
+      token: syntheticGrammarToken(),
+    };
+
+  return { success: true, value: states };
+};
+
+/** Errors about a table are reported against the closest grammar token, or 1:1 when unavailable. */
+const tokenFor = (stateIndex: number, productions: Production[] | undefined): GrammarToken => {
+  if (productions != null && productions.length > 0)
+    return productions[Math.min(stateIndex, productions.length - 1)].lhs;
+  return syntheticGrammarToken();
+};

package/src/utils/Stack.ts

@@ -17,7 +17,27 @@ export class Stack<T> {
     return ret;
   }
 
+  /** Reads `depth` items below the top of the stack. Depth 0 is the top. */
+  public peekAt(depth: number): T {
+    const ret = this.items[this.items.length - 1 - depth];
+    if (ret === undefined) throw new Error(`Stack does not have an item at depth ${depth}`);
+    return ret;
+  }
+
+  public get size() {
+    return this.items.length;
+  }
+
+  public get isEmpty() {
+    return this.items.length === 0;
+  }
+
+  /** A copy of the stack, bottom first. Useful for error reporting inside a recovery function. */
+  public toArray(): T[] {
+    return [...this.items];
+  }
+
   constructor(items: T[] = []) {
-    this.items = items;
+    this.items = [...items];
   }
-}
+}

package/src/utils/errorWindowBuilder.ts

@@ -1,23 +1,25 @@
 import { GrammarToken } from "../meta/common";
 
+/**
+ * Renders the lines around a grammar token and points at the token itself, so that a syntax or
+ * table error tells the user exactly which part of their file to look at.
+ */
 export const buildErrorWindow = (file: string, token: GrammarToken) => {
   const lines = file.split("\n");
+  const lineNumberWidth = `${token.line}`.length;
+  const gutter = (line: number) => `${`${line}`.padStart(lineNumberWidth)} | `;
 
-  const length = Math.max(`${token.line}`.length, `${token.column}`.length);
-  let second = "",
-    third = "";
+  const sourceLine = lines[token.line - 1];
+  const nextLine = lines[token.line];
 
-  for (let i = 0; i < token.column + length + 3; i++) {
-    second += " ";
-    third += "-";
-  }
-  second += "|";
-  third += "┘";
+  const pointerColumn = Math.max(0, Math.min(token.column, sourceLine === undefined ? 0 : sourceLine.length));
+  const pointerLength = Math.max(1, Math.min(token.lexeme === "" ? 1 : token.lexeme.length, sourceLine === undefined ? 1 : sourceLine.length - pointerColumn));
+  const pointer = `${" ".repeat(pointerColumn)}${"~".repeat(pointerLength)}`;
 
-  let window = `${token.line.toString().padStart(length)} | ${
-    lines.length <= token.line - 1 ? "" : lines[token.line - 1]
-  }\n${second}\n${third}\n`;
+  let window = `${gutter(token.line)}${sourceLine ?? "<end of file>"}\n`;
+  window += `${" ".repeat(lineNumberWidth)} | ${pointer}\n`;
+
+  if (nextLine !== undefined) window += `${gutter(token.line + 1)}${nextLine}\n`;
 
-  if (token.line < lines.length) window += `${(token.line + 1).toString().padStart(length)} | ${lines[token.line]}\n`;
   return window;
 };

package/src/utils/loadFiles.ts

@@ -0,0 +1,54 @@
+import fs from "fs/promises";
+import { Production, ValidateProductionsOptions, syntheticGrammarToken } from "../meta/common";
+import { Result } from "./Result";
+import { BuildStatesOptions, tryBuildStates } from "../table/selfhosted";
+import { tryBuildProductions } from "../meta/selfhosted";
+import type { TableState } from "../parser";
+
+export type LoadGrammarOptions = ValidateProductionsOptions;
+
+/** Reads a `.txt` grammar file and turns it into productions, reporting problems as a `Result`. */
+export const loadGrammar = async (
+  grammarPath: string,
+  options: LoadGrammarOptions = {},
+): Promise<Result<Production[]>> => {
+  let source: string;
+  try {
+    source = await fs.readFile(grammarPath, "utf8");
+  } catch (err) {
+    return {
+      success: false,
+      reason: `Could not read the grammar file: ${err instanceof Error ? err.message : String(err)}`,
+      token: syntheticGrammarToken(),
+    };
+  }
+
+  const result = tryBuildProductions(source, options);
+  if (result.success === false)
+    return { ...result, reason: `${result.reason} (in ${grammarPath})` };
+  return result;
+};
+
+export type LoadTableOptions = Omit<BuildStatesOptions, "source">;
+
+/** Reads a parsing table file written by the CLI, reporting problems as a `Result`. */
+export const loadTable = async (
+  tablePath: string,
+  options: LoadTableOptions = {},
+): Promise<Result<TableState[]>> => {
+  let source: string;
+  try {
+    source = await fs.readFile(tablePath, "utf8");
+  } catch (err) {
+    return {
+      success: false,
+      reason: `Could not read the parsing table file: ${err instanceof Error ? err.message : String(err)}`,
+      token: syntheticGrammarToken(),
+    };
+  }
+
+  const result = tryBuildStates(source, { ...options, source: tablePath });
+  if (result.success === false)
+    return { ...result, reason: `${result.reason} (in ${tablePath})` };
+  return result;
+};

package/src/utils/reducers.ts

@@ -0,0 +1,93 @@
+import { Production } from "../meta/common";
+
+export const KLEENE_REDUCER_NAME = "autogenerated-kleene";
+
+/** The names of every production that has a `: name` in the grammar file. */
+export const namedProductions = (productions: Production[]): string[] => {
+  const names = new Set<string>();
+  for (const production of productions)
+    if (production.name != null) names.add(production.name);
+  return [...names].sort();
+};
+
+/** Every named production in the grammar that `reducers` does not have a reducer for. */
+export const missingReducerNames = (
+  productions: Production[],
+  reducers: Record<string, unknown>,
+): string[] => namedProductions(productions).filter((name) => reducers[name] == null);
+
+const describeKleene = (productions: Production[]) => {
+  const needed = productions.filter(
+    (production) =>
+      production.name === KLEENE_REDUCER_NAME ||
+      production.identifier.startsWith("<autogen-"),
+  );
+  if (needed.length === 0) return "";
+
+  return `\nNote: this grammar uses "*" or "+", so it has ${needed.length} autogenerated list production(s) named "${KLEENE_REDUCER_NAME}". That reducer has to flatten the list it is handed (see README, "Repetition with * and +").`;
+};
+
+export const missingReducerMessage = (
+  productions: Production[],
+  reducers: Record<string, unknown>,
+): string => {
+  const missing = missingReducerNames(productions, reducers);
+  if (missing.length === 0) return "";
+
+  const has = namedProductions(productions).filter((name) => reducers[name] != null);
+  const kleene = missing.includes(KLEENE_REDUCER_NAME) ? describeKleene(productions) : "";
+
+  return (
+    `No reducer for ${missing.length === 1 ? "production" : "productions"} ${missing
+      .map((name) => `"${name}"`)
+      .join(", ")}.` +
+    `\nReducers are keyed by the name given in the grammar, e.g. "<PROGRAM: program>" is reduced by reducers.program.` +
+    (has.length === 0 ? "\nYour reducer map is empty." : `\nYou have reducers for: ${has.join(", ")}.`) +
+    kleene
+  );
+};
+
+export type ReducerMap<Node> = Record<string, (newInput: any, oldInput: any) => Node>;
+
+/**
+ * Wraps a map of reducers into the single reducer that `Sparse.generate` expects, keyed by the
+ * `: name` of each production in the grammar.
+ *
+ * A missing entry is reported by production name instead of surfacing as
+ * `reducers[name] is not a function` from deep inside the parse.
+ */
+export const defineReducers = <Reducers extends Record<string, (...args: never[]) => unknown>>(reducers: Reducers) =>
+  function sparseReducer(newInput: any, oldInput: any): any {
+    const name: string | null | undefined = newInput?.name;
+    const lookup = reducers as unknown as Record<string, (a: any, b: any) => any>;
+    const reducer = name == null ? undefined : lookup[name];
+    if (reducer == null)
+      throw new Error(
+        `No reducer for production "${name ?? ""}" (production ${oldInput?.index}). Reducers are keyed by the name given in the grammar.`,
+      );
+    return reducer(newInput, oldInput);
+  };
+
+/**
+ * Throws a descriptive error if `reducers` is missing any production the grammar names.
+ * Useful as a one-time check right after loading the grammar.
+ */
+export const assertReducersCoverGrammar = (productions: Production[], reducers: ReducerMap<unknown>) => {
+  const message = missingReducerMessage(productions, reducers);
+  if (message !== "") throw new Error(message);
+};
+
+/**
+ * The stringifier every example used to write by hand: `(type) => TokenType[type]`.
+ * Numeric TypeScript enums store their names in reverse, so a plain lookup is all it takes.
+ *
+ * ```ts
+ * const toStringifiedTokenType = enumToString<TokenType>(TokenType);
+ * ```
+ */
+export const enumToString =
+  <TokenType = unknown>(tokenTypes: object) =>
+  (tokenType: TokenType): string => {
+    const name = (tokenTypes as Record<string, unknown>)[tokenType as unknown as string];
+    return `${name ?? tokenType}`;
+  };

package/test/cli.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, beforeAll } from "vitest";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { examplePath, root } from "./helpers";
+
+const exec = promisify(execFile);
+
+let cli = path.join(root, "dist/cli.js");
+let tmp: string;
+
+type Run = { code: number; stdout: string; stderr: string };
+
+const run = async (...args: string[]): Promise<Run> => {
+  try {
+    const { stdout, stderr } = await exec("node", [cli, ...args], { cwd: root });
+    return { code: 0, stdout, stderr };
+  } catch (err) {
+    const failure = err as { code?: number; stdout: string; stderr: string };
+    return { code: failure.code ?? 1, stdout: failure.stdout ?? "", stderr: failure.stderr ?? "" };
+  }
+};
+
+beforeAll(async () => {
+  await exec("node", ["node_modules/typescript/bin/tsc", "-p", "tsconfig.build.json"], { cwd: root });
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), "sparse-cli-"));
+}, 180_000);
+
+describe("the sparse CLI", () => {
+  it("prints usage for --help and exits successfully", async () => {
+    const result = await run("--help");
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("Usage: npx @scinorandex/sparse --input=<grammar> --output=<table>");
+    expect(result.stdout).toContain("--lalr");
+    expect(result.stdout).toContain("--check");
+  });
+
+  it("fails with usage when --input is missing", async () => {
+    const result = await run("--output=" + path.join(tmp, "table.txt"));
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("Missing --input");
+  });
+
+  it("fails when the grammar does not exist", async () => {
+    const result = await run(`--input=${path.join(tmp, "nope.txt")}`, `--output=${path.join(tmp, "table.txt")}`);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("does not exist");
+  });
+
+  it("creates the output directory", async () => {
+    const output = path.join(tmp, "nested", "deeper", "table.txt");
+    const result = await run(`--input=${examplePath("math/grammar.txt")}`, `--output=${output}`);
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("22 LR(1) states");
+    expect(await fs.readFile(output, "utf8")).toBe(await fs.readFile(examplePath("math/table.txt"), "utf8"));
+  });
+
+  it("reproduces the committed math table", async () => {
+    const output = path.join(tmp, "math.txt");
+    await run(`--input=${examplePath("math/grammar.txt")}`, `--output=${output}`);
+
+    expect((await fs.readFile(output, "utf8")).trim()).toBe(
+      (await fs.readFile(examplePath("math/table.txt"), "utf8")).trim(),
+    );
+  });
+
+  it("prints the table to stdout", async () => {
+    const result = await run(`--input=${examplePath("math/grammar.txt")}`, "--stdout");
+    expect(result.code).toBe(0);
+    expect(result.stdout.trim()).toBe((await fs.readFile(examplePath("math/table.txt"), "utf8")).trim());
+  });
+
+  it("shows a window into the grammar when the grammar is broken", async () => {
+    const grammarPath = path.join(tmp, "broken.txt");
+    await fs.writeFile(grammarPath, "<S>: <PROGRAM>;\n<PROGRAM: program>: [NUMBER] (;\n");
+
+    const result = await run(`--input=${grammarPath}`, `--output=${path.join(tmp, "broken-table.txt")}`);
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("Invalid syntax at 2:30");
+    expect(result.stderr).toContain("<PROGRAM: program>: [NUMBER] (");
+    expect(result.stderr).toContain("~");
+    expect(result.stderr).not.toContain("at Object.");
+  });
+
+  it("reports a grammar that references an undefined variable", async () => {
+    const grammarPath = path.join(tmp, "dangling.txt");
+    await fs.writeFile(grammarPath, "<S>: <PROGRAM>;\n<PROGRAM: program>: [NUMBER] <NOPE> [EOF];\n");
+
+    const result = await run(`--input=${grammarPath}`, `--output=${path.join(tmp, "dangling-table.txt")}`);
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain(`Variable "<NOPE>"`);
+  });
+
+  it("warns about a suspicious grammar rule but still writes the table", async () => {
+    const grammarPath = path.join(tmp, "duplicate.txt");
+    const output = path.join(tmp, "duplicate-table.txt");
+    await fs.writeFile(grammarPath, "<S>: <PROGRAM>;\n<PROGRAM: program>: [NUMBER: n] [EOF: n];\n");
+
+    const result = await run(`--input=${grammarPath}`, `--output=${output}`);
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toContain("names more than one symbol");
+
+    const quiet = await run(`--input=${grammarPath}`, `--output=${output}`, "--quiet");
+    expect(quiet.stderr).toBe("");
+  });
+
+  it("accepts a table that is up to date with --check", async () => {
+    const output = path.join(tmp, "check.txt");
+    await run(`--input=${examplePath("math/grammar.txt")}`, `--output=${output}`);
+
+    const result = await run(`--input=${examplePath("math/grammar.txt")}`, `--output=${output}`, "--check");
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("is up to date");
+  });
+
+  it("reports a stale table with --check", async () => {
+    const grammar = "<S>: <PROGRAM>;\n<PROGRAM: program>: [NUMBER] [EOF];\n";
+    const grammarPath = path.join(tmp, "check-grammar.txt");
+    const output = path.join(tmp, "check-stale.txt");
+    await fs.writeFile(grammarPath, grammar);
+    await fs.writeFile(output, "[EOF]=r0\n");
+
+    const result = await run(`--input=${grammarPath}`, `--output=${output}`, "--check");
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("is out of date");
+  });
+
+  it("reports a table file that is not a table", async () => {
+    const grammarPath = path.join(tmp, "check-grammar2.txt");
+    const output = path.join(tmp, "check-garbage.txt");
+    await fs.writeFile(grammarPath, "<S>: <PROGRAM>;\n<PROGRAM: program>: [EOF];\n");
+    await fs.writeFile(output, "hello world\n");
+
+    const result = await run(`--input=${grammarPath}`, `--output=${output}`, "--check");
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("not a valid parsing table");
+  });
+});

package/test/codegen.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import fs from "fs/promises";
+import { buildStates, dehydateProduction, generateStates, tryBuildProductions } from "../src/index";
+import { grammarLexerGenerator } from "../src/meta/selfhosted";
+import { selfhosted as metaSelfHosted } from "../src/meta/states";
+import { selfhosted as tableSelfHosted } from "../src/table/states";
+import { examplePath, readFile } from "./helpers";
+
+/**
+ * Mirrors example/selfhosted/example.ts: the LR(1) states that Sparse uses to read its own grammar
+ * and table file formats are generated from the grammar files in example/selfhosted, and the copies
+ * checked into src/ have to be identical. If this test fails, the bootstrap is broken: either the
+ * grammar files changed without regenerating the states, or the states changed without updating
+ * the grammar files.
+ */
+const regen = async (grammarName: string) => {
+  const grammar = await readFile(grammarName);
+  const lexer = grammarLexerGenerator.generate(grammar, () => ({}));
+
+  const productionsResult = tryBuildProductions(lexer);
+  if (productionsResult.success === false) throw new Error(productionsResult.reason);
+  const productions = productionsResult.value;
+
+  const statesResult = generateStates(productions);
+  if (statesResult.success === false) throw new Error(statesResult.reason);
+
+  return {
+    states: statesResult.value.toJSObject(),
+    productions: productions.map(dehydateProduction),
+  };
+};
+
+describe("self hosted code generation", () => {
+  it("regenerates the states checked into src/meta/states.ts byte for byte", async () => {
+    const regenerated = await regen("selfhosted/01-meta-grammar.txt");
+
+    expect(regenerated).toEqual({ states: metaSelfHosted.states, productions: metaSelfHosted.productions });
+  });
+
+  it("regenerates the states checked into src/table/states.ts byte for byte", async () => {
+    const regenerated = await regen("selfhosted/02-table-grammar.txt");
+
+    expect(regenerated).toEqual({ states: tableSelfHosted.states, productions: tableSelfHosted.productions });
+  });
+
+  it("keeps the committed codegen files in example/selfhosted in sync", async () => {
+    for (const [grammarName, codegenName] of [
+      ["selfhosted/01-meta-grammar.txt", "selfhosted/codegen-meta.ts"],
+      ["selfhosted/02-table-grammar.txt", "selfhosted/codegen-table.ts"],
+    ]) {
+      const regenerated = await regen(grammarName as string);
+      const source = `export const states = ${JSON.stringify(regenerated.states, null, 2)};
+    export const productions = ${JSON.stringify(regenerated.productions, null, 2)};
+    export const selfhosted = { states, productions };`;
+
+      expect(await fs.readFile(examplePath(codegenName as string), "utf8")).toBe(source);
+    }
+  });
+
+  it("produces tables the library can read back", async () => {
+    const regenerated = await regen("selfhosted/01-meta-grammar.txt");
+
+    const fromJson = buildStates(
+      regenerated.states
+        .map((state) =>
+          Object.entries(state)
+            .map(([key, action]) => `${key}=${action.type === "goto" ? "" : action.type === "shift" ? "s" : "r"}${action.value}`)
+            .join(", "),
+        )
+        .join("\n"),
+    );
+
+    expect(fromJson.length).toBe(regenerated.states.length);
+  });
+});