openmodus 0.0.1__tar.gz

openmodus-0.0.1/.gitignore

@@ -0,0 +1,46 @@
+# Python environments and bytecode
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Test, analysis, and coverage state
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.hypothesis/
+.nox/
+.tox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Distribution artifacts
+dist/
+build/
+.eggs/
+*.egg
+*.egg-info/
+
+# Local configuration and editor state
+.env
+.env.*
+!.env.example
+!.env.template
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# Repository-local agent projections and generated workspaces
+/.agents/
+/.codex/
+/.claude/
+/.cursor/
+/.codebuddy/
+/.modus/
+/.worktrees/
+/.benchmark-state/

openmodus-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tencent Music Entertainment Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openmodus-0.0.1/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.5
+Name: openmodus
+Version: 0.0.1
+Summary: Evidence-backed authored knowledge for coding agents.
+Author: Modus contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: code-intelligence,coding-agents,developer-tools,knowledge-management,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: click<8.4,>=8.1.0
+Requires-Dist: jsonschema<5.0,>=4.0
+Requires-Dist: networkx<4.0,>=3.4
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: questionary<3.0,>=2.1
+Requires-Dist: tree-sitter-c-sharp<0.25,>=0.23
+Requires-Dist: tree-sitter-c<0.25,>=0.23
+Requires-Dist: tree-sitter-cpp<0.25,>=0.23
+Requires-Dist: tree-sitter-go<0.26,>=0.23
+Requires-Dist: tree-sitter-java<0.25,>=0.23
+Requires-Dist: tree-sitter-javascript<0.26,>=0.23
+Requires-Dist: tree-sitter-kotlin<2.0,>=1.0
+Requires-Dist: tree-sitter-php<0.25,>=0.23
+Requires-Dist: tree-sitter-python<0.26,>=0.23
+Requires-Dist: tree-sitter-rust<0.25,>=0.23
+Requires-Dist: tree-sitter-typescript<0.25,>=0.23
+Requires-Dist: tree-sitter<0.26,>=0.23.0
+Requires-Dist: typer<0.26,>=0.12.0
+Provides-Extra: test
+Requires-Dist: coverage[toml]<8.0,>=7.0; extra == 'test'
+Requires-Dist: mypy<3.0,>=1.19; extra == 'test'
+Requires-Dist: pytest<10.0,>=7.0; extra == 'test'
+Requires-Dist: ruff<1.0,>=0.5.0; extra == 'test'
+Requires-Dist: types-jsonschema<5.0,>=4.0; extra == 'test'
+Requires-Dist: types-networkx<4.0,>=3.4; extra == 'test'
+Requires-Dist: types-pyyaml<7.0,>=6.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Modus
+
+Modus turns a repository and its business material into reviewable,
+source-grounded Markdown knowledge for coding agents.
+
+The first open-source release keeps one durable product: authored knowledge.
+Source graphs are not a second database. During `/modus-init` or
+`/modus-reinit`, a disposable analyzer builds an in-memory evidence graph,
+projects the evidence needed for authoring, and then releases its working
+state.
+
+## Design
+
+```text
+repository bytes + build context
+              │ freeze
+              ▼
+      CST / structural IR
+              │
+       project binding
+              │
+   compiler observations (optional)
+              │
+   explicit semantic reconciliation
+              │
+      in-memory evidence graph
+              │ project
+              ▼
+ deterministic JSON evidence bundle
+              │ current init/reinit only
+              ▼
+ reviewed Markdown knowledge
+```
+
+This separation is intentional:
+
+- source bytes and build configuration answer which code was analyzed;
+- CST, project binding, and compiler observations retain their own provenance;
+- exact, candidate, heuristic, and unresolved relationships stay distinct;
+- conflicts become diagnostics instead of being overwritten;
+- a method witness points back to source rather than copying method bodies;
+- business domains and modules remain an agent-and-user judgment, never a
+  clustering side effect.
+
+Ordinary knowledge use, hooks, status, and incremental updates read current
+source and authored Markdown only. They cannot import or read initialization
+analysis.
+
+## Product surface
+
+Modus installs exactly five knowledge skills:
+
+- `using-modus` progressively adds project evidence only when the task needs it;
+- `modus-init` and `modus-reinit` create or fully refresh authored knowledge;
+- `modus-update-knowledge` performs an explicitly requested scoped update;
+- `modus-sync-knowledge` silently revises knowledge only after a code change
+  actually changes durable semantics or source anchors.
+
+The first three authoring workflows are exposed as `/modus-init`,
+`/modus-reinit`, and `/modus-update-knowledge`. `using-modus` and
+`modus-sync-knowledge` are agent lifecycle helpers, not extra user workflows.
+Unrelated conversations never inspect Modus state.
+
+The project layout keeps control and data ownership visibly separate:
+
+```text
+.modus/            config, manifest, neutral skills/commands, hooks
+modus/knowledge/   the only durable product data
+modus/.cache/      disposable analysis and authoring state, created on demand
+```
+
+No other top-level entry belongs under `modus/`.
+
+## Evidence bundle
+
+Each successful build publishes one immutable bundle:
+
+```text
+modus/.cache/init-analysis/bundles/<bundleDigest>/
+    ├── manifest.json
+    ├── snapshot/{index.json,sources/,build-units/}
+    ├── scope/{index.json,candidates/}
+    ├── services/{index.json,boundaries/}
+    ├── diagnostics.json
+    └── evidence/{index.json,files/}
+```
+
+Each namespace is a bounded stable-key range catalog. Source files, build
+units, technical candidates, service boundaries, and evidence records have
+independent shards. Scope exposes explainable technical signals and navigation,
+never business names or conclusions.
+
+The bundle contract has no absolute paths, timestamps, random IDs, raw graph,
+SQL database, WAL, historical generation, full-text index, or query language.
+JSON is stable-sorted UTF-8 with an explicit schema version.
+
+Publication occurs in a same-filesystem temporary directory. The manifest binds
+exactly five Merkle roots; recursive validation rejects bad catalogs, records,
+references, paths, digests, and orphan shards before atomic rename. Current
+initialization consumes only the `BuildReceipt` returned by its own invocation.
+
+## Commands
+
+The supported CLI is deliberately small:
+
+```text
+modus init
+modus update
+modus help
+modus uninstall
+modus status
+modus --version
+```
+
+`modus uninstall` removes managed project integration and the local CLI after
+showing a preview. Authored knowledge under `modus/knowledge` is retained by
+default; deleting that durable data requires the explicit
+`modus uninstall --delete-knowledge` option.
+
+Initialization Skills use one internal adapter:
+
+```text
+modus internal init-analysis build --root . --compiler auto --json
+modus internal init-analysis select --root . --bundle-digest <digest> --source-snapshot-digest <digest> --view scope|services|evidence --json
+```
+
+The command is synchronous. Progress is written to stderr; JSON stdout contains
+only the bundle digest, source-snapshot digest, coverage, and diagnostics
+summaries. Select returns complete records under a byte/item budget and an
+optional stable cursor. There is no graph update/status/query/export/doctor or
+persisted progress command.
+
+The design is informed by public ideas from CodeWiki, Aider, GitNexus,
+Repomix, and OpenDeepWiki, while the implementation, contracts, tests, prompts,
+and assets are independently authored for Modus. No source code from those
+projects is included.
+
+## Failure semantics
+
+Snapshot drift, an invalid manifest, a digest mismatch, or cross-bundle mixing
+fails the current analysis. A failed build does not replace the last complete
+bundle, but the current init/reinit also does not consume that older bundle.
+It immediately continues from current source and user material.
+
+A local parser or compiler-provider failure lowers only the affected evidence.
+It never means the repository has no business behavior. Compiler observations
+cannot silently overwrite CST or project binding; reconciliation retains the
+chosen result, alternatives, reason, context, and source witness.
+
+## Workspace semantics
+
+A workspace root never runs initialization analysis. When a user chooses to
+initialize members that have no authored knowledge, each member runs as an
+independent single repository. Bundle identities and evidence never cross
+member roots.
+
+## Installation
+
+Modus is distributed on PyPI as `openmodus`, while the installed command and
+Python import remain `modus`:
+
+```bash
+uv tool install openmodus
+modus --version
+modus init
+```
+
+Python 3.11 or newer is required.
+
+## Development
+
+The package supports Python 3.11–3.14.
+
+```bash
+uv sync --locked --extra test
+uv run pytest
+uv run ruff check .
+uv run mypy
+uv build
+```
+
+The architecture boundary test rejects imports of `modus.init_analysis` from
+ordinary runtime packages. Distribution checks also reject legacy
+`modus.graph`, SQLite stores, WAL/query code, and obsolete graph commands.
+
+The public application boundary is intentionally narrow:
+
+```python
+from modus.init_analysis import BuildOptions, EvidenceRequest
+from modus.init_analysis import build, open_bundle, select
+
+receipt = build(".", BuildOptions(compiler_mode="auto"))
+bundle = open_bundle(
+    ".",
+    receipt.bundle_digest,
+    receipt.source_snapshot_digest,
+)
+scope = select(bundle, EvidenceRequest(view="scope"))
+```
+
+Everything behind these calls is implementation detail. This keeps the first
+release understandable today and leaves future machine-query capabilities free
+to earn their own explicit product contract later.

