@ttsc/banner 0.7.3 → 0.8.0-dev.20260506

package/README.md

@@ -9,7 +9,7 @@
 [![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://github.com/samchon/ttsc/tree/master/docs)
 [![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.
+`@ttsc/banner` adds a fixed `@packageDocumentation` JSDoc banner by inserting a source preamble before TypeScript-Go parses the project.
 
 ## Setup
 
@@ -27,10 +27,10 @@ Open your project's `tsconfig.json`, then add this entry under `compilerOptions.
     "plugins": [
       {
         "transform": "@ttsc/banner",
-        "banner": "/*! @license MIT (c) 2026 Acme */"
-      }
-    ]
-  }
+        "banner": "License MIT (c) 2026 Acme",
+      },
+    ],
+  },
 }
 ```
 
@@ -40,7 +40,7 @@ Run your normal `ttsc` command:
 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.
+The plugin formats every banner line inside a JSDoc block and adds `@packageDocumentation`. The banner follows TypeScript's normal comment emit policy, so `removeComments: true` removes it.
 
 ## Notes
 
@@ -53,11 +53,11 @@ The banner is written to emitted `.js`, `.mjs`, `.cjs`, `.d.ts`, `.d.mts`, and `
       // Keep lint first.
       { "transform": "@ttsc/lint", "config": { "no-var": "error" } },
 
-      // Output plugins run after emit, in order.
-      { "transform": "@ttsc/banner", "banner": "/*! @license MIT */" },
+      // First-party utilities use their documented transform order.
+      { "transform": "@ttsc/banner", "banner": "License MIT" },
       { "transform": "@ttsc/paths" },
-      { "transform": "@ttsc/strip", "calls": ["console.log"] }
-    ]
-  }
+      { "transform": "@ttsc/strip", "calls": ["console.log"] },
+    ],
+  },
 }
 ```

package/go.mod

@@ -1,3 +1,5 @@
 module github.com/samchon/ttsc/packages/banner
 
 go 1.26
+
+require github.com/samchon/ttsc/packages/ttsc v0.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ttsc/banner",
-  "version": "0.7.3",
-  "description": "First-party ttsc plugin that prepends a banner comment to emitted files.",
+  "version": "0.8.0-dev.20260506",
+  "description": "First-party ttsc plugin that adds package-documentation JSDoc banners during emit.",
   "main": "src/index.cjs",
   "exports": {
     ".": "./src/index.cjs",

package/plugin/banner.go

@@ -1,148 +1,3 @@
-// Output transformer for `@ttsc/banner`.
-//
-// The transformer prepends a configured banner to JavaScript and declaration
-// outputs. Source maps and tsbuildinfo files are excluded because prepending
-// human-readable text would corrupt their structured content.
 package main
 
-import (
-  "encoding/json"
-  "flag"
-  "fmt"
-  "os"
-  "path/filepath"
-  "strings"
-)
-
-type pluginEntry struct {
-  // Config carries the original compilerOptions.plugins[] config object. The
-  // sidecar scans the ordered descriptor list and consumes only its own entry.
-  Config map[string]any `json:"config"`
-  Name   string         `json:"name"`
-  Stage  string         `json:"stage"`
-}
-
-// RunOutput implements the output-stage sidecar command. The host passes an
-// emitted file path, the serialized plugin manifest, and an optional alternate
-// output path.
-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("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
-  }
-  // The operation is idempotent so watch builds do not duplicate banners when
-  // the same output file is seen more than once.
-  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") {
-    // The banner is line-oriented; forcing a trailing newline keeps the first
-    // emitted statement on its own line.
-    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.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")
-}
+// Banner transform logic lives in github.com/samchon/ttsc/packages/ttsc/utility.

package/plugin/main.go

@@ -1,14 +1,11 @@
 // Native sidecar entrypoint for `@ttsc/banner`.
-//
-// The command follows the ttsc plugin sidecar protocol: `check` validates the
-// plugin can run, `output` receives one emitted file and may rewrite it, and
-// `version` reports the sidecar version. All project semantics stay in the
-// host; this binary only prepends configured banner text.
 package main
 
 import (
   "fmt"
   "os"
+
+  "github.com/samchon/ttsc/packages/ttsc/utility"
 )
 
 const version = "0.0.1"
@@ -19,18 +16,19 @@ func main() {
 
 func run(args []string) int {
   if len(args) == 0 {
-    fmt.Fprintln(os.Stderr, "@ttsc/banner: command required (expected output|version)")
+    fmt.Fprintln(os.Stderr, "@ttsc/banner: command required (expected build|transform|check|version)")
     return 2
   }
   switch args[0] {
   case "-v", "--version", "version":
     fmt.Fprintf(os.Stdout, "@ttsc/banner %s\n", version)
     return 0
+  case "build":
+    return utility.RunBuild(args[1:])
+  case "transform":
+    return utility.RunTransform(args[1:])
   case "check":
-    // Banner rewriting is output-only; there is no program-wide analysis.
     return 0
-  case "output":
-    return RunOutput(args[1:])
   default:
     fmt.Fprintf(os.Stderr, "@ttsc/banner: unknown command %q\n", args[0])
     return 2

package/src/index.cjs

@@ -7,6 +7,6 @@ module.exports = function createTtscBanner() {
   return {
     name: "@ttsc/banner",
     source: path.resolve(__dirname, "..", "plugin"),
-    stage: "output",
+    stage: "transform",
   };
 };