All notable changes to docsync are documented here.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
A release of the ds binary and the cli module (0.1.9) and the library (0.1.7); the tier modules are unchanged. Fixes GitHub issues 5 to 8 and bugs 144 to 156: every directive on a line is read, a ds:claim about= keeps its baseline until it is renewed, and a workspace index missing on this machine no longer stops every command. Read Upgrading first if you use about= claims.
- A claim with
about=that an older version recorded gets its baseline at the firstds scanwith this version, taken from the blocks as the older version's last scan recorded them (ledger.tsv, andforeign.tsvfor blocks of other repositories), not from the blocks as they are now. A change made since that scan is therefore still reported. A claim last renewed by an older version stays reviewed while its blocks match that renewal, and is reportedexpired(classunknown) once they do not. The only change this version cannot see is one made and scanned entirely under the older version, after the claim's last renewal: the older version recorded no baseline it could be compared with. For a claim about another repository's block, the older version'sforeign.tsvheld the block only if a link also cited it; otherwise that block is baselined as it is at the upgrade.
- Renewing a
ds:claimnow records one hash per def it is about (id|env|hash, comma-separated) in the ack's block hash, andrefs.tsvcarries it as the claim row'sacked_hash. The claim's next change is classified against what was renewed, def by def, so a body-only edit to astability=apiblock after a renewal is no longer reported. Acks recorded by older versions, which hold one combined hash, still load and still count as a review while the blocks match them.acks.tsvandrefs.tsvkeep their formats.
- Only the first directive on a line was read. A second
<!-- ds:block … -->or{/* ds:block … */}on the same line, after a sentence, beside another on a line of its own, or in the next cell of a table row, was dropped without a word, so the sentence it guards was never flagged and its def was reporteduncovered. Every comment on a line is now read, one directive per comment, and each table cell keeps its own sentence. The directives guide also no longer says a directive in an HTML comment broken across lines is not read; it has been read since 0.1.5 (bug 144, GitHub issue 5). - Two directives inside one comment (
<!-- ds:block id=a ds:block id=b -->) were reported asbare word where key=value was expected, which does not say what is wrong. The problem now readsa second directive in one comment is not read; put each directive in its own comment, at the column of the second directive (bug 148). ds scanre-baselined ads:claimwithabout=: once a scan had recorded a changed block,ds checkreported the claimok, though nobody had acked it. A claim is now measured against its own baseline inrefs.tsv, as a citation is. That baseline is the state of its blocks at its latest renewal (ds ack --doc D --line N), or when it was first scanned if it was never renewed. A scan never moves it. A change the block'sstabilitydoes not flag still leaves the claim alone (bug 145, GitHub issue 6).- A
ds:claimwithabout=naming an id published by another repository in the workspace never expired. It now expires as a local one does, both live and undercheck --frozen.ds syncnow records a claim'sabout=ids in.ds/foreign.tsv, andds prune(also with--index) keeps the bodies a claim's baseline names, so the change is still classified (bug 146, GitHub issue 7). - A
ds:claimwithabout=naming an id nothing defines stayedokfor good, whether the block was deleted or the id was mistyped. It is nowbroken, with the same message and fix as a citation of that id, and a renewal does not clear it. A claim reviewed against an environment of the id that is no longer defined, while other environments still are, isexpireduntil it is renewed (bug 149). - A new definition of a claim's
about=id did not expire the claim, and the next scan adopted it. That covers both a def for another environment and the first def of an id just added toabout=. Such a claim now reportsclaim is about X: a new definition of X appeareduntil it is renewed, and a scan never adds a definition to a claim's baseline (bug 152). - A workspace index that is not on this machine stopped every command except
check --frozenwith exit 2, includingds scanandds def, which only touch the repository they run in. That covers a localworkspacepath that does not exist here and a git index that was never cloned and cannot be reached now. Every command exceptds syncandds publishnow prints a warning and carries on: citations of other repositories are read from the committed.ds/foreign.tsv, as--frozendoes. Without that file such a citation is reportedbroken(is cited but is not recorded in foreign.tsv), never passed, andds check --strictexits 1 because nothing could check them.ds doctor'sindexrow isWARNwhen.ds/foreign.tsvexists andFAILwhen it does not (bug 147, GitHub issue 8). ds doctorreported an unreachable git index with the last line of git's error,and the repository exists., instead of the reason. It now shows the line that says why, such as'/srv/idx.git' does not appear to be a git repositoryorCould not resolve host, and so does the warning when a first clone fails (bug 150).- A
workspacevalue that is not an existing directory and does not look like a git URL was passed togit clone, so the error was git'srepository '../shared-index' does not exist. It is now treated as a path and named as one:workspace path ../shared-index does not exist (resolved to …); create the index there, or point `workspace` in .ds/config.toml at it. A git URL is a value with a scheme (https://,ssh://,file://), git'suser@host:pathform, or a barehost/pathwhose first segment is a host name. The bare form, the one the configuration guide shows (github.com/org/ds-index), is now cloned over https; before, git read it as a local path and it never worked. Aworkspacepath that is a symlink to a missing directory is named as one, with the target it points at (bug 151). - A published entry in the workspace index that does not parse, or an index directory that cannot be opened, stopped every command in every repository reading that index, and the error (
repos/api: ledger: missing or malformed header line) did not say it was in the index. Commands now warn withworkspace index <dir> cannot be read: …; republish the entry from its repository with `ds publish`, or fix the indexand carry on as they do with no index.ds syncstill stops on it (bug 153). - A
.ds/foreign.tsvthat does not parse or cannot be read was ignored without a word by every command exceptcheck --frozen, the default in CI, which stops on it. Commands now warn that moves of foreign blocks are not reported and thatcheck --frozenwill fail, andds doctor'sledgerrow fails on it (bug 154). ds syncrefused to replace a.ds/foreign.tsvthat does not parse, though sync is what rewrites the file and every other error about it says to run sync. It now warns, replaces the file, and lists every cited block as new. A snapshot written by a newer docsync still stops sync, with the advice to upgrade (bug 155).- An empty, truncated or hand-edited
.ds/ledger.tsv,refs.tsv,acks.tsvorforeign.tsvwas named with no way out, and the command that writes it failed on it too. The error now says what to do: restore it withgit restore .ds/<file>; for the ledger, or delete it and runds scan, which rebuilds it from the source; for refs and acks, what deleting it instead costs; for foreign.tsv, runds sync. A file written by a newer docsync says to upgrade ds instead (bug 156).
A release of the ds binary and the cli module (0.1.8), the library (0.1.6) and ext/structured (0.1.2); ext/treesitter and ext/records/sqlite are unchanged. Fixes GitHub issue 4 and bugs 136 to 143: copies ds refresh cannot write are reported instead of staying stale, and directives are read only where they are real.
- SPEC "Reading directives" now says where each kind of directive is read, as a table. A link
[x](ds:…)in a comment or in a string literal in code is a citation, because strings hold prose such as help text, errors and UI text; a whole-line directive is one only in a comment, never in a string, where it is fixture text; a link in bare code is still read. The reasons are in SPEC §36. Behaviour in code files is unchanged; the formats with no comment syntax and the YAML, TOML and HCL comments changed as listed under Fixed.
- Repo mode: a
ds:blockwhoselines=range runs past the end of the block (or is not a range, such aslines=abcorlines=5-3) is now reported byds checkasrange, an error in repo mode, with "adjust lines=" as the fix. It used to be reported asstalewith "runds refresh" as the fix, forever: refresh could not write that copy, said only "0 repo-mode copies rewritten", andds ackdid not clear it. A bad range is reported before a changed block, because no refresh can bring the copy up to date until the range fits. A block that shrinks under a citation that used to fit reports the same (bug 136, GitHub issue 4). ds refreshnever skips a repo-mode copy silently. It printsskipped <doc>:<line>: <reason>for each copy it could not write and aN repo-mode copies skippedline, andlink only <doc>:<line>: <reason>for a copy written with only its caption and link (a block overmax_lines, anat=with no snapshot);--dry-runprints the same. The existing count lines are unchanged. The library hasSystem.FencesReport, which returns the same notes asCopyNotevalues;Fencesis unchanged (bug 136).- Repo mode: a copy citing
env=was rendered from the first def of the id rather than the one its environment names, so anenv=prodcopy could not be written and was reportedstaleforever. Refresh now resolves the def exactly ascheckdoes (bug 137). - A
ds:link inside a JSON, CSV orgo.sumfile (for example a note stored as a JSON string that describes how a repository cites its code) was read as a citation and reportedbroken. These formats have no comment syntax and no prose, so such a link is data;checkand the editor extension now ignore it. A whole-line directive in them is still reported as damage (bug 139). - A whole-line
ds:blockoutside a comment was read as a citation in JSON, CSV andgo.sum, and in files that take#or//comments but are read line by line (.gitignore,.dockerignore,go.mod,go.work,.vue,.svelte). It cites nothing there and is now reported asdirective is not inside a comment, as a whole-lineds:defalready was (bug 140). - Build mode: a repo-mode copy already in a page (left from repo mode, or pasted) was compared with its block and reported
stalewith "runds refresh" as the fix, but refresh only touched copies in repo mode.ds refreshnow brings such copies up to date in build mode too, and names any it cannot write; it still adds none, and says nothing about copies when a page holds none (bug 141). - A link-form directive inside a YAML, TOML or HCL comment (
# see [8081](ds:cfg?id=…)) cited nothing: those tiers read only the comment form of a directive. A comment is the primary carrier, so it is now a citation there, as it already was in INI, shell and code comments. Text outside comments is read as before (bug 142). - A
ds:defwritten as a bare line outside a comment was silently ignored in INI, env, properties, HTML, Markdown, AsciiDoc and reStructuredText files; it is now read and reported asdirective is not inside a comment, as the code tiers already did, sods repaircan comment it (bug 143). - A block-position
ds:blockof a secret, which never renders, is reported as aproblemnaming a carrier that works (ds:cfgords:chain). In repo mode it used to bestaleforever; in build mode it passed silently and rendered nothing (bug 138).
A release of the ds binary and the cli module (0.1.7) and the library (0.1.5, which adds the [update] config key); the tier modules are unchanged. ds can now update itself.
ds updateupdatesdsand theds-resolve-*plugins beside it to the newest release, in colour at a terminal: it prints the current version, checks, downloads the archive for the machine, verifies it against the release'schecksums.txtbefore replacing anything, and says what changed.--check(or--dry-run) only reports,--version vX.Y.Zinstalls a named release (also to go back),--forcereinstalls, and--jsonprints the result. A development build or ago installbuild is told how it is updated instead of being overwritten.- A release build keeps itself current: at most once a day, before a command run at a terminal, it checks for a newer release (waiting at most two seconds), installs it and runs the command on it. It stays out of CI,
--json, piped output,ds doctorand thelspandmcpservers; a failed check is silent and a failed install is one warning, after which the command runs on the current version. Turn it down withDS_UPDATE=notify(only say a release exists) orDS_UPDATE=off, for one run with--no-update, or for a whole team with the new[update] modekey in.ds/config.toml; the strictest setting wins. - The update settings show up where they are needed: the message before an automatic install names
DS_UPDATE=notifyandDS_UPDATE=off, the notify-mode notice says how to stop it,ds updateends with the mode in effect and what set it,ds doctorhas anupdaterow (mode, source, last check;WARNwhen a release is waiting), andds --helpnow has an Environment section listingDS_UPDATE,NO_COLORandCI.
A release of the ds binary and the cli module (0.1.6) and the library (0.1.4); the tier modules are unchanged. Remote defs can now bind whole blocks (GitHub issue 3), and the VS Code extension works in a real editor.
- A remote def can bind a whole block without a directive in the target file.
pick=yaml:tasks.deploybinds a Taskfile task (the key and everything under it),pick=toml:servera TOML table, andpick=symbol:Manifesta declaration in a code file, found and hashed exactly asds def file#Namewould. A change inside the block flags its citations; moving it within the file is reported asmoved. JSON objects and HCL blocks already worked this way (bugs 132 and 133). task vscode:tryopens a small demo repository in a VS Code window running the docsync extension fromeditors/vscode, with a cited value that has changed, so the code lens, hover, go-to-definition andds:links can be tried without installing anything;task vscode:packagebuilds the installable.vsix.
pick=yaml:split a key at its first colon, so a namespaced Taskfile task such astasks.state:bootstrapcould not be picked, althoughds def Taskfile.yml#tasks.state:bootstrapworked. The pick and the config tier now share one key-path grammar: a key ends at a colon followed by whitespace, and a segment holding a dot is quoted (tasks."a.b") (bug 135).- A pick whose value spans several lines said "use ds:block", which read as a fault in the citation even when it already was
ds:block. It now says to pick the key, table, section or symbol that holds those lines (bug 134). - The VS Code extension never started: VS Code's language client runs the server as
ds lsp --stdio, andds lsprejected the flag and exited.ds lspnow accepts--stdio, and the extension no longer asks for it, so it also works with an olderds(bug 130). - In VS Code, clicking a
[text](ds:cfg?id=…)ords:blocklink in markdown failed with "Unable to resolve resource". The extension now opens what it names: it reveals the block in its file and shows the id, location and current body (bug 131).
A release of the ds binary and the cli module (0.1.5), the library (0.1.3), and the tier modules (ext/structured 0.1.1, ext/treesitter 0.1.2, ext/records/sqlite 0.1.1): 81 fixes from a sweep that ran every documented behaviour against the binary. Read Upgrading first.
--resolvenow also needs[resolve] enabled = true, as--runneeds[run] enabled; without itdssays so on stderr and contacts nothing. Add the key to a nightly job's config if it used--resolve.- Config keys that were accepted and did nothing are refused when the config loads, naming the key:
notify.github_issues,[sources.*],[workspace.id]and[workspace.env]. env.knownapplies to every environment name:env.default,[run.env.<name>],--envoncheck,renderanddef, andenv=on defs and citations.[id] suffix_lengthandsuffix_alphabetare checked when the config loads.- Agent acks (MCP and
ds ack --agent) require a delegate listed in[owners]; MCP acks are recorded under the client's name. ds def,ds adoptandds def --fixderive an id's suffix from the repository, the file, the line and its content, so a dry run prints the id the real run writes.- Rendered links are relative to the page, so links in
docs/work on GitHub;{rel}joins{file}in[check] permalink. A repo-mode copy written with the old root-relative links is accepted as it is, and the nextds refreshrewrites it. - The
ds checktext summary counts passing findings asokinstead ofnone, and prints the diff under each finding. - A citation must carry its block's current label: one with a stale label is
brokenand names the id it meant (the spec said the suffix alone identified it). <!-- ds:cfg -->in block position is a scan problem, since render cannot show it.- Reports
dswrites (check --json,audit --export) are not scanned, so they create no phantom citations; the CI template fromds initwrites its report to$RUNNER_TEMP. - The scanner skips any checkout nested in the repository (a directory with its own
.git: a worktree, a submodule, a cloned dependency), as the spec already said it did for submodules.
ds-resolve-env, shipped in the release archives and install scripts:source=envhops are checked against the environmentdsruns in.- A
stale copyfinding: after a rotation, a copy that still holds the old value. - A
run failedfinding for ads:runthat fails undercheck --run; a run not executed isskippedwith the reason. ds doctorrows for the workspace, the reachability of its index, and eachresolve.providersplugin.ds init --agentsregistersds mcpwith Cursor, VS Code and Gemini configs where they exist, and honoursagents.mcpandagents.session_hook.- The MCP
impacttool takesstaged;ds whylists citations from other repositories;ds context --since <commit>works. - The GitHub action commits acks recorded under the
docs-ackedlabel to the pull request branch; the publish workflow template produces the JUnit report it publishes. - The Docusaurus plugin gains
sourceUrland refuses theremarkPluginsposition with a clear error. scripts/e2e/determinism.sh,round-trips.sh,upgrade.sh,resolvers.sh,def-targets.sh,cli-commands.sh,classify-and-diff.sh,workspace-surfaces.sh, and source-scanning tests that config keys take effect, that messages name real keys and commands, and that SPEC's findings table and library API match the code.
- Checking and diffs: a finding's diff comes from the stored body of the hash its citation was acked or first seen at, and
ds ackstores the body it approves, so the diff is never the wrong old version or missing. A change checked without a prior scan is never classifiedbodyby default, sostability=apino longer passes a signature change; a changed one-line constant isvalue.ds find,ds map,ds report --stalestand same-line findings are ordered by place, not by random id suffix. ds def: it no longer writes a trailing directive into.properties, INI and.envvalues (where it became part of the value);path#Namefinds every name a scan records (Holder.Member, Python constants and class attributes, TypeScript object paths, HCL and TOML tables, shell functions);path:A-Bbinds that range or refuses; a dotfile gets a label; a target on an existing directive returns that def instead of adding a second one.- Directives:
.mts,.cts,.cjs,.pyi,.tfvars,.markdownand.env.*take directives; a directive comment over several lines is read; a link-form directive with spaces is written[text](<ds:…>)and one markdown cannot read is reported instead of dropped; quoted link values lose their quotes;span=works in YAML, TOML and HCL;type=and ids are validated; two inline facts in one sentence, and two remote defs picking different values on one line, are separate blocks. - Render, context and commands:
render --attakes everything from that commit;ds:block at=renders its snapshot;.txtpages lose the bare directive line;contextshows block-position citations and the same diff ascheck;ds lspuses the client's workspace root;github comment --dry-runneeds no token;review --outworks without--ai;undo --listlabels moved committed writes correctly; a renewed claim clears at once;ack --from-commitrecordsnote=;refreshwith nothing to record writes nothing. - Secrets, URLs and runs: 1Password addresses resolve through the shipped
ds-resolve-onepassword; Vault addresses lose theirvault:prefix; a signed-outopisunverifiable; alocal=truedef is checked where its file exists;ds:runhonourstimeout=andexpect=<status>and requires a zero exit;ds:urlhonoursexpect=, and a link that gets no answer isunverifiableand never cached as dead. - Cross-repo:
ds publishcommits a local git index;stale_after_commitsandindextake effect; another repository's citation says which repository and where to ack it; a git-hosted index is cloned by the first command that needs it; repo-mode copies of another repository's block carry its body and are not printed twice. - A repo-mode copy whose code is all still in its block, only moved (a def added inside it, a
lines=window shifted), isstalefords refresh, nottampered. cli.WithNamereachesversion, remedies and doctor rows; the Hugo status partial lists only the current page's references; the spec's findings table, library API, scan-skip wording andds initdocs default match the code.
Two changes may report once after upgrading. Repo-mode copies are accepted with their old links, so nothing is needed there; run ds refresh when convenient to make their links relative to the page. If a nightly job runs ds check --resolve, add [resolve] enabled = true to .ds/config.toml, or it will check nothing.
A release of the ds binary and the cli module (0.1.4), the library (0.1.2) and the tree-sitter tier (0.1.1). Read Upgrading before you scan with it: Go blocks containing strings report once.
- docsync is now licensed under the Apache License 2.0 instead of the GNU AGPL v3.0, for every module, the VS Code client and the Docusaurus plugin. Releases up to and including ds 0.1.3, cli 0.1.3 and the library 0.1.1 remain available under the AGPL terms they were published with.
- In Go, the text inside a string literal was not part of a block's hash: changing
errors.New("account locked")to"account suspended", a URL, a query or a flag name inside a function never flagged the sentences citing it (bug 22). Go's grammar gives a string no node for its text, and the hash was built from the parse tree's leaves. Text that no child node covers is now hashed with its node. Only Go interpreted strings ("…") were affected; raw strings, runes, and strings in TypeScript, JavaScript, Python and SQL already hashed their text, and their hashes do not change. The extraction rule stays at 1. See Upgrading. - The extraction cache is now keyed on the
dsbuild as well as the rule, prefix, tiers and line limit. Keyed on the rule alone, an upgrade that fixes what a hash covers without changing the rule kept serving unchanged files their old hashes untilds check --full, so the fix appeared to apply only to files someone had edited. Each new build re-extracts once. policy.require_docand the unmarked view ofds reportdid nothing for Go, TypeScript, TSX, JavaScript, Python or SQL files: they only looked at files the heuristic code tier had read, and the standarddsreads those languages with their tree-sitter grammars. A file now counts by its extension, whichever tier read it.ds github comment: the closing fence of each block diff was written on the diff's last line, so the code block never closed and everything after it in the comment rendered as code.
After upgrading, a Go block whose code contains a "…" string has a new hash although its code did not change, so ds check reports each citation of it once, as a change. Re-ack those after confirming the code really is unchanged. A coding agent can do it with this prompt:
docsync was upgraded, and its hash now includes the text inside Go string
literals. Citations of Go blocks that contain a "..." string may be reported
once even though their code did not change. Clear only those, and nothing else:
1. Run `ds scan`, then `ds check --json`. Work only on findings whose block
file ends in .go.
2. For each one, find when that citation was last acked: `ds audit --id <id>`
prints one line per ack, starting with its time. Take the commit the
repository was at then: `git log -1 --before=<time> --format=%H`. If the id
was never acked, or that prints nothing, use the last commit that changed
.ds/refs.tsv. Compare the
block's lines at that commit with the working tree: `ds locate <id>` gives
the file and line range, and `git diff <commit> -- <file>` the changes.
3. If those lines did not change, the finding is the upgrade. Read the citing
sentence once to be sure it is still true, then run
`ds ack <id> --doc <doc> --line <line> --note "re-ack after the Go string hashing fix; code unchanged"`.
4. If the lines did change, this is a real finding. Do not ack it: fix the
sentence, or report it, as you would any other.
5. Run `ds check` again and report what you acked and what you left.
A release of the ds binary and the cli module (0.1.3), and of the library (0.1.1), which adds run.shell to the config. The end-to-end matrices now run on Linux and on Windows under Git Bash as well as on macOS.
[run] shellnames the shell thatds:runcommands and the[review]command run under (defaultsh).
- When the shell is not on PATH,
ds check --runandds review --ainow stop with an error naming the shell and the[run] shellkey. Before, every command was recorded as a failed run with no output, which on a Windows machine without Git for Windows read as the runbook being broken. - On Windows, a
ds checkrunning beside ads scancould fail, or make the scan fail, because Windows refuses to replace a file another process has open at that instant. Reads and writes under.ds/now wait that out. - A
ds:run file=script is handed to the shell as an argument of its own instead of inside a quoted command line.
A release of the ds binary and the cli module, after the first run of docsync on Windows.
- A
dsbuild for Windows on ARM64 (ds_v0.1.2_windows_arm64.zip), installed byinstall.ps1. .github/workflows/windows.ymlandscripts/windows-smoke.ps1: every module's tests, a build from source, and the published release, run on Windows amd64 and ARM64. Manual trigger.
- On Windows, a rooted path with no drive letter (
/etc/hosts,\etc\hosts) was accepted as a path inside the repository, andds:run file="/etc/hosts"was not refused. A path argument is now taken from the root, andfile=is judged by its text on every platform: a leading slash of either kind, or a drive, is refused. - On Windows, a file sitting where
.ds/blocksor.ds/ledgershould be was read as an empty store instead of an error.
A release of the ds binary and the cli module; the library and the tier modules stay at 0.1.0.
- The
dsrelease archives carry the five secret-resolver plugins (ds-resolve-aws,ds-resolve-gcp,ds-resolve-github,ds-resolve-onepassword,ds-resolve-vault) besideds, andinstall.sh/install.ps1install them with it. In 0.1.0 they could only be built withgo install, sods check --resolveneeded a Go toolchain.
The first release: the root library github.com/ubgo/docsync, the tier modules ext/structured, ext/treesitter and ext/records/sqlite, the cli module, and the ds binary for darwin/arm64, linux/amd64, linux/arm64 and windows/amd64, installable with install.sh / install.ps1 or go install. ds carries the tree-sitter tier and is built with cgo, so there is no prebuilt Intel Mac binary; go install github.com/ubgo/docsync/cli/cmd/[email protected] with a C compiler covers it. The five secret-resolver plugins install with go install as well.
install.sh(macOS, Linux) andinstall.ps1(Windows): download the newestdsrelease for the machine, verify it against the release'schecksums.txt, and install it. Generated byvolt gen install cli/cmd/ds.ds versionreports the release version a release build stamps (-X github.com/ubgo/docsync/cli.releaseVersion=…), instead of the pseudo-version the toolchain records for a build from a checkout.- A spec-promise gate: every sentence in
docs/SPEC.mdsaying "never", "always", "refuses", "must not", "deterministic" or "hard error" is listed intestdata/promises.txt, and each testable one is pinned by a test naming it (promise:<id>).taskfails on an unlisted promise, a listed one reworded, or one with no test. - The root library, the
dsCLI, and the structured (YAML, TOML, HCL), syntax (tree-sitter: Go, TypeScript, TSX, JavaScript, Python, SQL) and document (Markdown, HTML, AsciiDoc, reStructuredText) tiers. - An MCP server (
ds mcp) and a language server (ds lsp), with a VS Code client. - A GitHub Action and workflows, pre-commit hooks, a Docusaurus plugin, and a Hugo module.
- Workspaces: citations across repositories through a published index, with a committed snapshot so checks are reproducible offline.
- Sentence-level acks: a cited sentence rewritten since its ack is reported, with the old and new wording. Every ack records the extraction rule it was made under (rule 1). An ack made under another rule still holds when its sentence is unchanged; only when both the rule and the wording differ is it reported, once, as recorded under another rule rather than as a rewrite.
--dry-runforackandpublish; root discovery from any subdirectory.task perf, measuring the performance targets on a generated 100,000-file repository.- Group entries and body members are defs in their own right: an entry of
const ( … ),var ( … )ortype ( … ), a struct field, an interface method, an import, a TypeScript interface property, enum member or object-literal property (server.port). Each binds its own line and is found bypath#Name. ds repair: finds directives an older build wrote as bare lines into files that cannot hold one, comments them, or deletes them where the format has no comment syntax. Prints by default;--applywrites, andds undoreverses it byte for byte, deletions included.ds versionandds --version: the commit a binary was built from and whether that checkout was dirty.- Go module and workspace files (
go.mod,go.work) and Pkl take//comments.
- The extraction cache skips reading files whose size and modification time are unchanged;
check --fullstill reads every file. ds initand the shipped GitHub workflows trigger manually. Their automatic triggers are in each file's header, to paste back where Actions minutes are not metered.ds adoptresolves a relative link against the page holding it, then the repository root, and leaves a heading link into another page alone.- An id minted for a block the lookup cannot name takes the scanning tier's name (
server-port-…) rather than the file's.
- The fork guard on
check --runandcheck --resolvefailed open: a deleted fork, a pull request whose head repository was missing, or an event file that could not be read or parsed was treated as not a fork, so committed commands ran. It now fails closed, andreview --ai, which runs the committed[review]command and had no guard, has the same one. - A secret's value is never shown.
secret=trueon a line holding a real value, or any line in a[secret] pathsfile, was printed byrender,facts,context,read,blame,triage,review,export hugo, the MCPread,facts,contextandchecktools, and the change diff incheck --json— sixteen paths in all. Only an address (${{ secrets.X }},op://…, an AWS or GCP secret resource, avault:path) is shown now; everything else is withheld with its hash kept, so a rotated secret is still reported.
- The pre-commit hooks file moved to the repository root. Under
integrations/pre-commit/, the documentedrepo: https://github.com/ubgo/docsyncentry could not find it, since pre-commit reads it only at the root. ds defandds adoptrefuse to mint a def in a file under[scan] generated, naming the file; the spec promised this, but both wrote the directive, and the next code generation erased it while every sentence citing it stayed. An id already in such a file is still returned.- The spec said the
whitespaceclass is never reported; a re-indent is silent only where the syntax tier hashes the token stream (Go and the other tree-sitter languages). In a file with no grammar, indentation is content and a re-indent is a body change. The spec now says so. - A ledger or refs file recorded under a newer extraction rule was compared silently: unchanged blocks reported drift, and
ds scanrewrote the files under the older rule. Every command now refuses it, naming the file and both rules, anddoctorreportsFAIL. An older rule is a warning instead, since that is the upgrade path. Repositories that ran a pre-release build holdextract=2to4for what is now rule 1; settingextract=1on the first line of.ds/ledger.tsvand.ds/refs.tsvand runningds scanfixes them. ds doctorexits non-zero when any row isFAIL; it exited 0 even with a ledger it could not read.- A duplicated id's remedy names
ds def --fixinstead of the generic "fix the directive". - JSON-RPC responses with no result now carry
"result": null, as the protocol requires. - A change made since the last scan is diffed against its previous body as the scan produced it, not the raw lines of the old file: a config value changed from 443 to 8443 is shown as
-443 / +8443, not as the whole old line with its directive comment against the new value. - A directive is never written into a file that cannot hold one.
ds defandds adoptused to insert it bare into any type they did not recognise, which broke a Go workspace's build and would have left JSON unparseable; they now refuse, name the file type, and change nothing.ds scanreports a bare directive already sitting in such a file. - A directive is never written where it would not bind: the edit is checked in memory with the scanning tier first, so
--dry-runpredicts a refusal instead of a later scan finding it. - A directive above a grouped constant bound the next top-level declaration instead (bug 18), and a directive above any construct a grammar did not recognise did the same. It now binds the declaration below it or reports.
- Two ids bound to the same block are reported.
- An unknown
stability=is reported instead of silently becomingstable. - A typed standalone Go constant or variable (
const X T = v) can be found by name (bug 19). - A YAML key containing a colon, such as a Taskfile task
wfsys:up, can be addressed. - An ack from another extraction rule no longer asks for its unchanged sentence to be re-read (bug 17).
- The extraction cache is keyed on the directive prefix and the extractor tiers as well as the rule, so changing either is never served stale results.