@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.88

package/dist/core/init/detector.js

@@ -0,0 +1,582 @@
+/**
+ * `pugi init` codebase scanner (backlog #82).
+ *
+ * Zero-dep, depth-bounded probe of a workspace that returns a structured
+ * `DetectionResult` consumed by `template-renderer.ts` to materialise a
+ * project-aware `PUGI.md`. Detection runs OFFLINE — no fetches, no
+ * spawned processes other than the optional `git log` probe (and even
+ * that is injectable for tests).
+ *
+ * Detection rubric (the 7 surfaces):
+ *
+ *  1. Stack — primary language(s) inferred from manifest files.
+ *     package.json → Node, pyproject.toml/setup.py/requirements.txt
+ *     → Python, Cargo.toml → Rust, go.mod → Go, Gemfile → Ruby,
+ *     composer.json → PHP, pom.xml/build.gradle → Java.
+ *
+ *  2. Frameworks — derived from package.json deps + config files.
+ *     Next.js (next.config.*), Vite, NestJS (@nestjs/core), Express,
+ *     Fastify, Hono, SvelteKit, Nuxt, Remix, React, Vue, Angular,
+ *     Prisma, Drizzle, tRPC, Zod, FastAPI, Django, Flask, Axum,
+ *     Actix-web, Gin, Echo, Rails.
+ *
+ *  3. Test frameworks — Jest, Vitest, Mocha, Playwright, Cypress,
+ *     node:test, pytest, cargo test (implicit when Rust detected),
+ *     go test (implicit when Go detected).
+ *
+ *  4. Commit conventions — sampled from `git log --pretty=format:%s -50`.
+ *     Conventional commits (`feat:`, `fix(scope):`...), gitmoji
+ *     (`:sparkles:`), freeform, or unknown when log is empty.
+ *
+ *  5. Monorepo — pnpm-workspace.yaml / lerna.json / turbo.json /
+ *     nx.json / yarn workspaces in package.json.
+ *
+ *  6. Existing AI configs — CLAUDE.md (with content excerpt for
+ *     template seeding), PUGI.md (read content), .cursorrules,
+ *     .windsurfrules, .aiderignore.
+ *
+ *  7. Project layout — top-level dirs the operator should reference.
+ *
+ * Hard constraints:
+ *
+ *  - Walk depth capped at 4 (root + 3 levels).
+ *  - Max 3000 nodes visited (giant repos short-circuit gracefully).
+ *  - Skip dirs: node_modules, dist, .git, target, __pycache__, vendor,
+ *    .next, coverage, .turbo, .nx, build, out, .cache, tmp, venv,
+ *    .venv, .vscode, .idea, Pods.
+ *  - Every fs call wrapped in try/catch; missing manifest = field
+ *    omitted, never a thrown error.
+ *
+ * Reuses `languageForExtension`, `topLanguages`, `detectPackageManager`
+ * from `../context/repo-skeleton.js` for histogram + package-manager
+ * detection so we keep one source-of-truth for those mappings.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync, } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { detectPackageManager, languageForExtension, topLanguages, } from '../context/repo-skeleton.js';
+/** Hard cap on walker depth. Root counts as depth 0. */
+export const MAX_DETECTION_DEPTH = 4;
+/** Hard cap on nodes visited before we short-circuit the walk. */
+export const MAX_DETECTION_NODES = 3000;
+/** Dirs we never descend into (heavy, generated, IDE state). */
+export const SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    '.git',
+    'target',
+    '__pycache__',
+    'vendor',
+    '.next',
+    'coverage',
+    '.turbo',
+    '.nx',
+    'build',
+    'out',
+    '.cache',
+    'tmp',
+    'venv',
+    '.venv',
+    '.vscode',
+    '.idea',
+    'Pods',
+]);
+/** Recent git subject sample size. */
+export const GIT_LOG_SAMPLE_SIZE = 50;
+/** Default git log timeout in ms. */
+export const GIT_LOG_TIMEOUT_MS = 3_000;
+/** Run the full detection rubric over a workspace. */
+export function detectWorkspace(cwd, options = {}) {
+    const readLog = options.readCommitLog ?? defaultCommitLogReader(options.gitTimeoutMs);
+    const stack = detectStack(cwd);
+    const walk = walkDetection(cwd);
+    const languages = topLanguages(walk.histogram, 6);
+    const pkg = readPackageJsonSafe(cwd);
+    const frameworks = detectFrameworks(cwd, pkg, walk.fileSet);
+    const testFrameworks = detectTestFrameworks(cwd, pkg, stack.kind, walk.fileSet);
+    const commitConvention = classifyCommits(readLog(cwd));
+    const monorepo = detectMonorepo(cwd, pkg);
+    const aiConfigs = detectAiConfigs(cwd);
+    const scripts = pickScripts(pkg);
+    const topLevelDirs = walk.topLevelDirs;
+    return Object.freeze({
+        cwd,
+        stack,
+        languages,
+        frameworks,
+        testFrameworks,
+        commitConvention,
+        monorepo,
+        aiConfigs,
+        scripts,
+        topLevelDirs,
+        walkVisited: walk.visited,
+        walkTruncated: walk.truncated,
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Stack detection                                                   */
+/* ------------------------------------------------------------------ */
+/** Detect the primary stack via marker manifests. */
+export function detectStack(cwd) {
+    const manifests = [];
+    let kind = 'unknown';
+    let nodeName;
+    let nodeVersion;
+    if (existsSync(join(cwd, 'package.json'))) {
+        manifests.push('package.json');
+        kind = 'node';
+        const pkg = readPackageJsonSafe(cwd);
+        if (pkg) {
+            if (typeof pkg.name === 'string')
+                nodeName = pkg.name;
+            if (typeof pkg.version === 'string')
+                nodeVersion = pkg.version;
+        }
+    }
+    if (existsSync(join(cwd, 'pyproject.toml'))) {
+        manifests.push('pyproject.toml');
+        if (kind === 'unknown')
+            kind = 'python';
+    }
+    if (existsSync(join(cwd, 'setup.py'))) {
+        manifests.push('setup.py');
+        if (kind === 'unknown')
+            kind = 'python';
+    }
+    if (existsSync(join(cwd, 'requirements.txt'))) {
+        manifests.push('requirements.txt');
+        if (kind === 'unknown')
+            kind = 'python';
+    }
+    if (existsSync(join(cwd, 'Cargo.toml'))) {
+        manifests.push('Cargo.toml');
+        if (kind === 'unknown')
+            kind = 'rust';
+    }
+    if (existsSync(join(cwd, 'go.mod'))) {
+        manifests.push('go.mod');
+        if (kind === 'unknown')
+            kind = 'go';
+    }
+    if (existsSync(join(cwd, 'Gemfile'))) {
+        manifests.push('Gemfile');
+        if (kind === 'unknown')
+            kind = 'ruby';
+    }
+    if (existsSync(join(cwd, 'composer.json'))) {
+        manifests.push('composer.json');
+        if (kind === 'unknown')
+            kind = 'php';
+    }
+    if (existsSync(join(cwd, 'pom.xml'))) {
+        manifests.push('pom.xml');
+        if (kind === 'unknown')
+            kind = 'java';
+    }
+    if (existsSync(join(cwd, 'build.gradle')) || existsSync(join(cwd, 'build.gradle.kts'))) {
+        manifests.push(existsSync(join(cwd, 'build.gradle')) ? 'build.gradle' : 'build.gradle.kts');
+        if (kind === 'unknown')
+            kind = 'java';
+    }
+    const packageManager = kind === 'node' ? detectPackageManager(cwd) : undefined;
+    return Object.freeze({
+        kind,
+        manifests: Object.freeze(manifests),
+        packageManager,
+        nodeName,
+        nodeVersion,
+    });
+}
+const NODE_FRAMEWORK_SPECS = [
+    {
+        name: 'Next.js',
+        depKeys: ['next'],
+        configFiles: ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs'],
+    },
+    {
+        name: 'Vite',
+        depKeys: ['vite'],
+        configFiles: ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cjs'],
+    },
+    { name: 'NestJS', depKeys: ['@nestjs/core'] },
+    { name: 'Express', depKeys: ['express'] },
+    { name: 'Fastify', depKeys: ['fastify'] },
+    { name: 'Hono', depKeys: ['hono'] },
+    { name: 'SvelteKit', depKeys: ['@sveltejs/kit'], configFiles: ['svelte.config.js'] },
+    { name: 'Nuxt', depKeys: ['nuxt'], configFiles: ['nuxt.config.ts', 'nuxt.config.js'] },
+    { name: 'Remix', depKeys: ['@remix-run/react', '@remix-run/node'] },
+    { name: 'React', depKeys: ['react'] },
+    { name: 'Vue', depKeys: ['vue'] },
+    { name: 'Angular', depKeys: ['@angular/core'] },
+    { name: 'Prisma', depKeys: ['prisma', '@prisma/client'] },
+    { name: 'Drizzle', depKeys: ['drizzle-orm'] },
+    { name: 'tRPC', depKeys: ['@trpc/server', '@trpc/client'] },
+    { name: 'Zod', depKeys: ['zod'] },
+];
+const PYTHON_FRAMEWORK_SPECS = [
+    { name: 'FastAPI', token: 'fastapi' },
+    { name: 'Django', token: 'django' },
+    { name: 'Flask', token: 'flask' },
+];
+const RUST_FRAMEWORK_SPECS = [
+    { name: 'Axum', token: 'axum' },
+    { name: 'Actix-web', token: 'actix-web' },
+];
+const GO_FRAMEWORK_SPECS = [
+    { name: 'Gin', token: 'github.com/gin-gonic/gin' },
+    { name: 'Echo', token: 'github.com/labstack/echo' },
+];
+function detectFrameworks(cwd, pkg, fileSet) {
+    const found = [];
+    const seen = new Set();
+    if (pkg) {
+        const deps = collectDeps(pkg);
+        for (const spec of NODE_FRAMEWORK_SPECS) {
+            const evidence = matchFramework(spec, deps, cwd);
+            if (evidence && !seen.has(spec.name)) {
+                found.push({ name: spec.name, evidence });
+                seen.add(spec.name);
+            }
+        }
+    }
+    // Python frameworks from requirements.txt / pyproject.toml content scan.
+    const pyText = safeRead(join(cwd, 'requirements.txt')) ?? safeRead(join(cwd, 'pyproject.toml'));
+    if (pyText) {
+        const lowered = pyText.toLowerCase();
+        for (const spec of PYTHON_FRAMEWORK_SPECS) {
+            if (lowered.includes(spec.token) && !seen.has(spec.name)) {
+                found.push({ name: spec.name, evidence: `dependency: ${spec.token}` });
+                seen.add(spec.name);
+            }
+        }
+    }
+    // Rust frameworks from Cargo.toml content scan.
+    const cargo = safeRead(join(cwd, 'Cargo.toml'));
+    if (cargo) {
+        const lowered = cargo.toLowerCase();
+        for (const spec of RUST_FRAMEWORK_SPECS) {
+            if (lowered.includes(spec.token) && !seen.has(spec.name)) {
+                found.push({ name: spec.name, evidence: `dependency: ${spec.token}` });
+                seen.add(spec.name);
+            }
+        }
+    }
+    // Go frameworks from go.mod content scan.
+    const gomod = safeRead(join(cwd, 'go.mod'));
+    if (gomod) {
+        for (const spec of GO_FRAMEWORK_SPECS) {
+            if (gomod.includes(spec.token) && !seen.has(spec.name)) {
+                found.push({ name: spec.name, evidence: `dependency: ${spec.token}` });
+                seen.add(spec.name);
+            }
+        }
+    }
+    // Ruby on Rails — presence of `config/application.rb` is a very strong signal.
+    if (existsSync(join(cwd, 'Gemfile')) || fileSet.has('config/application.rb')) {
+        const gemfile = safeRead(join(cwd, 'Gemfile')) ?? '';
+        if (/rails/i.test(gemfile) && !seen.has('Rails')) {
+            found.push({ name: 'Rails', evidence: 'Gemfile: rails' });
+            seen.add('Rails');
+        }
+    }
+    return Object.freeze(found);
+}
+function matchFramework(spec, deps, cwd) {
+    if (spec.depKeys) {
+        for (const key of spec.depKeys) {
+            if (deps.has(key))
+                return `dependency: ${key}`;
+        }
+    }
+    if (spec.configFiles) {
+        for (const file of spec.configFiles) {
+            if (existsSync(join(cwd, file)))
+                return `config: ${file}`;
+        }
+    }
+    return null;
+}
+/* ------------------------------------------------------------------ */
+/* Test frameworks                                                   */
+/* ------------------------------------------------------------------ */
+function detectTestFrameworks(cwd, pkg, stack, fileSet) {
+    const found = new Set();
+    if (pkg) {
+        const deps = collectDeps(pkg);
+        if (deps.has('jest'))
+            found.add('Jest');
+        if (deps.has('vitest'))
+            found.add('Vitest');
+        if (deps.has('mocha'))
+            found.add('Mocha');
+        if (deps.has('@playwright/test') || deps.has('playwright'))
+            found.add('Playwright');
+        if (deps.has('cypress'))
+            found.add('Cypress');
+        // node:test surfaces via the `node --test` script invocation.
+        const scripts = pkg.scripts;
+        if (scripts && typeof scripts === 'object') {
+            for (const value of Object.values(scripts)) {
+                if (typeof value === 'string' && /\bnode\s+--test\b/.test(value)) {
+                    found.add('node:test');
+                    break;
+                }
+            }
+        }
+    }
+    // Pytest by `pytest.ini` / `pyproject.toml [tool.pytest]` / config files.
+    if (stack === 'python') {
+        if (existsSync(join(cwd, 'pytest.ini')))
+            found.add('pytest');
+        const pyproject = safeRead(join(cwd, 'pyproject.toml'));
+        if (pyproject && /\[tool\.pytest/.test(pyproject))
+            found.add('pytest');
+        const reqs = safeRead(join(cwd, 'requirements.txt'));
+        if (reqs && /pytest/i.test(reqs))
+            found.add('pytest');
+    }
+    // cargo / go test are implicit when stack matches; surface that signal.
+    if (stack === 'rust' && existsSync(join(cwd, 'Cargo.toml'))) {
+        found.add('cargo test');
+    }
+    if (stack === 'go' && existsSync(join(cwd, 'go.mod'))) {
+        found.add('go test');
+    }
+    // Test directory heuristic — surface even when nothing else matches.
+    if (found.size === 0) {
+        if (fileSet.has('tests') || fileSet.has('test') || fileSet.has('__tests__')) {
+            // Leave empty rather than guessing a framework name.
+        }
+    }
+    return Object.freeze(Array.from(found).sort((a, b) => a.localeCompare(b)));
+}
+/* ------------------------------------------------------------------ */
+/* Commit convention                                                 */
+/* ------------------------------------------------------------------ */
+const CONVENTIONAL_RE = /^(feat|fix|chore|docs|style|refactor|test|build|ci|perf|revert)(\(.+\))?!?:/i;
+const GITMOJI_RE = /^:[a-z0-9_+-]+:/;
+/** Classify a sample of commit subject lines. */
+export function classifyCommits(subjects) {
+    if (subjects.length === 0)
+        return 'unknown';
+    let conventional = 0;
+    let gitmoji = 0;
+    for (const raw of subjects) {
+        const subject = raw.trim();
+        if (!subject)
+            continue;
+        if (CONVENTIONAL_RE.test(subject))
+            conventional += 1;
+        else if (GITMOJI_RE.test(subject))
+            gitmoji += 1;
+    }
+    const total = subjects.length;
+    if (conventional / total >= 0.4)
+        return 'conventional';
+    if (gitmoji / total >= 0.4)
+        return 'gitmoji';
+    return 'freeform';
+}
+function defaultCommitLogReader(timeoutMs = GIT_LOG_TIMEOUT_MS) {
+    return (cwd) => {
+        try {
+            const out = execFileSync('git', ['log', `--pretty=format:%s`, `-${GIT_LOG_SAMPLE_SIZE}`], {
+                cwd,
+                encoding: 'utf8',
+                timeout: timeoutMs,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            return out.split('\n').filter((line) => line.length > 0);
+        }
+        catch {
+            return [];
+        }
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Monorepo detection                                                */
+/* ------------------------------------------------------------------ */
+function detectMonorepo(cwd, pkg) {
+    if (existsSync(join(cwd, 'pnpm-workspace.yaml'))) {
+        return { kind: 'pnpm', file: 'pnpm-workspace.yaml' };
+    }
+    if (existsSync(join(cwd, 'turbo.json'))) {
+        return { kind: 'turborepo', file: 'turbo.json' };
+    }
+    if (existsSync(join(cwd, 'nx.json'))) {
+        return { kind: 'nx', file: 'nx.json' };
+    }
+    if (existsSync(join(cwd, 'lerna.json'))) {
+        return { kind: 'lerna', file: 'lerna.json' };
+    }
+    if (pkg && Array.isArray(pkg.workspaces)) {
+        return { kind: 'yarn-workspaces', file: 'package.json' };
+    }
+    if (pkg &&
+        typeof pkg.workspaces === 'object' &&
+        pkg.workspaces !== null) {
+        return { kind: 'yarn-workspaces', file: 'package.json' };
+    }
+    return undefined;
+}
+/* ------------------------------------------------------------------ */
+/* AI configs                                                        */
+/* ------------------------------------------------------------------ */
+const AI_CONFIG_FILES = [
+    { name: 'CLAUDE.md', path: 'CLAUDE.md' },
+    { name: 'PUGI.md', path: 'PUGI.md' },
+    { name: '.cursorrules', path: '.cursorrules' },
+    { name: '.windsurfrules', path: '.windsurfrules' },
+    { name: '.aiderignore', path: '.aiderignore' },
+];
+const AI_EXCERPT_BYTES = 1_500;
+function detectAiConfigs(cwd) {
+    const found = [];
+    for (const spec of AI_CONFIG_FILES) {
+        const absPath = join(cwd, spec.path);
+        if (!existsSync(absPath))
+            continue;
+        const raw = safeRead(absPath);
+        let excerpt;
+        if (raw && raw.length > 0) {
+            excerpt = raw.slice(0, AI_EXCERPT_BYTES);
+        }
+        found.push({ name: spec.name, path: spec.path, excerpt });
+    }
+    return Object.freeze(found);
+}
+function walkDetection(cwd) {
+    const histogram = new Map();
+    const fileSet = new Set();
+    const topLevelDirs = [];
+    let visited = 0;
+    let truncated = false;
+    function walk(absPath, depth, relPrefix) {
+        if (visited >= MAX_DETECTION_NODES) {
+            truncated = true;
+            return;
+        }
+        visited += 1;
+        let entries;
+        try {
+            entries = readdirSync(absPath, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const rel = relPrefix.length === 0 ? entry.name : `${relPrefix}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                if (depth === 0)
+                    topLevelDirs.push(entry.name);
+                fileSet.add(rel);
+                if (depth + 1 < MAX_DETECTION_DEPTH) {
+                    walk(join(absPath, entry.name), depth + 1, rel);
+                }
+            }
+            else if (entry.isFile()) {
+                fileSet.add(rel);
+                if (depth === 0) {
+                    // Already counted above-tree manifests separately.
+                }
+                const ext = extname(entry.name);
+                if (ext.length > 0) {
+                    const lang = languageForExtension(entry.name);
+                    if (lang)
+                        histogram.set(lang, (histogram.get(lang) ?? 0) + 1);
+                }
+            }
+        }
+    }
+    walk(cwd, 0, '');
+    return Object.freeze({
+        histogram,
+        fileSet,
+        topLevelDirs: Object.freeze(topLevelDirs.slice(0, 20)),
+        visited,
+        truncated,
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Helpers                                                           */
+/* ------------------------------------------------------------------ */
+function readPackageJsonSafe(cwd) {
+    const raw = safeRead(join(cwd, 'package.json'));
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function collectDeps(pkg) {
+    const out = new Map();
+    for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+        const value = pkg[key];
+        if (!value || typeof value !== 'object')
+            continue;
+        for (const [name, version] of Object.entries(value)) {
+            if (typeof version === 'string')
+                out.set(name, version);
+        }
+    }
+    return out;
+}
+function pickScripts(pkg) {
+    if (!pkg)
+        return Object.freeze([]);
+    const scripts = pkg.scripts;
+    if (!scripts || typeof scripts !== 'object')
+        return Object.freeze([]);
+    const out = [];
+    const interesting = new Set([
+        'dev',
+        'start',
+        'build',
+        'test',
+        'typecheck',
+        'lint',
+        'format',
+        'check',
+        'ci',
+    ]);
+    for (const [name, value] of Object.entries(scripts)) {
+        if (typeof value !== 'string')
+            continue;
+        if (!interesting.has(name))
+            continue;
+        out.push({ name, command: value });
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name));
+    return Object.freeze(out);
+}
+function safeRead(path) {
+    try {
+        const st = statSync(path);
+        if (!st.isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+// `basename` is referenced via this binding so the linter does not strip the
+// import when only used indirectly through the manifest manifest array above.
+void basename;
+//# sourceMappingURL=detector.js.map