lucid-lint

A cognitive accessibility linter for prose. Built on cognitive load research. Bilingual EN/FR with equal care. Plugin-first, CI-native.

Status: v0.2.3 (2026-04-24) — patch cycle on the v0.2 line. 25 deterministic rules, bilingual EN / FR, hybrid scoring. Experimental-rule substrate (F-experimental-rule-status) landed 2026-05-02; the v0.3 cohort ships behind --experimental until the v0.3 cut. Pre-1.0 — breaking changes remain possible between minor versions. Current backlog: ROADMAP.md — v0.2 / v0.2.x.

What is lucid-lint?

lucid-lint reads your Markdown, plain-text, or piped prose and reports issues that increase cognitive load — the mental effort a reader spends to understand you.

Most prose linters measure style (write-good), grammar (Antidote), or surface readability (Flesch score). lucid-lint focuses on one thing: how hard is this text to read for someone whose attention is already stretched. Stretched attention could mean ADHD, fatigue, a second language, a noisy environment, or an accessibility-sensitive context (EAA, RGAA, FALC).

It's fast, CI-native, bilingual EN/FR, and designed to be extended.

How it compares

• Vale is a great prose linter with a plugin ecosystem. It's English-first and style-focused. lucid-lint is bilingual-first and cognitive-load focused.
• textlint has many plugins but no opinion on accessibility. lucid-lint takes a stance grounded in cognitive load research (Sweller, Gibson, Graesser).
• Hemingway and Grammarly are closed products for authors. lucid-lint is open source, CLI-first, CI-ready.
• Coh-Metrix is the academic reference for discourse cohesion metrics. It's rigorous but hard to integrate. lucid-lint borrows its conceptual model and ships it in a modern dev workflow.
• readability-score libraries compute Flesch, SMOG, etc. lucid-lint includes them as one signal among many.

Install

One-line installer (Linux, macOS, WSL):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bastien-gallay/lucid-lint/releases/latest/download/lucid-lint-installer.sh | sh

One-line installer (Windows PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/bastien-gallay/lucid-lint/releases/latest/download/lucid-lint-installer.ps1 | iex"

Both scripts are generated by cargo-dist at release time and place the binary on $PATH. To audit before running, download and read the script first:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bastien-gallay/lucid-lint/releases/latest/download/lucid-lint-installer.sh -o install.sh
less install.sh
sh install.sh

Via Cargo:

cargo install lucid-lint

From source:

git clone https://github.com/bastien-gallay/lucid-lint
cd lucid-lint
cargo install --path .

See docs/src/guide/installation.md for prebuilt-binary targets and the audit-before-running pattern.

Quick start

# Lint a Markdown file with the default profile
lucid-lint check README.md

# Use a specific profile
lucid-lint check --profile=public docs/*.md

# Pipe from stdin
cat draft.md | lucid-lint check -

# JSON output for CI
lucid-lint check --format=json docs/

# Fail CI if the aggregate score drops below 85 / 100
lucid-lint check --min-score=85 docs/

Scoring

Every run emits a global X / 100 score plus five per-category sub-scores (Structure · Rhythm · Lexicon · Syntax · Readability), in addition to the diagnostics list.

warning /tmp/draft.md:12:1 Sentence is 27 words long (maximum 22). [structure.sentence-too-long]

summary: 1 warnings.
→ run 'lucid-lint explain <rule-id>' — seen here: structure.sentence-too-long
────────────────────────────────────────────────────────────
score: 88/100
       structure    ██▏░░  8/20
       rhythm       █████  20/20
       lexicon      █████  20/20
       syntax       █████  20/20
       readability  █████  20/20

Use --min-score=N to gate CI on the aggregate score (the gate stacks with --fail-on-warning). Tune category caps and per-rule weights via the [scoring] and [scoring.weights] tables in lucid-lint.toml.

Full documentation in the user guide: Scoring.

Supported formats

• Markdown (.md, .markdown)
• Plain text (.txt)
• stdin

For other formats (AsciiDoc, reStructuredText, HTML, docx, PDF), convert first with Pandoc:

pandoc document.docx -t markdown | lucid-lint check -

Native support for more formats is on the roadmap.

Profiles

See RULES.md for per-rule thresholds.

Rules

25 rules grouped into 5 scoring categories — Structure · Rhythm · Lexicon · Syntax · Readability. Full reference in RULES.md.

Configuration

Create a lucid-lint.toml in your project root:

[default]
profile = "public"

[rules."structure.excessive-commas"]
max_commas = 2

[rules.unexplained-abbreviation]
whitelist = ["WCAG", "ARIA", "RGAA"]

[scoring]
category_max = 20
category_cap = 15

[scoring.weights]
sentence-too-long = 3

Editor integration

• pre-commit — ships with this repo; run pre-commit install to enable locally.
• VS Code extension — on the roadmap (v0.3+)
• Neovim LSP support — on the roadmap (v0.3+)

Documentation

Full documentation at https://bastien-gallay.github.io/lucid-lint (built with mdBook).

Quality & Security

• Codecov — line coverage for the Rust workspace
• CodeQL — static analysis: taint tracking, control-flow, cross-function patterns
• OpenSSF Scorecard — supply-chain checks: pinned actions, branch protection, signed releases

Contributing

Contributions welcome! See CONTRIBUTING.md.

Especially welcome:

• Rule proposals (open an issue first)
• Language-specific word lists (connectors, weasel words, jargon)
• Documentation improvements
• Benchmarks and corpus contributions

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.