@thinkai/tai-api-contract 2.127.0 → 2.128.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.127.0
+  version: 2.128.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -3844,12 +3844,15 @@ paths:
       operationId: getInsightsTestPyramidSummary
       description: >
         Org-level Test pyramid assessment for `/insights/test-pyramid`. Aggregates each
-        active repo's **latest** readiness-scan test-pyramid snapshot. Layer **presence
-        is count-based** (`fileCount > 0`); CI/dependency-only AF `present` flags are
-        ignored. Shape uses fixed advisory targets (base ~70% unit, middle ~20%
-        integration+contract+acceptance/BDD, top ~10% E2E) and returns
-        `insufficient_data` when total classified test files < 10. Does not change
-        Agentic Foundation `/readiness/test-pyramid*` responses.
+        active repo's **latest** readiness-scan test-pyramid snapshot and the immediately
+        previous succeeded/partial_failed/failed point when present (`limitPerRepo: 2`).
+        Layer **presence is count-based** (`fileCount > 0`); CI/dependency-only AF
+        `present` flags are ignored. Shape uses fixed advisory targets (base ~70% unit,
+        middle ~20% integration+contract+acceptance/BDD, top ~10% E2E) and returns
+        `insufficient_data` when total classified test files < 10. Also returns
+        maturity trend, coverage overlay, confidence, applicability, E2E-cross/hotspot
+        risk, and workspace-only `ciQuality` from the latest org dashboard snapshot.
+        Does not change Agentic Foundation `/readiness/test-pyramid*` responses.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
@@ -3879,7 +3882,9 @@ paths:
       operationId: listInsightsTestPyramidRepos
       description: >
         Page of repos with latest classified test-file counts, count-based presence,
-        presence maturity, and shape assessment. Use `gapsByLayer` on the summary
+        presence maturity, shape, trend vs the previous pyramid point, coverage
+        overlay, confidence/evidence, layer applicability, and risk signals
+        (`e2eCrossRepoCandidate`, `hotspotCount`). Use `gapsByLayer` on the summary
         endpoint (or filter this list via layerPresent) to answer “who lacks layer X?”.
         No v1 repo-detail Insights route — link repo names to AF readiness inventory.
       parameters:
@@ -21740,6 +21745,66 @@ components:
         contract: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
         e2e: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
 
+    InsightsTestPyramidMaturityDeltaDto:
+      type: string
+      enum: [up, down, unchanged, none]
+      description: >
+        Insights maturity rank change vs the immediately previous pyramid point
+        (missing 0, emerging 1, established 2, mature 3). `none` when the repo
+        has no previous succeeded/partial_failed/failed point.
+
+    InsightsTestPyramidConfidenceDto:
+      type: string
+      enum: [high, medium, low]
+
+    InsightsTestPyramidLayerConfidenceDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        integration: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        acceptance_bdd: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        contract: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        e2e: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+
+    InsightsTestPyramidCoverageRollupDto:
+      type: object
+      required: [reposWithCoverage, medianLinePercent]
+      properties:
+        reposWithCoverage:
+          type: integer
+          minimum: 0
+          description: Repos whose overlaid `lineCoverage` is non-null.
+        medianLinePercent:
+          type: number
+          nullable: true
+          minimum: 0
+          maximum: 100
+          description: >
+            Median of repo `linePercent` among repos that have coverage. Null when
+            `reposWithCoverage` is 0.
+
+    InsightsTestPyramidCiQualityDto:
+      type: object
+      nullable: true
+      required: [ciFailureRatePercent, bucketEnd]
+      properties:
+        ciFailureRatePercent:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: >
+            Latest org dashboard `quality.ciFailureRatePercent`, falling back to
+            `quality.ciBuildFailRatePercent`.
+        ciFlakinessPercent:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: Included only when `quality.ciFlakinessPercent` is a finite number.
+        bucketEnd:
+          type: string
+          description: Dashboard metrics bucket end for the org snapshot.
+
     InsightsTestPyramidSummaryDto:
       type: object
       required:
@@ -21752,6 +21817,14 @@ components:
         - layerPresence
         - maturityCounts
         - gapsByLayer
+        - newestScannedAt
+        - maturedRepoCount
+        - slippedRepoCount
+        - previousShape
+        - coverage
+        - e2eCrossRepoCandidateCount
+        - reposWithHotspots
+        - ciQuality
       properties:
         workspaceId: { type: string, format: uuid }
         generatedAt: { type: string, format: date-time }
@@ -21772,6 +21845,37 @@ components:
           $ref: "#/components/schemas/InsightsTestPyramidMaturityCountsDto"
         gapsByLayer:
           $ref: "#/components/schemas/InsightsTestPyramidGapsByLayerDto"
