@planu/cli 4.3.9 → 4.3.11

package/dist/engine/legacy/ast-analyzer.d.ts

@@ -1,21 +0,0 @@
-import type { LegacyFunctionInfo, LegacyFileAnalysis } from '../../types/index.js';
-export type { LegacyFunctionInfo, LegacyFileAnalysis };
-/**
- * Checks if the given file extension is a supported TypeScript/JavaScript file.
- */
-export declare function isSupportedFile(filePath: string): boolean;
-/**
- * Extracts a short snippet of lines around a given line number.
- */
-export declare function extractSnippet(lines: string[], lineIndex: number, context?: number): string;
-/**
- * Parses function names and their line numbers from source code.
- * Uses regex-based detection to avoid external AST dependencies.
- */
-export declare function extractFunctions(content: string): LegacyFunctionInfo[];
-/**
- * Reads and analyzes a TypeScript/JavaScript source file.
- * Returns null if the file is not supported or cannot be read.
- */
-export declare function analyzeFile(filePath: string): Promise<LegacyFileAnalysis | null>;
-//# sourceMappingURL=ast-analyzer.d.ts.map

package/dist/engine/legacy/ast-analyzer.js

@@ -1,113 +0,0 @@
-// Planu — engine/legacy/ast-analyzer.ts
-// Minimal TypeScript/JavaScript AST analyzer using regex-based patterns.
-// No external dependencies beyond Node built-ins.
-import { readFile } from 'node:fs/promises';
-import { extname } from 'node:path';
-// Regex patterns for function detection
-const FUNCTION_PATTERNS = [
-    // export function foo(
-    /^(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/m,
-    // const foo = (
-    /(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\(([^)]*)\)\s*(?::\s*\S+\s*)?=>/m,
-    // foo(
-    /^(?:export\s+)?(?:async\s+)?(\w+)\s*\(([^)]*)\)\s*(?::\s*\S+\s*)?{/m,
-];
-/**
- * Checks if the given file extension is a supported TypeScript/JavaScript file.
- */
-export function isSupportedFile(filePath) {
-    const ext = extname(filePath).toLowerCase();
-    return ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs'].includes(ext);
-}
-/**
- * Extracts a short snippet of lines around a given line number.
- */
-export function extractSnippet(lines, lineIndex, context = 3) {
-    const start = Math.max(0, lineIndex - 1);
-    const end = Math.min(lines.length, lineIndex + context);
-    return lines
-        .slice(start, end)
-        .map((l) => l.trimEnd())
-        .join('\n');
-}
-/**
- * Parses function names and their line numbers from source code.
- * Uses regex-based detection to avoid external AST dependencies.
- */
-export function extractFunctions(content) {
-    const lines = content.split('\n');
-    const functions = [];
-    const seen = new Set();
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        const trimmed = line.trim();
-        // Skip comments and empty lines
-        if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed === '') {
-            continue;
-        }
-        for (const pattern of FUNCTION_PATTERNS) {
-            const match = trimmed.match(pattern);
-            if (match) {
-                const name = match[1];
-                const paramsRaw = match[2] ?? '';
-                if (name === undefined || name === '' || seen.has(`${name}:${i}`)) {
-                    break;
-                }
-                seen.add(`${name}:${i}`);
-                const params = paramsRaw
-                    .split(',')
-                    .map((p) => p.trim().split(':')[0]?.trim() ?? '')
-                    .filter((p) => p.length > 0);
-                // Collect function body (up to closing brace or end of arrow fn)
-                const bodyLines = [];
-                let braceCount = 0;
-                let bodyStarted = false;
-                for (let j = i; j < Math.min(lines.length, i + 80); j++) {
-                    const bl = lines[j] ?? '';
-                    bodyLines.push(bl);
-                    for (const ch of bl) {
-                        if (ch === '{') {
-                            braceCount++;
-                            bodyStarted = true;
-                        }
-                        else if (ch === '}') {
-                            braceCount--;
-                        }
-                    }
-                    if (bodyStarted && braceCount === 0) {
-                        break;
-                    }
-                }
-                functions.push({
-                    name,
-                    line: i + 1,
-                    params,
-                    body: bodyLines.join('\n'),
-                    snippet: extractSnippet(lines, i + 1),
-                });
-                break;
-            }
-        }
-    }
-    return functions;
-}
-/**
- * Reads and analyzes a TypeScript/JavaScript source file.
- * Returns null if the file is not supported or cannot be read.
- */
-export async function analyzeFile(filePath) {
-    if (!isSupportedFile(filePath)) {
-        return null;
-    }
-    let content;
-    try {
-        content = await readFile(filePath, 'utf-8');
-    }
-    catch {
-        return null;
-    }
-    const lines = content.split('\n');
-    const functions = extractFunctions(content);
-    return { filePath, functions, lines };
-}
-//# sourceMappingURL=ast-analyzer.js.map

package/dist/engine/legacy/characterization-generator.d.ts

@@ -1,6 +0,0 @@
-import type { CharacterizationResult } from '../../types/index.js';
-/**
- * Generates characterization test stubs for functions in the given files.
- */
-export declare function generateCharacterizationTests(projectPath: string, files?: string[], outputFile?: string): Promise<CharacterizationResult>;
-//# sourceMappingURL=characterization-generator.d.ts.map

package/dist/engine/legacy/characterization-generator.js

@@ -1,146 +0,0 @@
-// Planu — engine/legacy/characterization-generator.ts
-// Generates characterization test stubs for existing functions.
-// The stubs call the function with detected sample inputs and leave
-// `// TODO: assert current output` placeholders for the developer to fill in.
-import { glob } from 'glob';
-import { join, relative, basename } from 'node:path';
-import { analyzeFile } from './ast-analyzer.js';
-// ---------------------------------------------------------------------------
-// Sample input inference
-// ---------------------------------------------------------------------------
-// Keyword groups for sample value inference
-const PATH_KEYWORDS = ['path', 'dir', 'file'];
-const URL_KEYWORDS = ['url', 'endpoint'];
-const ID_KEYWORDS = ['id', 'key'];
-const NUM_KEYWORDS = ['count', 'size', 'limit', 'max', 'min', 'num', 'index'];
-const BOOL_KEYWORDS = ['flag', 'enabled', 'active', 'is', 'has'];
-const ARRAY_KEYWORDS = ['list', 'items', 'arr'];
-const OBJ_KEYWORDS = ['opts', 'options', 'config', 'args'];
-function matchesAny(lower, keywords) {
-    return keywords.some((k) => lower.includes(k));
-}
-/**
- * Infers a plausible sample value for a parameter based on its name/type hints.
- */
-function inferSampleValue(paramName) {
-    const lower = paramName.toLowerCase();
-    if (matchesAny(lower, PATH_KEYWORDS)) {
-        return { name: paramName, value: '"/tmp/sample"', type: 'string' };
-    }
-    if (matchesAny(lower, URL_KEYWORDS)) {
-        return { name: paramName, value: '"https://example.com"', type: 'string' };
-    }
-    if (matchesAny(lower, ID_KEYWORDS)) {
-        return { name: paramName, value: '"test-id-001"', type: 'string' };
-    }
-    if (matchesAny(lower, NUM_KEYWORDS)) {
-        return { name: paramName, value: '10', type: 'number' };
-    }
-    if (matchesAny(lower, BOOL_KEYWORDS)) {
-        return { name: paramName, value: 'true', type: 'boolean' };
-    }
-    if (matchesAny(lower, ARRAY_KEYWORDS)) {
-        return { name: paramName, value: '[]', type: 'unknown[]' };
-    }
-    if (matchesAny(lower, OBJ_KEYWORDS)) {
-        return { name: paramName, value: '{}', type: 'Record<string, unknown>' };
-    }
-    return { name: paramName, value: `"${paramName}-value"`, type: 'string' };
-}
-/**
- * Generates a test stub for a single function.
- */
-function generateTestStub(fn, sourceFile, importPath, testId) {
-    const params = fn.params;
-    const sampleInputs = params.map(inferSampleValue);
-    const paramList = sampleInputs.map((s) => s.value).join(', ');
-    const isAsync = fn.body.includes('await') || fn.body.includes('async');
-    const awaitKeyword = isAsync ? 'await ' : '';
-    const testModifier = isAsync ? 'async ' : '';
-    const stubLines = [
-        `// Characterization test for ${fn.name}`,
-        `// File: ${sourceFile}`,
-        `// Generated by Planu — fill in the expected values.`,
-        ``,
-        `import { ${fn.name} } from '${importPath}';`,
-        ``,
-        `describe('${fn.name} (characterization)', () => {`,
-        `  it('should behave as currently observed', ${testModifier}() => {`,
-        ...sampleInputs.map((s) => `    const ${s.name} = ${s.value}; // ${s.type}`),
-        ``,
-        `    const result = ${awaitKeyword}${fn.name}(${paramList});`,
-        ``,
-        `    // TODO: Replace with actual observed output:`,
-        `    // expect(result).toEqual(/* observed value */);`,
-        `    expect(result).toBeDefined();`,
-        `  });`,
-        `});`,
-    ];
-    const testCode = stubLines.join('\n');
-    return {
-        id: testId,
-        sourceFile,
-        functionName: fn.name,
-        testCode,
-        sampleInputs,
-        developerNote: 'Run the function manually with these inputs, observe the output, then replace the TODO assertion with the actual expected value.',
-    };
-}
-// ---------------------------------------------------------------------------
-// File resolution
-// ---------------------------------------------------------------------------
-async function resolveFiles(projectPath, files) {
-    if (files !== undefined && files.length > 0) {
-        return files;
-    }
-    return glob('src/**/*.{ts,tsx,js,jsx}', {
-        cwd: projectPath,
-        absolute: true,
-        ignore: ['**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*', '**/index.ts'],
-    });
-}
-// ---------------------------------------------------------------------------
-// Main entry point
-// ---------------------------------------------------------------------------
-let testCounter = 0;
-function makeTestId() {
-    testCounter++;
-    return `CT-${String(testCounter).padStart(4, '0')}`;
-}
-/**
- * Generates characterization test stubs for functions in the given files.
- */
-export async function generateCharacterizationTests(projectPath, files, outputFile) {
-    testCounter = 0;
-    const resolvedFiles = await resolveFiles(projectPath, files);
-    const allTests = [];
-    for (const filePath of resolvedFiles) {
-        const absPath = filePath.startsWith('/') ? filePath : join(projectPath, filePath);
-        const analysis = await analyzeFile(absPath);
-        if (analysis === null || analysis.functions.length === 0) {
-            continue;
-        }
-        const relPath = relative(projectPath, absPath);
-        // Convert to a relative import path usable in tests/
-        const importBase = basename(absPath).replace(/\.(ts|tsx|js|jsx)$/, '.js');
-        const importDir = relative(join(projectPath, 'tests'), join(projectPath, relPath.replace(/\/[^/]+$/, '')));
-        const importPath = `${importDir}/${importBase}`;
-        for (const fn of analysis.functions) {
-            // Skip private-looking functions (underscore prefix)
-            if (fn.name.startsWith('_')) {
-                continue;
-            }
-            allTests.push(generateTestStub(fn, relPath, importPath, makeTestId()));
-        }
-    }
-    const defaultOutput = join(projectPath, 'tests', 'characterization', 'characterization.test.ts');
-    const outFile = outputFile ?? defaultOutput;
-    return {
-        projectPath,
-        filesAnalyzed: resolvedFiles.length,
-        tests: allTests,
-        outputFile: outFile,
-        summary: `Analyzed ${resolvedFiles.length} files. Generated ${allTests.length} characterization test stubs.`,
-    };
-}
-//# sourceMappingURL=characterization-generator.js.map

