introduce tools commands for the compiler

Author: zth

CHANGELOG.md

@@ -1,5 +1,7 @@
 # master
 
+- Introduce `rescript-relay-compiler tools`, exposing Relay analysis commands like `definition-audit`, `find-schema-references`, `fragment-dependents`, and `print-operation`.
+
 # 4.3.0
 
 - Respect `noFutureProofEnums` in generated ReScript enum types, disabling `FutureAddedValue(...)` when configured.

packages/relay

@@ -102,7 +102,7 @@ module.exports = {
 };
 ```
 
-> All configuration options can be seen by running `yarn relay-compiler --help` in your project.
+> All configuration options can be seen by running `yarn rescript-relay-compiler --help` in your project.
 
 > Read more about [custom scalars here.](custom-scalars)
 
@@ -126,6 +126,13 @@ You can go ahead and start it in watch mode right away (`yarn relay:watch`) in a
 
 The Relay compiler is really awesome. If you're interested there's plenty more to read about the compiler and how RescriptRelay uses it [here](the-compiler).
 
+## Tools and utils
+
+RescriptRelay ships two CLIs that are useful to know about:
+
+- `rescript-relay-compiler` for running the compiler itself, plus Relay compiler tools like `yarn relay tools --help` or `yarn relay tools definition-audit --min-selection-lines 40`. These `tools` commands are especially useful for agents and automation, because they can introspect the Relay parts of your codebase directly.
+- `rescript-relay-cli` for RescriptRelay-specific utilities like `yarn rescript-relay-cli remove-unused-fields` and `yarn rescript-relay-cli format-all-graphql`.
+
 ## Setting up the Relay environment
 
 Finally time for some actual code. Next thing is setting up the Relay environment. The Relay environment consists of a network layer responsible for dispatching your GraphQL queries, and a store responsible for storing data and supplying it to your components.

rescript-relay-documentation/docs/getting-started.md

@@ -6,6 +6,28 @@ sidebar_label: RescriptRelay CLI
 
 `rescript-relay-cli` is a CLI for making life using RescriptRelay just a tiny bit easier. It's automatically included with every release of `rescript-relay`.
 
+There are two different CLIs worth knowing about:
+
+- `rescript-relay-cli` for RescriptRelay-specific maintenance commands like removing unused fields and formatting GraphQL.
+- `rescript-relay-compiler` for the Relay compiler itself, including the `tools` analysis commands.
+
+At some point, these two will likely be merged into one, but for now they're separate.
+
+## RescriptRelay compiler tools
+
+The RescriptRelay compiler tools ship through `rescript-relay-compiler`, not `rescript-relay-cli`.
+
+Examples:
+
+```bash
+rescript-relay-compiler tools --help
+rescript-relay-compiler tools definition-audit --min-selection-lines 40
+rescript-relay-compiler tools find-schema-references User.name
+rescript-relay-compiler tools fragment-dependents UserCard_user --transitive
+```
+
+Use these compiler tools for codebase audits, impact analysis, and mechanical Relay refactors. Keep using `rescript-relay-cli` for the commands below. They're especially useful for code agents.
+
 ## Commands
 
 ### remove-unused-fields