XLSX Validation & Repair

CmdCal XLSX is designed for production workflows, not just happy-path generation. That means you can inspect completed workbooks, repair common structural damage, and revalidate the result with a shared findings model.

Validate A Finished Workbook

Use buffer-level validation when you want to inspect generated output or a third-party .xlsx before handing it to users.

import fs from "node:fs/promises";
import { SpreadsheetEngine } from "@paperjsx/json-to-xlsx";

const buffer = await fs.readFile("customer-template.xlsx");
const summary = await SpreadsheetEngine.validate(buffer);

console.log(summary.verdict);
console.log(summary.findings);

The validator returns:

• verdict: clean, warnings, or errors
• findings: structured, machine-readable workbook issues

What The Validator Already Covers

Current Phase 5 coverage includes:

• missing content type overrides
• orphan relationships
• missing worksheet targets
• out-of-range style indices
• broken table refs and duplicate table names
• worksheet dimension mismatches
• invalid hyperlink refs
• invalid data validation ranges
• overlapping merges
• clearly broken defined names

Run Conservative Repair

Repair is intentionally conservative. The goal is to salvage common workbook damage without quietly changing business meaning.

import fs from "node:fs/promises";
import { SpreadsheetEngine } from "@paperjsx/json-to-xlsx";

const broken = await fs.readFile("broken-report.xlsx");
const result = await SpreadsheetEngine.repair(broken);

await fs.writeFile("broken-report.repaired.xlsx", result.buffer);
console.log(result.actions);

Repairs currently include:

• rebuilding [Content_Types].xml
• removing orphan relationships
• clamping invalid style indices
• clipping invalid table refs
• recalculating worksheet dimensions
• removing invalid hyperlinks
• clipping data validation ranges
• clipping invalid merges and removing later overlaps deterministically
• removing clearly broken defined names
• stripping unsafe artifacts like macros, external links, and embeddings

Download Validation Samples

• Workbook with validations and hyperlinks: validation-hyperlinks-sample.xlsx
• Conservative repair options preset: repair-options.json

Validate, Repair, Revalidate

For incident handling and support flows, use the full orchestration path:

const result = await SpreadsheetEngine.validateAndRepair(buffer);

console.log(result.original.verdict);
console.log(result.repair.actions);
console.log(result.repaired.verdict);

This gives you:

• the original verdict
• the applied repair actions
• the repaired workbook buffer
• the repaired verdict after revalidation

Preflight Before Large Renders

Preflight is for document-level risk before you render:

const report = SpreadsheetEngine.preflight(workbook, {
  stringStrategy: "auto",
});

console.log(report.verdict);
console.log(report.renderModeRecommendation);
console.log(report.findings);

That is useful when you want early warnings about:

• large file pressure
• high unique-string pressure
• excessive style cardinality
• cross-app import risks

Operational Guidance

Use validateDocument(...) when you want schema safety before render.

Use preflight(...) when you want to estimate size, memory pressure, or cross-app risk before render.

Use validate(buffer) when you want to inspect finished .xlsx output.

Use repair(buffer) when you need a conservative salvage pass.

Use validateAndRepair(buffer) when you need a support-ready incident workflow with explicit before/after state.

If you want a sample pack instead of starting from a broken customer file, use Examples & Downloads.

Known Limits

The repair engine is not trying to “fix anything no matter what.” That is intentional.

Still-active follow-up work includes:

• shared string recovery
• minimal styles.xml regeneration when missing
• workbook protection coherence checks
• drawing relationship integrity repair
• broader extension-list compatibility warnings

If a workbook is badly damaged beyond the conservative rule set, the correct behavior is a structured error or a remaining finding, not silent corruption.