@cplieger/deadset-ts 5.2.3 → 6.0.1

package/src/module-declarations.ts

@@ -0,0 +1,241 @@
+/**
+ * The imports that name a `declare module` declaration whose name is a string literal: an
+ * augmentation or an ambient module, a wildcard one included. An import names it when its
+ * specifier equals the name, matches it with the one `*` standing for any run, or resolves
+ * to the same module. One that names it by name or pattern also reads the members it
+ * imports, whatever file the specifier resolves to, as a compiler reading no such file does.
+ */
+
+import {
+  isCallExpression,
+  isExportDeclaration,
+  isExternalModuleReference,
+  isImportDeclaration,
+  isImportEqualsDeclaration,
+  isImportTypeNode,
+  isLiteralTypeNode,
+  isModuleDeclaration,
+  isNamespaceExport,
+  isNamespaceImport,
+  isNoSubstitutionTemplateLiteral,
+  isStringLiteral,
+  SyntaxKind,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { renderPosition } from "./position.ts";
+import { UNANSWERED } from "./query.ts";
+import { nameComponent } from "./ref.ts";
+import type { Reference } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+
+/** Whether a node is a specifier's text: a string literal or a template with no substitution. */
+function literalText(node: Node | undefined): node is Node & { readonly text: string } {
+  return node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node));
+}
+
+/** The specifier one node writes, where it is an import of any form. */
+function specifierOf(node: Node): (Node & { readonly text: string }) | undefined {
+  if (isImportDeclaration(node) || isExportDeclaration(node)) {
+    const specifier = node.moduleSpecifier;
+    return literalText(specifier) ? specifier : undefined;
+  }
+  if (isImportEqualsDeclaration(node)) {
+    const reference = node.moduleReference;
+    return isExternalModuleReference(reference) && literalText(reference.expression)
+      ? reference.expression
+      : undefined;
+  }
+  if (isCallExpression(node) && node.expression.kind === SyntaxKind.ImportKeyword) {
+    const [argument] = node.arguments;
+    return literalText(argument) ? argument : undefined;
+  }
+  if (isImportTypeNode(node) && isLiteralTypeNode(node.argument)) {
+    const literal = node.argument.literal;
+    return literalText(literal) ? literal : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * The export names an import or a re-export reads from the module it names: none for a
+ * namespace, a star or a bare form.
+ */
+export function namesImported(node: Node): readonly string[] {
+  if (isImportDeclaration(node)) {
+    const clause = node.importClause;
+    const bindings = clause?.namedBindings;
+    return [
+      ...(clause?.name === undefined ? [] : ["default"]),
+      ...(bindings === undefined || isNamespaceImport(bindings)
+        ? []
+        : bindings.elements.map((one) => (one.propertyName ?? one.name).text)),
+    ];
+  }
+  const clause = isExportDeclaration(node) ? node.exportClause : undefined;
+  return clause === undefined || isNamespaceExport(clause)
+    ? []
+    : clause.elements.map((one) => (one.propertyName ?? one.name).text);
+}
+
+/**
+ * Whether a specifier matches a declaration's name, the name's one `*` standing for any run.
+ * A relative name is resolved against its own file, so no specifier names it by its text.
+ */
+function namesModule(specifier: string, name: string): boolean {
+  if (/^(?:\.{1,2}(?:\/|$)|\/)/u.test(name)) {
+    return false;
+  }
+  const star = name.indexOf("*");
+  if (star < 0 || name.slice(star + 1).includes("*")) {
+    return specifier === name;
+  }
+  const prefix = name.slice(0, star);
+  const suffix = name.slice(star + 1);
+  return (
+    specifier.length >= prefix.length + suffix.length &&
+    specifier.startsWith(prefix) &&
+    specifier.endsWith(suffix)
+  );
+}
+
+/** One module declaration a specifier names, and the members of it the import reads. */
+interface Named {
+  readonly id: string;
+  readonly members: readonly string[];
+}
+
+/**
+ * The module declarations of an inventory a specifier names by name or pattern, each with
+ * the members that hold the export names given.
+ */
+export function namedBy(
+  held: Inventory,
+): (specifier: string, names: readonly string[]) => readonly Named[] {
+  if (held.modules.size === 0) {
+    return () => [];
+  }
+  const refs = new Map<string, string>();
+  const children = new Map<string, InventorySymbol[]>();
+  for (const symbol of held.symbols) {
+    if (held.modules.has(symbol.id)) {
+      refs.set(symbol.id, symbol.ref);
+    }
+    if (held.modules.has(symbol.parent)) {
+      const siblings = children.get(symbol.parent) ?? [];
+      siblings.push(symbol);
+      children.set(symbol.parent, siblings);
+    }
+  }
+  return (specifier, names) =>
+    [...held.modules].flatMap(([id, name]) => {
+      if (!namesModule(specifier, name)) {
+        return [];
+      }
+      // A member is named by its declaration's reference, or an export alias's.
+      const ref = refs.get(id) ?? "";
+      const scope = ref.slice(0, ref.indexOf("#"));
+      const wanted = new Set(
+        names.flatMap((one) => [
+          `${ref}.${nameComponent(one)}`,
+          `${scope}#${nameComponent(one)}:alias`,
+        ]),
+      );
+      const members = (children.get(id) ?? []).filter((child) => wanted.has(child.ref));
+      return [{ id, members: members.map((child) => child.id) }];
+    });
+}
+
+/** One import of a project's own files, and the declaration or file that holds it. */
+interface Import {
+  readonly file: SourceFile;
+  readonly from: string;
+  readonly specifier: Node & { readonly text: string };
+  readonly names: readonly string[];
+}
+
+/** One module declaration of the inventory, and the name node it declares. */
+interface Declared {
+  readonly id: string;
+  readonly name: Node & { readonly text: string };
+}
+
+/**
+ * The references the imports of one project's own files make to the module declarations
+ * they name, each at the import's specifier.
+ */
+export function moduleDeclarationReferences<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  root: string,
+  testFiles: ReadonlySet<string>,
+): readonly Reference[] {
+  const imports: Import[] = [];
+  const declared: Declared[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const fileId = held.declarations.get(nodeKey(file, file));
+    if (fileId === undefined) {
+      continue;
+    }
+    const visit = (node: Node, from: string): void => {
+      const own = held.declarations.get(nodeKey(file, node));
+      if (isModuleDeclaration(node) && literalText(node.name) && own !== undefined) {
+        declared.push({ id: own, name: node.name });
+      }
+      const specifier = specifierOf(node);
+      if (specifier !== undefined) {
+        imports.push({ file, from, specifier, names: namesImported(node) });
+      }
+      node.forEachChild((child) => {
+        visit(child, own ?? from);
+      });
+    };
+    file.forEachChild((child) => {
+      visit(child, fileId);
+    });
+  }
+  if (declared.length === 0 || imports.length === 0) {
+    return [];
+  }
+
+  const asked = [...declared.map((one) => one.name), ...imports.map((one) => one.specifier)];
+  const answers = project.symbolsAt(asked.map((node) => project.handle(node)));
+  const moduleOf = (at: number): number | undefined => {
+    const symbol = answers[at];
+    return symbol === undefined || symbol === UNANSWERED ? undefined : symbol.id;
+  };
+
+  const named = namedBy(held);
+  const found: Reference[] = [];
+  imports.forEach((one, index) => {
+    const resolved = moduleOf(declared.length + index);
+    const position = renderPosition(one.file, root, one.specifier.getStart());
+    const read = (to: string, resolution: Reference["resolution"]): void => {
+      found.push({
+        from: one.from,
+        to,
+        position,
+        use: "read",
+        resolution,
+        test: testFiles.has(position.path),
+      });
+    };
+    const same = new Set(
+      declared
+        .filter((_, at) => resolved !== undefined && resolved === moduleOf(at))
+        .map((declaration) => declaration.id),
+    );
+    for (const id of same) {
+      read(id, "batch");
+    }
+    for (const declaration of named(one.specifier.text, one.names)) {
+      if (!same.has(declaration.id)) {
+        for (const to of [declaration.id, ...declaration.members]) {
+          read(to, "syntax");
+        }
+      }
+    }
+  });
+  return found;
+}

package/src/outside-tests.ts

@@ -1,9 +1,10 @@
 /**
  * The test files no compiler configuration of a run holds. The runner executes them all
  * the same, so each module one names is a test reference: the own file a relative
- * specifier names, and the declarations that file exports under the names read from it.
- * Such a file is read without a program, so what its body references beyond the modules
- * it names is not known.
+ * specifier names, and the declarations that file exports under the names read from it,
+ * or a module declaration the specifier names by name or pattern and its members of
+ * those names. Such a file is read without a program, so what its body references
+ * beyond the modules it names is not known.
  */
 
 import {
@@ -22,6 +23,7 @@ import { RESOLVED_EXTENSIONS, type ParseFile } from "./configuration-files.ts";
 import { emittedFrom } from "./emit-map.ts";
 import type { Host } from "./host.ts";
 import type { Inventory } from "./inventory.ts";
+import { namedBy, namesImported } from "./module-declarations.ts";
 import { dirnamePath, joinPath, normalizePath, queriedModulePath } from "./paths.ts";
 import { renderPosition } from "./position.ts";
 import { nameComponent } from "./ref.ts";
@@ -75,21 +77,15 @@ function modulesNamed(file: SourceFile): readonly NamedModule[] {
       const bindings = clause?.namedBindings;
       name(
         statement.moduleSpecifier,
-        [
-          ...(clause?.name === undefined ? [] : ["default"]),
-          ...(bindings === undefined || isNamespaceImport(bindings)
-            ? []
-            : bindings.elements.map((one) => (one.propertyName ?? one.name).text)),
-        ],
+        namesImported(statement),
         bindings === undefined ? clause?.name === undefined : isNamespaceImport(bindings),
       );
     } else if (isExportDeclaration(statement) && statement.moduleSpecifier !== undefined) {
       const clause = statement.exportClause;
-      const star = clause === undefined || isNamespaceExport(clause);
       name(
         statement.moduleSpecifier,
-        star ? [] : clause.elements.map((one) => (one.propertyName ?? one.name).text),
-        star,
+        namesImported(statement),
+        clause === undefined || isNamespaceExport(clause),
       );
     }
   }
@@ -158,11 +154,21 @@ export function outsideTestReferences(
       exported.set(key, [...(exported.get(key) ?? []), symbol.id]);
     }
   }
+  const declared = namedBy(held);
   const found: Reference[] = [];
   for (const { path, file } of tests) {
     const from = `${path}#`;
     const dir = dirnamePath(path) === "." ? "" : dirnamePath(path);
     for (const named of modulesNamed(file)) {
+      const position = renderPosition(file, targetRoot, named.specifier.getStart());
+      const read = (to: string, use: Reference["use"]): void => {
+        found.push({ from, to, position, use, resolution: "syntax", test: true, unheld: true });
+      };
+      for (const declaration of declared(named.text, named.names)) {
+        for (const to of [declaration.id, ...declaration.members]) {
+          read(to, "read");
+        }
+      }
       const written = named.text.includes("?") ? queriedModulePath(named.text) : named.text;
       if (written === undefined) {
         continue;
@@ -173,10 +179,6 @@ export function outsideTestReferences(
       if (fileId === undefined) {
         continue;
       }
-      const position = renderPosition(file, targetRoot, named.specifier.getStart());
-      const read = (to: string, use: Reference["use"]): void => {
-        found.push({ from, to, position, use, resolution: "syntax", test: true, unheld: true });
-      };
       if (named.evaluates) {
         read(fileId, "evaluation");
       }

package/src/overrides.ts

@@ -1,8 +1,9 @@
 /**
- * The overrides of the target's class members. A call through the base class, `this`
- * in the base's own body or a value typed as the base, names the base's member and
- * runs the override of whichever subclass the value is, so the base member's
- * declaration references every override as a use of it.
+ * The overrides of the target's class members. A call through the base class names the
+ * base's member and runs the override of whichever subclass the value is, so the base
+ * member's declaration references every override. A method overriding a member of a class
+ * declared outside the target, at any depth of its `extends` chain, is called by outside
+ * code holding the instance through that class, so its own class references it.
  */
 
 import {
@@ -18,6 +19,7 @@ import {
 import type { AliasChains } from "./alias-chain.ts";
 import { memberComponent } from "./class-members.ts";
 import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/unstable/sync";
 import { UNANSWERED } from "./query.ts";
 import type { Reference } from "./references.ts";
 import type { ProjectView } from "./session.ts";
@@ -58,9 +60,10 @@ function extending<Brand>(
 
 /**
  * The references each base class member makes to its overrides, for the classes of one
- * project that extend another class of the target. A member a nearer base already
- * overrides is reached through that override. A private member is not overridden.
- * Each reference is placed at the override and made by its file.
+ * project that extend another class of the target, and each class makes to its methods
+ * that override a member of a class declared outside the target. A member a nearer base
+ * already overrides is reached through that override. A private member is not
+ * overridden. Each reference is placed at the override and made by its file.
  */
 export function overrideReferences<Brand>(
   project: ProjectView<Brand>,
@@ -89,17 +92,28 @@ export function overrideReferences<Brand>(
     members.set(symbol.parent, own);
   }
   const bases = new Map<string, readonly string[]>();
+  const outsideBases = new Map<string, TSSymbol>();
+  const own = project.ownPaths();
   const symbols = project.symbolsAt(classes.map((one) => project.handle(one.base)));
   classes.forEach(({ id }, index) => {
     const symbol = symbols[index];
     if (symbol !== undefined && symbol !== UNANSWERED) {
-      bases.set(
-        id,
-        chains
-          .chainOf(symbol)
-          .map((target) => target.id)
-          .filter((target) => byId.get(target)?.kind === "class" && target !== id),
-      );
+      const inTarget = chains
+        .chainOf(symbol)
+        .map((target) => target.id)
+        .filter((target) => byId.get(target)?.kind === "class" && target !== id);
+      bases.set(id, inTarget);
+      const declared =
+        (symbol.flags & SymbolFlags.Alias) === 0 ? symbol : project.queries.aliased(symbol);
+      if (
+        inTarget.length === 0 &&
+        declared !== UNANSWERED &&
+        (declared.flags & SymbolFlags.Class) !== 0 &&
+        declared.declarations.length > 0 &&
+        declared.declarations.every((handle) => !own.has(handle.path))
+      ) {
+        outsideBases.set(id, declared);
+      }
     }
   });
 
@@ -117,6 +131,21 @@ export function overrideReferences<Brand>(
   };
 
   const found: Reference[] = [];
+  const outsideNames = outsideMemberNames(project, bases, outsideBases);
+  for (const [classId, names] of outsideNames) {
+    for (const [component, member] of members.get(classId) ?? []) {
+      if (member.kind === "method" && names.has(component)) {
+        found.push({
+          from: classId,
+          to: member.id,
+          position: member.position,
+          use: "read",
+          resolution: "override",
+          test: testFiles.has(member.position.path),
+        });
+      }
+    }
+  }
   for (const [classId, baseIds] of bases) {
     for (const [component, member] of members.get(classId) ?? []) {
       const seen = new Set([classId]);
@@ -134,3 +163,40 @@ export function overrideReferences<Brand>(
   }
   return found;
 }
+
+/**
+ * Per class of the target with a class declared outside the target in its `extends`
+ * chain, the names of the members that outside class's instances carry.
+ */
+function outsideMemberNames<Brand>(
+  project: ProjectView<Brand>,
+  bases: ReadonlyMap<string, readonly string[]>,
+  outsideBases: ReadonlyMap<string, TSSymbol>,
+): ReadonlyMap<string, ReadonlySet<string>> {
+  const direct = new Map<string, ReadonlySet<string>>();
+  for (const [classId, base] of outsideBases) {
+    const type = project.queries.declaredTypeOf(base);
+    const properties = type === UNANSWERED ? UNANSWERED : project.queries.propertiesOf(type);
+    if (properties !== UNANSWERED) {
+      direct.set(classId, new Set(properties.map((property) => property.escapedName)));
+    }
+  }
+  const names = new Map<string, ReadonlySet<string>>();
+  const above = (classId: string, seen: Set<string>): ReadonlySet<string> => {
+    if (seen.has(classId)) {
+      return new Set();
+    }
+    seen.add(classId);
+    return new Set([
+      ...(direct.get(classId) ?? []),
+      ...(bases.get(classId) ?? []).flatMap((base) => [...above(base, seen)]),
+    ]);
+  };
+  for (const classId of bases.keys()) {
+    const found = above(classId, new Set());
+    if (found.size > 0) {
+      names.set(classId, found);
+    }
+  }
+  return names;
+}

package/src/query.ts

@@ -203,11 +203,17 @@ export interface Queries {
   constituents(type: Type): Answer<readonly Type[]>;
   /** The generic type a type reference instantiates; the type itself for another type. */
   targetOf(type: Type): Answer<Type>;
+  /** The constraint of a type parameter, where it declares one; none for another type. */
+  constraintOf(type: Type): Answer<Type | undefined>;
   /** The symbol a type is declared by. */
   symbolOfType(type: Type): Answer<TSSymbol | undefined>;
   signaturesOf(type: Type, kind: SignatureKind): Answer<readonly Signature[]>;
   resolvedSignature(node: Node): Answer<Signature | undefined>;
   parameterType(signature: Signature, index: number): Answer<Type | undefined>;
+  /** The generic signature an instantiated one instantiates; none for another signature. */
+  genericOf(signature: Signature): Answer<Signature | undefined>;
+  /** The type of the parameter an argument at one position binds, a rest element's included. */
+  typeAtPosition(signature: Signature, index: number): Answer<Type>;
   signatureOf(declaration: Node): Answer<Signature | undefined>;
   returnTypeOf(signature: Signature): Answer<Type | undefined>;
   typeToString(type: Type): Answer<string>;
@@ -502,6 +508,14 @@ export function queriesOf(
             () => type.getTarget(),
           )
         : type,
+    constraintOf: (type) =>
+      type.isTypeParameter()
+        ? one(
+            "getConstraint",
+            () => typeLocation(type),
+            () => type.getConstraint(),
+          )
+        : undefined,
     symbolOfType: (type) =>
       one(
         "getSymbol",
@@ -526,6 +540,20 @@ export function queriesOf(
         () => `signature ${String(signature.id)} parameter ${String(index)}`,
         () => checker.getParameterType(signature, index),
       ),
+    genericOf: (signature) =>
+      signature.target === undefined
+        ? undefined
+        : one(
+            "getTarget",
+            () => `signature ${String(signature.id)}`,
+            () => signature.getTarget(),
+          ),
+    typeAtPosition: (signature, index) =>
+      one(
+        "getTypeParameterAtPosition",
+        () => `signature ${String(signature.id)} position ${String(index)}`,
+        () => signature.getTypeParameterAtPosition(index),
+      ),
     signatureOf: (declaration) =>
       one(
         "getSignatureFromDeclaration",

package/src/ref.ts

@@ -60,6 +60,7 @@ const REF_FORMS: readonly RegExp[] = REF_EXPRESSIONS.map(
 
 const IDENTIFIER = new RegExp(`^${TS_IDENT}$`, "u");
 const PRIVATE_NAME = new RegExp(`^#${TS_IDENT}$`, "u");
+// Stryker disable next-line Regex: its \v to \V mutant is no valid escape under the u flag, so the whole module fails to parse
 const ASCII_WHITESPACE = /[\t\n\v\f\r ]/gu;
 
 /** The section of a manifest that declares a dependency. */
@@ -168,6 +169,15 @@ export function renderRef(module: Module, fragment: Fragment): string {
   }
 }
 
+/**
+ * One declaration's key among a run's: its reference and the file that declares it. Two
+ * packages of one name spell one reference for two declarations, so the reference alone
+ * keys neither.
+ */
+export function declarationKey(ref: string, path: string): string {
+  return `${ref}\u0000${path}`;
+}
+
 /**
  * Whether one string is a reference of this language's grammar, in its canonical
  * spelling. A string that is not, whether misspelled or spelled in a form the

package/src/references.ts

@@ -42,6 +42,9 @@ import { specifierCandidates } from "./configuration-files.ts";
 import { namespaceUses } from "./namespace-objects.ts";
 import { globExpression } from "./glob.ts";
 import { declarationsByName, nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { augmentationReferences } from "./augmentations.ts";
+import { indexedAccessReferences } from "./indexed-access.ts";
+import { moduleDeclarationReferences } from "./module-declarations.ts";
 import { overrideReferences } from "./overrides.ts";
 import { dirnamePath, queriedModulePath, relativePath, resolvePath } from "./paths.ts";
 import { byPosition, isComponentFile, renderPosition, type Position } from "./position.ts";
@@ -1494,7 +1497,10 @@ export function references<Brand>(
 
   if (consumer === undefined) {
     found.push(...overrideReferences(project, held, chains, new Set(tests)));
+    found.push(...indexedAccessReferences(project, held, chains, root, new Set(tests)));
+    found.push(...moduleDeclarationReferences(project, held, root, new Set(tests)));
   }
+  found.push(...augmentationReferences(held, found));
   found.sort(
     (a, b) =>
       byPosition(a.position, b.position) ||

package/src/report.ts

@@ -19,7 +19,7 @@ import type { StaleSuppression } from "./findings/self-check.ts";
 import type { TestFileRule } from "./references.ts";
 
 /** The version of the report schema this analyzer writes a report to. */
-const SCHEMA_VERSION = "7.0.0";
+const SCHEMA_VERSION = "8.0.0";
 
 /** Every report schema version this analyzer reads: the one the Contract it implements admits. */
 export const SCHEMA_VERSIONS_ACCEPTED: readonly string[] = [SCHEMA_VERSION];
@@ -131,6 +131,11 @@ export interface WireTotals {
   readonly stale_suppressions: number;
   readonly pending: number;
   readonly omitted: number;
+  readonly withheld: {
+    readonly certain: number;
+    readonly probable: number;
+    readonly possible: number;
+  };
 }
 
 /** One project configuration of the matrix a run analyzed. */
@@ -438,6 +443,11 @@ function totalsOf(findings: readonly WireFinding[], result: PassResult): WireTot
     stale_suppressions: result.staleSuppressions.length,
     pending: result.totals.pending,
     omitted: 0,
+    withheld: {
+      certain: result.totals.withheld.certain,
+      probable: result.totals.withheld.probable,
+      possible: result.totals.withheld.possible,
+    },
   };
 }
 

package/src/reporters/sarif.ts

@@ -1,10 +1,12 @@
 import type { Confidence, Severity } from "../config.ts";
 import { jsonChunks } from "../json-chunks.ts";
 import { KINDS, type KindRow } from "../kinds.ts";
+import { declarationKey } from "../ref.ts";
 import type { Report, WireFinding, WireStaleSuppression } from "../report.ts";
 import { lineHashes, symbolFingerprint } from "./fingerprint.ts";
 import { RenderError, type RenderOptions } from "./reporter.ts";
 import { utf8Bytes } from "./sha256.ts";
+import { withheldLine } from "./text.ts";
 
 const SCHEMA =
   "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json";
@@ -159,7 +161,10 @@ function relatedOf(found: WireFinding): readonly Related[] {
     related.push({ label: "write", at, endLine: at.end_line });
   }
   for (const one of found.component.members ?? []) {
-    if (one.ref !== found.symbol.ref) {
+    if (
+      declarationKey(one.ref, one.position.path) !==
+      declarationKey(found.symbol.ref, found.position.path)
+    ) {
       related.push({ label: "member", at: one.position, endLine: one.position.end_line });
     }
   }
@@ -271,6 +276,7 @@ export function sarif(report: Report, options: RenderOptions): Iterable<string>
     ...report.stale_suppressions.map((stale) => staleResult(stale, index, hashOf)),
   ];
   const languages = [...report.analyzer.languages].sort().join("+");
+  const withheld = withheldLine(report.totals);
   const log = {
     $schema: SCHEMA,
     version: VERSION,
@@ -288,7 +294,8 @@ export function sarif(report: Report, options: RenderOptions): Iterable<string>
         columnKind: COLUMN_KIND,
         originalUriBaseIds: { [URI_BASE_ID]: { description: { text: ROOT_DESCRIPTION } } },
         results,
-        properties: { totals: report.totals },
+        properties:
+          withheld === undefined ? { totals: report.totals } : { totals: report.totals, withheld },
       },
     ],
   };

package/src/reporters/text.ts

@@ -24,11 +24,29 @@ function summary(totals: WireTotals): string {
   ].join(", ");
 }
 
+/** The confidences a withheld line names, from the highest the minimum can withhold. */
+const WITHHELD_ORDER = ["probable", "possible"] as const;
+
+/**
+ * The line naming what the minimum confidence withheld and the setting that shows it all,
+ * or undefined where it withheld nothing.
+ */
+export function withheldLine(totals: WireTotals): string | undefined {
+  const named = WITHHELD_ORDER.filter((confidence) => totals.withheld[confidence] > 0);
+  const lowest = named.at(-1);
+  if (lowest === undefined) {
+    return undefined;
+  }
+  const counts = named.map((confidence) => `${String(totals.withheld[confidence])} ${confidence}`);
+  return `withheld by analysis.min_confidence: ${counts.join(", ")}, shown with analysis.min_confidence set to ${lowest}`;
+}
+
 /**
  * One line per finding in the report's order, then one per stale suppression, then the
- * summary. A finding line is `path:line:col: kind name: message [confidence] (CODE)`; the
- * summary is deliberately not in that shape, so a filter for finding lines yields exactly
- * them. Nothing else is written: no timestamp, duration or host detail.
+ * withheld line where the minimum withheld a finding, then the summary. A finding line is
+ * `path:line:col: kind name: message [confidence] (CODE)`; the summary is deliberately not
+ * in that shape, so a filter for finding lines yields exactly them. Nothing else is
+ * written: no timestamp, duration or host detail.
  */
 export const text = (report: Report): Iterable<string> =>
   coalesced(
@@ -39,6 +57,10 @@ export const text = (report: Report): Iterable<string> =>
       for (const stale of report.stale_suppressions) {
         yield `${stale.position.path}:${String(stale.position.line)}:${String(stale.position.column)}: ${STALE_KIND} ${stale.symbol}: ${stale.message} [${STALE_CONFIDENCE}] (${stale.code})\n`;
       }
+      const withheld = withheldLine(report.totals);
+      if (withheld !== undefined) {
+        yield `${withheld}\n`;
+      }
       yield `${summary(report.totals)}\n`;
     })(),
   );