@effected/templates 0.1.0

package/CommentStyle.js

@@ -0,0 +1,104 @@
+import { Schema } from "effect";
+
+//#region src/CommentStyle.ts
+/**
+* A comment delimiter: non-empty, and free of control characters.
+*
+* @remarks
+* Every constraint is load-bearing rather than decorative. An empty delimiter
+* would make the marker scanner match every line in a document. A delimiter
+* containing a line break would let a caller inject arbitrary lines into a
+* rendered marker. And a delimiter containing NUL would collide in
+* {@link CommentStyle.id}, where NUL is the field separator — `{ prefix: "a\0b" }`
+* and `{ prefix: "a", suffix: "b" }` would key the same lookup entry. All of
+* them fail at construction.
+*
+* The pattern is a negated character class with a single quantifier, so it
+* cannot backtrack on hostile input.
+*/
+const Delimiter = Schema.String.check(Schema.isPattern(/^\P{Cc}+$/u));
+/**
+* How a managed section's markers are commented out in a given file format.
+*
+* @remarks
+* A **line** style carries only a `prefix` (`#`, `//`); a **wrapped** style
+* carries a `suffix` as well (`<!--` … `-->`). The wrapped form is what makes
+* managed sections representable in Markdown, HTML and XML, which the two-way
+* literal union this replaces could not express.
+*
+* The preset set is a convenience, not a closed world: a format nobody
+* anticipated is one `CommentStyle.make({ prefix: "%" })` away.
+*
+* @example
+* ```ts
+* import { CommentStyle } from "@effected/templates";
+*
+* CommentStyle.hash;                                  // # …
+* CommentStyle.html;                                  // <!-- … -->
+* CommentStyle.make({ prefix: "(*", suffix: "*)" });  // ML, no preset needed
+* ```
+*
+* @public
+*/
+var CommentStyle = class CommentStyle extends Schema.Class("CommentStyle")({
+	/** Opens the comment. Non-empty, single-line. */
+	prefix: Delimiter,
+	/** Closes the comment, for wrapped styles. Omitted for line styles. */
+	suffix: Schema.optionalKey(Delimiter)
+}) {
+	/** Shell, YAML, TOML, Python, Dockerfile, `.env`. */
+	static hash = CommentStyle.make({ prefix: "#" });
+	/** JavaScript, TypeScript, C, Go, Rust, JSONC. */
+	static slash = CommentStyle.make({ prefix: "//" });
+	/** INI, Lisp, assembly. */
+	static semicolon = CommentStyle.make({ prefix: ";" });
+	/** SQL, Lua, Haskell. */
+	static dash = CommentStyle.make({ prefix: "--" });
+	/** Markdown, HTML, XML — the wrapped style v3 could not represent. */
+	static html = CommentStyle.make({
+		prefix: "<!--",
+		suffix: "-->"
+	});
+	/** CSS, and the block form of every C-family language. */
+	static block = CommentStyle.make({
+		prefix: "/*",
+		suffix: "*/"
+	});
+	/**
+	* Every preset, in the order a reader would expect: line styles first,
+	* then wrapped.
+	*
+	* @remarks
+	* A grouped static over variants of one concept that live in one module
+	* and reach nothing heavier than each other — nothing sits behind a preset
+	* but a two-field object, so this is not the namespace-object hazard.
+	*/
+	static presets = [
+		CommentStyle.hash,
+		CommentStyle.slash,
+		CommentStyle.semicolon,
+		CommentStyle.dash,
+		CommentStyle.html,
+		CommentStyle.block
+	];
+	/**
+	* A stable string identity, for keying a plain `Map`.
+	*
+	* @remarks
+	* The `NUL` separator is not cosmetic: without it `{ prefix: "ab" }`
+	* and `{ prefix: "a", suffix: "b" }` would produce the same id and two
+	* genuinely different styles would collide in a lookup table. `NUL`
+	* cannot occur in a delimiter, which the single-line check guarantees is
+	* printable-ish, so the encoding is unambiguous.
+	*/
+	get id() {
+		return `${this.prefix}\u0000${this.suffix ?? ""}`;
+	}
+	/** True when the style wraps its content, i.e. it carries a suffix. */
+	get isWrapped() {
+		return this.suffix !== void 0;
+	}
+};
+
+//#endregion
+export { CommentStyle };

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.

package/ManagedSection.js

@@ -0,0 +1,211 @@
+import { SectionDialect } from "./SectionDialect.js";
+import { SectionDocument, SectionParseError } from "./SectionDocument.js";
+import { Context, Effect, FileSystem, Layer, Schema } from "effect";
+
+//#region src/ManagedSection.ts
+/**
+* Raised when the file behind a managed-section operation could not be read or
+* written.
+*
+* @remarks
+* The underlying `PlatformError` is preserved structurally in `cause` rather
+* than stringified. `operation` is what a bare platform error cannot tell a
+* caller: these operations are read-modify-write, so "it failed" is ambiguous
+* about whether the document was even seen.
+*
+* A **missing** file is not an error — it reads as a document with no
+* sections, and a sync creates it.
+*
+* @public
+*/
+var SectionFileError = class extends Schema.TaggedErrorClass()("SectionFileError", {
+	/** The file the operation was against. */
+	path: Schema.String,
+	/** Which half of the read-modify-write failed. */
+	operation: Schema.Literals(["read", "write"]),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Failed to ${this.operation} managed sections in "${this.path}"`;
+	}
+};
+const notFound = (error) => error.reason._tag === "NotFound";
+/**
+* Decodes file bytes **without** consuming a byte-order mark.
+*
+* @remarks
+* `FileSystem.readFileString` decodes through a default `TextDecoder`, which
+* strips a leading BOM — verified against `@effect/platform-node@4.0.0-beta.101`.
+* Reading through it would make the first sync of a BOM-carrying file silently
+* delete the BOM, which violates this package's central promise that every byte
+* outside a managed span survives. Reading bytes and decoding with
+* `ignoreBOM: true` keeps the mark in the leading text span, where it is
+* preserved like any other content.
+*/
+const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+const make = (options = {}) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const dialect = options.dialect ?? SectionDialect.default;
+	/**
+	* Read and parse, degrading a missing file to an empty document.
+	*
+	* One read, not an `exists` probe followed by a read: two syscalls with a
+	* race between them, where the file can appear or vanish in the gap.
+	*/
+	const load = (path) => fs.readFile(path).pipe(Effect.map((bytes) => decoder.decode(bytes)), Effect.catchTag("PlatformError", (error) => notFound(error) ? Effect.succeed("") : Effect.fail(new SectionFileError({
+		path,
+		operation: "read",
+		cause: error
+	}))), Effect.flatMap((text) => Effect.fromResult(SectionDocument.parseResult(text, dialect)).pipe(Effect.mapError((error) => SectionParseError.at(path, error)))));
+	const store = (path, text) => fs.writeFileString(path, text).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new SectionFileError({
+		path,
+		operation: "write",
+		cause: error
+	}))));
+	const syncAll = Effect.fn("ManagedSection.syncAll")(function* (path, sections) {
+		yield* Effect.annotateCurrentSpan({
+			path,
+			sections: sections.length
+		});
+		const document = yield* load(path);
+		const reconciled = yield* Effect.fromResult(document.reconcile(sections));
+		if (reconciled.changed) yield* store(path, reconciled.text);
+		return reconciled.outcomes;
+	});
+	return {
+		read: Effect.fn("ManagedSection.read")(function* (path, id) {
+			yield* Effect.annotateCurrentSpan({
+				path,
+				key: id.key
+			});
+			return (yield* load(path)).read(id);
+		}),
+		readAll: Effect.fn("ManagedSection.readAll")(function* (path) {
+			yield* Effect.annotateCurrentSpan({ path });
+			return (yield* load(path)).sections.map((placed) => placed.section);
+		}),
+		isManaged: Effect.fn("ManagedSection.isManaged")(function* (path, id) {
+			yield* Effect.annotateCurrentSpan({
+				path,
+				key: id.key
+			});
+			return (yield* load(path)).has(id);
+		}),
+		sync: Effect.fn("ManagedSection.sync")(function* (path, section) {
+			yield* Effect.annotateCurrentSpan({
+				path,
+				key: section.key
+			});
+			return (yield* syncAll(path, [section]))[0];
+		}),
+		syncAll,
+		check: Effect.fn("ManagedSection.check")(function* (path, section) {
+			yield* Effect.annotateCurrentSpan({
+				path,
+				key: section.key
+			});
+			return (yield* load(path)).check(section);
+		}),
+		checkAll: Effect.fn("ManagedSection.checkAll")(function* (path, sections) {
+			yield* Effect.annotateCurrentSpan({
+				path,
+				sections: sections.length
+			});
+			const document = yield* load(path);
+			return sections.map((section) => document.check(section));
+		}),
+		remove: Effect.fn("ManagedSection.remove")(function* (path, id) {
+			yield* Effect.annotateCurrentSpan({
+				path,
+				key: id.key
+			});
+			const next = (yield* load(path)).remove(id);
+			if (next._tag === "None") return false;
+			yield* store(path, next.value);
+			return true;
+		})
+	};
+});
+const unimplemented = (member) => {
+	throw new Error(`ManagedSection.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+/**
+* Managed sections in files: read, compare, sync and remove delimited blocks
+* whose surrounding content belongs to the user.
+*
+* @remarks
+* A thin shell over {@link SectionDocument}: every member reads the file, runs
+* the pure core, and writes back only when the text actually changed. All the
+* interesting behavior — and all the interesting tests — live in the pure core.
+*
+* `FileSystem` is required in `R` and discharged by the consumer's platform
+* layer at the edge. No `Path` is required: paths are handed to `FileSystem`
+* untouched.
+*
+* @example
+* ```ts
+* import { CommentStyle, ManagedSection, SectionId } from "@effected/templates";
+* import { Effect } from "effect";
+*
+* const Base = SectionId.make({ key: "base", commentStyle: CommentStyle.hash });
+* const Tool = SectionId.make({ key: "tool", commentStyle: CommentStyle.hash });
+*
+* const program = Effect.gen(function* () {
+*   const sections = yield* ManagedSection;
+*   // Declared order is written into the file, so `base` precedes `tool`.
+*   return yield* sections.syncAll(".husky/pre-commit", [
+*     Base.section("preamble"),
+*     Tool.section("run-the-tool"),
+*   ]);
+* });
+* ```
+*
+* @public
+*/
+var ManagedSection = class ManagedSection extends Context.Service()("@effected/templates/ManagedSection") {
+	/**
+	* The default layer, reading and writing {@link SectionDialect.default}
+	* markers.
+	*
+	* @remarks
+	* A bound `const`, not a function, so it memoizes by reference.
+	*/
+	static layer = Layer.effect(this, make());
+	/**
+	* A layer with a custom marker dialect.
+	*
+	* @remarks
+	* A parameterized layer factory mints a **fresh reference per call**, and
+	* layers memoize by reference — bind the result to a `const` and reuse it
+	* rather than calling `layerWith(...)` at each composition site.
+	*/
+	static layerWith = (options) => Layer.effect(ManagedSection, make(options));
+	/**
+	* A test double. Members a suite does not stub **die when called**, rather
+	* than returning a plausible-looking answer that makes a wrong test pass.
+	*/
+	static makeTest = (overrides = {}) => ({
+		read: () => Effect.sync(() => unimplemented("read")),
+		readAll: () => Effect.sync(() => unimplemented("readAll")),
+		isManaged: () => Effect.sync(() => unimplemented("isManaged")),
+		sync: () => Effect.sync(() => unimplemented("sync")),
+		syncAll: () => Effect.sync(() => unimplemented("syncAll")),
+		check: () => Effect.sync(() => unimplemented("check")),
+		checkAll: () => Effect.sync(() => unimplemented("checkAll")),
+		remove: () => Effect.sync(() => unimplemented("remove")),
+		...overrides
+	});
+	/**
+	* The test layer: {@link ManagedSection.makeTest} behind `Layer.succeed`, so
+	* a suite provides only the members it exercises.
+	*
+	* @remarks
+	* A parameterized layer factory mints a fresh reference per call — bind it
+	* to a `const` rather than calling it at each composition site.
+	*/
+	static layerTest = (overrides = {}) => Layer.succeed(ManagedSection, ManagedSection.makeTest(overrides));
+};
+
+//#endregion
+export { ManagedSection, SectionFileError };

package/Section.js

@@ -0,0 +1,126 @@
+import { CommentStyle } from "./CommentStyle.js";
+import { Schema } from "effect";
+
+//#region src/Section.ts
+/**
+* The name identifying a managed section, as it literally appears in the
+* file's markers.
+*
+* @remarks
+* Keys are **case-sensitive** and rendered verbatim: the key a consumer
+* declares is the key the marker carries. A file already containing
+* `SAVVY-LINT` markers is managed by declaring the key `"SAVVY-LINT"`.
+*
+* The character set is bounded so a key can always be read back out of a
+* marker unambiguously — whitespace in particular would make the scanner's
+* key capture ambiguous against the marker phrase that follows it.
+*
+* This is a checked string rather than a branded one **deliberately**: a
+* brand would force every call site through a decode step to spell
+* `SectionId.make({ key: "example-tool", … })`, and the validation a brand
+* would carry is already enforced by the check at construction.
+*
+* @public
+*/
+const SectionKey = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/));
+/**
+* What identifies a managed section inside a document: its key and the
+* comment style its markers are written in.
+*
+* @remarks
+* `commentStyle` is **required, with no default**. A defaulted style is how a
+* caller who forgets the argument writes `#` markers into a TypeScript file —
+* a syntax error in the user's own source, produced silently by an omission.
+*
+* @example
+* ```ts
+* import { CommentStyle, SectionId } from "@effected/templates";
+*
+* const ToolSection = SectionId.make({
+*   key: "example-tool",
+*   commentStyle: CommentStyle.hash,
+* });
+*
+* const block = ToolSection.section("echo hello");
+* ```
+*
+* @public
+*/
+var SectionId = class extends Schema.Class("SectionId")({
+	/** The section's name, exactly as it appears in the markers. */
+	key: SectionKey,
+	/** How this section's markers are commented out. */
+	commentStyle: CommentStyle
+}) {
+	/** Pair this identity with the content a tool wants inside it. */
+	section(content) {
+		return Section.make({
+			key: this.key,
+			commentStyle: this.commentStyle,
+			content
+		});
+	}
+};
+/**
+* A managed section: an identity plus the content its owner wants between the
+* markers.
+*
+* @remarks
+* Equality is **structural and whitespace-significant**. The v3 model this
+* replaces compared trimmed, whitespace-collapsed content, which silently
+* swallowed any template change that altered only indentation — the change
+* compared equal, reported `Unchanged`, and never reached the file. The one
+* normalization this package applies is to line endings, and it happens at
+* parse time rather than inside equality, so `Equal.equals` stays honest for
+* a consumer comparing two sections directly.
+*
+* @public
+*/
+var Section = class Section extends Schema.Class("Section")({
+	/** The section's name, exactly as it appears in the markers. */
+	key: SectionKey,
+	/** How this section's markers are commented out. */
+	commentStyle: CommentStyle,
+	/** Everything between the markers, exclusive of the boundary line breaks. */
+	content: Schema.String
+}) {
+	/** This section's identity, without its content. */
+	get id() {
+		return SectionId.make({
+			key: this.key,
+			commentStyle: this.commentStyle
+		});
+	}
+	/** The same section carrying different content. */
+	withContent(content) {
+		return Section.make({
+			key: this.key,
+			commentStyle: this.commentStyle,
+			content
+		});
+	}
+};
+/**
+* A managed section as found in a document, carrying the span it occupies.
+*
+* @remarks
+* `start` and `end` bound the **whole** block, from the first character of
+* the begin marker to one past the last character of the end marker, so
+* `text.slice(start, end)` is exactly the block as written. `line` is 1-based
+* and points at the begin marker, which is what a diagnostic needs.
+*
+* @public
+*/
+var PlacedSection = class extends Schema.Class("PlacedSection")({
+	/** The section, with line endings already normalized to `\n`. */
+	section: Section,
+	/** Offset of the begin marker's first character. */
+	start: Schema.Number,
+	/** Offset one past the end marker's last character. */
+	end: Schema.Number,
+	/** 1-based line of the begin marker. */
+	line: Schema.Number
+}) {};
+
+//#endregion
+export { PlacedSection, Section, SectionId, SectionKey };

