@ttsc/banner 0.5.0-dev.20260429

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeongho Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# `@ttsc/banner`
+
+![banner of @ttsc/banner](https://raw.githubusercontent.com/samchon/ttsc/refs/heads/master/assets/og.jpg)
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/ttsc/blob/master/LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/@ttsc/banner.svg)](https://www.npmjs.com/package/@ttsc/banner)
+[![NPM Downloads](https://img.shields.io/npm/dm/@ttsc/banner.svg)](https://www.npmjs.com/package/@ttsc/banner)
+[![Build Status](https://github.com/samchon/ttsc/workflows/test/badge.svg)](https://github.com/samchon/ttsc/actions?query=workflow%3Atest)
+[![Discord Badge](https://img.shields.io/badge/discord-samchon-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.gg/E94XhzrUCZ)](https://discord.gg/E94XhzrUCZ)
+
+`@ttsc/banner` prepends a fixed comment to emitted JavaScript and declaration files.
+
+## Setup
+
+Install `ttsc`, TypeScript-Go, and the banner plugin:
+
+```bash
+npm install -D ttsc @typescript/native-preview @ttsc/banner
+```
+
+Open your project's `tsconfig.json`, then add this entry under `compilerOptions.plugins`. If the file already has `compilerOptions`, merge this into the existing object:
+
+```jsonc
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "transform": "@ttsc/banner",
+        "banner": "/*! @license MIT (c) 2026 Acme */"
+      }
+    ]
+  }
+}
+```
+
+Run your normal `ttsc` command:
+
+```bash
+npx ttsc
+```
+
+The banner is written to emitted `.js`, `.mjs`, `.cjs`, `.d.ts`, `.d.mts`, and `.d.cts` files. Source maps and build-info files are left unchanged.
+
+## Notes
+
+`@ttsc/banner` can be used with other `ttsc` plugins:
+
+```jsonc
+{
+  "compilerOptions": {
+    "plugins": [
+      // Keep lint first.
+      { "transform": "@ttsc/lint", "rules": { "no-var": "error" } },
+
+      // Output plugins run after emit, in order.
+      { "transform": "@ttsc/banner", "banner": "/*! @license MIT */" },
+      { "transform": "@ttsc/paths" },
+      { "transform": "@ttsc/strip", "calls": ["console.log"] }
+    ]
+  }
+}
+```

package/go-plugin/banner/banner.go

@@ -0,0 +1,137 @@
+package banner
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const modeBanner = "ttsc-banner"
+
+type pluginEntry struct {
+	Config map[string]any `json:"config"`
+	Mode   string         `json:"mode"`
+	Name   string         `json:"name"`
+}
+
+func RunOutput(args []string) int {
+	fs := flag.NewFlagSet("output", flag.ContinueOnError)
+	fs.SetOutput(os.Stderr)
+	file := fs.String("file", "", "emitted file to transform")
+	out := fs.String("out", "", "write transformed text to this file instead of updating --file")
+	_ = fs.String("cwd", "", "project directory")
+	_ = fs.String("outDir", "", "emit directory override")
+	pluginsJSON := fs.String("plugins-json", "", "ttsc plugin manifest JSON")
+	_ = fs.String("rewrite-mode", modeBanner, "native mode")
+	_ = fs.String("tsconfig", "tsconfig.json", "project tsconfig")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+	if *file == "" {
+		fmt.Fprintln(os.Stderr, "@ttsc/banner: output requires --file")
+		return 2
+	}
+	config, err := findConfig(*pluginsJSON)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return 2
+	}
+	text, err := os.ReadFile(*file)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "@ttsc/banner: read %s: %v\n", *file, err)
+		return 2
+	}
+	patched, err := Apply(*file, string(text), config)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return 2
+	}
+	target := *file
+	if *out != "" {
+		target = *out
+	}
+	if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+		fmt.Fprintf(os.Stderr, "@ttsc/banner: mkdir: %v\n", err)
+		return 2
+	}
+	if err := os.WriteFile(target, []byte(patched), 0o644); err != nil {
+		fmt.Fprintf(os.Stderr, "@ttsc/banner: write %s: %v\n", target, err)
+		return 2
+	}
+	return 0
+}
+
+func Apply(fileName string, text string, config map[string]any) (string, error) {
+	if !isBannerableOutput(fileName) {
+		return text, nil
+	}
+	banner, err := parseBanner(config)
+	if err != nil {
+		return "", err
+	}
+	if strings.HasPrefix(text, banner) {
+		return text, nil
+	}
+	return banner + text, nil
+}
+
+func parseBanner(config map[string]any) (string, error) {
+	raw, ok := config["banner"]
+	if !ok {
+		return "", fmt.Errorf("@ttsc/banner: \"banner\" must be a non-empty string")
+	}
+	text, ok := raw.(string)
+	if !ok || strings.TrimSpace(text) == "" {
+		return "", fmt.Errorf("@ttsc/banner: \"banner\" must be a non-empty string")
+	}
+	if !strings.HasSuffix(text, "\n") {
+		text += "\n"
+	}
+	return text, nil
+}
+
+func findConfig(pluginsJSON string) (map[string]any, error) {
+	if strings.TrimSpace(pluginsJSON) == "" {
+		return nil, fmt.Errorf("@ttsc/banner: missing --plugins-json")
+	}
+	var entries []pluginEntry
+	if err := json.Unmarshal([]byte(pluginsJSON), &entries); err != nil {
+		return nil, fmt.Errorf("@ttsc/banner: invalid --plugins-json: %w", err)
+	}
+	for _, entry := range entries {
+		if entry.Mode == modeBanner || entry.Name == "@ttsc/banner" {
+			if entry.Config == nil {
+				return map[string]any{}, nil
+			}
+			return entry.Config, nil
+		}
+	}
+	return nil, fmt.Errorf("@ttsc/banner: plugin entry not found")
+}
+
+func isBannerableOutput(fileName string) bool {
+	lower := strings.ToLower(fileName)
+	if strings.HasSuffix(lower, ".map") || strings.HasSuffix(lower, ".tsbuildinfo") {
+		return false
+	}
+	return isJavaScriptOutput(fileName) || isDeclarationOutput(fileName)
+}
+
+func isJavaScriptOutput(fileName string) bool {
+	switch strings.ToLower(filepath.Ext(fileName)) {
+	case ".js", ".mjs", ".cjs":
+		return true
+	default:
+		return false
+	}
+}
+
+func isDeclarationOutput(fileName string) bool {
+	lower := strings.ToLower(fileName)
+	return strings.HasSuffix(lower, ".d.ts") ||
+		strings.HasSuffix(lower, ".d.mts") ||
+		strings.HasSuffix(lower, ".d.cts")
+}

package/go-plugin/go.mod

@@ -0,0 +1,3 @@
+module github.com/samchon/ttsc/packages/banner/go-plugin
+
+go 1.26

package/go-plugin/main.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/samchon/ttsc/packages/banner/go-plugin/banner"
+)
+
+const version = "0.0.1"
+
+func main() {
+	os.Exit(run(os.Args[1:]))
+}
+
+func run(args []string) int {
+	if len(args) == 0 {
+		fmt.Fprintln(os.Stderr, "@ttsc/banner: command required (expected output|version)")
+		return 2
+	}
+	switch args[0] {
+	case "-v", "--version", "version":
+		fmt.Fprintf(os.Stdout, "@ttsc/banner %s\n", version)
+		return 0
+	case "check":
+		return 0
+	case "output":
+		return banner.RunOutput(args[1:])
+	default:
+		fmt.Fprintf(os.Stderr, "@ttsc/banner: unknown command %q\n", args[0])
+		return 2
+	}
+}

package/index.cjs

@@ -0,0 +1,18 @@
+// @ts-check
+"use strict";
+
+const path = require("node:path");
+
+module.exports = function createTtscBanner() {
+  return {
+    name: "@ttsc/banner",
+    native: {
+      mode: "ttsc-banner",
+      source: {
+        dir: path.resolve(__dirname, "go-plugin"),
+      },
+      contractVersion: 1,
+      capabilities: ["output"],
+    },
+  };
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ttsc/banner",
+  "version": "0.5.0-dev.20260429",
+  "description": "First-party ttsc plugin that prepends a banner comment to emitted files.",
+  "main": "index.cjs",
+  "exports": {
+    ".": "./index.cjs",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "ttsc",
+    "banner",
+    "typescript",
+    "tsgo"
+  ],
+  "files": [
+    "README.md",
+    "index.cjs",
+    "go-plugin/go.mod",
+    "go-plugin/main.go",
+    "go-plugin/banner"
+  ],
+  "peerDependencies": {
+    "ttsc": "^0.4.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/samchon/ttsc"
+  },
+  "author": "Jeongho Nam",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/samchon/ttsc/issues"
+  },
+  "homepage": "https://github.com/samchon/ttsc/tree/master/packages/banner#readme"
+}