@cairn-tool/cairn 3.1.0 → 3.3.0

package/dist/pdf/inspect.js

@@ -0,0 +1,232 @@
+import { CODES, DiagnosticSink } from "./diagnostics.js";
+import { classify } from "./document.js";
+import { extractPage, round2 } from "./text.js";
+/** Square points per square inch: 72 × 72. */
+const POINTS_PER_SQUARE_INCH = 5184;
+/**
+ * Below this many characters per square inch a page cannot be read as a
+ * document.
+ *
+ * A conventionally typeset Letter page — 12 pt body, ~1.4 line spacing, one inch
+ * margins — carries roughly 3000 characters over 93.5 in², so about 32 chars per
+ * square inch. Five is a sixth of that: on Letter it is around 470 characters,
+ * six to eight lines. Above it the text layer can carry a document; below it,
+ * whatever is there is a stamp, a caption, or a watermark.
+ *
+ * The inputs are published alongside the label so a caller who disagrees can
+ * re-threshold from `characters` and `density` without reverse-engineering this
+ * constant.
+ */
+const SPARSE_DENSITY = 5;
+/** A page with a handful of glyphs and nothing else is `absent`, not `sparse`. */
+const MINIMUM_GLYPHS = 32;
+const MINIMUM_DENSITY = 0.5;
+export function classifyTextLayer(characters, density) {
+    if (characters === 0)
+        return "absent";
+    if (characters < MINIMUM_GLYPHS && density < MINIMUM_DENSITY)
+        return "absent";
+    if (density < SPARSE_DENSITY)
+        return "sparse";
+    return "present";
+}
+/** The document-level roll-up: the label holding at least 80% of pages, else mixed. */
+function rollUp(pages) {
+    if (pages.length === 0)
+        return "absent";
+    const counts = new Map();
+    for (const page of pages)
+        counts.set(page.textLayer, (counts.get(page.textLayer) ?? 0) + 1);
+    for (const label of ["present", "sparse", "absent"])
+        if ((counts.get(label) ?? 0) / pages.length >= 0.8)
+            return label;
+    return "sparse";
+}
+/** Strips C0 controls and bounds a metadata string; attacker-controlled input. */
+function clean(value) {
+    if (typeof value !== "string")
+        return undefined;
+    // eslint-disable-next-line no-control-regex
+    const stripped = value.replace(/[\u0000-\u001f\u007f]/g, "").trim();
+    return stripped ? stripped.slice(0, 1024) : undefined;
+}
+/**
+ * Converts a PDF `D:YYYYMMDDHHmmSS` date to ISO 8601 in UTC.
+ *
+ * Omitted rather than guessed when it does not parse, and never rendered in the
+ * host timezone: that would make the payload machine-dependent, which is the
+ * same reasoning the ADF converter applies to its own timestamps.
+ */
+export function parsePdfDate(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const match = /^D:(\d{4})(\d{2})?(\d{2})?(\d{2})?(\d{2})?(\d{2})?(?:(Z)|([+-])(\d{2})'?(\d{2})'?)?/.exec(value);
+    if (!match)
+        return undefined;
+    const [, year, month, day, hour, minute, second, , sign, offsetHours, offsetMinutes] = match;
+    const stamp = Date.UTC(Number(year), Number(month ?? "01") - 1, Number(day ?? "01"), Number(hour ?? "00"), Number(minute ?? "00"), Number(second ?? "00"));
+    if (Number.isNaN(stamp))
+        return undefined;
+    const offset = sign && offsetHours
+        ? (Number(offsetHours) * 60 + Number(offsetMinutes ?? "0")) * 60_000 * (sign === "-" ? -1 : 1)
+        : 0;
+    return new Date(stamp - offset).toISOString();
+}
+/** True when a structure tree carries at least one marked-content leaf. */
+export function hasStructContent(node) {
+    if (!node)
+        return false;
+    if (node.type === "content" && node.id)
+        return true;
+    return (node.children ?? []).some(hasStructContent);
+}
+/**
+ * The document facts that cost nothing: no page is opened.
+ *
+ * Every command carries this, so a caller can read `document.tagged` off a
+ * `to-markdown` payload rather than making a second call. `structured` and
+ * `textLayer` are absent here because only a command that walks pages can
+ * measure them, and a field nobody measured must not read as a measurement.
+ */
+export async function documentSummary(handle) {
+    const sink = new DiagnosticSink();
+    const { doc } = handle;
+    let info = {};
+    try {
+        const metadata = await handle.within(() => doc.getMetadata());
+        info = metadata.info ?? {};
+    }
+    catch {
+        sink.add({
+            code: CODES.metadataUnreadable,
+            quality: "approximate",
+            message: "The document's metadata could not be read; other findings are unaffected",
+        });
+    }
+    // getMarkInfo() returns a Map, not an object — reading `.Marked` on it is
+    // always undefined, which would report every document as untagged. The
+    // published .d.ts says otherwise and is wrong.
+    let tagged;
+    try {
+        const markInfo = await handle.within(() => doc.getMarkInfo());
+        tagged = markInfo instanceof Map && markInfo.get("Marked") === true;
+    }
+    catch {
+        tagged = false;
+    }
+    if (handle.encrypted)
+        sink.add({
+            code: CODES.encryptedOpenPassword,
+            quality: "exact",
+            message: "The document is encrypted but opened without a password, so its restrictions are advisory only",
+        });
+    return {
+        document: {
+            pageCount: doc.numPages,
+            tagged,
+            encrypted: handle.encrypted,
+            ...maybe("pdfVersion", clean(info.PDFFormatVersion)),
+            ...maybe("title", clean(info.Title)),
+            ...maybe("author", clean(info.Author)),
+            ...maybe("subject", clean(info.Subject)),
+            ...maybe("keywords", clean(info.Keywords)),
+            ...maybe("creator", clean(info.Creator)),
+            ...maybe("producer", clean(info.Producer)),
+            ...maybe("created", parsePdfDate(info.CreationDate)),
+            ...maybe("modified", parsePdfDate(info.ModDate)),
+        },
+        diagnostics: sink.all(),
+    };
+}
+/**
+ * The page inventory, on top of {@link documentSummary}.
+ *
+ * `probeStructure` drives whether each page's structure tree is opened. It is on
+ * for `inspect`, because `structured` is one of the two fields the command
+ * exists to report, and off elsewhere.
+ */
+export async function inspectDocument(handle, options = {}) {
+    const sink = new DiagnosticSink();
+    const { doc } = handle;
+    const summary = await documentSummary(handle);
+    for (const item of summary.diagnostics)
+        sink.add({ ...item, quality: item.quality, severity: item.severity });
+    const wanted = options.pages ?? Array.from({ length: doc.numPages }, (_, index) => index + 1);
+    const pages = [];
+    let structuredPages = 0;
+    let probedPages = 0;
+    for (const page of wanted) {
+        try {
+            const extracted = await extractPage(handle, page);
+            const density = extracted.width > 0 && extracted.height > 0
+                ? (extracted.characters * POINTS_PER_SQUARE_INCH) / (extracted.width * extracted.height)
+                : 0;
+            const textLayer = classifyTextLayer(extracted.characters, density);
+            pages.push({
+                page,
+                width: extracted.width,
+                height: extracted.height,
+                rotation: extracted.rotation,
+                characters: extracted.characters,
+                density: round2(density),
+                textLayer,
+            });
+            if (textLayer === "absent")
+                sink.add({
+                    code: CODES.noTextLayer,
+                    quality: "unsupported",
+                    message: "The page carries no text layer; nothing can be extracted from it",
+                    page,
+                    remediation: "The page is an image. Recognizing its text needs OCR, which this toolset does not do.",
+                });
+            if (options.probeStructure) {
+                probedPages += 1;
+                const proxy = await handle.within(() => doc.getPage(page));
+                const tree = await handle.within(() => proxy.getStructTree());
+                if (hasStructContent(tree))
+                    structuredPages += 1;
+                proxy.cleanup();
+            }
+        }
+        catch (error) {
+            const classified = await classify(error, page);
+            sink.add({ ...classified, quality: "unsupported" });
+        }
+    }
+    if (options.probeStructure) {
+        if (summary.document.tagged && structuredPages === 0)
+            sink.add({
+                code: CODES.taggedButEmpty,
+                quality: "approximate",
+                message: "The document declares /MarkInfo <</Marked true>> but no page carries a usable structure tree",
+                remediation: "Conversion will infer structure geometrically, as though the document were untagged.",
+            });
+        if (structuredPages > 0 && structuredPages < probedPages)
+            sink.add({
+                code: CODES.structPartial,
+                quality: "exact",
+                message: `A structure tree is present on ${structuredPages} of ${probedPages} pages`,
+            });
+    }
+    return {
+        document: {
+            ...summary.document,
+            ...(options.probeStructure
+                ? {
+                    structured: structuredPages === 0
+                        ? "none"
+                        : structuredPages === probedPages
+                            ? "struct"
+                            : "partial",
+                }
+                : {}),
+            ...(pages.length ? { textLayer: rollUp(pages) } : {}),
+        },
+        pages,
+        diagnostics: sink.all(),
+    };
+}
+function maybe(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+//# sourceMappingURL=inspect.js.map

package/dist/pdf/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/pdf/inspect.ts"],"names":[],"mappings":"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"}

package/dist/pdf/layout.d.ts

@@ -0,0 +1,78 @@
+import { DiagnosticSink } from "./diagnostics.js";
+import type { PageRuns, PositionedRun } from "./text.js";
+import type { Block } from "./types.js";
+/**
+ * Geometric structure inference.
+ *
+ * A PDF has no paragraphs, no headings, and no lists — only positioned glyph
+ * runs — so everything here is inference from geometry and font metrics. The
+ * stages are exported as pure functions taking and returning plain data, which
+ * is what makes each one testable on its own and lets them be reviewed one at a
+ * time.
+ *
+ * Every sort ends with an explicit `(page, index)` tie-break. A heuristic whose
+ * output flips between runs is worse than one that is wrong consistently.
+ */
+/** A line: runs sharing a baseline, ordered left to right. */
+export interface Line {
+    page: number;
+    y: number;
+    runs: PositionedRun[];
+    text: string;
+    /** Left edge, for indent comparisons. */
+    x: number;
+    /** The modal font size across the line's runs. */
+    size: number;
+    bold: boolean;
+    /** x positions where a gap wider than 1.5em opened — the only table signal. */
+    gaps: number[];
+}
+export interface NormalizeResult {
+    body: PositionedRun[];
+    dropped: number;
+}
+/**
+ * Splits out runs no axis-aligned heuristic can place.
+ *
+ * Text at an arbitrary angle and vertical writing are excluded rather than
+ * folded in at the wrong position, and reported. Every stage after this may
+ * assume upright, left-to-right runs.
+ */
+export declare function normalize(runs: PositionedRun[], sink: DiagnosticSink): NormalizeResult;
+/**
+ * Removes text that repeats at the same height on most pages.
+ *
+ * Requires at least four pages: below that, repetition is not evidence. A bucket
+ * that repeats but is *not* near an edge is left alone — that is a section title
+ * or a watermark, and dropping it would delete content.
+ */
+export declare function removeArtifacts(runs: PositionedRun[], pageCount: number, pageHeight: number, sink: DiagnosticSink): PositionedRun[];
+/**
+ * Splits a page's runs into columns, or reports that it could not.
+ *
+ * Reading a two-column page top to bottom interleaves the columns into text that
+ * reads like prose and is not — a degradation indistinguishable from success, so
+ * refusing to look is not the safe option. Looking, with a reported failure
+ * mode, is.
+ *
+ * A gutter is a vertical band at least 3% of the page wide containing no run and
+ * spanning at least 70% of the content's height. A candidate is rejected when
+ * the resulting sides differ by more than 6:1, which is a hanging indent or a
+ * figure rather than a gutter.
+ */
+export declare function splitColumns(runs: PositionedRun[], pageWidth: number, sink: DiagnosticSink, page: number): PositionedRun[][];
+/** Groups runs into lines and records the wide gaps within each. */
+export declare function buildLines(runs: PositionedRun[]): Line[];
+export interface LayoutOptions {
+    /** Outline titles to level, used to pin heading levels where they agree. */
+    headingLevels?: Map<string, number>;
+}
+/**
+ * Turns one document's pages into blocks.
+ *
+ * Column splitting, line grouping, and paragraph breaking are per page; the
+ * modal body size and the heading size ranking are computed across the whole
+ * document, because a per-page ranking makes heading levels drift between pages
+ * of the same document.
+ */
+export declare function blocksFromLayout(pages: PageRuns[], sink: DiagnosticSink, options?: LayoutOptions): Block[];