peaks-loop 4.0.54 → 4.1.0

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

@@ -77,8 +77,14 @@ function compareLocation(operation, location, members, out) {
         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 }
+                confidence: 'exact',
+                kind: 'changed',
+                via: 'type-changed',
+                method: operation.method,
+                path: operation.path,
+                location,
+                before: { field: name, type: before },
+                after: { field: name, type: after }
             });
         }
     }
@@ -99,8 +105,13 @@ function compareLocation(operation, location, members, out) {
         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 },
+            confidence: 'exact',
+            kind: 'changed',
+            via: 'renamed',
+            method: operation.method,
+            path: operation.path,
+            location,
+            before: { field: recordedName, type: docType },
             after: { field: docName, type: docType }
         });
     }
@@ -110,8 +121,13 @@ function compareLocation(operation, location, members, out) {
             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 },
+            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)) }
         });
     }
@@ -120,8 +136,13 @@ function compareLocation(operation, location, members, out) {
             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) },
+            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 }
         });
     }
@@ -138,12 +159,22 @@ function diffEndpoints(operations, recorded) {
         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 });
+            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 });
+            endpoints.push({
+                confidence: 'exact',
+                kind: 'removed',
+                method: entry.method,
+                path: entry.path
+            });
         }
     }
     return endpoints;
