typescript-perf 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to typescript-perf. The JSON output follows its own schema version (`typescript-perf/v1`, see
 [docs/schema.md](docs/schema.md)).
 
+## [0.2.1] - 2026-11-15
+
+### Fixed
+
+- `--tsc` and `--tsc7` given as `node_modules/.bin/tsc` reported the wrong version (for example "is 1.0.0"): the
+  symlink was not resolved, and the version was read from whatever package.json sat above `node_modules`. The version
+  now comes from the compiler itself (`tsc -v`), with the package.json of the real file as a fallback.
+- `ts7` credited parallel checking with part of the speed-up even when it brought nothing (on a 2-CPU machine,
+  single-threaded was faster than the default). The split is now computed from the measurements: the parallelism
+  factor (single-threaded / default) is reported only when the run ranges do not overlap. Otherwise the summary says
+  that all of the gain comes from the native compiler, with the number of CPUs, and whether parallel checking is
+  neutral or slower. A `--checkers` value clearly faster than the default is reported with its time.
+- `ts7` gave no warning when a condition's runs were widely spread (40.91% for the TypeScript 7 default on a busy
+  machine). Above a 10% spread (documented in the README), a warning names the condition, gives its spread and range,
+  and advises more runs than were made (`--runs 10`, or twice the runs already made) or closing other
+  applications. It appears in the summary, in `ts7.warnings` in the JSON, and
+  in the terminal, Markdown and HTML outputs.
+- `ts7 --markdown` printed an empty comment. It now has a table per condition (check time median, min, max, spread,
+  total time, memory), the warnings, the summary, the tsconfig options to change and the new errors.
+
 ## [0.2.0] - 2026-11-14
 
 First release meant for CI. The project was called `typecost` up to 0.1. It is now `typescript-perf`, with the commands `typescript-perf` and `tsperf`, the schema `typescript-perf/v1` and the config file `typescript-perf.config.ts`.

package/README.md

@@ -304,7 +304,7 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22, cache: npm }
       - run: npm ci
