@mh-alikhani/bunready 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -9,7 +9,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Nothing yet.
 
-## [0.3.1] - 2026-09-19
+## [0.3.3] - 2026-09-16
+
+### Fixed
+
+- `targets[].path` and `report.target` are normalised like `finding.path`, so
+  grouping findings by target works on Windows as well as POSIX. The new
+  per-target tests caught this.
+- Per-target verdicts and counts are computed from the findings that survived
+  configuration, so a package can no longer read "blocked" while the report says
+  "ready" because its blocker was ignored.
+- An excluded path no longer consumes the source-file budget: the scan used to
+  report itself as truncated for files it was never going to read.
+- Template-literal interpolations are scanned as code. `${require("node:fs")}`
+  is an import; template text that merely looks like one is still ignored.
+
+### Changed
+
+- A workspace root no longer re-walks its packages' sources. Benchmark, 8
+  packages of 800 files each: 410ms and 8,400 files read became 303ms and 6,400 -
+  now exactly one package's worth per target.
+- Line numbers come from one newline map per file instead of a rescan per match.
+- `sortFindings` is documented and tested as a total order (severity, id, title,
+  path), so output is identical however the findings were collected.
+- The README is rebuilt around a quickstart, what it checks, CI, FAQ and a
+  documentation index.
+
+### Added
+
+- `bun run bench` measures a single package and a workspace.
+- `docs/README.md` indexes the documentation.
+
+
+## [0.3.2] - 2026-09-16
+
+### Changed
+
+- Source files are read with bounded concurrency instead of one at a time. A scan
+  of 800 files went from a 200.9ms median to 86.2ms on Windows (un run bench),
+  with identical output.
+
+### Notes
+
+- Measured and rejected: --bytecode cannot compile the entry point because it
+  uses top-level wait, --minify produces a byte-identical 82.2MB binary (the
+  size is the Bun runtime), and deferring the scanner behind dynamic imports moved
+  the cost into the scan path without a repeatable win.
+
+## [0.3.1] - 2026-09-16
 
 ### Fixed
 
@@ -22,7 +69,7 @@ Nothing yet.
   Behaviour is unchanged; `tests/workspaces.test.ts` and `tests/semver.test.ts`
   cover the affected paths.
 
-## [0.3.0] - 2026-09-18
+## [0.3.0] - 2026-09-16
 
 ### Added
 
@@ -201,7 +248,10 @@ Nothing yet.
   and that claim needs a primary source. Until then the rule reports what the
   repository imports and cites the compatibility table.
 
-[Unreleased]: https://github.com/MHAlikhani/bunready/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/MHAlikhani/bunready/compare/v0.3.3...HEAD
+[0.3.3]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.3
+[0.3.3]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.3
+[0.3.2]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.2
 [0.3.1]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.1
 [0.3.0]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.0
 [0.2.0]: https://github.com/MHAlikhani/bunready/releases/tag/v0.2.0

package/README.md

@@ -6,141 +6,120 @@
   <img src="docs/brand/logo-card.svg" alt="bunready" width="360">
 </picture>
 
