@ttsc/strip 0.12.3 → 0.13.0

package/README.md

@@ -43,19 +43,27 @@ Default behavior removes these statement patterns:
 
 Call patterns match statement-level calls such as `console.log("debug")` or `assert.equal(left, right)`. A wildcard is supported at the end of a dotted call pattern, such as `assert.*`.
 
-Add a direct plugin config only when the project needs a different strip list:
+To customize the strip list, add a `strip.config.ts` next to your `tsconfig.json`:
+
+```ts
+// strip.config.ts
+import type { ITtscStripConfig } from "@ttsc/strip";
+
+export default {
+  calls: ["console.log", "console.debug", "assert.*"],
+  statements: ["debugger"],
+} satisfies ITtscStripConfig;
+```
+
+`@ttsc/strip` discovers its config by walking upward from the tsconfig directory, looking for `strip.config.{ts,cts,mts,js,cjs,mjs,json}`. To point at a specific file, set `configFile` on the tsconfig entry:
 
 ```jsonc
 {
   "compilerOptions": {
     "plugins": [
-      {
-        "transform": "@ttsc/strip",
-        "calls": ["console.log", "console.debug", "assert.*"],
-        "statements": ["debugger"],
-      },
-    ],
-  },
+      { "transform": "@ttsc/strip", "configFile": "./config/strip.config.ts" }
+    ]
+  }
 }
 ```
 

package/driver/config.go

