perf: bound indirect evidence after visual qualification

Author: Bill Leoutsakos

scripts/design-diff/README.md

@@ -206,7 +206,7 @@ JSON inputs are compared semantically, retaining array order and attributing cha
 the spec and configured renderer. Malformed/missing configured inputs flag with a limitation.
 
 The graph reuses up to 32,768 import/export snapshots keyed by source blob, resolving their
-paths again for each revision. The resolver retains at most 32 parsed modules per revision,
+paths again for each revision. Each consumer resolver retains at most 32 parsed modules,
 and requests Bun garbage collection between parser batches. These resource controls do
 not change evidence or decisions. The Node-based test runner uses its own garbage collector.
 
@@ -370,6 +370,14 @@ watchers distinguish changes to the forwarded export from unrelated declarations
 Custom props are exempt as event-only only when a resolved destructured prop is used exclusively
 to select JSX event handlers; the same rule applies inside nested JSX expressions. Unknown
 components and props with rendered uses keep conservative findings.
+Unchanged consumers are visited in dependency-distance order before source-path order, so a
+nearby visible use supplies the retained example before distant application plumbing when possible.
+The engine is a PR qualifier, not an exhaustive inventory of indirect effects. It analyzes every
+changed file, then follows unchanged consumers only while needed to establish whether the PR
+qualifies, retaining one nearby rendering-consumer examination when available. Once any retained
+finding flags and that examination is done, further indirect analysis cannot change the decision
+and is omitted with an explicit coverage limitation. Clean results still require all candidates
+to be examined. Direct findings, grouped source attribution and resolved usage counts remain.
 
 Opaque runtime factories can still connect backend or authentication changes to UI inputs too
 broadly. These findings count as apparent false positives against the frozen nonvisual labels;

scripts/design-diff/analyze.ts

@@ -5,7 +5,7 @@ import { cssValue, extractCss } from '#design-diff/extract/css'
 import { extractDocument } from '#design-diff/extract/documents'
 import { extractTsx } from '#design-diff/extract/tsx'
 import { GitReader } from '#design-diff/git'
-import { causalSources, groupFindings } from '#design-diff/group'
+import { groupFindings } from '#design-diff/group'
 import { renderingLock } from '#design-diff/infrastructure'
 import { fileLoadedInputs } from '#design-diff/inputs'
 import { reclaimMemory } from '#design-diff/memory'
@@ -192,25 +192,48 @@ export async function analyze(
     }
     let extracted = 0
     let omittedConsumers = 0
-    const covered = new Set<string>()
-    const currentPath = (file: string) => [...renames].find(([, old]) => old === file)?.[0] ?? file
+    /** Prefer direct consumers before distant opaque application plumbing when retaining one example. */
+    const downstream = new Map<string, Set<string>>()
+    for (const graph of [before.graph, after.graph])
+      for (const [file, dependencies] of graph.dependencies)
+        for (const dependency of dependencies) {
+          const consumers = downstream.get(dependency) ?? new Set<string>()
+          consumers.add(file)
+          downstream.set(dependency, consumers)
+        }
+    const distances = new Map([...changed].map((file) => [file, 0]))
+    const queue = [...changed]
+    for (let index = 0; index < queue.length; index++) {
+      const file = queue[index]
+      for (const consumer of downstream.get(file) ?? [])
+        if (!distances.has(consumer)) {
+          distances.set(consumer, distances.get(file)! + 1)
+          queue.push(consumer)
+        }
+    }
     const ordered = [...affected].sort(
-      (a, b) => Number(changed.has(b)) - Number(changed.has(a)) || a.localeCompare(b, 'en')
+      (a, b) =>
+        (distances.get(a) ?? Number.POSITIVE_INFINITY) -
+          (distances.get(b) ?? Number.POSITIVE_INFINITY) || a.localeCompare(b, 'en')
     )
