@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/starter/src/app/acceptance/motion-reference-study-behaviors.ts

@@ -0,0 +1,162 @@
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftMotionReferenceInput,
+} from "./types";
+
+type AcceptanceRowsById = ReadonlyMap<
+  string,
+  readonly ToolcraftComponentAcceptance[]
+>;
+
+function validateAcceptanceFields({
+  acceptance,
+  behaviorId,
+}: {
+  acceptance: ToolcraftComponentAcceptance;
+  behaviorId: string;
+}): string[] {
+  const errors: string[] = [];
+  if (!acceptance.automated || !acceptance.automatedTestName.trim()) {
+    errors.push(
+      `motion reference behavior "${behaviorId}" acceptance "${acceptance.id}" must have automated coverage.`,
+    );
+  }
+  if (!acceptance.browser || !acceptance.browserTestName.trim()) {
+    errors.push(
+      `motion reference behavior "${behaviorId}" acceptance "${acceptance.id}" must have browser coverage.`,
+    );
+  }
+  if (!acceptance.expectedObservable.trim()) {
+    errors.push(
+      `motion reference behavior "${behaviorId}" acceptance "${acceptance.id}" must describe its observable result.`,
+    );
+  }
+  return errors;
+}
+
+export function validateBehaviorCoverage(
+  input: ToolcraftMotionReferenceInput,
+  acceptanceRowsById: AcceptanceRowsById,
+): string[] {
+  const errors: string[] = [];
+  const studiesById = new Map<
+    string,
+    ToolcraftMotionReferenceInput["studies"]
+  >();
+  const usedBehaviorIds = new Set<string>();
+
+  for (const study of input.studies) {
+    studiesById.set(study.studyId, [
+      ...(studiesById.get(study.studyId) ?? []),
+      study,
+    ]);
+    for (const phase of study.phases) {
+      phase.behaviorIds.forEach((behaviorId) => usedBehaviorIds.add(behaviorId));
+    }
+    for (const event of study.events) {
+      if (event.classification === "product-behavior") {
+        event.behaviorIds.forEach((behaviorId) => usedBehaviorIds.add(behaviorId));
+      }
+    }
+  }
+
+  for (const behavior of input.behaviors) {
+    if (!behavior.description.trim()) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" must include a non-empty description.`,
+      );
+    }
+    if (!behavior.implementationIntent.trim()) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" must include a non-empty implementationIntent.`,
+      );
+    }
+    if (!usedBehaviorIds.has(behavior.id)) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" must be used by a phase or product event.`,
+      );
+    }
+
+    const timingClaimStudies = new Map<string, Set<string>>();
+    for (const timingClaim of behavior.timingClaims) {
+      const studyIds = timingClaimStudies.get(timingClaim.claim) ?? new Set();
+      if (studyIds.has(timingClaim.studyId)) {
+        errors.push(
+          `motion reference behavior "${behavior.id}" timing claim "${timingClaim.claim}" for study "${timingClaim.studyId}" is duplicated.`,
+        );
+      }
+      studyIds.add(timingClaim.studyId);
+      timingClaimStudies.set(timingClaim.claim, studyIds);
+
+      const studies = studiesById.get(timingClaim.studyId) ?? [];
+      if (studies.length === 0) {
+        errors.push(
+          `motion reference behavior "${behavior.id}" timing claim "${timingClaim.claim}" names missing study "${timingClaim.studyId}".`,
+        );
+      } else if (studies.length > 1) {
+        errors.push(
+          `motion reference behavior "${behavior.id}" timing claim "${timingClaim.claim}" studyId "${timingClaim.studyId}" resolves to ${studies.length} studies; expected exactly one.`,
+        );
+      } else {
+        const [study] = studies;
+        if (study.evidence.timingMode !== "seconds") {
+          errors.push(
+            `motion reference behavior "${behavior.id}" timing claim "${timingClaim.claim}" must name a seconds-timed study; "${timingClaim.studyId}" is ordinal.`,
+          );
+        }
+      }
+    }
+
+    const acceptanceRows = acceptanceRowsById.get(behavior.acceptanceId) ?? [];
+    if (acceptanceRows.length === 0) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" points to missing acceptanceId "${behavior.acceptanceId}".`,
+      );
+      continue;
+    }
+    for (const acceptance of acceptanceRows) {
+      errors.push(...validateAcceptanceFields({ acceptance, behaviorId: behavior.id }));
+    }
+    if (acceptanceRows.length > 1) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" acceptanceId "${behavior.acceptanceId}" resolves to ${acceptanceRows.length} acceptance rows; expected exactly one.`,
+      );
+      continue;
+    }
+    const [acceptance] = acceptanceRows;
+
+    const matchingReverseCoverage = (
+      acceptance.motionReferenceCoverage ?? []
+    ).filter(
+      (coverage) =>
+        coverage.referenceId === input.referenceId &&
+        coverage.behaviorId === behavior.id,
+    );
+    if (matchingReverseCoverage.length !== 1) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" acceptance "${acceptance.id}" must own exactly one reverse coverage pair; found ${matchingReverseCoverage.length}.`,
+      );
+    }
+
+    let coverageOwnerCount = 0;
+    for (const rows of acceptanceRowsById.values()) {
+      for (const entry of rows) {
+        const ownsCoverage = (entry.motionReferenceCoverage ?? []).some(
+          (coverage) =>
+            coverage.referenceId === input.referenceId &&
+            coverage.behaviorId === behavior.id,
+        );
+        if (ownsCoverage) {
+          coverageOwnerCount += 1;
+        }
+      }
+    }
+    if (coverageOwnerCount > 1) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" coverage pair has ${coverageOwnerCount} acceptance owners; expected exactly one.`,
+      );
+    }
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/motion-reference-study-coverage.ts

