@effected/templates 0.1.0

package/SectionDocument.js

@@ -0,0 +1,197 @@
+import { SectionDialect } from "./SectionDialect.js";
+import { CheckOutcome } from "./SectionOutcome.js";
+import { PlacedSection } from "./Section.js";
+import { SCAN_FAILURE_REASONS, detectEol, identityOf, normalizeEol, scan } from "./internal/scan.js";
+import { reconcile } from "./internal/reconcile.js";
+import { Effect, Equal, Option, Result, Schema } from "effect";
+
+//#region src/SectionDocument.ts
+/**
+* Raised when a document's managed-section structure cannot be read without
+* guessing.
+*
+* @remarks
+* Every reason names an ambiguity whose silent resolution corrupts a file.
+* A skipped unterminated marker makes the next write append a **second** copy
+* of the section; a duplicate means every sync updates the first copy while
+* the stale second one lives on disk forever. Malformed input therefore fails
+* through the typed channel with the line that identifies it, and the user
+* fixes their file.
+*
+* @public
+*/
+var SectionParseError = class SectionParseError extends Schema.TaggedErrorClass()("SectionParseError", {
+	/** Which ambiguity was found. */
+	reason: Schema.Literals(SCAN_FAILURE_REASONS),
+	/** 1-based line of the offending marker. */
+	line: Schema.Number,
+	/** The section key involved, when the failure names one. */
+	key: Schema.optionalKey(Schema.String),
+	/** The file the document came from. Absent for a document parsed from a string. */
+	path: Schema.optionalKey(Schema.String)
+}) {
+	get message() {
+		const where = this.path === void 0 ? `line ${this.line}` : `${this.path}:${this.line}`;
+		const which = this.key === void 0 ? "" : ` for section "${this.key}"`;
+		return `${REASON_PROSE[this.reason]}${which} at ${where}`;
+	}
+	/**
+	* The same failure, attributed to a file.
+	*
+	* @remarks
+	* The pure core has no path to report; the service that read the file
+	* attaches one on the way out.
+	*/
+	static at(path, error) {
+		return SectionParseError.make({
+			reason: error.reason,
+			line: error.line,
+			...error.key === void 0 ? {} : { key: error.key },
+			path
+		});
+	}
+};
+const REASON_PROSE = {
+	unterminatedSection: "Managed section is never closed",
+	orphanedEnd: "End marker closes no open section",
+	overlappingSections: "Managed section opens inside another",
+	duplicateSection: "Managed section appears twice"
+};
+/**
+* A parsed document: its text, the dialect it was read with, and every
+* managed section found in it.
+*
+* @remarks
+* This is the package's pure core. Parsing, inspection, reconciliation and
+* removal are all string-to-string, so every interesting invariant —
+* idempotency, text preservation, ordering normalization, line-ending
+* handling, marker-injection refusal — is assertable from a string literal
+* with no layer, no runtime and no filesystem.
+*
+* @example
+* ```ts
+* import { CommentStyle, SectionDocument, SectionId } from "@effected/templates";
+* import { Result } from "effect";
+*
+* const doc = SectionDocument.parseResult(source);
+* if (Result.isSuccess(doc)) {
+*   const id = SectionId.make({ key: "example-tool", commentStyle: CommentStyle.hash });
+*   const next = doc.success.reconcile([id.section("echo hello")]);
+* }
+* ```
+*
+* @public
+*/
+var SectionDocument = class SectionDocument extends Schema.Class("SectionDocument")({
+	/** The document's source text, exactly as parsed. */
+	text: Schema.String,
+	/** The marker vocabulary this document was read with. */
+	dialect: SectionDialect,
+	/** Every managed section found, in document order. */
+	sections: Schema.Array(PlacedSection),
+	/** The document's dominant line ending. */
+	eol: Schema.Literals(["\n", "\r\n"])
+}) {
+	/**
+	* Parse a document. The synchronous primitive.
+	*
+	* @remarks
+	* Pure computation exposes the sync form as the primitive; {@link SectionDocument.parse}
+	* derives from this and adds only the tracing span, so the two cannot drift.
+	* Synchronous callers — a lint hook, a build plugin — use this directly and
+	* never build an Effect runtime.
+	*/
+	static parseResult(text, dialect = SectionDialect.default) {
+		const scanned = scan(text, dialect);
+		if (!scanned.ok) {
+			const { reason, line, key } = scanned.failure;
+			return Result.fail(SectionParseError.make({
+				reason,
+				line,
+				...key === void 0 ? {} : { key }
+			}));
+		}
+		return Result.succeed(SectionDocument.make({
+			text,
+			dialect,
+			sections: scanned.sections,
+			eol: detectEol(text)
+		}));
+	}
+	/**
+	* Parse a document, in `Effect`.
+	*
+	* @remarks
+	* Defined in terms of {@link SectionDocument.parseResult} — synchronous
+	* callers can use that variant directly.
+	*/
+	static parse = Effect.fn("SectionDocument.parse")((text, dialect = SectionDialect.default) => Effect.fromResult(SectionDocument.parseResult(text, dialect)));
+	/** The section with this identity, if the document has one. */
+	read(id) {
+		const identity = identityOf(id.key, id.commentStyle);
+		const found = this.sections.find((placed) => identityOf(placed.section.key, placed.section.commentStyle) === identity);
+		return found === void 0 ? Option.none() : Option.some(found.section);
+	}
+	/** Whether the document carries a section with this identity. */
+	has(id) {
+		return Option.isSome(this.read(id));
+	}
+	/**
+	* Compare a declared section against the document, changing nothing.
+	*
+	* @remarks
+	* Total: there is no way for a comparison to fail. Line endings are
+	* normalized on both sides, so a CRLF document does not report drift
+	* against LF content forever.
+	*/
+	check(section) {
+		const expected = section.withContent(normalizeEol(section.content));
+		const current = this.read(section.id);
+		if (Option.isNone(current)) return CheckOutcome.Absent({ id: section.id });
+		return Equal.equals(current.value, expected) ? CheckOutcome.UpToDate({ section: current.value }) : CheckOutcome.Drifted({
+			onDisk: current.value,
+			expected
+		});
+	}
+	/**
+	* Fit a declared set of sections into this document.
+	*
+	* @remarks
+	* Declared sections come back **in declared order** — the ordering
+	* normalization is a guarantee consumers depend on, not a side effect.
+	* Text outside a managed span and sections this dialect does not own are
+	* preserved byte-for-byte. Nothing is rendered into the output until every
+	* declared section has rendered successfully, so a refusal leaves the
+	* document untouched.
+	*/
+	reconcile(sections) {
+		return reconcile({
+			text: this.text,
+			placed: this.sections,
+			declared: sections.map((section) => section.withContent(normalizeEol(section.content))),
+			dialect: this.dialect,
+			eol: this.eol
+		});
+	}
+	/**
+	* The document with this section removed, or `none` if it was not there.
+	*
+	* @remarks
+	* The blank lines around the removed block collapse into a single
+	* separator, so repeated removals never accumulate gaps.
+	*/
+	remove(id) {
+		const identity = identityOf(id.key, id.commentStyle);
+		const found = this.sections.find((placed) => identityOf(placed.section.key, placed.section.commentStyle) === identity);
+		if (found === void 0) return Option.none();
+		const eol = this.eol;
+		const before = this.text.slice(0, found.start).replace(/(?:\r?\n)+$/, "");
+		const after = this.text.slice(found.end).replace(/^(?:\r?\n)+/, "");
+		if (before !== "" && after !== "") return Option.some(`${before}${eol}${eol}${after}`);
+		if (before !== "") return Option.some(`${before}${eol}`);
+		return Option.some(after);
+	}
+};
+
+//#endregion
+export { SectionDocument, SectionParseError };

package/SectionOutcome.js

@@ -0,0 +1,20 @@
+import { Data } from "effect";
+
+//#region src/SectionOutcome.ts
+/**
+* Constructors and matchers for `SyncOutcome` — e.g.
+* `SyncOutcome.Created({ section })`, `SyncOutcome.$is("Updated")`.
+*
+* @public
+*/
+const SyncOutcome = Data.taggedEnum();
+/**
+* Constructors and matchers for `CheckOutcome` — e.g.
+* `CheckOutcome.Absent({ id })`, `CheckOutcome.$is("Drifted")`.
+*
+* @public
+*/
+const CheckOutcome = Data.taggedEnum();
+
+//#endregion
+export { CheckOutcome, SyncOutcome };