open-agreements
Version:
Open-source legal template filling CLI and library
285 lines • 16.5 kB
JavaScript
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