@atmin.ai/review 0.1.0-alpha.2

package/dist/contracts.d.ts

@@ -0,0 +1,625 @@
+export declare class ReviewInputError extends Error {
+}
+export declare const PRIORITIES: readonly ["P0", "P1", "P2", "P3", "P4"];
+export type Priority = typeof PRIORITIES[number];
+export interface Policy {
+    schemaVersion: 1;
+    rubricVersion: '1';
+    includeOptional: boolean;
+    requiredChecks: string[];
+}
+export interface ChangedFile {
+    path: string;
+    change: 'added' | 'modified' | 'deleted';
+    kind: 'text' | 'binary' | 'symlink' | 'submodule';
+}
+export interface Packet {
+    schemaVersion: 1;
+    repository: string;
+    pr: number;
+    baseRef: string;
+    headSha: string;
+    baseSha: string;
+    mergeBaseSha: string;
+    createdAt: string;
+    policy: Policy;
+    policyHash: string;
+    diffHash: string;
+    changedFiles: ChangedFile[];
+}
+export interface Anchor {
+    path: string;
+    side: 'head' | 'base';
+    line: number;
+}
+export type EvidenceAnchor = Omit<Anchor, 'line'> & {
+    line: number | null;
+};
+interface EvidenceBase {
+    id: string;
+    summary: string;
+    anchors: EvidenceAnchor[];
+}
+export type Evidence = EvidenceBase & ({
+    kind: 'source-reasoning' | 'reproduction' | 'ci';
+    provenance: 'declared';
+} | {
+    kind: 'source-read';
+    provenance: 'controller-captured';
+    capture: {
+        revision: string;
+        startLine: number;
+        endLine: number;
+        totalLines: number;
+        contentHash: string;
+    };
+});
+export interface Finding {
+    id: string;
+    priority: Priority;
+    kind: 'defect' | 'improvement';
+    category: 'correctness' | 'security' | 'data-integrity' | 'reliability' | 'validation' | 'simplicity';
+    title: string;
+    trigger: string;
+    consequence: string;
+    priorityReason: string;
+    counterEvidence: string;
+    suggestion: string;
+    anchor: Anchor;
+    evidenceIds: string[];
+}
+export interface Result {
+    schemaVersion: 1;
+    headSha: string;
+    baseSha: string;
+    policyHash: string;
+    status: 'not-started' | 'partial' | 'completed';
+    reviewer: {
+        name: string;
+        model: string;
+        context: 'independent' | 'author' | 'unknown';
+    };
+    summary: string;
+    coverage: {
+        path: string;
+        status: 'reviewed' | 'unreviewed';
+        evidenceIds: string[];
+    }[];
+    validation: {
+        name: string;
+        status: 'pass' | 'fail' | 'not-run' | 'not-applicable';
+        reason: string;
+        evidenceIds: string[];
+    }[];
+    evidence: Evidence[];
+    findings: Finding[];
+    limitations: string[];
+}
+export declare const text: {
+    type: string;
+    minLength: number;
+    maxLength: number;
+    pattern: string;
+};
+export declare const policySchema: {
+    type: string;
+    properties: {
+        schemaVersion: {
+            const: number;
+        };
+        rubricVersion: {
+            const: string;
+        };
+        includeOptional: {
+            type: string;
+        };
+        requiredChecks: {
+            uniqueItems: boolean;
+            type: string;
+            items: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                pattern: string;
+            };
+            minItems: number;
+            maxItems: number;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const packetSchema: {
+    type: string;
+    properties: {
+        schemaVersion: {
+            const: number;
+        };
+        repository: {
+            type: string;
+            pattern: string;
+        };
+        pr: {
+            type: string;
+            minimum: number;
+            maximum: number;
+        };
+        baseRef: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+            pattern: string;
+        };
+        headSha: {
+            type: string;
+            pattern: string;
+        };
+        baseSha: {
+            type: string;
+            pattern: string;
+        };
+        mergeBaseSha: {
+            type: string;
+            pattern: string;
+        };
+        createdAt: {
+            type: string;
+            pattern: string;
+        };
+        policy: {
+            type: string;
+            properties: {
+                schemaVersion: {
+                    const: number;
+                };
+                rubricVersion: {
+                    const: string;
+                };
+                includeOptional: {
+                    type: string;
+                };
+                requiredChecks: {
+                    uniqueItems: boolean;
+                    type: string;
+                    items: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    minItems: number;
+                    maxItems: number;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+        policyHash: {
+            type: string;
+            pattern: string;
+        };
+        diffHash: {
+            type: string;
+            pattern: string;
+        };
+        changedFiles: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    path: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    change: {
+                        type: string;
+                        enum: readonly string[];
+                    };
+                    kind: {
+                        type: string;
+                        enum: readonly string[];
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            minItems: number;
+            maxItems: number;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const resultSchema: {
+    type: string;
+    properties: {
+        schemaVersion: {
+            const: number;
+        };
+        headSha: {
+            type: string;
+            pattern: string;
+        };
+        baseSha: {
+            type: string;
+            pattern: string;
+        };
+        policyHash: {
+            type: string;
+            pattern: string;
+        };
+        status: {
+            type: string;
+            enum: readonly string[];
+        };
+        reviewer: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    pattern: string;
+                };
+                model: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    pattern: string;
+                };
+                context: {
+                    type: string;
+                    enum: readonly string[];
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+        summary: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+            pattern: string;
+        };
+        coverage: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    path: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    status: {
+                        type: string;
+                        enum: readonly string[];
+                    };
+                    evidenceIds: {
+                        uniqueItems: boolean;
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        minItems: number;
+                        maxItems: number;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            minItems: number;
+            maxItems: number;
+        };
+        validation: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    status: {
+                        type: string;
+                        enum: readonly string[];
+                    };
+                    reason: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    evidenceIds: {
+                        uniqueItems: boolean;
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        minItems: number;
+                        maxItems: number;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            minItems: number;
+            maxItems: number;
+        };
+        evidence: {
+            type: string;
+            items: {
+                oneOf: ({
+                    type: string;
+                    properties: {
+                        id: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        kind: {
+                            type: string;
+                            enum: readonly string[];
+                        };
+                        provenance: {
+                            const: string;
+                        };
+                        summary: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        anchors: {
+                            type: string;
+                            items: {
+                                type: string;
+                                properties: {
+                                    path: {
+                                        type: string;
+                                        minLength: number;
+                                        maxLength: number;
+                                        pattern: string;
+                                    };
+                                    side: {
+                                        type: string;
+                                        enum: readonly string[];
+                                    };
+                                    line: {
+                                        anyOf: ({
+                                            type: string;
+                                            minimum: number;
+                                        } | {
+                                            type: string;
+                                            minimum?: never;
+                                        })[];
+                                    };
+                                };
+                                required: string[];
+                                additionalProperties: boolean;
+                            };
+                            minItems: number;
+                            maxItems: number;
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                } | {
+                    type: string;
+                    properties: {
+                        id: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        kind: {
+                            const: string;
+                        };
+                        provenance: {
+                            const: string;
+                        };
+                        summary: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        anchors: {
+                            maxItems: number;
+                            type: string;
+                            items: {
+                                type: string;
+                                properties: {
+                                    path: {
+                                        type: string;
+                                        minLength: number;
+                                        maxLength: number;
+                                        pattern: string;
+                                    };
+                                    side: {
+                                        type: string;
+                                        enum: readonly string[];
+                                    };
+                                    line: {
+                                        anyOf: ({
+                                            type: string;
+                                            minimum: number;
+                                        } | {
+                                            type: string;
+                                            minimum?: never;
+                                        })[];
+                                    };
+                                };
+                                required: string[];
+                                additionalProperties: boolean;
+                            };
+                            minItems: number;
+                        };
+                        capture: {
+                            type: string;
+                            properties: {
+                                revision: {
+                                    type: string;
+                                    pattern: string;
+                                };
+                                startLine: {
+                                    type: string;
+                                    minimum: number;
+                                };
+                                endLine: {
+                                    type: string;
+                                    minimum: number;
+                                };
+                                totalLines: {
+                                    type: string;
+                                    minimum: number;
+                                };
+                                contentHash: {
+                                    type: string;
+                                    pattern: string;
+                                };
+                            };
+                            required: string[];
+                            additionalProperties: boolean;
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                })[];
+            };
+            minItems: number;
+            maxItems: number;
+        };
+        findings: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    priority: {
+                        type: string;
+                        enum: readonly string[];
+                    };
+                    kind: {
+                        type: string;
+                        enum: readonly string[];
+                    };
+                    category: {
+                        type: string;
+                        enum: readonly string[];
+                    };
+                    title: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    trigger: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    consequence: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    priorityReason: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    counterEvidence: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    suggestion: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    anchor: {
+                        type: string;
+                        properties: {
+                            path: {
+                                type: string;
+                                minLength: number;
+                                maxLength: number;
+                                pattern: string;
+                            };
+                            side: {
+                                type: string;
+                                enum: readonly string[];
+                            };
+                            line: {
+                                type: string;
+                                minimum: number;
+                            };
+                        };
+                        required: string[];
+                        additionalProperties: boolean;
+                    };
+                    evidenceIds: {
+                        minItems: number;
+                        uniqueItems: boolean;
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        maxItems: number;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            minItems: number;
+            maxItems: number;
+        };
+        limitations: {
+            type: string;
+            items: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                pattern: string;
+            };
+            minItems: number;
+            maxItems: number;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare function parsePacket(value: unknown): Packet;
+export declare function parseResult(value: unknown): Result;
+export declare function parsePolicy(value: unknown): Policy;
+export declare const defaultPolicy: () => Policy;
+export declare function initialResult(packet: Packet): Result;
+export {};

package/dist/contracts.js

@@ -0,0 +1,86 @@
+import { Ajv } from 'ajv';
+// Controller-authored validation messages only; never wrap provider or OS errors.
+export class ReviewInputError extends Error {
+}
+export const PRIORITIES = ['P0', 'P1', 'P2', 'P3', 'P4'];
+// Small schema constructors keep every object closed without a second schema framework.
+// Explicit whole-string matching also works with provider grammar decoders.
+export const text = { type: 'string', minLength: 1, maxLength: 16000, pattern: '^[\\s\\S]*\\S[\\s\\S]*$' };
+const sha = { type: 'string', pattern: '^[a-f0-9]{40}$' };
+const digest = { type: 'string', pattern: '^[a-f0-9]{64}$' };
+const choice = (values) => ({ type: 'string', enum: values });
+const array = (items, minItems = 0) => ({ type: 'array', items, minItems, maxItems: 10000 });
+const object = (properties) => ({
+    type: 'object', properties, required: Object.keys(properties), additionalProperties: false,
+});
+const refs = { ...array(text), uniqueItems: true };
+const anchor = object({ path: text, side: choice(['head', 'base']), line: { type: 'integer', minimum: 1 } });
+const evidenceAnchor = object({ path: text, side: choice(['head', 'base']), line: { anyOf: [{ type: 'integer', minimum: 1 }, { type: 'null' }] } });
+export const policySchema = object({
+    schemaVersion: { const: 1 }, rubricVersion: { const: '1' },
+    includeOptional: { type: 'boolean' }, requiredChecks: { ...array(text, 1), uniqueItems: true },
+});
+export const packetSchema = object({
+    schemaVersion: { const: 1 },
+    repository: { type: 'string', pattern: '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$' },
+    pr: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER },
+    baseRef: text, headSha: sha, baseSha: sha, mergeBaseSha: sha,
+    createdAt: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$' },
+    policy: policySchema, policyHash: digest, diffHash: digest,
+    changedFiles: array(object({ path: text, change: choice(['added', 'modified', 'deleted']), kind: choice(['text', 'binary', 'symlink', 'submodule']) })),
+});
+export const resultSchema = object({
+    schemaVersion: { const: 1 }, headSha: sha, baseSha: sha, policyHash: digest,
+    status: choice(['not-started', 'partial', 'completed']),
+    reviewer: object({ name: text, model: text, context: choice(['independent', 'author', 'unknown']) }),
+    summary: text,
+    coverage: array(object({ path: text, status: choice(['reviewed', 'unreviewed']), evidenceIds: refs })),
+    validation: array(object({ name: text, status: choice(['pass', 'fail', 'not-run', 'not-applicable']), reason: text, evidenceIds: refs })),
+    evidence: array({ oneOf: [object({
+                id: text, kind: choice(['source-reasoning', 'reproduction', 'ci']), provenance: { const: 'declared' },
+                summary: text, anchors: array(evidenceAnchor, 1),
+            }), object({
+                id: text, kind: { const: 'source-read' }, provenance: { const: 'controller-captured' },
+                summary: text, anchors: { ...array(evidenceAnchor, 1), maxItems: 1 },
+                capture: object({ revision: sha, startLine: { type: 'integer', minimum: 1 },
+                    endLine: { type: 'integer', minimum: 0 }, totalLines: { type: 'integer', minimum: 0 }, contentHash: digest }),
+            })] }),
+    findings: array(object({
+        id: text, priority: choice(PRIORITIES), kind: choice(['defect', 'improvement']),
+        category: choice(['correctness', 'security', 'data-integrity', 'reliability', 'validation', 'simplicity']),
+        title: text, trigger: text, consequence: text, priorityReason: text, counterEvidence: text,
+        suggestion: text, anchor, evidenceIds: { ...refs, minItems: 1 },
+    })),
+    limitations: array(text),
+});
+const ajv = new Ajv({ allErrors: true, strict: true });
+const validatePacketSchema = ajv.compile(packetSchema);
+const validateResultSchema = ajv.compile(resultSchema);
+const validatePolicySchema = ajv.compile(policySchema);
+export function parsePacket(value) {
+    if (!validatePacketSchema(value))
+        throw new Error(`Invalid packet: ${ajv.errorsText(validatePacketSchema.errors)}`);
+    return value;
+}
+export function parseResult(value) {
+    if (!validateResultSchema(value))
+        throw new Error(`Invalid result: ${ajv.errorsText(validateResultSchema.errors)}`);
+    return value;
+}
+export function parsePolicy(value) {
+    if (!validatePolicySchema(value))
+        throw new Error(`Invalid policy: ${ajv.errorsText(validatePolicySchema.errors)}`);
+    // Fixed ordering provides stable hashing independent of JSON property order.
+    return { schemaVersion: 1, rubricVersion: '1', includeOptional: value.includeOptional, requiredChecks: value.requiredChecks };
+}
+export const defaultPolicy = () => ({ schemaVersion: 1, rubricVersion: '1', includeOptional: false, requiredChecks: ['change-validation'] });
+export function initialResult(packet) {
+    return {
+        schemaVersion: 1, headSha: packet.headSha, baseSha: packet.baseSha, policyHash: packet.policyHash,
+        status: 'not-started', reviewer: { name: 'unknown', model: 'unknown', context: 'unknown' },
+        summary: 'The snapshot is captured. Investigation has not run.',
+        coverage: packet.changedFiles.map(({ path }) => ({ path, status: 'unreviewed', evidenceIds: [] })),
+        validation: packet.policy.requiredChecks.map(name => ({ name, status: 'not-run', reason: 'Required validation has not run.', evidenceIds: [] })),
+        evidence: [], findings: [], limitations: ['Investigation has not started; no repository code has been executed.'],
+    };
+}