@planu/cli 4.3.9 → 4.3.11

package/dist/engine/legacy/seam-finder.js

@@ -1,139 +0,0 @@
-// Planu — engine/legacy/seam-finder.ts
-// Finds dependency break points (seams) in TypeScript/JavaScript files.
-// Patterns: static calls, globals, new() inline, hardcoded paths/URLs.
-import { glob } from 'glob';
-import { analyzeFile } from './ast-analyzer.js';
-const SEAM_PATTERNS = [
-    {
-        category: 'static-call',
-        regex: /\b([A-Z]\w+)\.(\w+)\s*\(/,
-        breakability: 'moderate',
-        describe: (m) => `Static call to ${m[1] ?? '?'}.${m[2] ?? '?'}() — hard to mock/replace`,
-        suggest: () => 'Inject an interface/dependency instead of calling static method directly',
-    },
-    {
-        category: 'global-env',
-        regex: /process\.env\.(\w+)/,
-        breakability: 'easy',
-        describe: (m) => `Direct process.env.${m[1] ?? '?'} access — not injectable`,
-        suggest: (m) => `Extract to a config object or inject \`${m[1] ?? 'CONFIG'}\` via parameter`,
-    },
-    {
-        category: 'inline-new',
-        regex: /=\s*new\s+([A-Z]\w+)\s*\(/,
-        breakability: 'hard',
-        describe: (m) => `Inline \`new ${m[1] ?? '?'}()\` inside function — cannot be replaced`,
-        suggest: (m) => `Inject a factory or pass \`${m[1] ?? 'Dep'}Factory\` as a parameter`,
-    },
-    {
-        category: 'hardcoded-path',
-        regex: /['"`](\/[a-zA-Z0-9_\-/]+\.[a-zA-Z]{1,5})['"`]/,
-        breakability: 'easy',
-        describe: (m) => `Hardcoded file path: ${m[1] ?? '?'}`,
-        suggest: () => 'Move path to a config constant or inject via parameter',
-    },
-    {
-        category: 'hardcoded-url',
-        regex: /['"`](https?:\/\/[^'"`\s]+)['"`]/,
-        breakability: 'easy',
-        describe: (m) => `Hardcoded URL: ${(m[1] ?? '').slice(0, 60)}`,
-        suggest: () => 'Move URL to a config object or environment variable',
-    },
-    {
-        category: 'module-singleton',
-        regex: /^(?:import\s+\{[^}]+\}\s+from|const\s+\w+\s*=\s*require\s*\()/m,
-        breakability: 'moderate',
-        describe: () => 'Module-level singleton import — creates hidden dependency',
-        suggest: () => 'Pass the dependency via constructor or function parameter for testability',
-    },
-];
-// ---------------------------------------------------------------------------
-// Scanner
-// ---------------------------------------------------------------------------
-let seamCounter = 0;
-function makeSeamId() {
-    seamCounter++;
-    return `SM-${String(seamCounter).padStart(4, '0')}`;
-}
-/**
- * Scans a single file for seams.
- */
-async function scanFile(filePath) {
-    const analysis = await analyzeFile(filePath);
-    if (analysis === null) {
-        return [];
-    }
-    const seams = [];
-    for (const fn of analysis.functions) {
-        const bodyLines = fn.body.split('\n');
-        for (const pattern of SEAM_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;
-                    seams.push({
-                        id: makeSeamId(),
-                        category: pattern.category,
-                        file: filePath,
-                        line: absoluteLine,
-                        functionName: fn.name,
-                        description: pattern.describe(match),
-                        pattern: match[0],
-                        suggestion: pattern.suggest(match),
-                        breakability: pattern.breakability,
-                    });
-                }
-            }
-        }
-    }
-    return seams;
-}
-/**
- * Resolves the list of files to scan.
- */
-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 seams.
- */
-export async function findSeams(projectPath, files) {
-    seamCounter = 0;
-    const resolvedFiles = await resolveFiles(projectPath, files);
-    const BATCH = 20;
-    const allSeams = [];
-    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) {
-            allSeams.push(...r);
-        }
-    }
-    // Sort by breakability (hard first = most valuable to break), then file
-    const breakOrder = { hard: 0, moderate: 1, easy: 2 };
-    allSeams.sort((a, b) => {
-        const bk = breakOrder[a.breakability] - breakOrder[b.breakability];
-        if (bk !== 0) {
-            return bk;
-        }
-        return a.file.localeCompare(b.file);
-    });
-    const hardCount = allSeams.filter((s) => s.breakability === 'hard').length;
-    const modCount = allSeams.filter((s) => s.breakability === 'moderate').length;
-    const easyCount = allSeams.filter((s) => s.breakability === 'easy').length;
-    return {
-        projectPath,
-        filesScanned: resolvedFiles.length,
-        seams: allSeams,
-        summary: `Scanned ${resolvedFiles.length} files. Found ${allSeams.length} seams: ${hardCount} hard, ${modCount} moderate, ${easyCount} easy to break.`,
-    };
-}
-//# sourceMappingURL=seam-finder.js.map

package/dist/tools/legacy/characterize-legacy-code.d.ts

@@ -1,9 +0,0 @@
-import { z } from 'zod';
-import type { ToolResult, CharacterizeLegacyInput } from '../../types/index.js';
-export declare const CharacterizeLegacyCodeInputSchema: {
-    projectPath: z.ZodString;
-    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    outputFile: z.ZodOptional<z.ZodString>;
-};
-export declare function handleCharacterizeLegacyCode(args: CharacterizeLegacyInput): Promise<ToolResult>;
-//# sourceMappingURL=characterize-legacy-code.d.ts.map

package/dist/tools/legacy/characterize-legacy-code.js

@@ -1,63 +0,0 @@
-// Planu — tools/legacy/characterize-legacy-code.ts
-// Tool handler for characterize_legacy_code.
-import { z } from 'zod';
-import { writeFile, mkdir } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { generateCharacterizationTests } from '../../engine/legacy/characterization-generator.js';
-import { compactResult } from '../output-formatter.js';
-// ---------------------------------------------------------------------------
-// Input schema
-// ---------------------------------------------------------------------------
-export const CharacterizeLegacyCodeInputSchema = {
-    projectPath: z.string().max(4096).describe('Absolute path to the project root to analyze'),
-    files: z
-        .array(z.string())
-        .optional()
-        .describe('Optional list of absolute file paths to analyze. If omitted, scans src/**/*.{ts,js}'),
-    outputFile: z
-        .string()
-        .optional()
-        .describe('Absolute path where the generated test file will be written. Defaults to tests/characterization/characterization.test.ts'),
-};
-// ---------------------------------------------------------------------------
-// Handler
-// ---------------------------------------------------------------------------
-export async function handleCharacterizeLegacyCode(args) {
-    const { projectPath, files, outputFile } = args;
-    const result = await generateCharacterizationTests(projectPath, files, outputFile);
-    if (result.tests.length === 0) {
-        return compactResult(`## Characterization Tests\n\nNo functions found to characterize in ${result.filesAnalyzed} file(s).\n\nTip: ensure the target files export named functions.`);
-    }
-    // Write the generated test file
-    const outPath = result.outputFile;
-    const allTestCode = [
-        '// AUTO-GENERATED by Planu characterize_legacy_code',
-        '// Fill in the TODO assertions with observed output values.',
-        '// DO NOT delete these tests until proper unit tests replace them.',
-        '',
-        ...result.tests.map((t) => t.testCode),
-    ].join('\n\n');
-    await mkdir(dirname(outPath), { recursive: true });
-    await writeFile(outPath, allTestCode, 'utf-8');
-    const outRelative = outPath.startsWith(join(projectPath, ''))
-        ? outPath.slice(projectPath.length + 1)
-        : outPath;
-    const lines = [
-        `## Characterization Tests Generated`,
-        ``,
-        `**Files analyzed**: ${result.filesAnalyzed}`,
-        `**Test stubs generated**: ${result.tests.length}`,
-        `**Output**: \`${outRelative}\``,
-        ``,
-        `### Functions characterized`,
-    ];
-    for (const test of result.tests.slice(0, 20)) {
-        lines.push(`- \`${test.functionName}\` in \`${test.sourceFile}\``);
-    }
-    if (result.tests.length > 20) {
-        lines.push(`- _...and ${result.tests.length - 20} more_`);
-    }
-    lines.push(``, `### Next steps`, `1. Open \`${outRelative}\``, `2. Run each function with the sample inputs shown`, `3. Replace \`// TODO: assert current output\` with the observed value`, `4. Run the test suite — all characterization tests must pass before refactoring`);
-    return compactResult(lines.join('\n'));
-}
-//# sourceMappingURL=characterize-legacy-code.js.map

package/dist/tools/legacy/detect-hyrum-risks.d.ts

@@ -1,8 +0,0 @@
-import { z } from 'zod';
-import type { ToolResult, LegacyAnalysisInput } from '../../types/index.js';
-export declare const DetectHyrumRisksInputSchema: {
-    projectPath: z.ZodString;
-    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
-};
-export declare function handleDetectHyrumRisks(args: LegacyAnalysisInput): Promise<ToolResult>;
-//# sourceMappingURL=detect-hyrum-risks.d.ts.map

package/dist/tools/legacy/detect-hyrum-risks.js

@@ -1,47 +0,0 @@
-// Planu — tools/legacy/detect-hyrum-risks.ts
-// Tool handler for detect_hyrum_risks.
-import { z } from 'zod';
-import { scanHyrumRisks } from '../../engine/legacy/hyrum-scanner.js';
-import { compactResult, formatTable } from '../output-formatter.js';
-// ---------------------------------------------------------------------------
-// Input schema
-// ---------------------------------------------------------------------------
-export const DetectHyrumRisksInputSchema = {
-    projectPath: z.string().max(4096).describe('Absolute path to the project root to scan'),
-    files: z
-        .array(z.string())
-        .optional()
-        .describe('Optional list of absolute file paths to scan. If omitted, scans src/**/*.{ts,js}'),
-};
-// ---------------------------------------------------------------------------
-// Handler
-// ---------------------------------------------------------------------------
-export async function handleDetectHyrumRisks(args) {
-    const { projectPath, files } = args;
-    const result = await scanHyrumRisks(projectPath, files);
-    if (result.risks.length === 0) {
-        return compactResult(`## Hyrum Risk Scan\n\n${result.summary}\n\nNo observable behavior risks detected.`);
-    }
-    const tableRows = result.risks.slice(0, 30).map((r) => ({
-        ID: r.id,
-        Severity: r.severity,
-        Category: r.category,
-        Function: r.functionName,
-        File: r.file.split('/').slice(-2).join('/'),
-        Description: r.description.slice(0, 80),
-    }));
-    const table = formatTable(tableRows, ['ID', 'Severity', 'Category', 'Function', 'File', 'Description'], `Hyrum Risks (${result.risks.length})`);
-    const highRisks = result.risks.filter((r) => r.severity === 'high');
-    const highSection = highRisks.length > 0
-        ? [
-            ``,
-            `### High-Severity Risks (action required)`,
-            ...highRisks
-                .slice(0, 5)
-                .map((r) => `**${r.id}** \`${r.functionName}\` — ${r.description}\n` +
-                `\`\`\`\n${r.snippet}\n\`\`\``),
-        ].join('\n')
-        : '';
-    return compactResult([`## Hyrum Risk Detection`, ``, result.summary, ``, table, highSection].join('\n'));
-}
-//# sourceMappingURL=detect-hyrum-risks.js.map

package/dist/tools/legacy/refactor-with-safety-net.d.ts

@@ -1,10 +0,0 @@
-import { z } from 'zod';
-import type { ToolResult, RefactorSafetyNetInput } from '../../types/index.js';
-export declare const RefactorWithSafetyNetInputSchema: {
-    projectPath: z.ZodString;
-    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    coverageThreshold: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-};
-export declare function handleRefactorWithSafetyNet(args: RefactorSafetyNetInput): Promise<ToolResult>;
-//# sourceMappingURL=refactor-with-safety-net.d.ts.map

package/dist/tools/legacy/refactor-with-safety-net.js

@@ -1,55 +0,0 @@
-// Planu — tools/legacy/refactor-with-safety-net.ts
-// Tool handler for refactor_with_safety_net.
-import { z } from 'zod';
-import { buildSafetyNetPlan } from '../../engine/legacy/safety-net-orchestrator.js';
-import { compactResult } from '../output-formatter.js';
-// ---------------------------------------------------------------------------
-// Input schema
-// ---------------------------------------------------------------------------
-export const RefactorWithSafetyNetInputSchema = {
-    projectPath: z
-        .string()
-        .max(4096)
-        .describe('Absolute path to the project root to analyze and plan'),
-    files: z
-        .array(z.string())
-        .optional()
-        .describe('Optional list of absolute file paths to target. If omitted, scans src/**/*.{ts,js}'),
-    coverageThreshold: z
-        .number()
-        .min(0)
-        .max(100)
-        .optional()
-        .default(80)
-        .describe('Minimum coverage percentage required before refactoring. Default: 80'),
-    dryRun: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('If true, show the plan without executing any changes. Default: false (plan is always returned — this flag is reserved for future execution mode)'),
-};
-// ---------------------------------------------------------------------------
-// Handler
-// ---------------------------------------------------------------------------
-export async function handleRefactorWithSafetyNet(args) {
-    const { projectPath, files, coverageThreshold = 80 } = args;
-    const plan = await buildSafetyNetPlan(projectPath, files, coverageThreshold);
-    const lines = [`## Refactor with Safety Net`, ``, plan.summary, ``, `### Steps`];
-    for (const step of plan.steps) {
-        lines.push(`**${step.order}. ${step.label}** (~${step.estimatedMinutes} min)`);
-        lines.push(`   ${step.description}`);
-    }
-    if (plan.refactorSteps.length > 0) {
-        lines.push(``, `### Identified Refactor Actions`);
-        for (const rs of plan.refactorSteps.slice(0, 15)) {
-            const riskBadge = rs.risk === 'high' ? ' ⚠️ high risk' : rs.risk === 'medium' ? ' medium risk' : '';
-            lines.push(`- **${rs.pattern}**${riskBadge}: ${rs.change}`);
-        }
-        if (plan.refactorSteps.length > 15) {
-            lines.push(`- _...and ${plan.refactorSteps.length - 15} more_`);
-        }
-    }
-    lines.push(``, `### Coverage target`, `≥ ${plan.coverageBaseline}% line coverage required before starting refactoring.`, ``, `### Automated tools`, `- \`characterize_legacy_code\` — generates test stubs (Step 2)`, `- \`seams_detector\` — identifies injection points (Step 4)`, `- \`detect_hyrum_risks\` — flags observable behaviors to preserve`);
-    return compactResult(lines.join('\n'));
-}
-//# sourceMappingURL=refactor-with-safety-net.js.map

package/dist/tools/legacy/seams-detector.d.ts

@@ -1,8 +0,0 @@
-import { z } from 'zod';
-import type { ToolResult, LegacyAnalysisInput } from '../../types/index.js';
-export declare const SeamsDetectorInputSchema: {
-    projectPath: z.ZodString;
-    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
-};
-export declare function handleSeamsDetector(args: LegacyAnalysisInput): Promise<ToolResult>;
-//# sourceMappingURL=seams-detector.d.ts.map

package/dist/tools/legacy/seams-detector.js

@@ -1,47 +0,0 @@
-// Planu — tools/legacy/seams-detector.ts
-// Tool handler for seams_detector.
-import { z } from 'zod';
-import { findSeams } from '../../engine/legacy/seam-finder.js';
-import { compactResult, formatTable } from '../output-formatter.js';
-// ---------------------------------------------------------------------------
-// Input schema
-// ---------------------------------------------------------------------------
-export const SeamsDetectorInputSchema = {
-    projectPath: z.string().max(4096).describe('Absolute path to the project root to scan'),
-    files: z
-        .array(z.string())
-        .optional()
-        .describe('Optional list of absolute file paths to scan. If omitted, scans src/**/*.{ts,js}'),
-};
-// ---------------------------------------------------------------------------
-// Handler
-// ---------------------------------------------------------------------------
-export async function handleSeamsDetector(args) {
-    const { projectPath, files } = args;
-    const result = await findSeams(projectPath, files);
-    if (result.seams.length === 0) {
-        return compactResult(`## Seams Detector\n\n${result.summary}\n\nNo dependency break points detected.`);
-    }
-    const tableRows = result.seams.slice(0, 30).map((s) => ({
-        ID: s.id,
-        Breakability: s.breakability,
-        Category: s.category,
-        Function: s.functionName,
-        File: s.file.split('/').slice(-2).join('/'),
-        Suggestion: s.suggestion.slice(0, 80),
-    }));
-    const table = formatTable(tableRows, ['ID', 'Breakability', 'Category', 'Function', 'File', 'Suggestion'], `Seams Found (${result.seams.length})`);
-    const hardSeams = result.seams.filter((s) => s.breakability === 'hard');
-    const hardSection = hardSeams.length > 0
-        ? [
-            ``,
-            `### Hard-to-Break Seams (high priority)`,
-            ...hardSeams
-                .slice(0, 5)
-                .map((s) => `**${s.id}** \`${s.functionName}\` — ${s.description}\n` +
-                `_Suggestion_: ${s.suggestion}`),
-        ].join('\n')
-        : '';
-    return compactResult([`## Seams Detector`, ``, result.summary, ``, table, hardSection].join('\n'));
-}
-//# sourceMappingURL=seams-detector.js.map

package/dist/types/legacy.d.ts

@@ -1,151 +0,0 @@
-export type HyrumRiskCategory = 'exception-type' | 'return-shape' | 'ordering-guarantee' | 'null-vs-undefined' | 'error-message-text' | 'implicit-return';
-export interface HyrumRisk {
-    /** Unique identifier for the risk */
-    id: string;
-    /** Category of observable behavior risk */
-    category: HyrumRiskCategory;
-    /** File where the risk was detected */
-    file: string;
-    /** Line number (1-based) */
-    line: number;
-    /** Name of the function/method containing the risk */
-    functionName: string;
-    /** Human-readable description of the observable behavior */
-    description: string;
-    /** Severity: high = likely depended on, medium = possibly, low = unlikely */
-    severity: 'high' | 'medium' | 'low';
-    /** Code snippet showing the problematic pattern */
-    snippet: string;
-}
-export interface HyrumScanResult {
-    projectPath: string;
-    filesScanned: number;
-    risks: HyrumRisk[];
-    summary: string;
-}
-export type SeamCategory = 'static-call' | 'global-env' | 'inline-new' | 'hardcoded-path' | 'hardcoded-url' | 'module-singleton';
-export interface Seam {
-    /** Unique identifier for the seam */
-    id: string;
-    /** Category of the seam */
-    category: SeamCategory;
-    /** File where the seam was detected */
-    file: string;
-    /** Line number (1-based) */
-    line: number;
-    /** Name of the enclosing function/method */
-    functionName: string;
-    /** Human-readable description of the seam */
-    description: string;
-    /** The pattern that was matched */
-    pattern: string;
-    /** Suggested refactoring approach */
-    suggestion: string;
-    /** How easy it is to break this seam: easy | moderate | hard */
-    breakability: 'easy' | 'moderate' | 'hard';
-}
-export interface SeamScanResult {
-    projectPath: string;
-    filesScanned: number;
-    seams: Seam[];
-    summary: string;
-}
-export interface SampleInput {
-    /** Parameter name */
-    name: string;
-    /** Suggested sample value (as source code string) */
-    value: string;
-    /** Inferred TypeScript type */
-    type: string;
-}
-export interface CharacterizationTest {
-    /** Unique identifier */
-    id: string;
-    /** File being characterized */
-    sourceFile: string;
-    /** Function/method to characterize */
-    functionName: string;
-    /** Generated test stub code */
-    testCode: string;
-    /** Detected sample inputs for the function */
-    sampleInputs: SampleInput[];
-    /** Note to the developer about filling in expected values */
-    developerNote: string;
-}
-export interface CharacterizationResult {
-    projectPath: string;
-    filesAnalyzed: number;
-    tests: CharacterizationTest[];
-    outputFile: string;
-    summary: string;
-}
-export type SafetyNetStepStatus = 'pending' | 'in-progress' | 'done' | 'skipped' | 'failed';
-export interface SafetyNetStep {
-    /** Step number (1-based) */
-    order: number;
-    /** Short label for the step */
-    label: string;
-    /** Detailed description of what to do */
-    description: string;
-    /** Status of the step */
-    status: SafetyNetStepStatus;
-    /** Estimated effort in minutes */
-    estimatedMinutes: number;
-}
-export interface RefactorStep {
-    /** Target file to refactor */
-    file: string;
-    /** Description of what to change */
-    change: string;
-    /** Pattern: extract-function | inject-dependency | replace-singleton | introduce-seam */
-    pattern: 'extract-function' | 'inject-dependency' | 'replace-singleton' | 'introduce-seam';
-    /** Whether a test must exist before this step */
-    requiresTest: boolean;
-    /** Risk level for this step */
-    risk: 'low' | 'medium' | 'high';
-}
-export interface SafetyNetPlan {
-    projectPath: string;
-    targetFiles: string[];
-    coverageBaseline: number;
-    steps: SafetyNetStep[];
-    refactorSteps: RefactorStep[];
-    summary: string;
-}
-export interface LegacyFunctionInfo {
-    name: string;
-    line: number;
-    params: string[];
-    body: string;
-    snippet: string;
-}
-export interface LegacyFileAnalysis {
-    filePath: string;
-    functions: LegacyFunctionInfo[];
-    lines: string[];
-}
-export interface HyrumRiskPattern {
-    category: HyrumRiskCategory;
-    regex: RegExp;
-    severity: HyrumRisk['severity'];
-    describe: (match: RegExpMatchArray) => string;
-}
-export interface LegacySeamPattern {
-    category: SeamCategory;
-    regex: RegExp;
-    breakability: Seam['breakability'];
-    describe: (match: RegExpMatchArray) => string;
-    suggest: (match: RegExpMatchArray) => string;
-}
-export interface LegacyAnalysisInput {
-    projectPath: string;
-    files?: string[];
-}
-export interface CharacterizeLegacyInput extends LegacyAnalysisInput {
-    outputFile?: string;
-}
-export interface RefactorSafetyNetInput extends LegacyAnalysisInput {
-    coverageThreshold?: number;
-    dryRun?: boolean;
-}
-//# sourceMappingURL=legacy.d.ts.map

package/dist/types/legacy.js

@@ -1,5 +0,0 @@
-// Planu — legacy.ts
-// Types for Legacy Code Specialization (SPEC-480): characterization tests,
-// Hyrum risks, seams detection, and safety-net refactoring.
-export {};
-//# sourceMappingURL=legacy.js.map