@fragments-sdk/cli 0.14.3 → 0.15.0

package/src/service/ast-utils.ts

@@ -6,10 +6,11 @@
  * accurate patches for token replacement.
  */
 
-import { parse, type ParserOptions } from "@babel/parser";
+import { parse } from "@babel/parser";
 import traverse, { type NodePath } from "@babel/traverse";
 import generate from "@babel/generator";
 import * as t from "@babel/types";
+import { BABEL_PARSER_OPTIONS } from "./babel-config.js";
 
 /**
  * Style location information
@@ -43,26 +44,6 @@ export interface StyleLocation {
   context?: string;
 }
 
-/**
- * Babel parser options for React/TypeScript files
- */
-const PARSER_OPTIONS: ParserOptions = {
-  sourceType: "module",
-  plugins: [
-    "jsx",
-    "typescript",
-    ["decorators", { decoratorsBeforeExport: true }],
-    "classProperties",
-    "classPrivateProperties",
-    "classPrivateMethods",
-    "exportDefaultFrom",
-    "exportNamespaceFrom",
-    "dynamicImport",
-    "nullishCoalescingOperator",
-    "optionalChaining",
-    "objectRestSpread",
-  ],
-};
 
 /**
  * Extract style locations from a React/TypeScript source file
@@ -81,7 +62,7 @@ export function extractStyleLocations(
 
   let ast: t.File;
   try {
-    ast = parse(sourceCode, PARSER_OPTIONS);
+    ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
   } catch (error) {
     console.error(`Failed to parse ${filePath}:`, error);
     return locations;
@@ -267,7 +248,7 @@ export function applyPatch(
 ): PatchResult {
   let ast: t.File;
   try {
-    ast = parse(sourceCode, PARSER_OPTIONS);
+    ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
   } catch (error) {
     return {
       success: false,

package/src/service/babel-config.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared Babel parser configuration for React/TypeScript files.
+ */
+
+import type { ParserOptions } from "@babel/parser";
+
+export const BABEL_PARSER_OPTIONS: ParserOptions = {
+  sourceType: "module",
+  plugins: [
+    "jsx",
+    "typescript",
+    ["decorators", { decoratorsBeforeExport: true }],
+    "classProperties",
+    "classPrivateProperties",
+    "classPrivateMethods",
+    "exportDefaultFrom",
+    "exportNamespaceFrom",
+    "dynamicImport",
+    "nullishCoalescingOperator",
+    "optionalChaining",
+    "objectRestSpread",
+  ],
+};

package/src/service/enhance/converter.ts

