@thinkai/tai-api-contract 2.62.0 → 2.64.0

package/src/index.ts

@@ -1423,6 +1423,283 @@ export interface AiToolMemberDetailDto {
   heatmap: AiToolMemberHeatmapDayDto[];
 }
 
+/** Canonical SDLC Engineering Health module ids. */
+export const SDL_C_MODULE_IDS = [
+  "dora",
+  "ci-pipeline",
+  "collaboration-pr",
+  "security-risk",
+  "governance-architecture",
+  "financial-operational",
+] as const;
+export type SdlcModuleId = (typeof SDL_C_MODULE_IDS)[number];
+
+/** Canonical SDLC Engineering Health metric ids (34). */
+export const SDL_C_METRIC_IDS = [
+  "dora-deployment-frequency",
+  "dora-lead-time",
+  "dora-cfr",
+  "dora-mttr",
+  "ci-success-rate",
+  "ci-duration-p50-p95",
+  "ci-flakiness",
+  "ci-queue-wait",
+  "ci-cache-hit",
+  "pr-review-time",
+  "pr-bus-factor",
+  "pr-size",
+  "pr-abandonment",
+  "pr-review-depth",
+  "pr-draft-duration",
+  "pr-merge-conflicts",
+  "pr-commit-density",
+  "sec-dependabot-backlog",
+  "sec-vuln-mttr",
+  "sec-secret-scanning",
+  "sec-self-approvals",
+  "sec-unreviewed-merge",
+  "gov-branch-protection",
+  "gov-stale-branches",
+  "gov-orphaned-repos",
+  "gov-readme-health",
+  "gov-codeowners",
+  "gov-issue-pr-linkage",
+  "fin-gha-minutes",
+  "fin-copilot-utilization",
+  "fin-org-inactivity",
+  "fin-env-drift",
+  "fin-release-cadence",
+  "fin-api-rate-limit",
+] as const;
+export type SdlcMetricId = (typeof SDL_C_METRIC_IDS)[number];
+
+export type SdlcMetricDataStatus = "live" | "preview" | "unavailable";
+export type SdlcMetricHealthStatus = "healthy" | "warning" | "critical" | "unknown";
+export type SdlcBenchmarkBand = "elite" | "high" | "medium" | "low";
+
+export interface SdlcMetricTrendDto {
+  direction: "up" | "down" | "flat";
+  deltaPercent?: number;
+}
+
+export interface SdlcDailySeriesPointDto {
+  date: string;
+  value: number;
+}
+
+export interface SdlcMetricDto {
+  id: SdlcMetricId;
+  name: string;
+  dataStatus: SdlcMetricDataStatus;
+  healthStatus: SdlcMetricHealthStatus;
+  value: number | string | null;
+  unit?: string;
+  secondaryValue?: number | string | null;
+  secondaryLabel?: string;
+  trend?: SdlcMetricTrendDto;
+  benchmarkBand?: SdlcBenchmarkBand;
+  drilldownAvailable: boolean;
+  dailySeries?: SdlcDailySeriesPointDto[];
+  unavailableReason?: string;
+}
+
+export interface SdlcModuleDto {
+  id: SdlcModuleId;
+  name: string;
+  metrics: SdlcMetricDto[];
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/sdlc/overview */
+export interface SdlcOverviewDto {
+  rangeId: string;
+  from: string;
+  to: string;
+  department: string;
+  team: string;
+  repoIds: string[];
+  asOf: string;
+  modules: SdlcModuleDto[];
+}
+
+export interface SdlcDrilldownItemDto {
+  id: string;
+  title: string;
+  subtitle?: string;
+  url?: string;
+  occurredAt?: string;
+  metadata?: Record<string, string | number>;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/sdlc/drilldown/{metricId} */
+export interface SdlcDrilldownDto {
+  metricId: SdlcMetricId;
+  items: SdlcDrilldownItemDto[];
+  nextCursor?: string;
+}
+
+/** Shared Insights & Recommendations response meta (`_meta.isMock` is always false in production). */
+export interface InsightsResponseMeta {
+  syncedAt: string;
+  isMock: false;
+}
+
+export type InsightsVerdictStatus = "healthy" | "watch" | "at-risk";
+
+export interface InsightsRecommendationsVerdictSummary {
+  /** Merged-PR volume ratio vs prior equal-length window. */
+  productivityMultiplier: number;
+  productivityStatus: InsightsVerdictStatus;
+  ciFailRatePct: number;
+  qualityStatus: InsightsVerdictStatus;
+  spendPerMergedPrUsd: number;
+  spendPerMergedPrPrevUsd: number;
+  costStatus: InsightsVerdictStatus;
+}
+
+export interface InsightsRoiEngineerPoint {
+  id: string;
+  name: string;
+  team: string;
+  spendUsd: number;
+  mergedPrs: number;
+}
+
+export interface InsightsRecommendationsRoiQuadrant {
+  medianSpendUsd: number;
+  medianMergedPrs: number;
+  engineers: InsightsRoiEngineerPoint[];
+  correlationHint: string;
+}
+
+export interface InsightsVelocityQualityWeek {
+  weekStartIso: string;
+  mergedPrs: number;
+  ciFailRatePct: number;
+}
+
+export interface InsightsRecommendationsVelocityQuality {
+  weeks: InsightsVelocityQualityWeek[];
+  targetFailRatePct: number;
+  volumeGrowthPct: number;
+}
+
+export const INSIGHTS_REVIEW_STAGE_IDS = [
+  "open-review",
+  "review-approval",
+  "approval-merge",
+  "merged",
+] as const;
+export type InsightsReviewStageId = (typeof INSIGHTS_REVIEW_STAGE_IDS)[number];
+
+export interface InsightsReviewStage {
+  id: InsightsReviewStageId;
+  name: string;
+  medianHours: number;
+  trendPct: number;
+}
+
+export interface InsightsReviewerLoadItem {
+  id: string;
+  name: string;
+  reviewsCount: number;
+  sharePct: number;
+}
+
+export interface InsightsRecommendationsReviewPipeline {
+  stages: InsightsReviewStage[];
+  bottleneckStageId: InsightsReviewStageId;
+  reviewerLoad: InsightsReviewerLoadItem[];
+}
+
+export interface InsightsCostPerPrTeam {
+  id: string;
+  name: string;
+  activeAi: number;
+  spendUsd: number;
+  mergedPrs: number;
+  costPerPrUsd: number;
+  changePct: number;
+}
+
+export interface InsightsRecommendationsCostPerPr {
+  orgAvgCostUsd: number;
+  orgAvgPrevUsd: number;
+  teams: InsightsCostPerPrTeam[];
+}
+
+export interface InsightsAdoptionTeam {
+  id: string;
+  name: string;
+  activeAi: number;
+  totalMembers: number;
+  readinessPct: number;
+  outputPerEngPerWeek: number;
+}
+
+export interface InsightsRecommendationsAdoptionGap {
+  totalContributors: number;
+  activeContributors: number;
+  upliftPct: number;
+  teams: InsightsAdoptionTeam[];
+}
+
+export const INSIGHTS_RECOMMENDATION_MODULE_IDS = [
+  "mod-spend-vs-output",
+  "mod-velocity-vs-quality",
+  "mod-review-bottleneck",
+  "mod-cost-per-pr",
+  "mod-adoption-gap",
+] as const;
+export type InsightsRecommendationModuleId = (typeof INSIGHTS_RECOMMENDATION_MODULE_IDS)[number];
+
+export type InsightsRecommendationImpact = "high" | "medium";
+export type InsightsRecommendationTone = "action" | "no-action";
+export type InsightsEvidenceLinkKind = "user-spend" | "team" | "contributor" | "repo" | "module";
+
+export interface InsightsEvidenceChip {
+  label: string;
+  kind: InsightsEvidenceLinkKind;
+  targetId: string;
+}
+
+export interface InsightsRecommendationEvidenceGroup {
+  title: string;
+  chips: InsightsEvidenceChip[];
+}
+
+export interface InsightsRecommendationDto {
+  moduleId: InsightsRecommendationModuleId;
+  moduleName: string;
+  tone: InsightsRecommendationTone;
+  impact: InsightsRecommendationImpact;
+  headline: string;
+  observed: string;
+  action: string;
+  benefit: string;
+  confidencePct: number;
+  evidence: InsightsRecommendationEvidenceGroup[];
+}
+
+export type WithInsightsMeta<T> = T & { _meta: InsightsResponseMeta };
+
+export type InsightsRecommendationsVerdictSummaryResponse =
+  WithInsightsMeta<InsightsRecommendationsVerdictSummary>;
+export type InsightsRecommendationsRoiQuadrantResponse =
+  WithInsightsMeta<InsightsRecommendationsRoiQuadrant>;
+export type InsightsRecommendationsVelocityQualityResponse =
+  WithInsightsMeta<InsightsRecommendationsVelocityQuality>;
+export type InsightsRecommendationsReviewPipelineResponse =
+  WithInsightsMeta<InsightsRecommendationsReviewPipeline>;
+export type InsightsRecommendationsCostPerPrResponse =
+  WithInsightsMeta<InsightsRecommendationsCostPerPr>;
+export type InsightsRecommendationsAdoptionGapResponse =
+  WithInsightsMeta<InsightsRecommendationsAdoptionGap>;
+
+export interface InsightsRecommendationsListResponse {
+  items: InsightsRecommendationDto[];
+  _meta: InsightsResponseMeta;
+}
+
 export {
   JOURNEY_STEP_IDS,
   JOURNEY_STEP_REGISTRY,