README

drag-lint

The website is the up-to-date source: **[http://www.delphi-rag-lint.com](https://www.delphi-rag-lint.com)** -- help, articles and downloads. This README can lag behind it.

Alpha / work in progress. This is an early alpha under active, daily development -- expect rough edges, unfinished corners, and breaking changes between versions. It is shared early so the Delphi community can try it and shape it. Feedback and suggestions are very welcome -- please open an Issue with ideas, bugs, or "I wish it could...". Not yet recommended for unattended/production use.

A symbol-aware retrieval + lint + refactoring + IDE-integration tool for Delphi. Pure Object Pascal at runtime -- no Python, Node, or Rust. No cloud AI.

Use it as: CLI tool · LSP server (Zed / VS Code) · MCP server (Claude / Cursor) · RAD Studio 13 plugin.

Driving it from an AI agent? See docs/AI-USAGE.md -- copy-paste instructions so your AI uses drag-lint over CLI or MCP (and reads ~10-60x fewer tokens than opening whole units).

What it does today, and what is coming -- the feature list. A single readable document covering every capability by area (indexing, search, analysis, linting, diagnostics, documentation, refactoring, AI integration, IDE integration, reporting and the Component Converter), plus what changed in this release and an upcoming roadmap of everything currently planned. Features (generated from the feature registry), and Word, docs/drag-lint-features-2026-09-16.docx. Every count in it is read from the shipping build, not from the previous edition.

Built on tree-sitter-delphi13 (sibling project) and a vendored Pascal binding for libtree-sitter.

Background reading -- why that foundation. "Three Ways to Read Delphi" compares a raw lexer, DelphiAST and tree-sitter as three answers to one question: what should happen when the source does not fit? Covers the conditional-compilation fork, byte-exact round-trip fidelity, and three case studies -- including where a hand-written AST still wins. Also as styled HTML -- docs/PARSING-LAYERS.html (rendered) -- and Word, docs/PARSING-LAYERS.docx.

Companion: Delphi-RAG-Lint-Graph -- a standalone VCL viewer (Win64) that turns this index into an interactive symbol graph: UML class boxes, a Code Flow View that renders your DocInsight comments, a Where-Used caller list, search with Back/Forward history, and editor-sync (the graph follows the active unit in RAD Studio). Click-to-jump back into the IDE.

Screenshots

Out-of-process compiler intelligence, inside the IDE

Live diagnostics come from compiling your buffer in a spawned process -- even unsaved code -- so the IDE never freezes. The Structure panel and a dockable code graph sit beside the editor.

Your DocInsight /// comments, in Help Insight

`` and <remarks> render natively in the IDE's Help Insight tooltip.

Code Flow View

Trace a routine's calls as a flowchart -- each box carries its DocInsight summary (here TCompileChecker.Run).

UML class view, with doc on hover

Search a type to see its members (visibility glyphs + full signatures); hover a member for its DocInsight doc.

Where Used

A precise, clickable list of a symbol's callers -- 7 callers of ResolveActiveIndexDbs -- beside its unit's call graph.

AST-exact symbol query (CLI)

drag-lint query --name TCompileChecker --json returns every match with kind, qualified name, section, file and precise line/impl ranges -- no comment or string-literal noise.

Find callers, with source context (CLI)

drag-lint query find-callers lists every caller (7 here) with the surrounding source lines.

Semantic compile-check from the CLI

drag-lint check-unit compiles a unit in its project's context and reports findings (here: clean).

Diagrams and charts

Ask the index a question about one symbol, get a clickable chart back. Twenty-five formal questions -- butterfly, who-calls, what-it-calls, who-writes, who-reads, change-impact, tested-by, effects, touches-tables, class-surface, hierarchy, deps, cycles, wiring, lifecycle, event-wiring, architecture, protocol-trace, crosses-boundary, shown-where, exception-paths, consumers, feeds-from, lands-where and round-trip (one grid field, client -> pipe -> server -> SQL and back).

From RAD Studio: put the caret on the symbol and pick the question from drag-lint > Reports. The menu groups the questions by what you select (routine, field or grid column, type, unit, project, table), resolves the symbol under the caret to its full name, and runs the report in the background. The chart opens in your browser; the text answer is copied to the clipboard (and shown in a small IDE window) as a DocInsight /// <remarks> block you can paste above the declaration -- it carries no autodoc marker, so Auto Document leaves it alone. The same submenu holds Forms for testers (CSV)..., a spreadsheet of every form and how to reach it. See IDE Menu Reference.

From a terminal or an AI agent: drag-lint ask <id> --target <name> --project <x.dproj> [--open] -- it finds the indexes itself and prints the answer as text. Every question is answered in-process by the engine; no PowerShell is needed (pictures need Graphviz).

drag-lint is not a model: every chart comes from a formal call, and every row in it is a fact from the index with a file and a line. Each answer is a bundle -- graph.svg whose rows link back to the source (draglint://open: a click is received by drag-lint-open.exe, which hands it to the IDE plugin, once drag-lint protocol register has made the link clickable -- see Click-to-source links), PNG and PDF exports of the same layout, a browser shell, a meta.json that fingerprints the index and records the command that regenerates the chart, and a ready-to-paste DocInsight <remarks> reference. Full reference, one page per question: Diagrams and Charts.

The three charts below are drag-lint's own code, produced by the engine's drag-lint ask verb against a copy of its self-index at v1.17.0-alpha. (The PowerShell emitters under charts\src remain in the repository only as an internal parity reference.)

change-impact -- one function feeds closure, parse and lint

Question change-impact, target DRagLint.Preprocess.Profile.ProfileFromDproj, depth 3. 15 routines reach it: pp-profile and the index-profile resolver directly, then the project closure (BuildProjectFileScope), index, lint, lint-all, reconcile-project and document for a project. This is why reading the platform PropertyGroups in that one function moved the extractor version. Produced by drag-lint ask change-impact --target DRagLint.Preprocess.Profile.ProfileFromDproj --depth 3 --cap 16 (with every row shown).

deps -- where the linter sits in the layering

Question deps, target DRagLint.Lint.Linter. 6 units use it (the CLI and its program file, two LSP units, the MCP server, one lint unit); it uses 9 (core, parser, diagnostics, tree-sitter and three lint units). Boxes are src\ folders; a dashed edge is an implementation-section uses. Produced by drag-lint ask deps --target DRagLint.Lint.Linter. The whole-project architecture question on the same index draws 129 units in 23 zones with 598 internal edges -- correct, and too dense for a page, which is why the one-unit view is shown here.

butterfly -- the enum-value binding entry point

Question butterfly, target DRagLint.Index.CallResolver.TCallResolver.ResolveEnumValueRead, depth 2. 2 callers (the store's enum-value and call-target resolve passes) and 14 callee rows (scope checks, the identical-copy collapse, the symbol-store lookups). Produced by drag-lint ask butterfly --target DRagLint.Index.CallResolver.TCallResolver.ResolveEnumValueRead --depth 2.

Quick start

Common questions -> command

The fastest command for each question people actually ask. This table is also the first thing drag-lint --help prints, and it lives in docs/AI-USAGE.md too; the three must agree (see the DOCS-IN-SYNC rule in CLAUDE.md).

An explicit --db must exist. If any path you pass is not there, the verb names it (with its position, --db #2 of 3) on stderr and exits 2 -- it never answers from the databases that happened to open. A narrowed answer is indistinguishable from a complete one. Omit --db and the manifest resolver supplies the set, dropping absent files itself. With --project, a reader resolved through the consumer DB list opens the project's OWN index (its exact manifest section, else <project dir>\_D-RAG\<base>.sqlite) plus the platform library -- no sibling project's DB. Two readers are exceptions: outline --in F --project P also opens the DBs that hold or folder-match F (siblings included), and lint's dl:shared check opens the sibling projects a shared unit declares, on purpose. index (given --project or a .dpr/.dproj) and refresh-findings write to that own index and refuse when two sections claim the project; compile-check caches only into an explicit --db or the project's unique manifest section. A "db" in .drag-lint.json counts as an explicit --db.

Output encoding (every verb, stdout and stderr). The default is 7-bit ASCII: each non-ASCII UTF-16 code unit is written \uXXXX (lower-case hex; a character outside the BMP is its surrogate pair), which inside --json is the JSON escape itself, so a JSON reader gets the exact string back; in text output it is reversible unless the original held a literal backslash-u-four-hex sequence. ASCII output is byte-for-byte what it always was. --output-encoding utf8 or utf16 writes UTF-8 / UTF-16LE instead (no BOM); "outputEncoding": "utf8" in .drag-lint.json sets it when the command line does not; any other value is an argument error (exit 3). Files a verb writes (--output, reports) obey it too. When an ascii run turns non-ASCII characters into \uXXXX escapes it prints ONE stderr warning naming the count and how to switch (--output-encoding utf8, or "outputEncoding" in .drag-lint.json); a JSON file written with --output then also carries a leading "lossy_output": N. Non-ANSI characters in paths are stored in the index intact (they were ? before 2026-10-26).

Exit codes of the read-only verbs follow grep -- 1 is an ANSWER. 0 = answered with results; 1 = answered, EMPTY or NOT FOUND (query, query find-callers -- --json prints [] --, ancestors, descendants, context, call-path, reverse-calltree); 2 = usage error, an unknown callgraph --format, or a --db that is missing or at an OLD SCHEMA (also a manifest-resolved list whose every database is stale) -- nothing was answered; 3 = FATAL, including a stdout pipe the reader closed early (| head), so a truncated run never reads as clean. lint / lint-all use the opposite polarity: 1 = findings survived (--fail-on).

The traps, because each one turns a correct command into a silent zero:

• find-callers matches the bare member name. --name TFoo.Bar returns 0; --name Bar returns the call sites. The 0-caller hint says so and names the bare name. A property getter/setter (GetFoo) is also 0 in the plain form -- the default stays name-based -- and its hint points at usages --rw, which lists the readers and writers of a member, plain backing fields included (find-callers --resolved still reaches it through the property). usages counts a qualified call FHost.Feed(x) once (it used to count the stored call + member-access pair twice).

• find-callers also reports interface dispatch (RB-5): a method reached only THROUGH an interface method it implements lists those sites as a separate via <IFoo.Bar> dispatch group; --json rows gain via (the interface method), via_kind (interface) and, when the implements edge is ambiguous, via_edge, all placed before resolution. impact lists an interface method's implementors (--format json: implementors, via_dispatch [of via, kind, sites]), context adds ## Callers via interface dispatch sections (JSON: a via_dispatch array of {via, kind, sites}), and call-path follows an interface method to its implementors.

• implementors --target <IFoo|IFoo.Bar|TFoo|TFoo.Bar> is the interface report (1.40): which classes implement an interface and how (lists / via a derived interface / inherited / delegated by an implements property), which method answers an interface method in each class (resolution clauses IJob.Execute = RunJob included), the call/read/write sites of an interface member (attributed to the member, RB-5), a class's interfaces and what answers each member, and for a class method the members it answers (--uses: the sites reaching it; --max-sites N caps the list). --json = implementors/1; --format dot|mermaid; --library-db adds library implementor counts (--include-library lists them). Chart: ask implementors. MCP: get_implementors.

• find-unit for an RTL / VCL / third-party symbol needs the platform library database (resolve-dbs --platform win64), not a project DB - a project DB holds only that project's own units.

• query --name U --exact against a project DB answers MEMBERSHIP in both directions: a project DB is exactly the compile closure, so a miss is a real answer, not a lookup failure.

• query unit-usage without --in answers the project-wide question (which files reference the unit, and which merely IMPORT it; --limit N lists the first N and keeps the full counts); with --in it answers about one file. Its candidate set is the uses graph, since in Delphi you cannot name an export without a uses entry. For an RTL/VCL/third-party unit whose exports live in the platform library index, the project DB alone still answers the project-wide form: you get the importer list with the uses line, and an explicit note that reference counts were NOT computed -- never DEAD IMPORT, which without the export surface would be an artefact rather than a fact. Pass the library DB as a second --db for the breakdown. The --in form still exits 2, because "which of U's exports does this file use" is unanswerable without U's exports.

• query --text searches string literals, DFM, SQL and COMMENT PROSE -- //, { }, (* *) and ///. It still does NOT search source text (identifiers, declarations); use query find --decl-contains for a declaring line. Narrow with --kind literal|const|resourcestring|format|comment|doc|dfm-prop|sql-exception; --kind literal reproduces the behaviour from before comments were indexed.

• lint <file> is a strict subset of lint-all: project-wide rules (unused-public-symbol, unused-unit-in-uses, the uses-edge and duplicate-global rules) can only fire in lint-all. Never report "clean" from a per-file run.

• context wants the fully qualified name - Unit.TType.Member. It is about 60x leaner than reading the source files; add --full-surface only when the task is about a form's components, DFM or event wiring.

• A note: N of M indexed file(s) changed since this index was built line means reindex first. The answer may be stale. The note is on stderr, never inside a JSON document. The object envelopes of reverse-calltree, butterfly, callgraph, sql, schema and deps-report also carry "stale": true|false and "stale_files": <n>, so a consumer can surface staleness without reading stderr (stale is false for an index too old to carry the freshness stamp, exactly as the note is silent then).

  lint-all --json (and --format json|sarif) writes NOTHING to stderr on the success path (no progress lines, no control-channel line, no scope notes), so a 2>&1 capture is still one parseable document; errors and warnings stay on stderr.

Add --json to any query for machine-readable output.

Standalone CLI

1. Download the latest release (drag-lint.exe + tree-sitter*.dll).
2. Put them in the same directory.
3. Index a Delphi project:
   pascalCopy

   drag-lint index --project C:\Projects\MyApp\MyApp.dproj --db myapp.sqlite

4. Query symbols:
   pascalCopy

   drag-lint query --name TFoo --db myapp.sqlite
   drag-lint surface --qname Unit.TFoo --db myapp.sqlite
   drag-lint impact --qname Unit.TFoo.DoBar --db myapp.sqlite

Scan type and mode: two independent axes

Scan TYPE is declared by the target, not by a flag:

The project row means index --project <file> or a manifest include naming the project file. A POSITIONAL index <file.dproj> is not a closure scan: it refreshes only that one file, with no project defines, into the project's own database.

A project DB belongs to one project. A project-scoped run (--project, or a positional .dpr/.dproj) into a DB whose project_tag names a DIFFERENT project is refused (exit 2, naming both and suggesting resolve-dbs --project <x>), leaving the DB byte-identical; --rebuild proceeds with a NOTE, replacing the other closure wholesale. An untagged DB (fresh, folder-built, or pre-1.18) is accepted. (1.31.2)

MODE is chosen per run, independently of type:

Prefer one DB per project: a project DB answers questions about that project exactly. A question that spans projects needs several --db flags - drag-lint resolve-dbs --platform lists every configured DB, and resolve-dbs --project <x.dproj> / --in <x.pas> resolves a single target.

The first --db is the primary; every later one is an extra store. The primary answers the query and is the only store contributing resolved call edges - extras are searched by name for callers and used-in units. So the DB that owns the code under the question goes first, the platform library after it. The rule is the same for document, lint-all, lint-project and the exporters, so one --db list works across verbs: a block written by document --db P --db L is accepted by lint-all --db P --db L.

Indexing the Delphi RTL/VCL libraries

To build one index over everything Delphi itself knows about - the IDE's Library and Browsing search paths, read straight from the registry, deduplicated, with $(BDS) / $(Platform) macros expanded - use the --scan-libraries-* flags (no project or path needed):

drag-lint index --scan-libraries-win --db Library.sqlite   # Win32 + Win64 (default)
drag-lint index --scan-libraries-all --db Library.sqlite   # every registered platform

• --scan-libraries-win covers the IDE's native targets (Win32 + Win64). Because the RTL / VCL / FMX .pas source is shared across platforms, this already captures essentially all library source. (Its older spelling is listed under "Flag aliases:" in drag-lint --help.)
• --scan-libraries-all enumerates every platform subkey under ...\BDS\37.0\Library (Android*, iOS*, Linux64, OSX*, Win64x, ...). On top of the Win set it pulls in the platform-specific source trees - source\rtl\posix, source\rtl\ios, posix\osx - so symbols like Posix.*, iOSapi.*, Macapi.* and Androidapi.* resolve too.

Both probe HKCU + HKLM in both the 32- and 64-bit registry views and fold the results into a single deduplicated folder set. Add --dry-run to print the resolved folder list without indexing.

I installed new 3rd-party components. How to rebuild the library index

When you install a new third-party package (DevExpress, TMS, Raize, Async Professional, ...), its component installer registers its source/DCU folders on the IDE's Library and Browsing search paths. The library index does not update itself - it is a snapshot of those paths from the last scan, so symbols from the new components stay unresolved until you rebuild it.

1. Confirm what's missing (optional but quick). library-drift lists every registry root that is not yet in the index and exits non-zero if there's drift - run it right after installing to see the new folders:

drag-lint library-drift                       # active platform
drag-lint library-drift --platform win64      # a specific platform

Any MISSING: <path> line is a component folder the current index doesn't cover.

2. Rebuild the library index. Pick whichever matches how your indexes are managed:

• This repo's managed indexes (recommended here). The Library section of the named-DB manifest (third_party/dll-win64/drag-lint.json) has "source": "registry-libraries" and rebuilds both platform DBs (C:\Projects\.drag-lint\library-Win32.sqlite / library-Win64.sqlite) straight from the registry. Rebuild only that section - no need to touch the project indexes:
  pascalCopy

  drag-lint index --all --only Library            # both platforms, from the manifest
  drag-lint index --all --only Library --dry-run  # preview: prints the two target DBs first

• A standalone library DB (no manifest). Re-run the same --scan-libraries-* scan that first built it, pointing at the same --db file (it is rebuilt in place):
  pascalCopy

  drag-lint index --scan-libraries-win --db Library.sqlite   # Win32 + Win64
  drag-lint index --scan-libraries-all --db Library.sqlite   # every registered platform

3. Verify. Re-run library-drift - it should now report 0 missing (exit

0. If a folder still shows as MISSING, the component didn't register that path on the IDE search paths; add it under Tools -> Options -> Language -> Delphi -> Library (Library or Browsing path) for the right platform, then rebuild again. A root listed as EXCLUDED BY CONFIG (JSON excludedRoots) is pruned by the section's exclude globs (e.g. "Win64") and is not counted as drift.

Notes:

• Close nothing / rebuild anytime - this is a CLI (.exe) scan; RAD Studio can stay open. If the target .sqlite is locked, an orphaned drag-lint.exe is holding it - stop that process (not the IDE) and retry.
• After rebuilding, restart the IDE plugin's LSP (or reopen the project) so the running plugin picks up the refreshed library-*.sqlite. The CLI sees the new DB immediately.
• The scan reads the RTL/VCL/FMX and third-party source paths; components shipped as DCU-only still resolve for uses/dependency purposes but won't have browsable source bodies.

Untangling unit dependencies (cycles + uses cleanup)

This works because of the thorough index of the Delphi platform library and of your project: every unit, uses edge, symbol and reference is already in a local database, so drag-lint knows which symbol ties a cycle together and who uses it. The work runs locally and needs no AI and no internet: cycles, --plan and --fix make no network or model call (the only programs they start are your own msbuild, to prove an edit, and this engine re-indexing). In short: index --project X.dproj --db d.sqlite, then cycles --db d.sqlite --causes, then cycles --fix --project X.dproj --db d.sqlite (dry run), then the same with --apply; the steps are spelled out on the wiki page Circular Uses Report (cycles + fix plan). Find circular unit dependencies and the exact uses lines that form them:

drag-lint cycles --db myapp.sqlite --edges

Each cycle lists its A uses B [interface|implementation] edges, marks the interface edges as move-to-implementation candidates, and flags layering inversions (e.g. a COMMON unit reaching into CLIENT). Add --causes to pinpoint the specific symbols in A's interface that force the dependency on B (the types/vars/methods to move or extract) -- with the line numbers, and an honest note where the index couldn't resolve a reference.

Or generate a mechanical refactoring playbook -- written so that a model with no project context (or a junior dev) can follow it literally to a compiling tree:

drag-lint cycles --db myapp.sqlite --plan > cycle-plan.md

Per cycle it gives:

• what moves where -- each load-bearing symbol with its kind and a recipe for that kind: an enum / record / constant / variable moves unchanged (exact file lines, doc comment included); a class whose method bodies use the cycle is NOT moved -- a base class carrying just the members its consumers use is extracted into the leaf unit instead, and the reason is given. Every unit that uses a moved symbol is listed with its section and first-use line;
• uses decisions -- per unit, whether the old cycle partner is kept, moved from the interface to the implementation uses, or removed (only when nothing else from it is used in that section);
• the new units (<Declaring>.Untangle.pas; an existing <Declaring>.Untangle that still uses no unit of the cycle is extended in place instead) with their full text, and the rule for their uses clause (never a unit of the cycle);
• every edit to every file, .dpr and .dproj included, as current text + new text, listed bottom-up so line numbers stay valid;
• DONE and a checklist that ends with the re-index command and the exact output drag-lint cycles must print afterwards -- predicted by replaying the plan on the uses graph -- plus what to do for each compile error the edits can produce.

Since 1.43: two units whose moved types need each other (the F2047 shape) share ONE new unit, with forward declarations, instead of two new units that would be F2047 again; a set that cannot share one type block refuses coupling-remains, as does a plan whose own prediction still shows the interface coupling. Unit.GVar follows its move to Unit.Untangle.GVar (code only, never a comment or a string). A routine passed as a whole argument goes through its pointer. A call run from the consumer's finalization section is no init-order case any more; it is cut unless the declaring unit, finalized first after the cut, could show finalized state (finalization-order).

An interface-coupled cycle is cut to a legal implementation-only one (Part A); an optional Part B names the edge whose globals can move next, and re-running --plan on the edited tree prints it as the same kind of steps. On the circular-demo project, applying Part A and then Part B literally compiles, prints exactly the predicted output at each stage (the last being No circular unit dependencies found.), and the program's output is byte-identical to the original's. Followability is measured, not claimed: Haiku at its lowest effort, given only that report and a fresh copy of the project ("Break the cycle."), produced a tree that compiled with 0 errors and matched the predicted cycles output -- 4 of 4 criteria, first on 2026-09-23 and again on 2026-09-28 against engine 1.19.0-alpha. The report shape before it failed the same test, which is how the playbook got its current form.

Worked example: docs/examples/circular-uses-demo/ is a tiny compiling two-unit cycle, with the exact --edges / --causes / --plan output drag-lint produces for it captured verbatim in REPORT.md. (circular-uses is also a built-in lint rule, on by default, so lint-project flags cycles automatically.)

Then propose and apply the cleanup, verified by the compiler so it never breaks the build:

drag-lint uses-audit MyUnit.pas --db myapp.sqlite                       # propose
drag-lint uses-fix --project MyApp.dproj --db myapp.sqlite              # dry-run sweep report
drag-lint uses-fix MyUnit.pas --project MyApp.dproj --db myapp.sqlite --apply   # apply (.bak backup)

Caveat (important): uses-fix's per-unit verify is best-effort, not a faithful full-build check -- a single-unit dcc compile can reuse a stale .dcu (masking a real error) or abort on an RTL dependency. Treat cycles/uses-audit as advisory (they pinpoint candidates, and the index can miss refs like set types), and always do a full project build after --apply (revert from .bak if it fails). Reliable bulk cleanup needs full-project-build verification, not per-unit compiles.

A cycle report, generated not written

circular-demo/ is a small sample project (10 units) with three genuine uses cycles that still compile, each a different shape: a four-unit cycle coupled through interface uses and shared globals (one of its four edges is an implementation uses, which is exactly what makes it legal Delphi); a three-unit implementation-only cycle whose only cheap cut is a single routine call; and a two-unit implementation-only cycle whose only cheap cut is a member access behind is / as. The report plans the first one mechanically and says, per edge, why it refuses the other two. The full writeup is at circular-demo/CYCLE-REPORT.md.

This report is produced by drag-lint, not written by an AI. It is the literal stdout of two commands, run against the indexed project:

drag-lint index  --project circular-demo\CircularDemo.dproj --db circular-demo\_D-RAG\CircularDemo.sqlite
drag-lint cycles --db circular-demo\_D-RAG\CircularDemo.sqlite --edges --causes --plan --format text

An excerpt of the real output (every quoted line is verbatim; ... marks an elision):

## Cycle 1: demologger <-> democonfig <-> demoaudit <-> demosession

### Why it cycles
- `demologger` interface uses `TDemoSession` (class) at `DemoLogger.pas:40`; declared in `DemoSession.pas:20`.
- `democonfig` interface uses `TDemoLogLevel` (enum) at `DemoConfig.pas:23`; declared in `DemoLogger.pas:15`.
- `demosession` interface uses `TDemoAuditKind` (enum) at `DemoSession.pas:35`; declared in `DemoAudit.pas:24`.
...
### Step 1: what moves where
1. `TDemoSession` -- **class with methods**, declared at `DemoSession.pas` lines 14-47; method bodies at `DemoSession.pas` lines 64-73, 75-80, 82-86, 88-95, 97-100.
   - Recipe: **extract a base class** and keep `TDemoSession` where it is. Why: its method bodies use `GDemoSessionCount`, `GDemoAuditCount`, `GDemoAuditTrail`, which live in units of this cycle; moving the class would mean moving those bodies (lines 64-73, 75-80, 82-86, 88-95, 97-100) AND everything they use.
...
12. [ ] Run `drag-lint cycles --db "circular-demo\_D-RAG\CircularDemo.sqlite"`. It must print exactly:
3 circular unit group(s) found:
...
  [4 units] demologger <-> democonfig <-> demoaudit <-> demosession   (implementation-only -- legal, lower impact)

circular-demo/CYCLE-REPORT.md is the full, unabridged output -- the file to hand to a model. It, this excerpt and the wiki's are regenerated from and checked against the current engine by tests\autotest\run_cycle_examples_fresh.ps1, so none of them can silently fall behind the playbook again.

Or let drag-lint make the edits: cycles --fix. drag-lint cycles --fix --project circular-demo\CircularDemo.dproj --db circular-demo\_D-RAG\CircularDemo.sqlite is a dry run of the same plan for ONE group (the first mechanical one, or --cycle <n> / --unit <stem>): it builds the project first (a baseline that fails refuses the run; --no-compile skips the build), stages the edits in a shadow tree and prints the verdict, writing no source file. Add --apply to write them: every touched file is backed up as <file>.BCK<n> first, the project is built again (a compile error rolls every file back), the index refreshed, and cycles re-run against the prediction -- exit 0 written and verified (or written with --no-reindex, unverified); 1 refused, rolled back after a compile error or build timeout, or written but not verified; 2 error -- a write or build failed part-way (rolled back, project not changed, or the rollback failure is named), or bad flags (--part all applies Part A then Part B in one run). A group the engine cannot cut mechanically is refused with a named reason, never guessed at. The IDE offers it under Uses & Dependencies, on the Uses & Deps tab's Circular uses section, and on a circular-uses finding in the Structure window; details on the wiki page Circular Uses Report (cycles + fix plan).

Longer walkthrough: wiki -- Circular Dependency Report.

Third-party dependency report

See which external/library units the project leans on -- RTL, DevExpress, Spring4D, and anything not in your own tree:

drag-lint deps-report --db myapp.sqlite                 # rollup (text)
drag-lint deps-report --db myapp.sqlite --edges --format csv

Per external unit it reports which project units import it, how many, the shortest uses-path, and a library grouping; --edges gives the flat project-unit -> external-unit list. A unit is "external" when it isn't indexed or resolves to a library path (RTL / installed packages).

Component conversion

Plan AND APPLY a component/type migration (TDBEdit -> TcxDBEdit, or any TPersistent-rooted pair) from the REAL, AST-exact property trees of both types. proptree enumerates a type's deep property tree; convert-scaffold auto-drafts a validated reFind-superset rules file from both trees; convert-validate checks a rules file's paths against those trees -- catching typos that reFind's blind PCRE cannot -- and checks any G[I/N] glyph expression on a #link (syntax, ranges, one alternative per N; see docs\CONVERSION-RULES.md); and convert-apply rewrites the real .pas + .dfm files (dry-run by default, --apply to write for real, with automatic .BCK<n> backups + a recovery.txt unless --no-backup; a value an ANSI .pas cannot hold refuses the unit as encoding_refused, and --raise-encoding "<path>=utf8-bom" re-stores that file as UTF-8 with BOM). The book's unit rules act on the unit's uses clauses in the same run: #unuse Old removes Old, #use New adds New to the implementation uses, #useswap Old -> New1, New2 removes Old and adds each New once into the section Old was in -- never a duplicate, a unit both added and removed is kept, and an entry inside a {$IF...} region refuses the unit rather than guess. A unit with no .dfm (or nothing a #convert block matches) gets its unit rules alone; info --json advertises this as capabilities.apply_unit_rules: true. Uses reconciliation (1.27.0, default on; --no-reconcile-uses restores 1.26.6): the converted .pas/.dfm are re-indexed in memory and #unuse becomes a WATCH LIST -- a unit is KEPT (a kept row + warning naming the components) while a component the converted .dfm still streams needs it, REMOVED when only .pas code needs it (the dangling references are named; the compile errors are the intended signal), and kept when no --db knows it; presence is scope-alias aware (#unuse DBTables matches Bde.DBTables, #use DB is satisfied by Data.DB); a name the conversion introduces into the .pas gets its unit added (none since 1.27.0: a cast link no longer writes a .pas site, one cast-not-applied per site instead); a #link X <- X : StripDB value cast (shipped castlib, value strip-db) drops a trailing .db from the string in the .dfm and in single-literal .pas assignments ending the statement on their line, reporting every other site (a with block included) (capability value_cast_strip_db); an enum type #migrate maps members by the name after the lowercase prefix, and --old-platform-db <file> (1.43, capability old_platform_enum_map) reads the From members from the index of the platform the code was written against; inside a #convert block #migrate Old -> New renames a member (method, event, property) at every bound .pas access site and #migrate Old -> DL_NONE wraps it, inst.Old -> DL_NONE(inst.Old), a deliberate break that does not compile until converted by hand (items[] migrate-applied / deliberate-break / migrate-check, capability migrate_members, C18 slice 1); every run lists what the .pas still uses that the map does not cover in pas_uses[] (status mapped / cast-refused / not-rewritten / same-name / unmapped / global-dangling, capability pas_uses; since 1.28.2 the From class is resolved through the unit's uses scope and each row carries resolution resolved / ambiguous (with candidates[], nothing picked) / class-not-found / member-not-found / kind-unknown, capability pas_uses_resolution), and a name two units declare is reported (uses_unresolved), never picked -- unless the book's #use (or a uses entry of the unit) names one of them: a To type's unit is then added to the INTERFACE uses when its retyped field is declared there, or moved there. After --apply the unit's own project DB is refreshed (index --project, child process, terminated as failed after 10 minutes; --no-reindex skips it). capabilities.uses_reconcile: true. A book can also REPORT without writing anything (1.26.5): #warn <FromPath> "<text>" warns once per converted instance whose source .dfm streams the property (<value>, <name>, {Prop} placeholders), and #check-ref <ToPath> <Class>.<Prop>[, ...] warns when the converted value looks like a file path or names nothing any .dfm of the project carries (items[] kinds book-warning, ref-path-like, ref-dangling, ref-not-checked). The usual workflow: convert-scaffold -> convert-validate -> convert-apply (dry-run, review the plan) -> convert-apply --apply. Before a glyph rule, glyph-vacuum measures every streamed graphic in the legacy tree (class, property, strip geometry, count property) and writes a reviewable gallery -- the input to docs\GLYPH-CLASSES.md and the G[I/N] grammar (--append merges a rescan into an existing run). Full DSL reference, the 5 conversion surfaces, and the safety scheme: docs/CONVERSION-RULES.md.

ConvRulesEditor.exe -- the visual rule-book editor. Shipped in the win64 archive next to drag-lint.exe (it is built by dcc64 from a .dpr with no Win32 configuration, so the win32 archive has the rule books and the CLI verbs but not the GUI). It puts the source type's real property tree beside the target type's -- both read from the index, so both are the actual deep trees including inherited and nested members -- and lets you pair them up, author conditional mappings, see which types on a form are already covered by a rule, and compose the rules for one job out of several books. It authors the plan; the CLI applies it. Starter books are in convrules\, and the class/enum cast library casts.castlib sits beside the exe (convert-apply --castlib reads the same file). Manual: docs/converter/convrules-editor-manual.md; rule language: docs/converter/convrules-dsl.md.

Consuming the index from another tool

The SQLite index is documented for external consumers in docs/INDEX-SCHEMA.md -- every table, the project-vs-external boundary, and the stability contract. Introspect any index live with:

drag-lint schema --db myapp.sqlite --format json        # schema_version + tables + columns + row counts

When no verb answers the question you actually have, query the index directly. sql is read-only by construction -- an sqlite3 authorizer refuses ATTACH, PRAGMA, DDL and every write, a row cap and a wall-clock cap bound the answer, and exactly one statement is allowed:

drag-lint sql --db myapp.sqlite --limit 5 \n  --query "SELECT kind, COUNT(*) AS n FROM refs GROUP BY kind ORDER BY n DESC"

Ask schema --format json for the columns first: table names are discoverable, semantics are not.

Words the code does not spell

Every other query here assumes you already have an identifier. wiki starts from a word a person uses. A dl:wiki block is written inside an ordinary /// comment -- on the type that owns the concept, or above unit X; when the concept spans several types -- and names the aliases the team actually says:

/// <remarks>
/// dl:wiki Delta Streaming
/// Aliases: delta stream, cmdDelta pipeline, the streaming path
/// SeeCode: TDeltaStreamer, TDeltaSet.ApplyDelta
/// Body:
/// How row changes travel from client to server.
/// </remarks>
unit Micronite.Delta.Pipe;

drag-lint wiki --term "the streaming path"   # -> owning symbol, SeeCode targets, body
drag-lint wiki --list                        # every topic in the resolved indexes
drag-lint wiki --check                       # every SeeCode entry must resolve; exit 1 on drift

Nothing about this is a new index: the block lands in symbol_docs.raw_block through the existing extractor, so authoring one costs no reindex beyond the ordinary incremental walk any edited file already gets. Format: docs/wiki/Wiki-Blocks-Authoring.md.

Semantic errors without a full build

check-unit compiles a single unit in its project's context, so you get real compiler errors (e.g. E2003 Undeclared identifier) fast -- and on the unsaved buffer via a shadow overlay:

drag-lint check-unit MyUnit.pas --project MyApp.dproj --platform win64 \
          --db myapp.sqlite --resolve-uses

--resolve-uses turns an undeclared identifier into a fix: "add unit X to the uses clause."

LSP server (Zed / VS Code)

Point your editor's LSP config at drag-lint.exe lsp --db <path>.sqlite. The server speaks JSON-RPC over stdio.

Capabilities: hover, definition, references, completion, signatureHelp, diagnostics (publishDiagnostics on didSave), workspaceSymbols, rename (prepareRename + rename: a WorkspaceEdit the editor applies -- the server itself writes no file).

MCP server (Claude / Cursor)

Register it with Claude Code, VS Code and Cursor in one step:

drag-lint mcp-config --all [--db C:\Projects\MyApp\_D-RAG\MyApp.sqlite] [--dry-run]
drag-lint mcp-config --claude-code --remove
drag-lint init --project C:\Projects\MyApp\MyApp.dproj [--dry-run]   # register + index + mcp-config --all for one project

--claude-code edits the top-level "mcpServers" object of ~\.claude.json (%CLAUDE_CONFIG_DIR%\.claude.json when that is set); --vscode edits "servers" in %APPDATA%\Code\User\mcp.json; --cursor edits "mcpServers" in ~\.cursor\mcp.json; --all does all three and skips a client that is not installed. The entry is {"type":"stdio","command":"<engine>","args":["serve"(,"--db","<index>")]} (plus "env":{} for Claude Code); --engine <exe> overrides the default (this exe), --name <n> the entry name (default drag-lint). The edit is merged (only that one entry changes; every other key and server is kept, numbers keep their text), backed up (<file>.bak-<stamp>) and idempotent (a matching entry is unchanged and nothing is written); keys you added to the entry, such as env, survive an update, and env / headers values print as *** (an entry refused as not ours is never printed). An entry by that name that runs something other than drag-lint.exe is refused, as is a file holding comments or trailing commas (the entry to paste by hand is printed instead) or one that is not valid JSON. --remove takes only our entry out; --dry-run writes nothing; --json prints one object per target; --config-path <file> edits another file (with exactly one target), and --home-dir / --appdata-dir move where the default files are looked for (tests). Exit 0 done or unchanged, 1 refused, 2 usage/setup. This verb replaces charts\src\Set-DragLintMcpConfig.ps1.

Or add it to your MCP config by hand (e.g. ~/.claude/claude_desktop_config.json):

{
  "drag-lint": {
    "command": "drag-lint.exe",
    "args": ["serve", "--db", "C:\\Projects\\MyApp\\_D-RAG\\MyApp.sqlite"]
  }
}

15 tools are then available to Claude: find_symbol, find_callers, get_symbol_doc, get_context_bundle, rename_symbol, run_compile_check, and more (see MCP tools below).

Click-to-source links (draglint://)

Chart rows link to draglint://open?file=...&line=.... One per-user registry key (HKCU\Software\Classes\draglint, never HKLM, no elevation) hands such a click to drag-lint-open.exe, which validates the link and hands it to the IDE plugin, which opens the line in the running IDE:

drag-lint protocol register [--handler <drag-lint-open.exe>] [--dry-run] [--force]
drag-lint protocol status [--json]          # ours | legacy-powershell | foreign | none; exit 0 only when ours
drag-lint protocol unregister [--dry-run] [--force]

register defaults to the drag-lint-open.exe beside drag-lint.exe and registers it in place. It refuses a handler inside a *-wt\ worktree and a registration that belongs to another program unless --force is given; the older PowerShell registration made by charts\src\Register-DragLintProtocol.ps1 is replaced silently, and its copy %LOCALAPPDATA%\drag-lint\Open-DragLintUri.ps1 is deleted. --dry-run prints what would be written and writes nothing. This verb replaces Register-DragLintProtocol.ps1.

RAD Studio 13 plugin

1. Build the BPL:

   pascalCopy

   msbuild src/delphi-plugin/dclDragLintWizard.dproj /p:Platform=Win64 /p:Config=Debug

   Or download dclDragLintWizard.bpl from the latest GitHub release.

2. In RAD Studio: Component > Install Packages > Add -- browse to the BPL.

3. Restart RAD Studio.

4. The Tools > drag-lint menu now has 12+ entries. Settings live under Tools > Options > Third Party > drag-lint as four pages (General / Indexer / Linter / Editor); per-project lint rules are reachable via a "drag-lint: Project Rules..." right-click on the project node in the Project Manager.

5. On IDE startup, the drag-lint logo + version appear on the RAD Studio splash screen. Help > About > drag-lint shows an entry with live engine self-info (version, build date, tree-sitter versions, capabilities, exe path, plugin log location), fetched from drag-lint.exe on a background thread so it never blocks IDE startup; if the exe call fails, the entry shows a structured diagnostic error block instead.

Features

The table is generated from the feature registry (features\); the one-line-per-feature page is Quick Help and the registry itself is described on Feature Registry.

Editors

drag-lint lsp is a stdio language server: hover, go-to-definition, find-references, workspace symbols, completion and signature help, answered from the index across every project in your manifest at once -- no compiler and no project open. DelphiLSP implements neither find-references nor workspace symbols, so those two are drag-lint only.

It also answers one vendor-prefixed extension, draglint/hoverBundle: given a document position it returns the hover markdown, the structured hover model (the shape hover --format json emits) and the caller rows, in a single reply. The RAD Studio plugin uses it so a tooltip costs one warm request instead of a hover round trip plus three drag-lint.exe spawns that each re-opened indexes the server already had open. Any other client can ignore it; a server that predates it answers the standard -32601.

• VS Code -- extension included (editors/vscode/drag-lint/); package it with npm run package and install the .vsix. Findings land in the Problems panel tagged drag-lint, on save. It runs a private copy of the engine from its own globalStorage, so an open VS Code window never blocks an engine rebuild -- which makes it usable as a read-only window onto units something else is editing. Compiler diagnostics from DelphiLSP merge there for free if you install an extension that runs it: VS Code gives every extension its own diagnostic collection, so unlike the RAD Studio plugin the two cannot clobber each other. Since v1.5 it also ships a Pascal TextMate grammar and a colour theme generated from your own RAD Studio scheme (read out of HKCU\Software\Embarcadero\BDS\<ver>\Editor\Highlight), so the colours match the IDE literally rather than approximately -- before v1.5 nothing coloured Pascal in VS Code at all, since it has no built-in Pascal grammar.
• Zed -- tree-sitter highlighting and the language-server registration both live in the Rust extension at tree-sitter-delphi13/editors/zed/; see docs/EDITORS.md.
• Neovim / Helix / any LSP editor -- point it at drag-lint lsp. Add --full-rules (OFF by default for the bare server; the VS Code extension turns it ON through dragLint.fullRules, set it to false to switch it off) to publish the complete built-in rule set on every save instead of the subset; it runs lint out-of-process and reports its cost in ms on stderr. A platform-library unit (an RTL/VCL file covered by a library-*.sqlite) skips the project, flow and type-aware rules, in lint too: findings you cannot act on, and they blew the 8 s budget; the LSP and the IDE plugin's live lint also give such a file a 16 s budget instead of 8 s.

drag-lint lsp --proxy is a different shape of the same server: instead of answering alone, it spawns RAD Studio's own bin64\DelphiLSP.exe and relays the protocol between the IDE and it. The IDE's Code Insight manager is exclusive -- one server per language -- so registering drag-lint the plain way would trade the compiler front end (generics, with, inline vars, the unsaved buffer) for a symbol index. Proxying removes the either/or. Add --delphi-lsp <path> to override which server is spawned, or --delphi-lsp-bits 32 to forward to the 32-bit bin\DelphiLSP.exe instead of the default 64-bit bin64 one (any value but 32/64 exits 3). By default the relay is transparent: byte-for-byte identical to talking to DelphiLSP directly. Add --merge-diagnostics and drag-lint's lint findings (source drag-lint) are appended to DelphiLSP's own textDocument/publishDiagnostics notification, so compiler errors and lint findings arrive in ONE notification per file. It fails open: a file with unsaved edits, a clean file, a frame it cannot parse or a lint that overruns --merge-budget-ms <n> (default 300) forwards DelphiLSP's original bytes untouched. Add --merge-completion and drag-lint's completion items (from the --db index, or the indexes plain lsp would resolve) are appended to DelphiLSP's reply when their (label, kind) is not already there; DelphiLSP's items stay first. No drag-lint items, no index, or drag-lint over the budget forwards DelphiLSP's reply byte-identical. Add --merge-hover and drag-lint's hover facts (the same text plain lsp shows) follow DelphiLSP's hover after a --- rule, or stand alone when DelphiLSP has none; no drag-lint hover forwards DelphiLSP's reply (or its null) byte-identical. Add --merge-definition and a textDocument/definition that DelphiLSP answers with null or [] gets drag-lint's locations instead (a non-empty answer is forwarded untouched); DelphiLSP's initialize reply gains referencesProvider and workspaceSymbolProvider when it lacks them (or sets them false), and the proxy then answers textDocument/references and workspace/symbol itself from the index -- those requests never reach DelphiLSP.

drag-lint-switch --vscode --status|--on|--off toggles the delphi-lsp entry in a workspace's .vscode\mcp.json (backup on --off, restore on --on; refuses while VS Code runs).

See docs/EDITORS.md.

CLI

drag-lint <verb> [flags]. The complete, authoritative flag list for every verb is drag-lint --help; linked verbs below go to the matching wiki page for more detail and IDE-menu context. (Wiki links point at https://github.com/Alexl-git/Delphi-RAG-Lint/wiki and carry no .md suffix.)

Offline manual. The whole wiki is also published as a single ordered document -- docs/drag-lint-manual.pdf (~250 pages, bookmarked; a chapter per part, including Diagrams and charts) and docs/drag-lint-manual.docx. Regenerate with pwsh -File tools\build-manual.ps1; tests\autotest\run_manual_freshness_guard.ps1 fails the battery if it falls behind the wiki.

Indexing

Wherever a database is opened (index, query, lsp, serve) the 32-bit build refuses one larger than its size guard, because it would run out of address space mid-answer: --size-guard-mb N moves the threshold and --force32 overrides the refusal outright. Neither is normally needed on the Win64 build.

Search and navigation

Lint

298 rules across 18 categories -- 205 built-in + 93 external .scm, 251 enabled by default, 110 with an auto-fix.

CI flags (apply to lint / lint-all / check-ast): --format sarif (SARIF

2. .0), --fail-on <level> (nonzero exit at error|warning|info), --baseline <file> / --write-baseline <file>, --enable id1,id2, --profile <name>.

Naming fixes in a unit several projects compile (1.29.0). A naming fix (const-casing, method-pascalcase, local-var-casing, field-name-prefix, param-name-prefix, type-name-prefix, local-field-prefix) on a unit owned by two or more project indexes renames it in EVERY owner, or in none. Owners are found by the unit's full path in every DB the manifest lists; a stale owner is reindexed first (index --project); the new name must be free in all of them. An owner whose index is stamped with ANOTHER project's tag (the DB is some other project's closure) is unverified and refuses the rename; one that lacks a member its .dproj/.dpr declares is stale (the apply reindexes it). A single-finding fix (--fix-line + --fix-rule) is all-or-nothing and ends autofix: rename refused -- <reason>; a batch drops only the unsafe renames. A manifest that did not load completely refuses every naming fix (fail-closed). Only for 2+ owners (or unknown ownership) the run prints its plan -- rename-owners: N of M indexes, rename-project: <name> index=fresh|reindexed|stale|unverified [(<reason>)], rename-target: L<line> <old> -> <new> apply|dropped ..., rename-unknown:, rename-dropped-at-write: -- and --json gains projects and dropped_reason. The IDE's Fix it / Fix all in unit preview first and confirm before writing. Details: Multi-Project-Rename.

An autofix with several edits (a uses-clause move, unused-unit-in-uses) is an atomic group: every edit is validated against the on-disk file before anything is written, and one that would not apply drops the whole group. lint --fix --json marks such a finding "declined": true with a "decline_reason" (and applied: false); text output ends , N declined (...).

Docs

Refactor

Formatting is safe for your suppressions. drag-lint drives YADF for the current unit or the whole active project straight from the IDE menu, and neither // drag-lint:ignore comments nor // dl:ok <rule>@<hash> reviewed markers are invalidated by it. A dl:ok hash is computed over a normalised line -- comments and whitespace stripped, identifiers lowercased, string literals kept verbatim -- so reindenting and re-spacing cannot change it. Measured, not assumed: 10 markers in a real file survived a drag-lint format run with whitespace as the only difference, and one-line try ... except end; statements were not rewrapped. (Splitting or joining a line would re-hash a marker; that is the boundary of the guarantee.)

Whole-routine metric reviews are bound to the number. For the seven rules whose subject is an entire routine -- too-many-exit-points, cyclomatic-complexity, cognitive-complexity, method-too-long, too-many-locals, too-many-parameters, deep-nesting -- the marker's four hex digits are computed from the declaration line and the measured value. Without that, a dl:ok on one of them could never go stale: the marker hashes the routine header, which does not change when the body grows. Allow a 6-exit routine, add a seventh Exit, and lint used to report nothing at all -- neither the finding nor a stale marker. It now reports both, and the hint names the live number. An unrelated body edit that leaves the metric where it was does not invalidate the review. The marker grammar is unchanged; allow refuses a line that produces no metric finding rather than writing a hash that could never verify, and lint --json carries a metric field on these findings.

A marker that suppresses nothing is reported, whatever the reason. Besides review-marker-stale (the code moved), review-marker-unused (the finding is gone) and review-marker-malformed (not a rule id), review-marker-placeholder-hash (ON) flags a dl:ok whose @hash was never computed -- @0000 or a non-hex @xxxx on a // marker, or an @0000 marker written inside a { } block comment, where no marker is ever read. Record the real one with allow.

The REVIEWED stamp (optional). The @hash covers code only, so a marker's reason can go false without the marker ever going stale. Write REVIEWED <yyyy-mm-dd> (uppercase keyword, ISO date, anywhere in the reason) to record when a human last re-read it:

S := S + T; // dl:ok concat-in-loop@1a2b -- REVIEWED 2026-09-23 the loop is bounded

The stamp lives in the comment, so adding or refreshing it never changes the hash. review-marker-reason-unreviewed (OFF by default -- every older marker would report; opt in per project with "enabled" or --enable) flags a reason with no stamp, an invalid or future date, or a stamp older than max_age_days (default 180; "thresholds": {"review-marker-reason-unreviewed": N}, 0 = presence only).

Component conversion

Graphs

Compiler

Database

index also indexes .sql migration scripts, including CREATE EXCEPTION messages from MS*.sql files by default (--no-sql-ms to index every .sql).

Servers

Maintenance

Flag aliases

A verb's usage line names the canonical flag only. Each alias is accepted wherever its canonical flag is and means exactly the same, so scripts that use one keep working; write the canonical spelling. drag-lint --help lists them in its "Flag aliases:" section. Policy: docs/CLI-FLAG-ALIASES.md.

MCP tools (15)

Verified against src\mcp\DRagLint.MCP.Server.pas (HandleToolsList) -- this is the complete set the server registers; it does not expose import_log, format_file, workspace_status or workspace_index as MCP tools (those are CLI-only verbs).

Lint rule pack (298 rules)

Run drag-lint rules for the authoritative, always-current catalog (built-in + external .scm). As of v1.43.0-alpha: 298 rules across 18 categories -- 205 built-in and 93 external .scm, 251 enabled by default, and 110 with an auto-fix. The table below is a small sample of the built-in rules:

Compliance labels

Each rule can carry the CWE, CERT and MISRA ids it answers (data file rules\compliance.json; see docs\wiki\compliance-labels.md). drag-lint rules shows them ([CWE-476 EXP34-C]; --json adds a compliance object; --standard cwe|cert|misra lists only the rules labelled under one standard), lint --json / lint-all --json add compliance to each labelled finding, and lint --labels appends the ids to text findings. Labels never change a severity or an exit code.

Coupling rules

Newest additions, and a different kind of question: these ask which unit really depends on which, and why, rather than commenting on the code in front of you. They run project-wide, so they only fire under lint-all -- lint <file> is a documented subset that never reaches them.

global-only-uses-edge and uses-global-census are ON by default but each costs a full refs scan (0.92 s and 1.26 s on a 144 MB index), so both stay behind an opt-in gate that now defaults to keeping them -- filtering them out after the fact would hide the cost rather than avoid it.

Drop custom .scm + .json pairs in the rules/ directory; see rules/README.md for the schema.

RAD Studio plugin

The plugin exposes 66 entry points across four surfaces: 50 main-menu items, 2 under View > Tool Windows, 13 on the Structure form's right-click menu, and 1 on the Project Manager's. Auto-fix (Fix it / Fix all in unit / Fix all in project) and Allow this message live only on that right-click menu. There are also 12 Ctrl+Alt shortcuts (H hover, C completion, S signature, D diagnostics, R rename, M extract-method, I inline info, F find usages, T symbol search, U quick-fix uses, K reverse call tree, B butterfly).

drag-lint menu (top-level on the main menu bar -- falls back under Tools -- organized into submenus): Hover at Cursor, Show Completion, Show Signature Help, Run Diagnostics, Rename Symbol, Compile & Diagnose, Import Build Log, Format with YADF, Show Structure, Run AST Checks, Find Usages, Symbol Search, dockable panels (Structure / Usages / Graph), Reports submenu (every chart question, plus Forms for testers (CSV)...), Uses & Dependencies submenu (cycles, uses-audit, uses-fix, reconcile, wiring, impact, reverse call tree, Call Graph (Butterfly)...), Reverse Call Tree (clickable, Messages window) -- posts the N-deep upward call tree for the symbol under the cursor as clickable rows in the IDE Messages window (double-click a row to jump to that call site), Call Graph dock tab -- callers above and callees below the symbol as a navigable tree (double-click a node to jump to file:line); open it via Ctrl+Alt+B, the Uses & Dependencies menu item above, or right-click a symbol in the Structure tab -> "Show in Call Graph", Inspect Symbol submenu (surface, slice, type-at-cursor), Code Quality submenu (dead code, undocumented, TODOs, compiler hints, top symbols), Generate & Export submenu (docs, tests, enums, graph, Obsidian), Index & Maintenance submenu, plus diagnostics & test tools, and drag-lint Options... (opens Tools > Options focused on the drag-lint pages).

Keystroke bindings (registered via IOTAKeyBindingServices):

In-editor diagnostics: gutter dot markers + wavy underlines via IOTAEditViewNotifier.BeforeDrawLine. Severity colours from the IDE colour scheme registry.

Ghost-compile (live, out-of-process): as you type, drag-lint compiles your unsaved buffer(s) in a spawned process and surfaces real compiler errors (e.g. E2003 Undeclared identifier) in the gutter -- without saving, and without ever freezing the IDE. Fires automatically on idle and on tab-switch, with multi-unit overlays so edits across several open units are all seen.

Your files are never written. Since 2026-09-08 each dirty buffer is staged into a temporary shadow directory and compiled there (dcc with the shadow dir first on the unit search path, in full project context). The real paths are not touched, no mtime is stamped and no .dcu is deleted -- so the IDE has nothing to notice and no "changed on disk" reload prompt can appear, let alone discard the edits being compiled. All dirty buffers are staged before any compile, so a dirty unit that uses another dirty unit sees its buffer too, not the stale disk copy.

The trade-off, stated rather than discovered later: only the dirty units are compiled, and their dependencies resolve through existing .dcu files, so an error in a saved unit newly caused by a dirty unit's interface change is not caught. ghost-check --in-place restores the historical whole-project behaviour, which briefly overwrites the real files and then restores them byte-for-byte with a crash-safe recovery journal. It is opt-in and marked dangerous; nothing in the plugin passes it.

Hover tooltip (v0.35): a 200ms timer shows Application.HintWindow with the diagnostic message when the cursor is stable for 600ms over a row that has a diagnostic. Caret-based (not pixel-precise). Toggle via Settings.

Code lens (v0.32): dim grey [N callers] text next to method declarations.

Structure form (v0.30): floating fsStayOnTop form showing the symbol tree of the active file, updated on view activation.

Find Usages form (v0.33): Ctrl+Alt+F prompts for a symbol name; shows callers grouped by file in a TTreeView; double-click jumps the editor.

Symbol Search form (v0.33): Ctrl+Alt+T debounced live search over the indexed symbol table; Enter navigates the editor to the selected location.

Native Tools > Options pages (v0.30, split into four in Batch B): four pages -- General / Indexer / Linter / Editor -- under Tools > Options > Third Party > drag-lint, each backed by INTAAddInOptions. All plugin settings (exe path, DB template, indexer/linter/editor toggles) live here -- edit a value, click OK, and the next hover / lint / index action picks it up (no IDE restart needed). Reopen them anytime via drag-lint > drag-lint Options.... drag-lint-lint.json also accepts "exceptions": { "unit": "MyApp.Exceptions" }. The unit key is optional and defaults to uExceptionDefinitions, so "exceptions": { } is enough to turn the feature on; omitting the BLOCK is what leaves it off. With it set, raise-bare-exception names the existing exception class whose message already covers each bare raise Exception.Create(...) -- matched on the normalized message text, so 'Invoice not found' and 'Invoice was not found' resolve to the same class -- or, when none exists, derives and names the class that SHOULD be added (EInvoiceNotFound), so the advice is something you can paste rather than something you still have to invent. Omit it and the rule's output is unchanged.

Per-project lint rules (drag-lint-lint.json) are edited from the drag-lint dock's Lint Options tab, reachable via Project Manager right-click a project > "drag-lint: Project Rules...". That tab now has a naming-convention preset selector (v0.97) -- pick Embarcadero (AValue params) or House (pMyParam / FMyField / TMyClass) to bulk-set the naming rules, or Custom to hand-tune them. The combo also lists your own saved presets (v0.99): tune the 8 naming values, click Save as... and give it a name, and it's added to the combo alongside the built-ins; Delete removes a saved preset (built-ins and Custom cannot be deleted). Saved presets persist per-project in drag-lint-lint.json under a top-level naming.presets array -- IDE-written only; the CLI does not yet read this key.

Architecture

drag-lint.exe
  |
  +-- CLI dispatch (DRagLint.CLI)
  |     |
  |     +-- Indexer (DRagLint.Core.Indexer)
  |     |     +-- tree-sitter-delphi13.dll  (Delphi 13 grammar)
  |     |     +-- tree-sitter-dfm.dll        (DFM grammar)
  |     |     +-- tree-sitter.dll            (libtree-sitter runtime)
  |     |     +-- SQLite storage
  |     |
  |     +-- Query / Surface / Impact / Slice
  |     +-- Lint (rule runner over .scm files)
  |     +-- Refactor (rename, doc stubs, test stubs, YADF format)
  |     +-- Compiler diagnostics (msbuild integration)
  |     +-- Workspace (multi-project shared DB)
  |
  +-- LSP server (DRagLint.LSP.Server) -- stdio JSON-RPC
  |
  +-- MCP server (DRagLint.MCP.Server) -- stdio JSON-RPC
  |
  +-- CLI context bundler (DRagLint.Context.Bundler)

Source layout (src\): core, parser, preprocess, index, storage, resolver,
analysis, lint, diagnostics, doc, refactor, report, query, context, cli, lsp,
mcp, ... -- the deps chart above shows how the linter sits between them.

dclDragLintWizard.bpl  (Delphi IDE plugin)
  +-- Wizard / menu / keystrokes / EditViewNotifier
  +-- LSP client -> drag-lint.exe lsp
  +-- DiagnosticCache -> in-editor markers + hover tooltip
  +-- CodeLensCache -> inline [N callers]
  +-- Structure / Refactor / Usages / SymbolSearch forms
  +-- Options (INTAAddInOptions, 4 pages: General/Indexer/Linter/Editor)
  +-- Project Manager menu (per-project "Project Rules..." -> Lint Options dock)

All three entry-points (CLI, LSP, MCP) call the same indexer, query, lint, and refactor engine. The IDE plugin is a thin wrapper around the LSP client plus direct CLI calls for features the LSP protocol doesn't cover.

Building from source

Prerequisites:

• RAD Studio 13 Florence (37.0) with Win64 target
• tree-sitter-delphi13 DLLs in third_party/dll-win64/ (Win64) / third_party/dll-win32/ (Win32)

Build the CLI (Win64 Debug -- the configuration that is deployed): run build\build_draglint_win64.bat. It loads rsvars.bat, builds src\cli\drag-lint.dproj, stages the tree-sitter companions beside the linked exe, syncs rules\ and deploys to third_party\dll-win64\. By hand:

call "C:\Program Files (x86)\Embarcadero\Studio\37.0\bin\rsvars.bat"
cd src\cli
msbuild drag-lint.dproj /p:Config=Debug /p:Platform=Win64

Build the IDE plugin:

msbuild src/delphi-plugin/dclDragLintWizard.dproj /p:Config=Debug /p:Platform=Win64

Run the test battery -- every run_*.ps1 under tests/, enumerated recursively (~10 min). The driver prints the number it found; that printed denominator is the count, not any figure written in a document. See tests/README.md for the definition and the rules that go with it:

pwsh -File tests\run_battery.ps1                    # the battery (default: everything)
pwsh -File tests\run_battery.ps1 -List              # enumerate only, print the denominator
pwsh -File tests\run_battery.ps1 -Include autodoc   # a subset, for a fast inner loop

Individual runners can be invoked directly, e.g.:

pwsh -File tests/autotest/run_smoke.ps1       # CLI + LSP server smoke
pwsh -File tests/autotest/run_formsmap.ps1    # forms-csv navigation-map smoke (fixture project)

Older batch harnesses in tests/fixtures/ (T61_hovertracker.bat, ...) are not part of the PowerShell battery.

Version history

See CHANGELOG.md for the detailed history. The current release is v1.31.7-alpha; development continues daily.

License

MIT. See LICENSE.