tether-ui 0.2.0 → 0.4.0

package/dist/cli/index.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+import { persistedConfig, safeUrl } from "../utils/scenarios.js";
+import { readContract } from "../contract/read.js";
+import { validateCoverage } from "../utils/coverage.js";
+import { approvalCommands } from "./approvals.js";
+import { readApprovals } from "../approvals/storage.js";
+import { applyApprovals } from "../approvals/match.js";
 import { Command } from "commander";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -16,21 +22,26 @@ import { categories, } from "../types.js";
 const program = new Command()
     .name("tether")
     .description("Visual linting for AI-coded interfaces.")
-    .version("0.2.0");
+    .version("0.4.0");
 program.option("--cwd <directory>", "Project directory", process.cwd());
 const cwd = () => resolve(program.opts().cwd);
 const directory = () => join(cwd(), ".tether");
-function reportFor(contract, baseline, current) {
-    const issues = compare(contract, baseline, current);
+function reportFor(contract, baseline, current, file) {
+    const result = file
+        ? applyApprovals(contract, baseline, current, file)
+        : { issues: compare(contract, baseline, current) };
+    const { issues } = result;
+    const approvals = "approvals" in result ? result.approvals : undefined;
     return {
-        version: 1,
+        version: approvals ? 2 : 1,
+        ...(approvals ? { approvals } : {}),
         baselineAt: baseline.createdAt,
         scan: current,
         contract,
         issues,
         score: consistencyScore(issues),
         elementCount: current.snapshots.reduce((n, s) => n + s.elements.length, 0),
-        agentMarkdown: agentMarkdown(issues),
+        agentMarkdown: agentMarkdown(issues, approvals),
     };
 }
 function warnTruncated(report) {
@@ -62,23 +73,24 @@ program
             prompt.close();
         }
     }
+    const approvalFile = await readApprovals(cwd());
     const config = await loadConfig(cwd(), options.url, options.config);
-    console.log(`\ntether\n\nScanning ${config.url}…`);
+    console.log(`\ntether\n\nScanning ${safeUrl(config.url)}…`);
     const baseline = await scan(config, directory(), `baseline-${randomUUID().slice(0, 8)}`);
-    const contract = inferContract(baseline, config.minOccurrences);
+    const contract = inferContract(baseline, config.minOccurrences, config.scopes);
     // Save the exact scan configuration in the baseline so subsequent checks match it.
     await writeJson(join(directory(), "contract.json"), contract);
     await writeJson(join(directory(), "baseline.json"), {
         ...baseline,
-        config,
+        config: persistedConfig(config),
     });
-    const report = reportFor(contract, baseline, baseline);
+    const report = reportFor(contract, baseline, baseline, approvalFile);
     await writeJson(join(directory(), "report.json"), report);
     if (!(await exists(join(cwd(), "tether.config.ts"))) && !options.config)
-        await writeFile(join(cwd(), "tether.config.ts"), `export default ${JSON.stringify(config, null, 2)};\n`);
+        await writeFile(join(cwd(), "tether.config.ts"), `export default ${JSON.stringify(persistedConfig(config), null, 2).replace(JSON.stringify(safeUrl(config.url)), safeUrl(config.url) !== config.url ? "process.env.TETHER_URL" : JSON.stringify(config.url))};\n`);
     console.log(`\n✓ Baseline saved\n✓ ${categories.reduce((n, c) => n + contract[c].length, 0)} tokens in your visual contract\n✓ ${report.elementCount} elements inspected across ${baseline.snapshots.length} snapshots\n\nRun: tether check\n`);
     if (report.issues.length)
-        console.log(`Note: ${report.issues.length} existing layout problems are visible in tether report.`);
+        console.log(`Note: ${report.issues.length} existing visual deviations are visible in tether report.`);
     warnTruncated(report);
 });
 program
@@ -94,28 +106,24 @@ program
     if (!(await exists(join(directory(), "baseline.json"))))
         throw new Error("No baseline found. Run tether init first.");
     const baseline = await readJson(join(directory(), "baseline.json"));
