@avi770/testteam 3.0.0 → 3.2.0

package/dist/agents/113-response-contract-auditor.js

@@ -0,0 +1,694 @@
+/**
+ * Response Contract Auditor (Contract-Drift v2) — compares the response
+ * SHAPE a route handler actually builds against the response schema the
+ * OpenAPI/Swagger spec declares for that route.
+ *
+ * #95 (API Contract Drift) checks that routes *exist* on both sides
+ * (path × method). This is the v2: for routes present in both code and
+ * spec, it diffs the *fields* of the JSON body the handler returns against
+ * the spec's declared response `properties`:
+ *
+ *   - 113-undeclared-field        medium  infra-issue
+ *       Handler returns a field the contract never declares — drift; the
+ *       field is undocumented and clients can't rely on it.
+ *   - 113-undeclared-sensitive    high    code-bug-security
+ *       The undeclared field name looks sensitive (password / token /
+ *       secret / ssn / hash …) — likely accidental data exposure.
+ *   - 113-missing-required        medium  infra-issue
+ *       The contract marks a field `required` but the handler omits it —
+ *       breaks clients. Only emitted when the path declares a single
+ *       response schema (unambiguous).
+ *   - 113-no-spec / 113-no-shapes / 113-summary  info
+ *
+ * Sources: a JSON or YAML OpenAPI/Swagger spec (found like #95), plus
+ * #87's connection-map for the route → file inventory.
+ *
+ * False-positive bounds (deliberate):
+ *   - Response-shape diffing runs ONLY for files whose routes all map to a
+ *     single resource path (next-app/next-pages route files, single-route
+ *     express files) — so the handler's response literal is unambiguously
+ *     that path's.
+ *   - Only object-LITERAL responses (`res.json({ … })`, `Response.json({ … })`)
+ *     are inspected; `res.json(variable)` is skipped (shape unknown).
+ *   - Schemas with `additionalProperties` are treated as open (no
+ *     undeclared-field findings).
+ *
+ * Persists `evidence/response-contract-audit.json`. Read-only,
+ * parallel-safe, static analysis only — never connects to a real API.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { BaseAgent } from './base-agent.js';
+import { findSpecFile, normalisePath } from './95-contract-drift.js';
+export const SENSITIVE_RE = /^(?:password|passwd|pwd|token|secret|apikey|api_key|accesstoken|refreshtoken|ssn|creditcard|cardnumber|cvv|privatekey|private_key|hash|salt|sessionid|session_id)$/i;
+const TWO_XX_RE = /^2\d\d$/;
+function asObj(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v) ? v : null;
+}
+function asArr(v) {
+    return Array.isArray(v) ? v : null;
+}
+function asStr(v) {
+    return typeof v === 'string' ? v : null;
+}
+function stripComment(line) {
+    let inString = null;
+    let escape = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (inString) {
+            if (ch === '\\')
+                escape = true;
+            else if (ch === inString)
+                inString = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = ch;
+            continue;
+        }
+        if (ch === '#' && (i === 0 || /\s/.test(line[i - 1])))
+            return line.slice(0, i);
+    }
+    return line;
+}
+function unquote(s) {
+    const t = s.trim();
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+function parseScalar(raw) {
+    const s = raw.trim();
+    if (s === '' || s === '~' || s === 'null')
+        return null;
+    if (s.startsWith('[')) {
+        const end = s.lastIndexOf(']');
+        const inner = s.slice(1, end === -1 ? s.length : end).trim();
+        if (inner === '')
+            return [];
+        return inner.split(',').map((x) => parseScalar(x));
+    }
+    if (s.startsWith('{')) {
+        const end = s.lastIndexOf('}');
+        const inner = s.slice(1, end === -1 ? s.length : end);
+        const obj = {};
+        for (const pair of inner.split(',')) {
+            const ci = pair.indexOf(':');
+            if (ci >= 0)
+                obj[unquote(pair.slice(0, ci))] = parseScalar(pair.slice(ci + 1));
+        }
+        return obj;
+    }
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        return s.slice(1, -1);
+    }
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    if (/^-?\d+(?:\.\d+)?$/.test(s))
+        return Number(s);
+    return s;
+}
+function parseYamlBlock(lines, start, indent) {
+    if (start >= lines.length || lines[start].indent < indent)
+        return [null, start];
+    if (lines[start].text.startsWith('- ')) {
+        const arr = [];
+        let i = start;
+        while (i < lines.length && lines[i].indent === indent && lines[i].text.startsWith('- ')) {
+            const itemText = lines[i].text.slice(2).trim();
+            if (itemText === '') {
+                const childIndent = i + 1 < lines.length ? lines[i + 1].indent : indent + 1;
+                if (childIndent > indent) {
+                    const [val, ni] = parseYamlBlock(lines, i + 1, childIndent);
+                    arr.push(val);
+                    i = ni;
+                }
+                else {
+                    arr.push(null);
+                    i++;
+                }
+            }
+            else {
+                arr.push(parseScalar(itemText));
+                i++;
+            }
+        }
+        return [arr, i];
+    }
+    const obj = {};
+    let i = start;
+    while (i < lines.length && lines[i].indent === indent && !lines[i].text.startsWith('- ')) {
+        const m = lines[i].text.match(/^(['"]?)(.+?)\1\s*:(.*)$/);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const key = unquote(m[2]);
+        const rest = m[3].trim();
+        if (rest === '') {
+            const childIndent = i + 1 < lines.length ? lines[i + 1].indent : indent;
+            if (i + 1 < lines.length && childIndent > indent) {
+                const [val, ni] = parseYamlBlock(lines, i + 1, childIndent);
+                obj[key] = val;
+                i = ni;
+            }
+            else {
+                obj[key] = null;
+                i++;
+            }
+        }
+        else {
+            obj[key] = parseScalar(rest);
+            i++;
+        }
+    }
+    return [obj, i];
+}
+export function parseYaml(content) {
+    const lines = [];
+    for (const raw of content.split(/\r?\n/)) {
+        const stripped = stripComment(raw);
+        if (stripped.trim() === '' || /^\s*---\s*$/.test(stripped) || /^\s*%/.test(stripped))
+            continue;
+        lines.push({ indent: stripped.match(/^ */)?.[0].length ?? 0, text: stripped.trim() });
+    }
+    if (lines.length === 0)
+        return {};
+    return parseYamlBlock(lines, 0, lines[0].indent)[0];
+}
+export function parseSpecDocument(content, filePath) {
+    if (filePath.endsWith('.json')) {
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            return {};
+        }
+    }
+    return parseYaml(content);
+}
+function resolveRef(ref, doc) {
+    if (!ref.startsWith('#/'))
+        return null;
+    let cur = doc;
+    for (const seg of ref.slice(2).split('/')) {
+        const o = asObj(cur ?? undefined);
+        if (!o)
+            return null;
+        cur = o[seg.replace(/~1/g, '/').replace(/~0/g, '~')];
+        if (cur === undefined)
+            return null;
+    }
+    return cur;
+}
+/** Collect top-level property names + required list from a (possibly $ref'd) schema. */
+export function collectSchemaShape(schema, doc, depth = 0) {
+    const shape = { properties: new Set(), required: [], open: false };
+    if (depth > 6)
+        return shape;
+    const obj = asObj(schema);
+    if (!obj)
+        return shape;
+    const ref = asStr(obj.$ref);
+    if (ref) {
+        const resolved = resolveRef(ref, doc);
+        if (resolved)
+            return collectSchemaShape(resolved, doc, depth + 1);
+        return shape;
+    }
+    // array → inspect item schema
+    if (asStr(obj.type) === 'array' && obj.items) {
+        return collectSchemaShape(obj.items, doc, depth + 1);
+    }
+    // allOf / oneOf / anyOf → merge
+    for (const combiner of ['allOf', 'oneOf', 'anyOf']) {
+        const arr = asArr(obj[combiner]);
+        if (arr) {
+            for (const sub of arr) {
+                const subShape = collectSchemaShape(sub, doc, depth + 1);
+                for (const p of subShape.properties)
+                    shape.properties.add(p);
+                shape.required.push(...subShape.required);
+                if (subShape.open)
+                    shape.open = true;
+            }
+        }
+    }
+    const props = asObj(obj.properties);
+    if (props) {
+        for (const k of Object.keys(props))
+            shape.properties.add(k);
+    }
+    const required = asArr(obj.required);
+    if (required) {
+        for (const r of required) {
+            const s = asStr(r);
+            if (s)
+                shape.required.push(s);
+        }
+    }
+    if (obj.additionalProperties !== undefined && obj.additionalProperties !== false) {
+        shape.open = true;
+    }
+    return shape;
+}
+/** Build normalised-path → declared response shape from a spec document. */
+export function declaredShapesByPath(doc) {
+    const out = new Map();
+    const root = asObj(doc);
+    if (!root)
+        return out;
+    const paths = asObj(root.paths);
+    if (!paths)
+        return out;
+    for (const [rawPath, rawItem] of Object.entries(paths)) {
+        const item = asObj(rawItem);
+        if (!item)
+            continue;
+        const norm = normalisePath(rawPath);
+        for (const [method, rawOp] of Object.entries(item)) {
+            if (!/^(get|post|put|patch|delete|options|head|trace)$/i.test(method))
+                continue;
+            const op = asObj(rawOp);
+            if (!op)
+                continue;
+            const responses = asObj(op.responses);
+            if (!responses)
+                continue;
+            // pick the first 2xx (or `default`) response with a JSON schema
+            const codes = Object.keys(responses).filter((c) => TWO_XX_RE.test(c));
+            if (responses.default)
+                codes.push('default');
+            for (const code of codes) {
+                const resp = asObj(responses[code]);
+                if (!resp)
+                    continue;
+                const schema = findResponseSchema(resp);
+                if (!schema)
+                    continue;
+                const shape = collectSchemaShape(schema, root);
+                if (shape.properties.size === 0 && !shape.open)
+                    continue;
+                const existing = out.get(norm);
+                if (!existing) {
+                    out.set(norm, {
+                        properties: new Set(shape.properties),
+                        requiredSingle: shape.required.length ? [...new Set(shape.required)] : [],
+                        open: shape.open,
+                    });
+                }
+                else {
+                    for (const p of shape.properties)
+                        existing.properties.add(p);
+                    existing.requiredSingle = null; // more than one schema → ambiguous
+                    if (shape.open)
+                        existing.open = true;
+                }
+                break; // one response schema per operation is enough
+            }
+        }
+    }
+    return out;
+}
+/** OpenAPI 3 (`content.<mime>.schema`) or Swagger 2 (`schema`) response schema. */
+function findResponseSchema(resp) {
+    const content = asObj(resp.content);
+    if (content) {
+        const json = asObj(content['application/json']) ?? asObj(Object.values(content)[0]);
+        if (json && json.schema !== undefined)
+            return json.schema;
+    }
+    if (resp.schema !== undefined)
+        return resp.schema; // Swagger 2
+    return null;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Code side — response object-literal key extraction
+// ─────────────────────────────────────────────────────────────────────────
+function readBraces(content, openIdx) {
+    if (content[openIdx] !== '{')
+        return null;
+    let depth = 0;
+    let inString = null;
+    let escape = false;
+    for (let i = openIdx; i < content.length; i++) {
+        const ch = content[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (inString) {
+            if (ch === '\\')
+                escape = true;
+            else if (ch === inString)
+                inString = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`') {
+            inString = ch;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return { text: content.slice(openIdx, i + 1), end: i };
+        }
+    }
+    return null;
+}
+/** Top-level keys of an object-literal `{ … }` text (handles shorthand + quoted keys). */
+export function objectLiteralKeys(text) {
+    const keys = [];
+    let depth = 0;
+    let inString = null;
+    let escape = false;
+    let atPropStart = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (inString) {
+            if (ch === '\\')
+                escape = true;
+            else if (ch === inString)
+                inString = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`') {
+            if (atPropStart && depth === 1 && (ch === '"' || ch === "'")) {
+                let j = i + 1;
+                let key = '';
+                let esc = false;
+                for (; j < text.length; j++) {
+                    const c = text[j];
+                    if (esc) {
+                        key += c;
+                        esc = false;
+                        continue;
+                    }
+                    if (c === '\\') {
+                        esc = true;
+                        continue;
+                    }
+                    if (c === ch)
+                        break;
+                    key += c;
+                }
+                let m = j + 1;
+                while (m < text.length && /\s/.test(text[m]))
+                    m++;
+                if (text[m] === ':')
+                    keys.push(key);
+                i = j;
+                atPropStart = false;
+                continue;
+            }
+            inString = ch;
+            continue;
+        }
+        if (ch === '{') {
+            depth++;
+            atPropStart = depth === 1;
+            continue;
+        }
+        if (ch === '[' || ch === '(') {
+            depth++;
+            atPropStart = false;
+            continue;
+        }
+        if (ch === '}' || ch === ']' || ch === ')') {
+            depth--;
+            atPropStart = false;
+            continue;
+        }
+        if (ch === ',' && depth === 1) {
+            atPropStart = true;
+            continue;
+        }
+        if (depth === 1 && atPropStart) {
+            if (/\s/.test(ch))
+                continue;
+            if (ch === '.') {
+                atPropStart = false; // spread `...x`
+                continue;
+            }
+            if (/[A-Za-z_$]/.test(ch)) {
+                let j = i;
+                let id = '';
+                while (j < text.length && /[\w$]/.test(text[j])) {
+                    id += text[j];
+                    j++;
+                }
+                let m = j;
+                while (m < text.length && /\s/.test(text[m]))
+                    m++;
+                if (text[m] === ':' || text[m] === ',' || text[m] === '}')
+                    keys.push(id);
+                i = j - 1;
+                atPropStart = false;
+                continue;
+            }
+            atPropStart = false;
+        }
+    }
+    return [...new Set(keys)];
+}
+const RESPONSE_EMITTERS = [
+    /\.\s*status\s*\([^)]*\)\s*\.\s*json\s*\(/g,
+    /\bres\s*\.\s*json\s*\(/g,
+    /\bres\s*\.\s*jsonp\s*\(/g,
+    /\bres\s*\.\s*send\s*\(/g,
+    /\b(?:NextResponse|Response)\s*\.\s*json\s*\(/g,
+];
+/** Union of top-level keys across every object-literal response in a file. */
+export function extractResponseKeys(content) {
+    const keys = new Set();
+    for (const spec of RESPONSE_EMITTERS) {
+        const re = new RegExp(spec.source, 'g');
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            let k = m.index + m[0].length;
+            while (k < content.length && /\s/.test(content[k]))
+                k++;
+            if (content[k] !== '{')
+                continue;
+            const braces = readBraces(content, k);
+            if (!braces)
+                continue;
+            for (const key of objectLiteralKeys(braces.text))
+                keys.add(key);
+        }
+    }
+    return [...keys];
+}
+export function auditResponseContract(input) {
+    const shapes = declaredShapesByPath(input.doc);
+    const findings = [];
+    if (shapes.size === 0)
+        return findings;
+    // Group routes by file; only single-resource-path files get shape diffing.
+    const routesByFile = new Map();
+    for (const r of input.routes) {
+        const list = routesByFile.get(r.file) ?? [];
+        list.push({ method: r.method, path: r.path });
+        routesByFile.set(r.file, list);
+    }
+    const seen = new Set();
+    for (const [file, routes] of routesByFile) {
+        const norms = new Set(routes.map((r) => normalisePath(r.path)));
+        if (norms.size !== 1)
+            continue; // ambiguous association → skip
+        const norm = [...norms][0];
+        const declared = shapes.get(norm);
+        if (!declared || declared.open || declared.properties.size === 0)
+            continue;
+        const content = input.fileContents.get(file);
+        if (content === undefined)
+            continue;
+        const responseKeys = extractResponseKeys(content);
+        if (responseKeys.length === 0)
+            continue;
+        for (const key of responseKeys) {
+            if (declared.properties.has(key))
+                continue;
+            const kind = SENSITIVE_RE.test(key) ? 'undeclared-sensitive' : 'undeclared-field';
+            const id = `${kind}:${norm}:${key}:${file}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            findings.push({ kind, path: norm, field: key, file });
+        }
+        if (declared.requiredSingle) {
+            for (const req of declared.requiredSingle) {
+                if (responseKeys.includes(req))
+                    continue;
+                const id = `missing-required:${norm}:${req}:${file}`;
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                findings.push({ kind: 'missing-required', path: norm, field: req, file });
+            }
+        }
+    }
+    return findings;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Agent
+// ─────────────────────────────────────────────────────────────────────────
+export class ResponseContractAuditorAgent extends BaseAgent {
+    agentId = 113;
+    agentName = 'Response Contract Auditor';
+    async preFlight() {
+        const root = this.config.projectRoot ?? process.cwd();
+        if (!fs.existsSync(root)) {
+            throw new Error(`projectRoot does not exist: ${root}`);
+        }
+    }
+    async execute() {
+        const findings = [];
+        const projectRoot = this.config.projectRoot ?? process.cwd();
+        const specFile = findSpecFile(projectRoot);
+        if (!specFile) {
+            findings.push({
+                id: `${this.agentId}-no-spec`,
+                type: 'infra-issue',
+                severity: 'info',
+                agentId: this.agentId,
+                module: 'response-contract-auditor',
+                description: 'No OpenAPI / Swagger spec found — response-shape drift needs a spec (openapi.{json,yaml,yml}, swagger.*, api.*) at root, docs/, openapi/, api/, or spec/.',
+            });
+            return findings;
+        }
+        let doc;
+        try {
+            doc = parseSpecDocument(fs.readFileSync(specFile, 'utf-8'), specFile);
+        }
+        catch (err) {
+            findings.push({
+                id: `${this.agentId}-spec-unreadable`,
+                type: 'infra-issue',
+                severity: 'high',
+                agentId: this.agentId,
+                module: 'response-contract-auditor',
+                description: `Spec file ${specFile} exists but couldn't be parsed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            return findings;
+        }
+        const mapPath = path.join(this.runDir, 'evidence', 'connection-map.json');
+        let map = null;
+        try {
+            map = JSON.parse(fs.readFileSync(mapPath, 'utf-8'));
+        }
+        catch {
+            map = null;
+        }
+        if (!map) {
+            findings.push({
+                id: `${this.agentId}-no-map`,
+                type: 'infra-issue',
+                severity: 'high',
+                agentId: this.agentId,
+                module: 'response-contract-auditor',
+                description: `Found spec at ${path.relative(projectRoot, specFile)} but no connection-map.json — Agent #87 must run first.`,
+            });
+            return findings;
+        }
+        const routes = map.routes
+            .filter((r) => r.framework !== 'unknown')
+            .map((r) => ({ method: r.method, path: r.path, file: r.file }));
+        const fileContents = new Map();
+        for (const file of new Set(routes.map((r) => r.file))) {
+            try {
+                fileContents.set(file, fs.readFileSync(path.join(projectRoot, file), 'utf-8'));
+            }
+            catch {
+                // skip unreadable
+            }
+        }
+        const drift = auditResponseContract({ doc, routes, fileContents });
+        this.persistAudit(projectRoot, path.relative(projectRoot, specFile).split(path.sep).join('/'), routes.length, drift);
+        if (drift.length === 0) {
+            findings.push({
+                id: `${this.agentId}-no-shapes`,
+                type: 'infra-issue',
+                severity: 'info',
+                agentId: this.agentId,
+                module: 'response-contract-auditor',
+                description: `Compared ${routes.length} code route(s) against the spec — no response-shape drift detected.`,
+            });
+            return findings;
+        }
+        for (const d of drift.slice(0, 100)) {
+            if (d.kind === 'undeclared-sensitive') {
+                findings.push({
+                    id: `${this.agentId}-undeclared-sensitive-${d.path.replace(/[^\w]/g, '_')}-${d.field}`,
+                    type: 'code-bug-security',
+                    severity: 'high',
+                    agentId: this.agentId,
+                    module: 'response-contract-auditor',
+                    description: `Handler for ${d.path} (${d.file}) returns sensitive-looking field "${d.field}" that the API contract does not declare — likely accidental data exposure. Strip it from the response or add it to the spec only if intended.`,
+                    file: d.file,
+                });
+            }
+            else if (d.kind === 'undeclared-field') {
+                findings.push({
+                    id: `${this.agentId}-undeclared-field-${d.path.replace(/[^\w]/g, '_')}-${d.field}`,
+                    type: 'infra-issue',
+                    severity: 'medium',
+                    agentId: this.agentId,
+                    module: 'response-contract-auditor',
+                    description: `Handler for ${d.path} (${d.file}) returns field "${d.field}" not declared in the response schema — contract drift; either document it or stop returning it.`,
+                    file: d.file,
+                });
+            }
+            else {
+                findings.push({
+                    id: `${this.agentId}-missing-required-${d.path.replace(/[^\w]/g, '_')}-${d.field}`,
+                    type: 'infra-issue',
+                    severity: 'medium',
+                    agentId: this.agentId,
+                    module: 'response-contract-auditor',
+                    description: `Contract marks "${d.field}" required for ${d.path} but the handler (${d.file}) never includes it in its response — breaks clients expecting the field.`,
+                    file: d.file,
+                });
+            }
+        }
+        findings.push({
+            id: `${this.agentId}-summary`,
+            type: 'infra-issue',
+            severity: 'info',
+            agentId: this.agentId,
+            module: 'response-contract-auditor',
+            description: `Response-contract audit: ${drift.length} drift(s) — ${drift.filter(d => d.kind === 'undeclared-sensitive').length} sensitive, ${drift.filter(d => d.kind === 'undeclared-field').length} undeclared, ${drift.filter(d => d.kind === 'missing-required').length} missing-required.`,
+        });
+        return findings;
+    }
+    persistAudit(projectRoot, specFile, routeCount, drift) {
+        try {
+            const evidenceDir = path.join(this.runDir, 'evidence');
+            fs.mkdirSync(evidenceDir, { recursive: true });
+            fs.writeFileSync(path.join(evidenceDir, 'response-contract-audit.json'), JSON.stringify({ version: 1, generatedAt: new Date().toISOString(), projectRoot, specFile, routeCount, drift }, null, 2), 'utf-8');
+            this.addEvidence({
+                type: 'report',
+                path: 'evidence/response-contract-audit.json',
+                description: `Response-contract audit: ${drift.length} drift(s) across ${routeCount} route(s) vs ${specFile}`,
+            });
+        }
+        catch {
+            // non-fatal
+        }
+    }
+}
+//# sourceMappingURL=113-response-contract-auditor.js.map