phasegate 0.15.0

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

@@ -0,0 +1,236 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+import { AdrId } from './adr-id.js';
+import { AdrStatus, type InvalidAdrStatusError } from './adr-status.js';
+import { ArchgateMapping, type ArchgateMappingProps } from './archgate-mapping.js';
+import { SupersededByRef } from './superseded-by-ref.js';
+
+const DATE_PATTERN = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
+
+export type AdrFrontmatterProps = Readonly<{
+  adrId?: AdrId | string;
+  adr_id?: AdrId | string;
+  title?: string;
+  status?: AdrStatus | string;
+  date?: string;
+  archgate?: ArchgateMapping | ArchgateMappingProps;
+  supersededBy?: SupersededByRef | string;
+  superseded_by?: SupersededByRef | string;
+}>;
+
+export class AdrValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AdrValidationError';
+  }
+}
+
+export class SupersededByRequiredError extends Error {
+  constructor() {
+    super('Superseded の ADR には superseded_by が必須です');
+    this.name = 'SupersededByRequiredError';
+  }
+}
+
+export class InvalidAdrStatusTransitionError extends Error {
+  constructor(from: string, to: string) {
+    super(`ADR status を ${from} から ${to} へ遷移できません`);
+    this.name = 'InvalidAdrStatusTransitionError';
+  }
+}
+
+type InstantiateArgs = Readonly<{
+  adrId: AdrId;
+  title: string;
+  status: AdrStatus;
+  date: string;
+  archgate?: ArchgateMapping;
+  supersededBy?: SupersededByRef;
+  normalizeForStatus: boolean;
+}>;
+
+export class AdrFrontmatter {
+  readonly adrId: AdrId;
+  readonly adr_id: string;
+  readonly title: string;
+  readonly status: AdrStatus;
+  readonly date: string;
+  readonly archgate: ArchgateMapping | undefined;
+  readonly supersededBy: SupersededByRef | undefined;
+  readonly superseded_by: string | undefined;
+
+  private constructor(
+    adrId: AdrId,
+    title: string,
+    status: AdrStatus,
+    date: string,
+    archgate?: ArchgateMapping,
+    supersededBy?: SupersededByRef,
+  ) {
+    this.adrId = adrId;
+    this.adr_id = adrId.value;
+    this.title = title;
+    this.status = status;
+    this.date = date;
+    this.archgate = archgate;
+    this.supersededBy = supersededBy;
+    this.superseded_by = supersededBy?.toAdrRef();
+    Object.freeze(this);
+  }
+
+  static create(props: AdrFrontmatterProps): AdrFrontmatter {
+    return AdrFrontmatter.instantiate({
+      adrId: AdrFrontmatter.parseAdrId(props.adrId ?? props.adr_id),
+      title: props.title ?? '',
+      status: AdrFrontmatter.parseStatus(props.status),
+      date: props.date ?? '',
+      archgate: AdrFrontmatter.parseArchgate(props.archgate),
+      supersededBy: AdrFrontmatter.parseSupersededBy(props.supersededBy ?? props.superseded_by),
+      normalizeForStatus: true,
+    });
+  }
+
+  private static instantiate(args: InstantiateArgs): AdrFrontmatter {
+    const title = args.title.trim();
+    if (title.length === 0) {
+      throw new AdrValidationError('title は必須です');
+    }
+
+    if (!DATE_PATTERN.test(args.date)) {
+      throw new AdrValidationError(`date は YYYY-MM-DD 形式で指定してください: ${args.date}`);
+    }
+
+    if (args.archgate && !args.archgate.adrId.equals(args.adrId)) {
+      throw new AdrValidationError('archgate.adr_id は frontmatter.adr_id と一致する必要があります');
+    }
+
+    let supersededBy = args.supersededBy;
+    if (args.normalizeForStatus && !args.status.isSuperseded()) {
+      supersededBy = undefined;
+    }
+
+    if (args.status.isSuperseded() && !supersededBy) {
+      throw new SupersededByRequiredError();
+    }
+
+    return new AdrFrontmatter(
+      args.adrId,
+      title,
+      args.status,
+      args.date,
+      args.archgate,
+      supersededBy,
+    );
+  }
+
+  private static parseAdrId(value: AdrId | string | undefined): AdrId {
+    if (value instanceof AdrId) {
+      return value;
+    }
+
+    return AdrId.create(String(value ?? ''));
+  }
+
+  private static parseStatus(value: AdrStatus | string | undefined): AdrStatus {
+    if (value instanceof AdrStatus) {
+      return value;
+    }
+
+    return AdrStatus.create(String(value ?? ''));
+  }
+
+  private static parseArchgate(value: ArchgateMapping | ArchgateMappingProps | undefined): ArchgateMapping | undefined {
+    if (!value) {
+      return undefined;
+    }
+
+    return value instanceof ArchgateMapping ? value : ArchgateMapping.create(value);
+  }
+
+  private static parseSupersededBy(value: SupersededByRef | string | undefined): SupersededByRef | undefined {
+    if (!value) {
+      return undefined;
+    }
+
+    if (value instanceof SupersededByRef) {
+      return value;
+    }
+
+    return SupersededByRef.create(AdrId.create(value));
+  }
+
+  transitionStatus(nextStatus: AdrStatus): AdrFrontmatter {
+    if (!this.status.canTransitionTo(nextStatus)) {
+      throw new InvalidAdrStatusTransitionError(this.status.value, nextStatus.value);
+    }
+
+    return AdrFrontmatter.instantiate({
+      adrId: this.adrId,
+      title: this.title,
+      status: nextStatus,
+      date: this.date,
+      archgate: this.archgate,
+      supersededBy: this.supersededBy,
+      normalizeForStatus: true,
+    });
+  }
+
+  withSupersededBy(ref?: SupersededByRef): AdrFrontmatter {
+    return AdrFrontmatter.instantiate({
+      adrId: this.adrId,
+      title: this.title,
+      status: this.status,
+      date: this.date,
+      archgate: this.archgate,
+      supersededBy: ref,
+      normalizeForStatus: false,
+    });
+  }
+
+  withArchgate(mapping?: ArchgateMapping): AdrFrontmatter {
+    return AdrFrontmatter.instantiate({
+      adrId: this.adrId,
+      title: this.title,
+      status: this.status,
+      date: this.date,
+      archgate: mapping,
+      supersededBy: this.supersededBy,
+      normalizeForStatus: true,
+    });
+  }
+
+  toPrimitives(): {
+    adr_id: string;
+    title: string;
+    status: string;
+    date: string;
+    superseded_by?: string;
+    archgate?: { enforced_by: Array<{ validator_id: string; error_code: string }> };
+  } {
+    const primitives: {
+      adr_id: string;
+      title: string;
+      status: string;
+      date: string;
+      superseded_by?: string;
+      archgate?: { enforced_by: Array<{ validator_id: string; error_code: string }> };
+    } = {
+      adr_id: this.adrId.value,
+      title: this.title,
+      status: this.status.value,
+      date: this.date,
+    };
+
+    if (this.status.isSuperseded() && this.supersededBy) {
+      primitives.superseded_by = this.supersededBy.toAdrRef();
+    }
+
+    if (this.archgate) {
+      primitives.archgate = this.archgate.toPrimitives();
+    }
+
+    return primitives;
+  }
+}

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

