open-agreements
Version:
Open-source legal template filling CLI and library
190 lines • 9.16 kB
JavaScript
import { createHash } from 'node:crypto';
import { existsSync } from 'node:fs';
import canonicalizeModule from 'canonicalize/lib/canonicalize.js';
import { loadFieldSelectorMetadata, } from '../metadata.js';
import { loadComputedProfile } from './computed.js';
import { resolveFieldSelectorDir } from '../../utils/paths.js';
import { assertConditionalInputOwnership } from '../conditional-inputs.js';
import { typedFieldDefault } from '../field-defaults.js';
import { conditionalPredicates } from '../conditional-predicates.js';
import { INPUT_VALUE_FORMATS } from '../input-value-formats.js';
export const FIELD_SELECTOR_INPUT_SCHEMA_VERSION = 1;
export const FIELD_SELECTOR_SCHEMA_GENERATOR = 'open-agreements field-selector schema';
const SERIES_DESIGNATION_FIELD = /(?:^|_)series_designation$/;
const PERCENTAGE_FIELD = /(?:^|_)(?:percent|percentage)$/;
const PERCENTAGE_DESCRIPTION = /\bpercentage\b/i;
/**
* Legal value shapes whose surrounding prose is owned by the source form.
*
* Series tokens use a stable field-name contract. Percentage inputs use either
* that name contract or an explicit percentage declaration in canonical field
* metadata (for example `redemption_interest_rate`). The same helper drives
* both the published JSON Schema and the pre-fill runtime check, so callers
* cannot pass a rendered phrase or punctuation that the form adds again.
*/
export function fieldValuePattern(field) {
if (field.type !== 'string')
return undefined;
if (field.value_format)
return INPUT_VALUE_FORMATS[field.value_format].pattern;
if (SERIES_DESIGNATION_FIELD.test(field.name)) {
// A designation is one token (A, B, C, Seed, A-1), never "Series A
// Preferred Stock". Empty remains valid for conditional/optional fields.
return '^(?:|[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)$';
}
if (PERCENTAGE_FIELD.test(field.name) || PERCENTAGE_DESCRIPTION.test(field.description)) {
// The source owns the percent sign. Accept a bare decimal from 0 through
// 100, or empty for a conditional/optional field.
return '^(?:|100(?:\\.0+)?|(?:\\d|[1-9]\\d)(?:\\.\\d+)?)$';
}
return undefined;
}
function assertValueShapes(values, fields, path = '') {
for (const field of fields) {
const value = values[field.name];
if (value === undefined)
continue;
const fieldPath = path ? `${path}.${field.name}` : field.name;
const pattern = fieldValuePattern(field);
if (pattern && (typeof value !== 'string' || !new RegExp(pattern).test(value))) {
const expectation = field.value_format ? INPUT_VALUE_FORMATS[field.value_format].expectation : SERIES_DESIGNATION_FIELD.test(field.name)
? 'a designation token such as A, B, or C (not a rendered stock name)'
: 'a number-only percentage from 0 through 100 without a percent sign';
throw new Error(`Invalid field-selector input at "${fieldPath}": expected ${expectation}`);
}
if (field.type === 'array' && Array.isArray(value)) {
value.forEach((row, index) => {
if (row && typeof row === 'object' && !Array.isArray(row)) {
assertValueShapes(row, field.items ?? [], `${fieldPath}[${index}]`);
}
});
}
}
}
/** Fail malformed source-owned token/sigil values before any document work. */
export function assertFieldSelectorInputValueShapes(values, fields) {
assertValueShapes(values, fields);
}
/** Return every metadata field owned by computed.json rather than the caller. */
export function computedFieldNames(profile) {
const names = new Set();
if (!profile)
return names;
for (const name of Object.keys(profile.defaults))
names.add(name);
for (const rule of profile.rules) {
for (const name of Object.keys(rule.set_fill))
names.add(name);
for (const name of Object.keys(rule.set_audit))
names.add(name);
}
return names;
}
function fieldSchema(field) {
const common = {
title: field.display_label ?? field.name,
description: field.description,
};
// Empty defaults are omitted from the schema annotation, even when the
// declared scalar default has meaning to a conditional controller.
const defaultValue = field.default === '' ? undefined : typedFieldDefault(field);
if (defaultValue !== undefined)
common.default = defaultValue;
const pattern = fieldValuePattern(field);
if (pattern)
common.pattern = pattern;
switch (field.type) {
case 'boolean': return { ...common, type: 'boolean' };
case 'number': return { ...common, type: 'number' };
case 'date': return { ...common, type: 'string', format: 'date' };
case 'enum': return { ...common, type: 'string', enum: [...(field.options ?? [])] };
case 'multiselect':
return {
...common,
type: 'array',
uniqueItems: true,
items: { type: 'string', enum: [...(field.options ?? [])] },
};
case 'array': {
const items = field.items ?? [];
return {
...common,
type: 'array',
items: {
type: 'object',
additionalProperties: false,
properties: Object.fromEntries(items.map((item) => [item.name, fieldSchema(item)])),
required: items.map((item) => item.name),
},
};
}
default: return { ...common, type: 'string' };
}
}
export function buildFieldSelectorInputSchema(fieldSelectorId, metadata, computedProfile) {
const computed = computedFieldNames(computedProfile);
assertConditionalInputOwnership(metadata.fields, computed);
const fields = metadata.fields.filter((field) => !computed.has(field.name));
const inputNames = new Set(fields.map((field) => field.name));
const required = metadata.priority_fields.filter((name) => inputNames.has(name));
const conditions = fields.filter((field) => field.required_when).map((field) => {
const condition = field.required_when;
const predicates = conditionalPredicates(condition).map(predicate => {
const controller = fields.find((candidate) => candidate.name === predicate.field);
if (!controller)
throw new Error(`required_when controller "${predicate.field}" must be a caller input`);
const usesDefault = typedFieldDefault(controller) === predicate.equals;
return {
properties: { [predicate.field]: { const: predicate.equals } },
// Without a matching controller default, omission must not vacuously
// activate the condition. JSON Schema does not apply defaults itself.
...(!usesDefault ? { required: [predicate.field] } : {}),
};
});
return {
if: 'all_of' in condition ? { allOf: predicates } : predicates[0],
then: {
required: [field.name],
properties: {
[field.name]: ['string', 'enum', 'date'].includes(field.type)
? { type: 'string', pattern: '\\S' } : { type: field.type },
},
},
};
});
return {
$schema: 'https://json-schema.org/draft/2020-12/schema',
$id: `https://openagreements.org/schemas/field-selector/${fieldSelectorId}.schema.json`,
title: `${metadata.name} input`,
description: metadata.description ?? `Canonical caller-supplied fields for ${metadata.name}.`,
type: 'object',
additionalProperties: false,
properties: Object.fromEntries(fields.map((field) => [field.name, fieldSchema(field)])),
required,
...(conditions.length ? { allOf: conditions } : {}),
'x-openagreements': {
field_selector_id: fieldSelectorId,
source_version: metadata.source_version,
generator: FIELD_SELECTOR_SCHEMA_GENERATOR,
schema_version: FIELD_SELECTOR_INPUT_SCHEMA_VERSION,
},
};
}
export function getFieldSelectorInputSchema(fieldSelectorId, fieldSelectorDir = resolveFieldSelectorDir(fieldSelectorId)) {
if (!existsSync(fieldSelectorDir))
throw new Error(`Unknown field-selector "${fieldSelectorId}"`);
const metadata = loadFieldSelectorMetadata(fieldSelectorDir);
return buildFieldSelectorInputSchema(fieldSelectorId, metadata, loadComputedProfile(fieldSelectorDir));
}
export function canonicalJson(value) {
// canonicalize is CommonJS at runtime despite shipping an ESM-shaped .d.ts.
const serialize = canonicalizeModule;
const result = serialize(value);
if (result === undefined)
throw new Error('Value cannot be represented as canonical JSON');
return result;
}
export function canonicalSha256(value) {
return createHash('sha256').update(canonicalJson(value)).digest('hex');
}
//# sourceMappingURL=input-schema.js.map