-    const contract = await readJson(join(directory(), "contract.json"));
+    const contract = readContract(await readJson(join(directory(), "contract.json")));
     if (baseline.version !== 1 ||
         !Array.isArray(baseline.snapshots) ||
-        contract.version !== 1 ||
+        ![1, 2].includes(contract.version) ||
         categories.some((c) => !Array.isArray(contract[c]) ||
             contract[c].some((t) => typeof t.value !== "string")))
         throw new Error("Unsupported or invalid baseline / contract. Run tether init --force to recreate it.");
+    const approvalFile = await readApprovals(cwd());
     const config = await loadConfig(cwd(), options.url, options.config);
     if (!options.url &&
         !options.config &&
         !(await exists(join(cwd(), "tether.config.ts"))))
         config.url = baseline.url;
-    const coverage = (s) => `${s.route}|${s.viewport.name}|${s.viewport.width}|${s.viewport.height}`;
-    const baselineCoverage = new Set(baseline.snapshots.map(coverage));
-    const requested = config.routes.flatMap((route) => config.viewports.map((viewport) => coverage({ route, viewport })));
-    if (requested.length !== baselineCoverage.size ||
-        requested.some((k) => !baselineCoverage.has(k)))
-        throw new Error("Routes or viewports changed since the baseline. Run tether init --force to establish the new coverage.");
+    validateCoverage(config, contract, baseline);
     if (!options.agent && !options.json)
-        console.log(`\nScanning ${config.url}…\n`);
+        console.log(`\nScanning ${safeUrl(config.url)}…\n`);
     const current = await scan(config, directory(), `scan-${randomUUID().slice(0, 8)}`);
-    const report = reportFor(contract, baseline, current);
+    const report = reportFor(contract, baseline, current, approvalFile);
     await writeJson(join(directory(), "report.json"), report);
     console.log(options.json
         ? JSON.stringify(jsonReport(report, baseline), null, 2)
@@ -137,6 +145,7 @@ program
         throw new Error("Port must be 0 or an integer between 1024 and 65535.");
     await serveReport(directory(), port, options.open);
 });
