peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,254 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
+const BACKEND_DEP_NAMES = [
+    'express',
+    'koa',
+    'fastify',
+    '@nestjs/core',
+    '@nestjs/common',
+    'hapi',
+    '@hapi/hapi',
+    'restify',
+    'next' // treated separately for API routes
+];
+const BACKEND_DIR_CANDIDATES = ['server', 'backend', 'api', 'apps/server', 'apps/api', 'packages/server', 'packages/api'];
+const MONOREPO_CONFIG_FILES = ['pnpm-workspace.yaml', 'lerna.json', 'turbo.json', 'nx.json', 'rush.json'];
+const SWAGGER_CANDIDATE_PATHS = [
+    'swagger.json',
+    'swagger.yaml',
+    'openapi.json',
+    'openapi.yaml',
+    'openapi.yml',
+    'docs/swagger.json',
+    'docs/openapi.json',
+    'docs/openapi.yaml'
+];
+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: {} };
+    }
+}
+async function detectBackendFrameworks(deps) {
+    return BACKEND_DEP_NAMES.filter((name) => name !== 'next' && Object.prototype.hasOwnProperty.call(deps, name));
+}
+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;
+}
+async function detectBackendDirs(projectRoot) {
+    const found = [];
+    for (const candidate of BACKEND_DIR_CANDIDATES) {
+        if (await isDirectory(join(projectRoot, candidate))) {
+            found.push(candidate);
+        }
+    }
+    return found;
+}
+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;
+}
+async function detectMonorepoConfigs(projectRoot) {
+    const found = [];
+    for (const file of MONOREPO_CONFIG_FILES) {
+        if (await pathExists(join(projectRoot, file))) {
+            found.push(file);
+        }
+    }
+    return found;
+}
+async function countSrcFiles(projectRoot, max = 500) {
+    const srcDir = join(projectRoot, 'src');
+    if (!(await isDirectory(srcDir))) {
+        return 0;
+    }
+    let count = 0;
+    const queue = [srcDir];
+    while (queue.length > 0 && count < max) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(full);
+            }
+            else if (/\.(tsx?|jsx?|vue|svelte)$/.test(entry.name)) {
+                count += 1;
+                if (count >= max)
+                    break;
+            }
+        }
+    }
+    return count;
+}
+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 / (1000 * 60 * 60 * 24));
+        }
+    }
+    return null;
+}
+function decideArchetype(detected) {
+    const signals = [];
+    const hasBackend = detected.hasBackendFramework || detected.hasNextApiRoutes || detected.backendDirsPresent.length > 0;
+    signals.push({
+        name: 'backend-presence',
+        matched: hasBackend,
+        detail: hasBackend
+            ? [
+                detected.backendFrameworks.length > 0 ? `framework: ${detected.backendFrameworks.join(', ')}` : null,
+                detected.hasNextApiRoutes ? 'next-api-routes' : null,
+                detected.backendDirsPresent.length > 0 ? `dirs: ${detected.backendDirsPresent.join(', ')}` : null
+            ]
+                .filter(Boolean)
+                .join('; ')
+            : 'no backend framework, no next API routes, no backend dirs'
+    });
+    signals.push({
+        name: 'swagger-or-proto',
+        matched: detected.hasSwaggerOrProto,
+        detail: detected.hasSwaggerOrProto ? detected.swaggerPaths.join(', ') : 'no swagger/openapi/proto'
+    });
+    signals.push({
+        name: 'monorepo-config',
+        matched: detected.hasMonorepoConfig,
+        detail: detected.hasMonorepoConfig ? detected.monorepoConfigs.join(', ') : 'no monorepo config'
+    });
+    signals.push({
+        name: 'src-size',
+        matched: detected.srcFileCount >= 20,
+        detail: `${detected.srcFileCount} source files in src/`
+    });
+    signals.push({
+        name: 'lockfile-age',
+        matched: detected.lockfileAgeDays !== null && detected.lockfileAgeDays > 180,
+        detail: detected.lockfileAgeDays === null ? 'no lockfile' : `${detected.lockfileAgeDays} days`
+    });
+    if (!detected.hasPackageJson) {
+        return { archetype: 'unknown', confidence: 'low', signals };
+    }
+    // Monorepo detection runs BEFORE the backend check: a monorepo with
+    // a packages/server dir is a fullstack-monorepo, NOT legacy-fullstack.
+    // Slice 2026-07-15 ice-cola hot-fix: previously a monorepo with a
+    // backend sub-package fell through to `legacy-fullstack` because
+    // `hasBackend` includes `backendDirsPresent.length > 0`, which the
+    // L199 guard above couldn't handle. We now treat `hasMonorepoConfig`
+    // as a top-level classifier: any monorepo with a backend sub-package
+    // is `fullstack-monorepo`; without a backend it is `frontend-monorepo`.
+    if (detected.hasMonorepoConfig) {
+        return {
+            archetype: hasBackend ? 'fullstack-monorepo' : 'frontend-monorepo',
+            confidence: 'high',
+            signals
+        };
+    }
+    if (hasBackend && detected.srcFileCount >= 20) {
+        return { archetype: 'legacy-fullstack', confidence: 'high', signals };
+    }
+    const greenfieldSignals = [
+        detected.srcFileCount < 20,
+        detected.lockfileAgeDays === null || detected.lockfileAgeDays <= 30,
+        !detected.hasSwaggerOrProto
+    ];
+    const greenfieldSignalCount = greenfieldSignals.filter(Boolean).length;
+    // Greenfield must show both a small src AND a fresh/missing lockfile — otherwise an empty-src legacy stub still looks like greenfield.
+    if (!hasBackend && greenfieldSignals[0] === true && greenfieldSignals[1] === true) {
+        return { archetype: 'greenfield', confidence: greenfieldSignalCount === 3 ? 'high' : 'medium', signals };
+    }
+    const legacySignalCount = [
+        !hasBackend,
+        !detected.hasSwaggerOrProto,
+        (detected.lockfileAgeDays !== null && detected.lockfileAgeDays > 180) || detected.srcFileCount >= 20
+    ].filter(Boolean).length;
+    if (!hasBackend && legacySignalCount >= 2) {
+        return { archetype: 'legacy-frontend', confidence: legacySignalCount === 3 ? 'high' : 'medium', signals };
+    }
+    if (hasBackend) {
+        return { archetype: 'legacy-fullstack', confidence: 'medium', signals };
+    }
+    return { archetype: 'unknown', confidence: 'low', signals };
+}
+function decideFrontendOnly(report) {
+    if (report.archetype === 'legacy-frontend' || report.archetype === 'frontend-monorepo') {
+        return { frontendOnly: true, reason: `archetype=${report.archetype}` };
+    }
+    const noBackend = !report.detected.hasBackendFramework && !report.detected.hasNextApiRoutes && report.detected.backendDirsPresent.length === 0;
+    if (noBackend && !report.detected.hasSwaggerOrProto) {
+        return { frontendOnly: true, reason: 'no-backend-no-swagger' };
+    }
+    if (report.detected.hasBackendFramework || report.detected.hasNextApiRoutes || report.detected.backendDirsPresent.length > 0) {
+        return { frontendOnly: false, reason: 'backend-detected' };
+    }
+    return { frontendOnly: false, reason: 'swagger-or-proto-present' };
+}
+export async function scanArchetype(options) {
+    const { projectRoot } = options;
+    const { exists: hasPackageJson, deps } = await readPackageJsonDeps(projectRoot);
+    const backendFrameworks = await detectBackendFrameworks(deps);
+    const hasNext = Object.prototype.hasOwnProperty.call(deps, 'next');
+    const hasNextApiRoutes = await detectNextApiRoutes(projectRoot, hasNext);
+    const backendDirsPresent = await detectBackendDirs(projectRoot);
+    const swaggerPaths = await detectSwagger(projectRoot);
+    const monorepoConfigs = await detectMonorepoConfigs(projectRoot);
+    const srcFileCount = await countSrcFiles(projectRoot);
+    const ageDays = await lockfileAgeDays(projectRoot);
+    const detected = {
+        hasPackageJson,
+        hasBackendFramework: backendFrameworks.length > 0,
+        backendFrameworks,
+        hasSwaggerOrProto: swaggerPaths.length > 0,
+        swaggerPaths,
+        hasMonorepoConfig: monorepoConfigs.length > 0,
+        monorepoConfigs,
+        hasNextApiRoutes,
+        srcFileCount,
+        backendDirsPresent,
+        lockfileAgeDays: ageDays
+    };
+    const { archetype, confidence, signals } = decideArchetype(detected);
+    const base = { archetype, confidence, signals, detected };
+    const { frontendOnly, reason } = decideFrontendOnly(base);
+    return { ...base, frontendOnly, frontendOnlyReason: reason };
+}

