@usefragments/core 1.0.0 → 1.2.0

package/dist/index.js

@@ -1,9 +1,9 @@
-import {
-  ComponentGraphEngine
-} from "./chunk-SH4KPIYH.js";
 import {
   generateContext
 } from "./chunk-X34IA4LR.js";
+import {
+  ComponentGraphEngine
+} from "./chunk-SH4KPIYH.js";
 import {
   resolveArea
 } from "./chunk-3LLRNCPX.js";
@@ -109,9 +109,13 @@ import {
   ownedImportsEqual,
   resolveComponentGovernance,
   scaleGovernanceRecordSchema
-} from "./chunk-243QYRUF.js";
+} from "./chunk-DBVTSUMT.js";
 import {
+  AGENT_FORMAT_SCHEMA_VERSION,
+  agentErrorEnvelopeSchema,
   agentFormatSchema,
+  agentIntegritySchema,
+  agentOutputSchema,
   factEvidenceSchema,
   factLocationSchema,
   findingFixSchema,
@@ -130,7 +134,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "./chunk-R3X7UBHU.js";
+} from "./chunk-BQQTMGLA.js";
 import {
   OWNED_PACKAGE_IDENTITY_EPOCH,
   OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
@@ -382,7 +386,8 @@ async function proveCompliant(input, callbacks, options = {}) {
 
 // src/agent-format.ts
 function buildAgentFormat(input) {
-  const score = scoreFindings(input.findings);
+  const integrityFailed = !input.integrity.healthy || input.integrity.inert;
+  const score = integrityFailed ? 0 : scoreFindings(input.findings);
   const visibleFindings = uniqueFindings(input.findings).slice(0, input.maxFindings ?? 50);
   const agentFindings = visibleFindings.map((finding) => ({
     code: finding.code,
@@ -398,10 +403,11 @@ function buildAgentFormat(input) {
   }));
   const hasErrors = input.findings.some((finding) => severityLevel(finding.severity) === "error");
   return {
-    schemaVersion: "typestyle.agent.v1",
-    passed: (input.passed ?? true) && !hasErrors,
+    schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
+    passed: !integrityFailed && (input.passed ?? true) && !hasErrors,
     score,
-    summary: agentSummary(input.findings.length, input.filesScanned, score),
+    summary: integrityFailed ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}` : agentSummary(input.findings.length, input.filesScanned, score),
+    integrity: input.integrity,
     fix_first: agentFindings.filter((finding) => finding.plan.confidence >= 0.8),
     remaining: agentFindings.filter((finding) => finding.plan.confidence < 0.8),
     suppression_template: {
@@ -4994,7 +5000,8 @@ function ruleComponentsPreferLibrary(ix) {
     if (node.element.includes(".")) continue;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
-    const imported = importsByFileAndLocal.get(node.file)?.get(node.element);
+    const importsForFile = importsByFileAndLocal.get(node.file);
+    const imported = importsForFile?.get(node.element);
     const nodeInputType = node.element === "input" ? readStaticStringProp(props, "type") : void 0;
     const mapped = findMapping(node, nodeInputType, mappings);
     if (mapped && imported && isMappedCanonicalImport(imported, mapped)) continue;
@@ -5005,9 +5012,11 @@ function ruleComponentsPreferLibrary(ix) {
       const suggestedComponent2 = mapped.name;
       const suggestedImport2 = importPath ?? "the canonical library";
       const propMapping = mapped.propMapping ?? [];
+      const propCompatibility = assessMappedPropCompatibility(props, propMapping);
       const roleMatch = isRoleMatch(node, mapped);
       const precisionTier2 = roleMatch ? "role-reimpl" : "exact-html";
       if (imported && importPath && !ownedImportsEqual(imported.source, importPath) && node.element === suggestedComponent2) {
+        if (!isLocalExactComponentImportRedirectCandidate(imported, suggestedComponent2)) continue;
         const key = `${imported.file}\0${imported.local}\0${imported.source}\0${importPath}`;
         if (seenImportFixes.has(key)) continue;
         seenImportFixes.add(key);
@@ -5015,8 +5024,8 @@ function ruleComponentsPreferLibrary(ix) {
           makeFinding({
             ruleId: RULE_ID2,
             ruleVersion: RULE_VERSION2,
-            severity: policy.severity ?? "warn",
-            message: `<${node.element}> should import from ${importPath}.`,
+            severity: capAdvisorySeverity(policy.severity),
+            message: `<${node.element}> may need to import from ${importPath}; verify that the local component contract is compatible first.`,
             location: imported.location,
             evidence: ix.evidence([node.id, imported.id, policy.id]),
             fingerprintIdentity: {
@@ -5030,14 +5039,16 @@ function ruleComponentsPreferLibrary(ix) {
               title: `Replace import path with "${importPath}"`,
               from: imported.source,
               to: importPath,
-              deterministic: true
+              deterministic: false
             },
             attributes: {
               rawValue: imported.source,
               suggestedComponent: suggestedComponent2,
               suggestedImport: importPath,
               canonical: mapped.canonical,
-              confidence: mapped.confidence
+              confidence: mapped.confidence,
+              advisory: true,
+              contractProof: "missing"
             }
           })
         );
@@ -5067,7 +5078,11 @@ function ruleComponentsPreferLibrary(ix) {
               title: `Replace <${node.element}> with <${suggestedComponent2}>`,
               from: node.element,
               to: suggestedComponent2,
-              deterministic: true
+              // The fact IR cannot prove that it observed every JSX
+              // attribute shape (notably dynamic inline styles). The
+              // conform AST preflight may promote this guided fix only
+              // after it proves the complete prop surface directly.
+              deterministic: false
             }
           } : {},
           attributes: {
@@ -5077,8 +5092,12 @@ function ruleComponentsPreferLibrary(ix) {
             canonical: mapped.canonical,
             confidence: mapped.confidence,
             propMapping,
+            propCompatibility: propCompatibility.complete ? "observed-complete" : "incomplete",
+            ...mapped.conformStatus === "confirmed" ? { canonicalMappingConfirmed: true } : {},
+            ...propCompatibility.unprovenProps.length > 0 ? { unprovenProps: propCompatibility.unprovenProps } : {},
             precisionTier: precisionTier2,
-            ...roleMatch ? { matchedRole: node.role } : {}
+            ...roleMatch ? { matchedRole: node.role } : {},
+            ...isRawHtmlAdvisoryTier(precisionTier2) ? { advisory: true } : {}
           }
         })
       );
@@ -5121,6 +5140,47 @@ function ruleComponentsPreferLibrary(ix) {
     const suggestion = findSuggestionSource(suggestedComponent, sources);
     if (!suggestion) continue;
     if (!builtIn && !shouldSuggest(node, imported)) continue;
+    if (node.element === suggestedComponent) {
+      const importPath = canonicalImportPath(suggestion);
+      if (!imported || !importPath || !isLocalExactComponentImportRedirectCandidate(imported, suggestedComponent)) {
+        continue;
+      }
+      const key = `${imported.file}\0${imported.local}\0${imported.source}\0${importPath}`;
+      if (seenImportFixes.has(key)) continue;
+      seenImportFixes.add(key);
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID2,
+          ruleVersion: RULE_VERSION2,
+          severity: capAdvisorySeverity(policy.severity),
+          message: `<${node.element}> may need to import from ${importPath}; verify that the local component contract is compatible first.`,
+          location: imported.location,
+          evidence: ix.evidence([node.id, imported.id, policy.id]),
+          fingerprintIdentity: {
+            file: imported.file,
+            local: imported.local,
+            from: imported.source,
+            to: importPath
+          },
+          fix: {
+            kind: "replaceImport",
+            title: `Replace import path with "${importPath}"`,
+            from: imported.source,
+            to: importPath,
+            deterministic: false
+          },
+          attributes: {
+            rawValue: imported.source,
+            suggestedComponent,
+            suggestedImport: importPath,
+            suggestedImportSourceKind: suggestion.kind,
+            advisory: true,
+            contractProof: "missing"
+          }
+        })
+      );
+      continue;
+    }
     if (suggestion.kind === "directory") {
       if (node.element === suggestedComponent) continue;
       if (!builtIn) continue;
@@ -5163,7 +5223,10 @@ function ruleComponentsPreferLibrary(ix) {
             title: `Replace ${rawElement} with <${suggestedComponent}>`,
             from: node.element,
             to: suggestedComponent,
-            deterministic: true
+            // A canonical source proves that the target exists, not that
+            // this native element's complete prop contract is compatible.
+            // Only explicit canonical mappings carry that proof.
+            deterministic: false
           }
         } : {},
         attributes: {
@@ -5172,6 +5235,7 @@ function ruleComponentsPreferLibrary(ix) {
           suggestedImport,
           suggestedImportSourceKind: suggestion.kind,
           precisionTier,
+          propCompatibility: "unknown",
           ...builtIn?.matchedRole ? { matchedRole: builtIn.matchedRole } : {},
           ...builtIn?.inputType ? { matchedInputType: builtIn.inputType } : {},
           ...isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}
@@ -5288,6 +5352,39 @@ function shouldSuggest(node, imported) {
   if (!/^[A-Z]/.test(node.element)) return false;
   return imported !== void 0;
 }
+function assessMappedPropCompatibility(props, mappings) {
+  const byRawProp = new Map(mappings.map((mapping) => [mapping.rawProp, mapping]));
+  const unprovenProps = props.flatMap((prop) => {
+    if (prop.resolution === "spread") return [prop.prop];
+    const mapping = byRawProp.get(prop.prop);
+    if (!mapping || !mappingCanPreserveProp(mapping, prop)) return [prop.prop];
+    return [];
+  });
+  return { complete: unprovenProps.length === 0, unprovenProps };
+}
+function mappingCanPreserveProp(mapping, prop) {
+  const renames = mapping.rawProp !== mapping.canonicalProp;
+  const valueMap = mapping.valueMap;
+  const translatesValue = valueMap !== void 0 && Object.keys(valueMap).length > 0;
+  if (renames && (!isIdentifier(mapping.rawProp) || !isIdentifier(mapping.canonicalProp))) {
+    return false;
+  }
+  if (!translatesValue) return true;
+  if (!isIdentifier(mapping.rawProp)) return false;
+  return prop.resolution === "static" && typeof prop.value === "string" && Object.prototype.hasOwnProperty.call(valueMap, prop.value);
+}
+function isLocalExactComponentImportRedirectCandidate(usage, componentName) {
+  return isUnaliasedNamedImport(usage, componentName) && isProjectLocalImportSource(usage.source);
+}
+function isUnaliasedNamedImport(usage, componentName) {
+  return isSimpleComponentBinding(usage, componentName) && usage.imported === componentName;
+}
+function isSimpleComponentBinding(usage, componentName) {
+  return usage.namespace !== true && usage.local === componentName;
+}
+function isProjectLocalImportSource(source) {
+  return source.startsWith(".") || source.startsWith("/") || source.startsWith("@/") || source.startsWith("~/");
+}
 function sameHtmlTag(htmlEquivalent, element) {
   return htmlEquivalent !== void 0 && htmlEquivalent.toLowerCase() === element.toLowerCase();
 }
@@ -5320,6 +5417,7 @@ function isCanonicalMappingOption(value) {
   if (record.htmlType !== void 0 && typeof record.htmlType !== "string") return false;
   if (record.importPath !== void 0 && typeof record.importPath !== "string") return false;
   if (record.confidence !== void 0 && typeof record.confidence !== "number") return false;
+  if (record.conformStatus !== void 0 && record.conformStatus !== "confirmed") return false;
   if (record.declaredHtmlEquivalent !== void 0 && typeof record.declaredHtmlEquivalent !== "boolean") {
     return false;
   }
@@ -5422,6 +5520,11 @@ function sourceLabel(source) {
   if (source.kind === "registry") return source.importPath ?? source.installPath;
   return source.path;
 }
+function canonicalImportPath(source) {
+  if (source.kind === "npm") return source.specifier;
+  if (source.kind === "registry") return source.importPath;
+  return void 0;
+}
 function isCanonicalSourceImplementationFile(file, sources) {
   const normalizedFile = normalizePath(file);
   return sources.some((source) => {
@@ -7674,7 +7777,11 @@ function isDenyEligible(finding, failOnWarnings) {
   if (!BLOCKING_RULE_ALLOWLIST.has(finding.ruleId)) return false;
   if (finding.attributes?.advisory === true) return false;
   if (!gatesCi(finding, failOnWarnings)) return false;
-  if (finding.fix?.deterministic === false) return false;
+  if (finding.fix?.deterministic === false) {
+    if (finding.ruleId !== "components/prefer-library" || finding.attributes?.propCompatibility !== "observed-complete") {
+      return false;
+    }
+  }
   return true;
 }
 
@@ -7682,7 +7789,7 @@ function isDenyEligible(finding, failOnWarnings) {
 var RULE_TIER = {
   // ---- Tier A — contract vocabulary -------------------------------------
   "components/prefer-library": "contract",
-  // canonical-component bypass (FUI1001/1004)
+  // canonical-component bypass (FUI1004)
   "tokens/css-vars-must-be-defined": "contract",
   // token drift (FUI2015)
   // ---- Tier B — generic hygiene -----------------------------------------
@@ -7947,6 +8054,7 @@ function evaluateGovernanceIntegrity(input) {
       componentsFamily.remediation = "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
     } else {
       componentsFamily.reason = "components/prefer-library not enabled";
+      componentsFamily.remediation = "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
     }
   }
   const cssVarsActive = input.cssVarsActive ?? policyDeclaresCssVars(input.policy);
@@ -8035,6 +8143,29 @@ function evaluateGovernanceIntegrity(input) {
 // src/contract/preimage.ts
 var CONTRACT_DOMAINS = ["components", "tokens", "canonicalMap", "policy"];
 var CONTRACT_PREIMAGE_SCHEMA = "fcid-preimage:v1";
+var CONTRACT_PREIMAGE_CAPABILITY_HEADER = "X-Fragments-Contract-Preimage";
+var SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/u;
+function verifiedContractPreimageFromPin(pin) {
+  if (pin.preimageSchema !== CONTRACT_PREIMAGE_SCHEMA || !SHA256_HEX_PATTERN.test(pin.contractHash) || !pin.domainHashes || typeof pin.domainHashes !== "object") {
+    return null;
+  }
+  const keys = Object.keys(pin.domainHashes).sort();
+  const expectedKeys = [...CONTRACT_DOMAINS].sort();
+  if (keys.length !== expectedKeys.length || keys.some((key, index) => key !== expectedKeys[index])) {
+    return null;
+  }
+  const domains = Object.fromEntries(
+    CONTRACT_DOMAINS.map((domain) => [domain, pin.domainHashes?.[domain]])
+  );
+  if (CONTRACT_DOMAINS.some((domain) => !SHA256_HEX_PATTERN.test(domains[domain] ?? ""))) {
+    return null;
+  }
+  const preimage = {
+    schema: CONTRACT_PREIMAGE_SCHEMA,
+    domains
+  };
+  return contractHash(preimage) === pin.contractHash ? preimage : null;
+}
 function sortCanonical(items) {
   return items.map((item) => ({ item, key: canonicalPreimage(item) })).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0).map(({ item }) => item);
 }
@@ -8358,11 +8489,13 @@ function readPreferLibraryRule(config) {
 }
 export {
   AGENT_CONTEXT_RELATIVE_PATH,
+  AGENT_FORMAT_SCHEMA_VERSION,
   BLOCKING_RULE_ALLOWLIST,
   BRAND,
   CATALOG_FIXTURE_A_FCID,
   CODES,
   CONTRACT_DOMAINS,
+  CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
   DEFAULTS,
   DEFAULT_ENHANCED_STYLE_PROPERTIES,
@@ -8388,7 +8521,10 @@ export {
   SEVERITIES,
   SEVERITY_RANK,
   SEVERITY_WEIGHTS,
+  agentErrorEnvelopeSchema,
   agentFormatSchema,
+  agentIntegritySchema,
+  agentOutputSchema,
   aiMetadataSchema,
   analyzeComposition,
   asComponentId,
@@ -8705,6 +8841,7 @@ export {
   topologyBase,
   usePreviewVariantRuntime,
   validatorResultSchema,
+  verifiedContractPreimageFromPin,
   violationSchema,
   vocabularyRank
 };