@effected/markdown 0.2.0

package/Frontmatter.js

@@ -0,0 +1,272 @@
+import { MarkdownEdit } from "./MarkdownEdit.js";
+import { FrontmatterFormat } from "./MarkdownNode.js";
+import { Effect, Schema } from "effect";
+
+//#region src/Frontmatter.ts
+/**
+* Indicates that a frontmatter codec was handed a capture of a different
+* format — a yaml codec applied to a `+++` toml capture, for example.
+*
+* @remarks
+* The mismatch is detected before any parsing happens, so `cause`-free: the
+* node's `format` marker and the codec's declared `format` simply disagree.
+* Route on the `"FrontmatterFormatMismatchError"` tag with `Effect.catchTag`.
+*
+* @public
+*/
+var FrontmatterFormatMismatchError = class extends Schema.TaggedErrorClass()("FrontmatterFormatMismatchError", {
+	/** The format the codec decodes. */
+	expected: FrontmatterFormat,
+	/** The format the capture node actually carries. */
+	actual: FrontmatterFormat
+}) {
+	get message() {
+		return `frontmatter format mismatch: the ${this.expected} codec cannot decode a ${this.actual} capture`;
+	}
+};
+/**
+* Indicates that a frontmatter capture's content failed to parse in its
+* declared format.
+*
+* @remarks
+* The underlying format package's failure is preserved structurally in
+* `cause` — never stringified — so a consumer can reach the positioned
+* diagnostics the format engines carry. Route on the
+* `"FrontmatterDecodeError"` tag with `Effect.catchTag`.
+*
+* @public
+*/
+var FrontmatterDecodeError = class extends Schema.TaggedErrorClass()("FrontmatterDecodeError", {
+	/** The format that failed to parse. */
+	format: FrontmatterFormat,
+	/** The underlying format-package failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `frontmatter ${this.format} content failed to parse`;
+	}
+};
+/**
+* Indicates that frontmatter data failed to serialize in a codec's format.
+*
+* @remarks
+* The exact mirror of {@link FrontmatterDecodeError} on the write side: the
+* underlying format package's failure is preserved structurally in `cause` —
+* never stringified — so a consumer can reach the typed stringify error the
+* format engines carry (a `JsoncStringifyError`'s `code`, for example). Route
+* on the `"FrontmatterEncodeError"` tag with `Effect.catchTag`.
+*
+* @public
+*/
+var FrontmatterEncodeError = class extends Schema.TaggedErrorClass()("FrontmatterEncodeError", {
+	/** The format that failed to serialize. */
+	format: FrontmatterFormat,
+	/** The underlying format-package failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `frontmatter ${this.format} content failed to serialize`;
+	}
+};
+/**
+* Indicates that a document handed to a frontmatter decoder carries no
+* frontmatter capture.
+*
+* @remarks
+* Raised when the document genuinely has no frontmatter block — including
+* when it has one in the source but was parsed with the capture toggle off
+* (`MarkdownParseOptions.frontmatter` defaults to `false`). Cause-free: there
+* is nothing to diagnose beyond the absence itself. Consumers wanting
+* optional semantics can `Effect.catchTag("FrontmatterMissingError", ...)`
+* to a default.
+*
+* @public
+*/
+var FrontmatterMissingError = class extends Schema.TaggedErrorClass()("FrontmatterMissingError", {}) {
+	get message() {
+		return "the document has no frontmatter capture; was it parsed with `frontmatter: true`?";
+	}
+};
+/**
+* Indicates that decoded frontmatter data did not satisfy the consumer's
+* schema.
+*
+* @remarks
+* `issue` carries the **structured** schema failure — at runtime a
+* `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues` —
+* never a stringified rendering (the `ConfigValidationError` precedent from
+* `@effected/config-file`). It is typed `unknown` because v4 exposes no
+* `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
+*
+* @public
+*/
+var FrontmatterValidationError = class extends Schema.TaggedErrorClass()("FrontmatterValidationError", { 
+/** The structured schema issue. Never a string. */
+issue: Schema.Defect() }) {
+	get message() {
+		return "frontmatter data failed schema validation";
+	}
+};
+/**
+* The opening and closing fence lines for a frontmatter format — the closed
+* grammar the capture scanner recognizes: `---`…`---` yaml, `+++`…`+++` toml,
+* `---json`…`---` json.
+*/
+const FENCES = {
+	yaml: {
+		open: "---",
+		close: "---"
+	},
+	toml: {
+		open: "+++",
+		close: "+++"
+	},
+	json: {
+		open: "---json",
+		close: "---"
+	}
+};
+/**
+* Render a full frontmatter block — fences included, no trailing terminator
+* after the closing fence. The body's final line terminator is normalized:
+* the engines disagree (yaml and toml stringify emit a trailing newline,
+* jsonc does not), and an empty body (toml's encoding of `{}`) collapses to
+* adjacent fence lines.
+*/
+const renderBlock = (format, body) => {
+	const { open, close } = FENCES[format];
+	return `${open}\n${body === "" || body.endsWith("\n") ? body : `${body}\n`}${close}`;
+};
+/**
+* The frontmatter schema composition facade — typed gray-matter parity.
+*
+* @remarks
+* The design doc's indicative spelling was `Frontmatter.schema`, but
+* `Frontmatter` names the capture node class (the node classes co-locate in
+* `MarkdownNode.ts` and are named after their mdast types), so the facade
+* follows the package's Markdown-prefix convention instead.
+*
+* @public
+*/
+var MarkdownFrontmatter = class MarkdownFrontmatter {
+	/**
+	* Compose a consumer schema with a {@link FrontmatterCodec} into a typed
+	* decoder over a parsed `MarkdownDocument`.
+	*
+	* @remarks
+	* The decoder reads the document's frontmatter capture (parse with
+	* `frontmatter: true` — the toggle defaults off), decodes its raw value
+	* through the codec, then validates the data against `schema`. Each stage
+	* fails typed: no capture is {@link FrontmatterMissingError}, a
+	* wrong-format codec is {@link FrontmatterFormatMismatchError}, unparseable
+	* content is {@link FrontmatterDecodeError}, and schema-invalid data is
+	* {@link FrontmatterValidationError} carrying the structured issue.
+	*
+	* The seam takes the parsed document, not raw source: parse options
+	* (dialect, the frontmatter toggle) stay at the consumer's parse call and
+	* are never guessed here. Node-level composition remains available through
+	* `MarkdownDocument.frontmatter` plus the codec's own `decode`.
+	*
+	* Schema-producing in spirit: bind the returned decoder to a `const` when
+	* decoding many documents.
+	*
+	* @param schema - The schema the decoded frontmatter data must satisfy.
+	* @param codec - The format codec to decode the raw capture with.
+	* @returns A function from a parsed document to an `Effect` of the typed
+	*   frontmatter data.
+	*/
+	static schema(schema, codec) {
+		return (document) => {
+			const node = document.frontmatter;
+			return node === void 0 ? Effect.fail(new FrontmatterMissingError()) : codec.decode(node).pipe(Effect.flatMap((data) => Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new FrontmatterValidationError({ issue: error.issue }))))));
+		};
+	}
+	/**
+	* Compose a consumer schema with a {@link FrontmatterCodec} into a typed
+	* frontmatter **writer** over a parsed `MarkdownDocument` — the write
+	* mirror of {@link MarkdownFrontmatter.schema}.
+	*
+	* @remarks
+	* The writer schema-**encodes** the typed data, serializes it through the
+	* codec and returns the offset-splice edits that put the block in place —
+	* always exactly one:
+	*
+	* - A document **with** a frontmatter capture of the codec's format gets a
+	*   replacement of the entire block, both fence lines included; everything
+	*   outside the block survives byte-identical. A capture of a *different*
+	*   format fails with {@link FrontmatterFormatMismatchError} — the fences
+	*   are never switched.
+	* - A document with **no** capture gets one insert at offset 0: the fenced
+	*   block plus a blank line separating it from the existing content. Parse
+	*   with `frontmatter: true` (the toggle defaults off) — the same
+	*   precondition `schema` has — so absence means genuinely-no-frontmatter
+	*   and the insert cannot double a block the parse ignored.
+	*
+	* Each stage fails typed: schema-invalid data is
+	* {@link FrontmatterValidationError} carrying the structured issue, and a
+	* value the format cannot serialize is {@link FrontmatterEncodeError}
+	* carrying the format package's failure structurally.
+	*
+	* The block is re-serialized **whole** from the encoded data — gray-matter
+	* parity, not surgical editing — so anything the format's data model does
+	* not carry is not preserved: comments inside a yaml frontmatter block do
+	* **not** survive `set`. A per-key surgical mode over the format packages'
+	* edit layers is a documented future refinement, not current scope.
+	*
+	* Schema-producing in spirit: bind the returned writer to a `const` when
+	* writing many documents.
+	*
+	* @param schema - The schema the frontmatter data is encoded through.
+	* @param codec - The format codec to serialize the encoded data with.
+	* @returns A function from a parsed document and the typed data to an
+	*   `Effect` of the edits that install the block.
+	*/
+	static set(schema, codec) {
+		return (document, data) => {
+			const node = document.frontmatter;
+			if (node !== void 0 && node.format !== codec.format) return Effect.fail(new FrontmatterFormatMismatchError({
+				expected: codec.format,
+				actual: node.format
+			}));
+			return Schema.encodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new FrontmatterValidationError({ issue: error.issue }))), Effect.flatMap((encoded) => codec.encode(encoded)), Effect.map((body) => {
+				const block = renderBlock(codec.format, body);
+				if (node === void 0) {
+					const content = document.source.length === 0 ? `${block}\n` : `${block}\n\n`;
+					return [MarkdownEdit.make({
+						offset: 0,
+						length: 0,
+						content
+					})];
+				}
+				const offset = node.position.start.offset;
+				return [MarkdownEdit.make({
+					offset,
+					length: node.position.end.offset - offset,
+					content: block
+				})];
+			}));
+		};
+	}
+	/**
+	* Like {@link MarkdownFrontmatter.set}, but applies the edits to the
+	* document's source and returns the updated markdown text — the
+	* `modifyToString` parallel.
+	*
+	* @remarks
+	* Everything `set` documents holds verbatim: the whole-block
+	* re-serialization, the format-mismatch posture, the `frontmatter: true`
+	* precondition and the typed failures.
+	*
+	* @param schema - The schema the frontmatter data is encoded through.
+	* @param codec - The format codec to serialize the encoded data with.
+	* @returns A function from a parsed document and the typed data to an
+	*   `Effect` of the updated source text.
+	*/
+	static setToString(schema, codec) {
+		const write = MarkdownFrontmatter.set(schema, codec);
+		return (document, data) => write(document, data).pipe(Effect.map((edits) => MarkdownEdit.applyAll(document.source, edits)));
+	}
+};
+
+//#endregion
+export { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterValidationError, MarkdownFrontmatter };

package/FrontmatterResolver.js

@@ -0,0 +1,273 @@
+import { Effect, Result, Schema } from "effect";
+
+//#region src/FrontmatterResolver.ts
+/**
+* A `$schema` declaration referencing a schema by URL — any string containing
+* `://`.
+*
+* @remarks
+* Carried as data, never resolved in-package: the pure tier does no IO. An
+* external resolver implementing {@link FrontmatterSchemaResolver} may fetch
+* and interpret it.
+*
+* @public
+*/
+var SchemaDeclarationByUrl = class extends Schema.TaggedClass()("ByUrl", { 
+/** The URL as written in the declaration. */
+url: Schema.String }) {};
+/**
+* A `$schema` declaration referencing a schema by path — any string starting
+* `./`, `../` or `/` (a bundle- or file-relative reference).
+*
+* @remarks
+* Carried as data, never resolved in-package: the pure tier does no IO.
+*
+* @public
+*/
+var SchemaDeclarationByPath = class extends Schema.TaggedClass()("ByPath", { 
+/** The path as written in the declaration. */
+path: Schema.String }) {};
+/**
+* A `$schema` declaration carrying an inline JSON-Schema-like document — the
+* declaration value is itself a mapping.
+*
+* @remarks
+* Carried as data: the kit deliberately ships no JSON Schema engine
+* (`@effected/json-schema` is off the roadmap), so an inline document is
+* interpretable only through an external resolver plugged into the
+* {@link FrontmatterSchemaResolver} seam.
+*
+* @public
+*/
+var SchemaDeclarationInline = class extends Schema.TaggedClass()("Inline", { 
+/** The inline schema document, exactly as decoded from the frontmatter. */
+document: Schema.Unknown }) {};
+/**
+* A `$schema` declaration referencing a registered schema by name — any other
+* string, with the committed `name[@version]` grammar.
+*
+* @remarks
+* The string splits at the **last** `@`, so a leading npm-style scope
+* survives: `@savvy/skill@2.1.0` is name `@savvy/skill`, version `2.1.0`.
+* The version grammar is `X[.Y[.Z]]` — one to three dot-separated
+* non-negative integers; no prerelease, no build metadata, no npm range
+* operators. The recorded cost: `@` in a name is reserved forever as the
+* version separator, except the leading scope `@`.
+*
+* @public
+*/
+var SchemaDeclarationByName = class extends Schema.TaggedClass()("ByName", {
+	/** The name as written, scope included. */
+	name: Schema.String,
+	/** The version as written, when the declaration carries one. */
+	version: Schema.optionalKey(Schema.String)
+}) {};
+/**
+* The classified `$schema` declaration union — the full grammar contract for
+* how a frontmatter block may self-describe its schema.
+*
+* @public
+*/
+const SchemaDeclaration = Schema.Union([
+	SchemaDeclarationByUrl,
+	SchemaDeclarationByPath,
+	SchemaDeclarationInline,
+	SchemaDeclarationByName
+]);
+/**
+* Indicates that a `$schema` value does not classify: not a string or a
+* mapping, an empty string, or a name whose version segment falls outside the
+* committed `X[.Y[.Z]]` grammar.
+*
+* @public
+*/
+var SchemaDeclarationInvalidError = class extends Schema.TaggedErrorClass()("SchemaDeclarationInvalidError", {
+	/** Why the value failed to classify. */
+	reason: Schema.String,
+	/** The offending value, preserved structurally. */
+	value: Schema.Defect()
+}) {
+	get message() {
+		return `invalid $schema declaration: ${this.reason}`;
+	}
+};
+/**
+* Indicates that frontmatter data carries no `$schema` declaration where one
+* is required — the `requireDeclaration` strictness knob, or a registry
+* resolver that has nothing to dispatch on.
+*
+* @public
+*/
+var SchemaDeclarationMissingError = class extends Schema.TaggedErrorClass()("SchemaDeclarationMissingError", {}) {
+	get message() {
+		return "the frontmatter data carries no $schema declaration";
+	}
+};
+/**
+* Indicates that a declaration named a schema the resolver does not know —
+* an unregistered name, or a URL/path/inline declaration handed to the
+* name-keyed registry resolver.
+*
+* @public
+*/
+var SchemaNameUnknownError = class extends Schema.TaggedErrorClass()("SchemaNameUnknownError", { 
+/** The declaration that failed to resolve, when one exists. */
+declaration: Schema.optionalKey(SchemaDeclaration) }) {
+	get message() {
+		return "the $schema declaration names no registered schema";
+	}
+};
+/**
+* Indicates that a declaration's name is registered but its version segments
+* match no registration exactly — distinct from {@link SchemaNameUnknownError}
+* by design, so a legal-but-unsatisfied partial version (`skill@2` against a
+* `skill@2.1.0` registration) is diagnosable as a version problem, not an
+* unknown schema.
+*
+* @public
+*/
+var SchemaVersionUnresolvableError = class extends Schema.TaggedErrorClass()("SchemaVersionUnresolvableError", {
+	/** The registered name whose version could not be satisfied. */
+	name: Schema.String,
+	/** The requested version, when the declaration carried one. */
+	version: Schema.optionalKey(Schema.String)
+}) {
+	get message() {
+		return this.version === void 0 ? `schema "${this.name}" is registered only with versions; the declaration carries none` : `schema "${this.name}" has no registration matching version "${this.version}" exactly`;
+	}
+};
+const parseVersionSegments = (version) => {
+	if (!/^\d+(\.\d+){0,2}$/.test(version)) return;
+	return version.split(".").map((segment) => Number.parseInt(segment, 10));
+};
+const isMapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The `$schema` declaration classifier and the package's one built-in
+* resolver implementation.
+*
+* @public
+*/
+var SchemaResolver = class SchemaResolver {
+	/**
+	* Classify a raw `$schema` value into the declaration union.
+	*
+	* @remarks
+	* Total over its legal domain and typed on junk: a string containing
+	* `://` is {@link SchemaDeclarationByUrl}; a string starting `./`, `../`
+	* or `/` is {@link SchemaDeclarationByPath}; a mapping is
+	* {@link SchemaDeclarationInline}; any other non-empty string is
+	* {@link SchemaDeclarationByName} under the `name[@version]` grammar.
+	* Everything else — and a name whose version falls outside `X[.Y[.Z]]` —
+	* fails with {@link SchemaDeclarationInvalidError}.
+	*
+	* @param value - The raw `$schema` value from decoded frontmatter data.
+	* @returns The classified declaration, or the typed classification error.
+	*/
+	static classify(value) {
+		if (typeof value === "string") {
+			if (value.length === 0) return Result.fail(new SchemaDeclarationInvalidError({
+				reason: "the declaration is empty",
+				value
+			}));
+			if (value.includes("://")) return Result.succeed(new SchemaDeclarationByUrl({ url: value }));
+			if (value.startsWith("./") || value.startsWith("../") || value.startsWith("/")) return Result.succeed(new SchemaDeclarationByPath({ path: value }));
+			const separator = value.lastIndexOf("@");
+			if (separator <= 0) return Result.succeed(new SchemaDeclarationByName({ name: value }));
+			const name = value.slice(0, separator);
+			const version = value.slice(separator + 1);
+			if (parseVersionSegments(version) === void 0) return Result.fail(new SchemaDeclarationInvalidError({
+				reason: `version "${version}" is outside the X[.Y[.Z]] integer grammar`,
+				value
+			}));
+			return Result.succeed(new SchemaDeclarationByName({
+				name,
+				version
+			}));
+		}
+		if (isMapping(value)) return Result.succeed(new SchemaDeclarationInline({ document: value }));
+		return Result.fail(new SchemaDeclarationInvalidError({
+			reason: "the declaration is neither a string nor a mapping",
+			value
+		}));
+	}
+	/**
+	* Extract and classify the `$schema` declaration from decoded frontmatter
+	* data.
+	*
+	* @remarks
+	* Non-mapping data and a mapping without a `$schema` key both carry no
+	* declaration: the result succeeds with `undefined` by default, or fails
+	* with {@link SchemaDeclarationMissingError} under `requireDeclaration` —
+	* the design's strictness knob, applied at extraction where the
+	* present-or-absent branch actually lives.
+	*
+	* @param data - The decoded frontmatter data.
+	* @param options - `requireDeclaration` makes a missing `$schema` a typed
+	*   error.
+	* @returns The classified declaration, `undefined` when absent and
+	*   tolerated, or the typed error.
+	*/
+	static declarationOf(data, options) {
+		if (!isMapping(data) || !Object.hasOwn(data, "$schema")) return options?.requireDeclaration === true ? Result.fail(new SchemaDeclarationMissingError()) : Result.succeed(void 0);
+		return SchemaResolver.classify(data.$schema);
+	}
+	/**
+	* The package's one built-in resolver: a name-keyed registry with day-one
+	* exact version-segment resolution.
+	*
+	* @remarks
+	* Registration keys use the same `name[@version]` grammar as declarations
+	* — carrying a concrete version or none — and are validated eagerly: a key
+	* outside the grammar, or two keys whose version segments collide
+	* numerically, throws at construction (programmer error, not input).
+	*
+	* Resolution is exact: a declaration resolves only against an identically
+	* written registration (version segments compared numerically), a
+	* versionless declaration only against a versionless registration, and a
+	* legal-but-unsatisfied version fails with the dedicated
+	* {@link SchemaVersionUnresolvableError}, distinct from
+	* {@link SchemaNameUnknownError}. URL, path and inline declarations are
+	* never resolvable here — those belong to external resolvers plugged into
+	* the same seam. A registry cannot dispatch without a declaration, so an
+	* absent one fails with {@link SchemaDeclarationMissingError}.
+	*
+	* @param registrations - Schemas keyed by `name[@version]`.
+	* @returns The registry-backed resolver.
+	*/
+	static fromRegistry(registrations) {
+		const byName = /* @__PURE__ */ new Map();
+		for (const [key, schema] of Object.entries(registrations)) {
+			const classified = SchemaResolver.classify(key);
+			if (Result.isFailure(classified) || !(classified.success instanceof SchemaDeclarationByName)) throw new Error(`SchemaResolver.fromRegistry: registration key "${key}" is outside the name[@version] grammar`);
+			const declaration = classified.success;
+			const entry = byName.get(declaration.name) ?? { versions: /* @__PURE__ */ new Map() };
+			if (declaration.version === void 0) {
+				if (entry.versionless !== void 0) throw new Error(`SchemaResolver.fromRegistry: duplicate versionless registration for "${declaration.name}"`);
+				entry.versionless = schema;
+			} else {
+				const segments = parseVersionSegments(declaration.version);
+				if (segments === void 0) throw new Error(`SchemaResolver.fromRegistry: registration key "${key}" carries an illegal version`);
+				const canonical = segments.join(".");
+				if (entry.versions.has(canonical)) throw new Error(`SchemaResolver.fromRegistry: registrations for "${declaration.name}" collide on version ${canonical}`);
+				entry.versions.set(canonical, schema);
+			}
+			byName.set(declaration.name, entry);
+		}
+		return { resolve: (declaration, _data) => {
+			if (declaration === void 0) return Effect.fail(new SchemaDeclarationMissingError());
+			if (!(declaration instanceof SchemaDeclarationByName)) return Effect.fail(new SchemaNameUnknownError({ declaration }));
+			const entry = byName.get(declaration.name);
+			if (entry === void 0) return Effect.fail(new SchemaNameUnknownError({ declaration }));
+			if (declaration.version === void 0) return entry.versionless === void 0 ? Effect.fail(new SchemaVersionUnresolvableError({ name: declaration.name })) : Effect.succeed(entry.versionless);
+			const segments = parseVersionSegments(declaration.version);
+			const match = segments === void 0 ? void 0 : entry.versions.get(segments.join("."));
+			return match === void 0 ? Effect.fail(new SchemaVersionUnresolvableError({
+				name: declaration.name,
+				version: declaration.version
+			})) : Effect.succeed(match);
+		} };
+	}
+};
+
+//#endregion
+export { SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError };

package/JsonFrontmatter.js

@@ -0,0 +1,46 @@
+import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError } from "./Frontmatter.js";
+import { Effect } from "effect";
+import { Jsonc } from "@effected/jsonc";
+
+//#region src/JsonFrontmatter.ts
+/**
+* The json frontmatter codec, over `@effected/jsonc`.
+*
+* @remarks
+* Decodes a `---json`-fenced capture's raw value with `Jsonc.parse`, so the
+* jsonc engine's nesting depth cap fails through the typed channel: a hostile
+* frontmatter block surfaces as a {@link FrontmatterDecodeError} carrying the
+* `JsoncParseError` structurally, never a defect. JSONC being a JSON
+* superset, comments and trailing commas in a json capture decode rather than
+* fail — deliberate leniency, matching the kit's one JSON-family engine. An
+* empty capture fails typed: unlike yaml and toml, JSON has no
+* empty-document value.
+*
+* Encodes with `Jsonc.stringify` — plain 2-space JSON emission, never
+* comments; a circular reference, a `bigint` or a top-level unrepresentable
+* value fails as a {@link FrontmatterEncodeError} carrying the
+* `JsoncStringifyError` structurally. An empty object encodes to `{}`.
+*
+* `@effected/jsonc` is an optional peer — importing this module is what
+* requires it; a consumer who never touches json frontmatter never loads the
+* jsonc engine.
+*
+* @public
+*/
+const JsonFrontmatter = {
+	format: "json",
+	decode: (node) => node.format !== "json" ? Effect.fail(new FrontmatterFormatMismatchError({
+		expected: "json",
+		actual: node.format
+	})) : Jsonc.parse(node.value).pipe(Effect.mapError((cause) => new FrontmatterDecodeError({
+		format: "json",
+		cause
+	}))),
+	encode: (data) => Jsonc.stringify(data).pipe(Effect.mapError((cause) => new FrontmatterEncodeError({
+		format: "json",
+		cause
+	})))
+};
+
+//#endregion
+export { JsonFrontmatter };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.