chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/configuration/file_tools.py

@@ -0,0 +1,140 @@
+"""当前配置的格式转换和新文件发布；不推断业务参数，不执行分析。"""
+from io import StringIO
+import json
+import math
+from pathlib import Path
+
+from . import load_configuration, parse_configuration
+from .diagnostics import locate_error
+
+
+def configuration_type(data):
+    """识别三个独立当前入口。参数: 原生配置。返回: analysis/batch/mapping。异常: ValueError。
+
+    版本不能猜测或迁移；旧INI由独立legacy import入口处理。
+    """
+    from ..planning.checks import PlanValidationError
+    versions={'config_version':('analysis',3),'batch_version':('batch',1),'mapping_version':('mapping',1)}
+    present=[key for key in versions if type(data) is dict and key in data]
+    if len(present)!=1:raise PlanValidationError('$','需要且只能有一种配置版本字段','invalid_version')
+    key=present[0];name,version=versions[key]
+    if type(data[key]) is not int or data[key]!=version:
+        raise PlanValidationError('$.'+key,'仅接受当前版本'+str(version)+'，不转换旧结构','invalid_version')
+    return name
+
+
+def validate_document(document, base, *, return_plan=False):
+    """调用现有模型；return_plan=True时同时返回计划，避免配置工具重复加载DBC。
+
+    批量不加载子任务，映射只核映射与其分析部分；INI模式与段名需在实际导入时核对。
+    """
+    from ..planning import AnalysisPlan
+    from ..planning.checks import PlanValidationError
+    from .imports import expand_document_imports
+    try:
+        document=expand_document_imports(document)
+        name=configuration_type(document.data)
+        if name=='analysis':plan=AnalysisPlan.from_dict(document.data,base_dir=base)
+        elif name=='batch':
+            from ..batch.models import BatchPlan
+            plan=BatchPlan.from_dict(document.data,base_dir=base)
+        else:
+            from ..migration.api import _prepare_mapping
+            from ..migration.ini import ImportProblem
+            try:_prepare_mapping(document.data,base)
+            except ImportProblem as error:
+                raise PlanValidationError(error.issue.path,error.issue.message,error.issue.code) from error
+            try:plan=AnalysisPlan.from_dict(document.data['analysis'],base_dir=base)
+            except PlanValidationError as error:
+                error.path='$.analysis'+error.path[1:];error.refresh_text();raise
+        return (name,plan) if return_plan else name
+    except PlanValidationError as error:raise locate_error(error,document)
+
+
+def path_fields(data, config_type):
+    """枚举声明的文件路径位置。参数: 已校验配置及类型。返回: (容器,键)迭代器。异常: 内部结构错误。
+
+    只认来源文件/DBC、批量子计划和公共定义；metadata与表达式中的path文字保持原样。
+    """
+    if config_type=='batch':
+        for job in data.get('jobs',[]):yield job,'plan'
+        if 'template' in data:
+            yield data,'template'
+            from ..planning.input_paths import source_path_fields
+            holder={'paths':data['inputs']}
+            for owner,key in source_path_fields(holder):
+                yield (data,'inputs') if owner is holder else (owner,key)
+        return
+    analysis=data['analysis'] if config_type=='mapping' else data
+    for source in analysis.get('sources',[]):
+        from ..planning.input_paths import source_path_fields
+        yield from source_path_fields(source)
+        for channel in source.get('dbc_by_channel',{}):yield source['dbc_by_channel'],channel
+    for index in range(len(analysis.get('imports',[]))):yield analysis['imports'],index
+
+
+def same_native_value(left,right):
+    """核类型/顺序/数值不漂移，包含负零和大整数。参数: 原生值。返回: bool。异常: 无。"""
+    if type(left) is not type(right):return False
+    if type(left) is dict:
+        return list(left)==list(right) and all(same_native_value(left[key],right[key]) for key in left)
+    if type(left) is list:
+        return len(left)==len(right) and all(same_native_value(a,b) for a,b in zip(left,right))
+    if type(left) is float and left==0:return left==right and math.copysign(1,left)==math.copysign(1,right)
+    return left==right
+
+
+def serialize_configuration(data, format):
+    """输出可被受限解析器再读取的文本。参数: 配置及json/yaml。返回: str。异常: ValueError。
+
+    输出后独立重解析并核类型和值，避免YAML隐式类型或浮点表示改写含义。注释不参与互转。
+    """
+    if format=='json':text=json.dumps(data,ensure_ascii=False,allow_nan=False,indent=2)+'\n'
+    elif format=='yaml':
+        from ruamel.yaml import YAML
+        yaml=YAML(typ='safe',pure=True);yaml.version=(1,2);yaml.default_flow_style=False
+        yaml.sort_base_mapping_type_on_output=False
+        yaml.representer.ignore_aliases=lambda value:True
+        stream=StringIO();yaml.dump(data,stream);text=stream.getvalue()
+    else:raise ValueError('输出格式仅支持json或yaml')
+    if not same_native_value(data,parse_configuration(text,format=format).data):
+        raise ValueError('格式转换不能保持原配置类型、顺序和值；未写文件')
+    return text
+
+
+def output_format(path):
+    """由扩展名选择格式。参数: Path。返回: json/yaml。异常: ValueError。"""
+    suffix=path.suffix.lower()
+    if suffix not in ('.json','.yaml','.yml'):raise ValueError('新文件需要.json、.yaml或.yml扩展名')
+    return 'json' if suffix=='.json' else 'yaml'
+
+
+def write_new_configuration(path, text):
+    """独占写新文件。参数: 路径及已校验文本。返回: Path。异常: IO/取消。
+
+    已存在文件、硬链接和符号链接都由独占打开拒绝；部分写失败仅清理本次创建的文件。
+    """
+    target=Path(path).absolute()
+    stream=target.open('x',encoding='utf-8',newline='\n')
+    try:
+        with stream:stream.write(text);stream.flush()
+    except BaseException as error:
+        try:stream.close()
+        except OSError as cleanup:error.add_note('未能关闭部分配置 '+str(target)+': '+str(cleanup))
+        try:target.unlink()
+        except OSError as cleanup:error.add_note('未能清理部分配置 '+str(target)+': '+str(cleanup))
+        raise
+    return target
+
+
+def convert_configuration(source, output):
+    """仅改变当前配置的JSON/YAML表示。参数: 输入、新文件。返回: 输出Path。异常: 配置/IO错误。
+
+    相对路径存在时只允许同目录输出；跨目录需使用resolve显式重定位，不静默修改原值。
+    """
+    source=Path(source).absolute();target=Path(output).absolute()
+    document=load_configuration(source);name=validate_document(document,source.parent)
+    if source.parent!=target.parent and any(not Path(owner[key]).is_absolute() for owner,key in path_fields(document.data,name)):
+        raise ValueError('配置含相对路径，convert只能写入同目录；跨目录请用config resolve --output重新定位')
+    text=serialize_configuration(document.data,output_format(target))
+    return write_new_configuration(target,text)

