rspress-plugin-api-extractor 0.9.2 → 0.10.0

package/README.md

@@ -47,7 +47,8 @@ The plugin reads your `.api.json` model and writes one MDX page per public API i
 ## Features
 
 - Generates API docs from `.api.json` models for classes, interfaces, functions, type aliases, enums, variables and namespaces.
-- Type-checks code examples and adds Twoslash hover tooltips that show inferred types.
+- Type-checks code examples and adds Twoslash hover tooltips that show inferred types, each documented package under its own `tsconfig`.
+- Caches Twoslash results between builds, so repeat builds over an unchanged API render code blocks near-instantly.
 - Cross-links type references between pages, so a type named in a signature links to its own page.
 - Inlines compiler-generated base declarations (the `Foo_base` pattern from Effect `Schema.Class`, `Data.TaggedError` and mixin factories) in a "Base Class" section on the owning class page instead of documenting them as orphan variables.
 - Drives single-package sites, multi-package portals, RSPress multiVersion and i18n from one plugin.

package/build-program.js

@@ -56,7 +56,8 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 				packageName,
 				apiScope
 			};
-			if (twoslashTransformer != null) vfsConfig.twoslashTransformer = twoslashTransformer;
+			const scopeTransformer = TwoslashManager.getInstance().getTransformer(apiScope) ?? twoslashTransformer;
+			if (scopeTransformer != null) vfsConfig.twoslashTransformer = scopeTransformer;
 			if (hideCutTransformer != null) vfsConfig.hideCutTransformer = hideCutTransformer;
 			if (hideCutLinesTransformer != null) vfsConfig.hideCutLinesTransformer = hideCutLinesTransformer;
 			if (apiConfig.theme != null) vfsConfig.theme = apiConfig.theme;

package/build-stages.js

@@ -803,4 +803,4 @@ function buildPipelineForApi(input) {
 }
 
 //#endregion
-export { buildPipelineForApi, cleanupAndCommit, crossLinkKindPriority, generateSinglePage, normalizeMarkdownSpacing, prepareWorkItems, setBuildStagesEventEmitter, writeMetadata, writeSingleFile };
+export { buildPipelineForApi, cleanupAndCommit, crossLinkKindPriority, generateSinglePage, prepareWorkItems, setBuildStagesEventEmitter, writeMetadata, writeSingleFile };

package/index.d.ts

@@ -390,15 +390,19 @@ declare const MultiApiConfig: Schema.Struct<{
    * Path to a `tsconfig.json` for Twoslash.
    *
    * @remarks
-   * Twoslash runs against a single shared TypeScript environment for the
-   * whole build, so per-API tsconfigs are not honored in multi-API mode:
-   * the first API that provides one wins and the rest are ignored (a
-   * `ConfigCascadeWarning` is emitted when they differ). Ensure the
-   * configured tsconfigs are equivalent, or set the intended one on the
-   * first API only.
+   * This API's code blocks are type-checked under this config. APIs that
+   * declare the same config share one TypeScript environment; the file set
+   * is shared across all documented APIs either way, so a type owned by
+   * another documented package still resolves.
    */
   readonly tsconfig: Schema.optional<Schema.declare<string | URL | ((...args: Array<unknown>) => unknown), string | URL | ((...args: Array<unknown>) => unknown)>>;
-  /** TypeScript compiler options for Twoslash. First API wins, as with `tsconfig`. */
+  /**
+   * TypeScript compiler options for Twoslash, applying to this API only.
+   *
+   * @remarks
+   * Merged on top of the defaults and of this API's `tsconfig`, so declaring
+   * a single option overrides just that one.
+   */
   readonly compilerOptions: Schema.optional<Schema.Unknown>;
 }>;
 /** @public */
