schema.ts

import type { BugbotFramedAssignment } from '../../../../../domain/bugbot/framed_review';
/**
 * JSON schemas for findings-agent responses. Used with the findings query so the agent returns
 * structured JSON we can parse.
 */

import { MAX_FINDING_ID_LENGTH } from '../../../../policies/bugbot_finding_marker_policy';
import { AGENT_OUTPUT_LOCALE_SCHEMA_PROPERTY } from '../../../../policies/agent_output_locale_policy';

/** Detection returns findings and explicit lifecycle changes for prior finding IDs. */
export const BUGBOT_RESPONSE_SCHEMA = {
    type: 'object',
    properties: {
        outputLocale: AGENT_OUTPUT_LOCALE_SCHEMA_PROPERTY,
        findings: {
            type: 'array',
            description: 'Confirmed actionable defects only. Omit disproved candidates and explanations that the code or link is correct, including info. Return [] when no defect is demonstrated.',
            maxItems: 200,
            items: {
                type: 'object',
                properties: {
                    id: {
                        type: 'string',
                        minLength: 1,
                        maxLength: MAX_FINDING_ID_LENGTH,
                        description: 'Stable unique id for this finding (e.g. file:line:summary)',
                    },
                    title: { type: 'string', minLength: 1, maxLength: 500, description: 'Short title of the problem' },
                    description: { type: 'string', minLength: 1, maxLength: 8000, description: 'Clear explanation of the issue' },
                    file: { type: ['string', 'null'], maxLength: 500, description: 'Repository-relative path, or null when no precise file applies' },
                    line: { type: ['integer', 'null'], minimum: 1, description: 'Line number, or null when no precise line applies' },
                    endLine: { type: ['integer', 'null'], minimum: 1, description: 'Inclusive final line, or null when no range applies' },
                    severity: { type: ['string', 'null'], enum: ['high', 'medium', 'low', 'info', null], description: 'Severity, or null only when it cannot be assigned' },
                    confidence: { type: ['number', 'null'], minimum: 0, maximum: 1, description: 'Confidence from 0 to 1, or null when unavailable' },
                    category: { type: ['string', 'null'], enum: ['correctness', 'security', 'performance', 'reliability', 'maintainability', null], description: 'Primary defect category, or null when unavailable' },
                    evidence: { type: ['string', 'null'], maxLength: 8000, description: 'Concrete evidence, or null when unavailable' },
                    suggestion: { type: ['string', 'null'], maxLength: 8000, description: 'Suggested fix, or null when no safe suggestion applies' },
                    symbol: { type: ['string', 'null'], maxLength: 500, description: 'Nearest stable symbol, or null when unavailable' },
                    codeSnippet: { type: ['string', 'null'], maxLength: 2000, description: 'Minimal exact code fragment, or null when unavailable' },
                    suggestedCode: { type: ['string', 'null'], maxLength: 4000, description: 'Exact replacement text, or null for non-local or uncertain fixes' },
                },
                required: [
                    'id', 'title', 'description', 'file', 'line', 'endLine', 'severity',
                    'confidence', 'category', 'evidence', 'suggestion', 'symbol', 'codeSnippet',
                    'suggestedCode',
                ],
                additionalProperties: false,
            },
        },
        resolved_findings: {
            type: 'array',
            maxItems: 500,
            items: {
                type: 'object',
                properties: {
                    id: {
                        type: 'string',
                        minLength: 1,
                        maxLength: MAX_FINDING_ID_LENGTH,
                        description: 'Exact id of a retained previously reported finding',
                    },
                    resolution: {
                        type: 'string',
                        enum: ['fixed', 'obsolete'],
                        description: 'Whether the defect was fixed or its original situation no longer applies',
                    },
                },
                required: ['id', 'resolution'],
                additionalProperties: false,
            },
            description: 'Retained previous findings that are now fixed or obsolete; use an empty array when none are resolved.',
        },
    },
    required: ['outputLocale', 'findings', 'resolved_findings'],
    additionalProperties: false,
} as const;

