@eddacraft/anvil-core 0.1.0

package/dist/suppression/parser.js

@@ -0,0 +1,219 @@
+import { z } from 'zod';
+import { createDebugger } from '../utils/debug.js';
+const debug = createDebugger('suppression');
+export const ParsedSuppressionSchema = z.object({
+    warningId: z
+        .string()
+        .regex(/^(AP|ARCH|BOUND)-\d{3}$/)
+        .describe('Warning ID (e.g., AP-001, ARCH-001)'),
+    reason: z.string().min(1).describe('Human-provided reason for suppression'),
+    expiresAt: z.date().optional().describe('Expiry date for time-boxed suppressions'),
+    line: z.number().int().positive().describe('Line number of the comment (1-based)'),
+    column: z.number().int().nonnegative().optional().describe('Column number (0-based)'),
+    scope: z.enum(['line', 'statement', 'file']).describe('Suppression scope'),
+    raw: z.string().describe('Raw comment text'),
+});
+// Pattern: @anvil-ignore <ID>: <reason> (reason can be empty for validation)
+const IGNORE_PATTERN = /@anvil-ignore\s+((?:AP|ARCH|BOUND)-\d{3}):\s*(.*)/;
+// Pattern: @anvil-ignore-until YYYY-MM-DD <ID>: <reason>
+const IGNORE_UNTIL_PATTERN = /@anvil-ignore-until\s+(\d{4}-\d{2}-\d{2})\s+((?:AP|ARCH|BOUND)-\d{3}):\s*(.*)/;
+function determineScope(line, column, lineContent, previousLineHasCode) {
+    if (line <= 5 && !previousLineHasCode) {
+        const trimmed = lineContent.trim();
+        if (trimmed.startsWith('//') ||
+            trimmed.startsWith('/*') ||
+            trimmed.startsWith('/**') ||
+            trimmed.startsWith('<!--')) {
+            return 'file';
+        }
+    }
+    const beforeComment = lineContent.substring(0, column).trim();
+    if (beforeComment.length > 0 && !beforeComment.startsWith('//')) {
+        return 'line';
+    }
+    return 'statement';
+}
+function hasCode(line, insideHtmlComment) {
+    if (insideHtmlComment)
+        return false;
+    const trimmed = line.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (trimmed.startsWith('//'))
+        return false;
+    if (trimmed.startsWith('/*') && trimmed.endsWith('*/'))
+        return false;
+    if (trimmed.startsWith('/**') && trimmed.endsWith('*/'))
+        return false;
+    if (trimmed.startsWith('*') && !trimmed.startsWith('*/'))
+        return false;
+    if (trimmed.startsWith('<!--') && trimmed.includes('-->'))
+        return false;
+    if (trimmed.startsWith('<!--'))
+        return false;
+    return true;
+}
+function updateHtmlCommentState(line, insideHtmlComment) {
+    const trimmed = line.trim();
+    if (insideHtmlComment) {
+        return !trimmed.includes('-->');
+    }
+    if (trimmed.includes('<!--') && !trimmed.includes('-->')) {
+        return true;
+    }
+    return false;
+}
+function extractSuppressionComment(line) {
+    const singleMatch = line.match(/\/\/\s*(@anvil-ignore[^\n]*)/);
+    if (singleMatch) {
+        return {
+            comment: singleMatch[1],
+            column: line.indexOf('//'),
+        };
+    }
+    const blockMatch = line.match(/\/\*\*?\s*(@anvil-ignore[^*]*)\s*\*\//);
+    if (blockMatch) {
+        return {
+            comment: blockMatch[1],
+            column: line.indexOf('/*'),
+        };
+    }
+    const htmlMatch = line.match(/<!--\s*(@anvil-ignore.*?)\s*-->/);
+    if (htmlMatch) {
+        return {
+            comment: htmlMatch[1],
+            column: line.indexOf('<!--'),
+        };
+    }
+    return null;
+}
+function parseSuppression(comment, line, column, scope, raw) {
+    const untilMatch = comment.match(IGNORE_UNTIL_PATTERN);
+    if (untilMatch) {
+        const [, dateStr, warningId, reason] = untilMatch;
+        const trimmedReason = reason.trim();
+        if (!trimmedReason) {
+            return {
+                line,
+                column,
+                message: 'Suppression requires a non-empty reason',
+                raw,
+            };
+        }
+        const expiresAt = new Date(dateStr);
+        if (isNaN(expiresAt.getTime())) {
+            return {
+                line,
+                column,
+                message: `Invalid date format: ${dateStr}. Use YYYY-MM-DD`,
+                raw,
+            };
+        }
+        return {
+            warningId,
+            reason: trimmedReason,
+            expiresAt,
+            line,
+            column,
+            scope,
+            raw,
+        };
+    }
+    const ignoreMatch = comment.match(IGNORE_PATTERN);
+    if (ignoreMatch) {
+        const [, warningId, reason] = ignoreMatch;
+        const trimmedReason = reason.trim();
+        if (!trimmedReason) {
+            return {
+                line,
+                column,
+                message: 'Suppression requires a non-empty reason',
+                raw,
+            };
+        }
+        return {
+            warningId,
+            reason: trimmedReason,
+            line,
+            column,
+            scope,
+            raw,
+        };
+    }
+    return {
+        line,
+        column,
+        message: 'Invalid suppression format. Expected: @anvil-ignore <ID>: <reason> or @anvil-ignore-until <DATE> <ID>: <reason>',
+        raw,
+    };
+}
+export function parseSuppressions(content, _filePath) {
+    debug('parsing suppressions', { filePath: _filePath, contentLength: content.length });
+    const lines = content.split('\n');
+    const suppressions = [];
+    const errors = [];
+    let previousLineHasCode = false;
+    let insideHtmlComment = false;
+    for (let i = 0; i < lines.length; i++) {
+        const lineNumber = i + 1;
+        const lineContent = lines[i];
+        if (!lineContent.includes('@anvil-ignore')) {
+            previousLineHasCode = previousLineHasCode || hasCode(lineContent, insideHtmlComment);
+            insideHtmlComment = updateHtmlCommentState(lineContent, insideHtmlComment);
+            continue;
+        }
+        const extracted = extractSuppressionComment(lineContent);
+        if (!extracted) {
+            previousLineHasCode = previousLineHasCode || hasCode(lineContent, insideHtmlComment);
+            insideHtmlComment = updateHtmlCommentState(lineContent, insideHtmlComment);
+            continue;
+        }
+        const { comment, column } = extracted;
+        const scope = determineScope(lineNumber, column, lineContent, previousLineHasCode);
+        const result = parseSuppression(comment, lineNumber, column, scope, lineContent.trim());
+        if ('message' in result) {
+            errors.push(result);
+        }
+        else {
+            suppressions.push(result);
+        }
+        previousLineHasCode = previousLineHasCode || hasCode(lineContent, insideHtmlComment);
+        insideHtmlComment = updateHtmlCommentState(lineContent, insideHtmlComment);
+    }
+    if (suppressions.length > 0 || errors.length > 0) {
+        debug('suppressions parsed', { found: suppressions.length, errors: errors.length });
+    }
+    return { suppressions, errors };
+}
+export function isExpired(suppression, now = new Date()) {
+    if (!suppression.expiresAt) {
+        return false;
+    }
+    return suppression.expiresAt < now;
+}
+export function suppressionMatches(suppression, warningId, warningLine) {
+    if (suppression.warningId !== warningId) {
+        return false;
+    }
+    switch (suppression.scope) {
+        case 'file':
+            return true;
+        case 'line':
+            return suppression.line === warningLine;
+        case 'statement':
+            return warningLine === suppression.line + 1;
+        default:
+            return false;
+    }
+}
+export function findMatchingSuppression(suppressions, warningId, warningLine, now = new Date()) {
+    for (const suppression of suppressions) {
+        if (isExpired(suppression, now)) {
+            continue;
+        }
+        if (suppressionMatches(suppression, warningId, warningLine)) {
+            return suppression;
+        }
+    }
+    return null;
+}

package/dist/suppression/service.d.ts

@@ -0,0 +1,29 @@
+import type { ParsedSuppression } from './parser.js';
+import { SuppressionStore } from './store.js';
+import type { Warning } from '../antipattern/types.js';
+export interface SuppressionStats {
+    total: number;
+    active: number;
+    expired: number;
+    appliedThisRun: number;
+}
+export interface FileSuppressions {
+    file: string;
+    suppressions: ParsedSuppression[];
+}
+export declare class SuppressionService {
+    private store;
+    private fileCache;
+    private workspaceRoot;
+    constructor(workspaceRoot: string, store?: SuppressionStore);
+    private normalizeToRelative;
+    initialize(): Promise<void>;
+    parseFileSuppressions(filePath: string): Promise<ParsedSuppression[]>;
+    applyToWarnings(warnings: Warning[], filePath: string, now?: Date): Warning[];
+    processFiles(files: string[]): Promise<FileSuppressions[]>;
+    applyToAllWarnings(warnings: Warning[], now?: Date): Warning[];
+    getStats(warnings: Warning[], now?: Date): SuppressionStats;
+    clearCache(): void;
+    getStore(): SuppressionStore;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/suppression/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/suppression/service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,yBAAyB,CAAC;AAKpE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,iBAAiB,EAAE,CAAC;CACnC;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,aAAa,CAAS;gBAElB,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB;IAM3D,OAAO,CAAC,mBAAmB;IAarB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAsB3E,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,EAAE;IAgCnF,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAehE,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,EAAE;IAoB1E,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,GAAE,IAAiB,GAAG,gBAAgB;IA2BvE,UAAU,IAAI,IAAI;IAIlB,QAAQ,IAAI,gBAAgB;CAG7B"}

package/dist/suppression/service.js

@@ -0,0 +1,132 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { parseSuppressions, findMatchingSuppression } from './parser.js';
+import { SuppressionStore } from './store.js';
+import { createDebugger } from '../utils/debug.js';
+const debug = createDebugger('suppression');
+export class SuppressionService {
+    store;
+    fileCache = new Map();
+    workspaceRoot;
+    constructor(workspaceRoot, store) {
+        this.workspaceRoot = workspaceRoot;
+        const anvilDir = path.join(workspaceRoot, '.anvil');
+        this.store = store ?? new SuppressionStore(anvilDir);
+    }
+    normalizeToRelative(filePath) {
+        if (path.isAbsolute(filePath)) {
+            const withSep = this.workspaceRoot.endsWith(path.sep)
+                ? this.workspaceRoot
+                : this.workspaceRoot + path.sep;
+            if (filePath.startsWith(withSep)) {
+                return filePath.slice(withSep.length);
+            }
+            return path.relative(this.workspaceRoot, filePath);
+        }
+        return filePath;
+    }
+    async initialize() {
+        debug('initializing SuppressionService', { workspaceRoot: this.workspaceRoot });
+        await this.store.load();
+    }
+    async parseFileSuppressions(filePath) {
+        const normalizedPath = this.normalizeToRelative(filePath);
+        const cached = this.fileCache.get(normalizedPath);
+        if (cached) {
+            return cached;
+        }
+        try {
+            const absolutePath = path.isAbsolute(filePath)
+                ? filePath
+                : path.join(this.workspaceRoot, filePath);
+            const content = await fs.readFile(absolutePath, 'utf-8');
+            const result = parseSuppressions(content, normalizedPath);
+            this.fileCache.set(normalizedPath, result.suppressions);
+            return result.suppressions;
+        }
+        catch {
+            return [];
+        }
+    }
+    applyToWarnings(warnings, filePath, now = new Date()) {
+        const normalizedPath = this.normalizeToRelative(filePath);
+        const suppressions = this.fileCache.get(normalizedPath) ?? [];
+        return warnings.map((warning) => {
+            if (warning.suppressed) {
+                return warning;
+            }
+            const normalizedWarningFile = this.normalizeToRelative(warning.location.file);
+            if (normalizedWarningFile !== normalizedPath) {
+                return warning;
+            }
+            const match = findMatchingSuppression(suppressions, warning.id, warning.location.line, now);
+            if (!match) {
+                return warning;
+            }
+            const suppression = {
+                reason: match.reason,
+                scope: match.scope,
+            };
+            return {
+                ...warning,
+                suppressed: suppression,
+            };
+        });
+    }
+    async processFiles(files) {
+        debug('processing files for suppressions', { fileCount: files.length });
+        const results = [];
+        for (const file of files) {
+            const normalizedFile = this.normalizeToRelative(file);
+            const suppressions = await this.parseFileSuppressions(file);
+            if (suppressions.length > 0) {
+                results.push({ file: normalizedFile, suppressions });
+            }
+        }
+        return results;
+    }
+    applyToAllWarnings(warnings, now = new Date()) {
+        const fileGroups = new Map();
+        for (const warning of warnings) {
+            const normalizedFile = this.normalizeToRelative(warning.location.file);
+            const group = fileGroups.get(normalizedFile) ?? [];
+            group.push(warning);
+            fileGroups.set(normalizedFile, group);
+        }
+        const result = [];
+        for (const [file, fileWarnings] of fileGroups) {
+            const processed = this.applyToWarnings(fileWarnings, file, now);
+            result.push(...processed);
+        }
+        return result;
+    }
+    getStats(warnings, now = new Date()) {
+        const allSuppressions = [];
+        for (const suppressions of this.fileCache.values()) {
+            allSuppressions.push(...suppressions);
+        }
+        let expired = 0;
+        let active = 0;
+        for (const s of allSuppressions) {
+            if (s.expiresAt && s.expiresAt < now) {
+                expired++;
+            }
+            else {
+                active++;
+            }
+        }
+        const appliedThisRun = warnings.filter((w) => w.suppressed).length;
+        return {
+            total: allSuppressions.length,
+            active,
+            expired,
+            appliedThisRun,
+        };
+    }
+    clearCache() {
+        this.fileCache.clear();
+    }
+    getStore() {
+        return this.store;
+    }
+}

package/dist/suppression/store.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { SuppressionRecordSchema } from '../antipattern/types.js';
+import type { ParsedSuppression } from './parser.js';
+export type SuppressionRecord = z.infer<typeof SuppressionRecordSchema>;
+export declare const SuppressionStoreDataSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    suppressions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        pattern_id: z.ZodString;
+        file: z.ZodString;
+        line: z.ZodNumber;
+        reason: z.ZodString;
+        author: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+        commit: z.ZodOptional<z.ZodString>;
+        scope: z.ZodEnum<{
+            file: "file";
+            line: "line";
+            statement: "statement";
+            import: "import";
+        }>;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    lastUpdated: z.ZodString;
+}, z.core.$strip>;
+export type SuppressionStoreData = z.infer<typeof SuppressionStoreDataSchema>;
+export interface SuppressionMatch {
+    record: SuppressionRecord;
+    isExpired: boolean;
+}
+export declare class SuppressionStore {
+    private data;
+    private filePath;
+    private loaded;
+    constructor(anvilDir: string);
+    load(): Promise<void>;
+    save(): Promise<void>;
+    add(record: SuppressionRecord): void;
+    remove(id: string): boolean;
+    /**
+     * Check if a warning is suppressed at the given location.
+     * Returns null if no matching suppression OR if the matching suppression is expired.
+     * Use findSuppressionMatch() if you need to know about expired matches.
+     */
+    isSuppressed(warningId: string, file: string, line: number, now?: Date): SuppressionMatch | null;
+    /**
+     * Find a suppression match, including expired ones.
+     * Use this when you need to report on expired suppressions.
+     */
+    findSuppressionMatch(warningId: string, file: string, line: number, now?: Date): SuppressionMatch | null;
+    private matchesScope;
+    private isRecordExpired;
+    getAll(): SuppressionRecord[];
+    getByFile(file: string): SuppressionRecord[];
+    getExpired(now?: Date): SuppressionRecord[];
+    pruneExpired(now?: Date): number;
+    createRecordFromParsed(parsed: ParsedSuppression, file: string, gitCommit?: string): SuppressionRecord;
+    get isLoaded(): boolean;
+    get count(): number;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/suppression/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/suppression/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAKrD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;iBAIrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAMD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;gBAEX,QAAQ,EAAE,MAAM;IAStB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAUpC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAS3B;;;;OAIG;IACH,YAAY,CACV,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,IAAiB,GACrB,gBAAgB,GAAG,IAAI;IAW1B;;;OAGG;IACH,oBAAoB,CAClB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,IAAiB,GACrB,gBAAgB,GAAG,IAAI;IAgB1B,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,eAAe;IASvB,MAAM,IAAI,iBAAiB,EAAE;IAI7B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAI5C,UAAU,CAAC,GAAG,GAAE,IAAiB,GAAG,iBAAiB,EAAE;IAIvD,YAAY,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM;IAQ5C,sBAAsB,CACpB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,iBAAiB;IAwBpB,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;CACF"}

package/dist/suppression/store.js

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { SuppressionRecordSchema } from '../antipattern/types.js';
+import { createDebugger } from '../utils/debug.js';
+const debug = createDebugger('suppression');
+export const SuppressionStoreDataSchema = z.object({
+    version: z.literal(1),
+    suppressions: z.array(SuppressionRecordSchema),
+    lastUpdated: z.string().datetime(),
+});
+function generateSuppressionId(file, line, patternId) {
+    return `${file}:${line}:${patternId}`;
+}
+export class SuppressionStore {
+    data;
+    filePath;
+    loaded = false;
+    constructor(anvilDir) {
+        this.filePath = path.join(anvilDir, 'suppressions.json');
+        this.data = {
+            version: 1,
+            suppressions: [],
+            lastUpdated: new Date().toISOString(),
+        };
+    }
+    async load() {
+        debug('loading suppression store from', this.filePath);
+        try {
+            const content = await fs.readFile(this.filePath, 'utf-8');
+            const parsed = JSON.parse(content);
+            const result = SuppressionStoreDataSchema.safeParse(parsed);
+            if (result.success) {
+                debug('suppression store loaded', { count: result.data.suppressions.length });
+                this.data = result.data;
+            }
+            else {
+                this.data = {
+                    version: 1,
+                    suppressions: [],
+                    lastUpdated: new Date().toISOString(),
+                };
+            }
+        }
+        catch {
+            this.data = {
+                version: 1,
+                suppressions: [],
+                lastUpdated: new Date().toISOString(),
+            };
+        }
+        this.loaded = true;
+    }
+    async save() {
+        debug('saving suppression store', { count: this.data.suppressions.length });
+        this.data.lastUpdated = new Date().toISOString();
+        const dir = path.dirname(this.filePath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(this.filePath, JSON.stringify(this.data, null, 2), 'utf-8');
+    }
+    add(record) {
+        const existingIndex = this.data.suppressions.findIndex((s) => s.id === record.id);
+        if (existingIndex >= 0) {
+            this.data.suppressions[existingIndex] = record;
+        }
+        else {
+            this.data.suppressions.push(record);
+        }
+    }
+    remove(id) {
+        const index = this.data.suppressions.findIndex((s) => s.id === id);
+        if (index >= 0) {
+            this.data.suppressions.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check if a warning is suppressed at the given location.
+     * Returns null if no matching suppression OR if the matching suppression is expired.
+     * Use findSuppressionMatch() if you need to know about expired matches.
+     */
+    isSuppressed(warningId, file, line, now = new Date()) {
+        const match = this.findSuppressionMatch(warningId, file, line, now);
+        // Per acceptance criteria: expired suppressions should NOT suppress warnings
+        if (match && match.isExpired) {
+            return null;
+        }
+        return match;
+    }
+    /**
+     * Find a suppression match, including expired ones.
+     * Use this when you need to report on expired suppressions.
+     */
+    findSuppressionMatch(warningId, file, line, now = new Date()) {
+        for (const record of this.data.suppressions) {
+            if (record.file !== file)
+                continue;
+            if (record.pattern_id !== warningId)
+                continue;
+            const isExpired = this.isRecordExpired(record, now);
+            const matches = this.matchesScope(record, line);
+            if (matches) {
+                return { record, isExpired };
+            }
+        }
+        return null;
+    }
+    matchesScope(record, warningLine) {
+        switch (record.scope) {
+            case 'file':
+                return true;
+            case 'line':
+                return record.line === warningLine;
+            case 'statement':
+                return warningLine === record.line + 1;
+            case 'import':
+                return warningLine === record.line + 1;
+            default:
+                return false;
+        }
+    }
+    isRecordExpired(record, now) {
+        if (!record.expires_at) {
+            return false;
+        }
+        const expiresAt = new Date(record.expires_at);
+        return expiresAt < now;
+    }
+    getAll() {
+        return [...this.data.suppressions];
+    }
+    getByFile(file) {
+        return this.data.suppressions.filter((s) => s.file === file);
+    }
+    getExpired(now = new Date()) {
+        return this.data.suppressions.filter((record) => this.isRecordExpired(record, now));
+    }
+    pruneExpired(now = new Date()) {
+        const before = this.data.suppressions.length;
+        this.data.suppressions = this.data.suppressions.filter((record) => !this.isRecordExpired(record, now));
+        return before - this.data.suppressions.length;
+    }
+    createRecordFromParsed(parsed, file, gitCommit) {
+        const id = generateSuppressionId(file, parsed.line, parsed.warningId);
+        const record = {
+            id,
+            pattern_id: parsed.warningId,
+            file,
+            line: parsed.line,
+            reason: parsed.reason,
+            timestamp: new Date().toISOString(),
+            scope: parsed.scope,
+        };
+        if (gitCommit) {
+            record.commit = gitCommit;
+        }
+        if (parsed.expiresAt) {
+            record.expires_at = parsed.expiresAt.toISOString();
+        }
+        return record;
+    }
+    get isLoaded() {
+        return this.loaded;
+    }
+    get count() {
+        return this.data.suppressions.length;
+    }
+}

package/dist/utils/debug.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Debug logging utility for Anvil
+ *
+ * Enables debug output when ANVIL_DEBUG or DEBUG environment variable is set.
+ * This provides visibility into error handling without cluttering production output.
+ *
+ * Usage:
+ *   import { debug } from './utils/debug.js';
+ *   debug('provenance', 'Failed to parse index', error);
+ *
+ * Enable with:
+ *   ANVIL_DEBUG=1 anvil gate plan.md
+ *   DEBUG=anvil:* anvil gate plan.md
+ */
+type DebugNamespace = 'provenance' | 'cache' | 'gate' | 'validation' | 'adapter' | 'architecture' | 'edge-detector' | 'entry-detector' | 'drift' | 'policy' | 'git-ai-notes' | 'agent' | 'atomic' | 'git-agent' | 'lock' | 'queue' | 'check' | 'watch' | 'cli' | 'kindling' | 'api' | 'service' | 'export' | 'explain' | 'suppression' | 'config' | 'secret' | 'compiler';
+/**
+ * Check if debug logging is enabled
+ */
+export declare function isDebugEnabled(namespace?: DebugNamespace): boolean;
+/**
+ * Log a debug message if debug mode is enabled
+ *
+ * @param namespace - The component namespace (e.g., 'provenance', 'gate')
+ * @param message - The debug message
+ * @param data - Optional additional data to log
+ */
+/**
+ * Redact values that look like tokens, keys, or secrets before logging.
+ *
+ * Patterns redacted:
+ * - Hex tokens (40+ hex characters, e.g. SHA tokens, API keys)
+ * - Base64 tokens (20+ chars of base64 alphabet)
+ * - Common secret prefixes: sk-, ghp_, ghu_, Bearer
+ *
+ * @param value - The string to sanitize
+ * @returns The sanitized string with secrets replaced by [REDACTED]
+ */
+export declare function sanitizeForLog(value: string): string;
+export declare function debug(namespace: DebugNamespace, message: string, data?: unknown): void;
+/**
+ * Create a namespaced debug logger
+ *
+ * @param namespace - The component namespace
+ * @returns A debug function bound to the namespace
+ */
+export declare function createDebugger(namespace: DebugNamespace): (message: string, data?: unknown) => void;
+export {};
+//# sourceMappingURL=debug.d.ts.map

package/dist/utils/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,KAAK,cAAc,GACf,YAAY,GACZ,OAAO,GACP,MAAM,GACN,YAAY,GACZ,SAAS,GACT,cAAc,GACd,eAAe,GACf,gBAAgB,GAChB,OAAO,GACP,QAAQ,GACR,cAAc,GACd,OAAO,GACP,QAAQ,GACR,WAAW,GACX,MAAM,GACN,OAAO,GACP,OAAO,GACP,OAAO,GACP,KAAK,GACL,UAAU,GACV,KAAK,GACL,SAAS,GACT,QAAQ,GACR,SAAS,GACT,aAAa,GACb,QAAQ,GACR,QAAQ,GACR,UAAU,CAAC;AAEf;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,OAAO,CAoBlE;AAED;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAcpD;AAED,wBAAgB,KAAK,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAyBtF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,cAAc,GACxB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAE3C"}