openuispec 0.1.25 → 0.1.27

package/drift/index.ts

@@ -10,6 +10,7 @@
  *   openuispec drift --target ios           # check drift for ios
  *   openuispec drift                        # check all targets with snapshots
  *   openuispec drift --snapshot --target ios # snapshot for ios
+ *   openuispec drift --target ios --explain # explain semantic changes since baseline
  *   openuispec drift --json --target ios    # machine-readable output
  *   openuispec drift --target ios --all     # include stubs in drift count
  */
@@ -17,6 +18,7 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
 import { resolve, join, relative, basename, dirname } from "node:path";
 import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import YAML from "yaml";
 
 const STATE_FILE = ".openuispec-state.json";
@@ -28,20 +30,47 @@ interface FileEntry {
   status: string;
 }
 
-interface StateFile {
+export interface StateFile {
   spec_version: string;
   snapshot_at: string;
   target: string;
+  baseline?: BaselineRef;
   files: Record<string, FileEntry>;
 }
 
-interface DriftResult {
+export interface BaselineRef {
+  kind: "git_commit" | "working_tree";
+  commit: string | null;
+  branch: string | null;
+}
+
+export interface DriftResult {
   changed: string[];
   added: string[];
   removed: string[];
   unchanged: string[];
 }
 
+export interface SemanticChange {
+  kind: "added" | "removed" | "changed";
+  path: string;
+  before?: string;
+  after?: string;
+}
+
+export interface FileExplanation {
+  file: string;
+  status: "added" | "removed" | "changed";
+  changes: SemanticChange[];
+  truncated: boolean;
+}
+
+export interface ExplainResult {
+  available: boolean;
+  note?: string;
+  files: FileExplanation[];
+}
+
 // ── helpers ───────────────────────────────────────────────────────────
 
 function listFiles(dir: string, ext: string): string[] {
@@ -61,6 +90,21 @@ function hashFile(filePath: string): string {
   return `sha256:${hash}`;
 }
 
+function readFileIfExists(filePath: string): string | null {
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function parseSpecDocument(relPath: string, content: string): unknown {
+  if (relPath.endsWith(".json")) {
+    return JSON.parse(content);
+  }
+  return YAML.parse(content);
+}
+
 /** Read the status field from a screen or flow YAML file. */
 function readStatus(filePath: string): string {
   try {
@@ -129,10 +173,249 @@ function categorize(relPath: string): string {
   return "Other";
 }
 
+function runGit(args: string[], cwd: string): string | null {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function gitPathForFile(projectDir: string, relPath: string): string | null {
+  const repoRoot = runGit(["rev-parse", "--show-toplevel"], projectDir);
+  if (!repoRoot) return null;
+  return relative(repoRoot, join(projectDir, relPath));
+}
+
+function readFileFromGit(projectDir: string, commit: string, relPath: string): string | null {
+  const gitPath = gitPathForFile(projectDir, relPath);
+  if (!gitPath) return null;
+  return runGit(["show", `${commit}:${gitPath}`], projectDir);
+}
+
+function captureBaseline(projectDir: string, files: string[]): BaselineRef | undefined {
+  const repoRoot = runGit(["rev-parse", "--show-toplevel"], projectDir);
+  if (!repoRoot) return undefined;
+
+  const branch = runGit(["branch", "--show-current"], projectDir);
+  const commit = runGit(["rev-parse", "HEAD"], projectDir);
+  const repoPaths = files.map((file) => relative(repoRoot, file));
+  const status = runGit(["status", "--porcelain", "--", ...repoPaths], projectDir) ?? "";
+
+  return {
+    kind: status.length > 0 ? "working_tree" : "git_commit",
+    commit,
+    branch: branch || null,
+  };
+}
+
+export function formatBaseline(baseline?: BaselineRef): string | null {
+  if (!baseline) return null;
+
+  const ref = baseline.commit ? baseline.commit.slice(0, 12) : "uncommitted";
+  const branchSuffix = baseline.branch ? ` on ${baseline.branch}` : "";
+
+  if (baseline.kind === "git_commit") {
+    return `${ref}${branchSuffix} (exact git baseline)`;
+  }
+
+  return `${ref}${branchSuffix} + working tree spec changes`;
+}
+
+const MAX_CHANGES_PER_FILE = 20;
+const MAX_VALUE_LENGTH = 120;
+
+function summarizeValue(value: unknown): string {
+  if (typeof value === "string") {
+    return value.length > MAX_VALUE_LENGTH
+      ? JSON.stringify(`${value.slice(0, MAX_VALUE_LENGTH - 1)}…`)
+      : JSON.stringify(value);
+  }
+
+  const serialized = JSON.stringify(value);
+  if (!serialized) return String(value);
+  return serialized.length > MAX_VALUE_LENGTH
+    ? `${serialized.slice(0, MAX_VALUE_LENGTH - 1)}…`
+    : serialized;
+}
+
+function compareSemanticValue(
+  path: string,
+  before: unknown,
+  after: unknown,
+  changes: SemanticChange[]
+): void {
+  if (changes.length >= MAX_CHANGES_PER_FILE) return;
+
+  if (before === undefined && after === undefined) return;
+  if (before === undefined) {
+    changes.push({ kind: "added", path, after: summarizeValue(after) });
+    return;
+  }
+  if (after === undefined) {
+    changes.push({ kind: "removed", path, before: summarizeValue(before) });
+    return;
+  }
+
+  if (Array.isArray(before) || Array.isArray(after)) {
+    if (!Array.isArray(before) || !Array.isArray(after)) {
+      changes.push({
+        kind: "changed",
+        path,
+        before: summarizeValue(before),
+        after: summarizeValue(after),
+      });
+      return;
+    }
+
+    const maxLength = Math.max(before.length, after.length);
+    for (let index = 0; index < maxLength; index += 1) {
+      compareSemanticValue(`${path}[${index}]`, before[index], after[index], changes);
+      if (changes.length >= MAX_CHANGES_PER_FILE) return;
+    }
+    return;
+  }
+
+  if (
+    before &&
+    after &&
+    typeof before === "object" &&
+    typeof after === "object"
+  ) {
+    const beforeObj = before as Record<string, unknown>;
+    const afterObj = after as Record<string, unknown>;
+    const keys = Array.from(new Set([...Object.keys(beforeObj), ...Object.keys(afterObj)])).sort();
+
+    for (const key of keys) {
+      const nextPath = path ? `${path}.${key}` : key;
+      compareSemanticValue(nextPath, beforeObj[key], afterObj[key], changes);
+      if (changes.length >= MAX_CHANGES_PER_FILE) return;
+    }
+    return;
+  }
+
+  if (before !== after) {
+    changes.push({
+      kind: "changed",
+      path,
+      before: summarizeValue(before),
+      after: summarizeValue(after),
+    });
+  }
+}
+
+function explainFileChange(
+  projectDir: string,
+  baselineCommit: string,
+  relPath: string,
+  status: "added" | "removed" | "changed"
+): FileExplanation {
+  if (status === "added") {
+    return {
+      file: relPath,
+      status,
+      changes: [{ kind: "added", path: relPath }],
+      truncated: false,
+    };
+  }
+
+  if (status === "removed") {
+    return {
+      file: relPath,
+      status,
+      changes: [{ kind: "removed", path: relPath }],
+      truncated: false,
+    };
+  }
+
+  const beforeContent = readFileFromGit(projectDir, baselineCommit, relPath);
+  const afterContent = readFileIfExists(join(projectDir, relPath));
+
+  if (!beforeContent || !afterContent) {
+    return {
+      file: relPath,
+      status,
+      changes: [
+        {
+          kind: "changed",
+          path: relPath,
+          before: beforeContent ? "available" : "missing from baseline",
+          after: afterContent ? "available" : "missing from working tree",
+        },
+      ],
+      truncated: false,
+    };
+  }
+
+  try {
+    const beforeDoc = parseSpecDocument(relPath, beforeContent);
+    const afterDoc = parseSpecDocument(relPath, afterContent);
+    const changes: SemanticChange[] = [];
+    compareSemanticValue("", beforeDoc, afterDoc, changes);
+
+    return {
+      file: relPath,
+      status,
+      changes,
+      truncated: changes.length >= MAX_CHANGES_PER_FILE,
+    };
+  } catch (error) {
+    return {
+      file: relPath,
+      status,
+      changes: [
+        {
+          kind: "changed",
+          path: relPath,
+          after: error instanceof Error ? error.message : "unable to parse file diff",
+        },
+      ],
+      truncated: false,
+    };
+  }
+}
+
+export function explainDrift(projectDir: string, result: CheckResult): ExplainResult {
+  const baseline = result.state.baseline;
+  if (!baseline?.commit) {
+    return {
+      available: false,
+      note: "No git baseline metadata found in snapshot. Re-run `openuispec drift --snapshot --target <target>` from a git checkout.",
+      files: [],
+    };
+  }
+
+  if (baseline.kind !== "git_commit") {
+    return {
+      available: false,
+      note: "Snapshot was created from a dirty working tree, so semantic diff cannot reconstruct the exact baseline. Re-snapshot from a clean commit for precise explanations.",
+      files: [],
+    };
+  }
+
+  const files: FileExplanation[] = [];
+  for (const relPath of result.drift.added) {
+    files.push(explainFileChange(projectDir, baseline.commit, relPath, "added"));
+  }
+  for (const relPath of result.drift.removed) {
+    files.push(explainFileChange(projectDir, baseline.commit, relPath, "removed"));
+  }
+  for (const relPath of result.drift.changed) {
+    files.push(explainFileChange(projectDir, baseline.commit, relPath, "changed"));
+  }
+
+  files.sort((a, b) => a.file.localeCompare(b.file));
+  return { available: true, files };
+}
+
 // ── project resolution ───────────────────────────────────────────────
 
 /** Find the spec project directory by looking for openuispec.yaml. */
-function findProjectDir(cwd: string): string {
+export function findProjectDir(cwd: string): string {
   const candidates = [
     join(cwd, "openuispec"),
     cwd,
@@ -152,7 +435,7 @@ function findProjectDir(cwd: string): string {
 }
 
 /** Read the project name from the manifest. */
-function readProjectName(projectDir: string): string {
+export function readProjectName(projectDir: string): string {
   const doc = YAML.parse(
     readFileSync(join(projectDir, "openuispec.yaml"), "utf-8")
   );
@@ -160,7 +443,7 @@ function readProjectName(projectDir: string): string {
 }
 
 /** Read per-target output_dir map from the manifest. */
-function readOutputDirs(projectDir: string): Record<string, string> {
+export function readOutputDirs(projectDir: string): Record<string, string> {
   try {
     const doc = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
     return doc.generation?.output_dir ?? {};
@@ -170,7 +453,7 @@ function readOutputDirs(projectDir: string): Record<string, string> {
 }
 
 /** Resolve the generated output directory for a target. */
-function resolveOutputDir(projectDir: string, projectName: string, target: string): string {
+export function resolveOutputDir(projectDir: string, projectName: string, target: string): string {
   const outputDirs = readOutputDirs(projectDir);
   if (outputDirs[target]) {
     return resolve(projectDir, outputDirs[target]);
@@ -179,11 +462,11 @@ function resolveOutputDir(projectDir: string, projectName: string, target: strin
   return resolve(projectDir, "..", "generated", target, projectName);
 }
 
-function stateFilePath(projectDir: string, projectName: string, target: string): string {
+export function stateFilePath(projectDir: string, projectName: string, target: string): string {
   return join(resolveOutputDir(projectDir, projectName, target), STATE_FILE);
 }
 
-function discoverTargets(projectDir: string, projectName: string): string[] {
+export function discoverTargets(projectDir: string, projectName: string): string[] {
   const outputDirs = readOutputDirs(projectDir);
   const targets: string[] = [];
 
@@ -241,6 +524,7 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
 
   const files = discoverSpecFiles(projectDir);
   const doc = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+  const baseline = captureBaseline(projectDir, files);
 
   const entries: Record<string, FileEntry> = {};
   let stubCount = 0;
@@ -256,6 +540,7 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
     spec_version: doc.spec_version ?? "0.1",
     snapshot_at: new Date().toISOString(),
     target,
+    baseline,
     files: entries,
   };
 
@@ -267,18 +552,23 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
     console.log(`  ${stubCount} stubs (not tracked for drift)`);
   }
   console.log(`  target: ${target}`);
+  const baselineLabel = formatBaseline(baseline);
+  if (baselineLabel) {
+    console.log(`  baseline: ${baselineLabel}`);
+  }
 }
 
 // ── check ─────────────────────────────────────────────────────────────
 
-interface CheckResult {
+export interface CheckResult {
   state: StateFile;
   drift: DriftResult;
   stubDrift: DriftResult;
   statuses: Record<string, string>;
+  explanation?: ExplainResult;
 }
 
-function computeDrift(
+export function computeDrift(
   projectDir: string,
   state: StateFile,
   includeAll: boolean
@@ -326,13 +616,13 @@ function computeDrift(
   return { state, drift, stubDrift, statuses };
 }
 
-function check(
+export function loadTargetDrift(
   cwd: string,
-  projectDir: string,
   target: string,
-  jsonOutput: boolean,
-  includeAll: boolean
-): void {
+  includeAll: boolean,
+  explainOutput: boolean
+): { projectDir: string; projectName: string; statePath: string; result: CheckResult } {
+  const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
   const statePath = stateFilePath(projectDir, projectName, target);
   if (!existsSync(statePath)) {
@@ -345,6 +635,22 @@ function check(
 
   const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
   const result = computeDrift(projectDir, state, includeAll);
+  if (explainOutput) {
+    result.explanation = explainDrift(projectDir, result);
+  }
+
+  return { projectDir, projectName, statePath, result };
+}
+
+function check(
+  cwd: string,
+  projectDir: string,
+  target: string,
+  jsonOutput: boolean,
+  includeAll: boolean,
+  explainOutput: boolean
+): void {
+  const { result } = loadTargetDrift(cwd, target, includeAll, explainOutput);
 
   if (jsonOutput) {
     printJson(result);
@@ -361,7 +667,8 @@ function checkAll(
   cwd: string,
   projectDir: string,
   jsonOutput: boolean,
-  includeAll: boolean
+  includeAll: boolean,
+  explainOutput: boolean
 ): void {
   const projectName = readProjectName(projectDir);
   const targets = discoverTargets(projectDir, projectName);
@@ -378,6 +685,9 @@ function checkAll(
     const statePath = stateFilePath(projectDir, projectName, target);
     const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
     const result = computeDrift(projectDir, state, includeAll);
+    if (explainOutput) {
+      result.explanation = explainDrift(projectDir, result);
+    }
 
     if (jsonOutput) {
       printJson(result);
@@ -411,7 +721,9 @@ function printJson(result: CheckResult): void {
       {
         snapshot_at: result.state.snapshot_at,
         target: result.state.target,
+        baseline: result.state.baseline,
         ...result.drift,
+        explanation: result.explanation,
         stubs: stubTotal > 0 ? result.stubDrift : undefined,
       },
       null,
@@ -428,6 +740,10 @@ function printReport(projectDir: string, result: CheckResult): void {
   console.log(`Project: ${projectName}`);
   console.log(`Snapshot: ${result.state.snapshot_at}`);
   console.log(`Target: ${result.state.target}`);
+  const baselineLabel = formatBaseline(result.state.baseline);
+  if (baselineLabel) {
+    console.log(`Baseline: ${baselineLabel}`);
+  }
 
   const d = result.drift;
 
@@ -500,6 +816,46 @@ function printReport(projectDir: string, result: CheckResult): void {
   console.log(
     `\nSummary: ${d.changed.length} changed, ${d.added.length} added, ${d.removed.length} removed${stubSuffix}`
   );
+
+  if (result.explanation) {
+    console.log("\nSemantic Changes");
+    console.log("----------------");
+
+    if (!result.explanation.available) {
+      console.log(result.explanation.note ?? "Semantic explanation unavailable.");
+      return;
+    }
+
+    if (result.explanation.files.length === 0) {
+      console.log("No semantic changes to explain.");
+      return;
+    }
+
+    for (const file of result.explanation.files) {
+      console.log(`\n${file.file}`);
+      if (file.changes.length === 0) {
+        console.log("  · no property-level changes detected");
+        continue;
+      }
+
+      for (const change of file.changes) {
+        const pathLabel = change.path || "(root)";
+        if (change.kind === "added") {
+          const value = change.after ? ` = ${change.after}` : "";
+          console.log(`  + ${pathLabel}${value}`);
+        } else if (change.kind === "removed") {
+          const value = change.before ? ` (was ${change.before})` : "";
+          console.log(`  - ${pathLabel}${value}`);
+        } else {
+          console.log(`  ~ ${pathLabel}: ${change.before ?? "?"} -> ${change.after ?? "?"}`);
+        }
+      }
+
+      if (file.truncated) {
+        console.log(`  … truncated after ${MAX_CHANGES_PER_FILE} changes`);
+      }
+    }
+  }
 }
 
 // ── main ──────────────────────────────────────────────────────────────
@@ -508,6 +864,7 @@ export function runDrift(argv: string[]): void {
   const isSnapshot = argv.includes("--snapshot");
   const isJson = argv.includes("--json");
   const includeAll = argv.includes("--all");
+  const explainOutput = argv.includes("--explain");
 
   const targetIdx = argv.indexOf("--target");
   const target = targetIdx !== -1 && argv[targetIdx + 1] ? argv[targetIdx + 1] : null;
@@ -523,9 +880,9 @@ export function runDrift(argv: string[]): void {
     }
     snapshot(cwd, projectDir, target);
   } else if (target) {
-    check(cwd, projectDir, target, isJson, includeAll);
+    check(cwd, projectDir, target, isJson, includeAll, explainOutput);
   } else {
-    checkAll(cwd, projectDir, isJson, includeAll);
+    checkAll(cwd, projectDir, isJson, includeAll, explainOutput);
   }
 }
 

package/examples/todo-orbit/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.22 -->
+<!-- openuispec-rules-version: 0.1.23 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -66,15 +66,22 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 
 ## After modifying spec files
 1. Run `openuispec validate` to check specs against the schema.
-2. **Update the generated code** for each affected platform to match the new spec.
-3. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
-4. Run `openuispec drift` to verify no untracked drift remains.
+2. Run `openuispec validate semantic`.
+3. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+4. Run `openuispec prepare --target <target>` to build the target update bundle.
+5. **Update the generated code** for each affected platform to match the new spec.
+6. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
+7. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+8. Run `openuispec status` to see which other targets are still behind.
 
 ## CLI commands
 - `openuispec init` — scaffold a new spec project
 - `openuispec validate [group...]` — validate spec files against schemas
+- `openuispec validate semantic` — run semantic cross-reference linting
 - `openuispec drift --target <t>` — check for spec drift
+- `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
 - `openuispec drift --snapshot --target <t>` — snapshot current state
+- `openuispec prepare --target <t>` — build an AI-ready target update bundle
 - `openuispec update-rules` — update AI rules to match installed package version
 - `openuispec drift --all` — include stubs in drift check
 <!-- openuispec-rules-end -->

package/examples/todo-orbit/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.22 -->
+<!-- openuispec-rules-version: 0.1.23 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -66,15 +66,22 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 
 ## After modifying spec files
 1. Run `openuispec validate` to check specs against the schema.
-2. **Update the generated code** for each affected platform to match the new spec.
-3. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
-4. Run `openuispec drift` to verify no untracked drift remains.
+2. Run `openuispec validate semantic`.
+3. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+4. Run `openuispec prepare --target <target>` to build the target update bundle.
+5. **Update the generated code** for each affected platform to match the new spec.
+6. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
+7. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+8. Run `openuispec status` to see which other targets are still behind.
 
 ## CLI commands
 - `openuispec init` — scaffold a new spec project
 - `openuispec validate [group...]` — validate spec files against schemas
+- `openuispec validate semantic` — run semantic cross-reference linting
 - `openuispec drift --target <t>` — check for spec drift
+- `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
 - `openuispec drift --snapshot --target <t>` — snapshot current state
+- `openuispec prepare --target <t>` — build an AI-ready target update bundle
 - `openuispec update-rules` — update AI rules to match installed package version
 - `openuispec drift --all` — include stubs in drift check
 <!-- openuispec-rules-end -->