@ttsc/unplugin 0.30.4 → 0.31.1

package/src/core/transform/clock/filesystemClockReferences.ts

@@ -0,0 +1,90 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * The current stamp an adapter-owned probe has minted, keyed by the operations
+ * object that observes it and, inside, by reporting device.
+ *
+ * A filesystem stamps a write once per clock tick, so two same-length writes
+ * inside one tick are indistinguishable by metadata alone. A signature may
+ * therefore stand for content only while a later write is guaranteed to move
+ * it, and that guarantee needs a reference instant the observed filesystem
+ * itself produced: once some stamp on the same device is strictly newer than an
+ * input's modification stamp, that input's tick is provably over, so any later
+ * write must mint a newer stamp and move the signature. This adapts git's
+ * racily-clean index rule: both sides of the comparison come from the same
+ * reporting device, and the newer side is a write the adapter itself made.
+ *
+ * A timestamp merely observed on another input cannot advance the reference.
+ * Tools may assign modification times, and a filesystem clock can move
+ * backwards independently of the process clock. Neither a passive historical
+ * maximum nor `Date.now()` proves what stamp a write would mint now. The probe
+ * is therefore rewritten immediately before every proof that may reuse a
+ * content signature, and its previous reference is cleared before the write. A
+ * failed refresh or a different reporting device declines the optimization and
+ * retains the content comparison (samchon/ttsc#1344). A generation's capture
+ * and deliveries rewrite the probe it retains
+ * (`refreshFilesystemClockReference`); a proof that holds no generation, a
+ * failed generation's replay, a record's proof at a build start, and the
+ * observer's proof of a plugin source, mints in one probe directory the process
+ * keeps below this user's state root (`refreshProcessClockReference`). Once
+ * that directory exists, a mint rewrites the probe in place and adds or removes
+ * no entry in a directory another observer reads.
+ *
+ * Proofs share one reference per operations object and may interleave across an
+ * await. That is sound because separability is decided when an input's metadata
+ * is taken before its read (`inputMetadataEvidence`): whatever reference is
+ * current then was minted before that read, whichever proof minted it.
+ *
+ * The probe lives in an adapter-owned temporary directory outside the project.
+ * That directory may be on another volume, such as `C:` when a project lives on
+ * `D:`. Such a split-volume generation safely keeps reading content because no
+ * same-device reference exists; it never substitutes a process-clock guess or
+ * writes a probe into the user's project.
+ */
+const FILESYSTEM_CLOCK_REFERENCES = new WeakMap<
+  TtscTransformFilesystemOperations,
+  Map<bigint, bigint>
+>();
+
+/**
+ * Return one observed filesystem's current clock references, creating the empty
+ * map on first use.
+ *
+ * Each entry maps a reporting device to the modification stamp the adapter's
+ * probe last minted there. `refreshFilesystemClockReference` replaces the map's
+ * contents before a validation, and `stampSeparable` reads it: an input whose
+ * stamp is strictly older than its device's reference can be trusted by
+ * signature. A device with no entry proves nothing, so its inputs keep being
+ * compared by content. The map is held per operations object; a distinct view
+ * object gets an independent table. The view owner must keep observations
+ * coherent when its backing state or methods change: object identity alone does
+ * not establish equivalent filesystem evidence.
+ *
+ * @evidence contracts/common.md#principled-implementation Device-keyed references are partitioned by observing operation object; refresh and metadata owners must maintain that view's coherence before its table can qualify a signature. Table identity alone proves no observation equivalence.
+ * @evidence contracts/common.md#clear-and-simple-design One WeakMap owns reference tables by operation identity; refresh and separability consumers retain their own write and comparison responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The table contains minted filesystem stamps, never a passive historical maximum or guessed process time that would hide same-tick writes.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain racy-clean metadata, fresh writes, device identity, cross-volume behavior, and proof interleaving before describing the lookup.
+ * @evidence contracts/performance.md#efficient-algorithms Operation-table and device maps provide constant-time reference selection rather than rescanning inputs to infer a clock.
+ * @evidence contracts/performance.md#reuse-equivalent-work All proofs using the same operations object share its current device reference; replacement of that object creates independent evidence.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Weak association does not retain the operations object. Current writers
+ *   clear old entries and record at most one minted device stamp per refresh;
+ *   the returned Map can also be retained by its borrower. No native handle,
+ *   clock history or running task is acquired by table selection.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The table carries the observing view's bigint device/time representation;
+ *   actual probe reads and stamp comparison remain with their native owners.
+ *   A different view receives independent storage, without assuming equal OS
+ *   names or device labels establish cross-view clock equivalence.
+ */
+export function filesystemClockReferences(
+  /** Coherent observing view partitioning native device/time authority. */
+  filesystem: TtscTransformFilesystemOperations,
+): Map<bigint, bigint> {
+  let references = FILESYSTEM_CLOCK_REFERENCES.get(filesystem);
+  if (references === undefined) {
+    references = new Map();
+    FILESYSTEM_CLOCK_REFERENCES.set(filesystem, references);
+  }
+  return references;
+}

package/src/core/transform/clock/refreshFilesystemClockReference.ts

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { filesystemClockReferences } from "./filesystemClockReferences";
+
+/**
+ * Replace every prior clock proof with one reference minted by a fresh write.
+ *
+ * The reference directory is storage the adapter already owns, deliberately
+ * outside the project root, so stamping a probe file there produces a
+ * freshly-minted "now" without touching the user's project — the analogue of
+ * git writing its index. The probe is observed through the cache-owned
+ * operations and keyed by the device those operations report, so it only ever
+ * separates stamps on the filesystem that actually minted it. When its volume
+ * differs from the inputs' volume, or the observed filesystem cannot see the
+ * probe at all, nothing is proven and content comparison continues. The write
+ * uses the native host filesystem; the supplied observing view must coherently
+ * observe that probe for its metadata to represent this mint. This function
+ * does not independently certify equivalence of a replaced view.
+ *
+ * Forcing the reference onto the inputs' volume would require writing into the
+ * user's project or an otherwise unowned neighboring directory. That is not a
+ * valid price for this optimization, so the cross-volume case degrades to more
+ * reads instead.
+ *
+ * @evidence contracts/common.md#principled-implementation Clearing old references before a fresh owned probe write prevents previous or rolled-back stamps from certifying content; only observed regular-file metadata establishes a same-device reference.
+ * @evidence contracts/common.md#clear-and-simple-design This operation mints and records one probe stamp; input metadata comparison remains in the separability consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed writes, inaccessible probes, or another device cannot be replaced by Date.now or a historical maximum; actual content proof remains necessary.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain owned storage, fresh-write evidence, and why cross-volume inputs require more reads.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral clock proof uses native owned-path writes and the observing view's bigint device/time metadata, preserving cross-volume and unavailable-probe behavior without a platform clock assumption.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Clear the view's prior entries, then an available directory performs native
+ *   path joining, one write of process-counter text and one observed metadata
+ *   read. Costs include path/counter text and native I/O; a missing directory
+ *   skips I/O. Clearing/recording follows the current reference population,
+ *   not a scan of project inputs.
+ * @evidence contracts/performance.md#reuse-equivalent-work The existing probe path and shared per-view reference table are reused; only a newly minted stamp can authorize signature reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Refresh clears history and retains at most one regular-file device stamp;
+ *   failure leaves an empty reference table. The single probe persists in its
+ *   generation/process-owned directory until that owner attempts cleanup;
+ *   this refresh acquires no separate handle or retry task.
+ */
+export function refreshFilesystemClockReference(
+  /** Owned probe storage, or unavailable storage requiring reference withdrawal. */
+  referenceDirectory: string | undefined,
+  /** Coherent observing view whose device/time reference will be replaced. */
+  filesystem: TtscTransformFilesystemOperations,
+): void {
+  const references = filesystemClockReferences(filesystem);
+  references.clear();
+  if (referenceDirectory === undefined) return;
+  try {
+    const probe = path.join(referenceDirectory, "clock-reference");
+    fs.writeFileSync(probe, `${process.hrtime.bigint()}\n`);
+    const stats = filesystem.lstat(probe);
+    if (stats.isFile()) {
+      references.set(stats.dev, stats.mtimeNs);
+    }
+  } catch {
+    // A failed refresh leaves no reference, so content comparison continues.
+    references.clear();
+  }
+}

package/src/core/transform/clock/refreshProcessClockReference.ts

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { isMainThread } from "node:worker_threads";
+
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { pathIsWithin } from "../filesystem/pathIsWithin";
+import { userStateDirectory } from "../filesystem/userStateDirectory";
+import { disposeFilesystemClockReference } from "./disposeFilesystemClockReference";
+import { refreshFilesystemClockReference } from "./refreshFilesystemClockReference";
+
+/**
+ * Replace every prior clock proof with one reference minted in the probe
+ * directory this process keeps for the proofs that hold no generation.
+ *
+ * A proof may let a separable signature stand for content only against a
+ * reference minted before its own reads (`filesystemClockReferences`): after a
+ * clock rollback a write can land in the tick of a recorded stamp, and only a
+ * reference minted since the rollback puts that stamp inside it. A generation's
+ * deliveries and capture mint in the probe directory the generation retains. A
+ * proof that holds no generation has none: a failed generation's replay, whose
+ * directory was released with it, a record's proof at a build start, and the
+ * observer's proof of a plugin source.
+ *
+ * Those proofs run at any moment, beside compiles that observe the directories
+ * around them, so minting may change nothing but the probe itself. Creating and
+ * removing a directory per proof would add and remove an entry in the shared
+ * temporary directory, whose metadata other observers read: the absence of a
+ * `package.json` there, for one, is proven by that directory's own metadata
+ * holding still while a plugin descriptor is evaluated. The probe therefore
+ * lives at a process-named directory below this user's current state root
+ * (`userStateDirectory`), whose provider rechecks the native layout on each
+ * call; the probe is rewritten in place. A later session attempts to reclaim
+ * dead-process entries when it scans that state root. The main thread registers
+ * best-effort exit removal for its first successfully obtained directory.
+ * Worker threads share the process id and so the directory: a probe another
+ * thread rewrites between this one's write and its read is still a stamp minted
+ * before this proof reads.
+ *
+ * Minting is an optimization's precondition, never a requirement. When the
+ * directory cannot be had, either physical address cannot be resolved, or the
+ * probe directory lies inside the physical `root`, every prior reference is
+ * cleared anyway, so no signature is separable and the proof reads content.
+ *
+ * @param root The project or source the probe must lie outside.
+ * @param filesystem The operations whose references the proof judges against.
+ * @evidence contracts/common.md#principled-implementation Detached proofs mint a fresh reference in a process-owned directory outside the observed root; unavailable or inside-root storage clears reference authority instead.
+ * @evidence contracts/common.md#clear-and-simple-design The operation selects process storage then delegates the actual mint to the same reference writer used by generations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No process timestamp substitutes for a filesystem stamp, and failure preserves real content comparison without writing into the user's source tree.
+ * @evidence contracts/common.md#meaningful-documentation Paragraphs explain rollback ordering, directory-entry interference, worker sharing, and exit ownership before stating unavailable-storage behavior.
+ * @evidence contracts/portability.md#os-neutral-implementation The native user-state provider selects process storage; physical root and probe-directory resolution through the supplied coherent native view prevents lexical aliases from concealing containment. Unknown physical identity withdraws reference authority; observed device/time metadata qualifies cross-volume applicability.
+ * @evidence contracts/performance.md#efficient-algorithms Each call pays the state provider's native path/ownership checks and two physical path resolutions before an admitted delegated probe write/lstat. Work includes path text and native observations, not a cached directory lookup; the probe is rewritten rather than opening a temporary tree per proof.
+ * @evidence contracts/performance.md#reuse-equivalent-work Generation-free proofs share the same process probe and per-operation reference table while still minting before every proof that depends on separability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The provider's process-named directory and one probe persist between detached proofs. One main-thread listener attempts removal of the first acquired directory, and later session scans attempt dead-process reclamation. Native refusal or changed state-root backing can leave entries; neither exit nor a future scan guarantees successful or timely removal.
+ */
+export function refreshProcessClockReference(
+  root: string,
+  filesystem: TtscTransformFilesystemOperations,
+): void {
+  const directory = processClockDirectory();
+  let admitted: string | undefined;
+  if (directory !== undefined) {
+    try {
+      const physicalRoot = filesystem.realpath(path.resolve(root));
+      const physicalDirectory = filesystem.realpath(directory);
+      if (!pathIsWithin(physicalDirectory, physicalRoot)) admitted = directory;
+    } catch {
+      // Unknown native identity cannot establish outside-root storage.
+    }
+  }
+  refreshFilesystemClockReference(admitted, filesystem);
+}
+
+/**
+ * This process's probe directory, created when absent, or `undefined` when the
+ * state root cannot hold it; its removal is registered on the main thread's
+ * exit the first time it is found.
+ */
+function processClockDirectory(): string | undefined {
+  const directory = userStateDirectory(`${process.pid}-clock`);
+  if (directory !== undefined && isMainThread && !exitCleanupRegistered) {
+    exitCleanupRegistered = true;
+    process.once("exit", () => disposeFilesystemClockReference(directory));
+  }
+  return directory;
+}
+
+/** Whether the main thread already removes the directory on exit. */
+let exitCleanupRegistered = false;

package/src/core/transform/clock/stampSeparable.ts

@@ -0,0 +1,32 @@
+import type fs from "node:fs";
+
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { filesystemClockReferences } from "./filesystemClockReferences";
+
+/**
+ * Test the observed modification stamp against its device's current reference.
+ *
+ * A strictly newer minted reference is the separation criterion used by
+ * metadata-qualified content comparison. The caller owns fresh minting before
+ * the relevant read and coherence of the supplied metadata/view. This predicate
+ * only compares those values; it does not independently prove the mint/read
+ * ordering or guarantee unchanged state after the comparison.
+ *
+ * @evidence contracts/common.md#principled-implementation Only a strictly later reference from the same reporting device separates the recorded modification tick; equal or absent reference cannot certify metadata-only reuse.
+ * @evidence contracts/common.md#clear-and-simple-design One device lookup and bigint comparison implement the ordering criterion, leaving fresh minting and content reads with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Device metadata is not replaced by wall time, platform guesses, or a historical maximum that would miss same-tick writes.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the strict observed ordering criterion from caller-owned mint/read ordering and filesystem coherence.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral separability uses the observing filesystem's bigint device and nanosecond stamp rather than assuming one timestamp granularity or system-clock origin.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Borrows the view's reference table; lazy table allocation and retained entries have the filesystemClockReferences owner, not independent state or handles here.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One map lookup and one bigint comparison.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This scalar query selects no cached verdict or shared content computation; fresh-reference and content/signature reuse permission belong to the callers.
+ */
+export function stampSeparable(
+  /** Coherent observing view that owns the current device reference. */
+  filesystem: TtscTransformFilesystemOperations,
+  /** Observed metadata whose native device and modification stamp are compared. */
+  stats: fs.BigIntStats,
+): boolean {
+  const reference = filesystemClockReferences(filesystem).get(stats.dev);
+  return reference !== undefined && stats.mtimeNs < reference;
+}

package/src/core/transform/deliverCachedTransform.ts

@@ -0,0 +1,97 @@
+import type { TtscCachedProjectTransform } from "./cache/TtscCachedProjectTransform";
+import type { TtscTransformCache } from "./cache/TtscTransformCache";
+import { evictGeneration } from "./cache/evictGeneration";
+import { selectOrEvict } from "./cache/selectOrEvict";
+import { reportMissingProgramOutput } from "./diagnostics/reportMissingProgramOutput";
+import { reportSuccessDiagnostics } from "./diagnostics/reportSuccessDiagnostics";
+import { TtscMissingProgramOutputError } from "./errors/TtscMissingProgramOutputError";
+import { createTransformResult } from "./utils/createTransformResult";
+import { TtscGenerationProof } from "./validation/TtscGenerationProof";
+import { markCachedSourceServed } from "./validation/markCachedSourceServed";
+import type { TtscTransformHooks } from "./watch/TtscTransformHooks";
+import type { TtscWatchSelection } from "./watch/TtscWatchSelection";
+import { notifyFailedGenerationInputs } from "./watch/notifyFailedGenerationInputs";
+import { notifyVolatileDelivery } from "./watch/notifyVolatileDelivery";
+import { notifyWatchInputs } from "./watch/notifyWatchInputs";
+
+/**
+ * Deliver both captured and reused generations through one failure boundary.
+ *
+ * WARNING (#1713): host capabilities and callbacks apply to every delivery,
+ * including cache hits. Incomplete local results must never survive a failed
+ * handoff or acquire a persistent record. Stable ordinary generations retain
+ * their existing callback-failure recovery policy.
+ *
+ * A missing program output is an admitted absence: notify the same selection
+ * inputs and return control to the host. Compile failure retains its existing
+ * terminal policy through selectOrEvict and reports repair inputs.
+ *
+ * @evidence contracts/common.md#principled-implementation Captured and reused results share lifecycle admission, output selection, diagnostics and host handoff; incomplete ownership is evicted on any failed delivery effect, while missing output remains a host fallthrough.
+ * @evidence contracts/common.md#clear-and-simple-design One synchronous boundary removes duplicate initial/cache-hit delivery paths and their divergent callback and cleanup rules.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing outputs never manufacture transformed bytes or reusable observation authority; incomplete handoff failure cannot leave an owner for a sibling.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states per-delivery capability, callback failure, missing-output and compile-failure responsibilities.
+ * @evidence contracts/portability.md#os-neutral-implementation Native identities and host spellings remain delegated to the generation's existing output/watch owners.
+ * @evidence contracts/performance.md#efficient-algorithms Selection uses generation indexes; diagnostics, output/map work and current host callbacks remain necessary per delivery. Watch input and record derivation retain their owning population costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work Initial and reused answers share the exact same operation, while generation-owned indexes and the pass-qualified compiled result retain their separate validity premises.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Fresh-only admission releases capture resources; failed incomplete delivery evicts only its exact Promise. Ordinary selection/terminal and host lifecycle owners retain their established resource policy.
+ */
+export function deliverCachedTransform(props: {
+  cache: TtscTransformCache | undefined;
+  cached: TtscCachedProjectTransform;
+  generation: Promise<TtscCachedProjectTransform>;
+  key: string;
+  epoch: number | undefined;
+  file: string;
+  source: string;
+  hooks: TtscTransformHooks | undefined;
+  selection: TtscWatchSelection;
+}) {
+  const {
+    cache,
+    cached,
+    generation,
+    key,
+    epoch,
+    file,
+    source,
+    hooks,
+    selection,
+  } = props;
+  try {
+    TtscGenerationProof.admitFreshOnly(
+      cached,
+      cache,
+      key,
+      generation,
+      epoch,
+      hooks,
+    );
+    reportSuccessDiagnostics(cached, epoch);
+    let output;
+    try {
+      output = selectOrEvict(cache, key, generation, epoch, {
+        file,
+        projectRoot: cached.projectRoot,
+        result: cached.result,
+        tsconfig: cached.tsconfig,
+      });
+    } catch (error) {
+      if (!(error instanceof TtscMissingProgramOutputError)) {
+        notifyFailedGenerationInputs(hooks, cached, file, selection);
+        throw error;
+      }
+      reportMissingProgramOutput(cached, error, epoch);
+      notifyWatchInputs(hooks, cached, file, selection);
+      markCachedSourceServed(cached, file);
+      return undefined;
+    }
+    notifyWatchInputs(hooks, cached, file, selection);
+    markCachedSourceServed(cached, file);
+    notifyVolatileDelivery(hooks, cached, file);
+    return createTransformResult(file, source, output);
+  } catch (error) {
+    if (cached.freshDeliveryOnly === true)
+      evictGeneration(cache, key, generation);
+    throw error;
+  }
+}

package/src/core/transform/diagnostics/formatDiagnostics.ts

@@ -0,0 +1,47 @@
+import type { ITtscCompilerDiagnostic } from "ttsc";
+
+import { stripTerminalEscapes } from "./stripTerminalEscapes";
+
+/**
+ * Format a compiler diagnostic list into a human-readable string.
+ *
+ * Produces `"file: line:col: message"` entries joined by newlines, matching the
+ * output style of `tsc`. When the list is empty (e.g. a failure with no
+ * attached diagnostics) returns a generic fallback message so the thrown
+ * `Error` is never empty.
+ *
+ * @evidence contracts/common.md#principled-implementation Structured compiler locations and messages are rendered without inferring error categories from their text; the empty-list fallback belongs to failure formatting.
+ * @evidence contracts/common.md#clear-and-simple-design One projection joins present location components and delegates terminal escape removal to its single owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Formatting preserves diagnostic order and supplied positions rather than substituting expected fixture messages or synthetic success.
+ * @evidence contracts/common.md#meaningful-documentation The native comment states the rendered shape and explains why an empty failure still needs a message.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Performs no filesystem, path or process operation of its own.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One projection visits each diagnostic and scans each message once for
+ *   CSI escapes. Total work and output space scale with the diagnostic count
+ *   and rendered text lengths; supplied order and coordinates are retained.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function formatDiagnostics(
+  diagnostics: ITtscCompilerDiagnostic[],
+): string {
+  if (diagnostics.length === 0) {
+    return "ttsc transform failed";
+  }
+  return diagnostics
+    .map((diag) =>
+      [
+        diag.file ?? "ttsc",
+        diag.line === undefined
+          ? undefined
+          : `${diag.line}:${diag.character ?? 1}`,
+        stripTerminalEscapes(diag.messageText),
+      ]
+        .filter((part) => part !== undefined && part !== "")
+        .join(": "),
+    )
+    .join("\n");
+}

package/src/core/transform/diagnostics/formatUnknownError.ts

@@ -0,0 +1,40 @@
+import { stripTerminalEscapes } from "./stripTerminalEscapes";
+
+/**
+ * Render any thrown value as plain text for a bundler's error channel.
+ *
+ * Errors and error-shaped objects contribute their message, and anything else
+ * is stringified. ANSI CSI escape sequences are stripped, because the text ends
+ * up in a Vite overlay, a webpack report, or a CI annotation, where colour
+ * codes render as noise around the file and line the reader needs. Other
+ * terminal protocols remain outside the escape-removal helper's grammar.
+ *
+ * @evidence contracts/common.md#principled-implementation Error instances and message-bearing objects contribute their message; remaining thrown values use JavaScript string conversion before removing terminal control sequences.
+ * @evidence contracts/common.md#clear-and-simple-design Three direct representation cases share one escape-removal helper instead of introducing a separate exception taxonomy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The formatter does not guess recovery or success from message text and does not mutate the thrown object.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs describe opaque thrown values and explain why terminal rendering cannot be carried into bundler reports.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Performs no filesystem, path or process operation of its own.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Fixed representation branches select one message and delegate one CSI
+ *   scan, linear in message length. Message accessors and String conversion
+ *   can invoke caller code, whose cost and failures are not bounded here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function formatUnknownError(error: unknown): string {
+  if (error instanceof Error) {
+    return stripTerminalEscapes(error.message);
+  }
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof error.message === "string"
+  ) {
+    return stripTerminalEscapes(error.message);
+  }
+  return stripTerminalEscapes(String(error));
+}

package/src/core/transform/diagnostics/reportDivergentDelivery.ts

@@ -0,0 +1,59 @@
+import path from "node:path";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+
+/**
+ * Attempt one warning per native resolved spelling and generation when a module
+ * arrives with text that differs from the file it names.
+ *
+ * The spelling is recorded before stderr is written, so a synchronous write
+ * failure propagates but does not authorize another attempt for that key.
+ * Physical aliases remain separate warning keys; this reporting set does not
+ * decide compiler input identity or generation freshness.
+ *
+ * Ttsc compiles the whole project from disk, so the delivered text never
+ * reaches the output: the module is served from the compile of the file on
+ * disk. That is right when the host read the file just before it changed, and
+ * the host's next delivery resolves it. It is wrong when a plugin ordered
+ * before ttsc rewrote the module, because that rewrite is then dropped, so the
+ * report names the likely cause instead of letting the rewrite vanish
+ * silently.
+ *
+ * @evidence contracts/common.md#principled-implementation A generation-owned set suppresses repeated warning attempts for the same native resolved spelling while the message distinguishes delivered text from the disk program. Recording precedes writing, independently of stream success or backpressure.
+ * @evidence contracts/common.md#clear-and-simple-design One membership check and one stderr message own the warning; compilation and delivery policy remain outside reporting.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Divergence is exposed rather than hidden by returning the host's uncompiled text or rewriting expected module output.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the disk-compilation premise, rewrite causes, lexical suppression scope and pre-write recording rather than promising successful output.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node native resolve and relative choose the displayed address, including
+ *   native cross-root behavior. Splitting native separators and joining with /
+ *   is presentation only, not a guarantee of equal paths across filesystems.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Native resolution and set-key lookup cost path text. An unsuppressed report
+ *   also computes a relative address, allocates split/join and message strings,
+ *   then writes their bytes to stderr; repeated keys return before those steps.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The per-generation set suppresses repeated message construction and write
+ *   attempts for the same resolved spelling, not every physical alias.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The generation-owned set grows with distinct divergent spelling keys and
+ *   their text, then becomes collectible with the generation. Native stderr
+ *   owns stream buffering/backpressure; this reporter retains no separate task.
+ */
+export function reportDivergentDelivery(
+  /** Generation owning warning suppression and the diagnostic root. */
+  cached: TtscCachedProjectTransform,
+  /** Native source spelling normalized only for suppression and display. */
+  file: string,
+): void {
+  const reported = (cached.divergentDeliveryReported ??= new Set<string>());
+  const key = path.resolve(file);
+  if (reported.has(key)) return;
+  reported.add(key);
+  const name = path.relative(cached.projectRoot, key).split(path.sep).join("/");
+  process.stderr.write(
+    `ttsc: ${name} reached ttsc with text that differs from the file on disk. ` +
+      "ttsc transforms the file as it is on disk, so the delivered text was " +
+      "not used. If another plugin rewrites this module, order it after ttsc " +
+      '(ttsc runs with enforce: "pre").\n',
+  );
+}

package/src/core/transform/diagnostics/reportMissingProgramOutput.ts

@@ -0,0 +1,56 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import type { TtscMissingProgramOutputError } from "../errors/TtscMissingProgramOutputError";
+
+/**
+ * Attempt one warning per supplied file spelling and generation/epoch when a
+ * module is left untransformed.
+ *
+ * The condition is ordinary and the build continues, but it must never be
+ * silent: a file the program does not contain keeps whatever plugin syntax it
+ * carries, which can defer a missing plugin transformation to runtime. The
+ * generation's nonfatal stderr channel names that condition without repeating
+ * the same spelling per delivery. The typed error owns its message text; this
+ * reporter appends a newline but does not enforce a one-line message.
+ *
+ * Epoch changes clear the old file population; undefined is the persistent
+ * host's single reporting epoch. Recording precedes writing, so synchronous
+ * stream failure propagates without removing the attempted key.
+ *
+ * @evidence contracts/common.md#principled-implementation A per-generation set and delivery epoch distinguish already-attempted spelling keys from a new pass; the typed missing-output error supplies message text without changing the host's continuation policy or certifying stream success.
+ * @evidence contracts/common.md#clear-and-simple-design Epoch reset, membership suppression and stderr delivery form a single reporting responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The reporter forwards the typed continuation reason rather than manufacturing output or classifying a diagnostic substring; duplicate suppression follows the recorded generation/epoch key.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain pass/persistent suppression, caller-owned message text and recording before stream output without promising one line or successful delivery.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   The supplied file is an opaque suppression key; this reporter parses no
+ *   native path, resolves no alias and selects no filesystem/backend policy.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Key lookup/insertion retains file-text cost; an unsuppressed attempt
+ *   constructs and writes the full message plus newline. Epoch change clears
+ *   prior entry references, while repeated keys skip message construction/IO.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The generation set suppresses repeated write attempts for the same supplied
+ *   file spelling in one epoch; it does not deduplicate physical aliases.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The set grows with distinct file spellings and text in the current epoch,
+ *   clears on epoch change and becomes collectible with the generation. Stderr
+ *   owns buffered bytes/backpressure; no separate task or history is retained.
+ */
+export function reportMissingProgramOutput(
+  /** Generation owning epoch and warning-key population. */
+  cached: TtscCachedProjectTransform,
+  /** Typed continuation context supplying an opaque file key and message. */
+  error: TtscMissingProgramOutputError,
+  /** Pass identity, or undefined for persistent generation reporting. */
+  epoch: number | undefined,
+): void {
+  const reported = (cached.missingOutputReported ??= new Set<string>());
+  if (cached.missingOutputEpoch !== epoch) {
+    cached.missingOutputEpoch = epoch;
+    reported.clear();
+  }
+  if (reported.has(error.file)) {
+    return;
+  }
+  reported.add(error.file);
+  process.stderr.write(`${error.message}\n`);
+}