@usefragments/core 1.8.0 → 1.9.0

package/dist/schemas/index.d.ts

@@ -1,3 +1,3 @@
 import 'zod';
 export { LegacySeverityLevel, Severity, SeverityLevel, legacySeverityLevelSchema, severityLevelSchema, severitySchema } from '../severity.js';
-export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-Cxk3SOQP.js';
+export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-DtHxs0Pf.js';

package/dist/schemas/index.js

@@ -24,7 +24,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-UUREQ4HD.js";
+} from "../chunk-DGHZQTLH.js";
 import "../chunk-JNBFJ34I.js";
 import "../chunk-EIYNNS77.js";
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

package/src/rules/finding.ts

@@ -28,17 +28,38 @@ export interface MakeFindingInput {
   evidence: FactEvidence[];
   evidenceGrade?: EvidenceGrade;
   fingerprintIdentity: Record<string, unknown>;
+  /**
+   * Legacy identity tuple from before a fingerprint migration. When present,
+   * the finding also carries `previousFingerprint` (the legacy hash) so
+   * baseline classification can match records keyed on the old hash during
+   * the grace window. Position keys are permitted here — legacy identities
+   * are reproduced verbatim, contract violations included.
+   */
+  previousFingerprintIdentity?: Record<string, unknown>;
   fix?: FindingFix;
   attributes?: Record<string, unknown>;
 }
 
