tether-ui 0.3.0 → 0.4.0

package/dist/cli/index.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
+import { persistedConfig, safeUrl } from "../utils/scenarios.js";
 import { readContract } from "../contract/read.js";
-import { validateScopes } from "../contract/scopes.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";
@@ -18,21 +22,26 @@ import { categories, } from "../types.js";
 const program = new Command()
     .name("tether")
     .description("Visual linting for AI-coded interfaces.")
-    .version("0.3.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) {
@@ -64,20 +73,21 @@ 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, 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 visual deviations are visible in tether report.`);
@@ -103,24 +113,17 @@ program
         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;
-    if (JSON.stringify(validateScopes(config.scopes ?? [])) !==
-        JSON.stringify(validateScopes(contract.scopes ?? [])))
-        throw new Error("Component scopes or overrides changed since the baseline. Run tether init --force to establish the new contract.");
-    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)
@@ -142,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,6 +13,23 @@ export declare function jsonReport(report: Report, baseline: Scan): {
         };
     };
     findings: {
+        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;
@@ -20,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;
@@ -29,13 +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,51 +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,
-            ...(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,
-            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/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;

package/dist/drift/compare.js

@@ -1,3 +1,4 @@
+import { safeUrl } from "../utils/scenarios.js";
 import { resolveRule } from "../contract/scopes.js";
 import { createHash } from "node:crypto";
 import { baselineMatcher } from "../scanner/identity.js";
@@ -42,37 +43,42 @@ function equivalent(category, a, b) {
         /^-?[\d.]+px$/.test(b) &&
         Math.abs(parseFloat(a) - parseFloat(b)) <= 0.25);
 }
-export function compare(contract, baseline, current) {
-    const issues = new Map();
+/** Atomic observations are retained until approval matching is complete. */
+export function collectOccurrences(contract, baseline, current) {
+    const occurrences = [];
+    let identities = new Map(), selectors = new Map();
+    let state = "default";
+    let documentOverflowUnique = false, completeSnapshot = true;
     function push(issue, viewport) {
-        const key = [
-            issue.category,
-            issue.route,
-            issue.identity ?? issue.selector,
-            issue.current,
-            issue.title,
-        ]
-            .concat(issue.rule ? [issue.property, JSON.stringify(issue.rule)] : [])
-            .join("\0");
-        const previous = issues.get(key);
-        if (previous) {
-            if (!previous.viewports.includes(viewport))
-                previous.viewports.push(viewport);
-            for (const evidence of issue.evidence ?? [])
-                if (!previous.evidence?.some((e) => e.viewport.name === evidence.viewport.name))
-                    previous.evidence?.push(evidence);
-            if (!previous.property.split(", ").includes(issue.property))
-                previous.property += `, ${issue.property}`;
-        }
-        else
-            issues.set(key, {
-                ...issue,
-                id: createHash("sha256").update(key).digest("hex").slice(0, 12),
-                viewports: [viewport],
-            });
+        occurrences.push({
+            issue: { ...issue, ...(state !== "default" ? { state } : {}) },
+            viewport,
+            state,
+            identityUnique: completeSnapshot &&
+                issue.identityConfidence === "high" &&
+                identities.get(issue.identity ?? "") === 1,
+            selectorUnique: completeSnapshot &&
+                (selectors.get(issue.selector) === 1 ||
+                    (issue.category === "layout" &&
+                        issue.selector === "html" &&
+                        issue.property === "overflow" &&
+                        documentOverflowUnique)),
+        });
     }
     for (const snapshot of current.snapshots) {
-        const previousSnapshot = baseline.snapshots.find((s) => s.route === snapshot.route &&
+        state = snapshot.state ?? "default";
+        completeSnapshot = !snapshot.truncated;
+        identities = new Map();
+        selectors = new Map();
+        for (const element of snapshot.elements) {
+            if (element.identity)
+                identities.set(element.identity, (identities.get(element.identity) ?? 0) + 1);
+            selectors.set(element.selector, (selectors.get(element.selector) ?? 0) + 1);
+        }
+        documentOverflowUnique =
+            snapshot.layout.filter((p) => p.selector === "html" && p.kind === "overflow").length === 1;
+        const previousSnapshot = baseline.snapshots.find((s) => safeUrl(s.route) === safeUrl(snapshot.route) &&
+            (s.state ?? "default") === state &&
             s.viewport.name === snapshot.viewport.name &&
             s.viewport.width === snapshot.viewport.width &&
             s.viewport.height === snapshot.viewport.height);
@@ -107,7 +113,7 @@ export function compare(contract, baseline, current) {
                     current: o.value,
                     expected,
                     route: snapshot.route,
-                }, snapshot.viewport.name);
+                }, snapshot.viewport);
             }
         }
         for (const problem of snapshot.layout) {
@@ -130,9 +136,45 @@ export function compare(contract, baseline, current) {
                 current: problem.value,
                 expected: ["Content fits within the viewport"],
                 route: snapshot.route,
-            }, snapshot.viewport.name);
+            }, snapshot.viewport);
+        }
+    }
+    return occurrences;
+}
+export function groupOccurrences(contract, occurrences) {
+    const issues = new Map();
+    function push(issue, viewport) {
+        const key = [
+            issue.category,
+            issue.route,
+            issue.identity ?? issue.selector,
+            issue.current,
+            issue.title,
+        ]
+            .concat(issue.state && issue.state !== "default" ? [issue.state] : [])
+            .concat(issue.rule ? [issue.property, JSON.stringify(issue.rule)] : [])
+            .concat(issue.approval ? [issue.property, issue.approval.id] : [])
+            .join("\0");
+        const previous = issues.get(key);
+        if (previous) {
+            if (!previous.viewports.includes(viewport))
+                previous.viewports.push(viewport);
+            for (const evidence of issue.evidence ?? [])
+                if (!previous.evidence?.some((e) => e.viewport.name === evidence.viewport.name))
+                    previous.evidence?.push(evidence);
+            if (!previous.property.split(", ").includes(issue.property))
+                previous.property += `, ${issue.property}`;
         }
+        else
+            issues.set(key, {
+                ...issue,
+                ...(issue.evidence ? { evidence: [...issue.evidence] } : {}),
+                id: createHash("sha256").update(key).digest("hex").slice(0, 12),
+                viewports: [viewport],
+            });
     }
+    for (const occurrence of occurrences)
+        push(occurrence.issue, occurrence.viewport.name);
     const rank = { high: 0, medium: 1, low: 2 };
     if (contract.version === 2)
         for (const issue of issues.values()) {
@@ -142,6 +184,7 @@ export function compare(contract, baseline, current) {
     return [...issues.values()].sort((a, b) => rank[a.severity] - rank[b.severity] ||
         a.category.localeCompare(b.category) ||
         a.route.localeCompare(b.route) ||
+        (a.state ?? "default").localeCompare(b.state ?? "default") ||
         (a.identity ?? a.selector).localeCompare(b.identity ?? b.selector) ||
         a.current.localeCompare(b.current) ||
         (contract.version === 2
@@ -149,6 +192,9 @@ export function compare(contract, baseline, current) {
                 JSON.stringify(a.rule ?? null).localeCompare(JSON.stringify(b.rule ?? null))
             : 0));
 }
+export function compare(contract, baseline, current) {
+    return groupOccurrences(contract, collectOccurrences(contract, baseline, current));
+}
 export function consistencyScore(issues) {
     return Math.max(0, 100 -
         issues.reduce((sum, i) => sum + { high: 8, medium: 4, low: 2 }[i.severity], 0));

package/dist/drift/evidence.js

@@ -24,6 +24,7 @@ export function visibleBounds(bounds, viewport) {
 export function findingEvidence(current, baseline, element, prior) {
     return {
         viewport: current.viewport,
+        ...(current.state ? { state: current.state } : {}),
         current: {
             screenshot: current.screenshot,
             ...(element?.bounds ? { bounds: element.bounds } : {}),

package/dist/scanner/collect.d.ts

@@ -1,10 +1,11 @@
 import type { CollectedElement } from "./identity.js";
 import type { LayoutProblem, ScopeDefinition } from "../types.js";
 /** Pure DOM reader, serialized by Playwright into the page. */
-export declare function collect({ maxElements, ignore, scopes, }: {
+export declare function collect({ maxElements, ignore, scopes, sensitiveSelectors, }: {
     maxElements: number;
     ignore: string[];
     scopes?: ScopeDefinition[];
+    sensitiveSelectors?: string[];
 }): {
     elements: CollectedElement[];
     layout: LayoutProblem[];

package/dist/scanner/collect.js

@@ -1,5 +1,5 @@
 /** Pure DOM reader, serialized by Playwright into the page. */
-export function collect({ maxElements, ignore, scopes = [], }) {
+export function collect({ maxElements, ignore, scopes = [], sensitiveSelectors = [], }) {
     for (const selector of ignore) {
         try {
             document.querySelector(selector);
@@ -8,6 +8,16 @@ export function collect({ maxElements, ignore, scopes = [], }) {
             throw new Error(`Invalid ignore selector: ${selector}`);
         }
     }
+    const sensitive = sensitiveSelectors.flatMap((selector) => [
+        ...document.querySelectorAll(selector),
+    ]);
+    function privateElement(el) {
+        return (sensitive.some((s) => s.contains(el) || el.contains(s)) ||
+            (el.getAttribute("aria-labelledby") ?? "").split(/\s+/).some((id) => {
+                const label = document.getElementById(id);
+                return (label && sensitive.some((s) => s.contains(label) || label.contains(s)));
+            }));
+    }
     // Validate declarations even when the page contains no matching elements.
     for (const scope of scopes) {
         for (const selector of [
@@ -79,6 +89,8 @@ export function collect({ maxElements, ignore, scopes = [], }) {
             .join("");
     }
     function selectorFor(el) {
+        if (privateElement(el))
+            return structureFor(el);
         if (el.id && document.querySelectorAll(`#${escapeCss(el.id)}`).length === 1)
             return `#${escapeCss(el.id)}`;
         const testid = el.getAttribute("data-testid");
@@ -211,9 +223,9 @@ export function collect({ maxElements, ignore, scopes = [], }) {
             observations,
             bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
             signals: {
-                attributes,
-                text: el.textContent ?? "",
-                classes: [...el.classList],
+                attributes: privateElement(el) ? {} : attributes,
+                text: privateElement(el) ? "" : (el.textContent ?? ""),
+                classes: privateElement(el) ? [] : [...el.classList],
                 structure: structureFor(el),
             },
         });