Audit Scope
A sidebar checklist of the files under review. Point it at a markdown file
listing paths, tick them off as you go, and let it open each one the way that
makes sense for the commits you are reviewing between.
Plain JavaScript, no dependencies, no build step.
Where the data comes from
One markdown file per review, and nothing else. The extension never infers a
scope, never reads a project's own conventions, and holds no state of its own —
the markdown file is the whole input and the whole output.
It is found by glob (auditScope.glob, default **/SCOPE*.md). Several
matching files show as several roots, so one workspace can carry several
reviews at once. auditScope.ignore leaves some of them out — by default
anything under a .claude directory. Each entry is a name (.claude: that
directory or file anywhere), a path from the workspace folder (audit/old:
that directory and all below it; audit/old/SCOPE.md: that one file), or a
glob (docs/**).
Everything about how a file opens comes from that file's frontmatter:
---
title: Payments review
base: v1.4.0
head: release/1.5
---
## Ledger
- [ ] `src/ledger/posting.go`
- [-] `src/ledger/journal.go` — half way through
- [x] `src/ledger/balance.go` — reviewed, no findings
## API
- [ ] `src/api/handlers.go`
| Key |
Meaning |
Missing? |
title |
Shown as the tree root |
Falls back to the filename |
base |
Left-hand side of the diff |
Files just open — no diffing |
head |
Right-hand side |
base is diffed against the working tree |
repo |
Path to the git repo, relative to the scope file |
The scope file's own repo — usually omit it |
base-remote |
Repository to fetch base from, if not this one |
base is resolved locally |
head-remote |
Repository to fetch head from, if not this one |
head is resolved locally |
remote |
Fallback for both of the above |
— |
Paths listed in the scope file resolve against the git repository root, not
against the scope file's directory, so the same list works whether the file sits
at the top of the repo or in a subdirectory. That is why repo is almost never
needed: set it only when the scope file lives outside the repository it
describes. A repo that does not point at a git repository falls back to the
scope file's own repo and says so on the root node rather than silently
resolving every path against the wrong place.
base and head take anything git rev-parse accepts — a sha, a tag, a
branch, origin/release-2, a local ref — or a link to a commit in another
repository (see below). A value that does not resolve is reported on the root
node rather than failing silently.
Commits from other repositories
The two ends of a diff do not have to live in the same repository. A client
migrates from client/repo-a to client/repo-b and the review is "what
changed in the move"; or the base is a tag in an upstream fork the local clone
has never fetched. Either end can name where it comes from:
---
title: Migration review
base: https://github.com/client/repo-a/commit/3f2a9c1
head: https://github.com/client/repo-b/tree/main
---
A forge link — /commit/<sha>, /tree/<branch-or-tag>, GitHub, GitLab
(/-/commit/) or Bitbucket (/commits/) — carries its own repository. The
same thing spelled out, which also works for ssh URLs, local paths and remote
names the local repo already has:
---
base: v1.4.0
base-remote: git@github.com:client/repo-a.git
head: main
head-remote: ../repo-b-checkout
---
remote: on its own applies to both ends. base-remote / head-remote win
over a link's own repository, and a link wins over remote:.
What happens: the commit is fetched into the scope file's repository (the one
repo: or the fallbacks resolve to) under refs/audit-scope/…, where it
cannot collide with your branches and will not be garbage-collected. Once both
commits are objects in one repository, git diffs them like any other pair —
unrelated histories included. A full sha that is already present locally is
not fetched at all. A branch or tag name is fetched again on Reload Scope
Files; the routine reloads the file watcher triggers reuse what was fetched
during this session. Audit Scope: Forget Fetched Remote Commits deletes the
refs/audit-scope/… refs again when a review is over.
Fetching uses your normal git setup — credential helper, ssh agent — and never
prompts; a remote that would need an interactive login shows up as a problem on
the root node instead. A git@… or https://… value that names a repository
but no commit is reported too, rather than being treated as a ref name.
Because the checkout may then be a different repository from the one head
comes from, "is this file missing?" is judged against the head commit when
there is one, and against the working tree only when there is not.
Frontmatter is optional at every level. A plain checklist with no ---
block works fine; it simply opens files instead of diffing them. That is also
the graceful path for a list you did not write for this extension — drop the
glob on it and you get a clickable, tickable tree immediately, then add
frontmatter later if you want diffs.
If several scope files in one repo share the same commits, set
auditScope.base / auditScope.head / auditScope.repo in workspace settings
instead of repeating them. Frontmatter always wins over settings, so a scope
file that names its own commits stays portable between machines and people.
Generating the markdown is not this extension's job. If your scope lives
somewhere else — a ticket, a spreadsheet, another document in the repo — write a
small script that emits the markdown and keep it with that project. The
extension reads the result and stays out of it.
What counts as a file
Headings (# … ######) become collapsible groups. Headings with no files
under them are dropped, so prose sections do not clutter the tree.
A list item counts as a file when it starts with a checkbox — [ ], [-] or
[x] — followed by a backticked path, or a bare path containing a separator.
A bullet without a checkbox is prose, however much it looks like code: a note
such as - `Self::owner_of` stays a note. Anything inside a fenced code
block is ignored too. Text after the path becomes the item's tooltip.
Files that moved
When a file is not at the same path at both ends — renamed, or split into
pieces — say what to diff it against with new:old:
- [ ] `src/chunks/Vault.sol:src/Big.sol`
- [ ] `src/chunks/Oracle.sol:src/Big.sol`
- [ ] `src/Token.sol:contracts/Token.sol`
The left side is the file at head — it is what the tree shows, ticks and
opens — and the right side is where it was at base. The row shows
← old/path and the diff stat is for that pair, so two pieces of one original
can each be reviewed against it. If the old path is not present at base the
file opens plainly, and the tooltip says so.
How a file opens
| Situation |
What happens |
No base |
Opens the working-tree file |
base + head, file changed in that range |
Diff, base ↔ head |
base + head, file added in that range |
Opens normally — nothing to compare against |
base + head, file unchanged in that range |
Opens normally. Set auditScope.plainWhenUnchanged: false to get an empty diff instead |
base + head, file deleted at head |
Opens the base version alone |
base, no head |
Diff, base ↔ working tree |
| File not in the working tree |
Falls back to its content at head, or at base |
Both sides of a diff are served read-only out of git, so the commit you review
does not have to be the one you have checked out. Open File (No Diff) in the
context menu always gives you the editable working-tree file.
Diff layout
Diffs open side by side by default. auditScope.diffLayout changes that:
| Value |
|
sideBySide (default) |
Two columns, and stop VS Code collapsing to inline in a narrow editor |
inline |
The single-column inline view |
editorDefault |
Leave diffEditor.* alone and use whatever you already have set |
The right-click menu has Open Diff: Side by Side and Open Diff: Inline,
which override the setting for one file. Unlike a click, they always diff — so
they also work on a file that would otherwise open plainly because it is new or
has no hunks.
VS Code has no per-diff layout option — vscode.diff takes only
TextDocumentShowOptions — so the layout is a global editor setting. Anything
other than editorDefault therefore writes diffEditor.renderSideBySide to
your user settings, and for side-by-side also
diffEditor.useInlineViewWhenSpaceIsLimited. Each key is written only when it
differs from what you have, and skipped entirely if your VS Code build does not
register it. Use editorDefault if you would rather the extension never touched
those settings.
That second key is why a side-by-side diff sometimes "will not stay" side by
side: with it at its default, VS Code collapses to inline whenever the editor is
narrower than diffEditor.renderSideBySideInlineBreakpoint (900px), which is
easy to hit with the sidebar open.
Layouts
The layout icon in the view header switches how the files are arranged:
| Layout |
What you see |
| Checklist (default) |
The scope file as written: headings, then files, each with its folder in grey |
| Folders |
One folder tree over every file in the scope, headings ignored |
| Folders by heading |
The headings, with a folder tree under each |
A folder with nothing but a single subfolder is folded into it, so
contracts/common/guard/src is one row rather than four. Folder rows carry
their own done/total and checkbox, and Mark Reviewed and friends work on
them, so a whole directory can be ticked at once. The filter prunes the tree:
folders with no matching file disappear.
The choice is remembered per workspace. auditScope.layout sets the starting
layout for a workspace that has not chosen one yet, and the three layouts are
also commands (Audit Scope: Layout: …) for keybindings and the palette.
Finding a file
The search icon in the view header — or Ctrl+F
(⌘F) while the tree has focus — opens Filter Files. The tree
narrows as you type, matching anywhere in the path, not just the file name:
| Query |
Shows |
onramp |
every path containing it, in any case |
pools lock |
paths matching every word, in any order |
pools/*.rs |
* matches anything, ? one character |
Big.sol |
a moved file also matches by its path at base |
Groups and scope roots with nothing left are hidden, the header says how many
files are showing, and a clear icon appears next to the search one. Enter keeps
the filter; Escape puts back whatever was there before. While a filter is on,
ticking a group — or Mark Reviewed and friends on a group or the root —
reaches only the rows shown, so marking a group done while looking at two of
its twenty files does not tick the other eighteen.
The sidebar also follows what you are reading: when the active editor shows a
file in scope — the working-tree file, or either read-only side of a diff — its
row is selected. This only happens while the view is visible, so it never pops
the sidebar open; auditScope.revealActiveFile: false turns it off.
Progress
Each file is in one of three states, and clicking its box cycles through them:
| Marker |
State |
In the tree |
[ ] |
not reviewed |
unchecked |
[-] |
partially reviewed |
unchecked, half-filled icon, partial in the description |
[x] |
reviewed |
checked |
Click once for partial, again for done, a third time to clear. The right-click
menu has Mark Reviewed, Mark Partially Reviewed and Mark Not
Reviewed to jump straight to a state; on a group or the root they apply to
every file underneath. Ticking a group's own box marks all of its files done,
or clears them all.
Progress is written back as the marker in the scope file itself, so it lives in
git and everyone on the review sees it. Every other byte of the file is left
untouched. Set auditScope.persist to workspaceState to keep progress local
to your machine instead.
The view header shows done/total and the activity-bar badge shows how many
files are left; partially reviewed files count as not done.
Settings
| Setting |
Default |
|
auditScope.glob |
**/SCOPE*.md |
Which files to load |
auditScope.exclude |
**/{node_modules,target,.git}/** |
Glob of paths to skip while searching |
auditScope.ignore |
[".claude"] |
Scope files to leave out: names, paths, exact files or globs |
auditScope.base |
"" |
Fallback base for files without frontmatter (a rev or a forge link) |
auditScope.head |
"" |
Fallback head for files without frontmatter (a rev or a forge link) |
auditScope.repo |
"" |
Fallback repo path for files without frontmatter |
auditScope.diffLayout |
sideBySide |
sideBySide, inline or editorDefault |
auditScope.persist |
scopeFile |
scopeFile or workspaceState |
auditScope.checkForUpdates |
true |
Check GitHub for a newer release at startup |
auditScope.showDiffStat |
true |
Show +added −removed beside each file |
auditScope.revealActiveFile |
true |
Select the row of the file in the active editor |
auditScope.layout |
list |
Starting layout: list, tree or groupedTree |
auditScope.plainWhenUnchanged |
true |
Avoid empty diffs for files with no hunks |
Installing
The extension is distributed as a .vsix on the repository's Releases page.
gh release download --repo cre-mer/vscode-audit-scope --pattern '*.vsix' --clobber
code --install-extension audit-scope-*.vsix
After the first install it keeps itself current: shortly after startup it asks
GitHub whether a newer release exists and offers to install it. Audit Scope:
Check for Updates does the same on demand, and auditScope.checkForUpdates
turns the automatic check off.
That check shells out to the gh CLI rather than calling the API directly, so
it works while the repository is private. If gh is missing or logged out the
check stays quiet — it is a convenience, never a dependency.
A .vsix installed by hand is outside any marketplace, so VS Code will not
update it on its own. That is what the built-in check is for. If the
repository is ever made public, publishing to the Marketplace or Open VSX
would replace this with VS Code's native update mechanism.
Running from source
No build step — it is plain JavaScript with no dependencies. Open the folder
and press F5 for an Extension Development Host, or symlink it:
ln -s "$PWD" ~/.vscode-server/extensions/cre-mer.audit-scope-0.1.0
# or, for a local (non-remote) VS Code:
ln -s "$PWD" ~/.vscode/extensions/cre-mer.audit-scope-0.1.0
To build a .vsix yourself:
npx @vscode/vsce package --no-dependencies
Releases
Every push to main cuts one. CI runs the tests, bumps the version, tags it,
packages the .vsix and attaches it to a GitHub Release — which is where the
update check looks.
The bump is a patch by default. Put [minor] or [major] anywhere in the
commit message to bump further.
Tests
npm test # or: node test/parse.test.js && node test/hydrate.test.js
parse.test.js covers the parser, the checkbox rewriter, the three-state
cycle, the filter's matching rules, the folder-tree builder, forge-link parsing, the open-decision table
and the git helpers, including fetching from another repository.
hydrate.test.js drives the tree provider itself against a stubbed vscode
module, covering repo-root resolution, commits fetched from a second
repository, checkbox event handling, filtering, the three layouts, the parent
chain reveal walks, matching an open editor to its row, and problem reporting.
Both are self-contained: they build throwaway git repositories in a temp
directory (fetches go between two of them), so they depend on no particular
project, need no editor and never touch the network.