diff --git a/en/clice/cli/analyze.md b/en/clice/cli/analyze.md index b50c55882..5960bb73f 100644 --- a/en/clice/cli/analyze.md +++ b/en/clice/cli/analyze.md @@ -4,7 +4,7 @@ `clice analyze` reads the persisted index and reports facts a coding agent turns into refactoring decisions. It never builds or times anything: it describes the code, and the agent — with the code at hand — decides what to change. Like `clice query`, it reads the index `clice index` builds and prints JSON on stdout. -**Usage**: `clice analyze [--workspace ] [--configuration ] [options]` +**Usage**: `clice analyze [ [...]] [--workspace ] [--configuration ] [options]` ## Modules @@ -12,24 +12,24 @@ Every file in the scope belongs to a module, by default its directory. A module depends on another when one of its files names an entity a file of the other provides: a spelled name, a name a macro expansion produces in that file, or the template an explicit specialization specializes. The file providing an entity is a header defining it, else a header declaring it, else the source defining it. A dependency from a header is an interface edge, which would become an import of the module's interface; one only from sources is an implementation edge, which never closes a cycle because an implementation unit may import a module above it. Textual fragments such as `.inc` and `.def` files count as part of the files including them. A header only its own module's sources use, directly or through other such headers, is an internal partition: it adds nothing to the module's interface, and none of its dependencies are interface edges. -- `--scope ` analyzes only the files the globs match, as workspace-relative paths; by default every indexed file under the workspace outside a dot directory. -- `--depth ` names a file's default module by the first `n` segments of its directory instead of all of them. +- `--scope ` analyzes only the files the glob matches, as a workspace-relative path; repeat it for several. By default every indexed file under the workspace outside a dot directory. +- `--dir-depth ` names a file's default module by the first `n` segments of its directory instead of all of them. - `--partition ` assigns modules by globs, first match wins: `{"modules": [{"name": "core", "files": ["src/support/**", "src/vfs/**"]}]}`. Files no glob claims keep their directory module. For the `interface` view and [modularize](./modularize.md), `"textual": true` keeps a module headers, `"external": true` marks one an existing module stands for (the standard library), and `"provides": "std.compat"` names the module exporting a module's names, read from the libc++ module sources `--std ` names. -- `--move =,...` and `--merge +[+...],...` evaluate a hypothetical change without making it. +- `--move =` and `--merge +[+...]` evaluate a hypothetical change without making it; repeat them for several. - `--move-entity =
` evaluates moving a declaration, with its members and what their definitions name, to another header, existing or new; repeat it for several moves. The [locator](./query.md#locators) names the declaration by its whole name: a function's overloads in one scope move together, the locator the `edge` view prints picks one of them, and a name several scopes spell is an error listing the candidates. -- `--annotation ,...` and `--churn-since ` weigh the results; see [annotations](#annotations). -- `--view ` chooses the answer, `overview` by default. - -| View | Answers | -| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `overview` | the modules by layer, the edges with sample entities, the cycles with the lightest set of edges whose removal breaks each, header cycles inside a module, the number of internal partitions, the deepest import chain, rebuild totals, hotspots, move and split candidates, and obstacle counts | -| `edge --from --to ` | every entity the edge carries, with its locator, owner and the `file:line` of each use | -| `module --module ` | each file's dependencies and dependents by module, the module's internal partitions, and its other headers grouped by the modules using them — the lines a directory splits along | -| `file --file ` | what the file names by module, who names its entities, and its annotations | -| `obstacles` | every construct listed below | -| `macros` | macros used outside the file defining them, by module: imports carry no macros, so each reaches its users through a textual header | -| `impact` | per header, the units an edit to it rebuilds today and under the partition, and whether it is an internal partition | -| `interface [--module ]` | per module, what a wrapper module over its headers needs: the modules it imports, its entries with the name other modules include them by, its namespace-scope names with their headers, its namespace aliases, the headers that stay textual, the TU-local entities its headers share with other wrapped modules, the macros importers need, and the macros of other modules its headers read | +- `--annotation ` and `--churn-since ` weigh the results of the views that rank by them; see [annotations](#annotations). +- The view, a word after `modules`, chooses the answer, the overview when there is none. + +| View | Answers | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| (no view) | the modules by layer, the edges with sample entities, the cycles with the lightest set of edges whose removal breaks each, header cycles inside a module, the number of internal partitions, the deepest import chain, rebuild totals, hotspots, move and split candidates, and obstacle counts | +| `edge ` | every entity the edge carries, with its locator, owner and the `file:line` of each use | +| `module ` | each file's dependencies and dependents by module, the module's internal partitions, and its other headers grouped by the modules using them — the lines a directory splits along | +| `file ` | what the file names by module, who names its entities, and its annotations | +| `obstacles` | every construct listed below | +| `macros` | macros used outside the file defining them, by module: imports carry no macros, so each reaches its users through a textual header | +| `impact` | per header, the units an edit to it rebuilds today and under the partition, and whether it is an internal partition | +| `interface []` | per module, what a wrapper module over its headers needs: the modules it imports, its entries with the name other modules include them by, its namespace-scope names with their headers, its namespace aliases, the headers that stay textual, the TU-local entities its headers share with other wrapped modules, the macros importers need, and the macros of other modules its headers read | The overview's hotspots, move candidates and split candidates are capped by `--limit` (20 by default); modules, edges and cycles are always complete. diff --git a/en/clice/cli/format.md b/en/clice/cli/format.md index a56afa260..e9fd95511 100644 --- a/en/clice/cli/format.md +++ b/en/clice/cli/format.md @@ -8,7 +8,7 @@ into clice, as the editor does, several files at a time, with the settings of its own: the style comes from clang-format's own discovery, the nearest `.clang-format` above each file. -**Usage**: `clice format [--workspace ] [--configuration ] [--check] [--jobs ] [...]` +**Usage**: `clice format [...] [--workspace ] [--configuration ] [--check] [--jobs ]` Without paths it formats the build's own files: every translation unit of the compilation database and every file with a C-family suffix they include that diff --git a/en/clice/cli/index.md b/en/clice/cli/index.md index 05bd969a0..412ea3c13 100644 --- a/en/clice/cli/index.md +++ b/en/clice/cli/index.md @@ -4,7 +4,7 @@ `clice index` builds the persistent symbol index of a workspace ahead of time, so an editor session starts warm instead of indexing in the background while you work. It runs the same indexing pipeline as the server with a worker pool, and the two share one index per build configuration under `cache_dir`. -**Usage**: `clice index [--workspace ] [--configuration ] [--workers ]` +**Usage**: `clice index [--workspace ] [--configuration ] [--jobs ]` One process writes the index of a workspace at a time. While an editor session has the workspace open, its server holds that role, so `clice index` asks the server to run the sweep and waits for the result instead of starting a worker pool of its own; the summary says so. A lock held by a process that cannot be asked (another `clice index`, a server of a different clice build, or one whose configuration keeps background indexing off) makes the command fail with the holder named — rerun it when that process is done. @@ -12,12 +12,12 @@ The run is resumable: interrupting it with Ctrl-C or SIGTERM (what `timeout` and ## Inspecting the index -The same command reads the persisted index without touching it. Every mode prints plain lines meant for a terminal or `grep`, and works while an editor session holds the index open. +The same command's operations read the persisted index without touching it. Each prints plain lines meant for a terminal or `grep`, and works while an editor session holds the index open. -- `clice index --stats [--top ]` prints what the index contains: the translation units and file shards, the byte split of the shard columns and of the global symbol table, how symbols distribute by reference-file count and name length, how file shards distribute by variant count, and the largest shards. `--variants` appends one tab-separated line per file shard with its variant count, for comparing two runs. -- `clice index --show-symbol ` prints what the index records about a symbol: its kind, name and flags, the parent chain that spells its qualified name, the file holding its canonical declaration, and per file how many definitions, declarations and references it has. The name is matched as displayed (`Box`) or qualified (`ns::Box`); `#` names a symbol by its identity, which is how file-local symbols are reached. -- `clice index --show-file ` prints a file's persisted rows: the content generation the rows were built from, every variant with the translation units that contributed it, the row counts by relation kind, and the file-local symbols whose identities live only in this file. -- `clice index --show-tu ` prints a translation unit's manifest: when it was indexed, the files it contributed rows to, and its include tree. +- `clice index stats [--limit ]` prints what the index contains: the translation units and file shards, the byte split of the shard columns and of the global symbol table, how symbols distribute by reference-file count and name length, how file shards distribute by variant count, and the largest shards. `--variants` appends one tab-separated line per file shard with its variant count, for comparing two runs. +- `clice index symbol ` prints what the index records about the symbols a [locator](./query.md#locators) names: their kind, name and flags, the parent chain that spells the qualified name, the file holding the canonical declaration, and per file how many definitions, declarations and references each has. A name names every symbol spelling it whole (`Box`, `ns::Box`) that `clice query` finds; an id names its symbol even when no file declares it, as with a macro defined on the command line. +- `clice index file ` prints a file's persisted rows: the content generation the rows were built from, every variant with the translation units that contributed it, the row counts by relation kind, and the file-local symbols whose identities live only in this file. +- `clice index unit ` prints a translation unit's manifest: when it was indexed, the files it contributed rows to, and its include tree. ## Examples diff --git a/en/clice/cli/lint.md b/en/clice/cli/lint.md index 71dad13be..353e4d74c 100644 --- a/en/clice/cli/lint.md +++ b/en/clice/cli/lint.md @@ -6,7 +6,7 @@ clice integrates clang-tidy as a built-in linting engine. `clice lint` runs the checks of your `.clang-tidy` over the workspace's translation units with a resident worker pool and prints one merged report. -**Usage**: `clice lint [--workspace ] [--configuration ] [--workers ] [--index]` +**Usage**: `clice lint [--workspace ] [--configuration ] [--jobs ] [--index]` Runs clang-tidy over every translation unit of the compilation database that the lint set below admits, prints the merged findings, and exits non-zero when diff --git a/en/clice/cli/modularize.md b/en/clice/cli/modularize.md index 846bcdc7e..3de678130 100644 --- a/en/clice/cli/modularize.md +++ b/en/clice/cli/modularize.md @@ -6,9 +6,9 @@ The program's own code can follow: modules the partition marks for rewriting have their files rewritten in place into module units, headers into partitions and includes into imports. -**Usage**: `clice modularize --partition --out [--std ] [--no-mirrors] [--scope ] [--workspace ] [--configuration ]` +**Usage**: `clice modularize --partition --out [--std ] [--no-mirrors] [--scope ...] [--workspace ] [--configuration ]` -Every fact comes from the persisted index, as [`clice analyze modules --view interface`](./analyze.md#modules) reports it: run `clice index` first. The command writes files and prints what the build needs; it never edits a build file. +Every fact comes from the persisted index, as [`clice analyze modules interface`](./analyze.md#modules) reports it: run `clice index` first. The command writes files and prints what the build needs; it never edits a build file. ## Partition @@ -57,7 +57,7 @@ Which modules to rewrite and how coarse they are is the partition's choice: one A wrapping holds what the headers declare and define in one build configuration: the platform's C library, the macros a library's configuration header sets, the names a library declares for one target alone. A program built for several platforms or configurations runs modularize once for each, on an index of that configuration and into a directory of its own, then merges the results. -**Usage**: `clice modularize --merge --out [--no-mirrors]` +**Usage**: `clice modularize merge --out [--no-mirrors]` ```json { @@ -202,7 +202,7 @@ tests/modularize/program/01_one_module - Only the files the index holds are rewritten: a source no compilation of the indexed configuration enters, as another platform's, keeps its includes. - Clang does not take the global module fragment of an implementation partition as reachable from a unit importing it through another partition, though the standard has that unit import it too. A rewritten file therefore includes the headers that stay headers which such partitions include, and parses them again. - An include of a rewritten header under a preprocessor condition becomes an unconditional import. -- A header compiles once as a partition: one whose declarations differ by includer, or that tests a macro its includers define, keeps one reading only. `clice analyze modules --view obstacles` lists such headers to clear first. +- A header compiles once as a partition: one whose declarations differ by includer, or that tests a macro its includers define, keeps one reading only. `clice analyze modules obstacles` lists such headers to clear first. - An include of a file outside the scope stays where it is written; past the leading directives it lands in the purview, attaching what it declares to the module. - modularize stops with an error, before writing anything, when a header that stays a header includes a rewritten one or when a file it writes would overwrite another. - What the compiler reports on the rewritten tree is left to the build: headers of one module or of two rewritten modules including each other, a `static` entity in a header that becomes a partition, a rewritten source defining what a header that stays a header declares. diff --git a/en/clice/cli/overview.md b/en/clice/cli/overview.md index 57f2a8f31..fdaaf7b6e 100644 --- a/en/clice/cli/overview.md +++ b/en/clice/cli/overview.md @@ -8,13 +8,24 @@ clice is one binary. Editors launch `clice serve` and talk to it over LSP; the o | `lint` | Run clang-tidy over every translation unit with a worker pool. | [lint](./lint.md) | | `index` | Index a workspace ahead of time so the server starts warm. | [index](./index.md) | | `format` | Format the workspace's files with clang-format. | [format](./format.md) | -| `inspect` | Run one feature on source files and print the raw result as JSON. | | +| `inspect` | Run one feature on a source file and print the raw result as JSON. | | | `query` | Ask the persisted index about symbols, references, call graphs and files. | [query](./query.md) | | `refactor` | Rename a symbol across the workspace from the persisted index. | [refactor](./refactor.md) | | `analyze` | Report facts for refactoring, such as module dependencies and cycles. | [analyze](./analyze.md) | | `modularize` | Wrap third-party libraries as C++20 modules, rewrite the program into module units. | [modularize](./modularize.md) | | `scan` | Scan the include and module dependencies of the build, and time the scan. | [scan](./scan.md) | -`inspect` works today but has no page yet; its options are documented by `clice inspect --help`. +`inspect` works today but has no page yet; its operations and options are documented by `clice inspect --help`. -`serve`, `index`, `lint`, `format`, `inspect`, `scan`, `query`, `refactor`, `analyze` and `modularize` take `--configuration ` to pin the build configuration for the run, over the selection persisted from the editor; see [switching configurations](../guide/configuration.md#switching-configurations). +## Arguments + +Every subcommand takes its arguments the same way: + +``` +clice [] [...] [--option...] +``` + +- A command that does several things names the one to do by a word after it: `clice query references`, `clice index stats`, `clice analyze modules edge`. A command whose own job comes first runs it when no word follows: `clice index` indexes, `clice analyze modules` gives the overview. `--help` after any command or operation lists what it takes. +- The target, the symbol or file an operation is about, follows the operation: `clice query references "shapes::Circle::area"`, `clice query document-symbols src/main.cpp`. A symbol is named by a [locator](./query.md#locators) wherever one is taken; a file by its path, relative to the workspace (for `inspect`, to the current directory) or absolute. The files a command reads or writes itself, such as a partition or an output directory, are relative to the current directory. +- Options come after the operation. An option takes several values by being repeated: `--scope 'src/**' --scope 'include/**'`. +- `--workspace ` names the workspace, the current directory by default (`inspect` takes the project the file is in, as the editor does); `--configuration ` pins the build configuration over the selection persisted from the editor (see [switching configurations](../guide/configuration.md#switching-configurations)); `-j`, `--jobs ` is how many units or files `index`, `lint` and `format` work on at once; `--log-level` sets what is logged to stderr, warnings and errors by default (`serve`, whose stderr an editor shows, from `info`); the session logs of `serve`, `index` and `lint` keep `info` whatever it is. diff --git a/en/clice/cli/query.md b/en/clice/cli/query.md index 4105fa7ba..17989f68e 100644 --- a/en/clice/cli/query.md +++ b/en/clice/cli/query.md @@ -4,16 +4,16 @@ `clice query` asks the persisted index a structured question and prints the answer as JSON on stdout — for scripts and coding agents that want the facts a language server has without speaking LSP. It reads the index straight from disk, the same index `clice index` builds and an editor session keeps up to date, so it works while the editor is open and needs no server when it is not. -**Usage**: `clice query --method [--workspace ] [--configuration ] [--fresh] [question options]` +**Usage**: `clice query [ | ] [--workspace ] [--configuration ] [--fresh] [question options]` ## Questions -- `symbolSearch --symbol [--limit ]` lists the symbols a [locator](#locators) matches, best first, with their kind, file, line, container and `symbol`. -- `definition`, `readSymbol`, `references [--include-declaration]`, `callGraph [--direction callers|callees|both]` and `typeHierarchy [--direction supertypes|subtypes|both]` answer about the one symbol `--symbol ` names. A locator several symbols match lists them as `candidates`; a name none spells exactly lists the closest matches the same way. `definition` and `readSymbol` also give the symbol's `documentation`: its documentation comment as markdown, read as the editor's hover reads it — `@param`, `@return` and `@copydoc` resolved, an undocumented override showing what it overrides. -- `documentSymbols --path ` is the file's outline. -- `compileCommand --path ` is the command the editor would compile the file with, and where it came from: the file's own database entry, a host source for a header, a rule's default command, a command borrowed from a nearby unit — for a provisional member (`provisional`) or a file outside the build (`inferred`) — or the fallback. The command is the one the compiler resolves it to, with its target and system include directories; when asking the compiler failed, `toolchainError` says why and the command stays the unresolved driver command. -- `projectFiles [--filter all|source|header|module]` lists the build's files; `fileDeps --path [--direction includes|includers|both] [--depth ]` follow the include graph, and `impactAnalysis --path ` the include graph and the files that import a module the file is part of. -- `counterparts --path ` lists the files the file pairs with — a header's sources, a source's headers, a module's interface and implementation units — best first, each with its reasons, and names the one an editor would open without asking as `preferred` (see [Switch Source/Header](../features/navigation.md#switch-source-header)). +- `symbol-search [] [--limit ]` lists the symbols a [locator](#locators) matches, best first, with their kind, file, line, container and `symbol`. +- `definition `, `read-symbol `, `references [--include-declaration]`, `call-graph [--direction callers|callees|both]` and `type-hierarchy [--direction supertypes|subtypes|both]` answer about the one symbol the locator names. A locator several symbols match lists them as `candidates`; a name none spells exactly lists the closest matches the same way. `definition` and `read-symbol` also give the symbol's `documentation`: its documentation comment as markdown, read as the editor's hover reads it — `@param`, `@return` and `@copydoc` resolved, an undocumented override showing what it overrides. +- `document-symbols ` is the file's outline. +- `compile-command ` is the command the editor would compile the file with, and where it came from: the file's own database entry, a host source for a header, a rule's default command, a command borrowed from a nearby unit — for a provisional member (`provisional`) or a file outside the build (`inferred`) — or the fallback. The command is the one the compiler resolves it to, with its target and system include directories; when asking the compiler failed, `toolchainError` says why and the command stays the unresolved driver command. +- `project-files [--filter all|source|header|module]` lists the build's files; `file-deps [--direction includes|includers|both] [--depth ]` follow the include graph, and `impact-analysis ` the include graph and the files that import a module the file is part of. +- `counterparts ` lists the files the file pairs with — a header's sources, a source's headers, a module's interface and implementation units — best first, each with its reasons, and names the one an editor would open without asking as `preferred` (see [Switch Source/Header](../features/navigation.md#switch-source-header)). Paths are workspace-relative or absolute in questions, absolute in answers; lines are 1-based. @@ -38,11 +38,11 @@ A locator names symbols, wherever a command takes one. It is one string: spaces A local, a parameter and an entity of internal linkage — `static`, or in an anonymous namespace — are known only to the files that see them: a name finds them only together with `path:` naming their file or its directory. -Every symbol an answer lists carries `symbol`, a locator naming it back: its id, followed by `path:` and its file for a symbol only some files see. Pass it to `--symbol` as it is. On a shell command line, quote the whole locator: `#` there starts a comment, `<` and `>` redirect and `*` expands. +Every symbol an answer lists carries `symbol`, a locator naming it back: its id, followed by `path:` and its file for a symbol only some files see. Pass it back as it is. On a shell command line, quote the whole locator: `#` there starts a comment, `<` and `>` redirect and `*` expands. ## Answers -Every answer is one JSON object: `{"result": ..., "stale": [...]}` on success, `{"error": "...", "stale": [...]}` with exit code 1 when the question cannot be answered (an unknown symbol, a file that does not exist, an option value it does not take), or 2 when the arguments do not parse. An error for a locator that matched several symbols lists them in `candidates`, each with its `symbol`. +Every answer is one JSON object: `{"result": ..., "stale": [...]}` on success, `{"error": "...", "stale": [...]}` with exit code 1 when the question cannot be answered (an unknown symbol, a file that does not exist, an option value it does not take), or 2 when the arguments do not parse (an unknown question, a locator or file missing or too many). An error for a locator that matched several symbols lists them in `candidates`, each with its `symbol`. `stale` lists the files whose rows the answer had to leave out because their content on disk no longer matches what was indexed — the positions the index holds for them would point into text that moved. A file that changed only because a header it includes changed keeps answering from its last rows. A symbol whose definition sits in a stale file is reported as not found, with the file named, so a reader can tell "does not exist" from "not indexed yet". Only files the answer consulted are checked: a symbol added to a file after it was indexed is simply absent, since no row leads to that file — `--fresh` is the way to ask about the current disk. The index never sees unsaved editor buffers: the disk is the truth it describes. diff --git a/en/clice/cli/refactor.md b/en/clice/cli/refactor.md index ede96a714..aa514b841 100644 --- a/en/clice/cli/refactor.md +++ b/en/clice/cli/refactor.md @@ -4,7 +4,7 @@ `clice refactor` rewrites the workspace's sources from the persisted index, the same index `clice query` reads. Nothing is compiled, so a refactoring over a large tree takes about as long as a query. `rename` is the one refactoring today; an editor's rename runs the same engine. -**Usage**: `clice refactor rename (--symbol --to | --spec ) [--workspace ] [--configuration ] [--dry-run] [--fresh]` +**Usage**: `clice refactor rename ( | --spec ) [--workspace ] [--configuration ] [--dry-run] [--fresh]` ## Rename @@ -98,7 +98,7 @@ A name several symbols spell renames nothing until a locator picks one. A name two symbols spell lists both, and a scoped name or a candidate's `symbol` picks one Nothing is renamed while the name is ambiguous. Each candidate carries a -`symbol` to pass back to `--symbol` as it is. +`symbol` to pass back as it is. ```case tests/refactor/locators/02_ambiguous_name diff --git a/en/clice/features/code-action.md b/en/clice/features/code-action.md index c38fa3983..00cf0d74a 100644 --- a/en/clice/features/code-action.md +++ b/en/clice/features/code-action.md @@ -5,7 +5,7 @@ GENERATED markers by hand — edit the cases' README.md and run `pixi run update-feature-docs`. --> -clice offers code actions on a selection: refactorings that generate or reshape code from what the compiler knows about it, quick fixes for names no header declares, and the fixes the compiler and clang-tidy attach to their diagnostics. Every action is computed to completion when it is offered, so applying one never waits on a second request; edits carry the document version they were computed for, and an editor refuses them once the buffer moved on. The same actions run headless through `clice inspect code_action`. +clice offers code actions on a selection: refactorings that generate or reshape code from what the compiler knows about it, quick fixes for names no header declares, and the fixes the compiler and clang-tidy attach to their diagnostics. Every action is computed to completion when it is offered, so applying one never waits on a second request; edits carry the document version they were computed for, and an editor refuses them once the buffer moved on. The same actions run headless through `clice inspect code-action`. An action anchors on the innermost construct the selection covers — a method declaration, a class name, a `switch`, an `auto` — so the list stays short: a click on a method name offers what applies to that method, a click on the class name what applies to the class. diff --git a/en/clice/features/navigation.md b/en/clice/features/navigation.md index c279126fc..281da51d4 100644 --- a/en/clice/features/navigation.md +++ b/en/clice/features/navigation.md @@ -1616,7 +1616,7 @@ tests/workspace_symbol/projects/01_closed_files ## Switch Source/Header -Open the file the current one pairs with: a header's source, a source's header, a module interface's implementation units, an implementation unit's interface. In VS Code it is **Switch Source/Header** in the editor's right-click menu, `Alt+O`, or **Clice: Switch Source/Header** in the Command Palette; Neovim runs it as `:LspCliceSwitchSourceHeader`, and `clice query --method counterparts --path ` answers the same on the command line. Zed lets no extension add a command, and its own _switch source header_ works with clangd only. +Open the file the current one pairs with: a header's source, a source's header, a module interface's implementation units, an implementation unit's interface. In VS Code it is **Switch Source/Header** in the editor's right-click menu, `Alt+O`, or **Clice: Switch Source/Header** in the Command Palette; Neovim runs it as `:LspCliceSwitchSourceHeader`, and `clice query counterparts ` answers the same on the command line. Zed lets no extension add a command, and its own _switch source header_ works with clangd only. The candidates come from what the build and the index already know, so nothing is compiled for the answer: the files of the same name on the other side — in the file's own directory, or elsewhere in the workspace when one includes the other —, the declarations one holds that the other defines, and module declarations. Each candidate carries its reasons. The editor opens the best one directly when it is the only candidate or beats every other: it has each of the other's reasons among shared declarations and the same name, at least as many shared declarations, and either a reason more, twice the shared declarations when both share some, or — neither sharing any — a module pairing the other lacks. Otherwise it lists the candidates to pick from. diff --git a/en/clice/guide/configuration.md b/en/clice/guide/configuration.md index 8954fee7c..b428d449e 100644 --- a/en/clice/guide/configuration.md +++ b/en/clice/guide/configuration.md @@ -834,7 +834,7 @@ tests/project/rules/09_remove_flags ## Switching Configurations -The `configuration` tags on rules form a menu, and one tag is active per project; untagged rules always apply. The active one is, in priority order, the `--configuration ` argument (accepted by `clice serve`, `clice index`, `clice lint` and `clice inspect`), the persisted selection, or `default_configuration`. A selection is made from the editor — in VS Code the status bar shows the active configuration and clicking it opens the menu, other clients call `clice/switchConfiguration` — and is stored in `state.json` under `cache_dir`, never in `clice.toml`; it takes effect when the server is started again, which the VS Code extension does on its own. Each configuration keeps its own index under `cache_dir`, so switching back and forth never reindexes what a configuration already indexed. The tags are also how the batch commands choose an index: `clice index --configuration release` builds the release index, and `clice index --stats` reports the index of the configuration it resolves the same way. +The `configuration` tags on rules form a menu, and one tag is active per project; untagged rules always apply. The active one is, in priority order, the `--configuration ` argument (accepted by `clice serve`, `clice index`, `clice lint` and `clice inspect`), the persisted selection, or `default_configuration`. A selection is made from the editor — in VS Code the status bar shows the active configuration and clicking it opens the menu, other clients call `clice/switchConfiguration` — and is stored in `state.json` under `cache_dir`, never in `clice.toml`; it takes effect when the server is started again, which the VS Code extension does on its own. Each configuration keeps its own index under `cache_dir`, so switching back and forth never reindexes what a configuration already indexed. The tags are also how the batch commands choose an index: `clice index --configuration release` builds the release index, and `clice index stats` reports the index of the configuration it resolves the same way. diff --git a/en/clice/guide/quick-start.md b/en/clice/guide/quick-start.md index d43731fc2..c75a52249 100644 --- a/en/clice/guide/quick-start.md +++ b/en/clice/guide/quick-start.md @@ -111,4 +111,4 @@ clice index --workspace /path/to/project The run is resumable — interrupting it with Ctrl-C saves progress, and the next invocation continues where it left off instead of starting over. -`clice index --stats` prints what the persisted index currently contains. +`clice index stats` prints what the persisted index currently contains. diff --git a/sources/clice/cases/analyze/annotations/01_compile_time.json b/sources/clice/cases/analyze/annotations/01_compile_time.json index 9dc09d06a..2c834ec88 100644 --- a/sources/clice/cases/analyze/annotations/01_compile_time.json +++ b/sources/clice/cases/analyze/annotations/01_compile_time.json @@ -56,7 +56,7 @@ } }, { - "label": "$ clice analyze modules --view impact", + "label": "$ clice analyze modules impact", "value": { "stdout": "[\n {\n \"path\": \"core/fast.h\",\n \"baseline\": 1,\n \"partitioned\": 3,\n \"churn\": null,\n \"internal\": false\n },\n {\n \"path\": \"core/str.h\",\n \"baseline\": 3,\n \"partitioned\": 3,\n \"churn\": null,\n \"internal\": false\n },\n {\n \"path\": \"util/clock.h\",\n \"baseline\": 2,\n \"partitioned\": 2,\n \"churn\": null,\n \"internal\": false\n }\n]", "stderr": "warning: no churn annotation: Process git ended with exit code 128", @@ -64,7 +64,7 @@ } }, { - "label": "$ clice analyze modules --view impact --annotation compile_time.json", + "label": "$ clice analyze modules impact --annotation compile_time.json", "value": { "stdout": "[\n {\n \"path\": \"core/fast.h\",\n \"baseline\": 10,\n \"partitioned\": 12,\n \"churn\": null,\n \"internal\": false\n },\n {\n \"path\": \"core/str.h\",\n \"baseline\": 12,\n \"partitioned\": 12,\n \"churn\": null,\n \"internal\": false\n },\n {\n \"path\": \"util/clock.h\",\n \"baseline\": 11,\n \"partitioned\": 11,\n \"churn\": null,\n \"internal\": false\n }\n]", "stderr": "warning: no churn annotation: Process git ended with exit code 128", diff --git a/sources/clice/cases/analyze/views/01_edge.json b/sources/clice/cases/analyze/views/01_edge.json index 235090799..a9d3ea57f 100644 --- a/sources/clice/cases/analyze/views/01_edge.json +++ b/sources/clice/cases/analyze/views/01_edge.json @@ -46,7 +46,7 @@ } }, { - "label": "$ clice analyze modules --view edge --from util --to core", + "label": "$ clice analyze modules edge util core", "value": { "stdout": "{\n \"from\": \"util\",\n \"to\": \"core\",\n \"entities\": [\n {\n \"id\": \"#478ec97a46ae1c6f\",\n \"entity\": \"Str\",\n \"owner\": \"core/str.h\",\n \"users\": [\n \"util/clock.h:5\",\n \"util/fmt.cpp:3\"\n ],\n \"interface\": true\n },\n {\n \"id\": \"#b244f96089a92435\",\n \"entity\": \"length\",\n \"owner\": \"core/str.h\",\n \"users\": [\n \"util/clock.h:8\",\n \"util/fmt.cpp:4\"\n ],\n \"interface\": true\n }\n ]\n}", "exit": 0 diff --git a/sources/clice/cases/compile/languages/01_assembler.json b/sources/clice/cases/compile/languages/01_assembler.json index 9d914f7b2..88f1a849f 100644 --- a/sources/clice/cases/compile/languages/01_assembler.json +++ b/sources/clice/cases/compile/languages/01_assembler.json @@ -99,7 +99,7 @@ "name": "index", "blocks": [ { - "label": "$ clice index --workers 1", + "label": "$ clice index --jobs 1", "value": { "stdout": "Indexed 1 translation unit in #s: 1 file shard (# B), 1 symbol.\nSession log: ${WS}/.clice/logs/${SESSION}", "exit": 0 diff --git a/sources/clice/cases/index/delegation/01_running_server.json b/sources/clice/cases/index/delegation/01_running_server.json index 6a7b02399..8a72f453a 100644 --- a/sources/clice/cases/index/delegation/01_running_server.json +++ b/sources/clice/cases/index/delegation/01_running_server.json @@ -24,21 +24,21 @@ "name": "asks the running server to index", "blocks": [ { - "label": "$ clice index --workers 2", + "label": "$ clice index --jobs 2", "value": { "stdout": "Indexed through the running clice server (pid #).", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol extra --fresh", + "label": "$ clice query symbol-search extra --fresh", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"extra\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 5,\n \"container\": null,\n \"symbol\": \"#c9be3d07e9d6b64f\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol extra", + "label": "$ clice query symbol-search extra", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"extra\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 5,\n \"container\": null,\n \"symbol\": \"#c9be3d07e9d6b64f\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 @@ -57,14 +57,14 @@ } }, { - "label": "$ clice query --method symbolSearch --symbol compute --fresh", + "label": "$ clice query symbol-search compute --fresh", "value": { "stdout": "{\n \"error\": \"another clice process (pid #) holds the index writer lock at ${WS}/.clice; retry when it is done\",\n \"stale\": []\n}", "exit": 1 } }, { - "label": "$ clice query --method symbolSearch --symbol compute", + "label": "$ clice query symbol-search compute", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"compute\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 4,\n \"container\": null,\n \"symbol\": \"#81df9416985c4402\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 diff --git a/sources/clice/cases/lint/checks/02_compiler_warnings.json b/sources/clice/cases/lint/checks/02_compiler_warnings.json index 2452a4fa5..90488aa2b 100644 --- a/sources/clice/cases/lint/checks/02_compiler_warnings.json +++ b/sources/clice/cases/lint/checks/02_compiler_warnings.json @@ -24,7 +24,7 @@ "name": "test", "blocks": [ { - "label": "$ clice lint --workers 2", + "label": "$ clice lint --jobs 2", "value": { "stdout": "${WS}/main.cpp:2:9: warning: unused variable 'unused' [clang-diagnostic-unused-variable]\nLinted 1 translation unit in #s: 1 finding.", "exit": 1 diff --git a/sources/clice/cases/lint/findings/01_header_findings_merge.json b/sources/clice/cases/lint/findings/01_header_findings_merge.json index 23d1f1180..b887a32a6 100644 --- a/sources/clice/cases/lint/findings/01_header_findings_merge.json +++ b/sources/clice/cases/lint/findings/01_header_findings_merge.json @@ -34,7 +34,7 @@ "name": "test", "blocks": [ { - "label": "$ clice lint --workers 2", + "label": "$ clice lint --jobs 2", "value": { "stdout": "${WS}/average.cpp:4:12: warning: result of integer division used in a floating point context; possible loss of precision [bugprone-integer-division]\n${WS}/ratio.h:4:12: warning: result of integer division used in a floating point context; possible loss of precision [bugprone-integer-division]\nLinted 2 translation units in #s: 2 findings.", "exit": 1 diff --git a/sources/clice/cases/lint/findings/03_suppression_comments.json b/sources/clice/cases/lint/findings/03_suppression_comments.json index 20c239b74..7f4120efb 100644 --- a/sources/clice/cases/lint/findings/03_suppression_comments.json +++ b/sources/clice/cases/lint/findings/03_suppression_comments.json @@ -29,7 +29,7 @@ "name": "test", "blocks": [ { - "label": "$ clice lint --workers 2", + "label": "$ clice lint --jobs 2", "value": { "stdout": "${WS}/main.cpp:8:23: warning: use nullptr [modernize-use-nullptr]\n${WS}/registry.h:8:30: warning: use nullptr [modernize-use-nullptr]\nLinted 1 translation unit in #s: 2 findings.", "exit": 1 diff --git a/sources/clice/cases/lint/scope/01_keep_files_out.json b/sources/clice/cases/lint/scope/01_keep_files_out.json index 653f6343b..2e0a6a521 100644 --- a/sources/clice/cases/lint/scope/01_keep_files_out.json +++ b/sources/clice/cases/lint/scope/01_keep_files_out.json @@ -39,7 +39,7 @@ "name": "test", "blocks": [ { - "label": "$ clice lint --workers 2", + "label": "$ clice lint --jobs 2", "value": { "stdout": "${WS}/main.cpp:4:12: warning: use nullptr [modernize-use-nullptr]\nLinted 1 translation unit in #s: 1 finding.", "exit": 1 diff --git a/sources/clice/cases/modularize/libraries/01_one_library.json b/sources/clice/cases/modularize/libraries/01_one_library.json index e5c44bd09..ad06ce978 100644 --- a/sources/clice/cases/modularize/libraries/01_one_library.json +++ b/sources/clice/cases/modularize/libraries/01_one_library.json @@ -36,7 +36,7 @@ } }, { - "label": "$ clice modularize --scope \"app/**,third/**\" --partition partition.json --out wrap", + "label": "$ clice modularize --scope \"app/**\" --scope \"third/**\" --partition partition.json --out wrap", "value": { "stdout": "{\n \"wrapping\": {\n \"stdSources\": [],\n \"modules\": [\n {\n \"name\": \"alpha\",\n \"source\": \"alpha.cppm\",\n \"imports\": [],\n \"includeRoots\": [\n \"${WS}/third/alpha\"\n ],\n \"mirrors\": []\n }\n ],\n \"mirrors\": [\n \"mirror/alpha\"\n ],\n \"prelude\": \"prelude.h\",\n \"warnings\": []\n },\n \"rewriting\": {\n \"modules\": [],\n \"importers\": [],\n \"macros\": [],\n \"removed\": [],\n \"moved\": [],\n \"warnings\": []\n }\n}", "exit": 0, diff --git a/sources/clice/cases/query/basics/01_references.json b/sources/clice/cases/query/basics/01_references.json index 9e3505523..e80d49091 100644 --- a/sources/clice/cases/query/basics/01_references.json +++ b/sources/clice/cases/query/basics/01_references.json @@ -46,7 +46,7 @@ } }, { - "label": "$ clice query --method references --symbol shapes::Circle::measure --include-declaration", + "label": "$ clice query references shapes::Circle::measure --include-declaration", "value": { "stdout": "{\n \"result\": {\n \"name\": \"measure\",\n \"kind\": \"Method\",\n \"symbol\": \"#c9fbbb30710c2348\",\n \"references\": [\n {\n \"file\": \"${WS}/include/shapes/circle.h\",\n \"line\": 11,\n \"context\": \" double measure() const override;\"\n },\n {\n \"file\": \"${WS}/src/circle.cpp\",\n \"line\": 5,\n \"context\": \"double Circle::measure() const {\"\n },\n {\n \"file\": \"${WS}/test/circle_test.cpp\",\n \"line\": 4,\n \"context\": \" return shapes::Circle(1.0).measure() > 3 ? 0 : 1;\"\n }\n ],\n \"total\": 3\n },\n \"stale\": []\n}", "exit": 0 diff --git a/sources/clice/cases/query/basics/02_symbol_search.json b/sources/clice/cases/query/basics/02_symbol_search.json index 0512195af..96e674bd2 100644 --- a/sources/clice/cases/query/basics/02_symbol_search.json +++ b/sources/clice/cases/query/basics/02_symbol_search.json @@ -46,7 +46,7 @@ } }, { - "label": "$ clice query --method symbolSearch --symbol circ --limit 5", + "label": "$ clice query symbol-search circ --limit 5", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"Circle\",\n \"kind\": \"Class\",\n \"file\": \"${WS}/include/shapes/circle.h\",\n \"line\": 7,\n \"container\": \"shapes\",\n \"symbol\": \"#dd68185c34da1cfd\"\n },\n {\n \"name\": \"circumference\",\n \"kind\": \"Method\",\n \"file\": \"${WS}/src/circle.cpp\",\n \"line\": 9,\n \"container\": \"shapes::Circle\",\n \"symbol\": \"#1792a4d7c19a13df\"\n },\n {\n \"name\": \"Circle\",\n \"kind\": \"Method\",\n \"file\": \"${WS}/include/shapes/circle.h\",\n \"line\": 9,\n \"container\": \"shapes::Circle\",\n \"symbol\": \"#ed83a00043ec4620\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 diff --git a/sources/clice/cases/query/basics/03_symbol_questions.json b/sources/clice/cases/query/basics/03_symbol_questions.json index 5415f8331..eae087065 100644 --- a/sources/clice/cases/query/basics/03_symbol_questions.json +++ b/sources/clice/cases/query/basics/03_symbol_questions.json @@ -31,63 +31,63 @@ } }, { - "label": "$ clice query --method symbolSearch --symbol add", + "label": "$ clice query symbol-search add", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"add\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 2,\n \"container\": null,\n \"symbol\": \"#5c1bf8ca24c752f7\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method definition --symbol \"#5c1bf8ca24c752f7\"", + "label": "$ clice query definition \"#5c1bf8ca24c752f7\"", "value": { "stdout": "{\n \"result\": {\n \"name\": \"add\",\n \"kind\": \"Function\",\n \"symbol\": \"#5c1bf8ca24c752f7\",\n \"documentation\": null,\n \"definition\": {\n \"file\": \"${WS}/main.cpp\",\n \"startLine\": 2,\n \"endLine\": 2,\n \"text\": \"int add(int a, int b) { return a + b; }\"\n }\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method definition --symbol main.cpp:4", + "label": "$ clice query definition main.cpp:4", "value": { "stdout": "{\n \"result\": {\n \"name\": \"compute\",\n \"kind\": \"Function\",\n \"symbol\": \"#81df9416985c4402\",\n \"documentation\": null,\n \"definition\": {\n \"file\": \"${WS}/main.cpp\",\n \"startLine\": 4,\n \"endLine\": 4,\n \"text\": \"int compute() { return add(1, 2); }\"\n }\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method readSymbol --symbol compute", + "label": "$ clice query read-symbol compute", "value": { "stdout": "{\n \"result\": {\n \"name\": \"compute\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"startLine\": 4,\n \"endLine\": 4,\n \"documentation\": null,\n \"text\": \"int compute() { return add(1, 2); }\",\n \"symbol\": \"#81df9416985c4402\"\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method references --symbol add --include-declaration", + "label": "$ clice query references add --include-declaration", "value": { "stdout": "{\n \"result\": {\n \"name\": \"add\",\n \"kind\": \"Function\",\n \"symbol\": \"#5c1bf8ca24c752f7\",\n \"references\": [\n {\n \"file\": \"${WS}/a.h\",\n \"line\": 2,\n \"context\": \"int add(int a, int b);\"\n },\n {\n \"file\": \"${WS}/main.cpp\",\n \"line\": 2,\n \"context\": \"int add(int a, int b) { return a + b; }\"\n },\n {\n \"file\": \"${WS}/main.cpp\",\n \"line\": 4,\n \"context\": \"int compute() { return add(1, 2); }\"\n }\n ],\n \"total\": 3\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method callGraph --symbol add --direction callers", + "label": "$ clice query call-graph add --direction callers", "value": { "stdout": "{\n \"result\": {\n \"root\": {\n \"name\": \"add\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 2,\n \"symbol\": \"#5c1bf8ca24c752f7\"\n },\n \"callers\": [\n {\n \"name\": \"compute\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 4,\n \"symbol\": \"#81df9416985c4402\"\n }\n ],\n \"callees\": []\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method typeHierarchy --symbol Dog --direction supertypes", + "label": "$ clice query type-hierarchy Dog --direction supertypes", "value": { "stdout": "{\n \"result\": {\n \"root\": {\n \"name\": \"Dog\",\n \"kind\": \"Struct\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 3,\n \"symbol\": \"#7316a0a19122a8ae\"\n },\n \"supertypes\": [\n {\n \"name\": \"Animal\",\n \"kind\": \"Struct\",\n \"file\": \"${WS}/a.h\",\n \"line\": 3,\n \"symbol\": \"#a1654fc0dd5efb6c\"\n }\n ],\n \"subtypes\": []\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method documentSymbols --path main.cpp", + "label": "$ clice query document-symbols main.cpp", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"add\",\n \"kind\": \"Function\",\n \"startLine\": 2,\n \"endLine\": 2,\n \"symbol\": \"#5c1bf8ca24c752f7\"\n },\n {\n \"name\": \"Dog\",\n \"kind\": \"Struct\",\n \"startLine\": 3,\n \"endLine\": 3,\n \"symbol\": \"#7316a0a19122a8ae\"\n },\n {\n \"name\": \"compute\",\n \"kind\": \"Function\",\n \"startLine\": 4,\n \"endLine\": 4,\n \"symbol\": \"#81df9416985c4402\"\n },\n {\n \"name\": \"main\",\n \"kind\": \"Function\",\n \"startLine\": 5,\n \"endLine\": 5,\n \"symbol\": \"#70b5c0d150872970\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol kind:Struct,Function --limit 10", + "label": "$ clice query symbol-search kind:Struct,Function --limit 10", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"Animal\",\n \"kind\": \"Struct\",\n \"file\": \"${WS}/a.h\",\n \"line\": 3,\n \"container\": null,\n \"symbol\": \"#a1654fc0dd5efb6c\"\n },\n {\n \"name\": \"add\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 2,\n \"container\": null,\n \"symbol\": \"#5c1bf8ca24c752f7\"\n },\n {\n \"name\": \"Dog\",\n \"kind\": \"Struct\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 3,\n \"container\": null,\n \"symbol\": \"#7316a0a19122a8ae\"\n },\n {\n \"name\": \"compute\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 4,\n \"container\": null,\n \"symbol\": \"#81df9416985c4402\"\n },\n {\n \"name\": \"main\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 5,\n \"container\": null,\n \"symbol\": \"#70b5c0d150872970\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 diff --git a/sources/clice/cases/query/basics/04_file_questions.json b/sources/clice/cases/query/basics/04_file_questions.json index 0563e50c9..68fc4359f 100644 --- a/sources/clice/cases/query/basics/04_file_questions.json +++ b/sources/clice/cases/query/basics/04_file_questions.json @@ -31,42 +31,42 @@ } }, { - "label": "$ clice query --method projectFiles", + "label": "$ clice query project-files", "value": { "stdout": "{\n \"result\": {\n \"files\": [\n {\n \"path\": \"${WS}/main.cpp\",\n \"kind\": \"source\",\n \"moduleName\": null\n },\n {\n \"path\": \"${WS}/a.h\",\n \"kind\": \"header\",\n \"moduleName\": null\n }\n ],\n \"total\": 2\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method projectFiles --filter source", + "label": "$ clice query project-files --filter source", "value": { "stdout": "{\n \"result\": {\n \"files\": [\n {\n \"path\": \"${WS}/main.cpp\",\n \"kind\": \"source\",\n \"moduleName\": null\n }\n ],\n \"total\": 1\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method fileDeps --path main.cpp --direction includes", + "label": "$ clice query file-deps main.cpp --direction includes", "value": { "stdout": "{\n \"result\": {\n \"file\": \"${WS}/main.cpp\",\n \"includes\": [\n {\n \"path\": \"${WS}/a.h\",\n \"depth\": 1\n }\n ],\n \"includers\": []\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method fileDeps --path a.h --direction includers", + "label": "$ clice query file-deps a.h --direction includers", "value": { "stdout": "{\n \"result\": {\n \"file\": \"${WS}/a.h\",\n \"includes\": [],\n \"includers\": [\n {\n \"path\": \"${WS}/main.cpp\",\n \"depth\": 1\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method impactAnalysis --path a.h", + "label": "$ clice query impact-analysis a.h", "value": { "stdout": "{\n \"result\": {\n \"directDependents\": [\n \"${WS}/main.cpp\"\n ],\n \"transitiveDependents\": [],\n \"affectedModules\": []\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method counterparts --path a.h", + "label": "$ clice query counterparts a.h", "value": { "stdout": "{\n \"result\": {\n \"file\": \"${WS}/a.h\",\n \"candidates\": [\n {\n \"path\": \"${WS}/main.cpp\",\n \"reasons\": [\n \"defines 1 of 1 declaration\"\n ]\n }\n ],\n \"preferred\": \"${WS}/main.cpp\"\n },\n \"stale\": []\n}", "exit": 0 diff --git a/sources/clice/cases/query/basics/10_documentation.json b/sources/clice/cases/query/basics/10_documentation.json index e58fbbc5d..b4a95463a 100644 --- a/sources/clice/cases/query/basics/10_documentation.json +++ b/sources/clice/cases/query/basics/10_documentation.json @@ -31,28 +31,28 @@ } }, { - "label": "$ clice query --method readSymbol --symbol area", + "label": "$ clice query read-symbol area", "value": { "stdout": "{\n \"result\": {\n \"name\": \"area\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/geometry.cpp\",\n \"startLine\": 4,\n \"endLine\": 6,\n \"documentation\": \"Computes the area of a rectangle.\\n\\nParameters: \\n- `width` — The horizontal extent.\\n- `height` — The vertical extent.\\n\\nReturns: The product of both sides.\",\n \"text\": \"int area(int width, int height) {\\n return width * height;\\n}\",\n \"symbol\": \"#7b938a3382a6f65a\"\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method definition --symbol surface", + "label": "$ clice query definition surface", "value": { "stdout": "{\n \"result\": {\n \"name\": \"surface\",\n \"kind\": \"Function\",\n \"symbol\": \"#a2ee286bd8d3dc88\",\n \"documentation\": \"Computes the area of a rectangle.\\n\\nParameters: \\n- `width` — The horizontal extent.\\n- `height` — The vertical extent.\\n\\nReturns: The product of both sides.\",\n \"definition\": {\n \"file\": \"${WS}/geometry.cpp\",\n \"startLine\": 8,\n \"endLine\": 10,\n \"text\": \"int surface(int width, int height) {\\n return area(width, height);\\n}\"\n }\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method readSymbol --symbol Square::draw", + "label": "$ clice query read-symbol Square::draw", "value": { "stdout": "{\n \"result\": {\n \"name\": \"draw\",\n \"kind\": \"Method\",\n \"file\": \"${WS}/geometry.cpp\",\n \"startLine\": 14,\n \"endLine\": 14,\n \"documentation\": \"Draws the shape.\",\n \"text\": \"void Square::draw() {}\",\n \"symbol\": \"#e3c8e20a05689894\"\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method definition --symbol Shape::sides", + "label": "$ clice query definition Shape::sides", "value": { "stdout": "{\n \"result\": {\n \"name\": \"sides\",\n \"kind\": \"Field\",\n \"symbol\": \"#17762968bcc5b2cf\",\n \"documentation\": \"How many sides it has.\",\n \"definition\": {\n \"file\": \"${WS}/include/geometry.h\",\n \"startLine\": 16,\n \"endLine\": 16,\n \"text\": \"int sides\"\n }\n },\n \"stale\": []\n}", "exit": 0 diff --git a/sources/clice/cases/query/freshness/01_withheld_rows.json b/sources/clice/cases/query/freshness/01_withheld_rows.json index 26eee130b..e5f2fccd3 100644 --- a/sources/clice/cases/query/freshness/01_withheld_rows.json +++ b/sources/clice/cases/query/freshness/01_withheld_rows.json @@ -31,35 +31,35 @@ } }, { - "label": "$ clice query --method definition --symbol compute", + "label": "$ clice query definition compute", "value": { "stdout": "{\n \"error\": \"symbol not found\",\n \"stale\": [\n \"${WS}/main.cpp\"\n ]\n}", "exit": 1 } }, { - "label": "$ clice query --method definition --symbol new.cpp:1:5", + "label": "$ clice query definition new.cpp:1:5", "value": { "stdout": "{\n \"error\": \"symbol not found\",\n \"stale\": [\n \"${WS}/new.cpp\"\n ]\n}", "exit": 1 } }, { - "label": "$ clice query --method documentSymbols --path main.cpp", + "label": "$ clice query document-symbols main.cpp", "value": { "stdout": "{\n \"result\": {\n \"symbols\": []\n },\n \"stale\": [\n \"${WS}/main.cpp\"\n ]\n}", "exit": 0 } }, { - "label": "$ clice query --method documentSymbols --path a.h", + "label": "$ clice query document-symbols a.h", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"add\",\n \"kind\": \"Function\",\n \"startLine\": 2,\n \"endLine\": 2,\n \"symbol\": \"#5c1bf8ca24c752f7\"\n },\n {\n \"name\": \"Animal\",\n \"kind\": \"Struct\",\n \"startLine\": 3,\n \"endLine\": 3,\n \"symbol\": \"#a1654fc0dd5efb6c\"\n },\n {\n \"name\": \"~Animal\",\n \"kind\": \"Method\",\n \"startLine\": 3,\n \"endLine\": 3,\n \"symbol\": \"#2dbb9112f1fa26ec\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method counterparts --path a.h", + "label": "$ clice query counterparts a.h", "value": { "stdout": "{\n \"result\": {\n \"file\": \"${WS}/a.h\",\n \"candidates\": [],\n \"preferred\": null\n },\n \"stale\": [\n \"${WS}/main.cpp\"\n ]\n}", "exit": 0 diff --git a/sources/clice/cases/query/freshness/02_fresh_batch.json b/sources/clice/cases/query/freshness/02_fresh_batch.json index 444276b03..b75cd2e2d 100644 --- a/sources/clice/cases/query/freshness/02_fresh_batch.json +++ b/sources/clice/cases/query/freshness/02_fresh_batch.json @@ -24,7 +24,7 @@ "name": "test", "blocks": [ { - "label": "$ clice query --method symbolSearch --symbol compute --fresh", + "label": "$ clice query symbol-search compute --fresh", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"compute\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 4,\n \"container\": null,\n \"symbol\": \"#81df9416985c4402\"\n }\n ]\n },\n \"stale\": []\n}", "stderr": "indexing 0/1 units, 0 failed\nindexing 1/1 units, 0 failed", @@ -32,7 +32,7 @@ } }, { - "label": "$ clice query --method symbolSearch --symbol extra --fresh", + "label": "$ clice query symbol-search extra --fresh", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"extra\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 5,\n \"container\": null,\n \"symbol\": \"#c9be3d07e9d6b64f\"\n }\n ]\n },\n \"stale\": []\n}", "stderr": "indexing 0/1 units, 0 failed\nindexing 1/1 units, 0 failed", diff --git a/sources/clice/cases/query/names/05_file_local_names.json b/sources/clice/cases/query/names/05_file_local_names.json index 520882a54..efd41cbda 100644 --- a/sources/clice/cases/query/names/05_file_local_names.json +++ b/sources/clice/cases/query/names/05_file_local_names.json @@ -31,56 +31,56 @@ } }, { - "label": "$ clice query --method symbolSearch --symbol \"\\\"rows\\\"\"", + "label": "$ clice query symbol-search \"\\\"rows\\\"\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": []\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol \"\\\"rows\\\" path:a.cpp\"", + "label": "$ clice query symbol-search \"\\\"rows\\\" path:a.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"rows\",\n \"kind\": \"Variable\",\n \"file\": \"${WS}/a.cpp\",\n \"line\": 4,\n \"container\": \"a\",\n \"symbol\": \"#62144b44c2d7e570 path:${WS}/a.cpp\"\n },\n {\n \"name\": \"rows\",\n \"kind\": \"Parameter\",\n \"file\": \"${WS}/a.cpp\",\n \"line\": 2,\n \"container\": \"helper\",\n \"symbol\": \"#c779df7ea50d8026 path:${WS}/a.cpp\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol \"\\\"rows\\\" path:b.cpp\"", + "label": "$ clice query symbol-search \"\\\"rows\\\" path:b.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"rows\",\n \"kind\": \"Variable\",\n \"file\": \"${WS}/b.cpp\",\n \"line\": 1,\n \"container\": null,\n \"symbol\": \"#91b81847324836ae path:${WS}/b.cpp\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol \"helper::rows path:a.cpp\"", + "label": "$ clice query symbol-search \"helper::rows path:a.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"rows\",\n \"kind\": \"Parameter\",\n \"file\": \"${WS}/a.cpp\",\n \"line\": 2,\n \"container\": \"helper\",\n \"symbol\": \"#c779df7ea50d8026 path:${WS}/a.cpp\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method definition --symbol \"a::rows path:a.cpp\"", + "label": "$ clice query definition \"a::rows path:a.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"name\": \"rows\",\n \"kind\": \"Variable\",\n \"symbol\": \"#62144b44c2d7e570 path:${WS}/a.cpp\",\n \"documentation\": null,\n \"definition\": {\n \"file\": \"${WS}/a.cpp\",\n \"startLine\": 4,\n \"endLine\": 4,\n \"text\": \"int rows = 1\"\n }\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method definition --symbol \"\\\"rows\\\" path:a.cpp\"", + "label": "$ clice query definition \"\\\"rows\\\" path:a.cpp\"", "value": { "stdout": "{\n \"error\": \"ambiguous: 2 symbols match; name one by the `symbol` of a candidate\",\n \"candidates\": [\n {\n \"name\": \"rows\",\n \"kind\": \"Variable\",\n \"file\": \"${WS}/a.cpp\",\n \"line\": 4,\n \"container\": \"a\",\n \"symbol\": \"#62144b44c2d7e570 path:${WS}/a.cpp\"\n },\n {\n \"name\": \"rows\",\n \"kind\": \"Parameter\",\n \"file\": \"${WS}/a.cpp\",\n \"line\": 2,\n \"container\": \"helper\",\n \"symbol\": \"#c779df7ea50d8026 path:${WS}/a.cpp\"\n }\n ],\n \"stale\": []\n}", "exit": 1 } }, { - "label": "$ clice query --method definition --symbol \"#62144b44c2d7e570 path:${WS}/a.cpp\"", + "label": "$ clice query definition \"#62144b44c2d7e570 path:${WS}/a.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"name\": \"rows\",\n \"kind\": \"Variable\",\n \"symbol\": \"#62144b44c2d7e570 path:${WS}/a.cpp\",\n \"documentation\": null,\n \"definition\": {\n \"file\": \"${WS}/a.cpp\",\n \"startLine\": 4,\n \"endLine\": 4,\n \"text\": \"int rows = 1\"\n }\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method definition --symbol \"#c779df7ea50d8026 path:${WS}/a.cpp\"", + "label": "$ clice query definition \"#c779df7ea50d8026 path:${WS}/a.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"name\": \"rows\",\n \"kind\": \"Parameter\",\n \"symbol\": \"#c779df7ea50d8026 path:${WS}/a.cpp\",\n \"documentation\": null,\n \"definition\": {\n \"file\": \"${WS}/a.cpp\",\n \"startLine\": 2,\n \"endLine\": 2,\n \"text\": \"int rows\"\n }\n },\n \"stale\": []\n}", "exit": 0 diff --git a/sources/clice/cases/query/names/06_path_filters.json b/sources/clice/cases/query/names/06_path_filters.json index 70d460167..86f3c4a46 100644 --- a/sources/clice/cases/query/names/06_path_filters.json +++ b/sources/clice/cases/query/names/06_path_filters.json @@ -31,35 +31,35 @@ } }, { - "label": "$ clice query --method symbolSearch --symbol \"sum path:src/\"", + "label": "$ clice query symbol-search \"sum path:src/\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"sum_src\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/src/a.cpp\",\n \"line\": 2,\n \"container\": null,\n \"symbol\": \"#1021c69a8dde905f\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol \"\\\"tally\\\" path:src/a.cpp\"", + "label": "$ clice query symbol-search \"\\\"tally\\\" path:src/a.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"tally\",\n \"kind\": \"Variable\",\n \"file\": \"${WS}/src/a.cpp\",\n \"line\": 1,\n \"container\": null,\n \"symbol\": \"#6c0f5b9087ce07a0 path:${WS}/src/a.cpp\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol \"\\\"tally\\\" path:./lib/src/b.cpp\"", + "label": "$ clice query symbol-search \"\\\"tally\\\" path:./lib/src/b.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"tally\",\n \"kind\": \"Variable\",\n \"file\": \"${WS}/lib/src/b.cpp\",\n \"line\": 1,\n \"container\": null,\n \"symbol\": \"#420d45808a85b99e path:${WS}/lib/src/b.cpp\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol \"\\\"tally\\\" path:b.cpp\"", + "label": "$ clice query symbol-search \"\\\"tally\\\" path:b.cpp\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"tally\",\n \"kind\": \"Variable\",\n \"file\": \"${WS}/lib/src/b.cpp\",\n \"line\": 1,\n \"container\": null,\n \"symbol\": \"#420d45808a85b99e path:${WS}/lib/src/b.cpp\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice query --method symbolSearch --symbol \"sum path:\\\"${WS}/lib\\\"\"", + "label": "$ clice query symbol-search \"sum path:\\\"${WS}/lib\\\"\"", "value": { "stdout": "{\n \"result\": {\n \"symbols\": [\n {\n \"name\": \"sum_lib\",\n \"kind\": \"Function\",\n \"file\": \"${WS}/lib/src/b.cpp\",\n \"line\": 2,\n \"container\": null,\n \"symbol\": \"#39a8aa13717d58d5\"\n }\n ]\n },\n \"stale\": []\n}", "exit": 0 diff --git a/sources/clice/cases/refactor/edits/01_plan_then_write.json b/sources/clice/cases/refactor/edits/01_plan_then_write.json index 3a3c0a634..02f2b5caa 100644 --- a/sources/clice/cases/refactor/edits/01_plan_then_write.json +++ b/sources/clice/cases/refactor/edits/01_plan_then_write.json @@ -29,14 +29,14 @@ "name": "plans without writing", "blocks": [ { - "label": "$ clice index --workers 2", + "label": "$ clice index --jobs 2", "value": { "stdout": "Indexed 2 translation units in #s: 3 file shards (# KB), 8 symbols.\nSession log: ${WS}/.clice/logs/${SESSION}", "exit": 0 } }, { - "label": "$ clice refactor rename --symbol compute --to evaluate --dry-run", + "label": "$ clice refactor rename compute evaluate --dry-run", "value": { "stdout": "{\n \"result\": {\n \"applied\": false,\n \"renames\": [\n {\n \"line\": null,\n \"locator\": \"compute\",\n \"name\": \"compute\",\n \"kind\": \"Function\",\n \"symbol\": \"#0129094638d1b328\",\n \"newName\": \"evaluate\",\n \"edits\": 4,\n \"conflicts\": [],\n \"warnings\": [],\n \"error\": null,\n \"candidates\": null\n }\n ],\n \"files\": [\n {\n \"file\": \"${WS}/lib.h\",\n \"edits\": [\n {\n \"line\": 3,\n \"column\": 5,\n \"name\": \"compute\",\n \"newName\": \"evaluate\",\n \"heuristic\": false\n }\n ]\n },\n {\n \"file\": \"${WS}/main.cpp\",\n \"edits\": [\n {\n \"line\": 3,\n \"column\": 5,\n \"name\": \"compute\",\n \"newName\": \"evaluate\",\n \"heuristic\": false\n },\n {\n \"line\": 7,\n \"column\": 20,\n \"name\": \"compute\",\n \"newName\": \"evaluate\",\n \"heuristic\": false\n }\n ]\n },\n {\n \"file\": \"${WS}/other.cpp\",\n \"edits\": [\n {\n \"line\": 3,\n \"column\": 22,\n \"name\": \"compute\",\n \"newName\": \"evaluate\",\n \"heuristic\": false\n }\n ]\n }\n ],\n \"unconfirmed\": [\n {\n \"file\": \"${WS}/lib.h\",\n \"line\": 10,\n \"column\": 14,\n \"name\": \"compute\",\n \"reason\": \"inside a preprocessor directive, which the index does not resolve\",\n \"text\": \"#define CALL compute(1)\"\n },\n {\n \"file\": \"${WS}/main.cpp\",\n \"line\": 7,\n \"column\": 33,\n \"name\": \"compute\",\n \"reason\": \"the name is written here as `CALL`\",\n \"text\": \"int use() { return compute(2) + CALL; }\"\n }\n ],\n \"conflicts\": [],\n \"stale\": []\n },\n \"stale\": []\n}", "exit": 0 @@ -48,14 +48,14 @@ "name": "writes the edits", "blocks": [ { - "label": "$ clice index --workers 2", + "label": "$ clice index --jobs 2", "value": { "stdout": "Indexed 2 translation units in #s: 3 file shards (# KB), 8 symbols.\nSession log: ${WS}/.clice/logs/${SESSION}", "exit": 0 } }, { - "label": "$ clice refactor rename --symbol Widget --to Gadget", + "label": "$ clice refactor rename Widget Gadget", "value": { "stdout": "{\n \"result\": {\n \"applied\": true,\n \"renames\": [\n {\n \"line\": null,\n \"locator\": \"Widget\",\n \"name\": \"Widget\",\n \"kind\": \"Struct\",\n \"symbol\": \"#5b52580eb5b8875a\",\n \"newName\": \"Gadget\",\n \"edits\": 5,\n \"conflicts\": [],\n \"warnings\": [],\n \"error\": null,\n \"candidates\": null\n }\n ],\n \"files\": [\n {\n \"file\": \"${WS}/lib.h\",\n \"edits\": [\n {\n \"line\": 5,\n \"column\": 8,\n \"name\": \"Widget\",\n \"newName\": \"Gadget\",\n \"heuristic\": false\n },\n {\n \"line\": 6,\n \"column\": 5,\n \"name\": \"Widget\",\n \"newName\": \"Gadget\",\n \"heuristic\": false\n }\n ]\n },\n {\n \"file\": \"${WS}/main.cpp\",\n \"edits\": [\n {\n \"line\": 5,\n \"column\": 1,\n \"name\": \"Widget\",\n \"newName\": \"Gadget\",\n \"heuristic\": false\n },\n {\n \"line\": 5,\n \"column\": 9,\n \"name\": \"Widget\",\n \"newName\": \"Gadget\",\n \"heuristic\": false\n },\n {\n \"line\": 10,\n \"column\": 5,\n \"name\": \"Widget\",\n \"newName\": \"Gadget\",\n \"heuristic\": false\n }\n ]\n }\n ],\n \"unconfirmed\": [],\n \"conflicts\": [],\n \"stale\": []\n },\n \"stale\": []\n}", "exit": 0, diff --git a/sources/clice/cases/refactor/lists/01_rename_list.json b/sources/clice/cases/refactor/lists/01_rename_list.json index 39896368c..26de2e806 100644 --- a/sources/clice/cases/refactor/lists/01_rename_list.json +++ b/sources/clice/cases/refactor/lists/01_rename_list.json @@ -34,7 +34,7 @@ "name": "test", "blocks": [ { - "label": "$ clice index --workers 2", + "label": "$ clice index --jobs 2", "value": { "stdout": "Indexed 2 translation units in #s: 3 file shards (# KB), 8 symbols.\nSession log: ${WS}/.clice/logs/${SESSION}", "exit": 0 diff --git a/sources/clice/cases/refactor/locators/02_ambiguous_name.json b/sources/clice/cases/refactor/locators/02_ambiguous_name.json index a8915ad86..411eb4c90 100644 --- a/sources/clice/cases/refactor/locators/02_ambiguous_name.json +++ b/sources/clice/cases/refactor/locators/02_ambiguous_name.json @@ -4,7 +4,7 @@ "subtopic": "locators", "title": "Name an ambiguous symbol", "summary": "A name two symbols spell lists both, and a scoped name or a candidate's `symbol` picks one", - "prose": "Nothing is renamed while the name is ambiguous. Each candidate carries a\n`symbol` to pass back to `--symbol` as it is.", + "prose": "Nothing is renamed while the name is ambiguous. Each candidate carries a\n`symbol` to pass back as it is.", "status": "supported", "issues": [], "files": [ @@ -19,28 +19,28 @@ "name": "test", "blocks": [ { - "label": "$ clice index --workers 2", + "label": "$ clice index --jobs 2", "value": { "stdout": "Indexed 1 translation unit in #s: 1 file shard (# B), 5 symbols.\nSession log: ${WS}/.clice/logs/${SESSION}", "exit": 0 } }, { - "label": "$ clice refactor rename --symbol value --to amount --dry-run", + "label": "$ clice refactor rename value amount --dry-run", "value": { "stdout": "{\n \"result\": {\n \"applied\": false,\n \"renames\": [\n {\n \"line\": null,\n \"locator\": \"value\",\n \"name\": \"\",\n \"kind\": \"\",\n \"symbol\": \"\",\n \"newName\": \"amount\",\n \"edits\": 0,\n \"conflicts\": [],\n \"warnings\": [],\n \"error\": \"ambiguous: 2 symbols match; name one by the `symbol` of a candidate\",\n \"candidates\": [\n {\n \"name\": \"value\",\n \"kind\": \"Variable\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 6,\n \"container\": \"b\",\n \"symbol\": \"#2d69354e2aeb0cf6\"\n },\n {\n \"name\": \"value\",\n \"kind\": \"Variable\",\n \"file\": \"${WS}/main.cpp\",\n \"line\": 2,\n \"container\": \"a\",\n \"symbol\": \"#ab73a1a4b609cf4d\"\n }\n ]\n }\n ],\n \"files\": [],\n \"unconfirmed\": [],\n \"conflicts\": [],\n \"stale\": []\n },\n \"stale\": []\n}", "exit": 1 } }, { - "label": "$ clice refactor rename --symbol a::value --to amount --dry-run", + "label": "$ clice refactor rename a::value amount --dry-run", "value": { "stdout": "{\n \"result\": {\n \"applied\": false,\n \"renames\": [\n {\n \"line\": null,\n \"locator\": \"a::value\",\n \"name\": \"value\",\n \"kind\": \"Variable\",\n \"symbol\": \"#ab73a1a4b609cf4d\",\n \"newName\": \"amount\",\n \"edits\": 2,\n \"conflicts\": [],\n \"warnings\": [],\n \"error\": null,\n \"candidates\": null\n }\n ],\n \"files\": [\n {\n \"file\": \"${WS}/main.cpp\",\n \"edits\": [\n {\n \"line\": 2,\n \"column\": 5,\n \"name\": \"value\",\n \"newName\": \"amount\",\n \"heuristic\": false\n },\n {\n \"line\": 9,\n \"column\": 23,\n \"name\": \"value\",\n \"newName\": \"amount\",\n \"heuristic\": false\n }\n ]\n }\n ],\n \"unconfirmed\": [],\n \"conflicts\": [],\n \"stale\": []\n },\n \"stale\": []\n}", "exit": 0 } }, { - "label": "$ clice refactor rename --symbol \"#ab73a1a4b609cf4d\" --to amount", + "label": "$ clice refactor rename \"#ab73a1a4b609cf4d\" amount", "value": { "stdout": "{\n \"result\": {\n \"applied\": true,\n \"renames\": [\n {\n \"line\": null,\n \"locator\": \"#ab73a1a4b609cf4d\",\n \"name\": \"value\",\n \"kind\": \"Variable\",\n \"symbol\": \"#ab73a1a4b609cf4d\",\n \"newName\": \"amount\",\n \"edits\": 2,\n \"conflicts\": [],\n \"warnings\": [],\n \"error\": null,\n \"candidates\": null\n }\n ],\n \"files\": [\n {\n \"file\": \"${WS}/main.cpp\",\n \"edits\": [\n {\n \"line\": 2,\n \"column\": 5,\n \"name\": \"value\",\n \"newName\": \"amount\",\n \"heuristic\": false\n },\n {\n \"line\": 9,\n \"column\": 23,\n \"name\": \"value\",\n \"newName\": \"amount\",\n \"heuristic\": false\n }\n ]\n }\n ],\n \"unconfirmed\": [],\n \"conflicts\": [],\n \"stale\": []\n },\n \"stale\": []\n}", "exit": 0, diff --git a/zh/clice/cli/analyze.md b/zh/clice/cli/analyze.md index d4f1ef5ad..eeddae7d2 100644 --- a/zh/clice/cli/analyze.md +++ b/zh/clice/cli/analyze.md @@ -4,7 +4,7 @@ `clice analyze` 读取持久化索引并报告代码中的事实，供编程智能体据此作出重构决策。它不执行构建或计时，只描述代码；编程智能体则结合手头的代码决定如何修改。与 `clice query` 一样，它读取 `clice index` 构建的索引，并将 JSON 输出到标准输出。 -**用法**：`clice analyze [--workspace ] [--configuration ] [options]` +**用法**：`clice analyze [ [...]] [--workspace ] [--configuration ] [options]` ## 模块 @@ -12,24 +12,24 @@ 分析范围内的每个文件都属于一个模块，默认按所在目录划分。当一个模块中的文件通过名称引用另一个模块的文件所提供的实体时，前者就依赖于后者：既包括直接写出的名称，也包括在该文件中由宏展开产生的名称，以及显式特化所针对的模板。提供实体的文件优先取定义该实体的头文件，其次是声明该实体的头文件，最后是定义该实体的源文件。来自头文件的依赖是接口边，会转化为对所依赖模块接口的导入；仅来自源文件的依赖是实现边，不会形成循环依赖，因为实现单元可以导入位于其上层的模块。`.inc` 和 `.def` 等文本片段文件视为包含它们的文件的一部分。如果一个头文件仅供其所属模块的源文件使用，无论是直接使用，还是通过其他此类头文件间接使用，它都属于内部分区：它不会向模块接口添加任何内容，其依赖也都不是接口边。 -- `--scope ` 仅分析与 glob 模式匹配的文件，匹配时使用相对于工作区的路径；默认分析工作区下所有已建立索引且不位于名称以点开头的目录中的文件。 -- `--depth ` 使用文件所在目录路径的前 `n` 段命名其默认模块，而不是使用完整目录路径。 +- `--scope ` 仅分析与 glob 模式匹配的文件，匹配时使用相对于工作区的路径；重复给出该选项即可指定多个模式。默认分析工作区下所有已建立索引且不位于名称以点开头的目录中的文件。 +- `--dir-depth ` 使用文件所在目录路径的前 `n` 段命名其默认模块，而不是使用完整目录路径。 - `--partition ` 按 glob 模式分配模块，以首次匹配为准：`{"modules": [{"name": "core", "files": ["src/support/**", "src/vfs/**"]}]}`。未匹配任何 glob 模式的文件仍归入其所在目录对应的模块。对于 `interface` 视图和 [modularize](./modularize.md)，`"textual": true` 让模块保持为头文件，`"external": true` 标记由已有模块代替的模块（即标准库），`"provides": "std.compat"` 指定导出该模块中名称的模块，这些名称从 `--std ` 指定的 libc++ 模块源码中读取。 -- `--move =,...` 和 `--merge +[+...],...` 评估假设的变更，但不实际执行变更。 +- `--move =` 和 `--merge +[+...]` 评估假设的变更，但不实际执行变更；重复给出这两个选项即可评估多处变更。 - `--move-entity =
` 评估将声明连同其成员及其定义所引用的实体移至另一个头文件（已有或新建）的效果；重复给出该选项即可评估多处移动。[定位串](./query.md#locators)须写出声明的完整名称：同一作用域中函数的各个重载会一起移动，`edge` 视图输出的定位串可从中选定一个；若该名称在多个作用域中都有，则报错并列出全部候选。 -- `--annotation ,...` 和 `--churn-since ` 对结果加权；参见[注解](#annotations)。 -- `--view ` 选择结果视图，默认为 `overview`。 - -| 视图 | 提供的信息 | -| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `overview` | 按层划分的模块、附有实体示例的边、循环依赖及打破各循环依赖所需移除的最轻边集、模块内的头文件循环依赖、内部分区数量、最深导入链、重新构建总数、热点、移动候选和拆分候选，以及障碍数量 | -| `edge --from --to ` | 该边承载的所有实体，以及各实体的定位串、所有者和每处使用位置的 `file:line` | -| `module --module ` | 按模块列出的各文件依赖项及依赖方、该模块的内部分区，以及按使用它们的模块分组的其他头文件——这些就是目录拆分的边界 | -| `file --file ` | 该文件按模块列出所引用的实体、哪些文件引用它的实体，以及它的注解 | -| `obstacles` | 下文列出的所有代码结构 | -| `macros` | 按模块列出在其定义文件之外使用的宏：导入不传递宏，因此每个宏都通过文本头文件传递给使用方 | -| `impact` | 对于每个头文件，修改它后在当前结构下和采用分区方案后分别需要重新构建的单元，以及该头文件是否为内部分区 | -| `interface [--module ]` | 对于每个模块，为其头文件编写封装模块所需的信息：它导入的模块、它的入口头文件及其他模块包含这些头文件时所用的名称、它在命名空间作用域声明的名称及所在头文件、它的命名空间别名、仍以文本方式包含的头文件、它的头文件与其他封装模块共用的 TU 内部实体、导入方所需的宏，以及它的头文件读取的其他模块的宏 | +- `--annotation ` 和 `--churn-since ` 为按它们排序的视图的结果加权；参见[注解](#annotations)。 +- 视图由 `modules` 后面的一个词指定，用来选择结果；不指定视图时给出概览。 + +| 视图 | 提供的信息 | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| （不指定视图） | 按层划分的模块、附有实体示例的边、循环依赖及打破各循环依赖所需移除的最轻边集、模块内的头文件循环依赖、内部分区数量、最深导入链、重新构建总数、热点、移动候选和拆分候选，以及障碍数量 | +| `edge ` | 该边承载的所有实体，以及各实体的定位串、所有者和每处使用位置的 `file:line` | +| `module ` | 按模块列出的各文件依赖项及依赖方、该模块的内部分区，以及按使用它们的模块分组的其他头文件——这些就是目录拆分的边界 | +| `file ` | 该文件按模块列出所引用的实体、哪些文件引用它的实体，以及它的注解 | +| `obstacles` | 下文列出的所有代码结构 | +| `macros` | 按模块列出在其定义文件之外使用的宏：导入不传递宏，因此每个宏都通过文本头文件传递给使用方 | +| `impact` | 对于每个头文件，修改它后在当前结构下和采用分区方案后分别需要重新构建的单元，以及该头文件是否为内部分区 | +| `interface []` | 对于每个模块，为其头文件编写封装模块所需的信息：它导入的模块、它的入口头文件及其他模块包含这些头文件时所用的名称、它在命名空间作用域声明的名称及所在头文件、它的命名空间别名、仍以文本方式包含的头文件、它的头文件与其他封装模块共用的 TU 内部实体、导入方所需的宏，以及它的头文件读取的其他模块的宏 | 概览中的热点、移动候选和拆分候选条目数受 `--limit` 限制（默认为 20）；模块、边和循环依赖总是完整列出。 diff --git a/zh/clice/cli/format.md b/zh/clice/cli/format.md index c07f38290..0f1d3439f 100644 --- a/zh/clice/cli/format.md +++ b/zh/clice/cli/format.md @@ -4,7 +4,7 @@ `clice format` 用 clice 内置的 clang-format 格式化工作区中的文件，与编辑器中的格式化一致，一次处理多个文件，并沿用项目中已有的 `.clang-format` 配置。clice 自己不添加任何风格设置：风格来自 clang-format 自身的查找规则，即每个文件向上最近的那个 `.clang-format`。 -**用法**：`clice format [--workspace ] [--configuration ] [--check] [--jobs ] [...]` +**用法**：`clice format [...] [--workspace ] [--configuration ] [--check] [--jobs ]` 不带路径时，它格式化构建自身的文件：编译数据库中的每个翻译单元，以及它们包含的每个带 C 族后缀的文件——这些文件须位于工作区内，在构建树之外（构建树指根目录下存放编译数据库的目录，构建会在其中生成或拉取源文件），在其编译命令的系统包含目录之外，也在缓存目录之外。目录参数会把这个集合收窄到该目录下的文件；带 C 族后缀的文件参数则无论构建是否知道它都会被格式化。路径相对于工作区。`clice.toml` 中写有 `format = false` 的规则会把匹配到的文件排除在外，例如随项目附带的第三方库或生成的源文件： diff --git a/zh/clice/cli/index.md b/zh/clice/cli/index.md index 1c25e9842..12e65bf5d 100644 --- a/zh/clice/cli/index.md +++ b/zh/clice/cli/index.md @@ -4,7 +4,7 @@ `clice index` 预先为工作区构建持久化符号索引，让编辑器会话热启动，而不是在你工作时才在后台建立索引。它用 worker 池运行与服务器相同的索引流程，两者共用 `cache_dir` 下的索引，每个构建配置各一份。 -**用法**：`clice index [--workspace ] [--configuration ] [--workers ]` +**用法**：`clice index [--workspace ] [--configuration ] [--jobs ]` 同一时刻只有一个进程为工作区写索引。编辑器会话打开着工作区时，这个角色由它的服务器担任，因此 `clice index` 会请服务器执行这轮索引并等待结果，而不是自己启动一个 worker 池；摘要中会说明这一点。若锁被一个无法请求的进程持有（另一个 `clice index`、另一个 clice 构建的服务器，或配置里关闭了后台索引的服务器），命令会失败并给出持有者——等那个进程结束后再重新运行。 @@ -12,12 +12,12 @@ ## 查看索引 -同一条命令也能读取已持久化的索引，而不改动它。所有查看模式都输出纯文本行，便于在终端查看或交给 `grep` 处理；即使编辑器会话正打开着索引，这些模式也能正常工作。 +同一条命令的这些操作读取已持久化的索引，而不改动它。每个操作都输出纯文本行，便于在终端查看或交给 `grep` 处理；即使编辑器会话正打开着索引，它们也能正常工作。 -- `clice index --stats [--top ]` 输出索引内容的统计信息：翻译单元和文件分片、分片各列及全局符号表的字节占用明细、符号按引用文件数和名称长度的分布、文件分片按变体数量的分布，以及最大的分片。`--variants` 会为每个文件分片追加一行以制表符分隔的记录，其中包含该分片的变体数量，便于比较两次运行的结果。 -- `clice index --show-symbol ` 输出索引中记录的符号信息：种类、名称和标志，拼出其限定名的父级链，规范声明所在的文件，以及各文件中定义、声明和引用的数量。名称按显示形式（`Box`）或限定形式（`ns::Box`）匹配；`#` 按符号标识指定符号，文件局部符号就是通过这种方式访问的。 -- `clice index --show-file ` 输出文件已持久化的数据行：构建这些行所依据的内容版本、每个变体及贡献它的翻译单元，按关系类型统计的行数，以及身份只存在于该文件中的文件局部符号。 -- `clice index --show-tu ` 输出翻译单元的清单：索引时间、它为哪些文件贡献了数据行，以及它的包含树。 +- `clice index stats [--limit ]` 输出索引内容的统计信息：翻译单元和文件分片、分片各列及全局符号表的字节占用明细、符号按引用文件数和名称长度的分布、文件分片按变体数量的分布，以及最大的分片。`--variants` 会为每个文件分片追加一行以制表符分隔的记录，其中包含该分片的变体数量，便于比较两次运行的结果。 +- `clice index symbol ` 输出索引中记录的、由[定位串](./query.md#locators)指明的那些符号的信息：种类、名称和标志，拼出限定名的父级链，规范声明所在的文件，以及每个符号在各文件中定义、声明和引用的数量。名称会指明完整写出该名称的所有符号（`Box`、`ns::Box`），只要 `clice query` 能找到它们；id 即使在没有任何文件声明该符号时也能指明它，例如在命令行上定义的宏。 +- `clice index file ` 输出文件已持久化的数据行：构建这些行所依据的内容版本、每个变体及贡献它的翻译单元，按关系类型统计的行数，以及身份只存在于该文件中的文件局部符号。 +- `clice index unit ` 输出翻译单元的清单：索引时间、它为哪些文件贡献了数据行，以及它的包含树。 ## 示例 diff --git a/zh/clice/cli/lint.md b/zh/clice/cli/lint.md index 0bd6843e5..f1868a66a 100644 --- a/zh/clice/cli/lint.md +++ b/zh/clice/cli/lint.md @@ -4,7 +4,7 @@ clice 将 clang-tidy 集成为内置 Lint 引擎。`clice lint` 借助常驻 worker 池，对工作区内的翻译单元运行 `.clang-tidy` 中配置的检查，并输出一份合并后的报告。 -**用法**：`clice lint [--workspace ] [--configuration ] [--workers ] [--index]` +**用法**：`clice lint [--workspace ] [--configuration ] [--jobs ] [--index]` 对编译数据库中属于下文检查范围的每个翻译单元运行 clang-tidy， 输出合并后的检查结果；发现问题时以非零状态退出。 diff --git a/zh/clice/cli/modularize.md b/zh/clice/cli/modularize.md index 9aad851ab..75a981bda 100644 --- a/zh/clice/cli/modularize.md +++ b/zh/clice/cli/modularize.md @@ -6,9 +6,9 @@ 程序自身的代码也可以跟进：划分文件标记为改写的模块，其文件会被原地改写成模块单元，头文件变成分区（partition），包含变成导入。 -**用法**：`clice modularize --partition --out [--std ] [--no-mirrors] [--scope ] [--workspace ] [--configuration ]` +**用法**：`clice modularize --partition --out [--std ] [--no-mirrors] [--scope ...] [--workspace ] [--configuration ]` -所有信息都来自持久化索引，可通过 [`clice analyze modules --view interface`](./analyze.md#modules) 查看；请先运行 `clice index`。该命令会写入文件并输出构建所需的信息，但不会修改任何构建文件。 +所有信息都来自持久化索引，可通过 [`clice analyze modules interface`](./analyze.md#modules) 查看；请先运行 `clice index`。该命令会写入文件并输出构建所需的信息，但不会修改任何构建文件。 ## 划分 @@ -57,7 +57,7 @@ 一次封装只涵盖头文件在单一构建配置下声明和定义的内容：平台的 C 库、库的配置头文件设置的宏、库只为某个目标平台声明的名称。为多个平台或多种配置构建的程序，要为每个配置各运行一次 modularize，各自基于该配置的索引、写到各自的目录，然后合并结果。 -**用法**：`clice modularize --merge --out [--no-mirrors]` +**用法**：`clice modularize merge --out [--no-mirrors]` ```json { @@ -199,7 +199,7 @@ tests/modularize/program/01_one_module - 只有索引中的文件会被改写：被索引的构建配置中没有任何编译用到的源文件（例如其他平台的源文件）会保留原有的包含指令。 - clang 不认为实现分区的全局模块片段对经由另一个分区间接导入它的单元可达，尽管标准规定该单元同样导入了它。因此被改写的文件会自行包含这类分区所包含的、仍保持为头文件的头文件，并再解析一遍。 - 位于预处理条件中的被改写头文件的包含，会变成无条件的导入。 -- 头文件变成分区后只编译一次：声明随包含方而不同、或检测包含方所定义宏的头文件，只会保留其中一种结果。`clice analyze modules --view obstacles` 会列出这类头文件，应先行处理。 +- 头文件变成分区后只编译一次：声明随包含方而不同、或检测包含方所定义宏的头文件，只会保留其中一种结果。`clice analyze modules obstacles` 会列出这类头文件，应先行处理。 - 对分析范围外文件的包含保持原位；如果它位于文件开头那些预处理指令之后，就会落在模块辖域内，其中声明的实体随之附属于该模块。 - 以下情况 modularize 会在写出任何文件之前报错退出：仍保持为头文件的头文件包含了被改写的头文件；要写出的文件会覆盖已有文件。 - 编译器能在改写后的代码上报出的问题留给构建去发现：同一模块或两个被改写模块的头文件互相包含；变成分区的头文件里有 `static` 实体；被改写的源文件定义了仍保持为头文件的头文件所声明的实体。 diff --git a/zh/clice/cli/overview.md b/zh/clice/cli/overview.md index 6b8f6c5d6..dd7465a28 100644 --- a/zh/clice/cli/overview.md +++ b/zh/clice/cli/overview.md @@ -8,13 +8,24 @@ clice 只有一个二进制。编辑器启动 `clice serve` 并通过 LSP 与它 | `lint` | 用 worker 池对每个翻译单元运行 clang-tidy。 | [lint](./lint.md) | | `index` | 提前为工作区建立索引，让服务器热启动。 | [index](./index.md) | | `format` | 用 clang-format 格式化工作区中的文件。 | [format](./format.md) | -| `inspect` | 对源文件运行某一项功能，把原始结果打印成 JSON。 | | +| `inspect` | 对一个源文件运行某一项功能，把原始结果打印成 JSON。 | | | `query` | 向持久化索引查询符号、引用、调用图和文件。 | [query](./query.md) | | `refactor` | 依据持久化索引在整个工作区重命名一个符号。 | [refactor](./refactor.md) | | `analyze` | 报告重构所需的事实，例如模块依赖和循环依赖。 | [analyze](./analyze.md) | | `modularize` | 把第三方库封装成 C++20 模块，把程序改写成模块单元。 | [modularize](./modularize.md) | | `scan` | 扫描构建的 include 和模块依赖，并为扫描计时。 | [scan](./scan.md) | -`inspect` 现在已可使用但还没有页面，选项通过 `clice inspect --help` 查看。 +`inspect` 现在已可使用但还没有页面，它的操作和选项通过 `clice inspect --help` 查看。 -`serve`、`index`、`lint`、`format`、`inspect`、`scan`、`query`、`refactor`、`analyze` 和 `modularize` 都接受 `--configuration `，为本次运行固定构建配置，其优先级高于编辑器持久化的选择；参见[切换配置](../guide/configuration.md#switching-configurations)。 +## 参数 + +每个子命令都以同样的方式接受参数： + +``` +clice [] [...] [--option...] +``` + +- 能做几件事的命令，用紧跟其后的一个词指明要做哪一件：`clice query references`、`clice index stats`、`clice analyze modules edge`。有一项首要职能的命令，后面不跟词时就执行这项职能：`clice index` 建立索引，`clice analyze modules` 给出概览。在任何命令或操作后面加上 `--help`，都会列出它接受的参数。 +- 目标，即操作所针对的符号或文件，跟在操作之后：`clice query references "shapes::Circle::area"`、`clice query document-symbols src/main.cpp`。凡是接受符号的地方，都用[定位串](./query.md#locators)（locator）指明符号；文件则用路径指明，可以相对于工作区（对 `inspect` 而言相对于当前目录），也可以是绝对路径。命令自己读写的文件，例如分区文件或输出目录，相对于当前目录。 +- 选项放在操作之后。一个选项要取多个值时，就重复给出它：`--scope 'src/**' --scope 'include/**'`。 +- `--workspace ` 指定工作区，默认为当前目录（`inspect` 与编辑器一样，取文件所在的项目）；`--configuration ` 固定构建配置，其优先级高于编辑器持久化的选择（参见[切换配置](../guide/configuration.md#switching-configurations)）；`-j`、`--jobs ` 指定 `index`、`lint` 和 `format` 同时处理多少个单元或文件；`--log-level` 设置向 stderr 输出哪些日志，默认为警告和错误（编辑器会显示 `serve` 的 stderr，它从 `info` 级别起输出）；无论该选项取什么值，`serve`、`index` 和 `lint` 的会话日志都保留 `info` 级别。 diff --git a/zh/clice/cli/query.md b/zh/clice/cli/query.md index ccd7dcc73..db96de103 100644 --- a/zh/clice/cli/query.md +++ b/zh/clice/cli/query.md @@ -4,16 +4,16 @@ `clice query` 向持久化索引提出一个结构化的问题，并把答案以 JSON 形式打印到 stdout——供那些不想说 LSP、又想拿到语言服务器所掌握事实的脚本和 coding agent 使用。它直接从磁盘读取索引，正是 `clice index` 构建、编辑器会话持续更新的那一份，因此编辑器开着时它照常工作，编辑器没开时也不需要服务器。 -**用法**：`clice query --method [--workspace ] [--configuration ] [--fresh] [question options]` +**用法**：`clice query [ | ] [--workspace ] [--configuration ] [--fresh] [question options]` ## 支持的问题 -- `symbolSearch --symbol [--limit ]` 列出[定位串](#locators)（locator）匹配到的符号，最佳匹配排在最前，并附上各符号的种类、文件、行号、所属容器和 `symbol`。 -- `definition`、`readSymbol`、`references [--include-declaration]`、`callGraph [--direction callers|callees|both]` 和 `typeHierarchy [--direction supertypes|subtypes|both]` 针对 `--symbol ` 指明的那一个符号作答。定位串匹配到多个符号时，会把它们作为 `candidates` 列出；没有符号与该名称完全一致时，同样会列出最接近的匹配。`definition` 和 `readSymbol` 还会给出符号的 `documentation`：以 markdown 形式给出它的文档注释，读法与编辑器的悬停一致——解析 `@param`、`@return` 和 `@copydoc`，没有注释的重写函数显示它所重写函数的文档。 -- `documentSymbols --path ` 给出该文件的大纲。 -- `compileCommand --path ` 给出编辑器编译该文件时会使用的命令，以及它的来源：文件自身的数据库条目、头文件的宿主源文件、规则的默认命令、从邻近翻译单元借来的命令（借给临时成员时为 `provisional`，借给构建之外的文件时为 `inferred`），或内置的回退命令。给出的是经编译器解析后的命令，带有目标平台和系统头文件目录；询问编译器失败时，`toolchainError` 说明原因，命令则停留在未经解析的驱动命令。 -- `projectFiles [--filter all|source|header|module]` 列出构建涉及的文件；`fileDeps --path [--direction includes|includers|both] [--depth ]` 沿包含关系图查询，`impactAnalysis --path ` 则沿包含关系图以及导入该文件所属模块的文件查询。 -- `counterparts --path ` 列出与该文件配对的文件——头文件的源文件、源文件的头文件、模块的接口单元和实现单元——最佳的排在最前，每个都附上理由，并把编辑器无需询问就会直接打开的那一个标为 `preferred`（参见[切换源文件／头文件](../features/navigation.md#switch-source-header)）。 +- `symbol-search [] [--limit ]` 列出[定位串](#locators)（locator）匹配到的符号，最佳匹配排在最前，并附上各符号的种类、文件、行号、所属容器和 `symbol`。 +- `definition `、`read-symbol `、`references [--include-declaration]`、`call-graph [--direction callers|callees|both]` 和 `type-hierarchy [--direction supertypes|subtypes|both]` 针对定位串指明的那一个符号作答。定位串匹配到多个符号时，会把它们作为 `candidates` 列出；没有符号与该名称完全一致时，同样会列出最接近的匹配。`definition` 和 `read-symbol` 还会给出符号的 `documentation`：以 markdown 形式给出它的文档注释，读法与编辑器的悬停一致——解析 `@param`、`@return` 和 `@copydoc`，没有注释的重写函数显示它所重写函数的文档。 +- `document-symbols ` 给出该文件的大纲。 +- `compile-command ` 给出编辑器编译该文件时会使用的命令，以及它的来源：文件自身的数据库条目、头文件的宿主源文件、规则的默认命令、从邻近翻译单元借来的命令（借给临时成员时为 `provisional`，借给构建之外的文件时为 `inferred`），或内置的回退命令。给出的是经编译器解析后的命令，带有目标平台和系统头文件目录；询问编译器失败时，`toolchainError` 说明原因，命令则停留在未经解析的驱动命令。 +- `project-files [--filter all|source|header|module]` 列出构建涉及的文件；`file-deps [--direction includes|includers|both] [--depth ]` 沿包含关系图查询，`impact-analysis ` 则沿包含关系图以及导入该文件所属模块的文件查询。 +- `counterparts ` 列出与该文件配对的文件——头文件的源文件、源文件的头文件、模块的接口单元和实现单元——最佳的排在最前，每个都附上理由，并把编辑器无需询问就会直接打开的那一个标为 `preferred`（参见[切换源文件／头文件](../features/navigation.md#switch-source-header)）。 问题中的路径可以相对于工作区，也可以是绝对路径，答案中的路径一律是绝对路径；行号从 1 开始。 @@ -38,11 +38,11 @@ 局部变量、参数和具有内部链接的实体（`static` 实体，或位于匿名命名空间中的实体）只有能看到它们的文件才知道：按名称查找它们时，必须同时用 `path:` 给出它们所在的文件或该文件所在的目录。 -答案列出的每个符号都带有 `symbol`，即反过来指明该符号的定位串：它的 id；只有部分文件能看到的符号，id 后面再跟上 `path:` 和它所在的文件。把它原样传给 `--symbol` 即可。在 shell 命令行中，要给整个定位串加上引号：在那里 `#` 会开始一段注释，`<` 和 `>` 会重定向，`*` 会被展开。 +答案列出的每个符号都带有 `symbol`，即反过来指明该符号的定位串：它的 id；只有部分文件能看到的符号，id 后面再跟上 `path:` 和它所在的文件。把它原样传回即可。在 shell 命令行中，要给整个定位串加上引号：在那里 `#` 会开始一段注释，`<` 和 `>` 会重定向，`*` 会被展开。 ## 答案 -每个答案都是一个 JSON 对象：成功时是 `{"result": ..., "stale": [...]}`；问题无法回答时（符号不存在、文件不存在、选项取了不支持的值）是 `{"error": "...", "stale": [...]}`，退出码为 1；参数无法解析时同样如此，退出码为 2。定位串匹配到多个符号时，错误中会用 `candidates` 列出它们，每个都附上自己的 `symbol`。 +每个答案都是一个 JSON 对象：成功时是 `{"result": ..., "stale": [...]}`；问题无法回答时（符号不存在、文件不存在、选项取了不支持的值）是 `{"error": "...", "stale": [...]}`，退出码为 1；参数无法解析时（问题未知，定位串或文件缺失或多余）同样如此，退出码为 2。定位串匹配到多个符号时，错误中会用 `candidates` 列出它们，每个都附上自己的 `symbol`。 `stale` 列出答案不得不略过其数据行的文件：它们在磁盘上的内容已经与建立索引时不一致，索引为它们保存的位置会指向移动过的文本。仅因所包含的头文件发生变化的文件，仍用它上一次的数据行作答。定义位于已过期文件中的符号会被报告为未找到，并给出文件名，这样读者就能区分“不存在”和“尚未建立索引”。只有答案查阅过的文件才会被检查：在文件建立索引之后新增的符号只会缺席，因为没有任何数据行指向那个文件——要询问磁盘的当前状态，请用 `--fresh`。索引从不读取编辑器中未保存的缓冲区：它描述的是磁盘上的内容。 diff --git a/zh/clice/cli/refactor.md b/zh/clice/cli/refactor.md index 0932f4da7..f5c270c8f 100644 --- a/zh/clice/cli/refactor.md +++ b/zh/clice/cli/refactor.md @@ -4,7 +4,7 @@ `clice refactor` 根据持久化索引改写工作区的源代码，`clice query` 读取的也是同一份索引。整个过程不做编译，因此在大型源码树上做一次重构，耗时与一次查询相当。目前唯一的重构是 `rename`；编辑器里的重命名走的也是同一个引擎。 -**用法**：`clice refactor rename (--symbol --to | --spec ) [--workspace ] [--configuration ] [--dry-run] [--fresh]` +**用法**：`clice refactor rename ( | --spec ) [--workspace ] [--configuration ] [--dry-run] [--fresh]` ## 重命名 @@ -93,7 +93,7 @@ tests/refactor/edits/01_plan_then_write 若输入的名称对应两个符号，会列出这两个符号，使用带作用域的名称或候选项的 `symbol` 即可选定其中一个 -名称有歧义时，不会执行任何重命名。每个候选项都带有一个 `symbol`，可将其原样传给 `--symbol`。 +名称有歧义时，不会执行任何重命名。每个候选项都带有一个 `symbol`，可将其原样传回。 ```case tests/refactor/locators/02_ambiguous_name diff --git a/zh/clice/features/code-action.md b/zh/clice/features/code-action.md index f60e32452..14de47340 100644 --- a/zh/clice/features/code-action.md +++ b/zh/clice/features/code-action.md @@ -5,7 +5,7 @@ GENERATED markers by hand — edit the cases' README.md and run `pixi run update-feature-docs`. --> -clice 针对选区提供代码操作：依据编译器已掌握的信息生成或改写代码的重构、为头文件未声明的名字提供的快速修复，以及编译器和 clang-tidy 附在诊断上的修复。每个操作在列出时就已完整算好，应用时无需再等一次请求；编辑内容带有计算时所依据的文档版本，缓冲区一旦变动，编辑器就会拒绝它们。同一批操作也可以通过 `clice inspect code_action` 以无头方式运行。 +clice 针对选区提供代码操作：依据编译器已掌握的信息生成或改写代码的重构、为头文件未声明的名字提供的快速修复，以及编译器和 clang-tidy 附在诊断上的修复。每个操作在列出时就已完整算好，应用时无需再等一次请求；编辑内容带有计算时所依据的文档版本，缓冲区一旦变动，编辑器就会拒绝它们。同一批操作也可以通过 `clice inspect code-action` 以无头方式运行。 操作锚定在选区覆盖的最内层构造上——方法声明、类名、一个 `switch`、一个 `auto`——因此列表始终很短：点击方法名，列出的是适用于该方法的操作；点击类名，列出的则是适用于该类的操作。 diff --git a/zh/clice/features/navigation.md b/zh/clice/features/navigation.md index e9f4bc411..238e60fbe 100644 --- a/zh/clice/features/navigation.md +++ b/zh/clice/features/navigation.md @@ -1530,7 +1530,7 @@ tests/workspace_symbol/projects/01_closed_files ## 切换源文件／头文件 -打开与当前文件配对的文件：头文件的源文件、源文件的头文件、模块接口的实现单元、实现单元的接口。在 VS Code 中，可以从编辑器的右键菜单选择 **Switch Source/Header**，也可以按 `Alt+O`，或在命令面板中运行 **Clice: Switch Source/Header**；Neovim 中是 `:LspCliceSwitchSourceHeader`，命令行上则由 `clice query --method counterparts --path ` 给出同样的答案。Zed 不允许扩展添加命令，它自带的 _switch source header_ 只适用于 clangd。 +打开与当前文件配对的文件：头文件的源文件、源文件的头文件、模块接口的实现单元、实现单元的接口。在 VS Code 中，可以从编辑器的右键菜单选择 **Switch Source/Header**，也可以按 `Alt+O`，或在命令面板中运行 **Clice: Switch Source/Header**；Neovim 中是 `:LspCliceSwitchSourceHeader`，命令行上则由 `clice query counterparts ` 给出同样的答案。Zed 不允许扩展添加命令，它自带的 _switch source header_ 只适用于 clangd。 候选文件来自构建和索引已经掌握的信息，因此给出答案无需编译任何东西：另一侧的同名文件（位于该文件自己的目录中，或者位于工作区的其他位置、但两者之间有包含关系）、一方声明而另一方定义的那些声明，以及模块声明。每个候选都附有理由。最佳候选是唯一的候选，或者胜过其余每个候选时，编辑器会直接打开它。胜过对方需要同时满足：在共享声明和同名这两项理由中，对方具备的它都具备；共享声明不比对方少；并且理由比对方多一项，或者在双方都有共享声明时达到对方的两倍，或者在双方都没有共享声明时具备对方没有的模块配对。否则编辑器会列出这些候选，供用户挑选。 diff --git a/zh/clice/guide/configuration.md b/zh/clice/guide/configuration.md index c00be2b60..bc99cc514 100644 --- a/zh/clice/guide/configuration.md +++ b/zh/clice/guide/configuration.md @@ -834,7 +834,7 @@ tests/project/rules/09_remove_flags ## 切换配置 -规则上的 `configuration` 标签构成一份菜单，每个项目中有一个标签生效；不带标签的规则始终适用。生效的那个按优先级依次是 `--configuration ` 参数（`clice serve`、`clice index`、`clice lint` 和 `clice inspect` 都接受它）、持久化的选择、`default_configuration`。选择在编辑器中完成——VS Code 的状态栏显示生效的配置，点击即可打开菜单，其他客户端调用 `clice/switchConfiguration`——并存放在 `state.json` 中，该文件位于 `cache_dir` 下，绝不写入 `clice.toml`；它在服务器再次启动时生效，VS Code 扩展会自行重启服务器。每个配置在 `cache_dir` 下保留各自的索引，因此来回切换绝不会重新索引某个配置已经索引过的内容。批处理命令也通过这些标签选择索引：`clice index --configuration release` 构建 release 配置的索引，`clice index --stats` 报告按同样方式解析出的配置所对应的索引。 +规则上的 `configuration` 标签构成一份菜单，每个项目中有一个标签生效；不带标签的规则始终适用。生效的那个按优先级依次是 `--configuration ` 参数（`clice serve`、`clice index`、`clice lint` 和 `clice inspect` 都接受它）、持久化的选择、`default_configuration`。选择在编辑器中完成——VS Code 的状态栏显示生效的配置，点击即可打开菜单，其他客户端调用 `clice/switchConfiguration`——并存放在 `state.json` 中，该文件位于 `cache_dir` 下，绝不写入 `clice.toml`；它在服务器再次启动时生效，VS Code 扩展会自行重启服务器。每个配置在 `cache_dir` 下保留各自的索引，因此来回切换绝不会重新索引某个配置已经索引过的内容。批处理命令也通过这些标签选择索引：`clice index --configuration release` 构建 release 配置的索引，`clice index stats` 报告按同样方式解析出的配置所对应的索引。 diff --git a/zh/clice/guide/quick-start.md b/zh/clice/guide/quick-start.md index 8e9dd8677..c4f0fad8d 100644 --- a/zh/clice/guide/quick-start.md +++ b/zh/clice/guide/quick-start.md @@ -111,4 +111,4 @@ clice index --workspace /path/to/project 该过程支持断点续作——用 Ctrl-C 中断时会保存进度，下次运行会从上次中断处 继续，而不是从头开始。 -`clice index --stats` 会输出当前持久化索引所包含的内容。 +`clice index stats` 会输出当前持久化索引所包含的内容。