phasegate 0.15.0

package/scripts/harness/adr-foundation/application/usecases/seed-initial-adrs-use-case.ts

@@ -0,0 +1,84 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import { ADR } from '../../domain/aggregates/adr.js';
+import type { AdrDocumentParserPort } from '../../domain/ports/adr-document-parser-port.js';
+import type { AdrRepositoryPort } from '../../domain/ports/adr-repository-port.js';
+import { AdrValidationService } from '../../domain/services/adr-validation-service.js';
+import { AdrId } from '../../domain/value-objects/adr-id.js';
+import {
+  DuplicateAdrIdApplicationError,
+  SeedAdrDefinitionCountError,
+} from '../dto/application-errors.js';
+import type { SeedAdrDefinition } from '../dto/seed-adr-definition.js';
+
+export interface SeedInitialAdrsInput {
+  readonly definitions: SeedAdrDefinition[];
+  readonly overwrite?: boolean;
+}
+
+export interface SeedInitialAdrsOutput {
+  readonly created: readonly string[];
+  readonly skipped: readonly string[];
+}
+
+export class SeedInitialAdrsUseCase {
+  constructor(
+    private readonly adrRepository: AdrRepositoryPort,
+    private readonly documentParser: AdrDocumentParserPort,
+  ) {}
+
+  async execute(input: SeedInitialAdrsInput): Promise<Readonly<SeedInitialAdrsOutput>> {
+    if (input.definitions.length !== 11) {
+      throw new SeedAdrDefinitionCountError(input.definitions.length);
+    }
+
+    const created: string[] = [];
+    const skipped: string[] = [];
+
+    for (const [index, definition] of input.definitions.entries()) {
+      const adrId = AdrId.create(String(index + 1).padStart(3, '0'));
+      const adrRef = adrId.toAdrRef();
+
+      if (created.includes(adrRef) || skipped.includes(adrRef)) {
+        throw new DuplicateAdrIdApplicationError(adrRef);
+      }
+
+      const adr = ADR.create(
+        {
+          adr_id: adrId.value,
+          title: definition.title,
+          status: definition.status,
+          date: definition.date,
+          archgate: definition.archgate
+            ? {
+                adr_id: adrId.value,
+                enforced_by: definition.archgate.enforcedBy.map((entry) => ({
+                  validator_id: entry.validatorId,
+                  error_code: entry.errorCode,
+                })),
+              }
+            : undefined,
+        },
+        definition.body,
+        new AdrValidationService(),
+      );
+
+      const exists = await this.adrRepository.exists(adrId);
+      if (exists && input.overwrite !== true) {
+        skipped.push(adrRef);
+        continue;
+      }
+
+      this.documentParser.serializeDocument(adr);
+      await this.adrRepository.save(adr);
+      created.push(adrRef);
+    }
+
+    return Object.freeze({
+      created: Object.freeze(created),
+      skipped: Object.freeze(skipped),
+    });
+  }
+}

package/scripts/harness/adr-foundation/application/usecases/validate-adr-frontmatter-use-case.ts

@@ -0,0 +1,86 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type { AdrRepositoryPort } from '../../domain/ports/adr-repository-port.js';
+import { AdrValidationService } from '../../domain/services/adr-validation-service.js';
+import { AdrId } from '../../domain/value-objects/adr-id.js';
+import type {
+  AdrValidationResultDto,
+  AdrValidationViolationDto,
+} from '../dto/adr-validation-result-dto.js';
+import { AdrNotFoundApplicationError } from '../dto/application-errors.js';
+import { toHarnessErrors } from '../mappers/adr-validation-to-harness-error-mapper.js';
+
+export interface ValidateAdrFrontmatterInput {
+  readonly adrRef: string;
+}
+
+export class ValidateAdrFrontmatterUseCase {
+  constructor(private readonly adrRepository: AdrRepositoryPort) {}
+
+  async execute(
+    input: ValidateAdrFrontmatterInput,
+  ): Promise<Readonly<AdrValidationResultDto>> {
+    const adr = await this.adrRepository.findByRef(input.adrRef);
+    if (!adr) {
+      throw new AdrNotFoundApplicationError(input.adrRef);
+    }
+
+    const validationService = new AdrValidationService();
+    const violations: AdrValidationViolationDto[] = [];
+
+    try {
+      validationService.validateFrontmatter(adr.getFrontmatter());
+    } catch (error) {
+      violations.push(this.createViolation('frontmatter', 'ADR-FRONTMATTER-INVALID', error));
+    }
+
+    try {
+      validationService.validateBody(adr.getBody());
+    } catch (error) {
+      violations.push(this.createViolation('body', 'ADR-BODY-SECTION-REQUIRED', error));
+    }
+
+    const supersededBy = adr.getFrontmatter().superseded_by;
+    if (adr.getStatus().isSuperseded()) {
+      if (!supersededBy) {
+        violations.push({
+          field: 'superseded_by',
+          code: 'ADR-SUPERSEDED-BY-REQUIRED',
+          message: 'Superseded の ADR には superseded_by が必須です',
+        });
+      } else if (!(await this.adrRepository.exists(AdrId.fromAdrRef(supersededBy)))) {
+        violations.push({
+          field: 'superseded_by',
+          code: 'ADR-SUPERSEDED-TARGET-NOT-FOUND',
+          message: 'superseded_by の参照先ADRが存在しません',
+        });
+      }
+    }
+
+    const baseResult = Object.freeze({
+      adrRef: adr.toAdrRef(),
+      valid: violations.length === 0,
+      violations: Object.freeze(violations),
+      harnessErrors: Object.freeze([]),
+    });
+
+    return Object.freeze({
+      ...baseResult,
+      harnessErrors: toHarnessErrors(baseResult),
+    });
+  }
+
+  private createViolation(
+    field: string,
+    code: string,
+    error: unknown,
+  ): AdrValidationViolationDto {
+    return Object.freeze({
+      field,
+      code,
+      message: error instanceof Error ? error.message : 'ADR validation failed',
+    });
+  }
+}

package/scripts/harness/adr-foundation/application/usecases/validate-all-adrs-use-case.ts

@@ -0,0 +1,47 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type { AdrRepositoryPort } from '../../domain/ports/adr-repository-port.js';
+import type {
+  AdrHarnessError,
+  AdrValidationResultDto,
+} from '../dto/adr-validation-result-dto.js';
+import { ValidateAdrFrontmatterUseCase } from './validate-adr-frontmatter-use-case.js';
+
+export interface ValidateAllAdrsInput {
+  readonly failFast?: boolean;
+}
+
+export interface ValidateAllAdrsOutput {
+  readonly valid: boolean;
+  readonly results: readonly AdrValidationResultDto[];
+  readonly errors: readonly AdrHarnessError[];
+}
+
+export class ValidateAllAdrsUseCase {
+  constructor(private readonly adrRepository: AdrRepositoryPort) {}
+
+  async execute(input: ValidateAllAdrsInput): Promise<Readonly<ValidateAllAdrsOutput>> {
+    const adrs = await this.adrRepository.findAll();
+    const validator = new ValidateAdrFrontmatterUseCase(this.adrRepository);
+    const results: AdrValidationResultDto[] = [];
+    const errors: AdrHarnessError[] = [];
+
+    for (const adr of adrs) {
+      const result = await validator.execute({ adrRef: adr.toAdrRef() });
+      results.push(result);
+      errors.push(...result.harnessErrors);
+
+      if (input.failFast === true && result.valid === false) {
+        break;
+      }
+    }
+
+    return Object.freeze({
+      valid: errors.length === 0,
+      results: Object.freeze(results),
+      errors: Object.freeze(errors),
+    });
+  }
+}

package/scripts/harness/adr-foundation/composition-root.ts

@@ -0,0 +1,47 @@
+/**
+ * @layer composition
+ * @unit adr-foundation
+ *
+ * adr-foundation ユニットの Composition Root。
+ * 全コンポーネントを生成・配線し、外部に公開するハンドラー群を返す。
+ */
+import { RegexAdrFrontmatterParser } from './infrastructure/parsers/regex-adr-frontmatter-parser.js';
+import { AdrMarkdownDocumentParser } from './infrastructure/parsers/adr-markdown-document-parser.js';
+import { FileSystemAdrRepository } from './infrastructure/repositories/file-system-adr-repository.js';
+import { ListAdrsUseCase } from './application/usecases/list-adrs-use-case.js';
+import { ValidateAllAdrsUseCase } from './application/usecases/validate-all-adrs-use-case.js';
+import { ValidateAdrFrontmatterUseCase } from './application/usecases/validate-adr-frontmatter-use-case.js';
+import { ListAdrsCommandHandler } from './presentation/cli/list-adrs-command-handler.js';
+import { ValidateAdrCommandHandler } from './presentation/cli/validate-adr-command-handler.js';
+
+export function createAdrFoundationModule(rootDir: string) {
+  // Infrastructure — parsers
+  const frontmatterParser = new RegexAdrFrontmatterParser();
+  const documentParser = new AdrMarkdownDocumentParser(frontmatterParser);
+
+  // Infrastructure — repositories
+  const adrRepository = new FileSystemAdrRepository(rootDir, documentParser);
+
+  // Usecases
+  const listAdrsUseCase = new ListAdrsUseCase(adrRepository);
+  const validateAllAdrsUseCase = new ValidateAllAdrsUseCase(adrRepository);
+  const validateAdrFrontmatterUseCase = new ValidateAdrFrontmatterUseCase(
+    adrRepository,
+  );
+
+  // Presentation handlers
+  const listAdrsCommandHandler = new ListAdrsCommandHandler({
+    listAdrsUseCase,
+  });
+  const validateAdrCommandHandler = new ValidateAdrCommandHandler({
+    validateAllAdrsUseCase,
+    validateAdrFrontmatterUseCase,
+  });
+
+  return {
+    listAdrsCommandHandler,
+    validateAdrCommandHandler,
+    // expose repository for cross-unit use
+    adrRepository,
+  } as const;
+}

package/scripts/harness/adr-foundation/domain/aggregates/adr.ts

