peaks-loop 4.0.0-beta.2 → 4.0.0-beta.20

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/existing-system-service.js

@@ -0,0 +1,300 @@
+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';
+const DEFAULT_MAX_TOKENS = 40;
+const DEFAULT_SAMPLES = 5;
+const COLOR_KEYWORDS = ['color', 'primary', 'success', 'warning', 'error', 'danger', 'info', 'bg', 'background', 'border', 'text'];
+const SPACING_KEYWORDS = ['spacing', 'gap', 'padding', 'margin', 'size'];
+const TYPO_KEYWORDS = ['font', 'text-size', 'line-height', 'letter-spacing', 'heading'];
+const RADIUS_KEYWORDS = ['radius', 'rounded'];
+const STYLE_DIRS = ['src/styles', 'src/style', 'styles', 'src/assets/styles', 'src/theme', 'theme'];
+const COMPONENT_DIRS = ['src/components', 'src/Components', 'components'];
+const SERVICE_DIRS = ['src/services', 'src/service', 'src/api', 'src/apis'];
+const HOOK_DIRS = ['src/hooks', 'src/hook', 'src/composables'];
+function classifyToken(name) {
+    const lower = name.toLowerCase();
+    if (RADIUS_KEYWORDS.some((kw) => lower.includes(kw)))
+        return 'radius';
+    if (TYPO_KEYWORDS.some((kw) => lower.includes(kw)))
+        return 'typography';
+    if (SPACING_KEYWORDS.some((kw) => lower.includes(kw)))
+        return 'spacing';
+    if (COLOR_KEYWORDS.some((kw) => lower.includes(kw)))
+        return 'color';
+    return null;
+}
+function parseLessOrSassVars(content, sourceRel) {
+    const tokens = [];
+    // Match `@var: value;` (Less) or `$var: value;` (Sass)
+    const regex = /^\s*[@$]([a-zA-Z][\w-]*)\s*:\s*([^;]+);/gm;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const [, rawName, rawValue] = match;
+        if (rawName === undefined || rawValue === undefined)
+            continue;
+        tokens.push({ name: rawName, value: rawValue.trim(), source: sourceRel });
+    }
+    return tokens;
+}
+function parseCssVars(content, sourceRel) {
+    const tokens = [];
+    const regex = /--([a-zA-Z][\w-]*)\s*:\s*([^;]+);/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const [, rawName, rawValue] = match;
+        if (rawName === undefined || rawValue === undefined)
+            continue;
+        tokens.push({ name: `--${rawName}`, value: rawValue.trim(), source: sourceRel });
+    }
+    return tokens;
+}
+async function walkStyleFiles(projectRoot) {
+    const found = [];
+    for (const candidate of STYLE_DIRS) {
+        const full = join(projectRoot, candidate);
+        if (!(await isDirectory(full)))
+            continue;
+        const queue = [full];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current === undefined)
+                break;
+            let entries;
+            try {
+                entries = await readdir(current, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                    continue;
+                const entryPath = join(current, entry.name);
+                if (entry.isDirectory()) {
+                    queue.push(entryPath);
+                }
+                else if (/\.(less|scss|sass|css)$/i.test(entry.name)) {
+                    found.push(entryPath);
+                }
+            }
+        }
+    }
+    return found;
+}
+async function extractTailwindTokens(projectRoot) {
+    const candidates = ['tailwind.config.js', 'tailwind.config.ts', 'tailwind.config.cjs', 'tailwind.config.mjs'];
+    for (const candidate of candidates) {
+        const full = join(projectRoot, candidate);
+        if (await pathExists(full)) {
+            const content = await readText(full);
+            const tokens = [];
+            // Heuristic: extract keys under theme.extend.* via simple regex.
+            const colorBlock = /colors\s*:\s*\{([\s\S]*?)\}/.exec(content);
+            if (colorBlock?.[1] !== undefined) {
+                const colorRegex = /([a-zA-Z_][\w-]*)\s*:\s*['"`]([^'"`]+)['"`]/g;
+                let match;
+                while ((match = colorRegex.exec(colorBlock[1])) !== null) {
+                    const [, name, value] = match;
+                    if (name !== undefined && value !== undefined) {
+                        tokens.push({ name, value, source: candidate });
+                    }
+                }
+            }
+            return { tokens, source: { path: candidate, kind: 'tailwind-config' } };
+        }
+    }
+    return { tokens: [], source: null };
+}
+async function listFilesByMtime(dir, exts, max) {
+    if (!(await isDirectory(dir)))
+        return [];
+    const collected = [];
+    const queue = [dir];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        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 (exts.test(entry.name)) {
+                try {
+                    const stats = await stat(full);
+                    collected.push({ path: full, mtimeMs: stats.mtimeMs });
+                }
+                catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                    // skip unreadable
+                }
+            }
+        }
+    }
+    collected.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return collected.slice(0, max);
+}
+function classifyComponentNaming(samples) {
+    if (samples.length === 0)
+        return 'unknown';
+    let pascal = 0;
+    let kebab = 0;
+    for (const sample of samples) {
+        const name = basename(sample.path).replace(/\.[^.]+$/, '');
+        if (/^[A-Z][a-zA-Z0-9]*$/.test(name))
+            pascal += 1;
+        else if (/^[a-z][a-z0-9-]*$/.test(name))
+            kebab += 1;
+    }
+    if (pascal > 0 && kebab === 0)
+        return 'PascalCase';
+    if (kebab > 0 && pascal === 0)
+        return 'kebab-case';
+    if (pascal > 0 || kebab > 0)
+        return 'mixed';
+    return 'unknown';
+}
+async function firstExistingDir(projectRoot, candidates) {
+    for (const candidate of candidates) {
+        if (await isDirectory(join(projectRoot, candidate))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function dedupeTokens(tokens, max) {
+    const seen = new Set();
+    const out = [];
+    for (const token of tokens) {
+        const key = `${token.name}=${token.value}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(token);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+function findInconsistencies(tokens) {
+    const issues = [];
+    const byName = new Map();
+    for (const token of tokens) {
+        const set = byName.get(token.name) ?? new Set();
+        set.add(token.value);
+        byName.set(token.name, set);
+    }
+    for (const [name, values] of byName.entries()) {
+        if (values.size > 1) {
+            issues.push(`token "${name}" has ${values.size} different values across sources: ${[...values].join(' | ')}`);
+        }
+    }
+    return issues;
+}
+export async function scanExistingSystem(options) {
+    const { projectRoot } = options;
+    const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const maxSamples = options.maxSamplesPerKind ?? DEFAULT_SAMPLES;
+    const archetypeReport = await scanArchetype({ projectRoot });
+    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: []
+        };
+    }
+    const sources = [];
+    const rawTokens = [];
+    const styleFiles = await walkStyleFiles(projectRoot);
+    for (const file of styleFiles) {
+        const content = await readText(file);
+        const rel = relative(projectRoot, file).split(/[\\/]/).join('/');
+        if (/\.less$/i.test(file)) {
+            const lessTokens = parseLessOrSassVars(content, rel);
+            if (lessTokens.length > 0) {
+                sources.push({ path: rel, kind: 'less-vars' });
+                rawTokens.push(...lessTokens);
+            }
+        }
+        else if (/\.s[ac]ss$/i.test(file)) {
+            const sassTokens = parseLessOrSassVars(content, rel);
+            if (sassTokens.length > 0) {
+                sources.push({ path: rel, kind: 'sass-vars' });
+                rawTokens.push(...sassTokens);
+            }
+        }
+        const cssVars = parseCssVars(content, rel);
+        if (cssVars.length > 0) {
+            sources.push({ path: rel, kind: 'css-vars' });
+            rawTokens.push(...cssVars);
+        }
+    }
+    const tailwind = await extractTailwindTokens(projectRoot);
+    if (tailwind.source !== null) {
+        sources.push(tailwind.source);
+        rawTokens.push(...tailwind.tokens);
+    }
+    const colors = [];
+    const spacing = [];
+    const typography = [];
+    const radii = [];
+    for (const token of rawTokens) {
+        const category = classifyToken(token.name);
+        if (category === 'color')
+            colors.push(token);
+        else if (category === 'spacing')
+            spacing.push(token);
+        else if (category === 'typography')
+            typography.push(token);
+        else if (category === 'radius')
+            radii.push(token);
+    }
+    const componentDir = await firstExistingDir(projectRoot, COMPONENT_DIRS);
+    const serviceDir = await firstExistingDir(projectRoot, SERVICE_DIRS);
+    const hookDir = await firstExistingDir(projectRoot, HOOK_DIRS);
+    const componentSamples = componentDir !== null
+        ? await listFilesByMtime(join(projectRoot, componentDir), /\.(tsx|jsx|vue|svelte)$/i, maxSamples)
+        : [];
+    const serviceSamples = serviceDir !== null
+        ? await listFilesByMtime(join(projectRoot, serviceDir), /\.(ts|js)$/i, maxSamples)
+        : [];
+    const hookSamples = hookDir !== null
+        ? await listFilesByMtime(join(projectRoot, hookDir), /\.(ts|js)$/i, maxSamples)
+        : [];
+    const samples = [
+        ...componentSamples.map((sample) => ({ path: relative(projectRoot, sample.path).split(/[\\/]/).join('/'), kind: 'component' })),
+        ...serviceSamples.map((sample) => ({ path: relative(projectRoot, sample.path).split(/[\\/]/).join('/'), kind: 'service' })),
+        ...hookSamples.map((sample) => ({ path: relative(projectRoot, sample.path).split(/[\\/]/).join('/'), kind: 'hook' }))
+    ];
+    return {
+        archetype: archetypeReport.archetype,
+        scanned: true,
+        visualTokens: {
+            colors: dedupeTokens(colors, maxTokens),
+            spacing: dedupeTokens(spacing, maxTokens),
+            typography: dedupeTokens(typography, maxTokens),
+            radii: dedupeTokens(radii, maxTokens),
+            sources
+        },
+        conventions: {
+            componentNaming: classifyComponentNaming(componentSamples),
+            componentDir,
+            serviceDir,
+            hookDir,
+            samples
+        },
+        inconsistencies: findInconsistencies(rawTokens)
+    };
+}