chore: release v0.1.0 engine update and pypi workflow

Author: IndenScale

.github/workflows/publish-pypi.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-n-publish:
+    name: Build and publish Typedown to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Mandatory for trusted publishing
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Run Tests
+        run: |
+          uv sync
+          uv run td test tests/integration/cases
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

DEMO_SCRIPT.md

@@ -0,0 +1,33 @@
+# 2025-12-20 任务验收日志
+
+## 验收对象
+
+- `_strategy/todos/archive/03-核心重构-编译器驱动.md`
+- `_strategy/todos/04-llvm-架构迁移.md`
+
+## 验收结果
+
+### 任务 03: 核心重构 (编译器前端与链接器)
+
+**状态**: ✅ 已完成 (已归档)
+
+**验证项**:
+1. **Config**: `typedown/core/config.py` 已实现 `typedown.toml` 的 Schema 定义与加载逻辑。
+2. **Resolver**: `typedown/core/resolver.py` 已实现物理路径映射与自动探测。
+3. **Linker**: `typedown/core/compiler_context.py` 中的 `TypedownMetaFinder` 实现了基于 `sys.meta_path` 的 Import Hook。
+4. **CLI**: `typedown/commands/test.py` 已更新以使用新的编译器上下文。
+
+### 任务 04: 迁移至 LLVM 编译器架构
+
+**状态**: 🔄 进行中
+
+**进度详情**:
+- [x] **1. 符号表构建 (Symbols)**: `MistuneParser` (`typedown/core/mistune_parser.py`) 正确提取 ImportStmt 并构建隔离命名空间。
+- [ ] **2. 实体校验 (Entities)**: **[待办]** 尚未实现基于 Entity 类型的 Pydantic 类动态匹配与校验逻辑。
+- [x] **3. 链接解析 (Linkage)**: `Evaluator` (`typedown/core/evaluator.py`) 与 `DependencyGraph` (`typedown/core/graph.py`) 已实现全局引用扫描与悬空引用检查。
+- [x] **4. 后端执行 (Pytest Backend)**: `typedown/commands/test.py` 实现了将 spec 块转化为临时 pytest 文件并注入 `compiler` fixture 的逻辑。
+
+## 下一步计划
+
+集中精力完成 **Task 04 Item 2: 实体校验 (Entities)**。
+目标是实现 `Compiler._link` 或 `Compiler._validate` 阶段中对 `entity:<Type>` 的实例化与校验，确保所有定义的实体都符合其 `model` 定义的约束。

dev-docs/logs/2025-12-20.md

@@ -4,6 +4,19 @@ version = "0.1.0"
 description = "Progressive Formalization for Markdown using Pydantic and Pytest"
 readme = "README.md"
 requires-python = ">=3.10"
