Skip to content

cspell-config.prompt.md

Latest commit

 

History

History
83 lines (59 loc) · 6.34 KB

cspell-config.prompt.md

File metadata and controls

83 lines (59 loc) · 6.34 KB
Raw
agent agent
description Create or update the project cspell configuration with project words and ignores

Update cspell configuration with project-specific words and ignores

Context

  • 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.
  • cspell supports multiple config formats and file names. The agent must detect which format the project uses rather than assuming any specific one.
  • Projects may also use custom dictionary files (.txt word lists) organized in a dedicated directory. The agent must discover and respect existing dictionary structure.

Required Steps

Step 1: Detect project context

  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).
  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.
  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.

Step 2: Detect cspell configuration

  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.
  2. If multiple config files exist, use the first match and note the others for the user.
  3. If no config file exists, create cspell.json with a minimal scaffold (version, language, ignorePaths, words).
  4. Record the detected config path and format (JSON, YAML, or JS module) for subsequent steps.

Step 3: Detect custom dictionaries

  1. Search for a .cspell/ directory or any path referenced in the config's dictionaryDefinitions field.
  2. Catalog existing custom dictionary text files (.txt word lists) and note their names, paths, and apparent categories.
  3. Check the dictionaries field for enabled built-in dictionaries (e.g., k8s, docker, rust, aws, terraform, python, csharp).
  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.

Step 4: Run initial spell check

  1. Run cspell using the project command discovered in Step 1, or fall back to direct invocation (e.g., npx cspell "**/*", cspell "**/*").
  2. Collect unknown words from the output, excluding paths already covered by ignorePaths.

Step 5: Curate and categorize tokens

  1. Group unknown tokens into categories: project-specific terms, acronyms, technology names, environment variables, proper nouns, and potential typos.
  2. Filter out obvious garbage using these heuristics:
    • Hex strings of 16+ characters ([a-f0-9]{16,})
    • Base64 looking strings ([A-Za-z0-9+/]{20,}={0,2})
    • Tokens appearing only in lockfiles, minified assets, or build output
  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.
  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.

Step 6: Update configuration and dictionaries

  1. Add curated tokens to the words array or the appropriate custom dictionary file. Preserve original casing and avoid introducing duplicates.
  2. Sort the words array alphabetically (case-insensitive sort, preserve original case).
  3. Sort custom dictionary text files alphabetically with one word per line if they follow that convention.
  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.
  5. Preserve the existing config format and style conventions (indentation, trailing commas, module export structure).

Step 7: Validate and report

  1. Re-run cspell using the same command from Step 4.
  2. Report the final counts: files checked, issues found, files with issues.
  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).
  4. List any typos identified in Step 5 that should be fixed in source.

Acceptance criteria

  • The cspell configuration includes a comprehensive ignorePaths array that excludes generated and vendored folders.
  • The words array and any custom dictionary files contain the most common project-specific tokens, alphabetized and deduplicated.
  • A final cspell run shows a meaningful reduction from the baseline (target ≥80%, or the agent documents the remaining categories with rationale).

Notes and best practices

  • Preserve original casing for tokens (do not normalize to uppercase or lowercase).
  • Prefer adding tokens for environment variables, infrastructure outputs, and technology names rather than silencing real typos.
  • When in doubt about a token that appears only once in generated files, prefer ignoring the generated file path instead of adding the token.
  • 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.
  • When the project uses a JS/CJS/MJS config format, preserve the module export structure and do not convert to JSON.
  • 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).

Proceed with the Required Steps to detect, update, and validate the cspell configuration.