qfai 0.9.2 → 1.0.1

package/README.md

@@ -39,7 +39,7 @@ pnpm の場合（推奨）:
 pnpm add -D qfai
 ```
 
-**必要環境**: Node.js >= 18
+**必要環境**: Node.js >= 18.0.0（Supported） / Tested: Node.js 18, 20 / Recommended: Node.js 20 LTS 以上
 
 ## パッケージ
 
@@ -62,12 +62,12 @@ npx qfai report
 - `npx qfai doctor` による設定/探索/パス/glob/validate.json の事前診断
 - `npx qfai report` によるレポート出力
 
-補足: v0.x は日本語テンプレ中心で提供します。将来は英語を正本、日本語を別ドキュメントに切り替える方針です。
+補足: v1.x は日本語テンプレ中心で提供します。将来は英語を正本、日本語を別ドキュメントに切り替える方針です。
 
 ## 使い方（CLI）
 
 `validate` は `--fail-on` / `--strict` によって CI ゲート化できます。`validate` は常に `.qfai/out/validate.json`（`output.validateJsonPath`）へ JSON を出力します。`--format` は画面表示（text/github）のみを制御します。`--format github` はアノテーションの上限と重複排除を行い、先頭にサマリを出します（全量は `validate.json` か `--format text` を参照）。
-`report` は `.qfai/out/validate.json` を既定入力とし、`--in` で上書きできます（優先順位: CLI > config）。`--run-validate` を指定すると validate を実行してから report を生成します。出力先は `--out` で変更できます（`--format json` の場合は `.qfai/out/report.json`）。
+`report` は `.qfai/out/validate.json` を既定入力とし、`--in` で上書きできます（優先順位: CLI > config）。`--run-validate` を指定すると validate を実行してから report を生成します。出力先は `--out` で変更できます（`--format json` の場合は `.qfai/out/report.json`）。`--base-url <url>` を指定すると、report.md 内の相対パスをリンク化します（例: `npx qfai report --base-url https://example.com/repo`）。
 `doctor` は validate/report の前段で設定/探索/パス/glob/validate.json を診断します。`--format text|json`、`--out` をサポートし、診断のみ（修復はしません）。`--fail-on warning|error` を指定すると該当 severity 以上で exit 1（未指定は常に exit 0）になります。
 
 ### Prompts Overlay（v0.7 以降の方針）
@@ -78,7 +78,8 @@ QFAI が提供するプロンプト資産は次の 2 つに分離します。
 - `.qfai/prompts.local/**`: 利用者カスタム資産（QFAI はここを上書きしない）
 
 同じ相対パスのファイルがある場合は `.qfai/prompts.local` を優先して参照する運用とします。
-`report.json` は非契約（experimental / internal）として扱います。外部 consumer は依存しないでください。フィールドは例であり固定ではありません。短い例:
+
+`report.json` / `doctor.json` は内部表現で互換非保証です。外部連携は `report.md` など Markdown 出力を推奨します。破壊的変更は SemVer で管理しますが、JSON schema を固定する約束はしません。短い例:
 
 ```json
 {
@@ -100,7 +101,7 @@ qfai doctor: root=. config=qfai.config.yaml (found)
 summary: ok=10 info=1 warning=2 error=0
 ```
 
