phasegate 0.229.0 → 0.264.0

package/scripts/harness/traceability-model/application/facades/traceability-world-read-facade.ts

@@ -0,0 +1,372 @@
+// @unit traceability-model
+// @layer application
+// @work-item-id WI-288
+
+import {
+  TRACEABILITY_WORLD_READ_SCHEMA_VERSION,
+  type TraceabilityAcceptanceCriterionDto,
+  type TraceabilityReadDiagnosticDto,
+  type TraceabilityStoryDto,
+  type TraceabilityTestReferenceDto,
+  type TraceabilityUnitDto,
+  type TraceabilityWorkItemDto,
+  type TraceabilityWorldReadDto,
+} from "../dto/traceability-world-read-dto.js";
+import type {
+  RawTraceabilityStory,
+  RawTraceabilityTestAnnotation,
+  TraceabilityWorldReadSourcePort,
+} from "../ports/traceability-world-read-source-port.js";
+
+const STORY_ID_PATTERN = /^H(?:F\d+|\d{2})-\d{2}$/;
+const WORK_ITEM_ID_PATTERN = /^WI-\d+$/;
+const AC_ID_PATTERN = /^AC-(\d+)$/;
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const compareAcIds = (left: string, right: string): number => {
+  const leftMatch = AC_ID_PATTERN.exec(left);
+  const rightMatch = AC_ID_PATTERN.exec(right);
+  if (leftMatch && rightMatch) {
+    const difference = Number(leftMatch[1]) - Number(rightMatch[1]);
+    if (difference !== 0) return difference;
+  }
+  return compareStrings(left, right);
+};
+
+const compareTuples = (
+  left: readonly (string | number | null)[],
+  right: readonly (string | number | null)[],
+): number => {
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftValue = left[index] ?? "";
+    const rightValue = right[index] ?? "";
+    if (typeof leftValue === "number" && typeof rightValue === "number") {
+      if (leftValue !== rightValue) return leftValue - rightValue;
+      continue;
+    }
+    const difference = compareStrings(String(leftValue), String(rightValue));
+    if (difference !== 0) return difference;
+  }
+  return 0;
+};
+
+const groupBy = <T>(values: readonly T[], keyOf: (value: T) => string): ReadonlyMap<string, readonly T[]> => {
+  const groups = new Map<string, T[]>();
+  for (const value of values) {
+    const key = keyOf(value);
+    const current = groups.get(key) ?? [];
+    current.push(value);
+    groups.set(key, current);
+  }
+  return groups;
+};
+
+const diagnostic = (
+  code: string,
+  subjectId: string | null,
+  sourcePaths: readonly string[],
+  message: string,
+): TraceabilityReadDiagnosticDto => ({
+  code,
+  subjectId,
+  sourcePaths: [...sourcePaths].sort(compareStrings),
+  message,
+});
+
+export interface TraceabilityWorldReadFacadeDeps {
+  readonly sourcePort: TraceabilityWorldReadSourcePort;
+}
+
+export class TraceabilityWorldReadFacade {
+  private readonly sourcePort: TraceabilityWorldReadSourcePort;
+
+  constructor(deps: TraceabilityWorldReadFacadeDeps) {
+    this.sourcePort = deps.sourcePort;
+  }
+
+  async read(): Promise<TraceabilityWorldReadDto> {
+    const source = await this.sourcePort.read();
+    const diagnostics: TraceabilityReadDiagnosticDto[] = source.diagnostics.map((entry) =>
+      diagnostic(entry.code, entry.subjectId, entry.sourcePaths, entry.message),
+    );
+
+    const units = this.admitUnits(source.units, diagnostics);
+    const admittedStories = this.admitStories(source.stories, diagnostics);
+    const { stories, acceptanceCriteria } = this.projectStories(admittedStories, diagnostics);
+    const workItems = this.admitWorkItems(source.workItems, diagnostics);
+    const testReferences = this.projectTestReferences(
+      source.testAnnotations,
+      admittedStories,
+      acceptanceCriteria,
+      diagnostics,
+    );
+
+    return {
+      schemaVersion: TRACEABILITY_WORLD_READ_SCHEMA_VERSION,
+      units: units.sort((left, right) =>
+        compareTuples([left.unitId, left.definitionPath], [right.unitId, right.definitionPath]),
+      ),
+      stories: stories.sort((left, right) =>
+        compareTuples([left.storyId, left.sourcePath], [right.storyId, right.sourcePath]),
+      ),
+      acceptanceCriteria: acceptanceCriteria.sort((left, right) => {
+        const storyDifference = compareStrings(left.storyId, right.storyId);
+        if (storyDifference !== 0) return storyDifference;
+        const acDifference = compareAcIds(left.acId, right.acId);
+        if (acDifference !== 0) return acDifference;
+        return compareStrings(left.sourcePath, right.sourcePath);
+      }),
+      workItems: workItems.sort((left, right) =>
+        compareTuples([left.workItemId, left.descriptionPath], [right.workItemId, right.descriptionPath]),
+      ),
+      testReferences: testReferences.sort((left, right) => {
+        const storyDifference = compareStrings(left.storyId, right.storyId);
+        if (storyDifference !== 0) return storyDifference;
+        const acDifference = compareAcIds(left.acId, right.acId);
+        if (acDifference !== 0) return acDifference;
+        return compareTuples(
+          [left.binding, left.testType, left.filePath, left.testName],
+          [right.binding, right.testType, right.filePath, right.testName],
+        );
+      }),
+      diagnostics: diagnostics.sort((left, right) =>
+        compareTuples(
+          [left.code, left.subjectId, left.sourcePaths.join("\u0000")],
+          [right.code, right.subjectId, right.sourcePaths.join("\u0000")],
+        ),
+      ),
+    };
+  }
+
+  private admitUnits(
+    rawUnits: Awaited<ReturnType<TraceabilityWorldReadSourcePort["read"]>>["units"],
+    diagnostics: TraceabilityReadDiagnosticDto[],
+  ): TraceabilityUnitDto[] {
+    const result: TraceabilityUnitDto[] = [];
+    for (const [unitId, candidates] of groupBy(rawUnits, (entry) => entry.unitId)) {
+      if (candidates.length !== 1) {
+        diagnostics.push(
+          diagnostic(
+            "TM-WORLD-READ-DUPLICATE-UNIT",
+            unitId,
+            candidates.map((entry) => entry.definitionPath),
+            `Unit ID ${unitId} has ${candidates.length} owners`,
+          ),
+        );
+        continue;
+      }
+      const candidate = candidates[0];
+      result.push({
+        unitId: candidate.unitId,
+        definitionPath: candidate.definitionPath,
+        constructionRoot: candidate.constructionRoot,
+      });
+    }
+    return result;
+  }
+
+  private admitStories(
+    rawStories: readonly RawTraceabilityStory[],
+    diagnostics: TraceabilityReadDiagnosticDto[],
+  ): readonly RawTraceabilityStory[] {
+    const result: RawTraceabilityStory[] = [];
+    for (const [storyId, candidates] of groupBy(rawStories, (entry) => entry.storyId)) {
+      if (!STORY_ID_PATTERN.test(storyId)) {
+        diagnostics.push(
+          diagnostic(
+            "TM-WORLD-READ-MALFORMED-STORY-ID",
+            storyId,
+            candidates.map((entry) => entry.sourcePath),
+            `Story ID is not canonical: ${storyId}`,
+          ),
+        );
+        continue;
+      }
+      if (candidates.length !== 1) {
+        diagnostics.push(
+          diagnostic(
+            "TM-WORLD-READ-DUPLICATE-STORY",
+            storyId,
+            candidates.map((entry) => entry.sourcePath),
+            `Story ID ${storyId} has ${candidates.length} owners`,
+          ),
+        );
+        continue;
+      }
+      result.push(candidates[0]);
+    }
+    return result;
+  }
+
+  private projectStories(
+    rawStories: readonly RawTraceabilityStory[],
+    diagnostics: TraceabilityReadDiagnosticDto[],
+  ): {
+    readonly stories: TraceabilityStoryDto[];
+    readonly acceptanceCriteria: TraceabilityAcceptanceCriterionDto[];
+  } {
+    const stories: TraceabilityStoryDto[] = [];
+    const acceptanceCriteria: TraceabilityAcceptanceCriterionDto[] = [];
+    for (const story of rawStories) {
+      stories.push({
+        storyId: story.storyId,
+        legacyIds: [...new Set(story.legacyIds)].sort(compareStrings),
+        sourcePath: story.sourcePath,
+        line: story.line,
+      });
+      for (const [acId, candidates] of groupBy(story.acceptanceCriteria, (entry) => entry.acId)) {
+        if (!AC_ID_PATTERN.test(acId)) {
+          diagnostics.push(
+            diagnostic(
+              "TM-WORLD-READ-MALFORMED-AC-ID",
+              `${story.storyId}:${acId}`,
+              [story.sourcePath],
+              `Acceptance Criterion ID is not canonical: ${acId}`,
+            ),
+          );
+          continue;
+        }
+        if (candidates.length !== 1) {
+          diagnostics.push(
+            diagnostic(
+              "TM-WORLD-READ-DUPLICATE-AC",
+              `${story.storyId}:${acId}`,
+              [story.sourcePath],
+              `Acceptance Criterion ${story.storyId}:${acId} has ${candidates.length} owners`,
+            ),
+          );
+          continue;
+        }
+        acceptanceCriteria.push({
+          storyId: story.storyId,
+          acId,
+          sourcePath: story.sourcePath,
+          line: candidates[0].line,
+        });
+      }
+    }
+    return { stories, acceptanceCriteria };
+  }
+
+  private admitWorkItems(
+    rawWorkItems: Awaited<ReturnType<TraceabilityWorldReadSourcePort["read"]>>["workItems"],
+    diagnostics: TraceabilityReadDiagnosticDto[],
+  ): TraceabilityWorkItemDto[] {
+    const candidatesById = groupBy(rawWorkItems, (entry) => entry.workItemId);
+    const result: TraceabilityWorkItemDto[] = [];
+    for (const [workItemId, candidates] of candidatesById) {
+      if (!WORK_ITEM_ID_PATTERN.test(workItemId)) {
+        diagnostics.push(
+          diagnostic(
+            "TM-WORLD-READ-MALFORMED-WORK-ITEM-ID",
+            workItemId,
+            candidates.map((entry) => entry.descriptionPath),
+            `WorkItem ID is not canonical: ${workItemId}`,
+          ),
+        );
+        continue;
+      }
+      const matchingCandidates = candidates.filter((entry) => entry.directoryId === entry.workItemId);
+      for (const candidate of candidates) {
+        if (candidate.directoryId !== candidate.workItemId) {
+          diagnostics.push(
+            diagnostic(
+              "TM-WORLD-READ-WORK-ITEM-ID-MISMATCH",
+              workItemId,
+              [candidate.descriptionPath],
+              `WorkItem directory ${candidate.directoryId} does not match frontmatter ${candidate.workItemId}`,
+            ),
+          );
+        }
+      }
+      if (matchingCandidates.length === 0) continue;
+      if (candidates.length !== 1) {
+        diagnostics.push(
+          diagnostic(
+            "TM-WORLD-READ-DUPLICATE-WORK-ITEM",
+            workItemId,
+            candidates.map((entry) => entry.descriptionPath),
+            `WorkItem ID ${workItemId} has ${candidates.length} owners`,
+          ),
+        );
+        continue;
+      }
+      const candidate = matchingCandidates[0];
+      result.push({
+        workItemId,
+        legacyIds: candidate.legacyId ? [candidate.legacyId] : [],
+        type: candidate.type,
+        severity: candidate.severity,
+        status: candidate.status,
+        affects: [...new Set(candidate.affects)].sort(compareStrings),
+        descriptionPath: candidate.descriptionPath,
+      });
+    }
+    return result;
+  }
+
+  private projectTestReferences(
+    annotations: readonly RawTraceabilityTestAnnotation[],
+    stories: readonly RawTraceabilityStory[],
+    acceptanceCriteria: readonly TraceabilityAcceptanceCriterionDto[],
+    diagnostics: TraceabilityReadDiagnosticDto[],
+  ): TraceabilityTestReferenceDto[] {
+    const knownStories = new Map(stories.map((story) => [story.storyId, story]));
+    const criteriaByStory = groupBy(acceptanceCriteria, (entry) => entry.storyId);
+    const candidates: TraceabilityTestReferenceDto[] = [];
+
+    for (const annotation of annotations) {
+      if (!knownStories.has(annotation.storyId)) {
+        diagnostics.push(
+          diagnostic(
+            "TM-WORLD-READ-UNKNOWN-TEST-STORY",
+            annotation.storyId,
+            [annotation.filePath],
+            `Test annotation references unknown Story ${annotation.storyId}`,
+          ),
+        );
+        continue;
+      }
+      for (const criterion of criteriaByStory.get(annotation.storyId) ?? []) {
+        candidates.push({
+          storyId: annotation.storyId,
+          acId: criterion.acId,
+          binding: "file",
+          testType: annotation.testType,
+          filePath: annotation.filePath,
+          testName: null,
+          provenance: [
+            {
+              sourcePath: annotation.filePath,
+              line: annotation.line,
+            },
+          ],
+        });
+      }
+    }
+
+    const result: TraceabilityTestReferenceDto[] = [];
+    for (const [identity, references] of groupBy(candidates, (entry) =>
+      [entry.storyId, entry.acId, entry.binding, entry.testType, entry.filePath, entry.testName ?? "none"].join(
+        "\u0000",
+      ),
+    )) {
+      if (references.length !== 1) {
+        const first = references[0];
+        diagnostics.push(
+          diagnostic(
+            "TM-WORLD-READ-DUPLICATE-TEST-REFERENCE",
+            `${first.storyId}:${first.acId}`,
+            references.map((entry) => entry.filePath),
+            `TestReference identity ${identity} has ${references.length} owners`,
+          ),
+        );
+        continue;
+      }
+      result.push(references[0]);
+    }
+    return result;
+  }
+}

