8000 kex lint / kex format: a linter and autoformatter written in Kex · Issue #169 · kexhq/kex · GitHub
[go: up one dir, main page]

Skip to content

kex lint / kex format: a linter and autoformatter written in Kex #169

Open

Description

@akoskovacs

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 (see tools/docgen/PLAN.md), and built on Kex.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 lint reports, kex format rewrites. A rule that can fix itself supplies the replacement; lint --fix and format are then the same code path. Formatting must be idempotent — running it twice changes nothing — and that property is worth a test that formats every .kex in 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:

  1. trivia/CST support plus a printer that round-trips every .kex in the repo byte-for-byte;
  2. kex format with the layout rules the codebase already follows;
  3. kex lint with a first rule set;
  4. editor and CI wiring — format-on-save through the LSP, a make lint that CI runs.

Configuration: JSONC or Kex?

Undecided, and worth settling in this ticket before implementation.

  • Kex (lint.kex, or a block in package.kex) — one language for everything, the manifest vocabulary in src/manifest/bundle.kex is 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:

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

  1. akoskovacs commented on Aug 21, 2026

    @akoskovacs
    CollaboratorAuthor

    Blocked by #136 (lexer trivia with attachment; Kex.AST.toSource round-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.

  2. akoskovacs commented on Nov 12, 2026

    @akoskovacs
    CollaboratorAuthor

    Configuration: a proposal

    #650 (a Schema module 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.kex and format.kex would 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.kex is 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.

    # lint.kex
    lint do
      use("kex/recommended")
    
      lineLength(max: 100)
      unusedBinding(level: :error)
      toStringConversion(level: :off)
    
      within("spec/**") do
        unusedBinding(level: :off)
      end
    end
    

    2. One resolution order, the same for every tool

    Later levels override earlier ones.

    Level Where
    Rule defaults the rule's own schema
    Shared preset use("..."), from the toolchain or a dependency
    Workspace lint.kex at the workspace root
    Package lint.kex beside package.kex
    Path within("spec/**") do ... end
    Line or block a comment in the source, for the rare exception

    3. 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.kex like built-in ones.

    The formatter stays small

    • Linter: fully configurable. Rules are independent; turning one off affects nothing else.
    • Formatter: a handful of options at most, line width and little else. Every formatting option multiplies the combinations that must stay idempotent and splits the ecosystem into dialects. format.kex uses the same mechanism with a very short schema whose defaults are STYLE.md.

    Editor support for the configuration files

    package.kex already 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 gives lint.kex and format.kex the 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

    1. Lexer trivia with attachment; Kex.AST.toSource round-trip #136: trivia in the syntax tree. Nothing can format without it.
    2. Schema module: one validation library for JSON and block-syntax data files #650: schemas and data files, for lint.kex and format.kex.
    3. This issue: the linter and formatter themselves.

    Open

    • Whether projects can write their own rules in Kex, or only configure rules that ship in the toolchain or a plugin.
    • The exact spelling of the per-line exception comment.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ImportantNeeds attention sooner rather than later

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0