From 6178a6d129f88e27b17e790742b4fa9ac85d0909 Mon Sep 17 00:00:00 2001 From: Turadg Aleahmad Date: Tue, 28 Nov 2023 11:04:53 -0800 Subject: [PATCH 1/7] build: build-ts config --- package.json | 1 + tsconfig.build.json | 36 ++++++++++++++++++++++++++++++++++++ typings.d.ts | 6 ++++++ 3 files changed, 43 insertions(+) create mode 100644 tsconfig.build.json create mode 100644 typings.d.ts diff --git a/package.json b/package.json index 66bd1707106..8749c5fd652 100644 --- a/package.json +++ b/package.json @@ -77,6 +77,7 @@ "test:xs": "yarn workspaces run test:xs", "build": "yarn workspaces run build", "postinstall": "patch-package", + "build-ts": "tsc --build tsconfig.build.json", "build-xs-worker": "cd packages/xs-vat-worker && yarn build:xs-lin" }, "ava": { diff --git a/tsconfig.build.json b/tsconfig.build.json new file mode 100644 index 00000000000..c022baf2f8e --- /dev/null +++ b/tsconfig.build.json @@ -0,0 +1,36 @@ +/* Visit Visit https://www.typescriptlang.org/tsconfig to read more about this file */ +{ + "extends": [ + "./tsconfig.json", + "./tsconfig-build-options.json" + ], + "compilerOptions": { + "allowSyntheticDefaultImports": true, + "outDir": "./build" + }, + "exclude": [ + "packages/agoric-cli", + "packages/benchmark", + "packages/cosmic-swingset", + "packages/deployment", + "packages/import-manager", + "packages/solo", + "packages/stat-logger", + "packages/swingset-runner", + "packages/telemetry", + "packages/xsnap/moddable", + "packages/xsnap/xsnap-native", + "packages/xsnap-lockdown", + "**/build", + "**/dist", + "**/docs", + "**/*.umd.js", + "**/proposals", + "**/scripts", + "**/test" + ], + "include": [ + "./**/*.ts", + "packages/**/*.js" + ] +} diff --git a/typings.d.ts b/typings.d.ts new file mode 100644 index 00000000000..1a7de159427 --- /dev/null +++ b/typings.d.ts @@ -0,0 +1,6 @@ +// XXX retrofits for type deficiencies in external packages + +declare module '@endo/nat' { + export function Nat(specimen: unknown): bigint; + export function isNat(specimen: unknown): boolean; +} From 3368e9e0703e0ad926014420531941af852b3f0e Mon Sep 17 00:00:00 2001 From: Turadg Aleahmad Date: Tue, 28 Nov 2023 11:46:32 -0800 Subject: [PATCH 2/7] chore(types): misc fixes to build --- packages/SwingSet/src/kernel/state/kernelKeeper.js | 4 ++-- packages/boot/tools/supports.ts | 2 +- packages/cosmic-swingset/calc-rpcport.js | 2 ++ packages/internal/src/batched-deliver.js | 6 +++--- packages/swingset-liveslots/src/message.js | 6 +++--- packages/vat-data/src/index.js | 5 ++++- packages/vats/src/core/demoIssuers.js | 1 + packages/vats/src/core/types-ambient.d.ts | 1 + packages/vats/src/proposals/zcf-proposal.js | 2 +- 9 files changed, 18 insertions(+), 11 deletions(-) diff --git a/packages/SwingSet/src/kernel/state/kernelKeeper.js b/packages/SwingSet/src/kernel/state/kernelKeeper.js index b362774536d..656fcae1974 100644 --- a/packages/SwingSet/src/kernel/state/kernelKeeper.js +++ b/packages/SwingSet/src/kernel/state/kernelKeeper.js @@ -553,10 +553,10 @@ export default function makeKernelKeeper(kernelStorage, kernelSlog) { * Allocate a new koid. * * @param {string} ownerID - * @param {undefined | bigint} id + * @param {bigint} [id] * @returns {string} */ - function addKernelObject(ownerID, id = undefined) { + function addKernelObject(ownerID, id) { // providing id= is only for unit tests insistVatID(ownerID); if (id === undefined) { diff --git a/packages/boot/tools/supports.ts b/packages/boot/tools/supports.ts index 18bd4e1b138..e807ffc1aeb 100644 --- a/packages/boot/tools/supports.ts +++ b/packages/boot/tools/supports.ts @@ -25,7 +25,7 @@ import { import type { ExecutionContext as AvaT } from 'ava'; -import { makeRunUtils } from '@agoric/swingset-vat/tools/run-utils.ts'; +import { makeRunUtils } from '@agoric/swingset-vat/tools/run-utils.js'; const trace = makeTracer('BSTSupport', false); diff --git a/packages/cosmic-swingset/calc-rpcport.js b/packages/cosmic-swingset/calc-rpcport.js index 338e4bc9ac5..82ea5aa4664 100755 --- a/packages/cosmic-swingset/calc-rpcport.js +++ b/packages/cosmic-swingset/calc-rpcport.js @@ -11,6 +11,8 @@ import toml from '@iarna/toml'; const configString = fs.readFileSync(process.argv[2]).toString(); const config = toml.parse(configString); +// eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error +// @ts-ignore Property 'laddr' does not exist on type 'AnyJson' const { laddr } = config.rpc; // like tcp://0.0.0.0:26657 // eslint-disable-next-line no-useless-escape const m = laddr.match(/^tcp:\/\/([\d\.]+):(\d+)$/); diff --git a/packages/internal/src/batched-deliver.js b/packages/internal/src/batched-deliver.js index 64118422336..bdae61bb5e1 100644 --- a/packages/internal/src/batched-deliver.js +++ b/packages/internal/src/batched-deliver.js @@ -3,12 +3,12 @@ export const DEFAULT_BATCH_TIMEOUT_MS = 1000; /** - * @typedef {(message: any[], ackNum: number) => void} DeliverMessages + * @typedef {(message: any[], ackNum: number) => Promise} DeliverMessages */ /** * @param {DeliverMessages} deliver - * @param {{ clearTimeout: NodeJS.clearTimeout, setTimeout: NodeJS.setTimeout }} io + * @param {{ clearTimeout: import('node:timers').clearTimeout, setTimeout: import('node:timers').setTimeout }} io * @param {number} batchTimeoutMs */ export function makeBatchedDeliver( @@ -34,7 +34,7 @@ export function makeBatchedDeliver( // Transfer the batched messages to the deliver function. const msgs = batchedMessages; batchedMessages = []; - deliver(msgs, latestAckNum); + void deliver(msgs, latestAckNum); }, batchTimeoutMs); } diff --git a/packages/swingset-liveslots/src/message.js b/packages/swingset-liveslots/src/message.js index b6aa9a06922..fabc0e3120f 100644 --- a/packages/swingset-liveslots/src/message.js +++ b/packages/swingset-liveslots/src/message.js @@ -32,7 +32,7 @@ export function insistMessage(message) { /** * @param {unknown} vdo - * @returns {asserts vdo is VatDeliveryObject} + * @returns {asserts vdo is import('./types').VatDeliveryObject} */ export function insistVatDeliveryObject(vdo) { @@ -114,7 +114,7 @@ export function insistVatDeliveryResult(vdr) { /** * @param {unknown} vso - * @returns {asserts vso is VatSyscallObject} + * @returns {asserts vso is import('./types').VatSyscallObject} */ export function insistVatSyscallObject(vso) { @@ -194,7 +194,7 @@ export function insistVatSyscallObject(vso) { /** * @param {unknown} vsr - * @returns {asserts vsr is VatSyscallResult} + * @returns {asserts vsr is import('./types').VatSyscallResult} */ export function insistVatSyscallResult(vsr) { diff --git a/packages/vat-data/src/index.js b/packages/vat-data/src/index.js index ae46e743584..9218020dc09 100644 --- a/packages/vat-data/src/index.js +++ b/packages/vat-data/src/index.js @@ -42,10 +42,13 @@ export { prepareSingleton, } from './exo-utils.js'; -/** @typedef {import('@agoric/swingset-liveslots').Baggage} Baggage */ /** @typedef {import('@agoric/swingset-liveslots').DurableKindHandle} DurableKindHandle */ /** @template T @typedef {import('@agoric/swingset-liveslots').DefineKindOptions} DefineKindOptions */ +// Copy this type because aliasing it by `import('@agoric/swingset-liveslots').Baggage` +// causes this error in typedoc: Expected a symbol for node with kind Identifier +/** @typedef {MapStore} Baggage */ + // //////////////////////////// deprecated ///////////////////////////////////// /** diff --git a/packages/vats/src/core/demoIssuers.js b/packages/vats/src/core/demoIssuers.js index 432cb8033fd..24fe7c1addc 100644 --- a/packages/vats/src/core/demoIssuers.js +++ b/packages/vats/src/core/demoIssuers.js @@ -243,6 +243,7 @@ export const connectFaucet = async ({ }, produce: { mints }, }) => { + assert(mints); const vats = { mints: E(loadVat)('mints'), }; diff --git a/packages/vats/src/core/types-ambient.d.ts b/packages/vats/src/core/types-ambient.d.ts index 86c7691a84b..ebe8409cc9a 100644 --- a/packages/vats/src/core/types-ambient.d.ts +++ b/packages/vats/src/core/types-ambient.d.ts @@ -341,6 +341,7 @@ type ChainBootstrapSpaceT = { * Vault Factory. ONLY FOR DISASTER RECOVERY */ instancePrivateArgs: Map; + mints?: MintsVat; namesByAddress: import('../types.js').NameHub; namesByAddressAdmin: import('../types.js').NamesByAddressAdmin; pegasusConnections: import('@agoric/vats').NameHubKit; diff --git a/packages/vats/src/proposals/zcf-proposal.js b/packages/vats/src/proposals/zcf-proposal.js index e3fcb1868df..d27297e177d 100644 --- a/packages/vats/src/proposals/zcf-proposal.js +++ b/packages/vats/src/proposals/zcf-proposal.js @@ -3,7 +3,7 @@ import { E } from '@endo/far'; /** * @param {BootstrapPowers & { * consume: { - * vatAdminSvc: VatAdminSve; + * vatAdminSvc: VatAdminSvc; * vatStore: MapStore; * }; * }} powers From 81c63492f4afdd6ec8ed557d17e9d6bcbaceff8e Mon Sep 17 00:00:00 2001 From: Turadg Aleahmad Date: Tue, 28 Nov 2023 14:16:28 -0800 Subject: [PATCH 3/7] refactor: re-export objectMap from Endo --- packages/internal/src/utils.js | 48 ++-------------------------------- 1 file changed, 2 insertions(+), 46 deletions(-) diff --git a/packages/internal/src/utils.js b/packages/internal/src/utils.js index bbc2954fb50..02390ff7dcb 100644 --- a/packages/internal/src/utils.js +++ b/packages/internal/src/utils.js @@ -7,7 +7,7 @@ import { isPromise, makePromiseKit } from '@endo/promise-kit'; import { makeQueue } from '@endo/stream'; import { asyncGenerate, makeSet } from 'jessie.js'; -const { entries, fromEntries, keys, values } = Object; +const { fromEntries, keys, values } = Object; const { ownKeys } = Reflect; const { details: X, quote: q, Fail } = assert; @@ -42,51 +42,7 @@ export const fromUniqueEntries = allEntries => { }; harden(fromUniqueEntries); -/** - * By analogy with how `Array.prototype.map` will map the elements of - * an array to transformed elements of an array of the same shape, - * `objectMap` will do likewise for the string-named own enumerable - * properties of an object. - * - * Typical usage applies `objectMap` to a CopyRecord, i.e., - * an object for which `passStyleOf(original) === 'copyRecord'`. For these, - * none of the following edge cases arise. The result will be a CopyRecord - * with exactly the same property names, whose values are the mapped form of - * the original's values. - * - * When the original is not a CopyRecord, some edge cases to be aware of - * * No matter how mutable the original object, the returned object is - * hardened. - * * Only the string-named enumerable own properties of the original - * are mapped. All other properties are ignored. - * * If any of the original properties were accessors, `Object.entries` - * will cause its `getter` to be called and will use the resulting - * value. - * * No matter whether the original property was an accessor, writable, - * or configurable, all the properties of the returned object will be - * non-writable, non-configurable, data properties. - * * No matter what the original object may have inherited from, and - * no matter whether it was a special kind of object such as an array, - * the returned object will always be a plain object inheriting directly - * from `Object.prototype` and whose state is only these new mapped - * own properties. - * - * With these differences, even if the original object was not a CopyRecord, - * if all the mapped values are Passable, then the returned object will be - * a CopyRecord. - * - * @template {Record} O - * @param {O} original - * @template R map result - * @param {(value: O[keyof O], key: keyof O) => R} mapFn - * @returns {{ [P in keyof O]: R}} - */ -export const objectMap = (original, mapFn) => { - const ents = entries(original); - const mapEnts = ents.map(([k, v]) => [k, mapFn(v, k)]); - return harden(fromEntries(mapEnts)); -}; -harden(objectMap); +export { objectMap } from '@endo/patterns'; /** * @param {Array} leftNames From 37e9855108595c38567a2b9d54c29b3242471f37 Mon Sep 17 00:00:00 2001 From: Turadg Aleahmad Date: Tue, 28 Nov 2023 12:52:36 -0800 Subject: [PATCH 4/7] build: generate docs --- .gitignore | 1 + docs/typescript.md | 10 +++++ package.json | 2 + packages/ERTP/typedoc.json | 12 ++++++ packages/assert/typedoc.json | 9 +++++ packages/governance/typedoc.json | 11 ++++++ packages/inter-protocol/typedoc.json | 9 +++++ packages/notifier/typedoc.json | 8 ++++ packages/store/src/types.js | 6 ++- packages/store/typedoc.json | 9 +++++ packages/swingset-liveslots/README.md | 2 + packages/swingset-liveslots/typedoc.json | 10 +++++ packages/time/typedoc.json | 9 +++++ packages/vat-data/typedoc.json | 8 ++++ packages/zoe/typedoc.json | 16 ++++++++ tsconfig.json | 5 +-- typedoc.base.json | 4 ++ typedoc.json | 13 +++++++ yarn.lock | 49 +++++++++++++++++++++++- 19 files changed, 186 insertions(+), 7 deletions(-) create mode 100644 packages/ERTP/typedoc.json create mode 100644 packages/assert/typedoc.json create mode 100644 packages/governance/typedoc.json create mode 100644 packages/inter-protocol/typedoc.json create mode 100644 packages/notifier/typedoc.json create mode 100644 packages/store/typedoc.json create mode 100644 packages/swingset-liveslots/README.md create mode 100644 packages/swingset-liveslots/typedoc.json create mode 100644 packages/time/typedoc.json create mode 100644 packages/vat-data/typedoc.json create mode 100644 packages/zoe/typedoc.json create mode 100644 typedoc.base.json create mode 100644 typedoc.json diff --git a/.gitignore b/.gitignore index 6b27e826198..924317ab198 100644 --- a/.gitignore +++ b/.gitignore @@ -56,6 +56,7 @@ bundles bundle-*.js compiled dist +api-docs # misc /.vagrant diff --git a/docs/typescript.md b/docs/typescript.md index 84d8a3b6f1b..9f275b0411f 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -12,3 +12,13 @@ So our best solution is to have one source of truth for the types and auto-gener - `src/types.d.ts` is built automatically from types-ambient - `prepack` copies types-ambient.js to types.js and appends 'export {};' to turn it into a module, then builds - `postpack` deletes the new types.js and .d.ts files + +## Generating API docs + +We use [TypeDoc](https://typedoc.org/) to render API docs in HTML. + +```sh +yarn docs +open api-docs/index.html +``` + diff --git a/package.json b/package.json index 8749c5fd652..52b614d0b25 100644 --- a/package.json +++ b/package.json @@ -33,6 +33,7 @@ "prettier": "^3.0.3", "prettier-plugin-jsdoc": "^1.0.0", "type-coverage": "^2.26.3", + "typedoc": "^0.25.4", "typescript": "~5.2.2" }, "engines": { @@ -64,6 +65,7 @@ "scripts": { "clean": "yarn lerna run --no-bail clean", "check-dependencies": "node ./scripts/check-mismatched-dependencies.cjs", + "docs": "typedoc --tsconfig tsconfig.build.json", "lerna": "lerna", "link-cli": "yarn run create-agoric-cli", "create-agoric-cli": "node ./scripts/create-agoric-cli.cjs", diff --git a/packages/ERTP/typedoc.json b/packages/ERTP/typedoc.json new file mode 100644 index 00000000000..345e2c63f01 --- /dev/null +++ b/packages/ERTP/typedoc.json @@ -0,0 +1,12 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/index.js" + ], + "validation": { + "notExported": false, + "invalidLink": false, + } +} diff --git a/packages/assert/typedoc.json b/packages/assert/typedoc.json new file mode 100644 index 00000000000..e6544ff3b56 --- /dev/null +++ b/packages/assert/typedoc.json @@ -0,0 +1,9 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/assert.js", + "src/types.js", + ] +} diff --git a/packages/governance/typedoc.json b/packages/governance/typedoc.json new file mode 100644 index 00000000000..080a7259759 --- /dev/null +++ b/packages/governance/typedoc.json @@ -0,0 +1,11 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/index.js", + // FIXME hitting errors like: Failed to find JSDoc tag for ParamValueTyped after parsing comment, please file a bug report. + // "src/types-ambient.js", + "tools/puppetGovernance.js", + ] +} diff --git a/packages/inter-protocol/typedoc.json b/packages/inter-protocol/typedoc.json new file mode 100644 index 00000000000..5dc949e3a96 --- /dev/null +++ b/packages/inter-protocol/typedoc.json @@ -0,0 +1,9 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/index.js", + "src/clientSupport.js", + ] +} diff --git a/packages/notifier/typedoc.json b/packages/notifier/typedoc.json new file mode 100644 index 00000000000..ebbd5e24e8f --- /dev/null +++ b/packages/notifier/typedoc.json @@ -0,0 +1,8 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/index.js", + ] +} diff --git a/packages/store/src/types.js b/packages/store/src/types.js index d54e837a148..bad90d41be7 100644 --- a/packages/store/src/types.js +++ b/packages/store/src/types.js @@ -132,7 +132,8 @@ // ///////////////////////// Deprecated Legacy ///////////////////////////////// /** - * @template K,V + * @template K + * @template V * @typedef {object} LegacyWeakMap LegacyWeakMap is deprecated. Use WeakMapStore * instead if possible. * @property {(key: K) => boolean} has Check if a key exists @@ -145,7 +146,8 @@ */ /** - * @template K,V + * @template K + * @template V * @typedef {object} LegacyMap LegacyMap is deprecated. Use MapStore instead if * possible. * @property {(key: K) => boolean} has Check if a key exists diff --git a/packages/store/typedoc.json b/packages/store/typedoc.json new file mode 100644 index 00000000000..692e0a2090c --- /dev/null +++ b/packages/store/typedoc.json @@ -0,0 +1,9 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/index.js", + "src/types.js" + ] +} diff --git a/packages/swingset-liveslots/README.md b/packages/swingset-liveslots/README.md new file mode 100644 index 00000000000..65f2f0384f9 --- /dev/null +++ b/packages/swingset-liveslots/README.md @@ -0,0 +1,2 @@ +# SwingSet Liveslots + diff --git a/packages/swingset-liveslots/typedoc.json b/packages/swingset-liveslots/typedoc.json new file mode 100644 index 00000000000..148dc687071 --- /dev/null +++ b/packages/swingset-liveslots/typedoc.json @@ -0,0 +1,10 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/index.js", + "src/types.js", + "src/vatDataTypes.js", + ] +} diff --git a/packages/time/typedoc.json b/packages/time/typedoc.json new file mode 100644 index 00000000000..ab869aadef5 --- /dev/null +++ b/packages/time/typedoc.json @@ -0,0 +1,9 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/timeMath.js", + "src/types.js" + ] +} diff --git a/packages/vat-data/typedoc.json b/packages/vat-data/typedoc.json new file mode 100644 index 00000000000..ebbd5e24e8f --- /dev/null +++ b/packages/vat-data/typedoc.json @@ -0,0 +1,8 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/index.js", + ] +} diff --git a/packages/zoe/typedoc.json b/packages/zoe/typedoc.json new file mode 100644 index 00000000000..1998769b97c --- /dev/null +++ b/packages/zoe/typedoc.json @@ -0,0 +1,16 @@ +{ + "extends": [ + "../../typedoc.base.json" + ], + "entryPoints": [ + "src/contractSupport/index.js", + "src/contractSupport/types.js", + "src/contractFacet/types-ambient.d.ts", + "src/contractFacet/types.ts", + "src/zoeService/types.js", + "src/zoeService/utils.d.ts", + "src/zoeService/zoe.js", + "src/types.js", + "tools/manualTimer.js", + ] +} diff --git a/tsconfig.json b/tsconfig.json index bef3c4a60c1..5ce84c61a72 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -4,17 +4,16 @@ "module": "esnext", "moduleResolution": "node", "skipLibCheck": true, - "allowJs": true, "checkJs": true, "strict": false, "downlevelIteration": true, "strictNullChecks": true, "noImplicitThis": true, - "noEmit": true }, "include": [ - ".eslintrc.cjs" + ".eslintrc.cjs", + "dist" ] } diff --git a/typedoc.base.json b/typedoc.base.json new file mode 100644 index 00000000000..daa58cb2e56 --- /dev/null +++ b/typedoc.base.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "includeVersion": true +} diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 00000000000..685abaab401 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,13 @@ +{ + "entryPoints": [ + "packages/*" + ], + "exclude": [ + "packages/cosmic-proto/" + ], + "name": "API documentation of Agoric SDK ", + "entryPointStrategy": "packages", + "out": "api-docs", + "includeVersion": true, + "logLevel": "Verbose" +} diff --git a/yarn.lock b/yarn.lock index 7b051528ecc..154a8a6ed8c 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2633,6 +2633,11 @@ ansi-regex@^6.0.1: resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-6.0.1.tgz#3183e38fae9a65d7cb5e53945cd5897d0260a06a" integrity sha512-n5M855fKb2SsfMIiFFoVrABHJC8QtHwVx+mHWP3QcEqBHYienj5dHSgjbxtC0WEZXYt4wcD6zrQElDPhFuZgfA== +ansi-sequence-parser@^1.1.0: + version "1.1.1" + resolved "https://registry.yarnpkg.com/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz#e0aa1cdcbc8f8bb0b5bca625aac41f5f056973cf" + integrity sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg== + ansi-styles@^3.2.1: version "3.2.1" resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-3.2.1.tgz#41fbb20243e50b12be0f04b8dedbf07520ce841d" @@ -6136,7 +6141,7 @@ json5@^2.2.2: resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.3.tgz#78cd6f1a19bdc12b73db5ad0c61efd66c1e29283" integrity sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg== -jsonc-parser@3.2.0: +jsonc-parser@3.2.0, jsonc-parser@^3.2.0: version "3.2.0" resolved "https://registry.yarnpkg.com/jsonc-parser/-/jsonc-parser-3.2.0.tgz#31ff3f4c2b9793f89c67212627c51c6394f88e76" integrity sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w== @@ -6458,6 +6463,11 @@ lru-cache@^7.14.0, lru-cache@^7.4.4, lru-cache@^7.5.1, lru-cache@^7.7.1: resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-10.0.0.tgz#b9e2a6a72a129d81ab317202d93c7691df727e61" integrity sha512-svTf/fzsKHffP42sujkO/Rjs37BCIsQVRCeNYIm9WN8rgT7ffoUnRtZCqU+6BqcSBdv8gwJeTz8knJpgACeQMw== +lunr@^2.3.9: + version "2.3.9" + resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1" + integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow== + magic-string@^0.25.7: version "0.25.7" resolved "https://registry.yarnpkg.com/magic-string/-/magic-string-0.25.7.tgz#3f497d6fd34c669c6798dcb821f2ef31f5445051" @@ -6540,6 +6550,11 @@ map-obj@^4.0.0: resolved "https://registry.yarnpkg.com/map-obj/-/map-obj-4.3.0.tgz#9304f906e93faae70880da102a9f1df0ea8bb05a" integrity sha512-hdN1wVrZbb29eBGiGjJbeP8JbKjq1urkHJ/LIP/NY48MZ1QVXUsQBV1G1zvYFHn1XE06cwjBsOI2K3Ulnj1YXQ== +marked@^4.3.0: + version "4.3.0" + resolved "https://registry.yarnpkg.com/marked/-/marked-4.3.0.tgz#796362821b019f734054582038b116481b456cf3" + integrity sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A== + matcher@^5.0.0: version "5.0.0" resolved "https://registry.yarnpkg.com/matcher/-/matcher-5.0.0.tgz#cd82f1c7ae7ee472a9eeaf8ec7cac45e0fe0da62" @@ -6921,7 +6936,7 @@ minimatch@3.0.5: dependencies: brace-expansion "^1.1.7" -"minimatch@6 || 7 || 8 || 9", minimatch@^9.0.1: +"minimatch@6 || 7 || 8 || 9", minimatch@^9.0.1, minimatch@^9.0.3: version "9.0.3" resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.3.tgz#a6e00c3de44c3a542bfaae70abfc22420a6da825" integrity sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg== @@ -8698,6 +8713,16 @@ shell-quote@^1.6.1: resolved "https://registry.yarnpkg.com/shell-quote/-/shell-quote-1.7.3.tgz#aa40edac170445b9a431e17bb62c0b881b9c4123" integrity sha512-Vpfqwm4EnqGdlsBFNmHhxhElJYrdfcxPThu+ryKS5J8L/fhAwLazFZtq+S+TWZ9ANj2piSQLGj6NQg+lKPmxrw== +shiki@^0.14.1: + version "0.14.5" + resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.14.5.tgz#375dd214e57eccb04f0daf35a32aa615861deb93" + integrity sha512-1gCAYOcmCFONmErGTrS1fjzJLA7MGZmKzrBNX7apqSwhyITJg2O102uFzXUeBxNnEkDA9vHIKLyeKq0V083vIw== + dependencies: + ansi-sequence-parser "^1.1.0" + jsonc-parser "^3.2.0" + vscode-oniguruma "^1.7.0" + vscode-textmate "^8.0.0" + side-channel@^1.0.4: version "1.0.4" resolved "https://registry.yarnpkg.com/side-channel/-/side-channel-1.0.4.tgz#efce5c8fdc104ee751b25c58d4290011fa5ea2cf" @@ -9448,6 +9473,16 @@ typedarray@^0.0.6: resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777" integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c= +typedoc@^0.25.4: + version "0.25.4" + resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.4.tgz#5c2c0677881f504e41985f29d9aef0dbdb6f1e6f" + integrity sha512-Du9ImmpBCw54bX275yJrxPVnjdIyJO/84co0/L9mwe0R3G4FSR6rQ09AlXVRvZEGMUg09+z/usc8mgygQ1aidA== + dependencies: + lunr "^2.3.9" + marked "^4.3.0" + minimatch "^9.0.3" + shiki "^0.14.1" + "typescript@^3 || ^4": version "4.9.5" resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.9.5.tgz#095979f9bcc0d09da324d58d03ce8f8374cbe65a" @@ -9617,6 +9652,16 @@ vary@~1.1.2: resolved "https://registry.yarnpkg.com/vary/-/vary-1.1.2.tgz#2299f02c6ded30d4a5961b0b9f74524a18f634fc" integrity sha1-IpnwLG3tMNSllhsLn3RSShj2NPw= +vscode-oniguruma@^1.7.0: + version "1.7.0" + resolved "https://registry.yarnpkg.com/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz#439bfad8fe71abd7798338d1cd3dc53a8beea94b" + integrity sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA== + +vscode-textmate@^8.0.0: + version "8.0.0" + resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-8.0.0.tgz#2c7a3b1163ef0441097e0b5d6389cd5504b59e5d" + integrity sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg== + walk-up-path@^1.0.0: version "1.0.0" resolved "https://registry.yarnpkg.com/walk-up-path/-/walk-up-path-1.0.0.tgz#d4745e893dd5fd0dbb58dd0a4c6a33d9c9fec53e" From 5a82fb5b32be7318dc3c1368e6bdcb571a09fb83 Mon Sep 17 00:00:00 2001 From: Turadg Aleahmad Date: Tue, 28 Nov 2023 14:34:37 -0800 Subject: [PATCH 5/7] docs: demo annotations --- packages/assert/src/types.js | 3 ++- packages/governance/src/question.js | 1 + packages/notifier/src/storesub.js | 1 + 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/assert/src/types.js b/packages/assert/src/types.js index 6c53ce0a608..78ff6caf676 100644 --- a/packages/assert/src/types.js +++ b/packages/assert/src/types.js @@ -193,12 +193,13 @@ * payload itself is still passed unquoted to the console as it would be * without `quote`. * + * @example * For example, the following will reveal the expected sky color, but not the * actual incorrect sky color, in the thrown error's message: * ```js * sky.color === expectedColor || Fail`${sky.color} should be ${quote(expectedColor)}`; * ``` - * + * @example * The normal convention is to locally rename `details` to `X` and `quote` to `q` * like `const { details: X, quote: q } = assert;`, so the above example would then be * ```js diff --git a/packages/governance/src/question.js b/packages/governance/src/question.js index 801961dc9e1..270530cfb2b 100644 --- a/packages/governance/src/question.js +++ b/packages/governance/src/question.js @@ -41,6 +41,7 @@ const QuorumRule = /** @type {const} */ ({ const positionIncluded = (positions, p) => positions.some(e => keyEQ(e, p)); /** + * @internal * @param {QuestionSpec} allegedQuestionSpec * @returns {QuestionSpec} */ diff --git a/packages/notifier/src/storesub.js b/packages/notifier/src/storesub.js index 1068fa3379a..3389b2b6cb9 100644 --- a/packages/notifier/src/storesub.js +++ b/packages/notifier/src/storesub.js @@ -10,6 +10,7 @@ import { subscribeEach } from './subscribe.js'; /** * NB: does not yet survive upgrade https://github.com/Agoric/agoric-sdk/issues/6893 * + * @alpha * @template T * @param {Subscriber} subscriber * @param {(v: T) => void} consumeValue From cf66d243f597b987a357e13ca618f69eb674c958 Mon Sep 17 00:00:00 2001 From: Turadg Aleahmad Date: Tue, 28 Nov 2023 15:47:05 -0800 Subject: [PATCH 6/7] chore(types): misc fixes for tsdoc parsing --- packages/assert/src/types.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/assert/src/types.js b/packages/assert/src/types.js index 78ff6caf676..a4c287e4179 100644 --- a/packages/assert/src/types.js +++ b/packages/assert/src/types.js @@ -11,7 +11,7 @@ * @callback BaseAssert * The `assert` function itself. * - * @param {*} flag The truthy/falsy value + * @param {any} flag The truthy/falsy value * @param {Details} [optDetails] The details to throw * @param {ErrorConstructor} [ErrorConstructor] An optional alternate error * constructor to use. @@ -58,8 +58,8 @@ * The `assert.equal` method * * Assert that two values must be `Object.is`. - * @param {*} actual The value we received - * @param {*} expected What we wanted + * @param {any} actual The value we received + * @param {any} expected What we wanted * @param {Details} [optDetails] The details to throw * @param {ErrorConstructor} [ErrorConstructor] An optional alternate error * constructor to use. @@ -207,7 +207,7 @@ * ``` * * @callback AssertQuote - * @param {*} payload What to declassify + * @param {any} payload What to declassify * @param {(string|number)} [spaces] * @returns {StringablePayload} The declassified payload */ From d8cef7a56a73141dee06f83aedc064fa7dbc31e0 Mon Sep 17 00:00:00 2001 From: Turadg Aleahmad Date: Tue, 28 Nov 2023 16:17:38 -0800 Subject: [PATCH 7/7] ci: test building docs --- .github/workflows/test-all-packages.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/test-all-packages.yml b/.github/workflows/test-all-packages.yml index 871551fa2e4..2fbbbd5af0e 100644 --- a/.github/workflows/test-all-packages.yml +++ b/.github/workflows/test-all-packages.yml @@ -72,6 +72,9 @@ jobs: # eslint - name: yarn lint primary run: ./scripts/lint-with-types.sh primary + # build the API docs to verify it works + - name: build API docs + run: yarn docs lint-rest: timeout-minutes: 15