@vyuhlabs/dxkit 2.5.2 → 2.7.0

package/CHANGELOG.md

@@ -7,6 +7,211 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.0] - 2026-05-29
+
+The "Repo Explore" release. dxkit now builds a deterministic code graph
+of your repo and exposes it three ways: a CLI to query structure, an
+interactive graph in the dashboard, and per-finding blast radius in
+detailed reports. The throughline is helping a coding agent fix findings
+by navigating structure instead of re-reading whole files.
+
+### Added
+
+- **`vyuh-dxkit explore`** with six subcommands (`entry-points`,
+  `hot-files`, `communities`, `file`, `feature`, `api-surface`) for
+  asking the code graph what the repo does, where a feature lives, which
+  files are load-bearing, and what the public API surface is.
+- **`vyuh-dxkit context <query>`** returns a token-budgeted structural
+  slice for a query (an anchor symbol, its relevant neighbors, and the
+  blast radius), plus a fail-open Claude Code PreToolUse hook that feeds
+  it on Grep/Glob so agents need fewer follow-up whole-file reads.
+  Auto-installed with `--with-dxkit-agents`.
+- **Interactive Graph tab** in `vyuh-dxkit dashboard`, embedding
+  graphify's code-graph viewer with the renderer bundled to work
+  offline. Large repos render a community-aggregated view.
+- **`--graph-context`** on `vulnerabilities`, `test-gaps`, and `quality`
+  attaches each finding's module and blast radius (which files call into
+  it) to the detailed report, so a fixing agent gets the structural map
+  per finding without a separate lookup.
+- **Per-language call-graph reliability.** Where the call graph cannot be
+  resolved (C#, which cannot follow `using` across assemblies), blast
+  radius reads "n/a" rather than a misleading "0 callers", so it is never
+  mistaken for "safe to change".
+- **`dxkit-action`** now folds blast radius into prioritization as an
+  additive signal, and the generated `AGENTS.md` documents the new
+  commands.
+
+### Changed
+
+- `vyuh-dxkit health` writes the code graph to
+  `.dxkit/reports/graph.json` as a side effect, so a single run
+  populates the artifact the explore, context, dashboard, and
+  graph-context surfaces read.
+
+## [2.6.0] - 2026-05-23
+
+The "per-finding suppression + public-repo-safe baselines" release.
+Adds the typed-category allowlist surface for false-positive /
+test-fixture / mitigated-externally / accepted-risk / deferred
+suppression with inline + file-level modes; retires license
+findings from the baseline (~73% size drop on real customer repos);
+introduces three baseline modes with visibility-aware defaults so
+public repos no longer leak file paths, package names, and
+advisory IDs through a committed baseline.
+
+### Added
+
+- **Per-finding allowlist** — `vyuh-dxkit allowlist add/list/show/audit/prune`.
+  Typed-category suppression (`false-positive`, `test-fixture`,
+  `mitigated-externally`, `accepted-risk`, `deferred`) with required
+  reason + (where relevant) expiry. Two surfaces: inline
+  `// dxkit-allow:<category> reason="..."` annotations and a
+  file-level `.dxkit/allowlist.json`. `accepted-risk` and `deferred`
+  require expiry (default 90 days). See
+  [docs/commands/allowlist.md](docs/commands/allowlist.md).
+- **Strict stale-annotation detection** — orphaned `dxkit-allow:`
+  annotations (where the underlying finding is now gone) emit a
+  new `stale-allow` baseline kind on the next scan. The
+  TypeScript `@ts-expect-error` pattern, applied to suppressions —
+  forces cleanup, prevents the annotation graveyard. Allowlisting
+  a `stale-allow` finding is forbidden; only remediation is to
+  remove the orphaned comment.
+- **Allowlist activity in PR comments** — the
+  `dxkit-guardrails.yml` workflow's sticky PR comment now includes
+  an "Allowlist activity" section listing every entry added (or
+  removed) on this branch versus the baseline commit. Reviewers
+  see new suppressions being introduced and can sanity-check
+  category + reason + expiry before approving.
+- **`vyuh-dxkit issue`** — pre-filled GitHub Issues for false
+  positives, missing findings, bugs, feature requests, and docs
+  gaps. Nothing submits automatically — the CLI opens the
+  customer's browser at a new-issue URL with env metadata
+  pre-populated, customer reviews + clicks "Submit." See
+  [docs/commands/issue.md](docs/commands/issue.md).
+- **`commentSyntax` on language packs** — each pack declares its
+  line-comment marker (`#` for python/ruby; `//` for
+  typescript/go/rust/csharp/kotlin/java). Drives the inline
+  allowlist-annotation generator across every language uniformly.
+  Recipe-enforced: scaffolder ships an empty placeholder so
+  unfilled packs fail the contract test until populated.
+- Three preemptive architecture rules in `scripts/check-architecture.sh`
+  lock down the allowlist canonical entry points: no `createHash`
+  inside `src/allowlist/`, no direct `allowlist.json` IO outside
+  the canonical loader, no language-comment fallback literals
+  (`?? '//'`) anywhere in the module.
+
+### Changed
+
+- **License findings retired from the baseline.** Per-package
+  license attributions no longer flow through the baseline
+  producer registry — they were informational, not regression
+  material, and dominated baselines on real customer repos
+  (~73% of entries). The canonical license inventory now lives
+  solely in `.dxkit/bom.json` (`vyuh-dxkit bom`), which already
+  carries richer per-package data (licenseType, licenseText,
+  sourceUrl, supplier, releaseDate). Lenient migration:
+  baselines written by older dxkit versions still load — the
+  reader silently filters retired `license` entries on the way
+  in (no file rewrite until the next `baseline create --force`).
+  Dependency vulnerability tracking is unchanged — `dep-vuln`
+  is a separate identity kind on a separate producer and still
+  blocks via the guardrail check.
+- **Sanitization machinery for baseline entries.** New pure
+  module `src/baseline/sanitize.ts` introduces a stripped
+  `SanitizedBaselineEntry` variant (`{ id, kind, sanitized: true }`)
+  carrying identity + kind only. The `sanitizeEntry` /
+  `sanitizeFile` pass collapses every rich field; cross-run
+  matching still works at full confidence via the fingerprint
+  multiset pass. Producers now emit the rich
+  `RichBaselineEntry` shape (a `BaselineEntry` excluding the
+  sanitized variant); sanitization is a write-time
+  transformation, never a producer concern. Consumers walking
+  a baseline narrow via the `isSanitized` type guard before
+  switching on `entry.kind`. Write-path wiring + visibility-
+  aware mode selection ship in a follow-up commit.
+
+### Added
+
+- **Three baseline modes with visibility-aware defaults.**
+  `committed-full` (today's behavior, rich entries), `committed-
+  sanitized` (stripped per-entry payload via the sanitization
+  pass), and `ref-based` (no committed file; guardrail check
+  recomputes the prior side from a git ref via `git worktree
+  add`). The mode is picked by a single resolver
+  (`src/baseline/modes.ts`) with precedence: CLI flag →
+  `.dxkit/policy.json:baseline.mode` → visibility-derived default
+  (public repos auto-pick `ref-based`; everything else picks
+  `committed-full`). `committed-sanitized` is never auto-picked
+  — it's the explicit opt-in for compliance-conscious private
+  repos.
+- `vyuh-dxkit baseline create [--mode <m>] [--ref <r>]` and
+  `vyuh-dxkit guardrail check [--mode <m>] [--ref <r>]` — flags
+  override `policy.json` for one-off runs.
+- `gh repo view --json visibility` probe + per-process cache
+  in `src/baseline/visibility.ts`. Every failure path returns
+  `'unknown'`; the resolver treats unknown as private to avoid
+  surprise sanitization when `gh auth` lapses.
+- Ref-based gather mechanics in `src/baseline/ref-baseline.ts` —
+  `withRefWorktree(opts, fn)` is the reusable primitive; tears
+  down the worktree on success + failure. Mirrors file-mode
+  `.dxkit/salt` into the worktree so secret-HMAC entries pair
+  across cwd + worktree.
+
+### Architectural notes
+
+- New CLAUDE.md rule 11: baseline mode resolution flows through
+  `resolveBaselineMode`. Two arch-check rules lock the contract:
+  no `gh repo view --json visibility` outside
+  `src/baseline/visibility.ts`; no `git worktree add` / `remove`
+  outside `src/baseline/ref-baseline.ts`.
+- `resolvePolicy` lifted from `check.ts` to `policy.ts` so
+  `createBaseline` and `runGuardrailCheck` share one canonical
+  loader.
+
+### Discovery surfaces
+
+- **PR-comment markdown** now shows the resolved baseline mode in
+  the sticky footer (`_Mode_: \`ref-based\` (ref: \`origin/main\`)`).
+  Reviewers see WHY a guardrail run picked a given posture.
+- **JSON renderer** carries `baseline.mode = { value, source,
+  explanation, ref? }` so agents + dashboards can read the audit
+  trail without re-deriving it.
+- **`vyuh-dxkit doctor`** has two new operational checks:
+  - "baseline mode: ref-based" / "baseline captured (mode: ...)" —
+    the existing baseline-captured check now understands ref-based
+    mode (where no on-disk file is expected) so the doctor stops
+    reporting a false-negative on public repos.
+  - "baseline mode aligned with repo visibility" — warns when an
+    explicit `committed-full` pin is in use on a public repo (the
+    posture leaks file paths + package names; the auto-picker
+    would have chosen ref-based).
+- **`dxkit-onboard` skill** — step 5 now ASKs about disclosure
+  posture before running `baseline create`, walks customers through
+  the three modes, and offers a one-shot `.dxkit/policy.json` snippet
+  for pinning the choice repo-wide.
+- **`dxkit-action` skill** — new section explains how to act on a
+  blocked finding when the baseline is sanitized / ref-based
+  (locator stripped at write time; re-run the analyzer for full
+  context or allowlist by fingerprint).
+- **README + getting-started.md** — call out the public-repo
+  posture explicitly so customers don't accidentally commit a
+  rich baseline to an open-source repo.
+
+### Architectural notes
+
+- Added `stale-allow` as a new `IdentityKind` (Rule 9 + Rule 10
+  compliant: identityFor case + producer + fixture row +
+  removed from `DEFERRED_KINDS` once the gather pass landed).
+- The hint formatter (block-time guidance for blocked findings)
+  consumes the canonical `BaselineEntry` discriminated union
+  directly — no invented intermediate "BlockingFinding" shape.
+  TypeScript exhaustiveness across 6+ switches guarantees new
+  finding kinds can't ship without matching cases.
+- `dxkit-action` skill extended with the typed-category +
+  surfaces description; SAST recipe redirects from semgrep's
+  `// nosemgrep:` to dxkit's `// dxkit-allow:` (single canonical
+  suppression surface across all scanners).
+
 ## [2.5.2] - 2026-05-22
 
 The "scaffold UX + lifecycle skills + setup automation" release. Closes
