keepset 0.11.0 → 0.13.0

package/README.md

@@ -29,13 +29,14 @@ provenance.sha256; // the hash of exactly those bytes
 
 ```sh
 npx keepset search citatio --kind graph
+npx keepset namespaces
 npx keepset show cora
 npx keepset fetch cora --out cora.json
 npx keepset validate cora
 npx keepset roundtrip cora
 ```
 
-`fetch` writes the normalised result with its provenance beside it; `validate` checks the entry against the entry schema and its crosswalk against twindex's validation without the network; `roundtrip` fetches the dataset and checks that decoding the encoded native document gives it back. Exit status is 0 for an answer, 1 for a negative one (an invalid entry, a round trip that does not hold) and 2 for no answer (bad usage, an unknown or ambiguous name, a recipe that failed).
+`namespaces [path]` lists the namespaces directly beneath a path (the outermost ones without one) with how many datasets each holds, and the site has a page for each, linked from every entry's namespace. `fetch` writes the normalised result with its provenance beside it; `validate` checks the entry against the entry schema and its crosswalk against twindex's validation without the network; `roundtrip` fetches the dataset and checks that decoding the encoded native document gives it back. Exit status is 0 for an answer, 1 for a negative one (an invalid entry, a round trip that does not hold) and 2 for no answer (bad usage, an unknown or ambiguous name or namespace, a recipe that failed).
 
 ## Names, aliases and namespaces
 
