@gspothq/cli 0.1.1 → 0.2.0

package/configurations/general/engineering/rules/code/TESTING.md

@@ -1,5 +1,7 @@
 # Testing
 
+Read this rule when you write or change a test.
+
 Tests exist to catch bugs. A useful test fails when the behavior it covers breaks.
 
 ## Assertions
@@ -7,20 +9,23 @@ Tests exist to catch bugs. A useful test fails when the behavior it covers break
 - Use Arrange, Act, Assert. Test behavior, not private implementation details.
 - Assert exact values that the public interface defines, such as status codes, exit codes, and
   messages. Do not pin incidental configuration or internal representation.
-- Cover relevant empty and null inputs, limits, expected errors, and unexpected internal errors.
-- Assert every changed outcome: responses, stored rows, outbound requests, side effects, and logs.
-- A test has meaningful assertions; it does not merely prove that the code called a collaborator or
-  that a mock returns the value supplied to it.
+- Cover relevant empty and null inputs, limits, expected errors, and unexpected internal ones.
+- Assert every changed result: responses, stored rows, outbound requests, side effects, and logs.
+- A test has meaningful assertions; it does not only prove that the code called a collaborator or
+  that a mock returns its input.
 - Use snapshots only for stable data, and review every change to them.
 - Do not add test-only authentication bypasses, magic headers, or bypass routes.
+- Do not write a test that only repeats a constant, a table, or a configuration value. A test runs code and checks
+  its result.
+- Do not export a function only so that a test can call it. Test it through the public function that uses it.
 
 ## Mocks
 
 - Mock only what leaves the process: network, filesystem, subprocesses, clock, and database.
   Never mock the code under test or provider SDK internals.
-- Mock the module that talks to the network or database. Use dependency injection when the
-  code declares the dependencies. Replace that whole module rather than hiding selected behavior.
-- Keep mocks that affect the outcome in the arrange step. Reset or redefine shared mocks before
+- Mock the module that calls the network or database. Use dependency injection when the
+  code declares the dependencies. Replace that whole module rather than hiding parts of its behavior.
+- Keep mocks that affect the result in the arrange step. Reset or redefine shared mocks before
   each test; do not use surprising global auto-mocks.
 - Restore environment variables, globals, fake timers, and spies changed by a test.
 
@@ -28,10 +33,10 @@ Tests exist to catch bugs. A useful test fails when the behavior it covers break
 
 <!-- level: all -->
 
-- Follow the framework or runner's test layout and keep one layout in each repository.
-- Put builders, fakes, servers, and database support in the declared test support folder, never
+- Follow the test layout of the framework or runner, and keep one per repository.
+- Put builders, fakes, servers, and database code in the declared test support folder, never
   in `mocks/`, `helpers/`, or `utils/`. Support files contain no assertions or test blocks.
-- A test name states the scenario and expected outcome. Never use `test1`, `works`, `edge cases`,
+- A test name states the scenario and expected result. Never use `test1`, `works`, `edge cases`,
   or `happy path`. Group tests by unit, then scenario.
 - Prefer role and label queries. Use a test ID last; name it in camelCase for its control, such
   as `submitButton`. Never put visible text, user data, or record IDs in it.
@@ -44,9 +49,11 @@ Tests exist to catch bugs. A useful test fails when the behavior it covers break
   in a shared database.
 - Do not share mutable IDs between tests or count unrelated data. Add unrelated records when a
   test must prove that the code leaves them unchanged.
-- Use unique queue names, event IDs, operation IDs, or correlation IDs for event-driven tests.
+- Use unique queue names and event, operation, or correlation IDs for event-driven tests.
   Never purge shared queues or tables as a substitute for isolated data.
 - Do not use fixed sleeps. Use bounded polling, fake timers, or a signal that proves completion.
+- Test data does not copy the current version of the project or of a tool. Read the version from the dependency
+  file, or use a value outside real releases, such as `0.0.0-test`.
 
 ## Network and providers
 

package/configurations/general/files/manifest.toml

@@ -1,141 +1,113 @@
 allowed_words = ["JSON", "TOML", "YAML"]
+
 [configuration]
-title = "JSON, YAML, TOML, and XML files"
 always_selected = true
-description = "Checks JSON, YAML, TOML, XML, and related formats. Its tool files configure the tools that read these files."
+description = "Checks JSON, YAML, TOML, XML, and related formats, and writes a tool file for each checker."
+title = "JSON, YAML, TOML, and XML files"
 
 [files]
 extensions = [".json", ".jsonc", ".json5", ".yaml", ".yml", ".toml", ".xml"]
 
 [[tool]]
-name = "taplo"
-version = "0.10.0"
-min_version = "0.9.0"
-mise = "taplo"
 brew = "taplo"
 cargo = "taplo-cli"
+min_version = "0.9.0"
+mise = "taplo"
+name = "taplo"
+replace = ["taplo.toml", ".taplo.toml"]
+version = "0.10.0"
 # No npm pin: the npm build of Taplo checks no file on Windows, so every platform takes the native release.
 github = { name = "tamasfe/taplo", version = "0.10.0" }
-[[tool.replace]]
-file = "taplo.toml"
-shared = false
-
-[[tool.replace]]
-file = ".taplo.toml"
-shared = false
 
 [[tool]]
-name = "yamllint"
-version = "1.38.0"
+brew = "yamllint"
 mise = "pipx:yamllint"
+name = "yamllint"
 pypi = "yamllint"
-brew = "yamllint"
-[[tool.replace]]
-file = ".yamllint"
-shared = false
-
-[[tool.replace]]
-file = ".yamllint.yml"
-shared = false
-
-[[tool.replace]]
-file = ".yamllint.yaml"
-shared = false
+replace = [".yamllint", ".yamllint.yml", ".yamllint.yaml"]
+version = "1.38.0"
 
 [[tool]]
+mise = "npm:v8r"
 name = "v8r"
+npm = "v8r"
 requires = ["ajv"]
 version = "6.1.0"
-mise = "npm:v8r"
-npm = "v8r"
 
 # v8r imports this optional peer when it loads ajv-draft-04. Tool projects must install it.
 
 [[tool]]
-name = "ajv"
 kind = "library"
-version = "8.20.0"
+name = "ajv"
 npm = "ajv"
+version = "8.20.0"
 
 [[tool]]
+apt = "libxml2-utils"
+brew = "libxml2"
 name = "xmllint"
 system = true
-brew = "libxml2"
-apt = "libxml2-utils"
 
 [[tool_file]]
 target = ".gspot/config/taplo.toml"
 tool = "taplo"
 
 [[tool_file]]
+per_scope = true
 target = ".gspot/config/yamllint.yml"
 tool = "yamllint"
-per_scope = true
-rule_keys = ["rules"]
 
 [[tool_file]]
 target = ".gspot/config/v8r.yml"
 tool = "v8r"
 
 [[check]]
-name = "taplo"
-example = "The TOML line `enabled =` lacks a value and reports a parse error. Use `enabled = true` when the setting is a boolean."
-level = "recommended"
-stage = "commit"
-command = ["taplo", "check", "--config", "{tool_file:taplo}", "--colors", "never", "{files}"]
+command = ["taplo", "fmt", "--config", "{tool_file:taplo}", "--colors", "never", "--check", "--diff", "{files}"]
+example = "The TOML line `enabled=true` differs from the taplo output. Run `gspot check --fix` to get `enabled = true`."
 files = { extensions = [".toml"] }
-output = { format = "regex", pattern = "^\\s*┌─ (?<file>(?:[A-Za-z]:)?[^:]+):(?<line>\\d+):(?<column>\\d+)$", message = "The file does not parse as TOML." }
-summary = "Parses every TOML file with taplo; the schema check runs at push through v8r."
-why = "A TOML file that does not parse stops the tool that reads it at the worst moment."
-help = "Fix the line taplo names."
-
-[[check]]
-name = "taplo-format"
-example = "The TOML assignment `enabled=true` differs from the configured formatter output. Run the formatter to obtain `enabled = true` and rerun."
+fix = ["taplo", "fmt", "--config", "{tool_file:taplo}", "--colors", "never", "{files}"]
+help = "Run `gspot check --fix`."
 level = "recommended"
