UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

613 lines • 25.3 kB
/** * Checklist DOCX import/diff module. * * Parses a rendered closing-checklist DOCX and produces RFC 6902 patch * operations representing human edits to the document. * * Processes 5-column Documents, 5-column Action Items, and 5-column Issues tables. */ import AdmZip from 'adm-zip'; import { DOMParser } from '@xmldom/xmldom'; import { extractTables, } from '@usejunior/docx-core'; import { reverseHumanStatus } from './status-labels.js'; import { DOCUMENTS_HEADERS, ACTION_ITEMS_HEADERS, ISSUES_HEADERS, classifyRow, extractRenderVersion, } from './docx-table-helpers.js'; // --------------------------------------------------------------------------- // Parsing helpers // --------------------------------------------------------------------------- /** * Parse the merged Responsible column: "Entity (Individual)" format. * Uses the canonical shape to disambiguate single-token text. * * Known limitation: when canonical has both org and individual, any * parenthesized text is split — e.g. "Acme (Delaware)" would be parsed as * org="Acme", individual="Delaware". This is inherent to the format; the * canonical shape is the best available disambiguation signal. */ function parseResponsibleColumn(text, canonical) { const trimmed = text.trim(); if (!trimmed) return { organization: null, individual_name: null }; // Only attempt "Entity (Individual)" split when canonical has BOTH fields const hasBoth = canonical?.organization && canonical?.individual_name; if (hasBoth) { const parenIdx = trimmed.lastIndexOf('('); if (parenIdx > 0 && trimmed.endsWith(')')) { const org = trimmed.slice(0, parenIdx).trim(); const individual = trimmed.slice(parenIdx + 1, -1).trim(); return { organization: org || null, individual_name: individual || null }; } } // No parens or single-field canonical — use canonical shape as tiebreaker if (canonical) { if (canonical.organization && !canonical.individual_name) { return { organization: trimmed, individual_name: null }; } if (canonical.individual_name && !canonical.organization) { return { organization: null, individual_name: trimmed }; } } // Default (no canonical or canonical has both but no parens): treat as org return { organization: trimmed, individual_name: null }; } function toArray(collection) { return Array.isArray(collection) ? collection : Object.values(collection); } // --------------------------------------------------------------------------- // Table extraction from DOCX buffer // --------------------------------------------------------------------------- function parseDocxXml(buffer) { const zip = new AdmZip(buffer); const entry = zip.getEntry('word/document.xml'); if (!entry) throw new Error('word/document.xml not found in DOCX'); const xmlStr = entry.getData().toString('utf-8'); return new DOMParser().parseFromString(xmlStr, 'text/xml'); } function findExtractedTable(result, targetHeaders) { return result.tables.find((t) => { if (t.headers.length !== targetHeaders.length) return false; return t.headers.every((h, i) => h === targetHeaders[i]); }) ?? null; } // --------------------------------------------------------------------------- // Documents table import // --------------------------------------------------------------------------- function importDocumentsTable(table, checklist, ops, warnings) { const entries = toArray(checklist.checklist_entries); const documents = toArray(checklist.documents); const entriesById = new Map(entries.map((e) => [e.entry_id, e])); const documentsById = new Map(documents.map((d) => [d.document_id, d])); const seenIds = new Set(); let processed = 0; for (let i = 0; i < table.rows.length; i++) { const row = table.rows[i]; const entryId = row['ID']?.trim() ?? ''; const titleText = row['Title']?.trim() ?? ''; // Skip stage headings and sub-rows const rowType = classifyRow(entryId, titleText); if (rowType === 'stage_heading') continue; // Sub-rows: detect changes and emit warnings if (rowType !== 'main_entry' && rowType !== 'unknown') { // Sub-rows are read-only if (titleText || row['Status']?.trim()) { warnings.push({ code: 'SUB_ROW_CHANGED', table: 'documents', message: `Sub-row at index ${i} (${rowType}) is read-only`, rowIndex: i, }); } continue; } // Empty-ID unknown rows: display-only, skip with info warning if (!entryId && rowType === 'unknown') { warnings.push({ code: 'DISPLAY_ROW_SKIPPED', table: 'documents', message: `Row ${i} has empty ID — display-only row skipped`, rowIndex: i, }); continue; } // ID integrity policy if (!entryId) { warnings.push({ code: 'NEW_ROW_ADDED', table: 'documents', message: `Row ${i} has empty ID — new row addition not supported for documents table`, rowIndex: i, }); continue; } if (seenIds.has(entryId)) { warnings.push({ code: 'DUPLICATE_ID', table: 'documents', message: `Duplicate ID "${entryId}" at row ${i} — skipping`, rowIndex: i, }); continue; } seenIds.add(entryId); const entry = entriesById.get(entryId); if (!entry) { warnings.push({ code: 'UNKNOWN_ID', table: 'documents', message: `Unknown entry ID "${entryId}" at row ${i} — skipping`, rowIndex: i, }); continue; } processed++; // Compare and generate replace ops // Title (strip NBSP indent for comparison) const cleanTitle = titleText.replace(/^\u00A0+/, '').trim(); if (cleanTitle && cleanTitle !== entry.title) { ops.push({ op: 'replace', path: `/checklist_entries/${entryId}/title`, value: cleanTitle, rationale: 'DOCX import: title changed', }); } // Status const statusText = row['Status']?.trim() ?? ''; if (statusText) { const enumStatus = reverseHumanStatus(statusText); if (enumStatus && enumStatus !== entry.status) { ops.push({ op: 'replace', path: `/checklist_entries/${entryId}/status`, value: enumStatus, rationale: 'DOCX import: status changed', }); } } // Link → ChecklistDocument.primary_link const linkText = row['Link']?.trim() ?? ''; const doc = entry.document_id ? documentsById.get(entry.document_id) : null; if (doc) { const currentLink = doc.primary_link ?? ''; if (linkText !== currentLink) { ops.push({ op: linkText ? 'replace' : 'remove', path: `/documents/${doc.document_id}/primary_link`, ...(linkText ? { value: linkText } : {}), rationale: 'DOCX import: link changed', }); } } // Responsible → merged "Entity (Individual)" column const responsibleText = row['Responsible']?.trim() ?? ''; const parsed = parseResponsibleColumn(responsibleText, entry.responsible_party); const currentOrg = entry.responsible_party?.organization ?? ''; const currentIndividual = entry.responsible_party?.individual_name ?? ''; if ((parsed.organization ?? '') !== currentOrg || (parsed.individual_name ?? '') !== currentIndividual) { if (!entry.responsible_party && (parsed.organization || parsed.individual_name)) { // Create new responsible_party (never touch role) ops.push({ op: 'replace', path: `/checklist_entries/${entryId}/responsible_party`, value: { ...(parsed.organization ? { organization: parsed.organization } : {}), ...(parsed.individual_name ? { individual_name: parsed.individual_name } : {}), }, rationale: 'DOCX import: responsible party added', }); } else if (entry.responsible_party) { // Clearing entire responsible_party if (!parsed.organization && !parsed.individual_name && !responsibleText) { ops.push({ op: 'remove', path: `/checklist_entries/${entryId}/responsible_party`, rationale: 'DOCX import: responsible party cleared', }); } else { // Update individual fields (never touch role) if ((parsed.organization ?? '') !== currentOrg) { if (parsed.organization) { ops.push({ op: 'replace', path: `/checklist_entries/${entryId}/responsible_party/organization`, value: parsed.organization, rationale: 'DOCX import: organization changed', }); } else { ops.push({ op: 'remove', path: `/checklist_entries/${entryId}/responsible_party/organization`, rationale: 'DOCX import: organization cleared', }); } } if ((parsed.individual_name ?? '') !== currentIndividual) { if (parsed.individual_name) { ops.push({ op: 'replace', path: `/checklist_entries/${entryId}/responsible_party/individual_name`, value: parsed.individual_name, rationale: 'DOCX import: individual_name changed', }); } else { ops.push({ op: 'remove', path: `/checklist_entries/${entryId}/responsible_party/individual_name`, rationale: 'DOCX import: individual_name cleared', }); } } } } } } return processed; } // --------------------------------------------------------------------------- // Action Items table import // --------------------------------------------------------------------------- function importActionItemsTable(table, checklist, ops, warnings) { const actions = toArray(checklist.action_items); const actionsById = new Map(actions.map((a) => [a.action_id, a])); const seenIds = new Set(); let processed = 0; for (let i = 0; i < table.rows.length; i++) { const row = table.rows[i]; const actionId = row['ID']?.trim() ?? ''; // Empty ID = new row if (!actionId) { const description = row['Description']?.trim() ?? ''; if (description) { const newId = `A-${Date.now()}-${i}`; const statusText = row['Status']?.trim() ?? ''; const enumStatus = reverseHumanStatus(statusText) ?? 'NOT_STARTED'; ops.push({ op: 'add', path: `/action_items/${newId}`, value: { action_id: newId, description, status: enumStatus, assigned_to: row['Assigned To']?.trim() ? { individual_name: row['Assigned To']?.trim() } : undefined, due_date: row['Due Date']?.trim() || undefined, related_document_ids: [], citations: [], }, rationale: 'DOCX import: new action item added', }); warnings.push({ code: 'NEW_ROW_ADDED', table: 'action_items', message: `New action item "${description}" added with generated ID "${newId}"`, rowIndex: i, }); } continue; } if (seenIds.has(actionId)) { warnings.push({ code: 'DUPLICATE_ID', table: 'action_items', message: `Duplicate ID "${actionId}" at row ${i} — skipping`, rowIndex: i, }); continue; } seenIds.add(actionId); const action = actionsById.get(actionId); if (!action) { warnings.push({ code: 'UNKNOWN_ID', table: 'action_items', message: `Unknown action ID "${actionId}" at row ${i} — skipping`, rowIndex: i, }); continue; } processed++; // Description const desc = row['Description']?.trim() ?? ''; if (desc && desc !== action.description) { ops.push({ op: 'replace', path: `/action_items/${actionId}/description`, value: desc, rationale: 'DOCX import: action description changed', }); } // Status const statusText = row['Status']?.trim() ?? ''; if (statusText) { const enumStatus = reverseHumanStatus(statusText); if (enumStatus && enumStatus !== action.status) { ops.push({ op: 'replace', path: `/action_items/${actionId}/status`, value: enumStatus, rationale: 'DOCX import: action status changed', }); } } // Assigned To const assignedTo = row['Assigned To']?.trim() ?? ''; const currentAssigned = action.assigned_to?.individual_name ?? ''; if (assignedTo !== currentAssigned) { if (!action.assigned_to && assignedTo) { ops.push({ op: 'replace', path: `/action_items/${actionId}/assigned_to`, value: { individual_name: assignedTo }, rationale: 'DOCX import: action assigned_to changed', }); } else if (action.assigned_to) { ops.push({ op: 'replace', path: `/action_items/${actionId}/assigned_to/individual_name`, value: assignedTo || undefined, rationale: 'DOCX import: action assigned_to changed', }); } } // Due Date const dueDate = row['Due Date']?.trim() ?? ''; const currentDue = action.due_date ?? ''; if (dueDate !== currentDue) { ops.push({ op: dueDate ? 'replace' : 'remove', path: `/action_items/${actionId}/due_date`, ...(dueDate ? { value: dueDate } : {}), rationale: 'DOCX import: action due_date changed', }); } } // Check for removed rows for (const action of actions) { if (!seenIds.has(action.action_id)) { ops.push({ op: 'remove', path: `/action_items/${action.action_id}`, rationale: 'DOCX import: action item removed from table', }); } } return processed; } // --------------------------------------------------------------------------- // Issues table import // --------------------------------------------------------------------------- function importIssuesTable(table, checklist, ops, warnings) { const issues = toArray(checklist.issues); const issuesById = new Map(issues.map((iss) => [iss.issue_id, iss])); const seenIds = new Set(); let processed = 0; for (let i = 0; i < table.rows.length; i++) { const row = table.rows[i]; const issueId = row['ID']?.trim() ?? ''; // Empty ID = new row if (!issueId) { const title = row['Title']?.trim() ?? ''; if (title) { const newId = `I-${Date.now()}-${i}`; const statusText = row['Status']?.trim() ?? ''; const enumStatus = reverseHumanStatus(statusText) ?? 'OPEN'; ops.push({ op: 'add', path: `/issues/${newId}`, value: { issue_id: newId, title, status: enumStatus, summary: row['Summary']?.trim() || undefined, related_document_ids: [], citations: [], }, rationale: 'DOCX import: new issue added', }); warnings.push({ code: 'NEW_ROW_ADDED', table: 'issues', message: `New issue "${title}" added with generated ID "${newId}"`, rowIndex: i, }); } continue; } if (seenIds.has(issueId)) { warnings.push({ code: 'DUPLICATE_ID', table: 'issues', message: `Duplicate ID "${issueId}" at row ${i} — skipping`, rowIndex: i, }); continue; } seenIds.add(issueId); const issue = issuesById.get(issueId); if (!issue) { warnings.push({ code: 'UNKNOWN_ID', table: 'issues', message: `Unknown issue ID "${issueId}" at row ${i} — skipping`, rowIndex: i, }); continue; } processed++; // Title const title = row['Title']?.trim() ?? ''; if (title && title !== issue.title) { ops.push({ op: 'replace', path: `/issues/${issueId}/title`, value: title, rationale: 'DOCX import: issue title changed', }); } // Status const statusText = row['Status']?.trim() ?? ''; if (statusText) { const enumStatus = reverseHumanStatus(statusText); if (enumStatus && enumStatus !== issue.status) { ops.push({ op: 'replace', path: `/issues/${issueId}/status`, value: enumStatus, rationale: 'DOCX import: issue status changed', }); } } // Summary const summary = row['Summary']?.trim() ?? ''; const currentSummary = issue.summary ?? ''; if (summary !== currentSummary) { ops.push({ op: summary ? 'replace' : 'remove', path: `/issues/${issueId}/summary`, ...(summary ? { value: summary } : {}), rationale: 'DOCX import: issue summary changed', }); } // Citation (latest citation text) const citationText = row['Citation']?.trim() ?? ''; const currentCitations = issue.citations ?? []; const currentLatestCitation = currentCitations.length > 0 ? (currentCitations[currentCitations.length - 1].text ?? currentCitations[currentCitations.length - 1].ref ?? '') : ''; if (citationText && citationText !== currentLatestCitation) { // Add a new citation ops.push({ op: 'add', path: `/issues/${issueId}/citations/-`, value: { text: citationText }, rationale: 'DOCX import: issue citation updated', }); } } // Check for removed rows for (const issue of issues) { if (!seenIds.has(issue.issue_id)) { ops.push({ op: 'remove', path: `/issues/${issue.issue_id}`, rationale: 'DOCX import: issue removed from table', }); } } return processed; } // --------------------------------------------------------------------------- // Main import function // --------------------------------------------------------------------------- /** * Import a rendered closing-checklist DOCX and produce a patch envelope * representing the differences from the canonical checklist state. */ export function importChecklistFromDocx(options) { const { docxBuffer, canonicalChecklist, checklistId, currentRevision } = options; // Parse DOCX XML let xmlDoc; try { xmlDoc = parseDocxXml(docxBuffer); } catch (err) { return { ok: false, error_code: 'PARSE_FAILED', message: `Failed to parse DOCX: ${err instanceof Error ? err.message : String(err)}`, }; } // Check render version marker const renderVersion = extractRenderVersion(xmlDoc); if (renderVersion !== 'closing-checklist') { return { ok: false, error_code: 'VERSION_MISMATCH', message: 'DOCX is missing render version marker (closing-checklist). Was this rendered with the current template?', }; } // Use docx-core extractTables on the raw DOM // We need to use the xmldom Document as a DOM Document const extractResult = extractTables(xmlDoc, { rejectMergedCells: true, headerFilter: [DOCUMENTS_HEADERS, ACTION_ITEMS_HEADERS, ISSUES_HEADERS], }); // Check for merged cell errors if (extractResult.mergedCellDiagnostics.length > 0) { return { ok: false, error_code: 'MERGED_CELLS', message: `DOCX contains merged cells which cannot be safely parsed (${extractResult.mergedCellDiagnostics.length} merged cells detected)`, }; } const docsTable = findExtractedTable(extractResult, DOCUMENTS_HEADERS); const actionsTable = findExtractedTable(extractResult, ACTION_ITEMS_HEADERS); const issuesTable = findExtractedTable(extractResult, ISSUES_HEADERS); if (!docsTable && !actionsTable && !issuesTable) { return { ok: false, error_code: 'TABLE_NOT_FOUND', message: 'No recognized checklist tables found in DOCX. Expected 5-column headers (ID | Title | Link | Status | Responsible).', }; } const ops = []; const warnings = []; // Filter out control rows from extracted tables // (docx-core extractTables gives us raw data; control rows have {FOR / {END-FOR text) function filterControlRows(table) { const filteredRows = table.rows.filter((row) => { const firstCell = Object.values(row)[0] ?? ''; if (firstCell.trim().startsWith('{FOR') || firstCell.trim().startsWith('{END-FOR')) { return false; } return true; }); return { ...table, rows: filteredRows }; } let documentsProcessed = 0; let actionItemsProcessed = 0; let issuesProcessed = 0; if (docsTable) { const filtered = filterControlRows(docsTable); documentsProcessed = importDocumentsTable(filtered, canonicalChecklist, ops, warnings); } if (actionsTable) { const filtered = filterControlRows(actionsTable); actionItemsProcessed = importActionItemsTable(filtered, canonicalChecklist, ops, warnings); } if (issuesTable) { const filtered = filterControlRows(issuesTable); issuesProcessed = importIssuesTable(filtered, canonicalChecklist, ops, warnings); } // Build patch envelope const patch = ops.length > 0 ? { patch_id: `docx-import-${checklistId}-${Date.now()}`, mode: 'APPLY', expected_revision: currentRevision, operations: ops, source_event: { provider: 'docx-import', }, } : null; return { ok: true, patch, warnings, summary: { documentsProcessed, actionItemsProcessed, issuesProcessed, operationsGenerated: ops.length, warningsGenerated: warnings.length, }, }; } //# sourceMappingURL=docx-import.js.map