@threadedstack/wmd-web 0.1.17 → 0.1.19

package/src/build/dockerfile.js

@@ -0,0 +1,1055 @@
+// A Dockerfile parser that follows BuildKit's dockerfile frontend (v0.33.0; third_party/buildkit/frontend/
+// dockerfile/{parser,instructions,shell}): line continuation, comments, parser directives, heredoc detection,
+// JSON and shell forms, builder flags, and the typed instructions of instructions.Parse. Variable expansion
+// (shell.Lex.ProcessWord) is done for plain `$VAR` and `${VAR}` only; any other `${VAR<modifier>...}` throws
+// FallbackError, so the caller sends the file to BuildKit.
+//
+//   const df = parseDockerfile(text)
+//   df.stages[i].commands   typed instructions (see parseInstruction)
+//   df.metaArgs             ARG instructions before the first FROM
+//   df.directives           {syntax, escape, check} parser directives found
+//   df.ast                  the raw parse tree, as parser.Parse makes it ([{value, flags, next, children, heredocs, ...}])
+//
+// What is not ported: linter rules (the page runs none), source locations beyond the first/last line, and the
+// instruction forms the page never evaluates (a RUN is parsed, never run).
+
+const WS = /[\t\v\f\r ]+/ // reWhitespace
+
+/** A Dockerfile BuildKit would refuse (or this port cannot read); `line` is 1-based when known. */
+export class DockerfileError extends Error {
+  constructor(message, line = 0) {
+    super(line ? `dockerfile parse error on line ${line}: ${message}` : message)
+    this.name = 'DockerfileError'
+    this.line = line
+    this.detail = message
+  }
+}
+
+/** The Dockerfile uses something the page does not evaluate: BuildKit must build it. */
+export class FallbackError extends Error {
+  constructor(why) {
+    super(why)
+    this.name = 'FallbackError'
+    this.why = why
+  }
+}
+
+// ---------------------------------------------------------------- text helpers (Go's unicode / strings)
+
+const isSpaceCh = (c) => {
+  const n = c.codePointAt(0)
+  return (n >= 9 && n <= 13) || n === 32 || n === 0x85 || n === 0xa0 || n === 0x1680 || (n >= 0x2000 && n <= 0x200a) ||
+    n === 0x2028 || n === 0x2029 || n === 0x202f || n === 0x205f || n === 0x3000
+}
+const trimLeftSpace = (s) => {
+  let i = 0
+  while (i < s.length && isSpaceCh(s[i])) i++
+  return s.slice(i)
+}
+const trimSpace = (s) => {
+  let b = s.length
+  while (b > 0 && isSpaceCh(s[b - 1])) b--
+  return trimLeftSpace(s.slice(0, b))
+}
+const trimNewline = (s) => s.replace(/[\r\n]+$/, '')
+const isComment = (s) => {
+  const t = trimLeftSpace(s)
+  return t.length > 0 && t[0] === '#'
+}
+
+/** strconv.Quote for the strings Dockerfile tests contain. */
+export function goQuote(s) {
+  let out = '"'
+  for (const ch of s) {
+    const c = ch.codePointAt(0)
+    if (ch === '"') out += '\\"'
+    else if (ch === '\\') out += '\\\\'
+    else if (ch === '\n') out += '\\n'
+    else if (ch === '\t') out += '\\t'
+    else if (ch === '\r') out += '\\r'
+    else if (ch === '\x07') out += '\\a'
+    else if (ch === '\b') out += '\\b'
+    else if (ch === '\f') out += '\\f'
+    else if (ch === '\v') out += '\\v'
+    else if (c < 0x20 || c === 0x7f) out += `\\x${c.toString(16).padStart(2, '0')}`
+    else out += ch
+  }
+  return `${out}"`
+}
+
+// ---------------------------------------------------------------- parser directives (parser/directives.go)
+
+const VALID_DIRECTIVES = new Set(['syntax', 'escape', 'check'])
+const DIRECTIVE_RE = /^([a-zA-Z][a-zA-Z0-9]*)\s*=\s*(.+?)\s*$/
+
+class DirectiveParser {
+  constructor() {
+    this.line = 0
+    this.seen = new Set()
+    this.done = false
+  }
+
+  /** @returns {{name, value}|null} */
+  parseLine(line) {
+    this.line++
+    if (this.done) return null
+    if (!line.startsWith('#')) {
+      this.done = true
+      return null
+    }
+    const m = trimLeftSpace(line.slice(1)).match(DIRECTIVE_RE)
+    if (!m) {
+      this.done = true
+      return null
+    }
+    const k = m[1].toLowerCase()
+    if (!VALID_DIRECTIVES.has(k)) {
+      this.done = true
+      return null
+    }
+    if (this.seen.has(k)) throw new Error(`only one ${k} parser directive can be used`)
+    this.seen.add(k)
+    return { name: k, value: m[2], line: this.line }
+  }
+}
+
+function continuationRegex(esc) {
+  const e = esc === '`' ? '`' : '\\\\'
+  const cls = esc === '`' ? '[^`]' : '[^\\\\]'
+  return new RegExp(`(${cls})${e}[ \\t]*$|^${e}[ \\t]*$`)
+}
+
+// ---------------------------------------------------------------- line parsers (parser/line_parsers.go)
+
+function parseWords(rest, esc) {
+  const words = []
+  let phase = 0 // 0 spaces, 1 word, 2 quote
+  let quote = ''
+  let blankOK = false
+  let sb = ''
+  const chars = Array.from(rest)
+  for (let pos = 0; pos <= chars.length; pos++) {
+    const ch = chars[pos]
+    const atEnd = pos === chars.length
+    if (phase === 0) {
+      if (atEnd) break
+      if (isSpaceCh(ch)) continue
+      phase = 1
+    }
+    if ((phase === 1 || phase === 2) && atEnd) {
+      if (blankOK || sb.length > 0) words.push(sb)
+      break
+    }
+    if (phase === 1) {
+      if (isSpaceCh(ch)) {
+        phase = 0
+        if (blankOK || sb.length > 0) words.push(sb)
+        sb = ''
+        blankOK = false
+        continue
+      }
+      let c = ch
+      if (c === "'" || c === '"') {
+        quote = c
+        blankOK = true
+        phase = 2
+      }
+      if (c === esc) {
+        if (pos + 1 === chars.length) continue
+        sb += c
+        pos++
+        c = chars[pos]
+      }
+      sb += c
+      continue
+    }
+    if (phase === 2) {
+      let c = ch
+      if (c === quote) phase = 1
+      if (c === esc && quote !== "'") {
+        if (pos + 1 === chars.length) {
+          phase = 1
+          continue
+        }
+        pos++
+        sb += c
+        c = chars[pos]
+      }
+      sb += c
+    }
+  }
+  return words
+}
+
+/** regexp.Split(s, n) for a regexp that never matches the empty string. */
+function splitN(s, re, n) {
+  const out = []
+  let last = 0
+  for (const m of s.matchAll(new RegExp(re.source, 'g'))) {
+    if (n > 0 && out.length === n - 1) break
+    out.push(s.slice(last, m.index))
+    last = m.index + m[0].length
+  }
+  out.push(s.slice(last))
+  return out
+}
+
+function parseNameVal(rest, key, esc) {
+  const words = parseWords(rest, esc)
+  if (words.length === 0) return null
+  if (!words[0].includes('=')) {
+    // old format: KEY name value
+    const parts = splitN(rest, WS, 2)
+    if (parts.length < 2) throw new Error(`${key} must have two arguments`)
+    return { next: [parts[0], parts[1], ''] }
+  }
+  const next = []
+  for (const word of words) {
+    if (!word.includes('=')) throw new Error(`Syntax error - can't find = in ${goQuote(word)}. Must be of the form: name=value`)
+    const i = word.indexOf('=')
+    next.push(word.slice(0, i), word.slice(i + 1), '=')
+  }
+  return { next }
+}
+
+function parseStringsWhitespaceDelimited(rest) {
+  if (rest === '') return { next: [] }
+  return { next: splitN(rest, WS, -1) }
+}
+
+function parseString(rest) {
+  if (rest === '') return { next: [] }
+  return { next: [rest] }
+}
+
+function parseJSON(rest) {
+  const r = trimLeftSpace(rest)
+  if (!r.startsWith('[')) return { notArray: true }
+  let v
+  try {
+    v = JSON.parse(r)
+  } catch {
+    return { notArray: true }
+  }
+  if (!Array.isArray(v)) return { notArray: true }
+  for (const s of v) if (typeof s !== 'string') throw new Error('when using JSON array syntax, arrays must be comprised of strings only')
+  return { next: v, json: true }
+}
+
+function parseMaybeJSON(rest) {
+  if (rest === '') return { next: [] }
+  const j = parseJSON(rest)
+  if (!j.notArray) return j
+  return { next: [rest] }
+}
+
+function parseMaybeJSONToList(rest) {
+  const j = parseJSON(rest)
+  if (!j.notArray) return j
+  return parseStringsWhitespaceDelimited(rest)
+}
+
+function parseNameOrNameVal(rest, esc) {
+  return { next: parseWords(rest, esc) }
+}
+
+function parseHealthConfig(rest) {
+  let sep = 0
+  while (sep < rest.length && !isSpaceCh(rest[sep])) sep++
+  let next = sep
+  while (next < rest.length && isSpaceCh(rest[next])) next++
+  if (sep === 0) return { next: [] }
+  const typ = rest.slice(0, sep)
+  const cmd = parseMaybeJSON(rest.slice(next))
+  return { next: [typ, ...cmd.next], json: !!cmd.json }
+}
+
+function dispatchFor(name) {
+  switch (name) {
+    case 'add': case 'copy': case 'volume': return parseMaybeJSONToList
+    case 'arg': return parseNameOrNameVal
+    case 'cmd': case 'entrypoint': case 'run': case 'shell': return parseMaybeJSON
+    case 'env': return (rest, esc) => parseNameVal(rest, 'ENV', esc)
+    case 'label': return (rest, esc) => parseNameVal(rest, 'LABEL', esc)
+    case 'expose': case 'from': return parseStringsWhitespaceDelimited
+    case 'healthcheck': return parseHealthConfig
+    case 'maintainer': case 'stopsignal': case 'user': case 'workdir': return parseString
+    case 'onbuild': return 'sub'
+    default: return null
+  }
+}
+
+// ---------------------------------------------------------------- builder flags (parser/split_command.go)
+
+function extractBuilderFlags(line, esc) {
+  const chars = Array.from(line)
+  const words = []
+  let phase = 0
+  let sb = ''
+  let quote = ''
+  let blankOK = false
+  for (let pos = 0; pos <= chars.length; pos++) {
+    const atEnd = pos === chars.length
+    let ch = chars[pos]
+    if (phase === 0) {
+      if (atEnd) break
+      if (isSpaceCh(ch)) continue
+      if (ch !== '-' || pos + 1 === chars.length || chars[pos + 1] !== '-') return { rest: chars.slice(pos).join(''), flags: words }
+      phase = 1
+    }
+    if ((phase === 1 || phase === 2) && atEnd) {
+      if (sb !== '--' && (blankOK || sb.length > 0)) words.push(sb)
+      break
+    }
+    if (phase === 1) {
+      if (isSpaceCh(ch)) {
+        phase = 0
+        if (sb === '--') return { rest: chars.slice(pos).join(''), flags: words }
+        if (blankOK || sb.length > 0) words.push(sb)
+        sb = ''
+        blankOK = false
+        continue
+      }
+      if (ch === "'" || ch === '"') {
+        quote = ch
+        blankOK = true
+        phase = 2
+        continue
+      }
+      if (ch === esc) {
+        if (pos + 1 === chars.length) continue
+        pos++
+        ch = chars[pos]
+      }
+      sb += ch
+      continue
+    }
+    if (phase === 2) {
+      if (ch === quote) {
+        phase = 1
+        continue
+      }
+      if (ch === esc) {
+        if (pos + 1 === chars.length) {
+          phase = 1
+          continue
+        }
+        pos++
+        ch = chars[pos]
+      }
+      sb += ch
+    }
+  }
+  return { rest: '', flags: words }
+}
+
+function splitCommand(line, esc) {
+  const t = trimSpace(line)
+  const cmdline = splitN(t, WS, 2)
+  let args = ''
+  let flags = []
+  if (cmdline.length === 2) {
+    const r = extractBuilderFlags(cmdline[1], esc)
+    args = r.rest
+    flags = r.flags
+  }
+  return { cmd: cmdline[0], flags, args: trimSpace(args) }
+}
+
+function newNodeFromLine(line, esc) {
+  const { cmd, flags, args } = splitCommand(line, esc)
+  const fn = dispatchFor(cmd.toLowerCase())
+  let r
+  if (fn === 'sub') r = args === '' ? { next: [] } : { next: [], children: [newNodeFromLine(args, esc)] }
+  else if (fn === null) r = { next: [] }
+  else r = fn(args, esc)
+  return { value: cmd, original: line, flags, next: r?.next || [], json: !!r?.json, children: r?.children || [], heredocs: [] }
+}
+
+// ---------------------------------------------------------------- heredocs (parser.go)
+
+const HEREDOC_RE = /^(\d*)<<(-?)\s*([^<]*)$/
+
+/** shlex word split that keeps quotes and escapes raw (RawQuotes+RawEscapes), as heredocsFromLine uses it. */
+function rawWords(line) {
+  const words = []
+  let cur = ''
+  let inWord = false
+  const chars = Array.from(line)
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i]
+    if (ch === '\\') {
+      cur += ch
+      inWord = true
+      if (i + 1 < chars.length) cur += chars[++i]
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      inWord = true
+      cur += ch
+      let j = i + 1
+      while (j < chars.length && chars[j] !== ch) {
+        if (ch === '"' && chars[j] === '\\' && j + 1 < chars.length) cur += chars[j++]
+        cur += chars[j++]
+      }
+      if (j < chars.length) cur += chars[j]
+      i = j
+      continue
+    }
+    if (isSpaceCh(ch)) {
+      if (inWord) words.push(cur)
+      cur = ''
+      inWord = false
+      continue
+    }
+    cur += ch
+    inWord = true
+  }
+  if (inWord) words.push(cur)
+  return words
+}
+
+function unquoteWord(s) {
+  let out = ''
+  const chars = Array.from(s)
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i]
+    if (ch === '\\') {
+      if (i + 1 < chars.length) out += chars[++i]
+    } else if (ch === "'") {
+      let j = i + 1
+      while (j < chars.length && chars[j] !== "'") out += chars[j++]
+      i = j
+    } else if (ch === '"') {
+      let j = i + 1
+      while (j < chars.length && chars[j] !== '"') {
+        if (chars[j] === '\\' && j + 1 < chars.length && '"$\\'.includes(chars[j + 1])) j++
+        out += chars[j++]
+      }
+      i = j
+    } else out += ch
+  }
+  return out
+}
+
+/** parser.ParseHeredoc: {name, fd, expand, chomp, content} or null. */
+export function parseHeredocWord(src) {
+  const m = src.match(HEREDOC_RE)
+  if (!m || m[3].length === 0) return null
+  const rest = m[3]
+  const name = unquoteWord(rest)
+  const quotes = (s) => (s.match(/['"]/g) || []).length
+  const expand = quotes(name) === quotes(rest)
+  return { name, fd: m[1] ? Number(m[1]) : 0, expand, chomp: m[2] === '-', content: '' }
+}
+
+function heredocsFromLine(line) {
+  const docs = []
+  for (const w of rawWords(line)) {
+    const h = parseHeredocWord(w)
+    if (h) docs.push(h)
+  }
+  return docs
+}
+
+function canContainHeredoc(node) {
+  let n = node
+  if (n.value.toLowerCase() === 'onbuild' && n.children.length) n = n.children[0]
+  const v = n.value.toLowerCase()
+  if (v !== 'add' && v !== 'copy' && v !== 'run') return false
+  return !n.json
+}
+
+// ---------------------------------------------------------------- Parse (parser.go)
+
+function splitLines(text) {
+  const out = []
+  let i = 0
+  while (i < text.length) {
+    const j = text.indexOf('\n', i)
+    if (j < 0) {
+      out.push(text.slice(i))
+      break
+    }
+    out.push(text.slice(i, j + 1))
+    i = j + 1
+  }
+  return out
+}
+
+/**
+ * parser.Parse. Returns {ast: [node], escape, directives, warnings}.
+ * @param {string} text
+ */
+export function parseRaw(text) {
+  let esc = '\\'
+  let contRe = continuationRegex(esc)
+  const dp = new DirectiveParser()
+  const directives = {}
+  const warnings = []
+  const lines = splitLines(text)
+  const ast = []
+  let currentLine = 0
+  let idx = 0
+
+  const setEscape = (v) => {
+    if (v !== '`' && v !== '\\') throw new Error(`invalid escape token '${v}' does not match \` or \\`)
+    esc = v
+    contRe = continuationRegex(esc)
+  }
+  const processLine = (raw, stripLeft) => {
+    let token = trimNewline(raw)
+    if (stripLeft) token = trimLeftSpace(token)
+    const d = dp.parseLine(token)
+    if (d) {
+      directives[d.name] = d.value
+      if (d.name === 'escape') setEscape(d.value)
+    }
+    return isComment(token) ? '' : token
+  }
+  const trimCont = (s) => (contRe.test(s) ? { text: s.replace(contRe, '$1'), end: false } : { text: s, end: true })
+
+  while (idx < lines.length) {
+    let raw = lines[idx++]
+    if (currentLine === 0 && raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1)
+    let tok
+    try {
+      tok = processLine(raw, true)
+    } catch (e) {
+      throw new DockerfileError(e.message, currentLine)
+    }
+    currentLine++
+    const startLine = currentLine
+    const first = trimCont(tok)
+    let end = first.end
+    if (end && first.text.length === 0) continue
+    let buf = first.text
+    let emptyCont = false
+    while (!end && idx < lines.length) {
+      const next = lines[idx++]
+      let t
+      try {
+        t = processLine(next, false)
+      } catch (e) {
+        throw new DockerfileError(e.message, currentLine)
+      }
+      currentLine++
+      if (isComment(next)) continue
+      if (trimLeftSpace(trimNewline(t)).length === 0) {
+        emptyCont = true
+        continue
+      }
+      const c = trimCont(t)
+      end = c.end
+      buf += c.text
+    }
+    if (emptyCont) warnings.push(`Empty continuation line found in: ${buf}`)
+
+    let node
+    try {
+      node = newNodeFromLine(buf, esc)
+    } catch (e) {
+      throw new DockerfileError(e.message, startLine)
+    }
+    if (canContainHeredoc(node) && buf.includes('<<')) {
+      for (const h of heredocsFromLine(buf)) {
+        let terminated = false
+        let content = h.content
+        while (idx < lines.length) {
+          const l = lines[idx++]
+          currentLine++
+          let t = trimNewline(l)
+          if (h.chomp) t = t.replace(/^\t+/, '')
+          if (t === h.name) {
+            terminated = true
+            break
+          }
+          content += l
+        }
+        if (!terminated) throw new DockerfileError('unterminated heredoc', startLine)
+        h.content = content
+        node.heredocs.push(h)
+      }
+    }
+    node.startLine = startLine
+    node.endLine = currentLine
+    ast.push(node)
+  }
+  if (ast.length === 0) throw new DockerfileError('file with no instructions', currentLine)
+  return { ast, escape: esc, directives, warnings }
+}
+
+/** The tree in the form parser/dumper uses and the testfiles' `result` files hold: "(cmd flags args)\n" per instruction. */
+export function dump(ast) {
+  const node = (n) => {
+    let s = n.value.toLowerCase()
+    if (n.flags.length) s += ` [${n.flags.map(goQuote).join(' ')}]`
+    for (const a of n.next) s += ` ${goQuote(a)}`
+    for (const c of n.children) s += ` (${node(c)})`
+    return s.trim()
+  }
+  return ast.map((n) => `(${node(n)})\n`).join('')
+}
+
+// ---------------------------------------------------------------- flags (instructions/bflag.go)
+
+/** @param {string[]} args flag words like '--chown=1:1'; spec: {name: 'bool'|'string'|'strings'} */
+function parseFlags(args, spec) {
+  const out = {}
+  for (const a of args) {
+    if (a === '--') break
+    if (!a.startsWith('--')) throw new Error(`arg should start with -- : ${a}`)
+    const eq = a.indexOf('=')
+    const flagName = eq < 0 ? a : a.slice(0, eq)
+    const hasValue = eq >= 0
+    const value = hasValue ? a.slice(eq + 1) : ''
+    const name = flagName.slice(2)
+    const type = spec[name]
+    if (!type) throw new Error(`unknown flag: ${flagName}`)
+    if (name in out && type !== 'strings') throw new Error(`duplicate flag specified: ${flagName}`)
+    if (type === 'bool') {
+      if (hasValue && value === '') throw new Error(`missing a value on flag: ${flagName}`)
+      const v = value.toLowerCase()
+      if (v === 'true' || v === '') out[name] = true
+      else if (v === 'false') out[name] = false
+      else throw new Error(`expecting boolean value for flag ${flagName}, not: ${value}`)
+    } else if (type === 'string') {
+      if (!hasValue) throw new Error(`missing a value on flag: ${flagName}`)
+      out[name] = value
+    } else {
+      if (!hasValue) throw new Error(`missing a value on flag: ${flagName}`)
+      ;(out[name] ||= []).push(value)
+    }
+  }
+  return out
+}
+
+const NO_FLAGS = {}
+const FLAG_SPECS = {
+  copy: { chown: 'string', from: 'string', chmod: 'string', link: 'bool', exclude: 'strings', parents: 'bool' },
+  add: { chown: 'string', chmod: 'string', link: 'bool', 'keep-git-dir': 'bool', checksum: 'string', unpack: 'bool', exclude: 'strings' },
+  from: { platform: 'string' },
+  healthcheck: { interval: 'string', timeout: 'string', 'start-period': 'string', 'start-interval': 'string', retries: 'string' },
+  // RUN has mount, network, security, device: the flags are kept as given, never evaluated
+  run: { mount: 'strings', network: 'string', security: 'string', device: 'strings' },
+}
+
+// ---------------------------------------------------------------- Go durations (time.ParseDuration)
+
+const UNITS = { ns: 1, us: 1e3, 'µs': 1e3, 'μs': 1e3, ms: 1e6, s: 1e9, m: 6e10, h: 3.6e12 }
+/** @returns {number} nanoseconds */
+export function parseGoDuration(str) {
+  let s = str
+  let neg = false
+  if (s[0] === '-' || s[0] === '+') {
+    neg = s[0] === '-'
+    s = s.slice(1)
+  }
+  if (s === '0') return 0
+  if (s === '') throw new Error(`time: invalid duration ${goQuote(str)}`)
+  let total = 0
+  while (s !== '') {
+    const m = s.match(/^(\d*\.?\d*)([^\d.]*)/)
+    if (!m || m[1] === '' || m[1] === '.') throw new Error(`time: invalid duration ${goQuote(str)}`)
+    if (m[2] === '') throw new Error(`time: missing unit in duration ${goQuote(str)}`)
+    if (!(m[2] in UNITS)) throw new Error(`time: unknown unit ${goQuote(m[2])} in duration ${goQuote(str)}`)
+    total += Number(m[1]) * UNITS[m[2]]
+    s = s.slice(m[0].length)
+  }
+  return Math.round(neg ? -total : total)
+}
+
+const trimZeros = (x) => String(Number(x.toFixed(9)))
+/** Go's time.Duration String(): "30s", "1m30s", "0s". */
+export function goDurationString(ns) {
+  if (ns === 0) return '0s'
+  const neg = ns < 0
+  let u = Math.abs(ns)
+  let out
+  if (u < 1e9) {
+    if (u < 1e3) out = `${u}ns`
+    else if (u < 1e6) out = `${trimZeros(u / 1e3)}µs`
+    else out = `${trimZeros(u / 1e6)}ms`
+  } else {
+    const h = Math.floor(u / 3.6e12)
+    u -= h * 3.6e12
+    const m = Math.floor(u / 6e10)
+    u -= m * 6e10
+    out = `${h ? `${h}h` : ''}${h || m ? `${m}m` : ''}${trimZeros(u / 1e9)}s`
+  }
+  return neg ? `-${out}` : out
+}
+
+// ---------------------------------------------------------------- typed instructions (instructions/parse.go)
+
+const handleJSONArgs = (args, json) => (args.length === 0 ? [] : json ? args : [args.join(' ')])
+
+function parseKvps(next, cmd) {
+  if (next.length === 0) throw new Error(`${cmd} requires at least one argument`)
+  if (next.length % 3 !== 0) throw new Error(`Bad input to ${cmd}, too many arguments`)
+  const out = []
+  for (let i = 0; i < next.length; i += 3) {
+    if (next[i].length === 0) throw new Error(`${cmd} names can not be blank`)
+    out.push({ key: next[i], value: next[i + 1], noDelim: next[i + 2] === '' })
+  }
+  return out
+}
+
+function parseSourcesAndDest(args, heredocs, cmd) {
+  const srcs = args.slice(0, -1)
+  const dest = args[args.length - 1]
+  if (parseHeredocWord(dest)) throw new Error(`${cmd} cannot accept a heredoc as a destination`)
+  const lookup = new Map(heredocs.map((h) => [h.name, h]))
+  const sources = []
+  const contents = []
+  for (const s of srcs) {
+    const h = parseHeredocWord(s)
+    if (h) {
+      let data = lookup.get(h.name)?.content ?? ''
+      if (h.chomp) data = data.replace(/^\t+/gm, '')
+      contents.push({ path: h.name, data, expand: h.expand })
+    } else sources.push(s)
+  }
+  return { dest, sources, contents }
+}
+
+/**
+ * instructions.ParseInstruction: a typed object per instruction ({type, ...fields, line}).
+ * @param {object} node a raw node from parseRaw
+ */
+export function parseInstruction(node) {
+  const name = node.value.toLowerCase()
+  const args = node.next
+  const base = { type: name, line: node.startLine, original: trimSpace(node.original) }
+  const flags = (spec) => parseFlags(node.flags, spec || NO_FLAGS)
+  switch (name) {
+    case 'env':
+      flags()
+      return { ...base, pairs: parseKvps(args, 'ENV') }
+    case 'label':
+      flags()
+      return { ...base, pairs: parseKvps(args, 'LABEL') }
+    case 'maintainer':
+      if (args.length !== 1) throw new Error('MAINTAINER requires exactly one argument')
+      flags()
+      return { ...base, maintainer: args[0] }
+    case 'add':
+    case 'copy': {
+      if (args.length < 2) throw new Error(`${name.toUpperCase()} requires at least two arguments, but only one was provided. Destination could not be determined`)
+      const f = flags(FLAG_SPECS[name])
+      const sd = parseSourcesAndDest(args, node.heredocs, name.toUpperCase())
+      return {
+        ...base,
+        sources: sd.sources,
+        dest: sd.dest,
+        contents: sd.contents,
+        from: f.from || '',
+        chown: f.chown || '',
+        chmod: f.chmod || '',
+        link: f.link === true,
+        parents: f.parents === true,
+        exclude: f.exclude || [],
+        flagsUsed: Object.keys(f),
+      }
+    }
+    case 'from': {
+      let stageName = ''
+      if (args.length === 3 && args[1].toLowerCase() === 'as') {
+        stageName = args[2].toLowerCase()
+        if (!/^[a-z][a-z0-9\-_.]*$/.test(stageName)) throw new Error(`invalid name for build stage: ${goQuote(args[2])}, name can't start with a number or contain symbols`)
+      } else if (args.length !== 1) throw new Error('FROM requires either one or three arguments')
+      const f = flags(FLAG_SPECS.from)
+      return { ...base, baseName: args[0], name: stageName, platform: f.platform || '', commands: [] }
+    }
+    case 'onbuild': {
+      if (!node.children.length) throw new Error('ONBUILD requires at least one argument')
+      flags()
+      const trigger = node.children[0].value.trim().toUpperCase()
+      if (trigger === 'ONBUILD') throw new Error("Chaining ONBUILD via `ONBUILD ONBUILD` isn't allowed")
+      if (trigger === 'MAINTAINER' || trigger === 'FROM') throw new Error(`${trigger} isn't allowed as an ONBUILD trigger`)
+      return { ...base, expression: node.original.replace(/^\s*ONBUILD\s*/i, '') }
+    }
+    case 'workdir':
+      if (args.length !== 1) throw new Error('WORKDIR requires exactly one argument')
+      flags()
+      return { ...base, path: args[0] }
+    case 'run': {
+      const f = flags(FLAG_SPECS.run)
+      return { ...base, flagsUsed: Object.keys(f), cmdline: handleJSONArgs(args, node.json), shell: !node.json, heredocs: node.heredocs.length }
+    }
+    case 'cmd':
+    case 'entrypoint':
+      flags()
+      return { ...base, cmdline: handleJSONArgs(args, node.json), shell: !node.json }
+    case 'healthcheck': {
+      if (args.length === 0) throw new Error('HEALTHCHECK requires at least one argument')
+      const typ = args[0].toUpperCase()
+      const rest = args.slice(1)
+      if (typ === 'NONE') {
+        if (rest.length !== 0) throw new Error('HEALTHCHECK NONE takes no arguments')
+        return { ...base, health: { Test: ['NONE'] } }
+      }
+      const f = flags(FLAG_SPECS.healthcheck)
+      if (typ !== 'CMD') throw new Error(`Unknown type ${goQuote(typ)} in HEALTHCHECK (try CMD)`)
+      const cmdSlice = handleJSONArgs(rest, node.json)
+      if (cmdSlice.length === 0) throw new Error('Missing command after HEALTHCHECK CMD')
+      const health = { Test: [node.json ? 'CMD' : 'CMD-SHELL', ...cmdSlice] }
+      const opt = (key, field) => {
+        if (!f[key]) return
+        const d = parseGoDuration(f[key])
+        if (d !== 0 && d < 1e6) throw new Error(`Interval ${goQuote(key)} cannot be less than 1ms`)
+        if (d) health[field] = d
+      }
+      opt('interval', 'Interval')
+      opt('timeout', 'Timeout')
+      opt('start-period', 'StartPeriod')
+      opt('start-interval', 'StartInterval')
+      if (f.retries !== undefined && f.retries !== '') {
+        if (!/^[+-]?\d+$/.test(f.retries) || Math.abs(Number(f.retries)) > 2 ** 31 - 1) throw new Error(`strconv.ParseInt: parsing ${goQuote(f.retries)}: invalid syntax`)
+        const r = Number(f.retries)
+        if (r < 0) throw new Error(`--retries cannot be negative (${r})`)
+        if (r) health.Retries = r
+      }
+      return { ...base, health }
+    }
+    case 'expose':
+      if (args.length === 0) throw new Error('EXPOSE requires at least one argument')
+      flags()
+      return { ...base, ports: [...args].sort() }
+    case 'user':
+      if (args.length !== 1) throw new Error('USER requires exactly one argument')
+      flags()
+      return { ...base, user: args[0] }
+    case 'volume': {
+      if (args.length === 0) throw new Error('VOLUME requires at least one argument')
+      flags()
+      const volumes = args.map((v) => v.trim())
+      if (volumes.some((v) => v === '')) throw new Error('VOLUME specified can not be an empty string')
+      return { ...base, volumes }
+    }
+    case 'stopsignal':
+      if (args.length !== 1) throw new Error('STOPSIGNAL requires exactly one argument')
+      flags()
+      return { ...base, signal: args[0] }
+    case 'arg':
+      if (args.length < 1) throw new Error('ARG requires at least one argument')
+      flags()
+      return {
+        ...base,
+        args: args.map((a) => {
+          const i = a.indexOf('=')
+          if (i < 0) return { key: a, value: null }
+          if (i === 0) throw new Error('ARG names can not be blank')
+          return { key: a.slice(0, i), value: a.slice(i + 1) }
+        }),
+      }
+    case 'shell': {
+      flags()
+      const shell = handleJSONArgs(args, node.json)
+      if (shell.length === 0) throw new Error('SHELL requires at least one argument')
+      if (!node.json) throw new Error(`Source: ${node.original} is not valid for SHELL: not JSON`)
+      return { ...base, shell }
+    }
+    default:
+      throw new Error(`unknown instruction: ${node.value}`)
+  }
+}
+
+/**
+ * Parses a Dockerfile into stages (instructions.Parse): {stages: [{name, baseName, platform, commands, line}], metaArgs,
+ * directives, escape, ast, warnings}. Throws DockerfileError.
+ */
+export function parseDockerfile(text) {
+  const raw = parseRaw(String(text))
+  const stages = []
+  const metaArgs = []
+  for (const node of raw.ast) {
+    let cmd
+    try {
+      cmd = parseInstruction(node)
+    } catch (e) {
+      if (e instanceof DockerfileError) throw e
+      throw new DockerfileError(e.message, node.startLine)
+    }
+    if (stages.length === 0 && cmd.type === 'arg') {
+      metaArgs.push(cmd)
+      continue
+    }
+    if (cmd.type === 'from') stages.push(cmd)
+    else {
+      if (stages.length === 0) throw new DockerfileError('no build stage in current context', node.startLine)
+      stages[stages.length - 1].commands.push(cmd)
+    }
+  }
+  return { stages, metaArgs, directives: raw.directives, escape: raw.escape, ast: raw.ast, warnings: raw.warnings }
+}
+
+// ---------------------------------------------------------------- variable expansion (shell/lex.go ProcessWord)
+
+/** An env as BuildKit's shell.EnvGetter: insertion ordered, set replaces in place. */
+export class Env {
+  constructor(pairs = []) {
+    this.map = new Map(pairs)
+  }
+
+  get(k) {
+    return this.map.get(k)
+  }
+
+  has(k) {
+    return this.map.has(k)
+  }
+
+  set(k, v) {
+    this.map.set(k, v)
+  }
+
+  keys() {
+    return [...this.map.keys()]
+  }
+
+  clone() {
+    return new Env([...this.map])
+  }
+}
+
+const SPECIAL_PARAMS = '@*#?-$!0'
+const isLetter = (c) => /\p{L}/u.test(c)
+const isDigit = (c) => /\p{Nd}/u.test(c)
+
+/**
+ * shell.Lex.ProcessWord for plain `$VAR` and `${VAR}`: quotes and escapes are processed as BuildKit does, an unset
+ * variable is the empty string. A modifier (`${X:-y}`, `${X#p}`, ...) and special parameters (`$@`, `$$`, `$0`) throw
+ * FallbackError; an unterminated quote or brace throws DockerfileError (BuildKit refuses it too).
+ * @param {string} word
+ * @param {{get(k: string): string|undefined}} env
+ * @param {{escape?: string, words?: string[]}} [o] words: also split the result into words as ProcessWords does
+ * @param {Set<string>} [used] receives the names looked up
+ */
+export function expandWord(word, env, { escape = '\\', words } = {}, used) {
+  const chars = Array.from(word)
+  let i = 0
+  const peek = () => chars[i]
+  const next = () => chars[i++]
+  const shown = JSON.stringify(word)
+
+  const name = () => {
+    let n = ''
+    while (i < chars.length) {
+      const c = peek()
+      if (n.length === 0 && isDigit(c)) {
+        while (i < chars.length && isDigit(peek())) n += next()
+        return n
+      }
+      if (n.length === 0 && SPECIAL_PARAMS.includes(c)) return next()
+      if (!isLetter(c) && !isDigit(c) && c !== '_') break
+      n += next()
+    }
+    return n
+  }
+  const lookup = (n) => {
+    if (n.length === 1 && SPECIAL_PARAMS.includes(n)) throw new FallbackError(`the special parameter $${n} in ${shown}`)
+    if (/^\d+$/.test(n)) throw new FallbackError(`the positional parameter $${n} in ${shown}`)
+    used?.add(n)
+    const v = env.get(n)
+    return v === undefined ? '' : v
+  }
+  const dollar = () => {
+    next() // $
+    if (peek() !== '{') {
+      const n = name()
+      return n === '' ? '$' : lookup(n)
+    }
+    next()
+    if (i >= chars.length) throw new DockerfileError(`failed to process ${shown}: syntax error: missing '}'`)
+    const c = peek()
+    if (c === '{' || c === '}' || c === ':') throw new DockerfileError(`failed to process ${shown}: syntax error: bad substitution`)
+    const n = name()
+    const ch = next()
+    if (ch === '}') return lookup(n)
+    if (ch === undefined) throw new DockerfileError(`failed to process ${shown}: syntax error: missing '}'`)
+    throw new FallbackError(`the substitution \${${n}${ch}...} in ${shown}`)
+  }
+  const single = () => {
+    next()
+    let r = ''
+    for (;;) {
+      const c = next()
+      if (c === undefined) throw new DockerfileError(`failed to process ${shown}: unexpected end of statement while looking for matching single-quote`)
+      if (c === "'") return r
+      r += c
+    }
+  }
+  const double = () => {
+    next()
+    let r = ''
+    for (;;) {
+      const c = peek()
+      if (c === undefined) throw new DockerfileError(`failed to process ${shown}: unexpected end of statement while looking for matching double-quote`)
+      if (c === '"') {
+        next()
+        return r
+      }
+      if (c === '$') {
+        r += dollar()
+        continue
+      }
+      let ch = next()
+      if (ch === escape) {
+        const p = peek()
+        if (p === undefined) continue
+        if (p === '"' || p === '$' || p === escape) ch = next()
+      }
+      r += ch
+    }
+  }
+  let out = ''
+  // ProcessWords' splitting: a variable's value splits at spaces, a quoted part and an escaped char do not
+  let cur = ''
+  let inWord = false
+  const addRaw = (s) => {
+    cur += s
+    if (s !== '') inWord = true
+  }
+  const addVar = (s) => {
+    for (const ch of s) {
+      if (isSpaceCh(ch)) {
+        if (inWord && cur !== '') {
+          words?.push(cur)
+          cur = ''
+          inWord = false
+        }
+      } else addRaw(ch)
+    }
+  }
+  while (i < chars.length) {
+    const c = peek()
+    if (c === '$') {
+      const v = dollar()
+      out += v
+      addVar(v)
+    } else if (c === "'" || c === '"') {
+      const v = c === "'" ? single() : double()
+      out += v
+      addRaw(v)
+    } else if (c === '<') {
+      next()
+      if (peek() === '<') throw new FallbackError(`a heredoc marker in ${shown}`)
+      out += '<'
+      addRaw('<')
+    } else {
+      let ch = next()
+      if (ch === escape) {
+        ch = next()
+        if (ch === undefined) break
+        addRaw(ch)
+      } else addVar(ch)
+      out += ch
+    }
+  }
+  if (cur !== '') words?.push(cur)
+  return out
+}
+
+/** Go's %q of a []string: ["a" "b"] (what BuildKit writes in a history line for CMD and ENTRYPOINT). */
+export const goQuoteList = (a) => `[${a.map(goQuote).join(' ')}]`