@usefragments/core 1.10.2 → 2.0.0

package/src/index.ts

@@ -4,7 +4,7 @@
  */
 
 // Brand and default constants
-export { BRAND, DEFAULTS } from "./constants.js";
+export { BRAND, DEFAULTS, FRAGMENT_V3_SCHEMA_URL } from "./constants.js";
 export type { Brand, Defaults } from "./constants.js";
 
 export {
@@ -167,14 +167,20 @@ export type {
   FragmentsConfig,
   SnippetPolicyConfig,
   RegistryOptions,
+  FragmentIndex,
+  FragmentRegistry,
+  RegistryComponentEntry,
+  RegistryPropEntry,
+  FragmentContextOptions,
   CompiledFragment,
+  CompiledFragmentDesign,
+  CompiledFragmentMatrix,
+  CompiledFragmentPreview,
   CompiledFragmentsFile,
   ObservedComponentUsage,
   ObservedUsageProp,
   BlockDefinition,
   CompiledBlock,
-  RecipeDefinition, // @deprecated - use BlockDefinition
-  CompiledRecipe, // @deprecated - use CompiledBlock
   // Contract and provenance types
   FragmentContract,
   FragmentGenerated,
@@ -186,6 +192,18 @@ export type {
   CompositionMetadata,
   FragmentProvenance,
   FragmentDefinitionV2,
+  // v3 types (arity-discriminated)
+  FragmentMetaV3,
+  FragmentStateV3,
+  FragmentDontExampleV3,
+  FragmentGuidanceV3,
+  FragmentMatrixV3,
+  FragmentPreviewV3,
+  FragmentDesignV3,
+  PropAnnotation,
+  FragmentAnnotationsV3,
+  FragmentDefinitionV3Body,
+  FragmentDefinitionV3,
   // Screenshot types
   ScreenshotConfig,
   ServiceConfig,
@@ -207,8 +225,6 @@ export type {
   FigmaInstanceMapping,
   FigmaChildrenMapping,
   FigmaTextContentMapping,
-  // Storybook filter configuration
-  StorybookFilterConfig,
   // Token configuration
   AppConfig,
   DesignSystemConfig,
@@ -284,12 +300,18 @@ export type {
 // Fragments Registry Protocol contracts
 export {
   REGISTRY_ARTIFACT_SCHEMA_VERSION,
+  REGISTRY_INDEX_SCHEMA_VERSION,
   REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION,
   REGISTRY_MANIFEST_SCHEMA_VERSION,
+  REGISTRY_POINTER_SCHEMA_VERSION,
+  REGISTRY_SHARD_SCHEMA_VERSION,
+  assembleRegistryArtifact,
   assertValidRegistryArtifact,
   buildRegistryArtifact,
   buildRegistryFile,
+  buildRegistryPointer,
   computeRegistryHash,
+  defaultRegistryShardPath,
   finalizeRegistryManifest,
   hashRegistryFileContent,
   registryArtifactDigest,
@@ -303,14 +325,21 @@ export {
   registryFileRoleSchema,
   registryFileSchema,
   registryFileSize,
+  registryIndexSchema,
   registryInstallProfileSchema,
   registryInstallReceiptComponentSchema,
   registryInstallReceiptFileSchema,
   registryInstallReceiptSchema,
   registryManifestCanonicalPreimage,
   registryManifestDraftSchema,
+  registryManifestFileMetadata,
+  registryManifestFilePaths,
   registryManifestSchema,
+  registryPointerSchema,
+  registryShardSchema,
+  registryShardsForPaths,
   registrySourceSchema,
+  shardRegistryArtifact,
 } from "./registry.js";
 export type {
   RegistryArtifact,
@@ -324,13 +353,17 @@ export type {
   RegistryFileContent,
   RegistryFileInput,
   RegistryFileRole,
+  RegistryIndex,
   RegistryInstallProfile,
   RegistryInstallReceipt,
   RegistryInstallReceiptComponent,
   RegistryInstallReceiptFile,
   RegistryManifest,
   RegistryManifestDraft,
+  RegistryPointer,
+  RegistryShard,
   RegistrySource,
+  ShardedRegistryArtifact,
 } from "./registry.js";
 
 export {
@@ -338,13 +371,21 @@ export {
   buildRegistryInstallPlan,
   buildRegistryInstallReceipt,
   collectRegistryInstallDependencies,
+  expandRegistryComponentClosure,
   normalizeRegistryRepoPath,
-  selectedRegistryComponentNames,
+  resolveRegistryComponentId,
+  resolveRegistryInstallSelection,
+  resolveRegistryInstallSources,
   sourceToRegistryTargetPath,
 } from "./registry-install-plan.js";
 export type {
   BuildRegistryInstallPlanInput,
   RegistryInstallPlan,
+  RegistryInstallSelection,
+  RegistryInstallSelectionInput,
+  RegistryInstallSourceFile,
+  RegistryInstallSources,
+  RegistryInstallSourcesInput,
   RegistryWritePlan,
 } from "./registry-install-plan.js";
 
@@ -427,10 +468,10 @@ export {
   figmaPropMappingSchema,
   // Contract and provenance schemas
   fragmentContractSchema,
+  fragmentSourceValues,
   fragmentGeneratedSchema,
   fragmentBanSchema,
   blockDefinitionSchema,
-  recipeDefinitionSchema, // @deprecated - use blockDefinitionSchema
   // AI metadata schema
   aiMetadataSchema,
   // v2 schemas
@@ -438,6 +479,18 @@ export {
   fragmentProvenanceSchema,
   fragmentDefinitionV2Schema,
   governedFragmentDefinitionSchema,
+  // v3 schemas
+  fragmentMetaV3Schema,
+  fragmentStateV3Schema,
+  fragmentDontExampleV3Schema,
+  fragmentGuidanceV3Schema,
+  fragmentMatrixV3Schema,
+  fragmentPreviewV3Schema,
+  fragmentDesignV3Schema,
+  propAnnotationSchema,
+  fragmentAnnotationsV3Schema,
+  fragmentDefinitionV3BodySchema,
+  fragmentDefinitionV3Schema,
 } from "./schema.js";
 
 // Main API
@@ -448,8 +501,6 @@ export {
   normalizeToV1,
   defineBlock,
   compileBlock,
-  defineRecipe,
-  compileRecipe,
 } from "./defineFragment.js";
 export type { InferProps } from "./defineFragment.js";
 
@@ -457,6 +508,7 @@ export type { InferProps } from "./defineFragment.js";
 export {
   componentGovernanceRecordSchema,
   componentGovernanceRecordsSchema,
+  parseComponentGovernancePolicyJson,
   canonicalBridgeV1Schema,
   g,
   globalGovernanceRecordSchema,
@@ -467,6 +519,8 @@ export {
   isPresetSourcedRule,
   markPresetSourcedRules,
   normalizeGovernanceConfig,
+  resolveComponentGovernance,
+  resolveGovernanceRecordsForIdentity,
   scaleGovernanceRecordSchema,
 } from "./governance.js";
 export type {
@@ -501,15 +555,6 @@ export {
 } from "./policy-exclude.js";
 export type { PolicyExclude, PolicyExcludeInput } from "./policy-exclude.js";
 
-// Storybook adapter filtering
-export {
-  checkStoryExclusion,
-  detectSubComponentPaths,
-  isForceIncluded,
-  isConfigExcluded,
-} from "./storyFilters.js";
-export type { ExclusionReason, ExclusionResult, CheckStoryExclusionOpts } from "./storyFilters.js";
-
 // Context generation for AI agents
 export { generateContext } from "./context.js";
 export type { ContextOptions, ContextResult } from "./context.js";
@@ -517,23 +562,6 @@ export type { ContextOptions, ContextResult } from "./context.js";
 // Figma property mapping DSL
 export { figma, isFigmaPropMapping, resolveFigmaMapping } from "./figma.js";
 
-// Fragment JSON types (for .fragment.json files)
-export type {
-  Fragment,
-  FragmentFigma,
-  FragmentUsage as FragmentJsonUsage,
-  FragmentDoNotItem,
-  FragmentPattern,
-  FragmentAccessibility,
-  FragmentRelated,
-  FragmentMeta as FragmentJsonMeta,
-  FragmentIndex,
-  FragmentRegistry,
-  RegistryComponentEntry,
-  RegistryPropEntry,
-  FragmentContextOptions,
-} from "./fragment-types.js";
-
 // Token parsing and token-domain helpers
 export {
   calculateDeltaE,
@@ -649,6 +677,12 @@ export {
   ruleA11yRequiredAccessibleName,
   ruleA11yStandard,
 } from "./rules/index.js";
+export {
+  capConfiguredSeverity,
+  configuredFindingSeverity,
+  readRuleConfig,
+  type RuleConfigView,
+} from "./rules/rule-config.js";
 export { indexComponentIdentityUsage, type ComponentIdentityUsage } from "./identity/usage.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
 export {
@@ -705,7 +739,11 @@ export type { RuleTier, PresetRuleState } from "./rules/index.js";
 // Contract-site health denominator: how many style-declaration sites the
 // token-vocabulary rule actually judged. Consumed by the CLI's per-scan
 // `contract-site-health:v1` metric next to the identity usage index.
-export { contractTokenReferenceCensus } from "./rules/index.js";
+export {
+  contractTokenReferenceCensus,
+  EMPTY_VOCABULARY_MESSAGE,
+  emptyVocabularyConfigFile,
+} from "./rules/index.js";
 export type { ContractTokenReferenceCensus } from "./rules/index.js";
 
 // Rule families — the ONE expansion of a broad `govern.rules` id (`tokens/hardcoded-values`)
@@ -826,24 +864,39 @@ export {
 } from "./facts/index.js";
 export type { SupersededImportPathPreference } from "./facts/index.js";
 export {
-  canonicalPreimage,
   AGENT_CONTEXT_RELATIVE_PATH,
+  artifactContentHash,
   CATALOG_FIXTURE_A_FCID,
   catalogFixtureA,
   catalogFixtureAContractPayload,
   catalogFixtureATokensDtcg,
+  canonicalPreimage,
+  CONTRACT_DISPLAY_ONLY_FIELDS,
   CONTRACT_DOMAINS,
+  CONTRACT_ENFORCEMENT_FIELDS,
   CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
+  ContractCatalogValidationError,
   contractComponentsFromFragments,
   contractHash,
   contractPolicyFromGovernanceConfig,
+  deriveArtifactId,
   diffContractDomains,
   formatStampHeader,
   formatStampPin,
   formatStampVersionHash,
+  FRAGMENTS_MANIFEST_FILENAME,
+  FRAGMENTS_MANIFEST_SCHEMA_VERSION,
+  FRAGMENTS_MANIFEST_TOKEN_RULE,
+  fragmentsManifestFcid,
+  fragmentsManifestGrammarSchema,
+  fragmentsManifestPatternSchema,
+  fragmentsManifestPrimitiveSchema,
+  fragmentsManifestSchema,
   parseContractStamp,
+  parseFragmentsManifest,
   projectContractPreimage,
+  projectEnforcementContract,
   serializeContractStamp,
   sha256Hex,
   verifiedContractPreimageFromPin,
@@ -866,6 +919,7 @@ export type {
   ContractCatalogInput,
   ContractComponentInput,
   ContractDomain,
+  ContractEnforcementField,
   ContractIdentityPin,
   ContractPolicyInput,
   ContractPreimage,
@@ -874,6 +928,10 @@ export type {
   ContractStampRecord,
   ContractTokenInput,
   ContractWaiverInput,
+  FragmentsManifest,
+  FragmentsManifestGrammar,
+  FragmentsManifestPattern,
+  FragmentsManifestPrimitive,
 } from "./contract/index.js";
 export {
   governanceConfigWithLocalCanonical,
@@ -920,6 +978,9 @@ export type {
   FactLocation,
   FactEvidence,
   CanonicalCandidateFact,
+  CanonicalFactConflictV1,
+  CanonicalFactConflictValueV1,
+  CanonicalFactIntegrityV1,
   CanonicalMappingFact,
   CanonicalReplacementFact,
   ComponentLevelFact,
@@ -978,8 +1039,140 @@ export type {
   SuppressionDirectiveFact,
   ComponentFactInput,
 } from "./facts/index.js";
+export {
+  CANONICAL_FACT_MAX_CONFLICTS_V1,
+  CANONICAL_FACT_MAX_PROVENANCE_PER_VALUE_V1,
+  CANONICAL_FACT_MAX_VALUES_PER_CONFLICT_V1,
+  canonicalFactConflictV1Schema,
+  canonicalFactConflictValueV1Schema,
+  canonicalFactIntegrityV1Schema,
+  normalizeCanonicalFactIntegrityV1,
+} from "./facts/index.js";
+
+// V1 authority and analysis contracts. These remain browser-safe and have no
+// Cloud, provider, engine, model, or Node-only dependency.
+export {
+  analysisPlanIdFromDigest,
+  analysisPlanIdSchema,
+  analysisPlanIdStringSchema,
+  digestHexSchema,
+  digestHexStringSchema,
+  evaluationReceiptIdFromDigest,
+  mintEvaluationReceiptId,
+  evaluationReceiptIdSchema,
+  evaluationReceiptIdStringSchema,
+  parseAnalysisPlanId,
+  parseDigestHex,
+  parseEvaluationReceiptId,
+} from "./domain-ids.js";
+export type { AnalysisPlanId, DigestHex, EvaluationReceiptId } from "./domain-ids.js";
+export {
+  PROVIDER_ID_MAX_BYTES_V1,
+  REPOSITORY_BINDING_ID_MAX_BYTES_V1,
+  normalizeRepositoryBindingKeyV1,
+  repositoryBindingDigestV1,
+  repositoryBindingKeyV1Schema,
+} from "./repository-binding.js";
+export type { RepositoryBindingKeyV1, RepositoryBindingKeyV1Input } from "./repository-binding.js";
+export {
+  ANALYSIS_LIMIT_CEILINGS_V1,
+  ANALYSIS_PLAN_MAX_CAPABILITIES_V1,
+  ANALYSIS_PLAN_MAX_DIALECTS_PER_REGION_V1,
+  ANALYSIS_PLAN_MAX_REGIONS_V1,
+  CoverageValidationErrorV1,
+  analysisLimitsV1Schema,
+  analysisObligationsDigestV1,
+  analysisPlanDigestV1,
+  analysisPlanInputV1Schema,
+  analysisPlanV1Schema,
+  analysisRegionV1Schema,
+  buildAnalysisPlanV1,
+  coverageArtifactDigestV1,
+  coverageRegionV1Schema,
+  coverageStateV1Schema,
+  coverageSummaryV1Schema,
+  deriveCoverageSummaryV1,
+  normalizeAnalysisPlanInputV1,
+  parseAnalysisPlanV1,
+} from "./analysis-plan/index.js";
+export type {
+  AnalysisLimitsV1,
+  AnalysisPlanInputV1,
+  AnalysisPlanV1,
+  AnalysisRegionV1,
+  CoverageRegionV1,
+  CoverageStateV1,
+  CoverageSummaryV1,
+} from "./analysis-plan/index.js";
 
 // Topology — map file paths to product areas (area-scoped governance).
 // Also available at the `@usefragments/core/topology` subpath.
 export { resolveArea } from "./topology/index.js";
 export type { Area, AreaCriticality, AreaMatch, Topology } from "./topology/index.js";
+
+// Evaluation Module — the pure governance kernel (architecture spec §§1–2):
+// deterministic verdicts with kernel-owned FCID verification, four-state
+// finding classification, and three-state trust facts. Shipped in shadow mode
+// alongside the legacy CLI/Cloud verdict machines.
+export {
+  EVALUATION_MAX_FINDINGS_V2,
+  EVALUATION_MAX_MAP_ENTRIES_V2,
+  EVALUATION_MAX_POLICY_RULES_V2,
+  EVALUATION_MAX_REASON_CODES_V2,
+  EVALUATION_MAX_WAIVERS_V2,
+  EVALUATION_MAX_WAIVER_MATCHES_V2,
+  EVALUATION_RECEIPT_STRING_MAX_BYTES_V1,
+  EVALUATOR_VERSION,
+  EVALUATOR_VERSION_V2,
+  effectiveEvaluationWaiverV2Schema,
+  evaluate,
+  evaluationInputDigestV2,
+  evaluationResultDigestV2,
+  evaluationInputV2Schema,
+  evaluationReceiptDigestV1,
+  evaluationReceiptMintInputV1Schema,
+  evaluationReceiptV1Schema,
+  evaluationResultV2Schema,
+  parseEvaluationReceiptV1,
+  providerProofDigestV1,
+  providerProofV1Schema,
+} from "./evaluation/index.js";
+export type {
+  EffectivePolicy,
+  EffectiveRulePolicy,
+  EvaluatedFinding,
+  EvaluationBaseline,
+  EvaluationContractInput,
+  EvaluationEvidence,
+  EvaluationFindingInput,
+  EvaluationFindingState,
+  EvaluationInput,
+  EvaluationIntegrityInput,
+  EvaluationMappingTrust,
+  EvaluationReason,
+  EvaluationResult,
+  EvaluationScope,
+  EvaluationSourceTrust,
+  EvaluationTrust,
+  EvaluationVerdict,
+  EvaluationWaiver,
+  EffectiveEvaluationWaiverV2,
+  EvaluationAuthorityV1,
+  EvaluationEvidenceTrustV1,
+  EvaluationInputV2,
+  EvaluationIntegrityInputV2,
+  EvaluationReasonV2,
+  EvaluationReceiptMintInputV1,
+  EvaluationReceiptSemanticV1,
+  EvaluationReceiptV1,
+  EvaluationResultV2,
+  FindingV2,
+  ProviderProofSemanticV1,
+  ProviderProofV1,
+} from "./evaluation/index.js";
+
+export {
+  APPROVED_CONTRACT_TOKEN_MAX_NAMES,
+  APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH,
+  isApprovedContractTokenNames,
+} from "./approved-contract-tokens.js";

package/src/preview/validation.test.ts

@@ -128,6 +128,68 @@ describe("@usefragments/core/preview artifact validation", () => {
     ).toThrow(/unsupported source "storybook"/);
   });
 
+  it("requires component map keys to match unique normalized component keys", () => {
+    const mismatched = {
+      ...manifest,
+      components: {
+        RenamedButton: {
+          ...manifest.components.Button,
+          componentKey: "Button",
+        },
+      },
+    };
+    const duplicated = {
+      ...manifest,
+      components: {
+        Button: manifest.components.Button,
+        " Button ": {
+          ...manifest.components.Button,
+          componentKey: " Button ",
+        },
+      },
+    };
+
+    expect(() =>
+      definePreviewArtifactManifest(mismatched as unknown as PreviewArtifactManifest)
+    ).toThrow(/componentKey must match its components map key/);
+    expect(() =>
+      definePreviewArtifactManifest(duplicated as unknown as PreviewArtifactManifest)
+    ).toThrow(/duplicate normalized componentKey/);
+  });
+
+  it("requires supported previewability values and unique non-empty variant ids", () => {
+    const invalid = {
+      ...manifest,
+      components: {
+        Button: {
+          ...manifest.components.Button,
+          previewability: "unknown",
+          variants: [
+            ...manifest.components.Button.variants,
+            {
+              ...manifest.components.Button.variants[0],
+              id: " default ",
+            },
+            {
+              ...manifest.components.Button.variants[0],
+              id: " ",
+            },
+          ],
+        },
+      },
+    };
+
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/previewability must be one of/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/variants.1.id must be unique within the component/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/variants.2.id must be a non-empty string/);
+  });
+
   it("rejects malformed design comparison evidence", () => {
     const invalid = {
       ...manifest,

package/src/preview/validation.ts

@@ -1,4 +1,17 @@
-import type { PreviewArtifactManifest } from "./types";
+import type { Previewability, PreviewArtifactManifest } from "./types";
+
+const PREVIEWABILITY_VALUES = new Set<Previewability>([
+  "ready",
+  "building",
+  "needs-preview-provider",
+  "missing-dependency",
+  "missing-asset",
+  "server-only",
+  "unsupported-framework",
+  "runtime-error",
+  "build-error",
+  "docs-only",
+]);
 
 export interface PreviewArtifactValidationResult {
   ok: boolean;
@@ -96,12 +109,25 @@ function validateComponents(value: unknown, issues: string[]) {
     issues.push("components must be an object");
     return;
   }
+  const normalizedComponentKeys = new Set<string>();
   for (const [key, component] of Object.entries(value)) {
     if (!isRecord(component)) {
       issues.push(`components.${key} must be an object`);
       continue;
     }
-    requireString(component, "componentKey", issues, `components.${key}`);
+    const componentKey = component.componentKey;
+    if (typeof componentKey !== "string" || !componentKey.trim()) {
+      issues.push(`components.${key}.componentKey must be a non-empty string`);
+    } else {
+      if (key !== componentKey) {
+        issues.push(`components.${key}.componentKey must match its components map key`);
+      }
+      const normalizedComponentKey = componentKey.trim();
+      if (normalizedComponentKeys.has(normalizedComponentKey)) {
+        issues.push(`components contains duplicate normalized componentKey ${componentKey}`);
+      }
+      normalizedComponentKeys.add(normalizedComponentKey);
+    }
     requireString(component, "publicRef", issues, `components.${key}`);
     requireString(component, "displayName", issues, `components.${key}`);
     requireString(component, "exportName", issues, `components.${key}`);
@@ -112,17 +138,33 @@ function validateComponents(value: unknown, issues: string[]) {
         `components.${key}.definitionSource must be one of typescript, fragment, manual, synthesized`
       );
     }
+    if (!isPreviewability(component.previewability)) {
+      issues.push(
+        `components.${key}.previewability must be one of ${[...PREVIEWABILITY_VALUES].join(", ")}`
+      );
+    }
     if (!isRecord(component.props)) {
       issues.push(`components.${key}.props must be an object`);
     }
     if (!Array.isArray(component.variants)) {
       issues.push(`components.${key}.variants must be an array`);
     } else {
+      const normalizedVariantIds = new Set<string>();
       component.variants.forEach((variant, index) => {
         if (!isRecord(variant)) {
           issues.push(`components.${key}.variants.${index} must be an object`);
           return;
         }
+        const variantPath = `components.${key}.variants.${index}`;
+        if (typeof variant.id !== "string" || !variant.id.trim()) {
+          issues.push(`${variantPath}.id must be a non-empty string`);
+        } else {
+          const normalizedVariantId = variant.id.trim();
+          if (normalizedVariantIds.has(normalizedVariantId)) {
+            issues.push(`${variantPath}.id must be unique within the component`);
+          }
+          normalizedVariantIds.add(normalizedVariantId);
+        }
         validateDesignReference(
           variant.design,
           issues,
@@ -297,6 +339,10 @@ function isPreviewDefinitionSource(value: unknown): boolean {
   );
 }
 
+function isPreviewability(value: unknown): value is Previewability {
+  return typeof value === "string" && PREVIEWABILITY_VALUES.has(value as Previewability);
+}
+
 function isFiniteNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }