@schwabyio/gta 0.13.0 → 0.14.0

package/README.md

@@ -23,7 +23,7 @@ The package has no dependencies to install: everything `gta` uses is bundled int
 
 ## A first project
 
-A project is a folder holding a `collections/` directory, an `environments/` one and a
+A project is a folder holding a `collections/` folder, an `environments/` one and a
 `settings.yml`. The smallest project `gta` runs is three files:
 
 ```yaml
@@ -139,6 +139,43 @@ In a monorepo, projects that share a global project (`uses:` in `project.yml`) s
 setting by setting it again in its own file. Each project still needs a `settings.yml`,
 even an empty one.
 
+## Project rules
+
+A `rules.yml` beside `project.yml` writes down how a project's files are named, laid out
+and written, so everyone working on it, people and coding agents alike, keeps it the
+same:
+
+```yaml
+# rules.yml
+ids:
+  collections: kebab-case # or a pattern, such as '{folder}-[a-z0-9-]+'
+layout:
+  folders: required # every collection in a folder of collections/
+docs:
+  collections: required
+tags:
+  allowed: [smoke, regression]
+steps:
+  names: required
+tests:
+  only: [gta] # tests call the gta.* functions, and nothing else
+  statusCode: required
+guide: |
+  Name each step for what it proves.
+```
+
+```sh
+gta rules                        # the rules in effect, where each came from, what each means, the guide
+gta lint                         # check every file against them
+gta lint --json                  # the findings as JSON, for tools and agents
+```
+
+`gta lint` prints each finding at its file and line, with the rule it breaks, and exits
+`1` when it finds one. Rules never change a run: a file that breaks one still runs. A
+global project's `rules.yml` is shared like its `settings.yml`, and a project changes or
+turns off (`null`) any rule in its own file. Every rule is in
+[SPEC.md §1.4](https://github.com/schwabyio/gravity/blob/main/SPEC.md#14-rulesyml).
+
 ## In CI
 
 ```yaml
@@ -147,11 +184,113 @@ even an empty one.
   with:
     node-version: 22
 - run: npm install -g @schwabyio/gta
+- run: gta lint
 - run: gta all --environmentType staging --generateJUnitResults
   env:
     apiKey: ${{ secrets.STAGING_API_KEY }}
 ```
 
+## From Playwright and other code
+
+The package is also a library. A test written in code can run a collection or a request
+set, then use the values it saved, such as a token or the id of a user it created, in a
+browser test.
+
+### Playwright
+
+`@schwabyio/gta/playwright` gives you Playwright's `test` with a `gta` fixture. Point it
+at the project in `playwright.config.ts`:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test'
+import type { GravityConfig } from '@schwabyio/gta/playwright'
+
+export default defineConfig<{}, GravityConfig>({
+  use: {
+    gravity: { project: '../api-tests', environment: 'staging' }
+  }
+})
+```
+
+```ts
+// tests/dashboard.spec.ts
+import { test, expect } from '@schwabyio/gta/playwright'
+
+test('a new user sees their dashboard', async ({ page, gta }) => {
+  // requests/create-user.yml, run as a use: step would run it
+  const user = await gta.use('create-user', { plan: 'pro' })
+
+  await page.goto(`/users/${user.values.userId}`)
+  await expect(page.getByRole('heading')).toHaveText('Welcome')
+
+  // collections/billing.yml, starting from what create-user saved
+  await gta.run('billing', { vars: user.values })
+})
+```
+
+- Each `gta.run` and `gta.use` call is a step in Playwright's report. Each request is a
+  step inside it, linked to its step in the YAML, with the request and response attached.
+- A run that fails fails the test at the line that called it, with what failed. With
+  `soft: true` the test goes on and fails at the end, as `expect.soft` does.
+- `project` is relative to the folder `playwright.config.ts` is in, and defaults to it.
+  `environment`, `flags`, `bail` and `timeoutCollection` go beside it. The project opens
+  once per worker, so an environment's flag command runs once per worker.
+- A run counts toward the test's timeout, and one still going when the test ends is
+  stopped.
+- To use this `test` with fixtures of your own, combine them with Playwright's
+  `mergeTests`.
+
+It needs `@playwright/test` 1.51 or later, which installing `gta` does not install.
+
+### Any other code
+
+```js
+import { openProject } from '@schwabyio/gta'
+
+const project = await openProject('api-tests', { environment: 'staging' })
+const login = await project.use('login', { username: 'alice' })
+const checkout = await project.run('checkout', { vars: login.values })
+if (!checkout.passed) throw new Error(checkout.failures)
+```
+
+**`openProject(folder, options)`** opens the project in `folder`, the one holding
+`collections/`. The options are `environment`, `flags`, `bail` and `timeoutCollection`.
+Each one you leave out comes from `settings.yml`, the same way `gta` reads it, but here
+the project does not need a `settings.yml`.
+
+**`project.run(collection, options)`** runs a collection the way `gta` runs it: setup,
+then the steps once for each data row, then teardown. Name the collection by its id or
+its place in `collections/` (`checkout/sessions`). `tags` and `notTags` don't apply,
+since you name what runs, and a collection with `exclude: true` runs too. The options:
+
+| Option     | What it does                                                                                                                         |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `steps`    | Run only these steps, named as reports name them or numbered from 1. They run in the file's order, and setup and teardown still run. |
+| `vars`     | Values the run starts with. They sit over the environment and under a data row.                                                      |
+| `bail`     | Stop at the first failing step.                                                                                                      |
+| `signal`   | An `AbortSignal` that stops the run.                                                                                                 |
+| `onResult` | `(result, step) => void`, called as each request finishes.                                                                           |
+
+**`project.use(set, params, options)`** runs a request set as a `use:` step would:
+`login` is `requests/login.yml`, in the project or its global project. `params` are what
+`with:` gives, and a param you leave out takes its default. The options are those of
+`run`, without `steps`.
+
+Both resolve to the same outcome, however the steps fare:
+
+| Field      | What it holds                                                                                                                                                   |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `passed`   | `true` when nothing failed or errored and the run finished.                                                                                                     |
+| `values`   | Every value the run set or captured, by name: `gta.set`, and checks that save what they read, such as `'setAsCollectionVariable'`. Secrets are not hidden here. |
+| `summary`  | Totals, and every request's result as gta's JSON report holds it, with secrets shown as `[secret: NAME]`.                                                       |
+| `steps`    | Where each result's step is: its file and line.                                                                                                                 |
+| `failures` | What went wrong, as `gta` prints it under Failures. Empty when the run passed.                                                                                  |
+| `error`    | Why the run did not start or finish: a file that will not load, `timeoutCollection`, or a cancel. Otherwise `null`.                                             |
+
+They reject only when a collection, step or request set doesn't exist, or a value isn't a
+string, number, boolean or null. Types ship with the package.
+
 ## The file format
 
 [SPEC.md](https://github.com/schwabyio/gravity/blob/main/SPEC.md) specifies every file,

package/dist/FUNCTIONS.md

@@ -216,8 +216,11 @@ gta.expectResponseBodyToHaveUnorderedArray('users', [{ name: 'Ada' }, { name: /^
 ```
 
 An object in the list matches an item holding each of its properties with that value, or
-matching it when the value is a `RegExp`. The item may have others. A pattern is tested
-against the value as text, so it never matches an item that is an object or an array.
+matching it when the value is a `RegExp`. The item may have others. A property that is
+itself an object is matched the same way, so `{ data: { status: 'reversed' } }` finds an
+item whose `data` has that status, whatever else `data` holds. An array compares whole.
+A pattern is tested against the value as text, so it never matches an item that is an
+object or an array.
 
 **A list of `{ pathToProperty, expectedValue, specialHandling? }` entries.** Together
 they describe **one** item, property by property, and some item must match every entry.

package/dist/SPEC.md

@@ -1,6 +1,7 @@
 # The Gravity file format
 
-Version 0.9
+Version 0.14.0, the version of Gravity and `gta` that reads it: the two are released
+together.
 
 This document specifies the YAML files that **Gravity**, the desktop app, and **`gta`**,
 the command-line runner, read and write. Together they make up Gravity Test
@@ -26,18 +27,19 @@ is a complete, valid project to start from.
 
 ## At a glance
 
-| File                          | Where                                      | What it is                                  | §    |
-| ----------------------------- | ------------------------------------------ | ------------------------------------------- | ---- |
-| `collections/<id>.yml`        | `collections/`, or one directory inside it | A collection: requests run in order         | §2   |
-| `collections/<id>.csv\|.json` | Beside its collection                      | A data file: the collection runs once a row | §2.8 |
-| `environments/<name>.yml`     | `environments/`                            | Variables, secrets and flags for one target | §6   |
-| `project.yml`                 | The project folder                         | Name, global project, variables, trust      | §1.1 |
-| `settings.yml`                | The project folder                         | How `gta` runs the project                  | §1.3 |
-| `requests/<id>.yml`           | `requests/`, or one directory inside it    | A request set, run by `use:`                | §2.5 |
-| `endpoints/<id>.yml`          | `endpoints/`, or one directory inside it   | Defaults and checks per method and path     | §2.6 |
-| `bases/<id>.yml`              | `bases/`, or one directory inside it       | A base collection, for `extends:`           | §2.7 |
-| `checks/<name>.js`            | `checks/`                                  | Shared check functions                      | §5   |
-| `.env`                        | The project folder, never committed        | Values for secrets                          | §6   |
+| File                          | Where                                   | What it is                                  | §    |
+| ----------------------------- | --------------------------------------- | ------------------------------------------- | ---- |
+| `collections/<id>.yml`        | `collections/`, or one folder inside it | A collection: requests run in order         | §2   |
+| `collections/<id>.csv\|.json` | Beside its collection                   | A data file: the collection runs once a row | §2.8 |
+| `environments/<name>.yml`     | `environments/`                         | Variables, secrets and flags for one target | §6   |
+| `project.yml`                 | The project folder                      | Name, global project, variables, trust      | §1.1 |
+| `settings.yml`                | The project folder                      | How `gta` runs the project                  | §1.3 |
+| `rules.yml`                   | The project folder                      | How the project's files are written         | §1.4 |
+| `requests/<id>.yml`           | `requests/`, or one folder inside it    | A request set, run by `use:`                | §2.5 |
+| `endpoints/<id>.yml`          | `endpoints/`, or one folder inside it   | Defaults and checks per method and path     | §2.6 |
+| `bases/<id>.yml`              | `bases/`, or one folder inside it       | A base collection, for `extends:`           | §2.7 |
+| `checks/<name>.js`            | `checks/`                               | Shared check functions                      | §5   |
+| `.env`                        | The project folder, never committed     | Values for secrets                          | §6   |
 
 The smallest project `gta` runs is three files:
 
@@ -89,9 +91,10 @@ A **project** is a folder holding `collections/` and, usually, `environments/`:
 payments/                     a project
 ├── project.yml               optional (§1.1)
 ├── settings.yml              how gta runs it (§1.3)
+├── rules.yml                 how its files are written (§1.4)
 ├── collections/
 │   ├── smoke.yml             a collection
-│   └── checkout/             a directory grouping collections: one level only
+│   └── checkout/             a folder grouping collections: one level only
 │       ├── sessions.yml
 │       ├── sessions.csv      its data file (§2.8)
 │       └── refunds.yml
@@ -106,17 +109,17 @@ payments/                     a project
 └── .env                      secret values; not committed (§6)
 ```
 
-**Every `.yml` file directly in `collections/`, or in a directory one level down, is a
+**Every `.yml` file directly in `collections/`, or in a folder one level down, is a
 collection.** Nothing else is. Discovery is exact: no other `.yml` in a repository is
 mistaken for a collection. A file that does not parse is reported as a broken
 collection, never skipped in silence.
 
-- A directory inside a directory of `collections/` is reported as a problem and not
+- A folder inside a folder of `collections/` is reported as a problem and not
   read. `requests/`, `endpoints/` and `bases/` are read to the same depth, and
   `checks/` only at its top level.
-- Names starting with `.` are ignored, as are the directories `node_modules`, `.git`,
+- Names starting with `.` are ignored, as are the folders `node_modules`, `.git`,
   `reports`, `test-results`, `out` and `dist`.
-- Directories carry no configuration and need no file of their own. They group
+- Folders carry no configuration and need no file of their own. They group
   collections for display and for running a group.
 
 A project is any folder: the root of a repository, or one service of a monorepo. A
@@ -160,8 +163,8 @@ The file is optional, and so is every key in it. Any other key is an error.
 | `tls.ca` | list of relative paths | none        | Certificate files that requests trust (below).        |
 
 **`uses`** names a **global project**: an ordinary project whose `project.yml`
-variables, `environments/`, `requests/`, `endpoints/`, `bases/`, `checks/` and
-`settings.yml` every project using it shares.
+variables, `environments/`, `requests/`, `endpoints/`, `bases/`, `checks/`,
+`settings.yml` and `rules.yml` every project using it shares.
 
 - It must be a relative path. An absolute path is refused, since it would only work on
   one machine. Write it with `/`; `\` reads the same.
@@ -170,7 +173,15 @@ variables, `environments/`, `requests/`, `endpoints/`, `bases/`, `checks/` and
 - An environment in the global project merges under the project's environment of the
   same name, key by key, and the project's values win. An environment only the global
   project has is available too.
-- The global project's `settings.yml` lies under the project's the same way (§1.3).
+- The global project's `settings.yml` lies under the project's the same way (§1.3), and
+  so does its `rules.yml` (§1.4).
+- A global project's own `collections/` is **not** shared: a project using it never
+  sees or runs those collections. A global project needs none. It may have one for a
+  single purpose: **testing what it shares**. A collection there can `use:` its request
+  sets, `extends:` its bases and call its checks, against its own environments, so a
+  broken shared piece fails in one place, before every project relying on it does.
+  Those collections run only when the global project itself does, as a project in
+  Gravity or with `gta` in its folder, such as its own CI job.
 
 **`tls.ca`** lists certificate files that requests trust, for a server whose certificate
 a company or local CA signed, or a server's own self-signed certificate. A request
@@ -203,11 +214,11 @@ Projects are shared between macOS, Windows and Linux, and read the same on all t
   `use:` or `extends:` name, `uses`, a `tls.ca` file, a file a body sends, and an
   environment's file name. One that differs only in case is an error on every platform,
   naming the spelling on disk. The folders and files of §1 are lower case.
-- **No two names in one directory may differ only in case**, such as `Checkout/` and
+- **No two names in one folder may differ only in case**, such as `Checkout/` and
   `checkout/`: Linux can hold both, but a macOS or Windows checkout only one. This
   applies in `collections/`, `requests/`, `endpoints/`, `bases/`, `environments/` and
   `checks/`. Collection ids are unique ignoring case too (§2).
-- File, directory and environment names must avoid what Windows refuses: the characters
+- File, folder and environment names must avoid what Windows refuses: the characters
   `< > : " / \ | ? *`, control characters, a trailing dot or space, and the names `CON`,
   `PRN`, `AUX`, `NUL`, `CONIN$`, `CONOUT$`, `COM1`–`COM9` and `LPT1`–`LPT9`, with or
   without an extension. A file with such a name, made on macOS or Linux, is reported.
@@ -282,7 +293,7 @@ global project's `settings.yml`, the project's, the environment variable, the fl
 | --------------------- | ----------------------------------------------------------- |
 | `gta get`             | Nothing. It lists what `gta all` would run.                 |
 | `gta all`             | Every collection, except those with `exclude: true` (§2.4). |
-| `gta smoke,checkout/` | The collections and directories named, in that order.       |
+| `gta smoke,checkout/` | The collections and folders named, in that order.           |
 
 `gta get` also reports each `use:` and `extends:` that would stop a run, and each file a
 body names that is in neither the project nor its global project (§2.2), in every
@@ -290,11 +301,159 @@ collection, including those `gta all` leaves out (Appendix A). A file path with
 `{{variables}}` is left to the run. It exits `1` when it finds one, or a broken
 collection, and `0` otherwise.
 
-A collection is named by its `id`, or by its place (`checkout/sessions`). A directory is
-named by its name, and `checkout/` names only the directory. `--flag name=value` sets a
+A collection is named by its `id`, or by its place (`checkout/sessions`). A folder is
+named by its name, and `checkout/` names only the folder. `--flag name=value` sets a
 feature flag (§2.9), and `--json` prints the results as JSON. The exit code is `0` when
 everything passed, `1` when something failed, and `2` when `gta` could not run.
 
+### 1.4 `rules.yml`
+
+How a project's files are named, laid out and written, so that everyone working on it,
+people and coding agents alike, keeps it consistent. It sits beside `project.yml`, is
+committed, and is optional. `gta lint` checks the project against it. Gravity, the
+desktop app, marks each file, folder and step that breaks a rule, and will not create or
+rename a file or folder that would.
+
+```yaml
+ids:
+  collections: kebab-case # or a pattern, such as '{folder}-[a-z0-9-]+'
+  requests: camelCase
+layout:
+  folders: required # every collection in a folder of collections/
+  folderNames: [accounts, payments, smoke]
+  maxSteps: 30
+steps:
+  names: required
+  url: ^\{\{baseUrl\}\} # no host written out
+docs:
+  collections: required
+tags:
+  allowed: [smoke, regression, slow]
+tests:
+  only: [gta] # tests call the gta.* functions, and nothing else
+  statusCode: required
+guide: |
+  Name each step for what it proves. Logins go through `requests/login`.
+```
+
+**Rules never change a run.** A file that breaks one opens, sends and runs as before.
+`gta lint` reports it, and a CI job running `gta lint` fails on it. Gravity marks it, and
+flags what `tests.only` does not allow as a script is typed.
+
+| Rule                 | Value                  | What it checks                                                            |
+| -------------------- | ---------------------- | ------------------------------------------------------------------------- |
+| `ids.collections`    | style or pattern       | Each collection's id, its file name (§2).                                 |
+| `ids.requests`       | style or pattern       | Each request set's id (§2.5).                                             |
+| `ids.bases`          | style or pattern       | Each base collection's id (§2.7).                                         |
+| `ids.endpoints`      | style or pattern       | Each endpoints file's id (§2.6).                                          |
+| `layout.folders`     | `required`             | Every collection sits in a folder of `collections/`, none at its top.     |
+| `layout.folderNames` | list, style or pattern | Each folder of `collections/`: one of the list, or following the format.  |
+| `layout.maxSteps`    | integer ≥ 1            | The most steps a collection has in `steps`; `setup` and `teardown` aside. |
+| `steps.names`        | `required`             | Every step has a `name`, and no other step of its file has the same one.  |
+| `steps.url`          | pattern                | Every request step's URL, as written, matches it (below).                 |
+| `docs.collections`   | `required`             | Every collection has `docs`.                                              |
+| `docs.requests`      | `required`             | Every request set has `docs`.                                             |
+| `docs.steps`         | `required`             | Every step of a collection or request set has `docs`, in every list.      |
+| `tags.allowed`       | list of tags           | Every tag on a collection or a step is one of these.                      |
+| `tags.collections`   | `required`             | Every collection has `tags` of its own.                                   |
+| `tests.only`         | list (below)           | What a `tests` script may call.                                           |
+| `tests.everyStep`    | `required`             | Every step that sends a request or reads a connection is checked (below). |
+| `tests.statusCode`   | `required`             | Every request step's checks include its status code (below).              |
+
+- Any other group or rule is an error, as is a value of the wrong type.
+- A rule that takes `required` also takes `optional`, which turns it off.
+- A **style** is one of `kebab-case` (`create-user`), `snake_case` (`create_user`),
+  `camelCase` (`createUser`) and `PascalCase` (`CreateUser`). Lower case, in the first two,
+  includes digits: `404-handling` is kebab-case.
+- A **pattern** is a JavaScript regular expression that the whole name must match, as if
+  it began with `^` and ended with `$`. `{folder}` in it stands for the folder the file is
+  in, so `{folder}-[a-z0-9-]+` asks for `collections/payments/payments-refunds.yml`. A
+  value that is not a style and has none of a pattern's characters (`^`, `$`, `.`, `*`,
+  `+`, `?`, `(`, `)`, `[`, `]`, `{`, `}`, `|` or a backslash) is an error, so a
+  misspelled style is not taken for a pattern.
+- Rules check the project's own files, in `collections/`, `requests/`, `bases/` and
+  `endpoints/`. A global project's files follow the global project's `rules.yml`, checked
+  when `gta lint` runs in its folder.
+- `steps.*`, `docs.steps`, `tests.everyStep` and `tests.statusCode` are about the steps of
+  collections and request sets. An endpoint is a method and a path pattern, not a step
+  that runs, so they leave endpoints files alone.
+
+**`steps.url`** is a JavaScript regular expression that each request step's URL, as
+written with its `{{variables}}`, must match. Unlike an id pattern it is not anchored:
+`^\{\{baseUrl\}\}` asks that every URL start with `{{baseUrl}}`, so no host is written
+out in a step. A use step and a step reading a connection have no URL of their own.
+
+**`tests.everyStep` and `tests.statusCode`** count every script that runs after a step's
+response, wherever it is written: the step's own `tests`, its file's, its base
+collection's (§2.7) and its endpoint's (§2.6), unless the step has `base: false`. With
+`tests.statusCode`, one of them calls `gta.expectResponseStatusCodeToBe`, in any branch,
+or calls a check function (§5) whose own code does. A use step is left to its request
+set, whose steps are checked there. A step reading a connection needs tests under
+`tests.everyStep`, but has no status code of its own to check.
+
+**`tests.only`** lists what a `tests` script may call. It must list `gta`:
+
+| Entry      | Allows                                                    |
+| ---------- | --------------------------------------------------------- |
+| `gta`      | The `gta.*` functions (§5), except `gta.test`.            |
+| `gta.test` | Named checks of your own, with any code inside them (§5). |
+| `checks`   | The project's check files, `checks.<file>.<function>()`.  |
+| `console`  | `console.log()` and the rest.                             |
+
+With `only: [gta]`, a `tests` script holds calls to `gta.*` functions and nothing else:
+
+- **Every argument is a value**: a string, number, `true`, `false`, `null` or regular
+  expression, a template string, a list or object of values, or `new RegExp(…)` of
+  values. It may read `res`, `req`, `params`, `endpoint` and `item` (§5), call another
+  `gta.*` function such as `gta.get('id')`, or `JSON.parse` a value, since `gta.set` keeps
+  a list or object as JSON text.
+- **An `if` may choose by feature flag** (§2.9): its condition is `gta.flag()` calls
+  compared with values, joined by `!`, `&&` and `||`, and what it holds follows the same
+  rules.
+- **Nothing else**: no variables, loops, functions of your own, `assert`, `checks.*` or
+  `gta.test`. This is checked on the script's syntax, so a call cannot be hidden by
+  renaming it (`const c = checks`).
+
+```yaml
+tests: |
+  gta.expectResponseStatusCodeToBe(200)
+  gta.expectResponseBodyToHaveProperty('owner', gta.get('userId'))
+  gta.set('nextPage', res.body.links.next)
+  if (gta.flag('newCheckout') === true) {
+    gta.expectResponseBodyToHaveProperty('version', 2)
+  }
+```
+
+`tests.only` checks every `tests` script: a collection's own and each of its steps', and
+those of request sets, base collections and endpoints files. `before.script` is not
+checked.
+
+**`guide`** is Markdown, for what no rule can check: how steps are named, which request
+set a login goes through, what a collection is for. `gta rules` prints it after the
+rules, and Gravity shows it in Project settings. Each file's guide is read, the global
+project's first, so a project adds to a shared guide rather than replacing it.
+
+**From the global project.** A global project (§1.1) can have a `rules.yml` too, and it
+lies under the project's, rule by rule. There is no switch to turn this off: a project
+changes a shared rule by setting it in its own file, and turns it off with `null`, or
+`optional` for a `required` rule. A group set to `null`, such as `tags: null`, turns off
+every rule in it. Neither file is required.
+
+**Checking.** From a project folder, or a global project's:
+
+| Command     | Does                                                                                                                                                      |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gta lint`  | Checks every file against the rules, and prints each finding at its file and line, with its rule and the file the rule came from. Exits `1` on a finding. |
+| `gta rules` | Lists each rule set, its value, the file it came from and what it means, rules turned off included, then the guide.                                       |
+
+- Neither needs `settings.yml` or runs anything, and both take `--json`.
+- A file that will not parse is a finding, since no rule could be checked in it.
+- Both exit `2` when a rule is not valid, or `project.yml` names a global project that
+  cannot be used: its rules would quietly go unchecked.
+- A coding agent can run `gta rules` to learn a project's conventions before writing, and
+  `gta lint --json` after, to fix what it finds. Gravity offers to add a section saying so
+  to the project's `AGENTS.md`, which coding agents read; nothing is written until asked.
+
 ---
 
 ## 2. Collection file
@@ -367,7 +526,7 @@ exactly. `collections/checkout/sessions.yml` starts `id: sessions`.
 - **It must match the file name.** A file whose `id` is missing or different is a
   broken collection. Renaming a file means changing its `id` too.
 - **It must be unique in its home, ignoring case.** No two files in a project's
-  `collections/` may share an id, including files in different directories of it; the
+  `collections/` may share an id, including files in different folders of it; the
   same holds for `requests/`, `bases/` and `endpoints/`. Case is ignored because macOS
   and Windows file systems ignore it. Every file sharing an id is broken.
 - **It is letters, digits and `- _ .`, starting with a letter or digit**:
@@ -647,13 +806,13 @@ else selects it. With `stepTags: true`, its steps whose tags match are dropped f
 was selected.
 
 **`exclude: true`** leaves a collection out of group runs: `gta all`, with or without
-tags, and a directory named to `gta`. Named on its own, it still runs. Use it for work in
+tags, and a folder named to `gta`. Named on its own, it still runs. Use it for work in
 progress, a manual-only collection, or one waiting on a fix. `gta` lists what it left
 out, so a suite never shrinks without saying so.
 
 ### 2.5 Request sets and `use:`
 
-A **request set** is a collection in `requests/`, directly or one directory down, with a
+A **request set** is a collection in `requests/`, directly or one folder down, with a
 `params:` key: the inputs it takes. A step elsewhere runs it with **`use:`**, and passes
 values with **`with:`**.
 
@@ -707,7 +866,7 @@ method key, `headers`, `body`, `settings` or `before` on it is an error, and `wi
 without `use` is an error too.
 
 - **Finding the set.** `use: login` is `requests/login.yml` in the project, else in its
-  global project. `use: auth/login` is one directory down. `use: global:login` looks
+  global project. `use: auth/login` is one folder down. `use: global:login` looks
   only in the global project.
 - **`with:`** gives plain values; a param left out takes its default. A string may hold
   `{{variables}}`, resolved as the set's first request starts, just after the
@@ -872,7 +1031,8 @@ userId,expectedStatus,iterationLabel
   string**: a zip code `01234` stays `01234`. A short row leaves its last columns empty;
   a row with more values than the header is an error.
 - **JSON** is an array of objects, one per row. Values keep their type, which must be
-  string, number, boolean or null.
+  string, number, boolean or null. A row must not name a column twice: JSON readers keep
+  only the last value, so it is an error rather than a value quietly lost.
 - **`.csv` wins** when both exist. The name must match exactly, case included.
 - A data file must be at most 10 MB and have at least one row. The header must not have
   an empty or repeated column name. A data file that will not read makes the collection
@@ -1160,6 +1320,10 @@ saying so, and the checks after it still run.
 every item of a simple `list`, in any order. A `RegExp` in the list is a pattern some item
 must match as text, and so is one held by an object in the list:
 `[/^admin/, { name: /^Grace/ }]`. A pattern never matches an object or array item.
+An object in the list matches an item holding each of its properties, and the item may
+have others; a property that is itself an object is matched the same way, so
+`{ data: { status: 'reversed' } }` finds an item whose `data` has that `status` among
+other properties. An array compares whole.
 
 A list of `{ pathToProperty, expectedValue, specialHandling? }` objects describes **one**
 item, property by property; call it once per item. A property may appear twice, once to
@@ -1403,7 +1567,10 @@ delete req.headers['X-Debug']
 
 - `req.body` is text, and can be changed for a `json`, `xml`, `text` or `graphql` body.
   A form, multipart or file body is built from its parts, so it cannot.
-- `req.headers` is a map of names to values: add, change or delete them.
+- `req.headers` is a map of names to values: add, change or delete them. A header sent
+  more than once reads as its values joined with `, `, as `res.headers` does, and is
+  still sent once per value unless the script changes it. Set an array to send one
+  header per value.
 - Variables in what the script writes resolve afterwards, as in the file.
 - Anything else is a pre-request error, and nothing is sent.
 
@@ -1465,7 +1632,8 @@ global project's root.
 - A secret with no value anywhere fails the run, naming it. An empty credential is never
   sent.
 - Reports replace a secret's value with `[secret: NAME]`, wherever it appears. So does
-  the desktop app where it shows a request as sent.
+  the desktop app where it shows a request as sent, or what a script wrote with
+  `console`.
 - `.env` holds `NAME=value` lines. `#` starts a comment line, `export ` before a name is
   allowed, and a value may be quoted. It must not be committed.
 
@@ -1510,7 +1678,7 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
 - It must be YAML that parses, holding a mapping, in a file ending in `.yml`.
 - Unknown keys are errors in: a collection's top level, a step, `settings`, `before`,
   `body`, `project.yml`, `tls`, an environment file, an environment's `flags`, a param
-  spec and `settings.yml`.
+  spec, `settings.yml` and `rules.yml`.
 
 **Collections**
 
@@ -1567,7 +1735,7 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
 - An endpoint (`endpoints/`) has a URL that is a path starting with `/`, and no use
   steps or connections. An endpoints file has no `setup` or `teardown`.
 - A check file's name is a JavaScript identifier; if it isn't, the file is not loaded.
-- `collections/`, `requests/`, `endpoints/` and `bases/` hold files at most one directory
+- `collections/`, `requests/`, `endpoints/` and `bases/` hold files at most one folder
   down.
 
 **Portability (§1.2)**
@@ -1578,7 +1746,7 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
   `Collections/`.
 - No two names in `collections/`, `requests/`, `endpoints/`, `bases/`, `environments/`
   or `checks/` differ only in case.
-- No file or directory name is one Windows refuses.
+- No file or folder name is one Windows refuses.
 
 **Projects**
 
@@ -1587,6 +1755,9 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
 - Each `tls.ca` file exists and holds a PEM or DER certificate.
 - `settings.yml` exists for `gta`; a global project's is optional. The `environmentType`
   a run ends up with, if any, names an environment that exists.
+- In `rules.yml`, each rule has a value of the type §1.4 gives it, a pattern compiles,
+  `tests.only` lists `gta`, and `guide` is a string. What breaks a rule is a finding of `gta lint`, never an
+  error: it stops nothing (§1.4).
 
 **At run time**
 

package/dist/THIRD_PARTY_NOTICES.txt

@@ -2,6 +2,32 @@ gta bundles the following packages. Each is used under the license that follows
 
 --------------------------------------------------------------------------------
 
+acorn 8.18.0 (MIT)
+
+MIT License
+
+Copyright (C) 2012-2022 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
 undici 8.10.2 (MIT)
 
 MIT License