From 6c7054cb877807a2e5673762250f7f51c8902836 Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Thu, 11 Jul 2024 16:05:24 -0400 Subject: [PATCH 1/4] chore: Fix bad JSDoc imports Ref #9632 --- packages/ERTP/src/legacy-payment-helpers.js | 2 +- packages/ERTP/src/transientNotifier.js | 2 +- packages/ERTP/src/types.js | 6 +++--- packages/SwingSet/src/types-external.js | 4 ++-- packages/SwingSet/src/vats/timer/vat-timer.js | 4 ++-- packages/inter-protocol/src/proposals/utils.js | 2 +- packages/store/src/stores/scalarMapStore.js | 4 ++-- packages/store/src/stores/scalarSetStore.js | 2 +- packages/vats/src/lib-board.js | 2 +- packages/vats/src/vat-bank.js | 4 ++-- 10 files changed, 16 insertions(+), 16 deletions(-) diff --git a/packages/ERTP/src/legacy-payment-helpers.js b/packages/ERTP/src/legacy-payment-helpers.js index f52d2f92ee6..569c41b4ffb 100644 --- a/packages/ERTP/src/legacy-payment-helpers.js +++ b/packages/ERTP/src/legacy-payment-helpers.js @@ -6,7 +6,7 @@ import { mustMatch } from '@agoric/store'; import { AmountMath } from './amountMath.js'; /** - * @import {ERef} from '@endo/far'); + * @import {ERef} from '@endo/far'; * @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.js' */ diff --git a/packages/ERTP/src/transientNotifier.js b/packages/ERTP/src/transientNotifier.js index a01eaeb28c1..112c358a5a2 100644 --- a/packages/ERTP/src/transientNotifier.js +++ b/packages/ERTP/src/transientNotifier.js @@ -6,7 +6,7 @@ import { makeNotifierKit } from '@agoric/notifier'; /** * @import {Purse} from './types.js'; - * @import {LatestTopic, NotifierRecord} from '@agoric/notifier'); + * @import {LatestTopic, NotifierRecord} from '@agoric/notifier'; */ // Note: Virtual for high cardinality, but *not* durable, and so diff --git a/packages/ERTP/src/types.js b/packages/ERTP/src/types.js index 64dca7c5c8a..c51820cf59a 100644 --- a/packages/ERTP/src/types.js +++ b/packages/ERTP/src/types.js @@ -5,9 +5,9 @@ export {}; /// /** - * @import {Passable, RemotableObject} from '@endo/pass-style') - * @import {CopyBag, CopySet, Key} from '@endo/patterns') - * @import {LatestTopic, NotifierRecord} from '@agoric/notifier'); + * @import {Passable, RemotableObject} from '@endo/pass-style' + * @import {CopyBag, CopySet, Key} from '@endo/patterns' + * @import {LatestTopic, NotifierRecord} from '@agoric/notifier' */ /** @typedef {{ brand: Brand<'nat'>; value: bigint }} NatAmount */ diff --git a/packages/SwingSet/src/types-external.js b/packages/SwingSet/src/types-external.js index 7b45acfa86c..2a60b954d4c 100644 --- a/packages/SwingSet/src/types-external.js +++ b/packages/SwingSet/src/types-external.js @@ -3,8 +3,8 @@ export {}; /** - * @import {Guarded} from '@endo/exo') - * @import {Passable, RemotableObject} from '@endo/pass-style') + * @import {Guarded} from '@endo/exo' + * @import {Passable, RemotableObject} from '@endo/pass-style' */ /* This file defines types that part of the external API of swingset. That diff --git a/packages/SwingSet/src/vats/timer/vat-timer.js b/packages/SwingSet/src/vats/timer/vat-timer.js index 7ea007bf2cc..502d6fb8c11 100644 --- a/packages/SwingSet/src/vats/timer/vat-timer.js +++ b/packages/SwingSet/src/vats/timer/vat-timer.js @@ -16,8 +16,8 @@ import { makeScalarWeakMapStore } from '@agoric/store'; import { TimeMath } from '@agoric/time'; /** - * @import {Passable, RemotableObject} from '@endo/pass-style') - * @import {Key} from '@endo/patterns') + * @import {Passable, RemotableObject} from '@endo/pass-style' + * @import {Key} from '@endo/patterns' */ // This consumes O(N) RAM only for outstanding promises, via wakeAt(), diff --git a/packages/inter-protocol/src/proposals/utils.js b/packages/inter-protocol/src/proposals/utils.js index 4dce2abdad3..f632713cc7e 100644 --- a/packages/inter-protocol/src/proposals/utils.js +++ b/packages/inter-protocol/src/proposals/utils.js @@ -3,7 +3,7 @@ import { E } from '@endo/far'; import { WalletName } from '@agoric/internal'; import { getCopyMapEntries, makeCopyMap } from '@agoric/store'; -/** @import {CopyMap} from '@endo/patterns') */ +/** @import {CopyMap} from '@endo/patterns' */ /** * @param {ERef} nameAdmin diff --git a/packages/store/src/stores/scalarMapStore.js b/packages/store/src/stores/scalarMapStore.js index 2a9cf63cd18..9264a70d2fb 100644 --- a/packages/store/src/stores/scalarMapStore.js +++ b/packages/store/src/stores/scalarMapStore.js @@ -17,8 +17,8 @@ import { makeWeakMapStoreMethods } from './scalarWeakMapStore.js'; import { makeCurrentKeysKit } from './store-utils.js'; /** - * @import {Passable} from '@endo/pass-style'); - * @import {Key, Pattern} from '@endo/patterns'); + * @import {Passable} from '@endo/pass-style'; + * @import {Key, Pattern} from '@endo/patterns'; * @import {MapStore, MapStoreMethods, StoreOptions} from '../types.js'; */ diff --git a/packages/store/src/stores/scalarSetStore.js b/packages/store/src/stores/scalarSetStore.js index e49b4edf077..bf11d30ee33 100644 --- a/packages/store/src/stores/scalarSetStore.js +++ b/packages/store/src/stores/scalarSetStore.js @@ -12,7 +12,7 @@ import { makeWeakSetStoreMethods } from './scalarWeakSetStore.js'; import { makeCurrentKeysKit } from './store-utils.js'; /** - * @import {Key, Pattern} from '@endo/patterns'); + * @import {Key, Pattern} from '@endo/patterns'; * @import {SetStore, SetStoreMethods, StoreOptions} from '../types.js'; */ diff --git a/packages/vats/src/lib-board.js b/packages/vats/src/lib-board.js index f1c7a23a48f..f450d8e8cde 100644 --- a/packages/vats/src/lib-board.js +++ b/packages/vats/src/lib-board.js @@ -17,7 +17,7 @@ import { crc6 } from './crc.js'; /** * @import {RemotableObject} from '@endo/pass-style'; - * @import {Key} from '@endo/patterns'); + * @import {Key} from '@endo/patterns'; */ export const DEFAULT_CRC_DIGITS = 2; diff --git a/packages/vats/src/vat-bank.js b/packages/vats/src/vat-bank.js index 5922a85586c..5ef7d657081 100644 --- a/packages/vats/src/vat-bank.js +++ b/packages/vats/src/vat-bank.js @@ -22,8 +22,8 @@ import { } from './virtual-purse.js'; /** - * @import {Guarded} from '@endo/exo') - * @import {Passable, RemotableObject} from '@endo/pass-style') + * @import {Guarded} from '@endo/exo' + * @import {Passable, RemotableObject} from '@endo/pass-style' */ const { VirtualPurseControllerI } = makeVirtualPurseKitIKit(); From 476229d8e85a005d4be84a90267cdb2c280be0b2 Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Thu, 11 Jul 2024 16:07:22 -0400 Subject: [PATCH 2/4] chore: Make eslint-plugin-jsdoc aware of TypeDoc tags Ref #9632 --- .eslintrc.cjs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/.eslintrc.cjs b/.eslintrc.cjs index 1f2067b174c..e0393d92518 100644 --- a/.eslintrc.cjs +++ b/.eslintrc.cjs @@ -114,6 +114,27 @@ module.exports = { // The default is 'warn', but we want to enforce 'error'. '@jessie.js/safe-await-separator': 'error', + 'jsdoc/check-tag-names': [ + 'error', + { + // TypeDoc adds tags not otherwise known to JSDoc + // https://typedoc.org/guides/tags/ + definedTags: [ + 'alpha', + 'beta', + 'category', + 'categoryDescription', + 'defaultValue', + 'document', + 'group', + 'groupDescription', + 'internal', + 'privateRemarks', + 'remarks', + ], + }, + ], + // CI has a separate format check but keep this warn to maintain that "eslint --fix" prettifies // UNTIL https://github.com/Agoric/agoric-sdk/issues/4339 'prettier/prettier': 'warn', From b6437fe3aee632d135b0cf8ca31f09e57819603a Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Fri, 12 Jul 2024 10:44:52 -0400 Subject: [PATCH 3/4] chore: End each JSDoc import in changed files with a semicolon --- packages/ERTP/src/legacy-payment-helpers.js | 2 +- packages/ERTP/src/types.js | 6 +++--- packages/SwingSet/src/types-external.js | 6 +++--- packages/SwingSet/src/vats/timer/vat-timer.js | 16 ++++++++-------- packages/inter-protocol/src/proposals/utils.js | 2 +- packages/vats/src/lib-board.js | 2 +- packages/vats/src/vat-bank.js | 6 +++--- 7 files changed, 20 insertions(+), 20 deletions(-) diff --git a/packages/ERTP/src/legacy-payment-helpers.js b/packages/ERTP/src/legacy-payment-helpers.js index 569c41b4ffb..bb8f22749a3 100644 --- a/packages/ERTP/src/legacy-payment-helpers.js +++ b/packages/ERTP/src/legacy-payment-helpers.js @@ -7,7 +7,7 @@ import { AmountMath } from './amountMath.js'; /** * @import {ERef} from '@endo/far'; - * @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.js' + * @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.js'; */ /** diff --git a/packages/ERTP/src/types.js b/packages/ERTP/src/types.js index c51820cf59a..3fa88b16517 100644 --- a/packages/ERTP/src/types.js +++ b/packages/ERTP/src/types.js @@ -5,9 +5,9 @@ export {}; /// /** - * @import {Passable, RemotableObject} from '@endo/pass-style' - * @import {CopyBag, CopySet, Key} from '@endo/patterns' - * @import {LatestTopic, NotifierRecord} from '@agoric/notifier' + * @import {Passable, RemotableObject} from '@endo/pass-style'; + * @import {CopyBag, CopySet, Key} from '@endo/patterns'; + * @import {LatestTopic, NotifierRecord} from '@agoric/notifier'; */ /** @typedef {{ brand: Brand<'nat'>; value: bigint }} NatAmount */ diff --git a/packages/SwingSet/src/types-external.js b/packages/SwingSet/src/types-external.js index 2a60b954d4c..a62c411bd6b 100644 --- a/packages/SwingSet/src/types-external.js +++ b/packages/SwingSet/src/types-external.js @@ -1,10 +1,10 @@ -/** @import { ERef } from '@endo/far' */ +/** @import { ERef } from '@endo/far'; */ export {}; /** - * @import {Guarded} from '@endo/exo' - * @import {Passable, RemotableObject} from '@endo/pass-style' + * @import {Guarded} from '@endo/exo'; + * @import {Passable, RemotableObject} from '@endo/pass-style'; */ /* This file defines types that part of the external API of swingset. That diff --git a/packages/SwingSet/src/vats/timer/vat-timer.js b/packages/SwingSet/src/vats/timer/vat-timer.js index 502d6fb8c11..1f1ce669439 100644 --- a/packages/SwingSet/src/vats/timer/vat-timer.js +++ b/packages/SwingSet/src/vats/timer/vat-timer.js @@ -16,8 +16,8 @@ import { makeScalarWeakMapStore } from '@agoric/store'; import { TimeMath } from '@agoric/time'; /** - * @import {Passable, RemotableObject} from '@endo/pass-style' - * @import {Key} from '@endo/patterns' + * @import {Passable, RemotableObject} from '@endo/pass-style'; + * @import {Key} from '@endo/patterns'; */ // This consumes O(N) RAM only for outstanding promises, via wakeAt(), @@ -25,12 +25,12 @@ import { TimeMath } from '@agoric/time'; // client). Everything else should remain in the DB. /** - * @import {Timestamp} from '@agoric/time' - * @import {TimestampRecord} from '@agoric/time' - * @import {TimestampValue} from '@agoric/time' - * @import {RelativeTime} from '@agoric/time' - * @import {RelativeTimeValue} from '@agoric/time' - * @import {TimerService} from '@agoric/time' + * @import {Timestamp} from '@agoric/time'; + * @import {TimestampRecord} from '@agoric/time'; + * @import {TimestampValue} from '@agoric/time'; + * @import {RelativeTime} from '@agoric/time'; + * @import {RelativeTimeValue} from '@agoric/time'; + * @import {TimerService} from '@agoric/time'; * * @typedef {object} Handler * Handler is a user-provided Far object with .wake(time) used for callbacks diff --git a/packages/inter-protocol/src/proposals/utils.js b/packages/inter-protocol/src/proposals/utils.js index f632713cc7e..f0c00e9e18e 100644 --- a/packages/inter-protocol/src/proposals/utils.js +++ b/packages/inter-protocol/src/proposals/utils.js @@ -3,7 +3,7 @@ import { E } from '@endo/far'; import { WalletName } from '@agoric/internal'; import { getCopyMapEntries, makeCopyMap } from '@agoric/store'; -/** @import {CopyMap} from '@endo/patterns' */ +/** @import {CopyMap} from '@endo/patterns'; */ /** * @param {ERef} nameAdmin diff --git a/packages/vats/src/lib-board.js b/packages/vats/src/lib-board.js index f450d8e8cde..6faadaa337c 100644 --- a/packages/vats/src/lib-board.js +++ b/packages/vats/src/lib-board.js @@ -80,7 +80,7 @@ const calcCrc = (data, crcDigits) => { /** * @typedef {ReturnType} BoardState // TODO: use * Key from @agoric/store when available - * @import {Passable} from '@endo/marshal' + * @import {Passable} from '@endo/marshal'; * @see {prepareExoClassKit} * @see {@link ../../SwingSet/docs/virtual-objects.md|SwingSet Virtual Objects} Hoisting this function makes defining the state type concise. */ diff --git a/packages/vats/src/vat-bank.js b/packages/vats/src/vat-bank.js index 5ef7d657081..e7dd101408f 100644 --- a/packages/vats/src/vat-bank.js +++ b/packages/vats/src/vat-bank.js @@ -22,8 +22,9 @@ import { } from './virtual-purse.js'; /** - * @import {Guarded} from '@endo/exo' - * @import {Passable, RemotableObject} from '@endo/pass-style' + * @import {Guarded} from '@endo/exo'; + * @import {Passable, RemotableObject} from '@endo/pass-style'; + * @import {VirtualPurseController} from './virtual-purse.js'; */ const { VirtualPurseControllerI } = makeVirtualPurseKitIKit(); @@ -37,7 +38,6 @@ const BridgeChannelI = M.interface('BridgeChannel', { /** * @typedef {Awaited>>} VirtualPurse - * @import {VirtualPurseController} from './virtual-purse.js' */ /** From 02ff11e5adacc75e017cdd1111e337b5c3c4f1ae Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Fri, 12 Jul 2024 10:47:03 -0400 Subject: [PATCH 4/4] chore: Remove stale commentary --- packages/vats/src/lib-board.js | 3 --- 1 file changed, 3 deletions(-) diff --git a/packages/vats/src/lib-board.js b/packages/vats/src/lib-board.js index 6faadaa337c..69c0dc7ed41 100644 --- a/packages/vats/src/lib-board.js +++ b/packages/vats/src/lib-board.js @@ -80,9 +80,6 @@ const calcCrc = (data, crcDigits) => { /** * @typedef {ReturnType} BoardState // TODO: use * Key from @agoric/store when available - * @import {Passable} from '@endo/marshal'; - * @see {prepareExoClassKit} - * @see {@link ../../SwingSet/docs/virtual-objects.md|SwingSet Virtual Objects} Hoisting this function makes defining the state type concise. */ // TODO consider tightening initSequence to bigint only