phasegate 0.222.0 → 0.254.0

package/scripts/harness/traceability-model/infrastructure/adapters/file-system-traceability-world-read-adapter.ts

@@ -0,0 +1,223 @@
+// @unit traceability-model
+// @layer infrastructure
+// @work-item-id WI-288
+
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import type {
+  RawTraceabilityDiagnostic,
+  RawTraceabilityStory,
+  RawTraceabilityTestAnnotation,
+  RawTraceabilityUnit,
+  RawTraceabilityWorkItem,
+  TraceabilityWorldReadSourceDto,
+  TraceabilityWorldReadSourcePort,
+} from "../../application/ports/traceability-world-read-source-port.js";
+import type { MarkdownUnitDefinitionGateway } from "../gateways/markdown-unit-definition-gateway.js";
+import { parseTestTags } from "../parsers/source-metadata-parser.js";
+import { parseStoryCatalogEntries } from "../parsers/story-catalog-parser.js";
+import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parser.js";
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const toProjectRelativePath = (rootDir: string, absolutePath: string): string =>
+  path.relative(rootDir, absolutePath).split(path.sep).join("/");
+
+const collectFiles = async (rootDir: string, accept: (fileName: string) => boolean): Promise<readonly string[]> => {
+  const result: string[] = [];
+  const visit = async (directory: string): Promise<void> => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => compareStrings(left.name, right.name));
+    for (const entry of entries) {
+      const absolutePath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(absolutePath);
+      } else if (entry.isFile() && accept(entry.name)) {
+        result.push(absolutePath);
+      }
+    }
+  };
+  await visit(rootDir);
+  return result;
+};
+
+const sourceDiagnostic = (
+  code: string,
+  subjectId: string | null,
+  sourcePaths: readonly string[],
+  error: unknown,
+): RawTraceabilityDiagnostic => ({
+  code,
+  subjectId,
+  sourcePaths,
+  message: error instanceof Error ? error.message : String(error),
+});
+
+const classifyTestType = (filePath: string): RawTraceabilityTestAnnotation["testType"] => {
+  if (filePath.includes("/e2e/") || filePath.includes("/scenario/")) {
+    return "scenario";
+  }
+  if (filePath.includes("/integration/") || /\.it\.test\.[cm]?[jt]sx?$/.test(filePath)) {
+    return "it";
+  }
+  return "unit";
+};
+
+export interface FileSystemTraceabilityWorldReadAdapterDeps {
+  readonly rootDir: string;
+  readonly productDocsRoot: string;
+  readonly designDocsRoot: string;
+  readonly storyCatalogPath: string;
+  readonly inceptionRoot: string;
+  readonly testRoots: readonly string[];
+  readonly unitDefinitionGateway: MarkdownUnitDefinitionGateway;
+}
+
+export class FileSystemTraceabilityWorldReadAdapter implements TraceabilityWorldReadSourcePort {
+  private readonly deps: FileSystemTraceabilityWorldReadAdapterDeps;
+
+  constructor(deps: FileSystemTraceabilityWorldReadAdapterDeps) {
+    this.deps = deps;
+  }
+
+  async read(): Promise<TraceabilityWorldReadSourceDto> {
+    const diagnostics: RawTraceabilityDiagnostic[] = [];
+    const [units, stories, workItems, testAnnotations] = await Promise.all([
+      this.readUnits(diagnostics),
+      this.readStories(diagnostics),
+      this.readWorkItems(diagnostics),
+      this.readTestAnnotations(diagnostics),
+    ]);
+    return {
+      units,
+      stories,
+      workItems,
+      testAnnotations,
+      diagnostics,
+    };
+  }
+
+  private async readUnits(diagnostics: RawTraceabilityDiagnostic[]): Promise<readonly RawTraceabilityUnit[]> {
+    try {
+      const unitIds = await this.deps.unitDefinitionGateway.getAllUnitNames();
+      const result: RawTraceabilityUnit[] = [];
+      for (const unitId of unitIds) {
+        const constructionRoot = await this.deps.unitDefinitionGateway.findConstructionRoot(unitId);
+        result.push({
+          unitId,
+          definitionPath: path.posix.join(this.deps.productDocsRoot, "units", `${unitId}_unit.md`),
+          constructionRoot: constructionRoot?.value ?? null,
+        });
+      }
+      return result;
+    } catch (error) {
+      diagnostics.push(
+        sourceDiagnostic(
+          "TM-WORLD-READ-UNIT-SOURCE-ERROR",
+          null,
+          [path.posix.join(this.deps.productDocsRoot, "units")],
+          error,
+        ),
+      );
+      return [];
+    }
+  }
+
+  private async readStories(diagnostics: RawTraceabilityDiagnostic[]): Promise<readonly RawTraceabilityStory[]> {
+    try {
+      const absolutePath = path.join(this.deps.rootDir, this.deps.storyCatalogPath);
+      const content = await readFile(absolutePath, "utf8");
+      return parseStoryCatalogEntries(content).map((entry) => ({
+        storyId: entry.storyId,
+        legacyIds: [...entry.legacyIds],
+        sourcePath: this.deps.storyCatalogPath,
+        line: entry.lineNumber,
+        acceptanceCriteria: entry.acceptanceCriteria.map((criterion) => ({
+          acId: criterion.acId,
+          line: criterion.lineNumber,
+        })),
+      }));
+    } catch (error) {
+      diagnostics.push(sourceDiagnostic("TM-WORLD-READ-STORY-SOURCE-ERROR", null, [this.deps.storyCatalogPath], error));
+      return [];
+    }
+  }
+
+  private async readWorkItems(diagnostics: RawTraceabilityDiagnostic[]): Promise<readonly RawTraceabilityWorkItem[]> {
+    const absoluteRoot = path.join(this.deps.rootDir, this.deps.inceptionRoot);
+    let files: readonly string[];
+    try {
+      files = await collectFiles(absoluteRoot, (fileName) => fileName === "description.md");
+    } catch (error) {
+      diagnostics.push(
+        sourceDiagnostic("TM-WORLD-READ-WORK-ITEM-SOURCE-ERROR", null, [this.deps.inceptionRoot], error),
+      );
+      return [];
+    }
+
+    const result: RawTraceabilityWorkItem[] = [];
+    for (const absolutePath of files) {
+      const directoryId = path.basename(path.dirname(absolutePath));
+      if (!/^WI-/.test(directoryId)) continue;
+      const relativePath = toProjectRelativePath(this.deps.rootDir, absolutePath);
+      try {
+        const frontmatter = parseWorkItemFrontmatter(await readFile(absolutePath, "utf8"));
+        if (!frontmatter) {
+          diagnostics.push({
+            code: "TM-WORLD-READ-MISSING-WORK-ITEM-FRONTMATTER",
+            subjectId: directoryId,
+            sourcePaths: [relativePath],
+            message: `WorkItem ${directoryId} has no readable frontmatter`,
+          });
+          continue;
+        }
+        result.push({
+          directoryId,
+          workItemId: frontmatter.id,
+          legacyId: frontmatter.legacyId ?? null,
+          type: frontmatter.type,
+          severity: frontmatter.severity ?? null,
+          status: frontmatter.status ?? null,
+          affects: [...(frontmatter.affects ?? [])],
+          descriptionPath: relativePath,
+        });
+      } catch (error) {
+        diagnostics.push(sourceDiagnostic("TM-WORLD-READ-WORK-ITEM-PARSE-ERROR", directoryId, [relativePath], error));
+      }
+    }
+    return result;
+  }
+
+  private async readTestAnnotations(
+    diagnostics: RawTraceabilityDiagnostic[],
+  ): Promise<readonly RawTraceabilityTestAnnotation[]> {
+    const result: RawTraceabilityTestAnnotation[] = [];
+    for (const testRoot of this.deps.testRoots) {
+      const absoluteRoot = path.join(this.deps.rootDir, testRoot);
+      let files: readonly string[];
+      try {
+        files = await collectFiles(absoluteRoot, (fileName) => /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(fileName));
+      } catch (error) {
+        diagnostics.push(sourceDiagnostic("TM-WORLD-READ-TEST-SOURCE-ERROR", null, [testRoot], error));
+        continue;
+      }
+      for (const absolutePath of files) {
+        const relativePath = toProjectRelativePath(this.deps.rootDir, absolutePath);
+        try {
+          const tags = parseTestTags(await readFile(absolutePath, "utf8"));
+          for (const tag of tags) {
+            result.push({
+              storyId: tag.value,
+              filePath: relativePath,
+              line: tag.lineNumber,
+              testType: classifyTestType(relativePath),
+            });
+          }
+        } catch (error) {
+          diagnostics.push(sourceDiagnostic("TM-WORLD-READ-TEST-PARSE-ERROR", null, [relativePath], error));
+        }
+      }
+    }
+    return result;
+  }
+}