@@ -48,7 +49,11 @@ npx keepset fetch gset/g53
 npx keepset fetch g53
 ```
 
-A qualified name joins the namespace to a name with `/`, and any leading part of the namespace may be dropped while the name still means one dataset. An entry's own id always wins; otherwise a name that more than one entry answers to is refused with the ids it could mean (`DatasetAmbiguousError` in the library, exit status 2 in the CLI), and the way out is a longer qualified name or the id. `search --namespace suitesparse` (or `listDatasets({ namespace })`) lists a namespace and everything beneath it. Everything a command writes or prints uses the entry's own id, never the name typed.
+A qualified name joins the namespace to a name with `/`, and any leading part of the namespace may be dropped while the name still means one dataset (a middle part may not be). An entry's own id always wins; otherwise a name that more than one entry answers to is refused with the ids it could mean (`DatasetAmbiguousError` in the library, exit status 2 in the CLI), and the way out is a longer qualified name or the id. Everything a command writes or prints uses the entry's own id, never the name typed.
+
+An alias that is a path, such as `foo/graphs/bar`, files the entry in a second group as well: it is a name in its own right, not prefixed by the entry's namespace, and answers to `bar`, `graphs/bar` and `foo/graphs/bar`. The namespace is where an entry comes from and path aliases are cross-listing, so an entry can sit in several groups. The catalogue manifest can also give a namespace segment aliases (`namespaceAliases`, such as `ss` for `suitesparse`), and a name then answers with the alias in the segment's place.
+
+`search --namespace suitesparse` (or `listDatasets({ namespace })`) lists a group and every group beneath it, an entry once however many of those it is in. `listNamespaces(path)` lists the namespaces directly beneath a path, or the outermost ones, each with the number of entries at or beneath it.
 
 ## The entry format
 

package/dist/{bundled-DaXJpk0C.js → bundled-DNLiwEcd.js}

@@ -191,10 +191,87 @@ function countTarget(id, target) {
 	return new Map(category.counted.map((key) => [key, target[key].length]));
 }
 //#endregion
+//#region src/own.ts
+/**
+* Reads an own property of a record keyed by strings that come from data. A plain `record[key]` read follows the prototype chain, so a key such as `constructor` would find an inherited function instead of reporting absence.
+* @param record - The record to read.
+* @param key - Any string.
+* @returns The own property's value, or `undefined` when the record has no such own property.
+*/
+function getOwn(record, key) {
+	return Object.hasOwn(record, key) ? record[key] : void 0;
+}
+//#endregion
+//#region src/names.ts
+/** The character that joins a namespace's segments to each other and to a name. It is not in an id's alphabet, so a name containing it is always a path and never a literal id. */
+const NAME_SEPARATOR = "/";
+/**
+* Splits a path of ids on the separator.
+* @param path - A path such as `a/b`.
+* @returns Its segments.
+*/
+function segmentsOf(path) {
+	return path.split("/");
+}
+/**
+* The addresses of an entry, each as its path of segments with the name last: the id and every bare alias sit in the entry's own namespace, and an alias that is a path is an address of its own, in the group its leading segments name.
+* @param entry - The entry.
+* @returns One path per id or alias, the id first.
+*/
+function addressesOf(entry) {
+	const { namespace = [], aliases = [] } = entry;
+	return [entry.id, ...aliases].map((name) => name.includes("/") ? segmentsOf(name) : [...namespace, name]);
+}
+/**
+* The groups an entry belongs to: the namespace its id and bare aliases sit in, and the group each alias that is a path names, each once, in order of first appearance. A group is a path of segments; an entry belongs to every group above it as well, which the caller reads off the path.
+* @param entry - The entry.
+* @returns The groups, empty for an entry with no namespace and no path aliases.
+*/
+function groupsOf(entry) {
+	const seen = /* @__PURE__ */ new Set();
+	return addressesOf(entry).map((address) => address.slice(0, -1)).filter((group) => {
+		const key = group.join("/");
+		if (group.length === 0 || seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+/**
+* Every spelling of a path of segments when each segment may be replaced by one of its aliases.
+* @param segments - The segments.
+* @param aliases - The segment aliases.
+* @returns Each combination, the unaliased path first.
+*/
+function spellings(segments, aliases) {
+	return segments.reduce((paths, segment) => paths.flatMap((path) => [segment, ...getOwn(aliases, segment) ?? []].map((spelling) => [...path, spelling])), [[]]);
+}
+/**
+* Works out the names an entry answers to. Each address is a path of segments with the name last, and an address answers to every trailing run of its path, so id `c` in namespace `a/b` answers to `c`, `b/c` and `a/b/c`, and the alias `x/y/d` answers to `d`, `y/d` and `x/y/d`. Where the manifest gives a segment aliases, an address also answers with the alias in the segment's place.
+* @param entry - The entry: only its id, namespace and aliases are read.
+* @param segmentAliases - The manifest's aliases for namespace segments, if any.
+* @returns The fully qualified names and every name that resolves to the entry.
+*/
+function namesOf(entry, segmentAliases = {}) {
+	const addresses = addressesOf(entry);
+	const names = addresses.flatMap((address) => {
+		const name = address.slice(-1);
+		return spellings(address.slice(0, -1), segmentAliases).flatMap((group) => {
+			const path = [...group, ...name];
+			return Array.from({ length: path.length }, (_unused, depth) => path.slice(path.length - 1 - depth).join("/"));
+		});
+	});
+	return {
+		full: addresses.map((address) => address.join("/")),
+		all: [...new Set(names)]
+	};
+}
+//#endregion
 //#region src/entry.ts
 /** A stable identifier: an entry id, a catalogue id. It starts with a letter or digit, so no id can be `__proto__` or any other name that begins with an underscore. Entry ids stay the same across forks, which is what lets two catalogues be compared entry by entry. */
 const IdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, { message: "must start with a letter or digit and contain only letters, digits, '.', '_' and '-'" });
 /** A key of an entry's `properties` or `expectedCounts` record: an identifier that starts with a letter, so it can never be `__proto__` or another name Object.prototype reacts to on assignment. */
+/** An alias: an id, or a path of ids joined by `/` such as `foo/graphs/bar`. A bare id is a name inside the entry's own namespace; a path is a name of its own, in the group its leading segments name. The segment pattern repeats the one in `IdSchema` so that each part of a path is an id. */
+const AliasSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/, { message: "must be an id, or ids joined by '/', each starting with a letter or digit and containing only letters, digits, '.', '_' and '-'" });
 /** The path a dataset sits under in a collection, outermost segment first, such as `["suitesparse", "gset"]`. Each segment is an id, so a segment can never contain the `/` that joins a namespace to a name. */
 const NamespaceSchema = z.array(IdSchema).min(1);
 const RecordKeySchema = z.string().regex(/^[A-Za-z][A-Za-z0-9]*$/, { message: "must be a letter followed by letters or digits" });
@@ -334,7 +411,7 @@ const RESERVED_META_KEYS = ["id", "name"];
 const EntrySchema = define(z.object({
 	id: IdSchema,
 	namespace: NamespaceSchema.optional(),
-	aliases: z.array(IdSchema).min(1).optional(),
+	aliases: z.array(AliasSchema).min(1).optional(),
 	name: z.string().min(1),
 	description: z.string().min(1).optional(),
 	domain: z.string().min(1).optional(),
@@ -354,6 +431,12 @@ const EntrySchema = define(z.object({
 		path: ["aliases"],
 		message: "aliases must be unique and differ from the entry's own id"
 	});
+	const { full } = namesOf(entry);
+	if (new Set(full).size !== full.length) ctx.addIssue({
+		code: "custom",
+		path: ["aliases"],
+		message: "the entry's id and aliases must not give the same fully qualified name twice"
+	});
 	if (entry.recipe.status === "fetchable" && entry.recipe.source >= entry.sources.length) ctx.addIssue({
 		code: "custom",
 		path: ["recipe", "source"],
@@ -409,7 +492,7 @@ const LineageSchema = z.object({
 	repository: HttpUrlSchema
 }).strict();
 /**
-* A catalogue manifest: the catalogue's own id and version, where it lives, and, for a fork, its lineage. A catalogue is a self-contained set of entry documents beside its manifest, and a fork is its own catalogue with its own id, so lineage may never name the catalogue itself.
+* A catalogue manifest: the catalogue's own id and version, where it lives, the other names its namespace segments go by, and, for a fork, its lineage. A catalogue is a self-contained set of entry documents beside its manifest, and a fork is its own catalogue with its own id, so lineage may never name the catalogue itself. A segment alias is a name for a whole segment wherever it appears in a namespace, so it may not repeat, name itself, or be the segment of another alias.
 */
 const ManifestSchema = define(z.object({
 	id: IdSchema,
@@ -417,13 +500,35 @@ const ManifestSchema = define(z.object({
 	description: z.string().min(1),
 	version: SemVerSchema,
 	repository: HttpUrlSchema,
-	lineage: LineageSchema.optional()
+	lineage: LineageSchema.optional(),
+	namespaceAliases: recordOf(IdSchema, z.array(IdSchema).min(1)).optional()
 }).strict().superRefine((manifest, ctx) => {
 	if (manifest.lineage?.catalogue === manifest.id) ctx.addIssue({
 		code: "custom",
 		path: ["lineage", "catalogue"],
 		message: "a fork is its own catalogue: lineage must name the catalogue it was forked from, not itself"
 	});
+	const aliasOf = /* @__PURE__ */ new Map();
+	const aliases = manifest.namespaceAliases ?? {};
+	for (const [segment, names] of Object.entries(aliases)) for (const alias of names) {
+		const earlier = aliasOf.get(alias);
+		if (alias === segment) ctx.addIssue({
+			code: "custom",
+			path: ["namespaceAliases", segment],
+			message: `${alias} cannot be an alias of itself`
+		});
+		else if (earlier !== void 0) ctx.addIssue({
+			code: "custom",
+			path: ["namespaceAliases", segment],
+			message: `${alias} is already an alias of ${earlier}`
+		});
+		else if (Object.hasOwn(aliases, alias)) ctx.addIssue({
+			code: "custom",
+			path: ["namespaceAliases", segment],
+			message: `${alias} is itself a segment with aliases`
+		});
+		aliasOf.set(alias, segment);
+	}
 }));
 /**
 * Parses an unknown value as a catalogue manifest.
@@ -437,37 +542,9 @@ function parseManifest(doc) {
 	return result.data;
 }
 //#endregion
-//#region src/names.ts
-/** The character that joins a namespace's segments to each other and to a name. It is not in an id's alphabet, so a name containing it is always a path and never a literal id. */
-const NAME_SEPARATOR = "/";
-/**
-* Works out the names an entry answers to. A leaf is the entry's id or one of its aliases; a name is a leaf with any trailing run of the entry's namespace segments before it, so an entry in namespace `a/b` with id `c` answers to `c`, `b/c` and `a/b/c`.
-* @param entry - The entry: only its id, namespace and aliases are read.
-* @returns The fully qualified names and every name that resolves to the entry.
-*/
-function namesOf(entry) {
-	const { namespace = [], aliases = [] } = entry;
-	const leaves = [entry.id, ...aliases];
-	return {
-		full: leaves.map((leaf) => [...namespace, leaf].join("/")),
-		all: leaves.flatMap((leaf) => Array.from({ length: namespace.length + 1 }, (_unused, depth) => [...namespace.slice(namespace.length - depth), leaf].join("/")))
-	};
-}
-//#endregion
-//#region src/own.ts
-/**
-* Reads an own property of a record keyed by strings that come from data. A plain `record[key]` read follows the prototype chain, so a key such as `constructor` would find an inherited function instead of reporting absence.
-* @param record - The record to read.
-* @param key - Any string.
-* @returns The own property's value, or `undefined` when the record has no such own property.
-*/
-function getOwn(record, key) {
-	return Object.hasOwn(record, key) ? record[key] : void 0;
-}
-//#endregion
 //#region src/catalogue.ts
 /**
-* A catalogue index: the manifest, every entry, and every crosswalk file of the catalogue, keyed by its catalogue-relative path. The build assembles it from a catalogue directory; a consumer holding its own catalogue (a fork, say) can pass one to `createCatalogue`. Entry ids are unique, every fully qualified name (the whole namespace and an id or alias) identifies one entry and is not another entry's id, every crosswalk passes twindex's structural validation, every crosswalk file reference resolves, and every crosswalk's target is the category of each entry that uses it.
+* A catalogue index: the manifest, every entry, and every crosswalk file of the catalogue, keyed by its catalogue-relative path. The build assembles it from a catalogue directory; a consumer holding its own catalogue (a fork, say) can pass one to `createCatalogue`. Entry ids are unique, every fully qualified name (the whole path of an id or alias) identifies one entry and is not another entry's id, every namespace segment the manifest gives aliases to is some entry's segment and no alias is itself one, every crosswalk passes twindex's structural validation, every crosswalk file reference resolves, and every crosswalk's target is the category of each entry that uses it.
 */
 const CatalogueIndexSchema = define(z.object({
 	manifest: ManifestSchema,
@@ -479,6 +556,27 @@ const CatalogueIndexSchema = define(z.object({
 		path: ["crosswalks", file],
 		message: `rule ${String(issue.ruleIndex)}: ${issue.message}`
 	});
+	const segments = new Set(index.entries.flatMap((entry) => groupsOf(entry).flat()));
+	for (const [segment, aliases] of Object.entries(index.manifest.namespaceAliases ?? {})) {
+		if (!segments.has(segment)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"manifest",
+				"namespaceAliases",
+				segment
+			],
+			message: `no entry has a namespace segment ${segment}, so it has nothing to be an alias of`
+		});
+		for (const alias of aliases.filter((name) => segments.has(name))) ctx.addIssue({
+			code: "custom",
+			path: [
+				"manifest",
+				"namespaceAliases",
+				segment
+			],
+			message: `${alias} is already a namespace segment of an entry, so it cannot also be an alias`
+		});
+	}
 	const seen = /* @__PURE__ */ new Set();
 	const ids = new Set(index.entries.map((entry) => entry.id));
 	const owners = /* @__PURE__ */ new Map();
@@ -553,32 +651,57 @@ const CatalogueIndexSchema = define(z.object({
 * Whether a dataset matches a query.
 * @param dataset - The dataset.
 * @param query - The filters.
+* @param groups - The dataset's groups, each as a path joined by the separator.
+* @param namespace - The query's namespace with every segment alias replaced by its segment, when it has one.
 * @returns True when every given filter matches.
 */
-function matches(dataset, query) {
+function matches(dataset, query, groups, namespace) {
 	const { entry } = dataset;
 	if (query.kind !== void 0 && dataset.kind !== query.kind) return false;
 	if (query.category !== void 0 && entry.category !== query.category) return false;
 	if (query.domain !== void 0 && entry.domain !== query.domain) return false;
-	if (query.namespace !== void 0) {
-		const path = (entry.namespace ?? []).join("/");
-		if (path !== query.namespace && !path.startsWith(`${query.namespace}/`)) return false;
-	}
+	if (namespace !== void 0 && !groups.some((group) => group === namespace || group.startsWith(`${namespace}/`))) return false;
 	if (query.text !== void 0) {
 		const needle = query.text.toLowerCase();
 		return [
 			entry.id,
 			...entry.aliases ?? [],
-			(entry.namespace ?? []).join("/"),
+			...groups,
 			entry.name,
 			entry.description,
 			entry.domain,
 			...entry.tags
-		].filter((field) => field !== void 0 && field !== "").some((field) => field.toLowerCase().includes(needle));
+		].filter((field) => field !== void 0).some((field) => field.toLowerCase().includes(needle));
 	}
 	return true;
 }
 /**
+* Builds the tree of namespaces: every group of every entry and each path above it, with the ids of the entries at or beneath each.
+* @param groupsById - Each entry's groups, each as a path joined by the separator.
+* @returns The child namespaces of each path, the outermost ones under the empty path, each list in path order.
+*/
+function namespaceTree(groupsById) {
+	const members = /* @__PURE__ */ new Map();
+	for (const [id, groups] of groupsById) for (const group of groups) {
+		const segments = group.split("/");
+		for (let length = 1; length <= segments.length; length += 1) {
+			const path = segments.slice(0, length).join("/");
+			members.set(path, (members.get(path) ?? /* @__PURE__ */ new Set()).add(id));
+		}
+	}
+	const children = /* @__PURE__ */ new Map();
+	for (const [path, ids] of [...members].sort(([left], [right]) => left < right ? -1 : 1)) {
+		const cut = path.lastIndexOf("/");
+		const parent = cut === -1 ? "" : path.slice(0, cut);
+		children.set(parent, [...children.get(parent) ?? [], {
+			path,
+			name: path.slice(cut + 1),
+			count: ids.size
+		}]);
+	}
+	return children;
+}
+/**
 * Builds a queryable catalogue from an index. Pure and synchronous: no filesystem, no network, so it runs the same in a browser as in Node.
 * @param index - A candidate catalogue index.
 * @returns The catalogue.
@@ -592,7 +715,11 @@ function createCatalogue(index) {
 		id: manifest.id,
 		version: manifest.version
 	};
+	const segmentAliases = manifest.namespaceAliases ?? {};
+	const segmentOf = new Map(Object.entries(segmentAliases).flatMap(([segment, aliases]) => aliases.map((alias) => [alias, segment])));
+	const canonical = (path) => path.split("/").map((segment) => segmentOf.get(segment) ?? segment).join("/");
 	const datasets = /* @__PURE__ */ new Map();
+	const groupsById = /* @__PURE__ */ new Map();
 	const names = /* @__PURE__ */ new Map();
 	for (const entry of [...entries].sort((left, right) => left.id < right.id ? -1 : 1)) {
 		const crosswalk = "file" in entry.crosswalk ? getOwn(crosswalks, entry.crosswalk.file) : entry.crosswalk;
@@ -606,11 +733,16 @@ function createCatalogue(index) {
 			crosswalk,
 			catalogue
 		});
-		for (const name of new Set(namesOf(entry).all)) names.set(name, [...names.get(name) ?? [], entry.id]);
+		groupsById.set(entry.id, groupsOf(entry).map((group) => group.join("/")));
+		for (const name of namesOf(entry, segmentAliases).all) names.set(name, [...names.get(name) ?? [], entry.id]);
 	}
+	const tree = namespaceTree(groupsById);
 	return {
 		manifest,
-		listDatasets: (query = {}) => [...datasets.values()].filter((dataset) => matches(dataset, query)),
+		listDatasets: (query = {}) => {
+			const namespace = query.namespace === void 0 ? void 0 : canonical(query.namespace);
+			return [...datasets.values()].filter((dataset) => matches(dataset, query, groupsById.get(dataset.entry.id) ?? [], namespace));
+		},
 		getDataset: (name) => {
 			const exact = datasets.get(name);
 			if (exact !== void 0) return exact;
@@ -621,7 +753,8 @@ function createCatalogue(index) {
 			const dataset = datasets.get(only);
 			if (dataset === void 0) throw new DatasetNotFoundError(name);
 			return dataset;
-		}
+		},
+		listNamespaces: (path) => tree.get(path === void 0 ? "" : canonical(path)) ?? []
 	};
 }
 //#endregion
@@ -631,8 +764,12 @@ var catalogue_default = {
 		"id": "keepset",
 		"name": "keepset",
 		"description": "The keepset catalogue: datasets with machine-readable recipes that fetch each one and normalise it into its category's target shape.",
-		"version": "1.1.0",
-		"repository": "https://github.com/Mearman/keepset"
+		"version": "1.2.0",
+		"repository": "https://github.com/Mearman/keepset",
+		"namespaceAliases": {
+			"networkrepository": ["nr"],
+			"suitesparse": ["ss"]
+		}
 	},
 	crosswalks: { "crosswalks/graph-v1/topology.json": {
 		"source": "keepset/topology",
@@ -47667,9 +47804,17 @@ function listDatasets(query) {
 function getDataset(id) {
 	return catalogue().getDataset(id);
 }
+/**
+* Lists the namespaces directly beneath a path of the bundled catalogue, or the outermost ones, with how many entries each holds. Browser-safe.
+* @param path - A group path whose children to list; absent for the outermost namespaces.
+* @returns The child namespaces in path order.
+*/
+function listNamespaces(path) {
+	return catalogue().listNamespaces(path);
+}
 /** @returns The bundled catalogue's manifest: its id, version and repository. */
 function getManifest() {
 	return catalogue().manifest;
 }
 //#endregion
-export { toIssues as A, GraphV1Schema as B, RESERVED_META_KEYS as C, SourceSchema as D, SnapshotSchema as E, getTarget as F, DatasetNotFoundError as G, ArchiveError as H, kindOf as I, RecipeError as J, KeepsetError as K, listCategories as L, CategoryIdSchema as M, countTarget as N, WaybackTimestampSchema as O, getCategory as P, GraphEdgeSchema as R, ParserSchema as S, RelativePathSchema as T, CatalogueSyntaxError as U, JsonScalarSchema as V, DatasetAmbiguousError as W, UnknownCategoryError as Y, EntrySchema as _, createCatalogue as a, LicenceSchema as b, namesOf as c, SemVerSchema as d, parseManifest as f, CrosswalkReferenceSchema as g, CitationSchema as h, CatalogueIndexSchema as i, waybackUrl as j, parseEntry as k, LineageSchema as l, ArchiveSchema as m, getManifest as n, getOwn as o, ArchiveMemberSchema as p, NativeParseError as q, listDatasets as r, NAME_SEPARATOR as s, getDataset as t, ManifestSchema as u, HttpUrlSchema as v, RecipeSchema as w, NamespaceSchema as x, IdSchema as y, GraphNodeSchema as z };
+export { waybackUrl as A, listCategories as B, RecipeSchema as C, WaybackTimestampSchema as D, SourceSchema as E, CategoryIdSchema as F, ArchiveError as G, GraphNodeSchema as H, countTarget as I, DatasetNotFoundError as J, CatalogueSyntaxError as K, getCategory as L, groupsOf as M, namesOf as N, parseEntry as O, getOwn as P, UnknownCategoryError as Q, getTarget as R, RESERVED_META_KEYS as S, SnapshotSchema as T, GraphV1Schema as U, GraphEdgeSchema as V, JsonScalarSchema as W, NativeParseError as X, KeepsetError as Y, RecipeError as Z, HttpUrlSchema as _, CatalogueIndexSchema as a, NamespaceSchema as b, ManifestSchema as c, AliasSchema as d, ArchiveMemberSchema as f, EntrySchema as g, CrosswalkReferenceSchema as h, listNamespaces as i, NAME_SEPARATOR as j, toIssues as k, SemVerSchema as l, CitationSchema as m, getManifest as n, createCatalogue as o, ArchiveSchema as p, DatasetAmbiguousError as q, listDatasets as r, LineageSchema as s, getDataset as t, parseManifest as u, IdSchema as v, RelativePathSchema as w, ParserSchema as x, LicenceSchema as y, kindOf as z };

package/dist/{categories-BSJj6C-y.d.ts → categories-DzjLQ_fp.d.ts}

@@ -4,6 +4,8 @@ import { z } from "zod";
 /** A stable identifier: an entry id, a catalogue id. It starts with a letter or digit, so no id can be `__proto__` or any other name that begins with an underscore. Entry ids stay the same across forks, which is what lets two catalogues be compared entry by entry. */
 declare const IdSchema: z.ZodString;
 /** A key of an entry's `properties` or `expectedCounts` record: an identifier that starts with a letter, so it can never be `__proto__` or another name Object.prototype reacts to on assignment. */
+/** An alias: an id, or a path of ids joined by `/` such as `foo/graphs/bar`. A bare id is a name inside the entry's own namespace; a path is a name of its own, in the group its leading segments name. The segment pattern repeats the one in `IdSchema` so that each part of a path is an id. */
+declare const AliasSchema: z.ZodString;
 /** The path a dataset sits under in a collection, outermost segment first, such as `["suitesparse", "gset"]`. Each segment is an id, so a segment can never contain the `/` that joins a namespace to a name. */
 declare const NamespaceSchema: z.ZodArray<z.ZodString>;
 type Namespace = z.infer<typeof NamespaceSchema>;
@@ -443,7 +445,7 @@ declare const LineageSchema: z.ZodObject<{
 }, z.core.$strict>;
 type Lineage = z.infer<typeof LineageSchema>;
 /**
- * A catalogue manifest: the catalogue's own id and version, where it lives, and, for a fork, its lineage. A catalogue is a self-contained set of entry documents beside its manifest, and a fork is its own catalogue with its own id, so lineage may never name the catalogue itself.
+ * A catalogue manifest: the catalogue's own id and version, where it lives, the other names its namespace segments go by, and, for a fork, its lineage. A catalogue is a self-contained set of entry documents beside its manifest, and a fork is its own catalogue with its own id, so lineage may never name the catalogue itself. A segment alias is a name for a whole segment wherever it appears in a namespace, so it may not repeat, name itself, or be the segment of another alias.
  */
 declare const ManifestSchema: z.ZodObject<{
   id: z.ZodString;
@@ -456,6 +458,7 @@ declare const ManifestSchema: z.ZodObject<{
     version: z.ZodString;
     repository: z.ZodURL;
   }, z.core.$strict>>;
+  namespaceAliases: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>, unknown>>;
 }, z.core.$strict> & {
   is: (value: unknown) => value is {
     id: string;
@@ -468,6 +471,7 @@ declare const ManifestSchema: z.ZodObject<{
       version: string;
       repository: string;
     } | undefined;
+    namespaceAliases?: Record<string, string[]> | undefined;
   };
 };
 type Manifest = z.infer<typeof ManifestSchema>;
@@ -481,7 +485,7 @@ declare function parseManifest(doc: unknown): Manifest;
 //#endregion
 //#region src/catalogue.d.ts
 /**
- * A catalogue index: the manifest, every entry, and every crosswalk file of the catalogue, keyed by its catalogue-relative path. The build assembles it from a catalogue directory; a consumer holding its own catalogue (a fork, say) can pass one to `createCatalogue`. Entry ids are unique, every fully qualified name (the whole namespace and an id or alias) identifies one entry and is not another entry's id, every crosswalk passes twindex's structural validation, every crosswalk file reference resolves, and every crosswalk's target is the category of each entry that uses it.
+ * A catalogue index: the manifest, every entry, and every crosswalk file of the catalogue, keyed by its catalogue-relative path. The build assembles it from a catalogue directory; a consumer holding its own catalogue (a fork, say) can pass one to `createCatalogue`. Entry ids are unique, every fully qualified name (the whole path of an id or alias) identifies one entry and is not another entry's id, every namespace segment the manifest gives aliases to is some entry's segment and no alias is itself one, every crosswalk passes twindex's structural validation, every crosswalk file reference resolves, and every crosswalk's target is the category of each entry that uses it.
  */
 declare const CatalogueIndexSchema: z.ZodObject<{
   manifest: z.ZodObject<{
@@ -495,6 +499,7 @@ declare const CatalogueIndexSchema: z.ZodObject<{
       version: z.ZodString;
       repository: z.ZodURL;
     }, z.core.$strict>>;
+    namespaceAliases: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>, unknown>>;
   }, z.core.$strict> & {
     is: (value: unknown) => value is {
       id: string;
@@ -507,6 +512,7 @@ declare const CatalogueIndexSchema: z.ZodObject<{
         version: string;
         repository: string;
       } | undefined;
+      namespaceAliases?: Record<string, string[]> | undefined;
     };
   };
   crosswalks: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodType<Crosswalk, unknown, z.core.$ZodTypeInternals<Crosswalk, unknown>> & {
@@ -731,6 +737,7 @@ declare const CatalogueIndexSchema: z.ZodObject<{
         version: string;
         repository: string;
       } | undefined;
+      namespaceAliases?: Record<string, string[]> | undefined;
     };
     crosswalks: Record<string, Crosswalk>;
     entries: {
@@ -841,12 +848,18 @@ interface DatasetQuery {
   readonly category?: string;
   /** The entry's domain, matched exactly. */
   readonly domain?: string;
-  /** A namespace path such as `suitesparse` or `suitesparse/gset`: matches the entries in that namespace and every namespace beneath it. */
+  /** A group path such as `suitesparse` or `suitesparse/gset`, in which any segment may be an alias the manifest gives it: matches the entries in that group, in any group beneath it, and the entries a path alias files there. */
   readonly namespace?: string;
-  /** Text that must appear, ignoring case, in the entry's id, an alias, its namespace, name, description, domain or one of its tags. */
+  /** Text that must appear, ignoring case, in the entry's id, an alias, one of its groups, name, description, domain or one of its tags. */
   readonly text?: string;
 }
-/** A queryable catalogue: the surface `listDatasets` and `getDataset` are bound to. */
+/** One namespace in the tree of groups: its path, its last segment, and how many distinct entries sit in it or in any namespace beneath it. */
+interface NamespaceNode {
+  readonly path: string;
+  readonly name: string;
+  readonly count: number;
+}
+/** A queryable catalogue: the surface `listDatasets`, `getDataset` and `listNamespaces` are bound to. */
 interface Catalogue {
   readonly manifest: Manifest;
   /**
@@ -863,6 +876,12 @@ interface Catalogue {
    * @throws DatasetNotFoundError when no entry answers to the name.
    */
   readonly getDataset: (name: string) => Dataset;
+  /**
+   * Lists the namespaces directly beneath a path, or the outermost ones, with how many entries each holds. The tree is every group of every entry and each path above it, so an entry filed in `a/b` counts toward `a/b` and `a`.
+   * @param path - A group path whose children to list, in which any segment may be an alias the manifest gives it; absent for the outermost namespaces.
+   * @returns The child namespaces in path order; empty when the path has none, whether it is unknown or a leaf.
+   */
+  readonly listNamespaces: (path?: string) => NamespaceNode[];
 }
 /**
  * Builds a queryable catalogue from an index. Pure and synchronous: no filesystem, no network, so it runs the same in a browser as in Node.
@@ -974,4 +993,4 @@ declare function listCategories(): readonly Category[];
  */
 declare function countTarget(id: CategoryId, target: CategoryTarget): ReadonlyMap<string, number>;
 //#endregion
-export { RelativePathSchema as $, SemVerSchema as A, Entry as B, Dataset as C, LineageSchema as D, Lineage as E, ArchiveSchema as F, LicenceSchema as G, HttpUrlSchema as H, Citation as I, Parser as J, Namespace as K, CitationSchema as L, Archive as M, ArchiveMember as N, Manifest as O, ArchiveMemberSchema as P, RecipeSchema as Q, CrosswalkReference as R, CatalogueIndexSchema as S, createCatalogue as T, IdSchema as U, EntrySchema as V, Licence as W, RESERVED_META_KEYS as X, ParserSchema as Y, Recipe as Z, GraphV1Schema as _, CategoryTargets as a, parseEntry as at, Catalogue as b, getCategory as c, listCategories as d, Snapshot as et, GraphEdge as f, GraphV1 as g, GraphNodeSchema as h, CategoryTarget as i, WaybackTimestampSchema as it, parseManifest as j, ManifestSchema as k, getTarget as l, GraphNode as m, CategoryId as n, Source as nt, CountedKey as o, waybackUrl as ot, GraphEdgeSchema as p, NamespaceSchema as q, CategoryIdSchema as r, SourceSchema as rt, countTarget as s, Category as t, SnapshotSchema as tt, kindOf as u, JsonScalar as v, DatasetQuery as w, CatalogueIndex as x, JsonScalarSchema as y, CrosswalkReferenceSchema as z };
+export { Recipe as $, ManifestSchema as A, CrosswalkReference as B, Dataset as C, Lineage as D, createCatalogue as E, ArchiveMember as F, IdSchema as G, Entry as H, ArchiveMemberSchema as I, Namespace as J, Licence as K, ArchiveSchema as L, parseManifest as M, AliasSchema as N, LineageSchema as O, Archive as P, RESERVED_META_KEYS as Q, Citation as R, CatalogueIndexSchema as S, NamespaceNode as T, EntrySchema as U, CrosswalkReferenceSchema as V, HttpUrlSchema as W, Parser as X, NamespaceSchema as Y, ParserSchema as Z, GraphV1Schema as _, CategoryTargets as a, SourceSchema as at, Catalogue as b, getCategory as c, waybackUrl as ct, listCategories as d, RecipeSchema as et, GraphEdge as f, GraphV1 as g, GraphNodeSchema as h, CategoryTarget as i, Source as it, SemVerSchema as j, Manifest as k, getTarget as l, GraphNode as m, CategoryId as n, Snapshot as nt, CountedKey as o, WaybackTimestampSchema as ot, GraphEdgeSchema as p, LicenceSchema as q, CategoryIdSchema as r, SnapshotSchema as rt, countTarget as s, parseEntry as st, Category as t, RelativePathSchema as tt, kindOf as u, JsonScalar as v, DatasetQuery as w, CatalogueIndex as x, JsonScalarSchema as y, CitationSchema as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as RelativePathSchema, A as SemVerSchema, B as Entry, C as Dataset, D as LineageSchema, E as Lineage, F as ArchiveSchema, G as LicenceSchema, H as HttpUrlSchema, I as Citation, J as Parser, K as Namespace, L as CitationSchema, M as Archive, N as ArchiveMember, O as Manifest, P as ArchiveMemberSchema, Q as RecipeSchema, R as CrosswalkReference, S as CatalogueIndexSchema, T as createCatalogue, U as IdSchema, V as EntrySchema, W as Licence, X as RESERVED_META_KEYS, Y as ParserSchema, Z as Recipe, _ as GraphV1Schema, a as CategoryTargets, at as parseEntry, b as Catalogue, c as getCategory, d as listCategories, et as Snapshot, f as GraphEdge, g as GraphV1, h as GraphNodeSchema, i as CategoryTarget, it as WaybackTimestampSchema, j as parseManifest, k as ManifestSchema, l as getTarget, m as GraphNode, n as CategoryId, nt as Source, o as CountedKey, ot as waybackUrl, p as GraphEdgeSchema, q as NamespaceSchema, r as CategoryIdSchema, rt as SourceSchema, s as countTarget, t as Category, tt as SnapshotSchema, u as kindOf, v as JsonScalar, w as DatasetQuery, x as CatalogueIndex, y as JsonScalarSchema, z as CrosswalkReferenceSchema } from "./categories-BSJj6C-y.js";
+import { $ as Recipe, A as ManifestSchema, B as CrosswalkReference, C as Dataset, D as Lineage, E as createCatalogue, F as ArchiveMember, G as IdSchema, H as Entry, I as ArchiveMemberSchema, J as Namespace, K as Licence, L as ArchiveSchema, M as parseManifest, N as AliasSchema, O as LineageSchema, P as Archive, Q as RESERVED_META_KEYS, R as Citation, S as CatalogueIndexSchema, T as NamespaceNode, U as EntrySchema, V as CrosswalkReferenceSchema, W as HttpUrlSchema, X as Parser, Y as NamespaceSchema, Z as ParserSchema, _ as GraphV1Schema, a as CategoryTargets, at as SourceSchema, b as Catalogue, c as getCategory, ct as waybackUrl, d as listCategories, et as RecipeSchema, f as GraphEdge, g as GraphV1, h as GraphNodeSchema, i as CategoryTarget, it as Source, j as SemVerSchema, k as Manifest, l as getTarget, m as GraphNode, n as CategoryId, nt as Snapshot, o as CountedKey, ot as WaybackTimestampSchema, p as GraphEdgeSchema, q as LicenceSchema, r as CategoryIdSchema, rt as SnapshotSchema, s as countTarget, st as parseEntry, t as Category, tt as RelativePathSchema, u as kindOf, v as JsonScalar, w as DatasetQuery, x as CatalogueIndex, y as JsonScalarSchema, z as CitationSchema } from "./categories-DzjLQ_fp.js";
 import { Crosswalk } from "twindex";
 //#region src/errors.d.ts
 /** The root of this package's error taxonomy: every error keepset throws is a `KeepsetError`, so callers can catch the family with one check. */
@@ -64,25 +64,42 @@ export declare function listDatasets(query?: DatasetQuery): Dataset[];
  * @throws DatasetNotFoundError when no entry has that id.
  */
 export declare function getDataset(id: string): Dataset;
+/**
+ * Lists the namespaces directly beneath a path of the bundled catalogue, or the outermost ones, with how many entries each holds. Browser-safe.
+ * @param path - A group path whose children to list; absent for the outermost namespaces.
+ * @returns The child namespaces in path order.
+ */
+export declare function listNamespaces(path?: string): NamespaceNode[];
 /** @returns The bundled catalogue's manifest: its id, version and repository. */
 export declare function getManifest(): Manifest;
 //#endregion
 //#region src/names.d.ts
 /** The character that joins a namespace's segments to each other and to a name. It is not in an id's alphabet, so a name containing it is always a path and never a literal id. */
 export declare const NAME_SEPARATOR = "/";
+/** The other names namespace segments go by, as a catalogue manifest declares them: a segment mapped to its aliases. */
+type SegmentAliases = Readonly<Record<string, readonly string[]>>;
 /** The names an entry answers to: its fully qualified names, which must each identify it alone, and every name that resolves to it, which also includes the shorter forms. */
 interface EntryNames {
-  /** The whole namespace joined to each leaf, or the bare leaf for an entry with no namespace. */
+  /** Each address written out in full: the whole path of an address, with no segment alias substituted. */
   readonly full: readonly string[];
-  /** Every suffix of the namespace joined to each leaf, the fully qualified name and the bare leaf among them. */
+  /** Every trailing run of each address's path, the whole path and the bare name among them, with every combination of segment aliases for the namespace part. */
   readonly all: readonly string[];
 }
+/** The entry fields that give it addresses and groups. */
+type Addressed = Pick<Entry, "id" | "namespace" | "aliases">;
+/**
+ * The groups an entry belongs to: the namespace its id and bare aliases sit in, and the group each alias that is a path names, each once, in order of first appearance. A group is a path of segments; an entry belongs to every group above it as well, which the caller reads off the path.
+ * @param entry - The entry.
+ * @returns The groups, empty for an entry with no namespace and no path aliases.
+ */
+export declare function groupsOf(entry: Addressed): string[][];
 /**
- * Works out the names an entry answers to. A leaf is the entry's id or one of its aliases; a name is a leaf with any trailing run of the entry's namespace segments before it, so an entry in namespace `a/b` with id `c` answers to `c`, `b/c` and `a/b/c`.
+ * Works out the names an entry answers to. Each address is a path of segments with the name last, and an address answers to every trailing run of its path, so id `c` in namespace `a/b` answers to `c`, `b/c` and `a/b/c`, and the alias `x/y/d` answers to `d`, `y/d` and `x/y/d`. Where the manifest gives a segment aliases, an address also answers with the alias in the segment's place.
  * @param entry - The entry: only its id, namespace and aliases are read.
+ * @param segmentAliases - The manifest's aliases for namespace segments, if any.
  * @returns The fully qualified names and every name that resolves to the entry.
  */
-export declare function namesOf(entry: Pick<Entry, "id" | "namespace" | "aliases">): EntryNames;
+export declare function namesOf(entry: Addressed, segmentAliases?: SegmentAliases): EntryNames;
 //#endregion
 //#region src/serialise.d.ts
 /**
@@ -100,4 +117,4 @@ export declare function serialise(doc: Entry | Manifest | Crosswalk): string;
  */
 export declare function validateDataset(dataset: Dataset): SyntaxIssue[];
 //#endregion
-export { type Archive, type ArchiveMember, ArchiveMemberSchema, ArchiveSchema, type Catalogue, type CatalogueIndex, CatalogueIndexSchema, type Category, type CategoryId, CategoryIdSchema, type CategoryTarget, type CategoryTargets, type Citation, CitationSchema, type CountedKey, type CrosswalkReference, CrosswalkReferenceSchema, type Dataset, type DatasetQuery, type Entry, type EntryNames, EntrySchema, type GraphEdge, GraphEdgeSchema, type GraphNode, GraphNodeSchema, type GraphV1, GraphV1Schema, HttpUrlSchema, IdSchema, type JsonScalar, JsonScalarSchema, type Licence, LicenceSchema, type Lineage, LineageSchema, type Manifest, ManifestSchema, type Namespace, NamespaceSchema, type Parser, ParserSchema, RESERVED_META_KEYS, type Recipe, RecipeSchema, type RecipeStep, RelativePathSchema, SemVerSchema, type Snapshot, SnapshotSchema, type Source, SourceSchema, type SyntaxIssue, WaybackTimestampSchema, countTarget, createCatalogue, getCategory, getTarget, kindOf, listCategories, parseEntry, parseManifest, waybackUrl };
+export { AliasSchema, type Archive, type ArchiveMember, ArchiveMemberSchema, ArchiveSchema, type Catalogue, type CatalogueIndex, CatalogueIndexSchema, type Category, type CategoryId, CategoryIdSchema, type CategoryTarget, type CategoryTargets, type Citation, CitationSchema, type CountedKey, type CrosswalkReference, CrosswalkReferenceSchema, type Dataset, type DatasetQuery, type Entry, type EntryNames, EntrySchema, type GraphEdge, GraphEdgeSchema, type GraphNode, GraphNodeSchema, type GraphV1, GraphV1Schema, HttpUrlSchema, IdSchema, type JsonScalar, JsonScalarSchema, type Licence, LicenceSchema, type Lineage, LineageSchema, type Manifest, ManifestSchema, type Namespace, type NamespaceNode, NamespaceSchema, type Parser, ParserSchema, RESERVED_META_KEYS, type Recipe, RecipeSchema, type RecipeStep, RelativePathSchema, type SegmentAliases, SemVerSchema, type Snapshot, SnapshotSchema, type Source, SourceSchema, type SyntaxIssue, WaybackTimestampSchema, countTarget, createCatalogue, getCategory, getTarget, kindOf, listCategories, parseEntry, parseManifest, waybackUrl };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as toIssues, B as GraphV1Schema, C as RESERVED_META_KEYS, D as SourceSchema, E as SnapshotSchema, F as getTarget, G as DatasetNotFoundError, H as ArchiveError, I as kindOf, J as RecipeError, K as KeepsetError, L as listCategories, M as CategoryIdSchema, N as countTarget, O as WaybackTimestampSchema, P as getCategory, R as GraphEdgeSchema, S as ParserSchema, T as RelativePathSchema, U as CatalogueSyntaxError, V as JsonScalarSchema, W as DatasetAmbiguousError, Y as UnknownCategoryError, _ as EntrySchema, a as createCatalogue, b as LicenceSchema, c as namesOf, d as SemVerSchema, f as parseManifest, g as CrosswalkReferenceSchema, h as CitationSchema, i as CatalogueIndexSchema, j as waybackUrl, k as parseEntry, l as LineageSchema, m as ArchiveSchema, n as getManifest, p as ArchiveMemberSchema, q as NativeParseError, r as listDatasets, s as NAME_SEPARATOR, t as getDataset, u as ManifestSchema, v as HttpUrlSchema, w as RecipeSchema, x as NamespaceSchema, y as IdSchema, z as GraphNodeSchema } from "./bundled-DaXJpk0C.js";
+import { A as waybackUrl, B as listCategories, C as RecipeSchema, D as WaybackTimestampSchema, E as SourceSchema, F as CategoryIdSchema, G as ArchiveError, H as GraphNodeSchema, I as countTarget, J as DatasetNotFoundError, K as CatalogueSyntaxError, L as getCategory, M as groupsOf, N as namesOf, O as parseEntry, Q as UnknownCategoryError, R as getTarget, S as RESERVED_META_KEYS, T as SnapshotSchema, U as GraphV1Schema, V as GraphEdgeSchema, W as JsonScalarSchema, X as NativeParseError, Y as KeepsetError, Z as RecipeError, _ as HttpUrlSchema, a as CatalogueIndexSchema, b as NamespaceSchema, c as ManifestSchema, d as AliasSchema, f as ArchiveMemberSchema, g as EntrySchema, h as CrosswalkReferenceSchema, i as listNamespaces, j as NAME_SEPARATOR, k as toIssues, l as SemVerSchema, m as CitationSchema, n as getManifest, o as createCatalogue, p as ArchiveSchema, q as DatasetAmbiguousError, r as listDatasets, s as LineageSchema, t as getDataset, u as parseManifest, v as IdSchema, w as RelativePathSchema, x as ParserSchema, y as LicenceSchema, z as kindOf } from "./bundled-DNLiwEcd.js";
 import { validateCrosswalk } from "twindex";
 //#region src/serialise.ts
 /**
@@ -57,4 +57,4 @@ function validateDataset(dataset) {
 	return issues;
 }
 //#endregion
-export { ArchiveError, ArchiveMemberSchema, ArchiveSchema, CatalogueIndexSchema, CatalogueSyntaxError, CategoryIdSchema, CitationSchema, CrosswalkReferenceSchema, DatasetAmbiguousError, DatasetNotFoundError, EntrySchema, GraphEdgeSchema, GraphNodeSchema, GraphV1Schema, HttpUrlSchema, IdSchema, JsonScalarSchema, KeepsetError, LicenceSchema, LineageSchema, ManifestSchema, NAME_SEPARATOR, NamespaceSchema, NativeParseError, ParserSchema, RESERVED_META_KEYS, RecipeError, RecipeSchema, RelativePathSchema, SemVerSchema, SnapshotSchema, SourceSchema, UnknownCategoryError, WaybackTimestampSchema, countTarget, createCatalogue, getCategory, getDataset, getManifest, getTarget, kindOf, listCategories, listDatasets, namesOf, parseEntry, parseManifest, serialise, validateDataset, waybackUrl };
+export { AliasSchema, ArchiveError, ArchiveMemberSchema, ArchiveSchema, CatalogueIndexSchema, CatalogueSyntaxError, CategoryIdSchema, CitationSchema, CrosswalkReferenceSchema, DatasetAmbiguousError, DatasetNotFoundError, EntrySchema, GraphEdgeSchema, GraphNodeSchema, GraphV1Schema, HttpUrlSchema, IdSchema, JsonScalarSchema, KeepsetError, LicenceSchema, LineageSchema, ManifestSchema, NAME_SEPARATOR, NamespaceSchema, NativeParseError, ParserSchema, RESERVED_META_KEYS, RecipeError, RecipeSchema, RelativePathSchema, SemVerSchema, SnapshotSchema, SourceSchema, UnknownCategoryError, WaybackTimestampSchema, countTarget, createCatalogue, getCategory, getDataset, getManifest, getTarget, groupsOf, kindOf, listCategories, listDatasets, listNamespaces, namesOf, parseEntry, parseManifest, serialise, validateDataset, waybackUrl };

package/dist/node/fetch-dataset.d.ts

@@ -1,4 +1,4 @@
-import { B as Entry, C as Dataset, et as Snapshot, i as CategoryTarget, nt as Source } from "../categories-BSJj6C-y.js";
+import { C as Dataset, H as Entry, i as CategoryTarget, it as Source, nt as Snapshot } from "../categories-DzjLQ_fp.js";
 //#region src/node/fetch-dataset.d.ts
 /** The network port a recipe downloads through: `downloadRaw` by default, which returns the bytes exactly as served, or a stand-in under test. */
 export type FetchPort = (url: string, init: {

package/dist/node/fetch-dataset.js

@@ -1,4 +1,4 @@
-import { F as getTarget, H as ArchiveError, J as RecipeError, K as KeepsetError, N as countTarget, o as getOwn, q as NativeParseError, t as getDataset } from "../bundled-DaXJpk0C.js";
+import { G as ArchiveError, I as countTarget, P as getOwn, R as getTarget, X as NativeParseError, Y as KeepsetError, Z as RecipeError, t as getDataset } from "../bundled-DNLiwEcd.js";
 import { RoundTripMismatchError, assertRoundTrip, encode } from "twindex";
 import { createHash } from "node:crypto";
 import { gunzipSync } from "node:zlib";

package/dist-cli/keepset.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { writeFileSync } from "node:fs";
-import { KeepsetError, NAME_SEPARATOR, countTarget, getDataset, listDatasets, validateDataset } from "keepset";
+import { KeepsetError, NAME_SEPARATOR, countTarget, getDataset, listDatasets, listNamespaces, validateDataset } from "keepset";
 import { fetchDataset, roundTripDataset } from "keepset/node";
 import { parseArgs } from "node:util";
 //#region package.json
-var version = "0.11.0";
+var version = "0.13.0";
 const usage = `Usage: keepset <command> [options]
 
 Commands:
