Compatibility

seniority (cosmiconfig's API at the root), seniority/lilconfig, seniority/dotenv and seniority/rc are graded, not described as compatible. Each is run against its incumbent's own test suite, by compat-oracle, in CI.

The family's compatibility page is generated from the oracle's last run and is the authority for the current figures.

How a suite is gradedCopy Anchor Link

1. The incumbent's repository is cloned at the graded version, and its test directory is copied into packages/compat-oracle/vendor/. The versions are cosmiconfig 10.0.1, lilconfig 3.1.4, dotenv 18.0.9, and rc 1.2.8 (rc's release was never tagged, so its commit is pinned). Each copy has a PROVENANCE file.
2. The only edit is the import that reaches the library, rewritten to a shim generated per run.
3. A control run points the shim at the real incumbent first. Its total is what every rate is measured against.
4. The target run points the same shim at seniority.

What each grade coversCopy Anchor Link

• lilconfig: 77 of 77, the same count the real lilconfig gets here. Ten of the cases mock fs with jest.mock to assert which files were read, and the oracle applies that mock the way jest does.
• rc: 1 of 1, by exit code. rc's suite is one script of bare assertions with no reporter, so the grade is one bit: the script ran against seniority and exited 0. It is not 100% of anything.
• cosmiconfig: 242 of 243, the same count the real cosmiconfig gets here. YAML files are read with seniority/yaml, the package's own parser, loaded on the first YAML file. The 54 YAML cases that failed until 2026-09-30 pass, all 22 of import.test.ts among them. So does the XDG pair that registers only on Linux: the global config directory is read from XDG_CONFIG_HOME as cosmiconfig reads it. The one not passing is index.test.ts, which imports cosmiconfig's entry by a file path and fails for the control too.
• dotenv: 197 of 197, the same count the real dotenv gets here. The suite runs under node-tap, which counts assertions, so 197 is assertions. It spawns dotenv run and programs that import 'dotenv/config', and seniority answers both. dotenv 17.4.2's suite is graded and not claimed: 107 of 141, the 34 being the vault, the tips and the log line 18 moved to stderr.

Known differencesCopy Anchor Link

• No YAML, and no INI. The cosmiconfig and rc drop-ins read JSON (rc's with comments) and refuse YAML and INI by name, with a hint naming the argument that supplies a parser.
• seniority/dotenv writes process.env only when you give it nothing else. Pass processEnv and it fills that object instead.
• No vault. .env.vault, DOTENV_KEY and decrypt are not implemented, because dotenv 18 removed them.
• seniority's own API is stricter than the drop-ins. resolve reads only declared options from the environment and refuses unclear booleans. seniority/rc keeps rc's behaviour, which is to take every <name>_ variable.

Moving one importCopy Anchor Link

- import { cosmiconfig } from 'cosmiconfig';
+ import { cosmiconfig } from 'seniority';

- import { lilconfig } from 'lilconfig';
+ import { lilconfig } from 'seniority/lilconfig';

npx burgee migrate --dry-run lists every import it would rewrite, and rewrites only drop-ins graded level with their incumbent, which here means lilconfig and rc. Incremental migration moves from a drop-in to resolve.