chronaxis/configuration/imports.py

@@ -0,0 +1,144 @@
+"""展开明确列出的一层本地公共定义，供分析文件和INI映射文件加载使用。
+
+主配置按imports顺序引入sources/signals/derived，最后追加本地声明；重复名称
+直接拒绝。导入文件不能再导入文件，也不能声明运行、规则或输出字段。
+仅打开配置文件，数据/DBC路径按各自声明文件转为词法绝对路径；不读取业务输入。
+位置随本次加载保留，成功计划不持有原文或第二份配置，不执行环境替换或模板。
+"""
+from copy import deepcopy
+from pathlib import Path
+from types import MappingProxyType
+
+from . import load_configuration
+from .diagnostics import locate_error
+from .models import ConfigurationDocument, ConfigurationOrigin, field_path_text
+
+SECTIONS=('sources','signals','derived')  # 唯一允许共享的定义，不包含执行节点。
+
+
+def _reject(document, path, message, code='invalid_import', hint=None):
+    """在实际声明处拒绝导入。参数: 文档、tuple路径、原因/代码/建议。返回: 不返回。异常: PlanValidationError。"""
+    from ..planning.checks import PlanValidationError
+    raise locate_error(PlanValidationError(field_path_text(path),message,code,hint=hint),document)
+
+
+def _source_paths(source, base, path, document):
+    """固定一项来源中的公开文件路径。参数: 来源副本、声明目录、字段路径、原文档。返回: None。异常: 字段错误。
+
+    只改本次副本，metadata内任意path不解释为文件；不调用stat或resolve。
+    """
+    from ..planning.checks import absolute_path, array_at, PlanValidationError
+    try:
+        # 路径文字、列表和带offset的文件对象共用路径定位，不展开输入目录。
+        from ..planning.input_paths import source_path_fields
+        for owner,key in source_path_fields(source,field_path_text(path)):
+            owner[key]=str(absolute_path(owner[key],base,field_path_text((*path,key))))
+        if 'dbc_by_channel' in source:
+            values=source['dbc_by_channel']
+            if type(values) is not dict:
+                _reject(document,(*path,'dbc_by_channel'),'DBC通道映射必须为对象')
+            source['dbc_by_channel']={key:str(absolute_path(value,base,field_path_text((*path,'dbc_by_channel',key))))
+                                      for key,value in values.items()}
+    except PlanValidationError as error:
+        raise locate_error(error,document)
+
+
+def _append_definitions(data, prefix, document, source_prefix, merged, locations, origins, names):
+    """追加一个文件的定义并迁移字段位置。参数: 原定义/目标前缀/原文档/原前缀及本次容器。返回: None。异常: 定义/重复错误。
+
+    names保存首个同名声明的位置；所有修改仅发生在本次展开容器，无全局状态。
+    """
+    for section in SECTIONS:
+        if section not in data:continue
+        values=data[section]
+        expected=dict if section=='derived' else list
+        if type(values) is not expected:
+            _reject(document,(*source_prefix,section),
+                    'derived必须为名称到表达式的对象' if section=='derived' else '来源/信号定义必须为数组')
+        offset=len(merged[section])
+        entries=values.items() if section=='derived' else enumerate(values)
+        for index,value in entries:
+            path=(*source_prefix,section,index)
+            if section!='derived' and type(value) is not dict:
+                _reject(document,path,'每项公共定义必须为对象')
+            if section=='signals' and 'signals' in value:
+                children=value['signals']
+                if type(children) is not list or any(type(child) is not dict for child in children):
+                    _reject(document,(*path,'signals'),'组内signals必须为信号对象数组')
+                declarations=[(child.get('name'),(*path,'signals',child_index,'name'))
+                              for child_index,child in enumerate(children)]
+            else:
+                name=index if section=='derived' else value.get('name')
+                declarations=[(name,path if section=='derived' else (*path,'name'))]
+            for name,name_path in declarations:
+                if type(name) is not str or not name:
+                    _reject(document,name_path,'每项公共定义必须明确填写非空名称')
+                # 集中声明和普通信号仍共用一个名字空间，组本身没有额外名称。
+                identity=('sources' if section=='sources' else 'signals/derived',name)
+                if identity in names:
+                    first_source,first_path=names[identity]
+                    _reject(document,name_path,'重复定义 '+name,'duplicate_definition',
+                            '删除或改名；首次声明在 '+first_source+' '+field_path_text(first_path))
+                names[identity]=(document.source,name_path)
+            copied=deepcopy(value)
+            if section=='sources':_source_paths(copied,Path(document.source).parent,path,document)
+            if section=='derived':merged[section][name]=copied
+            else:merged[section].append(copied)
+        # 整个数组只遍历一次位置表，主文件项追加后仍指向主文件原索引。
+        original_prefix=(*source_prefix,section)
+        for original,location in document.locations.items():
+            if original[:len(original_prefix)]!=original_prefix:continue
+            suffix=original[len(original_prefix):]
+            if not suffix:continue
+            target=(*prefix,section,suffix[0] if section=='derived' else offset+suffix[0],*suffix[1:])
+            locations[target]=location
+            origins[target]=ConfigurationOrigin(document.source,original,location)
+
+
+def expand_document_imports(document):
+    """展开分析配置或映射中analysis的公共定义。参数: 已解析文档。返回: 可直接静态检查的文档。异常: 配置/读取错误。
+
+    未声明imports时原样返回，不增加复制或文件读取。批量文件通过每个子计划
+    自行使用imports；纯字典API不调用此函数。版本错误由原入口拒绝，不读其导入。
+    """
+    data=document.data
+    if type(data) is not dict:return document
+    prefix=('analysis',) if 'mapping_version' in data else ()
+    analysis=data.get('analysis') if prefix else data
+    if type(analysis) is not dict or 'imports' not in analysis:return document
+    if type(analysis.get('config_version')) is not int or analysis['config_version']!=3:return document
+    entries=analysis['imports']
+    if type(entries) is not list:
+        _reject(document,(*prefix,'imports'),'imports必须为本地配置路径数组')
+    # 定义数组重新构造；先清除被移动数组的旧位置，避免缺失字段误用旧索引行列。
+    raw=deepcopy(data)
+    target=raw['analysis'] if prefix else raw
+    merged={'sources':[],'signals':[],'derived':{}}
+    locations={path:location for path,location in document.locations.items()
+               if not (path[:len(prefix)]==prefix and len(path)>len(prefix)+1
+                       and path[len(prefix)] in SECTIONS)}
+    origins={path:ConfigurationOrigin(document.source,path,location) for path,location in locations.items()}
+    names={}
+    for index,entry in enumerate(entries):
+        path=(*prefix,'imports',index)
+        if type(entry) is not str or not entry.strip() or '://' in entry or any(char in entry for char in '*?[]'):
+            _reject(document,path,'导入路径必须为明确的本地JSON/YAML文件，不支持URL、通配符或空值')
+        imported=load_configuration(Path(document.source).parent/entry)
+        fragment=imported.data
+        if type(fragment) is not dict or not fragment:
+            _reject(imported,(),'公共定义文件必须是非空对象，只能包含sources、signals、derived')
+        unknown=set(fragment)-set(SECTIONS)
+        if unknown:
+            key=next(key for key in fragment if key in unknown)
+            _reject(imported,(key,),'公共定义只允许sources、signals、derived；不支持嵌套imports或版本包装')
+        _append_definitions(fragment,prefix,imported,(),merged,locations,origins,names)
+    _append_definitions(analysis,prefix,document,prefix,merged,locations,origins,names)
+    # 展开后不保留imports，执行计划只见一份普通配置；来源位置只在加载期使用。
+    target.pop('imports')
+    for section in SECTIONS:
+        if section!='derived' or merged[section] or section in target:
+            target[section]=merged[section]
+    from .overrides import apply_overrides
+    apply_overrides(target,document,prefix,locations,origins)
+    return ConfigurationDocument(raw,document.source,document.format,
+                                 MappingProxyType(locations),MappingProxyType(origins))

