docs: surface SQL + ANTLR across stalled pages, add PR-comment screenshot#172
Conversation
…shot Audit and refresh docs that lagged behind the SQL (mehen-sql/sqruff) and ANTLR (Kotlin, Java) additions. - introduction: promote SQL to a first-class feature — headline card, a dedicated "First-class SQL analysis" section, and an SQL entry in "What mehen computes"; fix the parser card (Kotlin/Java are ANTLR, add sqruff) and mention SQL in the intro line. - index: "nine" -> "eleven" source languages plus SQL and Markdown; add SQL card + compute block; fix Kotlin miscredited as tree-sitter; add Java/sqruff to the parser card. - concepts/architecture: add mehen-antlr and mehen-sql to the crate table, Java + SQL rows to the parser table and pipeline diagram, and new "ANTLR-backed analyzers" and "SQL is its own metric family" sections. - developers/update-grammars: drop the removed tree-sitter-markdown-text grammar; correct the pinning model (inline per-crate, xtask reaches it via __grammar_language()); note PowerShell has no generated grammar.rs and is not a codegen target. - developers/overview: add mehen-java and mehen-sql to the repo layout; ANTLR regeneration prereq covers Java too. - guides/github-action: replace the stale "only source-code metrics ship" note (docs-diff is a default feature and is wired into the diff path); document SQL in the diff; embed the sticky-comment screenshot. - guides/pr-comment-design: document the shipped --fail-on gating (dmi-drop, new-broken-link, filler-high, all) instead of "planned"; embed the screenshot. - add docs/images/pr-comment-metrics.png.
WalkthroughThe documentation now covers ANTLR-backed analyzers, Java grammar maintenance, SQL’s dedicated metric family, and revised tree-sitter workflows. Landing and introduction pages expand product descriptions and SQL metric listings. GitHub Action and PR comment guides document sticky comment layouts, SQL diff output, Markdown metrics, and active Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to reflect the addition of ANTLR-backed analyzers for Kotlin and Java, as well as a new SQL analyzer (mehen-sql) powered by sqruff. It also documents the GitHub Action sticky comment layout, --fail-on gating, and the architecture of these new components. The review feedback suggests capitalizing SQL dialect names (such as PostgreSQL, Snowflake, and BigQuery) across the documentation for consistency.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| | Rust | [`ra_ap_syntax`](https://docs.rs/ra_ap_syntax/) | The same syntax library rust-analyzer uses internally. | | ||
| | Kotlin | [ANTLR](https://www.antlr.org/) (official [Kotlin spec grammar](https://github.com/Kotlin/kotlin-spec)) | Semantically-named rules for `when` entries, elvis `?:`, safe-call `?.`, `catch` blocks, labeled jumps, and property accessors — richer than a tree-sitter CST. | | ||
| | Java | [ANTLR](https://www.antlr.org/) ([grammars-v4 Java grammar](https://github.com/antlr/grammars-v4/tree/master/java/java)) | Records, sealed types, switch expressions, text blocks, pattern matching, modules — as first-class, semantically-named rules. | | ||
| | SQL | [sqruff](https://github.com/quarylabs/sqruff) | Dialect-aware SQL CST (postgres, T-SQL, snowflake, bigquery, …) for CTE/join/subquery structure and object-touch analysis. | |
There was a problem hiding this comment.
For consistency and professional presentation, capitalize the names of the SQL dialects (e.g., PostgreSQL, Snowflake, BigQuery).
| SQL | [sqruff](https://github.com/quarylabs/sqruff) | Dialect-aware SQL CST (PostgreSQL, T-SQL, Snowflake, BigQuery, …) for CTE/join/subquery structure and object-touch analysis. |
| file-level **review-burden index** and **change-risk score**. | ||
|
|
||
| Dialect is inferred from syntax with a reported confidence (or pinned with a `-- sqlfluff:dialect:…` | ||
| directive) across postgres, T-SQL, snowflake, bigquery, and more. SQL files are picked up |
There was a problem hiding this comment.
Capitalize the SQL dialect names (PostgreSQL, Snowflake, BigQuery) to ensure consistent formatting across all documentation pages.
directive) across PostgreSQL, T-SQL, Snowflake, BigQuery, and more. SQL files are picked up
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 72926def47
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| The Python, TypeScript / JavaScript / TSX / JSX, PHP, Ruby, Rust, Kotlin, Java, SQL, and Markdown | ||
| analyzers do **not** use tree-sitter; they have no `grammar.rs` and need no kind-enum regeneration. |
There was a problem hiding this comment.
This new guidance says the Markdown analyzer has no grammar.rs, but crates/mehen-markdown/src/grammar.rs exists, is marked generated, and is used by the pulldown-backed syntax tree via crate::grammar::Markdown. Following this doc can mislead contributors into ignoring or hand-editing the generated Markdown kind enum; please remove Markdown from the “no grammar.rs” list or clarify that its generated enum is separate from the tree-sitter regeneration flow.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/index.mdx`:
- Around line 67-72: Add “modularity health” to the “For SQL” metric list in
docs/index.mdx, matching the terminology used in docs/introduction.mdx and the
sql.modularity_health composite score in the report output.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 45e6349a-734f-43ed-bcca-c289c87af52d
⛔ Files ignored due to path filters (1)
docs/images/pr-comment-metrics.pngis excluded by!**/*.png
📒 Files selected for processing (7)
docs/concepts/architecture.mdxdocs/developers/overview.mdxdocs/developers/update-grammars.mdxdocs/guides/github-action.mdxdocs/guides/pr-comment-design.mdxdocs/index.mdxdocs/introduction.mdx
| For SQL: | ||
|
|
||
| - [Structural and cognitive complexity](/metrics/sql/overview) from CTE, join, subquery, `CASE`, and | ||
| window structure; a [Review Burden Index](/metrics/sql/overview) and [Change Risk | ||
| Score](/metrics/sql/overview); an [SQL Halstead](/metrics/sql/overview) and maintainability index. | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Add "modularity health" to the "For SQL" metric list for consistency.
The "For SQL" section here omits modularity health, which is listed in the corresponding section in docs/introduction.mdx (Line 128) and is confirmed as a rendered composite score in crates/mehen-report/src/markdown.rs (sql.modularity_health in the "Composite scores" group). Adding it keeps the landing page accurate with both the introduction page and the actual report output.
📝 Proposed fix
- [Structural and cognitive complexity](/metrics/sql/overview) from CTE, join, subquery, `CASE`, and
window structure; a [Review Burden Index](/metrics/sql/overview) and [Change Risk
- Score](/metrics/sql/overview); an [SQL Halstead](/metrics/sql/overview) and maintainability index.
+ Score](/metrics/sql/overview); an [SQL Halstead](/metrics/sql/overview), maintainability index,
+ and modularity health.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| For SQL: | |
| - [Structural and cognitive complexity](/metrics/sql/overview) from CTE, join, subquery, `CASE`, and | |
| window structure; a [Review Burden Index](/metrics/sql/overview) and [Change Risk | |
| Score](/metrics/sql/overview); an [SQL Halstead](/metrics/sql/overview) and maintainability index. | |
| For SQL: | |
| - [Structural and cognitive complexity](/metrics/sql/overview) from CTE, join, subquery, `CASE`, and | |
| window structure; a [Review Burden Index](/metrics/sql/overview) and [Change Risk | |
| Score](/metrics/sql/overview); an [SQL Halstead](/metrics/sql/overview), maintainability index, | |
| and modularity health. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/index.mdx` around lines 67 - 72, Add “modularity health” to the “For
SQL” metric list in docs/index.mdx, matching the terminology used in
docs/introduction.mdx and the sql.modularity_health composite score in the
report output.
Binary Size ReportMeasured artifact: release Linux
Size historyxychart-beta
title "Binary size (bytes)"
x-axis ["feat(sql): SQL metrics analyze", "build(deps): bump ra_ap_syntax", "build(deps): bump gix from 0.8", "build(deps): bump log from 0.4", "build(deps): bump the ruff gro", "build(deps): bump the mago gro", "build: sync workspace crate ve", "build(deps): bump the oxc grou", "build(deps): bump tree-sitter ", "build(deps): bump camino from ", "feat: add Java analyzer and up", "build(deps): bump sqruff-lib-d", "build(deps): bump the mago gro", "build(deps): bump ra_ap_syntax", "build(deps): bump the oxc grou", "build(deps): bump mago-syntax-", "chore(main): release 1.3.0 (#1", "This PR"]
y-axis "Bytes"
bar [29151520, 29151560, 29154336, 29184128, 29154616, 29184664, 29184664, 29194704, 29194696, 29194704, 30767472, 30833880, 30833888, 30834016, 30811952, 30811944, 30811984, 31135680]
|
1 participant
Summary
Audits and refreshes documentation that had drifted behind two recent additions — the SQL analyzer (
mehen-sql/ sqruff) and the ANTLR backend (Kotlin, Java). Every claim was verified against the codebase (crates/,Cargo.tomlpins,xtasktargets,mehen-report,mehen-engine/src/diff.rs) before editing.Motivation
Several pages still described a pre-SQL, pre-ANTLR mehen:
index.mdxsaid "nine source languages" and omitted Java and SQL entirely.tree-sitter-markdown-text, which the code no longer references at all.<Note>claimed only source-code metrics ship) andmehen diff --fail-ondoc gating (documented as "planned").Changes
introduction.mdxindex.mdxconcepts/architecture.mdxmehen-antlr+mehen-sqlcrates, Java + SQL parser rows, pipeline-diagram update, and new ANTLR-backed analyzers / SQL is its own metric family sections.developers/update-grammars.mdxtree-sitter-markdown-text; corrected the pinning model (inline per-crate via__grammar_language()); noted PowerShell has nogrammar.rsand isn't a codegen target.developers/overview.mdxmehen-java+mehen-sqlto repo layout; ANTLR prereq now covers Java.guides/github-action.mdxdiff.rs:692); documented SQL in the diff; embedded screenshot.guides/pr-comment-design.mdx--fail-ongating; embedded screenshot.docs/images/pr-comment-metrics.pngVerification
<Frame>/<Card>/<Tabs>closed,<img>self-closed).index,introduction,supported-languages.markdown-text, "nine source", Kotlin-as-tree-sitter, stale Note).mint validate/mint broken-linksnot run — themintCLI requires an LTS Node (local env is Node 26). Substituted manual link-resolution + tag-balance checks. Worth a CI/LTS pass.Docs-only; no code or behavior changes.