@usefragments/core 2.0.2 → 2.1.0

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 });
+    }
+  );
+});

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

@@ -344,3 +344,249 @@ describe("components/prefer-library — #9e directory import-path identity", ()
     expect(ruleComponentsPreferLibrary(ix)).toHaveLength(1);
   });
 });
+
+describe("source-qualified canonical mapping execution", () => {
+  const mappings = ["first", "second"].map((name) => ({
+    name: "Button",
+    canonical: "Button",
+    htmlEquivalent: "button",
+    importPath: `@acme/${name}`,
+    source: { kind: "package", importPath: `@acme/${name}`, exportName: "Button" },
+    propMapping: [{ rawProp: "title", canonicalProp: name === "first" ? "label" : "caption" }],
+  }));
+  function scan(input: { reverse?: boolean; sourceQualified?: boolean; imported?: string }) {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "error",
+            options: {
+              ...(input.sourceQualified ? { sourceIdentitySchema: "component-source:v1" } : {}),
+              canonicalMappings: input.reverse ? [...mappings].reverse() : mappings,
+            },
+          },
+        },
+      })
+    );
+    const element = input.imported ? "Button" : "button";
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: "0",
+        element,
+        location: { file: "src/App.tsx", line: 1, column: 1 },
+      })
+    );
+    if (input.imported)
+      ix.add(
+        makeUsageImportFact({
+          file: "src/App.tsx",
+          local: "Button",
+          imported: "Button",
+          source: input.imported,
+          location: { file: "src/App.tsx", line: 1, column: 1 },
+        })
+      );
+    return ruleComponentsPreferLibrary(ix);
+  }
+  it("retains legacy first-target guidance for unmarked policy", () => {
+    expect(scan({})[0]?.attributes?.suggestedImport).toBe("@acme/first");
+  });
+  it("does not arbitrarily select props or an import when multiple approved targets fit", () => {
+    const forward = scan({ sourceQualified: true });
+    const withoutCapturedPolicy = (findings: ReturnType<typeof scan>) =>
+      findings.map(({ evidence: _evidence, ...finding }) => finding);
+    expect(withoutCapturedPolicy(forward)).toEqual(
+      withoutCapturedPolicy(scan({ sourceQualified: true, reverse: true }))
+    );
+    expect(forward).toHaveLength(1);
+    expect(forward[0]?.attributes?.ambiguousCanonicalTarget).toBe(true);
+    expect(forward[0]?.fix).toBeUndefined();
+    expect(forward[0]?.attributes).not.toHaveProperty("propMapping");
+  });
+  it.each(["@acme/first", "@acme/second"])(
+    "recognizes the exact approved import %s in either catalog order",
+    (imported) => {
+      expect(scan({ sourceQualified: true, imported })).toEqual([]);
+      expect(scan({ sourceQualified: true, imported, reverse: true })).toEqual([]);
+    }
+  );
+  function barrelScan(source: string, imported: string) {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "error",
+            options: {
+              sourceIdentitySchema: "component-source:v1",
+              canonicalMappings: ["first", "second"].map((folder) => ({
+                name: "Button",
+                canonical: "Button",
+                htmlEquivalent: "button",
+                importPath: `@acme/${folder}`,
+                source: { kind: "repository", path: `${folder}/Button.tsx`, symbol: "Button" },
+                exportAddresses: [
+                  { kind: "package", importPath: "@acme/public", exportName: `${folder}Button` },
+                ],
+              })),
+            },
+          },
+        },
+      })
+    );
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: "0",
+        element: "Button",
+        location: { file: "src/App.tsx", line: 1, column: 1 },
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/App.tsx",
+        local: "Button",
+        imported,
+        source,
+        location: { file: "src/App.tsx", line: 1, column: 1 },
+      })
+    );
+    return ruleComponentsPreferLibrary(ix);
+  }
+  it("recognizes a proven barrel export independently of its implementation symbol", () => {
+    expect(barrelScan("@acme/public", "secondButton")).toEqual([]);
+  });
+  it("does not authorize the definition symbol at an unproven package address", () => {
+    expect(barrelScan("@acme/second", "Button")[0]?.attributes?.ambiguousCanonicalTarget).toBe(
+      true
+    );
+  });
+  it("suggests the actual proven public export name while preserving the component identity", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "error",
+            options: {
+              sourceIdentitySchema: "component-source:v1",
+              canonicalMappings: [
+                {
+                  name: "Button",
+                  canonical: "Button",
+                  htmlEquivalent: "button",
+                  importPath: "@acme/unproven",
+                  source: { kind: "repository", path: "src/Button.tsx", symbol: "Button" },
+                  exportAddresses: [
+                    { kind: "package", importPath: "@acme/public", exportName: "PublicButton" },
+                  ],
+                },
+              ],
+            },
+          },
+        },
+      })
+    );
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: "0",
+        element: "button",
+        location: { file: "src/App.tsx", line: 1, column: 1 },
+      })
+    );
+    expect(ruleComponentsPreferLibrary(ix)[0]?.attributes).toMatchObject({
+      suggestedComponent: "PublicButton",
+      suggestedImport: "@acme/public",
+    });
+  });
+  it("does not fabricate a JSX replacement when one source has several public aliases", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "error",
+            options: {
+              sourceIdentitySchema: "component-source:v1",
+              canonicalMappings: [
+                {
+                  name: "Button",
+                  canonical: "Button",
+                  htmlEquivalent: "button",
+                  source: { kind: "repository", path: "src/Button.tsx", symbol: "Button" },
+                  exportAddresses: ["PrimaryButton", "SecondaryButton"].map((exportName) => ({
+                    kind: "package",
+                    importPath: "@acme/public",
+                    exportName,
+                  })),
+                },
+              ],
+            },
+          },
+        },
+      })
+    );
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: "0",
+        element: "button",
+        location: { file: "src/App.tsx", line: 1, column: 1 },
+      })
+    );
+    const finding = ruleComponentsPreferLibrary(ix)[0];
+    expect(finding?.attributes?.unresolvedCanonicalExport).toBe(true);
+    expect(finding?.fix).toBeUndefined();
+    expect(finding?.attributes).not.toHaveProperty("suggestedComponent");
+    expect(finding?.attributes).not.toHaveProperty("propMapping");
+  });
+  it("keeps role-only unresolved export guidance advisory", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "error",
+            options: {
+              sourceIdentitySchema: "component-source:v1",
+              canonicalMappings: [
+                {
+                  name: "Toast",
+                  canonical: "Toast",
+                  ariaRole: "status",
+                  source: { kind: "repository", path: "src/Toast.tsx", symbol: "Toast" },
+                  exportAddresses: [],
+                },
+              ],
+            },
+          },
+        },
+      })
+    );
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: "0",
+        element: "div",
+        role: "status",
+        location: { file: "src/App.tsx", line: 1, column: 1 },
+      })
+    );
+    const finding = ruleComponentsPreferLibrary(ix)[0];
+    expect(finding?.severity).toBe("moderate");
+    expect(finding?.attributes).toMatchObject({
+      unresolvedCanonicalExport: true,
+      advisory: true,
+      precisionTier: "role-reimpl",
+    });
+    expect(finding?.fix).toBeUndefined();
+  });
+});