@gspothq/cli 0.1.1 → 0.2.0

package/README.md

@@ -1,19 +1,66 @@
 # gspot
 
-gspot lints AI-generated code and writes rules for AI coding agents.
+gspot sets up linters, formatters, and security scanners for your repository and runs them before every commit.
+
+## What it does
+
+- **Picks the checks.** `gspot init` reads your files and turns on the checks for the languages and frameworks it
+  finds.
+- **Pins the tools.** Each check runs a known tool, such as ESLint, Ruff, or ShellCheck, at one version everywhere.
+- **Stops bad commits.** Git hooks check the staged files, and a CI job checks every push.
+- **Writes rules for your agent.** `AGENTS.md` and one rule file for each language say how to write code that
+  passes.
+
+## What it flags
+
+- Bugs and type errors
+- Security problems and leaked secrets
+- Vulnerable dependencies and licenses that you do not allow
+- Formatting, broken links, and spelling
+- Lint rules turned off without a reason
+- With `gspot set level all`: naming, structure, doc comments, duplication, and complexity
+
+A blocked commit lists each finding with its file, line, and rule:
+
+```text
+javascript/eslint  failed  2 findings
+  src/checkout.ts:4:8  @typescript-eslint/require-await  Async function 'pay' has no 'await' expression.
+  src/checkout.ts:8:13  no-empty  Empty block statement.
+```
 
 ## Install
 
-Commit your work, then run:
+You need Git and Node.js 24.15 or newer. With mise, gspot also installs program tools such as Gitleaks and
+ShellCheck.
 
