@usefragments/core 1.0.0

package/dist/schemas/index.js

@@ -0,0 +1,55 @@
+import {
+  agentFindingSchema,
+  agentFormatSchema,
+  agentPlanSchema,
+  factEvidenceSchema,
+  factLocationSchema,
+  findingFixSchema,
+  findingReplaceClassTokenFixSchema,
+  findingReplaceComponentFixSchema,
+  findingReplaceImportFixSchema,
+  findingReplacePropValueFixSchema,
+  findingReplaceStyleValueFixSchema,
+  findingSchema,
+  fixSchema,
+  governanceVerdictMetadataSchema,
+  governanceVerdictSchema,
+  normalizeFinding,
+  normalizeSeverity,
+  normalizeViolation,
+  suppressionDirectiveSchema,
+  validatorResultSchema,
+  violationSchema
+} from "../chunk-R3X7UBHU.js";
+import {
+  legacySeverityLevelSchema,
+  severityLevelSchema,
+  severitySchema
+} from "../chunk-V4VQB57N.js";
+export {
+  agentFindingSchema,
+  agentFormatSchema,
+  agentPlanSchema,
+  factEvidenceSchema,
+  factLocationSchema,
+  findingFixSchema,
+  findingReplaceClassTokenFixSchema,
+  findingReplaceComponentFixSchema,
+  findingReplaceImportFixSchema,
+  findingReplacePropValueFixSchema,
+  findingReplaceStyleValueFixSchema,
+  findingSchema,
+  fixSchema,
+  governanceVerdictMetadataSchema,
+  governanceVerdictSchema,
+  legacySeverityLevelSchema,
+  normalizeFinding,
+  normalizeSeverity,
+  normalizeViolation,
+  severityLevelSchema,
+  severitySchema,
+  suppressionDirectiveSchema,
+  validatorResultSchema,
+  violationSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/severity.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+declare const severitySchema: z.ZodEnum<["critical", "serious", "moderate", "minor"]>;
+type Severity = z.infer<typeof severitySchema>;
+declare const severityLevelSchema: z.ZodEnum<["error", "warn"]>;
+type SeverityLevel = z.infer<typeof severityLevelSchema>;
+declare const legacySeverityLevelSchema: z.ZodEnum<["error", "warn", "info", "warning"]>;
+type LegacySeverityLevel = z.infer<typeof legacySeverityLevelSchema>;
+declare const SEVERITIES: ["critical", "serious", "moderate", "minor"];
+declare const SEVERITY_WEIGHTS: Record<Severity, number>;
+declare const SEVERITY_RANK: Record<Severity, number>;
+declare function severityLevel(severity: Severity): SeverityLevel;
+declare function severityFromLevel(level: LegacySeverityLevel): Severity;
+declare function compareSeverity(a: Severity, b: Severity): number;
+declare function maxSeverity(a: Severity, b: Severity): Severity;
+declare function sortBySeverity<T>(items: readonly T[], getSeverity: (item: T) => Severity): T[];
+
+export { type LegacySeverityLevel, SEVERITIES, SEVERITY_RANK, SEVERITY_WEIGHTS, type Severity, type SeverityLevel, compareSeverity, legacySeverityLevelSchema, maxSeverity, severityFromLevel, severityLevel, severityLevelSchema, severitySchema, sortBySeverity };

package/dist/severity.js

@@ -0,0 +1,27 @@
+import {
+  SEVERITIES,
+  SEVERITY_RANK,
+  SEVERITY_WEIGHTS,
+  compareSeverity,
+  legacySeverityLevelSchema,
+  maxSeverity,
+  severityFromLevel,
+  severityLevel,
+  severityLevelSchema,
+  severitySchema,
+  sortBySeverity
+} from "./chunk-V4VQB57N.js";
+export {
+  SEVERITIES,
+  SEVERITY_RANK,
+  SEVERITY_WEIGHTS,
+  compareSeverity,
+  legacySeverityLevelSchema,
+  maxSeverity,
+  severityFromLevel,
+  severityLevel,
+  severityLevelSchema,
+  severitySchema,
+  sortBySeverity
+};
+//# sourceMappingURL=severity.js.map

package/dist/severity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/test-utils.d.ts

@@ -0,0 +1,14 @@
+import { C as CompiledBlock, b as CompiledFragment } from './governance-BOa3KyiJ.js';
+import 'zod';
+import 'react';
+import './topology/index.js';
+import './types-xJ2xyp_G.js';
+
+/**
+ * Shared factory builders for compiled-fragment tests.
+ */
+
+declare function makeCompiledFragment(overrides?: Partial<CompiledFragment>): CompiledFragment;
+declare function makeCompiledBlock(overrides?: Partial<CompiledBlock>): CompiledBlock;
+
+export { makeCompiledBlock, makeCompiledFragment };

package/dist/test-utils.js

@@ -0,0 +1,63 @@
+// src/test-utils.ts
+function makeCompiledFragment(overrides = {}) {
+  return {
+    filePath: "src/components/Button/Button.fragment.tsx",
+    meta: {
+      name: "Button",
+      description: "A clickable button element",
+      category: "actions",
+      status: "stable",
+      tags: ["interactive"],
+      ...overrides.meta
+    },
+    usage: {
+      when: ["Triggering an action", "Submitting a form"],
+      whenNot: ["Navigating to another page"],
+      ...overrides.usage
+    },
+    props: overrides.props ?? {
+      variant: {
+        type: "enum",
+        values: ["primary", "secondary", "ghost"],
+        default: "primary",
+        description: "Visual style variant"
+      },
+      size: {
+        type: "enum",
+        values: ["sm", "md", "lg"],
+        default: "md",
+        description: "Button size"
+      },
+      disabled: {
+        type: "boolean",
+        default: false,
+        description: "Whether the button is disabled"
+      }
+    },
+    variants: overrides.variants ?? [
+      { name: "Primary", description: "Default primary button", code: "<Button>Click</Button>" },
+      { name: "Secondary", description: "Secondary variant", code: '<Button variant="secondary">Click</Button>' }
+    ],
+    relations: overrides.relations,
+    contract: overrides.contract,
+    ai: overrides.ai,
+    _generated: overrides._generated
+  };
+}
+function makeCompiledBlock(overrides = {}) {
+  return {
+    filePath: "src/blocks/LoginForm.block.ts",
+    name: "Login Form",
+    description: "A standard login form with email and password fields",
+    category: "authentication",
+    components: ["Input", "Button"],
+    code: '<form>\n  <Input label="Email" />\n  <Input label="Password" type="password" />\n  <Button>Sign In</Button>\n</form>',
+    tags: ["auth", "form"],
+    ...overrides
+  };
+}
+export {
+  makeCompiledBlock,
+  makeCompiledFragment
+};
+//# sourceMappingURL=test-utils.js.map

package/dist/test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/test-utils.ts"],"sourcesContent":["/**\n * Shared factory builders for compiled-fragment tests.\n */\n\nimport type { CompiledFragment, CompiledBlock } from \"./compiled-types/index.js\";\n\nexport function makeCompiledFragment(\n  overrides: Partial<CompiledFragment> = {},\n): CompiledFragment {\n  return {\n    filePath: \"src/components/Button/Button.fragment.tsx\",\n    meta: {\n      name: \"Button\",\n      description: \"A clickable button element\",\n      category: \"actions\",\n      status: \"stable\",\n      tags: [\"interactive\"],\n      ...overrides.meta,\n    },\n    usage: {\n      when: [\"Triggering an action\", \"Submitting a form\"],\n      whenNot: [\"Navigating to another page\"],\n      ...overrides.usage,\n    },\n    props: overrides.props ?? {\n      variant: {\n        type: \"enum\",\n        values: [\"primary\", \"secondary\", \"ghost\"],\n        default: \"primary\",\n        description: \"Visual style variant\",\n      },\n      size: {\n        type: \"enum\",\n        values: [\"sm\", \"md\", \"lg\"],\n        default: \"md\",\n        description: \"Button size\",\n      },\n      disabled: {\n        type: \"boolean\",\n        default: false,\n        description: \"Whether the button is disabled\",\n      },\n    },\n    variants: overrides.variants ?? [\n      { name: \"Primary\", description: \"Default primary button\", code: \"<Button>Click</Button>\" },\n      { name: \"Secondary\", description: \"Secondary variant\", code: '<Button variant=\"secondary\">Click</Button>' },\n    ],\n    relations: overrides.relations,\n    contract: overrides.contract,\n    ai: overrides.ai,\n    _generated: overrides._generated,\n  };\n}\n\nexport function makeCompiledBlock(\n  overrides: Partial<CompiledBlock> = {},\n): CompiledBlock {\n  return {\n    filePath: \"src/blocks/LoginForm.block.ts\",\n    name: \"Login Form\",\n    description: \"A standard login form with email and password fields\",\n    category: \"authentication\",\n    components: [\"Input\", \"Button\"],\n    code: '<form>\\n  <Input label=\"Email\" />\\n  <Input label=\"Password\" type=\"password\" />\\n  <Button>Sign In</Button>\\n</form>',\n    tags: [\"auth\", \"form\"],\n    ...overrides,\n  };\n}\n"],"mappings":";AAMO,SAAS,qBACd,YAAuC,CAAC,GACtB;AAClB,SAAO;AAAA,IACL,UAAU;AAAA,IACV,MAAM;AAAA,MACJ,MAAM;AAAA,MACN,aAAa;AAAA,MACb,UAAU;AAAA,MACV,QAAQ;AAAA,MACR,MAAM,CAAC,aAAa;AAAA,MACpB,GAAG,UAAU;AAAA,IACf;AAAA,IACA,OAAO;AAAA,MACL,MAAM,CAAC,wBAAwB,mBAAmB;AAAA,MAClD,SAAS,CAAC,4BAA4B;AAAA,MACtC,GAAG,UAAU;AAAA,IACf;AAAA,IACA,OAAO,UAAU,SAAS;AAAA,MACxB,SAAS;AAAA,QACP,MAAM;AAAA,QACN,QAAQ,CAAC,WAAW,aAAa,OAAO;AAAA,QACxC,SAAS;AAAA,QACT,aAAa;AAAA,MACf;AAAA,MACA,MAAM;AAAA,QACJ,MAAM;AAAA,QACN,QAAQ,CAAC,MAAM,MAAM,IAAI;AAAA,QACzB,SAAS;AAAA,QACT,aAAa;AAAA,MACf;AAAA,MACA,UAAU;AAAA,QACR,MAAM;AAAA,QACN,SAAS;AAAA,QACT,aAAa;AAAA,MACf;AAAA,IACF;AAAA,IACA,UAAU,UAAU,YAAY;AAAA,MAC9B,EAAE,MAAM,WAAW,aAAa,0BAA0B,MAAM,yBAAyB;AAAA,MACzF,EAAE,MAAM,aAAa,aAAa,qBAAqB,MAAM,6CAA6C;AAAA,IAC5G;AAAA,IACA,WAAW,UAAU;AAAA,IACrB,UAAU,UAAU;AAAA,IACpB,IAAI,UAAU;AAAA,IACd,YAAY,UAAU;AAAA,EACxB;AACF;AAEO,SAAS,kBACd,YAAoC,CAAC,GACtB;AACf,SAAO;AAAA,IACL,UAAU;AAAA,IACV,MAAM;AAAA,IACN,aAAa;AAAA,IACb,UAAU;AAAA,IACV,YAAY,CAAC,SAAS,QAAQ;AAAA,IAC9B,MAAM;AAAA,IACN,MAAM,CAAC,QAAQ,MAAM;AAAA,IACrB,GAAG;AAAA,EACL;AACF;","names":[]}

