Skip to content

The design language that makes your AI harness better at design.

JavaScript

Mark the bundle, goldens and call vectors -diff so PR diffs stay readable

Paul Bakaus8ce9b29db475
diff --git a/.gitattributes b/.gitattributes
index c6ac3081a..067df5cb7 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -4,3 +4,48 @@
# is also safe for any binary that lands under these trees.
tests/fixtures/** -text
tests/oracle/** -text
+
+# Machine-written files that a line diff cannot usefully show. `-diff` makes
+# `git diff`, `git show` and `git log -p` print "Binary files differ" instead
+# of the content; `linguist-generated` collapses them in GitHub's PR view.
+# The in-page bundle carries the wasm module as one ~2.7 MB line, and each
+# golden is a JSON object whose captured output is one escaped string, so a
+# one-character change rewrites the whole file in a diff. AGENTS.md
+# ("Reviewing a PR") has the commands for reading these changes on purpose;
+# `git diff --text` restores the raw diff. The bytes, merges and `git diff
+# --exit-code` checks are unaffected.
+crates/live/assets/detect-antipatterns-browser.js -diff linguist-generated
+tests/oracle/golden/** -diff linguist-generated
+tests/oracle/vectors/**/*.jsonl -diff linguist-generated
+
+# Written by `cargo xtask bundle` but small and worth reading: collapsed on
+# GitHub, kept diffable locally.
+crates/live/assets/antipatterns.json linguist-generated
+
+# Provider output that `bun run build:release` writes and
+# .github/workflows/sync-generated-output.yml commits back to main (keep this
+# list in step with GENERATED_PATHS there). Collapsed on GitHub only.
+.agent/** linguist-generated
+.agents/** linguist-generated
+.codex/** linguist-generated
+.claude/** linguist-generated
+.cursor/** linguist-generated
+.dsh/** linguist-generated
+.gemini/** linguist-generated
+.github/agents/** linguist-generated
+.github/hooks/** linguist-generated
+.github/skills/** linguist-generated
+.grok/** linguist-generated
+.hermes/** linguist-generated
+.kiro/** linguist-generated
+.opencode/** linguist-generated
+.pi/** linguist-generated
+.omp/** linguist-generated
+.qoder/** linguist-generated
+.rovodev/** linguist-generated
+.trae/** linguist-generated
+.trae-cn/** linguist-generated
+.veto/** linguist-generated
+.vibe/** linguist-generated
+plugin/** linguist-generated
+cursor-plugin/** linguist-generated
diff --git a/AGENTS.md b/AGENTS.md
index 38afae21f..68e767cf1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,7 @@
## Build, Test, and Development Commands
-- `cargo build --release -p impeccable` - build this checkout's runtime into `target/release/impeccable`.
+- `cargo build --release -p impeccable` - build this checkout's runtime into `target/release/impeccable`. This one binary is also the detector (`impeccable detect`); there is no separate detector binary. Point `IMPECCABLE_BIN` at it.
- `cargo test --workspace` - run the Rust workspace tests.
- `bun run build` - source-first build: regenerate `dist/`, derived site assets, and validation output without syncing tracked harness folders.
- `bun run build:release` - release/distribution build: run the full build and sync tracked root harness folders plus `plugin/`.
@@ -70,6 +70,27 @@ Recent history favors short, imperative subjects such as `Fix: ...`, `Add ...`,
**Do not bump manifest versions or add changelog entries in a feature PR.** Bumping is a release step: a version in a feature branch conflicts with every other open branch, and a changelog entry describes a release that has not happened yet. Land the code; the maintainer bumps `package.json` / `.claude-plugin/plugin.json` / `extension/manifest.json` and writes `site/pages/changelog.astro` when cutting the release (see **Releases**). The only PR that touches a manifest version is one whose purpose is the release itself.
+## Reviewing a PR
+
+The in-page bundle, the oracle goldens and the call vectors are marked `-diff` in `.gitattributes`: one bundle line is the whole wasm module, and each golden's output is one escaped JSON string, so their raw diffs run to megabytes. Read the PR's files from a checkout instead of `git show <ref>:<path>` slices, and read the generated files on purpose:
+
+```sh
+gh pr diff <n> --name-only # what changed
+gh pr diff <n> --exclude 'tests/oracle/golden/*' --exclude 'tests/oracle/vectors/*' --exclude 'crates/live/assets/detect-antipatterns-browser.js'
+git fetch origin pull/<n>/head && git worktree add --detach "$TMPDIR/pr-<n>" FETCH_HEAD # Read and grep the PR's files here
+git -C "$TMPDIR/pr-<n>" merge-tree --write-tree --name-only origin/main HEAD # tree id, then any files that conflict with main
+gh pr checks <n>
+```
+
+`gh pr diff` ignores `.gitattributes`, hence the `--exclude` flags; a local `git diff` honours the attributes of the checked-out tree, so a branch cut before they landed still prints the raw diff (`-- . ':!tests/oracle/golden' ':!crates/live/assets'` trims it). `git grep` reports these files as binary; use `rg` or `git grep -a`. To review a changed golden by hand, decode it on both sides:
+
+```sh
+g='to_entries[]|"== \(.key)\n\(.value|if type=="string" then . else tojson end)"'; f=tests/oracle/golden/<case>.json
+diff <(git show origin/main:$f 2>/dev/null | jq -r "$g") <(git show HEAD:$f | jq -r "$g") # in the PR worktree; a new case diffs against nothing
+```
+
+Remove the worktree when done (`git worktree remove "$TMPDIR/pr-<n>"`).
+
## Contributing, Issue, and PR Guidelines
This repo is issue-first for outside contributions. If you are not `pbakaus` or `abdulwahabone`, do not open a PR unless a maintainer has first discussed the change in an issue and asked for, or clearly approved, a PR. For unapproved work, open an issue or comment on an existing issue and wait for maintainer direction. Unsolicited PRs may be closed without review.
diff --git a/CLAUDE.md b/CLAUDE.md
index 828f63255..db1bff074 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -153,6 +153,10 @@ AI agents must disclose AI assistance in commits, PR descriptions, comments, and
This contribution was prepared by an AI agent that tried to ship unchecked vibes across a human boundary. Impeccable asks for an issue and maintainer approval first.
```
+### Reviewing a PR
+
+The in-page bundle (`crates/live/assets/detect-antipatterns-browser.js`), the oracle goldens and the call vectors are `-diff` in `.gitattributes`, because their raw diffs run to megabytes. Follow **Reviewing a PR** in `AGENTS.md`: `gh pr diff <n> --exclude` those paths, check the PR head out into a detached worktree to read its files, and decode a changed golden with the `jq` recipe there rather than reading its raw diff.
+
## Testing
```bash