@@ -12,8 +12,12 @@ Commands:
          [--category <id>] [--json]
                       list the datasets whose id, alias, namespace, name,
                       description, domain or tags contain the text, filtered by
-                      kind, domain, namespace (and everything beneath it) or
-                      category
+                      kind, domain, namespace (and every namespace beneath it,
+                      segment aliases allowed) or category
+  namespaces [path] [--json]
+                      list the namespaces directly beneath a path, or the
+                      outermost ones, each with how many datasets it holds,
+                      tab-separated
   show <dataset> [--json]
                       print a dataset's metadata, recipe and crosswalk
   fetch <dataset> [--out <file>]
@@ -36,7 +40,7 @@ Options:
 
 Exit status: 0 for a result, a valid entry or a round trip that holds; 1 for an
 invalid entry or a round trip that does not hold; 2 when there is no answer:
-bad usage, an unknown or ambiguous dataset or a recipe that failed.
+bad usage, an unknown or ambiguous dataset or namespace or a recipe that failed.
 `;
 function parseCommandLine(args) {
 	return parseArgs({
@@ -78,6 +82,14 @@ function formatSearch(datasets) {
 	return datasets.map(({ entry }) => `${entry.id}\t${entry.name}\t${entry.category}\t${entry.recipe.status}\n`).join("");
 }
 /**
+* One line per namespace for `namespaces`: path and the number of datasets it holds, tab-separated so the output pipes into other tools.
+* @param nodes - The namespaces.
+* @returns The text.
+*/
+function formatNamespaces(nodes) {
+	return nodes.map((node) => `${node.path}\t${String(node.count)}\n`).join("");
+}
+/**
 * The human-readable form of `show`: the descriptor, sources, licence, citations, recipe and crosswalk rules, one labelled section after another.
 * @param dataset - The dataset.
 * @returns The text.
@@ -183,6 +195,17 @@ async function run(args, library, io) {
 			io.writeStdout(values.json === true ? json(datasets.map((dataset) => dataset.entry)) : formatSearch(datasets));
 			return 0;
 		}
+		if (command === "namespaces") {
+			if (rest.length > 1) return reject("namespaces takes at most one path");
+			const [path] = rest;
+			if (path !== void 0 && library.listDatasets({ namespace: path }).length === 0) {
+				io.writeStderr(`no namespace ${JSON.stringify(path)} in the catalogue\n`);
+				return 2;
+			}
+			const nodes = library.listNamespaces(path);
+			io.writeStdout(values.json === true ? json(nodes) : formatNamespaces(nodes));
+			return 0;
+		}
 		const [name, ...extra] = rest;
 		if (command === void 0) return reject("expected a command");
 		if (![
@@ -240,6 +263,7 @@ process.stdout.on("error", (error) => {
 process.exitCode = await run(process.argv.slice(2), {
 	listDatasets,
 	getDataset,
+	listNamespaces,
 	validateDataset,
 	fetchDataset: async (id) => fetchDataset(id),
 	roundTripDataset: async (id) => roundTripDataset(id),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "keepset",
   "description": "Library, CLI and statically generated catalogue for dataset fetch-and-normalise recipes",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "bin": {
     "keepset": "./dist-cli/keepset.mjs"
   },

package/schemas/entry.schema.json

@@ -1 +1 @@
-{"$defs":{"Crosswalk":{"$ref":"https://cdn.jsdelivr.net/npm/twindex@0.1.1/schemas/twindex.schema.json"},"Entry":{"additionalProperties":false,"properties":{"aliases":{"items":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"minItems":1,"type":"array"},"category":{"enum":["graph/v1"],"type":"string"},"citations":{"items":{"additionalProperties":false,"properties":{"doi":{"pattern":"^10\\.\\d{4,9}\\/\\S+$","type":"string"},"text":{"minLength":1,"type":"string"},"url":{"format":"uri","type":"string"}},"required":["text"],"type":"object"},"type":"array"},"crosswalk":{"anyOf":[{"$ref":"#/$defs/Crosswalk"},{"additionalProperties":false,"properties":{"file":{"type":"string"}},"required":["file"],"type":"object"}]},"description":{"minLength":1,"type":"string"},"domain":{"minLength":1,"type":"string"},"expectedCounts":{"additionalProperties":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"propertyNames":{"pattern":"^[A-Za-z][A-Za-z0-9]*$","type":"string"},"type":"object"},"id":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"licence":{"oneOf":[{"additionalProperties":false,"properties":{"id":{"pattern":"^[A-Za-z0-9][A-Za-z0-9.+-]*$","type":"string"},"kind":{"const":"spdx","type":"string"}},"required":["kind","id"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"custom","type":"string"},"name":{"minLength":1,"type":"string"},"url":{"format":"uri","type":"string"}},"required":["kind","name","url"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"unrecorded","type":"string"}},"required":["kind"],"type":"object"}]},"name":{"minLength":1,"type":"string"},"namespace":{"items":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"minItems":1,"type":"array"},"properties":{"additionalProperties":{"type":["string","number","boolean","null"]},"propertyNames":{"pattern":"^[A-Za-z][A-Za-z0-9]*$","type":"string"},"type":"object"},"recipe":{"oneOf":[{"additionalProperties":false,"properties":{"archive":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"none","type":"string"}},"required":["kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"gzip","type":"string"}},"required":["kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"zip","type":"string"},"member":{"anyOf":[{"additionalProperties":false,"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"},{"additionalProperties":false,"properties":{"extensions":{"items":{"pattern":"^\\.[A-Za-z0-9][A-Za-z0-9.]*$","type":"string"},"minItems":1,"type":"array"}},"required":["extensions"],"type":"object"}]}},"required":["kind","member"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"tar","type":"string"},"member":{"anyOf":[{"additionalProperties":false,"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"},{"additionalProperties":false,"properties":{"extensions":{"items":{"pattern":"^\\.[A-Za-z0-9][A-Za-z0-9.]*$","type":"string"},"minItems":1,"type":"array"}},"required":["extensions"],"type":"object"}]}},"required":["kind","member"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"tar.gz","type":"string"},"member":{"anyOf":[{"additionalProperties":false,"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"},{"additionalProperties":false,"properties":{"extensions":{"items":{"pattern":"^\\.[A-Za-z0-9][A-Za-z0-9.]*$","type":"string"},"minItems":1,"type":"array"}},"required":["extensions"],"type":"object"}]}},"required":["kind","member"],"type":"object"}]},"parser":{"oneOf":[{"additionalProperties":false,"properties":{"commentPrefixes":{"items":{"minLength":1,"type":"string"},"type":"array"},"delimiter":{"enum":["detect","whitespace","tab","comma","space"],"type":"string"},"encoding":{"enum":["utf-8","latin1"],"type":"string"},"format":{"const":"edge-list","type":"string"},"skipLines":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"sourceColumn":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"targetColumn":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["format","encoding","delimiter","skipLines","commentPrefixes","sourceColumn","targetColumn"],"type":"object"},{"additionalProperties":false,"properties":{"encoding":{"enum":["utf-8","latin1"],"type":"string"},"format":{"const":"matrix-market","type":"string"}},"required":["format","encoding"],"type":"object"},{"additionalProperties":false,"properties":{"encoding":{"enum":["utf-8","latin1"],"type":"string"},"format":{"const":"gml","type":"string"}},"required":["format","encoding"],"type":"object"},{"additionalProperties":false,"properties":{"encoding":{"enum":["utf-8","latin1"],"type":"string"},"format":{"const":"pajek","type":"string"}},"required":["format","encoding"],"type":"object"}]},"source":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"status":{"const":"fetchable","type":"string"}},"required":["status","source","archive","parser"],"type":"object"},{"additionalProperties":false,"properties":{"reason":{"minLength":1,"type":"string"},"status":{"const":"not-fetchable","type":"string"}},"required":["status","reason"],"type":"object"}]},"sources":{"items":{"additionalProperties":false,"properties":{"retrieved":{"format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","type":"string"},"snapshot":{"additionalProperties":false,"properties":{"timestamp":{"pattern":"^\\d{8}(?:\\d{6})?$","type":"string"},"url":{"format":"uri","type":"string"}},"required":["url","timestamp"],"type":"object"},"status":{"enum":["live","dead"],"type":"string"},"url":{"format":"uri","type":"string"}},"required":["url","retrieved","status"],"type":"object"},"minItems":1,"type":"array"},"tags":{"items":{"minLength":1,"type":"string"},"type":"array"}},"required":["id","name","tags","category","sources","licence","citations","recipe","crosswalk","expectedCounts","properties"],"type":"object"}},"$id":"https://cdn.jsdelivr.net/npm/keepset@0.11.0/schemas/entry.schema.json","$ref":"#/$defs/Entry","$schema":"https://json-schema.org/draft/2020-12/schema"}
+{"$defs":{"Crosswalk":{"$ref":"https://cdn.jsdelivr.net/npm/twindex@0.1.1/schemas/twindex.schema.json"},"Entry":{"additionalProperties":false,"properties":{"aliases":{"items":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*(?:\\/[A-Za-z0-9][A-Za-z0-9._-]*)*$","type":"string"},"minItems":1,"type":"array"},"category":{"enum":["graph/v1"],"type":"string"},"citations":{"items":{"additionalProperties":false,"properties":{"doi":{"pattern":"^10\\.\\d{4,9}\\/\\S+$","type":"string"},"text":{"minLength":1,"type":"string"},"url":{"format":"uri","type":"string"}},"required":["text"],"type":"object"},"type":"array"},"crosswalk":{"anyOf":[{"$ref":"#/$defs/Crosswalk"},{"additionalProperties":false,"properties":{"file":{"type":"string"}},"required":["file"],"type":"object"}]},"description":{"minLength":1,"type":"string"},"domain":{"minLength":1,"type":"string"},"expectedCounts":{"additionalProperties":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"propertyNames":{"pattern":"^[A-Za-z][A-Za-z0-9]*$","type":"string"},"type":"object"},"id":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"licence":{"oneOf":[{"additionalProperties":false,"properties":{"id":{"pattern":"^[A-Za-z0-9][A-Za-z0-9.+-]*$","type":"string"},"kind":{"const":"spdx","type":"string"}},"required":["kind","id"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"custom","type":"string"},"name":{"minLength":1,"type":"string"},"url":{"format":"uri","type":"string"}},"required":["kind","name","url"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"unrecorded","type":"string"}},"required":["kind"],"type":"object"}]},"name":{"minLength":1,"type":"string"},"namespace":{"items":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"minItems":1,"type":"array"},"properties":{"additionalProperties":{"type":["string","number","boolean","null"]},"propertyNames":{"pattern":"^[A-Za-z][A-Za-z0-9]*$","type":"string"},"type":"object"},"recipe":{"oneOf":[{"additionalProperties":false,"properties":{"archive":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"none","type":"string"}},"required":["kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"gzip","type":"string"}},"required":["kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"zip","type":"string"},"member":{"anyOf":[{"additionalProperties":false,"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"},{"additionalProperties":false,"properties":{"extensions":{"items":{"pattern":"^\\.[A-Za-z0-9][A-Za-z0-9.]*$","type":"string"},"minItems":1,"type":"array"}},"required":["extensions"],"type":"object"}]}},"required":["kind","member"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"tar","type":"string"},"member":{"anyOf":[{"additionalProperties":false,"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"},{"additionalProperties":false,"properties":{"extensions":{"items":{"pattern":"^\\.[A-Za-z0-9][A-Za-z0-9.]*$","type":"string"},"minItems":1,"type":"array"}},"required":["extensions"],"type":"object"}]}},"required":["kind","member"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"tar.gz","type":"string"},"member":{"anyOf":[{"additionalProperties":false,"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"},{"additionalProperties":false,"properties":{"extensions":{"items":{"pattern":"^\\.[A-Za-z0-9][A-Za-z0-9.]*$","type":"string"},"minItems":1,"type":"array"}},"required":["extensions"],"type":"object"}]}},"required":["kind","member"],"type":"object"}]},"parser":{"oneOf":[{"additionalProperties":false,"properties":{"commentPrefixes":{"items":{"minLength":1,"type":"string"},"type":"array"},"delimiter":{"enum":["detect","whitespace","tab","comma","space"],"type":"string"},"encoding":{"enum":["utf-8","latin1"],"type":"string"},"format":{"const":"edge-list","type":"string"},"skipLines":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"sourceColumn":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"targetColumn":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["format","encoding","delimiter","skipLines","commentPrefixes","sourceColumn","targetColumn"],"type":"object"},{"additionalProperties":false,"properties":{"encoding":{"enum":["utf-8","latin1"],"type":"string"},"format":{"const":"matrix-market","type":"string"}},"required":["format","encoding"],"type":"object"},{"additionalProperties":false,"properties":{"encoding":{"enum":["utf-8","latin1"],"type":"string"},"format":{"const":"gml","type":"string"}},"required":["format","encoding"],"type":"object"},{"additionalProperties":false,"properties":{"encoding":{"enum":["utf-8","latin1"],"type":"string"},"format":{"const":"pajek","type":"string"}},"required":["format","encoding"],"type":"object"}]},"source":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"status":{"const":"fetchable","type":"string"}},"required":["status","source","archive","parser"],"type":"object"},{"additionalProperties":false,"properties":{"reason":{"minLength":1,"type":"string"},"status":{"const":"not-fetchable","type":"string"}},"required":["status","reason"],"type":"object"}]},"sources":{"items":{"additionalProperties":false,"properties":{"retrieved":{"format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","type":"string"},"snapshot":{"additionalProperties":false,"properties":{"timestamp":{"pattern":"^\\d{8}(?:\\d{6})?$","type":"string"},"url":{"format":"uri","type":"string"}},"required":["url","timestamp"],"type":"object"},"status":{"enum":["live","dead"],"type":"string"},"url":{"format":"uri","type":"string"}},"required":["url","retrieved","status"],"type":"object"},"minItems":1,"type":"array"},"tags":{"items":{"minLength":1,"type":"string"},"type":"array"}},"required":["id","name","tags","category","sources","licence","citations","recipe","crosswalk","expectedCounts","properties"],"type":"object"}},"$id":"https://cdn.jsdelivr.net/npm/keepset@0.13.0/schemas/entry.schema.json","$ref":"#/$defs/Entry","$schema":"https://json-schema.org/draft/2020-12/schema"}

package/schemas/manifest.schema.json

@@ -1 +1 @@
-{"$defs":{"Manifest":{"additionalProperties":false,"properties":{"description":{"minLength":1,"type":"string"},"id":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"lineage":{"additionalProperties":false,"properties":{"catalogue":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"repository":{"format":"uri","type":"string"},"version":{"pattern":"^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$","type":"string"}},"required":["catalogue","version","repository"],"type":"object"},"name":{"minLength":1,"type":"string"},"repository":{"format":"uri","type":"string"},"version":{"pattern":"^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$","type":"string"}},"required":["id","name","description","version","repository"],"type":"object"}},"$id":"https://cdn.jsdelivr.net/npm/keepset@0.11.0/schemas/manifest.schema.json","$ref":"#/$defs/Manifest","$schema":"https://json-schema.org/draft/2020-12/schema"}
+{"$defs":{"Manifest":{"additionalProperties":false,"properties":{"description":{"minLength":1,"type":"string"},"id":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"lineage":{"additionalProperties":false,"properties":{"catalogue":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"repository":{"format":"uri","type":"string"},"version":{"pattern":"^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$","type":"string"}},"required":["catalogue","version","repository"],"type":"object"},"name":{"minLength":1,"type":"string"},"namespaceAliases":{"additionalProperties":{"items":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"minItems":1,"type":"array"},"propertyNames":{"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","type":"string"},"type":"object"},"repository":{"format":"uri","type":"string"},"version":{"pattern":"^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$","type":"string"}},"required":["id","name","description","version","repository"],"type":"object"}},"$id":"https://cdn.jsdelivr.net/npm/keepset@0.13.0/schemas/manifest.schema.json","$ref":"#/$defs/Manifest","$schema":"https://json-schema.org/draft/2020-12/schema"}