@gspothq/cli 0.1.1 → 0.2.0

package/configurations/infrastructure/github-actions/tool-files/zizmor.yml

@@ -0,0 +1,5 @@
+rules:
+    unpinned-uses:
+        config:
+            policies:
+                '*': hash-pin

package/configurations/infrastructure/nginx/manifest.toml

@@ -1,17 +1,18 @@
-allowed_words = ["nginx"]
+allowed_words = ["nginx", "NGINX"]
+
 [configuration]
+description = "nginx files: gixy finds security mistakes, and the server parser checks the rest in a container."
 title = "nginx"
-description = "nginx configuration: gixy for the security mistakes, and the server's own parser in a container for the rest."
 
 [files]
 paths = ["**/nginx.conf", "**/nginx/**/*.conf"]
 
 [[tool]]
+builds = ["macos", "linux"]
+mise = "pipx:gixy-ng"
 name = "gixy"
-version = "0.2.53"
 pypi = "gixy-ng"
-mise = "pipx:gixy-ng"
-builds = ["macos", "linux"]
+version = "0.2.53"
 version_pattern = "(\\d+\\.\\d+\\.\\d+)"
 
 [[tool]]
@@ -24,28 +25,27 @@ system = true
 [[tool_file]]
 target = ".gspot/config/gixy.cfg"
 tool = "gixy"
-rule_keys = ["skips"]
 
 [[check]]
-name = "gixy"
-example = "A location matching `/proxy/(.*)` with `proxy_pass http://$1` lets the request choose the destination and reports `ssrf`. Remove the request-controlled proxy destination and use the intended fixed upstream, or remove the proxy operation when the endpoint only needs to return a response."
-level = "recommended"
-stage = "commit"
 command = ["gixy", "--config", "{tool_file:gixy}", "--format", "json", "{file}"]
+example = "A location for `/proxy/(.*)` with `proxy_pass http://$1` sends requests to any host and reports `ssrf`. Point `proxy_pass` at a fixed upstream instead."
+help = "Change the block the way the rule page says. Turn one rule off with `gspot ignore nginx/gixy --rule <name> --reason \"<why>\"`."
+level = "recommended"
+name = "gixy"
 output = { format = "json", fields = { file = "path", line = "line", rule = "plugin", message = "summary" } }
-summary = "Reads every nginx file for the mistakes that open a server: request forgery, path traversal through alias, header injection, a disclosed version."
+stage = "commit"
+summary = "Checks every nginx file for mistakes that expose a server: request forgery, path traversal through alias, header injection, and a disclosed version."
 why = "These mistakes parse, serve traffic, and look like any other location block until somebody uses them."
-help = "Change the block the way the rule's page says. Turn one rule off with gspot ignore nginx/gixy --rule `<name>` --reason \"`<why>`\"."
 
 [[check]]
-name = "config-test"
-example = "The line `invalid_directive on;` fails the native configuration test with `nginx -t`. Remove the unknown directive or replace it with the intended supported directive, such as `listen 443 ssl;` in the configured TLS server. Rerun with the configured deployment image available."
+example = "The line `invalid_directive on;` fails `nginx -t`. Remove it, or replace it with a known directive such as `listen 443 ssl;`."
+files = { filenames = ["nginx.conf"] }
+help = "Fix the line nginx names. Set `tools.nginx.image` to the one your deployment runs."
 level = "recommended"
-stage = "push"
-runs = "scope"
+name = "config-test"
 needs = ["docker"]
+runs = "scope"
+stage = "push"
+summary = "Runs `nginx -t` on each main file inside the image, with a throwaway certificate and resolved upstream names. Records every file that nginx parsed."
 tool = "docker"
-files = { filenames = ["nginx.conf"] }
-summary = "Validates each main configuration inside the nginx image and records the files nginx parsed. It mounts a throwaway certificate and resolves upstream names."
-why = "Only nginx knows whether nginx accepts the file, and the other place to learn it is the restart in production."
-help = "Read the line nginx names. Set tools.nginx.image to the image the deployment runs."
+why = "Only nginx itself can confirm that a file parses; otherwise the first test comes at the restart in production."

package/configurations/infrastructure/nginx/rules/NGINX.md