+name = "taplo-format"
+output = { format = "regex", pattern = "^(?:\\s*┌─ (?<file>(?:[A-Za-z]:)?[^:]+):(?<line>\\d+):(?<column>\\d+)|--- a/(?<file>.+)|ERROR taplo:format_files: the file is not properly formatted path=\"(?<file>[^\"]+)\")$", message = "The file does not parse as TOML, or it is not in the format of the configured TOML settings.", fixable = "^(?:--- a/|ERROR taplo:format_files)" }
 stage = "commit"
-command = ["taplo", "fmt", "--config", "{tool_file:taplo}", "--colors", "never", "--check", "--diff", "{files}"]
-fix = ["taplo", "fmt", "--config", "{tool_file:taplo}", "--colors", "never", "{files}"]
-files = { extensions = [".toml"] }
-output = { format = "regex", pattern = "^(?:--- a/(?<file>.+)|ERROR taplo:format_files: the file is not properly formatted path=\"(?<file>[^\"]+)\")$", message = "The file is not formatted with the configured TOML settings." }
-summary = "Checks that every TOML file is formatted the way taplo formats it with the shared settings."
+summary = "Checks that every TOML file parses and matches the taplo output under the shared settings."
 why = "One formatter keeps a diff about the values, not the spacing."
-help = "Run gspot check --fix."
 
 [[check]]
-name = "yamllint"
-example = "Two `enabled` keys in the same YAML mapping report a duplicate-key finding. Keep the one intended value and remove the duplicate."
-level = "recommended"
-stage = "commit"
 command = ["yamllint", "-c", "{tool_file:yamllint}", "-f", "parsable", "-s", "{files}"]
+example = "Two `enabled` keys in one YAML mapping report a duplicate key. Keep one, and delete the other."
 files = { extensions = [".yaml", ".yml"] }
+help = "Fix the line yamllint names, or change rule options with `gspot set tools.yamllint.rules`."
+level = "recommended"
+name = "yamllint"
 output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):(?<column>\\d+): \\[(?:error|warning)\\] (?<message>.*?)(?: \\((?<rule>[a-z-]+)\\))?$" }
+stage = "commit"
 summary = "Parses every YAML file and checks its indentation, keys, and values with yamllint."
 why = "A YAML file that parses to the wrong shape fails silently: a duplicated key wins, a stray tab changes the nesting."
-help = "Fix the line yamllint names, or set the rule's options with gspot set tools.yamllint.rules."
 
 [[check]]
-name = "v8r"
-example = "A governed JSON file with a string where its selected schema requires a boolean reports a schema mismatch. Replace the value with the intended boolean and rerun against the same schema."
-level = "recommended"
-stage = "push"
-needs = ["network"]
 command = ["v8r", "--output-format", "text", "{files}"]
 env = { V8R_CONFIG_FILE = "{tool_file:v8r}" }
+example = "A JSON file with a string where its schema requires a boolean reports a mismatch. Replace the string with `true` or `false`."
 files = { extensions = [".json", ".jsonc", ".yaml", ".yml", ".toml"] }
-output = { format = "regex", pattern = "^(?<file>[^#\\s]+)#(?<message>.+)$" }
-summary = "Validates every tool file that has a known schema against it: package.json, tsconfig.json, mise, workflows and the rest of the SchemaStore catalog."
-why = "A key the schema refuses is a setting that never applies, and nobody finds out until the behavior it was meant to change does not change."
 help = "Fix the key v8r names, or map the file to its schema under tools.v8r.schema."
+level = "recommended"
+name = "v8r"
+needs = ["network"]
+output = { format = "regex", pattern = "^(?<file>[^#\\s]+)#(?<message>.+)$" }
+stage = "push"
+summary = "Validates each file that matches a SchemaStore schema, such as package.json, tsconfig.json, mise files, and workflows."
+why = "A key the schema rejects never takes effect, and nobody notices until the expected behavior fails to appear."
 
 [[check]]
-name = "xmllint"
-example = "The XML text `<settings><enabled>true</settings>` has mismatched tags. Close the child element as `<enabled>true</enabled>` before closing `settings`."
-level = "recommended"
-stage = "commit"
 command = ["xmllint", "--noout", "{files}"]
+example = "The XML text `<settings><enabled>true</settings>` has mismatched tags. Close the child element as `<enabled>true</enabled>` before closing `settings`."
 files = { extensions = [".xml", ".storyboard", ".xib"] }
