prehello 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## 1.0.0 - 2026-11-07
+
+### Added
+#### Agents
+- GitHub Copilot (CLI and VS Code): user and repository `copilot-instructions.md`, `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` from the repo root to the working directory, path-specific `*.instructions.md` (`applyTo` → conditional, description only → deferred, neither → ignored), prompt files (on demand), MCP servers from `~/.copilot/mcp-config.json`, `.mcp.json`, `.github/mcp.json`, `.vscode/mcp.json` and VS Code's user `mcp.json`. Sources in `spec/github-copilot.json`.
+- Gemini CLI: the `GEMINI.md` hierarchy (`~/.gemini`, working directory up to the `.git` boundary, subdirectories just-in-time), `context.fileName`, `@file` imports, extensions (`gemini-extension.json`), skills and MCP servers from settings. Sources in `spec/gemini-cli.json`.
+- Token estimates for both are unvalidated: Copilot uses the "model unknown" midpoint, Gemini the raw o200k count with a borrowed band (no Gemini ratio is invented).
+- Agent registry: one list of agents (`src/agents.ts`, `src/adapters/index.ts`) drives the CLI, scan, renderers and token profiles.
+
+#### Calibration
+- `prehello calibrate`: paste Claude Code's `/context` output (`--file ctx.txt`, `--context-file`, or `-` for standard input) and see prehello's estimate next to it per category (memory files one by one, skills, custom agents, MCP tools), with the error and whether it falls inside the band. `--json` prints it as JSON; `--save <file>` writes a record with no paths or names. Offline. Reads the grid layout, the newer "Estimated usage by category" layout and the legend-only form.
+- `docs/ACCURACY.md`: where every factor comes from, the measured spread, and what is not measured.
+- `scripts/calibrate-anthropic.mjs` (development only): measures the Claude/o200k ratio on real files via `count_tokens` or `claude -p`.
+
+#### PR diff, GitHub Action, badge
+- `--save <file>` writes a snapshot (the JSON report). `prehello diff <base.json> <head.json>` prints each agent's change, e.g. `Claude Code: +1.2k tokens before hello (~3.1k → ~4.3k, +39%)`, with the 10 biggest item changes. `--markdown` (or `--markdown=<file>`) gives a PR comment, `--json` the data, `--fail-above <tokens>` exits 2 when an agent grows by more. Offline; no git inside prehello.
+- GitHub Action (`action.yml`, `uses: PIYUSH-KUMAR1809/prehello@v1`): scans the PR base (git worktree) and head with an empty HOME, writes the job summary and one sticky PR comment, optional `fail-above`. Needs only `pull-requests: write`; fork PRs on `pull_request` fall back to the job summary. `docs/github-action.md` explains `pull_request_target` risk. This repository runs it on its own PRs (`.github/workflows/prehello.yml`).
+- `--badge <file>`: a shields.io endpoint JSON (`context before hello: ~5.2k tokens (Cursor)`).
+
+#### Benchmark
+- `benchmark/` (not in the npm package): `collect.mjs` samples public GitHub repositories with agent context files across stars buckets, `run.mjs` runs prehello on each with an empty HOME, `analyze.mjs` writes `benchmark/data/summary.json` and the charts in `benchmark/charts/`. Results (559 repositories, 2026-11-03) in `docs/BENCHMARK.md`.
+
+#### Fixture folders
+- Test-fixture folders are skipped by the project walk by default, for every agent: `fixtures`, `__fixtures__`, `fixture`, `testdata`, `test-data`, `__mocks__`, `__snapshots__` at any depth, and `snapshots` / `golden` / `goldens` below a `test`/`tests`/`__tests__`/`spec`/`e2e`/`cypress` folder (case-insensitive, both path separators). Running prehello in a repository that keeps sample `AGENTS.md`, `.cursor/rules` or skills there (such as prehello itself) no longer lists them as conditional context. `--include-fixtures` brings them back.
+- When a skipped fixture folder held agent files, the terminal report, Markdown and SARIF (`properties.prehello.fixtureFoldersSkipped`) say how many were skipped (a count, no paths) and `--json` has `scan.fixturesSkipped` (absent when 0). Not a warning; the exit code is unchanged.
+- A scan whose root is itself inside a fixtures folder never skips anything, and the scanned project's own top-level files are never skipped.
+
+#### Docs
+- README rewritten for 1.0: all five agents up front, benchmark numbers and charts, the GitHub Action snippet, error bands, and new screenshots in `docs/images/` (terminal scan, what-to-cut list, PR comment, share card) from real runs on a demo setup built from the test fixtures. Sample cards regenerated. `prehello diff --markdown`: the per-agent `<summary>` line is plain escaped text (GitHub does not render Markdown backticks there).
+
+#### Release and repository tooling
+- `release.yml`: pushing a `vX.Y.Z` tag (for the next release; the moving `v1` Action tag and pre-release tags do not trigger it) runs typecheck, tests and the install smoke test, checks that the tag matches `package.json`, then publishes to npm with provenance.
+- Dependabot (npm and GitHub Actions, weekly), CodeQL and OpenSSF Scorecard workflows.
+
+### Changed
+- Requires Node 22 or newer (`engines.node` is now `>=22`). Node 18 and 20 are end-of-life (April 2025 and April 2026); CI tests Node 22, 24 and 26 on Linux, macOS and Windows.
+- `--card card.png` (with a space) is accepted as the card file name, like `--card=card.png`. The next argument is taken as the file name only when it ends in `.svg` or `.png` and is not an existing directory.
+- The share card footer and the Markdown report footer now say `npx prehello` and link to the repository.
+- The version has one source of truth: `package.json`. `scripts/gen-version.mjs` writes `src/version.ts` before every build and typecheck, and a test fails if they drift.
+- MCP configs: `type: "local"` is read as stdio and `httpUrl` as HTTP (Copilot CLI and Gemini CLI formats).
+- The long README reference moved to `docs/REFERENCE.md`; SARIF rule help points there.
+
+#### Numbers
+- Claude Code: the single ×1.5 ±20% prior is replaced by ×1.43 for text and ×1.35 for JSON (MCP tool schemas), ±15%, from published Claude-tokenizer measurements (`spec/calibration.json`). Claude totals drop by roughly 5–10%. `--claude-profile legacy` is ×0.82 of the current factor (was a flat ×1.2).
+- Cursor: the skills listing is now modelled on what Cursor staff described (June 2026): `<agent_skill fullPath="…">` entries with descriptions cut to 80 characters. The low end assumes path-only entries, the high end full descriptions. Cursor skill-heavy totals drop; bands widen.
+
+#### Tests, CI and tooling
+- Tests use canonical temp directories (`test/helpers/tmp.ts`). On Windows the runner's temp dir is an 8.3 short path (`C:\Users\RUNNER~1\...`) while prehello, correctly, reports the real one; comparing the two caused most Windows failures (goldens, memory slugs, SARIF, adapters). An opt-in simulation (`PREHELLO_SIM_SHORTPATH=1`) reproduces this on any OS.
+- Fixture `.claude.json` files get their `__PROJECT__` placeholder JSON-escaped (a raw `C:\Users\x` made the file invalid JSON).
+- Symlink fixtures are stored as `<name>.__SYMLINK__` marker files and linked at run time; tests that need symlinks skip where the OS refuses them.
+- The case-insensitive-filesystem simulator handles drive roots; POSIX-only assertions are skipped on Windows; hostile-file-name test no longer needs an ESC file name on Windows; guard scripts embed paths as JSON strings.
+- Added `test/ci-portability.test.ts` (canonical temp dirs, JSON escaping, symlink markers, no backslash/drive/temp paths in terminal and `--json` output).
+- `scripts/smoke-install.mjs` removes `node_modules/@resvg` after install when newer npm versions install the optional engine despite `--omit=optional`, so the "engine absent" scenario is real.
+- CI: `actions/checkout@v5`, `actions/setup-node@v5`; the Windows PowerShell smoke step checks every exit code and uses a unique work directory.
+- Tests compared raw Report paths (native: backslashes on Windows) with forward-slash literals (`endsWith("project/CLAUDE.md")`), and a JSON dump with an unescaped path; they now compare normalised values (`posix()` in `test/helpers/tmp.ts`). `leakForms`/`canonical` no longer touch the disk for made-up paths.
+- New opt-in simulation `PREHELLO_SIM_WINSEP=1` (`test/helpers/winsep.ts`): tests see a Report whose paths use backslashes while the renderers still get the pristine one. It reproduces the failures of the second run on Linux; CI runs it (together with `PREHELLO_SIM_SHORTPATH=1`) on Ubuntu.
+
+### Fixed
+- CHANGELOG: 0.1.0 was published on 2026-10-25.
+- Windows: `autoMemoryDirectory` set as `~\...` is expanded like `~/...`.
+
+## 0.1.0 - 2026-10-25
+
+First version.
+
+### Added
+- Scan of a repository and the user-level config of Claude Code, Cursor and Codex (and plain `AGENTS.md`): instruction files, rules, skills, plugins, MCP servers.
+- Estimated tokens split into always-on / conditional / deferred / on-demand, with low/high bands, an explicit "not measured" list (never counted as 0) and a Context Grade (a heuristic).
+- "What to cut": the heaviest plugins, skill folders and MCP servers, with the estimated saving.
+- Findings: duplicate files, over-long or truncated files, ignored files, possible secrets (by line number only), skills listings over budget.
+- Outputs: terminal, `--json` (versioned, `--redact`), SVG/PNG share cards (`--card`), Markdown report (`--markdown`, `--markdown-compact`), SARIF 2.1.0 (`--sarif`, rules PH001-PH011), `--fix` dry-run plan.
+- CI gate `--max-tokens` (exit code 2).
+- Safe output writing (no symlinks, no overwriting files prehello did not write), scan budgets, hostile-input limits.
+- Linux, macOS and Windows support; Node 18, 20, 22.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piyush Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+<h1 align="center">prehello</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><b>See what your coding agent loads before you say hello, and what you could cut.</b></p>
+
+<p align="center">
+  <a href="https://github.com/PIYUSH-KUMAR1809/prehello/actions/workflows/ci.yml"><img src="https://github.com/PIYUSH-KUMAR1809/prehello/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/prehello"><img src="https://img.shields.io/npm/v/prehello" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A522-brightgreen" alt="Node 22 or newer">
+  <img src="https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey" alt="Linux, macOS and Windows">
+</p>
+
+Every **Claude Code, Cursor, Codex, GitHub Copilot and Gemini CLI** session starts with rules, skills, plugin listings and MCP servers already
+in the context window, before you type a word. **prehello** scans your repo and your user-level agent config and tells you
+**how many tokens that is, which plugin or file is responsible, and roughly what removing the top few would save.**
+
+- **Local and read-only.** No network, no telemetry, no API key, no child processes. Nothing leaves your machine.
+- **Honest numbers.** Every count is an estimate (`~`) with a published error band. What it cannot measure is listed, never shown as 0.
+- **Actionable.** A ranked "what to cut" list, a share card, a PR comment on every pull request, a badge, SARIF and a `--max-tokens` CI gate.
+
+```sh
+npx prehello                          # this folder plus your user-level agent config
+npx prehello ~/code/your-project      # a specific project
+npx prehello --card=card.png          # also write a PNG share card
+```
+
+Needs Node 22 or newer, on Linux, macOS or Windows. `npm install -g prehello` installs it as `prehello`.
+
+## What it prints
+
+<p align="center"><img src="https://raw.githubusercontent.com/PIYUSH-KUMAR1809/prehello/main/docs/images/scan.png" width="760" alt="prehello terminal output: per-agent totals for Claude Code, Cursor, Codex, GitHub Copilot and Gemini CLI, the what-to-cut list, measured vs not measured, and top offenders"></p>
+
+<sub>A real run of prehello 1.0 on a demo setup built from the bundled test fixtures (`test/fixtures/`), not anyone's real machine.</sub>
+
+Below this first screen come a per-agent breakdown (always-on / conditional / deferred / on-demand), findings, and a Context Grade
+(a heuristic of this tool, not a standard). The full output is in [docs/REFERENCE.md](docs/REFERENCE.md).
+
+> **Read the numbers as "what YOUR config adds".** The agent's built-in system prompt and tool definitions are not on disk, so no static
+> scanner can see them. prehello's total is the part *you* control. For the exact live total in one Claude Code session, use `/context`.
+
+**The share card** (`--card=card.png`) holds no paths or file contents:
+
+<p align="center"><img src="https://raw.githubusercontent.com/PIYUSH-KUMAR1809/prehello/main/docs/images/card.png" width="640" alt="prehello share card: Skills and plugins cost at least ~4.9k tokens before hello, with a treemap of plugins"></p>
+
+## What 559 public repos load before hello
+
+The [State of agent context 2026](docs/BENCHMARK.md) benchmark checked 2,041 public GitHub repos; 559 ship agent files. prehello ran on each with an
+empty HOME, so only the repo's own files count.
+
+- The median repo adds **~2.2k tokens** before hello. p90 is ~8.4k, the largest ~53k.
+- **20.4%** have both CLAUDE.md and AGENTS.md at the root, so Claude Code ignores the AGENTS.md.
+- **16.6%** have an instruction file longer than the agent's documented guideline; **3.4%** have an AGENTS.md chain Codex truncates at 32 KiB.
+- Stars don't predict size (Spearman 0.05), but they do predict adoption: **47%** of 10k+ star repos ship agent files, vs **17%** at 20–99 stars.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/PIYUSH-KUMAR1809/prehello/main/benchmark/charts/always-on-by-agent.png" width="420" alt="Always-on tokens per agent across 559 repos">
+  <img src="https://raw.githubusercontent.com/PIYUSH-KUMAR1809/prehello/main/benchmark/charts/mistakes.png" width="420" alt="Common agent-file mistakes across 559 repos">
+</p>
+
+Data, scripts and how to reproduce it are in [`benchmark/`](benchmark/) and [docs/BENCHMARK.md](docs/BENCHMARK.md).
+
+## A PR comment on every pull request
+
+```yaml
+# .github/workflows/prehello.yml
+on: pull_request
+permissions: { contents: read, pull-requests: write }
+jobs:
+  context-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0, persist-credentials: false }
+      - uses: PIYUSH-KUMAR1809/prehello@v1
+        with: { fail-above: 2k }   # optional
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/PIYUSH-KUMAR1809/prehello/main/docs/images/pr-comment.png" width="640" alt="The prehello PR comment: a table of base, head and change per agent"></p>
+
+One sticky comment per PR, updated on every push. Fork PRs fall back to the job summary. Details, inputs and the README badge
+(`--badge badge.json`, a shields.io endpoint) are in [docs/github-action.md](docs/github-action.md).
+
+## How accurate is it?
+
+Counts use the o200k tokenizer with per-agent factors from published measurements. Bands: Codex ±3%, Claude Code ±15%,
+Cursor and Copilot −3% to +15% (model unknown), Gemini CLI −3% to +64% (unvalidated). Sources and caveats are in [docs/ACCURACY.md](docs/ACCURACY.md).
+`prehello calibrate --file ctx.txt` compares the estimate with your own Claude Code `/context` reading, per category.
+
+## Outputs
+
+| You want | Run |
+| --- | --- |
+| The report in the terminal | `node dist/cli.js` (`--verbose` for per-item evidence) |
+| A share card (PNG or SVG) | `--card=card.png` or `--card=card.svg` (write the name with `=`) |
+| Something to paste into an issue, PR or Slack | `--markdown` (or `--markdown=report.md`, `--markdown-compact` for a PR comment) |
+| GitHub code scanning / IDEs | `--sarif=prehello.sarif` |
+| Machine-readable | `--json` (add `--redact` before sharing it: no paths or names) |
+| A budget gate in CI | `--max-tokens 16k` (exit code 2 above it) |
+| What a PR changes | `--save base.json` / `--save head.json`, then `prehello diff base.json head.json` (`--markdown`, `--fail-above 2k`) |
+| A PR comment on every pull request | the GitHub Action: `uses: PIYUSH-KUMAR1809/prehello@v1` ([docs/github-action.md](docs/github-action.md)) |
+| A README badge | `--badge badge.json` (shields.io endpoint JSON; see [docs/github-action.md](docs/github-action.md#badge)) |
+| Check the estimate against Claude Code | `prehello calibrate --file ctx.txt` (paste `/context` output; see [docs/ACCURACY.md](docs/ACCURACY.md)) |
+| Suggestions, changing nothing | `--fix` (dry run) |
+| Count Cursor "User Rules" you paste in | `--paste-user-rules rules.txt` |
+| Also count agent files inside test-fixture folders | `--include-fixtures` (skipped by default; see [docs/REFERENCE.md](docs/REFERENCE.md)) |
+
+`node dist/cli.js --help` lists every flag. PNG cards need the optional package `@resvg/resvg-wasm`; if it is missing, prehello prints how to install it
+and exits 1 without a stack trace, and the SVG card and everything else keep working.
+
+## Agents covered
+
+Claude Code, Cursor, Codex, GitHub Copilot (CLI and VS Code), Gemini CLI, and plain `AGENTS.md` files. What is scanned for each is in [docs/REFERENCE.md](docs/REFERENCE.md). Not yet: Windsurf, Cline.
+
+## FAQ
+
+**Does it send anything anywhere?** No. No network, no telemetry, no API key, no child processes. A test runs the CLI with a guard that blocks and records any
+network, DNS or child-process attempt. It writes only the output files you name (`--card=`, `--json=`, `--markdown=`, `--sarif=`).
+
+**Is the token count exact?** No, and it says so. It counts with the o200k tokenizer and applies a per-agent factor. The Claude factors come from
+published `count_tokens` measurements (a small sample, see [docs/ACCURACY.md](docs/ACCURACY.md)), not from prehello's own runs, so every
+total carries an error band and a `~`. `prehello calibrate` compares the estimate with your own Claude Code `/context` reading.
+
+**Why is my total smaller than what `/context` shows?** `/context` also sees the built-in system prompt, built-in tool definitions and the conversation. prehello only sees what is on disk.
+
+**Why not just use `/context`?** If you only use Claude Code and want the true number for one live session, do. prehello works before a session, covers Cursor, Codex, Copilot and Gemini CLI too,
+runs in CI, and ranks *which plugin or skill folder* to remove.
+
+**Does it start my MCP servers?** No. It lists their names and counts. Sizes come only from a small measured catalog (`spec/mcp-weights.json`, 7 servers) or a file you give it; every other server stays "unmeasured".
+
+**Does it change my files?** No. `--fix` is a dry run that only prints suggestions.
+
+**Can I trust the Context Grade?** It is a heuristic of this tool, not a standard. It is capped at B and marked provisional when something that always loads could not be measured. `node dist/cli.js explain grade` prints the rubric. `--no-grade` hides it.
+
+**Why does it say "Skipped N fixture folders"?** A repo that tests agent tooling keeps sample `AGENTS.md`, `CLAUDE.md`, `.cursor/rules` and skills under `test/fixtures/` and similar. No agent loads those, so prehello skips such folders by default and says how many it skipped (only folders where it found agent files). `--include-fixtures` counts them; scanning a folder that is itself inside a fixtures folder never skips anything.
+
+**Does it work on Windows?** Yes. CI runs the full suite on Ubuntu, Windows and macOS with Node 22, 24 and 26. See [docs/REFERENCE.md](docs/REFERENCE.md).
+
+## Limitations
+
+- Token counts are **estimates**; the Claude factors rest on about 10 published measurements, and Cursor's model is unknown (see [docs/ACCURACY.md](docs/ACCURACY.md)).
+- The built-in system prompt, built-in tools, Cursor User and Team Rules (unless pasted), claude.ai connectors, hook output and anything injected at runtime are **never measured**.
+- Loading rules come from the agents' public docs and announcements, not from their source, and were **not re-verified against live installs**; items where sources disagree are labelled `assumed`.
+- Five agents plus `AGENTS.md` are covered (Copilot and Gemini CLI token factors are unvalidated), and MCP server sizes exist for just 7 servers.
+
+Full list: [docs/REFERENCE.md](docs/REFERENCE.md).
+
+## How it differs
+
+Several small tools look at neighbouring problems. As of 2026-10-25, from each project's own npm, PyPI or docs page; **I read them, I did not run them**.
+They overlap with prehello in places, so if one of them fits better, use it.
+
+- **`/context`** (built into Claude Code): per Anthropic, it visualizes what is currently loaded into the context window and where it is being spent, for the live session.
+- **ccusage**: its npm description is "Analyze coding (agent) CLI token usage and costs from local data", so it is about what past sessions used and cost, not what loads before a session.
+- **ctxlint**: a linter for AI agent context files and MCP configs, catching broken paths, wrong commands and leaked secrets.
+- **ctxweight** (npm, v0.1.0): describes itself as an X-ray of your agent's context, with health checks and token cost in one command.
+- **ctxaudit**: audits "the invisible context tax" from skills, rules and instruction files (v0.1.0, PyPI).
+
+What prehello focuses on: a per-plugin / per-skill-folder **cut list**, **unmeasured is never 0** (totals become lower bounds), a confidence label on every item
+(`documented`, `observed`, `assumed`), a share card that holds no paths or file contents, and a CI gate. What it does **not** do: live sessions, dollar cost,
+linting your instructions against your code, or exact token counts.
+
+## Roadmap
+
+Not yet: `--probe` (starting MCP servers to measure real schemas), history beyond two snapshots, `--apply` / `--patch`, Windsurf and Cline adapters,
+Cursor Team Rules, a catalog beyond the 7 measured servers.
+
+## Contributing, security, licence
+
+Issues and PRs are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) (the ground rules are product promises: local, read-only, estimates labelled, no file contents in output).
+Report vulnerabilities as described in [SECURITY.md](SECURITY.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+MIT © 2026 Piyush Kumar

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,33 @@
+# Third-party notices
+
+prehello itself is MIT licensed (see `LICENSE`). It uses the following third-party material.
+
+## Runtime dependencies (installed by npm, not copied into this repository)
+
+| Package | Licence | Used for |
+| --- | --- | --- |
+| [gpt-tokenizer](https://github.com/niieani/gpt-tokenizer) 4.x | MIT | token counting with the `o200k_base` encoding. The encoding data originates from OpenAI's [tiktoken](https://github.com/openai/tiktoken) (MIT). |
+| [picomatch](https://github.com/micromatch/picomatch) 4.x | MIT | glob matching for agent settings (for example `claudeMdExcludes`) |
+| [smol-toml](https://github.com/squirrelchat/smol-toml) 1.x | BSD-3-Clause | reading Codex `config.toml` |
+
+## Optional dependency
+
+| Package | Licence | Used for |
+| --- | --- | --- |
+| [@resvg/resvg-wasm](https://github.com/yisibl/resvg-js) 2.x (resvg) | MPL-2.0 | rendering the PNG share card. Installed as an npm `optionalDependency`, loaded only when you ask for a PNG, never modified or bundled here. Its source and licence are available from the package. |
+
+## Bundled files
+
+| File | Licence | Notes |
+| --- | --- | --- |
+| `assets/fonts/Inter-*.subset.ttf` | SIL Open Font License 1.1 | Subsets (Basic Latin, Latin-1, a few punctuation marks) of static instances of [Inter](https://github.com/rsms/inter), Copyright 2016 The Inter Project Authors. Used only to draw the PNG card. The licence text is in `assets/fonts/OFL.txt`. |
+
+## Development-only dependencies (not shipped)
+
+TypeScript (Apache-2.0), vitest (MIT), ajv and ajv-formats (MIT), `@types/*` (MIT). The SARIF 2.1.0 JSON schema in `test/schema/` is published by OASIS (see `test/schema/README.md`).
+
+## Documentation
+
+The loading rules in `spec/*.json` are facts summarised from the public documentation of Claude Code, Cursor, Codex, GitHub Copilot and Gemini CLI, each with the URL it came from. No documentation text is copied.
+
+The Code of Conduct is the [Contributor Covenant](https://www.contributor-covenant.org) 2.1 (CC BY 4.0).

package/assets/fonts/OFL.txt

@@ -0,0 +1,94 @@
+The fonts in this folder are subsets (Basic Latin, Latin-1, and a few punctuation marks) of static instances
+(weights 400, 600, 800) of Inter. They are used only to draw the PNG share card.
+
+Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at: https://openfontlicense.org
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.