@cplieger/deadset-ts 7.0.0-dev.2 → 7.0.0-dev.3

package/src/matrix.ts

@@ -4,7 +4,7 @@
  * and intersected, with the dead components computed once over every configuration.
  */
 
-import { componentsOf, type Component } from "./components.ts";
+import { componentsOf, type Component, type Positional } from "./components.ts";
 import { graphOf, OUTSIDE, type Graph } from "./graph.ts";
 import type { InventorySymbol } from "./inventory.ts";
 import { byPosition } from "./position.ts";
@@ -36,6 +36,8 @@ export interface Configured {
    * finding.
    */
   readonly referenceOnly?: readonly string[] | undefined;
+  /** Each declaration's dependents, by id, as the configuration's inventory states them. */
+  readonly dependents?: ReadonlyMap<string, readonly string[]> | undefined;
 }
 
 /** The run's configurations, indexed for the sweep. */
@@ -56,6 +58,8 @@ export interface Matrix {
    * whose project holds it, in the run's order.
    */
   readonly heldIn: readonly (readonly string[])[];
+  /** Each declaration's dependents, by id, as the first configuration holding it states them. */
+  readonly dependents: ReadonlyMap<string, readonly string[]>;
 }
 
 /** One declaration dead in every configuration that holds it. */
@@ -128,7 +132,13 @@ export function matrixOf(per: readonly Configured[]): Matrix {
   const references: Reference[] = [];
   const firstSeen = new Map<string, number>();
   const judged = new Set<string>();
+  const dependents = new Map<string, readonly string[]>();
   per.forEach((one, index) => {
+    for (const [id, after] of one.dependents ?? []) {
+      if (!dependents.has(id)) {
+        dependents.set(id, after);
+      }
+    }
     const referenceOnly = new Set(one.referenceOnly);
     for (const symbol of one.symbols) {
       const held = holders.get(symbol.id);
@@ -168,6 +178,7 @@ export function matrixOf(per: readonly Configured[]): Matrix {
       [...new Set(per.flatMap((one) => one.supportFiles ?? []))],
     ),
     heldIn: symbols.map((symbol) => holders.get(symbol.id) ?? []),
+    dependents,
   };
 }
 
@@ -257,14 +268,16 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
     });
   });
 
+  const liveUnder = liveAnywhere(union.symbols, per);
   return {
-    liveUnder: liveAnywhere(union.symbols, per),
+    liveUnder,
     candidates,
     components: componentsOf(
       union,
       dead.map((one, at) => one && heldBy[at] === undefined),
       testOfDeadCode,
       unreferencedTest,
+      positionsOf(union, matrix.dependents, liveUnder),
     ),
   };
 }
@@ -286,6 +299,25 @@ export function liveFilesAt(
   );
 }
 
+/**
+ * Each declaration's dependents by its place in the union, and per place whether the
+ * declaration is live under reachability in some configuration.
+ */
+function positionsOf(
+  union: Graph,
+  dependents: ReadonlyMap<string, readonly string[]>,
+  liveUnder: ReadonlyMap<string, readonly Relation[]>,
+): Positional {
+  return {
+    dependents: union.symbols.map((symbol) =>
+      (dependents.get(symbol.id) ?? []).map((id) => union.at(id)).filter((at) => at !== OUTSIDE),
+    ),
+    live: union.symbols.map(
+      (symbol) => liveUnder.get(symbol.id)?.includes("reachability") === true,
+    ),
+  };
+}
+
 /** The relations in the order a declaration's entry lists them. */
 const RELATIONS: readonly Relation[] = ["reference-counting", "reachability"];
 

package/src/query.ts