/** Partition reviews must attest the exact immutable assignment they completed. */
export const BUGBOT_PARTITION_RESPONSE_SCHEMA = {
    ...BUGBOT_RESPONSE_SCHEMA,
    properties: {
        ...BUGBOT_RESPONSE_SCHEMA.properties,
        partition_id: {
            type: 'string',
            minLength: 1,
            maxLength: 128,
            description: 'Exact trusted partition id supplied by the review prompt.',
        },
        reviewed_head_sha: {
            type: 'string',
            pattern: '^[0-9a-fA-F]{7,64}$',
            description: 'Exact canonical pull-request head SHA supplied by the review prompt.',
        },
    },
    required: [...BUGBOT_RESPONSE_SCHEMA.required, 'partition_id', 'reviewed_head_sha'],
} as const;

/** Bind structured output to the trusted assignment, not examples in the diff. */
export function buildBugbotPartitionResponseSchema(
    expected: Readonly<{ partitionId: string; headSha: string; framed?: BugbotFramedAssignment }>,
): Readonly<Record<string, unknown>> {
    const framed = expected.framed;
    return {
        ...BUGBOT_PARTITION_RESPONSE_SCHEMA,
        required: [...BUGBOT_PARTITION_RESPONSE_SCHEMA.required, ...(framed ? ['reviewed_base_sha', 'review_manifest_digest', 'review_frame_id', 'review_coverage_digest', 'reviewed_fragment_ids'] : [])],
        properties: {
            ...BUGBOT_PARTITION_RESPONSE_SCHEMA.properties,
            ...(framed ? {
                reviewed_base_sha: { type: 'string', enum: [framed.baseSha] },
                review_manifest_digest: { type: 'string', enum: [framed.manifestDigest] },
                review_frame_id: { type: 'string', enum: [framed.frameId] },
                review_coverage_digest: { type: 'string', enum: [framed.coverageDigest] },
                reviewed_fragment_ids: { type: 'array', items: { type: 'string', enum: [...framed.fragmentIds] }, minItems: framed.fragmentIds.length, maxItems: framed.fragmentIds.length },
            } : {}),
            partition_id: {
                ...BUGBOT_PARTITION_RESPONSE_SCHEMA.properties.partition_id,
                enum: [expected.partitionId],
            },
            reviewed_head_sha: {
                ...BUGBOT_PARTITION_RESPONSE_SCHEMA.properties.reviewed_head_sha,
                enum: [expected.headSha],
            },
        },
    };
}

/**
 * Findings-agent response schema for comment intent.
 * Given the user comment and the list of unresolved findings, the agent decides whether
 * the user is asking to fix findings, apply a general change, or run a read-only review.
 */
export const BUGBOT_FIX_INTENT_RESPONSE_SCHEMA = {
    type: 'object',
    properties: {
        is_fix_request: {
            type: 'boolean',
            description:
                'True if the user comment is clearly requesting to fix one or more of the reported findings (e.g. "fix it", "arregla", "fix this vulnerability", "fix all"). False for questions, unrelated messages, or ambiguous text.',
        },
        target_finding_ids: {
            type: 'array',
            maxItems: 500,
            items: { type: 'string', minLength: 1, maxLength: MAX_FINDING_ID_LENGTH },
            description:
                'When is_fix_request is true: the exact finding ids from the list we provided that the user wants fixed. Use the exact id strings. For "fix all" or "fix everything" include all listed ids. When is_fix_request is false, return an empty array.',
        },
        is_do_request: {
            type: 'boolean',
            description:
                'True if the user is asking to perform some change or task in the repository (e.g. "add a test for X", "refactor this", "implement feature Y"). False for pure questions or when the only intent is to fix the reported findings (use is_fix_request for that).',
        },
        is_review_request: {
            type: 'boolean',
            description:
                'True if the user is asking for a read-only analysis or review of the current issue, branch, or pull request (e.g. "analyze the changes for security issues", "review this PR for bugs"). False for pure questions or file-changing requests.',
        },
    },
    required: ['is_fix_request', 'target_finding_ids', 'is_do_request', 'is_review_request'],
    additionalProperties: false,
} as const;