@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/result-explorer-view.ts

@@ -0,0 +1,597 @@
+/**
+ * Pure presentation for BB's isolated, read-only Build results explorer.
+ *
+ * The explorer consumes BRCS-02's closed result model. It does not read evidence
+ * bodies, infer a winner, recompute verification, or expose mutation controls.
+ * BRCS-07 may render these sections and references without adding result logic.
+ */
+
+import type { ResultReadbackView } from './result-readback-model.js';
+import type { EvidenceReferenceView } from './result-readback-schema.js';
+import type { ResultReadbackResult } from './result-readback-service.js';
+
+export const RESULT_EXPLORER_VIEW_VERSION = '1.0.0' as const;
+
+export type ResultExplorerKind = ResultReadbackView['kind'];
+
+export type ResultExplorerCondition =
+  | 'healthy'
+  | 'degraded'
+  | 'partial'
+  | 'stale'
+  | 'historical'
+  | 'unknown-freshness'
+  | 'malformed'
+  | 'incompatible'
+  | 'unavailable'
+  | 'empty'
+  | 'not-applicable';
+
+export type ResultExplorerReferenceType =
+  | 'artifact'
+  | 'patch'
+  | 'commit'
+  | 'branch'
+  | 'changed-file'
+  | 'pull-request'
+  | 'workflow'
+  | 'verification'
+  | 'worktree'
+  | 'judge'
+  | 'synthesis'
+  | 'delivery';
+
+export interface ResultExplorerReference {
+  id: string;
+  type: ResultExplorerReferenceType;
+  label: string;
+  value: string;
+  variant: string | null;
+  /** Only canonical patch references may advertise a read-only preview. */
+  previewEligible: boolean;
+}
+
+export interface ResultExplorerRow {
+  id: string;
+  label: string;
+  value: string;
+}
+
+export type ResultExplorerSectionRole =
+  | 'outcome'
+  | 'comparison'
+  | 'winner'
+  | 'synthesis'
+  | 'delivery'
+  | 'workflow'
+  | 'git'
+  | 'verification'
+  | 'blockers'
+  | 'finalization'
+  | 'evidence'
+  | 'provenance'
+  | 'health'
+  | 'notice';
+
+export interface ResultExplorerSection {
+  id: string;
+  role: ResultExplorerSectionRole;
+  title: string;
+  rows: readonly ResultExplorerRow[];
+  references: readonly ResultExplorerReference[];
+  /** Null when the section contains evidence; otherwise an explicit empty state. */
+  emptyState: string | null;
+}
+
+export interface ResultExplorerView {
+  viewVersion: typeof RESULT_EXPLORER_VIEW_VERSION;
+  state: 'available' | 'unavailable';
+  kind: ResultExplorerKind;
+  runId: string;
+  headline: string;
+  conditions: readonly ResultExplorerCondition[];
+  standaloneCommand: string;
+  sections: readonly ResultExplorerSection[];
+  /** This presentation surface intentionally has no result mutation controls. */
+  controls: readonly [];
+}
+
+const EVIDENCE_TYPES: Readonly<Record<EvidenceReferenceView['kind'], ResultExplorerReferenceType>> =
+  {
+    artifact: 'artifact',
+    branch: 'branch',
+    changed_file: 'changed-file',
+    commit: 'commit',
+    delivery: 'delivery',
+    judge: 'judge',
+    patch: 'patch',
+    synthesis: 'synthesis',
+    verification: 'verification',
+    worktree: 'worktree',
+  };
+
+const REFERENCE_LABELS: Readonly<Record<ResultExplorerReferenceType, string>> = {
+  artifact: 'Artifact',
+  patch: 'Patch',
+  commit: 'Commit',
+  branch: 'Branch',
+  'changed-file': 'Changed file',
+  'pull-request': 'Pull request',
+  workflow: 'Workflow',
+  verification: 'Verification',
+  worktree: 'Worktree',
+  judge: 'Judge result',
+  synthesis: 'Synthesis',
+  delivery: 'Delivery',
+};
+
+const COMMAND_PREFIXES: Readonly<Record<ResultExplorerKind, string>> = {
+  competition: 'build run competition results',
+  fusion: 'build run fusion results',
+  'backlog-execute': 'build plan backlog show',
+};
+
+function standaloneCommand(kind: ResultExplorerKind, runId: string): string {
+  return `${COMMAND_PREFIXES[kind]} ${runId} --json`;
+}
+
+function valueOrUnavailable(value: string | number | null | undefined): string {
+  if (value === null || value === undefined || value === '') return 'unavailable';
+  return String(value);
+}
+
+function listOrNone(values: readonly string[]): string {
+  return values.length === 0 ? 'none' : values.join(', ');
+}
+
+function evidenceReferences(
+  evidence: readonly EvidenceReferenceView[],
+  idPrefix: string
+): ResultExplorerReference[] {
+  return evidence.map((item, index) => {
+    const type = EVIDENCE_TYPES[item.kind];
+    return {
+      id: `${idPrefix}-${index + 1}`,
+      type,
+      label: REFERENCE_LABELS[type],
+      value: item.value,
+      variant: item.variant ?? null,
+      previewEligible: type === 'patch',
+    };
+  });
+}
+
+function directReference(
+  id: string,
+  type: Exclude<ResultExplorerReferenceType, 'patch'>,
+  value: string
+): ResultExplorerReference {
+  return {
+    id,
+    type,
+    label: REFERENCE_LABELS[type],
+    value,
+    variant: null,
+    previewEligible: false,
+  };
+}
+
+function section(
+  id: string,
+  role: ResultExplorerSectionRole,
+  title: string,
+  rows: readonly ResultExplorerRow[] = [],
+  references: readonly ResultExplorerReference[] = [],
+  emptyLabel = 'Build reports no evidence for this section.'
+): ResultExplorerSection {
+  return {
+    id,
+    role,
+    title,
+    rows,
+    references,
+    emptyState: rows.length === 0 && references.length === 0 ? emptyLabel : null,
+  };
+}
+
+function baseSections(view: ResultReadbackView): ResultExplorerSection[] {
+  return [
+    section('outcome', 'outcome', 'Outcome', [
+      { id: 'run-status', label: 'Status', value: view.status },
+      { id: 'terminal', label: 'Terminal', value: view.terminal ? 'yes' : 'no' },
+    ]),
+  ];
+}
+
+function candidateSections(
+  candidates: Extract<ResultReadbackView, { kind: 'competition' }>['candidates'],
+  noun: 'Candidate' | 'Contributor',
+  excludeJudgeEvidence = false
+): ResultExplorerSection[] {
+  if (candidates.length === 0) {
+    return [
+      section(
+        `${noun.toLowerCase()}s`,
+        'comparison',
+        `${noun} comparison`,
+        [],
+        [],
+        `Build reports no ${noun.toLowerCase()}s.`
+      ),
+    ];
+  }
+
+  return candidates.map((candidate, index) => {
+    const visibleEvidence = excludeJudgeEvidence
+      ? candidate.evidence.filter((item) => item.kind !== 'judge')
+      : candidate.evidence;
+    const references = evidenceReferences(visibleEvidence, `${noun.toLowerCase()}-${index + 1}`);
+    if (candidate.branch) {
+      references.unshift(
+        directReference(`${noun.toLowerCase()}-${index + 1}-branch`, 'branch', candidate.branch)
+      );
+    }
+    if (candidate.worktree) {
+      references.unshift(
+        directReference(
+          `${noun.toLowerCase()}-${index + 1}-worktree`,
+          'worktree',
+          candidate.worktree
+        )
+      );
+    }
+    return section(
+      `${noun.toLowerCase()}-${index + 1}`,
+      'comparison',
+      `${noun}: ${candidate.id}`,
+      [
+        { id: 'identity', label: 'Provider', value: candidate.provider },
+        { id: 'model', label: 'Model', value: valueOrUnavailable(candidate.model) },
+        { id: 'status', label: 'Status', value: candidate.status },
+        { id: 'phase', label: 'Phase', value: candidate.phase },
+        {
+          id: 'changed-files',
+          label: 'Changed files',
+          value: valueOrUnavailable(candidate.changedFiles),
+        },
+        {
+          id: 'build-verification',
+          label: 'Build verification',
+          value: valueOrUnavailable(candidate.verification.buildStatus),
+        },
+        {
+          id: 'lint-verification',
+          label: 'Lint verification',
+          value: valueOrUnavailable(candidate.verification.lintStatus),
+        },
+        {
+          id: 'test-verification',
+          label: 'Test verification',
+          value: valueOrUnavailable(candidate.verification.testStatus),
+        },
+      ],
+      references
+    );
+  });
+}
+
+function evidenceSection(
+  id: string,
+  role: ResultExplorerSectionRole,
+  title: string,
+  evidence: readonly EvidenceReferenceView[],
+  emptyLabel?: string
+): ResultExplorerSection {
+  return section(id, role, title, [], evidenceReferences(evidence, id), emptyLabel);
+}
+
+function healthSection(view: ResultReadbackView): ResultExplorerSection {
+  return section('health', 'health', 'Health and freshness', [
+    { id: 'health-state', label: 'Health', value: view.health.state },
+    { id: 'health-issues', label: 'Health issues', value: listOrNone(view.health.issues) },
+    { id: 'freshness-state', label: 'Freshness', value: view.freshness.state },
+    { id: 'freshness-checked', label: 'Checked at', value: view.freshness.checkedAt },
+    {
+      id: 'freshness-modified',
+      label: 'Last modified at',
+      value: valueOrUnavailable(view.freshness.lastModifiedAt),
+    },
+  ]);
+}
+
+type AvailableResult = Extract<ResultReadbackResult, { state: 'available' }>;
+
+function provenanceSection(
+  view: ResultReadbackView,
+  repository: AvailableResult['repository'],
+  visibleEvidence: readonly EvidenceReferenceView[] = view.evidence
+): ResultExplorerSection {
+  return section(
+    'provenance',
+    'provenance',
+    'Provenance',
+    [
+      { id: 'run-id', label: 'Run', value: view.runId },
+      { id: 'project-id', label: 'Project', value: repository.projectId },
+      { id: 'source-id', label: 'Source', value: repository.sourceId },
+      {
+        id: 'repository-path',
+        label: 'Repository',
+        value: repository.path,
+      },
+    ],
+    evidenceReferences(visibleEvidence, 'provenance')
+  );
+}
+
+function buildCompetitionSections(
+  view: Extract<ResultReadbackView, { kind: 'competition' }>,
+  repository: AvailableResult['repository']
+): ResultExplorerSection[] {
+  const gitKinds: readonly EvidenceReferenceView['kind'][] = [
+    'branch',
+    'changed_file',
+    'commit',
+    'patch',
+    'worktree',
+  ];
+  const verification = [
+    ...view.evidence.filter((item) => item.kind === 'verification'),
+    ...view.candidates.flatMap((candidate) =>
+      candidate.evidence.filter((item) => item.kind === 'verification')
+    ),
+  ];
+  return [
+    ...baseSections(view),
+    ...candidateSections(view.candidates, 'Candidate'),
+    evidenceSection(
+      'judge-winner',
+      'winner',
+      'Judge winner (immutable)',
+      view.judgeWinner.evidence,
+      'Build reports no Judge winner evidence.'
+    ),
+    evidenceSection('synthesis', 'synthesis', 'Synthesis', view.synthesis.evidence),
+    evidenceSection('delivery', 'delivery', 'Delivery', view.delivery.evidence),
+    evidenceSection('verification', 'verification', 'Verification', verification),
+    evidenceSection(
+      'git-references',
+      'git',
+      'Git references',
+      view.evidence.filter((item) => gitKinds.includes(item.kind))
+    ),
+    provenanceSection(view, repository),
+    healthSection(view),
+  ];
+}
+
+function buildFusionSections(
+  view: Extract<ResultReadbackView, { kind: 'fusion' }>,
+  repository: AvailableResult['repository']
+): ResultExplorerSection[] {
+  const visibleEvidence = view.evidence.filter((item) => item.kind !== 'judge');
+  return [
+    ...baseSections(view),
+    section('judge-policy', 'notice', 'Judging', [
+      {
+        id: 'judge-not-applicable',
+        label: 'Judge',
+        value: 'Not applicable: Fusion has no Judge winner by design.',
+      },
+    ]),
+    ...candidateSections(view.contributors, 'Contributor', true),
+    evidenceSection('synthesis', 'synthesis', 'Synthesis', view.synthesis.evidence),
+    evidenceSection('delivery', 'delivery', 'Delivery', view.delivery.evidence),
+    evidenceSection('evidence', 'evidence', 'Evidence', visibleEvidence),
+    provenanceSection(view, repository, visibleEvidence),
+    healthSection(view),
+  ];
+}
+
+function buildTrackedSections(
+  view: Extract<ResultReadbackView, { kind: 'backlog-execute' }>,
+  repository: AvailableResult['repository']
+): ResultExplorerSection[] {
+  const visibleEvidence = view.evidence.filter(
+    (item) => item.kind !== 'judge' && item.kind !== 'synthesis' && item.kind !== 'delivery'
+  );
+  const workflowReferences: ResultExplorerReference[] = [];
+  if (view.workflow.workflowId) {
+    workflowReferences.push(
+      directReference('workflow-id-reference', 'workflow', view.workflow.workflowId)
+    );
+  }
+  const gitReferences = evidenceReferences(
+    visibleEvidence.filter((item) =>
+      ['branch', 'changed_file', 'commit', 'patch', 'worktree'].includes(item.kind)
+    ),
+    'git'
+  );
+  if (view.branch.name) {
+    gitReferences.unshift(directReference('tracked-branch', 'branch', view.branch.name));
+  }
+  if (view.pullRequest.number !== null) {
+    gitReferences.push(
+      directReference('tracked-pr', 'pull-request', `#${view.pullRequest.number}`)
+    );
+  }
+  return [
+    ...baseSections(view),
+    section(
+      'workflow',
+      'workflow',
+      'Workflow',
+      [
+        {
+          id: 'workflow-id',
+          label: 'Workflow',
+          value: valueOrUnavailable(view.workflow.workflowId),
+        },
+        { id: 'sprint-id', label: 'Sprint', value: valueOrUnavailable(view.workflow.sprintId) },
+        { id: 'task-ids', label: 'Tasks', value: listOrNone(view.workflow.taskIds) },
+        {
+          id: 'plan-artifact',
+          label: 'Plan artifact',
+          value: valueOrUnavailable(view.workflow.planArtifact),
+        },
+        { id: 'process-state', label: 'Process', value: view.process.state },
+        {
+          id: 'last-step',
+          label: 'Last completed step',
+          value: valueOrUnavailable(view.steps.lastCompletedStep),
+        },
+        {
+          id: 'failed-step',
+          label: 'Failed at step',
+          value: valueOrUnavailable(view.steps.failedAtStep),
+        },
+        {
+          id: 'step-error',
+          label: 'Error',
+          value: valueOrUnavailable(view.steps.errorMessage),
+        },
+      ],
+      workflowReferences
+    ),
+    section(
+      'git-references',
+      'git',
+      'Branch, commit, and pull request',
+      [
+        { id: 'branch-role', label: 'Branch role', value: valueOrUnavailable(view.branch.role) },
+        {
+          id: 'branch-action',
+          label: 'Branch action',
+          value: valueOrUnavailable(view.branch.action),
+        },
+        {
+          id: 'source-branch',
+          label: 'Source branch',
+          value: valueOrUnavailable(view.branch.sourceBranch),
+        },
+        {
+          id: 'merge-commit',
+          label: 'PR merge commit',
+          value: valueOrUnavailable(view.pullRequest.mergeCommit),
+        },
+      ],
+      gitReferences
+    ),
+    evidenceSection(
+      'verification',
+      'verification',
+      'Verification',
+      visibleEvidence.filter((item) => item.kind === 'verification')
+    ),
+    section(
+      'blockers',
+      'blockers',
+      'Blockers',
+      view.blockers.map((blocker, index) => ({
+        id: `blocker-${index + 1}`,
+        label: blocker.id ? `Blocker ${blocker.id}` : `Blocker ${index + 1}`,
+        value: blocker.question,
+      })),
+      [],
+      'Build reports no blockers.'
+    ),
+    section('finalization', 'finalization', 'Finalization and delivery', [
+      { id: 'finalization-state', label: 'Finalization', value: view.finalization.state },
+      {
+        id: 'finalization-commit',
+        label: 'Final merge commit',
+        value: valueOrUnavailable(view.finalization.mergeCommit),
+      },
+      {
+        id: 'archive-pr',
+        label: 'Archive sync PR',
+        value:
+          view.finalization.archiveSyncPrNumber === null
+            ? 'unavailable'
+            : `#${view.finalization.archiveSyncPrNumber}`,
+      },
+      {
+        id: 'archive-warning',
+        label: 'Archive warning',
+        value: valueOrUnavailable(view.finalization.archiveSyncWarning),
+      },
+    ]),
+    provenanceSection(view, repository, visibleEvidence),
+    healthSection(view),
+  ];
+}
+
+function availableConditions(view: ResultReadbackView): ResultExplorerCondition[] {
+  const conditions: ResultExplorerCondition[] = [];
+  if (view.health.state === 'healthy') conditions.push('healthy');
+  if (view.health.state === 'degraded') conditions.push('degraded');
+  if (view.health.issues.includes('partial')) conditions.push('partial');
+  if (view.freshness.state === 'stale' || view.health.issues.includes('stale')) {
+    conditions.push('stale');
+  }
+  if (view.freshness.state === 'historical') conditions.push('historical');
+  if (view.freshness.state === 'unknown') conditions.push('unknown-freshness');
+  if (view.evidence.length === 0) conditions.push('empty');
+  if (view.kind === 'fusion') conditions.push('not-applicable');
+  return conditions;
+}
+
+function unavailableCondition(
+  reason: Extract<ResultReadbackResult, { state: 'unavailable' }>['reason']
+): ResultExplorerCondition {
+  if (reason === 'malformed-output') return 'malformed';
+  if (reason === 'unsupported-major') return 'incompatible';
+  return 'unavailable';
+}
+
+function unavailableHeadline(
+  reason: Extract<ResultReadbackResult, { state: 'unavailable' }>['reason']
+): string {
+  if (reason === 'malformed-output') return 'Result evidence is malformed';
+  if (reason === 'unsupported-major') return 'Result evidence is incompatible';
+  return 'Result evidence is unavailable';
+}
+
+/** Build one deterministic, read-only explorer view from the canonical readback result. */
+export function buildResultExplorerView(
+  kind: ResultExplorerKind,
+  result: ResultReadbackResult
+): ResultExplorerView {
+  if (result.state === 'unavailable') {
+    return {
+      viewVersion: RESULT_EXPLORER_VIEW_VERSION,
+      state: 'unavailable',
+      kind,
+      runId: result.runId,
+      headline: unavailableHeadline(result.reason),
+      conditions: [unavailableCondition(result.reason)],
+      standaloneCommand: standaloneCommand(kind, result.runId),
+      sections: [
+        section('unavailable', 'notice', 'Result unavailable', [
+          { id: 'reason', label: 'Reason', value: result.reason },
+          { id: 'detail', label: 'Detail', value: result.message },
+        ]),
+      ],
+      controls: [],
+    };
+  }
+
+  const view = result.view;
+  const sections =
+    view.kind === 'competition'
+      ? buildCompetitionSections(view, result.repository)
+      : view.kind === 'fusion'
+        ? buildFusionSections(view, result.repository)
+        : buildTrackedSections(view, result.repository);
+  return {
+    viewVersion: RESULT_EXPLORER_VIEW_VERSION,
+    state: 'available',
+    kind: view.kind,
+    runId: view.runId,
+    headline: `${view.kind} result: ${view.status}`,
+    conditions: availableConditions(view),
+    standaloneCommand: standaloneCommand(view.kind, view.runId),
+    sections,
+    controls: [],
+  };
+}