-```sh
-npm install --save-dev --save-exact @gspothq/cli
-git add package.json package-lock.json
-git commit -m "build: Add gspot"
-npx gspot init
-npx gspot install
-npx gspot check
+| Package manager                | Install                                                                          | Run                  |
+| ------------------------------ | -------------------------------------------------------------------------------- | -------------------- |
+| npm                            | `npm install --save-dev --save-exact @gspothq/cli`                               | `npx gspot`          |
+| pnpm                           | `pnpm add --save-dev --save-exact @gspothq/cli`                                  | `pnpm exec gspot`    |
+| Yarn                           | `yarn add --dev --exact @gspothq/cli`                                            | `yarn exec gspot`    |
+| Bun                            | `bun add --dev --exact @gspothq/cli`                                             | `bunx gspot`         |
+| mise, without a `package.json` | `mise use --pin node@24 --tool-option allow_low_downloads=true npm:@gspothq/cli` | `mise exec -- gspot` |
+
+## Set up
+
+```shell
+npx gspot init      # pick the checks, then write gspot.toml, the tool files, and the agent rules
+npx gspot install   # install the tools and turn on the Git hooks
+npx gspot check     # check every file now
 ```
 
-The [install guide](https://generativespotting.com/guides/install/) covers other package managers and mise. The
-[gspot guides and reference](https://generativespotting.com/) cover everything else.
+Commit the files that `gspot init` writes. Git does not keep the installed tools or the hooks, so run
+`npx gspot install` again in each new clone.
+
+## Documentation
+
+- [Quickstart](https://generativespotting.com/start/quickstart/)
+- [Read and fix findings](https://generativespotting.com/use/findings/)
+- [Settings in gspot.toml](https://generativespotting.com/configure/gspot-toml/)
+- [Every check](https://generativespotting.com/reference/checks/) and
+  [every command](https://generativespotting.com/reference/commands/)
+- [Source code and issues](https://github.com/stefanionescu/gspot)
+
+## License
+
+[Apache-2.0](https://github.com/stefanionescu/gspot/blob/main/LICENSE.md)

package/configurations/database/postgres/manifest.toml

@@ -1,114 +1,108 @@
 allowed_words = ["PostgreSQL", "Postgres"]
+
 [configuration]
-title = "Postgres"
+description = "Postgres migrations: squawk for changes that lock or break, ordered versions, and no edits after a run. Schema checks require row security, explicit grants, and an index under every foreign key."
 requires = ["sql"]
-description = "Postgres migrations: squawk for the changes that lock or break, ordered versions, and migrations that never change after they run. The schema checks ask for row security, explicit grants, and an index under every foreign key."
+title = "Postgres"
 
 [detect]
-dependencies = ["pg", "postgres", "psycopg", "asyncpg", "@neondatabase/serverless"]
 content = { "prisma/schema.prisma" = '(?:^|\n)[\t ]*provider[\t ]*=[\t ]*"postgresql"' }
+dependencies = ["pg", "postgres", "psycopg", "asyncpg", "@neondatabase/serverless"]
 
 [files]
 paths = ["db/migrations/*.sql", "migrations/*.sql", "**/supabase/migrations/*.sql"]
 
+[defaults]
+"tools.sqlfluff.dialect" = "postgres"
+
+[[naming.override]]
+allow_digits = true
+categories = ["folders"]
+paths = ["**/migrations/**"]
+reason = "Migration directories use the migration tool timestamp names."
+
 [[tool]]
-name = "squawk"
-version = "2.64.0"
+github = { name = "sbdchd/squawk", version = "v2.64.0" }
 min_version = "2.0.0"
 mise = "github:sbdchd/squawk"
+name = "squawk"
 npm = "squawk-cli"
-github = { name = "sbdchd/squawk", version = "v2.64.0" }
-[[tool.replace]]
-file = ".squawk.toml"
-shared = false
-
-[[tool.replace]]
-file = "squawk.toml"
-shared = false
+replace = [".squawk.toml", "squawk.toml"]
+version = "2.64.0"
 
 [[tool_file]]
+per_scope = true
 target = ".gspot/config/squawk.toml"
 tool = "squawk"
-per_scope = true
-rule_keys = ["excluded_rules"]
 
 [[check]]
-name = "squawk"
+command = ["squawk", "--config", "{tool_file:squawk}", "--reporter", "json", "{files}"]
+example = "A migration that adds a constraint with a full table scan reports a finding. Create the constraint first, and validate it in a separate migration."
 files = { paths = ["{setting:postgres.migrations_folder}/**/*.sql"] }
-example = "A migration adding a constraint that requires a disruptive table scan can report a migration-safety finding. Follow the reported rule to separate creation and validation or otherwise reduce the lock, then review the migration against the deployment database."
+help = "Follow the advice squawk prints for the rule. Turn one rule off with `gspot ignore postgres/squawk --rule <name> --reason \"<why>\"`."
 level = "recommended"
-stage = "commit"
-command = ["squawk", "--config", "{tool_file:squawk}", "--reporter", "json", "{files}"]
+name = "squawk"
 output = { format = "json", line_base = 0, fields = { file = "file", line = "line", column = "column", rule = "rule_name", message = "message" } }
-summary = "Reads every migration for the change that locks a table, rewrites it, or breaks the running application."
+stage = "commit"
+summary = "Checks every migration for changes that lock or rewrite a table, or break the running application."
 why = "A migration that takes an exclusive lock on a large table stops the application for as long as it runs."
-help = "Follow the help squawk prints for the rule. Turn one rule off with gspot ignore postgres/squawk --rule `<name>` --reason \"`<why>`\"."
 
 [[check]]
-name = "migration-order"
-example = "A new migration numbered before the latest committed migration reports an ordering finding. Give the new migration a version later than the committed maximum without renaming already applied migrations."
+example = "A new migration numbered below the latest committed one reports a finding. Give it a later version, and leave applied migrations unchanged."
+help = "Rename the new migration with a version later than the newest committed one."
 level = "recommended"
-stage = "commit"
+name = "migration-order"
 runs = "scope"
+stage = "commit"
 summary = "Checks that every migration has a version, that no two share one, and that a new migration sorts after the committed ones."
-why = "A migration that sorts before one already applied never runs on the databases that are ahead of it."
-help = "Rename the new migration with a version later than the newest committed one."
+why = "A migration that sorts before an applied one never runs on databases already past it."
 
 [[check]]
