@usefragments/core 1.10.2 → 2.0.0

package/dist/chunk-RYFULE43.js

@@ -0,0 +1,578 @@
+// src/compiled-types/index.ts
+var CompiledFragmentsFileValidationError = class extends Error {
+  source;
+  issues;
+  constructor(source, issues) {
+    const orderedIssues = [...issues].sort(compareStrings);
+    super(`Invalid compiled Fragments catalog at ${source}: ${orderedIssues.join("; ")}`);
+    this.name = "CompiledFragmentsFileValidationError";
+    this.source = source;
+    this.issues = orderedIssues;
+  }
+};
+function parseCompiledFragmentsFile(input, source = "fragments.json") {
+  let value = input;
+  if (typeof input === "string") {
+    try {
+      value = JSON.parse(input);
+    } catch {
+      throw new CompiledFragmentsFileValidationError(source, ["invalid JSON"]);
+    }
+  }
+  const issues = [];
+  if (!isRecord(value)) {
+    throw new CompiledFragmentsFileValidationError(source, ["root must be an object"]);
+  }
+  if (typeof value.version !== "string" || value.version.length === 0) {
+    issues.push("version must be a non-empty string");
+  }
+  if (typeof value.generatedAt !== "string" || value.generatedAt.length === 0) {
+    issues.push("generatedAt must be a non-empty string");
+  }
+  if (!isRecord(value.fragments)) {
+    issues.push("fragments must be an object");
+  } else {
+    const names = /* @__PURE__ */ new Map();
+    for (const [key, fragment] of sortedEntries(value.fragments)) {
+      validateCompiledFragment(key, fragment, issues);
+      if (!isRecord(fragment) || !isRecord(fragment.meta) || typeof fragment.meta.name !== "string") {
+        continue;
+      }
+      const previousKey = names.get(fragment.meta.name);
+      if (previousKey !== void 0) {
+        issues.push(
+          `fragments.${key}.meta.name duplicates fragments.${previousKey}.meta.name (${JSON.stringify(fragment.meta.name)})`
+        );
+      } else {
+        names.set(fragment.meta.name, key);
+      }
+    }
+  }
+  validateOptionalString(value.generatorVersion, "generatorVersion", issues);
+  validateOptionalString(value.packageName, "packageName", issues);
+  validateOptionalStringArray(value.buildInputs, "buildInputs", issues);
+  validateCompiledBlockMap(value.blocks, "blocks", issues);
+  validateCompiledBlockMap(value.recipes, "recipes", issues);
+  validateCompiledTokens(value.tokens, issues);
+  validateSerializedGraph(value.graph, issues);
+  validatePerformanceSummary(value.performanceSummary, issues);
+  if (issues.length > 0) throw new CompiledFragmentsFileValidationError(source, issues);
+  return value;
+}
+function validateCompiledFragment(key, value, issues) {
+  const path = `fragments.${key}`;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateString(value.filePath, `${path}.filePath`, issues);
+  validateFragmentMeta(value.meta, `${path}.meta`, issues);
+  validateFragmentUsage(value.usage, `${path}.usage`, issues);
+  if (value.guidance !== void 0) {
+    validateFragmentUsage(value.guidance, `${path}.guidance`, issues);
+  }
+  validateFragmentProps(value.props, `${path}.props`, issues);
+  validateFragmentVariants(value.variants, `${path}.variants`, issues);
+  validateOptionalRecordArray(value.governance, `${path}.governance`, issues);
+  validateRelations(value.relations, `${path}.relations`, issues);
+  validateFragmentPreview(value.preview, `${path}.preview`, issues);
+  validateFragmentMatrix(value.matrix, `${path}.matrix`, issues);
+  validateFragmentDesign(value.design, `${path}.design`, issues);
+  validateOptionalStringArray(value.tokens, `${path}.tokens`, issues);
+  validateOptionalRecord(value.ai, `${path}.ai`, issues);
+  validateOptionalString(value.framework, `${path}.framework`, issues);
+  validateOptionalStringArray(value.propsSummary, `${path}.propsSummary`, issues);
+  validateOptionalString(value.sourcePath, `${path}.sourcePath`, issues);
+  validateOptionalString(value.exportName, `${path}.exportName`, issues);
+  validateFragmentProvenance(value.provenance, `${path}.provenance`, issues);
+  validateFragmentGenerated(value._generated, `${path}._generated`, issues);
+  validateObservedUsages(value.usages, `${path}.usages`, issues);
+  validatePerformanceData(value.performance, `${path}.performance`, issues);
+}
+function validateFragmentMeta(value, path, issues) {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateString(value.name, `${path}.name`, issues);
+  validateString(value.description, `${path}.description`, issues);
+  validateString(value.category, `${path}.category`, issues);
+  validateOptionalStringArray(value.aliases, `${path}.aliases`, issues);
+  validateOptionalStringArray(value.tags, `${path}.tags`, issues);
+  if (value.status !== void 0 && !["stable", "beta", "deprecated", "experimental"].includes(String(value.status))) {
+    issues.push(`${path}.status must be stable, beta, deprecated, or experimental`);
+  }
+  validateOptionalString(value.since, `${path}.since`, issues);
+  validateOptionalString(value.figma, `${path}.figma`, issues);
+  validateOptionalRecord(value.figmaProps, `${path}.figmaProps`, issues);
+  if (value.dependencies !== void 0) {
+    if (!Array.isArray(value.dependencies)) {
+      issues.push(`${path}.dependencies must be an array`);
+    } else {
+      value.dependencies.forEach((dependency, index) => {
+        const dependencyPath = `${path}.dependencies.${index}`;
+        if (!isRecord(dependency)) {
+          issues.push(`${dependencyPath} must be an object`);
+          return;
+        }
+        validateString(dependency.name, `${dependencyPath}.name`, issues);
+        validateString(dependency.version, `${dependencyPath}.version`, issues);
+        validateOptionalString(dependency.reason, `${dependencyPath}.reason`, issues);
+      });
+    }
+  }
+}
+function validateFragmentUsage(value, path, issues) {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateStringArray(value.when, `${path}.when`, issues);
+  validateStringArray(value.whenNot, `${path}.whenNot`, issues);
+  validateOptionalStringArray(value.guidelines, `${path}.guidelines`, issues);
+  validateOptionalStringArray(value.accessibility, `${path}.accessibility`, issues);
+  if (value.choose !== void 0) {
+    validateStringRecord(value.choose, `${path}.choose`, issues);
+  }
+  if (value.dont !== void 0) {
+    if (!Array.isArray(value.dont)) {
+      issues.push(`${path}.dont must be an array`);
+    } else {
+      value.dont.forEach((entry, index) => {
+        const entryPath = `${path}.dont.${index}`;
+        if (!isRecord(entry)) {
+          issues.push(`${entryPath} must be an object`);
+          return;
+        }
+        validateString(entry.reason, `${entryPath}.reason`, issues);
+        validateString(entry.bad, `${entryPath}.bad`, issues);
+        validateString(entry.good, `${entryPath}.good`, issues);
+      });
+    }
+  }
+}
+function validateFragmentProps(value, path, issues) {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  for (const [name, prop] of sortedEntries(value)) {
+    const propPath = `${path}.${name}`;
+    if (!isRecord(prop)) {
+      issues.push(`${propPath} must be an object`);
+      continue;
+    }
+    validateString(prop.type, `${propPath}.type`, issues);
+    validateString(prop.description, `${propPath}.description`, issues);
+    validateOptionalStringArray(prop.values, `${propPath}.values`, issues);
+    validateOptionalBoolean(prop.required, `${propPath}.required`, issues);
+    validateOptionalStringArray(prop.constraints, `${propPath}.constraints`, issues);
+    validateOptionalRecord(prop.typeDetails, `${propPath}.typeDetails`, issues);
+    validateOptionalString(prop.controlType, `${propPath}.controlType`, issues);
+    validateOptionalRecord(prop.controlOptions, `${propPath}.controlOptions`, issues);
+    if (prop.visibility !== void 0 && prop.visibility !== "public" && prop.visibility !== "internal" && prop.visibility !== "hidden") {
+      issues.push(`${propPath}.visibility must be public, internal, or hidden`);
+    }
+  }
+}
+function validateFragmentVariants(value, path, issues) {
+  if (!Array.isArray(value)) {
+    issues.push(`${path} must be an array`);
+    return;
+  }
+  const names = /* @__PURE__ */ new Set();
+  value.forEach((variant, index) => {
+    const variantPath = `${path}.${index}`;
+    if (!isRecord(variant)) {
+      issues.push(`${variantPath} must be an object`);
+      return;
+    }
+    validateString(variant.name, `${variantPath}.name`, issues);
+    validateString(variant.description, `${variantPath}.description`, issues);
+    validateOptionalString(variant.code, `${variantPath}.code`, issues);
+    validateOptionalString(variant.figma, `${variantPath}.figma`, issues);
+    validateOptionalBoolean(variant.canonical, `${variantPath}.canonical`, issues);
+    validateOptionalRecord(variant.args, `${variantPath}.args`, issues);
+    if (typeof variant.name === "string") {
+      if (names.has(variant.name)) {
+        issues.push(
+          `${variantPath}.name duplicates an earlier variant (${JSON.stringify(variant.name)})`
+        );
+      }
+      names.add(variant.name);
+    }
+  });
+}
+function validateRelations(value, path, issues) {
+  if (value === void 0) return;
+  if (!Array.isArray(value)) {
+    issues.push(`${path} must be an array`);
+    return;
+  }
+  value.forEach((relation, index) => {
+    const relationPath = `${path}.${index}`;
+    if (!isRecord(relation)) {
+      issues.push(`${relationPath} must be an object`);
+      return;
+    }
+    validateString(relation.component, `${relationPath}.component`, issues);
+    validateString(relation.relationship, `${relationPath}.relationship`, issues);
+    validateString(relation.note, `${relationPath}.note`, issues);
+  });
+}
+function validateFragmentPreview(value, path, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateOptionalString(value.setupModule, `${path}.setupModule`, issues);
+  validateOptionalString(value.wrapperModule, `${path}.wrapperModule`, issues);
+  validateOptionalString(value.wrapperExport, `${path}.wrapperExport`, issues);
+  validateOptionalStringArray(value.css, `${path}.css`, issues);
+  validateOptionalStringArray(value.dynamicRegions, `${path}.dynamicRegions`, issues);
+  if (value.providers !== void 0 && !Array.isArray(value.providers)) {
+    issues.push(`${path}.providers must be an array`);
+  }
+  if (value.theme !== void 0 && value.theme !== "light" && value.theme !== "dark") {
+    issues.push(`${path}.theme must be light or dark`);
+  }
+}
+function validateFragmentMatrix(value, path, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  if (value.axes !== void 0) {
+    if (!isRecord(value.axes)) {
+      issues.push(`${path}.axes must be an object`);
+    } else {
+      for (const [axis, values] of sortedEntries(value.axes)) {
+        if (values !== "auto" && !isStringArray(values)) {
+          issues.push(`${path}.axes.${axis} must be auto or an array of strings`);
+        }
+      }
+    }
+  }
+  validateOptionalStringArray(value.forced, `${path}.forced`, issues);
+  validateOptionalRecord(value.worstCase, `${path}.worstCase`, issues);
+}
+function validateFragmentDesign(value, path, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateOptionalString(value.figmaNode, `${path}.figmaNode`, issues);
+}
+function validateFragmentProvenance(value, path, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateString(value.source, `${path}.source`, issues);
+  validateBoolean(value.verified, `${path}.verified`, issues);
+  validateOptionalString(value.frameworkSupport, `${path}.frameworkSupport`, issues);
+  validateOptionalString(value.sourceHash, `${path}.sourceHash`, issues);
+  validateOptionalString(value.extractedAt, `${path}.extractedAt`, issues);
+}
+function validateFragmentGenerated(value, path, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  const sources = ["storybook", "manual", "ai", "scan", "extracted", "merged", "migrated"];
+  if (typeof value.source !== "string" || !sources.includes(value.source)) {
+    issues.push(`${path}.source must be a supported provenance source`);
+  }
+  validateOptionalString(value.sourceFile, `${path}.sourceFile`, issues);
+  validateOptionalNumber(value.confidence, `${path}.confidence`, issues);
+  validateOptionalBoolean(value.verified, `${path}.verified`, issues);
+  validateOptionalString(value.timestamp, `${path}.timestamp`, issues);
+}
+function validateObservedUsages(value, path, issues) {
+  if (value === void 0) return;
+  if (!Array.isArray(value)) {
+    issues.push(`${path} must be an array`);
+    return;
+  }
+  value.forEach((usage, index) => {
+    const usagePath = `${path}.${index}`;
+    if (!isRecord(usage)) {
+      issues.push(`${usagePath} must be an object`);
+      return;
+    }
+    validateString(usage.file, `${usagePath}.file`, issues);
+    validateNumber(usage.line, `${usagePath}.line`, issues);
+    validateNumber(usage.column, `${usagePath}.column`, issues);
+    validateOptionalString(usage.parentElement, `${usagePath}.parentElement`, issues);
+    validateOptionalBoolean(usage.conditional, `${usagePath}.conditional`, issues);
+    if (!Array.isArray(usage.props)) {
+      issues.push(`${usagePath}.props must be an array`);
+      return;
+    }
+    usage.props.forEach((prop, propIndex) => {
+      const propPath = `${usagePath}.props.${propIndex}`;
+      if (!isRecord(prop)) {
+        issues.push(`${propPath} must be an object`);
+        return;
+      }
+      validateString(prop.name, `${propPath}.name`, issues);
+      if (typeof prop.kind !== "string" || !["static", "dynamic", "spread", "jsx", "boolean", "null"].includes(prop.kind)) {
+        issues.push(`${propPath}.kind must be a supported observation kind`);
+      }
+      if (prop.value !== void 0 && prop.value !== null && typeof prop.value !== "string" && typeof prop.value !== "number" && typeof prop.value !== "boolean") {
+        issues.push(`${propPath}.value must be a JSON scalar`);
+      }
+    });
+  });
+}
+function validatePerformanceData(value, path, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateNumber(value.bundleSize, `${path}.bundleSize`, issues);
+  validateNumber(value.rawSize, `${path}.rawSize`, issues);
+  validateString(value.complexity, `${path}.complexity`, issues);
+  validateNumber(value.budgetPercent, `${path}.budgetPercent`, issues);
+  validateBoolean(value.overBudget, `${path}.overBudget`, issues);
+  validateString(value.measuredAt, `${path}.measuredAt`, issues);
+  if (value.imports !== void 0) {
+    if (!Array.isArray(value.imports)) {
+      issues.push(`${path}.imports must be an array`);
+    } else {
+      value.imports.forEach((entry, index) => {
+        const entryPath = `${path}.imports.${index}`;
+        if (!isRecord(entry)) {
+          issues.push(`${entryPath} must be an object`);
+          return;
+        }
+        validateString(entry.path, `${entryPath}.path`, issues);
+        validateNumber(entry.bytes, `${entryPath}.bytes`, issues);
+        validateNumber(entry.percent, `${entryPath}.percent`, issues);
+      });
+    }
+  }
+}
+function validateCompiledBlockMap(value, path, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const [key, block] of sortedEntries(value)) {
+    const blockPath = `${path}.${key}`;
+    if (!isRecord(block)) {
+      issues.push(`${blockPath} must be an object`);
+      continue;
+    }
+    validateString(block.filePath, `${blockPath}.filePath`, issues);
+    validateString(block.name, `${blockPath}.name`, issues);
+    validateString(block.description, `${blockPath}.description`, issues);
+    validateString(block.category, `${blockPath}.category`, issues);
+    validateStringArray(block.components, `${blockPath}.components`, issues);
+    validateString(block.code, `${blockPath}.code`, issues);
+    validateOptionalStringArray(block.tags, `${blockPath}.tags`, issues);
+    if (typeof block.name === "string") {
+      if (names.has(block.name)) {
+        issues.push(
+          `${blockPath}.name duplicates an earlier block (${JSON.stringify(block.name)})`
+        );
+      }
+      names.add(block.name);
+    }
+  }
+}
+function validateCompiledTokens(value, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push("tokens must be an object");
+    return;
+  }
+  validateString(value.prefix, "tokens.prefix", issues);
+  validateNumber(value.total, "tokens.total", issues);
+  if (!isRecord(value.categories)) {
+    issues.push("tokens.categories must be an object");
+    return;
+  }
+  for (const [category, entries] of sortedEntries(value.categories)) {
+    const categoryPath = `tokens.categories.${category}`;
+    if (!Array.isArray(entries)) {
+      issues.push(`${categoryPath} must be an array`);
+      continue;
+    }
+    entries.forEach((entry, index) => {
+      const entryPath = `${categoryPath}.${index}`;
+      if (!isRecord(entry)) {
+        issues.push(`${entryPath} must be an object`);
+        return;
+      }
+      validateString(entry.name, `${entryPath}.name`, issues);
+      validateOptionalString(entry.value, `${entryPath}.value`, issues);
+      validateOptionalString(entry.description, `${entryPath}.description`, issues);
+    });
+  }
+}
+function validateSerializedGraph(value, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push("graph must be an object");
+    return;
+  }
+  if (!Array.isArray(value.nodes)) {
+    issues.push("graph.nodes must be an array");
+  } else {
+    const nodeNames = /* @__PURE__ */ new Set();
+    value.nodes.forEach((node, index) => {
+      const nodePath = `graph.nodes.${index}`;
+      if (!isRecord(node)) {
+        issues.push(`${nodePath} must be an object`);
+        return;
+      }
+      validateString(node.name, `${nodePath}.name`, issues);
+      validateString(node.category, `${nodePath}.category`, issues);
+      validateString(node.status, `${nodePath}.status`, issues);
+      validateOptionalStringArray(node.subComponents, `${nodePath}.subComponents`, issues);
+      if (typeof node.name === "string") {
+        if (nodeNames.has(node.name)) {
+          issues.push(
+            `${nodePath}.name duplicates an earlier graph node (${JSON.stringify(node.name)})`
+          );
+        }
+        nodeNames.add(node.name);
+      }
+    });
+  }
+  if (!Array.isArray(value.edges)) {
+    issues.push("graph.edges must be an array");
+  } else {
+    value.edges.forEach((edge, index) => {
+      const edgePath = `graph.edges.${index}`;
+      if (!isRecord(edge)) {
+        issues.push(`${edgePath} must be an object`);
+        return;
+      }
+      validateString(edge.s, `${edgePath}.s`, issues);
+      validateString(edge.t, `${edgePath}.t`, issues);
+      validateString(edge.ty, `${edgePath}.ty`, issues);
+      validateNumber(edge.w, `${edgePath}.w`, issues);
+      validateOptionalString(edge.no, `${edgePath}.no`, issues);
+      validateString(edge.p, `${edgePath}.p`, issues);
+    });
+  }
+  if (!isRecord(value.health)) {
+    issues.push("graph.health must be an object");
+    return;
+  }
+  validateStringArray(value.health.orphans, "graph.health.orphans", issues);
+  validateNumber(value.health.compositionCoverage, "graph.health.compositionCoverage", issues);
+  validateNumber(value.health.averageDegree, "graph.health.averageDegree", issues);
+  validateNumber(value.health.nodeCount, "graph.health.nodeCount", issues);
+  validateNumber(value.health.edgeCount, "graph.health.edgeCount", issues);
+  if (!Array.isArray(value.health.connectedComponents)) {
+    issues.push("graph.health.connectedComponents must be an array");
+  } else {
+    value.health.connectedComponents.forEach(
+      (component, index) => validateStringArray(component, `graph.health.connectedComponents.${index}`, issues)
+    );
+  }
+  if (!Array.isArray(value.health.hubs)) {
+    issues.push("graph.health.hubs must be an array");
+  } else {
+    value.health.hubs.forEach((hub, index) => {
+      const hubPath = `graph.health.hubs.${index}`;
+      if (!isRecord(hub)) {
+        issues.push(`${hubPath} must be an object`);
+        return;
+      }
+      validateString(hub.name, `${hubPath}.name`, issues);
+      validateNumber(hub.degree, `${hubPath}.degree`, issues);
+    });
+  }
+}
+function validatePerformanceSummary(value, issues) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push("performanceSummary must be an object");
+    return;
+  }
+  validateString(value.preset, "performanceSummary.preset", issues);
+  validateNumber(value.budget, "performanceSummary.budget", issues);
+  validateNumber(value.total, "performanceSummary.total", issues);
+  validateNumber(value.overBudget, "performanceSummary.overBudget", issues);
+  if (!isRecord(value.tiers)) {
+    issues.push("performanceSummary.tiers must be an object");
+  } else {
+    for (const [tier, count] of sortedEntries(value.tiers)) {
+      validateNumber(count, `performanceSummary.tiers.${tier}`, issues);
+    }
+  }
+}
+function validateString(value, path, issues) {
+  if (typeof value !== "string") issues.push(`${path} must be a string`);
+}
+function validateOptionalString(value, path, issues) {
+  if (value !== void 0) validateString(value, path, issues);
+}
+function validateNumber(value, path, issues) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    issues.push(`${path} must be a finite number`);
+  }
+}
+function validateOptionalNumber(value, path, issues) {
+  if (value !== void 0) validateNumber(value, path, issues);
+}
+function validateBoolean(value, path, issues) {
+  if (typeof value !== "boolean") issues.push(`${path} must be a boolean`);
+}
+function validateOptionalBoolean(value, path, issues) {
+  if (value !== void 0) validateBoolean(value, path, issues);
+}
+function validateStringArray(value, path, issues) {
+  if (!isStringArray(value)) issues.push(`${path} must be an array of strings`);
+}
+function validateOptionalStringArray(value, path, issues) {
+  if (value !== void 0) validateStringArray(value, path, issues);
+}
+function validateStringRecord(value, path, issues) {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object of strings`);
+    return;
+  }
+  for (const [key, entry] of sortedEntries(value)) {
+    validateString(entry, `${path}.${key}`, issues);
+  }
+}
+function validateOptionalRecord(value, path, issues) {
+  if (value !== void 0 && !isRecord(value)) issues.push(`${path} must be an object`);
+}
+function validateOptionalRecordArray(value, path, issues) {
+  if (value === void 0) return;
+  if (!Array.isArray(value) || value.some((entry) => !isRecord(entry))) {
+    issues.push(`${path} must be an array of objects`);
+  }
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function sortedEntries(value) {
+  return Object.entries(value).sort(([left], [right]) => compareStrings(left, right));
+}
+function compareStrings(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export {
+  CompiledFragmentsFileValidationError,
+  parseCompiledFragmentsFile
+};
+//# sourceMappingURL=chunk-RYFULE43.js.map