Skip to content
| Marketplace
Sign in
Visual Studio Code>Other>Audit ScopeNew to Visual Studio Code? Get it now.
Audit Scope

Audit Scope

BonisTech

|
9 installs
| (0) | Free
Sidebar checklist of the files in an audit scope, driven by a SCOPE.md with commit frontmatter. Diffs between any two commits, from any two repositories.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

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.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft