@effected/templates 0.1.0

package/index.js

@@ -0,0 +1,8 @@
+import { CommentStyle } from "./CommentStyle.js";
+import { SectionDialect, SectionRenderError } from "./SectionDialect.js";
+import { CheckOutcome, SyncOutcome } from "./SectionOutcome.js";
+import { PlacedSection, Section, SectionId, SectionKey } from "./Section.js";
+import { SectionDocument, SectionParseError } from "./SectionDocument.js";
+import { ManagedSection, SectionFileError } from "./ManagedSection.js";
+
+export { CheckOutcome, CommentStyle, ManagedSection, PlacedSection, Section, SectionDialect, SectionDocument, SectionFileError, SectionId, SectionKey, SectionParseError, SectionRenderError, SyncOutcome };

package/internal/reconcile.js

@@ -0,0 +1,113 @@
+import { SectionRenderError } from "../SectionDialect.js";
+import { SyncOutcome } from "../SectionOutcome.js";
+import { identityOf } from "./scan.js";
+import { Equal, Result } from "effect";
+
+//#region src/internal/reconcile.ts
+const reconcile = (input) => {
+	const { text, placed, declared, dialect, eol } = input;
+	const rendered = /* @__PURE__ */ new Map();
+	for (const section of declared) {
+		const identity = identityOf(section.key, section.commentStyle);
+		if (rendered.has(identity)) return Result.fail(new SectionRenderError({
+			reason: "duplicateDeclaration",
+			key: section.key
+		}));
+		const result = dialect.render(section, eol);
+		if (Result.isFailure(result)) return Result.fail(result.failure);
+		rendered.set(identity, result.success);
+	}
+	const onDisk = /* @__PURE__ */ new Map();
+	for (const entry of placed) onDisk.set(identityOf(entry.section.key, entry.section.commentStyle), entry);
+	const outcomes = declared.map((section) => {
+		const current = onDisk.get(identityOf(section.key, section.commentStyle));
+		if (current === void 0) return SyncOutcome.Created({ section });
+		return Equal.equals(current.section, section) ? SyncOutcome.Unchanged({ section }) : SyncOutcome.Updated({
+			before: current.section,
+			after: section
+		});
+	});
+	const items = [];
+	let cursor = 0;
+	for (const entry of placed) {
+		items.push({
+			kind: "text",
+			value: text.slice(cursor, entry.start)
+		});
+		items.push({
+			kind: "section",
+			identity: identityOf(entry.section.key, entry.section.commentStyle),
+			raw: text.slice(entry.start, entry.end),
+			render: void 0
+		});
+		cursor = entry.end;
+	}
+	items.push({
+		kind: "text",
+		value: text.slice(cursor)
+	});
+	const targets = new Set(declared.map((section) => identityOf(section.key, section.commentStyle)));
+	const slots = [];
+	items.forEach((item, index) => {
+		if (item.kind === "section" && targets.has(item.identity)) slots.push(index);
+	});
+	const itemIndexByDeclared = /* @__PURE__ */ new Map();
+	let slotCursor = 0;
+	declared.forEach((section, declaredIndex) => {
+		const identity = identityOf(section.key, section.commentStyle);
+		if (!onDisk.has(identity) || slotCursor >= slots.length) return;
+		const itemIndex = slots[slotCursor] ?? 0;
+		const item = items[itemIndex];
+		if (item?.kind === "section") item.render = rendered.get(identity);
+		itemIndexByDeclared.set(declaredIndex, itemIndex);
+		slotCursor += 1;
+	});
+	const beforeAnchor = /* @__PURE__ */ new Map();
+	const afterAnchor = /* @__PURE__ */ new Map();
+	const appended = [];
+	const pushInto = (map, anchor, value) => {
+		const list = map.get(anchor) ?? [];
+		list.push(value);
+		map.set(anchor, list);
+	};
+	declared.forEach((section, declaredIndex) => {
+		const identity = identityOf(section.key, section.commentStyle);
+		if (onDisk.has(identity)) return;
+		const block = rendered.get(identity) ?? "";
+		for (let next = declaredIndex + 1; next < declared.length; next += 1) {
+			const anchor = itemIndexByDeclared.get(next);
+			if (anchor !== void 0) {
+				pushInto(beforeAnchor, anchor, block);
+				return;
+			}
+		}
+		for (let previous = declaredIndex - 1; previous >= 0; previous -= 1) {
+			const anchor = itemIndexByDeclared.get(previous);
+			if (anchor !== void 0) {
+				pushInto(afterAnchor, anchor, block);
+				return;
+			}
+		}
+		appended.push(block);
+	});
+	const parts = [];
+	items.forEach((item, index) => {
+		if (item.kind === "text") {
+			parts.push(item.value);
+			return;
+		}
+		for (const block of beforeAnchor.get(index) ?? []) parts.push(block, eol, eol);
+		parts.push(item.render ?? item.raw);
+		for (const block of afterAnchor.get(index) ?? []) parts.push(eol, eol, block);
+	});
+	let output = parts.join("");
+	for (const block of appended) output = output.trim() === "" ? `${block}${eol}` : `${output.replace(/(?:\r?\n)+$/, "")}${eol}${eol}${block}${eol}`;
+	return Result.succeed({
+		text: output,
+		outcomes,
+		changed: output !== text
+	});
+};
+
+//#endregion
+export { reconcile };

