Skip to content

chore(lint): ESLint, Prettier and knip tracking issue #159

Open

Description

@SpiGAndromeda

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 off or warn.
  • 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 core no-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, any included.
  • 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-line comment 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/js recommended, 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-revs in chore: skip the Prettier reformat in git blame #200)
  • knip in default mode: unused exports, unused exported types, a duplicate export (READONLY_DISABLED_SUMMARY and READONLY_DISABLED_NOTIFICATION), files under tests/e2e/ reported unused (check whether they are spawned by path); knip also reports bwrap and sandbox-exec from os-sandbox.ts as 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-plugin recommended (with valid-expect maxArgs: 2, since the suite uses expect(value, message)), no-conditional-expect, no-conditional-in-test, no-conditional-tests, prefer-to-contain, prefer-to-be, prefer-strict-boolean-matchers, max-expects, and no-restricted-vi-methods for vi.mock and vi.doMock (chore(lint): add the Vitest ESLint plugin for the test files #171)
  • Production bans for writes to pi's terminal that no-console and the ban on direct process.stdout.write and process.stderr.write calls leave open. They replace the terminal-output convention that ci: review pull requests against documented conventions #220 adds, and the PR that adds them deletes docs/conventions/terminal-output.md:
    • any other access to process.stdout or process.stderr: destructuring, computed access, or passing the stream on (.pipe(process.stdout))
    • "inherit" as a stdio value, and fork, whose child inherits stdio by default; notebook/pager.ts hands the terminal to the pager on purpose and gets a disable comment with the reason. "inherit" is also a thinking-level value in model-groups/, so the ban matches stdio options only
    • execFileSync without a stdio option, which passes the child's stderr through (execSync does the same and is already banned)
    • write and writeSync calls on file descriptor 1 or 2

Shrinking the baseline

Each PR fixes the violations of one rule or a few related rules and prunes their entries.

  • no-console: the console.warn at runtime-singletons.ts breaks the TUI rule in AGENTS.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-option in notebook/pager.ts is the deliberate Windows cmd.exe path and gets a disable comment with the reason
  • ban/spawn-sync-import (config-invariants.test.ts); ban/find-package-json-import in pi-module-identity.test.ts and register-loader.test.ts resolves independently of pi-packages.mjs on 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.globSync and import.meta.dirname are 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 the any work below
  • no-explicit-any and the no-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: mostly any hits, plus nullable, unknown, boolean, array and Buffer values (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 to performance.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) and ban/zero-delay-timeout (tests/e2e/real-host.test.ts)
  • Replace the individual rule lists with js.configs.recommended, strictTypeChecked and stylisticTypeChecked

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

  1. added this to the 0.7.2 milestone on Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions