|
| 1 | +--- |
| 2 | +agent: "agent" |
| 3 | +description: "Creates or updates the project cspell configuration with project-specific words and ignores" |
| 4 | +--- |
| 5 | + |
| 6 | +# Update cspell configuration with project-specific words and ignores |
| 7 | + |
| 8 | +## Context |
| 9 | + |
| 10 | +* Goal: Add commonly used project-specific words to the cspell configuration, alphabetize the words list, and add useful `ignorePaths` aligned with the project's ignore files. |
| 11 | +* cspell supports multiple config formats and file names. The agent must detect which format the project uses rather than assuming any specific one. |
| 12 | +* Projects may also use custom dictionary files (`.txt` word lists) organized in a dedicated directory. The agent must discover and respect existing dictionary structure. |
| 13 | + |
| 14 | +## Required Steps |
| 15 | + |
| 16 | +### Step 1: Detect project context |
| 17 | + |
| 18 | +1. Identify the project's primary language and package manager by inspecting files at the workspace root (e.g., `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.csproj`, `pom.xml`, `Gemfile`). |
| 19 | +2. Determine how cspell is installed or available. Check for: a project dependency (npm, pip, or equivalent), a global install (`cspell --version`), or `npx`/`npx`-equivalent availability. If cspell is not available, ask the user for their preferred installation method. |
| 20 | +3. Check for an existing spell-check script in the project's task runner (e.g., `package.json` scripts, `Makefile` targets, `justfile` recipes, `pyproject.toml` scripts). Use the project command when one exists. |
| 21 | + |
| 22 | +### Step 2: Detect cspell configuration |
| 23 | + |
| 24 | +1. Search the workspace root for any cspell config file using a broad glob pattern (e.g., `cspell*`, `.cspell*`). cspell recognizes many naming variants including dotfiles (`.cspell.json`), plain names (`cspell.json`), JSONC (`cspell.jsonc`), JS modules (`cspell.config.{js,cjs,mjs}`), and YAML (`cspell.config.{yaml,yml}`). Also check `package.json` for a `cspell` configuration key. |
| 25 | +2. If multiple config files exist, use the first match and note the others for the user. |
| 26 | +3. If no config file exists, create `cspell.json` with a minimal scaffold (`version`, `language`, `ignorePaths`, `words`). |
| 27 | +4. Record the detected config path and format (JSON, YAML, or JS module) for subsequent steps. |
| 28 | + |
| 29 | +### Step 3: Detect custom dictionaries |
| 30 | + |
| 31 | +1. Search for a `.cspell/` directory or any path referenced in the config's `dictionaryDefinitions` field. |
| 32 | +2. Catalog existing custom dictionary text files (`.txt` word lists) and note their names, paths, and apparent categories. |
| 33 | +3. Check the `dictionaries` field for enabled built-in dictionaries (e.g., `k8s`, `docker`, `rust`, `aws`, `terraform`, `python`, `csharp`). |
| 34 | +4. When adding new words later, route each token to either the inline `words` array or an existing custom dictionary file based on category fit. If no custom dictionaries exist, add all tokens to the inline `words` array. |
| 35 | + |
| 36 | +### Step 4: Run initial spell check |
| 37 | + |
| 38 | +1. Run cspell using the project command discovered in Step 1, or fall back to direct invocation (e.g., `npx cspell "**/*"`, `cspell "**/*"`). |
| 39 | +2. Collect unknown words from the output, excluding paths already covered by `ignorePaths`. |
| 40 | + |
| 41 | +### Step 5: Curate and categorize tokens |
| 42 | + |
| 43 | +1. Group unknown tokens into categories: project-specific terms, acronyms, technology names, environment variables, proper nouns, and potential typos. |
| 44 | +2. Filter out obvious garbage using these heuristics: |
| 45 | + * Hex strings of 16+ characters (`[a-f0-9]{16,}`) |
| 46 | + * Base64 looking strings (`[A-Za-z0-9+/]{20,}={0,2}`) |
| 47 | + * Tokens appearing only in lockfiles, minified assets, or build output |
| 48 | +3. Identify likely typos that should be fixed in source rather than added to the dictionary (e.g., `recieve` → `receive`). Report these separately for the user to review. <!-- cspell:disable-line --> |
| 49 | +4. For each remaining token, decide placement: inline `words` array for project-specific terms, or the appropriate custom dictionary file when one exists and the token fits its category. |
| 50 | + |
| 51 | +### Step 6: Update configuration and dictionaries |
| 52 | + |
| 53 | +1. Add curated tokens to the `words` array or the appropriate custom dictionary file. Preserve original casing and avoid introducing duplicates. |
| 54 | +2. Sort the `words` array alphabetically (case-insensitive sort, preserve original case). |
| 55 | +3. Sort custom dictionary text files alphabetically with one word per line if they follow that convention. |
| 56 | +4. Add or refine `ignorePaths` entries to align with the project's ignore files (`.gitignore`, `.dockerignore`, etc.), but do not ignore source folders containing meaningful code and documentation. |
| 57 | +5. Preserve the existing config format and style conventions (indentation, trailing commas, module export structure). |
| 58 | + |
| 59 | +### Step 7: Validate and report |
| 60 | + |
| 61 | +1. Re-run cspell using the same command from Step 4. |
| 62 | +2. Report the final counts: files checked, issues found, files with issues. |
| 63 | +3. If the issue count has not meaningfully decreased from baseline (target: ≥80% reduction), provide a short rationale and suggest next actions (add more words, fix typos, or add more ignore paths). |
| 64 | +4. List any typos identified in Step 5 that should be fixed in source. |
| 65 | + |
| 66 | +## Acceptance criteria |
| 67 | + |
| 68 | +* The cspell configuration includes a comprehensive `ignorePaths` array that excludes generated and vendored folders. |
| 69 | +* The `words` array and any custom dictionary files contain the most common project-specific tokens, alphabetized and deduplicated. |
| 70 | +* A final cspell run shows a meaningful reduction from the baseline (target ≥80%, or the agent documents the remaining categories with rationale). |
| 71 | + |
| 72 | +## Notes and best practices |
| 73 | + |
| 74 | +* Preserve original casing for tokens (do not normalize to uppercase or lowercase). |
| 75 | +* Prefer adding tokens for environment variables, infrastructure outputs, and technology names rather than silencing real typos. |
| 76 | +* When in doubt about a token that appears only once in generated files, prefer ignoring the generated file path instead of adding the token. |
| 77 | +* For diacritics and special characters (e.g., `Piña`, `José`, `Müller`, `Straße`, `naïve`, `résumé`, `Zürich`), preserve the original forms but consider adding simplified fallbacks only if tests or files use them. <!-- cspell:disable-line --> |
| 78 | +* When the project uses a JS/CJS/MJS config format, preserve the module export structure and do not convert to JSON. |
| 79 | +* Adapt file-type globs for the spell-check command to the project's languages (e.g., `"**/*.{py,md,yaml,yml}"` for Python projects, `"**/*.{cs,md,json}"` for C# projects). |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +Proceed with the Required Steps to detect, update, and validate the cspell configuration. |
0 commit comments