@noctcore/lint-meta-rules 0.5.0 → 0.6.1

package/docs/rules/security-scanner-version-parity.md

@@ -3,6 +3,10 @@
 > CI and the local pre-push hook pin the same secret-scanner version, and the hook checks it at run
 > time.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSecurityScannerVersionParityRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Different scanner versions ship different rulesets, so a push can pass the local hook and fail CI (or
@@ -20,8 +24,6 @@ With the defaults (gitleaks):
 - a hook `GITLEAKS_IMAGE="...gitleaks:vX.Y.Z"` tag that differs from CI,
 - a hook that never runs `gitleaks version`.
 
-Dormant when neither the workflows nor the hook mention the scanner.
-
 ```yaml
 # .github/workflows/security.yml
 env:
@@ -39,7 +41,15 @@ GITLEAKS_VERSION="8.29.0"
 gitleaks git .
 ```
 
-## Factory
+## What it does not flag
+
+- A repo where neither the workflows nor the hook mention the scanner: the rule is dormant.
+- Whether the hook's version comparison is correct: it checks only that the hook's text runs
+  `<scanner> version`.
+- Versions not written as `x.y.z`, and any hook other than `hookFile`. A repo with several hooks needs
+  one rule instance per hook.
+
+## Options
 
 ```ts
 createSecurityScannerVersionParityRule(options?: SecurityScannerVersionParityOptions): IMetaRule
@@ -54,8 +64,7 @@ createSecurityScannerVersionParityRule(options?: SecurityScannerVersionParityOpt
 | `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-It checks that the hook's text runs `<scanner> version`, not that the comparison is correct, and it
-reads only `x.y.z` versions. One hook file is checked; a repo with several hooks needs one rule
-instance per hook.
+If you run the secret scanner in only one place (CI or a local hook, not both), there is no second pin
+to keep in step.

package/docs/rules/service-image-digest-pin.md

@@ -2,6 +2,10 @@
 
 > Workflow service/container images and docker-compose images are pinned by `@sha256:` digest.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createServiceImageDigestPinRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A tag (`postgres:17-alpine`) or `latest` names whatever the registry serves today, so a green build
@@ -11,9 +15,9 @@ can change under an unchanged commit, and a local run cannot promise the bytes C
 ## What it flags
 
 - In workflow files: `image:` under a job's `services:`, and a job's `container:` in scalar or mapping
-  form. An action step's `with: image:` input is not an image pull and is ignored.
-- In compose files: every service's `image:`, except a service that also has `build:` (there `image:`
-  tags an image built locally, which has no upstream digest).
+  form.
+- In compose files: every service's `image:`, including one behind an env default
+  (`${REDIS_IMAGE:-redis:7}`), which is reported as written since the text does not show a digest.
 
 Each violation carries the 1-indexed line.
 
@@ -32,7 +36,17 @@ services:
     image: app-api:local
 ```
 
-## Factory
+## What it does not flag
+
+- An image pinned as `tag@sha256:<digest>`.
+- An action step's `with: image:` input: it is not an image pull.
+- A compose service that also has `build:`: there `image:` tags an image built locally, which has no
+  upstream digest.
+- An exact ref listed in `allowUnpinned`, and compose files under a `skipDirs` segment.
+
+The check is line-based text, not a YAML parse.
+
+## Options
 
 ```ts
 createServiceImageDigestPinRule(options?: ServiceImageDigestPinOptions): IMetaRule
@@ -46,7 +60,7 @@ createServiceImageDigestPinRule(options?: ServiceImageDigestPinOptions): IMetaRu
 | `allowUnpinned` | `string[]` | `[]` | Exact image refs allowed unpinned, for a ref the registry cannot serve a digest for. Only that exact ref passes; a bumped tag is checked again. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-Line-based text, not a YAML parse. An image behind an env default (`${REDIS_IMAGE:-redis:7}`) is
