hafez 1.3.0 → 1.4.0

package/dist/document.d.ts

@@ -1,96 +1,113 @@
 import type { SessionLogEntry, SessionLogType } from './types.js';
-/**
- * Known structural section headings in Hafez entities, knowledge notes, and
- * session files. Derived from contracts.ts (defaultSections + optionalSections
- * + session sections) plus auto-generated sections not tracked in contracts
- * (Related). Only these are treated as section boundaries. Any other `## `
- * heading inside section content (e.g. in a brief or session log) is
- * preserved as-is.
- */
-export declare const STRUCTURAL_SECTIONS: Set<string>;
-/**
- * Find the next structural `## Heading` boundary after a given position.
- * Skips `## ` headings that are not known structural sections (content headings).
- * Returns the index of the `\n` before the `## `, or -1 if no structural heading found.
- */
-export declare function findNextStructuralHeading(body: string, from: number): number;
-/**
- * Find a ## Heading section and its content.
- * Returns { start, headingEnd, end, content } or null if not found.
- * Matches heading exactly (e.g. "## Brief" won't match "## Briefing").
- * Trailing whitespace on the heading line is tolerated — the splitter's
- * boundary tokenizer trims headings, so anything it treats as a boundary
- * must also be findable here (a hand-edited `## Session Log ` otherwise
- * gets a duplicate section and archival never fires).
- * Only treats known structural headings as section boundaries -- content
- * inside a section may contain arbitrary `## ` headings without corruption.
- */
-export declare function findSection(body: string, heading: string): {
-    start: number;
-    headingEnd: number;
-    end: number;
-    content: string;
-} | null;
-export interface DocSection {
-    heading: string;
-    content: string;
-}
-/**
- * Split a body into preamble + structural sections. Non-structural `## `
- * headings stay inside the enclosing section's content — sections are
- * atomic units of authored content, never split at user headings.
- * Headings and content come back trimmed; reassemble with
- * `## ${heading}\n\n${content}` joined by blank lines.
- */
-export declare function splitStructural(body: string): {
-    preamble: string;
-    sections: DocSection[];
-};
-/**
- * Replace a structural section's content, or create the section: before
- * `insertBefore` when that section exists, at EOF otherwise.
- */
-export declare function setSection(body: string, heading: string, content: string, insertBefore?: string): string;
-/** Append content at the end of a structural section (creating it at EOF if absent). */
-export declare function appendToSection(body: string, heading: string, content: string): string;
-/** Insert a formatted session-log entry newest-first (creating the section at EOF if absent). */
-export declare function prependSessionLogEntry(body: string, entry: string): string;
-/** Body up to the real Session Log section — the `summary` read depth. */
-export declare function bodyBeforeSessionLog(body: string): string;
 export declare function parseSessionLogHeading(line: string): {
     date: string;
     agent: string;
     type: SessionLogType;
 } | null;
 export declare function formatSessionLogEntry(entry: SessionLogEntry): string;
-/** Entries inside the real Session Log section only — entry-shaped lines
- * elsewhere in the body (e.g. quoted in a Brief) do not count. */
-export declare function countSessionLogEntries(body: string): number;
+/**
+ * Split a Session Log section's content into raw entry blocks, each beginning
+ * with a parseable entry heading. Non-entry text before the first heading is
+ * not an entry and is dropped. Document owns entry block splitting — merge's
+ * dedup/sort policy stays in merge.ts.
+ */
+export declare function splitLogEntries(content: string): string[];
+export declare function firstNonEmptyLine(s: string | null | undefined): string;
+/** The one wiki-link syntax the vault recognizes: [[slug]] or
+ * [[slug|display text]] — slug in group 1, display text in group 2.
+ * Padding inside the brackets is Obsidian-idiomatic ([[ slug ]], [[slug | Label]])
+ * and is absorbed by the pattern, so both captures come out already trimmed —
+ * every consumer (Related coverage, mention harvesting, export) sees the bare slug.
+ * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
+export declare const WIKI_LINK_RE: RegExp;
+/** What documentFor needs to know about a file to bind its section set.
+ *
+ * KIND is the whole context — deliberately no type/subtype narrowing. A file
+ * can legitimately carry sections outside its current type's contract (a
+ * promote race merged in a capture's Notes, a plan-shaped note never had its
+ * subtype persisted, a hand edit added Open Questions to a plain entity), and
+ * a narrower binding demotes those headings to non-structural text that the
+ * next section rewrite silently deletes. The kind-level union makes every
+ * same-kind heading a boundary, so no same-kind section is ever swallowed;
+ * the cost is that a same-kind heading quoted at line start inside a section
+ * strands as its own section on rewrite — visible and recoverable, unlike
+ * deletion. Cross-KIND headings (a session-only ## Decisions quoted in an
+ * entity Brief) are still not boundaries. */
+export interface DocContext {
+    kind: 'entity' | 'knowledge' | 'session';
+}
+/** The structural set a context binds — exposed for introspection and the
+ * contract-coverage tests; runtime consumers go through documentFor. */
+export declare function structuralSectionsFor(ctx: DocContext): ReadonlySet<string>;
+/** The Document operations bound to one file's structural section set. */
+export declare function documentFor(ctx: DocContext): Doc;
+/** Bind from a parsed vault file — kind from Layout. */
+export declare function documentForFile(parsed: {
+    kind: 'entity' | 'knowledge' | 'session';
+}): Doc;
+export interface DocSection {
+    heading: string;
+    content: string;
+}
+export interface Doc {
+    findNextStructuralHeading(body: string, from: number): number;
+    findSection(body: string, heading: string): {
+        start: number;
+        headingEnd: number;
+        end: number;
+        content: string;
+    } | null;
+    splitStructural(body: string): {
+        preamble: string;
+        sections: DocSection[];
+    };
+    setSection(body: string, heading: string, content: string, insertBefore?: string): string;
+    appendToSection(body: string, heading: string, content: string): string;
+    renameSection(body: string, from: string, to: string): string;
+    ensureSection(body: string, heading: string, opts?: {
+        after?: string;
+    }): string;
+    prependSessionLogEntry(body: string, entry: string): string;
+    bodyBeforeSessionLog(body: string): string;
+    countSessionLogEntries(body: string): number;
+    parseSessionLog(body: string): Array<{
+        date: string;
+        agent: string;
+        type: SessionLogType;
+        summary: string;
+    }>;
+    extractOldestSessionLogEntry(body: string): {
+        entry: string;
+        remaining: string;
+    } | null;
+    getBrief(body: string): string | null;
+    setBrief(body: string, content: string): string;
+    removeBrief(body: string): string;
+    getNextActions(body: string): string[];
+    addNextAction(body: string, action: string): string;
+    completeNextAction(body: string, query: string): {
+        matched: string;
+        body: string;
+    };
+    removeNextAction(body: string, query: string): {
+        matched: string;
+        body: string;
+    };
+    clearNextActions(body: string): string;
+    syncRelatedSection(body: string, frontmatter: {
+        parent?: string;
+        related?: string[];
+    }): string;
+}
+export declare function getBrief(body: string): string | null;
+export declare function getNextActions(body: string): string[];
 export declare function parseSessionLog(body: string): Array<{
     date: string;
     agent: string;
     type: SessionLogType;
     summary: string;
 }>;
-export declare function extractOldestSessionLogEntry(body: string): {
-    entry: string;
-    remaining: string;
-} | null;
-export declare function getBrief(body: string): string | null;
-export declare function setBrief(body: string, content: string): string;
-export declare function removeBrief(body: string): string;
-export declare function getNextActions(body: string): string[];
-export declare function addNextAction(body: string, action: string): string;
-export declare function completeNextAction(body: string, query: string): {
-    matched: string;
-    body: string;
-};
-export declare function removeNextAction(body: string, query: string): {
-    matched: string;
-    body: string;
-};
-export declare function clearNextActions(body: string): string;
-export declare function firstNonEmptyLine(s: string | null | undefined): string;
+export declare function countSessionLogEntries(body: string): number;
 /**
  * One-line summary for a doc: frontmatter description first, then the first
  * non-empty line of the kind's primary section (entity: Brief; knowledge:
@@ -98,11 +115,3 @@ export declare function firstNonEmptyLine(s: string | null | undefined): string;
  * Shared by the vault index and the OKF export so the two surfaces agree.
  */
 export declare function deriveSummary(kind: 'entity' | 'knowledge' | 'session', fm: Record<string, any>, body: string): string;
-/** The one wiki-link syntax the vault recognizes: [[slug]] or
- * [[slug|display text]] — slug in group 1, display text in group 2.
- * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
-export declare const WIKI_LINK_RE: RegExp;
-export declare function syncRelatedSection(body: string, frontmatter: {
-    parent?: string;
-    related?: string[];
-}): string;