package/internal/scan.js

@@ -0,0 +1,135 @@
+import { PlacedSection, Section } from "../Section.js";
+
+//#region src/internal/scan.ts
+/** The ways a document can be structurally unreadable. */
+const SCAN_FAILURE_REASONS = [
+	"unterminatedSection",
+	"orphanedEnd",
+	"overlappingSections",
+	"duplicateSection"
+];
+/** A document's dominant line ending. Any CRLF makes the document CRLF. */
+const detectEol = (text) => text.includes("\r\n") ? "\r\n" : "\n";
+/**
+* Collapse CRLF to LF.
+*
+* @remarks
+* Applied to section content at parse time so that the `Section` values the
+* rest of the package compares are already canonical. Doing it here rather
+* than inside equality keeps `Equal.equals` honest for a consumer comparing
+* two sections directly, and it is what stops a CRLF document from reporting
+* drift on every single run.
+*/
+const normalizeEol = (text) => text.replace(/\r\n/g, "\n");
+/** Strip exactly one line break from the start of a string. */
+const stripLeadingBreak = (text) => text.startsWith("\r\n") ? text.slice(2) : text.startsWith("\n") ? text.slice(1) : text;
+/** Strip exactly one line break from the end of a string. */
+const stripTrailingBreak = (text) => text.endsWith("\r\n") ? text.slice(0, -2) : text.endsWith("\n") ? text.slice(0, -1) : text;
+/** Offsets at which each 1-based line starts, for O(log n) line lookup. */
+const lineStarts = (text) => {
+	const starts = [0];
+	for (let index = 0; index < text.length; index += 1) if (text.charCodeAt(index) === 10) starts.push(index + 1);
+	return starts;
+};
+const lineAt = (starts, offset) => {
+	let low = 0;
+	let high = starts.length - 1;
+	while (low < high) {
+		const mid = low + high + 1 >> 1;
+		if ((starts[mid] ?? 0) <= offset) low = mid;
+		else high = mid - 1;
+	}
+	return low + 1;
+};
+/** The identity two sections must share to be duplicates of each other. */
+const identityOf = (key, style) => `${key}\u0000${style.id}`;
+const collectHits = (text, dialect) => {
+	const hits = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const matcher of dialect.matchers()) for (const match of text.matchAll(matcher.regex)) {
+		const start = match.index;
+		if (start === void 0 || seen.has(start)) continue;
+		seen.add(start);
+		hits.push({
+			kind: match[1] === "BEGIN" ? "BEGIN" : "END",
+			key: match[2] ?? "",
+			style: matcher.style,
+			start,
+			end: start + match[0].length
+		});
+	}
+	return hits.sort((left, right) => left.start - right.start);
+};
+/**
+* Locate every managed section, in document order.
+*
+* @remarks
+* A bounded linear pass — no recursion, so no stack-overflow surface on
+* hostile input. Sections cannot nest: a begin marker encountered while
+* another section is open is `overlappingSections`, not an inner block.
+*/
+const scan = (text, dialect) => {
+	const starts = lineStarts(text);
+	const sections = [];
+	const firstSeenAt = /* @__PURE__ */ new Map();
+	let open;
+	for (const hit of collectHits(text, dialect)) {
+		if (hit.kind === "BEGIN") {
+			if (open !== void 0) return {
+				ok: false,
+				failure: {
+					reason: "overlappingSections",
+					line: lineAt(starts, hit.start),
+					key: hit.key
+				}
+			};
+			open = hit;
+			continue;
+		}
+		if (open === void 0 || open.key !== hit.key || open.style.id !== hit.style.id) return {
+			ok: false,
+			failure: {
+				reason: "orphanedEnd",
+				line: lineAt(starts, hit.start),
+				key: hit.key
+			}
+		};
+		const identity = identityOf(open.key, open.style);
+		if (firstSeenAt.has(identity)) return {
+			ok: false,
+			failure: {
+				reason: "duplicateSection",
+				line: lineAt(starts, open.start),
+				key: open.key
+			}
+		};
+		firstSeenAt.set(identity, open.start);
+		const inner = stripTrailingBreak(stripLeadingBreak(text.slice(open.end, hit.start)));
+		sections.push(PlacedSection.make({
+			section: Section.make({
+				key: open.key,
+				commentStyle: open.style,
+				content: normalizeEol(inner)
+			}),
+			start: open.start,
+			end: hit.end,
+			line: lineAt(starts, open.start)
+		}));
+		open = void 0;
+	}
+	if (open !== void 0) return {
+		ok: false,
+		failure: {
+			reason: "unterminatedSection",
+			line: lineAt(starts, open.start),
+			key: open.key
+		}
+	};
+	return {
+		ok: true,
+		sections
+	};
+};
+
+//#endregion
+export { SCAN_FAILURE_REASONS, detectEol, identityOf, normalizeEol, scan };

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@effected/templates",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Managed-section blocks in user-editable files: parse, reconcile, sync and check delimited regions.",
+	"keywords": [
+		"templates",
+		"managed-section",
+		"codegen",
+		"sync",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/templates#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/templates"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "4.0.0-beta.101"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.12"
+    }
+  ]
+}