peaks-loop 4.0.42 → 4.0.44

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

@@ -0,0 +1,407 @@
+/**
+ * S1 / rid=api-diff-report — `peaks scan api-diff <doc>` (design
+ * `docs/superpowers/specs/2026-09-12-frontend-acl-contract-design.md` §2.1/§2.3).
+ *
+ * Read-only. Parses an OpenAPI 3.x document (JSON or YAML — `yaml` is already a
+ * runtime dependency) and diffs it against the three sources a consumer project
+ * already produces: `mock-plan.md`, the recorded `*-api.types.ts` interfaces,
+ * and the TXT handoff's `## API Migration` endpoint list.
+ *
+ * TWO RULES GOVERN EVERY LINE BELOW (QA repair, rid=api-diff-report):
+ *
+ *   1. Each document LOCATION is diffed against the recorded interface that
+ *      actually describes it. An operation has independent locations (path /
+ *      query / requestBody / per-status response) and a `...Request` interface
+ *      must never be compared against a response. No shared consumption across
+ *      locations.
+ *   2. Exactness requires BOTH sides to be fully known. Any uncertainty on the
+ *      recorded side SUPPRESSES the exact claim and says so — it is never
+ *      merely annotated. A half-readable interface silently invents
+ *      `added-in-document` / `removed-from-document` lines.
+ *
+ * This is the public entrypoint; parsing (`api-diff-openapi`), the recorded
+ * sources (`api-diff-recorded`) and the shared types (`api-diff-types`) live in
+ * sibling modules and are re-exported here.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadApiDocument, normalizeType } from './api-diff-openapi.js';
+import { MAX_CANDIDATE_NAMES, findHandoffWithApiMigration, findMockPlan, findRecordedInterfaceFiles, grepCandidateMentions, locationsForRole, normalizeEndpointPath, operationKey, pairingKey, parseHandoffEndpoints, parseRecordedInterfaces, roleOf } from './api-diff-recorded.js';
+import { ABSENT, NOT_DETECTABLE, toDisplayPath } from './api-diff-types.js';
+// The public surface of the whole api-diff feature, so callers (and the CLI)
+// need only ever import this one module.
+export * from './api-diff-openapi.js';
+export * from './api-diff-recorded.js';
+export * from './api-diff-types.js';
+const MAX_LISTED = 20;
+/** Bounded comma list for a note. Notes are read by humans, so they must not be unbounded. */
+function summarizeList(items) {
+    if (items.length === 0)
+        return '(none)';
+    if (items.length <= MAX_LISTED)
+        return items.join(', ');
+    return `${items.slice(0, MAX_LISTED).join(', ')}, +${items.length - MAX_LISTED} more`;
+}
+/** `GET /api/users/{id} response.200`, the unit a note has to be able to name. */
+function locationLabel(operation, location) {
+    return `${operation.method.toUpperCase()} ${operation.path} ${location}`;
+}
+// ---------------------------------------------------------------------------
+// The diff
+// ---------------------------------------------------------------------------
+/**
+ * Diffs ONE document location against ONE recorded interface.
+ *
+ * No state is shared between calls: an interface is only ever compared against
+ * locations of its own role, so a member consumed at a response location can no
+ * longer hide a request field (or vice versa).
+ */
+function compareLocation(operation, location, members, out) {
+    const docFields = operation.locations.get(location);
+    const recordedNormalized = new Map();
+    for (const [name, type] of members)
+        recordedNormalized.set(name, normalizeType(type));
+    const docOnly = [];
+    const recordedOnly = [];
+    const consumedDoc = new Set();
+    const consumedRecorded = new Set();
+    // Pass 1 — same name on both sides.
+    for (const [name, type] of docFields) {
+        const before = recordedNormalized.get(name);
+        if (before === undefined) {
+            docOnly.push(name);
+            continue;
+        }
+        consumedDoc.add(name);
+        consumedRecorded.add(name);
+        const after = normalizeType(type);
+        if (before !== after) {
+            out.push({
+                confidence: 'exact', kind: 'changed', via: 'type-changed', method: operation.method,
+                path: operation.path, location, before: { field: name, type: before }, after: { field: name, type: after }
+            });
+        }
+    }
+    for (const name of recordedNormalized.keys()) {
+        if (!docFields.has(name))
+            recordedOnly.push(name);
+    }
+    // Pass 2 — rename pairing for the leftovers, and ONLY when the type is
+    // identical and each side offers exactly one such candidate. Ambiguity is
+    // left alone: a guessed pairing is invisible, an unpaired field is not.
+    for (const docName of docOnly) {
+        const docType = normalizeType(docFields.get(docName));
+        const docCandidates = docOnly.filter((other) => normalizeType(docFields.get(other)) === docType);
+        const recordedCandidates = recordedOnly.filter((other) => recordedNormalized.get(other) === docType);
+        if (docCandidates.length !== 1 || recordedCandidates.length !== 1)
+            continue;
+        const recordedName = recordedCandidates[0];
+        consumedDoc.add(docName);
+        consumedRecorded.add(recordedName);
+        out.push({
+            confidence: 'exact', kind: 'changed', via: 'renamed', method: operation.method,
+            path: operation.path, location, before: { field: recordedName, type: docType },
+            after: { field: docName, type: docType }
+        });
+    }
+    // Pass 3 — genuine one-sided fields are change sites, not silence.
+    for (const docName of docOnly) {
+        if (consumedDoc.has(docName))
+            continue;
+        consumedDoc.add(docName);
+        out.push({
+            confidence: 'exact', kind: 'changed', via: 'added-in-document', method: operation.method,
+            path: operation.path, location, before: { field: docName, type: ABSENT },
+            after: { field: docName, type: normalizeType(docFields.get(docName)) }
+        });
+    }
+    for (const recordedName of recordedOnly) {
+        if (consumedRecorded.has(recordedName))
+            continue;
+        consumedRecorded.add(recordedName);
+        out.push({
+            confidence: 'exact', kind: 'changed', via: 'removed-from-document', method: operation.method,
+            path: operation.path, location, before: { field: recordedName, type: recordedNormalized.get(recordedName) },
+            after: { field: recordedName, type: ABSENT }
+        });
+    }
+}
+/** Endpoint-level diff. Both sides parsed; `{id}` and `:id` are normalised to one spelling first. */
+function diffEndpoints(operations, recorded) {
+    const endpoints = [];
+    if (recorded.length === 0)
+        return endpoints;
+    const key = (method, path) => `${method} ${normalizeEndpointPath(path)}`;
+    const recordedKeys = new Set(recorded.map((entry) => key(entry.method, entry.path)));
+    const documentKeys = new Set();
+    for (const operation of operations) {
+        const current = key(operation.method, operation.path);
+        documentKeys.add(current);
+        if (!recordedKeys.has(current)) {
+            endpoints.push({ confidence: 'exact', kind: 'added', method: operation.method, path: operation.path });
+        }
+    }
+    for (const entry of recorded) {
+        if (!documentKeys.has(key(entry.method, entry.path))) {
+            endpoints.push({ confidence: 'exact', kind: 'removed', method: entry.method, path: entry.path });
+        }
+    }
+    return endpoints;
+}
+/**
+ * Why nothing paired, what the convention actually is, and which link is
+ * missing — said with THIS document's own names so the fix is mechanical.
+ * Deliberately no path-based or fuzzy fallback: a confident wrong pairing is
+ * worse than an honest non-pairing, and the Exact label rests on that.
+ */
+function unpairedNote(operations, interfaces) {
+    const operationIds = [
+        ...new Set(operations.map((operation) => operation.operationId).filter((id) => id !== undefined))
+    ];
+    const exampleId = operationIds[0];
+    const convention = exampleId === undefined
+        ? 'this document declares no `operationId`, so the pairing key falls back to `<method><path>`'
+        : `operationId \`${exampleId}\` would pair with an interface named \`${exampleId.charAt(0).toUpperCase()}${exampleId.slice(1)}Response\``;
+    return `0 of ${interfaces.length} recorded interface(s) paired with a document operation, so no field-level exact diff was produced. `
+        + `Pairing is name-only — lowercased, punctuation stripped, one trailing Response/Request/Dto/Payload/Body removed — so ${convention}. `
+        + `Document operationIds: ${summarizeList(operationIds)}. `
+        + `Unpaired interfaces: ${summarizeList(interfaces.map((iface) => iface.name))}. `
+        + 'Rename one side so the two names match; this command will not guess a pairing.';
+}
+export function diffApiDocument(input) {
+    // The doc path is the user's own argument, so a relative one resolves against
+    // the process CWD — the shell convention. `--project` scopes the analysis; it
+    // must NOT re-root the argument, which produced doubled paths such as
+    // `<project>/<project>/docs/api.json`.
+    const projectRoot = resolve(input.projectRoot);
+    const docPath = resolve(input.docPath);
+    const document = loadApiDocument(docPath);
+    const notes = [];
+    const mockPlan = findMockPlan(projectRoot);
+    if (mockPlan === null) {
+        notes.push('no mock-plan.md found under .peaks/_runtime/*/rd/ — mock file paths are unknown.');
+    }
+    const interfaceFiles = findRecordedInterfaceFiles(projectRoot, mockPlan);
+    const interfaces = [];
+    for (const file of interfaceFiles) {
+        try {
+            interfaces.push(...parseRecordedInterfaces(readFileSync(file, 'utf8'), file));
+        }
+        catch (error) {
+            notes.push(`could not read recorded interface file ${toDisplayPath(projectRoot, file)}: ${error.message}`);
+        }
+    }
+    if (interfaces.length === 0) {
+        notes.push('no recorded interfaces found — exact field diff limited to document-internal changes.');
+    }
+    const handoff = findHandoffWithApiMigration(projectRoot);
+    const recordedEndpoints = handoff === null ? [] : parseHandoffEndpoints(readFileSync(handoff, 'utf8'));
+    if (handoff === null) {
+        notes.push('no TXT handoff with an `## API Migration` section found under .peaks/_runtime/*/txt/ — no recorded endpoint list to diff endpoints against.');
+    }
+    else if (recordedEndpoints.length === 0) {
+        notes.push(`the \`## API Migration\` section in ${toDisplayPath(projectRoot, handoff)} lists no \`METHOD /path\` endpoint — no recorded endpoint list to diff endpoints against.`);
+    }
+    // Pairing is by name AND by role. An operation may legitimately pair with two
+    // interfaces — one `...Request` and one `...Response` — so a name collision is
+    // only ambiguous within a single role.
+    const byKey = new Map();
+    for (const iface of interfaces) {
+        const key = pairingKey(iface.name);
+        byKey.set(key, [...(byKey.get(key) ?? []), iface]);
+    }
+    const fields = [];
+    const matchedInterfaces = new Set();
+    const coveredLocations = new Set();
+    const suppressedInterfaces = new Map();
+    const operationsWithRecords = new Set();
+    const pairedWithoutLocation = [];
+    const incompleteLocations = [];
+    const unpairedOperations = [];
+    for (const operation of document.operations) {
+        const candidates = byKey.get(operationKey(operation)) ?? [];
+        if (candidates.length === 0) {
+            unpairedOperations.push(`${operation.method.toUpperCase()} ${operation.path}`);
+            continue;
+        }
+        for (const candidate of candidates)
+            matchedInterfaces.add(candidate);
+        const byRole = new Map();
+        for (const candidate of candidates) {
+            const role = roleOf(candidate.name);
+            byRole.set(role, [...(byRole.get(role) ?? []), candidate]);
+        }
+        const where = `${operation.method.toUpperCase()} ${operation.path}`;
+        for (const [role, list] of byRole) {
+            if (role === 'unknown') {
+                notes.push(`${where}: recorded interface(s) ${list.map((iface) => `\`${iface.name}\``).join(', ')} name neither a request nor a response, so this command cannot tell which part of the operation they describe — pairing refused rather than guessed; their fields are not in the exact diff.`);
+                continue;
+            }
+            if (list.length > 1) {
+                notes.push(`${where}: ${list.length} recorded ${role} interfaces match (${list.map((iface) => `\`${iface.name}\``).join(', ')}) — pairing refused rather than guessed; their fields are not in the exact diff.`);
+                continue;
+            }
+            const iface = list[0];
+            if (iface.incompleteReason !== null) {
+                suppressedInterfaces.set(iface, iface.incompleteReason);
+                continue;
+            }
+            const roleLocations = locationsForRole(operation, role);
+            // A response interface's name carries no status, so with more than one
+            // JSON response body there is no way to know which one it describes.
+            if (role === 'response' && roleLocations.length > 1) {
+                notes.push(`${where}: ${roleLocations.length} response statuses have JSON bodies (${roleLocations.map((location) => location.slice('response.'.length)).join(', ')}) and \`${iface.name}\` names no status, so this command cannot tell which one it describes — pairing refused rather than guessed; its fields are not in the exact diff.`);
+                continue;
+            }
+            operationsWithRecords.add(operation);
+            if (roleLocations.length === 0) {
+                // A pairing that yields no location must still be named, or it is a
+                // silent hole: the interface looks consumed and nothing was diffed.
+                pairedWithoutLocation.push(`${where} (recorded \`${iface.name}\` describes the ${role === 'request' ? 'requestBody' : 'responses'})`);
+                continue;
+            }
+            for (const location of roleLocations) {
+                const label = locationLabel(operation, location);
+                coveredLocations.add(label);
+                // The doc-side half of the inverted rule: a location the DOC reader
+                // could not fully account for is suppressed, because a partial field set
+                // is indistinguishable from a complete one.
+                const issue = operation.locationIssues.get(location);
+                if (issue !== undefined) {
+                    incompleteLocations.push(`${label} (${issue})`);
+                    continue;
+                }
+                compareLocation(operation, location, iface.members, fields);
+            }
+        }
+    }
+    if (interfaces.length > 0) {
+        if (matchedInterfaces.size === 0) {
+            notes.push(unpairedNote(document.operations, interfaces));
+        }
+        else if (unpairedOperations.length > 0) {
+            // A MIX must never be silent: one paired operation used to be enough for
+            // the document to report "(no exact differences)" with no note at all.
+            notes.push(`${unpairedOperations.length} document operation(s) matched no recorded interface, so their fields are not in the exact diff: ${summarizeList(unpairedOperations)}. Interfaces pair by name: operationId \`getUser\` pairs with an interface named \`GetUserResponse\`.`);
+        }
+    }
+    if (incompleteLocations.length > 0) {
+        notes.push(`${incompleteLocations.length} document location(s) could not be fully read, so every exact line for them is suppressed rather than guessed: ${summarizeList(incompleteLocations)}.`);
+    }
+    if (suppressedInterfaces.size > 0) {
+        // The file is named too: a whole-file structural failure otherwise reads as
+        // one stray interface, and the reader has no idea where to look.
+        const listed = [...suppressedInterfaces]
+            .map(([iface, reason]) => `\`${iface.name}\` in ${toDisplayPath(projectRoot, iface.file)} (${reason})`)
+            .join('; ');
+        notes.push(`${suppressedInterfaces.size} recorded interface(s) are not fully readable even though the file parsed, so every exact line they would have produced is suppressed rather than guessed: ${summarizeList([listed])}.`);
+    }
+    if (pairedWithoutLocation.length > 0) {
+        notes.push(`${pairedWithoutLocation.length} recorded interface(s) paired with an operation that declares no matching location, so no exact line was produced for them: ${summarizeList(pairedWithoutLocation)}.`);
+    }
+    if (operationsWithRecords.size > 0) {
+        const uncovered = [];
+        for (const operation of operationsWithRecords) {
+            for (const location of operation.locations.keys()) {
+                // Only locations a body interface can actually describe. Path/query
+                // params are structurally never recorded, so flagging them would fire
+                // on nearly every operation and teach the reader to skip notes.
+                if (location !== 'request' && !location.startsWith('response.'))
+                    continue;
+                if (!coveredLocations.has(locationLabel(operation, location))) {
+                    uncovered.push(locationLabel(operation, location));
+                }
+            }
+        }
+        if (uncovered.length > 0) {
+            notes.push(`${uncovered.length} document location(s) have no recorded interface of the matching role, so no exact line was produced for them: ${summarizeList(uncovered)}.`);
+        }
+    }
+    // Candidate names come from the DIFF, never from "everything not verified
+    // unchanged": grepping a field that did not change is pure noise, and a
+    // section whose every line is noise trains the reader to ignore the section —
+    // the exact failure this feature exists to prevent. A changed field
+    // contributes BOTH spellings, because the old name is what the current code
+    // still says; a one-sided field contributes only the side that exists.
+    const candidateNames = new Set();
+    for (const entry of fields) {
+        if (entry.before.type !== ABSENT)
+            candidateNames.add(entry.before.field);
+        if (entry.after.type !== ABSENT)
+            candidateNames.add(entry.after.field);
+    }
+    const { mentions, truncated, hitsTruncated } = grepCandidateMentions(projectRoot, [...candidateNames], [docPath]);
+    if (truncated) {
+        notes.push(`candidate names capped at ${MAX_CANDIDATE_NAMES}; some changed fields were not name-grepped.`);
+    }
+    if (hitsTruncated) {
+        notes.push('candidate hits are capped per name; some change-site lines were not listed, so treat those lists as examples rather than the full set.');
+    }
+    if (fields.length === 0) {
+        // Only claim "nothing was parsed" when that is actually the case — after a
+        // suppression the interface WAS parsed, and saying otherwise misdirects.
+        notes.push(interfaces.length === 0
+            ? 'no candidate change-sites: change-site lookup needs a parsed recorded interface to know what changed.'
+            : 'no candidate change-sites: no exact field change was produced (see the notes above), so there is nothing to search for.');
+    }
+    else if (mentions.length === 0) {
+        notes.push('name-grep found no mentions of the changed names in this project.');
+    }
+    return {
+        document: {
+            file: toDisplayPath(projectRoot, docPath),
+            openapi: document.openapi,
+            title: document.title ?? null,
+            operationCount: document.operations.length
+        },
+        exact: { endpoints: diffEndpoints(document.operations, recordedEndpoints), fields },
+        candidates: mentions,
+        sources: {
+            mockPlan: mockPlan === null ? null : toDisplayPath(projectRoot, mockPlan),
+            interfaceFiles: interfaceFiles.map((file) => toDisplayPath(projectRoot, file)),
+            handoff: handoff === null ? null : toDisplayPath(projectRoot, handoff),
+            recordedEndpoints: recordedEndpoints.length
+        },
+        notes,
+        notDetectable: NOT_DETECTABLE
+    };
+}
+// ---------------------------------------------------------------------------
+// Text rendering
+// ---------------------------------------------------------------------------
+function renderFieldLine(entry) {
+    const beforeRef = entry.before.field === entry.after.field
+        ? `${entry.location}.${entry.before.field}`
+        : `${entry.location}.${entry.before.field} -> ${entry.location}.${entry.after.field}`;
+    return `  ${'CHANGED'.padEnd(9)} ${entry.method.toUpperCase()} ${entry.path}   ${beforeRef}   ${entry.before.type} -> ${entry.after.type}`;
+}
+export function formatApiDiffText(report) {
+    const lines = [];
+    // The header names the two parsed sides; the parenthetical fixes the direction
+    // of every `before -> after` line, which is otherwise ambiguous.
+    lines.push('Exact — document parsed vs recorded interfaces parsed (CHANGED reads recorded -> document)');
+    if (report.exact.endpoints.length === 0 && report.exact.fields.length === 0) {
+        lines.push('  (no exact differences)');
+    }
+    for (const entry of report.exact.endpoints) {
+        lines.push(`  ${(entry.kind === 'added' ? 'ADDED' : 'REMOVED').padEnd(9)} ${entry.method.toUpperCase()} ${entry.path}`);
+    }
+    for (const entry of report.exact.fields)
+        lines.push(renderFieldLine(entry));
+    for (const note of report.notes)
+        lines.push(`  note: ${note}`);
+    lines.push('');
+    lines.push('Candidate mentions — name-grep, may OVER- and UNDER-report');
+    if (report.candidates.length === 0) {
+        lines.push('  (none)');
+    }
+    for (const mention of report.candidates) {
+        const where = mention.hits.map((hit) => `${hit.file}:${hit.line}`).join('   ');
+        lines.push(`  ${mention.name}   ${where}`);
+    }
+    lines.push('');
+    lines.push('Not detectable by this command');
+    for (const item of report.notDetectable)
+        lines.push(`  - ${item}`);
+    return lines.join('\n');
+}

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