+help = "Fix the line xmllint names."
+level = "recommended"
+name = "xmllint"
 output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+): (?<message>.*)$" }
+stage = "commit"
 summary = "Parses every XML file with xmllint."
-why = "Malformed XML is refused by the reader at the worst moment."
-help = "Fix the line xmllint names."
+why = "A parser rejects malformed XML at the worst moment."

package/configurations/general/files/rules/YAML.md

@@ -1,19 +1,29 @@
 # YAML
 
-Rules for every `.yml` and `.yaml` file.
+Read this rule when you change a `.yml` or `.yaml` file.
 
 - Keep one document per file unless the consumer requires a stream.
-- Quote strings that YAML otherwise reinterprets: `yes`, `no`, `on`, `off`, `null`, `~`,
-  version numbers such as `1.10`, octal-looking values, and anything starting with `*`, `&`, `!`,
-  `%`, `@`, or a backtick.
-- Keep anchors and aliases inside one file. Name them for what they carry. No merge keys
-  across documents.
-- Long strings use a block scalar, `|` or `>`, rather than a quoted string with escapes.
+- Quote a string value that YAML otherwise reads as another type: `yes`, `no`, `on`, `off`, `null`, `~`, a version
+  such as `1.10`, an octal-looking number, and text that starts with `*`, `&`, `!`, `%`, `@`, or a backtick.
+- Name each anchor for what it holds, such as `&checkout-options`. Do not keep a name that a tool generated, such as
+  `&a1`.
+- Do not use merge keys, `<<:`. YAML 1.2 does not define them, and some readers ignore them.
+- Write a long string as a block scalar, `|` or `>`, not as a quoted string with escapes.
+
+## Comments
+
+- Put a comment that describes the whole file at the top, above the first key. Do not put it after `name:`
+  or between two top-level keys.
+- Put a comment about one key on the line above it, at the same indentation.
+- Do not add a comment at the end of a line. Allow a version comment only after a pinned commit, such as
+  `uses: jdx/mise-action@<sha> # v5.1.1`.
+- When the format has a description field, such as `description` in `action.yml`, put the text there, not in a
+  comment.
+- A comment describes the current file. Do not write work status in a comment, such as "jobs stay paused."
 
 ## Organization
 
 <!-- level: all -->
 
-- Order keys as the consumer documents, then alphabetically. Do not reorder keys in a file
-  you did not otherwise change.
-- Use `.yml` for GitHub workflows, `compose.yaml` for Compose, and `.yaml` elsewhere.
+- Order keys as the consumer documents them, then alphabetically. Reorder keys only in a file that you also change for another reason.
+- Use the `.yml` extension. Keep a file name that a tool requires, such as `compose.yaml` or `pnpm-workspace.yaml`.

package/configurations/general/format/manifest.toml

@@ -2,151 +2,98 @@ allowed_words = ["Prettier"]
 
 [configuration]
 always_selected = true
+description = "A single `[format]` block for every formatter, so Prettier, shfmt, Ruff, and markdownlint use the same indentation."
 title = "Format"
-description = "One [format] block every formatter reads, so indentation cannot disagree between Prettier, shfmt, Ruff, and markdownlint."
 
 [files]
 extensions = [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".jsx", ".json", ".jsonc", ".json5", ".md", ".mdx", ".css", ".scss", ".html", ".yml", ".yaml", ".vue", ".graphql"]
 prettier_plugins = true
 
 [[tool]]
-name = "prettier"
 crash_pattern = "\\[error\\] (?:No parser|Cannot find|Invalid)"
-version = "3.8.1"
+name = "prettier"
 npm = "prettier"
