repowise-dev Doc Drift API

openapi: 3.2.0
info:
  title: repowise Doc Drift API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: doc-drift
paths:
  /api/repos/{repo_id}/doc-drift:
    get:
      tags:
      - doc-drift
      summary: List Doc Drift
      description: 'Documents whose assertions the repository no longer satisfies.


        The summary describes the same filters as the list, so the two cannot

        disagree, and counts before ``limit`` so a capped page is never mistaken

        for the repository.'
      operationId: list_doc_drift_api_repos__repo_id__doc_drift_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: min_confidence
        in: query
        required: false
        schema:
          type: number
          maximum: 1.0
          minimum: 0.0
          default: 0.4
          title: Min Confidence
      - name: kind
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by reference class
          title: Kind
        description: Filter by reference class
      - name: document
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Only this document's findings
          title: Document
        description: Only this document's findings
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 100
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocDriftResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/doc-drift/references:
    get:
      tags:
      - doc-drift
      summary: Doc Drift References
      description: 'Which documents name *target*, and which of them carry drift.


        A reference says a document names a file the repository still has. It does

        not say the document describes it, and ``documents_with_drift`` is a fact

        about the document rather than about *target*: a drifted reference resolves

        to nothing, so the store cannot express "this description of your file is

        wrong" and must not be read as doing so.'
      operationId: doc_drift_references_api_repos__repo_id__doc_drift_references_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: target
        in: query
        required: true
        schema:
          type: string
          description: Repo-relative path of the file
          title: Target
        description: Repo-relative path of the file
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocDriftReferencesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
components:
  schemas:
    DocDriftResponse:
      properties:
        findings:
          items:
            $ref: '#/components/schemas/DocDriftFindingResponse'
          type: array
          title: Findings
        findings_emitted:
          type: integer
          title: Findings Emitted
        summary:
          anyOf:
          - $ref: '#/components/schemas/DocDriftSummaryResponse'
          - type: 'null'
        unavailable:
          anyOf:
          - type: string
            enum:
            - not_computed
            - index_predates_doc_drift
            - drift_read_failed
          - type: 'null'
          title: Unavailable
      type: object
      required:
      - findings
      - findings_emitted
      - summary
      title: DocDriftResponse
      description: Findings for a repository, with the rollup that makes them legible.
    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
    DocDriftReferencesResponse:
      properties:
        target_path:
          type: string
          title: Target Path
        references:
          items:
            $ref: '#/components/schemas/DocDriftReferenceResponse'
          type: array
          title: References
        references_emitted:
          type: integer
          title: References Emitted
        references_total:
          type: integer
          title: References Total
        documents:
          type: integer
          title: Documents
        documents_with_drift:
          items:
            $ref: '#/components/schemas/DocDriftDocumentDriftResponse'
          type: array
          title: Documents With Drift
        references_basis:
          type: string
          title: References Basis
        unavailable:
          anyOf:
          - type: string
            enum:
            - not_computed
            - index_predates_doc_drift
            - drift_read_failed
          - type: 'null'
          title: Unavailable
      type: object
      required:
      - target_path
      - references
      - references_emitted
      - references_total
      - documents
      - documents_with_drift
      - references_basis
      title: DocDriftReferencesResponse
      description: 'Which documents name one file: the reverse view, over HTTP.'
    DocDriftDocumentDriftResponse:
      properties:
        document:
          type: string
          title: Document
        findings:
          type: integer
          title: Findings
      type: object
      required:
      - document
      - findings
      title: DocDriftDocumentDriftResponse
      description: 'A naming document that carries drift somewhere in it.


        ``findings`` counts the whole document, not assertions about the file that

        was asked about. A drifted reference resolves to nothing, so no row here

        can say a document''s description of that file is wrong.'
    DocDriftSummaryResponse:
      properties:
        findings_total:
          type: integer
          title: Findings Total
        documents:
          type: integer
          title: Documents
        confidence:
          additionalProperties:
            type: integer
          type: object
          title: Confidence
        by_kind:
          additionalProperties:
            type: integer
          type: object
          title: By Kind
        findings_basis:
          type: string
          title: Findings Basis
        new_since_last_update:
          anyOf:
          - type: integer
          - type: 'null'
          title: New Since Last Update
      type: object
      required:
      - findings_total
      - documents
      - confidence
      - by_kind
      - findings_basis
      title: DocDriftSummaryResponse
      description: 'The rollup above the list, computed server-side over the same rows.


        ``findings_total`` counts every finding matching the query, including any

        the display cap left out, so a client cannot recompute a page as if it were

        the repository.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DocDriftReferenceResponse:
      properties:
        document:
          type: string
          title: Document
        line:
          type: integer
          title: Line
        kind:
          type: string
          title: Kind
        section:
          type: string
          title: Section
          default: ''
      type: object
      required:
      - document
      - line
      - kind
      title: DocDriftReferenceResponse
      description: 'A document that names a file the repository still has.


        Deliberately weaker than a finding: it does not claim the document

        describes the file, or that its prose is current.'
    DocDriftFindingResponse:
      properties:
        id:
          type: string
          title: Id
        file_path:
          type: string
          title: File Path
        line_number:
          type: integer
          title: Line Number
        kind:
          type: string
          title: Kind
        target:
          type: string
          title: Target
        confidence:
          type: number
          title: Confidence
        origin:
          type: string
          title: Origin
        reason:
          type: string
          title: Reason
        raw:
          type: string
          title: Raw
        context:
          type: string
          title: Context
        evidence:
          items:
            type: string
          type: array
          title: Evidence
        fingerprint:
          type: string
          title: Fingerprint
        suggestion:
          anyOf:
          - type: string
          - type: 'null'
          title: Suggestion
        suggestion_basis:
          anyOf:
          - type: string
          - type: 'null'
          title: Suggestion Basis
        first_seen_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Seen At
        is_new:
          type: boolean
          title: Is New
          default: false
      type: object
      required:
      - id
      - file_path
      - line_number
      - kind
      - target
      - confidence
      - origin
      - reason
      - raw
      - context
      - evidence
      - fingerprint
      title: DocDriftFindingResponse
      description: 'One assertion a document makes that the repository no longer satisfies.


        ``file_path`` is the *document* to edit, never the target it names. A

        reader who reads it as the broken file has been told the opposite of the

        truth, which is why the field keeps the name every other drift surface

        gives it.'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization