@cplieger/deadset-ts 8.0.0-dev.20 → 8.0.0-dev.21

package/src/analysis.ts

@@ -15,7 +15,6 @@ import {
   configuredRef,
   declarationsNamed,
 } from "./roots/configured-declarations.ts";
-import { decorator } from "./decorator.ts";
 import { configurationNeeds, dependenciesOf, projectNeeds } from "./dependencies.ts";
 import { carriersOf, NO_CARRIERS, type Carriers } from "./exposure.ts";
 import { deprecatedDeclarations, type Deprecation } from "./deprecation.ts";
@@ -26,32 +25,19 @@ import type { AppliedConvention } from "./entries/conventions.ts";
 import { readSources, type SourceFacts } from "./entries/sources.ts";
 import { readWorkflows, type Workflows } from "./entries/workflow-steps.ts";
 import { readEdgeSides } from "./edges.ts";
-import { enumGroup } from "./enum-group.ts";
 import { bindingsOf, distinctBindings, type BindingRecord } from "./bindings.ts";
-import { generatedFile, generatedFilesOf, type GeneratedFact } from "./generated-file.ts";
+import { generatedFilesOf, type GeneratedFact } from "./exemptions/generated-file.ts";
 import { inOperandNames } from "./findings/in-operands.ts";
 import { sourceFilesOf } from "./source-files.ts";
-import {
-  evidenceRecords,
-  heldRecords,
-  disabledClasses,
-  exemptionsOf,
-  isUnansweredRecord,
-  writtenRecords,
-  type Detector,
-  type Detectors,
-} from "./exempt.ts";
-import type { TSExemptionClass } from "./exempt-classes.ts";
+import { DETECTORS, detection } from "./exemptions/detectors.ts";
+import { exemptionsOf, settle, type Detectors, type Exemption } from "./exemptions/lifecycle.ts";
 import { heldByInclusion, sourcePaths, sourceTree } from "./file-facts.ts";
 import type { Finding } from "./finding.ts";
 import { findingsPass, recordedFindings, rowKey, type PassResult } from "./findings-pass.ts";
 import type { EmitterInput } from "./findings/emitter.ts";
 import { unmatchedRootFindings, type SelfCheckFacts } from "./findings/self-check.ts";
-import { frameworkLifecycle } from "./framework-lifecycle.ts";
 import type { Host } from "./host.ts";
 import { implementations, mergeImplementations } from "./findings/implementations.ts";
-import { injectionContainer } from "./injection-container.ts";
-import { interfaceSatisfaction, settledSatisfaction } from "./interface-satisfaction.ts";
 import { intraFunctionFacts, projectParts, type ProjectParts } from "./intra-function-parts.ts";
 import { type Inventory, type InventorySymbol } from "./inventory.ts";
 import { inventory } from "./inventory/enumerate.ts";
@@ -69,7 +55,6 @@ import type { UnansweredQuestion } from "./query.ts";
 import { byPosition, isComponentFile, type Position } from "./position.ts";
 import type { TypeErrorSkip, UnansweredCount } from "./report.ts";
 import { skippedUnits, type SkippedUnit } from "./type-errors.ts";
-import { reflectiveLookup } from "./reflective-lookup.ts";
 import { references, type Reference } from "./references.ts";
 import {
   rootSet,
@@ -79,7 +64,7 @@ import {
   type HeldScripts,
 } from "./roots/root-set.ts";
 import type { Scope } from "./scope.ts";
-import { decodedMembers, serializationContract, type Decoded } from "./serialization-contract.ts";
+import { decodedMembers, type Decoded } from "./exemptions/serialization-contract.ts";
 import { outsideTestReferences, testFilesAt, type OutsideTest } from "./tests/outside.ts";
 import type { UnseenLoad } from "./roots/unseen-loads.ts";
 import type { UnresolvedSpecifier } from "./load/specifiers.ts";
@@ -100,9 +85,7 @@ import { isPartKind, type SuppressionRecord, type Suppressions, type Verdict } f
 import { bindRows, readBaseline, readIgnoreFile, type Recorded } from "./suppress-file.ts";
 import { inlineDirectives, inlineSuppressions, type InlineDirective } from "./suppress-inline.ts";
 import { sweep, type Sweep, type SweepPolicy } from "./liveness/sweep.ts";
-import type { Exemption } from "./exempt.ts";
 import type { Mode } from "./tests/file-class.ts";
-import { readTemplates, templateField } from "./template-field.ts";
 import { bytewise } from "./text/compare.ts";
 import { holdsManifest, manifestAt } from "./fs/manifest.ts";
 import { runDirectories } from "./entries/run-directories.ts";
@@ -444,19 +427,6 @@ interface ComponentWarning {
   readonly reason: string;
 }
 
-/** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
-export const DETECTORS: Detectors = new Map<TSExemptionClass, Detector>([
-  ["interface-satisfaction", interfaceSatisfaction],
-  ["enum-group", enumGroup],
-  ["generated-file", generatedFile],
-  ["template-field", templateField],
-  ["reflective-lookup", reflectiveLookup],
-  ["decorator", decorator],
-  ["injection-container", injectionContainer],
-  ["framework-lifecycle", frameworkLifecycle],
-  ["serialization-contract", serializationContract],
-]);
-
 /** What the sweep of one run reads of each project, beside what a caller's stage adds. */
 interface SweptProject<Extra> {
   readonly configFile: string;
@@ -599,11 +569,8 @@ function readRun<Extra>(
   ) => Extra,
 ): ReadRun<Extra> {
   const targetRoot = scope.target.path;
-  const disabled = disabledClasses(config);
-  const templates = disabled.has("template-field")
-    ? { delimiters: config.analysis.template_delimiters, files: [] }
-    : readTemplates(host, targetRoot, config.analysis);
   const consumers = scope.consumers.map((consumer) => consumer.path);
+  const detect = detection(host, targetRoot, config, consumers, detectors);
   const directories = runDirectories(host, targetRoot, (fileName, text) =>
     engine.parseSourceFile(fileName, text),
   );
@@ -616,21 +583,7 @@ function readRun<Extra>(
       formedForNode: projectRead.formedForNode,
     });
     const testFiles = testFilePaths(project, targetRoot, testFile);
-    const evidence = evidenceRecords(
-      {
-        project,
-        held: projectRead.held,
-        targetRoot,
-        templates,
-        ts: config.ts,
-        consumers,
-        ...(config.analysis.generated_files === "include"
-          ? {}
-          : { generated: projectRead.generated }),
-      },
-      detectors,
-      disabled,
-    );
+    const evidence = detect({ project, held: projectRead.held, generated: projectRead.generated });
     const components = project.ownSourceFiles().filter(isComponentFile);
     const injected = project.program
       .getSourceFileNames()
@@ -724,30 +677,29 @@ function readRun<Extra>(
       ...one.decoded.copied,
     ]),
   ]);
