fix: use tag-specific complexity reports (#857)

* fix(expand-task): Use tag-specific complexity reports

- Add getTagAwareFilePath utility function to resolve tag-specific file paths
- Update expandTask to use tag-aware complexity report paths
- Fix issue where expand-task always used default complexity report
- Add comprehensive tests for getTagAwareFilePath utility
- Ensure proper handling of file extensions and directory structures

Fixes #850: Expanding tasks not using tag-specific complexity reports

The expandTask function now correctly uses complexity reports specific
to the current tag context (e.g., task-complexity-report_feature-branch.json)
instead of always using the default task-complexity-report.json file.

This enables proper task expansion behavior when working with multiple
tag contexts, ensuring complexity analysis is tag-specific and accurate.

* chore: Add changeset for tag-specific complexity reports fix

* test(expand-task): Add tests for tag-specific complexity report integration

- Introduced a new test suite for verifying the integration of tag-specific complexity reports in the expandTask function.
- Added a test case to ensure the correct complexity report is used when available for a specific tag.
- Mocked file system interactions to simulate the presence of tag-specific complexity reports.

This enhances the test coverage for task expansion behavior, ensuring it accurately reflects the complexity analysis based on the current tag context.

* refactor(task-manager): unify and simplify tag-aware file path logic and tests

- Reformatted imports and cleaned up comments in test files for readability
- Centralized mocks: moved getTagAwareFilePath & slugifyTagForFilePath
  mocks to setup.js for consistency and maintainability
- Simplified utils/getTagAwareFilePath: replaced manual parsing with
  path.parse() & path.format(); improved extension handling
- Enhanced test mocks for path.parse, path.format & reset path.join
  in beforeEach to avoid interference
- All tests now pass consistently; no change in functionality

tests/unit/utils.test.js

@@ -22,10 +22,26 @@ jest.mock('fs', () => ({
 }));
 
 jest.mock('path', () => ({
-	join: jest.fn((dir, file) => `${dir}/${file}`),
+	join: jest.fn((...paths) => paths.join('/')),
 	dirname: jest.fn((filePath) => filePath.split('/').slice(0, -1).join('/')),
 	resolve: jest.fn((...paths) => paths.join('/')),
-	basename: jest.fn((filePath) => filePath.split('/').pop())
+	basename: jest.fn((filePath) => filePath.split('/').pop()),
+	parse: jest.fn((filePath) => {
+		const parts = filePath.split('/');
+		const fileName = parts[parts.length - 1];
+		const extIndex = fileName.lastIndexOf('.');
+		return {
+			dir: parts.length > 1 ? parts.slice(0, -1).join('/') : '',
+			name: extIndex > 0 ? fileName.substring(0, extIndex) : fileName,
+			ext: extIndex > 0 ? fileName.substring(extIndex) : '',
+			base: fileName
+		};
+	}),
+	format: jest.fn((pathObj) => {
+		const dir = pathObj.dir || '';
+		const base = pathObj.base || `${pathObj.name || ''}${pathObj.ext || ''}`;
+		return dir ? `${dir}/${base}` : base;
+	})
 }));
 
 jest.mock('chalk', () => ({
@@ -72,7 +88,9 @@ import {
 	taskExists,
 	formatTaskId,
 	findCycles,
-	toKebabCase
+	toKebabCase,
+	slugifyTagForFilePath,
+	getTagAwareFilePath
 } from '../../scripts/modules/utils.js';
 
 // Import the mocked modules for use in tests
@@ -119,6 +137,8 @@ describe('Utils Module', () => {
 	beforeEach(() => {
 		// Clear all mocks before each test
 		jest.clearAllMocks();
+		// Restore the original path.join mock
+		jest.spyOn(path, 'join').mockImplementation((...paths) => paths.join('/'));
 	});
 
 	describe('truncate function', () => {
@@ -677,3 +697,51 @@ describe('CLI Flag Format Validation', () => {
 		});
 	});
 });
+
+test('slugifyTagForFilePath should create filesystem-safe tag names', () => {
+	expect(slugifyTagForFilePath('feature/user-auth')).toBe('feature-user-auth');
+	expect(slugifyTagForFilePath('Feature Branch')).toBe('feature-branch');
+	expect(slugifyTagForFilePath('test@special#chars')).toBe(
+		'test-special-chars'
+	);
+	expect(slugifyTagForFilePath('UPPERCASE')).toBe('uppercase');
+	expect(slugifyTagForFilePath('multiple---hyphens')).toBe('multiple-hyphens');
+	expect(slugifyTagForFilePath('--leading-trailing--')).toBe(
+		'leading-trailing'
+	);
+	expect(slugifyTagForFilePath('')).toBe('unknown-tag');
+	expect(slugifyTagForFilePath(null)).toBe('unknown-tag');
+	expect(slugifyTagForFilePath(undefined)).toBe('unknown-tag');
+});
+
+test('getTagAwareFilePath should use slugified tags in file paths', () => {
+	const basePath = '.taskmaster/reports/complexity-report.json';
+	const projectRoot = '/test/project';
+
+	// Master tag should not be slugified
+	expect(getTagAwareFilePath(basePath, 'master', projectRoot)).toBe(
+		'/test/project/.taskmaster/reports/complexity-report.json'
+	);
+
+	// Null/undefined tags should use base path
+	expect(getTagAwareFilePath(basePath, null, projectRoot)).toBe(
+		'/test/project/.taskmaster/reports/complexity-report.json'
+	);
+
+	// Regular tag should be slugified
+	expect(getTagAwareFilePath(basePath, 'feature-branch', projectRoot)).toBe(
+		'/test/project/.taskmaster/reports/complexity-report_feature-branch.json'
+	);
+
+	// Tag with special characters should be slugified
+	expect(getTagAwareFilePath(basePath, 'feature/user-auth', projectRoot)).toBe(
+		'/test/project/.taskmaster/reports/complexity-report_feature-user-auth.json'
+	);
+
+	// Tag with spaces and special characters
+	expect(
+		getTagAwareFilePath(basePath, 'Feature Branch @Test', projectRoot)
+	).toBe(
+		'/test/project/.taskmaster/reports/complexity-report_feature-branch-test.json'
+	);
+});