phasegate 0.150.1 → 0.151.0

package/scripts/harness/validator-system/domain/value-objects/contract-traceability-model.ts

@@ -0,0 +1,124 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-132 / WI-133 / WI-136 / WI-137 / WI-138
+
+export type PublicContractKind =
+  | 'cli-command'
+  | 'api-endpoint'
+  | 'port'
+  | 'config-option'
+  | 'domain-behavior'
+  | 'error-code';
+
+export type BoundaryCaseKind =
+  | 'empty-input'
+  | 'missing-required'
+  | 'invalid-enum'
+  | 'duplicate-id'
+  | 'unknown-reference'
+  | 'permission-denied'
+  | 'config-disabled'
+  | 'partial-failure'
+  | 'idempotency'
+  | 'backward-compatibility';
+
+export interface PublicContract {
+  readonly id: string;
+  readonly kind: PublicContractKind;
+  readonly sourcePath: string;
+  readonly requiredBehaviors: readonly string[];
+  readonly boundaryCases?: readonly BoundaryCaseKind[];
+}
+
+export interface TestObservation {
+  readonly id: string;
+  readonly kind: 'unit' | 'integration' | 'e2e' | 'adapter-contract';
+  readonly sourcePath: string;
+  readonly covers: readonly string[];
+}
+
+export interface ErrorContract {
+  readonly id: string;
+  readonly sourcePath: string;
+  readonly code?: string;
+  readonly severity?: 'error' | 'warning';
+  readonly message?: string;
+  readonly suggestion?: string;
+  readonly documentationRef?: string;
+  readonly exitCode?: number;
+  readonly machineFields?: readonly string[];
+}
+
+export interface StateTransition {
+  readonly from: string;
+  readonly to: string;
+  readonly guard?: string;
+}
+
+export interface StateMachineModel {
+  readonly id: string;
+  readonly sourcePath: string;
+  readonly docsStates: readonly string[];
+  readonly codeStates: readonly string[];
+  readonly transitions: readonly StateTransition[];
+  readonly terminalStates: readonly string[];
+  readonly invalidTransitions: readonly StateTransition[];
+}
+
+export interface TraceabilityGraphSlice {
+  readonly workItemId: string;
+  readonly affectedUnits: readonly string[];
+  readonly productUnits: readonly string[];
+  readonly implementationWorkItemIds: readonly string[];
+  readonly testWorkItemIds: readonly string[];
+  readonly publicDocsChanged: boolean;
+  readonly contractChanged: boolean;
+}
+
+export interface ContractTraceabilityInput {
+  readonly publicContracts: readonly PublicContract[];
+  readonly testObservations: readonly TestObservation[];
+  readonly errorContracts: readonly ErrorContract[];
+  readonly stateMachines: readonly StateMachineModel[];
+  readonly traceabilitySlices: readonly TraceabilityGraphSlice[];
+}
+
+export type ContractTraceabilityFindingKind =
+  | 'missing-required-behavior-test'
+  | 'missing-port-contract-test'
+  | 'missing-boundary-test'
+  | 'error-contract-shape'
+  | 'error-contract-exit-code'
+  | 'missing-error-path-test'
+  | 'state-doc-code-mismatch'
+  | 'state-invalid-terminal-transition'
+  | 'missing-transition-test'
+  | 'traceability-unit-mismatch'
+  | 'traceability-test-mismatch'
+  | 'public-doc-contract-sync';
+
+export interface ContractTraceabilityFinding {
+  readonly kind: ContractTraceabilityFindingKind;
+  readonly severity: 'error' | 'warning';
+  readonly subject: string;
+  readonly sourcePath: string;
+  readonly message: string;
+  readonly suggestion: string;
+}
+
+export class ContractTraceabilityReport {
+  readonly findings: readonly ContractTraceabilityFinding[];
+
+  private constructor(findings: readonly ContractTraceabilityFinding[]) {
+    this.findings = Object.freeze([...findings]);
+    Object.freeze(this);
+  }
+
+  static create(findings: readonly ContractTraceabilityFinding[]): ContractTraceabilityReport {
+    return new ContractTraceabilityReport(findings);
+  }
+
+  hasFindings(): boolean {
+    return this.findings.length > 0;
+  }
+}

package/scripts/harness/validator-system/domain/value-objects/semantic-drift-report.ts

@@ -0,0 +1,50 @@
+/**
+ * @layer domain
+ * @unit validator-system
+ * @work-item-id WI-139
+ */
+
+export type SemanticDriftKind =
+  | 'design-behavior-missing-code'
+  | 'design-behavior-missing-test'
+  | 'code-behavior-missing-design'
+  | 'code-behavior-missing-test'
+  | 'test-observation-missing-design';
+
+export interface SemanticDriftReportProps {
+  readonly kind: SemanticDriftKind;
+  readonly behaviorId: string;
+  readonly unitName: string;
+  readonly severity: 'warning' | 'error';
+  readonly location?: string;
+  readonly nextAction: string;
+}
+
+export class SemanticDriftReport {
+  readonly kind: SemanticDriftKind;
+  readonly behaviorId: string;
+  readonly unitName: string;
+  readonly severity: 'warning' | 'error';
+  readonly location: string | null;
+  readonly nextAction: string;
+
+  private constructor(props: SemanticDriftReportProps) {
+    this.kind = props.kind;
+    this.behaviorId = props.behaviorId;
+    this.unitName = props.unitName;
+    this.severity = props.severity;
+    this.location = props.location ?? null;
+    this.nextAction = props.nextAction;
+    Object.freeze(this);
+  }
+
+  static create(props: SemanticDriftReportProps): SemanticDriftReport {
+    if (props.behaviorId.trim().length === 0) {
+      throw new Error('behaviorId is required for semantic drift reports');
+    }
+    if (props.unitName.trim().length === 0) {
+      throw new Error('unitName is required for semantic drift reports');
+    }
+    return new SemanticDriftReport(props);
+  }
+}

package/scripts/harness/validator-system/domain/value-objects/validator-id.ts

@@ -7,6 +7,7 @@
  * L1-001〜L4-005 のバリデータを識別する不変値オブジェクト
  * Wave 2A で L1-017, L1-018, L2-013 を追加
  * WI-140 で L2-014 を追加
+ * WI-132/WI-133/WI-136/WI-137/WI-138 で L2-015 を追加
  */
 
 export class InvalidValidatorIdError extends Error {
@@ -29,6 +30,7 @@ const VALIDATOR_NAME_MAP: Record<string, string> = {
   'L2-003': 'test-quality',
   'L2-013': 'cli-e2e-test-existence',
   'L2-014': 'work-item-status-staleness',
+  'L2-015': 'contract-traceability-coverage',
   'L3-001': 'security',
   'L3-002': 'performance',
   'L3-003': 'coverage',

package/scripts/harness/validator-system/index.ts

@@ -18,6 +18,7 @@ export { LayerConfig } from './domain/value-objects/layer-config.js';
 export { DriftReport } from './domain/value-objects/drift-report.js';
 export { ConsistencyReport } from './domain/value-objects/consistency-report.js';
 export { DeadCodeReport } from './domain/value-objects/dead-code-report.js';
+export { SemanticDriftReport } from './domain/value-objects/semantic-drift-report.js';
 
 // --- Domain Services ---
 export { ValidatorRegistry, UnknownValidatorError } from './domain/services/validator-registry.js';
@@ -25,6 +26,7 @@ export { ValidatorExecutionService, ValidatorExecutionError } from './domain/ser
 export { DriftDetectionService } from './domain/services/l4/drift-detection-service.js';
 export { ConsistencyCheckService } from './domain/services/l4/consistency-check-service.js';
 export { DeadCodeDetectionService } from './domain/services/l4/dead-code-detection-service.js';
+export { SemanticDriftService } from './domain/services/l4/semantic-drift-service.js';
 
 // --- Application DTOs ---
 export type { ValidationResultContract } from './application/dto/validation-result-contract.js';

package/scripts/harness/validator-system/infrastructure/adapters/biome-ast-source-code-analyzer-adapter.ts

@@ -1,12 +1,14 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-117
  *
  * BiomeAstSourceCodeAnalyzerAdapter — SourceCodeAnalyzerPort実装
  * TypeScript Compiler API を使用してエクスポートを正確に抽出する（L4-001, L4-003）
  */
 import * as ts from 'typescript';
 import type { SourceCodeAnalyzerPort, SourceAnalysisResult } from '../../domain/ports/source-code-analyzer-port.js';
+import type { DriftElementRecord } from '../../domain/services/l4/drift-detection-service.js';
 import { readdir } from 'node:fs/promises';
 import { basename, join, relative, sep } from 'node:path';
 
@@ -44,7 +46,7 @@ export class BiomeAstSourceCodeAnalyzerAdapter implements SourceCodeAnalyzerPort
       const sourceFile = program.getSourceFile(filePath);
       if (!sourceFile) continue;
       results.push({
-        unitName: resolveUnitName(this.sourceRoot, filePath),
+        unitName: resolveUnitName(this.sourceRoot, filePath, sourceFile.text),
         filePath,
         exports: extractExports(sourceFile),
         imports: extractImports(sourceFile),
@@ -86,6 +88,17 @@ export class BiomeAstSourceCodeAnalyzerAdapter implements SourceCodeAnalyzerPort
     }
     return map;
   }
+
+  async getElementRecords(targetUnits?: readonly string[]): Promise<readonly DriftElementRecord[]> {
+    const results = await this.analyzeExports(targetUnits);
+    return results.flatMap((result) =>
+      result.exports.map((entry) => ({
+        element: entry.name,
+        unitName: result.unitName,
+        filePaths: [result.filePath],
+      }))
+    );
+  }
 }
 
 type ExportType = SourceAnalysisResult['exports'][number]['type'];
@@ -112,6 +125,19 @@ function extractExports(sourceFile: ts.SourceFile): SourceAnalysisResult['export
           exports.push({ name: decl.name.text, type: 'const' });
         }
       }
+    } else if (ts.isExportDeclaration(node) && node.exportClause) {
+      if (ts.isNamedExports(node.exportClause)) {
+        for (const element of node.exportClause.elements) {
+          exports.push({ name: element.name.text, type: 'type' });
+        }
+      }
+    } else if (ts.isExportDeclaration(node) && !node.exportClause && ts.isStringLiteral(node.moduleSpecifier)) {
+      exports.push({ name: `* from ${node.moduleSpecifier.text}`, type: 'type' });
+    }
+
+    const hasDefault = modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword) ?? false;
+    if (hasDefault) {
+      exports.push({ name: 'default', type: 'type' });
     }
   });
 
@@ -182,7 +208,10 @@ async function walkTsFiles(root: string, excludePattern: RegExp): Promise<string
   }
 }
 
