Repository navigation
Releases
supdoc v0.6.0
supdoc v0.6.0 checks code blocks in SQL, HTML, Makefile and XML end to end, and adds npm packages that carry the release binaries. The lockfile format is unchanged. What shipped is in the v0.6.0 milestone.
Install
- From v0.6.0 on,
npx supdocruns supdoc andnpm i -g supdocinstalls it. Thesupdocpackage pulls in one@supdoc/<os>-<cpu>package holding the release binary for macOS, Linux (statically linked) or Windows, on x64 or arm64. Nothing is compiled and no install script runs (#402). supdoc upgraderefuses a binary that an npm package installed and prints the npm command to run instead, so it never rewrites a file insidenode_modules.
More code-block languages
Each language is turned on by its own table, such as [features.code-blocks.xml].
- SQL blocks are now linted with sqruff as well as formatted. An unparsable block fails, and a
noqacomment can't hide a parse error (#437). - HTML blocks are now linted with biome as well as formatted with superhtml (#436).
- Makefile blocks (tagged
make,makefile,Makefileormk) are formatted with mbake and linted with checkmake. supdoc never asks mbake to validate, which would runmake, and always passes each tool a vetted copy of the project's config (#439). - XML blocks (tagged
xml,svg,xsd,xsl,xsltorxhtml) are linted and formatted with xmllint, without network access or catalogs. A block whose DOCTYPE names an external identifier or that declares an entity is left unchecked with a warning (#440).
Also
- The remaining code-block read guards refuse a root that can't be resolved, and tests pin it (#454).
Full changelog: v0.5.0...v0.6.0
v0.5.0
supdoc v0.5.0 ships prebuilt binaries for eight targets, builds and runs on Windows, and checks code blocks in four more languages. The lockfile format is unchanged. The JSON output of supdoc upgrade gains fields; nothing is removed. Most of what shipped is in the v0.5.0 milestone; SQL and HTML formatting are the first parts of #437 and #436, which stay open for v0.6.0.
Upgrading
- A v0.4.0 release binary can't upgrade itself.
supdoc upgradefor a downloaded binary starts at v0.5.0, so download the v0.5.0 archive by hand once. Acargo installupgrades through cargo as before (#370).
Install
- Each release carries prebuilt archives for eight targets: macOS (arm64, x86_64), Linux (arm64, x86_64, each glibc and musl) and Windows (x86_64, arm64), with a
SHA256SUMSfile and build attestations (#368). cargo binstall supdocinstalls the prebuilt binary (#405).- From v0.5.0 on, releases are immutable: a published release's assets can't be replaced (#403).
supdoc upgrade [VERSION]now also upgrades a downloaded release binary. It fetches the archive with the system curl over HTTPS from GitHub, checks it againstSHA256SUMS, and replaces the binary in place; on Windows the old one is left assupdoc.exe.old, which a laterupgraderemoves. Acargo installstill upgrades through cargo, except on Windows, whereupgradeprints the cargo command to run from another shell. Any other install is refused with the manual step. Without--yesit only previews (#370, #431).supdoc upgrade --jsongainsmethod(cargoorrelease-binary),asset,sha256andnotes.
Windows
- supdoc builds and its test suite passes on Windows x86_64 and arm64, and both are required CI checks. The trust store and the code-block cache live under
%LOCALAPPDATA%\supdoc(#369).
More code-block languages
Each language is turned on by its own table, such as [features.code-blocks.sql].
- CSS and SCSS blocks are formatted and linted with biome (#441).
- Dockerfile blocks (also tagged
containerfile) are linted with hadolint and formatted with dockerfmt (#438). - SQL blocks are formatted with sqruff.
dialectin[features.code-blocks.sql]picks the dialect (ansiby default), and a block tagged with a dialect, such aspostgresortsql, uses it whatever the setting says. There is no built-in SQL linter yet (#437). - HTML blocks are formatted with superhtml. A block holding a
<textarea>,<xmp>,<listing>,<plaintext>or<noscript>, or a<script>or<style>whose body superhtml would rewrite, is left unformatted with a warning. There is no built-in HTML linter yet (#436). linter = "markdownlint-cli2"in[features.code-blocks.markdown]is refused with an explanation: markdownlint-cli2 can't apply its per-directory config to a block passed on stdin. Use rumdl or a customlinter = { command = [...] }(#325).
Also
supdoc skill install --target agentsor--target claudewrites only that one skill copy (#401).- TypeScript, TSX and JavaScript get symbols for the keys of a default-exported object (#404), and for a
namespace A.B.C.Dof four to ten parts (#249). supdoc initworks on a filesystem without hard links (#250).check,update,fixandlistcheck a path as typed:nope/..exits 2 withcli-path-missingwhennopedoesn't exist, instead of checking the whole project, and so doesfile.md/..(#248).- The
link-outside-roothelp for a namespace link that climbs out of its namespace no longer suggests moving the config (#251). - Code-block read guards use one shared containment check (#371), and raw path joins outside the path module fail clippy in CI (#357).
Full changelog: v0.4.0...v0.5.0
supdoc v0.4.0
supdoc v0.4.0 adds trust, code-block checking for seven more languages, links to keys in JSON, YAML and TOML files, and supdoc upgrade. The lockfile format is unchanged. The JSON output gains fields and two new commands' schemas; nothing is removed. Everything shipped is in the v0.4.0 milestone.
Upgrading
- Links into JSON, YAML and TOML files become tracked. They were left untracked before. Each one shows as
link-newuntil it is recorded, so runsupdoc update --yesonce after upgrading, orcheckfails (#245). - A checkout's
[limits]can't raise a ceiling unless you trust it. A raise or0in an untrusted checkout is held back, andsupdoc config showsays so. The flag and environment variable always win (#348). from(...)oruses(...)starting with//is refused as climbing out of the project, like any path outside the root (#350).
Trust
supdoc trustrecords that a checkout may run tools that load its own code;--revokeremoves it, andSUPDOC_TRUST=1grants it for one run. No file in the checkout can grant it (#237).- In a trusted checkout, clippy lints Rust blocks against the project's build (#238). pylint (Python), prettier (TypeScript, JavaScript, JSON, YAML and Markdown) and eslint (TypeScript and JavaScript) can be selected in a language's table; they run only in a trusted checkout and are found in the project's
.venv/binornode_modules/.binfirst (#239). - Custom formatter and linter commands:
formatter = { command = [...] }andlinter = { command = [...], diagnostics = "gnu" }run only in a trusted checkout (#240).
More code-block languages
- TypeScript and JavaScript (biome), Go (gofmt, go vet in a module supdoc owns), Markdown (rumdl), JSON (biome), YAML (yamlfmt, yamllint) and TOML (tombi, offline) blocks are formatted and linted without trust (#242, #243, #244, #246).
- Code blocks in Python docstrings, JSDoc and TSDoc comments (including a fenceless
@example) and Go doc comments are checked (#247). fragment(<kind>)marks a block that shows statements, an expression, object entries or JSX children, and its tools check it in a fixed frame instead of failing to parse (#281).
Links to data files
- A link can name one key:
[version](Cargo.toml#package.version),[test job](.github/workflows/ci.yml#jobs.test). Arrays use 0-based indices; a.or~in a key is written~1or~0.[limits] max-key-segmentsbounds a hostile file (#245).
supdoc upgrade
supdoc upgrade [VERSION]reinstalls supdoc throughcargo install --locked, showing the plan first and acting only with--yes. It works for cargo installs only (#241).
Hardening
- Every path supdoc builds from file content (the lockfile, config, doc links,
from(...)/uses(...), git metadata, tool configs and output) goes through a validated type, and every write, rename or delete is checked for containment just before it happens (#336). [limits] max-file-sizecaps every file supdoc reads (#296).
Also
- The README is rewritten as a front page; detail moved to each command's
--help(#299). - Tests that depended on machine speed no longer fail under load (#322).
Full changelog: v0.3.1...v0.4.0
Binaries (added 2026-11-06). macOS and Linux archives built from this tag by the release workflow are attached, with SHA256SUMS and build-provenance attestations (gh attestation verify <archive> -R aidenzepp/supdoc). Windows binaries, and supdoc upgrade for a downloaded binary, start at v0.5.0, so a v0.4.0 binary is upgraded by downloading a newer one.
supdoc v0.3.1
supdoc v0.3.1 fixes two things in v0.3.0's code blocks: the summary of steps that didn't run, and the README's description of which tools run. Output schema, lockfile and config are unchanged.
Fixed
- Each not-run reason gets its own count. v0.3.0 gave every step that didn't run one label, so a project with one missing shell tool read "62 lint not run (tool missing)" when 57 of those Rust blocks were waiting on
supdoc trust. The summary now lists each reason with its own count, for example "57 lint not run (clippy needs trust) · 5 lint not run (tool missing)" (#227). - The README no longer says clippy runs. clippy is built, but it runs only in the project tier, which arrives with
supdoc trust. Until then a Rust block's lint step counts as not run. The README now lists only the tools that run: rustfmt, shfmt, ruff, black and shellcheck (#225).
Also
- supdoc now checks the code blocks in its own vendored skills (#226).
supdoc v0.3.0
supdoc v0.3.0 adds code blocks: it checks the fenced code in your Markdown and in Rust doc comments, keeps excerpts in sync with the code they quote, and formats and lints blocks with your project's own tools. Linking works as before, and the lockfile keeps schema_version = 2.
Code blocks
Turn the feature on with a [features.code-blocks] table, and each language with its own table: [features.code-blocks.rust], .shell or .python. A block in a language without a table is counted as not checked. [features.code-blocks] has its own include and exclude, which default to the top-level ones, so you can link everywhere and check code only in, say, docs/ and skills/.
- Excerpts that can't drift.
```rust from(src/lib.rs#Limits.resolve)makes a block exactly that symbol's text. You can repeatfrom(...); the excerpts are joined in order by a blank line. A stale block iscode-block-stale, andsupdoc fixrewrites it. - Hand-written blocks you want to keep honest.
uses(PATH#SYMBOL)tracks a symbol like a link, in any language.supdoc checkflags the block for review when the symbol changes, andsupdoc updaterecords the change. - Formatting with rustfmt (under your pinned toolchain and edition), shfmt (with your shell dialect), and ruff format or black. Unformatted blocks are
code-block-unformatted, andsupdoc fixapplies the formatter's output. Output that would close the fence or edit outside the block is refused. - Linting with ruff check for Python and shellcheck for shell. Each finding is
code-block-lintat the doc's own line and column. - Explicit switches, never automatic. supdoc never rewrites a block behind your back or invents a skip.
- Per block:
ignore(<reason>),lint(off: <reason>),format(off: <reason>), orlint(full)/format(full)to override the config. - Per tool:
[features.code-blocks.<language>.<tool>] lint/format = "full" | "off". - A step that didn't run is always counted and named, for example "1 lint not run (clippy needs trust)".
- Per block:
- Safe on untrusted docs. Tools are found on
PATH, never inside the checkout. Each one runs in its own process group, from an empty private directory, with a cleared environment, the block on stdin, capped output and a per-block timeout ([limits] code-block-timeout). Ctrl-C or SIGTERM stops every tool, and supdoc then ends by that signal. - Fast. Results are cached outside the checkout, and distinct blocks run in parallel.
Not in this release
- Clippy for Rust blocks is built, but it runs only in the project tier, which arrives with
supdoc trust. Compiling an untrusted block needs an OS-level file sandbox first. Until then, a Rust block's lint step reads "not run (clippy needs trust)". - rustdoc-style hidden
#lines aren't supported: a#line is ordinary code. Write context visibly, or excerpt it withfrom(...).
New codes
code-block-stale,-source-missing,-uses-new,-uses-changed,-uses-obsolete;code-block-unformatted,-parse,-lint;code-block-tool-missing,-tool-failed,-tool-timeout;code-block-not-checked,-unknown-attribute,-missing-reason,-fix-unsafe.
Every one has a help that names a command or value.
Also fixed
supdoc v0.2.1
supdoc v0.2.1 makes check faster by compiling each language only when a file of that language is read. Output, the lockfile and the JSON schema are unchanged from v0.2.0.
Faster
Before, every run compiled the queries for every built-in language at startup. Now each language compiles the first time a file of that language is read, at most once per run (#177).
Median check --quiet on an Apple M4 Pro, measured with hyperfine:
| project | v0.1.2 | v0.2.0 | v0.2.1 |
|---|---|---|---|
| ripgrep | 247.5 ms | 290.1 ms | 241.7 ms |
| supdoc | 218.1 ms | 237.1 ms | 217.8 ms |
This recovers the startup cost v0.2.0 added and keeps its lower memory use. check --json output is byte-identical to v0.2.0 on both projects.
Changed
- A built-in language whose query fails to compile still fails the run with
read-cartridge-load(exit 70) and the same help. It now happens when a file of that language is read, in any command that reads files, rather than on every run. CI still compiles every built-in, so a broken query can't ship.
supdoc v0.2.0
supdoc v0.2.0 is a breaking release. The JSON output schema moves to schema_version 2, the Rust library is no longer a public API, and several defaults change. Your supdoc.config.toml and supdoc.lock keep working, but some lock keys re-key once (see "Re-keys once" below): run supdoc update --yes after upgrading.
Breaking changes
- JSON schema version 2 (#169, #167, #138).
config show --json:line_endings.fileis nowline_endings.from, and eachlimits.*.fileislimits.*.from.- The nine per-command
cli-*-outputcodes (cli-check-output,cli-config-output,cli-fix-output,cli-list-output,cli-namespace-output,cli-rename-output,cli-resolve-output,cli-skill-output,cli-update-output) andinit's report failure are now one code,cli-output-failed.cli-init-writenow means only that the config file could not be written. --jsonl: the summary line now carries exactly the fields--jsonhas. The flat keys are gone: readsummary.*instead of the flat link counts, andsettings_change.line_endings.{from,to}instead ofline_endings_fromandline_endings_to.config show --jsongains alimitsobject.
- The library is no longer a public API (#173). The
supdoccrate exposes only the binary's entry point and a documentedsupdoc::testingmodule for its own integration tests. Use the CLI and its JSON output. - Config discovery stops at the top of the git work tree (#155). A submodule or nested repository without its own
supdoc.config.tomlno longer uses the superproject's config. Pass-c PATHto use it. initrefuses inside a configured project (#154):cli-init-nested, exit 2, naming the config it found. Usesupdoc init -c ./supdoc.config.tomlto write a nested one on purpose.- Every PATH argument is checked (#146).
supdoc check . nope.mdnow refusesnope.md(exit 2) instead of checking the whole project. - Config patterns refuse
.segments (#134).include = ["./docs"]matched nothing before; it is now aconfig-parseerror (exit 78) that says to writedocs. - Removed: the unreachable code
cli-rename-invalid-source-path(#164).
Limits for hostile or generated files
A new [limits] table, with matching environment variables and global flags (#138, #153, #160, #161, #170). Precedence is flag, then environment, then config, then the default. 0 means no limit, and every value needs a unit.
| limit | default | config key | env | flag | refusal |
|---|---|---|---|---|---|
| per-read parse and query time | 10s | parse-timeout |
SUPDOC_PARSE_TIMEOUT |
--parse-timeout |
read-timeout, exit 1 |
| lockfile size | 16MiB | max-lock-size |
SUPDOC_MAX_LOCK_SIZE |
--max-lock-size |
lock-too-large, exit 78 |
| config file size | 256KiB | env and flag only | SUPDOC_MAX_CONFIG_SIZE |
--max-config-size |
config-too-large, exit 78 |
| ignore file size | 256KiB | max-ignore-size |
SUPDOC_MAX_IGNORE_SIZE |
--max-ignore-size |
ignore-too-large, exit 78 |
- One deadline covers each read's parse and every query over it. A timed-out file is never left half-read, and every command exits 1 and prints the finding.
- The size caps are checked on the open file before anything is read, and a file that grows while it is read is still refused.
- A config file can raise its own limits. In CI, set the
SUPDOC_*variables or flags so a pull request can't loosen them.
Re-keys once
These change which links supdoc tracks or how a symbol is named, so update --yes re-records the affected entries once:
- Markdown anchors match GitHub (#148). Slugs keep combining marks and connector punctuation, and headings inside quotes and lists count toward
-1,-2numbering. - Accessor pairs and overloads are one symbol (#145, #149). A getter and setter, a Python property and its setter, or TypeScript overload signatures with their implementation resolve to one symbol instead of being ambiguous. Ambiguity lists show five candidates, then a count.
- One TypeScript query for
.tsand.tsx(#149). Dotted namespaces,export var, private names and object-literal members name the same way in both. - Doc links supdoc doesn't track (#140). A link to a directory, or a
#fragmentlink to a file type no language reads, is left untracked instead of being an error.check -vcounts them.
Safer by default
- A
supdoc.config.tomlorsupdoc.lockthat is a symlink is written through to its real file inside the project, and refused when the real file is outside it (#141). - A link target that isn't a regular file (a FIFO, socket or directory) is refused with
read-not-a-fileinstead of hanging (#159). - Non-regular lockfiles and
extendstargets are refused (#89, #113). namespace renamerefuses before writing anything when an ignore file is over its limit, and rewrites every link written with the old prefix, tracked or not (#156, #161).- The global git excludes file is found once and capped like other ignore files (#170).
Correctness
- A path-scoped
checkorupdatesees links that moved from a source that no longer exists (#142). fixrepairs//,\and:~:links when the repair is unique (#150), and a source deleted mid-fixis reported as changed (#144).- A closed stdout keeps the run's exit code (#135, #175).
- A built-in language that fails to load fails the run (
read-cartridge-load, exit 70) instead of reading nothing (#136). - Hash settings travel with the lock, and out-of-range symbols fail closed (#83).
Clearer messages
- Unreadable ignore files warn (
scan-ignore-file-unreadable), and an ignored path's help names the file holding the rule (#152). - A named path in a skipped directory or an unread file type warns, and a path the walk never reached says so (
scan-explicit-path-unscanned) (#139, #152). - Every printed command keeps your
-cand arguments (#91, #117, #125, #175). - Every error and warning help names a command or value to try, enforced by a test gate (#97, #119).
- Unsupported-language and extensionless files say what to do (#163).
Faster and smaller
- Peak memory of
checkdrops sharply because trees are dropped once their links are read (#131): rust-analyzer 421.0 to 32.6 MiB, ripgrep 88 to 31 MiB, supdoc 82 to 22 MiB. - Wall time is slightly slower than v0.1.2. Median
check --quieton an Apple M4 Pro: ripgrep 247.5 to 288.1 ms, supdoc 218.1 to 237.0 ms, rust-analyzer about 2 to 6% slower. A profile puts about half of it on compiling the larger TypeScript queries at startup, and half on re-parsing a doc that is also a link target, which is the price of the memory drop. Compiling each language only when a file of that type is first read is the planned fix.
New codes
cli-init-nested, cli-output-failed, cli-rename-config-outside-root, config-too-large, ignore-too-large, lock-too-large, read-cartridge-load, read-not-a-file, read-timeout, scan-explicit-path-unscanned, scan-ignore-file-unreadable.
Removed codes
cli-check-output, cli-config-output, cli-fix-output, cli-list-output, cli-namespace-output, cli-rename-output, cli-resolve-output, cli-skill-output, cli-update-output (now cli-output-failed), and cli-rename-invalid-source-path.
supdoc v0.1.2
supdoc v0.1.2 is a fix release. Nothing in the lockfile format or the config schema changes, so v0.1.1 projects work unchanged.
Faster
supdoc check on a project with 20,000 links drops from 10.9 s to 1.6 s (6.8x), measured with hyperfine on the same project and machine. Output is unchanged.
- Lock parsing and finding locations no longer count newlines from the start of the file for every link (#70).
- A comment region with no
[is no longer parsed for links (#65).
Stays inside the project
list TARGET#symbolno longer reads outside the project root, and a target that resolves outside it is refused withcli-path-outside-project(#75, #76, fixes #60).- A target path containing
..is refused when parsed (#75). - A target that is not a regular file, such as a FIFO, is refused instead of hanging
list,checkorresolve(#75).
Fewer silent surprises
list TARGETrefuses a misspelled symbol, a missing file or an unknown namespace instead of printing "No links" and exiting 0 (#76).- A doc file whose name is not a valid source path is reported as a
scan-invalid-source-pathwarning instead of being skipped silently (#71). - Naming a file under a symlinked directory warns with
scan-explicit-path-symlinkedinstead of blaming a nonexistent ignore rule (#68).
Clearer errors
- A failed link prints
supdoc update PATH --yeswith a path that runs from where you rancheck, quoted (#74). supdoc resolve FILE#SYMBOLsays to writesupdoc resolve FILE SYMBOL(#74).resolvesuggests only close symbol names, explains that line anchors are unsupported, and says to link the whole file when a file has no symbols (#72).- A broken
supdoc.lockheader says to writeversion = 1or to recreate the lock, not to delete an entry (#69). extendsnaming a directory, andincludegiven a string, now say what to write instead (#73).- The unknown
--formattip points at--output jsonand--json(#66).
Internal
- CI token is read-only, actions are pinned to commit SHAs, and a cargo-deny job runs (#64).
- Removed the unused
Traceverbosity and the emptyoutput::schemamodule. Thecli-not-builterror code is gone (#67). - Tests: dropped fixture-only goldens and added rename lock/config guards (#77); pinned the JSON fix object and the
SUPDOC_YES/SUPDOC_DRY_RUNwrites (#78).
New codes
scan-invalid-source-path(warning)scan-explicit-path-symlinked(warning)cli-resolve-fragment(error, exit 2)
supdoc v0.1.1
supdoc v0.1.1 is a fix release. Nothing in the lockfile format or the config schema changes, so v0.1.0 projects work unchanged.
Containment: what supdoc reads outside the project
The README now has a threat model: supdoc protects the contents of files outside the project root, not whether a path exists. These fixes make the code keep that promise.
extendsis refused alike whether it leaves the root or goes through a symlink (#27).- Config discovery no longer reveals whether a symlink target exists (#23).
skill installrefuses a project install through a symlink out of the root (#18).resolverefuses a FILE outside the project root (#58).- Ignore files symlinked out of the root no longer decide what is scanned, and their rules are never quoted (#24).
- A symlinked ignore file above the project root is not read (#56).
Ignore files work like git
- Parent ignore files stop at the top of the git work tree (#48).
- A nested repository or submodule starts a fresh ignore chain (#59).
- A submodule's exclude file is read, global excludes are anchored at the work-tree top, and a
.gitcounts only when git would use it (#49). - A symlinked
.gitignoreor.ignoreinside the project is ignored, as git does (#42). - Sources under an unreadable directory are reported as unread (#17).
- The README lists the remaining differences from git (#61).
Config and project discovery
- One presence rule for
supdoc.config.tomlin discovery and the nested-project check (#37). skill installfinds the project root with config discovery (#39).skill install --configrefuses a path that is not an existing file (#57).
Messages and output
checkandupdateprint findings by file, then position (#22).updatecloses on the plan and reports the line-endings change in JSONL (#15).renameprints walk findings in text output (#47).- Files are named relative to the project in messages and runnable helps (#26).
- A PATH that can't be looked up is reported as unreadable, not missing (#36).
extendserrors say it must lead to a readablesupdoc.config.toml(#38).- Help texts that misled are now runnable and effective (#19), and ignore-file wording no longer over-claims (#29).
Docs and packaging
- README: threat model (#43, #61) and the
schema_versioncompatibility policy (#14). - The packaged crate's tests compile and skip repository-only checks (#16).
Known issues
- #60:
supdoc list TARGET#symbolparses a file outside the root reached through an in-root symlink. No text or symbol names from that file are printed. Until this is fixed, the README's promise that supdoc lists no symbols from outside files does not hold forlist. - #51: a file that an outer
.gitignoreignores is still scanned. This is documented under "Differences from git".
Full changelog: v0.1.0...v0.1.1
supdoc v0.1.0
supdoc v0.1.0 is the first release. supdoc tracks links from documentation to code, such as [text](src/lib.rs#symbol), and reports when the code behind a link changes.
What it does
- Link docs or code comments to code with ordinary Markdown links:
[add](src/lib.rs#add)links one symbol,[lib](src/lib.rs)a whole file. supdoc update --yesrecords a hash of every linked target insupdoc.lock.supdoc checkcompares the code with those hashes and fails when a linked target changed, so it works as a CI gate.- Links are read in Rust, TypeScript, JavaScript, Python, Go, Bash and Markdown files. Markdown headings are symbols too.
Commands
check, update, fix (repairs broken links whose fix is certain), list, resolve, init, config show, namespace list and namespace rename, schema, completions and skill install (supdoc's agent skill). Every command has --json output with a published JSON Schema.
Configuration
supdoc works without a config. supdoc init writes a supdoc.config.toml with every key commented out. Namespaces give a part of the project a short name, so auth:src/session.rs#login works from any file.
This GitHub release was added after the tag; the tag and the crate are unchanged.