nogrep 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nogrep",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Navigable codebase index for Claude Code — stop grepping, start navigating",
   "repository": {
     "type": "git",

package/docs/ARCHITECTURE.md

@@ -1,239 +0,0 @@
-# nogrep — Internal Architecture
-
-## Module Boundaries
-
-```
-┌──────────────────────────────────────────────────────┐
-│              CC Plugin (slash commands)                │
-│  /init · /update · /query · /status · /on · /off      │
-│  Claude orchestrates — AI work happens here            │
-└────────────────────────┬─────────────────────────────┘
-                         │ calls scripts via Bash
-         ┌───────────────┼───────────────┐
-         ▼               ▼               ▼
-┌─────────────┐  ┌─────────────┐  ┌──────────────┐
-│  Signals    │  │    Query    │  │   Settings   │
-│  (collect)  │  │  (lookup)   │  │  (r/w JSON)  │
-└─────────────┘  └──────┬──────┘  └──────────────┘
-                        │
-┌─────────────┐  ┌──────┴──────┐
-│   Writer    │  │  Validator  │
-│ (file I/O)  │  │ (freshness) │
-└─────────────┘  └─────────────┘
-```
-
-No AI client module — Claude IS the AI. The slash commands contain the analysis prompts, and Claude executes them directly during the session.
-
----
-
-## Module Responsibilities
-
-### `commands/` (slash commands)
-Markdown prompts that guide Claude through each operation. `init.md` is the most complex — it orchestrates the full pipeline. Claude reads script output, performs analysis, and writes results.
-
-### `scripts/signals.ts`
-Collects language-agnostic signals from the filesystem. Pure data collection — no AI, no writes to `.nogrep/`.
-
-```typescript
-collectSignals(root, options) → SignalResult
-```
-
-### `scripts/write.ts`
-All file I/O for the `.nogrep/` directory. Takes structured JSON input (from Claude's analysis), writes files.
-
-```typescript
-writeContextFiles(nodes: NodeResult[], outputDir: string) → void
-buildIndex(nodes: NodeResult[]) → IndexJson
-buildRegistry(nodes: NodeResult[]) → RegistryJson
-patchClaudeMd(projectRoot: string) → void
-```
-
-### `scripts/query.ts`
-Pure lookup logic. Reads `_index.json`, matches tags/keywords, ranks results. No AI, no file writes. Called by hooks and `/nogrep:query`.
-
-```typescript
-extractTerms(question: string, taxonomy: Taxonomy) → { tags, keywords }
-resolve(terms, index) → RankedResult[]
-```
-
-### `scripts/validate.ts`
-Computes SHA256 of `src_paths` contents, compares to stored `src_hash` in node frontmatter.
-
-```typescript
-checkFreshness(node: ContextNode, projectRoot: string) → StaleResult
-```
-
-### `scripts/settings.ts`
-Read/write `.claude/settings.json` and `.claude/settings.local.json`. Handles merge logic (local takes precedence).
-
----
-
-## Data Flow: `/nogrep:init`
-
-> `$PLUGIN` = `${CLAUDE_PLUGIN_ROOT}` — the absolute path to the installed plugin directory.
-
-```
-Slash command: init.md (Claude orchestrates)
-  │
-  ├─→ Bash: node $PLUGIN/dist/signals.js    → SignalResult (JSON stdout)
-  │
-  ├─→ Claude analyzes signals           → StackResult
-  │
-  ├─→ For each cluster:
-  │     Claude reads trimmed source      → NodeResult
-  │
-  ├─→ Claude detects flows              → FlowResult[]
-  │
-  └─→ Bash: node $PLUGIN/dist/write.js      (receives JSON stdin)
-        writes .nogrep/domains/*.md etc
-        writes .nogrep/_index.json
-        writes .nogrep/_registry.json
-        patches CLAUDE.md
-        writes .claude/settings.json
-```
-
----
-
-## Data Flow: Hooks
-
-```
-User types prompt
-  │
-  └─→ prompt-submit.sh
-        node $PLUGIN/dist/query.js --question "$PROMPT"
-        → injects additionalContext
-
-CC decides to run grep
-  │
-  └─→ pre-tool-use.sh (PreToolUse hook)
-        extracts keywords from grep command
-        node $PLUGIN/dist/query.js --keywords "$KEYWORDS"
-        → injects additionalContext
-
-CC starts session
-  │
-  └─→ session-start.sh (SessionStart hook)
-        node $PLUGIN/dist/validate.js
-        → injects staleness warning if needed
-```
-
----
-
-## Key Types (`scripts/types.ts`)
-
-```typescript
-export interface SignalResult {
-  directoryTree: DirectoryNode[]
-  extensionMap: Record<string, number>
-  manifests: ManifestFile[]
-  entryPoints: string[]
-  gitChurn: ChurnEntry[]
-  largeFiles: FileSize[]
-  envFiles: string[]
-  testFiles: string[]
-}
-
-export interface StackResult {
-  primaryLanguage: string
-  frameworks: string[]
-  architecture: 'monolith' | 'monorepo' | 'multi-repo' | 'microservice' | 'library'
-  domainClusters: DomainCluster[]
-  conventions: StackConventions
-  stackHints: string
-  dynamicTaxonomy: { domain: string[]; tech: string[] }
-}
-
-export interface DomainCluster {
-  name: string
-  path: string
-  confidence: number
-}
-
-export interface NodeResult {
-  id: string
-  title: string
-  category: 'domain' | 'architecture' | 'flow' | 'entity'
-  tags: TagSet
-  relatesTo: Relation[]
-  inverseRelations: Relation[]
-  srcPaths: string[]
-  keywords: string[]
-  lastSynced: SyncMeta
-  // content fields
-  purpose: string
-  publicSurface: string[]
-  doesNotOwn: string[]
-  externalDeps: ExternalDep[]
-  gotchas: string[]
-}
-
-export interface TagSet {
-  domain: string[]
-  layer: string[]
-  tech: string[]
-  concern: string[]
-  type: string[]
-}
-
-export interface IndexJson {
-  version: string
-  generatedAt: string
-  commit: string
-  stack: Pick<StackResult, 'primaryLanguage' | 'frameworks' | 'architecture'>
-  tags: Record<string, string[]>
-  keywords: Record<string, string[]>
-  paths: Record<string, PathEntry>
-}
-
-export interface RankedResult {
-  contextFile: string
-  score: number
-  matchedOn: string[]
-  summary: string
-}
-
-export interface StaleResult {
-  file: string
-  isStale: boolean
-  reason?: string
-}
-```
-
----
-
-## Error Handling Strategy
-
-- Scripts: throw typed errors (`NogrepError` with `code` field), exit 1 with JSON error on stderr
-- Hooks: fail silently (exit 0) — never block CC session
-- Never swallow errors silently in scripts
-
-```typescript
-export class NogrepError extends Error {
-  constructor(
-    message: string,
-    public code: 'NO_INDEX' | 'NO_GIT' | 'IO_ERROR' | 'STALE'
-  ) {
-    super(message)
-  }
-}
-```
-
----
-
-## Testing Strategy
-
-### Unit tests (no filesystem)
-- `query/extractor.test.ts` — NL extraction logic
-- `query/resolver.test.ts` — index lookup ranking
-- `validator/staleness.test.ts` — hash comparison logic
-- `settings/index.test.ts` — merge logic
-
-### Integration tests (real filesystem)
-- `signals.test.ts` — run against fixture projects
-- `writer/*.test.ts` — write to temp dir, verify file contents
-
-### Fixture projects (`tests/fixtures/`)
-Minimal 5-10 file projects, enough for signal detection:
-- `nestjs-project/` — NestJS with billing + auth modules
-- `django-project/` — Django with users + payments apps
-- `react-project/` — React app with auth + dashboard features

package/docs/CLAUDE.md

@@ -1,161 +0,0 @@
-# nogrep — Implementation Guide for Claude Code
-
-## What You Are Building
-
-`nogrep` is a Claude Code plugin that gives AI agents a navigable index of any codebase, so they stop doing blind grep/find exploration.
-
-**The one thing it does:** Generate and maintain a structured `.nogrep/` directory with a reverse index (`_index.json`) and thin context nodes (markdown files), so CC can find the right files in 2 reads instead of 20.
-
-**What it is NOT:** A documentation generator, a code search engine, a standalone CLI, or a replacement for GSD or Compodoc. It is a navigation layer — intentionally minimal, fully scoped to Claude Code.
-
----
-
-## Before You Start
-
-Read these files in order before writing any code:
-
-1. `docs/SPEC.md` — full technical specification, schemas, pipeline details
-2. `docs/ARCHITECTURE.md` — project structure and module boundaries
-3. `docs/CONVENTIONS.md` — code style, naming, patterns to follow
-
----
-
-## Project Stack
-
-- **Language:** TypeScript (strict mode)
-- **Runtime:** Node.js 20+
-- **Package manager:** npm
-- **Testing:** Vitest
-- **Build:** `tsup`
-- **Distribution:** CC plugin (npm package)
-
----
-
-## Repository Structure to Create
-
-```
-nogrep/
-├── scripts/
-│   ├── signals.ts        # Phase 1: universal signal collection
-│   ├── query.ts          # index lookup (called by hooks)
-│   ├── validate.ts       # staleness check (called by hooks)
-│   ├── write.ts          # structured file writer (context nodes, index, registry)
-│   ├── settings.ts       # read/write .claude/settings.json
-│   ├── trim.ts           # language-agnostic source trimming
-│   └── types.ts          # all shared TypeScript types
-├── commands/
-│   ├── init.md           # orchestrates full init pipeline
-│   ├── update.md         # diff-based update of stale nodes
-│   ├── query.md          # manual index lookup
-│   ├── status.md         # coverage + freshness summary
-│   ├── on.md             # enable nogrep
-│   └── off.md            # disable nogrep
-├── hooks/
-│   ├── pre-tool-use.sh   # intercepts grep/find/rg
-│   ├── session-start.sh  # checks index freshness on session start
-│   └── prompt-submit.sh  # injects context on every user prompt
-├── templates/
-│   └── claude-md-patch.md  # snippet appended to target project CLAUDE.md
-├── tests/
-│   ├── fixtures/           # sample mini-projects for testing
-│   │   ├── nestjs-project/
-│   │   ├── django-project/
-│   │   └── react-project/
-│   ├── signals.test.ts
-│   ├── query.test.ts
-│   └── writer.test.ts
-├── docs/
-│   ├── CLAUDE.md           # this file
-│   ├── SPEC.md             # full technical spec
-│   ├── ARCHITECTURE.md     # internal architecture doc
-│   ├── CONVENTIONS.md      # coding conventions
-│   └── TASKS.md            # implementation tasks
-├── plugin.json
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
----
-
-## Implementation Order
-
-Implement in this exact order — each step is testable before moving on:
-
-### Step 1 — Scaffold
-- `package.json`, `tsconfig.json`, `tsup.config.ts`
-- `scripts/types.ts` — all types first
-- `plugin.json` — CC plugin manifest
-
-### Step 2 — Settings
-- `scripts/settings.ts` — read/write `.claude/settings.json` and `.claude/settings.local.json`
-- `commands/on.md` and `commands/off.md` slash commands
-
-### Step 3 — Phase 1: Signals (no AI)
-- `scripts/signals.ts` — universal signal collection
-- Test against the fixtures in `tests/fixtures/`
-
-### Step 4 — Source Trimming
-- `scripts/trim.ts` — language-agnostic source trimming
-- Test against TypeScript, Python, Java snippet fixtures
-
-### Step 5 — Writers
-- `scripts/write.ts` — context files, index builder, registry, CLAUDE.md patcher
-- `templates/claude-md-patch.md`
-- Test: write to temp dirs, verify file contents
-
-### Step 6 — Init Slash Command
-- `commands/init.md` — orchestrates the full pipeline
-- Embeds Phase 2 + Phase 3 prompts (Claude does the AI work)
-- Calls `dist/signals.js` for data, `dist/write.js` for output via `${CLAUDE_PLUGIN_ROOT}`
-
-### Step 7 — Query System
-- `scripts/query.ts` — extractor + resolver
-- `commands/query.md` slash command
-
-### Step 8 — Validate + Update + Status
-- `scripts/validate.ts` — staleness detection
-- `commands/update.md` — guided incremental update
-- `commands/status.md` — index health summary
-
-### Step 9 — Hooks
-- `hooks/pre-tool-use.sh` — intercepts grep/find
-- `hooks/session-start.sh` — freshness check
-- `hooks/prompt-submit.sh` — context injection
-
-### Step 10 — README + Distribution
-- `README.md`
-- Verify `npm pack` ships correct files
-
----
-
-## Key Decisions Already Made
-
-- **No standalone CLI.** Everything runs inside CC via slash commands and hooks.
-- **No AI client / SDK.** Claude IS the AI — slash commands contain the analysis prompts, Claude executes them directly.
-- **No database.** Everything is files. `.nogrep/` lives in the repo.
-- **Scripts are mechanical.** They collect data, write files, query indexes — no AI work.
-- **Nodes are intentionally thin** — 3 sentences of purpose, public surface, does-not-own, gotchas. Not comprehensive docs.
-- **Manual Notes section** in each node is never overwritten by update.
-- **Hooks intercept at tool-call level** — not just CLAUDE.md instructions, so CC cannot bypass.
-- **Per-project settings** — `.claude/settings.json` (team, committed) or `.claude/settings.local.json` (personal, gitignored).
-- **CI is out of scope for v1** — index maintained via `/nogrep:update` during CC sessions.
-
----
-
-## Environment Variables
-
-```bash
-NOGREP_DEBUG         # optional, set to 1 for verbose script output
-```
-
-No `ANTHROPIC_API_KEY` needed — Claude does the AI work directly.
-
----
-
-## Testing Approach
-
-- Use **Vitest** for all tests
-- Fixture projects in `tests/fixtures/` are minimal — 5-10 files each, enough to test detection
-- No AI mocking needed — scripts are pure data/IO
-- Run: `npm test`

package/docs/CONVENTIONS.md

@@ -1,162 +0,0 @@
-# nogrep — Coding Conventions
-
-## Language & Runtime
-
-- TypeScript strict mode — `"strict": true` in tsconfig
-- Node.js 20+
-- ESM modules (`"type": "module"` in package.json)
-- No `any` — use `unknown` and narrow
-
----
-
-## Naming
-
-```typescript
-// Files: kebab-case
-signals.ts
-index-builder.ts
-pre-tool-use.sh
-
-// Types/Interfaces: PascalCase
-interface StackResult { ... }
-interface NodeResult { ... }
-
-// Functions: camelCase, verb-first
-collectSignals()
-buildIndex()
-resolveQuery()
-extractTerms()
-checkFreshness()
-
-// Constants: UPPER_SNAKE_CASE
-const MAX_CLUSTER_LINES = 300
-```
-
----
-
-## Functions
-
-- Small and focused — one responsibility
-- Pure functions where possible (especially in scripts)
-- Prefer named parameters for 3+ args:
-
-```typescript
-// ✅
-writeContextFiles({ nodes, outputDir, preserveManualNotes })
-
-// ❌
-writeContextFiles(nodes, outputDir, true)
-```
-
-- Always type return values explicitly on exported functions
-- Async/await everywhere — no raw Promise chains
-
----
-
-## Error Handling
-
-Always use `NogrepError` with a code for expected failures:
-
-```typescript
-// ✅
-throw new NogrepError('No .nogrep/_index.json found. Run /nogrep:init first.', 'NO_INDEX')
-
-// ❌
-throw new Error('not found')
-```
-
-Scripts catch `NogrepError` and output JSON errors to stderr.
-Hooks fail silently (exit 0) — never block the CC session.
-
----
-
-## File I/O
-
-- All file paths are absolute — resolve early, pass around as absolute
-- Use `fs/promises` — no sync fs calls
-- Writer functions take `outputDir` as explicit parameter — never hardcode `.nogrep/`
-
----
-
-## Script Output
-
-Scripts communicate via stdout (JSON for data, plain text for human-readable).
-
-```
-# ✅ Good
-{ "nodes": 17, "stale": 1 }
-
-# ❌ Too chatty
-🚀 Starting signal collection...
-📁 Found 42 files...
-```
-
-Verbose output only when `NOGREP_DEBUG=1`, and goes to stderr.
-
----
-
-## Package Structure
-
-```json
-{
-  "type": "module",
-  "files": ["dist/", "commands/", "hooks/", "templates/", "plugin.json"]
-}
-```
-
----
-
-## Dependencies
-
-Keep dependencies minimal. Approved list:
-
-| Package | Purpose |
-|---------|---------|
-| `glob` | file glob matching |
-| `gray-matter` | frontmatter parsing |
-| `js-yaml` | YAML serialization |
-| `vitest` | testing (dev) |
-| `tsup` | build (dev) |
-| `typescript` | type checking (dev) |
-| `@types/node` | Node type defs (dev) |
-
-Do not add new dependencies without a strong reason.
-
----
-
-## tsconfig.json
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "outDir": "./dist",
-    "rootDir": "./scripts",
-    "declaration": true,
-    "sourceMap": true
-  },
-  "include": ["scripts/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
-}
-```
-
----
-
-## Tests
-
-- Test files in `tests/` directory
-- Use `describe` + `it` — not `test`
-- Each test file is independent — no shared state between files
-- Use `vitest`'s `vi.mock` sparingly — prefer dependency injection
-
-```typescript
-// ✅ injectable
-const result = collectSignals('/path/to/fixture', { exclude: [] })
-
-// ❌ global mock
-vi.mock('fs/promises')
-```