Chore/repo audit 2025 09 16 adding code coverage, type deduplication, cleanup of organization for files and folders (#5)

* chore: audit and refactor per standards

- Break all circular dependencies by using specific imports
- Consolidate duplicate interfaces
- Remove redundant barrel files
- Ensure no cycles with madge check

* refactor: remove index.ts barrels, update imports, add back selective barrels

- Removed all index.ts files and updated all imports to direct paths
- Consolidated duplicate interfaces
- Added back index.ts barrels exporting only necessary items for external use
- Fixed import of 'util' to use local guards
- Ensured no circular dependencies and green TypeScript compilation

* Refactor code structure for improved readability and maintainability

* feat: enhance error handling in API responses; add error structure to IApiResponse and update tests

* refactor: enhance tool registration process with additional type guards and improve test structure

Author: Coderrob

.eslintrc.json

@@ -36,7 +36,7 @@
     ],
     "simple-import-sort/imports": "error",
     "simple-import-sort/exports": "error",
-    "import/no-unused-modules": ["error", { "unusedExports": true }],
+    "import/no-unused-modules": ["off", { "unusedExports": true }],
     "no-console": ["error", { "allow": ["warn", "error"] }]
   }
 }

.vscode/extensions.json

@@ -3,8 +3,7 @@
     "esbenp.prettier-vscode",
     "editorconfig.editorconfig",
     "dbaeumer.vscode-eslint",
-    "DavidAnson.vscode-markdownlint",
-    "arcanis.vscode-zipfs"
+    "DavidAnson.vscode-markdownlint"
   ],
   "unwantedRecommendations": []
 }

TODO.md

@@ -16,7 +16,7 @@ This file is the canonical, human-manageable task queue for the Documentation-Dr
 
 How to use
 
-- To add a task: copy the task template below, fill out the fields, and insert the task at the appropriate priority position.
+- To add a task: copy the task template below, fill out the fields, and insert the appropriate priority position.
 - To reorder tasks: move the task block to a new place in this file. Tasks are processed top-to-bottom unless otherwise prioritized.
 - To mark a task complete: remove the task block from this file and add a short summary (task id, summary, and link to PR/commit) to the `Unreleased` section of `CHANGELOG.md`.
 
@@ -27,46 +27,155 @@ Priority convention
 - P2 — Medium (planned for upcoming work)
 - P3 — Low (nice-to-have)
 
-Task template reference
-
-See `docs/templates/task-template.md` for the canonical template and examples. The template below is a quick copy you can paste to create a task.
-
 ---
 
 id: T-001
-priority: P1
+priority: P0
 status: open
-summary: Short one-line summary of the task
-owner: Unassigned
-created: 2025-09-14
-updated: 2025-09-14
+summary: Implement comprehensive mock strategy for unit tests
+owner: AI Assistant
+created: 2025-09-16
+updated: 2025-09-16
 
 detailed_requirements:
 
-- Step 1: Do this.
+- Define readonly mock creation pattern for all external dependencies
+- Implement proper mock lifecycle management (creation in beforeEach, cleanup in afterEach)
+- Ensure mocks are fully isolated between tests
+- Use jest.Mocked<T> for type safety
+- Implement call count and parameter assertions for all mocked methods
+- Add jest.resetModules() for module isolation where needed
+- Document mock patterns in test standards
+
+positive_behaviors:
+
+- All mocks are readonly and properly typed
+- No test bleeding or state pollution
+- Clear assertion of call counts and parameters
+- Deterministic test execution
+
+negative_behaviors:
+
+- Mutable mocks
+- Missing cleanup leading to test interference
+- Incomplete call assertions
+- Memory leaks from uncleared references
+
+validations:
+
+- All existing tests pass with --detectLeaks
+- No flaky tests due to mock state
+- Coverage reports accurate (no false positives from mock pollution)
+- TypeScript compilation succeeds with mock types
+
+---
+
+id: T-002
+priority: P0
+status: open
+summary: Ensure all test files have proper afterEach cleanup
+owner: AI Assistant
+created: 2025-09-16
+updated: 2025-09-16
 
-- Step 2: Do that.
+detailed_requirements:
+
+- Add afterEach blocks to all test files
+- Clear all mocks with jest.clearAllMocks()
+- Reset modules with jest.resetModules() where appropriate
+- Close any resources (timers, connections) in mocks
+- Verify no memory leaks with --detectLeaks flag
 
 positive_behaviors:
 
-- The system should behave like this when correct.
+- Tests run cleanly without side effects
+- Memory usage remains stable across test runs
+- No interference between test suites
 
 negative_behaviors:
 
-- The system should NOT do this.
+- Memory leaks detected by Jest
+- Test state bleeding between runs
+- Resource exhaustion in CI
 
 validations:
 
