v11y-check 0.15.6 → 0.15.8

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
-/** @noformat — @generated. Do not edit. Compiled by rdy. */
+/** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.30.0";
+export const __readyupVersion = "0.35.0";
 
 
 // .readyup/kits/default.ts
@@ -63,7 +63,7 @@ var default_default = defineRdyKit({
   ]
 });
 function getMinVersion() {
-  const picked = { "version": "0.15.6" };
+  const picked = { "version": "0.15.8" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("v11y-check/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -5,7 +5,7 @@
       "checklists": [
         "v11y-check"
       ],
-      "esbuildVersion": "0.28.1",
+      "esbuildVersion": "0.28.2",
       "inputs": [
         {
           "hash": "52754bbb",
@@ -13,7 +13,7 @@
           "path": "kits/default.ts"
         },
         {
-          "hash": "cc25ad0c",
+          "hash": "2c9cf983",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -23,10 +23,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.30.0",
+      "readyupVersion": "0.35.0",
       "source": "kits/default.ts",
       "sourceHash": "52754bbb",
-      "targetHash": "f2af26e5"
+      "targetHash": "6d9f65b0"
     }
   ]
 }

package/dist/esm/bin/route.d.ts

@@ -1 +1,6 @@
+/**
+ * Route CLI arguments to the appropriate subcommand.
+ *
+ * Returns a numeric exit code: 0 for success, 1 for errors.
+ */
 export declare function routeCommand(args: string[]): Promise<number>;

package/dist/esm/cli.d.ts

@@ -1,4 +1,23 @@
-import type { CommandOptions } from './types.js';
+import { type CommandOptions } from './types.js';
+/**
+ * Run the default audit command (CI mode).
+ *
+ * Generates config, invokes audit-ci for each scope, and returns a combined exit code.
+ */
 export declare function auditCommand(options: CommandOptions): Promise<number>;
+/**
+ * Run the default grouped-check command.
+ *
+ * Audits each scope without allowlist filtering, cross-references results with
+ * the config allowlist, detects stale entries, and produces grouped output.
+ * Returns 1 when unallowed vulnerabilities exist.
+ */
 export declare function checkCommand(options: CommandOptions): Promise<number>;
+/**
+ * Run the `sync` subcommand.
+ *
+ * Audits each scope in report mode without allowlist filtering, then updates
+ * the allowlist to match current findings. When no config file exists, creates
+ * one at the default path.
+ */
 export declare function syncCommand(options: CommandOptions): Promise<number>;

package/dist/esm/cli.js

@@ -2,14 +2,14 @@ import process from 'node:process';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { loadConfig } from "./config.js";
-import { formatCheckJson, formatCheckText } from "./format-check.js";
+import { formatCheckJson, formatCheckText, } from "./format-check.js";
 import { formatCheckVerboseText } from "./format-verbose.js";
 import { generateAuditCiConfig } from "./generate.js";
 import { scaffoldConfig } from "./init/scaffold.js";
 import { parseAuditCiOutput, runAudit, runReport } from "./run-audit.js";
 import { syncAllowlist } from "./sync.js";
 import { withTempDir } from "./tmp.js";
