diff --git a/.claude/settings.local.json b/.claude/settings.local.json index c4f664c..08d75ad 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -60,7 +60,17 @@ "mcp__plugin_chrome-devtools-mcp_chrome-devtools__wait_for", "mcp__plugin_chrome-devtools-mcp_chrome-devtools__evaluate_script", "mcp__plugin_chrome-devtools-mcp_chrome-devtools__resize_page", - "mcp__plugin_chrome-devtools-mcp_chrome-devtools__close_page" + "mcp__plugin_chrome-devtools-mcp_chrome-devtools__close_page", + "mcp__plugin_chrome-devtools-mcp_chrome-devtools__list_network_requests", + "Bash(pnpm lint:*)", + "Bash(pnpm type-check:*)", + "Bash(npx tsc:*)", + "mcp__MiniMax_Token_Plan_MCP__understand_image", + "Bash(bun dev:*)", + "mcp__MiniMax_Token_Plan_MCP__web_search", + "mcp__tavily__tavily_search", + "Bash(xxd:*)", + "Bash(ls:*)" ], "deny": [], "ask": [], diff --git a/AGENTS.md b/AGENTS.md index e746911..4742e4d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # GitNexus — Code Intelligence -This project is indexed by GitNexus as **noob-components** (675 symbols, 1378 relationships, 35 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. +This project is indexed by GitNexus as **noob-components** (749 symbols, 1584 relationships, 55 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4742e4d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,101 @@ + +# GitNexus — Code Intelligence + +This project is indexed by GitNexus as **noob-components** (749 symbols, 1584 relationships, 55 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. + +> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. + +## Always Do + +- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user. +- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. +- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits. +- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance. +- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`. + +## When Debugging + +1. `gitnexus_query({query: ""})` — find execution flows related to the issue +2. `gitnexus_context({name: ""})` — see all callers, callees, and process participation +3. `READ gitnexus://repo/noob-components/process/{processName}` — trace the full execution flow step by step +4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed + +## When Refactoring + +- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`. +- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code. +- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed. + +## Never Do + +- NEVER edit a function, class, or method without first running `gitnexus_impact` on it. +- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis. +- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph. +- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope. + +## Tools Quick Reference + +| Tool | When to use | Command | +|------|-------------|---------| +| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` | +| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` | +| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` | +| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` | +| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` | +| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` | + +## Impact Risk Levels + +| Depth | Meaning | Action | +|-------|---------|--------| +| d=1 | WILL BREAK — direct callers/importers | MUST update these | +| d=2 | LIKELY AFFECTED — indirect deps | Should test | +| d=3 | MAY NEED TESTING — transitive | Test if critical path | + +## Resources + +| Resource | Use for | +|----------|---------| +| `gitnexus://repo/noob-components/context` | Codebase overview, check index freshness | +| `gitnexus://repo/noob-components/clusters` | All functional areas | +| `gitnexus://repo/noob-components/processes` | All execution flows | +| `gitnexus://repo/noob-components/process/{name}` | Step-by-step execution trace | + +## Self-Check Before Finishing + +Before completing any code modification task, verify: +1. `gitnexus_impact` was run for all modified symbols +2. No HIGH/CRITICAL risk warnings were ignored +3. `gitnexus_detect_changes()` confirms changes match expected scope +4. All d=1 (WILL BREAK) dependents were updated + +## Keeping the Index Fresh + +After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it: + +```bash +npx gitnexus analyze +``` + +If the index previously included embeddings, preserve them by adding `--embeddings`: + +```bash +npx gitnexus analyze --embeddings +``` + +To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.** + +> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`. + +## CLI + +| Task | Read this skill file | +|------|---------------------| +| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` | +| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` | +| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` | +| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` | +| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` | +| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` | + + diff --git a/claude.md b/claude.md deleted file mode 100644 index e19f357..0000000 --- a/claude.md +++ /dev/null @@ -1,254 +0,0 @@ -# noob-components - -## Project Overview - -A Vue 3 component library built with TypeScript and Vite, providing reusable UI components and composables for management applications. The library extends Element Plus with custom components, layouts, and utilities. - -## Technology Stack - -- **Framework**: Vue 3 (Composition API) -- **Language**: TypeScript -- **Build Tool**: Vite -- **Base UI Library**: Element Plus -- **Styling**: SCSS with scoped styles -- **State Management**: Vuex (for consuming applications) -- **Internationalization**: vue3-i18n -- **Package Manager**: npm/bun - -## Project Structure - -``` -noob-components/ -├── packages/ -│ ├── base/ # Base UI components -│ │ ├── data/ # Data display components (ListTable, etc.) -│ │ ├── item/ # Form input components (Input, Select, DateTime, etc.) -│ │ └── layout/ # Layout components -│ ├── manage/ # Management-specific components -│ │ ├── common/ # Common components (login forms, etc.) -│ │ └── router/ # Router layout components (index.vue, zhuBeiDong.vue) -│ └── app.ts # Main export file -├── plugs/ -│ ├── composables/ # Vue composables -│ │ ├── useListTable.ts # Table data management -│ │ ├── useModifyForm.ts # Form modification logic -│ │ └── ... -│ ├── http/ # HTTP utilities and API client -│ ├── element/ # Element Plus utilities -│ └── utils/ # General utilities -├── dist/ # Build output -│ ├── noob-mengyxu.js -│ ├── noob-mengyxu.css -│ └── style.css -└── vite.config.ts # Vite configuration -``` - -## Key Components - -### Router Layouts (`packages/manage/router/`) - -Two main layout components for management applications: - -- **index.vue**: Standard layout with horizontal/vertical menu support -- **zhuBeiDong.vue**: Alternative layout with specific styling - -Both components: -- Provide app structure with header, aside, and main content areas -- Support theme switching (via `state.style`) -- Support size adjustments (via `state.size`) -- Handle user authentication checks -- Use **scoped CSS** with `:deep()` for child component styling - -### Login Components (`packages/manage/common/`) - -- **login2.vue**: Login form with vertical layout (labels above inputs) - -### Data Components (`packages/base/data/`) - -- **list-table.vue**: Table component with pagination, sorting, filtering - - Uses TypeScript interface-based props - - Integrates with `useListTable` composable - - Supports Element Plus table features - -### Form Components (`packages/base/item/`) - -- **input.vue**: Text input wrapper -- **select.vue**: Select dropdown wrapper -- **datetime.vue**: Date/time picker wrapper -- **modify-form.vue**: Form modification component - -All form components: -- Support `.full` class for 100% width -- Have default constrained width via `.form-item` -- Use scoped styles - -## Key Composables - -### useListTable (`plugs/composables/useListTable.ts`) - -Manages table data with pagination and filtering. - -**Important implementation details:** -- Uses `deepCopy(toRaw(example))` to avoid infinite reactivity loops -- Automatically manages pagination params (`page`, `size`) -- Supports both array and paginated response (`{ data: [], total: N }`) -- Has `disableAutoQuery` option to disable automatic queries - -**Interface:** -```typescript -interface TableColumn { - code: string; // Property path (supports nested like "task.name") - name?: string; // Display name - i18n?: string; // i18n key - type?: string; // Column type - width?: string | number; - fixed?: boolean | 'left' | 'right'; - align?: 'left' | 'center' | 'right'; - slot?: boolean; // Use custom slot - dict?: string; // Dictionary for value mapping - timestamp?: boolean; // Format as timestamp - filesize?: boolean; // Format as file size -} -``` - -### useModifyForm (`plugs/composables/useModifyForm.ts`) - -Manages form state for add/edit operations. - -## Styling Conventions - -### CSS Scoping - -- **Router components** (`index.vue`, `zhuBeiDong.vue`): - - Split into unscoped (for `body`) and scoped blocks - - Use `:deep()` for child components from library - - Example: `:deep(.head-icon)`, `:deep(.el-input)` - -- **Form components** (`input.vue`, `select.vue`, etc.): - - Use scoped styles - - Support `.full` class to override width - -### CSS Variables Binding - -Components use `v-bind()` to bind Vuex state to CSS: -```scss -color: v-bind("state.style.color"); -background-color: v-bind("state.style.bodyBg"); -font-size: v-bind("state.size.fontSize"); -height: v-bind("state.size.headHeight"); -``` - -### State Structure - -```typescript -state.style = { - color: string; - bodyBg: string; - headBg: string; - itemBg: string; - selectionBg: string; - selectionColor: string; -} - -state.size = { - fontSize: string; - headHeight: string; - asideWidth: string; - mainHeight: string; - tableHeight: string; - headIconSize: string; - size: 'small' | 'default' | 'large'; -} -``` - -## Build Configuration - -### Library Build (`vite.config.ts`) - -- Entry: `packages/app.ts` -- Output: `dist/noob-mengyxu.js` and `dist/noob-mengyxu.css` -- CSS is extracted separately (not injected into JS) -- Vue is externalized (peer dependency) - -### Development Workflow - -1. **Local development with linking:** - ```bash - bun link - cd ../s6a_manage - bun link noob-mengyxu - ``` - -2. **Important**: When using `bun link`, JS/templates load from source but CSS loads from `dist/` - - After CSS changes, must rebuild: `npm run build:lib` - -## Common Issues and Solutions - -### Issue: CSS Conflicts from Multiple Router Components - -**Problem**: Multiple unscoped CSS rules causing variable conflicts - -**Solution**: -- Use scoped styles with `:deep()` for child elements -- Split into unscoped (body only) and scoped blocks - -### Issue: Infinite Loop in useListTable with deepCopy - -**Problem**: `deepCopy(example)` inside `watchEffect` establishes reactive dependencies - -**Solution**: Use `deepCopy(toRaw(example))` for deep non-reactive clone - -### Issue: Form Input Width Issues - -**Problem**: `.form-item` class collision between components - -**Solution**: -- Add `.full { width: 100%; }` to base components -- Remove conflicting styles from router components -- Use `:deep()` when needed to style library components - -### Issue: Header Icons Not Styled - -**Problem**: After scoping, library components don't have scoped attribute - -**Solution**: Change `.head-icon` to `:deep(.head-icon)` in router components - -## TypeScript Conventions - -- Use interface-based prop definitions: `defineProps()` -- Use `withDefaults()` for default values -- Prefer `undefined` over `null` for optional props (simplifies types) -- Use `() => []` or `() => ({})` for array/object defaults - -## Exports - -Main export file: `packages/app.ts` - -Exports are organized into modules: -- `Element`: Element Plus utilities -- `NoobHead`: Header components -- `NoobInput`, `NoobButton`, etc.: Form components -- `ListTable`, `ModifyForm`: Data components -- `Api`: HTTP client -- `Styles`, `Size`: Theme utilities -- Composables: `useListTable`, `useModifyForm`, etc. - -## Recent Changes - -1. **TypeScript Conversion**: Converted list-table.vue to interface-based props -2. **CSS Scoping**: Fixed conflicts by scoping router component styles -3. **Reactivity Fix**: Changed to `deepCopy(toRaw(example))` in useListTable -4. **Form Layout**: Fixed login form to use vertical layout (labels above inputs) -5. **Pagination**: Fixed handling of paginated responses `{ data: [], total: N }` - -## Dependencies - -Key dependencies: -- `vue`: ^3.x -- `element-plus`: UI library -- `vue3-i18n`: Internationalization -- `vuex`: State management (for consumers) -- `axios`: HTTP client -- `js-md5`: Password hashing -- `@vueuse/core`: Vue utilities -- `lodash-es`: Utility functions