-name = "edited-migrations"
-example = "Editing an already committed migration reports a frozen-history finding. Preserve the intended change as a new migration, restore the original migration bytes, and rerun. Do not rewrite a migration already applied to shared databases."
+example = "An edit to a committed migration reports a finding. Restore the original file, and write the change as a new migration."
+help = "Restore the file with `git checkout`, and write the change as a new migration."
 level = "recommended"
-stage = "commit"
+name = "edited-migrations"
 runs = "scope"
+stage = "commit"
 summary = "Checks that no migration at or before postgres.frozen_through differs from its committed text."
-why = "A migration that ran never runs again, so an edit to it changes new databases only and the environments drift apart."
-help = "Restore the file with git checkout, and write the change as a new migration."
+why = "An applied migration never runs again, so an edit reaches only new databases, and environments drift apart."
 
 [[check]]
-name = "row-level-security"
-example = "A newly created table without row-level security reports a missing-RLS finding. Add `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` for the table."
+example = "A new table without row-level security reports a finding. Add `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` for it."
+help = "Enable row level security on the table."
 level = "recommended"
-stage = "commit"
+name = "row-level-security"
 runs = "scope"
+stage = "commit"
 summary = "Checks that every table in a client schema turns on row level security."
-why = "A table in an exposed schema with no row security is readable and writable by every client that holds the public key."
-help = "Enable row level security on the table."
+why = "In an exposed schema, every client with the public key can read and write a table that has no row security."
 
 [[check]]
-name = "grants"
 example = "The statement `GRANT ALL ON TABLE public.items TO app_reader;` reports a broad grant. If the role only reads rows, use `GRANT SELECT ON TABLE public.items TO app_reader;`."
+help = "Name the privileges the role needs, such as `SELECT` alone."
 level = "recommended"
-stage = "commit"
+name = "grants"
 runs = "scope"
-summary = "Refuses a grant of every privilege in a migration."
-why = "Granting everything includes truncating the table, adding triggers, and every privilege a later Postgres adds, which nobody meant to give."
-help = "Name the privileges the role needs, such as `SELECT` alone."
+stage = "commit"
+summary = "Reports a migration that grants all privileges."
+why = "A full grant includes truncating the table, adding triggers, and each privilege a later Postgres adds, which nobody meant to give."
 
 [[check]]
-name = "definer-search-path"
-example = "A `SECURITY DEFINER` function without an explicit safe search path reports a finding. Add `SET search_path = ''` to the definition and schema-qualify the objects used in its body."
+example = "A `SECURITY DEFINER` function without a safe search path reports a finding. Add `SET search_path = ''` to the definition, and schema-qualify the objects in its body."
+help = "Give the function an empty `search_path` in its definition, and qualify every name inside it."
 level = "recommended"
-stage = "commit"
+name = "definer-search-path"
 runs = "scope"
+stage = "commit"
 summary = "Checks that every SECURITY DEFINER function sets its search_path."
 why = "A definer function runs with its owner's rights, and a caller who controls the search path chooses the objects it touches."
-help = "Give the function an empty `search_path` in its definition, and qualify every name inside it."
 
 [[check]]
-name = "foreign-key-indexes"
 example = "A foreign key on `orders.customer_id` without an index starting with that column reports a missing index. Add `CREATE INDEX orders_customer_id_idx ON orders (customer_id);` in the migration set."
+help = "Create an index that starts with the foreign key column."
 level = "recommended"
-stage = "commit"
+name = "foreign-key-indexes"
 runs = "scope"
+stage = "commit"
 summary = "Checks that an index, a primary key, or a unique key leads with every foreign key column."
 why = "Deleting a parent row scans the whole child table when the foreign key has no index."
-help = "Create an index that starts with the foreign key column."
-
-[[naming.override]]
-paths = ["**/migrations/**"]
-categories = ["directories"]
-allow_digits = true
-reason = "Migration directories use the migration tool timestamp names."
-
-[defaults]
-"tools.sqlfluff.dialect" = "postgres"

