fallow-type-aware 3.40.0 → 3.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fallow-type-aware",
3
- "version": "3.40.0",
3
+ "version": "3.42.0",
4
4
  "description": "Optional TypeScript-Go semantic refinement sidecar for Fallow",
5
5
  "license": "MIT",
6
6
  "repository": {
package/src/backend.mjs CHANGED
@@ -28,7 +28,7 @@ const importApi = async (subpath) => {
28
28
  };
29
29
  export const sync = await importApi("sync");
30
30
  export const ast = await importApi("ast/is");
31
- export const { SyntaxKind } = await importApi("ast");
31
+ export const { SyntaxKind, NodeFlags } = await importApi("ast");
32
32
  const { serverFS } = await importApi("fs");
33
33
 
34
34
  /**
@@ -19,6 +19,7 @@ import {
19
19
  } from "./backend.mjs";
20
20
 
21
21
  import { canonicalFileIdentity } from "./file-identity.mjs";
22
+ import { NON_NULLISH_HINT, nonNullishLinks } from "./optional-chain-proof.mjs";
22
23
 
23
24
  const { DiagnosticCategory } = sync;
24
25
 
@@ -131,8 +132,9 @@ const checkMutant = (context, check, mutant) => {
131
132
  check.snapshot = next;
132
133
  const errors = fileErrors(next.getProject(check.config), check.file.absolutePath);
133
134
  const codes = newErrorCodes(check.baseline, errors);
134
- return codes.length > 0
135
- ? { id: mutant.id, outcome: "compile-error", codes }
135
+ if (codes.length > 0) return { id: mutant.id, outcome: "compile-error", codes };
136
+ return check.hinted.has(mutant.id)
137
+ ? { id: mutant.id, outcome: "compiles", hint: NON_NULLISH_HINT }
136
138
  : { id: mutant.id, outcome: "compiles" };
137
139
  };
138
140
 
@@ -145,12 +147,14 @@ const checkInProject = (context, file, original, config) => {
145
147
  changes: { fileChanges: { changed: [file.absolutePath] } },
146
148
  snapshot: context.api.updateSnapshot({ openProjects: [config] }),
147
149
  baseline: null,
150
+ hinted: new Set(),
148
151
  };
149
152
  try {
150
153
  const project = check.snapshot.getProject(config);
151
154
  const reason = projectSkipReason(project, file, original);
152
155
  if (reason !== null) return unchecked(file, reason);
153
156
  check.baseline = countKeys(fileErrors(project, file.absolutePath));
157
+ check.hinted = nonNullishLinks(project, file, original);
154
158
  return file.mutants.map((mutant) => checkMutant(context, check, mutant));
155
159
  } finally {
156
160
  context.overlay.delete(check.identity);
@@ -0,0 +1,433 @@
1
+ // Finds optional-chaining mutants that the types suggest are equivalent to the
2
+ // original code. The result is an advisory hint, never a verdict: the mutant
3
+ // keeps the status `survived`, because a type does not prove a run-time value.
4
+ //
5
+ // The mutants `a?.b` -> `a.b`, `a?.()` -> `a()` and `a?.[k]` -> `a[k]` change
6
+ // nothing when the receiver `a` is never `null` or `undefined` at run time.
7
+ // The proof trusts declarations and never trusts flow analysis or assertions:
8
+ //
9
+ // - It reads the declared type of the root binding or property, not the type
10
+ // that control flow narrows at the use. A call can invalidate a narrowing
11
+ // that the checker keeps.
12
+ // - It rejects an assertion (`as`, `<T>x`, `x!`) anywhere in the receiver, and
13
+ // in the initializer of each local binding that the receiver reads.
14
+ // - It rejects bindings and properties that the language does not force to
15
+ // hold a value: `declare` and `.d.ts` variables, bindings without an
16
+ // initializer, `!` and `declare` properties, and class properties that no
17
+ // initializer or constructor assignment sets.
18
+ // - It rejects a `let`, `var` or parameter binding that any code assigns after
19
+ // its declaration, in a closure or through a destructuring target too.
20
+ // - It needs `strictNullChecks` (a type excludes nullish values only then) and
21
+ // `noUncheckedIndexedAccess` (otherwise `xs[0]` has a non-nullable type and
22
+ // is `undefined` for an empty array).
23
+ //
24
+ // When the provenance of the type is unclear, the proof says nothing and the
25
+ // mutant keeps its normal check.
26
+
27
+ import path from "node:path";
28
+
29
+ import { ast, NodeFlags, projectCompilerOptions, sync, SyntaxKind } from "./backend.mjs";
30
+ import { declarationsForSymbol } from "./semantic-identity.mjs";
31
+
32
+ const { TypeFlags, SymbolFlags } = sync;
33
+ const {
34
+ isArrayLiteralExpression,
35
+ isArrowFunction,
36
+ isAsExpression,
37
+ isBinaryExpression,
38
+ isCallExpression,
39
+ isClassDeclaration,
40
+ isClassExpression,
41
+ isConstructorDeclaration,
42
+ isElementAccessExpression,
43
+ isExpressionStatement,
44
+ isFunctionExpression,
45
+ isIdentifier,
46
+ isLiteralExpression,
47
+ isNewExpression,
48
+ isNonNullExpression,
49
+ isObjectLiteralExpression,
50
+ isParenthesizedExpression,
51
+ isPropertyAccessExpression,
52
+ isPropertyDeclaration,
53
+ isSatisfiesExpression,
54
+ isTemplateExpression,
55
+ isThisExpression,
56
+ isTypeAssertion,
57
+ isVariableDeclaration,
58
+ } = ast;
59
+
60
+ /** The hint that the response gives for a mutant whose receiver type excludes nullish values. */
61
+ export const NON_NULLISH_HINT = "type-non-nullish";
62
+
63
+ const OPTIONAL_TOKEN = "?.";
64
+ const TYPESCRIPT_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".cts"]);
65
+ const MAX_UNION_DEPTH = 8;
66
+ const MAX_BINDING_DEPTH = 8;
67
+ const NON_NULLABLE_FLAGS = TypeFlags.DefinitelyNonNullable;
68
+ const UNION_OR_INTERSECTION = TypeFlags.Union | TypeFlags.Intersection;
69
+
70
+ const strictNullChecks = (options) =>
71
+ options.strictNullChecks === true ||
72
+ (options.strictNullChecks === undefined && options.strict === true);
73
+
74
+ const allowsTypeProof = (project, absolutePath) => {
75
+ const options = projectCompilerOptions(project);
76
+ return (
77
+ TYPESCRIPT_EXTENSIONS.has(path.extname(absolutePath).toLowerCase()) &&
78
+ strictNullChecks(options) &&
79
+ options.noUncheckedIndexedAccess === true
80
+ );
81
+ };
82
+
83
+ const neverNullish = (type, depth) => {
84
+ if (depth > MAX_UNION_DEPTH) return false;
85
+ if ((type.flags & UNION_OR_INTERSECTION) !== 0) {
86
+ const members = type.getTypes?.() ?? [];
87
+ return members.length > 0 && members.every((member) => neverNullish(member, depth + 1));
88
+ }
89
+ return type.flags !== 0 && (type.flags & ~NON_NULLABLE_FLAGS) === 0;
90
+ };
91
+
92
+ const isParameter = (node) => node.kind === SyntaxKind.Parameter;
93
+ const isPropertySignature = (node) => node.kind === SyntaxKind.PropertySignature;
94
+
95
+ const isAssertion = (node) =>
96
+ isAsExpression(node) || isTypeAssertion(node) || isNonNullExpression(node);
97
+
98
+ const containsAssertion = (node) => {
99
+ if (isAssertion(node)) return true;
100
+ let found = false;
101
+ node.forEachChild((child) => {
102
+ found = found || containsAssertion(child);
103
+ return found ? true : undefined;
104
+ });
105
+ return found;
106
+ };
107
+
108
+ const hasModifier = (node, kind) => node.modifiers?.some((modifier) => modifier.kind === kind);
109
+
110
+ const hasToken = (node, kind) => {
111
+ let found = false;
112
+ node.forEachChild((child) => {
113
+ found = found || child.kind === kind;
114
+ return found ? true : undefined;
115
+ });
116
+ return found;
117
+ };
118
+
119
+ // True for a `declare` declaration, a member of one, or anything in a
120
+ // declaration file: their types are claims that no code in the project checks.
121
+ const isAmbient = (node) => {
122
+ for (let current = node; current; current = current.parent) {
123
+ if (current.isDeclarationFile === true) return true;
124
+ if (hasModifier(current, SyntaxKind.DeclareKeyword)) return true;
125
+ }
126
+ return false;
127
+ };
128
+
129
+ const typeAt = (project, declaration, symbol) =>
130
+ project.checker.getTypeOfSymbolAtLocation(symbol, declaration);
131
+
132
+ // A constructor statement `this.name = value;` at the top level of the body.
133
+ const constructorAssigns = (classNode, name) =>
134
+ classNode.members.some(
135
+ (member) =>
136
+ isConstructorDeclaration(member) &&
137
+ member.body !== undefined &&
138
+ member.body.statements.some((statement) => {
139
+ if (!isExpressionStatement(statement)) return false;
140
+ const { expression } = statement;
141
+ return (
142
+ isBinaryExpression(expression) &&
143
+ expression.operatorToken.kind === SyntaxKind.EqualsToken &&
144
+ isPropertyAccessExpression(expression.left) &&
145
+ isThisExpression(expression.left.expression) &&
146
+ expression.left.name.text === name &&
147
+ !containsAssertion(expression.right)
148
+ );
149
+ }),
150
+ );
151
+
152
+ const isParameterProperty = (declaration) =>
153
+ isParameter(declaration) && isConstructorDeclaration(declaration.parent);
154
+
155
+ const classPropertyIsSet = (project, declaration, context) => {
156
+ if (
157
+ hasModifier(declaration, SyntaxKind.DeclareKeyword) ||
158
+ hasToken(declaration, SyntaxKind.ExclamationToken)
159
+ ) {
160
+ return false;
161
+ }
162
+ if (declaration.initializer !== undefined) {
163
+ return initializerIsSafe(project, declaration.initializer, context);
164
+ }
165
+ if (hasModifier(declaration, SyntaxKind.StaticKeyword)) return false;
166
+ const owner = declaration.parent;
167
+ return (
168
+ (isClassDeclaration(owner) || isClassExpression(owner)) &&
169
+ constructorAssigns(owner, declaration.name.text)
170
+ );
171
+ };
172
+
173
+ const propertyIsSafe = (project, declaration, context) => {
174
+ if (isPropertySignature(declaration)) return true;
175
+ if (isParameterProperty(declaration)) return !isAmbient(declaration);
176
+ if (!isPropertyDeclaration(declaration) || isAmbient(declaration)) return false;
177
+ return classPropertyIsSet(project, declaration, context);
178
+ };
179
+
180
+ // The initializer must itself be non-nullish by declaration. Otherwise a
181
+ // stale narrowing in the initializer would give the binding a type that the
182
+ // value does not have.
183
+ const initializerIsSafe = (project, initializer, context) => {
184
+ if (containsAssertion(initializer)) return false;
185
+ const type = declaredType(project, initializer, context);
186
+ return type !== null && neverNullish(type, 0);
187
+ };
188
+
189
+ const uniqueDeclaration = (project, symbol) => {
190
+ const declarations = declarationsForSymbol(project, symbol);
191
+ return declarations.length === 1 ? declarations[0] : null;
192
+ };
193
+
194
+ // Node kinds that a write target passes through on the way to its assignment:
195
+ // `[a] = xs`, `({ a } = o)`, `({ k: a } = o)`, `(a as T) = v`.
196
+ const TARGET_WRAPPERS = new Set([
197
+ SyntaxKind.ParenthesizedExpression,
198
+ SyntaxKind.ArrayLiteralExpression,
199
+ SyntaxKind.ObjectLiteralExpression,
200
+ SyntaxKind.ShorthandPropertyAssignment,
201
+ SyntaxKind.SpreadElement,
202
+ SyntaxKind.SpreadAssignment,
203
+ SyntaxKind.AsExpression,
204
+ SyntaxKind.TypeAssertionExpression,
205
+ SyntaxKind.NonNullExpression,
206
+ SyntaxKind.SatisfiesExpression,
207
+ ]);
208
+
209
+ const isAssignmentOperator = (kind) =>
210
+ kind >= SyntaxKind.FirstAssignment && kind <= SyntaxKind.LastAssignment;
211
+
212
+ const isIncrementOperator = (kind) =>
213
+ kind === SyntaxKind.PlusPlusToken || kind === SyntaxKind.MinusMinusToken;
214
+
215
+ const isWriteTarget = (identifier) => {
216
+ let node = identifier;
217
+ for (let parent = node.parent; parent; parent = node.parent) {
218
+ if (TARGET_WRAPPERS.has(parent.kind)) {
219
+ node = parent;
220
+ continue;
221
+ }
222
+ switch (parent.kind) {
223
+ case SyntaxKind.PropertyAssignment:
224
+ if (parent.initializer !== node) return false;
225
+ node = parent;
226
+ continue;
227
+ case SyntaxKind.BinaryExpression:
228
+ return parent.left === node && isAssignmentOperator(parent.operatorToken.kind);
229
+ case SyntaxKind.PrefixUnaryExpression:
230
+ case SyntaxKind.PostfixUnaryExpression:
231
+ return isIncrementOperator(parent.operator);
232
+ case SyntaxKind.ForInStatement:
233
+ case SyntaxKind.ForOfStatement:
234
+ return parent.initializer === node;
235
+ default:
236
+ return false;
237
+ }
238
+ }
239
+ return false;
240
+ };
241
+
242
+ const writtenSymbolId = (project, identifier) => {
243
+ const symbol = isShorthandName(identifier)
244
+ ? project.checker.getShorthandAssignmentValueSymbol(identifier.parent)
245
+ : project.checker.getSymbolAtLocation(identifier);
246
+ return symbol?.id;
247
+ };
248
+
249
+ const isShorthandName = (identifier) =>
250
+ identifier.parent?.kind === SyntaxKind.ShorthandPropertyAssignment &&
251
+ identifier.parent.name === identifier;
252
+
253
+ // The ids of the symbols that code in `sourceFile` assigns, found once for
254
+ // each file. An unresolved write target is not recorded, so the scan also
255
+ // keeps a flag for a file where a write could not be resolved.
256
+ const writesOf = (project, sourceFile, cache) => {
257
+ const cached = cache.get(sourceFile);
258
+ if (cached) return cached;
259
+ const writes = { ids: new Set(), unresolved: false };
260
+ const visit = (node) => {
261
+ if (isIdentifier(node) && isWriteTarget(node)) {
262
+ const id = writtenSymbolId(project, node);
263
+ if (id === undefined) writes.unresolved = true;
264
+ else writes.ids.add(id);
265
+ }
266
+ node.forEachChild((child) => {
267
+ visit(child);
268
+ return undefined;
269
+ });
270
+ };
271
+ visit(sourceFile);
272
+ cache.set(sourceFile, writes);
273
+ return writes;
274
+ };
275
+
276
+ const isConstBinding = (declaration) =>
277
+ isVariableDeclaration(declaration) && (declaration.parent.flags & NodeFlags.Const) !== 0;
278
+
279
+ // A top-level `let` or `var` of a script file is global: code in another file
280
+ // can assign it, and the scan reads one file only.
281
+ const isGlobalScriptBinding = (declaration, sourceFile) =>
282
+ isVariableDeclaration(declaration) &&
283
+ sourceFile.externalModuleIndicator === undefined &&
284
+ declaration.parent.parent.parent === sourceFile;
285
+
286
+ // True when the binding can change after its declaration: a `let`, `var` or
287
+ // parameter that some code assigns. Only the module that declares a binding
288
+ // can assign it, so the scan reads the declaring file.
289
+ const isReassigned = (project, declaration, symbol, context) => {
290
+ if (isConstBinding(declaration)) return false;
291
+ const sourceFile = declaration.getSourceFile();
292
+ if (isGlobalScriptBinding(declaration, sourceFile)) return true;
293
+ const writes = writesOf(project, sourceFile, context.writes);
294
+ return writes.unresolved || writes.ids.has(symbol.id);
295
+ };
296
+
297
+ const bindingType = (project, identifier, context) => {
298
+ if (context.depth > MAX_BINDING_DEPTH) return null;
299
+ let symbol = project.checker.getSymbolAtLocation(identifier);
300
+ if (!symbol) return null;
301
+ if ((symbol.flags & SymbolFlags.Alias) !== 0) {
302
+ symbol = project.checker.getAliasedSymbol(symbol);
303
+ if (project.checker.isUnknownSymbol(symbol)) return null;
304
+ }
305
+ const declaration = uniqueDeclaration(project, symbol);
306
+ if (declaration === null || context.visited.has(declaration) || isAmbient(declaration)) {
307
+ return null;
308
+ }
309
+ context.visited.add(declaration);
310
+ if (isReassigned(project, declaration, symbol, context)) return null;
311
+ const inner = { ...context, depth: context.depth + 1 };
312
+ if (isParameter(declaration) && isIdentifier(declaration.name)) {
313
+ return typeAt(project, declaration, symbol);
314
+ }
315
+ if (
316
+ isVariableDeclaration(declaration) &&
317
+ isIdentifier(declaration.name) &&
318
+ declaration.initializer !== undefined &&
319
+ initializerIsSafe(project, declaration.initializer, inner)
320
+ ) {
321
+ return typeAt(project, declaration, symbol);
322
+ }
323
+ return null;
324
+ };
325
+
326
+ const propertyType = (project, access, context) => {
327
+ const objectType = declaredType(project, access.expression, context);
328
+ if (objectType === null) return null;
329
+ const property = project.checker.getPropertyOfType(objectType, access.name.text);
330
+ if (!property) return null;
331
+ const declaration = uniqueDeclaration(project, property);
332
+ if (declaration === null || !propertyIsSafe(project, declaration, context)) return null;
333
+ return typeAt(project, declaration, property);
334
+ };
335
+
336
+ const callType = (project, call) => {
337
+ const signature = project.checker.getResolvedSignature(call);
338
+ const declaration = signature?.declaration?.resolve(project);
339
+ if (!declaration?.type) return null;
340
+ return project.checker.getTypeAtLocation(declaration.type) ?? null;
341
+ };
342
+
343
+ const isFreshValue = (node) =>
344
+ isObjectLiteralExpression(node) ||
345
+ isArrayLiteralExpression(node) ||
346
+ isArrowFunction(node) ||
347
+ isFunctionExpression(node) ||
348
+ isClassExpression(node) ||
349
+ isNewExpression(node) ||
350
+ isTemplateExpression(node) ||
351
+ isLiteralExpression(node);
352
+
353
+ // The type that declarations give to `expression`, or null when the
354
+ // expression is not a form whose type the proof trusts. The checker's own
355
+ // type at the use is never read for a reference, because it reflects control
356
+ // flow narrowing.
357
+ const declaredType = (project, expression, context) => {
358
+ if (isParenthesizedExpression(expression) || isSatisfiesExpression(expression)) {
359
+ return declaredType(project, expression.expression, context);
360
+ }
361
+ if (isIdentifier(expression)) return bindingType(project, expression, context);
362
+ if (isThisExpression(expression)) {
363
+ const type = project.checker.getTypeAtLocation(expression);
364
+ return type ? (project.checker.getBaseConstraintOfType(type) ?? type) : null;
365
+ }
366
+ if (isPropertyAccessExpression(expression)) return propertyType(project, expression, context);
367
+ if (isCallExpression(expression) && expression.questionDotToken === undefined) {
368
+ return callType(project, expression);
369
+ }
370
+ if (isFreshValue(expression)) return project.checker.getTypeAtLocation(expression) ?? null;
371
+ return null;
372
+ };
373
+
374
+ const optionalLinkReceiver = (node) => {
375
+ if (node.questionDotToken === undefined) return null;
376
+ const hasReceiver =
377
+ isPropertyAccessExpression(node) || isElementAccessExpression(node) || isCallExpression(node);
378
+ return hasReceiver ? node.expression : null;
379
+ };
380
+
381
+ // Maps the UTF-16 end offset of each `?.` token to the receiver it follows.
382
+ const receiversByLinkEnd = (sourceFile) => {
383
+ const receivers = new Map();
384
+ const visit = (node) => {
385
+ const receiver = optionalLinkReceiver(node);
386
+ if (receiver !== null) receivers.set(node.questionDotToken.end, receiver);
387
+ node.forEachChild((child) => {
388
+ visit(child);
389
+ return undefined;
390
+ });
391
+ };
392
+ visit(sourceFile);
393
+ return receivers;
394
+ };
395
+
396
+ const isOptionalLink = (original, mutant) =>
397
+ original.subarray(mutant.start, mutant.end).toString("utf8") === OPTIONAL_TOKEN;
398
+
399
+ const utf16Offset = (original, byteOffset) =>
400
+ original.subarray(0, byteOffset).toString("utf8").length;
401
+
402
+ const receiverIsNeverNullish = (project, receiver, writes) => {
403
+ if (containsAssertion(receiver)) return false;
404
+ try {
405
+ const type = declaredType(project, receiver, { visited: new Set(), depth: 0, writes });
406
+ return type !== null && neverNullish(type, 0);
407
+ } catch {
408
+ return false;
409
+ }
410
+ };
411
+
412
+ /**
413
+ * Returns the ids of the mutants of `file` that remove an optional link from
414
+ * a receiver whose declarations prove it never nullish. `project` is the
415
+ * project of the original file, before any mutant is applied.
416
+ */
417
+ export const nonNullishLinks = (project, file, original) => {
418
+ const links = file.mutants.filter((mutant) => isOptionalLink(original, mutant));
419
+ if (links.length === 0 || !allowsTypeProof(project, file.absolutePath)) return new Set();
420
+ const sourceFile = project.program.getSourceFile(file.absolutePath);
421
+ if (!sourceFile) return new Set();
422
+ try {
423
+ const receivers = receiversByLinkEnd(sourceFile);
424
+ const writes = new Map();
425
+ const proven = links.filter((mutant) => {
426
+ const receiver = receivers.get(utf16Offset(original, mutant.end));
427
+ return receiver !== undefined && receiverIsNeverNullish(project, receiver, writes);
428
+ });
429
+ return new Set(proven.map((mutant) => mutant.id));
430
+ } catch {
431
+ return new Set();
432
+ }
433
+ };
package/src/semantic.mjs CHANGED
@@ -47,6 +47,7 @@ import {
47
47
  recordSymbolUncertainty,
48
48
  targetName,
49
49
  } from "./symbol-targets.mjs";
