hyper-html-api 0.13.0 → 0.15.0

package/src/patch-document.js

@@ -0,0 +1,122 @@
+import cheerioAdapter from './adapters/cheerio.js'
+import { checkCodecRules } from './engine/codecs.js'
+import { CodecRefused, NoRulesTag } from './engine/errors.js'
+import { findRulesIn } from './engine/rules-tag.js'
+import { codecOf } from './engine/rule-syntax.js'
+import { pickTab, sheet, tabNodes } from './codecs/sheet.js'
+import { CodecMiss, QueryRefused, holeMarker, patchGrid, scanGrid } from './codecs/sheet.vendor.js'
+import { holesHold } from './read.js'
+
+export const NOT_CANONICAL_MESSAGE =
+  'This sheet was edited outside the sheet editor, so the API cannot patch it: open the sheet in the editor and save once.'
+
+// Applies a patch list to a sheet document's source, rewriting only the rows it
+// touches. `load` is cheerio.load. patch is
+//   [{ sheet?, range: "B3", values: [[450]] } | { sheet?, append: [["Porto", 12]] }]
+// where `sheet` is a tab name or id (none means the first tab). Values are typed
+// input: null clears, a number or boolean is that value, a string starting with
+// "=" is a formula, any other string is text.
+//
+// options.newId() names appended rows (default: random ids); a test or the
+// conformance runner passes a counter so the output is the same on every run.
+//
+// Returns { html, changed: { cells, rows }, stale: true }: the host cannot
+// recalculate, so every patched table carries `stale` until a browser saves it.
+// Throws before producing output: NoRulesTag; RulesParseError or UnknownCodec for
+// a rules tag that cannot hold a sheet; CodecRefused 'no-sheet' when no single
+// sheet rule matches; QueryRefused (bad_patch, bad_value, bad_range,
+// outside_sheet, covered_cell, unknown_sheet) for a patch the sheet cannot take;
+// CodecRefused 'sheet-not-canonical' (hosts answer 409) for a table edited
+// outside the editor.
+export function patchDocument(load, src, patch, options = {}) {
+  const { token = 'api', newId } = options
+  if (!Array.isArray(patch) || patch.length === 0) {
+    throw new QueryRefused('bad_patch', 'patch is a non-empty list of operations')
+  }
+  const tabs = locateTabs(load, src, token)
+
+  const groups = new Map()
+  for (const op of patch) {
+    if (!op || typeof op !== 'object' || Array.isArray(op)) {
+      throw new QueryRefused('bad_patch', 'an operation is { sheet, range, values } or { sheet, append }')
+    }
+    const { sheet: wanted, ...gridOp } = op
+    const tab = pickTab(tabs, wanted)
+    if (!groups.has(tab)) groups.set(tab, [])
+    groups.get(tab).push(gridOp)
+  }
+
+  const edits = []
+  let cells = 0
+  let rows = 0
+  for (const [tab, ops] of groups) {
+    if (!tab.region) throw new CodecRefused('sheet-not-canonical', NOT_CANONICAL_MESSAGE)
+    const { bytes, changed } = patchGrid(src.slice(tab.region.start, tab.region.end), ops, newId ? { newId } : {})
+    edits.push({ ...tab.region, bytes })
+    cells += changed.cells
+    rows += changed.rows
+  }
+
+  edits.sort((a, b) => b.start - a.start)
+  let html = src
+  for (const edit of edits) html = html.slice(0, edit.start) + edit.bytes + html.slice(edit.end)
+  return { html, changed: { cells, rows }, stale: true }
+}
+
+// [{ id, name, region: { start, end } | null }]: region is where the tab's
+// canonical table sits in src, or null when the table is missing or not canonical.
+// The cut route first, as readDocument reads; when its holes do not verify, one
+// parse with source positions, then a strict scan at each table's start.
+function locateTabs(load, src, token) {
+  const marker = holeMarker(src)
+  const { rest, regions } = sheet.cut(src, marker)
+  if (regions.length > 0) {
+    const $ = load(rest)
+    const root = $.root()
+    const found = findRulesIn(cheerioAdapter, root, token)
+    if (!found) throw new NoRulesTag(token)
+    const container = sheetContainer(root, found)
+    if (holesHold($, root, found.rules, 'sheet', marker, regions.length)) {
+      return tabNodes(cheerioAdapter, container).map(({ id, name, table }) => ({
+        id, name, region: table ? holeRegion(table, marker, regions) : null,
+      }))
+    }
+  }
+
+  const root = load(src, { sourceCodeLocationInfo: true }).root()
+  const found = findRulesIn(cheerioAdapter, root, token)
+  if (!found) throw new NoRulesTag(token)
+  const container = sheetContainer(root, found)
+  return tabNodes(cheerioAdapter, container).map(({ id, name, table }) => ({
+    id, name, region: table ? scannedRegion(table, src) : null,
+  }))
+}
+
+function sheetContainer(root, found) {
+  checkCodecRules(found.rules, { version: found.version, codecs: { sheet } })
+  const rules = found.rules
+  const forms = rules && typeof rules === 'object' && !Array.isArray(rules)
+    ? Object.values(rules).map(codecOf).filter((form) => form && form.name === 'sheet')
+    : []
+  if (forms.length !== 1) throw new CodecRefused('no-sheet', 'this document has no single @codec(sheet) rule to patch')
+  const node = forms[0].selector ? cheerioAdapter.find(root, forms[0].selector)[0] : root
+  if (!node) throw new CodecRefused('no-sheet', "the document's @codec(sheet) rule matches no element")
+  return node
+}
+
+function holeRegion(table, marker, regions) {
+  const hole = cheerioAdapter.attr(table, 'data-hole')
+  if (!hole || !hole.startsWith(`${marker}-`)) return null
+  return regions[Number(hole.slice(marker.length + 1))] ?? null
+}
+
+function scannedRegion(table, src) {
+  const start = table.get(0)?.sourceCodeLocation?.startOffset
+  if (start == null) return null
+  try {
+    return { start, end: scanGrid(src, start) }
+  } catch (error) {
+    if (error instanceof CodecMiss) return null
+    throw error
+  }
+}

package/src/read.js

@@ -0,0 +1,163 @@
+import cheerioAdapter from './adapters/cheerio.js'
+import { extract } from './engine/extract.js'
+import { findRulesIn } from './engine/rules-tag.js'
+import { codecOf } from './engine/rule-syntax.js'
+import { sheet } from './codecs/sheet.js'
+import { checkCodecRules } from './engine/codecs.js'
+import { holeMarker, QueryRefused } from './codecs/sheet.vendor.js'
+
+// The URL parameters a host passes to readDocument as `query`, from a
+// URLSearchParams. Returns null when none of them is present (a whole read,
+// exactly as before). Each may appear once with a value, and none may be
+// mixed with ?data= (a caller-supplied rule set); anything else is
+// QueryRefused('bad_query'), which hosts answer with 400. Values are not
+// checked here: readDocument refuses a bad one with its own code.
+export const SHEET_QUERY_PARAMS = ['shape', 'sheet', 'range', 'render']
+
+export function parseSheetQuery(params) {
+  const query = {}
+  for (const key of SHEET_QUERY_PARAMS) {
+    const values = params.getAll(key)
+    if (values.length === 0) continue
+    if (values.length > 1) throw new QueryRefused('bad_query', `${key} appears ${values.length} times; send it once`)
+    if (values[0] === '') throw new QueryRefused('bad_query', `${key} is empty; give it a value or leave it out`)
+    query[key] = values[0]
+  }
+  if (Object.keys(query).length === 0) return null
+  if (params.has('data')) throw new QueryRefused('bad_query', `data cannot be combined with ${Object.keys(query).join(', ')}; a sheet query reads the document's own rules`)
+  return query
+}
+
+// Reads a document's data through its rules tag, from source. `load` is
+// cheerio.load, passed in so this package keeps cheerio out of its browser
+// bundles. Returns { data, version, fast }; data is null when no rules tag
+// carries `token`.
+//
+// A codec with cut() lets a host skip parsing its regions: the source is cut,
+// only the rest is parsed, and each hole hands the codec its region's bytes.
+// The holes are verified first: every hole is a real element, each index
+// appears exactly once and in order, and every hole lies under the element a
+// rule naming that codec selected, which only that codec reads. Anything else
+// (a grid inside a comment, a script or a textarea, a grid outside the sheet)
+// discards the cut and reads the whole source through the tree. `fast` is false whenever a
+// `<table grid` was read through the tree (that fallback, or a hand-edited table
+// the cut left in place), so a host can count how often the slow route runs.
+//
+// options: { token = 'api', query, view, codecs = { sheet } }. query and view
+// reach every codec rule (see src/codecs/sheet.js for the sheet's shapes).
+export function readDocument(load, src, options = {}) {
+  const { token = 'api', query, view, codecs = { sheet } } = options
+  const call = { codecs, query, view }
+  const cutting = Object.entries(codecs).filter(([, codec]) => typeof codec.cut === 'function')
+  if (cutting.length > 1) throw new Error('hyper-html-api: readDocument supports one codec with cut()')
+
+  if (cutting.length === 1) {
+    const [name, codec] = cutting[0]
+    const marker = holeMarker(src)
+    const { rest, regions } = codec.cut(src, marker)
+    if (regions.length > 0) {
+      const $ = load(rest)
+      const root = $.root()
+      const found = findRulesIn(cheerioAdapter, root, token)
+      const fast = countGrids(rest) === regions.length
+      if (!found) return { data: null, version: null, fast }
+      if (codec === sheet && readHolesHold($, root, found.rules, name, marker, regions.length)) {
+        const region = (table) => regionBytes(table, src, marker, regions)
+        const opts = { ...call, version: found.version, region }
+        checkCodecRules(found.rules, opts)
+        let tree
+        const data = {}
+        for (const [key, rule] of Object.entries(found.rules)) {
+          const codec = codecOf(rule)
+          const context = codec ? root : (tree ??= load(src).root())
+          data[key] = extract(cheerioAdapter, context, { [key]: rule }, { ...opts, region: codec ? region : undefined })[key]
+        }
+        return { data, version: found.version, fast }
+      }
+    }
+  }
+
+  const fast = !src.includes(GRID)
+
+  const root = load(src).root()
+  const found = findRulesIn(cheerioAdapter, root, token)
+  if (!found) return { data: null, version: null, fast }
+  return { data: extract(cheerioAdapter, root, found.rules, { ...call, version: found.version }), version: found.version, fast }
+}
+
+// A document's rules tag as { rules, version }, or null when no tag carries
+// `token`, without parsing its canonical tables: what a host needs to classify
+// a request body (isPatchBody) before it reads or patches. Same cut and checks
+// as readDocument; anything they reject is found by parsing the whole source.
+export function documentRules(load, src, options = {}) {
+  const { token = 'api', codecs = { sheet } } = options
+  const cutting = Object.entries(codecs).filter(([, codec]) => typeof codec.cut === 'function')
+  if (cutting.length === 1) {
+    const [name, codec] = cutting[0]
+    const marker = holeMarker(src)
+    const { rest, regions } = codec.cut(src, marker)
+    if (regions.length > 0) {
+      const $ = load(rest)
+      const root = $.root()
+      const found = findRulesIn(cheerioAdapter, root, token)
+      if (!found) return null
+      if (holesHold($, root, found.rules, name, marker, regions.length)) return { rules: found.rules, version: found.version }
+    }
+  }
+  const found = findRulesIn(cheerioAdapter, load(src).root(), token)
+  return found ? { rules: found.rules, version: found.version } : null
+}
+
+const GRID = '<table grid'
+
+function countGrids(text) {
+  let n = 0
+  for (let at = text.indexOf(GRID); at !== -1; at = text.indexOf(GRID, at + 1)) n++
+  return n
+}
+
+export function holesHold($, root, rules, name, marker, count) {
+  const holes = $('table[data-hole]').toArray()
+  if (holes.length !== count) return false
+  const containers = codecContainers(root, rules, name)
+  if (containers.length === 0) return false
+  return holes.every((hole, n) =>
+    hole.attribs['data-hole'] === `${marker}-${n}` &&
+    containers.some((container) => container === hole || $.contains(container, hole)))
+}
+
+// Only this selector cannot match within canonical grid bytes or depend on their children.
+const SHEET_CONTAINER = /^\[items\s*=\s*(?:sheets|"sheets"|'sheets')\]$/
+
+function readHolesHold($, root, rules, name, marker, count) {
+  if (!rules || typeof rules !== 'object' || Array.isArray(rules)) return false
+  for (const rule of Object.values(rules)) {
+    const form = codecOf(rule)
+    if (form && (form.name !== name || !SHEET_CONTAINER.test(form.selector))) return false
+  }
+  if (!holesHold($, root, rules, name, marker, count)) return false
+  const containers = new Set(codecContainers(root, rules, name))
+  return $('table[grid]').length === count && $('table[data-hole]').toArray().every(hole =>
+    hole.parent?.name === 'section' && Object.hasOwn(hole.parent.attribs, 'item') && containers.has(hole.parent.parent))
+}
+
+// The element each top level `selector@codec(name)` rule selects, as the engine
+// would read it: the first match, or the document itself for a bare "@codec(name)".
+function codecContainers(root, rules, name) {
+  if (!rules || typeof rules !== 'object' || Array.isArray(rules)) return []
+  const out = []
+  for (const rule of Object.values(rules)) {
+    const form = codecOf(rule)
+    if (!form || form.name !== name) continue
+    const node = form.selector ? cheerioAdapter.find(root, form.selector)[0] : root
+    if (node && node.get(0)) out.push(node.get(0))
+  }
+  return out
+}
+
+function regionBytes(table, src, marker, regions) {
+  const hole = cheerioAdapter.attr(table, 'data-hole')
+  if (!hole || !hole.startsWith(`${marker}-`)) return null
+  const region = regions[Number(hole.slice(marker.length + 1))]
+  return region ? src.slice(region.start, region.end) : null
+}

package/src/site.js

@@ -0,0 +1,164 @@
+import cheerioAdapter from './adapters/cheerio.js'
+import { extract } from './engine/extract.js'
+import { findRulesIn } from './engine/rules-tag.js'
+import { splitRule } from './engine/rule-syntax.js'
+import { writeDocument } from './write.js'
+
+export const SITE_KEY = 'site'
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// The part of `value` that `rule` declares. Keys the rule does not name are
+// dropped at every level, because the writer refuses unknown keys and a store
+// holds keys other pages use. A key the store does not hold stays absent, and
+// the writer skips an absent key, so the page keeps what it has.
+export function projectSite(rule, value) {
+  if (isPlainObject(rule)) {
+    if (!isPlainObject(value)) return value
+    const out = {}
+    for (const key of Object.keys(rule)) {
+      if (value[key] !== undefined) out[key] = projectSite(rule[key], value[key])
+    }
+    return out
+  }
+  if (Array.isArray(rule) && Array.isArray(value)) {
+    return value.map((item) => projectSite(rule[1], item))
+  }
+  return value
+}
+
+// Writes the store's values into a page through the page's own `site` rule.
+// Never throws for a page problem: a key that cannot be written is listed in
+// `failed` and the other keys still land. `declared` is false when the page has
+// no rules tag or no `site` object in it, and then `html` is `src`.
+export function writeSite(load, src, store, options = {}) {
+  const { token = 'api' } = options
+  const none = { html: src, changed: false, declared: false, applied: [], failed: [] }
+  if (!isPlainObject(store)) return none
+  let found
+  try {
+    found = findRulesIn(cheerioAdapter, load(src).root(), token)
+  } catch (error) {
+    return { ...none, declared: true, failed: [{ key: null, code: error.name, message: error.message }] }
+  }
+  if (!found || !isPlainObject(found.rules) || !isPlainObject(found.rules[SITE_KEY])) return none
+  const data = projectSite(found.rules[SITE_KEY], store)
+  const keys = Object.keys(data)
+  if (keys.length === 0) return { ...none, declared: true }
+  const write = (html, part) => writeDocument(load, html, { [SITE_KEY]: part }, { token, rules: found.rules }).html
+  try {
+    const html = write(src, data)
+    return { html, changed: html !== src, declared: true, applied: keys, failed: [] }
+  } catch {
+    // One key failed. Write them one at a time so the rest still land.
+  }
+  let html = src
+  const applied = []
+  const failed = []
+  for (const key of keys) {
+    try {
+      html = write(html, { [key]: data[key] })
+      applied.push(key)
+    } catch (error) {
+      failed.push({ key, code: error.name, message: error.message })
+    }
+  }
+  return { html, changed: html !== src, declared: true, applied, failed }
+}
+
+// The same rule with each attribute read turned into a read of its element's text, which is
+// null exactly where the element is missing: a missing element can then be told apart from
+// an element without the attribute, which both read as a null attribute.
+function presenceRule(rule) {
+  if (typeof rule === 'string') {
+    const { selector, prop } = splitRule(rule)
+    return prop && !prop.endsWith('[]') ? (selector || '.') : rule
+  }
+  if (Array.isArray(rule)) return rule.length < 2 ? rule : [rule[0], presenceRule(rule[1])]
+  if (isPlainObject(rule)) return Object.fromEntries(Object.entries(rule).map(([key, value]) => [key, presenceRule(value)]))
+  return rule
+}
+
+// The page's own `site` rule and the values the page holds for it right now, read key by
+// key: a key whose rule cannot be read (a broken selector) is listed in `broken` and left
+// out of `data`, and the other keys still read. `present` mirrors `data` for
+// siteValueProblem. Never throws: a page with no rules tag, or no `site` key, declares nothing.
+export function readSite(load, src, options = {}) {
+  const { token = 'api' } = options
+  const none = { declared: false, rule: null, data: {}, present: {}, broken: [] }
+  let root
+  let found
+  try {
+    root = load(src).root()
+    found = findRulesIn(cheerioAdapter, root, token)
+  } catch {
+    return none
+  }
+  if (!found || !isPlainObject(found.rules) || !isPlainObject(found.rules[SITE_KEY])) return none
+  const rule = found.rules[SITE_KEY]
+  const read = (keyRule, key) => extract(cheerioAdapter, root, { [key]: keyRule }, { templateAttr: 'cms-template' })[key]
+  const data = {}
+  const present = {}
+  const broken = []
+  for (const key of Object.keys(rule)) {
+    try {
+      data[key] = read(rule[key], key)
+      present[key] = read(presenceRule(rule[key]), key)
+    } catch {
+      delete data[key]
+      broken.push(key)
+    }
+  }
+  return { declared: true, rule, data, present, broken }
+}
+
+// Why a value read from a page must not be written to the store, or null when it may.
+// A text rule that matched no element reads null, and an emptied list cannot be regrown
+// by writeSite, so both would damage every other page. A null attribute is a real value:
+// it means the attribute is absent, unless `present` (readSite's mirror of the value) shows
+// that the attribute's element is missing too.
+export function siteValueProblem(rule, value, present) {
+  if (typeof rule === 'string') {
+    if (rule.endsWith('[]')) {
+      if (!Array.isArray(value)) return 'unreadable'
+      return value.length === 0 ? 'empty-list' : null
+    }
+    if (value !== null) return null
+    return splitRule(rule).prop === null || present === null ? 'unreadable' : null
+  }
+  if (Array.isArray(rule)) {
+    if (!Array.isArray(value)) return 'unreadable'
+    if (value.length === 0) return 'empty-list'
+    if (rule.length < 2) return null
+    for (const [index, row] of value.entries()) {
+      const problem = siteValueProblem(rule[1], row, Array.isArray(present) ? present[index] : undefined)
+      if (problem) return problem
+    }
+    return null
+  }
+  if (isPlainObject(rule)) {
+    if (!isPlainObject(value)) return 'unreadable'
+    for (const key of Object.keys(rule)) {
+      const problem = siteValueProblem(rule[key], value[key], isPlainObject(present) ? present[key] : undefined)
+      if (problem) return problem
+    }
+    return null
+  }
+  return 'unreadable'
+}
+
+// The store's next value for one key after a page edit. An object keeps the fields the
+// page's rule does not name, because other pages use them. A list is taken whole from
+// the page: rows have no identity to merge by.
+export function mergeSiteEdit(rule, stored, edited) {
+  if (isPlainObject(rule) && isPlainObject(edited)) {
+    const out = isPlainObject(stored) ? { ...stored } : {}
+    for (const key of Object.keys(rule)) {
+      if (edited[key] !== undefined) out[key] = mergeSiteEdit(rule[key], out[key], edited[key])
+    }
+    return out
+  }
+  return edited
+}

package/src/upgrade/codec-carry.js

@@ -0,0 +1,23 @@
+import { codecOf } from '../engine/rule-syntax.js'
+
+// Under a version 2 rules tag, a top level `@codec(name)` key (a sheet) is
+// carried whole on upgrade: the extract side keeps its container's markup as
+// a string, and the migrate side puts that string into the same key's
+// container in the new template. The value is never read into data and
+// written back, so the codec needs no whole-value write and the canonical
+// bytes its grammar reads stay as they were.
+export function splitCarried(rules, version) {
+  if (version !== '2' || !rules || typeof rules !== 'object' || Array.isArray(rules)) return { rules, carried: [] }
+  const rest = {}
+  const carried = []
+  for (const [key, rule] of Object.entries(rules)) {
+    const codec = codecOf(rule)
+    if (codec) carried.push({ key, selector: codec.selector })
+    else rest[key] = rule
+  }
+  return { rules: rest, carried }
+}
+
+export function carriedNode(adapter, root, selector) {
+  return adapter.find(root, selector)[0] || null
+}

package/src/upgrade/extract-all.js

@@ -1,17 +1,26 @@
 import { extract } from '../engine/extract.js'
 import domAdapter from '../adapters/dom.js'
 import { collectRulesTags } from './rules-tags.js'
