@schwabyio/gta 0.13.0 → 0.14.1

package/dist/SPEC.md

@@ -1,6 +1,7 @@
 # The Gravity file format
 
-Version 0.9
+Version 0.14.1, 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    | Reusable requests, 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,16 +91,17 @@ 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
 ├── environments/
 │   ├── local.yml
 │   └── staging.yml
-├── requests/                 request sets (§2.5)
+├── requests/                 reusable requests (§2.5)
 ├── endpoints/                endpoint bases (§2.6)
 ├── bases/                    base collections (§2.7)
 ├── checks/                   check files (§5)
@@ -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 reusable
+  requests, `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 reusable requests file'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 reusable requests file has `docs`.                                        |
+| `docs.steps`         | `required`             | Every step of a collection or reusable requests file 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 reusable requests files. 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 reusable
+requests file, 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 reusable requests files, 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
@@ -337,24 +496,24 @@ steps:
 
 Any key not listed here is an error.
 
-| Key        | Type                | Required | Default | Meaning                                                                        |
-| ---------- | ------------------- | -------- | ------- | ------------------------------------------------------------------------------ |
-| `id`       | string              | **yes**  |         | The file name without `.yml` (below).                                          |
-| `steps`    | list of steps       | no       | `[]`    | The requests, in run order (§2.1).                                             |
-| `setup`    | list of steps       | no       |         | Run once before `steps`; what it sets lasts the run (§2.10).                   |
-| `teardown` | list of steps       | no       |         | Run once after the rest, even when a step failed (§2.10).                      |
-| `docs`     | string              | no       |         | Markdown.                                                                      |
-| `tags`     | list of tags        | no       |         | Tags that select the whole collection (§2.4).                                  |
-| `stepTags` | boolean             | no       | `false` | `true` lets steps carry their own tags (§2.4).                                 |
-| `exclude`  | boolean             | no       | `false` | `true` leaves it out of group runs (§2.4).                                     |
-| `flags`    | map                 | no       |         | Feature flags the whole collection needs (§2.9).                               |
-| `headers`  | map                 | no       |         | Sent with every step; a step's own header of the same name wins (§2.3).        |
-| `settings` | map                 | no       |         | Defaults for every step (§2.3).                                                |
-| `vars`     | map of plain values | no       |         | Collection variables (§4).                                                     |
-| `before`   | map                 | no       |         | `script:` run before every step (§5).                                          |
-| `tests`    | string              | no       |         | JavaScript run after every step, before the step's own (§5).                   |
-| `extends`  | string              | no       |         | A base collection to build on (§2.7).                                          |
-| `params`   | map                 | no       |         | The inputs it takes as a request set (§2.5). Only in `requests/`, in practice. |
+| Key        | Type                | Required | Default | Meaning                                                                                   |
+| ---------- | ------------------- | -------- | ------- | ----------------------------------------------------------------------------------------- |
+| `id`       | string              | **yes**  |         | The file name without `.yml` (below).                                                     |
+| `steps`    | list of steps       | no       | `[]`    | The requests, in run order (§2.1).                                                        |
+| `setup`    | list of steps       | no       |         | Run once before `steps`; what it sets lasts the run (§2.10).                              |
+| `teardown` | list of steps       | no       |         | Run once after the rest, even when a step failed (§2.10).                                 |
+| `docs`     | string              | no       |         | Markdown.                                                                                 |
+| `tags`     | list of tags        | no       |         | Tags that select the whole collection (§2.4).                                             |
+| `stepTags` | boolean             | no       | `false` | `true` lets steps carry their own tags (§2.4).                                            |
+| `exclude`  | boolean             | no       | `false` | `true` leaves it out of group runs (§2.4).                                                |
+| `flags`    | map                 | no       |         | Feature flags the whole collection needs (§2.9).                                          |
+| `headers`  | map                 | no       |         | Sent with every step; a step's own header of the same name wins (§2.3).                   |
+| `settings` | map                 | no       |         | Defaults for every step (§2.3).                                                           |
+| `vars`     | map of plain values | no       |         | Collection variables (§4).                                                                |
+| `before`   | map                 | no       |         | `script:` run before every step (§5).                                                     |
+| `tests`    | string              | no       |         | JavaScript run after every step, before the step's own (§5).                              |
+| `extends`  | string              | no       |         | A base collection to build on (§2.7).                                                     |
+| `params`   | map                 | no       |         | The inputs it takes as a reusable requests file (§2.5). Only in `requests/`, in practice. |
 
 A collection has no `name` key. Its `id` is its name, and a file with `name:` is
 rejected with a message saying so.
@@ -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**:
@@ -388,29 +547,29 @@ key**, in capitals, whose value is the URL as a string.
 
 Methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
 
-| Key          | Type         | Required | Meaning                                                                   |
-| ------------ | ------------ | -------- | ------------------------------------------------------------------------- |
-| `<METHOD>`   | string       | **yes**  | The URL, query string included.                                           |
-| `name`       | string       | no       | Display name. Defaults to the method and URL.                             |
-| `headers`    | map          | no       | Over the collection's headers (§2.3).                                     |
-| `body`       | map          | no       | Exactly one kind of body (§2.2).                                          |
-| `settings`   | map          | no       | Over the collection's settings (§2.3).                                    |
-| `before`     | map          | no       | `script:` run before the request (§5).                                    |
-| `tests`      | string       | no       | The checks, as JavaScript: calls on `gta` (§3) and any other code (§5).   |
-| `tags`       | list of tags | no       | The step's own tags. Only with `stepTags: true` on the collection (§2.4). |
-| `flags`      | map          | no       | Feature flags the step needs (§2.9).                                      |
-| `forEach`    | string       | no       | Send the request once for each item of a list (below).                    |
-| `useTests`   | `true`       | no       | In a request set: the use step's `tests` check this response (§2.5).      |
-| `connection` | string       | no       | Keep the event stream this request opens as a connection (§2.11).         |
-| `base`       | `false`      | no       | `false` leaves the step's endpoint base out (§2.6).                       |
-| `docs`       | string       | no       | Markdown.                                                                 |
+| Key          | Type         | Required | Meaning                                                                         |
+| ------------ | ------------ | -------- | ------------------------------------------------------------------------------- |
+| `<METHOD>`   | string       | **yes**  | The URL, query string included.                                                 |
+| `name`       | string       | no       | Display name. Defaults to the method and URL.                                   |
+| `headers`    | map          | no       | Over the collection's headers (§2.3).                                           |
+| `body`       | map          | no       | Exactly one kind of body (§2.2).                                                |
+| `settings`   | map          | no       | Over the collection's settings (§2.3).                                          |
+| `before`     | map          | no       | `script:` run before the request (§5).                                          |
+| `tests`      | string       | no       | The checks, as JavaScript: calls on `gta` (§3) and any other code (§5).         |
+| `tags`       | list of tags | no       | The step's own tags. Only with `stepTags: true` on the collection (§2.4).       |
+| `flags`      | map          | no       | Feature flags the step needs (§2.9).                                            |
+| `forEach`    | string       | no       | Send the request once for each item of a list (below).                          |
+| `useTests`   | `true`       | no       | In a reusable requests file: the use step's `tests` check this response (§2.5). |
+| `connection` | string       | no       | Keep the event stream this request opens as a connection (§2.11).               |
+| `base`       | `false`      | no       | `false` leaves the step's endpoint base out (§2.6).                             |
+| `docs`       | string       | no       | Markdown.                                                                       |
 
 - A step with two method keys is an error, and so is a step with none, unless it is a
   use step or reads a connection.
 - **The URL is authoritative, query string included.** There is no separate block of
   query parameters. Editors show a parameter table as a view over the URL.
-- A step may instead run a request set with `use:` (§2.5). A use step has no method
-  key.
+- A step may instead run reusable requests with `use:` (§2.5). A use step has no
+  method key.
 - A step may also read a connection, an event stream an earlier step keeps open, with
   `connection:` and no method key (§2.11).
 - **Any other key is an error**, so a misspelled key such as `heders:` fails at once
@@ -504,13 +663,14 @@ declared multipart type without a boundary, such as `multipart/mixed`, gets one
 A declared boundary is used as written.
 
 **Files**, in `body.file` and a multipart part's `file`, are read from the folder of
-the project the step belongs to. For a step of a request set, that is the set's own
-project, which may be a global one. The path is the same wherever the collection sits
-inside `collections/`.
+the project the step belongs to. For a step of a reusable requests file, that is the
+file's own project, which may be a global one. The path is the same wherever the
+collection sits inside `collections/`.
 
-A file that is not there is looked for in the global project (§1.1), as a request set
-or a base collection is, so projects can share one copy of a file. A project's own file
-of the same path wins. `global:` before the path reads only the global project's:
+A file that is not there is looked for in the global project (§1.1), as a reusable
+requests file or a base collection is, so projects can share one copy of a file. A
+project's own file of the same path wins. `global:` before the path reads only the
+global project's:
 
 ```yaml
 body:
@@ -647,15 +807,16 @@ 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:`
+### 2.5 Reusable requests and `use:`
 
-A **request set** is a collection in `requests/`, directly or one directory down, with a
-`params:` key: the inputs it takes. A step elsewhere runs it with **`use:`**, and passes
-values with **`with:`**.
+**Reusable requests** are one or more requests that any step can run with **`use:`**,
+passing values with **`with:`**. They are written in a **reusable requests file**: a
+collection in `requests/`, directly or one folder down, with a `params:` key, the
+inputs it takes.
 
 ```yaml
 # requests/login.yml
@@ -700,39 +861,40 @@ values. No variable can take the place of a `params.` name.
 
 A default may name variables and other params, as in
 `email: '{{params.accountId}}@example.com'`. Like a `with:` value, it is resolved once
-for each use, so `accountId: '{{$uuid}}'` is one id wherever the set reads it.
+for each use, so `accountId: '{{$uuid}}'` is one id wherever the file reads it.
 
 **A use step** holds only `use`, `with`, `name`, `tags`, `flags`, `docs` and `tests`. A
 method key, `headers`, `body`, `settings` or `before` on it is an error, and `with`
 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
+- **Finding the file.** `use: login` is `requests/login.yml` in the project, else in its
+  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
+  `{{variables}}`, resolved as the file's first request starts, just after the
   collection's `before.script` has run for it: a value that script sets for each step
-  (§4) reaches the set. A missing required value, a name the set does not take, or a
-  value or default that cannot be resolved stops the set's steps before anything is
-  sent.
-- **Running.** A use step runs each of the set's steps in turn, in the collection's
+  (§4) reaches the file's requests. A missing required value, a name the file does not
+  take, or a value or default that cannot be resolved stops the file's steps before
+  anything is sent.
+- **Running.** A use step runs each of the file's steps in turn, in the collection's
   variable scope, so what one sets the next can read, and so can the steps after the use
   step. Each request is reported as its own result. When the use step has a `name`,
-  reports use it: `sign in` for a set of one step, `sign in › get profile` for a longer
+  reports use it: `sign in` for a file of one step, `sign in › get profile` for a longer
   one.
-- **Layers.** Headers and settings: the collection's, under the set's, under each
-  step's own. Scripts run collection, then set, then step: `before.script` before the
+- **Layers.** Headers and settings: the collection's, under the file's, under each
+  step's own. Scripts run collection, then file, then step: `before.script` before the
   request and `tests` after. The use step's own `tests` run last, on the response of
-  the set's step marked `useTests: true`, or else its last step. `params` is the set's
-  alone: the collection's scripts, and a base collection's or an endpoint's (§2.6,
-  §2.7), never see it. In an endpoint's `before.script`, a segment written as
+  the file's step marked `useTests: true`, or else its last step. `params` is the
+  file's alone: the collection's scripts, and a base collection's or an endpoint's
+  (§2.6, §2.7), never see it. In an endpoint's `before.script`, a segment written as
   `{{params.id}}` reads as written.
-- **One level.** A request set must not `use:` another, and has `params`, not `vars`. A
-  file in `requests/` without `params` is not a request set.
+- **One level.** A reusable requests file must not `use:` another, and has `params`,
+  not `vars`. A file in `requests/` without `params` is not a reusable requests file.
 
-**Saving under the caller's name.** A set can take the name to save a value under as a
-param, save it with `gta.set(params.saveAs, …)`, and read it back in its later steps
-with `{{@params.saveAs}}` (§4). The caller then reads it by the name it chose:
+**Saving under the caller's name.** A reusable requests file can take the name to save
+a value under as a param, save it with `gta.set(params.saveAs, …)`, and read it back in
+its later steps with `{{@params.saveAs}}` (§4). The caller then reads it by the name it
+chose:
 
 ```yaml
 # requests/create-user.yml
@@ -761,7 +923,8 @@ steps:
   headers: { Authorization: 'Bearer {{token1}}' }
 ```
 
-Only one step of a set may have `useTests`, and only a set's steps.
+Only one step of a reusable requests file may have `useTests`, and no other file's
+steps.
 
 ### 2.6 Endpoint bases
 
@@ -802,8 +965,8 @@ steps:
   `endpoint.id` is `42` for `{{baseUrl}}/users/{{userId}}` with `userId: 42`.
 - **What applies**, outermost first: the endpoints file's own `headers`, `settings`,
   `before` and `tests`, then the endpoint's, then the base collection's (§2.7), the
