@noctcore/lint-meta-rules 0.5.0 → 0.6.1

package/docs/rules/eslint-config-no-warn.md

@@ -3,6 +3,10 @@
 > Every rule in the RESOLVED ESLint config is `error` or `off`, never `warn`, including severities a
 > spread preset injects.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createEslintConfigNoWarnRule` from `@noctcore/lint-meta-rules/resolved-config` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `resolved-config` entry point, which (unlike the main one) loads ESLint:
 
 ```ts
@@ -32,11 +36,17 @@ It **fails closed**:
   breaks for one file shape cannot pass on the shapes that still work;
 - a package whose config ignores every probe is a violation, since nothing was checked.
 
-A probe that is merely ignored is fine while another probe resolves.
-
 Async: it implements the harness's `runAsync` (`@noctcore/harness` 0.3.0 or newer).
 
-## Factory
+## What it does not flag
+
+- A probe that is merely ignored, while another probe resolves.
+- A preset `warn` that a later block overrides to `error` or `off`: only the resolved severity counts.
+- A directory matched by `packages` that holds none of `configFiles` (it inherits a config it does not
+  own).
+- Blocks scoped to a file shape no probe matches (`.vue`, `e2e/**`) until you add a probe for it.
+
+## Options
 
 ```ts
 createEslintConfigNoWarnRule(options?: EslintConfigNoWarnOptions): IMetaRule
@@ -50,10 +60,10 @@ createEslintConfigNoWarnRule(options?: EslintConfigNoWarnOptions): IMetaRule
 | `probes` | `string[]` | `src/__lint_meta_probe__.{ts,tsx,test.ts,test.tsx}` | Files, relative to each package, the config is resolved for. Add one per file shape your config scopes blocks to (`.js`, `.vue`, `e2e/**`). |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: a pnpm monorepo
+### Worked example: a pnpm monorepo
 
-Settly-style layout, where every app and package owns a config built from a shared
-`@repo/eslint-config`, and the root config only lints tooling:
+A layout where every app and package owns a config built from a shared `@repo/eslint-config`, and the
+root config only lints tooling:
 
 ```ts
 createEslintConfigNoWarnRule({ packages: ['apps/*', 'packages/*'] });
@@ -63,9 +73,14 @@ Deleting the three `react-hooks/*` overrides from the shared React config (so th
 `recommended-latest` preset's `warn` shows through, with no `warn` literal anywhere) reports three
 rules in each of the three packages that spread it.
 
-## Notes
+### Notes
 
 - The rule resolves with the `eslint` that `@noctcore/lint-meta-rules` resolves, which is the
   consumer's own install when it is hoisted.
 - If a config imports a workspace package that must be built first, build it before lint-meta, or
   the rule reports that the config could not be resolved.
+
+## When not to use it
+
+If your repo has no flat ESLint config per package, or you cannot build the workspace packages a
+config imports before lint-meta runs, rely on [`no-warn-severity`](./no-warn-severity.md) alone.

package/docs/rules/file-size-ratchet.md

@@ -2,10 +2,13 @@
 
 > Source files stay at or under a line cap, with a one-way, self-tightening baseline ratchet.
 
-This single factory subsumes **both** of nightcore's file-size rules — `web-file-size-ratchet`
-(apps/web/src, `.ts`+`.tsx`) and `engine-file-size-ratchet` (packages/engine/src, `.ts`) — which were
-byte-identical logic differing only in scanned roots, extensions and exclusions. Create one instance
-per capped area, each with its own `id` (the `id` names both the rule and its committed baseline file).
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createFileSizeRatchetRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
+One factory covers every capped area: create one instance per area (an app's `src`, a package's
+`src`), each with its own roots, extensions, exclusions and `id`. The `id` names both the rule and its
+committed baseline file.
 
 ## Why
 
@@ -21,14 +24,23 @@ Measured in raw physical lines (`wc -l` semantics). Against a committed baseline
 
 - a **new** over-cap file (not in the baseline), or a baselined one that **grew** past its frozen
   count — a live violation;
-- a baselined file still within its frozen count — **grandfathered** (a stderr notice, no violation);
 - **self-tightening**: a baseline entry whose file is gone, is now at/under the cap, or shrank far
   below its frozen value (`< frozen * tightenRatio`) is itself a violation demanding a baseline update.
 
 The rule implements `baseline(ctx)` (the `IMetaRule` ratchet hook), which snapshots the current
 offender map so the runner can regenerate the frozen file.
 
-## Factory
+## What it does not flag
+
+- A file at or under `cap`.
+- A baselined file still within its frozen count: it is **grandfathered** (a stderr notice, no
+  violation). One that shrank only a little (still at or above `frozen * tightenRatio`) stays
+  grandfathered too.
+- Paths containing an `excludeContains` fragment (tests, specs, stories by default) or starting with an
+  `excludePrefixes` entry, and files whose extension is not in `extensions`.
+- Anything at all when `roots` is empty: the rule is inert until you name a root.
+
+## Options
 
 ```ts
 createFileSizeRatchetRule(options?: FileSizeRatchetOptions): IMetaRule
@@ -46,7 +58,7 @@ createFileSizeRatchetRule(options?: FileSizeRatchetOptions): IMetaRule
 | `baselineDir` | `string` | `.nightcore/lint-meta/baselines` | Where committed baselines live (from `@noctcore/harness`). |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-### Example: the two nightcore instances
+### Example: two capped areas
 
 ```ts
 createFileSizeRatchetRule({
@@ -64,8 +76,6 @@ createFileSizeRatchetRule({
 });
 ```
 
-De-projected from nightcore, which hardcoded the roots, extensions, exclusions and the `400` cap.
-
 ## When not to use it
 
 If you have no over-cap files and no desire to cap file size, skip it. If you want a hard cap with no

package/docs/rules/github-actions-least-privilege-permissions.md

@@ -2,6 +2,10 @@
 
 > A workflow's top-level `permissions:` exists, is not `write-all` / `read-all`, and grants no write.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createGithubActionsLeastPrivilegePermissionsRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 The top-level `permissions:` is the `GITHUB_TOKEN` every job gets unless the job says otherwise. A
@@ -13,6 +17,13 @@ cheapest containment there is.
 
 Keep the top level read-only and grant each write on the job that needs it.
 
+### Prior art
+
+It mirrors zizmor's [`excessive-permissions`](https://docs.zizmor.sh/audits/#excessive-permissions)
+audit and the OpenSSF Scorecard
+[Token-Permissions](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions)
+check.
+
 ## What it flags
 
 - A workflow with no top-level `permissions:`, naming each job that has no job-level
@@ -40,14 +51,18 @@ jobs:
       id-token: write
 ```
 
-## What it leaves alone
+## What it does not flag
 
 - A workflow with no top-level block when every job declares its own `permissions:`: the default
   token then reaches no job.
 - `permissions: {}`, and any scope at `read` or `none`.
 - Writes on a job, a `permissions:` input under a step's `with:`, and a commented-out line.
 
-## Factory
+Line-based text, not a YAML parse. It checks the top level only; a job that grants itself more than
+it uses is not judged. A reusable workflow (`on: workflow_call`) is held to the same bar, although
+its token can never exceed its caller's.
+
+## Options
 
 ```ts
 createGithubActionsLeastPrivilegePermissionsRule(options?: GithubActionsLeastPrivilegePermissionsOptions): IMetaRule
@@ -59,13 +74,7 @@ createGithubActionsLeastPrivilegePermissionsRule(options?: GithubActionsLeastPri
 | `allowTopLevelWrite` | `string[]` | `[]` | Scopes allowed at `write` in the top-level block, for a repo that accepts, say, `contents: write` on a single-job release workflow. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
-
-Line-based text, not a YAML parse. It checks the top level only; a job that grants itself more than
-it uses is not judged. A reusable workflow (`on: workflow_call`) is held to the same bar, although
-its token can never exceed its caller's.
+## When not to use it
 
-Prior art: zizmor's [`excessive-permissions`](https://docs.zizmor.sh/audits/#excessive-permissions)
-audit and the OpenSSF Scorecard
-[Token-Permissions](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions)
-check.
+If your repo has no GitHub Actions workflows there is nothing to check. If zizmor's
+`excessive-permissions` audit already gates CI, one of the two is enough.

package/docs/rules/github-actions-no-template-injection.md

@@ -2,6 +2,10 @@
 
 > `run:` scripts and `actions/github-script` bodies never expand attacker-controllable `${{ }}` context.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createGithubActionsNoTemplateInjectionRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 GitHub substitutes `${{ }}` into a `run:` script before the shell sees it. A PR titled
@@ -14,6 +18,12 @@ JavaScript built from the substituted text.
 The fix is to pass the value through `env:` and read it as a variable. An environment variable is
 data; the shell never parses its contents as script.
 
+### Prior art
+
+It mirrors zizmor's [`template-injection`](https://docs.zizmor.sh/audits/#template-injection) audit
+and GitHub's
+[security hardening guide](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections).
+
 ## What it flags
 
 A `${{ }}` expression inside a `run:` value (inline, a `|` / `>` block, or a multi-line plain
@@ -53,7 +63,7 @@ carries the 1-indexed line.
     script: console.log(process.env.BODY)
 ```
 
-## What it leaves alone
+## What it does not flag
 
 - The same expression under `env:`, `with:` (other than a github-script `script:`), `if:`,
   `name:` or `defaults.run`. Those are not parsed as script.
@@ -65,7 +75,13 @@ carries the 1-indexed line.
   strips before GitHub sees the value.
 - Paths with a `node_modules`, `.git`, `dist`, `.turbo` or `coverage` segment.
 
-## Factory
+Line-based text, not a YAML parse. An expression split across lines, the bracket form
+(`github.event['issue']['title']`), `toJSON(github.event)` and a value laundered through `env.*`
+set from event text are not seen. An expression that only tests a tainted field
+(`${{ contains(github.event.issue.title, 'x') }}`) evaluates to a boolean but is still reported;
+move the test to `if:` or into the script.
+
+## Options
 
 ```ts
 createGithubActionsNoTemplateInjectionRule(options?: GithubActionsNoTemplateInjectionOptions): IMetaRule
@@ -80,14 +96,7 @@ createGithubActionsNoTemplateInjectionRule(options?: GithubActionsNoTemplateInje
 | `checkStepOutputs` | `boolean` | `false` | Treat `steps.*.outputs.*` as attacker-controlled. Turn it on when steps echo event text into outputs. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-Line-based text, not a YAML parse. An expression split across lines, the bracket form
-(`github.event['issue']['title']`), `toJSON(github.event)` and a value laundered through `env.*`
-set from event text are not seen. An expression that only tests a tainted field
-(`${{ contains(github.event.issue.title, 'x') }}`) evaluates to a boolean but is still reported;
-move the test to `if:` or into the script.
-
-Prior art: zizmor's [`template-injection`](https://docs.zizmor.sh/audits/#template-injection) audit
-and GitHub's
-[security hardening guide](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections).
+If your repo has no GitHub Actions workflows or composite actions there is nothing to check. If
+zizmor's `template-injection` audit already gates CI, one of the two is enough.

package/docs/rules/github-actions-runner-pinned.md

@@ -2,6 +2,10 @@
 
 > Workflow jobs run on a named runner image, never a `*-latest` label.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createGithubActionsRunnerPinnedRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 GitHub repoints `ubuntu-latest` (and `macos-latest`, `windows-latest`) to a new OS image on its own
@@ -11,8 +15,7 @@ repo. Pinning a named image makes the move a reviewed diff.
 ## What it flags
 
 Every floating label in a `runs-on:` value, read as a scalar, a flow list (`[a, b]`), a block list, or
-a `group:` / `labels:` mapping. An expression (`${{ matrix.os }}`) cannot be judged from the text and
-is left alone; a commented-out `runs-on:` is ignored.
+a `group:` / `labels:` mapping.
 
 ```yaml
 # Bad
@@ -24,7 +27,17 @@ runs-on: ubuntu-24.04
 runs-on: ${{ matrix.os }}
 ```
 
-## Factory
+## What it does not flag
+
+- A named image (`ubuntu-24.04`), quoted or with a trailing comment, and a custom label such as
+  `self-hosted`.
+- An expression (`${{ matrix.os }}`): it cannot be judged from the text.
+- A commented-out `runs-on:`, and a later key in the job (`name: ubuntu-latest`) after the label list.
+
+Line-based text, not a YAML parse. A matrix value such as `os: [ubuntu-latest]` that feeds
+`runs-on: ${{ matrix.os }}` is not checked.
+
+## Options
 
 ```ts
 createGithubActionsRunnerPinnedRule(options?: GithubActionsRunnerPinnedOptions): IMetaRule
@@ -36,7 +49,7 @@ createGithubActionsRunnerPinnedRule(options?: GithubActionsRunnerPinnedOptions):
 | `floatingLabel` | `RegExp` | `/^[\w.-]+-latest$/u` | A label matching this is floating. Do not pass a `g`-flagged regex. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-Line-based text, not a YAML parse. A matrix value such as `os: [ubuntu-latest]` that feeds
-`runs-on: ${{ matrix.os }}` is not checked.
+If you want your CI to track GitHub's newest runner images automatically and accept the unreviewed
+moves, skip it.

package/docs/rules/github-actions-sha-pinned.md

@@ -2,6 +2,10 @@
 
 > GitHub Actions `uses:` refs are pinned to a 40-character commit SHA with a `# vN` comment.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createGithubActionsShaPinnedRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A tag or branch ref is a moving target: whoever controls the action's repository can repoint it, and
@@ -17,7 +21,7 @@ Every `uses:` line (step-level and job-level reusable workflow calls) in the sca
 - a SHA-pinned ref with no `# vN` comment,
 - a `docker://` ref with no `@sha256:<digest>`.
 
-Local actions (`uses: ./path`) are exempt. Each violation carries the 1-indexed line.
+Each violation carries the 1-indexed line.
 
 ```yaml
 # Bad
@@ -29,7 +33,17 @@ Local actions (`uses: ./path`) are exempt. Each violation carries the 1-indexed
 - uses: ./.github/actions/setup
 ```
 
-## Factory
+## What it does not flag
+
+- Local actions (`uses: ./path`).
+- A full 40-character SHA with a `# vN` comment, quoted or not, including a path inside the action
+  repo (`github/codeql-action/analyze@<sha> # v3`).
+- A `docker://` ref pinned by `@sha256:<digest>`.
+
+The check is line-based text, not a YAML parse. A `uses:` value split across lines, or built from an
+expression, is not seen.
+
+## Options
 
 ```ts
 createGithubActionsShaPinnedRule(options?: GithubActionsShaPinnedOptions): IMetaRule
@@ -40,7 +54,7 @@ createGithubActionsShaPinnedRule(options?: GithubActionsShaPinnedOptions): IMeta
 | `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
 
-The check is line-based text, not a YAML parse. A `uses:` value split across lines, or built from an
-expression, is not seen.
+If your repo has no GitHub Actions workflows, or you accept tag refs and review action updates some
+other way, skip it.

package/docs/rules/idempotency-key-parity.md

@@ -0,0 +1,91 @@
+# `idempotency-key-parity`
+
+> A procedure guarded by an idempotency middleware has a client caller that sends the key, or no
+> client caller at all.
+
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createIdempotencyKeyParityRule` from `@noctcore/lint-meta-rules/trpc` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
+Import it from the `trpc` entry point:
+
+```ts
+import { createIdempotencyKeyParityRule } from '@noctcore/lint-meta-rules/trpc';
+```
+
+## Why
+
+An idempotency middleware only de-duplicates when the client sends a key, and neither half fails when
+the other is missing. The server passes the request straight through, the client gets a normal
+response, and both test suites pass. A guard nobody sends a key to is decoration advertising
+double-submit protection that does not exist. One audit of a production API found 14 of 30 guarded
+procedures whose only web caller had never sent a key.
+
+The gap is only visible by holding the two lists side by side, which is what this rule does.
+
+## What it flags
+
+For every method in a `routerGlobs` file decorated with a `@<middlewareDecorator>(...)` list naming
+`middleware` (as a whole word), the rule derives `<alias>.<method>` from the class's
+`@<routerDecorator>({ <aliasKey>: '...' })`. If some `clientGlobs` file contains
+`<clientPrefix><alias>.<method>` and none of those files contains `keyToken`, the router file is
+reported.
+
+The method is read from the decorator to the next `async <name>(`, the shape `nestjs-trpc` routers
+take.
+
+## What it does not flag
+
+- A guarded procedure with no client caller: the guard is correct in advance of the screen that will
+  use it, and demanding a caller would be demanding the screen.
+- A procedure without the middleware, even when a client sends it a key: the header is ignored, so it
+  is inert rather than misleading.
+- A middleware whose name merely starts with the configured one (`IdempotencyMiddlewareLegacy`).
+- Procedures listed in `exempt`, and a router file with no alias.
+
+A key sent from a DIFFERENT client file than the one naming the call counts, and so does a client test
+file, if `clientGlobs` match it: the check is per procedure, across the client tree.
+
+With no `middleware` the rule is inert.
+
+## Options
+
+```ts
+createIdempotencyKeyParityRule(options?: IdempotencyKeyParityOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'idempotency-key-parity'` | Rule id. |
+| `middleware` | `string` | none (inert) | The middleware class that de-duplicates on a client-sent key. |
+| `routerGlobs` | `string[]` | `[]` | Server router files. |
+| `clientGlobs` | `string[]` | `[]` | Every client file that can call a procedure or send a key. |
+| `keyToken` | `string` | `'idempotencyKey'` | The token a client file must mention to count as sending a key. |
+| `clientPrefix` | `string` | `'trpc.'` | What precedes `<alias>.<method>` at a client call site. |
+| `routerDecorator` | `string` | `'Router'` | The class decorator that names the router. |
+| `aliasKey` | `string` | `'alias'` | The key in that decorator's object holding the alias. |
+| `middlewareDecorator` | `string` | `'UseMiddlewares'` | The method decorator listing a procedure's middlewares. |
+| `exempt` | `string[]` | `[]` | `<alias>.<method>` procedures whose caller deliberately sends no key. Keep it empty: the honest fix is to drop the middleware. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `hint` | `string` | none | Appended to every message: how this project threads the key. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+### Worked example: an app with an idempotency middleware
+
+A NestJS API guards its mutations with an `IdempotencyMiddleware` in `*.router.ts` files, and a web app
+calls them through tRPC hooks. The `hint` tells whoever hits a violation how the web app threads the
+key:
+
+```ts
+createIdempotencyKeyParityRule({
+  middleware: 'IdempotencyMiddleware',
+  routerGlobs: ['apps/api/src/**/*.router.ts'],
+  clientGlobs: ['apps/web/src/**/*.{ts,tsx}'],
+  hint: "Thread `trpc: { context: { idempotencyKey } }` through the hook's mutationOptions (see hooks/use-idempotency-key.ts).",
+});
+```
+
+## When not to use it
+
+If the key is generated server-side or by a client interceptor on every mutation, no call site can
+forget it.

package/docs/rules/layer-rank.md

@@ -3,6 +3,10 @@
 > A module may import only strictly-lower-ranked `<scope>` packages — equal (sideways) or higher
 > (upward) is forbidden.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createLayerRankRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Layered architectures encode a fixed dependency direction (e.g. `contracts → shared → storage/skills