+license = "MIT"
+keywords = ["markdown", "pydantic", "formalization", "documentation", "spec", "data-entry"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
 dependencies = [
     "typer>=0.9.0",
     "pydantic>=2.0.0",
@@ -13,8 +26,14 @@ dependencies = [
     "rich>=13.0.0",
     "tomli>=2.3.0",
     "mistune>=3.1.4",
+    "pyyaml>=6.0.0",
 ]
 
+[project.urls]
+Homepage = "https://typedown.io"
+Repository = "https://github.com/IndenScale/Typedown"
+Documentation = "https://typedown.io/docs"
+
 [project.optional-dependencies]
 server = [
     "pygls>=1.0.0",

pyproject.toml

@@ -5,13 +5,14 @@
 - [000-concept.md](meta/000-concept.md): Core concepts and philosophy.
 
 ## RFCs (Request for Comments)
-* [001-syntax.md](rfc/001-syntax.md): Basic syntax and extensions.
-* [002-evolution.md](rfc/002-evolution.md): Data evolution mechanisms.
-* [003-structure.md](rfc/003-structure.md): Project directory structure.
-* [004-import.md](rfc/004-import.md): Import and configuration inheritance.
-* [005-reference.md](rfc/005-reference.md): Reference and linking mechanisms.
-* [006-testing.md](rfc/006-testing.md): Testing and specification validation mechanisms.
+
+- [001-syntax.md](rfc/001-syntax.md): Basic syntax and extensions.
+- [002-evolution.md](rfc/002-evolution.md): Data evolution mechanisms.
+- [003-structure.md](rfc/003-structure.md): Project directory structure.
+- [004-import.md](rfc/004-import.md): Import and configuration inheritance.
+- [005-reference.md](rfc/005-reference.md): Reference and linking mechanisms.
+- [006-testing.md](rfc/006-testing.md): Testing and specification validation mechanisms.
 
 ## Architecture
 
-- [001-data-model.md](architecture/001-data-model.md): Internal compiler data models.
+- [001-ir.md](architecture/001-ir.md): Internal compiler representation (IR) and symbols.

specs/README.md

@@ -0,0 +1,57 @@
+# Typedown Intermediate Representation (IR)
+
+The Typedown IR is a set of structured data models representing the semantic content of a project after parsing and link-resolution. It is the language-neutral representation used between the **Frontend (Parser)** and the **Backend (Spec Runner/Validator)**.
+
+## 1. Node Hierarchy
+
+All IR nodes inherit from a base `Node` class.
+
+### 1.1 Base Node
+
+| Field      | Type                       | Description                                       |
+| :--------- | :------------------------- | :------------------------------------------------ |
+| `id`       | `Optional[str]`            | The unique identifier for this symbol.            |
+| `location` | `Optional[SourceLocation]` | File path and line range for diagnostics and LSP. |
+
+## 2. Semantic Nodes
+
+### 2.1 EntityDef
+
+Represents a data instance.
+
+- **Payload**: `data: Dict[str, Any]` (The YAML-parsed content).
+- **Type**: `type_name: str`.
+
+### 2.2 ModelDef
+
+Represents a Pydantic/Python model block.
+
+- **Payload**: `code: str`.
+
+### 2.3 SpecDef
+
+Represents a testing/validation block.
+
+- **Payload**: `code: str` (Python) or `data: Dict` (YAML).
+- **Name**: `name: str`.
+
+### 2.4 ImportStmt
+
+Represents a virtual or physical import.
+
+- **Source**: `source: str` (e.g., `@lib.math`).
+- **Names**: `List[str]` (Symbols imported).
+
+## 3. Document
+
+A `Document` is the root container for a single physical file.
+
+- **Path**: `Path`.
+- **Collections**: `imports`, `models`, `entities`, `specs`, `references`.
+
+## 4. Symbol Table
+
+The **Compiler** maintains a global Symbol Table (Map of `ID -> Node`).
+
+- All `EntityDef`, `ModelDef`, and `SpecDef` nodes with an `id` are registered here.
+- The `Evaluator` uses this table to resolve `[[ID]]` queries.

specs/architecture/001-data-model.md

@@ -6,43 +6,41 @@ Typedown uses standard Markdown syntax and extends its functionality through spe
 
 To support "Progressive Formalization," Typedown allows defining data models directly within Markdown documents. This is typically used during the initial or testing phases (Inception Phase).
 
-Use the `model` tag on code blocks. The content supports standard Python syntax but is enhanced with pre-loaded common type definitions.
+Use the `model` tag on code blocks. The content supports standard Python syntax. You can optionally provide an `id`.
 
 ````markdown
-```model
-# No need to manually import BaseModel, Field, List, etc.
-class Address(BaseModel):
-    city: str
-    zip_code: str
-
+```model id=UserAccount
 class User(BaseModel):
     name: str
     age: int = Field(..., ge=0)
-    role: str = "guest"
-    address: Optional[Address] = None
 ```
 ````
 
 ### Features
 
-1.  **Multi-Class Definition**: You can define multiple related classes within a single `model` block.
-2.  **Auto-imports**: To reduce boilerplate, the execution environment pre-loads the following symbols by default:
-    - **Pydantic**: `BaseModel`, `Field`, `validator`, `model_validator`, `PrivateAttr`
-    - **Typing**: `List`, `Dict`, `Optional`, `Union`, `Any`, `ClassVar`
-    - **Enum**: `Enum`
-3.  **Override Mechanism**: Classes defined here are automatically registered to the current document's context. If a name conflicts with an existing model, the new definition overrides the old one.
-
-## 2. Entity Instantiation
+1. **Multi-Class Definition**: You can define multiple related classes within a single `model` block.
+2. **Auto-imports**: To reduce boilerplate, the execution environment pre-loads the following symbols by default:
+   - **Pydantic**: `BaseModel`, `Field`, `validator`, `model_validator`, `PrivateAttr`
+   - **Typing**: `List`, `Dict`, `Optional`, `Union`, `Any`, `ClassVar`
+   - **Enum**: `Enum`
+3. **Override Mechanism**: Classes defined here are automatically registered to the current document's context. If a name conflicts with an existing model, the new definition overrides the old one.
 
-Use the `entity:<ClassName>` tag on code blocks to declare an instance of that class (data).
+Use the `entity:<ClassName>` tag. You can specify an `id` in the header or within the body.
 
 ````markdown
-# This is an Entity code block, instantiating the User class above
+# ID specified in header
 
-```entity:User
+```entity:User id=alice
 name: "Alice"
 age: 30
-role: "admin"
+```
+
+# ID specified in body (YAML)
+
+```entity:User
+id: "bob"
+name: "Bob"
+age: 25
 ```
 ````