+    let indirectExamples = 0
     for (const file of ordered) {
       if (++extracted % 32 === 0) reclaimMemory()
       if (!scoped(file, config) && !infrastructure(file, config)) continue
       if ([...renames.values()].includes(file) && !after.entries.has(file)) continue
-      const roots = [...(causes.get(file) ?? [])].map(currentPath)
-      if (!changed.has(file) && roots.length && roots.every((root) => covered.has(root))) {
+      if (
+        !changed.has(file) &&
+        indirectExamples > 0 &&
+        findings.some((finding) => finding.decision === 'flag')
+      ) {
         omittedConsumers++
         continue
       }
-      const firstFinding = findings.length
       const oldFile = renames.get(file) ?? file
       const a = await extract(before, previousTailwind, oldFile)
       const b = await extract(after, nextTailwind, file)
       findings.push(...compareDefinitions(a, b, affected))
+      if (!changed.has(file) && (a.length || b.length)) indirectExamples++
       if (
         changed.has(file) &&
         config.infrastructure.some((pattern) => new RegExp(pattern).test(file))
@@ -247,15 +270,11 @@ export async function analyze(
             review(file, after.entries.get(file)?.oid ?? '', 'Unsupported rendering mechanism')
           )
         )
-      for (const change of findings.slice(firstFinding))
-        if (change.decision === 'flag')
-          for (const source of causalSources(change, causes, renames))
-            if (source !== currentPath(file) || /\.[jt]sx$/.test(source)) covered.add(source)
     }
     if (omittedConsumers)
       report.limitations = [
         ...report.limitations,
-        `Repeated downstream expansion omitted for ${omittedConsumers} unchanged files after all contributing changed sources already had flagged evidence. Categories describe retained evidence; usage counts remain partial resolved references.`,
+        `Indirect analysis omitted for ${omittedConsumers} unchanged files after the PR qualified and a nearby rendering consumer was examined. All in-scope changed files were analyzed; additional indirect effects are not exhaustively catalogued. Categories describe retained evidence; usage counts remain partial resolved references.`,
       ]
     for (const file of changed) {
       if (file !== 'bun.lock' && !file.endsWith('/package.json') && file !== 'package.json')

scripts/design-diff/tests/group.test.ts

@@ -18,6 +18,52 @@ const fixture = {
     'import {Icon} from "@sim/emcn";export const A=()=> <Icon className={dynamicStyle}/>',
 }
 
+it('retains a nearby visual consumer before a distant opaque consumer', async () => {
+  const token = 'apps/sim/token.ts'
+  const direct = 'apps/sim/z-title.tsx'
+  const report = await compareFiles(
+    {
+      [token]: 'export const title="Filling"',
+      [direct]: 'import {title} from "./token";export const Title=()=> <span>{title}</span>',
+      'apps/sim/helper.ts': 'import {title} from "./token";export const config=unknown(title)',
+      'apps/sim/a-distant.tsx':
+        'import {config} from "./helper";export const View=()=> <Widget config={config}/>',
+    },
+    { [token]: 'export const title="Filling form"' },
+    settings
+  )
+  expect(report.findings[0].example?.change.after?.location.file).toBe(direct)
+  expect(report.findings[0].example?.change.category).toBe('content')
+})
+
+it('keeps direct findings and declares partial indirect coverage after qualification', async () => {
+  const token = 'apps/sim/token.ts'
+  const other = 'apps/sim/other.tsx'
+  const files = {
+    [token]: 'export const colour="red"',
+    [consumer]: 'export const View=()=> <div className="p-2"/>',
+    [other]: 'import {colour} from "./token";export const Other=()=> <div style={{color:colour}}/>',
+    'apps/sim/z-extra.tsx':
+      'import {colour} from "./token";export const Extra=()=> <span style={{color:colour}}/>',
+  }
+  const report = await compareFiles(
+    files,
+    {
+      [token]: 'export const colour="blue"',
+      [consumer]: files[consumer].replace('p-2', 'p-4'),
+    },
+    settings
+  )
+  expect(report.flagged).toBe(true)
+  expect(report.findings.some((finding) => finding.source.after?.file === consumer)).toBe(true)
+  expect(report.limitations.join(' ')).toContain(
+    'additional indirect effects are not exhaustively catalogued'
+  )
+  expect(
+    (await compareFiles(files, { [token]: 'export const colour="blue"' }, settings)).flagged
+  ).toBe(true)
+})
+
 it('groups a shared change once and counts only references to its defining module', async () => {
   const report = await compareFiles(
     fixture,

scripts/design-diff/tests/precision.test.ts

@@ -557,7 +557,7 @@ it('preserves selected helper return guards, defaults and call arguments', async
   expect((await compareFiles(files, { [view]: page('other') }, settings)).flagged).toBe(true)
 })
 
-it('retains every changed source while avoiding repeated consumer expansion', async () => {
+it('retains direct changes and a nearby token example while bounding indirect expansion', async () => {
   const files = {
     [data]: 'export const colour="red"',
     [view]: 'import {colour} from "./data";export const Page=()=> <div style={{color:colour}}/>',
@@ -582,9 +582,7 @@ it('retains every changed source while avoiding repeated consumer expansion', as
       .referenceCount
   ).toBe(2)
   expect(
-    report.limitations.some((limitation) =>
-      limitation.includes('Repeated downstream expansion omitted')
-    )
+    report.limitations.some((limitation) => limitation.includes('Indirect analysis omitted'))
   ).toBe(true)
 })