feat: add ImportDeclaration bindings and InjectImport mutation

[Emyrk]

Adds top-level import { ... } from "...", import type { ... }, and bare import "..." support so callers can prepend imports to the generated TypeScript output.

ts.ApplyMutations(
    config.InjectImport("zod", "z"),                       // import { z } from "zod"
    config.InjectTypeImport("./types", "Foo", "Bar=Renamed"), // import type { Bar as Renamed, Foo } from "./types"
    config.InjectSideEffectImport("./polyfill"),           // import "./polyfill"
)

Foundation for a follow-up that rewrites #82 as a guts mutation composable with ExportTypes, SimplifyOptional, etc.

Design notes, merge semantics, sort order, test list

File-by-file

• bindings/declarations.go: new ImportDeclaration (DeclarationType) and ImportSpecifier. Modeled forms: named, type-only, side-effect. Default and namespace imports are not yet supported; doc comments call this out.
• typescript-engine/src/index.ts: importSpecifier and importDeclaration wrappers around ts.factory.createImportSpecifier / createImportDeclaration / createImportClause / createNamedImports. When the named-imports array is undefined the wrapper drops the import clause so the printer emits the side-effect form natively. dist/main.js is rebuilt with pnpm run build.
• bindings/bindings.go: *ImportDeclaration dispatched through ToTypescriptDeclarationNode plus the goja-backed builders. Empty Alias emits just the name; a set Alias passes the original name as the TS propertyName so the printer emits Name as Alias.
• convert.go: imports []*bindings.ImportDeclaration field on Typescript, public AppendImport(decl) that merges by (Module, IsTypeOnly, SideEffect), and an emission block in SerializeInOrder that writes the imports above the alphabetically-sorted declarations.
• config/imports.go: the user-facing mutation API.

Merge semantics for AppendImport

Imports are keyed by (Module, IsTypeOnly, SideEffect):

• Same key merges. Specifiers are unioned by (Name, Alias, IsTypeOnly); duplicates dropped while preserving first-occurrence order.
• Mixed type-only + value for the same module split. This avoids silently flattening the type-only intent. InjectTypeImport("zod", "Foo") + InjectImport("zod", "bar") emits two lines, not import { Foo, bar } from "zod"; with Foo demoted.
• Side-effect imports dedupe per module.

Deterministic emission order

Serialize sorts before emitting so output is independent of mutation order:

• Imports: (Module asc, !SideEffect, IsTypeOnly asc). Same module groups together with side-effect first, then value, then type-only.
• Specifiers within an import: (Name, Alias, IsTypeOnly).

Mutation API details

"Name=Alias" shorthand in InjectImport / InjectTypeImport emits Name as Alias; bare names emit as-is. InjectSideEffectImport(module) takes no names.

Tests

• bindings/imports_test.go: goja round-trip for single, multiple, aliased, type-only, mixed, side-effect, side-effect-with-stray-IsTypeOnly.
• config/imports_internal_test.go: Name=Alias parser.
• imports_test.go (root), per-behavior subtests:
  • TestInjectImport_Merge — same-module dedup, specifiers sorted.
  • TestInjectImport_AliasAndType — alias shorthand + type form.
  • TestInjectImport_MixedTypeAndValueSplit — regression for the mixed-mode flatten bug.
  • TestInjectImport_SortedAcrossModules — alphabetical regardless of append order.
  • TestInjectSideEffectImport — bare emit, dedupe, side-effect-before-clausal placement.

go test ./... and go vet ./... pass (one pre-existing unreachable-code warning in convert.go predates this branch).

Follow-up

Stacked PR will replace the #82 string-builder serializer with a zod.AsSchemas mutation emitting VariableStatement + Alias pairs. That needs ImportDeclaration (this PR) plus new expression nodes for CallExpression, PropertyAccessExpression, ObjectLiteralExpression, ArrayLiteralExpression, ArrowFunction, and TypeQuery.

---

Generated by Coder Agents on behalf of @Emyrk.

[Emyrk]

/coder-agent-review