package/scripts/harness/traceability-model/infrastructure/parsers/story-catalog-parser.ts

@@ -10,20 +10,29 @@ export interface ParsedStoryCatalog {
   readonly aliasMap: ReadonlyMap<string, string>;
 }
 
+export interface ParsedStoryCatalogEntry {
+  readonly storyId: string;
+  readonly legacyIds: readonly string[];
+  readonly lineNumber: number;
+  readonly acceptanceCriteria: readonly {
+    readonly acId: string;
+    readonly lineNumber: number;
+  }[];
+}
+
 const STORY_ID_LINE_PATTERN = /\bH(?:F\d+|[0-9]{2})-[0-9]{2}\b/g;
-const TABLE_ALIAS_PATTERN =
-  /\|\s*(H(?:F\d+|[0-9]{2})-[0-9]{2})\s*\|.*?\|\s*(US-[0-9]{3})\s*\|/g;
+const TABLE_ALIAS_PATTERN = /\|\s*(H(?:F\d+|[0-9]{2})-[0-9]{2})\s*\|.*?\|\s*(US-[0-9]{3})\s*\|/g;
 // 旧US ラベルは Markdown 強調（**旧US**:）で囲まれることがあるため `\**` を許容する。
-const INLINE_ALIAS_PATTERN =
-  /(H(?:F\d+|[0-9]{2})-[0-9]{2}).*?旧US\**\s*[:：]\s*(US-[0-9]{3})/g;
+const INLINE_ALIAS_PATTERN = /(H(?:F\d+|[0-9]{2})-[0-9]{2}).*?旧US\**\s*[:：]\s*(US-[0-9]{3})/g;
 
 function execAll(pattern: RegExp, text: string): RegExpExecArray[] {
   const results: RegExpExecArray[] = [];
-  let match: RegExpExecArray | null;
   // Reset lastIndex to ensure clean iteration
   pattern.lastIndex = 0;
-  while ((match = pattern.exec(text)) !== null) {
+  let match = pattern.exec(text);
+  while (match !== null) {
     results.push(match);
+    match = pattern.exec(text);
   }
   return results;
 }
@@ -37,7 +46,7 @@ export function parseStoryCatalog(content: string): ParsedStoryCatalog {
   const aliasMap = new Map<string, string>();
 
   // 正規StoryIdを収集
-  const lines = content.split('\n');
+  const lines = content.split("\n");
   for (const line of lines) {
     const matches = execAll(STORY_ID_LINE_PATTERN, line);
     for (let j = 0; j < matches.length; j++) {
@@ -88,10 +97,79 @@ export function parseStoryCatalog(content: string): ParsedStoryCatalog {
   }
 
   const storyIds: string[] = [];
-  storyIdSet.forEach((id) => storyIds.push(id));
+  storyIdSet.forEach((id) => {
+    storyIds.push(id);
+  });
 
   return {
     storyIds: Object.freeze(storyIds),
     aliasMap,
   };
 }
+
+/**
+ * Story headingをowner locatorとして、heading scope内のlegacy IDとACを構造化する。
+ * `####`以下はStory内の補足見出しとして扱い、次のlevel 1-3見出しでscopeを閉じる。
+ */
+export function parseStoryCatalogEntries(content: string): readonly ParsedStoryCatalogEntry[] {
+  const lines = content.split(/\r?\n/);
+  const STORY_HEADING_PATTERN = /^###\s+(H(?:F\d+|[0-9]{2})-[0-9]{2})\b/;
+  const CLOSING_HEADING_PATTERN = /^#{1,3}\s+/;
+  const LEGACY_PATTERN = /旧US\**\s*[:：]\s*(US-[0-9]{3})/;
+  const AC_PATTERN = /^\s*-\s*\[[ xX]\]\s*(AC-[0-9]+)\s*[:：]/;
+  const entries: {
+    storyId: string;
+    legacyIds: string[];
+    lineNumber: number;
+    acceptanceCriteria: { acId: string; lineNumber: number }[];
+  }[] = [];
+  let current:
+    | {
+        storyId: string;
+        legacyIds: string[];
+        lineNumber: number;
+        acceptanceCriteria: { acId: string; lineNumber: number }[];
+      }
+    | undefined;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const storyHeading = STORY_HEADING_PATTERN.exec(line);
+    if (storyHeading) {
+      current = {
+        storyId: storyHeading[1],
+        legacyIds: [],
+        lineNumber: index + 1,
+        acceptanceCriteria: [],
+      };
+      entries.push(current);
+      continue;
+    }
+    if (CLOSING_HEADING_PATTERN.test(line)) {
+      current = undefined;
+      continue;
+    }
+    if (!current) continue;
+
+    const legacy = LEGACY_PATTERN.exec(line);
+    if (legacy && !current.legacyIds.includes(legacy[1])) {
+      current.legacyIds.push(legacy[1]);
+    }
+    const acceptanceCriterion = AC_PATTERN.exec(line);
+    if (acceptanceCriterion) {
+      current.acceptanceCriteria.push({
+        acId: acceptanceCriterion[1],
+        lineNumber: index + 1,
+      });
+    }
+  }
+
+  return entries.map((entry) => ({
+    storyId: entry.storyId,
+    legacyIds: [...entry.legacyIds],
+    lineNumber: entry.lineNumber,
+    acceptanceCriteria: entry.acceptanceCriteria.map((criterion) => ({
+      ...criterion,
+    })),
+  }));
+}

package/scripts/harness/world-model/application/dto/world-inspection-dto.ts

@@ -0,0 +1,43 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-291
+
+export type WorldJsonValue = null | boolean | number | string | readonly WorldJsonValue[] | WorldJsonObject;
+
+export interface WorldJsonObject {
+  readonly [key: string]: WorldJsonValue;
+}
+
+export interface WorldInventoryCountDto {
+  readonly value: string;
+  readonly count: number;
+}
+
+export interface WorldExtractionDiagnosticDto extends WorldJsonObject {
+  readonly code: string;
+  readonly line: number | null;
+  readonly nodeId: string | null;
+  readonly pathKey: string | null;
+  readonly payload: WorldJsonObject;
+}
+
+export interface WorldInspectionDto {
+  readonly snapshotId: string;
+  readonly schemaVersion: string;
+  readonly extractorVersion: string;
+  readonly corpusRoot: string;
+  readonly summary: {
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly diagnosticCount: number;
+    readonly hardDiagnosticCount: number;
+  };
+  readonly inventory: {
+    readonly nodeTypes: readonly WorldInventoryCountDto[];
+    readonly corpusRoles: readonly WorldInventoryCountDto[];
+    readonly artifactKinds: readonly WorldInventoryCountDto[];
+  };
+  readonly nodes: readonly WorldJsonObject[];
+  readonly edges: readonly WorldJsonObject[];
+  readonly diagnostics: readonly WorldExtractionDiagnosticDto[];
+}

package/scripts/harness/world-model/application/dto/world-obligation-report-dto.ts

@@ -0,0 +1,54 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-295
+
+import type { CanonicalJsonObject } from "../../domain/services/canonical-json-serializer.js";
+
+export type StructuralObligationClassification = "adopted-legacy" | "new-structural" | "invalid-declaration" | "waived";
+
+export interface StructuralObligationDto {
+  readonly violationFingerprint: string;
+  readonly ruleId: string;
+  readonly constraintId: string | null;
+  readonly factType: string | null;
+  readonly subject: CanonicalJsonObject;
+  readonly claimantPin: CanonicalJsonObject | null;
+  readonly premisePin: CanonicalJsonObject | null;
+  readonly expected: CanonicalJsonObject;
+  readonly observed: CanonicalJsonObject;
+  readonly classification: StructuralObligationClassification;
+  readonly waiver: CanonicalJsonObject | null;
+}
+
+export interface RepaidBaselineEntryDto {
+  readonly violationFingerprint: string;
+  readonly ruleId: string;
+  readonly constraintId: string | null;
+  readonly classification: "repaid";
+  readonly disposition: "cleanup-required";
+}
+
+export interface PolicyDiagnosticDto {
+  readonly code: string;
+  readonly subjectId: string | null;
+  readonly details: CanonicalJsonObject;
+}
+
+export interface ObligationReportSummaryDto {
+  readonly structuralObligations: number;
+  readonly repaidBaselineEntries: number;
+  readonly declaredSemanticDebts: number;
+  readonly policyDiagnostics: number;
+}
+
+export interface WorldObligationReportDto {
+  readonly schemaVersion: "phasegate-world-obligation-report/v1";
+  readonly evaluationId: string;
+  readonly rulesetVersion: string;
+  readonly policyInputsDigest: string;
+  readonly structuralObligations: readonly StructuralObligationDto[];
+  readonly repaidBaselineEntries: readonly RepaidBaselineEntryDto[];
+  readonly declaredSemanticDebts: readonly CanonicalJsonObject[];
+  readonly policyDiagnostics: readonly PolicyDiagnosticDto[];
+  readonly summary: ObligationReportSummaryDto;
+}

package/scripts/harness/world-model/application/dto/world-resolved-config-input.ts

@@ -0,0 +1,62 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-291
+
+import { PathKey } from "../../domain/value-objects/path-key.js";
+
+export interface WorldResolvedConfigInput {
+  readonly designDocsRoot?: string;
+  readonly inceptionRoot?: string;
+  readonly requirementMatrixPath?: string;
+}
+
+export interface WorldCorpusConfig {
+  readonly productScopes: readonly {
+    readonly productRoot: string;
+    readonly designDocsRoot: string;
+    readonly unitRoot: string;
+  }[];
+  readonly inceptionRoot: string;
+  readonly adrRoot: string;
+  readonly sourceRoot: string;
+  readonly include: readonly string[];
+  readonly exclude: readonly string[];
+  readonly matrixPath: string;
+  readonly attestationPath: string;
+  readonly integrityManifestPath: string;
+}
+
+const DEFAULT_DESIGN_DOCS_ROOT = "docs/product/construction";
+
+const validatePath = (value: string): string => PathKey.create(value).toString();
+
+const deriveProductRoot = (designDocsRoot: string): string => {
+  const normalized = designDocsRoot.replace(/\/+$/, "");
+  return normalized.endsWith("/construction") ? normalized.slice(0, -"/construction".length) : normalized;
+};
+
+export const resolveWorldCorpusConfig = (input?: WorldResolvedConfigInput): WorldCorpusConfig => {
+  const designDocsRoot = validatePath(input?.designDocsRoot ?? DEFAULT_DESIGN_DOCS_ROOT);
+  const productRoot = validatePath(deriveProductRoot(designDocsRoot));
+  const productScopes = [
+    {
+      productRoot: "docs/product",
+      designDocsRoot: DEFAULT_DESIGN_DOCS_ROOT,
+      unitRoot: "docs/product/units",
+    },
+    ...(productRoot === "docs/product"
+      ? []
+      : [{ productRoot, designDocsRoot, unitRoot: validatePath(`${productRoot}/units`) }]),
+  ];
+  return Object.freeze({
+    productScopes: Object.freeze(productScopes),
+    inceptionRoot: validatePath(input?.inceptionRoot ?? "docs/inception"),
+    adrRoot: "docs/ADR",
+    sourceRoot: "scripts/harness",
+    include: Object.freeze(["**/*"]),
+    exclude: Object.freeze([]),
+    matrixPath: validatePath(input?.requirementMatrixPath ?? ".harness/requirement-test-matrix.json"),
+    attestationPath: ".harness/attestation.json",
+    integrityManifestPath: "phasegate.integrity.json",
+  });
+};

package/scripts/harness/world-model/application/ports/obligation-report-writer-port.ts

@@ -0,0 +1,7 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-295, WI-296
+
+export interface ObligationReportWriterPort {
+  write(bytes: Uint8Array, reportPath?: string): Promise<void>;
+}

package/scripts/harness/world-model/application/ports/world-control-declaration-repository-port.ts

@@ -0,0 +1,57 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-294
+
+import type { ConstraintRecord, MalformedConstraintDeclaration } from "../../domain/entities/constraint-record.js";
+import type {
+  AdoptionBaseline,
+  SemanticDebtDeclaration,
+  WorldWaiver,
+} from "../../domain/entities/control-declarations.js";
+import type { ExplicitConstraintRelation } from "../../domain/value-objects/explicit-constraint-relation.js";
+import type { ExplicitNodeAlias } from "../../domain/value-objects/explicit-node-alias.js";
+
+export interface WorldControlDiagnosticDto {
+  readonly code: string;
+  readonly path: string;
+  readonly locator: string | null;
+  readonly message: string;
+}
+
+export interface ConstraintDeclarationSet {
+  readonly schemaVersion: "phasegate-world-constraints/v1";
+  readonly records: readonly ConstraintRecord[];
+  readonly malformedDeclarations: readonly MalformedConstraintDeclaration[];
+  readonly aliases: readonly ExplicitNodeAlias[];
+  readonly relations: readonly ExplicitConstraintRelation[];
+  readonly diagnostics: readonly WorldControlDiagnosticDto[];
+}
+
+export type WorldControlReadResult<T> =
+  | { readonly state: "absent"; readonly value: T; readonly diagnostics: readonly WorldControlDiagnosticDto[] }
+  | { readonly state: "loaded"; readonly value: T; readonly diagnostics: readonly WorldControlDiagnosticDto[] }
+  | { readonly state: "invalid"; readonly diagnostics: readonly WorldControlDiagnosticDto[] };
+
+export type WorldControlReplaceResult =
+  | { readonly state: "written"; readonly path: string }
+  | { readonly state: "invalid"; readonly diagnostics: readonly WorldControlDiagnosticDto[] };
+
+export interface ConstraintDeclarationRepositoryPort {
+  load(): Promise<WorldControlReadResult<ConstraintDeclarationSet>>;
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult>;
+}
+
+export interface AdoptionBaselineRepositoryPort {
+  load(): Promise<WorldControlReadResult<AdoptionBaseline | null>>;
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult>;
+}
+
+export interface WaiverDeclarationRepositoryPort {
+  load(): Promise<WorldControlReadResult<readonly WorldWaiver[]>>;
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult>;
+}
+
+export interface SemanticDebtRepositoryPort {
+  load(): Promise<WorldControlReadResult<readonly SemanticDebtDeclaration[]>>;
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult>;
+}

package/scripts/harness/world-model/application/ports/world-fact-source-port.ts

@@ -0,0 +1,17 @@
+// @unit world-model
+// @layer application
+// @work-item-id WI-291
+
+import type { Edge } from "../../domain/entities/edge.js";
+import type { ExtractionDiagnostic } from "../../domain/entities/extraction-diagnostic.js";
+import type { WorldNode } from "../../domain/entities/world-node.js";
+
+export interface WorldFactBatch {
+  readonly nodes: readonly WorldNode[];
+  readonly edges: readonly Edge[];
+  readonly diagnostics: readonly ExtractionDiagnostic[];
+}
+
+export interface WorldFactSourcePort {
+  extract(): Promise<readonly WorldFactBatch[]>;
+}