@@ -156,17 +187,19 @@ function diffEndpoints(operations, recorded) {
  */
 function unpairedNote(operations, interfaces) {
     const operationIds = [
-        ...new Set(operations.map((operation) => operation.operationId).filter((id) => id !== undefined))
+        ...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.';
+    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

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

@@ -33,7 +33,16 @@ export const NOT_DETECTABLE = [
     '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'];
+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. */
@@ -58,7 +67,7 @@ export function isRecord(value) {
 export function toDisplayPath(projectRoot, file) {
     const rootParts = safeRealpath(projectRoot).split(sep);
     const fileParts = safeRealpath(file).split(sep);
-    const inside = fileParts.length > rootParts.length
-        && rootParts.every((part, index) => part === fileParts[index]);
+    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/api-surface-helpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `src/services/scan/api-surface-helpers.ts`
+ *
+ * Small pure helpers (line lookup, name de-duplication, include-dir
+ * parsing) extracted verbatim from `api-surface-service.ts` (wave 2,
+ * file-size cap campaign) so the scanner stays under the 300 raw-line
+ * cap. Mechanical move only; these were module-private before the move.
+ */
+export declare function lineOf(content: string, matchIndex: number): number;
+export declare function uniqueByName<T extends {
+    name: string;
+}>(items: T[]): T[];
+export declare function parseIncludeDirs(raw: string | undefined): string[];

package/dist/services/scan/api-surface-helpers.js

@@ -0,0 +1,31 @@
+/**
+ * `src/services/scan/api-surface-helpers.ts`
+ *
+ * Small pure helpers (line lookup, name de-duplication, include-dir
+ * parsing) extracted verbatim from `api-surface-service.ts` (wave 2,
+ * file-size cap campaign) so the scanner stays under the 300 raw-line
+ * cap. Mechanical move only; these were module-private before the move.
+ */
+const DEFAULT_DIRS = ['src/cli', 'src/services'];
+export function lineOf(content, matchIndex) {
+    return content.slice(0, matchIndex).split('\n').length;
+}
+export function uniqueByName(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (seen.has(item.name))
+            continue;
+        seen.add(item.name);
+        out.push(item);
+    }
+    return out;
+}
+export function parseIncludeDirs(raw) {
+    if (!raw)
+        return [...DEFAULT_DIRS];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}

package/dist/services/scan/api-surface-service.d.ts

@@ -8,51 +8,8 @@
  * Pattern follows `libraries-service.ts` (readFileSync + readdir; pure
  * data shape; no AST parsing). karpathy §2: minimum code, no abstractions.
  */
-export type ApiSurfaceOptions = {
-    projectRoot: string;
-    /** Maximum entries per kind in output (after filtering). */
-    maxPerKind?: number;
-    /** Comma-separated globs (substring match) to limit the walk. */
-    includeDirs?: string;
-};
-export type CliEntry = {
-    name: string;
-    description: string;
-    sourceFile: string;
-};
-export type ServiceEntry = {
-    name: string;
-    kind: 'function' | 'class' | 'const';
-    isAsync: boolean;
-    sourceFile: string;
-    line: number;
-};
-export type TypeEntry = {
-    name: string;
-    kind: 'interface' | 'type' | 'enum';
-    sourceFile: string;
-    line: number;
-};
-export type ConstantEntry = {
-    name: string;
-    sourceFile: string;
-    line: number;
-};
-export type ApiSurfaceReport = {
-    projectRoot: string;
-    scannedAt: string;
-    counts: {
-        cli: number;
-        service: number;
-        type: number;
-        constant: number;
-    };
-    cli: CliEntry[];
-    service: ServiceEntry[];
-    type: TypeEntry[];
-    constant: ConstantEntry[];
-    warnings: string[];
-};
+import type { ApiSurfaceOptions, ApiSurfaceReport, CliEntry, ConstantEntry, ServiceEntry, TypeEntry } from './api-surface-types.js';
+export type { ApiSurfaceOptions, CliEntry, ServiceEntry, TypeEntry, ConstantEntry, ApiSurfaceReport };
 /**
  * Scan the project for API surfaces. Read-only. Never throws; failures
  * surface as warnings in the report.

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

@@ -10,7 +10,7 @@
  */
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-const DEFAULT_DIRS = ['src/cli', 'src/services'];
+import { lineOf, parseIncludeDirs, uniqueByName } from './api-surface-helpers.js';
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
 const COMMAND_RE = /\.command\(\s*['"]([^'"]+)['"]\s*\)\s*\.description\(\s*['"]([^'"]+)['"]/g;
 const EXPORT_FUNCTION_RE = /^export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm;
@@ -57,28 +57,6 @@ async function isDir(p) {
         return false;
     }
 }
-function lineOf(content, matchIndex) {
-    return content.slice(0, matchIndex).split('\n').length;
-}
-function uniqueByName(items) {
-    const seen = new Set();
-    const out = [];
-    for (const item of items) {
-        if (seen.has(item.name))
-            continue;
-        seen.add(item.name);
-        out.push(item);
-    }
-    return out;
-}
-function parseIncludeDirs(raw) {
-    if (!raw)
-        return [...DEFAULT_DIRS];
-    return raw
-        .split(',')
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0);
-}
 /**
  * Scan the project for API surfaces. Read-only. Never throws; failures
  * surface as warnings in the report.
@@ -114,8 +92,14 @@ export async function scanApiSurface(options) {
             }
         }
         if (rel.startsWith('src/services/')) {
-            for (const re of [EXPORT_FUNCTION_RE, EXPORT_CLASS_RE, EXPORT_CONST_RE,
-                EXPORT_INTERFACE_RE, EXPORT_TYPE_RE, EXPORT_ENUM_RE]) {
+            for (const re of [
+                EXPORT_FUNCTION_RE,
+                EXPORT_CLASS_RE,
+                EXPORT_CONST_RE,
+                EXPORT_INTERFACE_RE,
+                EXPORT_TYPE_RE,
+                EXPORT_ENUM_RE
+            ]) {
                 re.lastIndex = 0;
             }
             let m;
@@ -208,7 +192,12 @@ export function formatApiSurfaceMarkdown(report, opts = {}) {
     ];
     const arrays = [report.cli, report.service, report.type, report.constant];
     const trunc = truncated
-        ? [truncated.cli - report.cli.length, truncated.service - report.service.length, truncated.type - report.type.length, truncated.constant - report.constant.length]
+        ? [
+            truncated.cli - report.cli.length,
+            truncated.service - report.service.length,
+            truncated.type - report.type.length,
+            truncated.constant - report.constant.length
+        ]
         : [0, 0, 0, 0];
     for (let i = 0; i < sections.length; i++) {
         const [title, count, fmt] = sections[i];

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

@@ -0,0 +1,54 @@
+/**
+ * `src/services/scan/api-surface-types.ts`
+ *
+ * Report and entry type declarations extracted verbatim from
+ * `api-surface-service.ts` (wave 2, file-size cap campaign) so the
+ * scanner stays under the 300 raw-line cap. Mechanical move only —
+ * `api-surface-service.ts` re-exports every type from its original
+ * path.
+ */
+export type ApiSurfaceOptions = {
+    projectRoot: string;
+    /** Maximum entries per kind in output (after filtering). */
+    maxPerKind?: number;
+    /** Comma-separated globs (substring match) to limit the walk. */
+    includeDirs?: string;
+};
+export type CliEntry = {
+    name: string;
+    description: string;
+    sourceFile: string;
+};
+export type ServiceEntry = {
+    name: string;
+    kind: 'function' | 'class' | 'const';
+    isAsync: boolean;
+    sourceFile: string;
+    line: number;
+};
+export type TypeEntry = {
+    name: string;
+    kind: 'interface' | 'type' | 'enum';
+    sourceFile: string;
+    line: number;
+};
+export type ConstantEntry = {
+    name: string;
+    sourceFile: string;
+    line: number;
+};
+export type ApiSurfaceReport = {
+    projectRoot: string;
+    scannedAt: string;
+    counts: {
+        cli: number;
+        service: number;
+        type: number;
+        constant: number;
+    };
+    cli: CliEntry[];
+    service: ServiceEntry[];
+    type: TypeEntry[];
+    constant: ConstantEntry[];
+    warnings: string[];
+};

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

@@ -0,0 +1,10 @@
+/**
+ * `src/services/scan/api-surface-types.ts`
+ *
+ * Report and entry type declarations extracted verbatim from
+ * `api-surface-service.ts` (wave 2, file-size cap campaign) so the
+ * scanner stays under the 300 raw-line cap. Mechanical move only —
+ * `api-surface-service.ts` re-exports every type from its original
+ * path.
+ */
+export {};

package/dist/services/scan/archetype-detection.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Archetype detection primitives (B wave-3 file-size split).
+ *
+ * Extracted verbatim from `archetype-service.ts`: the backend /
+ * monorepo / swagger candidate lists, the archetype-detection
+ * thresholds (PRD-002b slice 2), and the async detectors that probe a
+ * project root for those signals. Values are bytewise-identical to
+ * the original literals. `archetype-service.ts` keeps the decision
+ * functions (`decideArchetype`, `decideFrontendOnly`,
+ * `decideIntegrationMode`) and the public `scanArchetype` entry; the
+ * `frontendOnly` / `frontendOnlyReason` output contract is unchanged.
+ */
+export declare const BACKEND_DEP_NAMES: string[];
+export declare const BACKEND_DIR_CANDIDATES: string[];
+export declare const MONOREPO_CONFIG_FILES: string[];
+/**
+ * PRD-002b slice 2 — extract archetype-detection thresholds. Names
+ * describe the meaning; values are bytewise-identical to the original
+ * literals (signaled in commit message).
+ */
+export declare const MS_PER_DAY: number;
+export declare const GREENFIELD_MAX_SRC_FILES = 20;
+export declare const LEGACY_MIN_SRC_FILES = 20;
+export declare const LOCKFILE_STALE_DAYS = 180;
+export declare const GREENFIELD_MAX_LOCKFILE_DAYS = 30;
+export declare const HIGH_CONFIDENCE_SIGNAL_COUNT = 3;
+export declare const SWAGGER_CANDIDATE_PATHS: string[];
+export declare function readPackageJsonDeps(projectRoot: string): Promise<{
+    exists: boolean;
+    deps: Record<string, string>;
+}>;
+export declare function detectBackendFrameworks(deps: Record<string, string>): Promise<string[]>;
+export declare function detectNextApiRoutes(projectRoot: string, hasNext: boolean): Promise<boolean>;
+export declare function detectBackendDirs(projectRoot: string): Promise<string[]>;
+export declare function detectSwagger(projectRoot: string): Promise<string[]>;
+export declare function detectMonorepoConfigs(projectRoot: string): Promise<string[]>;
+export declare function lockfileAgeDays(projectRoot: string): Promise<number | null>;

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

@@ -0,0 +1,142 @@
+/**
+ * Archetype detection primitives (B wave-3 file-size split).
+ *
+ * Extracted verbatim from `archetype-service.ts`: the backend /
+ * monorepo / swagger candidate lists, the archetype-detection
+ * thresholds (PRD-002b slice 2), and the async detectors that probe a
+ * project root for those signals. Values are bytewise-identical to
+ * the original literals. `archetype-service.ts` keeps the decision
+ * functions (`decideArchetype`, `decideFrontendOnly`,
+ * `decideIntegrationMode`) and the public `scanArchetype` entry; the
+ * `frontendOnly` / `frontendOnlyReason` output contract is unchanged.
+ */
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
+export const BACKEND_DEP_NAMES = [
+    'express',
+    'koa',
+    'fastify',
+    '@nestjs/core',
+    '@nestjs/common',
+    'hapi',
+    '@hapi/hapi',
+    'restify',
+    'next' // treated separately for API routes
+];
+export const BACKEND_DIR_CANDIDATES = [
+    'server',
+    'backend',
+    'api',
+    'apps/server',
+    'apps/api',
+    'packages/server',
+    'packages/api'
+];
+export const MONOREPO_CONFIG_FILES = [
+    'pnpm-workspace.yaml',
+    'lerna.json',
+    'turbo.json',
+    'nx.json',
+    'rush.json'
+];
+/**
+ * PRD-002b slice 2 — extract archetype-detection thresholds. Names
+ * describe the meaning; values are bytewise-identical to the original
+ * literals (signaled in commit message).
+ */
+// eslint-disable-next-line no-magic-numbers -- canonical ms-per-day math (1000 * 60s * 60min * 24h)
+export const MS_PER_DAY = 1000 * 60 * 60 * 24;
+export const GREENFIELD_MAX_SRC_FILES = 20;
+export const LEGACY_MIN_SRC_FILES = 20;
+export const LOCKFILE_STALE_DAYS = 180;
+export const GREENFIELD_MAX_LOCKFILE_DAYS = 30;
+export const HIGH_CONFIDENCE_SIGNAL_COUNT = 3;
+export const SWAGGER_CANDIDATE_PATHS = [
+    'swagger.json',
+    'swagger.yaml',
+    'openapi.json',
+    'openapi.yaml',
+    'openapi.yml',
+    'docs/swagger.json',
+    'docs/openapi.json',
+    'docs/openapi.yaml'
+];
+export async function readPackageJsonDeps(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!(await pathExists(pkgPath))) {
+        return { exists: false, deps: {} };
+    }
+    try {
+        const raw = await readText(pkgPath);
+        const parsed = JSON.parse(raw);
+        const deps = {
+            ...(parsed.dependencies ?? {}),
+            ...(parsed.devDependencies ?? {}),
+            ...(parsed.peerDependencies ?? {}),
+            ...(parsed.optionalDependencies ?? {})
+        };
+        return { exists: true, deps };
+    }
+    catch {
+        return { exists: true, deps: {} };
+    }
+}
+export async function detectBackendFrameworks(deps) {
+    return BACKEND_DEP_NAMES.filter((name) => name !== 'next' && Object.prototype.hasOwnProperty.call(deps, name));
+}
+export async function detectNextApiRoutes(projectRoot, hasNext) {
+    if (!hasNext) {
+        return false;
+    }
+    const candidates = ['pages/api', 'src/pages/api', 'app/api', 'src/app/api'];
+    for (const candidate of candidates) {
+        if (await isDirectory(join(projectRoot, candidate))) {
+            return true;
+        }
+    }
+    return false;
+}
+export async function detectBackendDirs(projectRoot) {
+    const found = [];
+    for (const candidate of BACKEND_DIR_CANDIDATES) {
+        if (await isDirectory(join(projectRoot, candidate))) {
+            found.push(candidate);
+        }
+    }
+    return found;
+}
+export async function detectSwagger(projectRoot) {
+    const found = [];
+    for (const candidate of SWAGGER_CANDIDATE_PATHS) {
+        if (await pathExists(join(projectRoot, candidate))) {
+            found.push(candidate);
+        }
+    }
+    const protoDir = join(projectRoot, 'proto');
+    if (await isDirectory(protoDir)) {
+        found.push('proto/');
+    }
+    return found;
+}
+export async function detectMonorepoConfigs(projectRoot) {
+    const found = [];
+    for (const file of MONOREPO_CONFIG_FILES) {
+        if (await pathExists(join(projectRoot, file))) {
+            found.push(file);
+        }
+    }
+    return found;
+}
+export async function lockfileAgeDays(projectRoot) {
+    const candidates = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb'];
+    for (const candidate of candidates) {
+        const full = join(projectRoot, candidate);
+        if (await pathExists(full)) {
+            const stats = await stat(full);
+            const ageMs = Date.now() - stats.mtimeMs;
+            return Math.floor(ageMs / MS_PER_DAY);
+        }
+    }
+    return null;
+}