@usefragments/core 2.0.1 → 2.1.0

package/src/evaluation/receipt.ts

@@ -7,7 +7,11 @@ import {
   parseAnalysisPlanV1,
 } from "../analysis-plan/index.js";
 import { canonicalPreimage, contractHash, sha256Hex } from "../contract/hash.js";
-import { CONTRACT_PREIMAGE_SCHEMA, type ContractPreimage } from "../contract/preimage.js";
+import {
+  CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  type ContractPreimage,
+} from "../contract/preimage.js";
 import {
   digestHexStringSchema,
   evaluationReceiptIdFromDigest,
@@ -21,6 +25,7 @@ import {
   repositoryBindingDigestV1,
   repositoryBindingKeyV1Schema,
 } from "../repository-binding.js";
+import { SOURCE_IDENTITY_EVALUATOR_VERSION_V2 } from "./types.js";
 import type {
   EffectiveEvaluationWaiverV2,
   EvaluationInputV2,
@@ -51,7 +56,7 @@ const unique = (values: readonly string[]): boolean => new Set(values).size ===
 
 const contractPreimageV1Schema: z.ZodType<ContractPreimage> = z
   .object({
-    schema: z.literal(CONTRACT_PREIMAGE_SCHEMA),
+    schema: z.enum([CONTRACT_PREIMAGE_SCHEMA, CONTRACT_PREIMAGE_SCHEMA_V2]),
     domains: z
       .object({
         components: digestHexStringSchema,
@@ -205,6 +210,16 @@ const evaluationInputV2RawSchema = z
   })
   .strict()
   .superRefine((input, context) => {
+    if (
+      input.contract.preimage.schema === CONTRACT_PREIMAGE_SCHEMA_V2 &&
+      input.evaluatorVersion !== SOURCE_IDENTITY_EVALUATOR_VERSION_V2
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["evaluatorVersion"],
+        message: "Source-qualified contracts require evaluation-kernel:v2.2",
+      });
+    }
     let plan;
     try {
       plan = parseAnalysisPlanV1(input.analysisPlan);

package/src/evaluation/types.ts

@@ -14,7 +14,11 @@
  * contract — every scenario's authored kernel verdict must land.
  */
 
-import type { ContractPreimage } from "../contract/preimage.js";
+import {
+  CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  type ContractPreimage,
+} from "../contract/preimage.js";
 import type {
   AnalysisPlanV1,
   CoverageRegionV1,
@@ -26,9 +30,20 @@ import type { FactIndex } from "../facts/fact-index.js";
 import type { RepositoryBindingKeyV1 } from "../repository-binding.js";
 
 /** Bumped when kernel semantics change in a way that can flip a verdict. */
-export const EVALUATOR_VERSION = "evaluation-kernel:v1" as const;
-/** Authoritative facts-only evaluator introduced by Fragments V1 Brief 04. */
-export const EVALUATOR_VERSION_V2 = "evaluation-kernel:v2" as const;
+export const EVALUATOR_VERSION = "evaluation-kernel:v1.1" as const;
+/** Current facts-only evaluator. The input schema remains V2. */
+export const EVALUATOR_VERSION_V2 = "evaluation-kernel:v2.1" as const;
+/** Source-qualified contracts require this generation; older receipts retain their semantics. */
+export const SOURCE_IDENTITY_EVALUATOR_VERSION_V2 = "evaluation-kernel:v2.2" as const;
+/** Replay-only generation: its captured mapping judgments remain authoritative. */
+export const LEGACY_EVALUATOR_VERSION_V2 = "evaluation-kernel:v2" as const;
+
+/** Missing schema is a retained V1 row; unknown future generations fail closed. */
+export function evaluatorVersionForContractSchema(schema?: string): string | null {
+  if (schema === undefined || schema === CONTRACT_PREIMAGE_SCHEMA) return EVALUATOR_VERSION_V2;
+  if (schema === CONTRACT_PREIMAGE_SCHEMA_V2) return SOURCE_IDENTITY_EVALUATOR_VERSION_V2;
+  return null;
+}
 
 /**
  * Four-state per-finding model (spec §2). `candidate` is the derivation step —

package/src/index.ts

@@ -881,6 +881,10 @@ export {
   CONTRACT_ENFORCEMENT_FIELDS,
   CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  CONTRACT_PREIMAGE_CAPABILITIES,
+  SUPPORTED_CONTRACT_PREIMAGE_SCHEMAS,
+  isSupportedContractPreimageSchema,
   ContractCatalogValidationError,
   contractComponentsFromFragments,
   contractHash,
@@ -928,6 +932,7 @@ export type {
   ContractIdentityPin,
   ContractPolicyInput,
   ContractPreimage,
+  ContractPreimageSchema,
   ContractPropMappingInput,
   ContractStampPin,
   ContractStampRecord,
@@ -1129,6 +1134,9 @@ export {
   EVALUATION_RECEIPT_STRING_MAX_BYTES_V1,
   EVALUATOR_VERSION,
   EVALUATOR_VERSION_V2,
+  SOURCE_IDENTITY_EVALUATOR_VERSION_V2,
+  evaluatorVersionForContractSchema,
+  LEGACY_EVALUATOR_VERSION_V2,
   effectiveEvaluationWaiverV2Schema,
   evaluate,
   evaluationInputDigestV2,
@@ -1181,3 +1189,24 @@ export {
   APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH,
   isApprovedContractTokenNames,
 } from "./approved-contract-tokens.js";
+
+export {
+  contractComponentSourceKey,
+  contractComponentExportAddresses,
+  approvedComponentGovernanceByteLimit,
+  APPROVED_COMPONENT_GOVERNANCE_LEGACY_MAX_BYTES,
+  APPROVED_COMPONENT_GOVERNANCE_QUALIFIED_MAX_BYTES,
+  contractComponentReplacementImport,
+  contractSourceFromFragment,
+  normalizeContractComponentSource,
+  normalizeContractSourcePath,
+  contractComponentsFromFragmentsV2,
+  projectContractPreimageV2,
+} from "./contract/source-identity.js";
+export type {
+  ContractComponentSource,
+  ContractComponentExport,
+  ContractComponentInputV2,
+  ContractCanonicalMappingInputV2,
+  ContractCatalogInputV2,
+} from "./contract/source-identity.js";

package/src/rules/components-prefer-library-classnames.test.ts

@@ -0,0 +1,354 @@
+import { describe, expect, it } from "vitest";
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  makeClassNameDynamicFact,
+  makeUsageNodeFact,
+  makeUsageImportFact,
+  ruleComponentsPreferLibrary,
+} from "../index.js";
+
+function scan(options: Record<string, unknown>) {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      rules: {
+        "components/prefer-library": { enabled: true, severity: "error", options },
+      },
+    })
+  );
+  const location = { file: "src/App.tsx", line: 2, column: 1 };
+  const node = makeUsageNodeFact({ file: location.file, nodePath: "0", element: "div", location });
+  ix.add(node);
+  ix.add(
+    makeClassNameDynamicFact({
+      file: location.file,
+      nodeId: node.id,
+      attr: "className",
+      reason: "identifier",
+      snippet: "styles.alert",
+      originPath: "0",
+      location,
+    })
+  );
+  return ruleComponentsPreferLibrary(ix);
+}
+const mappings = ["first", "second"].map((folder) => ({
+  name: "Alert",
+  canonical: "Alert",
+  importPath: `@acme/${folder}`,
+  source: { kind: "repository", path: `${folder}/Alert.tsx`, symbol: "Alert" },
+  exportAddresses: [{ kind: "package", importPath: `@acme/${folder}`, exportName: "Alert" }],
+}));
+const qualified = { sourceIdentitySchema: "component-source:v1" };
+
+describe("source-qualified class-name advice", () => {
+  it("preserves legacy authored-order import advice", () => {
+    const forward = scan({ canonicalMappings: mappings });
+    const reverse = scan({ canonicalMappings: [...mappings].reverse() });
+    expect(forward[0]?.attributes?.suggestedImport).toBe("@acme/first");
+    expect(reverse[0]?.attributes?.suggestedImport).toBe("@acme/second");
+  });
+  it("retains all same-name alternatives without choosing an import or replacement", () => {
+    const forward = scan({ ...qualified, canonicalMappings: mappings });
+    const reverse = scan({ ...qualified, canonicalMappings: [...mappings].reverse() });
+    const withoutEvidence = (value: typeof forward) =>
+      value.map(({ evidence: _, ...rest }) => rest);
+    expect(withoutEvidence(forward)).toEqual(withoutEvidence(reverse));
+    expect(forward).toHaveLength(1);
+    expect(forward[0]?.level).toBe("warn");
+    expect(forward[0]?.attributes?.advisory).toBe(true);
+    expect(forward[0]?.attributes?.canonicalAlternatives).toHaveLength(2);
+    expect(forward[0]?.attributes?.ambiguousCanonicalTarget).toBe(true);
+    expect(forward[0]?.attributes).not.toHaveProperty("suggestedComponent");
+    expect(forward[0]?.attributes).not.toHaveProperty("suggestedImport");
+    expect(forward[0]?.fix).toBeUndefined();
+  });
+  it("uses a proven barrel alias instead of the implementation name", () => {
+    const findings = scan({
+      ...qualified,
+      canonicalMappings: [
+        {
+          ...mappings[0],
+          exportAddresses: [
+            { kind: "package", importPath: "@acme/public", exportName: "PublicAlert" },
+          ],
+        },
+      ],
+    });
+    expect(findings[0]?.attributes).toMatchObject({
+      suggestedComponent: "PublicAlert",
+      suggestedImport: "@acme/public",
+    });
+  });
+  it("does not grant guessed package labels public export authority", () => {
+    const findings = scan({
+      ...qualified,
+      canonicalMappings: [{ ...mappings[0], exportAddresses: [] }],
+    });
+    expect(findings[0]?.attributes?.unresolvedCanonicalExport).toBe(true);
+    expect(findings[0]?.attributes).not.toHaveProperty("suggestedImport");
+    expect(findings[0]?.attributes).not.toHaveProperty("suggestedComponent");
+  });
+  it("recognizes a package inventory entry already proven by a repository export", () => {
+    const findings = scan({
+      ...qualified,
+      canonicalMappings: [mappings[0]],
+      canonicalSources: [{ kind: "npm", specifier: "@acme/first", include: ["Alert"] }],
+    });
+    expect(findings[0]?.attributes?.suggestedImport).toBe("@acme/first");
+    expect(findings[0]?.attributes).not.toHaveProperty("ambiguousCanonicalTarget");
+  });
+  it("does not select one of two adopted packages with the same public name", () => {
+    const findings = scan({
+      ...qualified,
+      canonicalSources: ["first", "second"].map((folder) => ({
+        kind: "npm",
+        specifier: `@acme/${folder}`,
+        include: ["Alert"],
+      })),
+    });
+    expect(findings[0]?.attributes?.canonicalAlternatives).toHaveLength(2);
+    expect(findings[0]?.attributes).not.toHaveProperty("suggestedImport");
+  });
+});
+
+function componentScan(
+  options: Record<string, unknown>,
+  imported?: { source: string; name: string }
+) {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      rules: {
+        "components/prefer-library": { enabled: true, severity: "error", options },
+      },
+    })
+  );
+  const location = { file: "src/App.tsx", line: 2, column: 1 };
+  ix.add(
+    makeUsageNodeFact({
+      file: location.file,
+      nodePath: "0",
+      element: imported ? "Button" : "button",
+      location,
+    })
+  );
+  if (imported)
+    ix.add(
+      makeUsageImportFact({
+        file: location.file,
+        local: "Button",
+        imported: imported.name,
+        source: imported.source,
+        location,
+      })
+    );
+  return ruleComponentsPreferLibrary(ix);
+}
+
+describe("qualified suggestion path consistency", () => {
+  const sources = ["first", "second"].map((name) => ({
+    kind: "npm",
+    specifier: `@acme/${name}`,
+    include: ["Button"],
+  }));
+  it("keeps legacy built-in source order but leaves qualified choices advisory and unresolved", () => {
+    expect(componentScan({ canonicalSources: sources })[0]?.attributes?.suggestedImport).toBe(
+      "@acme/first"
+    );
+    const forward = componentScan({ ...qualified, canonicalSources: sources });
+    const reverse = componentScan({ ...qualified, canonicalSources: [...sources].reverse() });
+    expect(forward[0]?.attributes).toEqual(reverse[0]?.attributes);
+    expect(forward[0]?.level).toBe("warn");
+    expect(forward[0]?.attributes).toMatchObject({
+      advisory: true,
+      ambiguousCanonicalTarget: true,
+    });
+    expect(forward[0]?.attributes?.canonicalAlternatives).toHaveLength(2);
+    expect(forward[0]?.attributes).not.toHaveProperty("suggestedImport");
+    expect(forward[0]?.fix).toBeUndefined();
+  });
+  it("does not select between public addresses of the same definition using inventory order or package metadata", () => {
+    const addresses = ["first", "second"].map((name) => ({
+      kind: "package",
+      importPath: `@acme/${name}`,
+      exportName: "Alert",
+    }));
+    const mapping = { ...mappings[0], exportAddresses: addresses };
+    const inventories = sources.map((source) => ({ ...source, include: ["Alert"] }));
+    const first = scan({
+      ...qualified,
+      canonicalMappings: [mapping],
+      canonicalSources: inventories,
+    });
+    const second = scan({
+      ...qualified,
+      canonicalMappings: [{ ...mapping, exportAddresses: [...addresses].reverse() }],
+      canonicalSources: [...inventories].reverse(),
+    });
+    expect(first[0]?.attributes).toEqual(second[0]?.attributes);
+    expect(first[0]?.attributes?.canonicalAlternatives).toHaveLength(2);
+    expect(first[0]?.attributes).not.toHaveProperty("suggestedImport");
+    expect(first[0]?.attributes).not.toHaveProperty("suggestedComponent");
+    expect(first[0]?.fix).toBeUndefined();
+  });
+  it("deduplicates repeated evidence for the same public address", () => {
+    const address = mappings[0]!.exportAddresses[0]!;
+    const findings = scan({
+      ...qualified,
+      canonicalMappings: [{ ...mappings[0], exportAddresses: [address, address] }],
+    });
+    expect(findings[0]?.attributes).toMatchObject({
+      suggestedImport: "@acme/first",
+      suggestedComponent: "Alert",
+    });
+    expect(findings[0]?.attributes).not.toHaveProperty("ambiguousCanonicalTarget");
+  });
+  it.each([
+    { source: "@acme/first", name: "Wrong" },
+    { source: "@acme/first/unproven-subpath", name: "Button" },
+  ])("does not let legacy root/name matching hide ambiguity for $source#$name", (imported) => {
+    const canonicalMappings = sources.map((source) => ({
+      name: "Button",
+      canonical: "Button",
+      importPath: source.specifier,
+      source: { kind: "package", importPath: source.specifier, exportName: "Button" },
+    }));
+    expect(componentScan({ canonicalMappings, canonicalSources: sources }, imported)).toEqual([]);
+    const findings = componentScan(
+      { ...qualified, canonicalMappings, canonicalSources: sources },
+      imported
+    );
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.attributes?.ambiguousCanonicalTarget).toBe(true);
+    expect(findings[0]?.attributes).not.toHaveProperty("suggestedImport");
+    expect(findings[0]?.fix).toBeUndefined();
+  });
+  it("accepts both exact approved public exports", () => {
+    for (const source of sources)
+      expect(
+        componentScan(
+          { ...qualified, canonicalSources: sources },
+          { source: source.specifier, name: "Button" }
+        )
+      ).toEqual([]);
+  });
+});
+
+describe("qualified owned-package aliases", () => {
+  const spellings = ["@usefragments/ui", "@fragments-sdk/ui"];
+  const addresses = spellings.map((importPath) => ({
+    kind: "package",
+    importPath,
+    exportName: "Alert",
+  }));
+  it("joins an owned alias inventory to the same proven repository export", () => {
+    const findings = scan({
+      ...qualified,
+      canonicalMappings: [{ ...mappings[0], exportAddresses: [addresses[0]] }],
+      canonicalSources: [{ kind: "npm", specifier: spellings[1], include: ["Alert"] }],
+    });
+    expect(findings[0]?.attributes?.suggestedImport).toBe("@usefragments/ui");
+    expect(findings[0]?.attributes).not.toHaveProperty("ambiguousCanonicalTarget");
+  });
+  it("deduplicates equivalent exports before selecting canonical spelling in either order", () => {
+    for (const exportAddresses of [addresses, [...addresses].reverse()]) {
+      const findings = scan({
+        ...qualified,
+        canonicalMappings: [{ ...mappings[0], exportAddresses }],
+      });
+      expect(findings[0]?.attributes?.suggestedImport).toBe("@usefragments/ui");
+      expect(findings[0]?.attributes).not.toHaveProperty("ambiguousCanonicalTarget");
+    }
+  });
+  it("normalizes built-in fallback guidance independently of inventory order", () => {
+    const inventories = spellings.map((specifier) => ({
+      kind: "npm",
+      specifier,
+      include: ["Button"],
+    }));
+    for (const canonicalSources of [inventories, [...inventories].reverse()]) {
+      const findings = componentScan({ ...qualified, canonicalSources });
+      expect(findings[0]?.attributes?.suggestedImport).toBe("@usefragments/ui");
+      expect(findings[0]?.attributes).not.toHaveProperty("ambiguousCanonicalTarget");
+    }
+  });
+});
+
+describe("qualified JSX replacement names", () => {
+  it("recognizes an existing exact default import using its real local binding", () => {
+    expect(
+      componentScan(
+        {
+          ...qualified,
+          canonicalMappings: [
+            {
+              name: "Button",
+              canonical: "Button",
+              htmlEquivalent: "button",
+              source: { kind: "repository", path: "src/Button.tsx", symbol: "Button" },
+              exportAddresses: [
+                { kind: "package", importPath: "@acme/ui/button", exportName: "default" },
+              ],
+            },
+          ],
+        },
+        { source: "@acme/ui/button", name: "default" }
+      )
+    ).toEqual([]);
+  });
+  it.each(["default", "lowercase", "not-an-identifier"])(
+    "keeps %s unresolved without inventing a local binding",
+    (exportName) => {
+      const canonicalMappings = [
+        {
+          name: "Button",
+          canonical: "Button",
+          htmlEquivalent: "button",
+          source: { kind: "repository", path: "src/Button.tsx", symbol: "Button" },
+          exportAddresses: [{ kind: "package", importPath: "@acme/ui", exportName }],
+        },
+      ];
+      const findings = componentScan({ ...qualified, canonicalMappings });
+      expect(findings).toHaveLength(1);
+      expect(findings[0]?.level).toBe("error");
+      expect(findings[0]?.attributes?.unresolvedCanonicalExport).toBe(true);
+      expect(findings[0]?.attributes).not.toHaveProperty("suggestedComponent");
+      expect(findings[0]?.attributes).not.toHaveProperty("suggestedImport");
+      expect(findings[0]?.fix).toBeUndefined();
+      const classFindings = scan({
+        ...qualified,
+        canonicalMappings: canonicalMappings.map((mapping) => ({
+          ...mapping,
+          name: "Alert",
+          canonical: "Alert",
+          htmlEquivalent: undefined,
+        })),
+      });
+      expect(classFindings[0]?.attributes?.advisory).toBe(true);
+      expect(classFindings[0]?.attributes).not.toHaveProperty("suggestedComponent");
+      expect(classFindings[0]?.attributes).not.toHaveProperty("suggestedImport");
+      expect(classFindings[0]?.fix).toBeUndefined();
+    }
+  );
+  it.each(["Button", "PublicButton"])(
+    "keeps the proven %s named export actionable",
+    (exportName) => {
+      const findings = componentScan({
+        ...qualified,
+        canonicalMappings: [
+          {
+            name: "Button",
+            canonical: "Button",
+            htmlEquivalent: "button",
+            source: { kind: "repository", path: "src/Button.tsx", symbol: "Button" },
+            exportAddresses: [{ kind: "package", importPath: "@acme/ui", exportName }],
+          },
+        ],
+      });
+      expect(findings[0]?.attributes?.suggestedComponent).toBe(exportName);
+      expect(findings[0]?.fix).toMatchObject({ kind: "replaceComponent", to: exportName });
+    }
+  );
+});