-  collection's, the request set's (§2.5) and the step's. Nearer headers and settings
-  win.
+  collection's, the reusable requests file's (§2.5) and the step's. Nearer headers and
+  settings win.
 - **A step's own check replaces the base's check of the same thing**: the status, a
   header by name, or a body property by path. A negative test only says what it expects,
   so checking for a 404 replaces the base's 200. Checks of other things stay, and named
@@ -872,7 +1035,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
@@ -902,8 +1066,8 @@ steps:
 ```
 
 - **Every flag named must have the value given.** A collection's `flags` apply to each
-  of its steps, and a use step's to each request of its set. Values compare as text, so
-  `true` matches `true` or `"true"`, and `2` matches `"2"`.
+  of its steps, and a use step's to each of its reusable requests. Values compare as
+  text, so `true` matches `true` or `"true"`, and `2` matches `"2"`.
 - **A step whose flags do not hold is skipped**, not failed. It sends nothing and is
   reported as skipped with the reason, such as `feature flag newCheckout is off`. A
   skipped step never fails a run.
@@ -987,7 +1151,8 @@ steps: # once per row of approved-domains.csv, as before
 - **The collection applies to them**: its headers, settings, `before`, `tests` and
   flags, as to any step. Their steps may be use steps and may use `forEach`, but carry
   no `tags`: they run whenever the collection does.
-- A request set, a base collection and an endpoints file have no setup or teardown.
+- A reusable requests file, a base collection and an endpoints file have no setup or
+  teardown.
 - Reports name their results `setup › log in` and `teardown › remove the grant`. Running
   a single step in the desktop app does not run them.
 
@@ -1160,6 +1325,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
@@ -1246,7 +1415,7 @@ to. Whitespace inside the braces is ignored. In code, read a variable with
 - **`{{@name}}` reads the variable `name` names.** With `saveAs: token1`,
   `{{@saveAs}}` is the value of `token1`. The name may itself be built from variables.
   A name that is not text, or names no variable, fails like an unknown variable. A
-  request set uses it to read what it saved under its caller's name (§2.5).
+  reusable requests file uses it to read what it saved under its caller's name (§2.5).
 - **In YAML, quote a value that starts with `{{`.** Unquoted, YAML reads `{` as a map.
 
 ### Built-in variables
@@ -1359,7 +1528,7 @@ military zone letter (`U` is -08:00, not UTC).
 | `req`      | `method`, `url`, `headers`, `body`: as sent in `tests`, as written in `before.script`, where a script may change `headers` and `body` (below).                                                                                              |
 | `assert`   | Node's strict `assert`, for use inside `gta.test`.                                                                                                                                                                                          |
 | `console`  | Captured into the step's result.                                                                                                                                                                                                            |
-| `params`   | A request set's params (§2.5), in its own scripts and in the tests of the use step running it.                                                                                                                                              |
+| `params`   | A reusable requests file's params (§2.5), in its own scripts and in the tests of the use step running it.                                                                                                                                   |
 | `endpoint` | An endpoint base's `{name}` values (§2.6), in its scripts and in every script of a step under it.                                                                                                                                           |
 | `checks`   | The project's check files (below).                                                                                                                                                                                                          |
 
@@ -1403,7 +1572,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 +1637,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 +1683,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**
 
@@ -1536,7 +1709,8 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
 - There is no `expect:` key; checks go in `tests`.
 - `base` is only ever `false`.
 - `forEach` is a string, and a use step has none.
-- `useTests` is only ever `true`, only on a request set's step, and on one step at most.
+- `useTests` is only ever `true`, only on a reusable requests file's step, and on one
+  step at most.
 - A step reading a connection has no `headers`, `body`, `base` or `forEach`. A step
   opening one has no `forEach`, and a use step has no `connection` (§2.11).
 
@@ -1561,13 +1735,14 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
 
 **Library files**
 
-- A request set (`requests/`) has `params`, uses no other set, and has no `vars`.
+- A reusable requests file (`requests/`) has `params`, uses no other, and has no
+  `vars`.
 - A base collection (`bases/`) has no `steps`, `setup`, `teardown` or `params`, and no
   `extends`.
 - 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 +1753,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 +1762,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**
 
@@ -1597,7 +1775,7 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
   seconds, printing a JSON object.
 - Every file a body names can be read from the project folder, or its global
   project's (§2.2).
-- Every `use:` and `extends:` names a usable file, and every `with:` suits its set.
+- Every `use:` and `extends:` names a usable file, and every `with:` suits its file.
   `gta get` checks these, and the body files named without `{{variables}}`, without
   running anything (§1.3).
 - A step's `forEach` resolves to a JSON array.