package/dist/services/scan/diff-scope-service.d.ts

@@ -0,0 +1,40 @@
+export type ScopePattern = {
+    raw: string;
+    regex: RegExp;
+    line: number;
+};
+export type FileClassification = 'in-scope' | 'out-of-scope-violation' | 'unclassified' | 'auto-allowed';
+export type ClassifiedFile = {
+    path: string;
+    classification: FileClassification;
+    matchedPattern?: string;
+    reason: string;
+};
+export type DiffScopeReport = {
+    ok: boolean;
+    rdArtifactPath: string;
+    inScopePatterns: ScopePattern[];
+    outOfScopePatterns: ScopePattern[];
+    changedFiles: ClassifiedFile[];
+    violations: ClassifiedFile[];
+    unclassified: ClassifiedFile[];
+    gitAvailable: boolean;
+    patternsDeclared: boolean;
+};
+export type DiffScopeError = {
+    kind: 'rd-not-found';
+};
+export type DiffScopeOptions = {
+    projectRoot: string;
+    requestId: string;
+    sessionId?: string;
+    baseRef?: string;
+};
+/**
+ * Convert a simple glob pattern to a regex.
+ * Supports `**` (any path including separators), `*` (one path segment), `?` (single char).
+ * Leading `/` is removed; matching is relative to project root.
+ */
+export declare function globToRegex(pattern: string): RegExp;
+export declare function getDiffVsScope(options: DiffScopeOptions): Promise<DiffScopeReport | DiffScopeError>;
+export declare function isDiffScopeError(value: DiffScopeReport | DiffScopeError): value is DiffScopeError;

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

