yodogawa 2.1.3 → 2.2.0

package/bin/commands/doctor.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { bold, green, red, yellow, gray } = require('kleur');
+
+const { SEVERITY, makeFinding, summarize, formatPosition } = require('../lib/findings');
+
+// requiresProject: docs/project が無いとき skip するチェック。
+// structure は不在自体を報告し、links は docs/ 全体（docs/tasks 含む）が対象なので走らせる。
+const CHECKS = [
+  { name: 'structure', run: require('../checks/structure').run, requiresProject: false },
+  { name: 'id-trace', run: require('../checks/id-trace').run, requiresProject: true },
+  { name: 'placeholder', run: require('../checks/placeholder').run, requiresProject: true },
+  { name: 'links', run: require('../checks/links').run, requiresProject: false },
+];
+
+const USAGE = `Usage: yodogawa doctor [--dir <path>] [--json]
+
+docs/project/ のトレーサビリティ・構造を検査します。
+
+Options:
+  --dir <path>  検査するプロジェクトのルート（既定: カレントディレクトリ）
+  --json        機械可読な JSON を stdout に出力
+  --help        このヘルプを表示
+
+Exit codes: 0 = Error なし（Warning のみ含む） / 1 = Error あり / 2 = 使い方の誤り`;
+
+function parseArgs(argv) {
+  const opts = { json: false, dir: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') opts.json = true;
+    else if (arg === '--dir') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('-')) {
+        return { error: '--dir にはパスを指定してください' };
+      }
+      opts.dir = argv[++i];
+    } else if (arg === '--help' || arg === '-h') return { help: true };
+    else return { error: `不明なオプション: ${arg}` };
+  }
+  return { opts };
+}
+
+function statusOf(findings) {
+  const { errors, warnings } = summarize(findings);
+  if (errors > 0) return 'fail';
+  if (warnings > 0) return 'warn';
+  return 'pass';
+}
+
+function printHuman(results, summary) {
+  const HEADER = {
+    pass: (name) => `${green('✔')} ${bold(name)}`,
+    warn: (name) => `${yellow('⚠')} ${bold(name)}`,
+    fail: (name) => `${red('✖')} ${bold(name)}`,
+    skip: (name) => `${gray('-')} ${bold(name)} ${gray('(skip)')}`,
+  };
+  for (const result of results) {
+    console.log(HEADER[result.status](result.name));
+    for (const f of result.findings) {
+      const label = f.severity === SEVERITY.ERROR ? red('error') : yellow('warning');
+      console.log(`  ${label} ${formatPosition(f)} ${f.message}`);
+    }
+  }
+  const skipped = results.filter((r) => r.status === 'skip').length;
+  const suffix = skipped > 0 ? `, ${skipped} skipped` : '';
+  const line = `${summary.errors} errors, ${summary.warnings} warnings (${results.length} checks${suffix})`;
+  console.log(summary.errors > 0 ? red(`\n✖ ${line}`) : green(`\n✔ ${line}`));
+}
+
+async function main(argv, { cwd = process.cwd() } = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (parsed.error) {
+    console.error(red(`✖ ${parsed.error}`));
+    console.error(USAGE);
+    return 2;
+  }
+
+  const rootDir = path.resolve(cwd, parsed.opts.dir || '.');
+  if (!fs.existsSync(rootDir)) {
+    console.error(red(`✖ 指定されたディレクトリが存在しません: ${rootDir}`));
+    return 2;
+  }
+
+  const projectMissing = !fs.existsSync(path.join(rootDir, 'docs', 'project'));
+  const results = CHECKS.map(({ name, run, requiresProject }) => {
+    if (projectMissing && requiresProject) {
+      return { name, status: 'skip', findings: [] };
+    }
+    // チェック自体の実行失敗（読み取り不能ファイル等）でも --json の stdout 純度と
+    // exit code 契約を守るため、throw は Error finding に変換する
+    let findings;
+    try {
+      findings = run({ rootDir });
+    } catch (err) {
+      findings = [
+        makeFinding(name, SEVERITY.ERROR, '(internal)', null, `チェックの実行に失敗しました: ${err.message}`),
+      ];
+    }
+    return { name, status: statusOf(findings), findings };
+  });
+
+  const findings = results.flatMap((r) => r.findings);
+  const summary = summarize(findings);
+  const ok = summary.errors === 0;
+
+  if (parsed.opts.json) {
+    const report = {
+      version: 1,
+      ok,
+      summary,
+      checks: results.map(({ name, status }) => ({ name, status })),
+      findings,
+    };
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printHuman(results, summary);
+  }
+  return ok ? 0 : 1;
+}
+
+module.exports = { main };

