Repository navigation
Description
Kex has no linter and no formatter. Style is enforced by review and by imitation, which does not scale and leaves every contributor guessing — the .kex sources in this repo already disagree with themselves about wrapping, alignment and blank lines, and the recent backtick-dedent migration (#158) had to be done with a throwaway awk script because there was no tool that could re-lay-out a literal.
What it should be
- Written in Kex, like
tools/docgen(seetools/docgen/PLAN.md), and built onKex.AST— the full-fidelity schema from Full-fidelity AST schema: named args, call blocks, patterns, bodies #135 already carries spans (startOffset/endOffset) and doc-comments, so a tool can map a finding back to an exact source range. - Two commands, one engine:
kex lintreports,kex formatrewrites. A rule that can fix itself supplies the replacement;lint --fixandformatare then the same code path. Formatting must be idempotent — running it twice changes nothing — and that property is worth a test that formats every.kexin the repo twice. - Configurable by the user. Open question below.
The hard part: fidelity
Autoformat needs everything the current AST throws away. Kex.AST keeps doc-comments (doc : String?) but not ordinary comments, blank lines, or where a trailing comment sat on its line. A formatter that loses a # why comment, or collapses the blank lines someone used to group a make block, is worse than no formatter.
So this needs either a lossless concrete syntax tree, or a trivia side-channel attached to the existing AST — a decision to make before any rules are written. It is also what makes this bigger than it looks, and why it should probably land in stages:
- trivia/CST support plus a printer that round-trips every
.kexin the repo byte-for-byte; kex formatwith the layout rules the codebase already follows;kex lintwith a first rule set;- editor and CI wiring — format-on-save through the LSP, a
make lintthat CI runs.
Configuration: JSONC or Kex?
Undecided, and worth settling in this ticket before implementation.
- Kex (
lint.kex, or a block inpackage.kex) — one language for everything, the manifest vocabulary insrc/manifest/bundle.kexis the precedent, and rules could be expressed in it rather than only toggled. Costs: config becomes executable-shaped, and reading it means running the parser on user code before linting user code. - JSONC — trivially readable by anything, editable by editors and bots, no evaluation. Costs: a second syntax in the toolchain, and no way to write a project-local rule.
A middle option: declarative Kex data (the manifest style — calls with no bodies, read as data, never executed), which keeps one syntax without making config a program.
Rules worth having on day one
Drawn from what review actually catches in this repo:
{ |x| ... }used for a multi-line block wheredo |x| ... endis the conventionif cond dowhere the parser wantsthen(today this can silently truncate amakeblock — see A syntax error in a stdlib file surfaces as cascading prelude type errors #165)- trailing whitespace, tabs mixed with spaces, missing trailing newline
- unused bindings, unused
usingimports toStringwhere the conversion protocol isto(String)- a block literal whose content is written flush-left when it could sit with the code (the Backtick literals should dedent by their content, not by the closing delimiter #158 migration, as a rule)
Prior art to look at
gofmt (no options at all), rustfmt (few options, config file), prettier (opinionated with escape hatches), credo (Elixir, lint-only, and the closest cultural fit). Worth deciding early how configurable the formatter is, separately from the linter: the fewer knobs it has, the more useful it is.
Activity
akoskovacs commentedon Aug 21, 2026
Blocked by #136 (lexer trivia with attachment;
Kex.AST.toSourceround-trip) — that stage is where the fidelity this needs comes from, so the "hard part" section above is really a restatement of #136 from the formatter's side rather than separate work.akoskovacs commentedon Nov 12, 2026
Configuration: a proposal
#650 (a
Schemamodule with schema-checked data files) answers the "JSONC or Kex?" question above. It is the middle option this issue describes: declarative Kex data, read as data and never executed, checked against a schema, with editor support.lint.kexandformat.kexwould be two such files.The aim is configuration that is universal: every rule is configurable, through one mechanism, at every level, and every tool sees the same result.
1. Every rule describes its own options with a schema
A rule declares its name, its documentation, its default level and its options. The vocabulary of
lint.kexis generated from the registered rules, built-in and plugin alike, so the editor offers completion, hover and checking for every rule and option without knowing any rule by name.2. One resolution order, the same for every tool
Later levels override earlier ones.
use("..."), from the toolchain or a dependencylint.kexat the workspace rootlint.kexbesidepackage.kexwithin("spec/**") do ... end3. One engine behind every entry point
kex lint,kex format, the language server (diagnostics, quick fixes, format on save) and CI resolve configuration the same way, so the editor never disagrees with the build.4. Third-party rules through the plugin system
A plugin registers rules with their schemas, and they appear in
lint.kexlike built-in ones.The formatter stays small
format.kexuses the same mechanism with a very short schema whose defaults areSTYLE.md.Editor support for the configuration files
package.kexalready gets hover and completion through a vocabulary file (src/manifest/bundle.kex) that the language server and the driver load by file name. That mechanism is hard-coded to one file. #650 would generalise it to a registry from file name to schema, which is what giveslint.kexandformat.kexthe same support, plus what the current mechanism cannot check: entries only where they belong, required and repeated entries, and nothing but data in the file.Order of work
Kex.AST.toSourceround-trip #136: trivia in the syntax tree. Nothing can format without it.lint.kexandformat.kex.Open