mopr 0.0.57.dev1__tar.gz → 0.0.69__tar.gz

{mopr-0.0.57.dev1 → mopr-0.0.69}/.gitignore

@@ -34,6 +34,19 @@
 # Test data
 data/
 
+# 例外: 随包分发的数据资产(不是测试数据) —— finance/forex/data/ 下的 cfets 头部归档
+# (1994-2005, 官网区间接口取不到的那一段), 必须入库并随 mopr.finance.forex 分发;
+# 需先解除目录级忽略, 再放行其中的 CSV(pyproject 的 package-data 与 MANIFEST.in 同步收录)。
+!finance/forex/data/
+!finance/forex/data/*.csv
+
+# 例外: 同上的第二处 —— finance/exchange/data/ 下的 ISO 10383 MIC 官方全量清单原文(CSV)
+# 与由其提取的四字码表(TXT), 必须入库并随 mopr.finance.exchange 分发;
+# 同样先解除目录级忽略, 再放行其中的 CSV / TXT(package-data 与 MANIFEST.in 同步收录)。
+!finance/exchange/data/
+!finance/exchange/data/*.csv
+!finance/exchange/data/*.txt
+
 # Python
 
 # Byte-compiled / optimized / DLL files
@@ -199,3 +212,10 @@ THIRD_PARTY_TODO.md
 
 # 仓库根的 compile_commands.json 软链（指向 build/Release 下由 CMake 导出的产物）
 compile_commands.json
+
+# --- 编辑器/IDE 本地配置 ---
+
+# VS Code 工作区配置由 scripts/vscode_sync.py 按操作系统分层生成：
+# 入库的是 .vscode-default/（共享层）与 .vscode-<platform>/（平台覆盖层），
+# 产物 .vscode/ 含与本机/平台相关的取值，不入库（本地文件保留）。
+.vscode/

{mopr-0.0.57.dev1/.vscode → mopr-0.0.69/.vscode-default}/settings.json

@@ -1,12 +1,4 @@
 {
-    "terminal.integrated.profiles.windows": {
-        "PowerShell": {
-            "source": "PowerShell",
-            "icon": "terminal-powershell",
-            "args": ["-NoExit", "-Command", "chcp 65001 > $null"]
-        }
-    },
-    "terminal.integrated.defaultProfile.windows": "PowerShell",
     "C_Cpp.intelliSenseEngine": "disabled",
     "cmake.configureOnOpen": false,
     "cmake.useCMakePresets": "never",
@@ -23,6 +15,6 @@
     "code-runner.runInTerminal": true,
     "java.diagnostic.filter": [
         "**/base/*.java",
-        "**/distributed/id/*.java",
+        "**/distributed/id/*.java"
     ]
 }

{mopr-0.0.57.dev1/.vscode → mopr-0.0.69/.vscode-default}/tasks.json

@@ -41,15 +41,6 @@
             "problemMatcher": [
                 "$msCompile"
             ]
-        },
-        {
-            "label": "refresh clangd db (ninja-debug)",
-            "type": "shell",
-            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File refresh-clangd.ps1",
-            "options": {
-                "cwd": "${workspaceFolder}"
-            },
-            "problemMatcher": []
         }
     ]
 }

mopr-0.0.69/.vscode-macos/settings.json

@@ -0,0 +1,5 @@
+{
+    "code-runner.executorMap": {
+        "python": "python3 tools/run_module.py $fullFileName"
+    }
+}

mopr-0.0.69/.vscode-macos/tasks.json

@@ -0,0 +1,14 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "refresh clangd db (ninja-debug)",
+            "type": "shell",
+            "command": "bash refresh-clangd.sh",
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": []
+        }
+    ]
+}

{mopr-0.0.57.dev1/.vscode → mopr-0.0.69/.vscode-windows}/launch.json

@@ -14,6 +14,14 @@
             "preLaunchTask": "mopr: build (debug-dynamic)",
             "stopAtEntry": false,
             "environment": []
+        },
+        {
+            "type": "cmake",
+            "request": "launch",
+            "name": "Debug portfile(s)",
+            "cmakeDebugType": "external",
+            "pipeName": "\\\\.\\pipe\\vcpkg_ext_portfile_dbg",
+            "preLaunchTask": "Debug vcpkg commands"
         }
     ]
 }

mopr-0.0.69/.vscode-windows/settings.json

@@ -0,0 +1,10 @@
+{
+    "terminal.integrated.profiles.windows": {
+        "PowerShell": {
+            "source": "PowerShell",
+            "icon": "terminal-powershell",
+            "args": ["-NoExit", "-Command", "chcp 65001 > $null"]
+        }
+    },
+    "terminal.integrated.defaultProfile.windows": "PowerShell"
+}

mopr-0.0.69/.vscode-windows/tasks.json

@@ -0,0 +1,14 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "refresh clangd db (ninja-debug)",
+            "type": "shell",
+            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File refresh-clangd.ps1",
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": []
+        }
+    ]
+}

mopr-0.0.69/AGENTS.md

@@ -0,0 +1,165 @@
+# AGENTS.md — 仓库协作规范
+
+本文件面向在本仓库工作的自动化 Agent 与协作者，列出必须遵守的约定。遇到与本文件冲突的做法时，以本文件为准。
+
+## 语言与版本要求
+
+mopr 是单仓多语言库（monolibrary），同一语义将来可能有多种语言实现。各语言最低版本由本项目独立维护，不要求与同系列 `quant1x` 仓库同步：
+
+| 语言 | 最低版本 | 说明 |
+| --- | --- | --- |
+| Python | 3.12+ | 3.12.x |
+| C++ | C++20 | GCC 13+ / Clang 17+ / MSVC 14.3+ |
+| Rust | 1.98.0+ | 2024 edition |
+| Go | 1.27+ | 1.27.x |
+| Java | 8+ | `pom.xml` 的 `java.version`（JDK 8 及以上） |
+
+- 编写各语言实现时，不得使用低于上表基线的语言特性与 API（含第三方依赖的最低版本要求）。
+- 版本基线变更由本项目独立评估；README.md「语言与版本要求」为对外文档，两者保持一致。
+- 当前仓库以 C++20 + MSVC v143 + CMake/Conan 2 为主验证。
+
+### 语言角色与演进顺序
+
+mopr 同一语义的多语言实现遵循固定的**角色与演进顺序**，与"主验证语言"无关：
+
+1. **Python 为 spec**：先行实现，确定语义、API 与默认行为（含解析/输出格式面），是其余语言的语义参照；
+2. **C++ 为生产实现**：Python spec 确定后落地，同时是仓库主验证语言（C++20 + MSVC v143 + CMake/Conan 2）；
+3. **Rust / Go 为扩展**：随后跟进，与 Python spec 保持 API/语义对齐。
+
+配套约定：
+
+- 文档、注释与 API 对照表描述语言时，遵循 `python → c++ → rust → go` 的演进顺序；**不得先入为主地以 C++ 为全部语言的语义源头**（反例：文档开头写"以 C++ 为基准 / 参考实现"）。语义判断以 Python（spec）为准绳。
+- 跨语言差异处理先从 Python（spec）侧定案，再推广至 C++（生产）与 Rust/Go（扩展）；若 Python 缺少某能力而其他语言已有，应先补 Python spec。
+- 语言最低版本表（上文）与 README.md「语言与版本要求」不因角色调整而改变。
+
+## 文件命名与物理命名空间约定
+
+同一功能拆分为多个源文件时，文件名统一采用「**功能名前缀 + 下划线 + 角色/平台名**」，用前缀在目录内构成**物理层面的命名空间**：
+
+- **前缀即命名空间**：同族文件按前缀自然聚拢，按前缀即可检索到该功能的全部实现：
+  - `base/strings_camel.go` / `strings_snake.go` / `strings_kebab.go` / `strings_helper.go`；
+  - `distributed/id/state_lock_unix.go` / `state_lock_windows.go` / `state_lock_shared.go` / `state_lock_other.go`；
+  - `base/mmap/mmap_posix.go` / `mmap_windows.go` / `mmap_unsupported.go`；
+  - `benchmark/micro/ringbuffer_mpmc_probe.cpp` / `ringbuffer_sched_cost_probe.cpp` / `ringbuffer_single_thread_ablation.cpp`。
+- **两级正交**：前缀承载功能维度，后缀承载语言与角色维度——语言后缀沿用各语言惯例（`.py` / `.h` / `.cpp` / `.rs` / `.go` / `.md`），角色后缀用于平台分支（`_posix` / `_windows` / `_unsupported`）与测试（`_test`）；同一功能的跨语言实现因此同名不同后缀、同处一目录。
+- **适用边界**：前缀只用于同一功能的文件分组，不为无关文件强加公共前缀；功能名已唯一的文件直接以功能名命名（`region.go` / `cron.rs` / `crc32.h`），不画蛇添足。
+- **同目录优先，不按语言分目录**：语言工具链要求「目录即成包」时（Go 的 `package`、Java 的包路径），在**该功能目录内**加同名二级目录与其它语言对齐（`base/mmap/mmap.go` ↔ `base/mmap.py`）；**不得**在仓库根按语言拆分语言级目录，把同一功能的各语言实现物理隔离——同目录并列才能形成「看到 `mmap.py` 顺手去看 `mmap.h` / `mmap.rs` / `mmap/mmap.go`」的对照与主动学习。
+- 与「仓库根即实现根」配合：目录承载模块级命名空间，文件名前缀承载模块内的功能级命名空间，二者共同决定 C++ 命名空间与各语言模块路径（见下文与 [CONTRIBUTING.md](CONTRIBUTING.md)「目录与多语言布局约定」）。
+- 设计意图（同目录对照的收益、按语言分目录为何是反例、对 AI 的友好之处）见 [docs/directory-layout-rationale.md](docs/directory-layout-rationale.md)。
+
+## Python 包形态与导入约定
+
+- mopr 的 Python 代码经 `pyproject.toml` package-dir 注册为 `mopr.*` 子包：`python/` → `mopr`（包入口，导出 `__version__`），`base/` → `mopr.base`，`log/` → `mopr.log`，`machine/` → `mopr.machine`，`runtime/` → `mopr.runtime`，`distributed/` → `mopr.distributed`，`tools/` → `mopr.tools`。仓库根目录无 `__init__.py`，源码形态下 `mopr` 是 PEP 420 隐式命名空间包。
+- 库模块以 `mopr.<子包>.<模块>` 导入；子包间存在跨子包相对导入（如 `log/core.py` 的 `from ..base import ...`），要求按包化名称导入——**禁止**在仓库根以顶层形态验证库模块（`from log.core import logger`、`python -m log.core` 会因相对导入越界报 `attempted relative import beyond top-level package`）。源码形态需在仓库根的父目录运行（或把仓库根加入 `PYTHONPATH`）；冒烟写法示例：`python -c "from mopr.log import logger"`。
+- 内置工具 `tools/` 无跨子包相对导入，可顶层 `python -m tools.*`，也可包化 `python -m mopr.tools.*`；提交信息「验证方式」优先采用包化形态。
+- 发现文档/产物中过时或错误的导入命令时，在 AGENTS.md / BUILDING.md 等人工维护文档中修正；CHANGELOG.md 由 autochangelog 自动生成/刷新，其内容（含历史验证命令）**禁止手工编辑**。
+
+## C++ 头文件引用约定
+
+- **公共头文件之间的跨目录引用一律用「相对当前文件的相对路径」**（引号形式）：`runtime/once.h` 引 `base/cron.h` 必须写 `#include "../base/cron.h"`；**禁止**仓库根相对路径（`"base/cron.h"`）与尖括号形式（`<base/cron.h>`）。
+- 原因：mopr 公共头文件随安装统一放入 `include/mopr/<模块>/`（如 `include/mopr/base/cron.h`），安装后 include 根为 `include/`，仓库根相对路径与尖括号形式均搜索不到；相对路径的目录关系在源码树与安装后保持一致。
+- 同目录引用写 `#include "error.h"`；第三方头文件仍用尖括号（`#include <spdlog/spdlog.h>`）。
+- `.cpp`、`tests/`、`benchmark/` 等不随安装分发的文件可用仓库根相对路径（构建期由 `$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}>` 提供 include 根）。
+- 使用方包含安装后的头文件写 `<mopr/<模块>/<头文件>.h>`（如 `<mopr/runtime/once.h>`）。
+
+## C++ 命名空间与头文件宏约定
+
+- **命名空间**：以项目名 `mopr` 为根，**仓库根路径下的子目录为第二级**，多级目录依次下探：
+  - `base/timestamp.h` → `mopr::base`；`storage/storage.h` → `mopr::storage`；
+  - `distributed/id/hlc.h` → `mopr::distributed::id`；`encoding/csv.h` → `mopr::encoding`。
+- 同一模块内可按文件/职责再设下一级子命名空间（如 `base/strings.h` → `mopr::base::strings`；`encoding/csv.h` → `mopr::encoding::csv`；`encoding/json.h` → `mopr::encoding::json`，含 `mopr::encoding::json_detail` / `mopr::encoding::safe_json` / `mopr::encoding::unsafe_json`；`encoding/yaml.h` → `mopr::encoding::yaml` / `mopr::encoding::safe_yaml`）。
+- **禁止**使用未挂 `mopr` 根的顶层命名空间（如 `namespace encoding`、`namespace runtime`）。第三方库自身的顶层命名空间（如 csv-parser 的 `csv`、yaml-cpp 的 `YAML`）不得作为本项目的命名空间根，与本项目命名空间冲突时一律以全局限定形式书写（`::csv::`）。
+- **头文件宏（`#ifndef` 守卫）**：`MOPR_{大写的目录名}_{文件名}_H`，目录层级用下划线连接，文件名取去扩展名的主体：
+  - `encoding/csv.h` → `MOPR_ENCODING_CSV_H`；`encoding/charsets.h` → `MOPR_ENCODING_CHARSETS_H`；
+  - `distributed/id/hlc.h` → `MOPR_DISTRIBUTED_ID_HLC_H`；`base/strings.h` → `MOPR_BASE_STRINGS_H`。
+- 守卫宏与 `#pragma once` 并存；`#endif` 行以注释回写宏名（如 `#endif // MOPR_ENCODING_CSV_H`）。
+- 新增公共头文件一律遵循上述规则。既有不合规处按模块逐个收敛（`runtime::*` → `mopr::runtime::*`、`base/filesystem.h` 的 `filesystem` → `mopr::base::filesystem`、`base/except.h` 的 `quant1x` → `mopr::base`、`base/mmap.h` 的全局 `file_mmap` / `mmap_open` / `mmap_flush` / `mmap_close` → `mopr::base` 内的 `MmapHandle` / `mmap_open` / `mmap_flush` / `mmap_close`），不做一次性大范围改名。
+- **公开符号命名跨语言一致**（同一语义在各语言同名，便于跨语言对照与回溯）：
+  - **公开函数名一致**：Python 与 C++ 使用同一函数名（如 Python `mmap_open` ↔ C++ `mmap_open`），不因语言差异改名；Rust / Go 沿用本语言惯例的，须在模块文档的 API 对照表中给出对应关系。
+  - **函数名带模块前缀时不套同名命名空间**：函数名已含模块前缀（如 `mmap_`）时，C++ 侧不再套一层同名命名空间——`mmap_open` 直接位于 `mopr::base`，而非 `mopr::base::mmap::mmap_open`（同风格参考 `base/region.h` 的 `region_currency` / `region_timezone`）。
+  - **公开结构体 typedef 统一 `mopr_` 前缀**：结构体标签与 typedef 用同名风格，如 `typedef struct mopr_xxx mopr_xxx_t;`；但跨语言共享的**句柄类型除外**——句柄跨语言同名，C++ 侧直接定义 `struct MmapHandle`（与 Python / Rust / Go 的 `MmapHandle` 一字不差），不套 `mopr_xxx_t` 风格。
+  - **句柄类型不得命名 `File`**：句柄承载的是映射而不是文件（文件句柄只是其内部成员之一），`File` 会与 `os.File` / 文件流混淆；跨语言统一用 `MmapHandle`（C++ 为 `struct MmapHandle`）。
+  - **句柄操作遵循语言惯例**：Python / Rust / Go 用句柄方法（`flush` / `close`、`Flush` / `Close`），C++ 句柄是 POD，用同名自由函数（`mmap_flush` / `mmap_close`）与之一一对应。
+  - **同一语义可同时提供「公开 API + RAII 类」两层**：第一层为跨平台公开 API（如 `mmap_open` / `mmap_flush` / `mmap_close` + 句柄），资源由调用方显式管理；第二层为跨语言同名的 RAII 类（如 `MappedMemory`：`MappedMemory.open` 打开，析构 / `Drop` / `with` / `defer` 自动释放）。两层共用同一实现、语义必须一致，区别仅在释放时机；模块文档须给出两层对照表（示例见 `base/mmap.md`「1. 分层与命名」）。
+  - **RAII 类名不得与模块名重复**：类名不叫 `mmap` / `Mmap`（与模块名、包名重复，且易被误读为句柄），统一用其语义名（如 `MappedMemory`），并跨语言同名；句柄另用 `XxxHandle`（如 `MmapHandle`，四语言同名，C++ 亦为 `struct MmapHandle`）。
+- 已知遗留（需按模块逐一评估，勿批量替换）：`base/common.h` 的全局 typedef 与常量（`i8` / `u8` / … 为标量别名、非结构体 typedef，不适用 `mopr_` 前缀约定），`base/format.h` 的全局探测模板与 `std::vector` 的 `operator<<`（依赖 ADL / 非限定查找，移入命名空间会导致使用方找不到），`tests/` 下 `*_test_types` 等测试辅助命名空间。
+
+## 测试规范
+
+系统级/底层组件（持久化、状态机、并发控制、底层资源管理等）的测试须遵循 [docs/system-component-testing-spec.md](docs/system-component-testing-spec.md)：
+
+- 覆盖六个维度：API 契约与边界防御、状态机生命周期、崩溃一致性与故障注入（**必选**）、不变量与属性测试、并发竞态、性能资源；
+- 测试以**不变量 (Invariants)** 为准绳，防御性优先于验证性，重点验证"失败时是否保持状态一致"；
+- 崩溃模拟必须用**进程级终止**（`os._exit` / `abort` / `kill -9`），不得用语言层异常或优雅退出替代；
+- 每个用例环境绝对隔离（独立临时目录/端口/内存空间），不依赖执行顺序。
+
+## git 提交规范
+
+### 1. 提交信息规范（含上级仓库约定）
+
+以下约定与上级 `quant1x` 仓库的提交规范保持一致：
+
+- **提交标题与正文必须使用中文**，准确说明本次变更内容；必要时可保留英文术语（如 `fmt`、`VcpkgEnabled`、`conan_toolchain`）作为对象标识。
+- **主题统一模板**：`<type>[<language>]：<summary>`（注意冒号为全角 `：`）。
+  - `<type>` 取值：`feat`（新特性）、`fix`（修复）、`refactor`（重构）、`perf`（性能）、`docs`（文档）、`test`（测试）、`chore`（例行维护）。
+  - `<language>` 取值：`python`、`c++`、`rust`、`go`、`java`、`multi`。mopr 是单仓多语言库（monolibrary），同一语义将来可能有多种语言实现，必须如实标注；本仓库当前以 `c++` 为主。多语言组合用半角逗号 `,` 分隔并按语义顺序书写（如 `python,c++`、`c++,rust`、`python,c++,rust,go,java`）——注意 `c++` 自身含 `+`，不用 `+` 连接以免出现 `c+++rust` 这类难读形式；变更仅涉及构建/工具/文档等不含代码语言的杂项时，标注其影响的实现语言，或使用 `multi`。
+  - **主题禁止仅写空泛描述**（如 `update` / `optimize` / `fix` 这类无对象的词），必须指明对象与语言，例如：
+    - `fix[c++]：修正 conan 静态运行时链接被 vcpkg 集成劫持的问题`
+    - `feat[c++]：重构 conan/cmake 多配置构建体系`
+    - `docs[c++]：更新 BUILDING.md 构建矩阵`
+- **正文**在标题后空一行，以 `- ` 分条列出要点；**跨语言同步改动**（本仓库如引入 `c++,rust` 等）正文必须补充：
+  1. 变更概述；
+  2. 涉及语言与文件范围；
+  3. 语义一致性说明；
+  4. 验证方式/测试命令。
+
+  ```
+  feat[c++]：新增按 build_type/runtime 分目录的构建布局
+
+  - conanfile.layout 按 build_type 与 compiler.runtime 推导独立目录
+  - 验证：conan install . --build=missing && cmake --preset release-dynamic
+  ```
+
+- **提交信息不得包含版本号、Git Tag 或发布相关信息**；tag 与版本号管理如另有工具负责（如 [autochangelog](https://gitee.com/quant1x/autochangelog)），不得手动干预。
+- 提交前必须逐项核对清单（Checklist）：
+  - [ ] 主题是否符合 `type[language]：summary` 模板？
+  - [ ] `type` 是否真实反映本次变更类型？
+  - [ ] `language` 是否准确标注本次涉及的开发语言，未标注或误标注视为不合规？
+  - [ ] 标题是否避免空泛描述、明确对象和影响？
+  - [ ] 正文是否包含要点（跨语言时含变更概述、文件范围、语义一致性、验证方式）？
+  - [ ] 是否未包含版本号 / Git Tag / 发布相关字符串？
+  - [ ] 是否以中文为主，能按语言维度快速过滤和回溯？
+
+  任一项未满足，必须在提交前修正，不能直接提交。
+
+### 2. Windows 下提交信息的字符集约定（重要）
+
+**背景**：Windows PowerShell 下在命令行内直接内嵌中文提交信息，会因 GBK/UTF-8 编码错乱导致解析失败（报错形如"字符串缺少终止符"或中文乱码），且此类失败发生在命令解析阶段，`&&` 前序命令（如 `git add`）也不会执行。
+
+**标准做法**：涉及中文的提交信息不得直接写入命令行参数，必须按以下流程执行：
+
+1. 用工具（write_to_file）将提交信息写入 UTF-8 编码的临时文件，例如 `<仓库根>/.git/commit-msg.tmp`（放在 `.git/` 内，不污染工作树）：
+   ```
+   chore: 中文标题
+
+   - 正文要点一
+   - 正文要点二
+   ```
+2. 依次执行暂存与提交：
+   ```
+   git add <文件>
+   git commit -F .git/commit-msg.tmp
+   ```
+3. 提交成功后删除临时文件：
+   ```
+   Remove-Item .git/commit-msg.tmp
+   ```
+
+**推论**：任何需要在 Windows 命令行传递的中文内容（提交信息、`-m` 参数、脚本输入等）都应优先改用文件传递（`-F`、`--file` 等参数），规避编码问题。
+
+### 3. 其他
+
+- 除非用户明确要求，不得执行 `git commit`、`git push`、`git rebase` 等写操作。
+- 不做破坏性 git 操作（`push --force`、`reset --hard` 等）。
+- tag 与版本号管理如另有工具负责（如 [autochangelog](https://gitee.com/quant1x/autochangelog)），不得手动干预。
+- autochangelog 安装方法见 [BUILDING.md](BUILDING.md)「版本发布（autochangelog）」。