@nova-lang/cli 0.1.0

package/README.md

@@ -0,0 +1,322 @@
+我设计了一种全新的标记语言，命名为 **Nova**（全称：**N**ested **O**rdered **V**ersatile **A**rchitecture）。它并非将 HTML、YAML、TeX 等语法简单堆砌，而是从它们各自的优势中抽象出**统一节点模型**——一切皆是可带属性、可含子节点的**函数式块（Block）**。Nova 的语法规则如下。
+
+---
+
+## 安装
+
+### npm（推荐）
+```bash
+npm install -g @nova-lang/cli
+# 需要先安装 Zig 编译器：https://ziglang.org/download/
+nova examples/sample.nv output.html
+```
+
+### pip
+```bash
+pip install -e .
+nova examples/sample.nv output.html
+```
+
+### Zig 编译
+```bash
+zig build
+./zig-out/bin/nova examples/sample.nv output.html
+```
+
+---
+
+## Nova 语法规范 v1.0
+
+### 核心设计理念
+- **一切皆块**：文档元素、元数据、样式、数据类型、宏都是块，语法形式统一。
+- **缩进定界**：块内容由缩进界定，省略闭合标记，类似 YAML 和 Python。
+- **标签即函数**：块类型通过 `@命令名` 调用，属性写在圆括号 `()` 里，子块写在缩进大括号 `{}` 里——这是一种**函数式标记**。
+- **双模数据**：内联采用自然书写，数据表可采用紧凑的类 CSV 表示或外部引用。
+- **强类型可编译**：可内嵌类型定义和接口，直接生成代码或验证数据。
+- **数学与宏不变质**：保留 TeX 强大排版，但将其融入统一语法。
+
+---
+
+### 1. 基础词法
+
+```nova
+// 单行注释
+/* 多行
+   注释 */
+
+// 文档元数据块
+@meta {
+    title: "Nova 示例"
+    author: Li Hua
+    date: 2026-06-20
+}
+
+// 引入外部包（如预定义类型、宏集）
+@use "nova/std/typography"
+@use "nova/schema/gencode"
+```
+
+- 字符串：`"双引号"` 或 `'单引号'`，支持 `#{...}` 插值。
+- 数字：`42`、`3.14`、`6.02e23`、`0xAB`。
+- 布尔与空：`true`、`false`、`null`。
+- 标识符：`[a-zA-Z_][a-zA-Z0-9_-]*`。
+
+---
+
+### 2. 块语法（融合 HTML/XML 结构 + YAML 简洁）
+
+一个块的基本形式为：
+
+```nova
+@块名(属性1: 值, 属性2: 值) 可选内联正文 {
+    子块1
+    子块2
+}
+```
+
+- **无子块**可省略大括号和缩进：  
+  `@image(src: "photo.png", alt: "头像")`
+- **块名省略**时为无名容器，等价于 `<div>` 或 YAML 映射。
+- **属性列表**写在紧跟的 `()` 中，逗号分隔，键值对用 `:` 分隔（也可用 `=`），布尔属性可省略值。
+- **子块**必须比父块缩进一层（2 个空格）。
+
+#### 示例
+```nova
+@page {
+    @header {
+        @title "Nova 语言手册"
+        @author "Li Hua"
+    }
+    @body {
+        @section(id: "intro") {
+            @p "Nova 是一种全新的可编程标记语言。"
+        }
+    }
+}
+```
+相当于 HTML 的 `<page><header><title>...</title>`…，但无需闭合标签，且结构由缩进清晰表达。
+
+---
+
+### 3. 内联元素与格式（融合 HTML 行内标签 + TeX 命令）
+
+内联内容使用 `@标记{ 文本 }` 或 `@标记(属性){ 文本 }`：
+```nova
+这是一段包含 @em{强调} 和 @strong{粗体} 的文本，
+还有 @a(href: "https://nova-lang.org"){链接} 和 @code{print(x)}。
+```
+与 TeX 的 `\emph{...}` 相似，但统一了属性传递方式。
+
+数学公式直接内嵌，支持 TeX 语法：
+- 行内：`$E = mc^2$`
+- 展示：`$$ \sum_{i=1}^n i = \frac{n(n+1)}{2} $$`
+- 也可使用块形式：`@equation { x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} }`
+
+---
+
+### 4. 列表与映射（YAML 优势）
+
+- **无序列表**用 `-` 或 `*` 引导：
+  ```nova
+  @ul {
+      - 苹果
+      - 香蕉
+      - 橘子
+  }
+  ```
+- **有序列表**用 `+` 后跟数字或 `#`：
+  ```nova
+  @ol {
+      + 1. 第一步
+      + 2. 第二步
+  }
+  ```
+- **映射**用键值对，可内联或展开：
+  ```nova
+  @config {
+      host: "localhost"
+      port: 8080
+      timeout: 30s
+  }
+  ```
+
+列表项本身可以是块，允许包含多段落或其他块：
+```nova
+- @p "第一点详细说明"
+  @note "补充信息"
+- @p "第二点"
+```
+
+---
+
+### 5. 表格系统（融合 CSV 紧凑 + 管道表可读性）
+
+Nova 提供三种表格写法，适应不同场景。
+
+#### 5.1 内联二维数组（CSV 风格）
+```nova
+@table {
+    [["姓名", "年龄", "城市"],
+     ["张三", 30, "北京"],
+     ["李四", 25, "上海"]]
+}
+```
+
+#### 5.2 带表头的块表（可读性）
+```nova
+@table {
+    @header { 姓名, 年龄, 城市 }
+    @row { 张三, 30, 北京 }
+    @row { 李四, 25, 上海 }
+}
+```
+
+#### 5.3 外部数据引用（CSV 文件绑定）
+```nova
+@table(src: @csv("data/measurements.csv"), caption: "测量数据")
+```
+这样保留了 CSV 的简单数据交换能力，同时能被解析器直接处理。
+
+---
+
+### 6. 宏与变量（TeX 宏 + 现代模板）
+
+宏定义使用 `@def` 或 `@macro`，支持位置参数和块参数。
+```nova
+@def greet(name) {
+    @p "您好，#{name}！"
+}
+
+@def framed(title: String = "提示", @content) {
+    @div(style: "border") {
+        @strong "#{title}"
+        @content
+    }
+}
+
+@greet("世界")
+@framed("警告") {
+    这是一条重要信息。
+}
+```
+调用方式与普通块完全一致，实现了 **标记即代码**。
+
+还支持**命名参数**、**默认值**和**块参数**（如 `@content`），这吸收了 LaTeX3 的新特性，但语法更清晰。
+
+---
+
+### 7. 类型定义与代码生成（gencode / 接口描述语言）
+
+Nova 可直接定义强类型消息，用于生成序列化代码、验证数据，或作为 API 合同。
+```nova
+@schema(Person) {
+    id: Int32 @1
+    name: String @2 = ""
+    email: String? @3       // ? 表示可选
+    tags: List<String> @4
+}
+
+@service(UserAPI) {
+    getUser(id: Int32) -> Person
+    listUsers() -> List<Person>
+    updateUser(id: Int32, data: UpdateMask) -> Person
+}
+```
+编译器可根据这些定义输出 Go struct、Protobuf、JSON Schema 或 Python dataclass。这继承了 gencode 的核心优势，并且语法与文档其他部分无缝融合。
+
+---
+
+### 8. 交叉引用与参考文献（LaTeX 优势）
+
+**标签**使用 `@label(标识符)`，**引用**使用 `@ref(标识符)`，**文献**使用 `@cite(key)`。
+```nova
+@chapter(id: "intro") {
+    @title "简介"
+    @label(sec:intro)
+}
+
+参见 @ref(sec:intro) 的讨论。该方法源自 @cite(lamport94)。
+
+@bibliography {
+    @entry(key: lamport94, type: book,
+            author: "Leslie Lamport",
+            title: "LATEX: A Document Preparation System",
+            year: 1994)
+}
+```
+文档的元数据中可指定参考文献风格，生成 PDF 或 HTML 时自动格式化。
+
+---
+
+### 9. 环境与条件（TeX 环境 + 现代流程控制）
+
+- **环境块**：`@if(条件) { ... }`，`@for(item in list) { ... }`。
+- **条件显示**：
+  ```nova
+  @if(@defined(debug)) {
+      @warn "调试模式开启，当前值：#{value}"
+  }
+  ```
+- **循环生成列表项**：
+  ```nova
+  @ul {
+      @for(user in users) {
+          - @strong(user.name) (#{user.email})
+      }
+  }
+  ```
+
+这使得文档不仅仅是静态文本，而是带有轻量逻辑的**活文档**。
+
+---
+
+### 10. 完整综合示例
+
+```nova
+@use "nova/std"
+@use "nova/plot"
+
+@meta {
+    title: "Nova 语言白皮书"
+    authors: ["Li Hua", "Zhang Wei"]
+    version: 1.0
+}
+
+@page {
+    @title "Nova 语言白皮书"
+
+    @abstract {
+        Nova 统一了文档与数据，提供前所未有的编写体验。
+        详见 @ref(sec:design)。
+    }
+
+    @chapter(id: "intro") @label(sec:intro) {
+        @p "本文介绍 Nova 的语法及设计理念。"
+        @p "数学示例：能量守恒 $E = mc^2$。"
+    }
+
+    @chapter(id: "design") @label(sec:design) {
+        @p "核心架构基于统一函数式块。"
+        @table(caption: "主流语言对比") {
+            @header { 特性, HTML, YAML, TeX, Nova }
+            @row { 标签, ✅, ❌, ✅, ✅ 函数式 }
+            @row { 缩进块, ❌, ✅, 部分, ✅ }
+            @row { 数学, ❌, ❌, ✅, ✅ }
+            @row { 类型定义, ❌, ❌, ❌, ✅ }
+        }
+    }
+
+    @chapter(id: "api") {
+        @p "数据模型定义："
+        @schema(Measurement) {
+            sensor_id: Int32 @1
+            value: Float64 @2 = 0.0
+            unit: String @3 = "mV"
+        }
+    }
+
+    @bibliography {
+        @entry(key: nova2026, title: "Nova Language Spec", year: 2026)
+    }
+}
+```

