phasegate 0.15.0

package/scripts/harness/traceability-model/domain/value-objects/layer-reference.ts

@@ -0,0 +1,41 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ *
+ * @layerタグから解釈したレイヤー参照
+ */
+import { LAYER_NAMES } from '../constants/layer-names.js';
+
+const VALID_LAYER_NAME_SET = new Set<string>(LAYER_NAMES);
+const LEGACY_LAYER_NAME_SET = new Set<string>(['port', 'usecase', 'controller']);
+
+export class LayerReference {
+  readonly layerName: string;
+  readonly valid: boolean;
+
+  private constructor(layerName: string, valid: boolean) {
+    this.layerName = layerName;
+    this.valid = valid;
+    Object.freeze(this);
+  }
+
+  static parse(layerName: string): LayerReference {
+    const normalizedLayerName = layerName.trim();
+    const valid =
+      VALID_LAYER_NAME_SET.has(normalizedLayerName) && !LEGACY_LAYER_NAME_SET.has(normalizedLayerName);
+
+    return new LayerReference(normalizedLayerName, valid);
+  }
+
+  isValid(): boolean {
+    return this.valid;
+  }
+
+  toString(): string {
+    return this.layerName;
+  }
+
+  equals(other: LayerReference): boolean {
+    return this.layerName === other.layerName && this.valid === other.valid;
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/metadata-tag.ts

@@ -0,0 +1,93 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ *
+ * ソースコードやテストコードから抽出したメタデータタグ
+ */
+import {
+  METADATA_TAG_TYPES,
+  type MetadataTagType,
+} from '../constants/metadata-tag-types.js';
+import type { ProjectRelativePath } from './project-relative-path.js';
+
+const METADATA_TAG_TYPE_SET = new Set<string>(METADATA_TAG_TYPES);
+
+export interface MetadataTagCreateArgs {
+  readonly type: string;
+  readonly value: string;
+  readonly lineNumber: number;
+  readonly filePath?: ProjectRelativePath | null;
+}
+
+export class MetadataTag {
+  readonly type: MetadataTagType;
+  readonly value: string;
+  readonly lineNumber: number;
+  readonly filePath: ProjectRelativePath | null;
+
+  private constructor(args: {
+    readonly type: MetadataTagType;
+    readonly value: string;
+    readonly lineNumber: number;
+    readonly filePath: ProjectRelativePath | null;
+  }) {
+    this.type = args.type;
+    this.value = args.value;
+    this.lineNumber = args.lineNumber;
+    this.filePath = args.filePath;
+    Object.freeze(this);
+  }
+
+  static create(args: MetadataTagCreateArgs): MetadataTag {
+    const normalizedValue = args.value.trim();
+
+    if (!METADATA_TAG_TYPE_SET.has(args.type)) {
+      throw new Error(`MetadataTag.typeが不正です: ${args.type}`);
+    }
+
+    if (normalizedValue.length === 0) {
+      throw new Error('MetadataTag.valueは空文字を許可しません');
+    }
+
+    if (!Number.isInteger(args.lineNumber) || args.lineNumber < 1) {
+      throw new Error(`MetadataTag.lineNumberは1以上の整数である必要があります: ${args.lineNumber}`);
+    }
+
+    return new MetadataTag({
+      type: args.type as MetadataTagType,
+      value: normalizedValue,
+      lineNumber: args.lineNumber,
+      filePath: args.filePath ?? null,
+    });
+  }
+
+  isUnitTag(): boolean {
+    return this.type === '@unit';
+  }
+
+  isLayerTag(): boolean {
+    return this.type === '@layer';
+  }
+
+  isStoryIdTag(): boolean {
+    return this.type === '@story-id';
+  }
+
+  isStoryTag(): boolean {
+    return this.type === '@story';
+  }
+
+  equals(other: MetadataTag): boolean {
+    const filePathEquals =
+      this.filePath === null
+        ? other.filePath === null
+        : other.filePath !== null && this.filePath.equals(other.filePath);
+
+    return (
+      this.type === other.type &&
+      this.value === other.value &&
+      this.lineNumber === other.lineNumber &&
+      filePathEquals
+    );
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/metadata-validation-result.ts

@@ -0,0 +1,97 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+export interface TraceabilityHarnessError {
+  readonly code: string;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly suggestion: string;
+  readonly fix_example?: string;
+}
+
+export interface MetadataValidationResultSuccessArgs {
+  readonly warnings?: readonly TraceabilityHarnessError[];
+}
+
+export interface MetadataValidationResultFailureArgs {
+  readonly errors: readonly TraceabilityHarnessError[];
+  readonly warnings?: readonly TraceabilityHarnessError[];
+}
+
+const errorEquals = (
+  left: TraceabilityHarnessError,
+  right: TraceabilityHarnessError,
+): boolean =>
+  left.code === right.code &&
+  left.severity === right.severity &&
+  left.message === right.message &&
+  left.suggestion === right.suggestion &&
+  left.fix_example === right.fix_example;
+
+export class MetadataValidationResult {
+  readonly valid: boolean;
+  readonly errors: readonly TraceabilityHarnessError[];
+  readonly warnings: readonly TraceabilityHarnessError[];
+
+  private constructor(args: {
+    readonly valid: boolean;
+    readonly errors: readonly TraceabilityHarnessError[];
+    readonly warnings: readonly TraceabilityHarnessError[];
+  }) {
+    if (args.valid && args.errors.length > 0) {
+      throw new Error('valid result cannot contain errors');
+    }
+
+    this.valid = args.valid;
+    this.errors = Object.freeze([...args.errors]);
+    this.warnings = Object.freeze([...args.warnings]);
+    Object.freeze(this);
+  }
+
+  static success(
+    args: MetadataValidationResultSuccessArgs = {},
+  ): MetadataValidationResult {
+    return new MetadataValidationResult({
+      valid: true,
+      errors: Object.freeze([]),
+      warnings: args.warnings ?? Object.freeze([]),
+    });
+  }
+
+  static failure(
+    args: MetadataValidationResultFailureArgs,
+  ): MetadataValidationResult {
+    return new MetadataValidationResult({
+      valid: false,
+      errors: args.errors,
+      warnings: args.warnings ?? Object.freeze([]),
+    });
+  }
+
+  hasErrors(): boolean {
+    return this.errors.length > 0;
+  }
+
+  hasWarnings(): boolean {
+    return this.warnings.length > 0;
+  }
+
+  equals(other: MetadataValidationResult): boolean {
+    if (
+      this.valid !== other.valid ||
+      this.errors.length !== other.errors.length ||
+      this.warnings.length !== other.warnings.length
+    ) {
+      return false;
+    }
+
+    return (
+      this.errors.every((error, index) => errorEquals(error, other.errors[index])) &&
+      this.warnings.every((warning, index) =>
+        errorEquals(warning, other.warnings[index]),
+      )
+    );
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/project-relative-path.ts

@@ -0,0 +1,96 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ *
+ * docs/ または scripts/ 配下のPOSIX相対パス
+ */
+const ALLOWED_PROJECT_ROOTS = new Set(['docs', 'scripts']);
+
+export class ProjectRelativePathError extends Error {
+  constructor(value: string) {
+    super(`ProjectRelativePathが不正です: ${value}`);
+    this.name = 'ProjectRelativePathError';
+  }
+}
+
+const normalizeSegments = (rawValue: string): readonly string[] => {
+  const normalizedValue = rawValue.trim();
+
+  if (normalizedValue.length === 0) {
+    throw new ProjectRelativePathError(rawValue);
+  }
+
+  if (normalizedValue.includes('\\')) {
+    throw new ProjectRelativePathError(rawValue);
+  }
+
+  if (normalizedValue.startsWith('/') || /^[A-Za-z]:\//.test(normalizedValue)) {
+    throw new ProjectRelativePathError(rawValue);
+  }
+
+  const segments = normalizedValue
+    .split('/')
+    .filter((segment) => segment.length > 0 && segment !== '.')
+    .map((segment) => {
+      if (segment === '..') {
+        throw new ProjectRelativePathError(rawValue);
+      }
+
+      return segment;
+    });
+
+  if (segments.length === 0 || !ALLOWED_PROJECT_ROOTS.has(segments[0])) {
+    throw new ProjectRelativePathError(rawValue);
+  }
+
+  return Object.freeze([...segments]);
+};
+
+export class ProjectRelativePath {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(value: string): ProjectRelativePath {
+    const segments = normalizeSegments(value);
+    return new ProjectRelativePath(segments.join('/'));
+  }
+
+  join(...segments: readonly string[]): ProjectRelativePath {
+    return ProjectRelativePath.create([this.value, ...segments].join('/'));
+  }
+
+  dirname(): ProjectRelativePath {
+    const segments = this.value.split('/');
+    const parentSegments = segments.slice(0, -1);
+    const parentValue = parentSegments.length > 0 ? parentSegments.join('/') : this.value;
+    return ProjectRelativePath.create(parentValue);
+  }
+
+  basename(): string {
+    const segments = this.value.split('/');
+    return segments[segments.length - 1];
+  }
+
+  extname(): string {
+    const baseName = this.basename();
+    const extensionIndex = baseName.lastIndexOf('.');
+    return extensionIndex >= 0 ? baseName.slice(extensionIndex) : '';
+  }
+
+  startsWith(prefix: string): boolean {
+    const normalizedPrefix = ProjectRelativePath.create(prefix).value;
+    return this.value.startsWith(normalizedPrefix);
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  equals(other: ProjectRelativePath): boolean {
+    return this.value === other.value;
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/story-id-annotation.ts

@@ -0,0 +1,49 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+import type { StoryIdLike } from './story-reference.js';
+
+export interface StoryIdAnnotationArgs {
+  readonly storyId: StoryIdLike;
+  readonly lineNumber: number;
+  readonly contextLine: string;
+  readonly standaloneLine: boolean;
+}
+
+export class StoryIdAnnotation {
+  readonly storyId: StoryIdLike;
+  readonly lineNumber: number;
+  readonly contextLine: string;
+  readonly standaloneLine: boolean;
+
+  private constructor(args: StoryIdAnnotationArgs) {
+    this.storyId = args.storyId;
+    this.lineNumber = args.lineNumber;
+    this.contextLine = args.contextLine;
+    this.standaloneLine = args.standaloneLine;
+    Object.freeze(this);
+  }
+
+  static create(args: StoryIdAnnotationArgs): StoryIdAnnotation {
+    if (!Number.isInteger(args.lineNumber) || args.lineNumber < 1) {
+      throw new Error('lineNumber must be greater than or equal to 1');
+    }
+
+    return new StoryIdAnnotation(args);
+  }
+
+  isStandalone(): boolean {
+    return this.standaloneLine;
+  }
+
+  equals(other: StoryIdAnnotation): boolean {
+    return (
+      this.storyId.equals(other.storyId) &&
+      this.lineNumber === other.lineNumber &&
+      this.contextLine === other.contextLine &&
+      this.standaloneLine === other.standaloneLine
+    );
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/story-id.ts

@@ -0,0 +1,58 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ *
+ * HXX-XX形式の正規ストーリーID
+ */
+const STORY_ID_PATTERN = /^H(?<epicNumber>[0-9]{2})-(?<storyNumber>[0-9]{2})$/;
+
+export class StoryIdFormatError extends Error {
+  constructor(value: string) {
+    super(`StoryIdはHXX-XX形式で指定してください: ${value}`);
+    this.name = 'StoryIdFormatError';
+  }
+}
+
+export class StoryId {
+  readonly value: string;
+  readonly epicNumber: string;
+  readonly storyNumber: string;
+
+  private constructor(value: string, epicNumber: string, storyNumber: string) {
+    this.value = value;
+    this.epicNumber = epicNumber;
+    this.storyNumber = storyNumber;
+    Object.freeze(this);
+  }
+
+  static parse(value: string): StoryId {
+    const normalizedValue = value.trim();
+    const match = STORY_ID_PATTERN.exec(normalizedValue);
+
+    if (!match?.groups) {
+      throw new StoryIdFormatError(value);
+    }
+
+    return new StoryId(normalizedValue, match.groups.epicNumber, match.groups.storyNumber);
+  }
+
+  static isValid(value: string): boolean {
+    return STORY_ID_PATTERN.test(value.trim());
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  getEpicNumber(): string {
+    return this.epicNumber;
+  }
+
+  getStoryNumber(): string {
+    return this.storyNumber;
+  }
+
+  equals(other: StoryId): boolean {
+    return this.value === other.value;
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/story-reference.ts

@@ -0,0 +1,40 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+export interface StoryIdLike {
+  readonly value: string;
+  equals(other: { readonly value: string }): boolean;
+}
+
+export interface StoryReferenceArgs {
+  readonly storyId: StoryIdLike;
+}
+
+export class StoryReference {
+  readonly storyId: StoryIdLike;
+  readonly resolved: boolean;
+
+  private constructor(storyId: StoryIdLike, resolved: boolean) {
+    this.storyId = storyId;
+    this.resolved = resolved;
+    Object.freeze(this);
+  }
+
+  static resolved(args: StoryReferenceArgs): StoryReference {
+    return new StoryReference(args.storyId, true);
+  }
+
+  static unresolved(args: StoryReferenceArgs): StoryReference {
+    return new StoryReference(args.storyId, false);
+  }
+
+  isResolved(): boolean {
+    return this.resolved;
+  }
+
+  equals(other: StoryReference): boolean {
+    return this.resolved === other.resolved && this.storyId.equals(other.storyId);
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/traceability-chain.ts

@@ -0,0 +1,66 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ */
+
+import { ChainLink, type ChainLinkType, type ProjectRelativePathLike } from './chain-link.js';
+
+const LINK_ORDER: Readonly<Record<ChainLinkType, number>> = Object.freeze({
+  'implementation-to-unit': 1,
+  'unit-to-design': 2,
+  'design-to-story': 3,
+  'story-to-plan': 4,
+});
+
+export interface TraceabilityChainArgs {
+  readonly origin: ProjectRelativePathLike;
+  readonly links: readonly ChainLink[];
+}
+
+export class TraceabilityChain {
+  readonly origin: ProjectRelativePathLike;
+  readonly links: readonly ChainLink[];
+
+  private constructor(origin: ProjectRelativePathLike, links: readonly ChainLink[]) {
+    this.origin = origin;
+    this.links = Object.freeze([...links]);
+    Object.freeze(this);
+  }
+
+  static create(args: TraceabilityChainArgs): TraceabilityChain {
+    if (args.links.length > 0 && !args.origin.equals(args.links[0].from)) {
+      throw new Error('origin must match the first link source');
+    }
+
+    let previousOrder = 0;
+    for (const link of args.links) {
+      const currentOrder = LINK_ORDER[link.linkType];
+      if (currentOrder < previousOrder) {
+        throw new Error('link order is invalid');
+      }
+      previousOrder = currentOrder;
+    }
+
+    return new TraceabilityChain(args.origin, args.links);
+  }
+
+  isComplete(): boolean {
+    return this.links.every((link) => link.resolved);
+  }
+
+  getBrokenLinks(): readonly ChainLink[] {
+    return Object.freeze(this.links.filter((link) => link.isBroken()));
+  }
+
+  getResolvedLinks(): readonly ChainLink[] {
+    return Object.freeze(this.links.filter((link) => !link.isBroken()));
+  }
+
+  equals(other: TraceabilityChain): boolean {
+    if (!this.origin.equals(other.origin) || this.links.length !== other.links.length) {
+      return false;
+    }
+
+    return this.links.every((link, index) => link.equals(other.links[index]));
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/unit-reference.ts

@@ -0,0 +1,70 @@
+/**
+ * @layer domain
+ * @unit traceability-model
+ *
+ * @unitタグから解決したUnit参照
+ */
+import type { ProjectRelativePath } from './project-relative-path.js';
+
+export interface UnitReferenceResolvedArgs {
+  readonly unitName: string;
+  readonly constructionRoot: ProjectRelativePath;
+}
+
+export interface UnitReferenceUnresolvedArgs {
+  readonly unitName: string;
+}
+
+export class UnitReference {
+  readonly unitName: string;
+  readonly resolved: boolean;
+  readonly constructionRoot: ProjectRelativePath | null;
+
+  private constructor(args: {
+    readonly unitName: string;
+    readonly resolved: boolean;
+    readonly constructionRoot: ProjectRelativePath | null;
+  }) {
+    if (!args.resolved && args.constructionRoot !== null) {
+      throw new Error('resolved=false のとき constructionRoot は null である必要があります');
+    }
+
+    if (args.resolved && args.constructionRoot === null) {
+      throw new Error('resolved=true のとき constructionRoot は必須です');
+    }
+
+    this.unitName = args.unitName;
+    this.resolved = args.resolved;
+    this.constructionRoot = args.constructionRoot;
+    Object.freeze(this);
+  }
+
+  static resolved(args: UnitReferenceResolvedArgs): UnitReference {
+    return new UnitReference({
+      unitName: args.unitName,
+      resolved: true,
+      constructionRoot: args.constructionRoot,
+    });
+  }
+
+  static unresolved(args: UnitReferenceUnresolvedArgs): UnitReference {
+    return new UnitReference({
+      unitName: args.unitName,
+      resolved: false,
+      constructionRoot: null,
+    });
+  }
+
+  isResolved(): boolean {
+    return this.resolved;
+  }
+
+  equals(other: UnitReference): boolean {
+    const rootEquals =
+      this.constructionRoot === null
+        ? other.constructionRoot === null
+        : other.constructionRoot !== null && this.constructionRoot.equals(other.constructionRoot);
+
+    return this.unitName === other.unitName && this.resolved === other.resolved && rootEquals;
+  }
+}

package/scripts/harness/traceability-model/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @layer public-api
+ * @unit traceability-model
+ *
+ * traceability-model ユニットのバレルエクスポート。
+ */
+
+// Composition Root
+export { createTraceabilityModelModule } from './composition-root.js';
+
+// Domain — value objects
+export { ProjectRelativePath } from './domain/value-objects/project-relative-path.js';
+export { StoryId } from './domain/value-objects/story-id.js';
+
+// Presentation — CLI handlers
+export { ValidateMetadataCommandHandler } from './presentation/cli/validate-metadata-command-handler.js';