phasegate 0.15.0

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-inception-plan-gateway.ts

@@ -0,0 +1,86 @@
+/**
+ * @layer infrastructure
+ * @unit traceability-model
+ *
+ * docs/inception/{unit}/{storyId}/ の存在確認で InceptionPlanPort を実装するゲートウェイ
+ */
+import { readdir } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { InceptionPlanPort } from '../../domain/ports/inception-plan-port.js';
+import type { ProjectRelativePathLike } from '../../domain/value-objects/chain-link.js';
+import type { StoryIdLike } from '../../domain/value-objects/story-reference.js';
+import { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+
+const PLAN_FILE_PATTERN = /_plan\.md$/;
+
+export interface FileSystemInceptionPlanGatewayDeps {
+  readonly rootDir: string;
+}
+
+export class FileSystemInceptionPlanGateway implements InceptionPlanPort {
+  private readonly rootDir: string;
+
+  constructor(deps: FileSystemInceptionPlanGatewayDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async exists(unitName: string, storyId: StoryIdLike): Promise<boolean> {
+    const planRoot = await this.findPlanRoot(unitName, storyId);
+    return planRoot !== null;
+  }
+
+  async findPlanRoot(
+    unitName: string,
+    storyId: StoryIdLike,
+  ): Promise<ProjectRelativePathLike | null> {
+    const relativePath = `docs/inception/${unitName}/${storyId.value}`;
+    const absolutePath = path.join(this.rootDir, relativePath);
+
+    if (!fs.existsSync(absolutePath)) {
+      return null;
+    }
+
+    const statResult = fs.statSync(absolutePath);
+    if (!statResult.isDirectory()) {
+      return null;
+    }
+
+    // 最低1つの *_plan.md が存在することを確認する
+    try {
+      const entries = await readdir(absolutePath);
+      const hasPlanFile = entries.some((entry) => PLAN_FILE_PATTERN.test(entry));
+      if (!hasPlanFile) {
+        return null;
+      }
+    } catch {
+      return null;
+    }
+
+    return ProjectRelativePath.create(relativePath);
+  }
+
+  async findPlanByStoryId(
+    storyId: StoryIdLike,
+  ): Promise<ProjectRelativePathLike | null> {
+    const inceptionDir = path.join(this.rootDir, 'docs', 'inception');
+
+    if (!fs.existsSync(inceptionDir)) {
+      return null;
+    }
+
+    try {
+      const unitDirs = await readdir(inceptionDir);
+      for (const unitDir of unitDirs) {
+        const result = await this.findPlanRoot(unitDir, storyId);
+        if (result !== null) {
+          return result;
+        }
+      }
+    } catch {
+      return null;
+    }
+
+    return null;
+  }
+}

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-metadata-reader.ts

@@ -0,0 +1,101 @@
+/**
+ * @layer infrastructure
+ * @unit traceability-model
+ *
+ * ファイルシステムからソースコードを読み込み MetadataReaderPort を実装するゲートウェイ
+ */
+import { readFile } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { MetadataReaderPort, MetadataTagLike } from '../../domain/ports/metadata-reader-port.js';
+import type { ProjectRelativePathLike } from '../../domain/value-objects/chain-link.js';
+import {
+  parseImplementationTags,
+  parseTestTags,
+} from '../parsers/source-metadata-parser.js';
+
+const SUPPORTED_EXTENSIONS = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.mts',
+  '.cts',
+]);
+
+export class MetadataReadInfrastructureError extends Error {
+  readonly originalError: Error | undefined;
+
+  constructor(filePath: string, cause?: unknown) {
+    super(`メタデータ読み取りに失敗しました: ${filePath}`);
+    this.name = 'MetadataReadInfrastructureError';
+    this.originalError = cause instanceof Error ? cause : undefined;
+  }
+}
+
+export interface FileSystemMetadataReaderDeps {
+  readonly rootDir: string;
+}
+
+export class FileSystemMetadataReader implements MetadataReaderPort {
+  private readonly rootDir: string;
+
+  constructor(deps: FileSystemMetadataReaderDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async readImplementationTags(
+    filePath: ProjectRelativePathLike,
+  ): Promise<readonly MetadataTagLike[]> {
+    const content = await this.readFileContent(filePath);
+    const parsed = parseImplementationTags(content);
+
+    return parsed.map((tag) => ({
+      type: tag.type,
+      value: tag.value,
+      lineNumber: tag.lineNumber,
+      filePath,
+    }));
+  }
+
+  async readTestTags(
+    filePath: ProjectRelativePathLike,
+  ): Promise<readonly MetadataTagLike[]> {
+    const content = await this.readFileContent(filePath);
+    const parsed = parseTestTags(content);
+
+    return parsed.map((tag) => ({
+      type: tag.type,
+      value: tag.value,
+      lineNumber: tag.lineNumber,
+      filePath,
+    }));
+  }
+
+  private async readFileContent(
+    filePath: ProjectRelativePathLike,
+  ): Promise<string> {
+    const absolutePath = path.join(this.rootDir, filePath.value);
+    const ext = path.extname(absolutePath);
+
+    if (!SUPPORTED_EXTENSIONS.has(ext)) {
+      throw new MetadataReadInfrastructureError(
+        filePath.value,
+        new Error(`サポートされていない拡張子です: ${ext}`),
+      );
+    }
+
+    if (!fs.existsSync(absolutePath)) {
+      throw new MetadataReadInfrastructureError(
+        filePath.value,
+        new Error(`ファイルが存在しません: ${absolutePath}`),
+      );
+    }
+
+    try {
+      return await readFile(absolutePath, 'utf8');
+    } catch (err) {
+      throw new MetadataReadInfrastructureError(filePath.value, err);
+    }
+  }
+}

package/scripts/harness/traceability-model/infrastructure/gateways/markdown-design-document-gateway.ts

@@ -0,0 +1,122 @@
+/**
+ * @layer infrastructure
+ * @unit traceability-model
+ *
+ * docs/product/construction/{unit}/ 配下の設計文書を読み込み DesignDocumentPort を実装するゲートウェイ
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { DesignDocumentPort } from '../../domain/ports/design-document-port.js';
+import type { ProjectRelativePathLike } from '../../domain/value-objects/chain-link.js';
+import { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+import { StoryIdAnnotation } from '../../domain/value-objects/story-id-annotation.js';
+import { StoryId } from '../../domain/value-objects/story-id.js';
+import { DesignDocumentFlags } from '../../domain/value-objects/design-document-flags.js';
+import { parseStoryAnnotations } from '../parsers/markdown-story-annotation-parser.js';
+import { parseFrontmatterFlags } from '../parsers/frontmatter-flag-parser.js';
+
+export interface MarkdownDesignDocumentGatewayDeps {
+  readonly rootDir: string;
+}
+
+export class MarkdownDesignDocumentGateway implements DesignDocumentPort {
+  private readonly rootDir: string;
+  private readonly contentCache = new Map<string, string>();
+
+  constructor(deps: MarkdownDesignDocumentGatewayDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async listByUnit(
+    unitName: string,
+  ): Promise<readonly ProjectRelativePathLike[]> {
+    const constructionDir = path.join(
+      this.rootDir,
+      'docs',
+      'product',
+      'construction',
+      unitName,
+    );
+
+    if (!fs.existsSync(constructionDir)) {
+      return [];
+    }
+
+    const entries = await readdir(constructionDir);
+    const results: ProjectRelativePathLike[] = [];
+
+    for (const entry of entries) {
+      if (entry.endsWith('.md')) {
+        results.push(
+          ProjectRelativePath.create(
+            `docs/product/construction/${unitName}/${entry}`,
+          ),
+        );
+      }
+    }
+
+    return results;
+  }
+
+  async findConstructionDocuments(
+    unitName: string,
+  ): Promise<readonly ProjectRelativePathLike[]> {
+    return this.listByUnit(unitName);
+  }
+
+  async readStoryAnnotations(
+    filePath: ProjectRelativePathLike,
+  ): Promise<readonly StoryIdAnnotation[]> {
+    const content = await this.getContent(filePath);
+    const parsed = parseStoryAnnotations(content);
+
+    const annotations: StoryIdAnnotation[] = [];
+    for (let i = 0; i < parsed.length; i++) {
+      const p = parsed[i];
+      try {
+        const storyId = StoryId.parse(p.storyIdValue);
+        annotations.push(
+          StoryIdAnnotation.create({
+            storyId,
+            lineNumber: p.lineNumber,
+            contextLine: p.contextLine,
+            standaloneLine: p.standaloneLine,
+          }),
+        );
+      } catch {
+        // StoryId形式が不正な場合はスキップする
+      }
+    }
+
+    return annotations;
+  }
+
+  async readStoryIdAnnotations(
+    filePath: ProjectRelativePathLike,
+  ): Promise<readonly StoryIdAnnotation[]> {
+    return this.readStoryAnnotations(filePath);
+  }
+
+  async readFrontmatterFlags(
+    filePath: ProjectRelativePathLike,
+  ): Promise<DesignDocumentFlags> {
+    const content = await this.getContent(filePath);
+    const parsed = parseFrontmatterFlags(content);
+    return DesignDocumentFlags.create(parsed.initialCreation);
+  }
+
+  private async getContent(
+    filePath: ProjectRelativePathLike,
+  ): Promise<string> {
+    const cached = this.contentCache.get(filePath.value);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const absolutePath = path.join(this.rootDir, filePath.value);
+    const content = await readFile(absolutePath, 'utf8');
+    this.contentCache.set(filePath.value, content);
+    return content;
+  }
+}

package/scripts/harness/traceability-model/infrastructure/gateways/markdown-story-catalog-gateway.ts

@@ -0,0 +1,98 @@
+/**
+ * @layer infrastructure
+ * @unit traceability-model
+ *
+ * user_stories.md を読み込み StoryCatalogPort を実装するゲートウェイ
+ */
+import { readFile, stat } from 'node:fs/promises';
+import * as path from 'node:path';
+import type { StoryCatalogPort } from '../../domain/ports/story-catalog-port.js';
+import type { StoryIdLike } from '../../domain/value-objects/story-reference.js';
+import { StoryId } from '../../domain/value-objects/story-id.js';
+import { parseStoryCatalog } from '../parsers/story-catalog-parser.js';
+
+export interface MarkdownStoryCatalogGatewayDeps {
+  readonly rootDir: string;
+}
+
+export class MarkdownStoryCatalogGateway implements StoryCatalogPort {
+  private readonly rootDir: string;
+  private cachedStoryIds: readonly StoryIdLike[] | null = null;
+  private cachedAliasMap: ReadonlyMap<string, StoryIdLike> | null = null;
+  private cachedMtime: number | null = null;
+
+  constructor(deps: MarkdownStoryCatalogGatewayDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async getAllStoryIds(): Promise<readonly StoryIdLike[]> {
+    await this.ensureLoaded();
+    return this.cachedStoryIds!;
+  }
+
+  async getAliasMap(): Promise<ReadonlyMap<string, StoryIdLike>> {
+    await this.ensureLoaded();
+    return this.cachedAliasMap!;
+  }
+
+  async hasStoryId(
+    storyId: StoryIdLike | { readonly value: string } | string,
+  ): Promise<boolean> {
+    const ids = await this.getAllStoryIds();
+    const value = typeof storyId === 'string' ? storyId : storyId.value;
+    return ids.some((id) => id.value === value);
+  }
+
+  async exists(storyId: StoryIdLike): Promise<boolean> {
+    return this.hasStoryId(storyId);
+  }
+
+  private async ensureLoaded(): Promise<void> {
+    const filePath = path.join(
+      this.rootDir,
+      'docs',
+      'product',
+      'user_stories.md',
+    );
+
+    let currentMtime: number;
+    try {
+      const fileStat = await stat(filePath);
+      currentMtime = fileStat.mtimeMs;
+    } catch {
+      this.cachedStoryIds = Object.freeze([]);
+      this.cachedAliasMap = new Map();
+      this.cachedMtime = null;
+      return;
+    }
+
+    if (this.cachedMtime !== null && this.cachedMtime === currentMtime) {
+      return;
+    }
+
+    const content = await readFile(filePath, 'utf8');
+    const parsed = parseStoryCatalog(content);
+
+    const storyIds: StoryIdLike[] = [];
+    for (let i = 0; i < parsed.storyIds.length; i++) {
+      try {
+        storyIds.push(StoryId.parse(parsed.storyIds[i]));
+      } catch {
+        // 不正な形式は無視する
+      }
+    }
+
+    const aliasMap = new Map<string, StoryIdLike>();
+    parsed.aliasMap.forEach((targetId, legacyId) => {
+      try {
+        aliasMap.set(legacyId, StoryId.parse(targetId));
+      } catch {
+        // 不正な形式は無視する
+      }
+    });
+
+    this.cachedStoryIds = Object.freeze(storyIds);
+    this.cachedAliasMap = aliasMap;
+    this.cachedMtime = currentMtime;
+  }
+}

package/scripts/harness/traceability-model/infrastructure/gateways/markdown-unit-definition-gateway.ts

@@ -0,0 +1,95 @@
+/**
+ * @layer infrastructure
+ * @unit traceability-model
+ *
+ * docs/product/units/ 配下の *_unit.md を走査し UnitDefinitionPort を実装するゲートウェイ
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { UnitDefinitionPort } from '../../domain/ports/unit-definition-port.js';
+import type { ProjectRelativePathLike } from '../../domain/value-objects/chain-link.js';
+import { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+
+const UNIT_ID_PATTERN = /Unit\s+ID\*{0,2}\s*[:：]\s*(\S+)/;
+
+export interface MarkdownUnitDefinitionGatewayDeps {
+  readonly rootDir: string;
+}
+
+export class MarkdownUnitDefinitionGateway implements UnitDefinitionPort {
+  private readonly rootDir: string;
+  private cachedUnitNames: readonly string[] | null = null;
+
+  constructor(deps: MarkdownUnitDefinitionGatewayDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async getAllUnitNames(): Promise<readonly string[]> {
+    await this.ensureLoaded();
+    return this.cachedUnitNames!;
+  }
+
+  async exists(unitName: string): Promise<boolean> {
+    const names = await this.getAllUnitNames();
+    return names.indexOf(unitName) >= 0;
+  }
+
+  async hasUnit(unitName: string): Promise<boolean> {
+    return this.exists(unitName);
+  }
+
+  async findConstructionRoot(
+    unitName: string,
+  ): Promise<ProjectRelativePathLike | null> {
+    const unitExists = await this.exists(unitName);
+    if (!unitExists) {
+      return null;
+    }
+
+    const constructionPath = `docs/product/construction/${unitName}`;
+    const absolutePath = path.join(this.rootDir, constructionPath);
+
+    if (!fs.existsSync(absolutePath)) {
+      return null;
+    }
+
+    return ProjectRelativePath.create(constructionPath);
+  }
+
+  async resolveConstructionRoot(
+    unitName: string,
+  ): Promise<ProjectRelativePathLike | null> {
+    return this.findConstructionRoot(unitName);
+  }
+
+  private async ensureLoaded(): Promise<void> {
+    if (this.cachedUnitNames !== null) {
+      return;
+    }
+
+    const unitsDir = path.join(this.rootDir, 'docs', 'product', 'units');
+    if (!fs.existsSync(unitsDir)) {
+      this.cachedUnitNames = Object.freeze([]);
+      return;
+    }
+
+    const entries = await readdir(unitsDir);
+    const unitNames: string[] = [];
+
+    for (const entry of entries) {
+      if (!entry.endsWith('_unit.md')) {
+        continue;
+      }
+
+      const filePath = path.join(unitsDir, entry);
+      const content = await readFile(filePath, 'utf8');
+      const match = UNIT_ID_PATTERN.exec(content);
+      if (match) {
+        unitNames.push(match[1].trim());
+      }
+    }
+
+    this.cachedUnitNames = Object.freeze(unitNames);
+  }
+}

package/scripts/harness/traceability-model/infrastructure/parsers/frontmatter-flag-parser.ts

@@ -0,0 +1,52 @@
+/**
+ * @layer infrastructure
+ * @unit traceability-model
+ *
+ * 設計文書先頭のYAML frontmatterから traceability.initial_creation を抽出するパーサー。
+ * gray-matterに依存せず正規表現で処理する。
+ */
+
+export interface ParsedFrontmatterFlags {
+  readonly initialCreation: boolean;
+}
+
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+const INITIAL_CREATION_PATTERN =
+  /^\s*initial_creation\s*:\s*(true|false)\s*$/m;
+const TRACEABILITY_BLOCK_PATTERN =
+  /traceability\s*:\s*\r?\n((?:\s+.+\r?\n?)*)/;
+
+/**
+ * Markdown先頭のfrontmatterから traceability.initial_creation フラグを抽出する。
+ *
+ * - frontmatterがなければ { initialCreation: false } を返す。
+ * - フラグが真偽値でなければ例外を投げる。
+ */
+export function parseFrontmatterFlags(content: string): ParsedFrontmatterFlags {
+  const frontmatterMatch = FRONTMATTER_PATTERN.exec(content);
+  if (!frontmatterMatch) {
+    return { initialCreation: false };
+  }
+
+  const frontmatterBody = frontmatterMatch[1];
+
+  const traceabilityMatch = TRACEABILITY_BLOCK_PATTERN.exec(frontmatterBody);
+  if (!traceabilityMatch) {
+    return { initialCreation: false };
+  }
+
+  const traceabilityBlock = traceabilityMatch[1];
+  const initialCreationMatch = INITIAL_CREATION_PATTERN.exec(traceabilityBlock);
+  if (!initialCreationMatch) {
+    return { initialCreation: false };
+  }
+
+  const rawValue = initialCreationMatch[1];
+  if (rawValue !== 'true' && rawValue !== 'false') {
+    throw new Error(
+      `traceability.initial_creation の値が不正です（true/false のみ許容）: ${rawValue}`,
+    );
+  }
+
+  return { initialCreation: rawValue === 'true' };
+}

package/scripts/harness/traceability-model/infrastructure/parsers/markdown-story-annotation-parser.ts

@@ -0,0 +1,59 @@
+/**
+ * @layer infrastructure
+ * @unit traceability-model
+ *
+ * Markdown本文から @story-id HXX-XX の独立行を抽出するパーサー
+ */
+
+export interface ParsedStoryAnnotation {
+  readonly storyIdValue: string;
+  readonly lineNumber: number;
+  readonly contextLine: string;
+  readonly standaloneLine: boolean;
+}
+
+const STORY_ID_LINE_PATTERN = /^@story-id\s+(.+)$/;
+const STORY_ID_INLINE_PATTERN = /@story-id\s+(\S+)/;
+
+/**
+ * Markdown本文から @story-id 注釈を抽出する。
+ * 行頭/行末空白を除去して独立行判定し、次行のコンテキストを contextLine として保持する。
+ */
+export function parseStoryAnnotations(
+  content: string,
+): readonly ParsedStoryAnnotation[] {
+  const lines = content.split('\n');
+  const annotations: ParsedStoryAnnotation[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmedLine = lines[i].trim();
+    const lineNumber = i + 1;
+
+    const standaloneMatch = STORY_ID_LINE_PATTERN.exec(trimmedLine);
+    if (standaloneMatch) {
+      const contextLine =
+        i + 1 < lines.length ? lines[i + 1].trim() : '';
+      annotations.push({
+        storyIdValue: standaloneMatch[1].trim(),
+        lineNumber,
+        contextLine,
+        standaloneLine: true,
+      });
+      continue;
+    }
+
+    const inlineMatch = STORY_ID_INLINE_PATTERN.exec(trimmedLine);
+    if (inlineMatch) {
+      const contextLine =
+        i + 1 < lines.length ? lines[i + 1].trim() : '';
+      annotations.push({
+        storyIdValue: inlineMatch[1].trim(),
+        lineNumber,
+        contextLine,
+        standaloneLine: false,
+      });
+    }
+  }
+
+  return Object.freeze([...annotations]);
+}