@thinkai/tai-api-contract 2.78.0 → 2.79.0-pr.976.2077d2a6

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.78.0
+  version: 2.79.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -80,6 +80,12 @@ tags:
       retrieval plus the workspace agent execution key (Claude or Cursor).
   - name: Platform
     description: Platform-wide banner surfaces (global outage/maintenance banner, issue #284).
+  - name: CodeInsights
+    description: >
+      Code Insights (`/insights/code`) — deterministic per-repo code-quality metrics
+      (LOC, cyclomatic complexity, duplication), hotspots, and playbook-threshold
+      findings collected during readiness scans. Every metric carries
+      `measured | derived | estimated | unavailable` provenance.
 
 paths:
   /admin/users/{userId}:
@@ -3280,6 +3286,113 @@ paths:
         "404":
           description: Workspace does not exist or malformed workspaceId
 
+  /workspaces/{workspaceId}/insights/code/summary:
+    get:
+      tags: [CodeInsights]
+      summary: Code Insights — org summary
+      operationId: getCodeInsightsSummary
+      description: >
+        Org-level Code Insights summary for `/insights/code`. Aggregates each active
+        repo's **latest** deterministic metrics row (unweighted medians — mega-repos
+        are not down-weighted, by design), findings counts by severity across latest
+        scans, the org top-10 complexity hotspots, and org-level SonarQube
+        coverage/tech-debt-ratio when a SonarQube source is connected (per-repo Sonar
+        mapping is v2). Reads stored scan outputs only — never recomputes on request.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Code Insights org summary payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeInsightsSummaryDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/code/repos:
+    get:
+      tags: [CodeInsights]
+      summary: Code Insights — per-repo metrics list (paginated)
+      operationId: listCodeInsightsRepos
+      description: >
+        Page of active (not user-archived) repos with their latest code-quality
+        metrics, threshold badges, and finding counts. Repos without a completed
+        metrics scan appear with `metricsStatus` absent/`null` ("pending first scan").
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/CodeInsightsRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/CodeInsightsRepoSearch"
+      responses:
+        "200":
+          description: Paginated repo code-quality metrics
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeInsightsRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/code/repos/{repoId}:
+    get:
+      tags: [CodeInsights]
+      summary: Code Insights — repo detail (metrics, hotspots, findings)
+      operationId: getCodeInsightsRepoDetail
+      description: >
+        Single-repo Code Insights detail: latest metrics row with per-metric
+        provenance, current hotspot snapshot (top-N worst files), and the findings
+        computed by the latest scan. `metrics` is `null` when the repo is pending
+        its first metrics scan.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: repoId
+          in: path
+          required: true
+          description: Internal repo UUID (`tai_workspace_repos.id`).
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: Repo code-quality detail payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeInsightsRepoDetailDto"
+        "400":
+          description: Malformed repoId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repo does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/members:
     get:
       tags: [Workspace]
@@ -8650,6 +8763,22 @@ components:
         type: string
         enum: [repoName, overallScore, lastAnalyzed, language]
         default: overallScore
+    CodeInsightsRepoSort:
+      name: sort
+      in: query
+      required: false
+      description: Allowlisted Code Insights repo sort field.
+      schema:
+        type: string
+        enum: [repoName, locTotal, ccAvg, dupPct, lastMeasuredAt]
+        default: repoName
+    CodeInsightsRepoSearch:
+      name: search
+      in: query
+      required: false
+      description: Case-insensitive substring filter on repo name / provider slug.
+      schema:
+        type: string
     ReadinessRepoSearch:
       name: search
       in: query
@@ -17114,3 +17243,326 @@ components:
         snippets:
           type: array
           items: { type: string }
