refactor: move builtin packages to gs/

Signed-off-by: Christian Stewart <[email protected]>

Author: paralin

.roo/rules/aider

@@ -1,5 +1,5 @@
 You may invoke an advanced artificial intelligence to analyze code or make edits to code by first writing the details of the task you want to complete and the prompt to `.aider-prompt` in the workspace root and then running the `aider` command-line tool with the --message-file flag set to `.aider-prompt`, including the filenames of all relevant code files and the files to edit as arguments. For example: `aider --yes-always --no-git --no-pretty --message-file .aider-prompt source_file.go other_source_file.ts information.md` - remember that `aider` is a shell command. Explicitly tell aider to not make any file changes if you don't expressly want that to happen.
 When using the `aider` tool add the `--architect` flag when asking aider to make difficult changes to files and add `--model o4-mini` if the task is very hard and you are not using many context files. Otherwise do not specify the `--model` nor the `--architect` flags.
 Remember that `aider` is a single-turn AI tool and cannot access git history or run commands directly. To review changes, provide the relevant file contents to `aider` via command line arguments and the `.aider-prompt` file. The `.aider-prompt` file should contain the task description and any additional context needed for the review.
-Pass all of the compiler source files as arguments to aider. You can use "./compiler/*.go ./builtin/builtin.ts" to include all relevant files. Also include any WIP.md file if you are using one.
+Pass all of the compiler source files as arguments to aider. You can use "./compiler/*.go ./gs/builtin/builtin.ts" to include all relevant files. Also include any WIP.md file if you are using one.
 Remember to always pass a high-level context and description of the task to Aider without a specific solution, and let aider figure out what to do to solve the problem.

.roo/rules/project-info

@@ -1,3 +1,3 @@
-GoScript is an experimental Go to TypeScript transpiler that enables developers to convert high-level Go code into maintainable TypeScript. It translates Go constructs—such as structs, functions, and pointer semantics—into idiomatic TypeScript code while preserving Go's value semantics and type safety. It is designed to bridge the gap between the robust type system of Go and the flexible ecosystem of TypeScript. The GoScript runtime, located in `builtin/builtin.ts`, provides necessary helper functions and is imported in generated code using the `@goscript/builtin` alias.
+GoScript is an experimental Go to TypeScript transpiler that enables developers to convert high-level Go code into maintainable TypeScript. It translates Go constructs—such as structs, functions, and pointer semantics—into idiomatic TypeScript code while preserving Go's value semantics and type safety. It is designed to bridge the gap between the robust type system of Go and the flexible ecosystem of TypeScript. The GoScript runtime, located in `gs/builtin/builtin.ts`, provides necessary helper functions and is imported in generated code using the `@goscript/builtin` alias.
 The generated output TypeScript style from the transpiler should not use semicolons and should always focus on code clarity and correctness.
 Follow Rick Rubin's concept of being both an engineer and a reducer (not always a producer) by focusing on the shortest, most straightforward solution that is correct.

builtin/builtin.go

@@ -9,8 +9,8 @@ import (
 	"github.com/pkg/errors"
 	"github.com/sirupsen/logrus"
 
-	// _ ensure we include the builtin package
-	_ "github.com/aperturerobotics/goscript/builtin"
+	// _ ensure we include the gs package
+	_ "github.com/aperturerobotics/goscript"
 )
 
 var (

cmd/goscript/cmd_compile.go

@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	gs "github.com/aperturerobotics/goscript"
 	"github.com/sirupsen/logrus"
 	"golang.org/x/tools/go/packages"
 )
