@fragments-sdk/cli 0.11.1 → 0.13.0

package/src/commands/sync.ts

@@ -0,0 +1,357 @@
+/**
+ * fragments sync — Auto-update fragment files from component source.
+ *
+ * Detects drift between component source and fragment documentation,
+ * then updates fragment files to match. Preserves human-authored fields
+ * (usage, description, variants) while updating machine-derivable fields
+ * (props, composition, contract).
+ */
+
+import pc from 'picocolors';
+import { readFile, writeFile } from 'node:fs/promises';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import { discoverFragmentFiles, loadFragmentFile } from '../core/node.js';
+import { parseFragmentFile } from '../core/parser.js';
+import { resolveComponentSourcePath } from '../core/auto-props.js';
+import { createComponentExtractor, type PropMeta, type CompositionMeta } from '../core/component-extractor.js';
+import type { FragmentsConfig } from '@fragments-sdk/core';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface SyncOptions {
+  /** Path to config file */
+  config?: string;
+  /** Path to tsconfig.json */
+  tsconfig?: string;
+  /** Preview changes without writing */
+  dryRun?: boolean;
+  /** Sync specific component only */
+  component?: string;
+}
+
+export interface SyncedComponent {
+  name: string;
+  file: string;
+  changes: string[];
+}
+
+export interface SyncResult {
+  success: boolean;
+  updated: SyncedComponent[];
+  skipped: Array<{ name: string; reason: string }>;
+  errors: Array<{ file: string; message: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export async function sync(options: SyncOptions = {}): Promise<SyncResult> {
+  const { config, configDir } = await loadConfig(options.config);
+
+  console.log(pc.cyan(`\n${BRAND.name} Sync\n`));
+
+  if (options.dryRun) {
+    console.log(pc.dim('Dry run — no files will be modified.\n'));
+  }
+
+  const result = await runSync(config, configDir, options);
+
+  // Print updated
+  if (result.updated.length > 0) {
+    const verb = options.dryRun ? 'Would update' : 'Updated';
+    console.log(pc.bold(`${verb} ${result.updated.length} fragment(s):\n`));
+    for (const comp of result.updated) {
+      console.log(`  ${pc.green('✓')} ${pc.bold(comp.name)} ${pc.dim(`(${comp.file})`)}`);
+      for (const change of comp.changes) {
+        console.log(`    ${pc.dim('•')} ${change}`);
+      }
+    }
+    console.log();
+  }
+
+  // Print skipped
+  if (result.skipped.length > 0) {
+    console.log(pc.dim(`Skipped ${result.skipped.length}: ${result.skipped.map(s => s.name).join(', ')}\n`));
+  }
+
+  // Print errors
+  if (result.errors.length > 0) {
+    console.log(pc.red(pc.bold('Errors:')));
+    for (const err of result.errors) {
+      console.log(`  ${pc.red('✗')} ${pc.bold(err.file)}: ${err.message}`);
+    }
+    console.log();
+  }
+
+  // Summary
+  if (result.updated.length === 0 && result.errors.length === 0) {
+    console.log(pc.green('All fragments are in sync — nothing to update.\n'));
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Core sync logic
+// ---------------------------------------------------------------------------
+
+async function runSync(
+  config: FragmentsConfig,
+  configDir: string,
+  options: SyncOptions
+): Promise<SyncResult> {
+  const fragmentFiles = await discoverFragmentFiles(config, configDir);
+  const updated: SyncedComponent[] = [];
+  const skipped: Array<{ name: string; reason: string }> = [];
+  const errors: Array<{ file: string; message: string }> = [];
+
+  if (fragmentFiles.length === 0) {
+    return { success: true, updated, skipped, errors };
+  }
+
+  const extractor = createComponentExtractor(options.tsconfig);
+
+  try {
+    for (const file of fragmentFiles) {
+      try {
+        const fragment = await loadFragmentFile(file.absolutePath);
+        if (!fragment?.meta?.name) continue;
+
+        // Filter to specific component if requested
+        if (options.component && fragment.meta.name !== options.component) continue;
+
+        // Parse fragment source to find component import
+        const fileContent = await readFile(file.absolutePath, 'utf-8');
+        const parsed = parseFragmentFile(fileContent, file.absolutePath);
+        if (!parsed.componentImport) {
+          skipped.push({ name: fragment.meta.name, reason: 'No component import found' });
+          continue;
+        }
+
+        // Resolve source path
+        const sourcePath = resolveComponentSourcePath(file.absolutePath, parsed.componentImport);
+        if (!sourcePath) {
+          skipped.push({ name: fragment.meta.name, reason: 'Cannot resolve component source' });
+          continue;
+        }
+
+        // Extract current state from source
+        const meta = extractor.extract(sourcePath, fragment.meta.name);
+        if (!meta) {
+          skipped.push({ name: fragment.meta.name, reason: 'Extraction returned null' });
+          continue;
+        }
+
+        // Compute the patch
+        const patch = computePatch(fileContent, fragment, meta);
+        if (patch.changes.length === 0) {
+          skipped.push({ name: fragment.meta.name, reason: 'Already in sync' });
+          continue;
+        }
+
+        if (!options.dryRun) {
+          await writeFile(file.absolutePath, patch.updatedContent, 'utf-8');
+        }
+
+        updated.push({
+          name: fragment.meta.name,
+          file: file.relativePath,
+          changes: patch.changes,
+        });
+      } catch (err) {
+        errors.push({
+          file: file.relativePath,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } finally {
+    extractor.dispose();
+  }
+
+  return {
+    success: errors.length === 0,
+    updated,
+    skipped,
+    errors,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Patch computation — text-level updates to fragment file
+// ---------------------------------------------------------------------------
+
+interface PatchResult {
+  updatedContent: string;
+  changes: string[];
+}
+
+/**
+ * Compute text-level patches for a fragment file based on extracted metadata.
+ *
+ * Strategy: find the `props: { ... }` block in the source and replace it with
+ * an updated version that includes new props. Preserves human-authored prop
+ * entries (descriptions, constraints) while adding missing props and removing
+ * stale ones.
+ */
+function computePatch(
+  fileContent: string,
+  fragment: { meta: { name: string }; props: Record<string, unknown>; ai?: { compositionPattern?: string; subComponents?: string[] } },
+  meta: { props: Record<string, PropMeta>; composition: CompositionMeta | null }
+): PatchResult {
+  const changes: string[] = [];
+  let content = fileContent;
+
+  // Filter to local props only
+  const localSourceProps = Object.fromEntries(
+    Object.entries(meta.props).filter(([_, p]) => p.source === 'local')
+  );
+
+  // Detect added props
+  const addedProps: string[] = [];
+  for (const name of Object.keys(localSourceProps)) {
+    if (!(name in fragment.props)) {
+      addedProps.push(name);
+    }
+  }
+
+  // Detect removed props
+  const removedProps: string[] = [];
+  for (const name of Object.keys(fragment.props)) {
+    if (!(name in localSourceProps)) {
+      removedProps.push(name);
+    }
+  }
+
+  // Apply prop additions — insert before the closing brace of the props block
+  if (addedProps.length > 0) {
+    const propsBlockEnd = findPropsBlockEnd(content);
+    if (propsBlockEnd !== -1) {
+      const newEntries = addedProps.map(name => {
+        const prop = localSourceProps[name];
+        return formatPropEntry(name, prop);
+      }).join('\n');
+
+      content = content.slice(0, propsBlockEnd) + newEntries + '\n  ' + content.slice(propsBlockEnd);
+      changes.push(`Added props: ${addedProps.join(', ')}`);
+    }
+  }
+
+  // Apply prop removals — comment out removed props
+  if (removedProps.length > 0) {
+    for (const name of removedProps) {
+      // Match the prop entry line(s) — find `propName: {` and its block
+      const propRegex = new RegExp(`([ \\t]*)${escapeRegex(name)}:\\s*\\{`, 'g');
+      const match = propRegex.exec(content);
+      if (match) {
+        const indent = match[1];
+        const startIdx = match.index;
+        // Find the matching closing brace
+        const endIdx = findMatchingBrace(content, match.index + match[0].length - 1);
+        if (endIdx !== -1) {
+          // Find the end of the line after the closing brace (include trailing comma)
+          let lineEnd = endIdx + 1;
+          if (content[lineEnd] === ',') lineEnd++;
+          if (content[lineEnd] === '\n') lineEnd++;
+
+          const removedBlock = content.slice(startIdx, lineEnd);
+          const commented = removedBlock
+            .split('\n')
+            .map(line => line ? `${indent}// [drift:removed] ${line.trimStart()}` : '')
+            .join('\n');
+          content = content.slice(0, startIdx) + commented + content.slice(lineEnd);
+        }
+      }
+    }
+    changes.push(`Removed props: ${removedProps.join(', ')}`);
+  }
+
+  // Sync composition in ai block
+  if (meta.composition && !fragment.ai?.compositionPattern) {
+    changes.push(`Composition: "${meta.composition.pattern}" pattern detected`);
+  }
+
+  return { updatedContent: content, changes };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Find the closing `}` of the top-level `props: { ... }` block */
+function findPropsBlockEnd(content: string): number {
+  const propsStart = content.search(/\bprops:\s*\{/);
+  if (propsStart === -1) return -1;
+  const braceStart = content.indexOf('{', propsStart);
+  return findMatchingBrace(content, braceStart);
+}
+
+/** Find the matching closing brace for an opening brace at `start` */
+function findMatchingBrace(content: string, start: number): number {
+  let depth = 0;
+  let inString: string | null = null;
+  let escaped = false;
+
+  for (let i = start; i < content.length; i++) {
+    const ch = content[i];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (ch === '\\') {
+      escaped = true;
+      continue;
+    }
+
+    if (inString) {
+      if (ch === inString) inString = null;
+      continue;
+    }
+
+    if (ch === "'" || ch === '"' || ch === '`') {
+      inString = ch;
+      continue;
+    }
+
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+
+  return -1;
+}
+
+/** Format a PropMeta into a fragment prop entry string */
+function formatPropEntry(name: string, prop: PropMeta): string {
+  const lines: string[] = [];
+  lines.push(`    ${name}: {`);
+  lines.push(`      type: '${prop.typeKind}',`);
+  if (prop.description) {
+    lines.push(`      description: ${JSON.stringify(prop.description)},`);
+  } else {
+    lines.push(`      description: '', // TODO: add description`);
+  }
+  if (prop.required) {
+    lines.push(`      required: true,`);
+  }
+  if (prop.values && prop.values.length > 0) {
+    lines.push(`      values: [${prop.values.map(v => `'${v}'`).join(', ')}],`);
+  }
+  if (prop.default !== undefined) {
+    lines.push(`      default: '${prop.default}',`);
+  }
+  lines.push(`    },`);
+  return lines.join('\n');
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/commands/validate.ts

@@ -5,7 +5,8 @@
 import pc from 'picocolors';
 import { BRAND } from '../core/index.js';
 import { loadConfig } from '../core/node.js';
-import { validateSchema, validateCoverage, validateAll, validateSnippets } from '../validators.js';
+import { validateSchema, validateCoverage, validateAll, validateSnippets, validateDrift } from '../validators.js';
+import type { DriftValidationResult } from '../validators.js';
 
 /**
  * Options for validate command
@@ -19,6 +20,10 @@ export interface ValidateOptions {
   coverage?: boolean;
   /** Validate snippet/render policy only */
   snippets?: boolean;
+  /** Detect metadata drift between source and fragments */
+  drift?: boolean;
+  /** Path to tsconfig.json for drift detection */
+  tsconfig?: string;
   /** Override snippet policy mode for this run */
   snippetMode?: 'warn' | 'error';
   /** Start component name for alphabetical snippet batch validation */
@@ -68,6 +73,11 @@ export async function validate(options: ValidateOptions = {}): Promise<ValidateR
       componentStart: options.componentStart,
       componentLimit,
     });
+  } else if (options.drift) {
+    console.log(pc.dim('Running drift detection...\n'));
+    const driftResult = await validateDrift(config, configDir, { tsconfig: options.tsconfig });
+    result = driftResult;
+    printDriftReport(driftResult);
   } else {
     console.log(pc.dim('Running all validations...\n'));
     result = await validateAll(config, configDir, {
@@ -113,3 +123,35 @@ export async function validate(options: ValidateOptions = {}): Promise<ValidateR
 
   return result;
 }
+
+/**
+ * Print a structured drift report grouped by component
+ */
+function printDriftReport(result: DriftValidationResult): void {
+  if (result.reports.length === 0) {
+    console.log(pc.green('No drift detected — fragments are in sync with source.\n'));
+    return;
+  }
+
+  console.log(pc.bold(`Drift detected in ${result.reports.length} component(s):\n`));
+
+  for (const report of result.reports) {
+    console.log(`  ${pc.bold(report.component)} ${pc.dim(`(${report.file})`)}`);
+
+    for (const drift of report.drifts) {
+      const icon = drift.kind === 'removed' ? pc.red('−') :
+                   drift.kind === 'added' ? pc.green('+') : pc.yellow('~');
+      const label = drift.kind.replace('_', ' ');
+      console.log(`    ${icon} ${drift.prop}: ${label}`);
+      if (drift.kind !== 'added' && drift.kind !== 'removed') {
+        console.log(pc.dim(`      fragment: ${drift.fragment}`));
+        console.log(pc.dim(`      source:   ${drift.source}`));
+      }
+    }
+
+    if (report.compositionDrift) {
+      console.log(`    ${pc.yellow('~')} composition: ${report.compositionDrift}`);
+    }
+    console.log();
+  }
+}