fix(design-diff): trace collection writes without mixing unrelated properties

Author: Bill Leoutsakos

scripts/design-diff/README.md

@@ -96,6 +96,7 @@ scripts/design-diff/
   dependencies.ts                       Export-aware imports and source reference counts
   ast.ts                                Babel parsing and syntax normalization
   refactors.ts                          Supported literal/refactor normalization
+  mutations.ts                          Referenced collection/property writes
   resolve.ts                            Bounded expression and import resolution
   inputs.ts                             Configured file-loaded documentation inputs
   infrastructure.ts                     Rendering lockfile dependency closure
@@ -179,7 +180,7 @@ The configured Fumadocs `OPENAPI_SPEC_FILES` list is parsed from Git in each rev
 JSON inputs are compared semantically, retaining array order and attributing changes to both
 the spec and configured renderer. Malformed/missing configured inputs flag with a limitation.
 
-The graph reuses up to 10,000 import/export snapshots keyed by source blob, resolving their
+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,
 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.

scripts/design-diff/dependencies.ts

@@ -189,7 +189,7 @@ export class DependencyGraph {
           effects: effects.length ? fingerprint(effects) : undefined,
         }
         this.modules.set(file, module)
-        if (moduleSnapshots.size >= 10000)
+        if (moduleSnapshots.size >= 32768)
           moduleSnapshots.delete(moduleSnapshots.keys().next().value!)
         moduleSnapshots.set(cacheKey, { module, specifiers: [...specifiers] })
       } catch {

scripts/design-diff/extract/tsx.ts

@@ -287,8 +287,7 @@ export function extractTsx(resolver: Resolver, file: string): Definition[] {
       } else emit(path, 'review', 'native-options', evidence)
     },
     TaggedTemplateExpression(path) {
-      // A tag is only a standalone visual definition for a known styling binding.
-      // SQL and String.raw still participate when explicitly read by a visual input.
+      /** A tag is only a standalone visual definition for a known styling binding. SQL and String.raw still participate when explicitly read by a visual input. */
       const tag = child(path, 'tag')
       const root = tag.isMemberExpression() ? child(tag, 'object') : tag
       if (!root.isIdentifier()) return

scripts/design-diff/mutations.ts

@@ -0,0 +1,50 @@
+import type { Binding, NodePath } from '@babel/traverse'
+import * as t from '@babel/types'
+
+/** Writes to a referenced collection remain relevant even when its binding is const. */
+export function mutations(binding: Binding, selected?: string): NodePath[] {
+  const result = new Set<NodePath>()
+  for (const reference of binding.referencePaths) {
+    const first = reference.parentPath
+    if (selected && first?.isMemberExpression() && first.node.object === reference.node) {
+      const key = first.node.property
+      const name =
+        !first.node.computed && t.isIdentifier(key)
+          ? key.name
+          : t.isStringLiteral(key)
+            ? key.value
+            : undefined
+      const method =
+        first.parentPath.isCallExpression() && first.parentPath.node.callee === first.node
+      if (name !== undefined && name !== selected && !method) continue
+    }
+    let value = reference
+    let member = value.parentPath
+    while (member?.isMemberExpression() && member.node.object === value.node) {
+      const parent = member.parentPath
+      if (
+        (parent.isAssignmentExpression() && parent.node.left === member.node) ||
+        parent.isUpdateExpression() ||
+        parent.isUnaryExpression({ operator: 'delete' })
+      )
+        result.add(parent)
+      const property = member.node.property
+      const name = t.isIdentifier(property)
+        ? property.name
+        : t.isStringLiteral(property)
+          ? property.value
+          : ''
+      if (
+        parent.isCallExpression() &&
+        parent.node.callee === member.node &&
+        /^(?:push|pop|shift|unshift|splice|sort|reverse|fill|copyWithin|set|add|delete|clear)$/.test(
+          name
+        )
+      )
+        result.add(parent)
+      value = member
+      member = value.parentPath
+    }
+  }
+  return [...result]
+}

scripts/design-diff/refactors.ts

@@ -1,6 +1,7 @@
 import type traverse from '@babel/traverse'
 import type { NodePath } from '@babel/traverse'
 import * as t from '@babel/types'
+import { mutations } from '#design-diff/mutations'
 
 /** Normalize the equivalent Object.entries record-map idiom without executing its callback. */
 export function normalizeRefactors(ast: t.File, visit: typeof traverse): void {
@@ -97,7 +98,7 @@ export function normalizeLiteralAliases(ast: t.File, visit: typeof traverse): vo
       value = literal(path.get('expression') as NodePath, seen)
     else if (path.isReferencedIdentifier()) {
       const binding = path.scope.getBinding(path.node.name)
-      if (binding?.constant && binding.path.isVariableDeclarator())
+      if (binding?.constant && binding.path.isVariableDeclarator() && !mutations(binding).length)
         value = literal(binding.path.get('init') as NodePath, seen)
     } else if (path.isObjectExpression()) {
       const properties: t.ObjectProperty[] = []

scripts/design-diff/report.ts

@@ -85,7 +85,7 @@ export function serializeReport(report: Report, limit = REPORT_BYTES): string {
   }
   const json = () => `${JSON.stringify(copy, null, 2)}\n`
   let result = json()
-  // Remove details first, then source groups. Stable prefixes make repeated output identical.
+  /** Remove details first, then source groups. Stable prefixes make repeated output identical. */
   if (Buffer.byteLength(result) > limit) {
     for (const [i, finding] of copy.findings.entries()) {
       finding.changes = sample(finding.changes, `findings[${i}].changes.remaining`, 1)

scripts/design-diff/resolve.ts

@@ -9,6 +9,7 @@ import {
   symbolName,
   traverse,
 } from '#design-diff/ast'
+import { mutations } from '#design-diff/mutations'
 import { previewValue } from '#design-diff/report'
 import type { SourceTree } from '#design-diff/source'
 import type { Data, Evidence } from '#design-diff/types'
@@ -160,8 +161,7 @@ export class Resolver {
       )
     )
       return true
-    // Canvas operations are specific; ambiguous DOM methods require a typed/ref receiver
-    // or another established DOM operation in the same function.
+    /** Canvas operations are specific; ambiguous DOM methods require a typed/ref receiver or another established DOM operation in the same function. */
     if (
       /^(?:fillRect|strokeRect|drawImage|fillText|strokeText|addColorStop|getContext)$/.test(method)
     )
@@ -281,6 +281,28 @@ export class Resolver {
     }
   }
 
+  /** Conditions around writes can change the visible collection even when each value is unchanged. */
+  private mutationValue(write: NodePath, file: string, depth: number): Data {
+    const conditions: Data[] = []
+    for (
+      let parent = write.parentPath;
+      parent && !parent.isFunction();
+      parent = parent.parentPath
+    ) {
+      if (
+        parent.isIfStatement() ||
+        parent.isConditionalExpression() ||
+        parent.isWhileStatement() ||
+        parent.isDoWhileStatement() ||
+        parent.isForStatement()
+      )
+        conditions.push(this.value(child(parent, 'test'), file, depth + 1))
+      if (parent.isForOfStatement() || parent.isForInStatement())
+        conditions.push(this.value(child(parent, 'right'), file, depth + 1))
+    }
+    return { value: this.value(write, file, depth + 1), conditions }
+  }
+
   private currentFile = ''
 
   /** Select a property before expanding siblings, including createEnv's schema convention. */
@@ -298,8 +320,18 @@ export class Resolver {
       return this.selected(child(path, 'expression'), key, file, depth + 1, seen)
     if (path.isIdentifier()) {
       const binding = path.scope.getBinding(path.node.name)
-      if (binding?.constant && binding.path.isVariableDeclarator())
-        return this.selected(child(binding.path, 'init'), key, file, depth + 1, seen)
+      if (binding?.constant && binding.path.isVariableDeclarator()) {
+        const initial = this.selected(child(binding.path, 'init'), key, file, depth + 1, seen)
+        const writes = mutations(binding, key)
+        if (initial !== undefined && writes.length) {
+          this.unresolved.add('Writes to this object property feed rendering')
+          return {
+            $property: initial,
+            writes: writes.map((write) => this.mutationValue(write, file, depth + 1)),
+          }
+        }
+        return initial
+      }
       if (binding?.path.isImportSpecifier() || binding?.path.isImportDefaultSpecifier()) {
         const declaration = binding.path.parentPath
         if (declaration.isImportDeclaration()) {
@@ -459,8 +491,7 @@ export class Resolver {
     t.traverseFast(path.node, (node) => {
       if (t.isJSXElement(node) || t.isJSXFragment(node)) renders = true
     })
-    // JSX definitions are extracted at their own source. Expanding component bodies
-    // again at every reference duplicates evidence and confuses refactors with prop changes.
+    /** JSX definitions are extracted at their own source. Expanding component bodies again at every reference duplicates evidence and confuses refactors with prop changes. */
     if (renders) return { $renderFunction: { file, symbol: symbolName(path) } }
     const body = child(path, 'body')
     if (!body.isBlockStatement())
@@ -803,6 +834,14 @@ export class Resolver {
           writes: binding.constantViolations.map((violation) => fingerprint(violation.node)),
         }
       }
+      const writes = mutations(binding)
+      if (writes.length && binding.path.isVariableDeclarator()) {
+        this.unresolved.add('Collection or object mutations feed this visual input')
+        return {
+          $state: this.value(child(binding.path, 'init'), file, depth + 1),
+          writes: writes.map((write) => this.mutationValue(write, file, depth + 1)),
+        }
+      }
       const bound = binding.path
       const parameter = this.parameter(bound, node.name, file, depth)
       if (parameter !== undefined) return parameter
@@ -934,6 +973,8 @@ export class Resolver {
       return { $condition: test, then: read('consequent'), else: read('alternate') }
     }
     if (t.isFunction(node)) return this.functionValue(path, file, depth)
+    if (t.isAssignmentExpression(node))
+      return { $assignment: node.operator, target: fingerprint(node.left), value: read('right') }
     if (t.isNewExpression(node)) return { $new: read('callee'), arguments: readList('arguments') }
     if (t.isTaggedTemplateExpression(node)) return { $tag: read('tag'), template: read('quasi') }
     if (t.isAwaitExpression(node)) return { $await: read('argument') }

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

@@ -299,3 +299,48 @@ it('preserves value/type names shared by generated schema declarations', async (
       .some((reason) => /parser|extraction failed/i.test(reason))
   ).toBe(false)
 })
+
+it.each([
+  (colour: string) =>
+    `export function colours(){const values=[];values.push('${colour}');return values}`,
+  (colour: string) =>
+    `export function colours(){const values={colour:'red'};values.colour='${colour}';return values.colour}`,
+])('retains writes to const collections feeding rendering', async (source) => {
+  const report = await compareFiles(
+    {
+      [data]: source('red'),
+      [view]: 'import {colours} from "./data";export const Page=()=> <Panel colours={colours()}/>',
+    },
+    { [data]: source('blue') },
+    settings
+  )
+  expect(report.flagged).toBe(true)
+})
+
+it('retains conditions around collection writes', async () => {
+  const source = (enabled: boolean) =>
+    `export function colours(){const values=[];if(${enabled})values.push('red');return values}`
+  const report = await compareFiles(
+    {
+      [data]: source(true),
+      [view]: 'import {colours} from "./data";export const Page=()=> <Panel colours={colours()}/>',
+    },
+    { [data]: source(false) },
+    settings
+  )
+  expect(report.flagged).toBe(true)
+})
+
+it('isolates unrelated mutable object fields such as telemetry warmup state', async () => {
+  const source = (warm: boolean) =>
+    `const state={client:null,warmup:false};state.client=connect();state.warmup=${warm};export function client(){return state.client}`
+  const report = await compareFiles(
+    {
+      [data]: source(false),
+      [view]: 'import {client} from "./data";export const Page=()=> <Panel client={client()}/>',
+    },
+    { [data]: source(true) },
+    settings
+  )
+  expect(report.flagged).toBe(false)
+})