+
+    CodeInsightsMetricProvenance:
+      type: string
+      enum: [measured, derived, estimated, unavailable]
+      description: >
+        Where a metric value came from: `measured` (direct tool output),
+        `derived` (computed from measured inputs, e.g. the maintainability band),
+        `estimated` (heuristic proxy, e.g. test-to-source ratio), or `unavailable`
+        (tool missing/failed, or the language is unsupported). Keyed per metric in
+        `CodeInsightsMetricsDto.provenance`.
+
+    CodeInsightsMaintainabilityBand:
+      type: string
+      enum: [green, yellow, red]
+      description: CC/LOC-derived maintainability band (documented heuristic, not Halstead MI).
+
+    CodeInsightsMetricsStatus:
+      type: string
+      enum: [ok, failed, skipped]
+      description: >
+        Outcome of the repo's latest metrics scan: `ok` (at least one tool measured),
+        `failed` (every tool failed — metric fields are null with `unavailable`
+        provenance), `skipped` (stage ran but found no measurable source).
+
+    CodeInsightsFindingSeverity:
+      type: string
+      enum: [critical, high, medium, low]
+
+    CodeInsightsFindingCategory:
+      type: string
+      enum: [duplication, complexity, proliferation, coverage]
+      description: >
+        v1 deterministic categories. The v2 LLM pass adds `anemic_domain`,
+        `context_leak`, `tx_boundary`, `error_handling` (contract bump).
+
+    CodeInsightsFindingSource:
+      type: string
+      enum: [deterministic]
+      description: v1 ships deterministic findings only; the v2 LLM pass adds `llm`.
+
+    CodeInsightsMetricsDto:
+      type: object
+      required: [runId, measuredAt, metricsStatus, structureCounts, provenance, toolVersions]
+      properties:
+        runId:
+          type: string
+          description: Readiness run that produced this metrics row.
+        measuredAt:
+          type: string
+          format: date-time
+        metricsStatus:
+          $ref: "#/components/schemas/CodeInsightsMetricsStatus"
+        locTotal:
+          type: integer
+          nullable: true
+        filesTotal:
+          type: integer
+          nullable: true
+        ccAvg:
+          type: number
+          nullable: true
+          description: Mean cyclomatic complexity across analyzed functions.
+        ccMax:
+          type: integer
+          nullable: true
+        ccP90:
+          type: number
+          nullable: true
+          description: 90th percentile function cyclomatic complexity (nearest-rank).
+        dupPct:
+          type: number
+          nullable: true
+          description: Duplicated lines as a percentage of analyzed lines (0–100).
+        maintainabilityBand:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsMaintainabilityBand"
+          nullable: true
+        coveragePct:
+          type: number
+          nullable: true
+          description: Reserved for per-repo SonarQube enrichment (v2); null in v1.
+        debtRatio:
+          type: number
+          nullable: true
+          description: Reserved for per-repo SonarQube enrichment (v2); null in v1.
+        structureCounts:
+          type: object
+          additionalProperties: true
+          description: >
+            Heuristic structure counters: dto/mapper/config/exception file + LOC
+            counts, test/source LOC split, per-language LOC, functions_analyzed,
+            test_ratio, dto_mapper_share_pct.
+        provenance:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/CodeInsightsMetricProvenance"
+          description: Per-metric provenance keyed by DTO field name (e.g. `ccAvg`, `dupPct`, `testRatio`).
+        toolVersions:
+          type: object
+          additionalProperties: { type: string }
+          description: Tool name → version string for the tools that produced this row.
+
+    CodeInsightsHotspotDto:
+      type: object
+      required: [filePath, flags]
+      properties:
+        filePath:
+          type: string
+          description: Repo-relative file path.
+        loc:
+          type: integer
+          nullable: true
+        ccMax:
+          type: integer
+          nullable: true
+          description: Max function cyclomatic complexity in the file.
+        paramsMax:
+          type: integer
+          nullable: true
+        nestingMax:
+          type: integer
+          nullable: true
+          description: Max nested control structures (null when the analyzer does not report nesting).
+        dupPct:
+          type: number
+          nullable: true
+          description: Estimated per-file duplicated line share (0–100).
+        flags:
+          type: array
+          items: { type: string }
+          description: Subset of `god_file`, `high_cc`, `long_params`, `deep_nesting`.
+
+    CodeInsightsFindingDto:
+      type: object
+      required: [id, severity, category, title, explanation, evidence, source, runId, createdAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+        severity:
+          $ref: "#/components/schemas/CodeInsightsFindingSeverity"
+        category:
+          $ref: "#/components/schemas/CodeInsightsFindingCategory"
+        title:
+          type: string
+        explanation:
+          type: string
+        evidence:
+          type: object
+          additionalProperties: true
+          description: Measured values and thresholds backing the finding.
+        remediation:
+          type: string
+          nullable: true
+        source:
+          $ref: "#/components/schemas/CodeInsightsFindingSource"
+        runId:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+
+    CodeInsightsFindingsBySeverityDto:
+      type: object
+      required: [critical, high, medium, low]
+      properties:
+        critical: { type: integer, minimum: 0 }
+        high: { type: integer, minimum: 0 }
+        medium: { type: integer, minimum: 0 }
+        low: { type: integer, minimum: 0 }
+
+    CodeInsightsRepoListItemDto:
+      type: object
+      required: [repoId, repoName, language, providerSlug, webUrl, badges, findingsBySeverity, provenance]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+        language:
+          type: string
+        providerSlug:
+          type: string
+          description: "owner/repo on the VCS provider."
+        webUrl:
+          type: string
+        lastMeasuredAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Null when the repo is pending its first metrics scan.
+        metricsStatus:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsMetricsStatus"
+          nullable: true
+        locTotal:
+          type: integer
+          nullable: true
+        ccAvg:
+          type: number
+          nullable: true
+        ccMax:
+          type: integer
+          nullable: true
+        dupPct:
+          type: number
+          nullable: true
+        maintainabilityBand:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsMaintainabilityBand"
+          nullable: true
+        badges:
+          type: array
+          items: { type: string }
+          description: >
+            Active threshold badges from the latest scan: subset of `god_files`,
+            `high_complexity`, `duplication`, `proliferation`, `low_test_ratio`.
+        findingsBySeverity:
+          $ref: "#/components/schemas/CodeInsightsFindingsBySeverityDto"
+        provenance:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/CodeInsightsMetricProvenance"
+
+    CodeInsightsRepoListDto:
+      allOf:
+        - $ref: "#/components/schemas/PageMetaDto"
+        - type: object
+          required: [items]
+          properties:
+            items:
+              type: array
+              items:
+                $ref: "#/components/schemas/CodeInsightsRepoListItemDto"
+
+    CodeInsightsRepoDetailDto:
+      type: object
+      required: [repoId, repoName, language, providerSlug, webUrl, metrics, hotspots, findings]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+        language:
+          type: string
+        providerSlug:
+          type: string
+        webUrl:
+          type: string
+        metrics:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsMetricsDto"
+          nullable: true
+          description: Null when the repo is pending its first metrics scan.
+        hotspots:
+          type: array
+          items:
+            $ref: "#/components/schemas/CodeInsightsHotspotDto"
+        findings:
+          type: array
+          items:
+            $ref: "#/components/schemas/CodeInsightsFindingDto"
+          description: Findings from the latest scan only (history is retention-bounded).
+
+    CodeInsightsOrgHotspotDto:
+      allOf:
+        - $ref: "#/components/schemas/CodeInsightsHotspotDto"
+        - type: object
+          required: [repoId, repoName]
+          properties:
+            repoId:
+              type: string
+              format: uuid
+            repoName:
+              type: string
+
+    CodeInsightsSonarDto:
+      type: object
+      required: [connected]
+      properties:
+        connected:
+          type: boolean
+          description: Whether a SonarQube source is configured for the workspace.
+        coveragePct:
+          type: number
+          nullable: true
+          description: Org-level SonarQube coverage from the latest precomputed quality snapshot.
+        techDebtRatioPct:
+          type: number
+          nullable: true
+          description: Org-level SonarQube SQALE technical debt ratio from the latest quality snapshot.
+
+    CodeInsightsSummaryDto:
+      type: object
+      required: [reposMeasured, reposPending, findingsBySeverity, topHotspots, sonar]
+      properties:
+        reposMeasured:
+          type: integer
+          minimum: 0
+          description: Active repos whose latest metrics scan completed (`ok`).
+        reposPending:
+          type: integer
+          minimum: 0
+          description: Active repos without a completed metrics scan (never scanned, or only failed/skipped).
+        ccAvgMedian:
+          type: number
+          nullable: true
+          description: Unweighted median of latest `ccAvg` across measured repos (null when none measured).
+        dupPctMedian:
+          type: number
+          nullable: true
+          description: Unweighted median of latest `dupPct` across measured repos (null when none measured).
+        findingsBySeverity:
+          $ref: "#/components/schemas/CodeInsightsFindingsBySeverityDto"
+        topHotspots:
+          type: array
+          items:
+            $ref: "#/components/schemas/CodeInsightsOrgHotspotDto"
+          description: Org top-10 complexity hotspots by `ccMax` (current per-repo snapshots).
+        sonar:
+          $ref: "#/components/schemas/CodeInsightsSonarDto"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.78.0",
+  "version": "2.79.0-pr.976.2077d2a6",
   "private": false,
   "type": "module",
   "main": "dist/index.js",