Add under-anything knowledge dashboard
This commit is contained in:
qiaoxinjiu
@@ -0,0 +1,258 @@
|
||||
# .understandignore Design Spec
|
||||
|
||||
## Overview
|
||||
|
||||
Add user-configurable file exclusion via `.understandignore` files, using `.gitignore` syntax. This makes analysis faster by skipping irrelevant files (vendor code, generated output, test fixtures) without modifying hardcoded defaults.
|
||||
|
||||
## Goals
|
||||
|
||||
- Let users exclude files/directories from analysis via `.understandignore`
|
||||
- Use `.gitignore` syntax (familiar, no learning curve)
|
||||
- Keep hardcoded defaults as built-in — `.understandignore` adds patterns on top
|
||||
- Allow `!` negation to force-include files excluded by defaults
|
||||
- Auto-generate a commented-out starter file on first run (deterministic code, not LLM)
|
||||
- Pause before analysis to let user review the ignore file
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Replacing `.gitignore` — this is analysis-specific
|
||||
- Per-directory `.understandignore` files (project root and `.understand-anything/` only)
|
||||
- GUI for editing ignore patterns
|
||||
|
||||
---
|
||||
|
||||
## IgnoreFilter Module
|
||||
|
||||
New file: `packages/core/src/ignore-filter.ts`
|
||||
|
||||
Uses the [`ignore`](https://www.npmjs.com/package/ignore) npm package for gitignore-compatible pattern matching.
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
export interface IgnoreFilter {
|
||||
isIgnored(relativePath: string): boolean;
|
||||
}
|
||||
|
||||
export function createIgnoreFilter(projectRoot: string): IgnoreFilter;
|
||||
```
|
||||
|
||||
### Behavior
|
||||
|
||||
`createIgnoreFilter` loads patterns in this order (later entries can override earlier ones):
|
||||
|
||||
1. **Hardcoded defaults** — the existing exclusion patterns from project-scanner (node_modules/, .git/, dist/, build/, bin/, obj/, *.lock, *.min.js, etc.)
|
||||
2. **`.understand-anything/.understandignore`** — project-level, lives alongside the output
|
||||
3. **`.understandignore`** at project root — alternative location for visibility
|
||||
|
||||
Patterns merge additively. `!` negation in user files can override hardcoded defaults (e.g., `!dist/` force-includes dist/).
|
||||
|
||||
### Hardcoded Default Patterns
|
||||
|
||||
These are the built-in defaults (matching current project-scanner behavior, plus bin/obj for .NET):
|
||||
|
||||
```
|
||||
# Dependency directories
|
||||
node_modules/
|
||||
.git/
|
||||
vendor/
|
||||
venv/
|
||||
.venv/
|
||||
__pycache__/
|
||||
|
||||
# Build output
|
||||
dist/
|
||||
build/
|
||||
out/
|
||||
coverage/
|
||||
.next/
|
||||
.cache/
|
||||
.turbo/
|
||||
target/
|
||||
bin/
|
||||
obj/
|
||||
|
||||
# Lock files
|
||||
*.lock
|
||||
package-lock.json
|
||||
yarn.lock
|
||||
pnpm-lock.yaml
|
||||
|
||||
# Binary/asset files
|
||||
*.png
|
||||
*.jpg
|
||||
*.jpeg
|
||||
*.gif
|
||||
*.svg
|
||||
*.ico
|
||||
*.woff
|
||||
*.woff2
|
||||
*.ttf
|
||||
*.eot
|
||||
*.mp3
|
||||
*.mp4
|
||||
*.pdf
|
||||
*.zip
|
||||
*.tar
|
||||
*.gz
|
||||
|
||||
# Generated files
|
||||
*.min.js
|
||||
*.min.css
|
||||
*.map
|
||||
*.generated.*
|
||||
|
||||
# IDE/editor
|
||||
.idea/
|
||||
.vscode/
|
||||
|
||||
# Misc
|
||||
LICENSE
|
||||
.gitignore
|
||||
.editorconfig
|
||||
.prettierrc
|
||||
.eslintrc*
|
||||
*.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Starter File Generator
|
||||
|
||||
New file: `packages/core/src/ignore-generator.ts`
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
export function generateStarterIgnoreFile(projectRoot: string): string;
|
||||
```
|
||||
|
||||
### Behavior
|
||||
|
||||
- Deterministic code — scans the project directory for common patterns
|
||||
- Returns the file content as a string (caller writes it to disk)
|
||||
- All suggestions are **commented out** — user must uncomment to activate
|
||||
- Header comment explains the file, syntax, and built-in defaults
|
||||
|
||||
### Detection Logic
|
||||
|
||||
| If exists | Suggest |
|
||||
|-----------|---------|
|
||||
| `__tests__/` or `*.test.*` files | `# __tests__/`, `# *.test.*`, `# *.spec.*` |
|
||||
| `fixtures/` or `testdata/` | `# fixtures/`, `# testdata/` |
|
||||
| `test/` or `tests/` | `# test/`, `# tests/` |
|
||||
| `.storybook/` | `# .storybook/` |
|
||||
| `docs/` | `# docs/` |
|
||||
| `examples/` | `# examples/` |
|
||||
| `scripts/` | `# scripts/` |
|
||||
| `migrations/` | `# migrations/` |
|
||||
| `*.snap` files | `# *.snap` |
|
||||
| `bin/` (non-.NET, i.e. shell scripts) | `# bin/` |
|
||||
| `obj/` | `# obj/` |
|
||||
|
||||
### Generated File Format
|
||||
|
||||
```
|
||||
# .understandignore — patterns for files/dirs to exclude from analysis
|
||||
# Syntax: same as .gitignore (globs, # comments, ! negation, trailing / for dirs)
|
||||
# Lines below are suggestions — uncomment to activate.
|
||||
# Use ! prefix to force-include something excluded by defaults.
|
||||
#
|
||||
# Built-in defaults (always excluded unless negated):
|
||||
# node_modules/, .git/, dist/, build/, bin/, obj/, *.lock, *.min.js, etc.
|
||||
#
|
||||
|
||||
# --- Suggested exclusions (uncomment to activate) ---
|
||||
|
||||
# Test files
|
||||
# __tests__/
|
||||
# *.test.*
|
||||
# *.spec.*
|
||||
|
||||
# Test data
|
||||
# fixtures/
|
||||
# testdata/
|
||||
|
||||
# Documentation
|
||||
# docs/
|
||||
|
||||
# ... (more suggestions based on detection)
|
||||
```
|
||||
|
||||
Only generated if `.understand-anything/.understandignore` doesn't already exist.
|
||||
|
||||
---
|
||||
|
||||
## Skill Integration
|
||||
|
||||
### Phase 0.5: Ignore Setup (new phase in SKILL.md)
|
||||
|
||||
Added between Pre-flight (Phase 0) and SCAN (Phase 1):
|
||||
|
||||
1. Check if `.understand-anything/.understandignore` exists
|
||||
2. If not, run `generateStarterIgnoreFile(projectRoot)` and write the result to `.understand-anything/.understandignore`
|
||||
3. Report to user:
|
||||
- **First run:** "Generated `.understand-anything/.understandignore` with suggested exclusions. Please review it and uncomment any patterns you'd like to exclude. When ready, confirm to continue."
|
||||
- **Subsequent runs:** "Found `.understand-anything/.understandignore`. Review it if needed, then confirm to continue."
|
||||
4. Wait for user confirmation before proceeding
|
||||
|
||||
### Phase 1: SCAN changes
|
||||
|
||||
The `project-scanner` agent's scan script is updated to:
|
||||
|
||||
1. Collect files via `git ls-files` (or fallback)
|
||||
2. Apply agent's hardcoded pattern filter (Layer 1 — existing behavior)
|
||||
3. Apply `IgnoreFilter` from core (Layer 2 — user patterns)
|
||||
4. Add `filteredByIgnore` count to scan output
|
||||
5. Report: "Scanned {totalFiles} files ({filteredByIgnore} excluded by .understandignore)"
|
||||
|
||||
Two-layer filtering:
|
||||
- **Layer 1:** Agent's hardcoded patterns in the prompt (fast, coarse filter)
|
||||
- **Layer 2:** `IgnoreFilter` from core (deterministic code, user-configurable)
|
||||
|
||||
---
|
||||
|
||||
## Project Scanner Agent Update
|
||||
|
||||
Changes to `understand-anything-plugin/agents/project-scanner.md`:
|
||||
|
||||
- After the file list is built and Layer 1 filtering is applied, the agent runs a Node.js script that imports `createIgnoreFilter` from `@understand-anything/core` and filters the remaining paths
|
||||
- The scan result JSON includes a new `filteredByIgnore: number` field
|
||||
- Existing hardcoded exclusion patterns in the agent prompt remain for backward compatibility
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### `packages/core/src/__tests__/ignore-filter.test.ts`
|
||||
|
||||
- Parses basic glob patterns (`*.log`, `dist/`)
|
||||
- Handles `#` comments and blank lines
|
||||
- Handles `!` negation (force-include)
|
||||
- Handles `**/` recursive matching
|
||||
- Handles trailing `/` for directory-only patterns
|
||||
- Merges defaults + user patterns correctly
|
||||
- `!` in user file overrides hardcoded defaults
|
||||
- Returns `false` for paths not matching any pattern
|
||||
|
||||
### `packages/core/src/__tests__/ignore-generator.test.ts`
|
||||
|
||||
- Generates starter file with header comment
|
||||
- Detects existing directories and suggests relevant patterns
|
||||
- All suggestions are commented out (prefixed with `# `)
|
||||
- Doesn't overwrite existing file
|
||||
- Includes bin/obj suggestions when relevant
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `packages/core/src/ignore-filter.ts` | Parse .understandignore, merge with defaults, filter paths |
|
||||
| `packages/core/src/ignore-generator.ts` | Generate starter file by scanning project structure |
|
||||
| `packages/core/src/__tests__/ignore-filter.test.ts` | Filter logic tests |
|
||||
| `packages/core/src/__tests__/ignore-generator.test.ts` | Generator tests |
|
||||
| `agents/project-scanner.md` | Add Layer 2 filtering via IgnoreFilter |
|
||||
| `skills/understand/SKILL.md` | Add Phase 0.5 (generate + pause for review) |
|
||||
| `packages/core/package.json` | Add `ignore` npm dependency |
|
||||
Reference in New Issue
Block a user