@effected/templates 0.1.0

package/index.d.ts

@@ -0,0 +1,812 @@
+import { Context, Data, Effect, FileSystem, Layer, Option, Result, Schema } from "effect";
+//#region src/CommentStyle.d.ts
+declare const CommentStyle_base: Schema.Class<CommentStyle, Schema.Struct<{
+  /** Opens the comment. Non-empty, single-line. */
+  readonly prefix: Schema.String;
+  /** Closes the comment, for wrapped styles. Omitted for line styles. */
+  readonly suffix: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * 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
+ */
+declare class CommentStyle extends CommentStyle_base {
+  /** Shell, YAML, TOML, Python, Dockerfile, `.env`. */
+  static readonly hash: CommentStyle;
+  /** JavaScript, TypeScript, C, Go, Rust, JSONC. */
+  static readonly slash: CommentStyle;
+  /** INI, Lisp, assembly. */
+  static readonly semicolon: CommentStyle;
+  /** SQL, Lua, Haskell. */
+  static readonly dash: CommentStyle;
+  /** Markdown, HTML, XML — the wrapped style v3 could not represent. */
+  static readonly html: CommentStyle;
+  /** CSS, and the block form of every C-family language. */
+  static readonly block: CommentStyle;
+  /**
+   * 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 readonly presets: ReadonlyArray<CommentStyle>;
+  /**
+   * 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(): string;
+  /** True when the style wraps its content, i.e. it carries a suffix. */
+  get isWrapped(): boolean;
+}
+//#endregion
+//#region src/Section.d.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
+ */
+declare const SectionKey: Schema.String;
+declare const SectionId_base: Schema.Class<SectionId, Schema.Struct<{
+  /** The section's name, exactly as it appears in the markers. */
+  readonly key: Schema.String;
+  /** How this section's markers are commented out. */
+  readonly commentStyle: typeof CommentStyle;
+}>, {}>;
+/**
+ * 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
+ */
+declare class SectionId extends SectionId_base {
+  /** Pair this identity with the content a tool wants inside it. */
+  section(content: string): Section;
+}
+declare const Section_base: Schema.Class<Section, Schema.Struct<{
+  /** The section's name, exactly as it appears in the markers. */
+  readonly key: Schema.String;
+  /** How this section's markers are commented out. */
+  readonly commentStyle: typeof CommentStyle;
+  /** Everything between the markers, exclusive of the boundary line breaks. */
+  readonly content: Schema.String;
+}>, {}>;
+/**
+ * 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
+ */
+declare class Section extends Section_base {
+  /** This section's identity, without its content. */
+  get id(): SectionId;
+  /** The same section carrying different content. */
+  withContent(content: string): Section;
+}
+declare const PlacedSection_base: Schema.Class<PlacedSection, Schema.Struct<{
+  /** The section, with line endings already normalized to `\n`. */
+  readonly section: typeof Section;
+  /** Offset of the begin marker's first character. */
+  readonly start: Schema.Number;
+  /** Offset one past the end marker's last character. */
+  readonly end: Schema.Number;
+  /** 1-based line of the begin marker. */
+  readonly line: Schema.Number;
+}>, {}>;
+/**
+ * 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
+ */
+declare class PlacedSection extends PlacedSection_base {}
+//#endregion
+//#region src/SectionDialect.d.ts
+/**
+ * The line ending a document uses.
+ *
+ * @public
+ */
+type Eol = "\n" | "\r\n";
+declare const SectionRenderError_base: Schema.Class<SectionRenderError, Schema.TaggedStruct<"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`.
+   */
+  readonly reason: Schema.Literals<readonly ["markerInContent", "unknownCommentStyle", "duplicateDeclaration"]>;
+  /** The key of the section that could not be rendered. */
+  readonly key: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+declare class SectionRenderError extends SectionRenderError_base {
+  get message(): string;
+}
+declare const SectionDialect_base: Schema.Class<SectionDialect, Schema.Struct<{
+  /**
+   * 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.
+   */
+  readonly phrase: Schema.String;
+  /** Which comment styles the document scanner recognizes. At least one. */
+  readonly styles: Schema.$Array<typeof CommentStyle>;
+}>, {}>;
+/**
+ * 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
+ */
+declare class SectionDialect extends SectionDialect_base {
+  /**
+   * The zero-configuration dialect: the phrase `MANAGED SECTION` and every
+   * preset comment style.
+   */
+  static readonly default: SectionDialect;
+  /** True when a section written in this style can be scanned back. */
+  recognizes(style: CommentStyle): boolean;
+  /** The opening marker line for an identity, without a line break. */
+  beginMarker(id: SectionId): string;
+  /** The closing marker line for an identity, without a line break. */
+  endMarker(id: SectionId): string;
+  /**
+   * 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: Section, eol?: Eol): Result.Result<string, SectionRenderError>;
+  /**
+   * True when `text` contains a line this dialect would read as a marker.
+   *
+   * @internal
+   */
+  containsMarker(text: string): boolean;
+  /**
+   * 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(): ReadonlyArray<{
+    readonly style: CommentStyle;
+    readonly regex: RegExp;
+  }>;
+  private marker;
+}
+//#endregion
+//#region src/SectionOutcome.d.ts
+/**
+ * What a sync did to one declared section.
+ *
+ * @remarks
+ * `Updated` carries **both sides** rather than a diff. The model this replaces
+ * computed a set difference over lines, which deduplicated, ignored order, and
+ * reported a pure line reordering as no change at all — a diff that could say
+ * "nothing changed" about changed content. Every consumer of that model read
+ * only the tag, so the honest primitive is the pair; a caller wanting a
+ * rendering diffs `before.content` against `after.content` with the diff
+ * library of its choice.
+ *
+ * @public
+ */
+type SyncOutcome = Data.TaggedEnum<{
+  /** The section was not in the document and has been added. */
+  readonly Created: {
+    readonly section: Section;
+  };
+  /** The section was present with different content and has been rewritten. */
+  readonly Updated: {
+    readonly before: Section;
+    readonly after: Section;
+  };
+  /** The section was already exactly as declared. */
+  readonly Unchanged: {
+    readonly section: Section;
+  };
+}>;
+/**
+ * Constructors and matchers for `SyncOutcome` — e.g.
+ * `SyncOutcome.Created({ section })`, `SyncOutcome.$is("Updated")`.
+ *
+ * @public
+ */
+declare const SyncOutcome: {
+  readonly $is: <Tag extends "Created" | "Unchanged" | "Updated">(tag: Tag) => (u: unknown) => u is Extract<{
+    readonly _tag: "Created";
+    readonly section: Section;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Unchanged";
+    readonly section: Section;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Updated";
+    readonly before: Section;
+    readonly after: Section;
+  }, {
+    readonly _tag: Tag;
+  }>;
+  readonly $match: {
+    <Cases extends {
+      readonly Created: (args: {
+        readonly _tag: "Created";
+        readonly section: Section;
+      }) => any;
+      readonly Unchanged: (args: {
+        readonly _tag: "Unchanged";
+        readonly section: Section;
+      }) => any;
+      readonly Updated: (args: {
+        readonly _tag: "Updated";
+        readonly before: Section;
+        readonly after: Section;
+      }) => any;
+    }>(cases: Cases): (value: {
+      readonly _tag: "Created";
+      readonly section: Section;
+    } | {
+      readonly _tag: "Unchanged";
+      readonly section: Section;
+    } | {
+      readonly _tag: "Updated";
+      readonly before: Section;
+      readonly after: Section;
+    }) => import("effect/Unify").Unify<ReturnType<Cases["Created" | "Unchanged" | "Updated"]>>;
+    <Cases extends {
+      readonly Created: (args: {
+        readonly _tag: "Created";
+        readonly section: Section;
+      }) => any;
+      readonly Unchanged: (args: {
+        readonly _tag: "Unchanged";
+        readonly section: Section;
+      }) => any;
+      readonly Updated: (args: {
+        readonly _tag: "Updated";
+        readonly before: Section;
+        readonly after: Section;
+      }) => any;
+    }>(value: {
+      readonly _tag: "Created";
+      readonly section: Section;
+    } | {
+      readonly _tag: "Unchanged";
+      readonly section: Section;
+    } | {
+      readonly _tag: "Updated";
+      readonly before: Section;
+      readonly after: Section;
+    }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Created" | "Unchanged" | "Updated"]>>;
+  };
+  readonly Created: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Created";
+    readonly section: Section;
+  }, "_tag">;
+  readonly Unchanged: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Unchanged";
+    readonly section: Section;
+  }, "_tag">;
+  readonly Updated: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Updated";
+    readonly before: Section;
+    readonly after: Section;
+  }, "_tag">;
+};
+/**
+ * What a check found, without touching the document.
+ *
+ * @remarks
+ * Three flat variants rather than the `Found({ isUpToDate, diff })` +
+ * `NotFound` pair they replace: a boolean beside a diff that already encodes
+ * the same fact is two sources of truth for one question, and it forces every
+ * caller through a nested branch.
+ *
+ * @public
+ */
+type CheckOutcome = Data.TaggedEnum<{
+  /** No section with this identity is in the document. */
+  readonly Absent: {
+    readonly id: SectionId;
+  };
+  /** The document already says exactly what was declared. */
+  readonly UpToDate: {
+    readonly section: Section;
+  };
+  /** The document has this section, with different content. */
+  readonly Drifted: {
+    readonly onDisk: Section;
+    readonly expected: Section;
+  };
+}>;
+/**
+ * Constructors and matchers for `CheckOutcome` — e.g.
+ * `CheckOutcome.Absent({ id })`, `CheckOutcome.$is("Drifted")`.
+ *
+ * @public
+ */
+declare const CheckOutcome: {
+  readonly $is: <Tag extends "Absent" | "Drifted" | "UpToDate">(tag: Tag) => (u: unknown) => u is Extract<{
+    readonly _tag: "Absent";
+    readonly id: SectionId;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Drifted";
+    readonly onDisk: Section;
+    readonly expected: Section;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "UpToDate";
+    readonly section: Section;
+  }, {
+    readonly _tag: Tag;
+  }>;
+  readonly $match: {
+    <Cases extends {
+      readonly Absent: (args: {
+        readonly _tag: "Absent";
+        readonly id: SectionId;
+      }) => any;
+      readonly Drifted: (args: {
+        readonly _tag: "Drifted";
+        readonly onDisk: Section;
+        readonly expected: Section;
+      }) => any;
+      readonly UpToDate: (args: {
+        readonly _tag: "UpToDate";
+        readonly section: Section;
+      }) => any;
+    }>(cases: Cases): (value: {
+      readonly _tag: "Absent";
+      readonly id: SectionId;
+    } | {
+      readonly _tag: "Drifted";
+      readonly onDisk: Section;
+      readonly expected: Section;
+    } | {
+      readonly _tag: "UpToDate";
+      readonly section: Section;
+    }) => import("effect/Unify").Unify<ReturnType<Cases["Absent" | "Drifted" | "UpToDate"]>>;
+    <Cases extends {
+      readonly Absent: (args: {
+        readonly _tag: "Absent";
+        readonly id: SectionId;
+      }) => any;
+      readonly Drifted: (args: {
+        readonly _tag: "Drifted";
+        readonly onDisk: Section;
+        readonly expected: Section;
+      }) => any;
+      readonly UpToDate: (args: {
+        readonly _tag: "UpToDate";
+        readonly section: Section;
+      }) => any;
+    }>(value: {
+      readonly _tag: "Absent";
+      readonly id: SectionId;
+    } | {
+      readonly _tag: "Drifted";
+      readonly onDisk: Section;
+      readonly expected: Section;
+    } | {
+      readonly _tag: "UpToDate";
+      readonly section: Section;
+    }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Absent" | "Drifted" | "UpToDate"]>>;
+  };
+  readonly Absent: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Absent";
+    readonly id: SectionId;
+  }, "_tag">;
+  readonly Drifted: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Drifted";
+    readonly onDisk: Section;
+    readonly expected: Section;
+  }, "_tag">;
+  readonly UpToDate: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "UpToDate";
+    readonly section: Section;
+  }, "_tag">;
+};
+//#endregion
+//#region src/SectionDocument.d.ts
+declare const SectionParseError_base: Schema.Class<SectionParseError, Schema.TaggedStruct<"SectionParseError", {
+  /** Which ambiguity was found. */
+  readonly reason: Schema.Literals<readonly ["unterminatedSection", "orphanedEnd", "overlappingSections", "duplicateSection"]>;
+  /** 1-based line of the offending marker. */
+  readonly line: Schema.Number;
+  /** The section key involved, when the failure names one. */
+  readonly key: Schema.optionalKey<Schema.String>;
+  /** The file the document came from. Absent for a document parsed from a string. */
+  readonly path: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+declare class SectionParseError extends SectionParseError_base {
+  get message(): string;
+  /**
+   * 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: string, error: SectionParseError): SectionParseError;
+}
+/**
+ * The result of reconciling a declared set of sections against a document.
+ *
+ * @remarks
+ * A plain interface rather than a `Schema.Class`: `outcomes` holds
+ * `SyncOutcome` values, which are a `Data.TaggedEnum` and therefore not
+ * a schema, so the class form would be schema-shaped in name only.
+ *
+ * @public
+ */
+interface SectionReconciliation {
+  /** The document as it should now read. */
+  readonly text: string;
+  /** One outcome per declared section, in declared order. */
+  readonly outcomes: ReadonlyArray<SyncOutcome>;
+  /** Whether `text` differs from the document it was reconciled against. */
+  readonly changed: boolean;
+}
+declare const SectionDocument_base: Schema.Class<SectionDocument, Schema.Struct<{
+  /** The document's source text, exactly as parsed. */
+  readonly text: Schema.String;
+  /** The marker vocabulary this document was read with. */
+  readonly dialect: typeof SectionDialect;
+  /** Every managed section found, in document order. */
+  readonly sections: Schema.$Array<typeof PlacedSection>;
+  /** The document's dominant line ending. */
+  readonly eol: Schema.Literals<readonly ["\n", "\r\n"]>;
+}>, {}>;
+/**
+ * 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
+ */
+declare class SectionDocument extends SectionDocument_base {
+  /**
+   * 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: string, dialect?: SectionDialect): Result.Result<SectionDocument, SectionParseError>;
+  /**
+   * Parse a document, in `Effect`.
+   *
+   * @remarks
+   * Defined in terms of {@link SectionDocument.parseResult} — synchronous
+   * callers can use that variant directly.
+   */
+  static readonly parse: (text: string, dialect?: SectionDialect | undefined) => Effect.Effect<SectionDocument, SectionParseError, never>;
+  /** The section with this identity, if the document has one. */
+  read(id: SectionId): Option.Option<Section>;
+  /** Whether the document carries a section with this identity. */
+  has(id: SectionId): boolean;
+  /**
+   * 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: Section): CheckOutcome;
+  /**
+   * 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: ReadonlyArray<Section>): Result.Result<SectionReconciliation, SectionRenderError>;
+  /**
+   * 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: SectionId): Option.Option<string>;
+}
+//#endregion
+//#region src/ManagedSection.d.ts
+declare const SectionFileError_base: Schema.Class<SectionFileError, Schema.TaggedStruct<"SectionFileError", {
+  /** The file the operation was against. */
+  readonly path: Schema.String;
+  /** Which half of the read-modify-write failed. */
+  readonly operation: Schema.Literals<readonly ["read", "write"]>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+declare class SectionFileError extends SectionFileError_base {
+  get message(): string;
+}
+/**
+ * The {@link ManagedSection} service shape.
+ *
+ * @remarks
+ * Exported so a consumer can type a function against the shape without naming
+ * the service class, and so the surface is a reviewable declaration rather
+ * than whatever the implementation happened to return.
+ *
+ * Every member is **data-first**: the path comes first and nothing is dual.
+ * The model this replaces made all seven members dual, which doubled the
+ * declared surface for a data-last form no call site used — and a dual member
+ * cannot be stubbed with a one-line override in {@link ManagedSection.layerTest},
+ * because the override has to satisfy both overloads.
+ *
+ * @public
+ */
+interface ManagedSectionShape {
+  /** The section with this identity, if the file has one. */
+  readonly read: (path: string, id: SectionId) => Effect.Effect<Option.Option<Section>, SectionParseError | SectionFileError>;
+  /** Every managed section in the file, in document order. */
+  readonly readAll: (path: string) => Effect.Effect<ReadonlyArray<Section>, SectionParseError | SectionFileError>;
+  /** Whether the file carries a section with this identity. */
+  readonly isManaged: (path: string, id: SectionId) => Effect.Effect<boolean, SectionParseError | SectionFileError>;
+  /** Make one section say what it should, writing only if that changes the file. */
+  readonly sync: (path: string, section: Section) => Effect.Effect<SyncOutcome, SectionParseError | SectionRenderError | SectionFileError>;
+  /**
+   * Make a whole set of sections say what they should, in declared order.
+   *
+   * @remarks
+   * The declared order is written into the file — see
+   * {@link SectionDocument.reconcile}. Writes only if the text changes.
+   */
+  readonly syncAll: (path: string, sections: ReadonlyArray<Section>) => Effect.Effect<ReadonlyArray<SyncOutcome>, SectionParseError | SectionRenderError | SectionFileError>;
+  /** Compare one section against the file, changing nothing. */
+  readonly check: (path: string, section: Section) => Effect.Effect<CheckOutcome, SectionParseError | SectionFileError>;
+  /** Compare a set of sections against the file from a single read. */
+  readonly checkAll: (path: string, sections: ReadonlyArray<Section>) => Effect.Effect<ReadonlyArray<CheckOutcome>, SectionParseError | SectionFileError>;
+  /** Remove a section. `false` when it was not there. */
+  readonly remove: (path: string, id: SectionId) => Effect.Effect<boolean, SectionParseError | SectionFileError>;
+}
+/**
+ * How a `ManagedSection` layer reads and writes markers.
+ *
+ * @public
+ */
+interface ManagedSectionOptions {
+  /** Defaults to {@link SectionDialect.default}. */
+  readonly dialect?: SectionDialect;
+}
+declare const ManagedSection_base: Context.ServiceClass<ManagedSection, "@effected/templates/ManagedSection", ManagedSectionShape>;
+/**
+ * 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
+ */
+declare class ManagedSection extends ManagedSection_base {
+  /**
+   * The default layer, reading and writing {@link SectionDialect.default}
+   * markers.
+   *
+   * @remarks
+   * A bound `const`, not a function, so it memoizes by reference.
+   */
+  static readonly layer: Layer.Layer<ManagedSection, never, FileSystem.FileSystem>;
+  /**
+   * 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 readonly layerWith: (options: ManagedSectionOptions) => Layer.Layer<ManagedSection, never, FileSystem.FileSystem>;
+  /**
+   * 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 readonly makeTest: (overrides?: Partial<ManagedSectionShape>) => ManagedSectionShape;
+  /**
+   * 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 readonly layerTest: (overrides?: Partial<ManagedSectionShape>) => Layer.Layer<ManagedSection>;
+}
+//#endregion
+export { CheckOutcome, CommentStyle, type Eol, ManagedSection, type ManagedSectionOptions, type ManagedSectionShape, PlacedSection, Section, SectionDialect, SectionDocument, SectionFileError, SectionId, SectionKey, SectionParseError, type SectionReconciliation, SectionRenderError, SyncOutcome };
+//# sourceMappingURL=index.d.ts.map