package/dist/engine/legacy/hyrum-scanner.d.ts

@@ -1,6 +0,0 @@
-import type { HyrumScanResult } from '../../types/index.js';
-/**
- * Scans the given files (or project) for Hyrum's Law risks.
- */
-export declare function scanHyrumRisks(projectPath: string, files?: string[]): Promise<HyrumScanResult>;
-//# sourceMappingURL=hyrum-scanner.d.ts.map

package/dist/engine/legacy/hyrum-scanner.js

@@ -1,137 +0,0 @@
-// Planu — engine/legacy/hyrum-scanner.ts
-// Detects Hyrum's Law risks in public API surfaces:
-// observable behaviors that callers may depend on even if undocumented.
-import { glob } from 'glob';
-import { analyzeFile, extractSnippet } from './ast-analyzer.js';
-// ---------------------------------------------------------------------------
-// Risk detection patterns
-// ---------------------------------------------------------------------------
-const RISK_PATTERNS = [
-    {
-        category: 'exception-type',
-        regex: /throw\s+new\s+(\w+Error|Error)\s*\(/,
-        severity: 'high',
-        describe: (m) => `Throws ${m[1] ?? 'Error'} — callers may catch this specific type`,
-    },
-    {
-        category: 'return-shape',
-        regex: /return\s*\{\s*(\w+)\s*:/,
-        severity: 'medium',
-        describe: (m) => `Returns object with key "${m[1] ?? '?'}" — shape may be depended on`,
-    },
-    {
-        category: 'null-vs-undefined',
-        regex: /return\s+(null|undefined)\b/,
-        severity: 'high',
-        describe: (m) => `Returns ${m[1] ?? 'null/undefined'} — callers may distinguish null vs undefined`,
-    },
-    {
-        category: 'ordering-guarantee',
-        regex: /\.sort\s*\(/,
-        severity: 'medium',
-        describe: () => 'Array.sort() used — output ordering may be depended on by callers',
-    },
-    {
-        category: 'error-message-text',
-        regex: /throw\s+new\s+\w+\s*\(\s*[`'"]/,
-        severity: 'medium',
-        describe: () => 'Error with string literal — error message text may be relied upon by callers',
-    },
-    {
-        category: 'implicit-return',
-        regex: /=>\s*[^{(\n][^;\n]*$/m,
-        severity: 'low',
-        describe: () => 'Arrow function with implicit return — return value shape may be an implicit contract',
-    },
-];
-// ---------------------------------------------------------------------------
-// Scanner
-// ---------------------------------------------------------------------------
-let riskCounter = 0;
-function makeRiskId() {
-    riskCounter++;
-    return `HR-${String(riskCounter).padStart(4, '0')}`;
-}
-/**
- * Scans a single file for Hyrum risks.
- */
-async function scanFile(filePath) {
-    const analysis = await analyzeFile(filePath);
-    if (analysis === null) {
-        return [];
-    }
-    const risks = [];
-    for (const fn of analysis.functions) {
-        const bodyLines = fn.body.split('\n');
-        for (const pattern of RISK_PATTERNS) {
-            for (let i = 0; i < bodyLines.length; i++) {
-                const line = bodyLines[i] ?? '';
-                const match = line.match(pattern.regex);
-                if (match) {
-                    const absoluteLine = fn.line + i;
-                    risks.push({
-                        id: makeRiskId(),
-                        category: pattern.category,
-                        file: filePath,
-                        line: absoluteLine,
-                        functionName: fn.name,
-                        description: pattern.describe(match),
-                        severity: pattern.severity,
-                        snippet: extractSnippet(analysis.lines, absoluteLine),
-                    });
-                }
-            }
-        }
-    }
-    return risks;
-}
-/**
- * Resolves the list of files to scan.
- * If `files` is provided, uses that list. Otherwise globs for TS/JS files.
- */
-async function resolveFiles(projectPath, files) {
-    if (files !== undefined && files.length > 0) {
-        return files;
-    }
-    return glob('src/**/*.{ts,tsx,js,jsx}', {
-        cwd: projectPath,
-        absolute: true,
-        ignore: ['**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*'],
-    });
-}
-/**
- * Scans the given files (or project) for Hyrum's Law risks.
- */
-export async function scanHyrumRisks(projectPath, files) {
-    riskCounter = 0;
-    const resolvedFiles = await resolveFiles(projectPath, files);
-    // Process in parallel with a concurrency limit
-    const BATCH = 20;
-    const allRisks = [];
-    for (let i = 0; i < resolvedFiles.length; i += BATCH) {
-        const batch = resolvedFiles.slice(i, i + BATCH);
-        const batchResults = await Promise.all(batch.map((f) => scanFile(f)));
-        for (const r of batchResults) {
-            allRisks.push(...r);
-        }
-    }
-    // Sort by severity then file
-    const severityOrder = { high: 0, medium: 1, low: 2 };
-    allRisks.sort((a, b) => {
-        const sv = severityOrder[a.severity] - severityOrder[b.severity];
-        if (sv !== 0) {
-            return sv;
-        }
-        return a.file.localeCompare(b.file);
-    });
-    const highCount = allRisks.filter((r) => r.severity === 'high').length;
-    const medCount = allRisks.filter((r) => r.severity === 'medium').length;
-    const lowCount = allRisks.filter((r) => r.severity === 'low').length;
-    return {
-        projectPath,
-        filesScanned: resolvedFiles.length,
-        risks: allRisks,
-        summary: `Scanned ${resolvedFiles.length} files. Found ${allRisks.length} Hyrum risks: ${highCount} high, ${medCount} medium, ${lowCount} low.`,
-    };
-}
-//# sourceMappingURL=hyrum-scanner.js.map

package/dist/engine/legacy/safety-net-orchestrator.d.ts

@@ -1,7 +0,0 @@
-import type { SafetyNetPlan } from '../../types/index.js';
-/**
- * Builds a safety-net refactoring plan for the given project and target files.
- * Pure function — returns a plan without executing anything.
- */
-export declare function buildSafetyNetPlan(projectPath: string, targetFiles?: string[], coverageThreshold?: number): Promise<SafetyNetPlan>;
-//# sourceMappingURL=safety-net-orchestrator.d.ts.map

package/dist/engine/legacy/safety-net-orchestrator.js

@@ -1,114 +0,0 @@
-// Planu — engine/legacy/safety-net-orchestrator.ts
-// Pure orchestrator: given a project and target files, produces a sequenced
-// safety-net plan for refactoring. No real execution — returns the plan.
-import { join } from 'node:path';
-import { findSeams } from './seam-finder.js';
-// ---------------------------------------------------------------------------
-// Step builders
-// ---------------------------------------------------------------------------
-function buildStep(order, label, description, estimatedMinutes) {
-    return {
-        order,
-        label,
-        description,
-        status: 'pending',
-        estimatedMinutes,
-    };
-}
-const BASELINE_STEPS = [
-    {
-        label: 'Measure coverage baseline',
-        description: 'Run the test suite with coverage enabled (e.g., `pnpm test:coverage`) and record the current line/branch coverage percentage for the target files.',
-        status: 'pending',
-        estimatedMinutes: 5,
-    },
-    {
-        label: 'Add characterization tests',
-        description: 'Use `characterize_legacy_code` to generate test stubs. Fill in expected values by running the code manually. These tests lock in existing behavior before any refactoring.',
-        status: 'pending',
-        estimatedMinutes: 30,
-    },
-    {
-        label: 'Verify safety net',
-        description: 'Run the test suite again. All characterization tests must pass before proceeding. If any fail, fix the expected values — do not change the production code yet.',
-        status: 'pending',
-        estimatedMinutes: 5,
-    },
-];
-const REFACTOR_STEPS_AFTER_SAFETY_NET = [
-    {
-        label: 'Break seams incrementally',
-        description: 'Use `seams_detector` output to identify injection points. Break one seam at a time. Run tests after each change.',
-        status: 'pending',
-        estimatedMinutes: 60,
-    },
-    {
-        label: 'Validate behavior unchanged',
-        description: 'After each refactor step, run the full test suite. All characterization tests must still pass. If any break, roll back the last change.',
-        status: 'pending',
-        estimatedMinutes: 10,
-    },
-    {
-        label: 'Remove characterization scaffolding',
-        description: 'Once the refactored code has proper unit tests covering the same behaviors, remove the temporary characterization test stubs.',
-        status: 'pending',
-        estimatedMinutes: 15,
-    },
-];
-// ---------------------------------------------------------------------------
-// Refactor steps from seams
-// ---------------------------------------------------------------------------
-function seamToRefactorStep(seam) {
-    const patternMap = {
-        'static-call': 'inject-dependency',
-        'global-env': 'inject-dependency',
-        'inline-new': 'inject-dependency',
-        'module-singleton': 'replace-singleton',
-        'hardcoded-path': 'inject-dependency',
-        'hardcoded-url': 'inject-dependency',
-    };
-    const pattern = patternMap[seam.category] ?? 'introduce-seam';
-    const risk = seam.breakability === 'hard' ? 'high' : seam.breakability === 'moderate' ? 'medium' : 'low';
-    return {
-        file: seam.file,
-        change: `In function \`${seam.functionName}\`: ${seam.suggestion}`,
-        pattern,
-        requiresTest: true,
-        risk,
-    };
-}
-// ---------------------------------------------------------------------------
-// Main orchestrator
-// ---------------------------------------------------------------------------
-/**
- * Builds a safety-net refactoring plan for the given project and target files.
- * Pure function — returns a plan without executing anything.
- */
-export async function buildSafetyNetPlan(projectPath, targetFiles, coverageThreshold = 80) {
-    // Detect seams to populate refactor steps
-    const seamResult = await findSeams(projectPath, targetFiles);
-    // Build ordered steps
-    const steps = [
-        ...BASELINE_STEPS.map((s, i) => buildStep(i + 1, s.label, s.description, s.estimatedMinutes)),
-        ...REFACTOR_STEPS_AFTER_SAFETY_NET.map((s, i) => buildStep(BASELINE_STEPS.length + i + 1, s.label, s.description, s.estimatedMinutes)),
-    ];
-    // Build refactor steps from detected seams (max 20 to keep plan readable)
-    const refactorSteps = seamResult.seams
-        .slice(0, 20)
-        .map((seam) => seamToRefactorStep(seam));
-    const resolvedFiles = targetFiles !== undefined && targetFiles.length > 0
-        ? targetFiles
-        : [`${join(projectPath, 'src')}/**/*.{ts,js}`];
-    const totalMinutes = steps.reduce((sum, s) => sum + s.estimatedMinutes, 0);
-    return {
-        projectPath,
-        targetFiles: resolvedFiles,
-        coverageBaseline: coverageThreshold,
-        steps,
-        refactorSteps,
-        summary: `Safety-net plan: ${steps.length} steps (~${totalMinutes} min total). ` +
-            `${refactorSteps.length} refactor actions identified from ${seamResult.seams.length} seams. ` +
-            `Coverage target: ≥${coverageThreshold}%.`,
-    };
-}
-//# sourceMappingURL=safety-net-orchestrator.js.map

package/dist/engine/legacy/seam-finder.d.ts

@@ -1,6 +0,0 @@
-import type { SeamScanResult } from '../../types/index.js';
-/**
- * Scans the given files (or project) for seams.
- */
-export declare function findSeams(projectPath: string, files?: string[]): Promise<SeamScanResult>;
-//# sourceMappingURL=seam-finder.d.ts.map