-- Automated tests (unit/integration) to run and expected results.
+- jest --detectLeaks passes for all test suites
+- Memory profiling shows no growth
+- All mocks properly reset
+
+---
+
+id: T-003
+priority: P1
+status: open
+summary: Continue unit test implementation for remaining modules
+owner: AI Assistant
+created: 2025-09-16
+updated: 2025-09-16
+
+detailed_requirements:
+
+- Implement tests for formatting utilities (responses.ts, jsonapi-formatter.ts, pagination-helper.ts)
+- Add tests for tool utilities (tool-loader.ts, tool-factory.ts, etc.)
+- Create tests for API layer (backstage-catalog-api.ts)
+- Implement auth layer tests (auth-manager.ts, input-sanitizer.ts, security-auditor.ts)
+- Add cache layer tests (cache-manager.ts)
+- Test main files (server.ts, generate-manifest.ts)
+- Use lessons from mock strategy and cleanup for quality
 
-- Manual checks or QA steps.
+positive_behaviors:
 
-notes:
+- All public methods have positive and negative test cases
+- Table-driven tests for simple functions
+- Proper mocking of external dependencies
+- High test coverage (>95%)
 
-- Any additional context or links to spec ids or planning.md sections.
+negative_behaviors:
+
+- Untested code paths
+- Poor mock isolation
+- Missing edge case coverage
+
+validations:
+
+- jest --coverage shows >95% for all metrics
+- All tests pass consistently
+- No memory leaks
+- Code review passes
 
 ---
 
-Active tasks
+id: T-004
+priority: P2
+status: open
+summary: Integrate tests into CI pipeline with coverage gates
+owner: AI Assistant
+created: 2025-09-16
+updated: 2025-09-16
+
+detailed_requirements:
+
+- Configure GitHub Actions or CI to run tests
+- Set coverage thresholds (95% statements, branches, functions, lines)
+- Add test result reporting
+- Ensure ES module support in CI environment
+- Fail builds on coverage below thresholds
+
+positive_behaviors:
+
+- Automated test execution on PRs
+- Coverage requirements enforced
+- Test failures block merges
+
+negative_behaviors:
+
+- Tests not running in CI
+- Coverage regressions allowed
+- Manual test execution required
+
+validations:
 
-<!-- Add tasks below. Keep the completed tasks out of this file and move to CHANGELOG.md -> Unreleased -->
+- CI passes for current codebase
+- Coverage reports generated and accessible
+- PR checks include test status

jest.config.mjs

@@ -12,6 +12,12 @@ export default {
   },
   transformIgnorePatterns: ['node_modules/(?!(@modelcontextprotocol)/)'],
   testPathIgnorePatterns: ['<rootDir>/dist/'],
-  collectCoverageFrom: ['src/**/*.{ts,js}', '!src/**/*.spec.ts', '!src/**/*.test.ts', '!src/**/__fixtures__/**/*'],
+  collectCoverageFrom: [
+    'src/**/*.{ts,js}',
+    '!src/**/*.spec.ts',
+    '!src/**/*.test.ts',
+    '!src/types/**/*',
+    '!src/**/__fixtures__/**/*',
+  ],
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
 };

package.json

@@ -1,6 +1,5 @@
 {
   "author": "Robert Lindley",
-  "type": "module",
   "dependencies": {
     "@backstage/catalog-client": "^1.9.1",
     "@backstage/catalog-model": "^1.7.3",
@@ -14,37 +13,45 @@
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
+    "@types/express": "^5.0.3",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.0.0",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
+    "dependency-cruiser": "^17.0.1",
     "esbuild": "^0.18.18",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-import-resolver-typescript": "^4.4.4",
-    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-simple-import-sort": "^10.0.0",
+    "eslint-plugin-unused-imports": "^4.2.0",
     "jest": "^29.7.0",
     "jest-util": "^29.7.0",
+    "jscpd": "^4.0.5",
+    "madge": "^8.0.0",
     "prettier": "^3.5.3",
     "rimraf": "^5.0.0",
     "ts-jest": "^29.3.2",
+    "ts-morph": "^27.0.0",
+    "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
   },
   "main": "dist/bundle.cjs",
   "name": "@coderrob/mcp-backstage-server",
   "packageManager": "[email protected]",
   "scripts": {
-    "clean": "rimraf dist",
-    "build:types": "tsc --emitDeclarationOnly",
-    "build:bundle": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=cjs --outfile=dist/bundle.cjs --minify --sourcemap --metafile=dist/esbuild-meta.json",
     "build": "yarn clean && yarn build:bundle",
+    "build:bundle": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --outfile=dist/bundle.cjs --minify --sourcemap --metafile=dist/esbuild-meta.json",
     "build:full": "yarn clean && yarn build:types && tsc && yarn build:bundle",
+    "build:types": "tsc --emitDeclarationOnly",
+    "clean": "rimraf dist",
     "lint": "eslint 'src/**/*.ts' --ext .ts",
     "lint:fix": "prettier . --write && eslint 'src/**/*.ts' --ext .ts --fix",
     "start": "node dist/bundle.cjs",
     "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --coverage"
   },
+  "type": "module",
   "types": "dist/index.d.ts",
   "version": "1.0.0"
 }