@@ -21,7 +226,7 @@ Tag: `create-dxkit@v0.2.0`. Run `npm init @vyuhlabs/dxkit` to get
 the new combined experience.
 
 Validated end-to-end with two cross-stack walkthroughs on 2026-05-22:
-`vyuhlabs-platform` (python + typescript) and `dpl-studio` (csharp).
+a polyglot Python+TypeScript reference repo and a .NET reference repo.
 Both stacks: defect closures verified, per-pack devcontainer adapts
 correctly, doctor's new tier-3 surfaces operational gaps with
 actionable fix commands.
@@ -1457,9 +1662,9 @@ Four pieces shipped together:
 The post-shipment audit's master bug + its direct cascade:
 
 - **D055** — `.dxkit-ignore` multi-segment paths flatten to basenames
-  in cloc / graphify / grep. `Dev/Addons/VendorAddon/SAPB1/` silently
-  became `{Dev, Addons, VendorAddon, SAPB1}` — cloc then excluded every
-  directory named `Dev` in the tree, killing 90% of source visibility.
+  in cloc / graphify / grep. `app/vendor/generated/` silently
+  became `{app, vendor, generated}`, so cloc then excluded every
+  directory named `app` in the tree, killing 90% of source visibility.
   Fix: `getClocExcludeFlags` emits `--exclude-dir` (basenames) PLUS
   `--fullpath --not-match-d` (Perl regex on full path).
   `getPythonExcludeFilter` emits both a basename set AND a multi-
