@effected/templates 0.3.0 → 0.4.0

package/README.md

@@ -65,11 +65,40 @@ Effect.runPromise(program.pipe(Effect.provide(ManagedSection.layer), Effect.prov
 // example output on a second, identical run: [ "Unchanged", "Unchanged" ]
 ```
 
+## Marker attributes
+
+A `BEGIN` marker can carry `name="value"` pairs, so a tool reads a block's provenance — which run wrote it, and when — off the marker line without opening the block:
+
+```ts
+import { CommentStyle, SectionDocument, SectionId } from "@effected/templates";
+import { Result } from "effect";
+
+const Tool = SectionId.make({ key: "tool", commentStyle: CommentStyle.hash });
+const doc = SectionDocument.parseResult("#!/usr/bin/env sh\n");
+
+if (Result.isSuccess(doc)) {
+  const next = doc.success.reconcile([Tool.section("npx tool run", { origin: "ci", runId: "1873" })]);
+  console.log(Result.isSuccess(next) ? next.success.text : next.failure.message);
+  // #!/usr/bin/env sh
+  //
+  // # --- BEGIN tool MANAGED SECTION origin="ci" runId="1873" ---
+  // npx tool run
+  // # --- END tool MANAGED SECTION ---
+}
+```
+
+Attributes are metadata, never identity: a section is found by key and comment style alone, so bumping `runId` updates that block in place instead of orphaning it and appending a second one. They do count as difference — `check` answers `Drifted` when a declared attribute disagrees with the marker on disk, which is what lets a tool rewrite a block whose only change is its metadata. Omitting the argument and passing `{}` are the same section, so a caller that never uses attributes sees no drift against a bare marker.
+
+The grammar has no escaping, deliberately: names match `[A-Za-z][A-Za-z0-9_-]*`, values are double-quoted and carry neither `"` nor a line break, and anything outside that fails typed as a `SectionRenderError` with `reason: "invalidAttribute"` naming the attribute — before a byte is written. An `END` marker never carries attributes, and an attribute run that does not parse cleanly (a mangled pair, one name declared twice) makes the whole line ordinary content rather than a marker.
+
+Attributed markers are a one-way compatibility break: a scanner predating this feature does not recognize one at all, so the block it opens stops being a managed section for that tool. Writing attributes into a file another tool also manages is a decision, not a detail.
+
 ## Features
 
 - `SectionDocument` — the pure core: `parse` / `read` / `has` / `check` / `reconcile` / `remove` over a plain string, with no `Effect`, no IO and no runtime needed to test it.
 - `ManagedSection` — the service: `read`, `readAll`, `isManaged`, `sync`, `syncAll`, `check`, `checkAll` and `remove`, each writing back only when the text changed.
 - `CommentStyle` — an open set of `{prefix, suffix?}` presets (`hash`, `slash`, `semicolon`, `dash`, `html`, `block`) covering both line comments and wrapped ones like `<!-- … -->`, so a managed section can live in Markdown or HTML, not just source files.
+- Marker attributes — `name="value"` pairs on a `BEGIN` marker, via `SectionId.section(content, attributes)` and `Section.attributes`: metadata for the tool, never part of a section's identity.
 - `SyncOutcome` / `CheckOutcome` — tagged results (`Created` / `Updated` / `Unchanged`, `Absent` / `UpToDate` / `Drifted`) that carry the sections involved rather than a diff, so a caller renders exactly the comparison it needs.
 - Byte-preserving outside managed blocks: every character outside a declared section's span survives a sync, in order, including a leading BOM.
 - Idempotent by construction: syncing an already-up-to-date document writes nothing and touches no mtime.

package/Section.js

@@ -1,5 +1,5 @@
 import { CommentStyle } from "./CommentStyle.js";
-import { Schema } from "effect";
+import { Effect, Schema } from "effect";
 
 //#region src/Section.ts
 /**
@@ -52,12 +52,20 @@ var SectionId = class extends Schema.Class("SectionId")({
 	/** How this section's markers are commented out. */
 	commentStyle: CommentStyle
 }) {
-	/** Pair this identity with the content a tool wants inside it. */
-	section(content) {
+	/**
+	* Pair this identity with the content a tool wants inside it.
+	*
+	* @remarks
+	* `attributes` become `name="value"` pairs on the section's BEGIN marker,
+	* emitted in the record's insertion order. They are metadata, not identity:
+	* see {@link Section} for the grammar and the equality rules.
+	*/
+	section(content, attributes) {
 		return Section.make({
 			key: this.key,
 			commentStyle: this.commentStyle,
-			content
+			content,
+			...attributes === void 0 ? {} : { attributes }
 		});
 	}
 };
@@ -74,6 +82,21 @@ var SectionId = class extends Schema.Class("SectionId")({
 * parse time rather than inside equality, so `Equal.equals` stays honest for
 * a consumer comparing two sections directly.
 *
+* `attributes` are `name="value"` pairs carried on the BEGIN marker — metadata
+* a tool wants readable from the marker line itself, without opening the
+* content. They **participate in equality** (an attribute change is real
+* drift) but **never in identity**: the section a marker names is decided by
+* key and comment style alone, so changing an attribute updates a block in
+* place rather than orphaning it. Equality over attributes is record equality
+* — order-insensitive, so two sections carrying the same pairs in different
+* insertion orders compare equal — while an actual rewrite renders the pairs
+* in the record's insertion order. Omitting the field and passing `{}` are
+* the same section: the constructor defaults to an empty record.
+*
+* Attribute names must match `[A-Za-z][A-Za-z0-9_-]*` and values may not
+* contain `"` or a line break; violations fail typed at render, not here, so
+* runtime data can never turn construction into a defect.
+*
 * @public
 */
 var Section = class Section extends Schema.Class("Section")({
@@ -82,7 +105,9 @@ var Section = class Section extends Schema.Class("Section")({
 	/** How this section's markers are commented out. */
 	commentStyle: CommentStyle,
 	/** Everything between the markers, exclusive of the boundary line breaks. */
-	content: Schema.String
+	content: Schema.String,
+	/** The BEGIN marker's `name="value"` pairs. Empty when the marker carries none. */
+	attributes: Schema.Record(Schema.String, Schema.String).pipe(Schema.withConstructorDefault(Effect.succeed({})))
 }) {
 	/** This section's identity, without its content. */
 	get id() {
@@ -91,12 +116,13 @@ var Section = class Section extends Schema.Class("Section")({
 			commentStyle: this.commentStyle
 		});
 	}
-	/** The same section carrying different content. */
+	/** The same section carrying different content. Attributes are preserved. */
 	withContent(content) {
 		return Section.make({
 			key: this.key,
 			commentStyle: this.commentStyle,
-			content
+			content,
+			attributes: this.attributes
 		});
 	}
 };

package/SectionDialect.js

@@ -1,4 +1,5 @@
 import { CommentStyle } from "./CommentStyle.js";
+import { ATTRIBUTE_NAME_PATTERN, isValidAttributeValue, parseAttributeRun } from "./internal/attributes.js";
 import { Equal, Result, Schema } from "effect";
 
 //#region src/SectionDialect.ts
@@ -23,19 +24,27 @@ var SectionRenderError = class extends Schema.TaggedError()("SectionRenderError"
 	* 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`.
+	* `invalidAttribute` — an attribute's name is outside the
+	* `[A-Za-z][A-Za-z0-9_-]*` grammar, or its value contains `"` or a line
+	* break; either would render a marker the scanner could not read back
+	* verbatim, and there is no escaping mechanism by design.
 	*/
 	reason: Schema.Literals([
 		"markerInContent",
 		"unknownCommentStyle",
-		"duplicateDeclaration"
+		"duplicateDeclaration",
+		"invalidAttribute"
 	]),
 	/** The key of the section that could not be rendered. */
-	key: Schema.String
+	key: Schema.String,
+	/** The offending attribute's name, when the refusal names one. */
+	attribute: Schema.optionalKey(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`;
+			case "invalidAttribute": return this.attribute === void 0 ? `Section "${this.key}" declares an attribute with an invalid name or value` : `Section "${this.key}" declares attribute "${this.attribute}" with an invalid name or value`;
 			default: return `Section "${this.key}" was declared twice in one call`;
 		}
 	}
@@ -114,12 +123,18 @@ var SectionDialect = class SectionDialect extends Schema.Class("SectionDialect")
 			reason: "unknownCommentStyle",
 			key: section.key
 		}));
+		for (const [name, value] of Object.entries(section.attributes)) if (!ATTRIBUTE_NAME_PATTERN.test(name) || !isValidAttributeValue(value)) return Result.fail(new SectionRenderError({
+			reason: "invalidAttribute",
+			key: section.key,
+			attribute: name
+		}));
 		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)}`);
+		const begin = this.marker("BEGIN", section.id, section.attributes);
+		return Result.succeed(`${begin}${eol}${body}${eol}${this.endMarker(section.id)}`);
 	}
 	/**
 	* True when `text` contains a line this dialect would read as a marker.
@@ -127,7 +142,12 @@ var SectionDialect = class SectionDialect extends Schema.Class("SectionDialect")
 	* @internal
 	*/
 	containsMarker(text) {
-		return this.matchers().some((matcher) => text.matchAll(matcher.regex).next().done === false);
+		for (const matcher of this.matchers()) for (const match of text.matchAll(matcher.regex)) {
+			const run = match[3];
+			if (run === void 0) return true;
+			if (match[1] !== "END" && parseAttributeRun(run) !== void 0) return true;
+		}
+		return false;
 	}
 	/**
 	* One compiled scanner per recognized comment style, memoized.
@@ -148,15 +168,16 @@ var SectionDialect = class SectionDialect extends Schema.Class("SectionDialect")
 			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")
+				regex: new RegExp(`^${escapeRegex(style.prefix)}${GAP}---${GAP}(BEGIN|END)${GAP}${KEY_CAPTURE}${GAP}${phrase}(?:${GAP}([^ \\t\\r\\n][^\\r\\n]*?))?${GAP}---${tail}[ \\t]*(?=\r?$)`, "gm")
 			};
 		});
 		matcherCache.set(this, compiled);
 		return compiled;
 	}
-	marker(kind, id) {
+	marker(kind, id, attributes) {
 		const tail = id.commentStyle.suffix === void 0 ? "" : ` ${id.commentStyle.suffix}`;
-		return `${id.commentStyle.prefix} --- ${kind} ${id.key} ${this.phrase} ---${tail}`;
+		const run = attributes === void 0 ? "" : Object.entries(attributes).map(([name, value]) => ` ${name}="${value}"`).join("");
+		return `${id.commentStyle.prefix} --- ${kind} ${id.key} ${this.phrase}${run} ---${tail}`;
 	}
 };
 

package/index.d.ts

@@ -119,8 +119,15 @@ declare const SectionId_base: Schema.Class<SectionId, Schema.Struct<{
  * @public
  */
 declare class SectionId extends SectionId_base {
-  /** Pair this identity with the content a tool wants inside it. */
-  section(content: string): Section;
+  /**
+   * Pair this identity with the content a tool wants inside it.
+   *
+   * @remarks
+   * `attributes` become `name="value"` pairs on the section's BEGIN marker,
+   * emitted in the record's insertion order. They are metadata, not identity:
+   * see {@link Section} for the grammar and the equality rules.
+   */
+  section(content: string, attributes?: Readonly<Record<string, string>>): Section;
 }
 declare const Section_base: Schema.Class<Section, Schema.Struct<{
   /** The section's name, exactly as it appears in the markers. */
@@ -129,6 +136,8 @@ declare const Section_base: Schema.Class<Section, Schema.Struct<{
   readonly commentStyle: typeof CommentStyle;
   /** Everything between the markers, exclusive of the boundary line breaks. */
   readonly content: Schema.String;
+  /** The BEGIN marker's `name="value"` pairs. Empty when the marker carries none. */
+  readonly attributes: Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.String>>;
 }>, {}>;
 /**
  * A managed section: an identity plus the content its owner wants between the
@@ -143,12 +152,27 @@ declare const Section_base: Schema.Class<Section, Schema.Struct<{
  * parse time rather than inside equality, so `Equal.equals` stays honest for
  * a consumer comparing two sections directly.
  *
+ * `attributes` are `name="value"` pairs carried on the BEGIN marker — metadata
+ * a tool wants readable from the marker line itself, without opening the
+ * content. They **participate in equality** (an attribute change is real
+ * drift) but **never in identity**: the section a marker names is decided by
+ * key and comment style alone, so changing an attribute updates a block in
+ * place rather than orphaning it. Equality over attributes is record equality
+ * — order-insensitive, so two sections carrying the same pairs in different
+ * insertion orders compare equal — while an actual rewrite renders the pairs
+ * in the record's insertion order. Omitting the field and passing `{}` are
+ * the same section: the constructor defaults to an empty record.
+ *
+ * Attribute names must match `[A-Za-z][A-Za-z0-9_-]*` and values may not
+ * contain `"` or a line break; violations fail typed at render, not here, so
+ * runtime data can never turn construction into a defect.
+ *
  * @public
  */
 declare class Section extends Section_base {
   /** This section's identity, without its content. */
   get id(): SectionId;
-  /** The same section carrying different content. */
+  /** The same section carrying different content. Attributes are preserved. */
   withContent(content: string): Section;
 }
 declare const PlacedSection_base: Schema.Class<PlacedSection, Schema.Struct<{
@@ -192,10 +216,16 @@ declare const SectionRenderError_base: Schema.Class<SectionRenderError, Schema.T
    * 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`.
+   * `invalidAttribute` — an attribute's name is outside the
+   * `[A-Za-z][A-Za-z0-9_-]*` grammar, or its value contains `"` or a line
+   * break; either would render a marker the scanner could not read back
+   * verbatim, and there is no escaping mechanism by design.
    */
-  readonly reason: Schema.Literals<readonly ["markerInContent", "unknownCommentStyle", "duplicateDeclaration"]>;
+  readonly reason: Schema.Literals<readonly ["markerInContent", "unknownCommentStyle", "duplicateDeclaration", "invalidAttribute"]>;
   /** The key of the section that could not be rendered. */
   readonly key: Schema.String;
+  /** The offending attribute's name, when the refusal names one. */
+  readonly attribute: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Raised when a section cannot be turned into marker-delimited text.

package/internal/attributes.js

@@ -0,0 +1,63 @@
+//#region src/internal/attributes.ts
+/** The attribute name grammar. No leading digit, underscore or dash. */
+const ATTRIBUTE_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+/** True when a value can appear inside an attribute's double quotes verbatim. */
+const isValidAttributeValue = (value) => !value.includes("\"") && !value.includes("\n") && !value.includes("\r");
+const isNameStart = (code) => code >= 65 && code <= 90 || code >= 97 && code <= 122;
+const isNameChar = (code) => isNameStart(code) || code >= 48 && code <= 57 || code === 95 || code === 45;
+const isSeparator = (code) => code === 32 || code === 9;
+/**
+* Parse a captured attribute run, or refuse it.
+*
+* @remarks
+* `undefined` means the run is not a valid attribute run and the line carrying
+* it is **not a marker** — it is ordinary content. That covers a mangled pair
+* and a name declared twice: two values for one name is two intentions for one
+* attribute, and any choice between them would be a guess.
+*
+* Document order is preserved: the returned record's insertion order is the
+* order the pairs appear in the marker.
+*
+* A hand-rolled single pass rather than a validating regex: the run comes off
+* an untrusted document line, and the natural `(pair)(sep pair)*$` pattern
+* backtracks polynomially on hostile near-misses. This walk touches each
+* character exactly once, so a megabyte of adversarial line costs a megabyte
+* of work.
+*/
+const parseAttributeRun = (run) => {
+	const attributes = {};
+	const length = run.length;
+	let index = 0;
+	let first = true;
+	while (index < length) {
+		if (!first) {
+			if (!isSeparator(run.charCodeAt(index))) return;
+			while (index < length && isSeparator(run.charCodeAt(index))) index += 1;
+			if (index >= length) return;
+		}
+		first = false;
+		if (!isNameStart(run.charCodeAt(index))) return;
+		const nameStart = index;
+		index += 1;
+		while (index < length && isNameChar(run.charCodeAt(index))) index += 1;
+		const name = run.slice(nameStart, index);
+		if (index + 1 >= length || run.charCodeAt(index) !== 61 || run.charCodeAt(index + 1) !== 34) return;
+		index += 2;
+		const valueStart = index;
+		while (index < length) {
+			const code = run.charCodeAt(index);
+			if (code === 34) break;
+			if (code === 10 || code === 13) return;
+			index += 1;
+		}
+		if (index >= length) return;
+		const value = run.slice(valueStart, index);
+		index += 1;
+		if (Object.hasOwn(attributes, name)) return;
+		attributes[name] = value;
+	}
+	return first ? void 0 : attributes;
+};
+
+//#endregion
+export { ATTRIBUTE_NAME_PATTERN, isValidAttributeValue, parseAttributeRun };

package/internal/scan.js

@@ -1,3 +1,4 @@
+import { parseAttributeRun } from "./attributes.js";
 import { PlacedSection, Section } from "../Section.js";
 
 //#region src/internal/scan.ts
@@ -49,13 +50,21 @@ const collectHits = (text, dialect) => {
 	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;
+		const run = match[3];
+		let attributes;
+		if (run !== void 0) {
+			if (match[1] === "END") continue;
+			attributes = parseAttributeRun(run);
+			if (attributes === void 0) continue;
+		}
 		seen.add(start);
 		hits.push({
 			kind: match[1] === "BEGIN" ? "BEGIN" : "END",
 			key: match[2] ?? "",
 			style: matcher.style,
 			start,
-			end: start + match[0].length
+			end: start + match[0].length,
+			...attributes === void 0 ? {} : { attributes }
 		});
 	}
 	return hits.sort((left, right) => left.start - right.start);
@@ -109,7 +118,8 @@ const scan = (text, dialect) => {
 			section: Section.make({
 				key: open.key,
 				commentStyle: open.style,
-				content: normalizeEol(inner)
+				content: normalizeEol(inner),
+				...open.attributes === void 0 ? {} : { attributes: open.attributes }
 			}),
 			start: open.start,
 			end: hit.end,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/templates",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"private": false,
 	"description": "Managed-section blocks in user-editable files: parse, reconcile, sync and check delimited regions.",
 	"keywords": [