@usefragments/core 1.0.0

package/src/agent-format.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+
+import { buildAgentFormat } from "./agent-format.js";
+import { agentFormatSchema, type Finding } from "./schemas/index.js";
+
+const DEAD_TOOL_NAMES = ["apply_fix", "swap_to_canonical", "tokens.suggest"];
+
+function finding(overrides: Partial<Finding> = {}): Finding {
+  return {
+    ruleId: "styles/no-raw-color",
+    ruleVersion: "1.0.0",
+    severity: "serious",
+    level: "error",
+    code: "FUI2001",
+    message: "Use a token.",
+    fingerprint: "fp_1",
+    location: { file: "src/Button.tsx", line: 1, column: 1 },
+    evidence: [
+      {
+        factId: "fact_1",
+        fact: {
+          kind: "style",
+          location: { file: "src/Button.tsx", line: 1, column: 1 },
+        },
+      },
+    ],
+    ...overrides,
+  };
+}
+
+describe("buildAgentFormat", () => {
+  it("names only hosted MCP tools in fix plans", () => {
+    const agentFormat = buildAgentFormat({
+      filesScanned: 1,
+      findings: [
+        finding({
+          fix: {
+            kind: "replaceStyleValue",
+            title: "Use token",
+            property: "color",
+            value: "var(--color-brand)",
+            deterministic: true,
+          },
+        }),
+        finding({
+          ruleId: "components/prefer-library",
+          code: "FUI1001",
+          fingerprint: "fp_2",
+        }),
+        finding({
+          code: "FUI2002",
+          fingerprint: "fp_3",
+          attributes: { property: "color", rawValue: "#2563eb" },
+        }),
+      ],
+    });
+
+    agentFormatSchema.parse(agentFormat);
+    const toolNames = [...agentFormat.fix_first, ...agentFormat.remaining].map(
+      (entry) => entry.plan.tool
+    );
+
+    expect(new Set(toolNames)).toEqual(new Set(["design_system/conform"]));
+    for (const deadName of DEAD_TOOL_NAMES) {
+      expect(toolNames).not.toContain(deadName);
+    }
+  });
+
+  it("keeps warn-only scans passed when the report summary passed", () => {
+    const agentFormat = buildAgentFormat({
+      filesScanned: 1,
+      passed: true,
+      findings: [
+        finding({
+          severity: "moderate",
+          level: "warn",
+        }),
+      ],
+    });
+
+    expect(agentFormat.passed).toBe(true);
+  });
+
+  it("omits full findings and evidence by default", () => {
+    const agentFormat = buildAgentFormat({
+      filesScanned: 1,
+      findings: [finding()],
+    });
+
+    expect(agentFormat.findings).toBeUndefined();
+    expect([...agentFormat.fix_first, ...agentFormat.remaining][0]?.evidence).toEqual([]);
+  });
+
+  it("keeps a gradient score for noisy scans", () => {
+    const findings = Array.from({ length: 80 }, (_, index) =>
+      finding({
+        fingerprint: `fp_${index}`,
+        severity: "moderate",
+        level: "warn",
+      })
+    );
+
+    expect(buildAgentFormat({ filesScanned: 3, findings }).score).toBeGreaterThan(0);
+  });
+});

package/src/agent-format.ts