@@ -0,0 +1,116 @@
+/**
+ * S1 / rid=api-diff-report — shared types for `peaks scan api-diff <doc>`
+ * (design `docs/superpowers/specs/2026-09-12-frontend-acl-contract-design.md`
+ * §2.1/§2.3).
+ *
+ * GOVERNING PRINCIPLE (QA repair): exactness requires BOTH sides to be fully
+ * known. Any uncertainty on the recorded side SUPPRESSES the exact claim — it
+ * is not merely annotated. `confidence: 'exact'` is reserved for lines where
+ * both sides were parsed AND the recorded interface was fully readable.
+ */
+/** The honest boundary of the feature. Printed in the output, not just documented. */
+export declare const NOT_DETECTABLE: readonly string[];
+export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/** Rendered type text for the side of a one-sided field, i.e. the field is not there at all. */
+export declare const ABSENT = "(absent)";
+export type Method = (typeof HTTP_METHODS)[number];
+/**
+ * Which half of an operation a recorded interface describes, derived from the
+ * suffix its name carries. A location is only ever diffed against an interface
+ * of the matching role — one shared member map compared against every location
+ * is what produced a Request interface being consumed at a response location.
+ */
+export type InterfaceRole = 'request' | 'response' | 'unknown';
+export type DocOperation = {
+    method: Method;
+    path: string;
+    operationId?: string;
+    /** Ordered `location -> leaf field name -> normalized type text`. */
+    locations: Map<string, Map<string, string>>;
+    /**
+     * `location -> why the DOC reader could not fully account for it`. The same
+     * inverted rule the recorded side gets: a partial field set is
+     * indistinguishable from a complete one, so an unreadable construct suppresses
+     * the location's exact lines instead of being presented as complete.
+     */
+    locationIssues: Map<string, string>;
+};
+export type ParsedDocument = {
+    openapi: string;
+    title?: string;
+    operations: DocOperation[];
+};
+export type RecordedInterface = {
+    name: string;
+    file: string;
+    members: Map<string, string>;
+    /** Non-null when the extractor could not read the full member set — suppresses every exact line for this interface. */
+    incompleteReason: string | null;
+};
+export type RecordedEndpoint = {
+    method: Method;
+    path: string;
+};
+export type EndpointEntry = {
+    confidence: 'exact';
+    kind: 'added' | 'removed';
+    method: Method;
+    path: string;
+};
+export type FieldSide = {
+    field: string;
+    type: string;
+};
+export type FieldEntry = {
+    confidence: 'exact';
+    kind: 'changed';
+    via: 'type-changed' | 'renamed' | 'added-in-document' | 'removed-from-document';
+    method: Method;
+    path: string;
+    location: string;
+    before: FieldSide;
+    after: FieldSide;
+};
+export type CandidateMention = {
+    confidence: 'candidate';
+    name: string;
+    hits: readonly {
+        file: string;
+        line: number;
+    }[];
+};
+export type ApiDiffReport = {
+    document: {
+        file: string;
+        openapi: string;
+        title: string | null;
+        operationCount: number;
+    };
+    exact: {
+        endpoints: readonly EndpointEntry[];
+        fields: readonly FieldEntry[];
+    };
+    candidates: readonly CandidateMention[];
+    sources: {
+        mockPlan: string | null;
+        interfaceFiles: readonly string[];
+        handoff: string | null;
+        recordedEndpoints: number;
+    };
+    notes: readonly string[];
+    notDetectable: readonly string[];
+};
+/** Raised for a non-OpenAPI-3.x input so the CLI can exit non-zero with no diff output. */
+export declare class ApiDiffInputError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Project-relative, forward-slashed path for display.
+ *
+ * Compares path SEGMENTS, not raw `startsWith`: with a naive prefix test a root
+ * of `D:/x` also "contains" `D:/x-archive/docs/api.json`, which then rendered as
+ * the misleading `archive/docs/api.json`.
+ */
+export declare function toDisplayPath(projectRoot: string, file: string): string;

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

