@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/behaviors/dsl.ts

@@ -0,0 +1,293 @@
+/**
+ * Declarative behavior definitions: a table form for the common case
+ * "parse the arguments; operands and some option values are files that are
+ * read, written or deleted", compiled to the same {@link Behavior} interface
+ * as hand-written definitions.
+ *
+ *   define({ names: ['sort'], summary: 'sort lines',
+ *            spec: { short: 'nru', shortWithArg: 'okt', long: { output: '=o' } },
+ *            operands: 'read*', flags: { o: 'write' } })
+ *
+ * Operand patterns are space-separated tokens matched against the operands in
+ * order. A token is `kind[:dir][~][*|?]`:
+ *
+ *   read write append delete   a path effect (resolved against the cwd);
+ *                              `-` as a read operand means stdin
+ *   url                        a network effect with the operand as target
+ *   pattern code subcommand    a display hint (h.role), no effect
+ *   arg                        any other operand (a mode, a size, a key), no effect
+ *   cmd                        the rest of the operands is a command to analyze
+ *                              (wrappers; needs `spec.posix`)
+ *   :dir                       display hint: the operand is a directory
+ *   ~                          the effect is only possible (`maybe`)
+ *   *                          any number (at most one starred token per pattern)
+ *   ?                          optional (documentation only: missing operands just have no effect)
+ *
+ * Operands beyond a pattern without `*` make the result incomplete. Unknown
+ * flags make it incomplete too (as with hand-written definitions).
+ *
+ * Anything the table cannot say goes into `when` (overrides applied when a
+ * flag is present), `subcommands` (a table per subcommand), or `extra` (a
+ * function post-processing the result). See docs/behaviors.md.
+ */
+
+import type { AValue } from '../analysis/value.ts'
+import { concrete, known } from '../analysis/value.ts'
+import type { Effect } from '../policy/effects.ts'
+import type { ArgSpec, Behavior, BehaviorHelpers, BehaviorResult, Invocation, OutputInfo, ParsedArgs } from './types.ts'
+
+/** A fixed effect a command always has: paths may start with `~/` (the home directory); relative ones resolve against the cwd. */
+export type StaticEffect =
+  | { kind: 'read' | 'write' | 'delete'; path: string; recursive?: boolean; maybe?: boolean }
+  | { kind: 'network'; detail: string; maybe?: boolean }
+  | { kind: 'process' | 'unknown'; detail: string }
+
+export interface Def {
+  summary?: string
+  /** Option syntax (see {@link ArgSpec}). */
+  spec?: ArgSpec
+  /** Operand pattern, e.g. `'read*'`, `'arg write*'`, `'read* write'`. Default: no operands expected. */
+  operands?: string
+  /** Option values by canonical flag name: `{ o: 'write', f: 'read', e: 'pattern' }` (same kinds as operand tokens). */
+  flags?: Record<string, string>
+  /** Flags not in `spec` are accepted (they do not make the result incomplete): for query-only subcommands. */
+  anyFlags?: boolean
+  /** Path effects are recursive: always, or when one of these flags is present. */
+  recursive?: boolean | string[]
+  /** Reads are of names and metadata only (`ls`, `tree`, `du`): marked `names: true`, never content reads. */
+  namesOnly?: boolean
+  /** Without path operands, the first path token applies to the cwd (`ls`, `rg`). */
+  cwdIfNone?: boolean
+  /** Does it read stdin? `'operands'`: when no read operand is given or one is `-`. Default: `'operands'` if the pattern has a read token, else `'maybe'`. */
+  stdin?: boolean | 'maybe' | 'operands'
+  stdout?: OutputInfo
+  /** Effects the command always has, in addition to the operand ones. */
+  effects?: StaticEffect[]
+  /** The command runs code or does things the table cannot describe: an `unknown` effect with this detail, and `complete: false`. */
+  opaque?: string
+  /** Overrides applied when a flag is present; keys are canonical flag names, `|`-separated alternatives (`'a|append'`). Later entries win. */
+  when?: Record<string, Def>
+  /**
+   * The first operand is a subcommand looked up here (`'list|ls'` keys for
+   * aliases, `'*'` for any other, `''` for none). `spec` then describes the
+   * global options before it (parsed POSIX-style); the subcommand's own
+   * `spec` its options. A subcommand not in the table is incomplete.
+   */
+  subcommands?: Record<string, Def>
+  /** Post-process the computed result (the escape hatch for what the table cannot express). */
+  extra?: (r: BehaviorResult, c: { inv: Invocation; h: BehaviorHelpers; p: ParsedArgs; operands: AValue[] }) => BehaviorResult
+}
+
+interface Token { kind: string; dir: boolean; maybe: boolean; star: boolean }
+
+const KINDS = new Set(['read', 'write', 'append', 'delete', 'url', 'pattern', 'code', 'subcommand', 'arg', 'cmd'])
+const PATH_KINDS = new Set(['read', 'write', 'append', 'delete'])
+
+const tokenCache = new Map<string, Token[]>()
+function tokens(pattern: string): Token[] {
+  let t = tokenCache.get(pattern)
+  if (t) return t
+  t = pattern.split(/\s+/).filter(Boolean).map((s): Token => {
+    const m = /^([a-z]+)(:dir)?(~)?([*?])?$/.exec(s)
+    if (!m || !KINDS.has(m[1])) throw new Error(`bad operand token '${s}'`)
+    return { kind: m[1], dir: !!m[2], maybe: !!m[3], star: m[4] === '*' }
+  })
+  if (t.filter((x) => x.star).length > 1) throw new Error(`more than one starred token in '${pattern}'`)
+  tokenCache.set(pattern, t)
+  return t
+}
+
+/** Assign operands to tokens: fixed tokens before the star from the left, after it from the right. */
+function match(toks: Token[], ops: AValue[]): { pairs: [Token, AValue][]; extra: AValue[] } {
+  const star = toks.findIndex((t) => t.star)
+  const pairs: [Token, AValue][] = []
+  const cmd = toks.findIndex((t) => t.kind === 'cmd')
+  if (star === -1) {
+    const n = cmd === -1 ? Math.min(toks.length, ops.length) : Math.min(cmd, ops.length)
+    for (let i = 0; i < n; i++) pairs.push([toks[i], ops[i]])
+    if (cmd !== -1 && ops.length > cmd) return { pairs: [...pairs, [toks[cmd], ops[cmd]]], extra: [] }
+    return { pairs, extra: ops.slice(n) }
+  }
+  const before = toks.slice(0, star)
+  const after = toks.slice(star + 1)
+  const nb = Math.min(before.length, ops.length)
+  for (let i = 0; i < nb; i++) pairs.push([before[i], ops[i]])
+  const rest = ops.slice(nb)
+  const na = Math.min(after.length, rest.length)
+  const mid = rest.slice(0, rest.length - na)
+  for (const o of mid) pairs.push([toks[star], o])
+  for (let i = 0; i < na; i++) pairs.push([after[after.length - na + i], rest[mid.length + i]])
+  return { pairs, extra: [] }
+}
+
+function has(p: ParsedArgs, key: string): boolean {
+  return key.split('|').some((k) => p.flags.has(k))
+}
+
+/** The definition after applying `when` overrides for the flags present. */
+function effective(def: Def, p: ParsedArgs): Def {
+  if (!def.when) return def
+  let d: Def = { ...def }
+  for (const [k, o] of Object.entries(def.when)) if (has(p, k)) d = { ...d, ...o }
+  return d
+}
+
+function staticEffect(e: StaticEffect, h: BehaviorHelpers): Effect {
+  if ('path' in e) {
+    const home = h.home()
+    const path = e.path === '~' || e.path.startsWith('~/')
+      ? { alts: (home ?? known('~')).alts.map((a) => [...a, e.path.slice(1)].filter((s) => s !== '')) }
+      : h.resolve(known(e.path))
+    return { kind: e.kind, path, ...(e.recursive ? { recursive: true } : {}), ...(e.maybe ? { maybe: true } : {}) }
+  }
+  if (e.kind === 'network') return { kind: 'network', detail: e.detail, ...(e.maybe ? { maybe: true } : {}) }
+  return { kind: e.kind, detail: e.detail }
+}
+
+const isDash = (v: AValue): boolean => concrete(v) === '-'
+
+/** Analyze `argv` (operands and options, argv[0] excluded) with a definition. */
+export function analyzeDef(def: Def, inv: Invocation, argv: AValue[], h: BehaviorHelpers): BehaviorResult {
+  if (def.subcommands) return analyzeSubcommand(def, inv, argv, h)
+  const p = h.parseArgs(argv, def.spec ?? {})
+  const d = effective(def, p)
+  const toks = tokens(d.operands ?? '')
+  const recursive = d.recursive === true || (Array.isArray(d.recursive) && d.recursive.some((k) => has(p, k)))
+  const effects: Effect[] = []
+  let complete = p.unknownFlags.length === 0 || d.anyFlags === true
+  let readsStdin: boolean | 'maybe' | undefined
+  let stdout = d.stdout
+  let sawRead = false
+  let sawDash = false
+  let sawPath = false
+
+  const apply = (t: Token, v: AValue, option: boolean): void => {
+    if (t.dir) h.role(v, 'dir')
+    switch (t.kind) {
+      case 'read':
+      case 'write':
+      case 'append':
+      case 'delete': {
+        if (isDash(v) && (t.kind === 'read' || option)) {
+          if (t.kind === 'read') sawDash = true
+          return
+        }
+        if (t.kind === 'read' && !option) sawRead = true
+        if (!option) sawPath = true
+        const kind = t.kind === 'append' ? 'write' : t.kind
+        effects.push({ kind, path: h.resolve(v), ...(recursive ? { recursive: true } : {}), ...(t.kind === 'append' ? { append: true } : {}), ...(t.maybe ? { maybe: true } : {}) } as Effect)
+        return
+      }
+      case 'url':
+        effects.push({ kind: 'network', target: v, detail: inv.name })
+        return
+      case 'pattern':
+      case 'code':
+      case 'subcommand':
+        h.role(v, t.kind)
+        return
+    }
+  }
+
+  const { pairs, extra } = match(toks, p.operands)
+  if (extra.length > 0) complete = false
+  for (const [t, v] of pairs) {
+    if (t.kind === 'cmd') {
+      const at = p.operands.indexOf(v)
+      const sub = h.subcommand(p.operands.slice(at))
+      effects.push(...sub.effects)
+      if (sub.complete === false) complete = false
+      readsStdin = sub.readsStdin
+      stdout ??= sub.stdout
+      continue
+    }
+    apply(t, v, false)
+  }
+  if (d.cwdIfNone && !sawPath) {
+    const first = toks.find((t) => PATH_KINDS.has(t.kind))
+    if (first) {
+      const kind = first.kind === 'append' ? 'write' : first.kind
+      effects.push({ kind, path: inv.cwd, ...(recursive ? { recursive: true } : {}), ...(first.maybe ? { maybe: true } : {}) } as Effect)
+      if (kind === 'read') sawRead = true
+    }
+  }
+  for (const [k, pattern] of Object.entries(d.flags ?? {})) {
+    const t = tokens(pattern)[0]
+    for (const v of p.multi.get(k) ?? []) apply(t, v, true)
+  }
+  for (const e of d.effects ?? []) effects.push(staticEffect(e, h))
+  if (d.opaque) {
+    effects.push({ kind: 'unknown', detail: d.opaque })
+    complete = false
+  }
+  if (readsStdin === undefined) {
+    const stdin = d.stdin ?? (toks.some((t) => t.kind === 'read') ? 'operands' : 'maybe')
+    readsStdin = stdin === 'operands' ? !sawRead || sawDash : stdin
+  }
+  const r: BehaviorResult = { effects, readsStdin, complete, ...(stdout ? { stdout } : {}) }
+  return d.extra ? d.extra(r, { inv, h, p, operands: p.operands }) : r
+}
+
+function analyzeSubcommand(def: Def, inv: Invocation, argv: AValue[], h: BehaviorHelpers): BehaviorResult {
+  const p = h.parseArgs(argv, { ...def.spec, posix: true })
+  const d = effective(def, p)
+  // the global options' own effects (option values, fixed effects)
+  const base: Effect[] = []
+  for (const [k, pattern] of Object.entries(d.flags ?? {})) {
+    const t = tokens(pattern)[0]
+    for (const v of p.multi.get(k) ?? []) {
+      if (t.dir) h.role(v, 'dir')
+      if (PATH_KINDS.has(t.kind) && !isDash(v)) base.push({ kind: t.kind === 'append' ? 'write' : t.kind, path: h.resolve(v) } as Effect)
+      else if (t.kind === 'pattern' || t.kind === 'code') h.role(v, t.kind)
+    }
+  }
+  for (const e of d.effects ?? []) base.push(staticEffect(e, h))
+  if (d.opaque) base.push({ kind: 'unknown', detail: d.opaque })
+  const globalComplete = (p.unknownFlags.length === 0 || d.anyFlags === true) && !d.opaque
+  const [subv, ...rest] = p.operands
+  const table = d.subcommands!
+  const lookup = (name: string): Def | undefined => {
+    for (const [k, v] of Object.entries(table)) if (k !== '*' && k.split('|').includes(name)) return v
+    return table['*']
+  }
+  if (subv === undefined) {
+    const none = table['']
+    if (!none) return { effects: base, readsStdin: false, complete: globalComplete }
+    const r = analyzeDef(none, inv, [], h)
+    return { ...r, effects: [...base, ...r.effects], complete: globalComplete && r.complete !== false }
+  }
+  const name = concrete(subv)
+  if (name === undefined) {
+    return { effects: [...base, { kind: 'unknown', detail: `${inv.name} subcommand is not known statically` }], readsStdin: 'maybe', complete: false }
+  }
+  h.role(subv, 'subcommand')
+  const sub = lookup(name)
+  if (!sub) return { effects: [...base, { kind: 'unknown', detail: `${inv.name} ${name}` }], readsStdin: 'maybe', complete: false }
+  // global options are usually accepted after the subcommand too
+  const r = analyzeDef({ ...sub, spec: mergeSpec(def.spec, sub.spec) }, inv, rest, h)
+  return { ...r, effects: [...base, ...r.effects], complete: globalComplete && r.complete !== false }
+}
+
+function mergeSpec(outer: ArgSpec | undefined, inner: ArgSpec | undefined): ArgSpec {
+  if (!outer) return inner ?? {}
+  if (!inner) return { ...outer, posix: false }
+  return {
+    ...inner,
+    short: (inner.short ?? '') + (outer.short ?? ''),
+    shortWithArg: (inner.shortWithArg ?? '') + [...(outer.shortWithArg ?? '')].filter((c) => !(inner.short ?? '').includes(c)).join(''),
+    long: { ...outer.long, ...inner.long },
+  }
+}
+
+/** Compile a table definition to a {@link Behavior}. */
+export function define(def: Def & { names: string[] }): Behavior {
+  return {
+    names: def.names,
+    summary: def.summary,
+    analyze: (inv, h) => {
+      const r = analyzeDef(def, inv, inv.argv.slice(1), h)
+      if (!def.namesOnly) return r
+      return { ...r, effects: r.effects.map((e) => (e.kind === 'read' ? { ...e, names: true } : e)) }
+    },
+  }
+}

package/src/behaviors/index.ts

@@ -0,0 +1,19 @@
+import { BehaviorRegistry } from './registry.ts'
+import { coreBehaviors } from './defs/core.ts'
+import { devtoolBehaviors } from './defs/devtools.ts'
+import { toolBehaviors } from './defs/tools.ts'
+import { macosBehaviors } from './defs/macos.ts'
+
+export * from './types.ts'
+export { BehaviorRegistry, parseArgs, resolvePath, basename } from './registry.ts'
+export { coreBehaviors } from './defs/core.ts'
+export { devtoolBehaviors } from './defs/devtools.ts'
+export { toolBehaviors } from './defs/tools.ts'
+export { macosBehaviors } from './defs/macos.ts'
+export { define, analyzeDef, type Def, type StaticEffect } from './dsl.ts'
+
+/** A registry with every bundled definition. */
+export function defaultBehaviors(): BehaviorRegistry {
+  return new BehaviorRegistry([...coreBehaviors, ...devtoolBehaviors, ...toolBehaviors, ...macosBehaviors])
+}
+export { argRoles, lexicalRole } from './roles.ts'

package/src/behaviors/registry.ts

@@ -0,0 +1,261 @@
+/**
+ * The behavior registry: looks up a definition by command basename and
+ * provides the helpers definitions use (abstract path resolution, GNU-style
+ * argument parsing over abstract values, nested command analysis).
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import type { AValue } from '../analysis/value.ts'
+import { concat, concrete, describe, isHole, known, knownPrefix, unknownString } from '../analysis/value.ts'
+import type { ArgSpec, Behavior, BehaviorHelpers, BehaviorResult, Invocation, ParsedArgs, ScriptInfo, StdinKind } from './types.ts'
+
+/** Analyze a shell script (provided by the static analyzer, to avoid a dependency cycle). */
+export type ScriptAnalyzer = (source: AValue, positional: AValue[], inv: Invocation, info?: ScriptInfo) => BehaviorResult
+
+const MAX_DEPTH = 8
+
+/** Observes helper calls (used to map effects back to the arguments they came from). */
+export interface HelperTracer {
+  resolved(input: AValue, output: AValue): void
+  role(value: AValue, role: import('./types.ts').ArgRole): void
+}
+
+export class BehaviorRegistry {
+  private readonly byName = new Map<string, Behavior>()
+  scriptAnalyzer: ScriptAnalyzer | null = null
+  /** When set, helper calls are reported to it (see roles.ts). */
+  tracer: HelperTracer | null = null
+
+  constructor(behaviors: Behavior[] = []) {
+    for (const b of behaviors) this.add(b)
+  }
+
+  add(b: Behavior): this {
+    for (const n of b.names) this.byName.set(n, b)
+    return this
+  }
+
+  get(name: string): Behavior | undefined {
+    return this.byName.get(basename(name))
+  }
+
+  names(): string[] {
+    return [...this.byName.keys()].sort()
+  }
+
+  /**
+   * Analyze one invocation. Commands without a definition yield a single
+   * `unknown` effect and `complete: false`.
+   */
+  analyze(inv: Invocation, depth = 0): BehaviorResult {
+    const name = inv.name
+    const b = this.byName.get(name)
+    if (!b) {
+      const script = this.shellScriptOf(inv)
+      if (script !== undefined && this.scriptAnalyzer && depth <= MAX_DEPTH) {
+        const r = this.scriptAnalyzer(known(script.text), inv.argv.slice(1), inv, { file: script.path })
+        return { ...r, effects: [{ kind: 'read', path: known(script.path), source: name }, ...r.effects] }
+      }
+      return { effects: [{ kind: 'unknown', detail: `no behavior definition for '${name}'`, source: name }], complete: false, readsStdin: 'maybe' }
+    }
+    if (depth > MAX_DEPTH) return { effects: [{ kind: 'unknown', detail: 'nesting too deep', source: name }], complete: false }
+    const h = this.helpers(inv, depth)
+    try {
+      const r = b.analyze(inv, h)
+      for (const e of r.effects) e.source ??= name
+      return { complete: true, readsStdin: 'maybe', ...r }
+    } catch (e) {
+      return { effects: [{ kind: 'unknown', detail: `behavior '${name}' failed: ${(e as Error).message}`, source: name }], complete: false }
+    }
+  }
+
+  /** An executable file with a bash/sh shebang named by argv[0]. */
+  private shellScriptOf(inv: Invocation): { path: string; text: string } | undefined {
+    const a0 = concrete(inv.argv[0])
+    if (a0 === undefined || !a0.includes('/')) return undefined
+    const p = concrete(resolvePath(known(a0), inv.cwd))
+    if (p === undefined) return undefined
+    try {
+      const st = fs.statSync(p)
+      if (!st.isFile() || st.size > 1024 * 1024) return undefined
+      const text = fs.readFileSync(p, 'utf8')
+      const m = /^#![ \t]*(\S+)(?:[ \t]+(\S+))?/.exec(text.split('\n')[0])
+      if (!m) return undefined
+      const interp = basename(m[1]) === 'env' ? m[2] : basename(m[1])
+      return interp === 'bash' || interp === 'sh' ? { path: p, text } : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  helpers(inv: Invocation, depth: number): BehaviorHelpers {
+    const tracer = this.tracer
+    const resolve = (p: AValue): AValue => {
+      const r = resolvePath(p, inv.cwd)
+      tracer?.resolved(p, r)
+      return r
+    }
+    return {
+      resolve,
+      role: (value, role) => tracer?.role(value, role),
+      parseArgs,
+      subcommand: (argv, opts = {}) => {
+        if (argv.length === 0) return { effects: [] }
+        const n = concrete(argv[0])
+        if (n === undefined) {
+          return { effects: [{ kind: 'unknown', detail: `command name ${describe(argv[0])} is not known statically`, source: inv.name }], complete: false }
+        }
+        const sub: Invocation = { ...inv, name: basename(n), argv, stdin: opts.stdin ?? inv.stdin, cwd: opts.cwd ?? inv.cwd }
+        const r = this.analyze(sub, depth + 1)
+        return { ...r, effects: [{ kind: 'exec', argv }, ...r.effects] }
+      },
+      script: (source, positional = [], info) => {
+        tracer?.role(source, 'code')
+        if (!this.scriptAnalyzer) return { effects: [{ kind: 'unknown', detail: 'no script analyzer', source: inv.name }], complete: false }
+        return this.scriptAnalyzer(source, positional, inv, info)
+      },
+      home: () => inv.env('HOME') ?? known(os.homedir()),
+    }
+  }
+}
+
+export function basename(p: string): string {
+  const i = p.lastIndexOf('/')
+  return i === -1 ? p : p.slice(i + 1)
+}
+
+/** Resolve a path value against a cwd: absolute values stay, relative ones are joined. Literal `.`/`..` are left for the policy shape check. */
+export function resolvePath(p: AValue, cwd: AValue): AValue {
+  const alts = p.alts.map((alt): AValue[] => {
+    const first = alt[0]
+    if (first === undefined) return [cwd]
+    if (typeof first === 'string' && first.startsWith('/')) return [{ alts: [alt] }]
+    if (isHole(first) && first.type === 'path' && first.under) return [{ alts: [alt] }]
+    // a `~` that reaches a behavior is literal: word expansion has already expanded unquoted tildes
+    // ("~/x" names ./~/x, as in bash)
+    return [cwd, known('/'), { alts: [alt] }]
+  })
+  const parts = alts.map((a) => concat(...a))
+  if (parts.length === 1) return parts[0]
+  return { alts: parts.flatMap((v) => v.alts) }
+}
+
+/**
+ * GNU-style argument parsing over abstract values. Concrete arguments parse
+ * normally; an unknown argument whose known prefix starts with `-` is
+ * recorded as an unknown flag; one whose first character is unknown could be
+ * an option or an operand, so it is returned both as an operand and in
+ * `ambiguous`.
+ */
+export function parseArgs(args: AValue[], spec: ArgSpec): ParsedArgs {
+  const flags = new Map<string, AValue | true>()
+  const multi = new Map<string, AValue[]>()
+  const operands: AValue[] = []
+  const ambiguous: AValue[] = []
+  const unknownFlags: string[] = []
+  const short = spec.short ?? ''
+  const shortArg = spec.shortWithArg ?? ''
+  const long = spec.long ?? {}
+  const setFlag = (name: string, v: AValue | true): void => {
+    flags.set(name, v)
+    if (v !== true) {
+      const list = multi.get(name) ?? []
+      list.push(v)
+      multi.set(name, list)
+    }
+  }
+  let onlyOperands = false
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    const s = concrete(a)
+    if (onlyOperands) {
+      operands.push(a)
+      continue
+    }
+    if (s === undefined) {
+      const prefix = knownPrefix(a)
+      if (prefix.startsWith('-') && prefix.length > 1) {
+        unknownFlags.push(describe(a))
+      } else if (prefix === '') {
+        operands.push(a)
+        ambiguous.push(a)
+      } else {
+        operands.push(a)
+        if (spec.posix) onlyOperands = true
+      }
+      continue
+    }
+    if (s === '--') {
+      onlyOperands = true
+      continue
+    }
+    const single = spec.longSingle === true && s.length > 2 && s[0] === '-' && s[1] !== '-'
+    if ((s.startsWith('--') && s.length > 2) || single) {
+      const body = s.slice(single ? 1 : 2)
+      const eq = body.indexOf('=')
+      const name = eq === -1 ? body : body.slice(0, eq)
+      // allow unambiguous prefixes (not for single-dash options, which fall back to short flags)
+      let key = Object.hasOwn(long, name) ? name : undefined
+      if (key === undefined && !single) {
+        const candidates = Object.keys(long).filter((k) => k.startsWith(name))
+        if (candidates.length === 1) key = candidates[0]
+      }
+      if (key !== undefined) {
+        const kind = long[key]
+        const canonical = typeof kind === 'string' && kind.startsWith('=') ? kind.slice(1) : key
+        const n = typeof kind === 'number' ? kind : typeof kind === 'string' ? (shortArg.includes(canonical) ? spec.arity?.[canonical] ?? 1 : 0) : kind ? 1 : 0
+        if (n > 0) {
+          if (eq !== -1 && n === 1) setFlag(canonical, known(body.slice(eq + 1)))
+          else if (i + n < args.length) {
+            i += n
+            setFlag(canonical, args[i])
+          } else {
+            i = args.length
+            setFlag(canonical, unknownString(`${s} (missing)`))
+          }
+        } else setFlag(canonical, true)
+        continue
+      }
+      if (!single) {
+        unknownFlags.push(s)
+        continue
+      }
+    }
+    if (spec.numeric && /^-\d+$/.test(s)) {
+      setFlag(spec.numeric, known(s.slice(1)))
+      continue
+    }
+    if (s.startsWith('-') && s.length > 1) {
+      for (let j = 1; j < s.length; j++) {
+        const f = s[j]
+        if (shortArg.includes(f)) {
+          const rest = s.slice(j + 1)
+          const n = spec.arity?.[f] ?? 1
+          if (rest !== '' && n === 1) setFlag(f, known(rest))
+          else {
+            const need = rest !== '' ? n - 1 : n
+            if (i + need < args.length) {
+              i += need
+              setFlag(f, args[i])
+            } else {
+              i = args.length
+              setFlag(f, unknownString(`-${f} (missing)`))
+            }
+          }
+          break
+        }
+        if (short.includes(f)) setFlag(f, true)
+        else unknownFlags.push('-' + f)
+      }
+      continue
+    }
+    operands.push(a)
+    if (spec.posix) onlyOperands = true
+  }
+  return { flags, multi, operands, ambiguous, unknownFlags }
+}
+
+export function stdinOf(kind: StdinKind): StdinKind {
+  return kind
+}