@jterrazz/test 8.0.0 → 9.0.0

package/dist/oxlint.d.cts

@@ -0,0 +1,150 @@
+//#region src/lint/types.d.ts
+/**
+ * Local structural types for the slice of oxlint's JS-plugin API this layer uses.
+ *
+ * oxlint 1.74 does not publicly export its `Plugin` / `Rule` / `Context` types
+ * (only `RuleTester`, from `oxlint/plugins-dev`), so we describe the exact subset
+ * we depend on here. Declaring them locally keeps the rules layer importing
+ * NOTHING from the framework runtime — only these ambient shapes and, where a
+ * rule needs it, pure helpers from `core/` (e.g. the token list, the kebab-case
+ * utilities). The API is ESLint-compatible, so these shapes mirror ESTree.
+ */
+/** A source comment, as exposed by oxlint's ESTree-compatible `sourceCode`. */
+type Comment = {
+  range?: [number, number];
+  start?: number;
+  type: 'Block' | 'Line' | 'Shebang';
+  value: string;
+};
+/**
+ * Minimal AST node. Rules narrow by `type` and read known fields defensively —
+ * the full generated node union is not re-exported, and structural access keeps
+ * the layer decoupled from oxlint's internal type churn.
+ */
+type AstNode = {
+  type: string;
+  [key: string]: unknown;
+};
+/** The slice of `context.sourceCode` the rules read. */
+type SourceCode = {
+  getAllComments: () => Comment[];
+  getCommentsInside: (node: AstNode) => Comment[];
+  text: string;
+};
+/** A diagnostic accepted by `context.report`. */
+type Diagnostic = {
+  data?: Record<string, number | string>;
+  messageId?: string;
+  message?: string;
+  node?: AstNode;
+};
+/** Rule context passed to `create`. */
+type RuleContext = {
+  filename: string;
+  id: string;
+  /** Configured rule options (`['error', …options]` minus the severity). */
+  options: readonly unknown[];
+  physicalFilename: string;
+  report: (diagnostic: Diagnostic) => void;
+  sourceCode: SourceCode;
+};
+/** A visitor: node-type keys → handlers invoked on entry. */
+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/10-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). */
+  convention: string;
+  /** Convention family letter, e.g. `'A'`. */
+  family: string;
+  /** Convention code, e.g. `'A1'`. */
+  id: string;
+  /** One line: why the rule exists. */
+  rationale: string;
+};
+/** Rule metadata (the subset we set). */
+type RuleMeta = {
+  defaultOptions?: unknown[];
+  docs?: RuleDoc & {
+    description?: string;
+  };
+  messages?: Record<string, string>;
+  /** JSON schema for options — required by oxlint for rules that take options. */
+  schema?: false | unknown[];
+  type?: 'layout' | 'problem' | 'suggestion';
+};
+/** A lint rule in oxlint's `create` form. */
+type LintRule = {
+  create: (context: RuleContext) => Visitor;
+  meta?: RuleMeta;
+};
+/** An oxlint JS plugin: a namespace plus its rules. */
+type LintPlugin = {
+  meta: {
+    name: string;
+  };
+  rules: Record<string, LintRule>;
+};
+//#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/j1-no-only-skip': '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;
+/**
+ * The full catalogue at its intended severities — spread into an oxlint
+ * `rules` map to enable everything in one line:
+ *
+ *     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'] }]
+ */
+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: {
+  jsPlugins: string[];
+  overrides: {
+    files: string[];
+    rules: {
+      'import/exports-last': string;
+    };
+  }[];
+  rules: Record<string, "error" | "warn">;
+};
+//#endregion
+export { plugin as default, recommendedRules, testing };

package/dist/oxlint.d.ts

@@ -0,0 +1,150 @@
+//#region src/lint/types.d.ts
+/**
+ * Local structural types for the slice of oxlint's JS-plugin API this layer uses.
+ *
+ * oxlint 1.74 does not publicly export its `Plugin` / `Rule` / `Context` types
+ * (only `RuleTester`, from `oxlint/plugins-dev`), so we describe the exact subset
+ * we depend on here. Declaring them locally keeps the rules layer importing
+ * NOTHING from the framework runtime — only these ambient shapes and, where a
+ * rule needs it, pure helpers from `core/` (e.g. the token list, the kebab-case
+ * utilities). The API is ESLint-compatible, so these shapes mirror ESTree.
+ */
+/** A source comment, as exposed by oxlint's ESTree-compatible `sourceCode`. */
+type Comment = {
+  range?: [number, number];
+  start?: number;
+  type: 'Block' | 'Line' | 'Shebang';
+  value: string;
+};
+/**
+ * Minimal AST node. Rules narrow by `type` and read known fields defensively —
+ * the full generated node union is not re-exported, and structural access keeps
+ * the layer decoupled from oxlint's internal type churn.
+ */
+type AstNode = {
+  type: string;
+  [key: string]: unknown;
+};
+/** The slice of `context.sourceCode` the rules read. */
+type SourceCode = {
+  getAllComments: () => Comment[];
+  getCommentsInside: (node: AstNode) => Comment[];
+  text: string;
+};
+/** A diagnostic accepted by `context.report`. */
+type Diagnostic = {
+  data?: Record<string, number | string>;
+  messageId?: string;
+  message?: string;
+  node?: AstNode;
+};
+/** Rule context passed to `create`. */
+type RuleContext = {
+  filename: string;
+  id: string;
+  /** Configured rule options (`['error', …options]` minus the severity). */
+  options: readonly unknown[];
+  physicalFilename: string;
+  report: (diagnostic: Diagnostic) => void;
+  sourceCode: SourceCode;
+};
+/** A visitor: node-type keys → handlers invoked on entry. */
+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/10-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). */
+  convention: string;
+  /** Convention family letter, e.g. `'A'`. */
+  family: string;
+  /** Convention code, e.g. `'A1'`. */
+  id: string;
+  /** One line: why the rule exists. */
+  rationale: string;
+};
+/** Rule metadata (the subset we set). */
+type RuleMeta = {
+  defaultOptions?: unknown[];
+  docs?: RuleDoc & {
+    description?: string;
+  };
+  messages?: Record<string, string>;
+  /** JSON schema for options — required by oxlint for rules that take options. */
+  schema?: false | unknown[];
+  type?: 'layout' | 'problem' | 'suggestion';
+};
+/** A lint rule in oxlint's `create` form. */
+type LintRule = {
+  create: (context: RuleContext) => Visitor;
+  meta?: RuleMeta;
+};
+/** An oxlint JS plugin: a namespace plus its rules. */
+type LintPlugin = {
+  meta: {
+    name: string;
+  };
+  rules: Record<string, LintRule>;
+};
+//#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/j1-no-only-skip': '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;
+/**
+ * The full catalogue at its intended severities — spread into an oxlint
+ * `rules` map to enable everything in one line:
+ *
+ *     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'] }]
+ */
+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: {
+  jsPlugins: string[];
+  overrides: {
+    files: string[];
+    rules: {
+      'import/exports-last': string;
+    };
+  }[];
+  rules: Record<string, "error" | "warn">;
+};
+//#endregion
+export { plugin as default, recommendedRules, testing };