session-json-schema.yml

openapi: 3.0.3
info:
  title: Mutant Session Result Schema
  description: |
    Schema for the JSON files written to `.mutant/results/<session-id>.json`
    after each mutant run. These files are consumed by the `mutant session`
    CLI subcommands.

    Generated by reading the Transform pipeline definitions in:
    - lib/mutant/result/session.rb
    - lib/mutant/result.rb
    - lib/mutant/isolation.rb
    - lib/mutant/result/test.rb
    - lib/mutant/result/exception.rb
    - lib/mutant/result/process_status.rb
    - lib/mutant/log_capture.rb
  version: 1.1.0

paths: {}

components:
  schemas:
    Session:
      type: object
      required:
        - killtime
        - mutant_version
        - pid
        - ruby_version
        - runtime
        - session_id
        - subject_results
      properties:
        killtime:
          type: number
          format: double
          description: Total time spent running tests across all mutations (seconds).
        mutant_version:
          type: string
          description: Mutant version that produced this session.
        pid:
          type: integer
          description: Process ID of the mutant run.
        ruby_version:
          type: string
          description: Ruby version used during the run.
        runtime:
          type: number
          format: double
          description: Wall-clock runtime of the session (seconds).
        session_id:
          type: string
          format: uuid
          description: UUIDv7 session identifier. First 48 bits encode the millisecond timestamp.
        subject_results:
          type: array
          items:
            $ref: '#/components/schemas/SubjectResult'

    SubjectResult:
      type: object
      required:
        - amount_mutations
        - coverage_results
        - expression_syntax
        - identification
        - source
        - source_path
        - tests
      properties:
        amount_mutations:
          type: integer
          description: Total number of mutations in scope for this subject.
        coverage_results:
          type: array
          items:
            $ref: '#/components/schemas/CoverageResult'
        expression_syntax:
          type: string
          description: "Subject expression without source location (e.g. `Foo::Bar#baz`)."
        identification:
          type: string
          description: "Full subject identification including source location (e.g. `Foo::Bar#baz:lib/foo.rb:42`)."
        source:
          type: string
          description: Source code of the subject. Parsed back to AST on load.
        source_path:
          type: string
          description: Path to the source file.
        tests:
          type: array
          items:
            type: string
          description: Identification strings of the tests selected for this subject.

    CoverageResult:
      type: object
      required:
        - mutation_result
        - criteria_result
      properties:
        mutation_result:
          $ref: '#/components/schemas/MutationResult'
        criteria_result:
          $ref: '#/components/schemas/CoverageCriteria'

    MutationResult:
      type: object
      required:
        - isolation_result
        - mutation_diff
        - mutation_identification
        - mutation_source
        - mutation_type
        - runtime
      properties:
        isolation_result:
          $ref: '#/components/schemas/IsolationResult'
        mutation_diff:
          type: string
          nullable: true
          description: Unified diff between original and mutated source. Null when no diff could be computed.
        mutation_identification:
          type: string
          description: "Unique mutation identifier (e.g. `evil:Foo#bar:foo.rb:42:a1b2c`)."
        mutation_source:
          type: string
          description: Source code of the mutation. Parsed back to AST on load.
        mutation_type:
          type: string
          enum: [evil, neutral, noop]
          description: |
            Type of mutation:
            - `evil`: a code change that should be caught by tests.
            - `neutral`: original code re-inserted (tests should still pass).
            - `noop`: no code change at all (tests must pass).
        runtime:
          type: number
          format: double
          description: Time spent testing this mutation (seconds).

    IsolationResult:
      type: object
      required:
        - exception
        - log
        - process_status
        - timeout
        - value
      properties:
        exception:
          nullable: true
          description: Exception raised during isolation, or null.
          $ref: '#/components/schemas/Exception'
        log:
          description: |
            Combined stderr and stdout from the killfork process.
            New sessions use the LogCapture object form; legacy sessions
            written before v0.17 stored this as a plain string and are
            accepted on load for backwards compatibility.
          oneOf:
            - $ref: '#/components/schemas/LogCapture'
            - type: string
        process_status:
          nullable: true
          description: Exit status of the killfork process, or null.
          $ref: '#/components/schemas/ProcessStatus'
        timeout:
          type: number
          format: double
          nullable: true
          description: Timeout duration in seconds if the mutation timed out, or null.
        value:
          nullable: true
          description: Test result from the killfork, or null if execution failed.
          $ref: '#/components/schemas/TestResult'

    TestResult:
      type: object
      required:
        - job_index
        - passed
        - runtime
        - output
      properties:
        job_index:
          type: integer
          nullable: true
          description: Index of the parallel job that ran this test.
        passed:
          type: boolean
          description: Whether the test suite passed.
        runtime:
          type: number
          format: double
          description: Test execution time (seconds).
        output:
          description: |
            Test runner output.
            New sessions use the LogCapture object form; legacy sessions
            written before v0.17 stored this as a plain string and are
            accepted on load for backwards compatibility.
          oneOf:
            - $ref: '#/components/schemas/LogCapture'
            - type: string

    CoverageCriteria:
      type: object
      required:
        - process_abort
        - test_result
        - timeout
      properties:
        process_abort:
          type: boolean
          description: Whether the mutation was killed by a process abort.
        test_result:
          type: boolean
          description: Whether the mutation was killed by a test failure.
        timeout:
          type: boolean
          description: Whether the mutation was killed by a timeout.

    Exception:
      type: object
      required:
        - backtrace
        - message
        - original_class
      properties:
        backtrace:
          type: array
          items:
            type: string
          description: Exception backtrace lines.
        message:
          type: string
          description: Exception message.
        original_class:
          type: string
          description: Fully qualified class name of the original exception.

    ProcessStatus:
      type: object
      required:
        - exitstatus
      properties:
        exitstatus:
          type: integer
          description: Exit status code of the killfork process.

    LogCapture:
      type: object
      description: |
        Tagged representation of captured log output that preserves raw
        bytes. UTF-8 valid captures are stored inline; otherwise the
        bytes are base64-encoded (RFC 4648, no line breaks, `=` padding).
      required:
        - type
        - content
      properties:
        type:
          type: string
          enum: [string, binary]
          description: |
            - `string`: `content` is the raw UTF-8 text.
            - `binary`: `content` is base64-encoded raw bytes.
        content:
          type: string
          description: UTF-8 text when `type` is `string`; base64-encoded bytes when `type` is `binary`.