package/dist/topology/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Topology — map a repo-relative file path to its product area.
+ *
+ * This is the DRY keystone of the topology layer: the ONLY area-matching
+ * implementation in the monorepo. Consumers (CLI scan, Cloud managed-editor
+ * preview, cross-repo reconciliation) import it; none reimplements glob/area
+ * logic. Pure and browser-safe — no Node, no parser deps.
+ *
+ * See `apps/cloud/docs/topology/01-architecture.md §1`.
+ */
+type AreaCriticality = "low" | "medium" | "high" | "revenue" | "regulated";
+interface Area {
+    id: string;
+    name: string;
+    criticality: AreaCriticality;
+    owners: string[];
+    /** Globs matched against repo-relative file paths in v0. */
+    files: string[];
+    /** Stored for later route-topology adapters; NOT matched in v0. */
+    routes?: string[];
+    /** Tie-break: higher wins. Defaults to declaration order. */
+    priority?: number;
+}
+interface Topology {
+    /** Bump signals "re-tag" to consumers that cache. */
+    version: number;
+    /** Whether area file globs are matched relative to app.path or repo root. Defaults to "app". */
+    base?: "app" | "repo";
+    /** Array (not a keyed record) so precedence is deterministic. */
+    areas: Area[];
+}
+interface AreaMatch {
+    areaId: string;
+    areaName: string;
+    criticality: AreaCriticality;
+    owners: string[];
+    /** The winning pattern — surfaced in reports for transparency. */
+    matchedGlob: string;
+}
+/**
+ * Resolve the product area for a repo-relative path. First match by
+ * `(priority desc, declaration order)`. Returns `null` when nothing matches —
+ * the caller buckets that as the explicit "Unassigned" area (never dropped;
+ * dropping unmatched evidence would make coverage lie).
+ */
+declare function resolveArea(repoRelPath: string, topology: Topology): AreaMatch | null;
+
+export { type Area, type AreaCriticality, type AreaMatch, type Topology, resolveArea };