-doctor の JSON も非契約（内部形式。将来予告なく変更あり）です。フィールドは例であり固定ではありません。短い例:
+doctor の JSON 例:
 
 ```json
 {
@@ -123,7 +124,7 @@ doctor の JSON も非契約（内部形式。将来予告なく変更あり）
 
 ## analyze（意味矛盾のレビュー補助）
 
-`validate` は deterministic な構造矛盾（参照/フォーマット/トレーサビリティ）を検査し、CI Hard Gate にできます。一方で、**意味矛盾（解釈/前提/用語/例外/受入条件の齟齬）**は deterministic に検出できないため、v0.9 では **手動プロンプト**として導線を提供します。
+`validate` は deterministic な構造矛盾（参照/フォーマット/トレーサビリティ）を検査し、CI Hard Gate にできます。一方で、**意味矛盾（解釈/前提/用語/例外/受入条件の齟齬）**は deterministic に検出できないため、v1.0 では **手動プロンプト**として導線を提供します。
 
 重要:
 
@@ -301,4 +302,4 @@ pnpm test:assets
 
 ## ライセンス
 
-[MIT](https://github.com/aganesy/QFAI/blob/main/packages/qfai/LICENSE)
+[MIT](./LICENSE)

package/dist/cli/index.cjs

@@ -39,6 +39,7 @@ var DEFAULT_IGNORE_DIRS = /* @__PURE__ */ new Set([
   "tmp",
   ".mcp-tools"
 ]);
+var DEFAULT_GLOB_FILE_LIMIT = 2e4;
 async function collectFiles(root, options = {}) {
   const entries = [];
   if (!await exists(root)) {
@@ -53,16 +54,29 @@ async function collectFiles(root, options = {}) {
   return entries;
 }
 async function collectFilesByGlobs(root, options) {
+  const limit = normalizeLimit(options.limit);
   if (options.globs.length === 0) {
-    return [];
+    return { files: [], truncated: false, matchedFileCount: 0, limit };
   }
-  return (0, import_fast_glob.default)(options.globs, {
+  const stream = import_fast_glob.default.stream(options.globs, {
     cwd: root,
     ignore: options.ignore ?? [],
     onlyFiles: true,
     absolute: true,
     unique: true
   });
+  const files = [];
+  let truncated = false;
+  for await (const entry of stream) {
+    if (files.length >= limit) {
+      truncated = true;
+      destroyStream(stream);
+      break;
+    }
+    files.push(String(entry));
+  }
+  const matchedFileCount = files.length;
+  return { files, truncated, matchedFileCount, limit };
 }
 async function walk(base, current, ignoreDirs, extensions, out) {
   const items = await (0, import_promises.readdir)(current, { withFileTypes: true });
@@ -94,6 +108,25 @@ async function exists(target) {
     return false;
   }
 }
+function normalizeLimit(value) {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    return DEFAULT_GLOB_FILE_LIMIT;
+  }
+  const flooredValue = Math.floor(value);
+  if (flooredValue <= 0) {
+    return DEFAULT_GLOB_FILE_LIMIT;
+  }
+  return flooredValue;
+}
+function destroyStream(stream) {
+  if (!stream || typeof stream !== "object") {
+    return;
+  }
+  const record2 = stream;
+  if (typeof record2.destroy === "function") {
+    record2.destroy();
+  }
+}
 
 // src/cli/commands/analyze.ts
 async function runAnalyze(options) {
@@ -909,15 +942,18 @@ async function collectScTestReferences(root, globs, excludeGlobs) {
       scan: {
         globs: normalizedGlobs,
         excludeGlobs: mergedExcludeGlobs,
-        matchedFileCount: 0
+        matchedFileCount: 0,
+        truncated: false,
+        limit: DEFAULT_GLOB_FILE_LIMIT
       }
     };
   }
-  let files = [];
+  let scanResult;
   try {
-    files = await collectFilesByGlobs(root, {
+    scanResult = await collectFilesByGlobs(root, {
       globs: normalizedGlobs,
-      ignore: mergedExcludeGlobs
+      ignore: mergedExcludeGlobs,
+      limit: DEFAULT_GLOB_FILE_LIMIT
     });
   } catch (error2) {
     return {
@@ -925,13 +961,15 @@ async function collectScTestReferences(root, globs, excludeGlobs) {
       scan: {
         globs: normalizedGlobs,
         excludeGlobs: mergedExcludeGlobs,
-        matchedFileCount: 0
+        matchedFileCount: 0,
+        truncated: false,
+        limit: DEFAULT_GLOB_FILE_LIMIT
       },
       error: formatError3(error2)
     };
   }
   const normalizedFiles = Array.from(
-    new Set(files.map((file) => import_node_path6.default.normalize(file)))
+    new Set(scanResult.files.map((file) => import_node_path6.default.normalize(file)))
   );
   for (const file of normalizedFiles) {
     const text = await (0, import_promises6.readFile)(file, "utf-8");
@@ -950,7 +988,9 @@ async function collectScTestReferences(root, globs, excludeGlobs) {
     scan: {
       globs: normalizedGlobs,
       excludeGlobs: mergedExcludeGlobs,
-      matchedFileCount: normalizedFiles.length
+      matchedFileCount: scanResult.matchedFileCount,
+      truncated: scanResult.truncated,
+      limit: scanResult.limit
     }
   };
 }
@@ -1120,8 +1160,8 @@ var import_promises8 = require("fs/promises");
 var import_node_path9 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 async function resolveToolVersion() {
-  if ("0.9.2".length > 0) {
-    return "0.9.2";
+  if ("1.0.1".length > 0) {
+    return "1.0.1";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -1332,19 +1372,27 @@ async function createDoctorData(options) {
     ...config.validation.traceability.testFileExcludeGlobs
   ]);
   try {
-    const matched = globs.length === 0 ? [] : await collectFilesByGlobs(root, { globs, ignore: exclude });
-    const matchedCount = matched.length;
-    const severity = globs.length === 0 ? "warning" : scenarioFiles.length > 0 && config.validation.traceability.scMustHaveTest && matchedCount === 0 ? "warning" : "ok";
+    const scanResult = globs.length === 0 ? {
+      files: [],
+      truncated: false,
+      matchedFileCount: 0,
+      limit: DEFAULT_GLOB_FILE_LIMIT
+    } : await collectFilesByGlobs(root, { globs, ignore: exclude });
+    const matchedCount = scanResult.matchedFileCount;
+    const truncated = scanResult.truncated;
+    const severity = globs.length === 0 ? "warning" : truncated ? "warning" : scenarioFiles.length > 0 && config.validation.traceability.scMustHaveTest && matchedCount === 0 ? "warning" : "ok";
     addCheck(checks, {
       id: "traceability.testGlobs",
       severity,
       title: "Test file globs",
-      message: globs.length === 0 ? "testFileGlobs is empty (SC\u2192Test cannot be verified)" : `matchedFileCount=${matchedCount}`,
+      message: globs.length === 0 ? "testFileGlobs is empty (SC\u2192Test cannot be verified)" : truncated ? `fileCount=${matchedCount} (truncated, limit=${scanResult.limit})` : `fileCount=${matchedCount}`,
       details: {
         globs,
         excludeGlobs: exclude,
         scenarioFiles: scenarioFiles.length,
-        scMustHaveTest: config.validation.traceability.scMustHaveTest
+        scMustHaveTest: config.validation.traceability.scMustHaveTest,
+        truncated,
+        limit: scanResult.limit
       }
     });
   } catch (error2) {
@@ -1353,7 +1401,12 @@ async function createDoctorData(options) {
       severity: "error",
       title: "Test file globs",
       message: "Glob scan failed (invalid pattern or filesystem error)",
-      details: { globs, excludeGlobs: exclude, error: String(error2) }
+      details: {
+        globs,
+        excludeGlobs: exclude,
+        limit: DEFAULT_GLOB_FILE_LIMIT,
+        error: String(error2)
+      }
     });
   }
   return {
@@ -1387,8 +1440,10 @@ async function buildOutDirCollisionCheck(root) {
         (collisionRoot) => toRelativePath(result.monorepoRoot, collisionRoot)
       ).sort((a, b) => a.localeCompare(b))
     })).sort((a, b) => a.outDir.localeCompare(b.outDir));
-    const severity = collisions.length > 0 ? "warning" : "ok";
-    const message = collisions.length > 0 ? `outDir collision detected (count=${collisions.length})` : `outDir collision not detected (configs=${configRoots.length})`;
+    const truncated = result.scan.truncated;
+    const severity = collisions.length > 0 || truncated ? "warning" : "ok";
+    const messageBase = collisions.length > 0 ? `outDir collision detected (count=${collisions.length})` : `outDir collision not detected (configs=${configRoots.length})`;
+    const message = truncated ? `${messageBase}; scan truncated (collected=${result.scan.matchedFileCount}, limit=${result.scan.limit})` : messageBase;
     return {
       id: "output.outDirCollision",
       severity,
@@ -1397,7 +1452,8 @@ async function buildOutDirCollisionCheck(root) {
       details: {
         monorepoRoot: relativeRoot,
         configRoots,
-        collisions
+        collisions,
+        scan: result.scan
       }
     };
   } catch (error2) {
@@ -1412,10 +1468,11 @@ async function buildOutDirCollisionCheck(root) {
 }
 async function detectOutDirCollisions(root) {
   const monorepoRoot = await findMonorepoRoot(root);
-  const configPaths = await collectFilesByGlobs(monorepoRoot, {
+  const configScan = await collectFilesByGlobs(monorepoRoot, {
     globs: ["**/qfai.config.yaml"],
     ignore: DEFAULT_CONFIG_SEARCH_IGNORE_GLOBS
   });
+  const configPaths = configScan.files;
   const configRoots = Array.from(
     new Set(configPaths.map((configPath) => import_node_path10.default.dirname(configPath)))
   ).sort((a, b) => a.localeCompare(b));
@@ -1436,7 +1493,16 @@ async function detectOutDirCollisions(root) {
       });
     }
   }
-  return { monorepoRoot, configRoots, collisions };
+  return {
+    monorepoRoot,
+    configRoots,
+    collisions,
+    scan: {
+      truncated: configScan.truncated,
+      matchedFileCount: configScan.matchedFileCount,
+      limit: configScan.limit
+    }
+  };
 }
 async function findMonorepoRoot(startDir) {
   let current = import_node_path10.default.resolve(startDir);
@@ -3543,13 +3609,14 @@ async function createReportData(root, validation, configResult) {
     issues: normalizedValidation.issues
   };
 }
-function formatReportMarkdown(data) {
+function formatReportMarkdown(data, options = {}) {
   const lines = [];
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
   lines.push("# QFAI Report");
   lines.push("");
   lines.push(`- \u751F\u6210\u65E5\u6642: ${data.generatedAt}`);
-  lines.push(`- \u30EB\u30FC\u30C8: ${data.root}`);
-  lines.push(`- \u8A2D\u5B9A: ${data.configPath}`);
+  lines.push(`- \u30EB\u30FC\u30C8: ${formatPathLink(data.root, baseUrl)}`);
+  lines.push(`- \u8A2D\u5B9A: ${formatPathLink(data.configPath, baseUrl)}`);
   lines.push(`- \u7248: ${data.version}`);
   lines.push("");
   const severityOrder = {
@@ -3688,8 +3755,7 @@ function formatReportMarkdown(data) {
         `#### ${item.severity.toUpperCase()} [${item.code}] ${item.message}`
       );
       if (item.file) {
-        const loc = item.loc?.line ? `:${item.loc.line}` : "";
-        out.push(`- file: ${item.file}${loc}`);
+        out.push(`- file: ${formatPathWithLine(item.file, item.loc, baseUrl)}`);
       }
       if (item.rule) {
         out.push(`- rule: ${item.rule}`);
@@ -3815,6 +3881,11 @@ function formatReportMarkdown(data) {
   lines.push(
     `- testFileCount: ${data.traceability.testFiles.matchedFileCount}`
   );
+  if (data.traceability.testFiles.truncated) {
+    lines.push(
+      `- testFileTruncated: true (limit=${data.traceability.testFiles.limit})`
+    );
+  }
   if (data.traceability.sc.missingIds.length === 0) {
     lines.push("- missingIds: (none)");
   } else {
@@ -3824,7 +3895,8 @@ function formatReportMarkdown(data) {
       if (files.length === 0) {
         return id;
       }
-      return `${id} (${files.join(", ")})`;
+      const formattedFiles = files.map((file) => formatPathLink(file, baseUrl));
+      return `${id} (${formattedFiles.join(", ")})`;
     });
     lines.push(`- missingIds: ${missingWithSources.join(", ")}`);
   }
@@ -3841,7 +3913,8 @@ function formatReportMarkdown(data) {
       if (refs.length === 0) {
         lines.push(`- ${scId}: (none)`);
       } else {
-        lines.push(`- ${scId}: ${refs.join(", ")}`);
+        const formattedRefs = refs.map((ref) => formatPathLink(ref, baseUrl));
+        lines.push(`- ${scId}: ${formattedRefs.join(", ")}`);
       }
     }
   }
