phasegate 0.15.0

package/scripts/harness/traceability-model/application/usecases/build-traceability-chain-usecase.ts

@@ -0,0 +1,64 @@
+/**
+ * @layer application
+ * @unit traceability-model
+ */
+
+import type { TraceabilityChainOutput, TraceabilityLinkOutput } from '../dto/traceability-chain-output.js';
+import type { TraceabilityChainBuilder } from '../../domain/services/traceability-chain-builder.js';
+import type { ChainLink } from '../../domain/value-objects/chain-link.js';
+import type { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+
+type TraceabilityBuilder = Pick<TraceabilityChainBuilder, 'build'>;
+
+const toLinkOutput = (link: ChainLink): Readonly<TraceabilityLinkOutput> =>
+  Object.freeze({
+    from: link.from.toString(),
+    to: link.to.toString(),
+    linkType: link.linkType,
+    resolved: link.resolved,
+  });
+
+export class TraceabilityChainBuildError extends Error {
+  readonly origin: string;
+  readonly cause: unknown;
+
+  constructor(origin: string, cause: unknown) {
+    super(`traceability chain build failed: ${origin}`);
+    this.name = 'TraceabilityChainBuildError';
+    this.origin = origin;
+    this.cause = cause;
+  }
+}
+
+export interface BuildTraceabilityChainUseCaseDeps {
+  readonly builder: TraceabilityBuilder;
+}
+
+export class BuildTraceabilityChainUseCase {
+  private readonly builder: TraceabilityBuilder;
+
+  constructor(deps: BuildTraceabilityChainUseCaseDeps) {
+    this.builder = deps.builder;
+  }
+
+  async execute(
+    origin: ProjectRelativePath | string,
+  ): Promise<Readonly<TraceabilityChainOutput>> {
+    const originValue = typeof origin === 'string' ? origin : origin.toString();
+
+    try {
+      const chain = await this.builder.build(origin);
+      const links = Object.freeze(chain.links.map(toLinkOutput));
+      const brokenLinks = Object.freeze(chain.getBrokenLinks().map(toLinkOutput));
+
+      return Object.freeze({
+        origin: chain.origin.toString(),
+        complete: chain.isComplete(),
+        links,
+        brokenLinks,
+      });
+    } catch (error) {
+      throw new TraceabilityChainBuildError(originValue, error);
+    }
+  }
+}

package/scripts/harness/traceability-model/application/usecases/resolve-legacy-story-id-usecase.ts

@@ -0,0 +1,34 @@
+/**
+ * @layer application
+ * @unit traceability-model
+ */
+
+import type { StoryIdAliasResolver } from '../../domain/services/story-id-alias-resolver.js';
+import { StoryId } from '../../domain/value-objects/story-id.js';
+
+type LegacyStoryIdResolver = Pick<StoryIdAliasResolver, 'isLegacyFormat' | 'resolve'>;
+
+export interface ResolveLegacyStoryIdUseCaseDeps {
+  readonly resolver: LegacyStoryIdResolver;
+}
+
+export class ResolveLegacyStoryIdUseCase {
+  private readonly resolver: LegacyStoryIdResolver;
+
+  constructor(deps: ResolveLegacyStoryIdUseCaseDeps) {
+    this.resolver = deps.resolver;
+  }
+
+  async execute(legacyId: string): Promise<StoryId | null> {
+    if (!this.resolver.isLegacyFormat(legacyId)) {
+      return null;
+    }
+
+    const resolved = await this.resolver.resolve(legacyId);
+    if (resolved === null) {
+      return null;
+    }
+
+    return StoryId.parse(resolved.value);
+  }
+}

package/scripts/harness/traceability-model/application/usecases/validate-design-story-annotations-usecase.ts

@@ -0,0 +1,83 @@
+/**
+ * @layer application
+ * @unit traceability-model
+ */
+
+import type { MetadataValidationOutput } from '../dto/metadata-validation-output.js';
+import type { DesignDocumentPort } from '../../domain/ports/design-document-port.js';
+import type { MetadataValidator } from '../../domain/services/metadata-validator.js';
+import type { MetadataValidationResult } from '../../domain/value-objects/metadata-validation-result.js';
+import type { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+
+type DesignStoryAnnotationsValidator = Pick<
+  MetadataValidator,
+  'validateDesignDocument'
+>;
+
+const toOutput = (
+  filePath: ProjectRelativePath,
+  result: MetadataValidationResult,
+): Readonly<MetadataValidationOutput> =>
+  Object.freeze({
+    filePath: filePath.toString(),
+    valid: result.valid,
+    errors: result.errors,
+    warnings: result.warnings,
+  });
+
+export class DesignDocumentReadApplicationError extends Error {
+  readonly filePath: string;
+  readonly cause: unknown;
+
+  constructor(filePath: string, cause: unknown) {
+    super(`design document read failed: ${filePath}`);
+    this.name = 'DesignDocumentReadApplicationError';
+    this.filePath = filePath;
+    this.cause = cause;
+  }
+}
+
+export interface ValidateDesignStoryAnnotationsUseCaseDeps {
+  readonly designDocumentPort: DesignDocumentPort;
+  readonly validator: DesignStoryAnnotationsValidator;
+}
+
+export class ValidateDesignStoryAnnotationsUseCase {
+  private readonly designDocumentPort: DesignDocumentPort;
+  private readonly validator: DesignStoryAnnotationsValidator;
+
+  constructor(deps: ValidateDesignStoryAnnotationsUseCaseDeps) {
+    this.designDocumentPort = deps.designDocumentPort;
+    this.validator = deps.validator;
+  }
+
+  async execute(
+    filePaths: readonly ProjectRelativePath[],
+  ): Promise<readonly Readonly<MetadataValidationOutput>[]> {
+    const results: Readonly<MetadataValidationOutput>[] = [];
+
+    for (const filePath of filePaths) {
+      try {
+        if (typeof this.designDocumentPort.readFrontmatterFlags !== 'function') {
+          throw new Error('readFrontmatterFlags is not implemented');
+        }
+        if (typeof this.designDocumentPort.readStoryAnnotations !== 'function') {
+          throw new Error('readStoryAnnotations is not implemented');
+        }
+
+        const flags = await this.designDocumentPort.readFrontmatterFlags(filePath);
+        const annotations = await this.designDocumentPort.readStoryAnnotations(filePath);
+        const result = await this.validator.validateDesignDocument({
+          documentPath: filePath,
+          annotations,
+          flags,
+        });
+        results.push(toOutput(filePath, result));
+      } catch (error) {
+        throw new DesignDocumentReadApplicationError(filePath.toString(), error);
+      }
+    }
+
+    return Object.freeze(results);
+  }
+}

package/scripts/harness/traceability-model/application/usecases/validate-implementation-metadata-usecase.ts

@@ -0,0 +1,76 @@
+/**
+ * @layer application
+ * @unit traceability-model
+ */
+
+import type { MetadataValidationOutput } from '../dto/metadata-validation-output.js';
+import type { MetadataReaderPort } from '../../domain/ports/metadata-reader-port.js';
+import type { MetadataValidator } from '../../domain/services/metadata-validator.js';
+import type { MetadataValidationResult } from '../../domain/value-objects/metadata-validation-result.js';
+import type { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+
+type ImplementationMetadataValidator = Pick<
+  MetadataValidator,
+  'validateImplementation'
+>;
+
+const toOutput = (
+  filePath: ProjectRelativePath,
+  result: MetadataValidationResult,
+): Readonly<MetadataValidationOutput> =>
+  Object.freeze({
+    filePath: filePath.toString(),
+    valid: result.valid,
+    errors: result.errors,
+    warnings: result.warnings,
+  });
+
+export class MetadataReadApplicationError extends Error {
+  readonly filePath: string;
+  readonly cause: unknown;
+
+  constructor(filePath: string, cause: unknown) {
+    super(`implementation metadata read failed: ${filePath}`);
+    this.name = 'MetadataReadApplicationError';
+    this.filePath = filePath;
+    this.cause = cause;
+  }
+}
+
+export interface ValidateImplementationMetadataUseCaseDeps {
+  readonly metadataReaderPort: MetadataReaderPort;
+  readonly validator: ImplementationMetadataValidator;
+}
+
+export class ValidateImplementationMetadataUseCase {
+  private readonly metadataReaderPort: MetadataReaderPort;
+  private readonly validator: ImplementationMetadataValidator;
+
+  constructor(deps: ValidateImplementationMetadataUseCaseDeps) {
+    this.metadataReaderPort = deps.metadataReaderPort;
+    this.validator = deps.validator;
+  }
+
+  async execute(
+    filePaths: readonly ProjectRelativePath[],
+  ): Promise<readonly Readonly<MetadataValidationOutput>[]> {
+    const results: Readonly<MetadataValidationOutput>[] = [];
+
+    for (const filePath of filePaths) {
+      let tags;
+      try {
+        tags = await this.metadataReaderPort.readImplementationTags(filePath);
+      } catch (error) {
+        throw new MetadataReadApplicationError(filePath.toString(), error);
+      }
+
+      const result = await this.validator.validateImplementation({
+        filePath,
+        tags,
+      });
+      results.push(toOutput(filePath, result));
+    }
+
+    return Object.freeze(results);
+  }
+}

package/scripts/harness/traceability-model/application/usecases/validate-test-story-metadata-usecase.ts

@@ -0,0 +1,76 @@
+/**
+ * @layer application
+ * @unit traceability-model
+ */
+
+import type { MetadataValidationOutput } from '../dto/metadata-validation-output.js';
+import type { MetadataReaderPort } from '../../domain/ports/metadata-reader-port.js';
+import type { MetadataValidator } from '../../domain/services/metadata-validator.js';
+import type { MetadataValidationResult } from '../../domain/value-objects/metadata-validation-result.js';
+import type { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+
+type TestStoryMetadataValidator = Pick<MetadataValidator, 'validateTest'>;
+
+const toOutput = (
+  filePath: ProjectRelativePath,
+  result: MetadataValidationResult,
+): Readonly<MetadataValidationOutput> =>
+  Object.freeze({
+    filePath: filePath.toString(),
+    valid: result.valid,
+    errors: result.errors,
+    warnings: result.warnings,
+  });
+
+export class MetadataReadApplicationError extends Error {
+  readonly filePath: string;
+  readonly cause: unknown;
+
+  constructor(filePath: string, cause: unknown) {
+    super(`test metadata read failed: ${filePath}`);
+    this.name = 'MetadataReadApplicationError';
+    this.filePath = filePath;
+    this.cause = cause;
+  }
+}
+
+export interface ValidateTestStoryMetadataUseCaseDeps {
+  readonly metadataReaderPort: MetadataReaderPort;
+  readonly validator: TestStoryMetadataValidator;
+}
+
+export class ValidateTestStoryMetadataUseCase {
+  private readonly metadataReaderPort: MetadataReaderPort;
+  private readonly validator: TestStoryMetadataValidator;
+
+  constructor(deps: ValidateTestStoryMetadataUseCaseDeps) {
+    this.metadataReaderPort = deps.metadataReaderPort;
+    this.validator = deps.validator;
+  }
+
+  async execute(
+    filePaths: readonly ProjectRelativePath[],
+  ): Promise<readonly Readonly<MetadataValidationOutput>[]> {
+    const results: Readonly<MetadataValidationOutput>[] = [];
+
+    for (const filePath of filePaths) {
+      let tags;
+      try {
+        if (typeof this.metadataReaderPort.readTestTags !== 'function') {
+          throw new Error('readTestTags is not implemented');
+        }
+        tags = await this.metadataReaderPort.readTestTags(filePath);
+      } catch (error) {
+        throw new MetadataReadApplicationError(filePath.toString(), error);
+      }
+
+      const result = await this.validator.validateTest({
+        filePath,
+        tags,
+      });
+      results.push(toOutput(filePath, result));
+    }
+
+    return Object.freeze(results);
+  }
+}

package/scripts/harness/traceability-model/application/usecases/verify-traceability-coverage-usecase.ts

@@ -0,0 +1,60 @@
+/**
+ * @layer application
+ * @unit traceability-model
+ */
+
+import type { TraceabilityCoverageOutput } from '../dto/traceability-coverage-output.js';
+import type { BuildTraceabilityChainUseCase } from './build-traceability-chain-usecase.js';
+import type { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+
+type TraceabilityChainExecutor = Pick<BuildTraceabilityChainUseCase, 'execute'>;
+
+export class TraceabilityCoverageApplicationError extends Error {
+  readonly cause: unknown;
+
+  constructor(cause: unknown) {
+    super('traceability coverage verification failed');
+    this.name = 'TraceabilityCoverageApplicationError';
+    this.cause = cause;
+  }
+}
+
+export interface VerifyTraceabilityCoverageUseCaseDeps {
+  readonly buildTraceabilityChainUseCase: TraceabilityChainExecutor;
+}
+
+export class VerifyTraceabilityCoverageUseCase {
+  private readonly buildTraceabilityChainUseCase: TraceabilityChainExecutor;
+
+  constructor(deps: VerifyTraceabilityCoverageUseCaseDeps) {
+    this.buildTraceabilityChainUseCase = deps.buildTraceabilityChainUseCase;
+  }
+
+  async execute(
+    filePaths: readonly ProjectRelativePath[],
+  ): Promise<Readonly<TraceabilityCoverageOutput>> {
+    try {
+      const results = [];
+      for (const filePath of filePaths) {
+        results.push(await this.buildTraceabilityChainUseCase.execute(filePath));
+      }
+
+      const completeChains = results.filter((result) => result.complete).length;
+      const incompleteChains = results.length - completeChains;
+      const brokenLinks = results.reduce(
+        (total, result) => total + result.brokenLinks.length,
+        0,
+      );
+
+      return Object.freeze({
+        totalFiles: filePaths.length,
+        completeChains,
+        incompleteChains,
+        brokenLinks,
+        results: Object.freeze(results),
+      });
+    } catch (error) {
+      throw new TraceabilityCoverageApplicationError(error);
+    }
+  }
+}

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

@@ -0,0 +1,61 @@
+/**
+ * @layer composition
+ * @unit traceability-model
+ *
+ * traceability-model ユニットの Composition Root。
+ * 全コンポーネントを生成・配線し、外部に公開するハンドラー群を返す。
+ */
+import { MarkdownStoryCatalogGateway } from './infrastructure/gateways/markdown-story-catalog-gateway.js';
+import { MarkdownUnitDefinitionGateway } from './infrastructure/gateways/markdown-unit-definition-gateway.js';
+import { FileSystemMetadataReader } from './infrastructure/gateways/file-system-metadata-reader.js';
+import { MarkdownDesignDocumentGateway } from './infrastructure/gateways/markdown-design-document-gateway.js';
+import { FileSystemInceptionPlanGateway } from './infrastructure/gateways/file-system-inception-plan-gateway.js';
+import { MetadataValidator } from './domain/services/metadata-validator.js';
+import { TraceabilityChainBuilder } from './domain/services/traceability-chain-builder.js';
+import { StoryIdAliasResolver } from './domain/services/story-id-alias-resolver.js';
+import { ValidateImplementationMetadataUseCase } from './application/usecases/validate-implementation-metadata-usecase.js';
+import { ValidateMetadataCommandHandler } from './presentation/cli/validate-metadata-command-handler.js';
+import { ProjectRelativePath } from './domain/value-objects/project-relative-path.js';
+
+export function createTraceabilityModelModule(rootDir: string) {
+  // Infrastructure gateways
+  const storyCatalog = new MarkdownStoryCatalogGateway({ rootDir });
+  const unitDefinition = new MarkdownUnitDefinitionGateway({ rootDir });
+  const metadataReader = new FileSystemMetadataReader({ rootDir });
+  const designDocument = new MarkdownDesignDocumentGateway({ rootDir });
+  const inceptionPlan = new FileSystemInceptionPlanGateway({ rootDir });
+
+  // Domain services
+  const metadataValidator = new MetadataValidator({
+    storyCatalogPort: storyCatalog,
+    unitDefinitionPort: unitDefinition,
+  });
+  const traceabilityChainBuilder = new TraceabilityChainBuilder({
+    metadataReaderPort: metadataReader,
+    unitDefinitionPort: unitDefinition,
+    designDocumentPort: designDocument,
+    storyCatalogPort: storyCatalog,
+    inceptionPlanPort: inceptionPlan,
+  });
+  const storyIdAliasResolver = new StoryIdAliasResolver(storyCatalog);
+
+  // Usecases
+  const validateImplementationMetadataUseCase =
+    new ValidateImplementationMetadataUseCase({
+      metadataReaderPort: metadataReader,
+      validator: metadataValidator,
+    });
+
+  // Presentation handlers
+  const validateMetadataCommandHandler = new ValidateMetadataCommandHandler({
+    validateImplementationMetadataUseCase,
+    createProjectRelativePath: (value: string) =>
+      ProjectRelativePath.create(value),
+  });
+
+  return {
+    validateMetadataCommandHandler,
+    // expose key services for cross-unit use
+    storyCatalog,
+  } as const;
+}

package/scripts/harness/traceability-model/domain/constants/layer-names.ts

@@ -0,0 +1,14 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ *
+ * traceability-modelで使用する正規レイヤー名
+ */
+export const LAYER_NAMES = Object.freeze([
+  'domain',
+  'application',
+  'infrastructure',
+  'presentation',
+] as const);
+
+export type LayerName = (typeof LAYER_NAMES)[number];

package/scripts/harness/traceability-model/domain/constants/metadata-tag-types.ts

@@ -0,0 +1,14 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ *
+ * traceability-modelで使用する正規メタデータタグ種別
+ */
+export const METADATA_TAG_TYPES = Object.freeze([
+  '@unit',
+  '@layer',
+  '@story-id',
+  '@story',
+] as const);
+
+export type MetadataTagType = (typeof METADATA_TAG_TYPES)[number];

package/scripts/harness/traceability-model/domain/constants/traceability-link-types.ts

@@ -0,0 +1,14 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ *
+ * 逆引きチェーンで使用するリンク種別
+ */
+export const TRACEABILITY_LINK_TYPES = Object.freeze([
+  'implementation-to-unit',
+  'unit-to-design',
+  'design-to-story',
+  'story-to-plan',
+] as const);
+
+export type TraceabilityLinkType = (typeof TRACEABILITY_LINK_TYPES)[number];

package/scripts/harness/traceability-model/domain/ports/design-document-port.ts

@@ -0,0 +1,24 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+import type { ProjectRelativePathLike } from '../value-objects/chain-link.js';
+import type { DesignDocumentFlags } from '../value-objects/design-document-flags.js';
+import type { StoryIdAnnotation } from '../value-objects/story-id-annotation.js';
+
+export interface DesignDocumentPort {
+  listByUnit?(unitName: string): Promise<readonly ProjectRelativePathLike[]>;
+  findConstructionDocuments?(
+    unitName: string,
+  ): Promise<readonly ProjectRelativePathLike[]>;
+  readStoryAnnotations?(
+    filePath: ProjectRelativePathLike,
+  ): Promise<readonly StoryIdAnnotation[]>;
+  readStoryIdAnnotations?(
+    filePath: ProjectRelativePathLike,
+  ): Promise<readonly StoryIdAnnotation[]>;
+  readFrontmatterFlags?(
+    filePath: ProjectRelativePathLike,
+  ): Promise<DesignDocumentFlags>;
+}

package/scripts/harness/traceability-model/domain/ports/inception-plan-port.ts

@@ -0,0 +1,16 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+import type { ProjectRelativePathLike } from '../value-objects/chain-link.js';
+import type { StoryIdLike } from '../value-objects/story-reference.js';
+
+export interface InceptionPlanPort {
+  exists?(unitName: string, storyId: StoryIdLike): Promise<boolean>;
+  findPlanRoot?(
+    unitName: string,
+    storyId: StoryIdLike,
+  ): Promise<ProjectRelativePathLike | null>;
+  findPlanByStoryId?(storyId: StoryIdLike): Promise<ProjectRelativePathLike | null>;
+}

package/scripts/harness/traceability-model/domain/ports/metadata-reader-port.ts

@@ -0,0 +1,22 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+import type { ProjectRelativePathLike } from '../value-objects/chain-link.js';
+
+export interface MetadataTagLike {
+  readonly type: string;
+  readonly value: string;
+  readonly lineNumber: number;
+  readonly filePath?: ProjectRelativePathLike;
+}
+
+export interface MetadataReaderPort {
+  readImplementationTags(
+    filePath: ProjectRelativePathLike,
+  ): Promise<readonly MetadataTagLike[]>;
+  readTestTags?(
+    filePath: ProjectRelativePathLike,
+  ): Promise<readonly MetadataTagLike[]>;
+}

package/scripts/harness/traceability-model/domain/ports/story-catalog-port.ts

@@ -0,0 +1,14 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+import type { StoryIdLike } from '../value-objects/story-reference.js';
+
+export interface StoryCatalogPort {
+  getAllStoryIds?(): Promise<readonly StoryIdLike[]>;
+  getAliasMap?(): Promise<ReadonlyMap<string, StoryIdLike>>;
+  getLegacyStoryIdAliases?(): Promise<Readonly<Record<string, string>>>;
+  exists?(storyId: StoryIdLike): Promise<boolean>;
+  hasStoryId?(storyId: StoryIdLike | { readonly value: string } | string): Promise<boolean>;
+}

package/scripts/harness/traceability-model/domain/ports/unit-definition-port.ts

@@ -0,0 +1,14 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+import type { ProjectRelativePathLike } from '../value-objects/chain-link.js';
+
+export interface UnitDefinitionPort {
+  getAllUnitNames?(): Promise<readonly string[]>;
+  exists?(unitName: string): Promise<boolean>;
+  hasUnit?(unitName: string): Promise<boolean>;
+  findConstructionRoot?(unitName: string): Promise<ProjectRelativePathLike | null>;
+  resolveConstructionRoot?(unitName: string): Promise<ProjectRelativePathLike | null>;
+}