@noctcore/lint-meta-rules 0.1.0 → 0.2.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/lint-meta-rules",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -46,7 +46,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@noctcore/harness": "^0.1.0"
+    "@noctcore/harness": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",