Repository navigation
Description
Goal
Move every decision about how the code looks into deterministic checks: ESLint with type information, Prettier and knip. An agent or a reviewer should not have to decide code shape case by case.
Contract
- Every rule is an error from the PR that adds it. No rule is set to
offorwarn. - Violations that exist when a rule lands are recorded in
eslint-suppressions.json, ESLint's baseline, as a count per file and rule. New code is held to every rule from the start. - A PR that fixes recorded violations prunes the baseline with
npx eslint . --prune-suppressions; lint fails while a recorded count is higher than the actual one. - A project ban that lands with violations gets its own rule ID under the local
ban/namespace, so it keeps its own count in the baseline. Bans without violations stay on the coreno-restricted-*rules. - Presets (
js.configs.recommended,strictTypeChecked,stylisticTypeChecked) are listed as individual rules until the baseline holds no entries for them; then the preset replaces the list. - Tests follow the same rules as production code,
anyincluded. - Lint runs against the lock-file dependency tree only. Code that serves two Pi versions keeps a disable comment that names the versions, not a baseline entry.
- A pattern the code needs on purpose keeps an
eslint-disable-next-linecomment with the reason at that line, not a baseline entry and not a file-wide exemption in the config. Lint rejects a disable comment without a reason. - CI and the pre-commit hook run ESLint.
Setup
typescript-eslint 8.72.2 declares typescript <6.1.0, and main is on TypeScript 7. ESLint gets the TypeScript 6 compiler API through an npm alias, and tsc stays on 7:
"typescript": "npm:@typescript/typescript6@^6.0.2",
"@typescript/native": "npm:typescript@^7.0.2"The alias goes once typescript-eslint supports TypeScript 7 (typescript-eslint/typescript-eslint#10940).
Done
- ESLint with typescript-eslint, eslint-plugin-import-x, eslint-plugin-n and eslint-comments, every rule of
@eslint/jsrecommended, strict-type-checked and stylistic-type-checked plus the project bans, the current violations in the baseline, and lint in CI and the pre-commit hook (chore(lint): add ESLint with type-aware rules #160)
Tooling still to add
- Prettier (chore(lint): add Prettier and format the repository #199, with
.git-blame-ignore-revsin chore: skip the Prettier reformat in git blame #200) - knip in default mode: unused exports, unused exported types, a duplicate export (
READONLY_DISABLED_SUMMARYandREADONLY_DISABLED_NOTIFICATION), files undertests/e2e/reported unused (check whether they are spawned by path); knip also reportsbwrapandsandbox-execfromos-sandbox.tsas unlisted binaries, which belong in its ignored binaries (chore(lint): add knip for unused files, exports and dependencies #192) -
max-lines-per-function: agree on a limit (the 20 lines from the Model Groups spawn router #14 review are disputed), then enable it with its violations in the baseline -
@vitest/eslint-pluginrecommended (withvalid-expectmaxArgs: 2, since the suite usesexpect(value, message)),no-conditional-expect,no-conditional-in-test,no-conditional-tests,prefer-to-contain,prefer-to-be,prefer-strict-boolean-matchers,max-expects, andno-restricted-vi-methodsforvi.mockandvi.doMock(chore(lint): add the Vitest ESLint plugin for the test files #171) - Production bans for writes to pi's terminal that
no-consoleand the ban on directprocess.stdout.writeandprocess.stderr.writecalls leave open. They replace theterminal-outputconvention that ci: review pull requests against documented conventions #220 adds, and the PR that adds them deletesdocs/conventions/terminal-output.md:- any other access to
process.stdoutorprocess.stderr: destructuring, computed access, or passing the stream on (.pipe(process.stdout)) "inherit"as a stdio value, andfork, whose child inherits stdio by default;notebook/pager.tshands the terminal to the pager on purpose and gets a disable comment with the reason."inherit"is also a thinking-level value inmodel-groups/, so the ban matches stdio options onlyexecFileSyncwithout astdiooption, which passes the child's stderr through (execSyncdoes the same and is already banned)writeandwriteSynccalls on file descriptor 1 or 2
- any other access to
Shrinking the baseline
Each PR fixes the violations of one rule or a few related rules and prunes their entries.
-
no-console: theconsole.warnatruntime-singletons.tsbreaks the TUI rule inAGENTS.md(fix: stop __setSingletons from writing to the console #170) -
ban/exec-sync-import(notebook/pager.ts,os-sandbox.ts),ban/set-singletons-import(notebook/store.ts),ban/module-level-set-singletons(spawn/renderer.ts, refactor(runtime): initialize singletons at startup and drop the no-op frame scheduler #102);ban/shell-optioninnotebook/pager.tsis the deliberate Windowscmd.exepath and gets a disable comment with the reason -
ban/spawn-sync-import(config-invariants.test.ts);ban/find-package-json-importinpi-module-identity.test.tsandregister-loader.test.tsresolves independently ofpi-packages.mjson purpose and gets a disable comment with the reason at each call -
switch-exhaustiveness-check,no-unsafe-finally,import-x/no-mutable-exports -
preserve-caught-error,unbound-method,no-dynamic-delete -
no-unused-vars(positional parameters take a_prefix; destructuring that drops fields is allowed) -
n/no-unsupported-features/node-builtins:module.findPackageJSON,module.register,fs.globSyncandimport.meta.dirnameare experimental at the Node 22.19 floor; allow each in the config with a reason, or replace it -
no-unnecessary-condition: each hit is dead code or a type that does not match runtime values -
strict-boolean-expressions -
no-unsafe-type-assertion: production casts get guards; most test hits clear with theanywork below -
no-explicit-anyand theno-unsafe-*rules it drives, almost all in tests: typed test hosts and mocks -
no-non-null-assertion, mostly through a typed handler getter (refactor: replace the non-null assertions with checked narrowing #190) -
restrict-template-expressions: mostlyanyhits, plus nullable,unknown, boolean, array andBuffervalues (refactor: convert non-string template values explicitly #191) -
require-await,no-empty-function,no-misused-spread,no-control-regex -
prefer-nullish-coalescing,prefer-optional-chain,no-unnecessary-type-conversion,no-unused-expressions,no-invalid-void-type,no-base-to-string,restrict-plus-operands -
only-throw-error,prefer-promise-reject-errors,use-unknown-in-catch-callback-variable,return-await - In tests:
ban/wall-clock(deadlines move toperformance.now(), fixture timestamps to fixed values; a site that needs the real clock gets a disable comment with the reason),ban/console-assignment(tests/test-utils.ts) andban/zero-delay-timeout(tests/e2e/real-host.test.ts) - Replace the individual rule lists with
js.configs.recommended,strictTypeCheckedandstylisticTypeChecked
Out of scope
Checks ESLint cannot express: that the Pi packages in package.json share one pinned version and that each peer range starts at its pinned version, and a single [Unreleased] section in CHANGELOG.md. The kind of range is in scope: #204 adds package-json/restrict-dependency-ranges, which requires exact pins in devDependencies and >= ranges in peerDependencies for the Pi packages and typebox.
Activity