keepset 0.0.4 → 0.1.0

package/dist/index.d.ts

@@ -1 +1,106 @@
-export {}
+import { z } from "zod";
+//#region src/targets/graph-v1.d.ts
+/** A JSON scalar: the only values graph/v1 metadata may hold, so `meta` stays a flat record any consumer can tabulate. `z.number()` already rejects NaN and the infinities, which JSON cannot carry. */
+export declare const JsonScalarSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+type JsonScalar = z.infer<typeof JsonScalarSchema>;
+/** A node: an id, an optional type, and whatever else the dataset carries. The target fixes only what every graph consumer needs, so extra fields pass through untouched. */
+export declare const GraphNodeSchema: z.ZodObject<{
+  id: z.ZodString;
+  type: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type GraphNode = z.infer<typeof GraphNodeSchema>;
+/** An edge: source and target node ids, an optional type, and whatever else the dataset carries. Direction is the dataset's own: graph/v1 records it in `meta`, never by duplicating edges. */
+export declare const GraphEdgeSchema: z.ZodObject<{
+  source: z.ZodString;
+  target: z.ZodString;
+  type: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type GraphEdge = z.infer<typeof GraphEdgeSchema>;
+/**
+ * The graph/v1 normalisation target: `{ meta, nodes, edges }`, the shape the thesis pipeline's benchmark cache already uses. It describes the result `fetchDataset` resolves a graph entry to, not what a source file may contain. Beyond the field shapes it checks the two properties every consumer relies on: node ids are unique, and every edge endpoint names a node.
+ */
+export declare const GraphV1Schema: z.ZodObject<{
+  meta: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+  nodes: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+  }, z.core.$loose>>;
+  edges: z.ZodArray<z.ZodObject<{
+    source: z.ZodString;
+    target: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+  }, z.core.$loose>>;
+}, z.core.$strict> & {
+  is: (value: unknown) => value is {
+    meta: Record<string, string | number | boolean | null>;
+    nodes: {
+      [x: string]: unknown;
+      id: string;
+      type?: string | undefined;
+    }[];
+    edges: {
+      [x: string]: unknown;
+      source: string;
+      target: string;
+      type?: string | undefined;
+    }[];
+  };
+};
+type GraphV1 = z.infer<typeof GraphV1Schema>;
+//#endregion
+//#region src/categories.d.ts
+/** Every category id the registry knows. A category id is `<kind>/v<version>`: the kind of data, and the version of its normalisation target, so a breaking change to a target is a new category rather than an edit to an old one. */
+export declare const CategoryIdSchema: z.ZodEnum<{
+  "graph/v1": "graph/v1";
+}>;
+type CategoryId = z.infer<typeof CategoryIdSchema>;
+/** The normalisation target each category resolves to, keyed by category id. */
+interface CategoryTargets {
+  readonly "graph/v1": GraphV1;
+}
+/** The normalised shape of any category: what `fetchDataset` can resolve to. */
+type CategoryTarget = CategoryTargets[CategoryId];
+/** One category: its id, what it holds, and the schema of its normalisation target. */
+interface Category<Id extends CategoryId = CategoryId> {
+  readonly id: Id;
+  readonly description: string;
+  readonly target: z.ZodType<CategoryTargets[Id]>;
+}
+/**
+ * Looks up a category by id.
+ * @param id - Any string; category ids usually come from entry documents, so the argument is untrusted.
+ * @returns The category.
+ * @throws UnknownCategoryError when no category has that id.
+ */
+export declare function getCategory<Id extends CategoryId>(id: Id): Category<Id>;
+export declare function getCategory(id: string): Category;
+/**
+ * Returns the schema of a category's normalisation target.
+ * @param id - Any string, as for `getCategory`.
+ * @returns The target schema.
+ * @throws UnknownCategoryError when no category has that id.
+ */
+export declare function getTarget<Id extends CategoryId>(id: Id): z.ZodType<CategoryTargets[Id]>;
+export declare function getTarget(id: string): z.ZodType<CategoryTarget>;
+/**
+ * The kind of data a category holds: the part of its id before the version.
+ * @param id - A category id.
+ * @returns The kind, such as `graph`.
+ */
+export declare function kindOf(id: CategoryId): string;
+/** @returns Every registered category, in id order. */
+export declare function listCategories(): readonly Category[];
+//#endregion
+//#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. */
+export declare class KeepsetError extends Error {
+  constructor(message: string);
+}
+/** Thrown when a category id names no category in the registry. Carries the ids that do exist, so the message says what would have been accepted. */
+export declare class UnknownCategoryError extends KeepsetError {
+  readonly categoryId: string;
+  readonly knownIds: readonly string[];
+  constructor(categoryId: string, knownIds: readonly string[]);
+}
+//#endregion
+export type { Category, CategoryId, CategoryTarget, CategoryTargets, GraphEdge, GraphNode, GraphV1, JsonScalar };

package/dist/index.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+//#region src/errors.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. */
+var KeepsetError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = new.target.name;
+	}
+};
+/** Thrown when a category id names no category in the registry. Carries the ids that do exist, so the message says what would have been accepted. */
+var UnknownCategoryError = class extends KeepsetError {
+	categoryId;
+	knownIds;
+	constructor(categoryId, knownIds) {
+		super(`unknown category ${JSON.stringify(categoryId)}: known categories are ${knownIds.join(", ")}`);
+		this.categoryId = categoryId;
+		this.knownIds = knownIds;
+	}
+};
+//#endregion
+//#region src/define.ts
+/**
+* Attaches a type guard to a Zod schema (the schema-attached guard pattern: validation, inference and narrowing share one definition, so the three cannot drift). This module is isolated because it is the one place in the package that augments an object in place with Object.assign, which the house lint rule that eslint.config.ts turns off for this file alone would otherwise reject: object spread is no alternative, as it copies own properties only and drops the Zod prototype's parse/refine methods.
+* @param schema - The schema to augment.
+* @returns The same schema object, now also carrying `is`.
+*/
+function define(schema) {
+	return Object.assign(schema, { is(value) {
+		return schema.safeParse(value).success;
+	} });
+}
+//#endregion
+//#region src/targets/graph-v1.ts
+/** A JSON scalar: the only values graph/v1 metadata may hold, so `meta` stays a flat record any consumer can tabulate. `z.number()` already rejects NaN and the infinities, which JSON cannot carry. */
+const JsonScalarSchema = z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.null()
+]);
+/** A node: an id, an optional type, and whatever else the dataset carries. The target fixes only what every graph consumer needs, so extra fields pass through untouched. */
+const GraphNodeSchema = z.looseObject({
+	id: z.string().min(1),
+	type: z.string().min(1).optional()
+});
+/** An edge: source and target node ids, an optional type, and whatever else the dataset carries. Direction is the dataset's own: graph/v1 records it in `meta`, never by duplicating edges. */
+const GraphEdgeSchema = z.looseObject({
+	source: z.string().min(1),
+	target: z.string().min(1),
+	type: z.string().min(1).optional()
+});
+/**
+* The graph/v1 normalisation target: `{ meta, nodes, edges }`, the shape the thesis pipeline's benchmark cache already uses. It describes the result `fetchDataset` resolves a graph entry to, not what a source file may contain. Beyond the field shapes it checks the two properties every consumer relies on: node ids are unique, and every edge endpoint names a node.
+*/
+const GraphV1Schema = define(z.object({
+	meta: z.record(z.string(), JsonScalarSchema),
+	nodes: z.array(GraphNodeSchema),
+	edges: z.array(GraphEdgeSchema)
+}).strict().superRefine((graph, ctx) => {
+	const ids = /* @__PURE__ */ new Set();
+	for (const [index, node] of graph.nodes.entries()) {
+		if (ids.has(node.id)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"nodes",
+				index,
+				"id"
+			],
+			message: `duplicate node id ${JSON.stringify(node.id)}`
+		});
+		ids.add(node.id);
+	}
+	for (const [index, edge] of graph.edges.entries()) for (const end of ["source", "target"]) if (!ids.has(edge[end])) ctx.addIssue({
+		code: "custom",
+		path: [
+			"edges",
+			index,
+			end
+		],
+		message: `edge ${end} ${JSON.stringify(edge[end])} names no node`
+	});
+}));
+//#endregion
+//#region src/categories.ts
+/** Every category id the registry knows. A category id is `<kind>/v<version>`: the kind of data, and the version of its normalisation target, so a breaking change to a target is a new category rather than an edit to an old one. */
+const CategoryIdSchema = z.enum(["graph/v1"]);
+/** The registry. Adding a category is adding its id to `CategoryIdSchema` and its entry here, with its target schema beside graph/v1's in src/targets/: the mapped type makes the compiler reject a registry that misses an id or has one too many. */
+const registry = { "graph/v1": {
+	id: "graph/v1",
+	description: "A graph as { meta, nodes, edges }: a flat record of scalar metadata, nodes carrying at least an id, and edges carrying at least source and target node ids, with optional node and edge types.",
+	target: GraphV1Schema
+} };
+function getCategory(id) {
+	const parsed = CategoryIdSchema.safeParse(id);
+	if (!parsed.success) throw new UnknownCategoryError(id, CategoryIdSchema.options);
+	return registry[parsed.data];
+}
+function getTarget(id) {
+	return getCategory(id).target;
+}
+/**
+* The kind of data a category holds: the part of its id before the version.
+* @param id - A category id.
+* @returns The kind, such as `graph`.
+*/
+function kindOf(id) {
+	return id.slice(0, id.indexOf("/"));
+}
+/** @returns Every registered category, in id order. */
+function listCategories() {
+	return CategoryIdSchema.options.map((id) => getCategory(id));
+}
+//#endregion
+export { CategoryIdSchema, GraphEdgeSchema, GraphNodeSchema, GraphV1Schema, JsonScalarSchema, KeepsetError, UnknownCategoryError, getCategory, getTarget, kindOf, listCategories };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "keepset",
   "description": "Library, CLI and statically generated catalogue for dataset fetch-and-normalise recipes",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "dependencies": {
     "zod": "4.6.6"
   },
@@ -71,7 +71,7 @@
     "prepare": "husky",
     "prepublishOnly": "pnpm run lint:check && pnpm run typecheck && pnpm run test && pnpm run build && publint && attw --pack --profile esm-only",
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.node.json"
   },
   "sideEffects": false,
   "type": "module",