@ttsc/banner 0.8.1 → 0.9.0

package/README.md

@@ -9,17 +9,41 @@
 [![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` adds a fixed `@packageDocumentation` JSDoc banner by inserting a source preamble before TypeScript-Go parses the project.
+`@ttsc/banner` adds a fixed `@packageDocumentation` JSDoc banner to the output.
 
 ## Setup
 
-Install `ttsc`, TypeScript-Go, and the banner plugin:
+Install `ttsc` and TypeScript-Go, then the banner plugin:
 
 ```bash
-npm install -D ttsc @typescript/native-preview @ttsc/banner
+npm install -D ttsc @typescript/native-preview
+npm install -D @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:
+Add `banner.config.ts` next to your project config:
+
+```ts
+// banner.config.ts
+import type { TtscBannerConfig } from "@ttsc/banner";
+
+export default {
+  text: "License MIT (c) 2026 Acme",
+} satisfies TtscBannerConfig;
+```
+
+Run your normal `ttsc` command:
+
+```bash
+npx ttsc
+```
+
+If `@ttsc/banner` is installed and no banner config file can be found, the compile fails.
+
+## Configuration
+
+Use `banner.config.ts` for ordinary projects.
+
+Use `compilerOptions.plugins` only when the project needs a different config file path or inline text:
 
 ```jsonc
 {
@@ -27,37 +51,28 @@ Open your project's `tsconfig.json`, then add this entry under `compilerOptions.
     "plugins": [
       {
         "transform": "@ttsc/banner",
-        "banner": "License MIT (c) 2026 Acme",
+        "config": "./config/banner.config.ts",
       },
     ],
   },
 }
 ```
 
-Run your normal `ttsc` command:
+The explicit `config` path resolves from the selected `tsconfig.json` directory.
 
-```bash
-npx ttsc
-```
-
-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
-
-`@ttsc/banner` can be used with other `ttsc` plugins:
+Existing inline text config remains supported:
 
 ```jsonc
 {
   "compilerOptions": {
     "plugins": [
-      // Keep lint first.
-      { "transform": "@ttsc/lint", "config": { "no-var": "error" } },
-
-      // 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/banner",
+        "text": "License MIT (c) 2026 Acme",
+      },
     ],
   },
 }
 ```
+
+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.

package/lib/index.d.ts

@@ -0,0 +1,15 @@
+import type { ITtscBannerPluginConfig } from "./structures";
+export * from "./structures/index";
+type TtscPluginDescriptor = {
+    name: string;
+    source: string;
+    stage?: "check" | "transform";
+};
+type TtscPluginFactoryContext<TConfig> = {
+    binary: string;
+    cwd: string;
+    plugin: TConfig;
+    projectRoot: string;
+    tsconfig: string;
+};
+export default function createTtscBanner(_context: TtscPluginFactoryContext<ITtscBannerPluginConfig>): TtscPluginDescriptor;

package/lib/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = createTtscBanner;
+const node_path_1 = __importDefault(require("node:path"));
+__exportStar(require("./structures/index"), exports);
+function createTtscBanner(_context) {
+    return {
+        name: "@ttsc/banner",
+        source: node_path_1.default.resolve(__dirname, "..", "plugin"),
+        stage: "transform",
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,0DAA6B;AAI7B,qDAAmC;AAgBnC,0BACE,QAA2D;IAE3D,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC;QAC/C,KAAK,EAAE,WAAW;KACnB,CAAC;AACJ,CAAC"}

package/lib/structures/ITtscBannerPluginConfig.d.ts

@@ -0,0 +1,13 @@
+/** `compilerOptions.plugins[]` entry shape consumed by `@ttsc/banner`. */
+export interface ITtscBannerPluginConfig {
+    /** Set to `false` to keep the entry while disabling this plugin. */
+    enabled?: boolean;
+    /** Plugin module specifier. */
+    transform?: string;
+    /** Inline banner text. */
+    text?: string;
+    /** Path to `banner.config.*`, resolved from the selected tsconfig directory. */
+    config?: string;
+    /** Extra plugin-owned fields are passed through unchanged. */
+    [key: string]: unknown;
+}

package/lib/structures/ITtscBannerPluginConfig.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ITtscBannerPluginConfig.js.map

package/lib/structures/ITtscBannerPluginConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITtscBannerPluginConfig.js","sourceRoot":"","sources":["../../src/structures/ITtscBannerPluginConfig.ts"],"names":[],"mappings":""}

package/lib/structures/TtscBannerConfig.d.ts

@@ -0,0 +1,5 @@
+/** Standalone `banner.config.*` file shape consumed by `@ttsc/banner`. */
+export type TtscBannerConfig = string | {
+    /** Text inserted into the generated `@packageDocumentation` block. */
+    text: string;
+};

package/lib/structures/TtscBannerConfig.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=TtscBannerConfig.js.map

package/lib/structures/TtscBannerConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscBannerConfig.js","sourceRoot":"","sources":["../../src/structures/TtscBannerConfig.ts"],"names":[],"mappings":""}

package/lib/structures/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ITtscBannerPluginConfig";
+export * from "./TtscBannerConfig";

package/lib/structures/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ITtscBannerPluginConfig"), exports);
+__exportStar(require("./TtscBannerConfig"), exports);
+//# sourceMappingURL=index.js.map

package/lib/structures/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,qDAAmC"}

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@ttsc/banner",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "First-party ttsc plugin that adds package-documentation JSDoc banners during emit.",
-  "main": "src/index.cjs",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "exports": {
-    ".": "./src/index.cjs",
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
     "./package.json": "./package.json"
   },
   "keywords": [
@@ -13,12 +17,25 @@
     "typescript",
     "tsgo"
   ],
+  "ttsc": {
+    "plugin": {
+      "transform": "@ttsc/banner"
+    }
+  },
   "files": [
     "README.md",
-    "src/index.cjs",
+    "lib",
+    "src",
     "go.mod",
-    "plugin"
+    "plugin/banner.go",
+    "plugin/main.go"
   ],
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@typescript/native-preview": "7.0.0-dev.20260508.1",
+    "rimraf": "^6.1.2",
+    "ttsc": "0.9.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/samchon/ttsc"
@@ -28,5 +45,8 @@
   "bugs": {
     "url": "https://github.com/samchon/ttsc/issues"
   },
-  "homepage": "https://github.com/samchon/ttsc/tree/master/packages/banner#readme"
+  "homepage": "https://github.com/samchon/ttsc/tree/master/packages/banner#readme",
+  "scripts": {
+    "build": "rimraf lib && tsgo"
+  }
 }

package/plugin/main.go

@@ -28,7 +28,7 @@ func run(args []string) int {
   case "transform":
     return utility.RunTransform(args[1:])
   case "check":
-    return 0
+    return utility.RunCheck(args[1:])
   default:
     fmt.Fprintf(os.Stderr, "@ttsc/banner: unknown command %q\n", args[0])
     return 2

package/src/index.ts

@@ -0,0 +1,29 @@
+import path from "node:path";
+
+import type { ITtscBannerPluginConfig } from "./structures";
+
+export * from "./structures/index";
+
+type TtscPluginDescriptor = {
+  name: string;
+  source: string;
+  stage?: "check" | "transform";
+};
+
+type TtscPluginFactoryContext<TConfig> = {
+  binary: string;
+  cwd: string;
+  plugin: TConfig;
+  projectRoot: string;
+  tsconfig: string;
+};
+
+export default function createTtscBanner(
+  _context: TtscPluginFactoryContext<ITtscBannerPluginConfig>,
+): TtscPluginDescriptor {
+  return {
+    name: "@ttsc/banner",
+    source: path.resolve(__dirname, "..", "plugin"),
+    stage: "transform",
+  };
+}

package/src/structures/ITtscBannerPluginConfig.ts

@@ -0,0 +1,17 @@
+/** `compilerOptions.plugins[]` entry shape consumed by `@ttsc/banner`. */
+export interface ITtscBannerPluginConfig {
+  /** Set to `false` to keep the entry while disabling this plugin. */
+  enabled?: boolean;
+
+  /** Plugin module specifier. */
+  transform?: string;
+
+  /** Inline banner text. */
+  text?: string;
+
+  /** Path to `banner.config.*`, resolved from the selected tsconfig directory. */
+  config?: string;
+
+  /** Extra plugin-owned fields are passed through unchanged. */
+  [key: string]: unknown;
+}

package/src/structures/TtscBannerConfig.ts

@@ -0,0 +1,7 @@
+/** Standalone `banner.config.*` file shape consumed by `@ttsc/banner`. */
+export type TtscBannerConfig =
+  | string
+  | {
+      /** Text inserted into the generated `@packageDocumentation` block. */
+      text: string;
+    };

package/src/structures/index.ts

@@ -0,0 +1,2 @@
+export * from "./ITtscBannerPluginConfig";
+export * from "./TtscBannerConfig";

package/src/index.cjs

@@ -1,12 +0,0 @@
-// @ts-check
-"use strict";
-
-const path = require("node:path");
-
-module.exports = function createTtscBanner() {
-  return {
-    name: "@ttsc/banner",
-    source: path.resolve(__dirname, "..", "plugin"),
-    stage: "transform",
-  };
-};