package/dist/topology/index.js

@@ -0,0 +1,7 @@
+import {
+  resolveArea
+} from "../chunk-3LLRNCPX.js";
+export {
+  resolveArea
+};
+//# sourceMappingURL=index.js.map

package/dist/topology/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-xJ2xyp_G.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Component Graph data model — types for the design-system-semantic relationship graph.
+ *
+ * These types describe nodes (components), edges (relationships), and health
+ * metrics that together give AI agents structural understanding of a design system.
+ */
+type GraphEdgeType = 'imports' | 'hook-depends' | 'renders' | 'composes' | 'parent-of' | 'alternative-to' | 'sibling-of';
+declare const GRAPH_EDGE_TYPES: readonly GraphEdgeType[];
+/** Default weight for each edge type */
+declare const EDGE_TYPE_WEIGHTS: Record<GraphEdgeType, number>;
+interface ComponentNode {
+    name: string;
+    category: string;
+    status: string;
+    compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
+    subComponents?: string[];
+}
+interface GraphEdge {
+    source: string;
+    target: string;
+    type: GraphEdgeType;
+    weight: number;
+    note?: string;
+    /** Where this edge was detected from */
+    provenance: string;
+}
+interface GraphHealth {
+    /** Components with zero edges */
+    orphans: string[];
+    /** Top components by total degree (in + out) */
+    hubs: Array<{
+        name: string;
+        degree: number;
+    }>;
+    /** Percentage of components appearing in at least one block */
+    compositionCoverage: number;
+    /** Disconnected groups (BFS on undirected projection) */
+    connectedComponents: string[][];
+    /** Average degree across all nodes */
+    averageDegree: number;
+    /** Total node and edge counts */
+    nodeCount: number;
+    edgeCount: number;
+}
+interface ComponentGraph {
+    nodes: ComponentNode[];
+    edges: GraphEdge[];
+    health: GraphHealth;
+}
+interface ImpactResult {
+    /** The component that was changed */
+    component: string;
+    /** Components affected at each depth level */
+    affected: Array<{
+        component: string;
+        depth: number;
+        path: string[];
+        edgeType: GraphEdgeType;
+    }>;
+    /** Blocks that use the changed component or any affected component */
+    affectedBlocks: string[];
+    /** Total count of affected components */
+    totalAffected: number;
+}
+interface PathResult {
+    /** Whether a path exists */
+    found: boolean;
+    /** Nodes along the shortest path (including source and target) */
+    path: string[];
+    /** Edges along the shortest path */
+    edges: GraphEdge[];
+}
+interface NeighborResult {
+    /** The center component */
+    component: string;
+    /** All components reachable within maxHops */
+    neighbors: Array<{
+        component: string;
+        hops: number;
+        edgeType: GraphEdgeType;
+    }>;
+}
+interface CompositionTree {
+    /** The root component */
+    component: string;
+    /** Composition pattern */
+    compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
+    /** Direct sub-components */
+    subComponents: string[];
+    /** Components that declare this component as their parent */
+    children: string[];
+    /** Parent component (if this is a sub-component) */
+    parent?: string;
+    /** Sibling components at the same level */
+    siblings: string[];
+    /** Blocks that use this component */
+    blocks: string[];
+}
+interface SerializedEdge {
+    /** source */
+    s: string;
+    /** target */
+    t: string;
+    /** type */
+    ty: GraphEdgeType;
+    /** weight */
+    w: number;
+    /** note (optional) */
+    no?: string;
+    /** provenance */
+    p: string;
+}
+interface SerializedComponentGraph {
+    nodes: ComponentNode[];
+    edges: SerializedEdge[];
+    health: GraphHealth;
+}
+
+export { type ComponentGraph as C, EDGE_TYPE_WEIGHTS as E, type GraphEdgeType as G, type ImpactResult as I, type NeighborResult as N, type PathResult as P, type SerializedComponentGraph as S, type GraphEdge as a, type CompositionTree as b, type GraphHealth as c, type ComponentNode as d, GRAPH_EDGE_TYPES as e, type SerializedEdge as f };

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@usefragments/core",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Core types, schemas, and runtime API for Fragments component definitions",
+  "author": "Conan McNicholl",
+  "homepage": "https://usefragments.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fragments-sdk/fragments",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./react": {
+      "types": "./dist/react-types.d.ts",
+      "import": "./dist/react-types.js"
+    },
+    "./compiled-types": {
+      "types": "./dist/compiled-types/index.d.ts",
+      "import": "./dist/compiled-types/index.js"
+    },
+    "./graph": {
+      "types": "./dist/graph/index.d.ts",
+      "import": "./dist/graph/index.js"
+    },
+    "./topology": {
+      "types": "./dist/topology/index.d.ts",
+      "import": "./dist/topology/index.js"
+    },
+    "./generate": {
+      "types": "./dist/generate/index.d.ts",
+      "import": "./dist/generate/index.js"
+    },
+    "./codes": {
+      "types": "./dist/codes/index.d.ts",
+      "import": "./dist/codes/index.js"
+    },
+    "./severity": {
+      "types": "./dist/severity.d.ts",
+      "import": "./dist/severity.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js"
+    },
+    "./preview": {
+      "types": "./dist/preview/index.d.ts",
+      "import": "./dist/preview/index.js"
+    },
+    "./package-identity": {
+      "types": "./dist/package-identity.d.ts",
+      "import": "./dist/package-identity.js"
+    },
+    "./test-utils": {
+      "types": "./dist/test-utils.d.ts",
+      "import": "./dist/test-utils.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "fragments",
+    "design-system",
+    "component-library",
+    "react",
+    "types",
+    "schema",
+    "ai",
+    "mcp"
+  ],
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@storybook/csf": "^0.1.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@storybook/csf": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@storybook/csf": "^0.1.12",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^18.3.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}