-[[tool.replace]]
-file = ".prettierrc"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.json"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.yml"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.yaml"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.json5"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.js"
-shared = false
-
-[[tool.replace]]
-file = "prettier.config.js"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.ts"
-shared = false
-
-[[tool.replace]]
-file = "prettier.config.ts"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.mjs"
-shared = false
-
-[[tool.replace]]
-file = "prettier.config.mjs"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.mts"
-shared = false
-
-[[tool.replace]]
-file = "prettier.config.mts"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.cjs"
-shared = false
-
-[[tool.replace]]
-file = "prettier.config.cjs"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.cts"
-shared = false
-
-[[tool.replace]]
-file = "prettier.config.cts"
-shared = false
-
-[[tool.replace]]
-file = ".prettierrc.toml"
-shared = false
-
-[[tool.replace]]
-file = ".prettierignore"
-shared = false
+replace = [".prettierrc", ".prettierrc.json", ".prettierrc.yml", ".prettierrc.yaml", ".prettierrc.json5", ".prettierrc.js", "prettier.config.js", ".prettierrc.ts", "prettier.config.ts", ".prettierrc.mjs", "prettier.config.mjs", ".prettierrc.mts", "prettier.config.mts", ".prettierrc.cjs", "prettier.config.cjs", ".prettierrc.cts", "prettier.config.cts", ".prettierrc.toml", ".prettierignore"]
+version = "3.8.1"
 
-[[tool.replace]]
+[[tool.replace_key]]
 file = "package.json"
 key = "prettier"
-shared = true
 
-[[tool.replace]]
+[[tool.replace_key]]
 file = "package.yaml"
 key = "prettier"
-shared = true
 
 [[tool]]
-name = "editorconfig-checker"
-version = "3.4.0"
-env = { EC_VERSION = "v3.4.0" }
-npm = { name = "editorconfig-checker", version = "7.0.0" }
-mise = { name = "npm:editorconfig-checker", version = "7.0.0" }
 brew = "editorconfig-checker"
 github = { name = "editorconfig-checker/editorconfig-checker", version = "v3.4.0" }
-[[tool.replace]]
-file = ".editorconfig"
-shared = false
+mise = { name = "github:editorconfig-checker/editorconfig-checker", version = "3.4.0", options = { rename_exe = "editorconfig-checker" } }
+name = "editorconfig-checker"
+replace = [".editorconfig"]
+version = "3.4.0"
 
 [[tool_file]]
 target = ".editorconfig"
 tool = ["editorconfig-checker", "prettier"]
 
 [[tool_file]]
+pointer = { path = "prettier.config.mjs", when = { configuration = "javascript" }, body = '''
+import { readFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const toolFile = new URL({target_json}, import.meta.url);
+const options = JSON.parse(readFileSync(toolFile, 'utf8'));
+const folder = dirname(fileURLToPath(toolFile));
+const root = dirname(fileURLToPath(import.meta.url));
+const movePattern = (pattern) => {
+    const negated = pattern.startsWith('!');
+    const value = negated ? pattern.slice(1) : pattern;
+    if (!value.includes('/') || isAbsolute(value)) return pattern;
+    return (negated ? '!' : '') + relative(root, resolve(folder, value)).replaceAll('\\', '/');
+};
+const moveSelectors = (selectors) => Array.isArray(selectors) ? selectors.map(movePattern) : movePattern(selectors);
+if (options.plugins !== undefined) {
+    options.plugins = options.plugins.map((plugin) => plugin.startsWith('.') ? fileURLToPath(new URL(plugin, toolFile)) : plugin);
+}
+if (options.overrides !== undefined) {
+    options.overrides = options.overrides.map((entry) => ({
+        ...entry,
+        files: moveSelectors(entry.files),
+        ...(entry.excludeFiles === undefined ? {} : { excludeFiles: moveSelectors(entry.excludeFiles) }),
+    }));
+}
+export default options;
+''' }
 target = ".gspot/config/prettier.json"
 tool = "prettier"
-pointer = { path = "prettier.config.mjs", when = { configuration = "javascript" } }
 
 [[tool_file]]
 target = ".prettierignore"
 tool = "prettier"
 
 [[check]]
-name = "prettier"
-example = "A selected JavaScript file containing `const value={enabled:true};` differs from the configured Prettier output. Run the formatter and retain its spacing and wrapping changes before rerunning."
-level = "recommended"
-stage = "commit"
 command = ["prettier", "--check", "--config", "{tool_file:prettier}", "--ignore-path", ".prettierignore", "--log-level", "warn", "{files}"]
+example = "A JavaScript file with `const value={enabled:true};` differs from the Prettier output. Run `gspot check --fix` to format it."
 exit_codes = [1]
 fix = ["prettier", "--write", "--config", "{tool_file:prettier}", "--ignore-path", ".prettierignore", "--log-level", "warn", "{files}"]