chronaxis/configuration/initialization.py

@@ -0,0 +1,36 @@
+"""把已校验的随包合成场景写入新目录，不改写已有文件。"""
+from pathlib import Path
+
+from .template_catalog import available_templates, template_files
+
+
+def initialize_configuration(scene, output, *, style='annotated'):
+    """生成独立场景。参数: 场景名、新目录及风格。返回: 入口绝对路径。异常: ValueError/IO/取消。
+
+    先读取全部包资源再独占创建目录，入口最后写出。写入失败仅删除本次创建的文件和目录；
+    清理失败附注原错误并保留残余，不删除其他进程写入的文件，不以成功掩盖部分写入。
+    """
+    contents=template_files(scene,style=style)
+    template=next(t for t in available_templates() if t.name==scene)
+    target=Path(output).absolute()
+    # mkdir的独占失败发生在清理区之前，已有目录（包括空目录、链接）不属于本次操作。
+    target.mkdir()
+    created_files=[];created_directories=[target]
+    try:
+        # 将主入口放在最后，使中途产物不能被误认为完整场景。
+        for relative,content in sorted(contents,key=lambda item:item[0]==template.entrypoint):
+            path=target/relative
+            missing=[];parent=path.parent
+            while parent!=target and not parent.exists():missing.append(parent);parent=parent.parent
+            for directory in reversed(missing):directory.mkdir();created_directories.append(directory)
+            with path.open('xb') as stream:
+                created_files.append(path);stream.write(content)
+        return target/template.entrypoint
+    except BaseException as error:
+        for path in reversed(created_files):
+            try:path.unlink()
+            except OSError as cleanup:error.add_note('未能清理本次文件 '+str(path)+': '+str(cleanup))
+        for directory in reversed(created_directories):
+            try:directory.rmdir()
+            except OSError as cleanup:error.add_note('未能清理本次空目录 '+str(directory)+': '+str(cleanup))
+        raise

