Repository navigation
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.