@ksmv/ui-checks 0.1.0

package/dist/governance.js

@@ -0,0 +1,75 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { compareBaseline, validateBaseline } from "./baseline.js";
+import { validateSuppressions } from "./suppressions.js";
+export function resolveReportExitCode(report, failOnUncovered) {
+    if (report.operationalErrors.length > 0 ||
+        report.uncovered.some(({ required }) => required === true) ||
+        (failOnUncovered && report.uncovered.length > 0)) {
+        return 2;
+    }
+    return report.violations.length > 0 ? 1 : 0;
+}
+export function applyConfiguredSuppressions(report, config) {
+    if (config.suppressions === undefined) {
+        return { issues: [], valid: true };
+    }
+    const validation = validateSuppressions(config.suppressions, report.violations);
+    if (validation.exitCode === 2) {
+        report.operationalErrors.push({
+            code: "config",
+            message: "Configured suppressions are invalid.",
+        });
+        return { issues: [], valid: false };
+    }
+    report.suppressions = validation.used;
+    report.violations = [...validation.remaining, ...validation.issues];
+    return { issues: validation.issues, valid: true };
+}
+async function readBaseline(path) {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    const validation = validateBaseline(parsed);
+    if (!validation.baseline) {
+        throw new Error("invalid-baseline");
+    }
+    return validation.baseline;
+}
+export async function applyConfiguredBaseline(report, config, issues) {
+    if (!config.baseline) {
+        return;
+    }
+    try {
+        const path = resolve(config.root ?? process.cwd(), config.baseline);
+        const baseline = await readBaseline(path);
+        const issueSet = new Set(issues);
+        const currentViolations = report.violations.filter((violation) => !issueSet.has(violation));
+        const comparison = compareBaseline(currentViolations, baseline);
+        report.baselineMatches = comparison.baselineMatches;
+        report.baselineDebt = [
+            ...new Set([
+                ...Object.keys(comparison.debtByRule),
+                ...Object.keys(comparison.reducedByRule),
+            ]),
+        ]
+            .sort()
+            .map((rule) => ({
+            active: comparison.debtByRule[rule] ?? 0,
+            reduced: comparison.reducedByRule[rule] ?? 0,
+            rule,
+        }));
+        report.violations = [...comparison.newViolations, ...issues];
+    }
+    catch {
+        report.operationalErrors.push({
+            code: "config",
+            message: "Configured baseline could not be read or validated.",
+        });
+    }
+}
+export async function applyDebtControls(report, config) {
+    const suppressionResult = applyConfiguredSuppressions(report, config);
+    if (suppressionResult.valid) {
+        await applyConfiguredBaseline(report, config, suppressionResult.issues);
+    }
+    report.exitCode = resolveReportExitCode(report, config.failOnUncovered ?? true);
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { defineConfig } from "./config.js";
+export type { ChecksConfig, ComputedEvidenceRef, ThemeConfig } from "./config.js";
+export { parseContrastManifest, parseThemeContract, resolveContractSet, tokenNamePattern, } from "./contracts.js";
+export type { ContractIdentity, ContractSet, ContractSource, ContrastManifest, ContrastPair, ThemeContract, } from "./contracts.js";
+export { computeThemeSourceHash, loadComputedEvidence } from "./evidence.js";
+export type { ThemeEvidence } from "./evidence.js";
+export { formatHumanReport, formatJsonReport } from "./result.js";
+export type { BaselineDebt, CheckReport, ExitCode, IgnoredFile, OperationalError, SourceLocation, Suppression, Uncovered, Violation, } from "./result.js";
+export { approveBaselineGrowth, baselineFor, compareBaseline, fingerprintViolation, normalizeRelativePath, serializeBaseline, validateBaseline, writeBaselineFile, } from "./baseline.js";
+export type { BaselineComparison, BaselineEntry, BaselineFile, BaselineMetadata, BaselineValidation, GrowthApproval, GrowthApprovalOptions, } from "./baseline.js";
+export { validateSuppressions } from "./suppressions.js";
+export type { SuppressionValidation } from "./suppressions.js";
+export { runChecks } from "./scan.js";
+export type { CheckRule, RuleResult, RunChecksOptions, ScannedFile, TypeScriptToken, } from "./scan.js";
+export { createNoLiteralColorRule } from "./rules/noLiteralColor.js";
+export type { NoLiteralColorOptions } from "./rules/noLiteralColor.js";
+export { createDefaultRules } from "./rules/default.js";
+export type { DefaultRulesOptions } from "./rules/default.js";
+export { createTokenPrefixRule } from "./rules/tokenPrefix.js";
+export { createTokenCompleteRule, loadThemeContract, } from "./rules/tokenComplete.js";
+export type { TokenCompleteOptions, } from "./rules/tokenComplete.js";
+export { createTokenContrastRule, loadContrastManifest, } from "./rules/tokenContrast.js";
+export type { TokenContrastOptions, } from "./rules/tokenContrast.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export { defineConfig } from "./config.js";
+export { parseContrastManifest, parseThemeContract, resolveContractSet, tokenNamePattern, } from "./contracts.js";
+export { computeThemeSourceHash, loadComputedEvidence } from "./evidence.js";
+export { formatHumanReport, formatJsonReport } from "./result.js";
+export { approveBaselineGrowth, baselineFor, compareBaseline, fingerprintViolation, normalizeRelativePath, serializeBaseline, validateBaseline, writeBaselineFile, } from "./baseline.js";
+export { validateSuppressions } from "./suppressions.js";
+export { runChecks } from "./scan.js";
+export { createNoLiteralColorRule } from "./rules/noLiteralColor.js";
+export { createDefaultRules } from "./rules/default.js";
+export { createTokenPrefixRule } from "./rules/tokenPrefix.js";
+export { createTokenCompleteRule, loadThemeContract, } from "./rules/tokenComplete.js";
+export { createTokenContrastRule, loadContrastManifest, } from "./rules/tokenContrast.js";

package/dist/result.d.ts

@@ -0,0 +1,65 @@
+export type ExitCode = 0 | 1 | 2;
+export interface SourceLocation {
+    column: number;
+    line: number;
+}
+export interface Violation extends SourceLocation {
+    message: string;
+    nodeKind: string;
+    path: string;
+    rule: string;
+}
+export interface Uncovered extends SourceLocation {
+    message: string;
+    nodeKind: string;
+    path: string;
+    rule: string;
+    required?: boolean;
+}
+export interface Suppression {
+    expires: string;
+    fingerprint: string;
+    ownerRole: string;
+    path: string;
+    reason: string;
+    rule: string;
+}
+export interface IgnoredFile {
+    path: string;
+    reason: "excluded-by-configuration";
+}
+export interface OperationalError {
+    code: "config" | "internal" | "no-files" | "parse" | "read";
+    message: string;
+    path?: string;
+}
+export interface BaselineDebt {
+    active: number;
+    reduced: number;
+    rule: string;
+}
+export interface CheckReport {
+    baselineDebt: BaselineDebt[];
+    baselineMatches: Violation[];
+    declarationsChecked: number;
+    contracts?: {
+        contrast: ContractIdentity;
+        source: ContractSource;
+        theme: ContractIdentity;
+    };
+    durationMs: number;
+    exitCode: ExitCode;
+    filesDiscovered: number;
+    filesIgnored: IgnoredFile[];
+    filesRead: number;
+    nodesChecked: number;
+    operationalErrors: OperationalError[];
+    rulesExecuted: string[];
+    schemaVersion: 1;
+    suppressions: Suppression[];
+    uncovered: Uncovered[];
+    violations: Violation[];
+}
+export declare function formatJsonReport(report: CheckReport): string;
+export declare function formatHumanReport(report: CheckReport): string;
+import type { ContractIdentity, ContractSource } from "./contracts.js";

package/dist/result.js

@@ -0,0 +1,42 @@
+export function formatJsonReport(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function formatHumanReport(report) {
+    const lines = [
+        `Exit code: ${report.exitCode}`,
+        `Files discovered: ${report.filesDiscovered}`,
+        `Files read: ${report.filesRead}`,
+        `Files ignored: ${report.filesIgnored.length}`,
+        `TSX nodes checked: ${report.nodesChecked}`,
+        `CSS declarations checked: ${report.declarationsChecked}`,
+        `Duration: ${report.durationMs}ms`,
+        `Rules executed: ${report.rulesExecuted.length}`,
+        `Violations: ${report.violations.length}`,
+        `Baseline matches: ${report.baselineMatches.length}`,
+        `Uncovered: ${report.uncovered.length}`,
+        `Suppressions: ${report.suppressions.length}`,
+        `Operational errors: ${report.operationalErrors.length}`,
+    ];
+    for (const debt of report.baselineDebt) {
+        lines.push(`Baseline debt ${debt.rule}: active ${debt.active}, reduced ${debt.reduced}`);
+    }
+    for (const rule of report.rulesExecuted) {
+        lines.push(`Rule executed: ${rule}`);
+    }
+    for (const ignored of report.filesIgnored) {
+        lines.push(`Ignored: ${ignored.path} ${ignored.reason}`);
+    }
+    for (const finding of report.baselineMatches) {
+        lines.push(`Baseline match: ${finding.path}:${finding.line}:${finding.column} ${finding.rule}`);
+    }
+    for (const suppression of report.suppressions) {
+        lines.push(`Suppression: ${suppression.path} ${suppression.rule} expires ${suppression.expires}`);
+    }
+    for (const finding of [...report.violations, ...report.uncovered]) {
+        lines.push(`${finding.path}:${finding.line}:${finding.column} ${finding.rule} ${finding.message}`);
+    }
+    for (const error of report.operationalErrors) {
+        lines.push(`${error.path ? `${error.path} ` : ""}${error.code} ${error.message}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/rules/default.d.ts

@@ -0,0 +1,10 @@
+import type { ThemeConfig } from "../config.js";
+import type { ContrastManifest, ThemeContract } from "../contracts.js";
+import type { CheckRule } from "../scan.js";
+export interface DefaultRulesOptions {
+    computed?: Record<string, Record<string, string>>;
+    contract?: ThemeContract;
+    manifest?: ContrastManifest;
+    themes: ThemeConfig[];
+}
+export declare function createDefaultRules({ computed, contract, manifest, themes, }: DefaultRulesOptions): Promise<CheckRule[]>;

package/dist/rules/default.js

@@ -0,0 +1,16 @@
+import { createNoLiteralColorRule } from "./noLiteralColor.js";
+import { createTokenCompleteRule, loadThemeContract } from "./tokenComplete.js";
+import { createTokenContrastRule, loadContrastManifest, } from "./tokenContrast.js";
+import { createTokenPrefixRule } from "./tokenPrefix.js";
+export async function createDefaultRules({ computed, contract, manifest, themes, }) {
+    const [resolvedContract, resolvedManifest] = await Promise.all([
+        contract ?? loadThemeContract(),
+        manifest ?? loadContrastManifest(),
+    ]);
+    return [
+        createNoLiteralColorRule({ themes }),
+        createTokenPrefixRule(),
+        createTokenCompleteRule({ computed, contract: resolvedContract, themes }),
+        createTokenContrastRule({ computed, manifest: resolvedManifest, themes }),
+    ];
+}

package/dist/rules/noLiteralColor.d.ts

@@ -0,0 +1,6 @@
+import type { ThemeConfig } from "../config.js";
+import type { CheckRule } from "../scan.js";
+export interface NoLiteralColorOptions {
+    themes: ThemeConfig[];
+}
+export declare function createNoLiteralColorRule({ themes, }: NoLiteralColorOptions): CheckRule;

package/dist/rules/noLiteralColor.js

@@ -0,0 +1,126 @@
+import { isComputedPropertyName, isIdentifier, isJsxAttribute, isJsxExpression, isObjectLiteralExpression, isPropertyAssignment, isStringLiteralLikeNode, } from "typescript/unstable/ast";
+import { containsLiteralColor, isColorBearingProperty } from "../color.js";
+import { isAllowedThemeDeclaration } from "./theme.js";
+function emptyResult() {
+    return { uncovered: [], violations: [] };
+}
+function propertyName(node) {
+    if (isIdentifier(node) || isStringLiteralLikeNode(node)) {
+        return node.text;
+    }
+    return isComputedPropertyName(node) && isStringLiteralLikeNode(node.expression)
+        ? node.expression.text
+        : undefined;
+}
+function jsxStringValue(node) {
+    if (!node) {
+        return undefined;
+    }
+    if (isStringLiteralLikeNode(node)) {
+        return node.text;
+    }
+    return isJsxExpression(node) &&
+        node.expression &&
+        isStringLiteralLikeNode(node.expression)
+        ? node.expression.text
+        : undefined;
+}
+function classContainsLiteralColor(value) {
+    return [...value.matchAll(/\[([^\]]+)\]/g)].some((match) => {
+        const candidate = match[1] ?? "";
+        const separator = candidate.indexOf(":");
+        if (separator <= 0) {
+            return containsLiteralColor(candidate);
+        }
+        const property = candidate.slice(0, separator);
+        const propertyValue = candidate.slice(separator + 1);
+        const beforeBracket = value.slice(0, match.index ?? 0);
+        const currentClass = beforeBracket.slice(Math.max(beforeBracket.lastIndexOf(" "), beforeBracket.lastIndexOf("\n"), beforeBracket.lastIndexOf("\t")) + 1);
+        const utility = currentClass.split(":").at(-1) ?? "";
+        if (utility.endsWith("-")) {
+            if (property === "color" || property === "image") {
+                return containsLiteralColor(propertyValue);
+            }
+            return (/^(?:accent|bg|border|caret|decoration|divide|fill|from|outline|placeholder|ring|shadow|stroke|text|to|via)-$/.test(utility) && containsLiteralColor(propertyValue));
+        }
+        return (isColorBearingProperty(property) && containsLiteralColor(propertyValue));
+    });
+}
+export function createNoLiteralColorRule({ themes, }) {
+    return {
+        name: "css/no-literal-color",
+        check(file) {
+            const result = emptyResult();
+            file.cssRoot?.walkDecls((declaration) => {
+                if (isColorBearingProperty(declaration.prop) &&
+                    containsLiteralColor(declaration.value) &&
+                    !isAllowedThemeDeclaration(file, declaration, themes)) {
+                    result.violations.push({
+                        column: declaration.source?.start?.column ?? 1,
+                        line: declaration.source?.start?.line ?? 1,
+                        message: "Literal colors are allowed only in configured themes.",
+                        nodeKind: "css-declaration",
+                        path: file.path,
+                        rule: "css/no-literal-color",
+                    });
+                }
+            });
+            if (!file.sourceFile) {
+                return result;
+            }
+            const sourceFile = file.sourceFile;
+            const visit = (node) => {
+                if (isJsxAttribute(node) && isIdentifier(node.name)) {
+                    const value = jsxStringValue(node.initializer);
+                    const isDirectColor = isColorBearingProperty(node.name.text);
+                    const isLiteralClass = node.name.text === "className" &&
+                        value !== undefined &&
+                        classContainsLiteralColor(value);
+                    if (value !== undefined &&
+                        ((isDirectColor && containsLiteralColor(value)) || isLiteralClass)) {
+                        const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                        result.violations.push({
+                            column: position.character + 1,
+                            line: position.line + 1,
+                            message: "Literal colors are allowed only in configured themes.",
+                            nodeKind: "tsx-color-attribute",
+                            path: file.path,
+                            rule: "css/no-literal-color",
+                        });
+                    }
+                }
+                if (isJsxAttribute(node) &&
+                    isIdentifier(node.name) &&
+                    node.name.text === "style" &&
+                    node.initializer &&
+                    isJsxExpression(node.initializer) &&
+                    node.initializer.expression &&
+                    isObjectLiteralExpression(node.initializer.expression)) {
+                    for (const property of node.initializer.expression.properties) {
+                        if (!isPropertyAssignment(property) ||
+                            !isStringLiteralLikeNode(property.initializer)) {
+                            continue;
+                        }
+                        const name = propertyName(property.name);
+                        if (name !== undefined &&
+                            isColorBearingProperty(name) &&
+                            containsLiteralColor(property.initializer.text)) {
+                            const position = sourceFile.getLineAndCharacterOfPosition(property.initializer.getStart(sourceFile));
+                            result.violations.push({
+                                column: position.character + 1,
+                                line: position.line + 1,
+                                message: "Literal colors are allowed only in configured themes.",
+                                nodeKind: "tsx-style-property",
+                                path: file.path,
+                                rule: "css/no-literal-color",
+                            });
+                        }
+                    }
+                }
+                node.forEachChild(visit);
+            };
+            sourceFile.forEachChild(visit);
+            return result;
+        },
+    };
+}

package/dist/rules/theme.d.ts

@@ -0,0 +1,23 @@
+import type { Declaration } from "postcss";
+import type { ThemeConfig } from "../config.js";
+import type { ScannedFile } from "../scan.js";
+export interface ThemeDeclaration {
+    column: number;
+    line: number;
+    path: string;
+    value: string;
+}
+export interface CollectedTheme {
+    declarations: Map<string, ThemeDeclaration>;
+    files: Set<string>;
+    name: string;
+    overlapping: boolean;
+    unresolved: boolean;
+    selector: string;
+}
+export declare function createThemeCollector(themeConfigs: ThemeConfig[]): {
+    begin: () => void;
+    collect: (file: ScannedFile) => void;
+    themes: CollectedTheme[];
+};
+export declare function isAllowedThemeDeclaration(file: ScannedFile, declaration: Declaration, themes: ThemeConfig[]): boolean;

package/dist/rules/theme.js

@@ -0,0 +1,128 @@
+function normalizePath(path) {
+    return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function exactAttributes(selector) {
+    const attributes = new Map();
+    for (const match of selector.matchAll(/\[([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\]\s]+))\]/g)) {
+        const name = match[1];
+        const value = match[2] ?? match[3] ?? match[4];
+        if (name !== undefined && value !== undefined) {
+            attributes.set(name, value);
+        }
+    }
+    return attributes;
+}
+function isSingleCompoundSelector(selector) {
+    const withoutAttributes = selector.replace(/\[[^\]]+\]/g, "");
+    return /^(?:[a-zA-Z][\w-]*|\*|[.#][\w-]+)*$/.test(withoutAttributes);
+}
+function selectorsAreProvablyDisjoint(left, right) {
+    if (!isSingleCompoundSelector(left) || !isSingleCompoundSelector(right)) {
+        return false;
+    }
+    const leftAttributes = exactAttributes(left);
+    const rightAttributes = exactAttributes(right);
+    for (const [name, value] of leftAttributes) {
+        const otherValue = rightAttributes.get(name);
+        if (otherValue !== undefined && otherValue !== value) {
+            return true;
+        }
+    }
+    const leftIds = [...left.matchAll(/#([\w-]+)/g)].map((match) => match[1]);
+    const rightIds = [...right.matchAll(/#([\w-]+)/g)].map((match) => match[1]);
+    return (leftIds.length === 1 &&
+        rightIds.length === 1 &&
+        leftIds[0] !== rightIds[0]);
+}
+export function createThemeCollector(themeConfigs) {
+    const themes = themeConfigs.map((theme) => ({
+        declarations: new Map(),
+        files: new Set(theme.files.map(normalizePath)),
+        name: theme.name,
+        overlapping: false,
+        selector: theme.selector.trim(),
+        unresolved: false,
+    }));
+    function begin() {
+        for (const theme of themes) {
+            theme.declarations.clear();
+            theme.overlapping = false;
+            theme.unresolved = false;
+        }
+        for (let index = 0; index < themes.length; index += 1) {
+            const theme = themes[index];
+            if (!theme) {
+                continue;
+            }
+            for (const candidate of themes.slice(index + 1)) {
+                const sharesFile = [...theme.files].some((file) => candidate.files.has(file));
+                if (sharesFile &&
+                    !selectorsAreProvablyDisjoint(theme.selector, candidate.selector)) {
+                    theme.overlapping = true;
+                    candidate.overlapping = true;
+                }
+            }
+        }
+    }
+    function collect(file) {
+        if (!file.cssRoot) {
+            return;
+        }
+        for (const theme of themes) {
+            if (!theme.files.has(normalizePath(file.path))) {
+                continue;
+            }
+            const configuredSelectors = new Set(themes
+                .filter((candidate) => candidate.files.has(normalizePath(file.path)))
+                .map(({ selector }) => selector));
+            let matchingRules = 0;
+            file.cssRoot.walkRules((rule) => {
+                const selector = rule.selector.trim();
+                const directDeclarations = (rule.nodes ?? []).filter((node) => node.type === "decl" && node.prop.startsWith("--"));
+                if (directDeclarations.length > 0 &&
+                    selector !== theme.selector &&
+                    !configuredSelectors.has(selector)) {
+                    theme.unresolved = true;
+                }
+                if (selector !== theme.selector) {
+                    return;
+                }
+                matchingRules += 1;
+                if (rule.parent?.type !== "root") {
+                    theme.unresolved = true;
+                }
+                const nestedCustomDeclarations = [];
+                rule.walkDecls((declaration) => {
+                    if (declaration.parent !== rule && declaration.prop.startsWith("--")) {
+                        nestedCustomDeclarations.push(declaration);
+                    }
+                });
+                if (nestedCustomDeclarations.length > 0) {
+                    theme.unresolved = true;
+                }
+                for (const declaration of directDeclarations) {
+                    if (theme.declarations.has(declaration.prop)) {
+                        theme.overlapping = true;
+                    }
+                    theme.declarations.set(declaration.prop, {
+                        column: declaration.source?.start?.column ?? 1,
+                        line: declaration.source?.start?.line ?? 1,
+                        path: file.path,
+                        value: declaration.value,
+                    });
+                }
+            });
+            if (matchingRules > 1) {
+                theme.overlapping = true;
+            }
+        }
+    }
+    return { begin, collect, themes };
+}
+export function isAllowedThemeDeclaration(file, declaration, themes) {
+    const path = normalizePath(file.path);
+    const parent = declaration.parent;
+    return themes.some((theme) => theme.files.map(normalizePath).includes(path) &&
+        parent?.type === "rule" &&
+        parent.selector.trim() === theme.selector.trim());
+}

package/dist/rules/tokenComplete.d.ts

@@ -0,0 +1,11 @@
+import type { ThemeConfig } from "../config.js";
+import { type ThemeContract } from "../contracts.js";
+import type { CheckRule } from "../scan.js";
+export type { ThemeContract } from "../contracts.js";
+export interface TokenCompleteOptions {
+    computed?: Record<string, Record<string, string>>;
+    contract: ThemeContract;
+    themes: ThemeConfig[];
+}
+export declare function loadThemeContract(url?: URL): Promise<ThemeContract>;
+export declare function createTokenCompleteRule({ computed, contract, themes, }: TokenCompleteOptions): CheckRule;

package/dist/rules/tokenComplete.js

@@ -0,0 +1,115 @@
+import { unresolvedTokenReferences } from "../color.js";
+import { parseThemeContract, } from "../contracts.js";
+import { createThemeCollector } from "./theme.js";
+export async function loadThemeContract(url) {
+    const { readFile } = await import("node:fs/promises");
+    const packaged = url ?? new URL("../theme-contract.json", import.meta.url);
+    return parseThemeContract(await readFile(packaged, "utf8"));
+}
+function findingLocation(theme) {
+    const first = theme.declarations.values().next().value;
+    return {
+        column: first?.column ?? 1,
+        line: first?.line ?? 1,
+        path: first?.path ?? [...theme.files].sort()[0] ?? "theme.css",
+    };
+}
+export function createTokenCompleteRule({ computed = {}, contract, themes, }) {
+    const collector = createThemeCollector(themes);
+    return {
+        name: "tokens/complete",
+        begin: collector.begin,
+        check(file) {
+            collector.collect(file);
+            return { uncovered: [], violations: [] };
+        },
+        complete() {
+            const result = { uncovered: [], violations: [] };
+            for (const theme of collector.themes) {
+                const location = findingLocation(theme);
+                const computedTheme = computed[theme.name] ?? {};
+                const evidenceTokens = new Set([
+                    ...contract.required,
+                    ...Object.keys(contract.derived),
+                    ...Object.values(contract.derived),
+                ]);
+                const hasCompleteComputedEvidence = [...evidenceTokens].every((token) => computedTheme[token] !== undefined);
+                if (theme.overlapping && !hasCompleteComputedEvidence) {
+                    result.uncovered.push({
+                        ...location,
+                        message: `Theme ${theme.name} uses overlapping selectors.`,
+                        nodeKind: "theme-selector",
+                        rule: "tokens/complete",
+                        required: true,
+                    });
+                }
+                if (theme.unresolved && !hasCompleteComputedEvidence) {
+                    result.uncovered.push({
+                        ...location,
+                        message: `Theme ${theme.name} has unresolved cascade conditions.`,
+                        nodeKind: "theme-cascade",
+                        rule: "tokens/complete",
+                        required: true,
+                    });
+                }
+                let missingRequired = false;
+                for (const token of contract.required) {
+                    if (!theme.declarations.has(token)) {
+                        missingRequired = true;
+                        result.violations.push({
+                            ...location,
+                            message: `Theme ${theme.name} is missing required token ${token}.`,
+                            nodeKind: `theme-token:${token}`,
+                            rule: "tokens/complete",
+                        });
+                    }
+                }
+                if (missingRequired) {
+                    result.uncovered.push({
+                        ...location,
+                        message: `Theme ${theme.name} is incomplete.`,
+                        nodeKind: "theme-required-coverage",
+                        rule: "tokens/complete",
+                        required: true,
+                    });
+                }
+                for (const [token, fallback] of Object.entries(contract.derived)) {
+                    if (!theme.declarations.has(token) &&
+                        !theme.declarations.has(fallback)) {
+                        result.violations.push({
+                            ...location,
+                            message: `Derived token ${token} has no available documented fallback.`,
+                            nodeKind: `theme-token:${token}`,
+                            rule: "tokens/complete",
+                        });
+                    }
+                }
+                const tokens = new Map([...theme.declarations].map(([name, declaration]) => [
+                    name,
+                    declaration.value,
+                ]));
+                for (const [name, value] of Object.entries(computedTheme)) {
+                    tokens.set(name, value);
+                }
+                const reportedReferences = new Set();
+                for (const declaration of theme.declarations.values()) {
+                    for (const reference of unresolvedTokenReferences(declaration.value, tokens)) {
+                        if (!reportedReferences.has(reference)) {
+                            reportedReferences.add(reference);
+                            result.uncovered.push({
+                                column: declaration.column,
+                                line: declaration.line,
+                                message: `Theme ${theme.name} contains an unresolved token reference.`,
+                                nodeKind: "theme-token-value",
+                                path: declaration.path,
+                                rule: "tokens/complete",
+                                required: true,
+                            });
+                        }
+                    }
+                }
+            }
+            return result;
+        },
+    };
+}