-reported as written, since the text does not show a digest.
+If your workflows and compose files only run throwaway local services where you accept whatever a tag
+serves today, skip it.

package/docs/rules/session-epoch-captured.md

@@ -0,0 +1,89 @@
+# `session-epoch-captured`
+
+> Every call into the sign-in seam passes the session epoch it captured before reading the
+> credential.
+
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionEpochCapturedRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
+Import it from the `session` entry point:
+
+```ts
+import { createSessionEpochCapturedRule } from '@noctcore/lint-meta-rules/session';
+```
+
+## Why
+
+A common way to make "sign out everywhere" stick is a per-user epoch: a revocation bumps it, and a mint
+refuses to write a session under a stale value. Where the epoch is read decides what the fence covers.
+Read inside the mint, it covers the session-store write and nothing else, so the whole credential check
+(a password hash verify, an OAuth token exchange) is a window in which a sign-in that already read the
+revoked state still mints a surviving session.
+
+So every entry point reads the epoch BEFORE it reads the credential and hands the value to the seam
+that ends the sign-in. Forgetting to is invisible: the sign-in works and every test passes, because the
+race only loses under a concurrent revocation. This rule fails any call into the seam whose arguments
+never mention the epoch.
+
+## What it flags
+
+Each `.<call>(...)` call in a file matched by `sourceGlobs` whose argument text (found by balancing
+parentheses) does not mention `field` as a whole word. The parenthesis scanner reads each call on its
+own, so a call written on one line is checked too, and an unstamped call cannot borrow the epoch of
+the next one.
+
+## What it does not flag
+
+- `epochless: true`, or any identifier that merely contains the field: whole words only.
+- Files in `exempt` (the seam's own home, which defines the method and its default).
+- Files ending in an `excludeSuffixes` entry, and `skipDirs` segments.
+
+With no `call` the rule is inert.
+
+## Options
+
+```ts
+createSessionEpochCapturedRule(options?: SessionEpochCapturedOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'session-epoch-captured'` | Rule id. |
+| `call` | `string` | none (inert) | The post-credential seam, matched as `.<call>(`. |
+| `field` | `string` | `'epoch'` | The argument every call must mention. |
+| `exempt` | `string[]` | `[]` | Repo-relative files skipped outright: the seam's own home. |
+| `captureCall` | `string` | none | How the epoch is captured, quoted in the message. |
+| `sourceGlobs` | `string[]` | `[]` (inert) | Source to read. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `excludeSuffixes` | `string[]` | `.spec.ts`, `.spec.tsx`, `.test.ts`, `.test.tsx` | File endings skipped. |
+| `hint` | `string` | none | Appended to every message. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+### Worked example: an app with a post-credential sign-in seam
+
+Every sign-in entry point (password, OAuth, second factor) ends by calling one seam,
+`beginOrEstablish`, which a two-factor challenge service defines. Each entry point reads the epoch with
+`sessionService.readEpoch(userId)` before it checks the credential, and passes it in:
+
+```ts
+createSessionEpochCapturedRule({
+  call: 'beginOrEstablish',
+  exempt: ['apps/api/src/modules/auth/services/two-factor-challenge.service.ts'],
+  captureCall: 'sessionService.readEpoch(userId)',
+  sourceGlobs: [
+    'apps/*/{src,test,tests,security-spec}/**/*.{ts,tsx}',
+    'packages/*/{src,test,tests,security-spec}/**/*.{ts,tsx}',
+    'tools/**/*.{ts,tsx}',
+  ],
+  excludeSuffixes: ['.spec.ts', '.test.ts'],
+});
+```
+
+Two flows in such an app mint without a captured epoch and are outside the rule by construction, because they
+never call the seam: signup (the account did not exist when the request began) and password change (it
+revokes first and then re-issues, so the current counter is the right one).
+
+## When not to use it
+
+Without a revocation epoch (or an equivalent generation counter) there is no fence to extend.

package/docs/rules/session-kind-stamped.md

@@ -0,0 +1,89 @@
+# `session-kind-stamped`
+
+> Every call that mints a session stamps the principal's kind onto it, or sits in an allowlisted,
+> provably single-kind flow.
+
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionKindStampedRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
+Import it from the `session` entry point:
+
+```ts
+import { createSessionKindStampedRule } from '@noctcore/lint-meta-rules/session';
+```
+
+## Why
+
+When one sign-in serves two kinds of account (staff and a customer portal, say) and the request
+pipeline reads the kind from the SESSION rather than the database, the stamp is only as good as the
+mint that wrote it. A session minted without the field reads as whatever the reader defaults to. For the
+fence between the two kinds that is a silent promotion: a portal account whose session lost its stamp
+is a staff caller inside its own tenant, and the tenant boundary waves it through as legitimate.
+
+This is not hypothetical. In one production codebase, two re-issue paths (a password
+change and a revoke-other-sessions action, both reachable by a portal account) shipped without the
+stamp while every gate was green, because nothing mechanical looked.
+
+## What it flags
+
+For each `.<mintCall>(...)` call in a file matched by `sourceGlobs` (arguments found by balancing
+parentheses, so a multi-line options object with nested calls is read whole):
+
+1. If the arguments contain an object literal, that literal must mention `field` as a whole word. Each
+   call is checked on its own, so a file with two mints where only one stamps is still reported.
+2. If the arguments carry no literal (options built elsewhere), the file must mention `field`
+   somewhere. Coarser, but no silent hole.
+3. Otherwise the file must be in `allowUnstamped`.
+
+## What it does not flag
+
+- `.<mintCall>Something(`, and the method's definition.
+- `kindless` or `kinds`: the field must appear as a whole word.
+- Files in `allowUnstamped`, files ending in an `excludeSuffixes` entry, and `skipDirs` segments.
+
+With no `mintCall` the rule is inert.
+
+Residual gap, stated rather than hidden: a file that stamps the field on one delegated mint and forgets
+it on a second delegated mint passes clause 2.
+
+## Options
+
+```ts
+createSessionKindStampedRule(options?: SessionKindStampedOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'session-kind-stamped'` | Rule id. |
+| `mintCall` | `string` | none (inert) | The method whose call mints a session, matched as `.<mintCall>(`. |
+| `field` | `string` | `'kind'` | The session field every mint must stamp. |
+| `allowUnstamped` | `string[]` | `[]` | Repo-relative files whose mints may stamp nothing because they provably never mint for an account that needs the field. Keep it short; write the proof next to each entry. |
+| `stampExample` | `string` | none | An example of the stamp, quoted in the message. |
+| `sourceGlobs` | `string[]` | `[]` (inert) | Application source to read. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `excludeSuffixes` | `string[]` | `.spec.ts`, `.spec.tsx`, `.test.ts`, `.test.tsx` | File endings skipped. |
+| `hint` | `string` | none | Appended to every message. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+### Worked example: an app with staff and portal accounts
+
+One sign-in serves staff accounts and invite-only portal accounts, and every session mint goes
+through `establishSession`. Self-signup only ever creates staff accounts, so its file is allowed to
+mint without a stamp:
+
+```ts
+createSessionKindStampedRule({
+  mintCall: 'establishSession',
+  // Self-signup creates a new tenant and its owner ADMIN; a PORTAL row is only ever
+  // invite-provisioned, so no input to this flow produces a portal session.
+  allowUnstamped: ['apps/api/src/modules/auth/services/register.service.ts'],
+  stampExample: "...(user.kind === 'PORTAL' ? { kind: 'PORTAL' as const } : {})",
+  sourceGlobs: ['apps/*/{src,test,tests,security-spec}/**/*.{ts,tsx}'],
+});
+```
+
+## When not to use it
+
+If the pipeline reads the account kind from the database on every request, a missing stamp costs
+nothing and there is nothing to fence.

package/docs/rules/session-landing-declared.md

@@ -0,0 +1,95 @@
+# `session-landing-declared`
+
+> Every file that opens a door into a session declares where it leaves the caller, and a door whose
+> landing demands a return shape has it.
+
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionLandingDeclaredRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
+Import it from the `session` entry point:
+
+```ts
+import { createSessionLandingDeclaredRule } from '@noctcore/lint-meta-rules/session';
+```
+
+## Why
+
+With two shells behind one sign-in (staff and a customer portal, say), the client can only send an
+account to the right one if the response that ends the sign-in says which kind it is. The first door
+(the password sign-in) usually does. A second door that finishes a sign-in from a different service (a
+second-factor challenge) can return the same union and still have its landing unwired, and nothing
+fails: the account signs in, lands in the wrong shell, and bounces off its guard. In one production
+codebase, every portal account with 2FA enabled did exactly that.
+
+Two sibling rules fence the same seam, [`session-mint-callers`](./session-mint-callers.md) (who may
+mint) and [`session-kind-stamped`](./session-kind-stamped.md) (the session carries the kind). Neither
+can see this, because both are about the session and this is about the RESPONSE.
+
+## What it flags
+
+1. **Completeness.** A file matched by `sourceGlobs` that calls any of `doorCalls` and is not in
+   `doors`. A new door fails the build until someone classifies it, which is what keeps the list an
+   enumeration rather than a docblock nobody updates.
+2. **The landing's demand.** A door whose landing maps to a string in `landings` and whose source never
+   contains that string (for example `Promise<ILoginResult>`, the return type that carries the kind to
+   the client). Coarse on purpose: it proves the kind REACHES the client, which is what a text rule can
+   see; where the client then navigates is the client's own tests' job.
+3. **The declarations.** A door whose `landing` is not a key of `landings`, or whose `because` is empty.
+4. **Staleness.** A door whose file no longer exists, or that `sourceGlobs` do not reach.
+
+## What it does not flag
+
+- A file that only defines a door method (the leading dot is required).
+- A door whose landing maps to `null`: a re-issue that replaces the cookie of a caller already inside a
+  shell has no landing to get wrong.
+- Files ending in an `excludeSuffixes` entry, and `skipDirs` segments.
+
+With no `doorCalls` the rule is inert.
+
+## Options
+
+```ts
+createSessionLandingDeclaredRule(options?: SessionLandingDeclaredOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'session-landing-declared'` | Rule id. |
+| `doorCalls` | `string[]` | `[]` (inert) | Methods whose call opens a door into a session (the mint, and the gate in front of it), each matched as `.<name>(`. |
+| `doors` | `{ file, landing, because }[]` | `[]` | Every door: a repo-relative file, one of the `landings`, and why that landing is right. |
+| `landings` | `Record<string, string \| null>` | `{}` | The landings a door may declare, each mapped to the text a door with it must contain, or `null`. |
+| `sourceGlobs` | `string[]` | `[]` (inert) | Application source to read. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `excludeSuffixes` | `string[]` | `.spec.ts`, `.spec.tsx`, `.test.ts`, `.test.tsx` | File endings skipped. |
+| `hint` | `string` | none | Appended to every message. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+### Worked example: an app with two sign-in shells
+
+Staff and portal accounts share one sign-in and land in different shells. Sessions open through
+`establishSession` or the second-factor gate `beginOrEstablish`. The two doors either kind can reach
+must return `Promise<ILoginResult>`; the rest are staff-only or re-issues:
+
+```ts
+const AUTH = 'apps/api/src/modules/auth';
+
+createSessionLandingDeclaredRule({
+  doorCalls: ['establishSession', 'beginOrEstablish'],
+  landings: { 'login-result': 'Promise<ILoginResult>', reissue: null, 'staff-only': null },
+  doors: [
+    { file: `${AUTH}/services/login.service.ts`, landing: 'login-result', because: 'The password sign-in: either half of the product arrives here.' },
+    { file: `${AUTH}/services/two-factor-challenge.service.ts`, landing: 'login-result', because: 'The second door: verifyChallenge finishes a sign-in on its own.' },
+    { file: `${AUTH}/oauth/oauth.controller.ts`, landing: 'staff-only', because: 'OAuthAccountService refuses a PORTAL account on every resolution branch.' },
+    { file: `${AUTH}/services/register.service.ts`, landing: 'staff-only', because: 'Self-signup mints a tenant and its owner ADMIN.' },
+    { file: `${AUTH}/services/password-change.service.ts`, landing: 'reissue', because: 'The caller already holds a session.' },
+    { file: `${AUTH}/services/session-management.service.ts`, landing: 'reissue', because: 'revokeOthers re-issues the caller their own session.' },
+  ],
+  sourceGlobs: ['apps/*/{src,test,tests,security-spec}/**/*.{ts,tsx}'],
+});
+```
+
+## When not to use it
+
+With a single shell, or with the landing decided server-side by a redirect that already reads the
+account, there is no landing a door can get wrong.

package/docs/rules/session-mint-callers.md

@@ -0,0 +1,85 @@
+# `session-mint-callers`
+
+> The method that mints a session is callable only from an allowlist of files, so a new sign-in
+> entry point cannot skip the gate in front of it.
+
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionMintCallersRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
+Import it from the `session` entry point:
+
+```ts
+import { createSessionMintCallersRule } from '@noctcore/lint-meta-rules/session';
+```
+
+## Why
+
+Most auth stacks have one method that turns an authenticated principal into a session: it writes the
+session store, sets the cookie, rotates CSRF. In front of it sits a gate (a second-factor challenge, an
+epoch capture) that every sign-in is meant to pass through. A new entry point, typically an OAuth
+callback added months later, that calls the mint directly signs the user in with the gate skipped, and
+nothing fails: the flow works, its tests pass, the gate's tests pass. The mint is the one door into a
+session, so this rule fences the door by caller.
+
+## What it flags
+
+A file matched by `sourceGlobs` that calls `.<mintCall>(` (whitespace before the paren allowed) and is
+not in `allowedCallers`.
+
+## What it does not flag
+
+- The method's definition (`async establishSession(`): the leading dot is required.
+- `.<mintCall>Something(`: only whitespace may sit between the name and the paren.
+- Files ending in an `excludeSuffixes` entry (tests drive the mint directly), and paths with a
+  `skipDirs` segment.
+- Everything outside `sourceGlobs`, including a lint-meta rule module that quotes the call.
+
+With no `mintCall` the rule is inert.
+
+## Options
+
+```ts
+createSessionMintCallersRule(options?: SessionMintCallersOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'session-mint-callers'` | Rule id. |
+| `mintCall` | `string` | none (inert) | The method whose call mints a session, matched as `.<mintCall>(`. |
+| `allowedCallers` | `string[]` | `[]` | Repo-relative files that may call it, matched exactly: the method's home, the gate, and flows with no gate to pass (signup, a re-issue to a caller who already holds a session). |
+| `gateCall` | `string` | none | The method a sign-in entry point must call instead, named in the message. |
+| `sourceGlobs` | `string[]` | `[]` (inert) | Application source to read. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `excludeSuffixes` | `string[]` | `.spec.ts`, `.spec.tsx`, `.test.ts`, `.test.tsx` | File endings skipped. |
+| `hint` | `string` | none | Appended to every message, e.g. a pointer to your auth docs. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+### Worked example: an app with a gated session mint
+
+`establishSession` mints the session and `beginOrEstablish` is the second-factor gate every sign-in
+must pass through. Only the mint's home, the gate, signup and the two re-issue flows may call the mint
+directly:
+
+```ts
+const AUTH = 'apps/api/src/modules/auth/services';
+
+createSessionMintCallersRule({
+  id: 'establish-session-callers',
+  mintCall: 'establishSession',
+  gateCall: 'beginOrEstablish',
+  allowedCallers: [
+    `${AUTH}/auth-shared.service.ts`,
+    `${AUTH}/two-factor-challenge.service.ts`,
+    `${AUTH}/register.service.ts`,
+    `${AUTH}/password-change.service.ts`,
+    `${AUTH}/session-management.service.ts`,
+  ],
+  sourceGlobs: ['apps/*/{src,test,tests,security-spec}/**/*.{ts,tsx}'],
+});
+```
+
+## When not to use it
+
+If sessions are minted by a framework you do not call (a hosted auth provider's middleware), there is no
+method to fence.

package/docs/rules/tenant-model-registry-parity.md

@@ -3,6 +3,10 @@
 > Every tenant-bearing Prisma model is scoped by the runtime tenant extension or exempt with a
 > reason, and the tenant lint rules resolve with exactly that registry.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTenantModelRegistryParityRule` from `@noctcore/lint-meta-rules/prisma` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `prisma` entry point:
 
 ```ts
@@ -45,7 +49,17 @@ cannot be resolved.
 
 Async: it implements the harness's `runAsync` (`@noctcore/harness` 0.3.0 or newer).
 
-## Factory
+## What it does not flag
+
+- A schema model that carries only some of the `tenantFields` columns: a model must carry ALL of them
+  to be tenant-bearing.
+- A tenant-bearing model listed in `unscopedByDesign`, once it names its hand-scope columns in
+  `handScopedModels` or records why it cannot in `handScopePending`.
+- Hand-scope gaps when `requireHandScope` is `false`.
+- The resolved ESLint config when `eslint` is `false`; the hand-scope option when `handScopedRule` is
+  `null` or the registry has no hand-scoped models.
+
+## Options
 
 ```ts
 createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions): IMetaRule
@@ -77,10 +91,10 @@ createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions):
 
 Keys are Prisma delegate accessors (`invoice` for `model Invoice`).
 
-## Worked example: Settly
+### Worked example: a multi-tenant monorepo
 
-Settly scopes on `tenantId`, splits its schema per domain, keeps the runtime map in its API's tenant
-extension and the exemption maps in a registry module its ESLint config also reads:
+A project that scopes on `tenantId`, splits its schema per domain, keeps the runtime map in its API's
+tenant extension and the exemption maps in a registry module its ESLint config also reads:
 
 ```ts
 import { createTenantModelRegistryParityRule } from '@noctcore/lint-meta-rules/prisma';

package/docs/rules/test-runner-segregation.md

@@ -2,6 +2,10 @@
 
 > Bun-side and foreign-side test runners are never mixed within a package.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestRunnerSegregationRule` from `@noctcore/lint-meta-rules` · Category `testing` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A package that mixes two test runners (e.g. `bun:test` and Vitest) has tests that run under one
@@ -15,10 +19,18 @@ and the **foreign set** (`vitestDirs`). For every `*.test.ts(x)` file:
 
 - **bun-side** — must import the bun runner (`bunRunnerImport`) and must NOT import the foreign runner
   (`foreignRunnerImport`);
-- **foreign-side** — must NOT import the bun runner. (A direct foreign-runner import is not required —
-  it may arrive transitively via shared test-utils.)
+- **foreign-side** — must NOT import the bun runner.
+
+## What it does not flag
 
-## Factory
+- A foreign-side test with no direct foreign-runner import: the runner may arrive transitively via
+  shared test-utils.
+- A bun-side test that imports `bunRunnerImport` and not the foreign runner.
+- Anything in a `vitestDirs` directory for a missing bun import (those dirs leave the bun set).
+- Files that are not `*.test.ts` / `*.test.tsx` (setup files, helpers), and `require()` or dynamic
+  imports: only a `from '<runner>'` import is read.
+
+## Options
 
 ```ts
 createTestRunnerSegregationRule(options?: TestRunnerSegregationOptions): IMetaRule
@@ -33,8 +45,6 @@ createTestRunnerSegregationRule(options?: TestRunnerSegregationOptions): IMetaRu
 | `foreignRunnerImport` | `string` | `'vitest'` | The foreign runner import specifier. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `bun:test` vs `vitest` and the two dir sets.
-
 ## When not to use it
 
 If your repo uses a single test runner everywhere, this rule has nothing to segregate.

package/docs/rules/test-sibling-enforcement.md

@@ -2,10 +2,14 @@
 
 > Every source file matched by `include` must have a colocated sibling test.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestSiblingEnforcementRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A pure helper with no test is a silent liability — the kind of code that drifts because nothing pins
-its behavior. Requiring a colocated test for a chosen class of files (nightcore's `.utils.ts` sidecars)
+its behavior. Requiring a colocated test for a chosen class of files (`.utils.ts` helper files, say)
 makes "did you test this?" a mechanical check rather than a review-time hope.
 
 ## What it flags
@@ -14,7 +18,13 @@ For each file matched by an `include` glob, the sibling test is the same path wi
 extension replaced by each configured test extension. If none of those siblings exists, the source
 file is flagged. Strict — there is no baseline; the pattern is opt-in via which files `include` selects.
 
-## Factory
+## What it does not flag
+
+- A matched file with a sibling for any one of `testExtensions` (`foo.utils.test.ts` or
+  `foo.utils.test.tsx` for `foo.utils.ts`).
+- Files outside `include` (only `apps/web/src/**/*.utils.ts` by default).
+
+## Options
 
 ```ts
 createTestSiblingEnforcementRule(options?: TestSiblingEnforcementOptions): IMetaRule
@@ -26,9 +36,6 @@ createTestSiblingEnforcementRule(options?: TestSiblingEnforcementOptions): IMeta
 | `testExtensions` | `string[]` | `['.test.ts', '.test.tsx']` | Accepted colocated-test extensions (replace the source extension). |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `apps/web/src/**/*.utils.ts` and the `.utils.test.ts(x)`
-sibling shape.
-
 ## When not to use it
 
 If you colocate tests loosely or centralize them in a `__tests__` tree, retune `include`/`testExtensions`

package/docs/rules/test-workspace-enrollment.md

@@ -2,6 +2,10 @@
 
 > Every tested package must be enumerated in the aggregate test script.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestWorkspaceEnrollmentRule` from `@noctcore/lint-meta-rules` · Category `testing` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 When the CI test command is a hardcoded list of workspace paths, a package added without editing that
@@ -13,10 +17,17 @@ cannot silently escape CI.
 
 Reads the root manifest's `scriptName` command. For each candidate directory (from `packageGlobs`
 plus `extraDirs`, minus `excludeDirs`) that contains at least one file matching `testGlobSuffix`, if
-the directory string does not appear in the script command, it is flagged. A missing or invalid
-manifest is a no-op.
+the directory string does not appear in the script command, it is flagged.
+
+## What it does not flag
 
-## Factory
+- A candidate package with no file matching `testGlobSuffix`.
+- Directories in `excludeDirs` (tested by a different runner or script).
+- Anything when the root manifest is missing or is not valid JSON: the rule is a no-op.
+- A directory whose path appears anywhere in the script text: the check is a substring match, not a
+  parse of the command.
+
+## Options
 
 ```ts
 createTestWorkspaceEnrollmentRule(options?: TestWorkspaceEnrollmentOptions): IMetaRule
@@ -32,9 +43,6 @@ createTestWorkspaceEnrollmentRule(options?: TestWorkspaceEnrollmentOptions): IMe
 | `testGlobSuffix` | `string` | `'**/*.test.ts'` | Glob suffix (per dir) that detects the presence of tests. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded the `test:node` script, a `packages/*` + `apps/sidecar`
-dir list, and a vitest exclusion set.
-
 ## When not to use it
 
 If your test runner discovers packages automatically (no hardcoded path list), this rule is