⚡ Bolt: 비동기 파일 읽기를 통한 CLI 탐색 성능 개선

.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 - Async Concurrent File Reads for CLI Lists
+**Learning:** Sequential `readFileSync` calls block the Node main thread and can slow down list operations traversing many specs.
+**Action:** Use `Promise.all` with `fs.promises.readFile` to process files concurrently. If reading thousands of files, employ a concurrency limit (e.g. chunking) to prevent EMFILE limits.

src/cli.ts

@@ -307,17 +307,18 @@ 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()));
+    const result = (await fn()) as Awaited<T>;
+    outputSuccess(payload(result));
   } catch (error) {
     const info = errorInfo(error);
     outputError({ code: info.code, message: info.message, details: info.details, actions: info.actions });

src/entity-commands.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, promises as fsPromises } from "node:fs";
 import { basename, join } from "node:path";
 import {
   orderActorFrontmatter,
@@ -36,12 +36,22 @@ export function createActor(args: { name: string; displayName?: string; type?: s
   return { name, path: relativePath(path, root) };
 }
 
-export function listActors(args: { cwd?: string }) {
+export async function listActors(args: { cwd?: string }) {
   const { root } = mustConfig(args.cwd);
-  return walkFiles(join(root, "specs/actors"), (path) => path.endsWith(".md")).map((path) => ({
-    ...parseActorFrontmatter(parseMatter(readFileSync(path, "utf8")).data),
-    path: relativePath(path, root),
-  }));
+  const files = walkFiles(join(root, "specs/actors"), (path) => path.endsWith(".md"));
+  const results = [];
+  const chunkSize = 100;
+  for (let i = 0; i < files.length; i += chunkSize) {
+    const chunk = files.slice(i, i + chunkSize);
+    const parsedChunk = await Promise.all(
+      chunk.map(async (path) => ({
+        ...parseActorFrontmatter(parseMatter(await fsPromises.readFile(path, "utf8")).data),
+        path: relativePath(path, root),
+      }))
+    );
+    results.push(...parsedChunk);
+  }
+  return results;
 }
 
 export function showActor(args: { name: string; cwd?: string }) {
@@ -105,12 +115,22 @@ export function createStakeholder(args: { name: string; displayName?: string; ty
   return { name, path: relativePath(path, root) };
 }
 
-export function listStakeholders(args: { cwd?: string }) {
+export async function listStakeholders(args: { cwd?: string }) {
   const { root } = mustConfig(args.cwd);
-  return walkFiles(join(root, "specs/stakeholders"), (path) => path.endsWith(".md")).map((path) => ({
-    ...parseStakeholderFrontmatter(parseMatter(readFileSync(path, "utf8")).data),
-    path: relativePath(path, root),
-  }));
+  const files = walkFiles(join(root, "specs/stakeholders"), (path) => path.endsWith(".md"));
+  const results = [];
+  const chunkSize = 100;
+  for (let i = 0; i < files.length; i += chunkSize) {
+    const chunk = files.slice(i, i + chunkSize);
+    const parsedChunk = await Promise.all(
+      chunk.map(async (path) => ({
+        ...parseStakeholderFrontmatter(parseMatter(await fsPromises.readFile(path, "utf8")).data),
+        path: relativePath(path, root),
+      }))
+    );
+    results.push(...parsedChunk);
+  }
+  return results;
 }
 
 export function showStakeholder(args: { name: string; cwd?: string }) {
@@ -179,10 +199,22 @@ export function createGoal(args: { actor: string; description: string; level?: s
   return { id, path: relativePath(path, root) };
 }
 
-export function listGoals(args: { actor?: string; status?: string; cwd?: string }) {
+export async function listGoals(args: { actor?: string; status?: string; cwd?: string }) {
   const { root } = mustConfig(args.cwd);
-  return walkFiles(join(root, "specs/goals"), (path) => path.endsWith(".md"))
-    .map((path) => ({ path, frontmatter: parseGoalFrontmatter(parseMatter(readFileSync(path, "utf8")).data) }))
+  const files = walkFiles(join(root, "specs/goals"), (path) => path.endsWith(".md"));
+  const results: { path: string; frontmatter: GoalFrontmatter }[] = [];
+  const chunkSize = 100;
+  for (let i = 0; i < files.length; i += chunkSize) {
+    const chunk = files.slice(i, i + chunkSize);
+    const parsedChunk = await Promise.all(
+      chunk.map(async (path) => ({
+        path,
+        frontmatter: parseGoalFrontmatter(parseMatter(await fsPromises.readFile(path, "utf8")).data),
+      }))
+    );
+    results.push(...parsedChunk);
+  }
+  return results
     .filter(({ frontmatter }) => !args.actor || frontmatter.actor === slugify(args.actor))
     .filter(({ frontmatter }) => !args.status || frontmatter.status === args.status.toUpperCase())
     .map(({ path, frontmatter }) => ({ ...frontmatter, path: relativePath(path, root) }));

src/usecase-commands.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, promises as fsPromises } from "node:fs";
 import { join } from "node:path";
 import {
   orderActorFrontmatter,
@@ -84,11 +84,25 @@ 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"));
+
+  const results: { path: string; parsed: ParsedUseCase }[] = [];
+  const chunkSize = 100;
+  for (let i = 0; i < files.length; i += chunkSize) {
+    const chunk = files.slice(i, i + chunkSize);
+    const parsedChunk = await Promise.all(
+      chunk.map(async (path) => ({
+        path,
+        parsed: parseUseCaseMarkdown(await fsPromises.readFile(path, "utf8")),
+      }))
+    );
+    results.push(...parsedChunk);
+  }
+
+  return results
     .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 });
   });