@@ -0,0 +1,506 @@
+package strip
+
+import (
+  "bytes"
+  "context"
+  "encoding/json"
+  "fmt"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "runtime"
+  "strings"
+  "time"
+)
+
+// configLoaderTimeout caps every `ttsx`/`node -e` subprocess that evaluates a
+// user-supplied strip config. Mirrors the lint package budget: 60 s is generous
+// for cold ttsx starts on CI runners and tight enough to keep user-visible
+// feedback under a minute.
+const configLoaderTimeout = 60 * time.Second
+
+// stripConfigFilenames is the ordered list of candidate filenames that
+// findStripConfigFile checks in each directory during upward discovery.
+var stripConfigFilenames = []string{
+  "strip.config.ts",
+  "strip.config.mts",
+  "strip.config.cts",
+  "strip.config.js",
+  "strip.config.mjs",
+  "strip.config.cjs",
+  "strip.config.json",
+}
+
+// allowedTsconfigKeys lists the tsconfig plugin-entry keys that @ttsc/strip
+// accepts. Any other key is a hard error.
+var allowedTsconfigKeys = map[string]struct{}{
+  "configFile": {},
+  "enabled":    {},
+  "name":       {},
+  "stage":      {},
+  "transform":  {},
+}
+
+// loadStripConfigMap validates the tsconfig plugin entry and loads the strip
+// configuration from either an explicit configFile or an auto-discovered
+// strip.config.* file. Returns the raw config map ready for parseStrip.
+func loadStripConfigMap(pluginConfig map[string]any, cwd, tsconfigPath string) (map[string]any, error) {
+  // Reject any key that @ttsc/strip does not recognise. This surfaces
+  // stale inline keys (calls, statements) with a clear error so users
+  // migrate to a config file instead of silently using defaults.
+  for key := range pluginConfig {
+    if _, ok := allowedTsconfigKeys[key]; !ok {
+      return nil, fmt.Errorf(
+        "@ttsc/strip: tsconfig plugin entry contains unsupported key %q; "+
+          "strip configuration must be supplied via a strip.config.* file "+
+          "(use the \"configFile\" key to point at a custom path)",
+        key,
+      )
+    }
+  }
+
+  // Resolve the config file: explicit configFile wins over discovery.
+  configFilePath := ""
+  if rawCF, ok := pluginConfig["configFile"]; ok {
+    cf, ok := rawCF.(string)
+    if !ok || strings.TrimSpace(cf) == "" {
+      return nil, fmt.Errorf("@ttsc/strip: \"configFile\" must be a non-empty string path")
+    }
+    configFilePath = resolveStripConfigFilePath(cf, cwd, tsconfigPath)
+  } else {
+    discovered, err := findStripConfigFile(cwd, tsconfigPath)
+    if err != nil {
+      return nil, err
+    }
+    configFilePath = discovered
+  }
+
+  // No config file found → use defaults (parseStrip treats an empty map
+  // as "apply built-in defaults").
+  if configFilePath == "" {
+    return map[string]any{}, nil
+  }
+
+  raw, err := loadStripConfigFile(configFilePath)
+  if err != nil {
+    return nil, err
+  }
+  cfg, ok := raw.(map[string]any)
+  if !ok {
+    return nil, fmt.Errorf("@ttsc/strip: config file %s must export an object", configFilePath)
+  }
+  return cfg, nil
+}
+
+// findStripConfigFile walks upward from the tsconfig directory (or cwd when no
+// tsconfig is set) and returns the first directory that contains exactly one
+// strip.config.* file. Multiple candidates in the same directory is an error.
+// Returns "" (no error) when the filesystem root is reached without a match.
+func findStripConfigFile(cwd, tsconfigPath string) (string, error) {
+  dir := stripDiscoveryBaseDir(cwd, tsconfigPath)
+  for {
+    matches := make([]string, 0, 1)
+    for _, name := range stripConfigFilenames {
+      candidate := filepath.Join(dir, name)
+      if stat, err := os.Stat(candidate); err == nil && !stat.IsDir() {
+        matches = append(matches, candidate)
+      }
+    }
+    if len(matches) > 1 {
+      names := make([]string, 0, len(matches))
+      for _, m := range matches {
+        names = append(names, filepath.Base(m))
+      }
+      return "", fmt.Errorf(
+        "@ttsc/strip: multiple strip config files found in %s (%s); "+
+          "set \"configFile\" explicitly in the tsconfig plugin entry",
+        dir, strings.Join(names, ", "),
+      )
+    }
+    if len(matches) == 1 {
+      return matches[0], nil
+    }
+    parent := filepath.Dir(dir)
+    if parent == dir {
+      return "", nil
+    }
+    dir = parent
+  }
+}
+
+// stripDiscoveryBaseDir returns the directory from which auto-discovery walks
+// upward. Prefers the tsconfig directory over cwd so nested package configs are
+// found relative to the tsconfig that triggered the strip run.
+func stripDiscoveryBaseDir(cwd, tsconfigPath string) string {
+  if tsconfigPath != "" {
+    resolved := tsconfigPath
+    if !filepath.IsAbs(resolved) {
+      resolved = filepath.Join(cwd, resolved)
+    }
+    return filepath.Dir(resolved)
+  }
+  return cwd
+}
+
+// resolveStripConfigFilePath resolves a user-supplied config path to an
+// absolute path. Absolute paths are returned unchanged; relative paths are
+// joined to the tsconfig directory (or cwd when no tsconfig is set).
+func resolveStripConfigFilePath(configPath, cwd, tsconfigPath string) string {
+  if filepath.IsAbs(configPath) {
+    return configPath
+  }
+  return filepath.Join(stripDiscoveryBaseDir(cwd, tsconfigPath), configPath)
+}
+
+// loadStripConfigFile loads and deserializes a strip config file at location.
+// The format is determined by extension: .json is parsed natively; .js/.cjs/.mjs
+// run through a Node subprocess; .ts/.cts/.mts run through ttsx.
+func loadStripConfigFile(location string) (any, error) {
+  ext := strings.ToLower(filepath.Ext(location))
+  switch ext {
+  case ".json":
+    return loadStripJSONConfigFile(location)
+  case ".js", ".cjs", ".mjs":
+    return loadStripScriptConfigFile(location)
+  case ".ts", ".cts", ".mts":
+    return loadStripTypeScriptConfigFile(location)
+  default:
+    return nil, fmt.Errorf("@ttsc/strip: unsupported config file extension %q for %s", ext, location)
+  }
+}
+
+// loadStripJSONConfigFile reads and JSON-parses a strip config file. A leading
+// UTF-8 BOM is stripped before parsing so files saved by Windows editors are
+// accepted.
+func loadStripJSONConfigFile(location string) (any, error) {
+  body, err := os.ReadFile(location)
+  if err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: read config file %s: %w", location, err)
+  }
+  body = bytes.TrimPrefix(body, []byte{0xEF, 0xBB, 0xBF})
+  var out any
+  if err := json.Unmarshal(body, &out); err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: parse config file %s: %w", location, err)
+  }
+  return out, nil
+}
+
+// stripScriptLoaderSource is the inline Node.js script used by
+// loadStripScriptConfigFile to evaluate a .js/.cjs/.mjs strip config and
+// serialize the result to stdout as JSON.
+const stripScriptLoaderSource = `
+const { pathToFileURL } = require("node:url");
+
+(async () => {
+  const mod = await import(pathToFileURL(process.argv[1]).href);
+  let current = mod;
+  for (let i = 0; i < 8; i++) {
+    if (current !== null && typeof current === "object" && Object.prototype.hasOwnProperty.call(current, "default")) {
+      current = current.default;
+      continue;
+    }
+    break;
+  }
+  const value = typeof current === "function" ? await current() : current;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("strip config file must export an object");
+  }
+  process.stdout.write(JSON.stringify(value));
+})().catch((error) => {
+  process.stderr.write(error && error.stack ? error.stack : String(error));
+  process.exit(1);
+});
+`
+
+// loadStripScriptConfigFile evaluates a .js/.cjs/.mjs config file by running a
+// Node subprocess that dynamic-imports the file, resolves the default export,
+// and serializes the result as JSON to stdout.
+func loadStripScriptConfigFile(location string) (any, error) {
+  node := os.Getenv("TTSC_NODE_BINARY")
+  if node == "" {
+    node = "node"
+  }
+  ctx, cancel := context.WithTimeout(context.Background(), configLoaderTimeout)
+  defer cancel()
+  cmd := exec.CommandContext(ctx, node, "-e", stripScriptLoaderSource, location)
+  cmd.Env = stripNodeConfigLoaderEnv(location)
+  output, err := cmd.Output()
+  if err != nil {
+    if ctx.Err() == context.DeadlineExceeded {
+      return nil, fmt.Errorf("@ttsc/strip: load config file %s: timed out after %s", location, configLoaderTimeout)
+    }
+    stderr := ""
+    if exit, ok := err.(*exec.ExitError); ok {
+      stderr = strings.TrimSpace(string(exit.Stderr))
+    }
+    if stderr != "" {
+      return nil, fmt.Errorf("@ttsc/strip: load config file %s: %s", location, stderr)
+    }
+    return nil, fmt.Errorf("@ttsc/strip: load config file %s: %w", location, err)
+  }
+  var out any
+  if err := json.Unmarshal(output, &out); err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: parse config file %s output: %w", location, err)
+  }
+  return out, nil
+}
+
+// stripTypeScriptLoaderSource returns the TypeScript source of the ephemeral
+// loader script that ttsx executes to evaluate a TypeScript strip config file.
+// importLiteral must be a JSON-encoded relative import path (e.g.
+// `"./strip.config.ts"`) produced by json.Marshal.
+func stripTypeScriptLoaderSource(importLiteral string) string {
+  return fmt.Sprintf(`import * as importedConfig from %s;
+
+declare const process: {
+  stdout: { write(value: string): void };
+  stderr: { write(value: string): void };
+  exit(code?: number): never;
+};
+
+try {
+  let current: unknown = importedConfig;
+  for (let i = 0; i < 8; i++) {
+    if (current !== null && typeof current === "object" && Object.prototype.hasOwnProperty.call(current as Record<string, unknown>, "default")) {
+      current = (current as Record<string, unknown>).default;
+      continue;
+    }
+    break;
+  }
+  if (typeof current === "function") {
+    current = await (current as () => unknown | Promise<unknown>)();
+  }
+  if (current === null || typeof current !== "object" || Array.isArray(current)) {
+    throw new Error("strip config file must export an object");
+  }
+  process.stdout.write(JSON.stringify(current));
+} catch (error) {
+  process.stderr.write(error instanceof Error && error.stack ? error.stack : String(error));
+  process.exit(1);
+}
+`, importLiteral)
+}
+
+// loadStripTypeScriptConfigFile evaluates a .ts/.cts/.mts config file by writing
+// an ephemeral loader script and tsconfig into a temp directory, symlinking the
+// nearest node_modules, then running ttsx with a configLoaderTimeout deadline.
+//
+// The ttsx build runs with `--no-plugins`: the loader only needs to
+// type-check and execute the strip config file, so loading the host
+// project's transform/check plugins would be wasteful and could fail the
+// build against this deliberately lenient loader tsconfig.
+func loadStripTypeScriptConfigFile(location string) (any, error) {
+  tempDir, err := os.MkdirTemp("", "ttsc-strip-config-")
+  if err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: create config loader tempdir: %w", err)
+  }
+  defer os.RemoveAll(tempDir)
+
+  if err := stripLinkNearestNodeModules(tempDir, filepath.Dir(location)); err != nil {
+    return nil, err
+  }
+
+  loader := filepath.Join(tempDir, "loader.mts")
+  tsconfig := filepath.Join(tempDir, "tsconfig.json")
+  importSpecifier, err := stripRelativeImportSpecifier(tempDir, location)
+  if err != nil {
+    return nil, err
+  }
+  importLiteral, err := json.Marshal(importSpecifier)
+  if err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: encode config import %s: %w", location, err)
+  }
+  if err := os.WriteFile(loader, []byte(stripTypeScriptLoaderSource(string(importLiteral))), 0o644); err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: write config loader: %w", err)
+  }
+  if err := os.WriteFile(tsconfig, []byte(stripTypeScriptLoaderTsconfig(loader, location, tempDir)), 0o644); err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: write config loader tsconfig: %w", err)
+  }
+
+  args := []string{
+    "--project", tsconfig,
+    "--cwd", tempDir,
+    "--cache-dir", filepath.Join(tempDir, "cache"),
+    "--no-plugins",
+  }
+  if tsgo := os.Getenv("TTSC_TSGO_BINARY"); tsgo != "" {
+    args = append(args, "--binary", tsgo)
+  }
+  args = append(args, loader)
+
+  ctx, cancel := context.WithTimeout(context.Background(), configLoaderTimeout)
+  defer cancel()
+  cmd := stripTtsxCommandContext(ctx, args...)
+  cmd.Env = stripNodeConfigLoaderEnv(location)
+  output, err := cmd.Output()
+  if err != nil {
+    if ctx.Err() == context.DeadlineExceeded {
+      return nil, fmt.Errorf("@ttsc/strip: load TypeScript config file %s: timed out after %s", location, configLoaderTimeout)
+    }
+    stderr := ""
+    if exit, ok := err.(*exec.ExitError); ok {
+      stderr = strings.TrimSpace(string(exit.Stderr))
+    }
+    if stderr != "" {
+      return nil, fmt.Errorf("@ttsc/strip: load TypeScript config file %s: %s", location, stderr)
+    }
+    return nil, fmt.Errorf("@ttsc/strip: load TypeScript config file %s: %w", location, err)
+  }
+  var out any
+  if err := json.Unmarshal(output, &out); err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: parse TypeScript config file %s output: %w", location, err)
+  }
+  return out, nil
+}
+
+// stripTypeScriptLoaderTsconfig generates the JSON content of the ephemeral
+// tsconfig used by the loader script.
+func stripTypeScriptLoaderTsconfig(loader, location, outDir string) string {
+  content := map[string]any{
+    "compilerOptions": map[string]any{
+      "allowImportingTsExtensions":      true,
+      "allowJs":                         true,
+      "checkJs":                         false,
+      "module":                          "ESNext",
+      "moduleResolution":                "bundler",
+      "noImplicitAny":                   false,
+      "outDir":                          filepath.ToSlash(filepath.Join(outDir, "out")),
+      "rewriteRelativeImportExtensions": true,
+      "rootDir":                         "/",
+      "skipLibCheck":                    true,
+      "strict":                          false,
+      "target":                          "ES2022",
+    },
+    "files": []string{
+      filepath.ToSlash(loader),
+      filepath.ToSlash(location),
+    },
+  }
+  body, err := json.MarshalIndent(content, "", "  ")
+  if err != nil {
+    panic(err)
+  }
+  return string(body)
+}
+
+// stripTtsxCommandContext returns an exec.Cmd that runs ttsx with the given
+// arguments, routing through node when the resolved binary is a script file.
+func stripTtsxCommandContext(ctx context.Context, args ...string) *exec.Cmd {
+  ttsx := os.Getenv("TTSC_TTSX_BINARY")
+  if ttsx == "" {
+    ttsx = "ttsx"
+  }
+  if stripShouldRunThroughNode(ttsx) {
+    node := os.Getenv("TTSC_NODE_BINARY")
+    if node == "" {
+      node = "node"
+    }
+    return exec.CommandContext(ctx, node, append([]string{ttsx}, args...)...)
+  }
+  return exec.CommandContext(ctx, ttsx, args...)
+}
+
+// stripShouldRunThroughNode reports whether the resolved ttsx binary is a
+// script (JS or TS extension) that must be executed via node.
+func stripShouldRunThroughNode(binary string) bool {
+  switch strings.ToLower(filepath.Ext(binary)) {
+  case ".js", ".cjs", ".mjs", ".ts", ".cts", ".mts":
+    return true
+  default:
+    return false
+  }
+}
+
+// stripNodeConfigLoaderEnv builds the environment for a Node.js config-loader
+// subprocess. Prepends the nearest node_modules to NODE_PATH so imports in
+// .js/.cjs/.mjs config files resolve correctly.
+func stripNodeConfigLoaderEnv(location string) []string {
+  env := os.Environ()
+  parts := make([]string, 0, 2)
+  if nodeModules := stripFindNearestNodeModules(filepath.Dir(location)); nodeModules != "" {
+    parts = append(parts, nodeModules)
+  }
+  if existing := os.Getenv("NODE_PATH"); existing != "" {
+    parts = append(parts, existing)
+  }
+  if len(parts) == 0 {
+    return env
+  }
+  return stripSetEnv(env, "NODE_PATH", strings.Join(parts, string(os.PathListSeparator)))
+}
+
+// stripFindNearestNodeModules walks upward from start and returns the first
+// node_modules directory found, or "" when the filesystem root is reached.
+func stripFindNearestNodeModules(start string) string {
+  dir := filepath.Clean(start)
+  for {
+    candidate := filepath.Join(dir, "node_modules")
+    if stat, err := os.Stat(candidate); err == nil && stat.IsDir() {
+      return candidate
+    }
+    parent := filepath.Dir(dir)
+    if parent == dir {
+      return ""
+    }
+    dir = parent
+  }
+}
+
+// stripLinkNearestNodeModules creates a node_modules symlink (or Windows
+// junction) inside tempDir pointing at the nearest node_modules upward from
+// sourceDir. No-op when no node_modules is found.
+func stripLinkNearestNodeModules(tempDir, sourceDir string) error {
+  nodeModules := stripFindNearestNodeModules(sourceDir)
+  if nodeModules == "" {
+    return nil
+  }
+  link := filepath.Join(tempDir, "node_modules")
+  err := os.Symlink(nodeModules, link)
+  if err == nil {
+    return nil
+  }
+  if runtime.GOOS == "windows" {
+    jerr := stripCreateWindowsJunction(link, nodeModules)
+    if jerr == nil {
+      return nil
+    }
+    err = fmt.Errorf("%w (junction fallback: %v)", err, jerr)
+  }
+  return fmt.Errorf("@ttsc/strip: link config node_modules %s: %w", nodeModules, err)
+}
+
+// stripCreateWindowsJunction creates a directory junction on Windows.
+func stripCreateWindowsJunction(link, target string) error {
+  cmd := exec.Command("cmd", "/c", "mklink", "/J", link, target)
+  if out, err := cmd.CombinedOutput(); err != nil {
+    return fmt.Errorf("mklink /J failed: %v: %s", err, strings.TrimSpace(string(out)))
+  }
+  return nil
+}
+
+// stripRelativeImportSpecifier computes the ESM import specifier for location
+// relative to fromDir, always prefixed with "./" or "../".
+func stripRelativeImportSpecifier(fromDir, location string) (string, error) {
+  relative, err := filepath.Rel(fromDir, location)
+  if err != nil {
+    return "", fmt.Errorf("@ttsc/strip: resolve relative config import %s: %w", location, err)
+  }
+  relative = filepath.ToSlash(relative)
+  if strings.HasPrefix(relative, "../") || strings.HasPrefix(relative, "./") {
+    return relative, nil
+  }
+  return "./" + relative, nil
+}
+
+// stripSetEnv updates an existing key=value entry in env (in-place) or appends
+// a new one.
+func stripSetEnv(env []string, key, value string) []string {
+  prefix := key + "="
+  for i, entry := range env {
+    if strings.HasPrefix(entry, prefix) {
+      env[i] = prefix + value
+      return env
+    }
+  }
+  return append(env, prefix+value)
+}

package/driver/strip.go

@@ -1,268 +1,314 @@
 package strip
 
 import (
-	"fmt"
-	"strings"
+  "fmt"
+  "strings"
 
-	shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimast "github.com/microsoft/typescript-go/shim/ast"
 
-	"github.com/samchon/ttsc/packages/ttsc/driver"
+  "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
 func init() {
-	driver.RegisterPlugin(plugin{})
+  driver.RegisterPlugin(plugin{})
 }
 
+// plugin implements driver.ProgramPlugin for @ttsc/strip.
 type plugin struct{}
 
+// ApplyProgram strips configured call expressions and debugger statements from
+// every source file in the program.
 func (plugin) ApplyProgram(prog *driver.Program, ctx driver.PluginContext) error {
-	rewriter, err := parseStrip(ctx.Entry.Config)
-	if err != nil {
-		return err
-	}
-	for _, file := range prog.SourceFiles() {
-		rewriter.apply(file)
-	}
-	return nil
+  config, err := loadStripConfigMap(ctx.Entry.Config, ctx.Cwd, ctx.Tsconfig)
+  if err != nil {
+    return err
+  }
+  rewriter, err := parseStrip(config)
+  if err != nil {
+    return err
+  }
+  for _, file := range prog.SourceFiles() {
+    rewriter.apply(file)
+  }
+  return nil
 }
 
+// stripRewriter holds the resolved strip configuration for a single build.
 type stripRewriter struct {
-	calls         []callPattern
-	stripDebugger bool
+  calls         []callPattern
+  stripDebugger bool
 }
 
+// callPattern represents a parsed call-expression stripping rule such as
+// "console.log" (exact) or "assert.*" (wildcard prefix).
 type callPattern struct {
-	parts    []string
-	wildcard bool
+  parts    []string
+  wildcard bool
 }
 
+// parseStrip builds a stripRewriter from the plugin config map. When neither
+// "calls" nor "statements" is present the default configuration is applied:
+// strip console.log, console.debug, assert.*, and debugger statements.
 func parseStrip(config map[string]any) (*stripRewriter, error) {
-	_, hasCalls := config["calls"]
-	_, hasStatements := config["statements"]
-	if !hasCalls && !hasStatements {
-		config = map[string]any{
-			"calls":      []any{"console.log", "console.debug", "assert.*"},
-			"statements": []any{"debugger"},
-		}
-	}
-	calls, err := stringArrayConfig(config, "calls")
-	if err != nil {
-		return nil, fmt.Errorf("@ttsc/strip: %w", err)
-	}
-	statements, err := stringArrayConfig(config, "statements")
-	if err != nil {
-		return nil, fmt.Errorf("@ttsc/strip: %w", err)
-	}
-	out := &stripRewriter{}
-	for _, call := range calls {
-		pattern, err := parseCallPattern(call)
-		if err != nil {
-			return nil, fmt.Errorf("@ttsc/strip: %w", err)
-		}
-		out.calls = append(out.calls, pattern)
-	}
-	for _, statement := range statements {
-		switch statement {
-		case "debugger":
-			out.stripDebugger = true
-		default:
-			return nil, fmt.Errorf("@ttsc/strip: unsupported statement pattern %q", statement)
-		}
-	}
-	return out, nil
+  _, hasCalls := config["calls"]
+  _, hasStatements := config["statements"]
+  if !hasCalls && !hasStatements {
+    config = map[string]any{
+      "calls":      []any{"console.log", "console.debug", "assert.*"},
+      "statements": []any{"debugger"},
+    }
+  }
+  calls, err := stringArrayConfig(config, "calls")
+  if err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: %w", err)
+  }
+  statements, err := stringArrayConfig(config, "statements")
+  if err != nil {
+    return nil, fmt.Errorf("@ttsc/strip: %w", err)
+  }
+  out := &stripRewriter{}
+  for _, call := range calls {
+    pattern, err := parseCallPattern(call)
+    if err != nil {
+      return nil, fmt.Errorf("@ttsc/strip: %w", err)
+    }
+    out.calls = append(out.calls, pattern)
+  }
+  for _, statement := range statements {
+    switch statement {
+    case "debugger":
+      out.stripDebugger = true
+    default:
+      return nil, fmt.Errorf("@ttsc/strip: unsupported statement pattern %q", statement)
+    }
+  }
+  return out, nil
 }
 
