keepset 0.10.0 → 0.11.0

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

@@ -3,6 +3,10 @@ import { z } from "zod";
 //#region src/entry.d.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. */
 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. */
+/** 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>;
 /** An http or https URL: the only schemes a recipe may download from. Any host is allowed, an address or a single-label name included, so a fork can point a recipe at a server on its own network. */
 declare const HttpUrlSchema: z.ZodURL;
 /** A Wayback Machine timestamp, `YYYYMMDD` or `YYYYMMDDhhmmss`: the moment the snapshot is pinned to. */
@@ -211,10 +215,12 @@ type CrosswalkReference = z.infer<typeof CrosswalkReferenceSchema>;
 /** The meta keys a fetched result takes from the entry's own descriptor, which its `properties` therefore may not also set. */
 declare const RESERVED_META_KEYS: readonly ["id", "name"];
 /**
- * One catalogue entry: the descriptor (id, name, description, domain, tags), the category whose target the entry resolves to, where the bytes come from, the licence and citations, the recipe, the crosswalk, the counts a fetched result is expected to have and the dataset's recorded properties. The kind of data is the category's (`kindOf(category)`), never a second field that could disagree with it.
+ * One catalogue entry: the descriptor (id, optional namespace and aliases, name, description, domain, tags), the category whose target the entry resolves to, where the bytes come from, the licence and citations, the recipe, the crosswalk, the counts a fetched result is expected to have and the dataset's recorded properties. The kind of data is the category's (`kindOf(category)`), never a second field that could disagree with it.
  */
 declare const EntrySchema: z.ZodObject<{
   id: z.ZodString;
+  namespace: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
   name: z.ZodString;
   description: z.ZodOptional<z.ZodString>;
   domain: z.ZodOptional<z.ZodString>;
@@ -411,6 +417,8 @@ declare const EntrySchema: z.ZodObject<{
     };
     expectedCounts: Record<string, number>;
     properties: Record<string, string | number | boolean | null>;
+    namespace?: string[] | undefined;
+    aliases?: string[] | undefined;
     description?: string | undefined;
     domain?: string | undefined;
   };
@@ -473,7 +481,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 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 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.
  */
 declare const CatalogueIndexSchema: z.ZodObject<{
   manifest: z.ZodObject<{
@@ -506,6 +514,8 @@ declare const CatalogueIndexSchema: z.ZodObject<{
   }>, unknown>;
   entries: z.ZodArray<z.ZodObject<{
     id: z.ZodString;
+    namespace: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     domain: z.ZodOptional<z.ZodString>;
@@ -702,6 +712,8 @@ declare const CatalogueIndexSchema: z.ZodObject<{
       };
       expectedCounts: Record<string, number>;
       properties: Record<string, string | number | boolean | null>;
+      namespace?: string[] | undefined;
+      aliases?: string[] | undefined;
       description?: string | undefined;
       domain?: string | undefined;
     };
@@ -806,6 +818,8 @@ declare const CatalogueIndexSchema: z.ZodObject<{
       };
       expectedCounts: Record<string, number>;
       properties: Record<string, string | number | boolean | null>;
+      namespace?: string[] | undefined;
+      aliases?: string[] | undefined;
       description?: string | undefined;
       domain?: string | undefined;
     }[];
@@ -827,7 +841,9 @@ interface DatasetQuery {
   readonly category?: string;
   /** The entry's domain, matched exactly. */
   readonly domain?: string;
-  /** Text that must appear, ignoring case, in the entry's id, name, description, domain or one of its tags. */
+  /** A namespace path such as `suitesparse` or `suitesparse/gset`: matches the entries in that namespace and every namespace beneath it. */
+  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. */
   readonly text?: string;
 }
 /** A queryable catalogue: the surface `listDatasets` and `getDataset` are bound to. */
@@ -840,12 +856,13 @@ interface Catalogue {
    */
   readonly listDatasets: (query?: DatasetQuery) => Dataset[];
   /**
-   * Returns one dataset by entry id.
-   * @param id - The entry id; untrusted, so lookup never reaches inherited properties.
+   * Returns one dataset by name. An entry's own id always resolves to it, ahead of any alias or shorter form; otherwise the name is an alias, or an id or alias with any trailing run of the entry's namespace before it (`b/c` or `a/b/c` for id `c` in namespace `a/b`), and resolves only when exactly one entry answers to it.
+   * @param name - An entry id, alias or qualified name; untrusted, so lookup never reaches inherited properties.
    * @returns The dataset.
-   * @throws DatasetNotFoundError when no entry has that id.
+   * @throws DatasetAmbiguousError when more than one entry answers to the name and none has it as its id.
+   * @throws DatasetNotFoundError when no entry answers to the name.
    */
-  readonly getDataset: (id: string) => Dataset;
+  readonly getDataset: (name: string) => Dataset;
 }
 /**
  * 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.
@@ -957,4 +974,4 @@ declare function listCategories(): readonly Category[];
  */
 declare function countTarget(id: CategoryId, target: CategoryTarget): ReadonlyMap<string, number>;
 //#endregion
-export { SnapshotSchema 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, RESERVED_META_KEYS as J, Parser as K, CitationSchema as L, Archive as M, ArchiveMember as N, Manifest as O, ArchiveMemberSchema as P, Snapshot as Q, CrosswalkReference as R, CatalogueIndexSchema as S, createCatalogue as T, IdSchema as U, EntrySchema as V, Licence as W, RecipeSchema as X, Recipe as Y, RelativePathSchema as Z, GraphV1Schema as _, CategoryTargets as a, Catalogue as b, getCategory as c, listCategories as d, Source as et, GraphEdge as f, GraphV1 as g, GraphNodeSchema as h, CategoryTarget as i, waybackUrl as it, parseManifest as j, ManifestSchema as k, getTarget as l, GraphNode as m, CategoryId as n, WaybackTimestampSchema as nt, CountedKey as o, GraphEdgeSchema as p, ParserSchema as q, CategoryIdSchema as r, parseEntry as rt, countTarget as s, Category as t, SourceSchema as tt, kindOf as u, JsonScalar as v, DatasetQuery as w, CatalogueIndex as x, JsonScalarSchema as y, CrosswalkReferenceSchema as z };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as SnapshotSchema, 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 RESERVED_META_KEYS, K as Parser, L as CitationSchema, M as Archive, N as ArchiveMember, O as Manifest, P as ArchiveMemberSchema, Q as Snapshot, R as CrosswalkReference, S as CatalogueIndexSchema, T as createCatalogue, U as IdSchema, V as EntrySchema, W as Licence, X as RecipeSchema, Y as Recipe, Z as RelativePathSchema, _ as GraphV1Schema, a as CategoryTargets, b as Catalogue, c as getCategory, d as listCategories, et as Source, f as GraphEdge, g as GraphV1, h as GraphNodeSchema, i as CategoryTarget, it as waybackUrl, j as parseManifest, k as ManifestSchema, l as getTarget, m as GraphNode, n as CategoryId, nt as WaybackTimestampSchema, o as CountedKey, p as GraphEdgeSchema, q as ParserSchema, r as CategoryIdSchema, rt as parseEntry, s as countTarget, t as Category, tt as SourceSchema, u as kindOf, v as JsonScalar, w as DatasetQuery, x as CatalogueIndex, y as JsonScalarSchema, z as CrosswalkReferenceSchema } from "./categories-CUf1VecC.js";
+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 { 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. */
@@ -30,11 +30,17 @@ export declare class NativeParseError extends KeepsetError {
 }
 /** Thrown when an archive does not hold exactly one member the recipe's member selector matches, or is not a well-formed archive of its stated kind. */
 export declare class ArchiveError extends KeepsetError {}
-/** Thrown when no entry in the catalogue has the requested id. */
+/** Thrown when no entry in the catalogue answers to the requested id, alias or qualified name. */
 export declare class DatasetNotFoundError extends KeepsetError {
   readonly datasetId: string;
   constructor(datasetId: string);
 }
+/** Thrown when a name that is not an entry's own id is a valid way to address more than one entry. Carries the ids of the entries it could mean, so the message says how to be specific. */
+export declare class DatasetAmbiguousError extends KeepsetError {
+  readonly requested: string;
+  readonly candidateIds: readonly string[];
+  constructor(name: string, candidateIds: readonly string[]);
+}
 /** The step of a recipe that failed: the recipe itself (not fetchable), downloading the source, unpacking the archive, parsing the native shape, applying the crosswalk, or validating the result against the category target. */
 type RecipeStep = "recipe" | "download" | "extract" | "parse" | "crosswalk" | "validate";
 /** Thrown when running an entry's recipe fails. Names the entry and the failing step, and carries the underlying error as `cause`; a recipe never resolves to a partial or default-shaped result. */
@@ -61,6 +67,23 @@ export declare function getDataset(id: string): Dataset;
 /** @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 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. */
+  readonly full: readonly string[];
+  /** Every suffix of the namespace joined to each leaf, the fully qualified name and the bare leaf among them. */
+  readonly all: readonly 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`.
+ * @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.
+ */
+export declare function namesOf(entry: Pick<Entry, "id" | "namespace" | "aliases">): EntryNames;
+//#endregion
 //#region src/serialise.d.ts
 /**
  * Serialises a catalogue document (an entry, a manifest or a crosswalk file) as its file holds it: two-space indented JSON with keys in ascending order and a trailing newline. The form depends only on the document's content, so parsing a file written this way and serialising the result reproduces the file byte for byte.
@@ -77,4 +100,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, 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 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 { 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 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as countTarget, B as CatalogueSyntaxError, C as SnapshotSchema, D as toIssues, E as parseEntry, F as GraphEdgeSchema, G as UnknownCategoryError, H as KeepsetError, I as GraphNodeSchema, L as GraphV1Schema, M as getTarget, N as kindOf, O as waybackUrl, P as listCategories, R as JsonScalarSchema, S as RelativePathSchema, T as WaybackTimestampSchema, U as NativeParseError, V as DatasetNotFoundError, W as RecipeError, _ as IdSchema, a as createCatalogue, b as RESERVED_META_KEYS, c as ManifestSchema, d as ArchiveMemberSchema, f as ArchiveSchema, g as HttpUrlSchema, h as EntrySchema, i as CatalogueIndexSchema, j as getCategory, k as CategoryIdSchema, l as SemVerSchema, m as CrosswalkReferenceSchema, n as getManifest, p as CitationSchema, r as listDatasets, s as LineageSchema, t as getDataset, u as parseManifest, v as LicenceSchema, w as SourceSchema, x as RecipeSchema, y as ParserSchema, z as ArchiveError } from "./bundled-BIBLzetw.js";
+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 { 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, DatasetNotFoundError, EntrySchema, GraphEdgeSchema, GraphNodeSchema, GraphV1Schema, HttpUrlSchema, IdSchema, JsonScalarSchema, KeepsetError, LicenceSchema, LineageSchema, ManifestSchema, NativeParseError, ParserSchema, RESERVED_META_KEYS, RecipeError, RecipeSchema, RelativePathSchema, SemVerSchema, SnapshotSchema, SourceSchema, UnknownCategoryError, WaybackTimestampSchema, countTarget, createCatalogue, getCategory, getDataset, getManifest, getTarget, kindOf, listCategories, listDatasets, parseEntry, parseManifest, serialise, validateDataset, waybackUrl };
+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 };

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

@@ -1,4 +1,4 @@
-import { B as Entry, C as Dataset, Q as Snapshot, et as Source, i as CategoryTarget } from "../categories-CUf1VecC.js";
+import { B as Entry, C as Dataset, et as Snapshot, i as CategoryTarget, nt as Source } from "../categories-BSJj6C-y.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 { A as countTarget, H as KeepsetError, M as getTarget, U as NativeParseError, W as RecipeError, o as getOwn, t as getDataset, z as ArchiveError } from "../bundled-BIBLzetw.js";
+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 { RoundTripMismatchError, assertRoundTrip, encode } from "twindex";
 import { createHash } from "node:crypto";
 import { gunzipSync } from "node:zlib";

package/dist-cli/keepset.mjs

@@ -1,33 +1,42 @@
 #!/usr/bin/env node
 import { writeFileSync } from "node:fs";
-import { KeepsetError, countTarget, getDataset, listDatasets, validateDataset } from "keepset";
+import { KeepsetError, NAME_SEPARATOR, countTarget, getDataset, listDatasets, validateDataset } from "keepset";
 import { fetchDataset, roundTripDataset } from "keepset/node";
 import { parseArgs } from "node:util";
 //#region package.json
-var version = "0.10.0";
+var version = "0.11.0";
 const usage = `Usage: keepset <command> [options]
 
 Commands:
-  search [text] [--kind <kind>] [--domain <domain>] [--category <id>] [--json]
-                      list the datasets whose id, name, description, domain or
-                      tags contain the text, filtered by kind, domain or category
-  show <id> [--json]  print a dataset's metadata, recipe and crosswalk
-  fetch <id> [--out <file>]
+  search [text] [--kind <kind>] [--domain <domain>] [--namespace <path>]
+         [--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
+  show <dataset> [--json]
+                      print a dataset's metadata, recipe and crosswalk
+  fetch <dataset> [--out <file>]
                       run the dataset's recipe and write the normalised result
                       to <file> (default <id>.json), with its provenance beside
                       it in <file without .json>.provenance.json
-  validate <id>       check the entry against the entry schema and its
+  validate <dataset>  check the entry against the entry schema and its
                       crosswalk against twindex's validation
-  roundtrip <id>      fetch the dataset and check that decoding the encoded
+  roundtrip <dataset> fetch the dataset and check that decoding the encoded
                       native document gives it back
 
+A <dataset> is an entry id, an alias, or a qualified name such as
+suitesparse/gset/g53, written with / between the namespace and the name. Any
+leading part of the namespace may be dropped (gset/g53, g53) while the name
+still means one dataset; an entry's own id always means that entry.
+
 Options:
   --help, -h          print this help
   --version, -v       print the version
 
 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 dataset or a recipe that failed.
+bad usage, an unknown or ambiguous dataset or a recipe that failed.
 `;
 function parseCommandLine(args) {
 	return parseArgs({
@@ -37,6 +46,7 @@ function parseCommandLine(args) {
 		options: {
 			kind: { type: "string" },
 			domain: { type: "string" },
+			namespace: { type: "string" },
 			category: { type: "string" },
 			json: { type: "boolean" },
 			out: { type: "string" },
@@ -77,6 +87,8 @@ function formatShow(dataset) {
 	const lines = [`${entry.name} (${entry.id})`];
 	if (entry.description !== void 0) lines.push("", entry.description);
 	lines.push("", `category: ${entry.category} (kind ${dataset.kind})`, `catalogue: ${dataset.catalogue.id} ${dataset.catalogue.version}`);
+	if (entry.namespace !== void 0) lines.push(`namespace: ${entry.namespace.join(NAME_SEPARATOR)}`);
+	if (entry.aliases !== void 0) lines.push(`aliases: ${entry.aliases.join(", ")}`);
 	if (entry.domain !== void 0) lines.push(`domain: ${entry.domain}`);
 	if (entry.tags.length > 0) lines.push(`tags: ${entry.tags.join(", ")}`);
 	const { licence } = entry;
@@ -164,13 +176,14 @@ async function run(args, library, io) {
 				...text === void 0 ? {} : { text },
 				...values.kind === void 0 ? {} : { kind: values.kind },
 				...values.domain === void 0 ? {} : { domain: values.domain },
+				...values.namespace === void 0 ? {} : { namespace: values.namespace },
 				...values.category === void 0 ? {} : { category: values.category }
 			};
 			const datasets = library.listDatasets(query);
 			io.writeStdout(values.json === true ? json(datasets.map((dataset) => dataset.entry)) : formatSearch(datasets));
 			return 0;
 		}
-		const [id, ...extra] = rest;
+		const [name, ...extra] = rest;
 		if (command === void 0) return reject("expected a command");
 		if (![
 			"show",
@@ -178,14 +191,15 @@ async function run(args, library, io) {
 			"validate",
 			"roundtrip"
 		].includes(command)) return reject(`unknown command ${command}`);
-		if (id === void 0 || extra.length > 0) return reject(`${command} takes exactly one dataset id`);
+		if (name === void 0 || extra.length > 0) return reject(`${command} takes exactly one dataset`);
+		const dataset = library.getDataset(name);
+		const { id } = dataset.entry;
 		if (command === "show") {
-			const dataset = library.getDataset(id);
 			io.writeStdout(values.json === true ? json(dataset) : formatShow(dataset));
 			return 0;
 		}
 		if (command === "validate") {
-			const issues = library.validateDataset(library.getDataset(id));
+			const issues = library.validateDataset(dataset);
 			if (issues.length > 0) {
 				io.writeStdout(formatIssues(issues));
 				return 1;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "keepset",
   "description": "Library, CLI and statically generated catalogue for dataset fetch-and-normalise recipes",
-  "version": "0.10.0",
+  "version": "0.11.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":{"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"},"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.10.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._-]*$","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"}

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.10.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"},"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"}