Code Assurance
Sustained confirmation of code quality and correctness.
Code review approves a change once, here and now. Code Assurance keeps
confidence in code over time:
- a person checks a piece of code and confirms that it is correct,
taking responsibility for that confirmation;
- the confirmation is stored in the repository, tied to that exact code;
- when the code changes later, the confirmation becomes outdated;
- the changed code is confirmed again, by the same person or someone else.
The result is a continuous history of trust in the code, not a one-time
pull request approval.
Getting started
- Open a git repository and run Code Assurance: Initialize in this
repository. It creates
.code-assurance/ and adds a merge rule to
.gitattributes.
- Select code, right-click and pick Code Assurance → Confirm selected
lines, or put the cursor in a function and pick Confirm enclosing
function. Add an optional comment.
- Commit
.code-assurance/ together with your code. Teammates see your
confirmations after they pull.
Statuses
| Mark |
Status |
Meaning |
| 🟩 |
confirmed |
The confirmed code is present and unchanged. |
| 🟧 |
outdated |
The code changed since it was confirmed (or moved away from its surroundings). |
| 🟨 |
ambiguous |
The unchanged code now exists in several identical copies and none can be singled out. |
Statuses are computed from the code every time and are never stored or set
by hand.
Positions follow the code
Each confirmation remembers the commit it was made on and, for code that
was not committed yet, a compact description of the uncommitted changes
(line fingerprints, never the code itself). From these the confirmed text
is rebuilt and compared with the current text using a line diff, so:
- adding or removing lines above or below confirmed code moves its marks
with the code;
- an edited range is shown as outdated exactly where the code is now;
- identical copies of the code elsewhere do not confuse it.
When the commit is not available (a shallow clone, rewritten history) the
code is found by its content and surroundings instead.
Commands
Right-click in an editor → Code Assurance, or the Command Palette:
| Command |
Languages |
| Confirm selected lines |
all files |
| Confirm enclosing function |
JavaScript, TypeScript, Python, Go, Rust |
| Confirm enclosing type |
JavaScript, TypeScript, Python, Go, Rust |
| Confirm enclosing impl block |
Rust |
| Confirm enclosing module |
Rust |
| Confirm whole file |
all files |
| Confirm again |
all files |
| Withdraw my confirmation |
all files |
| Confirmation actions at cursor… |
all files |
| Move confirmations of a renamed file |
all files |
"Type" covers classes, interfaces, structs, enums and traits. Functions
include methods, constructors, function-valued variables
(const f = () => …), Python lambdas and Rust macros.
Hovering confirmed code shows who confirmed it, when, on which commit and
with which comment, with links to confirm again, resolve, see the diff since
confirmation and the history of the file. A CodeLens above each confirmed
span shows the same summary.
Confirming a span that fully encloses your earlier confirmations (or the
same symbol) replaces them; you are asked first when they had comments or
were outdated. Partly overlapping confirmations stand side by side.
Side bar
The Coverage view works like the Search view: the filters are on top
and the files they let through are listed right below them.
- Filter by path: a regular expression matched against the
repository-relative path. While a path or reviewer filter is set, folders
open by themselves (up to 300 files).
- The toggle inside the input keeps only files with confirmations.
- Reviewer narrows the files and the reviewers list to one person.
Below the filters: the share of code lines confirmed, every tracked file
with its coverage rolled up through folders, the reviewers with the files
they confirmed, and confirmations of files that no longer exist. Filters
never change a percentage. Blank lines are not counted. The view title has
buttons to hide the marks in editors while you write code, refresh, clear
the filters and collapse all folders; Code Assurance: Filter coverage
moves the focus to the filter. The tree works with the keyboard: arrows,
Home/End, Enter.
Files can be left out of coverage with .code-assurance/ignore
(gitignore syntax: *, **, ?, trailing /, leading !).
Settings
| Setting |
Values |
Default |
codeAssurance.marks.position |
gutter | text | background |
background |
gutter: a thin bar at the right edge of the gutter next to the line
numbers, over the breakpoint column. A breakpoint dot on the same line
stays visible.
text: a bar at the start of each line inside the text area; the gutter
stays free for breakpoints and other extensions.
background: a faint tint behind each whole line. The colors are almost
transparent, so selections, the current line highlight and search matches
stay visible on top of it.
Colors (workbench.colorCustomizations): codeAssurance.confirmed,
codeAssurance.outdated, codeAssurance.ambiguous for the bars at the
start of lines and the overview ruler; codeAssurance.confirmedBackground,
codeAssurance.outdatedBackground, codeAssurance.ambiguousBackground for
the line background. The gutter bars use fixed colors.
Storage
.code-assurance/
config.json
ignore
records/<path of the source file>/<author id>.jsonl
Records are append-only JSON lines, one file per person and source file, so
branches merge without conflicts (merge=union). Nothing is ever rewritten
or deleted: withdrawing a confirmation appends a tombstone. Every record is
treated as untrusted input: a person can only replace or withdraw their own
confirmations, and record text is escaped wherever it is shown.
Development
Requires Node.js 26 and npm 11 (.nvmrc; nvm use picks the version) and
just.
just install # dependencies
just check # format, lint, types, unit tests, bundle
just run # VS Code window with the extension loaded
just package # .vsix
just # all recipes
src/core is plain Node with unit tests in test/core; src/vscode
contains the editor integration.
Formatting and linting use Biome (biome.json;
the biomejs.biome editor extension applies it on save), types are checked
by TypeScript 7.
just test-int runs the extension in a real VS Code window with a
throw-away repository and profile. Symbol commands for Python, Go and Rust
are checked with the language extensions installed in your VS Code
(ms-python.python with Pylance, golang.go with gopls,
rust-lang.rust-analyzer with cargo); they are linked into the test
profile, and a language whose extensions are missing is skipped.
VSCODE_EXTENSIONS points to another extensions folder, VSCODE_BIN to
another editor binary. With REQUIRE_LANGUAGES=1 a skipped language
fails the run.
Continuous integration and releases
GitHub Actions (.github/workflows):
- CI on every push to
main and every pull request: format, lint,
types, unit tests and the .vsix package (kept as a build artifact),
npm audit, and the integration test in a downloaded VS Code under
Xvfb with the Python, Go and Rust extensions installed, where every
language is required.
- Release on a
v* tag: checks the tag against package.json, runs
the checks again, publishes to the Visual Studio Marketplace and attaches
the .vsix to a GitHub release.
To release: move the [Unreleased] notes in CHANGELOG.md under the new
version, then
just release patch # or minor / major: commit "release: X.Y.Z" and tag vX.Y.Z
git push --follow-tags # the tag starts the Release workflow
Publishing uses Marketplace Trusted Publishing (OIDC), so no access
token is stored. The yurii-musolov publisher needs a Trusted Publishing
policy (marketplace.visualstudio.com/manage → publisher → Trusted
Publishing → Create) with the repository owner and name, the workflow
release.yml and the environment marketplace. For a private repository
the workflow has to run within 48 hours of creating the policy.
Dependabot proposes weekly updates of npm packages and actions; the VS Code
and Node.js type packages are raised by hand together with
engines.vscode.
License
MIT