chronaxis/configuration/json_parser.py

@@ -0,0 +1,114 @@
+"""标准库负责JSON语法和数值；轻量第二遍只定位字段，不再构造第二份配置树。"""
+from bisect import bisect_right
+import json
+from math import isfinite
+import re
+
+from .models import ConfigurationError, ConfigurationLocation
+
+MAX_DEPTH=64
+_SPACE=re.compile(r'[ \t\r\n]*')
+
+
+class _DuplicateKey(ValueError):
+    """只用于让标准库停止覆盖重复键；随后位置扫描给出具体字段。"""
+
+
+def _unique_pairs(pairs):
+    """建立唯一键对象。参数: 标准库键值对。返回: dict。异常: 重复键。"""
+    result={}
+    for key,value in pairs:
+        if key in result:
+            raise _DuplicateKey(key)
+        result[key]=value
+    return result
+
+
+class _Locations:
+    """只记录JSON路径和偏移，不保留第二份值树；语法真值仍由json.loads决定。"""
+
+    def __init__(self, text, source):
+        """建立本次扫描状态。参数: 文本/显示来源。返回: owner。异常: 分配失败。"""
+        self.text,self.source=text,source
+        self.positions={}
+        self.lines=[match.start() for match in re.finditer('\n',text)]
+        self.decoder=json.JSONDecoder()
+
+    def location(self, offset):
+        """把字符偏移转换为1基行列。参数: 偏移。返回: 位置。异常: 无。"""
+        line=bisect_right(self.lines,offset-1)
+        previous=self.lines[line-1] if line else -1
+        return ConfigurationLocation(line+1,offset-previous)
+
+    def scan(self, offset=0, path=(), depth=0):
+        """遍历合法JSON或已知含重复键的JSON。返回: 结束偏移。异常: 重复键/过深/语法错误。"""
+        offset=_SPACE.match(self.text,offset).end()
+        location=self.location(offset)
+        if depth>MAX_DEPTH:
+            raise ConfigurationError(self.source,path,location,'nesting_limit','配置嵌套不能超过64层')
+        self.positions[path]=location
+        first=self.text[offset]
+        if first=='{':
+            offset=_SPACE.match(self.text,offset+1).end()
+            if self.text[offset]=='}':return offset+1
+            seen=set()
+            while True:
+                key_at=offset
+                key,offset=json.decoder.scanstring(self.text,offset+1,True)
+                if key in seen:
+                    raise ConfigurationError(self.source,(*path,key),self.location(key_at),
+                        'duplicate_key',f'重复键：{key}')
+                seen.add(key)
+                offset=_SPACE.match(self.text,offset).end()+1  # 已通过JSON语法检查的冒号。
+                offset=self.scan(offset,(*path,key),depth+1)
+                offset=_SPACE.match(self.text,offset).end()
+                if self.text[offset]=='}':return offset+1
+                offset=_SPACE.match(self.text,offset+1).end()
+        if first=='[':
+            offset=_SPACE.match(self.text,offset+1).end()
+            if self.text[offset]==']':return offset+1
+            index=0
+            while True:
+                offset=self.scan(offset,(*path,index),depth+1)
+                offset=_SPACE.match(self.text,offset).end()
+                if self.text[offset]==']':return offset+1
+                offset=_SPACE.match(self.text,offset+1).end()
+                index+=1
+        # raw_decode这里只接原子值，绝不重新解码整个容器。
+        _,end=self.decoder.raw_decode(self.text,offset)
+        return end
+
+
+def _finite_values(value, source, locations, path=()):
+    """拒绝JSON宽松接受的NaN/Infinity及指数溢出。返回: None。异常: 定位到实际值。"""
+    if type(value) is float and not isfinite(value):
+        raise ConfigurationError(source,path,locations[path],'nonfinite_number','数值必须有限，不能使用NaN或Infinity')
+    if type(value) is dict:
+        for key,item in value.items():_finite_values(item,source,locations,(*path,key))
+    elif type(value) is list:
+        for index,item in enumerate(value):_finite_values(item,source,locations,(*path,index))
+
+
+def parse_json(text, source):
+    """按标准JSON加载并附准确位置。参数: 文本/来源。返回: 数据和位置表。异常: ConfigurationError。"""
+    try:
+        try:
+            data=json.loads(text,object_pairs_hook=_unique_pairs)
+        except _DuplicateKey:
+            # 标准库已找到实际重复；不从字符串搜索猜测它属于哪个嵌套对象。
+            _Locations(text,source).scan()
+            raise AssertionError('JSON重复键位置扫描没有发现重复')
+        except json.JSONDecodeError:
+            raise
+        except (ValueError,OverflowError) as error:
+            # Python的十进制整数安全长度限制等数值错误不能泄露为无文件定位的底层异常。
+            raise ConfigurationError(source,(),None,'invalid_number','数字超出当前Python可解析的范围') from error
+        scanner=_Locations(text,source)
+        scanner.scan()
+        _finite_values(data,source,scanner.positions)
+        return data,scanner.positions
+    except json.JSONDecodeError as error:
+        raise ConfigurationError(source,(),ConfigurationLocation(error.lineno,error.colno),
+            'invalid_json',error.msg) from error
+    except RecursionError as error:
+        raise ConfigurationError(source,(),None,'nesting_limit','配置嵌套不能超过64层') from error

