npm - @noctcore/lint-meta-rules - Versions diffs - 0.6.0 → 0.6.1 - Mend

@noctcore/lint-meta-rules 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

package/README.md +83 -73
package/docs/rules/agents-doc-presence.md +13 -4
package/docs/rules/canonical-helpers-single-home.md +13 -3
package/docs/rules/dockerfile-base-image-digest-pin.md +17 -4
package/docs/rules/eslint-config-no-warn.md +22 -7
package/docs/rules/file-size-ratchet.md +19 -9
package/docs/rules/github-actions-least-privilege-permissions.md +20 -11
package/docs/rules/github-actions-no-template-injection.md +21 -12
package/docs/rules/github-actions-runner-pinned.md +19 -6
package/docs/rules/github-actions-sha-pinned.md +19 -5
package/docs/rules/idempotency-key-parity.md +13 -5
package/docs/rules/layer-rank.md +17 -6
package/docs/rules/no-cloned-component-folders.md +13 -4
package/docs/rules/no-warn-severity.md +14 -3
package/docs/rules/package-shape.md +13 -6
package/docs/rules/prisma-method-surface.md +19 -4
package/docs/rules/security-scanner-version-parity.md +16 -7
package/docs/rules/service-image-digest-pin.md +21 -7
package/docs/rules/session-epoch-captured.md +15 -9
package/docs/rules/session-kind-stamped.md +15 -7
package/docs/rules/session-landing-declared.md +13 -5
package/docs/rules/session-mint-callers.md +11 -3
package/docs/rules/tenant-model-registry-parity.md +18 -4
package/docs/rules/test-runner-segregation.md +15 -5
package/docs/rules/test-sibling-enforcement.md +12 -5
package/docs/rules/test-workspace-enrollment.md +14 -6
package/docs/rules/translation-dead-keys.md +33 -20
package/docs/rules/ui-primitive-shape.md +13 -4
package/docs/rules/workspace-graph-parity.md +15 -5
package/package.json +4 -4

package/README.md CHANGED Viewed

@@ -1,32 +1,56 @@
 # @noctcore/lint-meta-rules