package/bin/commands/install.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const prompts = require('prompts');
+const { bold, green, cyan, red } = require('kleur');
+
+async function main({ cwd = process.cwd(), pkgRoot = path.join(__dirname, '..', '..') } = {}) {
+  console.log(bold().cyan('\n🚀 Welcome to Yodogawa Skills Installer!\n'));
+
+  const response = await prompts({
+    type: 'select',
+    name: 'type',
+    message: 'Which configuration would you like to install?',
+    choices: [
+      { title: 'Claude Code (.claude/skills/)', value: 'claude' },
+      { title: 'Other IDEs — Cursor / Codex / Antigravity (.agents/skills/)', value: 'agents' }
+    ]
+  });
+
+  if (!response.type) {
+    console.log(red('✖ Operation cancelled.'));
+    return;
+  }
+
+  const dirMap = {
+    claude: '.claude',
+    agents: '.agents',
+  };
+  const targetDirName = dirMap[response.type];
+  const targetDir = path.join(cwd, targetDirName);
+
+  if (fs.existsSync(targetDir)) {
+    const confirm = await prompts({
+      type: 'confirm',
+      name: 'overwrite',
+      message: `Directory ${targetDirName} already exists. Merge and update its contents?`,
+      initial: false
+    });
+    if (!confirm.overwrite) {
+      console.log(red('✖ Operation cancelled.'));
+      return;
+    }
+  }
+
+  console.log(`\nInstalling Yodogawa skills to ${bold(targetDirName)}...`);
+
+  await fs.copy(path.join(pkgRoot, 'skills'), path.join(targetDir, 'skills'));
+  await fs.copy(path.join(pkgRoot, 'templates'), path.join(targetDir, 'templates'));
+
+  console.log(green(`\n✔ Successfully installed Yodogawa skills for ${response.type}!`));
+  console.log(`\nNext steps:`);
+  console.log(`1. Open ${bold(targetDirName + '/skills/')} to explore the skills.`);
+  console.log(`2. Start using them in your project!\n`);
+  console.log(`Note: reinstalling merges into existing files. Renamed or removed skills are not auto-deleted — delete ${bold(targetDirName + '/skills')} and ${bold(targetDirName + '/templates')} first to reflect them.\n`);
+}
+
+module.exports = { main };

package/bin/commands/new-task.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const { bold, green, red, yellow } = require('kleur');
+
+// b-001-create-task-directory の採番規則に準拠（SKILL.md 手順2）
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const TASK_DIR_RE = /^task(\d{6})-/;
+const MAX_ID = 999999;
+
+const USAGE = `Usage: yodogawa new-task <slug> [--dir <path>] [--json]
+
+docs/tasks/ に連番タスク ID 付きディレクトリを作成します（作成はディレクトリのみ。
+タスク定義書などのドキュメントは /b-002-create-task-definition 以降で作成します）。
+
+Arguments:
+  slug          タスク内容を表す英小文字・数字・ハイフンのスラッグ（3〜5 語推奨）
+
+Options:
+  --dir <path>  プロジェクトのルート（既定: カレントディレクトリ）
+  --json        機械可読な JSON を stdout に出力
+  --help        このヘルプを表示
+
+Exit codes: 0 = 成功 / 1 = 操作失敗 / 2 = 使い方の誤り`;
+
+function parseArgs(argv) {
+  const opts = { json: false, dir: null, slug: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') opts.json = true;
+    else if (arg === '--dir') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('-')) {
+        return { error: '--dir にはパスを指定してください' };
+      }
+      opts.dir = argv[++i];
+    } else if (arg === '--help' || arg === '-h') return { help: true };
+    else if (arg.startsWith('-')) return { error: `不明なオプション: ${arg}` };
+    else if (opts.slug === null) opts.slug = arg;
+    else return { error: `引数が多すぎます: ${arg}` };
+  }
+  return { opts };
+}
+
+async function main(argv, { cwd = process.cwd() } = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (parsed.error) {
+    console.error(red(`✖ ${parsed.error}`));
+    console.error(USAGE);
+    return 2;
+  }
+
+  const { slug, dir, json } = parsed.opts;
+  if (!slug) {
+    console.error(red('✖ スラッグを指定してください（例: yodogawa new-task user-profile-edit）'));
+    console.error(USAGE);
+    return 2;
+  }
+  if (!SLUG_RE.test(slug)) {
+    console.error(
+      red(`✖ スラッグ「${slug}」が不正です。英小文字・数字・ハイフンのみ（連続ハイフン禁止）で指定してください`)
+    );
+    return 2;
+  }
+
+  const rootDir = path.resolve(cwd, dir || '.');
+  if (!fs.existsSync(rootDir)) {
+    console.error(red(`✖ 指定されたディレクトリが存在しません: ${rootDir}`));
+    return 2;
+  }
+  const tasksDir = path.join(rootDir, 'docs', 'tasks');
+  if (!fs.existsSync(tasksDir)) {
+    console.error(
+      red('✖ docs/tasks がありません。/a-001-setup-doc-structure でドキュメント骨格を先に作成してください')
+    );
+    return 1;
+  }
+
+  // 3〜5 語推奨（範囲外は警告のみで続行 = b-001 SKILL.md に忠実）。
+  // --json の stdout を汚さないよう警告は stderr へ出す。
+  const wordCount = slug.split('-').length;
+  if (wordCount < 3 || wordCount > 5) {
+    console.error(yellow(`⚠ スラッグは 3〜5 語を推奨します（現在 ${wordCount} 語）。このまま続行します`));
+  }
+
+  const ids = fs
+    .readdirSync(tasksDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => TASK_DIR_RE.exec(entry.name))
+    .filter(Boolean)
+    .map((m) => parseInt(m[1], 10));
+  const nextId = ids.length > 0 ? Math.max(...ids) + 1 : 1;
+  if (nextId > MAX_ID) {
+    console.error(red(`✖ タスク ID が上限（${MAX_ID}）を超えました`));
+    return 1;
+  }
+
+  const id = `task${String(nextId).padStart(6, '0')}`;
+  const dirName = `${id}-${slug}`;
+  await fs.ensureDir(path.join(tasksDir, dirName));
+  const relPath = `docs/tasks/${dirName}`;
+
+  if (json) {
+    console.log(JSON.stringify({ id, slug, path: relPath }, null, 2));
+  } else {
+    console.log(green(`✔ タスクディレクトリ ${bold(relPath)} を作成しました`));
+    console.log('続いてタスク定義書を作成しますか？（/b-002-create-task-definition）');
+  }
+  return 0;
+}
+
+module.exports = { main };