-function resolveUnitName(sourceRoot: string, filePath: string): string {
+function resolveUnitName(sourceRoot: string, filePath: string, sourceText: string): string {
+  const unitMatch = /@unit\s+([a-z0-9-]+)/i.exec(sourceText);
+  if (unitMatch) return unitMatch[1];
+
   const relativePath = relative(sourceRoot, filePath);
   const [firstSegment] = relativePath.split(sep);
   return firstSegment || basename(filePath);

package/scripts/harness/validator-system/infrastructure/adapters/file-system-contract-traceability-policy-adapter.ts

@@ -0,0 +1,115 @@
+// @unit validator-system
+// @layer infrastructure
+// @work-item-id WI-132 / WI-133 / WI-136 / WI-137 / WI-138
+
+import { readFile } from 'node:fs/promises';
+import type { ContractTraceabilityPolicyPort } from '../../domain/ports/contract-traceability-policy-port.js';
+import type {
+  BoundaryCaseKind,
+  ContractTraceabilityInput,
+  PublicContract,
+  PublicContractKind,
+  TestObservation,
+} from '../../domain/value-objects/contract-traceability-model.js';
+
+const CONTRACT_KINDS = new Set<PublicContractKind>([
+  'cli-command',
+  'api-endpoint',
+  'port',
+  'config-option',
+  'domain-behavior',
+  'error-code',
+]);
+
+const BOUNDARY_KINDS = new Set<BoundaryCaseKind>([
+  'empty-input',
+  'missing-required',
+  'invalid-enum',
+  'duplicate-id',
+  'unknown-reference',
+  'permission-denied',
+  'config-disabled',
+  'partial-failure',
+  'idempotency',
+  'backward-compatibility',
+]);
+
+export class FileSystemContractTraceabilityPolicyAdapter implements ContractTraceabilityPolicyPort {
+  async collect(targetPaths: readonly string[]): Promise<ContractTraceabilityInput> {
+    const publicContracts: PublicContract[] = [];
+    const testObservations: TestObservation[] = [];
+
+    for (const targetPath of targetPaths) {
+      let content: string;
+      try {
+        content = await readFile(targetPath, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      publicContracts.push(...this.extractContracts(targetPath, content));
+      testObservations.push(...this.extractObservations(targetPath, content));
+    }
+
+    return {
+      publicContracts,
+      testObservations,
+      errorContracts: [],
+      stateMachines: [],
+      traceabilitySlices: [],
+    };
+  }
+
+  private extractContracts(sourcePath: string, content: string): readonly PublicContract[] {
+    return [...content.matchAll(/@phasegate-contract\s+([^\n\r*]+)/g)].flatMap((match) => {
+      const attrs = this.parseAttrs(match[1]);
+      const id = attrs.get('id');
+      const kind = attrs.get('kind');
+      if (!id || !this.isContractKind(kind)) return [];
+
+      return [{
+        id,
+        kind,
+        sourcePath,
+        requiredBehaviors: this.splitList(attrs.get('behaviors')),
+        boundaryCases: this.splitList(attrs.get('boundary')).filter(this.isBoundaryKind),
+      }];
+    });
+  }
+
+  private extractObservations(sourcePath: string, content: string): readonly TestObservation[] {
+    return [...content.matchAll(/@phasegate-observation\s+([^\n\r*]+)/g)].flatMap((match, index) => {
+      const attrs = this.parseAttrs(match[1]);
+      const covers = this.splitList(attrs.get('covers'));
+      if (covers.length === 0) return [];
+      const kind = attrs.get('kind');
+      return [{
+        id: attrs.get('id') ?? `${sourcePath}#observation-${index + 1}`,
+        kind: kind === 'adapter-contract' || kind === 'integration' || kind === 'e2e' ? kind : 'unit',
+        sourcePath,
+        covers,
+      }];
+    });
+  }
+
+  private parseAttrs(raw: string): Map<string, string> {
+    const attrs = new Map<string, string>();
+    for (const match of raw.matchAll(/([a-zA-Z][a-zA-Z0-9_-]*)=("[^"]*"|'[^']*'|[^\s]+)/g)) {
+      attrs.set(match[1], match[2].replace(/^['"]|['"]$/g, ''));
+    }
+    return attrs;
+  }
+
+  private splitList(raw: string | undefined): string[] {
+    if (!raw) return [];
+    return raw.split(',').map((value) => value.trim()).filter((value) => value.length > 0);
+  }
+
+  private isContractKind(value: string | undefined): value is PublicContractKind {
+    return value !== undefined && CONTRACT_KINDS.has(value as PublicContractKind);
+  }
+
+  private isBoundaryKind(value: string): value is BoundaryCaseKind {
+    return BOUNDARY_KINDS.has(value as BoundaryCaseKind);
+  }
+}

package/scripts/harness/validator-system/infrastructure/adapters/harness-config-validator-config-adapter.ts

@@ -38,7 +38,7 @@ export class HarnessConfigValidatorConfigAdapter implements ValidatorConfigPort
     const layerData = this.config.layers?.[layer] ?? {};
 
     const defaultValidators: Record<string, string[]> = {
-      L2: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014'],
+      L2: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'],
       L3: ['L3-001', 'L3-002', 'L3-003', 'L3-004'],
       L4: ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005'],
     };

package/scripts/harness/validator-system/infrastructure/adapters/markdown-design-document-adapter.ts

@@ -1,14 +1,25 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-117, WI-118
  *
  * MarkdownDesignDocumentAdapter — DesignDocumentPort実装
  */
 import type { DesignDocumentPort, StructuredDesignDoc } from '../../domain/ports/design-document-port.js';
+import type { DriftElementRecord } from '../../domain/services/l4/drift-detection-service.js';
 import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 const ADR_PATTERN = /ADR-\d{3}/g;
+const WORK_ITEM_PATTERN = /@work-item-id\s+(WI-\d{3})/g;
+const LAYER_PATTERN = /@layer\s+([a-z0-9-]+)/gi;
+const UNIT_PATTERN = /@unit\s+([a-z0-9-]+)/gi;
+const CONSTRUCTION_DOC_NAMES = [
+  'domain_model.md',
+  'logical_design.md',
+  'unit_test_design.md',
+  'it_test_design.md',
+];
 
 // ISSUE-005 P3-8: メタ見出し / 議論用セクションを drift 対象から除外するマーカー。
 // 見出し行の直後 (同一行末 or 次の非空行) に置かれたコメントを拾う。
@@ -111,26 +122,28 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     const results: StructuredDesignDoc[] = [];
 
     for (const unitName of unitNames) {
-      const docPath = join(this.docsRoot, unitName, 'domain_model.md');
-      const cached = this.cache.get(docPath);
-      if (cached) {
-        results.push(cached);
-        continue;
-      }
+      for (const docName of CONSTRUCTION_DOC_NAMES) {
+        const docPath = join(this.docsRoot, unitName, docName);
+        const cached = this.cache.get(docPath);
+        if (cached) {
+          results.push(cached);
+          continue;
+        }
 
-      try {
-        const markdown = await readFile(docPath, 'utf8');
-        const doc: StructuredDesignDoc = {
-          unitName,
-          docPath,
-          concepts: extractConcepts(markdown).map((concept) => ({ ...concept, type: 'class' })),
-          layerDependencies: [],
-          adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
-        };
-        this.cache.set(docPath, doc);
-        results.push(doc);
-      } catch {
-        continue;
+        try {
+          const markdown = await readFile(docPath, 'utf8');
+          const doc: StructuredDesignDoc = {
+            unitName,
+            docPath,
+            concepts: extractConcepts(markdown).map((concept) => ({ ...concept, type: 'class' })),
+            layerDependencies: extractLayerDependencies(markdown),
+            adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
+          };
+          this.cache.set(docPath, doc);
+          results.push(doc);
+        } catch {
+          continue;
+        }
       }
     }
 
@@ -138,7 +151,32 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
   }
 
   async getLayerAnnotations(targetDocs?: readonly string[]): Promise<Record<string, string>> {
-    return {};
+    const docs = targetDocs && targetDocs.length > 0
+      ? await this.loadExplicitDocs(targetDocs)
+      : await this.loadDesignDocuments();
+    const annotations: Record<string, string> = {};
+
+    for (const doc of docs) {
+      const markdown = await readFile(doc.docPath, 'utf8');
+      const layers = Array.from(new Set(Array.from(markdown.matchAll(LAYER_PATTERN)).map((match) => match[1])));
+      const units = Array.from(new Set(Array.from(markdown.matchAll(UNIT_PATTERN)).map((match) => match[1])));
+      const workItems = Array.from(new Set(Array.from(markdown.matchAll(WORK_ITEM_PATTERN)).map((match) => match[1])));
+
+      for (const layer of layers) {
+        annotations[`${doc.docPath}#layer:${layer}`] = isKnownLayer(layer) ? 'layer:known' : 'layer:unknown';
+      }
+      for (const unit of units) {
+        annotations[`${doc.docPath}#unit:${unit}`] = unit === doc.unitName ? 'unit:matched' : `unit:mismatch:${doc.unitName}`;
+      }
+      for (const adrRef of doc.adrRefs) {
+        annotations[adrRef] = 'adr:referenced';
+      }
+      for (const workItemId of workItems) {
+        annotations[`${doc.docPath}#work-item:${workItemId}`] = 'work-item:referenced';
+      }
+    }
+
+    return annotations;
   }
 
   async getElements(targetUnits?: readonly string[]): Promise<string[]> {
@@ -146,6 +184,17 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     return docs.flatMap((doc) => doc.concepts.map((concept) => concept.name));
   }
 
+  async getElementRecords(targetUnits?: readonly string[]): Promise<readonly DriftElementRecord[]> {
+    const docs = await this.loadDesignDocuments(targetUnits);
+    return docs.flatMap((doc) =>
+      doc.concepts.map((concept) => ({
+        element: concept.name,
+        unitName: doc.unitName,
+        pointers: concept.pointers ?? [],
+      }))
+    );
+  }
+
   async getElementPointers(targetUnits?: readonly string[]): Promise<Record<string, readonly string[]>> {
     const docs = await this.loadDesignDocuments(targetUnits);
     const map: Record<string, readonly string[]> = {};
@@ -176,6 +225,26 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     return map;
   }
 
+  private async loadExplicitDocs(targetDocs: readonly string[]): Promise<readonly StructuredDesignDoc[]> {
+    const docs: StructuredDesignDoc[] = [];
+    for (const docPath of targetDocs) {
+      try {
+        const markdown = await readFile(docPath, 'utf8');
+        const unitName = inferUnitNameFromDocPath(this.docsRoot, docPath);
+        docs.push({
+          unitName,
+          docPath,
+          concepts: extractConcepts(markdown).map((concept) => ({ ...concept, type: 'class' })),
+          layerDependencies: extractLayerDependencies(markdown),
+          adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
+        });
+      } catch {
+        continue;
+      }
+    }
+    return docs;
+  }
+
   private async listUnitNames(): Promise<string[]> {
     try {
       const entries = await readdir(this.docsRoot, { withFileTypes: true });
@@ -185,3 +254,25 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     }
   }
 }
+
+function extractLayerDependencies(markdown: string): Array<{ from: string; to: string }> {
+  const dependencies: Array<{ from: string; to: string }> = [];
+  const dependencyPattern = /([a-z0-9-]+)\s*(?:->|→)\s*([a-z0-9-]+)/gi;
+  for (const match of markdown.matchAll(dependencyPattern)) {
+    dependencies.push({ from: match[1], to: match[2] });
+  }
+  return dependencies;
+}
+
+function isKnownLayer(layer: string): boolean {
+  return ['domain', 'application', 'infrastructure', 'presentation', 'test'].includes(layer);
+}
+
+function inferUnitNameFromDocPath(docsRoot: string, docPath: string): string {
+  const normalizedRoot = docsRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+  const normalizedPath = docPath.replace(/\\/g, '/');
+  const relativePath = normalizedPath.startsWith(`${normalizedRoot}/`)
+    ? normalizedPath.slice(normalizedRoot.length + 1)
+    : normalizedPath;
+  return relativePath.split('/')[0] || 'unknown';
+}