-  const evidence = withOutside.map((one) => writtenRecords(one.evidence, written));
-  const settled = settledSatisfaction(
-    withOutside.map((one, index) => ({
-      evidence: evidence[index] ?? [],
+  const settled = settle(
+    withOutside.map((one) => ({
+      records: one.evidence,
       held: one.projectRead.held,
+      testFiles: new Set([...one.testFiles, ...support]),
     })),
-    [...withOutside.flatMap((one) => one.references), ...read.result.references],
+    {
+      references: [...withOutside.flatMap((one) => one.references), ...read.result.references],
+      written,
+      mode,
+    },
   );
   const answers = withOutside.map((one, index): SweptProject<Extra> => {
     const { projectRead } = one;
-    const satisfied = settled[index];
-    const detected = heldRecords(satisfied?.evidence ?? evidence[index] ?? [], {
-      mode,
-      testFiles: new Set([...one.testFiles, ...support]),
-    });
-    const exempt = detected.records;
-    const made = [...one.references, ...(satisfied?.references ?? [])];
+    const exempt = settled[index]?.records ?? [];
+    const made = [...one.references, ...(settled[index]?.references ?? [])];
     const held = new Set(projectRead.held.symbols.map((symbol) => symbol.position.path));
     const supportFiles = [...support].filter((path) => held.has(path)).sort(bytewise);
     const testUsedFiles = [...testUsed].filter((path) => held.has(path)).sort(bytewise);
     const configured: Configured = {
       configuration: projectRead.configuration,
       symbols: projectRead.held.symbols,
-      references: [...made, ...evidenceReferences(projectRead.held.symbols, detected.inTestFiles)],
+      references: made,
       roots: projectRead.rooted.liveUnderReachability,
       testFiles: [...one.testFiles, ...supportFiles],
       ...(supportFiles.length === 0 ? {} : { supportFiles }),
@@ -769,7 +721,7 @@ function readRun<Extra>(
         ...projectRead.rooted.unanswered,
         ...made.filter((reference) => reference.guessed === true).map((reference) => reference.to),
         ...one.held,
-        ...exempt.filter(isUnansweredRecord).map((record) => record.id),
+        ...exempt.filter((record) => record.unanswered === true).map((record) => record.id),
         ...one.decoded.unanswered,
       ],
       filledOutside: one.decoded.filled,
@@ -822,39 +774,6 @@ function readRun<Extra>(
   };
 }
 
-/**
- * The test references exemption evidence written in a test file makes: each is a read of
- * the declaration it would retain, made by the test file at the evidence's site.
- */
-function evidenceReferences(
-  symbols: readonly InventorySymbol[],
-  inTestFiles: readonly Exemption[],
-): readonly Reference[] {
-  if (inTestFiles.length === 0) {
-    return [];
-  }
-  const files = new Map(
-    symbols
-      .filter((symbol) => symbol.kind === "file")
-      .map((symbol) => [symbol.position.path, symbol.id]),
-  );
-  return inTestFiles.flatMap((record) => {
-    const from = files.get(record.site.path);
-    return from === undefined
-      ? []
-      : [
-          {
-            from,
-            to: record.id,
-            position: record.site,
-            use: "read",
-            resolution: "syntax",
-            test: true,
-          },
-        ];
-  });
-}
-
 /**
  * The declarations a write the mode counts stores into, a write a test-support file
  * makes being a test's.

package/src/bindings.ts

@@ -29,7 +29,7 @@ import {
   type SourceFile,
 } from "@typescript/native/ast";
 import { GENERATORS } from "./contract/contract.generated.ts";
-import type { GeneratedFact } from "./generated-file.ts";
+import type { GeneratedFact } from "./exemptions/generated-file.ts";
 import { componentOf, nameNodeOf } from "./inventory.ts";
 import { nameComponent, spell } from "./ref.ts";
 import { bytewise } from "./text/compare.ts";

package/src/conformance-record.ts

@@ -2,9 +2,9 @@
 // Regenerate it with `UPDATE_GOLDEN=1 npx vitest --run src/conformance.corpus.test.ts`.
 export const RECORD = {
   conformance: {
-    corpusVersion: "6.0.0",
+    corpusVersion: "6.1.0",
     result: "pass",
-    digest: "sha256:e4af2b9bcd07fd745101bf3215cd21e9df1448bdc332a791f25d5676cf15c794",
+    digest: "sha256:352b870acbc05213d4869bc18611137d0782cc0c9a8379e7a998a3d9cea2d966",
   },
   gaps: [],
 } as const;

package/src/contract/contract.generated.ts

@@ -4,7 +4,7 @@ export const CONTRACT_VERSION = "8.0.0";
 export const SCHEMA_VERSIONS = ["9.0.0"] as const;
 export const SCHEMA_VERSION = "9.0.0";
 export const FACTS_VERSION = "1.0.0";
-export const CORPUS_VERSION = "6.0.0";
+export const CORPUS_VERSION = "6.1.0";
 export const CODE_PREFIX = "DS";
 export const FAMILY_KEY_LENGTH = 4;
 
@@ -421,7 +421,7 @@ export const KIND_ROWS = [
     languages: ["go", "ts"],
     subject: "declaration",
     holdsLive: true,
-    rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method. Three subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface, and so is a method whose name and signature are those of a method of an exported interface type declared by a package outside the target that the import closure holds, because that interface fixes them whether or not the program converts the method's type to it. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending. A reference from a Go external test package, a test file whose package clause names its directory's package with the suffix _test, is a reference from outside the package, because that test builds as another package and needs the export.",
+    rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method. Four subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface, and so is a method whose name and signature are those of a method of an exported interface type declared by a package outside the target that the import closure holds, because that interface fixes them whether or not the program converts the method's type to it. A Go function a driver finds by its exported name is excluded, whatever else refers to it, because unexporting it stops the driver from running it: a test, a benchmark, a fuzz test or an example of a test file, TestMain, a test method a suite runner calls, and a go-fuzz entry point. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending. A reference from a Go external test package, a test file whose package clause names its directory's package with the suffix _test, is a reference from outside the package, because that test builds as another package and needs the export.",
     precondition:
       "Closed world only. A Go main package, and an internal/ directory tree for importers outside its parent, are closed worlds whatever the configuration declares, because no other program can import them, so this finding is reported there always. A published package is a closed world only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type is not reported when a reference from outside the package reaches its values through its own package's exported declarations: a reference to an exported function or method whose parameters or results name the type, to an exported variable or constant whose type names it, to an exported field or property whose type names it, an embedded field included, or to an exported member of the type itself, a field promoted through an embedding included. A type a reference from outside the package names, or whose values such a reference reaches, passes the reach on to each type its definition names other than through an unexported member, whether it is exported or not, so an unexported type an exported function returns passes it to the types its exported fields name. A type names another through every composite that spells it: a pointer, an array, a slice, a map key or value, a channel, a function signature and a type argument. The referencing code holds values of the type, so unexporting it would leave an exported declaration naming a type its users cannot name. A package-level declaration whose name a string literal spells carries the class grammar/analysis/confidence.md gives it.",
     details: { narrower_visibility: "required", name_literal: "optional" },
@@ -437,7 +437,7 @@ export const KIND_ROWS = [
     languages: ["go"],
     subject: "declaration",
     holdsLive: true,
-    rule: "An exported symbol of a non-internal package whose every reference is inside the target module, reported as a candidate for relocation behind an internal boundary. The subject is a package-level declaration or a method. Three subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface, and so is a method whose name and signature are those of a method of an exported interface type declared by a package outside the target that the import closure holds, because that interface fixes them whether or not the program converts the method's type to it. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending. A reference from a Go external test package, a test file whose package clause names its directory's package with the suffix _test, is a reference from outside the package, because that test builds as another package and needs the export.",
+    rule: "An exported symbol of a non-internal package whose every reference is inside the target module, reported as a candidate for relocation behind an internal boundary. The subject is a package-level declaration or a method. Four subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface, and so is a method whose name and signature are those of a method of an exported interface type declared by a package outside the target that the import closure holds, because that interface fixes them whether or not the program converts the method's type to it. A Go function a driver finds by its exported name is excluded, whatever else refers to it, because unexporting it stops the driver from running it: a test, a benchmark, a fuzz test or an example of a test file, TestMain, a test method a suite runner calls, and a go-fuzz entry point. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending. A reference from a Go external test package, a test file whose package clause names its directory's package with the suffix _test, is a reference from outside the package, because that test builds as another package and needs the export.",
     precondition:
       "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type is not reported when a reference from outside the target module reaches its values through its own package's exported declarations, as DS1501 defines that reach, because the referencing code holds values of the type, and moving it behind an internal boundary would leave an exported declaration naming a type its users cannot name.",
     details: { narrower_visibility: "required", name_literal: "optional" },
@@ -1444,6 +1444,7 @@ export const FAILURE_CLASSES = {
   "unwritten-output": "run",
   "unreportable-path": "run",
   "memory-exhausted": "run",
+  "missing-toolchain": "run",
   "missing-analyzer": "run",
   "unadmitted-analyzer": "run",
   "unresolved-edge": "run",

package/src/dependencies.ts

@@ -202,7 +202,7 @@ export function packageOfSpecifier(specifier: string): string | undefined {
 }
 
 /** The package an installed file belongs to, read below the last dependency directory of its path. */
-function packageOfPath(path: string): string | undefined {
+export function packageOfPath(path: string): string | undefined {
   const at = path.lastIndexOf(MODULES_SEGMENT);
   return at < 0 ? undefined : packageOfSpecifier(path.slice(at + MODULES_SEGMENT.length));
 }

package/src/exemptions/argument-places.ts

@@ -0,0 +1,198 @@
+/**
+ * Which parameter place each argument of a call binds, the one reading every question
+ * about a call's arguments asks. A plain argument fills the next place, and a spread or
+ * an `apply` list typed as a tuple whose elements are all required fills one place per
+ * element. Any other spread or list has no known length: from its first place on, each of
+ * its element types, and every later argument, may fill any place, so a value is never
+ * read as missing a parameter only because its place could not be read. The type at each
+ * place is the checker's answer for it, so this reading names places and never types them.
+ */
+
+import { isSpreadElement, type Expression } from "@typescript/native/ast";
+import { ElementFlags, type Signature, type Type } from "@typescript/native/sync";
+import { must } from "../query.ts";
+import type { ProjectView } from "../session.ts";
+
+/** The places one argument fills. */
+export interface Span {
+  /** The argument's index among the invocation's arguments. */
+  readonly argument: number;
+  /** The first place it can fill. */
+  readonly first: number;
+  /** The type at each place from `first` on, or, where `open`, at any place from it on. */
+  readonly given: readonly (Type | undefined)[];
+  /** Whether the argument's length, or the length of a spread before it, is unknown. */
+  readonly open: boolean;
+  /** Whether the argument is a spread or a list, whose value is its elements. */
+  readonly spread: boolean;
+}
+
+/** One argument at one parameter place, with the type it gives there. */
+export interface Placed {
+  readonly argument: number;
+  /** The index in the argument's span `given` of the type it gives there. */
+  readonly element: number;
+  readonly place: number;
+  readonly given: Type | undefined;
+  /** Whether the signature has no such place, so it says nothing of what the argument keeps. */
+  readonly uncovered: boolean;
+  /**
+   * Whether it stands for every place of a rest from `place` on, an argument of unknown
+   * length there taking any type the rest's element type holds.
+   */
+  readonly rest: boolean;
+}
+
+/**
+ * How many places a signature has. Where it `repeats`, its rest has no fixed length and
+ * `count` ends at the rest's first place: the checker answers each place past it, and an
+ * argument of unknown length meets every one of them.
+ */
+export interface Layout {
+  readonly count: number;
+  readonly repeats: boolean;
+}
+
+/** The element flags of a tuple type; none for another type. */
+function elementFlags<Brand>(project: ProjectView<Brand>, type: Type): readonly ElementFlags[] {
+  const target = type.isTupleType() ? must(project.queries.targetOf(type)) : undefined;
+  return target?.isTupleTypeTarget() === true ? target.elementFlags : [];
+}
+
+/** What a spread argument puts at the places it fills, and how many it fills at least. */
+function spread<Brand>(
+  project: ProjectView<Brand>,
+  type: Type | undefined,
+): {
+  readonly types: readonly (Type | undefined)[];
+  readonly fixed: boolean;
+  readonly least: number;
+} {
+  const { queries } = project;
+  if (type === undefined) {
+    return { types: [undefined], fixed: false, least: 0 };
+  }
+  if (type.isTupleType()) {
+    const flags = elementFlags(project, type);
+    return {
+      types: must(queries.typeArguments(type)).slice(0, flags.length),
+      fixed: flags.every((flag) => (flag & ElementFlags.Required) !== 0),
+      least: flags.filter((flag) => (flag & ElementFlags.Required) !== 0).length,
+    };
+  }
+  if (must(queries.isArray(type))) {
+    return { types: must(queries.typeArguments(type)), fixed: false, least: 0 };
+  }
+  // Another iterable's elements are read off its type arguments, as `Set<T>` holds `T`.
+  return { types: [type, ...must(queries.typeArguments(type))], fixed: false, least: 0 };
+}
+
+/** The element types of a tuple of `count` required elements; none for another type. */
+export function knownElements<Brand>(
+  project: ProjectView<Brand>,
+  type: Type,
+  count: number,
+): readonly (Type | undefined)[] | undefined {
+  if (!type.isTupleType()) {
+    return undefined;
+  }
+  const elements = spread(project, type);
+  return elements.fixed && elements.types.length === count ? elements.types : undefined;
+}
+
+/**
+ * The places each argument fills, `types` holding the type of each argument's value; it
+ * may be empty where no argument is a spread and no given type is read. `listed` reads
+ * the last argument as a list whose elements the places bind.
+ */
+export function spansOf<Brand>(
+  project: ProjectView<Brand>,
+  args: readonly Expression[],
+  listed: boolean,
+  types: readonly (Type | undefined)[],
+): readonly Span[] {
+  const spans: Span[] = [];
+  let place = 0;
+  let open = false;
+  for (const [at, argument] of args.entries()) {
+    const type = types[at];
+    if (!isSpreadElement(argument) && !(listed && at === args.length - 1)) {
+      spans.push({ argument: at, first: place, given: [type], open, spread: false });
+      place += 1;
+      continue;
+    }
+    const elements = spread(project, type);
+    open ||= !elements.fixed;
+    spans.push({ argument: at, first: place, given: elements.types, open, spread: true });
+    place += elements.least;
+  }
+  return spans;
+}
+
+/**
+ * The places of one signature as the checker counts them: one per parameter, and in
+ * place of a rest as many as the `length` the checker answers for its type, where that
+ * is a number literal or a union of them. Any other `length`, an array's or an array-like
+ * interface's `number` among them, leaves the rest open.
+ */
+export function layoutOf<Brand>(project: ProjectView<Brand>, signature: Signature): Layout {
+  const { queries } = project;
+  const fixed = signature.parameters.length;
+  const rest = must(queries.restTypeOf(signature));
+  if (rest === undefined) {
+    return { count: fixed, repeats: false };
+  }
+  const length = must(queries.propertyTypeOf(rest, "length"));
+  const lengths = length === undefined ? [] : must(queries.constituents(length));
+  const bounds = lengths.flatMap((one) => (one.isNumberLiteralType() ? [one.value] : []));
+  if (bounds.length > 0 && bounds.length === lengths.length) {
+    return { count: fixed - 1 + Math.max(...bounds), repeats: false };
+  }
+  return { count: fixed, repeats: true };
+}
+
+/**
+ * The parameter place each argument binds in a signature of `layout`, with the type it
+ * gives there. A span of unknown length binds every place from its first to the last the
+ * layout counts, and past them, where the rest is open, one `rest` placement for every
+ * later place, or else its first place alone. A place past every place of a layout that
+ * does not repeat is `uncovered`.
+ */
+export function placesIn(spans: readonly Span[], layout: Layout): readonly Placed[] {
+  const placed: Placed[] = [];
+  const add = (span: Span, place: number, rest: boolean): void => {
+    const uncovered = place >= layout.count && !layout.repeats;
+    const elements = span.open
+      ? span.given.map((given, element) => ({ given, element }))
+      : [{ given: span.given[place - span.first], element: place - span.first }];
+    placed.push(
+      ...elements.map((one) => ({ argument: span.argument, place, uncovered, rest, ...one })),
+    );
+  };
+  for (const span of spans) {
+    const open = span.open && layout.repeats;
+    const end = !span.open
+      ? span.first + span.given.length
+      : Math.max(layout.count, open ? span.first : span.first + 1);
+    for (let place = span.first; place < end; place += 1) {
+      add(span, place, false);
+    }
+    if (open) {
+      add(span, Math.max(layout.count, span.first), true);
+    }
+  }
+  return placed;
+}
+
+/**
+ * Whether a span fills the parameter declared at `index`, a rest parameter every place
+ * from it on; with `element`, whether that element of a span that is not open does.
+ */
+export function fills(span: Span, index: number, rest: boolean, element?: number): boolean {
+  if (element !== undefined && !span.open) {
+    const place = span.first + element;
+    return rest ? place >= index : place === index;
+  }
+  const last = span.open ? Number.POSITIVE_INFINITY : span.first + span.given.length - 1;
+  return rest ? last >= index : span.first <= index && index <= last;
+}