phasegate 0.91.0 → 0.108.0

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-migration-apply-gateway.ts

@@ -0,0 +1,110 @@
+// @unit traceability-model
+// @layer infrastructure
+
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+import type { WorkItemMigrationApplyPort } from "../../domain/ports/work-item-migration-apply-port.js";
+import type {
+  WorkItemMigrationAppliedCandidate,
+  WorkItemMigrationCandidate,
+} from "../../domain/value-objects/work-item-migration-candidate.js";
+
+export interface FileSystemWorkItemMigrationApplyGatewayDeps {
+  readonly rootDir: string;
+}
+
+export class FileSystemWorkItemMigrationApplyGateway implements WorkItemMigrationApplyPort {
+  private readonly rootDir: string;
+
+  constructor(deps: FileSystemWorkItemMigrationApplyGatewayDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async apply(candidate: WorkItemMigrationCandidate): Promise<WorkItemMigrationAppliedCandidate> {
+    const sourceDir = path.join(this.rootDir, candidate.sourcePath);
+    const targetDir = path.join(this.rootDir, candidate.targetPath);
+
+    await assertPathDoesNotExist(targetDir);
+    await mkdir(path.dirname(targetDir), { recursive: true });
+    await rename(sourceDir, targetDir);
+
+    const descriptionPath = await this.normalizeDescriptionFile(targetDir, candidate);
+    await this.ensureFrontmatter(descriptionPath, candidate.frontmatterPreview);
+
+    return Object.freeze({
+      legacyId: candidate.legacyId,
+      nextId: candidate.nextId,
+      sourcePath: candidate.sourcePath,
+      targetPath: candidate.targetPath,
+      descriptionPath: path.posix.join(candidate.targetPath, "description.md"),
+    });
+  }
+
+  private async normalizeDescriptionFile(targetDir: string, candidate: WorkItemMigrationCandidate): Promise<string> {
+    const descriptionPath = path.join(targetDir, "description.md");
+    if (candidate.descriptionFileName === "description.md") {
+      return descriptionPath;
+    }
+
+    await assertPathDoesNotExist(descriptionPath);
+    if (candidate.descriptionFileName === null) {
+      await writeFile(descriptionPath, `# ${candidate.legacyId}\n`, "utf8");
+      return descriptionPath;
+    }
+
+    await rename(path.join(targetDir, candidate.descriptionFileName), descriptionPath);
+    return descriptionPath;
+  }
+
+  private async ensureFrontmatter(descriptionPath: string, frontmatterPreview: string): Promise<void> {
+    const content = await readFile(descriptionPath, "utf8");
+    const existing = parseFrontmatter(content);
+
+    if (existing === null) {
+      await writeFile(descriptionPath, `${frontmatterPreview}\n\n${content}`, "utf8");
+      return;
+    }
+
+    if (matchesPlannerFrontmatter(existing.frontmatter, frontmatterPreview)) {
+      return;
+    }
+
+    const body = content.slice(existing.length).replace(/^\s+/, "");
+    await writeFile(descriptionPath, `${frontmatterPreview}\n\n${body}`, "utf8");
+  }
+}
+
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const ID_PATTERN = /^id:\s*(\S+)\s*$/m;
+const LEGACY_ID_PATTERN = /^legacy_id:\s*(\S+)\s*$/m;
+
+function parseFrontmatter(content: string): { readonly frontmatter: string; readonly length: number } | null {
+  const match = FRONTMATTER_PATTERN.exec(content);
+  if (!match) return null;
+  return { frontmatter: match[1], length: match[0].length };
+}
+
+function matchesPlannerFrontmatter(existing: string, preview: string): boolean {
+  const previewMatch = FRONTMATTER_PATTERN.exec(`${preview}\n`);
+  if (!previewMatch) return false;
+  const previewBody = previewMatch[1];
+
+  const previewId = ID_PATTERN.exec(previewBody)?.[1];
+  const existingId = ID_PATTERN.exec(existing)?.[1];
+  if (previewId === undefined || previewId !== existingId) return false;
+
+  const previewLegacy = LEGACY_ID_PATTERN.exec(previewBody)?.[1];
+  if (previewLegacy === undefined) return true;
+
+  const existingLegacy = LEGACY_ID_PATTERN.exec(existing)?.[1];
+  return existingLegacy === previewLegacy;
+}
+
+async function assertPathDoesNotExist(targetPath: string): Promise<void> {
+  try {
+    await access(targetPath);
+  } catch {
+    return;
+  }
+  throw new Error(`Path already exists: ${targetPath}`);
+}

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-migration-source-gateway.ts

@@ -0,0 +1,182 @@
+// @unit traceability-model
+// @layer infrastructure
+
+import * as fs from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import * as path from "node:path";
+import type { WorkItemMigrationSourcePort } from "../../domain/ports/work-item-migration-source-port.js";
+import type {
+  LegacyIssueDirectory,
+  WorkItemDescriptionFileName,
+} from "../../domain/value-objects/work-item-migration-candidate.js";
+
+const ISSUE_DIR_PATTERN = /^(?:ISSUE|WI)-\d+$/;
+const H_ID_DIR_PATTERN = /^H\d{2}-\d{2}$/;
+const WI_DIR_PATTERN = /^WI-\d+$/;
+const SKIPPED_INCEPTION_DIRS = new Set(["_shared", "_operation", "_cross", "issues"]);
+
+export interface FileSystemWorkItemMigrationSourceGatewayDeps {
+  readonly rootDir: string;
+}
+
+export class FileSystemWorkItemMigrationSourceGateway implements WorkItemMigrationSourcePort {
+  private readonly rootDir: string;
+
+  constructor(deps: FileSystemWorkItemMigrationSourceGatewayDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async listLegacyIssueDirectories(): Promise<readonly LegacyIssueDirectory[]> {
+    const entries: LegacyIssueDirectory[] = [];
+    entries.push(...(await this.listCrossIssueDirectories()));
+    entries.push(...(await this.listUnitLegacyDirectories()));
+    return Object.freeze(entries);
+  }
+
+  async listExistingWorkItemIds(): Promise<readonly string[]> {
+    const inceptionDir = path.join(this.rootDir, "docs", "inception");
+    if (!fs.existsSync(inceptionDir)) return Object.freeze([]);
+
+    const ids = new Set<string>();
+    const crossDir = path.join(inceptionDir, "_cross");
+    if (fs.existsSync(crossDir)) {
+      for (const name of await readdir(crossDir)) {
+        if (WI_DIR_PATTERN.test(name)) ids.add(name);
+      }
+    }
+
+    for (const unitName of await readdir(inceptionDir)) {
+      if (SKIPPED_INCEPTION_DIRS.has(unitName)) continue;
+      const unitDir = path.join(inceptionDir, unitName);
+      if (!fs.statSync(unitDir).isDirectory()) continue;
+      for (const name of await readdir(unitDir)) {
+        if (WI_DIR_PATTERN.test(name)) ids.add(name);
+      }
+    }
+
+    return Object.freeze([...ids].sort());
+  }
+
+  private async listCrossIssueDirectories(): Promise<readonly LegacyIssueDirectory[]> {
+    const issuesDir = path.join(this.rootDir, "docs", "inception", "issues");
+    if (!fs.existsSync(issuesDir)) return Object.freeze([]);
+
+    const names = (await readdir(issuesDir)).sort();
+    const entries: LegacyIssueDirectory[] = [];
+    for (const name of names) {
+      if (!ISSUE_DIR_PATTERN.test(name)) continue;
+      const sourcePath = `docs/inception/issues/${name}`;
+      const entry = await this.createEntry({
+        legacyId: name,
+        sourcePath,
+        targetPath: `docs/inception/_cross/${toTargetId(name)}`,
+        scope: "cross",
+      });
+      entries.push(entry);
+    }
+    return Object.freeze(entries);
+  }
+
+  private async listUnitLegacyDirectories(): Promise<readonly LegacyIssueDirectory[]> {
+    const inceptionDir = path.join(this.rootDir, "docs", "inception");
+    if (!fs.existsSync(inceptionDir)) return Object.freeze([]);
+
+    const unitNames = (await readdir(inceptionDir)).sort();
+    const entries: LegacyIssueDirectory[] = [];
+    for (const unitName of unitNames) {
+      if (SKIPPED_INCEPTION_DIRS.has(unitName)) continue;
+      const unitDir = path.join(inceptionDir, unitName);
+      if (!fs.statSync(unitDir).isDirectory()) continue;
+
+      entries.push(...(await this.collectUnitIssueEntries(unitName)));
+      entries.push(...(await this.collectUnitHIdEntries(unitName)));
+    }
+
+    return Object.freeze(entries);
+  }
+
+  private async collectUnitIssueEntries(unitName: string): Promise<readonly LegacyIssueDirectory[]> {
+    const issuesDir = path.join(this.rootDir, "docs", "inception", unitName, "issues");
+    if (!fs.existsSync(issuesDir)) return Object.freeze([]);
+
+    const entries: LegacyIssueDirectory[] = [];
+    for (const name of (await readdir(issuesDir)).sort()) {
+      if (!ISSUE_DIR_PATTERN.test(name)) continue;
+      const sourcePath = `docs/inception/${unitName}/issues/${name}`;
+      const entry = await this.createEntry({
+        legacyId: name,
+        sourcePath,
+        targetPath: `docs/inception/${unitName}/${toTargetId(name)}`,
+        scope: "unit",
+        unitName,
+      });
+      entries.push(entry);
+    }
+    return Object.freeze(entries);
+  }
+
+  private async collectUnitHIdEntries(unitName: string): Promise<readonly LegacyIssueDirectory[]> {
+    const unitDir = path.join(this.rootDir, "docs", "inception", unitName);
+    const entries: LegacyIssueDirectory[] = [];
+    for (const name of (await readdir(unitDir)).sort()) {
+      if (!H_ID_DIR_PATTERN.test(name)) continue;
+      const childDir = path.join(unitDir, name);
+      if (!fs.statSync(childDir).isDirectory()) continue;
+
+      const sourcePath = `docs/inception/${unitName}/${name}`;
+      const descriptionFileName = this.resolveDescriptionFileName(sourcePath);
+      const content =
+        descriptionFileName === null
+          ? ""
+          : await readFile(path.join(this.rootDir, sourcePath, descriptionFileName), "utf8");
+
+      entries.push({
+        legacyId: name,
+        sourcePath,
+        scope: "unit",
+        unitName,
+        descriptionFileName,
+        content,
+        targetExists: false,
+      });
+    }
+    return Object.freeze(entries);
+  }
+
+  private async createEntry(args: {
+    readonly legacyId: string;
+    readonly sourcePath: string;
+    readonly targetPath: string;
+    readonly scope: "cross" | "unit";
+    readonly unitName?: string;
+  }): Promise<LegacyIssueDirectory> {
+    const descriptionFileName = this.resolveDescriptionFileName(args.sourcePath);
+    const content =
+      descriptionFileName === null
+        ? ""
+        : await readFile(path.join(this.rootDir, args.sourcePath, descriptionFileName), "utf8");
+
+    return {
+      legacyId: args.legacyId,
+      sourcePath: args.sourcePath,
+      scope: args.scope,
+      ...(args.unitName !== undefined ? { unitName: args.unitName } : {}),
+      descriptionFileName,
+      content,
+      targetExists: fs.existsSync(path.join(this.rootDir, args.targetPath)),
+    };
+  }
+
+  private resolveDescriptionFileName(sourcePath: string): WorkItemDescriptionFileName | null {
+    const descriptionPath = path.join(this.rootDir, sourcePath, "description.md");
+    if (fs.existsSync(descriptionPath)) return "description.md";
+
+    const issueDescriptionPath = path.join(this.rootDir, sourcePath, "issue_description.md");
+    return fs.existsSync(issueDescriptionPath) ? "issue_description.md" : null;
+  }
+}
+
+function toTargetId(legacyId: string): string {
+  if (legacyId.startsWith("WI-")) return legacyId;
+  return `WI-${legacyId.replace(/^ISSUE-/, "").padStart(3, "0")}`;
+}

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

@@ -4,17 +4,20 @@
  *
  * 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';
+
+import * as fs from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+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 { DesignDocumentFlags } from "../../domain/value-objects/design-document-flags.js";
+import { ProjectRelativePath } from "../../domain/value-objects/project-relative-path.js";
+import { StoryId } from "../../domain/value-objects/story-id.js";
+import { StoryIdAnnotation } from "../../domain/value-objects/story-id-annotation.js";
+import type { WorkItemFrontmatter } from "../../domain/value-objects/work-item-frontmatter.js";
+import { parseFrontmatterFlags } from "../parsers/frontmatter-flag-parser.js";
+import { parseStoryAnnotations } from "../parsers/markdown-story-annotation-parser.js";
+import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parser.js";
 
 export interface MarkdownDesignDocumentGatewayDeps {
   readonly rootDir: string;
@@ -28,16 +31,8 @@ export class MarkdownDesignDocumentGateway implements DesignDocumentPort {
     this.rootDir = deps.rootDir;
   }
 
-  async listByUnit(
-    unitName: string,
-  ): Promise<readonly ProjectRelativePathLike[]> {
-    const constructionDir = path.join(
-      this.rootDir,
-      'docs',
-      'product',
-      'construction',
-      unitName,
-    );
+  async listByUnit(unitName: string): Promise<readonly ProjectRelativePathLike[]> {
+    const constructionDir = path.join(this.rootDir, "docs", "product", "construction", unitName);
 
     if (!fs.existsSync(constructionDir)) {
       return [];
@@ -47,27 +42,19 @@ export class MarkdownDesignDocumentGateway implements DesignDocumentPort {
     const results: ProjectRelativePathLike[] = [];
 
     for (const entry of entries) {
-      if (entry.endsWith('.md')) {
-        results.push(
-          ProjectRelativePath.create(
-            `docs/product/construction/${unitName}/${entry}`,
-          ),
-        );
+      if (entry.endsWith(".md")) {
+        results.push(ProjectRelativePath.create(`docs/product/construction/${unitName}/${entry}`));
       }
     }
 
     return results;
   }
 
-  async findConstructionDocuments(
-    unitName: string,
-  ): Promise<readonly ProjectRelativePathLike[]> {
+  async findConstructionDocuments(unitName: string): Promise<readonly ProjectRelativePathLike[]> {
     return this.listByUnit(unitName);
   }
 
-  async readStoryAnnotations(
-    filePath: ProjectRelativePathLike,
-  ): Promise<readonly StoryIdAnnotation[]> {
+  async readStoryAnnotations(filePath: ProjectRelativePathLike): Promise<readonly StoryIdAnnotation[]> {
     const content = await this.getContent(filePath);
     const parsed = parseStoryAnnotations(content);
 
@@ -92,30 +79,29 @@ export class MarkdownDesignDocumentGateway implements DesignDocumentPort {
     return annotations;
   }
 
-  async readStoryIdAnnotations(
-    filePath: ProjectRelativePathLike,
-  ): Promise<readonly StoryIdAnnotation[]> {
+  async readStoryIdAnnotations(filePath: ProjectRelativePathLike): Promise<readonly StoryIdAnnotation[]> {
     return this.readStoryAnnotations(filePath);
   }
 
-  async readFrontmatterFlags(
-    filePath: ProjectRelativePathLike,
-  ): Promise<DesignDocumentFlags> {
+  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> {
+  async readWorkItemFrontmatter(filePath: ProjectRelativePathLike): Promise<WorkItemFrontmatter | null> {
+    const content = await this.getContent(filePath);
+    return parseWorkItemFrontmatter(content);
+  }
+
+  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');
+    const content = await readFile(absolutePath, "utf8");
     this.contentCache.set(filePath.value, content);
     return content;
   }

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

@@ -0,0 +1,136 @@
+// @unit traceability-model
+// @layer infrastructure
+/**
+ * 設計文書先頭 YAML frontmatter から WorkItem メタデータを抽出するパーサー（H03-04 / ISSUE-026 Phase A-2）。
+ *
+ * - 既存 `parseFrontmatterFlags` (initial_creation) とは独立実装・後方互換
+ * - frontmatter 不在時は `null` を返し、必須キー不足・enum 違反時は
+ *   `WorkItemFrontmatterValidationError` を throw する
+ * - YAML の一般的な edge case（anchor / 複数行 string / tagged type）は非対応。
+ *   本 parser は WI frontmatter の単純な key: value + flat/block list のみを扱う
+ */
+
+import {
+  WORK_ITEM_ID_PATTERN,
+  WORK_ITEM_SEVERITIES,
+  WORK_ITEM_STATUSES,
+  WORK_ITEM_TYPES,
+  type WorkItemFrontmatter,
+  WorkItemFrontmatterValidationError,
+  type WorkItemSeverity,
+  type WorkItemStatus,
+  type WorkItemType,
+} from "../../domain/value-objects/work-item-frontmatter.js";
+
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+const scalarPattern = (key: string): RegExp => new RegExp(`^\\s*${key}\\s*:\\s*(.+?)\\s*$`, "m");
+
+const flowArrayPattern = (key: string): RegExp => new RegExp(`^\\s*${key}\\s*:\\s*\\[([^\\]]*)\\]\\s*$`, "m");
+
+const blockArrayPattern = (key: string): RegExp =>
+  new RegExp(`^\\s*${key}\\s*:\\s*\\r?\\n((?:[ \\t]+-[ \\t]+.+\\r?\\n?)+)`, "m");
+
+export function parseWorkItemFrontmatter(content: string): WorkItemFrontmatter | null {
+  const match = FRONTMATTER_PATTERN.exec(content);
+  if (!match) return null;
+
+  const body = match[1];
+
+  const id = extractScalar(body, "id");
+  const type = extractScalar(body, "type");
+
+  if (!id && !type) {
+    return null;
+  }
+
+  if (!id) {
+    throw new WorkItemFrontmatterValidationError("id が不足しています");
+  }
+  if (!type) {
+    throw new WorkItemFrontmatterValidationError("type が不足しています");
+  }
+  if (!WORK_ITEM_ID_PATTERN.test(id)) {
+    throw new WorkItemFrontmatterValidationError(`id 形式が不正です: ${id}`);
+  }
+  if (!WORK_ITEM_TYPES.has(type as WorkItemType)) {
+    throw new WorkItemFrontmatterValidationError(`type 値が enum 外: ${type}`);
+  }
+
+  const severityRaw = extractScalar(body, "severity");
+  if (severityRaw !== undefined && !WORK_ITEM_SEVERITIES.has(severityRaw as WorkItemSeverity)) {
+    throw new WorkItemFrontmatterValidationError(`severity 値が enum 外: ${severityRaw}`);
+  }
+
+  const statusRaw = extractScalar(body, "status");
+  if (statusRaw !== undefined && !WORK_ITEM_STATUSES.has(statusRaw as WorkItemStatus)) {
+    throw new WorkItemFrontmatterValidationError(`status 値が enum 外: ${statusRaw}`);
+  }
+
+  const affects = extractArray(body, "affects");
+  const source = extractScalar(body, "source");
+  const legacyId = extractScalar(body, "legacy_id");
+
+  const result: {
+    id: string;
+    type: WorkItemType;
+    affects?: readonly string[];
+    severity?: WorkItemSeverity;
+    status?: WorkItemStatus;
+    source?: string;
+    legacyId?: string;
+  } = {
+    id,
+    type: type as WorkItemType,
+  };
+  if (affects) result.affects = affects;
+  if (severityRaw) result.severity = severityRaw as WorkItemSeverity;
+  if (statusRaw) result.status = statusRaw as WorkItemStatus;
+  if (source) result.source = source;
+  if (legacyId) result.legacyId = legacyId;
+
+  return result;
+}
+
+function extractScalar(body: string, key: string): string | undefined {
+  const match = scalarPattern(key).exec(body);
+  if (!match) return undefined;
+  const raw = match[1].trim();
+  if (raw.length === 0) return undefined;
+  // フロー配列記法 (`[a, b]`) は scalar として扱わず、array 抽出側に委ねる
+  if (raw.startsWith("[")) return undefined;
+  return stripYamlQuotes(raw);
+}
+
+function extractArray(body: string, key: string): readonly string[] | undefined {
+  const flow = flowArrayPattern(key).exec(body);
+  if (flow) {
+    const items = flow[1]
+      .split(",")
+      .map((s) => stripYamlQuotes(s.trim()))
+      .filter((s) => s.length > 0);
+    return items.length > 0 ? items : undefined;
+  }
+
+  const block = blockArrayPattern(key).exec(body);
+  if (block) {
+    const items = block[1]
+      .split(/\r?\n/)
+      .map((line) => line.replace(/^[ \t]+-[ \t]+/, "").trim())
+      .map(stripYamlQuotes)
+      .filter((s) => s.length > 0);
+    return items.length > 0 ? items : undefined;
+  }
+
+  return undefined;
+}
+
+function stripYamlQuotes(value: string): string {
+  if (value.length < 2) return value;
+  const first = value[0];
+  const last = value[value.length - 1];
+  if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}