refactor-large-function

name	refactor-large-function
description	Pick one large function flagged by ESLint max-lines-per-function and refactor it into smaller, focused helpers without breaking tests.

Refactor Large Function

An ESLint complexity or max-lines-per-function rule is producing warnings for functions that are too long. Pick one of those functions (not from extension.ts, which is intentionally monolithic) and refactor it into smaller, focused private helpers.

Step 1 - Identify the target

Run ESLint with the complexity rules to get the current list of violations:

cd vscode-extension && node_modules/.bin/eslint src --rule '{"max-lines-per-function": ["warn", 80]}' --format stylish 2>&1 | grep "Lines/Fn\|max-lines-per-function" | head -20

Or, if the project already has the rule configured, just run:

cd vscode-extension && node_modules/.bin/eslint src 2>&1 | grep "max-lines-per-function\|Lines/Fn" | head -20

Choose one function to refactor, following these priorities:

1. Skip src/extension.ts - it is intentionally large and hard to test in isolation.
2. Prefer files that already have unit tests (check test/unit/ for a matching test file).
3. Among the remaining candidates, pick the one with the clearest logical sections (wizard steps, processing phases, format branches, etc.) - those decompose most cleanly.

Step 2 - Read the instructions file

Before touching any code, read the relevant sub-project instructions file. For vscode-extension/ work, read .github/instructions/vscode-extension.instructions.md.

Step 3 - Understand the function

Read the full function body and identify natural decomposition boundaries:

• Wizard / multi-step UI flows: each step becomes a private method returning null on cancellation.
• Format dispatch (e.g. JSONL vs JSON vs delta): each format branch becomes its own function.
• Multi-phase processing: setup / main loop / finalization each become their own function.
• Complex sub-operations inside a branch that push complexity above the threshold: extract them too.

Introduce small result interfaces or types at the top of the file (not exported) to carry data between steps cleanly, rather than long parameter lists.

Step 4 - Run the baseline tests

Before changing anything, compile and run the existing unit tests to establish a green baseline:

cd vscode-extension
node_modules/.bin/tsc.cmd --noEmit          # type-check
npm run test:node                            # unit tests

Record which tests cover the target file so you know what to watch.

Step 5 - Refactor

Apply the extraction. Rules:

• The public/exported API must not change - only internal structure changes.
• Each extracted helper should have a single clear responsibility, stated in its name.
• Private methods use a leading _ prefix to signal they are internal helpers.
• Return null (not undefined) from a helper to signal user cancellation or an unrecoverable error; the caller does an early if (!result) { return; } guard.
• Do not add new comments unless the code is genuinely non-obvious after extraction.
• Keep new helpers in the same file unless they are independently reusable - do not create new files just to reduce line counts.

Step 6 - Lint the changed file

cd vscode-extension && node_modules/.bin/eslint src/path/to/changed-file.ts

All new warnings introduced by your changes must be resolved before proceeding. Pre-existing warnings on other functions in the same file are acceptable - do not fix unrelated code.

Step 7 - Run the full test suite and build

cd vscode-extension
node_modules/.bin/tsc.cmd --noEmit          # type-check
npm run test:node                            # unit tests
node esbuild.js --production                # production bundle

All tests must pass and the build must succeed. If a test fails, fix the refactoring - do not modify the tests unless the test itself was wrong before your change.

Step 8 - Commit

Write a commit in this format:

refactor: extract <FunctionName> into focused private methods

<One or two sentences describing which logical sections were extracted
and why the split makes sense.>

Co-authored-by: Copilot <[e-mail]>

Step 9 - Open a PR

Open a pull request to main. The PR description should:

• Lead with the motivation (ESLint rule violation, cognitive overhead).
• List the extracted helpers in a small table (method name | responsibility).
• Confirm that all unit tests pass and the production build succeeds.
• Note any pre-existing warnings that were not introduced by this change.

Constraints

• Only modify the one source file being refactored (plus its test file if a test needs updating to import a newly-exported helper, which should be rare).
• Do not fix pre-existing ESLint warnings on other functions in the same file.
• Do not change any exported function signatures or public class method signatures.
• Do not add new test files - rely on the existing test suite to verify correctness.
• If tsc or unit tests fail after your change, revert and choose a different decomposition strategy rather than patching around the failure.