@@ -650,15 +654,19 @@ declare const PluginOptions: Schema.Struct<{
      * Path to a `tsconfig.json` for Twoslash.
      *
      * @remarks
-     * Twoslash runs against a single shared TypeScript environment for the
-     * whole build, so per-API tsconfigs are not honored in multi-API mode:
-     * the first API that provides one wins and the rest are ignored (a
-     * `ConfigCascadeWarning` is emitted when they differ). Ensure the
-     * configured tsconfigs are equivalent, or set the intended one on the
-     * first API only.
+     * This API's code blocks are type-checked under this config. APIs that
+     * declare the same config share one TypeScript environment; the file set
+     * is shared across all documented APIs either way, so a type owned by
+     * another documented package still resolves.
      */
     readonly tsconfig: Schema.optional<Schema.declare<string | URL | ((...args: Array<unknown>) => unknown), string | URL | ((...args: Array<unknown>) => unknown)>>;
-    /** TypeScript compiler options for Twoslash. First API wins, as with `tsconfig`. */
+    /**
+     * TypeScript compiler options for Twoslash, applying to this API only.
+     *
+     * @remarks
+     * Merged on top of the defaults and of this API's `tsconfig`, so declaring
+     * a single option overrides just that one.
+     */
     readonly compilerOptions: Schema.optional<Schema.Unknown>;
   }>>>>>;
   /** Canonical site URL used for Open Graph absolute URLs. */

package/layers/ConfigServiceLive.js

@@ -18,10 +18,13 @@ import { DEFAULT_CATEGORIES } from "../schemas/config.js";
 import "../schemas/index.js";
 import { ConfigService } from "../services/ConfigService.js";
 import { PathDerivationService } from "../services/PathDerivationService.js";
+import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
 import { TypeRegistryService } from "../services/TypeRegistryService.js";
+import { makeTwoslashCache, twoslashEnvHash } from "../twoslash-cache.js";
 import path from "node:path";
 import { hashContent } from "@tsdoctor/snapshot";
 import { Effect, Layer, Metric } from "effect";
+import ts from "typescript";
 import os from "node:os";
 import { createHighlighter } from "shiki";
 