+approvalCommands(program, cwd);
 program.parseAsync().catch((error) => {
     console.error(`\ntether: ${error.message}\n`);
     process.exitCode = 2;

package/dist/cli/json.d.ts

@@ -2,7 +2,7 @@ import { type Report, type Scan } from "../types.js";
 /** Screenshot references are local JSON pointers, not random scan directory names. */
 export declare function jsonReport(report: Report, baseline: Scan): {
     schema: string;
-    version: number;
+    version: 1;
     summary: {
         total: number;
         severity: {
@@ -13,7 +13,23 @@ export declare function jsonReport(report: Report, baseline: Scan): {
         };
     };
     findings: {
-        id: string;
+        viewports: string[];
+        property: string;
+        current: string;
+        expected: string[];
+        evidence: {
+            baseline?: {
+                bounds?: import("../types.js").Bounds | undefined;
+                screenshotRef: string | null;
+            } | undefined;
+            current: {
+                bounds?: import("../types.js").Bounds | undefined;
+                screenshotRef: string | null;
+            };
+            state?: string | undefined;
+            viewport: import("../types.js").Viewport;
+        }[];
+        state?: string | undefined;
         identity: string;
         identityConfidence: import("../types.js").IdentityConfidence;
         selector: string;
@@ -21,6 +37,37 @@ export declare function jsonReport(report: Report, baseline: Scan): {
         category: "colors" | "fontFamilies" | "fontSizes" | "fontWeights" | "lineHeights" | "spacing" | "radii" | "shadows" | "borders" | "elementHeights" | "layout";
         severity: import("../types.js").Severity;
         route: string;
+        rule?: import("../types.js").RuleProvenance | undefined;
+        id: string;
+    }[];
+    staleApprovals?: undefined;
+} | {
+    schema: string;
+    version: 2;
+    summary: {
+        total: number;
+        active: {
+            total: number;
+            severity: {
+                [k: string]: number;
+            };
+            category: {
+                [k: string]: number;
+            };
+        };
+        approved: {
+            total: number;
+            severity: {
+                [k: string]: number;
+            };
+            category: {
+                [k: string]: number;
+            };
+        };
+        staleApprovals: number;
+    };
+    findings: {
+        status: string;
         viewports: string[];
         property: string;
         current: string;
@@ -30,11 +77,23 @@ export declare function jsonReport(report: Report, baseline: Scan): {
                 bounds?: import("../types.js").Bounds | undefined;
                 screenshotRef: string | null;
             } | undefined;
-            viewport: import("../types.js").Viewport;
             current: {
                 bounds?: import("../types.js").Bounds | undefined;
                 screenshotRef: string | null;
             };
+            state?: string | undefined;
+            viewport: import("../types.js").Viewport;
         }[];
+        state?: string | undefined;
+        identity: string;
+        identityConfidence: import("../types.js").IdentityConfidence;
+        selector: string;
+        title: string;
+        category: "colors" | "fontFamilies" | "fontSizes" | "fontWeights" | "lineHeights" | "spacing" | "radii" | "shadows" | "borders" | "elementHeights" | "layout";
+        severity: import("../types.js").Severity;
+        route: string;
+        rule?: import("../types.js").RuleProvenance | undefined;
+        id: string;
     }[];
+    staleApprovals: import("../types.js").Approval[];
 };

package/dist/cli/json.js

@@ -9,50 +9,76 @@ export function jsonReport(report, baseline) {
                 (file === "report.json" ? "scan/" : "") +
                 `snapshots/${index}/screenshot`;
     };
+    const finding = (i) => ({
+        id: i.id,
+        ...(i.rule ? { rule: i.rule } : {}),
+        identity: i.identity ?? `selector:${i.selector}`,
+        identityConfidence: i.identityConfidence ?? "low",
+        selector: i.selector,
+        title: i.title,
+        category: i.category,
+        severity: i.severity,
+        route: i.route,
+        ...(i.state ? { state: i.state } : {}),
+        viewports: [...i.viewports].sort(),
+        property: i.property,
+        current: i.current,
+        expected: [...i.expected].sort(),
+        evidence: [...(i.evidence ?? [])]
+            .sort((a, b) => a.viewport.name.localeCompare(b.viewport.name))
+            .map((e) => ({
+            viewport: e.viewport,
+            ...(e.state ? { state: e.state } : {}),
+            current: {
+                screenshotRef: reference(report.scan, "report.json", e.current.screenshot),
+                ...(e.current.bounds ? { bounds: e.current.bounds } : {}),
+            },
+            ...(e.baseline
+                ? {
+                    baseline: {
+                        screenshotRef: reference(baseline, "baseline.json", e.baseline.screenshot),
+                        ...(e.baseline.bounds ? { bounds: e.baseline.bounds } : {}),
+                    },
+                }
+                : {}),
+        })),
+    });
+    const summary = (issues) => ({
+        total: issues.length,
+        severity: Object.fromEntries(["high", "medium", "low"].map((s) => [
+            s,
+            issues.filter((i) => i.severity === s).length,
+        ])),
+        category: Object.fromEntries([...categories, "layout"].map((c) => [
+            c,
+            issues.filter((i) => i.category === c).length,
+        ])),
+    });
+    if (!report.approvals)
+        return {
+            schema: "tether.check",
+            version: 1,
+            summary: summary(report.issues),
+            findings: report.issues.map(finding),
+        };
+    const approved = report.approvals.approved;
     return {
         schema: "tether.check",
-        version: 1,
+        version: 2,
         summary: {
-            total: report.issues.length,
-            severity: Object.fromEntries(["high", "medium", "low"].map((s) => [
-                s,
-                report.issues.filter((i) => i.severity === s).length,
-            ])),
-            category: Object.fromEntries([...categories, "layout"].map((c) => [
-                c,
-                report.issues.filter((i) => i.category === c).length,
-            ])),
+            total: report.issues.length + approved.length,
+            active: summary(report.issues),
+            approved: summary(approved),
+            staleApprovals: report.approvals.stale.length,
         },
-        findings: report.issues.map((i) => ({
-            id: i.id,
-            identity: i.identity ?? `selector:${i.selector}`,
-            identityConfidence: i.identityConfidence ?? "low",
-            selector: i.selector,
-            title: i.title,
-            category: i.category,
-            severity: i.severity,
-            route: i.route,
-            viewports: [...i.viewports].sort(),
-            property: i.property,
-            current: i.current,
-            expected: [...i.expected].sort(),
-            evidence: [...(i.evidence ?? [])]
-                .sort((a, b) => a.viewport.name.localeCompare(b.viewport.name))
-                .map((e) => ({
-                viewport: e.viewport,
-                current: {
-                    screenshotRef: reference(report.scan, "report.json", e.current.screenshot),
-                    ...(e.current.bounds ? { bounds: e.current.bounds } : {}),
-                },
-                ...(e.baseline
-                    ? {
-                        baseline: {
-                            screenshotRef: reference(baseline, "baseline.json", e.baseline.screenshot),
-                            ...(e.baseline.bounds ? { bounds: e.baseline.bounds } : {}),
-                        },
-                    }
-                    : {}),
+        findings: [
+            ...report.issues.map((i) => ({ ...finding(i), status: "active" })),
+            ...approved.map((i) => ({
+                ...finding(i),
+                status: "approved",
+                approval: i.approval,
             })),
-        })),
+        ],
+        staleApprovals: report.approvals.stale,
     };
 }

package/dist/contract/describe.d.ts

@@ -0,0 +1,2 @@
+import type { RuleProvenance } from "../types.js";
+export declare function ruleDescription(rule: RuleProvenance): string;

package/dist/contract/describe.js

@@ -0,0 +1,6 @@
+export function ruleDescription(rule) {
+    const context = rule.scope
+        ? `${rule.scope}${rule.variant ? ` (${rule.variant})` : ""}/${rule.part}`
+        : "unscoped";
+    return `${rule.source} · ${context}${rule.reason ? ` · ${rule.reason}` : ""} · ${rule.samples} component instances · tokens: ${rule.tokens.map((t) => `${t.value} (${t.count})`).join(", ") || "none"}`;
+}

package/dist/contract/infer.d.ts

@@ -1,2 +1,2 @@
-import { type Contract, type Scan } from "../types.js";
-export declare function inferContract(scan: Scan, minOccurrences?: number): Contract;
+import { type Contract, type Scan, type ScopeDefinition } from "../types.js";
+export declare function inferContract(scan: Scan, minOccurrences?: number, scopes?: ScopeDefinition[]): Contract;

package/dist/contract/infer.js

@@ -1,5 +1,6 @@
-import { categories } from "../types.js";
-export function inferContract(scan, minOccurrences = 2) {
+import { validateScopes } from "./scopes.js";
+import { categories, } from "../types.js";
+export function inferContract(scan, minOccurrences = 2, scopes = []) {
     const contract = {
         version: 1,
         createdAt: scan.createdAt,
@@ -23,5 +24,71 @@ export function inferContract(scan, minOccurrences = 2) {
         // A small page still gets one representative token per observed category.
         contract[category] = recurring.length ? recurring : ranked.slice(0, 1);
     }
+    if (scopes.length) {
+        const definitions = validateScopes(scopes);
+        contract.version = 2;
+        contract.scopes = definitions;
+        contract.partial = scan.snapshots.some((s) => s.truncated);
+        const rules = new Map();
+        const key = (scope, part, category, property) => JSON.stringify([scope, part, category, property]);
+        for (const snapshot of scan.snapshots)
+            for (const element of snapshot.elements) {
+                const scope = element.scope;
+                if (!scope || !definitions.some((d) => d.name === scope.name))
+                    continue;
+                const instance = JSON.stringify([snapshot.route, scope.instance]);
+                for (const o of element.observations) {
+                    const k = key(scope.name, scope.part, o.category, o.property);
+                    const entry = rules.get(k) ?? {
+                        rule: {
+                            scope: scope.name,
+                            part: scope.part,
+                            category: o.category,
+                            property: o.property,
+                            samples: 0,
+                            tokens: [],
+                            source: "scope",
+                        },
+                        samples: new Set(),
+                        values: new Map(),
+                    };
+                    entry.samples.add(instance);
+                    const values = entry.values.get(o.value) ?? new Set();
+                    values.add(instance);
+                    entry.values.set(o.value, values);
+                    rules.set(k, entry);
+                }
+            }
+        for (const scope of definitions)
+            for (const override of scope.overrides ?? []) {
+                const k = key(scope.name, override.part ?? "root", override.category, override.property);
+                const old = rules.get(k);
+                rules.set(k, {
+                    rule: {
+                        scope: scope.name,
+                        part: override.part ?? "root",
+                        category: override.category,
+                        property: override.property,
+                        samples: 0,
+                        tokens: [],
+                        source: "override",
+                    },
+                    samples: old?.samples ?? new Set(),
+                    values: new Map(override.values.map((v) => [
+                        v,
+                        old?.values.get(v) ?? new Set(),
+                    ])),
+                });
+            }
+        contract.rules = [...rules.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([, entry]) => ({
+            ...entry.rule,
+            samples: entry.samples.size,
+            tokens: [...entry.values]
+                .map(([value, instances]) => ({ value, count: instances.size }))
+                .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value)),
+        }));
+    }
     return contract;
 }

package/dist/contract/read.d.ts

@@ -0,0 +1,3 @@
+import { type Contract } from "../types.js";
+/** Validate without rewriting legacy data or changing its ordering. */
+export declare function readContract(input: unknown): Contract;

package/dist/contract/read.js

@@ -0,0 +1,67 @@
+import { categories } from "../types.js";
+import { validateScopes, validProperty } from "./scopes.js";
+/** Validate without rewriting legacy data or changing its ordering. */
+export function readContract(input) {
+    const c = input;
+    const fail = () => {
+        throw new Error("Unsupported or invalid contract. Supported versions: 1 (global), 2 (scoped). Restore a valid contract or run tether init --force.");
+    };
+    const tokens = (t) => Array.isArray(t) &&
+        t.every((v) => v &&
+            typeof v.value === "string" &&
+            Number.isInteger(v.count) &&
+            v.count >= 0);
+    if (!c ||
+        ![1, 2].includes(c.version) ||
+        !Number.isInteger(c.minOccurrences) ||
+        c.minOccurrences < 1 ||
+        c.minOccurrences > 1000 ||
+        categories.some((k) => !tokens(c[k])))
+        fail();
+    if (c.version === 2) {
+        const scopes = validateScopes(c.scopes);
+        if (!scopes.length ||
+            !Array.isArray(c.rules) ||
+            typeof c.partial !== "boolean")
+            fail();
+        const keys = new Set();
+        for (const rule of c.rules) {
+            if (!rule || typeof rule !== "object")
+                fail();
+            const scope = scopes.find((s) => s.name === rule.scope);
+            if (!scope ||
+                (rule.part !== "root" &&
+                    !Object.hasOwn(scope.parts ?? {}, rule.part)) ||
+                !categories.includes(rule.category) ||
+                !validProperty(rule.category, rule.property) ||
+                !["scope", "override"].includes(rule.source) ||
+                !Number.isInteger(rule.samples) ||
+                rule.samples < 0 ||
+                !tokens(rule.tokens) ||
+                rule.tokens.some((t) => t.count > rule.samples))
+                fail();
+            const key = JSON.stringify([
+                rule.scope,
+                rule.part,
+                rule.category,
+                rule.property,
+            ]);
+            if (keys.has(key))
+                fail();
+            keys.add(key);
+            const override = scope.overrides?.find((o) => o.part === rule.part &&
+                o.category === rule.category &&
+                o.property === rule.property);
+            if ((rule.source === "override") !== !!override ||
+                (override &&
+                    JSON.stringify([...override.values].sort()) !==
+                        JSON.stringify(rule.tokens.map((t) => t.value).sort())))
+                fail();
+        }
+        for (const scope of scopes)
+            for (const o of scope.overrides ?? [])
+                if (!keys.has(JSON.stringify([scope.name, o.part, o.category, o.property])))
+                    fail();
+    }
+    return c;
+}

package/dist/contract/scopes.d.ts

@@ -0,0 +1,5 @@
+import { type ScopeDefinition, type Contract, type ElementRecord, type Observation, type RuleProvenance } from "../types.js";
+export declare function validProperty(category: string, property: unknown): property is string;
+/** Canonical, serializable declarations. CSS syntax is checked in the browser. */
+export declare function validateScopes(input: unknown): ScopeDefinition[];
+export declare function resolveRule(contract: Contract, element: ElementRecord, observation: Observation): RuleProvenance | undefined;

package/dist/contract/scopes.js

@@ -0,0 +1,150 @@
+import { categories, } from "../types.js";
+import { normalizeValue } from "../utils/normalize.js";
+const name = (s) => typeof s === "string" && /^[a-zA-Z][\w-]{0,63}$/.test(s);
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const selector = (v) => typeof v === "string" && !!v.trim();
+export function validProperty(category, property) {
+    if (typeof property !== "string")
+        return false;
+    const properties = {
+        colors: /^(color|background-color|border-color)$/,
+        fontFamilies: /^font-family$/,
+        fontSizes: /^font-size$/,
+        fontWeights: /^font-weight$/,
+        lineHeights: /^line-height$/,
+        spacing: /^(padding|margin)-(top|right|bottom|left)$|^(row|column)-gap$/,
+        radii: /^border-radius$/,
+        shadows: /^box-shadow$/,
+        borders: /^border$/,
+        elementHeights: /^height$/,
+    };
+    return !!properties[category]?.test(property);
+}
+/** Canonical, serializable declarations. CSS syntax is checked in the browser. */
+export function validateScopes(input) {
+    if (!Array.isArray(input))
+        throw new Error("Config scopes must be an array.");
+    const names = new Set();
+    const selectors = new Set();
+    const result = [];
+    for (const s of input) {
+        if (!object(s) ||
+            !name(s.name) ||
+            !selector(s.selector) ||
+            names.has(s.name) ||
+            selectors.has(s.selector.trim()))
+            throw new Error("Scopes need unique names and distinct, nonempty CSS selectors.");
+        if (Object.keys(s).some((k) => ![
+            "name",
+            "selector",
+            "variant",
+            "minOccurrences",
+            "parts",
+            "overrides",
+        ].includes(k)))
+            throw new Error(`Unknown setting in scope ${s.name}.`);
+        if (s.variant !== undefined && !name(s.variant))
+            throw new Error(`Invalid variant for scope ${s.name}.`);
+        if (s.minOccurrences !== undefined &&
+            (!Number.isInteger(s.minOccurrences) ||
+                Number(s.minOccurrences) < 2 ||
+                Number(s.minOccurrences) > 1000))
+            throw new Error(`Scope ${s.name} minOccurrences must be between 2 and 1000; use an explicit override for a singleton.`);
+        if (s.parts !== undefined &&
+            (!object(s.parts) ||
+                Object.entries(s.parts).some(([k, v]) => !name(k) || k === "root" || !selector(v))))
+            throw new Error(`Scope ${s.name} parts need names (other than root) and CSS selectors.`);
+        const parts = Object.fromEntries(Object.entries(s.parts ?? {}).sort(([a], [b]) => a.localeCompare(b)));
+        if (new Set(Object.values(parts).map((v) => v.trim())).size !==
+            Object.keys(parts).length)
+            throw new Error(`Duplicate part selectors in ${s.name}.`);
+        if (s.overrides !== undefined && !Array.isArray(s.overrides))
+            throw new Error(`Scope ${s.name} overrides must be an array.`);
+        const keys = new Set();
+        const overrides = [];
+        for (const o of (s.overrides ?? [])) {
+            if (!object(o) ||
+                !categories.includes(o.category) ||
+                !validProperty(String(o.category), o.property) ||
+                !Array.isArray(o.values) ||
+                !o.values.length ||
+                o.values.some((v) => typeof v !== "string" || !v.trim()))
+                throw new Error(`Invalid property, category or values in ${s.name} override.`);
+            if (Object.keys(o).some((k) => !["part", "category", "property", "values"].includes(k)))
+                throw new Error(`Unknown override setting in ${s.name}.`);
+            const part = o.part ?? "root";
+            if (typeof part !== "string" ||
+                (part !== "root" && !Object.hasOwn(parts, part)))
+                throw new Error(`Unknown override part in ${s.name}.`);
+            const key = JSON.stringify([part, o.category, o.property]);
+            if (keys.has(key))
+                throw new Error(`Duplicate override for ${s.name}/${part}/${o.property}.`);
+            keys.add(key);
+            const values = [
+                ...new Set(o.values.map((v) => normalizeValue(o.property, v))),
+            ].sort();
+            if (values.some((v) => ["transparent", "0px", "none", "normal", "auto"].includes(v)))
+                throw new Error(`Override for ${s.name} contains a value the scanner does not collect.`);
+            overrides.push({
+                part,
+                category: o.category,
+                property: o.property,
+                values,
+            });
+        }
+        names.add(s.name);
+        selectors.add(s.selector.trim());
+        result.push({
+            name: s.name,
+            selector: s.selector.trim(),
+            ...(s.variant ? { variant: s.variant } : {}),
+            ...(s.minOccurrences !== undefined
+                ? { minOccurrences: Number(s.minOccurrences) }
+                : {}),
+            parts,
+            overrides: overrides.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+        });
+    }
+    return result.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function resolveRule(contract, element, observation) {
+    if (contract.version === 1)
+        return;
+    const membership = element.scope;
+    const definition = contract.scopes?.find((s) => s.name === membership?.name);
+    const rule = contract.rules?.find((r) => r.scope === membership?.name &&
+        r.part === membership?.part &&
+        r.category === observation.category &&
+        r.property === observation.property);
+    const context = membership
+        ? {
+            scope: membership.name,
+            ...(definition?.variant ? { variant: definition.variant } : {}),
+            part: membership.part,
+        }
+        : {};
+    const threshold = definition?.minOccurrences ?? Math.max(2, contract.minOccurrences);
+    const supported = rule?.tokens.filter((t) => rule.source === "override" || t.count >= threshold) ?? [];
+    if (rule &&
+        supported.length &&
+        (rule.source === "override" || !contract.partial))
+        return {
+            ...context,
+            source: rule.source,
+            samples: rule.samples,
+            tokens: supported,
+        };
+    return {
+        ...context,
+        source: "global",
+        reason: !membership
+            ? "unscoped"
+            : contract.partial
+                ? "partial-baseline"
+                : !rule
+                    ? "missing-rule"
+                    : "insufficient-support",
+        samples: rule?.samples ?? 0,
+        tokens: contract[observation.category],
+    };
+}

package/dist/drift/compare.d.ts

@@ -1,5 +1,8 @@
-import type { Category, Contract, Issue, Scan, Severity } from "../types.js";
+import type { Category, Contract, Issue, Scan, Severity, FindingOccurrence } from "../types.js";
 export declare const labels: Record<Category | "layout", string>;
 export declare function severityFor(category: Category, value: string, expected: string[]): Severity;
+/** Atomic observations are retained until approval matching is complete. */
+export declare function collectOccurrences(contract: Contract, baseline: Scan, current: Scan): FindingOccurrence[];
+export declare function groupOccurrences(contract: Contract, occurrences: FindingOccurrence[]): Issue[];
 export declare function compare(contract: Contract, baseline: Scan, current: Scan): Issue[];
 export declare function consistencyScore(issues: Issue[]): number;