openmodus-0.0.1/README.md

@@ -0,0 +1,203 @@
+# Modus
+
+Modus turns a repository and its business material into reviewable,
+source-grounded Markdown knowledge for coding agents.
+
+The first open-source release keeps one durable product: authored knowledge.
+Source graphs are not a second database. During `/modus-init` or
+`/modus-reinit`, a disposable analyzer builds an in-memory evidence graph,
+projects the evidence needed for authoring, and then releases its working
+state.
+
+## Design
+
+```text
+repository bytes + build context
+              │ freeze
+              ▼
+      CST / structural IR
+              │
+       project binding
+              │
+   compiler observations (optional)
+              │
+   explicit semantic reconciliation
+              │
+      in-memory evidence graph
+              │ project
+              ▼
+ deterministic JSON evidence bundle
+              │ current init/reinit only
+              ▼
+ reviewed Markdown knowledge
+```
+
+This separation is intentional:
+
+- source bytes and build configuration answer which code was analyzed;
+- CST, project binding, and compiler observations retain their own provenance;
+- exact, candidate, heuristic, and unresolved relationships stay distinct;
+- conflicts become diagnostics instead of being overwritten;
+- a method witness points back to source rather than copying method bodies;
+- business domains and modules remain an agent-and-user judgment, never a
+  clustering side effect.
+
+Ordinary knowledge use, hooks, status, and incremental updates read current
+source and authored Markdown only. They cannot import or read initialization
+analysis.
+
+## Product surface
+
+Modus installs exactly five knowledge skills:
+
+- `using-modus` progressively adds project evidence only when the task needs it;
+- `modus-init` and `modus-reinit` create or fully refresh authored knowledge;
+- `modus-update-knowledge` performs an explicitly requested scoped update;
+- `modus-sync-knowledge` silently revises knowledge only after a code change
+  actually changes durable semantics or source anchors.
+
+The first three authoring workflows are exposed as `/modus-init`,
+`/modus-reinit`, and `/modus-update-knowledge`. `using-modus` and
+`modus-sync-knowledge` are agent lifecycle helpers, not extra user workflows.
+Unrelated conversations never inspect Modus state.
+
+The project layout keeps control and data ownership visibly separate:
+
+```text
+.modus/            config, manifest, neutral skills/commands, hooks
+modus/knowledge/   the only durable product data
+modus/.cache/      disposable analysis and authoring state, created on demand
+```
+
+No other top-level entry belongs under `modus/`.
+
+## Evidence bundle
+
+Each successful build publishes one immutable bundle:
+
+```text
+modus/.cache/init-analysis/bundles/<bundleDigest>/
+    ├── manifest.json
+    ├── snapshot/{index.json,sources/,build-units/}
+    ├── scope/{index.json,candidates/}
+    ├── services/{index.json,boundaries/}
+    ├── diagnostics.json
+    └── evidence/{index.json,files/}
+```
+
+Each namespace is a bounded stable-key range catalog. Source files, build
+units, technical candidates, service boundaries, and evidence records have
+independent shards. Scope exposes explainable technical signals and navigation,
+never business names or conclusions.
+
+The bundle contract has no absolute paths, timestamps, random IDs, raw graph,
+SQL database, WAL, historical generation, full-text index, or query language.
+JSON is stable-sorted UTF-8 with an explicit schema version.
+
+Publication occurs in a same-filesystem temporary directory. The manifest binds
+exactly five Merkle roots; recursive validation rejects bad catalogs, records,
+references, paths, digests, and orphan shards before atomic rename. Current
+initialization consumes only the `BuildReceipt` returned by its own invocation.
+
+## Commands
+
+The supported CLI is deliberately small:
+
+```text
+modus init
+modus update
+modus help
+modus uninstall
+modus status
+modus --version
+```
+
+`modus uninstall` removes managed project integration and the local CLI after
+showing a preview. Authored knowledge under `modus/knowledge` is retained by
+default; deleting that durable data requires the explicit
+`modus uninstall --delete-knowledge` option.
+
+Initialization Skills use one internal adapter:
+
+```text
+modus internal init-analysis build --root . --compiler auto --json
+modus internal init-analysis select --root . --bundle-digest <digest> --source-snapshot-digest <digest> --view scope|services|evidence --json
+```
+
+The command is synchronous. Progress is written to stderr; JSON stdout contains
+only the bundle digest, source-snapshot digest, coverage, and diagnostics
+summaries. Select returns complete records under a byte/item budget and an
+optional stable cursor. There is no graph update/status/query/export/doctor or
+persisted progress command.
+
+The design is informed by public ideas from CodeWiki, Aider, GitNexus,
+Repomix, and OpenDeepWiki, while the implementation, contracts, tests, prompts,
+and assets are independently authored for Modus. No source code from those
+projects is included.
+
+## Failure semantics
+
+Snapshot drift, an invalid manifest, a digest mismatch, or cross-bundle mixing
+fails the current analysis. A failed build does not replace the last complete
+bundle, but the current init/reinit also does not consume that older bundle.
+It immediately continues from current source and user material.
+
+A local parser or compiler-provider failure lowers only the affected evidence.
+It never means the repository has no business behavior. Compiler observations
+cannot silently overwrite CST or project binding; reconciliation retains the
+chosen result, alternatives, reason, context, and source witness.
+
+## Workspace semantics
+
+A workspace root never runs initialization analysis. When a user chooses to
+initialize members that have no authored knowledge, each member runs as an
+independent single repository. Bundle identities and evidence never cross
+member roots.
+
+## Installation
+
+Modus is distributed on PyPI as `openmodus`, while the installed command and
+Python import remain `modus`:
+
+```bash
+uv tool install openmodus
+modus --version
+modus init
+```
+
+Python 3.11 or newer is required.
+
+## Development
+
+The package supports Python 3.11–3.14.
+
+```bash
+uv sync --locked --extra test
+uv run pytest
+uv run ruff check .
+uv run mypy
+uv build
+```
+
+The architecture boundary test rejects imports of `modus.init_analysis` from
+ordinary runtime packages. Distribution checks also reject legacy
+`modus.graph`, SQLite stores, WAL/query code, and obsolete graph commands.
+
+The public application boundary is intentionally narrow:
+
+```python
+from modus.init_analysis import BuildOptions, EvidenceRequest
+from modus.init_analysis import build, open_bundle, select
+
+receipt = build(".", BuildOptions(compiler_mode="auto"))
+bundle = open_bundle(
+    ".",
+    receipt.bundle_digest,
+    receipt.source_snapshot_digest,
+)
+scope = select(bundle, EvidenceRequest(view="scope"))
+```
+
+Everything behind these calls is implementation detail. This keeps the first
+release understandable today and leaves future machine-query capabilities free
+to earn their own explicit product contract later.