@@ -0,0 +1,57 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+const ADR_ID_PATTERN = /^(?:ADR-)?(?<id>[0-9]{3})$/;
+
+export class InvalidAdrIdError extends Error {
+  constructor(value: string) {
+    super(`ADR IDは001以上の3桁数値またはADR-001形式で指定してください: ${value}`);
+    this.name = 'InvalidAdrIdError';
+  }
+}
+
+export class AdrId {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(raw: string): AdrId {
+    const normalizedValue = raw.trim();
+    const match = ADR_ID_PATTERN.exec(normalizedValue);
+
+    if (!match?.groups?.id) {
+      throw new InvalidAdrIdError(raw);
+    }
+
+    const value = match.groups.id;
+    if (Number(value) < 1) {
+      throw new InvalidAdrIdError(raw);
+    }
+
+    return new AdrId(value);
+  }
+
+  static fromAdrRef(adrRef: string): AdrId {
+    return AdrId.create(adrRef);
+  }
+
+  toNumber(): number {
+    return Number(this.value);
+  }
+
+  toAdrRef(): string {
+    return `ADR-${this.value}`;
+  }
+
+  equals(other: AdrId): boolean {
+    return this.value === other.value;
+  }
+
+  compare(other: AdrId): number {
+    return this.toNumber() - other.toNumber();
+  }
+}

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

