@planu/cli 3.9.11 → 3.9.13

package/dist/engine/implementation-brief/generator.js

@@ -1,139 +0,0 @@
-// engine/implementation-brief/generator.ts — SPEC-586: Orchestrate implementation brief generation
-import { writeFile, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-import { scanReusableHelpers } from './helpers-scanner.js';
-import { findTestPatterns } from './test-pattern-matcher.js';
-import { extractConventions } from './convention-extractor.js';
-import { enumerateExtensionPoints } from './extension-points.js';
-import { predictTestBreaks } from '../impact-detector/test-break-predictor.js';
-const MAX_HELPERS = 10;
-function renderBrief(brief) {
-    const lines = [];
-    lines.push(`# Implementation Brief — ${brief.specId}`);
-    lines.push(`_Generated ${brief.generatedAt}_`);
-    lines.push('');
-    lines.push('## Reusable helpers');
-    if (brief.reusableHelpers.length === 0) {
-        lines.push('_None found._');
-    }
-    else {
-        for (const h of brief.reusableHelpers) {
-            lines.push(`- **${h.symbol}** — \`${h.path}:${h.line}\` — ${h.purpose}`);
-        }
-    }
-    lines.push('');
-    lines.push('## Test patterns');
-    if (brief.testPatterns.length === 0) {
-        lines.push('_No similar tests found._');
-    }
-    else {
-        for (const t of brief.testPatterns) {
-            lines.push(`- \`${t.testPath}\` — ${t.whyRelevant}`);
-        }
-    }
-    lines.push('');
-    lines.push('## Applicable conventions');
-    if (brief.conventions.excerpts.length === 0) {
-        lines.push('_No matching rules found._');
-    }
-    else {
-        for (const e of brief.conventions.excerpts) {
-            lines.push(`### ${e.rule}`);
-            lines.push('');
-            lines.push(e.excerpt);
-            lines.push('');
-        }
-    }
-    lines.push('## Existing extension points');
-    if (brief.extensionPoints.length === 0) {
-        lines.push('_None detected._');
-    }
-    else {
-        for (const ep of brief.extensionPoints) {
-            lines.push(`- \`${ep}\``);
-        }
-    }
-    lines.push('');
-    lines.push('## Anticipated test breaks');
-    if (brief.anticipatedBreaks.length === 0) {
-        lines.push('_No anticipated breaks detected._');
-    }
-    else {
-        for (const b of brief.anticipatedBreaks) {
-            lines.push(`- \`${b.testPath}\` — pattern: **${b.pattern}** — ${b.remediation}`);
-        }
-    }
-    lines.push('');
-    return lines.join('\n');
-}
-function renderPrompt(specId, description, brief) {
-    const lines = [];
-    lines.push(`# Implementation prompt — ${specId}`);
-    lines.push('');
-    // What to build — first non-empty line of description (up to 120 chars)
-    const goal = description
-        .split('\n')
-        .find((l) => l.trim().length > 0)
-        ?.slice(0, 120) ?? specId;
-    lines.push('## What to build');
-    lines.push(goal.trim());
-    lines.push('');
-    /* v8 ignore start */
-    // Files to CREATE — infer from helpers/extension points
-    if (brief.extensionPoints.length > 0) {
-        lines.push('## Files to CREATE (exact paths)');
-        for (const ep of brief.extensionPoints.slice(0, 5)) {
-            lines.push(`- ${ep}`);
-        }
-        lines.push('');
-    }
-    // Reusable helpers — key symbols to import (avoids discovery)
-    if (brief.reusableHelpers.length > 0) {
-        lines.push('## Reusable helpers (import, do not rewrite)');
-        for (const h of brief.reusableHelpers.slice(0, 5)) {
-            lines.push(`- \`${h.symbol}\` from \`${h.path}\` — ${h.purpose}`);
-        }
-        lines.push('');
-    }
-    // Anticipated test breaks
-    if (brief.anticipatedBreaks.length > 0) {
-        lines.push('## Tests that will break (exact fixes)');
-        for (const b of brief.anticipatedBreaks) {
-            lines.push(`- \`${b.testPath}\` — ${b.remediation}`);
-        }
-        lines.push('');
-    }
-    /* v8 ignore stop */
-    lines.push('## Verify with');
-    lines.push('```');
-    lines.push('pnpm typecheck && pnpm lint && pnpm test');
-    lines.push('```');
-    return lines.join('\n');
-}
-export async function generateImplementationBrief(input) {
-    const { specId, specPath, projectPath, description, tags, target, scope } = input;
-    const [helpers, testPatterns, conventions, extensionPoints, anticipatedBreaks] = await Promise.all([
-        scanReusableHelpers(projectPath, description, tags).catch(() => []),
-        findTestPatterns(projectPath, description, tags, scope).catch(() => []),
-        extractConventions(projectPath, tags, target, scope).catch(() => ({ excerpts: [] })),
-        enumerateExtensionPoints(projectPath).catch(() => []),
-        predictTestBreaks(projectPath).catch(() => []),
-    ]);
-    const brief = {
-        specId,
-        generatedAt: new Date().toISOString(),
-        reusableHelpers: helpers.slice(0, MAX_HELPERS),
-        testPatterns,
-        conventions,
-        extensionPoints,
-        anticipatedBreaks,
-    };
-    const specDir = dirname(specPath);
-    await mkdir(specDir, { recursive: true });
-    // Write both implementation-brief.md and prompt.md (SPEC-629) in parallel
-    await Promise.all([
-        writeFile(join(specDir, 'implementation-brief.md'), renderBrief(brief), 'utf-8'),
-        writeFile(join(specDir, 'prompt.md'), renderPrompt(specId, description, brief), 'utf-8'),
-    ]);
-}
-//# sourceMappingURL=generator.js.map

package/dist/engine/implementation-brief/helpers-scanner.d.ts

@@ -1,3 +0,0 @@
-import type { ReusableHelper } from '../../types/index.js';
-export declare function scanReusableHelpers(projectPath: string, description: string, tags: string[]): Promise<ReusableHelper[]>;
-//# sourceMappingURL=helpers-scanner.d.ts.map

package/dist/engine/implementation-brief/helpers-scanner.js

@@ -1,163 +0,0 @@
-// engine/implementation-brief/helpers-scanner.ts — SPEC-586: Semantic search for reusable helpers
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { join, relative, extname } from 'node:path';
-const MAX_FILES = 300;
-const MAX_DEPTH = 4;
-const TOP_N = 10;
-const CODE_EXT = new Set(['.ts', '.js', '.py', '.go', '.rs', '.java', '.kt', '.rb', '.cs']);
-function extractKeywords(text) {
-    return text
-        .toLowerCase()
-        .replace(/[^a-z0-9\s-]/g, ' ')
-        .split(/\s+/)
-        .filter((w) => w.length > 3)
-        .filter((w) => !STOP_WORDS.has(w));
-}
-const STOP_WORDS = new Set([
-    'this',
-    'that',
-    'with',
-    'from',
-    'have',
-    'will',
-    'when',
-    'then',
-    'given',
-    'spec',
-    'planu',
-    'tool',
-    'file',
-    'path',
-    'type',
-    'into',
-    'also',
-    'each',
-    'only',
-    'over',
-    'such',
-    'more',
-    'some',
-    'after',
-    'must',
-]);
-function scoreText(text, keywords) {
-    const lower = text.toLowerCase();
-    let score = 0;
-    for (const kw of keywords) {
-        if (lower.includes(kw)) {
-            score += kw.length;
-        }
-    }
-    return score;
-}
-async function scanDir(dir, projectPath, keywords, results, depth, budget) {
-    if (depth > MAX_DEPTH || budget.remaining <= 0) {
-        return;
-    }
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        if (budget.remaining <= 0) {
-            break;
-        }
-        if (entry.startsWith('.') || entry === 'node_modules' || entry === 'dist') {
-            continue;
-        }
-        const full = join(dir, entry);
-        let s;
-        try {
-            s = await stat(full);
-        }
-        catch {
-            continue;
-        }
-        if (s.isDirectory()) {
-            await scanDir(full, projectPath, keywords, results, depth + 1, budget);
-        }
-        else if (CODE_EXT.has(extname(entry))) {
-            const b = budget;
-            b.remaining -= 1;
-            const rel = relative(projectPath, full);
-            const score = scoreText(rel, keywords);
-            if (score > 0) {
-                results.push({ path: rel, score });
-            }
-        }
-    }
-}
-function parseFunctionSymbol(line) {
-    const match = /export\s+(?:async\s+)?function\s+(\w+)|export\s+const\s+(\w+)\s*=|export\s+(?:type|interface|class)\s+(\w+)/.exec(line);
-    if (!match) {
-        return null;
-    }
-    return match[1] ?? match[2] ?? match[3] ?? null;
-}
-function extractPurpose(lines, exportLine) {
-    for (let i = exportLine - 1; i >= Math.max(0, exportLine - 3); i--) {
-        const line = lines[i]?.trim() ?? '';
-        if (line.startsWith('//') || line.startsWith('*') || line.startsWith('/**')) {
-            return line.replace(/^[/*\s]+/, '').slice(0, 80);
-        }
-    }
-    return 'helper function';
-}
-async function extractHelpers(filePath, keywords, projectPath) {
-    let content;
-    try {
-        content = await readFile(filePath, 'utf-8');
-    }
-    catch {
-        return [];
-    }
-    const lines = content.split('\n');
-    const helpers = [];
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (!line.includes('export')) {
-            continue;
-        }
-        const symbol = parseFunctionSymbol(line);
-        if (!symbol) {
-            continue;
-        }
-        const symbolScore = scoreText(symbol, keywords);
-        if (symbolScore === 0) {
-            continue;
-        }
-        helpers.push({
-            symbol,
-            path: relative(projectPath, filePath),
-            line: i + 1,
-            purpose: extractPurpose(lines, i),
-        });
-    }
-    return helpers;
-}
-export async function scanReusableHelpers(projectPath, description, tags) {
-    const srcDir = join(projectPath, 'src');
-    const keywords = extractKeywords(`${description} ${tags.join(' ')}`);
-    if (keywords.length === 0) {
-        return [];
-    }
-    const candidates = [];
-    const budget = { remaining: MAX_FILES };
-    await scanDir(srcDir, projectPath, keywords, candidates, 0, budget);
-    candidates.sort((a, b) => b.score - a.score);
-    const top = candidates.slice(0, 20);
-    const helpers = [];
-    for (const c of top) {
-        const full = join(projectPath, c.path);
-        const extracted = await extractHelpers(full, keywords, projectPath);
-        helpers.push(...extracted);
-        if (helpers.length >= TOP_N) {
-            break;
-        }
-    }
-    return helpers.slice(0, TOP_N);
-}
-//# sourceMappingURL=helpers-scanner.js.map

package/dist/engine/implementation-brief/test-pattern-matcher.d.ts

@@ -1,3 +0,0 @@
-import type { TestPatternMatch } from '../../types/index.js';
-export declare function findTestPatterns(projectPath: string, description: string, tags: string[], scope: string): Promise<TestPatternMatch[]>;
-//# sourceMappingURL=test-pattern-matcher.d.ts.map

package/dist/engine/implementation-brief/test-pattern-matcher.js

@@ -1,90 +0,0 @@
-// engine/implementation-brief/test-pattern-matcher.ts — SPEC-586: Find similar test patterns
-import { readdir, stat } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-const MAX_TEST_FILES = 200;
-const TOP_N = 3;
-function extractKeywords(text) {
-    return text
-        .toLowerCase()
-        .replace(/[^a-z0-9\s]/g, ' ')
-        .split(/\s+/)
-        .filter((w) => w.length > 3);
-}
-function scoreMatch(filePath, keywords) {
-    const lower = filePath.toLowerCase();
-    let score = 0;
-    for (const kw of keywords) {
-        if (lower.includes(kw)) {
-            score += kw.length;
-        }
-    }
-    return score;
-}
-async function collectTestFiles(dir, results, budget, depth) {
-    if (budget.remaining <= 0 || depth > 5) {
-        return;
-    }
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        if (budget.remaining <= 0) {
-            break;
-        }
-        if (entry.startsWith('.') || entry === 'node_modules') {
-            continue;
-        }
-        const full = join(dir, entry);
-        let s;
-        try {
-            s = await stat(full);
-        }
-        catch {
-            continue;
-        }
-        if (s.isDirectory()) {
-            await collectTestFiles(full, results, budget, depth + 1);
-        }
-        else if (entry.endsWith('.test.ts') || entry.endsWith('.test.js')) {
-            const b = budget;
-            b.remaining -= 1;
-            results.push(full);
-        }
-    }
-}
-function explainRelevance(filePath, keywords) {
-    const matched = [];
-    const lower = filePath.toLowerCase();
-    for (const kw of keywords) {
-        if (lower.includes(kw)) {
-            matched.push(kw);
-        }
-    }
-    return matched.length > 0
-        ? `matches keywords: ${matched.slice(0, 3).join(', ')}`
-        : 'structural similarity';
-}
-export async function findTestPatterns(projectPath, description, tags, scope) {
-    const testsDir = join(projectPath, 'tests');
-    const keywords = extractKeywords(`${description} ${tags.join(' ')} ${scope}`);
-    if (keywords.length === 0) {
-        return [];
-    }
-    const testFiles = [];
-    const budget = { remaining: MAX_TEST_FILES };
-    await collectTestFiles(testsDir, testFiles, budget, 0);
-    const scored = testFiles
-        .map((f) => ({ path: f, score: scoreMatch(relative(projectPath, f), keywords) }))
-        .filter((x) => x.score > 0)
-        .sort((a, b) => b.score - a.score)
-        .slice(0, TOP_N);
-    return scored.map((s) => ({
-        testPath: relative(projectPath, s.path),
-        whyRelevant: explainRelevance(relative(projectPath, s.path), keywords),
-    }));
-}
-//# sourceMappingURL=test-pattern-matcher.js.map

package/dist/engine/risk-analyzer/risk-generator.d.ts

@@ -1,6 +0,0 @@
-import type { RiskAnalysisContext, RiskRegister } from '../../types/index.js';
-/**
- * Generate an initial risk register from spec metadata.
- */
-export declare function generateRiskRegister(ctx: RiskAnalysisContext, totalBudget?: number): RiskRegister;
-//# sourceMappingURL=risk-generator.d.ts.map

package/dist/engine/risk-analyzer/risk-generator.js

@@ -1,94 +0,0 @@
-function buildRiskTemplates(ctx) {
-    const templates = [];
-    if (ctx.difficulty >= 4) {
-        templates.push({
-            description: 'High complexity may lead to estimation overrun',
-            category: 'technical',
-            probability: 40,
-            impactDays: 3,
-            mitigationPlan: 'Break down into smaller tasks and reassess estimates',
-        });
-    }
-    if (ctx.scope === 'cross-module' || ctx.scope === 'architectural') {
-        templates.push({
-            description: 'Cross-module changes risk breaking existing integrations',
-            category: 'integration',
-            probability: 35,
-            impactDays: 2,
-            mitigationPlan: 'Add integration tests covering all affected modules before merging',
-        });
-    }
-    if (ctx.dependencyCount > 3) {
-        templates.push({
-            description: 'Multiple dependencies increase coordination overhead',
-            category: 'dependency',
-            probability: 30,
-            impactDays: 2,
-            mitigationPlan: 'Establish dependency contracts early and monitor for version conflicts',
-        });
-    }
-    if (ctx.risk === 'high' || ctx.risk === 'critical') {
-        templates.push({
-            description: 'Spec flagged as high-risk requires extra review',
-            category: 'organizational',
-            probability: 50,
-            impactDays: 3,
-            mitigationPlan: 'Schedule mandatory peer review and add approval gates before deployment',
-        });
-    }
-    if (ctx.tags.includes('security')) {
-        templates.push({
-            description: 'Security-sensitive changes require audit',
-            category: 'security',
-            probability: 25,
-            impactDays: 4,
-            mitigationPlan: 'Engage security team for review and run SAST/DAST tools',
-        });
-    }
-    if (ctx.fileCount > 10) {
-        templates.push({
-            description: 'Large number of files increases merge conflict risk',
-            category: 'technical',
-            probability: 30,
-            impactDays: 1,
-            mitigationPlan: 'Use feature flags and incremental PRs to reduce merge surface',
-        });
-    }
-    return templates;
-}
-function buildRisks(ctx, templates) {
-    return templates.map((t, index) => ({
-        id: `R${index + 1}`,
-        description: t.description,
-        category: t.category,
-        probability: t.probability,
-        impactUsd: 0,
-        impactDays: t.impactDays,
-        owner: '',
-        status: 'identified',
-        mitigationPlan: t.mitigationPlan,
-        specId: ctx.specId,
-    }));
-}
-function computeAggregateScore(risks, totalBudgetDays) {
-    const rawScore = risks.reduce((acc, r) => acc + (r.probability / 100) * r.impactDays, 0);
-    const denominator = Math.max(totalBudgetDays, 1);
-    const score = (rawScore / denominator) * 100;
-    return Math.min(score, 100);
-}
-/**
- * Generate an initial risk register from spec metadata.
- */
-export function generateRiskRegister(ctx, totalBudget) {
-    const budgetDays = totalBudget ?? 30;
-    const templates = buildRiskTemplates(ctx);
-    const risks = buildRisks(ctx, templates);
-    const aggregateRiskScore = computeAggregateScore(risks, budgetDays);
-    return {
-        specId: ctx.specId,
-        risks,
-        aggregateRiskScore,
-        generatedAt: new Date().toISOString(),
-    };
-}
-//# sourceMappingURL=risk-generator.js.map

package/dist/types/implementation-brief.d.ts

@@ -1,41 +0,0 @@
-export interface ReusableHelper {
-    symbol: string;
-    path: string;
-    line: number;
-    purpose: string;
-}
-export interface TestPatternMatch {
-    testPath: string;
-    whyRelevant: string;
-}
-export interface ConventionExcerpt {
-    rule: string;
-    excerpt: string;
-}
-export type AnticipatedBreakPattern = 'tool-count' | 'snapshot' | 'license-plans-sync' | 'streams-anchor' | 'other';
-export interface AnticipatedBreak {
-    testPath: string;
-    pattern: AnticipatedBreakPattern;
-    remediation: string;
-}
-export interface ImplementationBrief {
-    specId: string;
-    generatedAt: string;
-    reusableHelpers: ReusableHelper[];
-    testPatterns: TestPatternMatch[];
-    conventions: {
-        excerpts: ConventionExcerpt[];
-    };
-    extensionPoints: string[];
-    anticipatedBreaks: AnticipatedBreak[];
-}
-export interface ImplementationBriefInput {
-    specId: string;
-    specPath: string;
-    projectPath: string;
-    description: string;
-    tags: string[];
-    target: string;
-    scope: string;
-}
-//# sourceMappingURL=implementation-brief.d.ts.map

package/dist/types/implementation-brief.js

@@ -1,3 +0,0 @@
-// types/implementation-brief.ts — SPEC-586: Implementation brief types
-export {};
-//# sourceMappingURL=implementation-brief.js.map