Audit remediation: stabilization, concurrency, correctness, perf, tests

.devcontainer/devcontainer.json

@@ -0,0 +1,30 @@
+{
+  "name": "Reporecall",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+  "remoteUser": "node",
+  "updateRemoteUserUID": true,
+  "init": true,
+  "postCreateCommand": "npm ci",
+  "postStartCommand": "bash -lc 'git rev-parse --git-dir >/dev/null 2>&1 && git config --global --add safe.directory \"${containerWorkspaceFolder}\" || true'",
+  "forwardPorts": [37222],
+  "portsAttributes": {
+    "37222": {
+      "label": "Reporecall daemon",
+      "onAutoForward": "notify"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "GitHub.vscode-github-actions",
+        "vitest.explorer",
+        "esbenp.prettier-vscode"
+      ],
+      "settings": {
+        "files.eol": "\n",
+        "typescript.tsdk": "node_modules/typescript/lib"
+      }
+    }
+  }
+}

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test -- --run
+      - run: npm run build
+      - run: npm run smoke
+      - run: npm audit --omit=dev --audit-level=high
+      - run: npm pack --dry-run

.github/workflows/publish.yml

@@ -1,7 +1,8 @@
 name: Publish
 on:
-  push:
-    tags: ['v*']
+  release:
+    types: [published]
+  workflow_dispatch:
 permissions:
   contents: read
 jobs:
@@ -17,6 +18,9 @@ jobs:
       - run: npm run lint
       - run: npm test -- --run
       - run: npm run build
+      - run: npm run smoke
+      - run: npm audit --omit=dev --audit-level=high
+      - run: npm pack --dry-run
       - run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/release-please.yml

@@ -0,0 +1,23 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: release-please-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: .release-please-config.json
+          manifest-file: .release-please-manifest.json

.gitignore

@@ -1,6 +1,7 @@
 node_modules/
 dist/
 .memory/
+.engram/
 reports
 .claude/
 .demo/
@@ -15,3 +16,17 @@ claude-code-source-main
 .tmp/
 test/.test-data-server-*/
 test/.test-data-server-*/graphify-3/
+
+.env
+.env.*
+*.log
+.idea/
+.vscode/
+coverage/
+*.tgz
+
+# Lockfiles: npm is canonical (package-lock.json); ignore pnpm
+pnpm-lock.yaml
+
+# Local MCP config (non-portable absolute paths) — copy from .mcp.json.example
+.mcp.json

.mcp.json.example

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "reporecall": {
+      "command": "node",
+      "args": [
+        "./dist/memory.js",
+        "mcp",
+        "--project",
+        "${PROJECT_ROOT}"
+      ]
+    }
+  }
+}

.release-please-config.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "node",
+  "include-v-in-tag": true,
+  "include-component-in-tag": false,
+  "bump-minor-pre-major": true,
+  "bump-patch-for-minor-pre-major": false,
+  "pull-request-title-pattern": "chore: release ${version}",
+  "packages": {
+    ".": {
+      "package-name": "@proofofwork-agency/reporecall",
+      "release-type": "node"
+    }
+  },
+  "changelog-sections": [
+    { "type": "feat", "section": "Features" },
+    { "type": "fix", "section": "Bug Fixes" },
+    { "type": "perf", "section": "Performance Improvements" },
+    { "type": "deps", "section": "Dependencies" },
+    { "type": "revert", "section": "Reverts" },
+    { "type": "refactor", "section": "Code Refactoring" },
+    { "type": "ci", "section": "Continuous Integration", "hidden": true },
+    { "type": "build", "section": "Build System", "hidden": true },
+    { "type": "chore", "section": "Miscellaneous Chores", "hidden": true },
+    { "type": "docs", "section": "Documentation", "hidden": true },
+    { "type": "style", "section": "Styles", "hidden": true },
+    { "type": "test", "section": "Tests", "hidden": true }
+  ]
+}

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.7.1"
+}

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to Reporecall
+
+Reporecall is a local-first codebase context engine for coding agents. Keep changes focused, source-grounded, and easy to verify.
+
+## Local Setup
+
+```bash
+npm ci
+npm run build
+npm test -- --run
+```
+
+Use `make ci-precheck` before pushing. It mirrors the CI gates that run on pull requests.
+
+## Development
+
+Reporecall requires Node.js `>=20` (declared in `package.json` `engines`). Canonical workflow:
+
+```bash
+npm ci            # install dependencies
+npm run lint      # type-check (tsc --noEmit)
+npm test -- --run # run the test suite (Vitest, single run)
+npm run build     # build with tsup
+```
+
+## Pull Requests
+
+- Use one logical change per PR.
+- Include tests for behavior changes.
+- Run `make ci-precheck` and include anything you could not verify.
+- Use conventional commit-style titles such as `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `ci:`, or `chore:`.
+- Update `CHANGELOG.md` or relevant docs for user-facing changes.
+
+## Dependencies
+
+Dependency changes need a short justification in the PR:
+
+- why the package or version is needed;
+- whether it adds native code, install-time downloads, or runtime network access;
+- why existing dependencies are not enough.
+
+Security fixes are welcome. Production dependency advisories at `high` or `critical` severity must be fixed or explicitly justified before release.

Makefile

@@ -0,0 +1,24 @@
+SHELL := /bin/bash
+
+.PHONY: ci-precheck lint test build smoke audit pack-check
+
+ci-precheck: lint test build smoke audit pack-check
+	@echo "ci-precheck passed"
+
+lint:
+	npm run lint
+
+test:
+	npm test -- --run
+
+build:
+	npm run build
+
+smoke:
+	npm run smoke
+
+audit:
+	npm audit --omit=dev --audit-level=high
+
+pack-check:
+	npm pack --dry-run

README.md

@@ -26,6 +26,8 @@ reporecall serve         # Start daemon + file watcher
 reporecall lens --serve  # Open the architecture dashboard
 ```
 
+The package also exposes a `memory` CLI alias, which may collide with other global installs; `reporecall` is the canonical command name.
+
 That's it. Context is injected automatically into every Claude Code prompt via hooks, wiki pages regenerate as the code changes, and the lens dashboard is always one command away.
 
 ---
@@ -300,7 +302,7 @@ Main tool groups:
 
 | Group | Tools |
 | --- | --- |
-| Code search | `search_code`, `get_symbol`, `resolve_seed` |
+| Code search | `search_context`, `search_code`, `read_code_chunk`, `get_symbol`, `resolve_seed` |
 | Flow/navigation | `find_callers`, `find_callees`, `explain_flow`, `build_stack_tree`, `get_imports` |
 | Business context | `list_product_areas`, `business_context_query` |
 | Topology | `get_communities`, `get_hub_nodes`, `get_surprises`, `suggest_investigations` |
@@ -314,16 +316,22 @@ Configuration lives in `.memory/config.json`.
 
 | Key | Default | Description |
 | --- | --- | --- |
-| `embeddingProvider` | `"keyword"` | Retrieval backend. `keyword` is local FTS-only. |
+| `embeddingProvider` | `"local"` | Retrieval backend. `local` uses Xenova/all-MiniLM-L6-v2 local vector embeddings; `keyword` is FTS-only with no vectors (also: `ollama`, `openai`). |
 | `wikiBudget` | `400` | Max tokens for wiki injection per prompt. |
 | `wikiMaxPages` | `3` | Max wiki pages injected per prompt. |
 | `memoryBudget` | `500` | Max tokens for memory injection per prompt. |
 | `capabilityEvidence` | `true` | Use code/wiki/graph evidence to select related files for trace, architecture, and change prompts. |
 | `genericCapabilityHydration` | `true` | Hydrate broad inventory evidence into prompt context for questions like "which files implement...". |
+| `contextCompressionMode` | `"auto"` | Compress secondary code evidence in assembled context. Use `"off"` to disable or `"always"` for diagnostics. |
+| `contextCompressionPreserveTopChunks` | `1` | Number of top chunks kept as full source before secondary evidence can be compacted. |
+| `contextCompressionMinChunkTokens` | `100` | Minimum chunk size before compression is attempted. |
+| `contextCompressionTargetRatio` | `0.75` | Maximum compressed/full token ratio accepted for compacted evidence. |
 | `topologyEnabled` | `true` | Run topology/community analysis after indexing. |
 | `topologyMaxChunks` | `50000` | Skip full topology graph construction above this indexed chunk count. |
 | `shutdownTimeoutMs` | `10000` | Graceful shutdown timeout in milliseconds. |
 
