openuispec 0.1.28 → 0.1.30

package/schema/openuispec.schema.json

@@ -111,6 +111,16 @@
             "type": "string"
           }
         },
+        "code_roots": {
+          "type": "object",
+          "description": "Additional project code roots used as generation context.",
+          "properties": {
+            "backend": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
         "output_format": {
           "type": "object",
           "description": "Per-target generation config",

package/schema/semantic-lint.ts

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import YAML from "yaml";
+import { listFiles, readManifest } from "../drift/index.js";
 
 type UnknownRecord = Record<string, unknown>;
 
@@ -19,6 +20,7 @@ export interface UsageLint {
 }
 
 interface SemanticContext {
+  manifest: unknown;
   localeFiles: Map<string, Set<string>>;
   formatterNames: Set<string>;
   mapperNames: Set<string>;
@@ -66,17 +68,6 @@ function loadData(filePath: string): unknown {
   return filePath.endsWith(".json") ? loadJson(filePath) : loadYaml(filePath);
 }
 
-function listFiles(dir: string, ext: string): string[] {
-  try {
-    return readdirSync(dir)
-      .filter((file) => file.endsWith(ext))
-      .sort()
-      .map((file) => join(dir, file));
-  } catch {
-    return [];
-  }
-}
-
 function isRecord(value: unknown): value is UnknownRecord {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -213,9 +204,7 @@ function collectIconRefs(filePath: string): { refs: Set<string>; suffixes: strin
   return { refs, suffixes };
 }
 
-function buildContext(projectDir: string, includes: Includes): SemanticContext {
-  const manifestPath = join(projectDir, "openuispec.yaml");
-  const manifest = loadYaml(manifestPath) as UnknownRecord;
+function buildContext(projectDir: string, includes: Includes, manifest: UnknownRecord): SemanticContext {
 
   const localeDir = resolve(projectDir, includes.locales);
   const localeFiles = new Map<string, Set<string>>();
@@ -281,6 +270,7 @@ function buildContext(projectDir: string, includes: Includes): SemanticContext {
       : localeFiles.keys().next().value ?? null;
 
   return {
+    manifest,
     localeFiles,
     formatterNames,
     mapperNames,
@@ -552,6 +542,37 @@ function lintLocaleCoverage(context: SemanticContext): UsageLint[] {
   return errors;
 }
 
+function lintManifestGenerationContext(projectDir: string, manifest: unknown): UsageLint[] {
+  if (!isRecord(manifest)) return [];
+
+  const hasApiEndpoints =
+    isRecord(manifest.api) &&
+    isRecord(manifest.api.endpoints) &&
+    Object.keys(manifest.api.endpoints).length > 0;
+  if (!hasApiEndpoints) return [];
+
+  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 [{
+      path: "openuispec.yaml",
+      message: 'api endpoints require generation.code_roots.backend to point at the backend folder',
+    }];
+  }
+
+  const resolvedBackendRoot = resolve(projectDir, backendRoot);
+  if (!existsSync(resolvedBackendRoot)) {
+    return [{
+      path: "openuispec.yaml",
+      message: `generation.code_roots.backend points to a missing folder: ${backendRoot}`,
+    }];
+  }
+
+  return [];
+}
+
 function printSemanticErrors(label: string, errors: UsageLint[]): number {
   if (errors.length === 0) return 0;
   const previewLimit = 10;
@@ -566,12 +587,41 @@ function printSemanticErrors(label: string, errors: UsageLint[]): number {
   return errors.length;
 }
 
+export function collectSemanticLint(projectDir: string, includes: Includes): UsageLint[] {
+  const manifest = readManifest(projectDir) as UnknownRecord;
+  const context = buildContext(projectDir, includes, manifest);
+  const contractsDir = resolve(projectDir, includes.contracts);
+
+  const allErrors: UsageLint[] = [
+    ...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"),
+  ];
+
+  for (const filePath of files) {
+    allErrors.push(
+      ...lintFile(filePath, context, { validateTokens: !filePath.startsWith(contractsDir) })
+    );
+  }
+
+  return allErrors;
+}
+
 export function runSemanticLint(projectDir: string, includes: Includes): number {
-  const context = buildContext(projectDir, includes);
+  const manifest = readManifest(projectDir) as UnknownRecord;
+  const context = buildContext(projectDir, includes, manifest);
   let total = 0;
   const contractsDir = resolve(projectDir, includes.contracts);
 
   total += printSemanticErrors("locales", lintLocaleCoverage(context));
+  total += printSemanticErrors("openuispec.yaml", lintManifestGenerationContext(projectDir, context.manifest));
 
   const files = [
     join(projectDir, "openuispec.yaml"),

package/schema/validate.ts

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import type { ErrorObject } from "ajv";
 import YAML from "yaml";
-import { runSemanticLint, type Includes } from "./semantic-lint.js";
+import { runSemanticLint, collectSemanticLint, type Includes } from "./semantic-lint.js";
 
 const require = createRequire(import.meta.url);
 const Ajv2020 = require("ajv/dist/2020") as typeof import("ajv").default;
@@ -311,6 +311,71 @@ function lintFlowFile(dataPath: string): number {
   return errors.length;
 }
 
+// ── collect variants (structured errors for --json) ──────────────────
+
+interface JsonError {
+  file: string;
+  path: string;
+  message: string;
+}
+
+function collectValidateFile(
+  ajv: AjvInstance,
+  dataPath: string,
+  schemaId: string,
+  label?: string,
+): JsonError[] {
+  const name = label ?? basename(dataPath);
+  const data = loadData(dataPath);
+  const validate = ajv.getSchema(schemaId);
+
+  if (!validate) {
+    return [{ file: name, path: "(root)", message: `schema ${schemaId} not found` }];
+  }
+
+  const valid = validate(data);
+  if (valid) return [];
+
+  const errors: ErrorObject[] = validate.errors ?? [];
+  return errors.map((e) => ({
+    file: name,
+    path: e.instancePath || "(root)",
+    message: e.message ?? "unknown error",
+  }));
+}
+
+function collectLintScreenFile(dataPath: string): JsonError[] {
+  const root = getSingleRootValue(loadData(dataPath));
+  const errors = lintScreenLikeDefinition(root, basename(dataPath));
+  return errors.map((e) => ({
+    file: basename(dataPath),
+    path: e.path,
+    message: e.message,
+  }));
+}
+
+function collectLintFlowFile(dataPath: string): JsonError[] {
+  const root = getSingleRootValue(loadData(dataPath));
+  if (!isRecord(root) || !isRecord(root.screens)) return [];
+
+  const errors: UsageLint[] = [];
+  for (const [screenId, screenEntry] of Object.entries(root.screens)) {
+    if (!isRecord(screenEntry) || !isRecord(screenEntry.screen_inline)) continue;
+    errors.push(
+      ...lintScreenLikeDefinition(
+        screenEntry.screen_inline,
+        `${basename(dataPath)}/screens/${screenId}/screen_inline`,
+      ),
+    );
+  }
+
+  return errors.map((e) => ({
+    file: basename(dataPath),
+    path: e.path,
+    message: e.message,
+  }));
+}
+
 // ── build Ajv instance with all schemas ──────────────────────────────
 
 function buildAjv(): AjvInstance {
@@ -436,9 +501,15 @@ function resolveInclude(projectDir: string, includePath: string): string {
 
 // ── validation groups ────────────────────────────────────────────────
 
+interface JsonGroupResult {
+  group: string;
+  errors: JsonError[];
+}
+
 interface ValidationGroup {
   label: string;
   run(ajv: AjvInstance, projectDir: string, includes: Includes): number;
+  collectJson(ajv: AjvInstance, projectDir: string, includes: Includes, groupKey: string): JsonGroupResult;
 }
 
 const GROUPS: Record<string, ValidationGroup> = {
@@ -451,6 +522,12 @@ const GROUPS: Record<string, ValidationGroup> = {
         `${BASE}openuispec.schema.json`,
       );
     },
+    collectJson(ajv, projectDir, _includes, groupKey) {
+      return {
+        group: groupKey,
+        errors: collectValidateFile(ajv, join(projectDir, "openuispec.yaml"), `${BASE}openuispec.schema.json`),
+      };
+    },
   },
 
   tokens: {
@@ -476,6 +553,27 @@ const GROUPS: Record<string, ValidationGroup> = {
       }
       return errors;
     },
+    collectJson(ajv, projectDir, includes, groupKey) {
+      const errors: JsonError[] = [];
+      const tokensDir = resolveInclude(projectDir, includes.tokens);
+      const tokenMap: Record<string, string> = {
+        "color.yaml": "color.schema.json",
+        "typography.yaml": "typography.schema.json",
+        "spacing.yaml": "spacing.schema.json",
+        "elevation.yaml": "elevation.schema.json",
+        "motion.yaml": "motion.schema.json",
+        "layout.yaml": "layout.schema.json",
+        "themes.yaml": "themes.schema.json",
+        "icons.yaml": "icons.schema.json",
+      };
+      for (const [data, schema] of Object.entries(tokenMap)) {
+        const filePath = join(tokensDir, data);
+        if (existsSync(filePath)) {
+          errors.push(...collectValidateFile(ajv, filePath, `${BASE}tokens/${schema}`));
+        }
+      }
+      return { group: groupKey, errors };
+    },
   },
 
   screens: {
@@ -492,6 +590,18 @@ const GROUPS: Record<string, ValidationGroup> = {
       }
       return errors;
     },
+    collectJson(ajv, projectDir, includes, groupKey) {
+      const errors: JsonError[] = [];
+      const dir = resolveInclude(projectDir, includes.screens);
+      for (const f of listFiles(dir, ".yaml")) {
+        const schemaErrors = collectValidateFile(ajv, f, `${BASE}screen.schema.json`);
+        errors.push(...schemaErrors);
+        if (schemaErrors.length === 0) {
+          errors.push(...collectLintScreenFile(f));
+        }
+      }
+      return { group: groupKey, errors };
+    },
   },
 
   flows: {
@@ -508,6 +618,18 @@ const GROUPS: Record<string, ValidationGroup> = {
       }
       return errors;
     },
+    collectJson(ajv, projectDir, includes, groupKey) {
+      const errors: JsonError[] = [];
+      const dir = resolveInclude(projectDir, includes.flows);
+      for (const f of listFiles(dir, ".yaml")) {
+        const schemaErrors = collectValidateFile(ajv, f, `${BASE}flow.schema.json`);
+        errors.push(...schemaErrors);
+        if (schemaErrors.length === 0) {
+          errors.push(...collectLintFlowFile(f));
+        }
+      }
+      return { group: groupKey, errors };
+    },
   },
 
   platform: {
@@ -520,6 +642,14 @@ const GROUPS: Record<string, ValidationGroup> = {
       }
       return errors;
     },
+    collectJson(ajv, projectDir, includes, groupKey) {
+      const errors: JsonError[] = [];
+      const dir = resolveInclude(projectDir, includes.platform);
+      for (const f of listFiles(dir, ".yaml")) {
+        errors.push(...collectValidateFile(ajv, f, `${BASE}platform.schema.json`));
+      }
+      return { group: groupKey, errors };
+    },
   },
 
   locales: {
@@ -532,6 +662,14 @@ const GROUPS: Record<string, ValidationGroup> = {
       }
       return errors;
     },
+    collectJson(ajv, projectDir, includes, groupKey) {
+      const errors: JsonError[] = [];
+      const dir = resolveInclude(projectDir, includes.locales);
+      for (const f of listFiles(dir, ".json")) {
+        errors.push(...collectValidateFile(ajv, f, `${BASE}locale.schema.json`));
+      }
+      return { group: groupKey, errors };
+    },
   },
 
   contracts: {
@@ -549,6 +687,19 @@ const GROUPS: Record<string, ValidationGroup> = {
       }
       return errors;
     },
+    collectJson(ajv, projectDir, includes, groupKey) {
+      const errors: JsonError[] = [];
+      const dir = resolveInclude(projectDir, includes.contracts);
+      for (const f of listFiles(dir, ".yaml")) {
+        const name = basename(f);
+        if (name.startsWith("x_")) {
+          errors.push(...collectValidateFile(ajv, f, `${BASE}custom-contract.schema.json`));
+        } else {
+          errors.push(...collectValidateFile(ajv, f, `${BASE}contract.schema.json`));
+        }
+      }
+      return { group: groupKey, errors };
+    },
   },
 
   semantic: {
@@ -556,6 +707,17 @@ const GROUPS: Record<string, ValidationGroup> = {
     run(_ajv, projectDir, includes) {
       return runSemanticLint(projectDir, includes);
     },
+    collectJson(_ajv, projectDir, includes, groupKey) {
+      const lintErrors = collectSemanticLint(projectDir, includes);
+      return {
+        group: groupKey,
+        errors: lintErrors.map((e) => ({
+          file: e.path.includes("/") ? e.path.split("/")[0] : e.path,
+          path: e.path,
+          message: e.message,
+        })),
+      };
+    },
   },
 };
 
@@ -590,22 +752,47 @@ function findProjectDir(cwd: string): string {
 
 // ── main ─────────────────────────────────────────────────────────────
 
+export { buildAjv, readIncludes, GROUPS };
+export type { JsonGroupResult, JsonError };
+
 export function runValidate(argv: string[]): void {
+  const jsonMode = argv.includes("--json");
+  const filteredArgs = argv.filter((a) => a !== "--json");
+
   const selected =
-    argv.length > 0
-      ? argv.filter((a) => a in GROUPS)
+    filteredArgs.length > 0
+      ? filteredArgs.filter((a) => a in GROUPS)
       : Object.keys(GROUPS);
 
   if (selected.length === 0) {
     console.error(
       `Unknown group(s). Available: ${Object.keys(GROUPS).join(", ")}`,
     );
-    process.exit(2);
+    process.exit(1);
   }
 
   const projectDir = findProjectDir(process.cwd());
   const includes = readIncludes(projectDir);
   const ajv = buildAjv();
+
+  if (jsonMode) {
+    const groups: JsonGroupResult[] = [];
+    let totalErrors = 0;
+
+    for (const key of selected) {
+      const result = GROUPS[key].collectJson(ajv, projectDir, includes, key);
+      groups.push(result);
+      totalErrors += result.errors.length;
+    }
+
+    console.log(JSON.stringify({ groups, total_errors: totalErrors }, null, 2));
+
+    if (totalErrors > 0) {
+      process.exit(2);
+    }
+    return;
+  }
+
   let totalErrors = 0;
 
   for (const key of selected) {
@@ -617,7 +804,7 @@ export function runValidate(argv: string[]): void {
   console.log(`\n${"=".repeat(50)}`);
   if (totalErrors > 0) {
     console.log(`FAILED: ${totalErrors} total validation error(s)`);
-    process.exit(1);
+    process.exit(2);
   } else {
     console.log("ALL PASSED: Every example file validates successfully");
   }

package/status/index.ts

@@ -40,6 +40,8 @@ interface TargetStatus {
   removed: number;
   behind: boolean;
   explain_available: boolean;
+  status: "up to date" | "behind" | "needs baseline" | "needs generation";
+  recommended_next_step: string;
   note?: string;
 }
 
@@ -96,6 +98,10 @@ function buildTargetStatus(cwd: string, projectDir: string, projectName: string,
       removed: 0,
       behind: false,
       explain_available: false,
+      status: outputExists ? "needs baseline" : "needs generation",
+      recommended_next_step: outputExists
+        ? `Run \`openuispec drift --snapshot --target ${target}\` after reviewing the generated output.`
+        : `Run code generation for "${target}", then \`openuispec prepare --target ${target}\` to build the target work bundle.`,
       note: outputExists
         ? "No snapshot found for this target."
         : `Output directory not found. Run code generation for "${target}" first.`,
@@ -126,6 +132,11 @@ function buildTargetStatus(cwd: string, projectDir: string, projectName: string,
     removed,
     behind: changed + added + removed > 0,
     explain_available: explanation.available,
+    status: changed + added + removed > 0 ? "behind" : "up to date",
+    recommended_next_step:
+      changed + added + removed > 0
+        ? `Run \`openuispec prepare --target ${target}\` to build the target work bundle for the pending spec changes.`
+        : `No immediate action required for "${target}". Re-run \`openuispec status\` after spec changes or after re-baselining.`,
     note: explanation.available ? undefined : explanation.note,
   };
 }
@@ -156,12 +167,6 @@ function printReport(result: StatusResult): void {
       : target.output_exists
         ? "no snapshot"
         : "output missing";
-    const status = target.snapshot
-      ? (target.behind ? "behind" : "up to date")
-      : target.output_exists
-        ? "needs baseline"
-        : "needs generation";
-
     console.log(`${target.target}`);
     console.log(`  output: ${target.output_dir}`);
     console.log(`  output exists: ${target.output_exists ? "yes" : "no"}`);
@@ -170,11 +175,12 @@ function printReport(result: StatusResult): void {
       console.log(`  baseline: ${target.baseline.label}`);
     }
     console.log(`  drift: ${summary}`);
-    console.log(`  status: ${status}`);
+    console.log(`  status: ${target.status}`);
     console.log(`  explain: ${target.explain_available ? "available" : "unavailable"}`);
     if (target.note) {
       console.log(`  note: ${target.note}`);
     }
+    console.log(`  next: ${target.recommended_next_step}`);
     console.log("");
   }
 }