package/bin/nova.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+function findBinary() {
+  const binName = process.platform === "win32" ? "nova.exe" : "nova";
+
+  const candidates = [
+    path.join(__dirname, "..", "zig-out", "bin", binName),
+    path.join(__dirname, "..", "bin", binName),
+  ];
+
+  if (process.env.NOVA_BINARY) {
+    candidates.unshift(process.env.NOVA_BINARY);
+  }
+
+  for (const p of candidates) {
+    try {
+      if (fs.statSync(p).isFile()) {
+        return p;
+      }
+    } catch {}
+  }
+
+  return null;
+}
+
+function main() {
+  const binary = findBinary();
+  if (!binary) {
+    console.error(
+      "Nova Zig binary not found.\n" +
+        "  Build with: npm run build  (requires Zig compiler)\n" +
+        "  Or set:     NOVA_BINARY=/path/to/nova\n"
+    );
+    process.exit(1);
+  }
+
+  const result = spawnSync(binary, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+
+  process.exit(result.status ?? 1);
+}
+
+main();

package/build.zig

@@ -0,0 +1,25 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const exe_mod = b.createModule(.{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const exe = b.addExecutable(.{
+        .name = "nova",
+        .root_module = exe_mod,
+    });
+
+    b.installArtifact(exe);
+
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+
+    const run_step = b.step("run", "Run Nova");
+    run_step.dependOn(&run_cmd.step);
+}

package/install.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execSync, spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const ROOT = path.resolve(__dirname);
+const BIN_DIR = path.join(ROOT, "zig-out", "bin");
+const BIN_NAME = process.platform === "win32" ? "nova.exe" : "nova";
+const BIN_PATH = path.join(BIN_DIR, BIN_NAME);
+
+function alreadyBuilt() {
+  try {
+    return fs.statSync(BIN_PATH).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function findZig() {
+  try {
+    const r = spawnSync("which", ["zig"], { stdio: "pipe" });
+    if (r.status === 0) {
+      return r.stdout.toString().trim();
+    }
+  } catch {}
+  try {
+    const r = spawnSync("where", ["zig"], { stdio: "pipe", shell: true });
+    if (r.status === 0) {
+      return r.stdout.toString().trim().split("\n")[0];
+    }
+  } catch {}
+  return null;
+}
+
+function build() {
+  if (alreadyBuilt()) {
+    console.log("nova: binary already built at " + BIN_PATH);
+    return;
+  }
+
+  const zig = findZig();
+  if (!zig) {
+    console.log(
+      "nova: Zig compiler not found. Skipping build.\n" +
+        "  Install Zig: https://ziglang.org/download/\n" +
+        "  Then run:     npm run build"
+    );
+    return;
+  }
+
+  console.log("nova: building with " + zig + " ...");
+  const result = spawnSync(zig, ["build"], {
+    cwd: ROOT,
+    stdio: "inherit",
+  });
+
+  if (result.status === 0) {
+    console.log("nova: built successfully -> " + BIN_PATH);
+  } else {
+    console.error("nova: build failed (exit code " + result.status + ")");
+    process.exit(result.status ?? 1);
+  }
+}
+
+build();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@nova-lang/cli",
+  "version": "0.1.0",
+  "description": "Nova: Nested Ordered Versatile Architecture — a programmable markup language CLI",
+  "license": "MIT",
+  "keywords": [
+    "markup",
+    "markdown",
+    "typesetting",
+    "document",
+    "schema",
+    "code-generation"
+  ],
+  "bin": {
+    "nova": "bin/nova.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js",
+    "build": "zig build",
+    "build-release": "zig build -Doptimize=ReleaseSafe",
+    "clean": "rm -rf zig-out zig-cache .zig-cache",
+    "test": "nova lex examples/basics.nv && nova ast examples/basics.nv"
+  },
+  "files": [
+    "bin/",
+    "install.js",
+    "build.zig",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": ["darwin", "linux", "win32"],
+  "cpu": ["x64", "arm64"]
+}