open-agreements
Version:
Open-source legal template filling CLI and library
76 lines • 3.04 kB
TypeScript
import type { DocumentViewNode } from './document_view-types.js';
/**
* Deterministic locator primitive over a `DocumentView`.
*
* A locator resolves a SINGLE span (raw-text offsets within one node) and never
* heals, scores, or guesses. Ambiguity — zero matches or more than one — is a
* drift signal reported as `unresolved`, so a caller updates the selector rather
* than silently filling the wrong place. Redundant `assertions` corroborate the
* `primary` match the moment an upstream change makes them disagree.
*
* Patterns are authored against the stable, normalized `clean_text`; resolved
* spans are returned as RAW offsets (`getParagraphText` / `replaceTextAtRange`
* coordinates) via {@link buildCleanToRawOffsetMap}.
*/
export type LocatorStep = {
kind: 'section';
/** Exact match against the node's derived heading text. */
headingText?: string;
/** Regex (un-anchored) tested against the node's derived heading text. */
headingRegex?: string;
/** Exact match against the paragraph's Word style id. */
headingStyleId?: string;
/**
* Outline level at which the region ends: the region runs from the matched
* heading until the next heading whose level is `<= untilLevel`. Defaults
* to the matched heading's own level (so the region ends at the next
* sibling-or-higher heading); when the matched heading has no level and no
* `untilLevel` is given, the region runs to the end of the current scope.
*/
untilLevel?: number;
} | {
kind: 'regex';
pattern: string;
flags?: string;
group?: number;
} | {
kind: 'contextual';
contextPattern: string;
targetPattern: string;
rowLabelPattern?: string;
} | {
kind: 'fingerprint';
contentFingerprint: string;
};
export interface Locator {
/** Ordered `section` steps narrowing to a region (Scrapy-style nesting). */
scope?: LocatorStep[];
/** The deterministic single-span resolver. Must be regex | contextual | fingerprint. */
primary: LocatorStep;
/** Corroborators that never select. Must be regex | contextual | fingerprint. */
assertions?: LocatorStep[];
}
export interface LocatorAssertionResult {
ok: boolean;
kind: string;
detail?: string;
}
export interface LocatorResolution {
/** RAW-offset span, or null when the primary did not resolve to exactly one span. */
match: {
nodeId: string;
start: number;
end: number;
} | null;
/** True when the primary matched zero or more than one span (a drift signal). */
unresolved: boolean;
/** Per-assertion corroboration results (empty when `unresolved`). */
assertionResults: LocatorAssertionResult[];
}
/**
* Resolve a {@link Locator} against a document view. Deterministic: the same
* `(view, locator)` always yields the same result, with no randomness, scoring,
* or tie-breaking.
*/
export declare function resolveLocator(view: DocumentViewNode[], locator: Locator): LocatorResolution;
//# sourceMappingURL=locator.d.ts.map