tsifdef 1.1.8

package/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+  <img src="assets/icon.png" alt="TSIfDef icon" width="128">
+</p>
+
+# TSIfDef 1.1.8
+
+**English** | [简体中文](./README.zh-CN.md)
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-brightgreen.svg?style=flat)](./LICENSE)
+[![Release](https://img.shields.io/github/v/release/Tencent/TSIfDef?style=flat&label=release)](https://github.com/Tencent/TSIfDef/releases/latest)
+[![Changelog](https://img.shields.io/badge/changelog-1.1.8-orange.svg?style=flat)](./CHANGELOG.md)
+[![GitHub Stars](https://img.shields.io/github/stars/Tencent/TSIfDef?style=flat&logo=github)](https://github.com/Tencent/TSIfDef/stargazers)
+[![GitHub Issues](https://img.shields.io/github/issues/Tencent/TSIfDef?style=flat&logo=github)](https://github.com/Tencent/TSIfDef/issues)
+[![Test](https://github.com/Tencent/TSIfDef/actions/workflows/test.yml/badge.svg)](https://github.com/Tencent/TSIfDef/actions/workflows/test.yml)
+[![Build](https://github.com/Tencent/TSIfDef/actions/workflows/build.yml/badge.svg)](https://github.com/Tencent/TSIfDef/actions/workflows/build.yml)
+
+> **TSIfDef adds reliable `#if` conditional compilation to TypeScript.**
+> Build multiple products from one source tree while the compiler, editor, and
+> ESLint always see the same active code.
+
+```typescript
+#if BROWSER
+export const runtime = "browser";
+#elif NODE
+export const runtime = "node";
+#else
+#error Select a supported runtime
+#endif
+```
+
+[![Download](https://img.shields.io/badge/Download-Latest_Release-blue.svg?style=for-the-badge)](https://github.com/Tencent/TSIfDef/releases/latest)
+
+## Quick Start
+
+Install TSIfDef as a development dependency:
+
+```bash
+npm install -D tsifdef
+```
+
+Create a Profile containing the macros enabled for this build:
+
+```json
+["BROWSER"]
+```
+
+Point `package.json` at that Profile and use TSIfDef as the compiler entry:
+
+```json
+{
+  "tsifdef": "./Profiles/browser.json",
+  "scripts": {
+    "build": "tsifdef build",
+    "watch": "tsifdef build --watch"
+  }
+}
+```
+
+Write conditional TypeScript directly in the original source file, as shown
+in the example above.
+
+Run the normal project build:
+
+```bash
+npm run build
+```
+
+Only the active branch reaches TypeScript. Source paths, diagnostics,
+declarations, and source maps still point to the original files.
+
+## Product Highlights
+
+- **One source tree** — no generated shadow project and no duplicated platform code.
+- **One Profile** — builds, editor intelligence, and ESLint use the same macro set.
+- **Native TypeScript output** — original paths and source-map locations are preserved.
+- **Complete editor feedback** — inactive code is dimmed and folded without false errors.
+- **Production workflows** — incremental compilation, watch mode, ESLint, and CI are supported.
+
+## Editor Support
+
+Download the `.vsix` from [GitHub Releases](https://github.com/Tencent/TSIfDef/releases/latest)
+and install it in VS Code, CodeBuddy, or CodeBuddy CN. Open a project whose
+`package.json` contains the `tsifdef` Profile pointer.
+
+The extension shows the active Profile in the status bar, dims inactive code,
+provides folding and diagnostics, and keeps the TypeScript language service on
+the same active source used by the build.
+
+## ESLint
+
+The same `tsifdef` package includes the ESLint processor and parser wrapper; no
+second TSIfDef package is required. Add its recommended config to an existing
+TypeScript flat config:
+
+```javascript
+import tsifdef from "tsifdef/eslint-plugin";
+
+export default [
+  // Your existing TypeScript ESLint config,
+  tsifdef.configs["flat/recommended"],
+];
+```
+
+ESLint then reports against the active source at the original line and column
+positions, with autofix and quick fixes intact. No rules need to be disabled —
+formatting rules such as `prettier/prettier` stay enabled and report only on
+active code. Legacy `.eslintrc` setup is documented in the
+[Integration Guide](./INTEGRATION.md).
+
+## Build Behavior
+
+Incremental builds and `--watch` are supported, and current-project `files`,
+`include`, and `exclude` settings are honored. Changing the selected Profile
+forces a full rebuild. `outFile` and project references (`tsc -b`) are not
+supported.
+
+Use `tsifdef build --emit-projection <dir>` when you need to inspect the exact
+source view passed to TypeScript.
+
+## Documentation
+
+| Document | Purpose |
+|---|---|
+| [Integration Guide](./INTEGRATION.md) | Build, editor, and ESLint setup |
+| [Portable Specification](./spec/README.md) | Syntax, behavior, schemas, and conformance fixtures |
+| [Changelog](./CHANGELOG.md) | Release history |
+| [Contributing](./CONTRIBUTING.md) | Development and pull-request workflow |
+| [Security Policy](./SECURITY.md) | Private vulnerability reporting |
+
+## Requirements
+
+- Node.js 18.17 or newer
+- TypeScript 5.5
+- VS Code 1.85 or a compatible editor for the VSIX
+
+## Development
+
+```bash
+npm ci
+npm test
+npm run build
+```
+
+Maintainers can build and verify the npm and VSIX artifacts with
+`npm run release`. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the repository
+workflow.
+
+## License
+
+TSIfDef is released under the [Apache License 2.0](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,141 @@
+<p align="center">
+  <img src="assets/icon.png" alt="TSIfDef 图标" width="128">
+</p>
+
+# TSIfDef 1.1.8
+
+[English](./README.md) | **简体中文**
+
+[![许可证](https://img.shields.io/badge/license-Apache--2.0-brightgreen.svg?style=flat)](./LICENSE)
+[![最新版本](https://img.shields.io/github/v/release/Tencent/TSIfDef?style=flat&label=release)](https://github.com/Tencent/TSIfDef/releases/latest)
+[![更新日志](https://img.shields.io/badge/changelog-1.1.8-orange.svg?style=flat)](./CHANGELOG.zh-CN.md)
+[![GitHub Stars](https://img.shields.io/github/stars/Tencent/TSIfDef?style=flat&logo=github)](https://github.com/Tencent/TSIfDef/stargazers)
+[![GitHub Issues](https://img.shields.io/github/issues/Tencent/TSIfDef?style=flat&logo=github)](https://github.com/Tencent/TSIfDef/issues)
+[![测试](https://github.com/Tencent/TSIfDef/actions/workflows/test.yml/badge.svg)](https://github.com/Tencent/TSIfDef/actions/workflows/test.yml)
+[![构建](https://github.com/Tencent/TSIfDef/actions/workflows/build.yml/badge.svg)](https://github.com/Tencent/TSIfDef/actions/workflows/build.yml)
+
+> **TSIfDef 为 TypeScript 提供可靠的 `#if` 条件编译。**
+> 一套源码构建多个产品，并让编译器、编辑器和 ESLint 始终使用同一份激活代码。
+
+```typescript
+#if BROWSER
+export const runtime = "browser";
+#elif NODE
+export const runtime = "node";
+#else
+#error Select a supported runtime
+#endif
+```
+
+[![下载](https://img.shields.io/badge/下载-最新版本-blue.svg?style=for-the-badge)](https://github.com/Tencent/TSIfDef/releases/latest)
+
+## 快速开始
+
+将 TSIfDef 安装为开发依赖：
+
+```bash
+npm install -D tsifdef
+```
+
+创建 Profile，列出本次构建启用的宏：
+
+```json
+["BROWSER"]
+```
+
+在 `package.json` 中指向该 Profile，并使用 TSIfDef 作为编译入口：
+
+```json
+{
+  "tsifdef": "./Profiles/browser.json",
+  "scripts": {
+    "build": "tsifdef build",
+    "watch": "tsifdef build --watch"
+  }
+}
+```
+
+直接在原始 TypeScript 文件中编写条件代码，如上方示例所示。
+
+运行项目构建：
+
+```bash
+npm run build
+```
+
+TypeScript 只会看到激活分支；源码路径、诊断、声明文件和 sourcemap 仍然指向原文件。
+
+## 产品能力
+
+- **一套源码**：不生成影子工程，不复制平台代码。
+- **一份 Profile**：构建、编辑器智能提示和 ESLint 使用同一组宏。
+- **原生 TypeScript 产物**：保留原始路径和 sourcemap 位置。
+- **完整编辑器体验**：未激活代码自动置灰和折叠，不产生错误诊断。
+- **工程化支持**：支持增量编译、watch、ESLint 和 CI。
+
+## 编辑器支持
+
+从 [GitHub Releases](https://github.com/Tencent/TSIfDef/releases/latest) 下载
+`.vsix`，安装到 VS Code、CodeBuddy 或 CodeBuddy CN。项目的 `package.json`
+需要包含 `tsifdef` Profile 指针。
+
+扩展会在状态栏显示当前 Profile，置灰和折叠未激活代码，提供宏诊断，并让
+TypeScript 语言服务与构建过程使用同一份激活代码。
+
+## ESLint
+
+同一个 `tsifdef` 包已经包含 ESLint processor 和 parser wrapper，无需安装第二个
+TSIfDef 包。将推荐配置加入现有 TypeScript Flat Config：
+
+```javascript
+import tsifdef from "tsifdef/eslint-plugin";
+
+export default [
+  // 项目现有的 TypeScript ESLint 配置，
+  tsifdef.configs["flat/recommended"],
+];
+```
+
+ESLint 只检查激活代码，诊断保留原始行列位置，自动修复和快速修复均正常工作。不需要
+关闭任何规则——`prettier/prettier` 等格式化规则保持开启即可，只会对激活代码生效。
+旧版 `.eslintrc` 接入方式见[接入指南](./INTEGRATION.zh-CN.md)。
+
+## 构建行为
+
+支持增量构建和 `--watch`，当前项目的 `files`、`include` 和 `exclude` 配置都会
+生效。切换 Profile 会触发全量重编。不支持 `outFile` 和 project
+references（`tsc -b`）。
+
+需要检查 TypeScript 实际接收的源码时，可使用
+`tsifdef build --emit-projection <dir>`。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [接入指南](./INTEGRATION.zh-CN.md) | 构建、编辑器和 ESLint 的完整接入方式 |
+| [可移植规范](./spec/README.zh-CN.md) | 语法、行为、Schema 和一致性用例 |
+| [更新日志](./CHANGELOG.zh-CN.md) | 版本变更记录 |
+| [参与贡献](./CONTRIBUTING.md) | 开发与 Pull Request 流程 |
+| [安全策略](./SECURITY.md) | 私密漏洞报告方式 |
+
+## 环境要求
+
+- Node.js 18.17 或更高版本
+- TypeScript 5.5
+- VS Code 1.85 或兼容编辑器
+
+## 开发
+
+```bash
+npm ci
+npm test
+npm run build
+```
+
+维护者可以使用 `npm run release` 构建并验证 npm 和 VSIX 产物。仓库协作流程见
+[CONTRIBUTING.md](./CONTRIBUTING.md)。
+
+## 许可证
+
+TSIfDef 使用 [Apache License 2.0](./LICENSE) 开源。

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are made against the latest released version of TSIfDef.
+
+## Reporting a vulnerability
+
+Use [GitHub Security Advisories](https://github.com/Tencent/TSIfDef/security/advisories/new)
+to report a vulnerability privately. Include the affected version, impact,
+reproduction steps, and any suggested mitigation.
+
+Do not open a public issue for an undisclosed vulnerability. Use
+[GitHub Issues](https://github.com/Tencent/TSIfDef/issues) for non-sensitive bugs
+and feature requests.

package/assets/icon-mono.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <title>TSIfDef — monochrome mask</title>
+  <defs>
+    <g id="m-hash" stroke-width="13" stroke-linecap="round" fill="none">
+      <path d="M52 24 L41 104"/>
+      <path d="M89 24 L78 104"/>
+      <path d="M30 51 L100 51"/>
+      <path d="M28 79 L98 79"/>
+    </g>
+    <clipPath id="m-left"><rect x="0" y="0" width="64" height="128"/></clipPath>
+    <clipPath id="m-right"><rect x="64" y="0" width="64" height="128"/></clipPath>
+  </defs>
+  <use href="#m-hash" stroke="currentColor" clip-path="url(#m-left)"/>
+  <use href="#m-hash" stroke="currentColor" stroke-opacity="0.40" clip-path="url(#m-right)"/>
+</svg>

package/assets/icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <title>TSIfDef</title>
+  <rect width="128" height="128" rx="28" fill="#17324E"/>
+  <defs>
+    <g id="hash" stroke-width="13" stroke-linecap="round" fill="none">
+      <path d="M52 24 L41 104"/>
+      <path d="M89 24 L78 104"/>
+      <path d="M30 51 L100 51"/>
+      <path d="M28 79 L98 79"/>
+    </g>
+    <clipPath id="left"><rect x="0" y="0" width="64" height="128"/></clipPath>
+    <clipPath id="right"><rect x="64" y="0" width="64" height="128"/></clipPath>
+  </defs>
+  <use href="#hash" stroke="#FFFFFF" clip-path="url(#left)"/>
+  <use href="#hash" stroke="#FFFFFF" stroke-opacity="0.40" clip-path="url(#right)"/>
+</svg>

package/dist/cli/build.d.ts

@@ -0,0 +1,70 @@
+import { type MacroDiagnostic } from "../core/index.js";
+import type { ProfileFile } from "./config.js";
+export interface BuildOptions {
+    readonly projectRoot: string;
+    readonly project: string;
+    readonly profile: ProfileFile;
+    /**
+     * Optional debug dump: when set, each macro file's equal-length projection is
+     * written under this directory at its original project-relative path. This is
+     * an auditing artifact only — it is never fed to the compiler.
+     */
+    readonly emitProjectionDir?: string;
+    /**
+     * Compiler options that override the tsconfig, e.g. `{ module, outDir,
+     * tsBuildInfoFile }`. Parse these from tsc-style flags with `parseTscOverride`
+     * so the CLI never reimplements tsc option parsing.
+     */
+    readonly compilerOptionsOverride?: import("typescript").CompilerOptions;
+}
+export interface BuildResult {
+    readonly emitted: boolean;
+    /** Absolute paths of files written by emit, in deterministic order. */
+    readonly outputFiles: readonly string[];
+    /** True when type checking or macro analysis reported blocking diagnostics. */
+    readonly hasErrors: boolean;
+}
+export interface BuildFileDiagnostic {
+    readonly file: string;
+    readonly diagnostics: readonly MacroDiagnostic[];
+}
+/** Raised when source files contain macro-structure diagnostics; blocks emit. */
+export declare class BuildMacroDiagnosticsError extends Error {
+    readonly files: readonly BuildFileDiagnostic[];
+    readonly code: "build-macro-diagnostics";
+    constructor(files: readonly BuildFileDiagnostic[]);
+}
+/** Raised for tsconfig shapes that projected compilation cannot support. */
+export declare class BuildUnsupportedError extends Error {
+    readonly code: "build-unsupported";
+    constructor(message: string);
+}
+/**
+ * Compile the project by projected compilation: hijack the CompilerHost so the
+ * TypeScript compiler reads equal-length masked text under the ORIGINAL file
+ * names, then drive `program.emit()`. Because the compiler never sees a shadow
+ * path, emitted sourcemap `sources`, `.d.ts`, and diagnostic paths point at the
+ * original sources with no post-processing.
+ */
+export declare function buildProject(options: BuildOptions): Promise<BuildResult>;
+/**
+ * With `inlineSources`, tsc embeds the text it read — which is our masked
+ * projection — into the sourcemap's `sourcesContent`. Replace each embedded
+ * entry with the original disk text so debuggers show real source, keeping the
+ * equal-length projection everywhere else. Handles both external `.map` files
+ * and inline base64 `sourceMappingURL` data URIs.
+ */
+export declare function restoreInlineSourcesFor(fileName: string, text: string): string;
+/**
+ * Parse tsc-style flags (e.g. `--module commonjs --outDir dist`) into a
+ * `CompilerOptions` override using TypeScript's own command-line parser, so the
+ * CLI never reimplements option parsing. Only compiler options are honored;
+ * file names in the flags are ignored.
+ *
+ * Path-valued options are resolved to absolute paths against `cwd`. This is
+ * required for cross-run incremental correctness: `.tsbuildinfo` stores output
+ * paths, and a relative `outDir` / `tsBuildInfoFile` resolves against a
+ * different base on the next run, defeating the up-to-date check.
+ */
+export declare function parseTscOverride(args: readonly string[], cwd?: string): Promise<import("typescript").CompilerOptions>;
+//# sourceMappingURL=build.d.ts.map