+        newestScannedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Latest per-repo `scannedAt`. Null when `reposWithPyramid` is 0.
+        maturedRepoCount:
+          type: integer
+          minimum: 0
+          description: Repos whose Insights maturity rank increased vs the previous point.
+        slippedRepoCount:
+          type: integer
+          minimum: 0
+          description: Repos whose Insights maturity rank decreased vs the previous point.
+        previousShape:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
+          nullable: true
+          description: >
+            Insights workspace shape from previous-point file totals for repos that
+            have a previous point. Null when no repo has a previous point.
+        coverage:
+          $ref: "#/components/schemas/InsightsTestPyramidCoverageRollupDto"
+        e2eCrossRepoCandidateCount:
+          type: integer
+          minimum: 0
+        reposWithHotspots:
+          type: integer
+          minimum: 0
+          description: Repos whose latest Code Insights snapshot has `hotspotCount` > 0.
+        ciQuality:
+          $ref: "#/components/schemas/InsightsTestPyramidCiQualityDto"
 
     InsightsTestPyramidRepoItemDto:
       type: object
@@ -21785,6 +21889,17 @@ components:
         - layerPresent
         - totalClassifiedFiles
         - shape
+        - previousMaturity
+        - maturityDelta
+        - previousShapeLabel
+        - lineCoverage
+        - lowestConfidence
+        - layerConfidence
+        - evidenceCount
+        - frameworks
+        - layerApplicable
+        - e2eCrossRepoCandidate
+        - hotspotCount
       properties:
         repoId: { type: string, format: uuid }
         repoName: { type: string }
@@ -21793,13 +21908,59 @@ components:
           $ref: "#/components/schemas/TestPyramidRunStatusDto"
         maturity:
           $ref: "#/components/schemas/InsightsTestPyramidMaturityDto"
+        previousMaturity:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidMaturityDto"
+          nullable: true
+        maturityDelta:
+          $ref: "#/components/schemas/InsightsTestPyramidMaturityDeltaDto"
+        previousShapeLabel:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidShapeLabelDto"
+          nullable: true
         layerFileCounts:
           $ref: "#/components/schemas/InsightsTestPyramidLayerCountsDto"
         layerPresent:
           $ref: "#/components/schemas/InsightsTestPyramidLayerPresentDto"
+        layerApplicable:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidLayerPresentDto"
+          description: Snapshot `layers.*.applicable` for each layer.
         totalClassifiedFiles: { type: integer, minimum: 0 }
         shape:
           $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
+        lineCoverage:
+          allOf:
+            - $ref: "#/components/schemas/TestPyramidLineCoverageDto"
+          description: >
+            Same overlay as AF progress — latest Sonar row first, else snapshot
+            `testPyramid.lineCoverage`. Null when both are missing. Not Code Insights
+            `coveragePct`.
+        lowestConfidence:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto"
+          description: >
+            Minimum confidence among layers with Insights presence (`fileCount > 0`);
+            if none present, minimum of applicable layers. Order low < medium < high.
+        layerConfidence:
+          $ref: "#/components/schemas/InsightsTestPyramidLayerConfidenceDto"
+        evidenceCount:
+          type: integer
+          minimum: 0
+          description: Sum of layer `evidence[]` lengths on the latest snapshot.
+        frameworks:
+          type: array
+          maxItems: 8
+          items: { type: string }
+          description: Unique framework names across layers, capped at 8.
+        e2eCrossRepoCandidate: { type: boolean }
+        hotspotCount:
+          type: integer
+          nullable: true
+          minimum: 0
+          description: >
+            Row count in `tai_workspace_repo_code_hotspots` for the repo's latest
+            Code Insights metrics snapshot. Null when the repo has no metrics snapshot.
 
     InsightsTestPyramidRepoListDto:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.127.0",
+  "version": "2.128.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "@stoplight/spectral-cli": "^6.16.3",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.5.1",
     "jsonpath-plus": "^10.3.0",
     "openapi-typescript": "^7.13.0",
     "typescript": "~6.0.3"

package/src/generated/openapi.ts

@@ -1403,7 +1403,7 @@ export interface paths {
         };
         /**
          * Test pyramid assessment — workspace summary
-         * @description Org-level Test pyramid assessment for `/insights/test-pyramid`. Aggregates each active repo's **latest** readiness-scan test-pyramid snapshot. Layer **presence is count-based** (`fileCount > 0`); CI/dependency-only AF `present` flags are ignored. Shape uses fixed advisory targets (base ~70% unit, middle ~20% integration+contract+acceptance/BDD, top ~10% E2E) and returns `insufficient_data` when total classified test files < 10. Does not change Agentic Foundation `/readiness/test-pyramid*` responses.
+         * @description Org-level Test pyramid assessment for `/insights/test-pyramid`. Aggregates each active repo's **latest** readiness-scan test-pyramid snapshot and the immediately previous succeeded/partial_failed/failed point when present (`limitPerRepo: 2`). Layer **presence is count-based** (`fileCount > 0`); CI/dependency-only AF `present` flags are ignored. Shape uses fixed advisory targets (base ~70% unit, middle ~20% integration+contract+acceptance/BDD, top ~10% E2E) and returns `insufficient_data` when total classified test files < 10. Also returns maturity trend, coverage overlay, confidence, applicability, E2E-cross/hotspot risk, and workspace-only `ciQuality` from the latest org dashboard snapshot. Does not change Agentic Foundation `/readiness/test-pyramid*` responses.
          */
         get: operations["getInsightsTestPyramidSummary"];
         put?: never;
@@ -1423,7 +1423,7 @@ export interface paths {
         };
         /**
          * Test pyramid assessment — per-repo list (paginated)
-         * @description Page of repos with latest classified test-file counts, count-based presence, presence maturity, and shape assessment. Use `gapsByLayer` on the summary endpoint (or filter this list via layerPresent) to answer “who lacks layer X?”. No v1 repo-detail Insights route — link repo names to AF readiness inventory.
+         * @description Page of repos with latest classified test-file counts, count-based presence, presence maturity, shape, trend vs the previous pyramid point, coverage overlay, confidence/evidence, layer applicability, and risk signals (`e2eCrossRepoCandidate`, `hotspotCount`). Use `gapsByLayer` on the summary endpoint (or filter this list via layerPresent) to answer “who lacks layer X?”. No v1 repo-detail Insights route — link repo names to AF readiness inventory.
          */
         get: operations["listInsightsTestPyramidRepos"];
         put?: never;
@@ -9659,6 +9659,34 @@ export interface components {
             contract: components["schemas"]["InsightsTestPyramidLayerPresenceDto"];
             e2e: components["schemas"]["InsightsTestPyramidLayerPresenceDto"];
         };
+        /**
+         * @description Insights maturity rank change vs the immediately previous pyramid point (missing 0, emerging 1, established 2, mature 3). `none` when the repo has no previous succeeded/partial_failed/failed point.
+         * @enum {string}
+         */
+        InsightsTestPyramidMaturityDeltaDto: "up" | "down" | "unchanged" | "none";
+        /** @enum {string} */
+        InsightsTestPyramidConfidenceDto: "high" | "medium" | "low";
+        InsightsTestPyramidLayerConfidenceDto: {
+            unit: components["schemas"]["InsightsTestPyramidConfidenceDto"];
+            integration: components["schemas"]["InsightsTestPyramidConfidenceDto"];
+            acceptance_bdd: components["schemas"]["InsightsTestPyramidConfidenceDto"];
+            contract: components["schemas"]["InsightsTestPyramidConfidenceDto"];
+            e2e: components["schemas"]["InsightsTestPyramidConfidenceDto"];
+        };
+        InsightsTestPyramidCoverageRollupDto: {
+            /** @description Repos whose overlaid `lineCoverage` is non-null. */
+            reposWithCoverage: number;
+            /** @description Median of repo `linePercent` among repos that have coverage. Null when `reposWithCoverage` is 0. */
+            medianLinePercent: number | null;
+        };
+        InsightsTestPyramidCiQualityDto: {
+            /** @description Latest org dashboard `quality.ciFailureRatePercent`, falling back to `quality.ciBuildFailRatePercent`. */
+            ciFailureRatePercent: number;
+            /** @description Included only when `quality.ciFlakinessPercent` is a finite number. */
+            ciFlakinessPercent?: number;
+            /** @description Dashboard metrics bucket end for the org snapshot. */
+            bucketEnd: string;
+        } | null;
         InsightsTestPyramidSummaryDto: {
             /** Format: uuid */
             workspaceId: string;
@@ -9673,6 +9701,22 @@ export interface components {
             layerPresence: components["schemas"]["InsightsTestPyramidLayerPresenceMapDto"];
             maturityCounts: components["schemas"]["InsightsTestPyramidMaturityCountsDto"];
             gapsByLayer: components["schemas"]["InsightsTestPyramidGapsByLayerDto"];
+            /**
+             * Format: date-time
+             * @description Latest per-repo `scannedAt`. Null when `reposWithPyramid` is 0.
+             */
+            newestScannedAt: string | null;
+            /** @description Repos whose Insights maturity rank increased vs the previous point. */
+            maturedRepoCount: number;
+            /** @description Repos whose Insights maturity rank decreased vs the previous point. */
+            slippedRepoCount: number;
+            /** @description Insights workspace shape from previous-point file totals for repos that have a previous point. Null when no repo has a previous point. */
+            previousShape: components["schemas"]["InsightsTestPyramidShapeDto"] | null;
+            coverage: components["schemas"]["InsightsTestPyramidCoverageRollupDto"];
+            e2eCrossRepoCandidateCount: number;
+            /** @description Repos whose latest Code Insights snapshot has `hotspotCount` > 0. */
+            reposWithHotspots: number;
+            ciQuality: components["schemas"]["InsightsTestPyramidCiQualityDto"];
         };
         InsightsTestPyramidRepoItemDto: {
             /** Format: uuid */
@@ -9682,10 +9726,27 @@ export interface components {
             scannedAt: string;
             currentRunStatus: components["schemas"]["TestPyramidRunStatusDto"];
             maturity: components["schemas"]["InsightsTestPyramidMaturityDto"];
+            previousMaturity: components["schemas"]["InsightsTestPyramidMaturityDto"] | null;
+            maturityDelta: components["schemas"]["InsightsTestPyramidMaturityDeltaDto"];
+            previousShapeLabel: components["schemas"]["InsightsTestPyramidShapeLabelDto"] | null;
             layerFileCounts: components["schemas"]["InsightsTestPyramidLayerCountsDto"];
             layerPresent: components["schemas"]["InsightsTestPyramidLayerPresentDto"];
+            /** @description Snapshot `layers.*.applicable` for each layer. */
+            layerApplicable: components["schemas"]["InsightsTestPyramidLayerPresentDto"];
             totalClassifiedFiles: number;
             shape: components["schemas"]["InsightsTestPyramidShapeDto"];
+            /** @description Same overlay as AF progress — latest Sonar row first, else snapshot `testPyramid.lineCoverage`. Null when both are missing. Not Code Insights `coveragePct`. */
+            lineCoverage: components["schemas"]["TestPyramidLineCoverageDto"];
+            /** @description Minimum confidence among layers with Insights presence (`fileCount > 0`); if none present, minimum of applicable layers. Order low < medium < high. */
+            lowestConfidence: components["schemas"]["InsightsTestPyramidConfidenceDto"];
+            layerConfidence: components["schemas"]["InsightsTestPyramidLayerConfidenceDto"];
+            /** @description Sum of layer `evidence[]` lengths on the latest snapshot. */
+            evidenceCount: number;
+            /** @description Unique framework names across layers, capped at 8. */
+            frameworks: string[];
+            e2eCrossRepoCandidate: boolean;
+            /** @description Row count in `tai_workspace_repo_code_hotspots` for the repo's latest Code Insights metrics snapshot. Null when the repo has no metrics snapshot. */
+            hotspotCount: number | null;
         };
         InsightsTestPyramidRepoListDto: {
             items: components["schemas"]["InsightsTestPyramidRepoItemDto"][];
@@ -10317,6 +10378,11 @@ export type InsightsTestPyramidGapRepoDto = components['schemas']['InsightsTestP
 export type InsightsTestPyramidGapsByLayerDto = components['schemas']['InsightsTestPyramidGapsByLayerDto'];
 export type InsightsTestPyramidMaturityCountsDto = components['schemas']['InsightsTestPyramidMaturityCountsDto'];
 export type InsightsTestPyramidLayerPresenceMapDto = components['schemas']['InsightsTestPyramidLayerPresenceMapDto'];
+export type InsightsTestPyramidMaturityDeltaDto = components['schemas']['InsightsTestPyramidMaturityDeltaDto'];
+export type InsightsTestPyramidConfidenceDto = components['schemas']['InsightsTestPyramidConfidenceDto'];
+export type InsightsTestPyramidLayerConfidenceDto = components['schemas']['InsightsTestPyramidLayerConfidenceDto'];
+export type InsightsTestPyramidCoverageRollupDto = components['schemas']['InsightsTestPyramidCoverageRollupDto'];
+export type InsightsTestPyramidCiQualityDto = components['schemas']['InsightsTestPyramidCiQualityDto'];
 export type InsightsTestPyramidSummaryDto = components['schemas']['InsightsTestPyramidSummaryDto'];
 export type InsightsTestPyramidRepoItemDto = components['schemas']['InsightsTestPyramidRepoItemDto'];
 export type InsightsTestPyramidRepoListDto = components['schemas']['InsightsTestPyramidRepoListDto'];