@usefragments/core 1.5.2 → 1.7.0

package/dist/react-types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode, JSX } from 'react';
-export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-pKrfh517.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-D9KtH-vg.js';
 import 'zod';
 import './topology/index.js';
 import './types-xJ2xyp_G.js';

package/dist/registry.d.ts

@@ -52,15 +52,15 @@ declare const registryFileContentSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     path: string;
     size: number;
+    content: string;
     contentType: string;
     sha256: string;
-    content: string;
 }, {
     path: string;
     size: number;
+    content: string;
     contentType: string;
     sha256: string;
-    content: string;
 }>;
 declare const registrySourceSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     kind: z.ZodLiteral<"package">;
@@ -216,7 +216,7 @@ declare const registryComponentSchema: z.ZodObject<{
     componentId: string;
     name: string;
     publicRef: string;
-    tier: "core" | "custom" | "utility" | "composition";
+    tier: "custom" | "utility" | "composition" | "core";
     examples: unknown[];
     files: {
         path: string;
@@ -264,7 +264,7 @@ declare const registryComponentSchema: z.ZodObject<{
     provenance?: Record<string, unknown> | undefined;
     category?: string | undefined;
     contract?: unknown;
-    tier?: "core" | "custom" | "utility" | "composition" | undefined;
+    tier?: "custom" | "utility" | "composition" | "core" | undefined;
     examples?: unknown[] | undefined;
     styleFiles?: string[] | undefined;
     tokenDependencies?: string[] | undefined;
@@ -498,7 +498,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "core" | "custom" | "utility" | "composition";
+        tier: "custom" | "utility" | "composition" | "core";
         examples: unknown[];
         files: {
             path: string;
@@ -546,7 +546,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "core" | "custom" | "utility" | "composition" | undefined;
+        tier?: "custom" | "utility" | "composition" | "core" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -611,7 +611,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "core" | "custom" | "utility" | "composition";
+        tier: "custom" | "utility" | "composition" | "core";
         examples: unknown[];
         files: {
             path: string;
@@ -667,8 +667,8 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         label: string;
     };
     version: string;
-    channel: string;
     generatedAt: string;
+    channel: string;
     packageFiles: {
         path: string;
         size: number;
@@ -713,7 +713,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "core" | "custom" | "utility" | "composition" | undefined;
+        tier?: "custom" | "utility" | "composition" | "core" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -759,8 +759,8 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         label: string;
     };
     version: string;
-    channel: string;
     generatedAt: string;
+    channel: string;
     fcid?: string | undefined;
     contractVersionId?: string | undefined;
     packageFiles?: {
@@ -971,7 +971,7 @@ declare const registryManifestSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "core" | "custom" | "utility" | "composition";
+        tier: "custom" | "utility" | "composition" | "core";
         examples: unknown[];
         files: {
             path: string;
@@ -1019,7 +1019,7 @@ declare const registryManifestSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "core" | "custom" | "utility" | "composition" | undefined;
+        tier?: "custom" | "utility" | "composition" | "core" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -1086,7 +1086,7 @@ declare const registryManifestSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "core" | "custom" | "utility" | "composition";
+        tier: "custom" | "utility" | "composition" | "core";
         examples: unknown[];
         files: {
             path: string;
@@ -1143,8 +1143,8 @@ declare const registryManifestSchema: z.ZodObject<{
         label: string;
     };
     version: string;
-    channel: string;
     generatedAt: string;
+    channel: string;
     packageFiles: {
         path: string;
         size: number;
@@ -1189,7 +1189,7 @@ declare const registryManifestSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "core" | "custom" | "utility" | "composition" | undefined;
+        tier?: "custom" | "utility" | "composition" | "core" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -1236,8 +1236,8 @@ declare const registryManifestSchema: z.ZodObject<{
         label: string;
     };
     version: string;
-    channel: string;
     generatedAt: string;
+    channel: string;
     fcid?: string | undefined;
     contractVersionId?: string | undefined;
     packageFiles?: {
@@ -1450,7 +1450,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "core" | "custom" | "utility" | "composition";
+            tier: "custom" | "utility" | "composition" | "core";
             examples: unknown[];
             files: {
                 path: string;
@@ -1498,7 +1498,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "core" | "custom" | "utility" | "composition" | undefined;
+            tier?: "custom" | "utility" | "composition" | "core" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1565,7 +1565,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "core" | "custom" | "utility" | "composition";
+            tier: "custom" | "utility" | "composition" | "core";
             examples: unknown[];
             files: {
                 path: string;
@@ -1622,8 +1622,8 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             label: string;
         };
         version: string;
-        channel: string;
         generatedAt: string;
+        channel: string;
         packageFiles: {
             path: string;
             size: number;
@@ -1668,7 +1668,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "core" | "custom" | "utility" | "composition" | undefined;
+            tier?: "custom" | "utility" | "composition" | "core" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1715,8 +1715,8 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             label: string;
         };
         version: string;
-        channel: string;
         generatedAt: string;
+        channel: string;
         fcid?: string | undefined;
         contractVersionId?: string | undefined;
         packageFiles?: {
@@ -1754,15 +1754,15 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         path: string;
         size: number;
+        content: string;
         contentType: string;
         sha256: string;
-        content: string;
     }, {
         path: string;
         size: number;
+        content: string;
         contentType: string;
         sha256: string;
-        content: string;
     }>>;
 }, "strip", z.ZodTypeAny, {
     schemaVersion: "fragments.registry-artifact.v1";
@@ -1773,7 +1773,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "core" | "custom" | "utility" | "composition";
+            tier: "custom" | "utility" | "composition" | "core";
             examples: unknown[];
             files: {
                 path: string;
@@ -1830,8 +1830,8 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             label: string;
         };
         version: string;
-        channel: string;
         generatedAt: string;
+        channel: string;
         packageFiles: {
             path: string;
             size: number;
@@ -1863,9 +1863,9 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
     files: Record<string, {
         path: string;
         size: number;
+        content: string;
         contentType: string;
         sha256: string;
-        content: string;
     }>;
 }, {
     schemaVersion: "fragments.registry-artifact.v1";
@@ -1886,7 +1886,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "core" | "custom" | "utility" | "composition" | undefined;
+            tier?: "custom" | "utility" | "composition" | "core" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1933,8 +1933,8 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             label: string;
         };
         version: string;
-        channel: string;
         generatedAt: string;
+        channel: string;
         fcid?: string | undefined;
         contractVersionId?: string | undefined;
         packageFiles?: {
@@ -1966,9 +1966,9 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
     files: Record<string, {
         path: string;
         size: number;
+        content: string;
         contentType: string;
         sha256: string;
-        content: string;
     }>;
 }>, {
     schemaVersion: "fragments.registry-artifact.v1";
@@ -1979,7 +1979,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "core" | "custom" | "utility" | "composition";
+            tier: "custom" | "utility" | "composition" | "core";
             examples: unknown[];
             files: {
                 path: string;
@@ -2036,8 +2036,8 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             label: string;
         };
         version: string;
-        channel: string;
         generatedAt: string;
+        channel: string;
         packageFiles: {
             path: string;
             size: number;
@@ -2069,9 +2069,9 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
     files: Record<string, {
         path: string;
         size: number;
+        content: string;
         contentType: string;
         sha256: string;
-        content: string;
     }>;
 }, {
     schemaVersion: "fragments.registry-artifact.v1";
@@ -2092,7 +2092,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "core" | "custom" | "utility" | "composition" | undefined;
+            tier?: "custom" | "utility" | "composition" | "core" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -2139,8 +2139,8 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             label: string;
         };
         version: string;
-        channel: string;
         generatedAt: string;
+        channel: string;
         fcid?: string | undefined;
         contractVersionId?: string | undefined;
         packageFiles?: {
@@ -2172,9 +2172,9 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
     files: Record<string, {
         path: string;
         size: number;
+        content: string;
         contentType: string;
         sha256: string;
-        content: string;
     }>;
 }>;
 declare const registryInstallReceiptFileSchema: z.ZodObject<{

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-DbkPE46t.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-hZAlYCli.js';

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-pKrfh517.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-D9KtH-vg.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.5.2",
+  "version": "1.7.0",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",
@@ -112,6 +112,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "check:browser-types": "tsc -p test-fixtures/browser-consumer/tsconfig.json",
     "dev": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",

package/src/__tests__/policy-exclude.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  describePolicyExclude,
+  detectUnmatchedPolicyExcludes,
+  governanceConfigSchema,
+  matchPolicyExclude,
+  normalizePolicyExcludes,
+  type GovernanceConfig,
+} from "../index.js";
+
+describe("policy exclude normalization", () => {
+  it("accepts bare globs and { glob, reason } records alike", () => {
+    expect(
+      normalizePolicyExcludes([
+        "src/legacy/**",
+        { glob: "vendor/**", reason: "vendor drop, tracked in DS-611" },
+      ])
+    ).toEqual([
+      { glob: "src/legacy/**" },
+      { glob: "vendor/**", reason: "vendor drop, tracked in DS-611" },
+    ]);
+  });
+
+  it("returns undefined when nothing usable is authored", () => {
+    expect(normalizePolicyExcludes(undefined)).toBeUndefined();
+    expect(normalizePolicyExcludes([])).toBeUndefined();
+    expect(normalizePolicyExcludes(["", { reason: "no glob" }, 7])).toBeUndefined();
+  });
+
+  it("matches `**` across segments and `*` within one", () => {
+    const excludes = normalizePolicyExcludes(["src/legacy/vendor/**", "src/*.tsx"]);
+
+    expect(matchPolicyExclude(excludes, "src/legacy/vendor/deep/Widget.tsx")).toEqual({
+      glob: "src/legacy/vendor/**",
+    });
+    expect(matchPolicyExclude(excludes, "./src/App.tsx")).toEqual({ glob: "src/*.tsx" });
+    expect(matchPolicyExclude(excludes, "src\\App.tsx")).toEqual({ glob: "src/*.tsx" });
+    expect(matchPolicyExclude(excludes, "src/nested/App.tsx")).toBeUndefined();
+    expect(matchPolicyExclude(undefined, "src/App.tsx")).toBeUndefined();
+  });
+
+  it("describes an exclusion with its scope, glob, and reason", () => {
+    expect(
+      describePolicyExclude("style.rawColors.forbid", {
+        glob: "vendor/**",
+        reason: "vendor drop",
+      })
+    ).toBe("style.rawColors.forbid exclude matched vendor/** — vendor drop");
+    expect(describePolicyExclude("styles/no-raw-color", { glob: "vendor/**" })).toBe(
+      "styles/no-raw-color exclude matched vendor/**"
+    );
+  });
+});
+
+describe("global record excludes compile onto policy facts", () => {
+  const policy: GovernanceConfig = {
+    styles: [
+      {
+        kind: "style.rawColors.forbid",
+        except: [],
+        prefer: "token",
+        severity: "warn",
+        exclude: [{ glob: "src/legacy/vendor/**", reason: "vendor drop" }],
+      },
+    ],
+    jsx: [
+      {
+        kind: "jsx.importPath.prefer",
+        from: "@mui/material",
+        to: "@/components",
+        severity: "warn",
+        exclude: ["src/legacy/vendor/**"],
+      },
+    ],
+  };
+
+  it("is accepted by the shipped schema", () => {
+    expect(() => governanceConfigSchema.parse(policy)).not.toThrow();
+  });
+
+  it("threads the normalized excludes onto the compiled facts", () => {
+    const facts = compileGlobalGovernanceFacts(policy);
+    const color = facts.find((fact) => fact.kind === "style_raw_color_forbidden");
+    const importPath = facts.find((fact) => fact.kind === "jsx_import_path_preferred");
+
+    expect(color).toMatchObject({
+      exclude: [{ glob: "src/legacy/vendor/**", reason: "vendor drop" }],
+    });
+    expect(importPath).toMatchObject({ exclude: [{ glob: "src/legacy/vendor/**" }] });
+  });
+
+  it("keeps a user exclude alive when a preset record shares the same fact id", () => {
+    // A resolved policy is `[...presetRecords, ...userRecords]`, and the singleton style
+    // kinds are content-addressed on kind alone — so only one of the two survives
+    // indexing. The user's exemption must not be the casualty.
+    const facts = compileGlobalGovernanceFacts({
+      styles: [
+        { kind: "style.rawColors.forbid", except: [], prefer: "token", severity: "warn" },
+        {
+          kind: "style.rawColors.forbid",
+          except: [],
+          prefer: "token",
+          severity: "warn",
+          exclude: ["src/legacy/vendor/**"],
+        },
+      ],
+    });
+
+    const colorFacts = facts.filter((fact) => fact.kind === "style_raw_color_forbidden");
+    expect(colorFacts).toHaveLength(2);
+    // Both copies carry the union, so whichever the index keeps is the armed one.
+    for (const fact of colorFacts) {
+      expect(fact).toMatchObject({ exclude: [{ glob: "src/legacy/vendor/**" }] });
+    }
+  });
+
+  it("leaves fact identity untouched so fingerprints do not move", () => {
+    const withExclude = compileGlobalGovernanceFacts(policy);
+    const withoutExclude = compileGlobalGovernanceFacts({
+      styles: [{ kind: "style.rawColors.forbid", except: [], prefer: "token", severity: "warn" }],
+      jsx: [
+        {
+          kind: "jsx.importPath.prefer",
+          from: "@mui/material",
+          to: "@/components",
+          severity: "warn",
+        },
+      ],
+    });
+
+    expect(withExclude.map((fact) => fact.id)).toEqual(withoutExclude.map((fact) => fact.id));
+    // …and a policy with no excludes stays byte-identical to the pre-1.6.0 shape.
+    expect(withoutExclude.every((fact) => !("exclude" in fact))).toBe(true);
+  });
+});
+
+describe("detectUnmatchedPolicyExcludes", () => {
+  const policy: GovernanceConfig = {
+    styles: [
+      {
+        kind: "style.rawColors.forbid",
+        except: [],
+        prefer: "token",
+        severity: "warn",
+        exclude: ["src/legacy/vendor/**"],
+      },
+    ],
+    rules: { "styles/no-raw-spacing": { exclude: ["src/deleted-area/**"] } },
+  };
+
+  it("stays silent when every glob covers a scanned file", () => {
+    expect(
+      detectUnmatchedPolicyExcludes(policy, [
+        "src/legacy/vendor/Widget.tsx",
+        "src/deleted-area/Old.tsx",
+      ])
+    ).toEqual([]);
+  });
+
+  it("names each glob that scoped nothing, on both authoring routes", () => {
+    const diagnostics = detectUnmatchedPolicyExcludes(policy, ["src/App.tsx"]);
+
+    expect(diagnostics).toMatchObject([
+      {
+        code: "FUI9006",
+        kind: "unmatched-exclude",
+        path: "govern.rules.styles/no-raw-spacing.exclude",
+      },
+      { code: "FUI9006", kind: "unmatched-exclude", path: "govern.styles[0].exclude" },
+    ]);
+    expect(diagnostics[0]?.message).toContain("src/deleted-area/**");
+    expect(diagnostics[1]?.message).toContain("style.rawColors.forbid");
+  });
+
+  it("does not flag excludes when nothing was scanned at all", () => {
+    expect(detectUnmatchedPolicyExcludes(policy, [])).toEqual([]);
+  });
+});

package/src/agent-format.test.ts

@@ -136,6 +136,19 @@ describe("buildAgentFormat", () => {
     });
   });
 
+  it("distinguishes affected files from all scanned files in the summary", () => {
+    const agentFormat = buildAgentFormat({
+      filesScanned: 7,
+      findings: [
+        finding({ fingerprint: "fp_1" }),
+        finding({ fingerprint: "fp_2", location: { file: "src/Button.tsx", line: 2, column: 1 } }),
+      ],
+      integrity: HEALTHY_INTEGRITY,
+    });
+
+    expect(agentFormat.summary).toBe("2 findings in 1 file; 7 scanned; score 67");
+  });
+
   it("marks an inert zero-rule scan indeterminate without inventing a score", () => {
     const agentFormat = buildAgentFormat({
       filesScanned: 1,

package/src/agent-format.ts

@@ -22,6 +22,7 @@ export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
   const zeroRulesLoaded = input.integrity.rulesLoaded === 0;
   const integrityFailed = !input.integrity.healthy || input.integrity.inert;
   const score = integrityFailed ? 0 : scoreFindings(input.findings);
+  const filesAffected = new Set(input.findings.map((finding) => finding.location.file)).size;
   const visibleFindings = uniqueFindings(input.findings).slice(0, input.maxFindings ?? 50);
   const agentFindings = visibleFindings.map((finding) => ({
     code: finding.code,
@@ -48,7 +49,7 @@ export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
       ? "indeterminate; zero_rules_loaded"
       : integrityFailed
         ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}`
-        : agentSummary(input.findings.length, input.filesScanned, score),
+        : agentSummary(input.findings.length, filesAffected, input.filesScanned, score),
     integrity: input.integrity,
     fix_first: agentFindings.filter((finding) => finding.plan.confidence >= 0.8),
     remaining: agentFindings.filter((finding) => finding.plan.confidence < 0.8),
@@ -119,9 +120,14 @@ function scoreFindings(findings: readonly Finding[]): number {
   return Math.max(1, Math.round(100 / (1 + penalty / 40)));
 }
 
-function agentSummary(count: number, filesScanned: number, score: number): string {
+function agentSummary(
+  count: number,
+  filesAffected: number,
+  filesScanned: number,
+  score: number
+): string {
   if (count === 0) return `passed with score ${score}; no findings`;
-  return `${count} finding${count === 1 ? "" : "s"} across ${filesScanned} file${filesScanned === 1 ? "" : "s"}; score ${score}`;
+  return `${count} finding${count === 1 ? "" : "s"} in ${filesAffected} file${filesAffected === 1 ? "" : "s"}; ${filesScanned} scanned; score ${score}`;
 }
 
 function planForFinding(finding: Finding): AgentFormat["fix_first"][number]["plan"] {