+// apply removes matching statements from file's top-level statement list.
 func (s *stripRewriter) apply(file *shimast.SourceFile) {
-	if s == nil || file == nil || (len(s.calls) == 0 && !s.stripDebugger) {
-		return
-	}
-	filterStatements(file.Statements, s)
+  if s == nil || file == nil || (len(s.calls) == 0 && !s.stripDebugger) {
+    return
+  }
+  filterStatements(file.Statements, s)
 }
 
+// filterStatements removes stripped statements from list in-place, preserving
+// order. Children of retained statements are recursively filtered.
 func filterStatements(list *shimast.NodeList, strip *stripRewriter) {
-	if list == nil || len(list.Nodes) == 0 {
-		return
-	}
-	out := make([]*shimast.Node, 0, len(list.Nodes))
-	for _, stmt := range list.Nodes {
-		if shouldStripStatement(stmt, strip) {
-			continue
-		}
-		filterChildStatements(stmt, strip)
-		out = append(out, stmt)
-	}
-	list.Nodes = out
+  if list == nil || len(list.Nodes) == 0 {
+    return
+  }
+  out := make([]*shimast.Node, 0, len(list.Nodes))
+  for _, stmt := range list.Nodes {
+    if shouldStripStatement(stmt, strip) {
+      continue
+    }
+    filterChildStatements(stmt, strip)
+    out = append(out, stmt)
+  }
+  list.Nodes = out
 }
 
