⚡ Bolt: [성능 개선] listUseCases의 동기식 파일 읽기를 비동기 병렬 처리로 최적화

.jules/bolt.md

@@ -1,3 +1,7 @@
 ## 2026-06-09 - Optimize File System Traversal
 **Learning:** Combining `fs.readdirSync` with `fs.statSync` for every file is a major performance bottleneck for local-first CLI tools that traverse many files.
 **Action:** Always prefer `fs.readdirSync(..., { withFileTypes: true })` to avoid redundant syscalls, which significantly speeds up directory traversal.
+
+## 2026-06-09 - Concurrent I/O over Synchronous Mapping
+**Learning:** Mapping over an array of files with `fs.readFileSync` creates a massive performance bottleneck by blocking the main thread sequentially, which degrades scalability when a directory has many files.
+**Action:** Always prefer `fs.promises.readFile` concurrently with `Promise.all()` over synchronous `readFileSync` loops for optimal I/O performance, ensuring that caller functions and command wrappers are correctly updated to handle `async` execution.

src/cli.ts

@@ -307,17 +307,17 @@ function suggestDoctorActions(findings: { rule: string; message: string }[]) {
   return actions;
 }
 
-function runCommand<T>(
-  fn: () => T,
-  payload: (data: T) => {
+async function runCommand<T>(
+  fn: () => T | Promise<T>,
+  payload: (data: Awaited<T>) => {
     data: unknown;
     affectedFiles?: { path: string }[];
     warnings?: { message: string }[];
     suggestedNextActions: { command: string; reason?: string }[];
   },
 ) {
   try {
-    outputSuccess(payload(fn()));
+    outputSuccess(payload((await fn()) as Awaited<T>));
   } catch (error) {
     const info = errorInfo(error);
     outputError({ code: info.code, message: info.message, details: info.details, actions: info.actions });

src/usecase-commands.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, promises as fsPromises, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   orderActorFrontmatter,
@@ -84,11 +84,15 @@ export function createUseCase(args: {
   return { key, path: relativePath(path, root), format: "BRIEF" as const, affectedFiles };
 }
 
-export function listUseCases(args: { cwd?: string; status?: string; actor?: string; level?: string; q?: string }) {
+export async function listUseCases(args: { cwd?: string; status?: string; actor?: string; level?: string; q?: string }) {
   const config = readConfig(args.cwd ?? process.cwd());
   if (!config) throw new Error("NOT_INITIALIZED");
-  return walkFiles(join(config.root, "specs/usecases"), (path) => path.endsWith(".md"))
-    .map((path) => ({ path, parsed: parseUseCaseMarkdown(readFileSync(path, "utf8")) }))
+  const files = walkFiles(join(config.root, "specs/usecases"), (path) => path.endsWith(".md"));
+  // ⚡ Bolt: Optimize I/O by executing `fs.promises.readFile` concurrently via `Promise.all`
+  // rather than performing blocking synchronous file reads sequentially.
+  const rawContents = await Promise.all(files.map(path => fsPromises.readFile(path, "utf8")));
+
+  return files.map((path, i) => ({ path, parsed: parseUseCaseMarkdown(rawContents[i]!) }))
     .filter(({ parsed }) => !args.status || parsed.frontmatter.status === args.status.toUpperCase())
     .filter(({ parsed }) => !args.actor || parsed.frontmatter.primary_actor === slugify(args.actor!))
     .filter(({ parsed }) => !args.level || parsed.frontmatter.level === parseLevel(args.level!))

tests/authoring.test.ts

@@ -11,15 +11,15 @@ import { normalizeUseCaseMarkdown } from "../src/format/normalize.js";
 import { runDoctor } from "../src/validate/doctor.js";
 
 describe("use-case authoring loop", () => {
-  it("runs init -> usecase create -> round-trip -> doctor with no errors", () => {
+  it("runs init -> usecase create -> round-trip -> doctor with no errors", async () => {
     const root = join(tmpdir(), `vspec-authoring-${crypto.randomUUID()}`);
     mkdirSync(root, { recursive: true });
     initProject({ root, key: "VSPEC" });
     const created = createUseCase({ cwd: root, title: "Author a use case", primaryActor: "developer" });
     const file = readFileSync(join(root, created.path), "utf8");
     expect(serializeUseCase(parseUseCaseMarkdown(file))).toBe(normalizeUseCaseMarkdown(file));
     expect(runDoctor({ root, target: created.key }).findings.filter((finding) => finding.level === "error")).toEqual([]);
-    expect(listUseCases({ cwd: root })).toHaveLength(1);
+    expect(await listUseCases({ cwd: root })).toHaveLength(1);
     expect(showUseCase({ cwd: root, key: created.key }).useCase.frontmatter.title).toBe("Author a use case");
     rmSync(root, { recursive: true, force: true });
   });