phasegate 0.15.0

package/scripts/harness/biome-ast-engine/domain/value-objects/rule-violation.ts

@@ -0,0 +1,118 @@
+/**
+ * @layer domain
+ * @unit biome-ast-engine
+ */
+
+import { FilePath } from './file-path.js';
+import { RuleName } from './rule-name.js';
+
+export type RuleViolationSeverity = 'error' | 'warning';
+
+type RuleViolationProps = {
+  readonly filePath: FilePath;
+  readonly line: number;
+  readonly column: number;
+  readonly ruleName: RuleName;
+  readonly message: string;
+  readonly severity: RuleViolationSeverity;
+  readonly fixExample?: string | null;
+};
+
+const VALID_SEVERITIES = new Set<RuleViolationSeverity>(['error', 'warning']);
+
+export class RuleViolation {
+  readonly filePath: FilePath;
+  readonly line: number;
+  readonly column: number;
+  readonly ruleName: RuleName;
+  readonly message: string;
+  readonly severity: RuleViolationSeverity;
+  readonly fixExample: string | null;
+
+  private constructor(props: Required<RuleViolationProps>) {
+    this.filePath = props.filePath;
+    this.line = props.line;
+    this.column = props.column;
+    this.ruleName = props.ruleName;
+    this.message = props.message;
+    this.severity = props.severity;
+    this.fixExample = props.fixExample;
+  }
+
+  static create(props: RuleViolationProps): RuleViolation {
+    if (props.line < 1) {
+      throw new Error('line must be greater than or equal to 1');
+    }
+
+    if (props.column < 1) {
+      throw new Error('column must be greater than or equal to 1');
+    }
+
+    if (props.message.length === 0) {
+      throw new Error('message must not be empty');
+    }
+
+    if (!VALID_SEVERITIES.has(props.severity)) {
+      throw new Error(`Invalid rule violation severity: ${props.severity}`);
+    }
+
+    return Object.freeze(
+      new RuleViolation({
+        ...props,
+        fixExample: props.fixExample ?? null,
+      })
+    );
+  }
+
+  equals(other: RuleViolation): boolean {
+    return (
+      this.filePath.equals(other.filePath) &&
+      this.line === other.line &&
+      this.column === other.column &&
+      this.ruleName.equals(other.ruleName) &&
+      this.message === other.message &&
+      this.severity === other.severity &&
+      this.fixExample === other.fixExample
+    );
+  }
+
+  withFixExample(fixExample: string): RuleViolation {
+    return RuleViolation.create({
+      filePath: this.filePath,
+      line: this.line,
+      column: this.column,
+      ruleName: this.ruleName,
+      message: this.message,
+      severity: this.severity,
+      fixExample,
+    });
+  }
+
+  toContract(): {
+    filePath: string;
+    line: number;
+    column: number;
+    ruleName: string;
+    message: string;
+    severity: RuleViolationSeverity;
+    fix_example?: string;
+  } {
+    const contract = {
+      filePath: this.filePath.toString(),
+      line: this.line,
+      column: this.column,
+      ruleName: this.ruleName.toString(),
+      message: this.message,
+      severity: this.severity,
+    };
+
+    if (this.fixExample === null) {
+      return contract;
+    }
+
+    return {
+      ...contract,
+      fix_example: this.fixExample,
+    };
+  }
+}

package/scripts/harness/biome-ast-engine/domain/value-objects/source-module-snapshot.ts

@@ -0,0 +1,133 @@
+/**
+ * @layer domain
+ * @unit biome-ast-engine
+ */
+
+import { FilePath } from './file-path.js';
+import { ImportEdge } from './import-edge.js';
+import { LayerName } from './layer-name.js';
+
+type SourceModuleSnapshotProps = {
+  readonly filePath: FilePath;
+  readonly declaredUnit: string | null;
+  readonly declaredLayer: LayerName | string | null;
+  readonly imports: readonly ImportEdge[];
+  readonly anyTypeCount: number;
+  readonly typedNodeCount: number;
+  readonly commentLineCount: number;
+  readonly logicalLineCount: number;
+  readonly repeatedCommentBlocks: number;
+  readonly duplicationFingerprints: readonly string[];
+  readonly exportedSymbols: readonly string[];
+  readonly isEntrypointCandidate: boolean;
+};
+
+const ensureNonNegative = (value: number, label: string): number => {
+  if (value < 0) {
+    throw new Error(`${label} must be greater than or equal to zero`);
+  }
+
+  return value;
+};
+
+const normalizeDeclaredLayer = (value: LayerName | string | null): LayerName | null => {
+  if (value === null) {
+    return null;
+  }
+
+  if (value instanceof LayerName) {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    return LayerName.tryFromString(value);
+  }
+
+  return null;
+};
+
+export class SourceModuleSnapshot {
+  readonly filePath: FilePath;
+  readonly declaredUnit: string | null;
+  readonly declaredLayer: LayerName | null;
+  readonly imports: readonly ImportEdge[];
+  readonly anyTypeCount: number;
+  readonly typedNodeCount: number;
+  readonly commentLineCount: number;
+  readonly logicalLineCount: number;
+  readonly repeatedCommentBlocks: number;
+  readonly duplicationFingerprints: readonly string[];
+  readonly exportedSymbols: readonly string[];
+  readonly isEntrypointCandidate: boolean;
+
+  private constructor(props: Omit<SourceModuleSnapshotProps, 'declaredLayer'> & { declaredLayer: LayerName | null }) {
+    this.filePath = props.filePath;
+    this.declaredUnit = props.declaredUnit;
+    this.declaredLayer = props.declaredLayer;
+    this.imports = props.imports;
+    this.anyTypeCount = props.anyTypeCount;
+    this.typedNodeCount = props.typedNodeCount;
+    this.commentLineCount = props.commentLineCount;
+    this.logicalLineCount = props.logicalLineCount;
+    this.repeatedCommentBlocks = props.repeatedCommentBlocks;
+    this.duplicationFingerprints = props.duplicationFingerprints;
+    this.exportedSymbols = props.exportedSymbols;
+    this.isEntrypointCandidate = props.isEntrypointCandidate;
+  }
+
+  static create(props: SourceModuleSnapshotProps): SourceModuleSnapshot {
+    const declaredLayer = normalizeDeclaredLayer(props.declaredLayer);
+
+    return Object.freeze(
+      new SourceModuleSnapshot({
+        filePath: props.filePath,
+        declaredUnit: props.declaredUnit,
+        declaredLayer,
+        imports: Object.freeze([...props.imports]),
+        anyTypeCount: ensureNonNegative(props.anyTypeCount, 'anyTypeCount'),
+        typedNodeCount: ensureNonNegative(props.typedNodeCount, 'typedNodeCount'),
+        commentLineCount: ensureNonNegative(props.commentLineCount, 'commentLineCount'),
+        logicalLineCount: ensureNonNegative(props.logicalLineCount, 'logicalLineCount'),
+        repeatedCommentBlocks: ensureNonNegative(
+          props.repeatedCommentBlocks,
+          'repeatedCommentBlocks'
+        ),
+        duplicationFingerprints: Object.freeze([...props.duplicationFingerprints]),
+        exportedSymbols: Object.freeze([...props.exportedSymbols]),
+        isEntrypointCandidate: props.isEntrypointCandidate,
+      })
+    );
+  }
+
+  hasUnitComment(): boolean {
+    return this.declaredUnit !== null;
+  }
+
+  hasLayerComment(): boolean {
+    return this.declaredLayer !== null;
+  }
+
+  anyRatio(): number {
+    if (this.typedNodeCount === 0) {
+      return 0;
+    }
+
+    return this.anyTypeCount / this.typedNodeCount;
+  }
+
+  commentDensity(): number {
+    if (this.logicalLineCount === 0) {
+      return 0;
+    }
+
+    return this.commentLineCount / this.logicalLineCount;
+  }
+
+  belongsToLayerDirectory(): boolean {
+    if (this.declaredLayer === null) {
+      return false;
+    }
+
+    return this.filePath.segments().includes(this.declaredLayer.toPathSegment());
+  }
+}

package/scripts/harness/biome-ast-engine/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @layer public-api
+ * @unit biome-ast-engine
+ *
+ * biome-ast-engine ユニットのバレルエクスポート。
+ */
+
+// Composition Root
+export { createBiomeAstEngineModule } from './composition-root.js';
+
+// Presentation — CLI handler
+export { HarnessLintCommandHandler } from './presentation/cli/harness-lint-command-handler.js';

package/scripts/harness/biome-ast-engine/infrastructure/adapters/biome-cli-executor-adapter.ts