@@ -0,0 +1,46 @@
+/**
+ * S1 / rid=api-diff-report — shared types for `peaks scan api-diff <doc>`
+ * (design `docs/superpowers/specs/2026-09-12-frontend-acl-contract-design.md`
+ * §2.1/§2.3).
+ *
+ * GOVERNING PRINCIPLE (QA repair): exactness requires BOTH sides to be fully
+ * known. Any uncertainty on the recorded side SUPPRESSES the exact claim — it
+ * is not merely annotated. `confidence: 'exact'` is reserved for lines where
+ * both sides were parsed AND the recorded interface was fully readable.
+ */
+import { resolve, sep } from 'node:path';
+/** The honest boundary of the feature. Printed in the output, not just documented. */
+export const NOT_DETECTABLE = [
+    'a field whose type is unchanged but whose meaning changed',
+    'a removed endpoint that nothing calls',
+    'drift where this document is stale: types cannot check doc against server'
+];
+export const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+/** Rendered type text for the side of a one-sided field, i.e. the field is not there at all. */
+export const ABSENT = '(absent)';
+/** Raised for a non-OpenAPI-3.x input so the CLI can exit non-zero with no diff output. */
+export class ApiDiffInputError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ApiDiffInputError';
+        this.code = code;
+    }
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Project-relative, forward-slashed path for display.
+ *
+ * Compares path SEGMENTS, not raw `startsWith`: with a naive prefix test a root
+ * of `D:/x` also "contains" `D:/x-archive/docs/api.json`, which then rendered as
+ * the misleading `archive/docs/api.json`.
+ */
+export function toDisplayPath(projectRoot, file) {
+    const rootParts = resolve(projectRoot).split(sep);
+    const fileParts = resolve(file).split(sep);
+    const inside = fileParts.length > rootParts.length
+        && rootParts.every((part, index) => part === fileParts[index]);
+    return (inside ? fileParts.slice(rootParts.length) : fileParts).join('/');
+}