@@ -0,0 +1,61 @@
+/**
+ * Converter — transforms scanner output (ComponentUsage[]) to governance engine input (UISpec)
+ *
+ * Bridge between the codebase scanner (Babel AST analysis) and the govern engine.
+ * Each file's usages become a UISpec with one UINode per component usage.
+ */
+
+import { relative } from 'node:path';
+import type { ComponentUsage } from './types.js';
+import type { UISpec, UINode } from '@fragments-sdk/govern';
+
+/**
+ * Convert a list of component usages from a single file into a UISpec
+ * suitable for the governance engine.
+ *
+ * Each ComponentUsage becomes a UINode:
+ *   - id: `${relativePath}:${line}:${column}` (unique, traceable back to source)
+ *   - type: componentName (e.g. "Button", "Card.Header")
+ *   - props: merged static + dynamic markers + spread markers
+ */
+export function usagesToSpec(
+  usages: ComponentUsage[],
+  filePath: string,
+  rootDir: string,
+): UISpec {
+  const relativePath = relative(rootDir, filePath);
+
+  const nodes: UINode[] = usages.map((usage) => ({
+    id: `${relativePath}:${usage.line}:${usage.column}`,
+    type: usage.componentName,
+    props: mergeProps(usage),
+  }));
+
+  return {
+    nodes,
+    metadata: {
+      agent: 'scan',
+      timestamp: new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Merge static props, dynamic prop markers, and spread markers into
+ * a single Record<string, unknown> for the UINode.
+ */
+function mergeProps(usage: ComponentUsage): Record<string, unknown> {
+  const props: Record<string, unknown> = { ...usage.props.static };
+
+  // Mark dynamic props so governance rules can see them
+  for (const name of usage.props.dynamic) {
+    props[name] = '(dynamic)';
+  }
+
+  // Mark spread props
+  for (const name of usage.props.spreads) {
+    props[`...${name}`] = true;
+  }
+
+  return props;
+}

package/src/service/enhance/props-extractor.ts

@@ -586,13 +586,23 @@ function extractPropsFromInlineParams(
     // const ComponentName = (...) => ...
     if (ts.isVariableStatement(node)) {
       for (const decl of node.declarationList.declarations) {
-        if (
-          ts.isIdentifier(decl.name) &&
-          decl.name.text === componentName &&
-          decl.initializer &&
-          (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))
-        ) {
-          targetFunc = decl.initializer;
+        if (ts.isIdentifier(decl.name) && decl.name.text === componentName && decl.initializer) {
+          if (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer)) {
+            targetFunc = decl.initializer;
+          }
+          // Handle React.forwardRef(...) or forwardRef(...)
+          else if (ts.isCallExpression(decl.initializer)) {
+            const callee = decl.initializer.expression;
+            const isForwardRef =
+              (ts.isPropertyAccessExpression(callee) && callee.name.text === 'forwardRef') ||
+              (ts.isIdentifier(callee) && callee.text === 'forwardRef');
+            if (isForwardRef && decl.initializer.arguments.length > 0) {
+              const firstArg = decl.initializer.arguments[0];
+              if (ts.isArrowFunction(firstArg) || ts.isFunctionExpression(firstArg)) {
+                targetFunc = firstArg;
+              }
+            }
+          }
         }
       }
     }
@@ -777,7 +787,12 @@ function inferComponentName(filePath: string): string {
   if (name === "index") {
     name = basename(dirname(filePath));
   }
-  return name;
+
+  return name
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join("");
 }
 
 /**
@@ -850,6 +865,7 @@ export async function extractPropsForComponent(
       if (existsSync(fullPath)) {
         return extractPropsFromFile(fullPath, {
           propsTypeName: `${componentName}Props`,
+          componentName,
         });
       }
     }
@@ -870,6 +886,7 @@ export async function extractAllComponentProps(
     try {
       const extraction = await extractPropsFromFile(filePath, {
         propsTypeName: `${componentName}Props`,
+        componentName,
       });
       results.set(componentName, extraction);
     } catch (error) {

package/src/service/enhance/scanner.ts

@@ -6,7 +6,8 @@
  * - Component usages in JSX with props
  */
 
-import { parse, type ParserOptions } from "@babel/parser";
+import { parse } from "@babel/parser";
+import { BABEL_PARSER_OPTIONS } from "../babel-config.js";
 import _traverse from "@babel/traverse";
 import * as t from "@babel/types";
 
@@ -19,26 +20,6 @@ import type {
   UsageProps,
 } from "./types.js";
 
-/**
- * Babel parser options for React/TypeScript files
- */
-const PARSER_OPTIONS: ParserOptions = {
-  sourceType: "module",
-  plugins: [
-    "jsx",
-    "typescript",
-    ["decorators", { decoratorsBeforeExport: true }],
-    "classProperties",
-    "classPrivateProperties",
-    "classPrivateMethods",
-    "exportDefaultFrom",
-    "exportNamespaceFrom",
-    "dynamicImport",
-    "nullishCoalescingOperator",
-    "optionalChaining",
-    "objectRestSpread",
-  ],
-};
 
 /**
  * Scan a file for component imports
@@ -56,7 +37,7 @@ export async function scanFileForImports(
 
   try {
     const sourceCode = await readFile(filePath, "utf-8");
-    const ast = parse(sourceCode, PARSER_OPTIONS);
+    const ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
 
     traverse(ast, {
       ImportDeclaration(path) {
@@ -128,7 +109,7 @@ export async function scanFileForUsages(
   try {
     const sourceCode = await readFile(filePath, "utf-8");
     const lines = sourceCode.split("\n");
-    const ast = parse(sourceCode, PARSER_OPTIONS);
+    const ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
 
     traverse(ast, {
       JSXOpeningElement(path) {
@@ -189,7 +170,7 @@ export async function scanFile(
   try {
     const sourceCode = await readFile(filePath, "utf-8");
     const lines = sourceCode.split("\n");
-    const ast = parse(sourceCode, PARSER_OPTIONS);
+    const ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
 
     // Track local names to component names mapping within this file
     const localToComponent = new Map<string, string>();

package/src/service/snippet-validation.ts

@@ -494,8 +494,11 @@ function sortAndFilterBatch(
   const getComponentName = (relativePath: string): string => {
     const normalized = relativePath.replace(/\\/g, '/');
     const fileName = normalized.split('/').pop() ?? normalized;
-    if (fileName.endsWith(BRAND.fileExtension)) {
-      return fileName.slice(0, -BRAND.fileExtension.length);
+    // Handle both V2 (.contract.json) and legacy (.fragment.tsx/.fragment.ts)
+    for (const ext of [BRAND.fileExtension, '.fragment.tsx', '.fragment.ts']) {
+      if (fileName.endsWith(ext)) {
+        return fileName.slice(0, -ext.length);
+      }
     }
     return extractComponentName(relativePath);
   };
@@ -572,7 +575,10 @@ export async function validateSnippetPolicy(
   const issues: FileIssue[] = [];
 
   const discovered = await discoverFragmentFiles(config, configDir);
-  const fragmentFiles = discovered.filter((file) => file.relativePath.endsWith(BRAND.fileExtension));
+  // Snippet validation applies to TSX fragment files (not .contract.json which has no render code)
+  const fragmentFiles = discovered.filter((file) =>
+    file.relativePath.endsWith('.fragment.tsx') || file.relativePath.endsWith('.fragment.ts')
+  );
 
   const batchResult = sortAndFilterBatch(fragmentFiles, policy.componentStart, policy.componentLimit);
   if (batchResult.warning) {