Adds CLI executable cypherfmt to the language support package #518
+253
−2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
tomasnyberg
commented
May 30, 2025
| import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs'; | ||
| import { join } from 'path'; | ||
|
|
||
| const CYPHER_FILE_EXTENSIONS = ['.cy', '.cyp', '.cypher']; |
Contributor
Author
There was a problem hiding this comment.
I considered .cql as well but that seems to be used for other things (cassandra) as well. .cyp seems to be a legacy one
https://stackoverflow.com/questions/15161221/neo4j-script-file-format-is-there-any
Contributor
Author
There was a problem hiding this comment.
I guess someone could have cypher files with different extensions as well and want to be able to pass a flag, but I'm leaving that out for now...
Contributor
There was a problem hiding this comment.
I've added .cql here. Although I agree this is confusing for people that could be using that extension for something else, this should be aligned with the extensions the vscode plugin accepts. There's been requests in the past to support it in the vscode plugin when it initially was not
ncordon
approved these changes
May 30, 2025
JPryce-Aklundh
added a commit
to neo4j/docs-cypher
that referenced
this pull request
Jun 3, 2025
## Description Hey, docs team! For the past few months, as a master's thesis project, @simonthuresson and I have been working on a formatter for Cypher. In short, the formatter formats a Cypher query so that it follows the styleguide recommendations. During development, we found that the styleguide is quite far from comprehensive, and also some of the cypher snippets in the docs disagree with it as well. Filling out the missing pieces and addressing any ambiguity became a fairly large part of our project, and we wrote extensively about how we did so in our thesis, which you can find here: - [An Evaluation of Approaches to Code Formatting](https://lup.lub.lu.se/luur/download?func=downloadFile&recordOId=9188816&fileOId=9188817) In short, we did a survey on styling preferences, and talked to Cypher users to try and figure out what the most preferred way of writing Cypher was. We then took those learnings and implemented it in our formatter so that it could automatically enforce the rules. This PR is a draft of how we think the styleguide should be updated in accordance with the new rules. I did not put a lot of time into the wording and structure of the recommendations, as I would prefer to leave that to the professionals (you), but I provided some examples which hopefully illustrate the ideas well. If you want more detailed context on the rules, refer to the thesis (chapter 4 specifically). I also included a recommendation at the start of the style guide that users should use our formatter, as manual formatting is generally not a great idea. #### Note I included a link to the language support npm package that I claim provides a command-line tool. This is not actually live yet, but will be soon: neo4j/cypher-language-support#518 ## Try it out If you want to get a better feel for how the formatter works and how it applies the rules, you can try it out in: - Query in the Aura console (the ... menu -> format query) - [The Cypher Language Support CodeMirror playground](https://neo4j.github.io/cypher-language-support/) - [VS Code](https://marketplace.visualstudio.com/items?itemName=neo4j-extensions.neo4j-for-vscode) I would also recommend running any Cypher queries you add to the docs through the formatter first, to ensure that the styling is always consistent across all documentation. ## Note This is my last day at Neo4j, so I probably will not be able to respond to any comments on this PR. If you have questions, direct them at the language support team (#team-cypher-language-support), they have reviewed every line of code in the formatter, and are well aware of how it works. Feel free to completely change the wording I have used, this is just a first draft that I wanted to get in before leaving. --------- Co-authored-by: Jens Pryce-Åklundh <[email protected]>
JPryce-Aklundh
added a commit
to neo4j/docs-cypher
that referenced
this pull request
Jun 3, 2025
## Description Hey, docs team! For the past few months, as a master's thesis project, @simonthuresson and I have been working on a formatter for Cypher. In short, the formatter formats a Cypher query so that it follows the styleguide recommendations. During development, we found that the styleguide is quite far from comprehensive, and also some of the cypher snippets in the docs disagree with it as well. Filling out the missing pieces and addressing any ambiguity became a fairly large part of our project, and we wrote extensively about how we did so in our thesis, which you can find here: - [An Evaluation of Approaches to Code Formatting](https://lup.lub.lu.se/luur/download?func=downloadFile&recordOId=9188816&fileOId=9188817) In short, we did a survey on styling preferences, and talked to Cypher users to try and figure out what the most preferred way of writing Cypher was. We then took those learnings and implemented it in our formatter so that it could automatically enforce the rules. This PR is a draft of how we think the styleguide should be updated in accordance with the new rules. I did not put a lot of time into the wording and structure of the recommendations, as I would prefer to leave that to the professionals (you), but I provided some examples which hopefully illustrate the ideas well. If you want more detailed context on the rules, refer to the thesis (chapter 4 specifically). I also included a recommendation at the start of the style guide that users should use our formatter, as manual formatting is generally not a great idea. #### Note I included a link to the language support npm package that I claim provides a command-line tool. This is not actually live yet, but will be soon: neo4j/cypher-language-support#518 ## Try it out If you want to get a better feel for how the formatter works and how it applies the rules, you can try it out in: - Query in the Aura console (the ... menu -> format query) - [The Cypher Language Support CodeMirror playground](https://neo4j.github.io/cypher-language-support/) - [VS Code](https://marketplace.visualstudio.com/items?itemName=neo4j-extensions.neo4j-for-vscode) I would also recommend running any Cypher queries you add to the docs through the formatter first, to ensure that the styling is always consistent across all documentation. ## Note This is my last day at Neo4j, so I probably will not be able to respond to any comments on this PR. If you have questions, direct them at the language support team (#team-cypher-language-support), they have reviewed every line of code in the formatter, and are well aware of how it works. Feel free to completely change the wording I have used, this is just a first draft that I wanted to get in before leaving. --------- Co-authored-by: Jens Pryce-Åklundh <[email protected]>
JPryce-Aklundh
added a commit
to neo4j/docs-cypher
that referenced
this pull request
Jun 3, 2025
## Description Hey, docs team! For the past few months, as a master's thesis project, @simonthuresson and I have been working on a formatter for Cypher. In short, the formatter formats a Cypher query so that it follows the styleguide recommendations. During development, we found that the styleguide is quite far from comprehensive, and also some of the cypher snippets in the docs disagree with it as well. Filling out the missing pieces and addressing any ambiguity became a fairly large part of our project, and we wrote extensively about how we did so in our thesis, which you can find here: - [An Evaluation of Approaches to Code Formatting](https://lup.lub.lu.se/luur/download?func=downloadFile&recordOId=9188816&fileOId=9188817) In short, we did a survey on styling preferences, and talked to Cypher users to try and figure out what the most preferred way of writing Cypher was. We then took those learnings and implemented it in our formatter so that it could automatically enforce the rules. This PR is a draft of how we think the styleguide should be updated in accordance with the new rules. I did not put a lot of time into the wording and structure of the recommendations, as I would prefer to leave that to the professionals (you), but I provided some examples which hopefully illustrate the ideas well. If you want more detailed context on the rules, refer to the thesis (chapter 4 specifically). I also included a recommendation at the start of the style guide that users should use our formatter, as manual formatting is generally not a great idea. #### Note I included a link to the language support npm package that I claim provides a command-line tool. This is not actually live yet, but will be soon: neo4j/cypher-language-support#518 ## Try it out If you want to get a better feel for how the formatter works and how it applies the rules, you can try it out in: - Query in the Aura console (the ... menu -> format query) - [The Cypher Language Support CodeMirror playground](https://neo4j.github.io/cypher-language-support/) - [VS Code](https://marketplace.visualstudio.com/items?itemName=neo4j-extensions.neo4j-for-vscode) I would also recommend running any Cypher queries you add to the docs through the formatter first, to ensure that the styling is always consistent across all documentation. ## Note This is my last day at Neo4j, so I probably will not be able to respond to any comments on this PR. If you have questions, direct them at the language support team (#team-cypher-language-support), they have reviewed every line of code in the formatter, and are well aware of how it works. Feel free to completely change the wording I have used, this is just a first draft that I wanted to get in before leaving. --------- Co-authored-by: Jens Pryce-Åklundh <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Adds an executabale to the language support package that runs formatQuery, with the name
cypherfmt(our preferred name for the formatter). Also updates the README for the package to mention it to avoid any surprises, and adds "formatting" as a keyword for the package.CLI description (taken from the updated README for the language-support package)
This package includes a command-line tool for formatting Cypher queries using
cypherfmt. After installation, you can use it via thecypherfmtcommand:For more information, run
cypherfmt --help.Testing
I added two basic tests, that spawn a node process that runs the cli.mjs file and tests the following:
So I don't actually test the in-place formatting. I've intentionally avoided doing so since I'm not a big fan of having tests that modify files, and potentially induce a git diff if it's e.g. interrupted halfway, or errors out.
Missing features
I've kept this PR fairly light so the basics of the CLI can be settled on before introducing tons of functionality. Some things that might be nice to add in the future: