DEV Community: Kazu

How to safely remove a Django model field: finding every real reference before you delete

Kazu — Tue, 02 Jun 2026 13:00:00 +0000

Every Django project has at least one of these. A model with an old field that's probably not used anymore. "Probably" is the scary part. If something in production is still referencing it, deleting the column breaks the app. AttributeError, in production.

So you don't delete it. You want to, but you can't figure out how to check safely, so it just sits there. The column takes up space in every query. The field clutters the model definition. And it keeps sitting there, month after month, because the cost of confirming it's unused feels higher than the cost of leaving it.

Think about what happens when AttributeError: 'Article' object has no attribute 'summary' hits production. Users get 500 errors every time they open the page. Logs flood. Slack lights up. "Was it that deploy we just pushed?" Already considering a rollback. And the cause was deleting a field you thought was unused.

That's why nobody deletes anything. You can't be sure, so you don't. That's the right call. The problem is there was no way to get sure.

I tried the obvious thing: searching for the field name in VS Code. Hundreds of hits. I started opening them one by one and immediately noticed most aren't real references. File paths, comments, unrelated variable names. I searched for the .html field in one Django project and got 1,202 results. The actual code accessing that field: 10 results.

1,192 were noise. But you couldn't know that upfront.

Why search returns 1,202 hits

When you give up because there are too many results, that's not a failure on your part. VS Code search and grep just weren't built for this.

These tools answer "does this string appear anywhere in this file?" That's useful for a lot of things. But when you want to know "is this field actually referenced in code?", text search picks up way too much. The field name in a string literal, in a comment, as part of a filename: it all counts as a hit. Sorting through them is manual work.

Here's what those 1,202 results for .html broke down to:

Type	Count
File extensions (`layout.html`, etc.)	1,087
Unrelated strings	27
Comments	21
Other noise	57
Actual field accesses	10

You can't check 1,200 results. Giving up was the right call. The issue wasn't how you used the tool. You were using the wrong tool.

And .html isn't a special case. Say you want to delete a title field on an Article model. "title" shows up everywhere in a codebase: variable names, dictionary keys, comments, strings. Hundreds of results. Same problem.

Common field names are the worst. status, name, type, created_at — these appear in dozens of unrelated contexts throughout a typical Django project. The search that was supposed to answer a simple question becomes 40 minutes of opening files, closing files, and losing track of what you've already checked.

"I searched, couldn't check everything, left it alone." Most Django developers have been here. You want to delete it but can't. The check isn't impossible, it's just too expensive. So the field stays. They accumulate.

This compounds over time. A project that's two years old might have thirty fields that nobody's confident about. The developers who added them have moved on. The tickets that motivated them are closed. The tests, if they exist, pass regardless of whether the field is used. There's no mechanism forcing a cleanup, just the gradual intuition that the schema is getting harder to understand.

If you know regex, you might try narrowing it: grep -rn "\bhtml\b" --include="*.py" to limit to Python files. Still the same problem. "html" as a dictionary key, in a comment — it all still hits. "Python files only" and "actual field access" are completely different things.

The more you refine the regex, the more you start wondering whether the regex itself is missing something. You end up needing to verify the verification. The tool that was supposed to save you time has become another source of doubt.

There's also the psychological cost. You open VS Code, run the search, see 847 results for status, and your shoulders drop. You close the tab. You tell yourself you'll check it later. "Later" never comes. Nobody should have to hand-verify 847 results to answer a yes/no question.

When undeletable fields pile up, here's what actually happens.

The schema bloats. Ten, twenty unused columns accumulate. A new developer opens the model, scans the fields. "What's this one for?" They try to find out, can't, and decide not to touch it. Reasonable. But when that pattern repeats, you end up with an unspoken rule: don't touch this model.

Every migration feels slightly more risky. The unease builds until nobody touches it at all. Six months later, another developer thinks the same thing. The cycle repeats.

This is technical debt in the same way missing tests are. An unresolvable cost that accumulates. Development slows. Onboarding takes longer. Nobody intended this, but the project gets heavier over time.

This isn't a skills problem. The tool didn't exist yet.

Here's the situation I kept ending up in: I'd look at a field, feel like it was probably unused, open VS Code to check, get overwhelmed by results, close it, and go do something else. The field would still be there six months later. The next developer would go through the same loop. The field would still be there a year later.

At some point the schema becomes archaeology. Fields with names like legacy_content, old_slug, deprecated_flag: nobody knows what they do, nobody wants to touch them, and the project carries them forever. Every SELECT * is slightly slower. Every new developer's mental model of the data is slightly more confused.

The real cost is cognitive load. Every unused field is a small tax on everyone who reads the model. Multiply that by thirty fields and two years of new developers and you start to see why "we never clean up old fields" becomes an invisible drag on velocity.

How colref reads code structure instead of text

What you actually wanted to know was: where is obj.html referenced in code? colref returns exactly that. File paths and string contents ignored.

How does it tell the difference? Instead of treating code as a sequence of characters, it reads the code structure.

embed.html in Python means "read the html attribute of the embed object": a specific structure. "pages/publish.html" is string data, not an attribute access. Reading code structure makes that difference detectable. Only places written as object.field_name get picked up. The .html that appears inside a string is ignored.

If text search is like pressing Ctrl+F on a page, reading code structure is closer to a human reading through every line. Except it handles thousands of lines in an instant.

It scans Python code and returns only .field_name accesses, with file and line number.

Method	Hits (for `.html`)	What it sees
VS Code full-text search	3,534	All string matches
grep `\.html\b`	1,202	Word-boundary matches
colref	10	Actual field accesses only

3,534 or 1,202 becomes 10. Whether you can act on the results depends entirely on how many there are.

When you get 10 results: open each one. views.py:42 means go to that line and check whether obj.html is actually being accessed. Real reference — can't delete. Not a real reference — skip. Ten results takes 10–15 minutes.

A few common things you'll see when reviewing results: the field name appearing in a migration file (colref skips migrations, but if it didn't, this would be a false positive; the migration is just recording the history of the field's existence, not actively using it). You might also see test factories or fixtures that set the field value. Worth noting: if you delete the field and forget to update the factory, your test suite will break. That's not a reason not to delete, it's just something to clean up as part of the deletion.

When you get zero: you have a fact. "No references found in Python code." That's different from "I think it's probably unused." Move to the next step: checking getattr, templates, Admin, Forms, and Serializers. Zero from colref is the starting point, not the finish line.

The shift is from "check 1,200 things" to "check 10 things, then a handful of specific files." That's the difference between a task you'll defer indefinitely and one you'll do today.

For the technical details of how code structure is read, see ARCHITECTURE.md.

Installation

Install via pipx:

pipx install colref

Or with pip:

pip install colref

Specify the model name, field name, and your project directory:

colref check --orm django --model Embed --field html ./

Results come back as filename:line_number. Each one is something you can open directly. Ten results takes maybe ten minutes to verify. Nothing compared to scrolling through 1,202 results, losing your place, and giving up halfway through.

A note on model names: use the class name exactly as it appears in your models file, including capitalization. Embed, not embed or EMBED. Field names are case-sensitive too: html, not HTML. If you get zero results for a field you know is used, double-check the casing first.

The ./ at the end is the path to scan. You can point it at a specific app directory if you want to narrow it down, but pointing at the project root works fine and makes sure nothing gets missed.

What zero results doesn't cover

Zero results doesn't mean "safe to delete." It means "not found in Python code."

Dynamic access: getattr(obj, field_name) with the field name in a variable won't be detected. Check separately:

grep -rn "getattr" --include="*.py" ./ | grep your_field

Django templates: {{ page.html }} lives in .html files. colref only scans .py. Check templates separately:

grep -rn "your_field" --include="*.html" ./

Django Admin, Forms, and DRF Serializers: This is the easiest one to miss. None of these are detected:

# Django Admin
class ArticleAdmin(admin.ModelAdmin):
    list_display = ['title']
    list_filter = ['title']

# Django Forms
class ArticleForm(forms.ModelForm):
    class Meta:
        fields = ['title']

# DRF Serializer
class ArticleSerializer(serializers.ModelSerializer):
    class Meta:
        fields = ['title']

Determining which model the string 'title' in a list refers to requires tracing class inheritance, which colref doesn't handle yet. Check these separately:

grep -rn "your_field" --include="*.py" ./

This grep has the same noise problem as full-text search. Opening the Admin, Forms, and Serializer files directly is more reliable. In most projects there aren't many of them.

These are exactly the places a Django beginner might not think to check. You verify the views, the serializers feel obvious after you remember them, but Django Admin is easy to forget, especially if the admin configuration lives in a file you rarely open. I've seen list_display hold a reference to a field that had been "confirmed deleted" twice already. The admin file just wasn't in anyone's mental checklist.

Once you've checked all of the above and colref returns zero, that's a grounded deletion: confirmed in Python code, checked getattr, templates, Admin/Forms/Serializers. Not "I think it's probably fine."

Checking Admin/Forms/Serializers by eye sounds tedious, but in practice it takes a few minutes. These files tend to be organized by model. Open admin.py, search for the model name, check list_display and related attributes. Open serializers.py, find the relevant serializer, check fields. Open forms.py if you have one. It's not a grep problem, it's an "open three files and look" problem. That's manageable even without a tool.

colref (Python attribute accesses) + grep (dynamic patterns and templates) + manual check (Admin/Forms/Serializers) covers the vast majority of real-world Django codebases. There are edge cases colref doesn't handle yet; the Detection Patterns docs list them. For most projects, this three-part check is enough to move from "I think it's probably unused" to "I have confirmed it's unused."

The five-step procedure

# 1. Check for field accesses in Python code
colref check --orm django --model YourModel --field your_field ./

# 2. Check for dynamic access
grep -rn "getattr" --include="*.py" ./ | grep your_field

# 3. Check templates
grep -rn "your_field" --include="*.html" ./

# 4. Delete the field and generate the migration
python manage.py makemigrations --name remove_your_field

# 5. Apply to the schema
python manage.py migrate

Steps 2 and 3 are still grep — colref doesn't solve everything. But step 1 cuts 1,202 results down to 10. The "too many results to check, left it alone" situation: this is the one place that changes.

The difference between "probably unused, I think" and "zero results in Python code, no getattr, nothing in templates" is real. If something breaks in production, knowing what you checked tells you exactly where to look. You know the cause came from outside your checked scope: a dynamic reference, a template, a pattern colref doesn't handle yet. The cause is narrowed. Grounded deletion makes debugging faster when things go wrong.

One more thing about step 4 and 5: don't skip makemigrations --name. Giving the migration a descriptive name like remove_summary_field makes the history readable. Six months from now, someone scanning migration filenames can see what changed and when without opening every file.

Also: run the migration locally and make sure your test suite passes before deploying. When you're confident about a deletion it's tempting to skip the verification. Don't. If a test factory is still setting the deleted field, the tests will catch it before production does.

The whole process — run colref, check the checklist, generate the migration, run tests locally, deploy — takes maybe 30 minutes for a field that's actually unused. Compare that to leaving the field there indefinitely because you couldn't confirm it was safe to remove.

First run: try a field you know is used

If you don't have a candidate field in mind, try a field you know is used, something like title on Article:

colref check --orm django --model Article --field title ./

If title is in use, you'll get multiple results with file and line number:

app/views.py:42
app/serializers.py:18
app/templates/article_detail.py:11

Seeing what a real result looks like makes it easier to judge zero results later. Then try a field you've been wondering about. Close to zero? Move to steps 2 and 3.

From installation to first run: under five minutes. No need to read the README first. Running it is faster than reading about it.

What do you do when you get 3 results? Open all three. For each one: is this code still running in production? If a reference is inside a function that's clearly dead code, something wrapped in if False or commented out, it doesn't count. If it's live code, the field is still in use. But 3 results is a manageable number. You can make that judgment call.

What if you get 0 results? Don't stop there. Run steps 2 and 3. Zero from colref, zero from getattr grep, zero from template grep: that's three independent checks. At that point, also check your Admin, Forms, and Serializer files by eye. If all of that is clear, you have something solid to stand on.

Even without a deletion candidate right now, colref is useful for routine schema review. Scan migration history, spot something that looks unused, run colref. Zero results? It goes on the deletion candidate list. "Probably unused" becomes "not referenced in Python code" in 30 seconds.

I do this periodically on projects I maintain. Every few months I scan the migration history for fields I don't recognize, run colref on them, and build a short list. It takes maybe 20 minutes and usually turns up one or two candidates worth investigating further. Some end up staying because they're used in ways colref doesn't detect yet. But a few always turn out to be genuinely gone: references removed over time, nobody noticed, nobody cleaned it up. Those get deleted.

colref is still in development. If something doesn't work or you get unexpected results, open an issue at github.com/shinagawa-web/colref. Real usage feedback is what shapes the priorities. A bug report with a concrete example is more useful than ten feature requests.

colref currently supports Django and Rails. For the roadmap, see issue #74.

If you find a field that colref misses, something it should have flagged but didn't, that's especially useful to report. The detection gap around Admin, Forms, and Serializers is a known limitation, but there may be patterns in your codebase that nobody's encountered yet. The tool gets better with more real-world cases.

How many fields are you sitting on that you haven't been able to delete?

"How I Cut My Go Markdown Linter's Benchmark by 81%"

Kazu — Tue, 26 May 2026 13:00:00 +0000

When I started optimizing gomarklint, I had no benchmarks. I had unit tests. I had coverage. But I had no idea what the linter actually cost to run on a real document.

Here's what I found, what I changed, and what I'd do differently next time.

What is gomarklint?

gomarklint is a Go-based CLI Markdown linter I've been building as an open-source project. The pitch: catch broken links before your readers do, keep your Markdown clean, single binary, no Node.js required.

The main alternative most teams reach for is markdownlint, which works well but requires a Node.js runtime. For Go projects running in a lean CI environment, pulling in Node.js just to lint Markdown felt like the wrong tradeoff. gomarklint ships as a standalone binary installable via Homebrew, npm, or go install, and integrates with GitHub Actions and pre-commit out of the box.

The rule set covers around 25 checks: structural rules like heading-level (no H4 appearing under H2 without an H3 in between), content rules like no-bare-urls and fenced-code-language, and link validation including internal anchor checking. Each rule emits diagnostics with file path, line number, and severity — error causes a non-zero exit, making it safe as a CI gate.

Internally, each rule is a function that receives the full file content as a slice of lines and returns a slice of violations. No shared parse tree, no AST, just functions over strings. That made it easy to add rules quickly.

The current release processes 100,000+ lines in under 170ms. A typical 200-line README lints in under 0.2 ms across all rules, and a large documentation site with hundreds of files fits in a CI step nobody notices. Getting there required 20 PRs over three weeks, each measured before it merged.

The Starting Point: No Visibility

gomarklint's rules like heading-level, no-bare-urls, fenced-code-language, and around 25 others each receive the full file content split into lines and return a slice of violations. Rules run independently, no shared parse tree, no AST, just functions over strings.

That architecture is easy to extend. But every rule doing anything non-trivial had to solve the same problem on its own: "is this line inside a code block?" Headings inside fenced blocks aren't real headings. URLs inside fenced blocks aren't real URLs. Every rule that cared had to figure it out independently.

The solution that grew organically was a shared utility called GetCodeBlockLineRanges. It scanned the entire document, built a list of [start, end] line ranges for every fenced block, and returned them. Any rule could then call isInCodeBlock(lineNumber, ranges) to check membership via a linear search.

I didn't notice this was a problem because I never measured it.

Step 1: Build a Benchmark You Can Trust

Before optimizing anything, I needed a benchmark I could actually rely on. The existing per-rule _bench_test.go files were isolated and not included in CI comparisons, so they gave no signal about end-to-end cost.

I rewrote the benchmark around a single generateComplexMarkdown(n int) function that produces a realistic n-section document (headings, paragraphs, lists, fenced code blocks, images, links) exercising every rule's scan path without producing any violations:

func writeIntro(sb *strings.Builder) {
    sb.WriteString("# Main Title\n\n")
    sb.WriteString("This is the introduction to the document.\n\n")
}

func writeHeading(sb *strings.Builder, i int) {
    fmt.Fprintf(sb, "## Section %d\n\n", i)
}

func writeParagraph(sb *strings.Builder) {
    sb.WriteString("This section contains *important* information. ")
    sb.WriteString("Here are some **key** details that you should know about.\n\n")
}

func writeList(sb *strings.Builder) {
    sb.WriteString("Key points:\n\n")
    sb.WriteString("- First important point\n")
    sb.WriteString("- Second critical detail\n")
    sb.WriteString("- Third consideration\n\n")
}

