Repository navigation
Releases
Releases · WJDdidi-1/dev-doctor
v0.2.4
0.2.4 — 2026-11-15
- New: a nested
.aiignorenow works — an.aiignorein a subdirectory applies to that directory, git's per-directory rule:pkg/.aiignorewithbig.loghidespkg/big.logand nothing else, so a package can ignore its own generated files without touching the repo-root file. Before this, a nested.aiignorewas silently ignored (a 200 KBpkg/big.logstill cost 15 points) while a nested.gitignorealready worked — a user writing.aiignoreby gitignore semantics hit a silent trap. The patterns keep their existing meaning (directorydir/, basename globs,/-anchored paths, relative to the file's own directory);--fixstill writes only the root.aiignore, and a nested.aiignorefile itself is counted like any other small file. The scan cache fingerprints every.aiignorethe walk reads (not just the root one), so a rule change at any level forces a full re-scan; a cache file from before this change degrades to one full re-scan and is rewritten in the new shape. The method is git's own per-directory.gitignore(gitignore(5)): patterns are read from the file in the same directory as the path, or any parent directory, and match relative to that file's location. - New:
context --min-score N/all --min-score N— pass at this context score instead of 85 (a whole number from 0 to 100): a strict team passes at 95, an old repo starts at 70 and raises the bar as it cleans up. The verdict, the exit code, the GitHub annotations and the report all follow the bar, and the result carries it asminScore, so--jsonand MCP consumers can read the bar the verdict was judged against; a--fixre-scan keeps the same bar instead of silently falling back to 85. The default stays 85, so existing gates, hooks and docs keep meaning what they meant. The method is Biome's--max-diagnosticswith--error-on-warnings(26,105 stars): the threshold is a number the user sets, not a constant baked into the verdict. - New:
--fix --dry-runnow exits1when the fix would change.aiignore, even when the score passes — a repo at 85/100 with a pending*.logentry used to exit0, so no CI gate could tell "clean" from "fix pending". The preview itself is unchanged (same diff-style listing, nothing written); the dry run now answers "would the fix change anything?", and--json/ MCP carry the same answer asfix.wouldChange. The method is prettier's--check(52,413 stars): exit1when something would change, because that is what makes a preview usable as a CI gate. No new flag on purpose — the preview already is the check, so a second flag would split one question in two. - New: MCP structured output — every tool now declares a loose
outputSchema: { type: 'object' }intools/list, and a successfultools/callreturns the same object asstructuredContentalongside the unchanged text block, so a calling application (the MCP Inspector's Structured Output panel, a host that routes on fields) can read the result typed instead of parsing the text. Error results carry nostructuredContent. The schema stays loose on purpose: the payloads are dynamic nested objects with optional fields, and the Inspector validatesstructuredContentagainstoutputSchemawith AJV, so a detailed schema would warn on any property it does not list. The declared protocol version stays2024-11-05: the fields are additive and older clients ignore them, the same precedent as annotations. The method is the MCP Inspector's (11,297 stars) structured-output panel. - New:
context --new-from-rev[=<ref>]/all --new-from-rev[=<ref>]— report only noise that is new since the ref (defaultHEAD, or--changed's ref when it names one): it implies--changed, and a file already noisy at the ref counts only its growth, so touching a 2 MB lockfile to bump one version adds no noise, while growing it by 100 KB reports exactly those 100 KB. Two different refs (--changed=X --new-from-rev=Y) is a usage error: one ref governs both the changed set and the new-noise baseline. A renamed file counts as new (its old path is not traced); review items and secret findings are still reported for every changed file. The ref sizes come from onegit ls-treecall, so the baseline costs one git invocation however many files changed. The MCPdiagnose_context/diagnose_alltools take the same behaviour asnewFromRev. The method is golangci-lint's--new-from-rev, at file level. - New:
context --cache/all --cache— reuse the scan cache for unchanged files (.dev-diagnosis-cache.jsonat the scan root): a second scan of an unchanged tree skips re-reading files whose size and mtime still match, so a 44-second scan of a 53,000-file repo comes back in about 5 seconds (measured on a Node.js checkout: 43.9 s fresh, 5.4–6.1 s cached — about 8×, not the 20–40× first predicted: the walk, ignore matching and aggregation still run, only the content reads are skipped). A fully-cached run does not rewrite the cache file: when nothing changed, its bytes and mtime stay as they were. Opt-in, off by default;--cache-location <file>moves the cache file. The cache file is plain JSON (fingerprints only — findings carry rule and line, never a value) and is excluded from the scan. A changed.aiignoreor.gitignore, a new tool version or a corrupt cache means a full re-scan; a--changedscan only adds or updates entries, never drops the rest. The result says when the cache was used (cachedin--json, oneCache:line in the terminal and--report), and a cache hit is a fingerprint-verified earlier observation, not a blind spot — cached files are neverunknowns. The cache is a local performance artifact, not a security boundary: a hand-edited cache file could hide a finding, the same as a hand-edited.eslintcache— delete the file to force a fresh scan. CI and the pre-commit hook never use it by default. The method is ESLint's--cache, metadata strategy only — hashing would cost the reads the cache exists to avoid. The MCPdiagnose_context/diagnose_alltools take the same behaviour ascache: true. - New:
all --annotations/context --annotations— also print the top noise items as GitHub Actions workflow commands (::warning file=...::...), so they surface on the run's annotations panel without opening the log: no token, no file, no upload. A failing score adds one run-level::error::. At most 10 items (the platform's per-level cap); directory rollups are skipped (an annotation needs a file) and secret findings are never annotated. With--jsonthe lines go to stderr so stdout stays parseable, and with--fixthey follow the post-fix re-scan. The Action needs no change —args: --annotationspasses straight through. The method is golangci-lint's github-actions output format. - New:
binariescheck —dev-diagnosis binaries [path](andall, plus the MCPdiagnose_binariestool) checks up the largest native binaries in a repo (ELF, PE, Mach-O, 16 KB or larger;.git,node_modulesand hidden directories skipped, like the context scan): one hardening table each — PIE, NX, RELRO, stripped, stack protector, fortify, CET/BTI-PAC, RPATH, RUNPATH — plus whole-file entropy. The headers are read with the Node standard library only: no engine, no network, no REA dependency. A value the headers cannot determine isunknownwith a note saying why (a static binary has no dynamic symbol table, so its stack protector cannot be told from headers), never guessed. This is a checkup, not a security audit: it reports what the headers say, never assesses exploitability, and it always passes — a binary with PIE disabled is a fact, not a failure.--top Nshows the N largest (default 5, max 20). Verified against REA's ground truth for esbuild 0.25.0: all ten hardening fields and the entropy (6.18 vs REA's 6.1813) agree. The method is REA's no-engine probes, re-implemented. - New:
unknownsin the context report —all(terminal,--json,--report, MCPdiagnose_all) now reports what the scan does not know: files past the file limit that were never counted, paths that could not be read (including dangling symlinks), and files over 1 MB that were not content-scanned for secrets. In--jsonthe field isunknowns(each entry a kind, a plain detail, and counts) withvisibleFilesPct, the share of the repo's files the score is based on; the terminal prints anUnknowns:list, and the score note now says the exact coverage instead of "totals are a lower bound". An unknown costs no score points — it is a measured blind spot, not a failure — but a 100/100 on a half-scanned repo is not a clean bill for the whole repo, so the report says how much it saw. The method is REA's Evidence/Unknown model: unknown is a first-class answer, not a missing one. (A symlink to a real file is counted as that file now — the agent is handed the target's contents either way — where the walk used to skip every symlink silently.) - New:
all --only <checks>/all --skip <checks>— run only the named checks, or every check except the named ones (comma-separated: context, binaries, path, flakes, cache; the two flags cannot be combined). The cache check runs the build twice, soall --skip cacheis the fast path when the build itself is not under suspicion; checks skipped this way are listed as skipped, so the summary stays honest, and--fixrefuses to run when context is skipped (it writes the context check's suggestions). The MCPdiagnose_alltool takes the same selection asonly/skiparrays. The method is super-linter's VALIDATE_ toggles: one list selects the checks, the rest are skipped. - New:
secretscommand —dev-diagnosis secrets <file>...scans named files for secrets only (the same credential shapes the context check looks for), prints file + rule + line, never the value, and exits 1 when one is found. It is the command the newdev-diagnosis-commit-msgpre-commit hook runs on the commit mess...
v0.2.2
What's new in 0.2.2
- The MCP server is now listed in the official MCP registry (
io.github.WJDdidi-1/dev-diagnosis). A release-triggered workflow publishes the listing via GitHub OIDC, so agents can find and install the server from the registry.server.jsoncarries the registry metadata,scripts/check-registry-release.mjswaits for the new npm version to be live before the listing is published, andtest/registry.test.mjskeeps the metadata in sync with the package version. llms.txtat the repo root — a short machine-readable summary for AI search and retrieval, pointing agents at the install and usage commands.package.jsoncarriesmcpNameand expanded keywords (ai-agent,mcp,model-context-protocol,claude,context-window,agent-skills,token-optimization) so the package is discoverable by agents searching npm.
Verification
- Local tests 127/127; CI 12/12 green (Ubuntu/macOS/Windows × Node 18/20/22/24) on the release commit — run https://github.com/WJDdidi-1/dev-doctor/actions/runs/43440309626
v0.2.1
0.2.1 — 2026-11-12
- Fix:
dev-diagnosis setupand--skill-generate --globalwrote MCP configs and skills to the wrong home directory on macOS and Windows (they ignored$HOME). They now honour$HOMEon all platforms. v0.2.0 shipped with this bug on macOS/Windows; CI caught it after the release (8 of 12 matrix jobs red) and this patch is the fix. - Fix: test fixtures and tests are now CRLF-safe, so the suite passes on Windows checkouts as well as macOS and Linux.
- Verified: CI 12/12 green (Ubuntu/macOS/Windows × Node 18/20/22/24).
v0.2.0 — MCP server, one-command setup, and a screencast
What's new
dev-diagnosis --mcp— the four checks as an MCP server on stdio (pure Node.js standard library, no new dependencies): five tools (diagnose_context,diagnose_path,diagnose_cache,diagnose_flakes,diagnose_all), each returning the same JSON the CLI's--jsonproduces.--sandbox <dir>restricts every path the tools touch to that directory.dev-diagnosis --skill-generate— writes a Claude Agent Skills SKILL.md (project or--global) telling an agent to rundev-diagnosis allwhen it starts work in a repo, fix what FAILs, and re-run to confirm. Never overwrites an existing SKILL.md.dev-diagnosis setup— wires the MCP server into Claude Code, Codex CLI, Cursor and VS Code in one command. Previews exactly what will be written first; merges into existing configs without touching other entries;--dry-runpreviews,--checkreports.- GitHub Action —
action.ymlat the repo root runsdev-diagnosis allin one CI step and fails the job when a check fails. contextnow reports token cost —≈ 439k tokens (estimate)next to the noise list, andestimatedTokensin--json.allends with a one-line summary — passed/failed/skipped counts, context noise bytes, cache saving — in text and--json.- README screencast — a 22 s terminal recording (
docs/demo.gif):allfinds ≈439k tokens of noise,--fixwrites one.aiignoreentry, a re-run comes back 94/100 PASS. Every line is verbatim CLI output.
Fixes
context --fix/all --fix(and MCP tools withfix: true) used to report the pre-fix verdict — exit 1 and FAIL — even though the fix had landed and a re-run scores clean. They now re-scan after writing.aiignoreand report the post-fix score, verdict and exit code. Other failures are still not masked:all --fixexits 1 when flakes, path or cache still fail.context --fixno longer writes review suggestions (e.g. secret-like files) into.aiignore— a basename pattern likesecret.jshid every same-named file in the repo while fixing nothing. Review suggestions are advisory only (reviewSuggestionsin--json).contextno longer lists noise that costs no points and tells you to fix it — on a 100/100 repo it still printed a fix for the lockfile, contradicting its own PASS.- Test suite now runs serially (cache timing skewed under parallel runs) and no longer leaks ~100 MB of temp dirs per run.
Verified
124/124 tests, self-check 100/100, real MCP protocol check 25/25 (JSON-RPC 2.0, sandboxing, error handling), real setup + skill end-to-end 33/33. Cold npx start 0.77 s to the first conclusion. No new runtime dependencies; Node >= 18; fully offline.
Install: npx dev-diagnosis-cli or npm install -g dev-diagnosis-cli
v0.1.8
0.1.8 — 2026-11-12
- Fix:
all --jsonembedded the build's full stdout (coldStdout/warmStdout) in the cache check, while standalonecache --jsonalready left it out — a chatty build bloated the machine-readable output. Both shapes are now the same: timings and verdict only. The--jsonoption also now documentscache(the usage line and help text listed onlycontext,path,flakesandall, although standalonecache --jsonalready worked). - New:
contextnow also honours.gitignore— files and directories it lists are excluded from the scan, at the repo root and in nested.gitignorefiles alike, so a repo whose build output, logs or data dumps are already git-ignored no longer gets flagged for them, and--fixno longer duplicates those entries into.aiignore. The common pattern forms work (*,?,[...],**,/-anchored paths, directory-onlydir/,!negation with last-match-wins);.git/info/excludeand the global gitignore are not read. (82 tests.) - Dogfood: the repo now ships a
.aiignoreexcluding the demo fixture (examples/demo-repo/), sodev-diagnosis allon a checkout passes its owncontextcheck (was 77/100 FAIL, now 100/100 PASS). The fixture is intentionally noisy test data and stays noisy when scanned directly —npm run exampleoutput is unchanged.
v0.1.7
0.1.7 — 2026-11-12
- Fix:
dev-diagnosis <path>no longer errors with "unknown command" — the usage line promises[all] [path], but a bare path was treated as a command name. A bare positional that is an existing directory now meansallon that path (options like--commandstill apply); a word that is neither a known command nor a directory is still a usage error, so a typo stays a typo. The help text and README say so. - Fix:
--top Nwas silently ignored in--jsonoutput —flakes <dir> --json --top 1returned all five demo tests instead of one. The JSONtestsarray is now limited to the N highest-ranked tests, in standaloneflakesand inall --jsonalike;totalsstill describes the whole run set, the same split the text table makes. - Fix:
all --jsondropped the reason a check could not run — a missing runs directory or a failing build came out as"flakes": null/"cache": nullnext tooverall: FAIL, with nothing saying why. A check with no result now reports{ "error": "<reason>" }instead, so a script consuming the JSON can tell which check failed and why. - Fix: a run directory with no JUnit XML files was silently dropped —
flakeson two run directories, one of them empty, reported "runs: 1" with no mention of the second run. An empty run directory is now named in the output (and in--jsonunderskippedRuns) and fails the check: a CI run that produced no reports is a broken upload, not a run with zero tests. (72 tests.)
v0.1.6
0.1.6 — 2026-11-12
- Fix: an empty JUnit file (0 bytes, whitespace only, or a declaration/comment and nothing else) no longer parses as a clean run of zero tests — the XML reader now requires a root element, so the file is reported as "no root element", listed in the warnings, and the
flakescheck fails instead of silently reporting on half-read data. A genuinely empty report (<testsuites></testsuites>) still parses to zero tests. (62 tests.) - Docs: the 0.1.5 entry is now dated 2026-11-11.
v0.1.5
0.1.5 — 2026-11-11
- Fix: a JUnit file that cannot be parsed no longer passes silently —
flakesused to collect the parse error into a warnings list nothing ever printed, so a run set of only corrupt XML reported "no flaky tests" and exited 0. The warning is now printed with the file and the parse position, and the check fails with how many files could not be parsed, so the verdict is never based on half-read data. (58 tests.) - Docs: a Troubleshooting note for running
npxinside a checkout of this repo — npx prefers the checkout's own package.json and fails withdev-diagnosis: not found;npm installdoes not fix it (no dependencies, so nonode_modulesis created). Runnode bin/dev-diagnosis.jsdirectly,npm link, or runnpxfrom another directory.
v0.1.4
0.1.4 — 2026-11-11
- Fix: large files now get an exact-path
.aiignoresuggestion (their repo-relative path), socontext --fixcan hide them — previously large files had no suggestion at all, so--fixcould never clean a repo with an oversized file and re-scanning still failed (the demo fixture's 1.68 MBdata/export.jsonproved it). After the fix, fix then re-scan comes back clean (Score 100/100). (54 tests.) - Docs: CHANGELOG 0.1.3 entry now dated 2026-11-11.
v0.1.3
0.1.3 — 2026-11-11
- Fix: nested build-output directories are reported by their full path from the repo root (
packages/foo/dist/) instead of a baredist/— the bare entry only matches top-level output, so--fixon a repo whose build output lives in a subdirectory wrote an.aiignoreentry the next scan ignored, and the scan kept failing after the fix. Files under one build directory are also rolled up into a single row instead of one row per file. (53 tests.)