chronaxis/configuration/models.py

@@ -0,0 +1,74 @@
+"""配置加载期的原生数据、字段位置和语法错误，不参与分析执行或来源读取。"""
+from dataclasses import dataclass, field
+from collections.abc import Mapping
+import json
+
+
+def field_path_text(path):
+    """把键/数组下标路径变成无歧义文本。参数: tuple。返回: JSON路径。异常: 非内部路径。"""
+    result='$'
+    for part in path:
+        if type(part) is int:
+            result+=f'[{part}]'
+        elif type(part) is str:
+            result+=('.'+part if part.isidentifier() else '['+json.dumps(part,ensure_ascii=False)+']')
+        else:
+            raise TypeError('配置字段路径只接受文本键或整数下标')
+    return result
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationLocation:
+    """一处源码位置；行列从1开始，列按Unicode字符计，不按UTF-8字节计。"""
+    line: int
+    column: int
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationOrigin:
+    """展开字段的声明位置；只保存文件名、字段路径及行列，不保存第二份配置。"""
+    source: str  # 实际声明文件的词法绝对路径。
+    field_path: tuple  # 声明文件内部路径，索引尚未被合并重排。
+    location: ConfigurationLocation | None  # 原文一基行列；无法取得时为None。
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationDocument:
+    """只在加载期间持有原生值和必要位置；调用者构造计划后释放本对象。"""
+    data: object
+    source: str
+    format: str
+    locations: Mapping
+    origins: Mapping = field(default_factory=dict)  # 仅文件导入展开时填充，计划构造后释放。
+
+    def origin_for(self, field_path):
+        """查最近声明来源并保留缺失字段后缀。参数: tuple路径。返回: 来源或None。异常: 无。"""
+        original=tuple(field_path)
+        path=original
+        # 缺少字段只能沿所属对象定位，不能捏造它在原文件中的行列。
+        while path not in self.origins and path:
+            path=path[:-1]
+        origin=self.origins.get(path)
+        if origin is None:return None
+        return ConfigurationOrigin(origin.source,origin.field_path+original[len(path):],origin.location)
+
+    def location_for(self, field_path):
+        """取具体值位置，缺少字段时回溯最近父对象。参数: tuple路径。返回: 位置或None。异常: 无。"""
+        path=tuple(field_path)
+        while path not in self.locations and path:
+            path=path[:-1]
+        return self.locations.get(path)
+
+
+class ConfigurationError(ValueError):
+    """保存语法错误码、文件和字段位置；消息不打印整份配置或执行任意内容。"""
+
+    def __init__(self, source, field_path, location, code, message):
+        """建立错误事实。参数: 来源/tuple路径/位置/代码/原因。返回: None。异常: 无。"""
+        self.source=source
+        self.field_path=tuple(field_path)
+        self.location=location
+        self.code=code
+        self.message=message
+        place=source if location is None else f'{source}:{location.line}:{location.column}'
+        super().__init__(f'{place} {field_path_text(self.field_path)}: {message}')

