Skip to content

supdoc v0.2.0

Choose a tag to compare

@aidenzepp aidenzepp released this 02 Nov 05:53
· 244 commits to main since this release
6d47024

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.file is now line_endings.from, and each limits.*.file is limits.*.from.
    • The nine per-command cli-*-output 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) and init's report failure are now one code, cli-output-failed. cli-init-write now means only that the config file could not be written.
    • --jsonl: the summary line now carries exactly the fields --json has. The flat keys are gone: read summary.* instead of the flat link counts, and settings_change.line_endings.{from,to} instead of line_endings_from and line_endings_to.
    • config show --json gains a limits object.
  • The library is no longer a public API (#173). The supdoc crate exposes only the binary's entry point and a documented supdoc::testing module 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.toml no longer uses the superproject's config. Pass -c PATH to use it.
  • init refuses inside a configured project (#154): cli-init-nested, exit 2, naming the config it found. Use supdoc init -c ./supdoc.config.toml to write a nested one on purpose.
  • Every PATH argument is checked (#146). supdoc check . nope.md now refuses nope.md (exit 2) instead of checking the whole project.
  • Config patterns refuse . segments (#134). include = ["./docs"] matched nothing before; it is now a config-parse error (exit 78) that says to write docs.
  • 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, -2 numbering.
  • 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 .ts and .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 #fragment link to a file type no language reads, is left untracked instead of being an error. check -v counts them.

Safer by default

  • A supdoc.config.toml or supdoc.lock that 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-file instead of hanging (#159).
  • Non-regular lockfiles and extends targets are refused (#89, #113).
  • namespace rename refuses 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 check or update sees links that moved from a source that no longer exists (#142).
  • fix repairs //, \ and :~: links when the repair is unique (#150), and a source deleted mid-fix is 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 -c and 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 check drops 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 --quiet on 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.