@usefragments/core 1.10.2 → 2.0.0

package/src/facts/facts.test.ts

@@ -153,6 +153,21 @@ describe("fact IR — content-addressed IDs", () => {
     expect(a).toBe(b);
   });
 
+  it("rejects circular and runtime-only fact identity values deterministically", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+
+    expect(() => factId("component", circular)).toThrow(
+      "Circular fact identity value at (root).i.self"
+    );
+    expect(() => factId("component", { componentId: () => "Button" })).toThrow(
+      "Unsupported fact identity value at (root).i.componentId: function"
+    );
+    expect(() => factId("component", { confidence: Number.NaN })).toThrow(
+      "Unsupported fact identity value at (root).i.confidence: non-finite number"
+    );
+  });
+
   it("keys definition and identity facts by the portable componentKey", () => {
     const first = makeComponentDefinitionFact({
       file: "src/a/Button.tsx",

package/src/facts/ids.ts

@@ -22,15 +22,58 @@ import type { ComponentId, FactId } from "./types.js";
 // ---------------------------------------------------------------------------
 
 export function canonicalJson(value: unknown): string {
+  return canonicalJsonValue(value, new Set<object>(), "(root)");
+}
+
+function canonicalJsonValue(value: unknown, ancestors: Set<object>, path: string): string {
   if (value === undefined) return "null";
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Unsupported fact identity value at ${path}: non-finite number`);
+    }
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+      throw new TypeError(`Unsupported fact identity value at ${path}: number`);
+    }
+    return serialized;
+  }
+  if (typeof value !== "object") {
+    throw new TypeError(`Unsupported fact identity value at ${path}: ${typeof value}`);
+  }
   if (Array.isArray(value)) {
-    return `[${value.map(canonicalJson).join(",")}]`;
+    if (ancestors.has(value)) throw new TypeError(`Circular fact identity value at ${path}`);
+    ancestors.add(value);
+    try {
+      return `[${value
+        .map((entry, index) => canonicalJsonValue(entry, ancestors, `${path}[${index}]`))
+        .join(",")}]`;
+    } finally {
+      ancestors.delete(value);
+    }
   }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    const objectType = prototype?.constructor?.name ?? "unknown";
+    throw new TypeError(`Unsupported fact identity object at ${path}: ${objectType}`);
+  }
+  if (ancestors.has(value)) throw new TypeError(`Circular fact identity value at ${path}`);
+  ancestors.add(value);
   const entries = Object.entries(value as Record<string, unknown>)
     .filter(([, v]) => v !== undefined)
     .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+  try {
+    return `{${entries
+      .map(
+        ([key, entry]) =>
+          `${JSON.stringify(key)}:${canonicalJsonValue(entry, ancestors, `${path}.${key}`)}`
+      )
+      .join(",")}}`;
+  } finally {
+    ancestors.delete(value);
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/facts/index.ts

@@ -72,8 +72,21 @@ export type {
   TailwindTokenResolvedFact,
   TailwindValue,
   ThemeDeclarationFact,
+  CanonicalFactConflictV1,
+  CanonicalFactConflictValueV1,
+  CanonicalFactIntegrityV1,
 } from "./types.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 "./integrity.js";
+
 export { componentId, asComponentId, factId, hash64Hex, canonicalJson } from "./ids.js";
 
 export {
@@ -122,7 +135,7 @@ export {
 } from "./builders.js";
 
 export { FactIndex, matchesGlob } from "./fact-index.js";
-export type { FactConflict, FactEvidence } from "./fact-index.js";
+export type { FactConflict, FactDuplicate, FactEvidence } from "./fact-index.js";
 
 export { compileGlobalGovernanceFacts, compileComponentFacts } from "./compile.js";
 export { projectSupersededImportPathPreferences } from "./compile.js";

package/src/facts/integrity.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { compareCanonicalStrings } from "../contract/hash.js";
+import { digestHexStringSchema } from "../domain-ids.js";
+import type { CanonicalFactIntegrityV1 } from "./types.js";
+
+export const CANONICAL_FACT_MAX_CONFLICTS_V1 = 1_000;
+export const CANONICAL_FACT_MAX_VALUES_PER_CONFLICT_V1 = 64;
+export const CANONICAL_FACT_MAX_PROVENANCE_PER_VALUE_V1 = 1_000;
+
+const boundedString = z.string().min(1).max(4_096);
+const unique = (values: readonly string[]): boolean => new Set(values).size === values.length;
+const provenance = z
+  .array(boundedString)
+  .min(1)
+  .max(CANONICAL_FACT_MAX_PROVENANCE_PER_VALUE_V1)
+  .refine(unique, "provenance values must be unique");
+
+export const canonicalFactConflictValueV1Schema = z
+  .object({
+    valueDigest: digestHexStringSchema,
+    factIds: provenance,
+    totalFactIdCount: z.number().int().positive().optional(),
+    analyzerIds: provenance,
+    totalAnalyzerIdCount: z.number().int().positive().optional(),
+    evidenceRefs: provenance,
+    totalEvidenceRefCount: z.number().int().positive().optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    for (const [path, total, retained] of [
+      ["totalFactIdCount", value.totalFactIdCount, value.factIds.length],
+      ["totalAnalyzerIdCount", value.totalAnalyzerIdCount, value.analyzerIds.length],
+      ["totalEvidenceRefCount", value.totalEvidenceRefCount, value.evidenceRefs.length],
+    ] as const) {
+      if (total !== undefined && total < retained) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [path],
+          message: `${path} cannot be smaller than retained provenance`,
+        });
+      }
+    }
+  });
+
+export const canonicalFactConflictV1Schema = z
+  .object({
+    canonicalKey: boundedString,
+    factKind: boundedString,
+    state: z.literal("conflict"),
+    values: z
+      .array(canonicalFactConflictValueV1Schema)
+      .min(2)
+      .max(CANONICAL_FACT_MAX_VALUES_PER_CONFLICT_V1)
+      .refine(
+        (values) => new Set(values.map((value) => value.valueDigest)).size === values.length,
+        "conflict values must have distinct material digests"
+      ),
+    totalValueCount: z.number().int().min(2).optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.totalValueCount !== undefined && value.totalValueCount < value.values.length) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["totalValueCount"],
+        message: "totalValueCount cannot be smaller than retained values",
+      });
+    }
+  });
+
+export const canonicalFactIntegrityV1Schema = z.union([
+  z
+    .object({
+      state: z.literal("healthy"),
+      coalescedDuplicateCount: z.number().int().nonnegative(),
+    })
+    .strict(),
+  z
+    .object({
+      state: z.literal("conflict"),
+      coalescedDuplicateCount: z.number().int().nonnegative(),
+      conflicts: z
+        .array(canonicalFactConflictV1Schema)
+        .min(1)
+        .max(CANONICAL_FACT_MAX_CONFLICTS_V1)
+        .refine(
+          (conflicts) =>
+            new Set(conflicts.map((conflict) => conflict.canonicalKey)).size === conflicts.length,
+          "canonical conflict keys must be unique"
+        ),
+      totalConflictCount: z.number().int().positive().optional(),
+    })
+    .strict()
+    .superRefine((value, context) => {
+      if (
+        value.totalConflictCount !== undefined &&
+        value.totalConflictCount < value.conflicts.length
+      ) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["totalConflictCount"],
+          message: "totalConflictCount cannot be smaller than retained conflicts",
+        });
+      }
+    }),
+]);
+
+const sorted = (values: readonly string[]): string[] => [...values].sort();
+
+export function normalizeCanonicalFactIntegrityV1(value: unknown): CanonicalFactIntegrityV1 {
+  const parsed = canonicalFactIntegrityV1Schema.parse(value);
+  if (parsed.state === "healthy") return parsed;
+  return {
+    ...parsed,
+    totalConflictCount: parsed.totalConflictCount ?? parsed.conflicts.length,
+    conflicts: parsed.conflicts
+      .map((conflict) => ({
+        ...conflict,
+        totalValueCount: conflict.totalValueCount ?? conflict.values.length,
+        values: conflict.values
+          .map((entry) => ({
+            ...entry,
+            factIds: sorted(entry.factIds),
+            totalFactIdCount: entry.totalFactIdCount ?? entry.factIds.length,
+            analyzerIds: sorted(entry.analyzerIds),
+            totalAnalyzerIdCount: entry.totalAnalyzerIdCount ?? entry.analyzerIds.length,
+            evidenceRefs: sorted(entry.evidenceRefs),
+            totalEvidenceRefCount: entry.totalEvidenceRefCount ?? entry.evidenceRefs.length,
+          }))
+          .sort((left, right) => compareCanonicalStrings(left.valueDigest, right.valueDigest)),
+      }))
+      .sort((left, right) => compareCanonicalStrings(left.canonicalKey, right.canonicalKey)),
+  };
+}

package/src/facts/types.ts

@@ -160,6 +160,11 @@ export interface StyleFontSizeScaleFact extends BaseFact, PolicyFactExcludes {
 export interface StyleCssVarsMustBeDefinedFact extends BaseFact, PolicyFactExcludes {
   kind: "style_css_vars_must_be_defined";
   severity: GovernanceSeverity;
+  /**
+   * Repo-relative path of the resolved fragments config, when the scan knows
+   * it. Omitted from fact identity — same policy, different config filename.
+   */
+  configPath?: string;
 }
 
 /**
@@ -758,3 +763,34 @@ export type FactKind = Fact["kind"];
 
 /** Narrows a Fact union by kind. */
 export type FactOfKind<K extends FactKind> = Extract<Fact, { kind: K }>;
+
+// ---------------------------------------------------------------------------
+// V1 canonical integrity vocabulary (additive; current FactIndex is unchanged)
+// ---------------------------------------------------------------------------
+
+export interface CanonicalFactConflictValueV1 {
+  valueDigest: string;
+  factIds: string[];
+  totalFactIdCount?: number;
+  analyzerIds: string[];
+  totalAnalyzerIdCount?: number;
+  evidenceRefs: string[];
+  totalEvidenceRefCount?: number;
+}
+
+export interface CanonicalFactConflictV1 {
+  canonicalKey: string;
+  factKind: string;
+  state: "conflict";
+  values: CanonicalFactConflictValueV1[];
+  totalValueCount?: number;
+}
+
+export type CanonicalFactIntegrityV1 =
+  | { state: "healthy"; coalescedDuplicateCount: number }
+  | {
+      state: "conflict";
+      coalescedDuplicateCount: number;
+      conflicts: CanonicalFactConflictV1[];
+      totalConflictCount?: number;
+    };

package/src/governance-integrity.test.ts

@@ -614,6 +614,7 @@ describe("evaluateGovernanceIntegrity", () => {
     const tokens = verdict.families.find((f) => f.id === "tokens");
     expect(tokens?.armed).toBe(false);
     expect(tokens?.reason).toBe("no token vocabulary");
+    expect(verdict.roster).toMatchObject({ configured: 1, active: 0, inert: 1 });
   });
 
   it("7c. error-level token drift with a vocabulary is blocking-capable", () => {

package/src/governance-integrity.ts

@@ -227,7 +227,7 @@ const PASSTHROUGH_KEYS = [
   },
   {
     path: ["registry"],
-    keys: ["requireStory", "publicOnly", "categoryDepth", "includeProps", "embedFragments"],
+    keys: ["requireStory", "publicOnly", "categoryDepth", "includeProps"],
   },
   {
     path: ["govern", "tailwind"],
@@ -953,10 +953,12 @@ export function evaluateGovernanceIntegrity(
   const activeRuleCount = [...configs.entries()].filter(
     ([ruleId, config]) => CONSUMED_RULE_IDS.has(ruleId) && config.enabled
   ).length;
+  const tokensVocabularyInert =
+    !tokensArmed && tokensFamily.reason === "no token vocabulary" ? 1 : 0;
   const roster = {
     configured: configuredRuleCount + configDiagnostics.length,
-    active: activeRuleCount,
-    inert: configDiagnostics.length,
+    active: Math.max(0, activeRuleCount - tokensVocabularyInert),
+    inert: configDiagnostics.length + tokensVocabularyInert,
   };
 
   return {

package/src/governance-telemetry.ts

@@ -327,6 +327,14 @@ export const GOVERNANCE_TELEMETRY_FIELDS = [
     carriage: "derived",
     topLevelField: "adoption",
   },
+  {
+    path: "adoption.adopted[].{componentKey,displayName,canonicalTarget,usageCount}",
+    type: "bounded adopted component-identity summaries",
+    purpose:
+      "Explains which canonical components account for current adopted call sites without uploading source.",
+    carriage: "derived",
+    topLevelField: "adoption",
+  },
   {
     path: "adoption.shadows[].{componentKey,displayName,canonicalTarget,usageCount}",
     type: "bounded component-identity summaries",

package/src/governance.ts

@@ -133,10 +133,15 @@ const componentCapabilityRecordSchema = z.object({
   capability: z.string().min(1),
 });
 
+const requiredComponentGovernanceValueSchema = z.custom<unknown>(
+  (value) => value !== undefined,
+  "Expected an explicitly present governance value"
+);
+
 const propValueAvoidRecordSchema = z.object({
   kind: z.literal("prop.value.avoid"),
   prop: z.string().min(1),
-  value: z.unknown(),
+  value: requiredComponentGovernanceValueSchema,
   because: z.string(),
   suggest: z.string().optional(),
   severity: governanceSeveritySchema,
@@ -145,10 +150,10 @@ const propValueAvoidRecordSchema = z.object({
 const propValueForbidRecordSchema = z.object({
   kind: z.literal("prop.value.forbid"),
   prop: z.string().min(1),
-  value: z.unknown(),
+  value: requiredComponentGovernanceValueSchema,
   when: z.object({ path: z.string().min(1).optional() }).optional(),
   because: z.string(),
-  fix: z.object({ replaceWith: z.unknown() }).optional(),
+  fix: z.object({ replaceWith: requiredComponentGovernanceValueSchema }).optional(),
   severity: governanceSeveritySchema,
 });
 
@@ -167,6 +172,24 @@ export const componentGovernanceRecordSchema = z.discriminatedUnion("kind", [
 
 export const componentGovernanceRecordsSchema = z.array(componentGovernanceRecordSchema);
 
+/** Parse portable component policy records; malformed authority is unavailable, never empty. */
+export function parseComponentGovernancePolicyJson(
+  policyJson: string
+): ComponentGovernanceRecord[] | null {
+  try {
+    const parsed: unknown = JSON.parse(policyJson);
+    const record =
+      parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : null;
+    const candidate = Array.isArray(parsed) ? parsed : (record?.governance ?? record?.rules);
+    const result = componentGovernanceRecordsSchema.safeParse(candidate);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+
 const componentPolicyMatchSchema = z
   .object({
     componentKey: z.string().min(1).optional(),
@@ -587,10 +610,15 @@ export interface ComponentGovernanceBuilder<TProps> {
   accessibility(): AccessibilityGovernanceBuilder;
 }
 
-export interface GovernedFragmentDefinition<
+/**
+ * One-argument governed definition. Requires an explicit `govern` function
+ * and/or `governance` records — both optional keys previously let plain v2
+ * definitions satisfy this type (the optional-key type lie).
+ */
+type GovernedFragmentDefinitionBase<
   TProps = unknown,
   TComponent extends FragmentComponent<TProps> = FragmentComponent<TProps>,
-> {
+> = {
   component: TComponent;
   meta: FragmentMeta;
   guidance: FragmentGuidance;
@@ -605,9 +633,22 @@ export interface GovernedFragmentDefinition<
   };
   contract?: FragmentContract;
   _provenance?: FragmentProvenance;
-  govern?: (g: ComponentGovernanceBuilder<TProps>) => ComponentGovernanceRecord[];
-  governance?: ComponentGovernanceRecord[];
-}
+};
+
+export type GovernedFragmentDefinition<
+  TProps = unknown,
+  TComponent extends FragmentComponent<TProps> = FragmentComponent<TProps>,
+> = GovernedFragmentDefinitionBase<TProps, TComponent> &
+  (
+    | {
+        govern: (g: ComponentGovernanceBuilder<TProps>) => ComponentGovernanceRecord[];
+        governance?: ComponentGovernanceRecord[];
+      }
+    | {
+        governance: ComponentGovernanceRecord[];
+        govern?: (g: ComponentGovernanceBuilder<TProps>) => ComponentGovernanceRecord[];
+      }
+  );
 
 export type ResolvedGovernedFragmentDefinition<
   TProps = unknown,
@@ -668,6 +709,27 @@ export function resolveComponentGovernance<TProps>(
   return componentGovernanceRecordsSchema.parse(records);
 }
 
+/**
+ * Resolve the component governance records that belong in the FCID preimage.
+ *
+ * Prefer an already-resolved `governance` array (Cloud mint / compiled payloads).
+ * Fall back to evaluating `govern` when present. Returns `undefined` when the
+ * fragment carries no governance surface — callers omit the field from identity.
+ */
+export function resolveGovernanceRecordsForIdentity(
+  definition: Pick<GovernedFragmentDefinition, "govern" | "governance"> | null | undefined
+): ComponentGovernanceRecord[] | undefined {
+  if (!definition) return undefined;
+  if (Array.isArray(definition.governance)) {
+    return componentGovernanceRecordsSchema.parse(definition.governance);
+  }
+  if (typeof definition.govern === "function") {
+    const builder = createComponentGovernanceBuilder();
+    return componentGovernanceRecordsSchema.parse(definition.govern(builder));
+  }
+  return undefined;
+}
+
 export function normalizeGovernanceConfig<TConfig extends { govern?: GovernanceConfig }>(
   config: TConfig
 ): TConfig {