@@ -0,0 +1,177 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+import { AdrValidationService } from '../services/adr-validation-service.js';
+import { AdrBody, type AdrBodyProps } from '../value-objects/adr-body.js';
+import {
+  AdrFrontmatter,
+  InvalidAdrStatusTransitionError,
+  type AdrFrontmatterProps,
+} from '../value-objects/adr-frontmatter.js';
+import { AdrId } from '../value-objects/adr-id.js';
+import { AdrStatus } from '../value-objects/adr-status.js';
+import {
+  ArchgateMapping,
+  type ArchgateMappingProps,
+} from '../value-objects/archgate-mapping.js';
+import { SupersededByRef } from '../value-objects/superseded-by-ref.js';
+
+export { InvalidAdrStatusTransitionError } from '../value-objects/adr-frontmatter.js';
+
+export class MalformedAdrDocumentError extends Error {
+  constructor(cause: unknown) {
+    const message = cause instanceof Error ? cause.message : 'Unknown ADR document error';
+    super(`ADR文書を再構築できません: ${message}`);
+    this.name = 'MalformedAdrDocumentError';
+  }
+}
+
+export class SelfSupersedeNotAllowedError extends Error {
+  constructor(adrRef: string) {
+    super(`自分自身を superseded_by に指定できません: ${adrRef}`);
+    this.name = 'SelfSupersedeNotAllowedError';
+  }
+}
+
+type AdrDocument = Readonly<{
+  frontmatter: AdrFrontmatter | AdrFrontmatterProps;
+  body: AdrBody | AdrBodyProps;
+}>;
+
+export class ADR {
+  readonly id: AdrId;
+  private readonly frontmatter: AdrFrontmatter;
+  private readonly body: AdrBody;
+  private readonly validationService: AdrValidationService;
+
+  private constructor(
+    frontmatter: AdrFrontmatter,
+    body: AdrBody,
+    validationService: AdrValidationService,
+  ) {
+    this.id = frontmatter.adrId;
+    this.frontmatter = frontmatter;
+    this.body = body;
+    this.validationService = validationService;
+    Object.freeze(this);
+  }
+
+  static create(
+    frontmatter: AdrFrontmatter | AdrFrontmatterProps,
+    body: AdrBody | AdrBodyProps,
+    validationService: AdrValidationService,
+  ): ADR {
+    const resolvedFrontmatter =
+      frontmatter instanceof AdrFrontmatter ? frontmatter : AdrFrontmatter.create(frontmatter);
+    const resolvedBody = body instanceof AdrBody ? body : AdrBody.create(body);
+
+    validationService.validateFrontmatter(resolvedFrontmatter);
+    validationService.validateBody(resolvedBody);
+
+    return new ADR(resolvedFrontmatter, resolvedBody, validationService);
+  }
+
+  static reconstitute(
+    document: AdrDocument,
+    validationService: AdrValidationService,
+  ): ADR;
+  static reconstitute(
+    frontmatter: AdrFrontmatter | AdrFrontmatterProps,
+    body: AdrBody | AdrBodyProps,
+    validationService: AdrValidationService,
+  ): ADR;
+  static reconstitute(
+    frontmatterOrDocument: AdrDocument | AdrFrontmatter | AdrFrontmatterProps,
+    bodyOrService: AdrValidationService | AdrBody | AdrBodyProps,
+    maybeValidationService?: AdrValidationService,
+  ): ADR {
+    try {
+      if (maybeValidationService) {
+        return ADR.create(
+          frontmatterOrDocument as AdrFrontmatter | AdrFrontmatterProps,
+          bodyOrService as AdrBody | AdrBodyProps,
+          maybeValidationService,
+        );
+      }
+
+      const document = frontmatterOrDocument as AdrDocument;
+      return ADR.create(document.frontmatter, document.body, bodyOrService as AdrValidationService);
+    } catch (error) {
+      throw new MalformedAdrDocumentError(error);
+    }
+  }
+
+  approve(): ADR {
+    return this.withFrontmatter(this.frontmatter.transitionStatus(AdrStatus.accepted()));
+  }
+
+  deprecate(): ADR {
+    const nextFrontmatter = this.frontmatter
+      .transitionStatus(AdrStatus.deprecated())
+      .withSupersededBy(undefined);
+
+    return this.withFrontmatter(nextFrontmatter);
+  }
+
+  supersede(newAdrId: AdrId): ADR {
+    if (this.id.equals(newAdrId)) {
+      throw new SelfSupersedeNotAllowedError(this.id.toAdrRef());
+    }
+
+    const nextFrontmatter = this.frontmatter
+      .withSupersededBy(SupersededByRef.create(newAdrId))
+      .transitionStatus(AdrStatus.superseded());
+
+    return this.withFrontmatter(nextFrontmatter);
+  }
+
+  repropose(): ADR {
+    const nextFrontmatter = this.frontmatter
+      .transitionStatus(AdrStatus.proposed())
+      .withSupersededBy(undefined);
+
+    return this.withFrontmatter(nextFrontmatter);
+  }
+
+  updateBody(newBody: AdrBody | AdrBodyProps): ADR {
+    this.validationService.validateBody(newBody);
+    const body = newBody instanceof AdrBody ? newBody : AdrBody.create(newBody);
+    return new ADR(this.frontmatter, body, this.validationService);
+  }
+
+  replaceArchgate(mapping?: ArchgateMapping | ArchgateMappingProps): ADR {
+    if (!mapping) {
+      return this.withFrontmatter(this.frontmatter.withArchgate(undefined));
+    }
+
+    this.validationService.validateArchgate(mapping);
+    const nextMapping = mapping instanceof ArchgateMapping ? mapping : ArchgateMapping.create(mapping);
+    return this.withFrontmatter(this.frontmatter.withArchgate(nextMapping));
+  }
+
+  getStatus(): AdrStatus {
+    return this.frontmatter.status;
+  }
+
+  getArchgate(): ArchgateMapping | undefined {
+    return this.frontmatter.archgate;
+  }
+
+  getFrontmatter(): AdrFrontmatter {
+    return this.frontmatter;
+  }
+
+  getBody(): AdrBody {
+    return this.body;
+  }
+
+  toAdrRef(): string {
+    return this.id.toAdrRef();
+  }
+
+  private withFrontmatter(frontmatter: AdrFrontmatter): ADR {
+    this.validationService.validateFrontmatter(frontmatter);
+    return new ADR(frontmatter, this.body, this.validationService);
+  }
+}

package/scripts/harness/adr-foundation/domain/ports/adr-document-parser-port.ts

@@ -0,0 +1,11 @@
+import type { ADR } from '../aggregates/adr.js';
+import type { AdrBody } from '../value-objects/adr-body.js';
+import type { AdrFrontmatter } from '../value-objects/adr-frontmatter.js';
+
+export interface AdrDocumentParserPort {
+  parseDocument(rawMarkdown: string): {
+    frontmatter: AdrFrontmatter;
+    body: AdrBody;
+  };
+  serializeDocument(adr: ADR): string;
+}

package/scripts/harness/adr-foundation/domain/ports/adr-frontmatter-parser-port.ts

@@ -0,0 +1,6 @@
+import type { AdrFrontmatter } from '../value-objects/adr-frontmatter.js';
+
+export interface AdrFrontmatterParserPort {
+  parseFrontmatter(raw: string): AdrFrontmatter;
+  serializeFrontmatter(frontmatter: AdrFrontmatter): string;
+}

package/scripts/harness/adr-foundation/domain/ports/adr-repository-port.ts

@@ -0,0 +1,15 @@
+import type { ADR } from '../aggregates/adr.js';
+import type { AdrId } from '../value-objects/adr-id.js';
+import type { AdrStatus } from '../value-objects/adr-status.js';
+
+export interface AdrRepositoryPort {
+  findById(id: AdrId): Promise<ADR | null>;
+  findByRef(adrRef: string): Promise<ADR | null>;
+  findAll(filters?: {
+    statuses?: AdrStatus[];
+    includeTemplate?: boolean;
+  }): Promise<ADR[]>;
+  save(adr: ADR): Promise<void>;
+  exists(id: AdrId): Promise<boolean>;
+  nextId(): Promise<AdrId>;
+}

package/scripts/harness/adr-foundation/domain/services/adr-validation-service.ts

@@ -0,0 +1,27 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+import { AdrBody, type AdrBodyProps } from '../value-objects/adr-body.js';
+import {
+  AdrFrontmatter,
+  type AdrFrontmatterProps,
+} from '../value-objects/adr-frontmatter.js';
+import {
+  ArchgateMapping,
+  type ArchgateMappingProps,
+} from '../value-objects/archgate-mapping.js';
+
+export class AdrValidationService {
+  validateFrontmatter(frontmatter: AdrFrontmatter | AdrFrontmatterProps): void {
+    void (frontmatter instanceof AdrFrontmatter ? frontmatter : AdrFrontmatter.create(frontmatter));
+  }
+
+  validateBody(body: AdrBody | AdrBodyProps): void {
+    void (body instanceof AdrBody ? body : AdrBody.create(body));
+  }
+
+  validateArchgate(mapping: ArchgateMapping | ArchgateMappingProps): void {
+    void (mapping instanceof ArchgateMapping ? mapping : ArchgateMapping.create(mapping));
+  }
+}

package/scripts/harness/adr-foundation/domain/value-objects/adr-body.ts