chronaxis/configuration/origins.py

@@ -0,0 +1,90 @@
+"""按请求说明定义或叶字段来自哪个配置文件；不作为执行计划的持久状态。
+
+只读主配置与明确的一层公共定义，先复用静态校验再生成小型来源记录。
+默认报告定义位置及来源文件路径；fields模式列全部显式叶字段，不虚构默认值来源。
+既不读取CSV/DBC等业务输入，也不写报告文件；调用者决定显示或重定向。
+"""
+from pathlib import Path
+
+from . import load_configuration
+from .imports import expand_document_imports
+from .file_tools import validate_document
+from .models import field_path_text
+
+
+def _at(data, path):
+    """读取存在的字段，跳过展开后已删除的imports位置。参数: 原生树/tuple路径。返回: (存在,值)。异常: 无。"""
+    current=data
+    for key in path:
+        if type(current) is dict and key in current:current=current[key]
+        elif type(current) is list and type(key) is int and 0<=key<len(current):current=current[key]
+        else:return False,None
+    return True,current
+
+
+def _record(document, path, name=None):
+    """复制一项有限来源事实。参数: 文档、路径、可选定义名。返回: dict。异常: 无。"""
+    origin=document.origin_for(path)
+    location=origin.location if origin else document.location_for(path)
+    return dict(name=name,effective_path=field_path_text(path),
+                declared_path=field_path_text(origin.field_path if origin else path),
+                file=origin.source if origin else document.source,
+                line=None if location is None else location.line,
+                column=None if location is None else location.column)
+
+
+def configuration_origins(source, *, fields=False):
+    """读取实际定义或叶字段的声明位置。参数: 配置路径、是否逐字段。返回: 来源报告dict。异常: 配置/读取错误。
+
+    分析和映射都列其定义；批量只列本文件的任务，不读取子计划。省略的默认字段
+    不在报告内。fields只保位置而不复制值；路径声明单独说明最终指向。
+    """
+    path=Path(source).absolute()
+    document=expand_document_imports(load_configuration(path))
+    kind=validate_document(document,path.parent)
+    items=[]
+    if fields:
+        for parts in document.locations:
+            exists,value=_at(document.data,parts)
+            if exists and type(value) not in (dict,list):items.append(_record(document,parts))
+    else:
+        prefix=('analysis',) if kind=='mapping' else ()
+        analysis=document.data['analysis'] if prefix else document.data
+        if kind=='batch' and 'template' in analysis:
+            item=_record(document,('template',),'template')
+            item['resolved_paths']=[str((path.parent/analysis['template']).absolute())]
+            items.append(item)
+            items.append(_record(document,('inputs',),'inputs'))
+        sections=('jobs',) if kind=='batch' else ('sources','signals','derived')
+        for section in sections:
+            values=analysis.get(section,{} if section=='derived' else [])
+            entries=values.items() if section=='derived' else enumerate(values)
+            for key,value in entries:
+                if section=='signals' and 'signals' in value:
+                    for child_index,child in enumerate(value['signals']):
+                        items.append(_record(document,(*prefix,section,key,'signals',child_index),child['name']))
+                    continue
+                name=key if section=='derived' else value.get('name')
+                item=_record(document,(*prefix,section,key),name)
+                # 文件位置只按已知路径字段说明；metadata内路径文字不解释。
+                if section=='sources':
+                    from ..planning.input_paths import source_path_fields
+                    declared=[owner[key] for owner,key in source_path_fields(value)]
+                    declared.extend(value.get('dbc_by_channel',{}).values())
+                    item['resolved_paths']=[str((path.parent/entry).absolute()) for entry in declared]
+                elif section=='jobs':item['resolved_paths']=[str((path.parent/value['plan']).absolute())]
+                items.append(item)
+    return dict(configuration=str(path),configuration_type=kind,
+                scope='fields' if fields else 'definitions',items=items)
+
+
+def render_origins(report):
+    """将有限来源记录显示为中文文本。参数: configuration_origins报告。返回: str。异常: 内部报告结构错误。"""
+    lines=['配置来源：'+report['configuration'],
+           '只列显式声明；未读取业务输入。批量任务的子配置需单独查看。']
+    for item in report['items']:
+        place=item['file']
+        if item['line'] is not None:place+=f":{item['line']}:{item['column']}"
+        lines.append(item['effective_path']+' ← '+place+' '+item['declared_path'])
+        for path in item.get('resolved_paths',[]):lines.append('  文件路径：'+path)
+    return '\n'.join(lines)+'\n'

chronaxis/configuration/overrides.py

@@ -0,0 +1,55 @@
+"""只覆盖公共定义中的明确配置项，不允许隐藏改名、添加对象或递归合并自由数据。
+
+覆盖值按主文件定位，随后仍由普通计划校验器检查；来源表同时指回真正的覆盖位置。
+"""
+from copy import deepcopy
+from .models import ConfigurationOrigin
+
+ALLOWED={
+    'sources':{'path','paths','dbc_by_channel','time','reader'},
+    'signals':{'dtype','unit','valid_for','period','conversion','choices','valid_range','invalid_values','sample_policy','same_time_policy'},
+    'derived':{'expr','unit'},
+}
+
+
+def apply_overrides(target, document, prefix, locations, origins):
+    """修改本次独立副本；参数含原文位置。返回None；非法对象/字段经_imports._reject定位。"""
+    from .imports import _reject, _source_paths
+    from pathlib import Path
+    raw=target.pop('overrides',{})
+    if type(raw) is not dict or set(raw)-set(ALLOWED):
+        _reject(document,(*prefix,'overrides'),'overrides仅允许sources/signals/derived对象')
+    for section,items in raw.items():
+        where=(*prefix,'overrides',section)
+        if type(items) is not dict:_reject(document,where,'覆盖项须按已有名称索引')
+        catalog={}
+        if section=='derived':
+            catalog={name:(value,(*prefix,section,name)) for name,value in target.get(section,{}).items()}
+        else:
+            for index,value in enumerate(target.get(section,[])):
+                if section=='signals' and 'signals' in value:
+                    for ci,child in enumerate(value['signals']):catalog[child['name']]=(child,(*prefix,section,index,'signals',ci))
+                else:catalog[value['name']]=(value,(*prefix,section,index))
+        for name,changes in items.items():
+            path=(*where,name)
+            if name not in catalog:_reject(document,path,'覆盖目标不存在，不允许新增定义')
+            if type(changes) is not dict or not changes or set(changes)-ALLOWED[section]:
+                _reject(document,path,'覆盖字段不在允许列表；不能改名、改绑定或修改自由metadata')
+            value,target_path=catalog[name]
+            # path/paths是同一输入声明的两种形状，只保留用户本次选定的一种。
+            if section=='sources':
+                if 'path' in changes and 'paths' not in changes:value.pop('paths',None)
+                if 'paths' in changes and 'path' not in changes:value.pop('path',None)
+            # 被整体替换的字段不再保留旧叶子来源，例如旧time.clock已被省略。
+            replaced=set(changes)
+            if section=='sources' and replaced & {'path','paths'}:replaced.update(('path','paths'))
+            for effective in tuple(origins):
+                if effective[:len(target_path)]==target_path and len(effective)>len(target_path) and effective[len(target_path)] in replaced:
+                    origins.pop(effective,None);locations.pop(effective,None)
+            value.update(deepcopy(changes))
+            if section=='sources':_source_paths(value,Path(document.source).parent,path,document)
+            for original,location in document.locations.items():
+                if original[:len(path)]==path and len(original)>len(path):
+                    effective=(*target_path,*original[len(path):])
+                    locations[effective]=location
+                    origins[effective]=ConfigurationOrigin(document.source,original,location)