import type { Confidence, FixEffort, RuleResult, Severity } from "../types.js";
/**
 * A bucket of findings sharing the same `(ruleId, templateSignature)` key.
 *
 * Why bucket? On a programmatic-SEO site, a single template bug surfaces as
 * dozens (or thousands) of identical findings — one per generated page. Listing
 * them individually buries the actionable signal under noise. Bucketing
 * collapses them so the operator sees:
 *
 *   "23 instances on /templates/:slug — fix once, resolve all 23"
 *
 * instead of 23 separate finding lines. The bucket key is
 * `${ruleId}::${templateSignature ?? pageUrl ?? "__site__"}`:
 *
 *  - Same rule + same template signature -> ONE bucket with count = N.
 *  - Same rule + different templates -> separate buckets per template.
 *  - Same rule, no pageUrl (site-wide) -> its own `__site__` bucket.
 *  - Same rule + same pageUrl with no template signature -> its own bucket
 *    (count usually 1; counts > 1 collapse harmless duplicates).
 */
export interface BucketedFinding {
    ruleId: string;
    /** Null when the finding is site-wide (no pageUrl) or when no signature could be inferred. */
    templateSignature: string | null;
    count: number;
    representativeUrl: string;
    representativeMessage: string;
    representativeFix?: string;
    representativeDocsUrl?: string;
    severity: Severity;
    effort?: FixEffort;
    /** v0.4.3 — confidence of the representative finding (used for caveat rendering). */
    representativeConfidence?: Confidence;
}
/**
 * Collapse findings that share `(ruleId, templateSignature)` into buckets.
 *
 * Output order: count DESC, then severity DESC (critical > error > warning >
 * info), then effort DESC (quick > moderate > structural), with ruleId as a
 * stable tiebreaker so snapshot tests don't flap.
 */
export declare function bucketByTemplate(findings: RuleResult[]): BucketedFinding[];
//# sourceMappingURL=bucket-findings.d.ts.map