open-agreements
Version:
Open-source legal template filling CLI and library
363 lines • 20.3 kB
JavaScript
/**
* Pre-compile validation of a DocumentSpec.
*
* Two jobs:
* 1. Shape/referential checks for the spec subset whose emitters have shipped.
* 2. Loud rejection of declared-but-not-yet-implemented spec features. The
* type surface covers the full add-docx-generation change; emitters land
* in phases, and a spec feature without an emitter must fail compilation
* with a typed error naming the feature and its path — never be silently
* dropped (scenario SDX-GEN-003).
*
* Shipped so far: formatted text/tab/break runs, five-part PAGE/NUMPAGES
* fields, paragraph formatting, named styles + styles.xml, multi-section
* documents with per-section page setup, page numbering, break types,
* default/first/even headers and footers, tables (grid, spans, vertical
* merges, cell decoration, nesting), multi-level numbering with w:numPr
* list references, and drafting notes compiled to anchored comments (body
* story only — header/footer paragraphs cannot carry notes).
*
* Every declared feature now has an emitter; the loud-rejection contract
* (SDX-GEN-003) lives on as runtime guards against unrecognized block and
* inline kinds, which protect callers handing in JSON that the TypeScript
* surface never saw.
*/
import { GenerationSpecError } from './errors.js';
import { HIGHLIGHT_COLORS, NUMBERING_LEVEL_JUSTIFICATIONS, THEME_COLOR_SLOTS } from './types.js';
const COLOR_HEX_RE = /^[0-9A-Fa-f]{6}$/;
const TWO_HEX_RE = /^[0-9A-Fa-f]{2}$/;
const HIGHLIGHT_COLOR_SET = new Set(HIGHLIGHT_COLORS);
const LVL_JC_SET = new Set(NUMBERING_LEVEL_JUSTIFICATIONS);
const THEME_COLOR_SLOT_SET = new Set(THEME_COLOR_SLOTS);
function unsupported(path, feature) {
throw new GenerationSpecError('unsupported_feature', path, `Spec feature '${feature}' is declared in the DocumentSpec type surface but its emitter has not shipped yet; ` +
'it is rejected rather than silently ignored');
}
export function validateSpec(spec) {
if (!Array.isArray(spec.sections) || spec.sections.length === 0) {
throw new GenerationSpecError('empty_sections', '/sections', 'DocumentSpec.sections must contain at least one section');
}
validateTheme(spec);
const declaredStyleIds = validateStyles(spec.styles ?? []);
const numbering = validateNumbering(spec.numbering ?? []);
spec.sections.forEach((section, sectionIndex) => {
validateSection(section, `/sections/${sectionIndex}`, declaredStyleIds, numbering);
});
}
function validateTheme(spec) {
if (!spec.theme?.colors)
return;
for (const [slot, hex] of Object.entries(spec.theme.colors)) {
if (!THEME_COLOR_SLOT_SET.has(slot)) {
throw new GenerationSpecError('invalid_value', `/theme/colors/${slot}`, `theme color slot must be one of the supported theme slots, got '${slot}'`);
}
if (typeof hex !== 'string' || !COLOR_HEX_RE.test(hex)) {
throw new GenerationSpecError('invalid_value', `/theme/colors/${slot}`, `theme color value must be six hex digits without '#', got '${hex}'`);
}
}
}
/** Returns numId handle → set of declared levels, for list-reference checks. */
function validateNumbering(definitions) {
const declared = new Map();
definitions.forEach((definition, index) => {
const path = `/numbering/${index}`;
if (!definition.numId) {
throw new GenerationSpecError('invalid_value', `${path}/numId`, 'NumberingSpec requires a numId handle');
}
if (declared.has(definition.numId)) {
throw new GenerationSpecError('invalid_value', `${path}/numId`, `Duplicate numbering handle '${definition.numId}'`);
}
if (!Array.isArray(definition.levels) || definition.levels.length === 0) {
throw new GenerationSpecError('invalid_value', `${path}/levels`, 'Numbering definitions require at least one level');
}
const levels = new Set();
definition.levels.forEach((level, levelIndex) => {
const levelPath = `${path}/levels/${levelIndex}`;
if (!Number.isInteger(level.ilvl) || level.ilvl < 0 || level.ilvl > 8) {
throw new GenerationSpecError('invalid_value', `${levelPath}/ilvl`, 'ilvl must be an integer between 0 and 8');
}
if (levels.has(level.ilvl)) {
throw new GenerationSpecError('invalid_value', `${levelPath}/ilvl`, `Duplicate ilvl ${level.ilvl} in numbering '${definition.numId}'`);
}
levels.add(level.ilvl);
if (typeof level.lvlText !== 'string' || level.lvlText.length === 0) {
throw new GenerationSpecError('invalid_value', `${levelPath}/lvlText`, 'Numbering levels require a lvlText pattern');
}
if (level.start !== undefined && (!Number.isInteger(level.start) || level.start < 0)) {
throw new GenerationSpecError('invalid_value', `${levelPath}/start`, 'Level start must be a non-negative integer');
}
if (level.lvlJc !== undefined && !LVL_JC_SET.has(level.lvlJc)) {
throw new GenerationSpecError('invalid_value', `${levelPath}/lvlJc`, `lvlJc must be one of ${NUMBERING_LEVEL_JUSTIFICATIONS.join(', ')}, got '${level.lvlJc}'`);
}
if (level.runProps)
validateRunProps(level.runProps, `${levelPath}/runProps`);
});
declared.set(definition.numId, levels);
});
return declared;
}
/** Returns the set of resolvable style ids (declared styles + implicit Normal). */
function validateStyles(styles) {
const ids = new Set(['Normal']);
styles.forEach((style, index) => {
const path = `/styles/${index}`;
if (!style.styleId || !style.name) {
throw new GenerationSpecError('invalid_value', path, 'StyleSpec requires styleId and name');
}
if (ids.has(style.styleId)) {
throw new GenerationSpecError('invalid_value', `${path}/styleId`, `Duplicate styleId '${style.styleId}'`);
}
ids.add(style.styleId);
if (style.run)
validateRunProps(style.run, `${path}/run`);
});
// basedOn / next must resolve against the full declared set (forward refs allowed).
styles.forEach((style, index) => {
const path = `/styles/${index}`;
for (const key of ['basedOn', 'next']) {
const ref = style[key];
if (ref !== undefined && !ids.has(ref)) {
throw new GenerationSpecError('dangling_style_reference', `${path}/${key}`, `Style '${style.styleId}' references undeclared style '${ref}' via ${key}`);
}
}
});
return ids;
}
function validateSection(section, path, styleIds, numbering) {
if (section.pageNumbering?.start !== undefined) {
const start = section.pageNumbering.start;
if (!Number.isInteger(start) || start < 1) {
throw new GenerationSpecError('invalid_value', `${path}/pageNumbering/start`, 'Page numbering start must be a positive integer');
}
}
for (const [kind, set] of [['headers', section.headers], ['footers', section.footers]]) {
if (!set)
continue;
for (const slot of ['default', 'first', 'even']) {
const content = set[slot];
if (!content)
continue;
const slotPath = `${path}/${kind}/${slot}`;
if (!Array.isArray(content.blocks) || content.blocks.length === 0) {
throw new GenerationSpecError('invalid_value', `${slotPath}/blocks`, 'Header/footer blocks must be a non-empty array');
}
content.blocks.forEach((block, blockIndex) => {
validateBlock(block, `${slotPath}/blocks/${blockIndex}`, styleIds, numbering, 'headerFooter');
});
}
}
const size = section.page?.sizeTwips;
if (size && (!(size.w > 0) || !(size.h > 0))) {
throw new GenerationSpecError('invalid_value', `${path}/page/sizeTwips`, 'Page size dimensions must be positive twips');
}
const margins = section.page?.marginsTwips;
if (margins) {
for (const [key, value] of Object.entries(margins)) {
if (value !== undefined && (typeof value !== 'number' || value < 0 || !Number.isFinite(value))) {
throw new GenerationSpecError('invalid_value', `${path}/page/marginsTwips/${key}`, 'Margins must be non-negative finite twips');
}
}
}
if (!Array.isArray(section.blocks)) {
throw new GenerationSpecError('invalid_value', `${path}/blocks`, 'Section blocks must be an array');
}
section.blocks.forEach((block, blockIndex) => {
validateBlock(block, `${path}/blocks/${blockIndex}`, styleIds, numbering, 'body');
});
}
function validateBlock(block, path, styleIds, numbering, story) {
if (block.kind === 'table')
validateTable(block, path, styleIds, numbering, story);
else if (block.kind === 'paragraph')
validateParagraph(block, path, styleIds, numbering, story);
else
unsupported(path, `block kind '${block.kind}'`);
}
/**
* Table shape and grid arithmetic. Every row's effective column count
* (the sum of its cells' gridSpans) must equal the declared grid, and a
* vertical-merge continuation must sit at exactly the grid position and
* span of a merge cell in the previous row — otherwise readers either show
* a recovery dialog or silently reflow the table.
*/
function validateTable(table, path, styleIds, numbering, story) {
if (!Array.isArray(table.columnWidthsTwips) || table.columnWidthsTwips.length === 0) {
throw new GenerationSpecError('invalid_value', `${path}/columnWidthsTwips`, 'Tables require at least one column width');
}
table.columnWidthsTwips.forEach((width, i) => {
if (!(width > 0) || !Number.isFinite(width)) {
throw new GenerationSpecError('invalid_value', `${path}/columnWidthsTwips/${i}`, 'Column widths must be positive finite twips');
}
});
if (table.borders)
validateBorders(table.borders, `${path}/borders`);
if (!Array.isArray(table.rows) || table.rows.length === 0) {
throw new GenerationSpecError('invalid_value', `${path}/rows`, 'Tables require at least one row');
}
const columnCount = table.columnWidthsTwips.length;
// Grid start → span of every merge-participating cell in the previous row.
let previousMerges = new Map();
table.rows.forEach((row, rowIndex) => {
const rowPath = `${path}/rows/${rowIndex}`;
if (!Array.isArray(row.cells) || row.cells.length === 0) {
throw new GenerationSpecError('invalid_value', `${rowPath}/cells`, 'Rows require at least one cell');
}
if (row.heightTwips !== undefined && (!(row.heightTwips > 0) || !Number.isFinite(row.heightTwips))) {
throw new GenerationSpecError('invalid_value', `${rowPath}/heightTwips`, 'Row height must be positive finite twips');
}
const currentMerges = new Map();
let gridOffset = 0;
row.cells.forEach((cell, cellIndex) => {
const cellPath = `${rowPath}/cells/${cellIndex}`;
if (cell.gridSpan !== undefined && (!Number.isInteger(cell.gridSpan) || cell.gridSpan < 1)) {
throw new GenerationSpecError('invalid_value', `${cellPath}/gridSpan`, 'gridSpan must be a positive integer');
}
const span = cell.gridSpan ?? 1;
if (cell.vMerge === 'continue') {
if (rowIndex === 0) {
throw new GenerationSpecError('grid_mismatch', `${cellPath}/vMerge`, 'A vertical merge cannot continue in the first row');
}
if (previousMerges.get(gridOffset) !== span) {
throw new GenerationSpecError('grid_mismatch', `${cellPath}/vMerge`, `vMerge continuation at grid column ${gridOffset} (span ${span}) has no matching merge cell in the previous row`);
}
}
if (cell.vMerge !== undefined)
currentMerges.set(gridOffset, span);
if (cell.widthTwips !== undefined && (!(cell.widthTwips > 0) || !Number.isFinite(cell.widthTwips))) {
throw new GenerationSpecError('invalid_value', `${cellPath}/widthTwips`, 'Cell width must be positive finite twips');
}
if (cell.borders)
validateBorders(cell.borders, `${cellPath}/borders`);
if (cell.shadingHex !== undefined && !COLOR_HEX_RE.test(cell.shadingHex)) {
throw new GenerationSpecError('invalid_value', `${cellPath}/shadingHex`, `shadingHex must be six hex digits without '#', got '${cell.shadingHex}'`);
}
if (cell.themeFill !== undefined) {
validateThemeColorSlot(cell.themeFill, `${cellPath}/themeFill`, 'themeFill');
}
if (cell.shadingHex !== undefined && cell.themeFill !== undefined) {
throw new GenerationSpecError('invalid_value', `${cellPath}/themeFill`, 'themeFill cannot be set when shadingHex is also set');
}
validateOptionalTwoHex(cell.themeFillTint, `${cellPath}/themeFillTint`, 'themeFillTint');
validateOptionalTwoHex(cell.themeFillShade, `${cellPath}/themeFillShade`, 'themeFillShade');
if ((cell.themeFillTint !== undefined || cell.themeFillShade !== undefined) && cell.themeFill === undefined) {
throw new GenerationSpecError('invalid_value', `${cellPath}/themeFill`, 'themeFill is required when themeFillTint or themeFillShade is set');
}
if (cell.marginsTwips) {
for (const [key, value] of Object.entries(cell.marginsTwips)) {
if (value !== undefined && (typeof value !== 'number' || value < 0 || !Number.isFinite(value))) {
throw new GenerationSpecError('invalid_value', `${cellPath}/marginsTwips/${key}`, 'Cell margins must be non-negative finite twips');
}
}
}
if (!Array.isArray(cell.blocks)) {
throw new GenerationSpecError('invalid_value', `${cellPath}/blocks`, 'Cell blocks must be an array (empty allowed; an empty cell compiles to an empty paragraph)');
}
cell.blocks.forEach((block, blockIndex) => {
validateBlock(block, `${cellPath}/blocks/${blockIndex}`, styleIds, numbering, story);
});
gridOffset += span;
});
if (gridOffset !== columnCount) {
throw new GenerationSpecError('grid_mismatch', rowPath, `Row spans ${gridOffset} grid column(s) but the table declares ${columnCount}`);
}
previousMerges = currentMerges;
});
}
function validateBorders(borders, path) {
for (const [edge, spec] of Object.entries(borders)) {
if (!spec)
continue;
if (spec.colorHex !== undefined && !COLOR_HEX_RE.test(spec.colorHex)) {
throw new GenerationSpecError('invalid_value', `${path}/${edge}/colorHex`, `colorHex must be six hex digits without '#', got '${spec.colorHex}'`);
}
if (spec.sizeEighthPt !== undefined && (!(spec.sizeEighthPt > 0) || !Number.isFinite(spec.sizeEighthPt))) {
throw new GenerationSpecError('invalid_value', `${path}/${edge}/sizeEighthPt`, 'Border size must be positive finite eighth-points');
}
}
}
function validateParagraph(paragraph, path, styleIds, numbering, story) {
if (paragraph.note !== undefined) {
if (story === 'headerFooter') {
throw new GenerationSpecError('invalid_value', `${path}/note`, 'Drafting notes anchor as document-story comments and cannot live in headers or footers');
}
if (typeof paragraph.note.text !== 'string' || paragraph.note.text.length === 0) {
throw new GenerationSpecError('invalid_value', `${path}/note/text`, 'Drafting notes require non-empty text');
}
}
if (paragraph.list !== undefined) {
const levels = numbering.get(paragraph.list.numId);
if (!levels) {
throw new GenerationSpecError('dangling_numbering_reference', `${path}/list/numId`, `Paragraph references undeclared numbering '${paragraph.list.numId}'`);
}
if (!levels.has(paragraph.list.ilvl)) {
throw new GenerationSpecError('dangling_numbering_reference', `${path}/list/ilvl`, `Numbering '${paragraph.list.numId}' declares no level ${paragraph.list.ilvl}`);
}
}
if (paragraph.styleId !== undefined && !styleIds.has(paragraph.styleId)) {
throw new GenerationSpecError('dangling_style_reference', `${path}/styleId`, `Paragraph references undeclared style '${paragraph.styleId}'`);
}
if (paragraph.tabs) {
paragraph.tabs.forEach((stop, i) => {
if (!(stop.posTwips >= 0) || !Number.isFinite(stop.posTwips)) {
throw new GenerationSpecError('invalid_value', `${path}/tabs/${i}/posTwips`, 'Tab stop position must be a non-negative finite twips value');
}
});
}
if (!Array.isArray(paragraph.runs)) {
throw new GenerationSpecError('invalid_value', `${path}/runs`, 'Paragraph runs must be an array');
}
paragraph.runs.forEach((run, runIndex) => {
validateInline(run, `${path}/runs/${runIndex}`);
});
}
function validateInline(run, path) {
if (run.kind !== 'tab' && run.kind !== 'break' && run.kind !== 'field' && run.kind !== 'text') {
unsupported(path, `inline kind '${run.kind}'`);
}
if (run.kind === 'tab' || run.kind === 'break')
return;
if (run.kind === 'field') {
if (typeof run.cachedResult !== 'string' || run.cachedResult.length === 0) {
throw new GenerationSpecError('invalid_value', `${path}/cachedResult`, 'Fields require a non-empty cachedResult — the no-recovery-dialog guarantee is unrepresentable-by-omission');
}
validateRunProps(run, path);
return;
}
if (typeof run.text !== 'string') {
throw new GenerationSpecError('invalid_value', `${path}/text`, 'Text runs must carry a string');
}
validateRunProps(run, path);
}
function validateRunProps(props, path) {
if (props.colorHex !== undefined && !COLOR_HEX_RE.test(props.colorHex)) {
throw new GenerationSpecError('invalid_value', `${path}/colorHex`, `colorHex must be six hex digits without '#', got '${props.colorHex}'`);
}
if (props.themeColor !== undefined) {
validateThemeColorSlot(props.themeColor, `${path}/themeColor`, 'themeColor');
}
if (props.colorHex !== undefined && props.themeColor !== undefined) {
throw new GenerationSpecError('invalid_value', `${path}/themeColor`, 'themeColor cannot be set when colorHex is also set');
}
validateOptionalTwoHex(props.themeTint, `${path}/themeTint`, 'themeTint');
validateOptionalTwoHex(props.themeShade, `${path}/themeShade`, 'themeShade');
if ((props.themeTint !== undefined || props.themeShade !== undefined) && props.themeColor === undefined) {
throw new GenerationSpecError('invalid_value', `${path}/themeColor`, 'themeColor is required when themeTint or themeShade is set');
}
if (props.sizePt !== undefined && (!(props.sizePt > 0) || !Number.isFinite(props.sizePt))) {
throw new GenerationSpecError('invalid_value', `${path}/sizePt`, 'sizePt must be a positive finite number');
}
if (props.highlight !== undefined && !HIGHLIGHT_COLOR_SET.has(props.highlight)) {
throw new GenerationSpecError('invalid_value', `${path}/highlight`, `highlight must be one of the fixed CT_HighlightColor values, got '${props.highlight}'`);
}
}
function validateThemeColorSlot(value, path, fieldName) {
if (!THEME_COLOR_SLOT_SET.has(value)) {
throw new GenerationSpecError('invalid_value', path, `${fieldName} must be one of the supported theme slots, got '${value}'`);
}
}
function validateOptionalTwoHex(value, path, fieldName) {
if (value !== undefined && !TWO_HEX_RE.test(value)) {
throw new GenerationSpecError('invalid_value', path, `${fieldName} must be two hex digits without '#', got '${value}'`);
}
}
//# sourceMappingURL=validate-spec.js.map