import { loadBuffer } from 'cheerio'; import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, writeFileSync } from 'node:fs'; import { join } from 'node:path'; import { fileURLToPath, URL } from 'node:url'; /** @typedef {{sku: string, name: string, priceCents: number, quantity: number, url: string}} StockItem */ /** @typedef {{schemaVersion: 1, sourceKind: 'local-fixture', revision: string, title: string, introduction: string, currency: 'USD', notes: string[], items: StockItem[]}} StockSnapshot */ const projectRoot = fileURLToPath(new URL('../', import.meta.url)); const inputPath = join(projectRoot, 'fixtures/catalog.html'); const outputDirectory = join(projectRoot, 'output'); const outputPath = join(outputDirectory, 'catalog.json'); const temporaryPath = join(outputDirectory, 'catalog.json.tmp'); const maxInputBytes = 128 * 1024; const maxOutputBytes = 8000; const baseUrl = new URL('https://catalog.example/stock/'); const canonicalLink = /^https:\/\/catalog\.example\/stock\/items\/[a-z-]+\.html(?:\?[a-z0-9=&-]+)?$/; /** @param {unknown} value @returns {value is Record} */ function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); } /** @param {unknown} value @param {string} label @param {number} maximum */ function textField(value, label, maximum) { if (typeof value !== 'string') { throw new Error(`${label}: missing text.`); } const text = value.replace(/\s+/gu, ' ').trim(); if (!text || text.length > maximum || /[\u0000-\u001f\u007f\ufffd]/u.test(text)) { throw new Error(`${label}: expected 1 through ${maximum} characters without controls or decoding replacement characters.`); } return text; } /** @param {unknown} value @param {string} label */ function catalogUrl(value, label) { if (typeof value !== 'string' || !value || value.length > 512 || /[\u0000-\u0020\u007f]/u.test(value)) { throw new Error(`${label}: missing or invalid href.`); } const url = new URL(value, baseUrl); if (url.origin !== baseUrl.origin || url.username || url.password) { throw new Error(`${label}: link must use the approved HTTPS origin without credentials.`); } url.hash = ''; if (!canonicalLink.test(url.href) || url.href.length > 512) { throw new Error(`${label}: unsupported catalog path or query.`); } return url.href; } /** @param {string} text @param {string} label */ function priceInCents(text, label) { const match = /^\$(0|[1-9][0-9]{0,2})\.([0-9]{2})$/.exec(text); if (!match) { throw new Error(`${label}: expected a USD price such as $3.50.`); } const cents = Number(match[1]) * 100 + Number(match[2]); if (cents > 10000) { throw new Error(`${label}: price exceeds $100.00.`); } return cents; } /** @returns {Buffer} */ function readBoundedInput() { const entry = lstatSync(inputPath); if (!entry.isFile() || entry.isSymbolicLink()) { throw new Error('fixtures/catalog.html must be an ordinary file, not a symlink.'); } const descriptor = openSync(inputPath, 'r'); try { const stat = fstatSync(descriptor); if (!stat.isFile() || stat.size > maxInputBytes) { throw new Error('HTML input exceeds the 128 KiB file limit.'); } const buffer = Buffer.alloc(maxInputBytes + 1); let length = 0; while (length < buffer.length) { const count = readSync(descriptor, buffer, length, buffer.length - length, null); if (count === 0) break; length += count; } if (length === 0 || length > maxInputBytes) { throw new Error('HTML input must contain 1 through 131072 bytes.'); } return buffer.subarray(0, length); } finally { closeSync(descriptor); } } /** @param {Buffer} input @returns {StockSnapshot} */ function extractSnapshot(input) { const $ = loadBuffer(input, { scriptingEnabled: false, encoding: { defaultEncoding: 'utf-8' }, }); const metadataElements = $('script#catalog-metadata[type="application/json"]'); if (metadataElements.length !== 1) { throw new Error('Expected exactly one JSON catalog-metadata element.'); } /** @type {unknown} */ const metadata = JSON.parse(metadataElements.text()); if (!isRecord(metadata) || metadata.currency !== 'USD') { throw new Error('Catalog metadata must declare currency USD.'); } const revision = textField(metadata.revision, 'Catalog revision', 32); if (!/^[a-z0-9-]+$/.test(revision)) { throw new Error('Catalog revision must use lowercase letters, digits, and hyphens.'); } // Exclude non-content nodes from text extraction, not to execute or sanitize HTML. $('script, style, template, noscript').remove(); if ($('title').length !== 1 || $('#catalog-intro').length !== 1 || $('ul#stock-notes').length !== 1) { throw new Error('Expected one title, catalog-intro paragraph, and stock-notes list.'); } const title = textField($('title').text(), 'Title', 120); const introduction = textField($('#catalog-intro').text(), 'Introduction', 240); const noteElements = $('ul#stock-notes').children('li'); if (noteElements.length < 1 || noteElements.length > 5) { throw new Error('Expected 1 through 5 stock notes.'); } const notes = noteElements.toArray().map((element, index) => textField($(element).text(), `Note ${index + 1}`, 160)); const table = $('table#stock'); if (table.length !== 1 || table.find('table, [rowspan], [colspan]').length !== 0 || table.children('tfoot').length !== 0) { throw new Error('Expected one stock table without nested tables, merged cells, or a footer.'); } const headerRows = table.children('thead').children('tr'); const expectedHeaders = ['Item', 'Price', 'In stock', 'Details']; const headers = headerRows.children('th').toArray().map((element) => textField($(element).text(), 'Header', 40)); if (table.children('thead').length !== 1 || headerRows.length !== 1 || headerRows.children().length !== 4 || headers.length !== 4 || headers.some((header, index) => header !== expectedHeaders[index])) { throw new Error('Stock headers must be Item, Price, In stock, Details.'); } const bodies = table.children('tbody'); const rows = bodies.children('tr'); if (bodies.length !== 1 || rows.length < 1 || rows.length > 20) { throw new Error('Expected one stock body with 1 through 20 item rows.'); } /** @type {StockItem[]} */ const items = []; /** @type {Set} */ const seen = new Set(); rows.each((index, element) => { const row = $(element); const label = `Item row ${index + 1}`; const sku = textField(row.attr('data-sku'), `${label} SKU`, 7); if (!/^KIT-[0-9]{3}$/.test(sku) || seen.has(sku)) { throw new Error(`${label}: SKU must be unique and have the form KIT-001.`); } seen.add(sku); const cells = row.children('td'); if (cells.length !== 4 || row.children().length !== 4 || !cells.eq(1).hasClass('price') || !cells.eq(2).hasClass('quantity')) { throw new Error(`${label}: expected four unmerged cells with price and quantity in their declared columns.`); } const nameElement = cells.eq(0).find('.item-name'); const linkElement = cells.eq(3).find('a.details'); if (nameElement.length !== 1 || linkElement.length !== 1) { throw new Error(`${label}: expected one item-name and one details link.`); } const name = textField(nameElement.text(), `${label} name`, 120); const priceCents = priceInCents(textField(cells.eq(1).text(), `${label} price`, 12), label); const quantityText = textField(cells.eq(2).text(), `${label} quantity`, 3); if (!/^(0|[1-9][0-9]{0,2})$/.test(quantityText) || Number(quantityText) > 100) { throw new Error(`${label}: quantity must be an integer from 0 through 100.`); } const url = catalogUrl(linkElement.attr('href'), `${label} details`); items.push({ sku, name, priceCents, quantity: Number(quantityText), url }); }); items.sort((a, b) => a.sku < b.sku ? -1 : a.sku > b.sku ? 1 : 0); return { schemaVersion: 1, sourceKind: 'local-fixture', revision, title, introduction, currency: 'USD', notes, items }; } function prepareOutputDirectory() { const entry = lstatSync(outputDirectory, { throwIfNoEntry: false }); if (entry && (!entry.isDirectory() || entry.isSymbolicLink())) { throw new Error('output must be an ordinary directory, not a file or symlink.'); } if (!entry) mkdirSync(outputDirectory); } function cleanGeneratedFiles() { const paths = [outputPath, temporaryPath]; for (const path of paths) { const entry = lstatSync(path, { throwIfNoEntry: false }); if (entry && (!entry.isFile() || entry.isSymbolicLink())) { throw new Error('Refusing cleanup: a generated output path is not an ordinary file.'); } } for (const path of paths) rmSync(path, { force: true }); } const args = process.argv.slice(2); if (args.length > 1 || (args.length === 1 && args[0] !== '--clean')) { throw new Error('Use npm run extract or npm run clean; no input URL or output path is accepted.'); } prepareOutputDirectory(); cleanGeneratedFiles(); if (args[0] === '--clean') { console.log('Removed only output/catalog.json and output/catalog.json.tmp.'); } else { try { const snapshot = extractSnapshot(readBoundedInput()); const json = JSON.stringify(snapshot, null, 2) + '\n'; if (Buffer.byteLength(json, 'utf8') > maxOutputBytes) { throw new Error('JSON output exceeds the 8000-byte transfer limit.'); } writeFileSync(temporaryPath, json, { encoding: 'utf8', flag: 'wx' }); renameSync(temporaryPath, outputPath); console.log(`Extracted ${snapshot.items.length} items -> output/catalog.json (no network requests).`); } catch (error) { cleanGeneratedFiles(); throw error; } }