@ttsc/unplugin 0.30.4 → 0.31.1

package/src/core/tsconfig/matches.ts

@@ -0,0 +1,94 @@
+import type { IRootPattern } from "./IRootPattern";
+import { isPackageDirectory } from "./isPackageDirectory";
+import { matchesRootComponent } from "./matchesRootComponent";
+
+/**
+ * Match path components through the compiled glob's possible states.
+ *
+ * A directory needs a remaining filename component; completing an exact file
+ * pattern does not authorize traversal into a directory with that file's name.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   State expansion allows recursive components to consume zero directories;
+ *   transitions consume one part under literal or wildcard rules. A completed
+ *   filename state differs from a viable directory prefix.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Two state sets express the current and next positions iteratively; compile
+ *   owns grammar and this matcher owns transitions and acceptance.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Package, hidden-name and min.js rules are compiler wildcard semantics rather
+ *   than branches selected for known test filenames.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native prose explains iterative matching and the nonobvious directory/file
+ *   distinction; the min.js transition carries its compiler-semantic reason.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Consumes compiler-language components and the supplied pattern case rule, including minified-suffix comparison. Native roots, file identity and directory capability discovery remain outside this text matcher.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   At most C + 1 component positions form each active state set; P path parts
+ *   require up to P-times-C expansion/transitions and O(C) temporary states.
+ *   String/package/minified-name checks add their text costs; each component's
+ *   token matcher additionally bounds work by its pattern and candidate lengths.
+ *   Escaped whole-literal expressions retain their text cost. Iterative sets
+ *   merge equal positions instead of expanding recursive glob paths separately.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Wildcard states reuse one lazy minified-suffix result for the same path part
+ *   and fixed pattern case rule. The next part/call starts fresh; current/next
+ *   Sets merge duplicate positions without a cross-query match cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The state sets are local to the call.
+ */
+export function matches(
+  parts: string[],
+  pattern: IRootPattern,
+  directory: boolean,
+): boolean {
+  const { components } = pattern;
+  let states = new Set([0]);
+  const expand = (): void => {
+    for (const state of states) {
+      if (!pattern.literal && components[state] === "**") states.add(state + 1);
+    }
+  };
+  for (const part of parts) {
+    expand();
+    const next = new Set<number>();
+    let minJs: boolean | undefined;
+    for (const state of states) {
+      const component = components[state];
+      if (component === undefined) continue;
+      if (!pattern.literal && component === "**") {
+        if (!part.startsWith(".") && !isPackageDirectory(part)) next.add(state);
+      } else if (typeof component !== "string") {
+        if (
+          (!component.wildcard ||
+            (!isPackageDirectory(part) &&
+              // TypeScript-Go's file matcher leaves a `.min.js` name out of
+              // every wildcard that does not spell `.min.` itself.
+              (directory ||
+                component.mentionsMin ||
+                !(minJs ??= hasMinJsSuffix(part, pattern.caseSensitive))))) &&
+          matchesRootComponent(part, component.expression)
+        )
+          next.add(state + 1);
+      } else if (component === part) {
+        next.add(state + 1);
+      }
+    }
+    if (next.size === 0) return false;
+    states = next;
+  }
+  expand();
+  // A directory needs a remaining filename component, not just a completed
+  // exact-file match; otherwise `include: ["*.ts"]` would descend into a
+  // directory named `artifact.ts` and watch its unrelated children.
+  return directory
+    ? [...states].some((state) => state < components.length)
+    : states.has(components.length);
+}
+
+/** `hasMinJsSuffix`, with the same case rule the compiled components use. */
+function hasMinJsSuffix(part: string, caseSensitive: boolean): boolean {
+  return (caseSensitive ? part : part.toLowerCase()).endsWith(".min.js");
+}

package/src/core/tsconfig/matchesProjectRootFile.ts

@@ -0,0 +1,114 @@
+import type { IRootPattern } from "./IRootPattern";
+import type { ITtscProjectMembershipPolicy } from "./ITtscProjectMembershipPolicy";
+import { compile } from "./compile";
+import { matches } from "./matches";
+import { policyUsesCaseSensitiveFileNames } from "./policyUsesCaseSensitiveFileNames";
+import { rootSpellings } from "./rootSpellings";
+
+const compiled = new WeakMap<
+  ITtscProjectMembershipPolicy,
+  Map<NodeJS.Platform, IRootPattern[]>
+>();
+
+/**
+ * Match configured root files or a directory that can contain one.
+ *
+ * This is discovery, not dependency membership: imports outside these specs
+ * remain compiler inputs and are proven by the external-input snapshot.
+ * TypeScript's include grammar has only *, ?, ** and implicit directory globs;
+ * wildcards never enter package folders or hidden paths, a `.min.js` file needs
+ * a wildcard that spells `.min.`, and a JSON file needs a literal entry or a
+ * spec ending in `.json`. A policy whose configuration could not be read stays
+ * permissive. Matching does not test the candidate's existence, so a newly
+ * created directory receives the same answer as an existing one. An absent
+ * reported case answer can still invoke the native cache-root approximation. An
+ * explicit filesystem-view platform controls path grammar independently of the
+ * policy's compiler comparison rule.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Compiled files/include patterns match root selection, not imported
+ *   dependencies. JSON admission and directory-prefix acceptance remain
+ *   separate rules; an unreadable policy conservatively admits possible roots.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One entry point chooses relevant patterns and equivalent root spellings;
+ *   compile owns grammar and matches owns the state transition algorithm.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Matching uses configured specs and the supplied or provisionally predicted
+ *   case answer, never a list of known application directories or a candidate
+ *   existence guess. A prediction is not the executable's reported rule.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs distinguish root discovery from dependencies and explain
+ *   hidden/package/JSON rules plus the permissive unreadable-config boundary.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The provided filesystem-view platform reaches compilation and root alias
+ *   conversion together; native callers default to the host, while foreign
+ *   views never resolve their roots through the host's path grammar. Compiler
+ *   case sensitivity remains independent of that grammar. Without a supplied
+ *   flag, the native predictor's documented proxy limitations remain; selecting
+ *   a foreign grammar does not replace that predictor's filesystem view.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The WeakMap does not keep discarded policies alive. Compiled patterns are
+ *   retained while a caller retains their policy, with bytes driven by its specs
+ *   and queried platform variants. There is no eviction within a live policy;
+ *   replacing it permits reclamation when no caller keeps the old object.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Cold queries compile all configured specs and resolve the case rule,
+ *   retaining the predictor's native placement/probe cost when needed. JSON
+ *   queries filter the pattern list. Root-spelling conversion, path text and
+ *   each candidate's path/component state traversal remain per-query costs.
+ *   Wildcard component work is bounded by its token and candidate code-point
+ *   dimensions; literal expressions and path conversion retain text costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The WeakMap shares compiled patterns across queries of the same immutable
+ *   policy and filesystem-view platform. Producers replace policies when
+ *   configuration or compiler case answers change; mutating a retained policy
+ *   violates that representation. Queries reuse compiled grammar, not candidate
+ *   existence or notification authority.
+ */
+export function matchesProjectRootFile(
+  location: string,
+  policy: ITtscProjectMembershipPolicy,
+  directory: boolean,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (policy.rootFileSpecs === undefined) return true;
+  let byPlatform = compiled.get(policy);
+  if (byPlatform === undefined) {
+    byPlatform = new Map();
+    compiled.set(policy, byPlatform);
+  }
+  let patterns = byPlatform.get(platform);
+  if (patterns === undefined) {
+    const caseSensitive = policyUsesCaseSensitiveFileNames(policy);
+    patterns = [
+      ...policy.rootFileSpecs.files.map((spec) =>
+        compile(spec, true, caseSensitive, platform),
+      ),
+      ...policy.rootFileSpecs.include.map((spec) =>
+        compile(spec, false, caseSensitive, platform),
+      ),
+    ].filter((pattern): pattern is IRootPattern => pattern !== undefined);
+    byPlatform.set(platform, patterns);
+  }
+  // A JSON file enters the program only through a literal entry or an include
+  // spec that itself ends in `.json`; TypeScript-Go matches every other spec
+  // against it and then discards the match. A directory can still hold one, so
+  // it keeps every pattern.
+  const json = !directory && location.toLowerCase().endsWith(".json");
+  const candidates = json
+    ? patterns.filter((pattern) => pattern.json)
+    : patterns;
+  if (candidates.length === 0) return false;
+  return rootSpellings(
+    location,
+    policy,
+    patterns[0]!.caseSensitive,
+    platform,
+  ).some((spelling) => {
+    const parts = spelling.replace(/\\/g, "/").split("/");
+    return candidates.some((pattern) => matches(parts, pattern, directory));
+  });
+}

