@jterrazz/test 15.3.0 → 16.0.0

package/dist/oxlint.d.cts

@@ -7069,6 +7069,7 @@ interface OxlintConfig extends Oxlintrc {
  */
 /** A source comment, as exposed by oxlint's ESTree-compatible `sourceCode`. */
 type Comment = {
+  end?: number;
   range?: [number, number];
   start?: number;
   type: 'Block' | 'Line' | 'Shebang';
@@ -7112,24 +7113,52 @@ type Visitor = Record<string, (node: AstNode) => void>;
  * The normative documentation a rule carries — the code is the source of truth
  * for the mechanized catalogue (docs-as-code inversion). Every plugin rule sets
  * `meta.docs` to its {@link RuleDoc} entry from `manifest.ts`; the catalogue
- * generator reads these to (re)write `docs/13-linting.md` and the annex.
+ * generator reads these to (re)write `docs/19-linting.md` and the annex.
  */
 type RuleDoc = {
-  /** Enforcement channel — the four faces the manifest assembles. */
-  channel: 'checker' | 'process' | 'runtime' | 'statique';
-  /** The French normative sentence (the constitution's per-rule text, moved here). */
+  /**
+   * Enforcement channel — ONE per row, and the row says which.
+   *
+   * A convention enforced two ways is two rows, because the two answer
+   * different questions: what `statique` sees in one file is not what
+   * `checker` sees across a tree, and neither is what `runtime` refuses.
+   * Writing a single row with two channels made the catalogue unable to say
+   * which pass a reader should expect a finding from.
+   *
+   * - `statique` — a `jterrazz/*` oxlint rule;
+   * - `upstream` — an option this vocabulary sets on an oxlint plugin rule
+   *   someone else owns (ADR-005);
+   * - `checker` — a pass of `dist/checker.js`, over a tree or a member;
+   * - `runtime` — a refusal the framework raises while a spec runs;
+   * - `type` — what the compiler refuses, proven by a `test-d` assertion;
+   * - `meta` — what one of the package's own meta-tests holds;
+   * - `process` — a review judgement no channel can decide.
+   */
+  channel: 'checker' | 'meta' | 'process' | 'runtime' | 'statique' | 'type' | 'upstream';
+  /** The normative sentence — the constitution's per-rule text, moved here. */
   convention: string;
   /**
    * One imperative line: what to DO about it. A ban with no destination is an
    * argument rather than a rule, so the catalogue and the message carry the
-   * same fix. A row that states none renders `—`.
+   * same fix.
    */
-  fix?: string;
+  fix: string;
   /**
-   * The specification facet the rule guards — segments the catalogue like
-   * the constructors segment the API. `'shared'` for cross-facet rules.
+   * Which tree of the source the rule belongs to, and therefore where its
+   * implementation sits: `src/lint/rules/model/` for a rule that reaches every
+   * facet, `src/lint/rules/<facet>/` for one that guards a single
+   * constructor's vocabulary. The catalogue is grouped on it — model first,
+   * then one section per facet — so a reader adopting one facet sees the
+   * rules that reach them and nothing else.
+   *
+   * Required, like `fix` and `reach`: a rule with no tree is a rule nobody
+   * placed, and `model` is a statement (this reaches every facet), not a
+   * default to fall into. The checker's passes carry the field too, although
+   * their implementations do not split by folder — several passes share one
+   * module because they share one walk of the tree, so the field alone says
+   * which facet a pass speaks for.
    */
-  facet?: 'api' | 'cli' | 'component' | 'integration' | 'jobs' | 'mobile' | 'shared' | 'website';
+  facet: 'api' | 'cli' | 'component' | 'integration' | 'jobs' | 'mobile' | 'model' | 'website';
   /** Convention family letter, e.g. `'A'`. */
   family: string;
   /** Convention code, e.g. `'A1'`. */
@@ -7137,11 +7166,26 @@ type RuleDoc = {
   /** One line: why the rule exists. */
   rationale: string;
   /**
-   * Which files the rule looks at — the vocabulary of `roleOf` plus the two
-   * shapes that are not a role (`tests`, everything the conventions bind, and
-   * `all`). A row that states none renders `—`.
+   * For an `upstream` row: the rule whose OPTION carries the convention
+   * (`vitest/no-restricted-matchers`). It is what the completeness meta-test
+   * reads, so a row of that channel names the option it rests on.
+   */
+  upstream?: string;
+  /**
+   * Which files the rule looks at — the vocabulary of `roleOf` plus the
+   * shapes that are not a role: `tests` (every file that declares tests),
+   * `specs` (a tree), `member` (a package), and `all`.
+   *
+   * `module` is the COLOCATED unit test — a `.test.ts` beside the module it
+   * covers, outside every specs tree. A `module`-role file under `specs/` is
+   * a repository suite: it covers a tree rather than a unit, and the passes
+   * that judge a tree are the ones that reach it.
+   *
+   * Required, like `fix`: a reader deciding whether a rule applies to the
+   * file in front of them should not have to read its implementation, and a
+   * row that left it blank was answering "somewhere".
    */
-  reach?: 'all' | 'component' | 'config' | 'document' | 'ground' | 'module' | 'specification' | 'specs' | 'tests';
+  reach: 'all' | 'component' | 'config' | 'contract' | 'document' | 'ground' | 'member' | 'module' | 'spec' | 'specification' | 'specs' | 'tests';
 };
 /** Rule metadata (the subset we set). */
 type RuleMeta = {
@@ -7168,21 +7212,7 @@ type LintPlugin = {
 };
 //#endregion
 //#region src/lint/plugin.d.ts
-/**
- * The `@jterrazz/test` oxlint plugin — the tool-facing lint layer that enforces
- * the statically-checkable CONVENTIONS rules (the `Lint(statique)` catalogue).
- *
- * Registered in a consumer's (or this repo's own) `oxlint.config.ts` via
- * `jsPlugins: ['@jterrazz/test/oxlint']` and referenced as `jterrazz/<rule>` in
- * the `rules` map, e.g. `'jterrazz/j2-no-sleep-in-specs': 'error'` — or enabled
- * wholesale by spreading {@link recommendedRules}.
- *
- * This entry is bundled by tsdown (`dist/oxlint.js`); rules import nothing from
- * the framework runtime (only pure core helpers: the token list, the case
- * conversions, the fixture-marker list), so the bundle stays free of the heavy
- * adapters (msw, pg, testcontainers, …) that the main entry pulls in.
- */
-declare const plugin: LintPlugin;
+declare const routedPlugin: LintPlugin;
 /**
  * The full catalogue at its intended severities — spread into an oxlint
  * `rules` map to enable everything in one line:
@@ -7190,27 +7220,9 @@ declare const plugin: LintPlugin;
  *     rules: { ...recommendedRules }
  *
  * Hard conventions are errors; redundancy heuristics (`<id>w-*` rule ids) are
- * warnings. `b5-await-using` is enabled but inert until re-declared with the
- * project's docker-aware runner names:
- *
- *     'jterrazz/b5-await-using': ['error', { runners: ['dockerCli'] }]
+ * warnings.
  */
 declare const recommendedRules: Record<string, 'error' | 'warn'>;
-/**
- * The composable testing fragment — wire the plugin, enable the whole
- * catalogue, and ship the one override every strict consumer needs. Designed
- * to be composed with a base preset (e.g. `@jterrazz/typescript/oxlint`):
- *
- *     import { compose, node } from '@jterrazz/typescript/oxlint';
- *     import { testing } from '@jterrazz/test/oxlint';
- *     export default compose(node, testing);
- *
- * `jsPlugins` registers the tool-facing entry; `rules` is {@link recommendedRules};
- * `overrides` relaxes `import/exports-last` for `*.specification.ts` — the A4 idiom
- * (`export const { cli, cleanup } … ; afterAll(cleanup)`) legitimately ends a spec
- * file on a non-export statement, so the relaxation ships here rather than being
- * hand-rolled in every consumer.
- */
 declare const testing: OxlintConfig;
 //#endregion
-export { plugin as default, recommendedRules, testing };
+export { routedPlugin as default, recommendedRules, testing };

package/dist/oxlint.d.ts

@@ -7069,6 +7069,7 @@ interface OxlintConfig extends Oxlintrc {
  */
 /** A source comment, as exposed by oxlint's ESTree-compatible `sourceCode`. */
 type Comment = {
+  end?: number;
   range?: [number, number];
   start?: number;
   type: 'Block' | 'Line' | 'Shebang';
@@ -7112,24 +7113,52 @@ type Visitor = Record<string, (node: AstNode) => void>;
  * The normative documentation a rule carries — the code is the source of truth
  * for the mechanized catalogue (docs-as-code inversion). Every plugin rule sets
  * `meta.docs` to its {@link RuleDoc} entry from `manifest.ts`; the catalogue
- * generator reads these to (re)write `docs/13-linting.md` and the annex.
+ * generator reads these to (re)write `docs/19-linting.md` and the annex.
  */
 type RuleDoc = {
-  /** Enforcement channel — the four faces the manifest assembles. */
-  channel: 'checker' | 'process' | 'runtime' | 'statique';
-  /** The French normative sentence (the constitution's per-rule text, moved here). */
+  /**
+   * Enforcement channel — ONE per row, and the row says which.
+   *
+   * A convention enforced two ways is two rows, because the two answer
+   * different questions: what `statique` sees in one file is not what
+   * `checker` sees across a tree, and neither is what `runtime` refuses.
+   * Writing a single row with two channels made the catalogue unable to say
+   * which pass a reader should expect a finding from.
+   *
+   * - `statique` — a `jterrazz/*` oxlint rule;
+   * - `upstream` — an option this vocabulary sets on an oxlint plugin rule
+   *   someone else owns (ADR-005);
+   * - `checker` — a pass of `dist/checker.js`, over a tree or a member;
+   * - `runtime` — a refusal the framework raises while a spec runs;
+   * - `type` — what the compiler refuses, proven by a `test-d` assertion;
+   * - `meta` — what one of the package's own meta-tests holds;
+   * - `process` — a review judgement no channel can decide.
+   */
+  channel: 'checker' | 'meta' | 'process' | 'runtime' | 'statique' | 'type' | 'upstream';
+  /** The normative sentence — the constitution's per-rule text, moved here. */
   convention: string;
   /**
    * One imperative line: what to DO about it. A ban with no destination is an
    * argument rather than a rule, so the catalogue and the message carry the
-   * same fix. A row that states none renders `—`.
+   * same fix.
    */
-  fix?: string;
+  fix: string;
   /**
-   * The specification facet the rule guards — segments the catalogue like
-   * the constructors segment the API. `'shared'` for cross-facet rules.
+   * Which tree of the source the rule belongs to, and therefore where its
+   * implementation sits: `src/lint/rules/model/` for a rule that reaches every
+   * facet, `src/lint/rules/<facet>/` for one that guards a single
+   * constructor's vocabulary. The catalogue is grouped on it — model first,
+   * then one section per facet — so a reader adopting one facet sees the
+   * rules that reach them and nothing else.
+   *
+   * Required, like `fix` and `reach`: a rule with no tree is a rule nobody
+   * placed, and `model` is a statement (this reaches every facet), not a
+   * default to fall into. The checker's passes carry the field too, although
+   * their implementations do not split by folder — several passes share one
+   * module because they share one walk of the tree, so the field alone says
+   * which facet a pass speaks for.
    */
-  facet?: 'api' | 'cli' | 'component' | 'integration' | 'jobs' | 'mobile' | 'shared' | 'website';
+  facet: 'api' | 'cli' | 'component' | 'integration' | 'jobs' | 'mobile' | 'model' | 'website';
   /** Convention family letter, e.g. `'A'`. */
   family: string;
   /** Convention code, e.g. `'A1'`. */
@@ -7137,11 +7166,26 @@ type RuleDoc = {
   /** One line: why the rule exists. */
   rationale: string;
   /**
-   * Which files the rule looks at — the vocabulary of `roleOf` plus the two
-   * shapes that are not a role (`tests`, everything the conventions bind, and
-   * `all`). A row that states none renders `—`.
+   * For an `upstream` row: the rule whose OPTION carries the convention
+   * (`vitest/no-restricted-matchers`). It is what the completeness meta-test
+   * reads, so a row of that channel names the option it rests on.
+   */
+  upstream?: string;
+  /**
+   * Which files the rule looks at — the vocabulary of `roleOf` plus the
+   * shapes that are not a role: `tests` (every file that declares tests),
+   * `specs` (a tree), `member` (a package), and `all`.
+   *
+   * `module` is the COLOCATED unit test — a `.test.ts` beside the module it
+   * covers, outside every specs tree. A `module`-role file under `specs/` is
+   * a repository suite: it covers a tree rather than a unit, and the passes
+   * that judge a tree are the ones that reach it.
+   *
+   * Required, like `fix`: a reader deciding whether a rule applies to the
+   * file in front of them should not have to read its implementation, and a
+   * row that left it blank was answering "somewhere".
    */
-  reach?: 'all' | 'component' | 'config' | 'document' | 'ground' | 'module' | 'specification' | 'specs' | 'tests';
+  reach: 'all' | 'component' | 'config' | 'contract' | 'document' | 'ground' | 'member' | 'module' | 'spec' | 'specification' | 'specs' | 'tests';
 };
 /** Rule metadata (the subset we set). */
 type RuleMeta = {
@@ -7168,21 +7212,7 @@ type LintPlugin = {
 };
 //#endregion
 //#region src/lint/plugin.d.ts
-/**
- * The `@jterrazz/test` oxlint plugin — the tool-facing lint layer that enforces
- * the statically-checkable CONVENTIONS rules (the `Lint(statique)` catalogue).
- *
- * Registered in a consumer's (or this repo's own) `oxlint.config.ts` via
- * `jsPlugins: ['@jterrazz/test/oxlint']` and referenced as `jterrazz/<rule>` in
- * the `rules` map, e.g. `'jterrazz/j2-no-sleep-in-specs': 'error'` — or enabled
- * wholesale by spreading {@link recommendedRules}.
- *
- * This entry is bundled by tsdown (`dist/oxlint.js`); rules import nothing from
- * the framework runtime (only pure core helpers: the token list, the case
- * conversions, the fixture-marker list), so the bundle stays free of the heavy
- * adapters (msw, pg, testcontainers, …) that the main entry pulls in.
- */
-declare const plugin: LintPlugin;
+declare const routedPlugin: LintPlugin;
 /**
  * The full catalogue at its intended severities — spread into an oxlint
  * `rules` map to enable everything in one line:
@@ -7190,27 +7220,9 @@ declare const plugin: LintPlugin;
  *     rules: { ...recommendedRules }
  *
  * Hard conventions are errors; redundancy heuristics (`<id>w-*` rule ids) are
- * warnings. `b5-await-using` is enabled but inert until re-declared with the
- * project's docker-aware runner names:
- *
- *     'jterrazz/b5-await-using': ['error', { runners: ['dockerCli'] }]
+ * warnings.
  */
 declare const recommendedRules: Record<string, 'error' | 'warn'>;
-/**
- * The composable testing fragment — wire the plugin, enable the whole
- * catalogue, and ship the one override every strict consumer needs. Designed
- * to be composed with a base preset (e.g. `@jterrazz/typescript/oxlint`):
- *
- *     import { compose, node } from '@jterrazz/typescript/oxlint';
- *     import { testing } from '@jterrazz/test/oxlint';
- *     export default compose(node, testing);
- *
- * `jsPlugins` registers the tool-facing entry; `rules` is {@link recommendedRules};
- * `overrides` relaxes `import/exports-last` for `*.specification.ts` — the A4 idiom
- * (`export const { cli, cleanup } … ; afterAll(cleanup)`) legitimately ends a spec
- * file on a non-export statement, so the relaxation ships here rather than being
- * hand-rolled in every consumer.
- */
 declare const testing: OxlintConfig;
 //#endregion
-export { plugin as default, recommendedRules, testing };
+export { routedPlugin as default, recommendedRules, testing };