infinity-data 2.0.0__tar.gz → 2.2.0__tar.gz

{infinity_data-2.0.0/src/infinity_data.egg-info → infinity_data-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: infinity-data
-Version: 2.0.0
+Version: 2.2.0
 Summary: InfinityData：声明式配置语言（.infd/.inft）的 Python 编译器库
 Author: infinity_system: yin_bailiang
 License: MIT

{infinity_data-2.0.0 → infinity_data-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "infinity-data"
-version = "2.0.0"
+version = "2.2.0"
 description = "InfinityData：声明式配置语言（.infd/.inft）的 Python 编译器库"
 readme = "README.md"
 license = { text = "MIT" }
@@ -35,6 +35,7 @@ Documentation = "https://github.com/yinbailiang/infinity_data#readme"
 [dependency-groups]
 # 测试组：仅运行测试所需（CI test job 只装这组，更快）
 test = [
+    "pyyaml",
     "pytest>=8.0",
     "pytest-cov>=5.0",
 ]
@@ -89,7 +90,7 @@ line-ending = "lf"
 typeCheckingMode = "strict"
 reportMissingTypeStubs = false
 reportMissingImports = "error"
-exclude = ["**/node_modules", "**/__pycache__", "**/.*", ".venv"]
+exclude = ["**/node_modules", "**/__pycache__", "**/.*", ".venv", "build"]
 venvPath = "."
 venv = ".venv"
 

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/parser/__init__.py

@@ -22,6 +22,7 @@ from infinity_data.parser.models import (
     DictValue,
     Document,
     DollarValue,
+    EnvImportItem,
     EnvImportStmt,
     ErrorConstraint,
     ErrorStatement,
@@ -59,6 +60,7 @@ __all__ = [
     'DictValue',
     'Document',
     'DollarValue',
+    'EnvImportItem',
     'EnvImportStmt',
     'ErrorConstraint',
     'ErrorStatement',

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/parser/models.py

@@ -120,16 +120,30 @@ class TemplateImportStmt(AstNode):
 
 
 @dataclass
-class EnvImportStmt(AstNode):
-    """环境变量导入: !env import NAME [as NEW_NAME]"""
+class EnvImportItem(AstNode):
+    """环境变量导入项: NAME [as NEW_NAME]。"""
 
     name: str  # 环境变量名
-    alias: str | None  # 别名（可选）
+    alias: str | None = None  # 别名（可选）
 
     def canonical(self) -> str:
         if self.alias is None:
-            return f'!env import {self.name}'
-        return f'!env import {self.name} as {self.alias}'
+            return self.name
+        return f'{self.name} as {self.alias}'
+
+
+@dataclass
+class EnvImportStmt(AstNode):
+    """环境变量导入: !env import NAME1 [as NEW1], NAME2 [as NEW2], ..."""
+
+    items: list[EnvImportItem]  # 导入项列表（项之间必须用逗号分隔）
+
+    def children(self) -> Iterable[AstNode]:
+        return self.items
+
+    def canonical(self) -> str:
+        items = ', '.join(i.canonical() for i in self.items)
+        return f'!env import {items}'
 
 
 @dataclass
@@ -178,7 +192,7 @@ class FileImportStmt(AstNode):
     """配置文件导入: !file "path" as <format> import .path.to.key as alias, ..."""
 
     file_path: str  # 文件路径
-    format: str | None  # 文件格式: "yaml", "json", "toml" 或 None（自动检测后缀）
+    format: str | None  # 文件格式: "yaml", "json", "toml", "raw" 或 None（自动检测后缀）
     imports: list[FileImportItem]
 
     def children(self) -> Iterable[AstNode]:

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/parser/parser.py

@@ -17,6 +17,7 @@ from infinity_data.parser.models import (
     DictValue,
     Document,
     DollarValue,
+    EnvImportItem,
     EnvImportStmt,
     ErrorConstraint,
     ErrorStatement,
@@ -272,18 +273,29 @@ class Parser:
 
     @staticmethod
     def _parse_env_import(stream: TokenStream, collector: DiagnosticCollector, kw_tok: EnvImportToken) -> EnvImportStmt:
-        """!env import NAME [as NEW_NAME]"""
+        """!env import NAME1 [as NEW1], NAME2 [as NEW2], ..."""
         Parser._expect_keyword(stream, collector, 'import')
-        name_tok = stream.expect(IdentifierToken)
 
-        alias = None
-        if Parser._peek_keyword(stream, 'as'):
-            stream.advance()
-            alias = stream.expect(IdentifierToken).name
+        # 导入项列表（项之间必须用逗号分隔）
+        items: list[EnvImportItem] = []
+        items.append(Parser._parse_env_import_item(stream, collector))
+
+        while True:
+            tok = stream.peek()
+            if isinstance(tok, CommaToken):
+                stream.advance()
+                items.append(Parser._parse_env_import_item(stream, collector))
+            elif isinstance(tok, IdentifierToken):
+                # 同一行内空格分隔（无逗号/换行）→ 报缺失逗号，容错继续（漏逗号）
+                collector.add(diag('parse.import_missing_comma', {}, tok.raw.source))
+                items.append(Parser._parse_env_import_item(stream, collector))
+            else:
+                # 换行/EOF 等 → 导入列表结束（换行后是新的顶层语句，不是导入项）
+                break
 
-        # 导入语句必须换行/EOF 结尾：!env 无导入项列表，若不加检查，同一行的逗号会被
-        # 顶层 skip_separators 吞掉（`!env import A as a, x = 1` 被误认为合法），与
-        # !from / !file 的「尾部必须换行」行为不一致。
+        # 导入语句必须换行/EOF 结尾：若不检查，同一行的逗号会被顶层 skip_separators
+        # 吞掉（`!env import A as a, x = 1` 被误认为合法），与 !from / !file 的
+        # 「尾部必须换行」行为不一致。
         tok = stream.peek()
         # 显式排除 NoNextType 以收窄类型：stream.eof() 是方法调用，无法据此收窄 tok，
         # 否则 tok 仍为 Token | NoNextType，访问 tok.raw 会触发类型错误。
@@ -300,6 +312,22 @@ class Parser:
         # 否则语句 source 会把下一行行首吞入（与 Field 不一致）
         return EnvImportStmt(
             source=stream.span_from(kw_tok),
+            items=items,
+        )
+
+    @staticmethod
+    def _parse_env_import_item(stream: TokenStream, collector: DiagnosticCollector) -> EnvImportItem:
+        """解析单个导入项: NAME [as NEW_NAME]。"""
+        first = stream.peek()
+        name_tok = stream.expect(IdentifierToken)
+
+        alias = None
+        if Parser._peek_keyword(stream, 'as'):
+            stream.advance()
+            alias = stream.expect(IdentifierToken).name
+
+        return EnvImportItem(
+            source=stream.span_from(first),
             name=name_tok.name,
             alias=alias,
         )
@@ -890,7 +918,7 @@ class Parser:
 
         支持:
         - int, str, bool, float, list, dict, ?, object
-        - type? → one(type, ?)
+        - type? → any(type, ?)
         - <constraint, constraint, ...> → all(constraint, ...)
         - <any(...)>, <one(...)>, <not(...)>, <all(...)>
         """
@@ -929,7 +957,7 @@ class Parser:
 
                 if isinstance(stream.peek(), QuestionToken):
                     stream.advance()
-                    # 直接展开: type? → one(type, ?)
+                    # 直接展开: type? → any(type, ?)
                     return Constraints(
                         source=stream.span_from(first),
                         constraints=[Parser._nullable(ident)],
@@ -938,7 +966,7 @@ class Parser:
                 # 单约束函数调用可省略尖括号: field: regex("re") = ...
                 if isinstance(stream.peek(), LparenToken):
                     call = Parser._parse_constraint_call(stream, collector, first)
-                    # 调用后也可空: regex("re")? → one(regex("re"), ?)
+                    # 调用后也可空: regex("re")? → any(regex("re"), ?)
                     if isinstance(stream.peek(), QuestionToken):
                         stream.advance()
                         call = Parser._nullable(call)
@@ -971,10 +999,10 @@ class Parser:
 
     @staticmethod
     def _nullable(c: Constraint) -> ConstraintCall:
-        """可空包装：constraint? → one(constraint, ?)。"""
+        """可空包装：constraint? → any(constraint, ?)。"""
         return ConstraintCall(
             source=c.source,
-            name='one',
+            name='any',
             arguments=[c, ConstraintIdent(source=c.source, name='?')],
         )
 
@@ -1025,7 +1053,7 @@ class Parser:
                     message=f'无法解析的约束: {bad_tok.raw.type.name}',
                 )
 
-        # 可空后缀: constraint? → one(constraint, ?)
+        # 可空后缀: constraint? → any(constraint, ?)
         if isinstance(stream.peek(), QuestionToken):
             stream.advance()
             return Parser._nullable(base)

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/pipeline.py

@@ -137,7 +137,7 @@ def _compile(file: File, options: CompileOptions) -> CompilationResult:
                 if resolver.schema.from_file and context.schema_scope is not None
                 else context.root_scope
             )
-            key = scope.get(resolver.schema.template)
+            key = scope.visible.get(resolver.schema.template)
             if key is None:
                 raise SchemaError('schema.undefined_template', {'template': resolver.schema.template})
             tpl = std.templates[key]

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/semantic/builder/__init__.py

@@ -13,8 +13,10 @@ from infinity_data.semantic.builder.models import (
     StdDocument,
     StdField,
     StdLiteral,
+    StdNode,
     StdObject,
     StdValue,
+    is_std_node,
 )
 
 __all__ = [
@@ -24,6 +26,8 @@ __all__ = [
     'StdDocument',
     'StdField',
     'StdLiteral',
+    'StdNode',
     'StdObject',
     'StdValue',
+    'is_std_node',
 ]

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/semantic/builder/builder.py

@@ -82,9 +82,9 @@ class AstBuilder:
         # 执行期状态（每次 build 重置）
         self._templates: dict[TemplateKey, TemplateDef] = {}
         self._template_scopes: dict[TemplateKey, Scope] = {}
-        self._root_scope: Scope = {}
+        self._root_scope: Scope = Scope()
         self._schema_scope: Scope | None = None
-        self._namespace: dict[str, StdValue] = {}  # $ 引用解析目标（!env/!file/!var 统一为 StdValue）
+        # $ 命名空间按文件就地解析（§1.8）：由各 Scope 对象自身携带（scope.namespaces）
         self._collector: DiagnosticCollector = DiagnosticCollector()  # 本次 build 的共享收集器
         self._depth = 0
         self._recursive_defaults: set[TemplateKey] = set()
@@ -107,9 +107,8 @@ class AstBuilder:
         """
         self._templates = {}
         self._template_scopes = {}
-        self._root_scope = {}
+        self._root_scope = Scope()
         self._schema_scope = None
-        self._namespace = {}
         self._collector = collector
         self._depth = 0
         self._recursive_defaults = set()
@@ -119,7 +118,6 @@ class AstBuilder:
         self._template_scopes = context.template_scopes
         self._root_scope = context.root_scope
         self._schema_scope = context.schema_scope
-        self._namespace = context.namespace
 
         # 静态防护：默认值引用环检测（默认值禁止自引用，见 neo_desg.md 2.6）
         self._detect_recursive_defaults()
@@ -127,8 +125,8 @@ class AstBuilder:
         # 模板配置校验：extra_*_vars 指向的字段必须在模板中声明（§2.9，定义即报错）
         self._check_variadic_config()
 
-        # !var 求值（§2.10）：root 构建前填充 $ 命名空间（前向引用 + 环检测）
-        self._resolve_var_statements(doc)
+        # !var 求值（§2.10）：root 构建前按文件填充 $ 命名空间（前向引用 + 环检测，就地解析）
+        self._resolve_var_statements(context)
 
         # 构建 root（顶层结构约束挂在 root.constraints，不执行）
         root_fields: list[StdField] = []
@@ -160,25 +158,44 @@ class AstBuilder:
         return StdDocument(
             root=StdObject(fields=self._finalize_object(root_fields, ''), constraints=root_constraints),
             templates=dict(self._templates),
-            scope=dict(self._root_scope),
+            scope=dict(self._root_scope.visible),
         )
 
     # ═══════════════════════════════════════════════════════
     # !var 求值（§2.10）
     # ═══════════════════════════════════════════════════════
 
-    def _resolve_var_statements(self, doc: Document) -> None:
-        """!var 求值：静态依赖图 + 环检测 + 拓扑求值 + path 投影，填充 $ 命名空间。
+    def _resolve_var_statements(self, context: ResolvedContext) -> None:
+        """!var 求值（按文件就地解析，§1.8）：每文件独立依赖图 + 环检测 + 拓扑求值。
 
         在 root 构建之前调用——前向引用经拓扑序天然支持；依赖环 → ``var.cycle``。
-        值构造（模板展开 / 解包 / $ 引用）全部复用 :meth:`_resolve_value`。
+        值构造（模板展开 / 解包 / $ 引用）全部复用 :meth:`_resolve_value`，
+        用**该文件**的 scope 就地解析、绑定**该文件**的 $ 命名空间（跨文件完全隔离）。
+        ``!var`` 语句由 scope 对象携带（``scope.var_statements``），此处遍历全部文件 scope。
+        Scope 按身份相等且可哈希（dataclass eq=False），直接用 set 去重。
         """
-        stmts = [s for s in doc.statements if isinstance(s, VarStmt)]
-        if not stmts:
-            return
+        seen: set[Scope] = set()
+        for scope in self._iter_scopes(context):
+            if scope in seen:
+                continue  # 同一 scope 被多模板共享，只处理一次
+            seen.add(scope)
+            if scope.var_statements:
+                self._resolve_var_file(scope, scope.var_statements)
+
+    def _iter_scopes(self, context: ResolvedContext) -> list[Scope]:
+        """context 中全部文件 scope（root + 各定义点 + schema 隐式导入）。"""
+        scopes: list[Scope] = [context.root_scope]
+        if context.schema_scope is not None:
+            scopes.append(context.schema_scope)
+        scopes.extend(context.template_scopes.values())
+        return scopes
+
+    def _resolve_var_file(self, scope: Scope, stmts: list[VarStmt]) -> None:
+        """单个文件内 !var 求值（用该文件 scope 解析，绑定该文件命名空间）。"""
+        namespace = scope.namespaces
         by_alias = {s.alias: i for i, s in enumerate(stmts)}
 
-        # 1) 依赖图：!var 的 $ 引用指向其他 !var 别名 → 边（walk 静态提取）
+        # 1) 依赖图：!var 的 $ 引用指向同文件其他 !var 别名 → 边（walk 静态提取）
         deps: dict[int, set[int]] = {}
         for i, s in enumerate(stmts):
             dep_indices: set[int] = set()
@@ -208,10 +225,10 @@ class AstBuilder:
         for i in range(len(stmts)):
             visit(i)
 
-        # 3) 拓扑序求值 → path 投影 → 填 namespace（duplicate 检测）
+        # 3) 拓扑序求值 → path 投影 → 填本文件命名空间（duplicate 检测）
         for i in order:
             s = stmts[i]
-            rv = self._resolve_value(s.value, '', self._root_scope)
+            rv = self._resolve_value(s.value, '', scope)
             if rv is None:
                 continue  # 值解析失败已报告
             if s.json_path:
@@ -220,10 +237,10 @@ class AstBuilder:
                 except (KeyError, IndexError, TypeError):
                     self._err('var.path_failed', {'alias': s.alias}, s.source, '')
                     continue
-            if s.alias in self._namespace:
+            if s.alias in namespace:
                 self._err('namespace.duplicate', {'name': s.alias}, s.source, '')
                 continue
-            self._namespace[s.alias] = rv
+            namespace[s.alias] = rv
 
     # ═══════════════════════════════════════════════════════
     # 递归默认值防护（方案 C：默认引用图 + 静态环检测）
@@ -299,7 +316,7 @@ class AstBuilder:
             return
         for node in walk(v):
             if isinstance(node, TemplateCallValue):
-                k = scope.get(node.template_name)
+                k = scope.visible.get(node.template_name)
                 if k is not None:
                     yield k, node.source
 
@@ -401,7 +418,7 @@ class AstBuilder:
         """数组元素 noexist → 报错并按 null（保留位置）。"""
         if isinstance(value, StdLiteral) and value.kind == 'noexist':
             self._err('value.noexist_in_array', {}, source, path)
-            return StdLiteral(kind='null', value=None)
+            return StdLiteral(kind='null', value=None, source=source)
         return value
 
     def _bind_to_std(self, value: Value | StdValue, path: str, scope: Scope) -> StdValue:
@@ -430,7 +447,7 @@ class AstBuilder:
                 case LiteralValue(value=tok):
                     return self._convert_literal(tok)
                 case DollarValue(name=n, type_cast=tc, source=src):
-                    return self._resolve_dollar(n, tc, path, src)
+                    return self._resolve_dollar(n, tc, path, src, scope)
                 case DictValue(fields=fs, constraints=cs, unpacks=ups):
                     std_fields: list[StdField] = []
                     # **expr 解包：目标必须是 dict，展开为键值对（disjoint merge 查重在 _finalize_object）
@@ -447,7 +464,11 @@ class AstBuilder:
                     # dict 结构级约束（作用于该字面量整体）：解析后挂节点，不执行
                     specs, diags = resolve_constraint_list(cs, scope)
                     self._collector.extend(diags)
-                    return StdObject(fields=self._finalize_object(std_fields, path), constraints=specs)
+                    return StdObject(
+                        fields=self._finalize_object(std_fields, path),
+                        constraints=specs,
+                        source=raw.source,
+                    )
                 case ArrayValue(elements=els):
                     std_elements: list[StdValue] = []
                     for i, e in enumerate(els):
@@ -462,7 +483,7 @@ class AstBuilder:
                         if rv is None:
                             continue
                         std_elements.append(self._array_noexist(rv, e.source, f'{path}[{i}]'))
-                    return StdArray(elements=std_elements)
+                    return StdArray(elements=std_elements, source=raw.source)
                 case TemplateCallValue(
                     template_name=tn,
                     positional_args=pa,
@@ -489,39 +510,51 @@ class AstBuilder:
         self,
         tok: StringToken | IntegerToken | FloatToken | BoolToken | NullToken | NoexistToken,
     ) -> StdLiteral:
-        """将字面量 Token 转为 StdLiteral。"""
+        """将字面量 Token 转为 StdLiteral（携带 token 在源文档中的位置）。"""
         match tok:
             case StringToken(value=v):
-                return StdLiteral(kind='str', value=v)
+                return StdLiteral(kind='str', value=v, source=tok.raw.source)
             case IntegerToken(value=v):
-                return StdLiteral(kind='int', value=v)
+                return StdLiteral(kind='int', value=v, source=tok.raw.source)
             case FloatToken(value=v):
-                return StdLiteral(kind='float', value=v)  # Decimal，含 NaN/±Inf
+                return StdLiteral(kind='float', value=v, source=tok.raw.source)  # Decimal，含 NaN/±Inf
             case BoolToken(value=v):
-                return StdLiteral(kind='bool', value=v)
+                return StdLiteral(kind='bool', value=v, source=tok.raw.source)
             case NullToken():
-                return StdLiteral(kind='null', value=None)
+                return StdLiteral(kind='null', value=None, source=tok.raw.source)
             case NoexistToken():
-                return StdLiteral(kind='noexist', value=None)
+                return StdLiteral(kind='noexist', value=None, source=tok.raw.source)
         raise TypeError(f'未知字面量 token 类型: {type(tok)}')
 
     def _resolve_dollar(
-        self, name: str, type_cast: str | None, path: str, source: SourceRange | None = None
+        self,
+        name: str,
+        type_cast: str | None,
+        path: str,
+        source: SourceRange | None = None,
+        scope: Scope | None = None,
     ) -> StdValue:
-        """解析 ``$name`` 引用，type_cast 为显式 as bool/int/float/str 转换。
+        """解析 ``$name`` 引用（按书写位置的 scope 就地查该文件 $ 命名空间，§1.8）。
 
-        source 为 ``$name`` 表达式在源码中的位置
+        type_cast 为显式 as bool/int/float/str 转换；source 为 ``$name`` 表达式在源码中的位置。
+        本文件空间查不到 → ``dollar.undefined`` 警告取 null（不中断编译）。
         """
-        if name not in self._namespace:
+        namespace = scope.namespaces if scope is not None else {}
+        if name not in namespace:
             self._warn('dollar.undefined', {'name': name}, source, path)
-            return StdLiteral(kind='null', value=None)
+            return StdLiteral(kind='null', value=None, source=source)
 
-        raw = self._namespace[name]
+        raw = namespace[name]
         # namespace 统一存 StdValue（!env/!file/!var 均由 python_to_std / 求值产出）
         if type_cast is None:
             return raw
         if isinstance(raw, (StdArray, StdObject)):
             return raw  # 结构化值 cast 不适用
+        # 空字面量：as 转换**保持传播**（null → null、noexist → noexist），
+        # 不做任何转换、不产生警告——三态可空语义不因显式 as 而丢失
+        # （此时 raw 已收窄为 StdLiteral）
+        if raw.kind in ('null', 'noexist'):
+            return raw
         raw = raw.value  # StdLiteral：提取 Python 值走转换
 
         match type_cast:
@@ -558,10 +591,10 @@ class AstBuilder:
                         )
                     )
                     val = False
-                return StdLiteral(kind='bool', value=val)
+                return StdLiteral(kind='bool', value=val, source=source)
             case 'int':
                 try:
-                    return StdLiteral(kind='int', value=int(cast(Any, raw)))
+                    return StdLiteral(kind='int', value=int(cast(Any, raw)), source=source)
                 except (ValueError, TypeError):
                     self._collector.add(
                         Diagnostic(
@@ -572,10 +605,10 @@ class AstBuilder:
                             path,
                         )
                     )
-                    return StdLiteral(kind='int', value=0)
+                    return StdLiteral(kind='int', value=0, source=source)
             case 'float':
                 try:
-                    return StdLiteral(kind='float', value=decimal.Decimal(str(raw)))
+                    return StdLiteral(kind='float', value=decimal.Decimal(str(raw)), source=source)
                 except (ValueError, TypeError, decimal.InvalidOperation):
                     self._collector.add(
                         Diagnostic(
@@ -586,11 +619,22 @@ class AstBuilder:
                             path,
                         )
                     )
-                    return StdLiteral(kind='float', value=decimal.Decimal(0))
+                    return StdLiteral(kind='float', value=decimal.Decimal(0), source=source)
             case 'str':
-                return StdLiteral(kind='str', value=str(raw))
+                # as str = 字符串化：任意字面量按**语言字面量风格**转为字符串，
+                # 保证可 round-trip 还原回原值（bool → true/false、float 特殊值
+                # → nan/+inf/-inf），不泄漏 Python 内部表示；null/noexist 已在上方
+                # 保持传播，不进入本分支
+                if isinstance(raw, bool):
+                    return StdLiteral(kind='str', value='true' if raw else 'false', source=source)
+                if isinstance(raw, decimal.Decimal):
+                    if raw.is_nan():
+                        return StdLiteral(kind='str', value='nan', source=source)
+                    if raw.is_infinite():
+                        return StdLiteral(kind='str', value='+inf' if raw > 0 else '-inf', source=source)
+                return StdLiteral(kind='str', value=str(raw), source=source)
             case _:
-                return StdLiteral(kind='str', value=str(raw))
+                return StdLiteral(kind='str', value=str(raw), source=source)
 
     # ═══════════════════════════════════════════════════════
     # 模板展开
@@ -709,7 +753,7 @@ class AstBuilder:
         for combo in combos:
             pa, na, upa, upk = self._build_expand_args(pos_args, named, unpack_args, unpack_kwargs, axes, combo)
             results.append(self._instantiate_once(template_name, pa, na, upa, upk, path, source, scope))
-        return StdArray(elements=results)
+        return StdArray(elements=results, source=source)
 
     def _resolve_axis(
         self,
@@ -782,7 +826,7 @@ class AstBuilder:
         解包：``*expr``（list → 位置参数）/ ``**expr``（dict → 命名参数）；
         解包键与已有参数冲突 → ``dict.duplicate_key``（disjoint merge，§2.7）。
         """
-        key = scope.get(template_name)
+        key = scope.visible.get(template_name)
         if key is None:
             self._collector.add(
                 Diagnostic(Severity.ERROR, 'template.undefined', {'template': template_name}, source, path)
@@ -931,14 +975,19 @@ class AstBuilder:
             if tf.name in param_values:
                 pv = param_values[tf.name]
                 v = self._bind_to_std(pv, child, scope)
+                # 字段位置 = 调用点参数表达式（值无来源时回退至此，而非模板定义）；
+                # 展开轴元素等彻底无来源时最后回退模板定义（避免丢失位置）
+                field_src = getattr(pv, 'source', None) or v.source or tf.source
             elif tf.default_value is not None:
                 v = self._resolve_value(tf.default_value, child, inner_scope)
+                # 字段位置 = 默认值表达式（模板定义内）
+                field_src = v.source if v is not None else tf.source
             else:
                 continue  # 必填且未提供 → 已在上面报错
 
             specs, diags = resolve_constraints(tf.constraints, inner_scope)
             self._collector.extend(diags)
-            std_fields.append(StdField(name=tf.name, value=v, source=tf.source, constraints=specs))
+            std_fields.append(StdField(name=tf.name, value=v, source=field_src, constraints=specs))
 
         # allow_extra=true：额外字段作为扩展字段进入内容（按调用点 scope 解析）
         for name, (arg_val, arg_src) in extra_args.items():
@@ -949,4 +998,9 @@ class AstBuilder:
         # 模板级约束（: 起始，约束整个 dict）：解析后挂到实例节点
         tpl_specs, tpl_diags = resolve_constraint_list(template.constraints, inner_scope)
         self._collector.extend(tpl_diags)
-        return StdObject(fields=self._finalize_object(std_fields, path), template=key, constraints=tpl_specs)
+        return StdObject(
+            fields=self._finalize_object(std_fields, path),
+            template=key,
+            constraints=tpl_specs,
+            source=source,
+        )

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/semantic/builder/models.py

@@ -24,14 +24,16 @@ from infinity_data.semantic.std import (
     StdArray,
     StdField,
     StdLiteral,
+    StdNode,
     StdObject,
     StdValue,
+    is_std_node,
     is_std_value,
     python_to_std,
 )
 
 if TYPE_CHECKING:
-    from infinity_data.semantic.resolver.models import Scope, TemplateKey
+    from infinity_data.semantic.resolver.models import TemplateKey
 
 __all__ = [
     'LiteralKind',
@@ -40,8 +42,10 @@ __all__ = [
     'StdDocument',
     'StdField',
     'StdLiteral',
+    'StdNode',
     'StdObject',
     'StdValue',
+    'is_std_node',
     'is_std_value',
     'python_to_std',
 ]
@@ -58,8 +62,10 @@ class StdDocument:
 
     - ``root``：编译产物（顶层对象）
     - ``templates``：全部已加载模板（:class:`TemplateKey` → 定义，含 ``!from`` 导入的）
-    - ``scope``：**入口文件**的可见名表（可见名 → :class:`TemplateKey`），
-      与 ``templates`` 配合可完整解析：可见名 → TemplateKey → TemplateDef
+    - ``scope``：**入口文件**的可见名表快照（可见名 → :class:`TemplateKey`），
+      与 ``templates`` 配合可完整解析：可见名 → TemplateKey → TemplateDef。
+      纯快照（普通 dict）：各文件的 `$` 命名空间 / !var 关联在 Phase 1 的
+      :class:`Scope` 上（§1.8），不随产物下发。
 
     不携带诊断：所有诊断经共享 :class:`DiagnosticCollector` 收集，
     由流水线在 :class:`CompilationResult` 上承载——诊断不属于文档数据。
@@ -67,4 +73,4 @@ class StdDocument:
 
     root: StdObject = field(default_factory=StdObject)
     templates: dict[TemplateKey, TemplateDef] = field(default_factory=lambda: {})
-    scope: Scope = field(default_factory=lambda: {})
+    scope: dict[str, TemplateKey] = field(default_factory=lambda: {})

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/semantic/constraints.py

@@ -38,7 +38,7 @@ _INVALID_CONSTRAINT = '@invalid'
 def expand_annotation(annotation: Constraints) -> Constraints:
     """展开约束语法糖：多约束 ``<a, b, c>`` → ``all(a, b, c)``。
 
-    （``type?`` → ``one(type, ?)`` 已在 parser 阶段展开。）
+    （``type?`` → ``any(type, ?)`` 已在 parser 阶段展开。）
     """
     if len(annotation.constraints) > 1:
         return Constraints(
@@ -141,7 +141,7 @@ def resolve_constraint_arg(c: Constraint, scope: Scope) -> tuple[Any, list[Diagn
 
 def translate_name(name: str, scope: Scope) -> str:
     """可见名 → 真名字符串。未命中（如 has(field) 的裸字段名）保留原名。"""
-    key = scope.get(name)
+    key = scope.visible.get(name)
     return str(key) if key is not None else name
 
 

{infinity_data-2.0.0 → infinity_data-2.2.0}/src/infinity_data/semantic/diagnostics.py

@@ -171,6 +171,10 @@ register_diagnostic_define(
     diagnostic_define('constraint.size_out', '{path_prefix}大小 {size} 不在范围 [{lo}, {hi}] 内'),
     diagnostic_define('constraint.each_need', '{path_prefix}each() 需要一个约束参数'),
     diagnostic_define('constraint.each_only', '{path_prefix}each 约束适用于 list/dict，实际 {actual}'),
+    diagnostic_define('constraint.position_only', '{path_prefix}position 约束只适用于 list，实际 {actual}'),
+    diagnostic_define('constraint.position_index', '{path_prefix}position 下标必须是整数: {value!r}'),
+    diagnostic_define('constraint.position_need', '{path_prefix}position() 需要一个约束参数'),
+    diagnostic_define('constraint.position_out', '{path_prefix}下标 {index} 越界（list 大小 {size}）'),
     diagnostic_define('constraint.in_not_in', '{path_prefix}值 {value} 不在允许的值 {choices!r} 中'),
     diagnostic_define('constraint.string_only', '{path_prefix}{constraint} 约束只适用于字符串'),
     diagnostic_define('constraint.invalid_value', '{path_prefix}无效的{what} {value!r}'),