@codewizard-dt/bootstrap 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,335 @@
|
|
|
1
|
+
# MCP Tools Guide
|
|
2
|
+
|
|
3
|
+
**Purpose**: Mandatory MCP tool usage rules for AI agents
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## ⚠️ TOP RULE — READ FIRST
|
|
8
|
+
|
|
9
|
+
**NEVER use `sed`, `awk`, `perl -i`, `echo >>`, or any other shell command to edit a file.** This applies to **every** file type — code, markdown, JSON, YAML, `.env`, anything. The fact that markdown is allowed to use standard tools means use the **`Edit`** and **`Write`** tools, **NOT** `sed`.
|
|
10
|
+
|
|
11
|
+
If you find yourself reaching for `sed -i` to flip task checkboxes, update a status line, replace a string in a config file, or do "just a quick fix" to a doc — **stop**. Use the `Edit` tool. If you have many similar replacements in one file, use `Edit` with `replace_all: true` or call `Edit` multiple times. The `Edit` tool is always the right answer.
|
|
12
|
+
|
|
13
|
+
The shell is for running programs (`pnpm test`, `git mv`, `curl`), not for inspecting or modifying files.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## MANDATORY: MCP Tool Requirements
|
|
18
|
+
|
|
19
|
+
These MCP servers are **REQUIRED** for all applicable operations. Using standard tools when an MCP tool exists is a violation of project rules.
|
|
20
|
+
|
|
21
|
+
| MCP Server | Mandatory For | Replaces |
|
|
22
|
+
|------------|--------------|----------|
|
|
23
|
+
| **Serena** | All **code** exploration and editing; **all** file/directory exploration and search (code, markdown, config, anything) | `Read`, `Edit`, `Write`, `Grep`, `Glob` (for code files); `bash` exploration commands (`ls`, `cat`, `find`, `grep`, `sed`, `awk`, `head`, `tail`, `tree`) for **any** file type |
|
|
24
|
+
| **Context7** | All library/framework documentation lookups | WebSearch, WebFetch (for library docs) |
|
|
25
|
+
| **Brave Search** | All general web research | WebSearch (for non-library topics) |
|
|
26
|
+
| **Playwright** | Browser automation, screenshots, UI interaction | WebFetch (for rendered pages) |
|
|
27
|
+
|
|
28
|
+
### Standard tools (`Read`, `Edit`, `Write`) are permitted for:
|
|
29
|
+
|
|
30
|
+
- **Markdown files** (`.md`) — content edits use standard tools (Serena's symbolic editor doesn't apply to prose)
|
|
31
|
+
- **Config files** — JSON, YAML, TOML, `.env`, `.gitignore`, `package.json`, etc.
|
|
32
|
+
- **Creating brand-new files** of any type
|
|
33
|
+
- **Binary files and images** (read only)
|
|
34
|
+
|
|
35
|
+
### Standard tools are NEVER permitted for:
|
|
36
|
+
|
|
37
|
+
- **Code files** — TypeScript, JavaScript, Python, Go, Rust, etc. Always use Serena's symbolic or file/line tools.
|
|
38
|
+
- **File or directory exploration of any kind**, regardless of file type. This includes:
|
|
39
|
+
- Listing directories → use `mcp__serena__list_dir`, **never** `ls` / `tree` / `find -type d`
|
|
40
|
+
- Finding files by name → use `mcp__serena__find_file`, **never** `find -name` / `ls | grep`
|
|
41
|
+
- Searching file contents → use `mcp__serena__search_for_pattern` or the `Grep` tool, **never** `grep` / `rg` / `ag` invoked through `bash`
|
|
42
|
+
- Reading file contents for inspection → use `mcp__serena__get_symbols_overview` (code) or `Read` (markdown/config), **never** `cat` / `head` / `tail`
|
|
43
|
+
- Editing via shell → **never** `sed` / `awk` / `echo >>`
|
|
44
|
+
|
|
45
|
+
The rule of thumb: **the shell is for running programs, not for inspecting or modifying files.** Even on a markdown file, do not `cat README.md` — use `Read`. Do not `grep -r foo .docs/` — use `mcp__serena__search_for_pattern` or the `Grep` tool.
|
|
46
|
+
|
|
47
|
+
### Common anti-patterns and their fixes
|
|
48
|
+
|
|
49
|
+
These are real mistakes AI agents make on this codebase. Do not repeat them.
|
|
50
|
+
|
|
51
|
+
#### ❌ Anti-pattern: `sed` to flip task-file checkboxes
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# WRONG — never do this
|
|
55
|
+
sed -i '' 's/- \[ \] Launch Puppeteer/- [x] Launch Puppeteer/; s/- \[ \] Navigate and screenshot/- [x] Navigate and screenshot/' .docs/tasks/051-ux-conversion-audit.md
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
This pattern shows up most often when marking multiple steps complete in a task file. It triggers an approval prompt every time, is fragile against whitespace or escaping, and silently corrupts files when a regex backfires.
|
|
59
|
+
|
|
60
|
+
✅ **Correct**: call the `Edit` tool once per checkbox (or use `replace_all: true` if every `- [ ]` in the file should become `- [x]`):
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
|
|
64
|
+
old_string="- [ ] Launch Puppeteer",
|
|
65
|
+
new_string="- [x] Launch Puppeteer")
|
|
66
|
+
Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
|
|
67
|
+
old_string="- [ ] Navigate and screenshot each marketing",
|
|
68
|
+
new_string="- [x] Navigate and screenshot each marketing")
|
|
69
|
+
# ...one Edit call per checkbox
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Yes, even if there are ten checkboxes. Ten `Edit` calls is correct. One `sed` is wrong.
|
|
73
|
+
|
|
74
|
+
#### ❌ Anti-pattern: `cat` to check what's in a file before editing
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
# WRONG
|
|
78
|
+
cat .docs/tasks/051-ux-conversion-audit.md
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
✅ **Correct**: `Read` tool. Always.
|
|
82
|
+
|
|
83
|
+
#### ❌ Anti-pattern: `ls` to see what's in a directory
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
# WRONG
|
|
87
|
+
ls .docs/uat/screenshots/
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
✅ **Correct**: `mcp__serena__list_dir(relative_path=".docs/uat/screenshots/")`
|
|
91
|
+
|
|
92
|
+
#### ❌ Anti-pattern: `grep -r` to find a string across files
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
# WRONG
|
|
96
|
+
grep -r "pending-uat" .
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
✅ **Correct**: the `Grep` tool, or `mcp__serena__search_for_pattern`.
|
|
100
|
+
|
|
101
|
+
#### ❌ Anti-pattern: `echo "new content" >> file.md` to append to a file
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# WRONG
|
|
105
|
+
echo "## New Section" >> README.md
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
✅ **Correct**: `Read` the file first to see the current end, then `Edit` to append (or `Write` if creating fresh).
|
|
109
|
+
|
|
110
|
+
**See also**: [`command-anti-patterns.md`](./command-anti-patterns.md) — shell hygiene, scratch-dir rules, and the /tackle-vs-UAT verification split.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Serena (Code Exploration & Editing)
|
|
115
|
+
|
|
116
|
+
Serena provides two editing approaches:
|
|
117
|
+
1. **Symbolic** — LSP-powered, refactoring-safe (entire functions/classes)
|
|
118
|
+
2. **File/line-based** — Precise line-range and regex edits (within functions)
|
|
119
|
+
|
|
120
|
+
### Tools
|
|
121
|
+
|
|
122
|
+
**Exploration:**
|
|
123
|
+
|
|
124
|
+
| Tool | Purpose | Key Params |
|
|
125
|
+
|------|---------|------------|
|
|
126
|
+
| `get_symbols_overview` | File structure overview | `relative_path`, `depth` (0=top-level) |
|
|
127
|
+
| `find_symbol` | Find symbols by name | `name_path_pattern`, `include_body`, `depth`, `substring_matching` |
|
|
128
|
+
| `find_referencing_symbols` | Find all callers/references | `name_path`, `relative_path` (file, not dir) |
|
|
129
|
+
| `search_for_pattern` | Regex search across files | `substring_pattern`, `relative_path`, `paths_include_glob` |
|
|
130
|
+
| `list_dir` | List directory contents | `relative_path`, `recursive` |
|
|
131
|
+
| `find_file` | Find files by name/mask | `file_mask`, `relative_path` |
|
|
132
|
+
|
|
133
|
+
**Symbolic editing** (use when replacing entire symbols):
|
|
134
|
+
|
|
135
|
+
| Tool | Purpose | Key Params |
|
|
136
|
+
|------|---------|------------|
|
|
137
|
+
| `replace_symbol_body` | Replace function/class body | `name_path`, `relative_path`, `body` (includes signature, NOT docstring) |
|
|
138
|
+
| `insert_after_symbol` | Add code after a symbol | `name_path`, `relative_path`, `body` |
|
|
139
|
+
| `insert_before_symbol` | Add code before a symbol | `name_path`, `relative_path`, `body` |
|
|
140
|
+
| `rename_symbol` | Rename across codebase | `name_path`, `relative_path`, `new_name` |
|
|
141
|
+
|
|
142
|
+
**File/line editing** (use for precise edits within symbols):
|
|
143
|
+
|
|
144
|
+
| Tool | Purpose | Key Params |
|
|
145
|
+
|------|---------|------------|
|
|
146
|
+
| `replace_content` | Literal or regex replacement | `relative_path`, `mode` (literal/regex), `needle`, `repl` |
|
|
147
|
+
| `replace_lines` | Replace line range | `relative_path`, `start_line`, `end_line`, `content` (0-based) |
|
|
148
|
+
| `delete_lines` | Delete line range | `relative_path`, `start_line`, `end_line` (0-based) |
|
|
149
|
+
| `insert_at_line` | Insert at line number | `relative_path`, `line`, `content` (0-based) |
|
|
150
|
+
|
|
151
|
+
### Name Path Patterns
|
|
152
|
+
|
|
153
|
+
- `"method"` — matches any symbol named "method"
|
|
154
|
+
- `"MyClass/method"` — matches method in MyClass (relative)
|
|
155
|
+
- `"/MyClass/method"` — exact match (absolute)
|
|
156
|
+
- `"MyClass/method[0]"` — specific overload
|
|
157
|
+
|
|
158
|
+
### Workflow
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
1. get_symbols_overview → 2. find_symbol → 3. Edit → 4. find_referencing_symbols
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Choosing Edit Mode
|
|
165
|
+
|
|
166
|
+
| Scenario | Use |
|
|
167
|
+
|----------|-----|
|
|
168
|
+
| Replace entire function/method/class | Symbolic: `replace_symbol_body` |
|
|
169
|
+
| Add new method to class | Symbolic: `insert_after_symbol` |
|
|
170
|
+
| Rename across codebase | Symbolic: `rename_symbol` |
|
|
171
|
+
| Edit few lines within large function | File/line: `replace_content` or `replace_lines` |
|
|
172
|
+
| Regex-based replacement | File/line: `replace_content` with `mode="regex"` |
|
|
173
|
+
| Edit doesn't align with symbol boundaries | File/line: `replace_lines` |
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Context7 (Library Documentation)
|
|
178
|
+
|
|
179
|
+
Two-step workflow — resolve the library ID, then query docs.
|
|
180
|
+
|
|
181
|
+
### Step 1: Resolve Library ID
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
mcp__context7__resolve-library-id(libraryName="sqlalchemy")
|
|
185
|
+
# Returns: "/sqlalchemy/sqlalchemy"
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Skip only if user provides an explicit `/org/project` ID.
|
|
189
|
+
|
|
190
|
+
### Step 2: Query Documentation
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
mcp__context7__query-docs(
|
|
194
|
+
libraryId="/sqlalchemy/sqlalchemy",
|
|
195
|
+
query="async session management"
|
|
196
|
+
)
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
If results are insufficient, refine the query with more specific terms.
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## Brave Search (Web Research)
|
|
204
|
+
|
|
205
|
+
### Rate Limit: 50 requests per second
|
|
206
|
+
|
|
207
|
+
- Up to 50 requests per second are supported — parallel searches are allowed
|
|
208
|
+
- On 429 errors, back off briefly and retry (max 3 times)
|
|
209
|
+
|
|
210
|
+
### Usage
|
|
211
|
+
|
|
212
|
+
```python
|
|
213
|
+
mcp__brave-search__brave_web_search(
|
|
214
|
+
query="FastAPI dependency injection best practices 2025",
|
|
215
|
+
count=10
|
|
216
|
+
)
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Use for general research, best practices, troubleshooting, news. Do NOT use for library documentation (use Context7).
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Playwright (Browser Automation)
|
|
224
|
+
|
|
225
|
+
### Tools
|
|
226
|
+
|
|
227
|
+
| Tool | Purpose |
|
|
228
|
+
|------|---------|
|
|
229
|
+
| `browser_navigate` | Navigate to a URL |
|
|
230
|
+
| `browser_take_screenshot` | Screenshot current page |
|
|
231
|
+
| `browser_snapshot` | Get accessibility tree (use to get element `ref` IDs before clicking/typing) |
|
|
232
|
+
| `browser_click` | Click element by `ref` ID from snapshot |
|
|
233
|
+
| `browser_type` | Type into an input field by `ref` ID |
|
|
234
|
+
| `browser_evaluate` | Execute JavaScript in browser |
|
|
235
|
+
| `browser_select_option` | Select dropdown option by `ref` ID |
|
|
236
|
+
| `browser_hover` | Hover over element by `ref` ID |
|
|
237
|
+
| `browser_close` | Close the browser |
|
|
238
|
+
|
|
239
|
+
### Workflow
|
|
240
|
+
|
|
241
|
+
1. **No explicit launch step** — the browser starts automatically on the first tool call.
|
|
242
|
+
2. **Accessibility-tree first** — always call `browser_snapshot` to get the current page structure and element `ref` IDs before interacting. Pass the `ref` to `browser_click`, `browser_type`, etc.
|
|
243
|
+
3. Use `browser_take_screenshot` for visual verification after navigation or interaction.
|
|
244
|
+
|
|
245
|
+
Use for visual verification, form interaction, and browser-rendered content. Do NOT use for static content fetching or library docs.
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## Onboarding & Memory
|
|
250
|
+
|
|
251
|
+
Always run onboarding check when starting work:
|
|
252
|
+
|
|
253
|
+
```python
|
|
254
|
+
mcp__serena__check_onboarding_performed()
|
|
255
|
+
# If not performed:
|
|
256
|
+
mcp__serena__onboarding()
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
### Memory Tools
|
|
260
|
+
|
|
261
|
+
| Tool | Purpose | Key Params |
|
|
262
|
+
|------|---------|------------|
|
|
263
|
+
| `list_memories` | List available memories | `topic` (optional filter, e.g. `"auth"`) |
|
|
264
|
+
| `read_memory` | Read a memory's contents | `memory_name` |
|
|
265
|
+
| `write_memory` | Create a new memory (markdown) | `memory_name`, `content`, `max_chars` (optional) |
|
|
266
|
+
| `edit_memory` | Update existing memory in-place | `memory_name`, `needle`, `repl`, `mode` (`literal` or `regex`), `allow_multiple_occurrences` |
|
|
267
|
+
| `rename_memory` | Rename or move a memory | `old_name`, `new_name` |
|
|
268
|
+
| `delete_memory` | Delete a memory (user permission required) | `memory_name` |
|
|
269
|
+
|
|
270
|
+
### Memory Naming & Organization
|
|
271
|
+
|
|
272
|
+
Use `/` separators to create topic hierarchies:
|
|
273
|
+
|
|
274
|
+
```
|
|
275
|
+
modules/frontend → .serena/memories/modules/frontend.md
|
|
276
|
+
auth/login/logic → .serena/memories/auth/login/logic.md
|
|
277
|
+
global/java/style_guide → shared across all projects
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
- **Project memories**: Stored in `.serena/memories/` within the project
|
|
281
|
+
- **Global memories**: Use `global/` prefix — shared across all projects (only when explicitly instructed)
|
|
282
|
+
- **Topic filtering**: `list_memories(topic="auth")` returns only memories under that topic
|
|
283
|
+
|
|
284
|
+
### When to Write Memories
|
|
285
|
+
|
|
286
|
+
Write memories to persist **non-obvious project knowledge** useful for future tasks:
|
|
287
|
+
|
|
288
|
+
- Architecture decisions and their rationale
|
|
289
|
+
- Integration patterns between modules
|
|
290
|
+
- Naming conventions and project-specific terminology
|
|
291
|
+
- Known gotchas, workarounds, and edge cases
|
|
292
|
+
- Configuration requirements that aren't self-documenting
|
|
293
|
+
|
|
294
|
+
**Do NOT write memories for**:
|
|
295
|
+
- Information already in code comments or docs
|
|
296
|
+
- Temporary task state or debugging notes
|
|
297
|
+
- Easily re-derivable facts (file paths, import lists)
|
|
298
|
+
|
|
299
|
+
### Memory Workflow
|
|
300
|
+
|
|
301
|
+
```
|
|
302
|
+
1. list_memories → discover what exists (filter by topic if needed)
|
|
303
|
+
2. read_memory → check if relevant memory already covers this
|
|
304
|
+
3. write_memory → create new, OR edit_memory → update existing
|
|
305
|
+
4. After implementation → update memories that reference changed code
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Best Practices
|
|
309
|
+
|
|
310
|
+
- **Check before writing**: Always `list_memories` then `read_memory` to avoid duplicates
|
|
311
|
+
- **Edit over rewrite**: Use `edit_memory` (literal or regex mode) for targeted updates instead of rewriting entire memories
|
|
312
|
+
- **Keep memories focused**: One topic per memory — split broad memories into topic-specific ones
|
|
313
|
+
- **Update after changes**: When code changes affect documented patterns, update the relevant memories
|
|
314
|
+
- **Meaningful names**: Use descriptive hierarchical names (`api/auth/jwt-flow` not `memory1`)
|
|
315
|
+
- **Review post-onboarding**: After Serena onboarding, review generated memories and refine them
|
|
316
|
+
|
|
317
|
+
---
|
|
318
|
+
|
|
319
|
+
## Quick Reference: Which Tool for What
|
|
320
|
+
|
|
321
|
+
| Task | MUST Use | NEVER Use |
|
|
322
|
+
|------|----------|-----------|
|
|
323
|
+
| Explore code structure | Serena `get_symbols_overview` | `Read` on code files, `cat` |
|
|
324
|
+
| Find function/class | Serena `find_symbol` | `Grep` on code files, `bash grep` |
|
|
325
|
+
| Edit code | Serena symbolic or file/line tools | Standard `Edit` on code files, `sed` |
|
|
326
|
+
| Rename symbol | Serena `rename_symbol` | Manual find-and-replace |
|
|
327
|
+
| Search file contents | Serena `search_for_pattern` or `Grep` tool | `bash grep` / `rg` / `ag` |
|
|
328
|
+
| List a directory | Serena `list_dir` | `ls`, `tree`, `find -type d` |
|
|
329
|
+
| Find files by name | Serena `find_file` or `Glob` tool | `find -name`, `ls \| grep` |
|
|
330
|
+
| Read markdown content | Standard `Read` | `cat`, `head`, `tail` |
|
|
331
|
+
| Edit markdown content | Standard `Edit` / `Write` | `sed`, `awk`, `echo >>` |
|
|
332
|
+
| Edit config files (JSON, YAML, .env) | Standard `Read`/`Edit`/`Write` | `sed`, Serena symbolic tools |
|
|
333
|
+
| Library docs | Context7 | `WebSearch` / `WebFetch` |
|
|
334
|
+
| General research | Brave Search (up to 50 req/sec, parallel OK) | WebSearch |
|
|
335
|
+
| Browser interaction | Playwright | `WebFetch` for rendered content |
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Task File Specification
|
|
2
|
+
|
|
3
|
+
Task files in `.docs/tasks/` are structured outlines designed for execution by `/tackle`.
|
|
4
|
+
|
|
5
|
+
## Naming Convention
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
<NNN>-<short-description>.md
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
- **NNN**: Zero-padded sequential integer (check `.docs/tasks/` and `completed/` to find the next number)
|
|
12
|
+
- **short-description**: Lowercase, hyphen-separated slug (2-4 words)
|
|
13
|
+
|
|
14
|
+
Examples: `001-basic-infrastructure.md`, `004-application-tracker.md`, `008-find-jobs.md`
|
|
15
|
+
|
|
16
|
+
## Required Structure
|
|
17
|
+
|
|
18
|
+
```markdown
|
|
19
|
+
# NNN — Task Title
|
|
20
|
+
|
|
21
|
+
## Objective
|
|
22
|
+
|
|
23
|
+
One-sentence description of what this task accomplishes.
|
|
24
|
+
|
|
25
|
+
## Approach
|
|
26
|
+
|
|
27
|
+
Brief summary of the technical approach or key decisions (1-3 sentences).
|
|
28
|
+
|
|
29
|
+
## Prerequisites
|
|
30
|
+
|
|
31
|
+
- [ ] Any setup or dependencies that must exist before starting
|
|
32
|
+
- [ ] Reference other tasks by number: "Task 001 (Infrastructure) completed"
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Steps
|
|
37
|
+
|
|
38
|
+
### 1. Section Name <!-- agent: general-purpose -->
|
|
39
|
+
|
|
40
|
+
- [ ] Step description with enough detail for an agent to implement
|
|
41
|
+
- [ ] Another step — include file paths, component names, or API routes when known
|
|
42
|
+
- Sub-detail or acceptance criteria (plain text indent, not a checkbox)
|
|
43
|
+
|
|
44
|
+
### 2. Another Section <!-- agent: general-purpose -->
|
|
45
|
+
|
|
46
|
+
- [ ] More steps grouped by logical area
|
|
47
|
+
|
|
48
|
+
### N. Verification <!-- agent: general-purpose -->
|
|
49
|
+
|
|
50
|
+
- [ ] Verify TypeScript compiles / tests pass / app runs
|
|
51
|
+
- [ ] Verify key user flows work end-to-end
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Rules
|
|
55
|
+
|
|
56
|
+
- Every actionable item uses `- [ ]` checkbox syntax
|
|
57
|
+
- Number step sections sequentially: `### 1.`, `### 2.`, etc.
|
|
58
|
+
- **Every step section MUST have an agent type annotation**: `<!-- agent: TYPE -->` on the `###` header line
|
|
59
|
+
- Valid types: `general-purpose`, `Explore`, `Plan`
|
|
60
|
+
- Group steps by logical area (e.g., "Schema Update", "API Routes", "UI Components")
|
|
61
|
+
- Steps should be specific enough for `/tackle` to execute without ambiguity — the task file IS the plan
|
|
62
|
+
- Include file paths, function names, or route patterns when known
|
|
63
|
+
- End with a verification section to confirm the work is complete
|
|
64
|
+
- Use `---` separator between Prerequisites and Steps
|
|
65
|
+
- Keep the objective to one sentence
|
|
66
|
+
- Keep the approach to 1-3 sentences
|
|
67
|
+
|
|
68
|
+
## Lifecycle
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
.docs/tasks/ → .docs/tasks/completed/
|
|
72
|
+
(/tackle + /uat-walk all pass)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
When a task reaches `completed/`, a UAT link is appended:
|
|
76
|
+
```markdown
|
|
77
|
+
---
|
|
78
|
+
**UAT**: [`.docs/uat/completed/NNN-slug.uat.md`](../uat/completed/NNN-slug.uat.md)
|
|
79
|
+
```
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Type-Checking & Linting Config Templates
|
|
2
|
+
|
|
3
|
+
Best-practice templates synthesized from analysis of all configs across ~/Repositories. Each template includes inline annotations explaining every non-obvious decision.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Templates
|
|
8
|
+
|
|
9
|
+
| File | When to use |
|
|
10
|
+
|------|-------------|
|
|
11
|
+
| `tsconfig/tsconfig.node-esm.jsonc` | Node.js service, CLI, or MCP server using native ESM |
|
|
12
|
+
| `tsconfig/tsconfig.vite-root.json` | Vite project root (solution coordinator — no compilation) |
|
|
13
|
+
| `tsconfig/tsconfig.app.jsonc` | Vite + React app (browser code) |
|
|
14
|
+
| `tsconfig/tsconfig.node.jsonc` | Vite config file compilation (`vite.config.ts`) |
|
|
15
|
+
| `tsconfig/tsconfig.lib.jsonc` | React/TS library that emits `.d.ts` for npm |
|
|
16
|
+
| `python/pyproject.toml` | Python project: mypy + basedpyright + ruff + pytest + coverage |
|
|
17
|
+
| `python/mypy.ini` | Standalone mypy config (use when `pyproject.toml` is owned by another tool) |
|
|
18
|
+
| `python/pyrightconfig.json` | Pyright / basedpyright standalone config |
|
|
19
|
+
| `eslint/eslint.config.ts` | ESLint flat config for React + TypeScript |
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Key Best Practices by Config Type
|
|
24
|
+
|
|
25
|
+
### TypeScript (`tsconfig.json`)
|
|
26
|
+
|
|
27
|
+
**Module system — pick the right pair:**
|
|
28
|
+
| Project type | `module` | `moduleResolution` |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| Node.js native ESM | `NodeNext` | `NodeNext` |
|
|
31
|
+
| Vite / bundled app | `ESNext` | `bundler` |
|
|
32
|
+
| Next.js | `ESNext` | `bundler` |
|
|
33
|
+
|
|
34
|
+
Never mix `module: ESNext` with `moduleResolution: node` — they are semantically incompatible.
|
|
35
|
+
|
|
36
|
+
**Strictness — go beyond `strict: true`:**
|
|
37
|
+
```jsonc
|
|
38
|
+
"strict": true, // enables 8 base flags
|
|
39
|
+
"noUncheckedIndexedAccess": true, // highest-value add-on; catches array/dict access bugs
|
|
40
|
+
"noImplicitReturns": true,
|
|
41
|
+
"noFallthroughCasesInSwitch": true,
|
|
42
|
+
"noImplicitOverride": true,
|
|
43
|
+
"noUnusedLocals": true,
|
|
44
|
+
"noUnusedParameters": true,
|
|
45
|
+
"verbatimModuleSyntax": true // TS 5.0+; prevents silent import bugs
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Vite projects — always use the three-file split:**
|
|
49
|
+
- Root `tsconfig.json` — `"files": []` + `"references"` only (no compilation of its own)
|
|
50
|
+
- `tsconfig.app.json` — browser libs, `noEmit: true`, `moduleResolution: bundler`
|
|
51
|
+
- `tsconfig.node.json` — Node libs, `noEmit: true`, covers only `vite.config.ts`
|
|
52
|
+
|
|
53
|
+
**Anti-patterns observed in the wild:**
|
|
54
|
+
- `module: ESNext` + `moduleResolution: node` — broken module resolution
|
|
55
|
+
- `target: es5` in 2024+ projects — unnecessary transpilation overhead
|
|
56
|
+
- `jsx: "react"` in modern code — use `"react-jsx"` (React 17+ automatic transform)
|
|
57
|
+
- `allowJs: true` without `checkJs: true` — JS files silently bypass type checking
|
|
58
|
+
- Keeping the tsc-generated comment template — adds noise, hides real config
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
### Python type checking (`pyproject.toml` / `mypy.ini`)
|
|
63
|
+
|
|
64
|
+
**mypy:**
|
|
65
|
+
- Always use `strict = true` — never approximate it with manual flag enumeration
|
|
66
|
+
- Use `[[tool.mypy.overrides]]` per-module instead of global `ignore_missing_imports = true`
|
|
67
|
+
- Never use `ignore_errors = true` on a whole module — it silences real bugs; use `ignore_missing_imports = true` only
|
|
68
|
+
- Always set `files` or `exclude` to prevent crawling `.venv`, `dist`, etc.
|
|
69
|
+
- Enable `pydantic.mypy` plugin in any Pydantic project
|
|
70
|
+
- Enable `sqlalchemy.ext.mypy.plugin` if using SQLAlchemy ORM
|
|
71
|
+
|
|
72
|
+
**ruff (replaces flake8 / isort / black):**
|
|
73
|
+
Minimum rule set: `E, W, F, I, B, UP`
|
|
74
|
+
Recommended rule set: `E, W, F, I, N, UP, B, C4, SIM, RUF`
|
|
75
|
+
Add `C90` (mccabe) for complex control-flow codebases (agent loops, etc.)
|
|
76
|
+
|
|
77
|
+
**basedpyright companion pattern:**
|
|
78
|
+
Run basedpyright alongside mypy with `typeCheckingMode = "off"` — opt in only to rules mypy currently lacks (notably `reportTypedDictNotRequiredAccess` for mypy gap #9408). Prevents double-reporting.
|
|
79
|
+
|
|
80
|
+
**Anti-patterns observed in the wild:**
|
|
81
|
+
- `ignore_errors = true` on internal modules — silences real type errors, not just stub gaps
|
|
82
|
+
- `cryptwiz_py`: manually approximating strict mode without `strict = true`, leaving gaps
|
|
83
|
+
- Missing `[tool.ruff.lint.isort]` `known-first-party` — isort can't distinguish first-party vs third-party without it
|
|
84
|
+
- `sales-agent`: no pydantic.mypy plugin despite heavy Pydantic usage
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
### ESLint (flat config)
|
|
89
|
+
|
|
90
|
+
- Use `tseslint.configs.strictTypeChecked` + `parserOptions.projectService: true` for full type-aware linting
|
|
91
|
+
- Never downgrade errors to `"warn"` — either fix or disable with a comment
|
|
92
|
+
- Scope globals tightly: `globals.browser` only in browser files, `globals.node` only in Node/config files
|
|
93
|
+
- Use a separate config block for test files
|
|
94
|
+
- Eliminate `FlatCompat` — all major plugins now ship native flat config support
|
|
95
|
+
- Let the TypeScript parser handle `ecmaVersion`; do not hard-code it
|
|
96
|
+
|
|
97
|
+
**Anti-patterns observed in the wild:**
|
|
98
|
+
- `portfolio_v2`: missing `parserOptions.projectService` — all type-aware lint rules silently disabled
|
|
99
|
+
- `openemr`: `FlatCompat` bridge for jest — use `jest.configs['flat/recommended']` instead
|
|
100
|
+
- `openemr`: `no-undef`, `no-unused-vars`, `no-redeclare` set to `"warn"` — silent tech debt
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
### pyrightconfig.json
|
|
105
|
+
|
|
106
|
+
- Always set `typeCheckingMode` explicitly — the default is `"off"`, meaning no type checking
|
|
107
|
+
- `reportMissingImports` should always be `"error"`
|
|
108
|
+
- `"standard"` is a safe project-wide floor; use per-file suppressions for legacy code
|
|
109
|
+
|
|
110
|
+
**Anti-patterns observed in the wild:**
|
|
111
|
+
- Neither `openemr` nor `cryptwiz_py` set `typeCheckingMode` — Pyright defaulted to `"off"` and did nothing
|
|
112
|
+
- `reportMissingImports: "warning"` — broken imports should always be errors
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
// eslint.config.ts
|
|
2
|
+
// Use for: React + TypeScript projects using ESLint flat config (v9+)
|
|
3
|
+
// Key: uses `strictTypeChecked` + `parserOptions.projectService` for full type-aware linting.
|
|
4
|
+
// Replace plugin imports to match your actual installed packages.
|
|
5
|
+
|
|
6
|
+
import js from '@eslint/js'
|
|
7
|
+
import globals from 'globals'
|
|
8
|
+
import reactHooks from 'eslint-plugin-react-hooks'
|
|
9
|
+
import reactRefresh from 'eslint-plugin-react-refresh'
|
|
10
|
+
import tseslint from 'typescript-eslint'
|
|
11
|
+
import { defineConfig, globalIgnores } from 'eslint/config'
|
|
12
|
+
// If using vitest (native flat config, no FlatCompat needed):
|
|
13
|
+
// import vitest from 'eslint-plugin-vitest'
|
|
14
|
+
// If using jest (v29+ ships native flat config, no FlatCompat needed):
|
|
15
|
+
// import jest from 'eslint-plugin-jest'
|
|
16
|
+
|
|
17
|
+
export default defineConfig([
|
|
18
|
+
// --- Global ignores (replaces .eslintignore) ---
|
|
19
|
+
globalIgnores([
|
|
20
|
+
'dist',
|
|
21
|
+
'build',
|
|
22
|
+
'coverage',
|
|
23
|
+
'.vite',
|
|
24
|
+
'**/*.gen.ts', // generated files
|
|
25
|
+
'**/*.d.ts', // declaration files
|
|
26
|
+
]),
|
|
27
|
+
|
|
28
|
+
// --- Source files: TypeScript + React ---
|
|
29
|
+
{
|
|
30
|
+
files: ['src/**/*.{ts,tsx}'],
|
|
31
|
+
extends: [
|
|
32
|
+
js.configs.recommended,
|
|
33
|
+
// strictTypeChecked = recommended + strict + ALL type-aware lint rules.
|
|
34
|
+
// Requires parserOptions.projectService below — without it, type-aware
|
|
35
|
+
// rules are silently disabled. This was the primary gap in portfolio_v2.
|
|
36
|
+
tseslint.configs.strictTypeChecked,
|
|
37
|
+
// stylisticTypeChecked adds formatting-adjacent TS rules (optional)
|
|
38
|
+
tseslint.configs.stylisticTypeChecked,
|
|
39
|
+
reactHooks.configs['recommended-latest'],
|
|
40
|
+
reactRefresh.configs.vite,
|
|
41
|
+
],
|
|
42
|
+
languageOptions: {
|
|
43
|
+
globals: globals.browser,
|
|
44
|
+
parserOptions: {
|
|
45
|
+
// projectService: true → auto-discovers tsconfig.json per file.
|
|
46
|
+
// More efficient than `project: ['./tsconfig.app.json']`.
|
|
47
|
+
// CRITICAL: without this, all type-aware rules are disabled.
|
|
48
|
+
projectService: true,
|
|
49
|
+
tsconfigRootDir: import.meta.dirname,
|
|
50
|
+
},
|
|
51
|
+
},
|
|
52
|
+
rules: {
|
|
53
|
+
// RULE: Never downgrade to "warn" — fix or disable with a comment.
|
|
54
|
+
// Warnings are silent tech debt that accumulate and never get fixed.
|
|
55
|
+
|
|
56
|
+
// Prefer type imports for better tree-shaking / circular dep safety
|
|
57
|
+
'@typescript-eslint/consistent-type-imports': [
|
|
58
|
+
'error',
|
|
59
|
+
{ prefer: 'type-imports', fixStyle: 'inline-type-imports' },
|
|
60
|
+
],
|
|
61
|
+
|
|
62
|
+
// void-returning arrow callbacks are fine in event handlers
|
|
63
|
+
'@typescript-eslint/no-misused-promises': [
|
|
64
|
+
'error',
|
|
65
|
+
{ checksVoidReturn: { attributes: false } },
|
|
66
|
+
],
|
|
67
|
+
|
|
68
|
+
// Allow `_` prefix to suppress unused variable lint
|
|
69
|
+
'@typescript-eslint/no-unused-vars': [
|
|
70
|
+
'error',
|
|
71
|
+
{ argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
|
|
72
|
+
],
|
|
73
|
+
},
|
|
74
|
+
},
|
|
75
|
+
|
|
76
|
+
// --- Test files (relaxed rules) ---
|
|
77
|
+
{
|
|
78
|
+
files: ['**/*.{spec,test}.{ts,tsx}', '**/__tests__/**/*.{ts,tsx}'],
|
|
79
|
+
// Uncomment whichever test framework you use:
|
|
80
|
+
// extends: [vitest.configs.recommended],
|
|
81
|
+
// extends: [jest.configs['flat/recommended']], // no FlatCompat needed in jest v29+
|
|
82
|
+
languageOptions: {
|
|
83
|
+
globals: {
|
|
84
|
+
...globals.node, // process, __dirname, etc.
|
|
85
|
+
},
|
|
86
|
+
},
|
|
87
|
+
rules: {
|
|
88
|
+
// Test files legitimately use `any` for mocks and non-null assertions
|
|
89
|
+
'@typescript-eslint/no-explicit-any': 'off',
|
|
90
|
+
'@typescript-eslint/no-non-null-assertion': 'off',
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
|
|
94
|
+
// --- Node / config scripts ---
|
|
95
|
+
{
|
|
96
|
+
files: ['*.config.{js,ts,mjs,mts}', 'scripts/**/*.{js,ts}'],
|
|
97
|
+
languageOptions: {
|
|
98
|
+
globals: globals.node,
|
|
99
|
+
},
|
|
100
|
+
rules: {
|
|
101
|
+
// Config files often use require() or dynamic imports
|
|
102
|
+
'@typescript-eslint/no-require-imports': 'off',
|
|
103
|
+
},
|
|
104
|
+
},
|
|
105
|
+
])
|