Glossary from Codebase

What this skill does

Scans a codebase for recurring domain terms and produces a glossary. Sources include exported function names, database table and column names, and noun phrases inside JSDoc / docstring comments.

Inputs

• repo_dir: project root.
• Optional lang: dominant language (ts, py, go, java); auto-detected from extension counts otherwise.
• Optional schema_path: SQL or Prisma schema file to mine for table/column names.

Steps

1. Detect language via find <repo_dir> -name '*.ts' -o -name '*.py' | head -200 | awk -F. '{print $NF}' | sort | uniq -c.
2. Extract identifiers: TS/JS via rg -oN '\bfunction ([A-Za-z][A-Za-z0-9_]+)' --replace '$1'; Python via rg -oN '\bdef ([a-zA-Z_][a-zA-Z0-9_]+)'; Go via rg -oN 'func \(.*\) ([A-Z][a-zA-Z0-9_]+)\('.
3. Split CamelCase / snake_case into tokens: getUserById -> [get, user, by, id]. Use a regex split.
4. Drop stopwords (get, set, is, has, the, to, from, with, for, data, info, value).
5. Tally token frequency across the corpus. Keep tokens occurring >= 5 times.
6. From schema_path, extract CREATE TABLE and column names with rg -oN 'CREATE TABLE\s+(\w+)' -r '$1' and similar for columns.
7. Pull noun phrases from comments: extract /** ... */ and # ... blocks; run a simple POS heuristic — capitalized multi-word phrases inside comments — to find candidate definitions.
8. For each kept token, pick the longest comment phrase containing it as the candidate definition.
9. Sort alphabetically; emit a markdown table: | Term | Definition | Sample location |.
10. Save to docs/glossary.md.

Output

docs/glossary.md with a header note ("Generated from on ") followed by an alphabetical glossary table. Each row's "Sample location" cell links to one file:line where the term appears.

Verification

Open three random rows and grep the codebase for the term; the count must be at least the threshold (5). Manually skim ten definitions for sanity — terms whose definitions read as gibberish should be moved to a "needs review" appendix rather than dropped silently. Re-run after changing the stopword list and confirm the glossary changes monotonically (terms only enter or exit, no shuffling).

Edge cases

• Mostly third-party imports / vendored code: respect .gitignore and exclude node_modules, vendor, dist from the scan.
• Multi-language repo: produce per-language sections rather than mixing namespaces.
• Highly abbreviated codebase (e.g., usrCt, prdId): supplement with a sibling abbreviations table; do not try to expand.
• No comments at all: skip the definition column and emit a "term, sample location" two-column table with a note.