@shivaedev/quality 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.5.0 - 2026-10-04
+
+### Added
+
+- Add the Biome preset `@shivaedev/quality/biome`. It sets the formatting (tabs, a line width of 150, double quotes), every rule Biome recommends at `error`, a list of stricter rules such as `noUnsafeTypeAssertion`, `useBlockStatements`, `noEqualsToNull`, `useConsistentArrayType` with `readonly T[]`, `noFloatingPromises` and `useExhaustiveSwitchCases`, sorted keys in JSON and object literals, and the GritQL plugins that ban ambient time, randomness, `console` and `process.env` and check `Effect.fn` span names. Its `declarations.json` declares the rules it turns off.
+- Add the `biome` rule. It runs Biome, now a dependency pinned to 2.5.14, and reports each finding as `biome/<category>`, so Biome's findings take part in the baseline. `adopt: ["biome"]` adopts all of them. It also asks for a root Biome config that extends the preset. Like every rule it is an error by default, so a repository that upgrades extends the preset and adopts `biome` into its baseline.
+- Add `quality fix`, which sorts every `package.json` and applies Biome's safe fixes, assist actions and formatting.
+- Add the `manifests/sorted` rule. It reports every `package.json` in the repository whose keys are not in the order of sort-package-json, now a dependency pinned to 4.0.0, and every `package.json` that is not valid JSON.
+- Add `@shivaedev/quality/vitest`. Its `testProjects()` sets up Vitest projects by file name: `unit` runs `*.test.ts` files in Node, `dom` runs `*.dom.test.ts` and `*.dom.test.tsx` files in happy-dom, and `slow` runs `*.slow.test.ts` files only when `--project slow` asks for it. Type tests (`*.typecheck.test.ts`) never run. `vitest` is an optional peer dependency.
+- Add `comments/no-environment-pragma`, which reports a test environment set by a Vitest or Jest environment pragma. A DOM test is named `*.dom.test.ts` instead.
+- Add `imports/cycles` and `imports/resolvable`, which read the import graph of the sources with the TypeScript compiler. `imports/cycles` reports each group of modules that import each other at run time, ignoring type-only imports, and takes no registry exceptions. `imports/resolvable` reports an import that resolves to nothing; its `generated` option names the folders where a relative import of a missing file is generated output. Like every rule they are errors by default, so a repository that upgrades baselines what they find. A run whose sources hold no module fails instead of passing on an empty graph.
+- Add `imports/fences` and the `fence()` builder for declaring import fences in the config without patterns: `fence(name).because(reason).from(target)` with `mayNotImport`, `mayNotReach` or `mayImportOnly(...).of(...)`, demonstrated by an illegal and a legal example that the rule checks against the policy. Targets are `packages`, `folders`, `files`, `modules`, `scopes`, `anyOf`, `workspace` and `anything`, each with `.except`, and every name must exist.
+
+### Changed
+
+- `suppressions/no-inline` allows `@ts-expect-error` in type tests by their file name, `*.typecheck.test.ts` or `typecheck.test.ts`, and takes no options. The `declared` option is gone, so a config that sets it fails to load until it is removed.
+- The `allow` lists of `comments/no-jsdoc` and `comments/max-per-file` are empty by default, so a tool pragma counts as a comment until the config allows its tag.
+
+### Fixed
+
+- Write all of a long report before exiting when the output is a pipe, instead of cutting it off.
+
+## 0.4.0 - 2026-10-03
+
+### Added
+
+- `suppressions/biome-overrides` follows `extends` entries that name a package,
+  such as a shared Biome preset, resolved from the root's `node_modules` through
+  `exports` (the `biome` and `default` conditions and `*` patterns), `main` or a
+  file inside the package, as Biome resolves them. A non-relative entry that
+  names a file at the repository root is read as that file. The weakenings a
+  preset makes count as declared when a `declarations.json` beside the preset
+  declares them; any other preset weakening is reported at the `extends` line.
+  A repository declaration that repeats one the preset ships is reported, and so
+  is an `extends` entry that cannot be resolved or read.
+- Add tsconfig presets for TypeScript 7. `@shivaedev/quality/tsconfig/base.json` is for type-checking with `noEmit`. `@shivaedev/quality/tsconfig/package.json` is the base plus declaration output, declaration and source maps, and relative `.ts` imports rewritten to `.js`, for building a package. The base sets `target` and `lib` to ESNext with bundler resolution; type-checks JavaScript with `allowJs` and `checkJs`; turns on `strict` (stating `noImplicitAny` and `strictBuiltinIteratorReturn` explicitly), `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noUnusedLocals`, `noUnusedParameters`, `verbatimModuleSyntax`, `isolatedModules`, `erasableSyntaxOnly`, `noUncheckedSideEffectImports` and `forceConsistentCasingInFileNames`; and rejects unreachable code and unused labels. Dot access to index signatures stays allowed.
+
+### Changed
+
+- `suppressions/biome-overrides` merges a config with the configs it extends the
+  way Biome does: a later setting of a rule, a group, `recommended` or `enabled`
+  replaces an earlier one, so a weakening that the extending config sets back to
+  `error` is no longer reported, while `overrides` and every `includes` list are
+  appended. The `extends` of an extended config are no longer followed, since
+  Biome does not apply them.
+
 ## 0.3.1 - 2026-10-03
 
 ### Changed

