phasegate 0.91.0 → 0.107.0

package/scripts/harness/config-foundation/application/usecases/load-resolved-config-use-case.ts

@@ -5,11 +5,13 @@
 import { ConfigValidationError } from '../../domain/errors/config-validation-error.js';
 import {
   HarnessConfig,
+  type HarnessConfigResolvedDocument,
   type HarnessConfigSourceDocument,
   type PresetId,
 } from '../../domain/harness-config.js';
 import type { ConfigRepositoryPort } from '../../domain/ports/config-repository-port.js';
 import type { ConfigSchemaValidatorPort } from '../../domain/ports/config-schema-validator-port.js';
+import { ArchitectureResolutionService } from '../../domain/services/architecture-resolution-service.js';
 import {
   PresetResolutionService,
   type PresetDefinition,
@@ -24,11 +26,13 @@ export interface LoadResolvedConfigUseCaseDependencies {
   readonly schemaValidator: ConfigSchemaValidatorPort;
   readonly presetDefinitions: PresetDefinitions;
   readonly presetResolutionService: PresetResolutionService;
+  readonly architectureResolutionService?: ArchitectureResolutionService;
 }
 
 export interface LoadedHarnessConfig {
   readonly aggregate: HarnessConfig;
   readonly path: string;
+  readonly schemaVersion: 'v2' | 'v3';
 }
 
 const PRESET_IDS = ['minimal', 'standard', 'strict'] as const satisfies readonly PresetId[];
@@ -94,6 +98,20 @@ export function resolveSourceDocument(
   );
 }
 