@@ -0,0 +1,206 @@
+import type { ToolcraftMotionReferenceInput } from "./types";
+
+const validEventClassifications = new Set<string>([
+  "edit-boundary",
+  "encoding-artifact",
+  "irrelevant-change",
+  "product-behavior",
+]);
+
+export function validateStudyCoverage(
+  input: ToolcraftMotionReferenceInput,
+): string[] {
+  const errors: string[] = [];
+  const behaviorsById = new Map<string, typeof input.behaviors>();
+  for (const behavior of input.behaviors) {
+    behaviorsById.set(behavior.id, [
+      ...(behaviorsById.get(behavior.id) ?? []),
+      behavior,
+    ]);
+  }
+
+  function validateBehaviorId({
+    behaviorId,
+    owner,
+  }: {
+    behaviorId: string;
+    owner: string;
+  }): void {
+    const behaviors = behaviorsById.get(behaviorId) ?? [];
+    if (behaviors.length === 0) {
+      errors.push(`${owner} cites unknown behaviorId "${behaviorId}".`);
+    } else if (behaviors.length > 1) {
+      errors.push(
+        `${owner} cites ambiguous behaviorId "${behaviorId}" with ${behaviors.length} definitions.`,
+      );
+    }
+  }
+
+  for (const study of input.studies) {
+    const reviewedFrameIndex = new Map(
+      study.evidence.reviewedFrames.map((frame, index) => [frame.frameId, index]),
+    );
+    const overviewFrameIndex = new Map<string, number>();
+    let previousReviewedFrameIndex = -1;
+
+    for (const [overviewIndex, frameId] of study.evidence.overviewFrameIds.entries()) {
+      const reviewedIndex = reviewedFrameIndex.get(frameId);
+
+      if (reviewedIndex === undefined) {
+        errors.push(
+          `motion reference study "${study.studyId}" overview frameId "${frameId}" must resolve to reviewedFrames.`,
+        );
+        continue;
+      }
+
+      if (reviewedIndex <= previousReviewedFrameIndex) {
+        errors.push(
+          `motion reference study "${study.studyId}" overviewFrameIds must follow reviewedFrames order; "${frameId}" resolves to index ${reviewedIndex} after ${previousReviewedFrameIndex}.`,
+        );
+      }
+
+      previousReviewedFrameIndex = reviewedIndex;
+      overviewFrameIndex.set(frameId, overviewIndex);
+    }
+
+    if (study.evidence.overviewFrameIds.length > 0 && study.phases.length === 0) {
+      errors.push(
+        `motion reference study "${study.studyId}" phases must cover the complete overview range.`,
+      );
+    }
+
+    let previousPhaseEndIndex: number | undefined;
+    for (const [phaseIndex, phase] of study.phases.entries()) {
+      const fromIndex = overviewFrameIndex.get(phase.fromFrameId);
+      const toIndex = overviewFrameIndex.get(phase.toFrameId);
+
+      if (fromIndex === undefined || toIndex === undefined) {
+        errors.push(
+          `motion reference study "${study.studyId}" phase "${phase.id}" frame range must resolve to overviewFrameIds.`,
+        );
+        continue;
+      }
+
+      if (fromIndex > toIndex) {
+        errors.push(
+          `motion reference study "${study.studyId}" phase "${phase.id}" must not end before it starts.`,
+        );
+      }
+
+      if (phaseIndex === 0 && fromIndex !== 0) {
+        errors.push(
+          `motion reference study "${study.studyId}" phases must start at overview index 0; "${phase.id}" starts at ${fromIndex}.`,
+        );
+      }
+
+      if (
+        previousPhaseEndIndex !== undefined &&
+        fromIndex !== previousPhaseEndIndex + 1
+      ) {
+        errors.push(
+          `motion reference study "${study.studyId}" phases must be contiguous; "${phase.id}" starts at overview index ${fromIndex} after index ${previousPhaseEndIndex}.`,
+        );
+      }
+      previousPhaseEndIndex = toIndex;
+
+      if (!phase.visualState.trim()) {
+        errors.push(
+          `motion reference study "${study.studyId}" phase "${phase.id}" must describe its visualState.`,
+        );
+      }
+
+      for (const behaviorId of phase.behaviorIds) {
+        validateBehaviorId({
+          behaviorId,
+          owner: `motion reference study "${study.studyId}" phase "${phase.id}"`,
+        });
+      }
+    }
+
+    const lastOverviewIndex = study.evidence.overviewFrameIds.length - 1;
+    if (
+      study.phases.length > 0 &&
+      previousPhaseEndIndex !== undefined &&
+      previousPhaseEndIndex !== lastOverviewIndex
+    ) {
+      errors.push(
+        `motion reference study "${study.studyId}" phases must end at overview index ${lastOverviewIndex}; received ${previousPhaseEndIndex}.`,
+      );
+    }
+
+    const evidenceEventsById = new Map(
+      study.evidence.detectedEvents.map((event) => [event.eventId, event]),
+    );
+    const authoredEventsByEvidenceId = new Map<string, typeof study.events>();
+
+    for (const event of study.events) {
+      const existing = authoredEventsByEvidenceId.get(event.evidenceEventId) ?? [];
+      authoredEventsByEvidenceId.set(event.evidenceEventId, [...existing, event]);
+
+      if (!evidenceEventsById.has(event.evidenceEventId)) {
+        errors.push(
+          `motion reference study "${study.studyId}" event "${event.id}" must cite a detected evidenceEventId.`,
+        );
+      }
+
+      if (!validEventClassifications.has(event.classification)) {
+        errors.push(
+          `motion reference study "${study.studyId}" event "${event.id}" has unsupported classification "${String(event.classification)}".`,
+        );
+        continue;
+      }
+
+      if (event.classification === "product-behavior") {
+        if (event.behaviorIds.length === 0) {
+          errors.push(
+            `motion reference study "${study.studyId}" product event "${event.id}" must cite at least one behaviorId.`,
+          );
+        }
+
+        for (const behaviorId of event.behaviorIds) {
+          validateBehaviorId({
+            behaviorId,
+            owner: `motion reference study "${study.studyId}" event "${event.id}"`,
+          });
+        }
+      } else {
+        if (event.behaviorIds.length !== 0) {
+          errors.push(
+            `motion reference study "${study.studyId}" event "${event.id}" classification "${event.classification}" must not cite behaviorIds.`,
+          );
+        }
+
+        if (!event.reason.trim()) {
+          errors.push(
+            `motion reference study "${study.studyId}" event "${event.id}" classification "${event.classification}" requires a non-empty reason.`,
+          );
+        }
+      }
+    }
+
+    for (const evidenceEvent of study.evidence.detectedEvents) {
+      const matchingAuthoredEvents =
+        authoredEventsByEvidenceId.get(evidenceEvent.eventId) ?? [];
+      if (matchingAuthoredEvents.length !== 1) {
+        errors.push(
+          `motion reference study "${study.studyId}" evidence event "${evidenceEvent.eventId}" must have exactly one authored event; found ${matchingAuthoredEvents.length}.`,
+        );
+      }
+
+      for (const frameId of [
+        evidenceEvent.beforeFrameId,
+        evidenceEvent.peakFrameId,
+        evidenceEvent.afterFrameId,
+        ...evidenceEvent.windowFrameIds,
+      ]) {
+        if (!reviewedFrameIndex.has(frameId)) {
+          errors.push(
+            `motion reference study "${study.studyId}" evidence event "${evidenceEvent.eventId}" frameId "${frameId}" must resolve to reviewedFrames.`,
+          );
+        }
+      }
+    }
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/motion-reference-study-identity.ts

@@ -0,0 +1,129 @@
+import type { ToolcraftMotionReferenceInput } from "./types";
+
+export function getMotionReferenceSourceSha256(
+  input: ToolcraftMotionReferenceInput,
+): string | undefined {
+  const sourceSha256Values = new Set(
+    input.studies.map((study) => study.evidence.sourceSha256),
+  );
+
+  return sourceSha256Values.size === 1
+    ? sourceSha256Values.values().next().value
+    : undefined;
+}
+
+export function validateStudyIdentity(
+  input: ToolcraftMotionReferenceInput,
+): string[] {
+  const errors: string[] = [];
+  const studyIds = new Set<string>();
+  const evidencePaths = new Set<string>();
+  const sourceSha256Values = new Set<string>();
+  const behaviorIds = new Set<string>();
+
+  if (input.studies.length === 0) {
+    errors.push(
+      `motion reference "${input.referenceId}" must declare at least one study.`,
+    );
+  }
+
+  for (const behavior of input.behaviors) {
+    if (!behavior.id.trim()) {
+      errors.push(
+        `motion reference "${input.referenceId}" behaviors must include non-empty ids.`,
+      );
+    } else if (behaviorIds.has(behavior.id)) {
+      errors.push(
+        `motion reference "${input.referenceId}" behavior id "${behavior.id}" is duplicated.`,
+      );
+    }
+    behaviorIds.add(behavior.id);
+  }
+
+  for (const study of input.studies) {
+    const studyLabel = study.studyId.trim() || "<missing-study-id>";
+
+    if (!study.studyId.trim()) {
+      errors.push(
+        `motion reference "${input.referenceId}" studies must include non-empty studyId values.`,
+      );
+    } else if (studyIds.has(study.studyId)) {
+      errors.push(
+        `motion reference "${input.referenceId}" studyId "${study.studyId}" is duplicated.`,
+      );
+    }
+    studyIds.add(study.studyId);
+
+    if (evidencePaths.has(study.evidencePath)) {
+      errors.push(
+        `motion reference "${input.referenceId}" evidencePath "${study.evidencePath}" is duplicated.`,
+      );
+    }
+    evidencePaths.add(study.evidencePath);
+
+    if (study.evidence.studyId !== study.studyId) {
+      errors.push(
+        `motion reference study "${studyLabel}" must match evidence.studyId "${study.evidence.studyId}".`,
+      );
+    }
+
+    sourceSha256Values.add(study.evidence.sourceSha256);
+
+    const frameIds = new Set<string>();
+    for (const frame of study.evidence.reviewedFrames) {
+      if (frameIds.has(frame.frameId)) {
+        errors.push(
+          `motion reference study "${studyLabel}" reviewed frameId "${frame.frameId}" is duplicated.`,
+        );
+      }
+      frameIds.add(frame.frameId);
+
+      if (frame.sourceSha256 !== study.evidence.sourceSha256) {
+        errors.push(
+          `motion reference study "${studyLabel}" frame "${frame.frameId}" sourceSha256 must match its evidence sourceSha256.`,
+        );
+      }
+    }
+
+    const evidenceEventIds = new Set<string>();
+    for (const event of study.evidence.detectedEvents) {
+      if (evidenceEventIds.has(event.eventId)) {
+        errors.push(
+          `motion reference study "${studyLabel}" evidence eventId "${event.eventId}" is duplicated.`,
+        );
+      }
+      evidenceEventIds.add(event.eventId);
+    }
+
+    const eventIds = new Set<string>();
+    for (const event of study.events) {
+      if (eventIds.has(event.id)) {
+        errors.push(
+          `motion reference study "${studyLabel}" event id "${event.id}" is duplicated.`,
+        );
+      }
+      eventIds.add(event.id);
+    }
+
+    const phaseIds = new Set<string>();
+    for (const phase of study.phases) {
+      if (phaseIds.has(phase.id)) {
+        errors.push(
+          `motion reference study "${studyLabel}" phase id "${phase.id}" is duplicated.`,
+        );
+      }
+      phaseIds.add(phase.id);
+    }
+  }
+
+  if (sourceSha256Values.size > 1) {
+    const sortedSourceSha256Values = [...sourceSha256Values].sort((left, right) =>
+      left.localeCompare(right, "en"),
+    );
+    errors.push(
+      `motion reference "${input.referenceId}" studies must share one sourceSha256; found ${sortedSourceSha256Values.join(", ")}.`,
+    );
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/motion-reference-study-partitions.ts

@@ -0,0 +1,186 @@
+import type { ToolcraftMotionReferenceInput } from "./types";
+
+type TimedStudyEvidence = Extract<
+  ToolcraftMotionReferenceInput["studies"][number]["evidence"],
+  { timingMode: "seconds" }
+>;
+type ReviewPartition = NonNullable<TimedStudyEvidence["reviewPartition"]>;
+
+type PartitionStudy = {
+  evidence: TimedStudyEvidence;
+  partition: ReviewPartition;
+  studyId: string;
+};
+
+function formatNumber(value: number): string {
+  return String(value);
+}
+
+function compareNumbers(left: number, right: number): number {
+  if (Number.isFinite(left) && Number.isFinite(right)) {
+    return left - right;
+  }
+  return formatNumber(left).localeCompare(formatNumber(right), "en");
+}
+
+export function validatePartitionCoverage(
+  input: ToolcraftMotionReferenceInput,
+): string[] {
+  const errors: string[] = [];
+  const groups = new Map<string, PartitionStudy[]>();
+
+  for (const study of input.studies) {
+    if (study.evidence.timingMode !== "seconds") {
+      continue;
+    }
+    const partition = study.evidence.reviewPartition;
+    if (!partition) {
+      continue;
+    }
+
+    const group = groups.get(partition.groupId) ?? [];
+    group.push({ evidence: study.evidence, partition, studyId: study.studyId });
+    groups.set(partition.groupId, group);
+  }
+
+  for (const [groupId, group] of groups) {
+    const countValues = [...new Set(group.map(({ partition }) => partition.count))];
+    const invalidCounts = countValues
+      .filter((count) => !Number.isSafeInteger(count) || count <= 0)
+      .sort(compareNumbers);
+    for (const count of invalidCounts) {
+      errors.push(
+        `motion reference partition "${groupId}" count must be a finite safe positive integer; received ${formatNumber(count)}.`,
+      );
+    }
+
+    const countIsShared = countValues.length === 1;
+    if (!countIsShared) {
+      errors.push(
+        `motion reference partition "${groupId}" studies must declare one shared count.`,
+      );
+    }
+
+    const validCounts = countValues.filter(
+      (count) => Number.isSafeInteger(count) && count > 0,
+    );
+    const oversizedCounts = validCounts
+      .filter((count) => count > group.length)
+      .sort(compareNumbers);
+    for (const count of oversizedCounts) {
+      errors.push(
+        `motion reference partition "${groupId}" count ${count} cannot exceed group cardinality ${group.length}.`,
+      );
+    }
+
+    const planValues = new Set(
+      group.map(({ partition }) => partition.planSha256),
+    );
+    const planIsShared = planValues.size === 1;
+    if (!planIsShared) {
+      errors.push(
+        `motion reference partition "${groupId}" studies must declare one shared planSha256.`,
+      );
+    }
+
+    const scopeStarts = new Set(
+      group.map(({ partition }) => partition.scope.startSeconds),
+    );
+    const scopeEnds = new Set(
+      group.map(({ partition }) => partition.scope.endSeconds),
+    );
+    const scopeIsShared = scopeStarts.size === 1 && scopeEnds.size === 1;
+    if (!scopeIsShared) {
+      errors.push(
+        `motion reference partition "${groupId}" studies must declare one shared scope.`,
+      );
+    }
+
+    const metadataIsValid =
+      invalidCounts.length === 0 &&
+      oversizedCounts.length === 0 &&
+      countIsShared &&
+      planIsShared &&
+      scopeIsShared;
+    if (!metadataIsValid) {
+      continue;
+    }
+
+    const [expectedCount] = countValues;
+    const [scopeStart] = scopeStarts;
+    const [scopeEnd] = scopeEnds;
+    if (
+      expectedCount === undefined ||
+      scopeStart === undefined ||
+      scopeEnd === undefined
+    ) {
+      continue;
+    }
+
+    const orderedGroup = [...group].sort((left, right) => {
+      const indexOrder = compareNumbers(
+        left.partition.index,
+        right.partition.index,
+      );
+      return indexOrder || left.studyId.localeCompare(right.studyId, "en");
+    });
+    const receivedIndices = orderedGroup.map(({ partition }) => partition.index);
+    const indicesAreExact =
+      orderedGroup.length === expectedCount &&
+      receivedIndices.every((index, position) => index === position);
+    if (!indicesAreExact) {
+      errors.push(
+        `motion reference partition "${groupId}" must contain indices 0..${expectedCount - 1} exactly; received ${receivedIndices.join(", ")}.`,
+      );
+      continue;
+    }
+
+    let previousEnd: number | undefined;
+    for (const { evidence, partition, studyId } of orderedGroup) {
+      const segment = evidence.segment;
+      if (!segment) {
+        errors.push(
+          `motion reference partition "${groupId}" study "${studyId}" must declare an explicit segment.`,
+        );
+        continue;
+      }
+
+      if (segment.endSeconds <= segment.startSeconds) {
+        errors.push(
+          `motion reference partition "${groupId}" study "${studyId}" segment must have positive duration.`,
+        );
+      }
+      if (partition.index === 0 && segment.startSeconds !== scopeStart) {
+        errors.push(
+          `motion reference partition "${groupId}" segments must start at scope.startSeconds ${scopeStart}; received ${segment.startSeconds}.`,
+        );
+      }
+      if (previousEnd !== undefined && segment.startSeconds !== previousEnd) {
+        errors.push(
+          `motion reference partition "${groupId}" segments must be contiguous and non-overlapping; index ${partition.index} starts at ${segment.startSeconds} after ${previousEnd}.`,
+        );
+      }
+      previousEnd = segment.endSeconds;
+
+      const scopeCoversFullSource =
+        scopeStart === 0 && scopeEnd === evidence.durationSeconds;
+      if (
+        scopeCoversFullSource &&
+        partition.index !== 0 &&
+        evidence.detectedEvents.some((event) => event.kind === "loop-seam")
+      ) {
+        errors.push(
+          `motion reference partition "${groupId}" original loop-seam evidence must appear only in index 0.`,
+        );
+      }
+    }
+
+    if (previousEnd !== undefined && previousEnd !== scopeEnd) {
+      errors.push(
+        `motion reference partition "${groupId}" segments must end at scope.endSeconds ${scopeEnd}; received ${previousEnd}.`,
+      );
+    }
+  }
+
+  return errors;
+}