@usefragments/core 1.0.0 → 1.2.0

package/src/rules/rules.test.ts

@@ -1775,7 +1775,7 @@ describe("components/prefer-library", () => {
     expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
   });
 
-  it("flags imported bespoke components when package canonical sources include the exported component", () => {
+  it("keeps same-name local import redirects advisory without a verified source contract", () => {
     const ix = new FactIndex();
     ix.addMany(
       compileGlobalGovernanceFacts({
@@ -1812,13 +1812,57 @@ describe("components/prefer-library", () => {
     expect(findings[0]).toMatchObject({
       ruleId: "components/prefer-library",
       code: "FUI1004",
+      fix: {
+        kind: "replaceImport",
+        from: "../components/Card",
+        to: "@acme/ui",
+        deterministic: false,
+      },
       attributes: {
         suggestedComponent: "Card",
         suggestedImport: "@acme/ui",
+        advisory: true,
+        contractProof: "missing",
       },
     });
   });
 
+  it("does not mistake TanStack Router Link for the canonical Link by name alone", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "error",
+            options: {
+              canonicalSources: [{ kind: "npm", specifier: "@acme/ui", include: ["Link"] }],
+            },
+          },
+        },
+      })
+    );
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/app.tsx",
+        nodePath: "0:0",
+        element: "Link",
+        location: { file: "src/app.tsx", line: 5, column: 4 },
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app.tsx",
+        local: "Link",
+        imported: "Link",
+        source: "@tanstack/react-router",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
   it("recognizes a current import through legacy npm source and mapping spellings", () => {
     const ix = new FactIndex();
     ix.addMany(
@@ -2159,7 +2203,7 @@ describe("components/prefer-library", () => {
     expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
   });
 
-  it("attaches a deterministic component fix from confirmed canonical mappings", () => {
+  it("keeps a complete mapped replacement guided until the conform AST preflight", () => {
     const ix = new FactIndex();
     ix.addMany(
       compileGlobalGovernanceFacts({
@@ -2183,6 +2227,15 @@ describe("components/prefer-library", () => {
         },
       })
     );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "@acme/ui",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
     ix.add(
       makeUsageNodeFact({
         file: "src/app.tsx",
@@ -2200,14 +2253,102 @@ describe("components/prefer-library", () => {
         kind: "replaceComponent",
         from: "button",
         to: "Button",
-        deterministic: true,
+        deterministic: false,
       },
       attributes: {
         suggestedComponent: "Button",
         suggestedImport: "@acme/ui",
         propMapping: [{ rawProp: "className", canonicalProp: "variant" }],
+        propCompatibility: "observed-complete",
       },
     });
+    expect(findings[0].attributes).not.toHaveProperty("canonicalMappingConfirmed");
+  });
+
+  it("withholds a native-element fix when a native-only prop has no confirmed mapping", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              canonicalMappings: [
+                {
+                  name: "Button",
+                  canonical: "Button",
+                  htmlEquivalent: "button",
+                  importPath: "@acme/ui",
+                },
+              ],
+            },
+          },
+        },
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "@acme/ui",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
+    addRawNode(ix, {
+      element: "button",
+      nodePath: "0:0",
+      props: [{ prop: "formAction", value: "/save" }],
+    });
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      fix: { kind: "replaceComponent", deterministic: false },
+      attributes: {
+        propCompatibility: "incomplete",
+        unprovenProps: ["formAction"],
+      },
+    });
+  });
+
+  it("keeps replacement metadata but marks it non-deterministic when its import is absent", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              canonicalMappings: [
+                {
+                  name: "Button",
+                  canonical: "Button",
+                  htmlEquivalent: "button",
+                  importPath: "@acme/ui",
+                },
+              ],
+            },
+          },
+        },
+      })
+    );
+    addRawNode(ix, { element: "button", nodePath: "0:0", text: "Save" });
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].attributes).toMatchObject({
+      suggestedComponent: "Button",
+      suggestedImport: "@acme/ui",
+    });
+    expect(findings[0].fix).toMatchObject({
+      kind: "replaceComponent",
+      from: "button",
+      to: "Button",
+      deterministic: false,
+    });
   });
 
   it("does not flag generic <div>/<span> from an inferred component primitive (anti-flood)", () => {
@@ -2561,29 +2702,38 @@ describe("components/prefer-library", () => {
       expect(findings.filter((f) => f.attributes?.suggestedComponent === "Hint")).toHaveLength(0);
     });
 
-    it("STILL fires the legit name-based import-redirect (<Modal> from wrong path → import @acme/ui)", () => {
+    it("STILL fires the legit local name-based import redirect (<Modal> → import @acme/ui)", () => {
       // Regression guard: removing the canonical selector must not kill the
       // real name-match import-redirect. <Modal> (the component's own name)
       // imported from the wrong path is genuine drift.
       const findings = importedFindings(
         [{ name: "Modal", canonical: "Dialog", importPath: "@acme/ui" }],
         "Modal",
-        "react-aria"
+        "../Modal"
       );
       expect(findings).toHaveLength(1);
       expect(findings[0].fix?.kind).toBe("replaceImport");
       expect(findings[0].attributes?.suggestedComponent).toBe("Modal");
     });
 
-    it("STILL fires when name === canonical (<Dialog> for name 'Dialog') from wrong path", () => {
+    it("STILL fires for a local import when name === canonical (<Dialog> for name 'Dialog')", () => {
       const findings = importedFindings(
         [{ name: "Dialog", canonical: "Dialog", importPath: "@acme/ui" }],
         "Dialog",
-        "react-aria"
+        "../Dialog"
       );
       expect(findings).toHaveLength(1);
       expect(findings[0].attributes?.suggestedComponent).toBe("Dialog");
     });
+
+    it("does not redirect a package-owned same-name Link without an explicit import policy", () => {
+      const findings = importedFindings(
+        [{ name: "Link", canonical: "Link", importPath: "@acme/ui" }],
+        "Link",
+        "@tanstack/react-router"
+      );
+      expect(findings).toHaveLength(0);
+    });
   });
 
   describe("directory canonical source (unfiltered include — dogfood shape)", () => {
@@ -2672,7 +2822,7 @@ describe("components/prefer-library", () => {
       expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
     });
 
-    it("flags raw <button> → Button when Button is a declared directory canonical", () => {
+    it("flags raw <button> → Button without advertising it as deterministic when Button is not imported", () => {
       const ix = new FactIndex();
       ix.addMany(
         compileGlobalGovernanceFacts({
@@ -2704,18 +2854,18 @@ describe("components/prefer-library", () => {
       expect(findings).toHaveLength(1);
       expect(findings[0]).toMatchObject({
         ruleId: "components/prefer-library",
-        fix: {
-          kind: "replaceComponent",
-          from: "button",
-          to: "Button",
-          deterministic: true,
-        },
         attributes: {
           rawValue: "button",
           suggestedComponent: "Button",
           suggestedImportSourceKind: "directory",
         },
       });
+      expect(findings[0].fix).toMatchObject({
+        kind: "replaceComponent",
+        from: "button",
+        to: "Button",
+        deterministic: false,
+      });
     });
 
     it("flags a raw element by canonical vocab id when display name diverges (Modal → Dialog)", () => {
@@ -2825,7 +2975,9 @@ describe("components/prefer-library", () => {
 
     const findings = ruleComponentsPreferLibrary(ix);
 
-    // type-specific mappings win over the generic tag-level one; text falls back
+    // Type-specific mappings win over the generic tag-level one; text falls
+    // back. No canonical bindings exist in this fixture, so suggestions remain
+    // useful but are not advertised as deterministic edits.
     expect(findings.map((finding) => finding.attributes?.suggestedComponent)).toEqual([
       "Checkbox",
       "RadioGroup",
@@ -2836,7 +2988,7 @@ describe("components/prefer-library", () => {
       "RadioGroup",
       "TextField",
     ]);
-    expect(findings.every((finding) => finding.fix?.deterministic === true)).toBe(true);
+    expect(findings.every((finding) => finding.fix?.deterministic === false)).toBe(true);
   });
 
   it("does not let a type-constrained mapping match a different or untyped input", () => {
@@ -2872,7 +3024,7 @@ describe("components/prefer-library", () => {
     expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
   });
 
-  it("attaches a deterministic import fix for canonical components from the wrong path", () => {
+  it("keeps a same-name local import redirect advisory without source-contract proof", () => {
     const ix = new FactIndex();
     ix.addMany(
       compileGlobalGovernanceFacts({
@@ -2918,9 +3070,10 @@ describe("components/prefer-library", () => {
         kind: "replaceImport",
         from: "../Button",
         to: "@acme/ui",
-        deterministic: true,
+        deterministic: false,
       },
       location: { line: 1, column: 0 },
+      attributes: { advisory: true, contractProof: "missing" },
     });
   });
 
@@ -2967,13 +3120,14 @@ describe("components/prefer-library", () => {
         suggestedComponent: "Alert",
         matchedRole: "status",
         confidence: 0.9,
+        advisory: true,
       },
     });
     // Role matches are advisory: no deterministic tag→component rewrite.
     expect(findings[0].fix).toBeUndefined();
   });
 
-  it("flags input type primitives config-free with deterministic fixes", () => {
+  it("flags input type primitives config-free without unsafe missing-import fixes", () => {
     const ix = preferLibraryIndex();
     addRawNode(ix, {
       element: "input",
@@ -3003,7 +3157,7 @@ describe("components/prefer-library", () => {
       "input-type",
       "input-type",
     ]);
-    expect(findings.map((finding) => finding.fix?.deterministic)).toEqual([true, true, true]);
+    expect(findings.every((finding) => finding.fix?.deterministic === false)).toBe(true);
   });
 
   it("does not infer generic text inputs as deterministic primitives", () => {
@@ -3093,7 +3247,7 @@ describe("components/prefer-library", () => {
       kind: "replaceComponent",
       from: "button",
       to: "Button",
-      deterministic: true,
+      deterministic: false,
     });
   });
 
@@ -3139,13 +3293,13 @@ describe("components/prefer-library", () => {
       kind: "replaceComponent",
       from: "button",
       to: "Button",
-      deterministic: true,
+      deterministic: false,
     });
     expect(findings[2].fix).toMatchObject({
       kind: "replaceComponent",
       from: "button",
       to: "Button",
-      deterministic: true,
+      deterministic: false,
     });
   });
 
@@ -3430,6 +3584,7 @@ describe("styles/no-raw-typography (BUG 10)", () => {
     );
     const findings = ruleStylesNoRawTypography(ix);
     expect(findings).toHaveLength(1);
+    expect(findings[0].code).toBe("FUI2016");
     expect(findings[0].fix).toMatchObject({
       value: "var(--font-size-md)",
       deterministic: true,

package/src/rules/taxonomy.test.ts

@@ -217,18 +217,21 @@ describe("§3 contract authored", () => {
     expect(ruleIds.every(isContractTierRule)).toBe(true);
   });
 
-  it("ranks canonical-component bypass first (vocabulary-first), with a directed fix", () => {
+  it("ranks canonical-component bypass first without claiming an unsafe missing-import fix", () => {
     const findings = runRules(withButtonText(contractIndex()));
     const ranked = findings.map((f) => f.ruleId).sort(compareByVocabularyRank);
     expect(ranked).toEqual(["components/prefer-library", "tokens/css-vars-must-be-defined"]);
 
     const canonical = findings.find((f) => f.ruleId === "components/prefer-library");
-    // "Replace your raw <button> with your <Button>" — a directed, deterministic fix.
+    // The direction is explicit, but this fixture has no Button binding. A
+    // generic source patcher cannot safely rename the element without also
+    // importing Button, so the replacement stays visible but is not advertised
+    // as deterministic.
     expect(canonical?.fix).toMatchObject({
       kind: "replaceComponent",
       from: "button",
       to: "Button",
-      deterministic: true,
+      deterministic: false,
     });
     expect(canonical?.attributes).toMatchObject({
       rawValue: "button",

package/src/rules/tiers.ts

@@ -27,7 +27,7 @@ export type RuleTier = "contract" | "hygiene";
  */
 export const RULE_TIER: Readonly<Record<string, RuleTier>> = {
   // ---- Tier A — contract vocabulary -------------------------------------
-  "components/prefer-library": "contract", // canonical-component bypass (FUI1001/1004)
+  "components/prefer-library": "contract", // canonical-component bypass (FUI1004)
   "tokens/css-vars-must-be-defined": "contract", // token drift (FUI2015)
 
   // ---- Tier B — generic hygiene -----------------------------------------

package/src/schemas/index.ts

@@ -228,11 +228,22 @@ export const agentFindingSchema = z.object({
   plan: agentPlanSchema,
 });
 
+export const AGENT_FORMAT_SCHEMA_VERSION = "typestyle.agent.v2" as const;
+
+export const agentIntegritySchema = z.object({
+  rulesLoaded: z.number().int().nonnegative(),
+  status: z.enum(["healthy", "degraded", "inert"]),
+  healthy: z.boolean(),
+  inert: z.boolean(),
+  reasons: z.array(z.string()),
+});
+
 export const agentFormatSchema = z.object({
-  schemaVersion: z.literal("typestyle.agent.v1"),
+  schemaVersion: z.literal(AGENT_FORMAT_SCHEMA_VERSION),
   passed: z.boolean(),
   score: z.number(),
   summary: z.string(),
+  integrity: agentIntegritySchema,
   fix_first: z.array(agentFindingSchema),
   remaining: z.array(agentFindingSchema),
   suppression_template: z.object({
@@ -250,6 +261,19 @@ export const agentFormatSchema = z.object({
 });
 export type AgentFormat = z.infer<typeof agentFormatSchema>;
 
+export const agentErrorEnvelopeSchema = z.object({
+  schemaVersion: z.literal(AGENT_FORMAT_SCHEMA_VERSION),
+  passed: z.literal(false),
+  error: z.object({
+    code: z.string().min(1),
+    message: z.string().min(1),
+  }),
+});
+export type AgentErrorEnvelope = z.infer<typeof agentErrorEnvelopeSchema>;
+
+export const agentOutputSchema = z.union([agentFormatSchema, agentErrorEnvelopeSchema]);
+export type AgentOutput = z.infer<typeof agentOutputSchema>;
+
 export function normalizeSeverity(severity: Severity | LegacySeverityLevel): Severity {
   return severitySchema.safeParse(severity).success
     ? (severity as Severity)