peaks-loop 4.0.42 → 4.0.44

package/dist/services/scan/api-diff-openapi.js

@@ -0,0 +1,359 @@
+/**
+ * S1 / rid=api-diff-report — OpenAPI 3.x parsing for `peaks scan api-diff`.
+ *
+ * `.json` via `JSON.parse`; `.yaml` / `.yml` via the `yaml` runtime dependency.
+ * A document that is not OpenAPI 3.x, or that declares no operations, raises
+ * `ApiDiffInputError` — the command must never print an empty-but-successful
+ * diff.
+ *
+ * THE SAME INVERTED COMPLETENESS RULE THE RECORDED SIDE GETS APPLIES HERE
+ * (QA final gate): `collectFields` returns a *partial* field set just as easily
+ * as a complete one, and the two are indistinguishable downstream. Any schema
+ * construct this reader cannot fully account for marks its LOCATION as
+ * incomplete, which suppresses every exact line for that location. Partial is
+ * never presented as complete.
+ */
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { ApiDiffInputError, HTTP_METHODS, isRecord } from './api-diff-types.js';
+const MAX_REF_DEPTH = 4;
+/**
+ * OpenAPI scalar types mapped to their TypeScript spelling. `integer` is NOT a
+ * TypeScript type — an unmapped `integer` produced a false `number -> integer`
+ * exact line against a recorded `id: number`.
+ */
+const SCALAR_TYPES = {
+    string: 'string',
+    number: 'number',
+    integer: 'number',
+    boolean: 'boolean'
+};
+const COMPOSITION_KEYS = ['allOf', 'oneOf', 'anyOf'];
+function refName(ref) {
+    const tail = ref.slice(ref.lastIndexOf('/') + 1);
+    return tail.length > 0 ? tail : ref;
+}
+/** Resolves a `$ref` chain. Callers that only need the NAME must not use this — see `schemaToTypeString`. */
+function deref(schema, doc, depth) {
+    if (!isRecord(schema))
+        return null;
+    const ref = schema['$ref'];
+    if (typeof ref === 'string' && depth < MAX_REF_DEPTH) {
+        let node = doc;
+        for (const part of ref.replace(/^#\//, '').split('/')) {
+            if (!isRecord(node))
+                return null;
+            node = node[part];
+        }
+        return deref(node, doc, depth + 1);
+    }
+    return schema;
+}
+/** The composition/open-shape construct a schema node carries, if any — those cannot be flattened without a compiler. */
+function unreadableConstruct(node) {
+    for (const key of COMPOSITION_KEYS) {
+        const value = node[key];
+        if (Array.isArray(value) && value.length > 0) {
+            return `it composes schemas with \`${key}\`, which cannot be flattened here`;
+        }
+    }
+    const additional = node['additionalProperties'];
+    if (additional !== undefined && additional !== false) {
+        return 'it declares `additionalProperties`, so it may carry fields it does not list';
+    }
+    return null;
+}
+/**
+ * Renders an OpenAPI schema as a TypeScript-ish type text. Arrays render as
+ * `Array<X>` (not `X[]`) on purpose: `normalizeType` rewrites both sides
+ * identically, so a recorded `X[]` and a document `Array<X>` still compare equal.
+ *
+ * A `$ref` is answered with its referenced NAME and never dereferenced. Checking
+ * after `deref()` made `refName` unreachable for every ref inside
+ * `MAX_REF_DEPTH`, so a nested `owner: {$ref: User}` was reported as `object`
+ * against a recorded `owner: User` — an exact line for a field that did not
+ * change. The name is the faithful reading, and it is what a recorded interface
+ * writes.
+ */
+function schemaToTypeString(schema, doc, depth) {
+    if (isRecord(schema) && typeof schema['$ref'] === 'string') {
+        const named = refName(schema['$ref']);
+        return schema['nullable'] === true ? `${named} | null` : named;
+    }
+    const node = deref(schema, doc, depth);
+    if (!node)
+        return 'unknown';
+    const nullable = node['nullable'] === true;
+    const enumValues = node['enum'];
+    let base;
+    if (Array.isArray(enumValues) && enumValues.length > 0) {
+        base = enumValues.map((value) => (typeof value === 'string' ? JSON.stringify(value) : String(value))).join(' | ');
+    }
+    else if (COMPOSITION_KEYS.some((key) => Array.isArray(node[key]) && node[key].length > 0)) {
+        const key = COMPOSITION_KEYS.find((candidate) => Array.isArray(node[candidate]));
+        const variants = node[key];
+        const glue = key === 'allOf' ? ' & ' : ' | ';
+        base = variants.map((variant) => schemaToTypeString(variant, doc, depth + 1)).join(glue);
+    }
+    else if (Array.isArray(node['type'])) {
+        // OpenAPI 3.1 spells nullability as `type: ['string', 'null']`. The same
+        // SCALAR_TYPES mapping must apply here — joining with bare `String(entry)`
+        // leaked an unmapped `integer`, which this file's own comment records as a
+        // source of false `number -> integer` exact lines.
+        base = node['type']
+            .map((entry) => (typeof entry === 'string' && SCALAR_TYPES[entry] !== undefined ? SCALAR_TYPES[entry] : String(entry)))
+            .join(' | ');
+    }
+    else {
+        const type = node['type'];
+        if (type === 'array') {
+            const items = node['items'];
+            base = `Array<${items === undefined ? 'unknown' : schemaToTypeString(items, doc, depth + 1)}>`;
+        }
+        else if (type === 'object') {
+            base = 'object';
+        }
+        else if (typeof type === 'string' && SCALAR_TYPES[type] !== undefined) {
+            base = SCALAR_TYPES[type];
+        }
+        else {
+            base = 'unknown';
+        }
+    }
+    return nullable ? `${base} | null` : base;
+}
+/**
+ * Flat leaf fields of a body/response schema. Arrays descend one level into
+ * `items`. The ROOT `$ref` is resolved on purpose — a top-level `$ref` response
+ * IS the interface — while nested refs stay named (see `schemaToTypeString`).
+ *
+ * A node carrying `allOf`/`oneOf`/`anyOf` or `additionalProperties` alongside its
+ * own `properties` is INCOMPLETE: the sibling properties made the location look
+ * non-empty, so there was neither suppression nor a note, and a field declared
+ * under `allOf` was reported as an exact `-> (absent)`.
+ */
+const UNRESOLVED_REF = 'its schema is a `$ref` chain deeper than the reader resolves';
+const NO_PROPERTIES = 'its schema lists no `properties`, so no field set could be read from it';
+function collectFields(schema, doc) {
+    const fields = new Map();
+    const node = deref(schema, doc, 0);
+    if (!node)
+        return { fields, incompleteReason: 'its schema could not be read' };
+    if (typeof node['$ref'] === 'string')
+        return { fields, incompleteReason: UNRESOLVED_REF };
+    const rootIssue = unreadableConstruct(node);
+    if (rootIssue !== null)
+        return { fields, incompleteReason: rootIssue };
+    let target = node;
+    if (target['type'] === 'array' || target['items'] !== undefined) {
+        const items = deref(target['items'], doc, 0);
+        if (!items)
+            return { fields, incompleteReason: 'its array items schema could not be read' };
+        if (typeof items['$ref'] === 'string')
+            return { fields, incompleteReason: UNRESOLVED_REF };
+        const itemsIssue = unreadableConstruct(items);
+        if (itemsIssue !== null)
+            return { fields, incompleteReason: itemsIssue };
+        target = items;
+    }
+    const properties = target['properties'];
+    // An ABSENT `properties` is not an empty field set: it is a schema this reader
+    // cannot produce a field set from at all. Returning `{fields: {}, null}` here
+    // dropped the whole location, which is the "empty result treated as a
+    // successful one" failure the inverted rule exists to prevent — and dropping
+    // a readable `200` also let a `*Response` interface be compared against a
+    // surviving `404`, defeating the multi-status guard.
+    if (!isRecord(properties))
+        return { fields, incompleteReason: NO_PROPERTIES };
+    // Per OpenAPI, OMITTING `required` means every property is optional — which is
+    // how `openapi-typescript` renders it (`id?: T`). Treating an absent
+    // `required` as "everything is required" produced false
+    // `string | undefined -> string` lines against generated recordings.
+    const requiredRaw = target['required'];
+    const required = Array.isArray(requiredRaw)
+        ? new Set(requiredRaw.filter((entry) => typeof entry === 'string'))
+        : new Set();
+    for (const [key, propSchema] of Object.entries(properties)) {
+        const type = schemaToTypeString(propSchema, doc, 1);
+        fields.set(key, required.has(key) ? type : `${type} | undefined`);
+    }
+    return { fields, incompleteReason: null };
+}
+function jsonContent(content) {
+    if (!isRecord(content))
+        return undefined;
+    if (content['application/json'] !== undefined)
+        return content['application/json'];
+    return Object.values(content)[0];
+}
+function schemaOf(media) {
+    return isRecord(media) ? media['schema'] : undefined;
+}
+function collectParameters(parameters, locations) {
+    if (!Array.isArray(parameters))
+        return;
+    for (const raw of parameters) {
+        if (!isRecord(raw))
+            continue;
+        const where = raw['in'];
+        const name = raw['name'];
+        if (where !== 'path' && where !== 'query')
+            continue;
+        if (typeof name !== 'string')
+            continue;
+        const key = where === 'path' ? 'pathParams' : 'queryParams';
+        const bucket = locations.get(key) ?? new Map();
+        bucket.set(name, schemaToTypeString(raw['schema'], {}, 0));
+        locations.set(key, bucket);
+    }
+}
+export function parseOpenApiDocument(file, doc) {
+    const version = doc['openapi'];
+    if (typeof version !== 'string' || !/^3\.\d+/.test(version.trim())) {
+        throw new ApiDiffInputError('NOT_OPENAPI_3', `${file} is not an OpenAPI 3.x document (expected a top-level \`openapi: 3.x\` string, found ${version === undefined ? 'nothing' : JSON.stringify(version)})`);
+    }
+    const paths = doc['paths'];
+    if (!isRecord(paths)) {
+        throw new ApiDiffInputError('NO_PATHS', `${file} declares openapi ${version} but has no \`paths\` object — nothing to diff`);
+    }
+    const operations = [];
+    for (const [path, pathItemRaw] of Object.entries(paths)) {
+        const pathItem = deref(pathItemRaw, doc, 0);
+        if (!pathItem)
+            continue;
+        for (const method of HTTP_METHODS) {
+            const opRaw = pathItem[method];
+            if (!isRecord(opRaw))
+                continue;
+            const locations = new Map();
+            const locationIssues = new Map();
+            const record = (location, read) => {
+                if (read.fields.size === 0 && read.incompleteReason === null)
+                    return;
+                locations.set(location, read.fields);
+                if (read.incompleteReason !== null)
+                    locationIssues.set(location, read.incompleteReason);
+            };
+            const shared = Array.isArray(pathItem['parameters']) ? pathItem['parameters'] : [];
+            const own = Array.isArray(opRaw['parameters']) ? opRaw['parameters'] : [];
+            collectParameters([...shared, ...own], locations);
+            const requestBody = opRaw['requestBody'];
+            const bodySchema = schemaOf(jsonContent(isRecord(requestBody) ? requestBody['content'] : undefined));
+            if (bodySchema !== undefined)
+                record('request', collectFields(bodySchema, doc));
+            const responses = opRaw['responses'];
+            if (isRecord(responses)) {
+                for (const [status, responseRaw] of Object.entries(responses)) {
+                    if (!isRecord(responseRaw))
+                        continue;
+                    const responseSchema = schemaOf(jsonContent(responseRaw['content']));
+                    if (responseSchema === undefined)
+                        continue;
+                    record(`response.${status}`, collectFields(responseSchema, doc));
+                }
+            }
+            const operationId = typeof opRaw['operationId'] === 'string' ? opRaw['operationId'] : undefined;
+            operations.push(operationId === undefined
+                ? { method, path, locations, locationIssues }
+                : { method, path, operationId, locations, locationIssues });
+        }
+    }
+    if (operations.length === 0) {
+        throw new ApiDiffInputError('NO_OPERATIONS', `${file} is an OpenAPI ${version} document but declares no operations — refusing to print an empty diff`);
+    }
+    const info = doc['info'];
+    const title = isRecord(info) && typeof info['title'] === 'string' ? info['title'] : undefined;
+    return title === undefined ? { openapi: version, operations } : { openapi: version, title, operations };
+}
+/** Reads and parses `.json` / `.yaml` / `.yml`. Throws `ApiDiffInputError` on anything else. */
+export function loadApiDocument(file) {
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        throw new ApiDiffInputError('UNREADABLE', `cannot read ${file}: ${error.message}`);
+    }
+    const lower = file.toLowerCase();
+    let parsed;
+    try {
+        if (lower.endsWith('.yaml') || lower.endsWith('.yml'))
+            parsed = parseYaml(raw);
+        else if (lower.endsWith('.json') || raw.trimStart().startsWith('{'))
+            parsed = JSON.parse(raw);
+        else
+            parsed = parseYaml(raw);
+    }
+    catch (error) {
+        throw new ApiDiffInputError('PARSE_FAILED', `cannot parse ${file} as JSON or YAML: ${error.message}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new ApiDiffInputError('NOT_AN_OBJECT', `${file} did not parse to an object`);
+    }
+    return parseOpenApiDocument(file, parsed);
+}
+/** Splits on a separator that sits at bracket depth 0, leaving `("a" | "b")[]` and `Record<string, number>` intact. */
+function splitTopLevel(text, separator) {
+    const parts = [];
+    let current = '';
+    let inString = null;
+    let depth = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        const ch = text[i];
+        if (inString !== null) {
+            if (ch === '\\') {
+                current += ch + (text[i + 1] ?? '');
+                i += 1;
+                continue;
+            }
+            if (ch === inString)
+                inString = null;
+            current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`') {
+            inString = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '<' || ch === '(' || ch === '[' || ch === '{')
+            depth += 1;
+        else if (ch === '>' || ch === ')' || ch === ']' || ch === '}')
+            depth = Math.max(0, depth - 1);
+        if (depth === 0 && text.startsWith(separator, i)) {
+            parts.push(current);
+            current = '';
+            i += separator.length - 1;
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts;
+}
+/**
+ * Normalizes type text so `Array<string>`, `string[]`, `string | null` and
+ * `string|null` compare equal.
+ *
+ * Quote style is unified because it is a RENDERING artifact, not a change: the
+ * document renders enums via `JSON.stringify` (`"a"`) while hand-written
+ * recorded types use single quotes (`'a'`), so the same project written with
+ * double quotes emitted nothing and with single quotes emitted an exact
+ * CHANGED. Duplicate union members are collapsed for the same reason — a
+ * recorded `a?: X` normalises to `X | undefined`, which against a document's
+ * `X | undefined` used to become `X | undefined | undefined`.
+ */
+export function normalizeType(text) {
+    let out = text.trim().replace(/[;,]\s*$/, '').replace(/\s+/g, ' ');
+    out = out.replace(/'([^'\\]*)'/g, '"$1"');
+    out = out.replace(/\s*\|\s*/g, ' | ').replace(/\s*&\s*/g, ' & ');
+    const union = splitTopLevel(out, ' | ');
+    if (union.length > 1)
+        out = [...new Set(union)].join(' | ');
+    out = out.replace(/\s*\[\s*\]/g, '[]');
+    for (let pass = 0; pass < 3; pass += 1) {
+        out = out.replace(/Array<([^<>]*)>/g, (_all, inner) => (/[|&]/.test(inner) ? `(${inner})[]` : `${inner}[]`));
+    }
+    out = out.replace(/\s*<\s*/g, '<').replace(/\s*>\s*/g, '>');
+    return out.trim();
+}

package/dist/services/scan/api-diff-recorded.d.ts

@@ -0,0 +1,96 @@
+/**
+ * S1 / rid=api-diff-report — the three RECORDED sources for `peaks scan api-diff`,
+ * plus the candidate name-grep.
+ *
+ *   1. `.peaks/_runtime/<sid>/rd/mock-plan.md`  (most recent by mtime)
+ *   2. recorded `*-api.types.ts` interfaces     (from (1) + `src/services/types`)
+ *   3. the `## API Migration` endpoint list in `.peaks/_runtime/<sid>/txt/*.md`
+ *
+ * All three are OPTIONAL: absence is reported in the report's `notes`, never
+ * silently. `typescript` is a devDependency and is NOT available at runtime, so
+ * recorded interfaces are read by the line-based extractor below — its limits
+ * are documented on the function and exercised by tests.
+ */
+import { type CandidateMention, type DocOperation, type InterfaceRole, type RecordedEndpoint, type RecordedInterface } from './api-diff-types.js';
+export declare const MAX_CANDIDATE_NAMES = 100;
+/**
+ * Line-based extractor for recorded `*-api.types.ts` interfaces.
+ *
+ * INVERTED DEFAULT (QA round 2): a line-based reader cannot tell "this line is
+ * not a member" from "I failed to read this member", so the model is not
+ * "exact unless I found a reason to suppress". It is the opposite — **an
+ * interface is COMPLETE only while every depth-1 line in its body is
+ * classified**. The first line the extractor cannot classify makes the whole
+ * interface INCOMPLETE, which suppresses every exact line for it and emits one
+ * note naming it and the reason.
+ *
+ * That is what catches, without needing to enumerate them in advance: quoted
+ * keys, index signatures, multi-line unions (the continuation line is the
+ * unclassifiable one), intersections and mapped types (which never reach a body
+ * at all — see `DECLARATION_LIKE`), and nested inline objects.
+ *
+ * KNOWN LIMITS, stated rather than papered over:
+ *   - members are matched at depth 1 only; a nested shape is `object` and makes
+ *     the interface incomplete rather than being half-read;
+ *   - `extends` is unresolvable without a compiler, so such an interface is
+ *     incomplete by construction;
+ *   - a regex literal containing a brace would still mis-count (`braceBalance`).
+ */
+export declare function parseRecordedInterfaces(source: string, file: string): RecordedInterface[];
+/**
+ * Which half of an operation an interface describes, from the suffix its name
+ * carries. `unknown` is a refusal, not a default: diffing an interface against
+ * a location it does not describe is how a request field got reported at a
+ * response location, and how a response-shaped `*Dto` got reported at the
+ * requestBody.
+ *
+ * Only suffixes that actually name a side are accepted. `Dto` names neither
+ * side (a `UserDto` is as likely to be a response), and a bare `Body` does not
+ * say which side it belongs to either — `GetThingResponseBody` ends in `Body`.
+ * `...RequestBody` still classifies as a request via the `request` suffix. A
+ * suffix that carries no information must not receive LESS caution than no
+ * suffix at all, so both become `unknown` and are refused with a note.
+ */
+export declare function roleOf(name: string): InterfaceRole;
+/** Locations of `operation` that `role` is allowed to describe. */
+export declare function locationsForRole(operation: DocOperation, role: InterfaceRole): string[];
+/** Source 1: the most recent `.peaks/_runtime/<sid>/rd/mock-plan.md`. */
+export declare function findMockPlan(projectRoot: string): string | null;
+/** Pulls the file paths a mock plan records (backticked or whitespace-delimited). */
+export declare function extractMockPlanPaths(source: string): string[];
+/** Source 2: recorded interface files — mock-plan-named plus the prescribed `src/services/types/*-api.types.ts` layout. */
+export declare function findRecordedInterfaceFiles(projectRoot: string, mockPlan: string | null): string[];
+/** Source 3: the newest TXT handoff that actually carries an `## API Migration` section. */
+export declare function findHandoffWithApiMigration(projectRoot: string): string | null;
+/** Parses the `## API Migration` body for `<METHOD> <path>` pairs. */
+export declare function parseHandoffEndpoints(source: string): RecordedEndpoint[];
+/**
+ * Key used to pair a document operation with a recorded interface. Deliberately
+ * conservative: only lowercasing, punctuation removal, and one trailing
+ * `Response`/`Request`/`Dto`/`Payload`/`Body` strip. Verb stripping (`getUser`
+ * -> `user`) was considered and rejected — a false pairing produces a
+ * confidently wrong diff, which is worse than the visible false negative of an
+ * unpaired interface (design §2.3).
+ */
+export declare function pairingKey(name: string): string;
+export declare function operationKey(operation: DocOperation): string;
+/**
+ * Greps every candidate name across the consumer's source and non-TS assets.
+ * Over-reports (test fixtures, unrelated identifiers) and under-reports (i18n
+ * keys, AntD `columns` arrays, monorepo barrels) — the report says so.
+ *
+ * `exclude` carries the OpenAPI document itself: it is the input, not a change
+ * site, and every field name would otherwise match on its own definition line.
+ */
+export declare function grepCandidateMentions(projectRoot: string, names: readonly string[], exclude?: readonly string[]): {
+    mentions: CandidateMention[];
+    truncated: boolean;
+    hitsTruncated: boolean;
+};
+/**
+ * Canonical endpoint path for comparison: `{id}` and `:id` are the same
+ * endpoint spelled two ways, and raw equality reported them as an exact
+ * ADDED + REMOVED pair. Parameter NAMES are collapsed too — `/users/{id}` and
+ * `/users/{userId}` are one endpoint.
+ */
+export declare function normalizeEndpointPath(path: string): string;