repowise-dev Areas API

openapi: 3.2.0
info:
  title: repowise Areas API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: areas
paths:
  /api/repos/{repo_id}/areas/tree:
    get:
      tags:
      - areas
      summary: Get Area Tree
      description: 'The root area''s rollup plus every directory up to *depth* levels below it.


        Complete over every scored file, not the map''s drawn field.'
      operationId: get_area_tree_api_repos__repo_id__areas_tree_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: root
        in: query
        required: false
        schema:
          type: string
          maxLength: 1024
          description: Area to unfold; the repo root by default.
          default: ''
          title: Root
        description: Area to unfold; the repo root by default.
      - name: depth
        in: query
        required: false
        schema:
          type: integer
          maximum: 4
          minimum: 1
          description: Levels below the root to include.
          default: 1
          title: Depth
        description: Levels below the root to include.
      - name: hold
        in: query
        required: false
        schema:
          type: string
          pattern: ^(none|map)$
          description: '`map` leaves out the origins the area map holds by default; `none` (default) reads every file.'
          default: none
          title: Hold
        description: '`map` leaves out the origins the area map holds by default; `none` (default) reads every file.'
      - name: include
        in: query
        required: false
        schema:
          type: string
          maxLength: 200
          description: 'With hold=map: comma-separated held origins to bring back, e.g. `test,build`.'
          default: ''
          title: Include
        description: 'With hold=map: comma-separated held origins to bring back, e.g. `test,build`.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AreaTreeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
  /api/repos/{repo_id}/areas/{area_path}:
    get:
      tags:
      - areas
      summary: Get Area Detail
      description: 'One area''s card: rollup, worst files, hotspots, owners, trend, findings, test reach.'
      operationId: get_area_detail_api_repos__repo_id__areas__area_path__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: area_path
        in: path
        required: true
        schema:
          type: string
          title: Area Path
      - name: hold
        in: query
        required: false
        schema:
          type: string
          pattern: ^(none|map)$
          description: '`map` leaves out the origins the area map holds by default; `none` (default) reads every file.'
          default: none
          title: Hold
        description: '`map` leaves out the origins the area map holds by default; `none` (default) reads every file.'
      - name: include
        in: query
        required: false
        schema:
          type: string
          maxLength: 200
          description: 'With hold=map: comma-separated held origins to bring back, e.g. `test,build`.'
          default: ''
          title: Include
        description: 'With hold=map: comma-separated held origins to bring back, e.g. `test,build`.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AreaDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
  /api/repos/{repo_id}/areas:
    get:
      tags:
      - areas
      summary: Get Area Detail
      description: 'One area''s card: rollup, worst files, hotspots, owners, trend, findings, test reach.'
      operationId: get_area_detail_api_repos__repo_id__areas_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: area_path
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Area Path
      - name: hold
        in: query
        required: false
        schema:
          type: string
          pattern: ^(none|map)$
          description: '`map` leaves out the origins the area map holds by default; `none` (default) reads every file.'
          default: none
          title: Hold
        description: '`map` leaves out the origins the area map holds by default; `none` (default) reads every file.'
      - name: include
        in: query
        required: false
        schema:
          type: string
          maxLength: 200
          description: 'With hold=map: comma-separated held origins to bring back, e.g. `test,build`.'
          default: ''
          title: Include
        description: 'With hold=map: comma-separated held origins to bring back, e.g. `test,build`.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AreaDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
