Files
e2e/scripts/check-error-codes.ts
0a5ee16387 refactor: move e2e's core into @e2e-dev/core, and engines peer on it (#1737)
* refactor: move e2e's core into @e2e-dev/core, and engines peer on it

The engine contract, locators, agent, replay cache, secrets, and the
session half of a worker move from packages/e2e to packages/core, the new
@e2e-dev/core package, at the same paths. e2e depends on it at its exact
version (a changesets fixed group) and reaches its modules through
@e2e-dev/core/lib/*, which is not public API; e2e/engine and e2e/agent
re-export it. @e2e-dev/web and @e2e-dev/mobile peer on @e2e-dev/core and
import the contract from @e2e-dev/core/engine. Install smoke checks that one
copy of @e2e-dev/core is installed.

Most of this diff is git mv and import specifiers rewritten to
@e2e-dev/core/lib/<path>; no behavior changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: build and pack @e2e-dev/core where e2e is built or packed alone

The Bun job built e2e before the @e2e-dev/core it compiles against, and the
examples nightly installs e2e from a tarball whose exact @e2e-dev/core is
not on npm; it now packs @e2e-dev/core and overrides it in each example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(engines): name @e2e-dev/core/engine as the contract's source

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(e2e): list @e2e-dev/core beside an engine in init and upgrade

Engines peer on @e2e-dev/core. Yarn installs no peer the project does
not list, and under Plug'n'Play the engine then fails to load.

- init adds @e2e-dev/core with any engine
- upgrade adds a required @e2e-dev peer the project lacks, and keeps a
  package e2e depends on at the version e2e names

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
2026-11-15 18:31:58 +00:00

140 lines
5.0 KiB
TypeScript

/**
* Asserts that the error reference documents every code the runner can raise,
* and names no code the runner cannot.
*
* The inventory is read from the source, not from a hand-kept list:
* `AgentErrorCode` (`src/types.ts`), `ENGINE_ERROR_CODES` (`src/engine/contract.ts`),
* and every literal handed to the `E2EError` family across the published packages.
* Runner codes are plain strings by design, so the constructor-argument scan
* is the closest thing to a union they have.
*
* Usage: `node scripts/check-error-codes.ts`. Exits 1 on the first
* discrepancy, listing every missing and every unknown code.
*/
import { readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { sourceRoots } from './error-codes.ts';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const TYPES_FILE = 'packages/core/src/types.ts';
const CONTRACT_FILE = 'packages/core/src/engine/contract.ts';
const ERRORS_PAGE = 'docs/reference/errors.mdx';
const ENGINE_PAGE = 'docs/reference/engine.mdx';
const CODE_PATTERN = /'([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*)'/g;
function read(path: string): string {
return readFileSync(join(ROOT, path), 'utf8');
}
function literals(text: string): string[] {
return [...text.matchAll(CODE_PATTERN)].map((match) => match[1]!);
}
/** Every `.ts` source file under the published packages, tests excluded. */
function sourceFiles(): string[] {
const files: string[] = [];
const walk = (dir: string): void => {
for (const entry of readdirSync(join(ROOT, dir), { withFileTypes: true })) {
const path = join(dir, entry.name);
if (entry.isDirectory()) walk(path);
else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')) files.push(path);
}
};
for (const root of sourceRoots()) walk(root);
return files;
}
/** Members of the `AgentErrorCode` union. */
function agentCodes(): Set<string> {
const match = /export type AgentErrorCode =([^;]+);/.exec(read(TYPES_FILE));
if (match === null) throw new Error(`AgentErrorCode union not found in ${TYPES_FILE}`);
return new Set(literals(match[1]!));
}
/** Members of the `ENGINE_ERROR_CODES` tuple. */
function engineCodes(): Set<string> {
const match = /export const ENGINE_ERROR_CODES = \[([^\]]+)\] as const;/.exec(read(CONTRACT_FILE));
if (match === null) throw new Error(`ENGINE_ERROR_CODES not found in ${CONTRACT_FILE}`);
return new Set(literals(match[1]!));
}
/**
* Codes handed to the runner's error classes: the first argument of
* `ConfigurationError`, `InfrastructureError`, and `TestError`, the second of
* `E2EError`, a subclass `super(...)`, and a parameter typed as a union of
* codes (`code: 'LAUNCH_TIMEOUT' | 'CLEANUP_TIMEOUT'`).
*/
function runnerCodes(): Map<string, string[]> {
const patterns = [
/new (?:ConfigurationError|InfrastructureError|TestError)\(\s*'([A-Z_]+)'/g,
/new E2EError\(\s*'[a-z]+',\s*'([A-Z_]+)'/g,
/\bsuper\(\s*'([A-Z_]+)'/g,
/\bcode:\s*('[A-Z_]+'(?:\s*\|\s*'[A-Z_]+')+)/g,
];
const found = new Map<string, string[]>();
for (const file of sourceFiles()) {
const text = read(file);
for (const pattern of patterns) {
for (const match of text.matchAll(pattern)) {
for (const code of literals(match[0])) {
const sites = found.get(code) ?? [];
if (!sites.includes(file)) sites.push(file);
found.set(code, sites);
}
}
}
}
return found;
}
/** Backticked codes on a docs page: `` `SOME_CODE` ``. */
function documentedCodes(page: string): Set<string> {
const text = read(page);
return new Set(
[...text.matchAll(/`([A-Z][A-Z0-9_]{2,})`/g)]
.map((match) => match[1]!)
.filter((code) => !code.startsWith('E2E_')),
);
}
function main(): number {
const agent = agentCodes();
const engine = engineCodes();
const runner = runnerCodes();
const errorsPage = documentedCodes(ERRORS_PAGE);
const enginePage = documentedCodes(ENGINE_PAGE);
const problems: string[] = [];
for (const code of [...agent].toSorted()) {
if (!errorsPage.has(code)) problems.push(`${ERRORS_PAGE}: AgentErrorCode ${code} is not documented`);
}
for (const [code, sites] of [...runner].toSorted(([a], [b]) => a.localeCompare(b))) {
if (!errorsPage.has(code)) {
problems.push(`${ERRORS_PAGE}: runner code ${code} is not documented (raised in ${sites.join(', ')})`);
}
}
for (const code of [...engine].toSorted()) {
if (!enginePage.has(code)) problems.push(`${ENGINE_PAGE}: engine code ${code} is not documented`);
}
const known = new Set([...agent, ...engine, ...runner.keys()]);
for (const code of [...errorsPage].toSorted()) {
if (!known.has(code)) problems.push(`${ERRORS_PAGE}: ${code} is documented but no source raises it`);
}
if (problems.length > 0) {
process.stderr.write(`${problems.join('\n')}\n`);
return 1;
}
process.stdout.write(
`error codes: ${known.size} in source (${agent.size} agent, ${runner.size} runner, ${engine.size} engine), all documented in ${ERRORS_PAGE} and ${ENGINE_PAGE}\n`,
);
return 0;
}
process.exitCode = main();