@fragments-sdk/cli 0.7.4 → 0.7.5

package/src/service/snippet-validation.ts

@@ -0,0 +1,635 @@
+import ts from 'typescript';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { FragmentsConfig, SnippetPolicyConfig } from '../core/types.js';
+import { BRAND } from '../core/constants.js';
+import {
+  discoverBlockFiles,
+  discoverFragmentFiles,
+  extractComponentName,
+  type DiscoveredFile,
+} from '../core/node.js';
+
+export interface SnippetValidationOptions {
+  mode?: 'warn' | 'error';
+  scope?: 'snippet' | 'snippet+render';
+  requireFullSnippet?: boolean;
+  allowedExternalModules?: string[];
+  componentStart?: string;
+  componentLimit?: number;
+}
+
+export interface SnippetValidationResult {
+  errors: Array<{ file: string; message: string }>;
+  warnings: Array<{ file: string; message: string }>;
+}
+
+interface EffectiveSnippetPolicy {
+  mode: 'warn' | 'error';
+  scope: 'snippet' | 'snippet+render';
+  requireFullSnippet: boolean;
+  allowedExternalModules: Set<string>;
+  componentStart?: string;
+  componentLimit?: number;
+}
+
+interface SourceContext {
+  imports: Map<string, string>;
+  localComponents: Set<string>;
+}
+
+interface FileIssue {
+  file: string;
+  message: string;
+}
+
+const INTRINSIC_TAGS = new Set([
+  'div',
+  'span',
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'main',
+  'section',
+  'article',
+  'aside',
+  'nav',
+  'header',
+  'footer',
+  'ul',
+  'ol',
+  'li',
+  'button',
+  'input',
+  'textarea',
+  'label',
+  'svg',
+  'path',
+]);
+
+const JSX_TAG_PATTERN = /<\s*([A-Za-z][A-Za-z0-9.]*)\b/g;
+const STYLE_PATTERN = /\bstyle\s*=\s*\{/;
+const TRANSPILED_PATTERN = /jsxDEV|_jsx|@__PURE__|\bfileName\s*:|\blineNumber\s*:|\bcolumnNumber\s*:/;
+const ALIAS_DRIFT_PATTERN = /<\s*[A-Z][A-Za-z0-9]*(?:Root|2)\b/;
+const HAS_IMPORT_PATTERN = /\bimport\s+[^;]+\s+from\s+['"][^'"]+['"]/;
+const HAS_JSX_PATTERN = /<\s*[A-Za-z][A-Za-z0-9.]*\b/;
+
+const DEFAULT_POLICY: EffectiveSnippetPolicy = {
+  mode: 'warn',
+  scope: 'snippet+render',
+  requireFullSnippet: true,
+  allowedExternalModules: new Set([
+    '@phosphor-icons/react',
+    'recharts',
+    'react-day-picker',
+  ]),
+};
+
+function normalizePolicy(
+  configured: SnippetPolicyConfig | undefined,
+  overrides: SnippetValidationOptions
+): EffectiveSnippetPolicy {
+  const fromConfig: EffectiveSnippetPolicy = {
+    mode: configured?.mode ?? DEFAULT_POLICY.mode,
+    scope: configured?.scope ?? DEFAULT_POLICY.scope,
+    requireFullSnippet: configured?.requireFullSnippet ?? DEFAULT_POLICY.requireFullSnippet,
+    allowedExternalModules: new Set(configured?.allowedExternalModules ?? [...DEFAULT_POLICY.allowedExternalModules]),
+    componentStart: overrides.componentStart,
+    componentLimit: overrides.componentLimit,
+  };
+
+  if (overrides.mode) fromConfig.mode = overrides.mode;
+  if (overrides.scope) fromConfig.scope = overrides.scope;
+  if (typeof overrides.requireFullSnippet === 'boolean') {
+    fromConfig.requireFullSnippet = overrides.requireFullSnippet;
+  }
+  if (overrides.allowedExternalModules && overrides.allowedExternalModules.length > 0) {
+    fromConfig.allowedExternalModules = new Set(overrides.allowedExternalModules);
+  }
+
+  return fromConfig;
+}
+
+function isFragmentsModule(modulePath: string): boolean {
+  return (
+    modulePath === '@fragments-sdk/ui'
+    || modulePath === '@fragments/ui'
+    || modulePath === '.'
+    || modulePath === '..'
+    || modulePath.startsWith('@/components/')
+    || modulePath.startsWith('@components/')
+    || modulePath.startsWith('./')
+    || modulePath.startsWith('../')
+  );
+}
+
+function collectSourceContext(sourceFile: ts.SourceFile): SourceContext {
+  const imports = new Map<string, string>();
+  const localComponents = new Set<string>();
+
+  function markLocal(name: string | undefined): void {
+    if (!name) return;
+    if (/^[A-Z]/.test(name)) {
+      localComponents.add(name);
+    }
+  }
+
+  function visit(node: ts.Node): void {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      const modulePath = node.moduleSpecifier.text;
+      const clause = node.importClause;
+
+      if (clause?.name) {
+        imports.set(clause.name.text, modulePath);
+      }
+
+      if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+        for (const item of clause.namedBindings.elements) {
+          imports.set(item.name.text, modulePath);
+        }
+      }
+    }
+
+    if (ts.isFunctionDeclaration(node)) {
+      markLocal(node.name?.text);
+    }
+
+    if (ts.isClassDeclaration(node)) {
+      markLocal(node.name?.text);
+    }
+
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+      markLocal(node.name.text);
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return { imports, localComponents };
+}
+
+function getJsxTags(code: string): string[] {
+  const tags: string[] = [];
+  JSX_TAG_PATTERN.lastIndex = 0;
+
+  let match: RegExpExecArray | null;
+  while ((match = JSX_TAG_PATTERN.exec(code)) !== null) {
+    tags.push(match[1]);
+  }
+
+  return tags;
+}
+
+function rootTagName(tag: string): string {
+  return tag.split('.')[0];
+}
+
+function parseSnippetImports(snippet: string): Map<string, string> {
+  const sourceFile = ts.createSourceFile(
+    'snippet.tsx',
+    snippet,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  return collectSourceContext(sourceFile).imports;
+}
+
+function findDefineCall(sourceFile: ts.SourceFile, name: 'defineFragment' | 'defineBlock'): ts.CallExpression | null {
+  let result: ts.CallExpression | null = null;
+
+  function visit(node: ts.Node): void {
+    if (result) return;
+
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === name) {
+      result = node;
+      return;
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return result;
+}
+
+function findProperty(obj: ts.ObjectLiteralExpression, propertyName: string): ts.Expression | null {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    if (!ts.isIdentifier(prop.name)) continue;
+    if (prop.name.text === propertyName) {
+      return prop.initializer;
+    }
+  }
+
+  return null;
+}
+
+function readStaticString(expr: ts.Expression | null): string | null {
+  if (!expr) return null;
+  if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) {
+    return expr.text;
+  }
+  return null;
+}
+
+function readRenderBody(renderExpr: ts.Expression, sourceFile: ts.SourceFile): string | null {
+  if (!ts.isArrowFunction(renderExpr) && !ts.isFunctionExpression(renderExpr)) {
+    return null;
+  }
+
+  const body = renderExpr.body;
+  const start = body.getStart(sourceFile);
+  const end = body.getEnd();
+  return sourceFile.text.slice(start, end).trim();
+}
+
+function report(issues: FileIssue[], file: string, message: string): void {
+  issues.push({ file, message });
+}
+
+function validateRawRules(
+  issues: FileIssue[],
+  file: string,
+  label: string,
+  code: string,
+): void {
+  if (STYLE_PATTERN.test(code)) {
+    report(issues, file, `${label}: inline style usage is not allowed; use Box/Stack/Text props.`);
+  }
+
+  if (TRANSPILED_PATTERN.test(code)) {
+    report(issues, file, `${label}: transpiler output detected (jsxDEV/_jsx/@__PURE__). Use authored snippet source.`);
+  }
+
+  if (ALIAS_DRIFT_PATTERN.test(code)) {
+    report(issues, file, `${label}: alias drift tag detected (*Root/*2). Use canonical component names.`);
+  }
+
+  const tags = getJsxTags(code);
+  const intrinsic = tags
+    .map((tag) => rootTagName(tag))
+    .filter((tag) => /^[a-z]/.test(tag))
+    .map((tag) => tag.toLowerCase())
+    .filter((tag) => INTRINSIC_TAGS.has(tag));
+
+  if (intrinsic.length > 0) {
+    const names = [...new Set(intrinsic)].sort().join(', ');
+    report(issues, file, `${label}: raw HTML tags are not allowed (${names}). Use Fragments primitives.`);
+  }
+}
+
+function validateComponentAllowlist(
+  issues: FileIssue[],
+  file: string,
+  label: string,
+  code: string,
+  imports: Map<string, string>,
+  localComponents: Set<string>,
+  policy: EffectiveSnippetPolicy,
+): void {
+  const tags = getJsxTags(code);
+  const seen = new Set<string>();
+
+  for (const tag of tags) {
+    const root = rootTagName(tag);
+
+    if (seen.has(root)) continue;
+    seen.add(root);
+
+    if (!/^[A-Z]/.test(root)) {
+      continue;
+    }
+
+    const modulePath = imports.get(root);
+
+    if (modulePath) {
+      if (isFragmentsModule(modulePath)) {
+        continue;
+      }
+      if (policy.allowedExternalModules.has(modulePath)) {
+        continue;
+      }
+
+      report(
+        issues,
+        file,
+        `${label}: component "${root}" comes from "${modulePath}" and is not in snippets.allowedExternalModules.`,
+      );
+      continue;
+    }
+
+    if (localComponents.has(root)) {
+      report(
+        issues,
+        file,
+        `${label}: locally defined JSX component "${root}" is not allowed in snippets/renders. Import approved components instead.`,
+      );
+      continue;
+    }
+
+    report(
+      issues,
+      file,
+      `${label}: component "${root}" is used without an import and is not allowed.`,
+    );
+  }
+}
+
+function validateSnippetString(
+  issues: FileIssue[],
+  file: string,
+  label: string,
+  snippet: string,
+  policy: EffectiveSnippetPolicy,
+): void {
+  validateRawRules(issues, file, label, snippet);
+
+  if (policy.requireFullSnippet) {
+    if (!HAS_IMPORT_PATTERN.test(snippet)) {
+      report(issues, file, `${label}: full snippet required (missing import statement).`);
+    }
+
+    if (!HAS_JSX_PATTERN.test(snippet)) {
+      report(issues, file, `${label}: full snippet required (missing JSX usage).`);
+    }
+  }
+
+  const imports = parseSnippetImports(snippet);
+  validateComponentAllowlist(issues, file, label, snippet, imports, new Set(), policy);
+}
+
+function validateFragmentSource(
+  sourceFile: ts.SourceFile,
+  file: string,
+  policy: EffectiveSnippetPolicy,
+  issues: FileIssue[],
+): void {
+  const context = collectSourceContext(sourceFile);
+
+  const defineCall = findDefineCall(sourceFile, 'defineFragment');
+  if (!defineCall) {
+    return;
+  }
+
+  const arg = defineCall.arguments[0];
+  if (!arg || !ts.isObjectLiteralExpression(arg)) {
+    return;
+  }
+
+  const variantsExpr = findProperty(arg, 'variants');
+  if (!variantsExpr || !ts.isArrayLiteralExpression(variantsExpr)) {
+    return;
+  }
+
+  for (const variantExpr of variantsExpr.elements) {
+    if (!ts.isObjectLiteralExpression(variantExpr)) continue;
+
+    const name = readStaticString(findProperty(variantExpr, 'name')) ?? 'Unknown';
+    const labelPrefix = `variant "${name}"`;
+
+    const codeExpr = findProperty(variantExpr, 'code');
+    const snippet = readStaticString(codeExpr);
+    if (snippet) {
+      validateSnippetString(issues, file, `${labelPrefix} snippet`, snippet, policy);
+    } else {
+      report(issues, file, `${labelPrefix}: missing explicit code snippet (variant.code).`);
+    }
+
+    if (policy.scope === 'snippet+render') {
+      const renderExpr = findProperty(variantExpr, 'render');
+      if (renderExpr) {
+        const renderBody = readRenderBody(renderExpr, sourceFile);
+        if (!renderBody) {
+          report(issues, file, `${labelPrefix} render: expected a static render function.`);
+          continue;
+        }
+
+        validateRawRules(issues, file, `${labelPrefix} render`, renderBody);
+        validateComponentAllowlist(
+          issues,
+          file,
+          `${labelPrefix} render`,
+          renderBody,
+          context.imports,
+          context.localComponents,
+          policy,
+        );
+      }
+    }
+  }
+}
+
+function validateBlockSource(
+  sourceFile: ts.SourceFile,
+  file: string,
+  policy: EffectiveSnippetPolicy,
+  issues: FileIssue[],
+): void {
+  const defineCall = findDefineCall(sourceFile, 'defineBlock');
+  if (!defineCall) {
+    return;
+  }
+
+  const arg = defineCall.arguments[0];
+  if (!arg || !ts.isObjectLiteralExpression(arg)) {
+    return;
+  }
+
+  const codeExpr = findProperty(arg, 'code');
+  const snippet = readStaticString(codeExpr);
+  if (!snippet) {
+    report(issues, file, 'block snippet: missing static code string.');
+    return;
+  }
+
+  validateSnippetString(issues, file, 'block snippet', snippet, policy);
+}
+
+function validateBlockPreviewExamples(
+  sourceFile: ts.SourceFile,
+  file: string,
+  policy: EffectiveSnippetPolicy,
+  issues: FileIssue[],
+): void {
+  if (policy.scope !== 'snippet+render') {
+    return;
+  }
+
+  const code = sourceFile.text;
+  const context = collectSourceContext(sourceFile);
+
+  validateRawRules(issues, file, 'block preview render', code);
+  validateComponentAllowlist(
+    issues,
+    file,
+    'block preview render',
+    code,
+    context.imports,
+    context.localComponents,
+    policy,
+  );
+}
+
+function sourceFileFromText(filePath: string, content: string): ts.SourceFile {
+  return ts.createSourceFile(
+    filePath,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+}
+
+function sortAndFilterBatch(
+  files: DiscoveredFile[],
+  componentStart?: string,
+  componentLimit?: number,
+): { selected: DiscoveredFile[]; warning?: string } {
+  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);
+    }
+    return extractComponentName(relativePath);
+  };
+
+  const sorted = [...files].sort((a, b) => {
+    const nameA = getComponentName(a.relativePath).toLowerCase();
+    const nameB = getComponentName(b.relativePath).toLowerCase();
+    return nameA.localeCompare(nameB);
+  });
+
+  if (!componentStart && !componentLimit) {
+    return { selected: sorted };
+  }
+
+  const startName = componentStart?.toLowerCase();
+  let startIndex = 0;
+
+  if (startName) {
+    const foundIndex = sorted.findIndex((file) => getComponentName(file.relativePath).toLowerCase() === startName);
+    if (foundIndex === -1) {
+      return {
+        selected: [],
+        warning: `Component start "${componentStart}" not found for snippet validation batch.`,
+      };
+    }
+    startIndex = foundIndex;
+  }
+
+  const limit = componentLimit && componentLimit > 0 ? componentLimit : sorted.length;
+  return {
+    selected: sorted.slice(startIndex, startIndex + limit),
+  };
+}
+
+async function findBlockPreviewExamplesFile(configDir: string): Promise<string | null> {
+  const candidates = [
+    join(configDir, 'apps/docs/src/app/(docs)/blocks/examples/index.tsx'),
+    join(configDir, '../apps/docs/src/app/(docs)/blocks/examples/index.tsx'),
+    join(configDir, '../../apps/docs/src/app/(docs)/blocks/examples/index.tsx'),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function toValidationResult(policy: EffectiveSnippetPolicy, issues: FileIssue[]): SnippetValidationResult {
+  if (policy.mode === 'error') {
+    return {
+      errors: issues,
+      warnings: [],
+    };
+  }
+
+  return {
+    errors: [],
+    warnings: issues,
+  };
+}
+
+/**
+ * Validate snippet and render policy for fragments, blocks, and docs block previews.
+ */
+export async function validateSnippetPolicy(
+  config: FragmentsConfig,
+  configDir: string,
+  options: SnippetValidationOptions = {},
+): Promise<SnippetValidationResult> {
+  const policy = normalizePolicy(config.snippets, options);
+  const issues: FileIssue[] = [];
+
+  const discovered = await discoverFragmentFiles(config, configDir);
+  const fragmentFiles = discovered.filter((file) => file.relativePath.endsWith(BRAND.fileExtension));
+
+  const batchResult = sortAndFilterBatch(fragmentFiles, policy.componentStart, policy.componentLimit);
+  if (batchResult.warning) {
+    issues.push({ file: 'snippets', message: batchResult.warning });
+  }
+
+  for (const file of batchResult.selected) {
+    try {
+      const content = await readFile(file.absolutePath, 'utf-8');
+      const sourceFile = sourceFileFromText(file.relativePath, content);
+      validateFragmentSource(sourceFile, file.relativePath, policy, issues);
+    } catch (error) {
+      issues.push({
+        file: file.relativePath,
+        message: `Failed to validate fragment snippets: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  }
+
+  const isBatchOnly = Boolean(policy.componentStart || policy.componentLimit);
+  if (!isBatchOnly) {
+    try {
+      const blockFiles = await discoverBlockFiles(configDir, config.exclude);
+      for (const file of blockFiles) {
+        try {
+          const content = await readFile(file.absolutePath, 'utf-8');
+          const sourceFile = sourceFileFromText(file.relativePath, content);
+          validateBlockSource(sourceFile, file.relativePath, policy, issues);
+        } catch (error) {
+          issues.push({
+            file: file.relativePath,
+            message: `Failed to validate block snippets: ${error instanceof Error ? error.message : String(error)}`,
+          });
+        }
+      }
+    } catch (error) {
+      issues.push({
+        file: 'blocks',
+        message: `Failed to discover block files: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+
+    const blockPreviewFile = await findBlockPreviewExamplesFile(configDir);
+    if (blockPreviewFile) {
+      try {
+        const content = await readFile(blockPreviewFile, 'utf-8');
+        const sourceFile = sourceFileFromText(blockPreviewFile, content);
+        validateBlockPreviewExamples(sourceFile, blockPreviewFile, policy, issues);
+      } catch (error) {
+        issues.push({
+          file: blockPreviewFile,
+          message: `Failed to validate block preview examples: ${error instanceof Error ? error.message : String(error)}`,
+        });
+      }
+    }
+  }
+
+  return toValidationResult(policy, issues);
+}

package/src/validators.ts

@@ -4,8 +4,8 @@ import {
   discoverComponentFiles,
   extractComponentName,
   loadFragmentFile,
-  type DiscoveredFile,
 } from './core/node.js';
+import { validateSnippetPolicy, type SnippetValidationOptions } from './service/snippet-validation.js';
 
 export interface ValidationResult {
   valid: boolean;
@@ -24,6 +24,13 @@ export interface ValidationWarning {
   message: string;
 }
 
+export interface ValidationRunOptions {
+  snippets?: boolean;
+  snippetMode?: 'warn' | 'error';
+  componentStart?: string;
+  componentLimit?: number;
+}
+
 /**
  * Validate fragment file schema
  */
@@ -137,16 +144,57 @@ export async function validateCoverage(
  */
 export async function validateAll(
   config: FragmentsConfig,
-  configDir: string
+  configDir: string,
+  options: ValidationRunOptions = {}
 ): Promise<ValidationResult> {
   const [schemaResult, coverageResult] = await Promise.all([
     validateSchema(config, configDir),
     validateCoverage(config, configDir),
   ]);
 
+  if (options.snippets === false) {
+    return {
+      valid: schemaResult.valid && coverageResult.valid,
+      errors: [...schemaResult.errors, ...coverageResult.errors],
+      warnings: [...schemaResult.warnings, ...coverageResult.warnings],
+    };
+  }
+
+  const snippetOptions: SnippetValidationOptions = {
+    ...(options.snippetMode && { mode: options.snippetMode }),
+    ...(options.componentStart && { componentStart: options.componentStart }),
+    ...(typeof options.componentLimit === 'number'
+      ? { componentLimit: options.componentLimit }
+      : {}),
+  };
+  const snippetResult = await validateSnippetPolicy(config, configDir, snippetOptions);
+
+  return {
+    valid: schemaResult.valid && coverageResult.valid && snippetResult.errors.length === 0,
+    errors: [...schemaResult.errors, ...coverageResult.errors, ...snippetResult.errors],
+    warnings: [...schemaResult.warnings, ...coverageResult.warnings, ...snippetResult.warnings],
+  };
+}
+
+/**
+ * Validate snippet/render policy only.
+ */
+export async function validateSnippets(
+  config: FragmentsConfig,
+  configDir: string,
+  options: ValidationRunOptions = {}
+): Promise<ValidationResult> {
+  const snippetResult = await validateSnippetPolicy(config, configDir, {
+    ...(options.snippetMode && { mode: options.snippetMode }),
+    ...(options.componentStart && { componentStart: options.componentStart }),
+    ...(typeof options.componentLimit === 'number'
+      ? { componentLimit: options.componentLimit }
+      : {}),
+  });
+
   return {
-    valid: schemaResult.valid && coverageResult.valid,
-    errors: [...schemaResult.errors, ...coverageResult.errors],
-    warnings: [...schemaResult.warnings, ...coverageResult.warnings],
+    valid: snippetResult.errors.length === 0,
+    errors: snippetResult.errors,
+    warnings: snippetResult.warnings,
   };
 }