package/configurations/database/postgres/rules/POSTGRES.md

@@ -1,12 +1,13 @@
 # Postgres
 
-Migrations, tables, row security, functions, grants, data migrations, and tests of a Postgres
-database. Use the roles and schemas the application declares.
+Read this rule when you change Postgres migrations, policies, functions, grants, or database tests.
+
+Use the roles and schemas the application declares.
 
 ## Migrations
 
-- Create a blank migration with the project's migration command, then edit the generated file.
-- Repair migration history only when the user asks for that task.
+- Create a blank migration with the command the project uses, then edit the generated file.
+- Repair migration history only when the user asks.
 - Make every durable change through a migration. Never use a web console or SQL editor on a remote database.
 - Use idempotent data definition language (DDL) only when the public interface promises repeated execution and you verify existing definitions. Do not hide schema drift with `IF NOT EXISTS`.
 
@@ -14,39 +15,39 @@ database. Use the roles and schemas the application declares.
 
 - Use UUIDv7 keys when rows need time order.
 - Use `TIMESTAMPTZ` for timestamps. Mutable rows that need audit columns get `created_at` and
-  `updated_at`, which the declared timestamp trigger or write owner updates.
+  `updated_at`, which the declared timestamp trigger or the writing code updates.
 - Index common filters, ordering columns, and frequent row security predicates.
 - Durable invariants live in the database as generated columns, uniqueness, and check
   constraints, not only in client validation.
 
 ## Row-level security
 
-- Every policy names its roles with `TO`, unless every role belongs in it.
+- Each policy names its roles with `TO`, unless all roles belong in it.
 - Wrap the identity function of an ownership check in a scalar subquery, so the planner evaluates
   it once per statement instead of once per row.
-- `UPDATE` needs both a `SELECT` policy and an `UPDATE` policy.
+- `UPDATE` needs both a `SELECT` and an `UPDATE` policy.
 
 | Operation   | Policy expression                                                               |
 | ----------- | ------------------------------------------------------------------------------- |
 | Read rows   | `USING` selects visible existing rows                                           |
 | Insert rows | `WITH CHECK` validates the proposed row; an insert policy has no `USING` clause |
 | Update rows | `USING` selects existing rows and `WITH CHECK` validates their new values       |
-| Delete rows | `USING` selects rows that may be deleted                                        |
+| Delete rows | `USING` selects rows the role may delete                                        |
 
-- Permissive policies broaden access and restrictive policies add conditions; review how every
-  policy for the role combines.
+- Permissive policies broaden access and restrictive ones add conditions; review how all
+  policies for the role combine.
 - Check resource ownership and tenant membership. Check proposed values too, so an update cannot
   move a row into another user's or tenant's scope.
 - Handle an unauthenticated identity explicitly, and limit anonymous access to the rows and
   operations the public API exposes.
 - Authorize from trusted claims and current membership data, never from user-editable template
-  metadata, and account for stale claims after a membership change.
-- Grants and row level security (RLS) provide separate controls: restrict table and schema privileges, then limit rows with
+  metadata. Account for stale claims after a membership change.
+- Grants and row level security (RLS) control access separately: restrict table and schema privileges, then limit rows with
   policies. RLS does not cover `TRUNCATE`.
 - A `USING (true)` policy fits only a public or service-only table, and the
   migration says why.
 - A privileged service role still needs explicit table grants, never a bypass for precise ones.
-- A view that clients can read sets `security_invoker = true` on Postgres 15 and later to respect
+- A view that clients can read sets `security_invoker = true` on Postgres 15 and later to apply
   the RLS of its tables. Otherwise, revoke access to it or keep it in a private schema.
 
 ## Functions and grants

package/configurations/framework/astro/manifest.toml

@@ -1,10 +1,8 @@
-
-
 [configuration]
-title = "Astro"
+description = "Astro components: ESLint applies the recommended and accessibility rules of eslint-plugin-astro as errors to frontmatter, markup, and scripts. `astro check` reports type errors in each component."
 requires = ["javascript"]
 suggests = ["typescript", "css"]
-description = "Astro components: ESLint reads the frontmatter, the markup, and the scripts together with the recommended and accessibility rules of the Astro plugin as errors, and astro check reports type errors in every component."
+title = "Astro"
 
 [detect]
 dependencies = ["astro"]
@@ -14,12 +12,15 @@ extensions = [".astro"]
 extensions = [".astro"]
 filenames = ["astro.config.mjs", "astro.config.ts"]
 
+[defaults]
+"tools.eslint.import_extension" = "extensionless"
+
 [[tool]]
+kind = "library"
 name = "eslint-plugin-astro"
+npm = "eslint-plugin-astro"
 rule_prefix = "astro"
-kind = "library"
 version = "1.7.0"
-npm = "eslint-plugin-astro"
 
 [tool.eslint]
 extensions = [".astro"]
@@ -29,15 +30,15 @@ name = "eslint-plugin-jsx-a11y"
 
 [[tool]]
 name = "astro-check"
-version = "0.9.10"
 npm = "@astrojs/check"
+version = "0.9.10"
 version_command = ["astro", "check", "--version"]
 
 [[tool]]
-name = "prettier-plugin-astro"
 kind = "library"
-version = "1.0.1"
+name = "prettier-plugin-astro"
 npm = "prettier-plugin-astro"
+version = "1.0.1"
 
 [tool.prettier]
 entry = "dist/index.js"
@@ -49,26 +50,6 @@ files = "*.astro"
 [tool.prettier.overrides.options]
 parser = "astro"
 
-[[check]]
-name = "astro-check"
-example = "A component whose frontmatter holds `const count: number = 'three';` reports `ts(2322)`. Give the value the declared type, such as `const count: number = 3;`."
-level = "recommended"
-stage = "push"
-runs = "scope"
-cwd = "scope"
-command = ["astro-check", "astro", "check", "--minimumSeverity", "warning", "--minimumFailingSeverity", "warning"]
-exit_codes = [1]
-summary = "Runs astro check over the scope: the type errors and warnings of every Astro component."
-why = "The TypeScript compiler cannot read a component file, so a type error inside one ships unless the Astro checker reads it."
-help = "Read the first error astro check prints and fix that component; later errors are often the same mistake."
-
-[check.files]
-extensions = [".astro"]
-
-[check.output]
-format = "regex"
-pattern = "^(?<file>[^:\\s][^:]*\\.astro):(?<line>\\d+):(?<column>\\d+) - (?:error|warning) (?<rule>[a-z-]+\\(\\d+\\)): (?<message>.*)$"
-
 [eslint]
 all_level_rules = ["astro/no-unused-css-selector", "astro/prefer-class-list-directive", "astro/prefer-object-class-list", "astro/prefer-split-class-list"]
 
@@ -81,15 +62,32 @@ package = "eslint-plugin-astro"
 source = "configs.flat/jsx-a11y-recommended"
 
 [[eslint.rules_off]]
-rules = ["gspot/no-trivial-files"]
 files = ["**/*.astro", "**/*.astro/*.ts", "**/*.astro/*.js"]
 reason = "A component is markup, never a file that only forwards: a script that only imports a module is how Astro bundles client code, and Astro reads the props of a component from the Props type in its own frontmatter."
-
-[defaults]
-"tools.eslint.import_extension" = "extensionless"
+rules = ["gspot/no-trivial-files"]
 
 [[tool_file]]
-target = ".gspot/config/eslint.config.mjs"
-tool = "eslint"
 fragment = true
 required_tools = ["eslint-plugin-astro", "eslint-plugin-jsx-a11y"]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+
+[[check]]
+command = ["astro-check", "astro", "check", "--minimumSeverity", "warning", "--minimumFailingSeverity", "warning"]
+cwd = "scope"
+example = "A component whose frontmatter holds `const count: number = 'three';` reports `ts(2322)`. Give the value the declared type, such as `const count: number = 3;`."
+exit_codes = [1]
+help = "Fix the first error `astro check` prints; later errors often come from the same mistake."
+level = "recommended"
+name = "astro-check"
+runs = "scope"
+stage = "push"
+summary = "Runs astro check over the scope: the type errors and warnings of every Astro component."
+why = "tsc cannot parse a component file, so a type error inside one ships unless `astro check` catches it."
+
+[check.files]
+extensions = [".astro"]
+
+[check.output]
+format = "regex"
+pattern = "^(?<file>[^:\\s][^:]*\\.astro):(?<line>\\d+):(?<column>\\d+) - (?:error|warning) (?<rule>[a-z-]+\\(\\d+\\)): (?<message>.*)$"

package/configurations/framework/astro/rules/ASTRO.md

@@ -1,6 +1,6 @@
 # Astro
 
-These rules cover Astro components, islands, markup, routing, and the data a page loads.
+Read this rule when you change Astro components, pages, or content collections.
 
 ## Components
 
@@ -19,7 +19,7 @@ These rules cover Astro components, islands, markup, routing, and the data a pag
 - Ship HTML by default. Add a `client:` directive only to a component that needs the browser.
 - Pick the most deferred directive that works: `client:visible` or `client:idle` before `client:load`.
 - `client:only` names the framework of the component, such as `client:only="react"`.
-- Astro serializes island props, so pass plain data. A function or a class instance does not survive the trip.
+- Astro serializes island props, so pass plain data. A function or a class instance does not survive serialization.
 
 ## Markup
 

package/configurations/framework/expo/manifest.toml

@@ -1,7 +1,7 @@
 [configuration]
-title = "Expo"
+description = "Expo applications: rules for public environment variables and DOM exports, and the project and SDK checks of Expo Doctor. The React Native configuration adds the component and style rules."
 requires = ["react-native"]
-description = "Expo applications: rules for public environment variables and DOM exports, plus Expo Doctor's project and SDK compatibility checks. React Native supplies the native component and style rules."
+title = "Expo"
 
 [detect]
 dependencies = ["expo"]
@@ -10,34 +10,34 @@ dependencies = ["expo"]
 filenames = ["app.json", "app.config.js", "app.config.ts", "eas.json"]
 
 [[tool]]
+kind = "library"
 name = "eslint-plugin-expo"
+npm = "eslint-plugin-expo"
 rule_prefix = "expo"
-kind = "library"
 version = "1.1.0"
-npm = "eslint-plugin-expo"
 
 [[tool]]
 name = "expo-doctor"
-version = "1.20.4"
 npm = "expo-doctor"
-
-[[check]]
-name = "doctor"
-tool = "expo-doctor"
-example = "An Expo project whose installed `react-native` differs from the version its Expo SDK expects reports a failed Doctor check. Install the expected version with `npx expo install --check` and rerun."
-level = "recommended"
-stage = "push"
-runs = "scope"
-needs = ["network"]
-summary = "Runs Expo Doctor in the selected Expo scope and reports each failed check with its issues."
-why = "A native package on the wrong version for the Expo SDK builds and then crashes on the device."
-help = "Read the issues and advice Expo Doctor prints for the failed check, then run npx expo install --check."
+version = "1.20.4"
 
 [eslint]
 all_level_rules = ["expo/prefer-box-shadow"]
 
 [[tool_file]]
-target = ".gspot/config/eslint.config.mjs"
-tool = "eslint"
 fragment = true
 required_tools = ["eslint-plugin-expo"]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+
