@ankurhalder/codebase-snapshot 3.0.0 → 4.0.1

package/docs/troubleshooting.md

@@ -0,0 +1,277 @@
+# Troubleshooting
+
+Every message below is the real text the tool prints. Find your symptom, then the cause and
+the fix.
+
+## The command does nothing
+
+**Symptom** — `npx @ankurhalder/codebase-snapshot generate` exits `0` and prints nothing. No
+`snapshot/` directory appears.
+
+**Cause** — a **stale global install** is shadowing `npx`. When a global copy exists, npm
+runs it instead of the published package, and a leftover `npm link` (pointing at a
+development checkout) resolves to a binary that is not there.
+
+**Fix**
+
+```bash
+npm ls -g --depth=0 | grep codebase-snapshot
+npm rm -g @ankurhalder/codebase-snapshot
+npx @ankurhalder/codebase-snapshot generate
+```
+
+If nothing is installed globally, clear the npx cache (`npm cache clean --force`) and retry.
+This is a local environment problem, not a package problem: on a machine without a global
+copy the same command works.
+
+## `command not found`
+
+**Cause** — when the package is installed as a project dependency, its binary lives in
+`node_modules/.bin` and is only on `PATH` inside a client runner or a package script.
+
+**Fix** — use `npx codebase-snapshot`, `pnpm exec codebase-snapshot`,
+`yarn codebase-snapshot`, `bun run codebase-snapshot`, or `./node_modules/.bin/codebase-snapshot`
+in scripts.
+
+## Exit code 2 — the command itself was wrong
+
+Exit `2` always means "retrying this unchanged will fail the same way". The message names the
+problem, and for an option the command does not take it also names the commands that do:
+
+```
+❌ --watch does not apply to `report` and was not applied. It is accepted by: `generate`.
+❌ --cwd does not apply to `describe` and was not applied. It is accepted by: `generate`, `validate`, `report`, `init`, `explain`, `skill`.
+```
+
+Nothing is silently ignored — that is the point of the message. The per-option `Applies to`
+column is in the [CLI reference](cli.md#options).
+
+| Message | Fix |
+| :--- | :--- |
+| `Unknown command "frobnicate". Expected one of: …` | Use one of the commands in the [CLI reference](cli.md). |
+| `--preset does not apply to \`generate\` and was not applied. It is accepted by: \`init\`. To scope a run, set include/excludePatterns/preset in snapshot.config.ts (or run \`codebase-snapshot init\` to generate one).` | `--preset`, `--include`, `--exclude`, `--yes`, `--minimal` and `--force` configure `init`, which writes them into the config. Set them at generation time in `snapshot.config.ts` instead. |
+| `--install does not apply to \`generate\` and was not applied. It is accepted by: \`skill\`.` | `--install` and `--target` configure `skill` only. |
+| `--cwd directory does not exist: …` / `--cwd is not a directory: …` | Point `--cwd` at an existing repository directory. |
+| `--out-dir requires a value (received an empty string).` | An unset shell variable expanded to nothing. Quote it or drop the flag. Every string option rejects `""` rather than silently using the default. |
+| `--max-part-bytes received a value that looks like another flag (for example a negative number). Use the "--option=value" form, and note that sizes must be positive.` | A negative number reads as a flag. Use `--max-part-bytes=-5`, and note that sizes must be positive. |
+| `Unknown preset "nope". Expected one of: …` | The message lists all 25 valid names. |
+| `--target must be one of: claude, agents, cursor, all (received "bogus").` | Fix the value. |
+| `diff expects exactly two arguments …` / `explain expects exactly one path.` | Fix the arity. |
+
+## Exit code 1 — the state was wrong
+
+### `Refusing to replace outDir …`
+
+```
+❌ Failed to generate snapshot: Refusing to replace outDir /repo/src: it holds no .codebase-snapshot marker (found app.ts). Remove the directory yourself, or point outDir at a new or empty directory.
+```
+
+**Cause** — the output directory contains files this tool did not write, and it cannot prove
+it wrote them. This guard exists because a mistyped `outDir` used to replace the directory:
+`outDir: "src"` deleted source code while reporting success.
+
+Ownership is proved by a `.codebase-snapshot` marker that parses as ours — a JSON object
+naming this generator, carrying a schema version this build understands, a per-snapshot `id`
+and the digest of the manifest it shipped. A file with the right name is not enough:
+
+| The directory | What the tool says |
+| :--- | :--- |
+| has files, no marker | `it holds no .codebase-snapshot marker (found app.ts)` |
+| has a zero-byte marker | `its .codebase-snapshot marker is empty (found .codebase-snapshot, app.ts)` |
+| has a marker that is not JSON | `its .codebase-snapshot marker is not valid JSON (found .codebase-snapshot, app.ts)` |
+| was written by 3.0.0 | `its .codebase-snapshot marker carries no snapshot id (found .codebase-snapshot, manifest.json)` |
+| carries our marker but you added files | `it carries this generator's ownership marker, but these entries are not part of the snapshot it recorded: custom.txt. Remove them yourself, or point outDir at a new or empty directory.` |
+
+**Fix** — point `--out-dir` somewhere new, or delete the directory yourself. Do not delete
+your source. Accepted without complaint: a missing directory, an empty directory, one
+holding only `.gitkeep`/`.gitignore`/`.DS_Store`, and a complete snapshot this build wrote.
+
+A snapshot written by 3.0.0 or earlier is **not** upgraded in place: its marker has three keys
+and no `id`, so the new build cannot prove it wrote the directory and refuses. Delete the old
+snapshot directory and generate again.
+
+### `Refusing to write into outDir …: it exists but is not a directory.`
+
+```
+❌ Failed to generate snapshot: Refusing to write into outDir /repo/notes.txt: it exists but is not a directory.
+```
+
+A regular file has the same name as the output directory. Rename or remove it.
+
+### `The config file could not be read`
+
+```
+⚠ Config: Could not parse /repo/snapshot.config.json: Expected property name or '}' …
+❌ The config file could not be read. Fix it, or delete it to use the defaults.
+```
+
+**Cause** — a config file exists but does not parse, or a `.ts` config cannot be loaded. This
+is fatal on purpose: skipping a broken config would generate a snapshot with none of your
+settings and still report success.
+
+**Fix** — fix the syntax, or delete the file to run on defaults. Check that the config is
+loadable on your Node version: a `.ts` config needs Node ≥ 22.6 **and** an ES-module project.
+`codebase-snapshot init` picks the right filename for the project automatically.
+
+### `Refusing to generate: …`
+
+```
+❌ Failed to generate snapshot: Refusing to generate: outDir is the working directory or one of its ancestors. outDir=/repo tmpDir=/repo/snapshot.tmp cwd=/repo
+```
+
+The output paths are unsafe: `outDir` or `tmpDir` is the working directory, an ancestor, the
+filesystem root, or they contain one another. The message prints the resolved paths so you
+can see why. Use a subdirectory.
+
+### Budget errors
+
+A budget set in a **config file** exits `1`, and names the setting as you wrote it:
+
+| Message | Fix |
+| :--- | :--- |
+| `maxPartBytes must be a positive byte count (received 0).` | Zero and negative values are errors, not "use the default". |
+| `maxPartBytes must be at least 4096 bytes (received 1000).` | Raise it to 4096 or more (`"120k"` is 122880). |
+| `maxPartBytes must be a byte count such as 120000, "120k" or "1.5mb" (received "abc").` | The value is not a number or a supported size string. |
+
+The same mistake on the **command line** is a usage error, exits `2`, names the flag, and is
+followed by the usage text:
+
+| Message | Fix |
+| :--- | :--- |
+| `--max-part-bytes must be at least 4096, received "1000".` | Raise it to 4096 or more. `--max-part-bytes 0` and `--max-part-bytes 1000` both produce this form. |
+| `--max-part-bytes expects a byte count such as 120000 or "120k", received "abc".` | The value is not a number or a supported size string. `--max-part-bytes=-5` produces this form too. |
+
+`--large-file-bytes` and `--max-monolith-bytes` share the second message, with their own flag
+name, and their minimum is 1 rather than 4096:
+`--large-file-bytes must be at least 1, received "0".`
+
+### `Cannot write the snapshot: permission denied under …`
+
+The output directory is not writable (or a parent is not readable). The previous snapshot is
+left intact. Fix the permissions, or choose another `--out-dir`.
+
+### `Snapshot validation failed` (from `validate`)
+
+Exit `1` with one line per class of drift:
+
+| Line | Meaning |
+| :--- | :--- |
+| `- modified: path` | The file changed since the snapshot. |
+| `- deleted: path` | The file is in the snapshot but no longer on disk. |
+| `- new file: path` | The file exists on disk and is not in the snapshot. |
+| `- part: part-001.md (missing from snapshot/parts)` | The part file was deleted or renamed. |
+| `- part: … (size mismatch …)` | The part was edited by hand. |
+| `- config: …` | A setting differs from the one recorded in the manifest. |
+| `- counts: …` | The manifest's own bookkeeping disagrees with its contents. |
+
+**Fix** — re-run `generate`. If it persists, the snapshot directory is being modified by
+something else.
+
+### `report` exits 1 (only when it cannot read the snapshot)
+
+- `Manifest not found at … Run generate first.` — nothing has been generated yet.
+- `… is not a snapshot manifest: missing \`counts\`` — the file parsed as JSON but is not a
+  manifest this tool wrote. Wrong `--out-dir`, or a foreign file named `manifest.json`.
+
+### `diff` exits 1
+
+- `No snapshot found at X: the path does not exist.`
+- `Could not read a manifest at X.`
+- `… is not a snapshot manifest (no "counts" object).`
+
+Point it at a snapshot directory or a `manifest.json` written by this tool.
+
+## A file is missing from the snapshot
+
+Run `explain` on it — it names the exact reason and the rule responsible:
+
+```bash
+npx codebase-snapshot explain src/generated/schema.ts
+```
+
+`manifest.json` records the same for every file in `skipped[]`:
+
+| `reason` | Meaning | Fix |
+| :--- | :--- | :--- |
+| `sensitive-file` | `.env`, `*.pem`, `.npmrc`, `.ssh/`, `.tfstate`, … | `--include-sensitive-files` if you really want it. |
+| `sensitive-path` | The path itself matched a secret rule, so the file is skipped and its path is masked in every artifact. | Rename the file; a path that looks like a key is treated as one. |
+| `binary` | Not text. | Nothing to do. |
+| `default-ignore` | A built-in rule, the preset's ecosystem ignores (`node_modules`, `__pycache__`, `target`, `vendor`, …), or the output directory. | A preset's ignores are not configurable; a custom `excludePatterns` can only remove more. |
+| `excluded` | Your own `excludePatterns`, or a path outside a non-empty `include` allow-list. | Remove the pattern, or widen `include`. |
+| `symlink` | Links are not followed (a directory link names its target in `detail`). | Snapshot the target. |
+| `outside-root` | A link whose target resolves outside the scanned root. | Keep the target inside the repository, or snapshot it directly. |
+| `gitignore` | A `.gitignore` excluded it, in a scan that is not reading git's index. | Remove the entry, or add the path to `include`. |
+| `read-error` | Unreadable file. | Check permissions. |
+| `not-file` | A directory, socket, FIFO. | Expected. |
+
+Inside a git repository the candidate list comes from git, which applies `.gitignore` before
+the scanner runs; those ignored paths are listed separately and recorded too, so a `.gitignore`d
+file or directory appears here with reason `gitignore` in either mode.
+
+`explain` can report two more, which never appear in `skipped[]` because they are about the
+path rather than about a candidate file:
+
+| `reason` | Meaning | Fix |
+| :--- | :--- | :--- |
+| `missing` | `no such file or directory, relative to the configured cwd` — nothing is at that path. | Check the path and `--cwd`. |
+| `not-discovered` | `exists but is not tracked or is otherwise not a candidate` — the file is there but the scanner never offered it, because it sits inside a directory the traversal skips, such as `node_modules`. | Copy it into the repository if you really need it in the snapshot; `include` cannot rescue a skipped directory. |
+
+Also check `include`: if it is non-empty it acts as an allow-list, and everything else is
+excluded.
+
+## The snapshot is too big
+
+- Lower the budget: `--max-part-bytes 120k`.
+- Exclude whole trees: `excludePatterns: ["vendor/**", "**/*.min.js"]` in the config.
+- Per-layer budgets: `budgets: { default: "120k", byLayer: { docs: 40000 } }`.
+- Skip artifacts you do not read: `--skip-artifacts navigation,projectTree,audit`.
+- Large files are already previewed rather than inlined; tune with `--large-file-bytes`.
+
+## Warnings that are working as intended
+
+These come from `generate`. They are recorded in `manifest.warnings` and repeated on stderr
+under a `- Warnings: N` line in the summary, and none of them stops a run:
+
+- `manifest.json is disabled: \`validate\` and \`report\` cannot inspect this snapshot.` — you
+  used `--skip-artifacts manifest`.
+- `parts are disabled but navigation.md is enabled: its links point at part files that were not written.`
+- `every artifact is disabled: only the .codebase-snapshot ownership marker will be written.`
+- A `hooks.afterGenerate` error is downgraded to a warning: the snapshot it was called for is
+  already written and is not lost.
+
+`validate` produces its own warnings, printed with a `⚠ ` prefix and never written to the
+manifest, because they describe the state of the repository rather than the snapshot:
+
+- `⚠ Working tree has uncommitted changes.`
+- `⚠ Snapshot was generated on branch "zeta" but the configured branch is "main".` — the
+  branch moved since the snapshot was written.
+
+## Detached HEAD
+
+On a detached HEAD (normal in CI) `manifest.git.branch` records the configured branch —
+`main` by default — because a detached HEAD cannot name one. Set `branch` in the config if
+your CI convention differs. This is not a warning condition.
+
+## Not a git repository
+
+Outside a repository the tool does not fail; it records what it can:
+
+```json
+{ "branch": "main", "commit": "unknown", "isDirty": false }
+```
+
+`branch` is the configured branch, `commit` is `"unknown"`, and `isDirty` is `false` because
+there is no tree to compare — not because the tree is clean. Read `commit` when you need to
+tell "no repository" from "clean repository", and do not treat `isDirty: false` alone as
+evidence that the snapshot was taken from committed state.
+
+## Still stuck
+
+```bash
+npx @ankurhalder/codebase-snapshot describe --format json > contract.json
+npx @ankurhalder/codebase-snapshot generate --dry-run --format json > dry-run.json
+```
+
+The first is the machine-readable contract, including a troubleshooting table. The second
+computes a full snapshot without writing anything, so you can inspect
+`config`, `counts`, `skipped` and `warnings` before committing to a run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankurhalder/codebase-snapshot",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "description": "Production-grade LLM codebase snapshot generator, auditor, and AST partitioner",
   "keywords": [
     "codebase",
@@ -32,7 +32,8 @@
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "bin": {
-    "codebase-snapshot": "./dist/bin.js"
+    "codebase-snapshot": "./dist/bin.js",
+    "snap": "./dist/bin.js"
   },
   "exports": {
     ".": {
@@ -75,9 +76,11 @@
     "pretest": "npm run build",
     "test": "node --test tests/*.test.js",
     "test:coverage": "node --test --experimental-test-coverage tests/*.test.js",
-    "prepare": "npm run build",
     "prepublishOnly": "npm run build",
-    "publish:create": "npm publish packages/create --access public"
+    "publish:create": "npm publish packages/create --access public",
+    "prepack": "npm run build",
+    "pack-check": "node scripts/pack-check.mjs",
+    "verify": "npm run check && npm run pack-check"
   },
   "dependencies": {
     "typescript": "^5.0.0"