@@ -15,11 +19,19 @@ are caught before they calcify.
 Each source file is assigned an **importer rank**: surface files (matched by `surfacePrefix`) get
 `surfaceRank`; otherwise the `packageDirPattern` capture is looked up in `ranks`. For each
 `<scope>/<pkg>` import whose target is also ranked, the rule flags it when the target rank is `>=` the
-importer rank (sideways when equal, upward when greater). Unranked importers and unranked targets are
-skipped, so a package outside the documented spine never produces a false positive. Test files are
-skipped.
+importer rank (sideways when equal, upward when greater).
+
+## What it does not flag
+
+- A downward import: the target's rank is strictly lower than the importer's.
+- Unranked importers and unranked targets, so a package outside the documented spine never produces a
+  false positive. Surface files are unranked unless `surfaceRank` is set.
+- Test files (`.test.ts`, `.test.tsx`).
+- Imports without a `from` clause (`import '<scope>/x'`, `import()`, `require()`): only
+  `from '<scope>/<pkg>'` is read.
+- Anything at all while `ranks` is empty.
 
-## Factory
+## Options
 
 ```ts
 createLayerRankRule(options?: LayerRankOptions): IMetaRule
@@ -35,8 +47,7 @@ createLayerRankRule(options?: LayerRankOptions): IMetaRule
 | `sourceGlobs` | `string[]` | packages + apps `src/**` `.ts`/`.tsx` | Source files to scan. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded a fixed rank table and the `@nightcore` scope. `ranks`
-defaults to `{}` so the rule is inert until a consumer supplies its own layering.
+`ranks` defaults to `{}`, so the rule is inert until you supply your own layering.
 
 ## When not to use it
 

package/docs/rules/no-cloned-component-folders.md

@@ -2,6 +2,10 @@
 
 > A component folder name may exist under only one feature.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createNoClonedComponentFoldersRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Same-named component folders across features are how sibling drift starts: a component cloned into a
@@ -16,7 +20,15 @@ A `<feature>/<Name>/<barrelFile>` path marks a component folder. Grouping by `<N
 `allowedClones` — is flagged. The allowlist freezes today's clone groups and only shrinks: an
 `allowedClones` entry whose clone group no longer exists is itself flagged as stale.
 
-## Factory
+## What it does not flag
+
+- A component folder name that exists under only one feature.
+- Folders under `excludedFeatures` (`ui` and `app` by default).
+- Names in `allowedClones` while their clone group still exists.
+- Folders without the `barrelFile`, and folders nested deeper than `<feature>/<Name>/` under
+  `componentsRoot`.
+
+## Options
 
 ```ts
 createNoClonedComponentFoldersRule(options?: NoClonedComponentFoldersOptions): IMetaRule
@@ -31,9 +43,6 @@ createNoClonedComponentFoldersRule(options?: NoClonedComponentFoldersOptions): I
 | `sharedDest` | `string` | `'components/ui'` | Where a shared surface should be hoisted (used in the message). |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `apps/web/src/components`, the `ui`/`app` excluded
-features, and a fixed `ALLOWED_CLONES` set.
-
 ## When not to use it
 
 If your components are not organized as `<feature>/<Component>/` folders under one root, or you

package/docs/rules/no-warn-severity.md

@@ -2,6 +2,10 @@
 
 > ESLint severity is `error` or `off`, never `warn`.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createNoWarnSeverityRule` from `@noctcore/lint-meta-rules` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Agents iterate by reading CI failures. A `warn` severity is a silent miss — it neither fails the
@@ -14,7 +18,16 @@ Reads each configured flat-config file (skipping any that do not exist), strips
 reports any line containing a `'warn'` / `"warn"` severity literal. The violation carries the
 1-indexed line number.
 
-## Factory
+## What it does not flag
+
+- A `'warn'` inside a `//` line comment.
+- The numeric severity `1`: only the quoted `'warn'` / `"warn"` literal is matched.
+- A `warn` a spread preset injects, since no file the project owns spells it. Use
+  [`eslint-config-no-warn`](./eslint-config-no-warn.md) for the resolved config.
+- Config files not listed in `configFiles` (the defaults are the root flat configs), and listed ones that
+  do not exist.
+
+## Options
 
 ```ts
 createNoWarnSeverityRule(options?: NoWarnSeverityOptions): IMetaRule
@@ -25,8 +38,6 @@ createNoWarnSeverityRule(options?: NoWarnSeverityOptions): IMetaRule
 | `configFiles` | `string[]` | `['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs']` | Flat-config files to scan; each is read only if present. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `eslint.config.mjs`.
-
 ## When not to use it
 
 If your project deliberately uses `warn` as an in-editor nudge that is not meant to gate CI, this rule

package/docs/rules/package-shape.md

@@ -3,6 +3,10 @@
 > Every workspace is named `<scope>/<dir>`; library packages expose a barrel and point their build
 > fields at the built output.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createPackageShapeRule` from `@noctcore/lint-meta-rules` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A monorepo stays navigable when a package's identity is mechanical: its npm name matches its folder,
@@ -20,10 +24,16 @@ For each `package.json` matched by `libraryGlobs` (full checks) or `appGlobs` (n
   `distMarker`, and `exports` must reference it.
 - **invalid JSON** — reported as a violation.
 
-App/surface packages are deployable entrypoints (vite/tauri/bun), so only the name check applies to
-them.
+## What it does not flag
+
+- Barrel and build-field problems in app/surface packages: they are deployable entrypoints
+  (vite/tauri/bun), so only the name check applies to them.
+- A package whose directory has an `externalNames` entry and whose name equals it.
+- A missing `distFields` entry or a missing `exports`: only fields that are present are checked, and
+  `exports` passes when any of its targets contains `distMarker`.
+- `package.json` files outside `libraryGlobs` and `appGlobs`.
 
-## Factory
+## Options
 
 ```ts
 createPackageShapeRule(options?: PackageShapeOptions): IMetaRule
@@ -40,9 +50,6 @@ createPackageShapeRule(options?: PackageShapeOptions): IMetaRule
 | `distFields` | `string[]` | `['main','module','types']` | `package.json` string fields that must point at built output. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded the `@nightcore` scope, the `packages/*` vs `apps/*`
-split, the `src/index.ts` barrel and the `dist/` marker.
-
 ## When not to use it
 
 If your packages are not scope-named after their folders, or libraries publish raw source (no build

package/docs/rules/prisma-method-surface.md

@@ -3,6 +3,10 @@
 > The Prisma reads and writes your rules police partition the generated client's `<Model>Delegate`
 > method surface exactly, so a Prisma upgrade cannot add an unguarded method.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createPrismaMethodSurfaceRule` 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
@@ -30,10 +34,16 @@ configured reads and writes are exactly its delegate surface.
 It **fails closed**: no generated client under `clientGlobs` is a violation, because a checkout that
 never ran `prisma generate` is exactly where drift hides. Run `prisma generate` before lint-meta.
 
+## What it does not flag
+
+- A generated client whose delegates expose exactly the configured reads and writes, in either the
+  per-model (`prisma-client`) or the single-file (`prisma-client-js`) layout.
+- Members that are not query methods: `fields`, the symbol brand and `$`-prefixed members.
+
 Members are read line by line: a delegate method is a generic, `name<T ...>(...)`, at the interface's
-member indentation. `fields`, the symbol brand and `$`-prefixed members are not query methods.
+member indentation, so a non-generic member is not counted.
 
-## Factory
+## Options
 
 ```ts
 createPrismaMethodSurfaceRule(options?: PrismaMethodSurfaceOptions): IMetaRule
@@ -50,9 +60,9 @@ createPrismaMethodSurfaceRule(options?: PrismaMethodSurfaceOptions): IMetaRule
 With the defaults, the rule checks the exact lists `@noctcore/eslint-plugin-prisma`'s rules read.
 If your own rules read their own lists, pass those.
 
-## Worked example: Settly
+### Worked example: a monorepo with a database package
 
-Settly's schema generates into `packages/database/generated/prisma` with the `prisma-client`
+A schema that generates into `packages/database/generated/prisma` with the `prisma-client`
 generator:
 
 ```ts
@@ -63,3 +73,8 @@ createPrismaMethodSurfaceRule({
 
 Adding a method to every generated delegate reports it as unguarded; adding it to one model only
 reports that delegate as divergent; removing the generated folder reports that no client was found.
+
+## When not to use it
+
+If no lint rule of yours reads a list of Prisma method names (no tenant, writer or transaction fence),
+there is no list to keep in step, so skip it.