phasegate 0.16.0 → 0.31.0

package/scripts/harness/phase-dependency-model/domain/services/gate-graph.ts

@@ -0,0 +1,223 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+import { GateDefinition } from '../values/gate-definition.js';
+import { GateName } from '../values/gate-name.js';
+
+export interface GateGraphViolation {
+  readonly code:
+    | 'DUPLICATE_GATE_NAME'
+    | 'UNKNOWN_DEPENDENCY'
+    | 'LEVEL_ORDER_VIOLATION'
+    | 'CYCLIC_DEPENDENCY';
+  readonly message: string;
+  readonly gateNames: readonly string[];
+}
+
+export class GateGraphValidationError extends Error {
+  readonly violations: readonly GateGraphViolation[];
+
+  constructor(violations: readonly GateGraphViolation[]) {
+    super(violations.map((violation) => violation.message).join('\n'));
+    this.name = 'GateGraphValidationError';
+    this.violations = Object.freeze([...violations]);
+  }
+}
+
+const toViolation = (
+  code: GateGraphViolation['code'],
+  message: string,
+  gateNames: readonly string[],
+): GateGraphViolation =>
+  Object.freeze({
+    code,
+    message,
+    gateNames: Object.freeze([...gateNames]),
+  });
+
+export class GateGraph {
+  readonly gates: ReadonlyMap<string, GateDefinition>;
+
+  private constructor(gates: ReadonlyMap<string, GateDefinition>) {
+    this.gates = gates;
+    Object.freeze(this);
+  }
+
+  static build(gates: GateDefinition[]): GateGraph {
+    const violations: GateGraphViolation[] = [];
+    const duplicateNames = new Set<string>();
+    const gateMap = new Map<string, GateDefinition>();
+
+    for (const gate of gates) {
+      const name = gate.name.value;
+      if (gateMap.has(name)) {
+        duplicateNames.add(name);
+        continue;
+      }
+      gateMap.set(name, gate);
+    }
+
+    for (const duplicateName of duplicateNames) {
+      violations.push(
+        toViolation(
+          'DUPLICATE_GATE_NAME',
+          `重複する GateName です: ${duplicateName}`,
+          [duplicateName],
+        ),
+      );
+    }
+
+    for (const gate of gateMap.values()) {
+      for (const dependencyName of gate.dependsOn) {
+        const dependency = gateMap.get(dependencyName.value);
+        if (!dependency) {
+          violations.push(
+            toViolation(
+              'UNKNOWN_DEPENDENCY',
+              `未知の dependsOn 参照です: ${gate.name.value} -> ${dependencyName.value}`,
+              [gate.name.value, dependencyName.value],
+            ),
+          );
+          continue;
+        }
+
+        if (dependency.level.value > gate.level.value) {
+          violations.push(
+            toViolation(
+              'LEVEL_ORDER_VIOLATION',
+              `レベル逆行です: ${gate.name.value} -> ${dependencyName.value}`,
+              [gate.name.value, dependencyName.value],
+            ),
+          );
+        }
+      }
+    }
+
+    const graph = new Map<string, string[]>();
+    for (const gate of gateMap.values()) {
+      graph.set(gate.name.value, []);
+    }
+    for (const gate of gateMap.values()) {
+      const neighbors = graph.get(gate.name.value);
+      if (!neighbors) {
+        continue;
+      }
+      for (const dependencyName of gate.dependsOn) {
+        if (gateMap.has(dependencyName.value)) {
+          neighbors.push(dependencyName.value);
+        }
+      }
+    }
+
+    for (const cycle of GateGraph.detectCycles(graph)) {
+      violations.push(
+        toViolation(
+          'CYCLIC_DEPENDENCY',
+          `循環依存が検出されました: ${cycle.join(' -> ')}`,
+          cycle,
+        ),
+      );
+    }
+
+    if (violations.length > 0) {
+      throw new GateGraphValidationError(violations);
+    }
+
+    return new GateGraph(gateMap);
+  }
+
+  resolveAncestors(name: GateName): GateName[] {
+    const target = this.gates.get(name.value);
+    if (!target) {
+      return [];
+    }
+
+    const visited = new Set<string>();
+    const ordered: GateName[] = [];
+
+    const visit = (gate: GateDefinition): void => {
+      for (const dependencyName of gate.dependsOn) {
+        if (visited.has(dependencyName.value)) {
+          continue;
+        }
+
+        const dependency = this.gates.get(dependencyName.value);
+        if (!dependency) {
+          continue;
+        }
+
+        visit(dependency);
+        visited.add(dependencyName.value);
+        ordered.push(dependencyName);
+      }
+    };
+
+    visit(target);
+
+    return ordered;
+  }
+
+  private static detectCycles(graph: ReadonlyMap<string, readonly string[]>): readonly string[][] {
+    let index = 0;
+    const indexMap = new Map<string, number>();
+    const lowLinkMap = new Map<string, number>();
+    const stack: string[] = [];
+    const inStack = new Set<string>();
+    const cycles: string[][] = [];
+
+    const strongConnect = (node: string): void => {
+      indexMap.set(node, index);
+      lowLinkMap.set(node, index);
+      index += 1;
+      stack.push(node);
+      inStack.add(node);
+
+      for (const next of graph.get(node) ?? []) {
+        if (!indexMap.has(next)) {
+          strongConnect(next);
+          lowLinkMap.set(node, Math.min(lowLinkMap.get(node) ?? 0, lowLinkMap.get(next) ?? 0));
+          continue;
+        }
+
+        if (inStack.has(next)) {
+          lowLinkMap.set(node, Math.min(lowLinkMap.get(node) ?? 0, indexMap.get(next) ?? 0));
+        }
+      }
+
+      if ((lowLinkMap.get(node) ?? -1) !== (indexMap.get(node) ?? -1)) {
+        return;
+      }
+
+      const component: string[] = [];
+      let current = '';
+      do {
+        current = stack.pop() ?? '';
+        if (current.length === 0) {
+          break;
+        }
+        inStack.delete(current);
+        component.push(current);
+      } while (current !== node);
+
+      if (component.length > 1) {
+        cycles.push(component.sort());
+        return;
+      }
+
+      const [single] = component;
+      if ((graph.get(single) ?? []).includes(single)) {
+        cycles.push(component);
+      }
+    };
+
+    for (const node of graph.keys()) {
+      if (!indexMap.has(node)) {
+        strongConnect(node);
+      }
+    }
+
+    return Object.freeze(cycles);
+  }
+}