package/scripts/harness/traceability-model/application/ports/staged-design-change-source-port.ts

@@ -0,0 +1,9 @@
+// @unit traceability-model
+// @layer application
+// @work-item-id WI-305
+
+import type { DesignChangeReadResultDto } from "../dto/changed-design-fragment-dto.js";
+
+export interface StagedDesignChangeSourcePort {
+  observe(stagedFiles: readonly string[]): Promise<DesignChangeReadResultDto>;
+}

package/scripts/harness/traceability-model/application/ports/traceability-world-read-source-port.ts

@@ -0,0 +1,61 @@
+// @unit traceability-model
+// @layer application
+// @work-item-id WI-288
+
+import type { TraceabilityTestType } from "../dto/traceability-world-read-dto.js";
+
+export interface RawTraceabilityUnit {
+  readonly unitId: string;
+  readonly definitionPath: string;
+  readonly constructionRoot: string | null;
+}
+
+export interface RawTraceabilityAcceptanceCriterion {
+  readonly acId: string;
+  readonly line: number;
+}
+
+export interface RawTraceabilityStory {
+  readonly storyId: string;
+  readonly legacyIds: readonly string[];
+  readonly sourcePath: string;
+  readonly line: number;
+  readonly acceptanceCriteria: readonly RawTraceabilityAcceptanceCriterion[];
+}
+
+export interface RawTraceabilityWorkItem {
+  readonly directoryId: string;
+  readonly workItemId: string;
+  readonly legacyId: string | null;
+  readonly type: string;
+  readonly severity: string | null;
+  readonly status: string | null;
+  readonly affects: readonly string[];
+  readonly descriptionPath: string;
+}
+
+export interface RawTraceabilityTestAnnotation {
+  readonly storyId: string;
+  readonly filePath: string;
+  readonly line: number;
+  readonly testType: TraceabilityTestType;
+}
+
+export interface RawTraceabilityDiagnostic {
+  readonly code: string;
+  readonly subjectId: string | null;
+  readonly sourcePaths: readonly string[];
+  readonly message: string;
+}
+
+export interface TraceabilityWorldReadSourceDto {
+  readonly units: readonly RawTraceabilityUnit[];
+  readonly stories: readonly RawTraceabilityStory[];
+  readonly workItems: readonly RawTraceabilityWorkItem[];
+  readonly testAnnotations: readonly RawTraceabilityTestAnnotation[];
+  readonly diagnostics: readonly RawTraceabilityDiagnostic[];
+}
+
+export interface TraceabilityWorldReadSourcePort {
+  read(): Promise<TraceabilityWorldReadSourceDto>;
+}

