UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

382 lines • 19.4 kB
import { readdirSync, existsSync, readFileSync } from 'node:fs'; import { join } from 'node:path'; import { validateFieldSelectorMetadata, loadFieldSelectorMetadata } from '../metadata.js'; import { CleanConfigSchema } from '../metadata.js'; import { NormalizeConfigSchema } from '../metadata.js'; import { parseReplacementKey } from '../field-selector/replacement-keys.js'; import { ComputedProfileSchema } from '../field-selector/computed.js'; import { SelectionsConfigSchema } from '../selector.js'; import { loadSelectorContracts } from '../selectors/loader.js'; import { AnchoredParagraphBindingsConfigSchema } from '../field-selector/anchored-paragraph-bindings.js'; import { RepeatableTablesConfigSchema } from '../field-selector/repeatable-tables.js'; import { ReferenceFieldsConfigSchema } from '../field-selector/reference-fields.js'; /** Pattern for valid template tags within replacement values */ const TAG_RE = /\{[a-z_][a-z0-9_]*\}/g; /** Pattern for any curly-brace token (to detect control tags) */ const ANY_BRACE_RE = /\{[^}]+\}/g; /** Only simple identifiers inside braces are allowed */ const SAFE_TAG_RE = /^\{[a-z_][a-z0-9_]*\}$/; /** * Validate a fieldSelector directory: * - No .docx files (copyrighted content must not be committed) * - metadata.yaml validates against schema * - For non-scaffold fieldSelectors: replacements.json present and valid * - Replacement values may be literal text, empty cleanup replacements, or * valid {identifier} tags * - In strict mode: scaffolds are errors, all files required */ export function validateFieldSelector(fieldSelectorDir, fieldSelectorId, options) { const errors = []; const warnings = []; const strict = options?.strict ?? false; // Check for .docx files (forbidden in fieldSelector dirs) const files = readdirSync(fieldSelectorDir); const docxFiles = files.filter((f) => f.toLowerCase().endsWith('.docx')); if (docxFiles.length > 0) { errors.push(`Copyrighted .docx file(s) found: ${docxFiles.join(', ')}. FieldSelectors must not contain source documents.`); } // Validate metadata const metaResult = validateFieldSelectorMetadata(fieldSelectorDir); if (!metaResult.valid) { errors.push(...metaResult.errors.map((e) => `metadata: ${e}`)); return { fieldSelectorId, valid: false, scaffold: false, errors, warnings }; } // Scaffold detection: if only metadata.yaml exists, this is a scaffold const metadata = loadFieldSelectorMetadata(fieldSelectorDir); const metadataFieldNames = new Set(metadata.fields.map((field) => field.name)); const computedPath = join(fieldSelectorDir, 'computed.json'); const hasReplacements = existsSync(join(fieldSelectorDir, 'replacements.json')); const isScaffold = !hasReplacements; // Inputs for the binding-reachability rule (issue #621). Any parse failure // below records its own error and clears this flag so the reachability rule // does not cascade spurious "unbound field" errors on top of a parse error. let reachabilityInputsOk = true; let computedProfile; let normalizeConfig; let selectionsConfig; let anchoredBindingsConfig; let repeatableTablesConfig; let replacementsRecord; /** Field names referenced by at least one {tag} in a replacements.json value. */ const replacementBoundFields = new Set(); // Validate computed.json if present let computedSetFillFields; if (existsSync(computedPath)) { try { const raw = readFileSync(computedPath, 'utf-8'); const profile = ComputedProfileSchema.parse(JSON.parse(raw)); computedProfile = profile; // Collect all fields targeted by defaults or set_fill rules computedSetFillFields = new Set(); for (const field of Object.keys(profile.defaults)) { computedSetFillFields.add(field); } for (const rule of profile.rules) { for (const field of Object.keys(rule.set_fill)) { computedSetFillFields.add(field); } } // Validate: computed set_fill fields must not have non-empty metadata defaults. // When computed.json owns a field, metadata should declare default: "" (or omit it) // so that the computed rule is the single source of truth for that field's value. for (const field of computedSetFillFields) { const metaField = metadata.fields.find((f) => f.name === field); if (metaField && metaField.default !== undefined && metaField.default !== '') { errors.push(`computed/metadata conflict: field "${field}" is set by computed.json set_fill ` + `but has non-empty metadata default "${metaField.default}". ` + `Computed-owned fields must use default: "" to avoid conflicting values.`); } } } catch (err) { const message = err instanceof Error ? err.message : 'invalid format'; errors.push(`computed.json: ${message}`); reachabilityInputsOk = false; } } if (isScaffold) { if (strict) { errors.push('Scaffold fieldSelector (metadata-only): not runnable. Use non-strict mode to allow scaffolds.'); } else { warnings.push('Scaffold fieldSelector (metadata-only): not runnable'); } return { fieldSelectorId, valid: errors.length === 0, scaffold: true, errors, warnings }; } // Validate replacements.json for runnable fieldSelectors. try { const raw = readFileSync(join(fieldSelectorDir, 'replacements.json'), 'utf-8'); const replacements = JSON.parse(raw); if (typeof replacements !== 'object' || replacements === null) { errors.push('replacements.json must be a JSON object'); reachabilityInputsOk = false; } else { replacementsRecord = replacements; const unknownTargets = new Set(); for (const [key, rawValue] of Object.entries(replacements)) { // Value can be a string or { value: string, format?: object } let value; if (typeof rawValue === 'string') { value = rawValue; } else if (typeof rawValue === 'object' && rawValue !== null && typeof rawValue.value === 'string') { value = rawValue.value; } else { errors.push(`replacements.json: value for "${key}" must be a string or { value: string, format?: object }`); continue; } // All curly-brace tokens in value must be safe identifiers (no control tags) const allBraces = value.match(ANY_BRACE_RE); if (allBraces) { for (const token of allBraces) { if (!SAFE_TAG_RE.test(token)) { errors.push(`replacements.json: unsafe tag "${token}" in value for "${key}". Only {identifier} tags allowed.`); continue; } const fieldName = token.slice(1, -1); replacementBoundFields.add(fieldName); if (!metadataFieldNames.has(fieldName)) { unknownTargets.add(fieldName); } } } // Value must not contain the source key (infinite loop prevention) // For qualified keys, check against the searchText, not the full key. const parsed = parseReplacementKey(key, value); if (parsed.type === 'simple' && value.includes(parsed.searchText)) { errors.push(`replacements.json: value for "${key}" contains the key itself (would cause infinite loop)`); } else if (parsed.type === 'context' && value.includes(parsed.searchText)) { errors.push(`replacements.json: value for "${key}" contains the search text "${parsed.searchText}" (would cause infinite loop)`); } } for (const fieldName of unknownTargets) { warnings.push(`Replacement target {${fieldName}} not found in metadata fields`); } } } catch (err) { errors.push(`replacements.json: ${err.message}`); reachabilityInputsOk = false; } // Validate clean.json if present const referenceFieldsPath = join(fieldSelectorDir, 'reference-fields.json'); if (existsSync(referenceFieldsPath)) { try { ReferenceFieldsConfigSchema.parse(JSON.parse(readFileSync(referenceFieldsPath, 'utf-8'))); } catch (err) { errors.push(`reference-fields.json: ${err instanceof Error ? err.message : 'invalid format'}`); } } // Validate clean.json if present const cleanPath = join(fieldSelectorDir, 'clean.json'); if (existsSync(cleanPath)) { try { const raw = readFileSync(cleanPath, 'utf-8'); CleanConfigSchema.parse(JSON.parse(raw)); } catch { errors.push(`clean.json: invalid format`); } } // Validate normalize.json if present const normalizePath = join(fieldSelectorDir, 'normalize.json'); if (existsSync(normalizePath)) { try { const raw = readFileSync(normalizePath, 'utf-8'); normalizeConfig = NormalizeConfigSchema.parse(JSON.parse(raw)); } catch { errors.push('normalize.json: invalid format'); reachabilityInputsOk = false; } } // Validate selections.json if present (needed as a reachability input: // a selections trigger is a document-affecting binding). const selectionsPath = join(fieldSelectorDir, 'selections.json'); if (existsSync(selectionsPath)) { try { const raw = readFileSync(selectionsPath, 'utf-8'); selectionsConfig = SelectionsConfigSchema.parse(JSON.parse(raw)); } catch { errors.push('selections.json: invalid format'); reachabilityInputsOk = false; } } const anchoredBindingsPath = join(fieldSelectorDir, 'anchored-paragraph-bindings.json'); if (existsSync(anchoredBindingsPath)) { try { anchoredBindingsConfig = AnchoredParagraphBindingsConfigSchema.parse(JSON.parse(readFileSync(anchoredBindingsPath, 'utf-8'))); } catch { errors.push('anchored-paragraph-bindings.json: invalid format'); reachabilityInputsOk = false; } } const repeatableTablesPath = join(fieldSelectorDir, 'repeatable-tables.json'); if (existsSync(repeatableTablesPath)) { try { repeatableTablesConfig = RepeatableTablesConfigSchema.parse(JSON.parse(readFileSync(repeatableTablesPath, 'utf-8'))); } catch { errors.push('repeatable-tables.json: invalid format'); reachabilityInputsOk = false; } } // Load selector contracts (fields/*.json + template-manifest.json). The // loader schema already enforces that every recipe declares at least one // occurrence locator, so a loaded recipe is a nonempty selector manifest. let selectorRecipeFields = new Set(); let migratedKeys = []; let contractsOk = true; try { const { manifests, templateManifest } = loadSelectorContracts(fieldSelectorDir, metadataFieldNames); selectorRecipeFields = new Set(manifests.map((m) => m.field_id)); migratedKeys = templateManifest?.migrated_keys ?? []; } catch (err) { errors.push(`selector contracts: ${err.message}`); reachabilityInputsOk = false; contractsOk = false; } // --- Binding reachability (issue #621) --- // Every field published in metadata.yaml must reach a document-affecting // binding: metadata field → (optional computed.json transformation chain) → // terminal binding, where a terminal binding is a replacements.json value // {tag}, a fields/<name>.json selector recipe, a selections.json trigger, // or a normalize.json replacement value {tag}. A field mentioned only in a // computed predicate whose rule leads nowhere, or only in an audit-only // (set_audit) assignment, is NOT reachable. if (reachabilityInputsOk && replacementsRecord) { const reachable = new Set(replacementBoundFields); for (const fieldId of selectorRecipeFields) { reachable.add(fieldId); } if (selectionsConfig) { for (const group of selectionsConfig.groups) { for (const option of group.options) { if (typeof option.trigger === 'object' && option.trigger !== null) { reachable.add(option.trigger.field); } if (option.replaceWith) { for (const tag of option.replaceWith.match(TAG_RE) ?? []) { reachable.add(tag.slice(1, -1)); } } } } } if (normalizeConfig) { for (const rule of normalizeConfig.paragraph_rules) { for (const value of Object.values(rule.replacements ?? {})) { for (const tag of value.match(TAG_RE) ?? []) { reachable.add(tag.slice(1, -1)); } } } } for (const group of anchoredBindingsConfig?.groups ?? []) { for (const binding of group.bindings) reachable.add(binding.field); } for (const table of repeatableTablesConfig?.tables ?? []) { reachable.add(table.rows_field); } // Propagate reachability backwards through computed.json to a fixpoint. // A rule with at least one reachable set_fill target makes two kinds of // inputs document-affecting: // 1. the fields its when_all/when_any predicates read (they gate the // assignment), and // 2. the fields referenced via ${name} interpolation inside a REACHABLE // target's assigned value (the evaluator's interpolate() substitutes // them into the value that reaches the document). // set_audit assignments do not propagate (audit-only), interpolation refs // in an UNreachable target's value do not count, and defaults are applied // verbatim (never interpolated), so they have no input fields to propagate to. if (computedProfile) { let changed = true; while (changed) { changed = false; for (const rule of computedProfile.rules) { const reachableAssignments = Object.entries(rule.set_fill) .filter(([target]) => reachable.has(target)); if (reachableAssignments.length === 0) continue; for (const predicate of [...rule.when_all, ...rule.when_any]) { if (!reachable.has(predicate.field)) { reachable.add(predicate.field); changed = true; } } for (const [, assigned] of reachableAssignments) { if (typeof assigned !== 'string') continue; for (const match of assigned.matchAll(/\$\{([A-Za-z0-9_]+)\}/g)) { if (!reachable.has(match[1])) { reachable.add(match[1]); changed = true; } } } } } } // Only top-level metadata.fields are checked: nested `items` sub-fields // exist for {FOR}-loop collections in ordinary redistributable templates // (validated by validation/template.ts) and are not independently bindable // field-selector inputs — a field-selector binds the collection field's // own {tag}, which this loop covers. for (const field of metadata.fields) { if (!reachable.has(field.name)) { errors.push(`unbound field "${field.name}": published in metadata.yaml but reaches no ` + `document-affecting binding (no replacements.json value tag, ` + `fields/${field.name}.json selector recipe, selections.json trigger, ` + `normalize.json replacement tag, or computed.json chain ending in one). ` + `Wire it to a binding or unpublish it (issue #621).`); } } } // --- Migrated-key integrity (issue #621, stricter selector-template rule) --- // Every template-manifest.json migrated key must (a) exist in // replacements.json and (b) map to a field with a nonempty selector // manifest — otherwise the key is withheld from the legacy patcher but no // selector recipe writes it, so the fill silently no-ops (#607 class). if (contractsOk && replacementsRecord) { for (const key of migratedKeys) { const rawValue = replacementsRecord[key]; if (rawValue === undefined) { errors.push(`template-manifest.json: migrated key "${key}" not found in replacements.json — ` + `the selector engine owns a key that no replacement declares`); continue; } const value = typeof rawValue === 'string' ? rawValue : (typeof rawValue === 'object' && rawValue !== null && typeof rawValue.value === 'string' ? rawValue.value : undefined); if (value === undefined) continue; // malformed value already reported above const tagFields = (value.match(TAG_RE) ?? []).map((tag) => tag.slice(1, -1)); // Literal and empty replacements are handled by the legacy patcher and // therefore have no selector field whose ownership can be checked. if (tagFields.length === 0) continue; const missingRecipes = tagFields.filter((f) => !selectorRecipeFields.has(f)); for (const fieldName of missingRecipes) { errors.push(`template-manifest.json: migrated key "${key}" maps to field "${fieldName}" ` + `which has no fields/${fieldName}.json selector recipe — the key is withheld ` + `from the legacy patcher but nothing else writes it`); } } } // Warn if source_sha256 is missing (fill will skip integrity verification) if (!metadata.source_sha256) { warnings.push('No source_sha256 in metadata — fill will skip integrity verification'); } return { fieldSelectorId, valid: errors.length === 0, scaffold: false, errors, warnings }; } //# sourceMappingURL=field-selector.js.map