@noctcore/lint-meta-rules 0.1.0 → 0.3.0

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

@@ -0,0 +1,43 @@
+# `dockerfile-base-image-digest-pin`
+
+> Dockerfile `FROM` base images are pinned by `@sha256:` digest.
+
+## Why
+
+`FROM node:22-slim` names whatever the registry serves at build time, so two builds of one commit can
+differ and a moved tag ships a change nobody reviewed. `tag@sha256:<digest>` keeps the tag for readers
+and fixes the bytes.
+
+## What it flags
+
+Every `FROM` whose image has no `@sha256:` digest. Exempt: `FROM scratch` and `FROM <earlier stage>`.
+An image chosen through a build arg (`FROM ${BASE}`) is resolved from its `ARG BASE=<default>` before
+the first `FROM`; one that cannot be resolved is reported, since the text does not show what is
+pulled. Each violation carries the 1-indexed line.
+
+```dockerfile
+# Bad
+FROM node:22-slim AS deps
+
+# Good
+FROM node:22-slim@sha256:<digest> AS deps
+FROM deps AS build
+FROM scratch
+```
+
+## Factory
+
+```ts
+createDockerfileBaseImageDigestPinRule(options?: DockerfileBaseImageDigestPinOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `dockerfileGlobs` | `string[]` | `Dockerfile`, `Dockerfile.*`, `*.Dockerfile` at any depth, dot-directories included | Dockerfiles to scan. |
+| `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
+
+A `FROM` split with a line continuation (`\`) is not read. Add a `Containerfile` glob if you use
+Podman naming.

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

@@ -0,0 +1,42 @@
+# `github-actions-runner-pinned`
+
+> Workflow jobs run on a named runner image, never a `*-latest` label.
+
+## Why
+
+GitHub repoints `ubuntu-latest` (and `macos-latest`, `windows-latest`) to a new OS image on its own
+schedule, so a green workflow can turn red, or quietly change what it tests, with no commit in your
+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.
+
+```yaml
+# Bad
+runs-on: ubuntu-latest
+runs-on: [self-hosted, ubuntu-latest]
+
+# Good
+runs-on: ubuntu-24.04
+runs-on: ${{ matrix.os }}
+```
+
+## Factory
+
+```ts
+createGithubActionsRunnerPinnedRule(options?: GithubActionsRunnerPinnedOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
+| `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
+
+Line-based text, not a YAML parse. A matrix value such as `os: [ubuntu-latest]` that feeds
+`runs-on: ${{ matrix.os }}` is not checked.

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

@@ -0,0 +1,46 @@
+# `github-actions-sha-pinned`
+
+> GitHub Actions `uses:` refs are pinned to a 40-character commit SHA with a `# vN` comment.
+
+## Why
+
+A tag or branch ref is a moving target: whoever controls the action's repository can repoint it, and
+the new code runs with your workflow's token. A full commit SHA cannot move. The trailing `# vN`
+comment keeps the pin readable and is what Dependabot rewrites on a bump, so a bare SHA is rejected
+too.
+
+## What it flags
+
+Every `uses:` line (step-level and job-level reusable workflow calls) in the scanned workflow files:
+
+- a ref whose pin is not a 40-character hex SHA (tags, branches, short SHAs, no `@` at all),
+- 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.
+
+```yaml
+# Bad
+- uses: actions/checkout@v6
+- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+
+# Good
+- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+- uses: ./.github/actions/setup
+```
+
+## Factory
+
+```ts
+createGithubActionsShaPinnedRule(options?: GithubActionsShaPinnedOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Limits
+
+The check is line-based text, not a YAML parse. A `uses:` value split across lines, or built from an
+expression, is not seen.

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

@@ -0,0 +1,61 @@
+# `security-scanner-version-parity`
+
+> CI and the local pre-push hook pin the same secret-scanner version, and the hook checks it at run
+> time.
+
+## Why
+
+Different scanner versions ship different rulesets, so a push can pass the local hook and fail CI (or
+the reverse) with no code difference. Pinning one version on both sides, and having the hook refuse a
+native binary of another version, keeps the two scans the same scan.
+
+## What it flags
+
+With the defaults (gitleaks):
+
+- workflows that pin different `GITLEAKS_VERSION` values,
+- a hook that runs gitleaks when no workflow pins `GITLEAKS_VERSION`, or workflows that pin it when the
+  hook never runs gitleaks,
+- a hook with no `GITLEAKS_VERSION="x.y.z"` declaration, or one that differs from CI,
+- 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:
+  GITLEAKS_VERSION: '8.30.1'
+```
+
+```bash
+# Good: scripts/ci/pre-push.sh
+GITLEAKS_VERSION="8.30.1"
+GITLEAKS_IMAGE="ghcr.io/gitleaks/gitleaks:v${GITLEAKS_VERSION}"
+[ "$(gitleaks version)" = "$GITLEAKS_VERSION" ] || exit 1
+
+# Bad: a drifted pin and no run-time check
+GITLEAKS_VERSION="8.29.0"
+gitleaks git .
+```
+
+## Factory
+
+```ts
+createSecurityScannerVersionParityRule(options?: SecurityScannerVersionParityOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `scanner` | `string` | `'gitleaks'` | The scanner's binary name, as it appears in the hook and its image name. |
+| `versionVariable` | `string` | `'GITLEAKS_VERSION'` | The variable both sides pin the version in (`KEY: x.y.z` in workflows, `KEY=x.y.z` in the hook). |
+| `imageVariable` | `string` | `'GITLEAKS_IMAGE'` | The hook's optional image variable, whose `<scanner>:vX.Y.Z` tag must agree. |
+| `hookFile` | `string` | `'scripts/ci/pre-push.sh'` | The local hook script, repo-relative. |
+| `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Limits
+
+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.

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

@@ -0,0 +1,52 @@
+# `service-image-digest-pin`
+
+> Workflow service/container images and docker-compose images are pinned by `@sha256:` digest.
+
+## Why
+
+A tag (`postgres:17-alpine`) or `latest` names whatever the registry serves today, so a green build
+can change under an unchanged commit, and a local run cannot promise the bytes CI ran.
+`tag@sha256:<digest>` keeps the readable tag and fixes the content.
+
+## 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).
+
+Each violation carries the 1-indexed line.
+
+```yaml
+# Bad
+services:
+  db:
+    image: postgres:17-alpine
+
+# Good
+services:
+  db:
+    image: postgres:17-alpine@sha256:<digest>
+  api:
+    build: .
+    image: app-api:local
+```
+
+## Factory
+
+```ts
+createServiceImageDigestPinRule(options?: ServiceImageDigestPinOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
+| `composeGlobs` | `string[]` | `compose` / `docker-compose` with optional `.x` / `-x` infix, `.yml` / `.yaml`, at any depth including dot-directories | Compose files to scan. |
+| `skipDirs` | `string[]` | `['node_modules', '.git', 'dist', '.turbo', 'coverage']` | A compose path with any of these segments is skipped. |
+| `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
+
+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.

package/docs/rules/translation-dead-keys.md

@@ -0,0 +1,98 @@
+# `translation-dead-keys`
+
+> Every translation catalog key is reachable from the source: named by a translation call, or spelled
+> by some string in the code.
+
+Import it from the `i18n` entry point, which (unlike the main one) loads ESLint:
+
+```ts
+import { createTranslationDeadKeysRule } from '@noctcore/lint-meta-rules/i18n';
+```
+
+## Why
+
+A catalog key nothing uses is still translated, reviewed and shipped in every language. Finding them is
+a whole-program question, so it is not an ESLint rule: a per-file rule never sees every call site
+(editor runs, `--cache`, lint-staged, sharded workers), and keys flow as data (key tables, key-building
+helpers, server-sent codes) that no call-site analysis follows.
+
+This rule resolves call sites with the same visitor and catalog loader as
+`noctcore-contracts/translation-key-exists` (exported by `@noctcore/eslint-plugin-contracts`), so the
+two checks never disagree on which key a call means. It then adds the data routes a per-file rule
+cannot see.
+
+## What counts as reached
+
+A key is reached, and never reported, when ANY of these holds:
+
+- a translation call resolves to it: `t('key')`, `t('ns:key')`, `t('key', { ns })`,
+  `useTranslation('ns', { keyPrefix })`, `<Trans i18nKey>`, a `TFunction<'ns'>` parameter, the
+  `fallbackNamespaces`;
+- a template key's static head is a prefix of it: `` t(`status.${s}`) `` reaches every `status.*`;
+- a `returnObjects` call names one of its ancestors;
+- ANY string literal in the scanned source equals the key, `ns:key`, or its plural/context base
+  (`key` reaches `key_one`, `key_ordinal_few`, `key_male`), in any namespace;
+- ANY template literal or `+` chain in the scanned source can produce it:
+  `` `nav.${id}.label` `` and `'errors.' + code` are patterns, not just call arguments;
+- it matches an `allow` pattern.
+
+And it reports **no dead key at all** when a scanned file cannot be analysed (a parse error), or when
+`sourceGlobs` match nothing: in both cases the rule would otherwise call reached keys dead.
+
+What is left was named by no call and spelled by no string. On a production app with 1,824 keys this
+reported 55, and every one of them had zero references outside the catalogs.
+
+## Blind spots
+
+It is conservative, not complete. It reports a reached key as dead when the key arrives by a route it
+cannot see:
+
+- **Keys that never appear in the scanned source**: server-sent codes, a CMS, another app, JSON
+  config. List them in `allow`, or add the files that spell them to `sourceGlobs`.
+- **A variable key under a `keyPrefix` binding**: `useTranslation('ns', { keyPrefix: 'form' })` then
+  `t(field)` with `field = 'name'` reaches `form.name`, but no string spells `form.name`. (A static key
+  under a `keyPrefix` is resolved correctly.)
+- **Keys built by anything other than `+` or a template literal**: `[a, b].join('.')`,
+  `` `${a}` `` split across variables, `String.prototype.concat`.
+
+It also misses some dead keys, by design: any string that happens to equal a key (in any namespace)
+keeps it alive, and a broad pattern such as `` `${x}.title` `` keeps every `*.title` alive.
+
+## Factory
+
+```ts
+createTranslationDeadKeysRule(options?: TranslationDeadKeysOptions): IMetaRule
+```
+
+Inert until both `catalogs` and `sourceGlobs` are set; there are no built-in paths.
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `catalogs` | `CatalogSource[]` | `[]` | The catalogs to check, in `translation-key-exists`' shape (`{ file, namespace?, keyPath? }`, `{ns}` placeholders allowed). List ONE language: a key is dead or alive regardless of how many languages translate it. |
+| `sourceGlobs` | `string[]` | `[]` | Every file that can reach a key: call sites AND key tables. Include tests if a key used only by a test should count as alive. |
+| `namespaces` | `string[]` | derived | The namespaces to check. Derived from `catalogs`: a `{ns}` file segment is globbed, a trailing `{ns}` keyPath segment lists the object's keys. Required when a `{ns}` sits anywhere else. |
+| `allow` | `string[]` | `[]` | `ns:key` patterns reached from outside the scanned source; `*` matches any run of characters. |
+| `skipDirs` | `string[]` | `['node_modules', '.git', 'dist', '.turbo', 'coverage']` | Source paths with any of these segments are skipped. |
+| `id` | `string` | `'translation-dead-keys'` | Rule id, for running more than one instance. |
+| `ciCritical` | `boolean` | `true` | Whether a dead key fails CI. |
+
+Every resolution option of `translation-key-exists` is accepted and means the same thing:
+`defaultNamespace`, `fallbackNamespaces`, `hooks`, `instances`, `functions`, `typeNames`,
+`transComponents`, `namespaceIdentifiers`, `nsSeparator`, `keySeparator`. Pass them the same values.
+
+```ts
+createTranslationDeadKeysRule({
+  catalogs: [
+    { file: 'apps/web/src/lib/i18n/locales/pl.json', keyPath: '{ns}' },
+    { file: 'apps/web/src/features/{ns}/locales/pl.json' },
+  ],
+  defaultNamespace: 'common',
+  namespaceIdentifiers: { HELP_NS: 'help' },
+  sourceGlobs: ['apps/web/src/**/*.ts', 'apps/web/src/**/*.tsx'],
+});
+```
+
+## Requirements
+
+The `i18n` entry needs the optional peers `eslint` (>= 9) and `@typescript-eslint/parser`. Scanned
+files are parsed as TypeScript with JSX enabled, without type information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/lint-meta-rules",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Portable, parameterized lint-meta rules — whole-repo / cross-file invariants ESLint cannot reach — for the @noctcore/harness lint-meta runner.",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./i18n": {
+      "types": "./dist/i18n.d.ts",
+      "import": "./dist/i18n.js",
+      "require": "./dist/i18n.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -41,15 +46,31 @@
   "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/lint-meta-rules",
   "bugs": "https://github.com/noctcore/eslint-plugins/issues",
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/i18n.ts --format esm,cjs --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },
   "dependencies": {
-    "@noctcore/harness": "^0.1.0"
+    "@noctcore/eslint-plugin-contracts": "^0.5.0",
+    "@noctcore/harness": "^0.3.0",
+    "@typescript-eslint/utils": "^8.61.1"
+  },
+  "peerDependencies": {
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": ">=9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@typescript-eslint/parser": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@typescript-eslint/parser": "^8.61.1",
+    "eslint": "^10.7.0",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0"
   }