harbor-spec 1.0.0__tar.gz

harbor_spec-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 李健
+
+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.

harbor_spec-1.0.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: harbor-spec
+Version: 1.0.0
+Summary: Harbor-spec v1.0.2 reference implementation (Python-only)
+License: MIT License
+        
+        Copyright (c) 2025 李健
+        
+        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.
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# ⚓ Harbor
+### The Context Governance Engine for Vibe Coding
+
+[![CI Status](https://img.shields.io/github/actions/workflow/status/your-org/harbor-spec/ci.yml?style=flat-square)](https://github.com/your-org/harbor-spec/actions)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue?style=flat-square)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+[![Strictness](https://img.shields.io/badge/Harbor-L3%20Strict-purple?style=flat-square)](https://github.com/your-org/harbor-spec)
+
+**让 AI 像代码一样被管理，让上下文像 Git 一样可追溯。**
+
+[理念 (Philosophy)] • [架构 (Architecture)] • [快速开始 (Quick Start)] • [工作流 (Workflow)]
+
+</div>
+
+---
+
+## 🌌 The Era of Vibe Coding
+
+编程正在经历一场范式转移。我们正在从 "Writing Code"（逐行编写）转向 **"Vibe Coding"**（通过自然语言与 AI 协作生成）。
+
+在这个新时代，**代码生成的边际成本趋近于零，但上下文维护的成本却在指数级上升。**
+- AI 改了代码，Docstring 还没改？👉 **Context Drift (上下文漂移)**
+- 测试用例还在测旧版本的逻辑？👉 **Validation Gap (验证断层)**
+- 为什么上周我们要把这个参数改成 Optional？👉 **Memory Loss (决策遗忘)**
+
+**Harbor** 应运而生。它不是另一个 Copilot，它是 **Copilot 的监管者**。它是一套用于治理 AI 生成代码的 **"良知" (Conscience)** 与 **"记忆" (Memory)** 系统。它是“程序员到上下文工程师”这一革命性转变的关键工具，它的目标是成为vibe coding时代的Git。
+
+## 🛡️ Core Philosophy
+
+Harbor 的核心设计理念基于 **L3 Contract Theory**：
+
+1.  **Code is Volatile, Contract is Immutable**: 实现代码可以由 AI 随意重写，但 L3 级 Docstring（契约）是锚点，必须由人类或高级审计确认。
+2.  **Noise is Signal**: 未经索引的代码、未同步的文档、未绑定的测试，都是系统中的“噪音”。Harbor 不会静默处理，而是将其显性化。
+3.  **Trust, but Verify**: 我们信任 AI 的编码能力，但必须通过 AST 静态分析和 LLM 语义审计来验证其产出。
+
+## 🏗️ Architecture
+
+Harbor 通过六大核心子系统构建了一个闭环的治理体系：
+
+```mermaid
+graph TD
+    Source[Source Code] -->|AST Parse| Adapter(Adapter)
+    Adapter -->|Contract Hash| Index(L3 Index / Memory)
+    
+    Index -->|Compare| Sync(Sync Engine)
+    Source -->|Body Hash| Sync
+    
+    Sync -->|Drift Detected| Status[CLI Status]
+    Sync -->|Diff Target| Audit(Semantic Guard)
+    
+    Env[.env / LLM] --> Audit
+    Audit -->|Semantic Check| Report[Audit Report]
+    
+    Tests[Test Cases] -->|DDT Binding| Validator(DDT Validator)
+    Index -->|Version Match| Validator
+    
+    Index -->|Aggregation| L2(L2 Generator)
+    Validator -->|Status| L2
+    
+    User[Developer] -->|Log Decision| Diary(Diary / History)
+````
+
+  - **🧠 Index (Memory)**: 这里的 `.harbor/cache` 是大脑，记录了代码的每一次“快照”与指纹。
+  - **⚖️ Sync (Conscience)**: 实时监测 "Implementation Drift"（代码变了，但契约没变）。
+  - **🌉 DDT (Bridge)**: **D**ecorator-driven **D**ata **T**esting。将测试用例与 L3 版本强绑定，拒绝“假绿灯”。
+  - **🤖 Audit (Guard)**: 集成 DeepSeek/OpenAI，对代码进行语义级审计，揪出逻辑与文档的违背之处。
+  - **📊 L2 (Dashboard)**: 自动生成 Markdown 视图，诚实地展示模块的测试覆盖率与契约状态。
+  - **📜 Diary (History)**: 结构化的决策日志，记录每一次变革背后的 "Why"。
+
+## ⚡ Quick Start
+
+### 1\. Installation
+
+Harbor 是一个纯 Python 工具，推荐在开发模式下安装：
+
+```bash
+git clone [https://github.com/your-org/harbor-spec.git](https://github.com/your-org/harbor-spec.git)
+cd harbor-spec
+pip install -e .
+```
+
+可选pypi安装：
+
+```bash
+pip install harbor-spec
+```
+
+### 2\. Configuration
+
+配置 LLM 以启用 AI 语义审计（支持 Ernie, DeepSeek, OpenAI 等兼容接口）：
+
+```bash
+cp .env.example .env
+# 编辑 .env 文件:
+# HARBOR_LLM_PROVIDER=openai
+# HARBOR_LLM_API_KEY=
+# HARBOR_LLM_BASE_URL=https://api.openai.com/v1
+# HARBOR_LANGUAGE=zh (可选，开启中文审计)
+```
+
+### 3\. Initialize
+
+构建初始索引，接管当前代码库：
+
+```bash
+harbor build-index
+```
+
+## 🎮 Workflow: A Day with Harbor
+
+### 1\. Check Status
+
+开始工作前，看看代码库是否干净。
+
+```bash
+harbor status
+# 输出: No changes detected. (Or list of drifts)
+```
+
+### 2\. Vibe Coding
+
+使用你喜欢的 AI 助手（Cursor, Windsurf, Copilot）修改代码。
+*假设你修改了 `harbor/utils.py` 的逻辑，但忘记更新 Docstring。*
+
+### 3\. Detect Drift
+
+Harbor 会发现你的代码实现了“偷跑”。
+
+```bash
+harbor status
+# 输出: M harbor.utils.func (Body changed, Contract static)
+```
+
+### 4\. AI Audit
+
+让 Harbor 的 AI 审计员检查你的修改是否违背了契约。
+
+```bash
+harbor audit --semantic
+# 输出: POSSIBLE_SEMANTIC_DRIFT ... [MISMATCH]: 代码抛出了 ValueError 但文档中未声明...
+```
+
+### 5\. Lock & Record
+
+修复问题后，更新索引并记录决策日志。
+
+```bash
+harbor build-index
+harbor diary log --summary "Refactor utils validation logic" --type refactor --importance high
+```
+
+## 🧩 Commands Cheatsheet
+
+| Command | Description |
+| :--- | :--- |
+| `harbor status` | 检查代码与索引的差异（Drift检测） |
+| `harbor build-index` | 更新 L3 索引缓存 (类似 `git commit`) |
+| `harbor audit --semantic` | 调用 LLM 进行语义一致性检查 |
+| `harbor ddt validate` | 验证测试用例与代码版本的绑定关系 |
+| `harbor gen l2` | 自动生成模块级的 README 文档 |
+| `harbor diary log` | 写入结构化的决策日志 |
+
+## 🤝 Contribution
+
+Harbor 遵循 **Strict L3** 开发规范。
+
+  - 所有 Public API 必须包含完整的 Google-style Docstring。
+  - 所有新增功能必须包含 DDT 测试绑定。
+  - 提交前请运行 `harbor audit --semantic` 自测。
+
+## 📄 License
+
+MIT © 2025 Harbor-spec Authors.

harbor_spec-1.0.0/README.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# ⚓ Harbor
+### The Context Governance Engine for Vibe Coding
+
+[![CI Status](https://img.shields.io/github/actions/workflow/status/your-org/harbor-spec/ci.yml?style=flat-square)](https://github.com/your-org/harbor-spec/actions)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue?style=flat-square)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+[![Strictness](https://img.shields.io/badge/Harbor-L3%20Strict-purple?style=flat-square)](https://github.com/your-org/harbor-spec)
+
+**让 AI 像代码一样被管理，让上下文像 Git 一样可追溯。**
+
+[理念 (Philosophy)] • [架构 (Architecture)] • [快速开始 (Quick Start)] • [工作流 (Workflow)]
+
+</div>
+
+---
+
+## 🌌 The Era of Vibe Coding
+
+编程正在经历一场范式转移。我们正在从 "Writing Code"（逐行编写）转向 **"Vibe Coding"**（通过自然语言与 AI 协作生成）。
+
+在这个新时代，**代码生成的边际成本趋近于零，但上下文维护的成本却在指数级上升。**
+- AI 改了代码，Docstring 还没改？👉 **Context Drift (上下文漂移)**
+- 测试用例还在测旧版本的逻辑？👉 **Validation Gap (验证断层)**
+- 为什么上周我们要把这个参数改成 Optional？👉 **Memory Loss (决策遗忘)**
+
+**Harbor** 应运而生。它不是另一个 Copilot，它是 **Copilot 的监管者**。它是一套用于治理 AI 生成代码的 **"良知" (Conscience)** 与 **"记忆" (Memory)** 系统。它是“程序员到上下文工程师”这一革命性转变的关键工具，它的目标是成为vibe coding时代的Git。
+
+## 🛡️ Core Philosophy
+
+Harbor 的核心设计理念基于 **L3 Contract Theory**：
+
+1.  **Code is Volatile, Contract is Immutable**: 实现代码可以由 AI 随意重写，但 L3 级 Docstring（契约）是锚点，必须由人类或高级审计确认。
+2.  **Noise is Signal**: 未经索引的代码、未同步的文档、未绑定的测试，都是系统中的“噪音”。Harbor 不会静默处理，而是将其显性化。
+3.  **Trust, but Verify**: 我们信任 AI 的编码能力，但必须通过 AST 静态分析和 LLM 语义审计来验证其产出。
+
+## 🏗️ Architecture
+
+Harbor 通过六大核心子系统构建了一个闭环的治理体系：
+
+```mermaid
+graph TD
+    Source[Source Code] -->|AST Parse| Adapter(Adapter)
+    Adapter -->|Contract Hash| Index(L3 Index / Memory)
+    
+    Index -->|Compare| Sync(Sync Engine)
+    Source -->|Body Hash| Sync
+    
+    Sync -->|Drift Detected| Status[CLI Status]
+    Sync -->|Diff Target| Audit(Semantic Guard)
+    
+    Env[.env / LLM] --> Audit
+    Audit -->|Semantic Check| Report[Audit Report]
+    
+    Tests[Test Cases] -->|DDT Binding| Validator(DDT Validator)
+    Index -->|Version Match| Validator
+    
+    Index -->|Aggregation| L2(L2 Generator)
+    Validator -->|Status| L2
+    
+    User[Developer] -->|Log Decision| Diary(Diary / History)
+````
+
+  - **🧠 Index (Memory)**: 这里的 `.harbor/cache` 是大脑，记录了代码的每一次“快照”与指纹。
+  - **⚖️ Sync (Conscience)**: 实时监测 "Implementation Drift"（代码变了，但契约没变）。
+  - **🌉 DDT (Bridge)**: **D**ecorator-driven **D**ata **T**esting。将测试用例与 L3 版本强绑定，拒绝“假绿灯”。
+  - **🤖 Audit (Guard)**: 集成 DeepSeek/OpenAI，对代码进行语义级审计，揪出逻辑与文档的违背之处。
+  - **📊 L2 (Dashboard)**: 自动生成 Markdown 视图，诚实地展示模块的测试覆盖率与契约状态。
+  - **📜 Diary (History)**: 结构化的决策日志，记录每一次变革背后的 "Why"。
+
+## ⚡ Quick Start
+
+### 1\. Installation
+
+Harbor 是一个纯 Python 工具，推荐在开发模式下安装：
+
+```bash
+git clone [https://github.com/your-org/harbor-spec.git](https://github.com/your-org/harbor-spec.git)
+cd harbor-spec
+pip install -e .
+```
+
+可选pypi安装：
+
+```bash
+pip install harbor-spec
+```
+
+### 2\. Configuration
+
+配置 LLM 以启用 AI 语义审计（支持 Ernie, DeepSeek, OpenAI 等兼容接口）：
+
+```bash
+cp .env.example .env
+# 编辑 .env 文件:
+# HARBOR_LLM_PROVIDER=openai
+# HARBOR_LLM_API_KEY=
+# HARBOR_LLM_BASE_URL=https://api.openai.com/v1
+# HARBOR_LANGUAGE=zh (可选，开启中文审计)
+```
+
+### 3\. Initialize
+
+构建初始索引，接管当前代码库：
+
+```bash
+harbor build-index
+```
+
+## 🎮 Workflow: A Day with Harbor
+
+### 1\. Check Status
+
+开始工作前，看看代码库是否干净。
+
+```bash
+harbor status
+# 输出: No changes detected. (Or list of drifts)
+```
+
+### 2\. Vibe Coding
+
+使用你喜欢的 AI 助手（Cursor, Windsurf, Copilot）修改代码。
+*假设你修改了 `harbor/utils.py` 的逻辑，但忘记更新 Docstring。*
+
+### 3\. Detect Drift
+
+Harbor 会发现你的代码实现了“偷跑”。
+
+```bash
+harbor status
+# 输出: M harbor.utils.func (Body changed, Contract static)
+```
+
+### 4\. AI Audit
+
+让 Harbor 的 AI 审计员检查你的修改是否违背了契约。
+
+```bash
+harbor audit --semantic
+# 输出: POSSIBLE_SEMANTIC_DRIFT ... [MISMATCH]: 代码抛出了 ValueError 但文档中未声明...
+```
+
+### 5\. Lock & Record
+
+修复问题后，更新索引并记录决策日志。
+
+```bash
+harbor build-index
+harbor diary log --summary "Refactor utils validation logic" --type refactor --importance high
+```
+
+## 🧩 Commands Cheatsheet
+
+| Command | Description |
+| :--- | :--- |
+| `harbor status` | 检查代码与索引的差异（Drift检测） |
+| `harbor build-index` | 更新 L3 索引缓存 (类似 `git commit`) |
+| `harbor audit --semantic` | 调用 LLM 进行语义一致性检查 |
+| `harbor ddt validate` | 验证测试用例与代码版本的绑定关系 |
+| `harbor gen l2` | 自动生成模块级的 README 文档 |
+| `harbor diary log` | 写入结构化的决策日志 |
+
+## 🤝 Contribution
+
+Harbor 遵循 **Strict L3** 开发规范。
+
+  - 所有 Public API 必须包含完整的 Google-style Docstring。
+  - 所有新增功能必须包含 DDT 测试绑定。
+  - 提交前请运行 `harbor audit --semantic` 自测。
+
+## 📄 License
+
+MIT © 2025 Harbor-spec Authors.

harbor_spec-1.0.0/harbor/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.2"
+

harbor_spec-1.0.0/harbor/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""Adapters package."""
+

harbor_spec-1.0.0/harbor/adapters/python/__init__.py

@@ -0,0 +1,2 @@
+"""Python language adapter."""
+

harbor_spec-1.0.0/harbor/adapters/python/parser.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import ast
+import hashlib
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Tuple, Union, Literal
+
+
+@dataclass
+class FunctionContract:
+    id: str
+    name: str
+    qualified_name: str
+    signature_hash: str
+    docstring: Optional[str]
+    docstring_raw_hash: Optional[str]
+    contract_hash: Optional[str]
+    lineno: int
+    col_offset: int
+    scope: Optional[Literal["public", "internal"]] = None
+    strictness: Optional[Literal["strict", "standard", "light"]] = None
+    is_method: bool = False
+    parent_class: Optional[str] = None
+
+
+class PythonAdapter:
+    def parse_file(self, file_path: str) -> List[FunctionContract]:
+        """解析并提取指定 Python 文件中的函数/方法契约元数据。
+
+        功能:
+          - 读取并解析 Python 源文件的 AST。
+          - 提取所有顶层函数与类方法的名称、签名哈希与 Docstring 双哈希。
+          - 识别 Docstring 中的 `@harbor.*` 标签与契约区 (Args/Returns/Raises) 文本。
+
+        使用场景:
+          - Harbor 索引构建（Phase 1）基座；为 `build-index` 提供 L3 解析能力。
+          - `harbor sync l3 --check` 的前置分析。
+
+        依赖:
+          - Python 标准库 `ast`、`hashlib`。
+
+        @harbor.scope: public
+        @harbor.l3_strictness: strict
+        @harbor.idempotency: read-only
+
+        Args:
+          file_path (str): 需要解析的 Python 源文件路径。
+
+        Returns:
+          List[FunctionContract]: 函数/方法契约元数据列表。
+
+        Raises:
+          IOError: 当文件读取失败。
+          SyntaxError: 当源文件存在语法错误，无法解析为 AST。
+        """
+        p = Path(file_path)
+        if not p.exists():
+            raise IOError(f"file not found: {file_path}")
+        try:
+            source = p.read_text(encoding="utf-8")
+        except Exception as e:
+            raise IOError(str(e))
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            raise
+        module_qual = self._module_qual_from_path(p)
+        return self._extract_functions(tree, module_qual)
+
+    def _extract_functions(self, tree: ast.AST, module_qual: str) -> List[FunctionContract]:
+        """提取顶层函数与类方法的契约元数据。
+
+        @harbor.scope: internal
+        @harbor.l3_strictness: standard
+
+        Args:
+          tree (ast.AST): 已解析的抽象语法树。
+          module_qual (str): 模块的点分限定名。
+
+        Returns:
+          List[FunctionContract]: 契约元数据列表。
+        """
+        items: List[FunctionContract] = []
+        for node in getattr(tree, "body", []):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                items.append(self._contract_from_function(node, module_qual, None))
+            elif isinstance(node, ast.ClassDef):
+                for sub in node.body:
+                    if isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        items.append(self._contract_from_function(sub, module_qual, node.name))
+        return items
+
+    def _contract_from_function(
+        self,
+        fn: Union[ast.FunctionDef, ast.AsyncFunctionDef],
+        module_qual: str,
+        parent_class: Optional[str],
+    ) -> FunctionContract:
+        """根据函数节点生成契约元数据。
+
+        @harbor.scope: internal
+        @harbor.l3_strictness: standard
+
+        Args:
+          fn: 函数或方法的 AST 节点。
+          module_qual: 模块限定名。
+          parent_class: 若为方法，则为父类名，否则为 None。
+
+        Returns:
+          FunctionContract: 契约元数据。
+        """
+        name = fn.name
+        is_method = parent_class is not None
+        qualified_name = (
+            f"{module_qual}.{parent_class}.{name}" if is_method else f"{module_qual}.{name}"
+        )
+        doc = ast.get_docstring(fn)
+        raw_hash, contract_hash = self._docstring_hashes(doc)
+        scope, strictness = self._parse_tags(doc) if doc else (None, None)
+        return FunctionContract(
+            id=qualified_name,
+            name=name,
+            qualified_name=qualified_name,
+            signature_hash=self._signature_hash(fn),
+            docstring=doc,
+            docstring_raw_hash=raw_hash,
+            contract_hash=contract_hash,
+            lineno=getattr(fn, "lineno", 0),
+            col_offset=getattr(fn, "col_offset", 0),
+            scope=scope,
+            strictness=strictness,
+            is_method=is_method,
+            parent_class=parent_class,
+        )
+
+    def _signature_hash(self, fn: Union[ast.FunctionDef, ast.AsyncFunctionDef]) -> str:
+        """计算函数签名的稳定哈希。
+
+        @harbor.scope: internal
+        @harbor.l3_strictness: standard
+
+        Args:
+          fn: 函数或方法的 AST 节点。
+
+        Returns:
+          str: 签名的 sha256 哈希。
+        """
+        a = fn.args
+        parts = [
+            "posonly:" + ",".join([x.arg for x in getattr(a, "posonlyargs", [])]),
+            "args:" + ",".join([x.arg for x in a.args]),
+            "vararg:" + (a.vararg.arg if a.vararg else ""),
+            "kwonly:" + ",".join([x.arg for x in a.kwonlyargs]),
+            "kwarg:" + (a.kwarg.arg if a.kwarg else ""),
+            "defaults:" + str(len(a.defaults)) + "|" + str(len(a.kw_defaults)),
+        ]
+        norm = "|".join(parts)
+        return hashlib.sha256(norm.encode("utf-8")).hexdigest()
+
+    def _docstring_hashes(self, doc: Optional[str]) -> Tuple[Optional[str], Optional[str]]:
+        """计算 Docstring 的 raw/contract 双哈希。
+
+        @harbor.scope: internal
+        @harbor.l3_strictness: standard
+
+        Args:
+          doc: Docstring 文本或 None。
+
+        Returns:
+          Tuple[str | None, str | None]: (raw_hash, contract_hash)。
+        """
+        if not doc:
+            return None, None
+        text = doc.replace("\r\n", "\n").strip()
+        raw = hashlib.sha256(text.encode("utf-8")).hexdigest()
+        contract_text = self._contract_area(text)
+        if not contract_text:
+            return raw, raw
+        contract = hashlib.sha256(contract_text.encode("utf-8")).hexdigest()
+        return raw, contract
+
+    def _contract_area(self, doc: str) -> str:
+        """提取契约区文本（Args/Returns/Raises + @harbor.* tags）。找不到则返回空串。
+
+        @harbor.scope: internal
+        @harbor.l3_strictness: standard
+
+        Args:
+          doc: 完整 Docstring。
+
+        Returns:
+          str: 契约区文本。
+        """
+        lines = doc.split("\n")
+        captured: List[str] = []
+        capturing = False
+        target_headers = {"Args:", "Returns:", "Raises:"}
+        for i, line in enumerate(lines):
+            s = line.strip()
+            if s.startswith("@harbor."):
+                captured.append(s)
+                continue
+            if s in target_headers:
+                capturing = True
+                captured.append(s)
+                continue
+            if capturing:
+                if s == "":
+                    capturing = False
+                    continue
+                if line.startswith(" ") or line.startswith("\t"):
+                    captured.append(line.rstrip())
+                else:
+                    capturing = False
+        return "\n".join([x for x in captured if x.strip()]).strip()
+
+    def _parse_tags(
+        self, doc: str
+    ) -> Tuple[Optional[Literal["public", "internal"]], Optional[Literal["strict", "standard", "light"]]]:
+        """从 Docstring 提取 @harbor.* 标签。
+
+        @harbor.scope: internal
+        @harbor.l3_strictness: standard
+
+        Args:
+          doc: 完整 Docstring。
+
+        Returns:
+          Tuple[scope, strictness]: 若未找到则返回 (None, None)。
+        """
+        scope: Optional[Literal["public", "internal"]] = None
+        strictness: Optional[Literal["strict", "standard", "light"]] = None
+        for line in doc.split("\n"):
+            s = line.strip()
+            if s.startswith("@harbor.scope:"):
+                val = s.split(":", 1)[1].strip()
+                if val in ("public", "internal"):
+                    scope = val  # type: ignore
+            elif s.startswith("@harbor.l3_strictness:"):
+                val = s.split(":", 1)[1].strip()
+                if val in ("strict", "standard", "light"):
+                    strictness = val  # type: ignore
+        return scope, strictness
+
+    def _module_qual_from_path(self, p: Path) -> str:
+        """根据文件路径生成模块限定名（点分格式）。
+
+        @harbor.scope: internal
+        @harbor.l3_strictness: standard
+
+        Args:
+          p: 源文件路径。
+
+        Returns:
+          str: 点分模块名，如 `harbor.adapters.python.parser`。
+        """
+        root = Path.cwd().resolve()
+        try:
+            rel = p.resolve().relative_to(root)
+        except Exception:
+            rel = p.name if p.is_file() else str(p)
+            rel = Path(rel)
+        parts = list(rel.parts)
+        if parts and parts[-1].endswith(".py"):
+            parts[-1] = parts[-1][:-3]
+        return ".".join([x for x in parts if x and x not in (".", "..")])
+

harbor_spec-1.0.0/harbor/cli/__init__.py

@@ -0,0 +1,2 @@
+"""CLI package."""
+