-      - uses: MartinFerret/typescript-perf@v0.2.0
+      - uses: MartinFerret/typescript-perf@v0.2.1
         with:
           fail-on: instantiations:5%
 ```
@@ -353,6 +353,10 @@ is 1% there. Check time depends on the runner, so give it a generous margin or l
 
 - **Median, range and noise.** Each number is the median of N runs after a discarded warm-up run. The range is the
   min and max over those runs. A difference counts only when it is larger than the range on both sides.
+- **Noise warning.** The spread of a condition is (max − min) / median of its check times. Above **10%**, `ts7`
+  warns, naming the condition and its spread, in every output (terminal, JSON `ts7.warnings`, Markdown, HTML): its
+  median is then less reliable. Run more times (it suggests `--runs 10`, or twice the runs already made) and close
+  other applications.
 - **Check time** comes from the compiler's own `--extendedDiagnostics`. TypeScript 5/6 print it in 10 ms steps. On
   TypeScript 7 it is wall time while several checkers run in parallel, so trace times, summed over checkers, can be
   larger than the check time.

package/dist/constants.d.ts

@@ -20,3 +20,8 @@ export declare const SPEED: {
     readonly fastMs: 2000;
     readonly slowMs: 10000;
 };
+/**
+ * Check-time spread (max − min, in percent of the median) above which a measured
+ * condition is flagged: its median is then less reliable. Documented in the README.
+ */
+export declare const NOISE_WARN_PCT = 10;

package/dist/constants.js

@@ -30,3 +30,8 @@ export const TS7_COUNTER_TOLERANCE_PCT = 1;
  * start working around it (skipping CI checks, waiting on the editor).
  */
 export const SPEED = { fastMs: 2000, slowMs: 10000 };
+/**
+ * Check-time spread (max − min, in percent of the median) above which a measured
+ * condition is flagged: its median is then less reliable. Documented in the README.
+ */
+export const NOISE_WARN_PCT = 10;

package/dist/detect.d.ts

@@ -11,6 +11,8 @@ export declare function aliasedCompilers(cwd: string): {
 }[];
 /** Every installed compiler: the project's own, and a TypeScript 7 if one is installed next to it. */
 export declare function findCompilers(cwd: string): CompilerInfo[];
+/** "Version 7.0.2" from `tsc -v`, or undefined if the binary does not answer. */
+export declare function versionFromCli(bin: string): string | undefined;
 /** Flags this compiler supports, from its own `--help --all`. */
 export declare function capabilities(c: CompilerInfo, cwd: string): Promise<CompilerCapabilities>;
 /** Resolve the tsconfig to measure: --project, or tsconfig.json in cwd. */

package/dist/detect.js

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { parseHelpFlags } from "./parse.js";
-import { run } from "./runner.js";
+import { isNodeScript, run } from "./runner.js";
 /** Find the TypeScript compiler the project itself uses, so we measure what the team actually runs. */
 export function detectCompiler(cwd, explicitBin) {
     if (explicitBin)
@@ -88,20 +89,48 @@ export function findCompilers(cwd) {
             found.push(a.compiler);
     return found;
 }
+/**
+ * A compiler given by path (--tsc, --tsc7). The version comes from the compiler
+ * itself (`tsc -v`). Only if that fails is it read from the package.json above
+ * the real file: node_modules/.bin/tsc is a symlink, and walking up from the
+ * link would find an unrelated package.json.
+ */
 function fromBin(bin) {
     if (!existsSync(bin))
         throw new Error(`Compiler not found: ${bin}`);
-    let dir = path.dirname(bin);
+    const real = realpathSync(bin);
+    const version = versionFromCli(real) ?? versionFromPackage(real) ?? "unknown";
+    return info(real, version, "explicit");
+}
+/** "Version 7.0.2" from `tsc -v`, or undefined if the binary does not answer. */
+export function versionFromCli(bin) {
+    try {
+        const [cmd, args] = isNodeScript(bin) ? [process.execPath, [bin, "-v"]] : [bin, ["-v"]];
+        const out = execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30_000, env: { ...process.env, NO_COLOR: "1" } });
+        return out.match(/Version\s+(\d+\.\d+\.\d+[^\s]*)/)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Version of the nearest package.json above the (real) compiler file that names a compiler package. */
+function versionFromPackage(realBin) {
+    let dir = path.dirname(realBin);
     while (dir !== path.dirname(dir)) {
         const p = path.join(dir, "package.json");
         if (existsSync(p)) {
-            const meta = JSON.parse(readFileSync(p, "utf8"));
-            if (meta.version)
-                return { ...info(bin, meta.version, "explicit") };
+            try {
+                const meta = JSON.parse(readFileSync(p, "utf8"));
+                if (meta.version && (meta.name === "typescript" || meta.name === "@typescript/native-preview"))
+                    return meta.version;
+            }
+            catch {
+                /* unreadable package.json: keep looking */
+            }
         }
         dir = path.dirname(dir);
     }
-    return info(bin, "unknown", "explicit");
+    return undefined;
 }
 function info(bin, version, source) {
     const major = Number(version.split(".")[0]) || 0;

package/dist/html.js

@@ -419,11 +419,14 @@ function ts7Body(r) {
     for (const c of t.checkers ?? [])
         cols.push({ label: `7, --checkers ${c.value}`, value: c.checkTimeMs.median, display: time(c.checkTimeMs.median), tone: "accent", note: !fromBlocked && c.checkTimeMs.median ? `${Math.round((a / c.checkTimeMs.median) * 10) / 10}×` : "" });
     const list = (title, items, tone) => items.length ? `<section><div class="section-head"><h2>${esc(title)}</h2><span class="count ${tone}">${items.length}</span></div><ul class="plain">${items.map((i) => `<li>${rich(i)}</li>`).join("")}</ul></section>` : "";
-    return `${hero}${cols.length ? `<section><div class="section-head"><h2>Check time</h2></div>${columns(cols)}</section>` : ""}
+    const warn = (t.warnings ?? []).length
+        ? `<section class="banner warn"><div class="banner-title">${ICON.dot} Noisy measurements</div>${(t.warnings ?? []).map((w) => `<p class="reason">${esc(w.replace(/^Warning: (.)/, (_m, c) => c.toUpperCase()))}</p>`).join("")}</section>`
+        : "";
+    return `${hero}${warn}${cols.length ? `<section><div class="section-head"><h2>Check time</h2></div>${columns(cols)}</section>` : ""}
     ${list("tsconfig options to change", t.config.removed, "bad")}
     ${list("New errors with TypeScript 7", t.diagnostics.added.map((d) => d.split("\n")[0]), "bad")}
     ${list(`Deprecated in TypeScript ${t.from.compiler.version}`, t.config.deprecated, "warn")}
-    <section><div class="section-head"><h2>Summary</h2></div><ul class="plain">${t.summary.map((s) => `<li>${rich(s)}</li>`).join("")}</ul></section>`;
+    <section><div class="section-head"><h2>Summary</h2></div><ul class="plain">${t.summary.filter((s) => !(t.warnings ?? []).includes(s)).map((s) => `<li>${rich(s)}</li>`).join("")}</ul></section>`;
 }
 /* -------------------------------------------------------------------- page */
 const CSS = `