@@ -0,0 +1,141 @@
+import { severityLevel } from "./severity.js";
+import type { AgentFormat, Finding } from "./schemas/index.js";
+import type { SuppressionDirectiveFact } from "./facts/index.js";
+
+export interface BuildAgentFormatInput {
+  findings: readonly Finding[];
+  filesScanned: number;
+  passed?: boolean;
+  suppressions?: readonly SuppressionDirectiveFact[];
+  iteration?: number;
+  maxIterations?: number;
+  previousScore?: number;
+  maxFindings?: number;
+  includeEvidence?: boolean;
+  includeFindings?: boolean;
+}
+
+export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
+  const score = scoreFindings(input.findings);
+  const visibleFindings = uniqueFindings(input.findings).slice(0, input.maxFindings ?? 50);
+  const agentFindings = visibleFindings.map((finding) => ({
+    code: finding.code,
+    ruleId: finding.ruleId,
+    filePath: finding.location.file,
+    line: finding.location.line,
+    col: finding.location.column,
+    severity: finding.severity,
+    level: severityLevel(finding.severity),
+    message: finding.message,
+    evidence: input.includeEvidence ? finding.evidence : [],
+    plan: planForFinding(finding),
+  }));
+
+  // Keep this aligned with the report summary: warn-level findings are debt, not
+  // scan failure, unless the caller has already folded fail-on-warnings into
+  // `passed:false`.
+  const hasErrors = input.findings.some((finding) => severityLevel(finding.severity) === "error");
+
+  return {
+    schemaVersion: "typestyle.agent.v1",
+    passed: (input.passed ?? true) && !hasErrors,
+    score,
+    summary: agentSummary(input.findings.length, input.filesScanned, score),
+    fix_first: agentFindings.filter((finding) => finding.plan.confidence >= 0.8),
+    remaining: agentFindings.filter((finding) => finding.plan.confidence < 0.8),
+    suppression_template: {
+      directive: '// @fragments-expect-error {code} reason="..." expires="YYYY-MM-DD"',
+      requiredFields: ["reason"],
+      example:
+        '// @fragments-expect-error FUI2001 reason="hero brand red approved" expires="2026-08-01"',
+    },
+    budget: {
+      iteration: input.iteration ?? 0,
+      maxIterations: input.maxIterations ?? 3,
+      scoreDelta: input.previousScore === undefined ? 0 : score - input.previousScore,
+    },
+    ...(input.includeFindings ? { findings: [...input.findings] } : {}),
+    ...(input.suppressions
+      ? {
+          suppressions: input.suppressions.map((suppression) => ({
+            code: suppression.code,
+            reason: suppression.reason,
+            ...(suppression.expiresOn ? { expiresOn: suppression.expiresOn } : {}),
+            scope: "line" as const,
+          })),
+        }
+      : {}),
+  };
+}
+
+function uniqueFindings(findings: readonly Finding[]): Finding[] {
+  const seen = new Set<string>();
+  const out: Finding[] = [];
+  for (const finding of findings) {
+    const key =
+      finding.fingerprint ??
+      `${finding.ruleId}\0${finding.location.file}\0${finding.location.line}\0${finding.message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(finding);
+  }
+  return out;
+}
+
+function scoreFindings(findings: readonly Finding[]): number {
+  if (findings.length === 0) return 100;
+  let penalty = 0;
+  for (const finding of findings) {
+    const level = severityLevel(finding.severity);
+    penalty += level === "error" ? 10 : level === "warn" ? 3 : 1;
+  }
+  return Math.max(1, Math.round(100 / (1 + penalty / 40)));
+}
+
+function agentSummary(count: number, filesScanned: number, score: number): string {
+  if (count === 0) return `passed with score ${score}; no findings`;
+  return `${count} finding${count === 1 ? "" : "s"} across ${filesScanned} file${filesScanned === 1 ? "" : "s"}; score ${score}`;
+}
+
+function planForFinding(finding: Finding): AgentFormat["fix_first"][number]["plan"] {
+  if (finding.fix?.deterministic === true) {
+    return {
+      tool: "design_system/conform",
+      args: {
+        filePath: finding.location.file,
+        fingerprint: finding.fingerprint,
+        apply: "deterministic",
+      },
+      confidence: 0.95,
+    };
+  }
+  if (
+    finding.code?.startsWith("FUI1") ||
+    finding.ruleId.includes("component") ||
+    finding.ruleId.includes("canonical")
+  ) {
+    return {
+      tool: "design_system/conform",
+      args: { filePath: finding.location.file, apply: "deterministic" },
+      confidence: 0.65,
+    };
+  }
+  return {
+    tool: "design_system/conform",
+    args: {
+      filePath: finding.location.file,
+      property:
+        stringAttribute(finding.attributes?.property) ??
+        stringAttribute(finding.attributes?.prop) ??
+        "color",
+      value:
+        stringAttribute(finding.attributes?.rawValue) ?? stringAttribute(finding.attributes?.color),
+      apply: "deterministic",
+    },
+    confidence: 0.55,
+  };
+}
+
+function stringAttribute(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/bundle.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+
+export const bundleSchemaVersionSchema = z.literal(1);
+export const bundleTargetSchema = z.enum([
+  'cursor',
+  'agents',
+  'claude',
+  'copilot',
+]);
+
+export const bundleArtifactMetadataSchema = z.object({
+  kind: z.enum([
+    'manifest',
+    'tokens',
+    'design-system',
+    'readme',
+    'helper',
+    'component',
+  ]),
+  key: z.string().min(1),
+  label: z.string().min(1),
+  path: z.string().min(1),
+  etag: z.string().min(1),
+  updatedAt: z.string().datetime(),
+  target: bundleTargetSchema.optional(),
+  componentId: z.string().optional(),
+  contentType: z.enum(['application/json', 'text/markdown']),
+});
+
+const bundleManifestRelationSchema = z.object({
+  type: z.string().min(1),
+  componentId: z.string().min(1),
+  name: z.string().min(1),
+});
+
+const bundleManifestCompoundChildSchema = z.object({
+  componentId: z.string().min(1),
+  name: z.string().min(1),
+});
+
+export const bundleManifestComponentEntrySchema = z.object({
+  componentId: z.string().min(1),
+  file: z.string().min(1),
+  name: z.string().min(1),
+  publicSlug: z.string().nullable(),
+  tier: z.enum(['core', 'composition']),
+  category: z.string().min(1),
+  status: z.string().min(1),
+  description: z.string(),
+  propCount: z.number().int().nonnegative(),
+  hasExamples: z.boolean(),
+  hasCompoundChildren: z.boolean(),
+  relations: z.array(bundleManifestRelationSchema),
+  compoundChildren: z.array(bundleManifestCompoundChildSchema),
+});
+
+export const bundleManifestSchema = z.object({
+  schemaVersion: bundleSchemaVersionSchema,
+  catalogRevision: z.string().min(1),
+  catalogUpdatedAt: z.string().datetime(),
+  org: z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    slug: z.string().min(1),
+  }),
+  designSystem: z.object({
+    name: z.string().min(1),
+    packageName: z.string().nullable(),
+    importPath: z.string().nullable(),
+  }),
+  sourceBinding: z.object({
+    bindingId: z.string().min(1),
+    projectId: z.string().min(1),
+    projectName: z.string().min(1),
+    repoFullName: z.string().min(1),
+    resolution: z.enum(['explicit', 'auto']),
+  }),
+  totalComponents: z.number().int().nonnegative(),
+  totalTokens: z.number().int().nonnegative(),
+  tokenCategories: z.record(z.string(), z.number().int().nonnegative()),
+  components: z.record(z.string(), bundleManifestComponentEntrySchema),
+});
+
+const bundleTokenEntrySchema = z.object({
+  name: z.string().min(1),
+  path: z.array(z.string().min(1)),
+  category: z.string().min(1),
+  value: z.string(),
+  type: z.string().optional(),
+  description: z.string().optional(),
+});
+
+export const bundleTokenFileSchema = z.object({
+  schemaVersion: bundleSchemaVersionSchema,
+  catalogRevision: z.string().min(1),
+  catalogUpdatedAt: z.string().datetime(),
+  categories: z.record(
+    z.string(),
+    z.object({
+      count: z.number().int().nonnegative(),
+      tokens: z.array(bundleTokenEntrySchema),
+    }),
+  ),
+  flat: z.array(bundleTokenEntrySchema),
+});
+
+export const bundleComponentShardSchema = z.object({
+  schemaVersion: bundleSchemaVersionSchema,
+  catalogRevision: z.string().min(1),
+  catalogUpdatedAt: z.string().datetime(),
+  componentId: z.string().min(1),
+  file: z.string().min(1),
+  component: z.object({
+    componentKey: z.string().min(1),
+    publicRef: z.string().min(1),
+    publicId: z.string().nullable(),
+    publicSlug: z.string().nullable(),
+    isCanonical: z.boolean().optional(),
+    name: z.string().min(1),
+    tier: z.enum(['core', 'composition']),
+    category: z.string().min(1),
+    status: z.string().min(1),
+    description: z.string(),
+    usageGuidance: z.string(),
+    dos: z.array(z.string()),
+    donts: z.array(z.string()),
+    props: z.record(z.string(), z.unknown()),
+    relations: z.array(z.record(z.string(), z.unknown())),
+    compoundChildren: z.array(bundleManifestCompoundChildSchema),
+    examples: z.array(z.record(z.string(), z.unknown())),
+    source: z.literal('design-system'),
+    sourcePath: z.string().optional(),
+    sourceRepoFullName: z.string().optional(),
+    parentComponentName: z.string().optional(),
+    parentComponentKey: z.string().optional(),
+  }),
+});
+
+export type BundleSchemaVersion = z.infer<typeof bundleSchemaVersionSchema>;
+export type BundleTarget = z.infer<typeof bundleTargetSchema>;
+export type BundleArtifactMetadata = z.infer<
+  typeof bundleArtifactMetadataSchema
+>;
+export type BundleManifestComponentEntry = z.infer<
+  typeof bundleManifestComponentEntrySchema
+>;
+export type BundleManifest = z.infer<typeof bundleManifestSchema>;
+export type BundleComponentShard = z.infer<typeof bundleComponentShardSchema>;
+export type BundleTokenFile = z.infer<typeof bundleTokenFileSchema>;

package/src/codes/__tests__/codes.test.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import {
+  CODES,
+  EXPLAIN_URL_BASE,
+  bridgeSourceViolation,
+  byCode,
+  byRuleId,
+} from "../index.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const registryPath = path.resolve(__dirname, "../../../../../docs/codes/registry.json");
+
+describe("FUI code registry", () => {
+  it("does not contain duplicate codes", () => {
+    expect(new Set(CODES.map((entry) => entry.code)).size).toBe(CODES.length);
+  });
+
+  it("does not contain duplicate rule IDs", () => {
+    expect(new Set(CODES.map((entry) => entry.ruleId)).size).toBe(CODES.length);
+  });
+
+  it("builds lookup maps from the registry", () => {
+    for (const entry of CODES) {
+      expect(byCode.get(entry.code)).toBe(entry);
+      expect(byRuleId.get(entry.ruleId)).toBe(entry);
+      expect(entry.explainUrl).toBe(`${EXPLAIN_URL_BASE}${entry.code}`);
+    }
+  });
+
+  it("matches the committed docs registry snapshot", () => {
+    const snapshot = JSON.parse(readFileSync(registryPath, "utf8"));
+    expect(snapshot).toEqual(CODES);
+  });
+
+  it("bridges source violations into canonical findings with code metadata", () => {
+    const bridged = bridgeSourceViolation({
+      validator: "scss",
+      violation: {
+        nodeId: "scss:src/app.css:2:4",
+        nodeType: "ScssDeclaration",
+        rule: "tokens/require-dual-fallback",
+        severity: "serious",
+        message: "Token fallback is missing",
+        filePath: "src/app.css",
+        line: 2,
+        column: 4,
+        rawValue: "var(--fui-color-accent)",
+      },
+    });
+
+    expect(bridged.finding).toMatchObject({
+      ruleId: "tokens/require-dual-fallback",
+      code: "FUI2003",
+      helpUrl: `${EXPLAIN_URL_BASE}FUI2003`,
+      location: { file: "src/app.css", line: 2, column: 4 },
+      attributes: {
+        source: "source-validator",
+        validator: "scss",
+        rawValue: "var(--fui-color-accent)",
+      },
+    });
+    expect(bridged.violation).toMatchObject({
+      code: "FUI2003",
+      helpUrl: `${EXPLAIN_URL_BASE}FUI2003`,
+      level: "error",
+    });
+  });
+});