sh-ast 0.4.0 → 0.5.0

package/README.md

@@ -6,6 +6,11 @@ mutable records preserving upstream fields, defaults, nulls, numeric operators,
 byte strings, and token positions. First use initializes WebAssembly synchronously
 in Node.js; no initialization promise is required.
 
+Traversal uses ordinary TypeScript arrays with explicit mutation limits. The
+[accepted representation decision](../../design/WALK-MUTATION-DECISION.md) records
+which live edits are supported and why this interface does not model Go storage
+capacity, reslicing, or value-slot addresses.
+
 ```ts
 import { LangBash, nodeEnd, parseSync } from 'sh-ast';
 
@@ -58,15 +63,93 @@ Positions }`. `Positions.get(node)` reads immutable original bounds by node
   a value does not promise every upstream operation accepts it.
 - `SYNTAX_SCHEMA` and `SYNTAX_INTERFACES` are deeply frozen field/interface
   metadata. Their order is not upstream Walk order.
+- `walk(node, callback)` calls the callback synchronously on entry and with `null`
+  on exit. Return `false` on entry to prune that occurrence, including its exit;
+  exit boolean values do not control traversal. Every callback result must be a
+  boolean; Promises and other values throw `InputError`. Child reads happen live, and
+  nested calls keep independent state. Specialized statement/item comment loops
+  visit value copies; ordinary comment lists visit their stored objects. The
+  array reference and initial length are captured when each list starts. Future
+  existing slots are read live; indices added beyond the captured extent are
+  ignored by that active traversal. Replacing the owner's array field does not retarget an active list.
+  See the mutation limits below.
+- `printSync(node, options?)` reconstructs the current edited tree and collects a
+  fresh upstream printer's output as `GoString`. Supported roots are File, Stmt,
+  Word, Assign, Command and WordPart alternatives. Only File gets a guaranteed
+  final newline. Printing applies upstream formatting; it does not replay the
+  original source or promise source-byte identity.
+- `PrintOptions` exposes `Indent`, `BinaryNextLine`, `SwitchCaseIndent`,
+  `SpaceRedirects`, `KeepPadding`, `Minify`, `SingleLine`, and `FunctionNextLine`.
+  Indent accepts an exact uint64 as a safe number or bigint, with zero selecting
+  tabs. Boolean defaults are false. KeepPadding is upstream's best-effort,
+  deprecated option; Minify and SingleLine together return an upstream error.
 
 `ParseError` and `LangError` preserve upstream fields, exact `Message` bytes, and
 any partial `File`. Their ordinary `Error.message` is a display string.
 `InputError` reports invalid binding inputs, upstream option constraints, or
 unsupported constructed nodes whose requested bound panics upstream.
 `ShInternalError` reports transport failures or unexpected upstream panics.
+`PrintError` retains ordinary upstream printer failures, and `PrintPanicError`
+retains panics from printing representable inputs. `WalkPanicError` represents
+upstream-equivalent traversal panics; callback exceptions retain their identity.
 All extend `ShAstError`. The conservative structural-depth guard throws
 `ShParseMaxDepthError` before potentially exhausting the WASM stack. It is a
 binding resource constraint and can reject deeply nested quoted or commented text.
+Printing collects complete output; large trees or indentation widths can consume
+substantial memory and time. The parse guard does not bound arbitrary constructed
+printing inputs. No arbitrary writer, partial-output, or reusable-printer protocol
+is exposed.
+
+## Traversal mutation limits
+
+Supported edits preserve a node's kind and shape: change syntax fields, replace
+pointer children before their read, replace future existing list slots, append
+beyond an active list's captured extent, or assign a new array to the owner field.
+Changes before a list starts are included in its captured reference and length.
+Pruning and synchronous nested walks retain their control behavior; nested walks
+see the tree at their own entry, while edits to shared objects remain live.
+
+Keep every index in an active list's captured extent present. Removing one,
+leaving a hole there, or shrinking below that extent is outside the supported
+contract, including through aliases. Truncation, `delete`, `pop`, `shift`, or a
+length-reducing `splice` can do this; removing appended indices beyond the captured
+extent does not affect the active list. No mutation detector or specific
+error/result is promised for those edits. Assign a new owner array
+instead; the active list keeps its original array and later walks see the new one.
+Length-preserving replacement or reordering, including `sort` and `reverse`,
+follows live slot reads and may revisit an object moved into a later slot. Walk
+does not promise to visit each object only once. An appended object moved into an
+original future slot is visited through that slot.
+
+Stored Comment callbacks receive JavaScript objects. Replacing a Comment slot
+leaves a retained callback object unchanged; it does not behave as a pointer to a
+Go value slot. Specialized Stmt/CaseItem/ArrayElem comment callbacks receive
+copies, so editing those callback values does not edit the original comments.
+Ordinary JavaScript aliases remain live; this interface does not clone shared
+arrays or objects. It does not model Go slice capacity, distinct slice headers
+sharing backing stores, or reslicing. These limits preclude unrestricted Go
+storage mutation parity while preserving live field edits and upstream traversal control.
+
+## Editing and printing
+
+```ts
+import { parseSync, printSync, walk } from 'sh-ast';
+
+const file = parseSync("printf '%s\\n' 'old 🎉'\n", { KeepComments: true });
+walk(file, (node) => {
+  if (node?.Type === 'SglQuoted' && node.Value === 'old 🎉') {
+    node.Value = 'new 🎉';
+  }
+  return true;
+});
+const output = printSync(file);
+```
+
+This edits a field without replacing array storage. Node positions still describe
+their upstream token values; live `nodePos` and `nodeEnd` compute from current
+fields, while a separately captured parse snapshot remains tied to original
+source. Consumers such as ESLint can edit a separate tree and use printed output
+as a fix without mutating their original lint view or traversal cache.
 
 `sh-ast/analyze` remains a separate syntactic interpretation layer. Its word,
 command, and wrapper analysis consumes the faithful records; it does not define
@@ -77,11 +160,12 @@ parser behavior or the core tree representation.
 Fields now use upstream spelling (`Type`, `Stmts`, `Cmd`, `Value`) and explicit
 null/default values. Replace dialect strings with numeric `Variant` constants,
 request comments explicitly, and handle structured errors and byte positions.
-The root no longer exports normalized `ShNode`/`ShNodes`, `range`/`loc`, `walk`, or
-`visitorKeys`. Consumers such as ESLint own their source-coordinate and traversal
-views. Whole-file parsing is the present scope; public upstream traversal and
-printing belong to the following minor release. Stateful/incremental parser
-protocols and full syntax-package parity are deferred.
+The root no longer exports normalized `ShNode`/`ShNodes`, `range`/`loc`, or
+`visitorKeys`. The new walker uses entry/null-exit callbacks rather than the former
+structural helper's protocol. Consumers such as ESLint own their source-coordinate
+and traversal views. Whole-file parsing, collected printing and the live walker
+with the mutation limits above form this candidate's scope. Stateful/incremental parser protocols
+and full syntax-package parity are deferred.
 
 The [design collection](../../design/ARCHITECTURE.md) and
 [implementation evidence](../../design/IMPLEMENTATION.md) describe the release

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { InputError, LangError, ParseError, newPos, nodeEnd, nodePos, parseSync, parseWithPositionsSync, rawOperator, } from './syntax.js';
 export type { ParseOptions, ParsedFile, PositionSnapshot, NodePositions } from './syntax.js';
+export { printSync } from './syntax-print.js';
+export type { PrintOptions } from './syntax-print.js';
+export { PrintError, PrintPanicError } from './syntax-print-errors.js';
+export { walk, WalkPanicError } from './syntax-walk.js';
 export type * from '../generated/syntax-types.js';
 export * from '../generated/syntax-constants.js';
 export type { SyntaxFieldSchema, SyntaxRecordSchema } from '../generated/syntax-schema.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,OAAO,EACP,OAAO,EACP,SAAS,EACT,sBAAsB,EACtB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7F,mBAAmB,8BAA8B,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC3F,OAAO,EACL,gCAAgC,EAChC,sBAAsB,EACtB,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,eAAO,MAAM,aAAa,gGAAqB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uDAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,OAAO,EACP,OAAO,EACP,SAAS,EACT,sBAAsB,EACtB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxD,mBAAmB,8BAA8B,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC3F,OAAO,EACL,gCAAgC,EAChC,sBAAsB,EACtB,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,eAAO,MAAM,aAAa,gGAAqB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uDAAyB,CAAC"}

package/dist/index.js

@@ -1,11 +1,14 @@
 /**
  * A faithful synchronous interface to mvdan/sh syntax. The root exposes upstream
- * records, constants, parser controls and position operations. Consumer-specific
+ * records, constants, parser controls, traversal, printing and position operations. Consumer-specific
  * source views and semantic analysis are separate responsibilities.
  */
 import { SYNTAX_INTERFACES as interfaces, SYNTAX_SCHEMA as schema, } from '../generated/syntax-schema.js';
 import { deepFreeze } from './deep-freeze.js';
 export { InputError, LangError, ParseError, newPos, nodeEnd, nodePos, parseSync, parseWithPositionsSync, rawOperator, } from './syntax.js';
+export { printSync } from './syntax-print.js';
+export { PrintError, PrintPanicError } from './syntax-print-errors.js';
+export { walk, WalkPanicError } from './syntax-walk.js';
 export * from '../generated/syntax-constants.js';
 export { ShAnalyzeInvalidWrapperSpecError, ShAnalyzeMaxDepthError, ShAstError, ShInternalError, ShParseMaxDepthError, } from './errors.js';
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,IAAI,UAAU,EAC/B,aAAa,IAAI,MAAM,GACxB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,OAAO,EACP,OAAO,EACP,SAAS,EACT,sBAAsB,EACtB,WAAW,GACZ,MAAM,aAAa,CAAC;AAGrB,cAAc,kCAAkC,CAAC;AAEjD,OAAO,EACL,gCAAgC,EAChC,sBAAsB,EACtB,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,IAAI,UAAU,EAC/B,aAAa,IAAI,MAAM,GACxB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,OAAO,EACP,OAAO,EACP,SAAS,EACT,sBAAsB,EACtB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAExD,cAAc,kCAAkC,CAAC;AAEjD,OAAO,EACL,gCAAgC,EAChC,sBAAsB,EACtB,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC"}

package/dist/sh-ast.d.ts

@@ -2338,6 +2338,79 @@ export declare const Pow: 44;
  */
 export declare const PowAssgn: 62;
 
+/**
+ * An error returned by upstream Printer.Print, such as an unsupported root or
+ * incompatible formatting options. No partial writer output is exposed.
+ * @public
+ */
+export declare class PrintError extends ShAstError {
+    /** Stable identity for an ordinary error returned by upstream Print. @public */
+    readonly code = "SH_AST_SYNTAX_PRINT";
+    /** Exact upstream error bytes; Error.message is only a display rendering. @public */
+    readonly Message: GoString;
+    /** Retains the upstream error without interpreting its human-readable text. @public */
+    constructor(message: GoString);
+}
+
+/**
+ * Upstream NewPrinter controls applied to a fresh printer for each call. All
+ * flags default to false; zero indentation selects tabs. The pinned WASM uint
+ * domain is 64-bit, so Indent accepts bigint beyond JavaScript's safe integers.
+ * @public
+ */
+export declare interface PrintOptions {
+    /** Spaces per level, or zero for tabs. Large values can request expensive output. */
+    Indent?: number | bigint;
+    /** Places multiline binary operators on the next line with a backslash continuation. */
+    BinaryNextLine?: boolean;
+    /** Indents case alternatives, placing their bodies two levels below the case clause. */
+    SwitchCaseIndent?: boolean;
+    /** Adds space after redirection operators except `>&`, `<&`, `>(` and `<(`. */
+    SpaceRedirects?: boolean;
+    /**
+     * Preserves token columns on a best-effort basis.
+     * @deprecated Upstream marks this option as flawed and plans removal in v4.
+     */
+    KeepPadding?: boolean;
+    /** Omits comments, indentation and optional whitespace. Incompatible with SingleLine. */
+    Minify?: boolean;
+    /** Reduces newlines except where comments, heredocs or File output require them. */
+    SingleLine?: boolean;
+    /** Places a function's opening brace on the next line. */
+    FunctionNextLine?: boolean;
+}
+
+/**
+ * Upstream Printer.Print panicked for a representable tree or option value.
+ * Partial and typed-nil trees can trigger this independently of root support.
+ * Catching the panic preserves reuse of the binding's shared runtime.
+ * @public
+ */
+export declare class PrintPanicError extends ShAstError {
+    /** Stable identity for an upstream panic caught at the Print operation. @public */
+    readonly code = "SH_AST_SYNTAX_PRINT_PANIC";
+    /** Exact panic rendering from Go; Error.message is only a display rendering. @public */
+    readonly Message: GoString;
+    /** Retains the panic message separately from ordinary returned Print errors. @public */
+    constructor(message: GoString);
+}
+
+/**
+ * Formats the current tree with a fresh upstream printer and collects all output.
+ * Supported roots are File, Stmt, Word, Assign, Command and WordPart; other Nodes
+ * produce PrintError. Only File output has upstream's trailing-newline behavior.
+ * Invalid UTF-8 output remains bytes. Upstream formatting can itself consume
+ * input bytes, including its tabwriter escape byte, so this is not source replay.
+ *
+ * InputError identifies unrepresentable input; PrintError is an ordinary returned
+ * upstream error; PrintPanicError retains an upstream operation panic. No partial
+ * output or arbitrary writer lifecycle is exposed. Full tree reconstruction and
+ * collected output require memory proportional to the values involved; extreme
+ * indentation or tree size is not made resource-safe by panic adaptation.
+ * @public
+ */
+export declare function printSync(node: Node_2, options?: PrintOptions): GoString;
+
 /**
  * The upstream ProcOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
  *
@@ -3695,6 +3768,53 @@ export declare const UpperAll: 97;
  */
 export declare const UpperFirst: 96;
 
+/**
+ * Walks synchronously using the pinned upstream case ordering. Each accepted entry is followed by its
+ * children and a null exit. Returning false prunes the entry without an exit;
+ * boolean exit return values are ignored. Every callback must return a boolean
+ * synchronously; other results produce InputError. Callback exceptions retain their identity,
+ * and upstream deferred comment callbacks still run during exception unwinding.
+ *
+ * Children and later fields are read live. Each list captures its array reference
+ * and length when traversal reaches that list, then reads existing later slots
+ * when reached. Replacing or reordering later slots is observed and can cause
+ * a node to be skipped or revisited. Indices added beyond the captured extent
+ * are not visited by that active list. Replacing the owner's array field does not
+ * redirect an active list, but a later walk or print sees the current field.
+ * Changes made before a list is reached are observed when it starts.
+ *
+ * Supported edits preserve each node's Type (and TypedNil.Kind), required field
+ * shapes and every index within each active list's captured extent. Leaving
+ * holes or shrinking an array below that extent (for example through truncation,
+ * deletion, or length-reducing splice/shift) is outside the mutation contract.
+ * These are not runtime validation rules. Ordinary JavaScript object and array
+ * aliases remain shared; the binding does not model distinct Go slice headers or
+ * capacity-dependent allocation over shared backing storage.
+ *
+ * Comments on Stmt, CaseItem and ArrayElem are copied before their callbacks,
+ * including position and byte-string values; editing a copy does not edit the
+ * stored comment. Last/CondLast/ThenLast/DoLast callbacks receive the stored
+ * JavaScript Comment object. Replacing its array slot leaves any previously
+ * retained callback object unchanged: there is no Go value-slot pointer identity.
+ * Reentrant walks maintain independent traversal state.
+ * @public
+ */
+export declare function walk(node: Node_2, callback: (node: Node_2 | null) => boolean): void;
+
+/**
+ * A panic raised by upstream-equivalent traversal, such as a nil dereference or
+ * unsupported concrete node. Exceptions thrown by callbacks are never wrapped.
+ * @public
+ */
+export declare class WalkPanicError extends ShAstError {
+    /** Stable discriminator for traversal panics. @public */
+    readonly code = "SH_AST_WALK_PANIC";
+    /** Exact upstream panic bytes; Error.message is only a display rendering. @public */
+    readonly Message: GoString;
+    /** Retains the upstream panic text separately from its display rendering. @public */
+    constructor(message: GoString);
+}
+
 /**
  * WhileClause represents a while or an until clause.
  *

package/dist/syntax-print-errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Printing has two upstream failure modes: returned errors and panics raised by
+ * the operation. Both retain exact message bytes; neither is a parser failure
+ * or a claim that the transport itself malfunctioned.
+ */
+import type { GoString } from '../generated/syntax-types.js';
+import { ShAstError } from './errors.js';
+/**
+ * An error returned by upstream Printer.Print, such as an unsupported root or
+ * incompatible formatting options. No partial writer output is exposed.
+ * @public
+ */
+export declare class PrintError extends ShAstError {
+    /** Stable identity for an ordinary error returned by upstream Print. @public */
+    readonly code = "SH_AST_SYNTAX_PRINT";
+    /** Exact upstream error bytes; Error.message is only a display rendering. @public */
+    readonly Message: GoString;
+    /** Retains the upstream error without interpreting its human-readable text. @public */
+    constructor(message: GoString);
+}
+/**
+ * Upstream Printer.Print panicked for a representable tree or option value.
+ * Partial and typed-nil trees can trigger this independently of root support.
+ * Catching the panic preserves reuse of the binding's shared runtime.
+ * @public
+ */
+export declare class PrintPanicError extends ShAstError {
+    /** Stable identity for an upstream panic caught at the Print operation. @public */
+    readonly code = "SH_AST_SYNTAX_PRINT_PANIC";
+    /** Exact panic rendering from Go; Error.message is only a display rendering. @public */
+    readonly Message: GoString;
+    /** Retains the panic message separately from ordinary returned Print errors. @public */
+    constructor(message: GoString);
+}
+//# sourceMappingURL=syntax-print-errors.d.ts.map

package/dist/syntax-print-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-print-errors.d.ts","sourceRoot":"","sources":["../src/syntax-print-errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,UAAU;IACxC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,yBAAyB;IAEtC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAE3B,uFAAuF;gBAC3E,OAAO,EAAE,QAAQ;CAK9B;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,mFAAmF;IACnF,QAAQ,CAAC,IAAI,+BAA+B;IAE5C,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAE3B,wFAAwF;gBAC5E,OAAO,EAAE,QAAQ;CAK9B"}

package/dist/syntax-print-errors.js

@@ -0,0 +1,37 @@
+import { ShAstError } from './errors.js';
+/**
+ * An error returned by upstream Printer.Print, such as an unsupported root or
+ * incompatible formatting options. No partial writer output is exposed.
+ * @public
+ */
+export class PrintError extends ShAstError {
+    /** Stable identity for an ordinary error returned by upstream Print. @public */
+    code = 'SH_AST_SYNTAX_PRINT';
+    /** Exact upstream error bytes; Error.message is only a display rendering. @public */
+    Message;
+    /** Retains the upstream error without interpreting its human-readable text. @public */
+    constructor(message) {
+        super(typeof message === 'string' ? message : new TextDecoder().decode(message));
+        this.Message = message;
+        this.name = 'PrintError';
+    }
+}
+/**
+ * Upstream Printer.Print panicked for a representable tree or option value.
+ * Partial and typed-nil trees can trigger this independently of root support.
+ * Catching the panic preserves reuse of the binding's shared runtime.
+ * @public
+ */
+export class PrintPanicError extends ShAstError {
+    /** Stable identity for an upstream panic caught at the Print operation. @public */
+    code = 'SH_AST_SYNTAX_PRINT_PANIC';
+    /** Exact panic rendering from Go; Error.message is only a display rendering. @public */
+    Message;
+    /** Retains the panic message separately from ordinary returned Print errors. @public */
+    constructor(message) {
+        super(typeof message === 'string' ? message : new TextDecoder().decode(message));
+        this.Message = message;
+        this.name = 'PrintPanicError';
+    }
+}
+//# sourceMappingURL=syntax-print-errors.js.map

package/dist/syntax-print-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-print-errors.js","sourceRoot":"","sources":["../src/syntax-print-errors.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxC,gFAAgF;IACvE,IAAI,GAAG,qBAAqB,CAAC;IAEtC,qFAAqF;IAC5E,OAAO,CAAW;IAE3B,uFAAuF;IACvF,YAAY,OAAiB;QAC3B,KAAK,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QACjF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,UAAU;IAC7C,mFAAmF;IAC1E,IAAI,GAAG,2BAA2B,CAAC;IAE5C,wFAAwF;IAC/E,OAAO,CAAW;IAE3B,wFAAwF;IACxF,YAAY,OAAiB;QAC3B,KAAK,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QACjF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/dist/syntax-print.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Collected-output access to upstream Printer.Print. The reverse codec rebuilds
+ * the current faithful tree, and Go owns formatting decisions. This module has
+ * no source cache, parser round trip, writer callbacks, or reusable printer state.
+ */
+import type { GoString, Node } from '../generated/syntax-types.js';
+/**
+ * Upstream NewPrinter controls applied to a fresh printer for each call. All
+ * flags default to false; zero indentation selects tabs. The pinned WASM uint
+ * domain is 64-bit, so Indent accepts bigint beyond JavaScript's safe integers.
+ * @public
+ */
+export interface PrintOptions {
+    /** Spaces per level, or zero for tabs. Large values can request expensive output. */
+    Indent?: number | bigint;
+    /** Places multiline binary operators on the next line with a backslash continuation. */
+    BinaryNextLine?: boolean;
+    /** Indents case alternatives, placing their bodies two levels below the case clause. */
+    SwitchCaseIndent?: boolean;
+    /** Adds space after redirection operators except `>&`, `<&`, `>(` and `<(`. */
+    SpaceRedirects?: boolean;
+    /**
+     * Preserves token columns on a best-effort basis.
+     * @deprecated Upstream marks this option as flawed and plans removal in v4.
+     */
+    KeepPadding?: boolean;
+    /** Omits comments, indentation and optional whitespace. Incompatible with SingleLine. */
+    Minify?: boolean;
+    /** Reduces newlines except where comments, heredocs or File output require them. */
+    SingleLine?: boolean;
+    /** Places a function's opening brace on the next line. */
+    FunctionNextLine?: boolean;
+}
+/**
+ * Formats the current tree with a fresh upstream printer and collects all output.
+ * Supported roots are File, Stmt, Word, Assign, Command and WordPart; other Nodes
+ * produce PrintError. Only File output has upstream's trailing-newline behavior.
+ * Invalid UTF-8 output remains bytes. Upstream formatting can itself consume
+ * input bytes, including its tabwriter escape byte, so this is not source replay.
+ *
+ * InputError identifies unrepresentable input; PrintError is an ordinary returned
+ * upstream error; PrintPanicError retains an upstream operation panic. No partial
+ * output or arbitrary writer lifecycle is exposed. Full tree reconstruction and
+ * collected output require memory proportional to the values involved; extreme
+ * indentation or tree size is not made resource-safe by panic adaptation.
+ * @public
+ */
+export declare function printSync(node: Node, options?: PrintOptions): GoString;
+//# sourceMappingURL=syntax-print.d.ts.map

package/dist/syntax-print.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-print.d.ts","sourceRoot":"","sources":["../src/syntax-print.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAOnE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,wFAAwF;IACxF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oFAAoF;IACpF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,YAAiB,GAAG,QAAQ,CAoC1E"}

package/dist/syntax-print.js

@@ -0,0 +1,86 @@
+import { ShInternalError } from './errors.js';
+import { InputError } from './syntax-errors.js';
+import { PrintError, PrintPanicError } from './syntax-print-errors.js';
+import { decodeWire, encodeWire, isGoString, isRecord, isSyntaxNode } from './syntax-wire.js';
+import { callSyntax } from './wasm-instance.js';
+/**
+ * Formats the current tree with a fresh upstream printer and collects all output.
+ * Supported roots are File, Stmt, Word, Assign, Command and WordPart; other Nodes
+ * produce PrintError. Only File output has upstream's trailing-newline behavior.
+ * Invalid UTF-8 output remains bytes. Upstream formatting can itself consume
+ * input bytes, including its tabwriter escape byte, so this is not source replay.
+ *
+ * InputError identifies unrepresentable input; PrintError is an ordinary returned
+ * upstream error; PrintPanicError retains an upstream operation panic. No partial
+ * output or arbitrary writer lifecycle is exposed. Full tree reconstruction and
+ * collected output require memory proportional to the values involved; extreme
+ * indentation or tree size is not made resource-safe by panic adaptation.
+ * @public
+ */
+export function printSync(node, options = {}) {
+    validatePrintOptions(options);
+    if (!isSyntaxNode(node)) {
+        throw new InputError('Expected a complete, acyclic upstream Node record');
+    }
+    const payload = new TextEncoder().encode(encodeWire(node));
+    const result = decodeWire(callSyntax('print', payload, encodeWire(options)));
+    if (!isRecord(result)) {
+        throw new ShInternalError('The syntax printer returned a non-record response');
+    }
+    if (result.Error !== undefined) {
+        const error = result.Error;
+        if (!isRecord(error) || !isGoString(error.Message)) {
+            throw new ShInternalError('The syntax printer returned a malformed error');
+        }
+        switch (error.Kind) {
+            case 'PrintError':
+                throw new PrintError(error.Message);
+            case 'PrintPanicError':
+                throw new PrintPanicError(error.Message);
+            case 'InputError':
+                throw new InputError(error.Message);
+            case 'InternalError':
+                throw new ShInternalError(typeof error.Message === 'string'
+                    ? error.Message
+                    : new TextDecoder().decode(error.Message));
+            default:
+                throw new ShInternalError('The syntax printer returned an unknown error kind');
+        }
+    }
+    if (!isGoString(result.Output)) {
+        throw new ShInternalError('The syntax printer returned an invalid output value');
+    }
+    return result.Output;
+}
+/** Validates exact option domains without imposing a formatting or indentation policy. */
+function validatePrintOptions(options) {
+    if (!isRecord(options)) {
+        throw new InputError('Printer options must be a data record');
+    }
+    const flags = new Set([
+        'BinaryNextLine',
+        'SwitchCaseIndent',
+        'SpaceRedirects',
+        'KeepPadding',
+        'Minify',
+        'SingleLine',
+        'FunctionNextLine',
+    ]);
+    for (const [name, value] of Object.entries(options)) {
+        if (name === 'Indent') {
+            const valid = typeof value === 'bigint'
+                ? value >= 0n && value <= 0xffffffffffffffffn
+                : typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+            if (!valid) {
+                throw new InputError('Indent must be a safe nonnegative integer or uint64 bigint');
+            }
+        }
+        else if (!flags.has(name)) {
+            throw new InputError(`Unknown printer option: ${name}`);
+        }
+        else if (typeof value !== 'boolean') {
+            throw new InputError(`${name} must be boolean`);
+        }
+    }
+}
+//# sourceMappingURL=syntax-print.js.map

package/dist/syntax-print.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-print.js","sourceRoot":"","sources":["../src/syntax-print.ts"],"names":[],"mappings":"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"}

package/dist/syntax-walk-bounds.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Private live boundary evaluation for Walk's comment placement. These methods
+ * mirror the pinned mvdan/sh node methods so callback edits are visible without
+ * repeatedly serializing subtrees to WASM. They are not public position APIs.
+ *
+ * Adapted from mvdan.cc/sh/v3 v3.13.1 syntax/nodes.go, copyright Daniel Martí.
+ * The upstream BSD license is retained in syntax-walk-license.ts.
+ */
+import type { Node, SyntaxPos } from '../generated/syntax-types.js';
+/** Stmt comments at or after the live end become the single deferred comment. @internal */
+export declare function atStatementEnd(node: Extract<Node, {
+    Type: 'Stmt';
+}>, hash: SyntaxPos): boolean;
+/** Case/array comments strictly after the live start become deferred. @internal */
+export declare function afterItemStart(node: Extract<Node, {
+    Type: 'CaseItem' | 'ArrayElem';
+}>, hash: SyntaxPos): boolean;
+//# sourceMappingURL=syntax-walk-bounds.d.ts.map

package/dist/syntax-walk-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-walk-bounds.d.ts","sourceRoot":"","sources":["../src/syntax-walk-bounds.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AA6LpE,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAE9F;AACD,mFAAmF;AACnF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,CAAC,EACvD,IAAI,EAAE,SAAS,GACd,OAAO,CAET"}