@usefragments/core 1.7.1 → 1.9.0

package/dist/index.js

@@ -1,3 +1,7 @@
+import {
+  CompiledFragmentsFileValidationError,
+  parseCompiledFragmentsFile
+} from "./chunk-RANPUC6C.js";
 import {
   generateContext
 } from "./chunk-X34IA4LR.js";
@@ -7,6 +11,11 @@ import {
 import {
   resolveArea
 } from "./chunk-3LLRNCPX.js";
+import {
+  GOVERNANCE_TELEMETRY_FIELDS,
+  GOVERNANCE_TELEMETRY_SOURCE_DISCLOSURE,
+  GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS
+} from "./chunk-MZ4SW3TP.js";
 import {
   REGISTRY_ARTIFACT_SCHEMA_VERSION,
   REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION,
@@ -41,11 +50,16 @@ import {
   sha256Hex
 } from "./chunk-YF65VYRY.js";
 import {
+  AGENT_FORMAT_SCHEMA_VERSION,
   CODES,
   EXPLAIN_URL_BASE,
   FactIndex,
   RULE_FAMILY_IDS,
   RULE_FAMILY_MEMBERS,
+  agentErrorEnvelopeSchema,
+  agentFormatSchema,
+  agentIntegritySchema,
+  agentOutputSchema,
   asComponentId,
   bridgeSourceViolation,
   bridgeSourceViolations,
@@ -61,13 +75,25 @@ import {
   describePolicyExclude,
   excludeGlobToRegExp,
   explainUrlForCode,
+  factEvidenceSchema,
   factId,
+  factLocationSchema,
+  findingFixSchema,
+  findingReplaceClassTokenFixSchema,
+  findingReplaceComponentFixSchema,
+  findingReplaceImportFixSchema,
+  findingReplacePropValueFixSchema,
+  findingReplaceStyleValueFixSchema,
+  findingSchema,
+  fixSchema,
   g,
   globalGovernanceRecordSchema,
   globalJsxGovernanceRecordSchema,
   globalStyleGovernanceRecordSchema,
   governanceConfigSchema,
   governanceSeveritySchema,
+  governanceVerdictMetadataSchema,
+  governanceVerdictSchema,
   hash64Hex,
   isPresetSourcedRule,
   isRuleFamilyId,
@@ -116,8 +142,11 @@ import {
   matchPolicyExclude,
   matchesGlob,
   normalizeExcludePath,
+  normalizeFinding,
   normalizeGovernanceConfig,
   normalizePolicyExcludes,
+  normalizeSeverity,
+  normalizeViolation,
   ownedComponentIdsEqual,
   ownedImportMatchesRoot,
   ownedImportsEqual,
@@ -126,33 +155,11 @@ import {
   projectSupersededImportPathPreferences,
   resolveComponentGovernance,
   ruleFamilyMembers,
-  scaleGovernanceRecordSchema
-} from "./chunk-WNMWKUYG.js";
-import {
-  AGENT_FORMAT_SCHEMA_VERSION,
-  agentErrorEnvelopeSchema,
-  agentFormatSchema,
-  agentIntegritySchema,
-  agentOutputSchema,
-  factEvidenceSchema,
-  factLocationSchema,
-  findingFixSchema,
-  findingReplaceClassTokenFixSchema,
-  findingReplaceComponentFixSchema,
-  findingReplaceImportFixSchema,
-  findingReplacePropValueFixSchema,
-  findingReplaceStyleValueFixSchema,
-  findingSchema,
-  fixSchema,
-  governanceVerdictMetadataSchema,
-  governanceVerdictSchema,
-  normalizeFinding,
-  normalizeSeverity,
-  normalizeViolation,
+  scaleGovernanceRecordSchema,
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "./chunk-ZHS52OT4.js";
+} from "./chunk-DGHZQTLH.js";
 import {
   OWNED_PACKAGE_IDENTITY_EPOCH,
   OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
@@ -182,10 +189,6 @@ import {
   severitySchema,
   sortBySeverity
 } from "./chunk-V4VQB57N.js";
-import {
-  CompiledFragmentsFileValidationError,
-  parseCompiledFragmentsFile
-} from "./chunk-RANPUC6C.js";
 
 // src/constants.ts
 var BRAND = {
@@ -4679,13 +4682,21 @@ function isAriaHidden(props) {
 }
 
 // src/rules/finding.ts
+var POSITION_IDENTITY_KEYS = ["line", "column", "endLine", "endColumn", "offset", "location"];
 function makeFinding(input) {
   if (input.evidence.length === 0) {
     throw new Error(`makeFinding(${input.ruleId}): findings must carry at least one evidence fact`);
   }
+  const positionKeys = POSITION_IDENTITY_KEYS.filter((key) => key in input.fingerprintIdentity);
+  if (positionKeys.length > 0) {
+    throw new Error(
+      `makeFinding(${input.ruleId}): fingerprintIdentity must not contain position keys (${positionKeys.join(", ")}) \u2014 fingerprints hash what's wrong, never where it sits. Use a source-order occurrence index for repeats of the same identity.`
+    );
+  }
   const fingerprint = hash64Hex(
     canonicalJson({ ruleId: input.ruleId, ...input.fingerprintIdentity })
   );
+  const previousFingerprint = input.previousFingerprintIdentity ? hash64Hex(canonicalJson({ ruleId: input.ruleId, ...input.previousFingerprintIdentity })) : void 0;
   const code = byRuleId.get(input.ruleId);
   return normalizeFinding({
     ruleId: input.ruleId,
@@ -4695,6 +4706,7 @@ function makeFinding(input) {
     helpUrl: code?.explainUrl,
     message: input.message,
     fingerprint,
+    ...previousFingerprint !== void 0 ? { previousFingerprint } : {},
     location: input.location,
     evidence: input.evidence,
     evidenceGrade: input.evidenceGrade ?? "source_backed",
@@ -6743,6 +6755,7 @@ function ruleJsxPreferredImportPath(ix) {
   if (policies.length === 0) return [];
   const findings = [];
   const seen = /* @__PURE__ */ new Set();
+  const occurrences = /* @__PURE__ */ new Map();
   for (const usage of ix.byKind("usage_import")) {
     const bridgeGoverned = policies.some((policy) => bridgeGovernsUnderlyingImport(policy, usage));
     const matches = policies.filter((policy) => {
@@ -6763,6 +6776,9 @@ function ruleJsxPreferredImportPath(ix) {
       const key = `${policy.id}\0${usage.file}\0${usage.source}\0${usage.location.line}\0${usage.location.column}\0${importedIdentity}`;
       if (seen.has(key)) continue;
       seen.add(key);
+      const identityKey = `${usage.file}\0${usage.source}\0${policy.to}\0${importedIdentity}`;
+      const occurrence = occurrences.get(identityKey) ?? 0;
+      occurrences.set(identityKey, occurrence + 1);
       findings.push(
         makeFinding({
           ruleId: RULE_ID8,
@@ -6772,6 +6788,15 @@ function ruleJsxPreferredImportPath(ix) {
           location: usage.location,
           evidence: ix.evidence([usage.id, policy.id]),
           fingerprintIdentity: {
+            file: usage.file,
+            from: usage.source,
+            to: policy.to,
+            imported: policy.imported,
+            occurrence
+          },
+          // Grace window (baseline v1 → v2): the pre-migration hash keyed on
+          // line/column. Drop with the v1 dual-match after one release.
+          previousFingerprintIdentity: {
             file: usage.file,
             from: usage.source,
             to: policy.to,
@@ -8760,16 +8785,28 @@ function indexTokensByCssVariable(tokens) {
 var RULE_ID22 = "tokens/css-vars-must-be-defined";
 var RULE_VERSION23 = "1";
 var CSS_VAR_REFERENCE = /var\(\s*(--[A-Za-z0-9_-]+)/gi;
+function contractVocabularyContext(ix) {
+  if (!ix.policy.cssVarsMustBeDefined()) return void 0;
+  const vocabulary = new Set(ix.byKind("contract_token").map((token) => token.name));
+  if (vocabulary.size === 0) return void 0;
+  return {
+    vocabulary,
+    prefixes: contractPrefixFamilies(vocabulary),
+    hasFlatTokens: [...vocabulary].some(isSingleSegmentVarName),
+    locallyDefinedCustomProperties: new Set(
+      ix.byKind("style_declaration").filter((decl) => decl.property.startsWith("--")).map((decl) => decl.property)
+    )
+  };
+}
+function isJudgedReference(tokenName, context) {
+  return context.vocabulary.has(tokenName) || sharesContractPrefix(tokenName, context.prefixes) || context.hasFlatTokens && isSingleSegmentVarName(tokenName) || context.locallyDefinedCustomProperties.has(tokenName);
+}
 function ruleTokensCssVarsMustBeDefined(ix) {
   const policy = ix.policy.cssVarsMustBeDefined();
   if (!policy) return [];
-  const vocabulary = new Set(ix.byKind("contract_token").map((token) => token.name));
-  if (vocabulary.size === 0) return [];
-  const prefixes = contractPrefixFamilies(vocabulary);
-  const hasFlatTokens = [...vocabulary].some(isSingleSegmentVarName);
-  const locallyDefinedCustomProperties = new Set(
-    ix.byKind("style_declaration").filter((decl) => decl.property.startsWith("--")).map((decl) => decl.property)
-  );
+  const context = contractVocabularyContext(ix);
+  if (!context) return [];
+  const { vocabulary } = context;
   const findings = [];
   for (const decl of ix.byKind("style_declaration")) {
     const seen = /* @__PURE__ */ new Set();
@@ -8779,8 +8816,7 @@ function ruleTokensCssVarsMustBeDefined(ix) {
       const tokenName = match[1];
       CSS_VAR_REFERENCE.lastIndex = skipToCloseParen(decl.value, match.index + 3);
       if (vocabulary.has(tokenName)) continue;
-      const shaped = sharesContractPrefix(tokenName, prefixes) || hasFlatTokens && isSingleSegmentVarName(tokenName) || locallyDefinedCustomProperties.has(tokenName);
-      if (!shaped) continue;
+      if (!isJudgedReference(tokenName, context)) continue;
       if (seen.has(tokenName)) continue;
       seen.add(tokenName);
       findings.push(
@@ -8819,6 +8855,23 @@ function sharesContractPrefix(name, prefixes) {
 function isSingleSegmentVarName(name) {
   return name.indexOf("-", 2) === -1;
 }
+function contractTokenReferenceCensus(ix) {
+  const context = contractVocabularyContext(ix);
+  if (!context) return void 0;
+  const checked = /* @__PURE__ */ new Set();
+  for (const decl of ix.byKind("style_declaration")) {
+    CSS_VAR_REFERENCE.lastIndex = 0;
+    let match;
+    while ((match = CSS_VAR_REFERENCE.exec(decl.value)) !== null) {
+      const tokenName = match[1];
+      CSS_VAR_REFERENCE.lastIndex = skipToCloseParen(decl.value, match.index + 3);
+      if (!isJudgedReference(tokenName, context)) continue;
+      checked.add(`${decl.location.file}:${decl.location.line}:${decl.location.column}`);
+      break;
+    }
+  }
+  return { checkedSites: checked.size };
+}
 function skipToCloseParen(value, openParenIndex) {
   let depth = 0;
   for (let i = openParenIndex; i < value.length; i++) {
@@ -10282,6 +10335,9 @@ export {
   EXPLAIN_URL_BASE,
   FRAGMENTS_INTERNAL_RULE_IDS,
   FactIndex,
+  GOVERNANCE_TELEMETRY_FIELDS,
+  GOVERNANCE_TELEMETRY_SOURCE_DISCLOSURE,
+  GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS,
   OWNED_PACKAGE_IDENTITY_EPOCH,
   OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
   PRESET_NAMES,
@@ -10383,6 +10439,7 @@ export {
   contractHash,
   contractPolicyFromGovernanceConfig,
   contractTierRuleIds,
+  contractTokenReferenceCensus,
   customerDefaultRuleStates,
   defineBlock,
   defineConfig,