package/src/core/tsconfig/matchesRootComponent.ts

@@ -0,0 +1,58 @@
+import type { IRootPattern } from "./IRootPattern";
+
+/**
+ * Match one compiled filename component without searching wildcard partitions.
+ *
+ * A token position is a possible prefix of the pattern. A star can advance
+ * without consuming text or stay in place while consuming a nonseparator; other
+ * tokens consume one Unicode code point. Equal positions merge before the next
+ * character, so repeated stars never multiply equivalent searches. Literal
+ * token expressions contain one escaped code point, retaining the compiler's
+ * Unicode simple-folding rule without lowercasing filenames.
+ *
+ * The expression must come from compile: a whole literal expression has no
+ * wildcard, and each token expression matches exactly one literal code point.
+ * Leading wildcard components exclude a leading dot; literal dots remain
+ * eligible. Package, minified-file and directory rules belong to matches.
+ *
+ * @evidence contracts/common.md#principled-implementation Star epsilon/consuming transitions and one-code-point literal/question transitions recognize the compiled component language. Merging identical token positions preserves every possible match without enumerating partitions; Unicode iteration and u/iu literal predicates retain existing character and case semantics.
+ * @evidence contracts/common.md#clear-and-simple-design One component matcher owns token-state traversal; compile owns tokens and matches retains path-level policy and recursive-directory states.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No filename exception, timeout, foreign mutation or alternate compiler policy replaces matching; the generated repeated-wildcard regexp is removed at its source.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the transition meaning, compiler-owned expression precondition and hidden-name boundary separately from path policy.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Consumes compiler-language text and compiled comparison predicates, not native paths or filesystem capabilities.
+ * @evidence contracts/performance.md#efficient-algorithms For T tokens and N candidate code points, each epsilon expansion visits at most T+1 distinct positions and each character tests at most T tokens: O((N+1)(T+1)) state work and O(T+1) temporary state. Two call-local Sets exchange roles and clear old positions rather than allocating a container per character. Literal predicates contain one escaped code point with no quantifier; whole literal expressions retain their pattern/text cost. No candidate code-point array or wildcard-partition tree is materialized.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Merges equivalent positions within one component evaluation; cross-query compiled pattern reuse remains with matchesProjectRootFile.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only call-local state sets are acquired; no handle, historical result or callback is retained.
+ */
+export function matchesRootComponent(
+  part: string,
+  expression: Exclude<IRootPattern["components"][number], string>["expression"],
+): boolean {
+  if (expression instanceof RegExp) return expression.test(part);
+  if ((expression[0] === "*" || expression[0] === "?") && part.startsWith("."))
+    return false;
+  let states = new Set([0]);
+  let next = new Set<number>();
+  const expand = (): void => {
+    for (const state of states)
+      if (expression[state] === "*") states.add(state + 1);
+  };
+  for (const character of part) {
+    expand();
+    next.clear();
+    for (const state of states) {
+      const token = expression[state];
+      if (token === undefined) continue;
+      if (token === "*") {
+        if (character !== "/") next.add(state);
+      } else if (token === "?" ? character !== "/" : token.test(character))
+        next.add(state + 1);
+    }
+    if (next.size === 0) return false;
+    const previous = states;
+    states = next;
+    next = previous;
+  }
+  expand();
+  return states.has(expression.length);
+}

