phasegate 0.15.0

package/scripts/harness/harness-error/domain/services/severity-contract-enforcer.ts

@@ -0,0 +1,37 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ *
+ * SeverityContractEnforcer ドメインサービス
+ * defaultSeverity に対する格下げを禁止し、許容される effective severity を返す
+ */
+import { SeverityDowngradeViolationError } from '../errors/severity-downgrade-violation-error.js';
+import type { Severity } from '../value-objects/severity.js';
+
+export class SeverityContractEnforcer {
+  resolveEffectiveSeverity(
+    requested: Severity | undefined,
+    defaultSeverity: Severity
+  ): Severity {
+    if (requested === undefined) {
+      return defaultSeverity;
+    }
+
+    if (requested.isHigherThan(defaultSeverity)) {
+      return requested;
+    }
+
+    if (requested.equals(defaultSeverity)) {
+      return requested;
+    }
+
+    throw new SeverityDowngradeViolationError(
+      requested.value,
+      defaultSeverity.value
+    );
+  }
+
+  assertNoDowngrade(requested: Severity, defaultSeverity: Severity): void {
+    this.resolveEffectiveSeverity(requested, defaultSeverity);
+  }
+}

package/scripts/harness/harness-error/domain/value-objects/adr-ref.ts

@@ -0,0 +1,34 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ *
+ * ADR参照値オブジェクト
+ * ADR-{3桁の数字} 形式の参照値を表現する
+ */
+import { InvalidAdrRefError } from '../errors/invalid-adr-ref-error.js';
+
+const ADR_REF_PATTERN = /^ADR-[0-9]{3}$/;
+
+export class AdrRef {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(raw: string): AdrRef {
+    if (!ADR_REF_PATTERN.test(raw)) {
+      throw new InvalidAdrRefError(raw);
+    }
+    return new AdrRef(raw);
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  equals(other: AdrRef): boolean {
+    return this.value === other.value;
+  }
+}

package/scripts/harness/harness-error/domain/value-objects/error-code.ts

@@ -0,0 +1,41 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ *
+ * エラーコード値オブジェクト
+ * L{0-4}-{3桁以上の数字} 形式の正規エラーコードを表現する
+ */
+import { InvalidErrorCodeError } from '../errors/invalid-error-code-error.js';
+
+const ERROR_CODE_PATTERN = /^L([0-4])-([0-9]{3,})$/;
+
+export class ErrorCode {
+  readonly value: string;
+  readonly layer: number;
+  readonly sequence: string;
+
+  private constructor(value: string, layer: number, sequence: string) {
+    this.value = value;
+    this.layer = layer;
+    this.sequence = sequence;
+    Object.freeze(this);
+  }
+
+  static create(raw: string): ErrorCode {
+    const match = ERROR_CODE_PATTERN.exec(raw);
+    if (!match) {
+      throw new InvalidErrorCodeError(raw);
+    }
+    const layer = Number(match[1]);
+    const sequence = match[2];
+    return new ErrorCode(raw, layer, sequence);
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  equals(other: ErrorCode): boolean {
+    return this.value === other.value;
+  }
+}

package/scripts/harness/harness-error/domain/value-objects/error-definition.ts

@@ -0,0 +1,128 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ *
+ * エラー定義値オブジェクト
+ * エラーコードごとの正規定義（タイトル、カテゴリ、severity、ADR/fix_example要否）を不変で保持する
+ */
+import { InvalidErrorDefinitionError } from '../errors/invalid-error-definition-error.js';
+import type { AdrRef } from './adr-ref.js';
+import type { ErrorCode } from './error-code.js';
+import type { FixExample } from './fix-example.js';
+import type { Severity } from './severity.js';
+
+export type ErrorDefinitionCategory =
+  | 'phase_gate'
+  | 'architecture'
+  | 'dependency'
+  | 'quality'
+  | 'security'
+  | 'performance'
+  | 'consistency'
+  | 'metadata';
+
+export interface ErrorDefinitionProps {
+  readonly code: ErrorCode;
+  readonly title: string;
+  readonly category: string;
+  readonly defaultSeverity: Severity;
+  readonly adrRefRequired: boolean;
+  readonly defaultAdrRef: AdrRef | null;
+  readonly fixExampleRequired: boolean;
+  readonly defaultFixExample: FixExample | null;
+  readonly ownerValidatorId: string;
+}
+
+export class ErrorDefinition {
+  readonly code: ErrorCode;
+  readonly title: string;
+  readonly category: string;
+  readonly defaultSeverity: Severity;
+  readonly adrRefRequired: boolean;
+  readonly defaultAdrRef: AdrRef | null;
+  readonly fixExampleRequired: boolean;
+  readonly defaultFixExample: FixExample | null;
+  readonly ownerValidatorId: string;
+
+  private constructor(props: ErrorDefinitionProps) {
+    this.code = props.code;
+    this.title = props.title;
+    this.category = props.category;
+    this.defaultSeverity = props.defaultSeverity;
+    this.adrRefRequired = props.adrRefRequired;
+    this.defaultAdrRef = props.defaultAdrRef;
+    this.fixExampleRequired = props.fixExampleRequired;
+    this.defaultFixExample = props.defaultFixExample;
+    this.ownerValidatorId = props.ownerValidatorId;
+    Object.freeze(this);
+  }
+
+  static create(props: ErrorDefinitionProps): ErrorDefinition {
+    if (!props.ownerValidatorId || props.ownerValidatorId.trim().length === 0) {
+      throw new InvalidErrorDefinitionError(
+        'ownerValidatorId は空文字であってはなりません。'
+      );
+    }
+
+    if (props.defaultAdrRef !== null && !props.adrRefRequired) {
+      throw new InvalidErrorDefinitionError(
+        'defaultAdrRef を持つ場合は adrRefRequired を true にしなければなりません。'
+      );
+    }
+
+    // fixExampleRequired=true かつ defaultFixExample=null は許容する
+    // （呼び出し側が明示的に fixExample を提供する前提）
+
+    return new ErrorDefinition(props);
+  }
+
+  requiresAdrRef(): boolean {
+    return this.adrRefRequired;
+  }
+
+  requiresFixExample(): boolean {
+    return this.fixExampleRequired;
+  }
+
+  resolveAdrRef(explicitAdrRef?: AdrRef | null): AdrRef | null {
+    if (explicitAdrRef) {
+      return explicitAdrRef;
+    }
+    return this.defaultAdrRef;
+  }
+
+  resolveFixExample(explicitFixExample?: FixExample | null): FixExample | null {
+    if (explicitFixExample) {
+      return explicitFixExample;
+    }
+    return this.defaultFixExample;
+  }
+
+  equals(other: ErrorDefinition): boolean {
+    const adrRefEqual =
+      this.defaultAdrRef === null && other.defaultAdrRef === null
+        ? true
+        : this.defaultAdrRef !== null && other.defaultAdrRef !== null
+          ? this.defaultAdrRef.equals(other.defaultAdrRef)
+          : false;
+
+    const fixExampleEqual =
+      this.defaultFixExample === null && other.defaultFixExample === null
+        ? true
+        : this.defaultFixExample !== null && other.defaultFixExample !== null
+          ? this.defaultFixExample.equals(other.defaultFixExample)
+          : false;
+
+    return (
+      this.code.equals(other.code) &&
+      this.title === other.title &&
+      this.category === other.category &&
+      this.defaultSeverity.equals(other.defaultSeverity) &&
+      this.adrRefRequired === other.adrRefRequired &&
+      adrRefEqual &&
+      this.fixExampleRequired === other.fixExampleRequired &&
+      fixExampleEqual &&
+      this.ownerValidatorId === other.ownerValidatorId
+    );
+  }
+}

package/scripts/harness/harness-error/domain/value-objects/fix-example-validation-result.ts

@@ -0,0 +1,64 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ *
+ * FixExample検証結果値オブジェクト
+ * 検証の成否・理由・詳細診断を不変で保持する
+ */
+import { InvalidFixExampleValidationResultError } from '../errors/invalid-fix-example-validation-result-error.js';
+
+export class FixExampleValidationResult {
+  readonly passed: boolean;
+  readonly validatorId: string;
+  readonly reason: string | null;
+  readonly diagnostics: readonly string[];
+
+  private constructor(
+    passed: boolean,
+    validatorId: string,
+    reason: string | null,
+    diagnostics: readonly string[]
+  ) {
+    this.passed = passed;
+    this.validatorId = validatorId;
+    this.reason = reason;
+    this.diagnostics = diagnostics;
+    Object.freeze(this);
+  }
+
+  static success(validatorId: string): FixExampleValidationResult {
+    return new FixExampleValidationResult(true, validatorId, null, []);
+  }
+
+  static failure(
+    validatorId: string,
+    reason: string,
+    diagnostics?: readonly string[]
+  ): FixExampleValidationResult {
+    if (!reason || reason.length === 0) {
+      throw new InvalidFixExampleValidationResultError(
+        'failure時のreasonは必須です。空文字は許容されません。'
+      );
+    }
+    const resolvedDiagnostics = diagnostics ?? [reason];
+    if (resolvedDiagnostics.length === 0) {
+      throw new InvalidFixExampleValidationResultError(
+        'failure時のdiagnosticsは1件以上必要です。'
+      );
+    }
+    return new FixExampleValidationResult(
+      false,
+      validatorId,
+      reason,
+      Object.freeze([...resolvedDiagnostics])
+    );
+  }
+
+  equals(other: FixExampleValidationResult): boolean {
+    if (this.passed !== other.passed) return false;
+    if (this.validatorId !== other.validatorId) return false;
+    if (this.reason !== other.reason) return false;
+    if (this.diagnostics.length !== other.diagnostics.length) return false;
+    return this.diagnostics.every((d, i) => d === other.diagnostics[i]);
+  }
+}

package/scripts/harness/harness-error/domain/value-objects/fix-example.ts

@@ -0,0 +1,34 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ *
+ * 修正コード片値オブジェクト
+ * trim後に空でないコード片であることを保証する
+ */
+import { InvalidFixExampleError } from '../errors/invalid-fix-example-error.js';
+
+export class FixExample {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(raw: string): FixExample {
+    if (raw.trim().length === 0) {
+      throw new InvalidFixExampleError(
+        'fix_exampleは空文字であってはなりません。有効なコード片を指定してください。'
+      );
+    }
+    return new FixExample(raw);
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  equals(other: FixExample): boolean {
+    return this.value === other.value;
+  }
+}

package/scripts/harness/harness-error/domain/value-objects/harness-error.ts

@@ -0,0 +1,94 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ *
+ * HarnessError 中心モデル（不変値オブジェクト）
+ * 集約を持たず、全属性を不変で保持する値オブジェクトとして設計
+ */
+import type { AdrRef } from './adr-ref.js';
+import type { ErrorCode } from './error-code.js';
+import type { FixExample } from './fix-example.js';
+import type { Severity } from './severity.js';
+
+export interface HarnessErrorContract {
+  readonly code: string;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly suggestion: string;
+  readonly adr_ref?: string;
+  readonly fix_example?: string;
+}
+
+export interface HarnessErrorProps {
+  readonly code: ErrorCode;
+  readonly severity: Severity;
+  readonly message: string;
+  readonly suggestion: string;
+  readonly adrRef: AdrRef | null;
+  readonly fixExample: FixExample | null;
+}
+
+export class HarnessError {
+  readonly code: ErrorCode;
+  readonly severity: Severity;
+  readonly message: string;
+  readonly suggestion: string;
+  readonly adrRef: AdrRef | null;
+  readonly fixExample: FixExample | null;
+
+  constructor(props: HarnessErrorProps) {
+    this.code = props.code;
+    this.severity = props.severity;
+    this.message = props.message;
+    this.suggestion = props.suggestion;
+    this.adrRef = props.adrRef;
+    this.fixExample = props.fixExample;
+  }
+
+  equals(other: HarnessError): boolean {
+    const adrRefEqual =
+      this.adrRef === null && other.adrRef === null
+        ? true
+        : this.adrRef !== null && other.adrRef !== null
+          ? this.adrRef.equals(other.adrRef)
+          : false;
+
+    const fixExampleEqual =
+      this.fixExample === null && other.fixExample === null
+        ? true
+        : this.fixExample !== null && other.fixExample !== null
+          ? this.fixExample.equals(other.fixExample)
+          : false;
+
+    return (
+      this.code.equals(other.code) &&
+      this.severity.equals(other.severity) &&
+      this.message === other.message &&
+      this.suggestion === other.suggestion &&
+      adrRefEqual &&
+      fixExampleEqual
+    );
+  }
+
+  hasAdrRef(): boolean {
+    return this.adrRef !== null;
+  }
+
+  hasFixExample(): boolean {
+    return this.fixExample !== null;
+  }
+
+  toContract(): Readonly<HarnessErrorContract> {
+    const contract: HarnessErrorContract = {
+      code: this.code.toString(),
+      severity: this.severity.value,
+      message: this.message,
+      suggestion: this.suggestion,
+      ...(this.adrRef !== null ? { adr_ref: this.adrRef.toString() } : {}),
+      ...(this.fixExample !== null
+        ? { fix_example: this.fixExample.toString() }
+        : {}),
+    };
+    return Object.freeze(contract);
+  }
+}

package/scripts/harness/harness-error/domain/value-objects/severity.ts

@@ -0,0 +1,46 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ *
+ * 重大度値オブジェクト
+ * "error" (rank=2) または "warning" (rank=1) のみ許容する
+ */
+import { InvalidSeverityError } from '../errors/invalid-severity-error.js';
+
+const SEVERITY_RANK: Record<string, number> = {
+  error: 2,
+  warning: 1,
+};
+
+const VALID_SEVERITIES = new Set(['error', 'warning']);
+
+export class Severity {
+  readonly value: 'error' | 'warning';
+  readonly rank: number;
+
+  private constructor(value: 'error' | 'warning', rank: number) {
+    this.value = value;
+    this.rank = rank;
+    // Object.freeze is called after construction in create()
+  }
+
+  static create(raw: 'error' | 'warning'): Severity {
+    if (!VALID_SEVERITIES.has(raw)) {
+      throw new InvalidSeverityError(raw);
+    }
+    const instance = new Severity(raw, SEVERITY_RANK[raw]);
+    return Object.freeze(instance);
+  }
+
+  isHigherThan(other: Severity): boolean {
+    return this.rank > other.rank;
+  }
+
+  equals(other: Severity): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): 'error' | 'warning' {
+    return this.value;
+  }
+}

package/scripts/harness/harness-error/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @layer barrel
+ * @unit harness-error
+ *
+ * harness-error ユニットの公開バレルエクスポート
+ */
+
+// --- Composition Root ---
+export { createHarnessErrorModule } from './composition-root.js';
+
+// --- Key Types ---
+export type { HarnessErrorContract } from './application/dto/harness-error-contract.js';
+
+// --- Key Classes ---
+export { ErrorDefinitionRegistry } from './domain/services/error-definition-registry.js';
+export { HarnessErrorFactory } from './domain/services/harness-error-factory.js';

package/scripts/harness/harness-error/infrastructure/adapters/file-system-adr-existence-checker-adapter.ts

@@ -0,0 +1,46 @@
+/**
+ * @layer infrastructure
+ * @unit harness-error
+ */
+import { readFile } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { AdrExistenceCheckerPort } from '../../domain/ports/adr-existence-checker-port.js';
+import type { AdrRef } from '../../domain/value-objects/adr-ref.js';
+
+const ADR_ID_PATTERN = /^\s*adr_id\s*:\s*["']?([0-9]{3})["']?\s*$/m;
+
+export interface FileSystemAdrExistenceCheckerAdapterDeps {
+  readonly rootDir: string;
+}
+
+export class FileSystemAdrExistenceCheckerAdapter
+  implements AdrExistenceCheckerPort
+{
+  private readonly rootDir: string;
+
+  constructor(deps: FileSystemAdrExistenceCheckerAdapterDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async exists(adrRef: AdrRef): Promise<boolean> {
+    const adrDir = path.join(this.rootDir, 'docs', 'ADR');
+    if (!fs.existsSync(adrDir)) {
+      return false;
+    }
+
+    const filePath = path.join(adrDir, `${adrRef.toString()}.md`);
+    if (!fs.existsSync(filePath)) {
+      return false;
+    }
+
+    const content = await readFile(filePath, 'utf8');
+    const match = content.match(ADR_ID_PATTERN);
+    if (!match) {
+      return false;
+    }
+
+    const expectedAdrId = adrRef.toString().slice('ADR-'.length);
+    return match[1] === expectedAdrId;
+  }
+}

package/scripts/harness/harness-error/infrastructure/adapters/legacy-error-reporter-adapter.ts

@@ -0,0 +1,54 @@
+/**
+ * @layer infrastructure
+ * @unit harness-error
+ */
+import type { HarnessError } from '../../../core/error-reporter.js';
+import type { ValidatorIssueDraft } from '../../application/dto/validator-issue-draft.js';
+
+function compressSuggestion(error: HarnessError): string {
+  const parts: string[] = [];
+
+  if (error.resolution.fixSuggestion.trim().length > 0) {
+    parts.push(error.resolution.fixSuggestion.trim());
+  }
+
+  if (error.resolution.docLinks.length > 0) {
+    parts.push(`参考資料: ${error.resolution.docLinks.join(', ')}`);
+  }
+
+  if (error.resolution.relatedFiles.length > 0) {
+    parts.push(`関連ファイル: ${error.resolution.relatedFiles.join(', ')}`);
+  }
+
+  if (parts.length === 0 && error.message.agentInstruction.trim().length > 0) {
+    parts.push(error.message.agentInstruction.trim());
+  }
+
+  if (parts.length === 0 && error.message.detailed.trim().length > 0) {
+    parts.push(error.message.detailed.trim());
+  }
+
+  if (parts.length === 0) {
+    parts.push(error.message.short);
+  }
+
+  return parts.join('\n');
+}
+
+function mapSeverity(
+  severity: HarnessError['severity']
+): 'error' | 'warning' {
+  return severity === 'error' ? 'error' : 'warning';
+}
+
+export class LegacyErrorReporterAdapter {
+  toDraft(error: HarnessError): Readonly<ValidatorIssueDraft> {
+    return Object.freeze({
+      code: error.code,
+      message: error.message.short,
+      suggestion: compressSuggestion(error),
+      severity: mapSeverity(error.severity),
+      validatorId: error.metadata.validator,
+    });
+  }
+}

package/scripts/harness/harness-error/infrastructure/adapters/type-script-snippet-syntax-adapter.ts

@@ -0,0 +1,59 @@
+/**
+ * @layer infrastructure
+ * @unit harness-error
+ */
+import ts from 'typescript';
+
+export interface TypeScriptSnippetSyntaxValidationResult {
+  readonly valid: boolean;
+  readonly diagnostics: readonly string[];
+}
+
+export class TypeScriptSnippetSyntaxAdapter {
+  validate(snippet: string): TypeScriptSnippetSyntaxValidationResult {
+    if (snippet.length === 0) {
+      return {
+        valid: true,
+        diagnostics: [],
+      };
+    }
+
+    const transpileResult = ts.transpileModule(
+      snippet,
+      {
+        compilerOptions: {
+          target: ts.ScriptTarget.ES2022,
+          module: ts.ModuleKind.ESNext,
+        },
+        fileName: 'fix-example.ts',
+        reportDiagnostics: true,
+      }
+    );
+
+    const diagnostics = (transpileResult.diagnostics ?? []).map((diagnostic) => {
+      const message = ts.flattenDiagnosticMessageText(
+        diagnostic.messageText,
+        '\n'
+      );
+
+      if (diagnostic.start === undefined) {
+        return message;
+      }
+
+      const sourceFile = diagnostic.file;
+      if (!sourceFile) {
+        return message;
+      }
+
+      const position = sourceFile.getLineAndCharacterOfPosition(
+        diagnostic.start
+      );
+      return `${message} (${position.line + 1}:${position.character + 1})`;
+    });
+
+    return {
+      valid: diagnostics.length === 0,
+      diagnostics,
+    };
+  }
+}