@@ -0,0 +1,90 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+export type AdrBodyProps = Readonly<{
+  context?: string;
+  decision?: string;
+  consequences?: string;
+  alternatives?: string | undefined;
+}>;
+
+export class AdrBodySectionRequiredError extends Error {
+  constructor(sectionName: string) {
+    super(`ADR本文の必須セクションが不足しています: ${sectionName}`);
+    this.name = 'AdrBodySectionRequiredError';
+  }
+}
+
+export class AdrBody {
+  readonly context: string;
+  readonly decision: string;
+  readonly consequences: string;
+  readonly alternatives: string | undefined;
+
+  private constructor(
+    context: string,
+    decision: string,
+    consequences: string,
+    alternatives?: string,
+  ) {
+    this.context = context;
+    this.decision = decision;
+    this.consequences = consequences;
+    this.alternatives = alternatives;
+    Object.freeze(this);
+  }
+
+  static create(props: AdrBodyProps): AdrBody {
+    const context = props.context?.trim() ?? '';
+    const decision = props.decision?.trim() ?? '';
+    const consequences = props.consequences?.trim() ?? '';
+    const alternatives =
+      props.alternatives === undefined ? undefined : props.alternatives.trim();
+
+    if (context.length === 0) {
+      throw new AdrBodySectionRequiredError('Context');
+    }
+
+    if (decision.length === 0) {
+      throw new AdrBodySectionRequiredError('Decision');
+    }
+
+    if (consequences.length === 0) {
+      throw new AdrBodySectionRequiredError('Consequences');
+    }
+
+    if (props.alternatives !== undefined && alternatives?.length === 0) {
+      throw new AdrBodySectionRequiredError('Alternatives');
+    }
+
+    return new AdrBody(context, decision, consequences, alternatives);
+  }
+
+  withAlternatives(alternatives?: string): AdrBody {
+    return AdrBody.create({
+      context: this.context,
+      decision: this.decision,
+      consequences: this.consequences,
+      alternatives,
+    });
+  }
+
+  toSectionMap(): Record<'Context' | 'Decision' | 'Consequences' | 'Alternatives', string | undefined> {
+    return {
+      Context: this.context,
+      Decision: this.decision,
+      Consequences: this.consequences,
+      Alternatives: this.alternatives,
+    };
+  }
+
+  equals(other: AdrBody): boolean {
+    return (
+      this.context === other.context &&
+      this.decision === other.decision &&
+      this.consequences === other.consequences &&
+      this.alternatives === other.alternatives
+    );
+  }
+}

package/scripts/harness/adr-foundation/domain/value-objects/adr-file-path.ts

@@ -0,0 +1,60 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+import { AdrId } from './adr-id.js';
+
+const ADR_FILE_PATH_PATTERN = /^docs\/ADR\/[0-9]{3}-[a-z0-9-]+\.md$/;
+
+export class InvalidAdrFilePathError extends Error {
+  constructor(value: string) {
+    super(`ADRファイルパスは docs/ADR/{NNN}-{slug}.md 形式で指定してください: ${value}`);
+    this.name = 'InvalidAdrFilePathError';
+  }
+}
+
+export class AdrFilePath {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(path: string): AdrFilePath {
+    if (path === 'docs/ADR/template.md') {
+      throw new InvalidAdrFilePathError(path);
+    }
+
+    if (!ADR_FILE_PATH_PATTERN.test(path)) {
+      throw new InvalidAdrFilePathError(path);
+    }
+
+    return new AdrFilePath(path);
+  }
+
+  static fromAdr(adrId: AdrId, title: string): AdrFilePath {
+    const slug = title
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .replace(/-{2,}/g, '-');
+
+    const normalizedSlug = slug.length > 0 ? slug : 'untitled';
+    return AdrFilePath.create(`docs/ADR/${adrId.value}-${normalizedSlug}.md`);
+  }
+
+  getAdrId(): AdrId {
+    const match = /^docs\/ADR\/(?<id>[0-9]{3})-/.exec(this.value);
+    return AdrId.create(match?.groups?.id ?? '');
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  equals(other: AdrFilePath): boolean {
+    return this.value === other.value;
+  }
+}