@starpak/lang 0.1.2 → 0.1.3

package/src/emit/ts.ts

@@ -11,6 +11,10 @@
  * - Spak's Lua-flavoured method calls (`list:sort`, `s:split`, ...) lower to
  *   calls on that shim; unknown methods keep normal JS method syntax.
  * - Slices are 1-based and inclusive: `list[1..n]` -> `list.slice(0, n)`.
+ * - `fs` named imports stay async when the binding is awaited, so
+ *   `import { readFile } from "fs"` + `await readFile(...)` works. Imports that
+ *   are never awaited keep the historical synchronous binding (hello.spk
+ *   compatibility); `import { readFileSync }` is always explicit.
  */
 
 import type {
@@ -27,6 +31,7 @@ import type {
   FunctionExpr,
   Ident,
   ImportDecl,
+  ImportForm,
   Index,
   MatchStmt,
   Param,
@@ -41,6 +46,7 @@ import type {
   TypeAnn,
   VarDecl,
 } from '../ast'
+import { versionBanner } from '../version'
 
 export interface EmitOptions {
   /** Emit the inlined runtime shim. Defaults to true. */
@@ -49,13 +55,24 @@ export interface EmitOptions {
   banner?: string
   /** Indentation unit. Defaults to two spaces. */
   indent?: string
+  /**
+   * Optional artifact name. When `version` is set (and `banner` is not), the
+   * banner becomes `// spak:<name>:<version>`, matching spm's build banners.
+   */
+  name?: string
+  /**
+   * Artifact version, 3 or 4 numeric segments (`1.0.0` / `1.0.0.0`). Parsed by
+   * the same rules as spm's `parseVersion`; invalid values throw.
+   */
+  version?: string
 }
 
 /** Lua-style methods that are backed by the runtime shim. */
 const RUNTIME_METHODS = new Set(['push', 'pop', 'sort', 'split', 'len'])
 
-/** Node builtins whose Spak `fs` surface is synchronous. */
+/** Node builtins whose Spak `fs` surface uses the sync/async compat shim. */
 const FS_SOURCES = new Set(['fs', 'node:fs'])
+/** Node `fs` functions that also exist as `*Sync` and `fs/promises` variants. */
 const FS_SYNC = new Set([
   'access', 'appendFile', 'chmod', 'chown', 'close', 'copyFile', 'cp',
   'exists', 'fchmod', 'fchown', 'fstat', 'fsync', 'ftruncate', 'futimes',
@@ -82,9 +99,15 @@ const __spak = {
     return out
   },
   slice(x, from, to, inclusive = true) {
-    const start = Number(from) - 1
-    const end = inclusive ? Number(to) : Number(to) - 1
-    return x.slice(start, end)
+    // 1-based, end-inclusive bounds. Empty ranges (1..0, 3..2) must be empty,
+    // so clamp instead of letting a negative end mean "from the tail".
+    const length = typeof x === "string" || Array.isArray(x) ? x.length : 0
+    const rawStart = Number(from) - 1
+    const rawEnd = inclusive ? Number(to) : Number(to) - 1
+    const start = Math.max(0, Number.isFinite(rawStart) ? rawStart : 0)
+    const end = Number.isFinite(rawEnd) ? rawEnd : -1
+    if (end < start || start >= length) return x.slice(0, 0)
+    return x.slice(start, Math.min(end, length))
   },
   idx(x, i) {
     // Lua-style 1-based indexing for sequences; plain maps keep their keys.
@@ -147,6 +170,8 @@ class Emitter {
   private level = 0
   private scopes: Array<Set<string>> = [new Set()]
   private temp = 0
+  /** Identifiers used directly under `await`; drives the async `fs` surface. */
+  private awaited = new Set<string>()
   private readonly options: EmitOptions
 
   constructor(options: EmitOptions = {}) {
@@ -189,9 +214,13 @@ class Emitter {
   /* ---------------------------------------------------------------- */
 
   emitProgram(program: Program): string {
+    this.awaited = collectAwaitedIdentifiers(program)
     for (const statement of program.body) this.emitStatement(statement)
     const chunks: string[] = []
-    const banner = this.options.banner ?? '// Generated by Spak emitTypeScript'
+    const defaultBanner = this.options.version
+      ? versionBanner(this.options.name ?? 'spak', this.options.version)
+      : '// Generated by Spak emitTypeScript'
+    const banner = this.options.banner ?? defaultBanner
     if (banner) chunks.push(banner)
     if (this.options.runtime !== false) chunks.push(RUNTIME.replace(/\n$/, ''))
     chunks.push(this.lines.join('\n'))
@@ -288,11 +317,34 @@ class Emitter {
     for (const statement of block.body) this.emitStatement(statement)
   }
 
+  /** Comments only: used for positions that cannot be wrapped at runtime. */
   private emitDecorators(decorators: Decorator[] | undefined): void {
     if (!decorators?.length) return
     for (const decorator of decorators) {
-      const args = decorator.args.map(arg => this.expr(arg)).join(', ')
-      this.line(`// @${decorator.name}${args ? `(${args})` : ''}`)
+      this.line(`// @${decorator.name}${this.decoratorArgs(decorator)}`)
+    }
+  }
+
+  private decoratorArgs(decorator: Decorator): string {
+    const args = decorator.args.map(arg => this.expr(arg)).join(', ')
+    return args ? `(${args})` : ''
+  }
+
+  /** Decorator as a callable expression: `memo`, `route("GET", "/x")`. */
+  private decoratorCall(decorator: Decorator): string {
+    return decorator.args.length
+      ? `${decorator.name}(${decorator.args.map(arg => this.expr(arg)).join(', ')})`
+      : decorator.name
+  }
+
+  /**
+   * Emits executable decorator wrappers (`target = dec(target)`), innermost
+   * decorator first, matching the docs' `@decorator fn` => `f = decorator(f)`.
+   */
+  private applyDecorators(target: string, decorators: Decorator[] | undefined): void {
+    if (!decorators?.length) return
+    for (const decorator of [...decorators].reverse()) {
+      this.line(`${target} = ${this.decoratorCall(decorator)}(${target});`)
     }
   }
 
@@ -389,7 +441,9 @@ class Emitter {
 
     if (node.receiver) {
       const fn = this.renderFunction(node)
-      this.line(`${node.receiver}.${node.name} = ${fn};`)
+      const target = `${node.receiver}.${propertyName(node.name)}`
+      this.line(`${target} = ${fn};`)
+      this.applyDecorators(target, node.decorators)
       return
     }
 
@@ -401,6 +455,7 @@ class Emitter {
       this.emitFunctionBody(node)
     })
     this.line('}')
+    this.applyDecorators(node.name, node.decorators)
   }
 
   private emitClassDecl(node: ClassDecl, exported: boolean): void {
@@ -411,6 +466,7 @@ class Emitter {
     const prefix = exported ? 'export ' : ''
     const parent = node.superClass ? ` extends ${node.superClass}` : ''
     this.line(`${prefix}class ${node.name}${parent} {`)
+    const methodWrappers: Array<{ target: string, decorators: Decorator[] }> = []
     this.withScope(() => {
       for (const member of node.members) {
         if (member.kind === 'VarDecl') {
@@ -424,14 +480,29 @@ class Emitter {
           continue
         }
         this.emitClassMethod(member)
+        if (member.decorators.length) {
+          if (member.name === 'init') {
+            // Constructors cannot be reassigned after the class is built.
+            this.emitDecorators(member.decorators)
+          } else {
+            methodWrappers.push({
+              target: `${node.name}.prototype.${propertyName(member.name)}`,
+              decorators: member.decorators,
+            })
+          }
+        }
       }
     })
     this.line('}')
+    for (const wrapper of methodWrappers) {
+      this.emitDecorators(wrapper.decorators)
+      this.applyDecorators(wrapper.target, wrapper.decorators)
+    }
+    this.applyDecorators(node.name, node.decorators)
   }
 
   private emitClassMethod(node: FnDecl): void {
     if (node.doc) this.emitDoc(node.doc)
-    this.emitDecorators(node.decorators)
     const name = node.name === 'init' ? 'constructor' : node.name
     const asyncKeyword = node.async && name !== 'constructor' ? 'async ' : ''
     this.line(`${asyncKeyword}${name}(${this.emitParams(node.params)}) {`)
@@ -606,23 +677,21 @@ class Emitter {
       return
     }
     const source = JSON.stringify(node.source)
-    if (node.clauses.length === 0) {
+    const form = node.form ?? inferImportForm(node)
+    if (node.clauses.length === 0 || form === 'side-effect') {
       this.line(`import ${source};`)
       return
     }
-    if (node.clauses.length === 1) {
+    if (form === 'namespace' || node.clauses[0]?.name === '*') {
       const clause = node.clauses[0]
-      if (clause.name === '*') {
-        this.line(`import * as ${clause.alias ?? 'ns'} from ${source};`)
-        return
-      }
-      if (!clause.alias) {
-        this.line(`import ${clause.name} from ${source};`)
-        this.declare(clause.name)
-        return
-      }
-      this.line(`import { ${clause.name} as ${clause.alias} } from ${source};`)
-      this.declare(clause.alias)
+      this.line(`import * as ${clause.alias ?? 'ns'} from ${source};`)
+      this.declare(clause.alias ?? 'ns')
+      return
+    }
+    if (form === 'default' && node.clauses.length === 1) {
+      const clause = node.clauses[0]
+      this.line(`import ${clause.name} from ${source};`)
+      this.declare(clause.name)
       return
     }
     const specifiers = node.clauses.map(clause => clause.alias ? `${clause.name} as ${clause.alias}` : clause.name)
@@ -631,37 +700,67 @@ class Emitter {
   }
 
   /**
-   * Spak's `fs` is synchronous (`for name in readdir(dir)`), so imports from
-   * `fs` are bound to the `*Sync` variants through a namespace import.
+   * Spak's `fs` keeps the Lua-flavoured synchronous surface for backwards
+   * compatibility (`for name in readdir(dir)` in hello.spk), but named imports
+   * that are awaited bind to `node:fs/promises` instead:
+   *
+   *   import { readFile } from "fs"
+   *   text = await readFile("a.txt")     ->  node:fs/promises
+   *
+   * Synchronous access is explicit via `import { readFileSync } from "fs"`.
    */
   private emitFsImport(node: ImportDecl): void {
+    const form = node.form ?? inferImportForm(node)
+    if (node.clauses.length === 0 || form === 'side-effect') {
+      this.line('import "node:fs";')
+      return
+    }
+
     const namespace = `__fs${++this.temp}`
-    this.line(`import * as ${namespace} from "node:fs";`)
-    if (node.clauses.length === 0) return
 
-    if (node.clauses.length === 1) {
+    if (form === 'namespace' || node.clauses[0]?.name === '*') {
       const clause = node.clauses[0]
-      if (clause.name === '*') {
-        this.line(`const ${clause.alias ?? 'fs'} = ${namespace};`)
-        return
-      }
-      if (!clause.alias && !FS_SYNC.has(clause.name)) {
-        this.line(`const ${clause.name} = ${namespace};`)
-        this.declare(clause.name)
-        return
-      }
+      const alias = clause.alias ?? 'fs'
+      this.line(`import * as ${namespace} from "node:fs";`)
+      this.line(`const ${alias} = ${namespace};`)
+      this.declare(alias)
+      return
+    }
+
+    // `import fs from "fs"` historically exposed the whole namespace.
+    if (form === 'default' && node.clauses.length === 1) {
+      const clause = node.clauses[0]
+      this.line(`import * as ${namespace} from "node:fs";`)
+      this.line(`const ${clause.name} = ${namespace};`)
+      this.declare(clause.name)
+      return
     }
 
+    const bindings: string[] = []
+    const asyncSpecifiers: string[] = []
     for (const clause of node.clauses) {
       if (clause.name === '*') {
-        this.line(`const ${clause.alias ?? 'fs'} = ${namespace};`)
+        bindings.push(`const ${clause.alias ?? 'fs'} = ${namespace};`)
+        this.declare(clause.alias ?? 'fs')
         continue
       }
       const local = clause.alias ?? clause.name
-      const member = FS_SYNC.has(clause.name) ? `${clause.name}Sync` : clause.name
-      this.line(`const ${local} = ${namespace}.${member};`)
+      const member = fsMember(clause.name, this.awaited.has(local))
+      if (member.namespace === 'async') {
+        asyncSpecifiers.push(clause.alias ? `${clause.name} as ${clause.alias}` : clause.name)
+        this.declare(local)
+        continue
+      }
+      if (member.renamed) {
+        bindings.push(`// fs compat: never awaited, bound to ${member.name}; use import { ${member.name} } for an explicit sync API`)
+      }
+      bindings.push(`const ${local} = ${namespace}.${member.name};`)
       this.declare(local)
     }
+
+    if (bindings.length) this.line(`import * as ${namespace} from "node:fs";`)
+    if (asyncSpecifiers.length) this.line(`import { ${asyncSpecifiers.join(', ')} } from "node:fs/promises";`)
+    for (const binding of bindings) this.line(binding)
   }
 
   /* ---------------------------------------------------------------- */
@@ -724,9 +823,11 @@ class Emitter {
     const object = this.expr(node.object)
     if (node.index.kind === 'Range') {
       const range = node.index
-      if (range.from.kind === 'NumberLit' && range.from.value === 1) {
-        if (range.inclusive) return `${object}.slice(0, ${this.expr(range.to)})`
-        return `${object}.slice(0, (${this.expr(range.to)}) - 1)`
+      // `list[1..n]` is the common case: a plain 0-based slice. Everything
+      // else (including `..<` and empty `1..0`) goes through the clamped
+      // runtime helper so an off-by-one end can never wrap from the tail.
+      if (range.from.kind === 'NumberLit' && range.from.value === 1 && range.inclusive) {
+        return `${object}.slice(0, ${this.expr(range.to)})`
       }
       return `__spak.slice(${object}, ${this.expr(range.from)}, ${this.expr(range.to)}, ${range.inclusive ? 'true' : 'false'})`
     }
@@ -811,6 +912,68 @@ class Emitter {
 /* Helpers                                                             */
 /* ------------------------------------------------------------------ */
 
+/** Falls back to the historical clause-shape inference for hand-built ASTs. */
+function inferImportForm(node: ImportDecl): ImportForm {
+  if (!node.clauses.length) return 'side-effect'
+  if (node.clauses.length > 1) return 'named'
+  if (node.clauses[0].name === '*') return 'namespace'
+  return 'default'
+}
+
+interface FsMember {
+  /** Property read from the `node:fs` / `node:fs/promises` namespace. */
+  name: string
+  namespace: 'sync' | 'async'
+  /** True when a non-awaited function was rewritten to its `*Sync` twin. */
+  renamed: boolean
+}
+
+/**
+ * Resolves how an `fs` named import is bound:
+ * - `readFileSync` -> `readFileSync` on `node:fs` (explicit sync)
+ * - `readFile` awaited -> `readFile` on `node:fs/promises`
+ * - `readFile` not awaited -> `readFileSync` on `node:fs` (compat)
+ */
+function fsMember(name: string, awaited: boolean): FsMember {
+  if (name.endsWith('Sync') || !FS_SYNC.has(name)) {
+    return { name, namespace: 'sync', renamed: false }
+  }
+  if (awaited) return { name, namespace: 'async', renamed: false }
+  return { name: `${name}Sync`, namespace: 'sync', renamed: true }
+}
+
+/** Collects identifiers used directly under `await` (`await readFile(...)`). */
+function collectAwaitedIdentifiers(program: Program): Set<string> {
+  const names = new Set<string>()
+
+  // Every identifier inside the awaited expression is a candidate; only fs
+  // names are consulted later, so unrelated identifiers are harmless.
+  const collectFrom = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return
+    if (Array.isArray(node)) {
+      for (const item of node) collectFrom(item)
+      return
+    }
+    const candidate = node as { kind?: string, name?: string }
+    if (candidate.kind === 'Ident' && candidate.name) names.add(candidate.name)
+    for (const child of Object.values(node)) collectFrom(child)
+  }
+
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== 'object') return
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item)
+      return
+    }
+    const node = value as { kind?: string, argument?: unknown }
+    if (node.kind === 'AwaitExpr') collectFrom(node.argument)
+    for (const child of Object.values(value)) visit(child)
+  }
+
+  visit(program)
+  return names
+}
+
 function rawParamName(param: Param): string {
   return param.rest ? (param.name === '...' ? 'args' : param.name) : param.name
 }

package/src/index.ts

@@ -13,6 +13,9 @@ export { emitTypeScript, typeAnn } from './emit/ts'
 export type { EmitOptions } from './emit/ts'
 export { emitLua } from './emit/lua'
 export type { EmitLuaOptions } from './emit/lua'
+export {
+  VERSION_PATTERN, isValidVersion, parseVersion, versionBanner,
+} from './version'
 export {
   ANY, NIL, NUMBER, STRING, BOOLEAN,
   fromTypeAnn, union, isNil, withoutNil, isAssignable,

package/src/parser.ts

@@ -28,6 +28,7 @@ import type {
   IfStmt,
   ImportClause,
   ImportDecl,
+  ImportForm,
   Index,
   MatchArm,
   MatchStmt,
@@ -687,9 +688,11 @@ class Parser {
     const start = this.expectKeyword('import')
     const clauses: ImportClause[] = []
     let source: string
+    let form: ImportForm
 
     if (this.at(TokenType.String)) {
       source = this.next().value
+      form = 'side-effect'
     } else if (this.matchOperator('{')) {
       this.skipNewlines()
       while (!this.atOperator('}')) {
@@ -706,12 +709,14 @@ class Parser {
       this.expect(TokenType.Operator, '}', 'Expected "}"')
       this.expectKeyword('from')
       source = this.expect(TokenType.String, undefined, 'Expected module path').value
+      form = 'named'
     } else if (this.matchOperator('*')) {
       this.expectKeyword('as')
       const alias = this.expect(TokenType.Identifier, undefined, 'Expected namespace alias')
       clauses.push({ name: '*', alias: alias.value })
       this.expectKeyword('from')
       source = this.expect(TokenType.String, undefined, 'Expected module path').value
+      form = 'namespace'
     } else {
       const name = this.expect(TokenType.Identifier, undefined, 'Expected import name')
       const clause: ImportClause = { name: name.value }
@@ -721,9 +726,10 @@ class Parser {
       clauses.push(clause)
       this.expectKeyword('from')
       source = this.expect(TokenType.String, undefined, 'Expected module path').value
+      form = 'default'
     }
 
-    return { kind: 'ImportDecl', clauses, source, loc: this.loc(start) }
+    return { kind: 'ImportDecl', clauses, source, form, loc: this.loc(start) }
   }
 
   private parseExport(): Statement {

package/src/version.ts

@@ -0,0 +1,44 @@
+/**
+ * Spak Lang - artifact version parsing
+ *
+ * Mirrors the rules spm uses for `--version` / manifest versions so emitted
+ * comments and spm artifacts accept exactly the same 3- or 4-segment values:
+ * `major.minor.patch` or `major.minor.patch.build`.
+ *
+ * This module intentionally has no dependency on spm; spm keeps its own
+ * validation (`packages/spm/src/version.ts`) and is not modified here.
+ */
+
+/** 3 or 4 numeric segments, nothing else. */
+export const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:\.\d+)?$/
+
+/** True when `input` is a valid 3- or 4-segment Spak version. */
+export function isValidVersion(input: unknown): input is string {
+  return typeof input === 'string' && VERSION_PATTERN.test(input)
+}
+
+/**
+ * Validate a version and return it unchanged (trimmed).
+ * Throws a plain `Error` for empty / malformed / path-like input.
+ */
+export function parseVersion(input: unknown): string {
+  const value = typeof input === 'string' ? input.trim() : ''
+  if (!value) {
+    throw new Error('版本号不能为空（格式：major.minor.patch 或 major.minor.patch.build，如 1.0.0 / 1.0.0.0）')
+  }
+  if (/[/\\\0]/.test(value) || value.includes('..')) {
+    throw new Error(`非法版本号 "${value}"：不能包含 /、\\、.. 或空字符`)
+  }
+  if (!VERSION_PATTERN.test(value)) {
+    throw new Error(`非法版本号 "${value}"：需为 3 段或 4 段纯数字（如 1.0.0 或 1.0.0.0）`)
+  }
+  return value
+}
+
+/**
+ * Builds the banner comment used by spm build/dev (`// spak:<name>:<version>`).
+ * Both 3- and 4-segment versions are preserved verbatim after validation.
+ */
+export function versionBanner(name: string, version: unknown): string {
+  return `// spak:${name}:${parseVersion(version)}`
+}