+// filterChildStatements recurses into node's children, filtering embedded
+// single-statement bodies (if, while, for, etc.) and nested statement lists.
 func filterChildStatements(node *shimast.Node, strip *stripRewriter) {
-	if node == nil {
-		return
-	}
-	filterEmbeddedStatements(node, strip)
-	if node.CanHaveStatements() {
-		filterStatements(node.StatementList(), strip)
-	}
-	node.ForEachChild(func(child *shimast.Node) bool {
-		filterChildStatements(child, strip)
-		return false
-	})
+  if node == nil {
+    return
+  }
+  filterEmbeddedStatements(node, strip)
+  if node.CanHaveStatements() {
+    filterStatements(node.StatementList(), strip)
+  }
+  node.ForEachChild(func(child *shimast.Node) bool {
+    filterChildStatements(child, strip)
+    return false
+  })
 }
 
+// filterEmbeddedStatements handles statement nodes that embed a single child
+// statement (if/else, do, while, for, with, labeled). A stripped child is
+// replaced with an empty synthesized statement to preserve the AST shape.
 func filterEmbeddedStatements(node *shimast.Node, strip *stripRewriter) {
-	switch node.Kind {
-	case shimast.KindIfStatement:
-		stmt := node.AsIfStatement()
-		stmt.ThenStatement = filterEmbeddedStatement(stmt.ThenStatement, strip)
-		stmt.ElseStatement = filterEmbeddedStatement(stmt.ElseStatement, strip)
-	case shimast.KindDoStatement:
-		stmt := node.AsDoStatement()
-		stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
-	case shimast.KindWhileStatement:
-		stmt := node.AsWhileStatement()
-		stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
-	case shimast.KindForStatement:
-		stmt := node.AsForStatement()
-		stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
-	case shimast.KindForInStatement, shimast.KindForOfStatement:
-		stmt := node.AsForInOrOfStatement()
-		stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
-	case shimast.KindWithStatement:
-		stmt := node.AsWithStatement()
-		stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
-	case shimast.KindLabeledStatement:
-		stmt := node.AsLabeledStatement()
-		stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
-	}
+  switch node.Kind {
+  case shimast.KindIfStatement:
+    stmt := node.AsIfStatement()
+    stmt.ThenStatement = filterEmbeddedStatement(stmt.ThenStatement, strip)
+    stmt.ElseStatement = filterEmbeddedStatement(stmt.ElseStatement, strip)
+  case shimast.KindDoStatement:
+    stmt := node.AsDoStatement()
+    stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
+  case shimast.KindWhileStatement:
+    stmt := node.AsWhileStatement()
+    stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
+  case shimast.KindForStatement:
+    stmt := node.AsForStatement()
+    stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
+  case shimast.KindForInStatement, shimast.KindForOfStatement:
+    stmt := node.AsForInOrOfStatement()
+    stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
+  case shimast.KindWithStatement:
+    stmt := node.AsWithStatement()
+    stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
+  case shimast.KindLabeledStatement:
+    stmt := node.AsLabeledStatement()
+    stmt.Statement = filterEmbeddedStatement(stmt.Statement, strip)
+  }
 }
 