@@ -205,6 +205,8 @@ export interface Queries {
   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 object and the index of an indexed-access type; none for another type. */
+  indexedAccessOf(type: Type): Answer<{ readonly object: Type; readonly index: Type } | undefined>;
   /** The symbol a type is declared by. */
   symbolOfType(type: Type): Answer<TSSymbol | undefined>;
   signaturesOf(type: Type, kind: SignatureKind): Answer<readonly Signature[]>;
@@ -516,6 +518,14 @@ export function queriesOf(
             () => type.getConstraint(),
           )
         : undefined,
+    indexedAccessOf: (type) =>
+      type.isIndexedAccessType()
+        ? one(
+            "getObjectType",
+            () => typeLocation(type),
+            () => ({ object: type.getObjectType(), index: type.getIndexType() }),
+          )
+        : undefined,
     symbolOfType: (type) =>
       one(
         "getSymbol",

package/src/references.ts

@@ -43,7 +43,10 @@ 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 { elementAccessReferences } from "./element-access.ts";
 import { indexedAccessReferences } from "./indexed-access.ts";
+import { keyofComparisonReferences } from "./keyof-comparisons.ts";
+import { unimplementedCalleeReads } from "./unimplemented-callees.ts";
 import { moduleDeclarationReferences } from "./module-declarations.ts";
 import { overrideReferences } from "./overrides.ts";
 import { dirnamePath, queriedModulePath, relativePath, resolvePath } from "./paths.ts";
@@ -185,6 +188,13 @@ export interface ReferenceCost {
   readonly contextualBatches: number;
   /** Per-type lookups for the contextual uses: each distinct type's constituents, properties and symbol. */
   readonly contextualLookups: number;
+  /**
+   * The requests the passes that read members through the checker's types make: element
+   * accesses, key comparisons, instantiated signatures and values handed to unimplemented
+   * callees. They are
+   * counted where the caller measures the client, through `requestCount`, and are 0 otherwise.
+   */
+  readonly typedLookups: number;
 }
 
 /** One project's references, in position order, and what reading them cost. */
@@ -221,6 +231,8 @@ export interface ReferenceOptions {
    * reference to a declaration of `held`, the target's, is recorded.
    */
   readonly consumer?: ConsumerSide;
+  /** The client's running request count, where the caller measures the client. */
+  readonly requestCount?: () => number;
 }
 
 /**
@@ -1556,12 +1568,21 @@ export function references<Brand>(
     }
   }
 
+  let typedLookups = 0;
   if (consumer === undefined) {
     found.push(...overrideReferences(project, held, chains, new Set(tests)));
+    const before = options.requestCount?.() ?? 0;
     found.push(...indexedAccessReferences(project, held, chains, root, new Set(tests)));
+    found.push(...elementAccessReferences(project, held, chains, root, new Set(tests)));
+    found.push(...keyofComparisonReferences(project, held, chains, root, new Set(tests)));
+    found.push(...unimplementedCalleeReads(project, held, chains, root, new Set(tests)));
+    typedLookups = (options.requestCount?.() ?? 0) - before;
     found.push(...moduleDeclarationReferences(project, held, root, new Set(tests)));
   }
-  found.push(...augmentationReferences(held, found));
+  const scripts = new Set(
+    walked.filter((one) => one.file.externalModuleIndicator === undefined).map((one) => one.fileId),
+  );
+  found.push(...augmentationReferences(held, found, scripts));
   found.sort(
     (a, b) =>
       byPosition(a.position, b.position) ||
@@ -1586,6 +1607,7 @@ export function references<Brand>(
       patternLookups: destructured.cost.patternLookups,
       contextualBatches: contextual.batches,
       contextualLookups: contextual.lookups,
+      typedLookups,
     },
   };
 }

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 = "8.0.0";
+const SCHEMA_VERSION = "8.1.0";
 
 /** Every report schema version this analyzer reads: the one the Contract it implements admits. */
 export const SCHEMA_VERSIONS_ACCEPTED: readonly string[] = [SCHEMA_VERSION];
@@ -45,6 +45,8 @@ interface WireDetails {
     readonly position: WirePosition;
   }[];
   readonly write_positions?: readonly WirePosition[];
+  /** Set under the name-literal rule, which no finding of this analyzer meets; SARIF still maps it. */
+  readonly name_literal?: WirePosition;
   readonly dependency_class?: string;
   readonly mechanism?: string;
   readonly entry?: {

package/src/reporters/sarif.ts

@@ -160,6 +160,10 @@ function relatedOf(found: WireFinding): readonly Related[] {
   for (const at of found.details.write_positions ?? []) {
     related.push({ label: "write", at, endLine: at.end_line });
   }
+  if (found.details.name_literal !== undefined) {
+    const at = found.details.name_literal;
+    related.push({ label: "name", at, endLine: at.end_line });
+  }
   for (const one of found.component.members ?? []) {
     if (
       declarationKey(one.ref, one.position.path) !==

package/src/serialization-contract.ts

@@ -1,12 +1,10 @@
 /**
- * The serialization-contract class: the data members and `toJSON` of every class,
- * interface and object type a value's static type names, and of every such type its
- * data members' types reach, where the value reaches `JSON.stringify` or a call
- * `ts.serializers` names, and those and `toString` where it is passed to an `unknown`
- * or `any` parameter of a function outside the analysis. A function of the project
- * handing such a parameter of its own to a destination is one, holding back what that
- * destination does, to a fixpoint. A function invoked through `Function.prototype.call`,
- * `apply` or `bind` is the callee, given the arguments those methods pass it.
+ * The serialization-contract class: the data members and `toJSON` of every type a value's
+ * static type reaches, where the value reaches `JSON.stringify` or a call `ts.serializers`
+ * names, and `toString` too where it reaches an `unknown` or `any` parameter of a function
+ * outside the analysis or an erased property of a type the program does not declare. A
+ * function of the project handing such a parameter to a destination is one, to a fixpoint,
+ * and a function invoked through `call`, `apply` or `bind` is the callee.
  */
 
 import {
@@ -59,6 +57,7 @@ import { nodeKey, type Inventory } from "./inventory.ts";
 import { renderPosition } from "./position.ts";
 import { must } from "./query.ts";
 import type { ProjectView } from "./session.ts";
+import { erasedStores, type ErasedStores } from "./erased-stores.ts";
 import { valueReach, type Reached } from "./value-reach.ts";
 
 /** The serializer every run reads, whatever the configuration names. */
@@ -527,13 +526,20 @@ function destinations<Brand>(
   return { invocation, at, mayReceive };
 }
 
-/** One argument whose value carries classes and object types of the target into a destination. */
+/** One value that carries classes and object types of the target into a destination. */
 interface Flow {
   readonly site: Node;
   readonly classes: ReadonlySet<string>;
   /** The members of the interfaces and object types the value carries. */
   readonly members: readonly TSSymbol[];
   readonly to: Destination;
+  /** What a retention names the destination by. */
+  readonly detail: string;
+}
+
+/** What two reaches carry together. */
+function joined(a: Reached, b: Reached): Reached {
+  return { classes: new Set([...a.classes, ...b.classes]), members: [...a.members, ...b.members] };
 }
 
 /** Each argument of a call that can receive one whose value carries a class of the target. */
@@ -542,8 +548,9 @@ function flowsOf<Brand>(
   held: Inventory,
   sites: readonly Site[],
   to: Destinations,
+  stores: ErasedStores,
 ): readonly Flow[] {
-  const reach = valueReach(project, held);
+  const reach = valueReach(project, held, stores.inside);
   const arguments_ = sites.flatMap((site) =>
     to.mayReceive(site.call)
       ? to.invocation(site.call).arguments.flatMap((argument, index) => {
@@ -560,7 +567,7 @@ function flowsOf<Brand>(
   const typeOf = new Map<Expression, Type | undefined>(
     asked.map((one, index) => [one.value, types[index]]),
   );
-  return arguments_.flatMap((one) => {
+  const passed = arguments_.flatMap((one) => {
     const type = typeOf.get(one.value);
     let reached: Reached = { classes: new Set<string>(), members: [] };
     if (one.value.kind === SyntaxKind.ThisKeyword) {
@@ -571,12 +578,38 @@ function flowsOf<Brand>(
     } else if (type !== undefined) {
       reached = reach.reachedFrom(type);
     }
+    for (const stored of stores.ofVariable(one.value) ?? []) {
+      reached = joined(reached, reach.reachedFrom(stored));
+    }
     const carries = reached.classes.size > 0 || reached.members.length > 0;
     const destination = carries ? to.at(one.site.call, one.argument) : undefined;
     return destination === undefined
       ? []
-      : [{ site: one.value, classes: reached.classes, members: reached.members, to: destination }];
+      : [
+          {
+            site: one.value,
+            classes: reached.classes,
+            members: reached.members,
+            to: destination,
+            detail: `passed to ${destination.callee}`,
+          },
+        ];
+  });
+  const left = stores.outside.flatMap((store) => {
+    const reached = reach.reachedFrom(store.type);
+    return reached.classes.size === 0 && reached.members.length === 0
+      ? []
+      : [
+          {
+            site: store.value,
+            classes: reached.classes,
+            members: reached.members,
+            to: { reach: "conversions" as const, callee: store.property },
+            detail: `stored in the property ${store.property} of a type the program does not declare`,
+          },
+        ];
   });
+  return [...passed, ...left];
 }
 
 /**
@@ -589,7 +622,13 @@ export function serializationContract<Brand>(input: DetectorInput<Brand>): reado
   const { project, held, targetRoot } = input;
   const walked = walkProject(project, held);
   const chains = aliasChains(project, held);
-  const flows = flowsOf(project, held, walked.sites, destinations(input, chains, walked));
+  const flows = flowsOf(
+    project,
+    held,
+    walked.sites,
+    destinations(input, chains, walked),
+    erasedStores(project),
+  );
   if (flows.length === 0) {
     return [];
   }
@@ -609,7 +648,7 @@ export function serializationContract<Brand>(input: DetectorInput<Brand>): reado
   const found: Evidence[] = [];
   for (const flow of flows) {
     const site = renderPosition(flow.site.getSourceFile(), targetRoot, flow.site.getStart());
-    const detail = `passed to ${flow.to.callee}`;
+    const { detail } = flow;
     for (const member of [...flow.classes].flatMap((id) => members.get(id) ?? [])) {
       const symbol = byId.get(member.id);
       const name = symbol === undefined ? "" : (memberComponent(symbol, byId) ?? "");

package/src/session.ts

@@ -28,13 +28,10 @@ import {
 } from "./query.ts";
 
 /**
- * The compiler the analysis reads through. It is a client over a protocol to a
- * separate process, so every accessor call is a round trip and a run holds one
- * client and one snapshot.
- *
- * It is an interface because the run's own accounting for that lifetime is not on
- * the client's surface: a snapshot reports whether it is disposed and not how many
- * a client opened, so the count is observed at this seam.
+ * The compiler the analysis reads through: a client over a protocol to a separate
+ * process, so every accessor call is a round trip and a run holds one client and one
+ * snapshot. It is an interface because a snapshot reports whether it is disposed and not
+ * how many a client opened, so the run's count of them is observed at this seam.
  */
 export interface Engine {
   /**
@@ -187,14 +184,10 @@ export function openEngine(options: EngineOptions): Engine {
 }
 
 /**
- * A node of one project's program, carried with that project's identity.
- *
- * `Brand` is a type parameter and never a value: a view is handed to a visitor
- * that introduces its own `Brand`, so two projects' views have handle types the
- * compiler will not exchange and a handle cannot reach another project's checker.
- * Handles are only meaningful inside the program that produced them, and the
- * cross-project step of the analysis compares rendered positions rather than
- * handles.
+ * A node of one project's program, carried with that project's identity. `Brand` is a
+ * type parameter and never a value: each visitor introduces its own, so two projects'
+ * handle types do not exchange and a handle cannot reach another project's checker. The
+ * cross-project step compares rendered positions, never handles.
  */
 export interface Handle<Brand> {
   readonly node: Node;
@@ -253,14 +246,11 @@ export interface ProjectView<Brand> {
    */
   aliasStepOf(symbol: TSSymbol): Answer<TSSymbol | undefined>;
   /**
-   * The node one symbol's declaration handle names, read in this project's program,
-   * or `undefined` where this project's program does not hold that file.
-   *
-   * A symbol is shared by every project of the snapshot and remembers the project it
-   * was first seen in, so resolving its handle without saying which program to read
-   * would answer out of whichever project reached the symbol first. The project is
-   * named here instead, and the answer becomes a handle of this project like any
-   * other. The read is local once the file has been fetched.
+   * The node one symbol's declaration handle names, read in this project's program, or
+   * `undefined` where this program does not hold that file. A symbol is shared by every
+   * project of the snapshot and remembers the one it was first seen in, so the project is
+   * named here, or the answer would come from whichever project reached the symbol first.
+   * The read is local once the file has been fetched.
    */
   declarationAt(handle: NodeHandle): Handle<Brand> | undefined;
 }
@@ -272,6 +262,13 @@ export interface ProjectView<Brand> {
  */
 export type ProjectVisitor<Result> = <Brand>(project: ProjectView<Brand>) => Result;
 
+/** One project a session opened: its configuration and the files of its own program. */
+export interface OpenedFiles {
+  readonly configFile: string;
+  /** The program's source files no default library and no external library holds. */
+  readonly fileNames: () => readonly string[];
+}
+
 /**
  * The source files of one program that `own` admits, in the program's order, none of
  * them one of the compiler's default libraries.
@@ -487,10 +484,10 @@ function projectsOf(
 /**
  * Runs `visit` over every project the compiler configurations name, inside one never updated
  * snapshot of one client, and answers in their order. A configuration `programs` describes is
- * built as that program, or opened from the configuration it writes, instead of as a project.
- * One the snapshot holds nothing for ends the run under `"refuse"` and is named in the result
- * under `"record"`. `last` runs after the last visit while the client still answers; the
- * snapshot is disposed and the client released after it, whether the visit completed or threw.
+ * built as that program, or opened from the configuration it writes. One the snapshot holds
+ * nothing for ends the run under `"refuse"` and is named in the result under `"record"`.
+ * `first` runs over every opened project before the first visit and `last` after the last,
+ * both while the client answers; the snapshot and the client are then released.
  */
 export function runSession<Result>(
   engine: Engine,
@@ -499,6 +496,7 @@ export function runSession<Result>(
   unopened: Unopened = "refuse",
   programs: ReadonlyMap<string, WorkspaceProgram> = new Map(),
   last: () => void = () => undefined,
+  first: (opened: readonly OpenedFiles[]) => void = () => undefined,
 ): SessionResult<Result> {
   try {
     const built: string[] = [];
@@ -523,7 +521,7 @@ export function runSession<Result>(
     try {
       const opened = projectsOf(snapshot, built, written);
       const log = new UnansweredLog();
-      const projects: Result[] = [];
+      const views: ProjectView<unknown>[] = [];
       const missing: string[] = [];
       for (const configFile of configFiles) {
         const project = opened.get(configFile);
@@ -534,8 +532,15 @@ export function runSession<Result>(
           missing.push(configFile);
           continue;
         }
-        projects.push(visit(viewOf(project, configFile, engine, log)));
+        views.push(viewOf(project, configFile, engine, log));
       }
+      first(
+        views.map((view) => ({
+          configFile: view.configFile,
+          fileNames: () => view.ownSourceFiles().map((file) => file.fileName),
+        })),
+      );
+      const projects = views.map((view) => visit(view));
       last();
       return {
         projects,

package/src/suppress-file.ts

@@ -59,6 +59,13 @@ const BASELINE_SHAPE: Shape = {
   recordWant: "a row naming code, symbol, path and reason, each a string",
 };
 
+/**
+ * The reference scheme of this analyzer's language. A record of the other scheme is
+ * form-checked and then left to the analyzer of its language: it binds nothing here, counts
+ * in neither total and is reported under no code.
+ */
+const OWN_SCHEME = "ts://";
+
 /** The closed key list of one entry or row. */
 const RECORD_KEYS: ReadonlySet<string> = new Set(["code", "symbol", "path", "reason"]);
 
@@ -126,6 +133,9 @@ function readRecord(value: unknown, site: Position, byReference: ByReference, sh
   if (path !== undefined && path !== "" && !isEntryPath(path)) {
     return refuse(JSON.stringify(path), PATH_WANT);
   }
+  if (!symbol.startsWith(OWN_SCHEME)) {
+    return { records: [], refusals: [] };
+  }
 
   const written = {
     code,
@@ -284,15 +294,68 @@ export function rowReason(provenance: Provenance): string {
   return `recorded by ${provenance.analyzer} ${provenance.version}`;
 }
 
+/** A row of the other language's scheme a write keeps: the members the document held, and no other. */
+interface KeptRow {
+  readonly code: string;
+  readonly symbol: string;
+  readonly path?: string;
+  readonly reason?: string;
+}
+
+/**
+ * The rows of the other language's scheme that the baseline document `text` holds, in
+ * document order and as written, which a write keeps. A document that is not a baseline,
+ * or a row in a shape no record takes, is refused rather than dropped.
+ */
+export function otherSchemeRows(text: string): readonly KeptRow[] {
+  const refuse = (detail: string): never => {
+    throw new Error(
+      `${BASELINE_FILE} cannot be rewritten keeping the other language's rows: ${detail}`,
+    );
+  };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error: unknown) {
+    return refuse(error instanceof Error ? error.message : String(error));
+  }
+  const held = isObject(parsed) ? parsed[BASELINE_SHAPE.array] : undefined;
+  if (!Array.isArray(held)) {
+    return refuse(BASELINE_SHAPE.documentWant);
+  }
+  return (held as readonly unknown[]).flatMap((value): KeptRow[] => {
+    try {
+      readRecord(value, documentSite(BASELINE_SHAPE), new Map(), BASELINE_SHAPE);
+    } catch (error: unknown) {
+      return refuse(error instanceof Error ? error.message : String(error));
+    }
+    // readRecord has checked every member is a string and the code and symbol are present.
+    const { code, symbol, path, reason } = value as Readonly<Record<string, string>>;
+    if (code === undefined || symbol === undefined || symbol.startsWith(OWN_SCHEME)) {
+      return [];
+    }
+    return [
+      {
+        code,
+        symbol,
+        ...(path === undefined ? {} : { path }),
+        ...(reason === undefined ? {} : { reason }),
+      },
+    ];
+  });
+}
+
 /**
- * A baseline holding one row per finding, in the order given, which is the report's. Every
- * row carries the provenance as its reason. A finding missing a value a row needs, and an
- * identity missing its name or version, are refused rather than written, because the
- * grammar requires a reason on every row.
+ * A baseline holding one row per finding, in the order given, which is the report's, after
+ * the other language's rows `kept`, so two analyzers writing one document in either order
+ * write the same bytes. Every recorded row carries the provenance as its reason. A finding
+ * missing a value a row needs, and an identity missing its name or version, are refused
+ * rather than written, because the grammar requires a reason on every row.
  */
 export function writeBaseline(
   findings: readonly Recorded[],
   provenance: Provenance,
+  kept: readonly KeptRow[] = [],
 ): Iterable<string> {
   if (provenance.analyzer === "" || provenance.version === "") {
     throw new Error(
@@ -308,5 +371,5 @@ export function writeBaseline(
     }
     return { code: found.code, symbol: found.symbol, path: found.path, reason };
   });
-  return jsonChunks({ description: BASELINE_DESCRIPTION, baseline }, 2);
+  return jsonChunks({ description: BASELINE_DESCRIPTION, baseline: [...kept, ...baseline] }, 2);
 }

package/src/suppress-inline.ts

@@ -1,7 +1,7 @@
 /**
  * The inline directive: `deadset:ignore`, the first token of a `//` line comment, naming
  * one or more codes and a reason, and binding to every declaration that begins on the line
- * below it.
+ * below it, or on its own line where it trails a token there.
  */
 
 import { SyntaxKind, type Node, type SourceFile } from "@typescript/native/unstable/ast";
@@ -211,6 +211,15 @@ function declarationLines(
   return below;
 }
 
+/**
+ * Whether the comment at `offset` follows a token on its own line, so it binds the
+ * declarations that begin on that line rather than on the next.
+ */
+function trails(file: SourceFile, offset: number): boolean {
+  const { line } = file.getLineAndCharacterOfPosition(offset);
+  return tokenStart(file.text, file.getPositionOfLineAndCharacter(line, 0)) < offset;
+}
+
 /** One comment in the namespace, what the grammar made of it, and what it bound. */
 export interface InlineDirective {
   readonly site: Position;
@@ -242,11 +251,12 @@ export function inlineDirectives<Brand>(
     const below = declarationLines(file, held, symbols);
     for (const comment of comments) {
       const site = renderPosition(file, targetRoot, comment.offset);
+      const target = trails(file, comment.offset) ? site.line : site.line + 1;
       found.push({
         site,
         text: comment.text,
         directive: classifyComment(comment.text),
-        bound: [...(below.get(site.line + 1) ?? [])],
+        bound: [...(below.get(target) ?? [])],
       });
     }
   }
@@ -254,8 +264,8 @@ export function inlineDirectives<Brand>(
 }
 
 /**
- * The inline directives of a run's projects, each bound to the declarations that begin on
- * the line below it, one directive binding the union of what each project holding its file
+ * The inline directives of a run's projects, each bound to the declarations the placement
+ * rule gives it, one directive binding the union of what each project holding its file
  * declares there. A directive that lacks only its reason is one {@link Refusal} per code;
  * any other malformed comment in the namespace ends the read with a
  * {@link SuppressionError} naming the first one written.