qfai 0.6.0 → 0.6.3

package/README.md

@@ -1,16 +1,46 @@
 # QFAI Toolkit
 
-Single-package distribution for QFAI.
+[![npm version](https://img.shields.io/npm/v/qfai.svg?style=flat)](https://www.npmjs.com/package/qfai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js->=18-brightgreen.svg)](https://nodejs.org/)
+
+品質重視型AI駆動運用モデル（SDD × ATDD × TDD）を単一パッケージで提供するツールキットです。
+
+## 目次
+
+- [インストール](#インストール)
+- [Quick Start](#quick-start最短成功)
+- [機能](#できること)
+- [CLI リファレンス](#使い方cli)
+- [設定](#設定)
+- [契約](#契約contracts)
+- [Monorepo 対応](#monorepo--サブディレクトリ)
+- [CI 統合](#ci-と-hard-gate)
+- [GitHub Actions](#github-actions-テンプレート)
+- [開発](#開発)
+- [ライセンス](#ライセンス)
+
+## インストール
+
+```sh
+npm install qfai
+```
 
-## Install
+または
 
-```
-npm i -D qfai
+```sh
+npx qfai init
 ```
 
-## Quick Start
+**必要環境**: Node.js >= 18
 
-```
+## パッケージ
+
+- `qfai`: CLI + コア + テンプレートを同梱
+
+## Quick Start（最短成功）
+
+```sh
 npx qfai init
 npx qfai validate --fail-on error --format github
 npx qfai report
@@ -24,33 +54,76 @@ npx qfai report
 - `npx qfai doctor` による設定/探索/パス/glob/validate.json の事前診断
 - `npx qfai report` によるレポート出力
 
-## Usage
+補足: v0.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`）。
+`doctor` は validate/report の前段で設定/探索/パス/glob/validate.json を診断します。`--format text|json`、`--out` をサポートし、診断のみ（修復はしません）。`--fail-on warning|error` を指定すると該当 severity 以上で exit 1（未指定は常に exit 0）になります。
+`report.json` は非契約（experimental / internal）として扱います。外部 consumer は依存しないでください。フィールドは例であり固定ではありません。短い例:
+
+```json
+{
+  "tool": "qfai",
+  "summary": {
+    "specs": 1,
+    "scenarios": 1,
+    "contracts": { "api": 0, "ui": 1, "db": 0 },
+    "counts": { "info": 0, "warning": 0, "error": 0 }
+  }
+}
+```
+
+doctor（text）の例:
+
+```text
+qfai doctor: root=. config=qfai.config.yaml (found)
+[ok] config.search: qfai.config.yaml found
+summary: ok=10 warning=2 error=0
+```
+
+doctor の JSON も非契約（内部形式。将来予告なく変更あり）です。フィールドは例であり固定ではありません。短い例:
+
+```json
+{
+  "tool": "qfai",
+  "checks": [
+    {
+      "id": "config.search",
+      "severity": "ok",
+      "message": "qfai.config.yaml found"
+    }
+  ]
+}
+```
 
-`validate` は `--fail-on` / `--strict` によって CI ゲート化できます。`validate` は常に `.qfai/out/validate.json`（`output.validateJsonPath`）へ JSON を出力し、`--format` は表示形式（text/github）のみを制御します。
-`report` は `.qfai/out/validate.json` を読み、既定で `.qfai/out/report.md` を出力します（`--format json` の場合は `.qfai/out/report.json`）。出力先は `--out` で変更できます。入力パスは固定です。
-`doctor` は validate/report の前段で設定/探索/パス/glob/validate.json を診断します。`--format text|json`、`--out` をサポートします。
 `init --yes` は予約フラグです（現行の init は非対話のため挙動差はありません）。既存ファイルがある場合は `--force` が必要です。
-`report.json` は experimental（互換保証なし）として扱います。`reportFormatVersion` を含み、破壊的変更時のみ増分します。
+
+## 設定
 
 設定はリポジトリ直下の `qfai.config.yaml` で行います。
 命名規約は `docs/rules/naming.md` を参照してください。
 
-## Contracts
+## 契約（Contracts）
 
-Spec では `QFAI-CONTRACT-REF:` 行で参照する契約IDを宣言します（`none` 可、宣言行は必須）。
-Scenario では `# QFAI-CONTRACT-REF:` のコメント行で契約参照を宣言します（`none` 可、宣言行は必須）。
+Spec では `QFAI-CONTRACT-REF:` 行で参照する契約IDを宣言します（`none` 可）。Spec の先頭 H1 に `SPEC-xxxx` が必須です。
+Scenario では `# QFAI-CONTRACT-REF:` のコメント行で契約参照を宣言します（`none` 可）。
 契約ファイルは `QFAI-CONTRACT-ID: <ID>` を **1ファイル1ID** で宣言します。
-Contract ID prefix は `UI-0001` / `API-0001` / `DB-0001` です。
-宣言では大文字（`UI-0001`）、ファイル名は小文字（`ui-0001-...`）を使用します。
+`validate.json` / `report` の file path は root 相対で出力します（absolute は出力しません）。
 
-契約関連の検証は `validation.traceability` で制御します。
+## Monorepo / サブディレクトリ
 
-- `validation.traceability.orphanContractsPolicy`: Spec から参照されない契約の扱い（default: `error`、`error` / `warning` / `allow`）
-- `validation.traceability.unknownContractIdSeverity`: Scenario が参照した契約 ID が存在しない場合の severity（default: `error`、`error` / `warning` のみ）
-- Spec の `QFAI-CONTRACT-REF` が未知 ID を参照した場合は常に error（`QFAI-TRACE-024`）
-- `unknownContractIdSeverity` は Scenario 側（`QFAI-TRACE-008`）のみを制御
+- `--root` 未指定時は cwd から親へ `qfai.config.yaml` を探索します（見つからない場合は defaultConfig + warning）。
+- monorepo ではパッケージ単位に `qfai.config.yaml` を置くか、`--root` で明示します。
+- `paths.outDir` はパッケージごとに分け、`out/` の衝突を避けてください。
 
-`npx qfai init` は `.qfai/contracts/` 配下に UI/API/DB のサンプルを生成します。
+例（pnpm workspace）:
+
+```text
+packages/<app-a>/qfai.config.yaml   # paths.outDir: .qfai/out/<app-a>
+packages/<app-b>/qfai.config.yaml   # paths.outDir: .qfai/out/<app-b>
+```
 
 ## CI と Hard Gate
 
@@ -68,3 +141,114 @@ SC→Test 検証は `validation.traceability.scMustHaveTest` と
 - `validation.traceability.testFileExcludeGlobs`: 追加の除外 glob（配列、任意）
 - `validation.traceability.scMustHaveTest`: SC→Test 検証の有効/無効を制御（`true` で有効、`false` で無効）
 - `validation.traceability.scNoTestSeverity`: SC 未参照時の重要度を指定（`error` / `warning`）
+
+## GitHub Actions テンプレート
+
+`npx qfai init` で `.github/workflows/qfai.yml` を生成します。テンプレートは `validate` ジョブで `.qfai/out/validate.json` を生成し、`qfai-validation` として artifact をアップロードします。`report` はテンプレートには含まれないため、必要なら別ジョブまたはローカルで `qfai report` を実行してください。
+
+テンプレートは npm 前提です。pnpm を使う場合は `cache` と install コマンドを置き換えてください。
+各 Actions のバージョンは運用方針に合わせて指定してください。
+
+追加で `report` を回す場合の最小例:
+
+```yaml
+jobs:
+  report:
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: npm
+      - run: npm ci
+      - uses: actions/download-artifact@v4
+        with:
+          name: qfai-validation
+          path: .qfai/out
+      - run: npx qfai report --out .qfai/out/report.md
+      - uses: actions/upload-artifact@v4
+        with:
+          name: qfai-report
+          path: .qfai/out/report.md
+```
+
+validate.json のスキーマと例は `docs/schema` / `docs/examples` を参照してください。
+PromptPack は非契約（互換保証なし）です。編集する場合はラップ運用を推奨します。
+
+## 生成される構成（例）
+
+```
+qfai.config.yaml
+.qfai/
+  README.md
+  require/
+    README.md
+  specs/
+    README.md
+    spec-0001/
+      spec.md
+      delta.md
+      scenario.md
+  rules/
+    conventions.md
+    pnpm.md
+  promptpack/
+    constitution.md
+    steering/
+      compatibility-vs-change.md
+      traceability.md
+      naming.md
+    commands/
+      plan.md
+      implement.md
+      review.md
+      release.md
+    roles/
+      qa.md
+      spec.md
+      test.md
+    modes/
+      compatibility.md
+      change.md
+  prompts/
+    README.md
+    makeOverview.md
+    makeBusinessFlow.md
+    require-to-spec.md
+    qfai-generate-test-globs.md
+    qfai-maintain-traceability.md
+    qfai-maintain-contracts.md
+    qfai-classify-change.md
+  contracts/
+    README.md
+    api/
+      api-0001-sample.yaml
+    ui/
+      ui-0001-sample.yaml
+    db/
+      db-0001-sample.sql
+  out/
+    README.md
+tests/
+  qfai-traceability.sample.test.ts
+.github/
+  workflows/
+    qfai.yml
+```
+
+## 開発
+
+```sh
+pnpm install
+pnpm build
+pnpm format:check
+pnpm lint
+pnpm check-types
+pnpm test:assets
+```
+
+## ライセンス
+
+[MIT](https://github.com/aganesy/QFAI/blob/main/LICENSE)

package/dist/cli/index.cjs

@@ -889,8 +889,8 @@ var import_promises6 = require("fs/promises");
 var import_node_path6 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 async function resolveToolVersion() {
-  if ("0.6.0".length > 0) {
-    return "0.6.0";
+  if ("0.6.3".length > 0) {
+    return "0.6.3";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -1021,6 +1021,22 @@ async function createDoctorData(options) {
     message: validateJsonExists ? "validate.json exists (report can run)" : "validate.json is missing (run 'qfai validate' before 'qfai report')",
     details: { path: toRelativePath(root, validateJsonAbs) }
   });
+  const outDirAbs = resolvePath(root, config, "outDir");
+  const rel = import_node_path7.default.relative(outDirAbs, validateJsonAbs);
+  const inside = rel !== "" && !rel.startsWith("..") && !import_node_path7.default.isAbsolute(rel);
+  addCheck(checks, {
+    id: "output.pathAlignment",
+    severity: inside ? "ok" : "warning",
+    title: "Output path alignment",
+    message: inside ? "validateJsonPath is under outDir" : "validateJsonPath is not under outDir (may be intended, but check configuration)",
+    details: {
+      outDir: toRelativePath(root, outDirAbs),
+      validateJsonPath: toRelativePath(root, validateJsonAbs)
+    }
+  });
+  if (options.rootExplicit) {
+    addCheck(checks, await buildOutDirCollisionCheck(root));
+  }
   const scenarioFiles = await collectScenarioFiles(specsRoot);
   const globs = normalizeGlobs2(config.validation.traceability.testFileGlobs);
   const exclude = normalizeGlobs2([
@@ -1052,23 +1068,9 @@ async function createDoctorData(options) {
       details: { globs, excludeGlobs: exclude, error: String(error2) }
     });
   }
-  const outDirAbs = resolvePath(root, config, "outDir");
-  const rel = import_node_path7.default.relative(outDirAbs, validateJsonAbs);
-  const inside = rel !== "" && !rel.startsWith("..") && !import_node_path7.default.isAbsolute(rel);
-  addCheck(checks, {
-    id: "output.pathAlignment",
-    severity: inside ? "ok" : "warning",
-    title: "Output path alignment",
-    message: inside ? "validateJsonPath is under outDir" : "validateJsonPath is not under outDir (may be intended, but check configuration)",
-    details: {
-      outDir: toRelativePath(root, outDirAbs),
-      validateJsonPath: toRelativePath(root, validateJsonAbs)
-    }
-  });
   return {
     tool: "qfai",
     version,
-    doctorFormatVersion: 1,
     generatedAt,
     root: toRelativePath(process.cwd(), root),
     config: {
@@ -1080,6 +1082,90 @@ async function createDoctorData(options) {
     checks
   };
 }
+var DEFAULT_CONFIG_SEARCH_IGNORE_GLOBS = [
+  ...DEFAULT_TEST_FILE_EXCLUDE_GLOBS,
+  "**/.pnpm/**",
+  "**/tmp/**",
+  "**/.mcp-tools/**"
+];
+async function buildOutDirCollisionCheck(root) {
+  try {
+    const result = await detectOutDirCollisions(root);
+    const relativeRoot = toRelativePath(process.cwd(), result.monorepoRoot);
+    const configRoots = result.configRoots.map((configRoot) => toRelativePath(result.monorepoRoot, configRoot)).sort((a, b) => a.localeCompare(b));
+    const collisions = result.collisions.map((item) => ({
+      outDir: toRelativePath(result.monorepoRoot, item.outDir),
+      roots: item.roots.map(
+        (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})`;
+    return {
+      id: "output.outDirCollision",
+      severity,
+      title: "OutDir collision",
+      message,
+      details: {
+        monorepoRoot: relativeRoot,
+        configRoots,
+        collisions
+      }
+    };
+  } catch (error2) {
+    return {
+      id: "output.outDirCollision",
+      severity: "error",
+      title: "OutDir collision",
+      message: "OutDir collision scan failed",
+      details: { error: String(error2) }
+    };
+  }
+}
+async function detectOutDirCollisions(root) {
+  const monorepoRoot = await findMonorepoRoot(root);
+  const configPaths = await collectFilesByGlobs(monorepoRoot, {
+    globs: ["**/qfai.config.yaml"],
+    ignore: DEFAULT_CONFIG_SEARCH_IGNORE_GLOBS
+  });
+  const configRoots = Array.from(
+    new Set(configPaths.map((configPath) => import_node_path7.default.dirname(configPath)))
+  ).sort((a, b) => a.localeCompare(b));
+  const outDirToRoots = /* @__PURE__ */ new Map();
+  for (const configRoot of configRoots) {
+    const { config } = await loadConfig(configRoot);
+    const outDir = import_node_path7.default.normalize(resolvePath(configRoot, config, "outDir"));
+    const roots = outDirToRoots.get(outDir) ?? /* @__PURE__ */ new Set();
+    roots.add(configRoot);
+    outDirToRoots.set(outDir, roots);
+  }
+  const collisions = [];
+  for (const [outDir, roots] of outDirToRoots.entries()) {
+    if (roots.size > 1) {
+      collisions.push({
+        outDir,
+        roots: Array.from(roots).sort((a, b) => a.localeCompare(b))
+      });
+    }
+  }
+  return { monorepoRoot, configRoots, collisions };
+}
+async function findMonorepoRoot(startDir) {
+  let current = import_node_path7.default.resolve(startDir);
+  while (true) {
+    const gitPath = import_node_path7.default.join(current, ".git");
+    const workspacePath = import_node_path7.default.join(current, "pnpm-workspace.yaml");
+    if (await exists4(gitPath) || await exists4(workspacePath)) {
+      return current;
+    }
+    const parent = import_node_path7.default.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return import_node_path7.default.resolve(startDir);
+}
 
 // src/cli/lib/logger.ts
 function info(message) {
@@ -1118,15 +1204,26 @@ async function runDoctor(options) {
     rootExplicit: options.rootExplicit
   });
   const output = options.format === "json" ? formatDoctorJson(data) : formatDoctorText(data);
+  const exitCode = shouldFailDoctor(data.summary, options.failOn) ? 1 : 0;
   if (options.outPath) {
     const outAbs = import_node_path8.default.isAbsolute(options.outPath) ? options.outPath : import_node_path8.default.resolve(process.cwd(), options.outPath);
     await (0, import_promises8.mkdir)(import_node_path8.default.dirname(outAbs), { recursive: true });
     await (0, import_promises8.writeFile)(outAbs, `${output}
 `, "utf-8");
     info(`doctor: wrote ${outAbs}`);
-    return;
+    return exitCode;
   }
   info(output);
+  return exitCode;
+}
+function shouldFailDoctor(summary, failOn) {
+  if (!failOn) {
+    return false;
+  }
+  if (failOn === "error") {
+    return summary.error > 0;
+  }
+  return summary.warning + summary.error > 0;
 }
 
 // src/cli/commands/init.ts
@@ -3021,13 +3118,11 @@ async function createReportData(root, validation, configResult) {
     normalizeScSources(resolvedRoot, scSources)
   );
   const version = await resolveToolVersion();
-  const reportFormatVersion = 1;
   const displayRoot = toRelativePath(resolvedRoot, resolvedRoot);
   const displayConfigPath = toRelativePath(resolvedRoot, configPath);
   return {
     tool: "qfai",
     version,
-    reportFormatVersion,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     root: displayRoot,
     configPath: displayConfigPath,
@@ -3877,12 +3972,16 @@ async function run(argv, cwd) {
       }
       return;
     case "doctor":
-      await runDoctor({
-        root: options.root,
-        rootExplicit: options.rootExplicit,
-        format: options.doctorFormat,
-        ...options.doctorOut !== void 0 ? { outPath: options.doctorOut } : {}
-      });
+      {
+        const exitCode = await runDoctor({
+          root: options.root,
+          rootExplicit: options.rootExplicit,
+          format: options.doctorFormat,
+          ...options.doctorOut !== void 0 ? { outPath: options.doctorOut } : {},
+          ...options.failOn && options.failOn !== "never" ? { failOn: options.failOn } : {}
+        });
+        process.exitCode = exitCode;
+      }
       return;
     default:
       error(`Unknown command: ${command}`);
@@ -3910,6 +4009,7 @@ Options:
   --format <text|json>         doctor \u306E\u51FA\u529B\u5F62\u5F0F
   --strict                     validate: warning \u4EE5\u4E0A\u3067 exit 1
   --fail-on <error|warning|never>  validate: \u5931\u6557\u6761\u4EF6
+  --fail-on <error|warning>        doctor: \u5931\u6557\u6761\u4EF6
   --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