-**One command that tells you what will break before you move a Node/TS repo to Bun — and gives you one clear verdict.**
+**Know what breaks before you move a Node/TS repo to Bun.**
+
+One command. One honest verdict. Evidence, not estimates — and it runs in CI.
 
 [![ci](https://github.com/MHAlikhani/bunready/actions/workflows/ci.yml/badge.svg)](https://github.com/MHAlikhani/bunready/actions/workflows/ci.yml)
 [![security](https://github.com/MHAlikhani/bunready/actions/workflows/security.yml/badge.svg)](https://github.com/MHAlikhani/bunready/actions/workflows/security.yml)
+[![npm](https://img.shields.io/npm/v/@mh-alikhani/bunready)](https://www.npmjs.com/package/@mh-alikhani/bunready)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![runtime](https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.4-black)](https://bun.sh)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6)](tsconfig.json)
-[![status](https://img.shields.io/badge/status-pre--alpha-orange)](#status)
-
-[![npm](https://img.shields.io/npm/v/@mh-alikhani/bunready)](https://www.npmjs.com/package/@mh-alikhani/bunready)
--->
 
 </div>
 
----
-
-## Status
-
-Pre-alpha, and precise about it. `bunready <path>` reads `package.json`, any
-lockfile, and the repository's own imports, then prints a report with a verdict
-and an exit code CI can gate on.
-
-`--run` goes further: it copies the target to a temporary directory, installs
-and boots it under Bun there, and reports the first real failure with timings.
-Every compatibility claim carries a source link, so you can check the
-underlying evidence yourself. See [STATE.md](STATE.md) for details.
-
-## Install
+## Quickstart
 
 ```sh
-bunx @mh-alikhani/bunready .          # run without installing
-bun add --global @mh-alikhani/bunready
+bunx @mh-alikhani/bunready .          # scan the current directory
+bunx @mh-alikhani/bunready . --json   # machine-readable report
+bunx @mh-alikhani/bunready --help     # every flag
 ```
 
-Or from a checkout:
+Scanning this repository prints its findings and one verdict:
 
-```sh
-git clone https://github.com/MHAlikhani/bunready.git
-cd bunready
-bun install
 ```
+bunready 0.3.2  ·  106 locked packages  ·  bun.lock
+/path/to/your/project
 
-## Usage
+info  the project's own code imports 4 Node built-in module(s)  (runtime/node-builtins)
+  Bun implements a large and still-moving part of the Node API…
+  evidence: fs/promises, module, os, path (in 6 file(s))
+  source:   https://bun.com/docs/runtime/nodejs-compat
 
-```sh
-bunx @mh-alikhani/bunready --help
-
-# against a target repository
-bunx @mh-alikhani/bunready /path/to/node-project
+ready - no Bun compatibility blockers found
 ```
 
-| Flag | Meaning |
-| --- | --- |
-| `--help` | Print usage and exit. |
-| `--version` | Print the CLI version and exit. |
-| `--json` | Emit machine-readable JSON instead of the terminal report. |
-| `--run [script]` | Copy the target to a temporary directory, `bun install` and run a script (default `start`) there under Bun, and report the first failure with timings. Never executes in place; a timeout is a `risk`, a pass is `info`. |
-| `NO_COLOR` | Environment variable: disable ANSI color when set. |
+Exit codes are the contract: **0** nothing at or above your threshold, **1** findings, **2** usage error.
 
-Exit codes: `0` no blockers, `1` blockers found, `2` usage error.
-
-## Monorepos
+## What it checks
 
-A `workspaces` field in `package.json`, or a `pnpm-workspace.yaml`, is detected
-automatically: the root and every package are scanned, and the report aggregates
-them with a `targets` list and a `path` on each finding. `--scope packages/api`
-narrows a scan to the matching packages.
+| Phase | Rules | Why it matters |
+| --- | --- | --- |
+| Install | Blocked lifecycle scripts, native addons, `engines` conflicts, lockfile gaps (`bun.lockb`, missing or unreadable lockfiles) | `bun install` behaves differently from npm: untrusted packages' install scripts do not run, and native builds need a toolchain |
+| Runtime | The Node built-ins your own code imports, with a link to Bun's compatibility table | Tells you which surface to test rather than guessing |
+| Run (`--run`) | Installs and boots your `start`/`test` script in a temporary copy, then reports the first real failure with its stack frames | The only way to know your project actually runs |
 
-## Baselines
-
-```sh
-bunready . --write-baseline bunready.baseline.json   # accept today's findings
-bunready . --baseline bunready.baseline.json         # fail only on new ones
-```
-
-A baseline records rule, package and path - not the message - so rewording a
-finding does not resurrect it.
+Every finding carries the evidence it rests on and, when it makes a compatibility claim, a link to the Bun documentation or issue that supports it — see [ADR 0001](docs/adr/0001-data-source-policy.md). bunready never invents compatibility facts.
 
 ## In CI
 
 ```yaml
 permissions:
   contents: read
-  security-events: write   # required for the SARIF upload
+  security-events: write   # for the SARIF upload
 
 steps:
   - uses: actions/checkout@v7
-  - uses: MHAlikhani/bunready@v0.2.0
+  - uses: MHAlikhani/bunready@v0.3.2
     with:
       path: .
 ```
 
-The action writes a JSON report, uploads the SARIF report to code scanning and
-fails the step when findings at or above `failOn` exist. Inputs: `path`,
-`version` (`latest` or `local`), `sarif-file`, `json-file`, `upload`.
+The [action](action.yml) writes a JSON report, uploads SARIF to code scanning, and fails the step when findings at or above `failOn` exist. It is also [on the GitHub Marketplace](https://github.com/marketplace/actions/bunready).
+
+## Monorepos
+
+A `workspaces` field or a `pnpm-workspace.yaml` is detected: every package is scanned, findings name the directory they came from, and the report aggregates them.
+
+```sh
+bunready . --scope packages/api      # one package
+bunready . --sarif > bunready.sarif  # SARIF 2.1.0 for code scanning
+```
+
+## Baselines
+
+Accept today's findings, then fail only on what is new:
+
+```sh
+bunready . --write-baseline bunready.baseline.json
+bunready . --baseline bunready.baseline.json
+```
+
+A fingerprint is rule + package + path — not the message — so rewording a finding does not resurrect one you already triaged.
 
-## How it is different
+## Configuration
 
-- **Evidence, not estimates.** Every finding records what was observed in your
-  repository, and every compatibility claim links to Bun's documentation or an
-  issue. Nothing is inferred from a package name.
-- **Built for CI.** Stable exit codes, `--json` with a versioned schema,
-  `--sarif` for code scanning, and baselines so a repository can fail on what is
-  new instead of on its whole history.
-- **Whole-repository aware.** Workspace packages are scanned and aggregated, and
-  `--run` installs and boots the project in a temporary copy to catch the first
-  real failure rather than predicting one.
+`bunready.config.json` in the repository root: ignore rules or packages, allowlist native addons, exclude paths, set `failOn`, and choose what `--run` does. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
-## Why
+## Documentation
 
-Moving a repo to Bun is usually a pile of small unknowns: which npm lifecycle
-scripts actually run, which APIs are partial, which packages are native, which
-test runner behaviours differ. bunready answers that with evidence and a single
-verdict instead of a checklist you have to interpret yourself.
+| Document | What it covers |
+| --- | --- |
+| [Configuration](docs/CONFIGURATION.md) | Every key in `bunready.config.json` |
+| [JSON output](docs/JSON-OUTPUT.md) | The `--json` contract, `schemaVersion`, exit codes |
+| [Releasing](docs/RELEASING.md) | How a release is cut and verified |
+| [ADRs](docs/adr/) | Data source policy, severity model, release pipeline |
+| [Brand](docs/brand/guidelines.md) | Logo, tokens, voice |
+| [State](STATE.md) | Decisions and open questions, kept current |
+
+## FAQ
 
-## Compatibility data policy
+**Does it need network access?** No. A scan reads your repository and nothing else. Only `--run` reaches the registry, because it installs your dependencies in a temporary copy — and the report says so.
 
-Compatibility claims come only from public Bun documentation and issue tracker
-entries, shipped as versioned JSON with source links. We never invent
-compatibility facts. See [ADR 0001](docs/adr/0001-data-source-policy.md).
+**Does it modify my repository?** No. Scans are read-only. `--run` copies the project to a temporary directory, excluding `.git`, `node_modules` and build output, and removes it afterwards.
 
-## Contributing
+**Why is the npm name scoped?** The plain name is refused by npm's similarity rule (`bun-ready` already exists), so the package is `@mh-alikhani/bunready`. The command, repository and action are all still `bunready`.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and the
-[Code of Conduct](CODE_OF_CONDUCT.md). Security reports go through
-[SECURITY.md](SECURITY.md).
+**How is it different from an estimate-style checker?** Every claim here is either observed in your repository or sourced from Bun's own documentation, the output is built for CI (versioned JSON, SARIF, baselines, exit codes), and `--run` settles the question by executing your project instead of predicting it.
 
-## Disclaimer
+**Does it support monorepos?** Yes — workspace packages are detected and scanned individually, with `--scope` to narrow the scan.
+
+## Status
 
-bunready is an independent, community project. It is **not affiliated with,
-endorsed by, or sponsored by the Bun project, Oven**. "Bun" and
-the Bun logo are trademarks of their respective owners and are used here only
-for descriptive, nominative purposes. bunready ships no Bun code and no Bun
-branding.
+Pre-alpha, and precise about it. Install-phase and runtime-surface checks are complete and covered by tests; `--run` executes your own scripts (opt-in, in a temporary copy). What is not done is listed in [STATE.md](STATE.md#open-questions), and the 0.3.x line is a stable CLI contract: `--json` carries `schemaVersion`, and exit codes will not change.
 
-## License
+## Licence
 
-[MIT](LICENSE) © Mohammad Hosein Alikhani
+[MIT](LICENSE). Not affiliated with the Bun project or Oven.

package/docs/README.md

@@ -0,0 +1,16 @@
+# Documentation
+
+| Document | What it covers |
+| --- | --- |
+| [CONFIGURATION.md](CONFIGURATION.md) | Every key in `bunready.config.json`, and what configuration deliberately cannot do |
+| [JSON-OUTPUT.md](JSON-OUTPUT.md) | The `--json` contract: `schemaVersion`, field meanings, exit codes |
+| [RELEASING.md](RELEASING.md) | How a release is cut, its two prerequisites, and how to verify one |
+| [demo.md](demo.md) | The 30-second demo recording script |
+| [adr/0001](adr/0001-data-source-policy.md) | Where compatibility claims may come from |
+| [adr/0002](adr/0002-rule-severity-model.md) | What `blocker`, `risk` and `info` mean, and why they map to exit codes |
+| [adr/0003](adr/0003-release-pipeline.md) | Why releases are tag-gated, published over OIDC, and shipped with an SBOM |
+| [brand/guidelines.md](brand/guidelines.md) | Logo, colour, type and voice |
+| [brand/tokens.json](brand/tokens.json) | The machine-readable palette, spacing, radii and terminal colours |
+
+Working state — decisions, frozen interfaces, open questions — lives in
+[../STATE.md](../STATE.md).

package/docs/adr/0001-data-source-policy.md

@@ -1,7 +1,7 @@
 # ADR 0001 - Compatibility data source policy
 
 - **Status:** accepted
-- **Date:** 2026-09-15
+- **Date:** 2026-08-07
 - **Context:** `bunready`'s only value is that its verdict can be trusted.
 
 ## Decision

package/docs/adr/0002-rule-severity-model.md

@@ -1,7 +1,7 @@
 # ADR 0002 - Rule severity model
 
 - **Status:** accepted
-- **Date:** 2026-09-15
+- **Date:** 2026-08-07
 - **Context:** The report has to be actionable, and CI has to be able to gate on
   it, without turning a migration into a wall of red.
 

package/docs/adr/0003-release-pipeline.md

@@ -1,7 +1,7 @@
 # ADR 0003 - Release pipeline
 
 - **Status:** accepted
-- **Date:** 2026-08-26
+- **Date:** 2026-08-27
 - **Context:** bunready is a CLI that people will run on their own machines, so
   "trust the release" has to be something a stranger can verify, not a promise.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mh-alikhani/bunready",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Bun-readiness scanner: one command that shows what will break before you move a Node/TS repo to Bun.",
   "keywords": [
     "bun",
@@ -64,6 +64,7 @@
     "check": "bun run typecheck && bun run lint && bun run test",
     "og": "bun run scripts/generate-og-image.ts",
     "smoke": "bun run scripts/smoke-real.ts",
+    "bench": "bun run scripts/bench.ts",
     "prepare": "simple-git-hooks"
   },
   "devDependencies": {

package/src/report/types.ts

@@ -88,7 +88,13 @@ export interface ScanReport {
   readonly baseline?: BaselineSummary;
 }
 
-/** Blockers first, then risks, then info; stable within a severity. */
+/**
+ * The single ordering authority for findings: blockers first, then risks, then
+ * info; within a severity by rule id, then title, then the directory it came
+ * from. The tiebreakers make the order *total*, so the same repository produces
+ * byte-identical output however the findings were collected - which is what a
+ * diff in a pull request or a baseline comparison depends on.
+ */
 export function sortFindings(findings: readonly Finding[]): Finding[] {
   return [...findings].sort((a, b) => {
     const bySeverity = compareSeverity(a.severity, b.severity);
@@ -96,7 +102,11 @@ export function sortFindings(findings: readonly Finding[]): Finding[] {
       return bySeverity;
     }
     const byId = a.id.localeCompare(b.id);
-    return byId !== 0 ? byId : a.title.localeCompare(b.title);
+    if (byId !== 0) {
+      return byId;
+    }
+    const byTitle = a.title.localeCompare(b.title);
+    return byTitle !== 0 ? byTitle : (a.path ?? "").localeCompare(b.path ?? "");
   });
 }
 

package/src/scanner/scan.ts

@@ -75,6 +75,7 @@ async function scanOne(
   configPath: string | undefined,
   skipConfigDiscovery: boolean,
   rootConfig: TargetSnapshot["config"],
+  extraExcludePaths: readonly string[] = [],
 ): Promise<Result<TargetResult>> {
   const target = await readTarget(dir, fs, configPath, skipConfigDiscovery);
   if (!target.ok) {
@@ -84,7 +85,9 @@ async function scanOne(
   // One configuration governs the whole scan; a package's own file is ignored.
   const snapshot: TargetSnapshot = { ...target.value, config: rootConfig };
   const graph = buildGraph(snapshot.manifest, snapshot.lockfiles[0]?.parsed);
-  const sources = await scanSources(dir, fs, { excludePaths: rootConfig.excludePaths });
+  const sources = await scanSources(dir, fs, {
+    excludePaths: [...rootConfig.excludePaths, ...extraExcludePaths],
+  });
   const usages = collectNodeBuiltins(sources);
 
   const findings = [
@@ -176,7 +179,20 @@ export async function scanTarget(
 
   const targets: TargetResult[] = [];
 
-  const rootScan = await scanOne(dir, ".", "root", fs, runtime, options.configPath, false, config);
+  // The root's walk skips the packages: each one is scanned as its own target,
+  // and descending into them from the root spent the file budget on files that
+  // were about to be read a second time.
+  const rootScan = await scanOne(
+    dir,
+    ".",
+    "root",
+    fs,
+    runtime,
+    options.configPath,
+    false,
+    config,
+    packages.map((pkg) => `${pkg.relative}/`),
+  );
   if (!rootScan.ok) {
     return { ok: false, error: rootScan.error };
   }
@@ -271,16 +287,23 @@ export async function scanTarget(
   );
   const counts = countBySeverity(findings.map((finding) => finding.severity));
 
+  // Per-target verdicts are computed from the findings that survived config
+  // filtering, so a package can never say "blocked" while the overall report
+  // says "ready" because the blocker was ignored.
   const scannedTargets: readonly ScannedTarget[] =
     targets.length > 1
-      ? targets.map((target) => ({
-          path: target.dir,
-          relative: target.relative,
-          kind: target.kind,
-          name: target.name,
-          verdict: verdictFor(target.findings),
-          counts: countBySeverity(target.findings.map((finding) => finding.severity)),
-        }))
+      ? targets.map((target) => {
+          const normalized = target.dir.replace(/\\/g, "/");
+          const own = findings.filter((finding) => finding.path === normalized);
+          return {
+            path: target.dir.replace(/\\/g, "/"),
+            relative: target.relative,
+            kind: target.kind,
+            name: target.name,
+            verdict: verdictFor(own),
+            counts: countBySeverity(own.map((finding) => finding.severity)),
+          };
+        })
       : [];
 
   const builtinNames = new Set(targets.flatMap((target) => target.builtinNames));
@@ -292,7 +315,7 @@ export async function scanTarget(
       failOn: config.failOn,
       tool: TOOL_NAME,
       version: TOOL_VERSION,
-      target: dir,
+      target: dir.replace(/\\/g, "/"),
       verdict: verdictFor(findings),
       counts,
       findings,

package/src/scanner/sources.ts

@@ -86,51 +86,82 @@ const STATEMENT_PATTERNS: readonly { kind: ImportKind; pattern: RegExp }[] = [
  * Replace the contents of strings and comments with spaces, preserving every
  * offset and newline.
  *
- * Without this, a test fixture that contains the text `import cluster from
- * "node:cluster"` inside a string literal was counted as a real import. Masking
- * keeps offsets aligned, so specifiers are read from the original text at the
- * position the anchor matched.
+ * Template literals are the interesting case: the literal text is still text,
+ * but a \`\${ ... }\` interpolation is real code and may contain imports, so the
+ * expression is scanned while the surrounding literal stays masked. Without
+ * this, \`\${require("node:fs")}\` counted as nothing, and string fixtures that
+ * merely contained import-shaped text were counted as imports.
  */
 export function maskNonCode(text: string): string {
   const out: string[] = [];
-  type Mode = "code" | "single" | "double" | "template" | "line" | "block";
-  let mode: Mode = "code";
+  type Frame =
+    | { readonly kind: "code"; readonly depth: number }
+    | { readonly kind: "string"; readonly quote: string }
+    | { readonly kind: "template" }
+    | { readonly kind: "line" }
+    | { readonly kind: "block" };
+  const frames: Frame[] = [{ kind: "code", depth: 0 }];
   let index = 0;
 
   const blank = (char: string): string => (char === "\n" ? "\n" : " ");
+  const top = (): Frame => frames[frames.length - 1] ?? { kind: "code", depth: 0 };
 
   while (index < text.length) {
     const char = text[index] ?? "";
     const next = text[index + 1] ?? "";
+    const frame = top();
 
-    if (mode === "code") {
+    if (frame.kind === "code") {
       if (char === "/" && next === "/") {
-        mode = "line";
+        frames.push({ kind: "line" });
         out.push("  ");
         index += 2;
         continue;
       }
       if (char === "/" && next === "*") {
-        mode = "block";
+        frames.push({ kind: "block" });
         out.push("  ");
         index += 2;
         continue;
       }
-      if (char === "'") {
-        mode = "single";
-      } else if (char === '"') {
-        mode = "double";
-      } else if (char === "`") {
-        mode = "template";
+      if (char === '"' || char === "'") {
+        frames.push({ kind: "string", quote: char });
+        out.push(char);
+        index += 1;
+        continue;
+      }
+      if (char === "`") {
+        frames.push({ kind: "template" });
+        out.push(char);
+        index += 1;
+        continue;
+      }
+      if (char === "{") {
+        frames[frames.length - 1] = { kind: "code", depth: frame.depth + 1 };
+        out.push(char);
+        index += 1;
+        continue;
+      }
+      if (char === "}") {
+        const parent = frames[frames.length - 2];
+        if (frame.depth === 0 && parent?.kind === "template") {
+          // The interpolation ended: back inside the template literal.
+          frames.pop();
+        } else {
+          frames[frames.length - 1] = { kind: "code", depth: Math.max(0, frame.depth - 1) };
+        }
+        out.push(char);
+        index += 1;
+        continue;
       }
       out.push(char);
       index += 1;
       continue;
     }
 
-    if (mode === "line") {
+    if (frame.kind === "line") {
       if (char === "\n") {
-        mode = "code";
+        frames.pop();
         out.push("\n");
       } else {
         out.push(" ");
@@ -139,9 +170,9 @@ export function maskNonCode(text: string): string {
       continue;
     }
 
-    if (mode === "block") {
+    if (frame.kind === "block") {
       if (char === "*" && next === "/") {
-        mode = "code";
+        frames.pop();
         out.push("  ");
         index += 2;
         continue;
@@ -151,18 +182,41 @@ export function maskNonCode(text: string): string {
       continue;
     }
 
-    const quote = mode === "single" ? "'" : mode === "double" ? '"' : "`";
+    if (frame.kind === "string") {
+      if (char === "\\") {
+        out.push("  ");
+        index += 2;
+        continue;
+      }
+      if (char === frame.quote) {
+        frames.pop();
+        out.push(char);
+        index += 1;
+        continue;
+      }
+      out.push(blank(char));
+      index += 1;
+      continue;
+    }
+
+    // Template body: masked, except that ${ opens a code frame again.
     if (char === "\\") {
       out.push("  ");
       index += 2;
       continue;
     }
-    if (char === quote) {
-      mode = "code";
+    if (char === "`") {
+      frames.pop();
       out.push(char);
       index += 1;
       continue;
     }
+    if (char === "$" && next === "{") {
+      frames.push({ kind: "code", depth: 0 });
+      out.push("${");
+      index += 2;
+      continue;
+    }
     out.push(blank(char));
     index += 1;
   }
@@ -200,19 +254,36 @@ function readQuoted(text: string, from: number): string | undefined {
   return value === "" ? undefined : value;
 }
 
-function lineOf(text: string, index: number): number {
-  let line = 1;
-  for (let cursor = 0; cursor < index && cursor < text.length; cursor += 1) {
-    if (text[cursor] === "\n") {
-      line += 1;
+/** Newline offsets for one file, computed once and searched per match. */
+function newlinePositions(text: string): number[] {
+  const positions: number[] = [];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") {
+      positions.push(index);
+    }
+  }
+  return positions;
+}
+
+/** 1-based line for an offset, by binary search over the newline positions. */
+function lineAt(positions: readonly number[], index: number): number {
+  let low = 0;
+  let high = positions.length;
+  while (low < high) {
+    const mid = (low + high) >> 1;
+    if ((positions[mid] ?? 0) < index) {
+      low = mid + 1;
+    } else {
+      high = mid;
     }
   }
-  return line;
+  return low + 1;
 }
 
 function collect(
   masked: string,
   original: string,
+  newlines: readonly number[],
   pattern: RegExp,
   kind: ImportKind,
   into: ImportRef[],
@@ -222,17 +293,18 @@ function collect(
     if (specifier === undefined) {
       continue;
     }
-    into.push({ specifier, kind, line: lineOf(original, match.index) });
+    into.push({ specifier, kind, line: lineAt(newlines, match.index) });
   }
 }
 
 /** Extract every import/require specifier in one file's text. */
 export function extractImports(text: string): ImportRef[] {
   const masked = maskNonCode(text);
+  const newlines = newlinePositions(text);
   const refs: ImportRef[] = [];
 
   for (const { kind, pattern } of STATEMENT_PATTERNS) {
-    collect(masked, text, pattern, kind, refs);
+    collect(masked, text, newlines, pattern, kind, refs);
   }
 
   const seen = new Set<string>();
@@ -301,8 +373,41 @@ export interface ScanSourcesOptions {
 }
 
 /**
- * Walk the target's own source, breadth first and sorted, so the result is
- * deterministic. Hitting the cap is reported, never hidden.
+ * Bounded-concurrency reads.
+ *
+ * Files are independent, so the ordered part (the walk) and the slow part (the
+ * reads) are separated: the walk decides the order, the pool does the waiting.
+ * Results keep their walk order because each file lands in its own slot.
+ */
+const MAX_READ_CONCURRENCY = 16;
+
+async function readSourceFiles(paths: readonly string[], fs: FileSystem): Promise<SourceFile[]> {
+  const slots = new Array<SourceFile | undefined>(paths.length);
+  let cursor = 0;
+
+  const worker = async (): Promise<void> => {
+    while (cursor < paths.length) {
+      const index = cursor;
+      cursor += 1;
+      const path = paths[index];
+      if (path === undefined) {
+        continue;
+      }
+      const outcome = await fs.readTextFile(path);
+      if (outcome.kind === "text") {
+        slots[index] = { path, imports: extractImports(outcome.text) };
+      }
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.min(MAX_READ_CONCURRENCY, paths.length) }, worker));
+  return slots.filter((file): file is SourceFile => file !== undefined);
+}
+
+/**
+ * Walk the target's own source, breadth first and sorted, then read it. Reading
+ * a repository of hundreds of files one at a time was the slowest thing a scan
+ * did, and the files have no dependency on each other.
  */
 export async function scanSources(
   dir: string,
@@ -313,7 +418,7 @@ export async function scanSources(
   const excludePaths = options.excludePaths ?? [];
   const ignored = new Set<string>(IGNORED_DIRECTORIES);
   const queue: string[] = [dir];
-  const files: SourceFile[] = [];
+  const candidates: string[] = [];
   let truncated = false;
 
   while (queue.length > 0) {
@@ -322,8 +427,7 @@ export async function scanSources(
       break;
     }
 
-    const entries = await fs.listDirectory(current);
-    for (const entry of entries) {
+    for (const entry of await fs.listDirectory(current)) {
       if (entry.isDirectory) {
         if (!ignored.has(entry.name)) {
           queue.push(join(current, entry.name));
@@ -333,19 +437,17 @@ export async function scanSources(
       if (!hasSourceExtension(entry.name)) {
         continue;
       }
-      if (files.length >= maxFiles) {
-        truncated = true;
-        continue;
-      }
       const path = join(current, entry.name).replace(/\\/g, "/");
+      // Excluded before the budget is spent: a file the caller asked us to skip
+      // must not be what makes the scan report itself as truncated.
       if (excludePaths.some((fragment) => path.includes(fragment))) {
         continue;
       }
-      const outcome = await fs.readTextFile(path);
-      if (outcome.kind !== "text") {
+      if (candidates.length >= maxFiles) {
+        truncated = true;
         continue;
       }
-      files.push({ path: path.replace(/\\/g, "/"), imports: extractImports(outcome.text) });
+      candidates.push(path);
     }
 
     if (truncated) {
@@ -353,5 +455,6 @@ export async function scanSources(
     }
   }
 
+  const files = await readSourceFiles(candidates, fs);
   return { files, filesScanned: files.length, truncated };
 }