package/bin/lib/check-cli.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const path = require('path');
+
+const { summarize, formatPosition } = require('./findings');
+
+// 各チェックを単体スクリプトとして実行するための共通シム。
+// findings を 1 行 1 件で表示し、Error があれば exit 1、なければ exit 0。
+function runCheckCli(run, dirArg) {
+  const rootDir = path.resolve(dirArg || '.');
+  const findings = run({ rootDir });
+  for (const f of findings) {
+    console.log(`${f.severity} ${formatPosition(f)} ${f.message}`);
+  }
+  const { errors } = summarize(findings);
+  process.exitCode = errors > 0 ? 1 : 0;
+}
+
+module.exports = { runCheckCli };

package/bin/lib/findings.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const path = require('path');
+
+const SEVERITY = { ERROR: 'error', WARNING: 'warning' };
+
+function makeFinding(check, severity, file, line, message) {
+  return { check, severity, file, line: line == null ? null : line, message };
+}
+
+function summarize(findings) {
+  let errors = 0;
+  let warnings = 0;
+  for (const f of findings) {
+    if (f.severity === SEVERITY.ERROR) errors++;
+    else if (f.severity === SEVERITY.WARNING) warnings++;
+  }
+  return { errors, warnings };
+}
+
+// findings の file を OS 非依存で安定させるための正規化（Windows でも posix 区切り）
+function toPosixRelative(baseDir, absPath) {
+  return path.relative(baseDir, absPath).split(path.sep).join('/');
+}
+
+// finding の位置表示（file または file:line）
+function formatPosition(finding) {
+  return finding.line == null ? finding.file : `${finding.file}:${finding.line}`;
+}
+
+module.exports = { SEVERITY, makeFinding, summarize, toPosixRelative, formatPosition };

package/bin/lib/markdown.js