50
+ import { recordBoundedUse } from "./symbol-use-evidence.mjs";
50
51
  import { analyzeTypeCoupling } from "./type-coupling.mjs";
51
52
  import {
52
53
  MODULE_SOURCE_EXTENSIONS,
@@ -79,7 +80,6 @@ const {
79
80
  } = ast;
80
81
 
81
82
  const ATTACHED_COMMENT_PATTERN = /\/\/|\/\*/u;
82
- const MAX_SYMBOL_USE_EVIDENCE = 1;
83
83
  const DECLARATION_KINDS = new Set([
84
84
  "export",
85
85
  "class",
@@ -265,12 +265,13 @@ const boundedResult = ({
265
265
  evidenceLimit,
266
266
  totalEvidenceCount,
267
267
  omissions: extraOmissions = [],
268
+ evidenceLimitIsGap = true,
268
269
  }) => {
269
270
  const ordered = orderedEvidence(evidence);
270
271
  const totalEvidence = totalEvidenceCount === undefined ? ordered.length : totalEvidenceCount;
271
272
  const returnedEvidenceCount = Math.min(ordered.length, evidenceLimit);
272
273
  const omissions = combineOmissions([
273
- ...evidenceLimitOmission(totalEvidence, returnedEvidenceCount),
274
+ ...(evidenceLimitIsGap ? evidenceLimitOmission(totalEvidence, returnedEvidenceCount) : []),
274
275
  ...extraOmissions,
275
276
  ]).toSorted(compareOmissions);
276
277
  const partial = omissions.length > 0;
@@ -284,7 +285,7 @@ const boundedResult = ({
284
285
  actions: resultActions(omissions),
285
286
  evidence: ordered.slice(0, evidenceLimit),
286
287
  totalEvidenceCount: totalEvidence,
287
- truncated,
288
+ truncated: truncated || totalEvidence > returnedEvidenceCount,
288
289
  omissions,
289
290
  data,
290
291
  };
@@ -598,11 +599,7 @@ const recordSymbolUse = (root, state, project, entry, node, namespace) => {
598
599
  state.aliasHopTotalByQuery.get(entry.query.id) + use.via.length,
599
600
  );
600
601
  }
601
- const limit =
602
- entry.query.operation === "symbol-use" ? MAX_SYMBOL_USE_EVIDENCE : state.evidenceLimit;
603
- if (evidence.length < limit) {
604
- evidence.push(use);
605
- }
602
+ recordBoundedUse(evidence, use, entry.query.operation, state.evidenceLimit);
606
603
  };
607
604
 
608
605
  const projectOwnsEntry = (project, entry) =>
@@ -1143,6 +1140,8 @@ const analyzeSymbolUse = (
1143
1140
  evidenceLimit,
1144
1141
  totalEvidenceCount,
1145
1142
  omissions,
1143
+ // A capped use keeps one item per file. A negative assertion needs every reference.
1144
+ evidenceLimitIsGap: assertion !== "confirmed-used",
1146
1145
  data: {
1147
1146
  symbol: semanticQueryIdentity(root, query, resolved),
1148
1147
  selected_project: resolved.state.config,
@@ -0,0 +1,24 @@
1
+ const isReExportUse = (use) => use.role.includes("re-export");
2
+
3
+ // The client credits a use only from a reachable file that reads the binding.
4
+ // One item for each file lets a capped result still show such a file.
5
+ const recordFileUse = (evidence, use, limit) => {
6
+ const index = evidence.findIndex((kept) => kept.path === use.path);
7
+ if (index === -1) {
8
+ if (evidence.length < limit) evidence.push(use);
9
+ return;
10
+ }
11
+ if (isReExportUse(evidence[index]) && !isReExportUse(use)) evidence[index] = use;
12
+ };
13
+
14
+ /**
15
+ * Adds one reference to the bounded evidence of a query.
16
+ * A `symbol-use` query keeps one item for each file. Other queries keep the first items.
17
+ */
18
+ export const recordBoundedUse = (evidence, use, operation, limit) => {
19
+ if (operation === "symbol-use") {
20
+ recordFileUse(evidence, use, limit);
21
+ } else if (evidence.length < limit) {
22
+ evidence.push(use);
23
+ }
24
+ };