+const POSITION_IDENTITY_KEYS = ["line", "column", "endLine", "endColumn", "offset", "location"];
+
 export function makeFinding(input: MakeFindingInput): Finding {
   if (input.evidence.length === 0) {
     throw new Error(`makeFinding(${input.ruleId}): findings must carry at least one evidence fact`);
   }
+  const positionKeys = POSITION_IDENTITY_KEYS.filter((key) => key in input.fingerprintIdentity);
+  if (positionKeys.length > 0) {
+    throw new Error(
+      `makeFinding(${input.ruleId}): fingerprintIdentity must not contain position keys ` +
+        `(${positionKeys.join(", ")}) — fingerprints hash what's wrong, never where it sits. ` +
+        `Use a source-order occurrence index for repeats of the same identity.`
+    );
+  }
   const fingerprint = hash64Hex(
     canonicalJson({ ruleId: input.ruleId, ...input.fingerprintIdentity })
   );
+  const previousFingerprint = input.previousFingerprintIdentity
+    ? hash64Hex(canonicalJson({ ruleId: input.ruleId, ...input.previousFingerprintIdentity }))
+    : undefined;
   const code = byRuleId.get(input.ruleId);
   return normalizeFinding({
     ruleId: input.ruleId,
@@ -48,6 +69,7 @@ export function makeFinding(input: MakeFindingInput): Finding {
     helpUrl: code?.explainUrl,
     message: input.message,
     fingerprint,
+    ...(previousFingerprint !== undefined ? { previousFingerprint } : {}),
     location: input.location,
     evidence: input.evidence,
     evidenceGrade: input.evidenceGrade ?? "source_backed",

package/src/rules/jsx-preferred-import-path.ts

@@ -13,6 +13,12 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
 
   const findings: Finding[] = [];
   const seen = new Set<string>();
+  // Source-order occurrence index per identity tuple: the fingerprint contract
+  // (finding.ts) forbids position, so repeats of the same offending import in
+  // one file are distinguished by ordinal, not line/column. Deleting the first
+  // occurrence promotes the second to its index — debt count stays truthful
+  // while edits elsewhere in the file cannot re-key anything.
+  const occurrences = new Map<string, number>();
 
   for (const usage of ix.byKind("usage_import")) {
     // A confirmed bridge supersedes any non-bridge preference over the same
@@ -41,6 +47,9 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
       const key = `${policy.id}\0${usage.file}\0${usage.source}\0${usage.location.line}\0${usage.location.column}\0${importedIdentity}`;
       if (seen.has(key)) continue;
       seen.add(key);
+      const identityKey = `${usage.file}\0${usage.source}\0${policy.to}\0${importedIdentity}`;
+      const occurrence = occurrences.get(identityKey) ?? 0;
+      occurrences.set(identityKey, occurrence + 1);
 
       findings.push(
         makeFinding({
@@ -53,6 +62,15 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
           location: usage.location,
           evidence: ix.evidence([usage.id, policy.id]),
           fingerprintIdentity: {
+            file: usage.file,
+            from: usage.source,
+            to: policy.to,
+            imported: policy.imported,
+            occurrence,
+          },
+          // Grace window (baseline v1 → v2): the pre-migration hash keyed on
+          // line/column. Drop with the v1 dual-match after one release.
+          previousFingerprintIdentity: {
             file: usage.file,
             from: usage.source,
             to: policy.to,

package/src/rules/rules.test.ts

@@ -37,6 +37,7 @@ import {
 } from "../index.js";
 import type { CanonicalBridgeV1, Fact, FactId } from "../index.js";
 import { RULE_VERSION as A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION } from "./a11y-required-accessible-name.js";
+import { makeFinding } from "./finding.js";
 
 type ButtonProps = {
   variant?: "primary" | "secondary" | "ghost" | "link";
@@ -438,6 +439,78 @@ describe("preferred JSX imports and components", () => {
     });
   });
 
+  it("keeps preferred-path fingerprints stable across line drift", () => {
+    const findingsAtLine = (line: number) => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@legacy/ui", "@usefragments/ui", { severity: "error" })],
+        })
+      );
+      ix.add(
+        makeUsageImportFact({
+          file: "apps/checkout/page.tsx",
+          local: "Button",
+          imported: "Button",
+          source: "@legacy/ui",
+          location: { file: "apps/checkout/page.tsx", line, column: 0 },
+        })
+      );
+      return ruleJsxPreferredImportPath(ix);
+    };
+
+    const before = findingsAtLine(1);
+    const after = findingsAtLine(9);
+
+    expect(after[0].fingerprint).toBe(before[0].fingerprint);
+    // Byte-pinned hashes: the legacy value is what a released v1 CLI recorded
+    // for this exact tuple (hash64Hex(canonicalJson({ruleId, file, from, to,
+    // line, column}))). If previousFingerprintIdentity ever drifts from the
+    // true v1 formula, real baselines mass-invalidate — this literal is the
+    // tripwire.
+    expect(before[0].fingerprint).toBe("4deee0ff7bb1810b");
+    expect(before[0].previousFingerprint).toBe("c04344ad7a96b651");
+    // The grace-window legacy hash still tracks position, so a v1 baseline
+    // recorded at either line matches exactly one of the two runs.
+    expect(after[0].previousFingerprint).not.toBe(before[0].previousFingerprint);
+  });
+
+  it("distinguishes repeated same-identity imports by source-order occurrence", () => {
+    // Two imports of the same specifier under different local aliases share the
+    // fingerprint identity tuple (local never enters the hash) — the ordinal
+    // tells them apart. Byte-identical duplicates collapse at the fact layer.
+    const findingsFor = (locals: readonly string[]) => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@legacy/ui", "@usefragments/ui", { severity: "error" })],
+        })
+      );
+      locals.forEach((local, index) => {
+        ix.add(
+          makeUsageImportFact({
+            file: "apps/checkout/page.tsx",
+            local,
+            imported: "Button",
+            source: "@legacy/ui",
+            location: { file: "apps/checkout/page.tsx", line: index * 10 + 1, column: 0 },
+          })
+        );
+      });
+      return ruleJsxPreferredImportPath(ix);
+    };
+
+    const both = findingsFor(["Button", "AliasedButton"]);
+    expect(both).toHaveLength(2);
+    expect(both[0].fingerprint).not.toBe(both[1].fingerprint);
+
+    // Deleting the first occurrence promotes the survivor to its ordinal, so
+    // the remaining debt matches a fingerprint the baseline already accepts.
+    const survivor = findingsFor(["AliasedButton"]);
+    expect(survivor).toHaveLength(1);
+    expect(survivor[0].fingerprint).toBe(both[0].fingerprint);
+  });
+
   it("emits a deterministic component replacement for canonical component mappings", () => {
     const legacyButtonId = makeComponentId("@legacy/ui", "LegacyButton");
     const ix = new FactIndex();
@@ -4163,6 +4236,47 @@ describe("styles/no-raw-dimensions", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// makeFinding fingerprint contract
+// ---------------------------------------------------------------------------
+
+describe("makeFinding fingerprint contract", () => {
+  const base = {
+    ruleId: "styles/no-raw-color",
+    ruleVersion: "1",
+    severity: "serious" as const,
+    message: "Raw color",
+    location: { file: "src/App.tsx", line: 3, column: 1 },
+    evidence: [{ factId: "fact-1" as FactId, fact: { kind: "style_declaration" } }],
+  };
+
+  it("rejects position keys in fingerprintIdentity", () => {
+    expect(() =>
+      makeFinding({
+        ...base,
+        fingerprintIdentity: { file: "src/App.tsx", value: "#fff", line: 3, column: 1 },
+      })
+    ).toThrow(/position keys \(line, column\)/);
+  });
+
+  it("hashes a legacy identity into previousFingerprint when provided", () => {
+    const migrated = makeFinding({
+      ...base,
+      fingerprintIdentity: { file: "src/App.tsx", value: "#fff", occurrence: 0 },
+      previousFingerprintIdentity: { file: "src/App.tsx", value: "#fff", line: 3, column: 1 },
+    });
+    const plain = makeFinding({
+      ...base,
+      fingerprintIdentity: { file: "src/App.tsx", value: "#fff", occurrence: 0 },
+    });
+
+    expect(migrated.fingerprint).toBe(plain.fingerprint);
+    expect(migrated.previousFingerprint).toBeDefined();
+    expect(migrated.previousFingerprint).not.toBe(migrated.fingerprint);
+    expect(plain.previousFingerprint).toBeUndefined();
+  });
+});
+
 // Type witness so eslint/tsc don't trip on unused imports above.
 const _typeWitness: Fact[] = [];
 void _typeWitness;

package/src/schemas/index.ts

@@ -116,6 +116,12 @@ export const findingSchema = z.object({
   helpUrl: z.string().url().optional(),
   message: z.string(),
   fingerprint: z.string(),
+  /**
+   * Fingerprint this finding carried before a fingerprint-identity migration.
+   * Emitted only by migrated rules during the grace window so baseline
+   * records keyed on the legacy hash keep matching instead of churning.
+   */
+  previousFingerprint: z.string().optional(),
   location: factLocationSchema,
   evidence: z.array(factEvidenceSchema).min(1),
   evidenceGrade: evidenceGradeSchema.optional(),