@@ -3856,8 +3929,9 @@ function formatReportMarkdown(data) {
   } else {
     for (const item of specScIssues) {
       const location = item.file ?? "(unknown)";
+      const formattedLocation = location === "(unknown)" ? location : formatPathLink(location, baseUrl);
       const refs = item.refs && item.refs.length > 0 ? item.refs.join(", ") : item.message;
-      lines.push(`- ${location}: ${refs}`);
+      lines.push(`- ${formattedLocation}: ${refs}`);
     }
   }
   lines.push("");
@@ -3869,7 +3943,7 @@ function formatReportMarkdown(data) {
   } else {
     for (const spot of hotspots) {
       lines.push(
-        `- ${spot.file}: total ${spot.total} (error ${spot.error} / warning ${spot.warning} / info ${spot.info})`
+        `- ${formatPathLink(spot.file, baseUrl)}: total ${spot.total} (error ${spot.error} / warning ${spot.warning} / info ${spot.info})`
       );
     }
   }
@@ -4026,6 +4100,41 @@ function formatMarkdownTable(headers, rows) {
   const separator = `| ${widths.map((width) => "-".repeat(width)).join(" | ")} |`;
   return [formatRow(headers), separator, ...rows.map(formatRow)];
 }
+function normalizeBaseUrl(value) {
+  if (!value) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  return trimmed.replace(/\/+$/, "");
+}
+function formatPathLink(value, baseUrl) {
+  if (!baseUrl) {
+    return value;
+  }
+  if (value === ".") {
+    return `[${value}](${baseUrl})`;
+  }
+  const encoded = encodePathForUrl(value);
+  if (!encoded) {
+    return value;
+  }
+  return `[${value}](${baseUrl}/${encoded})`;
+}
+function formatPathWithLine(value, loc, baseUrl) {
+  const link = formatPathLink(value, baseUrl);
+  const line = loc?.line ? `:${loc.line}` : "";
+  return `${link}${line}`;
+}
+function encodePathForUrl(value) {
+  const normalized = value.replace(/\\/g, "/");
+  if (normalized === ".") {
+    return "";
+  }
+  return normalized.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
 function toSortedArray2(values) {
   return Array.from(values).sort((a, b) => a.localeCompare(b));
 }
@@ -4079,6 +4188,16 @@ function buildHotspots(issues) {
   );
 }
 
