SELFconstno test imports itconst SELF: "@intellectual-frontiers/commons"The package of commons that every specifier of a library is rewritten into.
The one package of commons (commons 0036-distribution FR-019 to FR-027): in single distribution mode every library of commons is packed into @intellectual-frontiers/commons, with one exports map, one set of dependencies, one bin map, one version, and the compiled files and the sources of each library under the folder of its name. The same inspection that the packer makes before it packs is inspectCommons, which a test runs again on the tarball it unpacks.
bun commons/commons/tools/pack.ts (in commons/commons) pack dist/intellectual-frontiers-commons-<version>.tgz bun commons/commons/tools/pack.ts --check the same, and print what was found; exit 1 where anything was bun commons/commons/tools/pack.ts --size the same, and print what was packed by kind and by library (also dist/package-report.json, which the site shows) bun commons/libraries/src/pack-commons.ts --report the facts of the package without compiling: the libraries, the keys of exports, the commands and the dependencies bun commons/libraries/src/pack-commons.ts --tools [--check] the packages that compiling needs, in commons/commons/package.json and bun.lock (pack-tools.ts, FR-029)
A library is a folder of commons with a manifest that is not a metapackage (packableLibraries); single mode leaves none out unless SINGLE_EXCLUDED names it (a held library is packed like any other). The package maps a library to ./<library> (its . entry) and ./<library>/<subpath> (each other key), because the subpaths of two libraries collide (./governance is a key of ten of them). Each entry names its declarations (types), its source for Bun (bun) and its compiled file (default); a library's declarations are under <library>/dist/ at the same paths as its sources are in its folder, its compiled files are beside their sources, and its sources at those paths, so that a library keeps the shape it has in this repository. The compiler builds each library by itself (the same configuration as the packer of a library: the base of commons, preserveSymlinks, so that a declaration names another library by its package and not by a path), and every specifier that names a library, @intellectual-frontiers/<library>[/<subpath>], is written as @intellectual-frontiers/commons/<library>[/<subpath>] in the compiled files, the declarations and the sources the package carries (the package names itself, which Node, Bun and TypeScript resolve). The sources of this repository keep the name of the library (Kanon, 0033-kanon FR-010). The dependencies are the union of the runtime dependencies of the libraries, each at an exact version, except the packages SINGLE_PEERS names (the database drivers the libraries take as ports, what only Docs loads and the TypeScript compiler), which are optional peer dependencies the consumer installs; the commands are those the libraries declare, each a launcher in bin/ that imports the compiled module; the files of the package that do something when they are loaded (a module that installs a port, a command) are named in sideEffects, and every other is free of effects, which the inspection proves by reading the compiled files. A folder of a library other than its entries' folders and those of NOT_RUNTIME (the data of a catalog, the guides of Docs, the installers of Ergonex) is shipped once, beside the sources, and the compiled file of each source is beside it, so that a module reads it at the same relative path from its source (Bun) and from its compiled file (Node), and no file is in the package twice (dist/ holds declarations only). The libraries are resolved by name and the third-party packages from commons/commons alone (they are linked under commons/node_modules, which is not committed), so that a fresh clone in which only that folder was installed packs the package; the folder's package.json and bun.lock hold what that takes (pack-tools.ts), which the packer checks before it compiles.
import { rewriteSpecifiers } from "./pack-commons.ts";
rewriteSpecifiers('import { ok } from "@intellectual-frontiers/core";', new Set(["core"])).text; // 'import { ok } from "@intellectual-frontiers/commons/core";'Spec: 0001-libraries FR-029
SELFconstno test imports itconst SELF: "@intellectual-frontiers/commons"The package of commons that every specifier of a library is rewritten into.
Commandtypetype Command = { readonly name: string; readonly library: string; readonly module: string; readonly form: "main" | "script" };A command of a library: its name, the library, and the module (from the library's folder) that its launcher imports; main is a module whose main(argv) gives the exit status, script one that runs when it is loaded.
Factstypetype Facts = {
readonly name: string;
readonly version: string;
readonly summary: string;
/** Each key of the li… (1383 characters)type Facts = {
readonly name: string;
readonly version: string;
readonly summary: string;
/** Each key of the library's `exports` and the source file it names, from the library's folder (`./src/mod.ts`). */
readonly exports: Readonly<Record<string, string>>;
/** The folders of the library's folder that its entries and commands are in (`src`; `engine`, `sql`, ... for `data`). */
readonly roots: readonly string[];
/** The other folders of the library's folder that the package ships beside them: what the library reads at run time (`data`, `guides`, `install`); see {@link NOT_RUNTIME}. */
readonly folders: readonly string[];
/** The commands the library declares in `bin`. */
readonly bin: Readonly<Record<string, string>>;
/** Its runtime dependencies on packages that are not of commons, each with the version the library names. */
readonly dependencies: Readonly<Record<string, string>>;
/** What it names of the packages of {@link SINGLE_PEERS} in its `dependencies` or `devDependencies`, with the version it names: the package asks the consumer for them, and compiling needs them. */
readonly peers: Readonly<Record<string, string>>;
/** Its `devDependencies` that are not of commons: what the compiler needs of it besides its runtime dependencies. */
readonly devDependencies: Readonly<Record<string, string>>;
readonly held: boolean;
};A library as the package reads it.
exportKeyfunctionfunction exportKey(library: string, key: string): stringThe key an entry of a library has in the package: . of core is ./core, ./sha256 of it is ./core/sha256.
packableLibrariesfunctionfunction packableLibraries(repo: string): { readonly libraries: readonly Library[]; readonly problems: Findings; }The libraries that the one package holds: every folder with a manifest that is not a metapackage and that SINGLE_EXCLUDED does not name, in the order of their names.
NOT_RUNTIMEconstconst NOT_RUNTIME: ReadonlySet<string>The folders of a library's folder that are not shipped: what develops, proves and documents the library and is never read by its code at run time (its tests, its specifications, its tools and its acceptance kits, 0027-commons-libraries FR-025), what the packer makes itself (the launchers of bin) and what a build or an install leaves. Every other folder of a library's folder is shipped beside its sources and its compiled files, so that a folder a library reads at run time (the data of a catalog, the guides of Docs, the installers of Ergonex) is in the package without a list that someone keeps.
factsOffunctionfunction factsOf(repo: string, l: Library): { readonly facts: Facts; readonly problems: Findings; }The facts of a library from its manifest and its package; the problems where they do not agree.
LAUNCHEDconstno test imports itconst LAUNCHED: ReadonlyMap<string, { readonly module: string; readonly form: "main" | "script"; }>The commands whose launchers are not the library's own bin file: the file is made by the packer of the library (ifc-docs) or the command is the module itself (arcactl).
commandOffunctionno test imports itfunction commandOf(repo: string, library: string, name: string, target: string): { readonly command: Command | undefined; readonly problem: string | undefined; }The module a command's launcher imports, read from the library's own bin file (import { main } from "../src/x.ts") or from LAUNCHED.
commandsOffunctionfunction commandsOf(repo: string, facts: readonly Facts[]): { readonly commands: readonly Command[]; readonly problems: Findings; }The commands of the libraries, and the problems: two libraries that declare one name are a collision.
unionDependenciesfunctionfunction unionDependencies(facts: readonly Facts[]): { readonly dependencies: Readonly<Record<string, string>>; readonly problems: Findings; }The union of the runtime dependencies of the libraries that the package installs, and the problems: two versions of one package are a conflict, and a version that is not exact is refused. The packages the package asks of the consumer are not among them (peersOf).
EXACTconstno test imports itconst EXACT: RegExpAn exact version of npm: three numbers and, optionally, a prerelease.
peersOffunctionfunction peersOf(facts: readonly Facts[]): { readonly peerDependencies: Readonly<Record<string, string>>; readonly peerDependenciesMeta: Readonly<Record<string, { readonly optional: true; }>>; readonly problems: Findings; }What the package asks of the consumer (0036-distribution FR-023): the peerDependencies with their ranges and the peerDependenciesMeta that marks each optional one, from SINGLE_PEERS for the packages the libraries name; two libraries that name two versions of one of them are a finding. @types/node is added by the packer where a declaration names a type of Node, and is not optional.
exportsMapfunctionfunction exportsMap(facts: readonly Facts[]): Record<string, unknown>The exports of the package for these libraries: each entry names the declarations, the source for Bun and the compiled file of the library's entry, under the folder of the library.
rewriteSpecifiersfunctionfunction rewriteSpecifiers(source: string, libraries: ReadonlySet<string>): { readonly text: string; readonly unknown: readonly string[]; }The text with every specifier of a library of commons written as the specifier of the package, and the libraries it names that are no library of the package. A specifier is rewritten where it is imported and where a comment shows it in an example (the example of a documentation block is what a reader copies); the text of a string that is no specifier is left as it is.
oldSpecifiersfunctionfunction oldSpecifiers(source: string): readonly string[]The specifiers of a file that still name a library by its own package: none in a package.
runsWhenLoadedfunctionfunction runsWhenLoaded(compiled: string): booleanWhether a compiled file does something when it is loaded: a statement at the top level that is not a declaration, an import or an export (a call, an assignment, a condition, a loop), other than the block that runs only where the file is the program (if (import.meta.main)).
staticSpecifiersfunctionfunction staticSpecifiers(source: string): readonly string[]The specifiers a source imports statically: those after from and after a bare import, never import( and never a statement of types only (import type, export type), which leaves no import at run time.
INTERNAL_PATHSconstno test imports itconst INTERNAL_PATHS: readonly RegExp[]What only commons needs internally and never ships (0036-distribution FR-031): the folders of a library that develop, prove and document it, the tests, the source maps, the lockfiles, the baselines of the checks and the manifest of the library.
KINDSconstno test imports itconst KINDS: readonly ["compiled", "source", "declaration", "data", "documentation", "package"]The kinds of file the report counts.
Kindtypeno test imports ittype Kind = (typeof KINDS)[number];A kind of file.
kindOffunctionfunction kindOf(rel: string, files: ReadonlySet<string>): "compiled" | "data" | "declaration" | "documentation" | "package" | "source"The kind of a file of the staged package: the declarations are the .d.ts of dist/, a source is a .ts, a compiled file is a .js beside a source of the same name, documentation is Markdown, and what else a library carries is data.
Sizestypeno test imports ittype Sizes = { readonly files: number; readonly bytes: number; readonly byKind: Readonly<Record<Kind, { readonly files: number; readonly bytes: number }>> };The bytes and the files of one set of files, by kind.
PackageReporttypeno test imports ittype PackageReport = {
readonly name: string;
readonly version: string;
readonly total: Sizes;
readonly tarballB… (426 characters)type PackageReport = {
readonly name: string;
readonly version: string;
readonly total: Sizes;
readonly tarballBytes: number | undefined;
readonly libraries: readonly (Sizes & { readonly name: string })[];
readonly dependencies: Readonly<Record<string, string>>;
readonly peerDependencies: Readonly<Record<string, string>>;
readonly optionalPeers: readonly string[];
readonly budget: typeof SINGLE_BUDGET;
};What was packed, for the page of the site and for the budget (0036-distribution FR-032).
reportOfStagefunctionno test imports itfunction reportOfStage(stage: string, tarballBytes?: number | undefined): PackageReportThe report of a staged package: its sizes in all, by library and by kind, and what it depends on and asks of the consumer.
sizeTablefunctionno test imports itfunction sizeTable(r: PackageReport): stringThe text of the table --size prints: the package, its kinds, its libraries by size, and its dependencies.
inspectCommonsfunctionfunction inspectCommons(stage: string, libraries: readonly string[], budget?: { readonly apparentBytes: number; readonly files: number; }): FindingsWhat is wrong with the package staged in a folder (the files of the tarball, package/ unpacked), for the libraries it is to hold: see the remarks of this module.
PackCommonsOptionstypeno test imports ittype PackCommonsOptions = {
/** The compiler's entry (`node_modules/typescript/bin/tsc`); where it is not given, the o… (452 characters)type PackCommonsOptions = {
/** The compiler's entry (`node_modules/typescript/bin/tsc`); where it is not given, the one of `commons/commons` or of the root of the repository. */
readonly tsc?: string;
/** The folder whose `node_modules` holds `@types/node` and the third-party packages the libraries import; the folder of the package (`commons/commons`) where it is not given. */
readonly toolsFolder?: string;
readonly parallel?: number;
};What the packer is given besides the repository: the TypeScript compiler to run, how many libraries to build at once.
PackedCommonstypeno test imports ittype PackedCommons = {
readonly stage: string;
readonly tarball: string | undefined;
readonly findings: Findings;
readonly manifest: Json;
readonly counts: { readonly libraries: number; readonly files: number; readonly exports: number; readonly commands: number; readonly sideEffects: number };
};What packing made: the stage, the tarball where nothing was wrong, the findings, the manifest and the counts.
launcherOffunctionfunction launcherOf(c: Command): stringThe launcher of a command: the line Node runs, which imports the compiled module.
packCommonsfunctionfunction packCommons(repo: string, options?: PackCommonsOptions): Promise<PackedCommons>Builds, stages, inspects and packs the one package of the repository at repo.
reportOffunctionno test imports itfunction reportOf(repo: string): { readonly libraries: readonly string[]; readonly exports: readonly string[]; readonly commands: readonly Command[]; readonly dependencies: Readonly<Record<string, string>>; readonly problems: Findings; }The facts of the package without compiling: the libraries, the keys of the exports, the commands and the dependencies, and what is wrong with them.
singleExportKeysfunctionno test imports itfunction singleExportKeys(repo: string): readonly string[]The keys of the package's exports that the libraries make (the keys, in order), for the floor of the release (0001-libraries FR-027).
toolsOfLibrariesfunctionfunction toolsOfLibraries(repo: string, facts: readonly Facts[], union: Readonly<Record<string, string>>): { readonly tools: Readonly<Record<string, string>>; readonly problems: Findings; }The tools that compiling the libraries needs (FR-029): from their manifests and from what their packed sources import.
toolsFindingsOffunctionfunction toolsFindingsOf(repo: string, tools: Readonly<Record<string, string>>): FindingsWhat the manifest and the lockfile of the folder of the package lack of the tools.