+// filterEmbeddedStatement strips or recurses into a single embedded statement.
+// Returns an empty synthesized statement when stmt is to be stripped, preserving
+// the original source location for downstream source-map accuracy.
 func filterEmbeddedStatement(stmt *shimast.Statement, strip *stripRewriter) *shimast.Statement {
-	if stmt == nil {
-		return nil
-	}
-	if shouldStripStatement(stmt, strip) {
-		return emptyStatement(stmt)
-	}
-	filterChildStatements(stmt, strip)
-	return stmt
+  if stmt == nil {
+    return nil
+  }
+  if shouldStripStatement(stmt, strip) {
+    return emptyStatement(stmt)
+  }
+  filterChildStatements(stmt, strip)
+  return stmt
 }
 
+// emptyStatement creates a synthesized empty statement (";") that inherits
+// original's source location, used as a no-op placeholder after stripping.
 func emptyStatement(original *shimast.Node) *shimast.Statement {
-	empty := shimast.NewNodeFactory(shimast.NodeFactoryHooks{}).NewEmptyStatement()
-	empty.Flags |= shimast.NodeFlagsSynthesized
-	if original != nil {
-		empty.Loc = original.Loc
-	}
-	return empty
+  empty := shimast.NewNodeFactory(shimast.NodeFactoryHooks{}).NewEmptyStatement()
+  empty.Flags |= shimast.NodeFlagsSynthesized
+  if original != nil {
+    empty.Loc = original.Loc
+  }
+  return empty
 }
 
