diff --git a/skills/codescene-cli/SKILL.md b/skills/codescene-cli/SKILL.md new file mode 100644 index 0000000..1f18cba --- /dev/null +++ b/skills/codescene-cli/SKILL.md @@ -0,0 +1,180 @@ +--- +name: codescene-cli +description: > + Run CodeScene code health analyses locally with the `cs` CLI. Use this skill + whenever the user wants to analyse non-committed or staged changes, compare + branches or commits with a delta analysis, lint a file for code health issues, + wire CodeScene into git hooks, editors, or CI, validate or edit + `.codescene/code-health-rules.json` from the command line, or install, + update, or activate the CodeScene CLI. Triggers include `cs delta`, + `cs review`, `cs check`, `cs check-rules`, `cs rules-config`, and requests to + "run CodeScene locally" or "check code health before committing". +--- + +# CodeScene CLI (`cs`) + +The CodeScene CLI runs code health analyses where developers work: locally, in +pre-commit/push hooks, and in CI. Core workflows: + +- **`cs delta`** — change-based analysis between the working tree, commits, or + branches. Use before opening a PR to see the code health impact of a change. +- **`cs review`** / **`cs check`** — file-focused feedback. `review` prints a + JSON structure; `check` prints lint-style output for editor integration. +- **`cs rules-config`** / **`cs check-rules`** — validate and edit custom code + health rules from the command line. + +For the semantics of `.codescene/code-health-rules.json` itself (rule names, +weights, thresholds, `@codescene` directives), use the `codescene-health-rules` +skill; this skill covers the CLI tooling around it. + +______________________________________________________________________ + +## Choosing the Right Command + +| Task | Command | +| ------------------------------------------------ | ------------------------------------ | +| Analyse all non-committed changes | `cs delta` | +| Analyse only staged content (pre-commit hook) | `cs delta --staged` | +| Compare a feature branch against main | `cs delta main feat` | +| Machine-readable findings for a single file | `cs review file.py` | +| Lint-style output for an editor or quick check | `cs check file.py` | +| See which custom rule set matches a file | `cs check-rules file.py` | +| Validate or edit `code-health-rules.json` | `cs rules-config ` | +| Emit a starter `code-health-rules.json` template | `cs docs code-health-rules-template` | + +______________________________________________________________________ + +## `cs delta` — Change-Based Analysis + +```bash +cs delta # analyse all non-committed changes +cs delta --staged # examine only staged content +cs delta --file src/Server.js # analyse one file +cs delta main # analyse changes against the main branch +cs delta main feat # analyse changes between two branches +cs delta main~30 main # analyse the latest 30 commits on main +cs delta --output-format json # machine-readable output +``` + +Key behaviour: + +- Specifying any `--output-format` (json or edn) reports **new issues only** — + no improvements or explanations. Add `--pretty` to pretty-print. +- `--interactive` forces user input for findings (see `cs docs interactive`). +- `--git-hook` adapts the command for use in a git hook (see + `cs docs git-hooks`). + +### Git hook integration + +A pre-commit hook running `cs delta --staged --git-hook` catches code health +regressions before they reach the remote. Generate a working example with: + +```bash +cs docs pre-commit-hook-example # plain pre-commit hook +cs docs interactive-pre-commit-hook-example # interactive variant +``` + +______________________________________________________________________ + +## `cs review` and `cs check` — File-Focused Analysis + +Both accept a file path, a `:` git reference, or stdin: + +```bash +cs review test.c # working-tree file, JSON results +cs review master:./test.c # the file as it is on master +cs review 801b0c0f:./test.c # the file at a given commit +cs review --file-name test.c < test.c # read file data from stdin + +cs check test.c # same targets, lint-like output +cs check --file-name test.c < test.c +``` + +- `--file-name` is required when reading from stdin so the CLI can infer the + language from the extension. +- `cs review` supports `--output-format json|edn` and `--pretty`. +- `cs check` is designed for editor integration — see `cs docs vim` for a + (neo)vim example. + +______________________________________________________________________ + +## `cs rules-config` — Edit Rules from the CLI + +Validates and edits `code-health-rules.json` without hand-editing JSON. +Defaults to `.codescene/code-health-rules.json` in the current git repository; +override with `--config-path `. + +```bash +cs rules-config validate +cs rules-config validate --config-path /tmp/code-health-rules.json + +# Disable or enable a rule (single rule_set in the file) +cs rules-config set-rule --rule-name "Complex Method" --enabled false + +# With multiple rule_sets, select one via its glob +cs rules-config set-rule --matching-content-path "**/*.js" \ + --rule-name "Complex Method" --enabled false + +# Set a threshold +cs rules-config set-threshold \ + --threshold-name function_lines_of_code_warning --value 120 + +# List the threshold names and defaults for a language +cs rules-config list-thresholds --language Python --format json +``` + +Behavioural notes: + +- `--enabled true` stores weight `1.0`; `--enabled false` stores weight `0.0`. + For intermediate weights (down-prioritizing rather than disabling), edit the + JSON directly — see the `codescene-health-rules` skill. +- If no config file exists, `set-rule`/`set-threshold` create a minimal one at + the default path before applying the change. +- With multiple `rule_set` entries and no `--matching-content-path`, the + command fails and prints the available selectors. +- Unknown rule or threshold names fail with suggestions. +- If an update would create invalid config, the original file is restored. + +Use `cs check-rules ` to confirm which rule set a given file matches — +invaluable when debugging glob patterns. + +______________________________________________________________________ + +## `cs docs` — Built-In Documentation Topics + +```bash +cs docs git-hooks # delta in a git hook +cs docs interactive # delta interactive mode +cs docs pre-commit-hook-example # outputs an example pre-commit hook +cs docs vim # "check" integration for (neo)vim +cs docs license # setting up a license +cs docs file-name # file-name and language support +cs docs code-health-rules # customizing code health rules +cs docs code-health-rules-template # outputs a rules template +``` + +______________________________________________________________________ + +## Environment Variables + +| Variable | Purpose | +| -------------------------- | ------------------------------------------ | +| `CS_ACCESS_TOKEN` | Personal Access Token for licensing | +| `CS_ACCOUNT_ID` | Cloud account for `cs auth login` (OAuth) | +| `CS_ONPREM_URL` | Base URL for CodeScene Enterprise | +| `CS_DISABLE_VERSION_CHECK` | Disable the automatic version check | +| `CS_CERTS` | Extra trusted certs (DER/PEM/PKCS12 paths) | +| `CS_CERTS_PASSWORD` | Password for PKCS12 files | + +Licensing uses a **Personal Access Token** in `CS_ACCESS_TOKEN`; the older +"CodeScene CLI" / devtools tokens are deprecated. `cs version` prints the build +date and SHA of the installed tool. + +______________________________________________________________________ + +## Reference Files + +- [`references/command-reference.md`](references/command-reference.md) — Full + options for every command, verbatim from the upstream reference +- [`references/install-and-activate.md`](references/install-and-activate.md) — + Installation, updating, licensing, and platform-specific notes diff --git a/skills/codescene-cli/references/command-reference.md b/skills/codescene-cli/references/command-reference.md new file mode 100644 index 0000000..74e965e --- /dev/null +++ b/skills/codescene-cli/references/command-reference.md @@ -0,0 +1,197 @@ +# CodeScene CLI Command Reference + +Condensed from the upstream command reference. Run any command with `-h` / +`--help` for the authoritative help text of the installed version. + +______________________________________________________________________ + +## `cs delta` + +Run a delta analysis: compare current work against a previous state of the +code. See also `cs docs git-hooks`. + +```text +USAGE + $ cs delta [] [ []] + +OPTIONS + --staged Examine only staged content. + --interactive Interactive mode, forcing user input for findings. + See `cs docs interactive`. + --git-hook Run as a git hook. See `cs docs git-hooks`. + --output-format Output in json or edn format. Default human-readable. + --pretty Use with --output-format to pretty-print. + --verbose Verbose output + -h, --help Show help +``` + +Examples: + +```bash +cs delta # analyse all non-committed changes +cs delta --file src/Server.js # analyse one file +cs delta --output-format json # json output; reports NEW issues only — + # no improvements or explanations +cs delta main # analyse changes against the main branch +cs delta main feat # analyse changes between two branches +cs delta main~30 main # analyse the latest 30 commits on main +``` + +______________________________________________________________________ + +## `cs review` + +Check a file for code health issues and print the results as JSON. + +```text +USAGE + $ cs review [] [] + +OPTIONS + --file-name File-name when reading from stdin + --output-format Output in json or edn format. Default human-readable. + --pretty Use with --output-format to pretty-print. + --verbose Verbose output + -h, --help Show help +``` + +Examples: + +```bash +cs review test.c # check the file test.c +cs review master:./test.c # test.c as on the master branch +cs review 801b0c0f:./test.c # test.c at the given commit +cs review --file-name test.c < test.c # read file data from stdin +``` + +______________________________________________________________________ + +## `cs check` + +Check a file for code health issues and print the results in a lint-like manner. + +```text +USAGE + $ cs check [] [] + +OPTIONS + --file-name File-type/extension when reading from stdin + --verbose Verbose output + -h, --help Show help +``` + +Examples: + +```bash +cs check test.c # check the file test.c +cs check master:./test.c # test.c as on the master branch +cs check 801b0c0f:./test.c # test.c at the given commit +cs check --file-name test.c < test.c # read file data from stdin +``` + +______________________________________________________________________ + +## `cs check-rules` + +Find out which custom rules, if any, match the given file. Useful when creating +a custom `code-health-rules.json`. + +```bash +cs check-rules test.c # which code health rule set matches test.c +``` + +______________________________________________________________________ + +## `cs rules-config` + +Validate and edit a `code-health-rules.json` configuration file. Four +subcommands: `validate`, `set-rule`, `set-threshold`, `list-thresholds`. + +```text +USAGE + $ cs rules-config validate [--config-path ] + $ cs rules-config set-rule --rule-name --enabled true|false + [selector-options] + $ cs rules-config set-threshold --threshold-name + --value [selector-options] + $ cs rules-config list-thresholds --language [--format json] + [--config-path ] + +SELECTOR OPTIONS + --matching-content-path Required when multiple rule sets exist + +COMMON OPTIONS + --config-path Defaults to .codescene/code-health-rules.json in the + current git repo + --language Language name, e.g. Python, JavaScript, Java + --format json Output format (only json is supported) +``` + +Examples: + +```bash +cs rules-config validate +cs rules-config validate --config-path /tmp/code-health-rules.json +cs rules-config set-rule --rule-name "Complex Method" --enabled false +cs rules-config set-rule --matching-content-path "**/*.js" \ + --rule-name "Complex Method" --enabled false +cs rules-config set-threshold \ + --threshold-name function_lines_of_code_warning --value 120 +cs rules-config set-threshold \ + --threshold-name function_lines_of_code_warning --value 120 \ + --matching-content-path "**/*.js" +cs rules-config list-thresholds --language Python --format json +cs rules-config list-thresholds --language Java --format json +cs rules-config list-thresholds --language "C#" --format json +``` + +Semantics: + +- Default file: with no `--config-path`, the command uses + `.codescene/code-health-rules.json` from the current git repository. +- With a single `rule_set` in the file, `set-rule` and `set-threshold` update + it directly. With multiple `rule_set` entries, pass `--matching-content-path` + to select which rule set to edit; omitting it makes the command fail and + print the available selectors. +- `--enabled true` stores weight `1.0`; `--enabled false` stores weight `0.0`. +- If no config file exists when running `set-rule` or `set-threshold`, a + minimal file is created automatically at the default path first. +- Unknown rule or threshold names fail with suggestions. +- If an update creates invalid config, the original file is restored. + +______________________________________________________________________ + +## `cs docs` + +CodeScene CLI documentation topics: `cs docs `. + +| Topic | Covers | +| ------------------------------------- | ----------------------------------- | +| `git-hooks` | Using delta in a git hook | +| `interactive` | Delta interactive mode | +| `interactive-pre-commit-hook-example` | Example interactive pre-commit hook | +| `pre-commit-hook-example` | Example pre-commit hook | +| `vim` | `check` integration for (neo)vim | +| `license` | Setting up a license | +| `file-name` | File-name and language support | +| `code-health-rules` | Customizing code health rules | +| `code-health-rules-template` | Outputs a rules template | + +______________________________________________________________________ + +## `cs version` + +Displays the version, including the build date and SHA of the installed tool. + +______________________________________________________________________ + +## Environment Variables + +| Variable | Purpose | +| -------------------------- | ------------------------------------------ | +| `CS_ACCESS_TOKEN` | Personal Access Token for licensing | +| `CS_ACCOUNT_ID` | Cloud account selector for `cs auth login` | +| `CS_ONPREM_URL` | Base URL for CodeScene Enterprise | +| `CS_DISABLE_VERSION_CHECK` | Disable the automatic version update check | +| `CS_CERTS` | Extra trusted certs (DER/PEM/PKCS12 paths) | +| `CS_CERTS_PASSWORD` | Password for PKCS12 files, if any | diff --git a/skills/codescene-cli/references/install-and-activate.md b/skills/codescene-cli/references/install-and-activate.md new file mode 100644 index 0000000..ab69e20 --- /dev/null +++ b/skills/codescene-cli/references/install-and-activate.md @@ -0,0 +1,90 @@ +# Installing and Activating the CodeScene CLI + +## Install (Linux, macOS, Windows via WSL) + +The install script downloads the binary, moves it to `~/.local/bin`, makes it +executable, and adds `~/.local/bin` to `PATH` if needed. Works with bash, zsh, +or fish: + +```bash +curl https://downloads.codescene.io/enterprise/cli/install-cs-tool.sh | sh +``` + +## Manual installation + +Download the binary for your platform and make it executable: + +- Linux amd64: + `https://downloads.codescene.io/enterprise/cli/cs-linux-amd64-latest.zip` +- Linux aarch64: + `https://downloads.codescene.io/enterprise/cli/cs-linux-aarch64-latest.zip` +- Windows amd64: + `https://downloads.codescene.io/enterprise/cli/cs-windows-amd64-latest.zip` +- macOS amd64: + `https://downloads.codescene.io/enterprise/cli/cs-macos-amd64-latest.zip` +- macOS aarch64: + `https://downloads.codescene.io/enterprise/cli/cs-macos-aarch64-latest.zip` + +Platform-specific notes: + +- macOS binaries are not signed; move them out of quarantine with + `xattr -dr com.apple.quarantine `. +- Windows users might have to set the script execution policy manually: + `Set-ExecutionPolicy RemoteSigned`. + +## Updating + +Re-run the install script, or repeat the manual installation. Check the +installed version with `cs version` (prints build date and SHA). + +## Activation (licensing) + +The CLI requires an access token for licensing. Use a **Personal Access Token** +generated from your CodeScene user settings — the older "CodeScene CLI" / +devtools tokens are **deprecated** and have been replaced by Personal Access +Tokens. Then: + +```bash +export CS_ACCESS_TOKEN= +``` + +Windows PowerShell: + +```powershell +$env:CS_ACCESS_TOKEN = '' +``` + +Windows Command Prompt: + +```bat +SET CS_ACCESS_TOKEN= :: temporary, current session only +SETX CS_ACCESS_TOKEN :: persistent; takes effect in NEW terminals +``` + +Variables can also be set via System Properties → Advanced → Environment +Variables (shortcut: `Windows + R`, run `sysdm.cpl`, Advanced tab). + +## OAuth login (Cloud) + +For browser-based OAuth login, set `CS_ACCOUNT_ID` to a positive account ID +before running `cs auth login` to select that Cloud account: + +```bash +CS_ACCOUNT_ID=123 cs auth login +``` + +- The signed-in user must be a member of the requested account. +- OAuth credentials are stored separately for each selected account. +- `CS_ACCOUNT_ID` does not affect `CS_ACCESS_TOKEN` authentication. + +## Enterprise + +Point the CLI at a CodeScene Enterprise instance with: + +```bash +export CS_ONPREM_URL= +``` + +Additional trusted certificates can be supplied via `CS_CERTS` (DER, PEM, or +PKCS12 paths, comma or semicolon separated) and `CS_CERTS_PASSWORD` for PKCS12 +files. diff --git a/skills/codescene-health-rules/SKILL.md b/skills/codescene-health-rules/SKILL.md index 3854750..c6be4db 100644 --- a/skills/codescene-health-rules/SKILL.md +++ b/skills/codescene-health-rules/SKILL.md @@ -29,9 +29,12 @@ When the user asks to generate or modify `code-health-rules.json`: specific language, a legacy subdirectory?) 2. **Clarify intent per rule** — disable entirely (`0.0`), down-weight (`0.1–0.9`), or tighten/loosen a raw threshold? -3. **Emit only the overrides** — omit rules the user wants kept at defaults; +3. **Start from CodeScene's template if available** — a documented JSON + template is downloadable via the Hotspots section of the project + configuration; remove any rules that should stay at defaults. +4. **Emit only the overrides** — omit rules the user wants kept at defaults; this is how CodeScene itself recommends it and it reduces config drift. -4. **Place the file at `.codescene/code-health-rules.json`** in the repo root +5. **Place the file at `.codescene/code-health-rules.json`** in the repo root and commit it alongside application code. ______________________________________________________________________ @@ -79,14 +82,16 @@ Multiple `rule_sets` are allowed in one file — each matching a different glob. ### Precedence -``` +```text local .codescene/code-health-rules.json ↳ global rules repo (configured in Project > Hotspots) ↳ CodeScene built-in defaults ``` -A local repo file always wins. When updating global rules, trigger a full -analysis before delta analyses pick up the changes. +A local repo file always wins. Global rules come from one designated +repository, set via the **"Repository with global code health rules"** field in +the Hotspots tab of the project configuration. When updating global rules, +trigger a full analysis before delta analyses pick up the changes. ______________________________________________________________________ @@ -99,6 +104,17 @@ ______________________________________________________________________ | `0.1` | Near-invisible; useful for "track but don't fail PR gates" | | `0.0` | Rule disabled: excluded from score, virtual review, and PR gates | +**Consequences of disabling a rule** (all three apply at `weight: 0.0`): + +- The rule leaves the code health calculation entirely, so the reported score + can look *better* than the previously reported baseline. +- The rule is not presented in the virtual code review. +- The rule is not supervised by delta analysis or PR quality gates. + +For transparency, CodeScene shows a searchable summary of all overridden rules +under the **Scope** section of each analysis, and overridden thresholds appear +in the virtual code review of every impacted file. + **Do not disable the critical rules** — see `references/rules-catalogue.md` for which rules are advisory vs critical. Disabling a critical rule means you lose early warning on the findings most correlated with defect density. @@ -193,14 +209,29 @@ void legacy_dispatch(Event* e) { … } **Rules for directives:** -- Applies to the **function immediately following** the comment. -- Works for **function-level smells only** — cannot suppress module-level issues - (Lines of Code, Low Cohesion, Brain Class, etc.). -- The smell name must **exactly match** what the virtual code review shows. Note - that "Bumpy Road" appears as `"Bumpy Road Ahead"` in directive context. -- CodeScene surfaces all active directives in the PR review summary. Nothing - flies under the radar. -- Always include a rationale and a date so future maintainers can reassess. +- A directive **always applies to the function/method immediately following** + it. +- Works for **all function-level smells, and only those** — cannot suppress + module/file-level issues (Lines of Code, Low Cohesion, Brain Class, etc.). +- The smell name must **exactly match** what the virtual code review shows. + Unknown or misspelled names are **silently ignored** — no error, no + suppression. Note that "Bumpy Road" appears as `"Bumpy Road Ahead"` in + directive context. +- Directives may sit inside a **larger multi-line comment** (e.g. a Java + `/** … */` doc block); they need not be a standalone comment line. +- The virtual code review includes a **non-blocking warning** about any + directives in use, together with their impact, and CodeScene flags **new** + directives in its PR review summary. Nothing flies under the radar. + +**Best practices** (per CodeScene's own guidance): + +- **Be restrictive** — the clear majority of code health findings are real + problems that should be refactored, not suppressed. +- **Inspect new directives in review** — the PR review summary calls them out to + make this easy. +- **Document the rationale on the directive line, with a date**, so future + maintainers can reassess whether it still applies: + `// @codescene(disable-all) Rewrite next week (2020-01-30)` ______________________________________________________________________ diff --git a/typos.local.toml b/typos.local.toml index 2c3a836..0f77f7b 100644 --- a/typos.local.toml +++ b/typos.local.toml @@ -10,6 +10,7 @@ accepted = [ "ANALYZER", "MOLD", "analyzer", + "edn", "ises", "mold", ] diff --git a/typos.toml b/typos.toml index 28edcb7..ac6a1ac 100644 --- a/typos.toml +++ b/typos.toml @@ -707,6 +707,7 @@ extend-ignore-re = [ "dramatizers" = "dramatizers" "dramatizes" = "dramatizes" "dramatizing" = "dramatizing" +"edn" = "edn" "emphasisable" = "emphasizable" "emphasisably" = "emphasizably" "emphasisation" = "emphasization"