+[[check]]
+example = "A `react-native` version that differs from the one the Expo SDK requires fails a Doctor check. Run `npx expo install --check` to install the matching version."
+help = "Follow the advice Expo Doctor prints, then run `npx expo install --check`."
+level = "recommended"
+name = "expo-doctor"
+needs = ["network"]
+runs = "scope"
+stage = "push"
+summary = "Runs Expo Doctor and reports each failed check with its details."
+tool = "expo-doctor"
+why = "A native package on the wrong version for the Expo SDK builds and then crashes on the device."

package/configurations/framework/express/manifest.toml

@@ -1,17 +1,23 @@
 [configuration]
-title = "Express"
+description = "An Express service: Semgrep rules for request handling, and an OpenAPI document that lints and matches its source."
 requires = ["javascript"]
 suggests = ["openapi"]
-description = "An Express service: the Semgrep rules for request handling, an OpenAPI document that lints and matches its source."
+title = "Express"
 
 [detect]
 dependencies = ["express"]
 
 [[eslint.selectors]]
-selector = "CallExpression[callee.property.name=/^(json|send)$/] ObjectExpression > Property[key.name=/^(message|error)$/] > TemplateLiteral.value[expressions.length>0]"
 message = "A message a client reads names no identifier; put the value in its own field."
+selector = "CallExpression[callee.property.name=/^(json|send)$/] ObjectExpression > Property[key.name=/^(message|error)$/] > TemplateLiteral.value[expressions.length>0]"
 
 [[tool_file]]
+fragment = true
 target = ".gspot/config/eslint.config.mjs"
 tool = "eslint"
-fragment = true
+
+[[tool_file]]
+per_scope = true
+target = ".gspot/config/semgrep/express.yml"
+tool = "semgrep"
+when = { configuration = "security" }

package/configurations/framework/express/rules/EXPRESS.md

@@ -1,6 +1,8 @@
 # Express
 
-Routes, middleware, errors, and body parsing in an Express service, on top of the HTTP rules.
+Read this rule when you change routes, middleware, or error handling in an Express service.
+
+Follow the HTTP rules too.
 
 ## Routes and middleware
 
@@ -33,18 +35,18 @@ router.post('/orders', authenticate, validateBody(submitOrderSchema), async (req
 
 - Middleware can enforce ownership. It reaches the database for product behavior only through auth
   or ownership helpers built for that boundary.
-- A permission check that depends on domain state belongs in a module; a transport-level one
-  belongs in ownership middleware.
+- A permission check that depends on domain state belongs in a module, and a transport-level one
+  in ownership middleware.
 
 ## Errors
 
-- Express 5 forwards the rejection of a promise that a route or middleware returns, so return the
-  promise and add no wrapper that repeats this. Express 4 needs the project's async handler or an
+- Express 5 forwards a rejected promise that a route or middleware returns, so return it and add
+  no wrapper that repeats this. Express 4 needs the project's async handler or an
   explicit `next(error)`.
 - Callback-based asynchronous work passes its errors to `next(error)` in both versions.
 - Error middleware keeps its four-argument signature, even when the function does not use an argument.
-- After the response sends its headers, error middleware calls `next(error)` instead of writing a
-  second response.
+- After the headers go out, error middleware calls `next(error)` instead of writing a second
+  response.
 - The not-found handler comes after every route.
 
 ## Body parsing and proxies

package/configurations/framework/fastapi/manifest.toml

@@ -1,11 +1,17 @@
 [configuration]
-title = "FastAPI"
+description = "Checks FastAPI routes with Ruff. With security, adds Semgrep rules for request handling, and suggests the OpenAPI configuration."
 requires = ["python"]
 suggests = ["openapi"]
-description = "Checks FastAPI route declarations with Ruff. Adds Semgrep request-handling rules when security is selected and suggests the OpenAPI configuration."
+title = "FastAPI"
 
 [detect]
 dependencies = ["fastapi"]
 
-[ruff_rules]
+[ruff]
 recommended = ["FAST001", "FAST002", "FAST003"]
+
+[[tool_file]]
+per_scope = true
+target = ".gspot/config/semgrep/fastapi.yml"
+tool = "semgrep"
+when = { configuration = "security" }