knip-guard/dist/index.d.ts

Baseline / no-new-issues guard for Knip

/**
 * A single entry in a Knip issue array (dependency, export, type, etc.)
 * @property name - The name of the issue entry
 * @property line - Line number where the issue occurs
 * @property col - Column number where the issue occurs
 * @property pos - Position offset in the file
 */
export interface KnipIssueEntry {
    name?: string;
    line?: number;
    col?: number;
    pos?: number;
    [key: string]: unknown;
}
/**
 * A single issue reported by Knip, which may contain multiple categories of problems
 * @property file - The file path where the issue was detected
 * @property owners - Optional list of code owners for this file
 * @property dependencies - Unused npm dependencies
 * @property devDependencies - Unused dev dependencies
 * @property optionalPeerDependencies - Unused optional peer dependencies
 * @property unlisted - Unlisted dependencies that are imported
 * @property unresolved - Imports that cannot be resolved
 * @property binaries - Unused binary scripts
 * @property exports - Unused named exports
 * @property nsExports - Unused namespace exports
 * @property types - Unused type definitions
 * @property nsTypes - Unused namespace types
 * @property duplicates - Duplicate exports
 * @property enumMembers - Unused enum members, keyed by enum name
 * @property classMembers - Unused class members, keyed by class name
 */
export interface KnipIssue {
    file?: string;
    owners?: string[];
    dependencies?: KnipIssueEntry[];
    devDependencies?: KnipIssueEntry[];
    optionalPeerDependencies?: KnipIssueEntry[];
    unlisted?: KnipIssueEntry[];
    unresolved?: KnipIssueEntry[];
    binaries?: KnipIssueEntry[];
    exports?: KnipIssueEntry[];
    nsExports?: KnipIssueEntry[];
    types?: KnipIssueEntry[];
    nsTypes?: KnipIssueEntry[];
    duplicates?: string[];
    enumMembers?: Record<string, KnipIssueEntry[]>;
    classMembers?: Record<string, KnipIssueEntry[]>;
    [key: string]: unknown;
}
/**
 * The complete JSON report produced by Knip with `--reporter json`
 * @property files - List of unused files
 * @property issues - Array of issues organized by file
 */
export interface KnipJsonReport {
    files?: string[];
    issues?: KnipIssue[];
    [key: string]: unknown;
}
/**
 * The baseline data structure stored on disk
 * Tracks all known issues and metadata about when the baseline was created/updated
 * @property createdAt - ISO timestamp when the baseline was first created
 * @property updatedAt - ISO timestamp of the last update
 * @property issues - Sorted array of deterministic issue keys
 * @property sourceCommand - Optional command used to generate the baseline
 */
export interface BaselineData {
    createdAt: string;
    updatedAt: string;
    issues: string[];
    sourceCommand?: string;
}
/**
 * Result of comparing current issues against a baseline
 * @property newIssues - Issues found in current report but not in baseline
 * @property resolvedIssues - Issues in baseline that are no longer present
 */
export interface DiffResult {
    newIssues: string[];
    resolvedIssues: string[];
}
/**
 * Run knip with JSON reporter and parse the output
 * Executes the given command with `--reporter json` flag and returns the parsed report
 * @param command - Full command to run knip (default: "npx knip")
 * @returns Parsed Knip JSON report
 * @throws Error if command fails or output is invalid JSON
 * @example
 * const report = await runKnipJson('npm run knip');
 */
export declare function runKnipJson(command?: string): Promise<KnipJsonReport>;
/**
 * Load a Knip JSON report from a file
 * @param reportPath - Path to the Knip JSON report file
 * @returns Parsed Knip JSON report
 * @throws Error if file cannot be read or JSON is invalid
 * @example
 * const report = await loadKnipReportFromFile('./knip-report.json');
 */
export declare function loadKnipReportFromFile(reportPath: string): Promise<KnipJsonReport>;
/**
 * Extract deterministic issue keys from a Knip report
 * Keys exclude line/column/position information, making them stable across formatting changes
 * This allows baseline comparisons to work correctly even when code is reformatted
 * @param report - The Knip JSON report to extract keys from
 * @returns Set of deterministic issue keys
 * @example
 * const report = await runKnipJson();
 * const keys = extractIssueKeys(report);
 * // keys contains: "files::src/unused.ts", "exports::src/foo.ts::unusedFn"
 */
export declare function extractIssueKeys(report: KnipJsonReport): Set<string>;
/**
 * Load baseline data from disk
 * Returns null if the baseline file does not exist
 * @param baselinePath - Path to the baseline JSON file
 * @returns Baseline data or null if file not found
 * @throws Error if file exists but cannot be read or parsed
 * @example
 * const baseline = await loadBaseline('.knip-baseline.json');
 */
export declare function loadBaseline(baselinePath: string): Promise<BaselineData | null>;
/**
 * Save baseline data to disk
 * Creates a new baseline or updates an existing one with metadata timestamps
 * Issues are automatically sorted for deterministic output
 * @param baselinePath - Path where the baseline JSON file should be saved
 * @param issueKeys - Set of deterministic issue keys to include in baseline
 * @param existing - Existing baseline data (to preserve createdAt timestamp)
 * @param sourceCommand - Optional command used to generate the baseline
 * @returns The saved baseline data
 * @throws Error if file cannot be written
 * @example
 * const keys = extractIssueKeys(report);
 * const baseline = await saveBaseline('.knip-baseline.json', keys, null, 'npm run knip');
 */
export declare function saveBaseline(baselinePath: string, issueKeys: Set<string>, existing?: BaselineData | null, sourceCommand?: string): Promise<BaselineData>;
/**
 * Compare current issues against a baseline
 * Identifies new issues that weren't in the baseline and resolved issues that no longer exist
 * @param baseline - The baseline data to compare against (null is treated as empty)
 * @param currentIssueKeys - Set of current deterministic issue keys
 * @returns Object containing arrays of new and resolved issues, both sorted
 * @example
 * const baseline = await loadBaseline('.knip-baseline.json');
 * const current = extractIssueKeys(report);
 * const { newIssues, resolvedIssues } = diffBaseline(baseline, current);
 */
export declare function diffBaseline(baseline: BaselineData | null, currentIssueKeys: Set<string>): DiffResult;
//# sourceMappingURL=index.d.ts.map