package/scripts/harness/traceability-model/composition-root.ts

@@ -2,11 +2,14 @@
  * @layer application
  * @unit traceability-model
  * @work-item-id WI-093
+ * @work-item-id WI-305
  *
  * traceability-model ユニットの Composition Root。
  * 全コンポーネントを生成・配線し、外部に公開するハンドラー群を返す。
  */
 
+import { DesignChangeReadFacade } from "./application/facades/design-change-read-facade.js";
+import { TraceabilityWorldReadFacade } from "./application/facades/traceability-world-read-facade.js";
 import { ApplyWorkItemMigrationUseCase } from "./application/usecases/apply-work-item-migration-usecase.js";
 import { ApplyWorkItemStatusUseCase } from "./application/usecases/apply-work-item-status-usecase.js";
 import { DeriveWorkItemStatusUseCase } from "./application/usecases/derive-work-item-status-usecase.js";
@@ -19,11 +22,13 @@ import { StoryIdAliasResolver } from "./domain/services/story-id-alias-resolver.
 import { TraceabilityChainBuilder } from "./domain/services/traceability-chain-builder.js";
 import { WorkItemStatusDerivationService } from "./domain/services/work-item-status-derivation-service.js";
 import { ProjectRelativePath } from "./domain/value-objects/project-relative-path.js";
