@yolk-sdk/extractors 0.1.0-canary.98

package/src/node/xlsx-hyperlinks.ts

@@ -0,0 +1,260 @@
+import { Buffer } from 'node:buffer'
+import type { StrippedHyperlinkTags } from './office-archive.ts'
+import { indexParts, relationships, relationshipsPathFor, utf8Text } from './xlsx-parts.ts'
+import type { Relationship } from './xlsx-parts.ts'
+import { parseCellRange } from './xlsx-range.ts'
+import type { CellRange } from './xlsx-range.ts'
+import { prefixedAttribute, xmlAttributes } from './xml-text.ts'
+
+export type XlsxHyperlink = {
+  readonly range: CellRange
+  /** Normalized `http:`, `https:`, or `mailto:` URL, at most 2,048 characters. */
+  readonly target: string
+  /** Label for cells without text, at most 1,024 characters (longer labels end in `…`). */
+  readonly display?: string
+}
+
+/** Hyperlinks per worksheet name, in document order (a later link wins on overlap). */
+export type XlsxHyperlinks = ReadonlyMap<string, ReadonlyArray<XlsxHyperlink>>
+
+/** Longer targets are dropped: a truncated URL would point somewhere else. */
+const maxHyperlinkTargetCharacters = 2048
+
+/** Longer display labels are cut to this many characters, ending with an ellipsis. */
+const maxHyperlinkDisplayCharacters = 1024
+
+const capDisplay = (display: string) => {
+  if (display.length <= maxHyperlinkDisplayCharacters) return display
+
+  let kept = display.slice(0, maxHyperlinkDisplayCharacters - 1)
+  const last = kept.charCodeAt(kept.length - 1)
+
+  // Never leave half of a surrogate pair before the ellipsis.
+  if (last >= 0xd800 && last <= 0xdbff) kept = kept.slice(0, -1)
+
+  return `${kept}\u2026`
+}
+
+const shownProtocols = new Set(['http:', 'https:', 'mailto:'])
+
+const shownTarget = (target: string) => {
+  if (target.length > maxHyperlinkTargetCharacters || !URL.canParse(target)) return undefined
+
+  const url = new URL(target)
+
+  if (!shownProtocols.has(url.protocol) || url.href.length > maxHyperlinkTargetCharacters)
+    return undefined
+
+  return url.href
+}
+
+const hyperlinkFrom = (
+  tag: string,
+  sheetRelationships: ReadonlyMap<string, Relationship>
+): XlsxHyperlink | undefined => {
+  // Tags were captured as Latin-1 text of the original bytes; attribute values are UTF-8.
+  const attributes = xmlAttributes(Buffer.from(tag, 'latin1').toString('utf8'))
+  const ref = attributes.get('ref')
+  const range = ref === undefined ? undefined : parseCellRange(ref)
+  const id = prefixedAttribute(attributes, 'id')
+  const relationship = id === undefined ? undefined : sheetRelationships.get(id)
+
+  // Internal `location`-only links (`#Sheet2!A1`) are omitted; external links keep their
+  // location as a fragment, as SheetJS does.
+  if (range === undefined || relationship === undefined || !relationship.external) return undefined
+
+  const location = attributes.get('location')
+
+  const target = shownTarget(
+    location === undefined || location.length === 0
+      ? relationship.target
+      : `${relationship.target}#${location}`
+  )
+
+  if (target === undefined) return undefined
+
+  const display = attributes.get('display')?.trim()
+
+  return display === undefined || display.length === 0
+    ? { range, target }
+    : { range, target, display: capDisplay(display) }
+}
+
+/** A sheet of the workbook and the validated worksheet part SheetJS reads for it, if any. */
+export type HyperlinkSheet = {
+  readonly name: string
+  readonly part: string | undefined
+}
+
+/**
+ * Map the hyperlink tags removed from a workbook to its sheets (the same sheet list and worksheet
+ * parts SheetJS reads, from `buildSheetJsInput`) through each worksheet's relationships.
+ */
+export const resolveXlsxHyperlinks = (
+  parts: Readonly<Record<string, Uint8Array>>,
+  hyperlinkTags: StrippedHyperlinkTags,
+  sheets: ReadonlyArray<HyperlinkSheet>
+): XlsxHyperlinks => {
+  const bySheet = new Map<string, ReadonlyArray<XlsxHyperlink>>()
+
+  if (hyperlinkTags.size === 0) return bySheet
+
+  const index = indexParts(parts)
+  const text = (path: string) => utf8Text(index.find(path)?.bytes)
+
+  for (const { name, part } of sheets) {
+    const tags = part === undefined ? undefined : hyperlinkTags.get(part)
+
+    if (part === undefined || tags === undefined || bySheet.has(name)) continue
+
+    const sheetRelationships = relationships(text(relationshipsPathFor(part)))
+
+    const links = tags.flatMap(linkTag => {
+      const link = hyperlinkFrom(linkTag, sheetRelationships)
+
+      return link === undefined ? [] : [link]
+    })
+
+    if (links.length > 0) bySheet.set(name, links)
+  }
+
+  return bySheet
+}
+
+type ClippedLink = {
+  readonly order: number
+  readonly firstRow: number
+  readonly lastRow: number
+  readonly firstColumn: number
+  readonly lastColumn: number
+  readonly link: XlsxHyperlink
+}
+
+export type HyperlinkLookup = {
+  /** The winning link at a cell. Rows must be queried in ascending order. */
+  readonly at: (row: number, column: number) => XlsxHyperlink | undefined
+}
+
+/**
+ * Index links clipped to the visited range for row-major lookup without scanning every link per
+ * cell: a segment tree over columns whose nodes hold max-heaps (by document order) of the links
+ * covering them. Links enter when the sweep reaches their first row and are discarded lazily once
+ * it passes their last row. Work is O((links + cells) · log(columns) · log(links)).
+ */
+export const makeHyperlinkLookup = (
+  links: ReadonlyArray<XlsxHyperlink>,
+  visited: CellRange
+): HyperlinkLookup => {
+  const clipped = links
+    .flatMap((link, order): ReadonlyArray<ClippedLink> => {
+      const firstRow = Math.max(link.range.start.r, visited.start.r)
+      const lastRow = Math.min(link.range.end.r, visited.end.r)
+      const firstColumn = Math.max(link.range.start.c, visited.start.c) - visited.start.c
+      const lastColumn = Math.min(link.range.end.c, visited.end.c) - visited.start.c
+
+      return firstRow > lastRow || firstColumn > lastColumn
+        ? []
+        : [{ order, firstRow, lastRow, firstColumn, lastColumn, link }]
+    })
+    .sort((left, right) => left.firstRow - right.firstRow || left.order - right.order)
+
+  if (clipped.length === 0) return { at: () => undefined }
+
+  const width = visited.end.c - visited.start.c + 1
+  let leaves = 1
+
+  while (leaves < width) leaves *= 2
+
+  const heaps: Array<Array<ClippedLink> | undefined> = []
+
+  const push = (node: number, entry: ClippedLink) => {
+    const heap = heaps[node] ?? []
+    heaps[node] = heap
+    heap.push(entry)
+
+    let index = heap.length - 1
+
+    while (index > 0) {
+      const parent = (index - 1) >> 1
+      const parentEntry = heap[parent]
+
+      if (parentEntry === undefined || parentEntry.order >= entry.order) break
+
+      heap[index] = parentEntry
+      heap[parent] = entry
+      index = parent
+    }
+  }
+
+  const pop = (heap: Array<ClippedLink>) => {
+    const last = heap.pop()
+
+    if (last === undefined || heap.length === 0) return
+
+    heap[0] = last
+
+    let index = 0
+
+    for (;;) {
+      const left = index * 2 + 1
+      const right = left + 1
+      let largest = index
+
+      const largestOrder = () => heap[largest]?.order ?? -1
+
+      if ((heap[left]?.order ?? -1) > largestOrder()) largest = left
+
+      if ((heap[right]?.order ?? -1) > largestOrder()) largest = right
+
+      const swapped = heap[largest]
+
+      if (largest === index || swapped === undefined) return
+
+      heap[largest] = last
+      heap[index] = swapped
+      index = largest
+    }
+  }
+
+  const insert = (entry: ClippedLink) => {
+    let low = entry.firstColumn + leaves
+    let high = entry.lastColumn + leaves + 1
+
+    while (low < high) {
+      if ((low & 1) === 1) push(low++, entry)
+
+      if ((high & 1) === 1) push(--high, entry)
+
+      low >>= 1
+      high >>= 1
+    }
+  }
+
+  let nextEntry = 0
+
+  return {
+    at: (row, column) => {
+      for (let entry = clipped[nextEntry]; entry !== undefined && entry.firstRow <= row;) {
+        insert(entry)
+        nextEntry += 1
+        entry = clipped[nextEntry]
+      }
+
+      let best: ClippedLink | undefined
+
+      for (let node = column - visited.start.c + leaves; node >= 1; node >>= 1) {
+        const heap = heaps[node]
+
+        if (heap === undefined) continue
+
+        while (heap[0] !== undefined && heap[0].lastRow < row) pop(heap)
+
+        const top = heap[0]
+
+        if (top !== undefined && (best === undefined || top.order > best.order)) best = top
+      }
+
+      return best?.link
+    }
+  }
+}

