IF Commons GitHub

Lint

0001Draft

0001-lint · owner if · domain commons

The plugin

FR-001checkpassing

The library MUST give a lint plugin in the ESLint plugin format, named ifc, which bun lint --plugin loads from its source (TypeScript, with no build) or from the compiled module of the published package, with the rules no-vendor-api, no-registry-import, import-boundary, module-doc, switch-absurd and terminal-writers, each with a description, no schema and a create function.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: the plugin is in ESLint's format, named ifc, with the six rules, each with a description, no schema and a create function

Proved by: lint/suite/plugin.test.ts

Tests: passed: suite/plugin.test.ts the plugin is in ESLint's format, named ifc, with the rules every harness wants

Cited by: Lint, plugin

FR-002checkpartly run

The library MUST give defineRule, the typed way to define a rule: it decodes the rule's options once, with the decoders of core, and IF the options do not decode, THEN it MUST report that at the first line of each file, naming the rule and what is wrong, and MUST NOT run the rule; so that a harness keeps its own lists and adds its own rules, as a plugin of its own that bun lint --plugin loads.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: options that do not decode are reported and no rule runs; a harness's own rule made with defineRule is loaded by bun lint --plugin

Proved by: lint/suite/plugin.test.ts

Tests: skipped: suite/plugin.test.ts a harness defines its own rule with defineRule, in a plugin of its own, and bun lint loads; skipped: suite/plugin.test.ts options that do not decode are reported, never ignored: an allowed file without its reason

Cited by: Lint, rule

The rules

FR-003checkpartly run

no-vendor-api MUST refuse a member of a vendor's global (Deno.* and Bun.* by default, or the names its option globals gives), in code and in types, outside the files its option allow lists, each with a reason that is not blank.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: no-vendor-api refuses a vendor's global in code and in types outside the allowed files, through the real bun lint

Proved by: lint/suite/plugin.test.ts

Tests: skipped: suite/plugin.test.ts no-vendor-api refuses a vendor's global in code and in types outside the files allowed wit

FR-004checkpartly run

no-registry-import MUST refuse a module specifier that names a registry or a URL (npm:, jsr:, https: and http: by default, or the prefixes its option prefixes gives), in an import, an export ... from, a dynamic import() and an import() type; a bare name, a node: module and a relative path MUST pass.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: no-registry-import refuses npm:, jsr: and URL specifiers in every form of import

Proved by: lint/suite/plugin.test.ts

Tests: skipped: suite/plugin.test.ts no-registry-import refuses npm:, jsr: and URL specifiers in every form of import; a bare n

FR-005checkpartly run

import-boundary MUST refuse a relative import that leaves the package it is in, the packages being the folders its option roots names (a pattern such as packages/* names each of its folders); an import inside the package, and a file that is in no package, MUST pass.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: import-boundary refuses a relative import that leaves its package

Proved by: lint/suite/plugin.test.ts

Tests: skipped: suite/plugin.test.ts import-boundary refuses a relative import that leaves its package; one inside it, or from

FR-006checkpartly run

module-doc MUST refuse a file that does not begin with a JSDoc block (/** ... */) that says @module; a shebang line MAY come first.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: module-doc refuses a file that does not begin with a JSDoc block saying @module

Proved by: lint/suite/plugin.test.ts

Tests: skipped: suite/plugin.test.ts module-doc refuses a file that does not begin with a JSDoc block saying @module; a shebang

FR-007checkpartly run

switch-absurd MUST refuse a switch over a union, on its discriminant (x.kind by default, or the names its option discriminants gives), that does not end in a default that calls absurd (or the functions its option functions names); its option every MUST hold every switch to it.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: switch-absurd refuses a switch that does not end in a default calling absurd

Proved by: lint/suite/plugin.test.ts

Tests: skipped: suite/plugin.test.ts switch-absurd refuses a switch on kind that does not end in a default calling absurd; ever

FR-008checkpartly run

terminal-writers MUST refuse a write to the terminal (process.stdout, process.stderr, console and a vendor's streams, or the writers its option writers names) outside the files its option allow lists, each with a reason that is not blank.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: terminal-writers refuses a write to the terminal outside the allowed files

Proved by: lint/suite/plugin.test.ts

Tests: skipped: suite/plugin.test.ts terminal-writers refuses process.stdout, process.stderr, console and the vendors' streams

Testing a rule

FR-009checkpartly run

The library MUST give lintFiles, which writes files to a new folder, runs the real linter over them with the plugin loaded by --plugin and only one rule turned on by --rule, and gives the problems of the linter's JSON report, decoded; the linter MUST be the Bun named by IFC_LINT_BUN, or else the pinned canary (bun x --no-install bun@<version>), and where it is not installed linter() MUST say so, so that a test is skipped with that reason and not failed.

Enforced (check): .github: cd commons/lint && bun test suite/ — plugin.test.ts: every rule is proved against the real bun lint, run by lintFiles; skipped with its reason where the pinned canary is not installed

Proved by: lint/suite/plugin.test.ts

Tests: skipped: suite/plugin.test.ts a harness defines its own rule with defineRule, in a plugin of its own, and bun lint loads; skipped: suite/plugin.test.ts options that do not decode are reported, never ignored: an allowed file without its reason

Cited by: Lint, test-rule

The package

FR-010checkno test run

The library MUST be published to npm as compiled modules with their declarations, one entry for the plugin (.), one for the typed way to define a rule (./rule) and one for the way to test a rule (./test-rule), and bun lint --plugin MUST load the installed package's plugin and run its rules.

Enforced (check): .github: cd commons/lint && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/commons-packages.test.ts installs the tarball, runs every entry on Node 26 and Bun, type-checks a consumer and runs bun lint --plugin with the installed plugin

Acceptance scenarios

  1. Given the plugin loaded by bun lint --plugin, When a file uses a vendor global outside the allowed files, Then the linter reports it at its line, per FR-003.
  2. Given a rule whose options do not decode, When the linter runs, Then it reports the options and runs no rule, per FR-002.
  3. Given a harness with its own plugin made with defineRule, When bun lint loads it, Then its rule runs, per FR-002.
  4. Given the package installed in an empty project, When bun lint --plugin loads it, Then the rules run, per FR-010.

Out of scope

Edge cases

  • A file in no package for import-boundary: passes, per FR-005.
  • A blank reason in an allow list: the options do not decode, per FR-002.
  • The pinned canary not installed: the tests that need it are skipped with the reason, per FR-009.

Assumptions

  • Bun's lint runs JavaScript plugins in ESLint's format.

Open questions

  • None.

Key entities

  • Plugin - the ESLint plugin ifc and its rules.
  • Rule - a check of code with options that it takes from its setting.
  • Allow list - the files a rule does not apply to, each with its reason.

Success criteria

SC-001success criterion

A harness adopts the rules of Intellectual Frontiers with one line of bunfig.toml.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Lint, plugin, rule, test-rule

Titles, headings, exports, tables, columns and requirements. Esc closes.