+import { FileSystemTraceabilityWorldReadAdapter } from "./infrastructure/adapters/file-system-traceability-world-read-adapter.js";
+import { GitStagedDesignChangeAdapter } from "./infrastructure/adapters/git-staged-design-change-adapter.js";
 import { FileSystemInceptionPlanGateway } from "./infrastructure/gateways/file-system-inception-plan-gateway.js";
 import { FileSystemMetadataReader } from "./infrastructure/gateways/file-system-metadata-reader.js";
+import { FileSystemWorkItemIdentityGateway } from "./infrastructure/gateways/file-system-work-item-identity-gateway.js";
 import { FileSystemWorkItemMigrationApplyGateway } from "./infrastructure/gateways/file-system-work-item-migration-apply-gateway.js";
 import { FileSystemWorkItemMigrationSourceGateway } from "./infrastructure/gateways/file-system-work-item-migration-source-gateway.js";
-import { FileSystemWorkItemIdentityGateway } from "./infrastructure/gateways/file-system-work-item-identity-gateway.js";
 import { FileSystemWorkItemStatusGateway } from "./infrastructure/gateways/file-system-work-item-status-gateway.js";
 import { MarkdownDesignDocumentGateway } from "./infrastructure/gateways/markdown-design-document-gateway.js";
 import { MarkdownStoryCatalogGateway } from "./infrastructure/gateways/markdown-story-catalog-gateway.js";