@@ -0,0 +1,65 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+const ALLOWED_STATUSES = ['Proposed', 'Accepted', 'Deprecated', 'Superseded'] as const;
+type AdrStatusValue = (typeof ALLOWED_STATUSES)[number];
+
+const TRANSITIONS: Readonly<Record<AdrStatusValue, readonly AdrStatusValue[]>> = Object.freeze({
+  Proposed: Object.freeze(['Accepted', 'Deprecated']),
+  Accepted: Object.freeze(['Deprecated', 'Superseded']),
+  Deprecated: Object.freeze(['Proposed']),
+  Superseded: Object.freeze([]),
+});
+
+export class InvalidAdrStatusError extends Error {
+  constructor(value: string) {
+    super(`ADR statusはProposed/Accepted/Deprecated/Supersededのいずれかで指定してください: ${value}`);
+    this.name = 'InvalidAdrStatusError';
+  }
+}
+
+export class AdrStatus {
+  readonly value: AdrStatusValue;
+
+  private constructor(value: AdrStatusValue) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(raw: string): AdrStatus {
+    if (!ALLOWED_STATUSES.includes(raw as AdrStatusValue)) {
+      throw new InvalidAdrStatusError(raw);
+    }
+
+    return new AdrStatus(raw as AdrStatusValue);
+  }
+
+  static proposed(): AdrStatus {
+    return AdrStatus.create('Proposed');
+  }
+
+  static accepted(): AdrStatus {
+    return AdrStatus.create('Accepted');
+  }
+
+  static deprecated(): AdrStatus {
+    return AdrStatus.create('Deprecated');
+  }
+
+  static superseded(): AdrStatus {
+    return AdrStatus.create('Superseded');
+  }
+
+  canTransitionTo(target: AdrStatus): boolean {
+    return TRANSITIONS[this.value].includes(target.value);
+  }
+
+  equals(other: AdrStatus): boolean {
+    return this.value === other.value;
+  }
+
+  isSuperseded(): boolean {
+    return this.value === 'Superseded';
+  }
+}

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

@@ -0,0 +1,69 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+const VALIDATOR_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ERROR_CODE_PATTERN = /^L[0-4]-\d{3,}$/;
+
+export type ArchgateEntryProps = Readonly<{
+  validatorId?: string;
+  validator_id?: string;
+  errorCode?: string;
+  error_code?: string;
+}>;
+
+export class InvalidArchgateValidatorIdError extends Error {
+  constructor(value: string) {
+    super(`validator_idはkebab-caseで指定してください: ${value}`);
+    this.name = 'InvalidArchgateValidatorIdError';
+  }
+}
+
+export class InvalidArchgateErrorCodeError extends Error {
+  constructor(value: string) {
+    super(`error_codeはL0-L4レイヤーのHarness Error形式で指定してください: ${value}`);
+    this.name = 'InvalidArchgateErrorCodeError';
+  }
+}
+
+export class ArchgateEntry {
+  readonly validatorId: string;
+  readonly validator_id: string;
+  readonly errorCode: string;
+  readonly error_code: string;
+
+  private constructor(validatorId: string, errorCode: string) {
+    this.validatorId = validatorId;
+    this.validator_id = validatorId;
+    this.errorCode = errorCode;
+    this.error_code = errorCode;
+    Object.freeze(this);
+  }
+
+  static create(props: ArchgateEntryProps): ArchgateEntry {
+    const validatorId = props.validatorId ?? props.validator_id ?? '';
+    const errorCode = props.errorCode ?? props.error_code ?? '';
+
+    if (!VALIDATOR_ID_PATTERN.test(validatorId)) {
+      throw new InvalidArchgateValidatorIdError(validatorId);
+    }
+
+    if (!ERROR_CODE_PATTERN.test(errorCode)) {
+      throw new InvalidArchgateErrorCodeError(errorCode);
+    }
+
+    return new ArchgateEntry(validatorId, errorCode);
+  }
+
+  matchesValidatorId(value: string): boolean {
+    return this.validatorId === value;
+  }
+
+  matchesErrorCode(value: string): boolean {
+    return this.errorCode === value;
+  }
+
+  equals(other: ArchgateEntry): boolean {
+    return this.validatorId === other.validatorId && this.errorCode === other.errorCode;
+  }
+}

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

