feat(tsl-syntax-reference): harden retrieval contracts

Add stable section IDs, structural and routing regressions, quickstart consistency checks, and CI enforcement.

BREAKING CHANGE: replace heading-derived Section IDs with explicit syntax-NN-NNN identifiers.
This commit is contained in:
csh
2026-07-31 10:05:15 +08:00
parent 21e688a436
commit 736d1a8ad7
30 changed files with 1635 additions and 137 deletions
@@ -4,10 +4,16 @@
## 本篇职责
<!-- section-id: syntax-08-001 -->
回答“`type Name = class`、字段、`static`、方法、`property`、析构、类类型、继承和对象创建在 TSL 里怎样写”。
## 核心规则
<!-- section-id: syntax-08-002 -->
<!-- quickstart-rule: class-shape -->
- 类定义统一按 `type Name = class ... end;` 写。
- 顶层类声明可以放在松散语句之后(单向允许)。
- 顶层类声明也可以放在顶层 `function / procedure` 之后。
@@ -36,6 +42,7 @@
- 基础覆盖写法是:父类方法声明为 `virtual`,子类对应方法声明为 `override`
- 基础祖先类调用:可以用 `Inherited;``Inherited MethodName(...)``class(BaseClass, ObjectName).MethodName()`
- 创建对象有两种方式:`new ClassName()` 最常用,`createObject(...)` 作为次选。
<!-- quickstart-rule: object-creation -->
- 普通本地类实例化默认生成 `new ClassName()``createObject("ClassName")``createObject(ClassType)` 只在字符串类名、类类型变量或跨 `unit` 路径场景生成。
- 如果类里定义了 `function create(...)``new``createObject("ClassName", ...)``createObject(ClassType, ...)` 都可以透传构造参数,也都支持默认参数和命名参数。
- 析构写法是无参 `function destroy();`;对象的最后一个引用被清空(如设为 `nil`)时会触发它。存在别名引用时,只清空其中一个引用不会触发。
@@ -51,6 +58,8 @@
## 可直接照写示例
<!-- section-id: syntax-08-003 -->
使用这些示例时遵守:
- 普通本地类创建优先复制 `new ClassName()` 形态。
@@ -59,6 +68,8 @@
### 最小类与声明位置
<!-- section-id: syntax-08-004 -->
<!-- tags: 定义一个类, 定义类, 类怎么写, 最短类, 类放在哪, 类骨架 -->
最短类骨架:
@@ -169,6 +180,8 @@ writeLn(a);
### 字段、静态成员、常量与可见性
<!-- section-id: syntax-08-005 -->
<!-- tags: 成员变量, 静态成员, 类常量, 私有公开, 属性可见性, 只有类自己能访问 -->
`static` 字段:
@@ -383,6 +396,8 @@ end;
### 构造函数边界
<!-- section-id: syntax-08-006 -->
<!-- tags: 构造方法, 新建时初始化, create 怎么写, 带参数创建 -->
`create` 建议保持 `public`
@@ -412,6 +427,8 @@ end;
### 属性、类型注解与类外实现
<!-- section-id: syntax-08-007 -->
<!-- tags: property, 读写属性, getter setter, 方法写在类外 -->
基础 `property`
@@ -745,6 +762,8 @@ end;
### 对象创建与类类型
<!-- section-id: syntax-08-008 -->
<!-- tags: 创建对象, 实例化, new 怎么用, 拿到类本身, 动态建对象 -->
`new` 关键字:
@@ -897,6 +916,8 @@ end;
### 重载、继承与析构
<!-- section-id: syntax-08-009 -->
<!-- tags: 继承, 父类子类, 方法重载, 同名不同参, 析构, 对象销毁时, 调用父类方法, 父类同名方法, inherited -->
`overload` 方法:
@@ -1302,6 +1323,8 @@ end;
### 跨 unit 类路径
<!-- section-id: syntax-08-010 -->
<!-- tags: 跨文件的类, 跨文件继承, 类的完整路径 -->
`unit` 中的嵌套类路径创建属于跨 `unit` 边界,这里用 `text` 展示骨架:
@@ -1396,6 +1419,8 @@ writeLn(0);
## 默认生成模板
<!-- section-id: syntax-08-011 -->
最短类骨架直接复用本页开头的“最短类骨架”。
代码块身份:可直接照写示例
@@ -1407,6 +1432,8 @@ end;
## 禁止项
<!-- section-id: syntax-08-012 -->
- 以下误写不可照写;本节只收容易被智能体从相近语言或相邻 TSL 写法外推出来的边界,不重复列已经在核心规则里明确的普通规则。
- 不把裸类名成员访问当成文档事实;类方法和静态字段默认用 `class(Name).Member` 或文档明确反射入口。
-`self()` 当成本页明确的工厂式写法。