docs: PR workflow for protected main, packaging alignment, release notes (#1)

SutuSebastian · web-flow · commit b366c5329998 · 2026-04-07T11:12:24.000+03:00
* docs: document PR-only workflow for protected main

- CONTRIBUTING: branch from main, push branch, PR after CI green.
- docs/README: link CI workflow in contributor conventions.

* docs: align packaging/benchmark with docs/README conventions

- packaging: tarball contents match package.json files (include CHANGELOG).
- benchmark: point glob stack to Node vs Bun; avoid duplicating SQL in prose.
- docs/README: index packaging row + conventions (no duplicate runtime table; benchmark exception).

* ci(release): use npm run release for Changesets publish; document NPM_TOKEN

- setup-node@22 before changesets/action so publish matches npx changeset publish.
- Replace bun run release in the action: avoid exit 1 on no-op main pushes.
- packaging.md: explain every main push, no-changeset path, NPM_TOKEN for real publishes.

* ci(release): fact-check publish step; bun run release, honest docs

Remove unverified Bun-vs-npm claims. Revert to bun run release without setup-node.
Document troubleshooting (NPM_TOKEN, logs) instead of assumed root cause.

* chore: consolidate docs, packaging releases; add patch changeset

- docs README hub, packaging Changesets table, .changeset README pointer
- clean / check-updates scripts; CONTRIBUTING updates
- changeset: patch bump for @stainless-code/codemap
diff --git a/.changeset/README.md b/.changeset/README.md
@@ -6,3 +6,7 @@ find the full documentation for it [in our repository](https://github.com/change
 
 We have a quick list of common questions to get you started engaging with this project in
 [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).
+
+---
+
+**This repo:** How versioning, **`NPM_TOKEN`**, and the GitHub workflow fit together for **`@stainless-code/codemap`** — see [docs/packaging.md § Releases](../docs/packaging.md#releases) (single place; don’t duplicate here).
diff --git a/.changeset/docs-packaging-scripts.md b/.changeset/docs-packaging-scripts.md
@@ -0,0 +1,5 @@
+---
+"@stainless-code/codemap": patch
+---
+
+Consolidate docs (index hub, packaging/Releases, benchmark vs external root), point `.changeset/README` at packaging, and add `clean` / `check-updates` npm scripts.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -12,13 +12,28 @@ bun install   # runs `prepare` → Husky git hooks
 bun run dev   # same as `bun src/index.ts` — CLI from source
 bun test
 bun run check   # format + lint + tests + typecheck + build
+bun run clean   # remove untracked/ignored build artifacts (keeps `.env`, `.codemap.db*`)
+bun run check-updates   # interactive dependency updates (`bun update -i --latest`)
 ```
 
+### `main` and pull requests
+
+Branch **`main`** is **protected**: routine work does **not** push directly to `main`. Open a **pull request** and merge only after **[CI](workflows/ci.yml)** passes (format, lint, typecheck, test, build).
+
+```bash
+git fetch origin && git checkout main && git pull
+git checkout -b your-branch-name
+# … commit …
+git push -u origin your-branch-name
+```
+
+Then open a PR on GitHub into **`main`**.
+
 ### Readability & DX
 
 - **Public API** — Anything exported from the package entry (`src/index.ts` → `src/api.ts`, `config.ts`, shared types) should have **JSDoc** that reads well in hovers and in published typings.
 - **Layers** — Keep boundaries clear: [architecture.md](../docs/architecture.md) (`cli` → `application` → infrastructure). Don’t let CLI concerns leak into parsers or the DB layer.
-- **Before you push** — `bun run check` (or at least `bun run test` + `bun run typecheck` if you’re iterating).
+- **Before you open / update a PR** — `bun run check` (or at least `bun run test` + `bun run typecheck` while iterating).
 - **Style** — Match Oxfmt/Oxlint; prefer **straight-line code** and extracted helpers over long nested blocks.
 
 **Editor (VS Code):** [`.vscode/extensions.json`](../.vscode/extensions.json) lists recommended extensions (Bun, Oxc, TypeScript native preview, etc.). [`.vscode/settings.json`](../.vscode/settings.json) enables Oxc format on save and `tsgo`. Formatting and lint rules live in [`.oxfmtrc.json`](../.oxfmtrc.json) and [`.oxlintrc.json`](../.oxlintrc.json) (no framework-specific options beyond defaults).
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -31,8 +31,11 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      # Opens/updates the Version PR; after merge, publishes to npm and creates GitHub Releases
-      # (see https://github.com/changesets/action — createGithubReleases defaults to true).
+      # Opens/updates the Version PR when `.changeset/*.md` exist. When there are none, the action
+      # can still run `publish` (see changesets/action) so a just-merged Version PR can ship.
+      # `changeset publish` should exit 0 when there is nothing new to publish. If this job fails,
+      # read the step log: common causes are missing/invalid NPM_TOKEN, registry/network errors, or
+      # a real publish failure — not assumed from the runner alone.
       - name: Create Release Pull Request or Publish to npm
         id: changesets
         uses: changesets/action@v1
diff --git a/bun.lock b/bun.lock
diff --git a/docs/README.md b/docs/README.md
@@ -2,14 +2,14 @@
 
 Technical docs for **[@stainless-code/codemap](https://github.com/stainless-code/codemap)**. Quick start: [../README.md](../README.md).
 
-| File                                 | Topic                                                                                                                                                                                                                          |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [architecture.md](./architecture.md) | Schema, layering, CLI, programmatic API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files)                                                                             |
-| [benchmark.md](./benchmark.md)       | **[Indexing another project](./benchmark.md#indexing-another-project)** (`CODEMAP_*`, `.env`) · **[benchmark script](./benchmark.md#the-benchmark-script)** (`src/benchmark.ts`) · [`fixtures/minimal/`](../fixtures/minimal/) |
-| [packaging.md](./packaging.md)       | `dist/`, npm **`files`**, **engines**, **[Node vs Bun](./packaging.md#node-vs-bun)**, **[Releases](./packaging.md#releases)** (Changesets)                                                                                     |
-| [roadmap.md](./roadmap.md)           | Forward-looking backlog (not a `src/` inventory)                                                                                                                                                                               |
-| [why-codemap.md](./why-codemap.md)   | Why index + SQL for agents (speed, tokens, accuracy)                                                                                                                                                                           |
+| File                                 | Topic                                                                                                                                                                               |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [architecture.md](./architecture.md) | Schema, layering, CLI, API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files)                                               |
+| [benchmark.md](./benchmark.md)       | [**Indexing another project**](./benchmark.md#indexing-another-project) · [**Benchmark script**](./benchmark.md#the-benchmark-script) · [`fixtures/minimal/`](../fixtures/minimal/) |
+| [packaging.md](./packaging.md)       | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets)                |
+| [roadmap.md](./roadmap.md)           | Forward-looking backlog (not a `src/` inventory)                                                                                                                                    |
+| [why-codemap.md](./why-codemap.md)   | Why index + SQL for agents (speed, tokens, accuracy)                                                                                                                                |
 
-**Cross-cutting:** SQLite, workers, include globs, and **JSON config I/O** use Bun when available — **[packaging.md § Node vs Bun](./packaging.md#node-vs-bun)** (single table; don’t duplicate elsewhere). **Config shape / validation** (Zod, strict keys) lives only in **[architecture.md § User config](./architecture.md#user-config)**.
+**Cross-cutting:** Runtime splits (SQLite, workers, globs, JSON config I/O) — [packaging § Node vs Bun](./packaging.md#node-vs-bun) only (link it; don’t copy the table). **User config** shape/validation — [architecture § User config](./architecture.md#user-config) only.
 
-**Conventions:** one topic per file; relative links; no symbol/file counts or source line numbers (use `codemap query` / `bun run dev query` after indexing). **This repo:** `bun run dev` → `bun src/index.ts`; **`bun run build`** → tsdown → `dist/`. **Contributors:** `bun run check`, JSDoc on public API — [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md).
+**Conventions:** One topic per file; relative links; avoid stale file/symbol counts in narrative docs (use `codemap query` / `bun run dev query` after indexing; methodology tables in [benchmark.md](./benchmark.md) are fine). **This repo:** `bun run dev` → `bun src/index.ts`; `bun run build` → tsdown → `dist/`; `bun run clean` / `bun run check-updates` — [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md). **Contributors:** branch + PR into **`main`** ([CI](../.github/workflows/ci.yml)), `bun run check`, JSDoc on public API.
diff --git a/docs/benchmark.md b/docs/benchmark.md
@@ -45,7 +45,7 @@ Use **`CODEMAP_ROOT`** instead of **`CODEMAP_TEST_BENCH`** if you prefer; behavi
 ### Overview
 
 1. **Indexed** — single SQL query against `.codemap.db`
-2. **Traditional** — glob (Bun **`Glob`** or **`fast-glob`** on Node, same as the indexer) → **`readFileSync`** → regex match (simulates what AI agent tools like Grep/Read/Glob do)
+2. **Traditional** — glob (same implementation as the indexer — [packaging.md § Node vs Bun](./packaging.md#node-vs-bun)) → **`readFileSync`** → regex match (simulates what AI agent tools like Grep/Read/Glob do)
 
 **OSS note:** For **repeatable** numbers, use **`fixtures/minimal/`** ([Fixtures](#fixtures)) or index your own app with **`CODEMAP_ROOT`**. Tables below may still use historical labels; methodology is the same.
 
@@ -131,7 +131,7 @@ On a small repo, totals move with noise and thermal variance. On a large indexed
 
 The script’s **reindex** section averages **3 internal runs** per mode; full-rebuild wall time varies with disk and CPU load.
 
-The indexed CSS scenario uses `ORDER BY name LIMIT 50` — see `benchmark.ts` for the exact queries.
+The indexed CSS scenario uses `ORDER BY name LIMIT 50` — exact SQL for each scenario lives in **`src/benchmark.ts`** in this repo (not duplicated here; keep in sync when changing scenarios).
 
 ### Key takeaways
 
diff --git a/docs/packaging.md b/docs/packaging.md
@@ -9,7 +9,7 @@ How **@stainless-code/codemap** is built and published. Hub: [README.md](./READM
 
 ## Consuming locally
 
-Tarballs contain **`dist/`** + **`templates/`** only. **`bun run pack`**, then point the consumer at **`file:…/stainless-code-codemap-*.tgz`**, or use **`file:/path/to/repo`** after build, or **`bun link`**. If **`better-sqlite3`** fails in the consumer, **`npm rebuild better-sqlite3`** (native addon must match that Node).
+Published tarballs match **`package.json` `files`**: **`CHANGELOG.md`**, **`dist/`**, **`templates/`** (no `src/`). **`bun run pack`**, then point the consumer at **`file:…/stainless-code-codemap-*.tgz`**, or use **`file:/path/to/repo`** after build, or **`bun link`**. If **`better-sqlite3`** fails in the consumer, **`npm rebuild better-sqlite3`** (native addon must match that Node).
 
 **Engines** (`package.json`): **Node** `^20.19.0 || >=22.12.0` (matches **`oxc-parser`**; **`better-sqlite3`** is prebuilt for current Node majors only). **Bun** `>=1.0.0`. **Native bindings:** `better-sqlite3`, `lightningcss`, `oxc-parser`, `oxc-resolver` (NAPI); **`fast-glob`** and **`zod`** are JS-only. **`zod`** validates `codemap.config.*` at runtime (**`codemapUserConfigSchema`** in **`src/config.ts`**); see [architecture.md § User config](./architecture.md#user-config).
 
@@ -30,7 +30,13 @@ Same schema and CLI; implementation differs by runtime. Details: [architecture.m
 
 ## Releases
 
-[**Changesets**](https://github.com/changesets/changesets): **`bun run changeset`** → commit **`.changeset/`** → merge → [release workflow](../.github/workflows/release.yml) versions / publishes. **`bun run release`** runs **`changeset publish`** (CI uses it too). Needs **`NPM_TOKEN`** (and typically **`GITHUB_TOKEN`**) as repo secrets for publish and changelog links.
+Releases use [**Changesets**](https://github.com/changesets/changesets). Repo config: [`.changeset/config.json`](../.changeset/config.json) (`$schema` targets **`@changesets/config`** — resolved version in **`bun.lock`**). Upstream CLI docs: [`.changeset/README.md`](../.changeset/README.md).
+
+| Step | What happens                                                                                                                                                                                                                                                                                                                                              |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | **`bun run changeset`** — add a changeset file under **`.changeset/`**, commit, open PR to **`main`**.                                                                                                                                                                                                                                                    |
+| 2    | **Merge** — on every push to **`main`**, [`.github/workflows/release.yml`](../.github/workflows/release.yml) runs [`changesets/action@v1`](https://github.com/changesets/action): opens/updates the **Version packages** PR when pending changesets exist; **`publish: bun run release`** runs **`changeset publish`**; **`createGithubReleases: true`**. |
+| 3    | **Secrets** — **`GITHUB_TOKEN`** is provided by Actions. **`NPM_TOKEN`** (npm [automation token](https://docs.npmjs.com/creating-and-viewing-access-tokens)) must be a **repository secret** for publishes to npm. If the Release job fails, use the workflow log (missing token, registry error, etc.) — don’t assume the cause from the job name alone. |
 
 ## Related
 
diff --git a/package.json b/package.json
@@ -46,6 +46,8 @@
     "build": "tsdown",
     "changeset": "changeset",
     "check": "bun run build && bun run --parallel format:check lint:ci test typecheck",
+    "check-updates": "bun update -i --latest",
+    "clean": "git clean -xdf -e .env -e .codemap.db -e .codemap.db-wal -e .codemap.db-shm",
     "dev": "bun src/index.ts",
     "fix": "bun run lint:fix && bun run format",
     "format": "oxfmt",
@@ -67,7 +69,7 @@
     "better-sqlite3": "^12.8.0",
     "fast-glob": "^3.3.3",
     "lightningcss": "^1.32.0",
-    "oxc-parser": "^0.123.0",
+    "oxc-parser": "^0.124.0",
     "oxc-resolver": "^11.19.1",
     "zod": "^4.3.6"
   },
@@ -77,11 +79,11 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/bun": "^1.3.11",
     "@types/node": "^25.5.2",
-    "@typescript/native-preview": "^7.0.0-dev.20260406.1",
+    "@typescript/native-preview": "^7.0.0-dev.20260407.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
-    "oxfmt": "^0.43.0",
-    "oxlint": "^1.58.0",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
     "tsdown": "^0.21.7",
     "typescript": "^6.0.2"
   },

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@stainless-code/codemap": patch
 +---
++
 +Consolidate docs (index hub, packaging/Releases, benchmark vs external root), point `.changeset/README` at packaging, and add `clean` / `check-updates` npm scripts.