openuispec 0.2.19 → 0.2.21

package/dist/check/audit.js

@@ -0,0 +1,392 @@
+/**
+ * Design quality audit for OpenUISpec projects.
+ *
+ * Checks token patterns and contract completeness to produce a numeric quality score.
+ * Score formula: max(0, 100 - errors × 10 - warnings × 3)
+ *
+ * Usage:
+ *   openuispec check --target web --audit
+ *   openuispec check --target ios --audit --min-score 70
+ *   openuispec check --target web --audit --format json
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import YAML from "yaml";
+const AI_DEFAULT_FONTS = new Set(["Inter", "Roboto", "Arial", "Open Sans"]);
+const REQUIRED_TOKEN_FILES = [
+    "color.yaml",
+    "typography.yaml",
+    "spacing.yaml",
+    "elevation.yaml",
+    "motion.yaml",
+    "layout.yaml",
+    "themes.yaml",
+    "icons.yaml",
+];
+function readYaml(path) {
+    try {
+        return YAML.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function readYamlForAudit(path, domain, findings) {
+    try {
+        return YAML.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return null;
+        findings.push({
+            domain,
+            rule: "unreadable_file",
+            severity: "error",
+            message: `Could not parse "${path}". Fix malformed YAML before relying on this audit.`,
+        });
+        return null;
+    }
+}
+function checkRequiredTokenFiles(tokensDir, findings) {
+    for (const filename of REQUIRED_TOKEN_FILES) {
+        if (!existsSync(join(tokensDir, filename))) {
+            findings.push({
+                domain: "tokens",
+                rule: "missing_file",
+                severity: "error",
+                message: `Required token file "${filename}" is missing.`,
+            });
+        }
+    }
+}
+function checkTypography(tokensDir, findings) {
+    const doc = readYamlForAudit(join(tokensDir, "typography.yaml"), "typography", findings);
+    if (!doc?.typography)
+        return;
+    // Font diversity: primary must NOT be a common AI default
+    const primaryFont = doc.typography.font_family?.primary?.value;
+    if (typeof primaryFont === "string" && AI_DEFAULT_FONTS.has(primaryFont)) {
+        findings.push({
+            domain: "typography",
+            rule: "font_diversity",
+            severity: "error",
+            message: `Primary font "${primaryFont}" is an AI-default choice. Use a distinctive brand font.`,
+        });
+    }
+    // Scale usage: at least 4 distinct scale levels defined
+    const scaleKeys = Object.keys(doc.typography.scale ?? {});
+    if (scaleKeys.length > 0 && scaleKeys.length < 4) {
+        findings.push({
+            domain: "typography",
+            rule: "scale_usage",
+            severity: "warning",
+            message: `Only ${scaleKeys.length} type scale level(s) defined. Use ≥4 distinct levels for clear hierarchy.`,
+        });
+    }
+    // Weight hierarchy: at least 2 distinct weights
+    if (doc.typography.scale) {
+        const weights = new Set();
+        for (const level of Object.values(doc.typography.scale)) {
+            if (typeof level?.weight === "number") {
+                weights.add(level.weight);
+            }
+        }
+        if (weights.size > 0 && weights.size < 2) {
+            findings.push({
+                domain: "typography",
+                rule: "weight_hierarchy",
+                severity: "warning",
+                message: "Only 1 distinct font weight used across the type scale. Use ≥2 weights (e.g. 400 + 700) for clear hierarchy.",
+            });
+        }
+    }
+}
+function checkColor(tokensDir, findings) {
+    const doc = readYamlForAudit(join(tokensDir, "color.yaml"), "color", findings);
+    if (!doc?.color)
+        return;
+    // Pure black/white check
+    function scanForPure(obj, path) {
+        if (typeof obj !== "object" || obj === null)
+            return;
+        if (typeof obj.reference === "string") {
+            const ref = obj.reference.toUpperCase();
+            if (ref === "#000000" || ref === "#000") {
+                findings.push({
+                    domain: "color",
+                    rule: "pure_black",
+                    severity: "error",
+                    message: `Token at ${path} uses pure black (#000000). Use a near-black with hue instead.`,
+                });
+            }
+            if (ref === "#FFFFFF" || ref === "#FFF") {
+                findings.push({
+                    domain: "color",
+                    rule: "pure_white",
+                    severity: "error",
+                    message: `Token at ${path} uses pure white (#FFFFFF). Use a slightly tinted white instead.`,
+                });
+            }
+        }
+        for (const [key, value] of Object.entries(obj)) {
+            if (key !== "reference" && typeof value === "object") {
+                scanForPure(value, `${path}.${key}`);
+            }
+        }
+    }
+    scanForPure(doc.color, "color");
+    // Semantic color completeness: success, warning, danger, info
+    if (doc.color.semantic) {
+        const required = ["success", "warning", "danger", "info"];
+        const defined = Object.keys(doc.color.semantic);
+        for (const name of required) {
+            if (!defined.includes(name)) {
+                findings.push({
+                    domain: "color",
+                    rule: "semantic_completeness",
+                    severity: "warning",
+                    message: `Semantic color "${name}" is missing. Define all four (success, warning, danger, info) for complete state coverage.`,
+                });
+            }
+        }
+    }
+    // Theme coverage: check themes.yaml for both light + dark
+    {
+        const themes = readYamlForAudit(join(tokensDir, "themes.yaml"), "color", findings);
+        if (!themes?.themes)
+            return;
+        const themeKeys = Object.keys(themes.themes);
+        const hasLight = themeKeys.some((k) => k.includes("light"));
+        const hasDark = themeKeys.some((k) => k.includes("dark"));
+        if (!hasLight || !hasDark) {
+            findings.push({
+                domain: "color",
+                rule: "theme_coverage",
+                severity: "warning",
+                message: "Both light and dark themes should be defined in tokens/themes.yaml.",
+            });
+        }
+    }
+}
+function checkSpacing(tokensDir, findings) {
+    const doc = readYamlForAudit(join(tokensDir, "spacing.yaml"), "spacing", findings);
+    if (!doc?.spacing)
+        return;
+    // Scale usage: at least 4 distinct values
+    const scale = doc.spacing.scale ?? {};
+    const scaleCount = Object.keys(scale).length;
+    if (scaleCount > 0 && scaleCount < 4) {
+        findings.push({
+            domain: "spacing",
+            rule: "scale_usage",
+            severity: "warning",
+            message: `Only ${scaleCount} spacing scale value(s) defined. Define ≥4 for meaningful spatial rhythm.`,
+        });
+    }
+    // Alias usage: page_margin and card_padding should exist
+    const aliases = doc.spacing.aliases ?? {};
+    const aliasKeys = Object.keys(aliases).map((k) => k.toLowerCase());
+    if (!aliasKeys.some((k) => k.includes("page_margin") || k.includes("page"))) {
+        findings.push({
+            domain: "spacing",
+            rule: "alias_page_margin",
+            severity: "warning",
+            message: "No page_margin alias found in spacing tokens. Define it for consistent screen padding.",
+        });
+    }
+    if (!aliasKeys.some((k) => k.includes("card_padding") || k.includes("card"))) {
+        findings.push({
+            domain: "spacing",
+            rule: "alias_card_padding",
+            severity: "warning",
+            message: "No card_padding alias found in spacing tokens. Define it for consistent card spacing.",
+        });
+    }
+}
+function checkMotion(tokensDir, findings) {
+    const doc = readYamlForAudit(join(tokensDir, "motion.yaml"), "motion", findings);
+    if (!doc?.motion)
+        return;
+    // Duration variety: at least 2 distinct durations
+    const durations = doc.motion.duration ?? {};
+    const distinctDurations = new Set(Object.values(durations));
+    if (Object.keys(durations).length > 0 && distinctDurations.size < 2) {
+        findings.push({
+            domain: "motion",
+            rule: "duration_variety",
+            severity: "warning",
+            message: "Only 1 distinct duration value found. Use ≥2 distinct durations (e.g. quick + normal).",
+        });
+    }
+    // Reduced motion: must be defined
+    if (!doc.motion.reduced_motion) {
+        findings.push({
+            domain: "motion",
+            rule: "reduced_motion",
+            severity: "error",
+            message: "motion.reduced_motion is not defined. Must specify policy for prefers-reduced-motion.",
+        });
+    }
+    // Easing quality: enter + exit curves, at least one cubic-bezier
+    if (doc.motion.easing) {
+        const easings = doc.motion.easing;
+        const keys = Object.keys(easings);
+        if (!keys.includes("enter") || !keys.includes("exit")) {
+            findings.push({
+                domain: "motion",
+                rule: "easing_quality",
+                severity: "warning",
+                message: "Motion easing should define at least 'enter' and 'exit' curves for asymmetric transitions.",
+            });
+        }
+        const hasCubicBezier = Object.values(easings).some((v) => typeof v === "string" && v.includes("cubic-bezier"));
+        if (!hasCubicBezier) {
+            findings.push({
+                domain: "motion",
+                rule: "easing_quality",
+                severity: "warning",
+                message: "All easing curves are generic keywords. Use at least one cubic-bezier() for nuanced motion.",
+            });
+        }
+    }
+}
+function checkElevationProgression(tokensDir, findings) {
+    const doc = readYamlForAudit(join(tokensDir, "elevation.yaml"), "elevation", findings);
+    if (!doc?.elevation)
+        return;
+    const levels = Object.keys(doc.elevation).filter((k) => k !== "none");
+    if (levels.length < 2) {
+        findings.push({
+            domain: "elevation",
+            rule: "level_count",
+            severity: "warning",
+            message: `Only ${levels.length} non-none elevation level(s) defined. Define ≥2 (e.g. sm, md, lg) for meaningful depth hierarchy.`,
+        });
+        return;
+    }
+    const androidValues = [];
+    for (const level of levels) {
+        const val = doc.elevation[level]?.platform?.android?.elevation;
+        if (typeof val === "number")
+            androidValues.push(val);
+    }
+    if (androidValues.length >= 2) {
+        for (let i = 1; i < androidValues.length; i++) {
+            if (androidValues[i] <= androidValues[i - 1]) {
+                findings.push({
+                    domain: "elevation",
+                    rule: "progression",
+                    severity: "warning",
+                    message: "Elevation levels do not increase monotonically. Each level should cast a deeper shadow than the previous.",
+                });
+                break;
+            }
+        }
+    }
+}
+function checkLayoutSizeClasses(tokensDir, findings) {
+    const doc = readYamlForAudit(join(tokensDir, "layout.yaml"), "layout", findings);
+    if (!doc?.layout?.size_classes)
+        return;
+    const classes = Object.keys(doc.layout.size_classes);
+    if (classes.length < 2) {
+        findings.push({
+            domain: "layout",
+            rule: "size_class_coverage",
+            severity: "warning",
+            message: `Only ${classes.length} size class(es) defined. Define at least compact + regular for responsive layouts.`,
+        });
+    }
+    else if (!classes.includes("compact")) {
+        findings.push({
+            domain: "layout",
+            rule: "size_class_coverage",
+            severity: "warning",
+            message: "No 'compact' size class defined. Mobile-first layouts require a compact breakpoint.",
+        });
+    }
+}
+function checkContractStateCoverage(contractsDir, findings) {
+    if (!existsSync(contractsDir))
+        return;
+    for (const file of readdirSync(contractsDir).filter((f) => f.endsWith(".yaml") && !f.startsWith("x_"))) {
+        const doc = readYamlForAudit(join(contractsDir, file), "contracts", findings);
+        if (!doc)
+            continue;
+        const contractName = Object.keys(doc)[0];
+        const contract = doc[contractName];
+        const mustHandle = contract?.generation?.must_handle ?? [];
+        if (mustHandle.length === 0) {
+            findings.push({
+                domain: "contracts",
+                rule: "state_coverage",
+                severity: "warning",
+                message: `Contract "${contractName}" has no generation.must_handle entries. Define required states for AI compliance.`,
+            });
+        }
+    }
+}
+function checkContracts(contractsDir, findings) {
+    // All collections have empty_state in must_handle or variants
+    {
+        const doc = readYamlForAudit(join(contractsDir, "collection.yaml"), "contracts", findings);
+        const collection = doc ? doc[Object.keys(doc)[0]] : null;
+        if (collection) {
+            const mustHandle = collection.generation?.must_handle ?? [];
+            const hasEmptyState = mustHandle.some((s) => s.toLowerCase().includes("empty"));
+            if (!hasEmptyState) {
+                findings.push({
+                    domain: "contracts",
+                    rule: "collection_empty_state",
+                    severity: "warning",
+                    message: "collection contract does not list empty_state handling in generation.must_handle.",
+                });
+            }
+        }
+    }
+}
+export function buildAuditResult(projectDir, threshold = 0) {
+    const manifest = readYaml(join(projectDir, "openuispec.yaml"));
+    const tokensDir = resolve(projectDir, manifest?.includes?.tokens ?? "./tokens/");
+    const contractsDir = resolve(projectDir, manifest?.includes?.contracts ?? "./contracts/");
+    // Use audit_threshold from manifest if no CLI override
+    const effectiveThreshold = threshold > 0 ? threshold : (manifest?.generation_guidance?.audit_threshold ?? 0);
+    const findings = [];
+    checkRequiredTokenFiles(tokensDir, findings);
+    checkTypography(tokensDir, findings);
+    checkColor(tokensDir, findings);
+    checkSpacing(tokensDir, findings);
+    checkMotion(tokensDir, findings);
+    checkElevationProgression(tokensDir, findings);
+    checkLayoutSizeClasses(tokensDir, findings);
+    checkContracts(contractsDir, findings);
+    checkContractStateCoverage(contractsDir, findings);
+    const errors = findings.filter((f) => f.severity === "error").length;
+    const warnings = findings.filter((f) => f.severity === "warning").length;
+    const score = Math.max(0, 100 - errors * 10 - warnings * 3);
+    return {
+        score,
+        errors,
+        warnings,
+        findings,
+        passed: score >= effectiveThreshold,
+        threshold: effectiveThreshold,
+    };
+}
+export function formatAuditResult(result) {
+    const lines = [
+        `Design Quality Score: ${result.score}/100`,
+        `Errors: ${result.errors}  Warnings: ${result.warnings}`,
+        result.threshold > 0 ? `Threshold: ${result.threshold} — ${result.passed ? "PASS" : "FAIL"}` : "",
+        "",
+    ].filter((l) => l !== "" || lines?.length === 0);
+    if (result.findings.length === 0) {
+        lines.push("No issues found.");
+    }
+    else {
+        for (const f of result.findings) {
+            lines.push(`[${f.severity.toUpperCase()}] [${f.domain}] ${f.message}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/check/index.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * Composite check command for OpenUISpec projects.
+ *
+ * Combines schema validation, semantic linting, and prepare readiness
+ * into a single call for AI agents.
+ *
+ * Usage:
+ *   openuispec check --target web           # human-readable summary
+ *   openuispec check --target ios --json    # machine-readable output
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import YAML from "yaml";
+import { computeSharedDrift, findProjectDir, hasDriftChanges, readManifest, readProjectName, resolveOutputDir, sharedLayersForTarget, } from "../drift/index.js";
+import { buildAjv, readIncludes, GROUPS, } from "../schema/validate.js";
+import { collectSemanticLint } from "../schema/semantic-lint.js";
+import { buildAuditResult, formatAuditResult } from './audit.js';
+// ── prepare readiness helpers ─────────────────────────────────────────
+const PRESENTATION_ONLY_KEYS = new Set(["naming", "bundler", "css"]);
+function platformStackKeys(target) {
+    switch (target) {
+        case "android":
+            return ["architecture", "state", "preferences", "database", "di", "naming"];
+        case "web":
+            return ["runtime", "routing", "state", "storage_backend", "bundler", "css", "naming"];
+        case "ios":
+            return ["architecture", "persistence", "di", "naming"];
+        default:
+            return [];
+    }
+}
+function requiredPlatformDecisionKeys(target) {
+    return platformStackKeys(target).filter((key) => !PRESENTATION_ONLY_KEYS.has(key));
+}
+function readPlatformDefinition(projectDir, manifest, target) {
+    const platformDir = resolve(projectDir, manifest.includes?.platform ?? "./platform/");
+    const platformPath = join(platformDir, `${target}.yaml`);
+    if (!existsSync(platformPath))
+        return {};
+    try {
+        const doc = YAML.parse(readFileSync(platformPath, "utf-8"));
+        return doc?.[target] ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function missingPlatformDecisions(target, platformDef) {
+    const generation = platformDef.generation ?? {};
+    return requiredPlatformDecisionKeys(target).filter((key) => {
+        const value = generation[key];
+        return typeof value !== "string" || value.trim().length === 0;
+    });
+}
+function hasApiEndpoints(manifest) {
+    const endpoints = manifest.api?.endpoints;
+    return typeof endpoints === "object" && endpoints !== null && Object.keys(endpoints).length > 0;
+}
+function resolveBackendRoot(projectDir, manifest) {
+    const backendRoot = manifest.generation?.code_roots?.backend;
+    if (typeof backendRoot !== "string" || backendRoot.trim().length === 0) {
+        return null;
+    }
+    return resolve(projectDir, backendRoot);
+}
+function determinePrepare(projectDir, projectName, target) {
+    const manifest = readManifest(projectDir);
+    const outputDir = resolveOutputDir(projectDir, projectName, target);
+    const statePath = join(outputDir, ".openuispec-state.json");
+    const snapshotExists = existsSync(statePath);
+    const mode = snapshotExists ? "update" : "bootstrap";
+    const platformDef = readPlatformDefinition(projectDir, manifest, target);
+    const missing = missingPlatformDecisions(target, platformDef);
+    const warnings = [];
+    const backendContextRequired = hasApiEndpoints(manifest);
+    const backendRoot = resolveBackendRoot(projectDir, manifest);
+    const backendContextReady = !backendContextRequired || (backendRoot !== null && existsSync(backendRoot));
+    if (!backendContextReady) {
+        warnings.push("api endpoints require generation.code_roots.backend to point at an existing backend folder");
+    }
+    const stackConfirmation = platformDef.generation?.stack_confirmation;
+    const pendingUserConfirmation = typeof stackConfirmation === "string" && stackConfirmation !== "confirmed";
+    if (pendingUserConfirmation) {
+        warnings.push(`Target stack for "${target}" requires explicit user confirmation before implementation.`);
+    }
+    // Check for shared layer drift (only when tracks are configured)
+    const sharedLayers = sharedLayersForTarget(projectDir, target);
+    for (const layer of sharedLayers) {
+        if (layer.tracks.length === 0)
+            continue;
+        const driftResult = computeSharedDrift(projectDir, layer);
+        if (driftResult.state !== null) {
+            if (hasDriftChanges(driftResult.drift)) {
+                warnings.push(`Shared layer "${layer.name}" has spec drift — shared code may need updates before ${target} generation.`);
+            }
+        }
+    }
+    const ready = missing.length === 0 && backendContextReady && !pendingUserConfirmation;
+    return { mode, ready, missing, warnings };
+}
+// ── core (importable, no process.exit) ───────────────────────────────
+export function buildCheckResult(target, cwd = process.cwd(), includeAudit = false) {
+    const projectDir = findProjectDir(cwd);
+    const projectName = readProjectName(projectDir);
+    const includes = readIncludes(projectDir);
+    const ajv = buildAjv();
+    // 1. Schema validation (all groups except semantic)
+    const schemaGroupKeys = Object.keys(GROUPS).filter((k) => k !== "semantic");
+    const validationGroups = [];
+    let validationTotalErrors = 0;
+    for (const key of schemaGroupKeys) {
+        const result = GROUPS[key].collectJson(ajv, projectDir, includes, key);
+        validationGroups.push(result);
+        validationTotalErrors += result.errors.length;
+    }
+    const validation = {
+        total_errors: validationTotalErrors,
+        groups: validationGroups,
+    };
+    // 2. Semantic validation
+    const semanticErrors = collectSemanticLint(projectDir, includes);
+    const semantic = {
+        total_errors: semanticErrors.length,
+        errors: semanticErrors.map((e) => ({ path: e.path, message: e.message })),
+    };
+    // 3. Prepare readiness
+    const prepare = determinePrepare(projectDir, projectName, target);
+    const audit = includeAudit ? buildAuditResult(projectDir) : undefined;
+    return { target, validation, semantic, prepare, audit };
+}
+// ── main ──────────────────────────────────────────────────────────────
+export function runCheck(argv) {
+    const isJson = argv.includes("--json");
+    const targetIdx = argv.indexOf("--target");
+    const target = targetIdx !== -1 && argv[targetIdx + 1] ? argv[targetIdx + 1] : null;
+    if (!target) {
+        console.error("Error: --target is required for check");
+        console.error("Usage: openuispec check --target <target> [--json]");
+        process.exit(1);
+    }
+    const includeAudit = argv.includes("--audit");
+    const minScoreIdx = argv.indexOf("--min-score");
+    const minScore = minScoreIdx !== -1 && argv[minScoreIdx + 1] ? parseInt(argv[minScoreIdx + 1], 10) : 0;
+    const result = buildCheckResult(target, undefined, includeAudit);
+    if (isJson) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printReport(result);
+        if (result.audit) {
+            console.log("\nDesign Quality Audit");
+            console.log("====================");
+            console.log(formatAuditResult(result.audit));
+            if (minScore > 0 && result.audit.score < minScore) {
+                console.error(`\nFAIL: Score ${result.audit.score} is below --min-score ${minScore}`);
+                process.exit(1);
+            }
+        }
+    }
+    // Exit codes: 0 = clean + ready, 2 = validation errors, 1 = config error
+    const totalErrors = result.validation.total_errors + result.semantic.total_errors;
+    if (totalErrors > 0) {
+        process.exit(2);
+    }
+    if (!result.prepare.ready) {
+        process.exit(2);
+    }
+    process.exit(0);
+}
+function printReport(result) {
+    console.log("OpenUISpec Check");
+    console.log("================");
+    console.log(`Target: ${result.target}`);
+    const totalValidation = result.validation.total_errors;
+    const totalSemantic = result.semantic.total_errors;
+    console.log(`\nSchema validation: ${totalValidation === 0 ? "PASS" : `FAIL (${totalValidation} error(s))`}`);
+    if (totalValidation > 0) {
+        for (const group of result.validation.groups) {
+            if (group.errors.length > 0) {
+                console.log(`  ${group.group}: ${group.errors.length} error(s)`);
+                for (const err of group.errors.slice(0, 3)) {
+                    console.log(`    [${err.file}] ${err.path}: ${err.message}`);
+                }
+                if (group.errors.length > 3) {
+                    console.log(`    ... and ${group.errors.length - 3} more`);
+                }
+            }
+        }
+    }
+    console.log(`Semantic lint: ${totalSemantic === 0 ? "PASS" : `FAIL (${totalSemantic} error(s))`}`);
+    if (totalSemantic > 0) {
+        for (const err of result.semantic.errors.slice(0, 5)) {
+            console.log(`  [${err.path}] ${err.message}`);
+        }
+        if (result.semantic.errors.length > 5) {
+            console.log(`  ... and ${result.semantic.errors.length - 5} more`);
+        }
+    }
+    console.log(`\nPrepare readiness: ${result.prepare.ready ? "READY" : "NOT READY"}`);
+    console.log(`  Mode: ${result.prepare.mode}`);
+    if (result.prepare.missing.length > 0) {
+        console.log(`  Missing platform decisions: ${result.prepare.missing.join(", ")}`);
+    }
+    for (const w of result.prepare.warnings) {
+        console.log(`  Warning: ${w}`);
+    }
+    const totalErrors = result.validation.total_errors + result.semantic.total_errors;
+    console.log(`\nResult: ${totalErrors === 0 && result.prepare.ready ? "ALL CLEAR" : "ACTION NEEDED"}`);
+}
+// Direct execution
+const isDirectRun = process.argv[1]?.endsWith("check/index.ts") ||
+    process.argv[1]?.endsWith("check/index.js");
+if (isDirectRun) {
+    runCheck(process.argv.slice(2));
+}