@@ -1661,7 +1866,7 @@ discipline.
   (osv-scanner reads Gemfile.lock directly, no `bundle env`/`bundle
   show` introspection ladder). Stays accepted-deferred.
 - **D017** (NEW) — `dxkit bom <large-project> > file.json` produces
-  0-byte output intermittently on vyuhlabs-platform (1700+ deps).
+  0-byte output intermittently on a large reference repo (1700+ deps).
   EXIT=0, no error. Workaround: pipe through `cat`. Hypothesis:
   Node stdout buffer doesn't drain before process exit when output
   is large + stdout is a regular file. NOT a 2.4.6 ship blocker —
@@ -1671,7 +1876,7 @@ discipline.
 ### Pre-ship regression — clean
 
 Sequential dxkit reports captured against dxkit-on-dxkit and
-vyuhlabs-platform; 12 reports each diffed against the 2.4.5-fixed
+a large reference repo; 12 reports each diffed against the 2.4.5-fixed
 baseline. Zero code regressions detected. All deltas explained:
 
 - dxkit/test-gaps 16 → 32 — better data (Istanbul vs import-graph
@@ -1723,7 +1928,7 @@ at every commit in the 10-commit branch.
      `typescript`, etc.). `unfilteredTotalPackages` 22 → 353. The
      analyzed project's own deps were missing from BoM whenever the
      bug hit. Most repos that resolve peer-deps cleanly under
