@remit/config-format 0.0.1

package/src/read.ts

@@ -0,0 +1,109 @@
+import type { $ZodIssue, $ZodIssueUnrecognizedKeys } from "zod/v4/core";
+import {
+	type ReaderConfigDocument,
+	ReaderConfigDocumentSchema,
+} from "./document.js";
+import { ConfigEnvelopeSchema } from "./envelope.js";
+import {
+	ConfigCredentialError,
+	ConfigKindError,
+	ConfigMalformedError,
+	ConfigNotAnObjectError,
+	ConfigUnknownKeysError,
+	ConfigVersionError,
+	formatPath,
+} from "./errors.js";
+import {
+	type ConfigDocumentShape,
+	type ConfigMigration,
+	liftToCurrentVersion,
+} from "./migrations.js";
+import { CONFIG_KIND, CURRENT_SCHEMA_VERSION } from "./version.js";
+
+/**
+ * Substrings that make a key a credential. Matched on the lowercased key so a
+ * field arrives refused whatever the exporter chose to call it — `password`,
+ * `smtpPasswordHash`, `oauthRefreshToken` are all the same mistake.
+ */
+const CREDENTIAL_MARKERS = [
+	"password",
+	"passphrase",
+	"secret",
+	"token",
+	"apikey",
+	"privatekey",
+];
+
+const isCredentialKey = (key: string): boolean => {
+	const lowered = key.toLowerCase();
+	return CREDENTIAL_MARKERS.some((marker) => lowered.includes(marker));
+};
+
+const unrecognizedKeys = (
+	issues: readonly $ZodIssue[],
+): $ZodIssueUnrecognizedKeys[] =>
+	issues.filter(
+		(issue): issue is $ZodIssueUnrecognizedKeys =>
+			issue.code === "unrecognized_keys",
+	);
+
+/**
+ * Read a configuration document in two passes: the envelope decides what the
+ * file is and which version it claims, the migration chain lifts it to the
+ * version this reader knows, and only then does the strict schema see it.
+ * Doing it the other way round makes every older document look like a
+ * malformed current one.
+ */
+export function readConfigDocument(
+	input: unknown,
+	migrations?: readonly ConfigMigration[],
+): ReaderConfigDocument {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) {
+		throw new ConfigNotAnObjectError(
+			"Not a reader configuration document: expected a JSON object.",
+		);
+	}
+
+	const envelope = ConfigEnvelopeSchema.safeParse(input);
+	if (!envelope.success) {
+		const kindIssue = envelope.error.issues.find(
+			(issue) => issue.path[0] === "kind",
+		);
+		if (kindIssue) {
+			throw new ConfigKindError(
+				CONFIG_KIND,
+				(input as ConfigDocumentShape).kind,
+			);
+		}
+		throw new ConfigMalformedError(envelope.error.issues);
+	}
+
+	if (envelope.data.schemaVersion > CURRENT_SCHEMA_VERSION) {
+		throw new ConfigVersionError(
+			envelope.data.schemaVersion,
+			CURRENT_SCHEMA_VERSION,
+		);
+	}
+
+	const lifted = liftToCurrentVersion(
+		input as ConfigDocumentShape,
+		envelope.data.schemaVersion,
+		migrations,
+	);
+
+	const parsed = ReaderConfigDocumentSchema.safeParse(lifted);
+	if (parsed.success) return parsed.data;
+
+	const unknown = unrecognizedKeys(parsed.error.issues);
+	for (const issue of unknown) {
+		const credentials = issue.keys.filter(isCredentialKey);
+		if (credentials.length > 0) {
+			throw new ConfigCredentialError(formatPath(issue.path), credentials);
+		}
+	}
+	const first = unknown[0];
+	if (first)
+		throw new ConfigUnknownKeysError(formatPath(first.path), first.keys);
+
+	throw new ConfigMalformedError(parsed.error.issues);
+}

package/src/schema-artifact.ts

@@ -0,0 +1,19 @@
+import { fileURLToPath } from "node:url";
+import { CONFIG_SCHEMA_ARTIFACT_PATH } from "./version.js";
+
+/**
+ * The reviewable copy of the JSON Schema. Committed inside the package so a
+ * change to the document shape shows up as a schema diff in the same review,
+ * which is the only thing the check can compare against — the build artifact
+ * below is regenerated from empty on every CI run and would agree with itself.
+ */
+export const committedSchemaPath = (): string =>
+	fileURLToPath(
+		new URL("../schema/reader-config.v1.schema.json", import.meta.url),
+	);
+
+/** The generated artifact, at its path under the repository root. */
+export const artifactSchemaPath = (): string =>
+	fileURLToPath(
+		new URL(`../../../${CONFIG_SCHEMA_ARTIFACT_PATH}`, import.meta.url),
+	);

package/src/version.ts

@@ -0,0 +1,18 @@
+/**
+ * A reader configuration document declares its own kind and version in two
+ * fields that never move between versions. Everything else in the document is
+ * free to change shape; these two are the contract that lets a reader decide
+ * what it is looking at before it knows how to read it.
+ */
+export const CONFIG_KIND = "reader.config";
+
+/** The document version this package writes and can read up to. */
+export const CURRENT_SCHEMA_VERSION = 1;
+
+/** `$id` of the emitted JSON Schema artifact. */
+export const CONFIG_SCHEMA_ID =
+	"https://schemas.remit.email/reader-config.v1.schema.json";
+
+/** Path of the emitted JSON Schema artifact, relative to the repository root. */
+export const CONFIG_SCHEMA_ARTIFACT_PATH =
+	"build/config-schema/reader-config.v1.schema.json";

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../../tsconfig.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src/**/*.ts"]
+}