qfai 1.0.0 → 1.0.2

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 以上
 
 ## パッケージ
 
@@ -67,7 +67,7 @@ npx qfai report
 ## 使い方（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 以降の方針）
@@ -79,7 +79,7 @@ QFAI が提供するプロンプト資産は次の 2 つに分離します。
 
 同じ相対パスのファイルがある場合は `.qfai/prompts.local` を優先して参照する運用とします。
 
-`report.json` は非契約（experimental / internal）として扱います。外部 consumer は依存しないでください。フィールドは例であり固定ではありません。短い例:
+`report.json` / `doctor.json` は内部表現で互換非保証です。外部連携は `report.md` など Markdown 出力を推奨します。破壊的変更は原則 SemVer で管理しますが、プロジェクト方針により例外的に minor/patch で破壊的変更を行う場合があります（CHANGELOG に明記）。JSON schema を固定する約束はしません。短い例:
 
 ```json
 {
@@ -101,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
 {
@@ -239,7 +239,7 @@ qfai.config.yaml
     spec-0001/
       spec.md
       delta.md
-      scenario.md
+      scenario.feature
   rules/
     conventions.md
     pnpm.md

package/assets/init/.qfai/README.md

@@ -17,11 +17,11 @@ npx qfai report
 
 - `validation.traceability.testFileGlobs` に一致するテストコードで `QFAI:SC-xxxx` を参照する（コメント可）
 - Spec→Contract は `spec.md` の `QFAI-CONTRACT-REF` 行で宣言する
-- Scenario→Contract は `scenario.md` の `# QFAI-CONTRACT-REF` で宣言する（none 可）
+- Scenario→Contract は `scenario.feature` の `# QFAI-CONTRACT-REF` で宣言する（none 可）
 
 ## ディレクトリ概要
 
-- `specs/` : Spec Pack（spec.md / delta.md / scenario.md）
+- `specs/` : Spec Pack（spec.md / delta.md / scenario.feature）
 - `contracts/` : UI / API / DB 契約を置く場所
 - `require/` : 既存要件の集約（validate 対象外）
 - `rules/` : 規約・運用ルール

package/assets/init/.qfai/contracts/README.md

