@gspothq/cli 0.1.1 → 0.2.0

package/configurations/general/licenses/manifest.toml

@@ -1,33 +1,31 @@
 [configuration]
+description = "Checks the license of each installed dependency against the allowed list. An allowed-package record with a reason accepts one package."
 title = "Licenses"
-description = "Every installed dependency reports a license from the allowed list, or has an allowed-package record whose reason names its license."
 
 [files]
 filenames = ["package.json", "pyproject.toml"]
 
 [[tool]]
+mise = "npm:license-checker-rseidelsohn"
 name = "license-checker-rseidelsohn"
-version = "5.0.1"
 npm = "license-checker-rseidelsohn"
+replace = [".license-checker.json"]
+version = "5.0.1"
 version_exit_code = 1
-mise = "npm:license-checker-rseidelsohn"
-[[tool.replace]]
-file = ".license-checker.json"
-shared = false
 
 [[tool]]
+mise = "pipx:pip-licenses"
 name = "pip-licenses"
-version = "5.5.5"
 pypi = "pip-licenses"
-mise = "pipx:pip-licenses"
+version = "5.5.5"
 
 [[check]]
-name = "allowed"
-example = "An installed package whose reported license is outside licenses.allowed reports a finding for that exact package version. Replace it with an acceptable dependency, or write a [[licenses.allowed_package]] record with name, version, and a reason naming the license. A record for another version does not apply."
+example = "A dependency with a license outside `licenses.allowed` reports a finding for that version. Replace it, or write a `[[licenses.allowed_package]]` record with its name, version, and the license in a reason."
+files = { filenames = ["package.json", "pyproject.toml"] }
+help = "Replace the package, or write a [[licenses.allowed_package]] record by hand with its name, exact version, and a reason naming the license."
 level = "recommended"
-stage = "push"
+name = "allowed"
 runs = "once"
-files = { filenames = ["package.json", "pyproject.toml"] }
-summary = "Compares the license every installed npm or Python package reports with the allowed list and the allowed-package records."
+stage = "push"
+summary = "Compares the license of each installed npm or Python package with the allowed list and package records."
 why = "A license the project cannot accept arrives silently with a transitive dependency."
-help = "Replace the package, or write a [[licenses.allowed_package]] record by hand with its name, exact version, and a reason naming the license."

package/configurations/general/naming/defaults.json