@@ -0,0 +1,94 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+import { AdrId } from './adr-id.js';
+import { ArchgateEntry, type ArchgateEntryProps } from './archgate-entry.js';
+
+export type ArchgateMappingProps = Readonly<{
+  adrId?: AdrId | string;
+  adr_id?: AdrId | string;
+  enforcedBy?: readonly (ArchgateEntry | ArchgateEntryProps)[];
+  enforced_by?: readonly (ArchgateEntry | ArchgateEntryProps)[];
+}>;
+
+export class DuplicateArchgateEntryError extends Error {
+  constructor(validatorId: string, errorCode: string) {
+    super(`archgate.enforced_by に重複エントリがあります: ${validatorId} / ${errorCode}`);
+    this.name = 'DuplicateArchgateEntryError';
+  }
+}
+
+export class ArchgateMapping {
+  readonly adrId: AdrId;
+  readonly adr_id: string;
+  readonly enforcedBy: readonly ArchgateEntry[];
+  readonly enforced_by: readonly ArchgateEntry[];
+
+  private constructor(adrId: AdrId, enforcedBy: readonly ArchgateEntry[]) {
+    const frozenEntries = Object.freeze([...enforcedBy]);
+
+    this.adrId = adrId;
+    this.adr_id = adrId.value;
+    this.enforcedBy = frozenEntries;
+    this.enforced_by = frozenEntries;
+    Object.freeze(this);
+  }
+
+  static create(props: ArchgateMappingProps): ArchgateMapping {
+    const rawAdrId = props.adrId ?? props.adr_id;
+    const rawEntries = props.enforcedBy ?? props.enforced_by ?? [];
+    const adrId = rawAdrId instanceof AdrId ? rawAdrId : AdrId.create(String(rawAdrId ?? ''));
+    const enforcedBy = rawEntries.map((entry) =>
+      entry instanceof ArchgateEntry ? entry : ArchgateEntry.create(entry)
+    );
+
+    if (enforcedBy.length === 0) {
+      throw new Error('archgate.enforced_by には1件以上のエントリが必要です');
+    }
+
+    const uniqueKeys = new Set<string>();
+    for (const entry of enforcedBy) {
+      const key = `${entry.validatorId}:${entry.errorCode}`;
+      if (uniqueKeys.has(key)) {
+        throw new DuplicateArchgateEntryError(entry.validatorId, entry.errorCode);
+      }
+      uniqueKeys.add(key);
+    }
+
+    return new ArchgateMapping(adrId, enforcedBy);
+  }
+
+  findByValidatorId(validatorId: string): ArchgateEntry[] {
+    return this.enforcedBy.filter((entry) => entry.matchesValidatorId(validatorId));
+  }
+
+  findByErrorCode(errorCode: string): ArchgateEntry[] {
+    return this.enforcedBy.filter((entry) => entry.matchesErrorCode(errorCode));
+  }
+
+  hasEntry(validatorId: string, errorCode: string): boolean {
+    return this.enforcedBy.some(
+      (entry) => entry.matchesValidatorId(validatorId) && entry.matchesErrorCode(errorCode)
+    );
+  }
+
+  toPrimitives(): {
+    enforced_by: Array<{ validator_id: string; error_code: string }>;
+  } {
+    return {
+      enforced_by: this.enforcedBy.map((entry) => ({
+        validator_id: entry.validatorId,
+        error_code: entry.errorCode,
+      })),
+    };
+  }
+
+  equals(other: ArchgateMapping): boolean {
+    if (!this.adrId.equals(other.adrId) || this.enforcedBy.length !== other.enforcedBy.length) {
+      return false;
+    }
+
+    return this.enforcedBy.every((entry, index) => entry.equals(other.enforcedBy[index]!));
+  }
+}

package/scripts/harness/adr-foundation/domain/value-objects/superseded-by-ref.ts

@@ -0,0 +1,26 @@
+/**
+ * @layer domain
+ * @unit adr-foundation
+ */
+import { AdrId } from './adr-id.js';
+
+export class SupersededByRef {
+  readonly adrId: AdrId;
+
+  private constructor(adrId: AdrId) {
+    this.adrId = adrId;
+    Object.freeze(this);
+  }
+
+  static create(adrId: AdrId): SupersededByRef {
+    return new SupersededByRef(adrId);
+  }
+
+  toAdrRef(): string {
+    return this.adrId.toAdrRef();
+  }
+
+  equals(other: SupersededByRef): boolean {
+    return this.adrId.equals(other.adrId);
+  }
+}

package/scripts/harness/adr-foundation/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @layer public-api
+ * @unit adr-foundation
+ *
+ * adr-foundation ユニットのバレルエクスポート。
+ */
+
+// Composition Root
+export { createAdrFoundationModule } from './composition-root.js';
+
+// Presentation — CLI handlers
+export { ListAdrsCommandHandler } from './presentation/cli/list-adrs-command-handler.js';
+export { ValidateAdrCommandHandler } from './presentation/cli/validate-adr-command-handler.js';

