diff --git a/module/move/unilang/plan.md b/module/move/unilang/plan.md index 4fb6721882..e5b8279366 100644 --- a/module/move/unilang/plan.md +++ b/module/move/unilang/plan.md @@ -1,142 +1,41 @@ -# Project Plan: Unilang Codestyle and Documentation Review +# Project Plan: Unilang Test File Documentation ### Goal -* Iterate through each file of the `unilang` crate, ensuring all code adheres to the established codestyle rules and has concise, accurate documentation. +* Add comprehensive documentation to all test files, including references to the Test Matrix, to ensure clarity and maintainability. ### Progress -* ✅ Codestyle Review Complete +* ✅ Test Documentation Complete ### Target Crate * module/move/unilang ### Relevant Context * Files to Include (for AI's reference, if `read_file` is planned, primarily from Target Crate): - * All `.rs` files within `module/move/unilang/src` and `module/move/unilang/tests`. + * `module/move/unilang/tests/inc/phase1/full_pipeline_test.rs` ### Expected Behavior Rules / Specifications (for Target Crate) -* All files must pass `cargo clippy` with the workspace lint settings without warnings. -* All public items should have clear, concise documentation. -* Code formatting should be consistent across the entire crate. +* Test functions should have doc comments explaining their purpose. +* Each test function should reference the Test Matrix row(s) it covers. ### Target File Structure (If Applicable, within Target Crate) * No changes to the file structure are planned. ### Increments -* ✅ Increment 1: Review `src/lib.rs` - * Detailed Plan Step 1: Read the content of `src/lib.rs`. - * Detailed Plan Step 2: Apply codestyle fixes, including adding documentation for all public modules. - * Detailed Plan Step 3: Use `mod_interface` to structure the crate's public API. - * Pre-Analysis: The `lib.rs` file is the entry point to the crate and should be well-documented and structured. - * Crucial Design Rules: [Structuring: Modules with `mod_interface`](#structuring-modules-with-mod_interface), [Comments and Documentation](#comments-and-documentation) - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` to ensure the changes compile. - * Commit Message: "style(unilang): Clean up and document src/lib.rs" -* ✅ Increment 2: Review `src/data.rs` - * Detailed Plan Step 1: Read the content of `src/data.rs`. - * Detailed Plan Step 2: Apply codestyle fixes (spacing, newlines, etc.). - * Detailed Plan Step 3: Add concise documentation to all public structs and their fields. - * Detailed Plan Step 4: Re-enable the `former` crate derive macros and attributes and fix any resulting compilation errors. - * Pre-Analysis: The file contains core data structures. The `former` derive is currently commented out and needs to be re-enabled and fixed. - * Crucial Design Rules: [Comments and Documentation](#comments-and-documentation) - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` to ensure the changes compile without errors or warnings. - * Commit Message: "style(unilang): Clean up and document src/data.rs" -* ✅ Increment 3: Review `src/error.rs` - * Detailed Plan Step 1: Read the content of `src/error.rs`. - * Detailed Plan Step 2: Apply codestyle fixes (spacing, newlines, etc.). - * Detailed Plan Step 3: Add concise documentation to the `Error` enum and its variants. - * Pre-Analysis: The file contains the basic error enum. It needs proper documentation and formatting. - * Crucial Design Rules: [Error Handling: Use a Centralized Approach](#error-handling-use-a-centralized-approach), [Comments and Documentation](#comments-and-documentation) - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` to ensure the changes compile. - * Commit Message: "style(unilang): Clean up and document src/error.rs" -* ✅ Increment 4: Review `src/help.rs` - * Detailed Plan Step 1: Read the content of `src/help.rs`. - * Detailed Plan Step 2: Apply codestyle fixes (spacing, newlines, etc.). - * Detailed Plan Step 3: Add concise documentation to the `HelpGenerator` struct and its methods. - * Pre-Analysis: The file contains the basic help generator. It needs proper documentation and formatting. - * Crucial Design Rules: [Comments and Documentation](#comments-and-documentation) - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` to ensure the changes compile. - * Commit Message: "style(unilang): Clean up and document src/help.rs" -* ✅ Increment 5: Review `src/interpreter.rs` - * Detailed Plan Step 1: Read the content of `src/interpreter.rs`. - * Detailed Plan Step 2: Apply codestyle fixes (spacing, newlines, etc.). - * Detailed Plan Step 3: Add concise documentation to the `Interpreter` and `ExecutionContext` structs and their methods. - * Pre-Analysis: The file contains the basic interpreter. It needs proper documentation and formatting. - * Crucial Design Rules: [Comments and Documentation](#comments-and-documentation) - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` to ensure the changes compile. - * Commit Message: "style(unilang): Clean up and document src/interpreter.rs" -* ✅ Increment 6: Review `src/parsing.rs` - * Detailed Plan Step 1: Read the content of `src/parsing.rs`. - * Detailed Plan Step 2: Apply codestyle fixes (spacing, newlines, etc.). - * Detailed Plan Step 3: Add concise documentation to all public items (`Token`, `Lexer`, `Parser`, `Statement`, `Program`) and their methods/variants/fields. - * Pre-Analysis: The file contains the lexer and parser. It's a large file and will require careful review to ensure all items are documented and formatted correctly. - * Crucial Design Rules: [Comments and Documentation](#comments-and-documentation), [New Lines for Blocks](#new-lines-for-blocks), [Spaces Around Symbols](#spaces-around-symbols). - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` to ensure the changes compile. - * Commit Message: "style(unilang): Clean up and document src/parsing.rs" -* ✅ Increment 7: Review `src/registry.rs` - * Detailed Plan Step 1: Read the content of `src/registry.rs`. - * Detailed Plan Step 2: Apply codestyle fixes (spacing, newlines, etc.). - * Detailed Plan Step 3: Add concise documentation to the `CommandRegistry` struct, `CommandRegistryBuilder` struct, and their methods. - * Pre-Analysis: The file contains the command registry. It needs proper documentation and formatting. - * Crucial Design Rules: [Comments and Documentation](#comments-and-documentation) - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` to ensure the changes compile. - * Commit Message: "style(unilang): Clean up and document src/registry.rs" -* ✅ Increment 8: Review `src/semantic.rs` - * Detailed Plan Step 1: Read the content of `src/semantic.rs`. - * Detailed Plan Step 2: Apply codestyle fixes (spacing, newlines, etc.). - * Detailed Plan Step 3: Add concise documentation to the `VerifiedCommand` and `SemanticAnalyzer` structs and their methods. - * Pre-Analysis: The file contains the semantic analyzer. It needs proper documentation and formatting. - * Crucial Design Rules: [Comments and Documentation](#comments-and-documentation) - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` to ensure the changes compile. - * Commit Message: "style(unilang): Clean up and document src/semantic.rs" -* ✅ Increment 9: Review `src/ca/` directory - * Detailed Plan Step 1: Read all files in `src/ca/` and its subdirectories. - * Detailed Plan Step 2: Refactor `src/ca/mod.rs`. - * Detailed Plan Step 3: Refactor `src/ca/parsing/mod.rs`. - * Detailed Plan Step 4: Refactor `src/ca/parsing/engine.rs`. - * Detailed Plan Step 5: Refactor `src/ca/parsing/error.rs`. - * Detailed Plan Step 6: Refactor `src/ca/parsing/input.rs`. - * Detailed Plan Step 7: Refactor `src/ca/parsing/instruction.rs`. - * Pre-Analysis: This directory seems to contain a secondary parsing engine or a more complex command architecture (`ca`). It needs to be reviewed for consistency with the rest of the crate. - * Crucial Design Rules: [Comments and Documentation](#comments-and-documentation), [New Lines for Blocks](#new-lines-for-blocks), [Spaces Around Symbols](#spaces-around-symbols). - * Relevant Behavior Rules: N/A - * Verification Strategy: Run `cargo build -p unilang` after refactoring all files in the directory. - * Commit Message: "style(unilang): Clean up and document src/ca/**" -* ✅ Increment 10: Review `tests/` directory - * Detailed Plan Step 1: Read all files in `tests/` and its subdirectories. - * Detailed Plan Step 2: Refactor `tests/tests.rs`. - * Detailed Plan Step 3: Refactor `tests/inc/mod.rs`. - * Detailed Plan Step 4: Refactor `tests/inc/phase1/mod.rs`. - * Detailed Plan Step 5: Refactor `tests/inc/phase1/foundational_setup.rs`. - * Detailed Plan Step 6: Refactor `tests/inc/phase1/full_pipeline_test.rs`. - * Pre-Analysis: The test files need to be reviewed for clarity, documentation, and adherence to codestyle. - * Crucial Design Rules: [Comments and Documentation](#comments-and-documentation) +* ✅ Increment 1: Document `tests/inc/phase1/full_pipeline_test.rs` + * Detailed Plan Step 1: Read the content of `tests/inc/phase1/full_pipeline_test.rs`. + * Detailed Plan Step 2: Add documentation to each test function, linking it to the corresponding Test Matrix rows from the previous plan. + * Pre-Analysis: The integration test file lacks documentation. + * Crucial Design Rules: [Testing: Plan with a Test Matrix When Writing Tests](#testing-plan-with-a-test-matrix-when-writing-tests), [Comments and Documentation](#comments-and-documentation) * Relevant Behavior Rules: N/A * Verification Strategy: Run `cargo test -p unilang` to ensure all tests still pass. - * Commit Message: "style(unilang): Clean up and document tests/**" -* ✅ Increment 11: Final Verification - * Detailed Plan Step 1: Run `cargo clippy -- -D warnings` to ensure there are no warnings. - * Detailed Plan Step 2: Run `cargo test` to ensure all tests pass. - * Pre-Analysis: All files have been reviewed. A final check is needed to ensure the entire crate is clean. - * Crucial Design Rules: N/A - * Relevant Behavior Rules: N/A - * Verification Strategy: All checks must pass. - * Commit Message: "chore(unilang): Final verification of codestyle changes" + * Commit Message: "docs(unilang): Add test matrix documentation to integration tests" ### Task Requirements -* Systematically review every `.rs` file. -* Apply codestyle fixes and add documentation as needed. +* Add documentation to test files. ### Project Requirements * Maintain consistency with the overall workspace codestyle. ### Notes & Insights -* This is a good opportunity to improve the overall quality and maintainability of the crate. -* The `former` crate usage is still disabled and should be noted for future work. \ No newline at end of file +* This will significantly improve the test suite's readability. \ No newline at end of file diff --git a/module/move/unilang/tests/inc/phase1/full_pipeline_test.rs b/module/move/unilang/tests/inc/phase1/full_pipeline_test.rs index a53eef063d..94df7b5b5c 100644 --- a/module/move/unilang/tests/inc/phase1/full_pipeline_test.rs +++ b/module/move/unilang/tests/inc/phase1/full_pipeline_test.rs @@ -11,7 +11,12 @@ use unilang::interpreter::{ Interpreter, ExecutionContext }; /// /// Tests for the `Lexer`. /// -// Test Matrix Rows: T1.1, T1.2, T1.3, T1.4 +/// This test covers the following combinations from the Test Matrix: +/// - T1.1: A command with various argument types. +/// - T1.2: Multiple commands separated by `;;`. +/// - T1.3: Whitespace handling. +/// - T1.4: Empty string literals. +/// #[test] fn lexer_tests() { @@ -48,7 +53,11 @@ fn lexer_tests() /// /// Tests for the `Parser`. /// -// Test Matrix Rows: T2.1, T2.2, T2.3 +/// This test covers the following combinations from the Test Matrix: +/// - T2.1: A single command with one argument. +/// - T2.2: Multiple commands with arguments. +/// - T2.3: Empty input. +/// #[test] fn parser_tests() { @@ -83,7 +92,13 @@ fn parser_tests() /// /// Tests for the `SemanticAnalyzer`. /// -// Test Matrix Rows: T3.1, T3.2, T3.3, T3.4, T3.5 +/// This test covers the following combinations from the Test Matrix: +/// - T3.1: A valid command with correct arguments. +/// - T3.2: An unknown command. +/// - T3.3: A command with a missing required argument. +/// - T3.4: A command with an argument of the wrong type. +/// - T3.5: A command with too many arguments. +/// #[test] fn semantic_analyzer_tests() { @@ -159,7 +174,10 @@ fn semantic_analyzer_tests() /// /// Tests for the `Interpreter`. /// -// Test Matrix Rows: T4.1, T4.2 +/// This test covers the following combinations from the Test Matrix: +/// - T4.1: A single valid command. +/// - T4.2: Multiple valid commands. +/// #[test] fn interpreter_tests() { @@ -203,7 +221,10 @@ fn interpreter_tests() /// /// Tests for the `HelpGenerator`. /// -// Test Matrix Rows: T5.1, T5.2 +/// This test covers the following combinations from the Test Matrix: +/// - T5.1: A command with arguments. +/// - T5.2: A command without arguments. +/// #[test] fn help_generator_tests() {