Glyph
Carve meaning into your codebase. Now the graph actually works.
One database. Two lenses. Total codebase awareness.
▸ Glyph ❤️ Fallow — Integration Docs
Glyph integrates Fallow's code quality analysis directly into its SQLite knowledge graph. Run fallow analyses and store results alongside structural data — query everything from one database.
$ glyph scan boottify /path/to/project
# Run all Fallow analyses (dead-code + health + dupes)
$ glyph fallow boottify
# Or run specific analyses
$ glyph fallow boottify dead-code
$ glyph fallow boottify health,dupes
# Combined structural + quality health report
$ glyph health boottify
# Query ingested quality issues
$ glyph issues boottify --kind dead-code
$ glyph issues boottify --kind health --sev critical
glyph health — What You Get
| Section | Source | What it shows |
|---|---|---|
| Fallow Issue Summary | Fallow | Dead-code breakdown (unused files, exports, types, deps) + complexity tiers |
| Largest Files | Glyph | Top 10 files by line count (from scan-time file_metrics) |
| Most Complex Functions | Fallow | CC, cognitive, CRAP scores — sorted worst first |
| Most-Connected Symbols | Glyph | Change impact analysis — which symbols would break the most if changed |
| Unused Exports | Glyph | Orphans detected by edge analysis (no callers, no imports) |
| Stats Footer | Both | Total files, symbols, issues, last scan/fallow run timestamps |
Fallow Schema Tables
| Table | Purpose |
|---|---|
| file_metrics | Per-file line count, symbol count, Fallow analysis timestamps |
| fallow_issues | All ingested issues with severity, complexity metrics, cross-referenced to files and symbols |
$ sqlite3 ~/.glyph/glyph.db "SELECT issue_kind, sub_kind, severity, COUNT(*) FROM fallow_issues GROUP BY 1,2,3 ORDER BY 4 DESC"
Why Glyph
// STRUCTURE_AWARE + QUALITY_AWARE
Zero LLM Cost
Pure tree-sitter AST parsing. No API calls, no tokens, no rate limits. Always free.
Incremental Updates
stat()-based change detection — unchanged files are never read or hashed. A no-op pass over 5,015 files across 3 projects takes 0.28s.
SQLite Knowledge Graph
Indexed lookups, BFS path traversal, multi-project. Not a JSON dump.
❤️ Fallow Integrated
Dead-code detection, cyclomatic complexity, code duplication — all stored alongside structural data.
Multi-Language
TypeScript, Python, Go, Bash. Same query interface across all languages.
AI-Ready
Generate PROJECT_MAP.md for your coding agent. Dramatically reduces find→read→trace loops.
▸ What Changed in v2.0 — Correctness Rewrite
v1's knowledge graph was largely non-functional. Three defects made most of what Glyph advertised return nothing at all. Each was measured against a live 57,121-symbol index before and after the fix. If you ran v1.x, re-index.
| Defect | Measured impact | Status |
|---|---|---|
| Symbol names extracted by slicing a decoded string with tree-sitter's byte offsets — one non-ASCII character shifted every later name | 26,240 of 57,121 symbols (46%) corrupt,
e.g. '\n\n const totalPushed = …' |
Fixed |
Edge resolution hardcoded source_id = None, so no edge had a source |
0 of 18,927 edges — deps,
path and bridges returned nothing on any project, ever |
Fixed |
| Incremental scans deleted a re-parsed file's inbound edges and never rebuilt them | Editing 10 files destroyed 35% of the graph (3,265 → 2,109 edges) | Fixed |
orphans used NOT IN against a subquery containing NULL —
which yields NULL, never true |
Returned zero rows, always | Fixed |
Import extraction looked up a grammar field named clause, which does not exist |
24 import edges across 4,710 files | Fixed |
watch passed an empty root to the scanner |
Silent no-op loop | Fixed |
Performance — v1.2.0 vs v2.0.0, same machine
| Operation | v1.2.0 | v2.0.0 |
|---|---|---|
| Full scan — 3,161 files | 7.79 s | 2.57 s (3.0×) |
| Full scan — 1,576 files | 3.31 s | 0.99 s (3.3×) |
| No-op incremental scan | 0.29 s | 0.17 s |
| Edges extracted (1,576-file repo) | 3,265 | 31,491 |
| Edges resolved to a symbol | 0 | 14,048 |
| Corrupt symbol names | 46% | 0% |
From stat()-based change detection, parallel parsing across processes, cached parsers,
iterative AST walking, up-front id allocation, and GROUP BY joins replacing correlated
subqueries. Accuracy spot-checked against grep: 260 caller files for
withAuth vs grep's 263; 405 vs 401 for the db singleton.
New in v2.0
$ glyph context myproject sendEmail
→ definition + line range + every caller + every callee + file symbols
# Is the index healthy? Catches exactly the failures v1 shipped with
$ glyph doctor
→ malformed names 0 [ok] · dangling targets 0 [ok] · all checks passed
# Re-scan every indexed project — cheap enough to cron
$ glyph refresh
→ 5,015 files across 3 projects in 0.28s
# Files that change often AND are structurally central
$ glyph hotspots myproject
# --json on every query command, for scripting and agents
$ glyph find myproject sendEmail --json
Upgrading from v1.x
$ glyph scan myproject /path/to/repo --full
$ glyph doctor
The v1 database is migrated automatically on first run — project names and paths are
kept, and the old file is backed up to
~/.glyph/glyph.db.v1-backup-<timestamp> first. v1 data is not
salvageable (46% corrupt names, zero edge sources), so a full re-scan is required.
Known limit. Roughly 45–50% of extracted edges resolve to a symbol inside the project; the rest are calls into node_modules/stdlib, which Glyph deliberately does not index. An unresolved edge means "points outside the project", not "not called". Dynamic dispatch is invisible to AST analysis. Use Glyph to find and orient fast — then read the code before you change it.
Available Versions
$ git checkout v2.0.1 | all releases →
$ git clone https://github.com/Daigtas/glyph.git$ cd glyph && ./install.sh$ glyph scan myproject /path/to/repo$ glyph fallow myproject$ glyph health myproject