openuispec 0.2.19 → 0.2.20

package/dist/runtime/package-paths.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const packageRootCache = new Map();
+function moduleDir(importMetaUrl) {
+    return dirname(fileURLToPath(importMetaUrl));
+}
+export function findPackageRoot(importMetaUrl) {
+    const startDir = moduleDir(importMetaUrl);
+    const cached = packageRootCache.get(startDir);
+    if (cached) {
+        return cached;
+    }
+    let current = startDir;
+    while (true) {
+        if (existsSync(join(current, "package.json"))) {
+            packageRootCache.set(startDir, current);
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new Error(`Could not locate package.json from ${startDir}`);
+        }
+        current = parent;
+    }
+}
+export function resolvePackagePath(importMetaUrl, ...segments) {
+    return join(findPackageRoot(importMetaUrl), ...segments);
+}
+export function readPackageVersion(importMetaUrl) {
+    const pkg = JSON.parse(readFileSync(resolvePackagePath(importMetaUrl, "package.json"), "utf-8"));
+    return pkg.version ?? "unknown";
+}

package/dist/schema/semantic-lint.js

@@ -0,0 +1,564 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import YAML from "yaml";
+import { listFiles, readManifest } from "../drift/index.js";
+/** Collect all locale keys from a JSON object, supporting both flat dotted keys and nested objects. */
+function collectLocaleKeys(data, prefix = "") {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return [];
+    const keys = [];
+    for (const [key, value] of Object.entries(data)) {
+        if (key.startsWith("$"))
+            continue; // skip $locale, $direction
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === "string") {
+            keys.push(fullKey);
+        }
+        else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            // Nested object — recurse to flatten
+            keys.push(...collectLocaleKeys(value, fullKey));
+        }
+    }
+    return keys;
+}
+const BUILTIN_CONTRACTS = new Set([
+    "nav_container",
+    "surface",
+    "action_trigger",
+    "input_field",
+    "data_display",
+    "collection",
+    "feedback",
+]);
+const BUILTIN_FORMATTERS = new Set([
+    "date",
+    "time",
+    "datetime",
+    "date_relative",
+    "currency",
+    "number",
+    "percent",
+    "boolean",
+    "duration",
+]);
+function loadJson(filePath) {
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+function loadYaml(filePath) {
+    return YAML.parse(readFileSync(filePath, "utf-8"));
+}
+function loadData(filePath) {
+    return filePath.endsWith(".json") ? loadJson(filePath) : loadYaml(filePath);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getSingleRootValue(data) {
+    if (!isRecord(data))
+        return undefined;
+    const values = Object.values(data);
+    return values.length === 1 ? values[0] : undefined;
+}
+function rootKeys(filePath) {
+    const data = loadData(filePath);
+    if (!isRecord(data))
+        return [];
+    return Object.keys(data);
+}
+function addNestedObjectKeys(prefix, value, refs) {
+    if (!isRecord(value))
+        return;
+    for (const [key, nested] of Object.entries(value)) {
+        const next = `${prefix}.${key}`;
+        refs.add(next);
+        addNestedObjectKeys(next, nested, refs);
+    }
+}
+function collectTokenRefs(root, value, refs) {
+    if (!root || !isRecord(value))
+        return;
+    refs.add(root);
+    if (root === "spacing") {
+        for (const group of ["scale", "aliases"]) {
+            const groupValue = value[group];
+            if (!isRecord(groupValue))
+                continue;
+            for (const [key, nested] of Object.entries(groupValue)) {
+                const ref = `${root}.${key}`;
+                refs.add(ref);
+                addNestedObjectKeys(ref, nested, refs);
+            }
+        }
+        return;
+    }
+    if (root === "typography") {
+        for (const group of ["scale", "font_family"]) {
+            const groupValue = value[group];
+            if (!isRecord(groupValue))
+                continue;
+            for (const [key, nested] of Object.entries(groupValue)) {
+                const ref = group === "scale" ? `${root}.${key}` : `${root}.${group}.${key}`;
+                refs.add(ref);
+                addNestedObjectKeys(ref, nested, refs);
+            }
+        }
+        return;
+    }
+    if (root === "elevation") {
+        for (const [key, nested] of Object.entries(value)) {
+            const ref = `${root}.${key}`;
+            refs.add(ref);
+            addNestedObjectKeys(ref, nested, refs);
+        }
+        return;
+    }
+    if (root === "color") {
+        addNestedObjectKeys(root, value, refs);
+    }
+}
+function collectApiRefs(prefix, value, refs) {
+    if (!isRecord(value))
+        return;
+    const looksLikeEndpoint = typeof value.method === "string" || typeof value.path === "string";
+    if (looksLikeEndpoint && prefix) {
+        refs.add(`api.${prefix}`);
+    }
+    for (const [key, nested] of Object.entries(value)) {
+        const nextPrefix = prefix ? `${prefix}.${key}` : key;
+        collectApiRefs(nextPrefix, nested, refs);
+    }
+}
+function iconNameWithVariant(name, variant) {
+    if (!variant)
+        return name;
+    if (variant.startsWith("_"))
+        return `${name}${variant}`;
+    return `${name}_${variant}`;
+}
+function collectIconRefs(filePath) {
+    const refs = new Set();
+    const suffixes = [];
+    const data = loadData(filePath);
+    if (!isRecord(data) || !isRecord(data.icons))
+        return { refs, suffixes };
+    const icons = data.icons;
+    const variants = isRecord(icons.variants) ? icons.variants : {};
+    const variantSuffixes = isRecord(variants.suffixes) ? variants.suffixes : {};
+    for (const suffix of Object.keys(variantSuffixes)) {
+        if (suffix.trim())
+            suffixes.push(suffix);
+    }
+    const registerEntry = (name, value) => {
+        refs.add(name);
+        if (!isRecord(value))
+            return;
+        if (Array.isArray(value.variants)) {
+            for (const variant of value.variants) {
+                if (typeof variant === "string" && variant.trim()) {
+                    refs.add(iconNameWithVariant(name, variant));
+                }
+            }
+        }
+    };
+    const registry = isRecord(icons.registry) ? icons.registry : {};
+    for (const groupValue of Object.values(registry)) {
+        if (!isRecord(groupValue))
+            continue;
+        for (const [name, value] of Object.entries(groupValue)) {
+            registerEntry(name, value);
+        }
+    }
+    const custom = isRecord(icons.custom) ? icons.custom : {};
+    for (const namespaceValue of Object.values(custom)) {
+        if (!isRecord(namespaceValue))
+            continue;
+        for (const [name, value] of Object.entries(namespaceValue)) {
+            registerEntry(name, value);
+        }
+    }
+    const fallback = isRecord(icons.fallback) ? icons.fallback : {};
+    if (typeof fallback.missing_icon === "string") {
+        refs.add(fallback.missing_icon);
+    }
+    return { refs, suffixes };
+}
+function buildContext(projectDir, includes, manifest) {
+    const localeDir = resolve(projectDir, includes.locales);
+    const localeFiles = new Map();
+    for (const filePath of listFiles(localeDir, ".json")) {
+        const localeName = basename(filePath, ".json");
+        const data = loadJson(filePath);
+        // Support both flat dotted keys ("nav.home": "Home") and nested objects ({ nav: { home: "Home" } })
+        const flatKeys = Object.keys(data).filter(k => !k.startsWith("$"));
+        const hasNestedObjects = flatKeys.some(k => {
+            const v = data[k];
+            return typeof v === "object" && v !== null && !Array.isArray(v);
+        });
+        const allKeys = hasNestedObjects ? collectLocaleKeys(data) : flatKeys;
+        localeFiles.set(localeName, new Set(allKeys));
+    }
+    const formatterNames = new Set([
+        ...BUILTIN_FORMATTERS,
+        ...(isRecord(manifest.formatters) ? Object.keys(manifest.formatters) : []),
+    ]);
+    const mapperNames = new Set(isRecord(manifest.mappers) ? Object.keys(manifest.mappers) : []);
+    const contractNames = new Set(BUILTIN_CONTRACTS);
+    const contractsDir = resolve(projectDir, includes.contracts);
+    for (const filePath of listFiles(contractsDir, ".yaml")) {
+        for (const key of rootKeys(filePath)) {
+            contractNames.add(key);
+        }
+    }
+    // Components are also valid references in screen sections (via "component:" key)
+    const componentNames = new Set();
+    const componentsDir = resolve(projectDir, includes.components);
+    for (const filePath of listFiles(componentsDir, ".yaml")) {
+        for (const key of rootKeys(filePath)) {
+            componentNames.add(key);
+        }
+    }
+    const tokenRefs = new Set();
+    const tokensDir = resolve(projectDir, includes.tokens);
+    for (const filePath of listFiles(tokensDir, ".yaml")) {
+        const data = loadData(filePath);
+        if (!isRecord(data))
+            continue;
+        for (const [root, value] of Object.entries(data)) {
+            collectTokenRefs(root, value, tokenRefs);
+        }
+    }
+    const iconsPath = join(tokensDir, "icons.yaml");
+    const iconData = existsSync(iconsPath)
+        ? collectIconRefs(iconsPath)
+        : { refs: new Set(), suffixes: [] };
+    const screenRefs = new Set();
+    const screensDir = resolve(projectDir, includes.screens);
+    for (const filePath of listFiles(screensDir, ".yaml")) {
+        for (const key of rootKeys(filePath)) {
+            screenRefs.add(`screens/${key}`);
+        }
+    }
+    const flowRefs = new Set();
+    const flowsDir = resolve(projectDir, includes.flows);
+    for (const filePath of listFiles(flowsDir, ".yaml")) {
+        for (const key of rootKeys(filePath)) {
+            flowRefs.add(`flows/${key}`);
+        }
+    }
+    const apiRefs = new Set();
+    if (isRecord(manifest.api) && isRecord(manifest.api.endpoints)) {
+        collectApiRefs("", manifest.api.endpoints, apiRefs);
+    }
+    const defaultLocale = isRecord(manifest.i18n) && typeof manifest.i18n.default_locale === "string"
+        ? manifest.i18n.default_locale
+        : localeFiles.keys().next().value ?? null;
+    return {
+        manifest,
+        localeFiles,
+        formatterNames,
+        mapperNames,
+        contractNames,
+        componentNames,
+        tokenRefs,
+        iconRefs: iconData.refs,
+        iconVariantSuffixes: iconData.suffixes,
+        screenRefs,
+        flowRefs,
+        apiRefs,
+        defaultLocale,
+    };
+}
+function missingLocalesForKey(context, key) {
+    const missing = [];
+    for (const [locale, keys] of context.localeFiles.entries()) {
+        if (!keys.has(key))
+            missing.push(locale);
+    }
+    return missing.sort();
+}
+function validateLocaleRef(value, path, context, errors) {
+    const ref = value.slice(3);
+    if (!ref)
+        return;
+    if (!ref.includes("{")) {
+        const missing = missingLocalesForKey(context, ref);
+        if (missing.length > 0) {
+            errors.push({
+                path,
+                message: `locale key "${ref}" is missing in locale(s): ${missing.join(", ")}`,
+            });
+        }
+        return;
+    }
+    const staticPrefix = ref.split("{", 1)[0];
+    if (staticPrefix) {
+        const hasMatch = Array.from(context.localeFiles.values()).some((keys) => Array.from(keys).some((key) => key.startsWith(staticPrefix)));
+        if (!hasMatch) {
+            errors.push({
+                path,
+                message: `dynamic locale key prefix "${staticPrefix}" does not match any locale entry`,
+            });
+        }
+    }
+    for (const formatter of extractFormatterRefs(ref)) {
+        if (!context.formatterNames.has(formatter)) {
+            errors.push({
+                path,
+                message: `unknown formatter "${formatter}" used inside locale key reference`,
+            });
+        }
+    }
+}
+function extractFormatterRefs(value) {
+    const refs = new Set();
+    const regex = /\|\s*format:([A-Za-z0-9_.-]+)/g;
+    let match;
+    while ((match = regex.exec(value)) !== null) {
+        const name = match[1].split(".", 1)[0];
+        if (name)
+            refs.add(name);
+    }
+    return Array.from(refs);
+}
+function extractMapperRefs(value) {
+    const refs = new Set();
+    const regex = /\|\s*map:([A-Za-z0-9_.-]+)/g;
+    let match;
+    while ((match = regex.exec(value)) !== null) {
+        if (match[1])
+            refs.add(match[1]);
+    }
+    return Array.from(refs);
+}
+function maybeTokenRef(value) {
+    return /^(color|typography|spacing|elevation)\./.test(value);
+}
+function isDynamicReference(value) {
+    return value.includes("{") || value.includes("}");
+}
+function isKnownIconRef(value, context) {
+    if (context.iconRefs.has(value))
+        return true;
+    for (const suffix of context.iconVariantSuffixes) {
+        if (value.endsWith(suffix)) {
+            const base = value.slice(0, -suffix.length);
+            if (context.iconRefs.has(base))
+                return true;
+        }
+    }
+    return false;
+}
+function validateStringValue(key, value, path, context, formIds, errors, options) {
+    if (value.startsWith("$t:")) {
+        validateLocaleRef(value, path, context, errors);
+    }
+    for (const formatter of extractFormatterRefs(value)) {
+        if (!context.formatterNames.has(formatter)) {
+            errors.push({ path, message: `unknown formatter "${formatter}"` });
+        }
+    }
+    for (const mapper of extractMapperRefs(value)) {
+        if (!context.mapperNames.has(mapper)) {
+            errors.push({ path, message: `unknown mapper "${mapper}"` });
+        }
+    }
+    if (options.validateTokens && maybeTokenRef(value) && !isDynamicReference(value) && !context.tokenRefs.has(value)) {
+        errors.push({ path, message: `unknown token reference "${value}"` });
+    }
+    if ((key === "contract" || key === "item_contract") && !context.contractNames.has(value)) {
+        errors.push({ path, message: `unknown contract "${value}"` });
+    }
+    if (key === "component" && !path.includes("platform_mapping") && !context.componentNames.has(value)) {
+        errors.push({ path, message: `unknown component "${value}"` });
+    }
+    if ((key === "icon" || key === "icon_active") &&
+        !isDynamicReference(value) &&
+        !value.includes(".") &&
+        !isKnownIconRef(value, context)) {
+        errors.push({ path, message: `unknown icon "${value}"` });
+    }
+    if ((key === "source" || key === "endpoint") && value.startsWith("api.") && !context.apiRefs.has(value)) {
+        errors.push({ path, message: `unknown API reference "${value}"` });
+    }
+    if (key === "destination" && value !== "$back") {
+        if (value.startsWith("screens/") && !context.screenRefs.has(value)) {
+            errors.push({ path, message: `unknown screen destination "${value}"` });
+        }
+        else if (value.startsWith("flows/") && !context.flowRefs.has(value)) {
+            errors.push({ path, message: `unknown flow destination "${value}"` });
+        }
+    }
+    if (key === "target" && value.startsWith("screens/")) {
+        const screenTarget = value.split(".", 1)[0];
+        if (!context.screenRefs.has(screenTarget)) {
+            errors.push({ path, message: `unknown screen target "${value}"` });
+        }
+    }
+    if (key === "form_id" && !formIds.has(value)) {
+        errors.push({ path, message: `unknown form_id "${value}" in submit action` });
+    }
+}
+function collectFormIds(value, formIds) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectFormIds(item, formIds);
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    if (typeof value.form_id === "string" && value.form_id.trim()) {
+        formIds.add(value.form_id);
+    }
+    for (const nested of Object.values(value)) {
+        collectFormIds(nested, formIds);
+    }
+}
+function traverse(value, path, context, formIds, errors, key = null, options) {
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            traverse(item, `${path}/${index}`, context, formIds, errors, key, options);
+        }
+        return;
+    }
+    if (typeof value === "string") {
+        validateStringValue(key, value, path, context, formIds, errors, options);
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    if (key === "icon" &&
+        typeof value.ref === "string" &&
+        !isDynamicReference(value.ref) &&
+        !value.ref.includes(".") &&
+        !isKnownIconRef(value.ref, context)) {
+        errors.push({ path: `${path}/ref`, message: `unknown icon "${value.ref}"` });
+    }
+    if (key === "sections") {
+        for (const [index, entry] of Object.entries(value)) {
+            if (typeof entry === "string" && entry.startsWith("screens/") && !context.screenRefs.has(entry)) {
+                errors.push({
+                    path: `${path}/${index}`,
+                    message: `unknown screen section reference "${entry}"`,
+                });
+            }
+        }
+    }
+    for (const [childKey, nested] of Object.entries(value)) {
+        traverse(nested, `${path}/${childKey}`, context, formIds, errors, childKey, options);
+    }
+}
+function lintFile(filePath, context, options) {
+    const data = loadData(filePath);
+    const formIds = new Set();
+    collectFormIds(data, formIds);
+    const errors = [];
+    traverse(data, basename(filePath), context, formIds, errors, null, options);
+    return errors;
+}
+function lintLocaleCoverage(context) {
+    const errors = [];
+    if (context.localeFiles.size <= 1)
+        return errors;
+    const baselineLocale = (context.defaultLocale && context.localeFiles.has(context.defaultLocale) && context.defaultLocale) ||
+        Array.from(context.localeFiles.keys())[0];
+    if (!baselineLocale)
+        return errors;
+    const baselineKeys = context.localeFiles.get(baselineLocale) ?? new Set();
+    for (const [locale, keys] of context.localeFiles.entries()) {
+        if (locale === baselineLocale)
+            continue;
+        for (const key of baselineKeys) {
+            if (!keys.has(key)) {
+                errors.push({
+                    path: `${locale}.json`,
+                    message: `missing locale key "${key}" from baseline locale "${baselineLocale}"`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+function lintManifestGenerationContext(projectDir, manifest) {
+    if (!isRecord(manifest))
+        return [];
+    // code_roots.backend is optional — it's a hint for AI generation, not a hard requirement
+    const generation = isRecord(manifest.generation) ? manifest.generation : {};
+    const codeRoots = isRecord(generation.code_roots) ? generation.code_roots : null;
+    const backendRoot = codeRoots && typeof codeRoots.backend === "string" ? codeRoots.backend.trim() : "";
+    if (!backendRoot)
+        return [];
+    const resolvedBackendRoot = resolve(projectDir, backendRoot);
+    if (!existsSync(resolvedBackendRoot)) {
+        return [{
+                path: "openuispec.yaml",
+                severity: "warning",
+                message: `generation.code_roots.backend points to a missing folder: ${backendRoot}`,
+            }];
+    }
+    return [];
+}
+function printSemanticErrors(label, errors) {
+    if (errors.length === 0)
+        return 0;
+    const previewLimit = 10;
+    const realErrors = errors.filter((e) => e.severity !== "warning");
+    const warnings = errors.filter((e) => e.severity === "warning");
+    if (realErrors.length > 0) {
+        console.log(`  FAIL  ${label} (${realErrors.length} semantic error(s))`);
+        for (const error of realErrors.slice(0, previewLimit)) {
+            console.log(`        [${error.path}] ${error.message}`);
+        }
+        if (realErrors.length > previewLimit) {
+            console.log(`        ... and ${realErrors.length - previewLimit} more`);
+        }
+    }
+    for (const warning of warnings) {
+        console.log(`  WARN  ${label}: ${warning.message}`);
+    }
+    return realErrors.length;
+}
+export function collectSemanticLint(projectDir, includes) {
+    const manifest = readManifest(projectDir);
+    const context = buildContext(projectDir, includes, manifest);
+    const contractsDir = resolve(projectDir, includes.contracts);
+    const componentsDir = resolve(projectDir, includes.components);
+    const allErrors = [
+        ...lintLocaleCoverage(context),
+        ...lintManifestGenerationContext(projectDir, context.manifest),
+    ];
+    const files = [
+        join(projectDir, "openuispec.yaml"),
+        ...listFiles(resolve(projectDir, includes.screens), ".yaml"),
+        ...listFiles(resolve(projectDir, includes.flows), ".yaml"),
+        ...listFiles(resolve(projectDir, includes.platform), ".yaml"),
+        ...listFiles(resolve(projectDir, includes.contracts), ".yaml"),
+        ...listFiles(componentsDir, ".yaml"),
+    ];
+    for (const filePath of files) {
+        const isContractOrComponent = filePath.startsWith(contractsDir) || filePath.startsWith(componentsDir);
+        allErrors.push(...lintFile(filePath, context, { validateTokens: !isContractOrComponent }));
+    }
+    return allErrors;
+}
+export function runSemanticLint(projectDir, includes) {
+    const manifest = readManifest(projectDir);
+    const context = buildContext(projectDir, includes, manifest);
+    let total = 0;
+    const contractsDir = resolve(projectDir, includes.contracts);
+    const componentsDir = resolve(projectDir, includes.components);
+    total += printSemanticErrors("locales", lintLocaleCoverage(context));
+    total += printSemanticErrors("openuispec.yaml", lintManifestGenerationContext(projectDir, context.manifest));
+    const files = [
+        join(projectDir, "openuispec.yaml"),
+        ...listFiles(resolve(projectDir, includes.screens), ".yaml"),
+        ...listFiles(resolve(projectDir, includes.flows), ".yaml"),
+        ...listFiles(resolve(projectDir, includes.platform), ".yaml"),
+        ...listFiles(resolve(projectDir, includes.contracts), ".yaml"),
+        ...listFiles(componentsDir, ".yaml"),
+    ];
+    for (const filePath of files) {
+        const isContractOrComponent = filePath.startsWith(contractsDir) || filePath.startsWith(componentsDir);
+        total += printSemanticErrors(basename(filePath), lintFile(filePath, context, { validateTokens: !isContractOrComponent }));
+    }
+    return total;
+}