infinity-data 1.0.0__py3-none-any.whl

infinity_data/parser/token_stream.py

@@ -0,0 +1,128 @@
+"""LL(1) Token 流包装器，继承 LL1Stream[Token]，自动追踪 source range。
+
+全链路流式：CharStream → RawToken → Token → AST。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TypeVar
+
+from infinity_data.infra.diagnostics import DiagnosticCollector
+from infinity_data.infra.ll1_stream import LL1Stream, NoNextType
+from infinity_data.parser.diagnostics import diag
+from infinity_data.tokenizer.models.raw_tokens import (
+    RawToken,
+    RawTokenType,
+    SourceRange,
+)
+from infinity_data.tokenizer.models.tokens import (
+    CommaToken,
+    EofToken,
+    NewlineToken,
+    Token,
+)
+
+_TToken = TypeVar('_TToken', bound=Token)
+
+
+class TokenStream(LL1Stream[Token]):
+    """LL(1) Token 流，继承 LL1Stream[Token]"""
+
+    def __init__(
+        self,
+        source: Iterable[Token],
+        error_collector: DiagnosticCollector,
+    ) -> None:
+        super().__init__(source)
+        self._errors: DiagnosticCollector = error_collector
+        self._last: Token | None = None
+
+    # ── LL1Stream 钩子 ────────────────────────────────────
+
+    def _on_advance(self, item: Token) -> None:
+        """消费每个 token 时记录，用于 range 追踪。"""
+        self._last = item
+
+    def check(self, expect: RawTokenType) -> bool:
+        token = self.peek()
+        if isinstance(token, NoNextType):
+            return False
+        return token.raw.type == expect
+
+    def eof(self) -> bool:
+        """结束判定：当前 token 为 EofToken，或流已物理耗尽（哨兵被消费后）。
+
+        EofToken 是 FinalTokenizer 产出的哨兵 token；基类 :class:`LL1Stream` 的
+        ``eof()`` 只认物理耗尽（哨兵被消费后才为 True），此处统一为「哨兵即结束」
+        ——解析循环无需再区分 ``check(EOF)`` 与 ``eof()``。
+        """
+        return isinstance(self.peek(), (EofToken, NoNextType))
+
+    # ── 跳过 ───────────────────────────────────────
+
+    def skip_newlines(self) -> None:
+        """跳过连续的换行"""
+        while not self.eof() and isinstance(self.peek(), NewlineToken):
+            self.advance()
+
+    def skip_separators(self) -> bool:
+        """跳过逗号和换行（元素分隔符）。
+
+        Returns:
+            是否消费了至少一个分隔符——区分「有分隔符」与「无分隔符」：
+            元素之间必须显式分隔，空格不构成分隔符。
+        """
+        saw = False
+        while not self.eof() and isinstance(self.peek(), (CommaToken, NewlineToken)):
+            self.advance()
+            saw = True
+        return saw
+
+    # ── Range 追踪 ────────────────────────────────────────
+
+    def span_from(self, first: Token | NoNextType | None) -> SourceRange:
+        """计算从 first 到当前最后消费 token 的 SourceRange。"""
+        if isinstance(first, NoNextType) or first is None:
+            first = self._last
+        if isinstance(first, NoNextType) or first is None:
+            return SourceRange.empty()
+        last = self._last if self._last else first
+        return SourceRange(file=first.raw.source.file, start=first.raw.source.start, end=last.raw.source.end)
+
+    @staticmethod
+    def single_span(token: Token) -> SourceRange:
+        """为单个 token 创建 SourceRange。"""
+        return SourceRange(file=token.raw.source.file, start=token.raw.source.start, end=token.raw.source.end)
+
+    # ── 期望 / 错误恢复 ─────────────────────────────
+
+    def expect(self, token_cls: type[_TToken]) -> _TToken:
+        """期望当前 token 为指定类型，否则收集错误并插入合成 token。
+
+        错误恢复策略：记录 UnexpectedTokenError → 消费意外 token → 返回合成 token。
+        合成 token 保证调用方拿到类型安全的对象，解析器始终前进，避免级联崩溃。
+        """
+        tok = self.peek()
+        if isinstance(tok, NoNextType):
+            rng = self.span_from(None)
+            self._errors.add(diag('parse.unexpected_token', {'expected': token_cls.__name__, 'actual': 'EOF'}, rng))
+            return self._synthetic(token_cls, source=rng)
+        if not isinstance(tok, token_cls):
+            self._errors.add(
+                diag(
+                    'parse.unexpected_token',
+                    {'expected': token_cls.__name__, 'actual': tok.raw.type.name},
+                    tok.raw.source,
+                )
+            )
+            self.advance()
+            return self._synthetic(token_cls, source=tok.raw.source)
+        self.advance()
+        return tok
+
+    def _synthetic(self, token_cls: type[_TToken], *, source: SourceRange | None = None) -> _TToken:
+        """构造合成 token（错误恢复用）。"""
+        rng = source or self.span_from(None)
+        raw = RawToken(type=RawTokenType.EOF, raw='', source=rng)
+        return token_cls(raw=raw)

infinity_data/pipeline.py

@@ -0,0 +1,252 @@
+"""编译流水线：源码字符串 → StdDocument / Python dict。
+
+全链路流式：chars → RawTokenizer → FinalTokenizer → Parser → AstBuilder → Executor → Converter。
+
+公共 API：
+- :func:`load` / :func:`compile_source`：编译入口，返回 :class:`CompilationResult`
+- :func:`safe_load`：零信任加载（deny_all 沙盒，禁止一切导入）
+- :func:`check`：仅校验，返回诊断列表
+- :func:`compile_document`：编译为 StdDocument（不降维）
+
+共享选项（env/sandbox/registry/schema）统一由 :class:`CompileOptions` 承载，
+各入口不再逐参数重复声明/转发。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from functools import cached_property
+from pathlib import Path
+from typing import Any
+
+from infinity_data.emit import reduce_object
+from infinity_data.frontend import parse_source
+from infinity_data.infra.diagnostics import Diagnostic, DiagnosticCollector, Severity
+from infinity_data.infra.file import DiskFile, File, MemFile
+from infinity_data.sandbox import Sandbox, SandboxConfig, SandboxError, Schema, SchemaError
+from infinity_data.semantic.builder import AstBuilder, StdDocument
+from infinity_data.semantic.executor import ConstraintExecutor
+from infinity_data.semantic.registry import ConstraintRegistry
+from infinity_data.semantic.resolver import ImportResolver, TemplateGraphResolver
+
+
+@dataclass(frozen=True)
+class CompileOptions:
+    """一次编译的共享选项（各公共入口的统一参数载体）。
+
+    - ``env``：环境变量便捷授权，等价于 ``SandboxConfig(env=...)``，与 ``sandbox`` 合并
+    - ``sandbox``：沙盒配置；``None`` = 零信任（deny_all，库默认）
+    - ``registry``：自定义约束注册表；``None`` = 内置
+    - ``schema``：顶层模板约束；``None`` = 不校验
+    """
+
+    env: Mapping[str, str] | None = None
+    sandbox: SandboxConfig | None = None
+    registry: ConstraintRegistry | None = None
+    schema: Schema | None = None
+
+    def effective_sandbox(self) -> SandboxConfig:
+        """env 合并进 sandbox 得实际生效配置；两者均缺省 → deny_all（零信任，库默认）。"""
+        if self.sandbox is None:
+            return SandboxConfig(env=dict(self.env)) if self.env is not None else SandboxConfig.deny_all()
+        if self.env is not None:
+            return replace(self.sandbox, env={**self.sandbox.env, **dict(self.env)})
+        return self.sandbox
+
+
+@dataclass
+class CompilationResult:
+    """一次编译的完整产物（根产物 + 诊断）。
+
+    - ``document``：:class:`StdDocument`（纯数据：root / templates / scope；诊断见 ``diagnostics``）
+    - ``root`` / ``value``：由 ``document`` 派生（惰性）——降维属 emit 层职责，
+      编译阶段不急于产出，访问时经 :mod:`infinity_data.emit` 计算
+    """
+
+    document: StdDocument
+    diagnostics: list[Diagnostic] = field(default_factory=lambda: [])
+
+    @cached_property
+    def value(self) -> dict[str, Any]:
+        """降维后的纯 Python dict（惰性，由 emit 层负责；尽力而为）。"""
+        return reduce_object(self.document.root)
+
+    @property
+    def has_errors(self) -> bool:
+        return any(d.severity is Severity.ERROR for d in self.diagnostics)
+
+    @property
+    def warnings(self) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.severity is Severity.WARNING]
+
+
+def _sorted_diagnostics(collector: DiagnosticCollector) -> list[Diagnostic]:
+    """收集器快照 → 按位置排序（末端归一化，成功与异常路径共用）。"""
+    return sorted(collector, key=lambda d: d.sort_key())
+
+
+def _compile(file: File, options: CompileOptions) -> CompilationResult:
+    """统一编译核心：File + CompileOptions → CompilationResult。
+
+    三阶段语义流水线在此**顶层组装**（各阶段互相零耦合，仅经数据模型）：
+
+    Phase 1（导入求解）→ :class:`ResolvedContext`
+      → Phase 2a（AST 构建）→ :class:`StdDocument`
+      → Phase 2b（约束执行 + schema 校验）→ 校验后的 root
+
+    诊断：单一 :class:`DiagnosticCollector` 从词法到语义全程复用，
+    末端仅做位置排序快照，无多集合事后合并。
+    """
+    text = file.read()
+    # 空源码 → 空配置
+    if not text.strip():
+        return CompilationResult(document=StdDocument())
+
+    # 单一诊断收集器：词法 → 语法 → 语义（Phase 1/2a/2b）全程复用
+    collector = DiagnosticCollector()
+    doc, _ = parse_source(file, collector)
+
+    sandbox_impl = Sandbox(
+        config=options.effective_sandbox(),
+        base_dir=file.root_path,
+    )
+    import_resolver = ImportResolver(sandbox=sandbox_impl)
+    resolver = TemplateGraphResolver(
+        registry=options.registry,
+        import_resolver=import_resolver,
+        schema=options.schema,
+    )
+    try:
+        # Phase 1：导入求解（模板图 / 可见名表 / 数据命名空间）
+        context = resolver.resolve(doc, file, collector)
+
+        # Phase 2a：AST 构建（约束挂载未执行）
+        std = AstBuilder().build(doc, context, collector)
+
+        # Phase 2b：约束执行 + 顶层 schema 校验（两阶段共享同一注册表实例）
+        executor = ConstraintExecutor(
+            registry=resolver.registry,
+            templates=std.templates,
+            template_scopes=context.template_scopes,
+        )
+        executor.validate(std.root, collector)
+        if resolver.schema is not None:
+            scope = (
+                context.schema_scope
+                if resolver.schema.from_file and context.schema_scope is not None
+                else context.root_scope
+            )
+            key = scope.get(resolver.schema.template)
+            if key is None:
+                raise SchemaError('schema.undefined_template', {'template': resolver.schema.template})
+            tpl = std.templates[key]
+            root = executor.apply_schema(std.root, resolver.schema, tpl, context.template_scopes[key], collector)
+            std = replace(std, root=root)
+    except SandboxError as e:
+        # 沙盒/schema 违规 → 追加到共享收集器（保留此前已收集的诊断），返回空文档（不抛出）
+        collector.add(Diagnostic(Severity.ERROR, e.code, dict(e.params), e.source))
+        return CompilationResult(
+            document=StdDocument(),
+            diagnostics=_sorted_diagnostics(collector),
+        )
+
+    # 末端：StdDocument 纯数据（不携带诊断）；诊断全部由收集器快照承载
+    document = StdDocument(
+        root=std.root,
+        templates=std.templates,
+        scope=std.scope,
+    )
+    return CompilationResult(
+        document=document,
+        diagnostics=_sorted_diagnostics(collector),
+    )
+
+
+def load(
+    path: str | Path,
+    *,
+    env: Mapping[str, str] | None = None,
+    sandbox: SandboxConfig | None = None,
+    registry: ConstraintRegistry | None = None,
+    schema: Schema | None = None,
+) -> CompilationResult:
+    """加载 .infd/.inft 文件并编译。
+
+    Args:
+        path: 文件路径（相对导入以此为基准）
+        其余选项（env/sandbox/registry/schema）见 :class:`CompileOptions`
+
+    沙盒/schema 违规不抛出：由编译核心转为 ERROR 诊断，返回空文档。
+    """
+    return _compile(
+        DiskFile.from_fullpath(path),
+        CompileOptions(env=env, sandbox=sandbox, registry=registry, schema=schema),
+    )
+
+
+def compile_source(
+    source: str,
+    *,
+    file_path: str = 'unknown',
+    env: Mapping[str, str] | None = None,
+    sandbox: SandboxConfig | None = None,
+    registry: ConstraintRegistry | None = None,
+    schema: Schema | None = None,
+) -> CompilationResult:
+    """编译源码字符串，返回 CompilationResult（选项见 :class:`CompileOptions`）。"""
+    file = MemFile(name=file_path, root_path=Path(file_path).parent, content=source)
+    return _compile(
+        file,
+        CompileOptions(env=env, sandbox=sandbox, registry=registry, schema=schema),
+    )
+
+
+def safe_load(
+    path: str | Path,
+    *,
+    registry: ConstraintRegistry | None = None,
+    schema: Schema | None = None,
+) -> CompilationResult:
+    """零信任加载：等价于 ``load(path, sandbox=SandboxConfig.deny_all())``。
+
+    所有导入语句（``!env`` / ``!file`` / ``!from``）均报错。
+    只允许纯字段定义、模板定义与字面量值。
+
+    用途:
+    - 读取沙盒配置文件（自举：SandboxConfig.from_dict）
+    - 读取纯模板文件 (.inft)
+    - 读取不需要外部资源的配置
+    """
+    return _compile(
+        DiskFile.from_fullpath(path),
+        CompileOptions(sandbox=SandboxConfig.deny_all(), registry=registry, schema=schema),
+    )
+
+
+def check(
+    path: str | Path,
+    *,
+    env: Mapping[str, str] | None = None,
+    sandbox: SandboxConfig | None = None,
+    registry: ConstraintRegistry | None = None,
+    schema: Schema | None = None,
+) -> list[Diagnostic]:
+    """仅校验，不输出。沙盒/schema 违规已由编译核心转为 ERROR 诊断。"""
+    return load(path, env=env, sandbox=sandbox, registry=registry, schema=schema).diagnostics
+
+
+def compile_document(
+    path: str | Path,
+    *,
+    env: Mapping[str, str] | None = None,
+    sandbox: SandboxConfig | None = None,
+    registry: ConstraintRegistry | None = None,
+    schema: Schema | None = None,
+) -> StdDocument:
+    """编译为 StdDocument（不经过降维）：root / templates / scope（纯数据，不携带诊断）。
+
+    沙盒/schema 违规时返回空文档；诊断见 :meth:`load` 结果（``CompilationResult.diagnostics``）。
+    """
+    result = load(path, env=env, sandbox=sandbox, registry=registry, schema=schema)
+    return result.document

infinity_data/sandbox/__init__.py

@@ -0,0 +1,32 @@
+"""M3 安全模型：沙盒配置、沙盒中介、顶层 Schema 约束与安全异常。
+
+子模块：
+- :mod:`config`：SandboxConfig（授权数据 + 工厂）
+- :mod:`mediator`：Sandbox（系统访问中介，File 的唯一产出者）
+- :mod:`errors`：SandboxError / SchemaError
+- :mod:`schema`：Schema（顶层模板约束）
+
+公共 API 从此包再导出，兼容 ``from infinity_data.sandbox import ...``。
+"""
+
+from infinity_data.sandbox.config import SandboxConfig
+from infinity_data.sandbox.errors import (
+    AccessDeniedError,
+    EnvNotAuthorizedError,
+    EnvNotSetError,
+    SandboxError,
+    SchemaError,
+)
+from infinity_data.sandbox.mediator import Sandbox
+from infinity_data.sandbox.schema import Schema
+
+__all__ = [
+    'Sandbox',
+    'SandboxConfig',
+    'SandboxError',
+    'EnvNotAuthorizedError',
+    'EnvNotSetError',
+    'AccessDeniedError',
+    'SchemaError',
+    'Schema',
+]

infinity_data/sandbox/config.py

@@ -0,0 +1,61 @@
+"""沙盒配置：授权数据（env / allow_env / allow_files / allow_templates / strict）
+与工厂方法。
+
+纯数据零行为：授权匹配与访问行为见 :mod:`infinity_data.sandbox.mediator`。
+自举场景可直接 ``SandboxConfig(**safe_load(...).value)`` 构造。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = ['SandboxConfig']
+
+
+@dataclass
+class SandboxConfig:
+    """控制 .infd 文件的导入权限。默认零信任。"""
+
+    # ── 环境变量注入：key → value。命中即返回，优先于 allow_env ──
+    env: dict[str, str] = field(default_factory=lambda: {})
+
+    # ── 环境变量读取白名单：授权从真实 OS 环境（os.environ）实时读取。
+    #    None = 全部允许；[] = 全部禁止（默认，零信任）──
+    allow_env: list[str] | None = field(default_factory=lambda: [])
+
+    # ── 文件导入白名单（glob 模式；None = 全部允许）──
+    allow_files: list[str] | None = field(default_factory=lambda: [])
+
+    # ── 模板导入白名单（glob 模式；None = 全部允许）──
+    allow_templates: list[str] | None = field(default_factory=lambda: [])
+
+    # ── 严格模式：True 白名单外导入抛 SandboxError；False 仅警告 ──
+    strict: bool = True
+
+    # ── 工厂方法 ──────────────────────────────────────
+
+    @staticmethod
+    def deny_all() -> SandboxConfig:
+        """零信任"""
+        return SandboxConfig()
+
+    @staticmethod
+    def full_access() -> SandboxConfig:
+        """全权限：全部环境变量实时读取 + 任意文件/模板。"""
+        return SandboxConfig(
+            allow_env=None,
+            allow_files=None,
+            allow_templates=None,
+        )
+
+    @staticmethod
+    def development() -> SandboxConfig:
+        """开发模式：当前目录全权限 + 全部环境变量实时读取。
+
+        ``**/*`` 匹配任意深度（``**`` 含零段，因此也能命中根级文件）。
+        """
+        return SandboxConfig(
+            allow_env=None,
+            allow_files=['**/*'],
+            allow_templates=['**/*'],
+        )

infinity_data/sandbox/errors.py

@@ -0,0 +1,106 @@
+"""沙盒安全异常体系（自有，独立于统一诊断模型）。
+
+错误模型：
+- 词法/语法/语义错误统一为 :class:`Diagnostic`（纯数据，从不抛异常）
+- 沙盒错误必须**中止编译**（控制流），故保留异常；携带 ``code/params/source``，
+  由编译核心（``infinity_data.pipeline``）捕获并转换为 ERROR 诊断，返回空文档
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from infinity_data.infra.diagnostics import diagnostic_define, register_diagnostic_define, render_message
+from infinity_data.infra.location import SourceRange, format_location
+
+__all__ = [
+    'SandboxError',
+    'EnvNotAuthorizedError',
+    'EnvNotSetError',
+    'AccessDeniedError',
+    'SchemaError',
+]
+
+register_diagnostic_define(
+    diagnostic_define(
+        'sandbox.env_unauthorized',
+        '[{location}] 环境变量 {name!r} 未在沙盒授权（!env import）',
+        en='[{location}] environment variable {name!r} is not authorized (!env import)',
+    ),
+    diagnostic_define(
+        'sandbox.env_not_set',
+        '[{location}] 环境变量 {name!r} 已授权但当前进程未设置',
+        en='[{location}] environment variable {name!r} is authorized but not set in this process',
+    ),
+    diagnostic_define(
+        'sandbox.access_denied',
+        '[{location}] {label}超出沙盒授权: {path_src}',
+        en='[{location}] {label} denied by sandbox: {path_src}',
+    ),
+    diagnostic_define(
+        'schema.undefined_template', '未定义的 schema 模板 {template!r}', en='undefined schema template {template!r}'
+    ),
+    diagnostic_define(
+        'schema.failed', '顶层 schema 校验失败: {detail}', en='top-level schema validation failed: {detail}'
+    ),
+    diagnostic_define(
+        'schema.extra_fields',
+        '顶层 schema 不允许额外字段: {fields}',
+        en='top-level schema does not allow extra fields: {fields}',
+    ),
+    diagnostic_define('schema.extra_fields_lenient', '顶层 schema 存在额外字段（已保留）: {fields}'),
+    diagnostic_define('schema.missing_required', '{path_prefix}顶层 schema 缺少必填字段 {field!r}（模板 {template}）'),
+)
+
+
+class SandboxError(Exception):
+    """沙盒安全异常基类（自有体系）。"""
+
+    def __init__(
+        self,
+        code: str,
+        params: dict[str, Any] | None = None,
+        source: SourceRange | None = None,
+    ) -> None:
+        super().__init__(code)
+        self.code: str = code
+        self.params: dict[str, Any] = params or {}
+        self.source: SourceRange | None = source
+
+    @property
+    def location(self) -> str:
+        return format_location(self.source)
+
+    @property
+    def message(self) -> str:
+        return render_message(self.code, self.params, location=self.location)
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class EnvNotAuthorizedError(SandboxError):
+    """``!env`` 引用的变量未在沙盒授权。"""
+
+    def __init__(self, name: str, source: SourceRange | None = None) -> None:
+        super().__init__('sandbox.env_unauthorized', {'name': name}, source)
+
+
+class EnvNotSetError(SandboxError):
+    """变量已授权但当前进程未设置。"""
+
+    def __init__(self, name: str, source: SourceRange | None = None) -> None:
+        super().__init__('sandbox.env_not_set', {'name': name}, source)
+
+
+class AccessDeniedError(SandboxError):
+    """文件/模板导入超出 glob 白名单。"""
+
+    def __init__(self, label: str, path: str, source: SourceRange | None = None) -> None:
+        super().__init__('sandbox.access_denied', {'label': label, 'path_src': path}, source)
+
+
+class SchemaError(SandboxError):
+    """顶层 schema 校验失败（中止编译）；以 ``code`` 区分具体原因。"""
+
+    pass