Metadata-Version: 2.4
Name: cnsh-v2
Version: 2.2.0
Summary: CNSH → C 通用转译器 v2.0 — 中文母语系统级语言，编译为 C99 原生可执行文件，内置 DNA 追溯与三色审计，零三方依赖
Author-email: 诸葛鑫 <346045695@qq.com>
License: MulanPSL-2.0
Project-URL: Homepage, https://uid9622.cn/cnsh/
Project-URL: Source, https://github.com/UID9622/cnsh-runtime
Keywords: cnsh,longhun,龍魂,chinese,programming-language,compiler,uid9622
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Mulan Permissive Software License v2 (MulanPSL-2.0)
Classifier: Natural Language :: Chinese (Simplified)
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<!--
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧬 龍魂·主权签章 · LONGHUN SOVEREIGN STAMP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DNA    : #龍芯⚡️2026-10-21-README-v1.0-UID9622
干支   : 丙午年·戊戌月·戊辰日·丑时
时间   : 2026-10-21T01:48:53+08:00
来源   : Manual
主权人 : UID9622 · 龍芯北辰 · 诸葛鑫
SHA256 : af5856ef8cd55096
许可   : CC BY-NC-SA 4.0（核心思想层）· 禁止用于AI训练
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-->

<!--
DNA: #龍芯⚡️2026-09-21-CNSH转C·说明文档-v2.0-UID9622
创建者: 诸葛鑫（UID9622）
License: MulanPSL v2 (https://license.coscl.org.cn/MulanPSL2)
-->

# CNSH → C 通用转译器 v2.0

CNSH 是一门**中文母语的系统级语言**：编译为 C99，再经 gcc/clang 编译为原生可执行文件，内置 DNA 追溯与三色审计。**零三方依赖**（仅 Python 标准库）。

## 快速开始

```bash
cd packaging/cnsh-v2

# 端到端：CNSH 源码 → C99 → 原生可执行文件 → 运行
python3 -m cnsh_v2 build examples/演示_主程序.cnsh
./examples/演示_主程序

# 只转译
python3 -m cnsh_v2 translate examples/演示_主程序.cnsh

# 只审计 / 查 DNA / 格式化 / 版本
python3 -m cnsh_v2 audit   examples/演示_主程序.cnsh
python3 -m cnsh_v2 dna     examples/演示_主程序.cnsh
python3 -m cnsh_v2 fmt     examples/演示_主程序.cnsh
python3 -m cnsh_v2 version
```

## 交互模式（REPL）

```bash
python3 -m cnsh_v2 repl              # 启动
python3 -m cnsh_v2 repl --debug      # 显示生成的 CNSH 源与编译报告
python3 -m cnsh_v2 repl --no-color   # 老终端
```

REPL 里直接输入 CNSH，回车即执行：

```
龍魂❯ 整数 x = 21
龍魂❯ 打印 x * 2
42
龍魂❯ 函数 加倍(整数 n) 返回类型 整数 {
...     返回 n * 2
... }
✅ 已登记声明
龍魂❯ 打印 加倍(50)
100
```

内置指令：`.帮助` `.退出` `.清空` `.历史` `.声明` `.载入 <文件>` `.版本` `.重置`

**执行方式说明（重要）**：`cnsh_v2` 是转译器，没有 eval/运行时。
REPL 每段都是「生成 CNSH 源 → `Compiler.build()` → 跑本机可执行 → 回收 stdout」。
变量与顶层声明跨段保留，旧段输出不会重放（用标记截断）。

**性能**（Apple M4 Max / clang 21，复算：`python3 tools/bench_交互解释器.py`）：

| 指标 | 实测 |
|---|---|
| 单段全链路中位 | ≈65 ms（编译占 98%） |
| 会话层（生成 20 段源） | 0.004 ms（可忽略） |
| 语句 1 → 800 段 | 74 → 93 ms（1.26×） |

结论：瓶颈是每段一次 clang，不是「重放旧语句」——千段以内不需要为它 `.重置`。

## 风格检查（lint）

```bash
python3 -m cnsh_v2 lint examples/            # 检查
python3 -m cnsh_v2 lint . --fix              # 自动修 L001（行尾空格）
python3 -m cnsh_v2 lint . --json             # 机器可读
python3 -m cnsh_v2 lint . --strict           # CI：W/L 也算失败
```

规则只管**风格与工程卫生**，语法/语义由编译器负责（E1xxx/E2xxx），不重复造。

| 代码 | 含义 | 可自动修 |
|---|---|---|
| L001 | 行尾空格 | ✅ `--fix` |
| L002 | 缩进不是本文件缩进单位的倍数 | — |
| L003 | 视觉宽度 > 100（中日韩按 2 计） | — |
| L004 | 文件头 15 行无 DNA 签章 | — |
| L005 | 有 DNA 但无许可证/归属声明 | — |
| W001 | 同文件内函数返回类型写法不一致 | — |
| W003 | 用了英文关键字（if/for/return…） | — |
| E001/E002 | 控制字符 / 非 UTF-8 | — |

**为什么规则要跟着文件走**：仓内 `.cnsh` 有 v0.1（2 空格缩进）、v1（`定义 …:`）、
v2（`函数 … 返回类型`）三种方言。用 v2 的 4 空格去量 v0.1 文件会 100% 误报
（实测 155 个文件里 L002 命中 208 次，全是假的）。所以缩进单位由文件自身推断，
装饰分隔线（`# ═════`）不算超宽，字符串字面量里的 `if` 不算英文关键字。

存量基线：155 个文件里 51% 有提示，其中 45% 是行尾空格、38% 缺许可证 —— 都是历史欠账，
不是新代码门槛。E 级为 0，说明没有真错误。

## 虚拟环境（venv）

```bash
python3 -m cnsh_v2 venv create          # 建 .cnsh-env/
eval "$(python3 -m cnsh_v2 venv activate)"   # 激活（导出三个环境变量）
python3 -m cnsh_v2 venv install ./我的库/     # 装本地包（目录里需 cnsh.toml）
python3 -m cnsh_v2 venv list            # 已装包
python3 -m cnsh_v2 venv info            # 环境信息
cnsh_venv_deactivate                    # 停用
```

CNSH 编译到 C，没有解释器隔离需求。venv 隔离的是三样：**stdlib 覆盖**、
**包搜索路径**、**构建产物目录**。不复制工具链。

三个变量，以及**谁真的消费它们**（设了没人读就是装饰品，所以逐条列出）：

| 变量 | 消费点 | 作用 |
|---|---|---|
| `CNSH_ENV` | `modules.ModuleResolver._搜索根` · `cli.build` | 环境根进搜索路径；`build` 无 `-o` 时产物落 `$CNSH_ENV/build/` |
| `CNSH_STDLIB` | `ModuleResolver._find` | 仅对 `stdlib/...` 前缀生效，优先于系统 stdlib |
| `CNSH_PKG_PATH` | `ModuleResolver._搜索根` | 逐条追加包搜索根 |

优先级：`$CNSH_STDLIB`（仅 stdlib/ 前缀）→ `$CNSH_ENV` → `$CNSH_PKG_PATH…`
→ 源文件目录 → 包根。未设变量时行为与旧版完全一致。

**不实现**：`cnsh init` 与 `cnsh.toml` 项目约定 —— 本仓没有这两样，venv 不假装能初始化项目；
包目录里读 `cnsh.toml`（没有就用目录名/unknown）。也不做远程索引与依赖求解。

顺带修掉一条静默路径：宽容模式下缺失导入会降级成空模块，而 `resolver.missing`
原先**没有任何人读** ⇒ 缺模块完全静默，用户只看到「编译通过 + 运行时报未定义符号」。
现在 `Compiler` 会输出 `W3001: 导入模块缺失，已降级为空模块`。

## 新建项目（init）

```bash
python3 -m cnsh_v2 init 我的项目 --venv
cd 我的项目
eval "$(python3 -m cnsh_v2 venv activate)"
python3 -m cnsh_v2 venv install     # 按 cnsh.toml 的 [dependencies]
python3 -m cnsh_v2 build            # 省略源文件 = 用 cnsh.toml 的 entry
./build/主程序
```

生成的结构：

```
我的项目/
├── cnsh.toml           项目配置
├── 主程序.cnsh          入口（能编译、能跑）
├── tests/test_主程序.cnsh  自带主函数的测试骨架（能编译、能跑、失败返回非零）
├── stdlib/             项目私有 stdlib 覆盖
├── build/              产物（已 gitignore）
├── .gitignore
└── README.md
```

`cnsh.toml` 的每个字段都有人消费：

| 字段 | 消费点 |
|---|---|
| `project.entry` | `build/translate/audit/dna/fmt` 省略源文件时用它 |
| `project.target` | `--target`，仅 `c` / `c99` / `c11` |
| `project.name` / `version` | 项目标识；`venv install` 读 name |
| `dependencies` | `venv install` 不带参数时按表安装 |
| `build.output_dir` | `build` 默认输出目录（保留源文件相对路径） |

**故意不提供** `flags` 与 `dev-dependencies`：没有对应实现，写了也不会生效。
**不支持** `--target python/js/rust`：编译器只产出 C，写进配置也编译不出来，所以直接报错。

⚠️ **中文包名必须加引号**：`"工具库" = "../lib"`。
TOML 裸键只允许 ASCII 字母数字与 `_`/`-`；写成 `工具库 = "..."` 会让**整份配置**解析失败
（不是那一行失效），`venv install` 会明确报「解析失败」而不是假装「表为空」。

## 一段 CNSH

```cnsh
导入 "stdlib/字符串.cnsh"

函数 主函数() 返回类型 整数 {
    整数 和 = 0
    对于 (整数 i = 0; i < 10; i++) {
        和 += i
    }
    如果 〖和 > 40〗 {
        打印 字符串_拼接("和是", "四十五")
    } 否则 {
        打印「不大」
    }
    返回 0
}
```

## 目录

```
docs/       语言规范（SPEC/TYPE_SYSTEM/SCOPE_RULES/UNDEFINED_BEHAVIOR/ABI/VERSIONING/CHANGELOG/ROADMAP）
cnsh_v2/    转译器本体（lexer/parser/sema/dna/audit/modules/codegen_c/compiler/cli/...）
stdlib/     标准库 CNSH 侧声明（字符串/数学/文件/时间/输入/内存）
tests/      一致性（JSON 用例）+ 黄金输出 + 回归
tools/      LSP 骨架（当前仅语法诊断）
examples/   端到端示例
```

## 测试

```bash
python3 tests/run_tests.py                          # 一致性 20 例（纯标准库 runner）
python3 -m pytest tests/test_golden.py tests/regression/   # 黄金输出 + 回归（或各自直接 python3 跑）
```

## 治理口径

- DNA 前缀 `#龍芯⚡️`，用户 UID9622；旧前缀自动迁移（`cnsh_v2/dna.py`）。
- 三色审计 🟢/🟡/🔴，strict 模式 🔴 阻断编译（`cnsh_v2/audit.py`）。
- 生成的 C 文件头部自动注入 DNA 注释 + 干支时间戳（`08_BIN/lh_输出戳.py`，失败降级 ISO，不影响编译）。

## 断言库（stdlib/断言.cnsh）

```cnsh
导入 "stdlib/断言.cnsh"

函数 主函数() 返回类型 整数 {
    断言相等(2 + 2, 4, "四则运算应成立")
    断言为真(5 > 3, "")
    断言相等文本("龍魂", "龍魂", "")
    打印「✅ 全部通过」
    返回 0
}
```

失败时**立即**打印原因到 stderr 并以退出码 1 终止——不是返回一个 0/1 让调用方自己记得检查。

| 函数 | 说明 |
|---|---|
| `断言(条件, 消息)` | 条件为假 ⇒ 失败 |
| `断言为真` / `断言为假` | 同上 / 取反 |
| `断言相等(期望, 实际, 消息)` | 整数比较 |
| `断言不等(值一, 值二, 消息)` | 整数比较 |
| `断言相等文本(期望, 实际, 消息)` | 文本比较（C 无重载，故单列） |

## 格式化（fmt）

```bash
cnsh fmt 主程序.cnsh            # 打印格式化结果
cnsh fmt 主程序.cnsh -w         # 原地写回
cnsh fmt . --check              # CI：需要格式化的文件存在则退出码 1
cnsh fmt 主程序.cnsh --dry-run  # 打印 diff，不写回
```

规则：行尾空白、整行注释 `#x`→`# x`（装饰行豁免）、连续空行压到 2、末尾恰好 1 个换行。

**不做缩进规范化**：仓内 v0.1 用 2 空格、v2 用 4 空格，强行统一不该由 fmt 决定。

**解析不过的文件一个字节都不动**（退出码 2）。原因：现有 `formatter.format_source()`
实测会**删光注释**（Token 流重建，注释不进流），用它写回等于数据丢失。
所以 fmt 只做行级处理，并带两条护栏：写回前再解析一次、注释行数不许减少。

## 调试（debug）

```bash
cnsh build --debug 主程序.cnsh   # 只产出带调试符号的产物
cnsh debug 主程序.cnsh           # 编译 + 启动 lldb/gdb
cnsh debug 主程序.cnsh --print-only   # 只打印命令
```

调试模式下 codegen 在每条语句前发 `#line N "源.cnsh"`，lldb 里变量声明直接显示
`decl = 主程序.cnsh:12`——不需要 `.cnsh.map`（没有调试器会读那种文件）。

⚠️ macOS 把 DWARF 放进同名 `.dSYM`，**可执行文件本身不含**。
所以「用 file 验证二进制含 DWARF」这条判据在 macOS 上永远假阴性，别用它。

## 发版（维护者）

```bash
python3 tools/发布.py --check      # 本地校验：版本双写 / 构建 / twine check / 关键模块
PYPI_TOKEN=pypi-... python3 tools/发布.py --upload
python3 tools/发布.py --verify --wait 30   # 从 PyPI 拉回来实装实跑
```

脚本挡四件事：
1. **版本双写**（`version.py` 与 `pyproject.toml` 各写一次，漏改就发错版本）
2. **代理**（构建的隔离环境会继承 socks5，报 `Missing dependencies for SOCKS support`）
3. **残包**（构建成功 ≠ 包里对：逐个检查关键模块与 `cli` 子命令是否真在 wheel 内）
4. **token 泄漏**（只经环境变量传给子进程，不进 argv、不回显）

⚠️ PyPI 同一版本号只能发一次，发错只能换号 —— 所以 `--upload` 前会把能查的都查一遍。

<!--
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔒 龍魂·主权封底 · SOVEREIGN SEAL
DNA    : #龍芯⚡️2026-10-21-README-v1.0-UID9622
干支   : 丙午年·戊戌月·戊辰日·丑时
主权人 : UID9622 · 龍芯北辰 · 诸葛鑫
铁律   : 人永远是1·不蒸馏·不投机·焊死
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-->