-output = { format = "regex", pattern = "^\\[warn\\] (?<file>[^\\s].*[^\\s.])$", message = "This file is not formatted the way Prettier formats it." }
-summary = "Checks that every file Prettier formats is already formatted that way."
+help = "Run `gspot check --fix` to format every file, or `prettier --write` on one file."
+level = "recommended"
+name = "prettier"
+output = { format = "regex", pattern = "^\\[warn\\] (?<file>[^\\s].*[^\\s.])$", message = "Not formatted the way Prettier formats it." }
+stage = "commit"
+summary = "Checks each file Prettier handles for unformatted code."
 why = "Formatting by hand differs by editor; one formatter keeps diffs about the change and not the spacing."
-help = "Run gspot check --fix to format every file, or prettier --write on one file."
 
 [[check]]
-name = "editorconfig-checker"
-example = "A file containing CRLF line endings when `.editorconfig` requires LF reports a line-ending finding. Save it with LF endings and rerun. Use the exact configured indentation and final-newline settings as well."
-level = "recommended"
-stage = "commit"
 command = ["editorconfig-checker", "-no-color", "-disable-indentation", "{files}"]
-tool = "editorconfig-checker"
+example = "A file with CRLF line endings under an `.editorconfig` that requires LF reports a finding. Save it with LF endings."
 files = { paths = ["**"] }
-output = { format = "grouped", file_pattern = "^(?<file>.+):$", pattern = "^\\s+(?:(?<line>\\d+)(?:-\\d+)?: )?(?<message>\\S.*)$" }
-summary = "Checks line endings, final newlines and trailing whitespace in every file against .editorconfig."
-why = "These rules cover the files no formatter touches, so a stray tab or missing newline never lands in a diff. Indentation is the formatters' job and is not checked here."
 help = "Fix the line the checker names; most editors apply .editorconfig on save."
+level = "recommended"
+name = "editorconfig-checker"
+output = { format = "grouped", file_pattern = "^(?<file>.+):$", pattern = "^\\s+(?:(?<line>\\d+)(?:-\\d+)?: )?(?<message>\\S.*)$" }
+stage = "commit"
+summary = "Checks line endings, final newlines, and trailing whitespace in every file against .editorconfig."
+tool = "editorconfig-checker"
+why = "These rules cover the files no formatter touches, so a stray tab or missing newline never lands in a diff. The formatters handle indentation."

package/configurations/general/gspot/manifest.toml

@@ -1,65 +1,45 @@
 allowed_words = ["gspot"]
+
 [configuration]
-title = "gspot"
 always_selected = true
-description = "Checks gspot.toml and generated files, checks suppression reasons with gspot/suppressions, and requires Node.js as a system tool."
+description = "Checks gspot.toml, generated files, and suppression reasons, and requires Node.js as a system tool."
+title = "gspot"
 
 [[tool]]
-name = "node"
+brew = "node@24"
 install_hint = "Install Node.js 24.2.0 or newer. On macOS, run brew install node@24. On Windows, run winget install OpenJS.NodeJS.LTS."
 min_version = "24.2.0"
-version_command = ["--version"]
+name = "node"
 system = true
-brew = "node@24"
+version_command = ["--version"]
 winget = "OpenJS.NodeJS.LTS"
 
 [[check]]
-name = "settings-format"
-example = "A hand-edited gspot.toml with separated tables reports a layout finding. Run gspot check --fix --only gspot/settings-format to regroup its tables and retain their comments."
+example = "An edit by hand to a tool file under `.gspot/config/` reports drift. Move the change into gspot.toml, then run `gspot apply`."
+help = "Change gspot.toml, then run `gspot apply`. After a merge, run `gspot apply`, followed by `gspot install`."
 level = "recommended"
-stage = "commit"
-files = { paths = ["gspot.toml"] }
-summary = "Keeps gspot.toml formatted."
-why = "One settings layout keeps related settings and their reasons together."
-help = "Run gspot check --fix --only gspot/settings-format."
-
-[[check]]
 name = "generated-files"
-example = "A file under `.gspot/config/` edited by hand differs from what gspot writes from gspot.toml and reports drift. Change the settings in gspot.toml and run gspot apply, or move the edited file aside so apply writes it again."
-level = "recommended"
-stage = "commit"
 runs = "once"