package/README.md

@@ -61,31 +61,34 @@ The config is typed: an unknown rule id, a misspelled option or an option of the
 
 ### Comments
 
-A comment says why, never what the code already says or what it used to be. Six rules hold every comment to that:
+A comment says why, never what the code already says or what it used to be. Seven rules hold every comment to that:
 
 | Rule | Reports | Options |
 | --- | --- | --- |
-| `comments/no-jsdoc` | Every `/** */` block, except a tool pragma | `allow` |
+| `comments/no-jsdoc` | Every `/** */` block, except a tool pragma the config allows | `allow` |
 | `comments/no-line-reference` | A line number: `file.ts:42`, `file.ts#L42`, `line 42` | none |
 | `comments/no-pr-reference` | A pull request or issue: `#123`, `PR 123`, `MR 123`, `pull request 123`, `merge request 123`, `issue 123`, `ticket 123`, `/pull/123`, `/pulls/123`, `/issues/123`, `/merge_requests/123`, `GH-123` | none |
 | `comments/no-banner` | A banner, divider or region: a line that starts or ends with three or more of `- = * # ~ _ + / \ ─ ━ ═ ┄ ┈`, `#region`, `#endregion` | none |
 | `comments/no-todo` | `TODO`, `FIXME`, `XXX` and `@todo` | none |
