document the .tap folder

Fix: #944

src/docs/content/changelog.md

@@ -99,6 +99,8 @@ Major rewrite.
 - Assertion aliases moved to the optional `@tapjs/synonyms`
   plugin (so no longer deprecated, but opt-in)
 - Dropped support for node 14 and earlier.
+- Probably good idea to [add `/.tap` to your `.gitignore`
+  file](./dot-tap-folder.md)
 
 ### CLI
 

src/docs/content/dot-tap-folder.md

@@ -0,0 +1,105 @@
+---
+title: The .tap Folder
+eleventyNavigation:
+  key: .tap Folder
+  parent: Docs
+  order: 47
+---
+
+> _tl;dr_ - Tap puts stuff in `.tap`. It's probably best to
+> `.gitignore` this folder.
+
+The `.tap` folder is used to store various things that tap uses.
+
+## `.tap/processinfo`
+
+Every process that is spawned in the course of running tests is
+assigned a UUID and information about it is stored for later
+analysis. This is used by tap to be able to know which tests need
+to be re-run when you do `tap --changed`, for example.
+
+The data is created by
+[`@tapjs/processinfo`](https://github.com/tapjs/processinfo).
+Each of the files in this folder have a filename corresponding to
+the uuid, and contain a JSON-encoded
+[`ProcessInfoNodeData`](https://tapjs.github.io/processinfo/interfaces/process_info_node.ProcessInfoNodeData.html)
+object.
+
+These nodes have a `root` and `parent` fields, creating a tree
+structure of processes. You can explore the tree by using the `i`
+command in the [REPL](./repl.md).
+
+```
+TAP> i test/config.ts
+test/config.ts:
+  date: 2023-10-05T22:58:15.094Z
+  command: /usr/local/bin/node
+  args:
+    - --import=file:///Users/isaacs/dev/tapjs/tapjs/node_modules/@tapjs/mock/dist/esm/import.mjs
+    - --loader=file:///Users/isaacs/dev/tapjs/tapjs/node_modules/ts-node/esm.mjs
+    - --no-warnings
+    - --enable-source-maps
+    - --import=file:///Users/isaacs/dev/tapjs/tapjs/node_modules/@tapjs/processinfo/dist/esm/import.mjs
+    - /Users/isaacs/dev/tapjs/tapjs/src/run/test/config.ts
+  cwd: /Users/isaacs/dev/tapjs/tapjs/src/run
+  pid: 93041
+  ppid: 93003
+  code: 0
+  runtime: 3737.6802079999998
+
+TAP> i 686a4eb3-e82f-4b6b-b365-2c38195776f9
+686a4eb3-e82f-4b6b-b365-2c38195776f9:
+  date: 2023-10-05T22:58:31.447Z
+  command: /usr/local/bin/node
+  args:
+    - /Users/isaacs/dev/tapjs/tapjs/src/run/dist/esm/index.js
+    - blah.test.js
+  cwd: /Users/isaacs/dev/tapjs/tapjs/src/run/.tap/fixtures/test-run.ts-fail-to-find-all-named-test-files
+  pid: 93259
+  ppid: 93149
+  parent: ee929bda-9b80-43af-a5d7-da233c1f80f9
+  code: 1
+  runtime: 490.024416
+```
+
+## `.tap/coverage`
+
+The coverage generated by each test process is stored to this
+folder, with a `<uuid>.json` filename corresponding to the file
+for the process in `.tap/processinfo`.
+
+These are V8 coverage dump files, with a `source-map-cache`
+attached to be able to turn V8's byte-offset-based coverage
+reporting into line/column reporting used by the istanbul
+reporters.
+
+It's the same format used by the `NODE_V8_COVERAGE` directory,
+but limited only to the files in your program that you've opted
+to provide coverage for, instead of _everything_ in
+`node_modules` and node's built-in modules. You can use this
+folder as an argument to any other program that knows how to
+interpret this format, or put coverage files in this folder and
+tap will include them in its coverage reporting.
+
+## `.tap/fixtures`
+
+This is the folder where the [`@tapjs/fixture`
+plugin](./plugins/fixture.md) puts its test fixture files.
+
+## `.tap/test-results`
+
+Whenever tests are run, the [raw TAP](./tap-format.md) output is
+saved to this folder. This is what the [`tap
+replay`](./cli.11ty.js#tap-replay) command uses to replay the
+results of the previous test run.
+
+## Ignoring or Saving
+
+There's little harm in exposing the `.tap` folder, as the only
+sensitive data it typically contains (other than your code
+itself) is file and folder paths.
+
+However, becuase it _does_ contain file and folder paths, it's
+system specific, and generally not something you'd want to check
+into source control, so I recommend adding `/.tap` to your
+`.gitignore` file.

src/docs/content/environment.md

@@ -138,8 +138,7 @@ running `TAP_DEBUG=1 tap ./test/foo.ts` will run as if the
 
 This is the "project root" from tap's point of view. It's where
 it looks for the config file (either `.taprc` or `package.json`),
-and where it puts the `.tap` folder containing process and
-coverage tracking information.
+and where it puts the [`.tap` folder](./dot-tap-folder.md).
 
 ### `_TAPJS_PROCESSINFO_*`
 

src/docs/content/upgrading-from-16.md

@@ -12,6 +12,13 @@ The [changelog](./changelog.md) covers much of the details, but
 this is intended to be a more deliberate guide for users
 depending on features that have changed.
 
+## Fixtures, coverage, and processinfo moved to one folder
+
+This stuff is all stored in the [`.tap`
+folder](./dot-tap-folder.md) now. If you were previously ignoring
+`/coverage`, `/.nyc_info`, and/or `.tap-testdir-*`, you can now
+replace that with just `/.tap`.
+
 ## `mochaGlobals`
 
 In tap 16, a top-level function `tap.mochaGlobals()` would dump