package/src/core/tsconfig/mergeMembershipPolicyOverlay.ts

@@ -0,0 +1,105 @@
+import type { ITtscProjectMembershipPolicy } from "./ITtscProjectMembershipPolicy";
+import { JAVASCRIPT_INPUT_EXTENSIONS } from "./JAVASCRIPT_INPUT_EXTENSIONS";
+import { OUTPUT_DIRECTORY_OPTIONS } from "./OUTPUT_DIRECTORY_OPTIONS";
+import { flattenDirectoryExclusionOrigins } from "./flattenDirectoryExclusionOrigins";
+import { resolveConfigDirTemplatePath } from "./resolveConfigDirTemplatePath";
+
+/**
+ * Apply the caller's compiler-options overlay on top of a policy read from the
+ * project config.
+ *
+ * The overlay wins for the compile, so it wins here too. A caller that turns
+ * `allowJs` on gets a program that admits JavaScript, and a membership rule
+ * that still refused it would miss files entering that program; a caller that
+ * turns it off gets the narrower rule for the same reason.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Explicit boolean overlays update extension admission and output path
+ *   overlays update their own exclusion provenance. Null removes an output
+ *   directory; missing legacy provenance preserves explicit exclusions.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The operation clones extension and exclusion state rather than mutating
+ *   the source policy; one provenance flattener owns default exclusion rules.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Output-directory overlays resolve at the supplied native config anchor
+ *   through compiler separator/template rules; existing root identity and
+ *   compiler case representation transfer without OS-name reinterpretation.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Overlay values come from the actual compile options, not emitted filename
+ *   guesses or directories selected for known test projects.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native explanation gives the reason compile and walk overlays must
+ *   agree; exclusion defaults remain documented on the owning policy members.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Copies E extension entries into a Set and N explicit exclusion references
+ *   into new provenance and flattened output arrays. Fixed flag/output-option
+ *   scans add bounded entry counts, while supplied output path resolution still
+ *   follows path text. Shared root specs, sources and case data are not recopied.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Applies one supplied overlay. Selection and generation owners decide when
+ *   a policy is reusable; this operation coordinates no cross-call computation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Transfers the merged policy and new arrays to its caller; the local Set
+ *   ends on return. It owns no historical cache or native handle.
+ */
+export function mergeMembershipPolicyOverlay(
+  policy: ITtscProjectMembershipPolicy,
+  compilerOptions: Record<string, unknown>,
+  baseDir: string,
+): ITtscProjectMembershipPolicy {
+  const inputExtensions = new Set(policy.inputExtensions);
+  const applyFlag = (key: string, extensions: readonly string[]): void => {
+    const value = compilerOptions[key];
+    if (typeof value !== "boolean") {
+      return;
+    }
+    for (const extension of extensions) {
+      if (value) {
+        inputExtensions.add(extension);
+      } else {
+        inputExtensions.delete(extension);
+      }
+    }
+  };
+  applyFlag("allowJs", JAVASCRIPT_INPUT_EXTENSIONS);
+  applyFlag("resolveJsonModule", [".json"]);
+
+  const inheritedOrigins = policy.directoryExclusionOrigins;
+  const directoryExclusionOrigins: {
+    declarationDir?: string;
+    exclude: string[];
+    outDir?: string;
+    useImplicitOutputExclusions: boolean;
+  } = {
+    declarationDir: inheritedOrigins?.declarationDir,
+    exclude: [...(inheritedOrigins?.exclude ?? policy.excludedDirectories)],
+    outDir: inheritedOrigins?.outDir,
+    useImplicitOutputExclusions:
+      inheritedOrigins?.useImplicitOutputExclusions ?? true,
+  };
+  for (const key of OUTPUT_DIRECTORY_OPTIONS) {
+    const value = compilerOptions[key];
+    if (value === null) {
+      delete directoryExclusionOrigins[key];
+    } else if (typeof value === "string") {
+      directoryExclusionOrigins[key] = resolveConfigDirTemplatePath(
+        baseDir,
+        value,
+      );
+    }
+  }
+  return {
+    rootFileSpecs: policy.rootFileSpecs,
+    directoryExclusionOrigins,
+    excludedDirectories: flattenDirectoryExclusionOrigins(
+      directoryExclusionOrigins,
+    ),
+    inputExtensions: [...inputExtensions],
+    sources: policy.sources,
+    useCaseSensitiveFileNames: policy.useCaseSensitiveFileNames,
+  };
+}

