@vyuhlabs/dxkit 2.5.2 → 2.6.0

package/CHANGELOG.md

@@ -7,6 +7,170 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

package/README.md

@@ -234,6 +234,86 @@ The classifier distinguishes:
 Customize via [`.dxkit/policy.json`](docs/configuration/policy.md) —
 auto-discovered when present, compiled-in defaults otherwise.
 
+### Baseline modes — public vs private repos
+
+The baseline file is committed to git. On public repos that
+disclosure surface matters: a `committed-full` baseline tells anyone
+reading the repo which file/line each finding lives on, which
+private packages you depend on, and which advisory IDs you're
+sitting on unpatched. dxkit ships three modes:
+
+| Mode                  | On-disk content                                          | Auto-default for |
+| --------------------- | -------------------------------------------------------- | ---------------- |
+| `committed-full`      | Rich entries (file/line/rule/package/advisory)           | private repos    |
+| `committed-sanitized` | Stripped to `{ id, kind }` per finding                   | opt-in           |
+| `ref-based`           | No file — guardrail recomputes prior side from a git ref | public repos     |
+
+`vyuh-dxkit baseline create` auto-picks via
+`gh repo view --json visibility`. Pin the choice repo-wide in
+`.dxkit/policy.json`:
+
+```json
+{ "baseline": { "mode": "ref-based", "ref": "origin/main" } }
+```
+
+The cross-run matching contract (fingerprint identity) is identical
+across all three modes — sanitization only strips human-readable
+locators, it doesn't change which findings pair across runs. See
+[docs/commands/baseline.md](docs/commands/baseline.md#modes) for the
+full trade-off discussion.
+
+---
+
+## Allowlist: per-finding suppression
+
+The baseline handles codebase-wide brownfield acceptance ("today's
+mess is grandfathered; tomorrow's must be net-new improvement").
+For per-finding decisions — false positives, intentional test
+fixtures, externally-mitigated risks, deliberately deferred work —
+use the [allowlist](docs/commands/allowlist.md).
+
+Five typed categories signal **why** a finding is suppressed:
+
+| Category               | Meaning                                           | Expiry                         |
+| ---------------------- | ------------------------------------------------- | ------------------------------ |
+| `false-positive`       | Scanner is wrong about this finding               | Optional                       |
+| `test-fixture`         | Intentional pattern in fixture / test code        | Optional                       |
+| `mitigated-externally` | Real risk neutralized at runtime (WAF, env, etc.) | Optional                       |
+| `accepted-risk`        | Real risk, team accepts, signed off               | **Required** (default 90 days) |
+| `deferred`             | Real, will fix later, tracked work                | **Required**                   |
+
+Two surfaces. Inline annotation for source-anchored findings:
+
+```python
+api_key = "sk_test_xxxx"  # dxkit-allow:test-fixture reason="placeholder in unit test"
+```
+
+File-level (`.dxkit/allowlist.json`) for cross-file findings or any
+suppression that needs an expiry. New entries appear in the PR-
+comment automation so reviewers see suppressions being introduced
+and can sanity-check the rationale before approving. `audit` /
+`prune` subcommands handle stale + soon-to-expire entries.
+
+**Strict cleanup**: orphaned `dxkit-allow:` annotations become
+`stale-allow` findings on the next scan. dxkit refuses to allowlist
+those — the only remediation is to remove the annotation. This is
+the TypeScript `@ts-expect-error` pattern: tools that surface their
+own stale suppressions force cleanup, preventing the annotation
+graveyard.
+
+```bash
+# The block message from `guardrail check` prints the exact command
+# to paste for any blocked finding — file:line for inline-compatible
+# kinds, --fingerprint for everything else.
+vyuh-dxkit allowlist add src/auth/oauth.ts:42 \
+    --category=test-fixture --reason="placeholder in unit test"
+
+vyuh-dxkit allowlist audit              # find stale + soon-to-expire entries
+```
+
+See [`vyuh-dxkit allowlist`](docs/commands/allowlist.md) for the
+full surface.
+
 ---
 
 ## Git-aware identity matching
@@ -459,6 +539,28 @@ dxkit is local-first.
 
 ---
 
+## Reporting issues
+
+If a scanner is too noisy, a finding is missing, dxkit itself is
+broken, or the docs are unclear, the fastest path to the dxkit team
+is the built-in issue subcommand:
+
+```bash
+vyuh-dxkit issue --type=false-positive \
+    --fingerprint=<id> \
+    --about="the scanner flags my intentional X as a Y"
+
+vyuh-dxkit issue --type=bug --about="vyuh-dxkit doctor crashes on macOS arm64"
+
+vyuh-dxkit issue --type=feature-request --about="add SARIF export"
+```
+
+It opens a pre-filled [GitHub issue](https://github.com/vyuh-labs/dxkit/issues)
+in your browser with dxkit version + platform info already populated.
+Nothing is submitted until you click "Submit" — you review the
+prefill first. See [`vyuh-dxkit issue`](docs/commands/issue.md) for
+the full reference.
+
 ## Contributing
 
 dxkit aims to be the standard agentic-development layer for any

package/dist/allowlist/categories.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Allowlist category taxonomy. Single source of truth for:
+ *   - Which categories exist
+ *   - Which categories require an expiry date
+ *   - Which categories may be expressed via inline source annotation
+ *   - Which categories apply to each `IdentityKind`
+ *   - Which finding kinds support inline annotations at all
+ *
+ * Pure module — no I/O, no analyzer dependencies. Consumed by the
+ * allowlist file reader/writer, the inline-annotation parser, the
+ * CLI, the block-time hint formatter, and the new `allowlistHits`
+ * baseline producer.
+ *
+ * See tmp/2.6-allowlist-design.md for the design discussion.
+ */
+import type { IdentityKind } from '../baseline/producers';
+/**
+ * Single source of truth for category values. The `AllowlistCategory`
+ * union type is derived from this array via `(typeof ...)[number]`,
+ * so adding a new category means appending one string here and every
+ * type-level check (Record-keyed tables, switch exhaustiveness,
+ * function parameter types) auto-updates. No two-place drift.
+ */
+export declare const ALL_CATEGORIES: readonly ["false-positive", "test-fixture", "mitigated-externally", "accepted-risk", "deferred"];
+export type AllowlistCategory = (typeof ALL_CATEGORIES)[number];
+/**
+ * Categories that REQUIRE a finite expiry date. The file-level
+ * allowlist write-path rejects entries in these categories without
+ * an `expiresAt`. The CLI defaults `expiresAt` to 90 days out for
+ * these — see `defaultExpiryDate`.
+ *
+ * Categories OUTSIDE this set represent stable assertions about the
+ * code that don't naturally stale (a test fixture remains a test
+ * fixture; a false positive remains a false positive until the
+ * scanner rule changes). They may carry an `expiresAt` if the
+ * customer chooses, but it's not enforced.
+ */
+export declare const EXPIRING_CATEGORIES: ReadonlySet<AllowlistCategory>;
+/**
+ * Categories that may be expressed via inline source annotation
+ * (`// dxkit-allow:<category> reason="..."`). The complement
+ * (`accepted-risk`, `deferred`) is file-only because those categories
+ * need fields (expiresAt, acknowledgedSeverity) that don't fit
+ * cleanly into a code comment.
+ */
+export declare const INLINE_COMPATIBLE_CATEGORIES: ReadonlySet<AllowlistCategory>;
+/**
+ * Finding kinds that have a stable single-line attachment point and
+ * therefore support inline annotations. Kinds outside this set are
+ * file-only (whole-file findings, cross-file findings, gap findings).
+ *
+ * Inline-compatible:
+ *   - `secret` / `secret-hmac`: the source line is the credential
+ *   - `code` / `config`: the source line is the flagged pattern
+ *   - `dep-vuln`: annotate the import or first-use line
+ *   - `hygiene`: the source line carries the TODO/FIXME/HACK marker
+ *
+ * File-only (no single-line site):
+ *   - `duplication`: two locations across files
+ *   - `coverage-gap` / `test-gap` / `test-file-degradation`: file or
+ *     symbol-range level, not single-line
+ *   - `god-file` / `large-file` / `stale-file`: whole-file findings
+ */
+export declare const INLINE_COMPATIBLE_KINDS: ReadonlySet<IdentityKind>;
+/**
+ * Categories applicable to each `IdentityKind`. Reflects what
+ * suppression rationales the kind can plausibly carry — a
+ * `coverage-gap` is rarely a "false positive" in the same way a
+ * scanner finding is; a `dep-vuln` is rarely a "test fixture."
+ *
+ * The CLI presents the applicable list as a multiple-choice prompt
+ * when the customer runs `vyuh-dxkit allowlist add` against a
+ * finding.
+ *
+ * The `Record<IdentityKind, ...>` ties this table to the canonical
+ * union: TypeScript fails the build when a new `IdentityKind`
+ * variant lands without a corresponding entry here.
+ */
+export declare const CATEGORIES_BY_KIND: Readonly<Record<IdentityKind, readonly AllowlistCategory[]>>;
+/**
+ * Whether a (kind, category) tuple may be expressed as an inline
+ * annotation. Both the kind AND the category must be inline-compatible.
+ *
+ * Examples:
+ *   canUseInline('secret', 'test-fixture')      // true
+ *   canUseInline('secret', 'accepted-risk')     // false (category file-only)
+ *   canUseInline('large-file', 'false-positive') // false (kind file-only)
+ *   canUseInline('hygiene', 'accepted-risk')    // false (category file-only)
+ */
+export declare function canUseInline(kind: IdentityKind, category: AllowlistCategory): boolean;
+/**
+ * Whether a category requires `expiresAt` on the file-level entry.
+ * Source of truth for the write-path validation rule.
+ */
+export declare function requiresExpiry(category: AllowlistCategory): boolean;
+/**
+ * Whether a (kind, category) tuple is semantically valid. The CLI
+ * uses this to reject incoherent combinations like
+ * `coverage-gap + false-positive` with a clear error pointing at
+ * the applicable categories for that kind.
+ */
+export declare function isCategoryValidForKind(kind: IdentityKind, category: AllowlistCategory): boolean;
+/**
+ * Number of days into the future the CLI defaults `expiresAt` to
+ * when the customer doesn't specify one. Locked at 90 in Sprint 0
+ * (Snyk + Dependabot industry default). Per-category overrides will
+ * land in `.dxkit/policy.json` (`allowlist.defaultExpiryDays`) in a
+ * follow-up commit if real customer signal demands it.
+ */
+export declare const DEFAULT_EXPIRY_DAYS = 90;
+/**
+ * Compute the default expiry date as an ISO `YYYY-MM-DD` string,
+ * `DEFAULT_EXPIRY_DAYS` from `now`. UTC-anchored to keep the date
+ * stable across timezone-different developers on the same team.
+ *
+ * `now` is injected for deterministic testing — production callers
+ * pass `new Date()` (the default).
+ */
+export declare function defaultExpiryDate(now?: Date): string;
+//# sourceMappingURL=categories.d.ts.map

package/dist/allowlist/categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../src/allowlist/categories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,kGAMjB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,iBAAiB,CAG7D,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,iBAAiB,CAItE,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,YAAY,CAO5D,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC,CA6C3F,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAErF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAE/F;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAIhE"}

package/dist/allowlist/categories.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Allowlist category taxonomy. Single source of truth for:
+ *   - Which categories exist
+ *   - Which categories require an expiry date
+ *   - Which categories may be expressed via inline source annotation
+ *   - Which categories apply to each `IdentityKind`
+ *   - Which finding kinds support inline annotations at all
+ *
+ * Pure module — no I/O, no analyzer dependencies. Consumed by the
+ * allowlist file reader/writer, the inline-annotation parser, the
+ * CLI, the block-time hint formatter, and the new `allowlistHits`
+ * baseline producer.
+ *
+ * See tmp/2.6-allowlist-design.md for the design discussion.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EXPIRY_DAYS = exports.CATEGORIES_BY_KIND = exports.INLINE_COMPATIBLE_KINDS = exports.INLINE_COMPATIBLE_CATEGORIES = exports.EXPIRING_CATEGORIES = exports.ALL_CATEGORIES = void 0;
+exports.canUseInline = canUseInline;
+exports.requiresExpiry = requiresExpiry;
+exports.isCategoryValidForKind = isCategoryValidForKind;
+exports.defaultExpiryDate = defaultExpiryDate;
+/**
+ * Single source of truth for category values. The `AllowlistCategory`
+ * union type is derived from this array via `(typeof ...)[number]`,
+ * so adding a new category means appending one string here and every
+ * type-level check (Record-keyed tables, switch exhaustiveness,
+ * function parameter types) auto-updates. No two-place drift.
+ */
+exports.ALL_CATEGORIES = [
+    'false-positive',
+    'test-fixture',
+    'mitigated-externally',
+    'accepted-risk',
+    'deferred',
+];
+/**
+ * Categories that REQUIRE a finite expiry date. The file-level
+ * allowlist write-path rejects entries in these categories without
+ * an `expiresAt`. The CLI defaults `expiresAt` to 90 days out for
+ * these — see `defaultExpiryDate`.
+ *
+ * Categories OUTSIDE this set represent stable assertions about the
+ * code that don't naturally stale (a test fixture remains a test
+ * fixture; a false positive remains a false positive until the
+ * scanner rule changes). They may carry an `expiresAt` if the
+ * customer chooses, but it's not enforced.
+ */
+exports.EXPIRING_CATEGORIES = new Set([
+    'accepted-risk',
+    'deferred',
+]);
+/**
+ * Categories that may be expressed via inline source annotation
+ * (`// dxkit-allow:<category> reason="..."`). The complement
+ * (`accepted-risk`, `deferred`) is file-only because those categories
+ * need fields (expiresAt, acknowledgedSeverity) that don't fit
+ * cleanly into a code comment.
+ */
+exports.INLINE_COMPATIBLE_CATEGORIES = new Set([
+    'false-positive',
+    'test-fixture',
+    'mitigated-externally',
+]);
+/**
+ * Finding kinds that have a stable single-line attachment point and
+ * therefore support inline annotations. Kinds outside this set are
+ * file-only (whole-file findings, cross-file findings, gap findings).
+ *
+ * Inline-compatible:
+ *   - `secret` / `secret-hmac`: the source line is the credential
+ *   - `code` / `config`: the source line is the flagged pattern
+ *   - `dep-vuln`: annotate the import or first-use line
+ *   - `hygiene`: the source line carries the TODO/FIXME/HACK marker
+ *
+ * File-only (no single-line site):
+ *   - `duplication`: two locations across files
+ *   - `coverage-gap` / `test-gap` / `test-file-degradation`: file or
+ *     symbol-range level, not single-line
+ *   - `god-file` / `large-file` / `stale-file`: whole-file findings
+ */
+exports.INLINE_COMPATIBLE_KINDS = new Set([
+    'secret',
+    'secret-hmac',
+    'code',
+    'config',
+    'dep-vuln',
+    'hygiene',
+]);
+/**
+ * Categories applicable to each `IdentityKind`. Reflects what
+ * suppression rationales the kind can plausibly carry — a
+ * `coverage-gap` is rarely a "false positive" in the same way a
+ * scanner finding is; a `dep-vuln` is rarely a "test fixture."
+ *
+ * The CLI presents the applicable list as a multiple-choice prompt
+ * when the customer runs `vyuh-dxkit allowlist add` against a
+ * finding.
+ *
+ * The `Record<IdentityKind, ...>` ties this table to the canonical
+ * union: TypeScript fails the build when a new `IdentityKind`
+ * variant lands without a corresponding entry here.
+ */
+exports.CATEGORIES_BY_KIND = {
+    // Source-level security findings: every category applies
+    secret: ['false-positive', 'test-fixture', 'mitigated-externally', 'accepted-risk', 'deferred'],
+    'secret-hmac': [
+        'false-positive',
+        'test-fixture',
+        'mitigated-externally',
+        'accepted-risk',
+        'deferred',
+    ],
+    code: ['false-positive', 'test-fixture', 'mitigated-externally', 'accepted-risk', 'deferred'],
+    config: ['false-positive', 'test-fixture', 'mitigated-externally', 'accepted-risk', 'deferred'],
+    // Dependency vulnerabilities: rarely a test fixture (the dep is real);
+    // every other category applies
+    'dep-vuln': ['false-positive', 'mitigated-externally', 'accepted-risk', 'deferred'],
+    // Duplicate blocks: occasionally a false positive (jscpd matched
+    // generated code); otherwise accepted-risk or deferred
+    duplication: ['false-positive', 'accepted-risk', 'deferred'],
+    // Coverage / test gaps: not "false-positive" in any practical sense;
+    // only accepted-risk or deferred
+    'coverage-gap': ['accepted-risk', 'deferred'],
+    'test-gap': ['accepted-risk', 'deferred'],
+    'test-file-degradation': ['accepted-risk', 'deferred'],
+    // Whole-file findings: false-positive (file IS not actually large /
+    // stale / god when reviewed); otherwise accepted-risk or deferred
+    'god-file': ['false-positive', 'accepted-risk', 'deferred'],
+    'large-file': ['false-positive', 'accepted-risk', 'deferred'],
+    'stale-file': ['false-positive', 'accepted-risk', 'deferred'],
+    // TODO / FIXME / HACK / console-log / any-type markers: only
+    // accepted-risk or deferred (the marker IS the hygiene issue)
+    hygiene: ['accepted-risk', 'deferred'],
+    // Stale-allow (orphaned inline allowlist annotation): never
+    // allowlisted. The right response is always "remove the stale
+    // annotation" — allowlisting the warning that an annotation is
+    // stale would defeat the entire strict-stale-detection model
+    // (TypeScript's @ts-expect-error pattern). Empty array means the
+    // CLI rejects with a hint pointing at the annotation's source
+    // location.
+    'stale-allow': [],
+};
+/**
+ * Whether a (kind, category) tuple may be expressed as an inline
+ * annotation. Both the kind AND the category must be inline-compatible.
+ *
+ * Examples:
+ *   canUseInline('secret', 'test-fixture')      // true
+ *   canUseInline('secret', 'accepted-risk')     // false (category file-only)
+ *   canUseInline('large-file', 'false-positive') // false (kind file-only)
+ *   canUseInline('hygiene', 'accepted-risk')    // false (category file-only)
+ */
+function canUseInline(kind, category) {
+    return exports.INLINE_COMPATIBLE_KINDS.has(kind) && exports.INLINE_COMPATIBLE_CATEGORIES.has(category);
+}
+/**
+ * Whether a category requires `expiresAt` on the file-level entry.
+ * Source of truth for the write-path validation rule.
+ */
+function requiresExpiry(category) {
+    return exports.EXPIRING_CATEGORIES.has(category);
+}
+/**
+ * Whether a (kind, category) tuple is semantically valid. The CLI
+ * uses this to reject incoherent combinations like
+ * `coverage-gap + false-positive` with a clear error pointing at
+ * the applicable categories for that kind.
+ */
+function isCategoryValidForKind(kind, category) {
+    return exports.CATEGORIES_BY_KIND[kind].includes(category);
+}
+/**
+ * Number of days into the future the CLI defaults `expiresAt` to
+ * when the customer doesn't specify one. Locked at 90 in Sprint 0
+ * (Snyk + Dependabot industry default). Per-category overrides will
+ * land in `.dxkit/policy.json` (`allowlist.defaultExpiryDays`) in a
+ * follow-up commit if real customer signal demands it.
+ */
+exports.DEFAULT_EXPIRY_DAYS = 90;
+/**
+ * Compute the default expiry date as an ISO `YYYY-MM-DD` string,
+ * `DEFAULT_EXPIRY_DAYS` from `now`. UTC-anchored to keep the date
+ * stable across timezone-different developers on the same team.
+ *
+ * `now` is injected for deterministic testing — production callers
+ * pass `new Date()` (the default).
+ */
+function defaultExpiryDate(now = new Date()) {
+    const expires = new Date(now);
+    expires.setUTCDate(expires.getUTCDate() + exports.DEFAULT_EXPIRY_DAYS);
+    return expires.toISOString().slice(0, 10);
+}
+//# sourceMappingURL=categories.js.map

package/dist/allowlist/categories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.js","sourceRoot":"","sources":["../../src/allowlist/categories.ts"],"names":[],"mappings":"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"}