@@ -104,7 +104,7 @@
     },
     "reserved": {
         "config": [
-            "directories",
+            "folders",
             "packages",
             "files",
             "modules",
@@ -123,7 +123,7 @@
                 "files": {
                     "cases": ["kebab"]
                 },
-                "directories": {
+                "folders": {
                     "cases": ["kebab"]
                 },
                 "types": {
@@ -170,7 +170,7 @@
                 "files": {
                     "cases": ["kebab"]
                 },
-                "directories": {
+                "folders": {
                     "cases": ["kebab"]
                 },
                 "types": {
@@ -208,7 +208,7 @@
                 "files": {
                     "cases": ["snake"]
                 },
-                "directories": {
+                "folders": {
                     "cases": ["snake"]
                 },
                 "modules": {
@@ -240,7 +240,7 @@
                 "files": {
                     "cases": ["pascal", "pascal-extension"]
                 },
-                "directories": {
+                "folders": {
                     "cases": ["pascal"]
                 },
                 "functions": {
@@ -257,7 +257,7 @@
                 "files": {
                     "cases": ["kebab", "snake"]
                 },
-                "directories": {
+                "folders": {
                     "cases": ["kebab", "snake"]
                 },
                 "functions": {
@@ -277,7 +277,7 @@
                 "files": {
                     "cases": ["timestamp-snake", "snake"]
                 },
-                "directories": {
+                "folders": {
                     "cases": ["snake"]
                 },
                 "functions": {
@@ -363,7 +363,7 @@
         },
         {
             "paths": ["**"],
-            "categories": ["directories"],
+            "categories": ["folders"],
             "reason": "Tools name these directories.",
             "allowed_names": ["node_modules", "__pycache__", "__tests__", "__mocks__"]
         },
@@ -389,7 +389,7 @@
         },
         {
             "paths": ["**/e2e/**"],
-            "categories": ["directories", "files"],
+            "categories": ["folders", "files"],
             "allow_digits": true
         },
         {
@@ -407,17 +407,18 @@
         {
             "open": "(",
             "close": ")",
-            "category": "directories"
+            "category": "folders"
         },
         {
             "open": "@",
             "close": "",
-            "category": "directories"
+            "category": "folders"
         },
         {
             "open": "_",
             "close": "",
-            "category": "directories"
+            "category": "folders"
         }
-    ]
+    ],
+    "allowed_phrases": ["package manager"]
 }

package/configurations/general/naming/manifest.toml

@@ -1,35 +1,35 @@
 [configuration]
-title = "Naming"
 always_selected = true
-description = "The naming engine: banned terms, case rules, length and word ceilings over every identifier, file, and folder."
+description = "Checks every identifier, file, and folder for banned words, case, length, and word count."
+title = "Naming"
 
 [files]
 languages = true
 
 [[check]]
-name = "identifiers"
-example = "`export const userHelper = 1;` reports the banned term `helper`. Rename it after what it holds, such as `userCount`."
+example = "`export const userHelper = 1;` reports the banned word `helper`. Rename it after what it holds, such as `userCount`."
+help = "Rename the thing after what it holds or does. To keep a name, list it exactly under `allowed_names` in a `[[naming.override]]` record with a reason, or change a limit with `gspot set naming.<language>.max_words`."
 level = "all"
+name = "identifiers"
 stage = "commit"
-summary = "Checks every identifier against the naming settings: banned terms, case, length, and word count."
-why = "Names such as `enhancedHandler`, `ensureConfigIfNeeded`, and `utils` do not explain the value or behavior a reader needs to understand."
-help = "Rename after what the thing is or does. Write the exact names under allowed_names in a [[naming.override]] record with a reason, or adjust a ceiling with gspot set naming.`<language>`.max_words."
+summary = "Checks every identifier against the naming settings: banned words, case, length, and word count."
+why = "Names such as `enhancedHandler`, `ensureConfigIfNeeded`, and `utils` hide what the value holds or the code does."
 
 [[check]]
-name = "paths"
 example = "`utils/format.js` reports `utils`. Move it into the folder of the feature it serves, such as `invoices/format.js`."
+help = "Rename the file or folder, or add a path rule under [[naming.override]] with a reason."
 level = "all"
+name = "paths"
 stage = "commit"
-summary = "Checks every file stem and folder name against the language's case rules and the banned terms."
-why = "A file named `enhanced-utils.ts` is a home for code nobody placed; the case rule keeps imports predictable."
-help = "Rename the file or folder, or add a path rule under [[naming.override]] with a reason."
+summary = "Checks every file stem and folder name against the case rules of its language and the banned words."
+why = "A file such as `enhanced-utils.ts` collects code with no clear place. One case rule keeps imports predictable."
 
 [[check]]
-name = "settings"
-example = "A naming allowance for an identifier that no selected source contains reports an unmatched settings entry. Remove the obsolete allowance or correct it to the exact required identifier and scope."
-level = "recommended"
-stage = "commit"
+example = "An allowed name that no source file contains reports an unmatched record. Remove the name, or correct it to the exact identifier and scope."
+help = "Remove the record that matches nothing, or fix its name or path."
+level = "all"
+name = "allowed-names"
 runs = "once"
-summary = "Reports allowed names that no selected source uses."
+stage = "commit"
+summary = "Reports allowed names that no source file uses."
 why = "An allowed name that nothing uses hides an obsolete exception."
-help = "Remove the entry that matches nothing, or fix its name or path."

package/configurations/general/naming/rules/NAMING.md

@@ -1,19 +1,21 @@
 # Naming
 
+Read this rule when you name a file, folder, type, function, or variable.
+
 ## Casing across languages
 
 <!-- level: all -->
 
-Each language naming file states its own case table. These decisions hold across every language so
-the same concept reads the same way throughout the program.
+Each language rule states its own case table. These decisions hold across languages, so one
+concept reads alike throughout the program.
 
-| Concern               | Rule                                                                                                                                                                                                                                                                                                                                            |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Acronyms              | Follow the language: TypeScript, JavaScript treat them as words such as `parseHttpUrl`, `userId`; Swift keeps uppercase initialisms (`avatarURL`, `userID`, `apiClient` at the start of a name); Python, SQL, Bash lowercase them inside snake_case such as `http_url`, `user_id`. A platform name keeps its spelling such as `XMLHttpRequest`. |
-| Directories           | kebab-case for TypeScript, JavaScript, Bash, HTML, CSS, and static sites; snake_case for Python packages; PascalCase for Swift directories, which mirror type names.                                                                                                                                                                            |
-| On the wire           | Preserve existing external interfaces. For interfaces defined by the project, use camelCase JSON fields, kebab-case URL segments.                                                                                                                                                                                                               |
-| Environment variables | `UPPER_SNAKE_CASE`, named by the external interface. No application prefix is required; names defined by the platform are kept verbatim.                                                                                                                                                                                                        |
-| Constants             | Module-level constants bound to a literal or a frozen object are `UPPER_SNAKE_CASE` in TypeScript, JavaScript, Python, and Bash, and lowerCamelCase in Swift.                                                                                                                                                                                   |
+| Concern               | Rule                                                                                                                                                                                                                                                                                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Acronyms              | Follow the language. TypeScript and JavaScript treat them as words, such as `parseHttpUrl` and `userId`. Swift keeps uppercase initialisms (`avatarURL`, `userID`, and `apiClient` at the start of a name). Python, SQL, and Bash lowercase them inside snake_case, such as `http_url` and `user_id`. An external API name keeps its spelling, such as `XMLHttpRequest`. |
+| Folders               | kebab-case for TypeScript, JavaScript, Bash, HTML, CSS, and static sites; snake_case for Python packages; PascalCase for Swift folders, which mirror type names.                                                                                                                                                                                                         |
+| On the wire           | Preserve existing external interfaces. For project interfaces, use camelCase JSON fields and kebab-case URL segments. Log fields follow the logging rules.                                                                                                                                                                                                               |
+| Environment variables | `UPPER_SNAKE_CASE`, named by the external interface. Add no application prefix. Keep names that the platform defines verbatim.                                                                                                                                                                                                                                           |
+| Constants             | Module-level constants bound to a literal or a frozen object use `UPPER_SNAKE_CASE` in TypeScript, JavaScript, Python, and Bash, and lowerCamelCase in Swift.                                                                                                                                                                                                            |
 
 ## Authority
 
@@ -29,13 +31,19 @@ bad name in a string key, an alias, or a file name.
 A name lets a reader understand the concept, scope, role, and expected value without reading
 the implementation. Name by role, responsibility, and domain meaning, never by storage type,
 UI framework type, collection shape, or implementation accident. Use English unless an
-external identifier keeps another spelling. Prefer the shortest name that gives a clear meaning at the use
-site, and add a qualifier only when the bare name has more than one meaning there. Never invent private
+external identifier keeps another spelling. Prefer the shortest name that keeps its meaning at the use site. Add a
+qualifier only when the bare name has more than one meaning there. Never invent private
 shorthand or drop letters from a word.
 
-Do not repeat context the enclosing type, module, directory, or package already supplies, and
-do not encode every implementation detail. One concept keeps one word across a feature. Use singular names for single values, plural names for collections, and
-named by their contents. A role word carries meaning where a primitive or weak type does not.
+Do not repeat context the enclosing type, module, folder, or package already supplies, or
+encode every implementation detail.
+
+Give each concept one word across the repository, and each word one meaning. Before you give a word to a new
+concept, search the code for it. When the word already names another concept, choose a different one. Add the synonyms
+you reject to `naming.banned_words`, so the naming check reports them. Use singular names for single values and
+plural ones for collections. Name a collection by what it holds.
+
+A role word carries meaning where a primitive or weak type does not.
 
 | Avoid               | Prefer                        | Why                                 |
 | ------------------- | ----------------------------- | ----------------------------------- |
@@ -68,42 +76,56 @@ A suffix names the role of a type. Use each suffix for one meaning. Name a type
 | `Provider`   | Supplies a capability or value, especially when the source may vary. |
 | `Adapter`    | Bridges one interface or framework shape to another.                 |
 
-Use `Route`, `Callback`, `Observer`, and `Listener` only for the corresponding framework shape. The language file for the framework defines UI role words such as `View`, `ViewModel`, `ViewController`, and `Coordinator`. Never use `Manager`. Use `Service` only
-where the framework uses it, such as a NestJS provider. Preserve external names such as Apple's
-`FileManager`.
+Use `Route`, `Callback`, `Observer`, and `Listener` only for the framework shapes they name. The language file for the framework defines UI role words such as `View`, `ViewModel`, `ViewController`, and `Coordinator`. Never use `Manager`. Keep `Service`
+for framework roles, such as a NestJS provider. Preserve external names, such as `FileManager`
+from Apple.
 
 ## Functions and methods
 
 <!-- level: all -->
 
-A function name starts with the action and carries enough domain context to read at the call
-site without repeating the enclosing type or module. A generic verb such as `process`, `handle`, `run`, `execute`,
-`manage`, `perform` never stands where the name can state the action. `handle` exists only in a
-framework callback such as a React `handleSubmit` or a UIKit `@objc handleConfirmButtonTapped`.
-Never use `Handler` as a type suffix. A name that needs `and`, `or`, `with`, or an umbrella verb
-marks a function that combines too many concepts.
-
-A fixed verb vocabulary spares the reader a guess at which synonym a module chose:
-
-| Verb                 | Meaning                                                                         |
-| -------------------- | ------------------------------------------------------------------------------- |
-| `get`                | Retrieve an existing value from memory, cache, file, database, SDK, or API.     |
-| `set`                | Assign or replace current state with the supplied value.                        |
-| `insert`, `update`   | Add or change a row or item in persisted data.                                  |
-| `delete`             | Destroy a durable row, object, or domain value.                                 |
-| `add`, `remove`      | In-memory collection membership only.                                           |
-| `create`             | Make a new independent domain value before persistence.                         |
-| `make`, `build`      | Construct an object or dependency; construct a value from existing values.      |
-| `parse`, `decode`    | Raw input to structured data; encoded bytes or payloads to typed values.        |
-| `encode`             | Typed values to bytes or serialized payloads.                                   |
-| `validate`, `assert` | Report invalidity; stop execution on failure.                                   |
-| `refresh`, `prepare` | Replace presentation state from a source; set up local state before a workflow. |
-| `reset`              | Return to an initial state.                                                     |
-
-Each act keeps one verb across the codebase: once retrieval uses `get`, no module reads, finds,
-fetches, or loads instead. The noun and the return type carry multiplicity and optionality
-such as `getSession`, `getSessions`, and a qualifier appears only to tell apart two operations at one
-use site. Give a domain operation that combines create, read, update, and delete (CRUD) acts its precise domain verb.
+A function name starts with the action and carries enough domain context to read at the call site without
+repeating the enclosing type or module. A generic verb such as `process`, `handle`, `execute`, `manage`, `perform`,
+or `ensure` never stands where the name can state the action. `handle` exists only in a framework callback such as
+a React `handleSubmit` or a UIKit `@objc handleConfirmButtonTapped`. Never use `Handler` as a type suffix. A name
+that needs `and`, `or`, `with`, or an umbrella verb marks a function that combines too many concepts. A preposition
+cannot replace a verb: `toPosix`, `fromRow`, and `withTimeout` need one.
+
+Each act has one verb. Use the table verb for each act, never a synonym:
+
+| Verb                          | Act                                                                                                         |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `get`                         | Take a value already in memory: a variable, a map, a cache, or a parsed structure.                          |
+| `read`                        | Take data from outside memory: a file, Git, the environment, a child process, or the network.               |
+| `write`                       | Put data into a file or another store outside memory.                                                       |
+| `find`                        | Search for one item. The result can be absent.                                                              |
+| `list`                        | Return every item of a kind, such as the files, the scopes, or the checks.                                  |
+| `select`                      | Choose among known options.                                                                                 |
+| `detect`                      | Infer a fact from the files of the project.                                                                 |
+| `build`, `make`               | Construct a value from other values, such as a message, a plan, or the text of a file.                      |
+| `create`                      | Make a new independent value or resource, such as an unsaved domain value, a folder, or a sandbox.          |
+| `parse`, `decode`             | Raw text to structured data; encoded bytes or payloads to typed values.                                     |
+| `encode`, `serialize`         | Typed values to bytes; values to the text of a file format.                                                 |
+| `format`                      | A value to text that people read: terminal lines, Markdown, or a message.                                   |
+| `check`                       | Inspect files or values for a check, and return its findings.                                               |
+| `validate`                    | Return what makes one value invalid.                                                                        |
+| `assert`                      | Stop with an error on an invalid value.                                                                     |
+| `run`                         | Start a named program, command, or step, such as `runEslint` or `runInstallCommand`. Never a bare `run`.    |
+| `spawn`                       | Start a child process.                                                                                      |
+| `set`                         | Assign or replace current state with the supplied value.                                                    |
+| `add`, `remove`               | In-memory collection membership only.                                                                       |
+| `insert`, `update`, `delete`  | Add, change, or destroy a row or item in persisted data.                                                    |
+| `prepare`, `refresh`, `reset` | Set up local state before a workflow; replace presentation state from a source; return to an initial state. |
+| `is`, `has`, `can`            | Predicates only: `is` for state, `has` for presence, and `can` for capability.                              |
+
+Use `plan`, `install`, `apply`, and `generate` only for the program step of the same name, such as an `install`
+command. When no table verb fits, pick another plain one that names the act. Plain verbs include `count`, `compare`,
+`merge`, `split`, `sort`, `filter`, `group`, `match`, `replace`, `normalize`, `convert`, `extract`, `strip`, `copy`,
+`move`, `stop`, and `wait`. Never use `load`, `fetch`, or `resolve` for retrieval; pick `get`, `read`, or `find`.
+
+The noun and the return type carry multiplicity and optionality, such as `getSession` and `getSessions`. Add a
+qualifier only to tell two operations apart at one use site. Give an operation that combines create, read,
+update, and delete (CRUD) acts its precise domain verb.
 Preserve framework, SDK, generated, and external names exactly.
 
 | Avoid                    | Prefer                   | Meaning                        |
@@ -115,45 +137,43 @@ Preserve framework, SDK, generated, and external names exactly.
 | `mapUserRowToUserDomain` | `mapUser`                | The parameter type says row.   |
 
 Where external data enters, name the conversion for the operation and the concept, `decodeUserResponse`
-rather than `transform`. Shape suffixes such as `Row`, `DTO`, `Request`, and `Response` stay on
-the type that declares the shape and never travel onto domain entities, view models, or the
-functions that accept the shape.
+rather than `transform`. DTO means data transfer object. Shape suffixes such as `Row`, `DTO`, `Request`, and `Response` stay on the type that
+declares it. Never put those suffixes on domain entities, view models, or functions that accept the shape.
 
 ## Booleans and predicates
 
 <!-- level: all -->
 
 Name stored boolean columns and direct domain mappings as concise positive states without a
-prefix: `enabled`, `active`, `retryable`, `webSearchEnabled`. Predicates, computed
-predicates, and presentation-state assertions ask their question with `is` for state, `has`
-for presence, and `can` for capability. Name an action for what it does even when it
-returns a boolean such as `sendInvite`. Name a proposed answer or control parameter
-for its role such as `defaultCountry`; a boolean type does not make a function a
+prefix: `enabled`, `active`, `retryable`, and `webSearchEnabled`. Predicates, including computed
+ones, and presentation-state assertions start with `is`, `has`, or `can`. Name an action for what
+it does even when it returns a boolean, such as `sendInvite`. Name a proposed answer or control
+parameter for its role, such as `defaultCountry`; a boolean type does not make a function a
 predicate.
 
-Negative names such as `isNotReady`, `isEmailNotUsed` give way to the positive form that
+Replace negative names such as `isNotReady` and `isEmailNotUsed` with the positive form that
 matches the branch without double negation. A boolean never reads like a noun value. Preserve external boolean names exactly, including framework, SDK,
 protocol, wire, and generated relationship names.
 
-| Avoid                    | Prefer                 | Meaning                                        |
-| ------------------------ | ---------------------- | ---------------------------------------------- |
-| `SearchPolicy.isEnabled` | `SearchPolicy.enabled` | Stored policy state.                           |
-| `email`                  | `hasEmailAddress`      | Presence of an email address.                  |
-| `textFile`               | `isTextFile`           | Whether a file meets the text-file definition. |
-| `isEmailNotUsed`         | `isEmailUsed`          | Whether an email address is already used.      |
-| `ready`                  | `is_ready`             | A computed readiness predicate in Bash.        |
+| Avoid                    | Prefer                 | Meaning                                           |
+| ------------------------ | ---------------------- | ------------------------------------------------- |
+| `SearchPolicy.isEnabled` | `SearchPolicy.enabled` | Stored policy state.                              |
+| `email`                  | `hasEmailAddress`      | Presence of an email address.                     |
+| `textFile`               | `isTextFile`           | Whether a file meets the text-file definition.    |
+| `isEmailNotUsed`         | `isEmailUsed`          | Whether an account already uses an email address. |
+| `ready`                  | `is_ready`             | A computed readiness predicate in Bash.           |
 
 ## Files and directories
 
 <!-- level: all -->
 
-Name files and directories for the behavior or entity they contain, not for reuse.
+Name files and folders for the behavior or entity they contain, not for reuse.
 
-- Name a file with one primary type after that type where the language does so. Name a module
+- Name a file that holds one primary type after it, where the language does so. Name a module
   after the capability it implements. Prefer feature folders to top-level type buckets.
 - Move code to a shared place only for a repeated concept with one module that implements it, never for a caller
   that does not exist yet.
-- A file name avoids the banned terms identifiers avoid. Only a generated artifact may carry a
+- File names and identifiers avoid the same banned words. Only a generated artifact may carry a
   timestamp in its name.
 
 | Avoid              | Prefer                        | Meaning                |
@@ -170,9 +190,9 @@ Name files and directories for the behavior or entity they contain, not for reus
 External systems use names that do not match the domain language. Keep those names in code that reads or writes external data.
 
 DTOs, SQL rows, generated types, wire payloads, and validation schemas keep the external field names.
-Renaming one changes the public interface. Translate them into domain names, through explicitly
-named mappings, before the values reach domain or presentation code; provider, database, and HTTP
-mechanics stay out of domain names.
+Renaming one changes the public interface. Translate them into domain names through explicit
+mappings before the values reach domain or presentation code. Keep provider, database, and HTTP
+mechanics out of domain names.
 
 A wire shape such as `MessageAttachmentDTO` keeps `storage_object_path`. The validated
 `MessageAttachment` uses `attachmentPath`, and the module that implements the storage protocol