@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/analysis/fs.ts

@@ -0,0 +1,121 @@
+/**
+ * A simulated file system for static analysis: what the snippet has done to
+ * paths so far on the current control-flow path. It answers "is this a
+ * directory now?" for `cd` (and test refinements), on top of the real file
+ * system as it is when the analysis runs.
+ *
+ * Entries are concrete normalised absolute paths. A path without an entry
+ * takes its state from its nearest ancestor entry (a deleted or file ancestor
+ * makes it absent, an unknown one unknown), else from the disk. Writes and
+ * deletes whose path is not concrete are kept as `fuzzy` shapes: any path
+ * they may touch is `unknown`.
+ */
+
+import * as fs from 'node:fs'
+import type { PathShape } from '../policy/policy.ts'
+
+export type FsState = 'dir' | 'file' | 'absent' | 'unknown'
+
+const MAX_FUZZY = 16
+
+export class AFs {
+  entries = new Map<string, FsState>()
+  /** Shapes of writes/deletes to paths not known statically. */
+  fuzzy: PathShape[] = []
+
+  clone(): AFs {
+    const f = new AFs()
+    f.entries = new Map(this.entries)
+    f.fuzzy = [...this.fuzzy]
+    return f
+  }
+
+  /**
+   * The state of `p`. `mayHaveCreated`: a command with unknown effects ran,
+   * so a path missing on disk may exist now.
+   */
+  lookup(p: string, mayHaveCreated = false): FsState {
+    const own = this.entries.get(p)
+    if (own !== undefined) return own
+    if (this.fuzzy.some((s) => touches(s, p))) return 'unknown'
+    for (let cur = parent(p); cur !== undefined; cur = parent(cur)) {
+      const st = this.entries.get(cur)
+      if (st === undefined) continue
+      if (st === 'absent' || st === 'file') return 'absent'
+      if (st === 'unknown') return 'unknown'
+      break // a known directory: the disk decides below it
+    }
+    const disk = diskState(p)
+    return disk === 'absent' && mayHaveCreated ? 'unknown' : disk
+  }
+
+  set(p: string, st: FsState): void {
+    this.entries.set(p, st)
+  }
+
+  /** `p` and its ancestors are directories (mkdir -p, or the parents of a written file). */
+  mkdirs(p: string): void {
+    for (let cur: string | undefined = p; cur !== undefined && cur !== '/'; cur = parent(cur)) {
+      if (this.entries.get(cur) === 'dir') break
+      this.entries.set(cur, 'dir')
+    }
+  }
+
+  /**
+   * `p` and everything below it are gone (`absent`: a failed `[ -e p ]`), or
+   * gone if the deleting command succeeded (`unknown`: `rm -rf p` may fail, and
+   * a definite verdict must not rely on it).
+   */
+  remove(p: string, st: 'absent' | 'unknown'): void {
+    const prefix = p === '/' ? '/' : p + '/'
+    for (const k of [...this.entries.keys()]) if (k.startsWith(prefix)) this.entries.delete(k)
+    this.entries.set(p, st)
+  }
+
+  /** A write or delete somewhere in `shapes`. */
+  fuzz(shapes: PathShape[]): void {
+    this.fuzzy.push(...shapes)
+    if (this.fuzzy.length > MAX_FUZZY) this.fuzzy = [{ kind: 'unknown', hint: 'many writes' }]
+  }
+
+  /** Control-flow merge: a path keeps its state only if both sides agree. */
+  static join(a: AFs, b: AFs, mayHaveCreated: boolean): AFs {
+    const out = new AFs()
+    for (const k of new Set([...a.entries.keys(), ...b.entries.keys()])) {
+      const x = a.lookup(k, mayHaveCreated)
+      const y = b.lookup(k, mayHaveCreated)
+      out.entries.set(k, x === y ? x : 'unknown')
+    }
+    out.fuzzy = [...a.fuzzy, ...b.fuzzy.filter((s) => !a.fuzzy.includes(s))]
+    if (out.fuzzy.length > MAX_FUZZY) out.fuzzy = [{ kind: 'unknown', hint: 'many writes' }]
+    return out
+  }
+}
+
+function parent(p: string): string | undefined {
+  if (p === '/') return undefined
+  const i = p.lastIndexOf('/')
+  return i <= 0 ? '/' : p.slice(0, i)
+}
+
+function inside(p: string, dir: string): boolean {
+  return p === dir || p.startsWith(dir === '/' ? '/' : dir + '/')
+}
+
+/** May a write/delete at `shape` change `p`? (A recursive delete of an ancestor removes it too.) */
+function touches(shape: PathShape, p: string): boolean {
+  switch (shape.kind) {
+    case 'exact': return inside(p, shape.path)
+    case 'below': return inside(p, shape.dir)
+    case 'unknown': return true
+  }
+}
+
+function diskState(p: string): FsState {
+  try {
+    const st = fs.statSync(p)
+    return st.isDirectory() ? 'dir' : 'file'
+  } catch {
+    return 'absent'
+  }
+}

package/src/analysis/outputs.ts

@@ -0,0 +1,242 @@
+/**
+ * Output types of common commands for `$(...)`: how the analysis types a
+ * command substitution whose body is (or ends in) one simple command.
+ *
+ * Behavior definitions may declare `stdout` themselves (`mktemp`, `pwd`,
+ * `git rev-parse --show-toplevel`). This table refines or supplies the type
+ * for small pure commands whose output shape depends on their arguments
+ * (`date +%s` is an `int`, `tr / _` never prints a `/`). Every entry must be
+ * an over-approximation: the hole type claims a property of EVERY possible
+ * output (see the hole types in value.ts), because definite policy verdicts
+ * rely on it.
+ */
+
+import type { Invocation, OutputInfo } from '../behaviors/types.ts'
+import type { AValue, HoleType, Seg } from './value.ts'
+import { concrete, isHole, isNameLike, isSlashFree, known } from './value.ts'
+
+/** Refine the stdout type a behavior reported (or supply one). */
+export function refineOutput(inv: Invocation, reported: OutputInfo | undefined): OutputInfo | undefined {
+  const args = inv.argv.slice(1)
+  const lit = args.map(concrete)
+  const t = (type: HoleType): OutputInfo => ({ type })
+  switch (inv.name) {
+    case 'date':
+      return dateOutput(args) ?? reported
+    case 'whoami':
+    case 'logname':
+    case 'arch':
+    case 'hostname':
+      // user and host names never contain `/` and are never `.`/`..`
+      return lit.every((a) => a !== undefined && /^-[a-zA-Z]+$/.test(a)) ? t('identifier') : reported
+    case 'nproc':
+      return lit.every((a) => a !== undefined && /^--?[a-z-]+$/.test(a)) ? t('int') : reported
+    case 'id':
+      if (lit.length >= 1 && lit.every((a) => a !== undefined && /^-[ugGnr]+$/.test(a))) {
+        const flags = lit.join('')
+        if (flags.includes('G')) return reported
+        return t(flags.includes('n') ? 'identifier' : 'int')
+      }
+      return reported
+    case 'uname':
+      // `-a`/`-v` include the kernel version string, which may contain `/`
+      return lit.every((a) => a !== undefined && /^-[smnrpio]+$/.test(a)) ? t('identifier') : reported
+    case 'uuidgen':
+      return args.length === 0 ? t('identifier') : reported
+    case 'basename':
+      return basenameOutput(args) ?? reported
+    case 'tr':
+      return trOutput(lit) ?? reported
+    case 'wc':
+      // counts only (no file names) when reading stdin: digits and blanks
+      return lit.every((a) => a !== undefined && /^-[clmw]+$/.test(a)) ? t('identifier') : reported
+    case 'git':
+      return gitOutput(lit) ?? reported
+    case 'md5':
+      // empty when the file is missing
+      return lit.includes('-q') && !lit.includes('-s') ? t('segment') : reported
+    case 'openssl':
+      return lit[0] === 'rand' && lit[1] === '-hex' && lit.length === 3 && /^\d+$/.test(lit[2] ?? '') ? t('hex') : reported
+    default:
+      return reported
+  }
+}
+
+// `%N` is nanoseconds in GNU date but a literal `N` in BSD date
+const DIGIT_CONVERSIONS = 'YmdHMSsyjuwCGgVUW'
+const NAME_CONVERSIONS = DIGIT_CONVERSIONS + 'NFTRzZaAbBhIp'
+
+/** `date +FMT`: digits only → int; no whitespace or `/` → identifier. */
+function dateOutput(args: AValue[]): OutputInfo | undefined {
+  const fmtArg = args.find((a) => (concrete(a) ?? '').startsWith('+'))
+  // any non-literal argument might be a format
+  if (args.some((a) => concrete(a) === undefined)) return undefined
+  if (!fmtArg) return undefined
+  const fmt = concrete(fmtArg)!.slice(1)
+  let digitsOnly = true
+  let anyConversion = false
+  for (let i = 0; i < fmt.length; i++) {
+    const ch = fmt[i]
+    if (ch === '%') {
+      let c = fmt[++i]
+      // flags and widths: %-d, %_H, %0e, %10s
+      while (c !== undefined && /[-_0^#]/.test(c)) c = fmt[++i]
+      while (c !== undefined && /\d/.test(c)) c = fmt[++i]
+      if (c === undefined) return undefined
+      if (c === '%') {
+        digitsOnly = false
+        continue
+      }
+      if (!NAME_CONVERSIONS.includes(c)) return undefined
+      if (!DIGIT_CONVERSIONS.includes(c)) digitsOnly = false
+      if (c !== 'Z' && c !== 'p') anyConversion = true
+      continue
+    }
+    if (/[\s/]/.test(ch)) return undefined
+    if (!/\d/.test(ch)) digitsOnly = false
+  }
+  if (!anyConversion) return undefined
+  return { type: digitsOnly ? 'int' : 'identifier' }
+}
+
+/**
+ * `basename NAME [SUFFIX]`: the last component of NAME. A concrete NAME
+ * gives the exact value; otherwise a real name when NAME's last component is
+ * one and no suffix is removed, else a `segment` (`basename ..` is `..`,
+ * `basename x.txt .txt`-style removal may leave anything).
+ */
+function basenameOutput(args: AValue[]): OutputInfo | undefined {
+  const ops = args.filter((a) => !(concrete(a) ?? 'x').startsWith('-'))
+  if (ops.length !== args.length || ops.length === 0 || ops.length > 2) return { type: 'segment' }
+  const name = ops[0]
+  const suffix = ops[1] === undefined ? '' : concrete(ops[1])
+  const c = concrete(name)
+  if (c !== undefined && suffix !== undefined) return { type: 'segment', value: known(basenameOf(c, suffix)) }
+  if (ops.length === 1 && name.alts.every(lastComponentIsName)) return { type: 'identifier' }
+  return { type: 'segment' }
+}
+
+function basenameOf(s: string, suffix: string): string {
+  if (s === '') return ''
+  const t = s.replace(/\/+$/, '')
+  if (t === '') return '/'
+  let b = t.slice(t.lastIndexOf('/') + 1)
+  if (suffix && b !== suffix && b.endsWith(suffix)) b = b.slice(0, -suffix.length)
+  return b
+}
+
+/** The last component of every concretisation contains a name-like hole or a non-dot literal character (and no hole that may hold `/`). */
+function lastComponentIsName(alt: Seg[]): boolean {
+  // strip trailing slashes in the final literal
+  const segs = [...alt]
+  while (segs.length > 0 && typeof segs[segs.length - 1] === 'string') {
+    const s = (segs[segs.length - 1] as string).replace(/\/+$/, '')
+    if (s === '') segs.pop()
+    else {
+      segs[segs.length - 1] = s
+      break
+    }
+  }
+  let named = false
+  for (let i = segs.length - 1; i >= 0; i--) {
+    const s = segs[i]
+    if (typeof s === 'string') {
+      const j = s.lastIndexOf('/')
+      const tail = j === -1 ? s : s.slice(j + 1)
+      if (/[^.]/.test(tail)) named = true
+      if (j !== -1) return named
+      continue
+    }
+    if (!isHole(s)) continue
+    if (isNameLike(s.type)) named = true
+    // a hole that may hold `/`: the last component starts somewhere inside it, after what we have seen
+    else if (!isSlashFree(s.type)) return named
+  }
+  return named
+}
+
+/** `tr` output without `/` (deleted, translated away, or not in the kept set). */
+function trOutput(lit: (string | undefined)[]): OutputInfo | undefined {
+  if (lit.some((a) => a === undefined)) return undefined
+  const flags = new Set<string>()
+  const sets: string[] = []
+  for (const a of lit as string[]) {
+    if (sets.length === 0 && /^-[cdsC]+$/.test(a)) for (const f of a.slice(1)) flags.add(f === 'C' ? 'c' : f)
+    else sets.push(a)
+  }
+  const complement = flags.has('c')
+  const del = flags.has('d')
+  if (sets.length === 0 || sets.length > 2) return undefined
+  const s1 = expandTrSet(sets[0])
+  if (s1 === undefined) return undefined
+  if (del && sets.length === 1) {
+    // -d SET: removes SET; -dc SET: keeps only SET
+    if (complement ? !s1.includes('/') : s1.includes('/')) return { type: 'segment' }
+    return undefined
+  }
+  if (!del && !complement && sets.length === 2) {
+    const s2 = expandTrSet(sets[1])
+    if (s2 === undefined || s2.length === 0) return undefined
+    // every `/` in SET1 maps to a non-`/` character of SET2 (SET2 is padded with its last character)
+    const i = s1.indexOf('/')
+    if (i === -1) return undefined
+    for (let k = 0; k < s1.length; k++) if (s1[k] === '/' && (s2[Math.min(k, s2.length - 1)] ?? '/') === '/') return undefined
+    // (a `/` listed twice maps by its last occurrence in GNU tr and its first in BSD: all are checked)
+    return { type: 'segment' }
+  }
+  return undefined
+}
+
+/** Expand a `tr` set's ranges and escapes; undefined for classes and other constructs we do not model. */
+function expandTrSet(s: string): string | undefined {
+  if (s.includes('[')) return undefined
+  const chars: string[] = []
+  for (let i = 0; i < s.length; i++) {
+    let c = s[i]
+    if (c === '\\') {
+      const n = s[++i]
+      if (n === undefined) return undefined
+      c = n === 'n' ? '\n' : n === 't' ? '\t' : n === '\\' ? '\\' : n
+      if (/[0-7]/.test(n)) return undefined
+    }
+    if (s[i + 1] === '-' && i + 2 < s.length) {
+      const end = s[i + 2]
+      if (end === '\\') return undefined
+      const a = c.charCodeAt(0)
+      const b = end.charCodeAt(0)
+      if (b < a) return undefined
+      for (let k = a; k <= b; k++) chars.push(String.fromCharCode(k))
+      i += 2
+      continue
+    }
+    chars.push(c)
+  }
+  return chars.join('')
+}
+
+/**
+ * `git rev-parse [--short] [--verify] REV`, `git rev-list --count`, `git log
+ * -1 --format=%H`: a hash or a count, but empty when git fails, and
+ * `rev-parse` echoes an unresolvable REV, so `segment` (and only when REV has
+ * no `/`).
+ */
+function gitOutput(lit: (string | undefined)[]): OutputInfo | undefined {
+  if (lit.some((a) => a === undefined)) return undefined
+  const a = lit as string[]
+  const sub = a[0]
+  const rest = a.slice(1)
+  if (sub === 'rev-parse') {
+    const flags = rest.filter((x) => x.startsWith('-'))
+    const revs = rest.filter((x) => !x.startsWith('-'))
+    if (revs.length !== 1 || revs[0].includes('/')) return undefined
+    if (!flags.every((f) => f === '--verify' || f === '-q' || f === '--quiet' || f === '--short' || /^--short=\d+$/.test(f))) return undefined
+    return { type: 'segment' }
+  }
+  if (sub === 'rev-list' && rest.includes('--count')) return { type: 'segment' }
+  if (sub === 'log') {
+    const fmt = rest.find((x) => /^--(format|pretty)=/.test(x))
+    if (fmt && /^--(?:format|pretty)=(?:format:|tformat:)?%[hH]$/.test(fmt) && rest.every((x) => x === fmt || /^-(1|n1|-max-count=1)$/.test(x) || !x.startsWith('-'))) return { type: 'segment' }
+    return undefined
+  }
+  return undefined
+}

package/src/analysis/value.ts

@@ -0,0 +1,264 @@
+/**
+ * Abstract string values for static analysis and behavior definitions.
+ *
+ * An {@link AValue} is a small set of alternatives; each alternative is a
+ * sequence of literal strings and typed {@link Hole}s (unknown substrings).
+ * Concrete runtime values are simply single-alternative, hole-free values,
+ * so behavior definitions are written once and serve both static analysis
+ * (abstract argv) and runtime enforcement (concrete argv).
+ *
+ * Hole types are a light-weight "type inference" for shell values:
+ * - `int`: decimal integer (never contains `/` or `.`)
+ * - `hex`: a non-empty hexadecimal string (commit ids, checksums)
+ * - `identifier`: a non-empty string without `/` that is not `.` or `..` (user and host names, formatted dates)
+ * - `filename`: a single existing path component (no `/`, never `.`/`..`), e.g. a glob match without directories
+ * - `segment`: a string without `/` that may be empty, `.` or `..` (the longest-prefix removal of `*` + `/` from a path, `tr / _` output)
+ * - `path`: a path, optionally known to be `under` a directory
+ * - `string`: anything
+ */
+
+export type HoleType = 'string' | 'int' | 'hex' | 'identifier' | 'filename' | 'segment' | 'path'
+
+/** Hole types that never contain `/`. */
+export function isSlashFree(t: HoleType): boolean {
+  return t === 'int' || t === 'hex' || t === 'identifier' || t === 'filename' || t === 'segment'
+}
+
+/** Hole types that are never empty and never `.` or `..` (so a path component containing one is a real name). */
+export function isNameLike(t: HoleType): boolean {
+  return t === 'int' || t === 'hex' || t === 'identifier' || t === 'filename'
+}
+
+export interface Hole {
+  hole: true
+  type: HoleType
+  /** Where the unknown came from, e.g. `$dir`, `$(git rev-parse --show-toplevel)`, `*.txt`. */
+  origin: string
+  /** For `path` holes: an absolute directory the value is known to lie under (after normalisation). */
+  under?: string
+  /** A glob pattern the value is known to match (for glob-derived holes). */
+  pattern?: string
+}
+
+export type Seg = string | Hole
+
+export interface AValue {
+  /** Alternatives (at least one). */
+  alts: Seg[][]
+}
+
+export const MAX_ALTS = 16
+
+export function isHole(s: Seg): s is Hole {
+  return typeof s !== 'string'
+}
+
+export function known(s: string): AValue {
+  return { alts: [[s]] }
+}
+
+export function hole(type: HoleType, origin: string, extra: Partial<Hole> = {}): AValue {
+  return { alts: [[{ hole: true, type, origin, ...extra }]] }
+}
+
+export function unknownString(origin: string): AValue {
+  return hole('string', origin)
+}
+
+function normalizeAlt(alt: Seg[]): Seg[] {
+  const out: Seg[] = []
+  for (const s of alt) {
+    if (typeof s === 'string') {
+      if (s === '') continue
+      const last = out[out.length - 1]
+      if (typeof last === 'string') out[out.length - 1] = last + s
+      else out.push(s)
+    } else out.push(s)
+  }
+  return out
+}
+
+function altKey(alt: Seg[]): string {
+  return JSON.stringify(alt)
+}
+
+function dedupe(alts: Seg[][]): Seg[][] {
+  const seen = new Set<string>()
+  const out: Seg[][] = []
+  for (const a of alts) {
+    const n = normalizeAlt(a)
+    const k = altKey(n)
+    if (!seen.has(k)) {
+      seen.add(k)
+      out.push(n)
+    }
+  }
+  return out
+}
+
+/** Collapse too many alternatives into a single unknown. */
+function cap(alts: Seg[][], origin: string): AValue {
+  const d = dedupe(alts)
+  if (d.length <= MAX_ALTS) return { alts: d }
+  return { alts: [[{ hole: true, type: 'string', origin }]] }
+}
+
+export function concat(...values: AValue[]): AValue {
+  let alts: Seg[][] = [[]]
+  for (const v of values) {
+    const next: Seg[][] = []
+    for (const a of alts) for (const b of v.alts) next.push([...a, ...b])
+    alts = next
+    if (alts.length > MAX_ALTS * 4) return cap(alts, values.map(describe).join(''))
+  }
+  return cap(alts, values.map(describe).join(''))
+}
+
+/** Union of possibilities (control-flow join). */
+export function join(...values: AValue[]): AValue {
+  return cap(values.flatMap((v) => v.alts), values.map(describe).join('|'))
+}
+
+/** The concrete string if the value is fully known with a single alternative. */
+export function concrete(v: AValue): string | undefined {
+  if (v.alts.length !== 1) return undefined
+  const a = v.alts[0]
+  if (a.length === 0) return ''
+  if (a.length === 1 && typeof a[0] === 'string') return a[0]
+  return undefined
+}
+
+/** All alternatives are hole-free: the finite set of possible strings. */
+export function finiteValues(v: AValue): string[] | undefined {
+  const out: string[] = []
+  for (const a of v.alts) {
+    if (a.some(isHole)) return undefined
+    out.push((a as string[]).join(''))
+  }
+  return out
+}
+
+export function isFullyKnown(v: AValue): boolean {
+  return v.alts.every((a) => !a.some(isHole))
+}
+
+/** The literal prefix shared by every alternative (possibly empty). */
+export function knownPrefix(v: AValue): string {
+  const prefixes = v.alts.map((a) => (typeof a[0] === 'string' ? a[0] : ''))
+  if (prefixes.length === 0) return ''
+  let p = prefixes[0]
+  for (const q of prefixes.slice(1)) {
+    let i = 0
+    while (i < p.length && i < q.length && p[i] === q[i]) i++
+    p = p.slice(0, i)
+  }
+  return p
+}
+
+/** Human-readable rendering: holes shown as `⟨origin:type⟩`. */
+export function describe(v: AValue): string {
+  const one = (a: Seg[]): string => a.map((s) => (typeof s === 'string' ? s : `⟨${s.origin}${s.type === 'string' ? '' : ':' + s.type}⟩`)).join('')
+  if (v.alts.length === 1) return one(v.alts[0])
+  return '{' + v.alts.map(one).join(' | ') + '}'
+}
+
+/** Map every alternative through a function of its segments. */
+export function mapAlts(v: AValue, f: (alt: Seg[]) => Seg[]): AValue {
+  return cap(v.alts.map(f), describe(v))
+}
+
+/** A regex (source) matching every concretisation of one alternative. */
+export function altRegexSource(alt: Seg[]): string {
+  return alt
+    .map((s) => {
+      if (typeof s === 'string') return s.replace(/[\\^$.*+?()[\]{}|/]/g, (c) => '\\' + c)
+      switch (s.type) {
+        case 'int': return '-?[0-9]+'
+        case 'hex': return '[0-9a-fA-F]+'
+        case 'identifier':
+        case 'filename': return '[^/]+'
+        case 'segment': return '[^/]*'
+        default: return '[\\s\\S]*'
+      }
+    })
+    .join('')
+}
+
+/** Can the value possibly equal `s`? */
+export function mayEqual(v: AValue, s: string): boolean {
+  return v.alts.some((a) => new RegExp('^' + altRegexSource(a) + '$').test(s))
+}
+
+/** Can the value possibly start with `prefix`? (conservative: true unless provably not) */
+export function mayStartWith(v: AValue, prefix: string): boolean {
+  return v.alts.some((a) => {
+    let rest = prefix
+    for (const s of a) {
+      if (rest === '') return true
+      if (typeof s === 'string') {
+        const n = Math.min(s.length, rest.length)
+        if (s.slice(0, n) !== rest.slice(0, n)) return false
+        rest = rest.slice(n)
+      } else {
+        return true
+      }
+    }
+    return rest === ''
+  })
+}
+
+/** Does every concretisation start with `prefix`? */
+export function mustStartWith(v: AValue, prefix: string): boolean {
+  return v.alts.every((a) => typeof a[0] === 'string' && a[0].startsWith(prefix)) || (prefix === '')
+}
+
+/** Split an abstract value at the first occurrence of a literal separator in its literal part (per alternative), for `--opt=value` parsing. */
+export function splitOnce(v: AValue, sep: string): [AValue, AValue] | undefined {
+  const lefts: Seg[][] = []
+  const rights: Seg[][] = []
+  for (const a of v.alts) {
+    let found = false
+    const left: Seg[] = []
+    const right: Seg[] = []
+    for (const s of a) {
+      if (found) right.push(s)
+      else if (typeof s === 'string' && s.includes(sep)) {
+        const i = s.indexOf(sep)
+        left.push(s.slice(0, i))
+        right.push(s.slice(i + sep.length))
+        found = true
+      } else if (typeof s !== 'string') {
+        return undefined
+      } else left.push(s)
+    }
+    if (!found) return undefined
+    lefts.push(left)
+    rights.push(right)
+  }
+  return [cap(lefts, 'left'), cap(rights, 'right')]
+}
+
+/**
+ * A whole argument that may be the empty string (only `segment` holes, no
+ * literal text) is downgraded to `string`: `touch "$x"` with an empty `$x`
+ * touches nothing, so the resolved path (the cwd) is not definitely written.
+ */
+export function guardEmpty(v: AValue): AValue {
+  let changed = false
+  const alts = v.alts.map((a) => {
+    if (!a.every((s) => isHole(s) && !isNameLike(s.type) && s.type !== 'path')) return a
+    if (!a.some((s) => isHole(s) && s.type === 'segment')) return a
+    changed = true
+    return a.map((s): Seg => (isHole(s) && s.type === 'segment' ? { ...s, type: 'string' } : s))
+  })
+  return changed ? { alts } : v
+}
+
+/** Lines/fields of a value: concrete values split; unknown values become one unknown element of the same type. */
+export function typeOf(v: AValue): HoleType | 'literal' | 'mixed' {
+  const holes = v.alts.flatMap((a) => a.filter(isHole))
+  if (holes.length === 0) return 'literal'
+  const types = new Set(holes.map((h) => h.type))
+  if (types.size === 1 && v.alts.every((a) => a.length === 1)) return holes[0].type
+  return 'mixed'
+}