+This table lists common keys only; see `src/core/config.ts` for the full, authoritative list of configuration options and defaults.
+
 Assistant/client instruction files such as `AGENTS.md`, `CLAUDE.md`, `.claude/**`, `.codex/**`, and `.mcp.json` are ignored by default as code evidence.
 
 ## CLI Reference

docs/architecture-overview.md

@@ -0,0 +1,16 @@
+# Architecture Overview
+
+Reporecall indexes a project locally and exposes source-grounded context through CLI commands, Claude Code hooks, and MCP tools.
+
+The main layers are:
+
+| Layer | Role |
+| --- | --- |
+| Indexer | Scans files, chunks source with Tree-sitter, records imports and call edges. |
+| Storage | Persists chunks, full-text search, metadata, graph edges, wiki, memory, and lens data in local stores. |
+| Search | Routes user prompts by intent, retrieves candidate chunks, expands graph evidence, and assembles prompt context. |
+| Hooks | Injects selected context into agent prompts and records hook diagnostics. |
+| MCP/CLI | Exposes search, flow explanation, wiki, memory, business context, lens export, and indexing operations. |
+| Lens/Wiki | Generates deterministic project views over code topology and business-facing capability evidence. |
+
+Reporecall should stay a repo-intelligence engine. It should not absorb provider proxying, model hosting, or editor UI responsibilities.

docs/release-verification.md

@@ -0,0 +1,28 @@
+# Release And Verification
+
+Reporecall releases are managed through release-please.
+
+Day to day:
+
+- Merge `feat:` and `fix:` changes to `main`.
+- The release-please workflow maintains a release PR.
+- Merging the release PR creates a GitHub release.
+- The publish workflow publishes the npm package from the release event.
+
+Before pushing or publishing, run:
+
+```bash
+make ci-precheck
+```
+
+The CI and publish gates run:
+
+- `npm ci`
+- `npm run lint`
+- `npm test -- --run`
+- `npm run build`
+- `npm run smoke`
+- `npm audit --omit=dev --audit-level=high`
+- `npm pack --dry-run`
+
+Do not soft-fail security, test, build, or packaging gates.

docs/retrieval-context-pipeline.md

@@ -0,0 +1,29 @@
+# Retrieval And Context Pipeline
+
+Reporecall builds context in this order:
+
+1. Sanitize and classify the prompt as `lookup`, `trace`, `bug`, `architecture`, `change`, or `skip`.
+2. Resolve explicit seeds when the prompt names a file, route, symbol, or subsystem.
+3. Retrieve candidates through keyword/vector indexes and graph expansion.
+4. Apply route-specific selection for bug localization, trace flow, or broad architecture inventory.
+5. Assemble context under the configured token budget.
+6. Add wiki, memory, and product-area evidence when relevant and within budget.
+7. Return text plus diagnostics through hooks, CLI, or MCP.
+
+Context quality is more important than raw chunk volume. For trace and architecture prompts, Reporecall should cover the implementation path across entry points, services, storage, handlers, and shared helpers when those layers exist.
+
+## Evidence Compression
+
+When context compression is enabled, Reporecall keeps primary evidence intact and compacts secondary evidence into language-aware bullets with retrievable original chunk references. Compressed entries preserve imports, signatures, decorators, route/config/error literals, query matches, line numbers, and a `chunkId`.
+
+The behavior is controlled in `.memory/config.json`:
+
+- `contextCompressionEnabled`: set `false` to disable evidence compression.
+- `contextCompressionMode`: `auto`, `always`, or `off`.
+- `contextCompressionPreserveTopChunks`: number of top chunks kept as full source.
+- `contextCompressionMinChunkTokens`: minimum chunk size before compression is attempted.
+- `contextCompressionTargetRatio`: maximum compressed/full token ratio accepted.
+
+Compressed context is reversible through the MCP `read_code_chunk` tool. Use the `chunkId` from compressed evidence, or provide `filePath` with `startLine`/`endLine`, to retrieve the full original chunk.
+
+MCP clients should prefer `search_context` for multi-file questions because it returns the same assembled, compression-aware context used by hooks and CLI explain. Use `search_code` when you explicitly need raw matching chunks instead of a token-budgeted context bundle.