@@ -0,0 +1,198 @@
+import { execFileSync } from 'node:child_process';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+const RED_LINE_HEADER = /^##\s+Red-line scope\s*$/;
+const IN_SCOPE_SUBHEADER = /^(?:###?\s+)?(?:in[- ]scope|scope|allowed):\s*$/i;
+const OUT_OF_SCOPE_SUBHEADER = /^(?:###?\s+)?(?:out[- ]of[- ]scope|forbidden|excluded|not in scope|do not touch):\s*$/i;
+const OUT_OF_SCOPE_INLINE = /\b(?:out[- ]of[- ]scope|do not modify|do not touch|forbidden|excluded)\b/i;
+const PLACEHOLDER_PATTERNS = [
+    /^<[^>]+>$/, // <placeholder>
+    /^\.{2,}$/, // ...
+    /^(?:in-scope|out-of-scope)\s+(?:files|surfaces)/i // bullet that is the template label, not a real path
+];
+const AUTO_ALLOWED_PATHS = [
+    /^\.peaks\//,
+    /^\.peaks-artifacts\//,
+    /^\.git\//
+];
+const AUTO_ALLOWED_TEST_FILE = /\.(?:test|spec)\.[a-z]+$/i;
+const AUTO_ALLOWED_TEST_DIR = /(?:^|\/)(?:tests?|__tests__|__mocks__|test|spec)\//;
+function isPlaceholder(text) {
+    return PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(text));
+}
+function escapeRegex(text) {
+    return text.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Convert a simple glob pattern to a regex.
+ * Supports `**` (any path including separators), `*` (one path segment), `?` (single char).
+ * Leading `/` is removed; matching is relative to project root.
+ */
+export function globToRegex(pattern) {
+    const trimmed = pattern.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+    let body = '';
+    let i = 0;
+    while (i < trimmed.length) {
+        const ch = trimmed[i] ?? '';
+        if (ch === '*') {
+            if (trimmed[i + 1] === '*') {
+                body += '.*';
+                i += 2;
+                // Skip following slash if any (since '**/' should match zero or more dirs)
+                if (trimmed[i] === '/')
+                    i += 1;
+            }
+            else {
+                body += '[^/]*';
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === '?') {
+            body += '[^/]';
+            i += 1;
+            continue;
+        }
+        body += escapeRegex(ch);
+        i += 1;
+    }
+    // If the pattern ends with no trailing slash and no extension wildcard, also allow it to match files under the path (treat as dir prefix)
+    // E.g. `src/services/login` should match `src/services/login/handler.ts`.
+    body = (!trimmed.includes("*") && !trimmed.includes("?") && !trimmed.includes("."))
+        ? `${body}(?:/.*)?`
+        : body;
+    return new RegExp(`^${body}$`);
+}
+function classifyPatternLine(raw) {
+    // Strip leading "- ", "* ", numbered list, or trailing comments.
+    const cleaned = raw.replace(/^\s*[-*+]\s*/, '').replace(/^\s*\d+\.\s*/, '').trim();
+    if (cleaned.length === 0)
+        return { pattern: null };
+    if (isPlaceholder(cleaned))
+        return { pattern: null };
+    // Take the first word/path-like token before whitespace or backticks.
+    // If the line wraps a path in backticks, extract it; otherwise take the whole line.
+    const backtickMatch = /`([^`]+)`/.exec(cleaned);
+    if (backtickMatch !== null && backtickMatch[1] !== undefined) {
+        return { pattern: backtickMatch[1].trim() };
+    }
+    // If the cleaned line is just a path-ish token, take it as-is.
+    if (/^[\w./*?{}[\]@-]+$/.test(cleaned)) {
+        return { pattern: cleaned };
+    }
+    // Otherwise the bullet is descriptive prose (e.g. "do not touch payment module"); skip.
+    return { pattern: null };
+}
+function parseRedLineScope(rdBody) {
+    const lines = rdBody.split(/\r?\n/);
+    let inSection = false;
+    let mode = 'unspecified';
+    const inScope = [];
+    const outOfScope = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        if (!inSection) {
+            if (RED_LINE_HEADER.test(raw)) {
+                inSection = true;
+            }
+            continue;
+        }
+        if (/^##\s/.test(raw))
+            break; // next H2
+        if (IN_SCOPE_SUBHEADER.test(raw.trim())) {
+            mode = 'in';
+            continue;
+        }
+        if (OUT_OF_SCOPE_SUBHEADER.test(raw.trim())) {
+            mode = 'out';
+            continue;
+        }
+        const { pattern } = classifyPatternLine(raw);
+        if (pattern === null)
+            continue;
+        const target = mode === 'out' || (mode === 'unspecified' && OUT_OF_SCOPE_INLINE.test(raw))
+            ? outOfScope
+            : inScope;
+        target.push({ raw: pattern, regex: globToRegex(pattern), line: i + 1 });
+    }
+    const declared = inScope.length > 0 || outOfScope.length > 0;
+    return { inScope, outOfScope, declared };
+}
+function tryGitChangedFiles(projectRoot, baseRef) {
+    try {
+        const trackedRaw = execFileSync('git', ['-C', projectRoot, 'diff', '--name-only', baseRef], { encoding: 'utf8' });
+        const tracked = trackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const untrackedRaw = execFileSync('git', ['-C', projectRoot, 'ls-files', '--others', '--exclude-standard'], { encoding: 'utf8' });
+        const untracked = untrackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        return { ok: true, files: Array.from(new Set([...tracked, ...untracked])) };
+    }
+    catch {
+        return { ok: false, files: [] };
+    }
+}
+function isAutoAllowed(path) {
+    if (AUTO_ALLOWED_PATHS.some((pattern) => pattern.test(path)))
+        return true;
+    if (AUTO_ALLOWED_TEST_FILE.test(path))
+        return true;
+    if (AUTO_ALLOWED_TEST_DIR.test(path))
+        return true;
+    return false;
+}
+function classifyFile(path, inScope, outOfScope) {
+    if (isAutoAllowed(path)) {
+        return { classification: 'auto-allowed', reason: 'Auto-allowed (test, mock, or Peaks artifact path)' };
+    }
+    const outMatch = outOfScope.find((pattern) => pattern.regex.test(path));
+    if (outMatch !== undefined) {
+        return { classification: 'out-of-scope-violation', matchedPattern: outMatch.raw, reason: `Matches explicit out-of-scope pattern "${outMatch.raw}"` };
+    }
+    const inMatch = inScope.find((pattern) => pattern.regex.test(path));
+    if (inMatch !== undefined) {
+        return { classification: 'in-scope', matchedPattern: inMatch.raw, reason: `Matches in-scope pattern "${inMatch.raw}"` };
+    }
+    return { classification: 'unclassified', reason: 'Does not match any declared scope pattern' };
+}
+export async function getDiffVsScope(options) {
+    const baseRef = options.baseRef ?? 'HEAD';
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: 'rd',
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const rdArtifact = await showRequestArtifact(showOptions);
+    if (rdArtifact === null) {
+        return { kind: 'rd-not-found' };
+    }
+    const { inScope, outOfScope, declared } = parseRedLineScope(rdArtifact.content);
+    const { ok: gitAvailable, files } = tryGitChangedFiles(options.projectRoot, baseRef);
+    const changedFiles = files.map((path) => {
+        const { classification, matchedPattern, reason } = classifyFile(path, inScope, outOfScope);
+        const entry = { path, classification, reason };
+        if (matchedPattern !== undefined) {
+            entry.matchedPattern = matchedPattern;
+        }
+        return entry;
+    });
+    const violations = changedFiles.filter((file) => file.classification === 'out-of-scope-violation');
+    const unclassified = changedFiles.filter((file) => file.classification === 'unclassified');
+    // ok if patterns are declared AND no violations AND no unclassified non-trivial files.
+    // If patterns were NOT declared, treat as a warning (ok=false but with a clear "patterns missing" reason).
+    const ok = gitAvailable && declared && violations.length === 0 && unclassified.length === 0;
+    return {
+        ok,
+        rdArtifactPath: rdArtifact.path,
+        inScopePatterns: inScope,
+        outOfScopePatterns: outOfScope,
+        changedFiles,
+        violations,
+        unclassified,
+        gitAvailable,
+        patternsDeclared: declared
+    };
+}
+export function isDiffScopeError(value) {
+    return value.kind !== undefined;
+}

package/dist/services/scan/existing-system-service.d.ts

@@ -0,0 +1,7 @@
+import type { ExistingSystemReport } from './scan-types.js';
+export type ExistingSystemScanOptions = {
+    projectRoot: string;
+    maxTokens?: number;
+    maxSamplesPerKind?: number;
+};
+export declare function scanExistingSystem(options: ExistingSystemScanOptions): Promise<ExistingSystemReport>;