@usefragments/core 2.0.1 → 2.1.0

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