openuispec 0.1.29 → 0.1.30

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("");
   }
 }