+// shouldStripStatement reports whether node should be removed based on the
+// current strip configuration. Only debugger and expression statements are
+// candidates; all other statement kinds are retained.
 func shouldStripStatement(node *shimast.Node, strip *stripRewriter) bool {
-	if node == nil {
-		return false
-	}
-	switch node.Kind {
-	case shimast.KindDebuggerStatement:
-		return strip.stripDebugger
-	case shimast.KindExpressionStatement:
-		expr := node.AsExpressionStatement().Expression
-		name, ok := callExpressionName(expr)
-		return ok && strip.matchesCall(name)
-	default:
-		return false
-	}
+  if node == nil {
+    return false
+  }
+  switch node.Kind {
+  case shimast.KindDebuggerStatement:
+    return strip.stripDebugger
+  case shimast.KindExpressionStatement:
+    expr := node.AsExpressionStatement().Expression
+    name, ok := callExpressionName(expr)
+    return ok && strip.matchesCall(name)
+  default:
+    return false
+  }
 }
 
+// matchesCall reports whether name matches any of the configured call patterns.
 func (s *stripRewriter) matchesCall(name string) bool {
-	for _, pattern := range s.calls {
-		if pattern.matches(name) {
-			return true
-		}
-	}
-	return false
+  for _, pattern := range s.calls {
+    if pattern.matches(name) {
+      return true
+    }
+  }
+  return false
 }
 
+// parseCallPattern parses a dot-separated call pattern string such as
+// "console.log" or "assert.*". A wildcard ("*") is only allowed as the
+// final segment. Empty segments are rejected.
 func parseCallPattern(text string) (callPattern, error) {
-	parts := strings.Split(text, ".")
-	for i, part := range parts {
-		if part == "" {
-			return callPattern{}, fmt.Errorf("invalid call pattern %q", text)
-		}
-		if part == "*" && i != len(parts)-1 {
-			return callPattern{}, fmt.Errorf("wildcard is only supported at the end of call pattern %q", text)
-		}
-	}
-	wildcard := parts[len(parts)-1] == "*"
-	if wildcard {
-		parts = parts[:len(parts)-1]
-	}
-	return callPattern{parts: parts, wildcard: wildcard}, nil
+  parts := strings.Split(text, ".")
+  for i, part := range parts {
+    if part == "" {
+      return callPattern{}, fmt.Errorf("invalid call pattern %q", text)
+    }
+    if part == "*" && i != len(parts)-1 {
+      return callPattern{}, fmt.Errorf("wildcard is only supported at the end of call pattern %q", text)
+    }
+  }
+  wildcard := parts[len(parts)-1] == "*"
+  if wildcard {
+    parts = parts[:len(parts)-1]
+  }
+  return callPattern{parts: parts, wildcard: wildcard}, nil
 }
 
+// matches reports whether a dotted call name (e.g. "console.log") matches
+// the pattern. Wildcard patterns require at least one extra segment beyond
+// the pattern prefix.
 func (p callPattern) matches(name string) bool {
-	parts := strings.Split(name, ".")
-	if p.wildcard {
-		if len(parts) <= len(p.parts) {
-			return false
-		}
-		return equalStringSlices(parts[:len(p.parts)], p.parts)
-	}
-	return equalStringSlices(parts, p.parts)
+  parts := strings.Split(name, ".")
+  if p.wildcard {
+    if len(parts) <= len(p.parts) {
+      return false
+    }
+    return equalStringSlices(parts[:len(p.parts)], p.parts)
+  }
+  return equalStringSlices(parts, p.parts)
 }
 
+// callExpressionName extracts the dotted callee name from a call expression
+// node, e.g. "console.log" from `console.log(...)`. Returns ("", false) when
+// expr is not a call expression or the callee is not a dotted identifier chain.
 func callExpressionName(expr *shimast.Node) (string, bool) {
-	if expr == nil || expr.Kind != shimast.KindCallExpression {
-		return "", false
-	}
-	call := expr.AsCallExpression()
-	return dottedName(call.Expression)
+  if expr == nil || expr.Kind != shimast.KindCallExpression {
+    return "", false
+  }
+  call := expr.AsCallExpression()
+  return dottedName(call.Expression)
 }
 
+// dottedName recursively extracts a dot-joined identifier chain from an
+// expression node. Returns ("", false) for any non-identifier, non-property-
+// access node.
 func dottedName(expr *shimast.Node) (string, bool) {
-	if expr == nil {
-		return "", false
-	}
-	switch expr.Kind {
-	case shimast.KindIdentifier:
-		return expr.Text(), true
-	case shimast.KindPropertyAccessExpression:
-		prop := expr.AsPropertyAccessExpression()
-		left, ok := dottedName(prop.Expression)
-		if !ok || prop.Name() == nil {
-			return "", false
-		}
-		return left + "." + prop.Name().Text(), true
-	default:
-		return "", false
-	}
+  if expr == nil {
+    return "", false
+  }
+  switch expr.Kind {
+  case shimast.KindIdentifier:
+    return expr.Text(), true
+  case shimast.KindPropertyAccessExpression:
+    prop := expr.AsPropertyAccessExpression()
+    left, ok := dottedName(prop.Expression)
+    if !ok || prop.Name() == nil {
+      return "", false
+    }
+    return left + "." + prop.Name().Text(), true
+  default:
+    return "", false
+  }
 }
 
