SCOPEconstno test imports itconst SCOPE: "@intellectual-frontiers"The scope of the packages of commons.
The package of a library of commons (commons 0032-libraries-by-concern FR-005, FR-013): the library's sources compiled by the TypeScript 7 compiler into ECMAScript modules and their declarations, the package.json that is published (each exports entry naming its types, the source for Bun and the compiled file for everything else), and the tarball. The same inspection that the packer makes before it packs is inspectPackage, which a test runs again on the tarball it unpacks.
bun tools/pack.ts of a library: pack dist/<scope>-<name>-<version>.tgz bun tools/pack.ts --check the same, and print what was found; exit 1 where anything was
A library's own package.json stays private and names its entries by their sources ("./src/mod.ts"); nothing is published from it by hand. A library that depends on another library of commons imports it by package name, and the published package depends on it at the version that library has in this repository. The declarations are written with .js specifiers (the compiler leaves .ts in a .d.ts, which a consumer's compiler cannot read), and only the declarations that the entries reach are published in a bundle. A package is refused where an entry has no declaration, where a declaration reached imports a file that is not in the package or a package that is not a dependency, or where the code imports a package that is not on npm.
A package that is also a command, or whose code imports what is not yet on npm, is packed with bundle: each entry's code and the command's are one bundle (bun build), the declarations are emitted from the sources and only those the entries reach are published, and whatever they import must be a package of npm that the package depends on.
SCOPEconstno test imports itconst SCOPE: "@intellectual-frontiers"The scope of the packages of commons.
Findingstypeno test imports ittype Findings = readonly string[];What is wrong with a package, one sentence each.
isObjectconstno test imports itconst isObject: (v: unknown) => v is Readonly<Record<string, unknown>>Whether a value is a plain object (not an array, not null).
noDotconstno test imports itconst noDot: (p: string) => stringA path of a manifest without its leading ./, with / separators.
filesUnderfunctionfunction filesUnder(root: string, dir?: string): readonly string[]The files under a folder, from the folder, in order (node_modules is not looked into).
DOC_BLOCKconstno test imports itconst DOC_BLOCK: RegExpThe documentation blocks of a source (a block comment that begins a line): an example in one names what a reader may write, not what the module imports.
specifiersOfconstno test imports itconst specifiersOf: (source: string) => readonly string[]The specifiers a source imports: not those of a comment, and not the text of a string that only looks like an import.
packageOffunctionno test imports itfunction packageOf(specifier: string): string | undefinedThe package a bare specifier names (@scope/name/sub is @scope/name), or undefined for a relative path, a node: builtin or a data: URL.
targetsOffunctionno test imports itfunction targetsOf(entry: unknown): Readonly<Record<string, string>>The target of an export entry for each condition: the string, or the types, bun or default of an object.
reachableDeclarationsfunctionno test imports itfunction reachableDeclarations(stage: string, manifest: Readonly<Record<string, unknown>>): { readonly reached: ReadonlySet<string>; readonly findings: Findings; }The declarations that the entries of a package reach, by relative imports from the types of each entry, and what is wrong on the way (a declaration that is not there).
inspectPackagefunctionno test imports itfunction inspectPackage(stage: string): FindingsWhat is wrong with the package staged in a folder (the files of the tarball, package/ unpacked): see the remarks of this module.
rewriteDeclarationSpecifiersfunctionno test imports itfunction rewriteDeclarationSpecifiers(source: string): stringWrites the declarations with .js in the place of .ts in their relative specifiers.
tarballNameconstno test imports itconst tarballName: (name: string, version: string) => stringThe tarball's name for a package: @scope/name at a version is scope-name-version.tgz.
Packedtypeno test imports ittype Packed = { readonly stage: string; readonly tarball: string | undefined; readonly findings: Findings; readonly manifest: Json };What packing a library made: the staging folder, the tarball, the findings and the manifest.
namesNodeTypesfunctionno test imports itfunction namesNodeTypes(folder: string): booleanWhether a declaration of the package names a node: module: a package whose types name Node's needs @types/node where it is type-checked (a peer dependency, FR-013 of 0032-libraries-by-concern).
PackOptionstypeno test imports ittype PackOptions = {
/** Types the compiler is given (`["node"]` for a library that names Node's). */
readonly types… (1515 characters)type PackOptions = {
/** Types the compiler is given (`["node"]` for a library that names Node's). */
readonly types?: readonly string[];
/**
* Commands of a package that is not a bundle: each command's name and the module, in `src/`, whose `main(argv)` gives the exit status; the package gets a one-line launcher for each (`<command>.mjs`, which Node and Bun run), made
* from the compiled module. The files under `src/` that are not TypeScript (a stylesheet a module reads beside itself) are published beside the sources and beside the compiled modules.
*/
readonly launchers?: Readonly<Record<string, string>>;
/** Packages the published package may use where they are installed beside it and does not need (loaded by name at run time): written as optional peer dependencies, name and range. */
readonly optionalPeers?: Readonly<Record<string, string>>;
/** A bundled package: the code of each entry and of each command is one file (`bun build`), and only the declarations the entries reach are published. */
readonly bundle?: {
/** The commands: their name, and the source that is the command's entry from the library's folder. */
readonly bin?: Readonly<Record<string, string>>;
/** The README that is published, where it is more than the common one. */
readonly readme?: string;
readonly keywords?: readonly string[];
/** Files of the library's folder that are published beside the others (`CREDITS.md`). */
readonly extraFiles?: readonly string[];
};
};What packing a library is told: its folder, where to stage it and whether to make the tarball.
packLibraryfunctionno test imports itfunction packLibrary(root: string, options?: PackOptions): Promise<Packed>Builds and stages the package of the library at root (a folder commons/<name>/ with a package.json and sources in src/), inspects it and, where nothing is wrong, packs it.