package/scripts/harness/adr-foundation/infrastructure/parsers/adr-markdown-document-parser.ts

@@ -0,0 +1,121 @@
+/**
+ * @layer infrastructure
+ * @unit adr-foundation
+ */
+import type { ADR } from '../../domain/aggregates/adr.js';
+import type { AdrDocumentParserPort } from '../../domain/ports/adr-document-parser-port.js';
+import type { AdrFrontmatterParserPort } from '../../domain/ports/adr-frontmatter-parser-port.js';
+import type { AdrBody } from '../../domain/value-objects/adr-body.js';
+import type { AdrFrontmatter } from '../../domain/value-objects/adr-frontmatter.js';
+import { AdrBody as AdrBodyClass } from '../../domain/value-objects/adr-body.js';
+
+const SECTION_HEADING_PATTERN = /^##\s+(.+)$/;
+
+const HEADING_ALIASES: Readonly<Record<string, 'Context' | 'Decision' | 'Consequences' | 'Alternatives'>> = {
+  Context: 'Context',
+  Decision: 'Decision',
+  Consequences: 'Consequences',
+  Alternatives: 'Alternatives',
+  'コンテキスト': 'Context',
+  '決定': 'Decision',
+  '結果': 'Consequences',
+  '代替案': 'Alternatives',
+};
+
+export class AdrMarkdownDocumentParser implements AdrDocumentParserPort {
+  private readonly frontmatterParser: AdrFrontmatterParserPort;
+
+  constructor(frontmatterParser: AdrFrontmatterParserPort) {
+    this.frontmatterParser = frontmatterParser;
+  }
+
+  parseDocument(rawMarkdown: string): {
+    frontmatter: AdrFrontmatter;
+    body: AdrBody;
+  } {
+    const frontmatter = this.frontmatterParser.parseFrontmatter(rawMarkdown);
+
+    const bodyText = this.extractBody(rawMarkdown);
+    const sectionMap = this.parseSections(bodyText);
+
+    const body = AdrBodyClass.create({
+      context: sectionMap.Context,
+      decision: sectionMap.Decision,
+      consequences: sectionMap.Consequences,
+      alternatives: sectionMap.Alternatives,
+    });
+
+    return { frontmatter, body };
+  }
+
+  serializeDocument(adr: ADR): string {
+    const frontmatterYaml = this.frontmatterParser.serializeFrontmatter(adr.getFrontmatter());
+    const title = adr.getFrontmatter().title;
+    const sections = adr.getBody().toSectionMap();
+
+    const lines: string[] = [frontmatterYaml, '', `# ${title}`];
+
+    const canonicalOrder: Array<'Context' | 'Decision' | 'Consequences' | 'Alternatives'> = [
+      'Context',
+      'Decision',
+      'Consequences',
+      'Alternatives',
+    ];
+
+    for (const sectionName of canonicalOrder) {
+      const content = sections[sectionName];
+      if (content !== undefined) {
+        lines.push('', `## ${sectionName}`, '', content);
+      }
+    }
+
+    return lines.join('\n') + '\n';
+  }
+
+  private extractBody(rawMarkdown: string): string {
+    const closingIndex = rawMarkdown.indexOf('---', rawMarkdown.indexOf('---') + 3);
+    if (closingIndex === -1) {
+      return rawMarkdown;
+    }
+
+    return rawMarkdown.slice(closingIndex + 3).trim();
+  }
+
+  private parseSections(bodyText: string): Record<string, string | undefined> {
+    const lines = bodyText.split(/\r?\n/);
+    const sectionMap: Record<string, string | undefined> = {};
+
+    let currentSection: string | null = null;
+    const sectionLines: string[] = [];
+
+    const flushSection = (): void => {
+      if (currentSection !== null) {
+        sectionMap[currentSection] = sectionLines.join('\n').trim();
+        sectionLines.length = 0;
+      }
+    };
+
+    for (const line of lines) {
+      if (/^#\s+/.test(line)) {
+        continue;
+      }
+
+      const headingMatch = SECTION_HEADING_PATTERN.exec(line);
+      if (headingMatch) {
+        flushSection();
+        const heading = headingMatch[1]!.trim();
+        const canonical = HEADING_ALIASES[heading];
+        currentSection = canonical ?? heading;
+        continue;
+      }
+
+      if (currentSection !== null) {
+        sectionLines.push(line);
+      }
+    }
+
+    flushSection();
+
+    return sectionMap;
+  }
+}