@@ -63,7 +63,7 @@ CREATE TABLE sample_table (
 ## 依存関係
 
 - Spec → Contracts（spec.md に `QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`。この行が SSOT）
-- Scenario → Contracts（scenario.md に `# QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`）
+- Scenario → Contracts（scenario.feature に `# QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`）
 
 ## 良い例 / 悪い例
 

package/assets/init/.qfai/prompts/makeBusinessFlow.md

@@ -5,7 +5,7 @@ Spec群を読み、Specに明示されている情報のみを根拠として、
 
 ## Inputs
 
-- 対象: `.qfai/specs/spec-*/spec.md` 形式のファイル（Spec Pack の `spec.md`。必要に応じて `scenario.md` / `delta.md` も補助参照）
+- 対象: `.qfai/specs/spec-*/spec.md` 形式のファイル（Spec Pack の `spec.md`。必要に応じて `scenario.feature` / `delta.md` も補助参照）
 
 ## Output (Option)
 

package/assets/init/.qfai/prompts/makeOverview.md

@@ -4,7 +4,7 @@
 
 ## Inputs
 
-- 対象: `.qfai/specs/spec-*/spec.md` 形式のファイル（Spec Pack の `spec.md`。必要に応じて `scenario.md` / `delta.md` も補助参照）
+- 対象: `.qfai/specs/spec-*/spec.md` 形式のファイル（Spec Pack の `spec.md`。必要に応じて `scenario.feature` / `delta.md` も補助参照）
 
 ## Output
 

package/assets/init/.qfai/prompts/qfai-maintain-traceability.md

@@ -9,7 +9,7 @@
 
 ## 必須入力
 
-- `.qfai/specs/**/spec.md` / `scenario.md` / `delta.md`
+- `.qfai/specs/**/spec.md` / `scenario.feature` / `delta.md`
 - `.qfai/out/validate.json`（あれば）
 - `.qfai/out/report.md`（あれば）
 - テストコード（`validation.traceability.testFileGlobs` に一致する範囲）

package/assets/init/.qfai/prompts/require-to-spec.md

@@ -11,7 +11,7 @@
 
 - `.qfai/specs/spec-0001/spec.md`
 - `.qfai/specs/spec-0001/delta.md`
-- `.qfai/specs/spec-0001/scenario.md`
+- `.qfai/specs/spec-0001/scenario.feature`
 - 必要に応じて `.qfai/contracts/{ui,api,db}` 配下
 
 > Spec は `spec-0001` から開始し、必要なら連番で増やすこと。
@@ -23,7 +23,7 @@
 - `spec.md` の必須セクションは `qfai.config.yaml` の設定に従う。
 - BR は `## 業務ルール` にのみ定義し、`- [BR-0001][P1] ...` 形式で書く。
 - `spec.md` に `QFAI-CONTRACT-REF:` を必ず記載する（不要なら `none`）。
-- `scenario.md` は Gherkin で書き、Feature に `@SPEC-xxxx` を付与する。
+- `scenario.feature` は Gherkin で書き、Feature に `@SPEC-xxxx` を付与する。
 - 各 Scenario は `@SC-xxxx` を **ちょうど1つ**、`@BR-xxxx` を **1つ以上**持つこと。
 - 契約ファイルには `QFAI-CONTRACT-ID: <ID>` を宣言する。
 - 契約 ID（UI/API/DB）を Scenario で参照する場合はタグまたは本文に明示する。

package/assets/init/.qfai/samples/analyze/analysis.md

@@ -12,7 +12,7 @@
 ## 入力（貼り付けたもの）
 
 - Spec: <spec.md / delta.md の該当範囲>
-- Scenario: <scenario.md の該当範囲>
+- Scenario: <scenario.feature の該当範囲>
 - Contract（任意）: <該当契約>
 - validate/report 要約: <report.md または validate.json の要約>
 - 差分: <PR diff / 変更ファイル一覧>

package/assets/init/.qfai/specs/README.md

@@ -6,7 +6,7 @@
 
 - `spec-0001/spec.md`（必須）
 - `spec-0001/delta.md`（必須）
-- `spec-0001/scenario.md`（必須・Gherkin）
+- `spec-0001/scenario.feature`（必須・Gherkin）
 
 > `spec-0001` は **4桁連番**。Spec ID も **4桁（SPEC-0001）** です。
 
@@ -42,7 +42,7 @@ QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
 - 互換維持 / 仕様変更の **どちらか1つ**に必ずチェックする
 - 根拠と影響範囲を明記する
 
-## Scenario（scenario.md）最小要件
+## Scenario（scenario.feature）最小要件
 
 - **Gherkin 記法**（Given/When/Then）
 - **1ファイル = 1 Scenario**（Scenario Outline 含む）

package/assets/init/.qfai/specs/spec-0001/delta.md

@@ -16,7 +16,7 @@
 ## 影響範囲（Impact）
 
 - 仕様（spec.md）:
-- シナリオ（scenario.md）:
+- シナリオ（scenario.feature）:
 - 契約（contracts）:
 - 実装（src）:
 - テスト（tests）:

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) {
@@ -617,7 +650,7 @@ async function collectSpecEntries(specsRoot) {
     dir,
     specPath: import_node_path4.default.join(dir, "spec.md"),
     deltaPath: import_node_path4.default.join(dir, "delta.md"),
-    scenarioPath: import_node_path4.default.join(dir, "scenario.md")
+    scenarioPath: import_node_path4.default.join(dir, "scenario.feature")
   }));
   return entries.sort((a, b) => a.dir.localeCompare(b.dir));
 }
@@ -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 ("1.0.0".length > 0) {
-    return "1.0.0";
+  if ("1.0.2".length > 0) {
+    return "1.0.2";
   }
   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);
@@ -2559,12 +2625,11 @@ async function validateScenarios(root, config) {
   const specsRoot = resolvePath(root, config, "specsDir");
   const entries = await collectSpecEntries(specsRoot);
   if (entries.length === 0) {
-    const expected = "spec-0001/scenario.md";
-    const legacy = "spec-001/scenario.md";
+    const expected = "spec-0001/scenario.feature";
     return [
       issue4(
         "QFAI-SC-000",
-        `Scenario \u30D5\u30A1\u30A4\u30EB\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002\u914D\u7F6E\u5834\u6240: ${config.paths.specsDir} / \u671F\u5F85\u30D1\u30BF\u30FC\u30F3: ${expected} (${legacy} \u306F\u975E\u5BFE\u5FDC)`,
+        `Scenario \u30D5\u30A1\u30A4\u30EB\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002\u914D\u7F6E\u5834\u6240: ${config.paths.specsDir} / \u671F\u5F85\u30D1\u30BF\u30FC\u30F3: ${expected}`,
         "info",
         specsRoot,
         "scenario.files"
@@ -2581,7 +2646,7 @@ async function validateScenarios(root, config) {
         issues.push(
           issue4(
             "QFAI-SC-001",
-            "scenario.md \u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002",
+            "scenario.feature \u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002",
             "error",
             entry.scenarioPath,
             "scenario.exists"
@@ -3543,13 +3608,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 +3754,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 +3880,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 +3894,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 +3912,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 +3928,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 +3942,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 +4099,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 +4187,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 +4240,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 +4338,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 +4597,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 +4704,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 +4754,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
 `;
 }