+| `comments/no-environment-pragma` | A test environment set by a `@vitest-environment` or `@jest-environment` pragma (and its `-options`); name the file `*.dom.test.ts` instead, see [Vitest projects](#vitest-projects) | none |
 | `comments/max-per-file` | A file with more than `max` comments, 2 by default | `max`, `allow` |
 
 The rules find comments with the TypeScript parser, so text inside strings, template literals, regular expressions and JSX never counts as a comment. They read the TypeScript and JavaScript modules among the sources and skip declaration files and the directives listed below. Each finding names the line its comment starts on.
 
+The default is no comments at all: a comment states only what the code cannot show, such as a constraint or a reason, and never narrates the code. The limit of `comments/max-per-file` is a crude tripwire against runaway comments, not a budget to fill, so a file that reaches it means something went wrong.
+
 `comments/max-per-file` counts comments this way:
 
 - A block comment counts once, however many lines it spans.
 - Line comments that each stand alone on adjacent lines form one run and count once. A blank line, code, a directive, or a comment after code on the same line starts a new one.
-- Tool pragmas and directives are not counted: compiler and linter directives (`@ts-…`, triple-slash directives such as `/// <reference …>`, `biome-ignore…`, `eslint-disable…`, `eslint-enable…`, `oxlint-…`, `stylelint-…`, `deno-lint-ignore…`, `tslint:disable…`, `prettier-ignore`, Flow's `$FlowFixMe`, `$FlowIgnore`, `$FlowExpectedError`, `$FlowIssue` and `@noflow`), bundler annotations (`#__PURE__`, `@__PURE__`, `#__NO_SIDE_EFFECTS__`, `@__NO_SIDE_EFFECTS__`) and coverage hints (`c8 ignore`, `v8 ignore`, `istanbul ignore`). The suppression rules below report the directives that silence a check.
+- Allowed tool pragmas and directives are not counted: compiler and linter directives (`@ts-…`, triple-slash directives such as `/// <reference …>`, `biome-ignore…`, `eslint-disable…`, `eslint-enable…`, `oxlint-…`, `stylelint-…`, `deno-lint-ignore…`, `tslint:disable…`, `prettier-ignore`, Flow's `$FlowFixMe`, `$FlowIgnore`, `$FlowExpectedError`, `$FlowIssue` and `@noflow`), bundler annotations (`#__PURE__`, `@__PURE__`, `#__NO_SIDE_EFFECTS__`, `@__NO_SIDE_EFFECTS__`) and coverage hints (`c8 ignore`, `v8 ignore`, `istanbul ignore`). The suppression rules below report the directives that silence a check.
 
 A file over the limit counts one violation for each comment above it: 5 comments against a limit of 2 count 3. A finding names the first comment over the limit.
 
-A tool pragma is a comment whose every line starts with an allowed tag, such as `/** @vitest-environment happy-dom */`. `allow` lists the tags and defaults to `@vitest-environment`, `@vitest-environment-options`, `@jest-environment`, `@jsx`, `@jsxFrag`, `@jsxImportSource` and `@jsxRuntime`. A list given replaces the default, and `comments/no-jsdoc` and `comments/max-per-file` each take their own, so give both the same list:
+A tool pragma is a comment whose every line starts with an allowed tag, such as `/** @jsxImportSource preact */`. `allow` lists the tags and is empty by default, so a pragma counts as a comment until the config allows its tag. Settings that a pragma would repeat in each file belong in the tool's config. `comments/no-jsdoc` and `comments/max-per-file` each take their own list, so give both the same one:
 
 ```ts
-const pragmas = ["@vitest-environment", "@license"];
+const pragmas = ["@jsxImportSource", "@license"];
 
 export default defineConfig({
 	rules: {
@@ -103,7 +106,7 @@ A check that is silenced at one site hides the problem instead of fixing it. Thr
 
 | Rule | Reports | Options |
 | --- | --- | --- |
-| `suppressions/no-inline` | Every comment directive that silences a linter, the compiler or a formatter, except a declared `@ts-expect-error` | `declared` |
+| `suppressions/no-inline` | Every comment directive that silences a linter, the compiler or a formatter, except `@ts-expect-error` in a type test | none |
 | `suppressions/no-double-cast` | A cast through `unknown`, `any` or `never`: `x as unknown as T`, `x as any as T`, `x as never as T`, `<T><unknown>x` | none |
 | `suppressions/biome-overrides` | A Biome setting that turns a check off or down, or keeps files out of it, without a declaration, and a declaration that matches no setting | `declared` |
 
@@ -117,35 +120,15 @@ A check that is silenced at one site hides the problem instead of fixing it. Thr
 
 Coverage hints (`c8 ignore`, `v8 ignore`, `istanbul ignore`) are allowed: they leave code out of a coverage measure and silence no linter or compiler. The rule reads the TypeScript and JavaScript modules among the sources, declaration files included, and every `.css`, `.scss` and `.less` file among the checked files, whatever `extensions` says. Each finding names the line its comment starts on and has the directive as its subject.
 
-#### Declared type tests
-
-A type test proves that an API rejects what its types forbid, and TypeScript asserts a compile error only through `@ts-expect-error`, which fails as soon as the error it expects goes away. So `@ts-expect-error`, and no other directive, may be declared for a set of files:
-
-```ts
-export default defineConfig({
-	rules: {
-		"suppressions/no-inline": {
-			options: {
-				declared: [
-					{
-						directive: "@ts-expect-error",
-						includes: ["*.typecheck.ts"],
-						reason: "Type tests assert the compile errors the public types must raise.",
-					},
-				],
-			},
-		},
-	},
-});
-```
+#### Type tests
 
-`includes` takes `.gitignore` patterns, like `exclude`. `@ts-ignore`, `@ts-nocheck` and every linter and formatter directive stay reported in those files. A declaration that matches no `@ts-expect-error` is reported against `quality.config.ts` until it is removed. A test that must pass a rejected value at run time, to prove the runtime refuses it too, calls the API through `Reflect.apply` instead of a directive.
+A type test proves that an API rejects what its types forbid, and TypeScript asserts a compile error only through `@ts-expect-error`, which fails as soon as the error it expects goes away. So `@ts-expect-error`, and no other directive, is allowed in a type test: a file named `*.typecheck.test.ts` or `typecheck.test.ts` (or `.tsx`). The compiler checks these files; [Vitest projects](#vitest-projects) never run them. `@ts-ignore`, `@ts-nocheck` and every linter and formatter directive stay reported in them. A test that must pass a rejected value at run time, to prove the runtime refuses it too, calls the API through `Reflect.apply` instead of a directive.
 
 `suppressions/no-double-cast` finds casts with the TypeScript parser, through parentheses and in either assertion syntax. A single cast is left to the linter, and `as const` is not a cast.
 
 #### Declared Biome overrides
 
-A scope that truly cannot follow a lint rule keeps its exception in the Biome config, and the quality config declares it with a reason. `suppressions/biome-overrides` reads `biome.json` or `biome.jsonc` at the root, every nested `biome.json` and `biome.jsonc` among the checked files, and the local files a config `extends` (an entry that starts with `.`). These settings count as overrides, at the top level and in every `overrides` entry:
+A scope that truly cannot follow a lint rule keeps its exception in the Biome config, and the quality config declares it with a reason. `suppressions/biome-overrides` reads `biome.json` or `biome.jsonc` at the root, every nested `biome.json` and `biome.jsonc` among the checked files, and the configs each of them `extends`, resolved the way Biome resolves them (see [Shared presets](#shared-presets)). These settings count as overrides, at the top level and in every `overrides` entry:
 
 | Setting | Declared as |
 | --- | --- |
@@ -188,6 +171,93 @@ export default defineConfig({
 
 A declaration covers a setting when its `rule` and its `includes` match the setting's exactly, in any order. An `includes` list that keeps files out is declared as the whole list, so every pattern added to it needs the declaration to change too. A setting at the top level of the root config has the scope `["**"]`, and an `overrides` entry has its own `includes` (`["**"]` when it has none). Patterns in a nested config are relative to its folder, so they are declared with the folder in front: `"src/**"` in `packages/web/biome.json` is declared as `"packages/web/src/**"`, and its top level as `"packages/web/**"`. A setting without a declaration is reported at its line in the Biome config; a declaration that no setting matches is reported against the root config, so the list cannot outlive the overrides it explains.
 
+#### Shared presets
+
+A config `extends` its entries the way Biome does:
+
+- An entry that starts with `./` or `../` is a file next to the config. Any other entry is first a file at the repository root, then a package in the root's `node_modules`, resolved through its `exports` (with the `biome` and `default` conditions, and `*` patterns), then its `main`, then a file inside it. A package may also name itself through the repository's own `package.json` `exports`. `"//"` in a nested config extends the root config, which is read on its own.
+- Biome reads only the entries of the config it loads: the `extends` of an extended config are not followed, so they are not read here either.
+- The extended configs apply from left to right and the config itself last. A later setting of a rule, a group, `recommended` or `enabled` replaces an earlier one, so a preset's weakening that the repository sets back to `error` is no override. A group set as a whole (`"suspicious": "error"`) replaces the settings of its rules; a rule set inside a group the preset turned off leaves the rest of the group off.
+- Lists are appended, not replaced: `overrides`, `plugins` and every `includes` list, `files.includes` among them. A repository's `files.includes` adds to the preset's, so each list is declared by whoever wrote it.
+- Patterns in an extended config resolve against the repository root, or against the folder of a nested config that extends it, as patterns in the config itself do.
+
+A package that ships a preset declares the weakenings the preset makes in a `declarations.json` beside the preset file, as an array of the same `{ rule, includes, reason }` entries the `declared` option takes. Its `includes` are written relative to the repository that extends the preset. Those weakenings count as declared, so the repository adds nothing for them:
+
+```json
+[
+	{
+		"rule": "lint/style/noDefaultExport",
+		"includes": ["**/*.config.ts"],
+		"reason": "Tools load their config files through the default export."
+	}
+]
+```
+
+A weakening the preset makes without such a declaration is reported at the line of the repository's `extends` entry, and the repository's own declaration covers it. A weakening the repository adds beyond the preset needs its own declaration, and a repository declaration that repeats one the preset ships is reported until it is removed. A preset entry that cannot be resolved or read, or whose `declarations.json` is invalid, is reported at the `extends` entry as well.
+
+### Imports
+
+Three rules read the import graph of the TypeScript and JavaScript modules among the sources. They build it once per run with the TypeScript compiler, without a bundler or another dependency.
+
+| Rule | Reports | Options |
+| --- | --- | --- |
+| `imports/cycles` | Modules that import each other at run time | none |
+| `imports/resolvable` | An import that resolves to nothing | `generated` |
+| `imports/fences` | An import that crosses a fence the config declares | `fences` |
+
+Each import resolves the way the compiler resolves it, with the options of the nearest `tsconfig.json` and the projects it references, under bundler resolution: `paths`, `package.json` `imports` and `exports` and the `source` condition hold, so a workspace package resolves to its source. The graph reads static and dynamic imports, `export ... from`, `require()`, `require.resolve()`, `import.meta.resolve()` of a bare specifier (a relative one is URL arithmetic that never checks the path), `import()` types, `/// <reference types>`, `/// <reference path>` and JSDoc `@import` tags.
+
+- An import of a stylesheet, an image or JSON resolves to the file, and only when the file exists, whatever declaration describes it. A Node builtin resolves.
+- A runtime import must resolve to code: a declaration file (`.d.ts`, `.d.mts`, `.d.cts`, or an asset declaration such as `.d.css.ts`) satisfies only `import type` and `export type`, however the import reaches it, so a package that has only its `@types` package installed, or an `exports` entry that points at a declaration, is reported.
+- A bare import resolves when a declaration file of the importer's tsconfig project declares the module in a script (`declare module "virtual:*"`). A relative import always needs a real file, `declare module "*"` and patterns with more than one `*` never count, and a `declare module` inside a module is an augmentation, which declares nothing new.
+- A relative import of a missing file resolves only inside a folder that `generated` names, such as a client a generator writes before the tests run. Each folder must be ignored by git, or at least every file an import names in it must be, hold no file git tracks but a `.gitkeep` or `.keep` placeholder, lie outside `node_modules` and hold a file that an import names. The import stays an edge to its path, so fences apply to it before the file exists.
+- A module that resolves into `node_modules` or outside the root is external, and its package is the one it resolves into, whatever alias the import uses. A `@types` package counts as the package it describes: `@types/hast` is `hast`, `@types/scope__name` is `@scope/name`.
+
+```ts
+"imports/resolvable": { options: { generated: ["packages/db/test/generated"] } },
+```
+
+`imports/cycles` reports each group of modules that import each other at run time once, at the alphabetically first of them, with one loop through the group. Its count is the number of modules in the group. `import type`, `export type`, type references and imports in declaration files are left out; `import { type X }` stays a runtime import. Dynamic `import()` and `require()` count; `require.resolve()` does not. It takes no registry exceptions. Each finding of `imports/resolvable` has the import as its subject.
+
+The gate fails closed: when the sources hold no module at all, the imports rules stop the run instead of passing on an empty graph. Point `sources` at the code, or turn the rules off.
+
+#### Fences
+
+A fence is one prohibition, stated in the config without patterns:
+
+```ts
+import { defineConfig, external, fence, folders, packages } from "@shivaedev/quality";
+
+const fences = [
+	fence("ui-never-imports-server")
+		.because("The UI ships to browsers.")
+		.from(folders("packages/ui/src"))
+		.mayNotImport(packages("server"))
+		.demonstratedBy({
+			illegal: ["packages/ui/src/index.ts", "packages/server/src/index.ts"],
+			legal: ["packages/ui/src/index.ts", external("effect")],
+		}),
+];
+
+export default defineConfig({ rules: { "imports/fences": { options: { fences } } } });
+```
+
+A fence has a name, a reason, the modules it holds (`from`) and one prohibition:
+
+- `mayNotImport(target)`: no module it holds imports the target.
+- `mayNotReach(target)`: nothing a module it holds imports, directly or through other modules of the repository, is the target. The finding names the path.
+- `mayImportOnly(...subjects).of(unit)`: the modules it holds import only the named modules or folders directly in a package's `src` folder (or the package folder) or in a folder.
+
+Targets are `packages(...)` (workspace packages by name, with or without their scope; a workspace package is a named `package.json` that `pnpm-workspace.yaml` or the root `package.json` `workspaces` includes, with `*`, `**`, `?`, `{a,b}` and `[...]` in its patterns, none of which match a folder whose name starts with `.` unless the pattern spells the dot, and a `packages` list or pattern the gate cannot read stops the run, and it holds every file below it that no deeper workspace package holds), `folders(...)`, `files(...)`, `modules(...)` (external packages by package name, and Node builtins), `scopes(...)` (every external package of a scope), `anyOf(...)`, `workspace` (every workspace package) and `anything`. Each takes `.except(...)`.
+
+The config does not compile without `demonstratedBy`, and the rule checks the examples against the policy: each is a chain of imports from a file of the repository, which may end in `external(name)`. The illegal example must cross this fence and no other; the legal example must cross none. Every name a fence uses must exist: a package, a folder that holds checked files, a checked file, a subject of the unit. Two fences may not share a name, and each needs a reason. A policy that breaks any of this stops the run. Fences count type imports too.
+
+A finding has its fence's name as its subject, so a registry entry with that subject excuses one file from one fence.
+
+### Manifests
+
+`manifests/sorted` keeps every `package.json` in the repository in the key order of [sort-package-json](https://github.com/keithamus/sort-package-json), a dependency of this package. It walks the whole repository, not only the sources, and skips files ignored by git and `node_modules`. A manifest that is not valid JSON is reported too. `quality fix` sorts the manifests, and the rule takes no registry exceptions.
+
 ### Local rules
 
 ```ts
@@ -288,6 +358,7 @@ An entry covers a rule's violations in one file, for good, and must say why. Wit
 
 ```text
 quality lint [--config <file>] [--warnings summary|all]
+quality fix [--config <file>]
 quality baseline write [--config <file>] [--rule <id>]...
 quality baseline prune [--config <file>] [--against <ref>]
 quality baseline tighten [--config <file>] [--staged]
@@ -303,6 +374,92 @@ quality baseline migrate [--config <file>] [--from <file>]
 | 1 | Failed: an uncovered error-level violation, a baselined file that got worse, a stale registry entry, a baseline entry for a rule that is off or unknown, or a baseline that grew against the merge base. |
 | 2 | Could not run: no or invalid config, an invalid baseline or registry, a baseline left in the earlier format, a missing source, a rule that threw, git history the check cannot read, or a usage error. |
 
+## Biome preset
+
+`@shivaedev/quality/biome` is one Biome setup for every repository. Biome is a dependency of this package, pinned to an exact version, and `quality` runs it, so a repository needs no Biome install of its own. The root `biome.json` extends the preset and adds only what is the repository's own:
+
+```json
+{
+	"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+	"extends": ["@shivaedev/quality/biome"]
+}
+```
+
+The preset sets:
+
+- **Formatting:** tabs, a line width of 150, double quotes, semicolons, trailing commas and operators at the start of a wrapped line.
+- **Lint:** every rule Biome recommends, at `error`, and a list of stricter rules on top, among them `noUnsafeTypeAssertion`, `useBlockStatements`, `noEqualsToNull`, `useNumericSeparators`, `useUnicodeRegex`, `useLiteralKeys`, `readonly T[]` arrays, `noFloatingPromises`, `noMisusedPromises`, `useExhaustiveSwitchCases`, `useExhaustiveDependencies`, `it` for every test, function declarations over function expressions, interfaces for object types, a cognitive complexity limit of 15, no nested ternaries, no barrel files and no `export *`.
+- **Assist:** organized imports and sorted keys, attributes, enum members, interface members and properties. Keys are sorted in JSON and in object literals alike; `package.json` is left out, because `manifests/sorted` gives it the order npm users expect.
+- **Plugins:** GritQL rules that ban ambient time, randomness, `console` and `process.env` for Effect's services, and that ask `Effect.fn` for a literal span name shaped `Owner.operation`. They load from `./node_modules/@shivaedev/quality/biome/plugins`, so the package must be installed at the repository root.
+- Files ignored by git are skipped.
+
+The preset turns off `noUnusedVariables` and `noUnusedFunctionParameters`, because the tsconfig presets report them through TypeScript, and allows default exports in `*.config.*` files, which tools load through the default export. It declares these weakenings in its `declarations.json`, so `suppressions/biome-overrides` takes them as declared. Every other weakening a repository adds is an override it declares with a reason.
+
+The `biome` rule runs `biome check` with the repository's config and reports each finding as `biome/<category>`, such as `biome/lint/style/useBlockStatements`, `biome/assist/source/useSortedKeys`, `biome/format` or `biome/plugin`, so Biome's findings go through the baseline like any other rule's. `adopt: ["biome"]` and `quality baseline write --rule biome` take in every Biome category at once. A finding below `error`, such as a rule a repository declared at `warn`, is not reported. The rule also asks for a root `biome.json` or `biome.jsonc` that extends the preset, and it takes no registry exceptions. A Biome config that Biome cannot load stops the run with Biome's message.
+
+`quality fix` sorts every `package.json`, then applies Biome's safe fixes, assist actions and formatting. An editor that runs Biome on save uses the same version when it resolves Biome from the root `node_modules`, so a repository that wants that installs `@biomejs/biome` at the version this package pins.
+
+## Vitest projects
+
+`@shivaedev/quality/vitest` sets up the tests of a package by file name, so no test file sets its environment with a pragma. It needs `vitest`, and `happy-dom` for DOM tests.
+
+```ts
+// vitest.config.ts
+import { testProjects } from "@shivaedev/quality/vitest";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({ test: testProjects() });
+```
+
+| Project | Files | Environment | Runs |
+| --- | --- | --- | --- |
+| `unit` | `*.test.ts` and the other test files | Node | By default |
+| `dom` | `*.dom.test.ts`, `*.dom.test.tsx` | happy-dom | By default |
+| `slow` | `*.slow.test.ts`, `*.slow.test.tsx` | Node | Only with `vitest run --project slow` |
+
+Type tests (`*.typecheck.test.ts` and `typecheck.test.ts`) are in no project: the compiler checks them. A test that is too slow for every run goes into the slow project instead of being skipped.
+
+## tsconfig presets
+
+Two presets hold one strict, current TypeScript setup for every repository. They target TypeScript 7.
+
+| Preset | Use |
+| --- | --- |
+| `@shivaedev/quality/tsconfig/base.json` | Type-checking with `noEmit`: applications, tests and scripts. |
+| `@shivaedev/quality/tsconfig/package.json` | Building a package: the base plus `declaration`, `declarationMap`, `sourceMap` and `rewriteRelativeImportExtensions`, so relative `.ts` imports are emitted as `.js`. |
+
+```json
+{
+	"extends": "@shivaedev/quality/tsconfig/base.json",
+	"compilerOptions": {
+		"lib": ["ESNext", "DOM"],
+		"types": ["node"]
+	},
+	"include": ["src", "test"]
+}
+```
+
+The base sets:
+
+- **Language:** `target` and `lib` ESNext, so the newest syntax is emitted as written and the newest built-ins are typed.
+- **Modules:** `module` ESNext, `moduleResolution` bundler, `moduleDetection` force, `verbatimModuleSyntax`, `isolatedModules`, `allowImportingTsExtensions`, `resolveJsonModule`, `noUncheckedSideEffectImports`, `forceConsistentCasingInFileNames` and `libReplacement: false`.
+- **JavaScript:** `allowJs` and `checkJs`, so JavaScript files are type-checked with the TypeScript ones.
+- **Erasable syntax only:** `erasableSyntaxOnly` rejects syntax that type stripping cannot erase, such as parameter properties.
+- **Checks:** `strict`, with `noImplicitAny`, `strictBuiltinIteratorReturn` and `useUnknownInCatchVariables` stated explicitly, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noUnusedLocals`, `noUnusedParameters`, `allowUnreachableCode: false` and `allowUnusedLabels: false`.
+- **Compilers:** `stableTypeOrdering`, so a TypeScript 6 build orders types the way TypeScript 7 does, and `skipLibCheck`.
+
+`noPropertyAccessFromIndexSignature` stays off, so a map-like key is read with dot access, and `isolatedDeclarations` stays off, so exported values keep their inferred types. `types`, `jsx`, `paths`, `include` and the output directories belong to each project. A project that needs more built-ins, such as the DOM, sets `lib` itself and keeps `ESNext` in it.
+
+A package that type-checks its tests with one config and builds `src` with another extends both, the package preset last:
+
+```json
+{
+	"extends": ["./tsconfig.json", "@shivaedev/quality/tsconfig/package.json"],
+	"compilerOptions": { "outDir": "dist", "rootDir": "src" },
+	"include": ["src"]
+}
+```
+
 ## Validation
 
-`pnpm ready` checks formatting, both TypeScript compilers, the rules, config, discovery, registry, baseline and report behavior, the command line against seeded repositories and git histories, and an installed tarball consumer that type-checks a config and runs the `quality` bin through a baseline cycle.
+`pnpm ready` checks formatting, TypeScript 7, the rules, the import graph against seeded repositories and the fence policy against its examples, config, discovery, registry, baseline and report behavior, the command line against seeded repositories and git histories, the Biome preset against every rule Biome recommends and against its declarations, the `biome` and `manifests/sorted` rules and `quality fix` against seeded repositories, the Vitest projects against a seeded repository that Vitest runs, an installed tarball consumer that type-checks a config and runs the `quality` bin through a baseline that takes in the preset's lint and plugin findings, and installed consumers that extend each tsconfig preset, type-check a fixture with an expected error for each check the base turns on, and run the package preset's build output.

package/biome/declarations.json

@@ -0,0 +1,17 @@
+[
+	{
+		"includes": ["**"],
+		"reason": "TypeScript reports unused variables through noUnusedLocals in the shared tsconfig, so Biome would report each one twice.",
+		"rule": "lint/correctness/noUnusedVariables"
+	},
+	{
+		"includes": ["**"],
+		"reason": "TypeScript reports unused parameters through noUnusedParameters in the shared tsconfig, so Biome would report each one twice.",
+		"rule": "lint/correctness/noUnusedFunctionParameters"
+	},
+	{
+		"includes": ["**/*.config.*"],
+		"reason": "Tools load their config files through the default export.",
+		"rule": "lint/style/noDefaultExport"
+	}
+]

package/biome/plugins/ambient-runtime.grit

@@ -0,0 +1,18 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+or {
+	or {
+		`Date.now()` as $match,
+		`new Date()` as $match
+	} where { register_diagnostic(span=$match, message="Ambient time is banned. Read time through Effect's Clock service.") },
+	`Math.random()` as $match where { register_diagnostic(span=$match, message="Ambient randomness is banned. Use Effect's Random service.") },
+	or {
+		`console.$method($...)` as $match,
+		`console[$method]($...)` as $match
+	} where { register_diagnostic(span=$match, message="console.* is banned. Log through Effect's logger.") },
+	or {
+		JsStaticMemberExpression() as $match where { $match <: `process.env` },
+		JsComputedMemberExpression() as $match where { $match <: `process["env"]` }
+	} where { register_diagnostic(span=$match, message="process.env is banned. Read configuration through Effect's Config service.") }
+}

package/biome/plugins/effect-fn-spans.grit

@@ -0,0 +1,7 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+`Effect.fn($name)` as $match where {
+	! $name <: r"^[\"'][A-Z][A-Za-z0-9]*\.[a-z][A-Za-z0-9]*[\"']$",
+	register_diagnostic(span=$match, message="Effect.fn takes a literal span name shaped PascalCaseOwner.lowerCamelCaseOperation, such as \"Transact.invalidateOnCommit\".")
+}