yodogawa 2.1.3 → 2.2.0

package/bin/checks/id-trace.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { parseLines, HEADING_RE } = require('../lib/markdown');
+const { SEVERITY, makeFinding, toPosixRelative } = require('../lib/findings');
+const { walkMdFiles } = require('../lib/walk-md');
+const { ID_FAMILIES } = require('../lib/project-spec');
+
+const CHECK = 'id-trace';
+// 族の列挙は ID_FAMILIES（SSoT）から導出する。前後が英数字・ハイフンに連続する
+// 出現（パス断片・複合語 CS-001-detail・P-00X のような部分一致）を除外する
+const ID_RE = new RegExp(
+  `(?<![0-9A-Za-z-])(${ID_FAMILIES.map((f) => f.family).join('|')})-(\\d+)(?![0-9A-Za-z-])`,
+  'g'
+);
+
+const ORPHAN_MESSAGES = {
+  P: (id) => `「${id}」はどのユーザーストーリーからも参照されていません（孤児ペルソナの可能性）`,
+  FN: (id) => `「${id}」は core-scenarios から参照されていません（シナリオ未カバーの可能性）`,
+};
+
+function collectOccurrences(projectDir) {
+  const occurrences = [];
+  for (const abs of walkMdFiles(projectDir)) {
+    const relFromProject = toPosixRelative(projectDir, abs);
+    for (const line of parseLines(fs.readFileSync(abs, 'utf8'))) {
+      if (line.inFence) continue;
+      const isHeading = HEADING_RE.test(line.visible);
+      ID_RE.lastIndex = 0;
+      let m;
+      while ((m = ID_RE.exec(line.visible)) !== null) {
+        occurrences.push({
+          family: m[1],
+          id: `${m[1]}-${m[2]}`,
+          relFile: relFromProject,
+          line: line.line,
+          isHeading,
+        });
+      }
+    }
+  }
+  return occurrences;
+}
+
+function run({ rootDir }) {
+  const projectDir = path.join(rootDir, 'docs', 'project');
+  if (!fs.existsSync(projectDir)) return [];
+
+  const findings = [];
+  const occurrences = collectOccurrences(projectDir);
+  const toFile = (relFromProject) => `docs/project/${relFromProject}`;
+
+  for (const fam of ID_FAMILIES) {
+    const famOccurrences = occurrences.filter((o) => o.family === fam.family);
+    if (famOccurrences.length === 0) continue;
+
+    const isDefinition = (o) =>
+      fam.definitionFiles.includes(o.relFile) && (!fam.headingDefinition || o.isHeading);
+
+    const definitions = new Map();
+    for (const o of famOccurrences) {
+      if (isDefinition(o) && !definitions.has(o.id)) definitions.set(o.id, o);
+    }
+    const references = famOccurrences.filter((o) => !isDefinition(o));
+
+    if (definitions.size === 0) {
+      if (fam.degradeWhenNoDefinitions) {
+        if (references.length > 0) {
+          const first = references[0];
+          findings.push(
+            makeFinding(
+              CHECK,
+              SEVERITY.WARNING,
+              toFile(first.relFile),
+              first.line,
+              `${fam.family} の定義元（${fam.definitionFiles.join(' / ')}）で ${fam.family} ID が定義されていないため、${fam.family} の trace 検査をスキップしました`
+            )
+          );
+        }
+        continue;
+      }
+      const anyDefinitionFileExists = fam.definitionFiles.some((rel) =>
+        fs.existsSync(path.join(projectDir, ...rel.split('/')))
+      );
+      if (!anyDefinitionFileExists) continue; // 定義ファイル自体が無い族は skip（structure が別途検出）
+    }
+
+    const reported = new Set();
+    for (const ref of references) {
+      if (definitions.has(ref.id) || reported.has(ref.id)) continue;
+      reported.add(ref.id);
+      findings.push(
+        makeFinding(
+          CHECK,
+          SEVERITY.ERROR,
+          toFile(ref.relFile),
+          ref.line,
+          `「${ref.id}」が ${fam.definitionFiles.join(' / ')} で定義されていません（trace 切れ）`
+        )
+      );
+    }
+
+    if (fam.orphanScanFiles) {
+      const scanFileExists = fam.orphanScanFiles.some((rel) =>
+        fs.existsSync(path.join(projectDir, ...rel.split('/')))
+      );
+      if (scanFileExists) {
+        const referencedInScan = new Set(
+          references.filter((o) => fam.orphanScanFiles.includes(o.relFile)).map((o) => o.id)
+        );
+        for (const [id, def] of definitions) {
+          if (!referencedInScan.has(id)) {
+            findings.push(
+              makeFinding(
+                CHECK,
+                SEVERITY.WARNING,
+                toFile(def.relFile),
+                def.line,
+                ORPHAN_MESSAGES[fam.family](id)
+              )
+            );
+          }
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  require('../lib/check-cli').runCheckCli(run, process.argv[2]);
+}

package/bin/checks/links.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { extractLinks } = require('../lib/markdown');
+const { SEVERITY, makeFinding, toPosixRelative } = require('../lib/findings');
+const { walkMdFiles } = require('../lib/walk-md');
+
+const CHECK = 'links';
+// URI スキーム付き（http/mailto/tel/data 等すべて）・アンカーのみ・絶対パスは
+// 相対リンク検査の対象外（ネットワークアクセスはしない＝決定性）
+const SKIP_TARGET_RE = /^([a-z][a-z0-9+.-]*:|#|\/)/i;
+
+// dir 配下の Markdown の相対リンク切れを findings として返す。
+// リポジトリ側（scripts/repo-check.mjs）から skills/・templates/ にも
+// 再利用できるよう、走査ロジックを分離している。
+function collectBrokenLinks(baseDir, filePrefix) {
+  const findings = [];
+  if (!fs.existsSync(baseDir)) return findings;
+
+  for (const abs of walkMdFiles(baseDir)) {
+    const file = `${filePrefix}${toPosixRelative(baseDir, abs)}`;
+    for (const link of extractLinks(fs.readFileSync(abs, 'utf8'))) {
+      if (SKIP_TARGET_RE.test(link.target)) continue;
+      const cleaned = link.target.split('#')[0].split('?')[0];
+      if (cleaned === '') continue;
+      let decoded;
+      try {
+        decoded = decodeURIComponent(cleaned);
+      } catch {
+        decoded = cleaned;
+      }
+      const resolved = path.resolve(path.dirname(abs), decoded);
+      if (!fs.existsSync(resolved)) {
+        findings.push(
+          makeFinding(
+            CHECK,
+            SEVERITY.ERROR,
+            file,
+            link.line,
+            `リンク先「${link.target}」が存在しません`
+          )
+        );
+      }
+    }
+  }
+  return findings;
+}
+
+function run({ rootDir }) {
+  return collectBrokenLinks(path.join(rootDir, 'docs'), 'docs/');
+}
+
+module.exports = { run, collectBrokenLinks };
+
+if (require.main === module) {
+  require('../lib/check-cli').runCheckCli(run, process.argv[2]);
+}

package/bin/checks/placeholder.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { parseLines, splitTableCells, HEADING_RE } = require('../lib/markdown');
+const { SEVERITY, makeFinding, toPosixRelative } = require('../lib/findings');
+const { walkMdFiles } = require('../lib/walk-md');
+const { KNOWN_TOKENS } = require('../lib/project-spec');
+
+const CHECK = 'placeholder';
+const COMMENT_ONLY_CELL_RE = /^<!--[\s\S]*-->$/;
+const HR_RE = /^(-{3,}|\*{3,}|_{3,})$/;
+
+// 行内にトークンが「リンク [token](...) 以外の形で」1 回でも出現するか
+function hasRawToken(text, token) {
+  let idx = text.indexOf(token);
+  while (idx !== -1) {
+    if (text[idx + token.length] !== '(') return true;
+    idx = text.indexOf(token, idx + 1);
+  }
+  return false;
+}
+
+// 空でも正常なセクション（テンプレート上、空欄がありうるもの）
+function isExemptHeading(text) {
+  return (
+    text.includes('（任意）') ||
+    text.includes('(任意)') ||
+    text.startsWith('メモ') ||
+    text.startsWith('Not Covered in MVP')
+  );
+}
+
+function checkFile(absPath, file, findings) {
+  const lines = parseLines(fs.readFileSync(absPath, 'utf8'));
+
+  for (const line of lines) {
+    if (line.inFence) continue;
+
+    // 1. コメントのみのテーブルセル（テンプレート行がそのまま残っている）
+    if (line.visible.includes('|')) {
+      const rawCells = splitTableCells(line.raw);
+      if (rawCells && rawCells.some((cell) => COMMENT_ONLY_CELL_RE.test(cell))) {
+        findings.push(
+          makeFinding(
+            CHECK,
+            SEVERITY.WARNING,
+            file,
+            line.line,
+            'テーブルに未記入のテンプレートセル（<!-- ... -->）が残っています'
+          )
+        );
+        continue;
+      }
+    }
+
+    // 2. 既知の角括弧プレースホルダ（リンク [text](...) は除外）
+    const tokens = KNOWN_TOKENS.filter((token) => hasRawToken(line.visible, token));
+    if (tokens.length > 0) {
+      findings.push(
+        makeFinding(
+          CHECK,
+          SEVERITY.WARNING,
+          file,
+          line.line,
+          `テンプレートのプレースホルダ ${tokens.join(' ')} が残っています`
+        )
+      );
+    }
+
+    // 3. **例:** マーカーの残置（例示ブロックが削除されていない）
+    if (line.visible.trim() === '**例:**') {
+      findings.push(
+        makeFinding(
+          CHECK,
+          SEVERITY.WARNING,
+          file,
+          line.line,
+          'テンプレートの例示ブロック（**例:**）が残っています'
+        )
+      );
+    }
+  }
+
+  // 4. 空セクション（##/### の本文にコメント・空行・罫線以外が無い）
+  const headings = [];
+  lines.forEach((line, idx) => {
+    if (line.inFence) return;
+    const m = line.visible.match(HEADING_RE);
+    if (m) headings.push({ level: m[1].length, text: m[2].trim(), line: line.line, idx });
+  });
+  headings.forEach((heading, hi) => {
+    if (heading.level < 2 || heading.level > 3) return;
+    if (isExemptHeading(heading.text)) return;
+    const next = headings.slice(hi + 1).find((h) => h.level <= heading.level);
+    const endIdx = next ? next.idx : lines.length;
+    const hasContent = lines.slice(heading.idx + 1, endIdx).some((line) => {
+      if (line.inFence) return true; // コードブロックは本文とみなす
+      const text = line.visible.trim();
+      return text !== '' && !HR_RE.test(text) && !HEADING_RE.test(line.visible);
+    });
+    if (!hasContent) {
+      findings.push(
+        makeFinding(
+          CHECK,
+          SEVERITY.WARNING,
+          file,
+          heading.line,
+          `セクション「${heading.text}」が未記入です`
+        )
+      );
+    }
+  });
+}
+
+function run({ rootDir }) {
+  const projectDir = path.join(rootDir, 'docs', 'project');
+  if (!fs.existsSync(projectDir)) return [];
+
+  const findings = [];
+  for (const abs of walkMdFiles(projectDir)) {
+    checkFile(abs, `docs/project/${toPosixRelative(projectDir, abs)}`, findings);
+  }
+  return findings;
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  require('../lib/check-cli').runCheckCli(run, process.argv[2]);
+}

package/bin/checks/structure.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { parseLines, splitTableCells, HEADING_RE } = require('../lib/markdown');
+const { SEVERITY, makeFinding } = require('../lib/findings');
+const spec = require('../lib/project-spec');
+
+const CHECK = 'structure';
+
+function run({ rootDir }) {
+  const projectDir = path.join(rootDir, 'docs', 'project');
+  if (!fs.existsSync(projectDir)) {
+    return [
+      makeFinding(
+        CHECK,
+        SEVERITY.ERROR,
+        'docs/project',
+        null,
+        'docs/project が存在しません。/a-001-setup-doc-structure でドキュメント骨格を作成してください'
+      ),
+    ];
+  }
+
+  const findings = [];
+  const existing = spec.CANONICAL_FILES.map((rel) =>
+    fs.existsSync(path.join(projectDir, ...rel.split('/')))
+  );
+  const frontier = existing.lastIndexOf(true);
+
+  // 骨格だけあって正準ドキュメントがゼロの状態を「健全」と誤報しない
+  if (frontier === -1) {
+    return [
+      makeFinding(
+        CHECK,
+        SEVERITY.WARNING,
+        'docs/project',
+        null,
+        'docs/project に正準ドキュメントが 1 つもありません（/a-002-initialize-project から要件定義を開始してください）'
+      ),
+    ];
+  }
+
+  for (let i = 0; i < frontier; i++) {
+    if (!existing[i]) {
+      findings.push(
+        makeFinding(
+          CHECK,
+          SEVERITY.ERROR,
+          `docs/project/${spec.CANONICAL_FILES[i]}`,
+          null,
+          '必須ファイルがありません（後続フェーズのドキュメントは既に存在します）'
+        )
+      );
+    }
+  }
+
+  spec.CANONICAL_FILES.forEach((rel, i) => {
+    if (!existing[i]) return;
+    const file = `docs/project/${rel}`;
+    const lines = parseLines(
+      fs.readFileSync(path.join(projectDir, ...rel.split('/')), 'utf8')
+    );
+    const headings = [];
+    let hasRequiredTableHeader = false;
+    const requiredHeader = spec.REQUIRED_TABLE_HEADERS[rel];
+
+    for (const line of lines) {
+      if (line.inFence) continue;
+      const m = line.visible.match(HEADING_RE);
+      // H1 はドキュメントタイトルなので必須見出しの充足に数えない
+      // （例: 02-mvp-scope.md の「# MVP Scope」がキー「MVP Scope」を偽充足しないように）
+      if (m && m[1].length >= 2) headings.push(m[2].trim());
+      if (requiredHeader && !hasRequiredTableHeader) {
+        const cells = splitTableCells(line.visible);
+        if (cells && cells.includes(requiredHeader)) hasRequiredTableHeader = true;
+      }
+    }
+
+    for (const key of spec.REQUIRED_HEADINGS[rel] || []) {
+      if (!headings.some((h) => h.startsWith(key))) {
+        findings.push(
+          makeFinding(CHECK, SEVERITY.ERROR, file, null, `必須見出し「${key}」が見つかりません`)
+        );
+      }
+    }
+    if (requiredHeader && !hasRequiredTableHeader) {
+      findings.push(
+        makeFinding(
+          CHECK,
+          SEVERITY.ERROR,
+          file,
+          null,
+          `必須テーブルヘッダ「${requiredHeader}」を含む表が見つかりません`
+        )
+      );
+    }
+  });
+
+  const designStarted = spec.CANONICAL_FILES.some(
+    (rel, i) => existing[i] && rel.startsWith('04-design/')
+  );
+  if (designStarted) {
+    for (const artifact of spec.REVIEW_ARTIFACTS) {
+      if (!fs.existsSync(path.join(projectDir, artifact))) {
+        findings.push(
+          makeFinding(
+            CHECK,
+            SEVERITY.WARNING,
+            `docs/project/${artifact}`,
+            null,
+            `設計フェーズに着手していますが ${artifact} がありません（/a-006-review-requirements-domain 未実施の可能性）`
+          )
+        );
+      }
+    }
+  }
+
+  return findings;
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  require('../lib/check-cli').runCheckCli(run, process.argv[2]);
+}

package/bin/cli.js

@@ -1,67 +1,51 @@
-#!/usr/bin/env node
-
-const fs = require('fs-extra');
-const path = require('path');
-const prompts = require('prompts');
-const { bold, green, cyan, red } = require('kleur');
-
-async function main() {
-  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.'));
-    process.exit(0);
-  }
-
-  const pkgRoot = path.join(__dirname, '..');
-  const dirMap = {
-    claude: '.claude',
-    agents: '.agents',
-  };
-  const targetDirName = dirMap[response.type];
-  const targetDir = path.join(process.cwd(), targetDirName);
-
-  try {
-    if (fs.existsSync(targetDir)) {
-      const confirm = await prompts({
-        type: 'confirm',
-        name: 'overwrite',
-        message: `Directory ${targetDirName} already exists. Overwrite?`,
-        initial: false
-      });
-      if (!confirm.overwrite) {
-        console.log(red('✖ Operation cancelled.'));
-        process.exit(0);
-      }
-    }
-
-    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`);
-
-  } catch (err) {
-    console.error(red(`\n✖ Error installing skills: ${err.message}`));
-    process.exit(1);
-  }
-}
-
-main().catch(err => {
-  console.error(red(err));
-  process.exit(1);
-});
+#!/usr/bin/env node
+'use strict';
+
+const { red } = require('kleur');
+const install = require('./commands/install');
+
+const HELP = `Usage: yodogawa [command] [options]
+
+Commands:
+  (なし)             対話形式でスキル・テンプレートをインストール
+  doctor             docs/project/ のトレーサビリティ・構造を検査
+  new-task <slug>    docs/tasks/ に連番タスクディレクトリを作成
+  help               このヘルプを表示
+
+各コマンドの詳細は yodogawa <command> --help を参照してください。`;
+
+function printHelp() {
+  console.log(HELP);
+}
+
+async function run(argv = process.argv.slice(2), { cwd = process.cwd() } = {}) {
+  const [command, ...rest] = argv;
+  if (command === undefined) {
+    // 後方互換: 引数なしは従来どおり対話インストール
+    await install.main({ cwd });
+    return 0;
+  }
+  if (command === 'doctor') return require('./commands/doctor').main(rest, { cwd });
+  if (command === 'new-task') return require('./commands/new-task').main(rest, { cwd });
+  if (command === '--help' || command === '-h' || command === 'help') {
+    printHelp();
+    return 0;
+  }
+  console.error(red(`✖ Unknown command: ${command}`));
+  console.error(HELP);
+  return 2;
+}
+
+// main は install の別名（既存利用箇所の後方互換のため維持）
+module.exports = { main: install.main, run };
+
+if (require.main === module) {
+  run()
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((err) => {
+      console.error(red(`\n✖ Error: ${err.message}`));
+      process.exitCode = 1;
+    });
+}