refactor(patterns): improve pattern types. Flatten @imports (#2256)

closes: #XXXX
refs: #2248 #1584 Agoric/agoric-sdk#6432

## Description

Pure refactor. Changes only static info. Mostly more consistent and more
readable use of `@import`.

One case made less readable: Remove newlines within a large `@import`
directive. The reason is that
`yarn lerna run build:types` chokes on those newlines. TODO minimal
repro + report issue.

Extracted from other PRs #1584 #2248 which are now staged on this one.
But this should be a reviewable and mergeable improvement regardless of
whether we move forward on the others.

### Security Considerations

none
### Scaling Considerations

none
### Documentation Considerations

none
### Testing Considerations

none
### Compatibility Considerations

none
### Upgrade Considerations
none

- ~[ ] Includes `*BREAKING*:` in the commit message with migration
instructions for any breaking change.~
- ~[ ] Updates `NEWS.md` for user-facing changes.~

packages/patterns/src/keys/checkKey.js

@@ -20,9 +20,11 @@ import { checkBagEntries, makeBagOfEntries } from './copyBag.js';
 
 const { ownKeys } = Reflect;
 
-/** @import {Checker} from '@endo/marshal' */
-/** @import {Passable} from '@endo/pass-style' */
-/** @import {CopyBag, CopyMap, CopySet, Key} from '../types' */
+/**
+ * @import {Passable} from '@endo/pass-style'
+ * @import {Checker} from '@endo/marshal'
+ * @import {CopyBag, CopyMap, CopySet, Key} from '../types.js'
+ */
 
 // ////////////////// Primitive and Scalar keys ////////////////////////////////
 

packages/patterns/src/keys/compareKeys.js

@@ -17,7 +17,7 @@ import {
 } from './checkKey.js';
 import { makeCompareCollection } from './keycollection-operators.js';
 
-/** @import {CopySet} from '../types' */
+/** @import {CopySet, KeyCompare} from '../types.js' */
 
 /**
  * CopySet X is smaller than CopySet Y iff all of these conditions hold:
@@ -86,7 +86,7 @@ const _mapCompare = makeCompareCollection(
 );
 harden(_mapCompare);
 
-/** @type {import('../types').KeyCompare} */
+/** @type {KeyCompare} */
 export const compareKeys = (left, right) => {
   assertKey(left);
   assertKey(right);

packages/patterns/src/keys/copyBag.js

@@ -12,10 +12,11 @@ import {
 
 import { X } from '@endo/errors';
 
-/** @import {CopyBag} from '../types' */
-/** @import {FullCompare} from '../types' */
-/** @import {Checker} from '@endo/marshal' */
-/** @import {Passable} from '@endo/pass-style' */
+/**
+ * @import {Passable} from '@endo/pass-style'
+ * @import {Checker} from '@endo/marshal'
+ * @import {CopyBag, FullCompare} from '../types.js'
+ */
 
 /**
  * @template T

packages/patterns/src/keys/copySet.js

@@ -13,9 +13,9 @@ import {
 import { X } from '@endo/errors';
 
 /**
- * @import {CopySet, FullCompare} from '../types'
- * @import {Checker} from '@endo/marshal'
  * @import {Passable} from '@endo/pass-style'
+ * @import {Checker} from '@endo/marshal'
+ * @import {CopySet, FullCompare} from '../types.js'
  */
 
 /**

packages/patterns/src/keys/keycollection-operators.js

@@ -8,11 +8,10 @@ import {
 import { makeIterator } from '@endo/common/make-iterator.js';
 import { makeArrayIterator } from '@endo/common/make-array-iterator.js';
 
-/** @import {RankCompare} from '@endo/marshal' */
-/** @import {KeyComparison} from '../types' */
-/** @import {KeyCompare} from '../types' */
-/** @import {FullCompare} from '../types' */
-/** @import {KeyCollection} from '../types' */
+/**
+ * @import {RankCompare} from '@endo/marshal'
+ * @import {Key, KeyCompare, FullCompare, KeyComparison, KeyCollection} from '../types.js'
+ */
 
 import { q, Fail } from '@endo/errors';
 
@@ -22,10 +21,10 @@ import { q, Fail } from '@endo/errors';
  * rank, into an iterable that resolves those ties using `fullCompare`.
  *
  * @template [V=unknown]
- * @param {Array<[import('../types.js').Key, V]>} entries
+ * @param {Array<[Key, V]>} entries
  * @param {RankCompare} rankCompare
  * @param {FullCompare} fullCompare
- * @returns {IterableIterator<[import('../types.js').Key, V]>}
+ * @returns {IterableIterator<[Key, V]>}
  */
 const generateFullSortedEntries = (entries, rankCompare, fullCompare) => {
   assertRankSorted(entries, rankCompare);
@@ -82,9 +81,9 @@ harden(generateFullSortedEntries);
  * @template [V=unknown]
  * @param {C} c1
  * @param {C} c2
- * @param {(collection: C) => Array<[import('../types.js').Key, V]>} getEntries
+ * @param {(collection: C) => Array<[Key, V]>} getEntries
  * @param {any} absentValue
- * @returns {IterableIterator<[import('../types.js').Key, V | absentValue, V | absentValue]>}
+ * @returns {IterableIterator<[Key, V | absentValue, V | absentValue]>}
  */
 export const generateCollectionPairEntries = (
   c1,
@@ -127,7 +126,7 @@ export const generateCollectionPairEntries = (
   nextY();
   return makeIterator(() => {
     let done = false;
-    /** @type {[import('../types.js').Key, V | absentValue, V | absentValue]} */
+    /** @type {[Key, V | absentValue, V | absentValue]} */
     let value;
     if (xDone && yDone) {
       done = true;
@@ -178,7 +177,7 @@ harden(generateCollectionPairEntries);
  *
  * @template [C=KeyCollection]
  * @template [V=unknown]
- * @param {(collection: C) => Array<[import('../types.js').Key, V]>} getEntries
+ * @param {(collection: C) => Array<[Key, V]>} getEntries
  * @param {any} absentValue
  * @param {KeyCompare} compareValues
  * @returns {(left: C, right: C) => KeyComparison}

packages/patterns/src/keys/merge-bag-operators.js

@@ -7,9 +7,10 @@ import {
 import { q, Fail } from '@endo/errors';
 import { assertNoDuplicateKeys, makeBagOfEntries } from './copyBag.js';
 
-/** @import {KeyComparison} from '../types' */
-/** @import {FullCompare} from '../types' */
-/** @import {RankCompare} from '@endo/marshal' */
+/**
+ * @import {RankCompare} from '@endo/marshal'
+ * @import {FullCompare} from '../types.js'
+ */
 
 // Based on merge-set-operators.js, but altered for the bag representation.
 // TODO share more code with that file and keycollection-operators.js.

packages/patterns/src/keys/merge-set-operators.js

@@ -7,9 +7,10 @@ import {
 import { q, Fail } from '@endo/errors';
 import { assertNoDuplicates, makeSetOfElements } from './copySet.js';
 
-/** @import {KeyComparison} from '../types' */
-/** @import {FullCompare} from '../types' */
-/** @import {RankCompare} from '@endo/marshal' */
+/**
+ * @import {RankCompare} from '@endo/marshal'
+ * @import {FullCompare, KeyComparison} from '../types.js'
+ */
 
 // TODO share more code with keycollection-operators.js.
 

packages/patterns/src/patterns/getGuardPayloads.js

@@ -16,7 +16,9 @@ import {
 } from './patternMatchers.js';
 import { getCopyMapKeys, makeCopyMap } from '../keys/checkKey.js';
 
-/** @import {AwaitArgGuard, AwaitArgGuardPayload, InterfaceGuard, InterfaceGuardPayload, MethodGuard, MethodGuardPayload} from '../types.js' */
+/**
+ * @import {AwaitArgGuard, AwaitArgGuardPayload, InterfaceGuard, InterfaceGuardPayload, MethodGuard, MethodGuardPayload} from '../types.js'
+ */
 
 // The get*GuardPayload functions exist to adapt to the worlds both
 // before and after https://github.com/endojs/endo/pull/1712 . When

packages/patterns/src/patterns/patternMatchers.js

@@ -34,16 +34,16 @@ import {
 } from '../keys/checkKey.js';
 import { generateCollectionPairEntries } from '../keys/keycollection-operators.js';
 
-/// <reference types="ses"/>
-
-/** @import {Checker, CopyRecord, CopyTagged, Passable} from '@endo/pass-style' */
-/** @import {ArgGuard, AwaitArgGuard, CheckPattern, GetRankCover, InterfaceGuard, MatcherNamespace, MethodGuard, MethodGuardMaker, Pattern, RawGuard, SyncValueGuard} from '../types.js' */
-/** @import {Kind, MatchHelper} from './types.js' */
+/**
+ * @import {Checker, CopyRecord, CopyTagged, Passable} from '@endo/pass-style'
+ * @import {ArgGuard, AwaitArgGuard, CheckPattern, GetRankCover, InterfaceGuard, MatcherNamespace, MethodGuard, MethodGuardMaker, Pattern, RawGuard, SyncValueGuard, Kind, Limits, AllLimits, Key, DefaultGuardType} from '../types.js'
+ * @import {MatchHelper, PatternKit} from './types.js'
+ */
 
 const { entries, values } = Object;
 const { ownKeys } = Reflect;
 
-/** @type {WeakSet<import('../types.js').Pattern>} */
+/** @type {WeakSet<Pattern>} */
 const patternMemo = new WeakSet();
 
 // /////////////////////// Match Helpers Helpers /////////////////////////////
@@ -78,13 +78,11 @@ export const defaultLimits = harden({
  * Thus, the result only needs to support destructuring. The current
  * implementation uses inheritance as a cheap hack.
  *
- * @param {import('../types.js').Limits} [limits]
- * @returns {import('../types.js').AllLimits}
+ * @param {Limits} [limits]
+ * @returns {AllLimits}
  */
 const limit = (limits = {}) =>
-  /** @type {import('../types.js').AllLimits} */ (
-    harden({ __proto__: defaultLimits, ...limits })
-  );
+  /** @type {AllLimits} */ (harden({ __proto__: defaultLimits, ...limits }));
 
 const checkIsWellFormedWithLimit = (
   payload,
@@ -149,15 +147,15 @@ const checkDecimalDigitsLimit = (specimen, decimalDigitsLimit, check) => {
 };
 
 /**
- * @returns {import('./types.js').PatternKit}
+ * @returns {PatternKit}
  */
 const makePatternKit = () => {
   /**
    * If this is a recognized match tag, return the MatchHelper.
    * Otherwise result undefined.
    *
    * @param {string} tag
-   * @returns {import('./types.js').MatchHelper | undefined}
+   * @returns {MatchHelper | undefined}
    */
   const maybeMatchHelper = tag =>
     // eslint-disable-next-line no-use-before-define
@@ -301,7 +299,7 @@ const makePatternKit = () => {
 
   /**
    * @param {Passable} specimen
-   * @param {import('../types.js').Key} keyAsPattern
+   * @param {Key} keyAsPattern
    * @param {Checker} check
    * @returns {boolean}
    */
@@ -1697,7 +1695,7 @@ const makePatternKit = () => {
     split: (base, rest = undefined) => {
       if (passStyleOf(harden(base)) === 'copyArray') {
         // TODO at-ts-expect-error works locally but not from @endo/exo
-        // @ts-ignore We know it should be an array
+        // @ts-expect-error We know it should be an array
         return M.splitArray(base, rest && [], rest);
       } else {
         return M.splitRecord(base, rest && {}, rest);
@@ -1706,7 +1704,7 @@ const makePatternKit = () => {
     partial: (base, rest = undefined) => {
       if (passStyleOf(harden(base)) === 'copyArray') {
         // TODO at-ts-expect-error works locally but not from @endo/exo
-        // @ts-ignore We know it should be an array
+        // @ts-expect-error We know it should be an array
         return M.splitArray([], base, rest);
       } else {
         return M.splitRecord({}, base, rest);
@@ -1933,7 +1931,7 @@ harden(assertInterfaceGuard);
  * @template {Record<PropertyKey, MethodGuard>} [M = Record<PropertyKey, MethodGuard>]
  * @param {string} interfaceName
  * @param {M} methodGuards
- * @param {{ sloppy?: boolean, defaultGuards?: import('../types.js').DefaultGuardType }} [options]
+ * @param {{ sloppy?: boolean, defaultGuards?: DefaultGuardType }} [options]
  * @returns {InterfaceGuard<M>}
  */
 const makeInterfaceGuard = (interfaceName, methodGuards, options = {}) => {

packages/patterns/src/patterns/types.js

@@ -2,25 +2,9 @@
 
 export {};
 
-/** @import {Passable} from '@endo/pass-style' */
-/** @import {PassStyle} from '@endo/pass-style' */
-/** @import {Checker} from '@endo/pass-style' */
-/** @import {MethodGuard} from '../types.js' */
-
-/** @import {MatcherNamespace} from '../types' */
-/** @import {Pattern} from '../types' */
-/** @import {GetRankCover} from '../types' */
-
 /**
- * @typedef {Exclude<PassStyle, 'tagged'> |
- *   'copySet' | 'copyBag' | 'copyMap' |
- *   `match:${any}` | `guard:${any}`
- * } Kind
- * It is either a PassStyle other than 'tagged', or, if the underlying
- * PassStyle is 'tagged', then the `getTag` value for tags that are
- * recognized at the @endo/patterns level of abstraction. For each of those
- * tags, a tagged record only has that kind if it satisfies the invariants
- * that the @endo/patterns level associates with that kind.
+ * @import {Passable, Checker} from '@endo/pass-style'
+ * @import {MatcherNamespace, Pattern, GetRankCover, Kind} from '../types.js'
  */
 
 /**
@@ -42,7 +26,7 @@ export {};
  * Assuming validity of `matcherPayload` as the payload of a Matcher corresponding
  * with this MatchHelper, reports whether `specimen` is matched by that Matcher.
  *
- * @property {import('../types').GetRankCover} getRankCover
+ * @property {GetRankCover} getRankCover
  * Assumes this is the payload of a CopyTagged with the corresponding
  * matchTag. Return a RankCover to bound from below and above,
  * in rank order, all possible Passables that would match this Matcher.

packages/patterns/src/types.js

@@ -2,9 +2,10 @@
 
 export {};
 
-/** @import {Checker, CopyArray, CopyRecord, CopyTagged, Passable} from '@endo/pass-style' */
-/** @import {PassStyle} from '@endo/pass-style' */
-/** @import {RankCompare, RankCover} from '@endo/marshal' */
+/**
+ * @import {CopyArray, CopyRecord, CopyTagged, Passable, PassStyle, Checker} from '@endo/pass-style'
+ * @import {RankCompare, RankCover} from '@endo/marshal'
+ */
 
 /**
  * @typedef {Passable} Key
@@ -218,6 +219,18 @@ export {};
  * @typedef {Partial<AllLimits>} Limits
  */
 
+/**
+ * @typedef {Exclude<PassStyle, 'tagged'> |
+ *   'copySet' | 'copyBag' | 'copyMap' |
+ *   `match:${any}` | `guard:${any}`
+ * } Kind
+ * It is either a PassStyle other than 'tagged', or, if the underlying
+ * PassStyle is 'tagged', then the `getTag` value for tags that are
+ * recognized at the @endo/patterns level of abstraction. For each of those
+ * tags, a tagged record only has that kind if it satisfies the invariants
+ * that the @endo/patterns level associates with that kind.
+ */
+
 /**
  * @typedef {object} PatternMatchers
  *

packages/patterns/test/test-pattern-limits.js

@@ -8,11 +8,13 @@ import {
   defaultLimits,
 } from '../src/patterns/patternMatchers.js';
 
-/** @import {Passable} from '@endo/marshal' */
-/** @import {Pattern} from '../src/types.js' */
+/**
+ * @import {Passable} from '@endo/marshal'
+ * @import {Pattern} from '../src/types.js'
+ */
 
 /**
- * @typedef MatchTest
+ * @typedef {object} MatchTest
  * @property {Passable} specimen
  * @property {Pattern[]} yesPatterns
  * @property {[Pattern, RegExp|string][]} noPatterns

packages/ses/src/error/assert.js

@@ -47,14 +47,7 @@ import './internal-types.js';
 import { makeNoteLogArgsArrayKit } from './note-log-args.js';
 
 /**
- * @import {BaseAssert,
- *          Assert,
- *          AssertionFunctions,
- *          AssertionUtilities,
- *          StringablePayload,
- *          DetailsToken,
- *          MakeAssert,
- * } from '../../types.js'
+ * @import {BaseAssert, Assert, AssertionFunctions, AssertionUtilities, StringablePayload, DetailsToken, MakeAssert} from '../../types.js'
  */
 
 // For our internal debugging purposes, uncomment