func writeCodeBlock(sb *strings.Builder) {
    sb.WriteString("```

go\n")
    sb.WriteString("func example() error {\n")
    sb.WriteString("    return nil\n")
    sb.WriteString("}\n")
    sb.WriteString("

```\n\n")
}

func writeLinks(sb *strings.Builder, i int) {
    sb.WriteString("Useful resources:\n\n")
    fmt.Fprintf(sb, "- [Documentation](https://example.com/docs/%d)\n", i)
    fmt.Fprintf(sb, "- [GitHub](https://github.com/project/%d)\n", i)
    sb.WriteString("\n")
}

func writeImage(sb *strings.Builder, i int) {
    fmt.Fprintf(sb, "![Diagram %d](diagram%d.png)\n\n", i, i)
}

func writeSubsection(sb *strings.Builder, i int) {
    fmt.Fprintf(sb, "### Subsection %d.1\n\n", i)
    sb.WriteString("More detailed information goes here.\n\n")
}

func generateComplexMarkdown(sections int) string {
    var sb strings.Builder
    writeIntro(&sb)
    for i := 1; i <= sections; i++ {
        writeHeading(&sb, i)
        writeParagraph(&sb)
        writeList(&sb)
        if i%2 == 0 {
            writeCodeBlock(&sb)
        }
        if i%3 == 0 {
            writeLinks(&sb, i)
        }
        if i%4 == 0 {
            writeImage(&sb, i)
        }
        writeSubsection(&sb, i)
    }
    result := sb.String()
    return result[:len(result)-1]
}

That last constraint — zero violations — matters. A benchmark that triggers violations measures error-reporting cost, not scanning cost. I added a guard test to enforce it:

func TestBenchmarkContentIsViolationFree(t *testing.T) {
    content := generateComplexMarkdown(1000)
    results, err := lint.LintContent(content, benchmarkConfig())
    require.NoError(t, err)
    assert.Empty(t, results)
}

This test runs in CI on every PR in the series. If anyone accidentally adds a violation to the benchmark content, the build breaks before the numbers become meaningless.

The benchmark also pays forward. Now that it runs on every PR, any new rule added to gomarklint gets automatically checked for performance regression before it merges. If a new no-trailing-spaces rule adds 15% to the geomean, benchstat surfaces that number in the PR diff — before it ships, not after. Without a benchmark in CI, performance regressions from new features are invisible until someone notices the linter "feels slower" on a large repo.

Step 2: Profile Before Touching Anything

With the benchmark in place, I ran a CPU and allocation profile against the 1000-section document:

go test -bench=BenchmarkFullLinting -benchtime=5s \
    -cpuprofile=cpu.prof -memprofile=mem.prof ./cmd/
go tool pprof -top cpu.prof

The top result:

Showing top 5 nodes out of 42
      flat  flat%   sum%        cum   cum%
   6.32s  63.72% 63.72%      6.32s 63.72%  isInCodeBlock
   0.89s   8.97% 72.69%      0.89s  8.97%  strings.TrimSpace
   0.54s   5.44% 78.14%      0.54s  5.44%  regexp.(*Regexp).FindStringSubmatch
   ...

isInCodeBlock was a shared helper called from multiple rules. Each call invoked GetCodeBlockLineRanges, which allocated a [][2]int slice by scanning the entire document to find fence boundaries, then performed a linear search through that slice to answer one question: "is line N inside a code block?"

That's O(n × k) per rule per line, where n is the number of lines and k is the number of code blocks. In a document with 6 rules calling it and 50 code blocks, every line triggered 6 linear searches over 50 ranges. The cost multiplied silently across every rule that wanted to skip code block content.

The allocation profile added a second finding: CheckHeadingLevels was calling regexp.MustCompile(atxHeadingPattern) inside the function body on every invocation — not once at package init. That single oversight was allocating ~16 MB of heap per benchmark run and showed up clearly in -memprofile output.

Step 3: Fix the Biggest Problem First

Both issues were in the heading-level rule. I fixed them together in PR #182:

Before:

func CheckHeadingLevels(filename string, lines []string, offset int, minLevel int) []LintError {
    var errs []LintError
    prevLevel := 0
    headingRegex := regexp.MustCompile(`^(#{1,6})\s+`) // compiled on every call
    codeBlockRanges, _ := GetCodeBlockLineRanges(lines) // O(n) alloc

    for i, line := range lines {
        if isInCodeBlock(i+1, codeBlockRanges) { // O(k) linear search per line
            continue
        }
        matches := headingRegex.FindStringSubmatch(line)
        if matches != nil {
            currentLevel := len(matches[1])
            // ... violation checks
            prevLevel = currentLevel
        }
    }
    return errs
}

After:

// atxHeadingLevel returns the heading level (1–6) or 0.
// Pure byte scan — no regex, no allocation.
func atxHeadingLevel(line string) int {
    level := 0
    for level < len(line) && line[level] == '#' {
        level++
    }
    if level == 0 || level > 6 {
        return 0
    }
    if level == len(line) || line[level] == ' ' || line[level] == '\t' {
        return level
    }
    return 0
}

func CheckHeadingLevels(filename string, lines []string, offset int, minLevel int) []LintError {
    var errs []LintError
    prevLevel := 0
    inCodeBlock := false
    var fenceMarker string

    for i, line := range lines {
        if len(line) == 0 {
            continue
        }
        first := firstNonSpaceByte(line)

        // Inline fence tracking — no allocation, no O(n×k) lookup.
        if inCodeBlock {
            if first == fenceMarker[0] {
                trimmed := strings.TrimSpace(line)
                if IsClosingFence(trimmed, fenceMarker) {
                    inCodeBlock = false
                    fenceMarker = ""
                }
            }
            continue
        }

        if first != '#' && first != '`' && first != '~' {
            continue
        }

        trimmed := strings.TrimSpace(line)
        if marker := openingFenceMarker(trimmed); marker != "" {
            inCodeBlock = true
            fenceMarker = marker
            continue
        }
        if first != '#' {
            continue
        }

        currentLevel := atxHeadingLevel(trimmed)
        if currentLevel == 0 {
            continue
        }
        // ... violation checks
        prevLevel = currentLevel
    }
    return errs
}

The result on CI (AMD EPYC, 1000-section document):

metric	before	after	delta
time/op (geomean)	52.55 ms	14.78 ms	−72%
memory/op	2.108 Mi	1.912 Mi	−9%
allocs/op	9,225	4,677	−49%

One PR. 72% of the time gone.

Step 4: Turn the Pattern Into a System

The heading-level fix revealed a reusable pattern: the firstNonSpaceByte prefilter. Most rules only care about lines starting with a specific byte. A heading starts with #. A fenced code block starts with ` or ~. A hard tab starts with \t.

Reading the first non-whitespace byte costs almost nothing — one loop over leading spaces, then a byte read. Calling strings.TrimSpace on every line is not free, especially when 95% of lines would be skipped anyway.

I applied this prefilter across 14 more rules over 14 subsequent PRs:

func firstNonSpaceByte(s string) byte {
    for i := 0; i < len(s); i++ {
        c := s[i]
        if c != ' ' && c != '\t' && c != '\r' && c != '\n' {
            return c
        }
    }
    return 0
}

Each individual PR produced a modest gain — 3% to 15% per rule. But they compounded:

PR	Rule	time delta
#193	no-bare-urls	−15.5%
#195	no-emphasis-as-heading	−8.8%
#190	empty-alt-text	−6.4%
#194	duplicate-heading	−3.0% (+ −12.6% memory)
#192	no-empty-links	−2.8%

The Final Numbers

Starting from the benchmark baseline after the scaffolding work, to the last PR in the series:

metric	start	end	improvement
time/op (geomean)	74.37 ms	13.88 ms	−81%
memory/op	2.221 Mi	1.654 Mi	−25%
allocs/op	9,533	4,510	−53%

Twenty PRs over three weeks. Each one measured, each one merged only after the CI benchmark comparison confirmed no regression.

What I'd Do Differently

Profile before writing a single optimization. I got lucky that the biggest problem (isInCodeBlock at 63%) was immediately obvious. In a more complex codebase, guessing the hotspot first would have sent me optimizing rules that contributed 0.5% of total CPU while the real bottleneck sat untouched. The 20-minute setup cost of a proper benchmark pays back on the first targeted fix.

Treat the benchmark content as a first-class artifact. A benchmark that produces violations is measuring error-reporting cost, not scanning cost. A benchmark whose content drifts rule-by-rule becomes impossible to interpret. The TestBenchmarkContentIsViolationFree guard test caught three cases mid-series where a content addition accidentally triggered a violation. Without it, I would have been optimizing against corrupted numbers and wondering why the geomean kept moving.

Two PRs in this series landed within measurement noise. One was closed without merging. Having numbers in each PR body made that obvious: the CI benchstat output showed ~ (p=0.485) and there was nothing to argue about. A single "performance" PR with twenty changes mixed together would have buried those non-results.

Writing before/after benchmark numbers in every PR description did something I didn't expect: it made the series reviewable after the fact. Looking back at 20 PRs, I can tell exactly which optimization accounted for which fraction of the total gain. The firstNonSpaceByte prefilter was worth applying to 14 rules because I could see, rule by rule, that it kept working. That's how I found the pattern in the first place.

Try It

gomarklint is open source: github.com/shinagawa-web/gomarklint. The entire optimization series is tracked under issue #146, with each PR linking back to it and carrying its own before/after benchmark numbers.

If you're running a Go linter or any line-by-line text processor, these two patterns are worth trying before anything fancier: inline fence tracking instead of pre-computed ranges, and a first-byte prefilter before any string work. Zero dependencies, easy to test, and between them they accounted for almost all of the 81%.

7 CI Checks I Added After Breaking My Own Go OSS Project

Kazu — Wed, 20 May 2026 13:02:00 +0000

Three days after a release, an issue arrived: "The install command doesn't work." A module path change in that release had broken go install. My test suite had passed. My local build had passed. CI had passed. The binary was broken anyway, and I found out from a user report, not from a check.

That was the first gap. There were more: no performance baseline, so I wouldn't know when a new rule was 3x slower. No way to verify whether the GitHub Action I'd published actually ran correctly in a user's workflow. Each gap seemed minor on its own. Together, they meant I was shipping changes I couldn't fully verify.

This is the CI harness I assembled over 11 months: 7 checks, each added after a specific failure made the gap impossible to ignore.

The Harness at a Glance

Check	Added	What it prevents
Tests & coverage	2025-06	Regressions going unnoticed
Installability	2025-07	A broken binary reaching users
Static analysis	2026-01	Code quality regressions, potential bugs
PR label enforcement	2026-02	Incomplete release notes
Benchmark comparison	2026-02	Unnoticed performance regressions
Action smoke test	2026-05	Breaking changes to the published Action
Invisible Unicode detection	2026-05	Zero-width characters sneaking into source

1. The Coverage Gate: A Tripwire for Vanishing Tests (June 2025)

Purpose: run the full test suite on every PR and enforce a minimum coverage threshold.

"Run tests" is not the same as "enforce coverage." A PR that deletes test helpers or bypasses a code path drops the coverage number silently if you're only running go test without tracking the percentage. The threshold forces the question every time: coverage falls below the minimum, CI fails.

- name: Test with coverage
  run: |
    go test ./... -coverprofile=coverage.out
    go tool cover -func=coverage.out | \
      awk '/total:/ { pct=$3+0; if (pct < 80) { print "Coverage " $3 " is below 80%"; exit 1 } }'

What it prevents: regressions going unnoticed. The test suite catches broken behavior; the coverage gate catches the removal of the tests that would have caught it.

2. The Install Canary: Proving Users Can Still Get In (July 2025)

Purpose: verify that go install github.com/shinagawa-web/gomarklint@latest still works after every push to main.

This sounds obvious until it breaks. Module path changes, missing main packages, incorrect version tags: any of these will produce an install error that a passing test suite won't catch. The check runs go install on the actual published module (not the local source) in a clean environment. If it fails on a PR, the PR cannot merge; if it catches something on main, main goes red until it's resolved.

What it prevents: releasing a binary that users cannot install. That's a silent failure that lands in your issue tracker three days later when someone reports "the install command doesn't work."

3. The Review Inliner: Surfacing Lint Where You Read Code (January 2026)

Purpose: surface lint errors inline on PRs rather than as a buried log line.

reviewdog runs golangci-lint and posts results as PR review comments on the specific lines that triggered the warning. The feedback loop matters: a lint error posted as a CI log line gets skimmed; a review comment on the line of code gets read.

What it prevents: code quality regressions that tests don't exercise. The enabled linters target cyclomatic complexity (gocyclo), cognitive complexity (gocognit), function length (funlen), unchecked errors (errcheck), and suspicious constructs (staticcheck, govet). In practice the complexity linters fire most often — a function that passes every test can still be flagged for being too difficult to reason about.

4. The Changelog Guard: Blocking the Invisible PR (February 2026)

Purpose: auto-assign labels from Conventional Commits prefixes (feat:, fix:, chore:, etc.) and block merging any PR that carries no label.

Release notes in gomarklint are generated from PR labels. A PR merged without a label is invisible in the changelog. The enforcement step runs on pull_request events and fails if no label is present after the auto-assignment pass.

What it prevents: gaps in release notes. If the changelog can't be trusted, the project's version history can't be trusted either.

5. The Performance Witness: Catching the 3x Slowdown That Passes Tests (February 2026)

Purpose: run the full benchmark suite on both the PR branch and main, then post the delta as a PR comment.

The comment uses a three-state indicator: ✅ if the PR branch is no slower than main, ⚠️ if it is 10–50% slower, and ❌ if it is more than 50% slower. This check does not hard-fail CI: it posts a warning comment and lets the reviewer decide whether to proceed.

Trap: hard-failing on performance regressions trains reviewers to ignore the check. Early versions did fail CI when the threshold was crossed. The problem is runner variance: GitHub Actions runners share hardware, and a run on a busy runner is measurably slower than a previous run on a quiet one. That variance exceeded the threshold I needed to catch real regressions. After two false positives in a row, I started dismissing the failures on sight. The fix was to post the data without blocking: the comparison still runs, the comment still appears, but the merge decision stays with the reviewer.

What it prevents: performance regressions that pass every unit test. A new rule implementation that is correct but 3x slower will show up immediately. The decision to merge or revise is still human, but the data is always there.

6. The Wrapper Probe: Testing What Users Actually Run (May 2026)

Purpose: actually run the published GitHub Action against a real Markdown fixture on every relevant change to the Action definition or the underlying binary.

A GitHub Action can have valid YAML and a valid binary and still fail in ways that neither validates: wrong input names, incorrect default values, broken entrypoint paths. The smoke test checks out the Action from the PR branch and runs it end-to-end in CI against a controlled fixture directory.

What it prevents: breaking changes to the Action going unnoticed. Users of the Action would hit the failure; I would not, because my own tests don't exercise the Action wrapper layer.

7. The Hidden-Character Scanner: Defending Against Code You Cannot See (May 2026)

Purpose: defend against supply-chain attacks that hide malicious code inside invisible Unicode characters embedded in .go and .sh files.

In March 2026, the GlassWorm attack was disclosed. It works by embedding malicious code inside Unicode variation selector characters (U+E0100–U+E01EF) — characters invisible in editors, invisible in GitHub's diff view, invisible to standard code review. A single visible source line can carry approximately 18,000 hidden lines of code. Over 151 GitHub repositories and 72 Open VSX extensions were confirmed compromised before the attack was publicly documented.

The check greps for the specific character ranges used in the attack on every push and PR touching Go or shell files:

#!/bin/sh
grep -rPn \
  '[\x{200B}\x{200C}\x{200D}\x{FEFF}]|[\x{E0100}-\x{E01EF}]' \
  --include='*.go' --include='*.sh' . && {
    echo "Invisible Unicode characters detected"
    exit 1
  }
# grep exits 1 when no match (success), 0 when match found (failure), 2 on error
[ $? -eq 2 ] && { echo "grep error: scan failed"; exit 2; }
exit 0

The job fails with a non-zero exit code on any match, and with a distinct exit code on grep errors, so a scan failure cannot silently bypass the check.

What it prevents: a contaminated contribution entering the codebase undetected. The threat isn't accidental encoding corruption — it's deliberate concealment. Standard diff review offers no protection against it.

The Local Mirror: Catching Failures Before They Become PRs

The CI harness runs on GitHub Actions, which means feedback arrives after a push. A PR that fails lint or drops below the coverage threshold wastes a round-trip: push, wait, read the failure, fix locally, push again.

The pre-push hook is the local mirror of the harness. It runs golangci-lint, the unit test suite, and E2E tests before git push completes. If any check fails, the push is aborted. The PR never gets opened in a broken state.

#!/bin/sh
set -e
golangci-lint run ./...
go test ./...
go test -tags e2e ./...

The hook can be bypassed with git push --no-verify for genuine emergencies, but that's an explicit override, not the default path.

How the Harness Grew

I started with tests only, because that's where every project should start. Each subsequent check was added after a specific failure: the installability check came after a broken binary slipped to users; benchmarks came after a performance regression went unnoticed through two releases; the Action smoke test came after I realized I had been testing the binary but not the wrapper that users actually invoke.

The harness wasn't designed. It was accumulated. Each new check costs very little once the infrastructure is in place (a new job, an existing action, a few lines of shell), and the protection adds up.

One gap it still doesn't close: the pre-push hook is opt-in and only runs on my machine. A new contributor submitting their first PR gets CI feedback rather than local feedback: the round-trip I eliminated for myself still exists for everyone else.

What Does Your Harness Look Like?

This is how I maintain quality in gomarklint: automated gates that catch categories of failure I've already experienced, running on every push and PR without my involvement.

What does your CI harness include? Have you added checks that go beyond tests and lint, things like installability verification, Action smoke tests, or performance baselines? I'm curious what gaps yours was built to close.

grep Said 1,202. The Real Answer Was 10. — Introducing colref

Kazu — Tue, 12 May 2026 23:14:48 +0000

When deleting a database column, I ran grep "\.html\b" across a Django codebase to check for references. It returned 1,202 hits. The column had 10 actual attribute-access references. The other 1,192 were template paths, HTML file extensions in strings, comments, and import fragments — none of which mattered.

Filtering 1,200+ grep hits by hand every time you drop a column isn't a workflow, it's a chore I kept putting off.

So I built colref — a CLI tool that uses AST parsing to find only the attribute-access references to a model field, filtering out everything grep can't.

The Haystack: One Field Name, Ten Thousand Strings

grep treats your codebase as a flat stream of characters. .html matches everything containing those five characters — in code, in strings, in comments, in template paths.

grep -rn "\.html\b" --include="*.py" wagtail/
# 1,202 hits

The 1,192 noise hits in Wagtail break down like this:

Category	Count	Example
HTML file extensions in strings	1,087	`template_name = "pages/publish.html"`
Other string literals	27	`format_html(...)`
Comments	21	`# See docs/settings.html#...`
Other	57	`template_html = base + ".html"`

The same problem appears across every project and every field name. On Mastodon, .domain gives 269 hits; 175 are spec files and SQL heredocs. On Zulip, .name for Stream returns 1,347 hits; 10 are noise.

grep matches characters. It cannot distinguish obj.html from publish.html in a path string.

The Blueprint: AST as a Code Structure Map

colref parses your source files into an Abstract Syntax Tree and walks only the attribute-access nodes — the ones that represent obj.field in running code.

colref check --orm django --model Embed --field html ./wagtail/
# 10 hits

String literals, comments, Django template strings, SQL heredocs, and docstring-embedded code examples are all invisible to the AST walker.

Approach	Hits	What's included
`grep "html"`	3,534	Everything
`grep "\.html\b"`	1,202	File extensions, strings, comments
colref	10	Attribute accesses only

The AST sees obj.html as an attribute access and "publish.html" as a string literal — two different node types.

The Anchor: ORM Schema as a Disambiguation Layer

AST parsing alone is not enough. obj.name might be Stream.name, User.name, or a method call with no relation to your database. colref resolves this by reading the ORM schema first.

For Django, it parses models.py files to find which fields are declared on which model. For Rails, it reads db/schema.rb (or replays migrations if schema.rb is absent). Only references to a field that actually exists on the target model are reported.

colref check --orm rails --model Account --field username ./mastodon/
# 40 hits  (grep \.username\b gives 196)

Without the schema, colref would have no way to distinguish account.username from config.username in a settings file.

The "Implicit Self" Trap

The most common false positive colref produces comes from bare method calls with no explicit receiver:

# Forem — app/views/articles/show.html.erb
<% title "Welcome!" %>
<% title @article.title_with_query_preamble(user_signed_in?) %>

When the field name matches a helper method called on implicit self, colref currently includes it. For the Forem title field, this produced 50 false positives out of 340 reported hits.

The fix is a receiver-aware pass: treat a call node as a candidate only when it has an explicit receiver. That work is on the roadmap.

Verified Against 15+ Real-World Projects

colref has been tested against real OSS codebases across both ORMs:

Django (10 projects: Wagtail, Saleor, Zulip, NetBox, BookWyrm, Misago, django-wiki, and others):

Zero false negatives across all tested model/field pairs
Zero false positives after fixing the models/ package scanner (#65)
Remaining gap: abstract_models.py patterns (django-oscar style) not yet supported

Rails (Mastodon, Forem, Fat Free CRM, Lobsters, Publify, mutual-aid, and others):

Same precision/recall profile
Projects without a committed db/schema.rb now supported via migration replay

Detailed results with TP/FN/FP breakdowns per project are in the GitHub issues.

What's Next

Django and Rails are the first two ORMs. The roadmap includes:

Laravel (PHP) — migration-based schema, Eloquent attribute access
Spring Boot / JPA (Java) — entity annotations, JPA field resolution
Prisma (TypeScript/Node) — schema.prisma as the source of truth

If you use one of these and want to help shape the implementation, the issues are open.

Where it stands

colref filters out the text noise that makes grep unreliable for column reference checks. On Wagtail, Mastodon, and Zulip the signal-to-noise ratio went from roughly 1% to 100%, and I now reach for it before grep when removing a column.

The implicit-self false positives are still there, abstract_models.py isn't handled, and 15 projects is a small slice of the Django and Rails worlds.

If you maintain a Django or Rails codebase, I'd like to know how colref does on your models — especially the cases where it misses something obvious or reports a hit that's clearly noise.

Try it and open an issue if it breaks.

go install github.com/shinagawa-web/colref@latest
colref check --orm django --model YourModel --field your_field ./

👉 github.com/shinagawa-web/colref

Beyond Lines: Announcing "gosemdiff" – A Logic-Aware Diff Tool for Go

Kazu — Thu, 30 Apr 2026 05:57:51 +0000

Today marks a personal milestone: I have finally finished a massive, six-month-long refactoring of my other project, gomarklint.

After spending half a year staring at Go code structures and AST nodes, I realized something painful. Our current tools are still "dumb" when it comes to understanding the intent of our changes. We are still reviewing code line-by-line, even though we think in structures and logic.

That's why I'm excited to announce my next OSS project: gosemdiff.

The Problem with Current Solutions (Including AI)

We now have AI tools that can summarize Pull Requests for us. They are helpful, but let's be honest: AI summaries are often "vibes-based." An AI might say, "This PR refactors the processing logic," but it can't mathematically guarantee that the logic remains unchanged. AI can hallucinate, overlook edge cases, or fail to distinguish between a variable rename and a subtle logic bug.

As engineers, we don't need a "guess." We need proof.

Standard git diff treats code as text. But code is not just text; it's a tree of logic.

The Solution: gosemdiff

gosemdiff is a semantic diff tool designed specifically for Go. Instead of comparing lines, it parses your source code into an Abstract Syntax Tree (AST) and compares the underlying structures.

The goal is to provide a "Truth Machine" for your Pull Requests.

Key Concepts:

Semantic Labeling: Automatically identify changes as MOVE, RENAME, or LOGIC CHANGE.
Logic Integrity: Prove that a refactor hasn't changed the execution flow by comparing normalized AST hashes.
Test-Gap Detection: Alert you if a logic change was made without any corresponding updates to your *_test.go files.
Zero-Noise Mode: Completely ignore comments, formatting, and import ordering.

The Roadmap to v1.0.0

I've laid out an ambitious roadmap in the repository, moving from basic function inventorying to a fully integrated GitHub Action.

The ultimate goal? A CI bot that tells your reviewers:

"This PR is 90% refactoring. Logic changes detected in only 2 files. One logic change is missing a unit test."

I Need Your Feedback!

I'm taking a short break to recharge after the gomarklint marathon, and full-scale development on gosemdiff will kick off in about two months.

However, the "Grand Vision" is already live in the README. I want to build this for the community, so I need your input:

What kind of diffs annoy you the most during code reviews?
What "semantic" features would make your life easier?
What's your dream CI summary?

Please check out the repo and leave your ideas, feature requests, or "what-ifs" in the GitHub Issues!

👉 gosemdiff

Let's make code reviews about logic again, not just lines.

How I Built Inline Disable Comments for a Go Markdown Linter

Kazu — Tue, 28 Apr 2026 13:00:00 +0000

If you've used ESLint, you've probably written // eslint-disable-next-line at least once. It's one of those small features that makes a linter actually usable in the real world — because no rule is right 100% of the time.

I recently built the same feature for gomarklint, a fast Markdown linter written in Go. This post walks through the design decisions and implementation details.

The Problem

gomarklint enforces rules like "no bare URLs," "headings must not skip levels," and "lines must not exceed 120 characters." These rules are useful globally, but sometimes a specific line is legitimately different:

A changelog entry that intentionally contains a bare URL
A generated code block where line length doesn't matter
A one-off exception that would be wrong to suppress project-wide

What we want is a way to suppress violations inline, scoped to exactly the lines that need it — just like markdownlint does with HTML comments:

<!-- markdownlint-disable MD013 -->
A very long line that is intentionally long...
<!-- markdownlint-enable MD013 -->

gomarklint uses the same HTML comment approach, with its own prefix:

<!-- gomarklint-disable MD013 -->

What We Need to Support

There are four directive types, covering both block-level and per-line use cases:

Directive	Scope
`<!-- gomarklint-disable -->`	Disables all rules from this line onward
`<!-- gomarklint-disable MD013 -->`	Disables specific rules from this line onward
`<!-- gomarklint-enable -->`	Re-enables all rules (ends a block disable)
`<!-- gomarklint-enable MD013 -->`	Re-enables specific rules
`<!-- gomarklint-disable-line -->`	Disables all rules on this line only
`<!-- gomarklint-disable-line MD013 -->`	Disables specific rules on this line only
`<!-- gomarklint-disable-next-line -->`	Disables all rules on the next line only
`<!-- gomarklint-disable-next-line MD013 -->`	Disables specific rules on the next line only

The Data Model

The core challenge is representing "which rules are disabled on line N" efficiently. I ended up with three types.

`lineDisable`

This struct describes the disable state for a single line:

type lineDisable struct {
    allDisabled bool
    names       []string
}

The interesting part is that names plays two different roles depending on allDisabled:

If allDisabled is false: names is the list of disabled rules
If allDisabled is true: names is the list of exceptions (rules that are not suppressed)

This lets the same struct handle both "disable everything" and "disable only MD013" without needing separate types. The isRuleDisabled method encodes this logic:

func (ld lineDisable) isRuleDisabled(ruleName string) bool {
    if ld.allDisabled {
        for _, r := range ld.names {
            if r == ruleName {
                return false // explicitly re-enabled
            }
        }
        return true
    }
    for _, r := range ld.names {
        if r == ruleName {
            return true
        }
    }
    return false
}

`disabledSet`

This is just a map from absolute line numbers to their disable state:

type disabledSet map[int]lineDisable

"Absolute line number" matters here because gomarklint strips YAML frontmatter before linting. We need to track an offset so that line numbers stay consistent with what the user sees in their editor.

`blockState`

This tracks the current block-level disable state as we scan through lines:

type blockState struct {
    allDisabled bool
    exceptions  []string // re-enabled rules when allDisabled=true
    rules       []string // named disabled rules when allDisabled=false
}

blockState is a temporary, mutable value — it gets updated as we encounter disable and enable directives, and its current state is applied to each line we visit.

Parsing: Step 1 — Extracting a Directive from a Line

Before we can build the disable map, we need to extract directives from individual lines. parseDirectiveLine handles this:

func parseDirectiveLine(line string) (directive string, ruleNames []string) {
    start := strings.Index(line, "<!--")
    if start == -1 {
        return "", nil
    }
    end := strings.Index(line[start:], "-->")
    if end == -1 {
        return "", nil
    }
    inner := strings.TrimSpace(line[start+4 : start+end])
    const prefix = "gomarklint-"
    if !strings.HasPrefix(inner, prefix) {
        return "", nil
    }
    parts := strings.Fields(inner[len(prefix):])
    if len(parts) == 0 {
        return "", nil
    }
    switch parts[0] {
    case "disable", "enable", "disable-line", "disable-next-line":
        return parts[0], parts[1:]
    default:
        return "", nil
    }
}

Find  to extract the comment body
Check for the gomarklint- prefix
Split the rest into the directive keyword and optional rule names

Rule names are everything after the directive keyword — so  yields ["MD013", "MD032"].

Parsing: Step 2 — Building the `disabledSet`

parseDisableComments scans all lines, maintains a running blockState, and builds the final disabledSet:

func parseDisableComments(lines []string, offset int) disabledSet {
    set := make(disabledSet)
    var bs blockState

    for i, line := range lines {
        absLine := i + 1 + offset
        directive, ruleNames := parseDirectiveLine(line)

        switch directive {
        case "disable":
            if len(ruleNames) == 0 {
                bs = blockState{allDisabled: true}
            } else {
                bs.rules = append(bs.rules, ruleNames...)
            }
        case "enable":
            if len(ruleNames) == 0 {
                bs = blockState{} // full reset
            } else if bs.allDisabled {
                bs.exceptions = append(bs.exceptions, ruleNames...)
            } else {
                bs.rules = removeAll(bs.rules, ruleNames)
            }
        case "disable-line":
            set.addLine(absLine, ruleNames)
        case "disable-next-line":
            if i+1 < len(lines) {
                set.addLine(absLine+1, ruleNames)
            }
        }

        bs.applyTo(set, absLine) // apply current block state to this line
    }

    return set
}

bs.applyTo(set, absLine) is called on every line, not just lines with directives. This is how block-level disabling propagates — the current block state "stamps" each line as we pass it.

disable-line and disable-next-line write directly to set without touching blockState, since they're scoped to one line only.

enable has two behaviors depending on the current block state:

Full enable → reset blockState entirely
Named enable inside an all-disabled block → add to exceptions list
Named enable inside a named-disable block → remove from the rules list

Priority: What Wins When Rules Conflict?

There are cases where a line can be affected by multiple directives. The priority rules are:

All-disabled beats named-disable. If a line is already fully disabled, adding named rules has no effect.
Line-specific directives beat block-level. A disable-line or disable-next-line always takes effect regardless of what the block state says.

addLine enforces rule 1:

func (d disabledSet) addLine(line int, ruleNames []string) {
    existing, exists := d[line]
    if exists && existing.allDisabled && len(existing.names) == 0 {
        return // fully disabled with no exceptions — nothing to add
    }
    if len(ruleNames) == 0 {
        d[line] = lineDisable{allDisabled: true}
        return
    }
    d[line] = lineDisable{names: append(existing.names, ruleNames...)}
}

Integration: Filtering Violations

With the disabledSet built, filtering in collectErrors is a map lookup per violation:

var disabled disabledSet
if strings.Contains(body, "gomarklint-disable") {
    disabled = parseDisableComments(lines, offset)
}

allErrors := l.collectLineErrors(path, lines, offset)
// ... external link checks ...

if len(disabled) > 0 {
    filtered := allErrors[:0]
    for _, e := range allErrors {
        if !disabled.isDisabled(e.Line, e.Rule) {
            filtered = append(filtered, e)
        }
    }
    allErrors = filtered
}

There's a small but meaningful optimization: we only call parseDisableComments if the file body actually contains the string "gomarklint-disable". For files without any directives — the common case — we skip the parsing step entirely. This keeps the hot path fast.

The filter uses the in-place slice trick (filtered := allErrors[:0]) to avoid an extra allocation.

Intentional "Silent Fail" for Invalid Rule Names

What happens if a user writes a typo or a nonexistent rule name?

<!-- gomarklint-disable-line no-bare-url -->
https://example.com

The correct rule name is no-bare-urls (with an s). The result: the directive is silently ignored, and the violation is still reported.

This is intentional. The lookup in isRuleDisabled is a plain string comparison:

for _, r := range ld.names {
    if r == ruleName {
        return true
    }
}

If the name doesn't match any known rule, the function returns false and the violation passes through. There's no registry lookup or error message.

This matches the behavior of markdownlint and most other linters. A warning system for invalid directive names could be added, but for now the behavior is predictable: wrong name → no suppression.

We have explicit E2E tests for this to make sure it stays intentional:

<!-- gomarklint-disable-line no-bare-url -->
https://wrong-rule-name.example.com

<!-- gomarklint-disable-next-line nonexistent-rule -->
https://nonexistent-rule.example.com

Both lines are expected to produce violations — the test fails if they're silently suppressed.

Testing Strategy

The feature is tested at three levels:

Unit tests (disable_comment_test.go) cover parseDirectiveLine and parseDisableComments in isolation — 13+ cases for directive parsing, edge cases for block/line scope interaction, priority rules, and frontmatter offset handling.

Integration tests (linter_test.go) run linter.Run() against in-memory Markdown strings and verify which violations survive filtering. These tests also include a case that confirms parsing is skipped when no directive keyword is present in the file.

E2E tests (e2e_test.go) run the actual binary against a fixture file (disable_comment.md) and check the reported line numbers. This catches any disconnect between the parsing logic and how violations are reported to the user.

The Full Picture

Here's the complete flow, end to end:

Markdown file
    │
    ▼
StripFrontmatter()  →  body string + offset int
    │
    ▼
strings.Contains("gomarklint-disable")?
    │   yes
    ▼
parseDisableComments(lines, offset)
    │   scan each line:
    │     parseDirectiveLine()  →  directive + ruleNames
    │     update blockState
    │     bs.applyTo(set, absLine)
    ▼
disabledSet  (map[int]lineDisable)
    │
    ▼
collectLineErrors()  →  []LintError
    │
    ▼
filter: !disabled.isDisabled(e.Line, e.Rule)
    │
    ▼
sorted []LintError  →  reported to user

The implementation is about 170 lines of Go (internal/linter/disable_comment.go). Most of the logic lives in the data model — the filtering step itself is just a map lookup.

The part I found most interesting was representing "all disabled except these" and "only these are disabled" with the same struct, by flipping what names means depending on allDisabled. It kept the code flat while covering the full directive surface.

Full implementation: gomarklint/internal/linter/disable_comment.go

gomarklint is an open-source Markdown linter written in Go.

How to add a markdown quality gate to your GitHub Actions workflow

Kazu — Tue, 21 Apr 2026 13:00:00 +0000

My team's docs repo crossed 400 files last year. We merged a PR that quietly introduced three broken external links, one heading that jumped from H2 to H4, and a fenced code block without a language tag. None of it failed CI. A reader filed a GitHub issue two weeks later.

Adding a markdown quality gate seemed like an obvious fix, but the first option we tried pulled in a Node.js runtime setup step, a pinned Node version, and a question from a teammate: "why does our docs pipeline touch Node?" This tutorial walks through building a working workflow from scratch — the file path, the triggers, the config, and what a real failure looks like.

Step 1: Create the workflow file

Create .github/workflows/markdown-lint.yml in your repository. Start with just the trigger:

name: Markdown lint

on:
  pull_request:
    paths:
      - "**/*.md"
  push:
    branches:
      - main
    paths:
      - "**/*.md"

The paths filter means the job only runs when a .md file changed. On a busy repo this matters — you don't want a Go or Python change triggering a docs check.

Step 2: Add the job skeleton

Extend the file with a job and the checkout step:

name: Markdown lint

on:
  pull_request:
    paths:
      - "**/*.md"
  push:
    branches:
      - main
    paths:
      - "**/*.md"

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

Nothing surprising here. Checkout is always first — the linter needs the files on disk.

Step 3: Add the markdown linter to your GitHub Actions job

We'll use gomarklint — a single static binary with no runtime dependencies. The entire lint step is one line:

name: Markdown lint

on:
  pull_request:
    paths:
      - "**/*.md"
  push:
    branches:
      - main
    paths:
      - "**/*.md"

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint Markdown
        uses: shinagawa-web/gomarklint-action@v1

That's the complete workflow. Push this file and the markdown lint check will run on every PR that touches a .md file.

Step 4: See a real failure

Without any configuration, gomarklint runs its default rules. A PR that introduces a heading jump produces output like this:

docs/api/endpoints.md:23: heading-level: expected H3, got H4 (skipped a level)
docs/contributing.md:11: fenced-code-language: code block has no language identifier
docs/contributing.md:58: external-link: https://old-domain.example.com/guide returned 404

The job exits non-zero. The PR check goes red. The broken content doesn't merge.

The external link check is the one that would have caught our production issue. gomarklint makes real HTTP requests to each linked URL and reports anything that returns 4xx or 5xx, or times out. No second tool required.

Step 5: Add a config file

Create .gomarklint.yaml at the repo root to tune which rules run and how:

rules:
  heading-level:
    enabled: true
    minLevel: 2
  fenced-code-language:
    enabled: true
  external-link:
    enabled: true
    timeoutSeconds: 10
    skipPatterns:
      - "localhost"
      - "example\\.com"

minLevel: 2 means H1 is reserved for the document title and the linter won't flag its absence in sub-pages. skipPatterns lets you exclude URLs that are intentionally unreachable in CI (local dev URLs, placeholder domains).

The gomarklint action picks up .gomarklint.yaml automatically — no flag needed.

Step 6: Make the markdown lint check block merges

In your repository settings, go to Branches → Branch protection rules → Require status checks to pass before merging and add lint (or whatever you named the job). From this point the check is a hard gate, not advisory.

The full workflow, with config wired in, looks like this:

name: Markdown lint

on:
  pull_request:
    paths:
      - "**/*.md"
  push:
    branches:
      - main
    paths:
      - "**/*.md"

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint Markdown
        uses: shinagawa-web/gomarklint-action@v1

The config lives in .gomarklint.yaml at the root. The action finds it automatically.

What the rules actually catch

gomarklint's default rule set covers the problems that consistently show up in team docs repositories:

Heading level jumps (H2 → H4 with no H3)
Duplicate headings within a file
More than one H1 per file
Missing blank lines around headings, lists, and code blocks
Fenced code blocks with no language identifier
Images with missing or empty alt text
Bare URLs that aren't wrapped in link syntax
Empty link destinations
External links that return 4xx/5xx or time out

All rules are on by default and individually toggleable in .gomarklint.yaml.

What it doesn't solve yet

The gate catches structural and link problems reliably. It doesn't enforce prose style — things like passive voice, sentence length, or terminology consistency require a different category of tool. For those, tools like Vale fill the gap, and you can add Vale as a second step in the same job without any conflict.

I'm currently looking at integrating internal anchor validation (catching [see this](#old-anchor) when old-anchor no longer exists after a heading rename). That's the one class of broken link this workflow still misses.

What's the first markdown rule you'd want failing your CI today — structure, links, or something else?

Footnote: why gomarklint over markdownlint-cli2

The other widely-used option is markdownlint-cli2, which has 50+ rules and a large community. The tradeoff is the runtime: it requires a Node.js setup step in CI (~15–20 seconds), which adds friction in non-JavaScript repos.

	markdownlint-cli2	gomarklint
Runtime	Node.js required	None (single binary)
Install in CI	`npm install -g markdownlint-cli2`	GitHub Action or `curl` one-liner
HTTP link validation	Separate tool needed	Built in
Rules	50+	14 structural + link validation

If you already have Node.js in your pipeline, markdownlint-cli2 is a solid choice. If you don't, gomarklint avoids adding it.

→ gomarklint on GitHub
→ gomarklint docs

Shipping a Go CLI to Every Ecosystem: GitHub Releases, Homebrew, and npm

Kazu — Tue, 14 Apr 2026 13:00:00 +0000

The Problem: Great Tools Die in Obscurity

You can build the fastest, most useful CLI tool in the world. But if installing it requires go install, you've already lost 90% of your potential users.

Most developers don't have Go installed. Most frontend engineers don't know what go install means. And most technical writers — the people who benefit most from a Markdown linter — will close the tab the moment they see a compile step.

Distribution is not a feature. Distribution is survival.

This is the story of how I took gomarklint — a Markdown linter written in Go — and made it installable via three ecosystems:

# For anyone — just download and run
curl -L https://github.com/shinagawa-web/gomarklint/releases/latest

# For macOS users
brew install shinagawa-web/tap/gomarklint

# For Node.js users
npm install -g @shinagawa-web/gomarklint

# For Go developers
go install github.com/shinagawa-web/gomarklint@latest

One binary. Four installation methods. Zero runtime dependencies.

Why Multi-Channel Distribution Matters

Let me share a real scenario.

A technical writer on your team wants to lint Markdown docs locally. They open the README, see go install ..., and immediately ask the engineering team for help. The engineer says "just install Go." The writer says "I just want to check my docs." Nothing happens.

Now imagine this instead:

npm install -g @shinagawa-web/gomarklint
gomarklint docs/

Done. No Go. No Homebrew. Just a tool they already know how to use.

Each distribution channel unlocks a different audience:

Channel	Audience
GitHub Releases	CI/CD pipelines, DevOps engineers
Homebrew	macOS developers
npm	Frontend engineers, technical writers
`go install`	Go developers

If your tool only lives in one ecosystem, you're leaving users on the table.

The Architecture: One Binary, Thin Wrappers

The core insight is simple: don't ship your binary inside the package. Download it at install time.

Here's how the npm distribution works:

npm install -g @shinagawa-web/gomarklint
        │
        ▼
  package.json (postinstall → node install.js)
        │
        ▼
  install.js detects OS/arch
        │
        ▼
  Downloads binary from GitHub Releases
        │
        ▼
  Verifies SHA-256 checksum
        │
        ▼
  cli.js (execFileSync → gomarklint binary)

The npm package contains no binary. It's three files:

package.json — metadata and postinstall hook
install.js — platform detection and binary download
cli.js — thin wrapper that invokes the binary

Total package size before install: under 5KB.

Step 1: Platform Detection (install.js)

The install script maps Node.js platform identifiers to GoReleaser archive names:

const PLATFORM_MAP = {
  darwin: "Darwin",
  linux: "Linux",
  win32: "Windows",
};

const ARCH_MAP = {
  x64: "x86_64",
  arm64: "arm64",
};

This covers the six combinations that matter: macOS (Intel + Apple Silicon), Linux (x64 + ARM), and Windows (x64 + ARM).

When npm install runs, the postinstall script:

Reads the version from package.json
Maps process.platform and process.arch to archive names
Downloads the checksums file and the archive in parallel
Verifies the SHA-256 checksum
Extracts the binary with tar
Sets executable permissions

No dependencies. Just Node.js built-ins: https, crypto, child_process, fs.

Step 2: The CLI Wrapper (cli.js)

The wrapper is intentionally minimal:

#!/usr/bin/env node
"use strict";

const { execFileSync } = require("child_process");
const path = require("path");

const ext = process.platform === "win32" ? ".exe" : "";
const bin = path.join(__dirname, "gomarklint" + ext);

try {
  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
} catch (e) {
  process.exitCode = e.status || 1;
}

Key design decisions:

stdio: "inherit" — passes through stdin/stdout/stderr, so output formatting and piping work exactly like the native binary
Exit code forwarding — critical for CI usage where non-zero exit means lint failure
No abstraction — the wrapper does nothing but proxy execution

Step 3: Supply Chain Security

Shipping binaries through npm raises legitimate security concerns. Two mechanisms address this:

SHA-256 Checksum Verification

GoReleaser generates a checksums file for every release. The install script downloads it and verifies the archive before extraction:

function verifyChecksum(data, expected) {
  const actual = crypto.createHash("sha256").update(data).digest("hex");
  if (actual !== expected) {
    throw new Error(
      `Checksum mismatch!\n  Expected: ${expected}\n  Actual:   ${actual}`
    );
  }
}

If someone tampers with the binary on GitHub Releases, the install fails loudly.

npm Provenance

The publish step uses --provenance, which cryptographically proves the package was built from a specific GitHub Actions workflow:

- name: Publish to npm
  run: npm publish --provenance --access public
  working-directory: npm
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Users can verify this with npm audit signatures.

Step 4: Automated Publishing with GoReleaser

The entire release pipeline runs on a single trigger: pushing a version tag.

# .github/workflows/goreleaser.yml
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
      - uses: goreleaser/goreleaser-action@v7
        with:
          args: release --clean

  npm-publish:
    needs: release
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - name: Set package version from tag
        working-directory: npm
        run: |
          VERSION="${GITHUB_REF_NAME#v}"
          node -e "
            const fs = require('fs');
            const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
            pkg.version = '${VERSION}';
            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
          "
      - name: Publish to npm
        run: npm publish --provenance --access public
        working-directory: npm
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

The npm package version is never manually managed. It's extracted from the git tag at publish time. v2.7.1 becomes npm version 2.7.1. Zero version drift.

The npm-publish job has needs: release, so it only runs after GoReleaser has finished uploading all binaries. If GoReleaser fails, npm doesn't publish a broken version.

Step 5: GoReleaser Configuration

One thing I learned the hard way: if you don't explicitly specify architectures, you might be missing builds that your npm users need.

builds:
  - env:
      - CGO_ENABLED=0
    goos:
      - linux
      - windows
      - darwin
    goarch:
      - amd64
      - arm64

Adding explicit arm64 support was essential. Apple Silicon is the default for new Macs, and ARM Linux servers are increasingly common. Without this, npm install would 404 on gomarklint_Darwin_arm64.tar.gz.

Gotcha: The Checksums Filename

Here's something that cost me a failed release.

I assumed GoReleaser generates checksums.txt. It doesn't. It generates gomarklint_2.7.0_checksums.txt — prefixed with the project name and version.

My first npm release failed with:

Error: Download failed: HTTP 404 for
  https://github.com/.../releases/download/v2.7.0/checksums.txt

Always check your actual release assets before writing the download logic:

gh release view v2.7.0 --json assets --jq '.assets[].name'

The Result

One git tag + git push now triggers:

GoReleaser builds binaries for 6 platform/arch combinations
GitHub Release is created with all assets and checksums
Homebrew formula is updated in the tap repository
npm package is published with provenance attestation

Total human effort per release: two commands.

git tag v2.7.1
git push origin v2.7.1

Takeaways

Distribution is a feature. The best CLI tool means nothing if people can't install it.
Don't ship binaries in packages. Download them at install time. Your npm package stays tiny, and you don't need to rebuild for every platform in npm's ecosystem.
Verify everything. SHA-256 checksums and npm provenance are table stakes for binary distribution.
Automate the version. Extract from the git tag. Never manually sync versions across ecosystems.
Test with real installs. npm install -g in a clean environment catches things unit tests never will.

If you're building a Go CLI and only distributing via go install, you're leaving users behind. The npm + Homebrew wrapper pattern takes an afternoon to set up and opens your tool to an entirely new audience.

Try it:

npm install -g @shinagawa-web/gomarklint
gomarklint .

Repository: https://github.com/shinagawa-web/gomarklint
npm: https://www.npmjs.com/package/@shinagawa-web/gomarklint
Documentation: https://shinagawa-web.github.io/gomarklint/

Choosing a Markdown linter for your docs pipeline: what each tool actually covers

Kazu — Tue, 10 Mar 2026 13:00:00 +0000

If you're setting up a documentation quality gate — for a Go service, a platform team's runbooks, or any repo where Markdown is the source of truth — you've probably hit the same decision point: four or five tools come up in search results, they all call themselves "Markdown linters," and it's genuinely unclear what each one actually catches versus what it quietly ignores.

This is a practical breakdown of the major options, what each one covers, where each one stops, and which use case each one fits best.

The tools and what they actually do

Tool	Language	Stars	Rules	Nature
markdownlint (DavidAnson)	JavaScript	~5,900	60 built-in	Structural linter
remark-lint	JavaScript	~1,000	~80 packages	Structural linter (AST-based)
markdownlint (Ruby)	Ruby	~2,009	~50	Structural linter
mdformat	Python	~726	N/A	Auto-formatter
gomarklint	Go	—	8	Structural linter + link checker

The distinction that matters most isn't language — it's whether the tool reports violations or silently rewrites files. mdformat is an auto-formatter: it won't tell you a heading level is wrong; it will just fix it. If you want visibility into what's broken (for PR review, for CI blocking), you want one of the linters, not a formatter.

If you need the broadest rule coverage: markdownlint

For teams that want thorough enforcement of documentation conventions — heading order, blank lines around elements, consistent list markers, trailing spaces, bare URLs — markdownlint (DavidAnson) is the mature choice. 60 built-in rules, a VS Code extension with wide adoption, and a CLI that integrates into any CI runner.

The cost: it requires Node.js. In a Go or Rust project where you've deliberately kept the toolchain lean, adding a JS runtime just for linting is a real friction point.

Pick this if: your team already runs Node.js in CI, or you need fine-grained rule configuration across many rule categories.

If you need AST-level extensibility: remark-lint

remark-lint operates on the parsed AST rather than raw text, which makes it uniquely suited to writing custom rules that understand document structure — not just surface patterns. Around 80 rules available across packages. The pluggable architecture is its strength; the configuration surface area is also its steepest learning curve.

Pick this if: you need to write project-specific rules, or you're already in the unified/remark ecosystem.

If you need format + dead-link validation in one binary, no runtime: gomarklint

gomarklint is a Go binary with no runtime dependencies. Download it, run it. It covers structural linting and two checks the JS tools don't touch at all:

Live external link validation — most linters ignore whether [see the RFC](https://...) actually resolves. gomarklint makes real HTTP requests, concurrently, and reports 404s and timeouts. ~2,000 links in under 10 seconds.

gomarklint . --enable-link-check

Unclosed code block detection — tolerant AST parsers silently repair a missing closing fence. gomarklint uses a text-based pass that catches the raw break — the one that causes everything below it to render as code.

The tradeoff is honest: 8 rules versus markdownlint's 60. If you need blanks-around-headings, no-bare-urls, or trailing-space enforcement today, gomarklint doesn't have them yet.

Pick this if: your repo is Go or polyglot and you want zero runtime overhead, or dead external links and structural breaks (unclosed fences, heading skips) are your highest-priority catches.

How the rules map across tools

For teams evaluating overlap before switching or combining tools:

gomarklint Rule	markdownlint	remark-lint
`final-blank-line`	MD047	`final-newline`
`unclosed-code-block`	— (unique)	— (unique)
`empty-alt-text`	MD045	—
`heading-level`	MD001 + MD041	`heading-increment`
`duplicate-heading`	MD024	`no-duplicate-headings`
`no-multiple-blank-lines`	MD012	`no-consecutive-blank-lines`
`external-link`	— (unique)	— (unique)
`no-setext-headings`	MD003	`heading-style`

unclosed-code-block and external-link have no equivalent in the major JS tools. Everything else in gomarklint's current set has a direct counterpart — so if you're already on markdownlint, you're not losing coverage by keeping it for the rules gomarklint doesn't yet implement.

Quick-reference decision guide

Broadest rule set, VS Code integration → markdownlint (DavidAnson)
Custom rules, AST access → remark-lint
Auto-fix without review → mdformat
No runtime, dead-link detection, CI binary → gomarklint
Maximum coverage today → markdownlint + gomarklint's --enable-link-check as a second pass

Try gomarklint

go install github.com/shinagawa-web/gomarklint@latest
gomarklint init
gomarklint .

Full documentation: https://shinagawa-web.github.io/gomarklint/

Which check has caught the most real issues in your docs pipeline — structural violations like heading order, or dead links that slipped through unnoticed? The answer tends to tell you which tool to reach for first.

Beyond Lines: Announcing "gosemdiff" – A Logic-Aware Diff Tool for Go

Kazu — Fri, 13 Feb 2026 14:50:00 +0000

Today marks a personal milestone: I have finally finished a massive, six-month-long refactoring of my other project, gomarklint.

That's why I'm excited to announce my next OSS project: gosemdiff.

The Problem with Current Solutions (Including AI)

As engineers, we don't need a "guess." We need proof.

Standard git diff treats code as text. But code is not just text; it's a tree of logic.

The Solution: gosemdiff

The goal is to provide a "Truth Machine" for your Pull Requests.

Key Concepts:

Semantic Labeling: Automatically identify changes as MOVE, RENAME, or LOGIC CHANGE.
Logic Integrity: Prove that a refactor hasn't changed the execution flow by comparing normalized AST hashes.
Test-Gap Detection: Alert you if a logic change was made without any corresponding updates to your *_test.go files.
Zero-Noise Mode: Completely ignore comments, formatting, and import ordering.

The Roadmap to v1.0.0

I've laid out an ambitious roadmap in the repository, moving from basic function inventorying to a fully integrated GitHub Action.

The ultimate goal? A CI bot that tells your reviewers:

"This PR is 90% refactoring. Logic changes detected in only 2 files. One logic change is missing a unit test."

I Need Your Feedback!

I'm taking a short break to recharge after the gomarklint marathon, and full-scale development on gosemdiff will kick off in about two months.

However, the "Grand Vision" is already live in the README. I want to build this for the community, so I need your input:

What kind of diffs annoy you the most during code reviews?
What "semantic" features would make your life easier?
What's your dream CI summary?

Please check out the repo and leave your ideas, feature requests, or "what-ifs" in the GitHub Issues!

👉 gosemdiff

Let's make code reviews about logic again, not just lines.

Making Parallel HTTP Requests Stable in Go: Lessons from Building a Markdown Linter

Kazu — Thu, 15 Jan 2026 13:28:45 +0000

When building gomarklint, a Go-based Markdown linter, I faced a challenge: checking 100,000+ lines of documentation for broken links. Parallelizing this with Goroutines seemed like a "no-brainer," but it immediately led to Flaky Tests in CI environments.

Speed is easy in Go; stability is the real challenge. Here are the three patterns I implemented to achieve both.

The Cache: Preventing 'Barrages'

In a large docset, the same URL appears dozens of times. Naive concurrency sends a request for every single occurrence, which looks like a DoS attack to the host.

Using sync.Map, I implemented a simple URL cache to ensure each unique URL is only checked once.

var urlCache sync.Map

// Check if we've seen this URL before
if val, ok := urlCache.Load(url); ok {
    return val.(*checkResult), nil
}

The Semaphore: Respecting Resource Limits

Even with a cache, checking 1,000 unique URLs simultaneously can exhaust local file descriptors or trigger rate limits.
I used a buffered channel as a semaphore to cap the number of active Goroutines.

maxConcurrency := 10
sem := make(chan struct{}, maxConcurrency)

for _, url := range urls {
    sem <- struct{}{} // Acquire token
    go func(u string) {
        defer func() { <-sem }() // Release token
        checkURL(u)
    }(url)
}

The Retry: Tolerating Network 'Whims'

Networks are inherently unreliable. A momentary blip shouldn't fail your entire CI build. I implemented Exponential Backoff to distinguish between permanent failures (404) and transient ones (5xx, timeouts).

// Only retry if it's a server error or network timeout
if err != nil || status >= 500 {
    time.Sleep(retryDelay * time.Duration(attempt))
    // retry...
}

The "Negative Caching" Trap

The most elusive bug was caching only the status code. If a request failed with a timeout, I stored status: 0. Subsequent checks retrieved 0 but didn't know an error had occurred, leading to inconsistent logic.

The Fix: Cache the entire result, including the error.

type checkResult struct {
    status int
    err    error
}
// Store the pointer to this struct in your cache

Conclusion: Is it 100% Stable?

Not quite. Even with these, "Cache Stampedes" (multiple Goroutines hitting the same uncached URL at the exact same millisecond) remain a concern.

I'm currently exploring golang.org/x/sync/singleflight to solve this. If you have experience tuning http.Client for massive parallel checks, I'd love to hear your thoughts in the comments or on GitHub!

Catch broken links in your Markdown docs before they reach production

Kazu — Tue, 13 Jan 2026 07:49:10 +0000

Your user clicked the "Getting Started" link in your README. They got a 404. You didn't know because the link had been broken for three weeks and no tool in your pipeline caught it.

That's the problem. Dead links in Markdown documentation are silent failures — they don't break tests, don't fail builds, and don't show up in code review. They only surface when a real person hits them.

I built gomarklint to close that gap. Here's what I learned running it across 180 Markdown files totaling 100,000+ lines.

The Three Kinds of Broken Links

Most link checkers treat all links the same. That's a mistake, because internal relative links, external HTTP links, and anchor fragment links fail for completely different reasons.

Internal relative links break when files get moved or renamed during a refactor. A link like [setup](./docs/setup.md) is valid the day you write it and invalid the day someone renames the file without updating references.

External HTTP links break for reasons you don't control — a third-party API changes its URL structure, a service goes down, a library migrates its docs to a new domain. These are often the most embarrassing failures because they affect the first impression a new user has of your project.

Anchor fragment links — links like [see config](#configuration) — break silently when headings change. If someone renames "Configuration" to "Config Options," every anchor pointing to #configuration is now dead, and no compiler will warn you.

gomarklint checks all three categories in a single pass. Enable link checking in your config:

{
  "enableLinkCheck": true,
  "skipLinkPatterns": ["localhost", "example.com"]
}

The skipLinkPatterns field lets you suppress false positives from placeholder URLs without disabling the check entirely.

The CI Hook: Failing the Build Before the PR Merges

Detection only matters if it runs before code ships. A link checker you run manually is a link checker you forget to run.

Here is a complete GitHub Actions workflow that checks every Markdown file on pull requests targeting main:

name: Markdown Link Check

on:
  pull_request:
    branches: [main]

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"

      - name: Install gomarklint
        run: go install github.com/shinagawa-web/gomarklint@latest

      - name: Check links
        run: gomarklint --enable-link-check ./...

The total runtime across 180 files is under 50ms — faster than most network round-trips to fetch a single external URL. Because gomarklint is a single compiled binary with no runtime dependency (no Node.js, no Ruby), the only meaningful CI time is the go install step, which caches cleanly via actions/setup-go.

The "Redirect Mask" Trap

The most elusive bug I found during development: external links that return 301 or 302 redirects were being silently treated as valid.

A link to http://old-docs.example.com/api might redirect to https://new-docs.example.com/api today. But in three months the redirect itself is removed, and your link goes from "redirects correctly" to "hard 404" overnight. The link check that passed six months ago is now wrong, and nothing told you the situation changed.

The fix: treat 3xx responses as warnings, not passes. In gomarklint, you can configure followRedirects: false to surface these — which forces you to update the link to the final destination rather than relying on a redirect that may not be permanent.

{
  "enableLinkCheck": true,
  "followRedirects": false
}

This is stricter than most teams want by default, but for docs you intend to maintain for years, it pays off.

What's Not Solved Yet

Link checking against rate-limited external services is still genuinely hard. GitHub, npm, and PyPI all throttle rapid HEAD requests, which produces false 429 failures in CI. The current approach — exponential backoff with a configurable retry count — helps, but a long PR queue can still hit limits.

The approach I'm exploring next is a two-tier strategy: fail the build on internal and anchor-fragment errors (always reliable, zero network cost), and report external link failures as warnings rather than hard errors, so they surface without blocking a merge.

If you've dealt with flaky external link checks in CI — whether in this tool or another — I'd genuinely like to know what threshold or retry logic worked for your repository size.

Check it out on GitHub: shinagawa-web/gomarklint

DEV Community: Kazu

How to safely remove a Django model field: finding every real reference before you delete

Why search returns 1,202 hits

How colref reads code structure instead of text

Installation

What zero results doesn't cover

The five-step procedure

First run: try a field you know is used

"How I Cut My Go Markdown Linter's Benchmark by 81%"

What is gomarklint?

The Starting Point: No Visibility

Step 1: Build a Benchmark You Can Trust

Step 2: Profile Before Touching Anything

Step 3: Fix the Biggest Problem First

Step 4: Turn the Pattern Into a System

The Final Numbers

What I'd Do Differently

Try It

7 CI Checks I Added After Breaking My Own Go OSS Project

The Harness at a Glance

1. The Coverage Gate: A Tripwire for Vanishing Tests (June 2025)

2. The Install Canary: Proving Users Can Still Get In (July 2025)

3. The Review Inliner: Surfacing Lint Where You Read Code (January 2026)

4. The Changelog Guard: Blocking the Invisible PR (February 2026)

5. The Performance Witness: Catching the 3x Slowdown That Passes Tests (February 2026)

6. The Wrapper Probe: Testing What Users Actually Run (May 2026)

7. The Hidden-Character Scanner: Defending Against Code You Cannot See (May 2026)

The Local Mirror: Catching Failures Before They Become PRs

How the Harness Grew

What Does Your Harness Look Like?

grep Said 1,202. The Real Answer Was 10. — Introducing colref

The Haystack: One Field Name, Ten Thousand Strings

The Blueprint: AST as a Code Structure Map

The Anchor: ORM Schema as a Disambiguation Layer

The "Implicit Self" Trap

Verified Against 15+ Real-World Projects

What's Next

Where it stands

Beyond Lines: Announcing "gosemdiff" – A Logic-Aware Diff Tool for Go

The Problem with Current Solutions (Including AI)

The Solution: gosemdiff

Key Concepts:

The Roadmap to v1.0.0

I Need Your Feedback!

How I Built Inline Disable Comments for a Go Markdown Linter

The Problem

What We Need to Support

The Data Model

lineDisable

disabledSet

blockState

Parsing: Step 1 — Extracting a Directive from a Line

Parsing: Step 2 — Building the disabledSet

Priority: What Wins When Rules Conflict?

Integration: Filtering Violations

Intentional "Silent Fail" for Invalid Rule Names

Testing Strategy

The Full Picture

How to add a markdown quality gate to your GitHub Actions workflow

Step 1: Create the workflow file

Step 2: Add the job skeleton

Step 3: Add the markdown linter to your GitHub Actions job

Step 4: See a real failure

Step 5: Add a config file

Step 6: Make the markdown lint check block merges

What the rules actually catch

What it doesn't solve yet

Footnote: why gomarklint over markdownlint-cli2

Shipping a Go CLI to Every Ecosystem: GitHub Releases, Homebrew, and npm

The Problem: Great Tools Die in Obscurity

Why Multi-Channel Distribution Matters

The Architecture: One Binary, Thin Wrappers

Step 1: Platform Detection (install.js)

Step 2: The CLI Wrapper (cli.js)

Step 3: Supply Chain Security

SHA-256 Checksum Verification

npm Provenance

Step 4: Automated Publishing with GoReleaser

Step 5: GoReleaser Configuration

Gotcha: The Checksums Filename

`lineDisable`

`disabledSet`

`blockState`

Parsing: Step 2 — Building the `disabledSet`