@gspothq/cli 0.0.0-stage → 0.1.1

package/configurations/platform/supabase/manifest.toml

@@ -0,0 +1,112 @@
+allowed_words = ["Supabase"]
+[configuration]
+title = "Supabase"
+requires = ["postgres", "javascript"]
+suggests = ["typescript"]
+description = "A Supabase project: a project file that parses, edge functions under Deno, and migrations named as the CLI names them. Every storage bucket has a policy, and privileged keys stay in their allowed files."
+
+[detect]
+paths = ["**/supabase/config.toml"]
+project_files = ["supabase/config.toml"]
+
+[files]
+paths = ["supabase/config.toml", "supabase/functions/**", "supabase/seed.sql"]
+
+[[tool]]
+name = "deno"
+version = "2.6.6"
+min_version = "2.0.0"
+mise = "deno"
+brew = "deno"
+github = { name = "denoland/deno", version = "v2.6.6" }
+scoop = "deno"
+
+[[tool]]
+name = "supabase"
+system = true
+version_command = ["--version"]
+min_version = "2.0.0"
+mise = "supabase"
+brew = "supabase/tap/supabase"
+npm = "supabase"
+scoop = "supabase"
+
+[[check]]
+name = "project-file"
+example = "A function entry in `supabase/config.toml` naming a function absent from the repository reports a stale function configuration. Restore the function source or remove its obsolete configuration table."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that the project file parses, and that every function it configures has a folder with an index file."
+why = "The CLI reads this file at every deploy, and a function it configures with no code fails there."
+help = "Correct the file at the place the message names, or remove the table of a function the repository does not hold."
+
+[[check]]
+name = "migration-names"
+example = "A Supabase migration named `add_users.sql` lacks the required timestamp prefix. Create it with `supabase migration new add_users`, then move the intended SQL into the generated migration file."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that every migration is named fourteen digits, an underscore, and snake case words."
+why = "The CLI orders and records migrations by this name, and it skips a file it cannot read a version from."
+help = "Create the migration with supabase migration new `<name>`, which writes the name."
+
+[[check]]
+name = "storage-policies"
+example = "A declared storage bucket with no matching policy on `storage.objects` reports missing access policy. Add a migration defining the intended access policy for that bucket and rerun."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that every storage bucket in the project file has a policy on storage.objects that names it."
+why = "A bucket with no policy is closed to everyone or, when it is public, open to everyone, and neither is a decision anybody wrote down."
+help = "Add a policy on storage.objects for the bucket in a migration."
+
+[[check]]
+name = "service-role-key"
+example = "A client source reading a Supabase secret or service-role key reports an administrative-key boundary finding. Move privileged operations and the key read to a server-only path, exposing only the required server operation to the client."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that secret and service role keys are named only in edge functions and test files."
+why = "Secret and service role keys bypass row level security, so a client bundle that holds either exposes privileged database access."
+help = "Move code to edge functions or tests, or run gspot ignore supabase/service-role-key with a reason."
+
+[[check]]
+name = "deno-lint"
+example = "An Edge Function declaring `var greeting = \"hello\";` reports `no-var`. Use `const greeting = \"hello\";` when the value does not change, then rerun with the pinned Deno tool available."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+tool = "deno"
+summary = "Runs deno lint over every edge function, with the function's own deno.json."
+why = "Edge functions run under Deno, and its linter knows the runtime the Node rules do not."
+help = "Change the code the way the rule says; deno lint --rules explains each one."
+
+[[check]]
+name = "deno-check"
+example = "An Edge Function assigning a string to a number-typed variable reports a Deno type error. Correct the value or type to match the intended contract, then rerun."
+level = "recommended"
+stage = "push"
+runs = "scope"
+tool = "deno"
+summary = "Type checks the entry file of every edge function with deno check."
+why = "The project compiler does not resolve the import map of a function, so only Deno sees its types."
+help = "Fix the first error Deno prints; later ones are often the same mistake."
+
+[[check]]
+name = "stale-types"
+command = ["supabase", "gen", "types", "typescript", "--local", "{each:--schema:supabase.schemas}"]
+generated_paths = [{ stdout = "{setting:supabase.types_file}" }]
+example = "A database types file that differs from the configured local Supabase schema reports drift. With the local database ready, regenerate using `supabase gen types typescript --local`, write the output to the configured file, and rerun."
+level = "recommended"
+stage = "push"
+runs = "scope"
+tool = "supabase"
+needs = ["docker"]
+summary = "Compares supabase.types_file with the types the CLI writes from the local database."
+why = "Stale types let code compile against a column the database dropped."
+help = "Run supabase gen types typescript --local and write the output to the file."
+
+[defaults]
+"postgres.client_schemas" = ["public"]
+"tools.squawk.assume_in_transaction" = true

