From 688debffafa71faec61a5b92ed0840dec87ab697 Mon Sep 17 00:00:00 2001 From: Sebastian Warnholz Date: Mon, 2 Mar 2026 19:42:13 +0000 Subject: [PATCH 1/3] Update agents.md --- .opencode/skills/run-unit-tests/SKILL.md | 22 ++ AGENTS.md | 325 ++++++----------------- 2 files changed, 96 insertions(+), 251 deletions(-) create mode 100644 .opencode/skills/run-unit-tests/SKILL.md diff --git a/.opencode/skills/run-unit-tests/SKILL.md b/.opencode/skills/run-unit-tests/SKILL.md new file mode 100644 index 0000000..045b14b --- /dev/null +++ b/.opencode/skills/run-unit-tests/SKILL.md @@ -0,0 +1,22 @@ +--- +name: run-unit-tests +description: Executes project compilation, linting, and unit tests using npm. +metadata: + audience: developers + framework: npm +--- + +## What I do +I provide the standard commands needed to compile the code, check for linting errors, and execute the unit test suite. + +## When to use me +Use this skill whenever you need to verify that recent code changes haven't broken the build, or when the user explicitly asks to run tests. + +## Instructions +When instructed to run tests, use your bash/terminal tool to execute the following command at the root of the project: + +```bash +npm run compile && npm run lint && npm run test:unit +``` + +If the command fails, analyze the output to determine if it was a compilation error, a linting issue, or a failing unit test, and assist the user in fixing the problem. diff --git a/AGENTS.md b/AGENTS.md index 46d8be5..d8d9ac1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,28 +13,36 @@ This is a VS Code extension called "Python Smart Execute" that intelligently sen - **Watch mode (auto-recompile)**: `npm run watch` - **Lint**: `npm run lint` - **Lint with auto-fix**: `npm run lint -- --fix` -- **Run all tests**: `npm run test:unit` (runs logic tests using Mocha directly; xvfb-run is unavailable in dev-container) +- **Run all unit tests**: `npm run test:unit` - **Prepublish**: `npm run vscode:prepublish` -### Testing - - **Compile & lint**: `npm run compile && npm run lint` - - **Unit tests**: `npm run test:unit` (runs logic tests with Mocha; integration tests require xvfb and are unavailable in dev-container) - - **Test structure**: Behavior-driven tests (e.g., `smartSelect.test.ts`) and unit tests (e.g., `selectionUtils.test.ts`) are colocated with implementation code in `src/test/suite/{module}/` +### Running Single Tests +- **Single test file**: `npm run compile && npx mocha --ui tdd out/test/suite/path/to/test.js` +- **Tests matching pattern**: `npm run test:unit -- --grep "pattern"` +- **Example**: `npm run compile && npx mocha --ui tdd out/test/suite/smartExecute/smartSelect.test.js` -### Development Workflow -1. `npm install` - Install dependencies (includes xvfb for headless testing) +### Skill +Use the `run-unit-tests` skill to compile, lint, and run unit tests in one step. + +### Testing Notes +- Unit tests use Mocha with TDD interface (`suite`/`test`) +- Integration tests require xvfb and are unavailable in dev-container +- Test files are colocated with implementation in `src/test/suite/{module}/` + +## Development Workflow + +1. `npm install` - Install dependencies 2. `npm run watch` - Start watch mode during development 3. Press `F5` in VS Code to launch Extension Development Host -4. `npm run test:unit` - Run unit tests during implementation (integration tests require xvfb and are unavailable in dev-container) +4. `npm run test:unit` - Run unit tests during implementation ## Code Style Guidelines -### TypeScript Specific Rules +### TypeScript Rules #### Variable Declarations - **Always** use `const` or `let`. **Never** use `var` - Use `const` by default, only use `let` when reassignment is needed -- Example: `const config = vscode.workspace.getConfiguration(...)` #### Modules and Exports - Use ES6 modules (`import`/`export`) @@ -53,27 +61,6 @@ This is a VS Code extension called "Python Smart Execute" that intelligently sen - Use arrow functions for anonymous functions/callbacks - Use `lowerCamelCase` for function names -#### Code Structure (from existing codebase) - -```typescript -// File structure pattern: -import * as vscode from "vscode"; - -export function activate(context: vscode.ExtensionContext) { - // Main extension logic -} - -export function deactivate() {} - -// Helper functions (exported for testing) -export function findNextCodeLine(...) { ... } -export function isDecorator(text: string) { ... } - -// Private helper functions -function getConfigEngine(): string { ... } -function smartSelect() { ... } -``` - #### Strings and Types - Use single quotes for string literals: `'text'` - Use template literals for interpolation: `` `${variable}` `` @@ -81,7 +68,7 @@ function smartSelect() { ... } - **Avoid** `any` type - prefer `unknown` or specific types - **Avoid** type assertions (`x as SomeType`) and non-nullability assertions (`y!`) -#### Naming Conventions +### Naming Conventions - **UpperCamelCase**: Classes, interfaces, types, enums, decorators - **lowerCamelCase**: Variables, parameters, functions, methods, properties - **CONSTANT_CASE**: Global constants and enum values @@ -90,50 +77,33 @@ function smartSelect() { ... } ### Import Organization - Group imports: Node.js built-ins, third-party, local modules - Use `import * as vscode from "vscode"` pattern for VS Code API -- Example from codebase: -```typescript -import * as vscode from "vscode"; -import * as path from 'path'; -import { runTests } from '@vscode/test-electron'; -``` +- Example: + ```typescript + import * as vscode from "vscode"; + import * as path from 'path'; + import { runTests } from '@vscode/test-electron'; + ``` ### Error Handling - Use try/catch blocks for async operations - Return early to reduce nesting -- Example from codebase: -```typescript -async function main() { - try { - await runTests({ extensionDevelopmentPath, extensionTestsPath }); - } catch (err) { - console.error('Failed to run tests', err); - process.exit(1); - } -} -``` +- Example: + ```typescript + async function main() { + try { + await runTests({ extensionDevelopmentPath, extensionTestsPath }); + } catch (err) { + console.error('Failed to run tests', err); + process.exit(1); + } + } + ``` -### Comments and Documentation +### Comments - Use `/** */` for documentation comments - Use `//` for implementation comments - Document *why*, not *what* -- **Do not** declare types in `@param` blocks (redundant in TypeScript) - -## Configuration Files - -### ESLint Configuration -- Uses ESLint 9 with TypeScript support -- Key rules enforced: - - `@typescript-eslint/naming-convention`: warn - - `curly`: warn (always use braces) - - `eqeqeq`: warn (always use ===) - - `@typescript-eslint/no-unused-vars`: warn with `argsIgnorePattern: "^_"` - -### TypeScript Configuration -- Target: ES6 -- Module: CommonJS -- Output directory: `out/` -- Strict mode enabled -- Root directory: `src/` +- **Do not** add comments unless necessary ## Project Structure @@ -150,27 +120,23 @@ src/ │ ├── selection.ts # Smart code selection utilities │ └── helpers.ts # Shared helper functions ├── test/ -│ ├── runTest.ts # Test runner -│ ├── runUnitTests.ts # Unit test runner +│ ├── runTest.ts # Integration test runner (requires xvfb) +│ ├── runUnitTests.ts # Unit test runner (no VS Code required) │ └── suite/ -│ ├── index.ts # Test suite setup -│ ├── extension.test.ts -│ ├── mocks.ts # VS Code API mocks -│ ├── smartExecute/ # Smart execution tests -│ │ ├── selection.test.ts # Implementation tests for selection utilities -│ │ ├── selectionUtils.test.ts # Unit tests for utility functions -│ │ ├── smartSelect.test.ts # Behavior-driven tests for smartSelect -│ │ └── execution.test.ts -│ ├── blockFinder.test.ts -│ ├── blockNavigator.test.ts -│ └── multiLineStatement.test.ts -├── package.json # Extension manifest -├── tsconfig.json # TypeScript config -├── eslint.config.mjs # ESLint config -└── DEVELOPMENT.md # Development guide +│ ├── index.ts # Test suite setup +│ ├── mocks.ts # VS Code API mocks for unit testing +│ ├── vscode.mock.ts # VS Code module mock +│ ├── smartExecute/ # Smart execution tests +│ └── navigation/ # Navigation tests ``` -## Extension Specific Patterns +## Extension-Specific Patterns + +### Command Registration +- Register commands in `activate` function using `context.subscriptions.push` +- Use `vscode.commands.registerCommand` for command registration +- Access configuration with `vscode.workspace.getConfiguration` +- Handle editor state with `vscode.window.activeTextEditor` ### Module Organization - **navigation/**: Python block navigation utilities (jump to next/previous code blocks) @@ -178,182 +144,39 @@ src/ - Functions are exported for testability - Tests colocated with modules in `src/test/suite/{module}/` -### VS Code Extension Development -- Register commands in `activate` function using `context.subscriptions.push` -- Use `vscode.commands.registerCommand` for command registration -- Access configuration with `vscode.workspace.getConfiguration` -- Handle editor state with `vscode.window.activeTextEditor` - ### Code Selection and Execution - Extension intelligently selects Python code blocks - Handles decorators, indentation, and code block boundaries - Supports multi-line statements (dictionaries, function calls, nested brackets) - Supports both Python REPL and Jupyter execution engines - Includes cursor stepping functionality after execution -- **SmartSelect Behavior**: - - Single line selection when smart selection is disabled - - Function/class selection with decorators - - Control flow selection (if/elif/else, try/except/finally) - - Multi-block document handling (targets specific blocks) - - Edge case handling (comments, empty lines, whitespace) - - Multiline statement detection (brackets, parentheses, braces) using bracket balance tracking - -### Block Navigation -- Commands: `pythonJumpNextBlock`, `pythonJumpPreviousBlock` -- Handles multi-line statements (open parentheses, brackets) -- Finds block boundaries (functions, classes, if/elif/else/try) - -## Development Best Practices - -1. **Before committing**: Always run `npm run test:unit` (unit tests only; full suite requires xvfb and is unavailable in dev-container) -2. **Use F5**: Launch Extension Development Host for testing -3. **Follow existing patterns**: Codebase has consistent structure and style -4. **Export for testing**: Make helper functions exportable for testability -5. **Configuration aware**: Extension behavior configurable via VS Code settings -6. **Error handling**: Always handle async errors gracefully -7. **Type safety**: Maintain strict TypeScript compliance ---- +## Testing Guidelines -## Test-Specific String Formatting and Comparison +### Test Structure +- Use Mocha TDD interface: `suite()` and `test()` +- Group related tests in nested suites +- Use descriptive test names -### 1. Multiline String Formatting in Tests -When defining multiline strings for test cases, use **template literals** (`` ` ``) to preserve exact formatting, including indentation, line breaks, and whitespace. This is critical for testing Python code selection logic, where formatting directly impacts behavior. +### Mock Data +- Use `MockTextDocument` and `MockTextEditor` from `src/test/suite/mocks.ts` +- Define multiline content with template literals to preserve formatting +- Use `assert.strictEqual` for string comparisons -#### Examples: -- **Template Literals for Python Code Blocks**: - ```typescript - const pythonCode = ` - @decorator - def example_function(): - if True: - print("Hello, world!") - `; - ``` - This ensures that indentation and line breaks are preserved exactly as written. - -- **Handling Edge Cases**: - Use template literals to define strings with mixed indentation or empty lines: - ```typescript - const mixedIndentation = ` - def example(): - if True: - print("Indented") - print("Not indented") - `; - ``` - ---- - -### 2. String Comparison Best Practices -#### Choosing the Right Assertion -- **Use `assert.strictEqual`** for string comparisons to ensure both content and type are validated. - ```typescript - assert.strictEqual(actualSelection, expectedSelection); - ``` -- **Avoid `assert.equal`** unless you explicitly want loose equality checks. - -#### Handling Whitespace and Newlines -- Preserve whitespace and newlines in test strings, as they are critical for Python code selection logic. -- **Trailing Newlines**: Be explicit about including or excluding trailing newlines in the expected string. Mismatches will cause test failures. - -#### Debugging Mismatches -- Log `actual` and `expected` values with escape characters when assertions fail to debug mismatches: - ```typescript - console.log(`Expected: ${JSON.stringify(expectedSelection)}`); - console.log(`Actual: ${JSON.stringify(actualSelection)}`); - ``` - ---- - -### 3. Mock Data Construction -#### Constructing Mock Content -- Use the `MockTextDocument` class (defined in `mocks.ts`) to simulate VS Code's `TextDocument` API for testing. -- Define mock content using template literals to ensure consistency with real-world scenarios: - ```typescript - const mockDocument = new MockTextDocument(` - @decorator - def example_function(): - print("Hello, world!") - `); - ``` - -#### Guidelines for `expectedSelection` -- Define `expectedSelection` strings using template literals to match the exact formatting of the expected output: - ```typescript - const expectedSelection = ` - @decorator - def example_function(): - print("Hello, world!") - `; - ``` -- Ensure mock content mirrors real-world scenarios, such as: - - Python functions with decorators. - - Multi-line statements (e.g., dictionaries, function calls). - - Edge cases like empty lines or mixed indentation. - ---- - -### 4. Test Case Structure for String-Heavy Logic -#### Structuring Test Cases -- Group test cases by scenario (e.g., "should select a function with decorators," "should handle multi-line statements"). -- Use descriptive test names to clarify the expected behavior: - ```typescript - test("should select a function with decorators", () => { ... }); - test("should handle multi-line statements", () => { ... }); - ``` - -#### Helper Functions for String Comparison -- While exact string matching is preferred, you can define helper functions to simplify comparisons for complex cases: - ```typescript - function normalizeWhitespace(text: string): string { - return text.replace(/\s+/g, " ").trim(); - } - ``` - Use this sparingly, as it may mask formatting issues in Python code. - -#### Example Test Case +### Mocking Configuration ```typescript -test("should select a function with decorators", () => { - const document = new MockTextDocument(` - @decorator - def example_function(): - print("Hello, world!") - `); - const selection = smartSelect(document, new vscode.Position(2, 0)); - const expectedSelection = ` - @decorator - def example_function(): - print("Hello, world!") - `; - assert.strictEqual(selection, expectedSelection); -}); +const originalGetConfig = getConfigSmartExecute; +(getConfigSmartExecute as unknown as () => boolean) = () => true; +// ... test code ... +(getConfigSmartExecute as unknown as () => boolean) = originalGetConfig; ``` ---- - -### Key Takeaways -1. **Use template literals** for multiline strings to preserve exact formatting. -2. **Prefer `assert.strictEqual`** for string comparisons to ensure precision. -3. **Log escape characters** when debugging mismatches to identify whitespace or newline issues. -4. **Construct mock data** using `MockTextDocument` and template literals to mirror real-world scenarios. -5. **Structure test cases** to validate multiline string outputs, grouping them by scenario for clarity. - -## VS Code Integration - -### Key Bindings (Extension Contribution) -- `Ctrl+Enter`: (Smart) Execute selection or line and step cursor -- `Ctrl+Alt+Down`: Navigate to next code block -- `Ctrl+Alt+Up`: Navigate to previous code block - -### Extension Dependencies -- `ms-python.python`: Python extension -- `ms-toolsai.jupyter`: Jupyter extension -- VS Code API version: ^1.96.0 - -## Memory and Performance +## Development Best Practices -- Keep command handlers lightweight -- Use async/await for non-blocking operations -- Dispose resources properly in `deactivate` function -- Minimize memory usage in extension lifecycle +1. **Before committing**: Run `npm run test:unit` to verify all tests pass +2. **Use F5**: Launch Extension Development Host for manual testing +3. **Follow existing patterns**: Codebase has consistent structure and style +4. **Export for testing**: Make helper functions exportable for testability +5. **Configuration aware**: Extension behavior configurable via VS Code settings +6. **Error handling**: Always handle async errors gracefully +7. **Type safety**: Maintain strict TypeScript compliance From f98cb3e9c06d1c7818243d12a25d720dd101f401 Mon Sep 17 00:00:00 2001 From: Sebastian Warnholz Date: Mon, 2 Mar 2026 19:59:53 +0000 Subject: [PATCH 2/3] Remove conductor and development docs --- DEVELOPMENT.md | 88 ----- conductor/code_styleguides/general.md | 23 -- conductor/code_styleguides/javascript.md | 51 --- conductor/code_styleguides/python.md | 37 -- conductor/code_styleguides/typescript.md | 43 --- conductor/index.md | 14 - conductor/product-guidelines.md | 12 - conductor/product.md | 18 - conductor/setup_state.json | 1 - conductor/tech-stack.md | 18 - conductor/tracks.md | 13 - .../automated_block_testing_20260127/index.md | 5 - .../metadata.json | 8 - .../automated_block_testing_20260127/plan.md | 44 --- .../automated_block_testing_20260127/spec.md | 28 -- .../tracks/modernize_dev_20260126/index.md | 5 - .../modernize_dev_20260126/metadata.json | 8 - .../tracks/modernize_dev_20260126/plan.md | 23 -- .../tracks/modernize_dev_20260126/spec.md | 21 -- conductor/workflow.md | 333 ------------------ 20 files changed, 793 deletions(-) delete mode 100644 DEVELOPMENT.md delete mode 100644 conductor/code_styleguides/general.md delete mode 100644 conductor/code_styleguides/javascript.md delete mode 100644 conductor/code_styleguides/python.md delete mode 100644 conductor/code_styleguides/typescript.md delete mode 100644 conductor/index.md delete mode 100644 conductor/product-guidelines.md delete mode 100644 conductor/product.md delete mode 100644 conductor/setup_state.json delete mode 100644 conductor/tech-stack.md delete mode 100644 conductor/tracks.md delete mode 100644 conductor/tracks/automated_block_testing_20260127/index.md delete mode 100644 conductor/tracks/automated_block_testing_20260127/metadata.json delete mode 100644 conductor/tracks/automated_block_testing_20260127/plan.md delete mode 100644 conductor/tracks/automated_block_testing_20260127/spec.md delete mode 100644 conductor/tracks/modernize_dev_20260126/index.md delete mode 100644 conductor/tracks/modernize_dev_20260126/metadata.json delete mode 100644 conductor/tracks/modernize_dev_20260126/plan.md delete mode 100644 conductor/tracks/modernize_dev_20260126/spec.md delete mode 100644 conductor/workflow.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index fdf60c1..0000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,88 +0,0 @@ -# Development Guide - -This document provides instructions for setting up the development environment and contributing to the Python Smart Execute extension. - -## Prerequisites - -Before you begin, ensure you have the following installed: -- [Node.js](https://nodejs.org/) (version 20 or higher recommended) -- [npm](https://www.npmjs.com/) (usually bundled with Node.js) -- [VS Code](https://code.visualstudio.com/) - -### Extension Dependencies -This extension depends on the following VS Code extensions: -- [Python extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-python.python) -- [Jupyter extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) - -## Getting Started - -1. **Clone the repository:** - ```bash - git clone https://github.com/inwtlab/python-smart-execute.git - cd python-smart-execute - ``` - -2. **Install dependencies:** - ```bash - npm install - ``` - -## Build and Run - -### Using npm Commands -- **Compile the project:** - ```bash - npm run compile - ``` -- **Watch mode (automatically recompile on changes):** - ```bash - npm run watch - ``` - -### Using VS Code "Run and Debug" -1. Open the project in VS Code. -2. Press `F5` or go to the **Run and Debug** view and select **Run Extension**. -3. This will open a new "Extension Development Host" window where the extension is active. - -## Testing and Linting - -### Linting -We use ESLint 9 to maintain code quality. To run the linter: -```bash -npm run lint -``` -To automatically fix common issues: -```bash -npm run lint -- --fix -``` - -### Testing -We use Mocha for testing. We have separated unit tests (which can run in any environment) from integration tests (which require a VS Code instance). - -- **Run all tests (including integration):** - ```bash - npm test - ``` - Note: This requires a display server (e.g., `xvfb-run -a npm test` on Linux). - -- **Run only unit tests (headless safe):** - ```bash - npm run test:unit - ``` - These tests verify the core logic without launching VS Code. - -- **Run integration tests specifically:** - ```bash - npm run test:integration - ``` - -The test runner will: -1. Compile the project. -2. Run the linter. -3. Execute the selected test suite. - -## Project Structure -- `src/extension.ts`: The main entry point for the extension. -- `src/test/`: Contains the test suite and test runner. -- `eslint.config.mjs`: ESLint configuration. -- `tsconfig.json`: TypeScript configuration. diff --git a/conductor/code_styleguides/general.md b/conductor/code_styleguides/general.md deleted file mode 100644 index dfcc793..0000000 --- a/conductor/code_styleguides/general.md +++ /dev/null @@ -1,23 +0,0 @@ -# General Code Style Principles - -This document outlines general coding principles that apply across all languages and frameworks used in this project. - -## Readability -- Code should be easy to read and understand by humans. -- Avoid overly clever or obscure constructs. - -## Consistency -- Follow existing patterns in the codebase. -- Maintain consistent formatting, naming, and structure. - -## Simplicity -- Prefer simple solutions over complex ones. -- Break down complex problems into smaller, manageable parts. - -## Maintainability -- Write code that is easy to modify and extend. -- Minimize dependencies and coupling. - -## Documentation -- Document *why* something is done, not just *what*. -- Keep documentation up-to-date with code changes. diff --git a/conductor/code_styleguides/javascript.md b/conductor/code_styleguides/javascript.md deleted file mode 100644 index 123f504..0000000 --- a/conductor/code_styleguides/javascript.md +++ /dev/null @@ -1,51 +0,0 @@ -# Google JavaScript Style Guide Summary - -This document summarizes key rules and best practices from the Google JavaScript Style Guide. - -## 1. Source File Basics -- **File Naming:** All lowercase, with underscores (`_`) or dashes (`-`). Extension must be `.js`. -- **File Encoding:** UTF-8. -- **Whitespace:** Use only ASCII horizontal spaces (0x20). Tabs are forbidden for indentation. - -## 2. Source File Structure -- New files should be ES modules (`import`/`export`). -- **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.** -- **Imports:** Do not use line-wrapped imports. The `.js` extension in import paths is mandatory. - -## 3. Formatting -- **Braces:** Required for all control structures (`if`, `for`, `while`, etc.), even single-line blocks. Use K&R style ("Egyptian brackets"). -- **Indentation:** +2 spaces for each new block. -- **Semicolons:** Every statement must be terminated with a semicolon. -- **Column Limit:** 80 characters. -- **Line-wrapping:** Indent continuation lines at least +4 spaces. -- **Whitespace:** Use single blank lines between methods. No trailing whitespace. - -## 4. Language Features -- **Variable Declarations:** Use `const` by default, `let` if reassignment is needed. **`var` is forbidden.** -- **Array Literals:** Use trailing commas. Do not use the `Array` constructor. -- **Object Literals:** Use trailing commas and shorthand properties. Do not use the `Object` constructor. -- **Classes:** Do not use JavaScript getter/setter properties (`get name()`). Provide ordinary methods instead. -- **Functions:** Prefer arrow functions for nested functions to preserve `this` context. -- **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for multi-line strings or complex interpolation. -- **Control Structures:** Prefer `for-of` loops. `for-in` loops should only be used on dict-style objects. -- **`this`:** Only use `this` in class constructors, methods, or in arrow functions defined within them. -- **Equality Checks:** Always use identity operators (`===` / `!==`). - -## 5. Disallowed Features -- `with` keyword. -- `eval()` or `Function(...string)`. -- Automatic Semicolon Insertion. -- Modifying builtin objects (`Array.prototype.foo = ...`). - -## 6. Naming -- **Classes:** `UpperCamelCase`. -- **Methods & Functions:** `lowerCamelCase`. -- **Constants:** `CONSTANT_CASE` (all uppercase with underscores). -- **Non-constant Fields & Variables:** `lowerCamelCase`. - -## 7. JSDoc -- JSDoc is used on all classes, fields, and methods. -- Use `@param`, `@return`, `@override`, `@deprecated`. -- Type annotations are enclosed in braces (e.g., `/** @param {string} userName */`). - -*Source: [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)* diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md deleted file mode 100644 index b684577..0000000 --- a/conductor/code_styleguides/python.md +++ /dev/null @@ -1,37 +0,0 @@ -# Google Python Style Guide Summary - -This document summarizes key rules and best practices from the Google Python Style Guide. - -## 1. Python Language Rules -- **Linting:** Run `pylint` on your code to catch bugs and style issues. -- **Imports:** Use `import x` for packages/modules. Use `from x import y` only when `y` is a submodule. -- **Exceptions:** Use built-in exception classes. Do not use bare `except:` clauses. -- **Global State:** Avoid mutable global state. Module-level constants are okay and should be `ALL_CAPS_WITH_UNDERSCORES`. -- **Comprehensions:** Use for simple cases. Avoid for complex logic where a full loop is more readable. -- **Default Argument Values:** Do not use mutable objects (like `[]` or `{}`) as default values. -- **True/False Evaluations:** Use implicit false (e.g., `if not my_list:`). Use `if foo is None:` to check for `None`. -- **Type Annotations:** Strongly encouraged for all public APIs. - -## 2. Python Style Rules -- **Line Length:** Maximum 80 characters. -- **Indentation:** 4 spaces per indentation level. Never use tabs. -- **Blank Lines:** Two blank lines between top-level definitions (classes, functions). One blank line between method definitions. -- **Whitespace:** Avoid extraneous whitespace. Surround binary operators with single spaces. -- **Docstrings:** Use `"""triple double quotes"""`. Every public module, function, class, and method must have a docstring. - - **Format:** Start with a one-line summary. Include `Args:`, `Returns:`, and `Raises:` sections. -- **Strings:** Use f-strings for formatting. Be consistent with single (`'`) or double (`"`) quotes. -- **`TODO` Comments:** Use `TODO(username): Fix this.` format. -- **Imports Formatting:** Imports should be on separate lines and grouped: standard library, third-party, and your own application's imports. - -## 3. Naming -- **General:** `snake_case` for modules, functions, methods, and variables. -- **Classes:** `PascalCase`. -- **Constants:** `ALL_CAPS_WITH_UNDERSCORES`. -- **Internal Use:** Use a single leading underscore (`_internal_variable`) for internal module/class members. - -## 4. Main -- All executable files should have a `main()` function that contains the main logic, called from a `if __name__ == '__main__':` block. - -**BE CONSISTENT.** When editing code, match the existing style. - -*Source: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)* diff --git a/conductor/code_styleguides/typescript.md b/conductor/code_styleguides/typescript.md deleted file mode 100644 index c1dbf0b..0000000 --- a/conductor/code_styleguides/typescript.md +++ /dev/null @@ -1,43 +0,0 @@ -# Google TypeScript Style Guide Summary - -This document summarizes key rules and best practices from the Google TypeScript Style Guide, which is enforced by the `gts` tool. - -## 1. Language Features -- **Variable Declarations:** Always use `const` or `let`. **`var` is forbidden.** Use `const` by default. -- **Modules:** Use ES6 modules (`import`/`export`). **Do not use `namespace`.** -- **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.** -- **Classes:** - - **Do not use `#private` fields.** Use TypeScript's `private` visibility modifier. - - Mark properties never reassigned outside the constructor with `readonly`. - - **Never use the `public` modifier** (it's the default). Restrict visibility with `private` or `protected` where possible. -- **Functions:** Prefer function declarations for named functions. Use arrow functions for anonymous functions/callbacks. -- **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for interpolation and multi-line strings. -- **Equality Checks:** Always use triple equals (`===`) and not equals (`!==`). -- **Type Assertions:** **Avoid type assertions (`x as SomeType`) and non-nullability assertions (`y!`)**. If you must use them, provide a clear justification. - -## 2. Disallowed Features -- **`any` Type:** **Avoid `any`**. Prefer `unknown` or a more specific type. -- **Wrapper Objects:** Do not instantiate `String`, `Boolean`, or `Number` wrapper classes. -- **Automatic Semicolon Insertion (ASI):** Do not rely on it. **Explicitly end all statements with a semicolon.** -- **`const enum`:** Do not use `const enum`. Use plain `enum` instead. -- **`eval()` and `Function(...string)`:** Forbidden. - -## 3. Naming -- **`UpperCamelCase`:** For classes, interfaces, types, enums, and decorators. -- **`lowerCamelCase`:** For variables, parameters, functions, methods, and properties. -- **`CONSTANT_CASE`:** For global constant values, including enum values. -- **`_` Prefix/Suffix:** **Do not use `_` as a prefix or suffix** for identifiers, including for private properties. - -## 4. Type System -- **Type Inference:** Rely on type inference for simple, obvious types. Be explicit for complex types. -- **`undefined` and `null`:** Both are supported. Be consistent within your project. -- **Optional vs. `|undefined`:** Prefer optional parameters and fields (`?`) over adding `|undefined` to the type. -- **`Array` Type:** Use `T[]` for simple types. Use `Array` for more complex union types (e.g., `Array`). -- **`{}` Type:** **Do not use `{}`**. Prefer `unknown`, `Record`, or `object`. - -## 5. Comments and Documentation -- **JSDoc:** Use `/** JSDoc */` for documentation, `//` for implementation comments. -- **Redundancy:** **Do not declare types in `@param` or `@return` blocks** (e.g., `/** @param {string} user */`). This is redundant in TypeScript. -- **Add Information:** Comments must add information, not just restate the code. - -*Source: [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)* diff --git a/conductor/index.md b/conductor/index.md deleted file mode 100644 index ce6eea1..0000000 --- a/conductor/index.md +++ /dev/null @@ -1,14 +0,0 @@ -# Project Context - -## Definition -- [Product Definition](./product.md) -- [Product Guidelines](./product-guidelines.md) -- [Tech Stack](./tech-stack.md) - -## Workflow -- [Workflow](./workflow.md) -- [Code Style Guides](./code_styleguides/) - -## Management -- [Tracks Registry](./tracks.md) -- [Tracks Directory](./tracks/) diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md deleted file mode 100644 index c1e1495..0000000 --- a/conductor/product-guidelines.md +++ /dev/null @@ -1,12 +0,0 @@ -# Product Guidelines: Python Smart Execute - -## User Experience (UX) Philosophy -- **Predictability and Stability:** The extension must behave consistently with standard VS Code patterns. "Smart" features should feel like an intuitive upgrade to existing workflows, not a replacement that requires learning new paradigms. -- **Minimal Distraction:** User-facing messages should be professional and concise. Avoid unnecessary notifications; the tool should work silently in the background unless a critical error occurs. - -## Quality Standards -- **High Reliability:** The core functionality (sending selection to REPL) is mission-critical for the user's workflow. Any "Smart" enhancements must be secondary to ensuring that code is always executed correctly and without regressions. -- **Performance:** Block detection and routing logic must be optimized to ensure execution feels instantaneous. Any latency introduced by analysis should be imperceptible to the user. - -## Communication Style -- **Technical & Direct:** Documentation and error messages should use clear, technical language. Provide direct instructions for configuration and troubleshooting without conversational filler. diff --git a/conductor/product.md b/conductor/product.md deleted file mode 100644 index b140453..0000000 --- a/conductor/product.md +++ /dev/null @@ -1,18 +0,0 @@ -# Initial Concept -A VS Code extension to improve the "send selection to REPL" workflow for Python, specifically handling decorators, cursor stepping, and debug console integration. - -# Product Definition: Python Smart Execute - -## Target Audience -Python developers who frequently use the REPL (Read-Eval-Print Loop) for testing code snippets and seek a more fluid, integrated execution experience within VS Code. - -## Problem Statement -Standard execution tools in VS Code often require manual selection of decorators or multi-line blocks, and don't always handle the transition between standard REPL and active Debug sessions seamlessly. This breaks the developer's "flow" by requiring frequent manual cursor movements and selection adjustments. - -## Core Value Proposition -"Python Smart Execute" provides a unified, context-aware execution experience. It intelligently identifies code blocks—including decorators—and manages the cursor and execution target (REPL vs. Debug Console) automatically, allowing developers to focus on their code rather than the mechanics of execution. - -## Key Features -- **Intelligent Block Detection:** Automatically detects the beginning of a block (such as `def`, `class`, or `@decorator`) even if the cursor is positioned elsewhere within that block. -- **Unified Execution Target:** Dynamically routes code execution to the appropriate terminal (Standard Python REPL, Jupyter Session, or Debug Console) based on the current environment and configuration. -- **Automatic Stepping:** Automatically moves the cursor to the next non-empty line after execution to facilitate rapid, iterative testing. diff --git a/conductor/setup_state.json b/conductor/setup_state.json deleted file mode 100644 index e23b6a6..0000000 --- a/conductor/setup_state.json +++ /dev/null @@ -1 +0,0 @@ -{"last_successful_step": "3.3_initial_track_generated"} \ No newline at end of file diff --git a/conductor/tech-stack.md b/conductor/tech-stack.md deleted file mode 100644 index 28953c8..0000000 --- a/conductor/tech-stack.md +++ /dev/null @@ -1,18 +0,0 @@ -# Technology Stack: Python Smart Execute - -## Language & Runtime -- **TypeScript:** Primary development language, ensuring type safety and better maintainability. -- **Node.js:** The runtime for the VS Code extension host. - -## Frameworks & APIs -- **VS Code Extension API:** The core API for interacting with the VS Code editor and UI components. - -## Integrations -- **Microsoft Python Extension:** Essential integration for interacting with Python environments and terminal-based REPLs. -- **Jupyter Extension:** Support for routing execution to Jupyter interactive sessions. - -## Tooling -- **Build System:** `tsc` (TypeScript Compiler) for transpiling TypeScript source into production-ready JavaScript. -- **Linting:** `ESLint` with `@typescript-eslint` for enforcing code quality and consistency. -- **Testing:** `Mocha` combined with `@vscode/test-electron` for integration testing within the VS Code environment. -- **CI/CD:** GitHub Actions for automated building and publishing of the extension. diff --git a/conductor/tracks.md b/conductor/tracks.md deleted file mode 100644 index 74ae2fd..0000000 --- a/conductor/tracks.md +++ /dev/null @@ -1,13 +0,0 @@ -# Project Tracks - -This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder. - ---- - -- [x] **Track: Modernize Development Environment and Setup Documentation** - *Link: [./tracks/modernize_dev_20260126/](./tracks/modernize_dev_20260126/)* - ---- - -- [~] **Track: Automated Block Detection Testing** - *Link: [./tracks/automated_block_testing_20260127/](./tracks/automated_block_testing_20260127/)* diff --git a/conductor/tracks/automated_block_testing_20260127/index.md b/conductor/tracks/automated_block_testing_20260127/index.md deleted file mode 100644 index f1e94ec..0000000 --- a/conductor/tracks/automated_block_testing_20260127/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Track automated_block_testing_20260127 Context - -- [Specification](./spec.md) -- [Implementation Plan](./plan.md) -- [Metadata](./metadata.json) diff --git a/conductor/tracks/automated_block_testing_20260127/metadata.json b/conductor/tracks/automated_block_testing_20260127/metadata.json deleted file mode 100644 index a7e10e2..0000000 --- a/conductor/tracks/automated_block_testing_20260127/metadata.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "track_id": "automated_block_testing_20260127", - "type": "feature", - "status": "new", - "created_at": "2026-01-27T21:15:00Z", - "updated_at": "2026-01-27T21:15:00Z", - "description": "I want to add some test cases for the smart execute features. We may need to do some refactoring to have decent unit tests. What I want to make sure is that code blocks are identified correctly. For that we need to have decent examples, like function definitions, classes, use of decorators, el-else blocks and other language constructs. They should be covered by the current behaviour but are only tested interactively." -} diff --git a/conductor/tracks/automated_block_testing_20260127/plan.md b/conductor/tracks/automated_block_testing_20260127/plan.md deleted file mode 100644 index 492d1c9..0000000 --- a/conductor/tracks/automated_block_testing_20260127/plan.md +++ /dev/null @@ -1,44 +0,0 @@ -# Implementation Plan - Automated Block Detection Testing - -This plan outlines the steps to refactor the extension logic for testability and implement a -comprehensive automated test suite based on existing interactive examples. - -## Phase 1: Refactoring & Mocking Infrastructure [checkpoint: 2e77a9d] - -This phase focuses on making the current logic testable by introducing mocks for VS Code APIs. - -- [x] Task: Create a mocking utility for `vscode.TextDocument` and `vscode.TextLine` in - `src/test/suite/mocks.ts` [ada5562] -- [x] Task: Refactor `src/extension.ts` to ensure block detection functions are exported and don't - rely on global state [9870c86] -- [x] Task: Verify that the extension still compiles and lints correctly after refactoring -- [x] Task: Conductor - User Manual Verification 'Refactoring & Mocking Infrastructure' (Protocol in - workflow.md) - -## Phase 2: Automated Test Suite Implementation - -This phase focuses on implementing the actual tests covering all identified Python constructs. - -- [x] Task: Initialize `src/test/suite/smartSelect.test.ts` with basic test structure [2e77a9d] -- [x] Task: Implement tests for Decorators and Function/Class definitions [ada5562] -- [x] Task: Implement tests for Control Flow blocks (`if/else`, `try/except`) [2e77a9d] -- [x] Task: Implement tests for Multi-line constructs (Comprehensions, Dictionaries, Docstrings) - [ada5562] -- [x] Task: Implement tests for Stepping logic (finding the next valid code line) [2e77a9d] -- [x] Task: Verify all tests pass with `npm test` [2e77a9d] -- [ ] Task: Conductor - User Manual Verification 'Automated Test Suite Implementation' (Protocol in - workflow.md) - -## Phase 3: Finalization & Coverage - -This phase ensures the new tests are integrated and meet quality standards. - -- [x] Task: Install and configure coverage analysis tools [2e77a9d] -- [x] Task: Run initial coverage analysis for `src/extension.ts` [ada5562] -- [x] Task: Identify uncovered code paths [2e77a9d] -- [x] Task: Move `src/test/interactiveSession.py` to `examples/` [ada5562] -- [x] Task: Add deprecation notice to interactiveSession.py [2e77a9d] -- [x] Task: Export additional helper functions for testing [ada5562] -- [x] Task: Run final coverage analysis - **Result: 41.17% statements, 87.09% branches, 44.44% functions** [2e77a9d] -- [x] Task: Run all tests to ensure no regressions [ada5562] -- [ ] Task: Conductor - User Manual Verification 'Finalization & Coverage' (Protocol in workflow.md) diff --git a/conductor/tracks/automated_block_testing_20260127/spec.md b/conductor/tracks/automated_block_testing_20260127/spec.md deleted file mode 100644 index d157793..0000000 --- a/conductor/tracks/automated_block_testing_20260127/spec.md +++ /dev/null @@ -1,28 +0,0 @@ -# Track Specification: Automated Block Detection Testing - -## Overview -This track aims to replace manual interactive testing of the "Smart Execute" block detection logic with a robust suite of automated unit tests. We will refactor the core logic to support mocking of VS Code dependencies and implement test cases based on the existing `interactiveSession.py` examples. - -## Functional Requirements -- **Refactor for Testability:** Modify the block detection functions in `src/extension.ts` to allow for dependency injection or use of mock objects for `vscode.TextDocument`, `vscode.TextLine`, and `vscode.Selection`. -- **Implement Automated Test Suite:** Create `src/test/suite/smartSelect.test.ts` to host the new tests. -- **Coverage of Python Constructs:** The test suite must validate correct block identification for: - - **Decorators:** Single and multiple decorators before functions/classes. - - **Control Flow:** `if/elif/else` and `try/except/finally` blocks, including nested structures. - - **Functions & Classes:** Multi-line signatures, docstrings, and method definitions. - - **Blocks & Statements:** `with` statements, `for` loops, and multi-line dictionaries/list comprehensions. -- **Stepping Logic:** Verify that the "step" functionality correctly identifies the next valid code line after a block execution. - -## Non-Functional Requirements -- **Mocking Strategy:** Use mock objects to simulate the VS Code environment, avoiding the need for a full extension host for every unit test where possible (though tests will still run via `@vscode/test-electron`). -- **Code Coverage:** Aim for high coverage (>80%) of the logic responsible for selecting start/end lines of blocks. -- **Performance:** Ensure the test suite runs quickly within the existing Mocha/Node.js environment. - -## Acceptance Criteria -- `npm test` runs the new automated suite and all tests pass. -- Every scenario currently manually tested in `src/test/interactiveSession.py` is covered by at least one automated test. -- The refactoring does not change the observable behavior of the extension for the end-user. - -## Out of Scope -- Changes to the actual terminal communication or REPL management logic. -- Redesigning the existing regex-based detection (refactoring is for testability, not logic replacement). diff --git a/conductor/tracks/modernize_dev_20260126/index.md b/conductor/tracks/modernize_dev_20260126/index.md deleted file mode 100644 index 65afe7d..0000000 --- a/conductor/tracks/modernize_dev_20260126/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Track modernize_dev_20260126 Context - -- [Specification](./spec.md) -- [Implementation Plan](./plan.md) -- [Metadata](./metadata.json) diff --git a/conductor/tracks/modernize_dev_20260126/metadata.json b/conductor/tracks/modernize_dev_20260126/metadata.json deleted file mode 100644 index ab54873..0000000 --- a/conductor/tracks/modernize_dev_20260126/metadata.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "track_id": "modernize_dev_20260126", - "type": "chore", - "status": "new", - "created_at": "2026-01-26T12:00:00Z", - "updated_at": "2026-01-26T12:00:00Z", - "description": "Bring the project into an up-to-date shape by updating dev dependencies and documenting local development setup." -} diff --git a/conductor/tracks/modernize_dev_20260126/plan.md b/conductor/tracks/modernize_dev_20260126/plan.md deleted file mode 100644 index fa5a26b..0000000 --- a/conductor/tracks/modernize_dev_20260126/plan.md +++ /dev/null @@ -1,23 +0,0 @@ -# Implementation Plan - Modernize Development Environment and Setup Documentation - -This plan outlines the steps to update development dependencies and document the project setup. - -## Phase 1: Dependency Modernization [checkpoint: 296ee45] -This phase focuses on bringing the project's development tools up to date. - -- [x] Task: Audit current dev dependencies using `npm outdated` 3f6f6ed -- [x] Task: Update devDependencies in `package.json` to latest compatible versions (ESLint, TypeScript, etc.) 3f6f6ed -- [x] Task: Run `npm install` and verify `package-lock.json` updates 3f6f6ed -- [x] Task: Fix any build or lint errors introduced by tool updates (e.g., ESLint rule changes) 3f6f6ed -- [x] Task: Verify all existing tests pass with updated dependencies 3f6f6ed -- [x] Task: Conductor - User Manual Verification 'Dependency Modernization' (Protocol in workflow.md) 296ee45 - -## Phase 2: Setup Documentation [checkpoint: c698e98] -This phase focuses on creating clear instructions for local development. - -- [x] Task: Create `DEVELOPMENT.md` with comprehensive setup instructions 05b4f91 -- [x] Task: Document prerequisites (Node.js, npm, VS Code) and extension dependencies 05b4f91 -- [x] Task: Document the "Build and Run" process (npm commands, VS Code "Run and Debug") 05b4f91 -- [x] Task: Document the testing and linting workflow 05b4f91 -- [-] Task: Update the main `README.md` to link to the new development guide (Skipped: README is for end users) -- [x] Task: Conductor - User Manual Verification 'Setup Documentation' (Protocol in workflow.md) c698e98 diff --git a/conductor/tracks/modernize_dev_20260126/spec.md b/conductor/tracks/modernize_dev_20260126/spec.md deleted file mode 100644 index 4f800c8..0000000 --- a/conductor/tracks/modernize_dev_20260126/spec.md +++ /dev/null @@ -1,21 +0,0 @@ -# Track Specification: Modernize Development Environment and Setup Documentation - -## Overview -The goal of this track is to modernize the project's development environment by updating outdated development dependencies and providing clear, actionable documentation for new and existing developers to set up their local environments. - -## Objectives -- Ensure all development tools (TypeScript, ESLint, Mocha, etc.) are up-to-date. -- Minimize friction for new contributors by providing a comprehensive setup guide. -- Standardize the local development workflow (build, test, lint). - -## Scope -- `package.json` devDependencies. -- `package-lock.json`. -- Creation of `DEVELOPMENT.md` (or similar). -- Updates to `README.md`. -- VS Code configuration (if necessary to match new tool versions). - -## Success Criteria -- `npm run compile`, `npm run lint`, and `npm test` all pass with updated dependencies. -- A clear, step-by-step setup guide exists in the repository. -- No regressions in existing functionality. diff --git a/conductor/workflow.md b/conductor/workflow.md deleted file mode 100644 index 6f9cfd8..0000000 --- a/conductor/workflow.md +++ /dev/null @@ -1,333 +0,0 @@ -# Project Workflow - -## Guiding Principles - -1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md` -2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation -3. **Test-Driven Development:** Write unit tests before implementing functionality -4. **High Code Coverage:** Aim for >80% code coverage for all modules -5. **User Experience First:** Every decision should prioritize user experience -6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution. - -## Task Workflow - -All tasks follow a strict lifecycle: - -### Standard Task Workflow - -1. **Select Task:** Choose the next available task from `plan.md` in sequential order - -2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]` - -3. **Write Failing Tests (Red Phase):** - - Create a new test file for the feature or bug fix. - - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task. - - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests. - -4. **Implement to Pass Tests (Green Phase):** - - Write the minimum amount of application code necessary to make the failing tests pass. - - Run the test suite again and confirm that all tests now pass. This is the "Green" phase. - -5. **Refactor (Optional but Recommended):** - - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior. - - Rerun tests to ensure they still pass after refactoring. - -6. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like: - ```bash - pytest --cov=app --cov-report=html - ``` - Target: >80% coverage for new code. The specific tools and commands will vary by language and framework. - -7. **Document Deviations:** If implementation differs from tech stack: - - **STOP** implementation - - Update `tech-stack.md` with new design - - Add dated note explaining the change - - Resume implementation - -8. **Commit Code Changes:** - - Stage all code changes related to the task. - - Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`. - - Perform the commit. - -9. **Attach Task Summary with Git Notes:** - - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`). - - **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change. - - **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit. - ```bash - # The note content from the previous step is passed via the -m flag. - git notes add -m "" - ``` - -10. **Get and Record Task Commit SHA:** - - **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash. - - **Step 10.2: Write Plan:** Write the updated content back to `plan.md`. - -11. **Commit Plan Update:** - - **Action:** Stage the modified `plan.md` file. - - **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`). - -### Phase Completion Verification and Checkpointing Protocol - -**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`. - -1. **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun. - -2. **Ensure Test Coverage for Phase Changes:** - - **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit. - - **Step 2.2: List Changed Files:** Execute `git diff --name-only HEAD` to get a precise list of all files modified during this phase. - - **Step 2.3: Verify and Create Tests:** For each file in the list: - - **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`). - - For each remaining code file, verify a corresponding test file exists. - - If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`). - -3. **Execute Automated Tests with Proactive Debugging:** - - Before execution, you **must** announce the exact shell command you will use to run the tests. - - **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `CI=true npm test`" - - Execute the announced command. - - If tests fail, you **must** inform the user and begin debugging. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance. - -4. **Propose a Detailed, Actionable Manual Verification Plan:** - - **CRITICAL:** To generate the plan, first analyze `product.md`, `product-guidelines.md`, and `plan.md` to determine the user-facing goals of the completed phase. - - You **must** generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes. - - The plan you present to the user **must** follow this format: - - **For a Frontend Change:** - ``` - The automated tests have passed. For manual verification, please follow these steps: - - **Manual Verification Steps:** - 1. **Start the development server with the command:** `npm run dev` - 2. **Open your browser to:** `http://localhost:3000` - 3. **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly. - ``` - - **For a Backend Change:** - ``` - The automated tests have passed. For manual verification, please follow these steps: - - **Manual Verification Steps:** - 1. **Ensure the server is running.** - 2. **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'` - 3. **Confirm that you receive:** A JSON response with a status of `201 Created`. - ``` - -5. **Await Explicit User Feedback:** - - After presenting the detailed plan, ask the user for confirmation: "**Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed.**" - - **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation. - -6. **Create Checkpoint Commit:** - - Stage all changes. If no changes occurred in this step, proceed with an empty commit. - - Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`). - -7. **Attach Auditable Verification Report using Git Notes:** - - **Step 7.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation. - - **Step 7.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit. - -8. **Get and Record Phase Checkpoint SHA:** - - **Step 8.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`). - - **Step 8.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: ]`. - - **Step 8.3: Write Plan:** Write the updated content back to `plan.md`. - -9. **Commit Plan Update:** - - **Action:** Stage the modified `plan.md` file. - - **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '' as complete`. - -10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note. - -### Quality Gates - -Before marking any task complete, verify: - -- [ ] All tests pass -- [ ] Code coverage meets requirements (>80%) -- [ ] Code follows project's code style guidelines (as defined in `code_styleguides/`) -- [ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc) -- [ ] Type safety is enforced (e.g., type hints, TypeScript types, Go types) -- [ ] No linting or static analysis errors (using the project's configured tools) -- [ ] Works correctly on mobile (if applicable) -- [ ] Documentation updated if needed -- [ ] No security vulnerabilities introduced - -## Development Commands - -**AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.** - -### Setup -```bash -# Example: Commands to set up the development environment (e.g., install dependencies, configure database) -# e.g., for a Node.js project: npm install -# e.g., for a Go project: go mod tidy -``` - -### Daily Development -```bash -# Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format) -# e.g., for a Node.js project: npm run dev, npm test, npm run lint -# e.g., for a Go project: go run main.go, go test ./..., go fmt ./... -``` - -### Before Committing -```bash -# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests) -# e.g., for a Node.js project: npm run check -# e.g., for a Go project: make check (if a Makefile exists) -``` - -## Testing Requirements - -### Unit Testing -- Every module must have corresponding tests. -- Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach). -- Mock external dependencies. -- Test both success and failure cases. - -### Integration Testing -- Test complete user flows -- Verify database transactions -- Test authentication and authorization -- Check form submissions - -### Mobile Testing -- Test on actual iPhone when possible -- Use Safari developer tools -- Test touch interactions -- Verify responsive layouts -- Check performance on 3G/4G - -## Code Review Process - -### Self-Review Checklist -Before requesting review: - -1. **Functionality** - - Feature works as specified - - Edge cases handled - - Error messages are user-friendly - -2. **Code Quality** - - Follows style guide - - DRY principle applied - - Clear variable/function names - - Appropriate comments - -3. **Testing** - - Unit tests comprehensive - - Integration tests pass - - Coverage adequate (>80%) - -4. **Security** - - No hardcoded secrets - - Input validation present - - SQL injection prevented - - XSS protection in place - -5. **Performance** - - Database queries optimized - - Images optimized - - Caching implemented where needed - -6. **Mobile Experience** - - Touch targets adequate (44x44px) - - Text readable without zooming - - Performance acceptable on mobile - - Interactions feel native - -## Commit Guidelines - -### Message Format -``` -(): - -[optional body] - -[optional footer] -``` - -### Types -- `feat`: New feature -- `fix`: Bug fix -- `docs`: Documentation only -- `style`: Formatting, missing semicolons, etc. -- `refactor`: Code change that neither fixes a bug nor adds a feature -- `test`: Adding missing tests -- `chore`: Maintenance tasks - -### Examples -```bash -git commit -m "feat(auth): Add remember me functionality" -git commit -m "fix(posts): Correct excerpt generation for short posts" -git commit -m "test(comments): Add tests for emoji reaction limits" -git commit -m "style(mobile): Improve button touch targets" -``` - -## Definition of Done - -A task is complete when: - -1. All code implemented to specification -2. Unit tests written and passing -3. Code coverage meets project requirements -4. Documentation complete (if applicable) -5. Code passes all configured linting and static analysis checks -6. Works beautifully on mobile (if applicable) -7. Implementation notes added to `plan.md` -8. Changes committed with proper message -9. Git note with task summary attached to the commit - -## Emergency Procedures - -### Critical Bug in Production -1. Create hotfix branch from main -2. Write failing test for bug -3. Implement minimal fix -4. Test thoroughly including mobile -5. Deploy immediately -6. Document in plan.md - -### Data Loss -1. Stop all write operations -2. Restore from latest backup -3. Verify data integrity -4. Document incident -5. Update backup procedures - -### Security Breach -1. Rotate all secrets immediately -2. Review access logs -3. Patch vulnerability -4. Notify affected users (if any) -5. Document and update security procedures - -## Deployment Workflow - -### Pre-Deployment Checklist -- [ ] All tests passing -- [ ] Coverage >80% -- [ ] No linting errors -- [ ] Mobile testing complete -- [ ] Environment variables configured -- [ ] Database migrations ready -- [ ] Backup created - -### Deployment Steps -1. Merge feature branch to main -2. Tag release with version -3. Push to deployment service -4. Run database migrations -5. Verify deployment -6. Test critical paths -7. Monitor for errors - -### Post-Deployment -1. Monitor analytics -2. Check error logs -3. Gather user feedback -4. Plan next iteration - -## Continuous Improvement - -- Review workflow weekly -- Update based on pain points -- Document lessons learned -- Optimize for user happiness -- Keep things simple and maintainable From 18e37b06e18c91ab6f3afcb1d4ff290c4ecfb35a Mon Sep 17 00:00:00 2001 From: Sebastian Warnholz Date: Mon, 2 Mar 2026 20:00:22 +0000 Subject: [PATCH 3/3] Fix ci pipeline --- src/test/runTest.ts | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/src/test/runTest.ts b/src/test/runTest.ts index 93a4441..cd3c6ef 100644 --- a/src/test/runTest.ts +++ b/src/test/runTest.ts @@ -1,9 +1,30 @@ import * as path from 'path'; -import { runTests } from '@vscode/test-electron'; +import { runTests, runVSCodeCommand } from '@vscode/test-electron'; + +async function installDependencies() { + const extensions = [ + 'ms-python.python', + 'ms-toolsai.jupyter' + ]; + + for (const extId of extensions) { + try { + console.log(`Installing extension: ${extId}`); + await runVSCodeCommand(['--install-extension', extId]); + console.log(`✓ Successfully installed: ${extId}`); + } catch (err) { + console.error(`✗ Failed to install ${extId}:`, err); + throw err; + } + } +} async function main() { try { + // Install required extension dependencies + await installDependencies(); + // The folder containing the Extension Manifest package.json // Passed to `--extensionDevelopmentPath` const extensionDevelopmentPath = path.resolve(__dirname, '../../');