-summary = "Compares every generated file with what gspot writes from the settings: a changed, missing, or stray file, or one with merge conflict markers, is a finding."
-why = "A generated file that no longer matches the settings runs a tool with settings nobody chose."
-help = "Change the settings in gspot.toml, then run gspot apply. After a merge, run gspot apply and then gspot install."
+stage = "commit"
+summary = "Compares generated files with the settings and reports changed, missing, and stray ones, and any with merge conflict markers."
+why = "A generated file that drifts from gspot.toml runs a tool with settings nobody chose."
 
 [[check]]
-name = "unused-entries"
-example = "An `[[ignore]]` entry for `bash/shellcheck` with `paths = [\"nowhere/**\"]` reports `unmatched-pattern` when that path matches no selected file. Remove the obsolete entry or correct its path to the actual exception, preserving its reason."
+example = "An `[[ignore]]` record with `paths = [\"nowhere/**\"]` that matches no file reports `unmatched-pattern`. Remove the record, or correct its path and keep the reason."
+help = "Remove the record or correct its path."
 level = "recommended"
-stage = "commit"
+name = "unmatched-patterns"
 runs = "once"
+stage = "commit"
 summary = "Checks settings path patterns against tracked files."
 why = "An ignore or declaration that matches nothing misleads the next reader."
-help = "Remove the entry or correct its path."
 
 [[check]]
-name = "settings"
-example = "An unknown setting or a loosened limit without a reason reports its gspot.toml key path. Correct the declaration or record the required reason."
+example = "An `eslint-disable-next-line` comment without a reason reports a finding. Fix the code and remove the comment, or append `-- reason: ...` that explains the exception."
+help = "Fix the finding and remove the suppression, or add a reason in the syntax of the tool. Never suppress a size or complexity limit: split the code by its steps, or ask the user to raise it in gspot.toml."
 level = "recommended"
-stage = "commit"
-runs = "once"
-files = { paths = ["gspot.toml"] }
-summary = "Checks the captured gspot.toml declarations for invalid settings and missing reasons."
-why = "A setting no check reads, or an unexplained loosening, can leave repository settings unenforced."
-help = "Fix the gspot.toml key the finding names, and give each loosened value a reason."
-
-[[check]]
 name = "suppressions"
-example = "An `eslint-disable-next-line` comment without a reason reports an unexplained suppression. Fix the underlying finding and remove the suppression, or append a specific `-- reason: ...` explanation of the required exception."
-level = "recommended"
-stage = "commit"
 runs = "once"
-summary = "Checks suppression reasons; Semgrep and Vale directives are refused outright."
+stage = "commit"
+summary = "Reports suppressions with no reason, any that lift a size or complexity limit, and Semgrep or Vale directives."
 why = "A suppression with no reason hides a finding nobody reviewed."
-help = "Use the tool's suppression syntax to write a meaningful reason, or fix the finding and remove the suppression."

package/configurations/general/gspot/rules/GENERATED.md

@@ -1,10 +1,20 @@
 # Generated Code
 
-- Never edit a generated file by hand. Change the source or the generator and regenerate
-  through its generation command.
+Read this rule when you change a generated file, or the code that writes one.
+
+- Never edit a generated file by hand. Change the source or the generator, and rerun its
+  command.
 - Mark generated paths in `.gitattributes` with `linguist-generated`; for example,
-  `output/** linguist-generated`. Where the format allows comments, add a header that names the
-  generation command. A folder named `generated/` does not make its files generated.
+  `output/** linguist-generated`. A folder named `generated/` does not make its files generated.
 - A generated file equals a fresh run of its command. A difference shows a defect in the change.
 - Do not commit build output (`dist/`, `coverage/`, compiled assets) unless the deployment reads
   it from the repository, and then declare it.
+
+## Readable output
+
+- Where the format allows comments, start the file with a header. Name the generator and the command that writes
+  it. Add one line that states the file's purpose.
+- Group the items of a generated list, such as an ignore file, under a comment that states their purpose, one
+  section per source. Write each item once.
+- Write one item per line, in a stable order. Use the formatter's layout.
+- Keep code that a program runs in a source file that the checks read, not in a string inside the generator.