ci: add GitHub workflow and AD-004 framework cache tests

AD-005: workflow on push/PR to main (Node 22, npm ci) runs lint, format:check, test, test:e2e, build.
AD-004: JSDoc for LRU keying; unit tests for cache hit, separate keys, eviction re-detect.
Update STATE and CONCERNS.

Made-with: Cursor

Author: hbarbosa02

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - name: Install
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Format
+        run: npm run format:check
+      - name: Unit tests
+        run: npm test
+      - name: E2E tests
+        run: npm run test:e2e
+      - name: Build
+        run: npm run build

.specs/codebase/CONCERNS.md

@@ -2,7 +2,7 @@
 
 **Analysis date:** 2026-04-25
 
-**Project state (decisions, todos, deferred work):** [`.specs/project/STATE.md`](../project/STATE.md) — e.g. **AD-001**–**AD-003** status, **Active blockers** (none as of last update), and **Deferred ideas** (full Angular / Laravel adapters).
+**Project state (decisions, todos, deferred work):** [`.specs/project/STATE.md`](../project/STATE.md) — e.g. **AD-001**–**AD-005** status, **Active blockers** (none as of last update), and **Deferred ideas** (full Angular / Laravel adapters).
 
 ## Tech debt
 
@@ -18,6 +18,8 @@
 - **Impact:** Same user-facing gap until real adapters are registered. Do not claim full Angular / Laravel support in product copy until adapter-level tests cover those surfaces (per AD-003).
 - **Next (matches STATE *Deferred ideas*):** Implement adapter services, register them in `FrameworkAdapterRegistryService`, and add tests before marketing support.
 
+**Documented in code and tests (AD-004, 2026-04-25):** `FrameworkDetectorService` documents LRU (max 10) keying on the raw project root string; unit tests assert cache hits, separate keys for different strings, and re-detection after eviction. See `src/mcp/core/data-access/services/framework-detector.service.ts` and `test/unit/core/data-access/services/framework-detector.service.spec.ts`.
+
 ## Security considerations
 
 **HTTP deployment without application-level auth**
@@ -55,11 +57,7 @@
 
 ## Test / ops gaps
 
-**No CI config in repository**
-
-- **Evidence:** No `.github/workflows` or `.gitlab-ci.yml` found in the workspace at analysis time.
-- **Impact:** Build/test discipline relies on local runs or off-repo automation.
-- **Fix approach:** Add a minimal pipeline running `lint`, `test`, `test:e2e`, `build` on push/PR.
+**Resolved (AD-005, 2026-04-25):** GitHub Actions workflow `.github/workflows/ci.yml` runs on push/PR to `main`/`master`: `lint`, `format:check`, `test`, `test:e2e`, `build` (Node 22, `npm ci`).
 
 **Coverage excludes ports and placeholder domains**
 

.specs/project/STATE.md

@@ -49,6 +49,34 @@
 
 ---
 
+### AD-004: Framework detection cache — keying and LRU (2026-04-25)
+
+**Decision:** Keep the current LRU cache (max 10 keys) in `FrameworkDetectorService`, keyed by the *resolved* project root string. Do not add canonical-path normalization in this pass unless profiling or user reports show duplicate entries for the same logical project as a problem.
+
+**Reason:** CONCERNS notes that different string forms of the “same” root (e.g. path variants) can cache separately; capacity is small and bounded. Changing keying (e.g. `realpath`) is a trade-off and needs targeted tests.
+
+**Trade-off:** Possible duplicate cache slots for equivalent roots; mitigated by LRU size and test coverage in `framework-detector.service.spec.ts`.
+
+**Impact:** `src/mcp/core/data-access/services/framework-detector.service.ts` (see **Fragile areas** in `.specs/codebase/CONCERNS.md`).
+
+**Status:** **Implemented** — JSDoc on `FrameworkDetectorService` and `CACHE_MAX_SIZE`; unit tests cover per-root caching, separate keys for distinct path strings, and re-detection after eviction (`test/unit/core/data-access/services/framework-detector.service.spec.ts`).
+
+---
+
+### AD-005: In-repo CI pipeline (2026-04-25)
+
+**Decision:** Add a GitHub Actions workflow; keep local `npm run precommit` (lint, format, test) for pre-push discipline. The pipeline should run `lint`, `format:check`, `test`, `test:e2e`, and `build` on push/PR to `main`/`master`, matching CONCERNS *Test / ops gaps*.
+
+**Reason:** Automated verification in-repo; catches regressions for contributors and forks.
+
+**Trade-off:** CI minutes and e2e runtime (~40s+ for stdio); Node version pinned in workflow (22).
+
+**Impact:** `.github/workflows/ci.yml`; see `.specs/codebase/CONCERNS.md`.
+
+**Status:** **Implemented** — `ci.yml` uses `actions/checkout` and `actions/setup-node` (Node 22, `npm ci`).
+
+---
+
 ## Active blockers
 
 _(None.)_
@@ -68,6 +96,7 @@ _(None yet.)_
 | 001 | Initialize `.specs/project/` (TLC)  | 2026-04-25 | e35b801 | Done    |
 | 002 | Brownfield map — 7 files in `.specs/codebase/` | 2026-04-25 | e35b801 | Done    |
 | 003 | Implement AD-001, AD-002, AD-003 (code + tests) | 2026-04-25 | e35b801 | Done    |
