chore: fix all usages of @module tags

Per [TypeDoc's documentation](https://typedoc.org/documents/Tags._module.html), a string following a `@module` tag _renames_ the module. JSDoc has this same behavior.

To that end, `@module`, if present, should _not_ be at the _top_ of a docstring (which is used at the description) unless we're in the business of renaming modules for documentation purposes (which we are welcome to do later, if we want).

* * *

There are many ways to do this, but I did it using [ripgrep](https://github.com/BurntSushi/ripgrep) and `sponge` from [moreutils](https://joeyh.name/code/moreutils/) (which—TIL—also contains a utility named `pee`):

```sh
for file in packages/*/src/**/*.{t,j}s; do
  rg -P '(?<=\/\*\*\n\s\*)\s@module(\s[\s\S]+?)(?=\n\s\*\/)' -U \
    --passthru -r '$1
*
* @module' $file | sponge $file
done
```

- `-P`: use PRCE2 (for the lookbehind)
- `-U`: enable multiline regex
- `--passthru`: dump the entire file
- `-r`: replace

Author: boneskull

Diff for: packages/compartment-mapper/src/archive.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides mechanisms for creating archives (zip files with a
+ * Provides mechanisms for creating archives (zip files with a
  * `compartmeent-map.json` and a file for every static dependency of an entry
  * module).
  *
@@ -13,6 +13,8 @@
  * See `archive-lite.js` for a variation that does not depend on Babel
  * for cases like XS native Compartments where pre-compilation is not
  * necessary or where the dependency on Babel can be dererred to runtime.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/capture-lite.js

@@ -1,5 +1,5 @@
 /**
- * @module
+ *
  * This module provides {@link captureFromMap}, which only "captures" the
  * compartment map descriptors and sources from a partially completed
  * compartment map--_without_ creating an archive. The resulting compartment map
@@ -25,6 +25,8 @@
  * contain original sources, so to import the archive with
  * `src/import-archive-lite.js`, you will need to provide the archive parsers
  * and entrain a runtime dependency on Babel.
+ *
+ * @module
  */
 
 /* eslint no-shadow: 0 */

Diff for: packages/compartment-mapper/src/import-archive-lite.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for evaluating the modules in an archive (a zip
+ * Provides functions for evaluating the modules in an archive (a zip
  * file with a `compartment-map.json` and a file for each module it contains.)
  *
  * These functions do not have a bias for any particular mapping, so you will
@@ -10,6 +10,8 @@
  * You will need to provide the `defaultParserForLanguage` from
  * `@endo/compartment-mapper/import-parsers.js` or
  * `@endo/compartment-mapper/archive-parsers.js`.
+ *
+ * @module
  */
 
 /* eslint no-shadow: "off" */

Diff for: packages/compartment-mapper/src/import-archive.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for evaluating modules in an archive (a zip file
+ * Provides functions for evaluating modules in an archive (a zip file
  * with a `compartment-map.json` and a file for a module and each of its
  * transitive dependencies.)
  *
@@ -12,6 +12,8 @@
  * See `import-archive-lite.js` for functions that are not coupled to these
  * parsers or the `node_modules` conventions without necessarily entraining a
  * dependency on Babel.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/import-hook.js

@@ -1,11 +1,13 @@
 /**
- * @module Provides the implementation of each compartment's `importHook` when
+ * Provides the implementation of each compartment's `importHook` when
  * using `import.js`, `import-lite.js`, `archive.js`, or `archive-lite.js`.
  * However, `import-archive.js` and `import-archive-lite.js` use their own
  * variant.
  *
  * For building archives, these import hooks create a table of all the modules
  * in a "working set" of transitive dependencies.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/import-lite.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for evaluating a module and its transitive
+ * Provides functions for evaluating a module and its transitive
  * dependencies given a partially completed compartment map.
  * The compartment map needs to describe every reachable compartment, where to
  * find modules in that compartment, and how to link modules between
@@ -13,6 +13,8 @@
  * The default `parserForLanguage` mapping is empty.
  * You will need to provide the `defaultParserForLanguage` from
  * `@endo/compartment-mapper/import-parsers.js` or similar.
+ *
+ * @module
  */
 
 /* eslint no-shadow: "off" */

Diff for: packages/compartment-mapper/src/import.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for evaluating a module and its transitive
+ * Provides functions for evaluating a module and its transitive
  * dependencies given the URL of the entry module and assuming packages laid
  * out according to the `node_modules` conventions.
  *
@@ -9,6 +9,8 @@
  *
  * The default `parserForLanguage` is `import-parsers.js`, which is suitable
  * for most cases.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/infer-exports.js

@@ -1,9 +1,11 @@
 /**
- * @module Provides functions needed by `node-modules.js` for building
+ * Provides functions needed by `node-modules.js` for building
  * inter-compartment linkage according to the specifications in a
  * `package.json` as laid out in the `node_modules` convention.
  * These functions implement the behavior for a package's `"main"`,
  * `"browser"`, `"imports"`, and `"exports"` properties in a `package.json`.
+ *
+ * @module
  */
 
 /** @import {LanguageForExtension} from './types.js' */

Diff for: packages/compartment-mapper/src/link.js

@@ -1,11 +1,13 @@
 /**
- * @module Provides the linking behavior shared by all Compartment Mapper
+ * Provides the linking behavior shared by all Compartment Mapper
  * workflows.
  * This involves creating and configuring compartments according to the
  * specifications in a compartment map, and is suitable for compartment maps
  * that just outline the locations of compartments and their inter-linkage and
  * also compartment maps that include every module descriptor in the transitive
  * dependencies of their entry module.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/map-parser.js

@@ -1,6 +1,8 @@
 /**
- * @module Exports {@link makeMapParsers}, which creates a function which matches a
+ * Exports {@link makeMapParsers}, which creates a function which matches a
  * module to a parser based on reasons.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/node-module-specifier.js

@@ -1,7 +1,9 @@
 /**
- * @module Provides functions for interacting with Node.js module specifiers in
+ * Provides functions for interacting with Node.js module specifiers in
  * their canonical form.
  * This is a kind of path math that is platform-agnostic.
+ *
+ * @module
  */
 
 // q, as in quote, for error messages.

Diff for: packages/compartment-mapper/src/node-modules.js

@@ -1,12 +1,14 @@
 /**
- * @module Provides functions for constructing a compartment map that has a
+ * Provides functions for constructing a compartment map that has a
  * compartment descriptor corresponding to every reachable package from an
  * entry module and how to create links between them.
  * The resulting compartment map does not describe individual modules but does
  * capture every usable route between packages including those generalized by
  * wildcard expansion.
  * See {@link link} to expand a compartment map to capture module descriptors
  * for transitive dependencies.
+ *
+ * @module
  */
 
 /* eslint no-shadow: 0 */

Diff for: packages/compartment-mapper/src/node-powers.js

@@ -1,10 +1,12 @@
 /**
- * @module Provides adapters for Compartment Mapper I/O to the corresponding
+ * Provides adapters for Compartment Mapper I/O to the corresponding
  * Node.js implementations of those behaviors.
  *
  * The Compartment Mapper generalizes its I/O interface to allow for a wide
  * variety of I/O providers, but especially for reading and writing from
  * virtualized file systems like zip files.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/parse-archive-cjs.js

@@ -1,6 +1,8 @@
 /**
- * @module Provides language behavior for analyzing, pre-compiling, and storing
+ * Provides language behavior for analyzing, pre-compiling, and storing
  * CommonJS modules for an archive.
+ *
+ * @module
  */
 
 /** @import {ParseFn} from './types.js' */

Diff for: packages/compartment-mapper/src/parse-archive-mjs.js

@@ -1,6 +1,8 @@
 /**
- * @module Provides language behavior for analyzing, pre-compiling, and storing ESM
+ * Provides language behavior for analyzing, pre-compiling, and storing ESM
  * modules for an archive.
+ *
+ * @module
  */
 
 /** @import {ParseFn} from './types.js' */

Diff for: packages/compartment-mapper/src/parse-bytes.js

@@ -1,6 +1,8 @@
 /**
- * @module Provides rudimentary support for treating an arbitrary file as a
+ * Provides rudimentary support for treating an arbitrary file as a
  * module that exports the bytes of that file.
+ *
+ * @module
  */
 
 /** @import {Harden} from 'ses' */

Diff for: packages/compartment-mapper/src/parse-cjs-shared-export-wrapper.js

@@ -1,7 +1,9 @@
 /**
- * @module Provides shared functionality for {@link parse-cjs.js} and {@link
+ * Provides shared functionality for {@link parse-cjs.js} and {@link
  * parse-archive-cjs.js} toward importing or archiving CommonJS as a virtual
  * module source.
+ *
+ * @module
  */
 
 /** @import {ReadFn, ReadPowers} from './types.js' */

Diff for: packages/compartment-mapper/src/parse-cjs.js

@@ -1,6 +1,8 @@
 /**
- * @module Provides language behavior (parser) for importing CommonJS as a
+ * Provides language behavior (parser) for importing CommonJS as a
  * virtual module source.
+ *
+ * @module
  */
 
 /** @import {ParseFn} from './types.js' */

Diff for: packages/compartment-mapper/src/parse-pre-cjs.js

@@ -1,9 +1,11 @@
 /**
- * @module Provides language-specific behavior for importing pre-compiled
+ * Provides language-specific behavior for importing pre-compiled
  * CommonJS.
  * Pre-compiled CommonJS is a module in JSON format that describes its imports,
  * exports, and source to execute in the presence of `require`, `module`, and
  * `exports`.
+ *
+ * @module
  */
 
 /** @import {ParseFn} from './types.js' */

Diff for: packages/compartment-mapper/src/parse-pre-mjs.js

@@ -1,8 +1,10 @@
 /**
- * @module Provides language-specific behaviors for importing pre-compiled ESM.
+ * Provides language-specific behaviors for importing pre-compiled ESM.
  * Pre-compiling or translating ESM from a module to a script with a
  * calling-convention is necessary to prepare an archive so that it can be
  * imported by the SES shim without entraining a dependency on Babel.
+ *
+ * @module
  */
 
 /** @import {ParseFn} from './types.js' */

Diff for: packages/compartment-mapper/src/parse-text.js

@@ -1,7 +1,9 @@
 /**
- * @module Provides language-behaviors for importing a module as a document
+ * Provides language-behaviors for importing a module as a document
  * that exports itself as a string based on a UTF-8 interpretation of the
  * module's text.
+ *
+ * @module
  */
 
 /** @import {ParseFn} from './types.js' */

Diff for: packages/compartment-mapper/src/policy-format.js

@@ -1,6 +1,8 @@
 /**
- * @module Provides functions for enforcing compartment-map linkage and global
+ * Provides functions for enforcing compartment-map linkage and global
  * variable policies for each compartment.
+ *
+ * @module
  */
 
 /** @import {SomePackagePolicy, SomePolicy} from './types.js' */

Diff for: packages/compartment-mapper/src/policy.js

@@ -1,5 +1,7 @@
 /**
- * @module Provides mechanisms for interacting with Compartment Map runtime policies.
+ * Provides mechanisms for interacting with Compartment Map runtime policies.
+ *
+ * @module
  */
 
 // @ts-check

Diff for: packages/compartment-mapper/src/powers.js

@@ -1,9 +1,11 @@
 /**
- * @module As the interface of the Compartment Mapper evolved, it became
+ * As the interface of the Compartment Mapper evolved, it became
  * necessary to expand some function signatures that accepted a single power to
  * one that accepted a powers object.
  * This module provides functions for safely unpacking I/O capabilities and
  * maintaining backward-compatibility with older accepted usage patterns.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/search.js

@@ -1,6 +1,8 @@
 /**
- * @module Provides the behavior for `node-modules.js` to find modules and
+ * Provides the behavior for `node-modules.js` to find modules and
  * packages according to the Node.js `node_modules` convention.
+ *
+ * @module
  */
 
 /**

Diff for: packages/compartment-mapper/src/types/compartment-map-schema.ts

@@ -1,7 +1,9 @@
 /**
- * @module These types describe the schema of a `compartment-map.json`, which
+ * These types describe the schema of a `compartment-map.json`, which
  * in turn describes how to load and link an application from storage, like a
  * file system, web host, or zip archive.
+ *
+ * @module
  */
 
 /* eslint-disable no-use-before-define */

Diff for: packages/compartment-mapper/src/types/external.ts

@@ -1,5 +1,7 @@
 /**
- * @module External types of the compartment mapper.
+ * External types of the compartment mapper.
+ *
+ * @module
  */
 
 /* eslint-disable no-use-before-define */

Diff for: packages/compartment-mapper/src/types/internal.ts

@@ -1,6 +1,8 @@
 /**
- * @module Internal types of the compartment mapper that need not be visible to
+ * Internal types of the compartment mapper that need not be visible to
  * consumers.
+ *
+ * @module
  */
 
 /* eslint-disable no-use-before-define */

Diff for: packages/compartment-mapper/src/types/node-powers.ts

@@ -1,6 +1,8 @@
 /**
- * @module These interfaces describe the powers needed in `node-powers.js` to
+ * These interfaces describe the powers needed in `node-powers.js` to
  * adapt host capabilities for the compartment mapper.
+ *
+ * @module
  */
 
 /* eslint-disable no-use-before-define */

Diff for: packages/compartment-mapper/src/types/policy-schema.ts

@@ -1,6 +1,8 @@
 /**
- * @module Describes the portion of a compartment map dedicated to narrowing
+ * Describes the portion of a compartment map dedicated to narrowing
  * or attenuating the powers available to each compartment.
+ *
+ * @module
  */
 
 /* eslint-disable no-use-before-define */

Diff for: packages/compartment-mapper/src/types/policy.ts

@@ -1,5 +1,7 @@
 /**
- * @module Types required for policy enforcement.
+ * Types required for policy enforcement.
+ *
+ * @module
  */
 
 /* eslint-disable no-use-before-define */

Diff for: packages/compartment-mapper/src/types/powers.ts

@@ -1,8 +1,10 @@
 /**
- * @module The compartment mapper requires certain host capabilities.
+ * The compartment mapper requires certain host capabilities.
  * These are the platform-neutral types for those capabilities.
  * For example, {@file node-powers.js} adapts Node.js how modules
  * to various subsets of these capabilities.
+ *
+ * @module
  */
 
 /* eslint-disable no-use-before-define */

Diff for: packages/compartment-mapper/src/types/typescript.ts

@@ -1,5 +1,7 @@
 /**
- * @module Helpers relevant to any TypeScript project.
+ * Helpers relevant to any TypeScript project.
+ *
+ * @module
  */
 
 /** Any object. All objects. Not `null`, though. */