@@ -140,6 +141,16 @@ func (c *Compiler) CompilePackages(ctx context.Context, patterns ...string) erro
 
 	// Compile all packages
 	for _, pkg := range pkgs {
+		// Check if the package has a handwritten equivalent
+		_, gsErr := gs.GsOverrides.ReadDir("gs/" + pkg.PkgPath)
+		if gsErr != nil && !os.IsNotExist(gsErr) {
+			return gsErr
+		}
+		if gsErr == nil {
+			c.le.Infof("Skipping compilation for overridden package %s", pkg.PkgPath)
+			continue
+		}
+
 		// Skip packages that failed to load
 		if len(pkg.Errors) > 0 {
 			c.le.WithError(pkg.Errors[0]).Warnf("Skipping package %s due to errors", pkg.PkgPath)
@@ -328,8 +339,8 @@ func NewFileCompiler(
 // top-level declarations in the Go file.
 func (c *FileCompiler) Compile(ctx context.Context) error {
 	f := c.ast
-
 	pkgPath := c.pkg.PkgPath
+
 	outputFilePath := TranslateGoFilePathToTypescriptFilePath(pkgPath, filepath.Base(c.fullPath))
 	outputFilePathAbs := filepath.Join(c.compilerConfig.OutputPathRoot, outputFilePath)
 
@@ -349,7 +360,7 @@ func (c *FileCompiler) Compile(ctx context.Context) error {
 	goWriter := NewGoToTSCompiler(c.codeWriter, c.pkg, c.Analysis)
 
 	// Add import for the goscript runtime using namespace import and alias
-	c.codeWriter.WriteLine("import * as $ from \"@goscript/builtin\";")
+	c.codeWriter.WriteLinef("import * as $ from %q;", "@goscript/builtin/builtin.js")
 	c.codeWriter.WriteLine("") // Add a newline after the import
 
 	if err := goWriter.WriteDecls(f.Decls); err != nil {
@@ -368,7 +379,7 @@ type GoToTSCompiler struct {
 
 	pkg *packages.Package
 
-	analysis *Analysis // Holds analysis information for code generation decisions
+	analysis *Analysis
 }
 
 // It initializes the compiler with a `TSCodeWriter` for output,

compiler/compiler.go

@@ -253,11 +253,20 @@ func (c *GoToTSCompiler) WriteImportSpec(a *ast.ImportSpec) {
 		impName = a.Name.Name
 	}
 
-	importPath := translateGoPathToTypescriptPath(goPath)
+	// All Go package imports are mapped to the @goscript/ scope.
+	// The TypeScript compiler will resolve these using tsconfig paths to either
+	// handwritten versions (in .goscript-assets) or transpiled versions (in goscript).
+	var tsImportPath string
+	if goPath == "github.com/aperturerobotics/goscript/builtin" {
+		tsImportPath = "@goscript/builtin/builtin.js"
+	} else {
+		tsImportPath = "@goscript/" + goPath
+	}
+
 	c.analysis.Imports[impName] = &fileImport{
-		importPath: importPath,
+		importPath: tsImportPath,
 		importVars: make(map[string]struct{}),
 	}
 
-	c.tsw.WriteImport(impName, importPath+"/index.js")
+	c.tsw.WriteImport(impName, tsImportPath+"/index.js")
 }

compiler/spec.go

@@ -437,7 +437,7 @@ func copyFile(src, dst string) error {
 // It includes all "*.gs.ts" and "index.ts" files found recursively within testDir.
 // It sets up "paths" aliases for:
 //   - The test's own generated package: "@goscript/PARENT_MODULE/compliance/tests/TEST_NAME/*" -> "./*"
-//   - The goscript builtin types: "@goscript/builtin" -> relative path to "workspaceDir/builtin/builtin.ts"
+//   - The goscript builtin types: "@goscript/builtin" -> relative path to "workspaceDir/gs/builtin/builtin.ts"
 //
 // Returns the path to the generated "tsconfig.json" file.
 func WriteTypeCheckConfig(t *testing.T, parentModulePath, workspaceDir, testDir string) string {
@@ -500,16 +500,12 @@ func WriteTypeCheckConfig(t *testing.T, parentModulePath, workspaceDir, testDir
 	compilerOptions := maps.Clone(tsconfig["compilerOptions"].(map[string]interface{}))
 	compilerOptions["baseUrl"] = "." // testDir is baseUrl
 
-	// For paths in tsconfig, it's often better to use relative paths from baseUrl if possible,
-	// but for @goscript/builtin, pointing to the canonical one is important.
-	// It needs to be relative from testDir (baseUrl) to workspaceDir/builtin/builtin.ts
-	builtinTsRelPath := filepath.ToSlash(filepath.Join(relWorkspacePath, "builtin", "builtin.ts"))
-
 	// Alias for this test's own generated packages
+	builtinTsRelPath := filepath.ToSlash(filepath.Join(relWorkspacePath, "gs", "*"))
 	testPkgGoPathPrefix := fmt.Sprintf("%s/compliance/tests/%s", parentModulePath, testName)
 	compilerOptions["paths"] = map[string][]string{
-		fmt.Sprintf("@goscript/%s/*", testPkgGoPathPrefix): {"./*"}, // Maps to files in testDir/*
-		"@goscript/builtin": {builtinTsRelPath},
+		fmt.Sprintf("@goscript/%s/*", testPkgGoPathPrefix): {"./*"},
+		"@goscript/*": {builtinTsRelPath},
 	}
 	tsconfig["compilerOptions"] = compilerOptions
 
@@ -623,13 +619,20 @@ func RunGoScriptTestDir(t *testing.T, workspaceDir, testDir string) {
 
 	tempDir := PrepareTestRunDir(t, testDir)
 
+	// Calculate the relative path from tempDir to the workspace's gs/builtin/builtin.ts
+	gsBuiltinPath := filepath.Join(workspaceDir, "gs", "*")
+	relGsBuiltinPath, err := filepath.Rel(tempDir, gsBuiltinPath)
+	if err != nil {
+		t.Fatalf("failed to calculate relative path from tempDir (%s) to gs/builtin/builtin.ts (%s): %v", tempDir, gsBuiltinPath, err)
+	}
+	relGsBuiltinPath = filepath.ToSlash(relGsBuiltinPath) // Ensure forward slashes for tsconfig
+
 	// tsconfig.json for the runner execution in tempDir
 	runnerTsConfig := maps.Clone(baseTsConfig)
 	runnerCompilerOptions := maps.Clone(runnerTsConfig["compilerOptions"].(map[string]interface{}))
 	runnerCompilerOptions["baseUrl"] = "." // tempDir is baseUrl
 	runnerCompilerOptions["paths"] = map[string][]string{
-		"@goscript/*":       {"./output/@goscript/*"},           // Maps to tempDir/output/@goscript/*
-		"@goscript/builtin": {"../../../../builtin/builtin.ts"}, // Maps to workspace/builtin/builtin.ts
+		"@goscript/*": {"./output/@goscript/*", relGsBuiltinPath},
 	}
 	runnerTsConfig["compilerOptions"] = runnerCompilerOptions
 

compliance/compliance.go

@@ -1,7 +1,7 @@
 // Generated file based on array_literal.go
 // Updated when compliance tests are re-run, DO NOT EDIT!
 
-import * as $ from "@goscript/builtin";
+import * as $ from "@goscript/builtin/builtin.js";
 
 export function main(): void {
 	// Test basic array literal

compliance/tests/array_literal/array_literal.gs.ts

@@ -1,7 +1,7 @@
 // Generated file based on assign_op.go
 // Updated when compliance tests are re-run, DO NOT EDIT!
 
-import * as $ from "@goscript/builtin";
+import * as $ from "@goscript/builtin/builtin.js";
 
 export function main(): void {
 	let a: number = 5

compliance/tests/assign_op/assign_op.gs.ts

@@ -1,7 +1,7 @@
 // Generated file based on async_basic.go
 // Updated when compliance tests are re-run, DO NOT EDIT!
 
-import * as $ from "@goscript/builtin";
+import * as $ from "@goscript/builtin/builtin.js";
 
 // This function receives from a channel, making it async.
 async function receiveFromChan(ch: $.Channel<number>): Promise<number> {