package/src/node/xlsx-parts.ts

@@ -0,0 +1,83 @@
+import { Buffer } from 'node:buffer'
+import { xmlAttributes } from './xml-text.ts'
+
+/** The main workbook part every validated XLSX archive contains. */
+export const workbookPartPath = 'xl/workbook.xml'
+
+export const utf8Text = (bytes: Uint8Array | undefined) =>
+  bytes === undefined ? '' : Buffer.from(bytes).toString('utf8')
+
+/** Resolve a relationship target against the directory of its source part (`xl/`, …). */
+export const resolvePartPath = (baseDirectory: string, target: string) => {
+  const segments: Array<string> = []
+  const path = target.startsWith('/') ? target.slice(1) : `${baseDirectory}${target}`
+
+  for (const segment of path.split('/')) {
+    if (segment === '..') segments.pop()
+    else if (segment !== '.' && segment !== '') segments.push(segment)
+  }
+
+  return segments.join('/')
+}
+
+export const directoryOf = (path: string) => path.slice(0, path.lastIndexOf('/') + 1)
+
+export const relationshipsPathFor = (partPath: string) =>
+  `${directoryOf(partPath)}_rels/${partPath.slice(partPath.lastIndexOf('/') + 1)}.rels`
+
+/**
+ * Validated parts by case-insensitive name, as SheetJS and OPC look them up. Archive validation
+ * rejects names that differ only in case, so each lower-cased name has one part.
+ */
+export type PartIndex = {
+  /** The validated entry name and bytes of a part, matched ignoring case. */
+  readonly find: (path: string) => { readonly name: string; readonly bytes: Uint8Array } | undefined
+}
+
+export const indexParts = (parts: Readonly<Record<string, Uint8Array>>): PartIndex => {
+  const names = new Map<string, string>()
+
+  for (const name of Object.keys(parts)) names.set(name.toLowerCase(), name)
+
+  return {
+    find: path => {
+      const name = names.get(path.toLowerCase())
+      const bytes = name === undefined ? undefined : parts[name]
+
+      return name === undefined || bytes === undefined ? undefined : { name, bytes }
+    }
+  }
+}
+
+// `[^<>]` keeps each candidate inside one tag, so scans stay linear in the part size.
+const startTagPattern = (localName: string) =>
+  new RegExp(`<(?:[\\w.-]+:)?${localName}(?=[\\s/>])[^<>]*>`, 'g')
+
+const relationshipTag = startTagPattern('Relationship')
+
+export type Relationship = {
+  readonly target: string
+  /** The `Type` attribute as written (relationship types are case-sensitive URIs). */
+  readonly type: string | undefined
+  readonly external: boolean
+}
+
+/** Relationships by `Id`; the first relationship with an `Id` wins. */
+export const relationships = (xml: string): ReadonlyMap<string, Relationship> => {
+  const byId = new Map<string, Relationship>()
+
+  for (const [tag] of xml.matchAll(relationshipTag)) {
+    const attributes = xmlAttributes(tag)
+    const id = attributes.get('Id')
+    const target = attributes.get('Target')
+
+    if (id !== undefined && target !== undefined && !byId.has(id))
+      byId.set(id, {
+        target,
+        type: attributes.get('Type'),
+        external: attributes.get('TargetMode') === 'External'
+      })
+  }
+
+  return byId
+}

package/src/node/xlsx-range.ts

@@ -0,0 +1,70 @@
+/** Zero-based cell position. */
+export type CellPosition = {
+  readonly r: number
+  readonly c: number
+}
+
+export type CellRange = {
+  readonly start: CellPosition
+  readonly end: CellPosition
+}
+
+const maxExcelRows = 1_048_576
+
+const maxExcelColumns = 16_384
+
+const cellAddressPattern = /^([A-Z]{1,3})([1-9][0-9]{0,6})$/
+
+const cellAddress = (value: string): CellPosition | undefined => {
+  const match = cellAddressPattern.exec(value)
+
+  if (match?.[1] === undefined || match[2] === undefined) return undefined
+
+  let column = 0
+
+  for (const letter of match[1]) column = column * 26 + letter.charCodeAt(0) - 64
+
+  const row = Number(match[2])
+
+  if (!Number.isSafeInteger(row) || row > maxExcelRows || column > maxExcelColumns) return undefined
+
+  return { r: row - 1, c: column - 1 }
+}
+
+/**
+ * Strictly parse `A1` or `A1:B2` within Excel's grid. Permissive SheetJS range decoders wrap or
+ * normalize invalid and overflowed references, so they are never used on untrusted refs.
+ */
+export const parseCellRange = (ref: string): CellRange | undefined => {
+  if (ref.length > 21) return undefined
+
+  const parts = ref.split(':')
+  const first = parts[0]
+
+  if (first === undefined || parts.length > 2) return undefined
+
+  const start = cellAddress(first)
+  const end = cellAddress(parts[1] ?? first)
+
+  if (start === undefined || end === undefined || end.r < start.r || end.c < start.c)
+    return undefined
+
+  return { start, end }
+}
+
+export const cellCount = (range: CellRange) =>
+  (range.end.r - range.start.r + 1) * (range.end.c - range.start.c + 1)
+
+/** `A1`-style address of a zero-based position. */
+export const encodeCellAddress = (position: CellPosition) => {
+  let column = ''
+  let remaining = position.c + 1
+
+  while (remaining > 0) {
+    const letter = (remaining - 1) % 26
+    column = String.fromCharCode(65 + letter) + column
+    remaining = Math.floor((remaining - 1) / 26)
+  }
+
+  return `${column}${position.r + 1}`
+}