@@ -34,6 +39,8 @@ import { WorkItemStatusCommandHandler } from "./presentation/cli/work-item-statu
 
 export interface TraceabilityModelPathRoots {
   readonly designDocsRoot: string;
+  readonly inceptionRoot?: string;
+  readonly testRoots?: readonly string[];
 }
 
 export interface TraceabilityModelModuleOptions {
@@ -48,13 +55,12 @@ const deriveProductDocsRoot = (designDocsRoot: string): string => {
   return normalized;
 };
 
-export function createTraceabilityModelModule(
-  rootDir: string,
-  options: TraceabilityModelModuleOptions = {},
-) {
+export function createTraceabilityModelModule(rootDir: string, options: TraceabilityModelModuleOptions = {}) {
   const designDocsRoot = options.pathRoots?.designDocsRoot ?? "docs/product/construction";
   const productDocsRoot = deriveProductDocsRoot(designDocsRoot);
   const storyCatalogPath = `${productDocsRoot}/user_stories.md`;
+  const inceptionRoot = options.pathRoots?.inceptionRoot ?? "docs/inception";
+  const testRoots = options.pathRoots?.testRoots ?? ["scripts/harness/__tests__"];
 
   // Infrastructure gateways
   const storyCatalog = new MarkdownStoryCatalogGateway({ rootDir, storyCatalogPath });
@@ -70,6 +76,15 @@ export function createTraceabilityModelModule(
   const workItemMigrationApply = new FileSystemWorkItemMigrationApplyGateway({ rootDir });
   const workItemIdentity = new FileSystemWorkItemIdentityGateway({ rootDir });
   const workItemStatus = new FileSystemWorkItemStatusGateway({ rootDir });
+  const worldReadSource = new FileSystemTraceabilityWorldReadAdapter({
+    rootDir,
+    productDocsRoot,
+    designDocsRoot,
+    storyCatalogPath,
+    inceptionRoot,
+    testRoots,
+    unitDefinitionGateway: unitDefinition,
+  });
 
   // Domain services
   const metadataValidator = new MetadataValidator({
@@ -86,6 +101,10 @@ export function createTraceabilityModelModule(
   });
   const storyIdAliasResolver = new StoryIdAliasResolver(storyCatalog);
   const workItemStatusDerivationService = new WorkItemStatusDerivationService();
+  const worldReadFacade = new TraceabilityWorldReadFacade({
+    sourcePort: worldReadSource,
+  });
+  const designChangeReadFacade = new DesignChangeReadFacade(new GitStagedDesignChangeAdapter(rootDir));
 
   // Usecases
   const validateImplementationMetadataUseCase = new ValidateImplementationMetadataUseCase({
@@ -141,5 +160,7 @@ export function createTraceabilityModelModule(
     storyCatalog,
     traceabilityChainBuilder,
     storyIdAliasResolver,
+    worldReadFacade,
+    designChangeReadFacade,
   } as const;
 }

package/scripts/harness/traceability-model/index.ts

@@ -1,16 +1,36 @@
 /**
  * @layer public-api
  * @unit traceability-model
+ * @work-item-id WI-305
  *
  * traceability-model ユニットのバレルエクスポート。
  */
 
+export type {
+  ChangedDesignFragmentDto,
+  DesignChangeReadDiagnosticDto,
+  DesignChangeReadResultDto,
+  DesignFragmentChangeKind,
+  DesignFragmentCorpusRole,
+} from "./application/dto/changed-design-fragment-dto.js";
+export type {
+  TraceabilityAcceptanceCriterionDto,
+  TraceabilityReadDiagnosticDto,
+  TraceabilityStoryDto,
+  TraceabilityTestReferenceDto,
+  TraceabilityTestType,
+  TraceabilityUnitDto,
+  TraceabilityWorkItemDto,
+  TraceabilityWorldReadDto,
+} from "./application/dto/traceability-world-read-dto.js";
+export { TRACEABILITY_WORLD_READ_SCHEMA_VERSION } from "./application/dto/traceability-world-read-dto.js";
+export { DesignChangeReadFacade } from "./application/facades/design-change-read-facade.js";
+// Application — public World read facade and plain DTO contract
+export { TraceabilityWorldReadFacade } from "./application/facades/traceability-world-read-facade.js";
 // Composition Root
-export { createTraceabilityModelModule } from './composition-root.js';
-
+export { createTraceabilityModelModule } from "./composition-root.js";
 // Domain — value objects
-export { ProjectRelativePath } from './domain/value-objects/project-relative-path.js';
-export { StoryId } from './domain/value-objects/story-id.js';
-
+export { ProjectRelativePath } from "./domain/value-objects/project-relative-path.js";
+export { StoryId } from "./domain/value-objects/story-id.js";
 // Presentation — CLI handlers
-export { ValidateMetadataCommandHandler } from './presentation/cli/validate-metadata-command-handler.js';
+export { ValidateMetadataCommandHandler } from "./presentation/cli/validate-metadata-command-handler.js";