# Transformation & State Management Method Inventory and Proposed Fixes Below is a systematic, evidence-based analysis of only the transformation-related methods and state management methods in StateService. Following the inventory is a set of targeted implementation fixes addressing known transformation-mode issues (e.g., overwriting transformed nodes, “currentState.clone is not a function,” and incomplete directive replacement). ------------------------------------------------------------------------------- ## 1. Transformation Method Inventory Below are the methods in StateService.ts (lines refer to the snippet provided) that directly relate to node transformation. | Method Name | Signature | In Interface? | In Implementation? | transformationFlags | stateModification | usageCount (snippet) | |--------------------------|----------------------------------------------------------------------------|--------------|--------------------|--------------------------------------------|-------------------------------------------------|----------------------| | getTransformedNodes | getTransformedNodes(): MeldNode[] | Yes (L41-42) | Yes (~L105-108) | None | None (returns copy of array) | 0 | | setTransformedNodes | setTransformedNodes(nodes: MeldNode[]): void | Yes (L43-44) | Yes (~L146-149) | None | Writes currentState.transformedNodes | 0 | | transformNode | transformNode(original: MeldNode, transformed: MeldNode): void | Yes (L45-46) | Yes (~L173-188) | ["_transformationEnabled" (read check)] | Mutates transformedNodes array | 0 | | isTransformationEnabled | isTransformationEnabled(): boolean | Yes (L47-48) | Yes (~L190-193) | ["_transformationEnabled" (read)] | None | 0 | | enableTransformation | enableTransformation(enable: boolean): void | Yes (L49-50) | Yes (~L195-211) | ["_transformationEnabled" (write/read)] | May overwrite currentState.transformedNodes | 0 | NOTES / EVIDENCE: • Snippet lines refer to the approximate interface definitions in IStateService (L41-50) and matching implementations in StateService (transformNode around line 173, enableTransformation around line 195, etc.). • No direct calls to these methods appear within StateService.ts itself (usageCount=0 in the snippet). External usage is inferred from test logs and other services. ------------------------------------------------------------------------------- ## 2. State Management Method Inventory Below are the methods in StateService.ts (lines refer to the snippet provided) that manage overall state lifecycle (clone, child states, immutability, local changes). Only those explicitly concerning state management are included. | Method Name | Signature | In Interface? | In Implementation? | deepCopyFields | shallowCopyFields | usageCount (snippet) | |-------------------|---------------------------------------------------------|--------------|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------------------| | clone | clone(): IStateService | Yes (L78-79) | Yes (~L298-334) | (none) → no recursive or nested object cloning for MeldNodes/Commands; everything is container-level only | variables.text → new Map(...)
variables.data → new Map(...)
variables.path → new Map(...)
commands → new Map(...)
nodes → copy array
transformedNodes → copy array
imports → new Set(...) | 0 | | createChildState | createChildState(): IStateService | Yes (L74-75) | Yes (~L284-290) | n/a (creates a new child StateService object referencing parent’s currentState) | n/a | 0 | | mergeChildState | mergeChildState(childState: IStateService): void | Yes (L76-77) | Yes (~L292-296) | Cannot confirm → calls stateFactory.mergeStates(...) with two StateNodes, not shown | Cannot confirm | 0 | | setImmutable | setImmutable(): void | Yes (L70-71) | Yes (~L275-277) | n/a → sets internal boolean _isImmutable only | n/a | 0 | | isImmutable (prop)| get isImmutable(): boolean | Yes (L72-73) | Yes (~L279-282) | n/a → read-only accessor for _isImmutable | n/a | 0 | | hasLocalChanges | hasLocalChanges(): boolean | Yes (L66-67) | Yes (~L265-267) | n/a → always returns true | n/a | 0 | | getLocalChanges | getLocalChanges(): string[] | Yes (L68-69) | Yes (~L269-272) | n/a → always returns ["state"] | n/a | 0 | NOTES / EVIDENCE: • clone() creates new containers (Maps, arrays, Sets) but does not deeply clone their contents. • createChildState() and mergeChildState() rely on StateFactory logic not shown, so the nature of copying or merging is partially unknown. • None of these are invoked within StateService.ts in the snippet (usageCount=0). External usage is indicated in test logs (DirectiveService, partial merges, etc.). ------------------------------------------------------------------------------- ## 3. Proposed Implementation Fixes for Transformation-Related Issues Several transformation-mode test failures point to inconsistent or overwritten transformations, as well as misuse of “currentState.clone()” outside StateService. Below are targeted fixes and their recommended TypeScript changes. -------------------------------------------------------------------------------- ### 3.1 “enableTransformation” Overwriting Existing Transformations • Observed Issue: Re-enabling transformation discards any previously transformed nodes by overwriting currentState.transformedNodes with a fresh copy of currentState.nodes. • Snippet Reference: StateService.enableTransformation (~lines 195–211). Use Case: When a service calls enableTransformation(true) multiple times, it can erase partial transformations already performed. -------------------------------------------------------------------------------- Proposed Fix Data: ```typescript { file: "StateService.ts", methodName: "enableTransformation", currentIssues: [ "Re-enabling transformation overwrites transformedNodes instead of preserving them." ], proposedFix: ` enableTransformation(enable: boolean): void { if (this._transformationEnabled === enable) { return; } this._transformationEnabled = enable; if (enable && !this.currentState.transformedNodes) { // Only initialize if we have no existing transformedNodes this.updateState({ transformedNodes: [...this.currentState.nodes] }, 'enableTransformation'); } } `, transformationFlags: [ { name: "_transformationEnabled", handling: "Set/unset the mode. Init transformedNodes only if undefined." } ], statePreservation: { whatToPreserve: "Existing partial transformations in currentState.transformedNodes", howToPreserve: "Check if currentState.transformedNodes is null/undefined before re-initializing" } } ``` Explanation: • The fix only sets “transformedNodes” on the first enable, preserving existing transformations if enableTransformation(true) is called again. • This prevents accidental data loss partway through a multi-step transformation sequence. -------------------------------------------------------------------------------- ### 3.2 Avoiding “currentState.clone()” Calls (Outside of StateService) • Observed Issue: Integration tests show “MeldInterpreterError: currentState.clone is not a function,” indicating external code tries to do “currentState.clone()” though “currentState” is a plain StateNode. • Likely Root Cause: The snippet reveals that “this.currentState” is typed as StateNode, which does not have a .clone() method. The correct approach is “myStateService.clone()”. -------------------------------------------------------------------------------- Proposed Fix Data: ```typescript { file: "DirectiveService.ts" /* or relevant caller */, methodName: "N/A (call sites)", currentIssues: [ "Attempting to invoke .clone() on a plain StateNode object instead of on the StateService instance." ], proposedFix: ` // Example scenario: // INCORRECT: // const cloned = this.currentState.clone(); // // CORRECT: // const clonedState = this.clone(); // // Use clonedState as IStateService `, transformationFlags: [ { name: "_transformationEnabled", handling: "No direct effect; fix ensures we call the service-level clone." } ], statePreservation: { whatToPreserve: "Full state, including transformation flags and transformed nodes", howToPreserve: "Use the official .clone() method on StateService, never the raw StateNode" } } ``` Explanation: • The fix is external to StateService itself: any code calling “currentState.clone()” must be changed to “this.clone()” on the actual StateService instance. • This ensures the entire state is duplicated according to the existing clone() logic (lines ~298–334), including transformation flags and partial transformations. -------------------------------------------------------------------------------- ### 3.3 Handling Directive Replacement in Transformation • Observed Issue: OutputService tests fail if directive nodes remain in the final transformedNodes array (e.g., “Output error (markdown): Unexpected directive in transformed nodes”). • Possible Cause: Some directive handlers do not explicitly replace or remove directive nodes. If transformation mode is on, the final output must be free of directive nodes or it raises an error. -------------------------------------------------------------------------------- Proposed Fix Data: ```typescript { file: "RunDirectiveHandler.ts / EmbedDirectiveHandler.ts", methodName: "execute() or similar directive handle method", currentIssues: [ "Some tests fail with leftover directive nodes in transformation mode, e.g. 'echo test' is not replaced with 'test output'." ], proposedFix: ` // Inside each directive's execution method: if (this.stateService.isTransformationEnabled()) { // Option A) Replace the directive node with a new Text or CodeFence node: this.stateService.transformNode(directiveNode, transformedTextNode); // Option B) If directive is no longer needed, remove it or transform to an empty node } `, transformationFlags: [ { name: "_transformationEnabled", handling: "Check if active; apply transformNode accordingly." } ], statePreservation: { whatToPreserve: "All previously transformed nodes; only replace the specific directive node.", howToPreserve: "Use stateService.transformNode(...) for partial replacement without rewriting entire arrays." } } ``` Explanation: • Each directive-based node must be removed or replaced with a suitable text/code node when transformation is on. • This fix ensures no directive node remains, preventing OutputService from throwing “Unexpected directive in transformed nodes.” -------------------------------------------------------------------------------- ### 3.4 Full Fix Example Code Below is an example revised excerpt from StateService.ts using the proposed fix for enableTransformation, around line 195: ```typescript // StateService.ts (approx lines 195-211) public enableTransformation(enable: boolean): void { if (this._transformationEnabled === enable) { return; } this._transformationEnabled = enable; // Initialize transformed nodes only if we do not already have them if (enable && !this.currentState.transformedNodes) { this.updateState({ transformedNodes: [...this.currentState.nodes] }, 'enableTransformation'); } } ``` And for directive handlers (pseudo-code) to ensure directives are replaced: ```typescript // RunDirectiveHandler.ts (pseudo-code for transformation) execute(directiveNode: MeldNode, ...): void { if (this.stateService.isTransformationEnabled()) { const transformedTextNode: MeldNode = { type: 'Text', content: 'test output', location: directiveNode.location }; // Replace the directive node with text this.stateService.transformNode(directiveNode, transformedTextNode); } } ``` ------------------------------------------------------------------------------- ## Summary & Next Steps • The above inventories confirm which methods control transformation mode and overall state life cycle. • Key fixes include (1) preserving partial transformations when “enableTransformation” is called multiple times, (2) calling “this.clone()” instead of “currentState.clone(),” and (3) ensuring directive handlers remove/replace directive nodes in transformation mode. • These changes align with the failing test scenarios (overwritten transformations, leftover directives, or “clone is not a function”). • After implementing these fixes, re-run the failing tests for “OutputService … transformation mode,” “DirectiveService … import directives,” and “API integration … clone is not a function” to confirm resolution. End of Report.