@vyuhlabs/dxkit 2.5.1 → 2.6.0

package/dist/allowlist/gather.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Inline allowlist annotation gather pass.
+ *
+ * Walks the source tree looking for `<lineComment> dxkit-allow:<category>`
+ * comments and records each occurrence as a `(file, line, category)`
+ * tuple. The `stale-allow` producer uses this list together with the
+ * current scan's secret/code/config findings to detect orphaned
+ * annotations — annotations whose underlying finding is no longer
+ * present, which the developer should remove.
+ *
+ * Architectural posture:
+ *
+ *   - File walk goes through the canonical `walkSourceFiles` helper
+ *     so `.gitignore` + `.dxkit-ignore` + bundled defaults are
+ *     honored uniformly. No custom recursion / exclusion logic
+ *     (per CLAUDE.md G_v4_7).
+ *   - Per-language comment marker comes from each pack's
+ *     `LanguageSupport.commentSyntax` via the inline annotation
+ *     parser. No hardcoded `'//'` / `'#'` literals in this module
+ *     (arch-check rule 2 enforces).
+ *   - Annotation parsing reuses `parseAnnotation` from `inline.ts`
+ *     — single source of grammar truth.
+ *
+ * Test files ARE walked (intentional — annotations often live in
+ * test fixtures suppressing scanner findings against deliberate
+ * placeholder credentials). Auto-generated files are NOT walked
+ * (the developer doesn't author annotations in generated code, and
+ * `walkSourceFiles` already excludes them by default).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatherInlineAllowlistAnnotations = gatherInlineAllowlistAnnotations;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const languages_1 = require("../languages");
+const walk_source_files_1 = require("../analyzers/tools/walk-source-files");
+const inline_1 = require("./inline");
+/**
+ * Walk source files under `cwd` and collect every inline allowlist
+ * annotation occurrence. Cheap on small repos; on large ones the
+ * `walkSourceFiles` cache amortizes the cost across multiple gather
+ * passes within a single baseline-create run.
+ *
+ * Returns occurrences in stable order (file path lexicographic, then
+ * line ascending) so downstream deterministic-output requirements
+ * are satisfied automatically.
+ */
+function gatherInlineAllowlistAnnotations(cwd, opts = {}) {
+    const includeTests = opts.includeTests ?? true;
+    const files = (0, walk_source_files_1.walkSourceFiles)(cwd, { includeTests });
+    const out = [];
+    // Build an extension → language lookup once per call. Cheap; the
+    // LANGUAGES registry is small (8 packs today).
+    const langByExt = buildLanguageByExtension();
+    for (const relPath of files) {
+        const ext = path.extname(relPath).toLowerCase();
+        const lang = langByExt.get(ext);
+        if (!lang || !lang.commentSyntax)
+            continue;
+        const abs = path.join(cwd, relPath);
+        let raw;
+        try {
+            raw = fs.readFileSync(abs, 'utf8');
+        }
+        catch {
+            // File disappeared mid-walk (race) or unreadable — skip.
+            continue;
+        }
+        // Fast path: source has no `dxkit-allow:` substring at all.
+        // Avoids per-line regex on the vast majority of files.
+        if (!raw.includes('dxkit-allow:'))
+            continue;
+        const lines = raw.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const parsed = (0, inline_1.parseAnnotation)(line, lang);
+            if (!parsed)
+                continue;
+            // `parseAnnotation` returns the category + reason but not
+            // the position. Determine position by inspecting whether the
+            // line is standalone (only whitespace + comment marker + body)
+            // or has source code preceding the comment.
+            const position = (0, inline_1.isStandaloneAnnotationLine)(line, lang)
+                ? 'above'
+                : 'same-line';
+            out.push({
+                file: relPath,
+                line: i + 1,
+                category: parsed.category,
+                position,
+            });
+        }
+    }
+    return out;
+}
+// ─── Internals ────────────────────────────────────────────────────────────
+function buildLanguageByExtension() {
+    const map = new Map();
+    for (const lang of languages_1.LANGUAGES) {
+        for (const ext of lang.sourceExtensions) {
+            const lower = ext.toLowerCase();
+            // First pack wins on duplicate extensions (none today, but
+            // the deterministic-order guarantee survives a future overlap).
+            if (!map.has(lower))
+                map.set(lower, lang);
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=gather.js.map

package/dist/allowlist/gather.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gather.js","sourceRoot":"","sources":["../../src/allowlist/gather.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCH,4EAkDC;AAxFD,uCAAyB;AACzB,2CAA6B;AAC7B,4CAAyC;AAEzC,4EAAuE;AACvE,qCAAgG;AAuBhG;;;;;;;;;GASG;AACH,SAAgB,gCAAgC,CAC9C,GAAW,EACX,OAAyB,EAAE;IAE3B,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAA,mCAAe,EAAC,GAAG,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IACrD,MAAM,GAAG,GAAgC,EAAE,CAAC;IAE5C,iEAAiE;IACjE,+CAA+C;IAC/C,MAAM,SAAS,GAAG,wBAAwB,EAAE,CAAC;IAE7C,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa;YAAE,SAAS;QAE3C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,yDAAyD;YACzD,SAAS;QACX,CAAC;QACD,4DAA4D;QAC5D,uDAAuD;QACvD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC;YAAE,SAAS;QAE5C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,MAAM,MAAM,GAAG,IAAA,wBAAe,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3C,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,0DAA0D;YAC1D,6DAA6D;YAC7D,+DAA+D;YAC/D,4CAA4C;YAC5C,MAAM,QAAQ,GAAuB,IAAA,mCAA0B,EAAC,IAAI,EAAE,IAAI,CAAC;gBACzE,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,WAAW,CAAC;YAChB,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,CAAC,GAAG,CAAC;gBACX,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ;aACT,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,6EAA6E;AAE7E,SAAS,wBAAwB;IAC/B,MAAM,GAAG,GAAG,IAAI,GAAG,EAA2B,CAAC;IAC/C,KAAK,MAAM,IAAI,IAAI,qBAAS,EAAE,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;YAChC,2DAA2D;YAC3D,gEAAgE;YAChE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/allowlist/hint.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Block-time hint generation.
+ *
+ * When the guardrail check rejects a finding, the developer needs
+ * three things to act on it:
+ *
+ *   1. **Remediation** — the recommended fix (rotate the secret,
+ *      upgrade the package, split the file, etc.). Generic per-kind
+ *      prose; the conversational `dxkit-fix` skill produces
+ *      LLM-backed, code-aware fixes when available.
+ *   2. **Inline example** — the exact annotation comment to paste
+ *      when the finding has a stable single-line attachment point
+ *      and the chosen category is inline-compatible.
+ *   3. **CLI command** — the exact `npx vyuh-dxkit allowlist add`
+ *      invocation that handles the mutation without the developer
+ *      typing annotation syntax.
+ *
+ * # Canonical input shape (CLAUDE.md Rule 9)
+ *
+ * This module consumes `BaselineEntry` directly — the canonical
+ * per-kind discriminated union from `src/baseline/types.ts`. NO
+ * intermediate "BlockingFinding" projection. The discriminated
+ * union flows into the switch statements below so TypeScript's
+ * exhaustiveness check fails the build when a new `IdentityKind`
+ * variant is added without matching `case` branches here.
+ *
+ * Language is inferred from the entry's file path (when present)
+ * via the canonical `LANGUAGES` registry. No language-specific
+ * branches; pack additions auto-propagate.
+ *
+ * The returned `BlockHint` is a plain data object so callers can
+ * render it as terminal output, emit it as JSON for the skill /
+ * future MCP surface, etc. Rendering text lives at the call site,
+ * NOT here.
+ */
+import type { BaselineEntry, FindingSeverity } from '../baseline/types';
+import { type AllowlistCategory } from './categories';
+export interface BlockHint {
+    /** Generic per-kind remediation text. Always present. */
+    readonly remediation: string;
+    /** Categories that semantically apply to this kind. Empty for
+     *  `license` (which drops out of the baseline producer registry
+     *  in 2.6+). */
+    readonly applicableCategories: readonly AllowlistCategory[];
+    /** Inline annotation example. Populated only when the entry has
+     *  a stable single-line attachment, the kind's first applicable
+     *  category is inline-compatible, and the language is inferable
+     *  from the file extension. */
+    readonly inlineExample?: string;
+    /** Shell command for the CLI write path. Always present. */
+    readonly cliCommand: string;
+    /** True when the kind has no inline-compatible category
+     *  applicable (e.g. hygiene — only accepted-risk + deferred,
+     *  both file-only). The CLI / skill routes the dev directly to
+     *  the file-level surface when true. */
+    readonly fileLevelOnly: boolean;
+    /** Pointer to the file-level allowlist surface when an expiring
+     *  category (accepted-risk / deferred) might apply. */
+    readonly fileLevelHint?: string;
+}
+/**
+ * Build the structured block-time hint from a baseline entry.
+ * Pure function — no IO, no side effects. The caller renders the
+ * fields into its medium of choice.
+ *
+ * The optional `severity` parameter is reserved for future
+ * remediation-prose tuning (e.g. "rotate IMMEDIATELY" for
+ * critical-severity secrets). Currently unused but threaded
+ * through so callers don't need to refactor when the prose
+ * starts varying on severity.
+ */
+export declare function formatBlockHint(entry: BaselineEntry, severity?: FindingSeverity): BlockHint;
+/**
+ * Generic per-kind remediation text. Exhaustive switch on the
+ * canonical `BaselineEntry['kind']` union — TypeScript enforces
+ * every variant has prose so a new kind can't ship without
+ * matching `case` branches.
+ */
+export declare function remediationFor(kind: BaselineEntry['kind']): string;
+//# sourceMappingURL=hint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hint.d.ts","sourceRoot":"","sources":["../../src/allowlist/hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGxE,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAStB,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;oBAEgB;IAChB,QAAQ,CAAC,oBAAoB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC5D;;;mCAG+B;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;4CAGwC;IACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;2DACuD;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,CAyB3F;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAsFlE"}

package/dist/allowlist/hint.js

@@ -0,0 +1,271 @@
+"use strict";
+/**
+ * Block-time hint generation.
+ *
+ * When the guardrail check rejects a finding, the developer needs
+ * three things to act on it:
+ *
+ *   1. **Remediation** — the recommended fix (rotate the secret,
+ *      upgrade the package, split the file, etc.). Generic per-kind
+ *      prose; the conversational `dxkit-fix` skill produces
+ *      LLM-backed, code-aware fixes when available.
+ *   2. **Inline example** — the exact annotation comment to paste
+ *      when the finding has a stable single-line attachment point
+ *      and the chosen category is inline-compatible.
+ *   3. **CLI command** — the exact `npx vyuh-dxkit allowlist add`
+ *      invocation that handles the mutation without the developer
+ *      typing annotation syntax.
+ *
+ * # Canonical input shape (CLAUDE.md Rule 9)
+ *
+ * This module consumes `BaselineEntry` directly — the canonical
+ * per-kind discriminated union from `src/baseline/types.ts`. NO
+ * intermediate "BlockingFinding" projection. The discriminated
+ * union flows into the switch statements below so TypeScript's
+ * exhaustiveness check fails the build when a new `IdentityKind`
+ * variant is added without matching `case` branches here.
+ *
+ * Language is inferred from the entry's file path (when present)
+ * via the canonical `LANGUAGES` registry. No language-specific
+ * branches; pack additions auto-propagate.
+ *
+ * The returned `BlockHint` is a plain data object so callers can
+ * render it as terminal output, emit it as JSON for the skill /
+ * future MCP surface, etc. Rendering text lives at the call site,
+ * NOT here.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatBlockHint = formatBlockHint;
+exports.remediationFor = remediationFor;
+const path = __importStar(require("path"));
+const sanitize_1 = require("../baseline/sanitize");
+const languages_1 = require("../languages");
+const categories_1 = require("./categories");
+const inline_1 = require("./inline");
+/**
+ * Subcommand string used in every `cliCommand` rendered by this
+ * module. One place to update if the subcommand ever renames.
+ */
+const ALLOWLIST_ADD_CMD = 'npx vyuh-dxkit allowlist add';
+/**
+ * Build the structured block-time hint from a baseline entry.
+ * Pure function — no IO, no side effects. The caller renders the
+ * fields into its medium of choice.
+ *
+ * The optional `severity` parameter is reserved for future
+ * remediation-prose tuning (e.g. "rotate IMMEDIATELY" for
+ * critical-severity secrets). Currently unused but threaded
+ * through so callers don't need to refactor when the prose
+ * starts varying on severity.
+ */
+function formatBlockHint(entry, severity) {
+    const applicableCategories = categories_1.CATEGORIES_BY_KIND[entry.kind];
+    const inlineCompatibleApplicable = applicableCategories.filter((c) => categories_1.INLINE_COMPATIBLE_CATEGORIES.has(c));
+    const fileLevelOnly = !categories_1.INLINE_COMPATIBLE_KINDS.has(entry.kind) || inlineCompatibleApplicable.length === 0;
+    const firstInlineCategory = inlineCompatibleApplicable[0];
+    const inlineExample = buildInlineExample(entry, firstInlineCategory);
+    const cliCommand = buildCliCommand(entry, applicableCategories);
+    const fileLevelHint = buildFileLevelHint(applicableCategories);
+    // Severity threaded for future use; not consumed yet — declare it
+    // touched so an unused-parameter rule doesn't complain.
+    void severity;
+    return {
+        remediation: remediationFor(entry.kind),
+        applicableCategories,
+        inlineExample,
+        cliCommand,
+        fileLevelOnly,
+        fileLevelHint,
+    };
+}
+/**
+ * Generic per-kind remediation text. Exhaustive switch on the
+ * canonical `BaselineEntry['kind']` union — TypeScript enforces
+ * every variant has prose so a new kind can't ship without
+ * matching `case` branches.
+ */
+function remediationFor(kind) {
+    switch (kind) {
+        case 'secret':
+        case 'secret-hmac':
+            return ('Rotate this credential immediately and load it from an environment variable ' +
+                'or secret manager instead of source. Do not commit the replacement to git ' +
+                'history — clean previous commits with git-filter-repo if necessary.');
+        case 'code':
+            return ('Review the flagged code pattern. If the scanner is wrong (false positive), ' +
+                'suppress via the allowlist with category=false-positive. Otherwise fix the ' +
+                'underlying issue — the scanner caught it for a reason.');
+        case 'config':
+            return ('Review the configuration setting. Many config-level findings ' +
+                '(TLS validation disabled, debug mode in production, etc.) reflect ' +
+                'operational risk; fix at the deployment / infrastructure layer where ' +
+                'possible rather than in source.');
+        case 'dep-vuln':
+            return ('Upgrade the vulnerable dependency to the patched version. Run ' +
+                '`npx vyuh-dxkit vulnerabilities` to see the suggested install command ' +
+                'for this ecosystem.');
+        case 'duplication':
+            return ('Extract the duplicated logic into a shared helper or accept the ' +
+                'duplication via the allowlist when it is intentional ' +
+                '(e.g., parallel test fixtures, generated code that must stay literal).');
+        case 'coverage-gap':
+            return ('Add a test covering the uncovered region. If the code path is ' +
+                'intentionally untested (build-time only, defensive error paths that ' +
+                'cannot be reached from tests), accept the gap via the allowlist.');
+        case 'test-gap':
+            return ('Create a test file for this source file. The convention follows the ' +
+                "language's standard (e.g., `*_test.go` for go, `*.test.ts` for " +
+                'typescript, `test_*.py` for python).');
+        case 'test-file-degradation':
+            return ('Restore the test body. Empty or fully commented-out test functions pass ' +
+                'silently in the test runner but provide no real coverage signal — they ' +
+                'are worse than no test because they hide gaps from view.');
+        case 'hygiene':
+            return ('Resolve the hygiene marker (TODO, FIXME, HACK, debug-print, or loose ' +
+                '`any` type). Complete the work it points at, file it as a tracked issue ' +
+                'in your task management system, or remove the marker if the underlying ' +
+                'concern is already addressed.');
+        case 'god-file':
+            return ('Split this file. It has grown beyond the maintainability threshold for ' +
+                'this codebase — large files concentrate change risk and make focused ' +
+                'review difficult. Extract cohesive subsets (related functions, related ' +
+                'types) into separate modules.');
+        case 'large-file':
+            return ('Split this file into smaller modules. Long files concentrate ' +
+                'cognitive load and make change risk harder to assess; smaller ' +
+                'modules with clear boundaries are easier to maintain.');
+        case 'stale-file':
+            return ('Remove the stale on-disk artifact (typically `.swp`, `.bak`, `.orig`, ' +
+                'or editor backup files). These should not be tracked in git — add the ' +
+                'pattern to `.gitignore` and untrack the file.');
+        case 'stale-allow':
+            return ('Remove the orphaned `dxkit-allow:` annotation — the finding it ' +
+                'suppressed is no longer present, so the annotation is dead code. ' +
+                'Allowlisting THIS finding is not supported; the only remediation is ' +
+                'to delete the annotation comment.');
+    }
+}
+// ─── Internals ───────────────────────────────────────────────────────────
+/**
+ * Project a `BaselineEntry` to the file + line locator the hint
+ * formatter needs. Exhaustive switch on entry.kind — TypeScript
+ * enforces every variant is handled. Adding a new kind requires
+ * extending this projection.
+ *
+ * Kinds without a stable file:line locator (`dep-vuln`, `duplication`,
+ * `secret-hmac`) return `{}` and route to the `--fingerprint=<id>`
+ * CLI form. Sanitized entries also return `{}` — the location was
+ * stripped at write time and can only be addressed by fingerprint.
+ */
+function entryLocator(entry) {
+    if ((0, sanitize_1.isSanitized)(entry))
+        return {};
+    switch (entry.kind) {
+        case 'secret':
+        case 'code':
+        case 'config':
+        case 'hygiene':
+        case 'stale-allow':
+            return { file: entry.file, line: entry.line };
+        case 'coverage-gap':
+        case 'test-gap':
+        case 'test-file-degradation':
+        case 'god-file':
+        case 'large-file':
+        case 'stale-file':
+            return { file: entry.file };
+        case 'secret-hmac':
+        case 'dep-vuln':
+        case 'duplication':
+            return {};
+    }
+}
+/**
+ * Look up the language pack matching a file's extension. Reads
+ * from the canonical `LANGUAGES` registry — no per-language
+ * branching here. A new language pack auto-propagates.
+ */
+function inferLanguage(file) {
+    const ext = path.extname(file).toLowerCase();
+    if (!ext)
+        return undefined;
+    for (const lang of languages_1.LANGUAGES) {
+        if (lang.sourceExtensions.includes(ext))
+            return lang;
+    }
+    return undefined;
+}
+function buildInlineExample(entry, firstInlineCategory) {
+    if (!firstInlineCategory)
+        return undefined;
+    if (!categories_1.INLINE_COMPATIBLE_KINDS.has(entry.kind))
+        return undefined;
+    const loc = entryLocator(entry);
+    if (!loc.file || loc.line === undefined)
+        return undefined;
+    const lang = inferLanguage(loc.file);
+    if (!lang || !lang.commentSyntax)
+        return undefined;
+    return (0, inline_1.renderAnnotation)({ category: firstInlineCategory, reason: '<your reason here>' }, lang);
+}
+function buildCliCommand(entry, applicableCategories) {
+    const firstCategory = applicableCategories[0];
+    const reasonArg = `--reason="<rationale here>"`;
+    const categoryArg = firstCategory ? `--category=${firstCategory}` : '--category=<category>';
+    const loc = entryLocator(entry);
+    // Two CLI forms, matching the two paths the `allowlist add` command
+    // accepts. Both are directly executable — no inferred missing args.
+    //
+    //   1. `<file>:<line>` — inline annotation insertion (kind-agnostic,
+    //      grammar-driven). Only chosen when the kind supports inline
+    //      attachment AND the entry carries file + line.
+    //   2. `--fingerprint=<id> --kind=<kind>` — file-level allowlist
+    //      entry. The fingerprint is the identity; the kind is needed
+    //      so the validator can apply per-kind rules.
+    if (categories_1.INLINE_COMPATIBLE_KINDS.has(entry.kind) && loc.file && loc.line !== undefined) {
+        return `${ALLOWLIST_ADD_CMD} ${loc.file}:${loc.line} ${categoryArg} ${reasonArg}`;
+    }
+    return `${ALLOWLIST_ADD_CMD} --fingerprint=${entry.id} --kind=${entry.kind} ${categoryArg} ${reasonArg}`;
+}
+function buildFileLevelHint(applicableCategories) {
+    const hasExpiringCategory = applicableCategories.some((c) => categories_1.EXPIRING_CATEGORIES.has(c));
+    if (!hasExpiringCategory)
+        return undefined;
+    return ('For accepted-risk or deferred suppression (both require an expiry date), ' +
+        'use --category=accepted-risk or --category=deferred with --expires=YYYY-MM-DD, ' +
+        'or edit .dxkit/allowlist.json directly.');
+}
+//# sourceMappingURL=hint.js.map

package/dist/allowlist/hint.js.map

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

package/dist/allowlist/inline.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Inline allowlist annotations.
+ *
+ * Grammar:
+ *
+ *   <lineComment> dxkit-allow:<category> reason="<text>"
+ *
+ * Examples:
+ *
+ *   # dxkit-allow:test-fixture reason="placeholder in unit test"
+ *   // dxkit-allow:false-positive reason="regex matches our intentional placeholder"
+ *
+ * Two positions:
+ *
+ *   - **Same-line** — annotation appears on the same source line as
+ *     the finding, separated by at least one space:
+ *
+ *       api_key = "sk_test_xxxx"  # dxkit-allow:test-fixture reason="..."
+ *
+ *   - **Above-line** — annotation occupies its own line, immediately
+ *     preceding the finding (matching its indentation):
+ *
+ *       # dxkit-allow:test-fixture reason="..."
+ *       api_key = "sk_test_xxxx"
+ *
+ * The position is chosen at insert time by `insertAnnotation`: short
+ * source lines (under the configurable threshold) get same-line
+ * annotation; longer lines get above-line so the result stays
+ * readable.
+ *
+ * The grammar applies uniformly across every language; only the
+ * `<lineComment>` token varies (`#` for python/ruby, `//` for
+ * typescript/go/rust/csharp/kotlin/java). Each language pack
+ * declares its token via `LanguageSupport.commentSyntax`.
+ *
+ * # Quoting + escaping
+ *
+ * The reason is a JSON-style string. To embed a literal `"`, escape
+ * as `\"`; to embed a literal `\`, escape as `\\`. The parser
+ * un-escapes both on read; the writer escapes both on insert. No
+ * other escape sequences are supported (no `\n`, `\t`, etc.) — keep
+ * the reason single-line for human review.
+ */
+import type { LanguageSupport } from '../languages/types';
+import { type AllowlistCategory } from './categories';
+export type AnnotationPosition = 'same-line' | 'above';
+export interface InlineAnnotation {
+    readonly category: AllowlistCategory;
+    /** Free-form rationale. `undefined` when the annotation is
+     *  syntactically valid but the `reason="..."` clause was omitted —
+     *  callers typically treat this as a "malformed annotation"
+     *  warning. */
+    readonly reason?: string;
+}
+export interface AnnotationMatch {
+    readonly annotation: InlineAnnotation;
+    readonly position: AnnotationPosition;
+    /** 1-indexed line where the annotation comment LIVES (not the
+     *  finding's line — though they're the same for `same-line`). */
+    readonly annotationLine: number;
+}
+export interface InsertOptions {
+    /**
+     * Maximum source-line length that still gets a same-line annotation.
+     * Longer lines get above-line annotation to keep the result
+     * readable. The annotation itself is typically 50-80 characters,
+     * so totaling source + annotation around 120-140 characters at
+     * this threshold.
+     */
+    readonly sameLineThreshold?: number;
+}
+/**
+ * Render a complete annotation comment for a given language.
+ * Exposed so callers (the CLI, the block-time hint formatter) can
+ * surface the exact string a developer would paste, without going
+ * through the file-mutation path.
+ */
+export declare function renderAnnotation(annotation: InlineAnnotation, lang: LanguageSupport): string;
+/**
+ * Parse a single line for an allowlist annotation. Returns `null`
+ * when no annotation marker is found OR when the category isn't
+ * one of the canonical values.
+ *
+ * Tolerates the `reason="..."` clause being absent — callers decide
+ * whether a missing reason invalidates the suppression.
+ *
+ * False-positive surface: a string literal containing the literal
+ * substring `<lineComment> dxkit-allow:<category>` would match.
+ * Discriminating "is this inside a string" requires real language
+ * parsing and isn't worth the complexity — the worst case is a
+ * legitimate finding gets suppressed when a developer wrote the
+ * grammar literally inside a string. Vanishingly rare in practice.
+ */
+export declare function parseAnnotation(line: string, lang: LanguageSupport): InlineAnnotation | null;
+/**
+ * Look for an annotation matching a finding at `filePath:lineNumber`
+ * (1-indexed). Checks two positions:
+ *
+ *   1. Same-line: the finding's line itself carries the annotation.
+ *   2. Above-line: the immediately-preceding line is a standalone
+ *      annotation comment.
+ *
+ * Returns `null` when neither position has a parseable annotation.
+ * Throws when the file doesn't exist or `lineNumber` is out of
+ * range — callers are typically operating on findings whose line
+ * numbers came from a fresh scan, so an out-of-range value
+ * indicates a bug worth surfacing.
+ */
+export declare function findAnnotationAt(filePath: string, lineNumber: number, lang: LanguageSupport): AnnotationMatch | null;
+/**
+ * Insert an allowlist annotation at `filePath:lineNumber`. Chooses
+ * same-line vs above-line based on the target line's length:
+ *
+ *   - Target shorter than `sameLineThreshold` → append to target.
+ *   - Target longer than threshold → prepend a new comment line
+ *     above target, copying its indentation.
+ *
+ * Returns the chosen position + the 1-indexed line where the
+ * annotation comment ended up (useful for the CLI to print "added
+ * at file:line").
+ *
+ * Refuses to insert when the category is not inline-compatible —
+ * the caller should route accepted-risk + deferred suppressions
+ * through the file-level allowlist instead.
+ *
+ * Preserves CRLF vs LF line endings: the file is read, split, and
+ * re-joined using the detected style. Files without a trailing
+ * newline keep that property.
+ */
+export declare function insertAnnotation(filePath: string, lineNumber: number, annotation: InlineAnnotation, lang: LanguageSupport, options?: InsertOptions): {
+    position: AnnotationPosition;
+    annotationLine: number;
+};
+/**
+ * Whether a line is a "standalone annotation comment" — meaning it
+ * contains nothing but leading whitespace + the comment marker +
+ * the annotation body. Used to distinguish an above-line annotation
+ * from a same-line annotation on a different finding's line.
+ *
+ * Exported because the gather pass (`src/allowlist/gather.ts`) needs
+ * the same predicate to label per-occurrence `position`. Single
+ * source of truth for the "what counts as standalone" rule.
+ *
+ * Example (python):
+ *   `    # dxkit-allow:test-fixture reason="..."`   ← standalone
+ *   `x = 1  # dxkit-allow:test-fixture reason="..."`  ← NOT standalone
+ */
+export declare function isStandaloneAnnotationLine(line: string, lang: LanguageSupport): boolean;
+//# sourceMappingURL=inline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../../src/allowlist/inline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAgD,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AASpG,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;mBAGe;IACf,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC;qEACiE;IACjE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAiBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAQ5F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAwB5F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,GACpB,eAAe,GAAG,IAAI,CA6BxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,GAAE,aAAkB,GAC1B;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAoD1D;AAQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAOvF"}