From 6cc070a1bd8d7f1d7436faff05062e154eb9ae43 Mon Sep 17 00:00:00 2001 From: leynos Date: Mon, 20 Jul 2026 16:54:06 +0200 Subject: [PATCH 1/2] Reconcile codescene-health-rules skill with upstream directive docs Fold the remaining details from CodeScene's code health documentation into the skill: - Directives may sit inside larger multi-line comments, and unknown or misspelled smell names are silently ignored. - Record CodeScene's best practices for directives: be restrictive, inspect new directives in review, and document the rationale inline with a date. - Spell out the consequences of a `weight: 0.0` rule (removed from the score, the virtual review, and delta/PR gates) and note that the reported score can then look better than the baseline. - Note the searchable overridden-rules summary under each analysis's Scope section, the template download via the Hotspots configuration, and the exact "Repository with global code health rules" field for global rules. Reformat the file with the repository Markdown tooling. --- skills/codescene-health-rules/SKILL.md | 57 ++++++++++++++++++++------ 1 file changed, 44 insertions(+), 13 deletions(-) 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)` ______________________________________________________________________ From 9a2ff73c5f3d03275f7800701efe178c44cb4c67 Mon Sep 17 00:00:00 2001 From: leynos Date: Mon, 20 Jul 2026 16:59:53 +0200 Subject: [PATCH 2/2] Add codescene-cli skill for local CodeScene analyses Document the CodeScene `cs` CLI as a skill covering the core workflows: - `cs delta` for change-based analysis of the working tree, staged content, commits, and branches, including git-hook integration. - `cs review` and `cs check` for file-focused feedback (JSON and lint-style respectively), including `:` targets and stdin. - `cs rules-config` and `cs check-rules` for validating and editing `.codescene/code-health-rules.json` from the command line. - `cs docs` topics, environment variables, installation, updating, and activation. Licensing is documented against Personal Access Tokens; the older "CodeScene CLI" / devtools tokens are deprecated. The skill cross-references `codescene-health-rules` for the semantics of the rules file itself. Accept `edn` (the output format) in the typos dictionary and commit the regenerated `typos.toml`. --- skills/codescene-cli/SKILL.md | 180 ++++++++++++++++ .../references/command-reference.md | 197 ++++++++++++++++++ .../references/install-and-activate.md | 90 ++++++++ typos.local.toml | 1 + typos.toml | 1 + 5 files changed, 469 insertions(+) create mode 100644 skills/codescene-cli/SKILL.md create mode 100644 skills/codescene-cli/references/command-reference.md create mode 100644 skills/codescene-cli/references/install-and-activate.md 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/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"