+import { splitCarried, carriedNode } from './codec-carry.js'
 import { readMeta } from './check.js'
 
 /**
  * Keyed extraction: one entry per rules tag under `root`, keyed by the
  * normalized data-rules-name value. This is the v1 side of an upgrade:
- * pack the page's data into labeled boxes.
+ * pack the page's data into labeled boxes. A `@codec(name)` key (a sheet,
+ * version 2 tags only) packs as its container's markup string, which a
+ * transform passes through unchanged.
  */
 export function extractAllFrom(adapter, root) {
   const dataByName = {}
-  for (const { name, rules } of collectRulesTags(adapter, root)) {
-    dataByName[name] = extract(adapter, root, rules)
+  for (const { name, rules, version } of collectRulesTags(adapter, root)) {
+    const { rules: plain, carried } = splitCarried(rules, version)
+    const data = extract(adapter, root, plain, { version })
+    for (const { key, selector } of carried) {
+      const node = carriedNode(adapter, root, selector)
+      data[key] = node ? adapter.prop(node, 'innerHTML') : null
+    }
+    dataByName[name] = data
   }
   return dataByName
 }

package/src/upgrade/migrate.js

@@ -1,12 +1,15 @@
 import { apply } from '../engine/apply.js'
 import { collectRulesTags } from './rules-tags.js'
 import { shapeMatch, countScalarLeaves } from './shape-match.js'
+import { splitCarried, carriedNode } from './codec-carry.js'
 
 /**
  * Pour keyed v1 data into the v2 document. Exact-name join: each v2 rules
  * tag pulls the entry with the same normalized name; tags with no matching
  * entry keep their template defaults; v1 entries with no matching tag are
  * counted as discarded. Renames are the transform's job, not the join's.
+ * A `@codec(name)` key takes its markup string whole into the new
+ * template's container for that key.
  */
 export function migrateInto(adapter, root, dataByName) {
   const tags = collectRulesTags(adapter, root)
@@ -14,14 +17,28 @@ export function migrateInto(adapter, root, dataByName) {
   const byName = {}
   const v2Names = new Set()
 
-  for (const { name, rules } of tags) {
+  for (const { name, rules, version } of tags) {
     v2Names.add(name)
     if (!Object.prototype.hasOwnProperty.call(dataByName, name)) {
       byName[name] = { carriedOver: 0, discarded: 0, listItems: 0 }
       continue
     }
-    const { data, summary } = shapeMatch(dataByName[name], rules)
-    apply(adapter, root, rules, data)
+    const { rules: plain, carried } = splitCarried(rules, version)
+    const entry = dataByName[name]
+    const { data, summary } = shapeMatch(withoutCarried(entry, carried), plain)
+    // A row whose nested list is empty at that spot in v2 grows from the page's seeds, as a write does.
+    apply(adapter, root, plain, data, { templateAttr: 'cms-template' })
+    for (const { key, selector } of carried) {
+      const markup = isPlainObject(entry) ? entry[key] : undefined
+      if (markup === undefined || markup === null) continue
+      const node = carriedNode(adapter, root, selector)
+      if (typeof markup === 'string' && node) {
+        adapter.prop(node, 'innerHTML', markup)
+        summary.carriedOver += 1
+      } else {
+        summary.discarded += 1
+      }
+    }
     byName[name] = summary
     totals.carriedOver += summary.carriedOver
     totals.discarded += summary.discarded
@@ -34,3 +51,14 @@ export function migrateInto(adapter, root, dataByName) {
 
   return { totals, byName, rulesTagCount: tags.length }
 }
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function withoutCarried(entry, carried) {
+  if (!carried.length || !isPlainObject(entry)) return entry
+  const rest = { ...entry }
+  for (const { key } of carried) delete rest[key]
+  return rest
+}

package/src/upgrade/rules-tags.js

@@ -1,5 +1,5 @@
 import { parseRelaxed } from '../engine/rules.js'
-import { SUPPORTED_VERSION } from '../engine/rules-tag.js'
+import { SUPPORTED_VERSIONS } from '../engine/rules-tag.js'
 import { UnknownRulesVersion } from '../engine/errors.js'
 
 const RULES_SELECTOR = 'script[data-rules-name]'
@@ -9,7 +9,7 @@ export function normalizeName(raw) {
 }
 
 /**
- * Collect every rules tag under `root` as [{ name, rules }], keyed by the
+ * Collect every rules tag under `root` as [{ name, rules, version }], keyed by the
  * whitespace-normalized data-rules-name attribute value. Duplicate names:
  * first tag wins with a warning (mirrors findRulesIn). Unsupported
  * data-rules-version throws so engine-format skew fails loudly instead of
@@ -29,9 +29,9 @@ export function collectRulesTags(adapter, root) {
       continue
     }
     const version = adapter.attr(tag, 'data-rules-version')
-    if (version !== SUPPORTED_VERSION) throw new UnknownRulesVersion(version)
+    if (!SUPPORTED_VERSIONS.includes(version)) throw new UnknownRulesVersion(version)
     seen.add(name)
-    out.push({ name, rules: parseRelaxed(adapter.text(tag)) })
+    out.push({ name, rules: parseRelaxed(adapter.text(tag)), version })
   }
   return out
 }