package/dist/markdown.js

@@ -1,4 +1,5 @@
 import { mb, num, rangeNum, rangeTime, time } from "./format.js";
+import { spreadPct } from "./stats.js";
 /* Markdown for pull-request comments. The first line is a stable marker, so
    the GitHub Action can find and update its own comment. */
 /** PR-comment ready: summary table, top deltas, budget status. */
@@ -43,6 +44,29 @@ export function renderMarkdown(r) {
         if (m.total.instantiations)
             out.push(`| Instantiations | ${num(m.total.instantiations.median)} | ${rangeNum(m.total.instantiations) || "1 run"} |`);
     }
+    if (r.ts7) {
+        const t = r.ts7;
+        out.push("", `TypeScript ${t.from.compiler.version} vs ${t.to.compiler.version}, median of ${t.from.measurement.runs} run${t.from.measurement.runs === 1 ? "" : "s"} each.`, "");
+        out.push("| Condition | Check time | Min | Max | Spread | Total time | Memory |", "|---|---:|---:|---:|---:|---:|---:|");
+        const row = (label, check, total, memory, blocked = false) => out.push(blocked
+            ? `| ${label} | did not type-check | | | | | |`
+            : `| ${label} | **${time(check.median)}** | ${time(check.min)} | ${time(check.max)} | ${spreadPct(check)}% | ${total ? time(total.median) : ""} | ${memory ? mb(memory.median) : ""} |`);
+        const m = (x) => [x.total.checkTimeMs, x.total.totalTimeMs, x.total.memoryMB, x.warnings.length > 0];
+        row(`TypeScript ${t.from.compiler.version}`, ...m(t.from.measurement));
+        row(`TypeScript ${t.to.compiler.version} (default)`, ...m(t.to.measurement));
+        if (t.singleThreaded)
+            row(`TypeScript ${t.to.compiler.version} single-threaded`, ...m(t.singleThreaded));
+        for (const c of t.checkers ?? [])
+            row(`TypeScript ${t.to.compiler.version} --checkers ${c.value}`, c.checkTimeMs, c.totalTimeMs);
+        if (t.warnings?.length)
+            out.push("", "> [!WARNING]", ...t.warnings.map((w) => `> - ${w.replace(/^Warning: (.)/, (_m, c) => c.toUpperCase())}`));
+        const summary = t.summary.filter((s) => !t.warnings?.includes(s));
+        out.push("", "**Summary**", "", ...summary.map((s) => `- ${s}`));
+        if (t.config.removed.length)
+            out.push("", "**tsconfig options TypeScript 7 rejects**", "", ...t.config.removed.map((o) => `- ${o}`));
+        if (t.diagnostics.added.length)
+            out.push("", "**New errors with TypeScript 7**", "", ...t.diagnostics.added.slice(0, 20).map((d) => `- \`${d.split("\n")[0]}\``));
+    }
     if (r.findings?.length) {
         out.push("", "**Findings**", "");
         for (const f of r.findings)

package/dist/report.js

@@ -338,8 +338,10 @@ function renderTs7(r) {
         for (const d of t.diagnostics.removed.slice(0, 10))
             out.push(`  ${green("−")} ${d.split("\n")[0]}`);
     }
+    for (const w of t.warnings ?? [])
+        out.push("", ...wrapText(`${badge("WARNING", yellow)} ${w.replace(/^Warning: (.)/, (_m, c) => c.toUpperCase())}`, W() - 4, "    ").map((l, i) => (i === 0 ? `  ${l}` : l)));
     out.push("", title("Summary"));
-    for (const s of t.summary)
+    for (const s of t.summary.filter((x) => !(t.warnings ?? []).includes(x)))
         out.push(...wrapText(`${cyan("•")} ${s}`, W() - 4, "    ").map((l, i) => (i === 0 ? `  ${l}` : l)));
     return out;
 }