@@ -172,6 +175,12 @@ function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThre
 			let firstApiTsconfig;
 			let firstApiCompilerOptions;
 			/**
+			* Raw TypeScript config per API scope. Each documented package is
+			* type-checked under its OWN configuration; the build no longer picks
+			* one and applies it to everything.
+			*/
+			const scopeTsConfigs = /* @__PURE__ */ new Map();
+			/**
 			* Emit a typed ModelLoadFailed event for a failed model load, then
 			* convert the typed failure to a defect — a missing or unparsable
 			* model remains fatal to the build, exactly as before, but the
@@ -229,6 +238,7 @@ function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThre
 					const baseRoute = yield* pathService.normalizeBaseRoute(api.baseRoute ?? "/");
 					firstApiTsconfig = api.tsconfig;
 					firstApiCompilerOptions = api.compilerOptions;
+					scopeTsConfigs.set(apiScopeOf(baseRoute, api.packageName), rawTsConfig(api));
 					if (rspressMultiVersion && api.versions) {
 						const versionResults = yield* Effect.forEach(Object.entries(api.versions), ([version, versionValue]) => Effect.gen(function* () {
 							const versionDp = (yield* pathService.derivePaths({
@@ -361,23 +371,13 @@ function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThre
 					}
 				} else if (options.apis) {
 					const apisWithTsconfig = options.apis.filter((a) => a.tsconfig);
-					if (apisWithTsconfig.length > 0) {
-						firstApiTsconfig = apisWithTsconfig[0].tsconfig;
-						const uniqueTsconfigs = new Set(apisWithTsconfig.map((a) => String(a.tsconfig)));
-						if (uniqueTsconfigs.size > 1) {
-							const chosen = String(firstApiTsconfig);
-							const ignored = [...uniqueTsconfigs].filter((t) => t !== chosen);
-							yield* emit(PluginEvent.ConfigCascadeWarning({
-								ctx: { buildId: "" },
-								level: "warn",
-								field: "tsconfig",
-								chosen,
-								ignored
-							}));
-						}
-					}
+					if (apisWithTsconfig.length > 0) firstApiTsconfig = apisWithTsconfig[0].tsconfig;
 					const apisWithCompilerOptions = options.apis.filter((a) => a.compilerOptions);
 					if (apisWithCompilerOptions.length > 0) firstApiCompilerOptions = apisWithCompilerOptions[0].compilerOptions;
+					for (const a of options.apis) {
+						const scopeRoute = yield* pathService.normalizeBaseRoute(a.baseRoute ?? `/${unscopedName(a.packageName)}`);
+						scopeTsConfigs.set(apiScopeOf(scopeRoute, a.packageName), rawTsConfig(a));
+					}
 					const multiResults = yield* Effect.forEach(options.apis, (api) => Effect.gen(function* () {
 						const apiBaseRoute = yield* pathService.normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`);
 						const dp = (yield* pathService.derivePaths({
@@ -477,8 +477,33 @@ function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThre
 				chosen: "empty VFS",
 				ignored: [typeLoadResult.failure.message ?? String(typeLoadResult.failure)]
 			}));
+			const twoslashEnv = twoslashEnvHash(combinedVfs, `typescript@${ts.version}`);
+			const restored = yield* (yield* TwoslashCacheService).load(twoslashEnv);
+			const twoslashCache = makeTwoslashCache(restored);
+			yield* emit(PluginEvent.TwoslashCacheLoaded({
+				ctx: { buildId: "" },
+				level: "debug",
+				envHash: twoslashEnv,
+				entries: restored.size
+			}));
 			const twoslashStartMs = performance.now();
-			TwoslashManager.getInstance().initialize(combinedVfs, void 0, void 0, void 0, resolvedCompilerOptions);
+			const manager = TwoslashManager.getInstance();
+			manager.initialize(combinedVfs, void 0, void 0, void 0, resolvedCompilerOptions, twoslashCache);
+			const resolvedByRawConfig = /* @__PURE__ */ new Map();
+			for (const [apiScope, rawConfig] of scopeTsConfigs) {
+				if (rawConfig === void 0) {
+					manager.registerScope(apiScope, resolvedCompilerOptions);
+					continue;
+				}
+				const rawKey = JSON.stringify([String(rawConfig.tsconfig ?? ""), rawConfig.compilerOptions ?? null]);
+				let scopeOptions = resolvedByRawConfig.get(rawKey);
+				if (scopeOptions === void 0) {
+					scopeOptions = yield* Effect.promise(() => resolveTypeScriptConfig(projectRoot, rawConfig));
+					resolvedByRawConfig.set(rawKey, scopeOptions);
+				}
+				manager.initialize(combinedVfs, void 0, void 0, void 0, scopeOptions, twoslashCache);
+				manager.registerScope(apiScope, scopeOptions);
+			}
 			yield* emit(PluginEvent.TwoslashInitialized({
 				ctx: { buildId: "" },
 				level: "debug",
@@ -537,6 +562,8 @@ function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThre
 				hideCutTransformer,
 				hideCutLinesTransformer,
 				twoslashTransformer,
+				twoslashCache,
+				twoslashEnvHash: twoslashEnv,
 				pageConcurrency: os.cpus().length,
 				logLevel: logLevel === "none" ? "info" : logLevel,
 				suppressExampleErrors,
@@ -547,6 +574,22 @@ function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThre
 	}));
 }
 /**
+* Derive the API scope key from a base route, matching the derivation in
+* `build-program.ts` so config resolution and the remark plugins agree on the
+* name a code block is attributed to.
+*/
+function apiScopeOf(baseRoute, packageName) {
+	return baseRoute.replace(/^\//, "").split("/")[0] || packageName;
+}
+/** The raw TypeScript config an API declares, or undefined when it declares none. */
+function rawTsConfig(api) {
+	if (api.tsconfig == null && api.compilerOptions == null) return void 0;
+	const cfg = {};
+	if (api.tsconfig != null) cfg.tsconfig = api.tsconfig;
+	if (api.compilerOptions != null) cfg.compilerOptions = api.compilerOptions;
+	return cfg;
+}
+/**
 * Strip npm scope from a package name.
 */
 function unscopedName(packageName) {

package/layers/ObservabilityLive.js

@@ -1,8 +1,10 @@
 import { makeEventBusLayer } from "../observability/EventBus.js";
-import { BuildMetrics } from "./build-metrics.js";
+import { formatCodeBlockReport, seriesFor } from "../observability/metric-report.js";
+import { BuildMetrics, makeMetricStore } from "./build-metrics.js";
 import { makeConsoleSink } from "../observability/sinks/console-sink.js";
 import { makeIssuesSink } from "../observability/sinks/issues-sink.js";
 import { makeMetricsSink } from "../observability/sinks/metrics-sink.js";
+import { makeRenderSink } from "../observability/sinks/render-sink.js";
 import { makeTraceSink } from "../observability/sinks/trace-sink.js";
 import { Effect, Layer, Logger, Metric, References } from "effect";
 
@@ -29,7 +31,8 @@ function makeSummaryLoggerLayer(logLevel) {
 	return Layer.mergeAll(Logger.layer([pluginLogger]), Layer.succeed(References.MinimumLogLevel, effectLevel));
 }
 /**
-* Compose the console + metrics + issues (+ optional trace) sinks into an EventBus layer.
+* Compose the console + metrics + issues + render (+ optional trace) sinks into
+* an EventBus layer.
 *
 * `cwd` is known at plugin-factory time (unlike the RSPress `outDir`), so the
 * trace path is resolved eagerly by `resolveObservability` and the trace sink
@@ -37,17 +40,22 @@ function makeSummaryLoggerLayer(logLevel) {
 */
 function buildEventBus(obs) {
 	const issues = makeIssuesSink();
+	const render = makeRenderSink();
+	const metrics = makeMetricStore();
 	const sinks = [
 		makeConsoleSink(obs.logLevel, { json: obs.json }),
-		makeMetricsSink(),
-		issues
+		makeMetricsSink(metrics.context),
+		issues,
+		render
 	];
 	const trace = obs.tracePath ? makeTraceSink(obs.tracePath) : null;
 	if (trace) sinks.push(trace);
 	return {
 		layer: makeEventBusLayer(sinks),
 		trace,
-		issues
+		issues,
+		render,
+		metrics
 	};
 }
 /**
@@ -55,8 +63,12 @@ function buildEventBus(obs) {
 * Accepts the configured slow-codeblock threshold so the warning message
 * interpolates the actual threshold rather than a hard-coded 100ms.
 * Replaces the 4 separate logSummary() calls in afterBuild.
+*
+* When a code-block report is supplied, the per-scope attribution lines are
+* appended after the aggregate code-block line. The report is optional so
+* existing callers and tests keep working unchanged.
 */
-const logBuildSummary = (slowCodeBlockMs) => Effect.gen(function* () {
+const logBuildSummary = (slowCodeBlockMs, renderPhase) => Effect.gen(function* () {
 	const filesTotal = yield* Metric.value(BuildMetrics.filesTotal);
 	const filesNew = yield* Metric.value(BuildMetrics.filesNew);
 	const filesModified = yield* Metric.value(BuildMetrics.filesModified);
@@ -68,6 +80,7 @@ const logBuildSummary = (slowCodeBlockMs) => Effect.gen(function* () {
 	const pagesGenerated = yield* Metric.value(BuildMetrics.pagesGenerated);
 	const externalPackages = yield* Metric.value(BuildMetrics.externalPackagesTotal);
 	const phaseDurationSnapshot = yield* Metric.value(BuildMetrics.phaseDuration);
+	const snapshots = yield* Metric.snapshot;
 	const total = filesTotal.count;
 	const newCount = filesNew.count;
 	const modified = filesModified.count;
@@ -86,14 +99,20 @@ const logBuildSummary = (slowCodeBlockMs) => Effect.gen(function* () {
 		yield* Effect.log(`📝 ${total} files (${parts.join(", ")})`);
 	}
 	if (pagesGenerated.count > 0) yield* Effect.log(`🧩 ${pagesGenerated.count} pages, ${externalPackages.count} external package(s)`);
-	if (phaseDurationSnapshot.count > 0) yield* Effect.log(`⏱ ${phaseDurationSnapshot.count} phase(s) timed`);
+	if (phaseDurationSnapshot.count > 0) {
+		const named = seriesFor(snapshots, "phase.time.ms").map((p) => `${p.attributes.phase ?? "?"} ${(p.value / 1e3).toFixed(1)}s`).slice(0, 6).join(", ");
+		yield* Effect.log(named.length > 0 ? `⏱ ${phaseDurationSnapshot.count} phase(s): ${named}` : `⏱ ${phaseDurationSnapshot.count} phase(s) timed`);
+	}
 	if (blocks > 0 && slowBlocks > 0) yield* Effect.logWarning(`Code block performance: ${slowBlocks} of ${blocks} blocks were slow (>${slowCodeBlockMs}ms)`);
+	if (renderPhase) for (const line of formatCodeBlockReport(renderPhase)) yield* Effect.log(line);
 	const totalErrors = tsErrors + prErrors;
 	if (totalErrors > 0) {
 		const errorParts = [];
 		if (tsErrors > 0) errorParts.push(`${tsErrors} Twoslash`);
 		if (prErrors > 0) errorParts.push(`${prErrors} Prettier`);
 		yield* Effect.logWarning(`${totalErrors} error(s) in code blocks (${errorParts.join(", ")})`);
+		const byCode = seriesFor(snapshots, "twoslash.diagnostics");
+		for (const series of byCode.slice(0, 5)) yield* Effect.logWarning(`  ${series.attributes.code ?? "TS?"} x${series.value} in ${series.attributes.scope ?? "(unscoped)"}`);
 	}
 });
 

package/layers/TwoslashCacheServiceLive.js

@@ -0,0 +1,53 @@
+import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
+import { decodeTwoslashCache, encodeTwoslashCache, twoslashBlobKey } from "../twoslash-cache.js";
+import { NodeFileSystem } from "@effect/platform-node";
+import { Effect, Layer, Option, Path } from "effect";
+import { Cache } from "@effected/store";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/layers/TwoslashCacheServiceLive.ts
+const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, Path.layer);
+/**
+* XDG app dirs under the same `tsdoctor` namespace the type registry uses, so
+* every derived-artifact cache this plugin keeps lives in one place.
+*/
+const AppDirsLive = AppDirs.layer({ namespace: "tsdoctor" }).pipe(Layer.provide(Layer.mergeAll(Xdg.layer, PlatformLive)));
+/**
+* A sqlite-backed `@effected/store` Cache in the XDG cache dir, separate from
+* the registry's `metadata.sqlite`.
+*
+* XDG rather than the repo: these are regenerable results derived from content
+* hashes, so they belong with the user's other caches — shared across worktrees
+* and checkouts of the same project, and untouched by cleaning `dist/`. Nothing
+* here needs to be committed for a build to be correct.
+*/
+const CacheLive = Layer.unwrap(Effect.gen(function* () {
+	const appDirs = yield* AppDirs;
+	const path = yield* Path.Path;
+	const cacheDir = yield* appDirs.ensureCache;
+	return Cache.layerSqlite({ filename: path.join(cacheDir, "twoslash.sqlite") });
+})).pipe(Layer.provide(Layer.mergeAll(AppDirsLive, PlatformLive)));
+/**
+* Live Twoslash cache persistence.
+*
+* Both operations swallow every failure by design — see the service docs. A
+* missing HOME, an unwritable cache dir or a corrupt database degrades the
+* build to "type-check everything", which is exactly the behaviour before this
+* cache existed.
+*/
+const TwoslashCacheServiceLive = Layer.succeed(TwoslashCacheService, {
+	load: (envHash) => Effect.gen(function* () {
+		const entry = yield* (yield* Cache).get(twoslashBlobKey(envHash));
+		return Option.isSome(entry) ? decodeTwoslashCache(entry.value.value) : /* @__PURE__ */ new Map();
+	}).pipe(Effect.provide(CacheLive), Effect.catchCause(() => Effect.succeed(/* @__PURE__ */ new Map()))),
+	save: (envHash, entries) => Effect.gen(function* () {
+		yield* (yield* Cache).set({
+			key: twoslashBlobKey(envHash),
+			value: encodeTwoslashCache(entries),
+			tags: ["twoslash"]
+		});
+	}).pipe(Effect.provide(CacheLive), Effect.catchCause(() => Effect.void))
+});
+
+//#endregion
+export { TwoslashCacheServiceLive };

package/layers/build-metrics.js

@@ -1,12 +1,21 @@
-import { Metric } from "effect";
+import { Context, Layer, Metric } from "effect";
 
 //#region src/layers/build-metrics.ts
+/** Create an isolated metric store for a single build. */
+function makeMetricStore() {
+	const registry = /* @__PURE__ */ new Map();
+	return {
+		registry,
+		context: Context.make(Metric.MetricRegistry, registry),
+		layer: Layer.succeed(Metric.MetricRegistry, registry)
+	};
+}
 /**
 * All build metrics as named counters/histograms.
 *
-* Note: Effect Metrics use a process-wide registry. In tests, counters
-* accumulate across test cases within the same process. Test assertions
-* should use loose matching (toContain) rather than exact count checks.
+* Metric state lives in the `Metric.MetricRegistry` of the surrounding context,
+* not in these constants, so these may be shared module-level values while each
+* build still gets its own counters — see {@link MetricRegistryLive}.
 *
 * Extracted into its own module so that `metrics-sink.ts` can import it
 * without creating a circular dependency through `ObservabilityLive.ts`
@@ -36,8 +45,20 @@ const BuildMetrics = {
 	] }),
 	codeblockTotal: Metric.counter("codeblock.total"),
 	codeblockSlow: Metric.counter("codeblock.slow"),
+	/**
+	* Summed milliseconds per dimension. Counters rather than histograms because
+	* the question these answer is "where did the time go", which needs a total;
+	* the histograms above still carry the distribution.
+	*/
+	codeblockTimeMs: Metric.counter("codeblock.time.ms"),
+	codeblockTwoslashMs: Metric.counter("codeblock.twoslash.ms"),
+	codeblockShikiMs: Metric.counter("codeblock.shiki.ms"),
+	/** Blocks the Twoslash transformer actually ran on. */
+	codeblockTwoslashTotal: Metric.counter("codeblock.twoslash.total"),
 	twoslashErrors: Metric.counter("twoslash.errors"),
 	prettierErrors: Metric.counter("prettier.errors"),
+	/** Shiki render failures. Previously unmapped, so they never reached a metric. */
+	shikiErrors: Metric.counter("shiki.errors"),
 	pagesGenerated: Metric.counter("pages.generated"),
 	apisCompleted: Metric.counter("apis.completed"),
 	apiVersionsLoaded: Metric.counter("api.versions.loaded"),
@@ -52,6 +73,12 @@ const BuildMetrics = {
 		5e3,
 		1e4
 	] }),
+	/**
+	* Summed phase milliseconds. Tagged by phase name, which the histogram alone
+	* cannot express — every phase previously collapsed into one distribution, so
+	* resolve could not be told apart from generate or write.
+	*/
+	phaseTimeMs: Metric.counter("phase.time.ms"),
 	vfsFiles: Metric.counter("vfs.files"),
 	importsPrepended: Metric.counter("imports.prepended"),
 	twoslashDiagnostics: Metric.counter("twoslash.diagnostics"),
@@ -59,4 +86,4 @@ const BuildMetrics = {
 };
 
 //#endregion
-export { BuildMetrics };
+export { BuildMetrics, makeMetricStore };

package/markdown/helpers.js

@@ -334,4 +334,4 @@ async function formatExampleCode(code, language, _context) {
 }
 
 //#endregion
-export { escapeMdxGenerics, escapeYamlString, formatExampleCode, formatImportsWithCut, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives };
+export { escapeMdxGenerics, escapeYamlString, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives };

package/observability/EventBus.js

@@ -16,8 +16,6 @@ function makeShape(sinks) {
 function makeEventBusLayer(sinks) {
 	return Layer.succeed(EventBus, makeShape(sinks));
 }
-/** No sinks: every emit is a no-op, wantsLevel always false. */
-const EventBusNoop = makeEventBusLayer([]);
 /** Emit when a bus is in context; silently no-op otherwise. */
 function emit(event) {
 	return Effect.serviceOption(EventBus).pipe(Effect.flatMap((maybe) => Option.isSome(maybe) ? maybe.value.emit(event) : Effect.void));

package/observability/heartbeat.js

@@ -70,4 +70,4 @@ function runHeartbeat(opts) {
 }
 
 //#endregion
-export { formatProgress, makeProgressEvent, readCounts, runHeartbeat };
+export { formatProgress, makeProgressEvent, runHeartbeat };

package/observability/metric-report.js

@@ -0,0 +1,124 @@
+import { Effect, Metric } from "effect";
+
+//#region src/observability/metric-report.ts
+/**
+* Break any counter down by its attributes, largest first.
+*
+* This is the generic form of what the code-block report does: because Effect
+* keys a registry entry by metric name plus attribute set, a breakdown is a
+* filter over `Metric.snapshot`, not something a sink has to accumulate. Adding
+* a dimension to an existing metric therefore costs a tag at the emit site and
+* nothing here.
+*/
+function seriesFor(snapshots, id) {
+	return snapshots.filter((snap) => snap.id === id && snap.attributes !== void 0).map((snap) => ({
+		attributes: snap.attributes ?? {},
+		value: counterValue(snap.state)
+	})).filter((series) => series.value > 0).sort((a, b) => b.value - a.value);
+}
+const ID_TO_FIELD = new Map(Object.entries({
+	blocks: "codeblock.total",
+	twoslashBlocks: "codeblock.twoslash.total",
+	slowBlocks: "codeblock.slow",
+	totalMs: "codeblock.time.ms",
+	twoslashMs: "codeblock.twoslash.ms",
+	shikiMs: "codeblock.shiki.ms"
+}).map(([field, id]) => [id, field]));
+function emptyBucket() {
+	return {
+		blocks: 0,
+		twoslashBlocks: 0,
+		slowBlocks: 0,
+		totalMs: 0,
+		twoslashMs: 0,
+		shikiMs: 0,
+		otherMs: 0
+	};
+}
+function withOther(bucket) {
+	return {
+		...bucket,
+		otherMs: Math.max(0, bucket.totalMs - bucket.twoslashMs - bucket.shikiMs)
+	};
+}
+function add(a, b) {
+	return withOther({
+		blocks: a.blocks + b.blocks,
+		twoslashBlocks: a.twoslashBlocks + b.twoslashBlocks,
+		slowBlocks: a.slowBlocks + b.slowBlocks,
+		totalMs: a.totalMs + b.totalMs,
+		twoslashMs: a.twoslashMs + b.twoslashMs,
+		shikiMs: a.shikiMs + b.shikiMs,
+		otherMs: 0
+	});
+}
+/** Counter states carry `count`; anything else contributes nothing. */
+function counterValue(state) {
+	if (typeof state !== "object" || state === null || !("count" in state)) return 0;
+	const count = state.count;
+	return typeof count === "number" ? count : Number(count);
+}
+/**
+* Build the code-block report from an explicit set of metric snapshots.
+*
+* Split from {@link codeBlockReport} so it can be exercised without a live
+* metric registry.
+*/
+function codeBlockReportFrom(snapshots) {
+	const bySeries = /* @__PURE__ */ new Map();
+	for (const snap of snapshots) {
+		const field = ID_TO_FIELD.get(snap.id);
+		if (!field || !snap.attributes) continue;
+		const { scope, component, twoslash } = snap.attributes;
+		if (scope === void 0 || component === void 0 || twoslash === void 0) continue;
+		const key = `${scope} ${component} ${twoslash}`;
+		const current = bySeries.get(key) ?? {
+			scope,
+			component,
+			twoslash: twoslash === "true",
+			...emptyBucket()
+		};
+		bySeries.set(key, {
+			...current,
+			[field]: current[field] + counterValue(snap.state)
+		});
+	}
+	const series = [...bySeries.values()].map((s) => ({
+		...s,
+		...withOther(s)
+	})).sort((a, b) => b.totalMs - a.totalMs);
+	let overall = emptyBucket();
+	const byScope = /* @__PURE__ */ new Map();
+	const byComponent = /* @__PURE__ */ new Map();
+	for (const s of series) {
+		overall = add(overall, s);
+		byScope.set(s.scope, add(byScope.get(s.scope) ?? emptyBucket(), s));
+		byComponent.set(s.component, add(byComponent.get(s.component) ?? emptyBucket(), s));
+	}
+	return {
+		overall,
+		series,
+		byScope: Object.fromEntries(byScope),
+		byComponent: Object.fromEntries(byComponent)
+	};
+}
+/** Read the code-block report from the current context's metric registry. */
+const codeBlockReport = Effect.map(Metric.snapshot, codeBlockReportFrom);
+/**
+* Render the report as the console summary lines logged at the end of a build.
+* Returns an empty array when no code block was processed.
+*/
+function formatCodeBlockReport(report) {
+	const { overall } = report;
+	if (overall.blocks === 0) return [];
+	const s = (ms) => `${(ms / 1e3).toFixed(1)}s`;
+	const pct = (ms) => overall.totalMs > 0 ? `${Math.round(ms / overall.totalMs * 100)}%` : "0%";
+	const lines = [`render phase: ${overall.blocks} code blocks in ${s(overall.totalMs)} (twoslash ${s(overall.twoslashMs)} ${pct(overall.twoslashMs)}, shiki ${s(overall.shikiMs)} ${pct(overall.shikiMs)}, other ${s(overall.otherMs)} ${pct(overall.otherMs)})`];
+	const scopes = Object.entries(report.byScope).sort((a, b) => b[1].totalMs - a[1].totalMs);
+	for (const [scope, bucket] of scopes.slice(0, 10)) lines.push(`  ${scope}: ${bucket.blocks} blocks, ${s(bucket.totalMs)} (twoslash ${s(bucket.twoslashMs)}, ${bucket.twoslashBlocks} typechecked)`);
+	if (scopes.length > 10) lines.push(`  and ${scopes.length - 10} more scopes`);
+	return lines;
+}
+
+//#endregion
+export { codeBlockReport, codeBlockReportFrom, formatCodeBlockReport, seriesFor };

package/observability/sinks/console-sink.js

@@ -27,6 +27,12 @@ function render(event) {
 		case "ConfigResolved": return `resolved ${event.baseRoute}: ${event.categoryCount} categories, ${event.externalCount} external`;
 		case "TwoslashDiagnostic": return `Twoslash TS${event.code} in ${event.file}:${event.line}:${event.col}: ${event.message}`;
 		case "TwoslashCheckFailed": return `Twoslash check failed (TS${event.code}) in ${event.file}; ${event.fsMapKeys.length} VFS files`;
+		case "TwoslashCacheLoaded": return event.entries > 0 ? `Twoslash cache: restored ${event.entries} cached result(s)` : "Twoslash cache: cold (no cached results for this type environment)";
+		case "TwoslashCacheSaved": {
+			const total = event.hits + event.misses;
+			const pct = total > 0 ? Math.round(event.hits / total * 100) : 0;
+			return `Twoslash cache: ${event.hits}/${total} hits (${pct}%), ${event.entries} entries${event.persisted ? " (saved)" : ""}`;
+		}
 		case "PageGenerated": return `page ${event.category}/${event.item} (${event.durationMs}ms)`;
 		case "FileDecision": return `${event.status}: ${event.file}`;
 		case "ItemSkipped": return `skipped ${event.kind} "${event.item}": ${event.reason}`;