@@ -0,0 +1,62 @@
+/**
+ * @layer infrastructure
+ * @unit biome-ast-engine
+ */
+
+import { spawnSync } from 'node:child_process';
+import type { FilePath } from '../../domain/value-objects/file-path.js';
+import type { BiomeExecutorPort } from '../../domain/ports/biome-executor-port.js';
+
+export class BiomeCliExecutionError extends Error {
+  constructor(
+    readonly exitCode: number,
+    readonly stderr: string
+  ) {
+    super(`biome check failed with exit code ${exitCode}: ${stderr}`);
+    this.name = 'BiomeCliExecutionError';
+  }
+}
+
+export interface BiomeCliExecutorAdapterDeps {
+  readonly cwd: string;
+  readonly biomeBin?: string;
+}
+
+/**
+ * BiomeExecutorPort の実装。
+ * `biome check --reporter json` をサブプロセスで実行する。
+ * 終了コードが 0 以外の場合は BiomeCliExecutionError をスローする。
+ * 診断結果の RuleViolation への変換は行わない。
+ */
+export class BiomeCliExecutorAdapter implements BiomeExecutorPort {
+  private readonly cwd: string;
+  private readonly biomeBin: string;
+
+  constructor(deps: BiomeCliExecutorAdapterDeps) {
+    this.cwd = deps.cwd;
+    this.biomeBin = deps.biomeBin ?? 'npx';
+  }
+
+  async executeCheck(files: readonly FilePath[]): Promise<void> {
+    const fileArgs = files.map((f) => f.toString());
+
+    const isNpx = this.biomeBin === 'npx';
+    const command = isNpx ? 'npx' : this.biomeBin;
+    const args = isNpx
+      ? ['biome', 'check', '--reporter', 'json', ...fileArgs]
+      : ['check', '--reporter', 'json', ...fileArgs];
+
+    const result = spawnSync(command, args, {
+      cwd: this.cwd,
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    // exit 0 = no issues, exit 1 = lint violations found (normal result)
+    // exit >= 2 = biome internal error
+    const exitCode = result.status ?? 1;
+    if (exitCode >= 2) {
+      throw new BiomeCliExecutionError(exitCode, result.stderr ?? '');
+    }
+  }
+}

package/scripts/harness/biome-ast-engine/infrastructure/adapters/harness-config-provider-adapter.ts

@@ -0,0 +1,38 @@
+/**
+ * @layer infrastructure
+ * @unit biome-ast-engine
+ */
+
+import type { RuleConfigProviderPort } from '../../domain/ports/rule-config-provider-port.js';
+
+export interface L1ConfigInput {
+  readonly enabled: boolean;
+  readonly rules: Record<string, 'error' | 'warning' | 'off'>;
+}
+
+const DEFAULT_L1_CONFIG: L1ConfigInput = {
+  enabled: true,
+  rules: {},
+};
+
+/**
+ * RuleConfigProviderPort の実装。
+ * 外部から L1 設定を注入可能。未指定時はデフォルト（enabled: true, rules: {} — 全ルールデフォルト有効）。
+ */
+export class HarnessConfigProviderAdapter implements RuleConfigProviderPort {
+  private readonly l1Config: L1ConfigInput;
+
+  constructor(injectedL1Config?: L1ConfigInput) {
+    this.l1Config = injectedL1Config ?? DEFAULT_L1_CONFIG;
+  }
+
+  async getL1Config(): Promise<{
+    enabled: boolean;
+    rules: Record<string, 'error' | 'warning' | 'off'>;
+  }> {
+    return {
+      enabled: this.l1Config.enabled,
+      rules: { ...this.l1Config.rules },
+    };
+  }
+}

package/scripts/harness/biome-ast-engine/infrastructure/adapters/harness-error-formatter-adapter.ts

@@ -0,0 +1,67 @@
+/**
+ * @layer infrastructure
+ * @unit biome-ast-engine
+ */
+
+import type { RuleViolation } from '../../domain/value-objects/rule-violation.js';
+import type { ViolationFormatterPort } from '../../domain/ports/violation-formatter-port.js';
+import { mapRuleNameToCode } from '../mappers/rule-violation-code-mapper.js';
+
+const RULE_SUGGESTIONS: Readonly<Record<string, string>> = {
+  'require-unit-comment': 'ファイル先頭に @unit コメントを追加する',
+  'require-layer-comment': 'ファイル先頭に @layer コメントを追加する',
+  'no-layer-violation': '依存方向をアーキテクチャ方針に合わせる',
+  'enforce-folder-structure': '宣言レイヤーと配置ディレクトリを一致させる',
+  'no-any-abuse': '型注釈を追加してanyを削減する',
+  'no-code-duplication': '共通化または抽象化を行う',
+  'no-ghost-file': '参照されないファイルを削除またはエントリポイントとして扱う',
+  'no-comment-flood': '不要なコメントを整理し自己説明的なコードへ改善する',
+};
+
+/**
+ * ViolationFormatterPort の実装。
+ * RuleViolation をルール名から L1-001〜L1-008 コードへマッピングし、
+ * 人間可読な出力形式へ変換する。
+ */
+export class HarnessErrorFormatterAdapter implements ViolationFormatterPort {
+  async format(
+    violations: readonly RuleViolation[]
+  ): Promise<
+    readonly {
+      code: string;
+      severity: 'error' | 'warning';
+      message: string;
+      suggestion: string;
+      adr_ref?: string;
+      fix_example?: string;
+    }[]
+  > {
+    return Object.freeze(
+      violations.map((v) => {
+        const ruleName = v.ruleName.toString();
+        const code = mapRuleNameToCode(ruleName);
+        const suggestion = RULE_SUGGESTIONS[ruleName] ?? '';
+
+        const entry: {
+          code: string;
+          severity: 'error' | 'warning';
+          message: string;
+          suggestion: string;
+          adr_ref?: string;
+          fix_example?: string;
+        } = {
+          code,
+          severity: v.severity,
+          message: `${v.filePath.toString()}:${v.line}:${v.column} ${v.message}`,
+          suggestion,
+        };
+
+        if (v.fixExample !== null) {
+          entry.fix_example = v.fixExample;
+        }
+
+        return Object.freeze(entry);
+      })
+    );
+  }
+}

package/scripts/harness/biome-ast-engine/infrastructure/adapters/node-workspace-file-adapter.ts

@@ -0,0 +1,110 @@
+/**
+ * @layer infrastructure
+ * @unit biome-ast-engine
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import type { FilePath } from '../../domain/value-objects/file-path.js';
+import { FilePath as FilePathVO } from '../../domain/value-objects/file-path.js';
+import type { WorkspaceFilePort } from '../../domain/ports/workspace-file-port.js';
+
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'coverage', '__fixtures__']);
+
+export interface NodeWorkspaceFileAdapterDeps {
+  readonly rootDir: string;
+}
+
+/**
+ * WorkspaceFilePort の実装。
+ * scripts/harness/ 配下の .ts/.tsx/.mts/.cts ファイルを列挙する。
+ * node_modules, dist, coverage, __fixtures__ は除外する。
+ */
+export class NodeWorkspaceFileAdapter implements WorkspaceFilePort {
+  private readonly rootDir: string;
+
+  constructor(deps: NodeWorkspaceFileAdapterDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async listSourceFiles(targets?: readonly string[]): Promise<readonly FilePath[]> {
+    if (targets && targets.length > 0) {
+      const results: FilePath[] = [];
+      for (const target of targets) {
+        const absoluteTarget = path.resolve(this.rootDir, target);
+        if (!fs.existsSync(absoluteTarget)) continue;
+        const fileStat = await stat(absoluteTarget);
+        if (fileStat.isDirectory()) {
+          await this.walkDirectory(absoluteTarget, results);
+        } else {
+          const ext = path.extname(target);
+          if (SOURCE_EXTENSIONS.has(ext)) {
+            const relative = path.relative(this.rootDir, absoluteTarget);
+            try {
+              results.push(FilePathVO.fromWorkspaceRelative(relative));
+            } catch {
+              // invalid path — skip
+            }
+          }
+        }
+      }
+      return Object.freeze(results);
+    }
+
+    const absoluteBase = path.resolve(this.rootDir, 'scripts/harness');
+    if (!fs.existsSync(absoluteBase)) {
+      return Object.freeze([]);
+    }
+
+    const results: FilePath[] = [];
+    await this.walkDirectory(absoluteBase, results);
+
+    return Object.freeze(results);
+  }
+
+  async readText(filePath: FilePath): Promise<string> {
+    const absolutePath = path.resolve(this.rootDir, filePath.toString());
+
+    return readFile(absolutePath, 'utf8');
+  }
+
+  async exists(filePath: FilePath): Promise<boolean> {
+    const absolutePath = path.resolve(this.rootDir, filePath.toString());
+
+    return fs.existsSync(absolutePath);
+  }
+
+  private async walkDirectory(dir: string, results: FilePath[]): Promise<void> {
+    const entries = await readdir(dir);
+
+    for (const entry of entries) {
+      if (EXCLUDED_DIRS.has(entry)) {
+        continue;
+      }
+
+      const fullPath = path.join(dir, entry);
+      const fileStat = await stat(fullPath);
+
+      if (fileStat.isDirectory()) {
+        await this.walkDirectory(fullPath, results);
+        continue;
+      }
+
+      const ext = path.extname(entry);
+
+      if (!SOURCE_EXTENSIONS.has(ext)) {
+        continue;
+      }
+
+      const relative = path.relative(this.rootDir, fullPath);
+
+      try {
+        results.push(FilePathVO.fromWorkspaceRelative(relative));
+      } catch {
+        // invalid path — skip
+      }
+    }
+  }
+}

package/scripts/harness/biome-ast-engine/infrastructure/adapters/system-clock-adapter.ts

@@ -0,0 +1,16 @@
+/**
+ * @layer infrastructure
+ * @unit biome-ast-engine
+ */
+
+import type { ClockPort } from '../../domain/ports/clock-port.js';
+
+/**
+ * ClockPort の実装。
+ * Date.now() を返す。
+ */
+export class SystemClockAdapter implements ClockPort {
+  now(): number {
+    return Date.now();
+  }
+}