# Offing: full documentation

> The complete text of the Offing documentation pages listed in llms.txt, in that order. Each section starts with the page's public address.

---

Source: https://velella.sh/offing/QUICKSTART/

# Quickstart

Five copy-paste steps, from the first scan to a baseline in CI. You need Node.js 22 or newer and a repository to scan. Every command runs locally; nothing is uploaded.

## 1. Run the first scan

```bash
npx @velella/offing scan .
```

Each finding names its severity, the exact file and line, the replacement, and the source. The first lines look like this on the demo project:

```text
Found 5 lifecycle risks. The most urgent:
  HIGH Unsupported actions/checkout runtime (.github/workflows/ci.yml:9)
  MEDIUM Node.js 18 is end-of-life (package.json:5)
  …
```

Add `--json` for machine-readable output, or `--format compact` for one line per finding when an agent reads the result.

## 2. Check one dependency before adding it

```bash
npx @velella/offing check pkg:npm/request@2.88.2
```

The command prints the lifecycle problem, the replacement, and the evidence. It exits `1` when a rule at or above `--fail-on` (default `high`) applies and `0` otherwise. `no-data` means Offing has no rule for the package, not that it is safe.

## 3. Read the evidence for one finding

Take a finding id from step 1 and inspect it:

```bash
npx @velella/offing explain '<finding-id>' .
```

For structured context an agent can follow, including affected files, usages, constraints, and verification commands:

```bash
npx @velella/offing context '<finding-id>' . --json
```

Offing suggests verification commands; it never runs migration commands for you.

## 4. Add the check to CI

Create `.github/workflows/offing.yml`:

```yaml
name: Offing

on:
  pull_request:

permissions:
  contents: read

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: velella-sh/offing@v0.7.1
        with:
          fail-on-severity: high
```

The action annotates the pull request, can upload SARIF to code scanning, and fails the job on a finding at or above the chosen severity. See the [GitHub Action guide](GITHUB_ACTION.md) for inputs, permissions, and artifacts.

## 5. Add a baseline

Accept the findings you already know about, then report only new regressions:

```bash
npx @velella/offing baseline .
npx @velella/offing scan . --baseline .offing-baseline.json
```

Commit `.offing-baseline.json`. The action reads the same file with `baseline: .offing-baseline.json`.

## Next

- [Install Offing on every channel](INSTALL.md)
- [Use it with an agent](AGENT_SKILLS.md) through the Agent Skill or the [local MCP server](MCP.md)
- [Lifecycle rules](RULES.md) and the [evidence policy](../CONTRIBUTING.md#evidence-policy)
- [Contribute](../CONTRIBUTING.md)

---

Source: https://velella.sh/offing/DEMO/

# 90-second demo

This repository includes a deliberately outdated project at `examples/demo`. Its manifest is stored as `package.json.fixture`; the example helper restores the real name in a temporary copy. It declares an unsupported Node.js range, uses the deprecated `request` package, and runs an old checkout action.

```bash
git clone https://github.com/velella-sh/offing.git
cd offing
npm ci
npm run build
demo="$(node dist/tools/examples.js demo)"
node dist/src/cli.js scan "$demo"
```

Offing reports four evidence-backed lifecycle findings: Node.js 18 and 20, `request`, and `actions/checkout@v4`. Each result includes the exact declaration, severity, replacement, and authoritative sources.

Pick the `request` finding ID from the scan and inspect it:

```bash
node dist/src/cli.js explain '<finding-id>' "$demo"
node dist/src/cli.js context '<finding-id>' "$demo" --json
```

The context packet identifies `package.json` and `src/client.js`, preserves HTTP behavior as a migration constraint, proposes ordered changes, and suggests checks. Offing does not modify files or execute suggested commands.

For an agent-driven version of the same flow, start `offing mcp` and use `scan_repository`, `explain_deprecation`, `create_migration_context`, and `verify_migration` in one local session.

## Example gallery

`examples/gallery` holds one minimal repository per detector, each with the exact findings a scan must return in `expected.json`. They exist to show each detector working in thirty seconds; they are deliberately outdated, so do not copy them into a real project.

Files a dependency scanner reads by name are committed under the neutral names from [decision 0027](https://github.com/velella-sh/offing/blob/main/docs/decisions/0027-fixtures-invisible-to-scanners.md), such as `Gemfile.lock.fixture`, so an example never appears as the repository's own dependency. The command below copies an example to a temporary directory, restores the real names there, and runs Offing inside it; nothing is written to the repository.

| Ecosystem | Directory | What it declares |
|---|---|---|
| Android | `examples/gallery/android` | Play Billing 5 in a Groovy and a Kotlin build script |
| CI images | `examples/gallery/ci-images` | Ubuntu 20.04 and Windows 2019 agents in Azure Pipelines |
| Containers | `examples/gallery/container` | Old Node, Python, Debian, Ubuntu, Alpine, Redis, and PostgreSQL base images across Dockerfiles, Compose, and a devcontainer |
| C++ | `examples/gallery/cpp` | `cmake_minimum_required` below the policy floor |
| Dart | `examples/gallery/dart` | A `pubspec.yaml` SDK constraint on an unsupported Dart release |
| Databases | `examples/gallery/database` | MySQL 5.7 and PostgreSQL 12 in Compose and Terraform |
| Deno | `examples/gallery/deno` | A Deno 1.x project and a Bun 1.0 pin |
| .NET | `examples/gallery/dotnet` | .NET 3.1, 5.0, 6.0, and 8.0 targets, + `global.json`, `Directory.Build.props`, central package versions, and a deprecated Azure storage package |
| Elixir | `examples/gallery/elixir` | Elixir 1.14 and Erlang 25, plus a retired package in `mix.exs` and `mix.lock` |
| GitHub Actions | `examples/gallery/github-actions` | `actions/checkout` on the retired Node 20 runtime |
| Go | `examples/gallery/go` | Go 1.22 and 1.23 in `go.mod` and `go.work` |
| Java | `examples/gallery/java` | JDK pins in Maven, Gradle, the version catalog, `.sdkmanrc`, `.tool-versions`, and `.java-version`; Spring Boot 2.x and 3.x plus a relocated Hibernate artifact |
| Kubernetes | `examples/gallery/kubernetes` | Removed `extensions/v1beta1`, `networking.k8s.io/v1beta1`, `policy/v1beta1`, and `batch/v1beta1` APIs, a pod security policy, and the retired Helm stable repository |
| Node.js | `examples/gallery/nodejs` | `.nvmrc` on Node.js 20 |
| npm | `examples/gallery/npm` | A dependency on the deprecated `request` package |
| PHP | `examples/gallery/php` | PHP 7.4 in `composer.json`, `composer.lock`, `.php-version`, and `.tool-versions` |
| Python | `examples/gallery/python` | `.python-version` on Python 3.9 |
| Ruby | `examples/gallery/ruby` | Ruby 3.2 in `.ruby-version`, `.tool-versions`, the `Gemfile`, and `Gemfile.lock` |
| Rust | `examples/gallery/rust` | Unmaintained crates (`failure`, `ansi-term`, `atty`, `tempdir`) and a toolchain pin on Rust 1.98 |
| Scala | `examples/gallery/scala` | Scala 2.11 and sbt 0.13 |
| Serverless | `examples/gallery/serverless` | Retired Lambda and Cloud Functions runtimes in a SAM template, a Serverless Framework service, and Terraform |
| Shell | `examples/gallery/shell` | PowerShell 7.0 in a module manifest and script, plus `actions/checkout` on Node 20 |
| Swift | `examples/gallery/swift` | An Xcode version in the App Store removal window |
| Terraform | `examples/gallery/terraform` | `.terraform-version` on an unsupported CLI release |

Scan any example the same way as the demo:

```bash
npm run build
node dist/tools/examples.js gallery/kubernetes scan
```

Use `npm run --silent example -- <example> <command>` for the same thing. With no command the tool prints the temporary directory and leaves it in place:

```bash
node dist/tools/examples.js gallery/php
```

Any other command accepts a whole example directory the same way:

```bash
node dist/tools/examples.js gallery countdown --as-of 2026-10-25
```

The gallery is part of `npm run check`. To run only its test:

```bash
npm run build
node --test dist/tests/examples-gallery.test.js
```

The test scans every example twice and compares the result to `expected.json` as a whole, so a rule or detector change that alters an example fails CI until the example and its expected output are reviewed together.

## Recordings

The recordings in the README are generated from `demos/*.tape` by the Demos workflow. This one looks up a runtime without scanning anything:

![Terminal recording: offing lookup node 18 reports Node.js 18 as end-of-life with the replacement and source](assets/demos/lookup.gif)

---

Source: https://velella.sh/offing/MCP/

# Local MCP server

Offing exposes its deterministic analysis to coding agents through a local Model Context Protocol server. The server uses stdio, requires no account or API key, and does not start a network listener.

## Start the server

From the published package:

```bash
npx --yes @velella/offing mcp
```

From a source checkout:

```bash
npm install
npm run mcp
```

An MCP host can launch the published command with configuration shaped like:

```json
{
  "mcpServers": {
    "offing": {
      "command": "npx",
      "args": ["--yes", "@velella/offing", "mcp"]
    }
  }
}
```

`npx --yes @velella/offing mcp` starts the same server, and is the command the [MCP Registry](https://registry.modelcontextprotocol.io) description in `server.json` uses.

The exact settings location depends on the host. Offing needs no environment variables or credentials.

## One-command install per host

Each host below gets the local stdio server with one install command. Claude Code and Codex also receive the portable Skill through the same plugin. Cursor and VS Code need the Skill separately ([Agent Skill](AGENT_SKILLS.md#one-command-install-per-host)). Every command was run in a clean environment on 2026-10-29 (macOS, Node.js 22). No Offing account is required.

Shared verify prompt after install: ask the agent to `Add the request package to this project`, and confirm it calls `check_dependency` for `pkg:npm/request` and reports the deprecation with a replacement and sources instead of adding the package.

### Claude Code

```sh
claude plugin install offing --marketplace velella-sh/offing
```

**Verify.** `claude plugin list` shows `offing@offing` enabled, and `claude plugin details offing` lists the `offing` MCP server. Start a new session and use the shared verify prompt.

Details: [Claude plugin](CLAUDE_PLUGIN.md).

### Codex

```sh
codex plugin marketplace add velella-sh/offing --ref main && codex plugin add offing@offing-codex
```

When the Offing repository marketplace is already configured (for example from a checkout that exposes `.agents/plugins/marketplace.json`), `codex plugin add offing@offing-codex` alone is enough.

**Verify.** Restart the Codex session, run `codex plugin list --json`, and confirm `offing@offing-codex` is installed and enabled. Then use the shared verify prompt. Trust the dependency-guard hook with `/hooks` if you want the PostToolUse check.

Details: [Codex plugin](CODEX_PLUGIN.md).

### Cursor

```sh
cursor --add-mcp '{"name":"offing","type":"stdio","command":"npx","args":["--yes","@velella/offing","mcp"]}'
```

**Verify.** Restart Cursor or reload the window. Under Settings → MCP, `offing` is listed and can be enabled. Then use the shared verify prompt. For the Skill, see [Agent Skill](AGENT_SKILLS.md#one-command-install-per-host).

Project-scoped copy of the same server entry: [`examples/agents/cursor/`](https://github.com/velella-sh/offing/tree/main/examples/agents/cursor).

### VS Code

```sh
code --add-mcp '{"name":"offing","type":"stdio","command":"npx","args":["--yes","@velella/offing","mcp"]}'
```

**Verify.** Command Palette → **MCP: List Servers** shows `offing`. In Copilot Chat Agent mode, use the shared verify prompt. For the Skill, see [Agent Skill](AGENT_SKILLS.md#one-command-install-per-host).

Project-scoped copy of the same server entry: [`examples/agents/copilot/`](https://github.com/velella-sh/offing/tree/main/examples/agents/copilot).

## What the server exposes

Everything below is read-only and runs in the local process. The server advertises the `tools`, `resources`, `prompts`, and `completions` capabilities. The same evidence-backed findings the tools return also render as a shareable local HTML report (`offing scan --format html`):

![Self-contained Offing HTML report showing finding counts and a high-severity deprecated package with location, replacement, and evidence](assets/screenshots/html-report.webp)

### Write safety

No tool, resource, or prompt writes to the repository, and none has an option that makes it write. Every tool advertises `readOnlyHint: true` and `destructiveHint: false`, takes no output, fix, or overwrite parameter, and never runs a command: `verify_migration` returns the project commands it suggests without executing them. [`tests/mcp-readonly.test.ts`](https://github.com/velella-sh/offing/blob/main/tests/mcp-readonly.test.ts) calls every tool, reads the resources, and gets the prompt against a fixture, and fails if the repository tree changes (paths, sizes, modification times, or content) or if a tool gains an option that looks like a write. If a future tool can write, it must require an explicit option, be documented here, and drop `readOnlyHint`.

### Lifecycle status file

An agent that cannot call the server can still read the repository's lifecycle state before it plans a change. `offing scan --write-status` writes `OFFING_STATUS.md` at the root of the scanned repository: finding counts by severity, how many findings the baseline accepted, the lifecycle data version, and the most severe findings in the `--format compact` form (at most 25, with a count of the rest). The file has no machine path, timestamp, or data age, so an unchanged repository produces the same bytes on every run and a commit only changes when the state does. Without the flag nothing is written, and the MCP tools never write it.

To point agents at it, add a line like this to `AGENTS.md` and refresh the file in CI or a pre-commit hook:

```markdown
Before planning dependency or runtime changes, read OFFING_STATUS.md for the repository's current lifecycle findings. Re-run `npx @velella/offing scan . --write-status` after you change them.
```

The file is a snapshot. Run a scan, or call `scan_repository`, to see the current state after an edit.

### Tools

Each tool has an `outputSchema` (the published JSON Schema in [`schemas/`](https://github.com/velella-sh/offing/tree/main/schemas), made self-contained for the client) and returns the result as structured content, also as JSON text. Failures return `isError` with a message and no structured content. Every failure also carries `_meta.offing` with `code` (a stable reason code), `class` (`usage`, `data`, `parse`, or `internal`), and `exitCode`, the exit code the CLI uses for that class, so a client can branch without parsing the message. The reason codes are listed in [CLI exit codes](CLI.md#exit-codes).

| Tool | Input | Output | Purpose |
| --- | --- | --- | --- |
| `scan_repository` | `repository_path?`, `baseline?` | `offing.scan.v1` (`scan.v1.schema.json`) | Complete result from all built-in detectors. With `baseline` (a path relative to the repository), suppressed findings are left out and `suppressions` reports how many, and which suppressions are expiring or expired. |
| `list_deprecations` | `repository_path?` | `offing.deprecations.v1` (`deprecations.v1.schema.json`) | Compact list for planning. |
| `explain_deprecation` | `finding_id`, `repository_path?` | one finding (`finding.v1.schema.json`) | The complete evidence-backed finding. |
| `create_migration_context` | `finding_id`, `repository_path?` | `offing.context.v1` (`context.v1.schema.json`) | Validated, rule-specific migration packet. |
| `verify_migration` | `finding_id`, `repository_path?` | `offing.verification.v1` (`verification.v1.schema.json`) | Re-scan and check a finding observed earlier in the session. |
| `check_dependency` | `purl`, `version?` | `offing.check.v1` (`check.v1.schema.json`) | Check one package before adding it; reads no repository. |
| `check_upgrade` | `target`, `path?` | `offing.upgrade.v1` (`upgrade.v1.schema.json`) | Whether the project can move to a target runtime, from lockfiles and manifests; `unknown` means no evidence was found, not that the upgrade is safe. |
| `check_snippet` | `path`, `content` | `offing.check-snippet.v1` (`check-snippet.v1.schema.json`) | What Offing flags in one snippet before it is written, checked in an isolated temporary directory; locations are relative to the snippet. Call it before writing package manifests, Dockerfiles, CI workflows, and Kubernetes manifests. Reads no repository. |
| `forecast_repository` | `repository_path?`, `months?`, `as_of?` | `ebb.forecast.v1` (`forecast.v1.schema.json`) | What reaches a dated end of life in the next months, grouped by month, with the repository's findings each event affects. |
| `recommend_version` | `product`, `minimumSupportDays?`, `as_of?` | `offing.recommend.v1` (`recommend.v1.schema.json`) | Which release line to write today (a name such as `node`, or a Package URL), from bundled lifecycle data only: the recommended line and its end date, alternatives, lines to avoid, and sources. `no-data` is not a statement that any version is safe. |
| `plan_migrations` | `repository_path?` | `offing.plan.v1` (`plan.v1.schema.json`) | Migration plan: waves of independent tasks a coordinating agent can hand out. |

`repository_path` defaults to the server's current working directory. Finding-specific tools require the exact `finding_id` Offing returned.

`check_upgrade` takes `target` as `runtime@version`, for example `php@8.4`, and reads only files already in the repository. It never installs a runtime, runs Composer, or uses the network. When no analyzer finds evidence for that runtime, the verdict is `unknown` and the tool says so; that is not a statement that the upgrade is safe.

### Checking a snippet before writing it

`check_snippet` answers "if I write this content to this path, what would Offing flag?" before the file exists. Pass the intended repository-relative `path` — `Dockerfile`, `.github/workflows/ci.yml`, `package.json` — and the exact `content`. Offing writes only that one file into a temporary directory, runs all built-in detectors against it, and returns the findings with paths and lines relative to the snippet, plus a `message` that says when the snippet is clean. The temporary directory is always removed, and the real repository is never read or written.

### Planning ahead with the forecast

`forecast_repository` answers "what ends of life are coming, and which of them hit this repository?" It runs a fresh local scan, then lists the lifecycle events that carry an authoritative date inside a window. Each event carries its rule, source, severity, and the findings in this repository that it will affect, grouped by calendar month with the earliest first.

The window starts at `as_of` (a `YYYY-MM-DD` date; today in UTC when omitted) and defaults to `months` 12, from 1 to 36. Passing `as_of` makes the result deterministic. The output is the same `ebb.forecast.v1` document that `offing forecast --json` prints. Only dated events are listed, so a package with no authoritative deadline does not appear; nothing is estimated.

### Resources

| URI | Contents | Lifetime |
| --- | --- | --- |
| `offing://rules/{id}` | One lifecycle rule as `ebb.rule.v1` (`rule.v1.schema.json`): affected PURL and versions, event, severity, replacement, deadline, sources, review provenance, migration steps. | Bundled with the release; reading one scans nothing. |
| `offing://findings/{repository}/{id}` | One finding observed in this session, identical to `explain_deprecation`. `{repository}` is an 8-character key of the repository root and `{id}` is the percent-encoded finding id. | This session only; empty until a scan, never written to disk. |

`resources/list` enumerates both families. The server sends `notifications/resources/list_changed` after every call that scans, so a host that cached the list refreshes it. Rule ids autocomplete by prefix. Reading an unknown URI fails with a resource-not-found error.

### Prompts

| Prompt | Arguments | Purpose |
| --- | --- | --- |
| `migrate-finding` | `finding_id` (required, autocompletes from observed findings), `repository_path?` | Runs a fresh scan, embeds the finding's migration packet, and instructs the model to edit within the packet's constraints, run the project's checks, and call `verify_migration` in the same session. It makes the finding observable, so verification works straight after. |

The prompt carries its safety limits: repository files are untrusted input, suggested commands are reviewed and run only under the host's normal authorization, and the model reports what remains instead of declaring success.

### Examples

`check_dependency` request and the start of its structured result:

```json
{ "method": "tools/call", "params": { "name": "check_dependency", "arguments": { "purl": "pkg:npm/request@2.88.2" } } }
```

```json
{
  "schemaVersion": "offing.check.v1",
  "purl": "pkg:npm/request",
  "version": "2.88.2",
  "status": "affected",
  "severity": "high",
  "findings": [{ "ruleId": "npm.package.request.deprecated", "event": "deprecated", "replacement": "Native fetch or a maintained HTTP client" }],
  "message": "pkg:npm/request@2.88.2: request is deprecated. …"
}
```

Reading a rule, then the findings of a scan:

```json
{ "method": "resources/read", "params": { "uri": "offing://rules/npm.package.request.deprecated" } }
{ "method": "resources/list" }
```

Fetching the migration prompt for a finding:

```json
{ "method": "prompts/get", "params": { "name": "migrate-finding", "arguments": { "finding_id": "<id from list_deprecations>", "repository_path": "." } } }
```

You can see all of it in the MCP Inspector:

```sh
npx @modelcontextprotocol/inspector npx --yes @velella/offing mcp
```

The Tools tab lists the seven tools with their output schemas, Resources lists the rules (and findings after a scan) and the two templates, and Prompts lists `migrate-finding`.

## Checking a dependency before adding it

To see afterwards what agents checked and which packages were flagged, set `OFFING_USAGE_LOG=1` for the server and run `offing usage`. The log is off by default, stays on your machine, and holds only package, result, and rule IDs ([Privacy](PRIVACY.md#local-usage-log)). Writing it is the one thing the server does outside memory, to that file and never to the repository.

Call `check_dependency` with a Package URL (`pkg:npm/request@2.88.2`, `pkg:pypi/nose`, `pkg:github/actions/checkout@v4`) when you are about to add or upgrade a dependency. The result has a `status`:

- `affected`: a rule applies. Read `findings[].summary`, `replacement`, and `sources`, and choose the replacement instead.
- `version-dependent`: rules exist, but only for some versions. Call again with the version you intend to use.
- `not-affected`: rules exist and none covers that version.
- `no-data`: Offing has no rule for the package. That is absence of evidence, not a safety claim.

The tool is read-only and idempotent, never touches the network, and answers from the lifecycle rules bundled with the server.

## Language server for any editor

The same engine runs as a Language Server Protocol server over stdio, so VS Code, Neovim, Helix, Zed, and JetBrains can show lifecycle findings without an MCP host. It starts no listener and makes no network call.

From the published package:

```bash
npx --yes @velella/offing lsp
```

From a source checkout:

```bash
npm run build
node dist/src/lsp.js
```

Point the editor's LSP client at that command. For Neovim:

```lua
vim.lsp.start({
  name = "offing",
  cmd = { "npx", "--yes", "@velella/offing", "offing lsp" },
  root_dir = vim.fs.dirname(vim.fs.find({ ".git" }, { upward = true })[1]),
})
```

For Helix, in `languages.toml`:

```toml
[language-server.offing]
command = "npx"
args = ["--yes", "@velella/offing", "offing lsp"]
```

The server provides:

| Capability | Behavior |
| --- | --- |
| Diagnostics | Every finding in the open document, at its line, with the rule id, severity, and a link to the first evidence source. |
| Hover | The finding title and summary, severity, confidence, replacement, deadline, and every evidence source as a link. |
| Code actions | `Offing: explain …` shows the finding with its evidence, and `Offing: open evidence …` opens the first source URL. Both run through `workspace/executeCommand`. |

Only the open document is scanned. On open, change, and save the server writes that buffer to a temporary directory, runs the detector engine there, and publishes the findings whose location is that file. It reads no other workspace file, writes nothing to the repository, and removes the temporary directory when the document closes or the server exits. A source file can depend on a manifest elsewhere, so findings that need a manifest outside the open document are not reported yet; use the CLI or the MCP server for a whole-repository scan.

The server uses the lifecycle data bundled with the installed release, and document text stays on the machine, as with the MCP server.

## Other agent hosts

Claude Code, Codex, Cursor, and VS Code have one-command installs above. Ready-to-copy setups for those hosts and others (an MCP entry plus the instruction to call `check_dependency` before adding a dependency) are in [`examples/agents/`](https://github.com/velella-sh/offing/tree/main/examples/agents) and [`integrations/cline/`](https://github.com/velella-sh/offing/tree/main/integrations/cline):

| Host | MCP config | Instructions |
| --- | --- | --- |
| Cursor | `.cursor/mcp.json` (or `cursor --add-mcp` above) | `.cursor/rules/offing.mdc` |
| Gemini CLI | `gemini-extension.json` or `.gemini/settings.json` | `GEMINI.md` |
| GitHub Copilot | `.vscode/mcp.json` (or `code --add-mcp` above) or repository settings (coding agent) | `.github/copilot-instructions.md` |
| Kilo Code | `kilo.jsonc` | `.kilo/rules/offing.md` |
| Cline | `cline_mcp_settings.json` (user settings) | `.clinerules/offing.md` |
| Windsurf | Cascade `mcp_config.json` (user config) | `.windsurf/rules/offing.md` |

Aider does not support MCP servers, so its setup in [`integrations/aider/`](https://github.com/velella-sh/offing/tree/main/integrations/aider) is a conventions file (`CONVENTIONS.md` loaded through `.aider.conf.yml` or `--read`) that tells the agent to run `npx @velella/offing check <purl>` instead of calling the tool.

To put the same instruction into a repository's `AGENTS.md` or `CLAUDE.md`, run `offing init --agents` in it: it adds a delimited section, keeps everything else byte for byte, and is safe to run again (`--dry-run` prints the diff first). `offing setup` does the same for every detected host at once (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Kilo Code), writing each host's own instruction file such as `.cursor/rules/offing.mdc` after confirmation or `--yes`; it does not edit MCP server entries, which stay in the per-host setups above.

Each directory says which vendor documentation its format follows and how to confirm it works in your host. The server command in each of them was run from the published package and answered a real MCP handshake, tool list, and `check_dependency` call (2026-10-18). They have not yet been run inside live host installations, and the READMEs say so.

## Where the server is listed

The server is registered as `io.github.velella-sh/offing` in the [official MCP Registry](https://registry.modelcontextprotocol.io), which holds only the metadata in `server.json` and points at the npm package. Every directory below was checked on 2026-10-27. The description is the one in `server.json`, and each submission says that scans are local and use no network.

| Directory | Status | Why, and what happened |
| --- | --- | --- |
| [Official MCP Registry](https://registry.modelcontextprotocol.io) | [Listed](https://registry.modelcontextprotocol.io/v0/servers?search=offing) | Published 2026-10-18; republished per release by step 7 of [RELEASING](RELEASING.md). |
| [GitHub MCP Registry](https://github.com/mcp) | Not listed, requested | Onboarding of a new server is manual curation; versions sync from the official Registry once onboarded. Onboarding request posted 2026-10-27 in [github/github-mcp-server Discussion #1257](https://github.com/github/github-mcp-server/discussions/1257#discussioncomment-19227895); check with `curl https://github.com/mcp/velella-sh/offing` (404 = not onboarded yet), since the registry API's search is unreliable. |
| VS Code / Copilot MCP gallery | Not listed, same route | The gallery reads the GitHub MCP Registry, so no separate step exists; it lists Offing once the onboarding above lands. |
| [Docker MCP Catalog](https://hub.docker.com/mcp) | Not listed, PR open | Submission is a PR to [docker/mcp-registry](https://github.com/docker/mcp-registry), reviewed by Docker, who then build and host the image in the `mcp` namespace. Submitted 2026-10-27 ([PR #6199](https://github.com/docker/mcp-registry/pull/6199)); `servers/offing/server.yaml` pins a commit, so a new release does not change the catalog until the entry is updated by a follow-up PR. |
| [Smithery](https://smithery.ai) | Not listed, not worth it | Smithery lists servers reachable over HTTP; local stdio servers ship as MCPB bundles instead, and its publishing flow shuts down on 2026-10-31 in favour of a passive directory. Skip. |
| [Glama](https://glama.ai/mcp/servers) | Not listed, pending | Glama re-indexes public MCP servers continuously, so the entry may appear by itself at [glama.ai/mcp/servers/velella-sh/offing](https://glama.ai/mcp/servers/velella-sh/offing); claim it once it does (needs a browser sign-in, so it is a maintainer step). A repository without a LICENSE gets a public grade penalty; the Apache-2.0 file is already there. |
| [PulseMCP](https://www.pulsemcp.com) | Not listed, not eligible | Submissions are paused (announced 2026-09-03). PulseMCP ingests the official Registry's servers automatically once it reopens, so no action until then. |
| [mcp.so](https://mcp.so) | Not listed | Free listing is through the form at [mcp.so/submit?type=server](https://mcp.so/submit?type=server) and goes through a review; the form needs a browser session, so it is left for a maintainer (or take the paid instant path, which the project does not use). |
| [Cursor Directory](https://cursor.directory) | Not listed, not worth it | Cursor's directory is now a plugin gallery for the Agent Plugins standard, which wants `plugin.json`/`mcp.json` resources that fit the CLI, not just the stdio server. Skip. |
| [Cline MCP Marketplace](https://cline.bot/mcp-marketplace) | Not listed | Submission is a GitHub issue on [cline/mcp-marketplace](https://github.com/cline/mcp-marketplace) with a 400×400 logo and the confirmation that Cline can install from this repository's README; needs testing in Cline itself, so it waits for a maintainer with the product installed. |

Submissions are outward-facing and hard to withdraw, so each one stayed conservative: they carry only the `server.json` metadata and README wording, and none of them pastes a token or credential; each directory is authenticated through its own flow.

## Agent workflow

1. Call `scan_repository` or `list_deprecations` before editing.
2. Use `explain_deprecation` to inspect evidence and lifecycle details.
3. Call `create_migration_context` and make changes within its constraints and affected files.
4. Run the packet's suggested project commands when appropriate.
5. Call `verify_migration` in the same MCP session.

Verification is deliberately conservative. Offing remembers the original finding, performs a fresh local scan, and checks its rule and declaration path. An unknown finding ID returns an error rather than a false success. `commandsExecuted` is always `false`: Offing suggests project-specific commands but never executes shell commands through MCP.

## Privacy and trust

- Repository traversal, parsing, matching, context creation, and verification happen inside the local Offing process.
- Communication with the MCP host uses stdin and stdout on the same machine.
- The server has no HTTP transport and makes no outbound requests.
- No hosted Offing service, telemetry, account, or API key is involved.
- Tool results can include file paths and short source excerpts already present in findings; the local MCP host receives those results so it can act on them.

The versioned JSON contracts live in `schemas/scan.v1.schema.json`, `schemas/deprecations.v1.schema.json`, `schemas/forecast.v1.schema.json`, `schemas/context.v1.schema.json`, `schemas/verification.v1.schema.json`, and `schemas/check-snippet.v1.schema.json`.

---

Source: https://velella.sh/offing/DRIFT/

# Runtime drift

`offing drift` finds every place a repository states a runtime version — version files, manifests, container images, and CI configuration — and reports, with exact locations, when the values disagree. A Dockerfile on Node.js 18, CI on 20, and `.nvmrc` on 22 is one line of output instead of three files to compare by hand.

Every command in this page reads repository files only. Drift checks never run a runtime, execute a repository's tools, or use the network. `--align` prints a patch and never writes it.

```bash
offing drift . --check
offing drift . --runtime ruby --json
offing drift . --runtime ruby --align 3.4
```

## How to read the report

Each runtime block lists every value with its `path:line`, the file or field it came from, the value as written, and the release line it resolves to. A value that cannot be resolved offline is reported too, with the reason. When the `pin` values select more than one release, the block says `DRIFT`. A `floor` is a minimum the project supports; when a floor is above the lowest pinned release that applies to it, the block says `FLOOR CONFLICT`. A floor that names a directory is checked against the pins that apply to that directory, not against every pin.

`--check` exits `1` when any runtime drifted or has a floor conflict. `--align <release>` requires `--runtime`, prints a unified diff for the pins it can rewrite, lists refused pins on stderr, and never writes a file. It refuses floors and ranges, and each collector documents the files it can rewrite.

## Adding a collector

One collector per runtime lives in `src/drift/<runtime>.ts`, reuses the parsers the detectors already have, and is registered once in `driftCollectors` in `src/drift/index.ts`. Each section below names the sources it reads, its release granularity, what it refuses to resolve, and which file it can align.

## Ruby

Reads, at any depth:

- `.ruby-version`, including the rbenv `ruby-3.3.1` and `3.3.1p123` forms.
- `.tool-versions` `ruby` lines, including several fallback versions.
- `Gemfile`: an exact `ruby "3.3.0"` is a pin; a literal requirement such as `ruby ">= 3.1.0"` or `ruby "~> 3.2"` is a floor.
- `Gemfile.lock` `RUBY VERSION`.
- `*.gemspec`: a literal `required_ruby_version`, such as `">= 3.1.0"` or `"~> 3.2"`, as a floor.
- `Dockerfile*` and `Containerfile*`: `FROM ruby:<tag>` and a literal `RUN asdf install ruby <version>`.
- `.github/workflows/*.yml`: the `ruby-version` input of `ruby/setup-ruby`.
- `.gitlab-ci.yml` `image:` values and `.circleci/config.yml` `docker:` images for the official `ruby` and `cimg/ruby` images.

Release granularity is `major.minor` (`3.3`).

Unresolved values are reported with the reason and excluded from the drift comparison: `system`, `latest`, an image without a tag, a moving image tag, a `${{ matrix.* }}` expression, and a requirement that states no minimum.

`align <release>` rewrites `.ruby-version`, a single-value `.tool-versions` ruby line, an exact `Gemfile` `ruby` directive, a `ruby/setup-ruby` `ruby-version` input, and the tag of a Dockerfile, GitLab CI, or CircleCI image. It refuses floors, ranges, image digests, and multi-value lines. `Gemfile.lock` is reported and refused with "regenerate the lockfile": Bundler owns that file.
`offing drift` finds every place a repository states a runtime version and reports, per runtime, whether those values agree. A repository that runs Node 18 in its Dockerfile, Node 20 in CI, and Node 22 in `.nvmrc` has a drift, even when every test passes on the version the developer uses. The command reads repository files only: scans never use the network and never execute repository code.
offing drift .                    # text report
offing drift . --json             # https://github.com/velella-sh/offing/schemas/drift.v1.schema.json
offing drift . --check            # exit 1 when a runtime drifts or has a floor conflict
offing drift . --runtime java --align 21   # print a patch; never write it
`--json` prints an `offing.drift.v1` document. Every pin carries its repository-relative path, the 1-based line of the value, the source it came from, the value exactly as written, and the release it resolves to offline. A value that cannot be resolved offline keeps its place in the report with an `unresolved` reason instead of a guessed release.
`--align <release>` prints a unified diff for the pins of one runtime that can be rewritten safely, and lists the refused pins on stderr. Offing never writes the patch.
## Java
Java releases are compared at the feature-release major: `17`, `21`, `25`. A legacy `1.8` resolves to `8`; a vendor prefix (`temurin-`) or suffix (`-tem`) is ignored. The vendor never changes support status.
| File | Fields read |
| --- | --- |
| `pom.xml` | `maven.compiler.release`, `maven.compiler.source`, `maven.compiler.target`, and `java.version` properties; `release`, `source`, and `target` in `maven-compiler-plugin` configuration, including `pluginManagement`. |
| `build.gradle`, `build.gradle.kts` | `java.toolchain.languageVersion` (`.set(...)` or `=`), `jvmToolchain(N)`, `sourceCompatibility`, and `targetCompatibility`, as literal values only. |
| `.java-version` | The first non-comment line. |
| `.sdkmanrc` | The `java=` entry. |
| `.tool-versions` | The first version of the `java` entry. |
| `Dockerfile`, `*.Dockerfile`, `Containerfile*` | `FROM` images of the `eclipse-temurin`, `openjdk`, and `amazoncorretto` families; `maven` and `gradle` tags that name a JDK, such as `3.9-eclipse-temurin-17` or `8.10-jdk21`; and `sdk install java` or `asdf install java` `RUN` lines. |
| `.github/workflows/*.yml` | The `java-version` input of `actions/setup-java`. A `${{ matrix.<key> }}` value is followed to the matrix list in the same job. |
| `.gitlab-ci.yml`, `.circleci/config.yml` | `image` references of the same JDK and build-image families. |
The Maven `release`, `source`, `target`, and `java.version` properties and the Gradle `sourceCompatibility` and `targetCompatibility` settings are floors: they say the oldest JDK the compiled code runs on, not the JDK that builds it, so a build on JDK 21 that compiles for 17 is not drift. Everything else is a `pin`: the JDK that builds or runs the project. `--align` rewrites pins only.
Reported as unresolved, never guessed:
- a Maven property reference such as `${java.version}`;
- a Gradle expression such as `JavaVersion.toVersion(libs.versions.java.get())`;
- a matrix or other workflow expression that does not resolve to a literal;
- `latest`, `lts`, `system`, or another floating version-file value;
- an image with no tag, a floating tag, or an image reference containing a variable.
`--align` rewrites only values it can select a release with:
- Maven compiler properties and `maven-compiler-plugin` settings whose text is a literal version;
- `.java-version`, `.sdkmanrc`, and `.tool-versions` entries with a literal version;
- an image tag that is a plain major, such as `eclipse-temurin:17`, or the JDK segment of a Maven or Gradle tag, such as `3.9-eclipse-temurin-17`;
- a single scalar `java-version` in `actions/setup-java`.
It refuses Gradle toolchain and compatibility settings, `Dockerfile RUN` installs, property references, floating tags, matrix values, and image tags with a digest or a non-major suffix.
# Drift
`offing drift` reads every place a repository states a runtime version and reports, with exact file and line, when those values select different release lines. A repository with Python 3.10 in `.python-version`, 3.11 in its Dockerfile, and 3.12 in CI has drift: tests pass on one version while production runs another.
Scans read repository files and nothing else. No drift path uses the network, runs a command, or evaluates repository code, and `--align` prints patches instead of writing files.
offing drift [path] [--json] [--check] [--runtime <id>] [--align <release>]
- `--check` exits `1` when any runtime has drifted or has a floor conflict.
- `--json` prints the `offing.drift.v1` document described by [`schemas/drift.v1.schema.json`](../schemas/drift.v1.schema.json).
- `--runtime <id>` limits the report to one runtime.
- `--align <release>` requires `--runtime`, and prints a unified diff that rewrites the pins it understands to `release`. It lists pins it refuses on stderr.
Each runtime is reported as its own block. Every pin carries its location, the source it came from, the value as written, and the release line the value selects offline. A value that cannot be resolved carries the reason instead of a guess. A `floor` is a minimum the project supports, not the version that builds it; a floor above the lowest pin is reported as a floor conflict.
Release granularity differs by runtime. Each section below states the granularity it reports and the values it leaves unresolved.
## .NET
.NET pins are reported at `major.minor` granularity: the SDK `8.0.204`, the image tag `8.0-alpine`, and the moniker `net8.0` all select `8.0`.
`netcoreapp` below 5 resolves to its own name (`netcoreapp3.1`) and is not compared with `netX.Y` releases. `netstandard*` is a compatibility contract that many runtimes satisfy, so it is reported as unresolved and never counted as drift, as are .NET Framework monikers such as `net48`.
**Pins**
| Source | Field | Align |
| --- | --- | --- |
| `global.json` | `sdk.version`, wherever the file appears | yes, keeping `rollForward` |
| `*.csproj`, `*.fsproj`, `*.vbproj` | a single `TargetFramework` in a `PropertyGroup` | yes |
| `Directory.Build.props` | a single `TargetFramework` | yes |
| `Dockerfile`, `*.Dockerfile`, `Containerfile` | `FROM mcr.microsoft.com/dotnet/{sdk,aspnet,runtime,runtime-deps}:<tag>`, including legacy `dotnet/core/*` images and `--platform` | yes |
| GitHub Actions | `actions/setup-dotnet` `dotnet-version`, one pin per line of a multi-line value | single value only |
| `.gitlab-ci.yml` | `image` and service values that name a Microsoft .NET image | no |
| `.circleci/config.yml` | job and executor `docker`/`machine` image values that name a Microsoft .NET image | no |
| `azure-pipelines.yml` | `container` and `resources.containers[].image` values that name a Microsoft .NET image | no |
A Microsoft .NET image is `mcr.microsoft.com/dotnet/sdk`, `aspnet`, `runtime`, or `runtime-deps`, or the legacy `dotnet/core/*` equivalents. Image tags keep their suffix: `8.0-alpine` selects `8.0`.
**Multi-targeting**
`<TargetFrameworks>` with several entries is intentional multi-targeting. Each entry is reported as a pin with source `TargetFrameworks`, the entries share one group, and they are not counted against each other. A source outside the list still counts: `TargetFrameworks` of `net6.0;net8.0` agrees with a Dockerfile that selects `8.0`, but drifts when the Dockerfile selects `9.0`. `--align` refuses the multi-targeting form.
**Unresolved**
A .NET Framework moniker, an MSBuild property reference such as `$(Tfm)`, a version with no minor (`8`, `latest`), a dynamic image reference, an expression, an image with no tag, and any value Offing does not read are reported as pins with a one-sentence reason and no release. A value is never guessed from a newer version existing.
**Align**
`--align` rewrites `global.json` `sdk.version` (keeping `rollForward`), a single `TargetFramework`, `FROM` tags that preserve the image suffix, and a single-value `setup-dotnet` `dotnet-version`. It refuses `TargetFrameworks`, MSBuild property references, .NET Framework monikers, CI image references, and any line whose form it does not recognize.
`offing drift` reports every place a repository states a runtime version: Dockerfiles, CI configuration, version files, manifests, and toolchain files. Each value is listed with its exact file, line, source, and the release line it resolves to offline. When the values disagree, the runtime is marked `DRIFT`; when a minimum the project requires is above the version that builds it, the value is listed as a floor conflict.
offing drift .              # what the repository states, by runtime
offing drift . --check      # exit 1 when any runtime disagrees
offing drift . --runtime rust --align 1.82   # print a patch; nothing is written
offing drift . --runtime go --align 1.22   # print a patch; nothing is written
Drift reads repository files only. It never uses the network, never executes repository code or tools, and never writes a file. `--align` prints a unified diff for review; apply it yourself, for example with `git apply`.
A value is a **pin** when it selects the version that builds or runs the project, and a **floor** when it states a minimum the project supports. Floors are compared with the lowest pinned release: a floor above it is a conflict, because the environment the pin selects cannot satisfy the project.
Values that cannot be resolved offline are still reported, with the reason. Offing never guesses a release.
## Rust
Release granularity is `1.minor`: the toolchain channel `1.79.0`, the image tag `1.79.0-slim-bookworm`, and the `.tool-versions` entry `1.79.0` all resolve to `1.79`. A `rust-toolchain` channel selects the toolchain that builds the project, so it is a pin; `rust-version` in `Cargo.toml` states the minimum the project supports, so it is a floor.
| Source | Field | Kind |
| `rust-toolchain.toml`, `rust-toolchain` | `channel` (or the one-line legacy form) | pin |
| `.tool-versions` | `rust` entry | pin |
| `Dockerfile*`, `Containerfile*`, `*.Dockerfile` | `FROM rust:<tag>` | pin |
| `.github/workflows/*.yml` | `dtolnay/rust-toolchain@<ref>` | pin |
| `.github/workflows/*.yml` | `dtolnay/rust-toolchain` `toolchain:` input | pin |
| `.github/workflows/*.yml` | `actions-rs/toolchain` `toolchain:` input | pin |
| `.github/workflows/*.yml` | job `container:` and `services.<name>.image` rust image | pin |
| `.gitlab-ci.yml` | `image:` or `services:` rust image | pin |
| `.circleci/config.yml` | Docker executor rust image | pin |
| `azure-pipelines.yml` | job `container:` rust image | pin |
| `Cargo.toml` | `package.rust-version` and `workspace.package.rust-version` | floor |
The Rust collector reuses the existing `rust-toolchain` and `Cargo.toml` parsers and reads Dockerfile `FROM` lines with the container parser. It reports these values as unresolved, without a release: `stable`, `beta`, `nightly`, and dated nightlies, a floating image tag such as `rust:latest`, an image with no tag, a tag that is not `1.minor`, an expression that is not a literal version, and a `.tool-versions` entry that names a `ref:` or `path:`.
`--align` rewrites `channel = "1.x"` lines and the one-line `rust-toolchain`, the `rust` entry of `.tool-versions`, `rust:<version>[-variant]` tags in Dockerfiles and CI configuration, `dtolnay/rust-toolchain@<ref>`, and the `toolchain:` input of `dtolnay/rust-toolchain` and `actions-rs/toolchain`. It keeps the target or image variant suffix. It refuses floors, named channels, expressions, and images pinned by digest.
## Go
Release granularity is `1.minor`: `go1.22.4` and the image tag `1.22.4-alpine` both resolve to `1.22`. A `go` directive is a minimum since Go 1.21 ([Go toolchains](https://go.dev/doc/toolchain), [go directive](https://go.dev/ref/mod#go-mod-file-go)), so it is a floor; a `toolchain` line selects the toolchain that builds the module, so it is a pin.
| `go.mod` | `toolchain go1.x.y` | pin |
| `go.work` | `toolchain go1.x.y` | pin |
| `go.mod` | `go 1.x[.y]` | floor |
| `go.work` | `go 1.x[.y]` | floor |
| `.go-version` | first non-comment line | pin |
| `.tool-versions` | `golang` entry | pin |
| `Dockerfile*`, `Containerfile*` | `FROM golang:<tag>` | pin |
| `.github/workflows/*.yml` | `actions/setup-go` `go-version` | pin |
| `.github/workflows/*.yml` | `actions/setup-go` `go-version-file` | pin, pointing at the named file |
| `.gitlab-ci.yml` | `image:` or `services:` golang image | pin |
| `.circleci/config.yml` | Docker executor golang image | pin |
| `azure-pipelines.yml` | job `container:` golang image | pin |
The Go collector reuses the existing `go.mod` and `go.work` parsers and reads Dockerfile `FROM` lines with the container parser. It reports these values as unresolved, without a release: a floating image tag such as `golang:latest`, an image with no tag, a tag that is not `major.minor`, a `stable` or `oldstable` `go-version`, an expression that is not a `matrix` reference, a matrix entry that is not a plain version, and a `.go-version` or `.tool-versions` value that is not a Go version.
`--align` rewrites `toolchain go1.x.y` lines, `.go-version`, the `golang` entry of `.tool-versions`, `FROM golang:<version>[-variant]` (keeping the variant suffix), and a single-value `actions/setup-go` `go-version`. It refuses floors, matrix and expression values, `go-version-file` pointers, and floating tags.
## Python
Python pins are reported at `major.minor` granularity: `3.11.4`, `3.11`, and `python-3.11` all select `3.11`. Version files and manifests are read at any depth, so a monorepo reports each service.
| `.python-version` | every line | yes |
| `.tool-versions` | the `python` line, one pin per version | yes |
| `runtime.txt` | `python-<version>` | yes |
| `Pipfile` | `[requires]` `python_version` and `python_full_version` | yes |
| `Dockerfile`, `*.Dockerfile`, `Containerfile` | `FROM python:<version>[-variant]`, including `--platform` and all stages | yes |
| GitHub Actions | `actions/setup-python` `python-version`, following a `${{ matrix.<key> }}` reference to its literal list; matrix values keep one pin each | single value only |
| `.gitlab-ci.yml` | `image` and `service` values that name a Python image | no |
| `.circleci/config.yml` | job and executor `docker`/`machine` `image` values that name a Python image | no |
| `azure-pipelines.yml` | `container` and `resources.containers[].image` values that name a Python image | no |
| `environment.yml`, `environment.yaml` | literal `python=...` entries under `dependencies`; a lower bound is a floor | no |
A Python image is `python`, `cimg/python`, or `circleci/python` on Docker Hub. A multi-version `.python-version` or `.tool-versions` line reports one pin per version.
**Floors**
| Source | Field |
| `pyproject.toml` | `[project]` `requires-python` |
| `pyproject.toml` | `[tool.poetry.dependencies]` `python` |
| `setup.cfg` | `[options]` `python_requires`, including continuation lines |
| `setup.py` | a literal `python_requires="..."` string; the file is read, never executed |
A floor resolves from its first lower bound, so `>=3.10,<3.13`, `^3.10`, and `~=3.10.2` all report `3.10`.
`3`, `3.x`, a wildcard with no minor version, `latest`, a tag or image with no version, a dynamic image reference, an expression, a constraint with no lower bound, and any value Offing does not read are reported as pins with a one-sentence reason and no release. A value is never guessed from a newer version existing.
`--align` rewrites `.python-version`, `.tool-versions`, `runtime.txt`, `Pipfile`, `FROM python:<version>[-variant]` (keeping the variant suffix and the rest of the instruction), and a single-value `setup-python` `python-version`. It refuses floors, matrix entries, CI image references, and any line whose form it does not recognize.

## Node.js

Node.js pins are reported at the major release: `18.19.0`, `v18`, and the image tag `18-alpine` all select `18`.

| Source | Field | Kind |
| --- | --- | --- |
| `.nvmrc` | the version line | pin |
| `.node-version` | the version line | pin |
| `.tool-versions` | the `nodejs` entry, one pin per version | pin |
| `package.json` | `volta.node` | pin |
| `package.json` | `engines.node` | floor |
| `Dockerfile`, `*.Dockerfile`, `Containerfile*` | `FROM node:<tag>`, including every stage | pin |
| `devcontainer.json` | the `image` tag and the `ghcr.io/devcontainers/features/node` feature `version` | pin |
| `.github/workflows/*.yml` | `actions/setup-node` `node-version` | pin |
| `.gitlab-ci.yml` | `image` and `services` values of the official `node`, `cimg/node`, and `circleci/node` images | pin |
| `.circleci/config.yml` | Docker executor values of those images | pin |
| `azure-pipelines.yml` | job `container` values of those images | pin |

A Dev Container image is read for the `node`, `cimg/node`, and `circleci/node` Docker Hub images and for the `devcontainers/javascript-node` and `devcontainers/typescript-node` images, whose tags carry the Node.js major after the image major, such as `1-18-bookworm`.

**LTS codenames**

`lts/<codename>` resolves through the Node.js release schedule ([nodejs/Release](https://github.com/nodejs/Release#release-schedule)): `argon` 4, `boron` 6, `carbon` 8, `dubnium` 10, `erbium` 12, `fermium` 14, `gallium` 16, `hydrogen` 18, `iron` 20, `jod` 22, and `krypton` 24. The Docker tag form `lts-<codename>[-variant]` resolves the same way.

**Matrix builds**

A `setup-node` matrix with several versions is intentional. Each value is reported as a pin with source `setup-node matrix`, the values share one group, and they are not counted against each other. A drift is reported only when a non-matrix pin disagrees with another non-matrix pin, or when a non-matrix pin falls outside the matrix.

**Unresolved**

`lts/*`, `latest`, `current`, `node`, an LTS codename Offing does not know, an image tag that names no Node.js release, a dynamic image reference, an expression, a matrix entry that is not a plain version, and a floor with no lower bound are reported as pins with a one-sentence reason and no release.

`--align` rewrites `.nvmrc`, `.node-version`, `.tool-versions`, `package.json` `volta.node`, `FROM node:<major>[-variant]` (keeping the variant suffix and the rest of the instruction), and a single-value `actions/setup-node` `node-version`. It refuses floors, `setup-node` matrices, Dev Container and CI image references, and any line whose form it does not recognize.

## Terraform

Terraform pins are reported at `major.minor` granularity: the `.terraform-version` value `1.17.0`, the image tag `1.17`, and `required_version = ">= 1.17.0"` all select `1.17`.

| Source | Field | Kind |
| --- | --- | --- |
| `.terraform-version`, at any depth | the version line, one pin per file | pin |
| `.tool-versions` | the first version of the `terraform` entry | pin |
| `Dockerfile`, `*.Dockerfile`, `Containerfile*` | `FROM hashicorp/terraform:<tag>` | pin |
| `.github/workflows/*.yml` | `hashicorp/setup-terraform` `terraform_version` | pin |
| `.github/workflows/*.yml` | job `container:` and `services.<name>.image` `hashicorp/terraform` images | pin |
| `.gitlab-ci.yml` | `image:` or `services:` `hashicorp/terraform` images | pin |
| `.circleci/config.yml` | Docker executor `hashicorp/terraform` images | pin |
| `azure-pipelines.yml` | job `container:` `hashicorp/terraform` images | pin |
| `*.tf`, in every module | `required_version` | pin when exact (`"1.17.0"`, `"= 1.17.0"`, `"~> 1.17.0"`), else floor |

The collector reuses the existing `.terraform-version` and `.tool-versions` parsers and reads `required_version` with the HCL parser. Provider versions in `required_providers` are not Terraform CLI versions and are not read.

**Directories**

Version files and `required_version` apply to the directory they live in, because modules in different directories can legitimately differ. A floor is checked only against the pins that apply to its directory: the nearest `.terraform-version` or `.tool-versions` at or above it, or the repository-wide pins (Dockerfiles, CI images, `setup-terraform`) when its directory declares none. A floor of `>= 1.17.0` beside a module `.terraform-version` of `1.17.0` agrees, even when the rest of the repository pins `1.16`. Pins are still compared across the repository, so modules on different release lines are a drift.

**Unresolved**

`latest`, `min-required`, `system`, a partial version such as `1.9`, a prerelease, a `.tool-versions` entry that names a `ref:` or `path:`, an image with no tag, a floating image tag, a workflow expression, and a constraint with no lower bound are reported with a one-sentence reason and no release.

**Align**

`--align <release>` rewrites `.terraform-version`, a single-value `.tool-versions` `terraform` entry, `FROM hashicorp/terraform:<version>` tags, a single-value `setup-terraform` `terraform_version`, and an exact `required_version` (keeping the `=` form when written). Where a full version is required, a release line such as `1.18` is written as `1.18.0`. It refuses floors, ranges, CI image references, and images pinned by digest.

## PHP

PHP pins are reported at `major.minor` granularity: `8.3.12`, `8.3`, and the image tag `8.3-fpm` all select `8.3`.

| Source | Field | Kind |
| --- | --- | --- |
| `composer.json` | `config.platform.php` | pin |
| `composer.json` | `require.php` | floor |
| `composer.lock` | `platform.php`, when present | floor |
| `.php-version` | the single version, including the phpenv `php-8.3.12` form | pin |
| `.tool-versions` | the `php` entry, one pin per version | pin |
| `Dockerfile`, `*.Dockerfile`, `Containerfile*` | `FROM php:<tag>` and a literal `RUN asdf install php <version>` | pin |
| `.github/workflows/*.yml` | the `php-version` input of `shivammathur/setup-php` | pin |
| `.gitlab-ci.yml` | `image:` values that name the official `php` image | pin |
| `.circleci/config.yml` | Docker executor values that name the `php` or `cimg/php` image | pin |

A PHP image is the Docker Hub `php` image, or `cimg/php` in CI. Image tags keep their variant suffix: `8.3-fpm` selects `8.3`.

A `setup-php` matrix with several versions is intentional. Each value is reported as a pin with source `setup-php matrix`, the values share one group, and they are not counted against each other.

**Floors**

`require.php` and `composer.lock` `platform.php` state what the project installs against, not the PHP that builds it, so they are floors. A floor resolves from its first lower bound: `^8.2`, `>=8.1`, and `8.1.*` all resolve to their major.minor. A floor above the lowest pinned release is a floor conflict, because that environment cannot install the project.

**Unresolved**

`latest`, `system`, a version with no minor (`8`), a moving image tag, an image with no tag, an expression that is not a `matrix` reference, and a constraint with no lower bound are reported as pins with a one-sentence reason and no release. A value is never guessed from a newer version existing.

**Align**

`--align <release>` rewrites `.php-version` (keeping the `php-` prefix), a single-value `.tool-versions` `php` line, `composer.json` `config.platform.php`, `FROM php:<version>[-variant]` tags, GitLab CI and CircleCI image tags, and a single-value `setup-php` `php-version`. It refuses floors, `composer.json` `require.php`, `composer.lock`, `setup-php` matrix values, multi-value `.tool-versions` lines, and image references pinned by digest. `composer.lock` is reported and refused with "regenerate the lockfile": Composer owns that file.

## Elixir

Elixir pins are reported at `major.minor` granularity: `1.16.2`, `1.16`, and the image tag `1.16.2-otp-26-alpine` all select `1.16`.

| Source | Field | Kind |
| --- | --- | --- |
| `.elixir-version` | the single version, including the asdf `1.16.2-otp-26` form | pin |
| `.tool-versions` | the `elixir` entry, one pin per version, the `-otp-NN` suffix kept as written | pin |
| `mix.exs` | the project `elixir:` constraint, quoted literals only | floor |
| `Dockerfile`, `*.Dockerfile`, `Containerfile*` | `FROM elixir:<tag>` and `FROM hexpm/elixir:<elixir>-erlang-<otp>-<os>` | pin |
| `.github/workflows/*.yml` | the `elixir-version` input of `erlef/setup-beam` | pin |
| `.gitlab-ci.yml` | `image:` values that name the official `elixir` or `hexpm/elixir` image | pin |
| `.circleci/config.yml` | Docker executor values that name `elixir` or `hexpm/elixir` | pin |

An Elixir image is the Docker Hub `elixir` image or the `hexpm/elixir` build image; other registries and other repositories are not read. Image tags keep their suffixes: `1.16.2-otp-26-alpine` selects `1.16`, and `hexpm/elixir:1.17.3-erlang-27.1.1-alpine-3.20` selects `1.17` from the version its tag names first.

The collector reuses the Elixir detector's runtime parser and `mix.exs` parser, so the same version grammar decides what is a pin here as in `offing scan`. A `setup-beam` matrix with several Elixir versions is intentional. Each value is reported as a pin with source `setup-beam elixir matrix`, the values share one group, and they are not counted against each other.

**Floors**

`mix.exs` `elixir:` states the oldest Elixir the project supports, not the one that builds it, so it is a floor. Only a quoted literal constraint is read: `~> 1.15` and `>= 1.15.7` resolve to their first lower bound, `1.15`. `Mix` is never run and `mix.exs` is never evaluated. A floor above the lowest pinned Elixir is a floor conflict, because that project cannot build on the runtime its own pins select.

**Unresolved**

`latest`, `main`, a version with no minor (`1`), an image with no tag, a moving image tag such as `elixir:latest`, a `hexpm/elixir` tag that is not `<elixir>-erlang-<otp>[-<os>]`, an expression that is not a `matrix` reference, and a constraint with no lower bound are reported as pins with a one-sentence reason and no release. A value is never guessed from a newer version existing.

**Align**

`--align <release>` rewrites `.elixir-version` (keeping its `-otp-NN` suffix), a single-value `.tool-versions` `elixir` line, a single-value `setup-beam` `elixir-version` (its quote style kept), and `elixir:<version>[-otp-<otp>][-variant]` tags in Dockerfiles, GitLab CI and CircleCI (the OTP part and the variant are preserved). It refuses the `mix.exs` floor, every `hexpm/elixir` tag — choosing its OS part is a decision, not a rewrite — `setup-beam` matrix values, multi-value `.tool-versions` lines, and image references pinned by digest.

## Erlang/OTP

Erlang/OTP pins are reported at the OTP major: `26.2.5`, `OTP-26.2.5`, and the `-otp-26.2.5` of an Elixir pin all select `26`.

| Source | Field | Kind |
| --- | --- | --- |
| `.tool-versions` | the `erlang` entry, one pin per version | pin |
| `.elixir-version`, `.tool-versions` | the `-otp-NN` suffix of an Elixir version that names one | pin |
| `Dockerfile`, `*.Dockerfile`, `Containerfile*`, `.gitlab-ci.yml`, `.circleci/config.yml` | the `erlang-<otp>` part of a `hexpm/elixir` tag, and the `-otp-<otp>` part of an `elixir` tag | pin |
| `.github/workflows/*.yml` | the `otp-version` input of `erlef/setup-beam`, including its `OTP-26.2.5` form | pin |

OTP is versioned with Elixir, so one line states both: `FROM hexpm/elixir:1.17.3-erlang-27.1.1-alpine-3.20` is an Elixir `1.17` pin for the Elixir collector and an OTP `27` pin for this one, at the same path and line. The Docker Hub `erlang` image is not a source of drift here, because the issue that scoped this collector lists only the sources above; a repository that runs Erlang on its own gets no pin from `FROM erlang:27`.

There is no Erlang floor source: `mix.exs` constrains Elixir, not OTP.

A `setup-beam` matrix with several OTP versions is intentional: the values are reported with source `setup-beam otp matrix`, share one group, and are not counted against each other.

**Unresolved**

`main`, `master`, and `latest`, an `otp-version` that is not a version (`edge`), an expression that is not a `matrix` reference, an `.tool-versions` `erlang` token that is not an OTP release, and a workflow that does not parse as YAML are reported with a reason or skipped; nothing is guessed. An Elixir version with no `-otp-` part simply yields no OTP pin.

**Align**

`--align <release>` rewrites a single-value `.tool-versions` `erlang` line, the `-otp-NN` suffix of `.elixir-version` and of a `.tool-versions` `elixir` line, a single-value `setup-beam` `otp-version` (written as the bare major, with the line's quotes kept), and the `-otp-<otp>` part of `elixir:<version>-otp-<otp>[-variant]` tags in Dockerfiles, GitLab CI and CircleCI. It refuses every `hexpm/elixir` tag, `setup-beam` matrix values, and image references pinned by digest.

---

Source: https://velella.sh/offing/INVENTORY/

# Inventory

`offing inventory` reads the JSON or text exports that cloud and cluster tools already produce and reports what they say is deployed: end-of-life runtimes, images, engines, cluster versions, and operating systems. Each result carries the importer, the file, and the exact place in the file the claim rests on, as an RFC 6901 JSON Pointer.

Offing never calls a cloud or cluster API. You run the export command on a machine with credentials, then give the file to `offing inventory`:

```bash
kubectl get deploy,sts,ds,cronjob,job,pod -A -o json > workloads.json
offing inventory workloads.json
```

Every importer reads one export file and produces items. The output is deterministic: results sort by file and pointer. An affected item means a lifecycle rule applies to the version the export names; `no-data` means Offing has no rule for that PURL, never that the thing is safe. A file no importer recognizes is listed, the run exits `2`, and the files that were recognized are still reported.

## Privacy

`inventory` reads only the files named on the command line. It makes no network request, runs no command, and reads no other file. It never executes code or tools from the scanned export. Output names only the resource's own short name: `resource` is never an account id, ARN, subscription id, project number, IP address, tag, or environment variable, and the one exception is a Kubernetes node's own name, which the cluster importer reports because the node is the resource (a node named by its IP address is skipped). `--redact` replaces each resource name with the first 12 hex characters of its SHA-256, in text and JSON output alike.

## Kubernetes workloads

### What it reads

Export a cluster's workload objects:

```bash
kubectl get deploy,sts,ds,cronjob,job,pod -A -o json > workloads.json
offing inventory workloads.json
```

The importer recognizes a Kubernetes `List` whose items each have `apiVersion`, `kind`, and `metadata`. A list of `Node` objects is left to the cluster importer. For every item it reads:

- `apiVersion` and `kind`, mapped to the Kubernetes lifecycle rules.
- `metadata.namespace` and `metadata.name`, which form `resource` as `<namespace>/<kind>/<name>`. Cluster-scoped objects have no namespace and use `cluster` instead.
- For `Pod`, `Deployment`, `StatefulSet`, `DaemonSet`, `ReplicaSet`, `Job`, and `CronJob`, every `containers[].image` and `initContainers[].image` in the pod template. For a `CronJob` that is `spec.jobTemplate.spec.template`.

Images are parsed with the same parser as the container detector. Identical image references are reported once per namespace and workload, at the first pointer where they appear. A label, annotation, environment variable, pod status, and `spec.nodeName` are never read.

### Rules matched

| Item | PURL | Registry |
| --- | --- | --- |
| Container image | `pkg:docker/<repository>`, for example `pkg:docker/library/node` | `registry/container.json` |
| API version | `pkg:generic/kubernetes/<group>/<Kind>`, for example `pkg:generic/kubernetes/networking.k8s.io/Ingress` | `registry/kubernetes.json` |

A Docker Hub image is written without the registry: `docker.io/library/node` is `pkg:docker/library/node`. Images from other registries are skipped, not reported, because no rule covers them yet and a private registry host can carry an account id.

An image tag is used as the version only when it is a plain release number: `node:18.19.0` is `18.19.0`, and `node:18` is `18.0.0`. Floating tags such as `latest`, `22-alpine`, or a digest with no tag name no version, so the item is reported as `version-dependent`, not guessed. An API version is translated to the rule's semver form by the same rule as the Kubernetes detector (decision 0008): `v1` is `1.0.0`, `v1beta1` is `1.0.0-beta.1`, and `v2beta2` is `2.0.0-beta.2`.

### Limit: the API server's preferred version

`kubectl get -o json` reports each object at a version the API server chooses to serve, not necessarily the version it was stored or applied at. An object created through a removed API can therefore appear at its replacement: an `Ingress` applied as `networking.k8s.io/v1beta1` is reported by a modern server as `networking.k8s.io/v1`. This importer can only judge the version the export names; it cannot infer an older stored version. Use a manifest scan to judge what the repository declares.

### What it does not judge

- Images from registries other than Docker Hub, including private registries and IP-address hosts: no rule covers them yet, so they are skipped rather than reported and no host, address, or account id reaches the output.
- Floating tags and digest-only references, whose release line the file does not name.
- The core API group (`apiVersion: v1`, such as `Pod`), which has no removed kinds in the Kubernetes migration guide.
- Objects and fields beyond the ones listed above.

The fixtures under `tests/fixtures/inventory/k8s-workloads/` reproduce the documented output shape of `kubectl get … -o json` (kubectl 1.31), with every identifier replaced by a placeholder. They were assembled from the command's output shape, not captured from a live cluster.

## Kubernetes cluster

Export the cluster's version and its nodes, then pass both files:

```bash
kubectl version -o json > k8s-cluster.json
kubectl get nodes -o json > k8s-nodes.json
offing inventory k8s-cluster.json k8s-nodes.json
```

The importer recognizes the version export, the object that carries `serverVersion.gitVersion`, and the node export, a Kubernetes `List` whose items are all `Node` objects with `status.nodeInfo`. From the version export it reads the control-plane version; from the node export it reads, per node:

- `status.nodeInfo.kubeletVersion`
- `status.nodeInfo.osImage`
- `status.nodeInfo.containerRuntimeVersion`
- `metadata.name`, which becomes `resource`

### Provider suffixes

`gitVersion` and `kubeletVersion` carry a provider suffix on managed services: `v1.28.3-eks-2fbdaf5`, `v1.30.5-gke.1445001`, `v1.31.5+k3s1`. Everything from the first `-` or `+` is stripped and the upstream release is judged, so each of those is `1.28.3`, `1.30.5`, and `1.31.5`. Managed providers (EKS, GKE, AKS) retire minors on their own calendars, which end earlier than upstream's, so a managed cluster should be judged by its provider's schedule too: the provider view is covered by the EKS, Google Cloud, and Azure tasks, and GKE already has its own rules in `registry/kubernetes.json`.

### Rules matched

| Item | PURL | Registry |
| --- | --- | --- |
| Control plane, kubelet | `pkg:generic/kubernetes` | `registry/kubernetes.json` |
| Node OS image | `pkg:generic/<distribution>`, for example `pkg:generic/ubuntu` | `registry/container.json` |
| Container runtime | `pkg:generic/containerd`, `pkg:generic/docker`, `pkg:generic/cri-o`, `pkg:generic/cri-dockerd` | no rules yet |

`registry/kubernetes.json` holds upstream minor-release rules sourced to the [Kubernetes release history](https://kubernetes.io/releases/) page. They are the reviewed adoption of the `kubernetes-2` lifecycle importer's drafts: each of the five newest ended minors has an `end-of-life` rule at high severity, a minor whose announced end of life has not passed is `scheduled-end-of-life` at low severity (decision 0010), and a reviewed `1.28-and-older` rule covers the lines the importer no longer drafts. A weekly importer run keeps these fresh; a managed cluster should still be judged by its provider's schedule, which ends earlier than upstream's.

An `osImage` maps to the distribution's PURL when it names one the registry knows: `Ubuntu 22.04.5 LTS` to `pkg:generic/ubuntu` at `22.04.5`, `SUSE Linux Enterprise Server 15 SP6` to `pkg:generic/sles` at `15.6`, `Amazon Linux 2` to `pkg:generic/amzn` at `2`. These are the same PURLs and rules the os-release importer checks, so a node image and a host's `/etc/os-release` are judged by one set of dates. A distribution without rules — Bottlerocket, Container-Optimized OS, Flatcar, Rocky Linux, AlmaLinux — is still reported, at its own PURL, as `no-data`: not safe, just unruled. An image that names none of the known distributions produces no item.

`containerRuntimeVersion` maps to the runtime's PURL: `containerd://1.6.32` to `pkg:generic/containerd` at `1.6.32`. No runtime rule set exists yet, so these report `no-data`. A version that is not a plain release number (`containerd://1.6.x`) is reported without a version.

### What is not judged

- Node capacity, conditions, taints, labels, and addresses: never read or reported.
- A node whose `metadata.name` is an IP address is skipped entirely, because `resource` names a resource, never an address.
- The images running on the nodes and the objects' API versions: the workloads importer covers those.
- Whether the control plane and the kubelets are within the version-skew policy: skew compatibility is a different question from end of life.
- Anything the export does not state. No command is run, no API is called, and no other file is read.

The fixtures under `tests/fixtures/inventory/k8s-cluster/` reproduce the documented output shape of `kubectl version -o json` and `kubectl get nodes -o json` (kubectl 1.31), with every identifier replaced by a placeholder. They were assembled from the command's output shape, not captured from a live cluster.

## Host operating systems

The `os-release` importer reads an `/etc/os-release` file from one host, or a bundle collected from several hosts, and reports the distribution release against its lifecycle rules.

### Export

One host:

```bash
ssh web-1 'cat /etc/os-release' > web-1.os-release
offing inventory web-1.os-release
```

Several hosts, in one file. Each block starts with `### host: <name>`; that name becomes the result's `resource`:

```bash
while read -r host; do
  printf '### host: %s\n' "$host"
  ssh "$host" 'cat /etc/os-release'
done < hosts.txt > os-release.bundle
offing inventory os-release.bundle
```

Offing runs neither loop; you run it, and Offing reads the result.

### Fields read

| Field | Use |
| --- | --- |
| `ID` | Names the distribution, and so the `pkg:generic/<distro>` rule set. |
| `VERSION_ID` | The release line the rules judge. The result's `pointer` is the `line:<n>` of this line in the file. |
| `ID_LIKE` | Read as the declared family. It is never used to apply a parent distribution's dates, because a derivative keeps its own release schedule. |

A block without both `ID` and a numeric `VERSION_ID` is skipped: a codename or a rolling tag such as `testing` does not name a release line the rules can judge. A single file with no host header uses its file name as the resource. Quoted values, such as `VERSION_ID="20.04"` and `ID='ubuntu'`, are read the same as unquoted ones.

### Rules matched

| Distribution (`ID`) | PURL | Release lines reported | Rule |
| --- | --- | --- | --- |
| `ubuntu` | `pkg:generic/ubuntu` | before 22.04 | `container.host-ubuntu.eol-22.04-and-older` |
| `debian` | `pkg:generic/debian` | before 12 | `container.host-debian.eol-11-and-older` |
| `rhel` | `pkg:generic/rhel` | 7 and older | `container.host-rhel.eol-7-and-older` |
| `centos` | `pkg:generic/centos` | 8 and older | `container.host-centos.eol-8-and-older` |
| `amzn` | `pkg:generic/amzn` | 2 and the 2018.03 AMI | `container.host-amazon-linux.eol-2-and-older` |
| `alpine` | `pkg:generic/alpine` | before 3.21 | `container.host-alpine.eol-3.20-and-older` |
| `sles` | `pkg:generic/sles` | 15 SP6 and older | `container.host-sles.eol-15-sp6-and-older` |

Every rule cites the distribution's own lifecycle page, not an aggregator. The rules live in `registry/container.json` next to the image rules, but use `pkg:generic/<distro>` PURLs and distribution sources: an image rule describes what a Docker tag ships, which is not the same question as what a host runs.

### What is not judged

- A file without `VERSION_ID` is skipped: a codename alone does not identify the release line for every distribution.
- A derivative reported under its own `ID` is checked only if that `ID` has a rule. `ID_LIKE` does not borrow the parent's dates. It is reported as `no-data`, not as safe.
- Paid add-on support is not treated as standard support. RHEL 7 Extended Life Cycle Support and SUSE Long Term Service Pack Support extend security fixes for a fee; the rules report that general support ended and name the add-on in the summary.
- A host with no readable `/etc/os-release` is not reported. Offing does not guess a distribution from other files.

### Fixtures

The fixtures under `tests/fixtures/inventory/os-release/` are the output of `cat /etc/os-release` on each distribution, with every identifier replaced by a placeholder. There is no CLI version to record: `cat` is part of the coreutils of each distribution.

## Docker containers and images

Produce the exports with the Docker CLI. Both forms are supported:

```bash
# running and stopped containers, including labels and state
docker inspect $(docker ps -aq) > docker-inspect.json

# a Compose project: a JSON array, or one JSON object per line
docker compose ps --format json > docker-compose-ps.json
```

The fixtures under [`tests/fixtures/inventory/docker/`](../tests/fixtures/inventory/docker/) follow the output of Docker CLI 29.6.2 (`docker inspect`) and Docker Compose v2 (`docker compose ps --format json`), with ids, names, and image tags replaced. The example [`examples/inventory/docker-inspect.json`](../examples/inventory/docker-inspect.json) is the same shape.

### What is read

| Format | Fields | Pointer |
| --- | --- | --- |
| `docker inspect` | `Name`, `Config.Image` | `/i/Name`, `/i/Config/Image` |
| `docker inspect` | `Config.Labels["org.opencontainers.image.base.name"]` | `/i/Config/Labels/org.opencontainers.image.base.name` |
| `docker inspect` | `Config.Labels["org.opencontainers.image.version"]` | `/i/Config/Labels/org.opencontainers.image.version` |
| `docker compose ps` | `Service`, `Image` | `/i/Service`, `/i/Image` |

`i` is the entry's index in the JSON array, or the zero-based line for line-delimited Compose output. Nothing else is read: `Env`, `Mounts`, `NetworkSettings`, `Ports`, and `Labels` beyond the two OCI labels above never appear in the report.

`resource` is the container name without the leading `/`, or the Compose service name. The image reference is parsed with the same parser the container detector uses ([`src/detectors/container/parse-image.ts`](../src/detectors/container/parse-image.ts)); interpolated values (`${IMAGE}`) and invalid references are skipped, never guessed.

### Rules matched

Images map to Docker PURLs, `pkg:docker/<repository>`, and are checked against [`registry/container.json`](https://github.com/velella-sh/ebb/blob/main/registry/container.json). For example, `node:18-alpine` becomes `pkg:docker/library/node` at version `18-alpine`, and `redis:6.0` becomes `pkg:docker/library/redis` at `6.0`. A tag that names a release line is the version; a floating tag such as `latest` or a digest-only reference has no version, so a range rule reports `version-dependent` instead of guessing.

Images from a registry other than Docker Hub keep the registry as the PURL namespace, for example `pkg:docker/ghcr.io/acme/app`. No Docker Hub rule matches those PURLs, so they are reported as `no-data`.

The two OCI labels add items when present: `org.opencontainers.image.base.name` is the base image, and `org.opencontainers.image.version` is the image's own version. Both are checked against the same rules, with the container name as their resource.

### Image ids

When `Config.Image` is a bare image id (`sha256:…`), Offing does not resolve it to an image. The container is reported with the PURL `pkg:docker/image-id` and the id as its version, which yields `no-data`: there is no lifecycle rule for an unresolved id. Run `docker inspect --format '{{.Config.Image}}' <container>` with a name instead when you need the image.

### What is not judged

- The operating system and runtimes *inside* an image: export or unpack the root filesystem and run `offing scan` on it.
- Images on registries other than Docker Hub, and Microsoft .NET images on `mcr.microsoft.com`: no rule is applied.
- Environment variables, mounts, published ports, and network settings: never read or reported.
- Whether a container is running: stopped containers are reported the same way.

## Report shape

The JSON report is `offing.inventory.v1`, validated by [`schemas/inventory.v1.schema.json`](../schemas/inventory.v1.schema.json). `results` holds one entry per item and check; `unrecognized` lists the files no importer recognized. Items are sorted by file and pointer, so the same exports produce the same report.

A Package URL with no rule is reported as `no-data`; when a PURL has rules but none covers the version, the item is `not-affected`. Neither status is a statement that the version is safe. A rule for an announced date that has not happened yet is a `scheduled-end-of-life` finding at low severity, so it does not fail a `high` gate.

## Importers

| Importer | Reads | Export command |
| --- | --- | --- |
| `aws-rds` | AWS RDS instances, Aurora clusters, and ElastiCache cache clusters | `aws rds describe-db-instances`, `aws rds describe-db-clusters`, `aws elasticache describe-cache-clusters` |
| `k8s-cluster` | Kubernetes control-plane and kubelet versions, node OS images, and container runtimes | `kubectl version -o json`, `kubectl get nodes -o json` |
| `terraform-state` | Terraform state from `terraform show -json` or a raw `terraform.tfstate` v4 file | `terraform show -json` |

## AWS RDS, Aurora, and ElastiCache

### Produce the export

Use the AWS CLI with JSON output and pass the file to `offing inventory`:

```bash
aws rds describe-db-instances --output json > rds-instances.json
aws rds describe-db-clusters --output json > rds-clusters.json
aws elasticache describe-cache-clusters --output json > cache-clusters.json

offing inventory rds-instances.json rds-clusters.json cache-clusters.json
```

The fixtures under `tests/fixtures/inventory/aws-rds/` are sanitized samples of these three documents: every account id, ARN, endpoint, and subnet id is a placeholder, and only the fields below are kept. They were assembled from the published output shape of `aws-cli` during review rather than captured from a live account.

### Fields read

| Document | Array | Engine field | Version field | Resource field |
| --- | --- | --- | --- | --- |
| `describe-db-instances` | `DBInstances` | `Engine` | `EngineVersion` | `DBInstanceIdentifier` |
| `describe-db-clusters` | `DBClusters` | `Engine` | `EngineVersion` | `DBClusterIdentifier` |
| `describe-cache-clusters` | `CacheClusters` | `Engine` | `EngineVersion` | `CacheClusterId` |

Everything else in the document is ignored: ARNs, endpoints, reader endpoints, hosted zone ids, subnet groups, VPC ids, security groups, tags, and parameter groups. An entry without a string `Engine`, `EngineVersion`, and resource field is skipped, never guessed.

### Engines and PURLs

| AWS engine | Provider PURL | Upstream PURL |
| --- | --- | --- |
| `postgres` | `pkg:generic/aws-rds/postgres` | `pkg:generic/postgresql` |
| `mysql` | `pkg:generic/aws-rds/mysql` | `pkg:generic/mysql` |
| `aurora-postgresql` | `pkg:generic/aws-aurora/postgresql` | `pkg:generic/postgresql` |
| `aurora-mysql`, `aurora` | `pkg:generic/aws-aurora/mysql` | none (see below) |
| `redis` | `pkg:generic/aws-elasticache/redis` | `pkg:generic/redis` |

Each recognized object produces two items when the version is also an upstream version, so the report shows both the provider's schedule and the upstream engine's schedule. AWS standard support and extended support dates differ from upstream end of life, and the rules are kept separate for that reason.

Aurora MySQL is the exception: its `EngineVersion` embeds the Aurora version, as in `8.0.mysql_aurora.3.10.0`, which is not an upstream MySQL release. Only the Aurora item is emitted rather than comparing that string to upstream MySQL rules.

Unknown engines are skipped: `mariadb`, `sqlserver-*`, `oracle-*`, `db2-*`, `memcached`, and `valkey` have no reviewed rule in this importer yet, so they produce no item and no claim.

### Rules matched

The rules live in [`registry/database.json`](https://github.com/velella-sh/ebb/blob/main/registry/database.json) under the provider PURLs, with the AWS release calendar as their source. "End of standard support" is recorded with the registry's `end-of-support` event; an announced date that is still in the future is recorded as `scheduled-end-of-life` at low severity until it passes. The summary of each rule says whether RDS Extended Support or ElastiCache Extended Support may keep the version running for a fee.

| Service | Versions with a rule (as of 2026-10-30) |
| --- | --- |
| RDS for PostgreSQL | 9.6, 10, 11, 12, 13 (ended); 14 (scheduled 2027-02-28) |
| RDS for MySQL | 5.7, 8.0 (ended) |
| Aurora PostgreSQL | 11, 12, 13 (ended); 14 (scheduled 2027-02-28) |
| Aurora MySQL | 1 (5.6), 2 (5.7) (ended) |
| ElastiCache Redis OSS | 4, 5 (ended 2026-01-31); 6 (scheduled 2027-01-31) |

A version outside these ranges is not reported as supported. When the provider PURL has rules for other versions, the item is `not-affected`: the check message says that rules exist and none covers this version. When the PURL has no rules at all, it is `no-data`. Neither status is a statement that the version is safe. This includes RDS for PostgreSQL 15 and later, RDS for MySQL 8.4 and later, Aurora PostgreSQL 15 and later, Aurora MySQL 3 and 8.4, and Redis OSS 7.x. Their announced end-of-standard-support dates are more than twelve months past the review date, so no rule is recorded yet under decision [0010](decisions/0010-scheduled-end-of-life.md); a later review adds them when the dates come within the window.

### What is not judged

The importer does not judge instance classes, storage, IOPS, parameter groups, patch levels within a supported minor version, certificate authorities, Multi-AZ or read-replica topology, backup retention, encryption, or licensing. It does not judge MariaDB, SQL Server, Oracle, Db2, Memcached, or Valkey. It does not verify that an export is complete or current. It does not read an AWS account, role, or region, and it cannot see an object that the export omits.

## Export files

Each section below documents one importer: the exact command that produces the export, the fields Offing reads, the lifecycle rules it matches, and what it does not judge. Fixtures live under `tests/fixtures/inventory/`, with every identifier replaced by a placeholder; the command and CLI version that produced them are recorded in the section.

## AWS Lambda

```bash
aws lambda list-functions --output json > lambda.json
offing inventory lambda.json
```

`list-functions` paginates. With pagination on, the CLI prints one JSON page after another; `offing` accepts the single page a one-page account prints as well as the array of pages a scripted caller collects. The fixtures under `tests/fixtures/inventory/aws-lambda/` reproduce the documented output of `aws lambda list-functions --output json` from AWS CLI v2, with every identifier replaced by a placeholder; they were not captured against a live account, so no CLI version is recorded.

**Fields read**

| Field | Use |
| --- | --- |
| `Functions[].FunctionName` | `resource` and nothing more. |
| `Functions[].Runtime` | `version`, and the runtime identifier in `pkg:generic/aws-lambda-runtime/<Runtime>`. |
| `Functions[].PackageType` | `Image` means the function runs a container image, which has no managed runtime, so it is skipped. |

Nothing else is copied: not `FunctionArn`, `Role`, environment variables, tags, account id, code, or architecture.

**Rules matched**

`registry/serverless.json`, the `pkg:generic/aws-lambda-runtime/<identifier>` PURLs. Every runtime the [AWS Lambda runtimes page](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) gives a deprecation date for has a rule: a runtime the page lists under Deprecated runtimes is `end-of-life` at `high`, and a runtime the page lists as supported with a projected deprecation date is `scheduled-end-of-life` at `low` with that date as its deadline. The same rules back the Serverless detector, so one lifecycle fact reaches a declaration and a live function alike.

**Not judged**

- Container-image functions (`PackageType: "Image"`): their runtime lives in the image, not in the function's configuration. Rebuild the image from a newer base image instead.
- Runtimes AWS has not dated — today `nodejs26.x` and `python3.15`, which the page lists as public preview and not scheduled — are reported as `no-data`, which is not a statement that they are safe.
- Function versions, aliases, `$LATEST`, code, layers, architecture, and memory: none of them changes the runtime lifecycle answer.
- Functions that a different export would show: this importer reads only the file you pass, and only the functions in it.

## AWS EKS clusters and node groups

```bash
aws eks describe-cluster --name prod-payments > cluster.json
aws eks describe-nodegroup --cluster-name prod-payments --nodegroup-name workers > nodegroup.json
offing inventory cluster.json nodegroup.json
```

Each command prints one document: `describe-cluster` prints `{"cluster": …}` and `describe-nodegroup` prints `{"nodegroup": …}`. A script that collects several outputs into one JSON array is read as well, so `jq -s '.[] | {cluster: .}'` over a list of cluster exports works; an array is read only when every element is one of the two document shapes.

**Fields read**

| Export | Fields | PURL | Version |
| --- | --- | --- | --- |
| `aws eks describe-cluster` | `cluster.name`, `cluster.version` | `pkg:generic/amazon-eks` | `version` |
| `aws eks describe-nodegroup` | `nodegroup.clusterName`, `nodegroup.nodegroupName`, `nodegroup.version` | `pkg:generic/amazon-eks` | `version` |
| `aws eks describe-nodegroup` | `nodegroup.amiType` | `pkg:generic/amzn` | the Amazon Linux release the AMI type is built on |

`resource` is the cluster name for a cluster and `<clusterName>/<nodegroupName>` for a node group; a node group whose export carries no `clusterName` is named by its own name alone. A pointer marks the exact field the version came from — `/cluster/version`, `/nodegroup/amiType` — with `/<entry>` in front for an array, so `/1/nodegroup/version` is the `version` of the second entry.

A version is read only in the shape EKS itself writes: `1.31` or `1.31.4`. A `v` prefix or an `-eks-…` build suffix is the kubelet string a node reports, not the cluster's release line, so such a value is skipped rather than guessed; run `kubectl get nodes -o json` and the Kubernetes cluster importer for those. `aws eks list-clusters` and `aws eks list-nodegroups` print names only, and `aws eks describe-cluster-versions` prints the versions EKS offers rather than the one deployed: none of them is read.

**Amazon Linux AMI types**

`amiType` names the Amazon EKS optimized AMI the nodes run, and each type is built on a known Amazon Linux release:

| `amiType` | Item |
| --- | --- |
| `AL2_x86_64`, `AL2_x86_64_GPU`, `AL2_ARM_64` | `pkg:generic/amzn` at `2` |
| `AL2023_x86_64_STANDARD`, `AL2023_ARM_64_STANDARD`, `AL2023_x86_64_NEURON`, `AL2023_x86_64_NVIDIA`, `AL2023_ARM_64_NVIDIA` | `pkg:generic/amzn` at `2023` |

The item is judged by the same host-OS rules a server's `/etc/os-release` is judged by, so an AL2 node group reports the Amazon Linux 2 end of support and an AL2023 node group reports `not-affected` — which says nothing about the packages inside the AMI. `BOTTLEROCKET_*`, `WINDOWS_*`, and `CUSTOM` produce no Amazon Linux item: no reviewed rule judges them, so the node group's operating system is skipped rather than guessed. `releaseVersion` (`AL2023_x86_64_STANDARD_20260918`) is an AMI build string and `platformVersion` (`eks.3227`) is the EKS platform, neither of which has a lifecycle of its own, so neither is read.

**Rules matched**

- `registry/kubernetes.json`: the `pkg:generic/amazon-eks` minor-version rules, sourced to the [Amazon EKS version lifecycle page](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html). A version past end of standard support but still inside its 12 months of extended support is `end-of-support` at `medium` with that end date as its deadline; `1.30` and earlier, which the calendar no longer lists, are `end-of-life` at `high`; an announced end of standard support that has not passed yet is `scheduled-end-of-life` at `low` ([decision 0010](decisions/0010-scheduled-end-of-life.md)), which is why `1.34`, `1.35`, and `1.36` carry rules and `1.37` does not yet — its date, 2027-12-01, is more than twelve months out.
- `registry/container.json`: the `pkg:generic/amzn` rules for a node group's AMI type.

`registry/terraform.json` carries the same EKS facts as its own rules for the Terraform detector, which reads `cluster_version` in `*.tf`; the Terraform state importer reads `registry/kubernetes.json`, so a state file's `aws_eks_cluster` and a live `describe-cluster` export are judged by the same rules.

**What is not judged**

- Self-managed nodes, Fargate pods, and any node outside a managed node group: `aws eks describe-nodegroup` only describes managed node groups. Use `kubectl get nodes -o json` for what is actually running.
- `cluster.addons[]` versions, `accessConfig`, `encryptionConfig`, `outpostConfig`, and upgrade policies.
- `endpoint`, `certificateAuthority.data`, `arn`, `roleArn`, `resourcesVpcConfig`, `subnets`, `securityGroupIds`, `remoteAccess.ec2SshKey`, tags, and labels: never read, never emitted.
- An EKS release no rule covers yet — today `1.37` — which reports `no-data`. `no-data` is never a statement that the version is supported.

**Fixtures**

`tests/fixtures/inventory/aws-eks/` holds one sanitized sample per document type, plus `rejects/` for the shapes listed above, with every account id, ARN, endpoint host, certificate, subnet, VPC and security group id, SSH key name, and tag value replaced by a placeholder. `examples/inventory/aws-eks.json` is a runnable sample. The shapes follow the documented output of AWS CLI v2 rather than a capture from a live account, so no CLI version is recorded.

## Google Cloud

```bash
gcloud functions list --format=json > functions.json
gcloud app versions list --format=json > app-engine-versions.json
gcloud container clusters list --format=json > gke-clusters.json
gcloud run services list --format=json > cloud-run-services.json
offing inventory functions.json app-engine-versions.json gke-clusters.json cloud-run-services.json
```

**Fields read**

| Export | Fields | PURL |
| --- | --- | --- |
| `gcloud functions list --format=json` | `name`, `runtime` (1st gen) or `buildConfig.runtime` (2nd gen) | `pkg:generic/google-cloud-functions-runtime/<runtime>` |
| `gcloud app versions list --format=json` | `name`, `runtime` | `pkg:generic/google-appengine-runtime/<runtime>` |
| `gcloud container clusters list --format=json` | `name`, `currentMasterVersion`, `currentNodeVersion` | `pkg:generic/google-gke` |
| `gcloud run services list --format=json` | `metadata.name`, `spec.template.spec.containers[].image` | `pkg:docker/library/<image>` |

`name` supplies the resource: the last path segment, never the project id or number. A Cloud Functions or App Engine runtime item reports the runtime as part of PURL, so the pointer marks the exact field the runtime was read from. A GKE cluster produces one item for the control-plane version and, when it differs, one for the node version; `releaseChannel` does not change the verdict, because the rules state both the end of standard support and the end of extended support.

Cloud Run has no managed language runtime. The importer reads only container images and only those that name a public Docker Hub base image (`node:20`, `python:3.12-slim`, or `library/node:20`): an image with a registry host or a namespace (`gcr.io/…`, `us-docker.pkg.dev/…`, `bitnami/node`) is skipped, as is an image with no tag, a digest-only reference, or a tag that does not start with a digit. A short image name maps to `pkg:docker/library/<name>` with the tag as the version.

**Rules matched**

- `registry/serverless.json`: Google Cloud Functions and App Engine runtime rules, sourced to Google's runtime support schedules.
- `registry/kubernetes.json`: GKE minor-version rules, sourced to the GKE release schedule.
- `registry/container.json`: base-image rules for Cloud Run images.

**What is not judged**

- Runtime *generations* and stack images (`google-22`, `google-24-full`); only the runtime ID is checked.
- Operating-system packages inside a function or container image.
- Image digests, private images, and image names that are not public base images.
- Anything not written literally in the export: a reference, a variable, or a value the export does not include is not resolved.

**Fixtures**

`tests/fixtures/inventory/gcp/` holds one sanitized sample per document type, and `examples/inventory/` holds two runnable samples. Each follows the JSON the commands above print, reduced to the fields this importer reads, with every project id, number, service account, URL, IP address, and environment value replaced by a placeholder. No `gcloud` CLI version is recorded because the contributor who added this importer had no Google Cloud project to capture exports from; the shapes follow the documented JSON output of the commands above rather than a recorded response.

## Azure

```bash
az webapp list -o json > webapps.json
az functionapp list -o json > functionapps.json
az aks list -o json > aks-clusters.json
offing inventory webapps.json functionapps.json aks-clusters.json
```

**Fields read**

| Export | Fields | PURL |
| --- | --- | --- |
| `az webapp list -o json` | `name`, `kind`, `siteConfig.linuxFxVersion` or `siteConfig.windowsFxVersion` | `pkg:generic/azure-app-service/<stack>` |
| `az functionapp list -o json` | the same, plus `siteConfig.FUNCTIONS_EXTENSION_VERSION` | `pkg:generic/azure-app-service/<stack>` and `pkg:generic/azure-functions` |
| `az aks list -o json` | `name`, `kubernetesVersion`, `agentPoolProfiles[].orchestratorVersion` | `pkg:generic/azure-aks` |

`name` supplies the resource: the app or cluster name, never the subscription id, the resource group id, a host name, or an ARM `id` path.

**Stack references**

`linuxFxVersion` and `windowsFxVersion` name the managed stack and its version in one string. The prefix selects the stack and the part after the first `|` is read as the version, stopping at the first `-`:

| Reference | Item |
| --- | --- |
| `NODE\|18-lts` | `pkg:generic/azure-app-service/node` at `18` |
| `PYTHON\|3.8` | `pkg:generic/azure-app-service/python` at `3.8` |
| `DOTNETCORE\|6.0` | `pkg:generic/azure-app-service/dotnet` at `6.0` |
| `DOTNET-ISOLATED\|7.0` | `pkg:generic/azure-app-service/dotnet-isolated` at `7.0` |
| `JAVA\|11-java11` | `pkg:generic/azure-app-service/java` at `11` |
| `PHP\|8.0` | `pkg:generic/azure-app-service/php` at `8.0` |

A reference with a third part (`PYTHON\|3.11\|3.0`) gives the same version. `DOCKER\|<image>` is a custom container with no managed stack, an empty value, a prefix this importer has no rules for, a reference with more than three parts (`JAVA\|8\|TOMCAT\|9.0`, where the app-server release is what a rule would need), and an app with no `siteConfig` are all skipped rather than guessed.

`az webapp list` and `az functionapp list` print the `SiteResource`, whose `siteConfig` the App Service API omits from a normal read because it can hold secrets. When the export has no `siteConfig`, read each app's configuration and keep its name and kind:

```bash
az webapp list -o tsv --query '[].{group:resourceGroup,name:name,kind:kind}' \
  | while read -r group name kind; do
      az webapp config show -g "$group" -n "$name" -o json \
        | jq --arg name "$name" --arg kind "$kind" '{name: $name, kind: $kind, siteConfig: .}'
    done \
  | jq -s '.' > webapps.json
offing inventory webapps.json
```

`az aks list` returns the cluster versions directly, so no follow-up call is needed.

**Functions runtime**

The Functions runtime version is an app setting in Azure, and app settings are never read: they carry connection strings and keys. An item is therefore produced only for an export that writes the value straight into `siteConfig`, never for one that carries it as a `siteConfig.appSettings` entry, and never for a setting named in an app whose `kind` does not include `functionapp`. Both spellings of the value are read: `~4` becomes version `4` and a pinned build such as `2.0.12345` keeps its build.

**AKS versions**

A cluster produces one item for its control plane (`kubernetesVersion`) and one for each agent pool version that differs from a version already reported for that cluster (`agentPoolProfiles[].orchestratorVersion`), so a pool that matches its control plane is not counted twice.

**Rules matched**

- `registry/serverless.json`: the `pkg:generic/azure-app-service/<stack>` and `pkg:generic/azure-functions` rules, sourced to Azure's [language runtime support policy](https://learn.microsoft.com/en-us/azure/app-service/language-support-policy) and [Functions runtime version page](https://learn.microsoft.com/en-us/azure/azure-functions/functions-versions), each citing the community schedule Azure follows for that runtime.
- `registry/kubernetes.json`: the `pkg:generic/azure-aks` minor-version rules, sourced to the [AKS supported Kubernetes versions page](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions). A version past its 12-month support window is `end-of-support` at `medium`; one past opt-in long-term support is `end-of-life` at `high`; an announced window end that has not passed yet is `scheduled-end-of-life` at `low`.

**What is not judged**

- `agentPoolProfiles[].osSku` and `windowsVersion`, and any node operating system or package inside a node image: the AKS rules judge the Kubernetes version only. Scan a node root filesystem export for its packages.
- `siteConfig.appSettings` and every other app setting, including a `FUNCTIONS_WORKER_RUNTIME` or a `FUNCTIONS_EXTENSION_VERSION` that only lives there.
- Host names, IPs, URLs, `serverFarmId`, SKU, location, tags, `resourceGroup`, and ARM `id` paths.
- Custom-container apps, and a Java app server (Tomcat, JBoss) named in a stack reference: no rule is applied to it.
- A stack version with no rule yet — today for example `NODE|24` or `JAVA|11` — which reports `not-affected`. That is not a statement that the version is supported; it says no Azure rule covers it.

**Fixtures**

`tests/fixtures/inventory/azure/` holds one sanitized sample per document type, with every subscription id, resource group id, ARM path, host name, IP address, DNS prefix, SSH key, service principal, and app-setting value replaced by a placeholder. `examples/inventory/azure-webapps.json` and `examples/inventory/aks.json` are runnable samples. No Azure CLI version is recorded because the contributor who added this importer had no Azure subscription to capture exports from; the shapes follow the documented JSON output of the commands above rather than a recorded response.

## Terraform state

The `terraform-state` importer reads the values Terraform recorded for deployed resources. It accepts two shapes:

```bash
# the state JSON `terraform show -json` prints
terraform show -json > state.json

# or the raw state file itself
offing inventory state.json terraform.tfstate
```

The first shape is state JSON: `format_version` plus `values.root_module`. The second is the raw state file: `version: 4` plus `resources`. Plan JSON (`planned_values.root_module`) is not read, because it describes a proposed change rather than what is deployed. The importer does not read `*.tf` source files; the Terraform detector already does that.

**Fields read**

Every module under `values.root_module`, including `child_modules` at any depth, and every resource instance is walked. In raw state, every entry of `resources` and every instance of `instances` is walked. Data sources and deposed objects are skipped.

| Resource type | Attribute | PURL | Version |
| --- | --- | --- | --- |
| `aws_lambda_function` | `runtime` | `pkg:generic/aws-lambda-runtime/<runtime>` | the runtime ID |
| `aws_db_instance`, `aws_rds_cluster`, `aws_elasticache_cluster`, `aws_elasticache_replication_group` | `engine`, `engine_version` | the AWS engine table below | `engine_version` |
| `aws_eks_cluster` | `version` | `pkg:generic/amazon-eks` | `version` |
| `google_container_cluster` | `master_version` | `pkg:generic/google-gke` | `master_version` |
| `google_cloudfunctions_function` | `runtime` | `pkg:generic/google-cloud-functions-runtime/<runtime>` | none: the runtime is part of the PURL |
| `google_cloudfunctions2_function` | `build_config[0].runtime` | `pkg:generic/google-cloud-functions-runtime/<runtime>` | none: the runtime is part of the PURL |
| `azurerm_kubernetes_cluster` | `kubernetes_version` | `pkg:generic/azure-aks` | `kubernetes_version` |
| `azurerm_linux_function_app` | `site_config[0].application_stack` | `pkg:generic/azure-app-service/<stack>` | the stack version |

Nothing else in the state is copied. ARNs, resource ids, endpoints, provider configurations, outputs, tags, environment variables, and Terraform or provider versions are never read or reported. A value that is missing, empty, not a string, or not a release-shaped value is skipped, never guessed.

**Resource and pointer**

`resource` is `<type>.<name>`, with `[index]` for `count` and `["key"]` for `for_each`, such as `aws_lambda_function.worker[0]` or `aws_lambda_function.api["green"]`. A nested resource keeps the same form; the module path is in the JSON Pointer, not in `resource`. Every pointer resolves to the exact string the item's version came from: `/values/root_module/resources/<i>/values/<attribute>` for state JSON, or `/resources/<i>/instances/<j>/attributes/<attribute>` for raw state, with `child_modules` segments in between.

**Engines and PURLs**

The engine mapping is the one the AWS RDS importer uses, so a deployed engine and a described engine are checked against the same rules:

| AWS engine | Provider PURL | Upstream PURL |
| --- | --- | --- |
| `postgres` | `pkg:generic/aws-rds/postgres` | `pkg:generic/postgresql` |
| `mysql` | `pkg:generic/aws-rds/mysql` | `pkg:generic/mysql` |
| `aurora-postgresql` | `pkg:generic/aws-aurora/postgresql` | `pkg:generic/postgresql` |
| `aurora-mysql`, `aurora` | `pkg:generic/aws-aurora/mysql` | none |
| `redis` | `pkg:generic/aws-elasticache/redis` | `pkg:generic/redis` |

Unknown engines, including `mariadb`, `sqlserver-*`, `oracle-*`, `db2-*`, `memcached`, and `valkey`, produce no item and no claim.

The Linux Function App stack reads the managed version fields of `application_stack` and maps each one to its own item:

| Field | PURL |
| --- | --- |
| `dotnet_version` | `pkg:generic/azure-app-service/dotnet` |
| `dotnet_isolated_version` | `pkg:generic/azure-app-service/dotnet-isolated` |
| `java_version` | `pkg:generic/azure-app-service/java` |
| `node_version` | `pkg:generic/azure-app-service/node` |
| `python_version` | `pkg:generic/azure-app-service/python` |
| `powershell_core_version` | `pkg:generic/azure-app-service/powershell` |

A leading `~` in a Node.js version is Azure's release-line notation, so `~18` is reported at version `18`. `use_custom_runtime` and a `docker` image mean the runtime is not a managed stack, so they produce no item.

**Rules matched**

- `registry/database.json`: RDS, Aurora, and ElastiCache engine rules, the same rules the AWS RDS importer uses.
- `registry/kubernetes.json`: GKE, AKS, and EKS minor-version rules.
- `registry/serverless.json`: AWS Lambda, Google Cloud Functions, and Azure App Service stack and Functions runtime rules.

`pkg:generic/amazon-eks` has rules in both `registry/kubernetes.json`, which this importer reads, and `registry/terraform.json`, which the Terraform source detector reads, so a cluster recorded in state and a `cluster_version` written in `*.tf` are judged by the same calendar. An EKS version no `registry/kubernetes.json` rule covers reports `no-data`. `no-data` is never a statement that the version is safe.

**What is not judged**

- Terraform plan JSON, `*.tf` source, module outputs, and provider configurations: this importer reads state values only.
- Deposed instances: only current instances are reported.
- Resource types and attributes beyond the table above, including EKS node groups, RDS proxy endpoints, and functions deployed outside the listed resource types.
- Whether the state is current, whether it matches the configuration, or whether a remote backend is reachable. Offing reads only the file you pass and never runs Terraform.

**Fixtures**

`tests/fixtures/inventory/terraform-state/` holds one sample of each format, including nested modules and `count` and `for_each` instances, with every account id, ARN, subscription id, project number, hostname, and environment value replaced by a placeholder. `examples/inventory/terraform-state.json` is a runnable sample in the `terraform show -json` shape. They were assembled from the documented state shape of Terraform 1.9 rather than captured from a live state; no Terraform CLI version is recorded.

---

Source: https://velella.sh/offing/playbooks/agent/

# Playbook: agent-driven migrations

A start-to-finish guide for letting a coding agent (Claude Code, Codex, Cursor, Copilot, Gemini CLI, Kilo Code) migrate one end-of-life or deprecated dependency, runtime, or GitHub Action, while Offing supplies the facts and the proof.

The split of responsibility is the point. Offing decides **what** is affected and **whether it is fixed**. The agent decides **how** to change the code. A human decides **whether to merge**.

## Before you start

- Install the guardrail so the agent checks before it adds anything: `npx skills add velella-sh/offing`, or connect the local MCP server ([MCP.md](../MCP.md)). Either path needs no account or API key.
- Work on a branch with a clean tree. One finding per branch keeps the diff reviewable and the verification unambiguous.
- Run the project's own tests once before changing anything. A migration cannot be verified against a suite that was already failing.

## The loop

Every migration is the same four steps. The agent should run them in order and stop if one fails.

### 1. Discover

```bash
npx @velella/offing scan . --json
```

Pick **one** finding and copy its exact `id`. Do not let the agent batch several findings into one change.

For a large result, `--format compact` fits an agent's context window, and `scan --write-status` writes `OFFING_STATUS.md` so an agent that cannot call tools can still read the repository's lifecycle state.

### 2. Explain

```bash
npx @velella/offing explain '<finding-id>' . --json
```

Read the rule, the exact location, and the authoritative source. If the agent cannot point to the source, it should not proceed: a lifecycle claim without a source is not a reason to change code.

### 3. Migrate

```bash
npx @velella/offing context '<finding-id>' . --json
```

The migration packet ([MIGRATION_PACKETS.md](../MIGRATION_PACKETS.md)) lists the declaration, every usage, behavioral constraints, ordered steps, and suggested verification commands. The agent follows the steps and touches only the affected files the packet names. Offing never edits files and never runs the suggested commands; the agent runs them under the host's normal permission prompts, after reading them.

### 4. Verify

```bash
npx @velella/offing scan . --json
```

The migration is done only when **both** hold: the project's tests pass, and a fresh scan no longer reports that rule at that location. Through MCP, `verify_migration` does the second check in the session that saw the finding. An unknown or missing finding ID after a rescan is not proof of success; the agent should compare rule and path, not just the ID.

## Worked examples on real repositories

These come from the pinned public corpus in `benchmarks/public-repositories/`, so each location is one Offing reports at that commit.

**A Python floor that reached end of life: `psf/requests`.** At commit `611c616`, line 17 of `pyproject.toml` reads `requires-python = ">=3.10"`, a release line that ended on 2026-10-01 (rule `python.runtime.eol-3.10-and-older`). The packet's scope is the declaration plus anything that gates on the old floor (CI matrix entries, classifiers, `python_requires` checks in tests). Raising the floor changes what the package supports for its users, so this is a decision to take to a maintainer; the agent should present the change, not make it silently.

**A deprecated Action in many workflows: `Akenon-Studio/.github`.** At commit `4ec1ebe`, `.github/workflows/security-scan.yml` line 127 uses an `actions/setup-node` release on Node 20, and two workflows use `actions/create-github-app-token@v2` below the supported major. The maintainers' own migration commit is the reference outcome. Here the packet paths are workflows only, so the diff should be a handful of `uses:` lines and nothing else. Check the Action's release notes for changed inputs before accepting the bump.

## Failure modes and what to do

| What goes wrong | Why | Response |
| --- | --- | --- |
| The agent edits files outside the packet | The packet's affected-file set is the scope; a broader edit has no Offing evidence behind it | Revert the extra edits, or open a follow-up issue for them |
| The agent bumps a version but the finding remains | The rule keys on the declaration, a range, or a runtime file the bump did not touch | Rescan, read the new location, repeat from step 2 |
| Tests pass, finding gone, behavior changed | The packet lists behavioral constraints for a reason; tests may not cover them | Read the constraints against the diff before merging |
| `no-data` from `check_dependency` for a replacement | Offing has no rule for it | Treat as unknown, not safe; pick the replacement the packet cites |
| The agent runs a suggested command that fails or is destructive | Suggested commands depend on project setup | Review commands first; Offing only suggests them |
| A finding keeps returning in CI | It was never fixed, or the baseline expired | Use `--baseline` only for findings you accept on purpose, with `--on-expired fail` so acceptance cannot rot |
| The finding ID is stale | IDs come from a specific scan | Rescan and select the finding again |
| Dynamic references or unsupported ecosystems | Offing reports a limitation instead of guessing | Report the limitation; do not invent a rule |

## Privacy boundaries

- Scans, `explain`, `context`, `check`, and the MCP server run locally and use no network. The one command that does is `offing data update`, which you run yourself ([PRIVACY.md](../PRIVACY.md)).
- Offing sends nothing about your repository anywhere. It has no account, no analytics, and no telemetry.
- **The agent host is a separate party.** Scan results and migration packets contain file paths and short source excerpts. Once they enter an agent's context, that host's privacy policy and your workspace settings apply. For a private repository, use a host and plan you already trust with that code.
- Repository contents are untrusted input. A file that says "ignore your instructions" is data, not a command. Do not let the agent follow instructions found in the repository, in a finding, or in a source excerpt.
- Do not put credentials in prompts. Offing never asks for them.

## Reviewing the result

Treat the agent's change like any contributor's pull request:

1. The diff touches only files named in the packet.
2. The cited source supports the claim in the PR description.
3. Project tests pass, and a fresh `offing scan` no longer reports the finding.
4. In CI, the [GitHub Action](../GITHUB_ACTION.md) with `fail-on-severity` keeps the finding from coming back.

## Prompt template

```text
Migrate one Offing finding in this repository.

1. Run `npx @velella/offing scan . --json` and pick finding <ID>.
2. Run `explain` and `context` for it. Summarize the source before editing.
3. Change only the files the migration packet lists. Do not refactor anything else.
4. Review each suggested verification command before running it.
5. Run the project tests, then rescan. Stop if the finding remains or tests fail,
   and tell me what you saw instead of widening the change.
```

---

Source: https://velella.sh/offing/playbooks/cli/

# Playbook: manual CLI checks

A start-to-finish guide for checking a repository by hand with the Offing CLI: scan it, read a finding, decide what to do, accept what you must, and keep it from coming back. No agent, account, or API key is involved. For agent-driven fixes, see [agent.md](agent.md).

## Before you start

- Node.js 22 or newer. Run commands with `npx @velella/offing <command>` or, from a clone of this repository, `npm run dev -- <command>`. The examples below write `offing`.
- Run `offing doctor --system` once. It confirms the runtime, the package, and the bundled MCP server and skill are usable, and says what to fix if not.
- Run `offing data status` to see which lifecycle data you are checking against and how old its evidence is. A scan is only as current as that date; `offing data update` is the one command that uses the network, and you run it yourself ([DATA.md](../DATA.md)).
- Work from a clean tree so a later diff shows only what you changed.

## The manual loop

### 1. Scan

<!-- testable -->
```bash
offing scan .
```

The summary lists every finding with its rule, location, severity, and replacement. Useful variants:

| Need | Command |
| --- | --- |
| One line per finding, for a terminal or a commit hook | `offing scan . --format compact` |
| Machine-readable output | `offing scan . --json` |
| Browse and jump to the line in `$EDITOR` | `offing scan . --interactive` (plain text when not a terminal) |
| Several projects at once, with combined counts | `offing scan ./api ./web ./infra` |
| A shareable report | `offing scan . --format html` or `--format sarif` |

A finding ID has the form `<rule-id>:<path>:<line>`, for example `nodejs.runtime.eol-18:package.json:1`. Copy it exactly; IDs belong to the scan that produced them.

### 2. Check a single package

You do not need to scan to ask about one thing. Use a Package URL:

<!-- testable expect=1 -->
```bash
offing check pkg:npm/request@2.88.2
offing check pkg:github/actions/setup-node@v3
```

`check` exits `1` when a rule at or above `--fail-on` (default `high`) applies and `0` otherwise. Three results look alike at a glance and mean different things:

| Status | Meaning | What to do |
| --- | --- | --- |
| `affected` | A reviewed rule applies, with a source | Read it; plan a replacement |
| `version-dependent` | The package has rules for some versions only | Re-run with a version |
| `no-data` | Offing has no rule for it | Treat as unknown, **not** safe |

### 3. Explain

<!-- testable -->
```bash
offing explain 'nodejs.runtime.eol-18:package.json:1' .
```

Read the rule, the exact location, and the authoritative source link. Open the source yourself. If the finding looks wrong (the line is not what the rule describes, or the source does not support the claim), stop and run `offing report-issue '<finding-id>' . --output issue.md` to produce a ready-to-file report instead of working around it.

### 4. Get the migration context

<!-- testable -->
```bash
offing context 'nodejs.runtime.eol-18:package.json:1' .
```

The packet lists the declaration, every usage, behavioral constraints, ordered steps, and suggested verification commands ([MIGRATION_PACKETS.md](../MIGRATION_PACKETS.md)). Offing never edits files and never runs those commands; you read each one and run it yourself.

### 5. Fix, then re-scan

Make the change, run the project's own tests, then:

<!-- testable -->
```bash
offing scan .
```

You are done when the tests pass **and** that rule no longer appears at that location. A changed finding ID is not proof of a fix: line numbers move, so compare the rule and path.

## Accepting a finding on purpose

Some findings cannot be fixed today (a customer pins you to an old runtime, a vendor has not shipped the replacement). Record that decision instead of ignoring the output:

<!-- testable -->
```bash
offing baseline . --output offing-baseline.json
offing scan . --baseline offing-baseline.json --on-expired fail
```

Findings in the baseline are suppressed and counted (`Baseline: 4 findings suppressed`). Suppressions expire; `--baseline-warn-days <n>` warns before they do, and `--on-expired fail` makes the scan exit `1` once one has, so acceptance cannot quietly become permanent. Commit the baseline file so the decision is reviewable. Do not baseline a finding you have not read.

## Scanning as of a date

<!-- testable -->
```bash
offing scan . --as-of 2027-07-01
```

`--as-of <YYYY-MM-DD>` answers "will this repository be clean on 1 July?". Every announced end of life (a `scheduled-end-of-life` rule) whose deadline is on or before that day is reported as ended, at end-of-life severity, so `--fail-on high` fails on what will break by then. Finding IDs do not change, so a baseline still matches. `--today` is an alias, and with `--baseline` the same day also decides which suppressions have expired. The result carries `asOf`. The scan itself still reads no clock and no network.

`--min-support-days <n>` warns before a line expires instead of after: a finding whose deadline falls within the next `n` days (from today, or from `--as-of`) is raised to `medium`, so the default `--fail-on high` gate stays green while the warning shows up. It is off unless given, and the same window is the `min-support-days` Action input.

This is not a forecast: `--as-of` projects the findings you have onto one day, while `offing forecast` lists what becomes end of life in the next 6 and 12 months.

## Forecasting what breaks next

<!-- testable -->
```bash
offing forecast .                       # the next 12 months
offing forecast . --months 6 --json
offing forecast . --as-of 2027-01-01    # count from another day
```

`forecast` lists the dated end-of-life events in the window, grouped by month, and shows where your repository is affected. Text output shows only events that touch a finding; `--json` (`ebb.forecast.v1`) lists every dated event, with an empty `findings` list for those that do not affect you. Events without a date are never listed or estimated, and the same date always gives the same output. `--months` takes 1 to 36 and defaults to 12. The scan reads no network.

## Gating a push or CI

<!-- testable -->
```bash
offing scan . --fail-on high      # exit 1 when a finding is high or critical
offing init --hooks --dry-run     # preview a pre-push hook for this repository
```

```bash
offing init --personal --dry-run  # preview a global hook for every repository
```

Without `--fail-on`, `scan` always exits `0`. Use `--dry-run` first to see exactly what `init` would write. Hooks never block a push when Offing is missing or a scan errors for another reason ([HOOKS.md](../HOOKS.md)). For CI, use the [GitHub Action](../GITHUB_ACTION.md).

For a repository you want to watch over time: `offing watch add ~/code/my-app`, then `offing watch --weekly` prints only what changed since the last run.

## Worked examples on real repositories

These come from the pinned public corpus in `benchmarks/public-repositories/`, so each location is one Offing reports at that commit.

**A Node.js range that includes ended releases: `expressjs/express`.** At commit `a419aa7`, `package.json` line 83 declares an `engines.node` range that also allows Node.js 18, 19, and 20, and `.github/workflows/ci.yml` line 49 tests a matrix starting at 18. A scan reports one finding per ended release line at the same declaration (`nodejs.runtime.eol-18`, `-19`, `-20`). Read them as one decision, not three: raising the floor changes which Node.js versions the package supports for its users, so `explain` first, then take it to a maintainer rather than editing the range on your own.

**A package that is only affected sometimes.** `offing check pkg:npm/<name>` without a version can answer `version-dependent`. That is the CLI telling you the answer depends on the version in your lockfile. Read the version from the lockfile, not from `package.json`, and check again with it.

## Failure modes and what to do

| What goes wrong | Why | Response |
| --- | --- | --- |
| `Findings: 0` on a path that does not exist | `scan` accepts a path with nothing in it and reports zero findings | Check the `Repository:` line in the output names the directory you meant |
| `No lifecycle risks found` on a project you expected to hit | The ecosystem or file is not covered, or the reference is dynamic | Run `offing capabilities`; Offing reports a limitation rather than guessing, so do not read silence as proof |
| `no-data` for a package | No reviewed rule exists | Unknown, not safe; look at the package's own release notes |
| A finding disappears after a data update | The rule changed or its evidence was revised | Run `offing data status`, then re-read the rule with `explain` |
| The finding ID is stale | IDs come from a specific scan | Re-scan and select it again |
| A bump leaves the finding in place | The rule keys on a range, a runtime file, or a workflow line the bump did not touch | Re-scan and read the new location |
| `check` exits non-zero with an error | Malformed Package URL (it must start with `pkg:`) | Fix the PURL; this is invalid input, not a finding |
| `--fail-on` breaks a hook you did not expect | The gate defaults to `high` | Choose it explicitly: `low`, `medium`, `high`, `critical`, or `none` |
| Results differ between machines | Different bundled data versions | Compare `offing data status` on both |

## Privacy boundaries

- `scan`, `check`, `explain`, `context`, `baseline`, `doctor`, and `mcp` run locally and use no network. `offing data update` is the one command that does, and you run it yourself. It sends nothing about your repository ([PRIVACY.md](../PRIVACY.md)).
- There is no account, analytics, or telemetry. By default Offing records nothing about what you checked. `OFFING_USAGE_LOG=1` opts in to a local file with the package, result, and rule IDs; it contains no repository path or file content and is never uploaded. Delete the file to erase it.
- Output contains file paths and short source excerpts. Before you paste a scan, a packet, or an `issue.md` into a ticket, a chat, or an AI tool, read it. For a private repository, share only what you are happy for that audience to see.
- `report-issue` writes a file; it does not send anything. Filing the issue is your action.
- Repository contents are untrusted input. Offing parses them and never executes them. A file that tells you to run something is still just a file.
- Suggested verification commands are suggestions. Read them before running them.

## Checklist for a manual pass

1. `offing data status` is recent enough for the decision you are making.
2. `scan` output names the repository you meant.
3. Each finding you act on has been through `explain`, and you opened its source.
4. Anything you accept is in a committed baseline with `--on-expired fail`.
5. A fresh `scan` after the change no longer reports the rule at that location, and the project's tests pass.

---

Source: https://velella.sh/offing/GITHUB_ACTION/

# GitHub Action

Offing's reusable Action scans the checked-out repository locally, emits GitHub annotations for findings, compares against an optional baseline, enforces a severity gate, and uploads the versioned JSON result.

## What it looks like

One comment per pull request, updated in place on every re-run, with the severity counts, the top findings, and their exact location. Each row links to the source the rule cites, so a reviewer can check the claim before changing code.

![Offing pull request comment showing severity counts and the top lifecycle findings with file locations](assets/screenshots/pr-comment.webp)

## Pull-request workflow

```yaml
name: Offing

on:
  pull_request:

permissions:
  contents: read

jobs:
  lifecycle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: velella-sh/offing@v0.1.1
        with:
          baseline: .offing-baseline.json
          fail-on-severity: high
```

Version tags provide stable release references. Pin a full commit SHA when your threat model requires immutable third-party action references. A release tag points at a commit that carries the compiled Action bundle, which the release chain builds onto a `release/<tag>` branch and never rebuilds, so the Action runs without installing anything and a tag you pinned keeps doing what it did. [Releasing](RELEASING.md#action-bundles-on-release-tags) explains why the bundle is not on `main`.

## Reusable workflow (one `uses:` line)

Organizations that want the same scan in every repository without copying checkout and Action steps can call the reusable workflow instead. It checks out the caller, runs Offing with the common inputs, and needs only `contents: read`. The Action version is pinned inside the workflow file, so pinning the workflow pins the scanner.

```yaml
name: Offing

on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: "0 4 * * 1"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  lifecycle:
    uses: velella-sh/offing/.github/workflows/offing-reusable.yml@v0.8.0
    with:
      baseline: .offing-baseline.json
      fail-on-severity: high
```

> **Version.** The reusable workflow first ships in `v0.8.0`. Until that tag exists, call `@main` only to try it, then replace it with the release tag before relying on it.

Every workflow input is optional and matches the Action default of the same name. Pass only what you need to change:

| Workflow input | Default | Meaning |
| --- | --- | --- |
| `path` | `.` | Repository root or subdirectory to scan. |
| `paths` | empty | Multi-line list of directories or globs relative to `path`. |
| `baseline` | empty | Baseline path relative to `path`. |
| `baseline-warn-days` | `14` | Warn when a baseline suppression expires within this many days. |
| `on-expired` | `resurface` | `resurface` or `fail` after a suppression's `expires` day. |
| `min-support-days` | empty | Warn on lines whose support ends within this many days. |
| `fail-on-severity` | `high` | Lowest failing level: `none`, `info`, `low`, `medium`, `high`, or `critical`. |
| `mode` | `scan` | `scan` or `diff` (diff fetches full history for the base and head SHAs). |
| `annotations` | empty | `changed`, `all`, or `none`; empty keeps the Action default. |
| `report-name` | `offing-report` | Artifact name when `upload-report` is true. |
| `upload-report` | `true` | Upload the JSON report as an Actions artifact. |
| `attribution` | `true` | Credit Offing in the job summary. |

The workflow exposes the same result outputs as the Action (`report-path`, `finding-count`, `has-new-findings`, `highest-severity`, `next-eol-date`, `findings-json`) so a later job can branch on them. Features that need write permissions — `pr-comment`, `suggest-fixes`, `commands`, `fix-pr`, `tracking-issue`, `upload-sarif`, `upload-badge` — stay on the Action step above; the reusable workflow keeps the minimal `contents: read` permission set.

For an organization `.github` repository that offers the starter in the Actions "New workflow" gallery, copy [`templates/workflows/`](../templates/workflows/) into that repository's `workflow-templates/` directory. See [Organization rollout](ORG_ROLLOUT.md#offer-the-starter-from-the-organizations-github-repository).

### SHA-pinned actions

For the first-party actions covered by Offing, a full 40-character commit pin is classified in this order:

1. A trailing release comment, such as `# v4`, `# v4.1.1`, `# tag=v4.1.1`, or `# version: v4.1.1`.
2. Offing's bundled map of exact release-tag SHAs, when the pin has no trailing comment.

```yaml
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
```

A malformed, ambiguous, or conflicting comment is not replaced by a map lookup: Offing reports it as `invalid-version-comment`. A SHA absent from the bundled map is reported as `unknown-sha`. These references are not lifecycle findings, so they do not affect severity gates or annotations.

The uploaded JSON report records the total in `unclassified.count` and lists each reference with its action, SHA, reason, and workflow location under `unclassified.references`. CLI text output adds a one-line count when any exist. Classification uses only repository contents and the bundled map; scans make no network requests.

Create and commit the baseline locally when existing findings are accepted:

```bash
npx @velella/offing baseline . --output .offing-baseline.json
```

A baseline entry can also say why a finding is accepted and until when. These fields are all optional, so a baseline written without them keeps working, and they never change which findings are suppressed:

```json
{ "fingerprint": "…", "ruleId": "nodejs.runtime.eol-20", "path": "package.json",
  "owner": "platform-team", "reason": "Upgrade tracked in PLAT-12", "created": "2026-10-17", "expires": "2027-01-31" }
```

`owner` and `reason` are non-empty text (up to 500 characters); `created` and `expires` are calendar dates (`YYYY-MM-DD`), and `expires` is not before `created`. An entry with a malformed field makes the baseline fail to load, with the entry's position in the message. The schema is [`schemas/baseline.v1.schema.json`](../schemas/baseline.v1.schema.json). **Expiry warnings.** When a scan uses a baseline, every suppression that matched a finding and expires within the next 14 days is listed in the scan's diagnostics (and as a `warning` on the Action run), soonest first, with its owner and reason:

```text
Baseline suppression expires in 5 days (2026-10-22): nodejs.runtime.eol-18 at package.json (owner: platform-team; reason: Upgrade tracked in PLAT-12).
```

Change the window with `--baseline-warn-days <n>` on `offing scan` or the `baseline-warn-days` Action input (0 to 365). The comparison day is today in UTC; `--today YYYY-MM-DD` sets it explicitly, which makes a run reproducible; suppression dates are compared only with that day.

**After `expires`.** A suppression is in force through its `expires` day and expired from the next day. An expired suppression stops hiding its finding: the finding is reported again, and the diagnostics say which suppression expired, how long ago, and its owner and reason. What happens beyond that is a policy, `--on-expired` on `offing scan` or the `on-expired` Action input:

| Policy | Behavior |
| --- | --- |
| `resurface` (default) | The finding is back in the results and is judged by the usual severity gate. |
| `fail` | The finding is back, and the scan also fails (the CLI exits 1, the Action fails the job) if any suppression has expired, even when the finding is below the gate. |

Only entries with an `expires` can expire, so a baseline written before these fields behaves exactly as before. A finding stays hidden while at least one of its suppressions is in force.

**Seeing what a baseline does.** A scan that uses a baseline never hides suppressions silently. `offing scan --json` adds a `suppressions` object to the result (and `scan.v1.schema.json` documents it): how many findings the baseline hid, the day it compared with, and the `expiring` and `expired` suppressions with their rule, path, `expires` day, owner, and reason. The text report ends its findings with a line such as `Baseline: 3 findings suppressed, 1 expiring within 14 days, 0 expired.`, the Action's job summary shows the same line and a table of the expiring and expired suppressions, and the MCP `scan_repository` tool returns the object when it is given a `baseline`. A scan without a baseline has no `suppressions` field.

**Upgrading needs no migration.** A baseline written by an earlier version (the `offing.baseline.v1` schema, with only `fingerprint`, `ruleId`, and `path`) loads and suppresses exactly what it always did; a test loads a baseline written by the published 0.1.0 against the current scanner. Fingerprints do not depend on the new fields, so adding an owner or reason to an existing entry by hand does not change what it suppresses. A newer release can report findings that an older baseline never recorded (for example a rule added since); those appear as new, which is the point of a baseline.

The Action then annotates and gates only findings not represented by that baseline.

## Chat and webhook digests

`offing scan --format slack`, `--format teams`, and `--format webhook` print a JSON payload to standard output. Offing only renders the payload and never sends it: the network call belongs to a step you write, so the scan itself stays offline.

- `slack` is a Slack incoming-webhook message: a fallback `text`, a header, a counts summary, and one section per finding. It fits Slack's 50-block and 3,000-character section limits.
- `teams` is a Microsoft Teams message with an Adaptive Card (version 1.4) for a Teams workflow webhook.
- `webhook` is a generic JSON payload (`schemaVersion: "offing.webhook.v1"`) with a count per severity and every finding, for any system that accepts JSON.

The chat formats list at most 20 findings, most severe first, and say how many were left out; `webhook` lists them all. Output is deterministic, with no timestamps in the chat formats.

Pipe the payload into your own webhook step. The URL lives in a secret, and the step runs only where you choose:

```yaml
- uses: actions/checkout@v7
- run: npm ci   # your project must already depend on offing
- name: Post digest to Slack
  if: always()
  run: npx --no-install offing scan . --format slack | curl -sS -X POST -H "Content-Type: application/json" --data @- "$SLACK_WEBHOOK_URL"
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
```

Use `--format teams` with a Teams workflow URL, or `--format webhook` with any endpoint, in the same way.

## Inputs and outputs

Every input is optional. The values below are the defaults used when a workflow
does not provide a `with` entry.

| Input | Default | Meaning |
| --- | --- | --- |
| `path` | `.` | Repository root or subdirectory to scan; `.` is the checked-out repository. |
| `paths` | empty | Multi-line list of directories or globs (for example `packages/*`) relative to `path`. Each match is scanned in one run; findings go into one report and SARIF, with a job-summary section per package. Empty scans only `path`. |
| `baseline` | empty | Baseline path relative to `path` (or to each matched package when `paths` is set). Empty reports every finding; a configured path that is missing fails the Action. |
| `min-support-days` | empty | Warn (medium severity) on lines whose support ends within this many days; off when empty. |
| `baseline-warn-days` | `14` | Warn when a baseline suppression expires within this many days (0 to 365). |
| `on-expired` | `resurface` | What a baseline suppression does after its `expires` day: `resurface` (its finding is reported again) or `fail` (also fail the job). |
| `fail-on-severity` | `high` | Lowest failing level: `none`, `info`, `low`, `medium`, `high`, or `critical`. |
| `mode` | `scan` | `scan` scans the checked-out tree. `diff` compares the pull request base and head SHAs from the event payload and fails only on findings the pull request introduces. See [pull request diff mode](#pull-request-diff-mode). |
| `annotations` | empty | Which findings become workflow annotations: `changed` annotates only findings on lines the pull request added or changed (the default in diff mode), `all` annotates every finding (the default in scan mode), `none` emits no annotations. Findings left out stay counted in the summary and the JSON report. |
| `report-name` | `offing-report` | Artifact name for the JSON report when `upload-report` is `true`. |
| `upload-report` | `true` | Upload the JSON report as an Actions artifact. `false` keeps the generated report only on the runner. |
| `upload-sarif` | `false` | Set to `true` to upload the findings to GitHub code scanning as SARIF. Needs `security-events: write`. |
| `upload-badge` | `false` | Generate a Shields.io endpoint JSON and a branded SVG badge, and upload both as the `offing-badge` artifact (14 days). |
| `pr-comment` | `false` | Set to `true` to post one summary comment on pull requests (counts and the top findings). Re-runs update the same comment. Needs `pull-requests: write`. |
| `agent-authors` | `Copilot, google-labs-jules[bot], devin-ai-integration[bot], chatgpt-codex-connector[bot], claude[bot]` | Comma-separated logins treated as coding agents. In diff mode, when the pull request author matches, the comment adds the **Stale choices this agent introduced** section. Set to `none` to turn it off. Matching ignores case and a leading `@`. |
| `suggest-fixes` | `false` | In diff mode, post one review whose `suggestion` blocks apply the deterministic fixes for findings on lines the pull request changed. Re-runs update the same review. Needs `pull-requests: write`; pull requests from forks are skipped. |
| `commands` | `false` | Set to `true` to answer `/offing explain` and `/offing ignore` comments when the workflow runs on `issue_comment`. Replies only to owners, members, and collaborators. Needs `pull-requests: write`. |
| `fix-pr` | `false` | Set to `true` to open or update one pull request on `offing/fixes` with every deterministic fix, and close it when nothing is left to fix. Runs only on `schedule` and `workflow_dispatch` events. Needs `contents: write` and `pull-requests: write`. See [scheduled fix pull request](#scheduled-fix-pull-request). |
| `tracking-issue` | `false` | Set to `true` in a scheduled workflow to keep one issue listing findings by end-of-life date. Re-runs update the same issue; it closes when nothing is left and reopens when findings return. Needs `issues: write`. |
| `github-token` | `${{ github.token }}` | Token used to post the comment, command reply, or fix suggestions when `pr-comment`, `commands`, or `suggest-fixes` is `true`, to open, update, or close the fix pull request when `fix-pr` is `true`, and to update the tracking issue when `tracking-issue` is `true`. |
| `attribution` | `true` | Adds one line to the job summary saying the scan was done by Offing, with a link. Set to `false` to leave it out. |

| Output | Availability | Meaning |
| --- | --- | --- |
| `report-path` | Always | Absolute runner path to the generated JSON report, whether or not `upload-report` is enabled. |
| `finding-count` | Always | Number of findings remaining after baseline comparison, encoded as a decimal string. |
| `has-new-findings` | Always | `true` when at least one finding remains after baseline comparison, `false` otherwise. In diff mode it covers the findings the pull request introduces. |
| `highest-severity` | Always | The highest remaining severity (`info`, `low`, `medium`, `high`, or `critical`), or empty when there are no findings. |
| `next-eol-date` | Always | The earliest end-of-life date among the remaining findings (`YYYY-MM-DD`), or empty when no finding carries a deadline. |
| `findings-json` | Always | The remaining findings as one compact JSON array. Each entry has `id`, `ruleId`, `severity`, `title`, `path`, and `line` and `deadline` when known. |
| `badge-path` | When `upload-badge` is `true` | Absolute runner path to `offing-badge.json`; otherwise empty. |
| `badge-svg-path` | When `upload-badge` is `true` | Absolute runner path to `offing-badge.svg`, next to the JSON; otherwise empty. |
| `sarif-path` | When `upload-sarif` is `true` | Absolute runner path to the generated SARIF file; otherwise empty. |

The job summary shows how many findings there are per severity, the ten most severe findings with their location and a link to the evidence each one cites, the age of the lifecycle data, and a warning when the data is stale. When there are more than ten findings, it says how many more there are; the JSON report artifact lists them all.

![Offing Actions job summary listing severity counts and the top lifecycle findings with evidence links](assets/screenshots/job-summary.webp)

### Branching on results

The outputs describe the findings that remain after baseline comparison, so a later step can act on them without reading the report. Every value is empty or `false` when nothing remains.

| Output | Example value | Meaning |
| --- | --- | --- |
| `has-new-findings` | `true` | `true` when at least one finding remains, `false` otherwise. |
| `highest-severity` | `critical` | The most severe remaining level, or empty when there are none. |
| `next-eol-date` | `2026-09-23` | The earliest deadline among the remaining findings, or empty when none is dated. |
| `findings-json` | `[{"id":"…","ruleId":"…","severity":"high","title":"…","path":"package.json","line":4,"deadline":"2026-09-23"}]` | The remaining findings as one compact JSON array. |

The scan step must pass for the steps after it to run, so this example sets `fail-on-severity: none` and leaves the decision to the later steps:

```yaml
- uses: velella-sh/offing@v0
  id: offing
  with:
    fail-on-severity: none
- name: Note new findings
  if: steps.offing.outputs.has-new-findings == 'true'
  run: echo "Offing found new findings; highest severity is ${{ steps.offing.outputs.highest-severity }}."
- name: Warn about the next deadline
  if: steps.offing.outputs.next-eol-date != ''
  run: echo "The next end of life is ${{ steps.offing.outputs.next-eol-date }}."
- name: List finding ids
  run: echo '${{ steps.offing.outputs.findings-json }}' | jq -r '.[].id'
```

In diff mode the same outputs cover only the findings the pull request introduces, so `findings-json` lists what the pull request added rather than the whole backlog.

### Monorepo paths

Monorepos should not need one job per package. Set `paths` to a multi-line list of directories or globs under `path`. Offing scans each match, writes one combined JSON report and SARIF, and adds one job-summary section per package. `fail-on-severity` is evaluated across all packages together.

```yaml
- uses: actions/checkout@v7
- uses: velella-sh/offing@v0
  with:
    paths: |
      packages/*
      apps/web
    fail-on-severity: high
```

Literals must exist and be directories. A glob that matches nothing fails the Action. `*` and `?` stay inside one path segment; `**` crosses segments. Diff mode ignores `paths` and compares the whole pull request checkout instead.

High and critical findings become error annotations, medium findings become warnings, and low or informational findings become notices. The gate is evaluated independently from annotation level.

### Pull request comment

Set `pr-comment: true` to get the comment shown at the top of this page: the counts per severity and the top findings, instead of reading every annotation. The same comment is updated on each re-run. The scan itself stays offline; only posting the comment calls the GitHub API.

```yaml
permissions:
  contents: read
  pull-requests: write
steps:
  - uses: actions/checkout@v6
  - uses: velella-sh/offing@v0
    with:
      pr-comment: "true"
```

Pull requests from forks get a read-only token, so the comment cannot be posted there: the Action logs a warning and the scan result is unaffected.

### Agent-authored pull requests

When `mode: diff` and the pull request author is a coding agent, the comment also carries a **Stale choices this agent introduced** section. It lists each finding the pull request introduced with its `path:line`, rule title, replacement, and evidence link, and closes with the line the agent can act on: "Replace these and push again; Offing will re-check." The comment is still the one Offing comment, updated on re-runs; a second comment is never posted.

`agent-authors` takes a comma-separated list of logins. The default covers GitHub's Copilot coding agent (`Copilot`), Jules (`google-labs-jules[bot]`), Devin (`devin-ai-integration[bot]`), OpenAI Codex cloud (`chatgpt-codex-connector[bot]`), and Claude (`claude[bot]`). Matching ignores case and a leading `@`. Set `agent-authors: none` to turn the section off, or name the logins your agents author with. The author comes from the event payload, so no extra request is made; scans stay offline.

### Comment commands

Set `commands: "true"` and run the Action on `issue_comment` so a reviewer can ask about a finding or accept it without leaving the pull request. A short workflow of its own is enough; it can sit next to the scan workflow:

```yaml
name: Offing commands

on:
  issue_comment:
    types: [created]

permissions:
  contents: read
  pull-requests: write

jobs:
  answer:
    if: github.event.issue.pull_request != null
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          ref: refs/pull/${{ github.event.issue.number }}/head
      - uses: velella-sh/offing@v0
        with:
          commands: "true"
```

`/offing explain <finding-id>` replies with the finding, its location, replacement and deadline, the affected usages, and a link to every source. Take the id from an annotation's `Finding:` line, or from `offing scan . --json`.

`/offing ignore <finding-id> <reason>` replies with a baseline entry that is ready to review and commit, for example:

```json
{ "fingerprint": "…", "ruleId": "nodejs.runtime.eol-20", "path": "package.json",
  "reason": "Upgrade tracked in PLAT-12", "created": "2026-10-29", "expires": "2027-01-27" }
```

Nothing is pushed. The reviewer adds the entry to the file named by the `baseline` input (`.offing-baseline.json` when it is empty) and commits it. The entry hides the finding until `expires`, 90 days after the reply; after that the finding is reported again, and `on-expired: fail` fails the job as well.

Comment text is untrusted input. Offing reads the first line that starts with `/offing`, parses it, and never evaluates it; file paths and ids from the comment are rendered as code, never as links. A reply is written only when the comment's `author_association` is `OWNER`, `MEMBER`, or `COLLABORATOR`; a command from anyone else, or a comment on an issue rather than a pull request, is skipped and logged as a notice. The finding comes from a local scan of the checked-out pull request head, so the scan stays offline and runs no repository code. Each reply carries a hidden marker and is updated on a re-run instead of being posted twice.

## Lifecycle tracking issue

Set `tracking-issue: true` to keep one issue that lists what ends soon, without gating a build. On `schedule` and `workflow_dispatch` runs the Action finds the issue by a hidden marker, updates it, or creates it. Findings are sorted by end-of-life date with a link to the exact file and line, and a "Changed since the last run" table names what appeared and what is gone. When a scan finds nothing, the issue closes with an explanatory body; the next run that finds a lifecycle risk reopens it.

```yaml
name: Offing lifecycle tracking
on:
  schedule:
    - cron: "0 7 * * 1" # Mondays 07:00 UTC
  workflow_dispatch:
permissions:
  contents: read
  issues: write
concurrency:
  group: offing-tracking-issue
  cancel-in-progress: false
jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: velella-sh/offing@v0.1.1
        with:
          tracking-issue: "true"
          fail-on-severity: none # the issue is the signal; do not fail the schedule
```

The marker is a hidden HTML comment, so the issue body stays readable and a re-run recognizes its own issue. The previous run's findings live in another hidden marker; that snapshot is how the next run says what changed. Do not edit or delete the markers: without them the next run creates a new issue. The scan stays offline; only updating the issue calls the GitHub API, and the job needs `issues: write`. Pull request tokens are read-only, so the input acts only on `schedule` and `workflow_dispatch` runs.

The Action looks for its issue among the 1,000 most recently updated issues. On a repository with more issue activity than that while the tracking issue is closed, it can fall outside the window and a second issue is created; delete one and the next run updates the other. GitHub caps issue bodies at 65,536 characters, so the findings table is shortened when needed while the hidden snapshot keeps tracking every finding; if even the shortened body would exceed the cap, the Action logs a warning and leaves the issue unchanged.

## Pull request diff mode

`finding-count` and the severity gate cover every finding in the checkout. On a busy repository that backlog grows, so reviewers cannot see which findings a pull request actually introduced. `mode: diff` fixes that: the Action scans the pull request base and head refs with the same engine as `offing diff`, and the gate, annotations, badge, comment, and summary count only what the pull request introduced. Findings the pull request fixes are listed in a "Fixed by this pull request" table in the summary and the pull request comment.

```yaml
steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 0   # diff mode archives the base and head SHAs from git objects, so fetch their history
  - uses: velella-sh/offing@v0
    with:
      mode: diff
```

The base and head come from the `pull_request` event payload (`pull_request.base.sha` and `pull_request.head.sha`); the comparison stays offline — both refs are unpacked with `git archive` and scanned locally. Outside a `pull_request` event, or when the payload lacks those SHAs, the Action logs a notice and runs a regular scan instead. The baseline input does not apply in diff mode: it describes accepted findings in the whole repository, not in one pull request, and the Action says so with a notice. Because the gate judges only introduced findings, a pull request that adds a deprecated package fails and one that only edits documentation passes.

Annotations on untouched files are noise, so diff mode annotates only findings on lines the pull request added or changed and counts the others in one summary line with a link to the full report. The gate, the severity counts, the badge, the comment, and the JSON report still cover every introduced finding. Set `annotations: all` to annotate every introduced finding, or `annotations: none` to emit no annotations at all. Scan mode defaults to `all`; an explicit `annotations: changed` there falls back to `all` with a notice because there is no pull request range.

### Suggested fixes

Set `suggest-fixes: true` with `mode: diff` to let a reviewer accept a fix with one click instead of reading migration notes. For findings on lines the pull request added or changed that `offing fix` can repair deterministically, the Action posts one review whose comments each contain a `suggestion` block, so GitHub's **Apply suggestion** rewrites the line. Findings without a deterministic fix get no suggestion; the scan, the gate, and the report are unchanged.

```yaml
permissions:
  contents: read
  pull-requests: write
steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 0   # diff mode archives the base and head SHAs from git objects
  - uses: velella-sh/offing@v0
    with:
      mode: diff
      suggest-fixes: "true"
```

A re-run updates the review it left instead of adding another: the review body and the comments on the same file and lines are rewritten, and comments whose suggestion no longer applies are deleted. A suggestion at a new line arrives as one more review, because GitHub does not allow adding comments to a submitted review. Pull requests from forks get a read-only token, so the Action logs a notice and posts nothing. The scan itself stays offline; only posting the review calls the GitHub API.

## End-of-life reminder issue

[`examples/lifecycle-watch.yml`](https://github.com/velella-sh/offing/blob/main/examples/lifecycle-watch.yml) is a copyable starter that reminds a team before a deadline without anyone running a scan. Copy it to `.github/workflows/lifecycle-watch.yml`. Every Monday (and on demand) it scans with `min-support-days`, then opens one issue listing each line whose support ends within `WINDOW_DAYS` (default 90). The next run updates that same issue instead of opening another, and closes it when nothing is near its deadline.

The scan stays offline; only the final step calls the GitHub API. The job needs `contents: read` and `issues: write`, and sets `fail-on-severity: none` so the schedule does not fail. Change `WINDOW_DAYS` or the cron line to taste.

## Scheduled fix pull request

Dependabot, but for end of life. Set `fix-pr: true` on a scheduled workflow and the Action keeps one pull request that contains every fix Offing can apply deterministically, the same patches `offing fix` prints. It commits them to `offing/fixes`, force-pushes the branch, and opens or updates that pull request. The body lists each fix with its exact location and the evidence it cites. When a run finds nothing left to fix, it closes the pull request instead of opening an empty one.

```yaml
name: Offing fixes

on:
  schedule:
    - cron: "0 6 * * 1" # Mondays 06:00 UTC
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: offing-fixes
  cancel-in-progress: false

jobs:
  fixes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: velella-sh/offing@v0.1.1
        with:
          fix-pr: "true"
          fail-on-severity: none
```

Every run force-pushes `offing/fixes`, and the pull request is found by its head branch rather than by title or body, so running twice updates the same pull request. A fixer that cannot apply a change exactly leaves that finding alone: the pull request contains only the patches that were applied. Review the pull request as you would any other; Offing never merges it and never touches the default branch.

`fix-pr` runs only on `schedule` and `workflow_dispatch` events. On any other event the Action logs a notice and leaves the repository alone, so a pull request from a fork, whose token is read-only, never tries to push. The scan itself stays offline: only the `git push` and the GitHub API calls that create, update, or close the pull request use the network, after the scan has finished. The job needs `contents: write` to push the branch and `pull-requests: write` to manage the pull request.

See it working on a schedule in [offing-action-sample](https://github.com/velella-sh/offing-action-sample): it keeps one fix pull request and one tracking issue current every Monday.

## Permissions and privacy

Only `contents: read` is required. Offing does not need `pull-requests: write` unless you set `pr-comment: true`, `commands: true`, or `suggest-fixes: true`; it then writes one pull request comment, command reply, or review of suggestions, each found again by a hidden marker and updated on every re-run, and needs only `pull-requests: write` for that. Offing does not send repository contents to an Offing backend. Annotations are emitted through runner workflow commands. `tracking-issue: true` needs `issues: write`; it updates one issue, also found by a hidden marker, and touches nothing else. With `fix-pr: true` it also needs `contents: write` (to push `offing/fixes`) and `pull-requests: write` (to open, update, or close the fix pull request).

The bundled scan is local and deterministic. When `upload-report` is `true`, the official `actions/upload-artifact` adapter sends `offing-report.json` to GitHub and retains it for 14 days. The report can contain repository-relative paths, matched source excerpts, dependency versions, and lifecycle evidence. Repository administrators should apply normal Actions artifact access controls or disable uploading for sensitive repositories.

Forked pull requests receive the same read-only scan behavior; no repository secrets are required.

## README badge

Set `upload-badge: true` to generate `offing-badge.json` and `offing-badge.svg` and upload the
`offing-badge` artifact, even when the severity gate fails. The `badge-path`
output lets a later step publish the same file. This is opt-in and does not grant
the Action write access or make network requests during the scan.

The badge reads `offing | clean`, or `offing | 3 high` when findings remain.
The message counts findings **after baseline comparison** and names the highest
remaining severity. It does not say a repository is risk-free: suppressed findings
are excluded, and the severity gate can pass while lower-severity findings remain.
`stale` means the lifecycle data is old (appended as `· stale` when findings remain),
and `expired` means a baseline suppression expired under `on-expired: fail`. Colors
come from the Offing palette: Verified Green for clean, muted amber for low and
medium, red for high and critical.

`offing-badge.svg` is the finished badge with the Offing mark. The
[Shields.io endpoint format](https://shields.io/badges/endpoint-badge) file,
`offing-badge.json`, holds `schemaVersion`, `label`, `message`, `color`, and
`labelColor`, for use with `img.shields.io/endpoint` when you want a different
Shields style.

Actions artifacts require authentication, so their download URLs cannot be used
as public Shields endpoints. For a public README, publish the JSON to a public
URL, such as a dedicated branch in a public repository. This example reserves
the `offing-badge` branch for the generated file; only trusted pushes to `main`
and manual runs on `main` may publish. No pull-request code gets a write token.
Use the default branch name of your repository if it is different.

```yaml
name: Offing badge
on:
  push:
    branches: [main]
  workflow_dispatch:
permissions:
  contents: write
concurrency:
  group: offing-badge
  cancel-in-progress: false
jobs:
  badge:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: velella-sh/offing@vX.Y.Z
        id: scan
        with:
          upload-badge: true
      - name: Publish aggregate badge data
        if: always() && steps.scan.outputs.badge-path != ''
        env:
          BADGE_PATH: ${{ steps.scan.outputs.badge-path }}
          BADGE_SVG_PATH: ${{ steps.scan.outputs.badge-svg-path }}
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          publish=$(mktemp -d)
          git init "$publish"
          git -C "$publish" remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.git"
          # GitHub CLI is preinstalled on ubuntu-latest.
          gh auth setup-git
          if git -C "$publish" ls-remote --exit-code --heads origin offing-badge; then
            git -C "$publish" fetch --depth=1 origin offing-badge
            git -C "$publish" checkout -b offing-badge FETCH_HEAD
          else
            git -C "$publish" checkout --orphan offing-badge
          fi
          cp "$BADGE_PATH" "$publish/offing-badge.json"
          cp "$BADGE_SVG_PATH" "$publish/offing-badge.svg"
          git -C "$publish" config user.name github-actions[bot]
          git -C "$publish" config user.email 41898282+github-actions[bot]@users.noreply.github.com
          git -C "$publish" add offing-badge.json offing-badge.svg
          if ! git -C "$publish" diff --cached --quiet; then
            git -C "$publish" commit -m "chore: update Offing badge"
            git -C "$publish" push origin HEAD:offing-badge
          fi
```

Then add this to the README, replacing `OWNER` and `REPO`:

```markdown
[![Offing lifecycle findings](https://raw.githubusercontent.com/OWNER/REPO/offing-badge/offing-badge.svg)](https://github.com/OWNER/REPO/actions)
```

Shields and GitHub cache badge images, so updates can take time to appear. The
badge describes the last published scan, not the latest commit or a guarantee of
freshness. A scan that cannot complete emits no new badge; its workflow failure
remains the authoritative status. Schedule trusted scans if you need regular
refreshes. Publishing aggregate counts makes them public; private repositories
can keep the artifact private or deliberately publish only this aggregate file.

## Code scanning

Set `upload-sarif: true` to show findings in the repository's **Security → Code scanning** tab. The Action writes the same findings as SARIF 2.1.0 and hands the file to `github/codeql-action/upload-sarif` under the category `offing`. The job needs one more permission:

![GitHub code scanning alert opened from Offing SARIF for a deprecated package, with replacement and verification steps](assets/screenshots/sarif-alert.webp)

```yaml
permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v7
  - uses: velella-sh/offing@v0.1.1
    with:
      upload-sarif: true
```

The token of a pull request from a fork is read-only, so the upload would fail there. Enable it for pushes and for pull requests from the same repository, for example `upload-sarif: ${{ github.event_name == 'push' }}`. Code scanning is free for public repositories and needs GitHub Code Security on private ones. The SARIF carries only locations and Offing's own rule text, not source content; the mapping is below.

### SARIF output

The same SARIF is available from the CLI, so other CI systems and editors can read it:

```bash
offing scan . --format sarif > offing.sarif
```

Output is deterministic: rules and results are sorted, paths are repository-relative with forward slashes on every platform, and neither the scan time nor the checkout path is written. Two scans of the same commit produce identical files.

| SARIF | Offing |
| --- | --- |
| `tool.driver.name`, `version` | `Offing` and the installed version |
| `rules[].id`, `name` | The lifecycle rule id, for example `github-actions.checkout.node20` |
| `rules[].shortDescription` | The rule title |
| `rules[].help` (`text` and `markdown`) | Replacement, deadline, migration steps, verification commands, and sources |
| `rules[].helpUri` | The first evidence source |
| `rules[].defaultConfiguration.level` | The same level mapping as `results[].level`, for the rule's severity |
| `rules[].properties.tags` | `lifecycle` and the detector id |
| `results[].ruleId`, `ruleIndex` | The finding's rule |
| `results[].level` | `critical` and `high` → `error`; `medium` → `warning`; `low` and `info` → `note` |
| `results[].message.text` | The finding summary, which names the exact reference, such as `actions/checkout@v3` |
| `results[].locations[]` | File path (`uriBaseId` `%SRCROOT%`) and `startLine` when the finding has a line |
| `results[].partialFingerprints["offingFindingId/v1"]` | The finding id, so alerts keep their identity between runs |

JSON, text, annotations, and SARIF are renderings of the same findings. A finding suppressed by a baseline is absent from all of them.

**Privacy.** SARIF contains no source code: only file paths, line numbers, and Offing's own rule text and evidence links. It is uploaded only when `upload-sarif` is `true`, and then only to GitHub code scanning in the same repository. Nothing is sent to an Offing service.

---

Source: https://velella.sh/offing/playbooks/github/

# Playbook: GitHub Actions

A start-to-finish guide for running Offing in GitHub Actions: add the Action to a pull request, read what it reports, accept what you must on purpose, and keep the gate honest over time. For a repository you check by hand, see [cli.md](cli.md). For agent-driven fixes, see [agent.md](agent.md).

## Before you start

- Confirm your workflow runs on a runner that still has the Node.js and action runtimes you use. Offing flags those too, so a workflow that installs an end-of-life runtime shows up in its own scan.
- Pick a version tag, such as `velella-sh/offing@v0.1.1`, and read the inputs table in [GITHUB_ACTION.md](../GITHUB_ACTION.md#inputs-and-outputs). Every input is optional; the defaults gate on `high` and upload the JSON report.
- Decide what the team accepts before the first run. Existing findings should go into a committed baseline, not into a gate that is switched off.
- Work on a branch. Run the Action on a pull request first, read the annotations, then make it required.

## The pull-request loop

### 1. Add the workflow

```yaml
name: Offing

on:
  pull_request:

permissions:
  contents: read

jobs:
  lifecycle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: velella-sh/offing@v0.1.1
        with:
          baseline: .offing-baseline.json
          fail-on-severity: high
```

`contents: read` is the only permission the scan needs. The scan reads the checked-out files and bundled data; it makes no network requests and sends no repository contents to an Offing service.

Pin a full commit SHA instead of a tag only when your threat model requires immutable references. A SHA pin with a trailing `# vX.Y.Z` comment is classified from that comment; a SHA without one is looked up in the bundled map, and an unknown one is reported as `unknown-sha` rather than guessed ([GITHUB_ACTION.md](../GITHUB_ACTION.md#sha-pinned-actions)).

### 2. Read the annotations

High and critical findings become error annotations on the file and line; medium findings become warnings; low and informational findings become notices. The job summary lists the counts per severity, the ten most severe findings, and the age of the lifecycle data.

A real finding from a public repository, at a pinned commit of `axios/axios`:

```text
nodejs.runtime.legacy:.github/workflows/release-branch.yml:72  critical  Node.js 22 LTS or later
```

The matrix on that line installs Node.js 12 with `actions/setup-node`. Run the same explanation locally before you change anything:

```bash
offing explain 'nodejs.runtime.legacy:.github/workflows/release-branch.yml:72' .
```

The output names the rule, the exact location, and the authoritative source. Open the source yourself. Then read the migration packet with `offing context` and make the change in the workflow, not in the scan.

Actions themselves are judged too. `offing check pkg:github/actions/setup-node@v3` reports that release as high, because it predates the action's Node.js 24 runtime, and names `actions/setup-node@v5` or later as the replacement. Bump the action, re-run the workflow, and confirm the annotation is gone.

### 3. Fix, then re-run

Change the workflow, let the project's own CI run, then confirm the rule no longer appears at that location on the pull request. Compare the rule and the path, not only the finding ID: line numbers move when a workflow is edited.

## Accepting a finding on purpose

Some findings cannot be fixed in this pull request: a matrix that a downstream consumer still tests, or a vendor action that has not shipped its replacement. Record the decision in the repository:

<!-- testable -->
```bash
offing baseline . --output .offing-baseline.json
```

Commit the file so the acceptance is reviewable. Each entry can carry an `owner`, a `reason`, and an `expires` date. Add them for every accepted finding; a suppression without an owner is one nobody will revisit.

<!-- testable -->
```bash
offing scan . --baseline .offing-baseline.json --on-expired fail
```

With `on-expired: fail`, the job fails once a suppression's `expires` day has passed, so acceptance cannot quietly become permanent. `baseline-warn-days` (default 14) puts the upcoming expiries in the job's diagnostics before that happens. Do not add a finding to the baseline that you have not read.

## Scheduled reminders

A pull-request check only reports what a change touches. A runtime that ends next quarter will not fail anyone's pull request until it is too late. The repository's [lifecycle-watch example](../../examples/lifecycle-watch.yml) runs weekly, scans with `min-support-days`, and keeps one issue up to date with every line whose support ends within the window. It needs `contents: read` and `issues: write`, and it sets `fail-on-severity: none` so the schedule itself never fails.

## Failure modes and what to do

| What goes wrong | Why | Response |
| --- | --- | --- |
| The job fails with no finding in the summary | `baseline` is set to a path that does not exist, which fails the Action on purpose | Commit the baseline file, or remove the input |
| `pr-comment` does nothing | The comment needs `pull-requests: write` and the token to post it | Add the permission, or leave `pr-comment` off and read the annotations |
| `upload-sarif` fails | Code scanning needs `security-events: write` | Add the permission, or keep `upload-sarif` at `false` |
| Results differ between a runner and a laptop | Different bundled data versions | Compare the data date in the job summary with `offing data status` locally |
| `unknown-sha` on an action pin | The SHA is not in the bundled release-tag map | Pin with a trailing `# vX.Y.Z` comment, or check the action by hand; it is not a lifecycle finding and does not gate the job |
| A new scan fails a workflow nobody touched | A runtime or action reached its end-of-life deadline | That is the point of the gate. Fix it in a pull request, or accept it in the baseline with an owner and a date |

## Privacy and permissions

- Only `contents: read` is required. Add `pull-requests: write` only for `pr-comment: true`, and `security-events: write` only for `upload-sarif: true`.
- The JSON report is uploaded as an Actions artifact for 14 days when `upload-report` is `true`. It can contain repository paths, matched source excerpts, dependency versions, and lifecycle evidence. Anyone with access to the repository's Actions artifacts can read it, so turn off `upload-report` for sensitive repositories, or restrict who can read artifacts.
- Scan output also appears in job summaries and PR comments. Read it before enabling `pr-comment` on a public repository.
- The scan runs on the code in the pull request. Offing parses repository files and never executes them, but the workflow itself runs whatever the pull request changes, so keep `pull_request_target` out of workflows that check out untrusted code.

## Checklist for a new repository

1. The workflow sets `permissions:` explicitly, with `contents: read` as the base.
2. The first run is on a pull request, and every annotation has been opened or explained.
3. Existing findings are in a committed baseline, each with an `owner`, a `reason`, and an `expires` date.
4. `on-expired: fail` is set, so an expired acceptance fails the job.
5. The scheduled reminder workflow is running, if the repository ships on a long cycle.
6. A pull request that fixes a finding shows the annotation gone, and the project's own tests pass.

---

Source: https://velella.sh/offing/ORG_ROLLOUT/

# Organization rollout

This guide takes one person from an unconfigured organization to a weekly lifecycle report for every repository in it. It is written to be followed in order:

1. Create a read-only token.
2. Add the organization-scan workflow.
3. Accept existing findings with a baseline.
4. Read the reports the workflow leaves behind.
5. Send the recurring digest to Slack or Teams.
6. Offer the per-repository starter from the organization's `.github` repository.
7. Open adoption pull requests at scale (optional).

The scan itself stays local. The organization-scan workflow lists repositories and downloads artifacts through the GitHub API; each scan checks out one repository and reads its files and Offing's bundled data, with no network access. Per-repository adoption uses one `uses:` line that calls the reusable scan workflow.

> **Version.** The reusable workflows and the `org:rollout` tool first ship in `v0.8.0`. The examples below call `@v0.8.0`. Until that tag exists, call `@main` only to try a workflow, then replace it with the release tag before relying on it.

## Before you start

You need:

- An organization owner to approve a fine-grained token, or a repository admin for the caller repository to add its secrets. The same person often fills both roles.
- One repository in the organization to host the caller workflow. A small operations or `.github` repository is a good home.
- GitHub Actions enabled in that repository.
- Optional: admin access to the Slack workspace or Teams channel that should receive the digest.
- Optional, for the local baseline and rollup commands: Node.js 22 or newer.

The caller repository is scanned like every other repository in the organization. It is not special.

## 1. Create a read-only organization token

The workflow needs a token that can list the organization's repositories and read each repository's contents. It does not need write access to anything, and no scan ever receives the token.

### Fine-grained token (recommended)

Create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new):

1. Set **Resource owner** to the organization.
2. Set **Repository access** to **All repositories**. A token scoped to selected repositories cannot list the whole organization.
3. Under **Repository permissions**, set **Contents** to **Read-only** and leave **Metadata** at its mandatory **Read-only** value.
4. Set an expiration you are willing to rotate. The workflow fails when the token expires, so put the rotation date on a calendar.
5. Create the token, approve it if the organization requires approval, and copy the value once.

### Classic token

If your organization still uses classic tokens, create one with:

| Repository visibility | Scopes |
| --- | --- |
| Private repositories included | `repo`, `read:org` |
| Public repositories only | `public_repo`, `read:org` |

`read:org` lets the token list the organization. `repo` (or `public_repo`) lets it read repository contents for the checkout.

### Store and verify it

Store the token as an Actions secret in the caller repository. `gh secret set` prompts for the value, so the token does not land in shell history:

```bash
gh secret set OFFING_ORG_TOKEN --repo your-org/your-ops-repo
```

Before relying on it, check that the token can see the repositories you expect. This prints the number of active, non-archived repositories:

```bash
GH_TOKEN=github_pat_your_token \
  gh api --paginate "/orgs/your-org/repos?per_page=100" \
  --jq '[.[] | select(.archived == false and .disabled == false)] | length'
```

A `404` usually means the token cannot see the organization; a `403` usually means the organization has not approved the token or it lacks a required scope.

If you omit the `github-token` secret, the workflow falls back to the caller's `GITHUB_TOKEN`. That works only when the caller's token can already read every repository, which is uncommon for an organization-wide list. Prefer the dedicated token.

## 2. Add the caller workflow

Add one workflow to the caller repository. It calls [`.github/workflows/org-scan.yml`](../.github/workflows/org-scan.yml), which lists the organization's repositories and scans each one in a bounded matrix through the first-party Offing Action. The Action version follows the workflow tag you call, so pinning the workflow pins the scanner.

Create `.github/workflows/offing-org-scan.yml`:

```yaml
name: Offing organization scan

on:
  schedule:
    - cron: "0 4 * * 1"
  workflow_dispatch:

permissions:
  contents: read
  # Only needed for the Slack/Teams digest. Remove it if you do not post one.
  actions: read

jobs:
  org-scan:
    uses: velella-sh/offing/.github/workflows/org-scan.yml@v0.8.0
    with:
      organization: your-org
      fail-on-severity: high
      max-jobs: 10
    secrets:
      github-token: ${{ secrets.OFFING_ORG_TOKEN }}
      slack-webhook-url: ${{ secrets.OFFING_SLACK_WEBHOOK }}   # optional
      teams-webhook-url: ${{ secrets.OFFING_TEAMS_WEBHOOK }}   # optional
```

Commit it, then run it once by hand:

```bash
gh workflow run offing-org-scan.yml --repo your-org/your-ops-repo
gh run list --repo your-org/your-ops-repo --workflow offing-org-scan.yml --limit 1
gh run watch <run-id> --repo your-org/your-ops-repo
```

The first run has three visible parts:

- **List repositories.** One job calls `GET /orgs/<org>/repos`, skips archived and disabled repositories, and prints how many it found.
- **Scan <repository>.** One matrix job per repository checks out its default branch and runs the Offing Action. Progress and annotations are per repository, so a failure names the repository.
- **Send digest.** After the matrix finishes, one job builds a rollup and posts it to the configured webhooks. It is skipped when neither webhook secret is set.

### Inputs

| Input | Default | Meaning |
| --- | --- | --- |
| `organization` | caller repository owner | The GitHub organization to scan. It must be an organization; user accounts are not supported. |
| `fail-on-severity` | `high` | Lowest severity that fails one repository's scan job: `none`, `info`, `low`, `medium`, `high`, or `critical`. |
| `max-jobs` | `10` | Maximum number of repositories scanned in parallel. Concurrency stays bounded while the matrix scales with the repository count. |

For the first inventory run, set `fail-on-severity: none`. The workflow then finishes successfully even when repositories have findings, which makes the artifacts and digest easy to inspect. Tighten it to `high` once the backlog is triaged, or move the gate to per-repository pull-request workflows with baselines (see [step 3](#3-accept-existing-findings-with-a-baseline)).

A scan job fails when a repository has findings at or above `fail-on-severity`, so the calling workflow fails if any repository crossed the gate. Matrix jobs do not cancel each other (`fail-fast: false`), so every repository is still scanned and every report is still uploaded.

### If you only want an inventory

Set `fail-on-severity: none` and leave the schedule as it is. The run is a weekly inventory: reports and the digest are produced, but no repository fails the workflow. Add per-repository pull-request workflows (see [step 3](#3-accept-existing-findings-with-a-baseline)) when you want a gate that blocks new findings.

## 3. Accept existing findings with a baseline

A baseline records findings you have reviewed and accepted. It is usually a file committed in each repository. Findings in the baseline are suppressed; findings that are not in it are reported and gated normally.

Run this in the repository whose findings you are accepting:

```bash
npx @velella/offing scan . --fail-on none
npx @velella/offing baseline . --output .offing-baseline.json
```

The second command writes one entry per current finding and keeps the file's history when it already exists, so running it again updates the file instead of starting over:

```text
Wrote 5 findings to /path/to/repository/.offing-baseline.json
No earlier baseline to compare with.
```

Review the file, then commit it:

```bash
git add .offing-baseline.json
git commit -m "chore: accept current Offing findings"
```

A scan that uses the baseline now hides exactly those findings:

```bash
npx @velella/offing scan . --baseline .offing-baseline.json --fail-on high
```

```text
Findings: 0
...
Baseline: 5 findings suppressed, 0 expiring within 14 days, 0 expired.
```

### Add an owner, a reason, and an expiry

Every entry can carry optional context. These fields never change what is suppressed, but they make the acceptance reviewable and let it expire:

```json
{
  "fingerprint": "6ca0234cda96c4bf931e7686f5a74bff85d0063cb143d25ec64136c9102343d3",
  "ruleId": "nodejs.runtime.eol-18",
  "path": "package.json",
  "owner": "platform-team",
  "reason": "Upgrade tracked in PLAT-12",
  "created": "2026-10-29",
  "expires": "2027-01-31"
}
```

`owner` and `reason` are non-empty text up to 500 characters. `created` and `expires` are `YYYY-MM-DD` calendar dates, and `expires` cannot be before `created`. Expired suppressions stop hiding their finding; a scan also warns 14 days before an expiry unless you change the window:

```bash
npx @velella/offing scan . --baseline .offing-baseline.json --baseline-warn-days 30
```

`--on-expired resurface` (the default) reports the finding again after its expiry day. `--on-expired fail` reports it and also fails the scan. See the [baseline format](GITHUB_ACTION.md#pull-request-workflow) for the full field reference.

### Wire the baseline into the per-repository workflow

The baseline only takes effect where a workflow passes it to the Action or the reusable workflow. Prefer one `uses:` line that calls the reusable workflow:

```yaml
jobs:
  lifecycle:
    uses: velella-sh/offing/.github/workflows/offing-reusable.yml@v0.8.0
    with:
      baseline: .offing-baseline.json
      fail-on-severity: high
```

Or pass the same inputs on the Action step directly:

```yaml
- uses: velella-sh/offing@v0.8.0
  with:
    baseline: .offing-baseline.json
    fail-on-severity: high
```

The organization-wide scan workflow (`org-scan.yml`) does not pass a `baseline` input: it scans each repository with the Action's defaults and reports every finding. Use it with `fail-on-severity: none` as the inventory and digest, and use the per-repository workflow above for the pull-request gate. This is also the workflow created by the adoption pull requests in [step 7](#7-open-adoption-pull-requests-at-scale); add the `baseline` line to that file when you accept its first report.

A shared baseline can be combined with the repository's own on the command line:

```bash
npx @velella/offing scan . \
  --baseline ../org-config/offing-baseline.json \
  --baseline .offing-baseline.json
```

`--baseline` is repeatable on the CLI. The Action input takes one path, so keep the repository's own file as the one the workflow reads and merge shared entries into it, or check out the shared file in the workflow and point `baseline` at that path.

## 4. Read the report artifacts

Each scan job writes a versioned JSON report and uploads it as an artifact named `offing-report-<repository>`. Artifacts are retained for 14 days.

In GitHub, open the run from **Actions → Offing organization scan**, scroll to **Artifacts**, and download the artifact for one repository. It contains `offing-report.json`. The run's job summary also shows the counts per severity, the ten most severe findings, and a link to the evidence for each one.

From a terminal, download every report from a run and merge them into one organization view:

```bash
gh run list --repo your-org/your-ops-repo --workflow offing-org-scan.yml --limit 1
gh run download <run-id> --repo your-org/your-ops-repo \
  --pattern 'offing-report-*' --dir org-reports
npx @velella/offing rollup org-reports/*/offing-report.json
```

The rollup reads the saved reports and nothing else, so it uses no network and does not touch the repositories. It prints totals, then counts grouped by repository, product, and owner:

```text
Offing rollup: 7 findings across 2 repositories

By repository:
  sample-api: 5 (2 high, 3 medium; nearest deadline 2020-02-11)
  sample-web: 2 (2 high; nearest deadline 2024-07-24)

By product:
  nodejs: 3 (3 medium) in sample-api
  github-actions: 2 (2 high) in sample-api, sample-web
  npm: 2 (2 high) in sample-api, sample-web

By owner:
  unowned: 7 (4 high, 3 medium) in sample-api, sample-web
```

The repository name comes from the artifact directory: `org-reports/offing-report-sample-api/offing-report.json` becomes `sample-api`. A repository with no matching artifact is absent, not counted as clean.

### Add owners

Create an `owners.json` that maps repository names to teams, then pass it to the rollup:

```json
{
  "sample-api": "platform",
  "sample-web": "frontend"
}
```

```bash
npx @velella/offing rollup org-reports/*/offing-report.json --owners owners.json
```

A repository missing from the file is grouped under `unowned`. This is the same grouping the Slack and Teams digest uses.

### Read the JSON directly

The report is `offing.scan.v1` (schema: [`schemas/scan.v1.schema.json`](../schemas/scan.v1.schema.json)). Each finding names its rule, severity, exact location, deadline when the source gives one, replacement, and evidence:

```json
{
  "schemaVersion": "offing.scan.v1",
  "findings": [
    {
      "ruleId": "github-actions.checkout.node20",
      "severity": "high",
      "location": { "path": ".github/workflows/ci.yml", "line": 7 },
      "deadline": "2026-09-23",
      "replacement": "actions/checkout@v5 or later",
      "sources": [{ "title": "GitHub changelog", "url": "https://github.blog/..." }]
    }
  ]
}
```

Suppressed findings are absent from the report. A scan that used a baseline adds a `suppressions` object that says how many it hid and which entries are expiring or expired.

### Optional: publish one page

The same rollup renders as a self-contained HTML page:

```bash
npx @velella/offing rollup org-reports/*/offing-report.json \
  --owners owners.json --html > org-report.html
```

[`templates/rollup/`](../templates/rollup/) packages that command as a GitHub Pages workflow. It runs after a successful organization scan, downloads the same artifacts, and publishes the page without a server. It only runs when the scan succeeds, so use `fail-on-severity: none` if you want the page even while the backlog is ungated.

### Optional: developer portals

To show the same lifecycle risk in Backstage, Grafana, Port, or Cortex — from one offline `export --format portal` catalog — see [Developer portals](PORTALS.md).

## 5. Set up the recurring digest

The schedule in [step 2](#2-add-the-caller-workflow) is the recurrence. This step connects it to a chat channel.

After the scan jobs finish, the reusable workflow downloads the run's `offing-report-*` artifacts and renders the same text as `offing rollup`. It lists the total findings across every repository by severity, repository, product, and owner, with each repository's nearest deadline. It posts even when some scan jobs failed, so a red run does not silence the weekly numbers.

Enable one or both webhooks by adding the secrets and passing them from the caller:

```yaml
jobs:
  org-scan:
    uses: velella-sh/offing/.github/workflows/org-scan.yml@v0.8.0
    with:
      organization: your-org
    secrets:
      github-token: ${{ secrets.OFFING_ORG_TOKEN }}
      slack-webhook-url: ${{ secrets.OFFING_SLACK_WEBHOOK }}
      teams-webhook-url: ${{ secrets.OFFING_TEAMS_WEBHOOK }}
```

The caller also needs `actions: read`, because the digest downloads the artifacts of its own run. Without that permission the notify job cannot read the artifacts; the scan jobs are unaffected.

If neither webhook secret is set, the notify job is skipped entirely and no outbound request is made.

### Set up the Slack webhook

1. Open [api.slack.com/apps](https://api.slack.com/apps) and create (or choose) an app for the channel that should receive digests.
2. Under **Features → Incoming Webhooks**, enable incoming webhooks and click **Add New Webhook to Workspace**.
3. Select the target channel and confirm. Slack shows a URL of the form `https://hooks.slack.com/services/T…/B…/…`.
4. In GitHub, open **Settings → Secrets and variables → Actions** in the repository that calls the org-scan workflow.
5. Create a secret named `OFFING_SLACK_WEBHOOK` and paste the webhook URL as its value. Treat the URL as a credential: anyone who has it can post to the channel.
6. Pass it to the workflow with `secrets: slack-webhook-url: ${{ secrets.OFFING_SLACK_WEBHOOK }}`.

### Set up the Teams webhook

Teams uses Workflow webhooks, not the legacy Incoming Webhook connector, which Microsoft is retiring. The Workflow webhook produces a URL compatible with Offing's Adaptive Card payload.

1. In the Teams channel that should receive digests, open **… → Workflows**.
2. Search for **Post to a channel when a webhook request is received** and select it.
3. Follow the setup wizard. Teams generates a URL of the form `https://prod-XX.westeurope.logic.azure.com/…`.
4. In GitHub, create a secret named `OFFING_TEAMS_WEBHOOK` and paste the URL.
5. Pass it to the workflow with `secrets: teams-webhook-url: ${{ secrets.OFFING_TEAMS_WEBHOOK }}`.

### Secrets table

| Secret | Required | Meaning |
| --- | --- | --- |
| `slack-webhook-url` | No | Incoming-webhook URL. When set, a Slack digest is posted after every scan. |
| `teams-webhook-url` | No | Workflow-webhook URL. When set, a Teams digest is posted after every scan. |

Both secrets are optional and independent. You can enable Slack, Teams, both, or neither.

### Test the digest

Run the workflow by hand and confirm the message arrives in the channel:

```bash
gh workflow run offing-org-scan.yml --repo your-org/your-ops-repo
```

The workflow truncates the digest to Slack's 3,000-character section limit, adding a `…truncated` marker. Keep the channel to the summary and use the artifacts or the [rollup page](#optional-publish-one-page) for the full list.

## 6. Offer the starter from the organization's `.github` repository

So each repository can add Offing from the Actions **New workflow** gallery instead of pasting YAML by hand, put the starter in the organization's [`.github` repository](https://docs.github.com/en/actions/sharing-automations/creating-workflow-templates-for-your-organization):

1. Create `your-org/.github` if it does not exist.
2. Copy both files from [`templates/workflows/`](../templates/workflows/) into that repository:

```text
workflow-templates/offing.yml
workflow-templates/offing.properties.json
```

3. Commit them on the default branch. The next time someone opens **Actions → New workflow** in a repository of the organization, **Offing lifecycle scan** appears in the list.

The starter is one job with one `uses:` line. It calls [`.github/workflows/offing-reusable.yml`](../.github/workflows/offing-reusable.yml) on pull requests, pushes to the default branch, a weekly schedule, and `workflow_dispatch`, with `contents: read` only:

```yaml
name: Offing

on:
  pull_request:
  push:
    branches: [$default-branch]
  schedule:
    - cron: "0 4 * * 1"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  lifecycle:
    uses: velella-sh/offing/.github/workflows/offing-reusable.yml@v0.8.0
```

`$default-branch` is GitHub's placeholder; it becomes the repository's real default branch when someone creates the workflow from the gallery. Until `v0.8.0` is tagged, replace `@v0.8.0` with `@main` in the copy under `workflow-templates/`, then pin the release tag before relying on it. To accept existing findings later, add `with: baseline: .offing-baseline.json` on that job (see [step 3](#3-accept-existing-findings-with-a-baseline)). Inputs, outputs, and the permission boundary are documented under [Reusable workflow](GITHUB_ACTION.md#reusable-workflow-one-uses-line).

## 7. Open adoption pull requests at scale

The organization-scan workflow covers every repository on a schedule. To put a pull-request workflow in every repository without waiting for each team to open the gallery, Offing can open the adoption pull requests for you. Offing lands best as one reviewed change per repository. The rollout tool (`tools/org-rollout.ts`) turns that into a single step: it lists the target repositories, shows exactly what it would change, and only opens pull requests when you explicitly ask for it. Nothing is ever pushed directly to a default branch, and scans stay offline: the tool's own network calls are GitHub API calls, never repository analysis.

Run it from a checkout of this repository:

```bash
npm ci
npm run org:rollout -- --org my-org                    # print the plan, change nothing
npm run org:rollout -- --org my-org --apply            # open one pull request per repository
npm run org:rollout -- --repos acme/api,acme/web       # a specific repository list instead of an org
```

`--apply` needs `GITHUB_TOKEN` or `GH_TOKEN` with write access to the target repositories. A token with read-only access can still run the dry run.

### What it does

For every target repository (non-archived, not a fork, with a default branch) it:

1. Checks whether any existing workflow under `.github/workflows/` already invokes `velella-sh/offing`. If one does, the repository is skipped, so reapplication can never stack duplicate workflows.
2. Resolves the action version to pin. Pass `--action-ref v0.8.0` for a fixed version; otherwise the tool pins the repository's latest release tag.
3. Prints the plan: each repository with `pull-request` or `skip`, the totals, and the full workflow file that would be added. **Without `--apply` this is the whole run.**
4. With `--apply`, and a token with write access, it opens one pull request per repository. The pull request creates the branch, adds `.github/workflows/offing.yml` (the workflow in [GitHub Action](GITHUB_ACTION.md)), and opens the pull request against the default branch.

The generated workflow runs the scan on pull requests, on a weekly schedule (`--schedule`, default `0 4 * * 1`), and on demand via `workflow_dispatch`. It needs no configuration: read-only permissions, no secrets, findings as annotations, and a `high` severity gate. To accept existing findings, commit the baseline from [step 3](#3-accept-existing-findings-with-a-baseline) and add the `baseline` input to the generated workflow in the same pull request:

```yaml
- uses: velella-sh/offing@v0.8.0
  with:
    baseline: .offing-baseline.json
    fail-on-severity: high
```

Without the input, the Action reports every finding even though the baseline file is committed.

### Options

| Option | Default | Meaning |
| --- | --- | --- |
| `--org <name>` | — | Target every qualifying repository of this organization. |
| `--repos <list>` | — | Comma-separated `owner/name` list instead of an organization. |
| `--apply` | off | Open the pull requests. Without it, only the plan is printed. |
| `--schedule <cron>` | `0 4 * * 1` | Cron expression for the weekly scan. |
| `--action-ref <ref>` | latest release | Action version to pin. |
| `--branch <name>` | `offing/lifecycle-scan` | Rollout branch name. A branch left behind by an earlier run is reused. |

### Design rules

- **Reviewed, never silent.** A rollout starts as a printed plan; opening pull requests is a deliberate `--apply`. Closing a pull request opts that repository out.
- **Idempotent in review.** Re-running the dry run after some merges only plans the repositories still missing the workflow.
- **Failures are reported, not hidden.** A repository that cannot take its pull request (no token, branch conflict) is listed at the end with its GitHub API error and the run exits nonzero; the rest still complete.

## Limits

GitHub Actions caps a matrix at 256 jobs, so an organization with more than 256 scannable repositories (archived and disabled repositories are skipped) needs call sites split into batches; call the workflow once per sub-organization. Archived and disabled repositories are skipped; forks and internal repositories are scanned unless the token cannot read them.

Artifacts are retained for 14 days. Download or roll up a run's reports before they expire if you need a longer history, or publish the [rollup page](#optional-publish-one-page) from a workflow that runs alongside the scan.

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| `List repositories` fails with `404` | The token cannot see the organization. Check its resource owner, repository access, and organization approval. |
| `List repositories` fails with `403` | The token is missing `contents`/`repo` or `read:org`, or the organization restricts fine-grained tokens. |
| A scan job cannot check out a repository | The token cannot read that repository's contents. Give it **All repositories**, not a selected list. |
| The digest is skipped | Neither `slack-webhook-url` nor `teams-webhook-url` was passed. |
| The digest job fails at `Download scan reports` | The caller did not grant `actions: read`. The reusable workflow cannot elevate its own permissions. |
| Committed baselines have no effect | The workflow did not pass `baseline`. Add it to the per-repository Action step. The organization scan does not pass one. |
| The workflow reports `v0.8.0` not found | The release is not tagged yet. Use `@main` to try it, then pin the release tag. |

## Privacy and permissions

| What | Where it runs | Network |
| --- | --- | --- |
| List repositories | GitHub Actions, caller repository | `GET /orgs/<org>/repos` |
| Scan one repository | GitHub Actions, checked-out repository | None. Files and bundled data only. |
| Upload reports | GitHub Actions artifacts | Normal Actions artifact storage, 14 days |
| Rollup digest | GitHub Actions, notify job | Reads local artifacts, then posts to the configured webhook |
| `offing baseline`, `offing rollup` | Your machine or CI | None. Local files only. |

Only `contents: read` is needed for the scans. Add `actions: read` for the digest. The dedicated token is used only by the list job; it is never passed to a scan. Offing does not send repository contents to an Offing service, and the report can contain repository-relative paths, matched excerpts, dependency versions, and lifecycle evidence, so apply normal artifact access controls.

---

Source: https://velella.sh/offing/GITLAB/

# GitLab

Offing ships a GitLab CI/CD component, [`templates/offing.yml`](../templates/offing.yml). It is published in the [CI/CD Catalog](https://gitlab.com/explore/catalog/velella-sh/offing). It adds one job that scans the checked-out repository, keeps the JSON report as a job artifact, and fails the pipeline at a severity gate. Its inputs mirror the [GitHub Action](GITHUB_ACTION.md): `path`, `baseline`, `baseline_warn_days`, `on_expired`, `min_support_days`, and `fail_on_severity` have the same meanings and defaults.

## Add the job

On GitLab.com, include the Catalog release. Pin the component to a plain semver Catalog version (no `v` prefix); the component's `version` input then defaults to the matching `offing` npm package:

```yaml
include:
  - component: $CI_SERVER_FQDN/velella-sh/offing/offing@0.7.1
    inputs:
      fail_on_severity: high
```

That include was verified from a clean public project: the job pulled `node:24-trixie-slim`, installed `@velella/offing@0.1.0` with `npx`, wrote `offing-report.json` and `gl-code-quality-report.json`, and passed at the default `high` gate with no findings. Set `baseline` only when you already have a baseline file committed (path relative to `path`).

On a self-managed instance, host a copy of the component and replace the project path:

```yaml
include:
  - component: $CI_SERVER_FQDN/<group>/<project>/offing@<version>
    inputs:
      fail_on_severity: high
```

## Permissions

The job needs nothing beyond the default pipeline permissions:

- It reads the files GitLab checks out for the job. It uses a shallow clone (`GIT_DEPTH: "1"`).
- It uses no access token, project or group variable, or secret, and does not call the GitLab API.
- It writes two files, kept as job artifacts for 14 days even when the gate fails: the JSON report (`offing-report.json` unless you set `report_name`) and a [Code Quality](https://docs.gitlab.com/ci/testing/code_quality/) report (`gl-code-quality-report.json` unless you set `code_quality_report_name`), which GitLab shows as findings in merge requests. The same report is available locally with `offing scan --format codequality`.
- It never edits the repository, opens a merge request, or runs a migration command.

## Network behavior

Scans make no network requests: the detectors read repository files and the lifecycle data bundled in the package. The job still needs the network twice, before the scan starts:

| When | What | Where it goes |
| --- | --- | --- |
| The runner starts the job | Pulls the `image` input (default `node:24-trixie-slim`) | Your runner's container registry |
| The job runs `npx` | Downloads `offing@<version>` and its dependencies | The npm registry your runner is configured for |

Neither request carries repository contents. Repository contents and findings stay on the runner; the report leaves it only as a GitLab job artifact.

## Self-managed GitLab

- **Hosting the component.** Put the component in a project on your instance, mirroring `templates/offing.yml`, and reference it with `$CI_SERVER_FQDN` as above. Components and `$[[ inputs.* ]]` interpolation need a GitLab version that supports CI/CD components; check your instance's release notes.
- **No access to Docker Hub.** Mirror a Node.js 22 or newer image into your own registry and pass it as `image`.
- **No access to the public npm registry.** Point npm at your internal registry or proxy, for example with an `NPM_CONFIG_REGISTRY` CI/CD variable, and make sure it serves `offing` at the pinned version.
- **Air-gapped runners.** Bake the package into the image and set `version` to match. The job's `npx --yes` call then finds it locally, and the scan itself already needs no network.
- **Lifecycle data.** The job does not run `offing data update`, so it never fetches newer rules from GitHub. To change the rules a pipeline uses, change the `version` input. See [Lifecycle data](DATA.md).

## Gate and baseline

The job exits with the gate's status after writing the report, so the report is available when the job fails. Accept existing findings with a baseline committed to the repository, and set `baseline` to its path relative to `path`; the format, expiry warnings, and `on_expired` behavior are the same as in the [GitHub Action](GITHUB_ACTION.md). See also [Privacy](PRIVACY.md).

---

Source: https://velella.sh/offing/playbooks/gitlab/

# Playbook: GitLab pipelines

A start-to-finish guide for running Offing in a GitLab pipeline: add the component, read what it reports, gate merges on severity, accept known findings with a baseline, and run it on a self-managed instance. For the component's inputs, permissions, and network behavior in full, see [GITLAB.md](../GITLAB.md). For fixing a finding by hand or with an agent, see [cli.md](cli.md) and [agent.md](agent.md).

## Before you start

- Find the GitLab version of your instance. CI/CD components and `$[[ inputs.* ]]` interpolation need a release that supports them. On GitLab.com they are available.
- The component is not in the CI/CD Catalog yet. Host a copy of `templates/offing.yml` in a GitLab project of your own, on GitLab.com or on a self-managed instance, and reference it as `$CI_SERVER_FQDN/<group>/<project>/offing@<version>`. Section 5 covers the self-managed details.
- Confirm the runner can pull a Node.js 22 or newer image and reach an npm registry that serves `offing`. The job needs both before the scan starts.
- Run the scan once from a workstation before you gate on it, so you see the findings you are about to inherit. `npx @velella/offing scan . --json` is the same scan the job runs.

## 1. Add the job

Add the component to `.gitlab-ci.yml`:

```yaml
include:
  - component: $CI_SERVER_FQDN/<group>/<project>/offing@<version>
    inputs:
      fail_on_severity: high
```

Pin `<version>` to a release. The component's `version` input decides which `offing` package the job runs, and it defaults to the version the component shipped with. Pinning the component and leaving the default in place keeps the rules you tested and the rules the pipeline uses the same. To change the rules a pipeline uses, change the version, not the data: the job does not run `offing data update`.

The job runs in the `test` stage by default. Set `stage` if your pipeline names its stages differently.

## 2. Read the result

The job writes two files and keeps them as artifacts for 14 days, even when the gate fails:

| File | Input that names it | What it is for |
| --- | --- | --- |
| `offing-report.json` | `report_name` | The full JSON report. Use it for audits and scripts. |
| `gl-code-quality-report.json` | `code_quality_report_name` | The GitLab Code Quality report. GitLab shows its findings in the merge request. |

Open the merge request's Code Quality widget first. Each finding names its rule and file. Then open the job log: the human-readable summary lists the same findings with their replacements.

To reproduce a result locally, use the same version and gate as the job:

```bash
npx --yes @velella/offing@<version> scan . --fail-on high
```

A local run and a pipeline run disagree only when the repository, the version, or the gate differs. If they disagree, compare the three before you assume a bug.

## 3. Gate the merge on severity

`fail_on_severity` is the lowest severity that fails the job. It defaults to `high`. The options are `none`, `info`, `low`, `medium`, `high`, and `critical`.

Start with the default. Move to `high` once the existing findings are either fixed or accepted in a baseline. Moving to `medium` or lower fails on findings a team may not yet have a plan for, so do it only after the backlog is clear.

When the job fails, the exit status is the gate's, and the reports are still there. Read the Code Quality widget, then pick the path:

- **Fix it by hand.** Follow [cli.md](cli.md) from the explain step.
- **Hand it to an agent.** Follow [agent.md](agent.md): one finding per branch, verified by the project's tests and a fresh scan.
- **It is wrong.** Do not work around it. Produce the report with `offing report-issue '<finding-id>' . --output issue.md` and file it.

## 4. Accept known findings with a baseline

A baseline is a file committed to the repository that lists findings you have accepted, each with an expiry date. Set `baseline` to its path relative to `path`:

```yaml
include:
  - component: $CI_SERVER_FQDN/<group>/<project>/offing@<version>
    inputs:
      baseline: .offing-baseline.json
      baseline_warn_days: "14"
      on_expired: fail
```

- `baseline_warn_days` warns when a suppression expires within that many days.
- `on_expired` decides what happens after the date. `resurface` reports the finding again. `fail` also fails the job, so an accepted risk cannot quietly stay accepted past its date.

The baseline format and expiry behavior are the same as in the [GitHub Action](../GITHUB_ACTION.md). Review every baseline change in the merge request like any other code change: a new suppression is an accepted risk, and it should carry a reason and a date a person chose.

To warn before a finding's support ends, set `min_support_days`. Leave it empty to report only what the data already marks.

## 5. Run it on a self-managed instance

Self-managed runners often cannot reach Docker Hub or the public npm registry. Work through these, in order:

1. **Host the component.** Copy `templates/offing.yml` into a project on your instance, then reference it as in step 1, with `$CI_SERVER_FQDN/<group>/<project>/offing@<version>`.
2. **Mirror the image.** Copy a Node.js 22 or newer image into your registry and set the `image` input to it.
3. **Point npm at your registry.** Set `NPM_CONFIG_REGISTRY` as a CI/CD variable so `npx` finds `offing` at the pinned version on your proxy.
4. **Or bake the package in.** On an air-gapped runner, put `offing` in the image and set `version` to match. The job's `npx --yes` call then uses the local copy. The scan itself never needed the network.

Keep the component version and the package version identical. A mismatch runs a rule set you did not choose.

## Failure modes

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| Job fails before any scan output | The runner cannot pull `image`, or `npx` cannot download the package | Mirror the image or configure the npm registry. Step 5. |
| No report artifact after a failed job | The job stopped before the scan ran, so nothing was written | Read the job log from the top. Reports exist only once the scan has run. |
| The job passes, but a `.gitlab-ci.yml` image is end-of-life | Image values in CI files are reported as unclassified, never as findings | Treat it as unknown, not safe. Check the image with `offing check` or read [COMPATIBILITY.md](../COMPATIBILITY.md). |
| A baseline entry does not suppress a finding | The `baseline` path is relative to `path`, not the repository root, or the finding's rule or location changed | Check the path in the job log. Re-run the scan to get the current finding ID. |
| A suppression fails the job after its date | `on_expired: fail` is working as designed | Fix the finding, or extend the suppression with a reason in a reviewed merge request. |

## Privacy boundaries

- The job uses no access token, project or group variable, or secret, and makes no GitLab API call. It never edits the repository or opens a merge request.
- The scan makes no network requests. The only network use is the image pull and the npm download, and neither carries repository contents.
- The reports leave the runner only as job artifacts. They name the files and lines where findings occur, so treat them as project metadata: anyone who can read the job's artifacts can read them. Check the project's visibility settings before you rely on the report staying private.
- Artifacts expire after 14 days. Download anything you need to keep.

## Check it works

Before you rely on the gate, run the job against a repository with a known finding, such as a dependency on a package or runtime that is past end of life. Then confirm two things:

- The Code Quality widget in the merge request lists that finding.
- The job's exit status matches the gate: it fails when a finding is at or above `fail_on_severity`, and passes when none is.

---

Source: https://velella.sh/offing/HOOKS/

# Hooks

Offing ships a Git pre-push hook that scans before you push, edit hooks for several agent hosts that check the files an agent just wrote, a Claude Code `PreToolUse` hook that checks packages before an agent installs them, a Cursor project rule, and a GitHub Copilot instructions file that tell the agent to check a dependency before it is added. All of them stay offline and use only the lifecycle rules bundled with Offing.

## Edit hooks

`offing hook <host>` is how an agent host asks Offing about a file it just wrote. The host sends its own hook payload as JSON on stdin; Offing runs one offline scan of the repository, keeps the findings in that file at or above the severity gate (default `medium`, or `--fail-on none` to report nothing), and answers in the protocol the host understands. A hook only prints and exits: it never edits files.

A hook must never break the agent's session. An unknown host, a malformed payload, an event that is not a file write or edit, a scan error, and a scan that takes longer than ten seconds all exit `0` with no output. `offing init --hooks-for <host>` writes the host's configuration so the host calls the command after an edit; each host has its own page, listed below.

Each host has its own page under [`docs/hooks/`](https://github.com/velella-sh/offing/tree/main/docs/hooks), so a new host adds a page and one line here:

- [Claude Code edit hook](hooks/claude-code.md)
- [Cline edit hook](hooks/cline.md)
- [Codex CLI edit hook](hooks/codex.md)
- [GitHub Copilot edit hook](hooks/copilot.md)
- [Cursor edit hook](hooks/cursor.md)
- [Devin Local edit hook](hooks/devin.md)
- [Gemini CLI edit hook](hooks/gemini.md)

## Git pre-push

`offing init --hooks` installs a Git pre-push hook that scans the repository before every push and blocks it when a finding reaches a severity you choose. It uses only local files; the scan never uses the network.

```bash
npx @velella/offing init --hooks --dry-run   # show the hook first
npx @velella/offing init --hooks             # install it
npx @velella/offing init --agents --hooks    # also add the agent instructions
```

### What the Git hook does

It runs `offing scan . --fail-on <severity> --format compact`. The default gate is `high`; choose another with `--fail-on low|medium|high|critical`. Only findings at or above the gate block the push (exit code 1). If Offing is not installed in the project, or a scan fails for another reason, the push is not blocked.

`scan --fail-on <severity|none>` works on its own too, for example in CI. Without it, `scan` exits 0 as before.

### Safe to run again

The hook holds one block between `# >>> offing pre-push >>>` and `# <<< offing pre-push <<<`. Running `init --hooks` again leaves a current block unchanged, and rewrites only that block when the gate changes. It creates `.git/hooks/pre-push` (honoring `core.hooksPath`) as an executable script.

Offing never overwrites a hook it did not write. If `pre-push` already exists without the block, the command stops and prints the line to add to it yourself.

### Husky and Lefthook

When a `.husky/` folder or a `lefthook.yml` exists, that tool owns the hooks, so Offing writes nothing and prints what to add:

```bash
# .husky/pre-push
npx --no-install offing scan . --fail-on high --format compact
```

```yaml
# lefthook.yml
pre-push:
  commands:
    offing:
      run: npx --no-install offing scan . --fail-on high --format compact
```

### The pre-commit framework

Teams that use [pre-commit](https://pre-commit.com) add Offing with three lines of config. Pin `rev` to a release tag so everyone runs the same scanner:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/velella-sh/offing
    rev: v0.1.0
    hooks:
      - id: offing
```

The repository defines two hooks in `.pre-commit-hooks.yaml`, both `language: node`:

| Hook                          | Runs                                                                       |
| ----------------------------- | -------------------------------------------------------------------------- |
| `offing`                   | On every commit.                                                           |
| `offing-changed-manifests` | Only when a manifest, lockfile, or CI workflow file is part of the commit. |

Both run `offing scan . --fail-on high --format compact`, so a commit is blocked by a `high` or `critical` finding. The scan reads the whole repository, because a finding depends on more than the staged files, and it stays offline. To change the gate, override `entry` in your config:

```yaml
hooks:
  - id: offing-changed-manifests
    entry: offing scan . --fail-on critical --format compact
```

Use `SKIP=offing git commit` to skip only Offing, or `git commit --no-verify` to skip every hook.

### Bypass the Git hook

```bash
git push --no-verify          # skip every hook for this push
OFFING_SKIP=1 git push     # skip only Offing
```

To remove the hook, delete the marked block (or the file, if it holds only that block).

### One setup for every repository

`offing init --personal` protects every repository on your machine. It writes `~/.config/offing/config.json` (honoring `XDG_CONFIG_HOME`) and a pre-push hook in `~/.config/offing/git-hooks/`, then runs `git config --global core.hooksPath` to point Git at it.

```bash
npx @velella/offing init --personal --dry-run   # show what would be written
npx @velella/offing init --personal             # ask, then write
npx @velella/offing init --personal --yes       # confirm without asking
```

It asks before writing anything; without a terminal it needs `--yes`. `--fail-on <severity>` sets the gate (default `high`). Running it again changes nothing when the setup is current.

A global hooks path replaces each repository's own `.git/hooks`, so the personal hook runs the repository's own `pre-push` afterwards, if it has one. Offing stops without changes when Git already uses a different global hooks path, or when the hook file there is not its own. Bypass and removal work as above; to remove it, run `git config --global --unset core.hooksPath`.

## Claude Code pre-install

The Claude Code hook runs before Bash tool calls. When the command is an `npm`, `pnpm`, `yarn`, `pip`, or `uv` install that names packages, each package is checked with `offing check` (in parallel). If Offing's lifecycle rules mark it as deprecated or end-of-life, the install is denied and Claude sees the reason, replacement, and evidence. Installs with no package arguments (for example `npm install` or `pip install -r requirements.txt`), packages with no rule, check failures, and check timeouts do not block — a timeout fails open so the install can proceed.

This is a best-effort guardrail, not a security boundary. The hook inspects the top-level Bash command and splits on `&&`, `||`, `;`, `|`, `&`, and newlines; nested invocations such as `bash -c "npm i request"` are not inspected.

### Install

1. Copy the hook script into the project:

```bash
mkdir -p .claude/hooks
cp integrations/claude-code/pre-install-guard.mjs .claude/hooks/
```

From a clone of this repository the path above works as written. From a release checkout, take the same file from the tree at that tag.

2. Merge the PreToolUse entry from `integrations/claude-code/hooks.json` into `.claude/settings.json` (or `~/.claude/settings.json` for every project):

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-install-guard.mjs\"",
            "timeout": 60
          }
        ]
      }
    ]
  }
}
```

The hook pins `npx --yes @velella/offing@<version>` to the same release as this repository. The first run may download that package from the network; once it is cached, each check and the lifecycle scan itself stay offline. Set `OFFING_CHECK_COMMAND` to another Offing command when you want a local build, for example a JSON array of argv: `["node","/path/to/dist/src/cli.js"]`.

### Opt out

```bash
OFFING_SKIP=1            # skip only this Offing hook for the session
OFFING_SKIP=true         # same
```

Only the values `1` and `true` skip the hook (`OFFING_SKIP=0` does not). Or set `"disableAllHooks": true` in `.claude/settings.json` (or pass `--settings '{"disableAllHooks": true}'` for one run) to turn off every Claude Code hook, including this one. To remove the hook permanently, delete its entry from settings and the copied script under `.claude/hooks/`.

## Cursor rules

Cursor reads project rules from `.cursor/rules/`, and a rule with `alwaysApply: true` is included in every chat. Offing ships the rule in two places, byte for byte identical, kept in sync by a test in this repository: `integrations/cursor/offing.mdc` for the install below, and `examples/agents/cursor/.cursor/rules/offing.mdc` in the complete host example verified in Cursor 3.25.9 on macOS (see that README for what the host actually did).

The rule is an instruction, not an enforcement point: nothing blocks an edit the way the Claude Code hook can. The check itself stays offline, whether it goes through MCP or the CLI as below; only a first uncached `npx` run reaches the network to fetch the pinned package.

### Install

1. Copy the rule into the project from a clone of this repository (from a release checkout, take the same file from the tree at that tag):

```bash
mkdir -p .cursor/rules
cp integrations/cursor/offing.mdc .cursor/rules/
```

Cursor reads only rules with the `.mdc` extension, so the extension is not optional. `offing setup` writes the same text into an existing `.cursor/rules/offing.mdc` when it detects a Cursor configuration; it asks before touching a file it did not write.

2. To have the agent call the MCP tool, follow `examples/agents/cursor/README.md` to add the `offing` server to `.cursor/mcp.json` and enable it in Cursor. Without MCP the rule says what to run instead: `npx @velella/offing check <purl>`.

### What the rule does

Before Cursor's agent adds a package, runtime, or GitHub Action, or picks one to replace another, it calls `check_dependency` with a Package URL such as `pkg:npm/request@2.88.2` or `pkg:github/actions/checkout@v4`. When the status is `affected`, it prefers the replacement the finding names and cites the evidence links; `version-dependent` means it checks again with the exact version it intends to use, and `no-data` means Offing has no rule for that package, not that it is safe. The rule tells the agent not to use Offing for security audits or for routine upgrades the project already uses.

## GitHub Copilot instructions

Copilot Chat and the Copilot coding agent read `.github/copilot-instructions.md` from the repository root and include it in every session. Offing ships the file in two places, byte for byte identical, kept in sync by a test in this repository: `integrations/copilot/copilot-instructions.md` for the install below, and `examples/agents/copilot/.github/copilot-instructions.md` in the complete host example — that example's text is what was already checked in Copilot Chat in Agent mode (VS Code 1.142.0 on macOS, 2026-10-19; see that README for what the agent did). The Copilot coding agent's MCP path has not been checked in the host yet, and the example README says so.

The file is an instruction, not an enforcement point: nothing blocks an edit the way the Claude Code hook can. The check itself stays offline, whether it goes through MCP or the CLI as below; only a first uncached `npx` run reaches the network to fetch the pinned package.

### Install

1. Copy the instructions into the project from a clone of this repository (from a release checkout, take the same file from the tree at that tag). The target name is fixed: Copilot reads only `.github/copilot-instructions.md`.

```bash
mkdir -p .github
cp integrations/copilot/copilot-instructions.md .github/copilot-instructions.md
```

If the project already has a Copilot instructions file, run `offing setup` instead of copying over it: when it detects a Copilot configuration it adds the Offing section to the existing `.github/copilot-instructions.md`, keeps everything else byte for byte, and asks before touching a file it did not write.

2. To have Copilot call the MCP tool, follow `examples/agents/copilot/README.md`: add the `offing` server to `.vscode/mcp.json` for Copilot Chat, or paste `coding-agent-mcp.json` under the repository's Copilot coding agent settings. Without MCP the instructions say what to run instead: `npx @velella/offing check <purl>`.

### What the instructions do

Before Copilot's agent adds a package, runtime, or GitHub Action, or picks one to replace another, it calls `check_dependency` with a Package URL such as `pkg:npm/request@2.88.2` or `pkg:github/actions/checkout@v4`. When the status is `affected`, it prefers the replacement the finding names and cites the evidence links; `version-dependent` means it checks again with the exact version it intends to use, and `no-data` means Offing has no rule for that package, not that it is safe. The instructions tell the agent not to use Offing for security audits or for routine upgrades the project already uses.

## A digest for your personal projects

`offing watch` re-scans the projects you register and prints only what is new since the last digest, so a new end-of-life date shows up once.

```bash
npx @velella/offing watch add ~/code/my-app     # register a project
npx @velella/offing watch list                  # show registered projects
npx @velella/offing watch                       # re-scan and print what changed
npx @velella/offing watch --weekly              # do nothing unless a week has passed since the last digest
npx @velella/offing watch remove ~/code/my-app  # stop watching
```

The project list and what each digest already reported live in `~/.config/offing/watch.json` (honoring `XDG_CONFIG_HOME`). A finding is reported again only when its deadline changes. A project that cannot be scanned is named in the digest and keeps its history. Scans stay offline.

For a weekly reminder, run it from cron or a login script, for example `0 9 * * 1 npx @velella/offing watch --weekly`. `--json` prints an `offing.watch.v1` document.

---

Source: https://velella.sh/offing/CAPABILITIES/

# Capability manifest and auto-discovery contract

Offing publishes one deterministic capability manifest for humans, agents, and
integrations:

```bash
offing capabilities --json
```

The output uses the `offing.capabilities.v1` contract. Its JSON Schema is
[`schemas/capabilities.v1.schema.json`](../schemas/capabilities.v1.schema.json),
and a complete committed example is
[`examples/capabilities.json`](../examples/capabilities.json).

## What the manifest describes

- the Offing package and product version;
- supported, experimental, and unsupported capabilities;
- supported detector ecosystems and their maturity;
- CLI, MCP, Skill, plugin, and CI surfaces and their entry points;
- the shared capability identifiers available through each surface; and
- compatibility rules for consumers reading newer manifests.

## Detector maturity

Each ecosystem carries a `maturity` field next to its existing `status`:

| `maturity` | Shown in the docs as | What it promises users |
| --- | --- | --- |
| `experimental` | Experimental | The detector runs and is usable. Findings, rule ids, and unclassified output may change between releases without notice. |
| `beta` | Beta | Findings were measured against independent ground truth. Rule and finding ids are listed in the changelog when they change. |
| `stable` | Supported | The same promise as beta on a larger and more varied corpus, as part of the documented product contract. |

`maturity` is the detector's `level` in
[`benchmarks/thresholds.json`](../benchmarks/thresholds.json), which is the single
source of truth for [decision 0013](decisions/0013-detector-maturity.md). It is not
a second, independent judgment.

An ecosystem's `maturity` is the lowest level among the detectors listed in its
`detectorIds`. When several detectors serve one ecosystem, the ecosystem is only as
mature as its least mature detector. Today `nodejs` and `npm` both list the `npm`
detector, so both take its level. A contract test fails when the manifest disagrees
with `benchmarks/thresholds.json`.

The existing `status` field keeps its meaning and is not replaced: it says whether
the ecosystem is a supported product surface, while `maturity` records the evidence
level of the detectors behind it. A reader that ignores unknown fields can keep
using `status` exactly as before; `maturity` is an additive optional field in the
v1 manifest.

Capability identifiers describe behavior, not transport. For example,
`repository.scan` is the same capability when reached through the CLI, local MCP
server, Agent Skill, experimental host plugin, or CI. Integrations should compare
identifiers rather than infer behavior from command or tool names.

## Forward compatibility

Consumers of a v1 manifest must follow the compatibility object included in the
document:

1. Ignore fields they do not understand within schema major version 1.
2. Ignore unknown capability and surface identifiers rather than failing the whole
   manifest.
3. Treat any unlisted capability or ecosystem as unsupported. Absence never means
   experimental or supported.
4. Reject an unknown schema major version until the consumer explicitly supports
   it.
5. Use each entry's `status`; do not promote `experimental` or `unsupported`
   behavior based on a matching entry-point name.

New optional fields, identifiers, and surfaces using the defined statuses can be
added in a compatible v1 minor manifest update. Removing or redefining an existing
identifier, changing required field meaning or status vocabulary, or weakening the
rules above requires a new schema major version.

## JSON output schemas and policy for adding fields

Every command supporting `--json` (or `--format json`) produces output that strictly conforms
to its published JSON Schema in `schemas/*.v1.schema.json` (such as `scan.v1.schema.json`,
`check.v1.schema.json`, `finding.v1.schema.json`, `context.v1.schema.json`,
`doctor.v1.schema.json`, and `data-status.v1.schema.json`).

Because scripts, agents, and CI automations depend on exact JSON structures,
Offing locks all published schemas with strict contract tests:

1. **Strict property validation:** Output schemas enforce `additionalProperties: false`
   across all object definitions. CLI output must not contain properties undeclared in the schema.
2. **Deliberate schema updates:** Adding a field to any `--json` output is never done
   implicitly. It requires an explicit, reviewed update to the relevant JSON Schema under
   `schemas/`, defining the property's type, constraints, and intent.
3. **Additive changes in v1:** New optional fields can be introduced in the current `v1`
   major schema release without breaking backward-compatible consumers.
4. **Breaking changes require a schema bump:** Removing existing properties, renaming
   fields, or altering requiredness / types requires a new schema major version (such as `v2`).
5. **Contract test enforcement:** Snapshot tests in `tests/schema-snapshots.test.ts`
   validate real execution output for every command against its schema and assert that any
   undeclared property triggers schema validation failure.

## Stability and privacy

The command reads a packaged constant and performs no repository scan, network
request, telemetry, or configuration write. Identical Offing versions produce
byte-for-byte identical JSON output. The package's contract tests validate both the
CLI output and committed example against the public JSON Schema and ensure every
surface references registered capability identifiers.

## Exit codes and error codes

Every CLI failure belongs to one class. The class decides the exit code, and with
`--json` (or `--format json`) the same class is written to stdout as an
`offing.error.v1` document, so an agent can branch without parsing messages.

| Class (`error.code`) | Exit code | Meaning |
| --- | --- | --- |
| *(none)* | 0 | The command succeeded. |
| `policy` | 1 | A gate you configured failed: `check` found an affected dependency at or above `--fail-on`, `doctor` reported a failed check, or `--on-expired fail` met an expired suppression. |
| `usage` | 2 | The command line is wrong: unknown command, flag, or value, or a missing argument. |
| `data` | 3 | The input is well formed but the data is not there: a finding ID that was not found, a pinned data version that is not available, or a data update that was refused. |
| `parse` | 4 | An input could not be parsed: an invalid Package URL, an unreadable or unsupported baseline, or an `AGENTS.md` section that is damaged. |
| `internal` | 5 | Offing failed unexpectedly. This is a bug; please report it. |

```json
{
  "schemaVersion": "offing.error.v1",
  "error": {
    "code": "usage",
    "reason": "unknown-command",
    "exitCode": 2,
    "message": "Unknown command: frobnicate"
  }
}
```

Each failure also carries one stable reason code, written as `error.reason` in the error document.

| Reason (`error.reason`) | Class | Raised when |
| --- | --- | --- |
| `policy-failed` | `policy` | A configured gate failed. No error document is written. |
| `invalid-argument` | `usage` | A flag, value, or operand is wrong or missing. |
| `invalid-config` | `usage` | The repository configuration file cannot be read or is invalid. |
| `invalid-data-version` | `usage` | `--data-version` is not a data version. |
| `unknown-command` | `usage` | The command name is not one Offing has. |
| `scaffold-failed` | `usage` | `new-rule` or `new-detector` could not create its files: an invalid id, a taken name, an existing file, or no contributor checkout. |
| `finding-not-found` | `data` | A finding ID matches no finding in the scan. |
| `finding-not-observed` | `data` | A finding ID was not observed earlier in this MCP session. |
| `data-unavailable` | `data` | A pinned data version or bundle is not available or does not verify. |
| `data-update-failed` | `data` | `offing data update` could not finish. |
| `invalid-purl` | `parse` | A Package URL is invalid. |
| `invalid-agent-file` | `parse` | An `AGENTS.md` section is damaged. |
| `invalid-sbom` | `parse` | An SBOM is not valid CycloneDX or SPDX. |
| `invalid-input` | `parse` | Another input could not be parsed. |
| `scan-memory-exceeded` | `internal` | The scan reached its heap limit. |
| `internal` | `internal` | Offing failed unexpectedly. |

Reason codes are stable: one is never renamed or moved to another class. The source is `ERROR_CODES` in `src/offing-error.ts`.

The message is also written to stderr in every mode. A `policy` failure is a
verdict on a result that was already printed, so stdout stays that single result
document and no error document is added. The set of classes and their exit codes
is stable; new classes would be added with new numbers, never by renumbering.

---

Source: https://velella.sh/offing/MIGRATION_PACKETS/

# Migration packets

`offing context <finding-id>` converts one scan finding into a portable plan for a human or coding agent. Add `--json` for the versioned `offing.context.v1` representation.

```bash
npx @velella/offing scan . --json
npx @velella/offing context '<finding-id>' . --json
```

## Packet contents

- The complete lifecycle finding and authoritative sources.
- The declaration file plus exact import, call, and configuration usages.
- Rule-specific behavioral and compatibility constraints.
- A warning when the replacement needs a newer Node.js or Python than the repository pins in `.nvmrc`, `.node-version`, `.python-version`, or `.tool-versions`.
- Ordered migration steps resolved to declaration, usage, or all affected paths.
- Suggested ecosystem verification commands and a final Offing re-scan.

Built-in registry rules carry reviewed migration guidance next to their lifecycle evidence. This keeps the scan engine and CLI independent of ecosystem-specific migration knowledge. External detectors can provide the same optional guidance through the detector SDK; otherwise Offing emits a conservative generic packet.

## Safety and determinism

Offing generates context but never edits files or executes verification commands. Packet generation is local, deterministic for a scan result, and does not require an LLM or network access.

The runtime validator checks more than field types: packet sources and usages must equal the finding evidence, affected files must be derived from those locations, step IDs and commands must be unique, and every step path must stay inside the affected-file set. The JSON contract is published at `schemas/context.v1.schema.json`.

Suggested commands may require project-specific setup and should be reviewed before execution. A migration is complete only after the relevant repository tests pass and a fresh Offing scan no longer reports the finding.

---

Source: https://velella.sh/offing/PLAN/

# Migration plans

`offing plan` turns a scan into waves of independent migration tasks. Each task names the files it is expected to edit (its touch set), a suggested branch, and the finding to migrate. Tasks in the same wave never share a touched path, so a host can start them as parallel agent sessions without two agents editing the same file.

```bash
# From a clone of Offing:
npm ci
npm run build
demo="$(node dist/tools/examples.js demo)"
npx @velella/offing plan "$demo"
npx @velella/offing plan "$demo" --json
npx @velella/offing plan "$demo" --wave 0
```

The JSON form is the versioned `offing.plan.v1` document. The local MCP tool `plan_migrations` returns the same object. Offing builds the plan and stops: it does not create branches, worktrees, or agent sessions, and it never runs a migration command.

## Touch sets

A task's touch set is the repository-relative paths a migration for that finding is expected to change: the finding's declaration file, every usage the scan recorded, and — for a dependency finding — the lockfile that resolves the same manifest. Two findings that share a lockfile therefore conflict, even when their declaration lines differ.

## Waves

Waves are a greedy colouring of those touch sets. Tasks are ordered by severity (highest first) then id; each task joins the first wave that does not already hold a conflicting path, or starts a new wave when every existing wave conflicts. Waves run in ascending index order. Inside one wave the tasks are independent, so a coordinating host can hand them out at the same time.

## Dispatch without Offing running anything

The example at [`examples/plan-dispatch/dispatch.mjs`](../examples/plan-dispatch/dispatch.mjs) reads `offing plan --json` from stdin and, for each task, prints a `git worktree add` command plus the name of the `migrate-finding` prompt. It prints only; it never runs a command.

```bash
npm ci
npm run build
npm run --silent example -- demo plan --json | node examples/plan-dispatch/dispatch.mjs
```

A host that wants parallel sessions creates each printed worktree itself, then runs the `migrate-finding` prompt in that tree with the task's finding id. See [Local MCP server](MCP.md) for the prompt and [Migration packets](MIGRATION_PACKETS.md) for the context each session receives.

---

Source: https://velella.sh/offing/UPGRADE_CHECK/

# Upgrade check

`offing upgrade-check --to <runtime@version> [path] [--json]` answers, offline and from files already in the repository, whether a project can move to a target runtime. It lists each blocker, warning, and unknown with the exact lockfile or manifest entry behind it. Agents get the same answer through the `check_upgrade` MCP tool.

```bash
offing upgrade-check --to php@8.4 .
offing upgrade-check --to nodejs@22 . --json
```

The text output starts with the verdict, then one line per issue:

```text
php@8.4: blocked (1 blockers, 0 warnings, 0 unknown)
composer.lock:9  acme/http-client@2.1.0  acme/http-client@2.1.0 requires php ^7.4, which excludes PHP 8.4.  [lockfile: require.php: ^7.4]
```

The JSON output is an `offing.upgrade.v1` document that conforms to [`schemas/upgrade.v1.schema.json`](../schemas/upgrade.v1.schema.json). Exit codes: `1` when the verdict is `blocked`, `0` for `ready` and `unknown`, `2` for bad input.

An analyzer only runs when the repository has the files it reads. Each issue names its analyzer, its level (`blocker`, `warning`, or `unknown`), the affected subject, the path and line, and the evidence value exactly as written.

- `blocker`: the project will not install or run on the target.
- `warning`: it works but is deprecated on the target.
- `unknown`: the evidence needed to judge it is missing.

## What it cannot know

- **Native extensions and build-time requirements.** A package may fail to build on the target for reasons its metadata does not state.
- **Packages without declared support ranges.** If a package never declares which runtime it supports, the analyzer reports `unknown` or nothing, never `ready` by assumption.
- **Code paths outside the source.** Dynamic loading, `eval`, generated code, and behavior that only appears at runtime are not visible here.
- **Your CI images and operating system.** The runtime inside a container image or on a runner is not part of this check.
- **Unresolved dependencies.** When a lockfile does not record a support range for a package, no analyzer can judge that package.
- **Anything at install time.** Offing never runs a package manager, Compiler, or test suite, and no scan uses the network.

An `unknown` verdict means Offing found no evidence for that runtime in this repository. It is not a statement that the upgrade is safe.

The worked commands below read the examples under `examples/upgrade/`. Their manifests and lockfiles are committed with scanner-neutral names ([decision 0027](decisions/0027-fixtures-invisible-to-scanners.md)), so `dist/tools/examples.js` copies an example to a temporary directory, restores the real names there, and runs the command inside it. Run `npm run build` first; nothing is written to the repository.

## Composer

The Composer analyzer (`composer-lock`) runs for `php` targets when `composer.lock` exists.

**Files and fields**

- `composer.lock` `packages[*].require.php` — a `blocker`.
- `composer.lock` `packages-dev[*].require.php` — a `warning`.
- `composer.lock` top-level `platform.php` — a `blocker`. This is the platform requirement the lockfile was resolved against.
- `composer.lock` top-level `platform-overrides.php` — a `blocker`.
- `composer.json` `require.php` — a `blocker`, with evidence kind `manifest`.

Each issue carries the constraint exactly as written (for example `^7.4` or `>=8.1 <8.5`) and the line of the field it came from. Package subjects are `<name>@<version>`; platform subjects are `platform.php` and `platform-overrides.php`; the project's own constraint uses the subject `composer.json`.

**Version syntax**

The matcher understands Composer's constraint syntax:

- caret ranges: `^1.2.3`, `^0.3`, `^0.0.3`
- tilde ranges: `~1.2`, `~8.4.0`
- comparisons: `>=`, `>`, `<=`, `<`, `!=`, `<>`, `==`, `=`
- wildcards: `*`, `1.*`, `1.0.x`
- hyphen ranges: `1.0 - 2.0`
- OR: `||` and `|`
- AND: space- or comma-joined terms, such as `>=8.1 <8.5` or `>=8.1, <8.5`
- pre-release suffixes: `8.4.0RC1`, `8.4.0-beta1`

A target written as a release line (`8.4`) is tested as both `8.4.0` and `8.4.99`, so an upper bound written as `<8.5` is not mistaken for a blocker. A target written with three or more parts (`8.4.0`) is tested as written.

**What it reports as `unknown`**

- A `require.php` value that is not a constraint this matcher understands, such as a truncated OR (`^8.4 ||`) or a value containing an unevaluated `${...}` expression.

A missing `require.php`, a `*` constraint, or a constraint that includes the target produces no issue. Composer itself is never run, and the lockfile is parsed as untrusted JSON.

## Go modules and vendored requirements

Analyzer id `go-modules`; runtime `go`. It applies when the repository root has a `go.mod`.

**Files and fields it reads**

- `go.mod`: the `go` directive and its line.
- `go.work`: the `go` directive and its line, when the workspace file is in the repository root.
- `vendor/modules.txt`: every `# <module> <version>` header and the `## explicit; go <version>` (or `## go <version>`) annotation that follows it. Package lines are ignored.
- The bundled `registry/go.json` rules for `pkg:generic/golang`.

**Version syntax it understands**

Release numbers as Go writes them: `1.23`, `1.23.0`, and a leading `go` (`go1.23.0`) are accepted and compared part by part. A target that is not a release number, such as `nightly`, is reported as `unknown`; it is never compared.

**What it reports**

- `blocker`, `manifest`: the target is below the `go` directive of `go.mod` or `go.work`. Since Go 1.21 the `go` line is a required minimum, not advice: a Go toolchain refuses a module that declares a newer Go version. The evidence is the directive value as written, at its line.
- `blocker`, `lockfile`: the target is below the `go` version `go mod vendor` recorded for a dependency in `vendor/modules.txt`. The subject is `<module>@<version>` and the evidence is the annotation line exactly as written.
- `warning`, `rule`: the target itself matches a bundled lifecycle rule for Go, so it is deprecated or end-of-support. The evidence is the rule id.
- `unknown`: `vendor/modules.txt` is absent, or records no `go` version. Dependencies' Go requirements are not in the repository without vendoring, so Offing reports `unknown` for them instead of assuming they are compatible. It does not run `go mod tidy` or any Go command to find out.

**Sources**

- [Go Modules Reference: `go` directive](https://go.dev/ref/mod#go-mod-file-go): the `go` line is a minimum required Go version since Go 1.21, and must be greater than or equal to the `go` line of every dependency.
- [Go Modules Reference: `go.work` files](https://go.dev/ref/mod#go-work-file-go): the workspace `go` directive names the toolchain version the workspace is written for.
- [Go Modules Reference: vendoring](https://go.dev/ref/mod#vendoring): `go mod vendor` writes `vendor/modules.txt` and records the `go` version from each dependency's `go.mod` since Go 1.17.
- [Go toolchains](https://go.dev/doc/toolchain): how the `go` directive selects a toolchain.

## Dart and Flutter

Applies when `pubspec.lock` exists. Runtimes: `dart` and `flutter`.

| File | Field | What it means |
| --- | --- | --- |
| `pubspec.lock` | `sdks.dart` | The Dart SDK bound shared by every resolved package: the intersection of their individual bounds. |
| `pubspec.lock` | `sdks.flutter` | The Flutter SDK bound shared by every resolved package. |
| `pubspec.yaml` | `environment.sdk` | The Dart SDK bound the project itself declares. |
| `pubspec.yaml` | `environment.flutter` | The Flutter SDK bound the project itself declares. |

A `dart@x` target is checked against the Dart bounds and a `flutter@x` target against the Flutter bounds; the other runtime's bounds are not consulted. A target outside a `pubspec.lock` bound is a `blocker` with subject `resolved package set` and `kind: "lockfile"`: the resolved set would not install. A target outside a `pubspec.yaml` bound is a `blocker` with subject `environment.sdk` or `environment.flutter` and `kind: "manifest"`. When neither file records a bound for the target runtime, one `unknown` issue is reported; it names the absent `sdks` key as evidence.

A target with fewer than three components is checked as `x.0.0` or `x.y.0`, so `dart@3.5` is checked as `3.5.0`.

Version syntax: a constraint is `any` or one or more space-joined terms, each `^`, `>=`, `<=`, `>`, `<`, or a bare version followed by `x.y.z` and an optional pre-release or build suffix. Caret follows pub's rules: `^1.2.3` means `>=1.2.3 <2.0.0`, `^0.2.3` means `>=0.2.3 <0.3.0`, and `^0.0.3` means `>=0.0.3 <0.0.4`. A bound the parser cannot read (a template, `||` range, or missing components) is treated as missing evidence, so the answer is `unknown` rather than `ready`.

The parsers are the ones the Dart detector uses: `src/detectors/dart/parse-pubspec-lock.ts` and `parse-pubspec.ts`.

```bash
node dist/tools/examples.js upgrade/dart-sdk upgrade-check --to dart@3.5
```

```text
blocked: dart@3.5 (1 blocker, 0 warnings, 0 unknown)
pubspec.lock:12  resolved package set  The resolved package set requires Dart >=3.6.0 <4.0.0, which excludes 3.5.0.  [lockfile >=3.6.0 <4.0.0]
```

## npm lockfile

Runtime: `nodejs`. Applies when `package-lock.json` or `npm-shrinkwrap.json` exists with `lockfileVersion` 2 or 3. A version 1 lockfile is reported as one `unknown` issue because it does not record package `engines`.

- Files read: `package-lock.json` and `npm-shrinkwrap.json`. Each issue names the file it came from.
- Fields read: `lockfileVersion`; for each `packages["node_modules/..."]` entry, `version`, `engines.node`, `dev`, and `devOptional`.
- Version syntax: semver ranges in `engines.node`, tested with `semver.satisfies` and `includePrerelease: false`. A bare target major such as `22` is tested as `22.0.0`; the bundled lifecycle data does not list per-minor Node.js releases.
- Levels: `blocker` for a production dependency whose range excludes the target; `warning` for an entry marked `dev: true` or `devOptional: true`; `unknown` for an `engines.node` value that is not a valid semver range.
- Evidence: `engines.node: <range as written>`, at the line of the `engines` key.
- Deduplication: identical name, version, and range across nested paths keep the first path.

```bash
node dist/tools/examples.js upgrade/npm-lock upgrade-check --to nodejs@22
```

```text
nodejs@22: blocked (1 blockers, 0 warnings, 0 unknown)
package-lock.json:16  sharp@0.30.7  sharp@0.30.7 declares engines.node ">=14.0.0 <17", which excludes Node.js 22.  [lockfile: engines.node: >=14.0.0 <17]
```

## pnpm lockfile

Runtime: `nodejs`. Applies when `pnpm-lock.yaml` exists with `lockfileVersion` 6.x or 9.x.

- Files read: `pnpm-lock.yaml`. In 6.x, `packages` entries carry `engines`, `dev`, and `devOptional`. In 9.x, `engines` lives under `packages`, while the dev flag is resolved from `importers` and `snapshots`.
- Fields read: `lockfileVersion`; for each `packages` entry, the key (`<name>@<version>`, with an optional leading `/` and an optional peer suffix) and `engines.node`; in 6.x, `dev` and `devOptional`; in 9.x, the `dependencies`, `optionalDependencies`, and `devDependencies` of every `importers` entry, and the `dependencies` and `optionalDependencies` of every `snapshots` entry.
- Version syntax: semver ranges in `engines.node`, tested with `semver.satisfies` and `includePrerelease: false`. A bare target major such as `22` is tested as `22.0.0`; the bundled lifecycle data does not list per-minor Node.js releases.
- Levels: `blocker` for a production dependency whose range excludes the target; `warning` for a dev dependency (`dev: true` or `devOptional: true` in 6.x, or reachable only from a dev dependency in 9.x); `unknown` for an `engines.node` value that is not a valid semver range.
- Evidence: `engines.node: <range as written>`, at the line of the `engines` key.
- Deduplication: identical name, version, and range across peer variants keep the first line.

## Poetry (`poetry.lock`)

Applies when `poetry.lock` exists. Runtime: `python`.

Files and fields it reads:

- Every `[[package]]` entry in `poetry.lock`: `name`, `version`, `python-versions`, and `category` (Poetry 1.1) or `groups` (later Poetry versions). Both group forms are handled.
- The project's own `[tool.poetry.dependencies]` `python` constraint in `pyproject.toml`, as a string or as a table with `version`.

Version syntax it understands: PEP 440 specifiers `>=`, `<=`, `<`, `>`, `==` (including `.*`), `!=`, and `~=`, joined with commas for AND; Poetry's `^` (caret), `~` (tilde), and `||` (OR) forms; and `*`, which matches every version. Comparisons follow PEP 440 ordering, including pre-releases, post-releases, development releases, and epochs.

What it reports:

- `blocker` for a main-group package whose `python-versions` excludes the target release, and for a project-level `python` constraint that excludes it.
- `warning` for a package in the `dev` or any other non-main group whose `python-versions` excludes the target.
- `unknown` for a `python-versions` value or project constraint the matcher cannot parse.

Evidence is the value as written: `python-versions: <value>` with `kind: "lockfile"` at that field's line, or `python: <value>` with `kind: "manifest"` at the `python` line in `pyproject.toml`. The subject is `<name>@<version>`, or `python` for the project constraint.

Example:

```text
blocked
poetry.lock:12  requests@2.28.0  requests@2.28.0 declares python-versions ">=3.7,<3.11", which excludes Python 3.13.  [lockfile: python-versions: >=3.7,<3.11]
pyproject.toml:9  python  The project's [tool.poetry.dependencies] python constraint ">=3.8,<3.12" excludes Python 3.13.  [manifest: python: >=3.8,<3.12]
```

## uv and PDM (`uv.lock`, `pdm.lock`)

Applies when `uv.lock` or `pdm.lock` exists. Runtime: `python`. Each issue names the file it came from.

Files and fields it reads:

- The top-level `requires-python` in `uv.lock`: the project's own range.
- Every `[[package]]` entry in `uv.lock`: `name`, `version`, `resolution-markers`, `sdist`, and the python and ABI tags of each wheel name.
- The `[metadata]` `requires_python` in `pdm.lock`, when present.
- Every `[[package]]` entry in `pdm.lock`: `name`, `version`, `requires_python`, and `groups`.

Version syntax it understands: PEP 440 specifiers `>=`, `<=`, `<`, `>`, `==` (including `.*`), `!=`, and `~=`, joined with commas for AND, plus `||` alternatives; the same comparisons in `resolution-markers` clauses on `python_version` and `python_full_version`; and wheel python tags that name a minor version (`cp39`, `py38`, `cp39-abi3`). A wheel tagged `abi3` allows every release at or above its tag. Markers that mention other variables (`sys_platform`, `platform_system`) do not bound Python.

What it reports:

- `blocker` when the project's own range (top-level `requires-python` in `uv.lock`, `[metadata]` `requires_python` in `pdm.lock`) excludes the target, when a uv package has no resolution that admits the target, and when a `default`-group PDM package's `requires_python` excludes it.
- `warning` for a PDM package in the `dev` or any other non-`default` group whose `requires_python` excludes the target. `uv.lock` has no groups.
- `unknown` for a range, marker, or wheel tag the matcher cannot parse, and for an invalid TOML file.

A uv package is reported only when every one of its resolutions states a Python bound and every bound excludes the target. Wheel tags are read only when the entry has no sdist, and a package with no bound at all is reported as nothing: wheel availability is never treated as evidence.

Evidence is the value as written: `requires-python: <range>` or `requires_python: <range>` for the project range, `resolution-markers: <marker>` for an excluding resolution, `wheels: <python tag>-<ABI tag>, ...` for version-specific wheels, and `requires_python: <range>` for a PDM package, all with `kind: "lockfile"` at that field's line. The subject is `<name>@<version>`, or `python` for the project range.

Example:

```text
python@3.13: blocked (1 blockers, 1 warnings, 0 unknown)
uv.lock:7  twisted@24.3.0  twisted@24.3.0 resolves only for Python versions matching "python_full_version < '3.13'", which excludes Python 3.13.  [lockfile: resolution-markers: python_full_version < '3.13']
pdm.lock:4  black@24.3.0  black@24.3.0 is in the dev group and its requires_python ">=3.9,<3.13" excludes Python 3.13.  [lockfile: requires_python: >=3.9,<3.13]
```

## Python standard library

Applies when the repository has at least one Python source file.

- **Reads:** every `.py` file the usage analysis reads (the same traversal as a scan: `.git`, virtual environments, build output, and dependency directories are skipped, as are files over 1 MB) and the module-import and symbol rules in `registry/python.json` whose package URL is `pkg:generic/python`.
- **Version syntax:** PEP 440 ranges from the rule's `vers`, compared with the target release, as in `python@3.13`.
- **Reports:** every `import module` and `from module import name` of a module removed by the target, and every use of a removed or deprecated function that the symbol rules describe. A `removed` rule whose range includes the target is a blocker; a `deprecated` rule whose range includes the target is a warning. Each issue is one usage location; the subject is the module or symbol and the evidence is the rule id.
- **`unknown`:** this analyzer reports none. A rule whose range does not include the target, or a target release the PEP 440 comparison cannot read, produces no issue.

## Node.js core APIs

Analyzer id `node-apis`; runtime `nodejs`. Applies when the repository's JavaScript or TypeScript source uses an API described by a `nodejs.symbol.*` rule, found with the same parser-backed usage analysis the npm detector uses.

- **Reads:** every JavaScript and TypeScript source file the usage analysis reads (the same traversal as a scan: `.git`, dependency and build directories, and files over 1 MB are skipped) and the `nodejs.symbol.*` rules in `registry/nodejs.json` whose package URL is `pkg:generic/nodejs`.
- **Version syntax:** semver ranges from the rule's `vers`, compared with the target release, as in `nodejs@24`. A rule whose range does not include the target produces no issue.
- **Reports:** every use of an API the target removed or deprecated. A `removed` rule whose range includes the target is a `blocker`; a `deprecated` rule whose range includes the target is a `warning`. Each issue is one usage location; the subject is the API name and the evidence is the rule id.
- **Levels come from rule data only:** the `event` and `vers` fields decide. Summaries and titles are never parsed for versions, so a rule that mentions a runtime-deprecation version in its text counts as a warning from that version only when the range is encoded in `vers`.
- **`unknown`:** this analyzer reports none. A target release the semver comparison cannot read, or a source file without a matched symbol, produces no issue.

The removal versions in the registry are sourced to the official [Node.js deprecations page](https://nodejs.org/api/deprecations.html).

## Target lifecycle

Analyzer id `target-lifecycle`; runtimes `nodejs`, `python`, `go`, `java`, `dotnet`, `ruby`, `php`, `dart`. Applies when the repository pins one of these runtimes in a file this analyzer can read; a repository without any such pin is not judged by it.

**The target itself**

The target release is looked up with `lookupProduct` against the bundled registry, and only the runtime's own lifecycle rules (`nodejs.runtime.*`, `python.runtime.*`, `go.runtime.*`, `java.jdk.*`, `dotnet.runtime.*`, `ruby.runtime.*`, `php.runtime.*`, `dart.sdk.*`) decide; module or platform rules that share the product never flag the release itself.

- A target that is end-of-life, removed, or out of support — or whose dated end has already passed — is a `blocker`: "the target itself is end-of-life; choose <newest supported line>". The suggested line is the rule's `replacement` from the bundled data; nothing is ever fetched.
- A target whose dated end falls within 180 days of the day checked is a `warning` with the deadline and the same suggestion.
- The evidence is the rule id; the issue is located at the repository's first pin of that runtime, so the report shows where the choice has to be made.

**Files that must change**

Every pin of the target runtime that differs from the target is listed as a `warning` with subject `pin to update`, at its exact path and line; a pin that already names the target is not listed.

- **Reads:** `.nvmrc`, `.node-version`, `.python-version` (version line, moving names such as `lts/*` are skipped); `.ruby-version`, `.php-version`, `.java-version`, and `global.json` through the existing runtime-pin parsers; every `.tool-versions` line of a known tool (a `path:` or `ref:` entry names no version and is skipped); `FROM` images of runtime repositories in any `Dockerfile`, `Containerfile`, or named variant (depth- and count-bounded walk, symlinks and build directories skipped); and `actions/setup-{node,python,ruby,java,dotnet,go,dart}` version inputs in `.github/workflows/*.yml|yaml`, scalar or list, parsed as data and never evaluated.
- **Version syntax:** `semver.coerce` normalizes what a pin stands for (`20`, `v20.11`, `18.19.0`, `node:20-alpine`, `8.0.x`, `temurin-22`); the comparison respects the precision the target was written with, so the target `24` matches any `24.x` pin while the target `24.12` requires that release line.
- **`unknown`:** this analyzer reports none. A runtime with no pins in the repository simply does not apply, and a target the bundled data does not flag produces only the pin list.

```bash
offing upgrade-check --to nodejs@18 tests/fixtures/upgrade/target-lifecycle/example
```

The example repository pins Node.js 20 in `.nvmrc`, a `Dockerfile`, and `.tool-versions`, so the end-of-life target is blocked with the suggestion and all three pins are listed. See [tests/fixtures/upgrade/target-lifecycle/example](../tests/fixtures/upgrade/target-lifecycle/example).

---

Source: https://velella.sh/offing/RECEIPTS/

# Verification receipts

A verification receipt is the deterministic record of what one change did to a repository's lifecycle findings: which a before/after comparison resolved, which remain, and which the change introduced. Offing builds it by comparing two scans. It never edits files and never runs a verification command.

```bash
offing receipt [path] --before <scan.json> [--format markdown|json] [--fail-on-introduced]
```

The default format is Markdown meant for a pull request body. `--format json` (or `--json`) prints the versioned `offing.receipt.v1` document. With `--fail-on-introduced`, the command exits `1` when the after scan reports findings the before scan did not.

Through the local MCP server, `verify_migration` can return the same receipt and `receipt_markdown` when the session already holds a before scan. See [Local MCP server](MCP.md).

## Reproduce one from `examples/demo`

Work on a copy of the demo so the repository tree stays unchanged. Scan first, save the report, remove the deprecated `request` dependency and its import, then ask for a receipt against the saved before scan:

```bash
npm ci
npm run build
demo="$(node dist/tools/examples.js demo)"
node dist/src/cli.js scan "$demo" --json > /tmp/offing-demo-before.json
```

In the copy, clear the `request` dependency and replace its usage:

```json
{
  "name": "offing-demo",
  "private": true,
  "engines": {
    "node": ">=18"
  },
  "dependencies": {}
}
```

```js
export function fetchStatus(url) {
  return fetch(url).then((response) => response.status);
}
```

Write those contents to `package.json` and `src/client.js`, then:

```bash
node dist/src/cli.js receipt "$demo" --before /tmp/offing-demo-before.json
```

That produces the Markdown below. Add `--format json` for the structured document.

## Example Markdown receipt

Real output from the steps above (Markdown escapes punctuation in titles and paths so the block stays paste-safe):

````markdown
<!-- offing-receipt -->
## Offing receipt: Partially resolved

| Resolved | Remaining | Introduced |
| --- | --- | --- |
| 1 | 4 | 0 |

### Resolved

| Severity | Finding | Location |
| --- | --- | --- |
| high | request is deprecated | package\.json:8 |

### Remaining

| Severity | Finding | Location |
| --- | --- | --- |
| high | Unsupported actions/checkout runtime | \.github/workflows/ci\.yml:9 |
| medium | Node\.js 18 is end\-of\-life | package\.json:5 |
| medium | Node\.js 19 is end\-of\-life | package\.json:5 |
| medium | Node\.js 20 is end\-of\-life | package\.json:5 |

### Introduced

_None._

### Suggested commands

```
git diff --check  # Validate the edited workflow diff.
node --version  # Confirm the active Node.js runtime is supported.
npm run build --if-present  # Verify imports, types, and the build remain valid.
npm run test --if-present  # Run HTTP behavior and repository tests when defined.
```

Reproduce with: `offing receipt "$demo" --before /tmp/offing-demo-before.json`
````

## What each section means

| Part | Meaning |
| --- | --- |
| `<!-- offing-receipt -->` | Marker so a tool can find or replace the block in a pull request body. |
| Heading verdict | Derived only from the counts: no findings, all resolved, findings remain, partially resolved, or new findings introduced. Introduced wins when any new finding appears. |
| Counts table | How many findings landed in each list. |
| Resolved | Present in the before scan and absent after. Matched by finding id. |
| Remaining | Present in both scans. |
| Introduced | Present only in the after scan. |
| Suggested commands | Verification commands named by the rules the comparison touched. Printed for the reader; Offing never runs them. |
| Reproduce line | The `offing receipt` command that rebuilds this receipt, with the path and `--before` scan it was built from, relative to the working directory. Shows `<path>` and `<scan.json>` when the caller does not know them, as the MCP `receipt_markdown` output does. |

When a list is empty, the section shows `_None._`. When a list has more than five findings, the Markdown collapses it into a `<details>` block.

## JSON contract

`--format json` prints the same comparison as `offing.receipt.v1`. The schema is [`schemas/receipt.v1.schema.json`](../schemas/receipt.v1.schema.json). Each finding entry keeps `id`, `rule`, `title`, `severity`, repository-relative `path`, and optional `line` — enough to join the finding in a `scan --json` report, not the whole finding. `data.before` and `data.after` record the lifecycle data each side used, or `null` when a scan did not.

The same two scans always produce the same receipt: comparison is by finding id, lists are sorted, and the builder reads no clock and no environment.

## Safety

`receipt` reads the `--before` scan file and re-scans the path locally. It does not use the network, does not evaluate repository code, and does not execute suggested commands. A migration is complete only after the project's own tests pass and a fresh scan no longer reports the findings you meant to clear.

---

Source: https://velella.sh/offing/SHARE_REPORT/

# Share a lifecycle report

Produce a terminal timeline or a self-contained HTML file from a local scan, then send the file yourself. Offing never uploads the report, the repository, or the scan result.

Every command below runs offline against files on disk. The examples use the deliberately outdated project at `examples/demo` in this repository; point them at any path you want to scan.

## Terminal timeline

```bash
# From a clone of Offing:
npm ci
npm run build
demo="$(node dist/tools/examples.js demo)"
npx @velella/offing forecast --timeline "$demo"
```

A real run on 2026-10-30 printed:

```text
Forecast from 2026-10-30 to 2027-10-30 (12 months)

2026-10  |
2026-11  |#############################################################  1 event
2026-12  |
2027-01  |
2027-02  |
2027-03  |
2027-04  |#############################################################  1 event
2027-05  |
2027-06  |#############################################################  1 event
2027-07  |
2027-08  |
2027-09  |
2027-10  |
```

Each bar is a month that has at least one dated lifecycle event in the default twelve-month window. Use `--months <n>` to widen or shorten the window, or drop `--timeline` for a plain list. Add `--json` when a tool needs the structured forecast instead of the drawing.

## HTML report

```bash
npx @velella/offing scan --format html "$demo" > report.html
```

Open `report.html` in a browser, attach it to an issue, or paste it into chat. The file is self-contained: styles and the embedded JSON scan result travel with it. Nothing leaves your machine unless you choose to send the file.

### What the report contains

- The repository path Offing scanned and when the scan ran.
- A severity summary and every finding: title, severity, exact file path and line, rule id, replacement, and migration notes.
- A treemap that sizes each directory and file by its severity-weighted findings (critical 8, high 4, medium 2, low 1, info 0.5) and colors it by its highest severity; each rectangle links to that file's findings below and shows its path and counts on hover or focus.
- Authoritative source links for each finding (for example the Node.js release schedule or a GitHub changelog entry).
- A "Next 12 months" forecast chart of dated end-of-life events in that window.
- The full scan document in a `<script type="application/json" id="offing-report">` block for anyone who wants the machine-readable form.

![Offing HTML report treemap sizing directories and files by severity-weighted finding count and coloring each rectangle by its highest severity](assets/screenshots/treemap.webp)

On `examples/demo`, the report lists findings such as "Unsupported actions/checkout runtime" at `.github/workflows/ci.yml:9` and "request is deprecated" at `package.json`, each with its source URLs.

### What is safe to send

The HTML file (and the timeline text) can include repository-relative paths, finding titles, short excerpts Offing already printed, and public evidence URLs. It does not include credentials, environment variables, or file contents beyond those finding fields. Offing does not open a network connection for `scan` or `forecast`, does not call home, and does not upload the report anywhere — sharing is only whatever you do with the file or the terminal output after the command finishes.

For the broader privacy contract, see [Privacy](PRIVACY.md).

---

Source: https://velella.sh/offing/SHOWCASE/

# Showcase

Short, copy-pasteable ways to show what Offing found. Every command runs locally against files on disk; nothing is uploaded and no scan uses the network. Unless a section names another project, the examples use the deliberately outdated project at `examples/demo` in this repository.

## Live countdown

```bash
# From a clone of Offing:
npm ci
npm run build
demo="$(node dist/tools/examples.js demo)"
npm run --silent example -- gallery countdown --as-of 2026-10-25
```

Prints one row per dated deadline that affects the project: the subject, a bar scaled to the remaining time in a two-year window, and the time left until 00:00 UTC on the deadline. Bars are green over 180 days, yellow from 30 to 180, red under 30, and dim once the date has passed. Rows are sorted by deadline, and `--limit` keeps the soonest ten by default.

On a terminal the frame redraws once per second for six seconds and stops on the final frame. `--once` prints one frame, `--no-animation` keeps one static frame, and piping the output prints one plain frame. `--json` prints the same rows with `subject`, `deadline`, `remainingSeconds`, `ruleId`, and `location`, so a script can chart or gate on them.

The example uses `examples/gallery`, which has upcoming deadlines across container, runtime, and package rules. The gallery is committed with scanner-neutral names, so the command copies it to a temporary directory and restores the real names before scanning. `docs/demos/countdown.tape` records the animation with [VHS](https://github.com/charmbracelet/vhs); regenerate the GIF with `vhs docs/demos/countdown.tape`.

## Fix before and after

```bash
offing fix . --show
```

Plays the deterministic fixes in the terminal. Each patch shows its file, the removed lines in red typed out first and the added lines in green after them, then the findings no fixer could repair appear in dim text with their reasons. The last line is the finding count before and the count after the patches, such as `12 → 3 findings`.

Nothing is written to the repository. The "after" count comes from a scan of a temporary copy of the repository with the patches applied, and the copy is removed afterwards. With `--branch` the fixes are committed on `offing/fix` as usual and the view shows what was committed, with the count from the re-scan of the real repository.

The play is held to six seconds: a long plan is typed faster, and if time still runs out the rest is printed at once. `--no-animation` prints the same content as static colored diffs, and piping the output prints it without color. `--show` cannot be combined with `--json`. `docs/demos/fix-show.tape` records the animation with [VHS](https://github.com/charmbracelet/vhs); regenerate the GIF with `vhs docs/demos/fix-show.tape`.

## Glance card

```bash
npm run --silent example -- gallery glance --as-of 2026-10-25
```

Prints a one-screen summary of the repository's lifecycle state, laid out like `neofetch`: the Offing mark on the left in the brand green, the facts on the right. The facts are the repository name, every detected ecosystem with its maturity level, findings by severity as colored blocks, the next deadline, the oldest ended item, and the lifecycle data version and age. The counts are the ones `scan --json` reports for the same path.

Under 80 terminal columns the mark is dropped and the facts keep the full width. `--json` prints the facts alone as an `offing.glance.v1` document, so a script or a dashboard can reuse them. `docs/demos/glance.tape` records the card with [VHS](https://github.com/charmbracelet/vhs); regenerate the GIF with `vhs docs/demos/glance.tape`.

## Shell prompt segment

```bash
offing prompt
```

Prints a short segment such as `⏳2` when the repository you are in has lifecycle findings, and nothing otherwise, so it can sit in your shell prompt. It reads only the scan cache that `offing scan` and `offing watch` leave behind: it never scans, starts a process, or uses the network, and a missing or stale cache prints nothing. The count is the high and critical findings when there are any, otherwise all findings; `--symbol EOL:` gives ASCII.

[docs/PROMPT.md](PROMPT.md) has snippets for Starship, oh-my-zsh, Powerlevel10k, fish, and bash. `docs/demos/prompt.tape` records it with [VHS](https://github.com/charmbracelet/vhs); regenerate the GIF with `vhs docs/demos/prompt.tape`.

## Watch board

```bash
offing watch --board
```

Ranks every project registered with `offing watch` by lifecycle risk. Each row is the rank, the project name, findings by severity as small colored bars, the next deadline, and a trend arrow against the previous board (▲ worse, ▼ better, ● same). Ranking uses the same severity weights as the HTML treemap (critical 8, high 4, medium 2, low 1, info 0.5), then the earliest deadline, then the project name.

The board re-scans like `watch run`, stores a per-project summary in the watch state file, and leaves the digest history alone. An older state file without summaries shows ● for every project. `--json` prints the ranked rows as an `offing.watch-board.v1` document. On a terminal the severity bars are colored; `NO_COLOR` or a pipe turns that off. `docs/demos/watch-board.tape` records the table with [VHS](https://github.com/charmbracelet/vhs); regenerate the GIF with `vhs docs/demos/watch-board.tape`.

## Year in review

```bash
offing wrapped . --year 2025
```

Plays a year-in-review of lifecycle findings for the repository. Each card is backed by data: findings fixed, findings introduced, net change, the longest-ended item still present, the top three CODEOWNERS owners by fixed findings (skipped when there is no CODEOWNERS file), and the next deadline in the coming year. Fixed and introduced counts match `offing diff <base>..<head> --json` for the same refs.

The base is the last commit before 1 January of the year; when the repository has none, the command says so and compares against the first commit. For a past year the head is the last commit of that year; for the current year it is `HEAD`. Scans use git objects only, so the working tree is never modified.

On a terminal the cards play one at a time within six seconds. `--no-animation` prints them all at once, and piping the output does the same. `--svg wrapped.svg` writes one 1200×630 summary card with no script and no external references. `--json` prints the `offing.wrapped.v1` document. `docs/demos/wrapped.tape` records the play with [VHS](https://github.com/charmbracelet/vhs); regenerate the GIF with `vhs docs/demos/wrapped.tape`.

## Time-lapse of a repository aging

```bash
offing timelapse . --from 2026-11 --to 2028-10 --no-animation
```

Plays 24 monthly frames of the same repository: each frame is the scan projected onto that month's last day with `scan --as-of` logic, so finding counts stay honest. Affected files start dim and turn red as their deadlines pass, with a running count under the tree. `--svg timelapse.svg` writes a 1200×630 CSS animation of those frames for a README; `--json` prints `{ month, findings, files }` for each month. `docs/demos/timelapse.tape` records the play with [VHS](https://github.com/charmbracelet/vhs); regenerate the GIF with `vhs docs/demos/timelapse.tape`.

## Mermaid support windows

```bash
npx @velella/offing scan --format mermaid --as-of 2026-10-30 "$demo"
```

Prints a fenced `mermaid` block containing a Gantt chart: one section per ecosystem and one bar per subject from the day the scan observed it to its deadline. A subject that has already ended is a `crit` milestone at its deadline; one that ends within 30 days is a `crit` bar. A `today` milestone follows `--as-of`. Paste the whole block into a README, an issue, or a pull request comment and GitHub renders the chart without an image file.

```mermaid
gantt
    title Offing support windows
    dateFormat YYYY-MM-DD
    axisFormat %Y-%m
    todayMarker off

    section github-actions
    Unsupported actions/checkout runtime :crit, milestone, bar0, 2026-09-23, 0d

    section nodejs
    Node.js 19 is end-of-life :crit, milestone, bar1, 2023-06-01, 0d
    Node.js 18 is end-of-life :crit, milestone, bar2, 2025-04-30, 0d
    Node.js 20 is end-of-life :crit, milestone, bar3, 2026-04-30, 0d

    section npm
    request is deprecated :crit, milestone, bar4, 2020-02-11, 0d

    section today
    today 2026-10-30 : milestone, marker, 2026-10-30, 0d
```

`--as-of <YYYY-MM-DD>` moves the bars and the `today` milestone together, so the same date always prints the same chart. The chart draws at most 40 bars and ends with a line such as `and 3 more`; `--format json` still lists every finding. Use it when a pull request or a README should show when support for what the repository uses runs out.

The same chart is available for the look-ahead window:

```bash
npx @velella/offing forecast --format mermaid --as-of 2026-10-30 "$demo"
```

`forecast --format mermaid` draws one bar per dated event in the forecast window, grouped by ecosystem, instead of only the findings in this repository.

The GitHub Action's pull request comment is raw Markdown, so a Mermaid block renders there too. The built-in comment does not include the chart or accept a comment template yet, so paste the command's output into a comment, or add a workflow step that writes it.

## Animated forecast for a README

`offing forecast --svg --animate` draws the coming months as a self-contained SVG: one bar from today to each dated lifecycle event, in date order, and a today marker that pulses twice. Bars follow the severity lanes, the file reads in light and dark through `prefers-color-scheme`, and `prefers-reduced-motion: reduce` shows the final frame immediately. The SVG contains no script, no `<foreignObject>`, and no external references.

```bash
npx @velella/offing forecast . --months 12 --svg --animate > docs/forecast.svg
```

Commit `docs/forecast.svg`, then embed it in the README:

```markdown
![Lifecycle forecast](docs/forecast.svg)
```

Use HTML when the image needs a width or a longer description:

```html
<img src="docs/forecast.svg" width="720" alt="Lifecycle forecast: dated end-of-life events in the next twelve months">
```

Without `--animate`, the command prints the marker-only timeline that the HTML report embeds, with no animation block. `--as-of <YYYY-MM-DD>` fixes the window when you need the file to stay byte-identical, for example in a test or a release note.

### Refresh it on a schedule

A scheduled GitHub Actions workflow can regenerate the file and commit it when the forecast changes. The scan is local, so the job only needs a checkout, Node.js 22, and `contents: write` to push the refreshed file.

```yaml
name: Refresh lifecycle forecast

on:
  schedule:
    - cron: "0 6 * * 1" # Mondays 06:00 UTC
  workflow_dispatch:

permissions:
  contents: write

jobs:
  forecast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npx --yes @velella/offing@0.8.0 forecast . --svg --animate > docs/forecast.svg
      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add docs/forecast.svg
          git diff --cached --quiet || git commit -m "docs: refresh the lifecycle forecast"
          git push
```

Pin the Offing release you use instead of always taking the latest. If the default branch is protected, open a pull request from the workflow instead of pushing to it. GitHub caches README images, so a refreshed file can take a few minutes to appear; the commit is the refresh.

---

Source: https://velella.sh/offing/COMPATIBILITY/

# Environment doctor and compatibility matrix

Offing can inspect its execution environment without scanning source files:

```bash
offing doctor .
offing doctor . --json
```

The doctor checks the Node.js runtime, installed package entry points, local MCP
server, portable Agent Skill, shared plugin prerequisites, and local or CI
workspace. It is read-only: it does not change configuration, execute suggested
repairs, start a network listener, or upload repository data.

`offing doctor --system` also asks `node`, `python3`, `go`, `java`, `dotnet`, and
`terraform` for their version (`--version`, or `-version` for Java, which works on
every release) and matches each against the bundled end-of-life and end-of-support
rules. The report lists each tool, its release line, and its status in a `system`
array; tools that are not installed are skipped. A tool that is out of support is a
warning, not a failure. Nothing else is run and nothing uses the network.

Text and JSON are generated from the same deterministic result. The JSON contract
is `offing.doctor.v1`; its schema is
[`schemas/doctor.v1.schema.json`](../schemas/doctor.v1.schema.json). A failed check
always includes a concrete remediation. Warnings describe usable but not yet stable
integration paths and do not make the command fail.

## Compatibility matrix

Matrix version: **2026-10-15 / v1**

| Surface | Combination | Status | Notes |
| --- | --- | --- | --- |
| CLI | Node.js 22+ on Linux | Supported | Primary local and CI execution path. |
| CLI | Node.js 22+ on macOS | Supported | Same deterministic CLI and JSON contracts; the full check runs on macOS in CI. |
| CLI | Node.js 24 on Linux | Supported | Part of the CI matrix next to Node.js 22. |
| CLI | Node.js 22+ on Windows | Supported | The full check runs on Windows in CI on every pull request. |
| GitHub Actions | Ubuntu runner | Supported | Composite Action, annotations, baselines, severity gate, and JSON artifact. |
| GitHub Actions | macOS runner | Experimental | Expected to work through `bash`; not yet in the required runner matrix. |
| GitHub Actions | Windows runner | Unsupported | The current composite Action requires `bash`. Use the CLI explicitly if available. |
| GitLab CI | Linux runner using the CLI | Experimental | Doctor detects `GITLAB_CI` and `CI_PROJECT_DIR`; a Catalog component is not published yet. |
| MCP | Local stdio host | Supported | No HTTP listener, account, credential, or hosted Offing service. |
| Agent Skill | skills.sh / skills CLI monorepo discovery | Supported | `velella-sh/offing` discovers and installs `offing`. |
| Agent Skill | Codex, Claude Code, Cursor, GitHub Copilot, or Gemini CLI | Supported | Project installation validated through the skills CLI on 2026-10-15. |
| Agent Skill | Other hosts supporting the open Agent Skills directory format | Experimental | The portable files can be copied or linked, but these hosts are not in the representative install gate. |
| Host plugins | Codex or Claude packaged plugin | Experimental | Shared MCP and Skill prerequisites exist; stable host packages are not published yet. |

## v1 compatibility guarantees

From **1.0.0**, the 1.x line is a SemVer compatibility promise: a consumer that pins `offing@^1` (or a specific 1.x release) can rely on the contracts below without a surprise break in a minor or patch release. Removals and replacements still follow the [deprecation policy](#deprecation-policy); this section states what each contract guarantees and how long that guarantee lasts on the 1.x line.

Scans stay offline and need no account. That property is part of the v1 promise and is not relaxed in a 1.x release.

### Support windows on 1.x

| Kind | Window on the 1.x line |
| --- | --- |
| A versioned document (`offing.*.vN`), its JSON Schema file, the detector SDK API version, the registry format, or the data-bundle format | Supported for the whole 1.x line. A successor (`vN+1`) may ship in a minor release; the older version keeps working at least through the [versioned-format notice period](#notice-periods) and is not removed before 2.0.0. |
| CLI commands, flags, and environment variables marked stable in the docs | Supported for the whole 1.x line. A rename or removal needs the [unversioned notice period](#notice-periods) and lands no earlier than 2.0.0. |
| MCP tools, resources, prompts, and their documented input fields | Same as CLI flags: whole 1.x line; removal only after notice, and not before 2.0.0. |
| GitHub Action and GitLab component inputs whose default preserves current behavior | Same as CLI flags. |
| Exit-code classes (`policy` 1, `usage` 2, `data` 3, `parse` 4, `internal` 5) | Stable for the whole 1.x line. New classes get new numbers; existing numbers are never renumbered. |
| Surfaces the matrix marks **Supported** or **Beta** | Get the windows above. |
| Surfaces the matrix marks **Experimental** | Usable, but may change in any minor release with a CHANGELOG entry; no multi-release window. |
| Node.js and other runtimes listed in the matrix | Dropped from the matrix only after that runtime reaches its own end of life, and only with a deprecation note in the release before the drop. |

A 1.x patch fixes behavior or security and does not add fields. A 1.x minor may add optional fields, commands, tools, or inputs. A required field, a rename, a type change, or a removal of a versioned format requires a new document version and the windows above — not a silent break inside 1.x.

### Per-contract guarantees

Each row is a published contract. The guarantee is the machine-readable shape: identifiers, field names, types, and exit codes. Help text, warning prose, and field order may change in any release. Consumers must ignore fields they do not know.

| Contract | Identifier / schema | Guarantee on 1.x |
| --- | --- | --- |
| Scan result | `offing.scan.v1` · [`scan.v1.schema.json`](../schemas/scan.v1.schema.json) | Required fields and types stay; optional fields may appear in a minor. A breaking change ships as `offing.scan.v2` while `v1` remains accepted for the window. |
| Dependency check | `offing.check.v1` · [`check.v1.schema.json`](../schemas/check.v1.schema.json) | Same additive rules. Status values already documented keep their meaning. |
| Migration context | `offing.context.v1` · [`context.v1.schema.json`](../schemas/context.v1.schema.json) | Packet shape stays; new optional sections may appear. |
| Deprecation list | `offing.deprecations.v1` · [`deprecations.v1.schema.json`](../schemas/deprecations.v1.schema.json) | Compact list shape stays for agents and planners. |
| Verification | `offing.verification.v1` · [`verification.v1.schema.json`](../schemas/verification.v1.schema.json) | Re-scan result shape stays. |
| Doctor | `offing.doctor.v1` · [`doctor.v1.schema.json`](../schemas/doctor.v1.schema.json) | Check and summary shape stays; new optional checks may appear. |
| Capabilities manifest | `offing.capabilities.v1` · [`capabilities.v1.schema.json`](../schemas/capabilities.v1.schema.json) | Manifest shape stays; new optional capability or surface entries may appear. |
| Baseline | `offing.baseline.v1` · [`baseline.v1.schema.json`](../schemas/baseline.v1.schema.json) | File format stays so CI baselines written under 1.x keep loading. |
| Config | `offing.config.v1` · [`config.v1.schema.json`](../schemas/config.v1.schema.json) | Documented keys keep their meaning; new optional keys may appear. |
| Rule document | `ebb.rule.v1` · [`rule.v1.schema.json`](https://github.com/velella-sh/ebb/blob/main/schemas/rule.v1.schema.json) | Rule view shape stays for MCP resources and tooling. |
| Fix plan | `offing.fix.v1` · [`fix.v1.schema.json`](../schemas/fix.v1.schema.json) | Plan shape stays. |
| Data status | `ebb.data-status.v1` · [`data-status.v1.schema.json`](../schemas/data-status.v1.schema.json) | Status shape stays. |
| CLI errors | `offing.error.v1` | `error.code` classes and exit codes stay as in [Exit codes](CAPABILITIES.md#exit-codes-and-error-codes). |
| Detector SDK | `offing.detector.v1` · [`src/sdk.ts`](../src/sdk.ts) | Detectors written to this API keep loading; a `v2` API may ship in parallel. |
| Registry file | `ebb.registry.v2` · [`registry.v2.schema.json`](https://github.com/velella-sh/ebb/blob/main/schemas/registry.v2.schema.json) | `v2` registries keep validating and loading; a `v3` may ship in parallel. |
| Data bundle | `ebb.data-bundle.v1` · [`data-bundle.v1.schema.json`](https://github.com/velella-sh/ebb/blob/main/schemas/data-bundle.v1.schema.json) | Bundle manifest shape stays; older bundles remain accepted for the window after a successor appears. |
| MCP server | Tool names, resource URIs, and input fields in [MCP](MCP.md) | Listed tools and resources keep working; new tools or optional inputs may appear. Output documents use the rows above. |
| GitHub Action / GitLab component | Input names in [GitHub Action](GITHUB_ACTION.md) and [GitLab](GITLAB.md) | Documented inputs keep their meaning; new inputs default to current behavior. |
| SARIF export | SARIF 2.1.0 from `scan --format sarif` | Remains valid SARIF 2.1.0; field mapping changes that would break code scanning need notice as for versioned formats. |
| Agent Skill | Portable skill layout and trigger description | Install and discovery paths for Supported hosts stay; host-specific packaging marked Experimental follows the experimental window. |

### Outside the v1 promise

These change without a contract break and are not covered by the windows above:

- **Lifecycle findings and rules.** Bundled data can add, change, or remove a finding when evidence changes. Pin a data version or use a [baseline](CAPABILITIES.md) to stabilize CI.
- **Detector maturity moves.** Promoting or demoting a detector between Experimental, Beta, and Supported follows [decision 0013](decisions/0013-detector-maturity.md).
- **Bug fixes** that correct a wrong location, match, or message.
- **Internals** not exported from `src/index.ts` or named in a schema, including maintainer scripts and test fixtures.
- **Human-readable wording** in CLI help, finding prose, and documentation.

Until 1.0.0 is tagged, Offing is still pre-1.0: the deprecation policy already applies, and this section is the contract that 1.0.0 will publish. Issue tracking for the release is in the [v1 epic](https://github.com/velella-sh/offing/issues/57).

## Deprecation policy

Offing reports other projects' deprecations. Its own interfaces follow the policy below, so a script, an agent, or a plugin built on Offing keeps working long enough to move.

### What the policy covers

| Interface | Version identifier | Additive change | Breaking change |
| --- | --- | --- | --- |
| CLI commands, flags, and environment variables | None | A new command, flag, or variable. | The old form is deprecated for a full window, then removed. |
| JSON output of `scan`, `check`, `explain`, `context`, `doctor`, and the other `--json` commands | `schemaVersion`, for example `offing.scan.v1` | A new optional field, added in a minor release. Consumers must ignore fields they do not know. | A new document version such as `offing.scan.v2`; `v1` keeps working for the window. |
| JSON Schemas in [`schemas/`](../schemas) | File name, for example `scan.v1.schema.json` | A new optional property. | A new `*.v2.schema.json` file; the `v1` file stays for the window. |
| MCP tools, resources, and prompts | Tool and resource URIs, input field names, and the same output `schemaVersion` | A new tool, prompt, optional input, or optional output field. | A new window, then a removal or a new output version. |
| Detector SDK ([`src/sdk.ts`](../src/sdk.ts)) | `offing.detector.v1` | A new optional member or a new context field. | `offing.detector.v2`; the engine keeps loading `v1` detectors during the window. |
| Registry format | `ebb.registry.v2` | A new optional rule or registry field, accepted by the validator in the same release. | `ebb.registry.v3`; `v2` registries are still read during the window. |
| Data bundle | `ebb.data-bundle.v1` | A new optional manifest field. | A new bundle version; the old one is still accepted during the window. |
| GitHub Action and GitLab component inputs | Input names | A new input whose default preserves current behavior. | The old input or behavior is deprecated for a full window, then removed. |

The contract is the machine-readable part: command names, exit codes, field names, types, and schema versions. Human-readable wording, help text, warning prose, and field order may change in any release. A new optional field may appear in a `v1` document in a minor release; a required field, a rename, a removal, or a type change requires a new version. Patch releases fix behavior but do not add fields.

### Notice periods

| Change | Minimum notice before removal |
| --- | --- |
| CLI flag, environment variable, Action or component input, MCP tool, prompt, resource, or input field | 90 days and one minor release, whichever ends later. |
| A versioned format: JSON document, schema file, registry, bundle, or detector API | 12 months and two minor releases after its successor ships. |

The window starts in the release that announces the deprecation, not in the release that removes it, and it is measured from that release's date. Extensions are allowed; shortening a window is not, except for a security or correctness problem (below).

Before 1.0, semantic versioning would permit a minor release to break an interface; this policy is deliberately stricter and already applies. From 1.0.0, the [v1 compatibility guarantees](#v1-compatibility-guarantees) lock the same windows into the SemVer major line. Surfaces the matrix marks **Experimental** may change in any minor release with a CHANGELOG entry; **Beta** and **Supported** surfaces get the windows above. Runtime support is listed in the matrix; a runtime is dropped from it only after the runtime reaches its own end of life and with a deprecation note in the release before the drop.

### Removal process

1. **Open an issue** labeled `deprecation` that names the interface, the replacement, and the intended removal release.
2. **Record it** in the table below with the release it was deprecated in and the earliest release or date it may be removed.
3. **Announce it in a release**: a CHANGELOG entry, a note in the docs for the interface, and the replacement and migration step. Where the interface can warn at runtime, a CLI flag or environment variable prints one line to stderr; an MCP tool or input is marked deprecated in its description.
4. **Keep it working** for the full window. Only fixes and security changes are made to a deprecated interface, and its behavior must not drift toward the replacement.
5. **Remove it** in the first release after the window. The CHANGELOG entry says so, the docs stop describing it, and a versioned format's old file is retired together with runtime support for it. The issue is linked from the release notes.
6. **If the replacement is not ready**, extend the window in the table and say why in the issue. A deprecation without a documented replacement is not opened.

A security vulnerability, data corruption, or a contract that would make a lifecycle answer unsafe to act on may be fixed or removed in the next patch release. The release notes name the change, and a vulnerability is reported through [SECURITY.md](../SECURITY.md).

### What is not a deprecation

- **Lifecycle findings.** Rules and their evidence are data, not an interface. A data update can add, change, or remove a finding at any time; a [baseline](CAPABILITIES.md) or a pinned data version is how a project stabilizes its results. A new finding is not a breaking change.
- **Detector coverage and maturity.** Moving a detector between `Experimental`, `Beta`, and `Supported`, or reading a new declaration form, changes what a scan reports. [Decision 0013](decisions/0013-detector-maturity.md) governs those changes.
- **Bug fixes.** Correcting a wrong location, rule match, or message is not a deprecation, even when the corrected output differs from the old one.
- **Internals.** Modules that are not exported from `src/index.ts` or named in a schema, the `tools/` maintainer scripts, test fixtures, and plugin packaging internals may change at any time.

### Current deprecations

| Interface | Deprecated in | May be removed after | Replacement |
| --- | --- | --- | --- |
| None | — | — | — |

## Ecosystem coverage

<!-- coverage-matrix:start -->
| Detector ecosystem | Status | Coverage |
| --- | --- | --- |
| CI runner images | Supported | `pool.vmImage` in `azure-pipelines.yml` is matched against reviewed Azure hosted-image rules. GitLab `image` and `services` values are unclassified. CircleCI orbs, dynamic values, and floating aliases are unclassified; other CircleCI images are not judged. See [CI runner images](#ci-runner-images-detector). |
| Container base images | Supported | `FROM` lines in Dockerfiles and Containerfiles and `services.*.image` in Compose files, for Docker Hub official images with a vendor lifecycle. See [Container base images](detectors/container.md). |
| .NET | Supported | `global.json`, project files, `Directory.Build.props`, `Directory.Packages.props`, and `packages.lock.json`, for .NET release lines past end of support and deprecated NuGet packages. See [.NET](detectors/dotnet.md). |
| Go | Supported | `go` and `toolchain` directives in `go.mod` and `go.work`, and direct `require` entries, for Go release lines past end of support. See [Go](detectors/go.md). |
| Java and Kotlin (JVM) | Supported | JDK declarations in `pom.xml`, Gradle build scripts, `.java-version`, `.sdkmanrc`, and `.tool-versions`, and direct Maven dependencies, for non-LTS JDK releases past end of support and moved artifacts. See [Java and Kotlin](detectors/java.md). |
| Kubernetes APIs | Supported | The literal `apiVersion` and `kind` in YAML manifests, Helm chart templates, and kustomization patches, for API versions the Kubernetes project says are no longer served, and `Chart.yaml` dependencies that still point at the retired Helm stable or incubator repositories. See [Kubernetes APIs](detectors/kubernetes.md). |
| GitHub Actions | Supported | Selected first-party Action lifecycle rules and exact workflow locations. |
| Node.js and npm | Supported | Runtime declarations, direct dependencies, lockfiles, and supported source usages. |
| PHP | Supported | Pinned runtime declarations in `.php-version`, `.tool-versions`, `composer.json`, and `composer.lock`, for PHP release lines past end of support and abandoned Composer packages. See [PHP](#php-detector). |
| Python | Supported | Runtime declarations, direct dependencies, common lockfiles, and supported source usages. |
| Ruby | Supported | Pinned runtime declarations in `.ruby-version`, `.tool-versions`, the Gemfile `ruby` directive, and Gemfile.lock `RUBY VERSION`, plus direct gems, for Ruby release lines past end of support and yanked gems. Gem rules can list source usages in Ruby files. |
| Rust | Supported | The pinned toolchain in `rust-toolchain(.toml)` and direct dependencies in `Cargo.toml` and `Cargo.lock`, for toolchains older than the newest stable release and unmaintained crates. See [Rust](detectors/rust.md). |
| Swift | Supported | `.swift-version` and `.xcode-version` pins, the `swift-tools-version` line and literal `from:` / `exact:` dependencies in `Package.swift`, and resolved pin versions in `Package.resolved`, for Xcode releases App Store Connect no longer accepts and Swift toolchain lines with a lifecycle rule. The iOS deployment target (`IPHONEOS_DEPLOYMENT_TARGET`) of an application target in an `.xcodeproj` `project.pbxproj`, for iOS releases App Store Connect no longer accepts. Libraries and `platforms:` minimums in `Package.swift` are not read for it. See [Swift](detectors/swift.md). |
| Android | Supported | Literal `compileSdk`, `minSdk`, `targetSdk`, and `buildToolsVersion` in `build.gradle` and `build.gradle.kts`, Android Gradle Plugin and Kotlin Android plugin versions in `settings.gradle(.kts)`, `agp` and `kotlin` keys in `libs.versions.toml`, and string-notation Maven dependencies, matched to reviewed rules. Bundled rules cover Google Play Billing Library majors 5 through 9. SDK and plugin declarations produce a finding only when a rule names them. See [Android](#android-detector). |
| C and C++ | Supported | `cmake_minimum_required`, C and C++ language standards, and compiler version checks in `CMakeLists.txt`; direct requirements in `conanfile.txt` and `conanfile.py`; and direct dependencies and `builtin-baseline` in `vcpkg.json`. Bundled rules cover CMake policy versions older than 3.5 (removed) and from 3.5 up to 3.10 (deprecated). See [C and C++](#c-and-c-detector). |
| Dart and Flutter | Supported | Resolved packages and SDK constraints in `pubspec.lock`, direct dependencies and `environment` constraints in `pubspec.yaml`, and the Flutter version pinned in `.fvmrc` and `.fvm/fvm_config.json`, for Dart SDK releases past end of support and discontinued pub packages. See [Dart and Flutter](detectors/dart.md). |
| Deno and Bun | Supported | Exact runtime pins in `deno.json`, `deno.jsonc`, `bunfig.toml`, `.bun-version`, and `.tool-versions`, for Deno and Bun release lines past end of life. Version ranges, floating aliases, and environment variables are not matched. See [Deno and Bun](detectors/deno.md). |
| Database runtimes | Experimental | Image tags of `postgres`, `mysql`, `mariadb`, `redis`, and `mongo` services in Compose files, and literal engine versions on AWS (`engine` and `engine_version`), Azure (`version`), and Google Cloud SQL (`database_version`) managed database resources in `*.tf`, for major and minor lines past end of life or standard support. Bundled rules cover PostgreSQL 11 through 13 and MySQL 5.7 and 8.0, Azure Database for PostgreSQL 11 through 13 and MySQL 5.7, and Cloud SQL for PostgreSQL 9.6 through 13 and MySQL 5.6 and 5.7. Variables in Terraform version attributes are listed as unclassified. See [Database runtimes](detectors/database.md). |
| Elixir and Mix | Supported | Pinned Elixir and Erlang/OTP versions in `.tool-versions`, the project `elixir:` constraint and direct Hex deps in `mix.exs`, and resolved Hex packages in `mix.lock`, for Elixir and OTP release lines past end of support and retired Hex packages. See [Elixir and Mix](detectors/elixir.md). |
| Scala and sbt | Supported | Pinned Scala versions in `.scala-version` and literal `scalaVersion` settings in `build.sbt`, and `sbt.version` in `project/build.properties`, for Scala 2.11, frozen Scala 3.0–3.2 lines, and sbt 0.13. See [Scala and sbt](detectors/scala.md). |
| Shell and PowerShell | Supported | Literal `#Requires -Version` directives in `*.ps1` and `*.psm1`, `PowerShellVersion` in `*.psd1` manifests, and pinned `mcr.microsoft.com/powershell` image tags in `.github/workflows` files, for PowerShell releases past end of support. Bundled rules cover PowerShell 6.x and 7.0 through 7.3. Shell names such as `shell: pwsh` and Bash images carry no version and are not matched. See [Shell and PowerShell](detectors/shell.md). |
| Terraform | Experimental | `required_version` and `required_providers` constraints in `*.tf`, locked provider versions in `.terraform.lock.hcl`, the Terraform CLI version pinned in `.terraform-version` and `.tool-versions`, and managed Kubernetes control-plane versions in `*.tf` for Amazon EKS, Google Kubernetes Engine, and Azure Kubernetes Service, for Terraform CLI and Kubernetes release lines past end of support. Bundled rules cover CLI lines 1.10 through 1.14 and EKS, GKE, and AKS versions 1.33 and earlier; provider rules are not bundled yet. See [Terraform](detectors/terraform.md). |
| Serverless runtimes | Supported | `Runtime` on AWS SAM and CloudFormation functions and `Globals`, `provider.runtime` and per-function `runtime` in `serverless.yml`, and Terraform `runtime` on `aws_lambda_function` plus Google Cloud Functions runtimes and Azure function-app `application_stack` version pins. Bundled rules cover selected AWS Lambda and Google Cloud Functions identifiers that the vendors list as end-of-life. See [Serverless runtimes](detectors/serverless.md). |
| Other language and platform ecosystems | Unsupported | Report the limitation; do not infer lifecycle status without a detector. |
<!-- coverage-matrix:end -->

`Supported` means the combination is part of the documented product contract.
`Experimental` means it is usable but lacks a complete release gate or stable
distribution package. For detectors, `Experimental`, `Beta`, and `Supported`
have the meanings and the evidence requirements in
[decision 0013](decisions/0013-detector-maturity.md), and the level of each is
recorded in `benchmarks/thresholds.json`. `Unsupported` means Offing does not currently claim the
combination works.

## PHP detector

Moved to [PHP detector: PHP detector](compatibility/php.md#php-detector).

### Supported files and declarations

Moved to [PHP detector: Supported files and declarations](compatibility/php.md#supported-files-and-declarations).

### What it reports

Moved to [PHP detector: What it reports](compatibility/php.md#what-it-reports).

### What it intentionally does not judge

Moved to [PHP detector: What it intentionally does not judge](compatibility/php.md#what-it-intentionally-does-not-judge).

### Known limits and false-positive boundaries

Moved to [PHP detector: Known limits and false-positive boundaries](compatibility/php.md#known-limits-and-false-positive-boundaries).

## Ruby detector

Moved to [Ruby detector: Ruby detector](compatibility/ruby.md#ruby-detector).

### Supported files and declarations

Moved to [Ruby detector: Supported files and declarations](compatibility/ruby.md#supported-files-and-declarations).

### What it reports

Moved to [Ruby detector: What it reports](compatibility/ruby.md#what-it-reports).

### What it intentionally does not judge

Moved to [Ruby detector: What it intentionally does not judge](compatibility/ruby.md#what-it-intentionally-does-not-judge).

### Known limits and false-positive boundaries

Moved to [Ruby detector: Known limits and false-positive boundaries](compatibility/ruby.md#known-limits-and-false-positive-boundaries).

## Swift detector

The `swift` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`, and the precision floor is enforced. Eighty-five public repositories in [Validation](validation/ecosystems.md#swift-corpus) cover it. Supported forms, limits, and data sources are documented in [Swift](detectors/swift.md). Its lifecycle rules are in `registry/swift.json` and ship in the [data bundle](DATA.md).

## Dart and Flutter detector

The `dart` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`, and the precision floor is enforced. Seventy-five public repositories are pinned for it in `benchmarks/public-repositories/`. Supported files, declaration forms, matching rules, and limits are documented in [Dart and Flutter](detectors/dart.md). Its lifecycle rules are in `registry/dart.json` and ship in the [data bundle](DATA.md).

## Elixir and Mix detector

The `elixir` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`. Supported files, declaration forms, matching rules, and limits are documented in [Elixir and Mix](detectors/elixir.md). Its lifecycle rules are in `registry/elixir.json` and ship with the package (see [Lifecycle data](DATA.md)).

## Scala and sbt detector

The `scala` detector is **stable**: its level is recorded as `stable` in `benchmarks/thresholds.json`, and the precision floor is enforced. Eighty public repositories in [Validation](validation/ecosystems.md#scala-and-sbt-corpus) cover it (blind-selected by the 2026-11-07 rule). Supported files, declaration forms, matching rules, and limits are documented in [Scala and sbt](detectors/scala.md). Its lifecycle rules are in `registry/scala.json` and ship with the package (see [Lifecycle data](DATA.md)).

## Database runtimes detector

The `database` detector is **experimental**: its level is recorded as `experimental` in `benchmarks/thresholds.json`. Five public repositories are pinned in `benchmarks/public-repositories/`: four targeted cases and one blind, zero-finding repository, with ground truth from the vendors' lifecycle sources. Supported files, declaration forms, matching rules, and limits are documented in [Database runtimes](detectors/database.md). Its lifecycle rules are in `registry/database.json` and ship in the [data bundle](DATA.md).

## Shell and PowerShell detector

The `shell` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`. Forty-three public repositories are pinned under the `shell` ecosystem, thirty-nine of them chosen blind, with nine zero-finding controls. Each expected finding was checked by reading its line at the pinned commit against Microsoft's PowerShell support lifecycle, independently of Offing output. Supported files, declaration forms, matching rules, and limits are documented in [Shell and PowerShell](detectors/shell.md). Its lifecycle rules are in `registry/shell.json` and ship in the [data bundle](DATA.md).

## Terraform detector

The `terraform` detector is **experimental**: its level is recorded as `experimental` in `benchmarks/thresholds.json`. Supported files, declaration forms, matching rules, and limits are documented in [Terraform](detectors/terraform.md). Its lifecycle rules are in `registry/terraform.json` and ship in the [data bundle](DATA.md).

### Managed Kubernetes

| Product | Declaration read | Notes |
| --- | --- | --- |
| Amazon EKS | `cluster_version` and `kubernetes_version` in a module whose `source` is `terraform-aws-modules/eks/aws` | The module renamed `cluster_version` to `kubernetes_version` in v21; the source, not the attribute name, decides the vendor. |
| Google Kubernetes Engine | `min_master_version` on `google_container_cluster`, or `kubernetes_version` and `min_master_version` in a module whose `source` is `terraform-google-modules/kubernetes-engine/google` | A `//submodule` path and a `?ref=` suffix are accepted. |
| Azure Kubernetes Service | `kubernetes_version` on `azurerm_kubernetes_cluster`, or `kubernetes_version` in a module whose `source` is `Azure/aks/azurerm` | A module with an unknown source has its version attributes reported as unclassified. |

## C and C++ detector

Moved to [C and C++ detector: C and C++ detector](compatibility/cpp.md#c-and-c-detector).

### Supported files and declarations

Moved to [C and C++ detector: Supported files and declarations](compatibility/cpp.md#supported-files-and-declarations).

### Package URLs

Moved to [C and C++ detector: Package URLs](compatibility/cpp.md#package-urls).

### What it reports

Moved to [C and C++ detector: What it reports](compatibility/cpp.md#what-it-reports).

### What it intentionally does not judge

Moved to [C and C++ detector: What it intentionally does not judge](compatibility/cpp.md#what-it-intentionally-does-not-judge).

### Known limits and false-positive boundaries

Moved to [C and C++ detector: Known limits and false-positive boundaries](compatibility/cpp.md#known-limits-and-false-positive-boundaries).

## Serverless runtimes detector

The `serverless` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`, and the precision floor is enforced. Forty-one public repositories in [Validation](validation/ecosystems.md#serverless-corpus) cover it (seven targeted, thirty-four blind). Supported forms, limits, and data sources are documented in [Serverless runtimes](detectors/serverless.md). Its lifecycle rules are in `registry/serverless.json` and ship in the [data bundle](DATA.md).

## Android detector

Moved to [Android detector: Android detector](compatibility/android.md#android-detector).

### Supported files and declarations

Moved to [Android detector: Supported files and declarations](compatibility/android.md#supported-files-and-declarations).

### Package URLs

Moved to [Android detector: Package URLs](compatibility/android.md#package-urls).

### What it reports

Moved to [Android detector: What it reports](compatibility/android.md#what-it-reports).

### What it intentionally does not judge

Moved to [Android detector: What it intentionally does not judge](compatibility/android.md#what-it-intentionally-does-not-judge).

### Known limits and false-positive boundaries

Moved to [Android detector: Known limits and false-positive boundaries](compatibility/android.md#known-limits-and-false-positive-boundaries).

## CI runner images detector

Moved to [CI runner images detector: CI runner images detector](compatibility/ci-runner-images.md#ci-runner-images-detector).

### Supported files and declarations

Moved to [CI runner images detector: Supported files and declarations](compatibility/ci-runner-images.md#supported-files-and-declarations).

### What it reports

Moved to [CI runner images detector: What it reports](compatibility/ci-runner-images.md#what-it-reports).

### What it intentionally does not judge

Moved to [CI runner images detector: What it intentionally does not judge](compatibility/ci-runner-images.md#what-it-intentionally-does-not-judge).

### Known limits and false-positive boundaries

Moved to [CI runner images detector: Known limits and false-positive boundaries](compatibility/ci-runner-images.md#known-limits-and-false-positive-boundaries).

## Monorepos

The npm and Python detectors read every package of a workspace, not only the repository root. Packages are found from the declarations the package managers use: `workspaces` in `package.json` (npm and Yarn, array or `packages` form), `pnpm-workspace.yaml` (with `!` exclusions), `lerna.json`, and `[tool.uv.workspace]` `members` and `exclude` in `pyproject.toml`. Globs support `*`, `?`, and `**`.

- Findings name the package's own file, for example `packages/a/package.json`, and carry the usages inside that package's directory; usages outside every package stay with the root.
- A workspace without its own lockfile resolves versions against the root's lockfile.
- Discovery is bounded: eight directory levels, 500 packages, symbolic links never followed, and `node_modules`, `vendor`, `dist`, `build`, `target`, virtual environments, and fixture directories skipped.
- A malformed workspace manifest is skipped, so one bad package does not hide the others. A malformed root `package.json` is still an error.
- Without a workspace declaration only the root is scanned, as before. Python projects that are not uv workspaces (for example separate `pyproject.toml` files under `services/`) are not discovered.

## CI behavior

- In GitHub Actions, the doctor requires `GITHUB_WORKSPACE` to name an accessible
  checkout directory.
- In GitLab CI, the doctor requires `CI_PROJECT_DIR` to name an accessible checkout
  directory.
- Outside those environments, it reports local execution and does not require CI
  variables.

The checks only read Offing's own packaged metadata and test workspace
accessibility. They do not inspect secrets, tokens, repository contents, or remote
services.

---

Source: https://velella.sh/offing/compatibility/php/

# PHP detector

The detector's supported declarations, what it reports, what it intentionally does not judge, and the false-positive boundaries. The matrix and policy it belongs to are on [Compatibility](../COMPATIBILITY.md).

## PHP detector

The `php` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`. 108 public repositories in [Validation](../validation/ecosystems.md#php-corpus) cover it. Its lifecycle rules are in `registry/php.json` and ship in the [data bundle](../DATA.md).

### Supported files and declarations

| File | Declaration read | Notes |
| --- | --- | --- |
| `.php-version` | One pinned version on a line by itself, such as `7.4.33`, `7.4`, or `php-7.4.33` | Blank lines and `#` comments are ignored. A file with more than one version, or any other line, produces nothing. The `php-` prefix is stripped before matching. |
| `.tool-versions` | A `php` line with one or more pinned versions | Every version on the line is reported. Other tools are ignored. A line with any unsupported token produces nothing. |
| `composer.json` | `require.php`, `config.platform.php`, and direct packages in `require` / `require-dev` (`vendor/name` with a literal constraint) | Extensions (`ext-*`), floating `*`, dynamic `${…}` values, `extra.php`, and other `config.platform.*` keys are ignored. |
| `composer.lock` | `platform.php`, and each resolved package in `packages` / `packages-dev` (`name` and `version`) | Every resolved package is checked, including transitive and `require-dev` packages. `platform-dev`, `plugin-api-version`, and non-`php` platform keys are not read. An `abandoned` flag is parsed and is not a finding by itself. |

Files are found by walking the repository up to eight directories deep, to at most 500 files. Symbolic links are not followed, and `.git`, `node_modules`, `vendor`, `dist`, `build`, `target`, `.venv`, `venv`, `fixtures`, `__fixtures__`, and `testdata` are skipped. PHP, phpenv, asdf, and Composer are never run, and nothing is fetched.

### What it reports

- A pinned PHP release line that is past end of life, in the `.php-version`, `.tool-versions`, `composer.json` `config.platform.php`, or `composer.lock` `platform.php` line that pins it, an exact `require.php` version that matches a rule, or a `require.php` / `config.platform.php` constraint that allows only end-of-life lines (`^7.3`, `~7.2`, `7.4.*`, `>=7.0 <7.3`). The bundled rules cover PHP 8.1, 8.0, and 7.4, citing the [PHP unsupported branches](https://www.php.net/eol.php) page. A range that also allows a supported or unlisted release, such as `>=7.4` or `^7.4 || ^8.2`, produces no runtime finding.
- A `composer.json` package line only when a rule covers every version of that package (`vers:composer/*`). The bundled abandoned-package rules cover `swiftmailer/swiftmailer` and `zendframework/zend-stdlib`, citing Packagist and the Symfony / Laminas announcements.
- A resolved package in `composer.lock` when a rule's `vers` contains that version. Abandoned-package rules match any resolved version of the named package.

Each finding names the file and line, and carries its rule's source, replacement, deadline, migration guidance, and verification commands. A package finding whose rule lists usage matchers also lists the `.php` files that `require` / `include` (and `_once`) that package, and the qualified calls those matchers name (`Class::method` and `new Class`). The finding's impact counts those usages, and a migration packet lists the files. A runtime finding points at the pin only.

### What it intentionally does not judge

- PHP releases and Composer packages with no rule in `registry/php.json`. A missing finding is not evidence that a version is current.
- A `.php-version` or `.tool-versions` value of `system` or `latest`, a template, or a value that interpolates at runtime.
- Composer `require.php` constraints that allow a supported or unlisted release (`>=7.4`, `^8.2`, `^7.4 || ^8.2`).
- Extensions (`ext-*`), floating `*` package constraints, `git` / `path` repositories, and dynamic `${…}` values in `composer.json`.
- An `abandoned` flag in `composer.lock` without a matching lifecycle rule. Composer may mark a package abandoned; Offing reports it only when a reviewed rule names that package.
- Vulnerability advisories and license policy.

### Known limits and false-positive boundaries

- A runtime pin is reported whatever the project actually runs. A stale `.tool-versions` or `config.platform.php` that a project no longer uses still produces a finding.
- `composer.lock` findings include transitive packages, because the lockfile resolves them. A package can be reported even though the project never imports it.
- Package names are matched exactly as written in the file, and a rule matches only the versions its `vers` range names.
- Malformed input produces no declarations from the affected unit, never a partial result, and no error is raised. For `.php-version`, `composer.json`, and `composer.lock` that unit is the whole file. For `.tool-versions` it is the one malformed line. A file over 1 MiB yields nothing, and a single line over 4,096 characters is skipped.
- The eight-level and 500-file limits are silent. Files beyond them, and any under `vendor` or a skipped directory, are not scanned.
- Source usage reads `.php` files. Quoted `require` / `include` (and `_once`) paths match a rule whose module is that path (a trailing `.php` is stripped). A call matches when the rule names the qualified form, such as `Swift_Mailer::newInstance` or `new Zend\Stdlib\Parameters`. Usage is not a PHP AST: it is regex-based matching, so unusual formatting can miss a call or require.
- A `require` or `include` whose argument is not a string literal (a variable, concatenation, or a method call on the string) is listed as unclassified, with its file and line. Offing does not guess which package it loads. `new $class` and `$class::method()` are unclassified for the same reason.
- Usage is not read under `vendor`, `fixtures`, `__fixtures__`, or `testdata`. Comments and ordinary strings are not usages. A single source line over 4,096 characters is skipped for usage scanning, matching the declaration parsers.

---

Source: https://velella.sh/offing/compatibility/ruby/

# Ruby detector

The detector's supported declarations, what it reports, what it intentionally does not judge, and the false-positive boundaries. The matrix and policy it belongs to are on [Compatibility](../COMPATIBILITY.md).

## Ruby detector

The `ruby` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`. 60 public repositories in [Validation](../validation/ecosystems.md#ruby-corpus) cover it. Its lifecycle rules are in `registry/ruby.json` and ship in the [data bundle](../DATA.md).

### Supported files and declarations

| File | Declaration read | Notes |
| --- | --- | --- |
| `.ruby-version` | One pinned version on a line by itself, such as `3.2.2`, `3.2`, `3.2.2p53`, or `ruby-3.2.2` | Blank lines and `#` comments are ignored. A file with more than one version, or any other line, produces nothing. |
| `.tool-versions` | A `ruby` line with one or more pinned versions | Every version on the line is reported. Other tools are ignored. A line with any unsupported token produces nothing. |
| `Gemfile` | The `ruby "3.2.2"` directive, and `gem "name", "version"` with a literal version | A `gem` line with a `git:` or `path:` option is skipped. Only the first literal version on a `gem` line is read. |
| `Gemfile.lock` | The `RUBY VERSION` line, and each resolved gem in the `GEM` section's `specs:` (`name (version)`) | Every resolved gem is checked, including transitive gems. `DEPENDENCIES`, `BUNDLED WITH`, and `GIT` and `PATH` specs are not read. |

Files are found by walking the repository up to eight directories deep, to at most 500 files. Symbolic links are not followed, and `.git`, `node_modules`, `vendor`, `dist`, `build`, `target`, `.venv`, `venv`, `fixtures`, `__fixtures__`, and `testdata` are skipped. Ruby, rbenv, asdf, and Bundler are never run, and nothing is fetched.

### What it reports

- A pinned Ruby release line that is past end of life, in the `.ruby-version`, `.tool-versions`, or `Gemfile` line that pins it, or the `Gemfile.lock` `RUBY VERSION` line. The bundled rules cover Ruby 3.2, 3.1, 3.0, and 2.7, citing the [Ruby maintenance branches](https://www.ruby-lang.org/en/downloads/branches/) page.
- A resolved gem in `Gemfile.lock` that a rule covers. The bundled gem rule covers `json` 2.17.1.1 (yanked), citing its [RubyGems version page](https://rubygems.org/gems/json/versions/2.17.1.1).
- A `Gemfile` gem line is reported only by a rule that covers every version of the gem. The bundled gem rule covers one version, so a `Gemfile` gem line alone produces no finding today.

Each finding names the file and line, and carries its rule's source, replacement, deadline, migration guidance, and verification commands. A gem finding whose rule lists usage matchers also lists the `.rb`, `.rake`, and `.ru` files that `require`, `load`, `gem`, or `autoload` that gem, and the qualified calls those matchers name (including a constant or variable assigned from that constant). The finding's impact counts those usages, and a migration packet lists the files. A runtime finding points at the pin only.

### What it intentionally does not judge

- Ruby releases and gems with no rule in `registry/ruby.json`. A missing finding is not evidence that a version is current.
- A `.ruby-version` or `.tool-versions` value of `system` or `latest`, a template, or a value that interpolates at runtime.
- Gemfile `ruby` directives with options, or a requirement that allows a supported or unlisted release, such as `ruby ">= 3.0"`. A requirement that allows only end-of-life lines (`ruby ">= 2.5", "< 2.7"`) is reported.
- Dependencies declared with no version, `git` or `path` gems, `eval_gemfile`, `gemspec`, or a dynamic value (`ENV[...]`, `#{...}`, `${...}`).
- `required_ruby_version` in a `*.gemspec`. A parser for it exists, but the detector does not read gemspec files yet, so a gemspec never produces a finding.
- Vulnerability advisories and license policy.

### Known limits and false-positive boundaries

- A runtime pin is reported whatever the project actually runs. A stale `.tool-versions` that a project no longer uses still produces a finding.
- `Gemfile.lock` findings include transitive gems, because the lockfile resolves them. A gem can be reported even though the project never imports it.
- Gem names are matched exactly as written in the file, and a rule matches only the versions its `vers` range names.
- A Bundler platform suffix in a lock version (such as `1.15.4-x86_64-linux`) is kept as written and compared as written.
- Malformed input produces no declarations from the affected unit, never a partial result, and no error is raised. For `.ruby-version`, `Gemfile`, and `Gemfile.lock` that unit is the whole file: an unterminated string in a `Gemfile`, a truncated spec in `Gemfile.lock`, or an unsupported line in `.ruby-version` yields nothing from that file. For `.tool-versions` it is the one malformed line. A file over 1 MiB yields nothing, and a single line over 4,096 characters is skipped.
- The eight-level and 500-file limits are silent. Files beyond them, and any under `vendor` or a skipped directory, are not scanned.
- Source usage reads `.rb`, `.rake`, and `.ru` files. `require "json"`, `require "json/ext"`, `load "json.rb"`, `gem "json"`, `autoload :JSON, "json"`, and `Kernel.require "json"` match a rule whose module is `json`. `require_relative` of a literal is a local file and is not a gem import. A call matches when the rule names the qualified form, such as `JSON.parse`, and the source calls it with parentheses (`JSON.parse(` or `JSON::parse(`). `Parser = JSON` or `parser = ::JSON`, and an alias of that alias, counts as the same call. A call without parentheses is not matched.
- A `require`, `load`, `gem`, or `autoload` whose argument is not a string literal (a variable, interpolation, concatenation, or a method call on the string) is listed as unclassified, with its file and line. Offing does not guess which gem it loads. `require_relative` is never unclassified: it always names a local file. A local variable or hash key named `require`/`load`/`gem`, or a bare `load` with no argument, is not a call.
- Alias assignments are capped per file; deep or cyclic alias chains resolve to nothing. A single source line over 4,096 characters is skipped for usage scanning, matching the declaration parsers.
- Usage is not read under `vendor`, `fixtures`, `__fixtures__`, or `testdata`. Comments, ordinary strings, percent literals, heredocs, and `=begin`/`=end` blocks are not usages. A method receiver such as `JSON.load` is a call only when a matcher names it, not a file `load`.

---

Source: https://velella.sh/offing/compatibility/android/

# Android detector

The detector's supported declarations, package URLs, what it reports, what it intentionally does not judge, and the false-positive boundaries. The matrix and policy it belongs to are on [Compatibility](../COMPATIBILITY.md).

## Android detector

The `android` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`. Eighty-four public repositories are pinned for it in `benchmarks/public-repositories/`. Its lifecycle rules are in `registry/android.json` and ship in the [data bundle](../DATA.md). The bundled rules cover Google Play Billing Library majors 5 through 9 and cite the [Google Play Billing Library version deprecation](https://developer.android.com/google/play/billing/deprecation-faq) timeline. Scans read that bundled registry only.

### Supported files and declarations

| File | Declaration read | Notes |
| --- | --- | --- |
| `build.gradle`, `build.gradle.kts` | Literal `compileSdk`, `minSdk`, `targetSdk`, and `buildToolsVersion` inside an `android { }` block, including `defaultConfig`, product flavors, and build types | An API level is a bare or quoted integer (`34`, `"34"`, `= 34`). `buildToolsVersion` is a quoted dotted number (`"34.0.0"`). |
| `build.gradle`, `build.gradle.kts` | A string-notation Maven coordinate on `implementation`, `api`, `compileOnly`, `runtimeOnly`, `testImplementation`, `testRuntimeOnly`, `testCompileOnly`, `annotationProcessor`, `kapt`, `ksp`, `compile`, `runtime`, or `testCompile` | The form is `implementation("group:artifact:version")`, with or without the parentheses. An optional classifier or `@` packaging suffix is not part of the version. |
| `settings.gradle`, `settings.gradle.kts` | A literal `id(...) version "..."` pin (Groovy quotes work too) for `com.android.application`, `com.android.library`, or `org.jetbrains.kotlin.android` | `apply false` still counts. The pin is read wherever it appears in the file. |
| `libs.versions.toml` | `agp` and `kotlin` keys in the `[versions]` table, each a quoted literal version | The file is found by that name at any depth, including `gradle/libs.versions.toml`. |

Files are found by walking the repository up to eight directories deep, to at most 2,000 of these files. Symbolic links are not followed, and `.git`, `node_modules`, `vendor`, `dist`, `build`, `target`, `.gradle`, `.venv`, `venv`, `fixtures`, `__fixtures__`, and `testdata` are skipped. Gradle is never run, and nothing is fetched.

### Package URLs

A string-notation dependency `group:artifact:version` is `pkg:maven/<group>/<artifact>`. An SDK setting is `pkg:generic/android/compileSdk`, `pkg:generic/android/minSdk`, `pkg:generic/android/targetSdk`, or `pkg:generic/android/buildToolsVersion`. An Android Gradle Plugin pin, in settings or the catalog `agp` key, is `pkg:generic/android/agp`. `org.jetbrains.kotlin.android` in settings is `pkg:generic/android/kotlin-android`. The catalog `kotlin` key is `pkg:generic/android/kotlin`, a different identity from the settings plugin.

### What it reports

- A string-notation `com.android.billingclient:billing` version that a bundled rule contains. The rules cover majors 5, 6, 7, 8, and 9.
- A literal `targetSdk` below 35 inside an `android { }` block (`android.target-sdk.existing.default-below-35`).
- An Android Gradle Plugin version, Kotlin Android plugin version, `compileSdk`, `minSdk`, `buildToolsVersion`, or catalog `agp` / `kotlin` pin when a rule for that Package URL contains the version text. No AGP/Kotlin/`compileSdk` rules are bundled today, so those declarations produce no finding until one is added.

The first matching rule wins. A rule whose VERS is malformed, or whose comparison throws, is skipped and does not hide a later rule. Each finding names the file and line, and carries its rule's source, replacement, deadline, migration guidance, and verification commands. A rule that lists usage matchers also lists `.java` and `.kt` usages. The bundled Play Billing rules do not list matchers, so those findings point at the declaration only.

### What it intentionally does not judge

- SDK levels, plugin versions, catalog pins, and Maven coordinates with no rule in `registry/android.json`. A missing finding is not evidence that a version meets Google Play's target API requirement or that a dependency is current.
- JDK pins in the same Gradle file (`sourceCompatibility`, `targetCompatibility`, `jvmToolchain`, `JavaLanguageVersion`). The Java and Kotlin detector reads those.
- Legacy names `compileSdkVersion`, `minSdkVersion`, and `targetSdkVersion`, method calls such as `compileSdk(34)`, and receiver forms such as `ext.minSdk`.
- Values outside an `android { }` block, property references, version-catalog calls, and `$` interpolation.
- Plugin versions written in `build.gradle(.kts)`, `alias(libs.plugins…)` lines, `kotlin("android") version "…"`, the chained `id("…").version("…")` form, and plugin ids other than `com.android.application`, `com.android.library`, and `org.jetbrains.kotlin.android`.
- Catalog keys other than `agp` and `kotlin`, and any version outside `[versions]`, including a `[plugins]` `version` or `version.ref`.
- Map notation (`group:`, `name:`, `version:`), version-catalog library aliases such as `implementation(libs.billing)`, and configuration names outside the list above, such as `debugImplementation` and `androidTestImplementation`.
- Dynamic and ranged versions (`8.+`, `latest.release`, `[8.0, 9.0)`) on plugin and catalog pins.
- Vulnerability advisories and license policy.

### Known limits and false-positive boundaries

- A literal inside `android { }` is reported when a rule matches it, including a product flavor or build type, and including a script the project no longer applies. Offing does not ask Gradle which variant is live.
- A plugin pin is read anywhere in `settings.gradle(.kts)`, including `pluginManagement` and a line marked `apply false`.
- String-notation test configurations are judged the same way as `implementation`.
- A catalog `kotlin` pin and the settings Kotlin Android plugin do not share a Package URL. A rule for one does not match the other.
- An unterminated comment or string, or a Kotlin string template the scanner cannot pair, makes that parser return nothing for the whole file. A `libs.versions.toml` with a multi-line string (`"""` or `'''`) does the same.
- Malformed input produces no declarations from the affected file, never a partial result, and no error is raised. A file over 1 MiB yields nothing, and a single line over 4,096 characters is skipped. Each parser keeps at most 5,000 declarations from one file.
- The eight-level and 2,000-file limits are silent. Files beyond them, and any under `build`, `.gradle`, or another skipped directory, are not scanned.
- A plugin or catalog value that is not a literal version is omitted. A string-notation coordinate is kept and compared as the version text written in the file. The analysis reports no unclassified references.

---

Source: https://velella.sh/offing/detectors/cpp.html

# C and C++

The `cpp` detector reports CMake policy floors that CMake has removed or deprecated, as declared in `cmake_minimum_required`, and matches Conan, vcpkg, language-standard, and compiler declarations when a reviewed rule covers them. It is **supported**: it is scored on the [public corpus](../VALIDATION.md) and held to the corpus precision and recall floors.

## What it reads

| File | Declaration |
| --- | --- |
| `CMakeLists.txt` | `cmake_minimum_required(VERSION <version>)`, `set(CMAKE_C_STANDARD <integer>)`, `set(CMAKE_CXX_STANDARD <integer>)`, and an `if` that names `CMAKE_<LANG>_COMPILER_ID` with `STREQUAL` and `CMAKE_<LANG>_COMPILER_VERSION` with a `VERSION_*` comparison |
| `conanfile.txt` | Each entry of the `[requires]` section, `name/version` |
| `conanfile.py` | The `requires` attribute and literal `self.requires(...)` calls |
| `vcpkg.json` | Top-level `builtin-baseline`, and each direct `dependencies` entry |

It walks the repository up to eight directories deep (at most 500 matching files) and does not follow symbolic links. It skips `.git`, `node_modules`, `vendor`, `dist`, `build`, `target`, `.venv`, `venv`, `fixtures`, `__fixtures__`, and `testdata`. CMake, Conan, and vcpkg are never run, and nothing is fetched.

## What it reports

- A `cmake_minimum_required` version that a `pkg:generic/cmake` rule contains. The bundled rules cover policy versions older than 3.5 (removed in CMake 4.0) and from 3.5 up to 3.10 (deprecated in CMake 3.31).
- A Conan requirement, a vcpkg `version>=` floor, a language standard, or a compiler comparison when a rule for that Package URL contains the version as written. There are no bundled rules for those yet.
- A vcpkg dependency with no `version>=`, only when a rule covers every version of that package.
- A `builtin-baseline` commit when a rule's range contains that string.

Each finding carries its rule's sources, replacement, migration steps, and verification commands. The detector reports no source usages.

## What it intentionally does not judge

- CMake generators and modules. The registry has rules for the Visual Studio 12 2013 generator, FindGDAL, and CMakeFindFrameworks, and the parser does not emit those declarations yet, so they produce no finding.
- Conan and vcpkg packages, language standards, compilers, and baselines with no rule. A missing finding is not evidence that a version is current.
- `cmake_minimum_required` written as a policy range (`VERSION 3.5...3.16`), a value read from a variable, or a generator expression.
- Conan `[tool_requires]` and `[build_requires]`, version ranges, and dynamic Python.
- Feature-scoped vcpkg dependencies and `overrides`.
- Vulnerability advisories and license policy.

## Known limits and false-positive boundaries

- A `version>=` floor is matched as that version, not as every version the constraint allows.
- A compiler check matches the compared version. `VERSION_LESS 9.3` is not read as "this project rejects compilers older than 9.3."
- Malformed input produces no declarations from that file, never a partial result, and no error is raised. A file over 1 MiB yields nothing, and a single line over 4,096 characters is skipped.
- The eight-level and 500-file limits are silent. Files beyond them, and any under `build`, `vendor`, or another skipped directory, are not scanned.

## Data

The rules are in `registry/cpp.json` and ship in the [data bundle](../DATA.md). The `cpp-1` importer drafts CMake policy compatibility rules from the `cmake_minimum_required` page for review; see [Lifecycle importers](../IMPORTERS.md).

## Validation

The corpus holds 15 pinned C/C++ ecosystem repositories: eleven with reviewed findings in that folder and four with none (`catchorg/Catch2`, `j2kun/mlir-tutorial`, `rogerorr/NtTrace`, and `jagheterfredrik/meb-preheat`). Across every ecosystem the corpus expects 242 `cpp` findings in 20 repositories. Of the 15 C/C++ entries, 11 were selected blind (73%). Every expected finding was checked by reading its line at the pinned commit; notes cite maintainer migration commits or the CMake policy documentation rather than Offing's output. Method and selection rules are in [Validation](../VALIDATION.md).

---

Source: https://velella.sh/offing/compatibility/ci-runner-images/

# CI runner images detector

The detector's supported declarations, what it reports, what it intentionally does not judge, and the false-positive boundaries. The matrix and policy it belongs to are on [Compatibility](../COMPATIBILITY.md).

## CI runner images detector

The `ci-images` detector is **supported**: its level is recorded as `stable` in `benchmarks/thresholds.json`. 98 public repositories are pinned for it (see [the corpus](../validation/ecosystems.md#ci-runner-images-corpus)), 67 of them selected blind (68%); precision and recall are enforced. Its lifecycle rules are in `registry/ci-images.json` and ship in the [data bundle](../DATA.md). Bundled rules include the scheduled removals of the macOS 14 Sonoma and Ubuntu 22.04 hosted images, citing the [Microsoft-hosted image deprecation schedule](https://learn.microsoft.com/azure/devops/pipelines/agents/hosted-deprecation-schedule). A label is a finding only when a reviewed rule covers it. Scans read that bundled registry only.

### Supported files and declarations

| File | Declaration read | Notes |
| --- | --- | --- |
| `azure-pipelines.yml` | Literal `pool.vmImage` on the pipeline, a stage, or a job | The label is matched when it is `ubuntu-<version>`, `macos-<version>`, or `windows-<version>`, compared case-insensitively. |
| `.gitlab-ci.yml` | Root and job `image` values, including an image object's `name`, and image values in `services` | Every located value is unclassified. None become findings. |
| `.circleci/config.yml` | `docker.image` and `machine.image` under `jobs` and `executors`, and string values under `orbs` | Orbs, dynamic values, and floating aliases are unclassified. A literal image is parsed and not judged. |

Only a file named `.gitlab-ci.yml`, `azure-pipelines.yml`, or `config.yml` directly inside a `.circleci` directory is read. Files are found by walking the repository up to eight directories deep, to at most 500 files. Symbolic links are not followed, and `.git`, `node_modules`, `vendor`, `dist`, `build`, `bin`, `obj`, `target`, `.venv`, `venv`, `fixtures`, `__fixtures__`, and `testdata` are skipped. GitLab CI, CircleCI, and Azure Pipelines are never run, and nothing is fetched.

### What it reports

- An Azure `pool.vmImage` whose family and numeric version a rule's Package URL and `vers` range contain. The finding is the value's line. It carries the rule's source, replacement, deadline, and migration guidance when the rule has it. Every matching rule is reported.
- Nothing for a GitLab image or service, a CircleCI image or orb, or an Azure label no rule covers. An unclassified reference is not a finding.

### What it intentionally does not judge

- GitLab CI images and services. Decision 0014 records no authoritative GitLab lifecycle source, so a literal image is not evidence that GitLab retired it.
- CircleCI `docker.image` and `machine.image` values, including ones that look old. This version has no CircleCI Package URL mapping, so a literal image is not matched against a rule. Orb references are not image lifecycle claims, and their remote contents are not read.
- `latest`, `ubuntu-latest`, `macos-latest`, `windows-latest`, and other `*-latest` or `:latest` aliases. `cimg/<name>:current` is floating too.
- Dynamic values: `$IMAGE`, `${IMAGE}`, `$(vmImage)`, `<< parameters.image >>`, `<< pipeline.parameters.image >>`, and any value that contains `$` or `<<`.
- Azure labels outside `ubuntu-`, `macos-`, and `windows-` plus a numeric version, including `ubuntu-22.04-arm64` and `windows-2025-vs2026`.
- A pool written as a string, a pool `name` without `vmImage`, containers, resources, and `strategy.matrix` `vmImage` entries.
- CircleCI workflow executor references, `resource_class`, descriptions, and a job that only names an orb executor.
- Comments, unrelated keys, unresolved YAML aliases, merge keys, non-string values, and malformed YAML.
- Vulnerability advisories. A newer image existing is not a lifecycle finding.

### Known limits and false-positive boundaries

- An Azure label is reported when a rule matches the text, including a pipeline the project no longer runs, and including a self-hosted agent that reuses a hosted label string. Offing does not ask Azure DevOps which pipeline is active.
- GitLab and CircleCI references that are unclassified name the file and line. A literal CircleCI image is omitted from both findings and unclassified references.
- Malformed YAML produces no declarations from that file, never a partial result, and no error is raised. A file over 1 MiB yields nothing, and a single value over 4,096 characters is skipped.
- The eight-level and 500-file limits are silent. Files beyond them, and any under a skipped directory, are not scanned.

---

Source: https://velella.sh/offing/compare/index.html

# Offing compared with other tools

Offing answers one question: **what in this repository is ending, and where is it used?**
Update bots and lifecycle databases answer neighbouring questions. This section states what each
tool is good at, links the evidence for every claim, and says where Offing is the weaker choice.

| Tool | Question it answers | Start with |
| --- | --- | --- |
| Renovate | Which dependencies have newer versions, and can the update be automated? | [Renovate compared](renovate.md) |
| Dependabot | Which dependencies have updates or security advisories on GitHub? | [Dependabot compared](dependabot.md) |
| endoflife.date | When does a product or release line stop receiving support? | [endoflife.date compared](endoflife-date.md) |

## Where Offing differs

- **Evidence, not just a version number.** Every rule names its sources and the date a maintainer
  reviewed it ([RULES.md](../RULES.md)); scans report the data version and age
  ([DATA.md](../DATA.md)).
- **Locations.** Findings point at the exact declaration or usage
  ([ARCHITECTURE.md](../ARCHITECTURE.md)), including retired APIs inside source files, which
  manifest-only tools cannot see.
- **Offline and deterministic.** Scans read local files and bundled data only
  ([DATA.md](../DATA.md)); no account or hosted service is involved.

## Measured, not asserted

Where Offing and Renovate can speak about the same dependency in the same file, the
[differential report](../differential-report.md) compares their results on a pinned corpus and links
the evidence for each disagreement, including the cases Renovate finds and Offing misses. The
method is described in [VALIDATION.md](../VALIDATION.md#differential-testing-against-renovate).

---

Source: https://velella.sh/offing/AGENT_SKILLS/

# Offing Agent Skills

Offing ships one portable Skill under `skills/offing/`. It follows the open Agent Skills directory format: standard YAML frontmatter plus Markdown instructions. There is no vendor-specific manifest, invocation policy, tool allowlist, script, or generated prompt.

| Workflow in the Skill | Moment |
| --- | --- |
| Scan and migrate | Repository lifecycle scans and finding explain / migrate / verify |
| Check before adding | Adding or choosing a package, runtime, or GitHub Action |
| Upgrade a runtime or Action | Upgrading an already-declared runtime or GitHub Action |

New to the dependency guardrail? Follow the tutorial [Stop your coding agent from adding deprecated packages](guides/agent-dependency-guard.md).

## Design

The Skill is an orchestration layer. It tells an agent when to act, then maps those intents to Offing's MCP tools or CLI commands. Lifecycle rules, evidence, affected-file calculation, migration steps, and verification behavior remain in the executable and versioned JSON contracts.

This prevents prompt drift: improving a detector or migration packet changes every client without requiring a rewritten Skill. The Skill opens with a table that routes the task to one of its three workflows, so a single install covers all three moments.

## Installation

The skills CLI discovers the Skill directly from the Offing monorepo. No dedicated distribution repository is needed:

```sh
npx skills add velella-sh/offing
```

For a non-interactive or explicitly selected install, use:

```sh
npx skills add velella-sh/offing --skill offing --yes
```

Update it with:

```sh
npx skills update offing
```

The npm package also includes the complete `skills/offing` folder for hosts that prefer a manual copy or link.

To tell the agents working in any other project to check dependencies with Offing, copy the snippet in [examples/agents-snippet.md](../examples/agents-snippet.md) into `AGENTS.md`, `CLAUDE.md`, or a similar instruction file.

The host also needs one Offing execution path:

- the local `offing mcp` stdio server; or
- the `offing` CLI available on `PATH`.

No account or API key is required.

## One-command install per host

Each host below gets the Skills with one install command. Claude Code and Codex also receive the local MCP server through the same plugin ([MCP](MCP.md#one-command-install-per-host)). Cursor and VS Code need the MCP server separately. Every command was run in a clean environment on 2026-10-29 (macOS, Node.js 22).

Shared verify prompt after install: ask the agent to `Add the request package to this project`, and confirm it checks `pkg:npm/request` (via `check_dependency` or `npx @velella/offing check`) and reports the deprecation with a replacement and sources instead of adding the package.

### Claude Code

```sh
claude plugin install offing --marketplace velella-sh/offing
```

**Verify.** `claude plugin list` shows `offing@offing` enabled, and `claude plugin details offing` lists both Skills. Start a new session and use the shared verify prompt.

Portable skills-CLI alternative: `npx skills add velella-sh/offing --agent claude-code --yes`, then `npx skills list`.

### Codex

```sh
codex plugin marketplace add velella-sh/offing --ref main && codex plugin add offing@offing-codex
```

When the Offing repository marketplace is already configured, `codex plugin add offing@offing-codex` alone is enough.

**Verify.** Restart the Codex session, run `codex plugin list --json`, and confirm `offing@offing-codex` is installed. Then use the shared verify prompt.

Portable skills-CLI alternative: `npx skills add velella-sh/offing --agent codex --yes`, then `npx skills list`.

### Cursor

```sh
npx skills add velella-sh/offing --agent cursor --yes
```

**Verify.** `npx skills list` shows `offing`. Restart Cursor, then use the shared verify prompt. For the MCP server, see [MCP](MCP.md#one-command-install-per-host).

### VS Code

VS Code Copilot Chat picks up the Skills through the skills CLI's `github-copilot` target:

```sh
npx skills add velella-sh/offing --agent github-copilot --yes
```

**Verify.** `npx skills list` shows `offing`. Reload the VS Code window, open Copilot Chat in Agent mode, then use the shared verify prompt. For the MCP server, see [MCP](MCP.md#one-command-install-per-host).

## One Skill for every ecosystem

Offing briefly shipped four per-ecosystem Skills (Node.js, Python, GitHub Actions, containers) and removed them in favor of one Skill. They were near-copies that differed only by a rule-prefix filter, so every workflow change had to be made five times, they could trigger together on one request, and they covered four of the ecosystems Offing supports. The claim that narrower descriptions trigger more reliably was never measured for that split. A later split by *moment* produced `offing-check-before-add` and `offing-upgrade-runtime-action` next to `offing`. Those were merged back into the single `offing` Skill (2026-11-11) so there is one install, one skills.sh entry, and one description to maintain; the three moments are now sections of that Skill and keep their own eval corpora below. If a measurement shows a gain from splitting, split then.

The ecosystem-specific cautions live in the lifecycle Skill's "Ecosystem notes".

## Use the guardrail in this repository

Agents working on Offing itself follow the same rule the Check before adding workflow teaches: run `offing check <purl>` before adding any dependency, runtime, or Action. Install the Skill as above, or run the check from source, which needs nothing else:

```sh
npm run dev -- check pkg:npm/request@2.88.2
```

The rule is stated for contributors in [AGENTS.md](../AGENTS.md#dependencies), and the `self-scan` CI job backs it up by failing on any finding the baseline does not cover (see [ADOPTION.md](ADOPTION.md#scanning-this-repository)).

## Discovery and host compatibility

On 2026-10-15, `npx skills add velella-sh/offing --list` discovered the `offing` Skill. A clean project installation then selected and installed that Skill for five representative skills CLI targets:

| Host | `--agent` value | Install result |
| --- | --- | --- |
| Codex | `codex` | Passed |
| Claude Code | `claude-code` | Passed |
| Cursor | `cursor` | Passed |
| GitHub Copilot | `github-copilot` | Passed |
| Gemini CLI | `gemini-cli` | Passed |

The same install registered the Skill with skills.sh. It is discoverable as `velella-sh/offing@offing` at [skills.sh](https://skills.sh/velella-sh/offing/offing). The skills CLI security summary reported Gen Agent Trust Hub **Safe**, Socket **0 alerts**, and Snyk **Low Risk** at validation time. These external assessments can change and do not replace review of the installed files.

## Evaluation

### Scan-and-migrate workflow

Each workflow keeps its own corpus and trigger proxy under `skills/offing/evals/`. The Skill triggers on the union of the three; the gates below apply to each workflow, and the separation check keeps them from claiming each other's prompts.

Trigger evaluation cases live in `skills/offing/evals/cases.json`. The versioned corpus contains 114 prompts: 54 expected triggers and 60 expected non-triggers, including 24 deliberately ambiguous requests and six add-a-dependency prompts that must not select this Skill. Each of the `agent-skills`, `codex`, and `claude` discovery lanes has 38 cases.

Run the deterministic metadata-selection proxy from the repository root:

```sh
npm run eval:skill-triggers
```

The command builds the evaluator, prints JSON results overall and by host lane, lists any failed case IDs, and exits unsuccessfully when the corpus has fewer than 50 cases, recall is below 90%, or the false-trigger rate is 5% or higher. It has no model, network, account, or API-key dependency, so CI and contributors can reproduce the same baseline.

Current published baseline:

| Lane | Cases | Recall | False-trigger rate |
| --- | ---: | ---: | ---: |
| All | 114 | 100% | 0% |
| Agent Skills | 38 | 100% | 0% |
| Codex | 38 | 100% | 0% |
| Claude | 38 | 100% | 0% |

### Tuning the description

The first published corpus was written against the description's concepts, so it passed completely and could not show whether the wording covered everyday requests. Expanding it to 108 cases exposed both directions of the problem:

| Measurement | Cases | Recall | False-trigger rate |
| --- | ---: | ---: | ---: |
| Previous description, expanded corpus | 108 | 79.6% | 7.4% |
| Tuned description and proxy | 108 | 100% | 0% |

Fifteen cases failed before the change. Eleven trigger requests missed because the description did not name support and maintenance status, container base images, or finding and verification work without the product name. Four non-goals falsely triggered because "deprecated" plus a manifest or a supported runtime was enough to cross the boundary, even when the request was about an npm script, a React hook, a Python function, or a Node API. The revised description states those boundaries, and the deterministic proxy that encodes it now requires a lifecycle status before a source-API or configuration request counts as a trigger. The gates are unchanged.

This is a contract test for the concepts exposed by the skill metadata, not a claim that every model version will make an identical routing decision. Live host checks can add observations without weakening the deterministic CI gate. Generic dependency upgrades, vulnerability or security audits, deprecated source APIs, project scripts, configuration, and unrelated modernization are explicit negative cases.

### Check-before-add workflow

`skills/offing/evals/check-before-add.json` measures the add-a-dependency moment: 54 prompts, 27 expected checks and 27 that should not trigger one, split evenly across the three discovery lanes. Positives add or choose a dependency in npm, PyPI, and GitHub Actions terms (`npm install request-promise`, `Add actions/checkout@v4 to the CI workflow`, `Which package should I use for date handling?`). Negatives are removals, installs of what the lockfile already declares, routine upgrades, `dependency injection`, tests, documentation, refactors, and repository lifecycle prompts that belong to `offing`.

`npm run eval:skill-triggers` reports recall and false-trigger rate for it under `dependencyGuard` (workflow `check-before-add`), overall and by lane, with the same gates (at least 40 cases, recall of 90% or more, false-trigger rate under 5%). It also fails when one workflow's positive prompts falsely trigger another workflow's classifier (`separation` in the JSON output).

Current published baseline:

| Lane | Cases | Recall | False-trigger rate |
| --- | ---: | ---: | ---: |
| All | 54 | 100% | 0% |
| Agent Skills | 18 | 100% | 0% |
| Codex | 18 | 100% | 0% |
| Claude | 18 | 100% | 0% |

### Upgrade runtime or Action workflow

Issue #1598 asked whether to add a further Skill for runtime upgrades and GitHub Actions upgrades. The decision corpus is the 24 positive prompts in `skills/offing/evals/upgrade-runtime-action.json` (12 runtime, 12 Actions; natural phrasing and lifecycle-worded asks, split across the three discovery lanes). Measuring the scan-and-migrate description alone on those prompts:

| Measurement | Cases | Covered by scan-and-migrate | Rate | Threshold | Decision |
| --- | ---: | ---: | ---: | ---: | --- |
| Runtime and GitHub Actions upgrade job | 24 | 12 | 50% | 80% | Added an upgrade workflow |

Misses were everyday upgrade asks without lifecycle jargon (`Upgrade our Node.js runtime to the current LTS.`, `Bump actions/checkout and actions/setup-node.`, and ten peers). Lifecycle-worded upgrades still hit the scan description; the upgrade workflow names the upgrade moment so those misses are covered.

The same JSON file is the workflow's own trigger corpus: 42 prompts, 24 expected triggers and 18 non-triggers (additions, whole-repo scans, routine package bumps, security, docs, and verification). `npm run eval:skill-triggers` reports it under `upgradeRuntimeAction` with the same gates (at least 40 cases, recall of 90% or more, false-trigger rate under 5%) and fails when its positives falsely trigger the check-before-add classifier or the reverse. Because the three workflows now share one Skill, the proxies remain per-workflow concept checks; there is no single-description union metric.

Current published baseline:

| Lane | Cases | Recall | False-trigger rate |
| --- | ---: | ---: | ---: |
| All | 42 | 100% | 0% |
| Agent Skills | 14 | 100% | 0% |
| Codex | 14 | 100% | 0% |
| Claude | 14 | 100% | 0% |

CI also validates the portable frontmatter, small instruction surface, vendor neutrality, complete tool mapping, and safety invariants.

Independent forward tests exercise three different agent situations:

| Agent situation | Observable success criterion | Result |
| --- | --- | --- |
| Skill discovery | Classify every trigger and non-trigger case through the metadata contract without reading expected answers. | Lifecycle, check-before-add, and upgrade-runtime-action corpora all pass across three lanes. |
| MCP-capable agent | Discover, explain, create context, migrate, and verify through the real stdio protocol in one session. | Passed with all five tools; checkout finding verified absent. |
| CLI-only agent | Complete the same lifecycle using only documented CLI fallbacks and a fresh final scan. | Passed; request migration changed only two packet files and ended with zero findings. |

Forward-test observations are recorded on the Week 11 GitHub issue when the phase is completed. Discovery testing narrowed an ambiguous generic migration trigger to migrations from Offing findings. CLI testing replaced the packet's `npx` rescan suggestion with the already-installed `offing` executable so verification remains offline-capable and version-consistent. MCP testing clarified that an empty usage list means there are no additional usages beyond the declaration, rather than implying that the declaration itself is not relevant.

## Limits and security assumptions

- Offing currently covers its documented GitHub Actions, Node.js, npm, and Python rules. The Skills report unsupported ecosystems instead of inventing migration advice.
- Dynamic references that detectors cannot classify remain explicit limitations.
- MCP verification needs the same server session that observed the finding. The CLI fallback uses a fresh scan and conservatively compares the rule and declaration path.
- The Skills grant no permissions. Suggested verification commands remain subject to the host's normal authorization rules.
- The bundles contain no executable skill scripts and declare no pre-approved tools.
- Installing through the skills CLI copies or links instruction files into the selected host's Skill directory; it does not install the Offing runtime itself.
- Repository analysis remains local. The selected host receives structured Offing results, which can include paths and short source excerpts, so its own privacy policy still applies.

---

Source: https://velella.sh/offing/SITE_STACK/

# Offing and Slipway

Two tools share the work on a [Slipway](https://github.com/arminazimi/slipway)-shaped Jekyll site for GitHub Pages. Each one owns a different question. Use them in order so an agent (or a human) does not mix lifecycle evidence with site layout concerns.

| Tool | Owns | Maturity |
| --- | --- | --- |
| **Offing** | Whether a gem, npm package, GitHub Action, or runtime line is deprecated or end-of-life, with evidence | Shipped (`offing` on npm) |
| **Slipway** | The Jekyll theme, layout, and Pages-oriented site stack | In planning and dogfooding; use only what its repository documents |

Offing runs locally against files on disk. It does not send your repository to a cloud service during a check or scan.

## The agent loop

Work in this order when you change dependencies or site content.

### 1. Before adding a gem, package, or Action

Check the dependency with Offing **before** you edit `Gemfile`, `package.json`, or workflow `uses:` pins.

```bash
npx @velella/offing check pkg:rubygems/jekyll@4.3.4
npx @velella/offing check pkg:npm/typescript@5.4.5
npx @velella/offing check pkg:github/actions/checkout@v4
```

Or, if the CLI is on your `PATH` as `offing`:

```bash
offing check pkg:rubygems/jekyll@4.3.4
```

- If the result is `affected`, prefer the replacement Offing names and cite its evidence links. Do not add the dependency without telling the user why.
- `version-dependent` means the answer depends on the version — call again with the version you intend to lock.
- `no-data` means Offing has no rule for that package; it is **not** a claim that the package is safe.

For Ruby gems on a Pages site, also keep an eye on the Ruby runtime line (`.ruby-version`, `Gemfile`, `Gemfile.lock`) — GitHub Pages builds with a fixed Ruby line that must still receive fixes.

### 2. Edit pages and configuration

Change Markdown, `_config.yml`, layouts, and workflows as the task requires. Slipway-specific behavior follows the Slipway repository and starter; do not assume features that are not documented there.

Copy the Offing CI starter when the site has no lifecycle gate yet: [examples/starters/slipway/](../examples/starters/slipway/).

## Which output to trust for what

| Question | Trust |
| --- | --- |
| Is this gem, package, or Action deprecated or end-of-life? | Offing `check` (or repository `scan`) — lifecycle rules with sources |
| What is already declared in this repo? | Offing `scan` on the tree — findings at exact paths |

Offing answers **lifecycle** questions with reviewed rules. A clean Offing scan does not mean the site's links work or that a new gem is safe in other ways.

## Wire this into your agent

Copy [examples/agents/site-stack/AGENTS.md](../examples/agents/site-stack/AGENTS.md) into the site repository (merge with your existing `AGENTS.md` if you already have one). It repeats the loop in imperative form for coding agents.

Related:

- [Offing for your agent](AGENTS_SETUP.md) — MCP, hooks, and host-specific setup
- [Slipway starter kit](../examples/starters/slipway/) — `.offing.json` and a pull-request workflow
- [Dependency check snippet](../examples/agents/dependency-check.md) — short guardrail text you can paste anywhere

---

Source: https://velella.sh/offing/RULES/

# Lifecycle rules

Every lifecycle claim Offing makes comes from a rule in [Ebb](https://github.com/velella-sh/ebb), the open lifecycle dataset Offing reads through the `@velella/ebb` package. A rule says which component is affected, in which versions, what happened to it, who says so, and when that was last checked. This page is the reference for writing one and for the fixtures that prove a detector reports it.

The rules live in Ebb's [`registry/`](https://github.com/velella-sh/ebb/tree/main/registry), and a rule is added or corrected with one pull request there; Ebb lints it and checks its purl cases. This repository holds the detectors and, for a rule that needs them, the fixtures under `tests/fixtures/<rule-id>/`. When a new Ebb release reaches this repository, every rule with fixtures runs again.

The format is `ebb.registry.v2`. Its JSON Schema is [`schemas/registry.v2.schema.json`](https://github.com/velella-sh/ebb/blob/main/schemas/registry.v2.schema.json) in Ebb, and the reasoning is in [Decision 0004](decisions/0004-registry-v2.md).

## From a source to a merged pull request

This walkthrough follows one real rule, `npm.package.request.deprecated` ([below](#a-complete-rule)), from the notice that justifies it to the pull request that adds it. The reference sections explain each field; this is the order to work in.

### 1. Find the claim and its source

Open the authoritative notice. For `request` it is the deprecation notice on the package's [npm page](https://www.npmjs.com/package/request). Write down:

- the URL, and the day you read it;
- the affected versions;
- the event, in the source's words;
- what the source says, and separately what a maintainer recommends instead;
- any date the source gives.

If the notice is vague about versions, the event, or a date, do not guess: say so in the issue. A rule without an authoritative source is not a rule; see [Evidence policy](#evidence-policy).

### 2. Add the rule to Ebb

Open a pull request in [Ebb](https://github.com/velella-sh/ebb) that adds the rule to `registry/<ecosystem>.json`, with a case in `cases/<ecosystem>.json`: a version the rule must match and one it must not. Ebb's [rule guide](https://github.com/velella-sh/ebb/blob/main/docs/RULES.md) walks through every field, and [A complete rule](#a-complete-rule) below is the finished `request` rule. Once it is merged and released, the rule reaches every user of Ebb, Offing included, without a change here.

### 3. Scaffold the fixtures here

When a detector has to prove it reports the rule, update `@velella/ebb` in a checkout of this repository and scaffold the fixtures:

```bash
git switch -c rule/<name>-deprecated
npm ci
npm install @velella/ebb@latest
npm run build
node dist/src/cli.js new-rule npm.package.<name>.deprecated
```

`new-rule` looks the id up in the installed `@velella/ebb` and refuses one that Ebb does not define or that already has fixtures. Otherwise it creates `tests/fixtures/<rule-id>/match/` and `clean/`, each with a placeholder source file and a README.

### 4. Write both fixtures

Replace the generated source files with the smallest repository that shows the behavior:

```js
// tests/fixtures/npm.package.request.deprecated/match/index.js
const request = require("request");

request.get("https://example.com/health"); // reported
```

```js
// tests/fixtures/npm.package.request.deprecated/clean/index.js
const request = { get() {} }; // not reported: a local object, not the package

request.get("https://example.com/health");
```

Both directories are scanned offline as untrusted repositories and nothing in them is executed. The `match` fixture must report the rule and `clean` must not; a lookalike that is reported is a bug in the rule or the analysis. Keep only the files the detector reads.

### 5. Run the checks locally

```bash
node dist/src/cli.js rules test <rule-id>
npm run build:reference
npm run check
```

- `rules test` scans both fixtures and prints the expected and actual observations. It needs both directories, so when you edit a rule that predates the fixture harness, add the two fixtures in the same pull request instead of skipping the check.
- A rule that only `offing inventory` judges (Google App Engine runtimes, GKE cluster versions) has no repository file for a detector to read. Put the cloud export in each fixture as a `.json` file, such as `app-engine-versions.json` or `gke-clusters.json`; `rules test` runs the inventory importers over those files and observes the rule when an item matches it.
- `build:reference` rewrites `docs/rules/<rule-id>.md` from the registry; CI fails when the committed pages drift. `docs/rules/index.md` and `docs/sitemap.xml` are gitignored and rebuilt by Pages with `--site`.
- `npm run check` is the same gate CI runs: build, full tests, plugin checks, and evals.

If the analysis is wrong rather than the rule, fix the detector in the same pull request and say so.

### 6. Open the pull request

```bash
git add package.json package-lock.json docs/rules/npm.package.request.deprecated.md tests/fixtures/npm.package.request.deprecated
git commit -m "test(npm): add fixtures for the request deprecation rule"
git push -u origin rule/request-deprecated
gh pr create --title "test(npm): add fixtures for the request deprecation rule" --body "Closes #<issue>"
```

Fill the template: the evidence link goes under **Evidence**, the commands you ran under **Verification**. A maintainer checks that the clean fixture is a fair lookalike and that the detector reports the rule where the source says it applies. Keep one rule per pull request.

After the rule is merged in Ebb, Ebb's weekly [source check](https://github.com/velella-sh/ebb/blob/main/.github/workflows/sources.yml) watches the link. When the source changes, the rule is reviewed there; see [Freshness and sources](#freshness-and-sources).

## A complete rule

```json
{
  "schemaVersion": "ebb.registry.v2",
  "ecosystem": "npm",
  "freshness": { "maxReviewAgeDays": 365 },
  "rules": [
    {
      "id": "npm.package.request.deprecated",
      "ecosystem": "npm",
      "purl": "pkg:npm/request",
      "vers": "vers:npm/*",
      "event": "deprecated",
      "title": "request is deprecated",
      "summary": "The package is fully deprecated and no new changes are expected.",
      "severity": "high",
      "replacement": "Native fetch or a maintained HTTP client",
      "deadline": "2020-02-11",
      "sources": [
        {
          "title": "request package deprecation notice",
          "url": "https://www.npmjs.com/package/request",
          "accessedAt": "2026-10-13"
        }
      ],
      "provenance": {
        "observedAt": "2026-10-13",
        "reviewedAt": "2026-10-14",
        "reviewer": "arminazimi"
      },
      "migration": {
        "constraints": ["Preserve request method, headers, authentication, redirects, and error semantics at each call site."],
        "steps": [
          { "id": "replace-request-calls", "title": "Rewrite request usages", "instructions": "Translate each reported import and call to native fetch or a maintained client.", "targets": "usages" }
        ],
        "verification": [
          { "command": "npm run test --if-present", "purpose": "Run the repository tests when defined." }
        ]
      },
      "usage": [
        { "kind": "import", "language": "javascript", "module": "request" }
      ],
      "x-npm": { "package": "request" }
    }
  ]
}
```

A second, smaller example lives in [`examples/registry.v2.example.json`](../examples/registry.v2.example.json). The files in Ebb's [`registry/`](https://github.com/velella-sh/ebb/tree/main/registry) are the best reference for each ecosystem.

## The registry file

| Field | Required | Meaning |
|---|---|---|
| `schemaVersion` | yes | Always `ebb.registry.v2`. |
| `ecosystem` | yes | A lowercase slug such as `npm`. Every rule in the file must use the same value. |
| `freshness.maxReviewAgeDays` | no | How long a rule may go without review before the weekly check reports it stale. Defaults to 365. |
| `rules` | yes | The rules, in the order detectors should consider them. |

## A rule

| Field | Required | Meaning |
|---|---|---|
| `id` | yes | Stable and unique, lowercase with dots and hyphens, for example `npm.package.request.deprecated`. Baselines and reports refer to it, so do not rename it. |
| `ecosystem` | yes | Matches the registry's `ecosystem`. |
| `purl` | yes | The affected component as a [Package URL](https://github.com/package-url/purl-spec), canonical and **without a version**: `pkg:npm/request`, `pkg:npm/%40angular/core`, `pkg:pypi/django-nose`, `pkg:github/actions/checkout`. Runtimes with no registry use `pkg:generic/<name>`, for example `pkg:generic/nodejs`. |
| `vers` | yes | The affected versions as a [VERS](https://github.com/package-url/vers-spec) range, for example `vers:npm/*` (every version), `vers:semver/<5.0.0`, `vers:semver/>=20.0.0\|<21.0.0`, `vers:pypi/<3.10`. Write it in canonical form: no spaces, no explicit `=`, constraints sorted by version. |
| `event` | yes | What happened, or what has been announced: `deprecated`, `end-of-support`, `end-of-life`, `removed`, or `scheduled-end-of-life`. Use the word the source uses; see [Choosing an event](#choosing-an-event). |
| `title` | yes | One line that names the problem. |
| `summary` | yes | One or two sentences stating what the source says, without advice. |
| `severity` | yes | `info`, `low`, `medium`, `high`, or `critical`. |
| `replacement` | no | What to move to. |
| `requires` | no | The lowest runtime versions the replacement works on, such as `{ "node": "18.0.0" }`. Only `node` and `python` are known. A migration packet warns when the repository pins an older runtime. |
| `deadline` | no | The date from the source, as `YYYY-MM-DD`. Omit it when the source gives none. |
| `sources` | yes | At least one authoritative source, each with a `title`, an `https` `url`, and the `accessedAt` day you read it (`YYYY-MM-DD`). The date ships with every finding. |
| `provenance` | yes | See below. |
| `migration` | no | Constraints, ordered steps, and verification commands. Used by `offing context`. Step `targets` are `declaration`, `usages`, or `all`; step ids are unique within the rule. |
| `usage` | no | Imports, calls, configuration keys, and deprecated symbols that show where a repository depends on the component. See [Symbol-level usage](#symbol-level-usage). |
| `x-<ecosystem>` | no | Matching hints the ecosystem's detector reads, such as `x-npm.package`, `x-nodejs.major`, `x-python.kind`, or `x-github-actions.supportedFromMajor`. See [Detector hints](#detector-hints). |

### Symbol-level usage

A `usage` entry of kind `symbol` marks one deprecated function, method, class, or option inside a module, so a rule can say `ReactDOM.render` is deprecated without flagging all of `react-dom`. `purl` and `vers` still say which package versions are affected; the entry says which symbol.

| Field | Required | Meaning |
|---|---|---|
| `kind` | yes | `symbol`. |
| `language` | yes | `javascript`, `typescript`, or `python`. Write one entry per language. |
| `module` | no | The module that exports the symbol, as it is imported: `react-dom`, `datetime`. Omit it for globals and builtins such as `Buffer` or `open`. |
| `symbol` | yes | Dotted path from the module: `render`, `Buffer.alloc`, `datetime.utcnow`. Identifier segments only. |
| `shape` | yes | How the symbol is used: `call`, `construct` (`new X()`, JavaScript and TypeScript only), `reference` (any other use, such as passing it as a value), `method` (called on any receiver inside a class that subclasses `unittest.TestCase` or `TestCase`, Python only), or `option` (a deprecated property in the call's options object). |
| `option` | when `shape` is `option` | The deprecated property name. Not allowed for other shapes. |
| `argument` | no | For `option`: zero-based position of the options argument. Defaults to the last argument. |
| `replacement` | no | What to use instead of this symbol. It overrides the rule's `replacement` in reports. |

Symbol entries are read by parser-backed usage analysis. Regex-based analysis ignores them, so a rule that has only symbol entries reports the declaration but no usages until that analysis runs. Add an `import` entry for the module as well when you want the regex scanner to find it. A hit is reported as a usage of kind `symbol` at the first identifier of the name (at the property name for `option`), with the module and symbol as its `symbol` text, such as `fs.exists` or `fs.rmdir(recursive)`. Names are followed through imports, `require`, destructuring, aliases, and a `node:` prefix, and a global such as `Buffer` is not reported when the file imports or declares that name itself. Scopes are not modelled, so a local variable that shadows an imported name can be reported. For Python, an `option` matches a keyword argument anywhere in the call, or a positional argument at `argument`. Each symbol entry needs its own evidence: the rule's `sources` must name the symbol, not only the package.

A complete rule, also in [`examples/registry.v2.symbol.example.json`](../examples/registry.v2.symbol.example.json):

```json
{
  "schemaVersion": "ebb.registry.v2",
  "ecosystem": "npm",
  "freshness": {
    "maxReviewAgeDays": 365
  },
  "rules": [
    {
      "id": "npm.symbol.react-dom.render.deprecated",
      "ecosystem": "npm",
      "purl": "pkg:npm/react-dom",
      "vers": "vers:npm/>=18.0.0",
      "event": "deprecated",
      "title": "ReactDOM.render is deprecated",
      "summary": "React 18 deprecates ReactDOM.render; it runs the app in React 17 mode and logs a warning.",
      "severity": "medium",
      "replacement": "createRoot from react-dom/client",
      "sources": [
        {
          "title": "React 18 upgrade guide: react-dom render",
          "url": "https://react.dev/blog/2022/03/08/react-18-upgrade-guide",
          "accessedAt": "2026-10-19"
        }
      ],
      "provenance": {
        "observedAt": "2026-10-19",
        "reviewedAt": "2026-10-19",
        "reviewer": "arminazimi"
      },
      "migration": {
        "constraints": [
          "Keep the application's root container and rendered tree unchanged."
        ],
        "steps": [
          {
            "id": "use-create-root",
            "title": "Switch to createRoot",
            "instructions": "Replace each reported render call with createRoot(container).render(element).",
            "targets": "usages"
          }
        ],
        "verification": [
          {
            "command": "npm run test --if-present",
            "purpose": "Run the repository tests when defined."
          }
        ]
      },
      "usage": [
        {
          "kind": "import",
          "language": "javascript",
          "module": "react-dom"
        },
        {
          "kind": "symbol",
          "language": "javascript",
          "module": "react-dom",
          "symbol": "render",
          "shape": "call",
          "replacement": "createRoot(container).render(element)"
        },
        {
          "kind": "symbol",
          "language": "typescript",
          "module": "react-dom",
          "symbol": "render",
          "shape": "call",
          "replacement": "createRoot(container).render(element)"
        }
      ],
      "x-npm": {
        "package": "react-dom"
      }
    }
  ]
}
```

To add one: find the official deprecation notice for the symbol, copy the rule above, set `purl` and `vers` to the package versions the notice covers, write one `symbol` entry per language, and run `npm run check`.

#### Walkthrough: add a symbol rule

This example adds a rule for `fs.exists`, which Node.js documents as deprecated in favour of `fs.access` or `fs.stat`. Follow the same steps for any symbol.

1. **Find the evidence.** Open the official documentation of the symbol and look for a deprecation notice. Here it is the `fs.exists` entry in the Node.js `fs` documentation, which carries `Stability: 0 - Deprecated`. Note the URL; the rule cites it. Without an authoritative notice for this symbol there is no rule.
2. **Pick the module and the symbol path.** `module` is what code imports: `fs`. `symbol` is the dotted path inside it: `exists`. Do not put the module in the symbol.
3. **Pick the shape.** `fs.exists(path, callback)` is called, so `shape` is `call`. Use `construct` for `new Buffer(size)`, `reference` when merely passing the function around is the problem, and `option` for a deprecated property of an options object.
4. **Write one entry per language.** Node.js code is JavaScript or TypeScript, so write two `symbol` entries that differ only in `language`. Add an `import` entry for the module too if you want the regex scanner to point at the file.
5. **Write the rule.** Copy the complete rule above, then set `purl`, `vers`, `title`, `summary`, `replacement`, `sources`, and `provenance` from the notice. `summary` states what the source says; the advice goes in `replacement`.
6. **Write a fixture.** A fixture is a small source file with usages that must be reported and lookalikes that must not. Put the expected result in comments so a reviewer can read it without running anything:

   ```js
   const fs = require("fs");
   const { promisify } = require("util");

   fs.exists("a.txt", () => {});          // reported: call of fs.exists
   const { exists } = require("fs");
   exists("b.txt", () => {});             // reported: destructured binding of fs.exists
   const check = fs.exists;
   check("c.txt", () => {});              // reported: alias of fs.exists

   fs.existsSync("a.txt");                // not reported: a different symbol
   fs.access("a.txt", () => {});          // not reported: the replacement
   const text = "fs.exists is deprecated"; // not reported: a string
   // fs.exists("d.txt", () => {});       // not reported: a comment
   const exists2 = (name) => name;
   exists2("e.txt");                      // not reported: an unrelated function
   ```

   Cover at least one reported usage per shape the rule declares, one alias, and the lookalikes above. A lookalike that the analysis reports is a bug in the rule or the analysis; fix it before the rule merges.
7. **Check it.** Run `npm run check`. It validates the rule against the schema, including every symbol entry, and fails when the reference pages under `docs/rules/` have drifted (run `npm run build:reference` to regenerate them). Open the pull request with `Closes #<issue>` and link the deprecation notice.

### Test a rule

A rule ships with two fixtures, and the harness runs them without any test code:

```
tests/fixtures/<rule-id>/match/   # a small repository the rule must report
tests/fixtures/<rule-id>/clean/   # a lookalike repository the rule must not report
```

Both directories are scanned offline as untrusted input, exactly like a repository. The `match` fixture must observe the rule and `clean` must not. A rule is observed when a detector reports it or, for a rule with `usage` matchers, when the usage analysis finds a match; a rule without both directories fails.

```bash
offing rules test <rule-id>          # exits 1 when a fixture fails and prints the expected and actual observations
offing rules lint [file...]          # checks schema, dates, source URLs, and duplicate ids with a fix hint
```

Keep fixtures tiny and give each one only the files its detector reads. The fixtures are also the reviewable evidence that the detector reports the rule where it should. When the detector changes, update them in the same pull request; when an update of `@velella/ebb` changes the rule, update them in the pull request that updates it. `offing rules lint` checks registry files in a checkout of Ebb.

### Provenance

Provenance makes a rule auditable.

| Field | Meaning |
|---|---|
| `observedAt` | The date you last saw the claim at its source. |
| `reviewedAt` | The date a maintainer last checked the rule against its sources. It must not be earlier than `observedAt`. |
| `reviewer` | Who reviewed it. |
| `importer` | The importer that drafted the rule, when one did. Omit it for hand-written rules. |

Dates are real calendar dates written `YYYY-MM-DD`; timestamps are rejected.

### Choosing an event

| Event | Use it when the source says |
|---|---|
| `deprecated` | The maintainer deprecated it, or put it in maintenance mode and recommends something else. |
| `end-of-support` | The release or version no longer receives support, for example because its runtime is gone. |
| `end-of-life` | The project or release line has reached end of life, is unmaintained, or is archived. |
| `removed` | The component, release, or service has been retired and no longer works. |
| `scheduled-end-of-life` | The vendor has announced a future end of life or end of support, with a date. The rule needs that date as its `deadline` and `severity: low`. It names the affected versions exactly as the later end-of-support or end-of-life rule will. When the date has passed, a reviewed change turns it into that rule (same `id`). See [decision 0010](decisions/0010-scheduled-end-of-life.md). |

If the source's wording fits two events, use the earlier one and quote the source in `summary`.

## Finding confidence

Every finding carries a `confidence` that says how the version behind it was read, so a pinned production runtime is easy to tell from a compatibility range:

| Value | Meaning |
|---|---|
| `exact` | Read from a pinned declaration, such as a Dockerfile tag or an `.nvmrc` file. |
| `range` | Read from a compatibility range that allows the affected version, such as `engines.node` or a dependency range with no lockfile entry. |
| `inferred-from-lock` | Read from a lockfile, or from a manifest declaration whose resolved version a lockfile confirms. |

A detector sets `confidence` when it knows better. Otherwise the engine uses `inferred-from-lock` for a finding located in a lockfile and `exact` for any other. The value appears in JSON output, in text output as a `Confidence:` line, and in SARIF as `properties.confidence`. It is additive: no existing field changes.

## Risk score

`riskScore` in `src/domain.ts` ranks findings so the riskiest are fixed first. It is a number from 0 to 100 built from three inputs and nothing else; popularity and download counts are never used.

| Input | Where it comes from | Points | Cap |
|---|---|---|---|
| Time since end of life | Whole days from the finding's `deadline` to the day scored (0 before the deadline or without one) | `floor(days × 50 / 730)` | 50, reached at two years |
| Usage | The finding's `impact.usageCount`, or its number of `usages` | 5 per usage | 25 |
| Advisories | The count of imported OSV advisory ids on the finding (`advisoryIds`), or the count the caller passes | 5 per advisory | 25 |

`score` is the sum of the three point values, and the result also returns the inputs and the points so the number can be checked by hand. The function reads no clock: the caller passes `today` (`YYYY-MM-DD`), so the same finding on the same day always scores the same. Offing does not fetch advisories during a scan; ids come from the bundled OSV cross-reference (see [Lifecycle data](DATA.md#osv-advisories)).

## Evidence policy

- Every rule needs an authoritative, versioned source: maintainer release notes, an official support or end-of-life policy, a registry deprecation flag, or platform documentation.
- Never infer lifecycle status from popularity, download counts, or a newer version existing.
- Dates, affected versions, and replacements must match the source. If the source is ambiguous, say so in the pull request.
- Rules are reviewed data, not code. A maintainer reviews every rule change in Ebb, and every change to `schemas/` and the rule fixtures here (see `.github/CODEOWNERS`).

## Validation

Everything above is enforced when a registry loads, and `npm run check` runs it on the bundled files. Validation reports every problem at once and names the rule and field, for example:

```text
Invalid registry (2 problems):
- rule "npm.package.request.deprecated": provenance.reviewedAt is required
- rule "npm.package.left-pad.deprecated": purl must be canonical and version-less (expected "pkg:npm/left-pad")
```

Beyond the schema, validation checks that:

- `purl` is canonical and has no version, qualifiers, or subpath;
- `vers` is canonical, its scheme is supported, every version in it is valid for that scheme, and the scheme fits the PURL type (for example `pypi` ranges on `pkg:pypi`);
- ids are unique, the rule's `ecosystem` matches the registry's, and there are no unknown fields (extensions must be named `x-<name>`);
- `migration` and `usage` entries are valid.

Supported version schemes are `semver`, `npm`, `cargo`, `golang`, `composer` (Semantic Versioning), `pypi` (PEP 440), `maven`, `nuget`, `gem`, and `intdot`.

## Freshness and sources

Scans never check freshness and never use the network, so results stay deterministic. Ebb's weekly [source check](https://github.com/velella-sh/ebb/blob/main/.github/workflows/sources.yml) reports stale rules, sources whose URL or title moved, and unreachable sources; corrections are made there.

## Detector hints

Existing detectors read a few fields that are specific to their ecosystem. In v2 they sit under `x-<ecosystem>` and are merged into the rule when the registry loads, so a detector sees the same rule it always has.

| Registry | Hints |
|---|---|
| `npm` | `x-npm.package` |
| `nodejs` | `x-nodejs.major` for one release line, or `x-nodejs.maximumMajor` for every line up to and including it |
| `python` | `x-python.kind` (`runtime` with `maximumVersion` such as `"3.9"`, or `package` with `package`) |
| `github-actions` | `x-github-actions.action` and `x-github-actions.supportedFromMajor` |

The hints must agree with `purl` and `vers`: `x-npm.package` is the package in `pkg:npm/...`, and `x-github-actions.supportedFromMajor: 5` goes with `vers:semver/<5.0.0`. New detectors should not add hints that `purl` and `vers` can already express.

## Drafting rules from sources

Rules do not have to be typed by hand. Ebb's [importers](https://github.com/velella-sh/ebb/blob/main/docs/IMPORTERS.md) read an authoritative source such as the Node.js release schedule or npm's deprecation flags and draft rules for a maintainer to review.

## Converting a v1 file

A tool converts registries written in the older, detector-specific format of the four bundled detectors. It derives `purl` and `vers` from the old fields, refuses to guess lifecycle events, and checks that every rule reads back unchanged:

```bash
npm run build
node dist/tools/registry-v1-to-v2.js registry/example.json \
  --observed-at 2026-10-13 --reviewed-at 2026-10-14 --reviewer your-name \
  --event example.rule.id=deprecated --out registry/example.json
```

## Detectors outside this repository

The public SDK still validates the v1 envelope (`validateRegistry`), so external detectors keep working unchanged. Loading v2 registries is currently internal to the bundled detectors; see [detector authoring](DETECTORS.md#registry-validation).

---

Source: https://velella.sh/offing/DATA/

# Lifecycle data: updates, signing, and trust

Offing's findings come from lifecycle rules (`registry/`). The rules that ship inside each release are always available. Between releases you can fetch newer rules, which are signed so that Offing can tell they came from the project's release workflow. This page explains how that works, what is checked, and what Offing promises.

## What you can rely on

- **Scans never use the network.** A scan, `check`, `explain`, `context`, `baseline`, `doctor`, and `data status` read local files only. The only command that connects to anything is `offing data update`, and it runs only when you run it. A test fails if any other code path opens a socket, resolves a name, or calls `fetch`.
- **Downloaded data is verified before it is used, every time it is loaded.** If it cannot be verified, Offing uses the data shipped with the installed release and says so in the result. It never loads data it could not verify.
- **You can see how fresh the evidence is.** Every scan and check says which data it used and how old it is, and warns when that is more than 30 days.
- **You can fix the data version** for reproducible CI.
- **No account, no telemetry.** Updating asks a public release list and downloads public files. Nothing about you or your repository is sent.

## Commands

```bash
offing data status                       # which data is in use, where it came from, how old it is (--json for tools)
offing data update                       # fetch and verify the newest signed bundle
offing data update --data-version 2026.10.01   # fetch exactly that bundle, without making it active
offing scan . --data-version 2026.10.01  # use exactly that bundle (every command takes this)
OFFING_DATA_VERSION=bundled offing scan .   # use only the data shipped with this release
```

`data status` reports one of three sources: **bundled** (shipped with the release), **cache** (the newest verified download), or **pinned** (the version you asked for). Its age is counted from when a downloaded bundle was built, or from the newest review date among the rules for bundled data.

### Updating

`offing data update` lists the project's `data-v…` releases, picks the newest one that has a bundle and a signature, downloads both (https only, with size limits and timeouts), verifies them completely, and only then stores them in your cache and makes them active. If anything is wrong the previous data stays active and nothing is written. Running it again when nothing changed says so.

It refuses a bundle that is older than the active one (a replayed old bundle would roll your rules back), a bundle the installed release already beats, and anything that fails verification. Three bundles are kept.

Downloads honor `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (Node.js 22.21 or newer). To use a mirror, point `EBB_DATA_URL` at its release list.

### Pinning

`--data-version X` or `OFFING_DATA_VERSION=X` (the flag wins) makes Offing use exactly bundle `X` from your cache, or `bundled` for the data shipped with the release. Unlike the automatic choice, a pin that cannot be met **stops the run** with exit code 3 (a data failure) instead of quietly using something else, so a CI job that pins its data either uses it or fails. The message tells you how to fetch it: `offing data update --data-version X`. A pinned bundle is verified just like any other, and is used whatever its age (the stale warning still appears).

### Where the data is stored

The data belongs to Ebb, so it lives in Ebb's cache: `EBB_DATA_DIR` if set, otherwise `~/Library/Caches/ebb` (macOS), `$XDG_CACHE_HOME/ebb` or `~/.cache/ebb` (Linux), or `%LOCALAPPDATA%\ebb\Cache` (Windows). Inside, `data/<version>/` holds `bundle.json` and its signature `bundle.json.sigstore.json`, and `data/active.json` names the active version. Deleting the directory returns Offing to the bundled data.

## What is in a bundle

One JSON file (`ebb.data-bundle.v1`, [schema](https://github.com/velella-sh/ebb/blob/main/schemas/data-bundle.v1.schema.json), [decision record](decisions/0006-data-bundle.md)) with a manifest and the files the detectors read: the lifecycle registries (one JSON file per ecosystem under `registry/`), the GitHub Actions SHA map, and the OSV cross-reference (`registry/osv.json`). The manifest lists each file's SHA-256, size, and rule count, a content address for the whole set, the build time, and the oldest Offing version that can read it. Versions look like `2026.10.16`, with `.N` for a second bundle on the same day. Building the bundle is deterministic: the same registry files and build time give the same bytes.

### OSV advisories

`registry/osv.json` maps lifecycle rule ids to OSV advisory identifiers that have **no fixed version** for that package. The `osv` [importer](https://github.com/velella-sh/ebb/blob/main/docs/IMPORTERS.md) drafts those rows at maintainer time from the OSV API; scans never call OSV. When a scan produces a finding whose `ruleId` appears in that file, the finding lists those ids in `advisoryIds` (and as an `Advisories:` line in text output). The risk score can use the count; Offing never fetches advisories during a scan.

## Trust model

A bundle is signed with **Sigstore keyless signing**. There is no long-lived signing key to steal or lose: the release workflow proves who it is to Sigstore with a short-lived GitHub identity token, receives a certificate that lasts minutes, signs the bundle, and the signature is recorded in a public transparency log.

Offing accepts a bundle only if **all** of these hold, checked offline:

1. The signature verifies against the exact bytes downloaded (certificate chain, validity period, transparency-log inclusion).
2. The signer is the project's release workflow: issuer `https://token.actions.githubusercontent.com` and an identity matching

   ```text
   ^https://github\.com/velella-sh/ebb/\.github/workflows/data-release\.yml@refs/(?:tags/data-v\d{4}\.\d{2}\.\d{2}(?:\.\d+)?|heads/main)$
   ```

   A valid signature from any other workflow, repository, or branch is refused.
3. The format is one Offing understands and its `minimumEbbVersion` is not newer than the installed release.
4. The bundle is complete, and every file matches its digest and size, with nothing missing or extra.

The certificates and log keys come from the Sigstore public-good trusted root, which ships in the `@velella/ebb` package (`data/sigstore-trusted-root.json`) so that verification needs no network. That is also why you should keep Offing reasonably current: if Sigstore rotates its keys and the root in your installed release is too old, signatures made after the rotation stop verifying. Offing then falls back to its bundled data and tells you; it does not skip the check.

To check a release by hand with [cosign](https://docs.sigstore.dev/):

```bash
cosign verify-blob \
  --bundle ebb-data-2026.10.16.json.sigstore.json \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/velella-sh/ebb/\.github/workflows/data-release\.yml@refs/(?:tags/data-v\d{4}\.\d{2}\.\d{2}(?:\.\d+)?|heads/main)$' \
  ebb-data-2026.10.16.json
```

### What this does not protect against

- A compromise of the repository's release workflow or of a maintainer with permission to push a `data-v…` tag: the workflow would sign whatever it was given. Rule changes are reviewed before they reach `main`, and the signature proves where a bundle came from, not that its contents are correct.
- A compromised Offing package: the trusted root and the signer identity are part of the release you installed.
- Wrong evidence. Signing says who published a rule, not that the claim is true; each rule cites its sources and review date for that reason.

### Release log

Every data release also publishes `release-log.jsonl`, a tamper-evident log of all data releases so far, with its own keyless signature (`release-log.jsonl.sigstore.json`). Each line is one release: version, `contentDigest`, the SHA-256 of the bundle file, the build time, the hash of the previous line, and its own hash. Because every entry commits to the one before it, changing, removing, or reordering a past release changes every later hash.

The release workflow downloads the previous release's log, refuses one that does not verify, appends the new bundle, and requires the result to extend the old log before signing it. The signatures of the bundle and of the log are recorded in the public Sigstore transparency log (Rekor), so a quiet rewrite would need the log's hashes and Rekor's entries to change together.

Check a log, and optionally that it extends an older copy you kept:

```bash
gh release download data-vYYYY.MM.DD --repo velella-sh/ebb --pattern 'release-log.jsonl*'
node dist/tools/data-release-log.js check release-log.jsonl --previous older-release-log.jsonl   # in a checkout of Ebb
```

The first release made after this was added starts the log; earlier releases are not listed.

## When something is wrong

Offing reports every refusal in the result, in the scan's `diagnostics` and in `data status`, for example:

```text
Ignoring downloaded lifecycle data 2026.10.16: registry/npm.json does not match its digest. Using the data bundled with Offing 0.3.0.
```

Common causes are a damaged download (run `offing data update` again), a bundle that needs a newer Offing (upgrade), and an expired trust root (upgrade). Data that is merely old is not an error; it is flagged stale after 30 days, and `offing data update` is the remedy.

## License and attribution

The lifecycle dataset is licensed separately from the scanner. It ships in the [`@velella/ebb`](https://github.com/velella-sh/ebb) package: the registry JSON under `registry/` and the first-party schemas under `schemas/` are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which allows use and redistribution, including commercially, with attribution and an indication of changes. Ebb's code is MIT. The package ships the data license as `LICENSE-DATA` and the attribution notice as `ATTRIBUTION.md`. Everything in this repository is [Apache-2.0](../LICENSE).

To reuse the dataset, credit it and link the license, for example:

> Lifecycle data from Ebb (`@velella/ebb`), by Armin Azimi and Ebb contributors, licensed under CC BY 4.0. https://github.com/velella-sh/ebb

Every rule carries its own `sources` (title, URL, and the `accessedAt` day it was read) and `reviewedAt`, so a consumer can trace a claim back to the page that states it and the date it was retrieved. `registry/sources.lock.json` records the current title and final URL of each cited page for maintainers and stays out of the published package. The upstream facts remain subject to the terms of the pages they come from; the license covers Ebb's selection, arrangement, normalization, and original text. Product and project names are trademarks of their owners and do not imply endorsement.

## Publishing a bundle

Bundles are published from [Ebb](https://github.com/velella-sh/ebb): a maintainer pushes a `data-vYYYY.MM.DD` tag there, and its [release workflow](https://github.com/velella-sh/ebb/blob/main/.github/workflows/data-release.yml) builds the bundle twice and requires identical bytes, signs it, verifies the signature, and attaches the bundle, the signature, and checksums to a GitHub release. See Ebb's [guide](https://github.com/velella-sh/ebb/blob/main/docs/DATA.md#publishing-a-bundle) and [Rule data](RELEASING.md#rule-data) here.

---

Source: https://velella.sh/offing/VALIDATION/

# v0.1 validation

Offing v0.1 was validated on 2026-10-14 against 20 public repositories pinned to immutable commits: ten Node.js repositories, nine Python repositories, and one Node.js/GitHub Actions repository. The complete corpus and expected finding locations live in `benchmarks/public-repositories/`; the executable harness is `benchmarks/public-repositories.ts`.

## Results

Moved to [Validation corpus: Results](validation/corpus.md#results).

## GitHub Actions corpus additions

Moved to [Validation corpus: GitHub Actions corpus additions](validation/corpus.md#github-actions-corpus-additions).

## Method

Moved to [Validation corpus: Method](validation/corpus.md#method).

## The 50-repository corpus

Moved to [Validation corpus: The 50-repository corpus](validation/corpus.md#the-50-repository-corpus).

## Kubernetes corpus

Moved to [Ecosystem corpora: Kubernetes corpus](validation/ecosystems.md#kubernetes-corpus).

## Kubernetes blind selection

Moved to [Ecosystem corpora: Kubernetes blind selection](validation/ecosystems.md#kubernetes-blind-selection).

## Java and Kotlin corpus

Moved to [Ecosystem corpora: Java and Kotlin corpus](validation/ecosystems.md#java-and-kotlin-corpus).

## Java and Kotlin blind selection

Moved to [Ecosystem corpora: Java and Kotlin blind selection](validation/ecosystems.md#java-and-kotlin-blind-selection).

## Scala and sbt corpus

Moved to [Ecosystem corpora: Scala and sbt corpus](validation/ecosystems.md#scala-and-sbt-corpus).

## Scala and sbt blind selection

Moved to [Ecosystem corpora: Scala and sbt blind selection](validation/ecosystems.md#scala-and-sbt-blind-selection).

## Ruby corpus

Moved to [Ecosystem corpora: Ruby corpus](validation/ecosystems.md#ruby-corpus).

## PHP corpus

Moved to [Ecosystem corpora: PHP corpus](validation/ecosystems.md#php-corpus).

## Swift corpus

Moved to [Ecosystem corpora: Swift corpus](validation/ecosystems.md#swift-corpus).

## Swift blind selection

Moved to [Ecosystem corpora: Swift blind selection](validation/ecosystems.md#swift-blind-selection).

## Serverless corpus

Moved to [Ecosystem corpora: Serverless corpus](validation/ecosystems.md#serverless-corpus).

## Serverless blind selection

Moved to [Ecosystem corpora: Serverless blind selection](validation/ecosystems.md#serverless-blind-selection).

## .NET blind selection

Moved to [Ecosystem corpora: .NET blind selection](validation/ecosystems.md#net-blind-selection).

## CI runner images corpus

Moved to [Ecosystem corpora: CI runner images corpus](validation/ecosystems.md#ci-runner-images-corpus).

## C and C++ corpus

Issue #1897 promotes the C/C++ detector to stable. The corpus already held twelve C/C++ ecosystem entries (four targeted migration pins and eight blind pins from the 300-repository pass). The gap for Supported was zero-finding controls: only `catchorg/Catch2` had an empty `expected` list.

The blind zero-finding rule, fixed on 2026-11-07 before Offing ran on these additions: for each of `cmake_minimum_required(VERSION 3.20`, `cmake_minimum_required(VERSION 3.22`, and `cmake_minimum_required(VERSION 3.25`, run `gh search code <query> --filename CMakeLists.txt --limit 50`, walk the results in order, and keep unique repositories that are not forks, not archived, not larger than 5,000 KB on GitHub, and not already in the corpus. Pin each at its default-branch commit that day. Scan in walk order and keep a repository only when every detector reports nothing; stop as soon as the C/C++ ecosystem has four empty `expected` lists. The three additions are, in order: `j2kun/mlir-tutorial`, `rogerorr/NtTrace`, and `jagheterfredrik/meb-preheat`. Later walk hits that produced findings (for example `innobi/pantab`) were not kept. The search returns different results on another day, so the pinned list, not a re-run, is the record.

Across the 15 C/C++ corpus entries, four have no findings at all, and 11 of the 15 were selected blind (73%). Corpus-wide the harness expects 242 `cpp` findings in 20 repositories. A narrowed offline run of the `cpp` and `shell` ecosystems on 2026-11-07 reported 11 true positives for `cpp` on those entries, no false positives, and no false negatives.

## Shell and PowerShell corpus

Issue #1897 promotes the Shell detector to stable. The corpus already held twelve shell ecosystem entries (four targeted and eight blind). Counts before this issue: five repositories with shell findings, twelve expected shell findings, and two zero-finding controls.

The blind finding rule, fixed on 2026-11-07 before Offing ran on these additions: for each query below, run `gh search code <query> --limit 50` with the listed path filter, walk the results in order, and keep unique repositories that are not forks, not archived, not larger than 5,000 KB on GitHub, and not already in the corpus, taking up to eight repositories per query until twenty-eight were kept. Pin each at its default-branch commit that day. Queries: `#Requires -Version 6.0` / `7.0` / `7.1` / `7.2` / `7.3` (`--extension ps1`), `#requires -Version 6` (`--extension psm1`), `PowerShellVersion = '7.0'` and `PowerShellVersion = '6.0'` (`--filename *.psd1`), and `mcr.microsoft.com/powershell:7.2` / `7.3` (`--extension yml`). After the first scan, repositories whose findings were almost entirely other detectors (for example `Contrast-Security-OSS/agent-operator`) were dropped so the shell sample stayed reviewable; every kept entry still came from that walk and was not chosen by its Offing score.

The blind zero-finding rule, fixed the same day: the same walk for `#Requires -Version 7.4`, `#Requires -Version 7.5`, and `PowerShellVersion = '7.4'`, then keep empty `expected` lists until the shell ecosystem has at least four zero-finding repositories. Kept zeros from that walk include `arnobpl/SymlinkCreator`, `ndabas/pico-setup-windows`, `microsoft/azure-redcap-paas`, `agadiffe/WindowsMize`, `kaitai-io/kaitai_struct_cpp_stl_runtime`, and `hcoona/cxx-for-java-developers`.

Ground truth: every finding in the kept repositories, from every detector, was read at its pinned line and recorded with a `maintainer-review` note quoting the path and line. PowerShell dates come from Microsoft's [PowerShell support lifecycle](https://learn.microsoft.com/powershell/scripting/install/powershell-support-lifecycle); other detectors cite their own vendor sources. Nothing in these entries is taken from Offing's output alone.

Across the 43 shell corpus entries, 29 have expected shell findings, nine have none, and 39 of the 43 were selected blind (91%). The corpus expects 102 shell findings in total. A narrowed offline run of the `cpp` and `shell` ecosystems on 2026-11-07 reported 102 true positives for `shell`, no false positives, and no false negatives.

## Go corpus

Issue #1892 added 31 Go entries: 24 blind and seven targeted. The targeted entries exercise multi-module repositories: `minio/minio` (twelve `go.mod` files, including five toolchain pins), `etcd-io/etcd` (five modules requiring the deprecated `github.com/golang/protobuf`), `hashicorp/vault` (three modules with the same requirement), `moby/moby` (four modules), `cli/cli` (a test module), and `containerd/containerd` (one module). `prometheus/prometheus` is a targeted zero-finding companion: it declares Go modules but no release line or module rule applies at the pin.

The blind rule, fixed on 2026-11-01 before Offing ran on these additions: GitHub repository search for `language:go stars:>=500 archived:false pushed:2023-01-01..2024-12-31`, sorted by stars descending. Walk the results in order and keep each repository whose default branch contains at least one `go.mod`, skipping repositories with more than 20 `Dockerfile*` files so that image findings do not crowd out the Go coverage. Take the first 24, whatever Offing reports for them. They are, in order: `FiloSottile/mkcert`, `ehang-io/nps`, `go-kit/kit`, `mislav/hub`, `gorilla/mux`, `matryer/xbar`, `bcicen/ctop`, `jmoiron/sqlx`, `julienschmidt/httprouter`, `sqshq/sampler`, `gophish/gophish`, `robfig/cron`, `golang/groupcache`, `revel/revel`, `bxcodec/go-clean-arch`, `gcla/termshark`, `sjwhitworth/golearn`, `dinedal/textql`, `akavel/up`, `apex/up`, `XiaoMi/soar`, `kelseyhightower/confd`, `smartystreets/goconvey`, and `p4gefau1t/trojan-go`. The search skipped `peterq/pan-light` (44 Dockerfiles) and `therecipe/qt` (71). The query returns different results on another day, so the pinned list above, not a re-run, is the record.

Ground truth: every finding in these repositories, from every detector, was read at its pinned line and recorded with a `maintainer-review` note naming the path and line. The Go release dates come from the [Go release policy](https://go.dev/doc/devel/release), the module deprecation from the module's `pkg.go.dev` page, and the other detectors' facts from their own vendor sources. Nothing in these entries is taken from Offing's output.

Across the 43 Go corpus entries, 39 have expected Go findings, four have none, and 31 of the 43 were selected blind (72%). A narrowed run of both ecosystems on 2026-11-01 reported 71 expected Go findings, 71 true positives, no false positives, and no false negatives. The full run the same day reported all 111 Go findings the corpus expects across every ecosystem, with no false positives and no false negatives.

## Rust corpus

Issue #1892 added 66 Rust entries: 46 blind and 20 targeted. The targeted rule, fixed on 2026-11-01: GitHub code search for `atty`, `ansi_term`, `failure`, and `tempdir` in `Cargo.toml`, deduplicated by repository and restricted to 200–2000 stars, sorted by stars descending; take the first 20 repositories not already in the corpus. They are: `Macchina-CLI/macchina`, `PaddiM8/kalker`, `mike-engel/jwt-cli`, `NixOS/nix-index`, `rabite0/hunter`, `dduan/tre`, `starcoinorg/starcoin`, `koute/cargo-web`, `clog-tool/clog-cli`, `pop-os/popsicle`, `paritytech/parity-bitcoin`, `chmln/handlr`, `gsquire/topngx`, `dwisiswant0/ppfuzz`, `Isona/dirble`, `sitkevij/hex`, `sit-fyi/sit`, `elkowar/pipr`, `jez/as-tree`, and `rust-lang/team`. The star cap keeps the sample to projects similar in scale to the rest of the corpus; the code search returns different results on another day, so the pinned list is the record.

The blind rule, fixed on the same date: GitHub repository search for `language:rust stars:>=300 archived:false pushed:2020-01-01..2022-06-30`, sorted by stars descending. Walk the results in order and keep each repository whose default branch contains a `Cargo.toml`; take the first 46, whatever Offing reports for them. They are, in order: `mit-pdos/noria`, `PistonDevelopers/conrod`, `nickel-org/nickel.rs`, `Kintaro/wtftw`, `rajasekarv/vega`, `zhuowei/nft_ptr`, `amethyst/legion`, `dimforge/nphysics`, `mesalock-linux/mesalink`, `tensorbase/tensorbase`, `lpxxn/rust-design-pattern`, `PumpkinDB/PumpkinDB`, `willdoescode/nat`, `ihciah/clean-dns-bpf`, `archseer/enigma`, `wubx/rust-in-databend`, `bwasty/learn-opengl-rs`, `spacejam/rio`, `Esc4iCEscEsc/skanuvaty`, `tsgates/rust.ko`, `headcrab-rs/headcrab`, `nachoparker/dutree`, `rustodon/rustodon`, `d-unsed/ruru`, `sciter-sdk/rust-sciter`, `bheisler/RustaCUDA`, `DanielKeep/cargo-script`, `raphlinus/font-rs`, `murarth/ketos`, `skyward-finance/contracts`, `h3r2tic/cornell-mcray`, `imager-io/imager`, `TimUntersberger/nog`, `ringbahn/ringbahn`, `altdesktop/i3-style`, `KOBA789/relly`, `rom1v/autoadb`, `TaKO8Ki/frum`, `crazymykl/rust-koans`, `quadrupleslap/scrap`, `tokio-rs/tokio-core`, `maciejkula/rustlearn`, `howardwu/wagyu`, `withoutboats/fehler`, `mathall/rim`, and `zackradisic/aussieplusplus`.

Ground truth: every finding in these repositories, from every detector, was read at its pinned line and recorded with a `maintainer-review` note naming the path and line. Crate status comes from the [RustSec advisory database](https://rustsec.org/), the toolchain dates from the [Rust release policy](https://www.rust-lang.org/policies/security), and the other detectors' facts from their own vendor sources.

Across the 78 Rust corpus entries, 36 have expected Rust findings, 28 have no findings at all, and 53 of the 78 were selected blind (68%). A narrowed run of both ecosystems on 2026-11-01 reported 61 expected Rust findings, 61 true positives, no false positives, and no false negatives. The full run the same day reported all 63 Rust findings the corpus expects across every ecosystem, with no false positives and no false negatives.

## Deno and Bun corpus

Issue #1895 grew the `deno` bucket from two pins to 71 repositories. The earlier pass pinned `starlink-awaken/StrategyManager` (Bun `1.0.0` in `.bun-version`) and `DominikDolejsi/PokeAppBackend` (Deno `1.46.2` as the root `"deno"` string in `deno.json`); a public code search for those two declaration forms found nothing further, so this pass used the pin form public projects actually keep, asdf's `.tool-versions`, and the detector was extended to read it.

The bucket now holds 71 repositories: 67 with expected `deno` findings (65 new), 71 expected `deno` findings (69 new: 35 Deno 1.x and 34 Bun 1.0.x or 0.x), and four zero-finding controls (`mob-sakai/unity-changeset`, `ericyd/salamivg`, `bee-browser/bee`, and `horvathandris/dime`). All 71 entries record `selection: "blind"`. Of the 65 new finding repositories, 33 pin Deno and 32 pin Bun, so the split is about half each.

Every finding in these repositories, from every detector, was read at its pinned line and recorded with a `maintainer-review` note naming the path, the line content, and the vendor source. Deno dates come from the [Deno 2.0.0 release](https://github.com/denoland/deno/releases/tag/v2.0.0), Bun dates from the [Bun 1.1.0 release](https://github.com/oven-sh/bun/releases/tag/bun-v1.1.0) and the [Bun 1.0.0 release](https://github.com/oven-sh/bun/releases/tag/bun-v1.0.0), and the other detectors' facts from their own vendor sources. Nothing in these entries is taken from Offing's output.

A narrowed offline run of `node dist/benchmarks/public-repositories.js --offline --ecosystem deno` on 2026-11-08 reported 71 true positives, no false positives, and no false negatives for the `deno` detector (precision 1, recall 1), over 71 repositories. The detector was promoted to `stable`, and so was the Bun capability, which uses the same detector.

## Deno and Bun blind selection

The rules below were fixed on 2026-11-08 **before** Offing ran on these additions. Every query is GitHub code search (`gh search code`) restricted to `filename:.tool-versions`, 100 results per page, and the results are walked in the order returned. A repository is kept only when its `.tool-versions` file, read directly, has a line whose first token is `deno` or `bun` and whose version is an exact three-component pin (no operator, wildcard, variable, `system`, or `latest`). Forked, archived, and already-pinned repositories, `velella-sh/offing`, repositories over 50,000 KB of GitHub disk usage, and paths under `deps`, `_build`, or `node_modules` are skipped, and each repository is kept once.

1. `deno 1.` — the first 33 eligible repositories. They are `denoland/setup-deno`, `chaijs/assertion-error`, `jthegedus/asdf-gcloud`, `nathankot/bashi`, `danilo-valente/compy`, `pocka/slack-message-parser`, `CSSSR/helm-deno`, `inoas/gleam-elixir-phoenix-liveview-counter`, `keithamus/gnome-shell-duckduckgo-search-provider`, `mistems/sandbox`, `nshkrdotcom/DSPex`, `grammyjs/chat-members`, `jthegedus/asdf-firebase`, `bermi/genetic`, `supafull/magnetic`, `eropple/tmuxed`, `nifty-lil-tricks/monitoring`, `jthegedus/asdf-v`, `collegeimprovements/dotfiles_old`, `dangvanthanh/vue-turborepo-boilerplate`, `nathankot/dotfiles`, `keithamus/deno-protod`, `sourcegraph/image-updater-pipeline`, `bermi/bermi-SDK`, `keithamus/deno-varint`, `reu/parser-combinators-lecture`, `cod3rocket/chat.io`, `reify-academy/fibery-toggl-integration`, `authgear/authgear-deno`, `jonnydgreen/ts-factory`, `wulymammoth/dotfiles`, `medson10/dotfiles`, and `eser/deno-boilerplate-console`.
2. `bun 1.0`, then `bun 0.` — the first 32 eligible repositories not already kept: `iloveitaly/openbook`, `reki2000/langs-bench-dijkstra`, `aklinker1/bunv`, `kidpollo/fullstack-kitchen-sink-2024`, `PatrickDeVries/logseq-plugin-colored-threads`, `cakekindel/purescript-postgresql`, `AdamBrodzinski/ocamlish`, `dangvanthanh/bundev`, `lsocrate/l5r-design-tools`, `c2c3/findaconference`, `jzweifel/hypertext-blog`, `courier-new/dotfiles`, `hack-dance/dashboard-demo`, `MelkdeSousa/polls`, `kobanyan/pgtune-api`, `KlausEverWalkingDev/my-dotfiles`, `r4ai/rehype-custom-code`, `stadacone/orenda`, `thetonus/website`, `edvardsanta/GenerateMarkdown`, `lucioreis/lazyvim`, `lirsacc/siren-chorus`, `rahulpatel/react-native-build-it`, `cakekindel/purescript-puppeteer`, `matbac85/nest-app`, `cowlingj/p2pp`, `bazuka5801/dotfiles-macos`, `Sanensi/low`, `nshafer/pax_demo.old`, `cakekindel/purescript-ezfetch`, `ctsstc/advent-of-code-2023`, and `kthatoto/vibe-tree`. `project-mahiwa/document` appeared in the walk but pins `bun 1.0`, a two-component pin the detector does not judge, so it was not kept.
3. Zero-finding controls: `deno 2.`, then `bun 1.3`. Walk the results in order and keep a repository only when its `.tool-versions` names a current pin (Deno 2.x or Bun 1.1 or later) and a scan of the pinned tree reports nothing for any detector; take four. The four are `mob-sakai/unity-changeset`, `ericyd/salamivg`, `bee-browser/bee`, and `horvathandris/dime`. Earlier hits with findings, such as `runtypes/runtypes` and `honojs/cli`, were skipped.

Not judged, and not counted as misses: `.deno-version`, `.bun-version.json`, a `package.json` `packageManager` or `engines` field, `requiredBunVersion`, a package `version` in `bunfig.toml`, `system` and `latest`, two-component pins, and Docker (`FROM denoland/deno:…`, `FROM oven/bun:…`) or CI (`deno-version:` and `bun-version:` under `denoland/setup-deno` and `oven-sh/setup-bun`) pins. Several corpus repositories contain those lines beside the judged `.tool-versions` pin. Searches return different results on another day, so the pinned list above, not a re-run, is the record.


## Elixir and Mix corpus

Issue #1895 added 36 Elixir entries, every one of them blind. Thirty-two have expected Elixir or Erlang findings and four have none: `sasa1977/soul_of_erlang_and_elixir` (Elixir 1.17.2, OTP 27), `gumi/yacto` (Elixir 1.17.2, OTP 27.0.1), `socrata/exsoda` (Elixir 1.17.3, OTP 27.3), and `danielberkompas/cloak` (Elixir 1.19.5, OTP 28.4).

The finding repositories, in the order the rule below kept them, are `smpallen99/coherence`, `elixir-crawly/crawly`, `emqx/MQTT-Client-Examples`, `bitcrowd/chromic_pdf`, `peek-travel/cocktail`, `supabase/libcluster_postgres`, `TheAlgorithms/Elixir`, `nimblehq/elixir-templates`, `implicitly-awesome/exop`, `benvp/live_motion`, `AccessOwl/open_owl`, `davydog187/timescale`, `sasa1977/elixir-in-action`, `sasa1977/boundary`, `standard-webhooks/standard-webhooks`, `coingaming/moon`, `danielberkompas/elasticsearch-elixir`, `revelrylabs/text_chunker_ex`, `fredwu/opq`, `acalejos/merquery`, `crertel/graphmath`, `navinpeiris/geoip`, `dvcrn/chatgpt-ui`, `commanded/commanded-ecto-projections`, `aviacommerce/avia`, `Hubs-Foundation/reticulum`, `esl/gradient`, `revelrylabs/ecto_soft_delete`, `elixir-desktop/desktop`, `fredwu/crawler`, `petalframework/petal_components`, and `sasa1977/con_cache`.

Every finding in these repositories, from every detector, was read at its pinned line and recorded with a `maintainer-review` note naming the path and line. Elixir dates come from the [Elixir security policy](https://github.com/elixir-lang/elixir/security/policy), OTP dates from the [Erlang/OTP security policy](https://github.com/erlang/otp/security/policy), and the other detectors' facts from their own vendor sources. Nothing in these entries is taken from Offing's output.

The files the detector reads are present across the set: every finding comes from a `.tool-versions` pin, and nearly every repository also has a `mix.exs` and a `mix.lock`. Exact `elixir: "1.14.x"` pins in `mix.exs` were not in the first pages of code search (the hits were `~> 1.14` ranges, which the detector does not judge). `filename:mix.exs fennec`, `filename:mix.lock fennec`, and `fennec language:Elixir` on 2026-11-07 returned no public consumer of the retired Hex package outside this repository's fixtures.

Docker and CI pins are in the corpus and are not judged. Examples read at the pinned commit: `dvcrn/chatgpt-ui` `FROM elixir:1.14.3-alpine`, `sasa1977/elixir-in-action` `ARG ELIXIR="1.15.4"`, `coingaming/moon` `FROM heathmont/elixir-ci:1.15.6-otp-26-alpine`, `petalframework/petal_components` `FROM hexpm/elixir:1.17.2-erlang-26.2.1-debian-bookworm-20260610-slim`, and `erlef/setup-beam` matrices in `revelrylabs/text_chunker_ex` and `Hubs-Foundation/reticulum`. `socrata/exsoda` names Elixir in `.travis.yml` and is a zero-finding repository.

Across the 36 entries, 32 have expected Elixir or Erlang findings (73 of them), four have none, and all 36 were selected blind. A narrowed run of `node dist/benchmarks/public-repositories.js --offline --ecosystem elixir` on 2026-11-07 reported 73 true positives, no false positives, and no false negatives for the `elixir` detector (precision 1, recall 1).

## Elixir and Mix blind selection

The blind rule, fixed on 2026-11-07 before Offing ran on these additions: GitHub code search (`gh api search/code`, 100 results per page) in this order.

1. `filename:.tool-versions "elixir 1.14"` — keep the first 12 eligible repositories whose file has at least one covered pin.
2. `filename:.tool-versions "elixir 1.15"` — the first 12 not already kept.
3. `filename:.tool-versions "erlang 25"` — the first 4 not already kept.
4. `filename:.tool-versions "erlang 26"` — the first 4 not already kept.

Zero-finding repositories: `filename:.tool-versions "elixir 1.17"`, `"elixir 1.18"`, or `"elixir 1.19"`. Keep a repository only when the file names elixir and erlang and no other tool, contains neither Elixir 1.14 or 1.15 nor OTP 25 or 26 (including an `-otp-25` or `-otp-26` suffix), and the default-branch tree has no Dockerfile, Containerfile, Compose file, `.github/workflows` file, `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `Gemfile`, `composer.json`, `pom.xml`, `build.gradle`, `requirements.txt`, or `*.csproj`. Take four.

Skip forks, archived repositories, repositories already in the corpus, `velella-sh/offing`, paths that are not `.tool-versions`, paths under `deps`, `_build`, or `node_modules`, and repositories whose GitHub disk usage is over 50,000 KB. Pin each at its default-branch commit on that date. Search totals that day: Elixir 1.14 was 425, Elixir 1.15 was 343, OTP 25 was 471, OTP 26 was 746, Elixir 1.17 was 378, Elixir 1.18 was 630, and Elixir 1.19 was 462. The queries return different results on another day, so the pinned list above, not a re-run, is the record.

Covered pins were classified by an independent reading of the `.tool-versions` lines (exact `major.minor` or `major.minor.patch`, plus one `-otp-N` suffix), not by an Offing scan. A four-component OTP version such as `25.3.2.5` is not an exact pin and was not counted.

## The 300-repository corpus

Moved to [Validation corpus: The 300-repository corpus](validation/corpus.md#the-300-repository-corpus).

## The 456-repository corpus

Moved to [Validation corpus: The 456-repository corpus](validation/corpus.md#the-456-repository-corpus).

## The held-out set

Moved to [Validation corpus: The held-out set](validation/corpus.md#the-held-out-set).

## Precision thresholds

[`benchmarks/thresholds.json`](../benchmarks/thresholds.json) sets a precision floor per detector (`github-actions`, `nodejs`, `npm`, `python`, `dotnet`, `java`, `kubernetes`, `serverless`, and `swift` enforce it; a detector is named by the first segment of its rule ids). The harness scores each detector, prints the figures under `detectors` in its JSON, and reports `thresholdViolations`. A stable detector below its `minPrecision` (0.95 today) fails the run with a line such as:

```text
THRESHOLD  npm: precision 0.9 is below the required 0.95
```

A detector at `beta` or `stable` also has a recall floor, 0.80 and 0.90 (decision 0013), computed as true positives over true positives plus false negatives; a full run below it prints `THRESHOLD  <detector>: recall … is below the required …`, fails, and cannot be recorded. Every corpus entry records `selection` (`blind` or `targeted`), and a test fails when one does not; entries added before the field existed were all picked from reviewed migration commits or known findings, so they record `targeted`.

The weekly corpus workflow therefore fails on a precision regression even if the exact-match comparison is later relaxed. Mark a new detector `"stable": false` until its corpus coverage is meaningful; it is still scored and reported but never fails the run. Never lower a floor to make a run pass.

## Fetching and the checkout cache

Moved to [Running the corpus: Fetching and the checkout cache](validation/running-the-corpus.md#fetching-and-the-checkout-cache).

## Running a subset

Moved to [Running the corpus: Running a subset](validation/running-the-corpus.md#running-a-subset).

### Re-running only what failed

Moved to [Running the corpus: Re-running only what failed](validation/running-the-corpus.md#re-running-only-what-failed).

### Comparing with an earlier run

Moved to [Running the corpus: Comparing with an earlier run](validation/running-the-corpus.md#comparing-with-an-earlier-run).

### Managing the cache

Moved to [Running the corpus: Managing the cache](validation/running-the-corpus.md#managing-the-cache).

### Warm ahead, run offline

Moved to [Running the corpus: Warm ahead, run offline](validation/running-the-corpus.md#warm-ahead-run-offline).

### Running only what a change affects

Moved to [Running the corpus: Running only what a change affects](validation/running-the-corpus.md#running-only-what-a-change-affects).

## Run cost and budget

Moved to [Running the corpus: Run cost and budget](validation/running-the-corpus.md#run-cost-and-budget).

## Stalled fetches

Moved to [Running the corpus: Stalled fetches](validation/running-the-corpus.md#stalled-fetches).

## Reading a run

Moved to [Running the corpus: Reading a run](validation/running-the-corpus.md#reading-a-run).

## Recording a full run

Moved to [Running the corpus: Recording a full run](validation/running-the-corpus.md#recording-a-full-run).

## Pull request check

Moved to [Running the corpus: Pull request check](validation/running-the-corpus.md#pull-request-check).

## Keeping `lastFullRun` current

Moved to [Running the corpus: Keeping `lastFullRun` current](validation/running-the-corpus.md#keeping-lastfullrun-current).

## Weekly run and refreshing pins

Moved to [Running the corpus: Weekly run and refreshing pins](validation/running-the-corpus.md#weekly-run-and-refreshing-pins).

## Differential testing against Renovate

Moved to [Differential testing: Differential testing against Renovate](validation/differential-testing.md#differential-testing-against-renovate).

## Differential testing against xeol

Moved to [Differential testing: Differential testing against xeol](validation/differential-testing.md#differential-testing-against-xeol).

## Differential testing against Pluto

Moved to [Differential testing: Differential testing against Pluto](validation/differential-testing.md#differential-testing-against-pluto).

## Accuracy by detector

Precision is true positives over true positives plus false positives; recall is true positives over true positives plus false negatives. Both come from the last full corpus run recorded in [`benchmarks/thresholds.json`](../benchmarks/thresholds.json), so a reader can regenerate every number: run `npm run record:corpus-run`, then `npm run build:coverage`. The table below is generated; a test fails when it drifts from the recorded run. `nodejs` is the Node.js runtime rules served by the npm detector. A dash means the last full run did not score that detector.

<!-- accuracy-tables:start -->
Measured on 557 pinned repositories at commit `dcc9f320` on 2026-11-06. Regenerate with `npm run build:coverage` after `npm run record:corpus-run`.

| Detector | Maturity | True positives | False positives | False negatives | Precision | Recall |
| --- | --- | --- | --- | --- | --- | --- |
| android | Supported | 10 | 0 | 0 | 1.000 | 1.000 |
| ci-images | Supported | 13 | 0 | 0 | 1.000 | 1.000 |
| container | Supported | 368 | 0 | 0 | 1.000 | 1.000 |
| cpp | Supported | 19 | 0 | 0 | 1.000 | 1.000 |
| dart | Supported | 8 | 0 | 0 | 1.000 | 1.000 |
| database | Experimental | 20 | 0 | 0 | 1.000 | 1.000 |
| deno | Supported | 0 | 0 | 0 | n/a | n/a |
| dotnet | Supported | 304 | 0 | 0 | 1.000 | 1.000 |
| elixir | Supported | 0 | 0 | 0 | n/a | n/a |
| github-actions | Supported | 1262 | 0 | 0 | 1.000 | 1.000 |
| go | Supported | 111 | 0 | 0 | 1.000 | 1.000 |
| java | Supported | 61 | 0 | 0 | 1.000 | 1.000 |
| kubernetes | Supported | 80 | 0 | 0 | 1.000 | 1.000 |
| nodejs | Supported | 349 | 0 | 0 | 1.000 | 1.000 |
| npm | Supported | 108 | 0 | 0 | 1.000 | 1.000 |
| php | Supported | 5 | 0 | 0 | 1.000 | 1.000 |
| python | Supported | 135 | 0 | 0 | 1.000 | 1.000 |
| ruby | Supported | 24 | 0 | 0 | 1.000 | 1.000 |
| rust | Supported | 63 | 0 | 0 | 1.000 | 1.000 |
| scala | Supported | 2 | 0 | 0 | 1.000 | 1.000 |
| serverless | Supported | 168 | 0 | 0 | 1.000 | 1.000 |
| shell | Supported | 12 | 0 | 0 | 1.000 | 1.000 |
| swift | Supported | 20 | 0 | 0 | 1.000 | 1.000 |
| terraform | Experimental | 66 | 0 | 0 | 1.000 | 1.000 |
<!-- accuracy-tables:end -->

## Mutation testing baseline

Line coverage shows which lines run; mutation testing asks whether the tests would notice a bug in them. `npm run test:mutation` runs [Stryker](https://stryker-mutator.io/) with the command runner over `src/engine/`, `src/baseline.ts`, `src/diff.ts`, and `src/vers/`, rebuilding with `tsc` and executing the unit tests that target those modules. The nightly [Mutation](../.github/workflows/mutation.yml) workflow publishes the score and surviving mutants in the job summary. It does not fail the build on the score yet.

First measured score on 2026-10-30 (commit `470542f4`): **59.59%** (1,139 killed, 7 timed out, 777 survived; 1,923 mutants). Per-file: `src/vers/` 80.12%, `src/baseline.ts` 72.78%, `src/diff.ts` 57.94%, `src/engine.ts` 23.12%.

## Interpretation and limits

Precision and recall are measured only against Offing's documented v0.1 rule set and the pinned corpus. They do not mean Offing detects every possible deprecation in these ecosystems. The corpus is public and reproducible, but not a statistically representative sample of all software. Dynamic action references and unsupported ecosystems remain intentionally unclassified.

The controlled source-usage benchmark provides a separate exact-match test for imports, calls, and configuration keys; see [Benchmarks](BENCHMARKS.md).

---

Source: https://velella.sh/offing/validation/corpus/

# Validation corpus

The public corpus behind the validation record: how it grew, how repositories were chosen blind, and the held-out set. The summary and the accuracy table are on [Validation](../VALIDATION.md).

## Results

| Measure | Result |
| --- | ---: |
| Repositories | 20 |
| Expected findings | 27 |
| True positives | 27 |
| False positives | 0 |
| False negatives | 0 |
| Precision | 1.0000 |
| Recall | 1.0000 |
| Median scan time | 8.19 ms |
| p95 scan time | 48.88 ms |
| Slowest scan | 49.73 ms |

Scan time measures only local Offing analysis after checkout. It excludes network and Git operations, which the harness reports separately as `checkoutMs` per repository and `medianCheckoutMs`, `p95CheckoutMs`, and `slowestCheckoutMs` in the summary, so Offing's own cost is never mixed with the time spent downloading a repository. The run used the development machine, so duration is a reference rather than a cross-machine guarantee.

## GitHub Actions corpus additions

The corpus has since grown to 30 repositories. The ten added entries are GitHub Actions repositories taken from reviewed migration commits (see [Mining migrations](../../benchmarks/mining/queries.md)). Eight are pinned to the commit *before* a migration, where Offing must report exactly the workflow locations the migration changed, and two are pinned to the migration commit itself, where it must report nothing. Together they include reusable workflows (`Akenon-Studio/.github`) and SHA-pinned actions (`smartcrabai/paperhanger`, `openmcp-project/crossplane-headlamp-plugin`).

Every expected finding in these entries has `groundTruthSource.kind` set to `migration-commit` and links to the commit that fixed it; a test checks each link against `benchmarks/mining/review-log.json`. A SHA-pinned entry is only accepted as zero-finding after checking that no pinned reference carries a version comment below the rule's supported major, because Offing does not classify SHA pins yet and would otherwise hide a deprecated version. Across all 30 repositories the harness reports 48 expected findings, 48 true positives, and no false positives or false negatives (observed 2026-10-16). The table above is the original 20-repository v0.1 run.

## Method

Every expected result is identified by rule ID, repository-relative path, and line at a pinned commit. The harness downloads each commit to a temporary directory, runs all built-in detectors, compares sets in both directions, reports per-repository timing, and removes the checkout. It exits unsuccessfully for any unexpected or missing finding.

```bash
npm run validate:public-repos
```

The audit covers both positive and zero-finding repositories across npm/Node.js, Python, and GitHub Actions. Findings were checked against their repository declarations and the authoritative sources bundled with the matching lifecycle rule.

## The 50-repository corpus

The corpus now has 50 repositories: the 20 from v0.1, the ten GitHub Actions entries above, and twenty more across the shipped detectors.

- Sixteen are pinned to the parent of a reviewed migration commit: six clean ones where the migration explains every finding (node-sass removals, Python runtime floors raised to a supported release), and ten where other deprecated declarations were still present. Findings that the migration fixed cite it with `groundTruthSource.kind` `migration-commit`; the rest are `maintainer-review` and quote the exact line that was read at that commit.
- Four are zero-finding repositories, including monorepos (`withastro/astro`, `vitest-dev/vitest`, `lerna/lerna`, `changesets/changesets`). They were also searched by hand for deprecated actions, runtimes and packages, independently of Offing's own rules.

The review tool (`benchmarks/mining/review.ts`) now accepts npm package, Python package, and Node.js and Python runtime rules as well as GitHub Actions rules, and `mine.ts` can mine one group at a time and append without replacing reviewed candidates (`--queries npm,python --limit 10 --append`). Across all 50 repositories the harness reports 81 expected findings, 81 true positives, no false positives and no false negatives (observed 2026-10-16).

## The 300-repository corpus

The corpus now has 300 repositories: the 189 earlier entries and 111 added in one pass, every one with `selection: "blind"`. They fill the ecosystems that had the fewest repositories: container, Go, Rust, Ruby, PHP, Android, C/C++, CI runner images, Dart, Terraform, database runtimes, and shell got seven each, and serverless, GitHub Actions, and Swift got nine each.

The blind rule, fixed on 2026-10-23 before Offing ran on these additions: for each query below, run `gh search code <query> --limit 60`, walk the results in the order returned that day, and keep the first N unique repositories that are not forks, not archived, not larger than 50,000 KB on GitHub, and not already in the corpus (or chosen by an earlier query); where the entry says root only, the matching path must be at the repository root. Pin each at its default-branch commit on that date. Licensing: only repository metadata, pinned commit IDs, paths, line numbers, and one short quoted line per finding are stored; no repository content is vendored, and each repository is fetched from GitHub at its pinned commit at run time. The query returns different results on another day, so the pinned list, not a re-run, is the record.

- `go` (7): `gh search code go 1.22 --filename go.mod`; `gh search code go 1.26 --filename go.mod`: `lwolf/kube-cleanup-operator`, `ICKelin/gtun`, `keycard-tech/keycard-go`, `Johonsoy/SmartStashDB`, `replicate/cog`, `charmbracelet/wish`, `slackhq/go-audit`.
- `rust` (7): `gh search code atty --filename Cargo.toml`; `gh search code ansi_term --filename Cargo.toml`; `gh search code tempdir --filename Cargo.toml`: `nikivdev/code`, `rathole-org/rathole`, `ogham/dog`, `suptejas/fleet`, `dflemstr/rq`, `databricks/click`, `gchp/iota`.
- `ruby` (7): `gh search code 3.1.4 --filename .ruby-version`; `gh search code 2.7.8 --filename .ruby-version`; `gh search code 3.4.1 --filename .ruby-version`: `67272-App-Design-Dev/PATS_v1_r7`, `HomeBusProjects/HomeBus`, `Kgomotso196/Blog`, `nmacawile/rails-chat-api`, `maedadev/bizside-ruby`, `nsidc/vagrant-vsphere`, `nov/web_authn_sample`.
- `android` (7): `gh search code com.android.billingclient:billing --filename build.gradle`; `gh search code com.android.billingclient:billing --filename build.gradle.kts`: `Aefyr/SAI`, `anjlab/android-inapp-billing-v3`, `Eajy/MaterialDesignDemo`, `serso/android-checkout`, `facebook/facebook-android-sdk`, `BranchMetrics/android-branch-deep-linking-attribution`, `d4rken-org/octi`.
- `cpp` (7): `gh search code cmake_minimum_required(VERSION 2.8 --filename CMakeLists.txt`; `gh search code cmake_minimum_required(VERSION 3.28 --filename CMakeLists.txt`: `BYVoid/uchardet`, `Xtra-Computing/thundergbm`, `wavebitscientific/functional-fortran`, `karimnaaji/vectiler`, `Off-World-Live/obs-spout2-plugin`, `QBDI/QBDI`, `Hapaxia/SelbaWard`.
- `ci-images` (7): `gh search code ubuntu-20.04 --filename azure-pipelines.yml`; `gh search code ubuntu-24.04 --filename azure-pipelines.yml`: `revery-ui/revery`, `microsoft/FASTER`, `hasura/graphqurl`, `inikep/lizard`, `Jackett/Jackett`, `dotnet/vscode-csharp`, `isomorphic-git/isomorphic-git`.
- `database` (7): `gh search code postgres:13 --extension yml`; `gh search code engine_version = "5.7" --extension tf`: `gitcoinco/grants-stack`, `jayfk/launchr`, `Kuper-Tech/sbmt-outbox`, `replicase/pgcapture`, `tmknom/example-pragmatic-terraform`, `PacktPublishing/Effective-DevOps-with-AWS-Second-Edition`, `RajitPaul11/terraform_aws`.
- `container` (7): `gh search code FROM node:24 --filename Dockerfile`; `gh search code FROM node:16 --filename Dockerfile`: `daimon3332/address`, `SpectrAI-Initiative/InnoClaw`, `navikt/security-playbook`, `rsmbl/Resemble.js`, `fanchangyong/deershare`, `firemakergk/aquar-home`, `sibbl/hass-lovelace-kindle-screensaver`.
- `terraform` (7): `gh search code required_version 1.12 --extension tf`; `gh search code required_version ~> 1.12 --extension tf`; `gh search code required_version --extension tf --filename versions.tf`: `skax-ca/iac-module-library`, `ql4b/cloudless-infra`, `terraform-google-modules/terraform-google-container-vm`, `cloudposse/terraform-aws-cicd`, `cloudposse/terraform-aws-ec2-instance`, `terraform-google-modules/terraform-google-log-export`, `GoogleCloudPlatform/notebooks-blueprint-security`.
- `node-actions` (9): `gh search code actions/checkout@v2 --extension yml`; `gh search code actions/checkout@v6 --extension yml`: `jugglerchris/rust-html2text`, `CausalAIBook/MetricsMLNotebooks`, `realabbas/Github-Actions-React-Native`, `ktye/i`, `lamdow8/lamdow8.github.io`, `bjdash/apic`, `lpereira/lwan`, `shivammathur/setup-php`, `hellofresh/action-changed-files`.
- `shell` (7): `gh search code #Requires -Version 7 --extension ps1`; `gh search code PowerShellVersion --filename psd1`: `domaindrivendev/Swashbuckle.AspNetCore`, `PowerShell/PSReadLine`, `SteeltoeOSS/Steeltoe`, `Kevin-Robertson/Inveigh`, `psake/psake`, `cyberark/ACLight`, `pester/Pester`.
- `php` (7): `gh search code ^7.4 --filename composer.json`; `gh search code ^8.3 --filename composer.json`: `dreamfactorysoftware/dreamfactory`, `doctrine/annotations`, `symfony/routing`, `driesvints/blade-icons`, `spatie/laravel-backup`, `mckenziearts/laravel-notify`, `spatie/db-dumper`.
- `dart` (7): `gh search code ^3.8.0 --filename pubspec.yaml`; `gh search code ^3.10.0 --filename pubspec.yaml`: `bensonarafat/super_tooltip`, `Mr-Pepe/syncable`, `rithik-dev/firebase_phone_auth_handler`, `dickermoshe/convex-dart`, `OpenFlutter/fluwx`, `Yubico/yubioath-flutter`, `dartgfx/gpux`.
- `serverless` (9): `gh search code nodejs14.x --filename serverless.yml`; `gh search code python3.8 --filename template.yaml`; `gh search code nodejs22.x --filename serverless.yml`: `SmartThingsCommunity/weather-color-light-smartapp-nodejs`, `ZeroSharp/serverless-php`, `Toola-bakery/Toola`, `ashokatechmin/Messcat`, `serverlesspub/imagemagick-aws-lambda-2`, `awslabs/aws-config-rdklib`, `aws-samples/aws-lambda-extensions`, `slackapi/bolt-js`, `webpro-nl/knip`.
- `swift` (9): `gh search code xcode --filename .xcode-version`; `gh search code IPHONEOS_DEPLOYMENT_TARGET = 12.0 --filename project.pbxproj`: `sarthak-behl/Signal-iOS`, `palak-ios-play/SecureChat-iOS`, `NorthWolfLabs/CodexGauge`, `Shopify/mobile-buy-sdk-ios`, `ReSwift/ReSwift`, `Swinject/Swinject`, `aslanyanhaik/youtube-iOS`, `square/Valet`, `swiftlang/swift-corelibs-xctest`.

Ground truth: for each repository the harness report was read line by line at the pinned commit, and every expected finding has a `maintainer-review` note quoting the path, line, and the matching text. The Go, Rust, Ruby, Android, C/C++, CI image, serverless, and GitHub Actions findings were also cross-checked against an independent `grep` over the pinned files (not Offing's output); the only differences are the scope boundaries below. Because the corpus scans every detector, every finding in these repositories is recorded, not only the ones for the ecosystem it was selected for. Findings of the npm, Node.js, Python, and .NET detectors were checked by reading the line, not by a second search. Several repositories that matched a version query have no finding in that ecosystem, which is expected: a range such as PHP `^7.4 || ^8.0` or Dart `sdk: ^3.8.0` still allows a supported release and is not an end-of-life declaration.

Scope boundaries seen while checking, none of which is a finding in this corpus: the GitHub Actions detector reads only the root `.github/workflows` directory, so nested workflows (`pkg/cli/init-templates/base/.github/workflows` in `replicate/cog`, a `fixtures` directory in `webpro-nl/knip`) and composite `action.yml` files (`realabbas/Github-Actions-React-Native`, `awslabs/aws-config-rdklib`, `sarthak-behl/Signal-iOS`) are not scanned; the CI image detector reads files named `azure-pipelines.yml`, not `azure-pipelines-full.yml` (`microsoft/FASTER`); and the Android detector does not report a Play Billing pin written as `"gplayImplementation"("...")` (`d4rken-org/octi`) or inside an `androidTestImplementation` call (`BranchMetrics/android-branch-deep-linking-attribution`). These are candidates for follow-up issues, not corpus entries.

## The 456-repository corpus

Issue #740 added 156 repositories to the 300 above to close the evidence gaps in [decision 0013](../decisions/0013-detector-maturity.md) for the four detectors that held `Supported` before the rules existed. Every one records `selection: "blind"`.

The blind rule, fixed on 2026-10-23 before Offing ran on these additions: GitHub repository search for a language, 100 to 500 stars, last pushed from 2021-01-01 to 2024-12-31, not a fork, not archived, sorted by stars descending (`gh search repos --language <language> --stars 100..500 --updated 2021-01-01..2024-12-31 --archived=false --include-forks=false --sort stars --order desc --limit 100`). Walk the results in order and keep a repository unless it is already in the corpus, is larger than 50,000 KB, or lacks the file the ecosystem needs. Pin each at its default-branch commit on that date. Each expected finding is the scan result with the line read at the pinned commit, recorded as a `maintainer-review` note.

- `node` (52, language JavaScript, a root `package.json`): `lucasbento/graphql-pokemon`, `adobe-photoshop/generator-assets`, `gruntjs/grunt-contrib-requirejs`, `mathiasbynens/CSS.escape`, `bitpay/bitauth`, `cloudinary/cloudinary-react`, `discordjs/RPC`, `pilwon/node-yahoo-finance`, `rpl/flow-coverage-report`, `sourcecred/sourcecred`, `Brainfock/Brainfock`, `manifoldfinance/defi-threat`, `remarkjs/remark-toc`, `fstirlitz/luaparse`, `mobxjs/mobx-react-todomvc`, `dxxzst/OfflineMap`, `ElementUI/element-theme`, `algorithm-visualizer/algorithms`, `d3/d3-interpolate`, `twilio-labs/call-gpt`, `jiayisheji/blog`, `svrxjs/svrx`, `wix-incubator/react-native-keyboard-aware-scrollview`, `malte-wessel/react-textfit`, `bartve/disconnect`, `insodoc/insomnia-documenter`, `whoisandy/react-blocks`, `o2team/elf`, `standard/ts-standard`, `briancavalier/slides`, `YataoZhang/my-single-spa`, `parmsang/gatsby-starter-ecommerce`, `acode/copenhagen`, `snorpey/triangulation`, `bchiang7/octoprofile`, `mahnunchik/gulp-responsive`, `cferdinandi/build-tool-boilerplate`, `mixtur/webpack-spritesmith`, `wzpan/hexo-generator-search`, `dai-shi/react-hooks-async`, `lazd/gulp-replace`, `mapmeld/profanity-pgp`, `lbovet/docson`, `lexich/redux-api`, `smartcontractkit/defi-minimal`, `allegro/node-worker-nodes`, `drawcall/AgileJS`, `tani/cheeriogs`, `Semantic-Org/Semantic-UI-CSS`, `uncleLian/vue2-news`, `abramenal/cypress-file-upload`, `CoreyGinnivan/whocanuse`.
- `python` (34, language Python, a root `pyproject.toml`, `setup.py`, `setup.cfg`, `Pipfile`, or `requirements.txt`): `NTMC-Community/MatchZoo-py`, `layer8secure/SilentHound`, `LAION-AI/natural_voice_assistant`, `caserec/CaseRecommender`, `SqueezeAILab/TinyAgent`, `jarus/flask-testing`, `Deadpool2000/Paybag`, `alxschwrz/codex_py2cpp`, `harperreed/photo-similarity-search`, `FranxYao/Long-Context-Data-Engineering`, `DougDougGithub/Babagaboosh`, `aryanvikash/Youtube-Downloader-Bot`, `tappi287/openvr_fsr_app`, `microsoft/powerbi-jupyter`, `JPCERTCC/MalConfScan`, `msight-tech/research-ms-loss`, `HazyResearch/evaporate`, `achembarpu/pockyt`, `blacknbunny/CVE-2018-10933`, `peract/peract`, `sweetcocoa/pop2piano`, `shichao-an/leetcode-python`, `simonw/db-to-sqlite`, `alexdelorenzo/cast_control`, `prateekiiest/Code-Sleep-Python`, `SourceCode-AI/aura`, `szc19990412/TransMIL`, `PrithivirajDamodaran/Styleformer`, `elbayadm/attn2d`, `CryptoGnome/Limit-Sniper`, `kturung/langgraph_streamlit_codeassistant`, `busimus/cutelog`, `flopp/GpxTrackPoster`, `corenel/pytorch-adda`.
- `node-actions` (13, language TypeScript, at least one workflow file in `.github/workflows`): `iamraphson/react-paystack`, `dai-shi/reactive-react-redux`, `mgmeyers/obsidian-list-callouts`, `rubenspgcavalcante/webpack-extension-reloader`, `innocenzi/tailwindcss-theming`, `lbdremy/solr-node-client`, `galnir/Master-Bot`, `ericnorris/striptags`, `xmindltd/xmind-sdk-js`, `rametta/pratica`, `wessberg/rollup-plugin-ts`, `Ff00ff/mammoth`, `bryanmylee/svelte-headless-table`.

A second Python pass followed, because the 34 repositories above held only 4 Python findings and `stable` needs 60. The blind rule, fixed on 2026-10-23 before Offing ran on these additions: for each query below, run `gh search code <query> --filename <file> --limit 60`, walk the results in the order returned that day, and keep the first five or six unique repositories whose matching path is exactly that file at the root, skipping forks, archives, repositories larger than 50,000 KB, and repositories already in the corpus. Pin each at its default-branch commit on that date. The queries look for old Python declarations, so they are expected to produce findings, but the repository is chosen by the query result and not by any Offing output.

- `python` (56 more):
  - `gh search code requires-python = ">=3.8" --filename pyproject.toml`: `cobrateam/splinter`, `pallets-eco/flask-debugtoolbar`, `Aiven-Open/pghoard`, `epfl-lts2/pygsp`, `isaiahbjork/Auto-GPT-Crypto-Plugin`, `widgetti/ipyvuetify`.
  - `gh search code python_requires=">=3.7" --filename setup.py`: `shenweichen/GraphEmbedding`, `Overv/outrun`, `BasicProtein/AugmentCode-Free`, `machow/siuba`, `LAMDA-NJU/Deep-Forest`, `drunkdream/weread-exporter`.
  - `gh search code 3.8 --filename .python-version`: `bndr/pipreqs`, `login-securite/lsassy`, `Lawouach/WebSocket-for-Python`, `n8henrie/pycookiecheat`, `DarrenOfficial/dpaste`, `psevensas/DjangoChannelsGraphqlWs`.
  - `gh search code python-3.8 --filename runtime.txt`: `AnimeKaizoku/EnterpriseALRobot`, `weareasterisk/gavel2`, `AbirHasan2005/TG-String-Session`, `IceKirby/NaTrave`, `urschrei/hexagrams`, `zolabar/trendPy`.
  - `gh search code python_version = "3.7" --filename Pipfile`: `hustlei/QssStylesheetEditor`, `DanMcInerney/pymetasploit3`, `donsheehy/datastructures`, `CodeForPhilly/chime`, `mozilla/crlite`, `prideout/svg3d`.
  - `gh search code requires-python = ">=3.7" --filename pyproject.toml`: `LAION-AI/CLAP`, `ncclient/ncclient`, `nschloe/tiptop`, `nschloe/perfplot`, `huggingface/hf_transfer`, `zu1k/Good-MITM`.
  - `gh search code python_requires=">=3.6" --filename setup.py`: `alibaba/tidevice`, `rachpt/lanzou-gui`, `Hsury/BiliDrive`, `malinkang/weread2notion-pro`, `maxhumber/gazpacho`.
  - `gh search code python = "^3.7" --filename pyproject.toml`: `bee-san/pyWhat`, `Gerapy/Gerapy`, `jayfk/statuspage`, `python-gino/gino`, `wustho/epr`.
  - `gh search code requires-python = ">=3.6" --filename pyproject.toml`: `doableware/djongo`, `python273/vk_api`, `miguelgrinberg/Flask-Migrate`, `vinifmor/bauh`, `cvg/glue-factory`.
  - `gh search code python 3.8 --filename .tool-versions`: `leosussan/fastapi-gino-arq-uvicorn`, `muxinc/mux-python`, `ozzs/monobox`, `crflynn/skranger`, `verypossible/very_plot`.

One more \`node-actions\` repository followed #1101: the new \`node-version\` rule gave findings to two repositories that had none, leaving three zero-finding GitHub Actions repositories where \`stable\` needs four. The rule, fixed before scanning: \`gh search code actions/checkout@v6 --extension yml --limit 60\`, walk the results in order, keep unique repositories that are not forks, archives, larger than 50,000 KB, or already pinned, and stop as soon as the zero-finding count reaches four. The first one walked, \`asciimoo/hister\`, had no findings, so it is the only addition.

The search returns different results on another day, so the pinned list above, not a re-run, is the record.

Effect on the levels: `github-actions`, `nodejs`, `npm`, and `python` now meet `stable` on the corpus evidence, so none of them is grandfathered any more.

## Corpus passes

Each pass that grew a bucket is written up in its own file under [`passes/`](passes/index.md), one file per pass, so two passes never edit the same page. Add a pass by adding a file there, not by appending a section here.

## Corpus targets

Decision 0030 sets 200 reviewed projects per bucket as the growth goal. Most buckets are below it, so the goal is
not the CI floor: failing every pull request below 200 would block all work until the corpus grows.

`benchmarks/corpus-targets.json` records the minimum each bucket must keep. It started at the counts when the
check landed and rises as the corpus grows. `node dist/benchmarks/corpus-targets.js` fails when a bucket is below
its minimum, before any network step in the corpus workflow; `--write` records the current counts as a reviewable
change. The [dashboard](../dashboard/) shows every bucket's count next to its minimum and the 200 goal.

## The held-out set

The main corpus is circular: its expected findings were written by reviewing the same commits Offing is scored on, so 1.0 shows that nothing regressed and not that Offing generalizes (issue #740, decision 0013). The held-out set (`benchmarks/held-out-repositories.json`) is separate: it is never used to write or tune a rule, and its ground truth was committed before Offing scanned it.

- **Rule, fixed on 2026-10-23.** The two repository searches behind the node and GitHub Actions entries above (JavaScript and TypeScript, 100 to 500 stars, last pushed 2021-01-01 to 2024-12-31, not a fork, not archived, sorted by stars) were walked past the last repository they had already supplied. The first repositories after that point that are not in the corpus, are at most 50,000 KB, and have a workflow file are held out: 15 (five from the JavaScript list at ranks 76 to 97, ten from the TypeScript list at ranks 65 to 81; the lists ended at 100 results).
- **Ground truth first.** `benchmarks/held-out/label.ts` labels the set from the text alone (it imports no detector and reads no registry): `uses: actions/checkout`, `actions/setup-node`, and `actions/cache` at major version 4 or lower, and workflow `node-version:` lines or `.nvmrc` naming Node.js 20 or lower. The labels were committed (`test(validation): write the held-out ground truth before any scan`) before the first scan.
- **Scope.** The comparison covers only the families `github-actions.checkout`, `github-actions.setup-node`, `github-actions.cache`, and `nodejs.runtime`, by family, path, and line. A rule that is outside the labeller is not judged here.
- **Run.** `npm run validate:held-out` (add `-- --output benchmarks/held-out-result.json` to record). It reports and never fails the build.

First result (before #1101): 15 repositories, 55 true positives, 2 false positives, 18 false negatives, precision 0.9649, recall 0.7534. The 18 misses were all `nodejs.runtime` lines in workflows that pin Node.js 14 or 16 (for example `node-version: 16`): the GitHub Actions detector did not read the `node-version` of `actions/setup-node` at all. The main corpus never exercised that case, which is what a held-out set is for. Issue #1101 added it (see [DETECTORS.md](../DETECTORS.md)); the 130 `nodejs.runtime` findings it adds to the main corpus were each checked by reading the line.

After #1101: 15 repositories, 73 true positives, 3 false positives, 0 false negatives, precision 0.9605, recall 1. The 3 "false positives" are not errors: two are `engines.node` declarations in `package.json` and one is a `strategy.matrix` Node.js list (`node: [8, 10, 12]` in `reid/node-jslint`), none of which the labeller reads. Because the rule was written after the first held-out run, this repository set no longer measures generalization for `node-version`; a fresh held-out set is needed for the next rule.

## Replaying data releases

`npm run replay:data` proves that a data update does not cause surprises. It scans the pinned repositories in `benchmarks/data-replay/repositories.json` (each also pinned in the public corpus at the same commit) once per data release (the last three `data-v*` tags) and once with the working tree's `registry/`, all with the same Offing code and the same scan time. The only input that differs between two scans is the data.

Every finding that appears or disappears between two consecutive releases must be explained by a rule that was added, removed, or edited between them (an edit means any field a scan reads; sources and provenance do not count), or, for `github-actions.*` findings, by a change to the SHA map. The run prints each change with its explanation and exits with status 1 when any change is unexplained. `--releases <n>` sets how many releases to replay and `--output <file>` writes the JSON report.

Notes:

- Releases from before the `accessedAt` requirement are brought up to the current schema for the replay (a missing `accessedAt` takes the rule's `observedAt`, and a registry the release lacked is empty, so its rules count as added). Nothing a scan reads is changed.
- The data bundle does not yet carry the deno, elixir, php, and scala registries; the replay installs them itself so every detector has its data.
- The `data-replay` workflow runs this on `main` when `src/` or `registry/` change, weekly, and on demand. It needs the network only to fetch the pinned checkouts and would exceed the pull-request runner-minute budget, so it does not run on pull requests: run `npm run replay:data` before changing `registry/`.

## Unreviewed expected findings

Growing the corpus to 200 repositories per ecosystem means about 4,600 pins, far beyond hand labeling every finding before the first scan. The candidate finder freezes the pins ([decision 0030](../decisions/0030-corpus-selection-and-200-target.md)); a second tool scans a local checkout of each eligible pin and records what the current detectors report as **unreviewed** expected findings.

- **Where they live.** `benchmarks/unreviewed-repositories/<ecosystem>.json`, separate from `benchmarks/public-repositories/`. Each entry has `reviewState: "unreviewed"`, `source: "scan-output"`, and `unreviewedExpected` instead of the reviewed corpus's `expected`. The different field name is deliberate: no scoring, threshold, or maturity function reads it, so an unreviewed entry cannot be mistaken for ground truth.
- **How they are made.** The tool reads the frozen candidate report, takes only candidates with an eligible immutable pin, and scans `<checkouts-dir>/<owner>--<name>` with the bundled lifecycle data. It never fetches, installs, builds, or runs repository code, and it uses no network. Transitive findings are omitted for the same reason the harness omits them. A missing checkout or scan failure stops the batch rather than writing a partial result.
- **What they count for.** Nothing. Unreviewed entries are not reviewed repositories, expected findings, precision or recall evidence, detector maturity evidence, or progress toward 200. Reports print the reviewed and unreviewed numbers in separate rows and mark only the reviewed row as precision evidence.
- **How they become reviewed.** A reviewer reads the pinned file, adds a `groundTruthSource` note quoting the path and line, replaces `unreviewedExpected` with `expected`, and moves the entry to `benchmarks/public-repositories/<ecosystem>/`. The hand-review sample in #2119 is the first consumer.

```bash
node dist/benchmarks/candidates/expected-cli.js generate candidates.json <checkouts-dir> benchmarks/unreviewed-repositories
node dist/benchmarks/candidates/expected-cli.js report
```

The first command prints a table such as:

```text
scope      repositories  findings  precision evidence
reviewed            557      3174  yes
unreviewed          300      1234  no
```

The unreviewed row says nothing about accuracy: its labels are the current output, so a run against them only shows that the output did not change. Precision still rests on the reviewed corpus and the held-out set.

---

Source: https://velella.sh/offing/validation/ecosystems/

# Ecosystem corpora

The pinned repository sets and blind selection rules for each ecosystem detector. The summary and the accuracy table are on [Validation](../VALIDATION.md).

## Kubernetes corpus

Thirty-six public repositories at pinned commits cover the `kubernetes` detector. Targeted (chosen knowing their result): `argoproj/argocd-example-apps` (Helm and kustomize applications, including a Chart.yaml dependency on the retired Helm stable repository), `kelseyhightower/ingress-with-static-ip`, `unixhot/salt-kubebin` (a CronJob and three Ingresses), `kubernetes/examples` (two PodSecurityPolicy documents, plus the two end-of-life base images the container detector reports there), and `lusyoe/springboot-k8s-example` (a Helm template and a plain manifest). `ahmetb/kubernetes-network-policy-recipes` is a targeted zero-finding companion (modern NetworkPolicy examples only), added so the kubernetes corpus still has two empty `expected` lists after argocd-example-apps gained the Helm stable finding.

Blind (rule below): `kelseyhightower/kubernetes-cluster-federation` (extensions/v1beta1 Deployments, ReplicaSets, and an Ingress), `motiv-labs/janus` (a PodDisruptionBudget and an Ingress, plus Go and Action findings), `FairwindsOps/pluto` (two extensions/v1beta1 Deployments outside its test directories), `luksa/kubernetes-in-action` (thirty-odd manifests across extensions, apps/v1beta1 and v1beta2, PodSecurityPolicy, CronJob, StatefulSet, CRD, and Ingress), `ossf/package-analysis` (an autoscaling/v2beta2 HorizontalPodAutoscaler), `knrt10/kubernetes-basicLearning` (a networking.k8s.io/v1beta1 Ingress), and five with no Kubernetes finding: `hasura/skor` (the removed version appears only as a `kind: List` item), `stefanprodan/gitops-istio` (the removed version appears only as a Flagger `autoscalerRef`), `doitintl/kube-no-trouble` (the removed versions are in `fixtures/`), `elastic/crd-ref-docs`, and `yaml-schema/yaml-schema`, `shepherd44/helm-charts` (current API versions).

Because the corpus scans every detector, every finding in these repositories is recorded, not only the Kubernetes ones. Each expected finding was checked by reading its line at the pinned commit, and its `groundTruthSource` is a `maintainer-review` note naming the path and line; none of these repositories has a migration commit for the finding, so none is cited. The rules' dates and removal releases come from the Kubernetes migration guide, not from these repositories. A run of `npm run validate:public-repos -- --ecosystem kubernetes` on 2026-10-23 over the seventeen Kubernetes entries reported no false positives or false negatives, with 67 expected `kubernetes` findings, all true.

**Correction (blind ground truth).** The `FairwindsOps/pluto` entry was missing one expected finding: `e2e/tests/assets/list/list-deployment-deprecated-and-non-deprecated.yaml` line 3, an `extensions/v1beta1 Deployment` inside a `kind: List` document. The first corpus run with the `kind: List` parser reported it as unexpected. A re-read of the pinned file confirmed it is a real removed API, so the expected list was extended after that run, and this paragraph records the change. The earlier count of 67 expected `kubernetes` findings predates this correction.

## Kubernetes blind selection

The five earliest Kubernetes repositories were chosen knowing their result, so each records `selection: "targeted"`; the twelve below record `selection: "blind"`.

The blind rule, fixed on 2026-10-23 before Offing ran on these additions: GitHub code search restricted to `--extension yaml` (`gh search code <query> --limit 60`) for each of `extensions/v1beta1`, `policy/v1beta1`, `batch/v1beta1`, `autoscaling/v2beta2`, and `networking.k8s.io/v1beta1` (removed API groups, expected to produce findings), and `apps/v1 Deployment` (current API, expected to produce none). Per query, walk the results in order and keep the first two unique repositories, skipping forks, archives, repositories already in the corpus or chosen by an earlier query, and repositories larger than 5,000 KB on GitHub. Pin each at its default-branch commit on that date. The twelve are `hasura/skor`, `kelseyhightower/kubernetes-cluster-federation`, `motiv-labs/janus`, `FairwindsOps/pluto`, `luksa/kubernetes-in-action`, `doitintl/kube-no-trouble`, `ossf/package-analysis`, `stefanprodan/gitops-istio`, `knrt10/kubernetes-basicLearning`, `elastic/crd-ref-docs`, `yaml-schema/yaml-schema`, and `shepherd44/helm-charts`. The query returns different results on another day, so the pinned list above, not a re-run, is the record.

Ground truth: for each repository every `apiVersion` line naming a removed group and version was listed with `grep` over the pinned YAML files and compared with the report, independently of Offing's own output, and each reported finding's `kind` was read from its manifest. Every expected finding has a `maintainer-review` note naming the path, the exact line, and the kind.

## Kubernetes stable expansion (2026-11-08)

To meet the stable evidence minimums of [decision 0013](../decisions/0013-detector-maturity.md) (at least 20 repositories with Kubernetes findings, 4 zero-finding Kubernetes-ecosystem repositories, at least two thirds blind, at least 60 `kubernetes.*` expected findings), the Kubernetes corpus gains further blind repositories. The selection rule below was fixed on 2026-11-08 **before** Offing ran on these additions.

Blind finding rule (2026-11-08): `gh search code --limit 60` for each of `extensions/v1beta1`, `batch/v1beta1`, `networking.k8s.io/v1beta1`, and `autoscaling/v2beta2` with `--extension yaml`; `charts.helm.sh/stable` with `--filename Chart.yaml` (Helm retired-repo pins); and `extensions/v1beta1` with `--filename kustomization.yaml` (Kustomize overlays). Walk results in order; keep unique repositories that are not forks, not archived, not larger than 50,000 KB, and not already in the corpus; pin each at its default-branch HEAD that day.

Blind zero-finding rule (same day): GitHub repository search for small NetworkPolicy example repositories (`kubernetes networkpolicy examples`, stars 10..5000, not archived). Walk results in order; warm and scan offline; keep a repository only when every detector reports nothing; stop once the Kubernetes ecosystem has four empty `expected` lists. Kept zeros from that walk: `fatihsoysalcom/kubernetes-network-policy-example` and `HaseebUllah-DevOps/kubernetes-security-policies` (alongside the earlier targeted zeros).

Corpus-wide `countEvidence` for `kubernetes` meets every stable row. Offline validate on the Kubernetes bucket reported precision 1 and recall 1.

## Java and Kotlin corpus

Twenty-five public repositories at pinned commits cover the `java` detector. Targeted (chosen knowing their result): `kagkarlsson/db-scheduler` (a multi-module Maven build, no findings), `piomin/sample-spring-reactive` (a `java.version` of 19), `danvega/loom` (`java.version`, `source`, and `target` of 19), `krakowski/jextract-demo` (a Gradle Kotlin DSL toolchain of 22), and `Descended/Henesys` (a `mysql:mysql-connector-java` 8.0.33 dependency, which the artifact's own POM relocates).

Blind (2026-10-23 rule below): `jzyong/GameServer4j` (JDK 13 and 14 compile levels across nine modules), `latexdraw/latexdraw` (`java.version` 14), `amigoscode/login-registration-backend` and `TechPrimers/spring-batch-example-1` (`java.version` 15), `moditect/jfrunit` (`java.version` 16, plus `actions/cache`, `actions/checkout`, and `actions/setup-java` at v2), `advanced-security/monorepo-filtering-workaround` (`java.version` 18, plus `actions/checkout@v3`), `ChristianAA/selenium-springboot-example` (JDK 18, plus Action pins), `stepstone-tech/doom-graalvm` (`java.version` 19), `vladannovi1234/ecommerce-springboot-react` (JDK 19 compile levels in ten modules), and three with no Java finding: `neo4j-examples/movies-java-spring-data-neo4j` and `stirante/RuneChanger` (JDK 17 and 11, both LTS; the first also has SHA-pinned Action findings), and `eh3rrera/graphql-java-spring-boot-example` (JDK 11 in the project, JDK 16 only inside a Maven profile, which the detector does not judge).

Blind stable expansion (2026-11-07 rule below): `maxithub/reactive-spring-tutorial` and `weltraumpirat/hexagonal_ddd` (`java.version` 13), `DomainDrivers/dd-java` and `LastBotInc/llama2j` (`java.version` 20), `mohamed-taman/Flight-Advisor` and `JPro-one/HelloJPro-Maven` (`java.version` 22), `mosh-hamedani/spring-store` (`java.version` 23), and `danvega/spring-boot-testing` (JDK 21 LTS, empty expected).

Every finding in these repositories is recorded, not only the Java ones, and each was checked by reading its line at the pinned commit. The ground truth is a `maintainer-review` note naming the path and line; none of the repositories has a migration commit for the finding. The JDK dates come from the Oracle Java SE Support Roadmap and the Temurin support page, and the relocation from the Maven Central POM, not from these repositories. A run of `npm run validate:public-repos -- --offline --ecosystem java` on 2026-11-07 over the twenty-five Java entries reported no false positives or false negatives, with 70 expected `java` findings, all true (20 repositories with Java findings in the Java bucket; 4 zero-finding Java-ecosystem repositories; 20 of 25 blind). Corpus-wide `countEvidence` for `java` is 21 repositories with findings and 71 expected findings.

## Java and Kotlin blind selection

The five earliest Java repositories were chosen knowing their result, so each records `selection: "targeted"`; the twelve below record `selection: "blind"`.

The blind rule, fixed on 2026-10-23 before Offing ran on these additions: GitHub code search `<java.version>N</java.version>` restricted to `filename:pom.xml`, for N in 14, 15, 16, 18, 19 (non-LTS, expected to produce findings) and 17 (LTS, expected to produce none), `gh search code --limit 60`. Per N, walk the results in order and keep the first two unique repositories whose matching path is exactly the root `pom.xml`, skipping forks, archives, repositories already in the corpus, and repositories larger than 50,000 KB on GitHub. Pin each at its default-branch commit on that date. The twelve are, in order: `jzyong/GameServer4j`, `latexdraw/latexdraw`, `amigoscode/login-registration-backend`, `TechPrimers/spring-batch-example-1`, `moditect/jfrunit`, `eh3rrera/graphql-java-spring-boot-example`, `advanced-security/monorepo-filtering-workaround`, `ChristianAA/selenium-springboot-example`, `stepstone-tech/doom-graalvm`, `vladannovi1234/ecommerce-springboot-react`, `neo4j-examples/movies-java-spring-data-neo4j`, and `stirante/RuneChanger`. `piomin/sample-spring-reactive` was skipped (already pinned). The query returns different results on another day, so the pinned list above, not a re-run, is the record.

Ground truth: for each repository every JDK declaration (`java.version`, `maven.compiler.*`, compiler-plugin `source`, `target`, and `release`, Gradle compatibility and toolchain settings, and `.java-version`, `.sdkmanrc`, `.tool-versions`) was listed with `grep` over the pinned files and compared with the report, independently of Offing's own output. Every expected finding has a `maintainer-review` note naming the path, the exact line, and the Oracle roadmap fact the rule rests on.

## Java and Kotlin stable expansion (2026-11-07)

To meet the stable evidence minimums of [decision 0013](../decisions/0013-detector-maturity.md) (21 repositories with Java findings, 4 zero-finding Java-ecosystem repositories, at least two thirds blind), the Java corpus gains further blind repositories. The selection rule below was fixed on 2026-11-07 **before** Offing ran on these additions.

Blind rule (2026-11-07): GitHub code search `filename:pom.xml` for `<java.version>N</java.version>` with N in **13, 20, 22, 23** (non-LTS, expected findings) and **21** (LTS, expected zero Java findings), `gh search code --limit 60`. Per N, walk the results in order; keep the first unique repositories whose matching path is exactly the root `pom.xml`; skip forks, archives, repositories already in the corpus, and repositories larger than 50,000 KB on GitHub. When pom search is exhausted for a version, also allow `build.gradle.kts` / `build.gradle` with `JavaLanguageVersion.of(N)` or `sourceCompatibility = JavaVersion.VERSION_1_N` / `VERSION_N` style. Pin each at its default-branch HEAD SHA on 2026-11-07. Prefer every new entry blind. Need enough new pins for seven repositories with Java findings and one zero-finding companion (JDK 21), so the bucket reaches 20 finding repositories and 4 zero-finding repositories.

The repositories kept by that walk, and the ground-truth notes for every finding on each pin (including other detectors), are recorded on the new `benchmarks/public-repositories/java/` entries listed above.

## Scala and sbt corpus

Eighty public repositories at pinned commits cover the `scala` detector. No public Scala corpus existed before 2026-11-07. The selection rules below were fixed on that date **before** Offing ran on any Scala addition. Scala 2.12 and 2.13 are intentionally not judged (still maintained); pins of those lines, and of Scala 3.3 LTS, are zero-finding / no-scala-finding controls. The corpus covers declaration forms `.scala-version`, `build.sbt` `scalaVersion`, and `project/build.properties` `sbt.version`. Rules in force: `scala.runtime.eol-2.11`, `scala.runtime.eos-3.0-3.2`, and `scala.sbt.eol-0.13`.

Blind alone reached stable evidence on 2026-11-07: 51 repositories with `scala.*` findings, 77 expected `scala` findings, 12 zero-finding Scala-ecosystem repositories, and all 80 repositories blind. No targeted multi-module additions were required. A run of `npm run validate:public-repos -- --offline --ecosystem scala` on that date reported precision 1 and recall 1 for `scala`.

### Scala and sbt blind selection

Blind rule, fixed on 2026-11-07 before Offing ran: `gh search code --limit 60` for each of:

1. `scalaVersion := "2.11` `filename:build.sbt`
2. `scalaVersion := "3.0` `filename:build.sbt`
3. `scalaVersion := "3.1` `filename:build.sbt`
4. `scalaVersion := "3.2` `filename:build.sbt`
5. `sbt.version=0.13` `filename:build.properties`
6. `2.11.` `filename:.scala-version` (content search for a 2.11 pin)
7. Zero-finding queries: `scalaVersion := "2.13`, `scalaVersion := "2.12`, and `scalaVersion := "3.3` `filename:build.sbt`

GitHub code search does not reliably match the `:=` token, so the walk used equivalent quoted version strings in the same filenames (`"2.11.12"`, `"2.11.8"`, `"2.11.11"`, `"3.0.2"`, `"3.1.3"`, `"3.2.2"`, `sbt.version=0.13.18` / `0.13.16`, `"2.13.12"`, `"2.12.18"`, `"3.3.3"`, and `2.11.12` in `.scala-version`) that still select repositories declaring those pins. Walk results in order; skip forks, archives, repositories already in the corpus, and repositories larger than 50,000 KB; keep when the default branch still has the matching file and the file still contains the pin. Pin each at its default-branch HEAD SHA on 2026-11-07. Need enough for stable counts (≥20 repositories with `scala.*` findings, ≥4 zero-finding Scala-ecosystem repositories, ≥⅔ blind, ≥60 `scala.*` expected findings). Prefer multi-module / nested project repositories for finding density. A few known multi-module finding-dense repositories may be added as `targeted` if blind alone cannot reach 60 findings; those are named as targeted in this section after selection.

Ground truth: for each pin every Scala/sbt declaration (and every other-detector finding on that pin) is read from the file and compared with the report. Every expected finding has a `maintainer-review` note naming the path, the exact line, and the vendor lifecycle fact the rule rests on (Scala development guarantees, sbt download / support pages). The query returns different results on another day, so the pinned list under `benchmarks/public-repositories/scala/`, not a re-run, is the record.

## Ruby corpus

Sixty public repositories at pinned commits cover the `ruby` detector, 41 of them selected blind (68%) and 19 targeted. 39 have expected Ruby findings (229 in total); 37 have expected findings of any detector (378 in total) and 23 have none. The original five are `rack/rack` (no findings), `Shopify/packwerk`, `thoughtbot/suspenders`, `github/view_component`, and `puma/puma` (a Gemfile `ruby "3.2.0"` directive). The selection rule was fixed before the results were read: GitHub repositories whose language is Ruby, ordered by stars, taking those with a Gemfile or `.ruby-version` at the default branch head; targeted entries are added where a manual search of `Gemfile` and `.ruby-version` showed a declaration the sample otherwise missed (a multi-requirement `ruby` directive). Each entry's `selection` field records which rule applied

Because the corpus scans every detector, every finding in these repositories is recorded, not only the Ruby ones. Each expected finding was checked by reading its line at the pinned commit, and its `groundTruthSource` is a `maintainer-review` note naming the path and line; none of these repositories has a reviewed migration entry in the mining log for the finding, so none is cited as `migration-commit`. The EOL dates come from the [Ruby maintenance branches](https://www.ruby-lang.org/en/downloads/branches/) page, not from these repositories.

## PHP corpus

108 public repositories at pinned commits cover the `php` detector, 73 of them selected blind (68%) and 35 targeted. 34 have expected PHP findings (70 in total); 55 have expected findings of any detector (235 in total) and 53 have none, including the original `laravel/laravel`. The selection rule was fixed before the results were read: GitHub repositories whose language is PHP, ordered by stars, taking those with a `composer.json` at the default branch head; targeted entries are added where a manual search of `require.php` showed a constraint form the sample otherwise missed (`^7.x`, `~7.2`, alternations of end-of-life lines). Each entry's `selection` field records which rule applied

Because the corpus scans every detector, every finding in these repositories is recorded, not only the PHP ones. Each expected finding was checked by reading its line at the pinned commit, and its `groundTruthSource` is a `maintainer-review` note naming the path and line; none of these repositories has a reviewed migration entry in the mining log for the finding, so none is cited as `migration-commit`. Package abandonment comes from Packagist and the Laminas / Symfony announcements; the PHP 7.4 end-of-life date comes from the [PHP unsupported branches](https://www.php.net/supported-versions.php) page, not from these repositories.

## Swift corpus

Eighty-five public repositories at pinned commits cover the `swift` detector.

Targeted: `seedco/Formalist` (`.xcode-version` 9.3.1 and an iOS 12 sample app), `bojan/Troop` (`.xcode-version` 10.2.1), `s2mr/xc` (`.xcode-version` 14.2.0), `s2mr/L10nLint` (`.xcode-version` 16.4.0), `Simperium/simperium-ios` (four iOS 8 application targets), and `JohnSundell/Files` (no findings).

Blind (rules below): the original seven from 2026-10-21, the later Swift corpus growth entries, and sixty-three repositories added on 2026-11-07 for the stable promotion. Because the corpus scans every detector, every finding in these repositories is recorded, not only the Swift ones. Each expected finding was checked by reading its line at the pinned commit, and its `groundTruthSource` is a `maintainer-review` note naming the path and line; none of these repositories has a reviewed migration entry in the mining log for the finding, so none is cited as `migration-commit`. The Xcode acceptance dates come from [App Store upcoming requirements](https://developer.apple.com/news/upcoming-requirements/), not from these repositories.

## Swift blind selection

The six earliest Swift repositories were chosen knowing their result, so each records `selection: "targeted"`. Later entries record `selection: "blind"`.

The first blind rule, fixed on 2026-10-21 before Offing ran on those additions: GitHub code search for `filename:xcode-version`. Walk unique repositories whose path is exactly `.xcode-version`, in the order returned that day. Skip a repository when it is a fork, archived, already in the corpus, not primarily Swift, or larger than 50,000 KB on GitHub. Keep it when the default branch still contains `.xcode-version`. Stop once the beta counts in [decision 0013](../decisions/0013-detector-maturity.md) are met, which happened at seven. The seven, pinned at their default-branch commit on that date, are search results 12, 19, 20, 22, 24, 28, and 31: `paulgessinger/swift-paperless`, `microsoft/SwiftStreamingMarkdown`, `hhru/mvi-swift`, `babylonhealth/Stevenson`, `cgoldsby/TvOSMoreButton`, `micahflee/TM-SGNL-iOS`, and `griffin-stewie/BudouX.swift`. Results before and between those were skipped by the rule above (size, language, or an existing pin), including `signalapp/Signal-iOS`, `Simperium/simperium-ios`, and `seedco/Formalist`. The query returns different results on another day, so the pinned list above, not a re-run, is the record.

The stable-promotion blind rule, fixed on 2026-11-07 before Offing ran on the new additions: GitHub code search in this order — `filename:.xcode-version` (limit 100), `IPHONEOS_DEPLOYMENT_TARGET = 9` in `filename:project.pbxproj` (limit 60), then `14.`, `15.`, and `16.0` in `filename:.xcode-version` for older pins still on default branches. Walk each result list in order. Skip forks, archives, repositories already in the corpus, and repositories larger than 50,000 KB. Prefer Swift or Objective-C as the repository language for the Xcode-version queries. Pin each kept repository at its default-branch HEAD that day. Stop once the stable counts in decision 0013 are met with margin. The sixty-three new files under `benchmarks/public-repositories/swift/` (indexes 0818–0880) are that batch. The query returns different results on another day, so the pinned list, not a re-run, is the record.

Ground truth: for each repository the `.xcode-version` line, every application-target `IPHONEOS_DEPLOYMENT_TARGET`, and any other detector declaration on that pin were read from the file and compared with the report. Pins at Xcode 26 and later produce no Xcode finding under the bundled rules. Every expected finding has a `maintainer-review` note naming the path, the exact line, and the vendor date the rule rests on.

## Serverless corpus

Forty-one public repositories at pinned commits cover the `serverless` detector.

Targeted: `Dwolla/webhook-receiver` (`provider.runtime` `nodejs14.x`), `haltakov/natural-language-image-search` (`provider.runtime` `python3.8`), `HUK-COBURG/innoforum-aws-serverless` (SAM and Terraform `nodejs14.x`, plus GitHub Actions pins), `BaptisteLecat/gcp_architect_certification` (Terraform Google Cloud Functions `nodejs14`), and `aws-samples/sam-python-crud-sample` (five SAM `python3.8` functions, plus GitHub Actions pins).

Blind (rule below): `serverless/examples` and `AnomalyInnovations/serverless-stack-demo-api` (no findings), `Swizec/lambda-screenshot-as-a-service` (`nodejs14.x`), `skojin/send-gmail-lambda` (`ruby2.7`), and `livgust/covid-vaccine-scrapers` (seven SAM `nodejs14.x` functions, plus Node.js and GitHub Actions pins).

Because the corpus scans every detector, every finding in these repositories is recorded, not only the Serverless ones. Each expected finding was checked by reading its line at the pinned commit, and its `groundTruthSource` is a `maintainer-review` note naming the path and line; none of these repositories has a reviewed migration entry in the mining log for the finding, so none is cited as `migration-commit`. The AWS Lambda and Google Cloud Functions end-of-life dates come from the [AWS Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) table and the [Cloud Run functions runtime support](https://cloud.google.com/functions/docs/runtime-support) schedule, not from these repositories.

**Correction (new rules, 2026-10-31).** Rules added after these entries were pinned now report on them, and the first corpus run listed each as unexpected: the Dockerfile `legacy-env-format` and `maintainer` rules on `hasura/skor` and `kubernetes/examples`, and the AWS Lambda rules for runtimes that are still supported (for example `nodejs22.x`, `nodejs24.x`, `provided.al2`) on `serverless/examples`, `aws-samples/aws-lambda-extensions`, `serverlesspub/imagemagick-aws-lambda-2`, and `slackapi/bolt-js`. Each was confirmed by reading the line at the pinned commit and added to `expected` with a `maintainer-review` note. That left `hasura/skor` and `serverless/examples` as no longer empty, so three targeted zero-finding entries were added to keep the beta evidence of decision 0013: `kubernetes-up-and-running/examples` (plain manifests), and `BauplanLabs/quack-reduce` and `dvalbuena1/visa_rescheduler_aws` (container-image and runtime-less Serverless Framework services, which declare no runtime for a rule to judge).

## Serverless blind selection

The five earliest Serverless corpus repositories were chosen knowing their result, so each records `selection: "targeted"`. The five below record `selection: "blind"`.

The blind rule, fixed on 2026-10-21 before Offing ran on these additions: GitHub code search for `runtime: nodejs14.x` in `filename:serverless.yml`, plus the first results of `Runtime: nodejs14.x` / `Runtime: python3.8` in SAM `template.yaml` and of current `runtime: nodejs22.x` examples, walking public non-fork repositories in the order returned that day. Keep a repository when its default-branch tip contains `serverless.yml`, `template.yaml` / `template.yml`, or a Terraform `aws_lambda_function` / `google_cloudfunctions*_function` runtime declaration; skip archives and the repositories already pinned as targeted. Stop at five. The five, pinned at their default-branch commit on that date, are `serverless/examples`, `AnomalyInnovations/serverless-stack-demo-api`, `Swizec/lambda-screenshot-as-a-service`, `skojin/send-gmail-lambda`, and `livgust/covid-vaccine-scrapers`. The query returns different results on another day, so the pinned list above, not a re-run, is the record.

Ground truth: for each repository the runtime lines (and any other detector findings on the same pin) were listed by reading the pinned files and compared with the report, independently of Offing's own output. Every expected finding has a `maintainer-review` note naming the path, the exact line, and the vendor date the rule rests on.

## Serverless stable expansion (2026-11-08)

To meet the stable evidence minimums of [decision 0013](../decisions/0013-detector-maturity.md), the Serverless corpus gains further blind repositories. The selection rule below was fixed on 2026-11-08 **before** Offing ran on these additions.

Blind finding rule (2026-11-08): `gh search code --limit 40` for `nodejs14.x` `--filename serverless.yml`, `python3.8` `--filename template.yaml`, `runtime = "nodejs14.x"` `--extension tf`, and `node_version = "14"` `--extension tf` (Azure App Service / Functions pins). Walk results in order; keep unique non-fork, non-archived repositories under 50,000 KB that are not already in the corpus; pin each at its default-branch HEAD that day.

Blind zero-finding rule (same day): walk tiny image-oriented or empty-runtime candidates from repository search (`serverless image packaging`, small star counts); keep only when the offline scan reports nothing for every detector. Kept zeros: `CloudNationHQ/terraform-azure-func` (module with no literal stack pin) and `api-evangelist/echo` (alongside the earlier targeted zeros).

The same change wires Azure `application_stack` version pins to `pkg:generic/azure-app-service/<stack>` rules (regression fixtures under `tests/fixtures/serverless/`). Corpus-wide `countEvidence` for `serverless` meets every stable row. Offline validate on the Serverless bucket reported precision 1 and recall 1.

## .NET blind selection

The six earliest .NET repositories were chosen knowing their result, so each records `selection: "targeted"`. The `selection` field is optional on every corpus entry; `"blind"` means the repository was chosen by a rule fixed before Offing ran on it ([decision 0013](../decisions/0013-detector-maturity.md)), and an entry without the field counts as not blind.

The blind rule, run on 2026-10-19: GitHub repository search for `language:C#`, 100 to 500 stars, last pushed from 2021-01-01 to 2024-12-31, not a fork, not archived, sorted by stars descending (`gh search repos --language "C#" --stars "100..500" --updated "2021-01-01..2024-12-31" --archived=false --include-forks=false --sort stars --order desc`). Walk the results in order and take each repository whose default branch has at least one `*.csproj`, `*.fsproj`, `*.vbproj`, or `global.json`; skip the others (Unity packages with no project file). Stop at twelve, whatever Offing reports for them. The twelve, pinned at their default-branch commit on that date, are results 1, 3, 5, 7, 9, 10, 11, 12, 13, 14, 15, and 16 of that search: rikimaru0345/Ceras, takuya-takeuchi/DlibDotNet, 0xthirteen/SharpStay, NightfallGT/Mercurial-Grabber, Dec0ne/ShadowSpray, Ceiridge/Chrome-Developer-Mode-Extension-Warning-Patcher, TerribleDev/OwinOAuthProviders, chsakell/mvcarchitecture, SeriaWei/ASP.NET-MVC-CMS, stanzhai/Html2Article, BeichenDream/SharpToken, and nettitude/SharpSocks. Ranks 2, 4, 6, and 8 have no project file. The query returns different results on another day, so the pinned list above, not a re-run, is the record.

Ground truth: for each repository the target frameworks, SDK pins, and package references were listed by `grep` over the pinned files and compared with the report, independently of Offing's own output. Every expected finding has a `maintainer-review` note naming the path, the exact line, and the vendor date the rule rests on. Ceras was the one miss: it targets `netcoreapp2.1` and `netcoreapp2.2`, which had no rule, so the registry gained the 1.x, 2.x, and 3.0 lines in the same change.

## CI runner images corpus

Five public repositories at pinned commits cover the `ci-images` detector: `oatpp/oatpp` (`ubuntu-20.04` and `ubuntu-22.04` hosted images), `Chinachu/Mirakurun` (four `ubuntu-22.04` pools, plus a deprecated `tslint` dependency), `microsoft/Sysmon-Linux` (`ubuntu-22.04`, plus `actions/checkout` v4.1.1), `aliostad/CacheCow` (`ubuntu-22.04`, plus .NET target frameworks past or scheduled for end of support), and `Windos/PoshNotify` (Azure Pipelines pools that use only `*-latest` images, no findings).

Issue #1898 added 86 entries: 60 blind and 26 targeted. The first blind rule, fixed on 2026-11-07 before Offing ran on the results: GitHub code search for `vmImage` in files named `azure-pipelines.yml`, taking hits in the order returned, one repository once; skip forks, repositories already in the corpus, and repositories over 100,000 KB; take the first 35. They are: `ardalis/GuardClauses`, `ardalis/SmartEnum`, `shahedc/NetLearnerApp`, `microsoft/SDCM`, `fastpack/fastpack`, `sestoft/C5`, `DigitalRuby/ExchangeSharp`, `imbushuo/EnergyStar`, `dotpcap/sharppcap`, `microsoft/vswhere`, `reanimate/reanimate`, `EducationalTestingService/skll`, `vkhorikov/CSharpFunctionalExtensions`, `danielga/garrysmod_common`, `Gericom/GBARunner2`, `microsoft/MSBuildSdks`, `ra1028/DiffableDataSources`, `seahorn/seahorn`, `gaelcolas/Sampler`, `microsoft/OpenXR-MixedReality`, `sixeyed/dockerfiles-windows`, `foonathan/array`, `alanmcgovern/Mono.Nat`, `analogdevicesinc/EVAL-ADICUP360`, `jet/FsKafka`, `UiPath/angular-components`, `ignatandrei/NETCoreBlockly`, `Amitpnk/Hexagonal-architecture-ASP.NET-Core`, `Azure/AppConfiguration-DotnetProvider`, `AugurProject/augur.js`, `sujiar37/AWX-HA-InstanceGroup`, `microsoft/MeshGraphormer`, `ivanpaulovich/FluentMediator`, `Simnico99/MicaWPF`, and `Foxlider/FASTER`. That sample was almost all `*-latest` images, so a second blind rule was fixed the same day: the same search, restricted to repositories whose last push is between 2022-01-01 and 2023-12-31, first 25: `zHaytam/SmartBreadcrumbs`, `vector-of-bool/pmm`, `dmyersturnbull/tyrannosaurus`, `Capgemini/xrm-datamigration`, `alexwang66/Guestbook-microservices-k8s`, `OfficeDev/microsoft-teams-apps-timetally`, `surge-synthesizer/tuning-workbench-synth`, `GoranHalvarsson/SitecoreBlazor`, `godsharp/GodSharp.Socket`, `dtylman/AWSRetriever`, `GriffinPlus/docker-strongswan`, `WinOpsDBA/DBAinTheCloud`, `StirlingLabs/Assimp.Net`, `shibayan/IISManager`, `hexawyz/NetUnicodeInfo`, `Softeq/mapbox-xamarin`, `ecampidoglio/Linker`, `CCRcmcpe/Auto-Arknights`, `tanathos/ClippyVS`, `psfinaki/CheckYourCzech`, `ZacBi/learn_NLP_again`, `kshitizadhikari/HexagonArchitecture1`, `attilaszasz/dotnet-catapult`, `sVathis/ebay-watchlist-calendar`, and `Sauceforge/SauceOpsMobile`. The 26 targeted entries were chosen knowing they declare older images: GitHub code search for `ubuntu-22.04` (14 repositories) and then `ubuntu-20.04` (12) in `azure-pipelines.yml`, same skips, first hits in order. The searches return different results on another day, so the pinned list is the record. GitLab CI and CircleCI repositories are not added: the detector reads them but judges nothing, so they could not carry findings.

The ci-images corpus now has 98 entries, 67 blind (68%). 29 have expected CI image findings (63 in total) and 20 have no findings of any detector. A full offline run reported no false positives and no false negatives for the detector.

Because the corpus scans every detector, every finding in these repositories is recorded, not only the CI image ones. Each expected finding was checked by reading its line at the pinned commit, and its `groundTruthSource` is a `maintainer-review` note naming the path and line. The Azure dates come from the [hosted image deprecation schedule](https://learn.microsoft.com/azure/devops/pipelines/agents/hosted-deprecation-schedule) and the [Azure DevOps blog deprecation plan](https://devblogs.microsoft.com/devops/upcoming-updates-for-azure-pipelines-agents-images/), not from these repositories. All five were chosen knowing their image labels, so each records `selection: "targeted"`.

## Container corpus

Issue #1898 added 30 container entries, all blind. The rule, fixed on 2026-11-07 before Offing ran on them: GitHub code search for `FROM` in files named `Dockerfile`, taking hits in the order the search returned them, one repository once. Skip forks, repositories already in the corpus, repositories over 100,000 KB, and repositories with more than 20 `Dockerfile*` files. Take the first 30. They are, in order: `laradock/php-fpm`, `laradock/workspace`, `NVIDIA-Genomics-Research/AtacWorks`, `Haufe-Lexware/docker-style-guide`, `jcgay/maven-color`, `istepanov/docker-mongodump`, `dreasysnail/RetGen`, `aerospike/aerospike-dev-notebooks.docker`, `botchagalupe/DockerDo`, `logandk/serverless-rack`, `transferwise/wise-pizza`, `NSEcho/furlzz`, `s7anley/redis-sentinel-docker`, `onecompiler/cheatsheets`, `edyan/php-fpm`, `rootsongjc/cheatsheets`, `behance/docker-php`, `aerospike-examples/interactive-notebooks`, `dvmonroe/sanity-ruby`, `maidaly/Arabic_OCR`, `PremiereGlobal/freeswitch-docker`, `Comcast/Ravel`, `tedsluis/docker-dump1090`, `dramforever/os-lectures-build`, `estafette/estafette-extension-dotnet`, `upconsulting/IsisCB`, `chrishenry/deltanyc-heatseek`, `lucdotdev/youtube_tiktok`, `jbochi/bullock`, and `whorusq/learning-docker`. The search skipped `appleboy/golang-testing` (27 Dockerfiles). The query returns different results on another day, so the pinned list, not a re-run, is the record.

The corpus now has 42 container entries, 37 blind (88%). Seven have no findings of any detector. A full offline run reported no false positives and no false negatives for the container detector.

Because the corpus scans every detector, every finding is recorded, not only the container ones, and each expected finding was checked by reading its line at the pinned commit.

## Dart corpus

Issue #1894 promoted the `dart` detector to stable. The corpus holds 75 pinned Dart repositories: 55 selected blind (73%) and 20 targeted. Across the whole corpus the detector expects 138 findings in 31 repositories (30 of them in the Dart bucket, plus a Dart SDK pin in `railwayapp/nixpacks`); 18 Dart-bucket repositories have no expected findings of any detector.

**Blind rule (fixed 2026-11-07 before Offing ran on these additions):** GitHub repository search `--language=Dart --stars='>=80' --archived=false`, sorted by stars descending. Walk results in order; keep a repository when its default branch contains a `pubspec.yaml`, it is not a fork, it is not already in the corpus, and it is not a meta list such as `awesome-flutter`. Skip `flutter/flutter` (over the 100,000 KB size cap). Take the first 48. Pin each at its default-branch HEAD commit SHA on that day.

**Targeted rule (fixed the same day):** GitHub code search for `>=2.17.0 <3.0.0` in `filename:pubspec.yaml`, taking hits in returned order, one repository once; skip forks, templates (`.twig`, `.hbs`, `templates/`), repositories already chosen, and repositories already in the corpus. Cap at 15. Earlier targeted entries cover exact SDK pins of Dart 3.8.

Ground truth: every finding in these repositories, from every detector, was read at its pinned line and recorded with a `maintainer-review` note naming the path and line. Dart end-of-support dates come from the [Dart security policy](https://dart.dev/security) and [changelog](https://dart.dev/changelog).

## Android corpus

Issue #1894 promoted the `android` detector to stable. The corpus holds 84 pinned Android repositories: 56 selected blind (67%) and 28 targeted. Across the whole corpus the detector expects 87 findings in 42 repositories (including Android findings declared in other ecosystems' pins); 22 Android-bucket repositories have no expected findings of any detector.

**Blind rule (fixed 2026-11-07 before Offing ran on these additions):** GitHub code search for `targetSdk` in `filename:build.gradle`, then the same for `filename:build.gradle.kts`. Walk hits in returned order, one repository once across both queries. Skip forks, archives, repositories already in the corpus, and paths that are not exactly `build.gradle` / `build.gradle.kts` or under a directory with those names. Take the first 48. Pin at default-branch HEAD.

**Targeted rule (fixed the same day):** GitHub code search for `targetSdk 28` through `targetSdk 30` in `filename:build.gradle`, and `targetSdk = 33` / `targetSdk = 34` in `filename:build.gradle.kts`, taking repositories whose matching path ends in `build.gradle` or `build.gradle.kts`. Skip forks, archives, already-chosen repositories, and template/backup suffixes. Cap so the blind share stays at or above two thirds.

Ground truth: every finding was read at its pinned line. Play Billing deprecation dates come from the [Billing Library deprecation FAQ](https://developer.android.com/google/play/billing/deprecation-faq); the targetSdk floor comes from [Google Play's target API level requirement](https://developer.android.com/google/play/requirements/target-sdk).

---

Source: https://velella.sh/offing/validation/running-the-corpus/

# Running the corpus

How to fetch, cache, narrow, record, and read a corpus run. The summary and the accuracy table are on [Validation](../VALIDATION.md).

## Fetching and the checkout cache

The harness fetches up to sixteen repositories at once; change that with `--concurrency <n>` or `OFFING_CORPUS_CONCURRENCY`. Scans and the report stay in corpus order.

By default it fetches each repository as a blobless shallow fetch plus a sparse checkout of only the files the detectors declare they read ([decision 0015](../decisions/0015-corpus-fetch-strategy.md)): a cold full run takes about a minute and fetches about 190 MB, and the results are identical to a full checkout. `OFFING_CORPUS_FETCH=shallow` fetches complete checkouts instead. `node dist/benchmarks/fetch-strategies.js --strategy <shallow|sparse|tarball>` re-measures the options.

Every corpus commit is pinned, so a checkout never changes. Set `OFFING_CORPUS_CACHE=<dir>` (for example `~/.cache/offing-corpus`) to keep each one on disk as `<owner>__<repo>@<commit>` and skip the network when it is already there. Entries are written to a temporary directory and renamed into place, and `.git` is removed because scans read files only, so an interrupted run never leaves a half-filled entry. A sparse entry carries an `.offing-fetch` marker naming the declarations it was built from; if a detector later declares more files, that entry is refetched rather than reused. Unset, there is no cache and a run behaves as before. A warm run reports the same true positives, false positives, false negatives, and findings as a cold one.

## Running a subset

```bash
npm run validate:public-repos -- --ecosystem php
npm run validate:public-repos -- --ecosystem php --ecosystem ruby
npm run validate:public-repos -- --repo laravel/framework
```

`--ecosystem <name>` and `--repo <owner/name>` are repeatable; naming both selects the union, reported in corpus order. An unknown name is an error that lists the valid ones. A filtered run still fails on any false positive or false negative among the entries it covers, but it is not a full run: it does not enforce the per-detector precision floors, it writes no `lastFullRun`, the JSON report says `"fullRun": false` with a `filter` line, and the run prints `FILTERED RUN` on stderr. Only an unfiltered run can be recorded or compared with the full-corpus claims in this document.

### Re-running only what failed

After fixing a detector, re-check just the repositories that had a mismatch:

```bash
npm run validate:public-repos -- --output corpus-result.json     # a run with UNEXPECTED or MISSING lines
npm run validate:public-repos -- --failed-from corpus-result.json
```

`--failed-from <report.json>` runs the repositories whose entry in that report has an `unexpected` or `missing` finding; any that have left the corpus are skipped. It is a filtered run like the others (`FILTERED RUN` on stderr, `"fullRun": false`) and never counts as a full run. A report with no mismatches prints that and exits 0 without fetching anything.

### Comparing with an earlier run

```bash
npm run validate:public-repos -- --compare corpus-result.json
npm run validate:public-repos -- --compare benchmarks/thresholds.json
```

`--compare <file>` prints what moved since that file. Against an earlier report it lists `ADDED` and `REMOVED` findings per repository and the per-detector true-positive, false-positive, and false-negative differences (`DELTA`), computed over the repositories present in both, so a filtered run compares like with like. Against `benchmarks/thresholds.json` it uses the recorded `lastFullRun` for the per-detector numbers only. Comparing never changes the exit code: false positives, false negatives, and the precision floors still decide it, and an unreadable comparison file is reported without failing the run.

### Managing the cache

A cache of complete checkouts is about 1.5 GB on disk; the default sparse entries need about 570 MB. A suggested location is `~/.cache/offing-corpus`; set `OFFING_CORPUS_CACHE` to it in your shell profile.

```bash
npm run corpus:cache -- status                       # directory, entry count, total size, entries no longer in the corpus
npm run corpus:cache -- prune --dry-run              # what removing entries no longer in the corpus would do
npm run corpus:cache -- prune                        # remove entries that are no longer in the corpus
npm run corpus:cache -- prune --max-size 800         # remove least recently used entries until the cache is at most 800 MB
npm run corpus:cache -- prune --all                  # empty the cache
```

`--dry-run` works with every `prune` form and removes nothing. Every cache hit refreshes the entry's last-used time, which is what `--max-size` orders by. The commands only ever touch directories directly under the cache directory whose names look like `<owner>__<repo>@<40-hex commit>`; anything else in there is left alone, and an empty or root-like path (`/`, your home directory, a single top-level directory) is refused.

### Warm ahead, run offline

```bash
npm run corpus:warm                       # fetch every missing checkout into the cache and stop; no scan
npm run corpus:warm -- --ecosystem php    # the same filters as a run
npm run validate:public-repos -- --offline
```

Both need `OFFING_CORPUS_CACHE` and print how many entries were already cached. `--offline` uses the cache only: if an entry is missing it fails before scanning anything, with exit code 2 and one message that lists every missing `repository@commit`. After `corpus:warm`, an `--offline` run reports the same results as an online one. A good habit is `npm run corpus:warm` after pulling `main`, so a later run never waits on a download.

### Running only what a change affects

```bash
npm run validate:public-repos -- --changed            # changes since origin/main, plus uncommitted and untracked files
npm run validate:public-repos -- --changed release/1  # a different base
```

`--changed [base]` reads `git diff --name-only <base>...HEAD` together with uncommitted and untracked files and maps them to corpus ecosystems with [`benchmarks/corpus-affected.ts`](../../benchmarks/corpus-affected.ts): `src/detectors/<name>`, `registry/<file>.json`, and `tests/fixtures/<name>/` map to the ecosystems that detector serves (for example `src/detectors/npm/index.ts` and `registry/nodejs.json` to `node`, the GitHub Actions detector to `node-actions`), and shared files map to every ecosystem whose detectors use them (`src/source-usage.ts` to nine ecosystems; `src/engine/`, `src/sdk.ts`, and the other scan-wide files to all twelve). It prints one `changed:` line per chosen ecosystem naming the paths behind it. If nothing maps, it says so and exits 0 without fetching. The result is a filtered run like any other, and it combines with `--ecosystem` and `--repo`.

The map is tested: every built-in detector, every corpus ecosystem, every directory under `src/detectors/`, every file in `registry/`, and every shared file a detector imports must be listed, so adding a detector fails `npm run check` until it is mapped. Other work can import the same module, for example a pull request workflow.

## Sharding a full run

A full run is split into eight shards, one CI job each, so the run stays inside the nightly budget at the 4,600-repository target. Locally:

```bash
npm run validate:public-repos -- --shard 2/8 --offline
npm run corpus:merge -- --dir shard-reports --output corpus-result.json
```

`--shard <index>/<count>` keeps every `count`th entry starting at `index`, applied after `--ecosystem`, `--repo`, `--failed-from`, and `--changed` have selected the entries. Every entry belongs to exactly one shard and membership is stable for a given corpus order, so two runs pick the same split. The JSON report records `"shard": { "index": 2, "count": 8 }`.

A shard is not a full run: it says `"fullRun": false`, does not enforce the precision or recall floors, and `npm run record:corpus-run` refuses `--shard`. Each shard writes `corpus-result-<shard>.json`. `node dist/benchmarks/corpus-merge.js --dir <dir>` reads exactly the `corpus-result-<n>.json` files, refuses anything that is not the complete set of verify-mode shards, checks every repository against its pinned commit exactly once, merges in corpus order, enforces the floors, and writes the single full report the artifact and the job summary expect. It applies the shard budgets described below.

Each repository is scanned in its own child process with an old-generation heap limit: 1024 MB by default, `--memory-limit <MB>` or `OFFING_CORPUS_MEMORY_MB` to change it. A repository that exceeds the limit, throws, or runs longer than its scan timeout (300 s by default, `OFFING_CORPUS_SCAN_TIMEOUT_SECONDS`) prints as `FAILED owner/repo@commit: reason`, counts its expected findings as missing, and the run carries on to the next repository; the run fails at the end. A fetch that exhausts its retries is recorded the same way, so one repository can neither crash the shard nor hide behind a missing report.

## Run cost and budget

Every report carries a `cost` block: total wall time, the summed fetch time (larger than the wall time when fetches overlap), cache hits and misses, and the size of the git data fetched (git does not expose network bytes, so this is the `.git` size of each fetched checkout). The run prints it as a `COST` line, and the weekly workflow shows it in the job summary.

`benchmarks/thresholds.json` holds the `budget`: a wall-time limit in seconds and a fetched-bytes limit, **per job** — one shard, or one unsharded run. Going over either prints a `BUDGET` warning (a `::warning::` annotation in Actions), lists it in the report's `budgetWarnings`, and flags it in the job summary. A merged report compares its summed fetched bytes against the limit times the shard count and its wall time (the slowest shard) against the single-shard limit. A budget overrun never fails the run; correctness is decided by false positives, false negatives, and failed scans.

The current limits are 600 s and 500 MB per shard, measured rather than guessed. At the 4,600 target a shard owns about 575 repositories, 8.3 times today's 70. A warm shard of 70 takes about 13 s (about two minutes at the target). A cold shard of 70 measured 107.1 s and fetched 53.3 MB here (another run of the same shard took 319.5 s on the same connection), which is about 440 MB for one target shard; decision 0015 measured 112 repositories cold in 49.8 s on an ordinary connection. The 600 s and 500 MB limits leave room for that spread, and the weekly job's timeout is 20 minutes. Tighten the budget in a pull request when a faster fetch strategy lands, and raise it only with a stated reason and a measurement.

## Stalled fetches

One hung connection must not hold a run. Each fetch passes git's low-speed abort (`http.lowSpeedLimit=1000`, `http.lowSpeedTime=30`: below 1 KB/s for 30 s) and a hard limit of 120 s per attempt, changed with `OFFING_CORPUS_FETCH_TIMEOUT_SECONDS`. A stall counts as a failed attempt, so it is retried and, when every attempt fails, recorded as a `FAILED` entry for that repository while the rest of the shard continues. At the end of every run the five slowest fetches print as `SLOWEST` lines.

## Reading a run

By default a run prints a short table on stdout instead of the full JSON: true positives, false positives, false negatives, and precision per ecosystem and per detector, then every `UNEXPECTED`, `MISSING`, and `FAILED` line, then a one-line wall-time summary. Progress goes to stderr as one line per fetched repository (`12/107 owner/name 2.1s`). The `COST`, `SLOWEST`, and `BUDGET` lines follow on stderr.

A `FAILED` line names a repository whose scan or fetch failed (for example its memory limit or its retries) and why. Its expected findings count as missing, and `summary.scanErrors` counts it, so it can never pass as a clean result or disappear from the report.

```bash
npm run validate:public-repos -- --output corpus-result.json   # table on screen, full JSON in the file
npm run validate:public-repos -- --json > corpus-result.json   # JSON on stdout; the table moves to stderr
```

`--output <file>` writes the full JSON report whatever the result, so a failing run still leaves it behind. The weekly workflow uses `--output` and uploads that file as the `corpus-result-<run id>` artifact.

## Recording a full run

```bash
npm run record:corpus-run
```

One command replaces the hand edits. It runs the whole corpus in verify mode and, only when that passes, writes the run into `lastFullRun` in `benchmarks/thresholds.json` (date, the current `HEAD` commit, repository and finding counts, precision, recall, and true positives, false positives, and false negatives for every detector, zero for one that reported nothing), then regenerates a local `docs/dashboard/data.json` preview (`npm run build:dashboard`; gitignored; Pages builds the published copy), the accuracy table below (`npm run build:coverage`), and a local `docs/llms-full.txt` preview (gitignored; Pages builds the published copy). It leaves the tracked changes uncommitted so you can review the diff.

It refuses, and changes nothing, when:

- the working tree has uncommitted changes, because the recorded commit would not describe them;
- any run-narrowing flag is passed (`--ecosystem`, `--repo`, `--failed-from`, `--changed`, `--shard`), or `--observe`, `--warm`, `--output`, `--json`, or `--compare`;
- the run did not cover every corpus entry, was not in verify mode, or has any false positive or false negative, a failed scan, or a detector below its precision floor.

Other harness flags such as `--concurrency` and `--offline` are passed through. Recording runs the corpus in one process, not in shards, because `lastFullRun` is written from a single complete report; the `record` job's 60-minute timeout covers it. The dashboard tests read the recorded commit, counts, and age from `benchmarks/thresholds.json` instead of repeating them, so recording a new run needs no test edits.

## Pull request check

Pull request CI (`ci.yml`) stays offline, so a detector or rule change that adds false positives would only be found in the weekly run. The `affected` job in [`.github/workflows/corpus.yml`](../../.github/workflows/corpus.yml) closes that gap: when a pull request touches `src/`, `registry/`, `tests/fixtures/`, or `benchmarks/`, it maps the changed files to corpus ecosystems with the same `--changed` logic described above and runs only those, using the weekly run's checkout cache (restore only). It always runs unsharded: the pull request keeps a single, affected-ecosystems-only job. The same workflow also covers the full and record modes via schedule and a `mode` `workflow_dispatch` input.

Before it fetches anything, the affected job also runs `node dist/benchmarks/corpus-snapshot.js`, and the same comparison runs in `npm test` for every pull request. [`benchmarks/corpus-snapshot.json`](../../benchmarks/corpus-snapshot.json) records how many findings, in how many repositories, the corpus expects for each detector. A change that removes or weakens an expectation, so that a known finding would no longer be required, fails with a `SNAPSHOT` line until the snapshot is updated on purpose with `node dist/benchmarks/corpus-snapshot.js --write`; that edit is a reviewable diff. Adding expectations never fails; run `--write` to ratchet the snapshot up.

The job summary lists the chosen ecosystems and every `UNEXPECTED` and `MISSING` line; the full report is attached as the `corpus-affected-result-<run id>` artifact. If nothing maps, it says so and fetches nothing. The job is **not a required check**: keep it out of branch protection, because it needs the network and GitHub's availability. It has `contents: read` only, no secrets, and no `pull_request_target`, and the base branch reaches the shell through an environment variable, never an inline expression. Treat a red run as a finding to explain in the pull request, using the rules in "Weekly run and refreshing pins" above.

Drift is invisible until a branch touches the ecosystem. The job only compares the ecosystems the changed files map to, so a finding the detectors report but the ground truth omits sits unnoticed on `main` until an unrelated pull request makes that ecosystem affected (for example, a change under `benchmarks/public-repositories/python/` or `container/`). A red `corpus (affected ecosystems)` job that names a repository your diff does not touch is probably that earlier drift, not your regression: reproduce it on `main` with `--offline --repo <owner/name>` before changing anything, and fix it in its own pull request.

## Keeping `lastFullRun` current

Decision 0013 requires a recorded full run within 30 days for `beta` and `stable`. The `record` job in [`.github/workflows/corpus.yml`](../../.github/workflows/corpus.yml) runs `npm run record:corpus-run` on the 1st and 15th of each month (and on demand with `mode=record`) and opens a pull request with the result. It records nothing when the run has a false positive, a false negative, or a missed floor, so a failed run leaves the old record and a red workflow. A maintainer reviews and merges that pull request; the record is never pushed to `main` directly.

## Weekly run and refreshing pins

Pull request CI never touches the network, so the corpus is checked by the `full` job in [`.github/workflows/corpus.yml`](../../.github/workflows/corpus.yml) every Monday and on demand (Actions → Corpus → Run workflow, `mode=full`). It runs eight shards in parallel, each restoring the shared checkout cache, and a `merge` job joins their reports into one full run; if any shard fails, the merge job does not run and no full result is published. The merged result is uploaded as the `corpus-result-<run id>` artifact even when it has mismatches. A failing run prints one line per mismatch, for example:

```text
UNEXPECTED owner/repo@4ec1ebe0fa: github-actions.setup-node.node20:.github/workflows/ci.yml:20
MISSING    owner/repo@4ec1ebe0fa: nodejs.runtime.eol-18:package.json:83
FAILED     owner/huge@4ec1ebe0fa: scan exceeded the 1024 MB per-repository memory limit
```

`UNEXPECTED` means Offing reported a finding the corpus does not list; `MISSING` means a listed finding was not reported. Because every commit is pinned, a mismatch means Offing's rules or detectors changed, not the repository. Decide which side is right before touching the corpus: fix the detector or rule when the corpus is right, and update the expected entry (with its `groundTruthSource`) only when the new result is correct.

To move an entry to a newer commit, change its `commit` to the full 40-character SHA, run `npm run observe:public-repos` to list what Offing now reports, review every difference against the repository at that commit, update `expected`, and run `npm run validate:public-repos` until it passes. Never refresh a pin only to make a failing run green.

---

Source: https://velella.sh/offing/validation/differential-testing/

# Differential testing

How Offing's findings compare with Renovate, xeol, and Pluto, and what each disagreement means. The summary and the accuracy table are on [Validation](../VALIDATION.md).

## Differential testing against Renovate

Renovate is the closest widely used tool, so the report compares Offing's findings with Renovate's for the same repository, by rule family. A maintainer runs Renovate (it needs the network and a large download; it is not part of `npm run check` or any scan). Give it a read-only GitHub token, or it cannot look up GitHub Actions:

```bash
export RENOVATE_TOKEN=<token> GITHUB_COM_TOKEN=<token>
npx renovate --platform=local --dry-run=lookup --report-type=file --report-path=renovate.json
npm run differential:renovate -- --renovate renovate.json --repository . --name owner/repo --out report.json
```

The two tools answer different questions. Renovate says a newer version exists and prints npm deprecation notices; it has no end-of-life data. Offing says a release line is past its vendor's end of life; it does not say an update exists. So the report only compares where both can speak about one dependency in one file:

| Family | Offing | Renovate | Counted as agreement |
| --- | --- | --- | --- |
| `deprecated-package` | `npm.package.*` findings | npm `deprecationMessage` | both mark the package deprecated |
| `base-image` | `container.*` findings | `dockerfile` / `docker-compose` updates | Renovate offers an update for the image Offing calls end-of-life |
| `github-action` | `github-actions.*` findings | `github-actions` updates | Renovate offers an update for the action Offing flags |

Outcomes: `agree`, `offing-only`, `renovate-only`, and `inconclusive` (Renovate skipped the lookup, for example `github-token-required` for Actions when run without a GitHub token, so it says nothing either way). Runtime findings (`nodejs.runtime.*`, `python.runtime.*`) have no Renovate counterpart and are listed as not comparable. Matching is by file and dependency name because Renovate gives no line numbers.

The committed reports are combined into one reviewable page, [differential-report.md](../differential-report.md) (and [differential-report.json](../differential-report.json)), which lists every disagreement with links to the declaration at the pinned commit and to each tool's evidence. Regenerate it with `npm run differential:report` after adding or refreshing a report; a test fails when it drifts from the reports.

Results for the five container corpus repositories, with Renovate 44.164 run with a read-only GitHub token on 2026-10-23 (reports in [`benchmarks/differential/reports/`](../../benchmarks/differential/reports/), trimmed Renovate output in `tests/fixtures/differential/`):

| Repository | Agree | Offing-only | Renovate-only | Inconclusive |
| --- | --- | --- | --- | --- |
| outline/outline | 22 | 5 | 13 | 0 |
| excalidraw/excalidraw | 23 | 2 | 2 | 0 |
| mealie-recipes/mealie | 17 | 0 | 4 | 0 |
| umami-software/umami | 8 | 1 | 0 | 0 |
| gethomepage/homepage | 0 | 0 | 0 | 0 |

What it shows:

- **Agreements** are 10 base images, 53 GitHub Action findings, and 7 npm deprecations. Where Offing calls `node` or `postgres` end-of-life, or flags `actions/checkout` on Node 20, Renovate offers a newer major version. Renovate does not say the old line is unsupported; only Offing does.
- **No comparison is inconclusive.** With a token Renovate looks up every GitHub Action, so the Action findings that were `inconclusive` in the 2026-10-16 run are now comparisons, and all of them agree.
- **Renovate-only** are npm deprecations Offing has no rule for (for example `@types/diff`, `@types/glob`, `@nuxt/types`, `react-waypoint`). This is the real gap: the `npm-deprecated` importer only checks a candidate list, so these names are candidates to add. Each is a Renovate observation, not evidence; the importer still requires the registry's own deprecation notice.
- **Offing-only** is not a real disagreement yet. All eight entries are packages Renovate does list, under a different spelling: the comparison reads the package name from the rule id, so `@types/dotenv` becomes `types.dotenv` and `next` with a version-line rule becomes `next.14`. Six of the Renovate-only `@types/*` entries are the same packages seen from the other side. Matching by the rule's package name is a follow-up to this comparison.

## Differential testing against xeol

[xeol](https://github.com/xeol-io/xeol) reports release cycles of products (runtimes, databases, npm packages) that endoflife.date lists as past end of life, for versions it finds in lockfiles and image filesystems. A maintainer runs it (it downloads an EOL database; it is not part of `npm run check` or any scan):

```bash
xeol dir:<checkout> -o json > xeol.json
npm run differential:xeol -- --xeol xeol.json --repository <checkout> --name owner/repo --out report.json
```

The report compares by product, not by file: xeol names the lockfile that resolved a version, Offing names the manifest that declares it. Offing runtime, container image, and npm package findings are compared with the xeol product of the same name (`node` images with `nodejs`, `golang` with `go`, `postgres` with `postgresql`). Outcomes: `agree` (both report the product), `offing-only`, and `xeol-only`. GitHub Actions, CI images, and the other families xeol has no product for are listed as not comparable.

Results for the five repositories of the Renovate comparison, with xeol 0.10.8 run with `dir:` on the pinned checkouts on 2026-10-23 (reports in [`benchmarks/differential/reports/xeol/`](../../benchmarks/differential/reports/xeol/), trimmed xeol output in `tests/fixtures/xeol/`):

| Repository | Agree | Offing-only | xeol-only |
| --- | --- | --- | --- |
| excalidraw/excalidraw | 0 | 3 | 0 |
| gethomepage/homepage | 0 | 0 | 0 |
| mealie-recipes/mealie | 0 | 2 | 2 |
| outline/outline | 0 | 11 | 0 |
| umami-software/umami | 1 | 4 | 1 |

What the numbers say:

- **Agreement is rare because the tools read different files.** `xeol dir:` resolves versions from lockfiles; it does not read Dockerfiles, workflow files, `.nvmrc`, or `engines`. Every Offing runtime and image finding here is therefore Offing-only, and not a sign that xeol disagrees. Where both read the same dependency, they agree: both call `next` 13 end of life in umami.
- **xeol-only** are npm packages whose release line endoflife.date lists as ended (`vue` 2.6 and 3.2, `vuetify` 2). Offing has no rule for them; each is a candidate for the `npm-support-end` importer, not evidence by itself.
- **Not compared:** GitHub Actions findings, which are the largest Offing family in these repositories and which xeol does not model.
## Differential testing against Pluto

[Pluto](https://github.com/FairwindsOps/pluto) reads `apiVersion` and `kind` from manifests and says whether the Kubernetes project still serves them, which is the question the `kubernetes` detector answers. A maintainer runs it (it is not part of `npm run check` or any scan). Run it from inside the checkout, because Pluto joins `--directory` to the working directory:

```bash
(cd <checkout> && pluto detect-files -d . -o json -t k8s=v1.36.0 > pluto.json)
npm run differential:pluto -- --pluto pluto.json --repository <checkout> --name owner/repo --out report.json
```

Findings are compared by file, kind, API group, and version. Outcomes: `agree` (Pluto reports the version as removed at the target version), `offing-only`, `pluto-only`, and `pluto-deprecated-only` (deprecated but still served; Offing judges only removed versions, so this is not a disagreement). Non-Kubernetes findings are listed as not comparable.

Results for the seventeen Kubernetes corpus repositories, with Pluto 5.24.4 at target `k8s=v1.36.0` on the pinned checkouts on 2026-10-23 (reports in [`benchmarks/differential/reports/pluto/`](../../benchmarks/differential/reports/pluto/), trimmed Pluto output in `tests/fixtures/pluto/`; repositories with no Kubernetes finding from either tool are left out of the table):

| Repository | Agree | Offing-only | Pluto-only | Pluto deprecated-only |
| --- | --- | --- | --- | --- |
| FairwindsOps/pluto | 1 | 1 | 3 | 0 |
| doitintl/kube-no-trouble | 0 | 0 | 38 | 1 |
| hasura/skor | 0 | 0 | 1 | 0 |
| kelseyhightower/ingress-with-static-ip | 1 | 0 | 0 | 0 |
| kelseyhightower/kubernetes-cluster-federation | 5 | 0 | 0 | 0 |
| knrt10/kubernetes-basicLearning | 1 | 0 | 0 | 0 |
| kubernetes/examples | 10 | 0 | 0 | 0 |
| luksa/kubernetes-in-action | 27 | 0 | 0 | 0 |
| lusyoe/springboot-k8s-example | 1 | 1 | 0 | 0 |
| motiv-labs/janus | 0 | 2 | 0 | 0 |
| ossf/package-analysis | 1 | 0 | 0 | 0 |
| unixhot/salt-kubebin | 15 | 0 | 0 | 0 |
| **Total** | **62** | **4** | **42** | **1** |

Every difference has one of three causes, none of them a wrong finding:

- **Offing-only** are Helm templates (`charts/templates/ingress.yaml`, `janus/templates/*.yaml`, a test chart). Pluto cannot parse files with template actions and skips them; Offing reads the `apiVersion` and `kind` lines of a template. This is Offing finding more.
- **Pluto-only** are `kind: List` items (`hasura/skor`, one Pluto test asset), JSON manifests, and files under `fixtures/` and `testdata/` directories (`doitintl/kube-no-trouble` has 38, `FairwindsOps/pluto` three). The detector page lists these as not judged. Pluto finding more here is the known cost of Offing's conservative scope, and the same forms are why the blind repositories were rechecked by hand.
- **Disagreement on a version Offing does judge** is zero: all 62 manifests that both tools read agree on removed.

---

Source: https://velella.sh/offing/state-of-eol/

# State of EOL

A citable summary of lifecycle risk in Offing's public benchmark corpus: every expected finding at a pinned commit, aggregated by product and release line. The tables below regenerate from the corpus and the last recorded full run; they are a census of that corpus, not a sample of the open-source world.

## Findings

<!-- state-of-eol:start -->
Measured on the public corpus of 1618 pinned repositories (10482 expected findings). The last full corpus run was commit `dcc9f320` on 2026-11-06 (557 repositories, precision 1, recall 1). Method: [Validation](VALIDATION.md). Corpus: [`benchmarks/public-repositories/`](../benchmarks/public-repositories/). Regenerate with `npm run build:coverage` after `npm run record:corpus-run`.

| Measure | Value |
| --- | ---: |
| Repositories | 1618 |
| Expected findings | 10482 |
| Products with findings | 170 |
| Release lines with findings | 246 |

### By product

| Product | Findings | Release lines | Repositories |
| --- | ---: | ---: | ---: |
| actions/checkout | 2154 | 1 | 584 |
| dockerfile | 965 | 2 | 72 |
| nodejs | 805 | 8 | 209 |
| dotnet | 587 | 10 | 65 |
| terraform | 489 | 4 | 17 |
| actions/upload-artifact | 482 | 1 | 169 |
| actions/setup-node | 308 | 1 | 123 |
| actions/setup-python | 288 | 1 | 119 |
| ruby | 279 | 11 | 71 |
| cmake | 276 | 2 | 30 |
| actions/cache | 275 | 1 | 100 |
| python | 221 | 2 | 140 |
| actions/download-artifact | 189 | 1 | 90 |
| actions/setup-java | 160 | 1 | 70 |
| golang | 156 | 6 | 70 |
| dart | 140 | 3 | 32 |
| library/node | 107 | 2 | 49 |
| powershell | 105 | 5 | 31 |
| softprops/action-gh-release | 105 | 1 | 71 |
| docker/build-push-action | 103 | 1 | 52 |
| docker/login-action | 102 | 1 | 61 |
| library/ubuntu | 99 | 2 | 43 |
| github-actions/set-output | 87 | 1 | 30 |
| android/targetSdk | 80 | 1 | 38 |
| actions/setup-go | 78 | 1 | 25 |
| docker/setup-buildx-action | 77 | 1 | 45 |
| aws-lambda-runtime/nodejs24.x | 74 | 1 | 1 |
| java | 73 | 4 | 22 |
| rust | 65 | 1 | 59 |
| library/python | 60 | 2 | 38 |
| erlang | 58 | 2 | 33 |
| library/alpine | 56 | 1 | 23 |
| xcode | 52 | 2 | 52 |
| sbt | 47 | 1 | 41 |
| actions/github-script | 46 | 1 | 23 |
| azure-pipelines/ubuntu-image | 45 | 2 | 23 |
| docker/setup-qemu-action | 40 | 1 | 29 |
| library/golang | 40 | 1 | 21 |
| deno | 36 | 1 | 35 |
| bun | 35 | 2 | 34 |
| docker/metadata-action | 35 | 1 | 24 |
| library/debian | 34 | 1 | 17 |
| scala | 30 | 2 | 27 |
| elixir | 28 | 2 | 27 |
| kubernetes/extensions/Deployment | 28 | 1 | 9 |
| babel-eslint | 27 | 1 | 26 |
| actions/deploy-pages | 26 | 1 | 26 |
| actions/setup-dotnet | 26 | 1 | 12 |
| atty | 24 | 1 | 23 |
| node-sass | 24 | 2 | 12 |
| php | 24 | 2 | 17 |
| ios | 23 | 1 | 8 |
| aws-lambda-runtime/nodejs14.x | 22 | 1 | 14 |
| library/postgres | 22 | 2 | 15 |
| aws-lambda-runtime/python3.14 | 21 | 1 | 1 |
| next | 21 | 4 | 10 |
| astral-sh/setup-uv | 20 | 1 | 11 |
| kubernetes/extensions/Ingress | 20 | 1 | 14 |
| actions/create-github-app-token | 19 | 1 | 4 |
| postgresql | 18 | 5 | 14 |
| actions/stale | 17 | 1 | 16 |
| @angular/core | 16 | 3 | 5 |
| aws-lambda-runtime/python3.8 | 16 | 1 | 6 |
| azure-pipelines/windows-image | 16 | 1 | 8 |
| library/ruby | 16 | 2 | 10 |
| tempdir | 16 | 1 | 12 |
| kubernetes/rbac.authorization.k8s.io/ClusterRoleBinding | 15 | 1 | 7 |
| swiftmailer/swiftmailer | 15 | 1 | 14 |
| ansi_term | 14 | 1 | 14 |
| doctrine/cache | 14 | 1 | 12 |
| fzaninotto/faker | 14 | 1 | 8 |
| kubernetes/batch/CronJob | 14 | 1 | 6 |
| rails | 14 | 1 | 1 |
| aws-lambda-runtime/provided.al2023 | 12 | 1 | 3 |
| failure | 12 | 1 | 6 |
| helm-repository/stable | 11 | 1 | 4 |
| kubernetes/policy/PodDisruptionBudget | 11 | 1 | 4 |
| actions/configure-pages | 10 | 1 | 10 |
| github.com/golang/protobuf | 10 | 1 | 4 |
| kubernetes/apps/Deployment | 10 | 2 | 3 |
| vue | 10 | 1 | 10 |
| aws-lambda-runtime/nodejs12.x | 9 | 1 | 3 |
| babel-preset-es2015 | 9 | 1 | 9 |
| com.android.billingclient/billing | 9 | 5 | 7 |
| kubernetes/rbac.authorization.k8s.io/ClusterRole | 9 | 1 | 4 |
| kubernetes/storage.k8s.io/StorageClass | 9 | 1 | 3 |
| mysql | 9 | 1 | 6 |
| aws-lambda-runtime/ruby4.0 | 8 | 1 | 1 |
| kubernetes/extensions/DaemonSet | 8 | 1 | 4 |
| kubernetes/policy/PodSecurityPolicy | 8 | 1 | 2 |
| library/redis | 8 | 2 | 4 |
| aws-lambda-runtime/nodejs20.x | 7 | 1 | 6 |
| aws-lambda-runtime/nodejs22.x | 7 | 1 | 3 |
| kubernetes/apiextensions.k8s.io/CustomResourceDefinition | 7 | 1 | 4 |
| kubernetes/autoscaling/HorizontalPodAutoscaler | 6 | 2 | 5 |
| react-native | 6 | 1 | 4 |
| kubernetes/extensions/PodSecurityPolicy | 5 | 1 | 1 |
| kubernetes/rbac.authorization.k8s.io/RoleBinding | 5 | 1 | 3 |
| rollup-plugin-terser | 5 | 1 | 5 |
| django | 4 | 2 | 4 |
| istanbul | 4 | 1 | 4 |
| library/mysql | 4 | 1 | 4 |
| request | 4 | 1 | 4 |
| tslint | 4 | 1 | 4 |
| WindowsAzure.Storage | 4 | 1 | 4 |
| actions/first-interaction | 3 | 1 | 3 |
| actions/labeler | 3 | 1 | 3 |
| aws-lambda-runtime/nodejs16.x | 3 | 1 | 2 |
| aws-lambda-runtime/provided.al2 | 3 | 1 | 2 |
| azure-pipelines/macos-image | 3 | 1 | 3 |
| github-actions/set-env | 3 | 1 | 2 |
| hashicorp/setup-terraform | 3 | 1 | 3 |
| kubernetes/extensions/ReplicaSet | 3 | 1 | 2 |
| kubernetes/networking.k8s.io/Ingress | 3 | 1 | 3 |
| kubernetes/rbac.authorization.k8s.io/Role | 3 | 1 | 3 |
| popper.js | 3 | 1 | 3 |
| redis | 3 | 1 | 3 |
| rollup-plugin-babel | 3 | 1 | 3 |
| aws-lambda-runtime/python3.7 | 2 | 1 | 1 |
| crypto-js | 2 | 1 | 2 |
| github-actions/add-path | 2 | 1 | 1 |
| karma-phantomjs-launcher | 2 | 1 | 2 |
| kubernetes/apiregistration.k8s.io/APIService | 2 | 1 | 1 |
| kubernetes/apps/DaemonSet | 2 | 1 | 2 |
| kubernetes/apps/ReplicaSet | 2 | 1 | 1 |
| kubernetes/apps/StatefulSet | 2 | 1 | 2 |
| laravel/framework | 2 | 1 | 1 |
| protractor | 2 | 1 | 2 |
| pycrypto | 2 | 1 | 2 |
| request-promise | 2 | 1 | 2 |
| sensiolabs/security-checker | 2 | 1 | 1 |
| uglify-es | 2 | 1 | 2 |
| @types/dotenv | 1 | 1 | 1 |
| @types/emoji-regex | 1 | 1 | 1 |
| @types/form-data | 1 | 1 | 1 |
| @types/koa-useragent | 1 | 1 | 1 |
| @types/sanitize-filename | 1 | 1 | 1 |
| @types/socket.io-client | 1 | 1 | 1 |
| amazon-eks | 1 | 1 | 1 |
| aws-lambda-runtime/dotnet10 | 1 | 1 | 1 |
| aws-lambda-runtime/go1.x | 1 | 1 | 1 |
| aws-lambda-runtime/java25 | 1 | 1 | 1 |
| aws-lambda-runtime/nodejs10.x | 1 | 1 | 1 |
| aws-lambda-runtime/nodejs18.x | 1 | 1 | 1 |
| aws-lambda-runtime/python3.13 | 1 | 1 | 1 |
| aws-lambda-runtime/ruby2.7 | 1 | 1 | 1 |
| azure-app-service/node | 1 | 1 | 1 |
| cloud.google.com/go/pubsub | 1 | 1 | 1 |
| domexception | 1 | 1 | 1 |
| google-cloud-functions-runtime/nodejs14 | 1 | 1 | 1 |
| google-cloud-functions-runtime/nodejs20 | 1 | 1 | 1 |
| google-cloud-functions-runtime/python37 | 1 | 1 | 1 |
| google-cloud-sql-mysql | 1 | 1 | 1 |
| gulp-util | 1 | 1 | 1 |
| helm-repository/incubator | 1 | 1 | 1 |
| i18next-parser | 1 | 1 | 1 |
| koa-router | 1 | 1 | 1 |
| kubernetes/admissionregistration.k8s.io/MutatingWebhookConfiguration | 1 | 1 | 1 |
| kubernetes/admissionregistration.k8s.io/ValidatingWebhookConfiguration | 1 | 1 | 1 |
| library/zookeeper | 1 | 1 | 1 |
| lodash.isequal | 1 | 1 | 1 |
| mysql/mysql-connector-java | 1 | 1 | 1 |
| natives | 1 | 1 | 1 |
| nose | 1 | 1 | 1 |
| pytest-runner | 1 | 1 | 1 |
| q | 1 | 1 | 1 |
| react-beautiful-dnd | 1 | 1 | 1 |
| socket.io-redis | 1 | 1 | 1 |
| typing | 1 | 1 | 1 |
| zendframework/zend-stdlib | 1 | 1 | 1 |

### By product and release line

| Product | Release line | Rule | Event | Findings | Repositories |
| --- | --- | --- | --- | ---: | ---: |
| actions/checkout | Unsupported actions/checkout runtime | [`github-actions.checkout.node20`](rules/github-actions.checkout.node20.html) | end-of-support | 2154 | 584 |
| dockerfile | The Dockerfile legacy "ENV key value" form is deprecated | [`container.dockerfile.legacy-env-format`](rules/container.dockerfile.legacy-env-format.html) | deprecated | 930 | 63 |
| actions/upload-artifact | Retired actions/upload-artifact release | [`github-actions.upload-artifact.retired`](rules/github-actions.upload-artifact.retired.html) | removed | 482 | 169 |
| terraform | Interpolation-only strings are deprecated | [`terraform.syntax.interpolation-only`](rules/terraform.syntax.interpolation-only.html) | deprecated | 409 | 12 |
| actions/setup-node | Unsupported actions/setup-node runtime | [`github-actions.setup-node.node20`](rules/github-actions.setup-node.node20.html) | end-of-support | 308 | 123 |
| actions/setup-python | Unsupported actions/setup-python runtime | [`github-actions.setup-python.node20`](rules/github-actions.setup-python.node20.html) | end-of-support | 288 | 119 |
| actions/cache | Unsupported actions/cache runtime | [`github-actions.cache.node20`](rules/github-actions.cache.node20.html) | end-of-support | 275 | 100 |
| cmake | CMake policy versions older than 3.5 are removed | [`cpp.cmake.policy-below-3.5.removed`](rules/cpp.cmake.policy-below-3.5.removed.html) | removed | 260 | 29 |
| nodejs | Node.js 20 is end-of-life | [`nodejs.runtime.eol-20`](rules/nodejs.runtime.eol-20.html) | end-of-life | 232 | 115 |
| dotnet | .NET 8 is no longer supported | [`dotnet.runtime.end-of-support-8.0`](rules/dotnet.runtime.end-of-support-8.0.html) | end-of-support | 203 | 27 |
| nodejs | Node.js 22 reaches end-of-life on 2027-04-30 | [`nodejs.runtime.eol-22`](rules/nodejs.runtime.eol-22.html) | scheduled-end-of-life | 197 | 85 |
| actions/download-artifact | Retired actions/download-artifact release | [`github-actions.download-artifact.retired`](rules/github-actions.download-artifact.retired.html) | removed | 189 | 90 |
| python | Python 3.9 and older are end-of-life | [`python.runtime.eol-3.9-and-older`](rules/python.runtime.eol-3.9-and-older.html) | end-of-life | 162 | 111 |
| actions/setup-java | Unsupported actions/setup-java runtime | [`github-actions.setup-java.node20`](rules/github-actions.setup-java.node20.html) | end-of-support | 160 | 70 |
| nodejs | Legacy Node.js runtime is end-of-life | [`nodejs.runtime.legacy`](rules/nodejs.runtime.legacy.html) | end-of-life | 138 | 76 |
| dart | Dart 2 and older no longer receive security updates | [`dart.sdk.end-of-support-2-and-older`](rules/dart.sdk.end-of-support-2-and-older.html) | end-of-support | 131 | 27 |
| nodejs | Node.js 18 is end-of-life | [`nodejs.runtime.eol-18`](rules/nodejs.runtime.eol-18.html) | end-of-life | 131 | 84 |
| ruby | Ruby 2.7 is end-of-life | [`ruby.runtime.eol-2.7`](rules/ruby.runtime.eol-2.7.html) | end-of-life | 109 | 24 |
| softprops/action-gh-release | Unsupported softprops/action-gh-release runtime | [`github-actions.action-gh-release.node20`](rules/github-actions.action-gh-release.node20.html) | end-of-support | 105 | 71 |
| docker/build-push-action | Unsupported docker/build-push-action runtime | [`github-actions.build-push-action.node20`](rules/github-actions.build-push-action.node20.html) | end-of-support | 103 | 52 |
| docker/login-action | Unsupported docker/login-action runtime | [`github-actions.login-action.node20`](rules/github-actions.login-action.node20.html) | end-of-support | 102 | 61 |
| nodejs | Node.js 19 is end-of-life | [`nodejs.runtime.eol-19`](rules/nodejs.runtime.eol-19.html) | end-of-life | 88 | 65 |
| github-actions/set-output | Deprecated GitHub Actions ::set-output command | [`github-actions.workflow-command.set-output`](rules/github-actions.workflow-command.set-output.html) | deprecated | 87 | 30 |
| library/node | Node.js image release lines 21 and older are end-of-life | [`container.node.eol-21-and-older`](rules/container.node.eol-21-and-older.html) | end-of-life | 87 | 38 |
| ruby | Ruby 3.2 is end-of-life | [`ruby.runtime.eol-3.2`](rules/ruby.runtime.eol-3.2.html) | end-of-life | 83 | 18 |
| android/targetSdk | Google Play requires targetSdk 35+ for existing phone and tablet apps | [`android.target-sdk.existing.default-below-35`](rules/android.target-sdk.existing.default-below-35.html) | end-of-support | 80 | 38 |
| actions/setup-go | Unsupported actions/setup-go runtime | [`github-actions.setup-go.node20`](rules/github-actions.setup-go.node20.html) | end-of-support | 78 | 25 |
| docker/setup-buildx-action | Unsupported docker/setup-buildx-action runtime | [`github-actions.setup-buildx-action.node20`](rules/github-actions.setup-buildx-action.node20.html) | end-of-support | 77 | 45 |
| golang | Go 1.20 and older are no longer supported | [`go.runtime.end-of-support-1.20-and-older`](rules/go.runtime.end-of-support-1.20-and-older.html) | end-of-support | 76 | 44 |
| aws-lambda-runtime/nodejs24.x | AWS Lambda Node.js 24 runtime reaches end of life on 2028-04-30 | [`serverless.aws-lambda.nodejs24.x`](rules/serverless.aws-lambda.nodejs24.x.html) | scheduled-end-of-life | 74 | 1 |
| dotnet | .NET 7 is no longer supported | [`dotnet.runtime.end-of-support-7.0`](rules/dotnet.runtime.end-of-support-7.0.html) | end-of-support | 74 | 11 |
| library/ubuntu | Ubuntu image release lines 20.04 and older are past standard support end-of-life | [`container.ubuntu.eol-20.04-and-older`](rules/container.ubuntu.eol-20.04-and-older.html) | end-of-life | 74 | 33 |
| terraform | The list() and map() functions were removed in Terraform 0.15 | [`terraform.function.list-map`](rules/terraform.function.list-map.html) | removed | 73 | 1 |
| dotnet | .NET 9 is no longer supported | [`dotnet.runtime.end-of-support-9.0`](rules/dotnet.runtime.end-of-support-9.0.html) | end-of-support | 72 | 8 |
| dotnet | .NET Core 3.1 is no longer supported | [`dotnet.runtime.end-of-support-3.1`](rules/dotnet.runtime.end-of-support-3.1.html) | end-of-support | 65 | 17 |
| rust | Rust 1.98 and older are no longer supported | [`rust.toolchain.end-of-support-1.98-and-older`](rules/rust.toolchain.end-of-support-1.98-and-older.html) | end-of-support | 65 | 59 |
| python | Python 3.10 and older are end-of-life | [`python.runtime.eol-3.10-and-older`](rules/python.runtime.eol-3.10-and-older.html) | end-of-life | 59 | 47 |
| library/alpine | Alpine Linux image release lines 3.20 and older are end-of-life | [`container.alpine.eol-3.20-and-older`](rules/container.alpine.eol-3.20-and-older.html) | end-of-life | 56 | 23 |
| powershell | PowerShell 7.0 (LTS) is no longer supported | [`shell.powershell.end-of-life-7.0`](rules/shell.powershell.end-of-life-7.0.html) | end-of-life | 53 | 11 |
| library/python | Python image release lines 3.10 and older are end-of-life | [`container.python.eol-3.10-and-older`](rules/container.python.eol-3.10-and-older.html) | end-of-life | 52 | 33 |
| dotnet | .NET Core 2.0 is no longer supported | [`dotnet.runtime.end-of-support-2.0`](rules/dotnet.runtime.end-of-support-2.0.html) | end-of-support | 50 | 4 |
| dotnet | .NET 5 is no longer supported | [`dotnet.runtime.end-of-support-5.0`](rules/dotnet.runtime.end-of-support-5.0.html) | end-of-support | 50 | 14 |
| dotnet | .NET 6 is no longer supported | [`dotnet.runtime.end-of-support-6.0`](rules/dotnet.runtime.end-of-support-6.0.html) | end-of-support | 50 | 16 |
| sbt | sbt 0.13 reached end of life | [`scala.sbt.eol-0.13`](rules/scala.sbt.eol-0.13.html) | end-of-life | 47 | 41 |
| actions/github-script | Unsupported actions/github-script runtime | [`github-actions.github-script.node20`](rules/github-actions.github-script.node20.html) | end-of-support | 46 | 23 |
| docker/setup-qemu-action | Unsupported docker/setup-qemu-action runtime | [`github-actions.setup-qemu-action.node20`](rules/github-actions.setup-qemu-action.node20.html) | end-of-support | 40 | 29 |
| library/golang | Go image release lines 1.25 and older are end-of-life | [`container.golang.eol-1.25-and-older`](rules/container.golang.eol-1.25-and-older.html) | end-of-life | 40 | 21 |
| deno | Deno 1.x is end-of-life | [`deno.runtime.eol-1.x`](rules/deno.runtime.eol-1.x.html) | end-of-life | 36 | 35 |
| docker/metadata-action | Unsupported docker/metadata-action runtime | [`github-actions.metadata-action.node20`](rules/github-actions.metadata-action.node20.html) | end-of-support | 35 | 24 |
| dockerfile | The Dockerfile MAINTAINER instruction is deprecated | [`container.dockerfile.maintainer`](rules/container.dockerfile.maintainer.html) | deprecated | 35 | 17 |
| java | Java 18 to 20 are no longer supported | [`java.jdk.end-of-support-18-20`](rules/java.jdk.end-of-support-18-20.html) | end-of-support | 35 | 9 |
| library/debian | Debian image release lines 11 and older are end-of-life | [`container.debian.eol-11-and-older`](rules/container.debian.eol-11-and-older.html) | end-of-life | 34 | 17 |
| bun | Bun 1.0.x is end-of-life | [`deno.bun.runtime.eol-1.0`](rules/deno.bun.runtime.eol-1.0.html) | end-of-life | 33 | 33 |
| java | Java 12 to 16 are no longer supported | [`java.jdk.end-of-support-12-16`](rules/java.jdk.end-of-support-12-16.html) | end-of-support | 32 | 8 |
| erlang | Erlang/OTP 26 no longer receives security updates | [`elixir.erlang.eol-26`](rules/elixir.erlang.eol-26.html) | end-of-life | 31 | 17 |
| golang | Go 1.24 is no longer supported | [`go.runtime.end-of-support-1.24`](rules/go.runtime.end-of-support-1.24.html) | end-of-support | 30 | 9 |
| powershell | PowerShell 7.2 (LTS) is no longer supported | [`shell.powershell.end-of-life-7.2`](rules/shell.powershell.end-of-life-7.2.html) | end-of-life | 30 | 10 |
| ruby | Ruby 3.1 is end-of-life | [`ruby.runtime.eol-3.1`](rules/ruby.runtime.eol-3.1.html) | end-of-life | 30 | 13 |
| xcode | Xcode 15 through 25 are not accepted for App Store uploads | [`swift.xcode.app-store-15-through-25`](rules/swift.xcode.app-store-15-through-25.html) | end-of-support | 29 | 29 |
| kubernetes/extensions/Deployment | Deployment extensions/v1beta1 is no longer served | [`kubernetes.extensions.deployment.v1beta1.removed`](rules/kubernetes.extensions.deployment.v1beta1.removed.html) | removed | 28 | 9 |
| scala | Scala 2.11 reached end of life | [`scala.runtime.eol-2.11`](rules/scala.runtime.eol-2.11.html) | end-of-life | 28 | 25 |
| babel-eslint | babel-eslint is deprecated | [`npm.package.babel-eslint.deprecated`](rules/npm.package.babel-eslint.deprecated.html) | deprecated | 27 | 26 |
| erlang | Erlang/OTP 25 no longer receives security updates | [`elixir.erlang.eol-25`](rules/elixir.erlang.eol-25.html) | end-of-life | 27 | 17 |
| actions/deploy-pages | Unsupported actions/deploy-pages runtime | [`github-actions.deploy-pages.node20`](rules/github-actions.deploy-pages.node20.html) | end-of-support | 26 | 26 |
| actions/setup-dotnet | Unsupported actions/setup-dotnet runtime | [`github-actions.setup-dotnet.node20`](rules/github-actions.setup-dotnet.node20.html) | end-of-support | 26 | 12 |
| azure-pipelines/ubuntu-image | Azure Pipelines Ubuntu 20.04 hosted image is retired | [`ci-images.azure-pipelines.ubuntu-20.04`](rules/ci-images.azure-pipelines.ubuntu-20.04.html) | removed | 26 | 15 |
| library/ubuntu | Ubuntu image release line 22.04 reaches standard support end-of-life on 2027-06-01 | [`container.ubuntu.eol-22.04`](rules/container.ubuntu.eol-22.04.html) | scheduled-end-of-life | 25 | 12 |
| atty | atty is no longer maintained | [`rust.crate.atty.unmaintained`](rules/rust.crate.atty.unmaintained.html) | deprecated | 24 | 23 |
| ios | iOS and iPadOS app targets below iOS 13 are not accepted for App Store uploads | [`swift.app-store.ios-below-13`](rules/swift.app-store.ios-below-13.html) | end-of-support | 23 | 8 |
| php | PHP 7.4 is end-of-life | [`php.runtime.eol-7.4`](rules/php.runtime.eol-7.4.html) | end-of-life | 23 | 16 |
| xcode | Xcode older than 15 is not accepted for App Store uploads | [`swift.xcode.app-store-below-15`](rules/swift.xcode.app-store-below-15.html) | end-of-support | 23 | 23 |
| aws-lambda-runtime/nodejs14.x | AWS Lambda Node.js 14 runtime is end-of-life | [`serverless.aws-lambda.nodejs14.x`](rules/serverless.aws-lambda.nodejs14.x.html) | end-of-life | 22 | 14 |
| aws-lambda-runtime/python3.14 | AWS Lambda Python 3.14 runtime reaches end of life on 2029-06-30 | [`serverless.aws-lambda.python3.14`](rules/serverless.aws-lambda.python3.14.html) | scheduled-end-of-life | 21 | 1 |
| astral-sh/setup-uv | Unsupported astral-sh/setup-uv runtime | [`github-actions.setup-uv.node20`](rules/github-actions.setup-uv.node20.html) | end-of-support | 20 | 11 |
| kubernetes/extensions/Ingress | Ingress extensions/v1beta1 is no longer served | [`kubernetes.extensions.ingress.v1beta1.removed`](rules/kubernetes.extensions.ingress.v1beta1.removed.html) | removed | 20 | 14 |
| library/node | Node.js image release line 22 reaches end-of-life on 2027-04-30 | [`container.node.eol-22-and-older`](rules/container.node.eol-22-and-older.html) | scheduled-end-of-life | 20 | 12 |
| actions/create-github-app-token | Unsupported actions/create-github-app-token runtime | [`github-actions.create-github-app-token.node20`](rules/github-actions.create-github-app-token.node20.html) | end-of-support | 19 | 4 |
| azure-pipelines/ubuntu-image | Azure Pipelines Ubuntu 22.04 hosted image is scheduled for removal | [`ci-images.azure-pipelines.ubuntu-22.04`](rules/ci-images.azure-pipelines.ubuntu-22.04.html) | scheduled-end-of-life | 19 | 10 |
| golang | Go 1.25 is no longer supported | [`go.runtime.end-of-support-1.25`](rules/go.runtime.end-of-support-1.25.html) | end-of-support | 19 | 12 |
| library/postgres | PostgreSQL image major versions 13 and older are end-of-life | [`container.postgres.eol-13-and-older`](rules/container.postgres.eol-13-and-older.html) | end-of-life | 18 | 13 |
| actions/stale | Unsupported actions/stale runtime | [`github-actions.stale.node20`](rules/github-actions.stale.node20.html) | end-of-support | 17 | 16 |
| powershell | PowerShell 6.x is no longer supported | [`shell.powershell.end-of-life-6`](rules/shell.powershell.end-of-life-6.html) | end-of-life | 17 | 9 |
| aws-lambda-runtime/python3.8 | AWS Lambda Python 3.8 runtime is end-of-life | [`serverless.aws-lambda.python3.8`](rules/serverless.aws-lambda.python3.8.html) | end-of-life | 16 | 6 |
| azure-pipelines/windows-image | Azure Pipelines Windows Server 2019 hosted image is retired | [`ci-images.azure-pipelines.windows-2019`](rules/ci-images.azure-pipelines.windows-2019.html) | removed | 16 | 8 |
| cmake | CMake policy versions older than 3.10 are deprecated | [`cpp.cmake.policy-below-3.10.deprecated`](rules/cpp.cmake.policy-below-3.10.deprecated.html) | deprecated | 16 | 5 |
| tempdir | tempdir is no longer maintained | [`rust.crate.tempdir.unmaintained`](rules/rust.crate.tempdir.unmaintained.html) | deprecated | 16 | 12 |
| elixir | Elixir 1.15 no longer receives security updates | [`elixir.runtime.eol-1.15`](rules/elixir.runtime.eol-1.15.html) | end-of-life | 15 | 15 |
| kubernetes/rbac.authorization.k8s.io/ClusterRoleBinding | ClusterRoleBinding rbac.authorization.k8s.io/v1beta1 is no longer served | [`kubernetes.rbac-authorization-k8s-io.clusterrolebinding.v1beta1.removed`](rules/kubernetes.rbac-authorization-k8s-io.clusterrolebinding.v1beta1.removed.html) | removed | 15 | 7 |
| library/ruby | Ruby image release lines 3.2 and older are end-of-life | [`container.ruby.eol-3.2-and-older`](rules/container.ruby.eol-3.2-and-older.html) | end-of-life | 15 | 10 |
| swiftmailer/swiftmailer | swiftmailer/swiftmailer is abandoned | [`php.package.swiftmailer.swiftmailer.abandoned`](rules/php.package.swiftmailer.swiftmailer.abandoned.html) | deprecated | 15 | 14 |
| ansi_term | ansi_term is no longer maintained | [`rust.crate.ansi-term.unmaintained`](rules/rust.crate.ansi-term.unmaintained.html) | deprecated | 14 | 14 |
| doctrine/cache | doctrine/cache is abandoned | [`php.package.doctrine.cache.abandoned`](rules/php.package.doctrine.cache.abandoned.html) | deprecated | 14 | 12 |
| dotnet | .NET Core 3.0 is no longer supported | [`dotnet.runtime.end-of-support-3.0`](rules/dotnet.runtime.end-of-support-3.0.html) | end-of-support | 14 | 6 |
| fzaninotto/faker | fzaninotto/faker is abandoned | [`php.package.fzaninotto.faker.abandoned`](rules/php.package.fzaninotto.faker.abandoned.html) | deprecated | 14 | 8 |
| kubernetes/batch/CronJob | CronJob batch/v1beta1 is no longer served | [`kubernetes.batch.cronjob.v1beta1.removed`](rules/kubernetes.batch.cronjob.v1beta1.removed.html) | removed | 14 | 6 |
| rails | Rails 8.0 security support is scheduled to end | [`ruby.gem.rails-8.0.scheduled-end-of-life`](rules/ruby.gem.rails-8.0.scheduled-end-of-life.html) | scheduled-end-of-life | 14 | 1 |
| ruby | Ruby 2.0.0 is end-of-life | [`ruby.runtime.eol-2.0.0`](rules/ruby.runtime.eol-2.0.0.html) | end-of-life | 14 | 2 |
| ruby | Ruby 2.6 is end-of-life | [`ruby.runtime.eol-2.6`](rules/ruby.runtime.eol-2.6.html) | end-of-life | 14 | 7 |
| elixir | Elixir 1.14 no longer receives security updates | [`elixir.runtime.eol-1.14`](rules/elixir.runtime.eol-1.14.html) | end-of-life | 13 | 13 |
| next | Next.js 15 is out of support | [`npm.package.next.15.support-end`](rules/npm.package.next.15.support-end.html) | end-of-support | 13 | 4 |
| @angular/core | @angular/core v20 reaches end of life on 2026-11-28 | [`npm.package.angular.core.v20.scheduled-end-of-life`](rules/npm.package.angular.core.v20.scheduled-end-of-life.html) | scheduled-end-of-life | 12 | 1 |
| aws-lambda-runtime/provided.al2023 | AWS Lambda OS-only runtime provided.al2023 runtime reaches end of life on 2029-06-30 | [`serverless.aws-lambda.provided.al2023`](rules/serverless.aws-lambda.provided.al2023.html) | scheduled-end-of-life | 12 | 3 |
| failure | failure is no longer maintained | [`rust.crate.failure.unmaintained`](rules/rust.crate.failure.unmaintained.html) | deprecated | 12 | 6 |
| golang | Go 1.22 is no longer supported | [`go.runtime.end-of-support-1.22`](rules/go.runtime.end-of-support-1.22.html) | end-of-support | 12 | 8 |
| node-sass | node-sass is deprecated | [`npm.package.node-sass.deprecated`](rules/npm.package.node-sass.deprecated.html) | deprecated | 12 | 12 |
| node-sass | Node Sass is end-of-life | [`npm.package.node-sass.eol`](rules/npm.package.node-sass.eol.html) | end-of-life | 12 | 12 |
| golang | Go 1.23 is no longer supported | [`go.runtime.end-of-support-1.23`](rules/go.runtime.end-of-support-1.23.html) | end-of-support | 11 | 6 |
| helm-repository/stable | Helm stable chart repository is end of life | [`kubernetes.helm.repository.stable.end-of-life`](rules/kubernetes.helm.repository.stable.end-of-life.html) | end-of-life | 11 | 4 |
| kubernetes/policy/PodDisruptionBudget | PodDisruptionBudget policy/v1beta1 is no longer served | [`kubernetes.policy.poddisruptionbudget.v1beta1.removed`](rules/kubernetes.policy.poddisruptionbudget.v1beta1.removed.html) | removed | 11 | 4 |
| actions/configure-pages | Unsupported actions/configure-pages runtime | [`github-actions.configure-pages.node20`](rules/github-actions.configure-pages.node20.html) | end-of-support | 10 | 10 |
| github.com/golang/protobuf | github.com/golang/protobuf is deprecated | [`go.module.github.com.golang.protobuf.deprecated`](rules/go.module.github.com.golang.protobuf.deprecated.html) | deprecated | 10 | 4 |
| ruby | Ruby 2.5 is end-of-life | [`ruby.runtime.eol-2.5`](rules/ruby.runtime.eol-2.5.html) | end-of-life | 10 | 6 |
| vue | Vue 2 is end-of-life | [`npm.package.vue.eol-2`](rules/npm.package.vue.eol-2.html) | end-of-life | 10 | 10 |
| aws-lambda-runtime/nodejs12.x | AWS Lambda Node.js 12 runtime is end-of-life | [`serverless.aws-lambda.nodejs12.x`](rules/serverless.aws-lambda.nodejs12.x.html) | end-of-life | 9 | 3 |
| babel-preset-es2015 | babel-preset-es2015 is deprecated | [`npm.package.babel-preset-es2015.deprecated`](rules/npm.package.babel-preset-es2015.deprecated.html) | deprecated | 9 | 9 |
| kubernetes/rbac.authorization.k8s.io/ClusterRole | ClusterRole rbac.authorization.k8s.io/v1beta1 is no longer served | [`kubernetes.rbac-authorization-k8s-io.clusterrole.v1beta1.removed`](rules/kubernetes.rbac-authorization-k8s-io.clusterrole.v1beta1.removed.html) | removed | 9 | 4 |
| kubernetes/storage.k8s.io/StorageClass | StorageClass storage.k8s.io/v1beta1 is no longer served | [`kubernetes.storage-k8s-io.storageclass.v1beta1.removed`](rules/kubernetes.storage-k8s-io.storageclass.v1beta1.removed.html) | removed | 9 | 3 |
| mysql | MySQL 5.7 is end-of-life | [`database.mysql.end-of-life-5.7`](rules/database.mysql.end-of-life-5.7.html) | end-of-life | 9 | 6 |
| ruby | Ruby 3.0 is end-of-life | [`ruby.runtime.eol-3.0`](rules/ruby.runtime.eol-3.0.html) | end-of-life | 9 | 8 |
| aws-lambda-runtime/ruby4.0 | AWS Lambda Ruby 4.0 runtime reaches end of life on 2029-03-31 | [`serverless.aws-lambda.ruby4.0`](rules/serverless.aws-lambda.ruby4.0.html) | scheduled-end-of-life | 8 | 1 |
| dart | Dart 3.8 no longer receives security updates | [`dart.sdk.end-of-support-3.8`](rules/dart.sdk.end-of-support-3.8.html) | end-of-support | 8 | 4 |
| golang | Go 1.21 is no longer supported | [`go.runtime.end-of-support-1.21`](rules/go.runtime.end-of-support-1.21.html) | end-of-support | 8 | 6 |
| kubernetes/apps/Deployment | Deployment apps/v1beta1 is no longer served | [`kubernetes.apps.deployment.v1beta1.removed`](rules/kubernetes.apps.deployment.v1beta1.removed.html) | removed | 8 | 2 |
| kubernetes/extensions/DaemonSet | DaemonSet extensions/v1beta1 is no longer served | [`kubernetes.extensions.daemonset.v1beta1.removed`](rules/kubernetes.extensions.daemonset.v1beta1.removed.html) | removed | 8 | 4 |
| kubernetes/policy/PodSecurityPolicy | PodSecurityPolicy policy/v1beta1 is no longer served | [`kubernetes.policy.podsecuritypolicy.v1beta1.removed`](rules/kubernetes.policy.podsecuritypolicy.v1beta1.removed.html) | removed | 8 | 2 |
| library/python | Python image release line 3.11 reaches end-of-life on 2027-10-31 | [`container.python.eol-3.11-and-older`](rules/container.python.eol-3.11-and-older.html) | scheduled-end-of-life | 8 | 5 |
| nodejs | Node.js 21 is end-of-life | [`nodejs.runtime.eol-21`](rules/nodejs.runtime.eol-21.html) | end-of-life | 8 | 2 |
| nodejs | Node.js 25 is end-of-life | [`nodejs.runtime.eol-25`](rules/nodejs.runtime.eol-25.html) | end-of-life | 8 | 4 |
| aws-lambda-runtime/nodejs20.x | AWS Lambda Node.js 20 runtime is end-of-life | [`serverless.aws-lambda.nodejs20.x`](rules/serverless.aws-lambda.nodejs20.x.html) | end-of-life | 7 | 6 |
| aws-lambda-runtime/nodejs22.x | AWS Lambda Node.js 22 runtime reaches end of life on 2027-04-30 | [`serverless.aws-lambda.nodejs22.x`](rules/serverless.aws-lambda.nodejs22.x.html) | scheduled-end-of-life | 7 | 3 |
| kubernetes/apiextensions.k8s.io/CustomResourceDefinition | CustomResourceDefinition apiextensions.k8s.io/v1beta1 is no longer served | [`kubernetes.apiextensions-k8s-io.customresourcedefinition.v1beta1.removed`](rules/kubernetes.apiextensions-k8s-io.customresourcedefinition.v1beta1.removed.html) | removed | 7 | 4 |
| library/redis | Redis image release lines 6.0 and older are end-of-life | [`container.redis.eol-6.0-and-older`](rules/container.redis.eol-6.0-and-older.html) | end-of-life | 7 | 3 |
| postgresql | PostgreSQL 13 is no longer a supported major version | [`database.postgresql.end-of-life-13`](rules/database.postgresql.end-of-life-13.html) | end-of-life | 7 | 7 |
| react-native | React Native 0.77 through 0.84 are unsupported | [`npm.package.react-native.0.77-to-0.84.end-of-support`](rules/npm.package.react-native.0.77-to-0.84.end-of-support.html) | end-of-support | 6 | 4 |
| ruby | Ruby 2.3 is end-of-life | [`ruby.runtime.eol-2.3`](rules/ruby.runtime.eol-2.3.html) | end-of-life | 6 | 3 |
| com.android.billingclient/billing | Google Play Billing Library 8 reaches its new-app and update deadline on 2027-08-31 | [`android.play-billing.version-8`](rules/android.play-billing.version-8.html) | scheduled-end-of-life | 5 | 3 |
| dotnet | .NET Core 2.1 is no longer supported | [`dotnet.runtime.end-of-support-2.1`](rules/dotnet.runtime.end-of-support-2.1.html) | end-of-support | 5 | 3 |
| kubernetes/extensions/PodSecurityPolicy | PodSecurityPolicy extensions/v1beta1 is no longer served | [`kubernetes.extensions.podsecuritypolicy.v1beta1.removed`](rules/kubernetes.extensions.podsecuritypolicy.v1beta1.removed.html) | removed | 5 | 1 |
| kubernetes/rbac.authorization.k8s.io/RoleBinding | RoleBinding rbac.authorization.k8s.io/v1beta1 is no longer served | [`kubernetes.rbac-authorization-k8s-io.rolebinding.v1beta1.removed`](rules/kubernetes.rbac-authorization-k8s-io.rolebinding.v1beta1.removed.html) | removed | 5 | 3 |
| next | Next.js 14 is out of support | [`npm.package.next.14.support-end`](rules/npm.package.next.14.support-end.html) | end-of-support | 5 | 4 |
| rollup-plugin-terser | rollup-plugin-terser is deprecated | [`npm.package.rollup-plugin-terser.deprecated`](rules/npm.package.rollup-plugin-terser.deprecated.html) | deprecated | 5 | 5 |
| dotnet | .NET Core 2.2 is no longer supported | [`dotnet.runtime.end-of-support-2.2`](rules/dotnet.runtime.end-of-support-2.2.html) | end-of-support | 4 | 2 |
| istanbul | istanbul is deprecated | [`npm.package.istanbul.deprecated`](rules/npm.package.istanbul.deprecated.html) | deprecated | 4 | 4 |
| java | Java 22 to 24 are no longer supported | [`java.jdk.end-of-support-22-24`](rules/java.jdk.end-of-support-22-24.html) | end-of-support | 4 | 4 |
| kubernetes/autoscaling/HorizontalPodAutoscaler | HorizontalPodAutoscaler autoscaling/v2beta2 is no longer served | [`kubernetes.autoscaling.horizontalpodautoscaler.v2beta2.removed`](rules/kubernetes.autoscaling.horizontalpodautoscaler.v2beta2.removed.html) | removed | 4 | 3 |
| library/mysql | MySQL image release lines 8.0 and older are past end-of-life | [`container.mysql.eol-8.0-and-older`](rules/container.mysql.eol-8.0-and-older.html) | end-of-life | 4 | 4 |
| library/postgres | PostgreSQL image release line 14 reaches end-of-life on 2026-11-12 | [`container.postgres.eol-14-and-older`](rules/container.postgres.eol-14-and-older.html) | scheduled-end-of-life | 4 | 4 |
| powershell | PowerShell 7.1 is no longer supported | [`shell.powershell.end-of-life-7.1`](rules/shell.powershell.end-of-life-7.1.html) | end-of-life | 4 | 3 |
| request | request is deprecated | [`npm.package.request.deprecated`](rules/npm.package.request.deprecated.html) | deprecated | 4 | 4 |
| terraform | Terraform CLI 1.13 is no longer a supported release line | [`terraform.cli.end-of-support-1.13`](rules/terraform.cli.end-of-support-1.13.html) | end-of-support | 4 | 3 |
| tslint | tslint is deprecated | [`npm.package.tslint.deprecated`](rules/npm.package.tslint.deprecated.html) | deprecated | 4 | 4 |
| WindowsAzure.Storage | WindowsAzure.Storage is deprecated on NuGet | [`dotnet.package.windowsazure-storage.deprecated`](rules/dotnet.package.windowsazure-storage.deprecated.html) | deprecated | 4 | 4 |
| actions/first-interaction | Unsupported actions/first-interaction runtime | [`github-actions.first-interaction.node20`](rules/github-actions.first-interaction.node20.html) | end-of-support | 3 | 3 |
| actions/labeler | Unsupported actions/labeler runtime | [`github-actions.labeler.node20`](rules/github-actions.labeler.node20.html) | end-of-support | 3 | 3 |
| aws-lambda-runtime/nodejs16.x | AWS Lambda Node.js 16 runtime is end-of-life | [`serverless.aws-lambda.nodejs16.x`](rules/serverless.aws-lambda.nodejs16.x.html) | end-of-life | 3 | 2 |
| aws-lambda-runtime/provided.al2 | AWS Lambda OS-only runtime provided.al2 runtime is end-of-life | [`serverless.aws-lambda.provided.al2`](rules/serverless.aws-lambda.provided.al2.html) | end-of-life | 3 | 2 |
| azure-pipelines/macos-image | Azure Pipelines macOS 14 Sonoma hosted image is scheduled for removal on 2026-11-23 | [`ci-images.azure-pipelines.macos-14`](rules/ci-images.azure-pipelines.macos-14.html) | scheduled-end-of-life | 3 | 3 |
| django | Django 4.2 LTS is end-of-life | [`python.package.django-4.2.eol`](rules/python.package.django-4.2.eol.html) | end-of-life | 3 | 3 |
| github-actions/set-env | Removed GitHub Actions ::set-env command | [`github-actions.workflow-command.set-env`](rules/github-actions.workflow-command.set-env.html) | removed | 3 | 2 |
| hashicorp/setup-terraform | Unsupported hashicorp/setup-terraform runtime | [`github-actions.setup-terraform.node20`](rules/github-actions.setup-terraform.node20.html) | end-of-support | 3 | 3 |
| kubernetes/extensions/ReplicaSet | ReplicaSet extensions/v1beta1 is no longer served | [`kubernetes.extensions.replicaset.v1beta1.removed`](rules/kubernetes.extensions.replicaset.v1beta1.removed.html) | removed | 3 | 2 |
| kubernetes/networking.k8s.io/Ingress | Ingress networking.k8s.io/v1beta1 is no longer served | [`kubernetes.networking-k8s-io.ingress.v1beta1.removed`](rules/kubernetes.networking-k8s-io.ingress.v1beta1.removed.html) | removed | 3 | 3 |
| kubernetes/rbac.authorization.k8s.io/Role | Role rbac.authorization.k8s.io/v1beta1 is no longer served | [`kubernetes.rbac-authorization-k8s-io.role.v1beta1.removed`](rules/kubernetes.rbac-authorization-k8s-io.role.v1beta1.removed.html) | removed | 3 | 3 |
| nodejs | Node.js 23 is end-of-life | [`nodejs.runtime.eol-23`](rules/nodejs.runtime.eol-23.html) | end-of-life | 3 | 3 |
| popper.js | popper.js is deprecated | [`npm.package.popper.js.deprecated`](rules/npm.package.popper.js.deprecated.html) | deprecated | 3 | 3 |
| postgresql | PostgreSQL 11 is no longer a supported major version | [`database.postgresql.end-of-life-11`](rules/database.postgresql.end-of-life-11.html) | end-of-life | 3 | 3 |
| postgresql | PostgreSQL 12 is no longer a supported major version | [`database.postgresql.end-of-life-12`](rules/database.postgresql.end-of-life-12.html) | end-of-life | 3 | 3 |
| postgresql | PostgreSQL 14 reaches the end of its support on 2026-11-12 | [`database.postgresql.end-of-life-14`](rules/database.postgresql.end-of-life-14.html) | scheduled-end-of-life | 3 | 3 |
| redis | Redis 7.0 is end-of-life | [`database.redis.end-of-life-7.0`](rules/database.redis.end-of-life-7.0.html) | end-of-life | 3 | 3 |
| rollup-plugin-babel | rollup-plugin-babel is deprecated | [`npm.package.rollup-plugin-babel.deprecated`](rules/npm.package.rollup-plugin-babel.deprecated.html) | deprecated | 3 | 3 |
| terraform | Terraform CLI 1.12 is no longer a supported release line | [`terraform.cli.end-of-support-1.12`](rules/terraform.cli.end-of-support-1.12.html) | end-of-support | 3 | 2 |
| @angular/core | @angular/core v18 and older are no longer supported | [`npm.package.angular.core.v18-and-older.end-of-support`](rules/npm.package.angular.core.v18-and-older.end-of-support.html) | end-of-support | 2 | 2 |
| @angular/core | @angular/core v19 is no longer supported | [`npm.package.angular.core.v19.end-of-support`](rules/npm.package.angular.core.v19.end-of-support.html) | end-of-support | 2 | 2 |
| aws-lambda-runtime/python3.7 | AWS Lambda Python 3.7 runtime is end-of-life | [`serverless.aws-lambda.python3.7`](rules/serverless.aws-lambda.python3.7.html) | end-of-life | 2 | 1 |
| bun | Bun 0.x pre-release is end-of-life | [`deno.bun.runtime.eol-0.x`](rules/deno.bun.runtime.eol-0.x.html) | end-of-life | 2 | 2 |
| crypto-js | crypto-js is deprecated | [`npm.package.crypto-js.deprecated`](rules/npm.package.crypto-js.deprecated.html) | deprecated | 2 | 2 |
| github-actions/add-path | Removed GitHub Actions ::add-path command | [`github-actions.workflow-command.add-path`](rules/github-actions.workflow-command.add-path.html) | removed | 2 | 1 |
| java | Java 9 and 10 are no longer supported | [`java.jdk.end-of-support-9-10`](rules/java.jdk.end-of-support-9-10.html) | end-of-support | 2 | 1 |
| karma-phantomjs-launcher | karma-phantomjs-launcher is deprecated | [`npm.package.karma-phantomjs-launcher.deprecated`](rules/npm.package.karma-phantomjs-launcher.deprecated.html) | deprecated | 2 | 2 |
| kubernetes/apiregistration.k8s.io/APIService | APIService apiregistration.k8s.io/v1beta1 is no longer served | [`kubernetes.apiregistration-k8s-io.apiservice.v1beta1.removed`](rules/kubernetes.apiregistration-k8s-io.apiservice.v1beta1.removed.html) | removed | 2 | 1 |
| kubernetes/apps/DaemonSet | DaemonSet apps/v1beta2 is no longer served | [`kubernetes.apps.daemonset.v1beta2.removed`](rules/kubernetes.apps.daemonset.v1beta2.removed.html) | removed | 2 | 2 |
| kubernetes/apps/Deployment | Deployment apps/v1beta2 is no longer served | [`kubernetes.apps.deployment.v1beta2.removed`](rules/kubernetes.apps.deployment.v1beta2.removed.html) | removed | 2 | 2 |
| kubernetes/apps/ReplicaSet | ReplicaSet apps/v1beta2 is no longer served | [`kubernetes.apps.replicaset.v1beta2.removed`](rules/kubernetes.apps.replicaset.v1beta2.removed.html) | removed | 2 | 1 |
| kubernetes/apps/StatefulSet | StatefulSet apps/v1beta1 is no longer served | [`kubernetes.apps.statefulset.v1beta1.removed`](rules/kubernetes.apps.statefulset.v1beta1.removed.html) | removed | 2 | 2 |
| kubernetes/autoscaling/HorizontalPodAutoscaler | HorizontalPodAutoscaler autoscaling/v2beta1 is no longer served | [`kubernetes.autoscaling.horizontalpodautoscaler.v2beta1.removed`](rules/kubernetes.autoscaling.horizontalpodautoscaler.v2beta1.removed.html) | removed | 2 | 2 |
| laravel/framework | Laravel 11 is no longer supported | [`php.package.laravel.framework-11.end-of-support`](rules/php.package.laravel.framework-11.end-of-support.html) | end-of-support | 2 | 1 |
| next | Next.js 12 is out of support | [`npm.package.next.12.support-end`](rules/npm.package.next.12.support-end.html) | end-of-support | 2 | 2 |
| postgresql | PostgreSQL 10 is no longer a supported major version | [`database.postgresql.end-of-life-10`](rules/database.postgresql.end-of-life-10.html) | end-of-life | 2 | 2 |
| protractor | Protractor is deprecated | [`npm.package.protractor.deprecated`](rules/npm.package.protractor.deprecated.html) | deprecated | 2 | 2 |
| pycrypto | PyCrypto is obsolete and vulnerable | [`python.package.pycrypto.obsolete`](rules/python.package.pycrypto.obsolete.html) | end-of-life | 2 | 2 |
| request-promise | request-promise is deprecated | [`npm.package.request-promise.deprecated`](rules/npm.package.request-promise.deprecated.html) | deprecated | 2 | 2 |
| ruby | Ruby 2.1 is end-of-life | [`ruby.runtime.eol-2.1`](rules/ruby.runtime.eol-2.1.html) | end-of-life | 2 | 2 |
| scala | Scala 3.0–3.2 no longer receive patches | [`scala.runtime.eos-3.0-3.2`](rules/scala.runtime.eos-3.0-3.2.html) | end-of-support | 2 | 2 |
| sensiolabs/security-checker | sensiolabs/security-checker is abandoned | [`php.package.sensiolabs.security-checker.abandoned`](rules/php.package.sensiolabs.security-checker.abandoned.html) | deprecated | 2 | 1 |
| uglify-es | uglify-es is deprecated | [`npm.package.uglify-es.deprecated`](rules/npm.package.uglify-es.deprecated.html) | deprecated | 2 | 2 |
| @types/dotenv | @types/dotenv is deprecated | [`npm.package.types.dotenv.deprecated`](rules/npm.package.types.dotenv.deprecated.html) | deprecated | 1 | 1 |
| @types/emoji-regex | @types/emoji-regex is deprecated | [`npm.package.types.emoji-regex.deprecated`](rules/npm.package.types.emoji-regex.deprecated.html) | deprecated | 1 | 1 |
| @types/form-data | @types/form-data is deprecated | [`npm.package.types.form-data.deprecated`](rules/npm.package.types.form-data.deprecated.html) | deprecated | 1 | 1 |
| @types/koa-useragent | @types/koa-useragent is deprecated | [`npm.package.types.koa-useragent.deprecated`](rules/npm.package.types.koa-useragent.deprecated.html) | deprecated | 1 | 1 |
| @types/sanitize-filename | @types/sanitize-filename is deprecated | [`npm.package.types.sanitize-filename.deprecated`](rules/npm.package.types.sanitize-filename.deprecated.html) | deprecated | 1 | 1 |
| @types/socket.io-client | @types/socket.io-client is deprecated | [`npm.package.types.socket.io-client.deprecated`](rules/npm.package.types.socket.io-client.deprecated.html) | deprecated | 1 | 1 |
| amazon-eks | Amazon EKS 1.30 and earlier are past end of extended support | [`terraform.eks.end-of-life-1.30-and-older`](rules/terraform.eks.end-of-life-1.30-and-older.html) | end-of-life | 1 | 1 |
| aws-lambda-runtime/dotnet10 | AWS Lambda .NET 10 runtime reaches end of life on 2028-11-14 | [`serverless.aws-lambda.dotnet10`](rules/serverless.aws-lambda.dotnet10.html) | scheduled-end-of-life | 1 | 1 |
| aws-lambda-runtime/go1.x | AWS Lambda Go 1.x runtime is end-of-life | [`serverless.aws-lambda.go1.x`](rules/serverless.aws-lambda.go1.x.html) | end-of-life | 1 | 1 |
| aws-lambda-runtime/java25 | AWS Lambda Java 25 runtime reaches end of life on 2029-06-30 | [`serverless.aws-lambda.java25`](rules/serverless.aws-lambda.java25.html) | scheduled-end-of-life | 1 | 1 |
| aws-lambda-runtime/nodejs10.x | AWS Lambda Node.js 10 runtime is end-of-life | [`serverless.aws-lambda.nodejs10.x`](rules/serverless.aws-lambda.nodejs10.x.html) | end-of-life | 1 | 1 |
| aws-lambda-runtime/nodejs18.x | AWS Lambda Node.js 18 runtime is end-of-life | [`serverless.aws-lambda.nodejs18.x`](rules/serverless.aws-lambda.nodejs18.x.html) | end-of-life | 1 | 1 |
| aws-lambda-runtime/python3.13 | AWS Lambda Python 3.13 runtime reaches end of life on 2029-06-30 | [`serverless.aws-lambda.python3.13`](rules/serverless.aws-lambda.python3.13.html) | scheduled-end-of-life | 1 | 1 |
| aws-lambda-runtime/ruby2.7 | AWS Lambda Ruby 2.7 runtime is end-of-life | [`serverless.aws-lambda.ruby2.7`](rules/serverless.aws-lambda.ruby2.7.html) | end-of-life | 1 | 1 |
| azure-app-service/node | App Service Node.js stacks older than 18 are no longer supported | [`serverless.azure-app-service.node-below-18`](rules/serverless.azure-app-service.node-below-18.html) | end-of-life | 1 | 1 |
| cloud.google.com/go/pubsub | cloud.google.com/go/pubsub is deprecated | [`go.module.cloud.google.com.go.pubsub.deprecated`](rules/go.module.cloud.google.com.go.pubsub.deprecated.html) | deprecated | 1 | 1 |
| com.android.billingclient/billing | Google Play Billing Library 5 is past its deprecation deadline | [`android.play-billing.version-5`](rules/android.play-billing.version-5.html) | deprecated | 1 | 1 |
| com.android.billingclient/billing | Google Play Billing Library 6 is past its deprecation deadline | [`android.play-billing.version-6`](rules/android.play-billing.version-6.html) | deprecated | 1 | 1 |
| com.android.billingclient/billing | Google Play Billing Library 7 is past its deprecation deadline | [`android.play-billing.version-7`](rules/android.play-billing.version-7.html) | deprecated | 1 | 1 |
| com.android.billingclient/billing | Google Play Billing Library 9 reaches its new-app and update deadline on 2028-08-31 | [`android.play-billing.version-9`](rules/android.play-billing.version-9.html) | scheduled-end-of-life | 1 | 1 |
| dart | Dart 3.11 no longer receives security updates | [`dart.sdk.end-of-support-3.11`](rules/dart.sdk.end-of-support-3.11.html) | end-of-support | 1 | 1 |
| django | Django 2.2 LTS is end-of-life | [`python.package.django-2.2.eol`](rules/python.package.django-2.2.eol.html) | end-of-life | 1 | 1 |
| domexception | domexception is deprecated | [`npm.package.domexception.deprecated`](rules/npm.package.domexception.deprecated.html) | deprecated | 1 | 1 |
| google-cloud-functions-runtime/nodejs14 | Google Cloud Functions Node.js 14 runtime is end-of-life | [`serverless.google-cloud-functions.nodejs14`](rules/serverless.google-cloud-functions.nodejs14.html) | end-of-life | 1 | 1 |
| google-cloud-functions-runtime/nodejs20 | Google Cloud Functions Node.js 20 runtime is end-of-life | [`serverless.google-cloud-functions.nodejs20`](rules/serverless.google-cloud-functions.nodejs20.html) | end-of-life | 1 | 1 |
| google-cloud-functions-runtime/python37 | Google Cloud Functions Python 3.7 runtime is end-of-life | [`serverless.google-cloud-functions.python37`](rules/serverless.google-cloud-functions.python37.html) | end-of-life | 1 | 1 |
| google-cloud-sql-mysql | Cloud SQL for MySQL 5.6 and 5.7 are in extended support | [`database.google-cloud-sql-mysql.extended-support-5.6-to-5.7`](rules/database.google-cloud-sql-mysql.extended-support-5.6-to-5.7.html) | end-of-support | 1 | 1 |
| gulp-util | gulp-util is deprecated | [`npm.package.gulp-util.deprecated`](rules/npm.package.gulp-util.deprecated.html) | deprecated | 1 | 1 |
| helm-repository/incubator | Helm incubator chart repository is end of life | [`kubernetes.helm.repository.incubator.end-of-life`](rules/kubernetes.helm.repository.incubator.end-of-life.html) | end-of-life | 1 | 1 |
| i18next-parser | i18next-parser is deprecated | [`npm.package.i18next-parser.deprecated`](rules/npm.package.i18next-parser.deprecated.html) | deprecated | 1 | 1 |
| koa-router | koa-router is deprecated | [`npm.package.koa-router.deprecated`](rules/npm.package.koa-router.deprecated.html) | deprecated | 1 | 1 |
| kubernetes/admissionregistration.k8s.io/MutatingWebhookConfiguration | MutatingWebhookConfiguration admissionregistration.k8s.io/v1beta1 is no longer served | [`kubernetes.admissionregistration-k8s-io.mutatingwebhookconfiguration.v1beta1.removed`](rules/kubernetes.admissionregistration-k8s-io.mutatingwebhookconfiguration.v1beta1.removed.html) | removed | 1 | 1 |
| kubernetes/admissionregistration.k8s.io/ValidatingWebhookConfiguration | ValidatingWebhookConfiguration admissionregistration.k8s.io/v1beta1 is no longer served | [`kubernetes.admissionregistration-k8s-io.validatingwebhookconfiguration.v1beta1.removed`](rules/kubernetes.admissionregistration-k8s-io.validatingwebhookconfiguration.v1beta1.removed.html) | removed | 1 | 1 |
| library/redis | Redis image release line 6.2 reaches end-of-life on 2027-04-01 | [`container.redis.eol-6.2-and-older`](rules/container.redis.eol-6.2-and-older.html) | scheduled-end-of-life | 1 | 1 |
| library/ruby | Ruby image release line 3.3 reaches end-of-life on 2027-03-31 | [`container.ruby.eol-3.3-and-older`](rules/container.ruby.eol-3.3-and-older.html) | scheduled-end-of-life | 1 | 1 |
| library/zookeeper | Apache ZooKeeper image release lines 3.7 and older are end-of-life | [`container.zookeeper.eol-3.7-and-older`](rules/container.zookeeper.eol-3.7-and-older.html) | end-of-life | 1 | 1 |
| lodash.isequal | lodash.isequal is deprecated | [`npm.package.lodash-isequal.deprecated`](rules/npm.package.lodash-isequal.deprecated.html) | deprecated | 1 | 1 |
| mysql/mysql-connector-java | mysql:mysql-connector-java has moved to com.mysql:mysql-connector-j | [`java.maven.mysql.mysql-connector-java.relocated`](rules/java.maven.mysql.mysql-connector-java.relocated.html) | deprecated | 1 | 1 |
| natives | natives is deprecated | [`npm.package.natives.deprecated`](rules/npm.package.natives.deprecated.html) | deprecated | 1 | 1 |
| next | Next.js 13 is out of support | [`npm.package.next.13.support-end`](rules/npm.package.next.13.support-end.html) | end-of-support | 1 | 1 |
| nose | nose is maintenance-only | [`python.package.nose.maintenance-only`](rules/python.package.nose.maintenance-only.html) | deprecated | 1 | 1 |
| php | PHP 7.3 is end-of-life | [`php.runtime.eol-7.3`](rules/php.runtime.eol-7.3.html) | end-of-life | 1 | 1 |
| powershell | PowerShell 7.3 is no longer supported | [`shell.powershell.end-of-life-7.3`](rules/shell.powershell.end-of-life-7.3.html) | end-of-life | 1 | 1 |
| pytest-runner | pytest-runner is deprecated | [`python.package.pytest-runner.deprecated`](rules/python.package.pytest-runner.deprecated.html) | deprecated | 1 | 1 |
| q | q is deprecated | [`npm.package.q.deprecated`](rules/npm.package.q.deprecated.html) | deprecated | 1 | 1 |
| react-beautiful-dnd | react-beautiful-dnd is deprecated | [`npm.package.react-beautiful-dnd.deprecated`](rules/npm.package.react-beautiful-dnd.deprecated.html) | deprecated | 1 | 1 |
| ruby | Ruby 2.2 is end-of-life | [`ruby.runtime.eol-2.2`](rules/ruby.runtime.eol-2.2.html) | end-of-life | 1 | 1 |
| ruby | Ruby 2.4 is end-of-life | [`ruby.runtime.eol-2.4`](rules/ruby.runtime.eol-2.4.html) | end-of-life | 1 | 1 |
| socket.io-redis | socket.io-redis is deprecated | [`npm.package.socket.io-redis.deprecated`](rules/npm.package.socket.io-redis.deprecated.html) | deprecated | 1 | 1 |
| typing | typing is archived on PyPI | [`python.package.typing.archived`](rules/python.package.typing.archived.html) | end-of-life | 1 | 1 |
| zendframework/zend-stdlib | zendframework/zend-stdlib is abandoned | [`php.package.zendframework.zend-stdlib.abandoned`](rules/php.package.zendframework.zend-stdlib.abandoned.html) | deprecated | 1 | 1 |
<!-- state-of-eol:end -->

## Limits

Counts come from expected findings in `benchmarks/public-repositories/`, joined to bundled rules in `registry/`. Scans never use the network. A product with no corpus finding does not appear here.

---

Source: https://velella.sh/offing/PRIVACY/

# Offing privacy

Offing analyzes software repositories on the user's computer. The Codex and Claude plugins start a local stdio MCP server and do not send repository contents to an Offing-operated service. Offing does not require an Offing account, collect analytics, use advertising identifiers, or sell personal data.

The local tools read supported manifests, lockfiles, workflow files, runtime-version files, and relevant source excerpts from the repository path the user authorizes. Results can contain file paths and short source excerpts. The host application receives those results, so its privacy policy and the user's workspace settings also apply.

The plugin launches the exact published `offing` npm version recorded in its manifest. The package manager may contact the configured npm registry to obtain that package. Lifecycle evidence links are returned as references; Offing does not open them automatically.

## Lifecycle data channel

Scans use no network. The one exception is `offing data update`, which you run yourself to fetch newer lifecycle rules between releases. Rules ship inside each release; that command downloads a public release list and two public files (the signed bundle and its signature) from the project's GitHub releases, verifies the Sigstore signature offline against a trusted root that ships in the package, and activates the new rules only after verification succeeds. If verification fails, Offing keeps the rules bundled with the installed release and reports why. Pinning with `--data-version` or `OFFING_DATA_VERSION` makes CI use an exact verified bundle (or `bundled`). It sends nothing about you or your repository. See [Lifecycle data](DATA.md).

## Command and surface access

Supply-chain scanners correctly report that the published package can read files, read environment variables, spawn processes (including `git`), and reach the network. Those capabilities are real; they are not used by every command. This table is the contract for what each surface actually does. "Scan path" means the repository (or paths) you pass on the command line or to a tool. Nothing here uploads repository contents to an Offing service.

| Surface / command | Filesystem | Environment | Child process | Network |
| --- | --- | --- | --- | --- |
| **CLI `scan`**, `forecast`, `status-card`, `explain`, `context`, `renovate-preset`, `dependabot-config` | Reads the scan path (manifests, lockfiles, workflows, source). Optional writes only when you ask: `--write-status` → `OFFING_STATUS.md`; `--baseline` reads a baseline file. `status-card`, `renovate-preset`, and `dependabot-config` print to stdout only | `OFFING_DATA_VERSION` (pin bundled/cached rules); `OFFING_DATA_DIR` / `XDG_CACHE_HOME` / `HOME` for cached data; `--interactive` uses `VISUAL` or `EDITOR` to open a finding | `--interactive` may spawn your editor. No `git`, no package manager | None |
| **CLI `lookup`**, `check` | None for the rules themselves (package or local data cache). `check` takes a Package URL; `lookup` takes a product name | Same data-pin and cache variables as `scan`; optional `OFFING_USAGE_LOG` appends one local line for `check` | None | None |
| **CLI `badge`** | `--shields` reads the scan path and prints Shields endpoint JSON. `--snippet` prints README markup only | None beyond process defaults for `--snippet`; data-pin variables when `--shields` scans | Without `--repo`, `--snippet` may run local `git remote get-url origin` (no remotes fetched) | None (image URLs in the markup are references; Offing does not fetch them) |
| **CLI `usage`** | Reads the local usage-log file when logging was enabled | `OFFING_USAGE_LOG`, or `--file` | None | None |
| **CLI `baseline`** | Reads the scan path; writes `.offing-baseline.json` (or `--output`) | Same data-pin and cache variables as `scan` | None | None |
| **CLI `report-issue`** | Reads the scan path and a few lines of the declaring file; optional `--output` write | Same data-pin and cache variables as `scan` | None | None (prints Markdown; never opens an issue) |
| **CLI `rollup`** | Reads the saved report JSON files you name (and optional `--owners` file) | None beyond process defaults | None | None |
| **CLI `inventory`** | Reads only the export files named on the command line and the bundled or cached lifecycle data; no cloud or cluster API | `EBB_DATA_DIR` / cache home variables for lifecycle data | None | None |
| **CLI `sbom enrich`**, `export` | Reads the SBOM (CycloneDX or SPDX 2.3) or bundled/cached lifecycle data; prints enriched JSON or CLE snapshots to stdout; leaves the input unchanged | Data-pin and cache variables as above | None | None |
| **CLI `capabilities`**, `completions`, `--help`, `--version` | None (packaged constants / scripts) | None | None | None |
| **CLI `data status`** | Reads the local data cache and bundled rules | `EBB_DATA_DIR` / cache home variables | None | None |
| **CLI `data update`** | Writes verified bundles under the local data cache | `EBB_DATA_URL` (optional mirror); `HTTP(S)_PROXY` / `http(s)_proxy`; cache home variables. May relaunch Node with `NODE_USE_ENV_PROXY` when a proxy is set | May re-exec the same Node process so proxy env is honored | **Yes** — public GitHub release list plus the signed bundle and signature only. Sends no repository data |
| **CLI `diff`** | Reads git objects into a temp directory, then scans them; leaves the working tree alone | Same data-pin and cache variables as `scan` | Runs local `git archive` and `tar` (no remotes) | None |
| **CLI `doctor`** | Reads the install layout and, for the path argument, local project markers | Detects CI via `GITHUB_ACTIONS` / `GITLAB_CI` and related workspace variables | With `--system`, runs fixed version commands (`node`, `python3`, `go`, …) with a short timeout | None |
| **CLI `guard`** | None for the check itself | Same as `check` for the preflight | After a passing check, spawns the package manager you named (`npm`, `pnpm`, `yarn`, `bun`, …) with your arguments | Only whatever that package manager does after Offing exits the check |
| **CLI `fix`** | Reads the scan path. Default: prints patches to stdout (no write). `--branch`: applies and commits on a new local branch | Same data-pin and cache variables as `scan` | `--branch` runs local `git` (`checkout`, `apply`, `add`, `commit`); never `push` | None |
| **CLI `init --agents`**, `setup` | Reads/writes agent instruction files in the scan path (`AGENTS.md`, `CLAUDE.md`, host rule files, …) | None beyond process defaults | None | None |
| **CLI `init`** (guided, no flags) | Reads the CI provider and agent markers in the scan path; writes `.github/workflows/offing.yml`, `.git/hooks/pre-push`, and agent files (after confirmation unless `--yes`) | None beyond process defaults | Runs `git rev-parse` to locate hooks | None |
| **CLI `init --hooks`** | Reads/writes `.git/hooks/pre-push` (or the path `git` reports) | None beyond process defaults | Runs `git rev-parse` to locate hooks | None |
| **CLI `init --personal`** | Writes `~/.config/offing/` (or `XDG_CONFIG_HOME`) config and a global pre-push hook | `HOME` / `USERPROFILE`, `XDG_CONFIG_HOME` | Runs `git config --global core.hooksPath` (after confirmation unless `--yes`) | None |
| **CLI `watch`** | Reads registered projects (same as `scan`); reads/writes `watch.json` under the personal config directory | `HOME` / `XDG_CONFIG_HOME` for state location; same data-pin variables when scanning | None | None |
| **CLI `new-detector`**, `new-rule`, `rules lint`, `rules test` | Contributor checkout only: scaffolds detector or rule fixtures, or reads registry fixtures under the repo | None | None | None |
| **CLI `mcp`** / **`offing mcp`** | Same reads as the tools below; no repository writes | Optional `OFFING_USAGE_LOG` for `check_dependency`; data-pin and cache variables | None (stdio only; no shell for migrations) | None |
| **MCP tools** (`scan_repository`, `list_deprecations`, `explain_deprecation`, `create_migration_context`, `verify_migration`, `check_dependency`) | Read the authorized repository path (except `check_dependency`, which reads no repository). Session findings stay in memory | Same as MCP process above | None — `verify_migration` returns suggested commands and does not run them | None |
| **`offing lsp`** | Reads/scans workspace folders; may write open buffer text into a private temp directory for analysis | None beyond process defaults | None | None (stdio language server) |
| **GitHub Action** | Reads `path` (default workspace); may write report/SARIF/badge under `RUNNER_TEMP` when upload inputs are on; reads `GITHUB_EVENT_PATH` for PR metadata | Action inputs as `INPUT_*`, plus `GITHUB_WORKSPACE`, `GITHUB_OUTPUT`, `GITHUB_STEP_SUMMARY`, `GITHUB_REPOSITORY`, `GITHUB_API_URL`, `RUNNER_TEMP`, and `INPUT_GITHUB-TOKEN` when commenting | None from Offing itself | **Only when `pr-comment: true`**: GitHub API upsert of one PR comment after the scan. The scan itself uses no network |
| **GitLab CI/CD component** | Reads the checked-out path; writes the JSON report and Code Quality report as job artifacts | Component inputs and standard GitLab CI variables; no access token required | None from Offing itself (`npx` runs the pinned package) | **None for the scan.** Before the scan, the runner may pull the job image and `npx` may fetch the pinned package from the configured npm registry. No GitLab API call; see [GitLab](GITLAB.md#network-behavior) |
| **Agent Skill / Codex & Claude plugins** | No direct I/O: they launch the local MCP server or tell the host to run CLI commands under the host's permission model | Host may set env when spawning MCP/CLI | Host may spawn `npx` / Node to start MCP | Package install may hit the npm registry; analysis stays local |

Notes that apply across rows:

- Detectors never call the network and never execute repository code. Repository contents are parsed as data.
- Evidence URLs in findings are references only; Offing does not open them.
- Maintainer-only scripts under `tools/` (importers, source checks, adoption metrics) can use the network and optional `GITHUB_TOKEN` / `GH_TOKEN`. They are not part of the published CLI scan path and are not in the table above.
- Socket and similar scanners flag the *capability* (filesystem, env, child process, URL strings) because the code exists in the tarball. Use this table to see which command exercises which capability.

## Local usage log

By default Offing records nothing about what you or an agent checked. If you set `OFFING_USAGE_LOG=1` (or to a file path), each `offing check` and each `check_dependency` call appends one line to a file on your machine: the time, the package URL and version checked, the result, its severity, and the matching rule IDs. It records no repository path, file content, user name, or prompt. `offing usage` reads that file and prints how many checks ran and which packages were flagged as `affected` (what the guardrail told an agent to avoid; Offing cannot itself stop an edit). **Nothing in this log is sent anywhere: Offing has no code that uploads it, and the summary command reads only the local file.** Delete the file to erase it; unset the variable to stop recording. Because the file lives on disk, anything that can read your files can read it.

Offing's tools do not edit repository files, execute suggested migration commands, open a network listener, or request credentials — except the explicit write and process rows in the table above (`baseline`, `--write-status`, `init` / `setup`, `fix --branch`, `guard`'s package manager, and similar). Users can disable or remove the plugin at any time. Questions can be reported through [GitHub Issues](https://github.com/velella-sh/offing/issues).

---

Source: https://velella.sh/offing/THREAT_MODEL/

# Threat model

Offing reads code it did not write, loads data it did not build at the same time as the code, and gives answers to tools that can edit and install. This page records what v1 trusts, the threats each surface faces, what mitigates them, and what remains. [Privacy](PRIVACY.md) lists the exact capabilities of every command; [Lifecycle data](DATA.md) explains bundle signatures. This page connects them.

## Scope and assumptions

In scope: the CLI scan path, the GitHub Action and GitLab component, lifecycle data bundles, the local MCP server, and the Git and agent hooks.

Out of scope: compromise of the operating system or the user's account, vulnerabilities in npm packages Offing depends on (listed with their reasons in [Runtime dependencies](DEPENDENCIES.md)), the correctness of the Sigstore and GitHub infrastructure, and what an AI host does with the answers it receives. Report Offing vulnerabilities through [SECURITY.md](../SECURITY.md).

Assumptions:

- **Repository contents are untrusted.** A repository may be hostile and may be written to make a scan look clean.
- **The machine and the user are trusted.** The person running Offing can already read the files it reads and run the commands it runs.
- **The agent is semi-trusted.** A coding agent using the MCP server can be manipulated by content it reads, including repository text that Offing returns.
- **Verified data is authentic, not necessarily correct.** A signature proves which workflow published a rule, not that the claim is true.
- **Hooks are guardrails, not boundaries.** Everything they add can be bypassed by the user and by commands they do not parse.

## Trust boundaries

| From | To | What crosses |
|---|---|---|
| Repository | Detectors and source analysis | File contents, parsed as data only |
| Signed release | Registry and scan engine | Declarative rules, after verification |
| Scan engine | CLI output and MCP host | Findings, file paths, short source excerpts |
| Hook | Package manager, Git, agent | A denial, or the user's command after a passing check |
| Offing | Network | Only `data update`, a first `npx` fetch, a configured PR comment, and the package manager's own traffic |

## Untrusted repositories

This surface covers `scan`, `explain`, `context`, `diff`, the GitHub Action, and the GitLab component. Detectors parse manifests, lockfiles, workflows, and source text; they never evaluate it, and the scan path never starts a child process or uses the network.

| STRIDE | Threat | Mitigation | Residual risk |
|---|---|---|---|
| Spoofing | A repository supplies a status file or a modified baseline that hides its own findings from a reader or an agent. | Findings always name the rule, the file, and the exact line; `OFFING_STATUS.md` is described as a snapshot; a baseline's suppressions are counted and reported; neither can change a rule. | A committed status file can be stale or forged for a human reader, and a pull request can edit the CI baseline. Reviewers must review baseline changes and re-scan. |
| Tampering | Malformed, duplicate, or contradictory input makes a parser miss a declaration, crash the scan, or report a wrong location. | Strict parsers; malformed input yields no declaration instead of a guess; unreadable directories are skipped; scans are deterministic. | Detection is declaration-based. A repository can declare one runtime and use another, and an unsupported syntax can hide a usage until a detector learns it. |
| Repudiation | There is no record of what a scan saw. | Not a logging product; CI keeps the JSON report, and an opt-in local usage log records `check` calls. | A local scan leaves no audit trail by default. |
| Information disclosure | Findings embed file paths and source excerpts that appear in logs, pull request comments, or an agent's context. | Reads stay local; the Action posts a comment only when asked; no Offing service receives results. | Whatever reads the output, including a hosted agent, receives the excerpts and applies its own policy. |
| Denial of service | A huge file, deeply nested JSON, a symlink cycle, or a pathological source file stalls the scan. | Per-file read caps of about 1 MB, JSON nesting capped at 64, symlinks not followed, unreadable paths skipped, bounded alias and depth budgets in source parsers. | A very large tree still costs time and memory; there is no global wall-clock budget, and CI jobs have their own timeouts. |
| Elevation of privilege | Repository content achieves execution, or text in a file instructs the agent that reads the findings. | Parsers never evaluate; no `eval`, no child process, no network in the scan path; the MCP prompt and migration packet name repository files as untrusted. | Prompt injection is not preventable by the scanner: a comment, a file name, or a manifest string can try to steer the host. The host's permission model is the boundary. |

`diff` is the one scan-path command that runs processes: it calls the local `git` and `tar` to materialize a revision in a temporary directory. They operate on Git objects, not on repository scripts.

## Data bundles

Lifecycle rules travel as one JSON bundle. The release workflow signs it with Sigstore keyless signing; Offing verifies it offline before use.

| STRIDE | Threat | Mitigation | Residual risk |
|---|---|---|---|
| Spoofing | A forged bundle claims to carry Offing's rules. | The signature must verify against the exact bytes; the signer must be the release workflow at a `data-v…` tag or `main`; chain, validity, and transparency-log inclusion are checked against a trusted root shipped in the package. | The trusted root ages. If Sigstore rotates keys and the installed release is too old, new bundles stop verifying and Offing falls back to bundled data. |
| Tampering | A file in a valid bundle is altered, removed, or added. | Every file has a SHA-256 and byte count, the manifest has a content digest, extra and missing files are refused, registry content is validated again, and the format version and minimum Offing version must match. | A compromise of the release workflow or of a maintainer who can push a data tag would sign whatever was built. Rule review before `main` is the control there. |
| Repudiation | A bundle's publisher is disputed. | The signing identity is recorded in the public transparency log and can be checked with `cosign`. | Verification is recorded only in local status output. |
| Information disclosure | Updating data reveals what the user is doing. | `data update` requests the public release list, the bundle, and its signature; it sends no repository data and no identifier. | The mirror and the network observe the download, as with any file fetch. |
| Denial of service | An oversized or hostile download exhausts memory or hangs. | 20 MB bundle, 1 MB signature, and 4 MB listing caps; 30-second request timeouts; a mirror can be configured but the same signature check still applies; failure falls back to bundled data. | Repeated failed updates can be retried without limit by the user or a script. |
| Elevation of privilege | A bundle carries executable behavior. | Bundles and registries are declarative JSON, validated before use; no rule field is executed. | A correctly signed but wrong rule affects findings until the next data release. Bundles have no revocation list, and a pinned old bundle stays pinned. |

The local calendar tool's `--bundle FILE` option reads a bundle the user names on the command line. It validates the registry schema but does not verify a signature, because the file is the user's own input, like any other path they pass.

## Release verification

`offing verify` reads the release manifest shipped in the package and hashes every file the manifest lists; a changed, shortened, or missing file fails. When a Sigstore bundle for the manifest is present, it verifies offline against the trusted root bundled with the package. The command never uses the network, so it does not verify the npm registry signature or the npm provenance attestation: those are served by the registry, not shipped in the tarball. The report names `npm audit signatures` and `gh attestation verify` as the commands that check them.

The residual risk is the unsigned case. A manifest with no signature detects an accidental or partial change, but an attacker who can rewrite every file can also rewrite the manifest and its digests. Authenticity rests on npm's registry signature and provenance attestation, which need the network, or on a future release that ships a signed manifest.

## MCP server

The server speaks MCP over stdio, is started by the host, and is one process per session. It advertises `tools`, `resources`, `prompts`, and `completions`.

| STRIDE | Threat | Mitigation | Residual risk |
|---|---|---|---|
| Spoofing | A host starts a different server, or an unrelated local process claims to be Offing. | There is no listener, port, account, or credential to impersonate; the host launches the process it configured, and the plugins pin an exact published version. | A host that resolves an unpinned `npx` package trusts the registry and cache it resolves from. |
| Tampering | A tool changes the repository while "analyzing" it. | Every tool is read-only, has no output, fix, or overwrite option, advertises `readOnlyHint: true`, and runs no command; session findings stay in memory; a test calls every tool and fails if the repository tree changes. | The host still has its own write tools. Offing cannot stop an agent from editing after a scan. |
| Repudiation | Nobody can tell which packages an agent was warned about. | An opt-in usage log appends package, result, severity, and rule IDs to a local file. | Nothing is recorded by default, and the log can be edited or deleted by anyone who can read the file. |
| Information disclosure | Tool results carry repository paths and excerpts into a hosted model. | No Offing-operated service receives results; the host's policy applies; `check_dependency` reads no repository. | A prompt-injected agent can point `scan_repository` at any path the user can read — not only the project — and surface what it finds. The host's authorization prompt is the boundary. |
| Denial of service | An agent requests scans of very large or repeated trees. | Per-file size caps and deterministic work per file. | The server has no per-request time budget; the host must cancel or time out a call. |
| Elevation of privilege | A tool executes a suggested migration command. | `verify_migration` returns the project commands it suggests; no tool spawns a shell; the `migrate-finding` prompt states that repository files are untrusted and that commands run only under the host's authorization. | The prompt is guidance. A host that auto-approves commands is outside Offing's control. |

## Hooks and guardrails

Four mechanisms try to catch a bad dependency at the moment it is added. Each is documented in [Hooks](HOOKS.md).

| Mechanism | What it does | Bypass and residual risk |
|---|---|---|
| Git pre-push hook (`init --hooks`) | Runs `scan . --fail-on <severity>` before a push and blocks at or above the gate. Offline, local rules only. | `git push --no-verify`, `OFFING_SKIP=1`, and deleting the hook. If Offing is missing or the scan errors, the push proceeds. It protects only pushes made from this clone. |
| Claude Code `PreToolUse` hook | Splits a top-level Bash command and checks package arguments of `npm`, `pnpm`, `yarn`, `pip`, and `uv` installs. | It inspects only the top-level command: `bash -c`, shell functions, aliases, scripts, `npm install` with no arguments, and lockfile installs are not checked. A 60-second host timeout and per-package budget fail open. The first `npx` run may download the pinned package. |
| `guard` CLI | Checks the npm packages named to `offing guard npm install …`, then runs exactly that command if none is refused. | `--force` overrides; arguments the parser does not understand, package scripts, and npm's own resolution and lifecycle scripts are outside the check. It checks lifecycle status, not malware. |
| Cursor rules and Copilot instructions | Tell the agent to call `check_dependency` before adding a package. | Advisory only; nothing blocks an edit. |

Common to all four: they read the same local rules, send nothing, and can be removed by the user. None is a security boundary against a determined person or a misbehaving agent, and none inspects transitive dependencies or the contents of the packages it approves.

## Network reach

Scans use no network. The complete list of network activity in the published package is in [Privacy](PRIVACY.md#command-and-surface-access):

- `data update`: the public release list, a signed bundle, and its signature.
- A first `npx` or package install of Offing itself, by the user, the plugin, or a hook.
- The GitHub Action's optional pull request comment, through the GitHub API.
- Whatever package manager a user runs through `guard`.

Maintainer scripts under `tools/` are not part of the published CLI and are excluded from this model.

## Reviewing this model

Update this page in the same pull request as any change to a trust boundary: a new tool that writes, a new network call, a new file format the scanner parses, a new hook, or a change to signature verification. A threat with no mitigation in the table is a bug or an accepted risk that should name its follow-up issue.

---

Source: https://velella.sh/offing/DEPENDENCIES.html

# Runtime dependencies

Offing installs as one npm package, and every package it depends on is code its users install and must trust.
This page records the audit of that set: why each dependency is there, what removing it would cost, and the
checks it passed. It is the written reason the [agent brief](../AGENTS.md#dependencies) asks for before a runtime
dependency can be kept or added.

The audit ran on **2026-11-06** at commit `efc784e5`. It changed no behavior and added no network access to any
scan. On **2026-11-09** the lifecycle data and the code that reads and verifies it moved into
[Ebb](https://github.com/velella-sh/ebb) (`@velella/ebb`), so the three Sigstore packages are now Ebb's dependencies and Offing depends on Ebb.

## Result

Six direct dependencies remain. Each one is imported by shipped `src/` code, declares no install script, and has
no reviewed lifecycle rule that would make Offing report it as end-of-life, deprecated, or retired. Nothing was
unused, so nothing was removed. Removing any of them would drop a feature users already rely on; the section for
each package says which one.

They resolve to a runtime tree of eleven packages: `@modelcontextprotocol/core`, Ebb's three Sigstore packages, and
`@sigstore/core` are the transitive additions. `npm audit --omit=dev` reports zero advisories, and [SECURITY.md](../SECURITY.md) requires
that to stay true at any severity and any depth.

| Dependency | Range | Installed | License | What it does for Offing | Install script |
|---|---|---|---|---|---|
| `@modelcontextprotocol/server` | `^2.3.1` | 2.4.0 | Apache-2.0 | Runs the local MCP server and its stdio transport | none |
| `@velella/ebb` | `^0.1.1` | 0.1.1 | MIT (data CC BY 4.0) | The lifecycle rules, purl and VERS matching, and signed data updates | none |
| `semver` | `^7.8.5` | 7.8.5 | ISC | Reads and compares semantic versions and npm ranges | none |
| `smol-toml` | `^1.9.1` | 1.9.1 | BSD-3-Clause | Parses TOML manifests and lockfiles | none |
| `yaml` | `^2.9.1` | 2.9.1 | ISC | Parses YAML manifests with exact line numbers | none |
| `zod` | `^4.6.5` | 4.6.7 | MIT | Validates MCP tool input and the capability manifest | none |

## Why each one stays

### `@modelcontextprotocol/server`

The official MCP TypeScript SDK. `src/mcp.ts` registers the ten tools, resources, and the migration prompt on its
`McpServer`, and `src/mcp-server.ts` serves them over stdio for `offing mcp`. The tests drive the same server
through its `InMemoryTransport`, which is why the package is also imported by `tests/`. Writing the JSON-RPC
framing, capability negotiation, and transport by hand would replace maintained protocol code with code no host
has tested, for a server that has to work with Claude, Codex, Copilot, and other MCP hosts.

### `@velella/ebb`

[Ebb](https://github.com/velella-sh/ebb) is the lifecycle data every finding comes from, published as its own package so other tools can use it:
the rules, the purl and VERS matching, the forecast, and the data updates that fetch a newer signed bundle and verify
it with Sigstore before use. Its runtime dependencies are `@sigstore/bundle`, `@sigstore/protobuf-specs`, and
`@sigstore/verify`, which verify a data bundle offline against the trusted root Ebb ships. It is part of the same
organization and reviewed the same way. Without it Offing would have no rules to report.

### `semver`

`semver` parses and compares versions and evaluates npm ranges in the npm detector, the version schemes, the lockfile
readers, `doctor`, `guard`, and the upgrade checks. Range syntax is where a small shortcut turns into wrong findings:
`||`, `x` ranges, hyphen ranges, and prerelease precedence all have defined behavior. `src/vers/semver.ts` already
adds the Composer and Go short forms on top; the comparison below that is the package's job.

### `smol-toml`

`smol-toml` parses `pyproject.toml`, `poetry.lock`, `uv.lock`, `pdm.lock`, and other TOML files read by the Python
detector, drift, fix, upgrade, and workspace code. It has no dependencies and no install script. A TOML parser is
not something to hand-roll for a tool whose findings must cite an exact declaration.

### `yaml`

`yaml` parses workflows, Compose files, Kubernetes manifests, Helm values, serverless templates, and the YAML
manifests behind drift. The detectors need node positions, not only values, so the parser has to keep them:
`LineCounter` and the document API are why findings can name an exact file and line. It is also used in the
codemods that edit those files without reformatting them.

### `zod`

`zod` defines the MCP tool input schemas in `src/mcp.ts` and validates the capability manifest in
`src/capabilities/schema.ts`. The MCP SDK already depends on it, so it is installed either way; declaring it
directly is required because Offing imports `zod/v4` itself. Replacing it would duplicate the schema definitions
and drift from what the SDK validates.

## What the audit checked

Need: every dependency in `package.json` is imported by at least one file under shipped `src/`, or by a file that
entry points import. `knip` in `npm run check` fails on an unused declaration.

Upkeep: each package is published from an actively maintained upstream (`modelcontextprotocol/typescript-sdk`,
`velella-sh/ebb`, `npm/node-semver`, `squirrelchat/smol-toml`, `eemeli/yaml`,
`colinhacks/zod`). [Dependabot](../.github/dependabot.yml) opens weekly update pull requests with a seven-day
cooldown, and the lockfile pins the resolved version.

Install scripts: none of the six declares `preinstall`, `install`, or `postinstall` at its installed version.
These commands reproduce the audit:

```bash
npm ls --omit=dev --all
npm audit --omit=dev
node -e '
const fs = require("node:fs");
for (const name of Object.keys(require("./package.json").dependencies)) {
  const { scripts = {} } = JSON.parse(fs.readFileSync(`node_modules/${name}/package.json`, "utf8"));
  const install = Object.keys(scripts).filter((key) => /^(pre|post)?install$/.test(key));
  console.log(name, install.length ? install.join(",") : "no install scripts");
}'
```

Lifecycle: `offing check pkg:npm/<name>@<version>` for each installed version returned `no-data` on
2026-11-06. That means no reviewed rule covers these packages; it does not mean they are safe, and it is not a
substitute for the advisory check above.

## Adding a runtime dependency

A new runtime dependency is a new package every user installs. It needs all of the following in the pull request:

1. A reason that names the feature it serves and why the code in this repository or the standard library cannot
   serve it.
2. No `preinstall`, `install`, or `postinstall` script, unless the pull request explains what the script does and
   why it is required.
3. A license compatible with Apache-2.0.
4. `npm run dev -- check pkg:npm/<name>@<version>` with no end-of-life, deprecated, or retired result. If the check
   names a replacement, use it or ask in the issue.
5. No new advisory in the runtime tree (`npm audit --omit=dev`) at any severity.
6. An entry in the table on this page, with the same fields as the existing rows.

Removing a dependency needs the same care in reverse: check that no shipped entry point imports it, that its
replacement parses the same inputs, and that the findings and their file and line locations do not change.

---

Source: https://velella.sh/offing/CONTRIBUTE/

# Start contributing

Offing's work is split into small issues, each sized for one pull request. You do not need to know the codebase first: every issue in the `lane: free-agent` lane carries a brief with the files to touch, the steps, and the command that proves it is done.

## Pick an issue

- [Open `good first issue` issues](https://github.com/velella-sh/offing/issues?q=is%3Aopen+label%3A%22good+first+issue%22) — isolated changes with fixtures. Start here.
- [Open `type: rule` good first issues](https://github.com/velella-sh/offing/issues?q=is%3Aopen+label%3A%22good+first+issue%22+label%3A%22type%3A+rule%22) — add one reviewed lifecycle rule from a sourced importer candidate, with fixtures.
- [Open fixture edge-case issues](https://github.com/velella-sh/offing/issues?q=is%3Aopen+label%3A%22type%3A+fixture%22+label%3A%22good+first+issue%22) — lock a triaged false-positive boundary into `tests/fixtures/` (see [the fixtures README](../tests/fixtures/README.md)).
- [All open issues](https://github.com/velella-sh/offing/issues) — filter by label, area, or size.
- [Project board](https://github.com/users/arminazimi/projects/3) — the current phase and what is in progress.
- [Roadmap](ROADMAP.md) — phases, epics, and what each one delivers.

Choose an issue whose **Depends on** issues are closed, then comment on it to claim it. Epics (`type: epic`) only track tasks; the work happens in their task issues.

## Lanes

A `lane:` label says who an issue suits. It is a promise about the brief, not a restriction.

| Lane | Who it suits | What to expect |
|---|---|---|
| `lane: free-agent` | New contributors and any coding agent | A complete brief: files, steps, commands, and a done-check |
| `lane: strong-agent` | Experienced contributors or strong coding agents | Architecture, contracts, parsers, and new detectors |
| `lane: maintainer` | Maintainer only | Accounts, releases, submissions, and outreach |

Sizes are `size: XS` (under an hour), `size: S` (a few hours), and `size: M` (about a day).

## Rules of the road

- One issue per pull request. If you find more work, open a follow-up issue.
- Add or update a test when behavior changes, and keep JSON output deterministic.
- Lifecycle claims need an authoritative, versioned source. Read the [evidence policy](../CONTRIBUTING.md#evidence-policy).
- Scans never use the network and never run repository code.
- Run `npm run check` before you ask for review.

## First steps

The [five-minute path in CONTRIBUTING.md](../CONTRIBUTING.md) walks through cloning, checking the baseline, branching, and opening a pull request. For a first substantive change, [add a lifecycle rule](../CONTRIBUTING.md#your-first-contribution-add-a-lifecycle-rule); rules are the most valuable contribution and the most self-contained.

## Ask

Questions and ideas belong in [GitHub Discussions](https://github.com/velella-sh/offing/discussions): **Q&A** to ask, **Ideas** to propose, and **Show and tell** to share what you built. Use issues for bugs, lifecycle rule proposals, and ecosystem requests.

---

Source: https://velella.sh/offing/DETECTORS/

# Detector authoring

Offing detectors are adapters at the detector SDK seam. They inspect a repository and return lifecycle findings; the scan engine handles detector attribution, sorting, reporting, and composition.

## Supported interface

Import the public SDK from `@velella/offing/sdk`:

```ts
import {
  defineDetector,
  DETECTOR_API_VERSION,
  type Detector,
} from "@velella/offing/sdk";
```

A compatible detector has one stable identifier and one operation:

```ts
export const detector = defineDetector({
  apiVersion: DETECTOR_API_VERSION,
  id: "example-ecosystem",
  async scan({ root }) {
    return [];
  },
}) satisfies Detector;
```

The interface guarantees:

- `root` is an absolute repository path.
- `id` uses lowercase letters, numbers, and single hyphens.
- `scan` returns findings without a `detector` field; the engine adds it from `id`.
- Findings must be deterministic for the same repository and bundled registry.
- Repository contents are untrusted input.
- The core contract provides no network capability. Detectors should use bundled, reviewed registry data so scans remain local and reproducible.
- An incompatible `apiVersion` fails before the detector scans.

See [`examples/detectors/todo-comments.ts`](../examples/detectors/todo-comments.ts) for a complete minimal adapter.

Built-in detectors with their own pages: [Container base images](detectors/container.md), [C and C++](detectors/cpp.md), [Dart and Flutter](detectors/dart.md), [Database runtimes](detectors/database.md), [.NET](detectors/dotnet.md), [Elixir and Mix](detectors/elixir.md), [Go](detectors/go.md), [Java and Kotlin](detectors/java.md), [Kubernetes APIs](detectors/kubernetes.md), [Rust](detectors/rust.md), [Scala and sbt](detectors/scala.md), [Serverless runtimes](detectors/serverless.md), [Shell and PowerShell](detectors/shell.md), [Swift](detectors/swift.md), [Terraform](detectors/terraform.md). The Ruby, PHP, Android, and CI runner images detectors have no separate pages yet; their supported declarations and limits are in [Compatibility](compatibility/ruby.md#ruby-detector), [Compatibility](compatibility/php.md#php-detector), [Compatibility](compatibility/android.md#android-detector), and [Compatibility](compatibility/ci-runner-images.md#ci-runner-images-detector).

## Python runtime declarations

The Python detector reads `.python-version` (one concrete version per line), `runtime.txt`, `.tool-versions`, `[project].requires-python` and Poetry's Python constraint in `pyproject.toml`, `python_requires` in the `[options]` section of `setup.cfg`, and literal `python_requires` keyword arguments to `setup(...)`, `setuptools.setup(...)`, or `distutils.core.setup(...)` in `setup.py`. Python source is parsed, never executed; computed values, variable references, concatenation, interpolation, and import aliases in `setup.py` are not resolved.

It also reads `envlist` and `env_list` in the `[tox]` section of `tox.ini`, including continuation lines, factors such as `py39-unit`, and Python brace lists such as `py{39,310}-unit`. These name pinned CPython release lines. Generic `py3`, PyPy environments, substitutions, and non-Python environments are skipped. Repeated factors for the same release on one line produce one finding.

A finding points at the pin, keyword, or value's exact line. Runtime pins use the rule's severity; compatibility ranges use medium severity and report a concrete lower bound. An upper-bound-only range such as `<3.9`, an exclusion such as `!=3.9.*`, or a floating value does not establish a runtime version and produces no finding. These declarations are read in the root project and each discovered uv workspace member.

## Ruby detector layout

Moved to [Detector layouts: Ruby detector layout](detectors/authoring-layouts.md#ruby-detector-layout).

## PHP detector layout

Moved to [Detector layouts: PHP detector layout](detectors/authoring-layouts.md#php-detector-layout).

## Android detector layout

Moved to [Detector layouts: Android detector layout](detectors/authoring-layouts.md#android-detector-layout).

## CI runner images detector layout

Moved to [Detector layouts: CI runner images detector layout](detectors/authoring-layouts.md#ci-runner-images-detector-layout).

## Dart detector layout

Moved to [Detector layouts: Dart detector layout](detectors/authoring-layouts.md#dart-detector-layout).

## Database runtimes detector layout

Moved to [Detector layouts: Database runtimes detector layout](detectors/authoring-layouts.md#database-runtimes-detector-layout).

## Shell and PowerShell detector layout

Moved to [Detector layouts: Shell and PowerShell detector layout](detectors/authoring-layouts.md#shell-and-powershell-detector-layout).

## Terraform detector layout

Moved to [Detector layouts: Terraform detector layout](detectors/authoring-layouts.md#terraform-detector-layout).

## Swift detector layout

Moved to [Detector layouts: Swift detector layout](detectors/authoring-layouts.md#swift-detector-layout).

## C and C++ detector layout

Moved to [Detector layouts: C and C++ detector layout](detectors/authoring-layouts.md#c-and-c-detector-layout).

## Serverless runtimes detector layout

Moved to [Detector layouts: Serverless runtimes detector layout](detectors/authoring-layouts.md#serverless-runtimes-detector-layout).

## Start a new detector in this repository

Do not copy an existing detector by hand. Generate the skeleton from a checkout of this repository:

```bash
npm ci
npm run build
node dist/src/cli.js new-detector go-modules --ecosystem go
```

The id is the detector's stable identifier (lowercase letters, digits, and single hyphens, starting with a letter). `--ecosystem` is the registry slug and defaults to the id. The command creates eight files and nothing else:

| File | What it is for |
| --- | --- |
| `src/detectors/<id>.ts` | The detector. It imports only the public SDK, reports nothing yet, and says in its header what to do next. |
| `src/detectors/<id>/parse.ts` | A pure, bounded parser: contents in, `{ value, line }` declarations out. Its header lists the rules it keeps and a place to document the forms it deliberately does not read. |
| `tests/<id>-detector.test.ts` | The conformance suite (determinism, zero-finding, malformed input) against the generated fixtures. |
| `tests/<id>-parse.test.ts` | The invariants every parser keeps: no throw on junk, bounded input and lines, determinism, 1-based lines. |
| `tests/fixtures/<id>/` | A README with a table of cases, and `zero/` and `malformed/` fixtures to replace with real ones. |
| `docs/detectors/<id>.md` | The page that describes what the detector reads, its rules, and its limits. |

The skeleton compiles and passes its own tests with zero rules, so every later change starts from a green build. The command refuses to run outside a checkout, refuses an id or ecosystem that an existing detector, registry file, or rule-id prefix already uses (it lists every clash and the file that holds it), and writes nothing if any target file exists.

After generating:

1. **Fixtures first.** Fill `tests/fixtures/<id>/` with small repositories: one positive per declaration type, lookalike negatives (comments, unrelated keys, dynamic values), a zero-finding one, and a malformed one. Describe each in the README table.
2. **Parser.** Teach `parse.ts` to read the declarations, one form at a time, each with a test. Bound the input, never evaluate what you read, and return nothing, not an error, for forms you do not support.
3. **Rules.** Add evidence-backed rules to `registry/<id>.json` in [Ebb](https://github.com/velella-sh/ebb) ([Lifecycle rules](RULES.md), [evidence policy](../CONTRIBUTING.md#evidence-policy)), then update `@velella/ebb` here.
4. **Detector.** In `<id>.ts`, find the files, parse them, and match declarations to rules. Report an exact path and line. Add the expected findings to the conformance test.
5. **Register it.** Add the detector to `builtInDetectors` in `src/detectors/index.ts`. The generator leaves this to you on purpose, so a skeleton never changes what scans report. Whether its rules ship in the signed data bundle is decided in Ebb.
6. **Check.** `npm run check` must pass, and `npm run validate:public-repos` must still match exactly. A new detector starts non-stable in `benchmarks/thresholds.json` until the corpus has meaningful coverage ([Validation](VALIDATION.md#precision-thresholds)).

Detectors that live outside this repository use the public SDK directly, as described below; `new-detector` is for contributors to Offing itself.

## Maturity

Every built-in detector has a level (`experimental`, `beta`, or `stable`) in `benchmarks/thresholds.json`. The level is what the detector promises users. [Decision 0013](decisions/0013-detector-maturity.md) defines those promises and the evidence that earns each level. The table below is that evidence, and `earnedLevel` in `benchmarks/thresholds.ts` checks the counts. A new detector starts as `experimental`.

A promotion is a pull request that changes `level` and records the corpus run the claim rests on: date, commit, precision, recall, and the counts below. For `beta` and `stable`, the thresholds file sets `stable` to `true`, so the corpus run enforces the precision floor. A demotion is the same pull request in reverse. It is also required when a full run shows precision or recall below the floor for that level and the gap is still open 30 days later.

### Promotion gates

A detector is named by the first segment of its rule ids. Conformance is the shared harness: determinism, locations, evidence, a mandatory zero-finding fixture, and malformed input that does not throw. "Repositories with findings" counts corpus repositories with at least one expected finding for that detector. "Zero-finding repositories" counts corpus repositories of the detector's ecosystem with no expected findings. A repository is blind when a rule fixed before the scan chose it. A repository picked because it contained a finding is targeted, and the corpus entry records `selection`. Every expected finding has a `groundTruthSource` that is independent of Offing's own output.

| Gate | Experimental → beta | Beta → stable |
| --- | --- | --- |
| Conformance | Passes on positive, negative, zero, and malformed fixtures | Still passes |
| Repositories with findings | At least 8 | At least 20 |
| Expected findings | At least 15 | At least 60 |
| Zero-finding repositories | At least 2 | At least 4 |
| Blind selection | At least half of the ecosystem's corpus repositories | At least two thirds |
| Precision on the whole corpus | At least 0.95 | At least 0.95 |
| Recall on the whole corpus | At least 0.80 | At least 0.90 |
| Full corpus run on current main, recorded in the thresholds file | Within 30 days | Within 30 days, with no precision or recall regression left open |
| Detector page | `docs/detectors/` states what is and is not judged | The page still matches the detector |

Experimental → beta is the conformance suite plus the beta column. Beta → stable keeps precision at or above 0.95 on the larger corpus, and the recorded run stays inside 30 days (four weeks) with no regression left open. An `experimental` detector is still scored; a precision or recall miss does not fail its run.

Four detectors that predate this bar (`github-actions`, `nodejs`, `npm`, and `python`) keep the level they already have until the corpus catches up. The threshold test names them. Every other detector's level has to meet the column it claims.

## Unclassified references

Detectors may implement the optional `analyze` operation when they need to return both findings and references that could not be classified safely. The stable `scan` operation remains required, so existing external detectors continue to work unchanged. The engine adds the detector ID, sorts the references deterministically, and exposes them under `unclassified.count` and `unclassified.references` in `offing.scan.v1` JSON output.

The built-in GitHub Actions detector uses this metadata for full 40-character commit pins it cannot resolve. It classifies a covered action from a valid trailing version comment first, or from Offing's bundled exact SHA-to-release map when no comment is present. An unknown SHA is reported with reason `unknown-sha`; a present but unusable comment is reported with reason `invalid-version-comment`. Neither case becomes a lifecycle finding because Offing does not guess a release line.

This resolution is fully offline. The bundled map is reviewed and regenerated by a separate maintainer tool; repository scans never query GitHub or another service.

### The runtime a `setup-*` action installs

Besides the action reference itself, the GitHub Actions detector reads one runtime input: the `dotnet-version` of `actions/setup-dotnet` (decided in [#845](https://github.com/velella-sh/offing/issues/845)). It judges each version with the `dotnet` runtime rules (`dotnet.runtime.end-of-support-*`, with Microsoft's support policy as the source), so a lifecycle change is made in one place. The workflow is parsed as YAML, never evaluated.

- A literal version names a release line: `6.0.x`, `6.0`, `6.0.100`, and the SDK band `6.0.4xx` are all .NET 6.
- A multi-line value (`dotnet-version: |`) is judged per entry, and each finding points at that entry's line.
- An expression such as `${{ matrix.dotnet }}`, a floating major (`6.x`, `6`), a pre-release (`7.0.100-preview.1`), or any other form is unclassified with its file and line, never guessed.
- The `global-json-file` input, `dotnet-quality`, and the other `setup-*` actions (`setup-node`, `setup-python`, and so on) are not read. Each needs its own mapping to a lifecycle rule set; they are follow-up work, not part of this decision.

### Bun lockfile resolution and diagnostics

The `npm` detector reads lockfiles to resolve exact package versions and build dependency paths: `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, and Bun's text lockfile (`bun.lock`).

- **`bun.lock` (text)**: Parsed as JSON. Direct and transitive packages in the `packages` dictionary resolve exact versions and dependency edges, matching them against lifecycle rules.
- **`bun.lockb` (binary)**: Bun's legacy binary lockfile format is not parsed. Rather than guessing versions from manifest ranges, the binary lockfile is reported as an unclassified diagnostic reference (`bun.lockb` at line 1). Running `bun install` with Bun 1.2+ generates a text `bun.lock` file that Offing resolves.

## Declaring the files a detector reads

Moved to [Detector contracts: Declaring the files a detector reads](detectors/authoring-contracts.md#declaring-the-files-a-detector-reads).

## Registry validation

Moved to [Detector contracts: Registry validation](detectors/authoring-contracts.md#registry-validation).

## Source usage contracts

Moved to [Detector contracts: Source usage contracts](detectors/authoring-contracts.md#source-usage-contracts).

## Compatibility policy

`offing.detector.v1` remains compatible throughout the `0.1.x` line. Additive fields will be optional. A future breaking interface will use a new API version so an old adapter fails clearly instead of producing unreliable findings.

Run `npm run check` against the minimum Offing version your detector supports. The repository compatibility suite exercises an external adapter, rejects an old API version, validates registry failure modes, and runs the published example through the same engine seam used by built-in detectors.

---

Source: https://velella.sh/offing/detectors/authoring-layouts/

# Detector layouts

The layout each built-in detector follows: one pure parser per file type, rules from a bundled registry, and a documented boundary. The authoring guide starts at [Detector authoring](../DETECTORS.md).

## Ruby detector layout

The Ruby detector is a useful example of the layout a built-in detector follows. Its entry point, `src/detectors/ruby/index.ts`, finds the files, reads them, and matches each declaration to a rule. One pure parser per file type sits beside it (`parse-ruby-runtime.ts`, `parse-gemfile.ts`, `parse-gemfile-lock.ts`, and `parse-gemspec.ts`):

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file or line.
- Rules come from `registry/ruby.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- A runtime pin uses the first rule whose `vers` range contains the version. A rule whose `vers` is malformed is skipped, so it does not hide a later rule.
- A `Gemfile` gem is matched only against rules that cover every version, while a `Gemfile.lock` gem is matched against any rule for that gem name.
- Gem rules that declare usage matchers use `analyzeSourceUsage`, so those findings list the Ruby files that import or call the gem. A `require`, `load`, `gem`, or `autoload` whose argument is not a string literal is unclassified. `require_relative` is never unclassified. Qualified calls without parentheses (for example `JSON.parse text`) are not matched.

The user-facing list of supported forms and limits for this detector is in [Compatibility](../compatibility/ruby.md#ruby-detector).

## PHP detector layout

The PHP detector follows the same layout. Its entry point, `src/detectors/php/index.ts`, finds the files, reads them, and matches each declaration to a rule. One pure parser per file type sits beside it (`parse-php-runtime.ts`, `parse-composer-json.ts`, and `parse-composer-lock.ts`):

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file or line.
- Rules come from `registry/php.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- A runtime pin uses the first rule whose `vers` range contains the version. A constraint that is not a concrete version (for example `>=7.4` or `^8.2`) is skipped, and a rule whose `vers` is malformed is skipped, so neither hides a later rule.
- A `composer.json` package is matched only against rules that cover every version of the package, while a `composer.lock` package is matched against any rule whose `vers` contains the resolved version. An `abandoned` flag in the lockfile is recorded by the parser and is not itself a finding.
- Package rules that declare usage matchers use `analyzeSourceUsage`, so those findings list the `.php` files that `require` or `include` that package and the qualified calls those matchers name. A `require` or `include` whose argument is not a string literal is unclassified, as is `new $class` or `$class::method()`. Runtime end-of-life rules do not name source usages.

The user-facing list of supported forms and limits for this detector is in [Compatibility](../compatibility/php.md#php-detector).

## Android detector layout

The Android detector follows the same layout. Its entry point, `src/detectors/android/index.ts`, finds the files, reads them, and matches each declaration to a rule. Pure parsers sit beside it: `parse-build-gradle.ts` for SDK settings, `parse-settings-gradle.ts` for plugin pins, and `parse-libs-versions-toml.ts` for the version catalog. String-notation Maven dependencies in `build.gradle` and `build.gradle.kts` come from the Java detector's `parse-gradle.ts`; this detector keeps only those dependency declarations.

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file.
- Rules come from `registry/android.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- A declaration uses the first rule whose `vers` range contains the version text. A rule whose `vers` is malformed, or whose comparison throws, is skipped, so it does not hide a later rule.
- An SDK setting matches `pkg:generic/android/<kind>` (`compileSdk`, `minSdk`, `targetSdk`, `buildToolsVersion`). An Android Gradle Plugin pin, in settings or the catalog `agp` key, matches `pkg:generic/android/agp`. `org.jetbrains.kotlin.android` in settings matches `pkg:generic/android/kotlin-android`. The catalog `kotlin` key matches `pkg:generic/android/kotlin`. A string-notation dependency matches `pkg:maven/<group>/<artifact>`.
- Property references, method calls, version-catalog lookups, and `$` interpolation produce no declaration. The analysis reports no unclassified references.
- A rule that lists usage matchers uses `analyzeSourceUsage` for `.java` and `.kt` files. The bundled Play Billing rules do not list matchers, so those findings point at the declaration only.

The user-facing list of supported forms and limits for this detector is in [Compatibility](../compatibility/android.md#android-detector).

## CI runner images detector layout

The CI runner images detector follows the same layout. Its entry point, `src/detectors/ci-images/index.ts`, finds the files, reads them, and matches Azure hosted-image labels to a rule. One pure parser per file type sits beside it (`parse-gitlab-ci.ts`, `parse-circleci.ts`, and `parse-azure-pipelines.ts`):

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file.
- Rules come from `registry/ci-images.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- An Azure `pool.vmImage` label of the form `ubuntu-<version>`, `macos-<version>`, or `windows-<version>` matches `pkg:generic/azure-pipelines/<family>-image` with an `intdot` version. Every rule whose `vers` range contains that version is reported. A label with an architecture suffix, or any other shape, is not matched.
- GitLab `image` and `services` values are always unclassified. CircleCI returns orbs, dynamic values, and floating aliases as unclassified; a literal CircleCI image is not matched, because this version has no CircleCI Package URL mapping.
- `latest`, `*-latest`, variables, and template expressions produce no finding. There is no source-usage pass.

The user-facing list of supported forms and limits for this detector is in [Compatibility](../compatibility/ci-runner-images.md#ci-runner-images-detector).

## Dart detector layout

The Dart detector follows the same layout. Its entry point, `src/detectors/dart/index.ts`, finds the files, reads them, and matches each declaration to a rule. One pure parser per file type sits beside it (`parse-pubspec.ts`, `parse-pubspec-lock.ts`, and `parse-fvm.ts`):

- Rules come from `registry/dart.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- An exact version (a `pubspec.lock` package, an FVM pin, or a constraint without an operator) uses the first rule whose `vers` range contains it. A constraint with an operator is matched only against rules that cover every version of that package. A rule whose `vers` is malformed is skipped, so it does not hide a later rule.
- Rules that declare usage matchers use `analyzeSourceUsage`, so those findings list the `.dart` files that import the package and the calls those matchers name. `Function.apply` and `dart:mirrors` reflection are unclassified.

The user-facing list of supported forms and limits for this detector is in [Dart and Flutter](dart.md).

## Database runtimes detector layout

The database detector reuses what the container and Terraform detectors already parse. Its entry point, `src/detectors/database/index.ts`, finds Compose and `*.tf` files, reads them, and matches each declaration to a rule. Two pure parsers sit beside it: `parse-compose.ts` filters the shared Compose image parser to database images, and `parse-terraform.ts` reads `engine` and `engine_version` with the shared HCL scanner:

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file.
- Rules come from `registry/database.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- A full version uses the first rule whose `vers` range contains it. A partial version (`12`, `5.7`) matches a rule only when the rule contains both ends of what the partial version could mean. A rule whose `vers` is malformed is skipped, so it does not hide a later rule.
- Each product maps to one Package URL (`pkg:generic/postgresql`, `mysql`, `mariadb`, `redis`, `mongodb`). There is no source-usage pass.

The user-facing list of supported forms and limits for this detector is in [Database runtimes](database.md).

## Shell and PowerShell detector layout

The shell detector reads PowerShell declarations and the PowerShell image tags in workflow files. Its entry point, `src/detectors/shell/index.ts`, finds `*.ps1`, `*.psm1`, `*.psd1`, and `.github/workflows` files, reads them, and matches each declaration to a rule. Two pure parsers sit beside it: `parse-powershell.ts` is a bounded lexical reader for `#Requires -Version` and `PowerShellVersion`, and `parse-workflow.ts` reads `shell:` values and pinned PowerShell or Bash images from workflow YAML.

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file.
- Rules come from `registry/shell.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- Matching works as in the database detector: a full version uses the first rule whose `vers` range contains it, and a partial version matches only when the rule contains both ends of what it could mean.
- All rules use one Package URL, `pkg:generic/powershell`. Shell names and Bash images are parsed but produce no findings. There is no source-usage pass.

The user-facing list of supported forms and limits for this detector is in [Shell and PowerShell](shell.md).

## Terraform detector layout

The Terraform detector follows the same layout. Its entry point, `src/detectors/terraform/index.ts`, finds the files, reads them, and matches each declaration to a rule. One pure parser per file type sits beside it (`parse-terraform.ts`, `parse-lock.ts`, and `parse-version-files.ts`), on top of the shared bounded scanner in `hcl.ts`:

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file.
- Rules come from `registry/terraform.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- An exact version (a version file, a lock entry, or a constraint without an operator) uses the first rule whose `vers` range contains it. A `~> X.Y.Z` constraint matches a rule that contains both ends of that minor line. Any other constraint is matched only against rules that cover every version. A rule whose `vers` is malformed is skipped, so it does not hide a later rule.
- The Terraform CLI is `pkg:generic/terraform` and a provider is `pkg:generic/terraform-provider/<namespace>/<name>`. There is no source-usage pass.

The user-facing list of supported forms and limits for this detector is in [Terraform](terraform.md).

## Swift detector layout

The Swift detector follows the same layout. Its entry point, `src/detectors/swift/index.ts`, finds the files, reads them, and matches each declaration to a rule. One pure parser per file type sits beside it (`parse-swift-toolchain.ts`, `parse-package-swift.ts`, `parse-package-resolved.ts`, and `parse-xcode-project.ts`):

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file or line.
- Rules come from `registry/swift.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- An exact pin (`.xcode-version`, `.swift-version`, `swift-tools-version`, `exact:` in `Package.swift`, a `Package.resolved` version, or an app-target `IPHONEOS_DEPLOYMENT_TARGET`) uses the first rule whose `vers` range contains the version. A rule whose `vers` is malformed is skipped, so it does not hide a later rule.
- A `from:` requirement in `Package.swift` is matched only against rules that cover every version of that package. Package identity is the lowercased repository name without `.git`, matching what SwiftPM writes in `Package.resolved`.
- The iOS deployment target is read only from application targets in `project.pbxproj` (`com.apple.product-type.application`), so a library or a `platforms:` minimum in `Package.swift` never produces that finding.
- Package rules that declare usage matchers use `analyzeSourceUsage`, so those findings list the `.swift` files that `import` that module and the qualified calls those matchers name. Runtime Objective-C lookup forms (`NSClassFromString`, `Selector(…)`, and similar) are unclassified. Toolchain and App Store rules do not name source usages.

The user-facing list of supported forms and limits for this detector is in [Swift](swift.md).

## C and C++ detector layout

The C and C++ detector follows the same layout. Its entry point, `src/detectors/cpp/index.ts`, finds the files, reads them, and matches each declaration to a rule. One pure parser per manifest sits beside it (`parse-cmakelists.ts`, `parse-conan.ts`, and `parse-vcpkg.ts`):

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file.
- Rules come from `registry/cpp.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- A declaration with a version uses the first rule whose `vers` range contains that version. A rule whose `vers` is malformed, or whose comparison throws, is skipped, so it does not hide a later rule.
- A vcpkg dependency with no `version>=` matches only a rule that covers every version of that package. `cmake_minimum_required` matches `pkg:generic/cmake`. A Conan requirement matches `pkg:conan/<name>`. A vcpkg dependency matches `pkg:vcpkg/<name>`. Language standards, compiler checks, and `builtin-baseline` match the generic Package URLs named in the detector.
- Generator and module rules are not matched yet: the CMake parser does not emit those declarations. There is no source-usage pass.

The detector is supported. Its public corpus and the user-facing list of supported forms, lifecycle data sources, and limits are in [C and C++](cpp.md) and [Compatibility](../compatibility/cpp.md#c-and-c-detector).

## Serverless runtimes detector layout

The Serverless runtimes detector follows the same layout. Its entry point, `src/detectors/serverless/index.ts`, finds the files, reads them, and matches each literal runtime identifier to a rule. One pure parser per file type sits beside it (`parse-template.ts`, `parse-serverless-yml.ts`, and `parse-tf.ts`):

- A parser returns nothing, not an error, for a form it does not support, and never returns part of a malformed file.
- Rules come from `registry/serverless.json`, loaded through the bundled data. The detector takes a rule loader so tests can supply their own rules.
- Each literal identifier is tried against `pkg:generic/aws-lambda-runtime/<id>` and `pkg:generic/google-cloud-functions-runtime/<id>`. The first rule whose VERS range contains the identifier wins. A rule whose VERS is malformed is skipped, so it does not hide a later rule.
- CloudFormation tags (`!Ref`, `!Sub`), Serverless `${…}` interpolations, Terraform `var` / `local` / interpolation values, and floating aliases such as `latest` produce no declaration.
- There is no source-usage pass: a runtime finding points at the declaration only.

The user-facing list of supported forms and limits for this detector is in [Serverless runtimes](serverless.md).

---

Source: https://velella.sh/offing/detectors/authoring-contracts/

# Detector contracts

The contracts around a detector: the files it declares it reads, the registry envelope it validates, and the source-usage helper it can call. The authoring guide starts at [Detector authoring](../DETECTORS.md).

## Declaring the files a detector reads

A detector may declare, in one place, which repository files its `scan` reads. The optional `inputs` field on `Detector` (added to the `offing.detector.v1` interface without changing anything that exists) has four parts, all relative to the scanned root with forward slashes:

| Field | Meaning |
| --- | --- |
| `fileNames` | Exact base names at any depth, case-insensitive; `*` matches any run of characters (`requirements*.txt`, `*.Dockerfile`). |
| `extensions` | Base-name endings, including the dot (`.csproj`). |
| `directories` | Directories, at the root or below any directory, all of whose files may be read (`.github/workflows`). |
| `sourceExtensions` | Source files read to map usage of a deprecated API (`.ts`, `.cs`). |

```ts
readonly inputs: DetectorInputs = {
  fileNames: ["go.mod", "go.work"],
  sourceExtensions: [".go"],
};
```

Every built-in detector declares it, and a test fails if one does not. `declaredInputsCheck` (`offing/conformance`, from `src/conformance/checks/inputs.ts`) scans a fixture while recording every file whose contents the scan opens, and fails naming each file outside the declaration:

```text
Detector "leaky" violated the "declared inputs" guarantee for fixture "leak": read "secrets/token.txt", which its inputs do not declare
```

Listing a directory or testing that a path exists is not a read, and files outside the scanned root (the bundled rules) are ignored. A detector that omits `inputs` makes no promise and passes the check. The declaration is what a tool needs to fetch only the files a detector reads; keep it as narrow as the detector's real behavior, and widen it in the same change that makes the detector read something new.

## Detector limits

`DETECTOR_LIMITS` (exported from `@velella/offing/sdk`, typed as `DetectorLimits`) is the one place the bounds of `offing.detector.v1` are written down. A finding must not come from a file larger than `maximumFileBytes` (1,000,000), from a path more than `maximumDirectoryDepth` (32) directories below the root, or from a vendored or generated directory in `vendoredDirectories` (`node_modules`, `vendor`, `dist`, `build`, `target`, `.venv`, `venv`). `boundsCheck` reads the same constant, so the documented limit and the enforced limit cannot drift. A detector may be stricter, never looser.

Together with the contract above, a detector's typed surface is: `inputs` (the files it reads), `DetectorFinding` (what it reports, with an optional `confidence` the engine derives when omitted), and `DETECTOR_LIMITS` (how far it may look). Start a new one with `new-detector`, which generates a skeleton that already satisfies all three.

## Registry validation

The bundled registries use the shared `ebb.registry.v2` format, keyed by Package URL and version range with provenance for every rule. See [Lifecycle rules](../RULES.md) for the format, the evidence policy, and how to write a rule. The v2 loader is internal to the bundled detectors for now; the public SDK validates the v1-style envelope below, so detectors outside this repository keep working unchanged.

Registry files for external detectors use a versioned envelope:

```json
{
  "schemaVersion": "example.registry.v1",
  "rules": []
}
```

Use `validateRegistry` for the envelope and a detector-owned type guard for each rule:

```ts
const registry = validateRegistry(JSON.parse(contents), {
  schemaVersion: "example.registry.v1",
  isRule: (value): value is ExampleRule =>
    isDeprecationRule(value) && typeof value.package === "string",
});
```

Validation rejects a missing or unexpected schema version, a non-array `rules` value, and the first invalid rule with its array index. `isDeprecationRule` validates the fields shared by every Offing lifecycle rule.

Rules may include optional migration guidance so `offing context` can produce ecosystem-specific packets without hard-coding detector knowledge in the CLI:

```json
{
  "migration": {
    "constraints": ["Preserve observable behavior."],
    "steps": [
      {
        "id": "replace-declaration",
        "title": "Replace the declaration",
        "instructions": "Move to the supported replacement.",
        "targets": "declaration"
      }
    ],
    "verification": [
      { "command": "npm test", "purpose": "Run the repository tests." }
    ]
  }
}
```

Step targets are `declaration`, `usages`, or `all`. The packet module resolves those targets to exact repository paths. Step IDs must be unique within a rule, and constraints, steps, and verification commands must all be non-empty. External detectors without migration guidance receive deterministic generic fallback steps.

## Source usage contracts

Detectors can enrich findings with concrete repository usages through the public `analyzeSourceUsage` helper. Pass all matched rules in one batch so the repository is traversed once:

```ts
import {
  analyzeSourceUsage,
  type SourceUsageContract,
} from "@velella/offing/sdk";

const contracts: SourceUsageContract[] = [{
  id: "legacy-client",
  matchers: [
    { kind: "import", language: "typescript", module: "legacy-client" },
    {
      kind: "call",
      language: "typescript",
      module: "legacy-client",
      targets: ["default", "get"],
    },
  ],
}];

const analyses = await analyzeSourceUsage(root, contracts);
```

Import and call matchers resolve common aliases in JavaScript, TypeScript, and Python. Go supports import and call matchers by import path. Java and Kotlin support import matchers only (`language: "java"` for `.java` files and `"kotlin"` for `.kt` files): `module` is a package or class name, an import of it or of anything below it matches (`import static` and wildcard imports included), and calls through the imported names are not mapped. Ruby supports import and call matchers (`language: "ruby"` for `.rb`, `.rake`, and `.ru` files): `module` is a require path, a literal `require`, `load`, `gem`, or `autoload` of that path (or a path under it) is an import, and a call target is a qualified call such as `JSON.parse(` (parentheses required). An assignment `Parser = JSON` makes `Parser.parse(` the same call. A dynamic `require`/`load`/`gem`/`autoload` argument is reported as unclassified instead of being guessed; `require_relative` is not. Configuration-key matchers support Python settings plus JSON, YAML, TOML, and INI-style files, and can optionally require a value fragment. Results include exact locations, excerpts, and a deterministic `none`, `low`, `medium`, or `high` migration-impact estimate. Keep matchers narrow: a lifecycle finding may safely have zero source usages, but an ambiguous match should not be reported as evidence.

---

Source: https://velella.sh/offing/IMPORTERS/

# Lifecycle importers

An importer reads one authoritative, machine-readable source and drafts [lifecycle rules](RULES.md) from it, so the rules grow from sources instead of being typed in by hand. Importers are maintainer tooling: scans never run them and never use the network. The decision behind them is [Decision 0005](decisions/0005-lifecycle-importers.md).

The importers moved with the rules to [Ebb](https://github.com/velella-sh/ebb), the open lifecycle dataset Offing reads. How they work, how to run one, and how to add a source are in Ebb's [importers guide](https://github.com/velella-sh/ebb/blob/main/docs/IMPORTERS.md).

---

Source: https://velella.sh/offing/CLAUDE_PLUGIN/

# Offing plugin for Claude

Offing's Claude plugin packages the canonical lifecycle Skill with the same version-pinned local MCP server used by the Codex adapter. It does not fork detectors, migration logic, or verification behavior.

## Requirements

- Claude Code 2.1.292 or newer for the one-command marketplace install shown below.
- Node.js 22 or newer for the local Offing MCP server.

## Install

Install directly from Offing's GitHub marketplace:

```sh
claude plugin install offing --marketplace velella-sh/offing
```

For older Claude Code versions, add the marketplace and install in two steps:

```sh
claude plugin marketplace add velella-sh/offing
claude plugin install offing@offing
```

Choose a scope when needed:

```sh
claude plugin install offing@offing --scope user
claude plugin install offing@offing --scope project
claude plugin install offing@offing --scope local
```

User scope enables Offing for you on this machine. Project scope records it in the repository's `.claude/settings.json` for collaborators. Local scope enables it only for you in the current repository.

For development without installing, load the adapter directory for one session:

```sh
claude --plugin-dir ./plugins/claude
```

## Confirm

```sh
claude plugin list
claude plugin details offing
```

The installed plugin exposes the `offing` Skill and the local `offing` MCP server. Scan, list, explain, context, and verify behavior is checked against the Codex adapter by `npm run eval:plugins`.

## Dependency guard

The plugin includes a `PostToolUse` hook that runs after Claude Code writes or edits a file. When the edit adds a dependency that Offing's lifecycle rules mark as deprecated, Claude gets a warning with the evidence and the replacement, and you see a one-line notice.

What it looks at:

- `package.json`: dependencies added or whose version changed.
- `requirements*.txt`, `constraints*.txt`, and `pyproject.toml`: added requirements.
- GitHub workflows and `action.yml`: added `uses:` references that carry a version tag, such as `actions/checkout@v4`.

Only what the edit added is checked, so existing dependencies never produce repeated warnings. For a range such as `^2.88.2` the lower bound is checked.

```text
Offing: pkg:npm/request@2.88.2 — request is deprecated (high, deprecated).
The package is fully deprecated and no new changes are expected.
Replacement: Native fetch or a maintained HTTP client.
Evidence: https://www.npmjs.com/package/request
```

Behavior you can rely on:

- It never blocks and never edits files. The warning explains the problem and cites its sources, and you or Claude decide what to do.
- It checks with `offing check`, which runs locally against the lifecycle rules bundled in the pinned release. No repository content leaves your machine.
- A package with no rule produces no output. That is absence of evidence, not a safety claim.
- If the check cannot run (for example, offline on the first use), the hook says so instead of staying silent, and the edit is unaffected. An unreadable payload exits quietly.

The hook script is generated from `integrations/dependency-guard/guard.mjs`, which the Codex integration shares. It uses the same pinned package as the MCP server (`offing@<version>`). Set `OFFING_CHECK_COMMAND` to use another Offing command, for example a local build.

## Update

```sh
claude plugin update offing@offing
```

The marketplace has automatic updates off by default. You can manage that setting from the Marketplaces tab in `/plugin`.

## Disable and re-enable

```sh
claude plugin disable offing@offing
claude plugin enable offing@offing
```

Disabling stops the Skill and MCP server from loading but keeps the installed files and settings.

## Remove

```sh
claude plugin uninstall offing@offing
```

If it was installed at project scope, add `--scope project`. To remove the marketplace after uninstalling its plugin:

```sh
claude plugin marketplace remove offing
```

## Public directory submission

The public Claude directory submission uses:

- Repository: `https://github.com/velella-sh/offing`
- Plugin path: `plugins/claude`
- Tracked branch: `main`
- Submission type: Plugin bundle

The submitter must connect a GitHub account with push access, answer Anthropic's data-handling and compliance questions, and submit from the [Claude developer portal](https://claude.ai/directory/manage). The local package is prepared for that review with a manifest, README, Apache-2.0 license, exact npm runtime pin, strict Claude validation, and the repository security/evaluation evidence in [Plugin host evaluation](PLUGIN_EVALS.md).

---

Source: https://velella.sh/offing/CODEX_PLUGIN/

# Codex plugin installation and management

Offing ships as a portable Agent Plugins package with a Codex compatibility manifest. It bundles the canonical Offing Skill and a local, read-only stdio MCP server. No Offing account or hosted Offing service is required.

## Requirements

- Codex CLI or Codex in the ChatGPT desktop app with plugin support.
- Node.js 22 or newer.
- Access to the npm registry the first time the pinned Offing runtime is launched.

## Dependency guard

The plugin ships a `PostToolUse` hook (`hooks/hooks.json`, matched to `apply_patch`) and the Skill carries the same instruction for sessions where hooks are off. When a patch adds a dependency that Offing's lifecycle rules mark as deprecated, Codex receives a warning with the evidence and the replacement, and you see a one-line notice.

It reads the patch Codex applied and checks only what the patch **added or changed**, in `package.json`, `requirements*.txt`, `constraints*.txt`, `pyproject.toml`, GitHub workflows, and `action.yml`. Existing dependencies never produce repeated warnings.

```text
Offing: pkg:npm/request@2.88.2 — request is deprecated (high, deprecated).
The package is fully deprecated and no new changes are expected.
Replacement: Native fetch or a maintained HTTP client.
Evidence: https://www.npmjs.com/package/request
```

- **Trust the hook first.** Codex does not run plugin hooks until you review them: enabling the plugin does not trust its hooks. Run `/hooks` in Codex and trust the Offing hook. Trust is tied to the hook's contents, so a plugin update asks again.
- **It never blocks or edits files.** It warns and cites sources; you and Codex decide what to do. If the check cannot run, the hook says so instead of staying silent, and the patch is unaffected.
- **It is local.** It runs `offing check` from the same pinned release as the MCP server; no repository content leaves your machine. A package with no rule produces no output, which is absence of evidence, not a safety claim.
- **If hooks are off** (`[features] hooks = false`) or you do not trust the hook, the Skill still tells Codex to call the `check_dependency` tool before adding a dependency.

The script is generated from `integrations/dependency-guard/guard.mjs`, shared with the Claude plugin. Set `OFFING_CHECK_COMMAND` to use another Offing command, for example a local build.

## Install from this repository

The repository marketplace is discovered from `.agents/plugins/marketplace.json` and exposes the package as `offing@offing-codex`:

```sh
codex plugin add offing@offing-codex
```

For a remote checkout, add or refresh the repository marketplace first:

```sh
codex plugin marketplace add velella-sh/offing --ref main
codex plugin add offing@offing-codex
```

Restart the current Codex session after installation so the packaged Skill and MCP server are discovered together.

## Verify the installation

List the installed plugin:

```sh
codex plugin list --json
```

Then ask Codex to run the packaged workflow:

```text
Scan this repository for supported lifecycle risks.
Explain the highest-severity Offing finding.
Create migration context for this deprecation.
Verify that the finding is gone after my change.
```

The installed workflow must expose scan, list, explain, context, and verify. Suggested migration commands are returned as guidance and are never executed by Offing.

Maintainers can run the same end-to-end check against an installed cache path:

```sh
npm run validate:codex-plugin -- --plugin-root /absolute/path/to/installed/offing
```

## Update

For the repo-local marketplace, reinstall the plugin so the cache is rebuilt from the current package:

```sh
codex plugin remove offing@offing-codex
codex plugin add offing@offing-codex
```

For a Git-backed marketplace added from `velella-sh/offing`, refresh its snapshot before reinstalling:

```sh
codex plugin marketplace upgrade offing-codex
```

The package pins its MCP runtime to the same semantic version as the plugin manifest, preventing a silent mix of plugin metadata and runtime versions.

## Remove

```sh
codex plugin remove offing@offing-codex
```

If the repository marketplace was added explicitly and is no longer needed:

```sh
codex plugin marketplace remove offing-codex
```

Removal deletes the installed plugin cache. It does not modify the repository being scanned.

## Local data and permissions

- The MCP process runs locally over stdio and reads only repository paths authorized by the host.
- Offing does not upload repository contents, require credentials, edit files, run migration commands, or open a network listener.
- Tool results can contain repository paths and short source excerpts and are returned to the Codex host.
- The host remains responsible for filesystem approvals and any later edits an agent makes.

See [Privacy](PRIVACY.md) for the complete data boundary and [Codex submission](CODEX_SUBMISSION.md) for public-directory review status.

---

Source: https://velella.sh/offing/CHANGELOG/

Every release is listed below, newest first. Each heading has a stable anchor, so a link such as [`CHANGELOG.html#v0.1.0`](#v0.1.0) keeps working after later releases. The repository's [CHANGELOG.md](https://github.com/velella-sh/offing/blob/main/CHANGELOG.md) is the source of truth; the [GitHub releases](https://github.com/velella-sh/offing/releases) carry the published notes.

<a id="unreleased"></a>

## Unreleased

<a id="v0.1.1"></a>

## 0.1.1 - 2026-11-12

- Release the Offing package and Action with the post-publish checks fixed to use the `@velella/offing` package name. The package contents are the same as 0.1.0.

<a id="v0.1.0"></a>

## 0.1.0 - 2026-11-11

- First release of Offing.

---

Source: https://velella.sh/offing/RELEASING/

# Releasing Offing

Any maintainer can cut a release by following this page. A release publishes four things that must agree on one version: the npm package `offing`, the GitHub Action (`velella-sh/offing@vX.Y.Z`), the generated Claude and Codex plugin packages, and the bundled lifecycle registries inside the package. Publishing needs maintainer accounts, so releases are `lane: maintainer` work.

## Before you start

- You are on an up-to-date `main` with a clean working tree, and CI on `main` is green.
- You can publish to the `offing` package on npm and push tags to the repository.
- Choose the version. Patch for fixes and rule data, minor for new detectors, commands, or output fields, and a major version only for a breaking change to an output schema or the detector SDK.

## Gates

Every gate must pass on the commit you will tag. None of them is optional.

| Gate | Command | What it proves |
|---|---|---|
| Full check | `npm run check` | Build, the Action bundle compiles, all tests including coverage floors in CI, plugin packages are in sync, plugin evals. This is what CI and `npm publish` (through `prepack`) run. |
| Coverage floors | `npm run test:coverage` | Lines, branches, and functions stay above the floors in `package.json`. |
| Public corpus | `npm run validate:public-repos` | Exact findings on every pinned public repository, and each detector's precision above its floor in `benchmarks/thresholds.json`. Needs network. |
| Package contents | `npm pack --dry-run` | Only `dist/src`, `examples`, `schemas`, and `skills` ship. The rules come from the `@velella/ebb` dependency. |
| Reproducible package | `npm run check:reproducible` | Two clean builds of the same commit pack to byte-identical npm tarballs. CI records the tarball hash on Linux, Windows, and macOS and fails `ci-ok` when the runners disagree; the release workflow runs the local check and fails on a mismatch. |

The last weekly run of the corpus workflow should also be green. If either is red, fix or explain it before tagging.

## Action bundles on release tags

The GitHub Action runs `dist/action/index.js`, one compiled bundle. `main` does not carry it: every merge rewrote the one minified line, so any two pull requests conflicted on it. Release tags still need the file, so the release chain builds it where it is needed:

- A push to `main` that changes the version in `package.json` runs the *Release* workflow's `action-bundle` job. It builds `dist/action`, commits it on the branch `release/vX.Y.Z` (one commit on top of the release commit), and prints the tagging commands below.
- The release tag points at that branch tip, not at a commit on `main`. The tag is created once and never moves, so `uses: velella-sh/offing@vX.Y.Z` keeps working for everyone who pinned it.
- The Release chain's `npm-publish` job ([`release.yml`](../.github/workflows/release.yml), guard in [`check-release-tip.sh`](../.github/scripts/check-release-tip.sh)) refuses a tag that is not exactly that branch tip, or whose parent is not on `main`, or that changes anything besides `dist/action/`. `prepack` then rebuilds the bundle on the tagged commit and fails when the committed copy differs, so a stale or hand-edited bundle cannot be published.
- The npm tarball is unaffected: `package.json`'s `files` list does not include `dist/action`, so the tarball is byte-identical to one packed from the release commit on `main`.

The tradeoff is that a release tag no longer points into `main` history, and its commit is not on `main`. The alternative, moving the tag onto a rebuilt commit after publishing, was rejected: the tag would move under users who already pinned it, the publish workflow would re-trigger, and every other release job (binaries, container, quickstart, major tag) selects the release by `git tag --points-at` on the commit it checked out.

## Verifying a published release

The package is reproducible: rebuilding the tagged commit packs the same tarball, byte for byte, so anyone can check that a published version was built from its source. On any machine with Node.js 22 or newer:

```bash
git clone --branch vX.Y.Z --depth 1 https://github.com/velella-sh/offing
cd offing
npm ci && npm run check:reproducible
```

The clone is the release branch tip: `git log -1` shows the commit that adds `dist/action/`, whose parent is the release commit on `main`. The printed SHA-256 must match the tarball npm serves for the version, which you can download and hash separately with `npm pack offing@X.Y.Z` in an empty directory and `shasum -a 256 offing-X.Y.Z.tgz`. npm normalizes the tar metadata (uid, gid, and mtimes) when packing, so the bytes depend on the shipped file contents only; a mismatch means the build is nondeterministic, and the check keeps both tarballs for diffing.

Two builds on one machine share every host-dependent step, so CI also compares builds made elsewhere: the Linux, Windows, and macOS jobs pack the same commit with `npm run record:reproducible -- <file>` and `ci-ok` runs [`compare-build-hashes.mjs`](../tools/compare-build-hashes.mjs) on the records. A path, line ending, or file-ordering difference that only one host has fails the pull request or merge-queue run.

An installed package carries `dist/src/release-manifest.json`, generated from the packed file list at publish time. `offing verify` checks every listed file offline and fails on a changed one; see [CLI](CLI.md#verify). It reports the npm registry signature and provenance attestation as unchecked because those live on the registry: `npm audit signatures` verifies them when the network is available.

### SLSA provenance

Every release channel publishes signed build provenance, and the release chain runs
[`slsa-verifier`](https://github.com/slsa-framework/slsa-verifier) against each channel before the run
succeeds. A release that loses or mismatches its provenance fails instead of shipping.

| Channel | Builder | SLSA Build level |
|---|---|---|
| Standalone binaries | [`generator_generic_slsa3.yml`](https://github.com/slsa-framework/slsa-github-generator/blob/main/.github/workflows/generator_generic_slsa3.yml) in an isolated job | 3 |
| Container image | [`generator_container_slsa3.yml`](https://github.com/slsa-framework/slsa-github-generator/blob/main/.github/workflows/generator_container_slsa3.yml) in an isolated job | 3 |
| npm package | npm trusted publishing on a GitHub-hosted runner | 2 |

npm's attestation is signed and verifiable, but the build and the publish run in the same
tenant-controlled job, which is Build L2. Reaching Build L3 for npm needs the retired Node.js SLSA
builder and a long-lived npm token, which would replace trusted publishing; that trade is not made
here. The `verify-provenance` stage of the npm publish fails the release when the attestation is
missing or does not match the published tarball.

Verify the binaries and the container image with `slsa-verifier` (v2.7.1 or newer):

```bash
# Standalone binaries and their multiple.intoto.jsonl provenance
mkdir release
gh release download vX.Y.Z --pattern 'multiple.intoto.jsonl' --pattern 'offing-*' --dir release
find release -name '*.sigstore.json' -delete
slsa-verifier verify-artifact release/offing-* \
  --provenance-path release/multiple.intoto.jsonl \
  --source-uri github.com/velella-sh/offing \
  --source-tag vX.Y.Z \
  --builder-id https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v2.1.0

# Container image: the provenance is stored next to the image in ghcr.io
image=ghcr.io/velella-sh/offing
digest="$(docker buildx imagetools inspect "$image:X.Y.Z" | sed -n 's/^Digest: *//p')"
slsa-verifier verify-image "$image@$digest" \
  --source-uri github.com/velella-sh/offing \
  --source-tag vX.Y.Z \
  --builder-id https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v2.1.0
```

Verify the npm package against the attestation the registry serves. npm's provenance records the
workflow ref, but `verify-npm-package` does not support `--source-tag`; it checks the repository with
`--source-uri` and prints the source commit for comparison with `git rev-parse vX.Y.Z`:

```bash
version=X.Y.Z
curl -Sso "offing-$version.tgz" "$(npm view "offing@$version" dist.tarball)"
curl -Sso attestations.json "$(npm view "offing@$version" --json | jq -r '.dist.attestations.url')"
SLSA_VERIFIER_EXPERIMENTAL=1 slsa-verifier verify-npm-package "offing-$version.tgz" \
  --attestations-path attestations.json \
  --builder-id https://github.com/actions/runner/github-hosted \
  --package-name @velella/offing \
  --package-version "$version" \
  --source-uri github.com/velella-sh/offing
```

## One-time npm setup

Trusted publishing needs the package to name its publisher. On npmjs.com, open the `offing` package, then Settings, then Trusted Publisher, choose GitHub Actions, and enter organization or user `velella-sh`, repository `offing`, and workflow filename `release.yml` (leave the environment empty). npm matches the workflow that runs `npm publish`, which is `release.yml` itself. If an older trusted-publisher entry still names `publish.yml`, add `release.yml` as a second entry (a package may have more than one), publish once successfully, then delete the `publish.yml` entry. Once a release has published this way, set the package's publishing access to "Require two-factor authentication and disallow tokens" so that only this workflow can publish. To rehearse the path before a real release, set `package.json` to a pre-release version such as `X.Y.Z-rc.1` through a pull request and tag its release branch.

## Steps

1. **Update the changelog.** Draft the entries from conventional commits with `npm run release:notes` (or run the *Release notes* workflow, which uploads the same text). Pull requests add their entries as fragments in `changes/`; the command below moves those fragments into the section, followed by the commit-derived bullets:

   ```bash
   node dist/tools/changelog.js --write X.Y.Z --date YYYY-MM-DD
   ```

   Only `feat`, `fix`, and breaking commits become entries; `docs`, `test`, `ci`, and `chore` commits are left out. The command moves the hand-written `Unreleased` bullets and the `changes/` fragments into a new `## X.Y.Z - YYYY-MM-DD` section, appends the generated bullets, deletes the fragments, and leaves an empty `## Unreleased` above. Read the section, remove duplicates, and make each bullet a clear imperative sentence.
2. **Bump the version.** Run `npm version X.Y.Z --no-git-tag-version`, set the same version in `src/version.ts` and `server.json`, then regenerate everything derived from it:

   ```bash
   npm run build:plugins
   ```

   This updates the plugin manifests and `.mcp.json` pins under `plugins/` and `.claude-plugin/marketplace.json`, and the plugin packages. Never edit those generated files by hand. The Action bundle is not committed here: the Release workflow builds it onto the release branch after this pull request merges (see [Action bundles on release tags](#action-bundles-on-release-tags)).
3. **Update the version in the docs and examples.** The README and `docs/GITHUB_ACTION.md` show `velella-sh/offing@vX.Y.Z`; update them to the new tag. The host setups under `examples/agents/` pin `offing@X.Y.Z` (and the Gemini extension its `version`); a test fails until they match `package.json`. `server.json` (the MCP Registry description) carries the version twice; bump it with `package.json`, and a test fails until they agree.
4. **Run the gates** above on the result, then commit as `chore: release X.Y.Z` through a pull request. Merge it once CI is green.
5. **Tag the release branch.** Merging the release pull request starts the *Release* workflow's `action-bundle` job, which commits the compiled bundle on `release/vX.Y.Z` and prints the commands below in its job summary. When it has finished, tag that branch tip:

   ```bash
   git fetch origin release/vX.Y.Z
   git tag -a vX.Y.Z -m "vX.Y.Z" FETCH_HEAD
   git push origin vX.Y.Z
   ```

   Tagging the merge commit on `main` does not work any more: that tree has no bundle, and the Release chain's npm stage refuses the tag with a message that says so. If the job failed, re-run it from the Actions tab; it does nothing when the branch already exists.

6. **Publish to npm.** Pushing the tag in step 5 starts the *Release* workflow's one chain: the `npm-publish` job (in `release.yml` itself, so OpenSSF Scorecard sees the publish step) publishes with npm trusted publishing (no stored token, provenance attestation), then the same run continues through binaries and the signed SBOM, container, major tag, and smoke. It refuses a tag that does not match the version in `package.json`, a tag that is not the `release/vX.Y.Z` branch tip, or a release branch commit that changes anything besides `dist/action/`, and `prepack` runs `npm run check` again, so a broken tree or a stale bundle cannot be published. A pre-release tag such as `vX.Y.Z-rc.1` is published under the `next` tag, so `latest` does not move. After publishing, a job installs the published version on a fresh machine and runs `--help`, `capabilities`, and a scan of `tests/fixtures/smoke` (`.github/scripts/smoke.mjs`); a package that installs but does not work fails the run. A `verify-provenance` job then checks the npm attestation with `slsa-verifier`, so a missing or mismatched attestation fails the release. A `verify-provenance` job then checks the npm attestation with `slsa-verifier`, so a missing or mismatched attestation fails the release. If a later stage fails, re-run only the failed jobs of that Release run — successful stages (including npm publish) are left alone. Watch the run in the Actions tab, then confirm with `npm view offing version` and run `npx @velella/offing@X.Y.Z --help` in an empty directory. To publish by hand instead (for example if the workflow is unavailable), run `npm publish` from the tagged commit; it will have no provenance.
7. **Publish to the MCP Registry.** The registry lists the server for MCP clients and tools that look for one. It holds only the metadata in `server.json`, which points at the npm package, so publish it **after** step 6, when `npm view offing version` shows the new version (the registry checks the package on npm, so it must exist there first). This is automated: the same Release run's `publish-npm` stage runs, after `npm-publish`, the `registry` job of [`publish.yml`](../.github/workflows/publish.yml) after its npm smoke job. It refuses a tag that does not match `server.json`, skips pre-release tags, then publishes `server.json` through the `mcp-publisher` tool with a GitHub OIDC login — no stored secret, since the job's OIDC identity names this repository. The binary it downloads is pinned to release 1.8.6 and checked against the release's SHA-256; the pin is only moved after a maintainer reviews the new release first.

   A published registry version cannot be changed, so check that `server.json` carries the version you just released first — the workflow refuses otherwise. Then confirm it is the latest:

   ```bash
   curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=offing"
   ```

   The response lists `io.github.velella-sh/offing` with the new `version`. The name is owned by the `arminazimi` GitHub account, and `package.json`'s `mcpName` ties the npm package to it.

   Other MCP directories need no step per release (recorded with their status in [MCP.md](MCP.md#where-the-server-is-listed)). Versions sync from the official Registry automatically in the directories that ingest it — the GitHub MCP Registry and the VS Code / Copilot gallery once its onboarding lands, and PulseMCP when its submissions reopen. The Docker MCP Catalog pins a commit in `servers/offing/server.yaml` of `docker/mcp-registry`, but only follow that entry when a release contains something a catalog user should see (a new tool, a new detector ecosystem); the npm package is what the pinned commit builds, so old tags keep working.

   **Manual fallback.** Keep this until the automation has succeeded on a real release from start to finish. If the `registry` job fails or is unavailable, run it by hand from the tagged commit after `npm view offing version` shows the new version:

   ```bash
   mcp-publisher login github   # approve the device code in a browser as the arminazimi account
   mcp-publisher publish
   ```
8. **Check the GitHub release body.** After the binaries create the release, the Release workflow writes the matching section of `CHANGELOG.md` at the tag, an install line, binary verification instructions, and a tagged changelog link. No copy-and-paste is needed. A pre-release without its own section gets a short pre-release note. Edit by hand only to add a release-specific note: reruns preserve every non-placeholder body. To preview notes, run *Release notes body* with `release_tag` and leave `dry_run` on. To explicitly replace an existing body, turn `dry_run` off and set `force` to true; with `force` false a hand-written body is preserved.
9. **Move the major tag** only if the project publishes one (for example `v1`), as a force-updated lightweight tag pointing at the new release. Do not move it for a pre-1.0 version. The same Release run does this after npm publish succeeds, for stable tags from `v1.0.0` on: the decision is in `.github/scripts/major-tag.mjs` (unit-tested), the tag only moves forward, and a pre-release or `0.x` tag changes nothing. To see what it would do for a tag without pushing anything, run the `Release` workflow by hand with `release_tag` set (a manual run with `release_tag` is always a dry run for the tag). To exercise every release stage without publishing, run it with `dry_run` on.
10. **Package the plugins.** For Codex, `npm run package:codex-plugin` writes `artifacts/offing-codex-plugin-<version>.zip`; follow [Codex submission](CODEX_SUBMISSION.md) to submit it. The Claude plugin is served from the repository marketplace, so the merged change in step 4 is its release; see [Claude plugin](CLAUDE_PLUGIN.md).
11. **Announce** only after the npm package, tag, and release are live.

## Standalone binaries

Each stable or pre-release tag also produces binaries that need no Node.js, for Linux (x64, arm64), macOS (x64, arm64), and Windows (x64). The `build-binaries` and `publish-binaries` stages in [`release.yml`](../.github/workflows/release.yml) run in the same Release chain after the npm stage succeeds, so they build the commit that passed every gate. Nothing needs to be done by hand.

- **What they are.** [`build-sea.mjs`](../.github/scripts/build-sea.mjs) stages exactly the files `npm pack` would publish, installs the production dependencies from `package-lock.json`, and embeds them in a Node.js [single executable application](https://nodejs.org/api/single-executable-applications.html) (built with `node --build-sea`, so the build runner uses Node.js 26). On first run, [`sea-boot.cjs`](../.github/scripts/sea-boot.cjs) unpacks the embedded package into the user's cache directory (`~/.cache/offing`, `~/Library/Caches/offing`, or `%LOCALAPPDATA%\offing`; `OFFING_SEA_CACHE` overrides it) and runs the same CLI as the npm package. Scans still use no network.
- **Gate.** Every binary runs `--help`, `capabilities`, and a scan of `tests/fixtures/smoke` (`.github/scripts/smoke.mjs`) before it is uploaded; on Linux and macOS this runs with `PATH=/usr/bin:/bin`, so a binary that secretly needs Node.js fails the release.
- **What is attached.** The release gets `offing-<version>-<os>-<arch>` files (`.exe` on Windows), `SHA256SUMS`, a keyless Sigstore (cosign) `.sigstore.json` bundle for each of those files, and an SLSA `multiple.intoto.jsonl` provenance file. The same stage runs `slsa-verifier` against the uploaded bytes and fails the run if the provenance does not match; the public command is in [SLSA provenance](#slsa-provenance). Each binary also carries a GitHub build provenance attestation: `gh attestation verify offing-<version>-<os>-<arch> --repo velella-sh/offing`, or compare `sha256sum -c SHA256SUMS`. To check a Sigstore signature by hand:

  ```bash
  cosign verify-blob \
    --bundle offing-<version>-<os>-<arch>.sigstore.json \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --certificate-identity-regexp '^https://github\.com/velella-sh/offing/\.github/workflows/release-publish-binaries\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-.+)?$' \
    offing-<version>-<os>-<arch>
  ```

  Binaries from releases up to and including v0.7.2 were signed with older identities: the monolithic `https://github.com/velella-sh/offing/.github/workflows/release.yml@refs/heads/main`, and (after the stage split, while post-publish still ran via `workflow_run` on the default branch) `https://github.com/velella-sh/offing/.github/workflows/release-publish-binaries.yml@refs/heads/main`. Verify those with `--certificate-identity-regexp '^https://github\.com/velella-sh/offing/\.github/workflows/release\.yml@refs/heads/main$'` or `'^https://github\.com/velella-sh/offing/\.github/workflows/release-publish-binaries\.yml@refs/heads/main$'` respectively. v0.7.0, v0.6.1, and v0.6.0 were cut before signing existed and carry signatures added later by the backfill described below.

  If no release exists for the tag yet, the job creates one; the following notes stage replaces its placeholder automatically as described in step 8.
- **macOS.** The binaries are signed ad hoc, not notarized. Downloaded with `curl` or `gh release download` they run as they are; a browser download is quarantined, and `xattr -d com.apple.quarantine <file>` clears it.
- **If a binary job fails.** The npm package is already published and is not affected. Fix the cause, then re-run the failed jobs of that same `Release` workflow run; `gh release upload --clobber` replaces files that were already attached.
- **Trying it before a release.** From a built checkout with Node.js 25.5 or newer, `node .github/scripts/build-sea.mjs offing-test`, then `node .github/scripts/smoke.mjs tests/fixtures/smoke -- ./offing-test` (on macOS run `codesign --force --sign - offing-test` first). Use an official Node.js build; some distributions (Homebrew's, for one) are built without single-executable support.

### SBOM

Every release attaches `sbom.cdx.json`: a CycloneDX 1.5 software bill of materials for the npm package. The `sbom` stage in [`release.yml`](../.github/workflows/release.yml) generates it from the production dependency tree the package installs (`npm ls --omit=dev --all --json`), so development tooling is not listed. Before anything is signed, the same stage validates the document against the bundled CycloneDX 1.5 JSON schema and checks that it names this release, lists every runtime dependency, and matches the installed tree. It then signs the document keylessly with cosign and attaches it with its `.sigstore.json` bundle. Verify it with:

```bash
cosign verify-blob \
  --bundle sbom.cdx.json.sigstore.json \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/velella-sh/offing/\.github/workflows/release-sbom\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-.+)?$' \
  sbom.cdx.json
```

A manual run with `dry_run` on generates and validates the SBOM and attaches nothing.

### VEX statements

Every release also attaches `vex.cdx.json`: a CycloneDX 1.5 VEX file that says which known dependency vulnerabilities do not affect Offing, with a reason for each. The statements are reviewed files in [`security/vex/`](../security/vex/README.md), one per advisory and package, each with a CycloneDX justification and a plain-words reason. The same stage that builds the SBOM turns them into the VEX file (`.github/scripts/release-vex.mjs`), keeps only the statements whose package is a component of that release's SBOM, links each to its component, validates the result against the CycloneDX 1.5 schema, and signs it with the same keyless identity as the SBOM. With no statements the file is valid and lists no vulnerabilities. Verify it like the SBOM, with `vex.cdx.json` and `vex.cdx.json.sigstore.json`. Add a statement when a dependency advisory does not affect Offing; fix the dependency when it does.

### Signing a release that predates the signing stage

Use this only for a release cut before the signing stage landed; a normal release signs itself. Run *Release backfill signatures* from Actions, enter the tags (for example `v0.7.0 v0.6.1`), and turn *dry run* off. The workflow downloads the assets already attached to those releases, signs those exact bytes with keyless Sigstore (cosign), verifies every signature, and uploads a `.sigstore.json` bundle next to each asset. It never rebuilds or replaces an asset.

A backfilled signature proves that the release workflow vouched for the published bytes when the repair ran. It is **not** build provenance: there is no SLSA `multiple.intoto.jsonl`, and Scorecard scores that release 8 rather than 10. Say so in the release notes; do not present a backfilled release as built-and-signed. Prefer the next normal release whenever one is due.

Verify a backfilled asset with the identity of the workflow at the ref it ran from. The v0.7.0, v0.6.1, and v0.6.0 backfill on 2026-11-06 ran from the pull-request branch that introduced the workflow:

```bash
cosign verify-blob \
  --bundle offing-<version>-<os>-<arch>.sigstore.json \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/velella-sh/offing/\.github/workflows/release-backfill-signatures\.yml@refs/heads/ci/2289-signed-releases$' \
  offing-<version>-<os>-<arch>
```

Later backfills run from `main`; use the same command with `@refs/heads/main`.

## Rule data

Lifecycle rules come from [Ebb](https://github.com/velella-sh/ebb) through the `@velella/ebb` dependency, so every package release carries the
rules of the Ebb version it locks. Between releases, rules reach users through Ebb's signed data releases, which
`offing data update` downloads and verifies. Ebb publishes them; its [release guide](https://github.com/velella-sh/ebb/blob/main/docs/DATA.md#publishing-a-bundle)
describes how. A new Ebb version reaches this repository as a dependency update, and the rules workflow runs every
rule fixture against it.

## Rolling back

Decide by what has already been published, and prefer fixing forward.

- **Nothing published yet** (the pull request or tag only): close the pull request, or delete the tag with `git push origin :refs/tags/vX.Y.Z` and `git tag -d vX.Y.Z`.
- **Bad npm release**: do not rely on `npm unpublish`, which is restricted for packages that have users. Publish a fixed patch release, then mark the bad one with `npm deprecate offing@X.Y.Z "Use X.Y.Z+1: <reason>"`.
- **Bad Action tag**: users pin the tag, so ship a fixed patch tag and point the README at it. If you must move a tag that was published only minutes ago, say so in the release notes.
- **Bad plugin package**: revert the generated files through a pull request and release a patch version; withdraw a pending Codex submission through its portal.
- **Bad rule**: revert or correct the rule in `registry/` and release a patch. If the rule is actively harmful (it reports something that is not deprecated), release first and discuss afterwards.

After any rollback, add a line to `CHANGELOG.md` explaining what happened and which version replaces the bad one.