Documentation on colref

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

OS	x86_64 (Intel/AMD)	arm64
macOS	✓	✓ (Apple Silicon)
Linux	✓	✓
Windows	✓	—

pip / pipx (Python users)#

If you are working on a Django or Python project, install via pipx or pip. No Go installation required.

pipx install colref

Or with pip:

pip install colref

gem (Ruby users)#

If you are working on a Rails or Ruby project, install via gem. No Go installation required.

gem install colref

Homebrew (macOS and Linux)#

brew install shinagawa-web/tap/colref

If you prefer to tap first:

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started#

Django project#

The following example runs colref against wagtail, a popular Django CMS.

No references found:

$ colref check --orm django --model Page --field search_description
Scanning 932 files...

No references found for Page.search_description

 Verify manually before deleting.

References found:

$ colref check --orm django --model Page --field seo_title
Scanning 932 files...

References found for Page.seo_title

 wagtail/admin/tests/pages/test_create_page.py:1867 page.seo_title
 wagtail/admin/tests/pages/test_create_page.py:1892 page.seo_title

Rails project#

The following example runs colref against mastodon.

No references found:

$ colref check --orm rails --model Account --field sensitized_at
Scanning 1502 files...

No references found for Account.sensitized_at

 Verify manually before deleting.

References found:

Use cases

Mon, 01 Jan 0001 00:00:00 +0000

Use cases#

colref started as a deletion check — “is it safe to remove this column?” — but the underlying operation (find every reference to a specific field) is useful in more situations. This page documents the ones that come up regularly.

Schema cleanup#

Dead column detection#

Instead of starting from a specific deletion candidate, work backwards from the schema. Take a column from your migration history you don’t recognize, run colref, and see what comes back.

How it works

Mon, 01 Jan 0001 00:00:00 +0000

How it works#

Overview#

Reads your ORM schema source to extract the field list
Walks the codebase and parses each file into an AST
Reports every location where the field name appears as an attribute access (e.g. user.email)

AST parsing avoids false positives from comments, migration files, and unrelated string matches that plain grep would surface.

Schema extraction#

Django — colref walks the target directory to find models.py files. Each file is parsed and the field list for the requested model is extracted. If the same model name appears in multiple files, colref exits with an error.

Detection patterns

Mon, 01 Jan 0001 00:00:00 +0000

Detection patterns#

colref uses static AST analysis. It can only detect patterns where the field name appears as a literal in the source. References where the field name is constructed at runtime (e.g. getattr(obj, field_name)) are out of scope by design — static analysis cannot determine what string field_name holds at runtime.

This page documents exactly which patterns are and are not detected for each ORM. The ground truth is the golden test files in test_patterns/.

Limitations

Mon, 01 Jan 0001 00:00:00 +0000

Limitations#

colref uses static AST analysis and cannot detect every reference pattern. References where the field name is constructed at runtime (e.g. getattr(obj, field_name)) are out of scope by design.

**No references found ≠ safe to delete.** colref reports what static analysis can see. Dynamic references such as `getattr(obj, var)` are out of scope by design — treat zero results as a starting point for human review, not as proof the column is unused.

Django#

Detected: attribute access, getattr(obj, "field") / attrgetter("field") (labeled [getattr]), most ORM methods (filter, exclude, get, Q, values, only, defer, order_by, F, aggregates, etc.), and raw SQL strings.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Contributing#

Setup#

Prerequisites: Go 1.21+

git clone https://github.com/shinagawa-web/colref.git
cd colref
make install-hooks

make install-hooks installs a pre-push hook. Every time you run git push, it automatically runs:

Lint — golangci-lint
Unit tests + coverage — unit tests with 100% coverage enforcement (e2e excluded)
Benchmarks — runs benchmarks; compares against main if benchstat is installed

That’s it for most changes. Write code, push, the hook tells you if anything is broken.

Adding a new detection pattern#

Add the pattern to the relevant scanner in internal/
Add test cases to the pattern battery in test_patterns/
Run make update-golden to regenerate golden files
Run make test-e2e to verify the pattern battery passes (the pre-push hook does not run e2e)
Update Detection patterns with the new pattern
Push — the hook runs lint, unit tests, and benchmarks

Submitting changes#

Open an issue before starting non-trivial work
Keep PRs focused — one logical change per PR
All tests must pass; coverage must stay at 100%

Running checks manually#

If you need to run individual checks without pushing: