@fragments-sdk/cli 0.15.10 → 0.17.0

package/src/commands/govern-scan.ts

@@ -3,14 +3,22 @@
  *
  * Parses real JSX/TSX files via the existing codebase scanner, converts
  * component usages to UISpec, and runs governance checks per file.
- * Optionally submits results to Fragments Cloud.
  */
 
 import pc from 'picocolors';
 import { resolve, relative } from 'node:path';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { BRAND } from '../core/index.js';
 import type { ComponentUsage } from '../service/enhance/types.js';
+import type { GovernanceVerdict } from '@fragments-sdk/govern';
+import {
+  aggregateVerdicts,
+  flattenComponentUsage,
+  buildComplianceSummary,
+  writeGovernScanReport,
+  type GovernScanReport,
+} from './govern-scan-report.js';
 
 // ---------------------------------------------------------------------------
 // Options
@@ -23,8 +31,16 @@ export interface GovernScanOptions {
   config?: string;
   /** Output format */
   format?: 'summary' | 'json' | 'sarif';
+  /** Write an aggregated machine-readable JSON report */
+  report?: string;
   /** Suppress non-error output */
   quiet?: boolean;
+  /** Fragments Cloud API key — reports findings to Cloud */
+  apiKey?: string;
+  /** Fragments Cloud base URL (default: https://app.usefragments.com) */
+  cloudUrl?: string;
+  /** Only scan files changed vs a base ref (default base: auto-detected merge base) */
+  diff?: boolean | string;
 }
 
 export interface GovernWatchOptions extends GovernScanOptions {
@@ -32,6 +48,53 @@ export interface GovernWatchOptions extends GovernScanOptions {
   debounce?: number;
 }
 
+// ---------------------------------------------------------------------------
+// Git diff helpers
+// ---------------------------------------------------------------------------
+
+const SCANNABLE_EXTENSIONS = new Set([
+  '.tsx', '.ts', '.jsx', '.js',
+]);
+
+function getChangedFiles(rootDir: string, base?: string): string[] | null {
+  try {
+    const baseRef = base || detectMergeBase(rootDir);
+    if (!baseRef) return null;
+
+    const output = execSync(
+      `git diff --name-only --diff-filter=ACMR ${baseRef}...HEAD`,
+      { cwd: rootDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
+    );
+
+    return output
+      .split('\n')
+      .map((f) => f.trim())
+      .filter((f) => f && SCANNABLE_EXTENSIONS.has(f.slice(f.lastIndexOf('.'))))
+      .map((f) => resolve(rootDir, f));
+  } catch {
+    return null;
+  }
+}
+
+function detectMergeBase(rootDir: string): string | null {
+  try {
+    const remote = execSync('git rev-parse --abbrev-ref origin/HEAD', {
+      cwd: rootDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (remote) return remote;
+  } catch { /* fallback */ }
+
+  for (const candidate of ['origin/main', 'origin/master']) {
+    try {
+      execSync(`git rev-parse --verify ${candidate}`, {
+        cwd: rootDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      return candidate;
+    } catch { /* try next */ }
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Scan defaults — applied when no config file exists
 // ---------------------------------------------------------------------------
@@ -78,6 +141,7 @@ function groupByFile(usages: ComponentUsage[]): Map<string, ComponentUsage[]> {
   return grouped;
 }
 
+
 // ---------------------------------------------------------------------------
 // governScan
 // ---------------------------------------------------------------------------
@@ -89,9 +153,9 @@ export async function governScan(
     loadPolicy,
     createEngine,
     buildAdaptersFromConfig,
-    createCloudAdapter,
     formatVerdict,
     computeComponentHealth,
+    computeScore,
   } = await import('@fragments-sdk/govern');
 
   const { scanCodebase } = await import(
@@ -125,54 +189,38 @@ export async function governScan(
     }
   }
 
-  // 3. Extract code tokens for cloud ingest
-  let codeTokens: string | undefined;
-  if (process.env.FRAGMENTS_API_KEY) {
-    codeTokens = await extractCodeTokens(rootDir, options.config, quiet);
-  }
-
-  // 3b. Load contract registry for governance + cloud ingest (if fragments.json exists)
-  let contractRegistry: string | undefined;
+  // 3. Load contract registry for contract-aware scoring (if fragments.json exists)
   let registryMap: Record<string, unknown> | undefined;
+  let hasRegistry = false;
   {
-    const { readFileSync, existsSync } = await import('node:fs');
     const fragmentsJsonPath = resolve(rootDir, 'fragments.json');
     if (existsSync(fragmentsJsonPath)) {
       try {
         const raw = readFileSync(fragmentsJsonPath, 'utf-8');
         const parsed = JSON.parse(raw);
         if (parsed.fragments && Array.isArray(parsed.fragments)) {
-          // Build name-keyed map for engine registry injection
           const map: Record<string, unknown> = {};
-          for (const f of parsed.fragments) {
-            if (f.meta?.name) {
-              map[f.meta.name] = f;
+          for (const fragment of parsed.fragments) {
+            if (fragment.meta?.name) {
+              map[fragment.meta.name] = fragment;
             }
           }
           registryMap = map;
-
-          if (process.env.FRAGMENTS_API_KEY) {
-            contractRegistry = JSON.stringify({ fragments: parsed.fragments });
-          }
+          hasRegistry = true;
           if (!quiet) {
-            console.log(pc.dim(`  Contract registry loaded (${parsed.fragments.length} components)\n`));
+            console.log(
+              pc.dim(`  Contract registry loaded (${parsed.fragments.length} components)\n`),
+            );
           }
         }
       } catch {
-        // Invalid fragments.json — skip
+        // Invalid fragments.json — skip registry-aware summary
       }
     }
   }
 
-  // 4. Build adapters. Auto-add cloud if FRAGMENTS_API_KEY is set
+  // 4. Build adapters from policy config
   const adapters = buildAdaptersFromConfig(policy.audit);
-  const hasCloudAdapter = adapters.length > 0 && policy.audit?.cloud;
-  if (!hasCloudAdapter && process.env.FRAGMENTS_API_KEY) {
-    adapters.push(createCloudAdapter({ codeTokens, contractRegistry }));
-    if (!quiet) {
-      console.log(pc.dim('  Cloud audit enabled (FRAGMENTS_API_KEY detected)\n'));
-    }
-  }
 
   // 5. Create engine (with registry for contract-aware validators)
   const engine = createEngine(
@@ -183,14 +231,36 @@ export async function governScan(
       : undefined,
   );
 
-  // 6. Scan codebase
-  if (!quiet) {
+  // 6. Scan codebase (optionally scoped to changed files via --diff)
+  let diffFiles: string[] | undefined;
+  if (options.diff) {
+    const base = typeof options.diff === 'string' ? options.diff : undefined;
+    const changed = getChangedFiles(rootDir, base);
+    if (changed && changed.length > 0) {
+      diffFiles = changed;
+      if (!quiet) {
+        console.log(pc.dim(`  Diff mode: scanning ${changed.length} changed file(s)...\n`));
+      }
+    } else if (changed && changed.length === 0) {
+      if (!quiet) {
+        console.log(pc.green('  No scannable files changed — all clear.\n'));
+      }
+      return { exitCode: 0 };
+    } else {
+      if (!quiet) {
+        console.log(pc.yellow('  Could not detect git diff — falling back to full scan.\n'));
+      }
+    }
+  }
+
+  if (!quiet && !diffFiles) {
     console.log(pc.dim('  Scanning files...\n'));
   }
 
   const analysis = await scanCodebase({
     rootDir,
     useCache: true,
+    files: diffFiles,
     onProgress: quiet
       ? undefined
       : (progress) => {
@@ -220,6 +290,16 @@ export async function governScan(
     if (!quiet) {
       console.log(pc.yellow('  No component usages found.\n'));
     }
+    if (options.report) {
+      const report: GovernScanReport = {
+        verdict: aggregateVerdicts([], computeScore, 'ci'),
+        componentUsage: [],
+      };
+      await writeGovernScanReport(options.report, report);
+      if (!quiet) {
+        console.log(pc.dim(`  Wrote governance report: ${resolve(options.report)}\n`));
+      }
+    }
     return { exitCode: 0 };
   }
 
@@ -229,17 +309,7 @@ export async function governScan(
   let passedFiles = 0;
   let totalViolations = 0;
   const violationCounts = new Map<string, number>();
-  const allVerdicts: Awaited<ReturnType<typeof engine.check>>[] = [];
-
-  // Build per-file usage snapshot for cloud
-  const usageSnapshot: Array<{
-    file: string;
-    components: Array<{
-      name: string;
-      line: number;
-      props: { static: Record<string, unknown>; dynamic: string[] };
-    }>;
-  }> = [];
+  const allVerdicts: GovernanceVerdict[] = [];
 
   for (const [filePath, usages] of grouped) {
     const spec = usagesToSpec(usages, filePath, rootDir);
@@ -251,19 +321,6 @@ export async function governScan(
     });
     allVerdicts.push(verdict);
 
-    // Collect per-file usage snapshot
-    usageSnapshot.push({
-      file: relPath,
-      components: usages.map((u) => ({
-        name: u.componentName,
-        line: u.line,
-        props: {
-          static: u.props.static,
-          dynamic: u.props.dynamic,
-        },
-      })),
-    });
-
     totalFiles++;
 
     if (verdict.passed) {
@@ -340,103 +397,197 @@ export async function governScan(
     }
   }
 
-  // 10. Push component usage snapshot + health to Cloud (if API key set)
-  if (process.env.FRAGMENTS_API_KEY && usageSnapshot.length > 0) {
-    try {
-      const apiKey = process.env.FRAGMENTS_API_KEY;
-      const url = process.env.FRAGMENTS_URL ?? 'https://app.usefragments.com';
-      await fetch(`${url}/api/ingest`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${apiKey}`,
-        },
-        body: JSON.stringify({
-          componentUsage: JSON.stringify(usageSnapshot),
-          componentHealth: JSON.stringify(health),
-        }),
-      });
-    } catch {
-      // Non-critical — don't fail the scan
+  if (options.report) {
+    const report: GovernScanReport = {
+      verdict: aggregateVerdicts(allVerdicts, computeScore, 'ci'),
+      componentUsage: flattenComponentUsage(allUsages, rootDir),
+    };
+    if (hasRegistry) {
+      report.complianceSummary = buildComplianceSummary(health);
+    }
+    await writeGovernScanReport(options.report, report);
+    if (!quiet) {
+      console.log(pc.dim(`  Wrote governance report: ${resolve(options.report)}\n`));
     }
   }
 
+  // Report to Fragments Cloud
+  if (options.apiKey) {
+    await reportToCloud({
+      apiKey: options.apiKey,
+      cloudUrl: options.cloudUrl,
+      verdicts: allVerdicts,
+      rootDir,
+      quiet,
+      diffOnly: !!diffFiles,
+    });
+  }
+
   return { exitCode: passedFiles === totalFiles ? 0 : 1 };
 }
 
 // ---------------------------------------------------------------------------
-// Token extraction for cloud ingest
+// Cloud reporting
 // ---------------------------------------------------------------------------
 
-/**
- * Auto-detect and extract code tokens to send alongside governance verdicts.
- * Tries: 1) tokens config from fragments.config.ts, 2) Tailwind config.
- * Returns a flat JSON string of token name → value, or undefined if nothing found.
- */
-async function extractCodeTokens(
-  rootDir: string,
-  configPath?: string,
-  quiet?: boolean,
-): Promise<string | undefined> {
-  try {
-    // 1. Try fragments.config.ts tokens config
+const DEFAULT_CLOUD_URL = 'https://app.usefragments.com';
+
+interface CloudReportOptions {
+  apiKey: string;
+  cloudUrl?: string;
+  verdicts: GovernanceVerdict[];
+  rootDir: string;
+  quiet: boolean;
+  diffOnly?: boolean;
+}
+
+function detectGitMetadata(): {
+  commitSha?: string;
+  branch?: string;
+  pr?: number;
+  repoFullName?: string;
+} {
+  const env = process.env;
+  const meta: ReturnType<typeof detectGitMetadata> = {};
+
+  if (env.GITHUB_SHA) meta.commitSha = env.GITHUB_SHA;
+  if (env.GITHUB_REPOSITORY) meta.repoFullName = env.GITHUB_REPOSITORY;
+  if (env.GITHUB_REF_NAME) meta.branch = env.GITHUB_REF_NAME;
+
+  if (env.GITHUB_EVENT_NAME === 'pull_request' && env.GITHUB_EVENT_PATH) {
     try {
-      const { loadConfig } = await import('../core/node.js');
-      const { parseTokenFiles } = await import('../service/index.js');
-
-      const { config, configDir } = await loadConfig(configPath);
-      if (config.tokens?.include?.length) {
-        const result = await parseTokenFiles(config.tokens, configDir);
-        if (result.tokens.length > 0) {
-          const flat: Record<string, string> = {};
-          for (const token of result.tokens) {
-            flat[token.name] = token.resolvedValue;
-          }
-          if (!quiet) {
-            console.log(
-              pc.dim(`  Extracted ${result.tokens.length} code tokens from config\n`),
-            );
-          }
-          return JSON.stringify(flat);
-        }
+      const event = JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, 'utf-8'));
+      if (event?.pull_request?.number) {
+        meta.pr = event.pull_request.number;
+      }
+      if (event?.pull_request?.head?.sha) {
+        meta.commitSha = event.pull_request.head?.sha;
       }
     } catch {
-      // No config or no tokens section — fall through
+      // Event file unreadable — skip PR number
     }
+  }
 
-    // 2. Try Tailwind config
-    const {
-      findTailwindConfig,
-      loadTailwindConfig,
-    } = await import('../service/token-normalizer.js');
-
-    const tailwindPath = findTailwindConfig(rootDir);
-    if (tailwindPath) {
-      const tokens = await loadTailwindConfig(tailwindPath);
-      if (tokens.length > 0) {
-        const flat: Record<string, string> = {};
-        for (const token of tokens) {
-          flat[token.name] = token.value;
-        }
-        if (!quiet) {
-          console.log(
-            pc.dim(`  Extracted ${tokens.length} tokens from Tailwind config\n`),
-          );
+  return meta;
+}
+
+async function reportToCloud(options: CloudReportOptions): Promise<void> {
+  const { apiKey, verdicts, rootDir, quiet, diffOnly } = options;
+  const baseUrl = (options.cloudUrl ?? DEFAULT_CLOUD_URL).replace(/\/+$/, '');
+
+  const findings: Array<{
+    ruleId: string;
+    severity: 'error' | 'warning' | 'info';
+    filePath?: string;
+    line?: number;
+    column?: number;
+    rawValue?: string;
+    suggestedToken?: string;
+    message: string;
+    category?: string;
+    fingerprint: string;
+  }> = [];
+
+  const { createHash } = await import('node:crypto');
+
+  for (const verdict of verdicts) {
+    for (const result of verdict.results) {
+      for (const v of result.violations) {
+        const severity = v.severity === 'critical' || v.severity === 'serious'
+          ? 'error'
+          : v.severity === 'moderate'
+            ? 'warning'
+            : 'info';
+
+        const fingerprint = createHash('sha256')
+          .update(`${v.rule}:${v.nodeType}:${v.nodeId}:${v.message}`)
+          .digest('hex')
+          .slice(0, 16);
+
+        let filePath: string | undefined;
+        let line: number | undefined;
+        let column: number | undefined;
+
+        if (v.filePath) {
+          filePath = v.filePath;
+          line = v.line;
+          column = v.column;
+        } else if (v.nodeId) {
+          const parts = v.nodeId.split(':');
+          if (parts.length >= 3) {
+            const col = parseInt(parts.pop()!, 10);
+            const ln = parseInt(parts.pop()!, 10);
+            const path = parts.join(':');
+            if (!isNaN(ln) && !isNaN(col) && path) {
+              filePath = path;
+              line = ln;
+              column = col;
+            }
+          }
+          if (!filePath) {
+            filePath = relative(rootDir, v.nodeId);
+          }
         }
-        return JSON.stringify(flat);
+
+        findings.push({
+          ruleId: v.rule,
+          severity,
+          filePath,
+          line,
+          column,
+          rawValue: v.rawValue,
+          message: `[${result.validator}] ${v.message}`,
+          category: result.validator,
+          fingerprint,
+          suggestedToken: v.suggestion,
+        });
       }
     }
-  } catch (error) {
+  }
+
+  if (!quiet) {
+    console.log(pc.dim(`  Reporting ${findings.length} finding(s) to Fragments Cloud...`));
+  }
+
+  const gitMeta = detectGitMetadata();
+
+  try {
+    const response = await fetch(`${baseUrl}/api/govern/ingest`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        findings,
+        source: 'ci',
+        diffOnly: diffOnly ?? false,
+        ...gitMeta,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      const msg = (body as { error?: string }).error ?? `HTTP ${response.status}`;
+      console.error(pc.red(`  ✗ Cloud report failed: ${msg}\n`));
+      return;
+    }
+
+    const body = await response.json() as { ingested?: number; orgSlug?: string };
     if (!quiet) {
       console.log(
-        pc.dim(
-          `  Token extraction skipped: ${error instanceof Error ? error.message : 'unknown error'}\n`,
-        ),
+        pc.green(`  ✓ Reported ${body.ingested ?? findings.length} finding(s) to Cloud`) +
+        (body.orgSlug ? pc.dim(` (${body.orgSlug})`) : '') +
+        '\n',
       );
     }
+  } catch (err) {
+    console.error(
+      pc.red(`  ✗ Cloud report failed: `) +
+      pc.dim(err instanceof Error ? err.message : 'Network error') +
+      '\n',
+    );
   }
-
-  return undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -450,7 +601,6 @@ export async function governWatch(
     loadPolicy,
     createEngine,
     buildAdaptersFromConfig,
-    createCloudAdapter,
     formatVerdict,
   } = await import('@fragments-sdk/govern');
 
@@ -480,9 +630,6 @@ export async function governWatch(
     policy = { ...policy, rules: SCAN_DEFAULT_RULES };
   }
   const adapters = buildAdaptersFromConfig(policy.audit);
-  if (!adapters.some(() => policy.audit?.cloud) && process.env.FRAGMENTS_API_KEY) {
-    adapters.push(createCloudAdapter());
-  }
   const engine = createEngine(policy, adapters);
 
   // 3. Watch for changes