@@ -1,4 +1,6 @@
-# `nginx`
+# NGINX
+
+Read this rule when you change NGINX configuration.
 
 ## Edge responsibilities
 
@@ -24,7 +26,7 @@
 - Use immutable caching only for content-addressed assets. Give mutable resources a cache
   lifetime and revalidation policy consistent with their update process.
 - Keep configuration in the repository, lint it before commit, and reload it through the
-  deployment flow, never edited on the host.
+  deployment flow; never edit it on the host.
 
 ## Images
 
@@ -34,5 +36,4 @@
 
 See [nginx TLS configuration](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_stapling)
 for stapling requirements. Certificate authorities can
-[retire OCSP](https://letsencrypt.org/2024/12/05/ending-ocsp); verify issuer support
-before enabling stapling.
+[retire OCSP](https://letsencrypt.org/2024/12/05/ending-ocsp).

package/configurations/infrastructure/openapi/manifest.toml

@@ -1,15 +1,15 @@
 [configuration]
+description = "A committed OpenAPI document: Spectral lints it, and its generator command leaves it unchanged."
 title = "OpenAPI"
-description = "A committed OpenAPI document: Spectral lints it, and the command that writes it must not change it."
 
 [detect]
 filenames = ["openapi.yaml", "openapi.yml", "openapi.json", "swagger.json", "swagger.yaml"]
 
 [[tool]]
+mise = "npm:@stoplight/spectral-cli"
 name = "spectral"
-version = "6.15.0"
 npm = "@stoplight/spectral-cli"
-mise = "npm:@stoplight/spectral-cli"
+version = "6.15.0"
 
 # Spectral's Ajv plugins must use the same ajv package as Spectral, so the tool project installs one shared ajv.
 
@@ -21,30 +21,30 @@ target = ".gspot/config/spectral.yaml"
 tool = "spectral"
 
 [[check]]
-name = "spectral"
-example = "An OpenAPI document whose operation references an undefined schema reports a validation finding. Define the schema or correct the reference in the source that produces the document, then regenerate it."
+command = ["spectral", "lint", "--ruleset", "{tool_file:spectral}", "--format", "text", "{setting:openapi.document}"]
+cwd = "root"
+example = "An operation that references an undefined schema reports a finding. Define the schema or fix the reference in the source, then generate the document again."
+files = { extensions = [".yaml", ".yml", ".json"] }
+help = "Change the document the way the rule says, or the code that writes it."
 level = "recommended"
-stage = "commit"
+name = "spectral"
+output = { format = "regex", pattern = '^(?<file>.+):(?<line>\d+):(?<column>\d+) (?:error|warning) (?<rule>\S+) "(?<message>.*)"$' }
 runs = "scope"
+stage = "commit"
+summary = "Lints the file in `openapi.document` with the Spectral OpenAPI rules."
 tool = "spectral"
-cwd = "root"
-command = ["spectral", "lint", "--ruleset", "{tool_file:spectral}", "--format", "text", "{setting:openapi.document}"]
 when = { setting = "openapi.document" }
-output = { format = "regex", pattern = '^(?<file>.+):(?<line>\d+):(?<column>\d+) (?:error|warning) (?<rule>\S+) "(?<message>.*)"$' }
-files = { extensions = [".yaml", ".yml", ".json"] }
-summary = "Lints the OpenAPI document named in openapi.document with the Spectral OpenAPI rules."
-why = "Clients are written from this document, so an operation with no id or an undefined response becomes somebody's broken client."
-help = "Change the document the way the rule says, or the code that writes it."
+why = "Teams generate clients from this document, so an operation with no ID or an undefined response breaks them."
 
 [[check]]
-name = "stale-document"
 command = ["{setting:openapi.generate_command}"]
-when = { setting = "openapi.generate_command" }
-generated_paths = [{ path = "{setting:openapi.document}" }]
-example = "A committed OpenAPI document that differs from the configured generator output reports drift. Run the declared generator, inspect the changed document, and retain the corrected output before rerunning."
+example = "A committed document that differs from the generator output reports drift. Run the generator, review the change, and commit it."
+generator_outputs = [{ path = "{setting:openapi.document}" }]
+help = "Run the command and commit the document it writes."
 level = "recommended"
-stage = "push"
+name = "stale-document"
 runs = "scope"
-summary = "Runs the command in openapi.generate_command and fails when it changes the document."
+stage = "push"
+summary = "Runs `openapi.generate_command` and fails when the document changes."
+when = { setting = "openapi.generate_command" }
 why = "A committed document that lags the routes describes a service that does not exist."
-help = "Run the command and commit the document it writes."

package/configurations/infrastructure/openapi/rules/OPENAPI.md

@@ -1,5 +1,7 @@
 # OpenAPI
 
+Read this rule when you change an OpenAPI document or its contract tests.
+
 ## Public contracts
 
 When the project publishes OpenAPI, its document describes the runtime API.
@@ -35,5 +37,5 @@ When you write contract tests:
 - Test the public response. Assert its status and content type.
 - Keep generated schemas and their inputs synchronized through the existing generator.
 
-An assertion that checks only selected response fields does not prove that the whole response
+An assertion that checks only some fields does not prove that the whole response
 satisfies its schema. Use the project's schema validator for that claim.

package/configurations/infrastructure/xcode/manifest.toml

@@ -1,8 +1,9 @@
 allowed_words = ["Xcode"]
+
 [configuration]
-title = "Xcode"
+description = "An Xcode project: property lists that parse, build settings files, and complete string catalogs. Asset catalogs hold their images, sources belong to a target, and entitlements stay on a list."
 suggests = ["swift"]
-description = "An Xcode project: property lists that parse, build settings files, and complete string catalogs. Asset catalogs hold their images, test targets sit in a plan, sources belong to a target, and entitlements stay on a list."
+title = "Xcode"
 
 [detect]
 paths = ["**/*.xcodeproj/project.pbxproj"]
@@ -13,119 +14,98 @@ extensions = [".plist", ".entitlements", ".xcconfig", ".xcstrings", ".storyboard
 paths = ["**/project.pbxproj", "**/*.xcscheme", "**/*.xctestplan", "**/*.xcassets/**/Contents.json"]
 
 [[tool]]
-name = "plutil"
-install_hint = "install Xcode from the App Store"
-system = true
 builds = ["macos"]
 crash_pattern = "couldn['’]t be opened"
+install_hint = "install Xcode from the App Store"
+name = "plutil"
+system = true
 
 [[check]]
-name = "plutil"
-example = "A plist containing an unclosed dictionary fails native validation. Close the dictionary and plist elements, then rerun with plutil available on a declared platform."
-level = "recommended"
-stage = "commit"
 command = ["plutil", "-lint", "{files}"]
+example = "A plist with an unclosed dictionary fails plutil. Close the dictionary element."
 files = { extensions = [".plist", ".entitlements"] }
+help = "Fix the element plutil names."
+level = "recommended"
+name = "plutil"
 output = { format = "regex", pattern = "^(?<file>[^:]+): (?<message>(?!OK$).+)$" }
+stage = "commit"
 summary = "Parses every property list and entitlements file with plutil."
 why = "A broken plist fails the build or, worse, ships an app whose settings silently fell back to defaults."
-help = "Fix the element plutil names."
 
 [[check]]
-name = "xcconfig"
 example = "A non-comment line `PRODUCT_NAME App` in an `.xcconfig` file lacks an assignment operator. Change it to `PRODUCT_NAME = App`."
-level = "recommended"
-stage = "commit"
-runs = "scope"
 files = { extensions = [".xcconfig"] }
-summary = "Checks that every line of a build settings file is a setting, an include, or a comment."
-why = "Xcode ignores a line it cannot read, so a typo turns a setting off without a word."
 help = "Write the line as a name, an equals sign, and a value."
+level = "recommended"
+name = "xcconfig"
+runs = "scope"
+stage = "commit"
+summary = "Checks that each line of an `.xcconfig` file holds a setting, an include, or a comment."
+why = "Xcode silently skips a line it cannot parse, so a typo turns a setting off."
 
 [[check]]
-name = "xcstrings"
-example = "A string catalog entry with one translated locale and an absent required locale reports the missing translation. Add that locale and its translation, or explicitly mark the string as not translated when that is the intended catalog state."
+example = "A catalog string that lacks a required locale reports a finding. Add the translation, or mark the string as not translated."
+files = { extensions = [".xcstrings"] }
+help = "Add the translation, or mark the string as not translated in the catalog."
 level = "recommended"
-stage = "commit"
+name = "xcstrings"
 runs = "scope"
-files = { extensions = [".xcstrings"] }
-summary = "Checks that every string catalog parses, and that every string has a translation for every locale the catalog uses."
+stage = "commit"
+summary = "Checks that each string catalog parses and translates every string into all its locales."
 why = "A string with no translation shows its source language in the middle of a translated screen."
-help = "Add the translation, or mark the string as not translated in the catalog."
 
 [[check]]
-name = "assets"
-example = "A `Contents.json` image entry naming `icon.png` reports a missing asset when that file does not exist. Add the intended image beside the manifest or remove the obsolete entry."
+example = "A `Contents.json` that names a missing `icon.png` reports a finding. Add the image beside it, or remove the reference."
+files = { paths = ["**/*.xcassets/**"], extensions = [".swift"] }
+help = "Add the image or delete the asset."
 level = "recommended"
-stage = "commit"
+name = "assets"
 runs = "scope"
-files = { paths = ["**/*.xcassets/**"], extensions = [".swift"] }
-summary = "Checks that every asset Contents.json parses and that every image set holds the images it names."
+stage = "commit"
+summary = "Checks that each asset `Contents.json` parses, and that its image set holds each file it names."
 why = "An image set with no image draws nothing at run time."
-help = "Add the image or delete the asset."
 
 [[check]]
-name = "unused-assets"
-example = "An asset set named only in an Xcode build setting counts as used. An asset that no source or build setting names reports an unused-asset finding."
-level = "all"
-stage = "commit"
-runs = "scope"
+example = "An asset set that no source file or build setting names reports `unused-asset`. Delete it, or reference it where the app loads it."
 files = { paths = ["**/*.xcassets/**"], extensions = [".swift", ".storyboard", ".xib", ".plist", ".pbxproj", ".xcconfig"] }
-summary = "At level all, finds asset sets that no source or Xcode build setting names."
-why = "An asset nobody names ships in the app for nothing."
-help = "Delete the asset or name it where it is used. For an accepted asset selected at runtime, run gspot ignore xcode/unused-assets --rule unused-asset --paths `<glob>` --reason \"`<why>`\"."
-
-[[check]]
-name = "test-plans"
-example = "A test target absent from the test plan used by its scheme reports missing coverage by the plan. Add that target to the plan and point the scheme at the plan."
+help = "Delete the asset, or name it in the code that loads it. For an asset that the app picks at run time, run `gspot ignore xcode/unused-assets --rule unused-asset --paths <glob> --reason \"<why>\"`."
 level = "all"
-stage = "commit"
+name = "unused-assets"
 runs = "scope"
-summary = "Checks that every shared scheme that runs tests names a test plan, and that every test target is in a plan."
-why = "A test target outside every plan never runs in CI, and its tests rot while they look present."
-help = "Add the target to a test plan, and point the scheme at the plan."
+stage = "commit"
+summary = "Finds asset sets that no source or Xcode build setting names, at level all."
+why = "An asset nobody names ships in the app for nothing."
 
 [[check]]
-name = "files-without-target"
-example = "A Swift source file under the project that belongs to no target reports an orphan source. Add the file to its intended target or delete the unused source. Remove project references to files that no longer exist."
+example = "A Swift file in no target reports a finding. Add the file to a target, or delete it."
+files = { extensions = [".swift"], paths = ["**/project.pbxproj"] }
+help = "Add the file to a target, or delete it."
 level = "recommended"
-stage = "commit"
+name = "files-without-target"
 runs = "scope"
-files = { extensions = [".swift"], paths = ["**/project.pbxproj"] }
-summary = "Compares the Swift files in the tree with the files the project names: a file in no target, and a target file that is gone."
-why = "A Swift file in no target is never compiled, so it breaks without anyone seeing it."
-help = "Add the file to a target or delete it, and remove the reference to a file that is gone."
-
-[[check]]
-name = "symlinks"
-when = { git = true }
-example = "A source directory represented by a symlink reports a project symlink finding. Replace the link with the intended repository-owned directory and update project references."
-level = "all"
 stage = "commit"
-runs = "scope"
-summary = "Reports every tracked symlink beside or under an Xcode project, with where it points."
-why = "Xcode, git, and each lint tool follow a symlink their own way, so one file is checked twice or never."
-help = "Replace the symlink with the folder it points at, or ignore the path with a reason."
+summary = "Finds the Swift files in the tree that no target of the project names."
+why = "Xcode never compiles a Swift file that belongs to no target, so it breaks unnoticed."
 
 [[check]]
-name = "entitlements"
-example = "An entitlement enabled in an `.entitlements` file but absent from `xcode.allowed_entitlements` reports a settings finding. Remove an unnecessary entitlement, or explicitly allow the required entitlement in settings."
-level = "recommended"
-when = { setting = "xcode.allowed_entitlements" }
-stage = "commit"
-runs = "scope"
+example = "An `.entitlements` key missing from `xcode.allowed_entitlements` reports a finding. Remove it, or add it to that list."
 files = { extensions = [".entitlements"] }
-summary = "Checks that every entitlement is on xcode.allowed_entitlements, when the settings hold that list."
-why = "An entitlement is a capability the system grants the app, and a new one deserves a review of its own."
 help = "Remove the entitlement, or add it to xcode.allowed_entitlements."
+level = "recommended"
+name = "entitlements"
+runs = "scope"
+stage = "commit"
+summary = "Checks each entitlement against `xcode.allowed_entitlements`, when the settings hold that list."
+when = { setting = "xcode.allowed_entitlements" }
+why = "Each entitlement grants the app a system capability, so a new one needs its own review."
 
 [[check]]
-name = "app-transport-security"
-example = "An Info.plist enabling `NSAllowsArbitraryLoads` disables transport protection broadly and reports a finding. Remove that key. If one host requires an exception, declare only the host-specific exception."
+example = "An Info.plist with `NSAllowsArbitraryLoads` reports a finding. Remove the key, and add an exception only for a host that needs one."
+files = { extensions = [".plist"] }
+help = "Remove the key, and add an exception for the one host that needs it."
 level = "recommended"
-stage = "commit"
+name = "app-transport-security"
 runs = "scope"
-files = { extensions = [".plist"] }
+stage = "commit"
 summary = "Refuses a property list that allows arbitrary loads, which turns transport security off for every host."
-why = "With arbitrary loads the app speaks plain HTTP to anyone, and one forgotten debug setting ships it."
-help = "Remove the key, and add an exception for the one host that needs it."
+why = "Arbitrary loads let the app send plain HTTP to any host, and one forgotten debug setting ships that."

package/configurations/infrastructure/xcode/rules/XCODE.md

@@ -1,8 +1,10 @@
 # Xcode
 
+Read this rule when you change Xcode project settings, schemes, or build phases.
+
 ## Project settings
 
-- `SWIFT_STRICT_CONCURRENCY = complete`. Set the upcoming-feature flags the project adopts in
+- `SWIFT_STRICT_CONCURRENCY = complete`. Set adopted upcoming-feature flags in
   the project, not per file.
 - Share schemes needed by collaborators and CI. Keep personal scheme state out of the repository.
 - Set deployment targets deliberately for each supported product. Verify compatibility
@@ -22,7 +24,7 @@
 - Run-script phases declare their interpreter and pass the checks for that language.
 - Every run-script phase declares its input and output files so the build system can skip it.
 - No network access or code generation without declared outputs.
-- The linter and the formatter run before commit, not as build phases that fail the build twice.
+- The linter and the formatter run before commit, not as phases that fail the build twice.
 
 ## Project organization
 
@@ -30,5 +32,5 @@
 
 Keep shared build settings in the project or `.xcconfig` file. A target overrides only
 what differs. Preserve the project's chosen modules and packages; do not introduce
-a package only to enforce a directory layout. Keep substantial build-script logic in a
+one only to enforce a folder layout. Keep substantial build-script logic in a
 repository file its language tools can check.