-import { AUDIT_SCOPES, isSeverityAtOrAbove } from "./types.js";
+import { AUDIT_SCOPES, isSeverityAtOrAbove, } from "./types.js";
 export async function auditCommand(options) {
     let loaded;
     try {

package/dist/esm/config.d.ts

@@ -1,10 +1,19 @@
-import type { V11yCheckConfig } from './types.js';
+import { type V11yCheckConfig } from './types.js';
+/** Default config file path, relative to the working directory. */
 export declare const DEFAULT_CONFIG_PATH = ".config/v11y-check.config.json";
+/** Discriminate between a config loaded from a file and one built from defaults. */
 export type ConfigSource = 'defaults' | 'file';
+/** Result of loading config, including the source discriminator. */
 export interface LoadConfigResult {
     config: V11yCheckConfig;
     configDir: string;
     configFilePath: string;
     configSource: ConfigSource;
 }
+/**
+ * Load and validate the v11y-check config from disk, falling back to defaults.
+ *
+ * When `configPath` is explicitly provided, the file must exist. When omitted,
+ * the default path is tried; if absent, `DEFAULT_CONFIG` is returned.
+ */
 export declare function loadConfig(configPath?: string, cwd?: string): Promise<LoadConfigResult>;

package/dist/esm/format-actions.d.ts

@@ -1,3 +1,9 @@
 import type { CheckResult } from './format-check.js';
 import type { AuditScope } from './types.js';
+/**
+ * Compute the "Actions:" footer for check output.
+ *
+ * Returns an empty string when the allowlist is fully current. Otherwise returns
+ * a bulleted action list with a verbose hint (when vulns exist) and a sync hint.
+ */
 export declare function formatActionHints(result: CheckResult, scopes: AuditScope[]): string;

package/dist/esm/format-check.d.ts

@@ -1,4 +1,5 @@
 import type { AuditResult, AuditScope, SeverityThreshold } from './types.js';
+/** Classification of an allowlist entry relative to current audit findings. */
 export interface AllowedVuln {
     addedAt?: string | undefined;
     cvss?: {
@@ -15,24 +16,37 @@ export interface AllowedVuln {
     title?: string | undefined;
     url: string;
 }
+/** An allowlist entry whose ID no longer appears in audit results. */
 export interface StaleEntry {
     id: string;
 }
+/** Check results for a single scope. */
 export interface ScopeCheckResult {
     allowed: AllowedVuln[];
     belowThreshold: AuditResult[];
     stale: StaleEntry[];
     unallowed: AuditResult[];
 }
+/** Aggregated check results across scopes. */
 export interface CheckResult {
     dev: ScopeCheckResult;
     prod: ScopeCheckResult;
 }
+/** Map a severity string to a colored circle emoji. */
 export declare function severityIndicator(severity: string | undefined): string;
+/** Resolve the best display ID for a vulnerability: GHSA ID if available, otherwise the numeric ID. */
 export declare function displayId(vuln: {
     ghsaId?: string | undefined;
     id: string;
 }): string;
+/** Build the severity suffix for a finding line, e.g. `  🔴 critical`. */
 export declare function formatSeveritySuffix(severity: string | undefined): string;
+/**
+ * Format check results as human-readable text output.
+ *
+ * Produces an intro banner, scoped findings with severity labels and GHSA IDs,
+ * and an action hints footer.
+ */
 export declare function formatCheckText(result: CheckResult, scopes: AuditScope[], now?: Date, thresholds?: Partial<Record<AuditScope, SeverityThreshold>>): string;
+/** Format check results as a JSON string with a top-level `summary` block derived from the result. */
 export declare function formatCheckJson(result: CheckResult, scopes: AuditScope[]): string;

package/dist/esm/format-summary.d.ts

@@ -1,8 +1,17 @@
 import type { CheckResult } from './format-check.js';
 import type { AuditScope } from './types.js';
+/** Status discriminant exposing the most severe finding category in a check result. */
 export type CheckSummaryStatus = 'vulnerabilities-found' | 'suppressed-vulnerabilities' | 'stale-overrides' | 'none';
+/** Headline summary of a check run: status discriminant plus count for the active category. */
 export interface CheckSummary {
     status: CheckSummaryStatus;
     count: number;
 }
+/**
+ * Derive the headline summary from a check result.
+ *
+ * Priority is severity-driven: unallowed > allowed > stale > none. The count is the total across
+ * the requested scopes for the *active* category only; for `'none'` it is `0`. Below-threshold
+ * findings never affect the summary — the threshold already excludes them from pass/fail.
+ */
 export declare function deriveSummary(result: CheckResult, scopes: AuditScope[]): CheckSummary;

package/dist/esm/format-time.d.ts

@@ -1 +1,10 @@
+/**
+ * Produce a human-readable relative-time string such as "just now", "N minutes ago",
+ * "yesterday", "N months ago", "N years ago".
+ *
+ * Uses millisecond math for units up through weeks to avoid DST/timezone drift on
+ * short intervals, and UTC calendar math for months and years.
+ *
+ * @internal — exported for test access; consumers should use higher-level formatting helpers.
+ */
 export declare function formatRelativeTime(fromIso: string, now: Date): string;

package/dist/esm/format-verbose.d.ts

@@ -1,3 +1,4 @@
-import type { CheckResult } from './format-check.js';
+import { type CheckResult } from './format-check.js';
 import type { AuditScope, SeverityThreshold } from './types.js';
+/** Format the verbose per-vulnerability check output as text. */
 export declare function formatCheckVerboseText(result: CheckResult, scopes: AuditScope[], now?: Date, thresholds?: Partial<Record<AuditScope, SeverityThreshold>>): string;

package/dist/esm/format-verbose.js

@@ -1,5 +1,5 @@
 import { formatActionHints } from "./format-actions.js";
-import { displayId, formatSeveritySuffix, severityIndicator } from "./format-check.js";
+import { displayId, formatSeveritySuffix, severityIndicator, } from "./format-check.js";
 import { formatRelativeTime } from "./format-time.js";
 const STATUS_UNALLOWED = '\u{1F6A8}';
 const STATUS_ALLOWED = '\u{26A0}\u{FE0F}';

package/dist/esm/generate.d.ts

@@ -1,9 +1,23 @@
 import type { AuditScope, ScopeConfig } from './types.js';
+/** Flat JSON shape that audit-ci expects as its config file. */
 interface AuditCiFlatConfig {
     [key: string]: boolean | string | string[] | undefined;
     allowlist: string[];
     'show-not-found'?: boolean;
 }
+/**
+ * Transform a scope config into the flat JSON structure audit-ci expects.
+ *
+ * Translates `severityThreshold` to the corresponding audit-ci boolean,
+ * adds scope-specific flags (`skip-dev` for prod, `extra-args: ["--dev"]` for dev),
+ * and flattens the typed allowlist to an array of ID strings.
+ */
 export declare function buildFlatConfig(scopeConfig: ScopeConfig, scope: AuditScope): AuditCiFlatConfig;
+/**
+ * Generate the audit-ci config file for a scope and write it to disk.
+ *
+ * The output path is `{outputDir}/audit-ci.{scope}.json`. The caller must
+ * ensure `outputDir` already exists (e.g., via `withTempDir`).
+ */
 export declare function generateAuditCiConfig(scopeConfig: ScopeConfig, scope: AuditScope, outputDir: string): Promise<string>;
 export {};

package/dist/esm/init/initCommand.d.ts

@@ -2,5 +2,11 @@ interface InitOptions {
     dryRun: boolean;
     force: boolean;
 }
+/**
+ * Run the `v11y init` command.
+ *
+ * Scaffolds the starter config file and the GitHub Actions workflow, then prints next steps.
+ * Returns the process exit code (0 for success, 1 if any write failed).
+ */
 export declare function initCommand({ dryRun, force }: InitOptions): number;
 export {};

package/dist/esm/init/scaffold.d.ts

@@ -1,4 +1,4 @@
-import type { WriteResult } from '@williamthorsen/nmr-core';
+import { type WriteResult } from '@williamthorsen/nmr-core';
 interface ScaffoldOptions {
     dryRun: boolean;
     force: boolean;
@@ -6,8 +6,28 @@ interface ScaffoldOptions {
 interface ScaffoldResult {
     configResult: WriteResult;
 }
+/**
+ * Scaffold the v11y-check config file with sensible defaults.
+ *
+ * Returns `{ configResult }` to preserve the signature consumed by `syncCommand`, which predates
+ * the workflow scaffolding and treats the config result as a named field.
+ */
 export declare function scaffoldConfig({ dryRun, force }: ScaffoldOptions): ScaffoldResult;
+/** Copy the bundled audit.yaml.template to `.github/workflows/audit.yaml` in the target repo. */
 export declare function copyWorkflowTemplate(dryRun: boolean, overwrite: boolean): WriteResult;
+/**
+ * Scaffold the GitHub Actions audit workflow to `.github/workflows/audit.yaml`.
+ *
+ * Wraps `copyWorkflowTemplate` to provide a stable seam for future post-write transformations
+ * (e.g., variable substitution) without changing call sites.
+ */
 export declare function scaffoldWorkflow(dryRun: boolean, overwrite: boolean): WriteResult;
+/**
+ * Scaffold v11y-check files for the target repo.
+ *
+ * Writes both the config file and the GitHub Actions workflow. Returns a flat array of write
+ * results in the order [config, workflow]. `ScaffoldOptions.force` is translated to `overwrite`
+ * when calling the workflow helpers.
+ */
 export declare function scaffoldFiles({ dryRun, force }: ScaffoldOptions): WriteResult[];
 export {};

package/dist/esm/init/templates.d.ts

@@ -1 +1,2 @@
+/** Default v11y-check config file content. */
 export declare const v11yCheckConfigTemplate: string;

package/dist/esm/run-audit.d.ts

@@ -1,21 +1,34 @@
 import type { AuditResult } from './types.js';
+/** Resolve the audit-ci binary path from node_modules. */
 export declare function resolveAuditCiBin(): string;
+/** Result of parsing audit-ci output, including any warnings. */
 export interface ParseResult {
     results: AuditResult[];
     warnings: string[];
 }
+/**
+ * Parse audit-ci JSON output into typed audit results.
+ *
+ * Extracts advisories from the JSON, mapping each to an `AuditResult` with
+ * the first discovered dependency path. Returns warnings when input is
+ * non-empty but not parseable.
+ */
 export declare function parseAuditCiOutput(jsonString: string): ParseResult;
+/** Result of extracting stale entries, including any warnings. */
 export interface StaleEntriesResult {
     entries: string[];
     warnings: string[];
 }
+/** Extract stale allowlist entries from audit-ci JSON output. */
 export declare function extractStaleEntries(jsonString: string): StaleEntriesResult;
+/** Options for running audit-ci. */
 interface RunAuditOptions {
     configPath: string;
     cwd?: string;
     json?: boolean;
     reportType?: 'full';
 }
+/** Result from a normal audit run. */
 export interface AuditRunResult {
     exitCode: number;
     staleEntries: string[];
@@ -23,12 +36,25 @@ export interface AuditRunResult {
     stderr: string;
     warnings: string[];
 }
+/**
+ * Invoke audit-ci with the given config file in normal (CI) mode.
+ *
+ * Returns the exit code faithfully. When `json` is true, output is JSON;
+ * otherwise audit-ci uses its default text format. Stale overrides are
+ * detected from JSON output and returned.
+ */
 export declare function runAudit({ configPath, cwd, json }: RunAuditOptions): AuditRunResult;
+/** Result from a report-mode audit run. */
 export interface ReportResult {
     results: AuditResult[];
     stdout: string;
     stderr: string;
     warnings: string[];
 }
+/**
+ * Invoke audit-ci in report mode (no allowlist filtering, swallows exit code).
+ *
+ * Always returns exit code 0. Parses JSON output into typed `AuditResult` objects.
+ */
 export declare function runReport({ configPath, cwd, reportType }: Omit<RunAuditOptions, 'json'>): ReportResult;
 export {};

package/dist/esm/sync.d.ts

@@ -1,19 +1,43 @@
 import type { AllowlistEntry, AuditResult, AuditScope, V11yCheckConfig } from './types.js';
+/** Produce a full ISO 8601 UTC datetime string. */
 export declare function formatUtcDatetime(date: Date): string;
+/** Format a Date as a human-friendly UTC string for use in reason messages. */
 export declare function formatFriendlyUtc(date: Date): string;
+/** Result of a sync operation for a single scope. */
 export interface SyncResult {
     added: AllowlistEntry[];
     kept: AllowlistEntry[];
     removed: AllowlistEntry[];
     scope: AuditScope;
 }
+/**
+ * Compute the updated allowlist by diffing audit results against the current entries.
+ *
+ * New advisories are added with an auto-populated reason. Resolved advisories are removed.
+ * Existing entries with a non-empty reason are preserved.
+ */
 export declare function computeSyncDiff(currentAllowlist: AllowlistEntry[], auditResults: AuditResult[], date?: Date): {
     added: AllowlistEntry[];
     kept: AllowlistEntry[];
     removed: AllowlistEntry[];
 };
+/**
+ * Build the updated config by replacing the allowlist for the given scope.
+ *
+ * Returns a new config object; does not mutate the input.
+ */
 export declare function buildUpdatedConfig(config: V11yCheckConfig, scope: AuditScope, newAllowlist: AllowlistEntry[]): V11yCheckConfig;
+/**
+ * Serialize the config to JSON with alphabetically ordered allowlist entry keys.
+ *
+ * Includes `$schema` when present. Uses `severityThreshold` instead of boolean fields.
+ */
 export declare function serializeConfig(config: V11yCheckConfig): string;
+/**
+ * Synchronize the allowlist for a scope by diffing audit results against the current config.
+ *
+ * Returns the sync diff and the updated config. Writes the updated config to disk.
+ */
 export declare function syncAllowlist(config: V11yCheckConfig, scope: AuditScope, auditResults: AuditResult[], configFilePath: string, date?: Date): Promise<{
     syncResult: SyncResult;
     updatedConfig: V11yCheckConfig;

package/dist/esm/tmp.d.ts

@@ -1 +1,9 @@
+/**
+ * Execute a callback with a temporary directory, ensuring cleanup afterward.
+ *
+ * Creates a unique temp directory under `os.tmpdir()` and removes it
+ * (recursively) when the callback completes or throws.
+ *
+ * @internal Exported for testing.
+ */
 export declare function withTempDir<T>(fn: (tempDir: string) => Promise<T>): Promise<T>;

package/dist/esm/types.d.ts

@@ -1,8 +1,13 @@
 import { z } from 'zod';
+/** The dependency scope to audit: development or production. */
 export type AuditScope = 'dev' | 'prod';
+/** All valid scope values. */
 export declare const AUDIT_SCOPES: readonly AuditScope[];
+/** Valid severity threshold values in ascending order. */
 export declare const SEVERITY_THRESHOLDS: readonly ["low", "moderate", "high", "critical"];
+/** Severity level at or above which audit-ci should fail. */
 export type SeverityThreshold = (typeof SEVERITY_THRESHOLDS)[number];
+/** A single allowlisted advisory with metadata for traceability. */
 export interface AllowlistEntry {
     addedAt?: string | undefined;
     id: string;
@@ -10,6 +15,7 @@ export interface AllowlistEntry {
     reason?: string | undefined;
     url: string;
 }
+/** Zod schema for an allowlist entry. */
 export declare const allowlistEntrySchema: z.ZodObject<{
     addedAt: z.ZodOptional<z.ZodString>;
     id: z.ZodString;
@@ -17,10 +23,13 @@ export declare const allowlistEntrySchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
     url: z.ZodString;
 }, z.core.$strip>;
+/** Configuration for a single audit scope (dev or prod). */
 export interface ScopeConfig {
     allowlist: AllowlistEntry[];
+    /** Fail on advisories at or above this severity. */
     severityThreshold?: SeverityThreshold | undefined;
 }
+/** Zod schema for a scope configuration block. */
 export declare const scopeConfigSchema: z.ZodObject<{
     allowlist: z.ZodArray<z.ZodObject<{
         addedAt: z.ZodOptional<z.ZodString>;
@@ -36,11 +45,13 @@ export declare const scopeConfigSchema: z.ZodObject<{
         critical: "critical";
     }>>;
 }, z.core.$strict>;
+/** Source-of-truth configuration for v11y-check. */
 export interface V11yCheckConfig {
     $schema?: string | undefined;
     dev: ScopeConfig;
     prod: ScopeConfig;
 }
+/** Zod schema for the full v11y-check configuration file. */
 export declare const v11yCheckConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     dev: z.ZodObject<{
@@ -74,7 +85,9 @@ export declare const v11yCheckConfigSchema: z.ZodObject<{
         }>>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+/** Built-in defaults used when no config file is present. */
 export declare const DEFAULT_CONFIG: V11yCheckConfig;
+/** A single vulnerability found by audit-ci. */
 export interface AuditResult {
     cvss?: {
         score?: number;
@@ -89,10 +102,19 @@ export interface AuditResult {
     title?: string | undefined;
     url: string;
 }
+/** Parsed CLI options shared across subcommands. */
 export interface CommandOptions {
     configPath?: string | undefined;
     json: boolean;
     scopes: AuditScope[];
     verbose: boolean;
 }
+/**
+ * Determine whether a severity string is at or above the given threshold.
+ *
+ * Unrecognized or undefined severities are treated as above threshold
+ * (conservative — surfaces unknown vulns rather than hiding them).
+ *
+ * @internal Exported for testing.
+ */
 export declare function isSeverityAtOrAbove(severity: string | undefined, threshold: SeverityThreshold): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v11y-check",
-  "version": "0.15.6",
+  "version": "0.15.8",
   "private": false,
   "description": "Wrap audit-ci with a richer config model, typed JSON source of truth, and sync workflow",
   "keywords": [
@@ -43,16 +43,16 @@
     "templates"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.5.0",
+    "@williamthorsen/nmr-core": "0.10.4",
+    "@williamthorsen/toolbelt.errors": "0.6.3",
     "audit-ci": "7.1.0",
-    "zod": "4.4.3",
-    "@williamthorsen/nmr-core": "0.10.2"
+    "zod": "4.4.3"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.filesystem": "0.6.0",
-    "@williamthorsen/toolbelt.testing": "0.3.0",
-    "@williamthorsen/toolbelt.vitest": "0.4.0",
-    "readyup": "0.30.0"
+    "@williamthorsen/toolbelt.filesystem": "0.8.2",
+    "@williamthorsen/toolbelt.testing": "0.5.0",
+    "@williamthorsen/toolbelt.vitest": "0.8.0",
+    "readyup": "0.35.0"
   },
   "engines": {
     "node": ">=24"