nogrep 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# nogrep
+
+A Claude Code plugin that gives AI agents a navigable index of any codebase, so they stop doing blind `grep`/`find` exploration.
+
+## What it does
+
+`nogrep` generates a structured `.nogrep/` directory with a reverse index and thin context nodes (markdown files). When Claude Code needs to find something, it reads 2 files instead of running 20 grep commands.
+
+## Install
+
+Add the marketplace and install the plugin:
+
+```
+/plugin marketplace add alirezanasseh/nogrep
+/plugin install nogrep@nogrep-marketplace
+```
+
+For local development/testing:
+
+```bash
+git clone https://github.com/alirezanasseh/nogrep.git
+cd nogrep && npm install && npm run build
+claude --plugin-dir ./nogrep
+```
+
+## Quick start
+
+1. Open your project in Claude Code
+2. Run `/nogrep:init` — Claude analyzes your codebase and generates the index
+3. That's it. Hooks automatically inject context when Claude searches your code
+
+## How it works
+
+```
+Phase 1: Collect signals    (scripts — file tree, deps, git churn, entry points)
+Phase 2: Detect stack       (Claude — language, frameworks, domain clusters)
+Phase 3: Analyze clusters   (Claude — per-domain context nodes from trimmed source)
+Phase 4: Write index        (scripts — .nogrep/ files, _index.json, CLAUDE.md patch)
+```
+
+Scripts handle data collection and file I/O. Claude does all the analysis work directly during the session — no API keys needed.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/nogrep:init` | Generate the full codebase index |
+| `/nogrep:update` | Incrementally update stale nodes |
+| `/nogrep:query <question>` | Manual index lookup |
+| `/nogrep:status` | Show index health and freshness |
+| `/nogrep:on` | Enable nogrep |
+| `/nogrep:off` | Disable nogrep |
+
+## Hooks
+
+nogrep installs three Claude Code hooks:
+
+- **PreToolUse** — intercepts `grep`/`find`/`rg` commands and injects relevant context files
+- **UserPromptSubmit** — injects context for code navigation prompts
+- **SessionStart** — checks index freshness and warns if stale
+
+## Output structure
+
+```
+.nogrep/
+├── _index.json        # reverse index (tags → files, keywords → files, paths → context)
+├── _registry.json     # source path → context file mapping
+├── _taxonomy.json     # allowed tags for this project
+├── domains/           # one file per business domain
+├── architecture/      # cross-domain architectural concerns
+├── flows/             # multi-domain business flows
+└── entities/          # data models
+```
+
+Each context node is a thin markdown file with YAML frontmatter — purpose, public surface, gotchas, and tags. Nodes include a `## Manual Notes` section that is never overwritten by updates.
+
+## Settings
+
+nogrep stores its enabled state in your project's `.claude/` directory:
+
+- `.claude/settings.json` — team settings (commit to repo)
+- `.claude/settings.local.json` — personal overrides (gitignored)
+
+## Requirements
+
+- Node.js 20+
+- Claude Code
+
+## License
+
+MIT

package/commands/init.md

@@ -0,0 +1,241 @@
+Initialize nogrep for this project. Follow these steps exactly in order.
+
+---
+
+## Step 1 — Collect Signals
+
+Run the signal collection script to gather project metadata:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/signals.js" --root .
+```
+
+Save the JSON output — you will use it in Step 2.
+
+---
+
+## Step 2 — Detect Stack
+
+Analyze the signals from Step 1. Look at the directory tree, dependency manifests, file extension distribution, and entry point candidates.
+
+Produce a JSON object with this exact shape (no prose, no markdown fences in your output — just the raw JSON):
+
+```
+{
+  "primary_language": "typescript",
+  "frameworks": ["nestjs", "react"],
+  "architecture": "monolith",
+  "domain_clusters": [
+    { "name": "billing", "path": "src/billing/", "confidence": 0.95 }
+  ],
+  "conventions": {
+    "entry_pattern": "*.module.ts",
+    "test_pattern": "*.spec.ts",
+    "config_location": "src/config/"
+  },
+  "stack_hints": "NestJS: *.module.ts = module boundary, *.service.ts = business logic",
+  "dynamic_taxonomy": {
+    "domain": ["billing", "auth", "users"],
+    "tech": ["stripe", "redis", "postgres"]
+  }
+}
+```
+
+**Architecture detection rules:**
+- `monolith` — single dependency manifest at root, one primary framework
+- `monorepo` — multiple dependency manifests with shared tooling (nx, turborepo, lerna, workspaces)
+- `multi-repo` — multiple dependency manifests at depth 1, no shared tooling, separate stacks per subfolder
+- `microservice` — multiple independently deployable services, often with Docker/K8s config
+- `library` — single package, exports API surface, no application entry points
+
+**Domain cluster detection:**
+- Look at top-level directories under `src/`, `app/`, `lib/`, `packages/`
+- Each cluster is a cohesive area of business logic (e.g., `billing`, `auth`, `users`)
+- Set confidence 0.0–1.0 based on how clearly defined the boundary is
+- Include at least the `path` glob pattern (e.g., `src/billing/**`)
+
+Save this result — you will use it in Steps 3 and 5.
+
+---
+
+## Step 3 — Analyze Each Domain Cluster
+
+For **each** domain cluster identified in Step 2, do the following:
+
+### 3a. Trim the source files
+
+Run the trim script to get signatures-only view of the cluster's source files. Pass all source files in the cluster's path as arguments:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/trim.js" <file1> <file2> ...
+```
+
+To find the files in the cluster, use the cluster's `path` from Step 2 to list source files:
+
+```bash
+find <cluster_path> -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.java" -o -name "*.go" -o -name "*.rs" -o -name "*.rb" -o -name "*.swift" -o -name "*.dart" -o -name "*.kt" -o -name "*.cs" -o -name "*.tsx" -o -name "*.jsx" \) | head -30
+```
+
+Then pass those files to the trim script.
+
+### 3b. Generate a context node
+
+Using the trimmed source from 3a and the stack info from Step 2, generate a context node.
+
+For each cluster, produce a JSON object with this shape:
+
+```
+{
+  "id": "billing",
+  "title": "Billing & Payments",
+  "category": "domain",
+  "purpose": "2-3 sentences MAX. Business intent, not technical description.",
+  "public_surface": ["BillingService.createSubscription(userId, planId)", "POST /billing/webhook"],
+  "does_not_own": ["email delivery → notifications", "user identity → auth"],
+  "external_deps": [{"name": "stripe", "usage": "payment processing"}],
+  "tags": {
+    "domain": ["billing"],
+    "layer": ["business", "data"],
+    "tech": ["stripe", "postgres"],
+    "concern": ["error-handling", "idempotency"],
+    "type": ["module"]
+  },
+  "relates_to": [
+    {"id": "notifications", "reason": "triggers invoice emails after payment events"}
+  ],
+  "src_paths": ["src/billing/**"],
+  "keywords": ["stripe", "webhook", "invoice", "retry", "idempotent"],
+  "gotchas": ["Webhook handler must be idempotent — check event.id before processing"]
+}
+```
+
+**Allowed tag values (use ONLY these — never invent new ones):**
+- `layer`: presentation, business, data, infrastructure, cross-cutting
+- `concern`: security, performance, caching, validation, error-handling, idempotency, observability
+- `type`: module, flow, entity, integration, config, ui, test
+- `domain`: use values from Step 2's `dynamic_taxonomy.domain`
+- `tech`: use values from Step 2's `dynamic_taxonomy.tech`
+
+**Rules:**
+- `purpose`: max 3 sentences — what the domain exists to do, not how
+- `gotchas`: max 5 items — non-obvious behaviors, footguns, constraints
+- `keywords`: 5–15 items — terms a developer would grep for to find this domain
+- `does_not_own`: include explicit redirections ("email delivery → notifications")
+- `id`: kebab-case, matches the cluster name
+
+Collect all node results — you will use them in Step 5.
+
+---
+
+## Step 4 — Detect Flows
+
+Review all the nodes from Step 3. A cluster qualifies as a cross-domain **flow** when:
+- Its import graph or `relates_to` touches 3+ distinct domain clusters, OR
+- It is named with flow keywords: `checkout`, `onboarding`, `signup`, `pipeline`, `workflow`, `process`
+
+For each detected flow, generate a node with `"category": "flow"` using the same schema as Step 3b. Flow nodes go in `.nogrep/flows/`.
+
+Add any flow nodes to your collection from Step 3.
+
+---
+
+## Step 5 — Write Everything
+
+Now assemble the final input for the writer script. Create a JSON object combining all nodes and the stack info:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "billing",
+      "title": "Billing & Payments",
+      "category": "domain",
+      "tags": { "domain": ["billing"], "layer": ["business"], "tech": ["stripe"], "concern": [], "type": ["module"] },
+      "relatesTo": [{"id": "notifications", "reason": "triggers emails"}],
+      "inverseRelations": [],
+      "srcPaths": ["src/billing/**"],
+      "keywords": ["stripe", "webhook"],
+      "lastSynced": { "commit": "", "timestamp": "2025-03-13T10:00:00Z", "srcHash": "" },
+      "purpose": "Handles all payment processing...",
+      "publicSurface": ["BillingService.createSubscription()"],
+      "doesNotOwn": ["email delivery → notifications"],
+      "externalDeps": [{"name": "stripe", "usage": "payment processing"}],
+      "gotchas": ["Webhook must be idempotent"]
+    }
+  ],
+  "stack": {
+    "primaryLanguage": "typescript",
+    "frameworks": ["nestjs"],
+    "architecture": "monolith"
+  }
+}
+```
+
+**Important:** When converting from Step 3's output format to the writer's input format:
+- `relates_to` → `relatesTo`
+- `src_paths` → `srcPaths`
+- `does_not_own` → `doesNotOwn`
+- `public_surface` → `publicSurface`
+- `external_deps` → `externalDeps`
+- Add `inverseRelations: []` (the writer populates these automatically)
+- Add `lastSynced` with empty `commit`, current ISO timestamp, and empty `srcHash`
+
+Pipe the JSON to the writer script:
+
+```bash
+echo '<YOUR_JSON>' | node "${CLAUDE_PLUGIN_ROOT}/dist/write.js" --root .
+```
+
+This will:
+- Create `.nogrep/` directory with all context node files
+- Build `_index.json` (reverse index)
+- Build `_registry.json` (source path → context file mapping)
+- Patch `CLAUDE.md` with navigation instructions
+
+---
+
+## Step 6 — Write Taxonomy
+
+Write `_taxonomy.json` to `.nogrep/` with the detected taxonomy. Use the `dynamic_taxonomy` from Step 2:
+
+```bash
+cat > .nogrep/_taxonomy.json << 'TAXONOMY_EOF'
+{
+  "static": {
+    "layer": ["presentation", "business", "data", "infrastructure", "cross-cutting"],
+    "concern": ["security", "performance", "caching", "validation", "error-handling", "idempotency", "observability"],
+    "type": ["module", "flow", "entity", "integration", "config", "ui", "test"]
+  },
+  "dynamic": {
+    "domain": <DOMAIN_VALUES_FROM_STEP_2>,
+    "tech": <TECH_VALUES_FROM_STEP_2>
+  },
+  "custom": {}
+}
+TAXONOMY_EOF
+```
+
+---
+
+## Step 7 — Enable nogrep
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/settings.js" --set enabled=true
+```
+
+---
+
+## Done
+
+Tell the user:
+
+> nogrep initialized successfully. The `.nogrep/` directory contains your codebase index.
+>
+> - **Context nodes:** one per domain/flow in `.nogrep/domains/` and `.nogrep/flows/`
+> - **Index:** `.nogrep/_index.json` — reverse lookup by tags, keywords, and paths
+> - **Registry:** `.nogrep/_registry.json` — maps source paths to context files
+>
+> nogrep is now enabled. Hooks will automatically inject context when you search.
+>
+> To update after code changes: `/nogrep:update`
+> To check index health: `/nogrep:status`

package/commands/off.md

@@ -0,0 +1,11 @@
+Disable nogrep for this project.
+
+Run this command to disable nogrep:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/settings.js" --set enabled=false
+```
+
+Tell the user:
+
+> nogrep is now disabled. Context injection is paused. Run `/nogrep:on` to re-enable.

package/commands/on.md

@@ -0,0 +1,21 @@
+Enable nogrep for this project.
+
+Run this command to enable nogrep:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/settings.js" --set enabled=true
+```
+
+Then check if the nogrep index exists:
+
+```bash
+test -f .nogrep/_index.json && echo "INDEX_EXISTS" || echo "INDEX_MISSING"
+```
+
+If the index is missing, tell the user:
+
+> nogrep is now enabled, but no index exists yet. Run `/nogrep:init` to generate the codebase index.
+
+If the index exists, tell the user:
+
+> nogrep is now enabled. Context will be injected automatically.

package/commands/query.md

@@ -0,0 +1,13 @@
+---
+allowed-tools: Bash(node *)
+---
+
+Run the nogrep query system to find relevant context files for the given question.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/query.js" --question "$ARGUMENTS" --format summary --limit 5
+```
+
+If results are returned, read the top context files to understand the relevant parts of the codebase before exploring source code directly.
+
+If no results are found, let the user know and suggest they run `/nogrep:init` if the index hasn't been created yet.

package/commands/status.md

@@ -0,0 +1,15 @@
+Show the current status of the nogrep index.
+
+Run the validation script:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/validate.js" --format text
+```
+
+If the command fails, tell the user:
+
+> No nogrep index found. Run `/nogrep:init` to generate the codebase index.
+
+If it succeeds, display the output to the user. If there are stale nodes, suggest:
+
+> Run `/nogrep:update` to refresh stale nodes.

package/commands/update.md

@@ -0,0 +1,89 @@
+Update stale nogrep context nodes based on recent changes.
+
+## Step 1: Check for stale nodes
+
+Run the validation script to find stale nodes:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/validate.js" --format json
+```
+
+If there are no stale nodes, tell the user:
+
+> All nogrep context nodes are up to date. Nothing to update.
+
+If the validation fails because no index exists, tell the user:
+
+> No nogrep index found. Run `/nogrep:init` first.
+
+## Step 2: Identify changed files
+
+Run git diff to find recently changed files:
+
+```bash
+git diff origin/main --name-only 2>/dev/null || git diff HEAD~10 --name-only 2>/dev/null || echo "NO_GIT"
+```
+
+If no git is available, tell the user you'll re-analyze all stale nodes based on hash mismatch.
+
+## Step 3: Map changes to affected nodes
+
+Read `.nogrep/_registry.json` to map changed files to their context nodes.
+
+For each stale node from Step 1:
+1. Read the existing context file to extract `## Manual Notes` content
+2. Read the source files listed in the node's `src_paths` frontmatter
+3. Use the trimming script to get signatures:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/dist/trim.js" <source_file_paths>
+```
+
+## Step 4: Re-analyze each affected cluster
+
+For each stale node, analyze the trimmed source and generate an updated context node.
+
+Read `.nogrep/_taxonomy.json` for allowed tag values.
+
+Return JSON only, no prose, no markdown fences:
+
+```
+{
+  "purpose": "2-3 sentences MAX. Business intent, not technical description.",
+  "public_surface": ["list of exported functions/routes/events other domains use"],
+  "does_not_own": ["what this module delegates elsewhere, with → target domain"],
+  "external_deps": [{"name": "lib", "usage": "what it's used for"}],
+  "tags": {
+    "domain": [],
+    "layer": [],
+    "tech": [],
+    "concern": [],
+    "type": []
+  },
+  "keywords": ["terms a developer would search to find this domain"],
+  "gotchas": ["max 5 non-obvious behaviors, footguns, or constraints"]
+}
+```
+
+Rules:
+- purpose: max 3 sentences
+- gotchas: max 5 items
+- keywords: 5-15 items
+- tags: use taxonomy values only, never invent new tag values
+- does_not_own: include explicit redirections ("email delivery → notifications")
+
+## Step 5: Write updates
+
+Combine all updated node results with any unchanged nodes. Pipe the full set as JSON to the writer:
+
+```bash
+echo '<json_input>' | node "${CLAUDE_PLUGIN_ROOT}/dist/write.js" --root .
+```
+
+The writer automatically preserves `## Manual Notes` sections from existing files.
+
+## Step 6: Confirm
+
+Tell the user which nodes were updated and suggest reviewing the changes:
+
+> Updated N nogrep context nodes. Run `git diff .nogrep/` to review changes.

package/dist/chunk-SMUAF6SM.js

@@ -0,0 +1,12 @@
+// scripts/types.ts
+var NogrepError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+};
+
+export {
+  NogrepError
+};
+//# sourceMappingURL=chunk-SMUAF6SM.js.map

package/dist/chunk-SMUAF6SM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../scripts/types.ts"],"sourcesContent":["// --- Directory / File types ---\n\nexport interface DirectoryNode {\n  name: string\n  path: string\n  type: 'file' | 'directory'\n  children?: DirectoryNode[]\n}\n\nexport interface ManifestFile {\n  path: string\n  type: string\n  depth: number\n}\n\nexport interface ChurnEntry {\n  path: string\n  changes: number\n}\n\nexport interface FileSize {\n  path: string\n  bytes: number\n}\n\n// --- Signal collection ---\n\nexport interface SignalResult {\n  directoryTree: DirectoryNode[]\n  extensionMap: Record<string, number>\n  manifests: ManifestFile[]\n  entryPoints: string[]\n  gitChurn: ChurnEntry[]\n  largeFiles: FileSize[]\n  envFiles: string[]\n  testFiles: string[]\n}\n\n// --- Stack detection ---\n\nexport interface StackConventions {\n  entryPattern: string\n  testPattern: string\n  configLocation: string\n}\n\nexport interface DomainCluster {\n  name: string\n  path: string\n  confidence: number\n}\n\nexport interface StackResult {\n  primaryLanguage: string\n  frameworks: string[]\n  architecture: 'monolith' | 'monorepo' | 'multi-repo' | 'microservice' | 'library'\n  domainClusters: DomainCluster[]\n  conventions: StackConventions\n  stackHints: string\n  dynamicTaxonomy: { domain: string[]; tech: string[] }\n}\n\n// --- Tags ---\n\nexport interface TagSet {\n  domain: string[]\n  layer: string[]\n  tech: string[]\n  concern: string[]\n  type: string[]\n}\n\nexport interface Taxonomy {\n  static: {\n    layer: string[]\n    concern: string[]\n    type: string[]\n  }\n  dynamic: {\n    domain: string[]\n    tech: string[]\n  }\n  custom: Record<string, string[]>\n}\n\n// --- Relations ---\n\nexport interface Relation {\n  id: string\n  reason: string\n}\n\nexport interface ExternalDep {\n  name: string\n  usage: string\n}\n\nexport interface SyncMeta {\n  commit: string\n  timestamp: string\n  srcHash: string\n}\n\n// --- Context nodes ---\n\nexport interface NodeResult {\n  id: string\n  title: string\n  category: 'domain' | 'architecture' | 'flow' | 'entity'\n  tags: TagSet\n  relatesTo: Relation[]\n  inverseRelations: Relation[]\n  srcPaths: string[]\n  keywords: string[]\n  lastSynced: SyncMeta\n  purpose: string\n  publicSurface: string[]\n  doesNotOwn: string[]\n  externalDeps: ExternalDep[]\n  gotchas: string[]\n}\n\n// --- Index ---\n\nexport interface PathEntry {\n  context: string\n  tags: string[]\n}\n\nexport interface IndexJson {\n  version: string\n  generatedAt: string\n  commit: string\n  stack: Pick<StackResult, 'primaryLanguage' | 'frameworks' | 'architecture'>\n  tags: Record<string, string[]>\n  keywords: Record<string, string[]>\n  paths: Record<string, PathEntry>\n}\n\n// --- Registry ---\n\nexport interface RegistryMapping {\n  glob: string\n  contextFile: string\n  watch: boolean\n}\n\nexport interface RegistryJson {\n  mappings: RegistryMapping[]\n}\n\n// --- Query ---\n\nexport interface RankedResult {\n  contextFile: string\n  score: number\n  matchedOn: string[]\n  summary: string\n}\n\n// --- Validation ---\n\nexport interface StaleResult {\n  file: string\n  isStale: boolean\n  reason?: string\n}\n\n// --- Settings ---\n\nexport interface NogrepSettings {\n  enabled: boolean\n}\n\n// --- Errors ---\n\nexport type NogrepErrorCode = 'NO_INDEX' | 'NO_GIT' | 'IO_ERROR' | 'STALE'\n\nexport class NogrepError extends Error {\n  constructor(\n    message: string,\n    public code: NogrepErrorCode,\n  ) {\n    super(message)\n  }\n}\n"],"mappings":";AAkLO,IAAM,cAAN,cAA0B,MAAM;AAAA,EACrC,YACE,SACO,MACP;AACA,UAAM,OAAO;AAFN;AAAA,EAGT;AACF;","names":[]}

package/dist/query.d.ts

@@ -0,0 +1,12 @@
+import { Taxonomy, IndexJson, RankedResult } from './types.js';
+
+declare function extractTerms(question: string, taxonomy: Taxonomy): {
+    tags: string[];
+    keywords: string[];
+};
+declare function resolveQuery(terms: {
+    tags: string[];
+    keywords: string[];
+}, index: IndexJson, limit?: number): RankedResult[];
+
+export { extractTerms, resolveQuery };