diff --git a/docs/typescript.md b/docs/typescript.md index 9f275b0411f..71ea63bc8f2 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -1,17 +1,12 @@ # usage of TypeScript -Our use of TypeScript has to accomodate both .js development in agoric-sdk (which cannot import types) and .ts development of consumers of agoric-sdk packages (which can import types). For .js development, we want ambient (global) types so that we don't have to precede each type reference by an import. For .ts development, we want exports from modules so we don't pollute a global namespace. - -This means we need two definition files. We could keep those both in SCM, but that would cause more confusion and risk them getting out of sync. We could have one be defined in terms of the other, but since there is no way to reexport to global namespace, it would have to be a secondary definition in the primary. This would typecheck because TS is structurally typed, but the secondary would lose all the documentation on the types. - -So our best solution is to have one source of truth for the types and auto-generate for one case from the other. We've chosen to have the ambient types as the source of truth so the SDK development can use them. The SDK consumption can have a build step during packaging, and that's when we make the exported (non-ambient) types. +Our use of TypeScript has to accomodate both .js development in agoric-sdk (which could not import types until TS 5.5) and .ts development of consumers of agoric-sdk packages (which could always import types). For .js development, we have many ambient (global) types so that we don't have to precede each type reference by an import. For .ts development, we want exports from modules so we don't pollute a global namespace. We are slowly transitioning away from ambient types. ## Best practices -- `src/types-ambient.js` defines types of the package -- `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 +- package entrypoint(s) exports explicit types +- for packages upon which other packages expect ambient types: + - `exported.d.ts` exports the explicit types and ambient re-exports ## Generating API docs diff --git a/packages/ERTP/exported.d.ts b/packages/ERTP/exported.d.ts index 5f8115fd82e..45d5d6528db 100644 --- a/packages/ERTP/exported.d.ts +++ b/packages/ERTP/exported.d.ts @@ -1,16 +1,12 @@ /* eslint-disable -- doesn't understand .d.ts */ -/** - * @file re-export types into global namespace, for consumers that expect these - * to be ambient - */ -// export everything export * from './src/types.js'; // XXX re-export types into global namespace, for consumers that expect these to // be ambient. Why the _ prefix? Because without it TS gets confused between the // import and export symbols. h/t https://stackoverflow.com/a/66588974 // Note one big downside vs ambients is that these types will appear to be on `globalThis`. +// UNTIL https://github.com/Agoric/agoric-sdk/issues/6512 import { Amount as _Amount, Brand as _Brand, diff --git a/packages/ERTP/tsconfig.json b/packages/ERTP/tsconfig.json index b8b77ea8bc3..6ae6211ef04 100644 --- a/packages/ERTP/tsconfig.json +++ b/packages/ERTP/tsconfig.json @@ -5,8 +5,10 @@ "maxNodeModuleJsDepth": 1, }, "include": [ - // omit exported.js because 1) it's empty and would overwrite exported.d.ts - // and 2) because it's only for consumption in other packages + // omit exported.js because 1) it need not be included in the typecheck of + // this package because it's only consumed by other packages and 2) + // including it causes the empty exported.js to overwrite the manual + // exported.d.ts (which doesn't need any building) "src/**/*.js", "src/**/*.ts", "test" diff --git a/packages/agoric-cli/src/commands/auction.js b/packages/agoric-cli/src/commands/auction.js index 3144a01220e..78e3d8a8515 100644 --- a/packages/agoric-cli/src/commands/auction.js +++ b/packages/agoric-cli/src/commands/auction.js @@ -6,11 +6,9 @@ import { outputActionAndHint } from '../lib/wallet.js'; const { Fail } = assert; -/** @import {ParamTypesMap} from '@agoric/governance/src/contractGovernance/typedParamManager.js' */ - /** - * @template {ParamStateRecord} M - * @typedef {import('@agoric/governance/src/contractGovernance/typedParamManager.js').ParamTypesMapFromRecord} ParamTypesMapFromRecord + * @import {ParamTypesMap, ParamTypesMapFromRecord} from '@agoric/governance/src/contractGovernance/typedParamManager.js' + * @import {ParamValueForType} from '@agoric/governance/src/types.js' */ /** diff --git a/packages/agoric-cli/src/commands/gov.js b/packages/agoric-cli/src/commands/gov.js index b2163696c5d..26a2f111927 100644 --- a/packages/agoric-cli/src/commands/gov.js +++ b/packages/agoric-cli/src/commands/gov.js @@ -13,7 +13,10 @@ import { sendAction, } from '../lib/wallet.js'; -/** @import {OfferSpec} from '@agoric/smart-wallet/src/offers.js' */ +/** + * @import {OfferSpec} from '@agoric/smart-wallet/src/offers.js' + * @import {QuestionDetails} from '@agoric/governance/src/types.js' + */ const collectValues = (val, memo) => { memo.push(val); diff --git a/packages/governance/exported.d.ts b/packages/governance/exported.d.ts new file mode 100644 index 00000000000..1cc353ee415 --- /dev/null +++ b/packages/governance/exported.d.ts @@ -0,0 +1,37 @@ +/* eslint-disable -- doesn't understand .d.ts */ + +export * from './src/types.js'; + +// XXX re-export types into global namespace, for consumers that expect these to +// be ambient. Why the _ prefix? Because without it TS gets confused between the +// import and export symbols. h/t https://stackoverflow.com/a/66588974 +// Note one big downside vs ambients is that these types will appear to be on `globalThis`. +// UNTIL https://github.com/Agoric/agoric-sdk/issues/6512 +import { + GovernanceFacetKit as _GovernanceFacetKit, + GovernanceTerms as _GovernanceTerms, + GovernorCreatorFacet as _GovernorCreatorFacet, + GovernanceSubscriptionState as _GovernanceSubscriptionState, + GovernorStartedInstallationKit as _GovernorStartedInstallationKit, + GovernedCreatorFacet as _GovernedCreatorFacet, + ParamStateRecord as _ParamStateRecord, + GovernedPublicFacet as _GovernedPublicFacet, + CommitteeElectoratePublic as _CommitteeElectoratePublic, + GovernedApis as _GovernedApis, + GovernableStartFn as _GovernableStartFn, +} from './src/types.js'; +declare global { + export { + _CommitteeElectoratePublic as CommitteeElectoratePublic, + _GovernableStartFn as GovernableStartFn, + _GovernanceFacetKit as GovernanceFacetKit, + _GovernanceSubscriptionState as GovernanceSubscriptionState, + _GovernanceTerms as GovernanceTerms, + _GovernedApis as GovernedApis, + _GovernedCreatorFacet as GovernedCreatorFacet, + _GovernedPublicFacet as GovernedPublicFacet, + _GovernorCreatorFacet as GovernorCreatorFacet, + _GovernorStartedInstallationKit as GovernorStartedInstallationKit, + _ParamStateRecord as ParamStateRecord, + }; +} diff --git a/packages/governance/exported.js b/packages/governance/exported.js index e6bb3f69af2..469002eeeed 100644 --- a/packages/governance/exported.js +++ b/packages/governance/exported.js @@ -1 +1 @@ -import './src/types-ambient.js'; +// Dummy file for .d.ts twin to declare ambients diff --git a/packages/governance/package.json b/packages/governance/package.json index 841690335d5..a0dd3d4f7f8 100644 --- a/packages/governance/package.json +++ b/packages/governance/package.json @@ -10,8 +10,8 @@ "scripts": { "build": "yarn build:bundles", "build:bundles": "node ./scripts/build-bundles.js", - "prepack": "echo \"export {}; \" | cat - src/types-ambient.js > src/types.js && tsc --build --clean tsconfig.build.json", - "postpack": "git clean -f '*.d.ts*' src/types.js", + "prepack": "tsc --build tsconfig.build.json", + "postpack": "git clean -f '*.d.ts*'", "test": "ava", "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js", "test:xs": "exit 0", @@ -61,6 +61,7 @@ "src/", "tools/", "exported.js", + "exported.d.ts", "NEWS.md" ], "ava": { diff --git a/packages/governance/src/binaryVoteCounter.js b/packages/governance/src/binaryVoteCounter.js index ad0452907db..1ffa4ee7d43 100644 --- a/packages/governance/src/binaryVoteCounter.js +++ b/packages/governance/src/binaryVoteCounter.js @@ -17,6 +17,10 @@ import { } from './typeGuards.js'; import { makeQuorumCounter } from './quorumCounter.js'; +/** + * @import {BuildVoteCounter, OutcomeRecord, Position, QuestionSpec, VoteStatistics} from './types.js'; + */ + const { Fail } = assert; const validateBinaryQuestionSpec = questionSpec => { diff --git a/packages/governance/src/breakTie.js b/packages/governance/src/breakTie.js index ac77da26121..c1489f9c588 100644 --- a/packages/governance/src/breakTie.js +++ b/packages/governance/src/breakTie.js @@ -1,3 +1,7 @@ +/** + * @import {Position} from './types.js'; + */ + /** * Randomly shuffle an array * https://stackoverflow.com/a/12646864 diff --git a/packages/governance/src/closingRule.js b/packages/governance/src/closingRule.js index 7d7252a96bc..f7cc2b4c48e 100644 --- a/packages/governance/src/closingRule.js +++ b/packages/governance/src/closingRule.js @@ -5,6 +5,10 @@ import { E } from '@endo/eventual-send'; import { Far } from '@endo/marshal'; +/** + * @import {CloseVoting} from './types.js'; + */ + /** @type {CloseVoting} */ export const scheduleClose = (closingRule, closeVoting) => { const { timer, deadline } = closingRule; diff --git a/packages/governance/src/committee.js b/packages/governance/src/committee.js index 17d496dc928..4fd70deafa9 100644 --- a/packages/governance/src/committee.js +++ b/packages/governance/src/committee.js @@ -16,6 +16,10 @@ import { QuorumRule } from './question.js'; import { ElectorateCreatorI, ElectoratePublicI } from './typeGuards.js'; import { prepareVoterKit } from './voterKit.js'; +/** + * @import {ElectorateCreatorFacet, CommitteeElectoratePublic, QuestionDetails, OutcomeRecord, AddQuestion} from './types.js'; + */ + const { ceilDivide } = natSafeMath; /** diff --git a/packages/governance/src/contractGovernance/governApi.js b/packages/governance/src/contractGovernance/governApi.js index 3dd00a37405..386e89e801e 100644 --- a/packages/governance/src/contractGovernance/governApi.js +++ b/packages/governance/src/contractGovernance/governApi.js @@ -9,6 +9,10 @@ import { coerceQuestionSpec, } from '../question.js'; +/** + * @import {Position, ApiGovernor, ApiInvocationIssue, PoserFacet, VoteOnApiInvocation} from '../types.js'; + */ + const { Fail, quote: q } = assert; /** diff --git a/packages/governance/src/contractGovernance/governFilter.js b/packages/governance/src/contractGovernance/governFilter.js index 9898434e8ce..293f6dc65e9 100644 --- a/packages/governance/src/contractGovernance/governFilter.js +++ b/packages/governance/src/contractGovernance/governFilter.js @@ -10,6 +10,10 @@ import { coerceQuestionSpec, } from '../question.js'; +/** + * @import {Position, ApiGovernor, ApiInvocationIssue, PoserFacet, VoteOnApiInvocation, FilterGovernor, GovernedCreatorFacet, OfferFilterIssue, VoteOnOfferFilter} from '../types.js'; + */ + /** * Make a pair of positions for a question about whether to update the offer * filter. If the vote passes, the list of blocked invitation strings will be diff --git a/packages/governance/src/contractGovernance/governParam.js b/packages/governance/src/contractGovernance/governParam.js index 3b8623a5cda..003877c0ae3 100644 --- a/packages/governance/src/contractGovernance/governParam.js +++ b/packages/governance/src/contractGovernance/governParam.js @@ -9,6 +9,9 @@ import { QuorumRule, } from '../question.js'; import { ParamChangesQuestionDetailsShape } from '../typeGuards.js'; +/** + * @import {ParamValue, ParamChangePositions, QuestionSpec, ChangeParamsPosition, ParamChangeIssue, ParamGovernor, ParamManagerRetriever, PoserFacet, VoteOnParamChanges} from '../types.js'; + */ const { Fail } = assert; diff --git a/packages/governance/src/contractGovernance/paramManager.js b/packages/governance/src/contractGovernance/paramManager.js index 0b5219c55e0..515e7579f5a 100644 --- a/packages/governance/src/contractGovernance/paramManager.js +++ b/packages/governance/src/contractGovernance/paramManager.js @@ -18,6 +18,10 @@ import { } from './assertions.js'; import { CONTRACT_ELECTORATE } from './governParam.js'; +/** + * @import {AnyParamManager, GovernanceSubscriptionState, ParamManagerBase, ParamStateRecord, ParamValueTyped, UpdateParams} from '../types.js'; + */ + const { Fail, quote: q } = assert; /** @@ -90,7 +94,7 @@ const makeParamManagerBuilder = (publisherKit, zoe) => { * @param {Keyword} name * @param {unknown} value * @param {(val) => void} assertion - * @param {ParamType} type + * @param {import('../constants.js').ParamType} type */ const buildCopyParam = (name, value, assertion, type) => { let current; diff --git a/packages/governance/src/contractGovernance/typedParamManager.js b/packages/governance/src/contractGovernance/typedParamManager.js index 5ec693ce7a6..57871b2f5de 100644 --- a/packages/governance/src/contractGovernance/typedParamManager.js +++ b/packages/governance/src/contractGovernance/typedParamManager.js @@ -5,6 +5,11 @@ import { makeParamManagerBuilder } from './paramManager.js'; const { Fail, quote: q } = assert; +/** + * @import {VoteCounterCreatorFacet, VoteCounterPublicFacet, QuestionSpec, OutcomeRecord, AddQuestion, AddQuestionReturn, GovernanceSubscriptionState, GovernanceTerms, ParamManagerBase, ParamStateRecord, ParamValueForType, UpdateParams} from '../types.js'; + * @import {ParamType} from '../constants.js'; + */ + /** * @typedef {Record} ParamTypesMap */ diff --git a/packages/governance/src/contractGovernor.js b/packages/governance/src/contractGovernor.js index e1e4833bf0d..8708ecbe055 100644 --- a/packages/governance/src/contractGovernor.js +++ b/packages/governance/src/contractGovernor.js @@ -7,6 +7,10 @@ import { CONTRACT_ELECTORATE } from './contractGovernance/governParam.js'; import { prepareContractGovernorKit } from './contractGovernorKit.js'; import { ParamChangesQuestionDetailsShape } from './typeGuards.js'; +/** + * @import {GovernableStartFn, GovernorCreatorFacet, GovernorPublic, ParamChangeIssueDetails} from './types.js'; + */ + const { Fail } = assert; const trace = makeTracer('CGov', false); diff --git a/packages/governance/src/contractGovernorKit.js b/packages/governance/src/contractGovernorKit.js index 17a12fc8a99..3bdf7e7bf6a 100644 --- a/packages/governance/src/contractGovernorKit.js +++ b/packages/governance/src/contractGovernorKit.js @@ -16,6 +16,10 @@ import { } from './contractGovernance/governParam.js'; import { ClosingRuleShape, ParamChangesSpecShape } from './typeGuards.js'; +/** + * @import {VoteCounterCreatorFacet, VoteCounterPublicFacet, QuestionSpec, OutcomeRecord, AddQuestion, AddQuestionReturn, ClosingRule, GovernableStartFn, LimitedCF, PoserFacet, VoteOnApiInvocation, VoteOnOfferFilter, VoteOnParamChanges} from './types.js'; + */ + const trace = makeTracer('CGK', false); const ContractGovernorKitI = { diff --git a/packages/governance/src/contractHelper.js b/packages/governance/src/contractHelper.js index 894f6f041d0..4b4486e693e 100644 --- a/packages/governance/src/contractHelper.js +++ b/packages/governance/src/contractHelper.js @@ -10,6 +10,10 @@ import { assertElectorateMatches } from './contractGovernance/paramManager.js'; import { makeParamManagerFromTerms } from './contractGovernance/typedParamManager.js'; import { GovernorFacetShape } from './typeGuards.js'; +/** + * @import {VoteCounterCreatorFacet, VoteCounterPublicFacet, QuestionSpec, OutcomeRecord, AddQuestion, AddQuestionReturn, GovernanceSubscriptionState, GovernanceTerms, GovernedApis, GovernedCreatorFacet, GovernedPublicFacet} from './types.js'; + */ + const { Fail, quote: q } = assert; export const GOVERNANCE_STORAGE_KEY = 'governance'; diff --git a/packages/governance/src/electorateTools.js b/packages/governance/src/electorateTools.js index ecb8cd2424d..301aaa8c9a9 100644 --- a/packages/governance/src/electorateTools.js +++ b/packages/governance/src/electorateTools.js @@ -2,6 +2,10 @@ import { EmptyProposalShape } from '@agoric/zoe/src/typeGuards.js'; import { E } from '@endo/eventual-send'; import { deeplyFulfilled, Far } from '@endo/marshal'; +/** + * @import {VoteCounterCreatorFacet, VoteCounterPublicFacet, QuestionSpec, OutcomeRecord, AddQuestion, AddQuestionReturn} from './types.js'; + */ + /** * @typedef {object} QuestionRecord * @property {ERef} voteCap diff --git a/packages/governance/src/index.js b/packages/governance/src/index.js index 62a486fdadb..7c527d3789f 100644 --- a/packages/governance/src/index.js +++ b/packages/governance/src/index.js @@ -1,6 +1,8 @@ -/// -/// -/// +// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512 +import '@agoric/ertp/exported.js'; +import '@agoric/zoe/src/contractFacet/types-ambient.js'; +import '@agoric/zoe/tools/types-ambient.js'; +import '@agoric/zoe/src/types.js'; /// diff --git a/packages/governance/src/multiCandidateVoteCounter.js b/packages/governance/src/multiCandidateVoteCounter.js index d7615e41f4e..6478501bad8 100644 --- a/packages/governance/src/multiCandidateVoteCounter.js +++ b/packages/governance/src/multiCandidateVoteCounter.js @@ -18,6 +18,10 @@ import { import { makeQuorumCounter } from './quorumCounter.js'; import { breakTie } from './breakTie.js'; +/** + * @import {QuestionSpec, BuildMultiVoteCounter, MultiOutcomeRecord, Position, VoteStatistics} from './types.js'; + */ + const { Fail } = assert; const validateQuestionSpec = questionSpec => { diff --git a/packages/governance/src/noActionElectorate.js b/packages/governance/src/noActionElectorate.js index b18314f99d8..cfde5182e46 100644 --- a/packages/governance/src/noActionElectorate.js +++ b/packages/governance/src/noActionElectorate.js @@ -5,6 +5,10 @@ import { EmptyProposalShape } from '@agoric/zoe/src/typeGuards.js'; import { ElectoratePublicI, ElectorateCreatorI } from './typeGuards.js'; +/** + * @import {ElectoratePublic, ElectorateCreatorFacet} from './types.js'; + */ + /** * This Electorate visibly has no members, takes no votes, and approves no * changes. diff --git a/packages/governance/src/question.js b/packages/governance/src/question.js index 270530cfb2b..b3684597e1b 100644 --- a/packages/governance/src/question.js +++ b/packages/governance/src/question.js @@ -3,6 +3,10 @@ import { makeHandle } from '@agoric/zoe/src/makeHandle.js'; import { QuestionI, QuestionSpecShape } from './typeGuards.js'; +/** + * @import {BuildQuestion, PositionIncluded, Question, QuestionSpec} from './types.js'; + */ + // Topics being voted on are 'Questions'. Before a Question is known to a // electorate, the parameters can be described with a QuestionSpec. Once the // question has been presented to an Electorate, there is a QuestionDetails diff --git a/packages/governance/src/quorumCounter.js b/packages/governance/src/quorumCounter.js index 762a70bcd83..63654ea457a 100644 --- a/packages/governance/src/quorumCounter.js +++ b/packages/governance/src/quorumCounter.js @@ -2,6 +2,10 @@ import { Far } from '@endo/marshal'; +/** + * @import {QuorumCounter} from './types.js'; + */ + export const makeQuorumCounter = quorumThreshold => { const check = stats => { const votes = stats.results.reduce( diff --git a/packages/governance/src/types-ambient.js b/packages/governance/src/types.js similarity index 99% rename from packages/governance/src/types-ambient.js rename to packages/governance/src/types.js index 3c4aba559a4..23a80c4c5c5 100644 --- a/packages/governance/src/types-ambient.js +++ b/packages/governance/src/types.js @@ -1,3 +1,5 @@ +export {}; + /** * @typedef { 'unranked' | 'order' | 'plurality' } ChoiceMethod * * UNRANKED: "unranked voting" means that the voter specifies some number of diff --git a/packages/governance/src/validators.js b/packages/governance/src/validators.js index 40228bff729..04b358ff1a4 100644 --- a/packages/governance/src/validators.js +++ b/packages/governance/src/validators.js @@ -2,6 +2,10 @@ import { E } from '@endo/eventual-send'; const { Fail, quote: q } = assert; +/** + * @import {VoteCounterCreatorFacet, VoteCounterPublicFacet, QuestionSpec, OutcomeRecord, AddQuestion, AddQuestionReturn, AssertContractGovernance, AssertContractElectorate} from './types.js'; + */ + /** * Assert that the governed contract was started by the governor. Throws if * either direction can't be established. If the call succeeds, then the diff --git a/packages/governance/src/voterKit.js b/packages/governance/src/voterKit.js index fcabc962671..7dea9b257ba 100644 --- a/packages/governance/src/voterKit.js +++ b/packages/governance/src/voterKit.js @@ -3,6 +3,10 @@ import { defineDurableHandle } from '@agoric/zoe/src/makeHandle.js'; import { E } from '@endo/eventual-send'; import { PositionShape, QuestionHandleShape } from './typeGuards.js'; +/** + * @import {VoteCounterCreatorFacet, VoteCounterPublicFacet, QuestionSpec, OutcomeRecord, AddQuestion, AddQuestionReturn, CompletedBallet, Position} from './types.js'; + */ + const VoterI = M.interface('voter', { castBallotFor: M.call(QuestionHandleShape, M.arrayOf(PositionShape)).returns( M.promise(), diff --git a/packages/governance/test/swingsetTests/committeeBinary/bootstrap.js b/packages/governance/test/swingsetTests/committeeBinary/bootstrap.js index dd7d527cf40..0eba1be0f9f 100644 --- a/packages/governance/test/swingsetTests/committeeBinary/bootstrap.js +++ b/packages/governance/test/swingsetTests/committeeBinary/bootstrap.js @@ -11,6 +11,10 @@ import { } from '../../../src/index.js'; import { remoteNullMarshaller } from '../utils.js'; +/** + * @import {QuestionDetails} from '../../../src/types.js'; + */ + const { quote: q } = assert; const makeVoterVat = async (log, vats, zoe) => { diff --git a/packages/governance/test/swingsetTests/committeeBinary/vat-voter.js b/packages/governance/test/swingsetTests/committeeBinary/vat-voter.js index 652a26156bf..25ce219568b 100644 --- a/packages/governance/test/swingsetTests/committeeBinary/vat-voter.js +++ b/packages/governance/test/swingsetTests/committeeBinary/vat-voter.js @@ -3,6 +3,10 @@ import { keyEQ } from '@agoric/store'; import { E } from '@endo/eventual-send'; import { Far } from '@endo/marshal'; +/** + * @import {CommitteeElectoratePublic, Issue} from '../../../src/types.js'; + */ + const { quote: q } = assert; /** diff --git a/packages/governance/test/swingsetTests/contractGovernor/bootstrap.js b/packages/governance/test/swingsetTests/contractGovernor/bootstrap.js index 4d7dae1ae9f..0f1e830bae8 100644 --- a/packages/governance/test/swingsetTests/contractGovernor/bootstrap.js +++ b/packages/governance/test/swingsetTests/contractGovernor/bootstrap.js @@ -11,6 +11,10 @@ import { import { remoteNullMarshaller } from '../utils.js'; import { makeTerms, MALLEABLE_NUMBER } from './governedContract.js'; +/** + * @import {ContractGovernanceVoteResult, GovernedPublicFacetMethods, GovernorCreatorFacet, ParamChangesSpec, QuestionDetails, SimpleIssue, StandardParamPath} from '../../../src/types.js'; + */ + const { quote: q } = assert; /** diff --git a/packages/governance/test/swingsetTests/contractGovernor/governedContract.js b/packages/governance/test/swingsetTests/contractGovernor/governedContract.js index e51ddb6bac3..b0231c0c78e 100644 --- a/packages/governance/test/swingsetTests/contractGovernor/governedContract.js +++ b/packages/governance/test/swingsetTests/contractGovernor/governedContract.js @@ -2,6 +2,10 @@ import { handleParamGovernance } from '../../../src/contractHelper.js'; import { ParamTypes } from '../../../src/index.js'; import { CONTRACT_ELECTORATE } from '../../../src/contractGovernance/governParam.js'; +/** + * @import {GovernanceTerms} from '../../../src/types.js'; + */ + const MALLEABLE_NUMBER = 'MalleableNumber'; const makeTerms = (number, invitationAmount) => { diff --git a/packages/governance/test/unitTests/test-committee.js b/packages/governance/test/unitTests/test-committee.js index 421bc944317..d525cf01d7a 100644 --- a/packages/governance/test/unitTests/test-committee.js +++ b/packages/governance/test/unitTests/test-committee.js @@ -20,6 +20,10 @@ import { import { documentStorageSchema } from '../../tools/storageDoc.js'; import { remoteNullMarshaller } from '../swingsetTests/utils.js'; +/** + * @import {SimpleIssue} from '../../src/types.js'; + */ + const filename = new URL(import.meta.url).pathname; const dirname = path.dirname(filename); diff --git a/packages/governance/test/unitTests/test-multiCandidateBallotCount.js b/packages/governance/test/unitTests/test-multiCandidateBallotCount.js index b63f514aaff..8447a0e8c7c 100644 --- a/packages/governance/test/unitTests/test-multiCandidateBallotCount.js +++ b/packages/governance/test/unitTests/test-multiCandidateBallotCount.js @@ -17,6 +17,10 @@ import { } from '../../src/index.js'; import { makeMultiCandidateVoteCounter } from '../../src/multiCandidateVoteCounter.js'; +/** + * @import {Position} from '../../src/types.js'; + */ + const SIMPLE_ISSUE = harden({ text: 'Fish or Beef or Pork or Chicken or Duck?', }); diff --git a/packages/governance/test/unitTests/test-paramGovernance.js b/packages/governance/test/unitTests/test-paramGovernance.js index b096c7066f7..0d277e86156 100644 --- a/packages/governance/test/unitTests/test-paramGovernance.js +++ b/packages/governance/test/unitTests/test-paramGovernance.js @@ -14,6 +14,10 @@ import { CONTRACT_ELECTORATE, ParamTypes } from '../../src/index.js'; import { MALLEABLE_NUMBER } from '../swingsetTests/contractGovernor/governedContract.js'; import { remoteNullMarshaller } from '../swingsetTests/utils.js'; +/** + * @import {GovernedPublicFacet, SimpleIssue} from '../../src/types.js'; + */ + const voteCounterRoot = '../../src/binaryVoteCounter.js'; const governedRoot = '../swingsetTests/contractGovernor/governedContract.js'; const contractGovernorRoot = '../../src/contractGovernor.js'; diff --git a/packages/governance/test/unitTests/test-puppetContractGovernor.js b/packages/governance/test/unitTests/test-puppetContractGovernor.js index 5652669f07f..161cefe6a22 100644 --- a/packages/governance/test/unitTests/test-puppetContractGovernor.js +++ b/packages/governance/test/unitTests/test-puppetContractGovernor.js @@ -13,6 +13,10 @@ import { CONTRACT_ELECTORATE, ParamTypes } from '../../src/index.js'; import { setUpGovernedContract } from '../../tools/puppetGovernance.js'; import { MALLEABLE_NUMBER } from '../swingsetTests/contractGovernor/governedContract.js'; +/** + * @import {GovernedPublicFacet, SimpleIssue} from '../../src/types.js'; + */ + const makeBundle = async sourceRoot => { const url = await importMetaResolve(sourceRoot, import.meta.url); const path = new URL(url).pathname; diff --git a/packages/governance/tools/puppetContractGovernor.js b/packages/governance/tools/puppetContractGovernor.js index 2406d43ba0a..3f6db072a1d 100644 --- a/packages/governance/tools/puppetContractGovernor.js +++ b/packages/governance/tools/puppetContractGovernor.js @@ -1,5 +1,3 @@ -import '../src/types-ambient.js'; - import { E } from '@endo/eventual-send'; import { Far } from '@endo/marshal'; @@ -8,6 +6,10 @@ import { Fail } from '@agoric/assert'; import { CONTRACT_ELECTORATE } from '../src/contractGovernance/governParam.js'; import { makeApiInvocationPositions } from '../src/contractGovernance/governApi.js'; +/** + * @import {GovernableStartFn, ParamChangesSpec} from '../src/types.js'; + */ + // @file a version of the contractGovernor.js contract simplified for testing. // It removes the electorate and doesn't try to support legibility. // It maintains the API for the governed contract (parameters, apis, and filters) diff --git a/packages/governance/tools/puppetGovernance.js b/packages/governance/tools/puppetGovernance.js index 34a561d5477..47089b3f62a 100644 --- a/packages/governance/tools/puppetGovernance.js +++ b/packages/governance/tools/puppetGovernance.js @@ -3,6 +3,10 @@ import { E } from '@endo/eventual-send'; import { resolve as importMetaResolve } from 'import-meta-resolve'; import { CONTRACT_ELECTORATE, ParamTypes } from '../src/index.js'; +/** + * @import {GovernableStartFn} from '../src/types.js'; + */ + const makeBundle = async sourceRoot => { const url = await importMetaResolve(sourceRoot, import.meta.url); const path = new URL(url).pathname; diff --git a/packages/governance/tsconfig.json b/packages/governance/tsconfig.json index 07c5c8d917c..4d55b6427bf 100644 --- a/packages/governance/tsconfig.json +++ b/packages/governance/tsconfig.json @@ -4,7 +4,10 @@ "maxNodeModuleJsDepth": 2, }, "include": [ - "exported.js", + // omit exported.js because 1) it need not be included in the typecheck of + // this package because it's only consumed by other packages and 2) + // including it causes the empty exported.js to overwrite the manual + // exported.d.ts (which doesn't need any building) "build", "scripts", "src", diff --git a/packages/notifier/package.json b/packages/notifier/package.json index 3795c33fdca..47022af7d72 100644 --- a/packages/notifier/package.json +++ b/packages/notifier/package.json @@ -9,7 +9,7 @@ }, "scripts": { "build": "exit 0", - "prepack": "echo \"export {}; \" | cat - src/types-ambient.js > src/types.js && tsc --build --clean tsconfig.build.json", + "prepack": "echo \"export {}; \" | cat - src/types-ambient.js > src/types.js && tsc --build tsconfig.build.json", "postpack": "git clean -f '*.d.ts*' src/types.js", "test": "ava", "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js", diff --git a/packages/store/exported.d.ts b/packages/store/exported.d.ts index a081e84c2b2..eb3dc666582 100644 --- a/packages/store/exported.d.ts +++ b/packages/store/exported.d.ts @@ -1,15 +1,12 @@ /* eslint-disable -- doesn't understand .d.ts */ -/** - * @file re-export types into global namespace, for consumers that expect these - * to be ambient - */ -// export everything + export * from './src/types.js'; // XXX re-export types into global namespace, for consumers that expect these to // be ambient. Why the _ prefix? Because without it TS gets confused between the // import and export symbols. h/t https://stackoverflow.com/a/66588974 // Note one big downside vs ambients is that these types will appear to be on `globalThis`. +// UNTIL https://github.com/Agoric/agoric-sdk/issues/6512 import { LegacyMap as _LegacyMap, LegacyWeakMap as _LegacyWeakMap, diff --git a/packages/zoe/package.json b/packages/zoe/package.json index aa0f0752ca8..9c2f471d900 100644 --- a/packages/zoe/package.json +++ b/packages/zoe/package.json @@ -10,7 +10,7 @@ "scripts": { "build": "yarn build:bundles", "build:bundles": "node scripts/build-bundles.js", - "prepack": "echo \"export {}; \" | cat - tools/types-ambient.js > tools/types.js && tsc --build --clean tsconfig.build.json", + "prepack": "echo \"export {}; \" | cat - tools/types-ambient.js > tools/types.js && tsc --build tsconfig.build.json", "postpack": "git clean -f '*.d.ts*' tools/types.js", "test": "ava --verbose", "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js", diff --git a/packages/zoe/src/contracts/priceAggregator.js b/packages/zoe/src/contracts/priceAggregator.js index 72449cd99bb..555f5002f98 100644 --- a/packages/zoe/src/contracts/priceAggregator.js +++ b/packages/zoe/src/contracts/priceAggregator.js @@ -31,7 +31,6 @@ import { ratiosSame, } from '../contractSupport/ratio.js'; -/// /** * @import {LegacyMap} from '@agoric/store/exported.js' */ diff --git a/packages/zoe/src/zoeService/zoe.js b/packages/zoe/src/zoeService/zoe.js index 23438293b18..6234f1696c6 100644 --- a/packages/zoe/src/zoeService/zoe.js +++ b/packages/zoe/src/zoeService/zoe.js @@ -11,8 +11,6 @@ * validate that. */ -/// -/// /// import { E } from '@endo/eventual-send';