+| 004 | **AD-004** cache docs/tests; **AD-005** GitHub Actions CI | 2026-04-25 | — | Done    |
 
 ---
 
@@ -84,6 +113,9 @@ _(None yet.)_
 - [x] Implement **AD-001** — env schema: remove non-portable `PROJECT_ROOT` default
 - [x] Implement **AD-002** — `McpModule.forRoot` version from `package.json`
 - [x] **AD-003** initial tranche — wire placeholder domain modules, document extension points, expand detection tests
+- [x] Record **AD-004** (framework detection cache) and **AD-005** (CI gap) from **CONCERNS**
+- [x] Implement **AD-004** — JSDoc + cache/LRU/eviction unit tests
+- [x] Implement **AD-005** — `.github/workflows/ci.yml`
 
 ---
 

src/mcp/core/data-access/services/framework-detector.service.ts

@@ -4,8 +4,14 @@ import { ProjectRootContextService } from '@/mcp/core/data-access/services/proje
 
 export type FrameworkType = 'nestjs' | 'angular' | 'laravel' | null;
 
+/** AD-004: max distinct project-root *strings* (LRU evicts oldest insertion when full). */
 const CACHE_MAX_SIZE = 10;
 
+/**
+ * Caches `detect()` per `getProjectRoot()` return value. Keys are not normalized
+ * (e.g. two strings that resolve to the same path may get separate entries).
+ * See `framework-detector.service.spec.ts` and `.specs/project/STATE.md` (AD-004).
+ */
 @Injectable()
 export class FrameworkDetectorService {
   private readonly cache = new Map<string, Promise<FrameworkType>>();

test/unit/core/data-access/services/framework-detector.service.spec.ts

@@ -189,4 +189,95 @@ describe('FrameworkDetectorService', () => {
 
     expect(fileReader.readFile).toHaveBeenCalled();
   });
+
+  /** AD-004: in-memory key is the raw project root string; same root reuses one detection. */
+  it('should call readFile once for package.json when detecting twice for the same root', async () => {
+    fileReader.readFile.mockImplementation((path: string) => {
+      if (path === 'package.json') {
+        return Promise.resolve(
+          JSON.stringify({
+            dependencies: { '@nestjs/core': '^11' },
+          }),
+        );
+      }
+      return Promise.resolve(null);
+    });
+
+    await sut.detect();
+    await sut.detect();
+
+    const pkgCalls = fileReader.readFile.mock.calls.filter((c) => c[0] === 'package.json');
+    expect(pkgCalls).toHaveLength(1);
+  });
+
+  /** AD-004: different root strings are separate cache keys (no path canonicalization). */
+  it('should not share cache between different project root strings', async () => {
+    let n = 0;
+    const projectRootContext = {
+      getProjectRoot: jest.fn().mockImplementation(() => (n++ === 0 ? '/a/x' : '/b/y')),
+    } as unknown as jest.Mocked<ProjectRootContextService>;
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        FrameworkDetectorService,
+        { provide: FileReaderService, useValue: fileReader },
+        { provide: ProjectRootContextService, useValue: projectRootContext },
+      ],
+    }).compile();
+
+    const detector = module.get(FrameworkDetectorService);
+    fileReader.readFile.mockImplementation((path: string) => {
+      if (path === 'package.json') {
+        return Promise.resolve(
+          JSON.stringify({
+            dependencies: { '@nestjs/core': '^11' },
+          }),
+        );
+      }
+      return Promise.resolve(null);
+    });
+
+    await detector.detect();
+    await detector.detect();
+
+    const pkgCalls = fileReader.readFile.mock.calls.filter((c) => c[0] === 'package.json');
+    expect(pkgCalls).toHaveLength(2);
+  });
+
+  /**
+   * AD-004: when the 11th distinct root is added, the oldest key is evicted; a later
+   * detect for that evicted root runs uncached detection again.
+   */
+  it('should re-run detection for an evicted project root', async () => {
+    const projectRootContext = {
+      getProjectRoot: jest.fn(),
+    } as unknown as jest.Mocked<ProjectRootContextService>;
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        FrameworkDetectorService,
+        { provide: FileReaderService, useValue: fileReader },
+        { provide: ProjectRootContextService, useValue: projectRootContext },
+      ],
+    }).compile();
+
+    const detector = module.get(FrameworkDetectorService);
+    fileReader.readFile.mockResolvedValue(null);
+
+    for (let i = 0; i < 10; i++) {
+      projectRootContext.getProjectRoot.mockReturnValue(`/r${i}`);
+      await detector.detect();
+    }
+
+    const callsAfterTen = fileReader.readFile.mock.calls.length;
+    expect(callsAfterTen).toBeGreaterThan(0);
+
+    projectRootContext.getProjectRoot.mockReturnValue('/r10');
+    await detector.detect();
+
+    projectRootContext.getProjectRoot.mockReturnValue('/r0');
+    await detector.detect();
+
+    expect(fileReader.readFile.mock.calls.length).toBeGreaterThan(callsAfterTen);
+  });
 });