package/scripts/harness/phase-dependency-model/domain/services/story-reflection-checker.ts

@@ -0,0 +1,66 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+import type { StoryReflectionConfig } from '../values/story-reflection-config.js';
+import type { StoryReflectionFileSystemPort } from '../ports/story-reflection-file-system-port.js';
+import {
+  StoryReflectionResult,
+  type StoryReflectionViolation,
+} from '../values/story-reflection-result.js';
+
+export class StoryReflectionChecker {
+  constructor(private readonly fsPort: StoryReflectionFileSystemPort) {}
+
+  async check(
+    unitId: string,
+    config: StoryReflectionConfig,
+  ): Promise<StoryReflectionResult> {
+    if (!config.enabled) {
+      return StoryReflectionResult.pass();
+    }
+
+    const storyIds = await this.fsPort.listStoryDirectories(unitId);
+
+    if (storyIds.length === 0) {
+      return StoryReflectionResult.pass();
+    }
+
+    const violations: StoryReflectionViolation[] = [];
+    const warnings: StoryReflectionViolation[] = [];
+
+    for (const storyId of storyIds) {
+      for (const mapping of config.mappings) {
+        const { inception: inceptionPath, product: productPath } =
+          mapping.resolve({ unitId, storyId });
+
+        const inceptionExists = await this.fsPort.fileExists(inceptionPath);
+
+        if (!inceptionExists) {
+          continue;
+        }
+
+        const hasAnnotation =
+          await this.fsPort.fileContainsStoryAnnotation(productPath, storyId);
+
+        if (!hasAnnotation) {
+          const violation: StoryReflectionViolation = {
+            storyId,
+            mapping,
+            inceptionPath,
+            productPath,
+          };
+
+          if (mapping.required) {
+            violations.push(violation);
+          } else {
+            warnings.push(violation);
+          }
+        }
+      }
+    }
+
+    return StoryReflectionResult.create({ violations, warnings });
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/gate-definition.ts

@@ -0,0 +1,127 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+import { GateName } from './gate-name.js';
+import { GateStoryAnnotation } from './gate-story-annotation.js';
+import { PhaseLevel } from './phase-level.js';
+
+export interface GateRequirement {
+  readonly path: string;
+  readonly required: boolean;
+}
+
+export interface GateDefinitionCreateArgs {
+  readonly name: GateName;
+  readonly level: PhaseLevel;
+  readonly requires: readonly GateRequirement[];
+  readonly blocks: readonly string[];
+  readonly dependsOn: readonly GateName[];
+  readonly storyAnnotation?: GateStoryAnnotation;
+}
+
+export class InvalidGateDefinitionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidGateDefinitionError';
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const parseRequirement = (raw: unknown): GateRequirement => {
+  if (!isRecord(raw) || typeof raw.path !== 'string' || typeof raw.required !== 'boolean') {
+    throw new InvalidGateDefinitionError('requires の形式が不正です');
+  }
+
+  const path = raw.path.trim();
+  if (path.length === 0) {
+    throw new InvalidGateDefinitionError('requires.path は必須です');
+  }
+
+  return Object.freeze({
+    path,
+    required: raw.required,
+  });
+};
+
+const parseStringArray = (raw: unknown, fieldName: string): readonly string[] => {
+  if (!Array.isArray(raw) || raw.some((entry) => typeof entry !== 'string')) {
+    throw new InvalidGateDefinitionError(`${fieldName} の形式が不正です`);
+  }
+
+  return Object.freeze(raw.map((entry) => entry.trim()));
+};
+
+export class GateDefinition {
+  readonly name: GateName;
+  readonly level: PhaseLevel;
+  readonly requires: readonly GateRequirement[];
+  readonly blocks: readonly string[];
+  readonly dependsOn: readonly GateName[];
+  readonly storyAnnotation?: GateStoryAnnotation;
+
+  private constructor(args: GateDefinitionCreateArgs) {
+    this.name = args.name;
+    this.level = args.level;
+    this.requires = Object.freeze([...args.requires]);
+    this.blocks = Object.freeze([...args.blocks]);
+    this.dependsOn = Object.freeze([...args.dependsOn]);
+    this.storyAnnotation = args.storyAnnotation;
+    Object.freeze(this);
+  }
+
+  static create(args: GateDefinitionCreateArgs): GateDefinition {
+    if (args.storyAnnotation && args.level.value !== 3) {
+      throw new InvalidGateDefinitionError('storyAnnotation は Level 3 のゲートにのみ指定できます');
+    }
+
+    return new GateDefinition(args);
+  }
+
+  static fromRaw(raw: unknown): GateDefinition {
+    if (!isRecord(raw)) {
+      throw new InvalidGateDefinitionError('GateDefinition の形式が不正です');
+    }
+
+    const name = GateName.create(String(raw.name ?? ''));
+    const level = PhaseLevel.create(Number(raw.level));
+    const requires = Array.isArray(raw.requires)
+      ? Object.freeze(raw.requires.map((requirement) => parseRequirement(requirement)))
+      : (() => {
+          throw new InvalidGateDefinitionError('requires の形式が不正です');
+        })();
+    const blocks = parseStringArray(raw.blocks ?? [], 'blocks');
+    const dependsOn = parseStringArray(raw.dependsOn ?? [], 'dependsOn').map((value) =>
+      GateName.create(value),
+    );
+    const storyAnnotation =
+      raw.storyAnnotation === undefined
+        ? undefined
+        : (() => {
+            if (
+              !isRecord(raw.storyAnnotation) ||
+              typeof raw.storyAnnotation.required !== 'boolean' ||
+              typeof raw.storyAnnotation.tag !== 'string'
+            ) {
+              throw new InvalidGateDefinitionError('storyAnnotation の形式が不正です');
+            }
+
+            return GateStoryAnnotation.create({
+              required: raw.storyAnnotation.required,
+              tag: raw.storyAnnotation.tag,
+            });
+          })();
+
+    return GateDefinition.create({
+      name,
+      level,
+      requires,
+      blocks,
+      dependsOn: Object.freeze(dependsOn),
+      storyAnnotation,
+    });
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/gate-name.ts

@@ -0,0 +1,40 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+const GATE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export class InvalidGateNameError extends Error {
+  constructor(value: string) {
+    super(`GateNameが不正です: ${value}`);
+    this.name = 'InvalidGateNameError';
+  }
+}
+
+export class GateName {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(value: string): GateName {
+    const normalizedValue = value.trim();
+
+    if (
+      normalizedValue.length === 0 ||
+      !GATE_NAME_PATTERN.test(normalizedValue) ||
+      normalizedValue.endsWith('-')
+    ) {
+      throw new InvalidGateNameError(value);
+    }
+
+    return new GateName(normalizedValue);
+  }
+
+  equals(other: GateName): boolean {
+    return this.value === other.value;
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/gate-story-annotation.ts

@@ -0,0 +1,39 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+export interface GateStoryAnnotationCreateArgs {
+  readonly required: boolean;
+  readonly tag: string;
+}
+
+export class InvalidGateStoryAnnotationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidGateStoryAnnotationError';
+  }
+}
+
+export class GateStoryAnnotation {
+  readonly required: boolean;
+  readonly tag: string;
+
+  private constructor(args: GateStoryAnnotationCreateArgs) {
+    this.required = args.required;
+    this.tag = args.tag.trim();
+    Object.freeze(this);
+  }
+
+  static create(args: GateStoryAnnotationCreateArgs): GateStoryAnnotation {
+    if (args.tag.trim().length === 0) {
+      throw new InvalidGateStoryAnnotationError('tagは必須です');
+    }
+
+    return new GateStoryAnnotation(args);
+  }
+
+  equals(other: GateStoryAnnotation): boolean {
+    return this.required === other.required && this.tag === other.tag;
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/phase-customization-policy.ts

@@ -5,19 +5,21 @@
 
 import { CustomRule } from './custom-rule.js';
 
+export type PresetName = 'full' | 'standard' | 'minimal' | 'custom';
+
 export interface PhaseCustomizationPolicyCreateArgs {
-  readonly preset?: 'default' | 'custom';
+  readonly preset?: PresetName | 'default';
   readonly rules: readonly CustomRule[];
   readonly overrideEnabled: boolean;
 }
 
 export class PhaseCustomizationPolicy {
-  readonly preset: 'default' | 'custom';
+  readonly preset: PresetName;
   readonly rules: readonly CustomRule[];
   readonly overrideEnabled: boolean;
 
   private constructor(args: {
-    readonly preset: 'default' | 'custom';
+    readonly preset: PresetName;
     readonly rules: readonly CustomRule[];
     readonly overrideEnabled: boolean;
   }) {
@@ -27,9 +29,19 @@ export class PhaseCustomizationPolicy {
     Object.freeze(this);
   }
 
+  private static resolvePreset(preset: PresetName | 'default' | undefined, hasRules: boolean): PresetName {
+    if (preset === undefined) {
+      return hasRules ? 'custom' : 'full';
+    }
+    if (preset === 'default') {
+      return 'full';
+    }
+    return preset;
+  }
+
   static create(args: PhaseCustomizationPolicyCreateArgs): PhaseCustomizationPolicy {
     return new PhaseCustomizationPolicy({
-      preset: args.preset ?? (args.rules.length === 0 ? 'default' : 'custom'),
+      preset: PhaseCustomizationPolicy.resolvePreset(args.preset, args.rules.length > 0),
       rules: args.rules,
       overrideEnabled: args.overrideEnabled,
     });

package/scripts/harness/phase-dependency-model/domain/values/story-reflection-config.ts

@@ -0,0 +1,44 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+import { StoryReflectionMapping } from './story-reflection-mapping.js';
+
+export interface StoryReflectionConfigCreateArgs {
+  readonly enabled: boolean;
+  readonly mappings: readonly StoryReflectionMapping[];
+}
+
+export class StoryReflectionConfig {
+  readonly enabled: boolean;
+  readonly mappings: readonly StoryReflectionMapping[];
+
+  private constructor(args: StoryReflectionConfigCreateArgs) {
+    this.enabled = args.enabled;
+    this.mappings = Object.freeze([...args.mappings]);
+    Object.freeze(this);
+  }
+
+  static create(args: StoryReflectionConfigCreateArgs): StoryReflectionConfig {
+    return new StoryReflectionConfig(args);
+  }
+
+  static disabled(): StoryReflectionConfig {
+    return new StoryReflectionConfig({ enabled: false, mappings: [] });
+  }
+
+  requiredMappings(): readonly StoryReflectionMapping[] {
+    return this.mappings.filter((m) => m.required);
+  }
+
+  optionalMappings(): readonly StoryReflectionMapping[] {
+    return this.mappings.filter((m) => !m.required);
+  }
+
+  equals(other: StoryReflectionConfig): boolean {
+    if (this.enabled !== other.enabled) return false;
+    if (this.mappings.length !== other.mappings.length) return false;
+    return this.mappings.every((m, i) => m.equals(other.mappings[i]));
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/story-reflection-mapping.ts

@@ -0,0 +1,91 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+export interface StoryReflectionMappingCreateArgs {
+  readonly inception: string;
+  readonly product: string;
+  readonly required: boolean;
+}
+
+export class InvalidStoryReflectionMappingError extends Error {
+  constructor(message: string) {
+    super(`StoryReflectionMapping が不正です: ${message}`);
+    this.name = 'InvalidStoryReflectionMappingError';
+  }
+}
+
+export class StoryReflectionMapping {
+  readonly inception: string;
+  readonly product: string;
+  readonly required: boolean;
+
+  private constructor(args: StoryReflectionMappingCreateArgs) {
+    this.inception = args.inception;
+    this.product = args.product;
+    this.required = args.required;
+    Object.freeze(this);
+  }
+
+  static create(args: StoryReflectionMappingCreateArgs): StoryReflectionMapping {
+    const inception = args.inception.trim();
+    const product = args.product.trim();
+
+    if (!inception.startsWith('docs/inception/')) {
+      throw new InvalidStoryReflectionMappingError(
+        `inception は docs/inception/ で始まる必要があります: ${inception}`,
+      );
+    }
+
+    if (!product.startsWith('docs/product/')) {
+      throw new InvalidStoryReflectionMappingError(
+        `product は docs/product/ で始まる必要があります: ${product}`,
+      );
+    }
+
+    if (!inception.includes('{storyId}')) {
+      throw new InvalidStoryReflectionMappingError(
+        `inception に {storyId} プレースホルダが必要です: ${inception}`,
+      );
+    }
+
+    if (!inception.includes('{unit}')) {
+      throw new InvalidStoryReflectionMappingError(
+        `inception に {unit} プレースホルダが必要です: ${inception}`,
+      );
+    }
+
+    if (!product.includes('{unit}')) {
+      throw new InvalidStoryReflectionMappingError(
+        `product に {unit} プレースホルダが必要です: ${product}`,
+      );
+    }
+
+    return new StoryReflectionMapping({
+      inception,
+      product,
+      required: args.required,
+    });
+  }
+
+  resolve(scope: { unitId: string; storyId: string }): { inception: string; product: string } {
+    const inception = this.inception
+      .replaceAll('{unit}', scope.unitId)
+      .replaceAll('{storyId}', scope.storyId);
+
+    const product = this.product
+      .replaceAll('{unit}', scope.unitId)
+      .replaceAll('{storyId}', scope.storyId);
+
+    return { inception, product };
+  }
+
+  equals(other: StoryReflectionMapping): boolean {
+    return (
+      this.inception === other.inception &&
+      this.product === other.product &&
+      this.required === other.required
+    );
+  }
+}