package/src/node/xlsx-routing.ts

@@ -0,0 +1,171 @@
+import { sheetJsTags, sheetJsTextViews } from './sheetjs-xml.ts'
+import type { SheetJsTag } from './sheetjs-xml.ts'
+
+/**
+ * Early, exact rejection of XLSX input that SheetJS 0.20.3 would hand to its ODS, Numbers, or
+ * binary (XLSB) parsers, so users get a clear error instead of "Could not read XLSX". These checks
+ * are not the security guarantee: SheetJS only ever receives the allowlisted archive built by
+ * `buildSheetJsInput` (`xlsx-sheetjs-input.ts`), which contains no marker entries and no `.bin`
+ * parts whatever these checks decide.
+ */
+
+/**
+ * An entry name as SheetJS looks it up: its ZIP reader (`cfb_add`) keeps a name that already
+ * starts with `Root Entry/` and otherwise stores `"Root Entry/" + name` with the first `//`
+ * collapsed; `safegetzipfile` strips `Root Entry/`, treats `\` and `/` alike, and compares
+ * lower-cased names.
+ */
+export const sheetJsEntryPath = (name: string) =>
+  (name.startsWith('Root Entry/') ? name : `Root Entry/${name}`.replace('//', '/'))
+    .replace(/^Root Entry\//, '')
+    .replaceAll('\\', '/')
+    .toLowerCase()
+
+/** Entries `parse_zip` checks before content types (SheetJS-normalized paths). */
+const alternateFormatEntries = new Set([
+  'meta-inf/manifest.xml',
+  'objectdata.xml',
+  'index/document.iwa'
+])
+
+/**
+ * Whether SheetJS would treat this entry as an ODS, UOC, or Numbers marker. `CFB.find` matches
+ * `Index.zip` by base name, and any `Root Entry/` name (any case) is rejected outright.
+ */
+export const isAlternateFormatEntry = (name: string) => {
+  const path = sheetJsEntryPath(name)
+
+  return (
+    name.toLowerCase().startsWith('root entry/') ||
+    alternateFormatEntries.has(path) ||
+    path.slice(path.lastIndexOf('/') + 1) === 'index.zip'
+  )
+}
+
+/** Whether any tag SheetJS would parse from any view of `content` satisfies `test`. */
+const someSheetJsTag = (content: Uint8Array, test: (tag: SheetJsTag) => boolean) =>
+  sheetJsTextViews(content).some(text => {
+    for (const tag of sheetJsTags(text)) {
+      if (test(tag)) return true
+    }
+
+    return false
+  })
+
+const namedEntities: ReadonlyMap<string, string> = new Map([
+  ['quot', '"'],
+  ['apos', "'"],
+  ['gt', '>'],
+  ['lt', '<'],
+  ['amp', '&']
+])
+
+/** SheetJS `unescapexml`: XML entities, numeric references, `_xHHHH_` codes, CDATA. */
+const unescapeLikeSheetJs = (text: string): string =>
+  text
+    .replace(/<!\[CDATA\[|\]\]>/g, '')
+    .replace(/&(quot|apos|gt|lt|amp|#x?[\da-f]+);/gi, (raw, entity: string) => {
+      const named = namedEntities.get(entity.toLowerCase())
+
+      if (named !== undefined) return named
+
+      const hex = entity[1] === 'x' || entity[1] === 'X'
+      const code = Number.parseInt(entity.slice(hex ? 2 : 1), hex ? 16 : 10)
+
+      return Number.isInteger(code) && code <= 0xffff ? String.fromCharCode(code) : raw
+    })
+    .replace(/_x([\da-f]{4})_/gi, (_, code: string) =>
+      String.fromCharCode(Number.parseInt(code, 16))
+    )
+
+/** SheetJS `resolve_path` from the directory of `xl/…` (only the final segment matters here). */
+const resolveLikeSheetJs = (target: string) => {
+  if (target.startsWith('/')) return target.slice(1)
+
+  const segments = ['xl']
+
+  for (const step of target.split('/')) {
+    if (step === '..') segments.pop()
+    else if (step !== '.') segments.push(step)
+  }
+
+  return segments.join('/')
+}
+
+/**
+ * Whether a `Target` or `PartName` names a path ending in `.bin`, the only suffix SheetJS hands
+ * to a binary parser. Checked raw and SheetJS-unescaped, as written and resolved.
+ */
+const namesBinaryPart = (value: string) =>
+  [value, unescapeLikeSheetJs(value)].some(
+    path =>
+      path.toLowerCase().endsWith('.bin') || resolveLikeSheetJs(path).toLowerCase().endsWith('.bin')
+  )
+
+/**
+ * Relationship types whose `.bin` targets SheetJS never parses: it follows workbook
+ * relationships only as sheets (worksheet, chartsheet, dialogsheet, macrosheet, or no type) and
+ * worksheet relationships only as comments, drawings, and legacy drawings.
+ */
+const binaryRelationshipTypes = new Set([
+  'printerSettings',
+  'oleObject',
+  'activeXControlBinary',
+  'customProperty',
+  'attachedToolbars',
+  'image',
+  'hyperlink'
+])
+
+/**
+ * Whether a relationships part has a `<Relationship>` whose `Target` ends in `.bin` and whose
+ * `Type` (read exactly as SheetJS reads it: case-sensitive, missing counts as a sheet) is not on
+ * the allowlist.
+ */
+export const relationshipsRouteToBinary = (content: Uint8Array) =>
+  someSheetJsTag(content, ({ head, attributes }) => {
+    const target = attributes.get('Target')
+
+    if (head !== '<Relationship' || target === undefined || !namesBinaryPart(target)) return false
+
+    const type = attributes.get('Type')
+
+    return type === undefined || !binaryRelationshipTypes.has(type.slice(type.lastIndexOf('/') + 1))
+  })
+
+/** Content types of `.bin` parts SheetJS never parses, lower-cased. */
+const binaryPartContentTypes = new Set([
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.printersettings',
+  'application/vnd.ms-office.activex',
+  'application/vnd.openxmlformats-officedocument.oleobject',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.customproperty',
+  'application/vnd.ms-excel.attachedtoolbars'
+])
+
+/** XLSB part types: `application/vnd.ms-excel.*` without an `+xml` suffix (toolbars excepted). */
+const isBinarySpreadsheetType = (contentType: string) =>
+  contentType.startsWith('application/vnd.ms-excel.') &&
+  !contentType.endsWith('+xml') &&
+  !binaryPartContentTypes.has(contentType)
+
+/**
+ * Whether `[Content_Types].xml` has an `<Override>` (any prefix, as SheetJS reads it) with an
+ * XLSB content type, or a `PartName` ending in `.bin` whose content type is not on the allowlist.
+ * `<Default>` entries are ignored: SheetJS does not route by them, and its own XLSX writer emits
+ * `<Default Extension="bin">` with the XLSB workbook type.
+ */
+export const contentTypesRouteToBinary = (content: Uint8Array) =>
+  someSheetJsTag(content, ({ head, attributes }) => {
+    if (head.replace(/<\w*:/, '<') !== '<Override') return false
+
+    const contentType = attributes.get('ContentType')?.toLowerCase()
+    const partName = attributes.get('PartName')
+
+    if (contentType !== undefined && isBinarySpreadsheetType(contentType)) return true
+
+    return (
+      partName !== undefined &&
+      namesBinaryPart(partName) &&
+      (contentType === undefined || !binaryPartContentTypes.has(contentType))
+    )
+  })