package/configurations/platform/supabase/rules/SUPABASE.md

@@ -0,0 +1,129 @@
+# Supabase
+
+Layout, database access, storage, Edge Functions, configuration, and secrets of a Supabase
+project, on top of the Postgres rules. Supabase uses the API roles `anon`, `authenticated`, and
+`service_role`.
+
+## Layout and migrations
+
+- Use the established Supabase layout for migrations, Edge Functions, storage assets, and tests.
+- A schema or contract change that affects another project updates that consumer deliberately.
+
+## Database access
+
+- `[api].schemas` in `config.toml` lists the schemas the Data API exposes. Treat those schemas as
+  externally reachable.
+- row level security (RLS) with no policy denies access through the API roles. Use that choice for tables that clients
+  must not read.
+- Roles Supabase creates for auth, cron, or storage stay scoped to the functions and schemas they need.
+- Each policy chooses `TO anon`, `TO authenticated`, or `TO service_role` deliberately. The service
+  role never stands in for precise grants or hides a missing policy.
+- A table can skip the foreign key to `auth.users` so its history survives account deletion.
+- Keep `[api].max_rows` conservative to bound accidental or malicious payloads.
+
+## Direct database connections
+
+Choose the Supabase connection mode for the workload.
+
+| Workload                                        | Connection choice                                                     |
+| ----------------------------------------------- | --------------------------------------------------------------------- |
+| Short-lived serverless application requests     | Transaction pooler, with a compatible driver                          |
+| Persistent server with direct network access    | Direct connection with a bounded application pool                     |
+| Persistent server on an IPv4-only network       | Session pooler when the direct endpoint is unavailable                |
+| Migrations, dumps, or session-dependent tooling | Direct connection; use a supported session alternative when necessary |
+
+A separate migration credential holds schema privileges. The application role holds only what
+runtime needs
+See [connection modes](https://supabase.com/docs/guides/database/connecting-to-postgres). Postgres.js
+uses the transaction pooler's supported configuration.
+Set explicit connection, idle, and query timeouts. Budget connections across instances and
+workers. With Postgres.js through transaction pooling, set `prepare: false` and confirm the setting
+after a driver or pooler change.
+
+A direct database connection carries no Supabase identity. When an application passes identity into
+PostgreSQL, one server operation verifies the token's issuer, signature, audience, and expiry. It
+maps the identity to a fixed set of allowed roles, then opens a transaction on a restricted
+connection. Use parameterized transaction-local `set_config` for claims and fixed trusted SQL for
+the role. Every protected query uses that transaction. Commit or rollback ends its context.
+
+When Drizzle generates migrations that the Supabase CLI applies, keep the CLI's migration format
+and one authoritative applied-history ledger. Declare provider-managed schemas and roles as
+existing. Check replay through the chosen runner. See
+[migration history](https://supabase.com/docs/guides/local-development/database-migrations) and
+[verified claims](https://supabase.com/docs/reference/javascript/auth-getclaims).
+
+## Storage
+
+- Define buckets in migrations and mirror them in `config.toml`. A change to `public`,
+  `file_size_limit`, or `allowed_mime_types` updates both in the same change.
+- Bucket restrictions enforce file size and MIME type, not only application validation.
+- RLS policies on `storage.objects` and `storage.buckets` control access. The service controls metadata in the `storage` schema: migrations add only policies, indexes for RLS or validation, triggers,
+  and bucket configuration. Object rows change only through the Storage API.
+
+### Storage names
+
+<!-- level: all -->
+
+- Storage buckets use `lower_snake_case`.
+- Use stable, explicit storage object keys.
+- Validate user-controlled key segments and limit their length before use.
+- Do not embed secrets, provider tokens, raw user text, or private identifiers in
+  object keys.
+- Do not use display text as storage identity.
+
+| Avoid                                       | Prefer                                 | Meaning                              |
+| ------------------------------------------- | -------------------------------------- | ------------------------------------ |
+| `Avatar Pictures`                           | `avatar_images`                        | A bucket.                            |
+| `avatars/john@example.com/avatar image.png` | `avatars/user_01hxx8j2r6/avatar.png`   | Object key without personal content. |
+| `uploads/latest`                            | `reports/report_01hxx8j2r6/export.pdf` | A key tied to a specific report.     |
+
+## Edge functions
+
+- Each deployable function lives under `functions/<function-name>/` in the CLI's functions root,
+  with a `[functions.<name>]` entry whose `entrypoint` starts from the configuration file directory.
+  Shared code lives in `functions/_shared/`, which Supabase never deploys.
+- Name a function folder in kebab-case for its callable operation, not its technology:
+  `submit-order`, never `SubmitOrder` or `provider_handler`. The folder, configuration entry, and
+  deployed name match.
+- Edge Functions run on Deno, and the Deno rules hold.
+- Keep `verify_jwt = true` for user-authenticated functions. Set it to `false` only when the function
+  exposes only public, harmless behavior, verifies a provider webhook signature, checks a service secret, or takes
+  a Vault secret from cron.
+- A publishable or secret API key differs from a user JSON Web Token (JWT). Never send that key as
+  `Authorization: Bearer <key>`. Forward the caller's `Authorization` header to the Supabase
+  client, so RLS runs as the user.
+- A service-role client serves only admin operations that cannot run as a user, on a path that
+  code and tests make explicit.
+- Keep handlers small: parsing, validation, responses, provider calls, and database operations move
+  into local modules as complexity grows. JSON responses, `OPTIONS`, and Cross-Origin Resource Sharing (CORS) go through one helper
+  in `functions/_shared/`.
+- Functions have runtime, CPU, memory, bundle-size, and log-rate limits, so long CPU-heavy work
+  runs elsewhere. Raw Supabase errors that expose credentials stay out of logs.
+- When you write tests, cover function logic in unit tests. Integration tests against a local
+  database and function server cover the client, auth, RLS, and the invocation path.
+
+## Configuration and secrets
+
+`config.toml` defines the desired local and remote configuration.
+
+Ask the user before changing signup, anonymous sign-in, providers, hooks, JWT expiry, or password policy.
+Also ask before weakening auth settings, row-level security, grants, or `verify_jwt`.
+Proceed when the task already authorizes the change. Write the reason in the commit when the user authorizes a commit.
+
+- Service keys, Edge secrets, Vault values, database URLs, and provider API keys stay backend-only.
+  They never appear in app code, checked-in files, logs, migration comments, tests, or test data.
+- Local secrets live in ignored env files or the caller's environment.
+- `pg_cron` and `pg_net` change only through migrations and deploy scripts. Cron reads its bearer
+  tokens from `vault.decrypted_secrets` at call time, never from its SQL.
+- A change to a cron target's auth updates the Vault secret, the function's check, and the cron
+  SQL together.
+
+## References
+
+[Database migrations](https://supabase.com/docs/guides/deployment/database-migrations),
+[row-level security](https://supabase.com/docs/guides/database/postgres/row-level-security),
+[Edge Functions](https://supabase.com/docs/guides/functions) and their
+[auth](https://supabase.com/docs/guides/functions/auth) and
+[configuration](https://supabase.com/docs/guides/functions/function-configuration),
+[storage access control](https://supabase.com/docs/guides/storage/security/access-control), and
+[scheduling functions](https://supabase.com/docs/guides/functions/schedule-functions).

package/configurations/platform/supabase/semgrep/supabase.yml

@@ -0,0 +1,60 @@
+rules:
+    - id: gspot.supabase.postgrest-filter-interpolation
+      patterns:
+          - pattern-either:
+                - pattern: $CLIENT.or(`...${$VAR}...`, ...)
+                - pattern: $CLIENT.filter($COLUMN, "in", `...${$VAR}...`, ...)
+                - pattern: $CLIENT.textSearch($COLUMN, `...${$VAR}...`, ...)
+          - pattern-not: '$CLIENT.textSearch(..., {..., type: "plain", ...})'
+          - pattern-not: '$CLIENT.textSearch(..., {..., type: "phrase", ...})'
+          - pattern-not: '$CLIENT.textSearch(..., {..., type: "websearch", ...})'
+      message: An interpolated value enters raw PostgREST filter syntax. Escape it for
+          the operator or use a typed filter.
+      languages:
+          - typescript
+          - javascript
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-20
+          category: security
+    - id: gspot.supabase.edge-cors-wildcard-with-credentials
+      pattern: '{..., "Access-Control-Allow-Origin": "*", ...,
+          "Access-Control-Allow-Credentials": "true", ...}'
+      message: Wildcard origins cannot be used with credentialed requests. List the
+          permitted origins.
+      languages:
+          - typescript
+          - javascript
+      severity: ERROR
+      paths:
+          include:
+              - /supabase/functions/**
+      metadata:
+          cwe:
+              - CWE-346
+          category: security
+    - id: gspot.supabase.edge-unvalidated-json-body
+      patterns:
+          - pattern: await req.json()
+          - pattern-not-inside: |-
+                const $BODY = await req.json()
+                ...
+                $SCHEMA.parse($BODY)
+          - pattern-not-inside: |-
+                const $BODY = await req.json()
+                ...
+                $SCHEMA.safeParse($BODY)
+      message: Request body consumed without schema validation. Use zod or similar to
+          validate the parsed JSON.
+      languages:
+          - typescript
+          - javascript
+      severity: ERROR
+      paths:
+          include:
+              - /supabase/functions/**
+      metadata:
+          cwe:
+              - CWE-20
+          category: security

package/configurations/testing/jest/manifest.toml

@@ -0,0 +1,54 @@
+[configuration]
+title = "Jest"
+requires = ["javascript", "coverage"]
+description = "Jest test rules and coverage floors for repository-owned test suites."
+
+[detect]
+dependencies = ["jest"]
+filenames = ["jest.config.*"]
+
+[files]
+paths = ["{setting:test_files}", "**/jest.config.*"]
+
+[[tool]]
+name = "jest"
+system = true
+
+[[tool]]
+name = "eslint-plugin-jest"
+rule_prefix = "jest"
+kind = "library"
+version = "29.16.6"
+npm = "eslint-plugin-jest"
+
+[[check]]
+name = "coverage"
+example = "Jest reports `coverage threshold for lines (90%) not met: 85%`. Add tests for the lines its report marks uncovered."
+level = "recommended"
+stage = "push"
+runs = "scope"
+cwd = "scope"
+tool = "jest"
+command = ["jest", "--ci", "--rootDir={root}/{scope}", "--coverage", "--coverageReporters=text-summary", "--coverageThreshold={\"global\":{\"lines\":{setting:coverage.lines},\"branches\":{setting:coverage.branches},\"functions\":{setting:coverage.functions},\"statements\":{setting:coverage.statements}}}"]
+run_in_copy = true
+exit_codes = [1]
+crash_pattern = "^No tests found|^  ● Test suite failed to run"
+summary = "Runs Jest in a disposable source copy and checks all four coverage floors."
+why = "A coverage floor keeps new code from arriving untested."
+help = "Correct failed tests and cover the reported branches, functions, lines, and statements."
+
+[check.files]
+extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]
+
+[check.output]
+format = "regex"
+pattern = "^Jest: \"global\" (?<message>coverage threshold for .+ not met: .+)$"
+
+[eslint]
+all_level_rules = ["jest/prefer-strict-equal"]
+
+[[tool_file]]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+fragment = true
+required_tools = ["eslint-plugin-jest"]

package/configurations/testing/pytest/manifest.toml

@@ -0,0 +1,53 @@
+[configuration]
+title = "pytest"
+requires = ["python", "coverage"]
+description = "pytest suites: Ruff pytest style rules over the tests, pytest test-name prefixes, and a coverage floor at push."
+
+[detect]
+dependencies = ["pytest"]
+filenames = ["conftest.py", "pytest.ini"]
+
+[[tool]]
+name = "pytest"
+install_hint = "Run: python -m pip install pytest"
+system = true
+suppression = { marker = "\\bpragma: ?no cover\\b", reason = "#[^#]*# ?(?<reason>\\S.*)" }
+min_version = "7.0.0"
+pypi = "pytest"
+version_pattern = "(\\d+\\.\\d+\\.\\d+)"
+
+[[tool]]
+name = "pytest-cov"
+install_hint = "Install pytest-cov in the Python environment used by pytest."
+kind = "library"
+system = true
+pypi = "pytest-cov"
+version_command = ["pytest", "--version", "--version"]
+version_pattern = "pytest-cov-(\\d+(?:\\.\\d+)+)"
+
+[[check]]
+name = "coverage"
+tool = ["pytest", "pytest-cov"]
+example = "pytest-cov reports `FAIL Required test coverage of 90% not reached. Total coverage: 85%`. Add a Python test for the uncovered behavior."
+level = "recommended"
+stage = "push"
+runs = "scope"
+cwd = "scope"
+command = ["pytest", "-q", "--strict-markers", "--strict-config", "--cov", "--cov-fail-under={setting:coverage.lines}", "--no-header", "-p", "no:cacheprovider"]
+exit_codes = [1]
+files = { extensions = [".py"] }
+output = { format = "regex", pattern = "^(?<message>(?:FAIL Required test coverage|FAILED |ERROR ).*)$" }
+summary = "Runs the test suite with coverage, and fails when a test fails or the covered share falls under the floor."
+why = "Python coverage reveals branches and lines the test suite does not exercise before a push."
+help = "Fix the failing test, or add tests for the code the report shows uncovered. Lower coverage.lines with a reason."
+
+[ruff_rules]
+recommended = ["PT008", "PT009", "PT010", "PT011", "PT012", "PT013", "PT014", "PT015", "PT016", "PT017", "PT020", "PT021", "PT024", "PT025", "PT027", "PT028", "PT030", "PT031"]
+all = ["PT001", "PT002", "PT003", "PT006", "PT007", "PT018", "PT019", "PT022", "PT023", "PT026"]
+
+[[naming.override]]
+paths = ["**/test_*.py", "**/*_test.py", "**/tests/**/*.py", "**/conftest.py"]
+languages = ["python"]
+categories = ["functions", "methods"]
+ignored_prefix = "^test_"
+reason = "The test runner finds a test by this prefix."

package/configurations/testing/swift-tests/manifest.toml

@@ -0,0 +1,52 @@
+[configuration]
+title = "Swift Tests"
+requires = ["swift", "coverage"]
+description = "Swift test files under XCTest and Swift Testing. A disabled test says why, no test sleeps, and coverage holds a floor."
+
+[detect]
+tags = ["swift-test", "swift-test-target"]
+paths = ["**/*.xctestplan"]
+
+[files]
+paths = ["**/*Tests/**/*.swift"]
+filenames = ["*.xctestplan"]
+
+[[tool_file]]
+target = ".gspot/config/swiftlint.yml"
+tool = "swiftlint"
+per_scope = true
+fragment = true
+pointer = { path = ".swiftlint.yml", directories = ["**/*Tests"], body = "parent_config: {target_json}\ndisabled_rules:\n    - force_unwrapping\n    - missing_docs\n    - no_magic_numbers\n" }
+
+[[check]]
+name = "skip-reasons"
+example = "In a Swift test, `throw XCTSkip()` reports a missing reason. Restore the test, or supply a nonempty reason such as `throw XCTSkip(\"Requires the hardware test device\")`. The check requires a reason; it does not validate when the test will be enabled."
+level = "recommended"
+stage = "commit"
+files = { tags = ["swift-test"] }
+summary = "Checks that skip calls and disabled traits name a nonempty reason, and unavailable tests carry an explanation."
+why = "A test turned off with no reason stays off, because nobody knows when it is safe to turn on."
+help = "Say why the test is off and what turns it back on, or delete the test."
+
+[[check]]
+name = "sleep"
+example = "A test using a fixed sleep to wait for asynchronous work reports a timing finding. Wait for the actual completion expectation or poll the required condition with a bounded timeout."
+level = "all"
+stage = "commit"
+files = { tags = ["swift-test"] }
+summary = "Refuses sleep calls in test files."
+why = "A sleep makes a test slow when it passes and flaky when the machine is slower than the number."
+help = "Wait on an expectation or a confirmation, or poll a condition with a timeout."
+
+[[check]]
+name = "coverage"
+example = "A Swift target reports 85% line coverage against a 90% floor. Add a test that exercises its uncovered lines, then rerun the target."
+level = "recommended"
+stage = "push"
+runs = "scope"
+needs = ["build"]
+operating_systems = ["macos", "linux"]
+files = { extensions = [".swift"] }
+summary = "Measures Xcode projects and Swift packages, holding each source target against coverage.lines and its coverage.override floor."
+why = "A target-specific coverage floor exposes Swift code that its test target has not exercised."
+help = "Add tests for the target, or lower its floor with a reason."

package/configurations/testing/swift-tests/rules/SWIFT-TESTS.md

@@ -0,0 +1,79 @@
+# Swift Tests
+
+When you write tests, these rules cover XCTest, Swift Testing, and snapshot tests.
+
+## What to test
+
+- Unit test domain entities, value objects, mapping, and application operations. When the
+  project uses view models, test their behavior too.
+- Test a use case with mocked repository protocols or network and database clients.
+- Test repository mapping apart from use case behavior.
+- When the project uses view models, assert state transitions and what the application shows to the user, never private method calls.
+- Test invalid payload mapping and validate external data when it enters the program.
+- Test cancellation and stale results for asynchronous operations.
+- Do not mock SwiftUI or test its framework behavior.
+- Do not test trivial getters, setters, or framework behavior.
+- Do not add a protocol only to make a mock when the code already accepts the network or database client as an argument.
+
+## Coverage by layer
+
+- Domain tests cover value validation, invariants, domain errors, and computed business properties.
+- Use case tests cover success, repository failure, validation failure, cancellation, and policy decisions.
+- Repository tests cover record mapping and error translation.
+- Network client tests cover the URL, the method, the headers, and the encoded body.
+- Network client tests also cover a non-HTTP response, a status outside 200 to 299, a decoding failure, and cancellation.
+- When the project uses view models, test initial, loading, success, empty, and error states,
+  then retry and stale results.
+- When the project uses coordinators, test route stack changes, modal state, dismissal, root
+  resets, and deep link translation.
+
+## Test data
+
+- Test data shows the behavior under test.
+- Prefer private builders or stubs with sensible defaults when model construction hides the point of the test.
+- Keep test builders beside the tests that use them, unless many test files share them on purpose.
+- Decode JSON test data only when the test covers decoding, mapping, or the format of an external payload.
+- Do not add a production default to make a test shorter.
+- Prefer stable identifiers, dates, clocks, and ordering.
+
+```swift
+private extension Message {
+    static func stub(
+        id: Message.ID = .init("message-1"),
+        subject: String = "Subject",
+        sender: Person = .stub()
+    ) -> Self {
+        Self(id: id, subject: subject, sender: sender)
+    }
+}
+```
+
+Test builders belong in test code. A test setup API never becomes a second model layer.
+
+## Style
+
+<!-- level: all -->
+
+- In XCTest, prefer throwing test methods with `try XCTUnwrap`.
+- In Swift Testing, prefer `try #require`.
+- Avoid `guard` in a test when an assertion helper states the failure directly.
+- Make test helpers and test data private unless several tests need them.
+
+## Disabled tests
+
+- Pass the reason to `XCTSkip` or `.disabled`. Name the issue, release, or platform version
+  that lets the test run again.
+- Delete a test that nobody plans to turn back on.
+
+## Time
+
+- Inject the clock, so a test advances time and never waits for it.
+
+## Snapshot and interface tests
+
+- Snapshot test reusable visual states and regressions that unit tests cannot cover.
+- Look at every reference image before committing it.
+- Keep each folder of references beside the test file it belongs to, and delete both together.
+- UI test critical navigation, authentication, submission, purchase, and recovery flows.
+
+Name Swift test files `<Type>Tests.swift`.

package/configurations/testing/vitest/eslint-presets.json

@@ -0,0 +1,22 @@
+{
+    "recommended": {
+        "package": "@vitest/eslint-plugin",
+        "version": "1.3.4",
+        "source": "configs.recommended",
+        "blocks": [
+            {
+                "parser": false,
+                "rules": {
+                    "vitest/expect-expect": "error",
+                    "vitest/no-identical-title": "error",
+                    "vitest/no-commented-out-tests": "error",
+                    "vitest/valid-title": "error",
+                    "vitest/valid-expect": "error",
+                    "vitest/valid-describe-callback": "error",
+                    "vitest/require-local-test-context-for-concurrent-snapshots": "error",
+                    "vitest/no-import-node-test": "error"
+                }
+            }
+        ]
+    }
+}

package/configurations/testing/vitest/manifest.toml

@@ -0,0 +1,69 @@
+allowed_words = ["Vitest"]
+
+[prefix_collisions]
+prefixes = ["vitest"]
+
+[configuration]
+title = "Vitest"
+requires = ["javascript", "coverage"]
+description = "Vitest test files: the test rules of ESLint over them, and coverage thresholds at push."
+
+[detect]
+dependencies = ["vitest"]
+
+[files]
+paths = ["**/vitest.config.*", "**/vitest.workspace.*"]
+
+[[tool]]
+name = "vitest"
+install_hint = "Run: npm install --save-dev vitest"
+system = true
+min_version = "2.0.0"
+npm = "vitest"
+
+[[tool]]
+name = "@vitest/eslint-plugin"
+rule_prefix = "vitest"
+kind = "library"
+version = "1.3.4"
+npm = "@vitest/eslint-plugin"
+
+[[tool]]
+name = "@vitest/coverage-v8"
+install_hint = "Run: npm install --save-dev @vitest/coverage-v8"
+kind = "library"
+system = true
+npm = "@vitest/coverage-v8"
+
+[[check]]
+name = "coverage"
+tool = ["vitest", "@vitest/coverage-v8"]
+example = "Vitest reports `ERROR: Coverage for lines (85%) does not meet global threshold (90%)`. Exercise the missing lines before the push check."
+level = "recommended"
+stage = "push"
+runs = "scope"
+cwd = "scope"
+command = ["vitest", "run", "--coverage", "--coverage.reporter=text-summary", "--coverage.thresholds.lines={setting:coverage.lines}", "--coverage.thresholds.branches={setting:coverage.branches}", "--coverage.thresholds.functions={setting:coverage.functions}", "--coverage.thresholds.statements={setting:coverage.statements}"]
+summary = "Runs the test suite with coverage, and fails when lines, branches, functions, or statements fall under their floors."
+why = "A floor keeps new code from arriving untested, which is when its behavior is cheapest to pin down."
+help = "Add tests for the code the coverage report shows uncovered, or lower one floor under coverage with a reason."
+
+[check.files]
+extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]
+
+[check.output]
+format = "regex"
+pattern = "^ERROR: (?<message>Coverage for .*)$"
+
+[eslint]
+all_level_rules = ["vitest/no-import-node-test", "vitest/prefer-strict-equal", "vitest/valid-title"]
+
+[eslint.presets.recommended]
+package = "@vitest/eslint-plugin"
+source = "configs.recommended"
+
+[[tool_file]]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+fragment = true
+required_tools = ["@vitest/eslint-plugin"]

package/configurations/testing/vitest/rules/VITEST.md

@@ -0,0 +1,18 @@
+# Vitest
+
+The general testing rules apply. Use the Vitest APIs for its runtime boundaries.
+
+- Use `vi.stubGlobal('fetch', ...)` or the project's interceptor to control external HTTP. Restore
+  stubbed globals through `vi.unstubAllGlobals()`.
+- Use `vi.mocked()` for typed access to a mocked dependency. A partial module mock calls
+  `importOriginal` when the unchanged exports still matter.
+- Restore fake timers with `vi.useRealTimers()` and mock implementations with `vi.restoreAllMocks()`.
+- Use `it.each` for one behavior across several inputs. Stop `describe()` nesting when it separates
+  no distinct behavior.
+
+```ts
+vi.mock('./email-client.js', async (importOriginal) => ({
+    ...(await importOriginal()),
+    sendEmail: vi.fn(),
+}));
+```