@@ -0,0 +1,103 @@
+'use strict';
+
+// Markdown を「論理行」のモデルに変換する共通前処理。
+// 全チェックはこのモデル経由で走査することで、フェンスコードブロック内・
+// HTML コメント内のテキストを誤検知しないことを一箇所で保証する。
+
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+const LINK_RE = /!?\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+// ATX 見出し。m[1] = レベル（# の数）、m[2] = 見出しテキスト
+const HEADING_RE = /^ {0,3}(#{1,6})\s+(.+)$/;
+
+// content → [{ raw, visible, line, inFence }]
+// - line: 1 始まり
+// - inFence: フェンス区切り行自身を含む
+// - visible: HTML コメント区間を除去したテキスト（フェンス内は raw のまま）
+function parseLines(content) {
+  const rawLines = String(content).split(/\r?\n/);
+  const lines = [];
+  let inFence = false;
+  let fenceChar = null;
+  let inComment = false;
+
+  for (let i = 0; i < rawLines.length; i++) {
+    const raw = rawLines[i];
+    let lineInFence = inFence;
+
+    if (!inComment) {
+      const fenceMatch = raw.match(FENCE_RE);
+      if (fenceMatch) {
+        if (!inFence) {
+          inFence = true;
+          fenceChar = fenceMatch[1][0];
+          lineInFence = true;
+        } else if (fenceMatch[1][0] === fenceChar) {
+          inFence = false;
+          lineInFence = true;
+        }
+      }
+    }
+
+    let visible;
+    if (lineInFence) {
+      visible = raw;
+    } else {
+      const stripped = stripComments(raw, inComment);
+      visible = stripped.visible;
+      inComment = stripped.inComment;
+    }
+    lines.push({ raw, visible, line: i + 1, inFence: lineInFence });
+  }
+  return lines;
+}
+
+function stripComments(text, inComment) {
+  let out = '';
+  let rest = text;
+  while (rest.length > 0) {
+    if (inComment) {
+      const end = rest.indexOf('-->');
+      if (end === -1) {
+        rest = '';
+      } else {
+        rest = rest.slice(end + 3);
+        inComment = false;
+      }
+    } else {
+      const start = rest.indexOf('<!--');
+      if (start === -1) {
+        out += rest;
+        rest = '';
+      } else {
+        out += rest.slice(0, start);
+        rest = rest.slice(start + 4);
+        inComment = true;
+      }
+    }
+  }
+  return { visible: out, inComment };
+}
+
+// content → [{ target, line }]（フェンス内・コメント内のリンクは除外）
+function extractLinks(content) {
+  const links = [];
+  for (const line of parseLines(content)) {
+    if (line.inFence) continue;
+    LINK_RE.lastIndex = 0;
+    let m;
+    while ((m = LINK_RE.exec(line.visible)) !== null) {
+      links.push({ target: m[1], line: line.line });
+    }
+  }
+  return links;
+}
+
+// テーブル行なら trim 済みセル配列、そうでなければ null
+function splitTableCells(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith('|')) return null;
+  const inner = trimmed.replace(/^\|/, '').replace(/\|$/, '');
+  return inner.split('|').map((cell) => cell.trim());
+}
+
+module.exports = { parseLines, extractLinks, splitTableCells, HEADING_RE };

package/bin/lib/project-spec.js

