Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
b31922c
feat(tree-sitter-compact): add declaration-level Compact grammar
0xisk Sep 15, 2026
0d4991b
refactor(compact-tree-sitter): rename the grammar crate
0xisk Sep 15, 2026
ec5cb8a
feat(compact-lint): add the check command
0xisk Sep 15, 2026
a8ac656
feat(compact-lint): add the fix command
0xisk Sep 15, 2026
46ef29a
ci(rust): stop persisting checkout credentials
0xisk Sep 16, 2026
f06882b
docs(compact-tree-sitter): correct the name field claim
0xisk Sep 16, 2026
e2b329d
test(compact-tree-sitter): skip symlinks in the corpus walk
0xisk Sep 16, 2026
847e376
Merge branch 'feat/tree-sitter-compact' into feat/compact-lint-check
0xisk Sep 16, 2026
334b4a9
fix(compact-lint): resolve explicit paths against cwd
0xisk Sep 16, 2026
9344813
refactor(compact-lint): mark Tag::new must_use
0xisk Sep 16, 2026
3ade154
fix(compact-lint): check constraints under docs = none
0xisk Sep 16, 2026
57a8323
Merge branch 'feat/compact-lint-check' into feat/compact-lint-fix
0xisk Sep 16, 2026
0acfa84
fix(compact-lint): skip inserting a tag a rename supplies
0xisk Sep 16, 2026
e64fef9
fix(compact-lint): validate the fix placeholder
0xisk Sep 16, 2026
c4737e6
fix(compact-lint): validate rename against forbid
0xisk Sep 16, 2026
aa06bbd
fix(compact-lint): write through a unique temp file
0xisk Sep 16, 2026
7b74838
feat(compact-lint): add the check command
0xisk Sep 15, 2026
68baa98
fix(compact-lint): resolve explicit paths against cwd
0xisk Sep 16, 2026
5ec1584
refactor(compact-lint): mark Tag::new must_use
0xisk Sep 16, 2026
3423bd6
fix(compact-lint): check constraints under docs = none
0xisk Sep 16, 2026
104d9e3
Merge branch 'feat/compact-lint-check' into feat/compact-lint-fix
0xisk Oct 13, 2026
a3e35f6
Merge branch 'main' into feat/compact-lint-fix
0xisk Nov 17, 2026
a907f86
fix(compact-lint): keep the closing */ on a module-name fix
0xisk Nov 17, 2026
8a940ed
fix(compact-lint): move delimiter-line text before inserting
0xisk Nov 17, 2026
8b14e94
fix(compact-lint): write the constraints tag only once
0xisk Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,4 @@ tree-sitter-language = "0.1"
walkdir = "2.5"

assert_cmd = "2.2"
tempfile = "3.27"
1 change: 1 addition & 0 deletions crates/compact-lint/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,4 @@ walkdir.workspace = true

[dev-dependencies]
assert_cmd.workspace = true
tempfile.workspace = true
70 changes: 68 additions & 2 deletions crates/compact-lint/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,14 @@

Doc-comment linter for Compact sources. It parses `.compact` files with
[`compact-tree-sitter`](../compact-tree-sitter), matches every declaration against the
per-kind template in `compact-lint.toml`, and prints one finding per line.
per-kind template in `compact-lint.toml`, and prints one finding per line. `fix`
rewrites the comments the repairable rules report.

## Usage

```sh
compact-lint check [PATHS]... [--config <file>] [--strict] [--no-format] [--compact-bin <path>]
compact-lint fix [PATHS]... [--config <file>] [--dry-run]
```

- `PATHS` — files or directories, walked recursively for `.compact`. Skipped while
Expand All @@ -32,6 +34,55 @@ summary goes to stderr, where `M` is the number of files checked.
- `1` — findings.
- `2` — usage, config, IO or parser error.

## Fix

`fix` rewrites `.compact` files so a following `check` is clean for every rule it
covers. It runs the same detection pass as `check`, so the two never disagree.

```sh
compact-lint fix [PATHS]... [--config <file>] [--dry-run]
```

- `PATHS` and `--config` resolve exactly as they do for `check`.
- `--dry-run` — report the edits and write nothing. Exit `1` when there are edits, so
CI gates on it the way it gates on `cargo fmt --check`.

Edits go to stdout, one per line, in `path:line:col: fix: <message>` form. The
`N edits in M files` summary goes to stderr, where `M` is the number of files changed.

Exit codes:

- `0` — the files were written, including when there was nothing to do.
- `1` — `--dry-run` only: edits would be made.
- `2` — usage, config, IO or parser error.

What each rule's fix does:

| Rule | Fix |
| --- | --- |
| `missing-doc` | Inserts a doc skeleton above the declaration, indented to it. Body lines come from `kinds.<kind>.tags` in config order; `@module` takes the declaration's name, every other tag takes `fix.placeholder`. Exported non-pure circuits also get the constraints line. A kind with neither gets a single placeholder line. |
| `missing-tag` | Inserts each missing tag after the block of the last tag that precedes it in `kinds.<kind>.tags`, else at the top of the body. A missing `@description` adopts untagged prose that opens the body instead of writing a placeholder. Text on the `/**` or `*/` line moves onto its own body line first, so a `/** … */` one-liner expands to the multi-line form. |
| `missing-constraints` | Inserts `<tag> k=?, rows=?` after the `@description` block, with a blank ` *` line before it and, where prose follows, one after. Without a `@description` it opens the body. On a circuit with no doc comment, it inserts a doc comment holding only that line. Nothing is inserted when a `tags.rename` entry renames another tag in the comment to the constraints tag, and a circuit never gets the constraints tag twice, even when `kinds.circuit.tags` lists it. |
| `forbidden-tag` | Renames the tag in place, and only where `tags.rename` maps it. |
| `module-name` | Replaces the first word of the `@module` value with the module's name, keeping what follows. A `*/` on the same line stays in place. |

Not fixed:

- `constraints-format` — a human wrote a measurement the rule cannot parse; guessing at
it would lose the value.
- `constraints-placeholder` — filling `k=?` needs a real measurement.
- `parse` — the file does not parse, so no rewrite is trustworthy.
- `format` — that is `compact format`'s job.
- A forbidden tag with no `tags.rename` entry stays a `check` finding.

Before writing, `fix` parses the rewritten file and refuses it, exiting `2`, when its
declarations differ from the original's: a doc edit never should change them.

Existing lines are never reordered or reflowed. Edits are computed against the original
text and applied from the highest offset down; several edits on one comment merge into a
single replacement of it. Files are rewritten through a sibling `.tmp` file and renamed
into place, keeping the file's line ending and its trailing newline, or lack of one.

## Rules

| Rule | Meaning |
Expand Down Expand Up @@ -79,6 +130,10 @@ tag = "@constraints"

[tags]
forbid = ["@return"]
rename = { "@return" = "@returns" }

[fix]
placeholder = "TODO"

[kinds.module]
docs = "exported"
Expand All @@ -94,6 +149,8 @@ Defaults when no config file is found:
| `exclude` | `[]` |
| `constraints.tag` | `"@constraints"` |
| `tags.forbid` | `[]` |
| `tags.rename` | `{}` |
| `fix.placeholder` | `"TODO"` |
| `kinds.<kind>.docs` | `"exported"` |
| `kinds.<kind>.tags` | `[]` |

Expand All @@ -105,6 +162,11 @@ Defaults when no config file is found:
`"all"` or `"none"` there.
- `exclude` filters files found by walking a directory. A file named on the command
line is always checked.
- `tags.rename` maps a forbidden tag to the tag `fix` writes in its place. Every key
must appear in `tags.forbid` and no value may, or the config is rejected. Both
spellings are validated like every other tag. An unmapped forbidden tag is reported,
never rewritten.
- `fix.placeholder` is the text `fix` writes where it has no value of its own.

`examples/compact-contracts.toml` is the config for OpenZeppelin/compact-contracts.

Expand All @@ -123,6 +185,10 @@ Defaults when no config file is found:
cargo test --workspace
```

`tests/fixtures/<case>/` holds one case per rule plus a clean case: a
`tests/fixtures/<case>/` holds one `check` case per rule plus a clean case: a
`compact-lint.toml`, the `.compact` sources, and `expected.txt`, the exact stdout with
paths relative to the case directory.

`tests/fixtures/fix-<case>/` holds one `fix` case per rule: a `compact-lint.toml`,
`before/`, `after/` and `expected.txt`. The run copies `before/` into a temporary
directory, so the fixtures are never rewritten in place.
1 change: 1 addition & 0 deletions crates/compact-lint/examples/compact-contracts.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ tag = "@constraints"

[tags]
forbid = ["@return"]
rename = { "@return" = "@returns" }
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

[kinds.module]
docs = "exported"
Expand Down
Loading
Loading