@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/printer/print.ts

@@ -0,0 +1,528 @@
+/**
+ * Pretty-printer: renders a parsed script as readable bash that parses to the
+ * same AST (see docs/pretty-printer.md).
+ *
+ * Words, assignment values, redirections, here-doc bodies, arithmetic and
+ * `[[ ]]` expressions are emitted as their exact source text; only the layout
+ * (newlines, ` \` continuations, indentation) is regenerated.
+ */
+
+import type * as A from '../parser/ast.ts'
+import { parse, literalOf } from '../parser/parser.ts'
+import type { ArgRole } from '../behaviors/types.ts'
+import { simpleCommandRoles } from './highlight.ts'
+import {
+  type AtomInfo, type Doc, blankLine, compoundGroup, cont, contForced, fill, group, hard, heredoc, indent, join, mark, nl, render, src, suffix, tok,
+} from './doc.ts'
+
+export interface FormatOptions {
+  /** Target line width (default 80). Single words longer than this overflow. */
+  width?: number
+  /** Indentation step (default 2). Wrapped arguments are indented twice this. */
+  indent?: number
+  /** Where `|`, `&&`, `||` go when a chain is broken: end of line (default) or start (with `\` continuations). */
+  operators?: 'trailing' | 'leading'
+  /**
+   * Prefix assignments (`FOO=1 BAR=2 cmd`): `auto` (default) puts each on its
+   * own line when there are two or more, or when the command does not fit;
+   * `always` does so for any number; `inline` only when it does not fit.
+   */
+  assignments?: 'auto' | 'always' | 'inline'
+  /** Compound commands: `auto` (default) keeps short ones on one line when they fit; `expanded` always expands. */
+  compounds?: 'auto' | 'expanded'
+  /** Reformat multi-line `$(…)` / `<(…)` bodies inside words (default false: verbatim). */
+  formatSubstitutions?: boolean
+  /** Keep at most this many blank lines between statements (default 1; 0 drops them). */
+  blankLines?: number
+  /** `function` keyword: normalize to `name()` (default) or preserve the original header. */
+  functionKeyword?: 'normalize' | 'preserve'
+  /**
+   * Top-level statements that share a source line (`a; b; c`). bash reads a
+   * script line by line: an expansion error (bad arithmetic, readonly
+   * assignment) discards the rest of the *logical* line, and an alias is only
+   * active from the next line. So:
+   * - `continuation` (default): one per line joined by `; \` — exactly the same behavior;
+   * - `newline`: plain separate lines (differs only after such an error);
+   * - `preserve`: keep them on one line.
+   * Inside compound commands and `$(…)` layout never matters (they are parsed whole).
+   */
+  statements?: 'continuation' | 'newline' | 'preserve'
+}
+
+export interface FormatResult {
+  text: string
+  /** Output range of every statement and command, by AST node id. */
+  map: Map<number, { start: number; end: number }>
+}
+
+/** Options with defaults applied. */
+export type Opts = Required<FormatOptions>
+
+const DEFAULTS: Opts = {
+  width: 80, indent: 2, operators: 'trailing', assignments: 'auto', compounds: 'auto',
+  formatSubstitutions: false, blankLines: 1, functionKeyword: 'normalize', statements: 'continuation',
+}
+
+/** Parse and pretty-print `source`. Throws ParseError on invalid input. */
+export function format(source: string, options: FormatOptions = {}): FormatResult {
+  return printScript(parse(source), source, options)
+}
+
+/** Pretty-print an already parsed script; `source` must be the text it was parsed from. */
+export function printScript(script: A.Script, source: string, options: FormatOptions = {}): FormatResult {
+  const { doc, opts } = buildDoc(script, source, options)
+  const r = render(doc, opts.width, { source })
+  return { text: r.text, map: r.map }
+}
+
+/** The layout document for a script (shared by the text and HTML renderers). */
+export function buildDoc(script: A.Script, source: string, options: FormatOptions = {}): { doc: Doc; opts: Opts } {
+  const opts = { ...DEFAULTS, ...options }
+  const p = new Printer(source, script.comments ?? [], opts)
+  p.lineHazard = usesLineSensitiveBuiltins(script)
+  const doc = p.topLevel(script)
+  const leftover = p.remainingComments()
+  return { doc: leftover.length ? [doc, hard, join(hard, leftover)] : doc, opts }
+}
+
+/** `alias` and `shopt` change how *later lines* are parsed: never split their lines (docs/pretty-printer.md §5). */
+function usesLineSensitiveBuiltins(script: A.Script): boolean {
+  let found = false
+  const visit = (n: unknown): void => {
+    if (found || n === null || typeof n !== 'object') return
+    if (Array.isArray(n)) {
+      for (const x of n) visit(x)
+      return
+    }
+    const node = n as { type?: string; words?: (A.Word | A.Assign)[] }
+    if (node.type === 'SimpleCommand') {
+      const w = node.words?.[0]
+      const name = w && w.type === 'Word' ? literalOf(w) : null
+      if (name === 'alias' || name === 'shopt' || name === 'unalias') found = true
+    }
+    for (const [k, v] of Object.entries(node)) if (k !== 'span' && v && typeof v === 'object') visit(v)
+  }
+  visit(script.body)
+  return found
+}
+
+type Body = A.Stmt[]
+
+const kw = (text: string): Doc => tok(text, 'kw')
+const op = (text: string): Doc => tok(text, 'op')
+
+/** The plain text of a simple document (src/tok/string), or null. */
+function plain(d: Doc, source: string): string | null {
+  if (typeof d === 'string') return d
+  if (Array.isArray(d)) return null
+  if (d.t === 'src') return source.slice(d.start, d.end)
+  if (d.t === 'tok') return d.text
+  return null
+}
+
+class Printer {
+  readonly src: string
+  readonly opts: Opts
+  lineHazard = false
+  private readonly comments: A.Comment[]
+  private readonly used: boolean[]
+
+  constructor(source: string, comments: A.Comment[], opts: Opts) {
+    this.src = source
+    this.comments = comments
+    this.used = comments.map(() => false)
+    this.opts = opts
+  }
+
+  /** Verbatim source, consuming the comments inside it. */
+  private verbatim(span: A.Span, atom?: AtomInfo, cls?: string): Doc {
+    this.consume(span)
+    return src(span.start, span.end, atom, cls)
+  }
+
+  private commentDoc(c: A.Comment): Doc {
+    const i = this.comments.indexOf(c)
+    return src(c.span.start, c.span.end, { id: -(i + 1), kind: 'cm', weight: 0.8 }, 'cm')
+  }
+
+  // -------------------------------------------------------------------------
+  // Comments
+  // -------------------------------------------------------------------------
+
+  /** Mark comments inside a verbatim span as printed (they are part of the text). */
+  private consume(span: A.Span): void {
+    this.comments.forEach((c, i) => {
+      if (!this.used[i] && c.span.start >= span.start && c.span.end <= span.end) this.used[i] = true
+    })
+  }
+
+  /** Unprinted comments that start before `offset`, in order (marked printed). */
+  private take(offset: number): A.Comment[] {
+    const out: A.Comment[] = []
+    this.comments.forEach((c, i) => {
+      if (!this.used[i] && c.span.start < offset) {
+        this.used[i] = true
+        out.push(c)
+      }
+    })
+    return out
+  }
+
+  /** The unprinted comment that follows `end` on the same source line, if any. */
+  private trailing(end: number, limit: number): A.Comment | null {
+    for (let i = 0; i < this.comments.length; i++) {
+      const c = this.comments[i]
+      if (this.used[i] || c.span.start < end || c.span.start >= limit) continue
+      if (this.src.slice(end, c.span.start).includes('\n')) return null
+      this.used[i] = true
+      return c
+    }
+    return null
+  }
+
+  private trailingDoc(c: A.Comment): Doc {
+    return suffix([' ', this.commentDoc(c)])
+  }
+
+  remainingComments(): Doc[] {
+    return this.take(Infinity).map((c) => this.commentDoc(c))
+  }
+
+  // -------------------------------------------------------------------------
+  // Statement lists
+  // -------------------------------------------------------------------------
+
+  topLevel(script: A.Script): Doc {
+    return this.list(script.body, script.span.end, true, true)
+  }
+
+  /**
+   * A statement list. `alwaysBreak` for the script top level; otherwise the
+   * separators are `nl` breaks that print `; ` when the enclosing group fits.
+   */
+  private list(stmts: Body, endOffset: number, alwaysBreak: boolean, top = false): Doc {
+    const parts: Doc[] = []
+    stmts.forEach((s, i) => {
+      const leading = this.take(s.span.start)
+      if (i > 0) {
+        const prev = stmts[i - 1]
+        const between = this.src.slice(prev.span.end, s.span.start)
+        // the same *logical* line: backslash-newline continuations do not end it
+        const sameLine = !between.replace(/\\\n/g, '').includes('\n')
+        if (top && sameLine && leading.length === 0 && this.opts.statements === 'continuation') {
+          parts.push(prev.background ? '' : op(';'), contForced)
+        } else if (sameLine && leading.length === 0 && ((top && this.opts.statements === 'preserve') || (this.lineHazard && this.opts.statements === 'newline'))) {
+          parts.push(prev.background ? ' ' : [op(';'), ' '])
+        } else {
+          const blank = this.opts.blankLines > 0 && /\n[ \t]*\n/.test(between)
+          if (alwaysBreak || leading.length > 0) parts.push(blank ? blankLine : hard)
+          else parts.push(nl(prev.background ? ' ' : '; ', blank))
+        }
+      }
+      for (const c of leading) parts.push(this.commentDoc(c), hard)
+      parts.push(this.stmt(s))
+      const next = stmts[i + 1]
+      const t = this.trailing(s.span.end, next ? next.span.start : endOffset)
+      if (t) parts.push(this.trailingDoc(t))
+    })
+    return parts
+  }
+
+  /** Does a body qualify to stay on one line (`compounds: 'auto'`)? */
+  private simpleBody(body: Body): boolean {
+    if (this.opts.compounds === 'expanded' || body.length !== 1) return false
+    const c = body[0].command
+    return c.type === 'SimpleCommand' || c.type === 'Pipeline' || c.type === 'AndOr'
+  }
+
+  private stmt(s: A.Stmt): Doc {
+    return mark(s.id, [this.command(s.command), s.background ? [' ', op('&')] : ''])
+  }
+
+  // -------------------------------------------------------------------------
+  // Commands
+  // -------------------------------------------------------------------------
+
+  private command(c: A.Command): Doc {
+    return mark(c.id, this.commandInner(c))
+  }
+
+  private commandInner(c: A.Command): Doc {
+    switch (c.type) {
+      case 'SimpleCommand': return this.simple(c)
+      case 'Pipeline': return this.pipeline(c)
+      case 'AndOr': return this.andOr(c)
+      case 'FunctionDef': return this.functionDef(c)
+      default: return [this.compound(c), this.compoundRedirs(c)]
+    }
+  }
+
+  /** Truncation preference for an argument word: strings and substitutions first. */
+  /**
+   * Truncation preference for an argument word: strings and substitutions
+   * first, then paths (shortened from the left), then plain words. Command
+   * names, flags and subcommands are never shortened.
+   */
+  private wordAtom(w: A.Word, role: 'cmd' | 'arg', argRole?: ArgRole): AtomInfo | undefined {
+    if (role === 'cmd' || argRole === 'cmd' || argRole === 'subcommand') return undefined
+    const text = this.src.slice(w.span.start, w.span.end)
+    if (/^-/.test(text) && !/[=\s]/.test(text)) return undefined
+    if ((argRole === 'file' || argRole === 'dir') && text.includes('/') && !text.includes('\n')) return { id: w.id, kind: 'word', weight: 0.9, tail: true }
+    const rich = w.parts.some((p) => p.type !== 'Lit' && p.type !== 'Escaped')
+    return { id: w.id, kind: 'word', weight: rich ? 1 : 0.6 }
+  }
+
+  private wordDoc(w: A.Word, role: 'cmd' | 'arg' = 'arg', argRole?: ArgRole): Doc {
+    if (this.opts.formatSubstitutions) {
+      const d = this.wordWithSubstitutions(w)
+      if (d) return d
+    }
+    return this.verbatim(w.span, this.wordAtom(w, role, argRole))
+  }
+
+  /** Words containing multi-line `$(…)` / `<(…)`: format their bodies, keep the rest verbatim. */
+  private wordWithSubstitutions(w: A.Word): Doc | null {
+    const substs: (A.CmdSubst | A.ProcSubst)[] = []
+    const visit = (parts: A.WordPart[]): void => {
+      for (const p of parts) {
+        if ((p.type === 'CmdSubst' && !p.backquote) || p.type === 'ProcSubst') {
+          if (this.src.slice(p.span.start, p.span.end).includes('\n') && p.body.length > 0) substs.push(p)
+        } else if (p.type === 'DblQuoted') visit(p.parts)
+      }
+    }
+    visit(w.parts)
+    if (substs.length === 0) return null
+    const out: Doc[] = []
+    let cursor = w.span.start
+    for (const s of substs) {
+      out.push(this.verbatim({ start: cursor, end: s.span.start }))
+      const open = s.type === 'CmdSubst' ? '$(' : `${s.direction}(`
+      out.push(tok(open, 'sub'), indent([hard, this.list(s.body, s.span.end, true)], this.opts.indent), hard, tok(')', 'sub'))
+      this.take(s.span.end) // comments right before `)`
+      cursor = s.span.end
+    }
+    out.push(this.verbatim({ start: cursor, end: w.span.end }))
+    return out
+  }
+
+  /** `name=value`: the `name=` part verbatim, the value as a word (so `$(…)` in it can be formatted). */
+  private assignDoc(a: A.Assign): Doc {
+    if (a.value?.type !== 'Word') return this.verbatim(a.span)
+    return [this.verbatim({ start: a.span.start, end: a.value.span.start }), this.wordDoc(a.value)]
+  }
+
+  /** The separator before a closing keyword (`done`, `fi`, `}`): `; ` flat, or ` ` after a background `&`. */
+  private closer(body: Body): Doc {
+    return nl(body[body.length - 1]?.background ? ' ' : '; ')
+  }
+
+  private redirDoc(r: A.Redirect): Doc {
+    if (!r.heredoc) {
+      // `> path`: the target is a path atom (an fd duplication like `2>&1` stays whole)
+      const op = { start: r.span.start, end: r.target.span.start }
+      const target = this.src.slice(r.target.span.start, r.target.span.end)
+      if (r.target.span.end > r.target.span.start && !/&\s*$/.test(this.src.slice(op.start, op.end)) && !target.includes('\n')) {
+        const tail = target.includes('/')
+        return [this.verbatim(op), this.verbatim(r.target.span, { id: r.target.id, kind: 'word', weight: tail ? 0.9 : 0.6, tail })]
+      }
+      return this.verbatim(r.span)
+    }
+    const text = this.verbatim(r.span)
+    const b = r.heredoc.body.span
+    this.consume(b)
+    return [text, heredoc(b.start, b.end, r.heredoc.delimiter, { id: r.id, kind: 'hd', weight: 1 })]
+  }
+
+  private simple(c: A.SimpleCommand): Doc {
+    const assigns = c.assigns.map((a) => this.assignDoc(a))
+    let first = true
+    let roles: (ArgRole | undefined)[] = []
+    try {
+      roles = simpleCommandRoles(c)
+    } catch {
+      // display only
+    }
+    const words = c.words.map((w, i) => {
+      if (w.type === 'Assign') return this.assignDoc(w)
+      const d = this.wordDoc(w, first ? 'cmd' : 'arg', roles[i])
+      first = false
+      return d
+    })
+    const redirs = c.redirs.map((r) => this.redirDoc(r))
+    // keep `-o value`, `-qm value` (combined short flags) and `--opt value` together when wrapping
+    const units: Doc[] = []
+    for (let i = 0; i < words.length; i++) {
+      const w = plain(words[i], this.src)
+      const next = i + 1 < words.length ? plain(words[i + 1], this.src) : null
+      if (i > 0 && w !== null && next !== null && /^(-[A-Za-z]+|--[A-Za-z][\w-]*)$/.test(w) && !next.startsWith('-')) {
+        units.push([words[i], ' ', words[i + 1]])
+        i++
+      } else units.push(words[i])
+    }
+    units.push(...redirs)
+    // the command name, then arguments filled onto lines and indented twice
+    const filled: Doc = units.length <= 1 ? (units[0] ?? '') : [units[0], indent(fill(fillParts(units.slice(1))), this.opts.indent * 2)]
+    if (assigns.length === 0) return group(filled)
+    if (units.length === 0) return group(join(cont, assigns))
+    const ownLines = this.opts.assignments === 'always' || (this.opts.assignments === 'auto' && assigns.length >= 2)
+    if (ownLines) return [join(contForced, assigns), contForced, group(filled)]
+    return group([join(cont, assigns), cont, group(filled)])
+  }
+
+  private operatorChain(items: A.Command[], ops: string[]): Doc {
+    const leading = this.opts.operators === 'leading'
+    const out: Doc[] = [this.command(items[0])]
+    const rest: Doc[] = []
+    for (let i = 1; i < items.length; i++) {
+      const o = ops[i - 1]
+      const comments = this.take(items[i].span.start)
+      if (leading && comments.length === 0) {
+        rest.push(cont, op(o), ' ', this.command(items[i]))
+      } else {
+        rest.push(' ', op(o))
+        for (const cm of comments) rest.push(this.trailingDoc(cm))
+        rest.push(nl(' '), this.command(items[i]))
+      }
+    }
+    out.push(indent(rest, this.opts.indent))
+    return group(out)
+  }
+
+  private pipeline(c: A.Pipeline): Doc {
+    const first = c.stages[0]
+    const prefix = this.src.slice(c.span.start, first.span.start).trim().replace(/\s+/g, ' ')
+    const ops = c.pipeStderr.map((e) => (e ? '|&' : '|'))
+    const chain = c.stages.length === 1 ? this.command(first) : this.operatorChain(c.stages, ops)
+    return prefix ? [kw(prefix), ' ', chain] : chain
+  }
+
+  private andOr(c: A.AndOr): Doc {
+    return this.operatorChain(c.items, c.ops)
+  }
+
+  private functionDef(f: A.FunctionDef): Doc {
+    const header = this.opts.functionKeyword === 'preserve'
+      ? tok(this.src.slice(f.span.start, f.body.span.start).trim().replace(/\s+/g, ' '), 'fn')
+      : tok(`${f.name}()`, 'fn')
+    return [header, ' ', this.command(f.body)]
+  }
+
+  private compoundRedirs(c: A.CompoundCommand): Doc {
+    if (c.redirs.length === 0) return ''
+    return [' ', join(' ', c.redirs.map((r) => this.redirDoc(r)))]
+  }
+
+  /** Source of a compound up to its first redirection (verbatim forms: `(( ))`, `[[ ]]`). */
+  private compoundText(c: A.CompoundCommand): Doc {
+    let end = c.redirs.length > 0 ? c.redirs[0].span.start : c.span.end
+    while (end > c.span.start && /\s/.test(this.src[end - 1])) end--
+    return this.verbatim({ start: c.span.start, end }, { id: c.id, kind: 'word', weight: 0.3 })
+  }
+
+  private body(body: Body, endOffset: number): Doc {
+    return indent([nl(' '), this.list(body, endOffset, false)], this.opts.indent)
+  }
+
+  private compound(c: A.CompoundCommand): Doc {
+    switch (c.type) {
+      case 'Group':
+        return compoundGroup([kw('{'), this.body(c.body, c.span.end), this.closer(c.body), kw('}')], !this.groupable(c.body))
+      case 'Subshell':
+        return compoundGroup([kw('('), this.body(c.body, c.span.end), nl(' '), kw(')')], !this.groupable(c.body))
+      case 'If': {
+        const parts: Doc[] = []
+        const flatOk = c.clauses.every((cl) => this.simpleBody(cl.body) && cl.cond.length === 1) && (c.elseBody === null || this.simpleBody(c.elseBody))
+        c.clauses.forEach((cl, i) => {
+          if (i > 0) parts.push(this.closer(c.clauses[i - 1].body), kw('elif'), ' ')
+          else parts.push(kw('if'), ' ')
+          parts.push(this.condList(cl.cond, cl.body[0]?.span.start ?? c.span.end), op(';'), ' ', kw('then'), this.body(cl.body, c.span.end))
+        })
+        const lastBody = c.clauses[c.clauses.length - 1].body
+        if (c.elseBody) parts.push(this.closer(lastBody), kw('else'), this.body(c.elseBody, c.span.end))
+        parts.push(this.closer(c.elseBody ?? lastBody), kw('fi'))
+        return compoundGroup(parts, !flatOk)
+      }
+      case 'Loop':
+        return compoundGroup([kw(c.kind), ' ', this.condList(c.cond, c.body[0]?.span.start ?? c.span.end), op(';'), ' ', kw('do'), this.body(c.body, c.span.end), this.closer(c.body), kw('done')], !this.simpleBody(c.body))
+      case 'For':
+      case 'Select': {
+        const head: Doc[] = [kw(c.type === 'For' ? 'for' : 'select'), ' ', tok(c.variable, 'var')]
+        if (c.items !== null) head.push(' ', kw('in'), ...c.items.flatMap((w) => [' ', this.wordDoc(w)]))
+        return compoundGroup([head, op(';'), ' ', kw('do'), this.body(c.body, c.span.end), this.closer(c.body), kw('done')], !this.simpleBody(c.body))
+      }
+      case 'ArithFor':
+        return compoundGroup([this.arithForHead(c), op(';'), ' ', kw('do'), this.body(c.body, c.span.end), this.closer(c.body), kw('done')], !this.simpleBody(c.body))
+      case 'Case':
+        return this.caseDoc(c)
+      case 'ArithCommand':
+      case 'CondCommand':
+        return this.compoundText(c)
+    }
+  }
+
+  private groupable(body: Body): boolean {
+    if (this.opts.compounds === 'expanded') return false
+    return body.length > 0 && body.every((s) => {
+      const t = s.command.type
+      return t === 'SimpleCommand' || t === 'Pipeline' || t === 'AndOr'
+    }) && body.length <= 3
+  }
+
+  /**
+   * `if`/`while` conditions: statements joined by `; ` (a trailing comment
+   * breaks the line). `limit` is where the body starts: a comment after it
+   * belongs to the body or the whole compound, not to the condition.
+   */
+  private condList(stmts: Body, limit: number): Doc {
+    const parts: Doc[] = []
+    stmts.forEach((s, i) => {
+      const leading = this.take(s.span.start)
+      if (i > 0) parts.push(leading.length ? hard : [op(';'), ' '])
+      for (const cm of leading) parts.push(this.commentDoc(cm), hard)
+      parts.push(this.stmt(s))
+      const next = stmts[i + 1]
+      const t = this.trailing(s.span.end, next ? next.span.start : limit)
+      if (t) parts.push(this.trailingDoc(t))
+    })
+    return parts
+  }
+
+  private arithForHead(c: A.ArithFor): Doc {
+    const exprs = [c.init, c.cond, c.step].filter((e): e is A.ArithExpr => e !== null)
+    const from = exprs.length ? exprs[exprs.length - 1].span.end : c.span.start
+    const close = this.src.indexOf('))', from)
+    return this.verbatim({ start: c.span.start, end: close + 2 })
+  }
+
+  private caseDoc(c: A.Case): Doc {
+    const ind = this.opts.indent
+    const word = this.wordDoc(c.word)
+    const items: Doc[] = []
+    for (const item of c.items) {
+      const leading = this.take(item.span.start)
+      for (const cm of leading) items.push(hard, this.commentDoc(cm))
+      const pats = join(op('|'), item.patterns.map((p) => this.wordDoc(p)))
+      const term = op(item.terminator)
+      if (item.body.length === 0) {
+        items.push(hard, [pats, op(')'), ' ', term])
+        continue
+      }
+      const body = this.list(item.body, item.span.end, false)
+      items.push(hard, compoundGroup([pats, op(')'), indent([nl(' '), body, nl(' '), term], ind)], !this.simpleBody(item.body)))
+    }
+    const tail = this.take(c.span.end)
+    for (const cm of tail) items.push(hard, this.commentDoc(cm))
+    return group([kw('case'), ' ', word, ' ', kw('in'), indent(items, ind), hard, kw('esac')], true)
+  }
+}
+
+/**
+ * Arguments as fill parts: `['', cont, a, cont, b, …]`. Fill alternates
+ * content and separator; the empty first content lets the separator between
+ * the command name and its first argument break like the others.
+ */
+function fillParts(units: Doc[]): Doc[] {
+  const parts: Doc[] = ['']
+  for (const u of units) parts.push(cont, u)
+  return parts
+}