package/dist/services/scan/archetype-service.js

@@ -235,6 +235,25 @@ function decideFrontendOnly(report) {
     }
     return { frontendOnly: false, reason: 'swagger-or-proto-present' };
 }
+/**
+ * Three frontend integration scenarios, from the signals `detected`
+ * already holds. Backend presence uses the SAME triple as
+ * `decideArchetype`'s `hasBackend` (framework OR next API routes OR
+ * backend dirs) rather than `hasBackendFramework` alone: `next` is
+ * deliberately excluded from `backendFrameworks` (:77), so a Next
+ * project with `pages/api` is `legacy-fullstack` there and must not be
+ * `prd-only` here — one report cannot contradict itself.
+ */
+function decideIntegrationMode(report) {
+    const hasBackend = report.detected.hasBackendFramework || report.detected.hasNextApiRoutes || report.detected.backendDirsPresent.length > 0;
+    if (hasBackend) {
+        return { integrationMode: 'full-stack', reason: 'backend-detected' };
+    }
+    if (report.detected.hasSwaggerOrProto) {
+        return { integrationMode: 'prd-plus-interface-doc', reason: 'interface-doc-present' };
+    }
+    return { integrationMode: 'prd-only', reason: 'no-backend-no-interface-doc' };
+}
 export async function scanArchetype(options) {
     const { projectRoot } = options;
     const { exists: hasPackageJson, deps } = await readPackageJsonDeps(projectRoot);
@@ -262,5 +281,12 @@ export async function scanArchetype(options) {
     const { archetype, confidence, signals } = decideArchetype(detected);
     const base = { archetype, confidence, signals, detected };
     const { frontendOnly, reason } = decideFrontendOnly(base);
-    return { ...base, frontendOnly, frontendOnlyReason: reason };
+    const { integrationMode, reason: integrationReason } = decideIntegrationMode(base);
+    return {
+        ...base,
+        frontendOnly,
+        frontendOnlyReason: reason,
+        integrationMode,
+        integrationModeReason: integrationReason
+    };
 }

package/dist/services/scan/existing-system-service.js

@@ -2,6 +2,7 @@ import { readdir, stat } from 'node:fs/promises';
 import { basename, join, relative } from 'node:path';
 import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
 import { scanArchetype } from './archetype-service.js';
+import { scanHookConvention } from './hook-convention-service.js';
 const DEFAULT_MAX_TOKENS = 40;
 const DEFAULT_SAMPLES = 5;
 const COLOR_KEYWORDS = ['color', 'primary', 'success', 'warning', 'error', 'danger', 'info', 'bg', 'background', 'border', 'text'];
@@ -205,14 +206,25 @@ export async function scanExistingSystem(options) {
     const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
     const maxSamples = options.maxSamplesPerKind ?? DEFAULT_SAMPLES;
     const archetypeReport = await scanArchetype({ projectRoot });
+    // Deliberately NOT behind the legacy gate below: the hook convention is read
+    // from file contents whenever a hook directory exists, so a greenfield or
+    // monorepo project adopting the ACL convention still gets it reported.
+    const hookConvention = await scanHookConvention({ projectRoot, hookDirs: HOOK_DIRS });
     if (archetypeReport.archetype === 'greenfield' || archetypeReport.archetype === 'unknown') {
         return {
             archetype: archetypeReport.archetype,
             scanned: false,
             scanSkippedReason: `archetype=${archetypeReport.archetype} — extraction only runs on legacy projects`,
             visualTokens: { colors: [], spacing: [], typography: [], radii: [], sources: [] },
-            conventions: { componentNaming: 'unknown', componentDir: null, serviceDir: null, hookDir: null, samples: [] },
-            inconsistencies: []
+            conventions: {
+                componentNaming: 'unknown',
+                componentDir: null,
+                serviceDir: null,
+                hookDir: null,
+                samples: [],
+                hookConvention
+            },
+            inconsistencies: hookConvention.inconsistencies
         };
     }
     const sources = [];
@@ -293,8 +305,9 @@ export async function scanExistingSystem(options) {
             componentDir,
             serviceDir,
             hookDir,
-            samples
+            samples,
+            hookConvention
         },
-        inconsistencies: findInconsistencies(rawTokens)
+        inconsistencies: [...findInconsistencies(rawTokens), ...hookConvention.inconsistencies]
     };
 }