fix: v0.4.0 remediation — dogfooding blockers, bug batch, UX polish, docs sweep

[dean0x]

Context

Six-agent dogfooding campaign (2026-07-17) found 3 release blockers plus a bug/UX/docs
batch while using MDS v0.4.0 in anger. This single consolidated PR fixes all of it
pre-release. Related issues: #172 (lint block-span --fix, deferred), #180 (follow-up
design questions).

Closes #181

Release Blockers (3)

1. Bare relative filename crash (e.g. mds build foo.mds from foo.mds's
   directory) — effective_parent in fs.rs mapped an empty parent path to .
   instead of producing a bad-path error; this caused panics on some platforms.

2. sourceMap.sources[0] cross-surface divergence — string-source compiles
   produced "<source>" on napi/Python/WASM but "input.mds" on the CLI, making
   cross-surface source-map consumers unreliable. Unified to "input.mds" via a
   map_source_label choke-point in sourcemap.rs.

3. mds fmt formatter-invariant false positive on trailing blank lines — templates
   ending with @if … @end\n\n were rejected by the safety gate with
   mds::formatter_invariant after a perfectly valid format run.

Key Changes

Phase A — Bare filename, walker exclusions, ElseifBranch AST

• effective_parent helper in fs.rs; all subcommands now handle bare filenames.
• Directory walker default-excludes hidden dirs (.git, .venv, …) and node_modules
  on all subcommands (build/check/watch/fmt/lint).
• ElseifBranch { condition, body, offset } struct replaces tuple form; lint
  @elseif diagnostics now anchor at the branch span.

Phase B — Lint core: partial apply, preview gate, display-path, overlap surfacing

• apply_fixes_incremental in lint/fix.rs: batch-first, right-to-left per-edit
  fallback; reports "N of M fixes applied" for partial results.
• lint --fix --check/--diff are now honest gated previews (reverify before showing).
• Directory-mode JSON file keys are full relative paths, not basenames.
• Overlapping fix plans are surfaced rather than silently dropped.
• Stdin lint diagnostics include a code frame with "input.mds" source label.

Phase C — Formatter gate + format_str_named

• Trailing-insignificant-text stripping in structural_equivalent eliminates the
  formatter-invariant false positive on trailing blank lines.
• format_str_named(source, base_dir, file_name): new public API that threads a
  caller file name through the formatter; mds fmt errors now name the file.

Phase D — Source-map accuracy + error quality

• --source-map --inline -o - (stdout) relativizes sources[] entries against CWD, eliminating literal absolute-path output. ../-chain reconstruction (which could still reconstruct the absolute path from a deep CWD) was found during review to remain live — HIGH severity — and was closed in the post-review remediation described below. Stdin --inline -o - is now allowed (was incorrectly rejected).
• type_mismatch errors carry spans via EvalContext threading.
• name_collision_at upgrades in ExportDirective::Wildcard, alias, and merge paths.
• mds::syntax label deduped ("syntax error occurred here").
• ArityMismatch help text added. \{ escape hint on unclosed brace.
• Messages-mode source-map warning reworded surface-neutral, deduplicated.

Phase E — Wrapper strict options, check summary, --vars UX

• @mdscript/mds wrapper rejects unknown option keys (mds::invalid_options).
• CheckOptions split from CompileOptions; check/checkFile no longer accept
  source-map options.
• mds check summary: "N passed, M failed" (was "N checked").
• mds fmt --check summary adds "N unchanged" count.
• --vars JSON errors include the file path.
• conftest.py picks the freshest CLI binary by mtime.

Phase F — Docs sweep + CHANGELOG

• spec.md: str( → string(); @# nonexistent comment syntax removed; unclosed
  code fence documented; §4.9 output example now includes emitted frontmatter.
• README.md: sidecar name corrected (<output>.map); fmt stdin demo updated.
• main.rs after_help: same fmt demo fix; --quiet help text clarified for lint.
• napi/Python/JS/WASM READMEs: sourceMap/sourcesContent and lint API documented.
• CHANGELOG: all behavior changes entered; str( → string() in migration bullet;
  sidecar name fixed in Source Map v3 entry.

Verification

All gates green at tip f55f4d0:

Gate	Result
cargo nextest run --workspace	1757/1757 passed
cargo fmt --all --check	clean
cargo clippy --workspace --all-targets -- -D warnings	0 warnings
node --test crates/mds-napi/__test__/index.spec.mjs	93/93 passed
pytest crates/mds-python/tests -q -m "not perf"	183 passed, 21 deselected 1
npm test -w packages/mds	248/248 passed
bundler workspaces (vite/rollup/webpack/rspack/bundler-utils)	all pass
WASM binary size	764.8 KB / 800 KB budget
Snyk code scan (crates/, packages/mds/src)	0 issues

Test Plan

• mds build foo.mds (bare filename from file's directory) — should succeed
• compile(src, {sourceMap:true}).sourceMap.sources[0] — should equal "input.mds" on napi, WASM, Python
• mds fmt on file with trailing blank line after @end — should exit 0
• mds check on directory — summary should say "N passed, M failed"
• mds lint --fix --check — should print "fix rejected:" for overlapping fixes
• @mdscript/mds compile(src, {unknownKey: true}) — should throw mds::invalid_options
• mds build template.mds --source-map --inline -o - — no absolute paths in stdout

---

Post-Review Remediation (2026-07-18, ~20 additional commits)

A full code review of this PR (13 reviewer agents, 9 focus areas) found 91 issues.
57 were fixed in a resolve pass across approximately 20 additional commits. 29 were
deliberately deferred as tracked follow-ups (FIX_SEPARATE / TECH_DEBT). 1 HIGH security finding — sources[] ..-chain path reconstruction — was escalated and fixed by explicit maintainer decision: a relativize_source choke-point in crates/mds-core/src/source_path.rs now applies project-root containment at both resolver.rs finalize sites; the napi and Python surfaces additionally moved from absolute paths to root-relative paths; Windows verbatim UNC prefix handling was added. 3 were confirmed
BY_DESIGN.

User-visible behavior changes introduced by the resolve pass

Silent gate bypass fixed (mds fmt / mds lint --fix on relative paths)
mds fmt <bare-filename> was swallowing genuine mds::syntax errors and printing
"Unchanged" (exit 0), because a relative base_dir caused check_symlink to fail
silently, falling through to a weaker structural fallback instead of running the
compile-equivalence gate. mds lint --fix <relative-path> was likewise rejecting
every fix with no diagnostic and exiting 2. The original "bare filename" blocker fix
did not cover the paths that compute a base_dir; resolve_base_dir now canonicalizes
to an absolute path before those checks run.

Directory walker all-excluded now exits non-zero
A directory whose .mds files all lived under hidden directories (.git, .venv,
.claude) or node_modules previously produced "No .mds files found" and exit 0 — a
CI gate passing green having validated nothing. The walker now exits non-zero and emits
a distinct skip-count message that is not suppressed by --quiet.

checkFile/lintFile reverted to synchronous throws
Both had been made async during this PR's development, silently changing the public
error contract (sync throw became an unhandled rejection). The pre-existing contract
is restored; async keywords removed.

@mdscript/mds wrapper now accepts basePath on compile/check
The option validator's METHOD_KEYS table was not derived from the TypeScript
interfaces, so basePath — which the underlying napi binding accepts — was rejected by
the wrapper with a generic "unknown key" error. The table is now generated from the
interface types at compile time, and napi's purpose-built error message is reachable
through the universal package.

lint --fix --check --format json <dir> now emits a parseable JSON envelope
Previously this combination produced exit 1 with empty stdout, causing JSON.parse("")
to throw in any downstream consumer. The JSON envelope is now emitted before exit.

lint - --fix --check no longer silently applies fixes and writes to stdout
The stdin lint path was not reading the --check/--diff flags, so this combination
applied all fixes and wrote the result to stdout rather than exiting 1 unmodified. The
flag combination is now rejected at the usage guard for stdin input.

Terminal-escape sanitization extended to the CLI error-rendering boundary
sanitize_control_chars covered LintDiagnostic.message/.help but not
MdsError::Syntax messages, which can embed user-controlled source fragments. Untrusted
.mds source could emit raw ESC bytes via mds lint or mds build. The sanitization
boundary is now the CLI error-rendering layer for both subcommands.

FixOutcome is #[non_exhaustive]; fix-plan sortedness guard is unconditional
mds::fix has never shipped on crates.io, so adding #[non_exhaustive] is free today
and a permanent breaking change after publish. The ascending-sortedness precondition for
the right-to-left accumulation in apply_fixes_incremental was enforced only by
debug_assert!, which is compiled out in release; an external caller passing an
unsorted FixPlan would get silent source corruption written to disk. Both are promoted
to unconditional fail-closed guards before the crates.io publish window closes.

crates/mds-napi scripts.build renamed to build:native
As build, the script joined the npm run build --workspaces fan-out that release.yml
runs after publishing @mdscript/mds-napi and before publishing the universal
@mdscript/mds package. A failure there would strand the release with platform
packages published but the universal package absent — npm will not accept a republish
of the same version.

CHANGELOG [Unreleased] restructured to Keep a Changelog conformance
The section had accumulated two Added, two Changed, and two breaking groups at
different heading depths and in divergent styles, split by a horizontal rule ~200 lines
apart. Merged and reordered before bump-version.mjs stamps the version.

Deferred items

29 issues were designated FIX_SEPARATE and will be filed as tracked GitHub issues.
These include: complexity refactors in the fix pipeline (apply_fixes dead code,
reverify gate duplication, oversized functions), pre-existing structural debt
(oversized resolver.rs / build.rs), the stdin label convention decision (#37,
recommended to resolve before v0.5.0 to avoid a second wire-format churn), and
TypeScript surface improvements that constitute deliberate behavior changes deserving
their own PRs.

---

Second Code-Review Pass (2026-07-18/19, 9 commits)

Two issues were missed by the first resolve run — the triage ledger's per-file group
tables enumerated 55 while its bucket count said 57. The two were implicitly FIX_NOW
by subtraction but were never dispatched to the resolver. Both had defective earlier
commits; one of those commits (a7ef84f) left the tree red.

Source-map path disclosure (HIGH / security)

sources[] entries in inline source maps could reconstruct an absolute filesystem
path, leaking the username and directory layout into compiled output that ships to end
users.

• All relativization now funnels through a single choke point,
  mds_core::source_path::relativize_source, applied unconditionally at both
  resolver.rs finalize sites. A release-critical security invariant must not sit
  behind a flag (PF-005).
• The rule is project-root containment, not "no ../". ../src/a.mds is correct
  SourceMap v3 output when the source lives above the output file and must survive;
  only paths that escape above the project root collapse to a basename. The reverted
  commit a7ef84f had this logic backwards.
• CompileOptions gains source_map_base: Option<PathBuf> — BREAKING; callers
  that use struct-literal construction must add ..Default::default(). #[non_exhaustive]
  was deliberately rejected: it forbids struct-literal and functional-update construction
  from other crates, which would break the existing bindings.
• FileSystem::source_root() -> Option<String> added with a provided default body —
  non-breaking for external implementors.
• Observable change: napi and Python sources[] go from absolute paths to
  project-root-relative paths. The root is detected via .git / .mdsroot, falling
  back to the entry-file directory.
• Windows fix (discovered by CI): verbatim UNC prefixes (\\?\C:\…) were not
  stripped from the detected root, so containment failed on the first path component
  and every Windows source map silently collapsed every entry to a basename.

mds fmt non-atomic write (MEDIUM)

std::fs::write truncates then writes; a crash or power loss mid-write left the
user's only copy of their source file truncated with no recovery path.

• All fmt writes now route through a shared atomic_write_file helper (moved from
  lint.rs → output.rs, making it available to both subcommands).
• sync_all() is called before NamedTempFile::persist(). The previous flush() was
  a no-op: NamedTempFile derefs to an unbuffered File, so flush() on it does
  nothing.
• File mode is masked with & 0o7777 to strip the S_IFMT type bits before passing
  to set_permissions.
• path.display() is used in all six error messages (was path raw, which on Windows
  emits \\?\ prefixes unreadably into diagnostics).
• Temp file prefix renamed from .mds-lint-fix- to something that doesn't embed the
  sibling subcommand's name.

Cross-surface parity (PF-007)

Two differential tests added to catch future surface divergence early:

• V-SM1: napi ↔ WASM — verifies sources[] values match across the two JS surfaces.
• CF-SM2: napi ↔ WASM ↔ CLI ↔ Python — four-way cross-surface comparison.

CF-SM2 hard-fails when the CI environment variable is set if any surface is
unavailable, so it cannot silently degrade to a green partial run. To support this,
the JS CI job now builds mds-cli and installs the Python binding before running the
JS test suite.

Follow-ups filed (real GitHub issues — not review-ledger IDs)

Three limitations of the atomic write approach are tracked but deliberately not fixed
in this pass:

• atomic_write_file: metadata() failure silently yields mode 0600 via .ok() #225 — metadata() failure silently yields mode 0600 via .ok()
• atomic_write_file: rename-based write does not preserve platform ACLs, xattrs, or owner/group #226 — rename-based writes do not preserve hard links, ACLs, xattrs, or owner/group
• build::write_output still uses truncate-then-write (non-atomic) for compiled artifacts #227 — build::write_output still uses truncate-then-write for compiled output artifacts

Verification

CI 18/18 green at HEAD c034fd1. Locally: 1,832 Rust tests (nextest), 36 doc tests,
519 JS, 199 pytest, cargo fmt --all --check and cargo clippy -D warnings clean,
verify-versions, cargo publish -p mds-core --dry-run. QA ran 31 acceptance
scenarios — all pass. Atomicity confirmed by inode identity check and a 688,650-sample
concurrent poller that observed zero truncation windows.

Reviewer note

CHANGELOG carries four new entries under [Unreleased] (Security / BREAKING / Changed
/ Fixed) covering the source-map and atomic-write changes. ADR-005 was amended (not
replaced) to document the containment rule and the source_map_base field. .devflow/
is gitignored, so the ADR amendment is local-only and will not appear in the diff.

Footnotes

1. Corrected — the original entry claimed 198 passed / 6 deselected, which
   came from a local run using -k "not perf" instead of -m "not perf". Because -k
   matches substrings of the full test node id, it silently deselected the 15 parametrized
   test_perf4_malformed_input_never_yields_internal cases alongside the 6 genuinely
   perf-marked ones, producing a false 198/6 split. The correct split is 183 passed /
   21 deselected. CI was never affected: .github/workflows/ci.yml lines 175, 180, 207,
   212 and crates/mds-python/pyproject.toml:45–47 all use the correct -m "not perf"
   form. The 15 adversarial panic-path guards do run in CI. This -k-vs--m trap is
   documented as repo pitfall PF-008. ↩