+function resolveArchitecture(
+  sourceDocument: HarnessConfigSourceDocument,
+  resolvedDocument: HarnessConfigResolvedDocument,
+  architectureResolutionService: ArchitectureResolutionService | undefined,
+): HarnessConfigResolvedDocument {
+  const service = architectureResolutionService ?? new ArchitectureResolutionService();
+  const { document } = service.resolve(sourceDocument.architecture);
+
+  return {
+    ...resolvedDocument,
+    architecture: document,
+  };
+}
+
 export async function loadHarnessConfig(
   dependencies: LoadResolvedConfigUseCaseDependencies,
   configPath?: string,
@@ -103,18 +121,28 @@ export async function loadHarnessConfig(
   validateDocumentOrThrow(dependencies.schemaValidator, document);
 
   const sourceDocument = toSourceDocument(document);
-  const resolvedDocument = resolveSourceDocument(
+  const resolvedFromPreset = resolveSourceDocument(
     sourceDocument,
     dependencies.presetDefinitions,
     dependencies.presetResolutionService,
   );
 
+  const resolvedDocument = resolveArchitecture(
+    sourceDocument,
+    resolvedFromPreset,
+    dependencies.architectureResolutionService,
+  );
+
+  const schemaVersion: 'v2' | 'v3' =
+    sourceDocument.architecture === undefined ? 'v2' : 'v3';
+
   return {
     aggregate: HarnessConfig.reconstitute({
       sourceDocument,
       resolvedDocument,
     }),
     path,
+    schemaVersion,
   };
 }
 
@@ -123,21 +151,24 @@ export class LoadResolvedConfigUseCase {
   private readonly schemaValidator: ConfigSchemaValidatorPort;
   private readonly presetDefinitions: PresetDefinitions;
   private readonly presetResolutionService: PresetResolutionService;
+  private readonly architectureResolutionService: ArchitectureResolutionService | undefined;
 
   constructor(dependencies: LoadResolvedConfigUseCaseDependencies) {
     this.configRepository = dependencies.configRepository;
     this.schemaValidator = dependencies.schemaValidator;
     this.presetDefinitions = dependencies.presetDefinitions;
     this.presetResolutionService = dependencies.presetResolutionService;
+    this.architectureResolutionService = dependencies.architectureResolutionService;
   }
 
   async execute(configPath?: string): Promise<ResolvedConfigOutput> {
-    const { aggregate, path } = await loadHarnessConfig(
+    const { aggregate, path, schemaVersion } = await loadHarnessConfig(
       {
         configRepository: this.configRepository,
         schemaValidator: this.schemaValidator,
         presetDefinitions: this.presetDefinitions,
         presetResolutionService: this.presetResolutionService,
+        architectureResolutionService: this.architectureResolutionService,
       },
       configPath,
     );
@@ -145,6 +176,7 @@ export class LoadResolvedConfigUseCase {
     return {
       config: aggregate.toResolvedConfig(),
       sourcePath: path,
+      schemaVersion,
     };
   }
 }

package/scripts/harness/config-foundation/application/usecases/migrate-schema-use-case.ts

@@ -0,0 +1,89 @@
+/**
+ * @layer application
+ * @unit config-foundation
+ *
+ * MigrateSchemaUseCase
+ * phasegate.config.json の schema を v2 から v3 へアップグレードする。
+ * v3 は `architecture` キーの存在で判定する。既に v3 の場合は no-op（alreadyUpToDate=true）。
+ *
+ * 現時点では v3 のみサポート。targetVersion != 'v3' は UnsupportedSchemaVersionError。
+ */
+
+import type { ConfigRepositoryPort } from '../../domain/ports/config-repository-port.js';
+
+export type MigrateSchemaInput = {
+  readonly targetVersion: 'v3';
+  readonly configPath?: string;
+};
+
+export type MigrateSchemaOutput = {
+  readonly configPath: string;
+  readonly migrated: boolean;
+  readonly alreadyUpToDate: boolean;
+  readonly appliedChanges: readonly string[];
+};
+
+export class UnsupportedSchemaVersionError extends Error {
+  constructor(version: string) {
+    super(`Unsupported schema version: ${version}. Only 'v3' is supported.`);
+    this.name = 'UnsupportedSchemaVersionError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class InvalidConfigShapeError extends Error {
+  constructor(configPath: string) {
+    super(`Config is not a JSON object: ${configPath}`);
+    this.name = 'InvalidConfigShapeError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const V3_ARCHITECTURE_DEFAULT = Object.freeze({ preset: 'clean' });
+
+export class MigrateSchemaUseCase {
+  private readonly configRepository: ConfigRepositoryPort;
+
+  constructor(deps: { configRepository: ConfigRepositoryPort }) {
+    this.configRepository = deps.configRepository;
+  }
+
+  async execute(input: MigrateSchemaInput): Promise<Readonly<MigrateSchemaOutput>> {
+    if (input.targetVersion !== 'v3') {
+      throw new UnsupportedSchemaVersionError(input.targetVersion);
+    }
+
+    const loaded = await this.configRepository.load(input.configPath);
+
+    if (!isPlainObject(loaded.document)) {
+      throw new InvalidConfigShapeError(loaded.path);
+    }
+
+    if ('architecture' in loaded.document) {
+      return Object.freeze({
+        configPath: loaded.path,
+        migrated: false,
+        alreadyUpToDate: true,
+        appliedChanges: Object.freeze([]),
+      });
+    }
+
+    const upgraded: Record<string, unknown> = {
+      ...loaded.document,
+      architecture: { ...V3_ARCHITECTURE_DEFAULT },
+    };
+    await this.configRepository.save(loaded.path, upgraded);
+
+    return Object.freeze({
+      configPath: loaded.path,
+      migrated: true,
+      alreadyUpToDate: false,
+      appliedChanges: Object.freeze([
+        'architecture: { preset: "clean" } を追加',
+      ]),
+    });
+  }
+}

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

@@ -15,8 +15,10 @@ import { EnableFeatureUseCase } from './application/usecases/enable-feature-use-
 import { DisableFeatureUseCase } from './application/usecases/disable-feature-use-case.js';
 import { ListAvailableFeaturesUseCase } from './application/usecases/list-available-features-use-case.js';
 import { LoadResolvedConfigUseCase } from './application/usecases/load-resolved-config-use-case.js';
+import { MigrateSchemaUseCase } from './application/usecases/migrate-schema-use-case.js';
 import { EnableFeatureCommandHandler } from './presentation/cli/enable-feature-command-handler.js';
 import { DisableFeatureCommandHandler } from './presentation/cli/disable-feature-command-handler.js';
+import { MigrateSchemaCommandHandler } from './presentation/cli/migrate-schema-command-handler.js';
 
 export function createConfigFoundationModule() {
   // Infrastructure
@@ -50,6 +52,7 @@ export function createConfigFoundationModule() {
     presetDefinitions,
     presetResolutionService,
   });
+  const migrateSchemaUseCase = new MigrateSchemaUseCase({ configRepository });
 
   // Presentation handlers
   const enableFeatureCommandHandler = new EnableFeatureCommandHandler({
@@ -60,17 +63,22 @@ export function createConfigFoundationModule() {
     disableFeatureUseCase,
     listAvailableFeaturesUseCase,
   });
+  const migrateSchemaCommandHandler = new MigrateSchemaCommandHandler({
+    migrateSchemaUseCase,
+  });
 
   return {
     handlers: {
       enableFeatureCommandHandler,
       disableFeatureCommandHandler,
+      migrateSchemaCommandHandler,
     },
     usecases: {
       enableFeatureUseCase,
       disableFeatureUseCase,
       listAvailableFeaturesUseCase,
       loadResolvedConfigUseCase,
+      migrateSchemaUseCase,
     },
   } as const;
 }

package/scripts/harness/config-foundation/domain/harness-config.ts

@@ -20,6 +20,10 @@ import type { L1Config } from './value-objects/l1-config.js';
 import type { L2Config } from './value-objects/l2-config.js';
 import type { L3Config } from './value-objects/l3-config.js';
 import type { L4Config } from './value-objects/l4-config.js';
+import type {
+  ArchitectureConfigDocument,
+  ArchitectureConfigSource,
+} from './value-objects/architecture-config.js';
 
 export type LayerId = 'L1' | 'L2' | 'L3' | 'L4';
 export type PresetId = 'minimal' | 'standard' | 'strict';
@@ -45,6 +49,7 @@ export interface HarnessConfigSourceDocument {
   harnesses: Partial<HarnessConfigResolvedDocument['harnesses']>;
   paths: HarnessConfigResolvedDocument['paths'];
   reporting: HarnessConfigResolvedDocument['reporting'];
+  architecture?: ArchitectureConfigSource;
 }
 
 export interface HarnessConfigResolvedDocument {
@@ -103,6 +108,7 @@ export interface HarnessConfigResolvedDocument {
     format: string;
     outputDir: string;
   };
+  architecture?: ArchitectureConfigDocument;
 }
 
 export type HarnessConfigV2 = HarnessConfigResolvedDocument;

package/scripts/harness/config-foundation/domain/services/architecture-resolution-service.ts

@@ -0,0 +1,257 @@
+/**
+ * @layer domain
+ * @unit config-foundation
+ */
+
+import { ConfigValidationError } from '../errors/config-validation-error.js';
+import {
+  freezeArchitectureDocument,
+  type ArchitectureConfigDocument,
+  type ArchitectureConfigSource,
+  type ArchitectureLayerDetection,
+  type ArchitectureMetadataTags,
+  type ArchitecturePresetId,
+} from '../value-objects/architecture-config.js';
+import {
+  ARCHITECTURE_PRESET_CATALOG,
+  type ArchitecturePresetDefinition,
+} from '../value-objects/architecture-preset-catalog.js';
+
+const DEFAULT_METADATA_TAGS: ArchitectureMetadataTags = Object.freeze({
+  layer: '@layer',
+  unit: '@unit',
+});
+
+const DEFAULT_LAYER_DETECTION: ArchitectureLayerDetection = Object.freeze({
+  byPath: true,
+  byTag: true,
+});
+
+const CLEAN_DEFAULT_SOURCE: ArchitectureConfigSource = Object.freeze({
+  preset: 'clean',
+});
+
+export interface ArchitectureResolutionResult {
+  readonly document: ArchitectureConfigDocument;
+  readonly warnings: readonly string[];
+}
+
+const cloneDependencies = (
+  source: Readonly<Record<string, readonly string[]>>
+): Record<string, string[]> => {
+  const cloned: Record<string, string[]> = {};
+
+  for (const [key, value] of Object.entries(source)) {
+    cloned[key] = [...value];
+  }
+
+  return cloned;
+};
+
+const lookupPresetDefinition = (
+  preset: ArchitecturePresetId
+): ArchitecturePresetDefinition | null => {
+  if (preset === 'custom') {
+    return null;
+  }
+
+  return ARCHITECTURE_PRESET_CATALOG[preset];
+};
+
+const ensureCustomHasExplicitLayers = (source: ArchitectureConfigSource): void => {
+  if (source.preset !== 'custom') {
+    return;
+  }
+
+  if (source.layers === undefined || source.allowedDependencies === undefined) {
+    throw new ConfigValidationError(
+      'architecture.preset "custom" では layers と allowedDependencies の明示指定が必須です'
+    );
+  }
+};
+
+const mergeLayers = (
+  preset: ArchitecturePresetDefinition | null,
+  override: readonly string[] | undefined
+): string[] => {
+  if (override !== undefined) {
+    return [...override];
+  }
+
+  return preset !== null ? [...preset.layers] : [];
+};
+
+const mergeDependencies = (
+  preset: ArchitecturePresetDefinition | null,
+  override: Readonly<Record<string, readonly string[]>> | undefined
+): Record<string, string[]> => {
+  if (override !== undefined) {
+    return cloneDependencies(override);
+  }
+
+  return preset !== null ? cloneDependencies(preset.allowedDependencies) : {};
+};
+
+const mergeMetadataTags = (
+  override: Partial<ArchitectureMetadataTags> | undefined
+): ArchitectureMetadataTags => {
+  return {
+    layer: override?.layer ?? DEFAULT_METADATA_TAGS.layer,
+    unit: override?.unit ?? DEFAULT_METADATA_TAGS.unit,
+  };
+};
+
+const mergeLayerDetection = (
+  override: Partial<ArchitectureLayerDetection> | undefined
+): ArchitectureLayerDetection => {
+  return {
+    byPath: override?.byPath ?? DEFAULT_LAYER_DETECTION.byPath,
+    byTag: override?.byTag ?? DEFAULT_LAYER_DETECTION.byTag,
+  };
+};
+
+const validateLayerDetection = (detection: ArchitectureLayerDetection): void => {
+  if (!detection.byPath && !detection.byTag) {
+    throw new ConfigValidationError(
+      'architecture.layerDetection は byPath / byTag の少なくとも一方を true にする必要があります'
+    );
+  }
+};
+
+const validateDependencyKeys = (
+  layers: readonly string[],
+  allowedDependencies: Record<string, string[]>
+): void => {
+  for (const key of Object.keys(allowedDependencies)) {
+    if (!layers.includes(key)) {
+      throw new ConfigValidationError(
+        `architecture.allowedDependencies のキー "${key}" は layers 配列に含まれません (C2)`
+      );
+    }
+  }
+};
+
+const validateDependencyValues = (
+  layers: readonly string[],
+  allowedDependencies: Record<string, string[]>
+): void => {
+  for (const [key, targets] of Object.entries(allowedDependencies)) {
+    for (const target of targets) {
+      if (!layers.includes(target)) {
+        throw new ConfigValidationError(
+          `architecture.allowedDependencies["${key}"] の依存先 "${target}" は layers 配列に含まれません (C3)`
+        );
+      }
+    }
+  }
+};
+
+const autofillSelfReference = (
+  layers: readonly string[],
+  allowedDependencies: Record<string, string[]>,
+  warnings: string[]
+): void => {
+  for (const layer of layers) {
+    const targets = allowedDependencies[layer];
+
+    if (targets === undefined) {
+      continue;
+    }
+
+    if (!targets.includes(layer)) {
+      targets.unshift(layer);
+      warnings.push(
+        `architecture.allowedDependencies["${layer}"] に自己参照 "${layer}" を補完しました (C1)`
+      );
+    }
+  }
+};
+
+const autofillMissingLayers = (
+  layers: readonly string[],
+  allowedDependencies: Record<string, string[]>,
+  warnings: string[]
+): void => {
+  for (const layer of layers) {
+    if (!(layer in allowedDependencies)) {
+      allowedDependencies[layer] = [layer];
+      warnings.push(
+        `architecture.allowedDependencies に layer "${layer}" のエントリが無いため自己参照のみで補完しました (C4)`
+      );
+    }
+  }
+};
+
+const warnCircularDependencies = (
+  allowedDependencies: Record<string, string[]>,
+  warnings: string[]
+): void => {
+  const entries = Object.entries(allowedDependencies);
+
+  for (const [source, targets] of entries) {
+    for (const target of targets) {
+      if (target === source) {
+        continue;
+      }
+
+      const reverseTargets = allowedDependencies[target];
+
+      if (reverseTargets !== undefined && reverseTargets.includes(source)) {
+        warnings.push(
+          `architecture.allowedDependencies に循環依存の疑いがあります: "${source}" → "${target}" と "${target}" → "${source}" (C5)`
+        );
+      }
+    }
+  }
+};
+
+const freezeDependencies = (
+  dependencies: Record<string, string[]>
+): Record<string, readonly string[]> => {
+  const frozen: Record<string, readonly string[]> = {};
+
+  for (const [key, value] of Object.entries(dependencies)) {
+    frozen[key] = Object.freeze([...value]);
+  }
+
+  return frozen;
+};
+
+export class ArchitectureResolutionService {
+  resolve(source: ArchitectureConfigSource | undefined): ArchitectureResolutionResult {
+    const warnings: string[] = [];
+    const effectiveSource = source ?? CLEAN_DEFAULT_SOURCE;
+
+    ensureCustomHasExplicitLayers(effectiveSource);
+
+    const presetDefinition = lookupPresetDefinition(effectiveSource.preset);
+    const layers = mergeLayers(presetDefinition, effectiveSource.layers);
+    const allowedDependencies = mergeDependencies(
+      presetDefinition,
+      effectiveSource.allowedDependencies
+    );
+
+    validateDependencyKeys(layers, allowedDependencies);
+    validateDependencyValues(layers, allowedDependencies);
+    autofillMissingLayers(layers, allowedDependencies, warnings);
+    autofillSelfReference(layers, allowedDependencies, warnings);
+    warnCircularDependencies(allowedDependencies, warnings);
+
+    const layerDetection = mergeLayerDetection(effectiveSource.layerDetection);
+
+    validateLayerDetection(layerDetection);
+
+    const document: ArchitectureConfigDocument = freezeArchitectureDocument({
+      preset: effectiveSource.preset,
+      layers,
+      allowedDependencies: freezeDependencies(allowedDependencies),
+      metadataTags: mergeMetadataTags(effectiveSource.metadataTags),
+      layerDetection,
+    });
+
+    return Object.freeze({
+      document,
+      warnings: Object.freeze([...warnings]),
+    });
+  }
+}

package/scripts/harness/config-foundation/domain/value-objects/architecture-config.ts

@@ -0,0 +1,66 @@
+/**
+ * @layer domain
+ * @unit config-foundation
+ */
+
+export const ARCHITECTURE_PRESET_IDS = [
+  'clean',
+  'strict-ddd',
+  'onion',
+  'hexagonal',
+  'layered',
+  'flat',
+  'custom',
+] as const;
+
+export type ArchitecturePresetId = (typeof ARCHITECTURE_PRESET_IDS)[number];
+
+export interface ArchitectureMetadataTags {
+  readonly layer: string;
+  readonly unit: string;
+}
+
+export interface ArchitectureLayerDetection {
+  readonly byPath: boolean;
+  readonly byTag: boolean;
+}
+
+export interface ArchitectureConfigSource {
+  readonly preset: ArchitecturePresetId;
+  readonly layers?: readonly string[];
+  readonly allowedDependencies?: Readonly<Record<string, readonly string[]>>;
+  readonly metadataTags?: Partial<ArchitectureMetadataTags>;
+  readonly layerDetection?: Partial<ArchitectureLayerDetection>;
+}
+
+export interface ArchitectureConfigDocument {
+  readonly preset: ArchitecturePresetId;
+  readonly layers: readonly string[];
+  readonly allowedDependencies: Readonly<Record<string, readonly string[]>>;
+  readonly metadataTags: ArchitectureMetadataTags;
+  readonly layerDetection: ArchitectureLayerDetection;
+}
+
+export const isArchitecturePresetId = (value: unknown): value is ArchitecturePresetId => {
+  return (
+    typeof value === 'string' && ARCHITECTURE_PRESET_IDS.includes(value as ArchitecturePresetId)
+  );
+};
+
+export const freezeArchitectureDocument = (
+  document: ArchitectureConfigDocument
+): ArchitectureConfigDocument => {
+  const frozenDependencies: Record<string, readonly string[]> = {};
+
+  for (const [key, value] of Object.entries(document.allowedDependencies)) {
+    frozenDependencies[key] = Object.freeze([...value]);
+  }
+
+  return Object.freeze({
+    preset: document.preset,
+    layers: Object.freeze([...document.layers]),
+    allowedDependencies: Object.freeze(frozenDependencies),
+    metadataTags: Object.freeze({ ...document.metadataTags }),
+    layerDetection: Object.freeze({ ...document.layerDetection }),
+  });
+};

package/scripts/harness/config-foundation/domain/value-objects/architecture-preset-catalog.ts

@@ -0,0 +1,75 @@
+/**
+ * @layer domain
+ * @unit config-foundation
+ */
+
+import type { ArchitecturePresetId } from './architecture-config.js';
+
+export interface ArchitecturePresetDefinition {
+  readonly layers: readonly string[];
+  readonly allowedDependencies: Readonly<Record<string, readonly string[]>>;
+}
+
+const freeze = (definition: ArchitecturePresetDefinition): ArchitecturePresetDefinition => {
+  const dependencies: Record<string, readonly string[]> = {};
+
+  for (const [key, value] of Object.entries(definition.allowedDependencies)) {
+    dependencies[key] = Object.freeze([...value]);
+  }
+
+  return Object.freeze({
+    layers: Object.freeze([...definition.layers]),
+    allowedDependencies: Object.freeze(dependencies),
+  });
+};
+
+export const ARCHITECTURE_PRESET_CATALOG: Readonly<
+  Record<Exclude<ArchitecturePresetId, 'custom'>, ArchitecturePresetDefinition>
+> = Object.freeze({
+  clean: freeze({
+    layers: ['domain', 'application', 'infrastructure', 'presentation'],
+    allowedDependencies: {
+      domain: ['domain'],
+      application: ['application', 'domain'],
+      infrastructure: ['infrastructure', 'application', 'domain'],
+      presentation: ['presentation', 'application', 'domain'],
+    },
+  }),
+  'strict-ddd': freeze({
+    layers: ['domain', 'application', 'infrastructure', 'presentation'],
+    allowedDependencies: {
+      domain: ['domain'],
+      application: ['application', 'domain'],
+      infrastructure: ['infrastructure', 'application', 'domain'],
+      presentation: ['presentation', 'application'],
+    },
+  }),
+  onion: freeze({
+    layers: ['domain', 'application', 'interface'],
+    allowedDependencies: {
+      domain: ['domain'],
+      application: ['application', 'domain'],
+      interface: ['interface', 'application', 'domain'],
+    },
+  }),
+  hexagonal: freeze({
+    layers: ['core', 'ports', 'adapters'],
+    allowedDependencies: {
+      core: ['core'],
+      ports: ['ports', 'core'],
+      adapters: ['adapters', 'ports', 'core'],
+    },
+  }),
+  layered: freeze({
+    layers: ['controller', 'service', 'repository'],
+    allowedDependencies: {
+      controller: ['controller', 'service'],
+      service: ['service', 'repository'],
+      repository: ['repository'],
+    },
+  }),
+  flat: freeze({
+    layers: [],
+    allowedDependencies: {},
+  }),
+});