package/src/core/tsconfig/normalizeTypeScriptPathSeparators.ts

@@ -0,0 +1,28 @@
+/**
+ * Match TypeScript's platform-independent treatment of config separators.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Backslashes become config-language forward slashes before native resolution,
+ *   matching compiler parsing instead of treating them as POSIX literal names.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This helper owns config separator spelling, separate from native path identity.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Normalization is a compiler syntax rule rather than an OS-specific filename
+ *   repair or a branch for a known configuration.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native description identifies config-language semantics, which explains
+ *   why the function is distinct from an arbitrary filesystem path conversion.
+ * @evidence contracts/portability.md#os-neutral-implementation Backslashes become slashes as TypeScript's configuration language treats them before native resolution; a path handed to the filesystem is resolved natively by the callers and never rewritten here.
+ * @evidence contracts/performance.md#efficient-algorithms One literal-character replacement scans the target in linear time and returns at most the same number of characters, without resolving directories or constructing a component collection.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This syntax conversion coordinates no completed or in-flight computation;
+ *   containing readers own reuse of normalized config observations.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function normalizeTypeScriptPathSeparators(target: string): string {
+  return target.replace(/\\/g, "/");
+}

package/src/core/tsconfig/policyUsesCaseSensitiveFileNames.ts

@@ -0,0 +1,59 @@
+import { compilerUsesCaseSensitiveFileNames } from "ttsc/tsconfig";
+
+import type { ITtscProjectMembershipPolicy } from "./ITtscProjectMembershipPolicy";
+
+/**
+ * Whether a membership policy matches root specs case-sensitively.
+ *
+ * A supplied compiler answer wins, including false. Before a report is
+ * available, compilerUsesCaseSensitiveFileNames approximates the answer from
+ * the policy root's plugin-cache location, or the current directory when that
+ * root is unknown. That physical-root proxy does not observe the executable and
+ * can disagree under different directory capabilities or native spelling
+ * mappings. Capture replaces it with an available report and refuses a walk
+ * primed under a different answer before retrying.
+ *
+ * @param policy The membership policy.
+ * @evidence contracts/common.md#principled-implementation
+ *   A supplied policy wins; an absent answer delegates to the shared native
+ *   cache-root approximation. The wrapper does not certify that proxy as the
+ *   executable's actual comparison rule.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One resolver owns reported-versus-predicted precedence for root matching.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   A supplied compiler flag governs matching, independently of native path
+ *   grammar. The fallback delegates actual cache-root selection and probing to
+ *   compilerUsesCaseSensitiveFileNames, including its documented platform and
+ *   proxy limitations; no source-directory OS label establishes case policy.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The shared approximation remains explicitly provisional; a later differing
+ *   envelope is handled by the generation owner rather than hidden.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native prose distinguishes supplied and approximate answers, unknown-root
+ *   fallback and report-driven retry, with the policy argument documented.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   A supplied boolean returns immediately. The fallback retains native cache
+ *   placement costs: default discovery may visit ancestors and manifest/layout
+ *   entries before root setup and lookup, even for an already cached probe.
+ *   This wrapper adds no input scan or secondary collection.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Supplied policy data needs no probe. Fallback sharing belongs to the shared
+ *   predictor's physical-root cache; placement/setup still repeat before its
+ *   lookup and historical answers do not independently prove current capability.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function policyUsesCaseSensitiveFileNames(
+  policy: ITtscProjectMembershipPolicy,
+): boolean {
+  return (
+    policy.useCaseSensitiveFileNames ??
+    compilerUsesCaseSensitiveFileNames({
+      projectRoot: policy.rootFileSpecs?.root?.path ?? process.cwd(),
+    })
+  );
+}

package/src/core/tsconfig/readEffectiveTsconfigPaths.ts

@@ -0,0 +1,91 @@
+import path from "node:path";
+
+import { absolutizePathsTarget } from "./absolutizePathsTarget";
+import { findDeclaredPaths } from "./findDeclaredPaths";
+
+/**
+ * Read the effective `compilerOptions.paths` of a tsconfig, following its
+ * `extends` chain, and absolutize every mapping target.
+ *
+ * TypeScript merges `compilerOptions` per option key, so the effective `paths`
+ * is the whole usable record from the nearest config in the chain that declares
+ * one (own config first, then `extends` entries in reverse priority order).
+ * Relative targets are anchored at the directory of the config that declares
+ * them. TypeScript-Go resolves inherited relative `paths` against the declaring
+ * file, not the extending one. Alias names are own enumerable data properties,
+ * including names that coincide with JavaScript prototype members, so
+ * serialization preserves the declared keys.
+ *
+ * The generated transform tsconfig replaces `paths` wholesale (standard
+ * `extends` semantics), so the alias overlay must re-state these base mappings
+ * or every tsconfig-only alias silently stops resolving. Absolutizing is
+ * required because the generated config lives in a system temp directory and
+ * TypeScript-Go rejects non-relative targets (TS5090) while accepting absolute
+ * ones.
+ *
+ * Best-effort by design: a missing or unparsable config in the chain yields
+ * `{}` here and a real config error from the compiler, which owns config
+ * diagnostics.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Effective paths replace the whole inherited option; each string target
+ *   becomes absolute at the declaring directory so wrapper relocation preserves
+ *   its resolution meaning. Explicit own data properties preserve arbitrary
+ *   alias keys without invoking inherited setters. Invalid targets are omitted.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Declaration lookup, target anchoring and output assembly have separate
+ *   helpers; this reader owns the wrapper's complete inherited alias overlay.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Targets resolve with native anchors and become forward-slash config
+ *   patterns; that representation conversion does not define filesystem identity.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The overlay preserves declared aliases rather than synthesizing aliases
+ *   for a known application; config diagnostics remain with the compiler.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Paragraphs explain wholesale replacement and temporary-wrapper anchoring,
+ *   including the reason an absolute mapping is necessary instead of optional.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Declaration lookup includes native config resolution and source parsing.
+ *   Output assembly scans every mapping and target, retaining only strings;
+ *   native anchoring and separator conversion also depend on target lengths.
+ *   The temporary filtered arrays and output grow with the selected targets.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This reader assembles one paths overlay. The enclosing transform-config
+ *   capture owns equivalence across reads through its source-chain signature;
+ *   a previous overlay alone does not establish current config contents.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Its output is local and handed to the caller.
+ */
+export function readEffectiveTsconfigPaths(
+  tsconfig: string,
+): Record<string, string[]> {
+  const resolved = path.resolve(tsconfig);
+  const declared = findDeclaredPaths(resolved, new Set());
+  if (declared === null) {
+    return {};
+  }
+  const output: Record<string, string[]> = {};
+  for (const [key, targets] of Object.entries(declared.paths)) {
+    if (!Array.isArray(targets)) {
+      continue;
+    }
+    const absolute = targets
+      .filter((target): target is string => typeof target === "string")
+      .map((target) =>
+        absolutizePathsTarget(declared.baseDir, target, path.dirname(resolved)),
+      );
+    if (absolute.length !== 0) {
+      Object.defineProperty(output, key, {
+        configurable: true,
+        enumerable: true,
+        value: absolute,
+        writable: true,
+      });
+    }
+  }
+  return output;
+}