openuispec 0.2.10 → 0.2.12

package/prepare/index.ts

@@ -21,10 +21,17 @@ import {
   readManifest,
   readProjectName,
   readStatus,
+  hasDriftChanges,
+  readSharedLayerState,
+  readTargetStructure,
   resolveOutputDir,
+  sharedLayersForTarget,
+  specCategory,
+  computeSharedDrift,
   type FileExplanation,
   type ExplainResult,
   type SemanticChange,
+  type SharedLayerConfig,
 } from "../drift/index.js";
 
 interface PrepareItem {
@@ -116,6 +123,20 @@ interface PrepareBootstrapBundle {
   reference_examples: string[];
 }
 
+interface SharedLayerInfo {
+  name: string;
+  platforms: string[];
+  language: string;
+  root: string;
+  paths: Record<string, string>;
+  scope: string;
+  tracks: string[];
+  already_generated: boolean;
+  generated_by_target: string | null;
+  has_drift: boolean;
+  guidance: string;
+}
+
 interface SpecFileContent {
   path: string;
   category: string;
@@ -135,6 +156,11 @@ export interface PrepareResult {
     commit: string | null;
     branch: string | null;
   };
+  baseline_status?: {
+    output_exists: boolean;
+    snapshot_exists: boolean;
+    action_needed: string | null;
+  };
   summary: {
     changed: number;
     added: number;
@@ -143,6 +169,7 @@ export interface PrepareResult {
   changes_available: boolean;
   explanation_note?: string;
   items: PrepareItem[];
+  shared_layers?: SharedLayerInfo[];
   bootstrap?: PrepareBootstrapBundle;
   spec_contents?: SpecFileContent[];
   next_steps: string[];
@@ -316,13 +343,88 @@ function resolveBackendRoot(projectDir: string, manifest: Record<string, any>):
   return resolve(projectDir, backendRoot);
 }
 
-function categorizeSpecFile(relPath: string): string {
-  if (relPath === "openuispec.yaml") return "manifest";
-  const group = relPath.split("/")[0];
-  return group || "other";
+// Use specCategory from drift/index.ts (imported above) instead of a local duplicate.
+const categorizeSpecFile = specCategory;
+
+function buildSharedLayerInfos(projectDir: string, target: string, layers?: SharedLayerConfig[]): SharedLayerInfo[] {
+  const resolvedLayers = layers ?? sharedLayersForTarget(projectDir, target);
+  if (resolvedLayers.length === 0) return [];
+
+  return resolvedLayers.map((layer) => {
+    const state = readSharedLayerState(layer);
+    const alreadyGenerated = state !== null;
+
+    // Only compute hash-based drift when tracks are configured
+    let hasDrift = false;
+    if (layer.tracks.length > 0) {
+      const driftResult = computeSharedDrift(projectDir, layer);
+      hasDrift = driftResult.state !== null && hasDriftChanges(driftResult.drift);
+    }
+
+    let guidance: string;
+    if (alreadyGenerated && !hasDrift) {
+      guidance = `Shared code already generated by ${state!.generated_by_target} — read existing code, don't regenerate.`;
+    } else if (alreadyGenerated && hasDrift) {
+      guidance = `Generated by ${state!.generated_by_target} but spec has drifted — review shared code for needed updates.`;
+    } else {
+      guidance = `Generate shared layer alongside ${target} platform code.`;
+    }
+
+    return {
+      name: layer.name,
+      platforms: layer.platforms,
+      language: layer.language,
+      root: layer.root,
+      paths: layer.paths,
+      scope: layer.scope,
+      tracks: layer.tracks,
+      already_generated: alreadyGenerated,
+      generated_by_target: state?.generated_by_target ?? null,
+      has_drift: hasDrift,
+      guidance,
+    };
+  });
+}
+
+function collectSharedLayerPaths(layers: SharedLayerConfig[]): string[] {
+  const paths: string[] = [];
+  for (const layer of layers) {
+    paths.push(layer.root);
+    for (const p of Object.values(layer.paths)) {
+      paths.push(resolve(layer.root, p));
+    }
+  }
+  return paths;
+}
+
+function dedupeExistingPaths(candidates: string[]): string[] {
+  const seen = new Set<string>();
+  return candidates
+    .map((c) => resolve(c))
+    .filter((c) => existsSync(c))
+    .filter((c) => {
+      if (seen.has(c)) return false;
+      seen.add(c);
+      return true;
+    });
 }
 
-function suggestCodeRoots(target: string, outputDir: string): string[] {
+function suggestCodeRoots(target: string, outputDir: string, projectDir?: string, sharedLayers?: SharedLayerConfig[]): string[] {
+  const layers = sharedLayers ?? (projectDir ? sharedLayersForTarget(projectDir, target) : []);
+
+  // When generation.structure is defined for the target, use it instead of heuristics
+  if (projectDir) {
+    const structure = readTargetStructure(projectDir, target);
+    if (structure) {
+      const candidates = [
+        structure.root,
+        ...Object.values(structure.paths).map((p) => resolve(structure.root, p)),
+        ...collectSharedLayerPaths(layers),
+      ];
+      return dedupeExistingPaths(candidates);
+    }
+  }
+
   const candidates: string[] = [];
 
   if (target === "web") {
@@ -340,15 +442,8 @@ function suggestCodeRoots(target: string, outputDir: string): string[] {
     candidates.push(outputDir);
   }
 
-  const seen = new Set<string>();
-  return candidates
-    .map((candidate) => resolve(candidate))
-    .filter((candidate) => existsSync(candidate))
-    .filter((candidate) => {
-      if (seen.has(candidate)) return false;
-      seen.add(candidate);
-      return true;
-    });
+  candidates.push(...collectSharedLayerPaths(layers));
+  return dedupeExistingPaths(candidates);
 }
 
 function walkFiles(root: string, files: string[], depth = 0): void {
@@ -506,7 +601,7 @@ function buildBootstrapNotes(category: string, target: string, specStatus: strin
   return notes;
 }
 
-function generationRules(target: string, outputDir: string, manifest: Record<string, any>): string[] {
+function generationRules(target: string, outputDir: string, manifest: Record<string, any>, sharedLayers?: SharedLayerInfo[]): string[] {
   const outputFormat = manifest.generation?.output_format?.[target] ?? {};
   const rules = [
     "Read openuispec.yaml first, then follow the referenced spec files instead of inventing structure from memory.",
@@ -523,6 +618,31 @@ function generationRules(target: string, outputDir: string, manifest: Record<str
     );
   }
 
+  if (sharedLayers && sharedLayers.length > 0) {
+    for (const layer of sharedLayers) {
+      if (layer.already_generated) {
+        rules.push(
+          `Shared layer "${layer.name}" already generated by ${layer.generated_by_target}. Read the existing code under ${layer.root} instead of regenerating it.`
+        );
+      } else {
+        rules.push(
+          `Generate shared layer "${layer.name}" (${layer.language}) under ${layer.root} alongside ${target} platform code.`
+        );
+      }
+      if (layer.scope) {
+        rules.push(
+          `Shared layer "${layer.name}" scope: ${layer.scope}`
+        );
+      }
+    }
+  }
+
+  // Include target structure scope when defined
+  const structure = manifest.generation?.structure?.[target];
+  if (structure?.scope) {
+    rules.push(`Target "${target}" scope: ${structure.scope}`);
+  }
+
   return rules;
 }
 
@@ -1065,8 +1185,10 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
   const platformDef = readPlatformDefinition(projectDir, manifest, target);
   const platformConfig = buildPlatformConfig(target, platformDef);
   const outputFormat = manifest.generation?.output_format?.[target] ?? {};
-  const codeRoots = suggestCodeRoots(target, outputDir);
+  const sharedLayerConfigs = sharedLayersForTarget(projectDir, target);
+  const codeRoots = suggestCodeRoots(target, outputDir, projectDir, sharedLayerConfigs);
   const missingDecisions = missingPlatformDecisions(target, platformDef);
+  const sharedLayerInfos = buildSharedLayerInfos(projectDir, target, sharedLayerConfigs);
   const backendRoot = resolveBackendRoot(projectDir, manifest);
   const backendContextReady = true; // backend is optional — not a generation blocker
   const pendingUserConfirmation = platformConfig.stack_confirmation.requires_user_confirmation;
@@ -1103,6 +1225,10 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
     );
   }
 
+  const outputDirExists = existsSync(outputDir);
+  const snapshotPath = join(outputDir, ".openuispec-state.json");
+  const snapshotFileExists = existsSync(snapshotPath);
+
   return {
     mode: "bootstrap",
     project: projectName,
@@ -1116,6 +1242,13 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
       commit: null,
       branch: null,
     },
+    baseline_status: {
+      output_exists: outputDirExists,
+      snapshot_exists: snapshotFileExists,
+      action_needed: outputDirExists && !snapshotFileExists
+        ? `Baseline pending — when satisfied with the generated output, run: openuispec drift --snapshot --target ${target}`
+        : null,
+    },
     summary: {
       changed: 0,
       added: 0,
@@ -1124,6 +1257,7 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
     changes_available: false,
     explanation_note: "No snapshot exists yet. This is a first-time generation bundle.",
     items: [],
+    ...(sharedLayerInfos.length > 0 ? { shared_layers: sharedLayerInfos } : {}),
     ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
     bootstrap: {
       output_exists: existsSync(outputDir),
@@ -1141,7 +1275,7 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
         supported_locales: manifest.i18n?.supported_locales ?? [],
       },
       spec_files: bootstrapSpecFiles(projectDir, target),
-      generation_rules: generationRules(target, outputDir, manifest),
+      generation_rules: generationRules(target, outputDir, manifest, sharedLayerInfos),
       generation_constraints: generationConstraints(target, platformConfig),
       generation_warnings: generationWarnings(target, platformConfig),
       reference_examples: referenceExamples(),
@@ -1153,8 +1287,10 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
 function buildUpdatePrepareResult(cwd: string, target: string, includeContents: boolean = false): PrepareResult {
   const { projectDir, projectName, result } = loadTargetDrift(cwd, target, false, true);
   const outputDir = resolveOutputDir(projectDir, projectName, target);
-  const codeRoots = suggestCodeRoots(target, outputDir);
+  const sharedLayerConfigs = sharedLayersForTarget(projectDir, target);
+  const codeRoots = suggestCodeRoots(target, outputDir, projectDir, sharedLayerConfigs);
   const manifest = readManifest(projectDir);
+  const sharedLayerInfos = buildSharedLayerInfos(projectDir, target, sharedLayerConfigs);
   const platformDef = readPlatformDefinition(projectDir, manifest, target);
   const platformConfig = buildPlatformConfig(target, platformDef);
   const outputFormat = manifest.generation?.output_format?.[target] ?? {};
@@ -1195,6 +1331,7 @@ function buildUpdatePrepareResult(cwd: string, target: string, includeContents:
     changes_available: result.explanation?.available ?? false,
     explanation_note: result.explanation?.note,
     items,
+    ...(sharedLayerInfos.length > 0 ? { shared_layers: sharedLayerInfos } : {}),
     ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
     next_steps: nextSteps,
   };

package/schema/openuispec.schema.json

@@ -152,6 +152,65 @@
             },
             "additionalProperties": true
           }
+        },
+        "shared": {
+          "type": "object",
+          "description": "Named shared code layers that span multiple targets (e.g. KMP common modules)",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "platforms": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "language": {
+                "type": "string"
+              },
+              "root": {
+                "type": "string"
+              },
+              "paths": {
+                "type": "object",
+                "additionalProperties": { "type": "string" }
+              },
+              "tracks": {
+                "type": "array",
+                "description": "Spec categories this shared layer tracks for drift. Must be explicit — choose which categories actually affect the shared code.",
+                "items": {
+                  "type": "string",
+                  "enum": ["manifest", "tokens", "contracts", "screens", "flows", "platform", "locales"]
+                }
+              },
+              "scope": {
+                "type": "string",
+                "description": "What code belongs in this shared layer (e.g. 'Business logic, data models, repositories, API clients, view models. No UI rendering.')"
+              }
+            },
+            "required": ["platforms", "language", "root", "scope"],
+            "additionalProperties": false
+          }
+        },
+        "structure": {
+          "type": "object",
+          "description": "Per-target output directory structure (overrides heuristic code root discovery)",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "root": {
+                "type": "string"
+              },
+              "paths": {
+                "type": "object",
+                "additionalProperties": { "type": "string" }
+              },
+              "scope": {
+                "type": "string",
+                "description": "What code belongs in this target directory (e.g. 'Pure SwiftUI views and navigation. All business logic comes from the shared layer.')"
+              }
+            },
+            "required": ["root"],
+            "additionalProperties": false
+          }
         }
       },
       "required": [

package/schema/semantic-lint.ts

@@ -5,6 +5,23 @@ import { listFiles, readManifest } from "../drift/index.js";
 
 type UnknownRecord = Record<string, unknown>;
 
+/** Collect all locale keys from a JSON object, supporting both flat dotted keys and nested objects. */
+function collectLocaleKeys(data: unknown, prefix = ""): string[] {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return [];
+  const keys: string[] = [];
+  for (const [key, value] of Object.entries(data as UnknownRecord)) {
+    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;
+}
+
 export interface Includes {
   tokens: string;
   contracts: string;
@@ -212,7 +229,14 @@ function buildContext(projectDir: string, includes: Includes, manifest: UnknownR
   for (const filePath of listFiles(localeDir, ".json")) {
     const localeName = basename(filePath, ".json");
     const data = loadJson(filePath);
-    localeFiles.set(localeName, new Set(Object.keys(data)));
+    // Support both flat dotted keys ("nav.home": "Home") and nested objects ({ nav: { home: "Home" } })
+    const flatKeys = Object.keys(data as object).filter(k => !k.startsWith("$"));
+    const hasNestedObjects = flatKeys.some(k => {
+      const v = (data as UnknownRecord)[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<string>([