pw-sanitizer 0.1.0

package/dist/config/loader.js

@@ -0,0 +1,173 @@
+"use strict";
+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.loadConfig = loadConfig;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const logger_js_1 = require("../logger.js");
+/**
+ * Ordered list of config file names that are auto-discovered in the current
+ * working directory when no explicit `--config` path is provided.
+ */
+const CONFIG_FILE_NAMES = [
+    'playwright-sanitizer.config.ts',
+    'playwright-sanitizer.config.js',
+    'playwright-sanitizer.config.json',
+];
+/**
+ * Loads a {@link SanitizerConfig} from an explicit file path.
+ *
+ * - `.json` files are parsed with `JSON.parse`.
+ * - `.ts` / `.js` files are loaded via dynamic `import()`.
+ *   If loading a `.ts` file fails, a compiled `.js` sibling is tried automatically.
+ *
+ * @param filePath - Absolute or relative path to the config file.
+ * @returns The resolved {@link SanitizerConfig}.
+ * @throws Calls `logger.fatal` (which throws) if the file is not found or cannot be parsed.
+ */
+async function loadConfigFromFile(filePath) {
+    const absolutePath = path.resolve(filePath);
+    if (!fs.existsSync(absolutePath)) {
+        return logger_js_1.logger.fatal(`Config file not found: ${absolutePath}`);
+    }
+    const ext = path.extname(absolutePath).toLowerCase();
+    if (ext === '.json') {
+        const content = fs.readFileSync(absolutePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    // .ts or .js — use dynamic import
+    try {
+        const module = await import(absolutePath);
+        return (module.default ?? module);
+    }
+    catch (err) {
+        // If .ts failed, try .js sibling
+        if (ext === '.ts') {
+            const jsSibling = absolutePath.replace(/\.ts$/, '.js');
+            if (fs.existsSync(jsSibling)) {
+                try {
+                    const module = await import(jsSibling);
+                    return (module.default ?? module);
+                }
+                catch {
+                    return logger_js_1.logger.fatal(`Failed to load config from both ${absolutePath} and ${jsSibling}. ` +
+                        `Ensure tsx or ts-node is available, or provide a .js config file.`);
+                }
+            }
+        }
+        return logger_js_1.logger.fatal(`Failed to load config from ${absolutePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Attempts to load a sanitizer config from the `sanitizer` key inside
+ * `playwright.config.ts` or `playwright.config.js` in the given directory.
+ *
+ * Returns `null` if no Playwright config is found, the file cannot be
+ * loaded, or it does not contain a `sanitizer` key.
+ *
+ * @param cwd - The directory to search for a Playwright config file.
+ * @returns The embedded {@link SanitizerConfig}, or `null` if not found.
+ */
+async function loadFromPlaywrightConfig(cwd) {
+    const candidates = ['playwright.config.ts', 'playwright.config.js'];
+    for (const name of candidates) {
+        const fullPath = path.resolve(cwd, name);
+        if (fs.existsSync(fullPath)) {
+            try {
+                const module = await import(fullPath);
+                const config = module.default ?? module;
+                if (config && typeof config === 'object' && 'sanitizer' in config) {
+                    return config.sanitizer;
+                }
+            }
+            catch {
+                // Not loadable or no sanitizer key — continue
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolves and loads the sanitizer configuration.
+ *
+ * Config discovery priority (first match wins):
+ * 1. Explicit `configPath` (from `--config` CLI flag or programmatic call)
+ * 2. `playwright-sanitizer.config.ts` in `cwd`
+ * 3. `playwright-sanitizer.config.js` in `cwd`
+ * 4. `playwright-sanitizer.config.json` in `cwd`
+ * 5. `sanitizer` key inside `playwright.config.ts` / `playwright.config.js`
+ *
+ * If none of the above are found, the function calls `logger.fatal` which
+ * throws an `Error` with an actionable message.
+ *
+ * @param configPath - Optional explicit path to a config file.
+ *   When provided, auto-discovery is skipped entirely.
+ * @returns The resolved {@link SanitizerConfig}.
+ * @throws Calls `logger.fatal` (which throws) when no config can be found or loaded.
+ *
+ * @example
+ * ```ts
+ * // Auto-discover config in cwd
+ * const config = await loadConfig();
+ *
+ * // Load from an explicit path
+ * const config = await loadConfig('./configs/sanitizer.config.ts');
+ * ```
+ */
+async function loadConfig(configPath) {
+    const cwd = process.cwd();
+    // 1. Explicit path
+    if (configPath) {
+        logger_js_1.logger.verbose(`Loading config from explicit path: ${configPath}`);
+        return loadConfigFromFile(configPath);
+    }
+    // 2-4. Auto-discover config files
+    for (const name of CONFIG_FILE_NAMES) {
+        const fullPath = path.resolve(cwd, name);
+        if (fs.existsSync(fullPath)) {
+            logger_js_1.logger.verbose(`Found config file: ${fullPath}`);
+            return loadConfigFromFile(fullPath);
+        }
+    }
+    // 5. Playwright config sanitizer key
+    const fromPlaywright = await loadFromPlaywrightConfig(cwd);
+    if (fromPlaywright) {
+        logger_js_1.logger.verbose('Loaded config from playwright.config sanitizer key');
+        return fromPlaywright;
+    }
+    return logger_js_1.logger.fatal('No playwright-sanitizer config found. ' +
+        'Create playwright-sanitizer.config.ts or pass --config <path>.');
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

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

package/dist/config/types.d.ts

@@ -0,0 +1,432 @@
+/**
+ * Root configuration object for `playwright-sanitizer`.
+ *
+ * All sections are optional — omitting a section disables that feature entirely.
+ * Nothing is redacted or removed unless explicitly declared here.
+ *
+ * @example
+ * ```ts
+ * // playwright-sanitizer.config.ts
+ * import type { SanitizerConfig } from 'playwright-sanitizer';
+ *
+ * const config: SanitizerConfig = {
+ *   redact: {
+ *     patterns: [{ id: 'auth-header', key: 'authorization' }],
+ *   },
+ *   remove: {
+ *     rules: [{ label: 'noisy-poll', stepName: /waitFor/ }],
+ *   },
+ * };
+ *
+ * export default config;
+ * ```
+ */
+export interface SanitizerConfig {
+    /**
+     * Declares what values to mask.
+     * Nothing is redacted unless explicitly listed here.
+     */
+    redact?: RedactConfig;
+    /**
+     * Declares which steps to delete entirely.
+     * Nothing is removed unless explicitly listed here.
+     */
+    remove?: RemoveConfig;
+    /** Output behaviour */
+    output?: OutputConfig;
+    /** Summary and logging */
+    reporting?: ReportingConfig;
+}
+/**
+ * Configuration for the redaction pipeline.
+ *
+ * Patterns are loaded from `patternFiles` first, then merged with inline
+ * `patterns`. Duplicate IDs result in a warning; the last definition wins.
+ */
+export interface RedactConfig {
+    /**
+     * Path(s) to external pattern files (.ts, .js, .json).
+     * Merged with inline `patterns`. No built-in patterns apply.
+     */
+    patternFiles?: string | string[];
+    /**
+     * Inline pattern definitions. Merged with patternFiles.
+     * These are the only patterns that will ever be applied.
+     */
+    patterns?: RedactPattern[];
+    /**
+     * Replacement string for redacted values.
+     * Default: `'[REDACTED]'`
+     */
+    placeholder?: string;
+    /**
+     * Partial redaction: keep first `prefix` and last `suffix` characters,
+     * replace the middle with `'***'`.
+     *
+     * @example
+     * With `{ prefix: 4, suffix: 4 }`:
+     * `'Bearer eyJhbGci...'` → `'Bear***..ci'`
+     *
+     * When set, takes priority over `placeholder` for string values.
+     * If the value is too short to apply partial redaction, it is fully redacted.
+     */
+    partialRedaction?: {
+        prefix: number;
+        suffix: number;
+    };
+}
+/**
+ * A single secret-matching rule used by the redaction pipeline.
+ *
+ * At least one of {@link key} or {@link valuePattern} must be provided.
+ * When both are provided, **both** must match for redaction to apply (AND logic).
+ *
+ * @example
+ * ```ts
+ * // Redact any field named "authorization" regardless of value
+ * { id: 'auth-header', key: 'authorization' }
+ *
+ * // Redact any field whose value looks like a Bearer token
+ * { id: 'bearer-token', valuePattern: /^Bearer\s+\S+$/ }
+ *
+ * // Redact only when both match
+ * { id: 'api-key', key: /^x-api-key$/i, valuePattern: /^[A-Za-z0-9]{32,}$/ }
+ * ```
+ */
+export interface RedactPattern {
+    /**
+     * REQUIRED. Unique identifier for this pattern.
+     * Used in summary output, warnings, and the dry-run log.
+     */
+    id: string;
+    /** Optional human-readable description of why this is being redacted. */
+    description?: string;
+    /**
+     * Match against the field/key name (header name, body property, query param name).
+     *
+     * - `string`: exact case-insensitive match
+     * - `RegExp`: tested against the key string
+     *
+     * At least one of `key` or {@link valuePattern} must be provided.
+     */
+    key?: string | RegExp;
+    /**
+     * Match against the field value. When provided alongside {@link key},
+     * **both** must match for redaction to apply (AND logic).
+     */
+    valuePattern?: RegExp;
+    /**
+     * Severity level — informational only, used for filtering in summary output.
+     * Does not affect whether redaction runs.
+     */
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+}
+/**
+ * Configuration for the step-removal pipeline.
+ *
+ * Rules are loaded from `ruleFiles` first, then merged with inline `rules`.
+ * Duplicate labels result in a warning; the last definition wins.
+ */
+export interface RemoveConfig {
+    /**
+     * Path(s) to external step rule files (.ts, .js, .json).
+     * Merged with inline `rules`. No built-in rules apply.
+     */
+    ruleFiles?: string | string[];
+    /**
+     * Inline step removal rules. Merged with ruleFiles.
+     * These are the only rules that will ever be applied.
+     */
+    rules?: RemoveRule[];
+    /**
+     * How to redistribute time after a step is deleted.
+     *
+     * - `'absorb-into-prev'` *(default)*: the preceding step's `endTime` absorbs the deleted duration.
+     * - `'absorb-into-next'`: the following step's `startTime` is shifted back.
+     * - `'gap'`: timestamps are not adjusted; a visible gap appears in the timeline.
+     */
+    timestampStrategy?: TimestampStrategy;
+    /**
+     * When `true`: log what would be removed per rule, but do not write any files.
+     * Default: `false`
+     */
+    dryRun?: boolean;
+    /**
+     * What to do with child steps when a parent step is removed.
+     *
+     * - `'remove-children'` *(default)*: also remove all descendant steps.
+     * - `'keep-shell'`: keep the parent as a no-op container without its children.
+     */
+    orphanStrategy?: 'remove-children' | 'keep-shell';
+}
+/**
+ * Controls how the timestamp timeline is repaired after step removal.
+ *
+ * @see {@link RemoveConfig.timestampStrategy}
+ */
+export type TimestampStrategy = 'absorb-into-prev' | 'absorb-into-next' | 'gap';
+/**
+ * A single step-matching rule used by the removal pipeline.
+ *
+ * At least one of {@link stepName}, {@link selector}, {@link url}, or
+ * {@link actionType} must be provided. When multiple matchers are set,
+ * **all** must match (AND logic) for a step to be removed.
+ *
+ * @example
+ * ```ts
+ * // Remove all "waitForTimeout" steps
+ * { label: 'timeouts', stepName: /waitForTimeout/ }
+ *
+ * // Remove network requests to a specific polling endpoint
+ * { label: 'health-poll', url: /\/api\/health$/, actionType: 'route' }
+ *
+ * // Safety guard: only remove if seen 5+ times consecutively
+ * { label: 'scroll-noise', actionType: 'scroll', minConsecutiveOccurrences: 5 }
+ * ```
+ */
+export interface RemoveRule {
+    /**
+     * REQUIRED. Human-readable label for this rule.
+     * Used in summary output, dry-run logs, and safety-guard warnings.
+     */
+    label: string;
+    /**
+     * Match against the step/action name as shown in the HTML report.
+     *
+     * - `string`: case-sensitive substring match
+     * - `RegExp`: tested against the step title, action, or method name
+     */
+    stepName?: string | RegExp;
+    /**
+     * Match against the CSS selector or XPath locator of a UI step.
+     *
+     * - `string`: case-sensitive substring match
+     * - `RegExp`: tested against the selector string
+     */
+    selector?: string | RegExp;
+    /**
+     * Match against the URL of a network request step.
+     *
+     * - `string`: case-sensitive substring match
+     * - `RegExp`: tested against the URL string
+     */
+    url?: string | RegExp;
+    /**
+     * Match against the Playwright internal action type from `trace.json`
+     * (e.g. `'click'`, `'fill'`, `'route'`, `'waitForSelector'`).
+     *
+     * - `string`: case-sensitive substring match
+     * - `RegExp`: tested against the action type string
+     */
+    actionType?: string | RegExp;
+    /**
+     * **SAFETY GUARD** — not an automatic detection threshold.
+     *
+     * Only remove a matching step if it appears **at least this many times
+     * consecutively** within a single test run. If the actual consecutive count
+     * is below this threshold, the tool **skips removal** and emits a warning.
+     *
+     * Use this to protect against accidentally removing legitimate one-off
+     * occurrences of a step that also appears in noisy repeating sequences.
+     */
+    minConsecutiveOccurrences?: number;
+}
+/**
+ * Controls where sanitized files are written and which file types are processed.
+ */
+export interface OutputConfig {
+    /** Directory containing Playwright HTML report files. Default: `'./playwright-report'` */
+    reportDir?: string;
+    /** Directory containing Playwright test result trace files. Default: `'./test-results'` */
+    traceDir?: string;
+    /**
+     * Output mode.
+     *
+     * - `'copy'` *(default)*: write sanitized files to {@link dir}, originals untouched.
+     * - `'in-place'`: overwrite original files (**destructive** — ensure version control).
+     * - `'side-by-side'`: write `<name>.sanitized.<ext>` next to each original.
+     */
+    mode?: 'copy' | 'in-place' | 'side-by-side';
+    /** Destination directory when {@link mode} is `'copy'`. Default: `'./sanitized-report'` */
+    dir?: string;
+    /** Whether to process HTML reports. Default: `true` */
+    processReports?: boolean;
+    /** Whether to process trace `.zip` files. Default: `true` */
+    processTraces?: boolean;
+    /**
+     * Whether to attempt screenshot redaction in trace files.
+     * Requires the optional `sharp` peer dependency.
+     * Default: `false`
+     */
+    redactScreenshots?: boolean;
+}
+/**
+ * Controls summary output and log verbosity.
+ */
+export interface ReportingConfig {
+    /** Print a summary table to stdout after processing. Default: `true` */
+    summary?: boolean;
+    /** Write the summary as JSON to this file path. Optional. */
+    summaryFile?: string;
+    /**
+     * Log verbosity level.
+     *
+     * - `'silent'` — no output at all
+     * - `'normal'` — info, warnings, and errors (default)
+     * - `'verbose'` — everything including per-step traces
+     */
+    logLevel?: 'silent' | 'normal' | 'verbose';
+}
+/**
+ * A single event entry from a Playwright `trace.json` or HTML report step list.
+ *
+ * Fields are a superset of what Playwright may emit — not all fields are present
+ * on every event type. Extra fields are preserved via the index signature.
+ */
+export interface TraceEvent {
+    /** Playwright internal event type (e.g. `'action'`, `'event'`). */
+    type?: string;
+    /** Human-readable action name (e.g. `'click'`, `'fill'`). */
+    action?: string;
+    /** API method name for protocol-level events. */
+    method?: string;
+    /** Arbitrary parameters attached to the event. */
+    params?: Record<string, unknown>;
+    /** Unix timestamp (ms) when the event started. */
+    startTime: number;
+    /** Unix timestamp (ms) when the event ended. */
+    endTime: number;
+    /** Display title shown in the Playwright report UI. */
+    title?: string;
+    /** CSS selector or XPath locator targeted by the action. */
+    selector?: string;
+    /** URL associated with a network request step. */
+    url?: string;
+    /** Playwright action type string used for internal classification. */
+    actionType?: string;
+    /** `callId` of the parent step, used to reconstruct the tree hierarchy. */
+    parentId?: string;
+    /** Unique identifier for this step within the trace. */
+    callId?: string;
+    /** Nested child steps (tree representation). */
+    children?: TraceEvent[];
+    /** Network request ID, used to correlate trace steps with `network.json` entries. */
+    requestId?: string;
+    /** Catch-all for any additional fields Playwright may add. */
+    [key: string]: unknown;
+}
+/**
+ * Result of attempting to redact a single string value.
+ */
+export interface RedactionResult {
+    /** `true` if a pattern matched and the value was replaced. */
+    redacted: boolean;
+    /** The (potentially replaced) value. Equal to the input when `redacted` is `false`. */
+    value: string;
+    /** ID of the pattern that triggered redaction. `undefined` when `redacted` is `false`. */
+    matchedPatternId?: string;
+}
+/**
+ * Records where a redaction occurred within the JSON tree.
+ */
+export interface RedactionMatch {
+    /** Dot-notation path to the redacted field (e.g. `'request.headers.authorization'`). */
+    keyPath: string;
+    /** ID of the {@link RedactPattern} that matched. */
+    patternId: string;
+}
+/**
+ * Aggregated result from a full `walkAndRedact` traversal.
+ */
+export interface WalkResult {
+    /** The transformed JSON tree (new object, input is never mutated). */
+    result: unknown;
+    /** Total number of individual values that were redacted. */
+    count: number;
+    /** Detailed list of every redaction that occurred. */
+    matches: RedactionMatch[];
+}
+/**
+ * A single step that was matched by a removal rule.
+ */
+export interface StepMatch {
+    /** Zero-based index of the step in the flat events array. */
+    index: number;
+    /** Label of the {@link RemoveRule} that matched this step. */
+    ruleLabel: string;
+    /** The matched {@link TraceEvent} object. */
+    event: TraceEvent;
+}
+/**
+ * The set of steps identified for removal across all rules.
+ */
+export interface RemovalSet {
+    /** Deduplicated set of event indices to remove. */
+    indices: Set<number>;
+    /** Detailed list of every match (one entry per step per rule). */
+    matches: StepMatch[];
+}
+/**
+ * Processing result for a single file (HTML report or trace `.zip`).
+ */
+export interface ProcessResult {
+    /** Absolute path of the input file. */
+    file: string;
+    /** Number of individual value redactions applied. */
+    redactionsApplied: number;
+    /** Number of top-level steps removed (children excluded from count). */
+    stepsRemoved: number;
+    /** Number of timestamp adjustments made after step removal. */
+    timestampRepairs: number;
+    /** Detailed list of every redaction match. */
+    redactionMatches: RedactionMatch[];
+    /** Detailed list of every step-removal match. */
+    removalMatches: StepMatch[];
+}
+/**
+ * Aggregated statistics produced after processing all files.
+ * Returned by {@link generateSummary} and optionally written to disk as JSON.
+ */
+export interface SanitizationSummary {
+    /** ISO-8601 timestamp of when processing completed. */
+    processedAt: string;
+    /** Count of HTML reports and trace files processed. */
+    filesProcessed: {
+        reports: number;
+        traces: number;
+    };
+    /** Redaction statistics. */
+    redact: {
+        /** Number of distinct patterns that were loaded. */
+        patternsLoaded: number;
+        /** Total number of value occurrences replaced across all files. */
+        totalOccurrencesReplaced: number;
+        /** Per-pattern occurrence counts, keyed by pattern `id`. */
+        byPatternId: Record<string, number>;
+    };
+    /** Step-removal statistics. */
+    remove: {
+        /** Number of distinct rules that were loaded. */
+        rulesLoaded: number;
+        /** Total number of steps deleted across all files. */
+        totalStepsDeleted: number;
+        /** Number of timestamp adjustments applied. */
+        timestampRepairs: number;
+        /** The {@link TimestampStrategy} that was used. */
+        timestampStrategy: string;
+        /** Per-rule removal counts. */
+        byRuleLabel: Array<{
+            label: string;
+            count: number;
+            files: number;
+        }>;
+        /** Safety-guard warning messages emitted during processing. */
+        safetyGuardWarnings: string[];
+    };
+    /** Output mode and destination directory. */
+    output: {
+        mode: string;
+        dir: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/config/types.d.ts.map

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

package/dist/config/types.js

@@ -0,0 +1,6 @@
+"use strict";
+// ─────────────────────────────────────────────
+// Top-level config
+// ─────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":";AAAA,gDAAgD;AAChD,mBAAmB;AACnB,gDAAgD"}

package/dist/config/validator.d.ts

@@ -0,0 +1,34 @@
+import type { SanitizerConfig, RedactPattern, RemoveRule } from './types.js';
+/**
+ * Validates that the config is structurally correct and has meaningful content.
+ *
+ * Checks that at least one of `redact` or `remove` contains actionable
+ * patterns / rules, then validates each pattern and rule individually.
+ * Any violation calls `logger.fatal` which throws immediately.
+ *
+ * @param config - The {@link SanitizerConfig} to validate.
+ * @throws Calls `logger.fatal` (which throws) for any validation failure.
+ */
+export declare function validateConfig(config: SanitizerConfig): void;
+/**
+ * Validates a single {@link RedactPattern}.
+ *
+ * Ensures that at least one of `key` or `valuePattern` is defined — a pattern
+ * with neither matcher would match nothing and is almost certainly a mistake.
+ *
+ * @param pattern - The pattern to validate.
+ * @throws Calls `logger.fatal` (which throws) if the pattern has no matchers.
+ */
+export declare function validatePattern(pattern: RedactPattern): void;
+/**
+ * Validates a single {@link RemoveRule}.
+ *
+ * Ensures that at least one matcher field (`stepName`, `selector`, `url`, or
+ * `actionType`) is defined — a rule with no matchers would match every step,
+ * which is almost certainly unintentional.
+ *
+ * @param rule - The rule to validate.
+ * @throws Calls `logger.fatal` (which throws) if the rule has no matchers.
+ */
+export declare function validateRule(rule: RemoveRule): void;
+//# sourceMappingURL=validator.d.ts.map

package/dist/config/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/config/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7E;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAqB5D;AA4CD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAM5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAMnD"}