@@ -0,0 +1,138 @@
+'use strict';
+
+// docs/project の正準構造の定義データ（Single Source of Truth）。
+// 根拠は templates/project/ の実テンプレート。テンプレートの見出しを変更したら
+// ここも合わせて更新すること。
+
+// A-Series の作成順（フェーズ順）。structure チェックはこの順序で
+// 「自分より後のファイルが存在するのに欠けているファイル」を Error にする
+// （フェーズ・フロンティア方式。未着手フェーズのファイルは報告しない）。
+const CANONICAL_FILES = [
+  '01-requirements/01-product-brief.md',
+  '01-requirements/02-mvp-scope.md',
+  '01-requirements/03-parking-lot.md',
+  '01-requirements/05-user-stories.md',
+  '02-behavior/01-core-scenarios.md',
+  '03-domain/01-domain-sketch.md',
+  '03-domain/02-ubiquitous-language.md',
+  '04-design/01-tech-stack.md',
+  '04-design/02-repository-structure.md',
+  '04-design/03-screen-design.md',
+  '04-design/04-design-system.md',
+  '04-design/05-data-model.md',
+  '04-design/06-api-spec.md',
+  '04-design/07-architecture.md',
+  '04-design/08-infrastructure.md',
+];
+
+// 常に任意のファイル（06 は existing モードのみ、01-domain-model は Full DDD のみ）
+const OPTIONAL_FILES = [
+  '01-requirements/06-features-implemented.md',
+  '03-domain/01-domain-model.md',
+];
+
+// 「このキーで始まる見出し」が存在すること（前方一致。ユーザーが括弧の補足を
+// 削っても壊れないよう、安定した骨格キーのみを要求する）。
+const REQUIRED_HEADINGS = {
+  '01-requirements/01-product-brief.md': [
+    '背景',
+    'ターゲットユーザー',
+    '価値提案',
+    '成功指標',
+    'クリティカル制約',
+    '非ゴール',
+  ],
+  '01-requirements/02-mvp-scope.md': ['検証する仮説', 'MVP Scope', 'Out of Scope'],
+  '02-behavior/01-core-scenarios.md': [
+    'Core Flow 一覧',
+    'Day 1 Happy Path',
+    'Critical Failure',
+    'Not Covered in MVP',
+  ],
+  '03-domain/01-domain-sketch.md': [
+    '主要用語',
+    'アクター',
+    '中核エンティティ',
+    '重要なビジネスルール',
+    'MVP では作らない',
+  ],
+  '03-domain/02-ubiquitous-language.md': ['禁止用語'],
+  '04-design/01-tech-stack.md': ['テックスタック一覧', '技術選定の基準'],
+  '04-design/02-repository-structure.md': ['ディレクトリ構造', 'アーキテクチャパターン'],
+  '04-design/03-screen-design.md': ['画面一覧', '画面遷移図'],
+  '04-design/04-design-system.md': ['カラーパレット', 'タイポグラフィ'],
+  '04-design/05-data-model.md': ['エンティティ一覧', 'リレーションシップ'],
+  '04-design/06-api-spec.md': ['認証・認可', 'エンドポイント一覧'],
+  '04-design/07-architecture.md': ['システムアーキテクチャ図', 'ADR'],
+  '04-design/08-infrastructure.md': ['インフラ構成図', '環境構成'],
+};
+
+// 見出しが乏しいファイルは代表テーブルのヘッダセルで骨格を検査する。
+const REQUIRED_TABLE_HEADERS = {
+  '01-requirements/03-parking-lot.md': 'Category 1',
+  '01-requirements/05-user-stories.md': 'ストーリーID',
+};
+
+// a-006（PM Gate）が docs/project/ 直下に生成するレビュー成果物。
+// 04-design に着手しているのに無い場合は a-006 未実施の示唆として Warning。
+const REVIEW_ARTIFACTS = ['AI_CONTEXT.md', 'STAKEHOLDER-SUMMARY.md'];
+
+// templates/project/ 由来の意味プレースホルダ（placeholder チェックが検出）。
+// コメント外に残っていたらテンプレート未記入とみなす。汎用の \[.+\] は
+// チェックボックスや Markdown リンクと衝突するため、既知トークンのみ検出する。
+// テンプレートとの同期は test/project-spec-sync.test.js が検証する。
+const KNOWN_TOKENS = [
+  '[役割]',
+  '[目的]',
+  '[理由]',
+  '[課題]',
+  '[画面名]',
+  '[コンテキスト名]',
+  '[Bounded Context名]',
+];
+
+// ID 体系（trace の SSoT）。definitionFiles 内の出現を定義とみなす
+// （headingDefinition の族は見出し行の出現のみが定義）。
+// orphanScanFiles: 定義済み ID がここから 1 度も参照されなければ孤児 Warning。
+// degradeWhenNoDefinitions: 定義集合が空のとき参照ごとの Error ではなく
+// 族全体で縮退 Warning 1 件にする（FN は定義元が任意ファイルのため）。
+const ID_FAMILIES = [
+  {
+    family: 'P',
+    definitionFiles: ['01-requirements/01-product-brief.md'],
+    orphanScanFiles: ['01-requirements/05-user-stories.md'],
+  },
+  {
+    family: 'US',
+    definitionFiles: ['01-requirements/05-user-stories.md'],
+  },
+  {
+    family: 'FN',
+    definitionFiles: [
+      '01-requirements/02-mvp-scope.md',
+      '01-requirements/06-features-implemented.md',
+    ],
+    orphanScanFiles: ['02-behavior/01-core-scenarios.md'],
+    degradeWhenNoDefinitions: true,
+  },
+  {
+    family: 'CS',
+    definitionFiles: ['02-behavior/01-core-scenarios.md'],
+    headingDefinition: true,
+  },
+  {
+    family: 'CF',
+    definitionFiles: ['02-behavior/01-core-scenarios.md'],
+    headingDefinition: true,
+  },
+];
+
+module.exports = {
+  CANONICAL_FILES,
+  OPTIONAL_FILES,
+  REQUIRED_HEADINGS,
+  REQUIRED_TABLE_HEADERS,
+  REVIEW_ARTIFACTS,
+  KNOWN_TOKENS,
+  ID_FAMILIES,
+};

package/bin/lib/walk-md.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// dir 配下の .md ファイルを再帰列挙する（絶対パス、名前順で決定的）。
+// Node 18 互換のため readdirSync の recursive オプションは使わない。
+function walkMdFiles(dir) {
+  const out = [];
+  (function walk(current) {
+    const entries = fs
+      .readdirSync(current, { withFileTypes: true })
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+    }
+  })(dir);
+  return out;
+}
+
+module.exports = { walkMdFiles };