chore: import upstream snapshot with attribution

packages/plugin-cli/src/manifest/load.ts

@@ -0,0 +1,481 @@
+/**
+ * Read and validate an `emdash-plugin.jsonc` manifest from disk.
+ *
+ * Failure modes, each with a distinct error code for scriptable consumers
+ * (`validate --json`, programmatic API users):
+ *
+ *   - `MANIFEST_NOT_FOUND` — file doesn't exist at the resolved path.
+ *   - `MANIFEST_TOO_LARGE` — file exceeds `MANIFEST_MAX_BYTES`. Reading
+ *     stops at the cap; the file is never fully buffered.
+ *   - `MANIFEST_PARSE_ERROR` — JSONC parse failure (trailing comma, missing
+ *     bracket, control char in string, duplicate keys). Includes line +
+ *     column from `jsonc-parser`'s offset.
+ *   - `MANIFEST_VALIDATION_ERROR` — JSONC parsed cleanly but the value
+ *     failed the Zod schema. Includes the field path and the offending
+ *     value's location in the source where possible.
+ *
+ * The line/column mapping is critical for editor-side workflows: a user
+ * running `emdash-plugin validate` from a CI step wants the same kind of
+ * pointer they'd get from `tsc` or `eslint`, not a Zod issue tree.
+ */
+
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { parseTree, type Node, type ParseError, printParseErrorCode } from "jsonc-parser";
+import type { ZodIssue } from "zod";
+
+import { ManifestSchema, type Manifest } from "./schema.js";
+
+/**
+ * Conventional manifest filename. Lives next to the plugin's `package.json`.
+ */
+export const MANIFEST_FILENAME = "emdash-plugin.jsonc";
+
+/**
+ * Hard cap on the bytes we'll buffer for a manifest. The largest real-world
+ * v1 manifest under the current schema is a few hundred bytes; even a heavily-
+ * populated future version with all the long-form sections from issue #1030
+ * (5 sections × 20 KB cap each from the lexicon) tops out under 128 KB. We
+ * pick 1 MiB so accidental mis-targets (`--manifest ./large.tar`) fail fast
+ * with a clear error rather than OOMing the CLI.
+ */
+export const MANIFEST_MAX_BYTES = 1024 * 1024;
+
+export type ManifestErrorCode =
+	| "MANIFEST_NOT_FOUND"
+	| "MANIFEST_TOO_LARGE"
+	| "MANIFEST_PARSE_ERROR"
+	| "MANIFEST_VALIDATION_ERROR";
+
+export class ManifestError extends Error {
+	override readonly name = "ManifestError";
+	readonly code: ManifestErrorCode;
+	/** Resolved absolute path of the manifest file. */
+	readonly path: string;
+	/**
+	 * Issues for `MANIFEST_VALIDATION_ERROR`. One per failed rule, each
+	 * carrying a JSON pointer-style path and an optional source location.
+	 * Empty for the other error codes.
+	 */
+	readonly issues: ManifestIssue[];
+
+	constructor(
+		code: ManifestErrorCode,
+		message: string,
+		path: string,
+		issues: ManifestIssue[] = [],
+	) {
+		super(message);
+		this.code = code;
+		this.path = path;
+		this.issues = issues;
+	}
+}
+
+export interface ManifestIssue {
+	/** Dotted/bracketed JSON path, e.g. `authors[0].email`. */
+	path: string;
+	message: string;
+	/** 1-indexed line and column in the manifest source, when known. */
+	location?: { line: number; column: number };
+}
+
+export interface LoadManifestResult {
+	manifest: Manifest;
+	/** Resolved absolute path. */
+	path: string;
+}
+
+/**
+ * Load and validate a manifest at `path`. `path` may be a directory (in
+ * which case `emdash-plugin.jsonc` is appended) or a file.
+ *
+ * Throws `ManifestError` on every failure path. Successful return guarantees
+ * the manifest is schema-valid (but normalisation to the publish-input
+ * shape still needs `./translate.ts`).
+ */
+export async function loadManifest(path: string): Promise<LoadManifestResult> {
+	const resolved = resolve(path);
+	// Heuristic: paths that end in `.jsonc` or `.json` are treated as
+	// files; everything else is treated as a directory. We don't `stat`
+	// to disambiguate because the error path "missing file" should be the
+	// same regardless of which form the caller passed.
+	const filePath =
+		resolved.endsWith(".jsonc") || resolved.endsWith(".json")
+			? resolved
+			: resolve(resolved, MANIFEST_FILENAME);
+
+	// Bounded read: open the file and read at most MANIFEST_MAX_BYTES+1
+	// bytes. The extra byte is a sentinel — if we get it, the file is
+	// definitely over the cap regardless of what `stat` would say.
+	// This closes the stat-then-readFile race where a concurrent writer
+	// could grow the file between size check and buffer.
+	const source = await readBoundedUtf8(filePath);
+	return parseAndValidate(source, filePath);
+}
+
+/**
+ * Read a UTF-8 file with a hard cap of `MANIFEST_MAX_BYTES` bytes.
+ * Throws `ManifestError(MANIFEST_TOO_LARGE)` if the file exceeds the cap,
+ * `ManifestError(MANIFEST_NOT_FOUND)` for ENOENT.
+ *
+ * We allocate a buffer of `MANIFEST_MAX_BYTES + 1` and read into it; if
+ * the read fills the whole buffer, the file is at least one byte over
+ * the limit and we reject. This avoids the TOCTOU window of a separate
+ * `stat` call: a concurrent writer can grow the file between syscalls,
+ * but it can never make our buffer larger than what we allocated up
+ * front.
+ *
+ * `read` returns a single chunk synchronously from kernel buffers when
+ * available; for files of our cap size (1 MiB) this is one syscall on
+ * Linux/macOS. We loop in case the kernel returns a short read.
+ */
+async function readBoundedUtf8(filePath: string): Promise<string> {
+	let handle: Awaited<ReturnType<typeof open>>;
+	try {
+		handle = await open(filePath, "r");
+	} catch (error) {
+		if (isNodeNotFoundError(error)) {
+			throw new ManifestError(
+				"MANIFEST_NOT_FOUND",
+				`No manifest at ${filePath}. Create one with: emdash-plugin init`,
+				filePath,
+			);
+		}
+		throw error;
+	}
+	try {
+		// One extra byte so we can detect oversize without reading
+		// arbitrarily much.
+		const buffer = Buffer.allocUnsafe(MANIFEST_MAX_BYTES + 1);
+		let totalRead = 0;
+		while (totalRead < buffer.length) {
+			const { bytesRead } = await handle.read(
+				buffer,
+				totalRead,
+				buffer.length - totalRead,
+				totalRead,
+			);
+			if (bytesRead === 0) break;
+			totalRead += bytesRead;
+		}
+		if (totalRead > MANIFEST_MAX_BYTES) {
+			throw new ManifestError(
+				"MANIFEST_TOO_LARGE",
+				`Manifest at ${filePath} is larger than the ${MANIFEST_MAX_BYTES}-byte cap. Check that you pointed --manifest at the right file.`,
+				filePath,
+			);
+		}
+		return buffer.subarray(0, totalRead).toString("utf8");
+	} finally {
+		await handle.close().catch(() => {
+			// Closing a handle should never fail in practice; if it
+			// does, swallow it — the read result is already in hand.
+		});
+	}
+}
+
+/**
+ * Variant for callers that already have the source text in hand (tests,
+ * editor integrations that read the buffer). The `path` argument is used
+ * for error messages only.
+ */
+export function parseAndValidateManifest(source: string, path: string): LoadManifestResult {
+	return parseAndValidate(source, path);
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Internals
+// ──────────────────────────────────────────────────────────────────────────
+
+function parseAndValidate(source: string, filePath: string): LoadManifestResult {
+	const parseErrors: ParseError[] = [];
+	// `parseTree` gives us both the parsed value AND the syntax tree, so we
+	// can map a Zod issue's path back to a source offset. `parse` alone
+	// loses that information.
+	const root = parseTree(source, parseErrors, {
+		// Comments are part of the JSONC contract. Trailing commas are
+		// allowed because they reduce diff noise when the user adds a new
+		// field at the end.
+		disallowComments: false,
+		allowTrailingComma: true,
+		allowEmptyContent: false,
+	});
+
+	if (parseErrors.length > 0) {
+		const first = parseErrors[0]!;
+		const { line, column } = offsetToLineCol(source, first.offset);
+		throw new ManifestError(
+			"MANIFEST_PARSE_ERROR",
+			`${filePath}:${line}:${column}: ${printParseErrorCode(first.error)}`,
+			filePath,
+		);
+	}
+
+	if (!root) {
+		// Shouldn't be reachable when `allowEmptyContent: false` is set and
+		// `parseErrors` is empty, but `parseTree`'s return type is nullable.
+		throw new ManifestError("MANIFEST_PARSE_ERROR", `${filePath}: file is empty`, filePath);
+	}
+
+	// Reject duplicate keys before validation. `nodeToValue` is last-wins
+	// (matches JSON.parse semantics) which silently shadows earlier keys
+	// — review-hostile for a security-sensitive document like this. We
+	// scan once for duplicates and surface them as a parse error with a
+	// source location, so a `git diff` reviewer can't be fooled by a
+	// "publisher": "<honest>" at the top of the file that gets overridden
+	// by "publisher": "<hostile>" further down.
+	const duplicate = findDuplicateKey(root);
+	if (duplicate) {
+		const { line, column } = offsetToLineCol(source, duplicate.offset);
+		throw new ManifestError(
+			"MANIFEST_PARSE_ERROR",
+			`${filePath}:${line}:${column}: duplicate key "${duplicate.key}". Each property may only be declared once.`,
+			filePath,
+		);
+	}
+
+	const value = nodeToValue(root);
+
+	const result = ManifestSchema.safeParse(value);
+	if (!result.success) {
+		const issues = result.error.issues.map((issue) => zodIssueToManifestIssue(issue, source, root));
+		const summary = issues
+			.map((i) => {
+				const loc = i.location ? `:${i.location.line}:${i.location.column}` : "";
+				return `${filePath}${loc}: ${i.path ? `${i.path}: ` : ""}${i.message}`;
+			})
+			.join("\n");
+		throw new ManifestError(
+			"MANIFEST_VALIDATION_ERROR",
+			`Manifest validation failed:\n${summary}`,
+			filePath,
+			issues,
+		);
+	}
+
+	return { manifest: result.data, path: filePath };
+}
+
+/**
+ * Map a Zod issue to a manifest issue. The path translation strips the
+ * leading `$` that some Zod versions prepend and produces the JSONC-style
+ * `authors[0].email` syntax users will recognise.
+ *
+ * Zod 4 types path segments as `PropertyKey` (string | number | symbol).
+ * Symbols cannot appear in a JSON-parsed value's path (JSON has no symbol
+ * keys), so we narrow defensively and treat any stray symbol as an
+ * opaque "<symbol>" string in the displayed path.
+ *
+ * Special-cases `unrecognized_keys` (typo'd field names): Zod reports the
+ * issue at the parent path with the offending key(s) in `issue.keys`.
+ * Without special handling, the line:col points at the parent object's
+ * opening brace, not the actual typo. We resolve the first listed key
+ * inside the parent and use ITS source offset, so a `"licens": "MIT"`
+ * mistake gets the pointer landing on the bad key's line and column.
+ */
+function zodIssueToManifestIssue(issue: ZodIssue, source: string, root: Node): ManifestIssue {
+	const path = narrowZodPath(issue.path);
+	const pathStr = formatZodPath(path);
+
+	let offset: number | undefined;
+	if (issue.code === "unrecognized_keys") {
+		const keys = (issue as ZodIssue & { keys?: readonly string[] }).keys;
+		const firstKey = keys?.[0];
+		if (firstKey !== undefined) {
+			const parent = findNodeAtPath(root, path);
+			if (parent?.type === "object" && parent.children) {
+				const prop: Node | undefined = parent.children.find(
+					(c) =>
+						c.type === "property" &&
+						c.children?.[0]?.type === "string" &&
+						c.children[0].value === firstKey,
+				);
+				const keyNode = prop?.children?.[0];
+				if (keyNode) offset = keyNode.offset;
+			}
+		}
+	}
+	if (offset === undefined) {
+		offset = findNodeAtPath(root, path)?.offset;
+	}
+
+	const location = offset !== undefined ? offsetToLineCol(source, offset) : undefined;
+	return location
+		? { path: pathStr, message: issue.message, location }
+		: { path: pathStr, message: issue.message };
+}
+
+/**
+ * Coerce a Zod 4 issue path (`PropertyKey[]`) to the string|number form
+ * the rest of the loader uses. A symbol segment is impossible for JSONC
+ * input, but we render it defensively rather than crashing.
+ */
+function narrowZodPath(path: ReadonlyArray<PropertyKey>): Array<string | number> {
+	return path.map((segment) => {
+		if (typeof segment === "string" || typeof segment === "number") return segment;
+		return segment.toString();
+	});
+}
+
+/**
+ * Format a Zod path array as `authors[0].email`. Numbers become bracketed
+ * indices; strings become dot-prefixed (except the first).
+ */
+function formatZodPath(path: ReadonlyArray<string | number>): string {
+	let out = "";
+	for (const segment of path) {
+		if (typeof segment === "number") {
+			out += `[${segment}]`;
+		} else {
+			out += out.length === 0 ? segment : `.${segment}`;
+		}
+	}
+	return out;
+}
+
+/**
+ * Walk the JSONC syntax tree to find the node at a given path. When the
+ * path traverses into a missing key or a wrong-shape value, returns the
+ * deepest ancestor that DID exist — so the resulting line:col still
+ * points at something useful (the parent object, where the missing
+ * property "should have been"). This matters most for two error
+ * classes:
+ *
+ *   - Missing required key: Zod's path is `[key]`, the value doesn't
+ *     exist; returning the root object's offset puts the pointer at the
+ *     opening brace, which an editor highlights as "issue with this
+ *     object".
+ *   - Unknown key (typo): Zod's path is `[wrongKey]`, the value doesn't
+ *     exist in the parent. Same parent-fallback gives the pointer the
+ *     line of the parent object.
+ *
+ * Both cases used to return undefined and lose the line:col entirely.
+ */
+function findNodeAtPath(root: Node, path: ReadonlyArray<string | number>): Node | undefined {
+	let current: Node | undefined = root;
+	let lastResolved: Node | undefined = root;
+	for (const segment of path) {
+		if (!current) return lastResolved;
+		if (typeof segment === "number") {
+			if (current.type !== "array" || !current.children) return current;
+			const next: Node | undefined = current.children[segment];
+			if (!next) return current;
+			current = next;
+		} else {
+			if (current.type !== "object" || !current.children) return current;
+			const prop: Node | undefined = current.children.find(
+				(c) =>
+					c.type === "property" &&
+					c.children?.[0]?.type === "string" &&
+					c.children[0].value === segment,
+			);
+			// `property` node's children are [keyNode, valueNode]. We want
+			// the value for further traversal. If the property is missing
+			// entirely (e.g. typo'd key, missing required field), fall
+			// back to the current object so the caller gets a source
+			// location for the containing structure.
+			const next: Node | undefined = prop?.children?.[1];
+			if (!next) return current;
+			current = next;
+		}
+		lastResolved = current;
+	}
+	return current;
+}
+
+/**
+ * Recursively scan an object node for duplicate property names. Returns
+ * the FIRST duplicate found (innermost-first within the recursion, but
+ * order across siblings is the order in the source) with its offset for
+ * line:column reporting.
+ *
+ * We scan the entire tree, not just the root: duplicate keys inside
+ * `author: { ... }` or `security: { ... }` are equally review-hostile.
+ */
+function findDuplicateKey(node: Node): { key: string; offset: number } | undefined {
+	if (node.type === "object" && node.children) {
+		const seen = new Set<string>();
+		for (const prop of node.children) {
+			if (prop.type !== "property") continue;
+			const keyNode = prop.children?.[0];
+			if (!keyNode || keyNode.type !== "string" || typeof keyNode.value !== "string") {
+				continue;
+			}
+			if (seen.has(keyNode.value)) {
+				return { key: keyNode.value, offset: keyNode.offset };
+			}
+			seen.add(keyNode.value);
+			const valueNode = prop.children?.[1];
+			if (valueNode) {
+				const nested = findDuplicateKey(valueNode);
+				if (nested) return nested;
+			}
+		}
+	} else if (node.type === "array" && node.children) {
+		for (const child of node.children) {
+			const nested = findDuplicateKey(child);
+			if (nested) return nested;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Convert a JSONC syntax-tree node to its plain JavaScript value. The
+ * `parseTree` API doesn't return values directly; this walks the tree.
+ *
+ * We can't use `jsonc-parser`'s `parse()` (which would give us the value
+ * directly) because we need the tree anyway for error-location mapping,
+ * and parsing twice doubles the work for a file we're about to validate.
+ */
+function nodeToValue(node: Node): unknown {
+	switch (node.type) {
+		case "object": {
+			const obj: Record<string, unknown> = {};
+			for (const prop of node.children ?? []) {
+				if (prop.type !== "property") continue;
+				const [keyNode, valueNode] = prop.children ?? [];
+				if (!keyNode || keyNode.type !== "string" || !valueNode) continue;
+				if (typeof keyNode.value !== "string") continue;
+				obj[keyNode.value] = nodeToValue(valueNode);
+			}
+			return obj;
+		}
+		case "array":
+			return (node.children ?? []).map((child) => nodeToValue(child));
+		case "string":
+		case "number":
+		case "boolean":
+		case "null":
+			return node.value;
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Convert a byte offset in `source` into 1-indexed line + column. Matches
+ * the convention `tsc` and `eslint` use for error pointers.
+ */
+function offsetToLineCol(source: string, offset: number): { line: number; column: number } {
+	let line = 1;
+	let column = 1;
+	const max = Math.min(offset, source.length);
+	for (let i = 0; i < max; i++) {
+		if (source.charCodeAt(i) === 10 /* \n */) {
+			line++;
+			column = 1;
+		} else {
+			column++;
+		}
+	}
+	return { line, column };
+}
+
+function isNodeNotFoundError(error: unknown): boolean {
+	return (
+		error instanceof Error && "code" in error && (error as { code: unknown }).code === "ENOENT"
+	);
+}