docs/reference/sources.json pins the guide commit and six upstream rule/test repositories. Each archive has a SHA-256 digest. vendor/manifest.json records the bytes of the frozen guide, inherited sample data, isolated sources, fixture corpus, and port recipes. Normal builds and tests use the committed snapshot and do not fetch upstream source.
The guide's original configuration bytes are retained in docs/reference/eslintrc.upstream.txt. The executable port is docs/reference/eslintrc.ts. Exact reviewed replacements in scripts/reference-patches.json reproduce the typed port, and snapshot checks compare its configuration data with the original sample. The catalog retains the original eslintrc.cjs provenance label and upstream hash. A sample change that no longer matches the port must be reviewed before refresh writes snapshots.
Run pnpm run snapshots:refresh to download the pinned archives, verify their digests, reproduce the vendor files, recapture Airbnb metadata, generate the catalog, build the packages, and recapture the upstream tests. The command uses tsx and does not install or execute an ESLint engine. Run pnpm run check afterward. pnpm run snapshots:refresh --latest-guide deliberately advances the guide commit to the current upstream branch before performing the same steps.
pnpm exec tsx scripts/vendor.ts --source-root .cache/upstream --check independently proves that all isolated files match their sources and reviewed patches. The refresh validates every port before writing vendor files. Exact context replacements fail on missing or ambiguous context. Generated rule registries and the extracted JSDoc helper have source guards that require review when their upstream inputs change.
Recipes may reference a patchesFile containing an ordered JSON array of exact before/after replacements. These replacements run after the recipe's inline patches, and their files are included in the integrity manifest. This keeps larger reviewed ports separate from the source inventory without weakening context checks.
To update a rule-source version, change its version, ref, and directory in the source lock, review the upstream release and dependency requirements, and remove its old archive digest. Run the refresh with --record-archives to record the reviewed new archive. Update the source guards, selected rule registry, relative dependency closure, and compatibility patches in scripts/vendor-recipes.json as required. Keep generator provenance and importer source directories consistent with the new lock. These updates require a maintainer; the weekly job advances the guide while retaining the reviewed rule-source versions.
Port recipes document the following adaptations:
- Core rules are strict TypeScript ES modules. Their source patches preserve the pinned implementations, including literal regex flag spelling. The standalone JSDoc lookup and indentation helpers retain their upstream source guards. Shared ESTree contracts and narrow external-library adapters describe the legacy API supplied by Oxlint. The execution-order rule ignores references used only in type annotations.
- JSDoc rules and helpers are strict TypeScript ES modules. The shared ES2024 compiler target accepts their existing Unicode-set regular expressions under the required Node 24 runtime. Their option types follow the pinned schemas, and their parser contracts include TypeScript and legacy Babel nodes. Type-parser parent links use a WeakMap. The ports retain handling for Oxc's null optional fields and enumerable ClassBody properties; a metadata fingerprint preserves the original schemas, documentation examples, and recommended configuration.
- React rules and helpers are strict TypeScript ES modules with typed component state, options, and parser nodes. The modern report adapter avoids engine discovery. Metadata and recommended configurations retain their pinned values. A narrow external CommonJS bridge loads the iterator helper entrypoints that are provided as runtime dependencies.
- Import rules and module utilities are strict TypeScript ES modules. Typed resolver results, parser contracts, export maps, and dependency traversal retain the pinned rule behavior and metadata. The private Oxc resolver and comment reader live in
vendor/import/compat; they remain included in adapter coverage. External CommonJS bridges load consumer-selected parsers, resolvers, and optional package metadata.
The TypeScript adapters separately preserve scope metadata, explicit global directives, legacy context methods, and incremental code-path segment observations. All these paths are tested through Oxlint. Build-time dependencies are bundled into the plugin; declared runtime dependencies remain external. The build rejects engine imports and emits third-party notices from the actual bundle inputs.
The importer records unsupported grammar/parser capabilities in tests/fixtures/import-report.json, including a source rule, source file, code hash, and reason for every exclusion. Exclusions are selected from parser metadata and grammar capabilities, never from whether a lint assertion passes. Count-only assertions preserve the upstream diagnostic count. Any fixture-capture failure fails the command. New auxiliary rules must be represented in the harness rather than silently dropping their diagnostics or fixes.
The weekly GitHub workflow opens a signed draft PR, runs acceptance checks, and explicitly dispatches the full Linux/Windows/macOS matrix for the update branch. It never merges or publishes. Repository Actions settings must allow workflow-created pull requests. A failed refresh or check remains visible as a failed workflow, and any resulting draft must be reviewed before merge.
Review the generated rule catalog, effective sample options and disabled rules, fixture changes, exclusions, source/patch hashes, license notices, and all platform checks. Use pnpm run snapshots:record only after intentionally reviewing a snapshot change; normal checks reject drift.
Local commits use git commit -S and include Co-authored-by: Codex <codex@openai.com>. Published packages are prepared with pnpm pack; publication is a separate maintainer action.
All 540 JavaScript sources from the migration baseline now have TypeScript ports: 308 core files, 44 JSDoc files, 133 React files, 54 import files, and the reference configuration. Emitted JavaScript in package dist directories remains the consumer runtime format. Upstream JavaScript filenames in provenance, patch inputs, and fixture strings remain unchanged.
pnpm run source:check scans authored source directories and root source configuration files, including untracked files. It rejects JavaScript source files, CommonJS TypeScript modules, unbound CommonJS module operations, explicit any, unchecked type suppressions, and ambient wildcard shims for local sources. The AST check permits exact external package declarations and distinguishes fixture strings and VM capture objects from executable CommonJS modules. scripts/source-policy.ts documents each external createRequire boundary and rejects literal local paths loaded through those bridges. Dynamic external loader inputs remain explicit review boundaries.
pnpm check runs the source guard, build, strict project and tool type checks, the complete Oxlint configuration, catalog and integrity checks, coverage tests, and Git whitespace checks. Vendor TypeScript and external declarations have no blanket lint exclusions. Strict compiler options and coverage thresholds remain in force; do not replace type contracts with unchecked files or permissive ambient module shims.
The existing development overrides permit sequential for...of traversal and early continue in the scope, context, and dependency parser adapters, where mutable graph traversal is required. Parser nodes are annotated in place. Internal application helpers retain named exports where already configured. All vendor families follow the repository's TypeScript import extension policy and full lint rules. Test-capture classes model upstream APIs. These development settings do not change the published presets.