package/dist/ts7.d.ts

@@ -1,4 +1,4 @@
-import type { CompilerInfo, Ts7Report } from "./types.js";
+import type { CompilerInfo, Stat, Ts7Report } from "./types.js";
 export interface Ts7Options {
     /** The project's current compiler (TypeScript 5 or 6). */
     from: CompilerInfo;
@@ -16,3 +16,34 @@ export interface Ts7Options {
  * the flag), diagnostics, and the tsconfig options each compiler complains about.
  */
 export declare function ts7Report(o: Ts7Options): Promise<Ts7Report>;
+export interface ParallelismInput {
+    /** Check time of the current compiler. */
+    from: Stat;
+    /** TypeScript 7 with its default settings. */
+    to: Stat;
+    /** TypeScript 7 with --singleThreaded, when the compiler supports it. */
+    single?: Stat;
+    /** TypeScript 7 with each --checkers value tried. */
+    checkers?: {
+        value: number;
+        checkTimeMs: Stat;
+    }[];
+    cpus: number;
+    fromVersion: string;
+}
+/**
+ * How much of the TypeScript 7 speed-up comes from the native compiler and how
+ * much from parallel checking, computed from the measurements. A difference
+ * counts only when the run ranges do not overlap (the same noise rule as
+ * everywhere else), so "parallel checking helps" is never assumed.
+ */
+export declare function parallelismSummary(p: ParallelismInput): string[];
+/**
+ * One warning per measured condition whose check-time spread is above the
+ * threshold, naming the condition and its spread, with what to do about it.
+ */
+export declare function spreadWarnings(conditions: {
+    label: string;
+    checkTimeMs: Stat;
+    skip?: boolean;
+}[], thresholdPct?: number): string[];

package/dist/ts7.js

@@ -2,7 +2,8 @@ import os from "node:os";
 import { capabilities, showConfig } from "./detect.js";
 import { measure } from "./measure.js";
 import { configDiagnostics } from "./parse.js";
-import { fmtPct, round } from "./stats.js";
+import { NOISE_WARN_PCT } from "./constants.js";
+import { clearlyLower, fmtPct, round, spreadPct } from "./stats.js";
 const mem = (n) => (n >= 1024 ? `${round(n / 1024, 1)} GB` : `${Math.round(n)} MB`);
 const ms = (n) => (n >= 1000 ? `${round(n / 1000, 2)} s` : `${round(n)} ms`);
 /** Strip what legitimately differs between compilers (nothing for now) so the diff shows real changes. */
@@ -62,14 +63,17 @@ export async function ts7Report(o) {
         /* no speed or memory comparison: one side did not type-check */
     }
     else if (b > 0)
-        summary.push(`Check time: ${ms(a)} → ${ms(b)} (${round(a / b, 1)}× faster with TypeScript ${o.to.version}, median of ${runs} runs).`);
-    if (!blocked && single && single.total.checkTimeMs.median > 0) {
-        const s = single.total.checkTimeMs.median;
-        summary.push(`Single-threaded: ${ms(s)}, so ${round(a / s, 1)}× comes from the native compiler alone and the rest from parallel checking.`);
+        summary.push(`Check time: ${ms(a)} → ${ms(b)} (${round(a / b, 1)}× faster with TypeScript ${o.to.version}, median of ${runs} run${runs === 1 ? "" : "s"}).`);
+    if (!blocked && b > 0) {
+        summary.push(...parallelismSummary({
+            from: fromM.total.checkTimeMs,
+            to: toM.total.checkTimeMs,
+            single: single && !single.warnings.length ? single.total.checkTimeMs : undefined,
+            checkers,
+            cpus: os.cpus().length,
+            fromVersion: o.from.version,
+        }));
     }
-    const best = checkers?.slice().sort((x, y) => x.checkTimeMs.median - y.checkTimeMs.median)[0];
-    if (!blocked && best && best.checkTimeMs.max < toM.total.checkTimeMs.min)
-        summary.push(`--checkers ${best.value} was faster than the default on this machine (${ms(best.checkTimeMs.median)}).`);
     const fm = fromM.total.memoryMB?.median;
     const tm = toM.total.memoryMB?.median;
     if (!blocked && fm && tm)
@@ -82,6 +86,13 @@ export async function ts7Report(o) {
         summary.push("No new errors with TypeScript 7.");
     if (removed.length)
         summary.push(`${removed.length} error${removed.length > 1 ? "s" : ""} reported by TypeScript ${o.from.version} no longer appear${removed.length > 1 ? "" : "s"} with 7.`);
+    const warnings = spreadWarnings([
+        { label: `TypeScript ${o.from.version}`, checkTimeMs: fromM.total.checkTimeMs, skip: fromBlocked },
+        { label: `TypeScript ${o.to.version} (default)`, checkTimeMs: toM.total.checkTimeMs, skip: toBlocked },
+        ...(single ? [{ label: `TypeScript ${o.to.version} single-threaded`, checkTimeMs: single.total.checkTimeMs, skip: single.warnings.length > 0 }] : []),
+        ...(checkers ?? []).map((c) => ({ label: `TypeScript ${o.to.version} --checkers ${c.value}`, checkTimeMs: c.checkTimeMs })),
+    ]);
+    summary.push(...warnings);
     if (fromM.stability.counters === "identical" && toM.stability.counters === "varies")
         summary.push(`TypeScript 7's counters varied between runs (up to ${fmtPct(toM.stability.counterSpreadPct)}): use a tolerance in budgets.`);
     return {
@@ -92,5 +103,56 @@ export async function ts7Report(o) {
         diagnostics: { added, removed },
         config: { deprecated, removed: gone },
         summary,
+        warnings,
     };
 }
+/**
+ * How much of the TypeScript 7 speed-up comes from the native compiler and how
+ * much from parallel checking, computed from the measurements. A difference
+ * counts only when the run ranges do not overlap (the same noise rule as
+ * everywhere else), so "parallel checking helps" is never assumed.
+ */
+export function parallelismSummary(p) {
+    const out = [];
+    const a = p.from.median;
+    const b = p.to.median;
+    const cpus = `${p.cpus} CPU${p.cpus === 1 ? "" : "s"}`;
+    if (p.single && p.single.median > 0 && b > 0) {
+        const s = p.single.median;
+        const native = round(a / s, 1);
+        const parallel = round(s / b, 2);
+        if (clearlyLower(p.to, p.single)) {
+            out.push(`Single-threaded: ${ms(s)}. The native compiler alone is ${native}× faster, and parallel checking adds ${round(s / b, 1)}× on this machine (${cpus}).`);
+        }
+        else if (clearlyLower(p.single, p.to)) {
+            out.push(`Single-threaded: ${ms(s)}, default: ${ms(b)}. All of the gain comes from the native compiler (${native}×): on this machine (${cpus}), parallel checking by default is slower than one thread (factor ${parallel}).`);
+        }
+        else {
+            out.push(`Single-threaded: ${ms(s)}, default: ${ms(b)}. All of the gain comes from the native compiler (${native}×): on this machine (${cpus}), parallel checking by default brings nothing measurable (factor ${parallel}, within the run-to-run spread).`);
+        }
+    }
+    const best = p.checkers?.slice().sort((x, y) => x.checkTimeMs.median - y.checkTimeMs.median)[0];
+    if (best && clearlyLower(best.checkTimeMs, p.to)) {
+        out.push(`--checkers ${best.value} is faster than the default on this machine: ${ms(best.checkTimeMs.median)} instead of ${ms(b)} (${round(a / best.checkTimeMs.median, 1)}× faster than TypeScript ${p.fromVersion}).`);
+    }
+    return out;
+}
+/**
+ * One warning per measured condition whose check-time spread is above the
+ * threshold, naming the condition and its spread, with what to do about it.
+ */
+export function spreadWarnings(conditions, thresholdPct = NOISE_WARN_PCT) {
+    const out = [];
+    for (const c of conditions) {
+        if (c.skip || c.checkTimeMs.values.length < 2)
+            continue;
+        const spread = spreadPct(c.checkTimeMs);
+        if (spread <= thresholdPct)
+            continue;
+        // Suggest more runs than were made: --runs 10 means nothing to someone who already ran 10.
+        const runs = c.checkTimeMs.values.length;
+        const more = Math.max(10, runs * 2);
+        out.push(`Warning: check times of ${c.label} are spread by ${spread}% (${ms(c.checkTimeMs.min)} to ${ms(c.checkTimeMs.max)} over ${runs} runs, above the ${thresholdPct}% threshold), so its median is less reliable. Run more times (--runs ${more}) and close other applications.`);
+    }
+    return out;
+}

package/dist/types.d.ts

@@ -268,6 +268,8 @@ export interface Ts7Report {
         removed: string[];
     };
     summary: string[];
+    /** Conditions whose check-time spread is above the noise threshold (also in the summary). */
+    warnings: string[];
 }
 export interface Environment {
     node: string;

package/docs/schema.md

@@ -95,5 +95,5 @@ that were crossed).
 
 `from` and `to` (`{ compiler, measurement }`), `singleThreaded` (when the compiler supports `--singleThreaded`),
 `checkers` (`{ value, checkTimeMs, totalTimeMs? }[]`, when it supports `--checkers`), `diagnostics` (`{ added, removed }`,
-excluding tsconfig errors), `config` (`{ deprecated, removed }`, from each compiler's own TS5xxx diagnostics) and `summary`
-(factual sentences).
+excluding tsconfig errors), `config` (`{ deprecated, removed }`, from each compiler's own TS5xxx diagnostics), `summary`
+(factual sentences) and `warnings` (conditions whose check-time spread is above 10%, also repeated in `summary`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-perf",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Find out why TypeScript is slow on your project, with fixes proven on your own code. Works with TypeScript 5, 6 and 7.",
   "type": "module",
   "bin": {

package/schema/typescript-perf-v1.schema.json

@@ -1102,6 +1102,13 @@
           "items": {
             "type": "string"
           }
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Conditions whose check-time spread is above the noise threshold (10%)."
         }
       }
     },