+// src/cli/lib/warnings.ts
+function warnIfTruncated(scan, context) {
+  if (!scan.truncated) {
+    return;
+  }
+  warn(
+    `[warn] ${context}: file scan truncated: collected ${scan.matchedFileCount} files (limit ${scan.limit})`
+  );
+}
+
 // src/cli/commands/report.ts
 async function runReport(options) {
   const root = import_node_path20.default.resolve(options.root);
@@ -4122,7 +4241,8 @@ async function runReport(options) {
     }
   }
   const data = await createReportData(root, validation, configResult);
-  const output = options.format === "json" ? formatReportJson(data) : formatReportMarkdown(data);
+  warnIfTruncated(data.traceability.testFiles, "report");
+  const output = options.format === "json" ? formatReportJson(data) : options.baseUrl ? formatReportMarkdown(data, { baseUrl: options.baseUrl }) : formatReportMarkdown(data);
   const outRoot = resolvePath(root, configResult.config, "outDir");
   const defaultOut = options.format === "json" ? import_node_path20.default.join(outRoot, "report.json") : import_node_path20.default.join(outRoot, "report.md");
   const out = options.outPath ?? defaultOut;
@@ -4219,6 +4339,7 @@ async function runValidate(options) {
   const configResult = await loadConfig(root);
   const result = await validateProject(root, configResult);
   const normalized = normalizeValidationResult(root, result);
+  warnIfTruncated(normalized.traceability.testFiles, "validate");
   const failOn = resolveFailOn(options, configResult.config.validation.failOn);
   const willFail = shouldFail(normalized, failOn);
   const format = options.format ?? "text";
@@ -4477,6 +4598,17 @@ function parseArgs(argv, cwd) {
       case "--run-validate":
         options.reportRunValidate = true;
         break;
+      case "--base-url": {
+        const next = readOptionValue(args, i);
+        if (next === null) {
+          invalid = true;
+          options.help = true;
+          break;
+        }
+        options.reportBaseUrl = next;
+        i += 1;
+        break;
+      }
       case "--help":
       case "-h":
         options.help = true;
@@ -4573,6 +4705,7 @@ async function run(argv, cwd) {
           format: options.reportFormat,
           ...options.reportOut !== void 0 ? { outPath: options.reportOut } : {},
           ...options.reportIn !== void 0 ? { inputPath: options.reportIn } : {},
+          ...options.reportBaseUrl !== void 0 ? { baseUrl: options.reportBaseUrl } : {},
           ...options.reportRunValidate ? { runValidate: true } : {}
         });
       }
@@ -4622,6 +4755,7 @@ Options:
   --out <path>                  report/doctor: \u51FA\u529B\u5148
   --in <path>                   report: validate.json \u306E\u5165\u529B\u5148\uFF08config\u3088\u308A\u512A\u5148\uFF09
   --run-validate                report: validate \u3092\u5B9F\u884C\u3057\u3066\u304B\u3089 report \u3092\u751F\u6210
+  --base-url <url>              report: \u30D1\u30B9\u3092\u30EA\u30F3\u30AF\u5316\u3059\u308B\u57FA\u6E96URL
   -h, --help      \u30D8\u30EB\u30D7\u8868\u793A
 `;
 }