Calliper Compare to Markdown Generator

Problem

When two versions of a contract, spec, config, or text file differ, manual review often misses subtle clause wording, field values, table cells, and compliance changes. calliper-compare2markdown turns the “submit two local files and get a readable diff” step into one fixed script: it calls the synchronous calliper API through PDRouter, by default POST /openapi/{serviceCode}/compare/markdown, and prints Markdown diff output to stdout. For engineers, the value is a stable intermediate artifact that can be parsed downstream.

How It Works

• Fixed entry point: use scripts/compare_to_markdown.js directly; do not reimplement the API flow or bypass the script during normal tasks.
• Auth and environment: prefer PAODINGAI_API_KEY, fall back to CALLIPER_ACCESS_TOKEN; fail if both are missing. Optional variables include PD_ROUTER_BASE_URL, PD_ROUTER_SERVICE_CODE, and PD_ROUTER_COMPARE_ENDPOINT.
• Request shape: after validating that both local input files exist, the script sends one multipart request with file1, file2, and optional config, plus an Authorization: Bearer header.
• Output parsing: if the response is Markdown or plain text, output it directly; otherwise try common JSON fields such as data.markdown and markdown, then fall back to the JSON text.
• File output: with output-markdown-path, the script writes the same content to that file while also printing to stdout. Progress and errors go to stderr, and failures return a non-zero exit code.

Boundaries

Use it for “export diff to Markdown,” generating parseable change summaries, clause extraction, mismatch validation, and rule checks. If the Markdown is only intermediate input, write it to a working file first and extract only needed fragments; return full Markdown only when the user explicitly asks for the original complete diff. If routing, service code, or endpoint differs from defaults, adjust environment variables rather than changing script logic.