package/SectionDialect.js

@@ -0,0 +1,164 @@
+import { CommentStyle } from "./CommentStyle.js";
+import { Equal, Result, Schema } from "effect";
+
+//#region src/SectionDialect.ts
+/**
+* Raised when a section cannot be turned into marker-delimited text.
+*
+* @remarks
+* Both reasons describe a document this package would be unable to read back
+* correctly, so rendering refuses rather than writing something it cannot
+* re-parse.
+*
+* @public
+*/
+var SectionRenderError = class extends Schema.TaggedErrorClass()("SectionRenderError", {
+	/**
+	* `markerInContent` — the content carries a line the scanner would read as
+	* a marker, which would move the block boundary and let the next sync
+	* consume user text. `unknownCommentStyle` — the section's comment style
+	* is not in the dialect's set, so the block would be written into a
+	* document where the scanner could never find it again, growing a
+	* duplicate on every run. `duplicateDeclaration` — the same identity was
+	* declared twice in one call, so the caller stated two intentions for one
+	* block and any choice between them would be a guess; this is the
+	* caller-side twin of the document-side `duplicateSection`.
+	*/
+	reason: Schema.Literals([
+		"markerInContent",
+		"unknownCommentStyle",
+		"duplicateDeclaration"
+	]),
+	/** The key of the section that could not be rendered. */
+	key: Schema.String
+}) {
+	get message() {
+		switch (this.reason) {
+			case "markerInContent": return `Section "${this.key}" has content containing a managed-section marker`;
+			case "unknownCommentStyle": return `Section "${this.key}" uses a comment style this dialect does not recognize`;
+			default: return `Section "${this.key}" was declared twice in one call`;
+		}
+	}
+};
+/** The key grammar, mirrored from `SectionKey` for the scanner's capture group. */
+const KEY_CAPTURE = "([A-Za-z0-9][A-Za-z0-9._-]*)";
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Inter-token whitespace is tolerated on read, normalized on write. */
+const GAP = "[ \\t]+";
+/**
+* Compiled matchers are cached per dialect instance. A `WeakMap` rather than
+* a field keeps `SectionDialect` a pure schema class — v3 hung a non-schema
+* private field off its definition class and had to hand-copy it on every
+* derivation.
+*/
+const matcherCache = /* @__PURE__ */ new WeakMap();
+/**
+* The marker vocabulary: what phrase delimits a managed section, and which
+* comment styles a document is scanned for.
+*
+* @remarks
+* `styles` exists because reconciliation must **recognize sections it does
+* not own** — a foreign tool's block in the same file is preserved verbatim
+* and must never be mistaken for prose. That set cannot be derived from the
+* caller's own sections, because a foreign block's style may appear nowhere
+* in them.
+*
+* One phrase per dialect is deliberate: two marker families in one document
+* make parsing ambiguous for no benefit anyone has asked for.
+*
+* @public
+*/
+var SectionDialect = class SectionDialect extends Schema.Class("SectionDialect")({
+	/**
+	* The phrase between the key and the closing rule.
+	*
+	* @remarks
+	* Letters, digits, spaces and underscores only. Dashes are excluded so a
+	* phrase can never contain the `---` rule and make a marker ambiguous
+	* against itself.
+	*/
+	phrase: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9 _]*$/)),
+	/** Which comment styles the document scanner recognizes. At least one. */
+	styles: Schema.Array(CommentStyle).check(Schema.isMinLength(1))
+}) {
+	/**
+	* The zero-configuration dialect: the phrase `MANAGED SECTION` and every
+	* preset comment style.
+	*/
+	static default = SectionDialect.make({
+		phrase: "MANAGED SECTION",
+		styles: CommentStyle.presets
+	});
+	/** True when a section written in this style can be scanned back. */
+	recognizes(style) {
+		return this.styles.some((candidate) => Equal.equals(candidate, style));
+	}
+	/** The opening marker line for an identity, without a line break. */
+	beginMarker(id) {
+		return this.marker("BEGIN", id);
+	}
+	/** The closing marker line for an identity, without a line break. */
+	endMarker(id) {
+		return this.marker("END", id);
+	}
+	/**
+	* A section as marker-delimited text, or a typed refusal.
+	*
+	* @remarks
+	* Fails rather than producing a document it could not read back: see
+	* {@link SectionRenderError}. Content is emitted with `eol` throughout,
+	* so a section rendered into a CRLF document stays CRLF.
+	*/
+	render(section, eol = "\n") {
+		if (!this.recognizes(section.commentStyle)) return Result.fail(new SectionRenderError({
+			reason: "unknownCommentStyle",
+			key: section.key
+		}));
+		if (this.containsMarker(section.content)) return Result.fail(new SectionRenderError({
+			reason: "markerInContent",
+			key: section.key
+		}));
+		const body = eol === "\n" ? section.content : section.content.replace(/\n/g, eol);
+		return Result.succeed(`${this.beginMarker(section.id)}${eol}${body}${eol}${this.endMarker(section.id)}`);
+	}
+	/**
+	* True when `text` contains a line this dialect would read as a marker.
+	*
+	* @internal
+	*/
+	containsMarker(text) {
+		return this.matchers().some((matcher) => text.matchAll(matcher.regex).next().done === false);
+	}
+	/**
+	* One compiled scanner per recognized comment style, memoized.
+	*
+	* @remarks
+	* Each pattern is anchored per line, bounds the key with an explicit
+	* character class, and carries no nested quantifier, so scanning is linear
+	* in document length. Every caller-supplied fragment — prefix, suffix,
+	* phrase — is regex-escaped before interpolation.
+	*
+	* @internal
+	*/
+	matchers() {
+		const cached = matcherCache.get(this);
+		if (cached !== void 0) return cached;
+		const phrase = escapeRegex(this.phrase).replace(/ +/g, GAP);
+		const compiled = this.styles.map((style) => {
+			const tail = style.suffix === void 0 ? "" : `${GAP}${escapeRegex(style.suffix)}`;
+			return {
+				style,
+				regex: new RegExp(`^${escapeRegex(style.prefix)}${GAP}---${GAP}(BEGIN|END)${GAP}${KEY_CAPTURE}${GAP}${phrase}${GAP}---${tail}[ \\t]*(?=\r?$)`, "gm")
+			};
+		});
+		matcherCache.set(this, compiled);
+		return compiled;
+	}
+	marker(kind, id) {
+		const tail = id.commentStyle.suffix === void 0 ? "" : ` ${id.commentStyle.suffix}`;
+		return `${id.commentStyle.prefix} --- ${kind} ${id.key} ${this.phrase} ---${tail}`;
+	}
+};
+
+//#endregion
+export { SectionDialect, SectionRenderError };