+// stringArrayConfig reads a string array from config[key]. Returns nil when the
+// key is absent. Returns an error when the value is not an array of non-empty strings.
 func stringArrayConfig(config map[string]any, key string) ([]string, error) {
-	raw, ok := config[key]
-	if !ok || raw == nil {
-		return nil, nil
-	}
-	values, ok := raw.([]any)
-	if !ok {
-		return nil, fmt.Errorf("%q must be an array of strings", key)
-	}
-	out := make([]string, 0, len(values))
-	for i, value := range values {
-		text, ok := value.(string)
-		if !ok || strings.TrimSpace(text) == "" {
-			return nil, fmt.Errorf("%q[%d] must be a non-empty string", key, i)
-		}
-		out = append(out, text)
-	}
-	return out, nil
+  raw, ok := config[key]
+  if !ok || raw == nil {
+    return nil, nil
+  }
+  values, ok := raw.([]any)
+  if !ok {
+    return nil, fmt.Errorf("%q must be an array of strings", key)
+  }
+  out := make([]string, 0, len(values))
+  for i, value := range values {
+    text, ok := value.(string)
+    if !ok || strings.TrimSpace(text) == "" {
+      return nil, fmt.Errorf("%q[%d] must be a non-empty string", key, i)
+    }
+    out = append(out, text)
+  }
+  return out, nil
 }
 
+// equalStringSlices reports whether left and right contain the same strings in
+// the same order.
 func equalStringSlices(left, right []string) bool {
-	if len(left) != len(right) {
-		return false
-	}
-	for i := range left {
-		if left[i] != right[i] {
-			return false
-		}
-	}
-	return true
+  if len(left) != len(right) {
+    return false
+  }
+  for i := range left {
+    if left[i] != right[i] {
+      return false
+    }
+  }
+  return true
 }

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@ttsc/strip",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "First-party ttsc plugin that removes configured calls and statements from emitted JavaScript.",
   "main": "src/index.cjs",
+  "types": "src/index.d.ts",
   "exports": {
-    ".": "./src/index.cjs",
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.cjs"
+    },
     "./package.json": "./package.json"
   },
   "keywords": [
@@ -21,8 +25,10 @@
   },
   "files": [
     "README.md",
+    "driver/config.go",
     "driver/strip.go",
     "src/index.cjs",
+    "src/index.d.ts",
     "go.mod",
     "plugin/main.go",
     "plugin/strip.go"

package/src/index.cjs

@@ -3,7 +3,31 @@
 
 const path = require("node:path");
 
-module.exports = function createTtscStrip() {
+// Keys from the tsconfig plugin entry that @ttsc/strip accepts. All other keys
+// are rejected so that stale inline options (calls, statements) surface as a
+// clear error rather than silently falling back to defaults.
+const ALLOWED_TSCONFIG_KEYS = new Set([
+  "configFile",
+  "enabled",
+  "name",
+  "stage",
+  "transform",
+]);
+
+module.exports = function createTtscStrip(context) {
+  const plugin =
+    context && typeof context === "object" && context.plugin != null
+      ? context.plugin
+      : {};
+  for (const key of Object.keys(plugin)) {
+    if (!ALLOWED_TSCONFIG_KEYS.has(key)) {
+      throw new Error(
+        `@ttsc/strip: tsconfig plugin entry contains unsupported key ${JSON.stringify(key)}; ` +
+          `strip configuration must be supplied via a strip.config.* file ` +
+          `(use the "configFile" key to point at a custom path)`,
+      );
+    }
+  }
   return {
     name: "@ttsc/strip",
     source: path.resolve(__dirname, "..", "driver"),

package/src/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Plugin descriptor factory consumed by ttsc's package discovery.
+ *
+ * `@ttsc/strip` is configured through a `strip.config.*` file, never through
+ * the factory context — the factory only returns the native descriptor.
+ *
+ * @internal
+ */
+declare function createTtscStrip(context: unknown): {
+  name: string;
+  source: string;
+  stage: "transform";
+};
+
+declare namespace createTtscStrip {
+  /**
+   * Standalone `strip.config.{ts,cts,mts,js,cjs,mjs,json}` file shape consumed
+   * by `@ttsc/strip`.
+   *
+   * Both keys are optional. The built-in defaults (`calls: ["console.log",
+   * "console.debug", "assert.*"]`, `statements: ["debugger"]`) apply only when
+   * *both* keys are omitted; declaring either key replaces both defaults with
+   * exactly what the file lists.
+   */
+  export interface ITtscStripConfig {
+    /**
+     * Statement-level call patterns to remove, written as dotted names. A
+     * trailing `.*` wildcard matches any final property — e.g. `"assert.*"`
+     * matches `assert.equal`, `assert.deepStrictEqual`, …
+     */
+    calls?: readonly string[];
+
+    /** Bare statement kinds to remove. Currently only `"debugger"` is supported. */
+    statements?: readonly string[];
+  }
+}
+
+export = createTtscStrip;