@planu/cli 0.28.0 → 0.30.0

package/dist/engine/ci-generator/planu-steps.d.ts

@@ -0,0 +1,11 @@
+import type { GeneratePlanuCIInput, GeneratePlanuCIResult } from '../../types/index.js';
+/**
+ * Generate the markdown snippet for adding a planu spec badge to README.
+ */
+export declare function generateBadgeMarkdown(owner: string, repo: string): string;
+/**
+ * Generate a complete Planu CI check workflow with optional drift detection,
+ * PR comments, badge generation, and configurable severity thresholds.
+ */
+export declare function generatePlanuCI(input: GeneratePlanuCIInput): GeneratePlanuCIResult;
+//# sourceMappingURL=planu-steps.d.ts.map

package/dist/engine/ci-generator/planu-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planu-steps.d.ts","sourceRoot":"","sources":["../../../src/engine/ci-generator/planu-steps.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,oBAAoB,EACpB,qBAAqB,EAEtB,MAAM,sBAAsB,CAAC;AAY9B;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AAmPD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAwElF"}

package/dist/engine/ci-generator/planu-steps.js

@@ -0,0 +1,292 @@
+// ci-generator/planu-steps.ts — Generate Planu-specific CI workflow YAML (SPEC-066 AC-02..07)
+import { generatePlanuConfigYaml } from './planu-config.js';
+// -- Constants ---------------------------------------------------------------
+const DEFAULT_SPECS_DIR = 'docs/sdd/specs';
+const WORKFLOW_PATH = '.github/workflows/planu-check.yml';
+const COMMENT_MARKER = '<!-- planu-ci-report -->';
+// -- Badge generation --------------------------------------------------------
+/**
+ * Generate the markdown snippet for adding a planu spec badge to README.
+ */
+export function generateBadgeMarkdown(owner, repo) {
+    const url = `https://img.shields.io/endpoint?url=https://planu.dev/badge/${owner}/${repo}`;
+    return `[![Planu Specs](${url})](https://planu.dev)`;
+}
+/**
+ * Generate the badge update step YAML lines for the CI workflow.
+ * Runs only on main/master push and creates a badge JSON endpoint.
+ */
+function buildBadgeStepLines(indent) {
+    return [
+        `${indent}- name: Generate spec badge`,
+        `${indent}  if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'`,
+        `${indent}  run: |`,
+        `${indent}    TOTAL=$(echo "$PLANU_RESULTS" | grep -c "SPEC-" || echo "0")`,
+        `${indent}    ISSUES=$(echo "$PLANU_RESULTS" | grep -c "FAIL" || echo "0")`,
+        `${indent}    if [ "$ISSUES" = "0" ]; then`,
+        `${indent}      COLOR="brightgreen"`,
+        `${indent}      MSG="passing"`,
+        `${indent}    else`,
+        `${indent}      COLOR="red"`,
+        `${indent}      MSG="$ISSUES issues"`,
+        `${indent}    fi`,
+        `${indent}    echo "{\\"schemaVersion\\":1,\\"label\\":\\"planu\\",\\"message\\":\\"$MSG\\",\\"color\\":\\"$COLOR\\"}" > planu-badge.json`,
+        `${indent}  env:`,
+        `${indent}    PLANU_RESULTS: \${{ steps.validate.outputs.results }}`,
+    ];
+}
+// -- PR comment step ---------------------------------------------------------
+function buildCommentStepLines(indent) {
+    return [
+        `${indent}- name: Post results to PR`,
+        `${indent}  if: github.event_name == 'pull_request'`,
+        `${indent}  uses: actions/github-script@v7`,
+        `${indent}  with:`,
+        `${indent}    script: |`,
+        `${indent}      const marker = '${COMMENT_MARKER}';`,
+        `${indent}      const body = marker + '\\n' + process.env.PLANU_COMMENT;`,
+        `${indent}      const { data: comments } = await github.rest.issues.listComments({`,
+        `${indent}        owner: context.repo.owner,`,
+        `${indent}        repo: context.repo.repo,`,
+        `${indent}        issue_number: context.issue.number,`,
+        `${indent}      });`,
+        `${indent}      const existing = comments.find(c => c.body && c.body.includes(marker));`,
+        `${indent}      if (existing) {`,
+        `${indent}        await github.rest.issues.updateComment({`,
+        `${indent}          owner: context.repo.owner,`,
+        `${indent}          repo: context.repo.repo,`,
+        `${indent}          comment_id: existing.id,`,
+        `${indent}          body,`,
+        `${indent}        });`,
+        `${indent}      } else {`,
+        `${indent}        await github.rest.issues.createComment({`,
+        `${indent}          owner: context.repo.owner,`,
+        `${indent}          repo: context.repo.repo,`,
+        `${indent}          issue_number: context.issue.number,`,
+        `${indent}          body,`,
+        `${indent}        });`,
+        `${indent}      }`,
+        `${indent}  env:`,
+        `${indent}    PLANU_COMMENT: \${{ steps.validate.outputs.comment }}`,
+    ];
+}
+// -- Severity / exit code step -----------------------------------------------
+function buildSeverityStepLines(indent, threshold, failOnDrift) {
+    if (!failOnDrift) {
+        return [
+            `${indent}- name: Check severity threshold`,
+            `${indent}  run: echo "Drift detection is informational only (fail-on-drift=false)"`,
+        ];
+    }
+    const thresholdCondition = threshold === 'critical'
+        ? 'CRITICAL_COUNT=$(echo "$PLANU_RESULTS" | grep -c "CRITICAL" || echo "0") && [ "$CRITICAL_COUNT" -gt 0 ]'
+        : threshold === 'warning'
+            ? 'ISSUE_COUNT=$(echo "$PLANU_RESULTS" | grep -cE "(FAIL|DRIFT)" || echo "0") && [ "$ISSUE_COUNT" -gt 0 ]'
+            : 'true';
+    if (threshold === 'info') {
+        return [
+            `${indent}- name: Check severity threshold`,
+            `${indent}  run: echo "Severity threshold is info — always passes"`,
+        ];
+    }
+    return [
+        `${indent}- name: Check severity threshold`,
+        `${indent}  run: |`,
+        `${indent}    if ${thresholdCondition}; then`,
+        `${indent}      echo "::error::Planu specs have issues above ${threshold} threshold"`,
+        `${indent}      exit 1`,
+        `${indent}    fi`,
+        `${indent}    echo "All specs within ${threshold} threshold"`,
+        `${indent}  env:`,
+        `${indent}    PLANU_RESULTS: \${{ steps.validate.outputs.results }}`,
+    ];
+}
+// -- Drift detection step ----------------------------------------------------
+function buildDriftStepLines(indent, specsDir) {
+    return [
+        `${indent}- name: Detect spec drift`,
+        `${indent}  id: drift`,
+        `${indent}  run: |`,
+        `${indent}    CHANGED_FILES=$(git diff origin/main...HEAD --name-only 2>/dev/null || echo "")`,
+        `${indent}    echo "Changed files:"`,
+        `${indent}    echo "$CHANGED_FILES"`,
+        `${indent}    DRIFT_FOUND="false"`,
+        `${indent}    for spec_dir in ${specsDir}/*/; do`,
+        `${indent}      if [ -f "$spec_dir/technical.md" ] || [ -f "$spec_dir/FICHA-TECNICA.md" ]; then`,
+        `${indent}        TECH_FILE=$(ls "$spec_dir"technical.md "$spec_dir"FICHA-TECNICA.md 2>/dev/null | head -1)`,
+        `${indent}        SPEC_FILES=$(grep -oE 'src/[a-zA-Z0-9_./-]+' "$TECH_FILE" 2>/dev/null || echo "")`,
+        `${indent}        for sf in $SPEC_FILES; do`,
+        `${indent}          if echo "$CHANGED_FILES" | grep -q "$sf"; then`,
+        `${indent}            SPEC_NAME=$(basename "$spec_dir")`,
+        `${indent}            echo "::warning::Drift detected: $sf modified, belongs to $SPEC_NAME"`,
+        `${indent}            DRIFT_FOUND="true"`,
+        `${indent}          fi`,
+        `${indent}        done`,
+        `${indent}      fi`,
+        `${indent}    done`,
+        `${indent}    echo "drift-detected=$DRIFT_FOUND" >> $GITHUB_OUTPUT`,
+    ];
+}
+// -- Validate step -----------------------------------------------------------
+function buildValidateStepLines(indent, specsDir) {
+    return [
+        `${indent}- name: Validate specs`,
+        `${indent}  id: validate`,
+        `${indent}  run: |`,
+        `${indent}    RESULTS=""`,
+        `${indent}    COMMENT="## Planu CI -- Reporte de Specs\\n\\n"`,
+        `${indent}    COMMENT+="### Validacion de Specs\\n"`,
+        `${indent}    COMMENT+="| Spec | Estado | Criterios |\\n"`,
+        `${indent}    COMMENT+="|------|--------|-----------|\\n"`,
+        `${indent}    TOTAL=0`,
+        `${indent}    ISSUES=0`,
+        `${indent}    for spec_dir in ${specsDir}/*/; do`,
+        `${indent}      [ -d "$spec_dir" ] || continue`,
+        `${indent}      SPEC_NAME=$(basename "$spec_dir")`,
+        `${indent}      TOTAL=$((TOTAL + 1))`,
+        `${indent}      SPEC_FILE=$(ls "$spec_dir"spec.md "$spec_dir"HU.md 2>/dev/null | head -1)`,
+        `${indent}      if [ -z "$SPEC_FILE" ]; then`,
+        `${indent}        RESULTS+="$SPEC_NAME FAIL missing-spec\\n"`,
+        `${indent}        COMMENT+="| $SPEC_NAME | FAIL | missing spec.md |\\n"`,
+        `${indent}        ISSUES=$((ISSUES + 1))`,
+        `${indent}        continue`,
+        `${indent}      fi`,
+        `${indent}      CRITERIA=$(grep -c "^### AC-" "$SPEC_FILE" 2>/dev/null || echo "0")`,
+        `${indent}      PROGRESS_FILE=$(ls "$spec_dir"progress.md "$spec_dir"PROGRESS.md 2>/dev/null | head -1)`,
+        `${indent}      if [ -n "$PROGRESS_FILE" ]; then`,
+        `${indent}        DONE=$(grep -c "Completado\\|Done\\|DONE" "$PROGRESS_FILE" 2>/dev/null || echo "0")`,
+        `${indent}      else`,
+        `${indent}        DONE=0`,
+        `${indent}      fi`,
+        `${indent}      if [ "$DONE" -ge "$CRITERIA" ] && [ "$CRITERIA" -gt 0 ]; then`,
+        `${indent}        STATUS="PASS"`,
+        `${indent}        RESULTS+="$SPEC_NAME PASS $DONE/$CRITERIA\\n"`,
+        `${indent}      else`,
+        `${indent}        STATUS="FAIL"`,
+        `${indent}        ISSUES=$((ISSUES + 1))`,
+        `${indent}        RESULTS+="$SPEC_NAME FAIL $DONE/$CRITERIA\\n"`,
+        `${indent}      fi`,
+        `${indent}      COMMENT+="| $SPEC_NAME | $STATUS | $DONE/$CRITERIA |\\n"`,
+        `${indent}    done`,
+        `${indent}    COMMENT+="\\n### Resumen\\n"`,
+        `${indent}    COMMENT+="- Total specs verificadas: $TOTAL\\n"`,
+        `${indent}    COMMENT+="- Specs con problemas: $ISSUES\\n"`,
+        `${indent}    if [ "$TOTAL" = "0" ]; then`,
+        `${indent}      COMMENT="## Planu CI -- Reporte de Specs\\n\\nTodas las specs estan en orden."`,
+        `${indent}    fi`,
+        `${indent}    echo "results<<EOF" >> $GITHUB_OUTPUT`,
+        `${indent}    echo -e "$RESULTS" >> $GITHUB_OUTPUT`,
+        `${indent}    echo "EOF" >> $GITHUB_OUTPUT`,
+        `${indent}    echo "comment<<EOF" >> $GITHUB_OUTPUT`,
+        `${indent}    echo -e "$COMMENT" >> $GITHUB_OUTPUT`,
+        `${indent}    echo "EOF" >> $GITHUB_OUTPUT`,
+        `${indent}    echo "issues=$ISSUES" >> $GITHUB_OUTPUT`,
+    ];
+}
+// -- Workflow header builder --------------------------------------------------
+function buildWorkflowHeader(postComment, workingDirectory) {
+    const lines = [];
+    lines.push('name: Planu Spec Check');
+    lines.push('');
+    lines.push('on:');
+    lines.push('  push:');
+    lines.push('    branches: [main, master]');
+    lines.push('  pull_request:');
+    lines.push('    branches: [main, master, develop]');
+    lines.push('  workflow_dispatch:');
+    lines.push('');
+    if (postComment) {
+        lines.push('permissions:');
+        lines.push('  contents: read');
+        lines.push('  pull-requests: write');
+        lines.push('  issues: write');
+        lines.push('');
+    }
+    lines.push('jobs:');
+    lines.push('  planu-check:');
+    lines.push('    name: Planu Spec Validation');
+    lines.push('    runs-on: ubuntu-latest');
+    if (workingDirectory !== '.') {
+        lines.push(`    defaults:`);
+        lines.push(`      run:`);
+        lines.push(`        working-directory: ${workingDirectory}`);
+    }
+    return lines;
+}
+function buildConfigReadStep(ind) {
+    return [
+        `${ind}- name: Read .planu.yml config`,
+        `${ind}  id: config`,
+        `${ind}  run: |`,
+        `${ind}    if [ -f ".planu.yml" ]; then`,
+        `${ind}      echo "config-found=true" >> $GITHUB_OUTPUT`,
+        `${ind}      echo "Planu config found at .planu.yml"`,
+        `${ind}    else`,
+        `${ind}      echo "config-found=false" >> $GITHUB_OUTPUT`,
+        `${ind}      echo "No .planu.yml found, using defaults"`,
+        `${ind}    fi`,
+    ];
+}
+// -- Main generator ----------------------------------------------------------
+/**
+ * Generate a complete Planu CI check workflow with optional drift detection,
+ * PR comments, badge generation, and configurable severity thresholds.
+ */
+export function generatePlanuCI(input) {
+    const { specsDir = DEFAULT_SPECS_DIR, detectDrift = true, failOnDrift = true, severityThreshold = 'warning', postComment = true, badge = true, workingDirectory = '.', } = input;
+    const features = ['validate'];
+    const ind = '      ';
+    const lines = buildWorkflowHeader(postComment, workingDirectory);
+    lines.push('    steps:');
+    lines.push(`${ind}- name: Checkout code`);
+    lines.push(`${ind}  uses: actions/checkout@v4`);
+    lines.push(`${ind}  with:`);
+    lines.push(`${ind}    fetch-depth: 0`);
+    lines.push('');
+    features.push('planu-config');
+    lines.push(...buildConfigReadStep(ind));
+    lines.push('');
+    const resolvedSpecsDir = workingDirectory === '.' ? specsDir : `${workingDirectory}/${specsDir}`;
+    lines.push(...buildValidateStepLines(ind, resolvedSpecsDir));
+    lines.push('');
+    if (detectDrift) {
+        features.push('detect-drift');
+        lines.push(...buildDriftStepLines(ind, resolvedSpecsDir));
+        lines.push('');
+    }
+    if (postComment) {
+        features.push('pr-comment');
+        lines.push(...buildCommentStepLines(ind));
+        lines.push('');
+    }
+    if (badge) {
+        features.push('badge');
+        lines.push(...buildBadgeStepLines(ind));
+        lines.push('');
+    }
+    if (failOnDrift) {
+        features.push('fail-on-drift');
+    }
+    lines.push(...buildSeverityStepLines(ind, severityThreshold, failOnDrift));
+    lines.push('');
+    lines.push('    outputs:');
+    lines.push('      drift-detected: ${{ steps.drift.outputs.drift-detected }}');
+    lines.push('      issues: ${{ steps.validate.outputs.issues }}');
+    const workflowYaml = lines.join('\n') + '\n';
+    const planuConfigYaml = generatePlanuConfigYaml({
+        specsDir,
+        failOnDrift,
+        severityThreshold,
+        postComment,
+        badge,
+    });
+    const badgeMarkdown = generateBadgeMarkdown('{owner}', '{repo}');
+    return {
+        workflowYaml,
+        workflowPath: WORKFLOW_PATH,
+        planuConfigYaml,
+        badgeMarkdown,
+        features,
+    };
+}
+//# sourceMappingURL=planu-steps.js.map

package/dist/engine/ci-generator/planu-steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planu-steps.js","sourceRoot":"","sources":["../../../src/engine/ci-generator/planu-steps.ts"],"names":[],"mappings":"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"}

package/dist/engine/code-transforms/transform-engine.d.ts

@@ -0,0 +1,7 @@
+import { type TransformRequest, type TransformResult } from '../../types/index.js';
+/**
+ * Execute a code transform based on the request intent.
+ * Returns a TransformResult with the transformed source, changes list, and timing.
+ */
+export declare function executeTransform(request: TransformRequest): TransformResult;
+//# sourceMappingURL=transform-engine.d.ts.map

package/dist/engine/code-transforms/transform-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-engine.d.ts","sourceRoot":"","sources":["../../../src/engine/code-transforms/transform-engine.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EASrB,MAAM,sBAAsB,CAAC;AAQ9B;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAiC3E"}

package/dist/engine/code-transforms/transform-engine.js

@@ -0,0 +1,67 @@
+// engine/code-transforms/transform-engine.ts — Transform orchestrator (AC-01).
+// Validates intent, dispatches to the correct transform implementation, measures timing.
+import { TRANSFORM_INTENTS, } from '../../types/index.js';
+import { renameSymbol } from './typescript/rename-symbol.js';
+import { addTypes } from './typescript/add-types.js';
+import { addErrorHandling } from './typescript/add-error-handling.js';
+import { modernizeSyntax } from './typescript/modernize-syntax.js';
+import { extractInterface } from './typescript/extract-interface.js';
+import { addJSDoc } from './typescript/add-jsdoc.js';
+/**
+ * Execute a code transform based on the request intent.
+ * Returns a TransformResult with the transformed source, changes list, and timing.
+ */
+export function executeTransform(request) {
+    const start = performance.now();
+    const fileName = request.fileName ?? 'input.ts';
+    // Validate intent
+    if (!TRANSFORM_INTENTS.includes(request.intent)) {
+        return {
+            success: false,
+            transformed: request.source,
+            changes: [],
+            durationMs: performance.now() - start,
+            error: `Unknown transform intent: '${request.intent}'. Valid intents: ${TRANSFORM_INTENTS.join(', ')}`,
+        };
+    }
+    try {
+        const result = dispatch(request.intent, request.source, request.options, fileName);
+        return {
+            success: true,
+            transformed: result.transformed,
+            changes: result.changes,
+            durationMs: performance.now() - start,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            transformed: request.source,
+            changes: [],
+            durationMs: performance.now() - start,
+            error: message,
+        };
+    }
+}
+function dispatch(intent, source, options, fileName) {
+    switch (intent) {
+        case 'rename-symbol':
+            return renameSymbol(source, options, fileName);
+        case 'add-types':
+            return addTypes(source, options, fileName);
+        case 'add-error-handling':
+            return addErrorHandling(source, options, fileName);
+        case 'modernize-syntax':
+            return modernizeSyntax(source, options, fileName);
+        case 'extract-interface':
+            return extractInterface(source, options, fileName);
+        case 'add-jsdoc':
+            return addJSDoc(source, options, fileName);
+        /* v8 ignore next 4 -- exhaustive check: unreachable thanks to TRANSFORM_INTENTS validation */
+        default: {
+            throw new Error(`Unhandled transform intent: ${String(intent)}`);
+        }
+    }
+}
+//# sourceMappingURL=transform-engine.js.map

package/dist/engine/code-transforms/transform-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-engine.js","sourceRoot":"","sources":["../../../src/engine/code-transforms/transform-engine.ts"],"names":[],"mappings":"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"}

package/dist/engine/code-transforms/typescript/add-error-handling.d.ts

@@ -0,0 +1,6 @@
+import type { AddErrorHandlingOptions, ErrorHandlingResult } from '../../../types/index.js';
+/**
+ * Add try/catch error handling to async functions.
+ */
+export declare function addErrorHandling(source: string, options: AddErrorHandlingOptions, fileName: string): ErrorHandlingResult;
+//# sourceMappingURL=add-error-handling.d.ts.map

package/dist/engine/code-transforms/typescript/add-error-handling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-error-handling.d.ts","sourceRoot":"","sources":["../../../../src/engine/code-transforms/typescript/add-error-handling.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,uBAAuB,EAGvB,mBAAmB,EACpB,MAAM,yBAAyB,CAAC;AAoDjC;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,uBAAuB,EAChC,QAAQ,EAAE,MAAM,GACf,mBAAmB,CAiDrB"}

package/dist/engine/code-transforms/typescript/add-error-handling.js

@@ -0,0 +1,92 @@
+// engine/code-transforms/typescript/add-error-handling.ts — (AC-04).
+// Wraps async function bodies with try/catch blocks.
+import { getTypeScript, parseSource, getLineNumber, createChange } from './ast-utils.js';
+function isAsyncFunction(ts, node) {
+    if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isArrowFunction(node)) {
+        const mods = ts.getModifiers(node);
+        return mods?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) === true;
+    }
+    return false;
+}
+function getNodeName(ts, node, sourceFile) {
+    if ((ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name) {
+        return node.name.getText(sourceFile);
+    }
+    return '<anonymous>';
+}
+function buildCatchBlock(style, fnName) {
+    switch (style) {
+        case 'return-null':
+            return [
+                `catch (error: unknown) {`,
+                `    console.error('Error in ${fnName}:', error);`,
+                `    return null;`,
+                `  }`,
+            ].join('\n');
+        case 'log-and-rethrow':
+            return [
+                `catch (error: unknown) {`,
+                `    console.error('Error in ${fnName}:', error);`,
+                `    throw error;`,
+                `  }`,
+            ].join('\n');
+        default: // 'rethrow'
+            return [`catch (error: unknown) {`, `    throw error;`, `  }`].join('\n');
+    }
+}
+function hasExistingTryCatch(ts, body) {
+    for (const stmt of body.statements) {
+        if (ts.isTryStatement(stmt)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Add try/catch error handling to async functions.
+ */
+export function addErrorHandling(source, options, fileName) {
+    const ts = getTypeScript();
+    const sourceFile = parseSource(source, fileName);
+    const style = options.style ?? 'rethrow';
+    const targets = [];
+    function visit(node) {
+        if (isAsyncFunction(ts, node)) {
+            let body;
+            if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
+                body = node.body;
+            }
+            else if (ts.isArrowFunction(node) && ts.isBlock(node.body)) {
+                body = node.body;
+            }
+            if (body && !hasExistingTryCatch(ts, body)) {
+                const name = getNodeName(ts, node, sourceFile);
+                targets.push({
+                    name,
+                    bodyStart: body.getStart(sourceFile) + 1,
+                    bodyEnd: body.getEnd() - 1,
+                    line: getLineNumber(sourceFile, node.getStart(sourceFile)),
+                });
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    if (targets.length === 0) {
+        return { transformed: source, changes: [] };
+    }
+    // Apply in reverse order
+    targets.sort((a, b) => b.bodyStart - a.bodyStart);
+    let result = source;
+    const changes = [];
+    for (const target of targets) {
+        const innerBody = result.slice(target.bodyStart, target.bodyEnd);
+        const catchBlock = buildCatchBlock(style, target.name);
+        const wrapped = `\n  try {${innerBody}} ${catchBlock}\n`;
+        result = result.slice(0, target.bodyStart) + wrapped + result.slice(target.bodyEnd);
+        changes.push(createChange(target.line, `Wrapped '${target.name}' with try/catch (${style})`));
+    }
+    changes.sort((a, b) => a.line - b.line);
+    return { transformed: result, changes };
+}
+//# sourceMappingURL=add-error-handling.js.map

package/dist/engine/code-transforms/typescript/add-error-handling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-error-handling.js","sourceRoot":"","sources":["../../../../src/engine/code-transforms/typescript/add-error-handling.ts"],"names":[],"mappings":"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"}

package/dist/engine/code-transforms/typescript/add-jsdoc.d.ts

@@ -0,0 +1,6 @@
+import type { AddJSDocOptions, AddJSDocResult } from '../../../types/index.js';
+/**
+ * Add JSDoc comments to functions and methods that don't have them.
+ */
+export declare function addJSDoc(source: string, options: AddJSDocOptions, fileName: string): AddJSDocResult;
+//# sourceMappingURL=add-jsdoc.d.ts.map

package/dist/engine/code-transforms/typescript/add-jsdoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-jsdoc.d.ts","sourceRoot":"","sources":["../../../../src/engine/code-transforms/typescript/add-jsdoc.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,eAAe,EAGf,cAAc,EACf,MAAM,yBAAyB,CAAC;AAwDjC;;GAEG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,MAAM,GACf,cAAc,CAwChB"}

package/dist/engine/code-transforms/typescript/add-jsdoc.js

@@ -0,0 +1,83 @@
+// engine/code-transforms/typescript/add-jsdoc.ts — Add JSDoc comments (AC-07).
+// Generates JSDoc stubs with @param, @returns, @throws for functions.
+import { getTypeScript, parseSource, getLineNumber, createChange } from './ast-utils.js';
+function hasJSDoc(source, nodeStart) {
+    // Check if there is already a JSDoc comment before this node
+    const before = source.slice(Math.max(0, nodeStart - 200), nodeStart);
+    return before.trimEnd().endsWith('*/');
+}
+function bodyHasThrow(ts, body) {
+    if (ts.isThrowStatement(body)) {
+        return true;
+    }
+    let found = false;
+    ts.forEachChild(body, (child) => {
+        if (bodyHasThrow(ts, child)) {
+            found = true;
+        }
+    });
+    return found;
+}
+function buildJSDoc(ts, node, sourceFile, options) {
+    const lines = ['/**'];
+    /* v8 ignore next 1 -- FunctionDeclaration without name is extremely rare in valid TS */
+    const name = node.name ? node.name.getText(sourceFile) : 'anonymous';
+    lines.push(` * ${name}`);
+    if (options.includeParams !== false) {
+        for (const param of node.parameters) {
+            const pName = param.name.getText(sourceFile);
+            const pType = param.type ? param.type.getText(sourceFile) : 'unknown';
+            lines.push(` * @param {${pType}} ${pName}`);
+        }
+    }
+    if (options.includeReturns !== false && node.type) {
+        const retType = node.type.getText(sourceFile);
+        if (retType !== 'void') {
+            lines.push(` * @returns {${retType}}`);
+        }
+    }
+    if (options.includeThrows !== false && node.body && bodyHasThrow(ts, node.body)) {
+        lines.push(` * @throws {Error}`);
+    }
+    lines.push(' */');
+    return lines.join('\n');
+}
+/**
+ * Add JSDoc comments to functions and methods that don't have them.
+ */
+export function addJSDoc(source, options, fileName) {
+    const ts = getTypeScript();
+    const sourceFile = parseSource(source, fileName);
+    const insertions = [];
+    function visit(node) {
+        if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
+            const start = node.getStart(sourceFile);
+            if (!hasJSDoc(source, start) && node.name) {
+                const name = node.name.getText(sourceFile);
+                const doc = buildJSDoc(ts, node, sourceFile, options);
+                insertions.push({
+                    position: start,
+                    text: doc + '\n',
+                    line: getLineNumber(sourceFile, start),
+                    name,
+                });
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    if (insertions.length === 0) {
+        return { transformed: source, changes: [] };
+    }
+    // Apply in reverse order
+    insertions.sort((a, b) => b.position - a.position);
+    let result = source;
+    const changes = [];
+    for (const ins of insertions) {
+        result = result.slice(0, ins.position) + ins.text + result.slice(ins.position);
+        changes.push(createChange(ins.line, `Added JSDoc to '${ins.name}'`));
+    }
+    changes.sort((a, b) => a.line - b.line);
+    return { transformed: result, changes };
+}
+//# sourceMappingURL=add-jsdoc.js.map

package/dist/engine/code-transforms/typescript/add-jsdoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-jsdoc.js","sourceRoot":"","sources":["../../../../src/engine/code-transforms/typescript/add-jsdoc.ts"],"names":[],"mappings":"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"}

package/dist/engine/code-transforms/typescript/add-types.d.ts

@@ -0,0 +1,3 @@
+import type { AddTypesOptions, AddTypesResult } from '../../../types/index.js';
+export declare function addTypes(source: string, _options: AddTypesOptions, fileName: string): AddTypesResult;
+//# sourceMappingURL=add-types.d.ts.map

package/dist/engine/code-transforms/typescript/add-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-types.d.ts","sourceRoot":"","sources":["../../../../src/engine/code-transforms/typescript/add-types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,eAAe,EAGf,cAAc,EACf,MAAM,yBAAyB,CAAC;AA0LjC,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,MAAM,GACf,cAAc,CAwBhB"}