UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

285 lines • 16.5 kB
import { existsSync, readFileSync } from 'node:fs'; import { join } from 'node:path'; import { loadFieldSelectorMetadata, loadCleanConfig, loadNormalizeConfig } from '../metadata.js'; import { loadSelectionsConfig } from '../selector.js'; import { resolveFieldSelectorDir } from '../../utils/paths.js'; import { verifyOutput, extractAllText } from './verifier.js'; import { extractSearchText } from './replacement-keys.js'; import { loadSelectorContracts, evaluatePostconditions } from '../selectors/index.js'; import { ensureSourceDocx } from './downloader.js'; import { loadComputedProfile, evaluateComputedProfile, buildComputedArtifact, buildPassthroughArtifact, writeComputedArtifact, } from './computed.js'; import { normalizeBracketArtifacts } from './bracket-normalizer.js'; import { normalizeDetachedHeadingPunctuation } from './heading-punctuation-normalizer.js'; import { runFillPipeline } from '../unified-pipeline.js'; import { formatDocumentDate, formatDocumentDateFields } from '../fill-pipeline.js'; import { applyRepeatableTables, loadRepeatableTablesConfig, validateRepeatableTableFields } from './repeatable-tables.js'; import { bindAnchoredParagraphFields, loadAnchoredParagraphBindingsConfig } from './anchored-paragraph-bindings.js'; import { normalizeNumberedHeadingSections } from './numbering-normalizer.js'; import { validateNumberingContinuationSource } from './numbering-continuations.js'; import { loadReferenceFieldsConfig } from './reference-fields.js'; import { assertFieldSelectorInputValueShapes, computedFieldNames } from './input-schema.js'; import { assertConditionalInputOwnership, assertConditionalRequiredInputs } from '../conditional-inputs.js'; import { preparedFieldDefault } from '../field-defaults.js'; function toComputedValueMap(values) { const computedValues = {}; for (const [key, value] of Object.entries(values)) { if (typeof value === 'string' || typeof value === 'boolean') { computedValues[key] = value; continue; } if (Array.isArray(value) && value.every((entry) => typeof entry === 'string')) { computedValues[key] = [...value]; } } return computedValues; } /** * Run the full fieldSelector pipeline: clean → patch → fill → verify. * If no inputPath is provided, auto-downloads the source document from source_url. */ export async function runFieldSelector(options) { const { fieldSelectorId, outputPath, values, keepIntermediate, computedOutPath } = options; const fieldSelectorDir = resolveFieldSelectorDir(fieldSelectorId); const metadata = loadFieldSelectorMetadata(fieldSelectorDir); const computedProfile = loadComputedProfile(fieldSelectorDir); assertConditionalInputOwnership(metadata.fields, computedFieldNames(computedProfile)); assertConditionalRequiredInputs(values, metadata.fields); // Validate source-owned token/sigil shapes before downloading, cleaning, or // writing a document. The exported caller schema uses the same constraints. assertFieldSelectorInputValueShapes(values, metadata.fields); const cleanConfig = loadCleanConfig(fieldSelectorDir); const normalizeConfig = loadNormalizeConfig(fieldSelectorDir); const repeatableTablesConfig = loadRepeatableTablesConfig(fieldSelectorDir); if (repeatableTablesConfig) validateRepeatableTableFields(repeatableTablesConfig, metadata.fields); const anchoredBindingsPath = join(fieldSelectorDir, 'anchored-paragraph-bindings.json'); const anchoredParagraphBindingsConfig = existsSync(anchoredBindingsPath) ? loadAnchoredParagraphBindingsConfig(anchoredBindingsPath) : undefined; const referenceFieldsConfig = loadReferenceFieldsConfig(join(fieldSelectorDir, 'reference-fields.json')); // Load selectionsConfig if selections.json exists (mirrors engine.ts template path) const selectionsPath = join(fieldSelectorDir, 'selections.json'); const selectionsConfig = existsSync(selectionsPath) ? loadSelectionsConfig(selectionsPath) : undefined; // Resolve input: explicit path or auto-download const inputPath = options.inputPath ?? await ensureSourceDocx(fieldSelectorId, metadata); const numberingContinuationPlan = normalizeConfig.numbering_continuations ? validateNumberingContinuationSource(inputPath, normalizeConfig.numbering_continuations) : undefined; // Load replacements.json const replacementsPath = join(fieldSelectorDir, 'replacements.json'); const replacements = JSON.parse(readFileSync(replacementsPath, 'utf-8')); const replacementFieldNames = new Set(); for (const rawReplacement of Object.values(replacements)) { const replacement = typeof rawReplacement === 'string' ? rawReplacement : rawReplacement.value; for (const match of replacement.matchAll(/\{([a-zA-Z0-9_]+)\}/g)) { replacementFieldNames.add(match[1]); } } // Selector contracts (opt-in per field via fields/<field_id>.json). The // declarative migrated_keys list — NOT inference — determines which legacy // keys the selector engine owns. Those are removed from the dict handed to // the legacy patcher only; the verifier still receives the FULL key set. const metadataFieldNames = metadata.fields.map((f) => f.name); const { manifests: selectorManifests, templateManifest } = loadSelectorContracts(fieldSelectorDir, metadataFieldNames); const migratedKeys = new Set(templateManifest?.migrated_keys ?? []); const patchReplacements = {}; for (const [key, value] of Object.entries(replacements)) { if (migratedKeys.has(key)) continue; patchReplacements[key] = value; } // Map each selector field to the source anchors of its migrated keys // (for the all_occurrences_identical postcondition). const migratedAnchorsByField = {}; for (const key of migratedKeys) { const raw = replacements[key]; if (raw === undefined) continue; const valueStr = typeof raw === 'string' ? raw : raw.value; const fieldMatch = valueStr.match(/\{([a-zA-Z0-9_]+)\}/); if (!fieldMatch) continue; const fieldId = fieldMatch[1]; (migratedAnchorsByField[fieldId] ??= []).push(extractSearchText(key)); } // Computed prose may interpolate source date fields. Normalize declared date // values before computed evaluation so both direct tags and derived prose see // the same display-ready value (and chained computed fields inherit it). // Computed prose must see the same declared caller defaults as direct tags. // Do not seed placeholders or computed-owned fields: their profile defaults // and rules retain authority. Explicit values (including blanks) stay intact. const defaultedValues = { ...values }; const materializedDefaultFields = new Set(); const computedOwnedFields = computedFieldNames(computedProfile); for (const field of metadata.fields) { if (field.name in defaultedValues || field.default === undefined || computedOwnedFields.has(field.name)) continue; defaultedValues[field.name] = preparedFieldDefault(field); materializedDefaultFields.add(field.name); } const inputValues = formatDocumentDateFields(defaultedValues, metadata.fields); const computedInputValues = toComputedValueMap(inputValues); const computedEvaluation = computedProfile ? evaluateComputedProfile(computedProfile, computedInputValues) : null; const mergedValues = computedEvaluation ? { ...inputValues, ...computedEvaluation.fillValues } : inputValues; // Computed rules may populate a date-typed field. Apply the same strict // formatting/validation boundary to derived values as direct inputs before // writing either the computed trace or the document output. const effectiveValues = formatDocumentDateFields(mergedValues, metadata.fields); const verificationValues = {}; for (const field of metadata.fields) { if (!replacementFieldNames.has(field.name)) { continue; } const value = effectiveValues[field.name]; if (typeof value === 'string') { // Mirror prepareFillData's date handling: `type: date` fields render ISO // input as a document date ("2026-07-15" → "July 15, 2026"), so verify // against the formatted value actually written to the output — otherwise // every ISO-supplied date field reports a spurious "Missing" warning. verificationValues[field.name] = field.type === 'date' ? formatDocumentDate(value) : value; } } const computedArtifact = computedEvaluation && computedProfile ? buildComputedArtifact({ fieldSelectorId, inputValues: computedInputValues, evaluated: computedEvaluation, profileVersion: computedProfile.version, }) : (computedOutPath ? buildPassthroughArtifact({ fieldSelectorId, inputValues: computedInputValues }) : undefined); if (computedOutPath && computedArtifact) { writeComputedArtifact(computedOutPath, computedArtifact); } const shouldNormalizeBracketArtifacts = options.normalizeBracketArtifacts ?? normalizeConfig.paragraph_rules.length > 0; const result = await runFillPipeline({ inputPath, outputPath, values: effectiveValues, fields: metadata.fields, priorityFieldNames: metadata.priority_fields, cleanPatch: { cleanConfig, replacements: patchReplacements }, selectorManifests, selectionsConfig, selectionsZeroMatchPolicy: options.selectionsZeroMatchPolicy, prePatchProcess: repeatableTablesConfig || anchoredParagraphBindingsConfig ? async (inputDocPath, outputDocPath) => { if (repeatableTablesConfig && anchoredParagraphBindingsConfig) { const repeatablePath = `${outputDocPath}.repeatable.docx`; applyRepeatableTables(inputDocPath, repeatablePath, repeatableTablesConfig, effectiveValues); bindAnchoredParagraphFields(repeatablePath, outputDocPath, anchoredParagraphBindingsConfig); } else if (repeatableTablesConfig) { applyRepeatableTables(inputDocPath, outputDocPath, repeatableTablesConfig, effectiveValues); } else if (anchoredParagraphBindingsConfig) { bindAnchoredParagraphFields(inputDocPath, outputDocPath, anchoredParagraphBindingsConfig); } } : undefined, referenceFieldsConfig, postProcess: shouldNormalizeBracketArtifacts || numberingContinuationPlan ? async (outputDocPath) => { if (numberingContinuationPlan) normalizeNumberedHeadingSections(outputDocPath, outputDocPath, numberingContinuationPlan); else normalizeNumberedHeadingSections(outputDocPath, outputDocPath); if (shouldNormalizeBracketArtifacts) { await normalizeBracketArtifacts(outputDocPath, outputDocPath, { rules: normalizeConfig.paragraph_rules, fieldValues: effectiveValues, }); } normalizeDetachedHeadingPunctuation(outputDocPath, outputDocPath); } : undefined, verify: async (p, cleanedSourcePath, referencedFields) => { // Verifier receives the FULL replacements key set (incl. migrated keys) so // a selector occurrence that failed to fill is still caught as a leftover // source placeholder — coverage is preserved after migration. // cleanedSourcePath baselines pre-existing formatting anomalies so only // fill-introduced ones are reported. // // Selection-aware value verification (#619): a supplied field whose ONLY // fill site lived in an alternative that selections.json removed (e.g. // arbitration_location in courts mode) is not in the final pre-fill // document, so its value legitimately never renders — checking it would // emit a false "Missing" warning. Restrict value-presence checks to // fields the post-selection document actually references, plus fields a // normalize.json rule writes post-fill (their values render without a // {tag} in the pre-fill buffer). const normalizeRuleFields = new Set(); for (const rule of normalizeConfig.paragraph_rules) { for (const template of Object.values(rule.replacements ?? {})) { for (const match of template.matchAll(/\{([a-zA-Z0-9_]+)\}/g)) { normalizeRuleFields.add(match[1]); } } } const activeVerificationValues = referencedFields ? Object.fromEntries(Object.entries(verificationValues).filter(([field]) => referencedFields.has(field) || normalizeRuleFields.has(field))) : verificationValues; const base = await verifyOutput(p, activeVerificationValues, replacements, cleanConfig, cleanedSourcePath); if (selectorManifests.length === 0) return base; const fieldValues = {}; for (const manifest of selectorManifests) { const v = effectiveValues[manifest.field_id]; if (typeof v === 'string') fieldValues[manifest.field_id] = v; } const postconditionChecks = evaluatePostconditions({ outputText: extractAllText(p), manifests: selectorManifests, fieldValues, migratedAnchorsByField, }); return { passed: base.passed && postconditionChecks.every((c) => c.passed), checks: [...base.checks, ...postconditionChecks], }; }, keepIntermediate, }); // Preserve the existing caller attribution: newly materialized metadata // defaults are effective inputs, not explicitly provided values. Computed // outputs retain their historical attribution behavior. const providedFieldsUsed = result.providedFieldsUsed.filter((field) => !materializedDefaultFields.has(field)); return { outputPath: result.outputPath, metadata, fieldsUsed: repeatableTablesConfig ? [...new Set([...result.fieldsUsed, ...repeatableTablesConfig.tables.map((table) => table.rows_field)])] : result.fieldsUsed, providedFieldsUsed: repeatableTablesConfig ? [...new Set([ ...providedFieldsUsed, ...repeatableTablesConfig.tables .map((table) => table.rows_field) .filter((field) => Object.hasOwn(values, field)), ])] : providedFieldsUsed, fillCommandCount: result.fillCommandCount, warnings: result.warnings, stages: result.stages, computedArtifact, computedOutPath, }; } export { cleanDocument } from './cleaner.js'; export { patchDocument } from './patcher.js'; export { verifyOutput, validateWordFields, normalizeText, extractAllText, countFormattingAnomalies } from './verifier.js'; export { ensureSourceDocx } from './downloader.js'; export { checkFieldSelectorSourceDrift, checkSelectorDrift, computeSourceStructureSignature } from './source-drift.js'; export { enumerateTextParts, getGeneralTextPartNames } from './ooxml-parts.js'; export { applyRepeatableTables, loadRepeatableTablesConfig, RepeatableTablesConfigSchema, validateRepeatableTableFields } from './repeatable-tables.js'; export { normalizeNumberedHeadingSections } from './numbering-normalizer.js'; export { bindAnchoredParagraphFields, loadAnchoredParagraphBindingsConfig, AnchoredParagraphBindingsConfigSchema } from './anchored-paragraph-bindings.js'; export { normalizeDetachedHeadingPunctuation } from './heading-punctuation-normalizer.js'; export { applyReferenceFieldActions, loadReferenceFieldsConfig, ReferenceFieldsConfigSchema } from './reference-fields.js'; //# sourceMappingURL=index.js.map