-     `--legacy-peer-deps` weren't affected (vyuhlabs-platform's BoM
+     `--legacy-peer-deps` weren't affected (the reference repo's BoM
      stayed correct at 145 packages); repos with subtle peer-dep
      issues silently lost root-dep enumeration.
 
@@ -2592,7 +2797,7 @@ unchanged — consumers can re-derive trivially if needed.
 - 715 tests passing (+18 pm-signals cases: license class mapping,
   compound expressions, staleness thresholds, effort semver deltas).
 - Typecheck + lint + format + architecture + pre-push CI-mirror gate clean.
-- vyuhlabs-platform smoke: all 4 sheets render correctly, exec summary
+- reference-repo smoke: all 4 sheets render correctly, exec summary
   surfaces 3 ship-blockers + 9 sprint-risk findings + pm2 flagged
   copyleft-strong, `@loopback/rest` surfaces as highest-leverage upgrade
   (27 transitive advisories, worst CRITICAL).
@@ -2600,7 +2805,7 @@ unchanged — consumers can re-derive trivially if needed.
 ## [2.3.1] - 2026-04-24
 
 Patch release fixing three install-robustness issues reported on a
-real vyuhlabs-platform install:
+real reference-repo install:
 
 ### Fixed
 
@@ -2646,7 +2851,7 @@ real vyuhlabs-platform install:
   Warnings only, no functional impact; would require either switching
   xlsx libraries (breaking) or upstream archiver modernization.
 
-### Validation on vyuhlabs-platform/userserver
+### Validation on the polyglot reference repo
 
 - `vyuh-dxkit tools` reports 12/13 tools found (vitest-coverage
   correctly listed as missing since lb-mocha is in use)
@@ -2719,7 +2924,7 @@ merge → tag → CI-publishes without deviation.
   unions the roots each package was found in; `isTopLevel`
   OR-merges; vulns dedup on `(id, package, installedVersion)`.
   Closes **D001a** — `bom platform/` previously missed
-  `platform/userserver/` entirely. Side-benefit: naturally
+  the product subdirectory entirely. Side-benefit: naturally
   addresses **D003** (C# multi-project) since each `.csproj`
   becomes its own root. (10h.5.0b)
 
@@ -2836,7 +3041,7 @@ bump required.
 - **TypeScript pack** — BFS over `package-lock.json` (v2/v3) from
   each root `dependencies` / `devDependencies` entry. Pure parser
   `buildTsTopLevelDepIndex` unit-tested; benchmark on
-  `vyuhlabs-platform`: 71/71 findings attributed across 31 vulnerable
+  reference repo: 71/71 findings attributed across 31 vulnerable
   packages, `@loopback/cli` rollup = 29 advisories (matches Snyk UI).
 
 - **Python pack** — BFS over `pip show` graph from packages with empty
@@ -2902,7 +3107,7 @@ bump required.
   `obj/project.assets.json`. Findings still emit; `topLevelDep` stays
   unset.
 
-- Release validated against `vyuhlabs-platform` TypeScript benchmark.
+- Release validated against the TypeScript reference benchmark.
   Python/Go/Rust/C# packs exercised via fixture-based unit tests
   (+53 new tests across the 4 non-TS language test files); real-world
   validation lands with 2.3.0's cross-ecosystem benchmark fixtures.