open-agreements
Version:
Open-source legal template filling CLI and library
110 lines • 5.08 kB
TypeScript
/**
* Unified fill pipeline — shared orchestration for all three fill paths
* (bundled templates, external/vendored, and fieldSelectors).
*
* Each path is now a thin wrapper that builds PipelineOptions and calls
* runFillPipeline(). The data-prep and fill steps come from fill-pipeline.ts;
* this module handles the surrounding orchestration: temp dir, copy, clean→patch,
* selections, fill, verify, cleanup.
*/
import { type ConfirmClauseDescriptor } from './fill-pipeline.js';
import { type FieldSelectorManifest, type FieldResolution } from './selectors/index.js';
import type { FieldDefinition, CleanConfig } from './metadata.js';
import type { SelectionsConfig } from './selector.js';
import type { VerifyResult } from './field-selector/types.js';
import { type ReferenceFieldsConfig } from './field-selector/reference-fields.js';
export interface PipelineOptions {
inputPath: string;
outputPath: string;
values: Record<string, unknown>;
fields: FieldDefinition[];
priorityFieldNames?: string[];
cleanPatch?: {
cleanConfig: CleanConfig;
replacements: Record<string, string | {
value: string;
format?: Record<string, unknown>;
}>;
};
selectorManifests?: FieldSelectorManifest[];
onSelectorResolved?: (fields: FieldResolution[]) => void;
selectionsConfig?: SelectionsConfig;
/**
* What to do when an UNSELECTED selections option matches zero paragraphs
* inside a group whose other options DID match (#720): the alternative that
* was meant to be removed is still in the document, so the output carries
* both alternatives.
*
* `'warn'` (default) reports it in `PipelineResult.warnings`; `'error'`
* rejects the fill. The default is `'warn'` only because the bundled
* `templates/` corpus carries three pre-existing marker mismatches this repo
* cannot fix (see the note at the call site) — it is not a judgement that the
* condition is acceptable.
*/
selectionsZeroMatchPolicy?: 'error' | 'warn';
coerceBooleans?: boolean;
computeDisplayFields?: (data: Record<string, unknown>) => void;
confirmClauses?: ConfirmClauseDescriptor[];
fixSmartQuotes?: boolean;
verify: (outputPath: string, cleanedSourcePath?: string, referencedFields?: Set<string>) => VerifyResult | Promise<VerifyResult>;
/**
* Structural source transformation that must run after cleaning but before
* selector/legacy scalar patching. Generated content must contain no fill
* commands because command analysis and filling happen later.
*/
prePatchProcess?: (inputPath: string, outputPath: string) => void | Promise<void>;
/** Target-driven, assertion-guarded REF-field structural actions. */
referenceFieldsConfig?: ReferenceFieldsConfig;
postProcess?: (outputPath: string) => void | Promise<void>;
keepIntermediate?: boolean;
}
export interface PipelineResult {
outputPath: string;
/**
* Prepared data keys that are actually referenced by a fill command
* ({field}, {IF field}, {FOR x IN field}) in the final pre-fill document.
* Includes blank-defaulted fields (they genuinely substitute an empty
* placeholder); excludes caller-supplied keys the document never consumes.
*/
fieldsUsed: string[];
/** Subset of fieldsUsed whose values the caller actually supplied. */
providedFieldsUsed: string[];
/** Fill commands found in the final pre-fill document (post clean/patch/selections). */
fillCommandCount: number;
/**
* Structured guardrail warnings for callers (CLI/API/MCP): zero-fill-command
* documents, unexpected zero-match patch keys, failed verification checks.
* Other advisory console output (priority fields, selector warnings) intentionally
* stays console-only for now.
*/
warnings: string[];
stages?: {
clean: string;
patch: string;
fill: string;
};
}
/**
* Run the unified fill pipeline:
* 1. Create temp dir
* 2. Copy inputPath → temp source.docx
* 3. If cleanPatch: clean → patch
* 4. prepareFillData (useBlankPlaceholder: true)
* 5. If selectionsConfig: apply selections
* 6. fillDocx → temp filled.docx
* 7. Copy filled.docx → outputPath
* 8. Run verify(outputPath), warn on failures
* 9. Cleanup temp dir (unless keepIntermediate)
*/
export declare function runFillPipeline(options: PipelineOptions): Promise<PipelineResult>;
/**
* Close whitespace seams left by empty substitutions within text paragraphs:
* collapse doubled spaces and remove whitespace immediately before punctuation.
*
* Paragraphs containing Word field characters (w:fldChar) are skipped because
* getParagraphText treats field-code runs as empty, so "Page " + PAGE field +
* " of " looks like "Page of " and the replacement would delete the field run
* that sits between the two space-bearing runs.
*/
export declare function normalizeEmptyFillWhitespaceInDocx(docxPath: string): Promise<void>;
//# sourceMappingURL=unified-pipeline.d.ts.map