components:
  schemas:
    AreaFileRow:
      properties:
        path:
          type: string
          title: Path
        score:
          type: number
          title: Score
        band:
          type: string
          enum:
          - at_risk
          - needs_work
          - fair
          - good
          - excellent
          title: Band
        nloc:
          type: integer
          title: Nloc
      type: object
      required:
      - path
      - score
      - band
      - nloc
      title: AreaFileRow
    AreaSeverityCounts:
      properties:
        critical:
          type: integer
          title: Critical
        high:
          type: integer
          title: High
        medium:
          type: integer
          title: Medium
        low:
          type: integer
          title: Low
      type: object
      required:
      - critical
      - high
      - medium
      - low
      title: AreaSeverityCounts
    AreaBandCounts:
      properties:
        at_risk:
          type: integer
          title: At Risk
        needs_work:
          type: integer
          title: Needs Work
        fair:
          type: integer
          title: Fair
        good:
          type: integer
          title: Good
        excellent:
          type: integer
          title: Excellent
      type: object
      required:
      - at_risk
      - needs_work
      - fair
      - good
      - excellent
      title: AreaBandCounts
    AreaFinding:
      properties:
        id:
          type: string
          title: Id
        file_path:
          type: string
          title: File Path
        biomarker_type:
          type: string
          title: Biomarker Type
        severity:
          type: string
          title: Severity
        function_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Function Name
        line_start:
          anyOf:
          - type: integer
          - type: 'null'
          title: Line Start
        health_impact:
          anyOf:
          - type: number
          - type: 'null'
          title: Health Impact
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
      type: object
      required:
      - id
      - file_path
      - biomarker_type
      - severity
      - function_name
      - line_start
      - health_impact
      - reason
      title: AreaFinding
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AreaTestReach:
      properties:
        files:
          type: integer
          title: Files
        with_test_file:
          type: integer
          title: With Test File
        measured_files:
          type: integer
          title: Measured Files
        line_coverage_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Line Coverage Pct
      type: object
      required:
      - files
      - with_test_file
      - measured_files
      - line_coverage_pct
      title: AreaTestReach
    AreaWorstFile:
      properties:
        path:
          anyOf:
          - type: string
          - type: 'null'
          title: Path
        score:
          type: number
          title: Score
      type: object
      required:
      - path
      - score
      title: AreaWorstFile
    AreaDeltaWindow:
      properties:
        target_days:
          type: integer
          title: Target Days
        latest_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest At
        baseline_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Baseline At
      type: object
      required:
      - target_days
      - latest_at
      - baseline_at
      title: AreaDeltaWindow
      description: The snapshots behind ``health_delta_30d``; the baseline may be nearer than 30 days.
    AreaOwners:
      properties:
        total:
          type: integer
          title: Total
        top:
          items:
            $ref: '#/components/schemas/AreaOwner'
          type: array
          title: Top
      type: object
      required:
      - total
      - top
      title: AreaOwners
    AreaDetailResponse:
      properties:
        area:
          $ref: '#/components/schemas/AreaNode'
        distribution:
          $ref: '#/components/schemas/AreaDistribution'
        worst_files:
          items:
            $ref: '#/components/schemas/AreaFileRow'
          type: array
          title: Worst Files
        hotspots:
          $ref: '#/components/schemas/AreaHotspots'
        owners:
          $ref: '#/components/schemas/AreaOwners'
        trend:
          items:
            $ref: '#/components/schemas/AreaTrendPoint'
          type: array
          title: Trend
        top_findings:
          items:
            $ref: '#/components/schemas/AreaFinding'
          type: array
          title: Top Findings
        test_reach:
          $ref: '#/components/schemas/AreaTestReach'
        delta_window:
          $ref: '#/components/schemas/AreaDeltaWindow'
        coupled_areas:
          items:
            $ref: '#/components/schemas/CouplingAreaSummary'
          type: array
          title: Coupled Areas
      type: object
      required:
      - area
      - distribution
      - worst_files
      - hotspots
      - owners
      - trend
      - top_findings
      - test_reach
      - delta_window
      title: AreaDetailResponse
    AreaBandShare:
      properties:
        files:
          type: integer
          title: Files
        nloc:
          type: integer
          title: Nloc
        pct:
          type: number
          title: Pct
      type: object
      required:
      - files
      - nloc
      - pct
      title: AreaBandShare
    AreaTreeResponse:
      properties:
        root:
          $ref: '#/components/schemas/AreaNode'
        depth:
          type: integer
          title: Depth
        nodes:
          items:
            $ref: '#/components/schemas/AreaNode'
          type: array
          title: Nodes
        delta_window:
          $ref: '#/components/schemas/AreaDeltaWindow'
        held:
          anyOf:
          - $ref: '#/components/schemas/AreaHeld'
          - type: 'null'
      type: object
      required:
      - root
      - depth
      - nodes
      - delta_window
      title: AreaTreeResponse
    CouplingAreaSummary:
      properties:
        pairs:
          type: integer
          title: Pairs
        unexplained_pairs:
          type: integer
          title: Unexplained Pairs
        unexplained_share:
          type: number
          title: Unexplained Share
        strength:
          type: number
          title: Strength
        co_changes:
          type: integer
          title: Co Changes
        last_co_change:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Co Change
        linked:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Linked
        hidden:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hidden
        path:
          type: string
          title: Path
      type: object
      required:
      - pairs
      - unexplained_pairs
      - unexplained_share
      - strength
      - co_changes
      - path
      title: CouplingAreaSummary
      description: 'One area''s coupling: every kept pair with a file in it.'
    AreaNode:
      properties:
        path:
          type: string
          title: Path
        name:
          type: string
          title: Name
        depth:
          type: integer
          title: Depth
        parent:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent
        has_children:
          type: boolean
          title: Has Children
        direct_file_count:
          type: integer
          title: Direct File Count
        file_count:
          type: integer
          title: File Count
        nloc:
          type: integer
          title: Nloc
        health:
          type: number
          title: Health
        band:
          type: string
          enum:
          - at_risk
          - needs_work
          - fair
          - good
          - excellent
          title: Band
        band_counts:
          $ref: '#/components/schemas/AreaBandCounts'
        worst_file:
          $ref: '#/components/schemas/AreaWorstFile'
        hotspot_count:
          type: integer
          title: Hotspot Count
        bus_factor_1_count:
          type: integer
          title: Bus Factor 1 Count
        primary_owner:
          anyOf:
          - $ref: '#/components/schemas/AreaOwner'
          - type: 'null'
        line_coverage_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Line Coverage Pct
        coverage_file_count:
          type: integer
          title: Coverage File Count
        findings:
          $ref: '#/components/schemas/AreaSeverityCounts'
        health_delta_30d:
          anyOf:
          - type: number
          - type: 'null'
          title: Health Delta 30D
      type: object
      required:
      - path
      - name
      - depth
      - parent
      - has_children
      - direct_file_count
      - file_count
      - nloc
      - health
      - band
      - band_counts
      - worst_file
      - hotspot_count
      - bus_factor_1_count
      - primary_owner
      - line_coverage_pct
      - coverage_file_count
      - findings
      - health_delta_30d
      title: AreaNode
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AreaOwner:
      properties:
        key:
          type: string
          title: Key
        name:
          type: string
          title: Name
        kind:
          type: string
          enum:
          - human
          - agent
          - bot
          title: Kind
        files:
          type: integer
          title: Files
        share:
          type: number
          title: Share
      type: object
      required:
      - key
      - name
      - kind
      - files
      - share
      title: AreaOwner
    AreaTrendPoint:
      properties:
        taken_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Taken At
        health:
          type: number
          title: Health
      type: object
      required:
      - taken_at
      - health
      title: AreaTrendPoint
    AreaDistribution:
      properties:
        total_files:
          type: integer
          title: Total Files
        total_nloc:
          type: integer
          title: Total Nloc
        bands:
          $ref: '#/components/schemas/AreaBandShares'
      type: object
      required:
      - total_files
      - total_nloc
      - bands
      title: AreaDistribution
    AreaHeld:
      properties:
        default:
          items:
            type: string
          type: array
          title: Default
        excluded:
          items:
            type: string
          type: array
          title: Excluded
        counts:
          additionalProperties:
            type: integer
          type: object
          title: Counts
      type: object
      required:
      - default
      - excluded
      - counts
      title: AreaHeld
      description: The origins the map holds out by default, and what this answer left out.
    AreaBandShares:
      properties:
        at_risk:
          $ref: '#/components/schemas/AreaBandShare'
        needs_work:
          $ref: '#/components/schemas/AreaBandShare'
        fair:
          $ref: '#/components/schemas/AreaBandShare'
        good:
          $ref: '#/components/schemas/AreaBandShare'
        excellent:
          $ref: '#/components/schemas/AreaBandShare'
      type: object
      required:
      - at_risk
      - needs_work
      - fair
      - good
      - excellent
      title: AreaBandShares
    AreaHotspots:
      properties:
        total:
          type: integer
          title: Total
        files:
          items:
            $ref: '#/components/schemas/AreaFileRow'
          type: array
          title: Files
      type: object
      required:
      - total
      - files
      title: AreaHotspots
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization