@gi-tcg/gts-transpiler 0.1.1 → 0.3.0

package/package.json

@@ -1,32 +1,31 @@
 {
   "name": "@gi-tcg/gts-transpiler",
-  "version": "0.1.1",
+  "version": "0.3.0",
+  "repository": "https://github.com/piovium/gts.git",
+  "license": "Apache-2.0",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "bun": "./src/index.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "src",
     "dist"
   ],
-  "scripts": {
-    "build": "bun build --outdir=dist --target=node --format=esm --conditions='bun' --packages=external src/index.ts",
-    "prepublishOnly": "bun run build"
-  },
+  "scripts": {},
   "dependencies": {
     "@jridgewell/sourcemap-codec": "^1.5.5",
     "@sveltejs/acorn-typescript": "^1.0.8",
-    "acorn": "^8.15.0",
-    "esrap": "^2.2.1",
+    "acorn": "8.15.0",
+    "esrap": "2.2.1",
     "magic-string": "^0.30.21",
     "zimmerframe": "^1.1.4"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.4",
+    "@types/node": "^24.3.0",
     "@types/estree": "^1.0.8",
     "@volar/language-core": "^2.4.27"
   }

package/src/config.ts

@@ -0,0 +1,221 @@
+import type { TranspileOption } from "./transform/gts";
+
+export interface PathPolyfill {
+  isAbsolute(filePath: string): boolean;
+  dirname(filePath: string): string;
+  resolve(...segments: string[]): string;
+}
+
+export const path: PathPolyfill = globalThis.require
+  ? (globalThis.require("node:path") as typeof import("node:path"))
+  : {
+      isAbsolute(filePath) {
+        return filePath.startsWith("/");
+      },
+      dirname(filePath) {
+        if (!filePath) {
+          return ".";
+        }
+        const normalized = normalizeSlashes(filePath);
+        if (normalized === "/") {
+          return "/";
+        }
+        const trimmed =
+          normalized.length > 1 && normalized.endsWith("/")
+            ? normalized.slice(0, -1)
+            : normalized;
+        const idx = trimmed.lastIndexOf("/");
+        if (idx < 0) {
+          return ".";
+        }
+        if (idx === 0) {
+          return "/";
+        }
+        return trimmed.slice(0, idx);
+      },
+      resolve(...segments) {
+        if (segments.length === 0) {
+          return ".";
+        }
+        let resolved = "";
+        for (let i = segments.length - 1; i >= 0; i--) {
+          const segment = segments[i];
+          if (!segment) {
+            continue;
+          }
+          if (resolved) {
+            resolved = `${segment}/${resolved}`;
+          } else {
+            resolved = segment;
+          }
+          if (path.isAbsolute(segment)) {
+            break;
+          }
+        }
+        return normalizeResolvedPath(resolved || ".");
+      },
+    };
+
+function normalizeSlashes(filePath: string): string {
+  return filePath.replace(/\\+/g, "/");
+}
+
+function normalizeResolvedPath(filePath: string): string {
+  const normalized = normalizeSlashes(filePath);
+  const isAbsolute = normalized.startsWith("/");
+  const parts = normalized.split("/");
+  const stack: string[] = [];
+  for (const part of parts) {
+    if (!part || part === ".") {
+      continue;
+    }
+    if (part === "..") {
+      if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+        stack.pop();
+      } else if (!isAbsolute) {
+        stack.push("..");
+      }
+      continue;
+    }
+    stack.push(part);
+  }
+  if (isAbsolute) {
+    return `/${stack.join("/")}` || "/";
+  }
+  return stack.join("/") || ".";
+}
+
+export interface GtsConfig extends TranspileOption {}
+
+export interface PackageJson {
+  gamingTs?: GtsConfig;
+}
+
+type ReadFileFn = (path: string, encoding: "utf8") => string;
+type ReadFileAsyncFn = (path: string, encoding: "utf8") => Promise<string>;
+
+export interface ResolveGtsConfigSyncOptions {
+  readFileFn: ReadFileFn;
+  cwd?: string;
+  stopDir?: string;
+}
+
+export interface ResolveGtsConfigAsyncOptions {
+  readFileFn: ReadFileAsyncFn;
+  cwd?: string;
+  stopDir?: string;
+}
+
+const DEFAULT_GTS_CONFIG: Required<GtsConfig> = {
+  runtimeImportSource: "@gi-tcg/gts-runtime",
+  providerImportSource: "@gi-tcg/core/gts",
+  shortcutFunctionPreludes: [
+    "cryo",
+    "hydro",
+    "pyro",
+    "electro",
+    "anemo",
+    "geo",
+    "dendro",
+    "omni",
+  ],
+  queryBindings: ["my", "opp"],
+};
+
+function* resolveGtsConfigImpl(
+  filePath: string,
+  inlineConfig: GtsConfig = {},
+  options: ResolveGtsConfigAsyncOptions | ResolveGtsConfigSyncOptions,
+): Generator<string | Promise<string>, Required<GtsConfig>, string> {
+  const startDir = normalizeStartDir(filePath, options.cwd);
+  const stopDir = options.stopDir ? path.resolve(options.stopDir) : void 0;
+  const pkgConfig = yield* findNearestPackageConfig(
+    options.readFileFn,
+    startDir,
+    stopDir,
+  );
+  return {
+    ...DEFAULT_GTS_CONFIG,
+    ...pkgConfig,
+    ...inlineConfig,
+  };
+}
+
+export async function resolveGtsConfig(
+  filePath: string,
+  inlineConfig: GtsConfig,
+  options: ResolveGtsConfigAsyncOptions,
+): Promise<Required<GtsConfig>> {
+  const generator = resolveGtsConfigImpl(filePath, inlineConfig, options);
+  let result = generator.next();
+  while (!result.done) {
+    const toRead = result.value;
+    const content = await toRead;
+    result = generator.next(content);
+  }
+  return result.value;
+}
+
+export function resolveGtsConfigSync(
+  filePath: string,
+  inlineConfig: GtsConfig,
+  options: ResolveGtsConfigSyncOptions,
+): Required<GtsConfig> {
+  const generator = resolveGtsConfigImpl(filePath, inlineConfig, options);
+  let result = generator.next();
+  while (!result.done) {
+    const toRead = result.value;
+    if (toRead instanceof Promise) {
+      throw new Error(
+        "resolveGtsConfigSync received a Promise. Did you mean to use resolveGtsConfig instead?",
+      );
+    }
+    const content = toRead;
+    result = generator.next(content);
+  }
+  return result.value;
+}
+
+function normalizeStartDir(sourceFile: string, cwd?: string): string {
+  const absolute = path.isAbsolute(sourceFile)
+    ? sourceFile
+    : path.resolve(cwd || ".", sourceFile);
+  return path.dirname(absolute);
+}
+
+function* findNearestPackageConfig(
+  readFileFn: ReadFileFn | ReadFileAsyncFn,
+  startDir: string,
+  stopDir?: string,
+): Generator<string | Promise<string>, GtsConfig, string> {
+  let currentDir = startDir;
+  while (true) {
+    const pkgPath = path.resolve(currentDir, "package.json");
+    const config = yield* readPackageConfig(readFileFn, pkgPath);
+    if (config) {
+      return config;
+    }
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    if (stopDir && currentDir === stopDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+  return {};
+}
+
+function* readPackageConfig(
+  readFileFn: ReadFileFn | ReadFileAsyncFn,
+  pkgPath: string,
+): Generator<string | Promise<string>, GtsConfig | undefined, string> {
+  try {
+    const content = yield readFileFn(pkgPath, "utf8");
+    const parsed = JSON.parse(content) as PackageJson;
+    return parsed.gamingTs;
+  } catch {
+    return;
+  }
+}

package/src/index.ts

@@ -11,7 +11,7 @@ export { GtsTranspilerError } from "./error";
 export function transpile(
   source: string,
   filename: string,
-  option: TranspileOption
+  option: TranspileOption,
 ): TranspileResult {
   const ast = parse(source);
   return transform(ast, option, {
@@ -23,9 +23,11 @@ export function transpile(
 export function transpileForVolar(
   source: string,
   filename: string,
-  option: TranspileOption
+  option: TranspileOption,
 ): VolarMappingResult {
-  const ast = parseLoose(source);
+  const ast = parseLoose(source, {
+    recordCallLParens: true,
+  });
   return transformForVolar(ast, option, {
     content: source,
     filename,
@@ -33,3 +35,10 @@ export function transpileForVolar(
 }
 
 export type { TranspileOption, TranspileResult, VolarMappingResult };
+export {
+  resolveGtsConfig,
+  resolveGtsConfigSync,
+  type GtsConfig,
+  path,
+  type PathPolyfill,
+} from "./config";

package/src/keywords.ts

@@ -1,4 +1,4 @@
-export const specialIdentifiers = [
+export const specialIdentifiers: string[] = [
   // Always Reserved Words
   "break",
   "case",

package/src/parse/comment.d.ts

@@ -0,0 +1,10 @@
+import { Comment, Node } from "estree";
+import { Options } from "acorn";
+
+export function getCommentHandlers(
+  source: string,
+  comments: Comment[],
+): {
+  onComment: Options["onComment"];
+  addComments: (ast: Node) => void;
+};

package/src/parse/gts_plugin.ts

@@ -75,7 +75,7 @@ export interface GtsPluginOption {
 
 export function gtsPlugin(options: GtsPluginOption = {}) {
   return function gtsPluginTransformer(
-    Parser: typeof ParserClass
+    Parser: typeof ParserClass,
   ): typeof ParserClass {
     const skipWhiteSpace = /(?:\s|\/\/.*|\/\*[^]*?\*\/)*/g;
     const lineBreak = /\r\n?|\n|\u2028|\u2029/;
@@ -95,7 +95,7 @@ export function gtsPlugin(options: GtsPluginOption = {}) {
       override parseStatement(
         context?: string | null,
         topLevel?: boolean,
-        exports?: AST.ExportSpecifier
+        exports?: AST.ExportSpecifier,
       ) {
         if (topLevel && this.gts_isDefineStatement()) {
           const node = this.startNode() as AST.GTSDefineStatement;
@@ -119,13 +119,20 @@ export function gtsPlugin(options: GtsPluginOption = {}) {
       gts_parseNamedAttributeDefinition() {
         const node = this.startNode() as AST.GTSNamedAttributeDefinition;
         // AttributeName
-        let name: any;
+        const start = this.start;
+        let name: AST.Identifier | AST.SimpleLiteral;
         if (this.type.label === "string") {
-          name = this.parseExprAtom();
+          name = this.parseExprAtom() as AST.SimpleLiteral;
+          if (typeof name.value === "string" && name.value.startsWith("~")) {
+            this.raise(
+              start,
+              `Attribute name starts with '~' is reserved for internal use.`,
+            );
+          }
         } else if (this.type.label === "name") {
           name = this.parseIdent();
         } else {
-          this.raise(this.start, "Expected attribute name");
+          this.raise(start, "Expected attribute name");
         }
         node.name = name;
         // AttributeBody
@@ -215,7 +222,7 @@ export function gtsPlugin(options: GtsPluginOption = {}) {
           if (stmt.type === "GTSDefineStatement") {
             this.raise(
               startPos,
-              "DefineStatement is not allowed in direct function."
+              "DefineStatement is not allowed in direct function.",
             );
           }
           node.body.push(stmt);
@@ -274,13 +281,13 @@ export function gtsPlugin(options: GtsPluginOption = {}) {
       override parseExprAtom(
         refDestructuringErrors?: Parse.DestructuringErrors,
         forInit?: boolean | "await",
-        forNew?: boolean
+        forNew?: boolean,
       ): AST.Expression {
         if (this.type === tokTypes.colon) {
           if (!this.isShortcutContext) {
             this.raise(
               this.start,
-              "ShortcutArgumentExpression ':' must be inside ShortcutFunction or DirectShortcutFunction."
+              "ShortcutArgumentExpression ':' must be inside ShortcutFunction or DirectShortcutFunction.",
             );
           }
           const node = this.startNode() as AST.GTSShortcutArgumentExpression;
@@ -307,7 +314,7 @@ export function gtsPlugin(options: GtsPluginOption = {}) {
         refDestructuringErrors?: Parse.DestructuringErrors | null,
         sawUnary?: boolean,
         incDec?: boolean,
-        forInit?: boolean | "await"
+        forInit?: boolean | "await",
       ): AST.Expression {
         if (this.isContextual("query")) {
           const expr = this.gts_parseQueryExpression();
@@ -320,12 +327,12 @@ export function gtsPlugin(options: GtsPluginOption = {}) {
           refDestructuringErrors,
           sawUnary,
           incDec,
-          forInit
+          forInit,
         );
       }
 
       gts_parseQueryExpression(
-        forInit?: boolean | "await"
+        forInit?: boolean | "await",
       ): AST.GTSQueryExpression {
         const node = this.startNode() as AST.GTSQueryExpression;
         this.next(); // consume 'query'

package/src/parse/index.ts

@@ -1,10 +1,11 @@
 import { Parser } from "acorn";
-import type { Program } from "estree";
+import type { Position, Program } from "estree";
 import { tsPlugin } from "@sveltejs/acorn-typescript";
 import { gtsPlugin, type GtsPluginOption } from "./gts_plugin.js";
 import { loosePlugin } from "./loose_plugin.js";
 import { getCommentHandlers } from "./comment.js";
 import { GtsTranspilerError } from "../error.js";
+import { recordCallLParenPlugin } from "./record_call_lparen_plugin.js";
 
 const TsParser = Parser.extend(tsPlugin());
 
@@ -29,15 +30,24 @@ export function parse(input: string, options?: GtsPluginOption): Program {
   }
 }
 
-export function parseLoose(input: string, options?: GtsPluginOption): Program {
+export interface ParseLooseOptions extends GtsPluginOption {
+  recordCallLParens?: boolean;
+}
+
+export function parseLoose(
+  input: string,
+  options?: ParseLooseOptions,
+): Program {
   try {
     const GtsParser = TsParser.extend(
       loosePlugin(),
+      ...(options?.recordCallLParens ? [recordCallLParenPlugin()] : []),
       gtsPlugin({
-        ...options,
-        allowEmptyShortcutMember: true,
-        allowEmptyPositionalAttribute: true,
-      })
+        allowEmptyShortcutMember:
+          options?.allowEmptyPositionalAttribute || true,
+        allowEmptyPositionalAttribute:
+          options?.allowEmptyPositionalAttribute || true,
+      }),
     );
     const { onComment, addComments } = getCommentHandlers(input, []);
     const ast = GtsParser.parse(input, {

package/src/parse/loose_plugin.ts

@@ -15,7 +15,7 @@ export function loosePlugin() {
           return super.parseIdent(liberal);
         }
       };
-      private _proxiedThis = new Proxy(this, {
+      readonly #proxiedThis = new Proxy(this, {
         get: (target, prop) => {
           if (prop === "parseIdent") {
             return this._patchedParseIdent;
@@ -45,7 +45,7 @@ export function loosePlugin() {
         forInit?: boolean | "await",
       ): AST.Expression {
         return super.parseSubscript.call(
-          this._proxiedThis,
+          this.#proxiedThis,
           base,
           startPos,
           startLoc,

package/src/parse/record_call_lparen_plugin.ts

@@ -0,0 +1,85 @@
+import { tokTypes, type Parser } from "acorn";
+import type { AST, Parse } from "../types.js";
+
+/**
+ * A plugin that records the location of the left parenthesis in CallExpression and 
+ * NewExpression.
+ * 
+ * This is useful for Language tooling, that we can maps the '(' token from its location, 
+ * to provide  * a signature help for user when they press `(` after a function name.
+ *
+ * The recorded location will be stored in `lParenLoc` property of the 
+ * CallExpression/NewExpression node.
+ * @returns
+ */
+export function recordCallLParenPlugin() {
+  return function recordCallLParenPluginTransformer(
+    parser: typeof Parser,
+  ): typeof Parser {
+    return class RecordCallLParenParser extends (parser as typeof Parse.Parser) {
+      override parseSubscript(
+        base: AST.Expression,
+        startPos: number,
+        startLoc: AST.Position,
+        noCalls?: boolean,
+        maybeAsyncArrow?: boolean,
+        optionalChained?: boolean,
+        forInit?: boolean | "await",
+      ): AST.Expression {
+        let recordedLParenLoc: AST.SourceLocation | null = null;
+        if (!noCalls && this.type === tokTypes.parenL) {
+          recordedLParenLoc = {
+            start: this.startLoc,
+            end: this.endLoc,
+          };
+        }
+        const result = super.parseSubscript(
+          base,
+          startPos,
+          startLoc,
+          noCalls,
+          maybeAsyncArrow,
+          optionalChained,
+          forInit,
+        );
+        if (recordedLParenLoc && result.type === "CallExpression") {
+          result.lParenLoc = recordedLParenLoc;
+        }
+        return result;
+      }
+
+      private _capturedLParenLocFromNew: AST.SourceLocation | null = null;
+      private readonly _patchedEat = (type: any) => {
+        if (type === tokTypes.parenL) {
+          this._capturedLParenLocFromNew = {
+            start: this.startLoc,
+            end: this.endLoc,
+          };
+        }
+        return this.eat(type);
+      };
+
+      readonly #proxiedThis = new Proxy(this, {
+        get: (target, prop) => {
+          if (prop === "eat") {
+            return this._patchedEat;
+          }
+          const value = Reflect.get(target, prop);
+          if (typeof value === "function") {
+            return value.bind(target);
+          }
+          return value;
+        },
+      });
+
+      override parseNew() {
+        const result = super.parseNew.apply(this.#proxiedThis);
+        if (this._capturedLParenLocFromNew && result.type === "NewExpression") {
+          result.lParenLoc = this._capturedLParenLocFromNew;
+          this._capturedLParenLocFromNew = null;
+        }
+        return result;
+      }
+    };
+  };
+}

package/src/transform/constants.ts

@@ -1,11 +1,11 @@
-export const DEFAULT_SHORTCUT_FUNCTION_PRELUDES =  [
-    "cryo",
-    "hydro",
-    "pyro",
-    "electro",
-    "anemo",
-    "geo",
-    "dendro",
-    "omni",
-  ];
-export const DEFAULT_QUERY_BINDINGS = ["my", "opp"];
+export const DEFAULT_SHORTCUT_FUNCTION_PRELUDES: string[] = [
+  "cryo",
+  "hydro",
+  "pyro",
+  "electro",
+  "anemo",
+  "geo",
+  "dendro",
+  "omni",
+];
+export const DEFAULT_QUERY_BINDINGS: string[] = ["my", "opp"];