openmodus-0.0.1/README.zh-CN.md

@@ -0,0 +1,164 @@
+# Modus
+
+Modus 将代码仓库与业务材料整理为可评审、可追溯到源码的 Markdown
+知识，供编码 Agent 使用。
+
+首版开源版本只有一种长期产品资产：正文知识。源码图不是第二套数据库。
+`/modus-init` 或 `/modus-reinit` 会临时构建内存证据图，投影出本轮
+正文创作需要的证据，随后释放工作状态。
+
+## 设计主线
+
+```text
+源码字节 + 真实构建上下文
+          │ 冻结
+          ▼
+      CST / 结构 IR
+          │
+       项目绑定
+          │
+    编译语义观察（可选）
+          │
+      显式语义协调
+          │
+       内存证据图
+          │ 投影
+          ▼
+  确定性 JSON 证据包
+          │ 仅当前 init/reinit
+          ▼
+    经评审的 Markdown 正文
+```
+
+这条边界保证：
+
+- 源码摘要与构建配置唯一回答“分析的是哪一份代码”；
+- CST、项目绑定和编译观察分别保留来源；
+- exact、candidate、heuristic、unresolved 不被混成一个置信分；
+- 冲突进入 diagnostics，不由更强层级无痕覆盖；
+- 方法证据只保存见证坐标，不复制完整方法体；
+- Domain/Module 仍由 Agent 理解业务、用户确认边界，不由聚类直接命名。
+
+普通知识使用、hooks、公开 status 与增量更新只读取当前源码和正文，
+不能导入或读取初始化分析。
+
+## 产品边界
+
+Modus 只安装五个知识库 Skill：
+
+- `using-modus` 仅在任务需要当前项目事实时渐进增强；
+- `modus-init` 与 `modus-reinit` 创建或完整刷新正文知识；
+- `modus-update-knowledge` 执行用户主动要求的局部更新；
+- `modus-sync-knowledge` 仅在代码变化真正影响长期语义或源码锚点时静默回刷。
+
+主动入口只有 `/modus-init`、`/modus-reinit`、`/modus-update-knowledge`。
+`using-modus` 与 `modus-sync-knowledge` 是 Agent 生命周期能力，不增加用户流程；
+炒股、翻译、一般问答等不依赖当前项目事实的会话完全不读取 Modus。
+
+控制面与数据面的边界固定为：
+
+```text
+.modus/            配置、安装清单、中立 Skill/命令与 Hook
+modus/knowledge/   唯一长期产品数据
+modus/.cache/      按需创建、可丢弃的分析与创作状态
+```
+
+`modus/` 下不允许出现其他一级文件或目录。
+
+## JSON 证据包
+
+```text
+modus/.cache/init-analysis/bundles/<bundleDigest>/
+    ├── manifest.json
+    ├── snapshot/{index.json,sources/,build-units/}
+    ├── scope/{index.json,candidates/}
+    ├── services/{index.json,boundaries/}
+    ├── diagnostics.json
+    └── evidence/{index.json,files/}
+```
+
+每个 namespace 都是按稳定 key 排序的有界 range catalog；源码文件、构建
+单元、技术候选、服务边界和 evidence record 各自分片。Scope 只给出可解释
+的技术 signals 与 navigation，不生成业务命名或业务结论。
+
+证据包不包含绝对路径、时间戳、随机 ID、原始完整图、SQL 数据库、WAL、
+历史 generation、全文索引或通用查询语言。JSON 使用稳定排序、UTF-8、
+统一换行和显式 schemaVersion。
+
+构建先写同文件系统临时目录，manifest 只绑定五个 Merkle 根；递归校验
+catalog、record、引用、路径、摘要和孤儿分片后原子发布。当前初始化只消费
+自己调用返回的 `BuildReceipt`。
+
+## CLI
+
+公开命令刻意保持精简：
+
+```text
+modus init
+modus update
+modus help
+modus uninstall
+modus status
+modus --version
+```
+
+`modus uninstall` 会先展示预览，再卸载受管项目集成与本机 CLI。
+`modus/knowledge` 正文知识默认保留；只有显式使用
+`modus uninstall --delete-knowledge` 才会删除这份长期数据。
+
+初始化 Skill 只使用一个内部适配器：
+
+```text
+modus internal init-analysis build --root . --compiler auto --json
+modus internal init-analysis select --root . --bundle-digest <digest> --source-snapshot-digest <digest> --view scope|services|evidence --json
+```
+
+命令同步完成，阶段进度写 stderr；构建回执只返回 bundleDigest、
+sourceSnapshotDigest、覆盖摘要与 diagnostics 摘要。select 按字节/条目预算
+返回完整记录和可选稳定游标。
+不存在 graph update/status/query/export/doctor 或持久化 progress 命令。
+
+本设计参考 CodeWiki、Aider、GitNexus、Repomix 与 OpenDeepWiki 的公开理念，
+但实现、合同、测试、提示词和资产均围绕 Modus 独立编写，不包含这些项目的源码。
+
+## 失败语义
+
+源码快照漂移、manifest 缺失、摘要不符或跨 bundle 混读会让本轮分析失败。
+失败不会覆盖最近完整包，但本轮 init/reinit 也不会回退读取旧包，而是立即
+用当前源码与材料继续。
+
+局部 parser 或 compiler Provider 失败只降低对应证据，不能解释成全仓没有
+业务事实。编译观察不能静默覆盖 CST 或项目绑定；协调结果保留选中关系、
+备选项、原因、上下文和源码见证。
+
+workspace 根永不运行 init-analysis。用户选择初始化没有正文的成员时，每个
+成员作为独立单仓分别构建，bundle 身份和消费上下文互不污染。
+
+## 安装
+
+Modus 在 PyPI 上的发行包名为 `openmodus`，安装后的命令与 Python 导入名
+仍然是 `modus`：
+
+```bash
+uv tool install openmodus
+modus --version
+modus init
+```
+
+需要 Python 3.11 或更高版本。
+
+## 开发
+
+```bash
+uv sync --locked --extra test
+uv run pytest
+uv run ruff check .
+uv run mypy
+uv build
+```
+
+架构边界测试会阻止普通运行时导入 `modus.init_analysis`；发布包检查会
+拒绝旧 `modus.graph`、SQLite store、WAL/query 代码和废弃 graph 命令。
+
+公共 Python 边界只有 `build`、`open_bundle`、`select` 及必要的类型
+契约。解析器、Provider、内存图和 JSON 编码细节均为内部实现。