espolar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piovium Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# espolar
+
+ESTree-compatible AST printer designed for JavaScript/TypeScript language tooling.
+
+## Features
+
+- **Source preservation** — untouched nodes (configurable) are printed verbatim from the original source, preserving whitespace, comments, formatting, and ASI safety.
+- **Volar.js mappings** — generates `Mapping<Data>[]` mapping source ranges to generated ranges, with automatic merging of adjacent mappings.
+- **Full TypeScript support** — handles all `@typescript-eslint/types` AST node types (TSESTree), compatible with acorn-typescript parsed ASTs.
+- **Extensible** — every aspect is customizable: untouched detection, mapping data, comments injection, printer overrides per node type.
+- **Zero runtime dependencies** — keeps the library minimal, only 10 kB gzipped.
+
+## Install
+
+```bash
+pnpm add espolar
+```
+
+Requires Node.js >= 26.
+
+## Usage
+
+```ts
+import { print } from "espolar";
+import type { PrintOptions } from "espolar";
+
+const ast = /* parse to AST.Program with loc/range */;
+
+const result = print(ast, {
+  source: originalCode,
+});
+
+console.log(result.code);      // generated source string
+console.log(result.mappings);  // Volar.js Mapping<{}>[]
+```
+
+### Custom printer
+
+```ts
+import { print } from "espolar";
+
+const result = print(ast, {
+  source,
+  printers: {
+    Literal(node, ctx) {
+      ctx.write(`"overridden"`);
+    },
+  },
+});
+```
+
+### Custom mapping data
+
+```ts
+import { print } from "espolar";
+
+const result = print(ast, {
+  source,
+  getMappingData: (node) => (node ? [node.type] : []),
+  combineMappingData: (left, right) => {
+    return [...left, ...right];
+  },
+});
+```
+
+## API
+
+### `print(node, options)`
+
+Main entry point. Returns `PrintResult<Data>`.
+
+#### `PrintOptions<Data>`
+
+| Option                | Type                               | Description                                                                                |
+| --------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------ |
+| `source`              | `string`                           | The original source code (required)                                                        |
+| `isUntouched`         | `(node) => boolean \| SourceRange` | Determine if a node should be preserved from source. Default: checks `range`/`start`/`end` |
+| `getMappingData`      | `(node?) => Data`                  | Extract data for each mapping entry. Default: `() => ({})`                                 |
+| `combineMappingData`  | `(left, right) => Data`            | Merge data when adjacent mappings are combined. Default: returns `right`                   |
+| `printers`            | `Printers<Data>`                   | Override printers for specific `AST_NODE_TYPES`                                            |
+| `getLeadingComments`  | `(node) => Comment[] \| undefined` | Return comments to print before a touched node                                             |
+| `getTrailingComments` | `(node) => Comment[] \| undefined` | Return comments to print after a touched node                                              |
+
+#### `PrintResult<Data>`
+
+| Field      | Type              | Description                               |
+| ---------- | ----------------- | ----------------------------------------- |
+| `code`     | `string`          | The generated source code                 |
+| `mappings` | `Mapping<Data>[]` | Volar.js source mappings (range-to-range) |
+
+### `PrinterContext<Data>`
+
+The context object passed to each printer function.
+
+| Method/Property                                         | Description                                     |
+| ------------------------------------------------------- | ----------------------------------------------- |
+| `readonly source: string`                               | The original source string                      |
+| `readonly generatedOffset: number`                      | Current output position                         |
+| `write(text: string)`                                   | Emit text to the output                         |
+| `writeNode(node)`                                       | Dispatch to a printer (preserving if untouched) |
+| `writeNodeList(nodes, separator)`                       | Print a list with explicit separator            |
+| `writeNodeListWithSourceGaps(nodes, fallbackSeparator)` | Print a list, copying source gaps between nodes |
+| `writePreservedNode(node)`                              | Force-preserve a node from source               |
+| `writeSource(start, end, data)`                         | Copy source range and add mapping               |
+| `getLeadingComments(node)`                              | Query leading comments                          |
+| `getTrailingComments(node)`                             | Query trailing comments                         |
+
+### Exported helpers
+
+| Export                      | Description                          |
+| --------------------------- | ------------------------------------ |
+| `defaultIsUntouched`        | Default untouched detection function |
+| `defaultGetMappingData`     | Default mapping data extractor       |
+| `defaultCombineMappingData` | Default mapping data combiner        |
+
+## Architecture
+
+The printer works in a single pass:
+
+1. If a node is **untouched** (has source range and `isUntouched` returns truthy), its original source text is copied verbatim with a 1:1 mapping.
+2. Otherwise, the node is dispatched to its registered **printer function**, which recursively calls `writeNode` on children.
+3. Adjacent untouched siblings have their mappings **merged** into a single combined range.
+
+This design preserves original formatting for unmodified code while only reconstructing the parts that changed.
+
+## Development
+
+```bash
+pnpm install        # Install dependencies
+pnpm test           # Run tests (vitest)
+pnpm coverage       # Run tests with V8 coverage
+pnpm typecheck      # TypeScript type checking
+pnpm build          # Build via tsdown
+```
+
+Tests use `acorn` + `@sveltejs/acorn-typescript` to parse TypeScript source into AST inputs.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { Mapping } from "@volar/source-map";
+import { AST_NODE_TYPES, TSESTree as AST } from "@typescript-eslint/types";
+
+//#region src/types.d.ts
+declare module "@typescript-eslint/types" {
+  namespace TSESTree {
+    interface NodeOrTokenData {
+      start?: number;
+      end?: number;
+    }
+    interface BabelTSFunctionSignatureBase {
+      typeAnnotation?: TSTypeAnnotation;
+      parameters?: Parameter[];
+    }
+    interface TSFunctionType extends BabelTSFunctionSignatureBase {}
+    interface TSConstructorType extends BabelTSFunctionSignatureBase {}
+    interface TSCallSignatureDeclaration extends BabelTSFunctionSignatureBase {}
+    interface TSConstructSignatureDeclaration extends BabelTSFunctionSignatureBase {}
+    interface TSIndexSignature extends BabelTSFunctionSignatureBase {}
+    interface TSMethodSignatureComputedName extends BabelTSFunctionSignatureBase {}
+    interface TSMethodSignatureNonComputedName extends BabelTSFunctionSignatureBase {}
+    interface BabelTSAbstractBase {
+      abstract?: boolean;
+      accessor?: boolean;
+    }
+    interface MethodDefinitionComputedName extends BabelTSAbstractBase {}
+    interface MethodDefinitionNonComputedName extends BabelTSAbstractBase {}
+    interface PropertyDefinitionComputedName extends BabelTSAbstractBase {}
+    interface PropertyDefinitionNonComputedName extends BabelTSAbstractBase {}
+    interface BabelClassBase {
+      superTypeParameters?: TSTypeParameterInstantiation;
+    }
+    interface ClassDeclarationWithName extends BabelClassBase {}
+    interface ClassDeclarationWithOptionalName extends BabelClassBase {}
+    interface ClassExpression extends BabelClassBase {}
+  }
+}
+interface NodeLike {
+  type: string;
+  loc?: AST.SourceLocation | null;
+  start?: number;
+  end?: number;
+  range?: [number, number];
+}
+interface Comment {
+  type: "Line" | "Block";
+  value: string;
+  loc?: AST.SourceLocation;
+  start?: number;
+  end?: number;
+  range?: [number, number];
+}
+//#endregion
+//#region src/mappings.d.ts
+interface SourceRange {
+  start: number;
+  end: number;
+}
+//#endregion
+//#region src/api.d.ts
+interface PrintResult<Data> {
+  code: string;
+  mappings: Mapping<Data>[];
+}
+interface PrintOptions<Data> {
+  source: string;
+  isUntouched?: (node: AST.Node) => boolean | SourceRange;
+  getMappingData?: (node?: AST.Node | null) => Data;
+  combineMappingData?: (left: Data, right: Data) => Data;
+  printers?: Printers<Data>;
+  getLeadingComments?: (node: AST.Node) => Comment[] | undefined;
+  getTrailingComments?: (node: AST.Node) => Comment[] | undefined;
+}
+interface PrinterContext<Data> {
+  readonly source: string;
+  readonly generatedOffset: number;
+  write(text: string): void;
+  writeNode(node: AST.Node | null | undefined): void;
+  writeNodeList(nodes: readonly (AST.Node | null | undefined)[], separator: string): void;
+  writeNodeListWithSourceGaps(nodes: readonly (AST.Node | null | undefined)[], fallbackSeparator: string): void;
+  writePreservedNode(node: AST.Node): void;
+  writeSource(start: number, end: number, data: Data): void;
+  getLeadingComments: (node: AST.Node) => Comment[] | undefined;
+  getTrailingComments: (node: AST.Node) => Comment[] | undefined;
+}
+type NodePrinter<Key extends AST_NODE_TYPES, Data> = (node: Extract<AST.Node, {
+  type: Key;
+}>, context: PrinterContext<Data>) => void;
+type Printers<Data> = { [K in AST_NODE_TYPES]?: NodePrinter<K, Data> };
+//#endregion
+//#region src/printer.d.ts
+declare function print<Data>(node: AST.Node, options: PrintOptions<Data>): PrintResult<Data>;
+declare function print<Data>(node: import("estree").Node, options: PrintOptions<Data>): PrintResult<Data>;
+declare function print<Data>(node: NodeLike, options: PrintOptions<Data>): PrintResult<Data>;
+declare function defaultIsUntouched(node: AST.Node): boolean | SourceRange;
+declare function defaultGetMappingData(node?: AST.Node | null): unknown;
+declare function defaultCombineMappingData(left: unknown, right: unknown): unknown;
+//#endregion
+export { type AST, type Comment, type NodeLike, type NodePrinter, type PrintOptions, type PrintResult, type PrinterContext, defaultCombineMappingData, defaultGetMappingData, defaultIsUntouched, print };