-Portable, parameterized **lint-meta** rules — whole-repo / cross-file invariants that ESLint's
-per-file AST model cannot reach (every `package.json` name matches a convention, every imported
-workspace package is a declared dependency, file-size ratchets, agent-doc presence, and more).
+Whole-repo checks that ESLint's one-file-at-a-time model cannot make: every workspace is named by
+convention, every imported workspace package is a declared dependency, every GitHub Action is pinned
+to a commit SHA, no ESLint rule resolves to `warn`, no source file grows past a line cap, and more.
+This is not an ESLint plugin; the rules run under the
+[`@noctcore/harness`](https://www.npmjs.com/package/@noctcore/harness) `lint-meta` runner.
-Each rule implements the portable [`IMetaRule`](https://www.npmjs.com/package/@noctcore/harness)
-contract published by `@noctcore/harness`: a pure function of an `IMetaCtx` returning `IViolation[]`.
+**Docs:** [noctcore.github.io/eslint-plugins/packages/lint-meta-rules](https://noctcore.github.io/eslint-plugins/packages/lint-meta-rules/)
-## How this package is consumed
+Not a good fit if you are not running the harness.
-This is a **versioned source catalog**, not a runtime dependency you `require()` from a consumer's
-registry. The `@noctcore/harness` `lint-meta` subcommand runs a *bounded eval* that executes only one
-local `.nightcore/lint-meta/registry.js` and never resolves arbitrary imports — a deliberate security
-boundary, since that file runs inside a foreign CI. So the intended integration point is nightcore's
-harness **export pipeline**: it reads a rule's source here, inlines/transforms it, and emits flat
-JavaScript directly into a consumer's `.nightcore/lint-meta/`. No consumer registry imports this
-package at runtime.
+## What it checks
-Publishing to npm is for versioning and discoverability; it is not a "`npm install` this and
-`require()` it" pitch.
+- **config**: workspace package names and build fields, the workspace dependency graph against
+  imports and tsconfig references, ESLint severities.
+- **source-text**: layering between packages, a file-size ratchet, agent-doc presence, colocated
+  tests, one home per helper, no cloned component folders, UI primitive shape.
+- **testing**: every tested package is enrolled in the aggregate test script, and test runners are
+  not mixed within a package.
+- **ci**: GitHub Actions pinned by SHA and to named runners, no template injection, least-privilege
+  permissions, container images pinned by digest, and the secret scanner pinned to one version.
-## Why factories
+Every check is listed in [Rules](#rules), with a page per rule.
-`IMetaRule.run(ctx)` takes no config, so every rule that hardcoded a nightcore-specific anchor (a
-`@nightcore` scope, an `apps/web/src` root, a rank table) is exported as a **factory** —
-`createXRule(options): IMetaRule` — with those anchors lifted to typed options carrying sensible
-defaults. A programmatic caller (or the export pipeline) constructs each rule with the consumer's own
-options:
+## Install
+```sh
+bun add -D @noctcore/harness @noctcore/lint-meta-rules   # or npm i -D / pnpm add -D
+```
+The `/i18n`, `/resolved-config` and `/prisma` entry points also need the optional peer `eslint`, and
+`/i18n` needs `@typescript-eslint/parser` (see [Rules](#rules)).
+## Run with the harness
+Each rule implements the [`IMetaRule`](https://www.npmjs.com/package/@noctcore/harness) contract
+from `@noctcore/harness`: a pure function of an `IMetaCtx` returning `IViolation[]`. The harness
+`lint-meta` subcommand runs them.
+You do not `require()` this package from your repo. The harness executes only one local file,
+`.nightcore/lint-meta/registry.js`, and never resolves arbitrary imports, because that file runs
+inside CI. Its **export pipeline** reads a rule's source from this package, inlines it and writes
+plain JavaScript into your repo's `.nightcore/lint-meta/`. The package is on npm for versioning and
+discoverability.
+### Every rule is a factory
+`IMetaRule.run(ctx)` takes no config, so each rule is exported as a **factory**,
+`createXRule(options): IMetaRule`. Anything project-specific (a workspace scope, a source root, a
+rank table) is a typed option with a default. Some defaults, such as the `@nightcore` scope and the
+400-line cap, are only starting points: set your own. A programmatic caller (or the export pipeline)
+constructs each rule with your options:
 ```ts
 import { createPackageShapeRule, createFileSizeRatchetRule } from '@noctcore/lint-meta-rules';
@@ -42,33 +66,43 @@ over the whole catalog.
 ## Rules
-13 nightcore lint-meta rules are ported as 12 factories — nightcore's `web-file-size-ratchet` and
-`engine-file-size-ratchet` were byte-identical logic and collapse into a single
-`createFileSizeRatchetRule` (instantiated once per capped area). Five CI-hygiene rules (category
-`ci`) are ported from a production NestJS + Vite monorepo, one factory each, and two GitHub Actions
-security rules (also `ci`) are written for this catalog, for 19 factories in all.
-| Factory | Source rule(s) | Category | What it enforces |
-| --- | --- | --- | --- |
-| [`createNoWarnSeverityRule`](./docs/rules/no-warn-severity.md) | `no-warn-severity` | config | ESLint severity is `error`/`off`, never `warn`. |
-| [`createPackageShapeRule`](./docs/rules/package-shape.md) | `package-shape` | config | Every workspace is named `<scope>/<dir>`; libraries expose a barrel and point build fields at `dist/`. |
-| [`createWorkspaceGraphParityRule`](./docs/rules/workspace-graph-parity.md) | `workspace-graph-parity` | config | Imported `<scope>/*` specifiers are declared `workspace:*` deps and mirrored in tsconfig references. |
-| [`createLayerRankRule`](./docs/rules/layer-rank.md) | `layer-rank` | source-text | A module imports only strictly-lower-ranked `<scope>` packages (no sideways/upward edges). |
-| [`createFileSizeRatchetRule`](./docs/rules/file-size-ratchet.md) | `web-file-size-ratchet`, `engine-file-size-ratchet` | source-text | Source files stay under a line cap, with a one-way self-tightening baseline ratchet. |
-| [`createAgentsDocPresenceRule`](./docs/rules/agents-doc-presence.md) | `agents-doc-presence` | source-text | An agent-contract doc exists at the root, every surface, and every non-opted-out package. |
-| [`createTestSiblingEnforcementRule`](./docs/rules/test-sibling-enforcement.md) | `test-sibling-enforcement` | source-text | Every source file matched by `include` has a colocated sibling test. |
-| [`createCanonicalHelpersSingleHomeRule`](./docs/rules/canonical-helpers-single-home.md) | `canonical-helpers-single-home` | source-text | A helper symbol is not exported from two different helper homes. |
-| [`createNoClonedComponentFoldersRule`](./docs/rules/no-cloned-component-folders.md) | `no-cloned-component-folders` | source-text | A component folder name exists under only one feature (shrinking allowlist). |
-| [`createUiPrimitiveShapeRule`](./docs/rules/ui-primitive-shape.md) | `ui-primitive-shape` | source-text | A folder primitive ships its proof siblings; a flat primitive carries none at the ui root. |
-| [`createTestWorkspaceEnrollmentRule`](./docs/rules/test-workspace-enrollment.md) | `test-workspace-enrollment` | testing | Every tested package is enumerated in the aggregate test script. |
-| [`createTestRunnerSegregationRule`](./docs/rules/test-runner-segregation.md) | `test-runner-segregation` | testing | Bun-side and foreign-side test runners are never mixed within a package. |
-| [`createGithubActionsShaPinnedRule`](./docs/rules/github-actions-sha-pinned.md) | `github-actions-sha-pinned` | ci | Workflow `uses:` refs are pinned to a full commit SHA with a `# vN` comment. |
-| [`createGithubActionsRunnerPinnedRule`](./docs/rules/github-actions-runner-pinned.md) | `github-actions-runner-pinned` | ci | Workflow jobs run on a named runner image, never a `*-latest` label. |
-| [`createGithubActionsNoTemplateInjectionRule`](./docs/rules/github-actions-no-template-injection.md) | `github-actions-no-template-injection` | ci | `run:` and github-script bodies never expand attacker-controllable `${{ }}` context (issue/PR titles, comments, branch names). |
-| [`createGithubActionsLeastPrivilegePermissionsRule`](./docs/rules/github-actions-least-privilege-permissions.md) | `github-actions-least-privilege-permissions` | ci | A workflow's top-level `permissions:` exists, is not `write-all`/`read-all`, and grants no write. |
-| [`createServiceImageDigestPinRule`](./docs/rules/service-image-digest-pin.md) | `service-image-digest-pin` | ci | Workflow service/container images and compose images are pinned by `@sha256:` digest. |
-| [`createDockerfileBaseImageDigestPinRule`](./docs/rules/dockerfile-base-image-digest-pin.md) | `dockerfile-base-image-digest-pin` | ci | Dockerfile `FROM` base images are pinned by `@sha256:` digest. |
-| [`createSecurityScannerVersionParityRule`](./docs/rules/security-scanner-version-parity.md) | `security-scanner-version-parity` | ci | CI and the local pre-push hook pin the same secret-scanner version, and the hook checks it at run time. |
+The main entry exports 19 factories. `createFileSizeRatchetRule` covers any number of capped areas:
+create one instance per area, each with its own `id`.
+<!-- begin generated rules -->
+<!-- Generated by `bun run docs:readmes` from each rule's meta. Do not edit by hand. -->
+| Rule | Description | Factory | Import from | Category | Fails CI by default |
+| --- | --- | --- | --- | --- | --- |
+| [`agents-doc-presence`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/agents-doc-presence/) | AGENTS.md must exist at the repo root, every surface, and every non-opted-out package. | `createAgentsDocPresenceRule` | `@noctcore/lint-meta-rules` | `source-text` | yes |
+| [`canonical-helpers-single-home`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/canonical-helpers-single-home/) | Pure helpers must live in one canonical home (flag the same exported symbol appearing in multiple homes). | `createCanonicalHelpersSingleHomeRule` | `@noctcore/lint-meta-rules` | `source-text` | yes |
+| [`dockerfile-base-image-digest-pin`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/dockerfile-base-image-digest-pin/) | Dockerfile FROM base images must be pinned by `@sha256:` digest (scratch and earlier build stages exempt). | `createDockerfileBaseImageDigestPinRule` | `@noctcore/lint-meta-rules` | `ci` | yes |
+| [`file-size-ratchet`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/file-size-ratchet/) | Source files stay at or under 400 raw lines. Today's offenders are grandfathered by .nightcore/lint-meta/baselines/file-size-ratchet.json; a new/grown offender fails, and a stale/shrunk baseline entry demands tightening. | `createFileSizeRatchetRule` | `@noctcore/lint-meta-rules` | `source-text` | yes |
+| [`github-actions-least-privilege-permissions`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/github-actions-least-privilege-permissions/) | GitHub Actions workflows declare a read-only top-level `permissions:` (no `write-all`/`read-all`, no `<scope>: write`); writes go on the job that needs them. | `createGithubActionsLeastPrivilegePermissionsRule` | `@noctcore/lint-meta-rules` | `ci` | yes |
+| [`github-actions-no-template-injection`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/github-actions-no-template-injection/) | GitHub Actions `run:` and github-script bodies never expand attacker-controllable `${{ }}` context (issue/PR titles, comments, branch names); pass it through `env:` instead. | `createGithubActionsNoTemplateInjectionRule` | `@noctcore/lint-meta-rules` | `ci` | yes |
+| [`github-actions-runner-pinned`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/github-actions-runner-pinned/) | GitHub Actions jobs must run on a pinned runner image (for example ubuntu-24.04), never a *-latest label. | `createGithubActionsRunnerPinnedRule` | `@noctcore/lint-meta-rules` | `ci` | yes |
+| [`github-actions-sha-pinned`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/github-actions-sha-pinned/) | GitHub Actions `uses:` refs must be pinned to a 40-character commit SHA with a `# vN` comment (local ./ actions exempt). | `createGithubActionsShaPinnedRule` | `@noctcore/lint-meta-rules` | `ci` | yes |
+| [`layer-rank`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/layer-rank/) | Fixed dependency direction by rank: a module imports only strictly-lower-ranked &lt;scope&gt; packages (equal/upward forbidden). | `createLayerRankRule` | `@noctcore/lint-meta-rules` | `source-text` | yes |
+| [`no-cloned-component-folders`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/no-cloned-component-folders/) | A component folder name may exist under only ONE feature. Shared surfaces are hoisted; divergent ones get a divergent name. Today’s clones are frozen in a shrinking allowlist. | `createNoClonedComponentFoldersRule` | `@noctcore/lint-meta-rules` | `source-text` | yes |
+| [`no-warn-severity`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/no-warn-severity/) | ESLint severity is 'error' or 'off', never 'warn'. A rule that matters is an error; a failure is fixed, not silenced. | `createNoWarnSeverityRule` | `@noctcore/lint-meta-rules` | `config` | yes |
+| [`package-shape`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/package-shape/) | Every workspace is named &lt;scope&gt;/&lt;dir&gt;; library packages expose a barrel and point main/module/types/exports at the built output. | `createPackageShapeRule` | `@noctcore/lint-meta-rules` | `config` | yes |
+| [`security-scanner-version-parity`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/security-scanner-version-parity/) | The gitleaks version pinned in the workflows must equal the one in scripts/ci/pre-push.sh, and the hook must compare a native gitleaks against it at run time. | `createSecurityScannerVersionParityRule` | `@noctcore/lint-meta-rules` | `ci` | yes |
+| [`service-image-digest-pin`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/service-image-digest-pin/) | Workflow service and container images, and docker-compose images, must be pinned by `@sha256:` digest (a service that builds locally is exempt). | `createServiceImageDigestPinRule` | `@noctcore/lint-meta-rules` | `ci` | yes |
+| [`test-runner-segregation`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/test-runner-segregation/) | Bun-side packages use 'bun:test'; foreign-side packages use 'vitest'. Never mix runners. | `createTestRunnerSegregationRule` | `@noctcore/lint-meta-rules` | `testing` | yes |
+| [`test-sibling-enforcement`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/test-sibling-enforcement/) | Every source file matched by `include` must have a colocated sibling test. Pure helpers must ship a test. | `createTestSiblingEnforcementRule` | `@noctcore/lint-meta-rules` | `source-text` | yes |
+| [`test-workspace-enrollment`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/test-workspace-enrollment/) | Every candidate package with test files must be enumerated in the root 'test:node' script. | `createTestWorkspaceEnrollmentRule` | `@noctcore/lint-meta-rules` | `testing` | yes |
+| [`ui-primitive-shape`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/ui-primitive-shape/) | A folder primitive under the ui root must ship its proof siblings (test, stories); a flat primitive must not carry sibling proof files at the root. | `createUiPrimitiveShapeRule` | `@noctcore/lint-meta-rules` | `source-text` | yes |
+| [`workspace-graph-parity`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/workspace-graph-parity/) | Imported &lt;scope&gt;/* specifiers must be declared workspace:* deps, and tsconfig references must mirror those deps. | `createWorkspaceGraphParityRule` | `@noctcore/lint-meta-rules` | `config` | yes |
+| [`translation-dead-keys`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/translation-dead-keys/) | Every translation catalog key must be reachable from the source: named by a translation call, or spelled by some string in the code. | `createTranslationDeadKeysRule` | `@noctcore/lint-meta-rules/i18n` | `source-text` | yes |
+| [`prisma-method-surface`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/prisma-method-surface/) | The Prisma reads and writes the rules police partition the generated client's &lt;Model&gt;Delegate method surface exactly, so a Prisma upgrade cannot add an unguarded method. | `createPrismaMethodSurfaceRule` | `@noctcore/lint-meta-rules/prisma` | `config` | yes |
+| [`tenant-model-registry-parity`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/tenant-model-registry-parity/) | Every tenant-bearing Prisma model is scoped by the runtime extension or exempt with a reason, and the tenant lint rules resolve with exactly that registry. | `createTenantModelRegistryParityRule` | `@noctcore/lint-meta-rules/prisma` | `config` | yes |
+| [`eslint-config-no-warn`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/eslint-config-no-warn/) | Every rule in the RESOLVED ESLint config is "error" or "off", never "warn", including severities a spread preset injects. | `createEslintConfigNoWarnRule` | `@noctcore/lint-meta-rules/resolved-config` | `config` | yes |
+| [`session-epoch-captured`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/session-epoch-captured/) | Every call into the sign-in seam must pass the session epoch captured before the credential was read, or a revocation landing during the credential check loses the race. | `createSessionEpochCapturedRule` | `@noctcore/lint-meta-rules/session` | `source-text` | yes |
+| [`session-kind-stamped`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/session-kind-stamped/) | Every call that mints a session must stamp the principal kind onto it, or sit in an allowlisted, provably single-kind flow; a session read without the kind falls back to a default and can silently promote one kind of account into another. | `createSessionKindStampedRule` | `@noctcore/lint-meta-rules/session` | `source-text` | yes |
+| [`session-landing-declared`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/session-landing-declared/) | Every file that opens a door into a session must declare where it leaves the caller, and a door whose landing demands a return shape (the one that carries the principal kind to the client) must have it. | `createSessionLandingDeclaredRule` | `@noctcore/lint-meta-rules/session` | `source-text` | yes |
+| [`session-mint-callers`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/session-mint-callers/) | The method that mints a session may only be called from allowlisted files; a new sign-in entry point must route through the gate in front of it so the gate cannot be bypassed. | `createSessionMintCallersRule` | `@noctcore/lint-meta-rules/session` | `source-text` | yes |
+| [`idempotency-key-parity`](https://noctcore.github.io/eslint-plugins/rules/lint-meta-rules/idempotency-key-parity/) | Procedures carrying the idempotency middleware must have a client caller that sends an idempotency key, or no client caller at all. | `createIdempotencyKeyParityRule` | `@noctcore/lint-meta-rules/trpc` | `source-text` | yes |
+<!-- end generated rules -->
 Every factory is callable with no arguments (all options default), so `createAllRules()` and
 per-factory defaults work out of the box; supply options to retarget a rule at your own repo.
@@ -81,20 +115,12 @@ The main entry never loads ESLint; this one needs the optional peers `eslint` an
 `@typescript-eslint/parser`. Its factories are not part of `RULE_FACTORIES` / `createAllRules()`:
 they are inert until you point them at your catalogs.
-| Factory | Category | What it enforces |
-| --- | --- | --- |
-| [`createTranslationDeadKeysRule`](./docs/rules/translation-dead-keys.md) | source-text | Every catalog key is reachable: named by a translation call, or spelled by some string in the source. |
 ### `@noctcore/lint-meta-rules/resolved-config`
 Checks over the RESOLVED ESLint config. They load ESLint and resolve configs through
 `calculateConfigForFile`, which is async, so they implement the harness's `runAsync`
 (`@noctcore/harness` 0.3.0 or newer) and need the optional peer `eslint`.
-| Factory | Category | What it enforces |
-| --- | --- | --- |
-| [`createEslintConfigNoWarnRule`](./docs/rules/eslint-config-no-warn.md) | config | No rule RESOLVES to `warn`, including a severity a spread preset injects, which the text scan of `no-warn-severity` cannot see. |
 ### `@noctcore/lint-meta-rules/prisma`
 Whole-repo Prisma guardrails that keep `@noctcore/eslint-plugin-prisma`'s inputs honest. They read
@@ -102,31 +128,15 @@ the plugin's method sets, schema parser and registry reconciliation, so the lint
 checks cannot disagree. The registry parity check resolves an ESLint config (async, `runAsync`) and
 needs the optional peer `eslint`. Neither is in `RULE_FACTORIES`: both need the project's paths.
-| Factory | Category | What it enforces |
-| --- | --- | --- |
-| [`createTenantModelRegistryParityRule`](./docs/rules/tenant-model-registry-parity.md) | config | Every tenant-bearing schema model is scoped at runtime or exempt with a reason, and the tenant lint rules resolve with exactly that registry. |
-| [`createPrismaMethodSurfaceRule`](./docs/rules/prisma-method-surface.md) | config | The reads and writes the rules police are exactly the generated client's delegate methods, so a Prisma upgrade cannot add an unguarded one. |
 ### `@noctcore/lint-meta-rules/session`
 Fences around the one seam that turns an authenticated principal into a session. Each rule is inert
 until you name that seam: the method that mints, the gate in front of it, the files allowed to call it,
 the landings a sign-in can end in. None is in `RULE_FACTORIES`. They load nothing beyond the harness
-contract. Ported from a production NestJS app, where each one exists because its bug shipped once.
-| Factory | Category | What it enforces |
-| --- | --- | --- |
-| [`createSessionMintCallersRule`](./docs/rules/session-mint-callers.md) | source-text | The method that mints a session is called only from allowlisted files, so a new sign-in entry point cannot skip the gate in front of it. |
-| [`createSessionKindStampedRule`](./docs/rules/session-kind-stamped.md) | source-text | Every mint stamps the principal kind onto the session, or sits in an allowlisted, provably single-kind flow. |
-| [`createSessionEpochCapturedRule`](./docs/rules/session-epoch-captured.md) | source-text | Every call into the sign-in seam passes the revocation epoch captured before the credential was read. |
-| [`createSessionLandingDeclaredRule`](./docs/rules/session-landing-declared.md) | source-text | Every file that opens a door into a session declares its landing, and a door whose landing demands a return shape has it. |
+contract.
 ### `@noctcore/lint-meta-rules/trpc`
 Cross-tree checks between tRPC routers and the clients that call them. The decorator shape defaults to
 `nestjs-trpc`'s; the rule is inert until you name the middleware and the two trees. Not in
 `RULE_FACTORIES`.
-| Factory | Category | What it enforces |
-| --- | --- | --- |
-| [`createIdempotencyKeyParityRule`](./docs/rules/idempotency-key-parity.md) | source-text | A procedure guarded by an idempotency middleware has a client caller that sends the key, or no client caller at all. |

package/docs/rules/agents-doc-presence.md CHANGED Viewed

@@ -2,6 +2,10 @@
 > An agent-contract doc must exist at the repo root, every surface, and every non-opted-out package.
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createAgentsDocPresenceRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
 ## Why
 An agent editing a boundary should read its guardrails first. Requiring an `AGENTS.md` (or whatever
@@ -17,7 +21,15 @@ Reports a missing doc at:
 - every directory derived from `surfaceGlobs` (all surfaces), and
 - every directory derived from `packageGlobs`, except those in `optOut`.
-## Factory
+## What it does not flag
+- A package directory listed in `optOut`.
+- The repo root when `requireAtRoot` is `false`.
+- Directories that no `surfaceGlobs` or `packageGlobs` entry matches (the defaults look one level deep
+  under `apps/` and `packages/`).
+- The doc's content: an empty or stale file passes, since only its presence is checked.
+## Options
 ```ts
 createAgentsDocPresenceRule(options?: AgentsDocPresenceOptions): IMetaRule
@@ -32,9 +44,6 @@ createAgentsDocPresenceRule(options?: AgentsDocPresenceOptions): IMetaRule
 | `optOut` | `string[]` | `[]` | Package directories exempt from the requirement. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
-De-projected from nightcore, which hardcoded `AGENTS.md`, the root/apps/packages layout and a fixed
-leaf opt-out set.
 ## When not to use it
 If your repo does not adopt an agent-contract doc convention, skip it.

package/docs/rules/canonical-helpers-single-home.md CHANGED Viewed

@@ -2,6 +2,10 @@
 > A helper symbol must not be exported from two different helper homes.
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createCanonicalHelpersSingleHomeRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
 ## Why
 When the same helper name is exported from multiple files, callers import inconsistent copies and the
@@ -15,7 +19,15 @@ extracts top-level exported identifiers (from `export function|const|let|var …
 lists — keyed on the **local** name before any `as`), and flags any name that appears as an export in
 more than one file. Strict, no baseline.
-## Factory
+## What it does not flag
+- A name exported from only one helper home, however many files import it.
+- An `export { x as y }` alias under a new public name: the check keys on the local name `x`.
+- Files outside `include`, and any path containing an `excludeContains` fragment (`/lib/` by default).
+- `export default`, `export class`, `export type` and `export interface` declarations: only
+  `function`, `const`, `let`, `var` declarations and `export { … }` lists are read.
+## Options
 ```ts
 createCanonicalHelpersSingleHomeRule(options?: CanonicalHelpersSingleHomeOptions): IMetaRule
@@ -27,8 +39,6 @@ createCanonicalHelpersSingleHomeRule(options?: CanonicalHelpersSingleHomeOptions
 | `excludeContains` | `string[]` | `['/lib/']` | Drop any matched path containing one of these fragments. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
-De-projected from nightcore, which hardcoded `apps/web/src/**/*.utils.ts` and a `/lib/` exclusion.
 ## When not to use it
 If your project intentionally re-exports the same symbol from several modules (barrels, façades), scope

package/docs/rules/dockerfile-base-image-digest-pin.md CHANGED Viewed

@@ -2,6 +2,10 @@
 > Dockerfile `FROM` base images are pinned by `@sha256:` digest.
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createDockerfileBaseImageDigestPinRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
 ## Why
 `FROM node:22-slim` names whatever the registry serves at build time, so two builds of one commit can
@@ -25,7 +29,16 @@ FROM deps AS build
 FROM scratch
 ```
-## Factory
+## What it does not flag
+- `FROM scratch` and `FROM <earlier stage>` (a name given by a previous `AS`).
+- `FROM ${BASE}` whose `ARG BASE=<default>` before the first `FROM` is digest-pinned.
+- Dockerfiles under any `skipDirs` segment (`node_modules`, `.git`, `dist`, `.turbo`, `coverage`) and
+  files the `dockerfileGlobs` do not match.
+- A `FROM` split with a line continuation (`\`): it is not read. Add a `Containerfile` glob if you use
+  Podman naming.
+## Options
 ```ts
 createDockerfileBaseImageDigestPinRule(options?: DockerfileBaseImageDigestPinOptions): IMetaRule
@@ -37,7 +50,7 @@ createDockerfileBaseImageDigestPinRule(options?: DockerfileBaseImageDigestPinOpt
 | `skipDirs` | `string[]` | `['node_modules', '.git', 'dist', '.turbo', 'coverage']` | A path with any of these segments is skipped. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
-## Limits
+## When not to use it
-A `FROM` split with a line continuation (`\`) is not read. Add a `Containerfile` glob if you use
-Podman naming.
+If your images are built only for local development and you accept whatever a tag serves at build
+time, skip it.

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.