@fragments-sdk/cli 0.7.4 → 0.7.5

package/src/core/types.ts

@@ -426,6 +426,24 @@ export interface CIConfig {
   jsonOutput?: boolean;
 }
 
+/**
+ * Snippet policy configuration.
+ * Controls snippet/render quality enforcement in `fragments validate`.
+ */
+export interface SnippetPolicyConfig {
+  /** Validation mode: warn (non-blocking) or error (blocking). Default: warn */
+  mode?: "warn" | "error";
+
+  /** Validate snippet strings only, or snippet strings + render functions. Default: snippet+render */
+  scope?: "snippet" | "snippet+render";
+
+  /** Require authored snippets to be full, copy-pasteable examples with imports. Default: true */
+  requireFullSnippet?: boolean;
+
+  /** Allow these external modules for JSX components in snippets/renders. */
+  allowedExternalModules?: string[];
+}
+
 /**
  * Config file structure
  */
@@ -465,6 +483,9 @@ export interface FragmentsConfig {
 
   /** CI pipeline configuration */
   ci?: CIConfig;
+
+  /** Snippet/render policy validation */
+  snippets?: SnippetPolicyConfig;
 }
 
 /**

package/src/index.ts

@@ -9,11 +9,12 @@ export {
 export type { DiscoveredFile } from "./core/node.js";
 
 // Validators
-export { validateSchema, validateCoverage, validateAll } from "./validators.js";
+export { validateSchema, validateCoverage, validateAll, validateSnippets } from "./validators.js";
 export type {
   ValidationResult,
   ValidationError,
   ValidationWarning,
+  ValidationRunOptions,
 } from "./validators.js";
 
 // Build

package/src/service/snippet-validation.test.ts

@@ -0,0 +1,209 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { FragmentsConfig } from '../core/types.js';
+import { validateSnippetPolicy } from './snippet-validation.js';
+
+async function createTempProject(): Promise<string> {
+  return mkdtemp(resolve(tmpdir(), 'fragments-snippets-'));
+}
+
+async function writeFragment(projectDir: string, componentName: string, content: string): Promise<void> {
+  const dir = resolve(projectDir, 'src/components', componentName);
+  await mkdir(dir, { recursive: true });
+  await writeFile(resolve(dir, `${componentName}.fragment.tsx`), content);
+}
+
+const baseConfig: FragmentsConfig = {
+  include: ['src/**/*.fragment.tsx'],
+  exclude: ['**/node_modules/**'],
+  framework: 'react',
+  snippets: {
+    mode: 'warn',
+    scope: 'snippet+render',
+    requireFullSnippet: true,
+    allowedExternalModules: ['@phosphor-icons/react'],
+  },
+};
+
+let lastProjectDir: string | null = null;
+
+afterEach(async () => {
+  if (lastProjectDir) {
+    await rm(lastProjectDir, { recursive: true, force: true });
+    lastProjectDir = null;
+  }
+});
+
+describe('validateSnippetPolicy', () => {
+  it('reports snippet and render violations in warn mode', async () => {
+    const projectDir = await createTempProject();
+    lastProjectDir = projectDir;
+
+    await writeFragment(
+      projectDir,
+      'Button',
+      `import React from 'react';
+import { defineFragment } from '@fragments/core';
+import { Button } from '.';
+
+export default defineFragment({
+  component: Button,
+  meta: { name: 'Button', description: 'Button', category: 'actions' },
+  usage: { when: ['x'], whenNot: ['y'] },
+  props: {},
+  variants: [
+    {
+      name: 'Default',
+      description: 'Default',
+      code: '<Button />',
+      render: () => (
+        <div style={{ display: 'flex' }}>
+          <Button>Click</Button>
+        </div>
+      ),
+    },
+  ],
+});
+`,
+    );
+
+    const result = await validateSnippetPolicy(baseConfig, projectDir);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.warnings.some((w) => w.message.includes('full snippet required (missing import statement)'))).toBe(true);
+    expect(result.warnings.some((w) => w.message.includes('inline style usage is not allowed'))).toBe(true);
+    expect(result.warnings.some((w) => w.message.includes('raw HTML tags are not allowed'))).toBe(true);
+  });
+
+  it('allows approved external JSX modules in snippets', async () => {
+    const projectDir = await createTempProject();
+    lastProjectDir = projectDir;
+
+    await writeFragment(
+      projectDir,
+      'Icon',
+      `import React from 'react';
+import { defineFragment } from '@fragments/core';
+import { Icon } from '.';
+
+export default defineFragment({
+  component: Icon,
+  meta: { name: 'Icon', description: 'Icon', category: 'display' },
+  usage: { when: ['x'], whenNot: ['y'] },
+  props: {},
+  variants: [
+    {
+      name: 'Default',
+      description: 'Default',
+      code: \`import { Icon } from '@fragments-sdk/ui';
+import { House } from '@phosphor-icons/react';
+
+<Icon icon={House} />
+<House />\`,
+      render: () => <Icon icon={() => null} />,
+    },
+  ],
+});
+`,
+    );
+
+    const result = await validateSnippetPolicy(baseConfig, projectDir);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  it('does not treat PascalCase component names like Header as intrinsic html tags', async () => {
+    const projectDir = await createTempProject();
+    lastProjectDir = projectDir;
+
+    await writeFragment(
+      projectDir,
+      'Header',
+      `import React from 'react';
+import { defineFragment } from '@fragments/core';
+import { Header } from '.';
+
+export default defineFragment({
+  component: Header,
+  meta: { name: 'Header', description: 'Header', category: 'layout' },
+  usage: { when: ['x'], whenNot: ['y'] },
+  props: {},
+  variants: [
+    {
+      name: 'Default',
+      description: 'Default',
+      code: \`import { Header } from '@/components/Header';
+
+<Header>
+  <Header.Brand>MyApp</Header.Brand>
+</Header>\`,
+      render: () => (
+        <Header>
+          <Header.Brand>MyApp</Header.Brand>
+        </Header>
+      ),
+    },
+  ],
+});
+`,
+    );
+
+    const result = await validateSnippetPolicy(baseConfig, projectDir);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  it('supports error mode and alphabetical component batch filtering', async () => {
+    const projectDir = await createTempProject();
+    lastProjectDir = projectDir;
+
+    await writeFragment(
+      projectDir,
+      'Alpha',
+      `import React from 'react';
+import { defineFragment } from '@fragments/core';
+import { Alpha } from '.';
+
+export default defineFragment({
+  component: Alpha,
+  meta: { name: 'Alpha', description: 'Alpha', category: 'display' },
+  usage: { when: ['x'], whenNot: ['y'] },
+  props: {},
+  variants: [{ name: 'Default', description: 'Default', render: () => <Alpha /> }],
+});
+`,
+    );
+
+    await writeFragment(
+      projectDir,
+      'Beta',
+      `import React from 'react';
+import { defineFragment } from '@fragments/core';
+import { Beta } from '.';
+
+export default defineFragment({
+  component: Beta,
+  meta: { name: 'Beta', description: 'Beta', category: 'display' },
+  usage: { when: ['x'], whenNot: ['y'] },
+  props: {},
+  variants: [{ name: 'Default', description: 'Default', render: () => <Beta /> }],
+});
+`,
+    );
+
+    const result = await validateSnippetPolicy(baseConfig, projectDir, {
+      mode: 'error',
+      componentStart: 'Beta',
+      componentLimit: 1,
+    });
+
+    expect(result.warnings).toHaveLength(0);
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors.every((issue) => issue.file.includes('Beta.fragment.tsx'))).toBe(true);
+  });
+});