Add MethodNodeExpander for comment/decorator preservation in method sorting

Implements node expansion to include method metadata (JSDoc comments, decorators)
as composite AST nodes that move as single units during refactoring operations.

Key features:
- Expands method nodes to include leading comments and decorators
- Creates synthetic composite nodes using createWrappedNode
- Supports both MethodDeclaration and ConstructorDeclaration
- Handles adjacent comment detection with whitespace-only separation
- Clean architecture with focused single-responsibility methods

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: pjurczynski

.quality-baseline.json

@@ -715,12 +715,6 @@
       "singleUseVariable"
     ]
   },
-  "tests/utils/test-utilities.ts": {
-    "lastCommitId": "833b616cbfbafc559be677926289fc4eddf0bc4e",
-    "violations": [
-      "singleUseVariable"
-    ]
-  },
   "tests/integration/fixture.test.ts": {
     "lastCommitId": "f7d3433d1b8e57e08257e50af05bf009f175e2d0",
     "violations": [

src/core/locators/method-node-expander.ts

@@ -0,0 +1,95 @@
+import { 
+  createWrappedNode, 
+  MethodDeclaration, 
+  ConstructorDeclaration, 
+  Node, 
+  SourceFile, 
+  ts,
+  Decorator,
+  JSDoc
+} from 'ts-morph';
+
+export class MethodNodeExpander {
+  expandWithMetadata(
+    method: MethodDeclaration | ConstructorDeclaration,
+    sourceFile: SourceFile
+  ): Node {
+    return this.createWrapperNode(method, this.locateMethodMetadata(method), sourceFile);
+  }
+  
+  private locateMethodMetadata(method: MethodDeclaration | ConstructorDeclaration): ts.Node[] {
+    return [
+      ...this.getDecoratorNodes(method),
+      ...this.getJsDocNodes(method)
+    ];
+  }
+
+  private getDecoratorNodes(method: MethodDeclaration | ConstructorDeclaration): ts.Node[] {
+    if (!Node.isMethodDeclaration(method)) return [];
+    return method.getDecorators().map((decorator: Decorator) => decorator.compilerNode);
+  }
+
+  private getJsDocNodes(method: MethodDeclaration | ConstructorDeclaration): ts.Node[] {
+    return method.getJsDocs().map((jsDoc: JSDoc) => jsDoc.compilerNode);
+  }
+
+  private createWrapperNode(
+    method: MethodDeclaration | ConstructorDeclaration,
+    metadata: ts.Node[],
+    sourceFile: SourceFile
+  ): Node {
+    const allNodes = [...metadata, method.compilerNode];
+    const wrapperNode = this.createBlockNode(allNodes);
+    this.setWrapperRange(wrapperNode, allNodes, sourceFile);
+    return createWrappedNode(wrapperNode, { sourceFile: sourceFile.compilerNode });
+  }
+
+  private createBlockNode(allNodes: ts.Node[]): ts.Block {
+    return ts.factory.createBlock(
+      allNodes.map(node => this.nodeToStatement(node)),
+      false
+    );
+  }
+
+
+  private nodeToStatement(node: ts.Node): ts.Statement {
+    if (ts.isStatement(node)) {
+      return node;
+    }
+    return ts.factory.createExpressionStatement(node as ts.Expression);
+  }
+
+  private setWrapperRange(
+    wrapperNode: ts.Block,
+    allNodes: ts.Node[],
+    sourceFile: SourceFile
+  ): void {
+    if (allNodes.length === 0) return;
+    
+    this.setNodePosition(wrapperNode, this.calculateStartPosition(allNodes, sourceFile));
+    this.setNodeEnd(wrapperNode, this.calculateEndPosition(allNodes));
+  }
+
+  private calculateStartPosition(allNodes: ts.Node[], sourceFile: SourceFile): number {
+    return Math.min(...allNodes.map(node => {
+      const leadingComments = ts.getLeadingCommentRanges(sourceFile.getFullText(), node.pos) || [];
+      return leadingComments.length > 0 
+        ? Math.min(...leadingComments.map(c => c.pos))
+        : node.pos;
+    }));
+  }
+
+  private calculateEndPosition(allNodes: ts.Node[]): number {
+    return Math.max(...allNodes.map(node => node.end));
+  }
+
+  private setNodePosition(node: ts.Node, position: number): void {
+    Object.defineProperty(node, 'pos', { value: position, writable: false });
+  }
+
+  private setNodeEnd(node: ts.Node, endPosition: number): void {
+    Object.defineProperty(node, 'end', { value: endPosition, writable: false });
+  }
+
+
+}

tests/unit/locators/method-node-expander.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from '@jest/globals';
+import { Project, SourceFile } from 'ts-morph';
+import { MethodNodeExpander } from '../../../src/core/locators/method-node-expander';
+
+describe('MethodNodeExpander', () => {
+  let project: Project;
+  let expander: MethodNodeExpander;
+
+  beforeEach(() => {
+    project = new Project({ useInMemoryFileSystem: true });
+    expander = new MethodNodeExpander();
+  });
+
+  function testNodeExpansion(code: string, nodeSelector: (sourceFile: SourceFile) => any, expectedText: string): void {
+    const sourceFile = project.createSourceFile('test.ts', code);
+    expect(expander.expandWithMetadata(nodeSelector(sourceFile), sourceFile).getFullText().trim()).toBe(expectedText);
+  }
+
+  describe('Node Expansion', () => {
+    it('should expand method with JSDoc', () => {
+      testNodeExpansion(
+        `class TestClass {
+  /**
+   * This is a JSDoc comment
+   */
+  testMethod() {
+    return 'test';
+  }
+}`,
+        (sf) => sf.getClassOrThrow('TestClass').getMethodOrThrow('testMethod'),
+        `/**
+   * This is a JSDoc comment
+   */
+  testMethod() {
+    return 'test';
+  }`
+      );
+    });
+
+    it('should expand method with decorator', () => {
+      testNodeExpansion(
+        `class TestClass {
+  @deprecated
+  testMethod() {
+    return 'test';
+  }
+}`,
+        (sf) => sf.getClassOrThrow('TestClass').getMethodOrThrow('testMethod'),
+        `@deprecated
+  testMethod() {
+    return 'test';
+  }`
+      );
+    });
+
+    it('should expand method with single-line comment', () => {
+      testNodeExpansion(
+        `class TestClass {
+  // This is a single-line comment
+  testMethod() {
+    return 'test';
+  }
+}`,
+        (sf) => sf.getClassOrThrow('TestClass').getMethodOrThrow('testMethod'),
+        `// This is a single-line comment
+  testMethod() {
+    return 'test';
+  }`
+      );
+    });
+
+    it('should expand constructor with metadata', () => {
+      testNodeExpansion(
+        `class TestClass {
+  /**
+   * Constructor documentation
+   */
+  constructor() {
+    // Constructor body
+  }
+}`,
+        (sf) => sf.getClassOrThrow('TestClass').getConstructors()[0],
+        `/**
+   * Constructor documentation
+   */
+  constructor() {
+    // Constructor body
+  }`
+      );
+    });
+
+    it('should expand method with combined metadata', () => {
+      testNodeExpansion(
+        `class TestClass {
+  /**
+   * JSDoc comment
+   */
+  @deprecated
+  @injectable
+  complexMethod(): void {
+    console.log('test');
+  }
+}`,
+        (sf) => sf.getClassOrThrow('TestClass').getMethodOrThrow('complexMethod'),
+        `/**
+   * JSDoc comment
+   */
+  @deprecated
+  @injectable
+  complexMethod(): void {
+    console.log('test');
+  }`
+      );
+    });
+
+
+    it('should expand class property with JSDoc', () => {
+      testNodeExpansion(
+        `class TestClass {
+  /**
+   * A class property with JSDoc
+   */
+  private value: string = 'default';
+}`,
+        (sf) => sf.getClassOrThrow('TestClass').getProperties()[0] as any,
+        `/**
+   * A class property with JSDoc
+   */
+  private value: string = 'default';`
+      );
+    });
+
+    it('should expand arrow function property with JSDoc', () => {
+      testNodeExpansion(
+        `class TestClass {
+  /**
+   * Arrow function method with JSDoc
+   * @param input - The input parameter
+   */
+  arrowMethod = (input: string): string => {
+    return input.toUpperCase();
+  };
+}`,
+        (sf) => sf.getClassOrThrow('TestClass').getProperties()[0] as any,
+        `/**
+   * Arrow function method with JSDoc
+   * @param input - The input parameter
+   */
+  arrowMethod = (input: string): string => {
+    return input.toUpperCase();
+  };`
+      );
+    });
+
+    it('should expand standalone variable with JSDoc', () => {
+      testNodeExpansion(
+        `/**
+ * A standalone variable with JSDoc
+ * @type {string}
+ */
+const globalVariable = 'hello world';
+
+class TestClass {}`,
+        (sf) => sf.getVariableStatements()[0] as any,
+        `/**
+ * A standalone variable with JSDoc
+ * @type {string}
+ */
+const globalVariable = 'hello world';`
+      );
+    });
+  });
+});