phasegate 0.229.0 → 0.254.0

package/scripts/harness/world-model/infrastructure/adapters/matrix-fact-extractor.ts

@@ -0,0 +1,283 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-290
+// @work-item-id WI-292
+
+import type { RequirementTestMatrixDto } from "../../../nyquist-validation/index.js";
+import { ExtractionDiagnostic } from "../../domain/entities/extraction-diagnostic.js";
+import { WorldNode } from "../../domain/entities/world-node.js";
+import type { WorldHashingPort } from "../../domain/ports/world-hashing-port.js";
+import { type CanonicalJsonObject, CanonicalJsonSerializer } from "../../domain/services/canonical-json-serializer.js";
+import { ArtifactKind } from "../../domain/value-objects/artifact-kind.js";
+import { CorpusRole } from "../../domain/value-objects/corpus-role.js";
+import { PathKey } from "../../domain/value-objects/path-key.js";
+import type { TestReferenceBinding, TestReferenceType } from "../../domain/value-objects/world-node-id.js";
+import {
+  assertExactKeys,
+  OwnerProjectionError,
+  projectionDiagnostic,
+  readOptionalJson,
+  requireArray,
+  requireObject,
+  requireString,
+} from "./json-fact-extractor-support.js";
+import type { RuntimeFactExtraction } from "./runtime-fact-extraction.js";
+
+const DEFAULT_MATRIX_PATH = ".harness/requirement-test-matrix.json";
+const SUPPORTED_VERSIONS = new Set(["1.0", "1.1", "1.2"]);
+type CoverageStatus = "planned" | "required";
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+const compareAcIds = (left: string, right: string): number => {
+  const leftNumber = /^AC-(\d+)$/.exec(left);
+  const rightNumber = /^AC-(\d+)$/.exec(right);
+  if (leftNumber && rightNumber) {
+    const difference = Number(leftNumber[1]) - Number(rightNumber[1]);
+    if (difference !== 0) return difference;
+  }
+  return compareStrings(left, right);
+};
+
+interface MatrixReferenceProjection {
+  readonly storyId: string;
+  readonly acId: string;
+  readonly binding: TestReferenceBinding;
+  readonly testType: TestReferenceType;
+  readonly filePath: string;
+  readonly testName: string | null;
+}
+
+interface MatrixProjection {
+  readonly version: RequirementTestMatrixDto["version"];
+  readonly stories: readonly {
+    readonly storyId: string;
+    readonly coverageStatus: CoverageStatus;
+    readonly coverageLifecycle: readonly CoverageStatus[];
+    readonly storyMappings: readonly {
+      readonly acId: string;
+      readonly testReferences: readonly MatrixReferenceProjection[];
+    }[];
+  }[];
+}
+
+export interface MatrixFactExtractorDeps {
+  readonly rootDir: string;
+  readonly hashingPort: WorldHashingPort;
+  readonly matrixPath?: string;
+  readonly serializer?: CanonicalJsonSerializer;
+}
+
+export class MatrixFactExtractor {
+  private readonly deps: MatrixFactExtractorDeps;
+  private readonly serializer: CanonicalJsonSerializer;
+
+  constructor(deps: MatrixFactExtractorDeps) {
+    this.deps = deps;
+    this.serializer = deps.serializer ?? new CanonicalJsonSerializer();
+  }
+
+  async extract(): Promise<RuntimeFactExtraction> {
+    const relativePath = this.deps.matrixPath ?? DEFAULT_MATRIX_PATH;
+    const read = await readOptionalJson(this.deps.rootDir, relativePath, "matrix");
+    if (read.state !== "present") {
+      return { nodes: [], edges: [], diagnostics: [read.diagnostic] };
+    }
+    try {
+      const projection = this.project(read.value);
+      const artifact = WorldNode.artifact({
+        artifactKind: ArtifactKind.generatedArtifact(),
+        corpusRole: CorpusRole.generated(),
+        path: read.path,
+        digest: this.deps.hashingPort.sha256(this.serializer.serialize(projection)),
+        attributes: projection as unknown as CanonicalJsonObject,
+      });
+      const candidates = projection.stories.flatMap((story) =>
+        story.storyMappings.flatMap((mapping) =>
+          mapping.testReferences.map((reference) =>
+            WorldNode.testReference({
+              storyId: reference.storyId,
+              acId: reference.acId,
+              binding: reference.binding,
+              testType: reference.testType,
+              filePath: PathKey.create(reference.filePath),
+              testName: reference.testName ?? undefined,
+              digest: this.deps.hashingPort.sha256(this.serializer.serialize(reference)),
+              attributes: { matrixPath: relativePath },
+            }),
+          ),
+        ),
+      );
+      const diagnostics: ExtractionDiagnostic[] = [];
+      const references = this.admitUniqueReferences(candidates, read.path, diagnostics);
+      return {
+        nodes: [artifact, ...references].sort((left, right) => compareStrings(left.id.toString(), right.id.toString())),
+        edges: [],
+        diagnostics,
+      };
+    } catch (error) {
+      return {
+        nodes: [],
+        edges: [],
+        diagnostics: [projectionDiagnostic(read.path, "matrix", error)],
+      };
+    }
+  }
+
+  private project(value: unknown): MatrixProjection {
+    const root = requireObject(value, "matrix");
+    assertExactKeys(root, ["version", "generatedAt", "stories"], "matrix");
+    const version = requireString(root.version, "matrix.version");
+    if (!SUPPORTED_VERSIONS.has(version)) {
+      throw new OwnerProjectionError("unsupported-provider-schema", `unsupported matrix version: ${version}`, {
+        schemaVersion: version,
+      });
+    }
+    requireString(root.generatedAt, "matrix.generatedAt");
+    const stories = requireArray(root.stories, "matrix.stories").map((rawStory, storyIndex) => {
+      const story = requireObject(rawStory, `matrix.stories[${storyIndex}]`);
+      assertExactKeys(
+        story,
+        ["storyId", "coverageStatus", "coverageLifecycle", "storyMappings"],
+        `matrix.stories[${storyIndex}]`,
+      );
+      const storyId = requireString(story.storyId, `matrix.stories[${storyIndex}].storyId`);
+      const coverageStatus = this.projectCoverageStatus(
+        story.coverageStatus,
+        `matrix.stories[${storyIndex}].coverageStatus`,
+      );
+      const coverageLifecycle = this.projectCoverageLifecycle(
+        story.coverageLifecycle,
+        coverageStatus,
+        `matrix.stories[${storyIndex}].coverageLifecycle`,
+      );
+      const storyMappings = requireArray(story.storyMappings, `matrix.stories[${storyIndex}].storyMappings`).map(
+        (rawMapping, mappingIndex) => {
+          const field = `matrix.stories[${storyIndex}].storyMappings[${mappingIndex}]`;
+          const mapping = requireObject(rawMapping, field);
+          assertExactKeys(mapping, ["acId", "testReferences"], field);
+          const acId = requireString(mapping.acId, `${field}.acId`);
+          const testReferences = requireArray(mapping.testReferences, `${field}.testReferences`).map(
+            (rawReference, referenceIndex) =>
+              this.projectReference(rawReference, `${field}.testReferences[${referenceIndex}]`, storyId, acId),
+          );
+          return {
+            acId,
+            testReferences: testReferences.sort((left, right) =>
+              compareStrings(this.referenceKey(left), this.referenceKey(right)),
+            ),
+          };
+        },
+      );
+      return {
+        storyId,
+        coverageStatus,
+        coverageLifecycle,
+        storyMappings: storyMappings.sort((left, right) => compareAcIds(left.acId, right.acId)),
+      };
+    });
+    return {
+      version,
+      stories: stories.sort((left, right) => compareStrings(left.storyId, right.storyId)),
+    };
+  }
+
+  private projectCoverageStatus(value: unknown, field: string): CoverageStatus {
+    if (value === undefined) return "required";
+    const status = requireString(value, field);
+    if (status !== "planned" && status !== "required") {
+      throw new OwnerProjectionError("malformed-provider-document", `${field} is invalid`, { field });
+    }
+    return status;
+  }
+
+  private projectCoverageLifecycle(
+    value: unknown,
+    status: CoverageStatus,
+    field: string,
+  ): readonly CoverageStatus[] {
+    if (value === undefined) return Object.freeze([status]);
+    const lifecycle = requireArray(value, field).map((entry, index) => {
+      const item = requireString(entry, `${field}[${index}]`);
+      if (item !== "planned" && item !== "required") {
+        throw new OwnerProjectionError("malformed-provider-document", `${field}[${index}] is invalid`, { field });
+      }
+      return item;
+    });
+    const validSequence =
+      (lifecycle.length === 1 && (lifecycle[0] === "planned" || lifecycle[0] === "required"))
+      || (lifecycle.length === 2 && lifecycle[0] === "planned" && lifecycle[1] === "required");
+    if (!validSequence || lifecycle[lifecycle.length - 1] !== status) {
+      throw new OwnerProjectionError("malformed-provider-document", `${field} is not a forward lifecycle`, { field });
+    }
+    return Object.freeze(lifecycle);
+  }
+
+  private projectReference(value: unknown, field: string, storyId: string, acId: string): MatrixReferenceProjection {
+    const reference = requireObject(value, field);
+    assertExactKeys(reference, ["filePath", "testType", "testName", "binding"], field);
+    const filePath = requireString(reference.filePath, `${field}.filePath`);
+    PathKey.create(filePath);
+    const testType = requireString(reference.testType, `${field}.testType`);
+    if (testType !== "unit" && testType !== "it" && testType !== "scenario") {
+      throw new OwnerProjectionError("malformed-provider-document", `${field}.testType is invalid`, {
+        field: `${field}.testType`,
+      });
+    }
+    const binding = reference.binding === undefined ? "file" : requireString(reference.binding, `${field}.binding`);
+    if (binding !== "ac" && binding !== "file") {
+      throw new OwnerProjectionError("malformed-provider-document", `${field}.binding is invalid`, {
+        field: `${field}.binding`,
+      });
+    }
+    const testName = reference.testName === undefined ? null : requireString(reference.testName, `${field}.testName`);
+    return {
+      storyId,
+      acId,
+      binding,
+      testType,
+      filePath,
+      testName,
+    };
+  }
+
+  private admitUniqueReferences(
+    candidates: readonly WorldNode[],
+    pathKey: PathKey,
+    diagnostics: ExtractionDiagnostic[],
+  ): readonly WorldNode[] {
+    const groups = new Map<string, WorldNode[]>();
+    for (const candidate of candidates) {
+      const id = candidate.id.toString();
+      const current = groups.get(id) ?? [];
+      current.push(candidate);
+      groups.set(id, current);
+    }
+    const admitted: WorldNode[] = [];
+    for (const [id, entries] of groups) {
+      if (entries.length === 1) {
+        admitted.push(entries[0]);
+        continue;
+      }
+      diagnostics.push(
+        ExtractionDiagnostic.create({
+          code: "duplicate-node-id",
+          nodeId: entries[0].id,
+          path: pathKey,
+          payload: { candidates: entries.length, provider: "matrix", testReferenceId: id },
+        }),
+      );
+    }
+    return admitted;
+  }
+
+  private referenceKey(reference: MatrixReferenceProjection): string {
+    return [
+      reference.storyId,
+      reference.acId,
+      reference.binding,
+      reference.testType,
+      reference.filePath,
+      reference.testName ?? "",
+    ].join("\u0000");
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/product-fact-extractor.ts

@@ -0,0 +1,29 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-289, WI-291
+
+import { CorpusRole } from "../../domain/value-objects/corpus-role.js";
+import type { DesignFactSource } from "./design-fact-extraction.js";
+import { FileSystemDesignFactScope, type MarkdownDesignFactExtractor } from "./markdown-design-fact-extractor.js";
+
+export interface ProductFactExtractorDeps {
+  readonly rootDir: string;
+  readonly markdownExtractor: MarkdownDesignFactExtractor;
+  readonly productRoot?: string;
+}
+
+export class ProductFactExtractor extends FileSystemDesignFactScope implements DesignFactSource {
+  constructor(deps: ProductFactExtractorDeps) {
+    super({
+      rootDir: deps.rootDir,
+      relativeRoot: deps.productRoot ?? "docs/product",
+      role: CorpusRole.product(),
+      markdownExtractor: deps.markdownExtractor,
+      include: (relativePath) => relativePath.endsWith(".md"),
+      skip: (relativePath) => /\/units\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*_unit\.md$/.test(relativePath),
+      metadata: (relativePath, ownerIndex) => ({
+        storyIds: ownerIndex.storyIdsBySourcePath.get(relativePath),
+      }),
+    });
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/proposal-fact-extractor.ts

@@ -0,0 +1,29 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-289, WI-291
+
+import { CorpusRole } from "../../domain/value-objects/corpus-role.js";
+import type { DesignFactSource } from "./design-fact-extraction.js";
+import { FileSystemDesignFactScope, type MarkdownDesignFactExtractor } from "./markdown-design-fact-extractor.js";
+
+export interface ProposalFactExtractorDeps {
+  readonly rootDir: string;
+  readonly markdownExtractor: MarkdownDesignFactExtractor;
+  readonly inceptionRoot?: string;
+}
+
+export class ProposalFactExtractor extends FileSystemDesignFactScope implements DesignFactSource {
+  constructor(deps: ProposalFactExtractorDeps) {
+    super({
+      rootDir: deps.rootDir,
+      relativeRoot: deps.inceptionRoot ?? "docs/inception",
+      role: CorpusRole.inception(),
+      markdownExtractor: deps.markdownExtractor,
+      include: (relativePath) => relativePath.endsWith(".md"),
+      skip: () => false,
+      metadata: (relativePath, ownerIndex) => ({
+        ownerWorkItemId: ownerIndex.workItemIdByDescriptionPath.get(relativePath),
+      }),
+    });
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/runtime-fact-extraction.ts

@@ -0,0 +1,19 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-290
+
+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 RuntimeFactExtraction {
+  readonly nodes: readonly WorldNode[];
+  readonly edges: readonly Edge[];
+  readonly diagnostics: readonly ExtractionDiagnostic[];
+}
+
+export const EMPTY_RUNTIME_FACT_EXTRACTION: RuntimeFactExtraction = Object.freeze({
+  nodes: Object.freeze([]),
+  edges: Object.freeze([]),
+  diagnostics: Object.freeze([]),
+});

package/scripts/harness/world-model/infrastructure/adapters/source-metadata-fact-extractor.ts

@@ -0,0 +1,22 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-290, WI-291
+
+import type { WorldHashingPort } from "../../domain/ports/world-hashing-port.js";
+import { TypeScriptSourceFactExtractor } from "./type-script-source-fact-extractor.js";
+
+export interface SourceMetadataFactExtractorDeps {
+  readonly rootDir: string;
+  readonly hashingPort: WorldHashingPort;
+  readonly sourceRoot?: string;
+}
+
+export class SourceMetadataFactExtractor extends TypeScriptSourceFactExtractor {
+  constructor(deps: SourceMetadataFactExtractorDeps) {
+    super({
+      ...deps,
+      sourceKind: "implementation",
+      include: (relativePath) => !relativePath.includes("/__tests__/"),
+    });
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/test-reference-source-fact-extractor.ts

@@ -0,0 +1,22 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-290, WI-291
+
+import type { WorldHashingPort } from "../../domain/ports/world-hashing-port.js";
+import { TypeScriptSourceFactExtractor } from "./type-script-source-fact-extractor.js";
+
+export interface TestReferenceSourceFactExtractorDeps {
+  readonly rootDir: string;
+  readonly hashingPort: WorldHashingPort;
+  readonly sourceRoot?: string;
+}
+
+export class TestReferenceSourceFactExtractor extends TypeScriptSourceFactExtractor {
+  constructor(deps: TestReferenceSourceFactExtractorDeps) {
+    super({
+      ...deps,
+      sourceKind: "test",
+      include: (relativePath) => relativePath.includes("/__tests__/"),
+    });
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/traceability-design-fact-adapter.ts

@@ -0,0 +1,112 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-289
+
+import type { TraceabilityWorldReadDto } from "../../../traceability-model/index.js";
+import { ExtractionDiagnostic } from "../../domain/entities/extraction-diagnostic.js";
+import { WorldNode } from "../../domain/entities/world-node.js";
+import type { WorldHashingPort } from "../../domain/ports/world-hashing-port.js";
+import { CanonicalJsonSerializer } from "../../domain/services/canonical-json-serializer.js";
+import { PathKey } from "../../domain/value-objects/path-key.js";
+import type { TraceabilityDesignFactIndex } from "./design-fact-extraction.js";
+
+export interface TraceabilityWorldReadFacadeContract {
+  read(): Promise<TraceabilityWorldReadDto>;
+}
+
+export interface TraceabilityDesignFactAdapterDeps {
+  readonly facade: TraceabilityWorldReadFacadeContract;
+  readonly hashingPort: WorldHashingPort;
+  readonly serializer?: CanonicalJsonSerializer;
+}
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const optionalPath = (sourcePaths: readonly string[]): PathKey | undefined => {
+  if (sourcePaths.length === 0) return undefined;
+  try {
+    return PathKey.create([...sourcePaths].sort(compareStrings)[0]);
+  } catch {
+    return undefined;
+  }
+};
+
+export class TraceabilityDesignFactAdapter {
+  private readonly facade: TraceabilityWorldReadFacadeContract;
+  private readonly hashingPort: WorldHashingPort;
+  private readonly serializer: CanonicalJsonSerializer;
+
+  constructor(deps: TraceabilityDesignFactAdapterDeps) {
+    this.facade = deps.facade;
+    this.hashingPort = deps.hashingPort;
+    this.serializer = deps.serializer ?? new CanonicalJsonSerializer();
+  }
+
+  async read(): Promise<TraceabilityDesignFactIndex> {
+    const dto = await this.facade.read();
+    if (dto.schemaVersion !== "phasegate-traceability-world-read/v1") {
+      return {
+        workItemNodes: [],
+        unitIdByDefinitionPath: new Map(),
+        storyIdsBySourcePath: new Map(),
+        workItemIdByDescriptionPath: new Map(),
+        diagnostics: [
+          ExtractionDiagnostic.create({
+            code: "unsupported-provider-schema",
+            payload: { provider: "traceability-model", schemaVersion: dto.schemaVersion },
+          }),
+        ],
+      };
+    }
+
+    const workItemNodes = dto.workItems.map((workItem) =>
+      WorldNode.workItem({
+        workItemId: workItem.workItemId,
+        digest: this.hashingPort.sha256(this.serializer.serialize(workItem)),
+        attributes: {
+          affects: [...workItem.affects].sort(compareStrings),
+          descriptionPath: workItem.descriptionPath,
+          legacyIds: [...workItem.legacyIds].sort(compareStrings),
+          severity: workItem.severity,
+          status: workItem.status,
+          type: workItem.type,
+        },
+      }),
+    );
+    const unitIdByDefinitionPath = new Map(
+      dto.units
+        .map((unit) => [unit.definitionPath, unit.unitId] as const)
+        .sort((left, right) => compareStrings(left[0], right[0])),
+    );
+    const storyIdsBySourcePath = new Map<string, readonly string[]>();
+    for (const story of dto.stories) {
+      const current = storyIdsBySourcePath.get(story.sourcePath) ?? [];
+      storyIdsBySourcePath.set(story.sourcePath, [...current, story.storyId].sort(compareStrings));
+    }
+    const workItemIdByDescriptionPath = new Map(
+      dto.workItems
+        .map((workItem) => [workItem.descriptionPath, workItem.workItemId] as const)
+        .sort((left, right) => compareStrings(left[0], right[0])),
+    );
+    const diagnostics = dto.diagnostics.map((entry) =>
+      ExtractionDiagnostic.create({
+        code: "provider-diagnostic",
+        path: optionalPath(entry.sourcePaths),
+        payload: {
+          message: entry.message,
+          provider: "traceability-model",
+          providerCode: entry.code,
+          sourcePaths: [...entry.sourcePaths].sort(compareStrings),
+          subjectId: entry.subjectId,
+        },
+      }),
+    );
+    return {
+      workItemNodes: workItemNodes.sort((left, right) => compareStrings(left.id.toString(), right.id.toString())),
+      unitIdByDefinitionPath,
+      storyIdsBySourcePath,
+      workItemIdByDescriptionPath,
+      diagnostics,
+    };
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/traceability-world-read-facade-merger.ts

@@ -0,0 +1,38 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-291
+
+import type { TraceabilityWorldReadDto } from "../../../traceability-model/index.js";
+import type { TraceabilityWorldReadFacadeContract } from "./traceability-design-fact-adapter.js";
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const mergePlainDtos = <T>(values: readonly (readonly T[])[]): readonly T[] => {
+  const byProjection = new Map<string, T>();
+  for (const value of values.flat()) {
+    const key = JSON.stringify(value);
+    if (!byProjection.has(key)) byProjection.set(key, value);
+  }
+  return [...byProjection.entries()].sort(([left], [right]) => compareStrings(left, right)).map(([, value]) => value);
+};
+
+export class TraceabilityWorldReadFacadeMerger implements TraceabilityWorldReadFacadeContract {
+  constructor(private readonly facades: readonly TraceabilityWorldReadFacadeContract[]) {
+    if (facades.length === 0) throw new Error("at least one traceability facade is required");
+  }
+
+  async read(): Promise<TraceabilityWorldReadDto> {
+    const results = await Promise.all(this.facades.map((facade) => facade.read()));
+    const unsupported = results.find((result) => result.schemaVersion !== "phasegate-traceability-world-read/v1");
+    if (unsupported) return unsupported;
+    return {
+      schemaVersion: "phasegate-traceability-world-read/v1",
+      units: mergePlainDtos(results.map((result) => result.units)),
+      stories: mergePlainDtos(results.map((result) => result.stories)),
+      acceptanceCriteria: mergePlainDtos(results.map((result) => result.acceptanceCriteria)),
+      workItems: mergePlainDtos(results.map((result) => result.workItems)),
+      testReferences: mergePlainDtos(results.map((result) => result.testReferences)),
+      diagnostics: mergePlainDtos(results.map((result) => result.diagnostics)),
+    };
+  }
+}