monoco-toolkit 0.1.0__py3-none-any.whl → 0.2.5__py3-none-any.whl

monoco/features/i18n/commands.py

@@ -4,7 +4,9 @@ from rich.console import Console
 from rich.table import Table
 from rich.panel import Panel
 
-from monoco.core.config import get_config
+from typing import Optional, Annotated
+from monoco.core.config import get_config, find_monoco_root
+from monoco.core.output import AgentOutput, OutputManager
 from . import core
 
 app = typer.Typer(help="Management tools for Documentation Internationalization (i18n).")
@@ -14,6 +16,9 @@ console = Console()
 def scan(
     root: str = typer.Option(None, "--root", help="Target root directory to scan. Defaults to the project root."),
     limit: int = typer.Option(10, "--limit", help="Maximum number of missing files to display. Use 0 for unlimited."),
+    check_issues: bool = typer.Option(False, "--check-issues", help="Include Issues directory in the scan."),
+    check_source_lang: bool = typer.Option(False, "--check-source-lang", help="Verify if source files content matches source language (heuristic)."),
+    json: AgentOutput = False,
 ):
     """
     Scan the project for internationalization (i18n) status.
@@ -25,36 +30,92 @@ def scan(
 
     Returns a report of files missing translations in the checking target languages.
     """
-    config = get_config()
-    target_root = Path(root).resolve() if root else Path(config.paths.root)
+    if root:
+        target_root = Path(root).resolve()
+    else:
+        target_root = find_monoco_root(Path.cwd())
+
+    # Load config with correct root
+    config = get_config(project_root=str(target_root))
     target_langs = config.i18n.target_langs
+    source_lang = config.i18n.source_lang
     
-    console.print(f"Scanning i18n coverage in [bold cyan]{target_root}[/bold cyan]...")
-    console.print(f"Target Languages: [bold yellow]{', '.join(target_langs)}[/bold yellow] (Source: {config.i18n.source_lang})")
+    if not OutputManager.is_agent_mode():
+        console.print(f"Scanning i18n coverage in [bold cyan]{target_root}[/bold cyan]...")
+        console.print(f"Target Languages: [bold yellow]{', '.join(target_langs)}[/bold yellow] (Source: {source_lang})")
     
-    all_files = core.discover_markdown_files(target_root)
+    all_files = core.discover_markdown_files(target_root, include_issues=check_issues)
     
     source_files = [f for f in all_files if not core.is_translation_file(f, target_langs)]
     
     # Store missing results: { file_path: [missing_langs] }
     missing_map = {}
+    # Store lang mismatch results: [file_path]
+    lang_mismatch_files = []
+
     total_checks = len(source_files) * len(target_langs)
     found_count = 0
     
     for f in source_files:
-        missing_langs = core.check_translation_exists(f, target_root, target_langs)
+        # Check translation existence
+        missing_langs = core.check_translation_exists(f, target_root, target_langs, source_lang)
         if missing_langs:
             missing_map[f] = missing_langs
             found_count += (len(target_langs) - len(missing_langs))
         else:
             found_count += len(target_langs)
             
+        # Check source content language if enabled
+        if check_source_lang:
+            if not core.is_content_source_language(f, source_lang):
+                # Try to detect actual language for better error message
+                try:
+                    content = f.read_text(encoding="utf-8")
+                    detected = core.detect_language(content)
+                except:
+                    detected = "unknown"
+                lang_mismatch_files.append((f, detected))
+            
     # Reporting
     coverage = (found_count / total_checks * 100) if total_checks > 0 else 100
     
     # Sort missing_map by file path for stable output
     sorted_missing = sorted(missing_map.items(), key=lambda x: str(x[0]))
-    
+
+    if OutputManager.is_agent_mode():
+        # JSON Output
+        report = {
+            "root": str(target_root),
+            "source_lang": source_lang,
+            "target_langs": target_langs,
+            "stats": {
+                "total_source_files": len(source_files),
+                "total_checks": total_checks,
+                "found_translations": found_count,
+                "coverage_percent": round(coverage, 2),
+                "missing_files_count": len(sorted_missing),
+                "mismatch_files_count": len(lang_mismatch_files)
+            },
+            "missing_files": [
+                {
+                    "file": str(f.relative_to(target_root)),
+                    "missing_langs": langs,
+                    "expected_paths": [
+                        str(core.get_target_translation_path(f, target_root, l, source_lang).relative_to(target_root))
+                        for l in langs
+                    ]
+                }
+                for f, langs in sorted_missing
+            ],
+            "language_mismatches": [
+                {"file": str(f.relative_to(target_root)), "detected": detected}
+                for f, detected in lang_mismatch_files
+            ]
+        }
+        OutputManager.print(report)
+        return
+
+    # Human Output
     # Apply limit
     total_missing_files = len(sorted_missing)
     display_limit = limit if limit > 0 else total_missing_files
@@ -77,7 +138,7 @@ def scan(
         rel_path = f.relative_to(target_root)
         expected_paths = []
         for lang in langs:
-            target = core.get_target_translation_path(f, target_root, lang)
+            target = core.get_target_translation_path(f, target_root, lang, source_lang)
             expected_paths.append(str(target.relative_to(target_root)))
             
         table.add_row(
@@ -88,6 +149,21 @@ def scan(
         
     console.print(table)
     
+    # Show Language Mismatch Warnings
+    if lang_mismatch_files:
+        console.print("\n")
+        mismatch_table = Table(title=f"Source Language Mismatch (Expected: {source_lang})", box=None)
+        mismatch_table.add_column("File", style="yellow")
+        mismatch_table.add_column("Detected", style="red")
+        
+        limit_mismatch = 10
+        for f, detected in lang_mismatch_files[:limit_mismatch]:
+             mismatch_table.add_row(str(f.relative_to(target_root)), detected)
+             
+        console.print(mismatch_table)
+        if len(lang_mismatch_files) > limit_mismatch:
+             console.print(f"[dim]... and {len(lang_mismatch_files) - limit_mismatch} more.[/dim]")
+
     # Show hint if output was truncated
     if display_limit < total_missing_files:
         console.print(f"\n[dim]💡 Tip: Use [bold]--limit 0[/bold] to show all {total_missing_files} missing files.[/dim]\n")
@@ -111,11 +187,14 @@ def scan(
     if total_missing_files > 0:
         summary_lines.append(f"  - Partial Missing: {partial_missing}")
         summary_lines.append(f"  - Complete Missing: {complete_missing}")
+        
+    if lang_mismatch_files:
+        summary_lines.append(f"Language Mismatches: {len(lang_mismatch_files)}")
     
     summary_lines.append(f"Coverage: [{status_color}]{coverage:.1f}%[/{status_color}]")
     
     summary = "\n".join(summary_lines)
     console.print(Panel(summary, title="I18N STATUS", expand=False))
 
-    if missing_map:
+    if missing_map or lang_mismatch_files:
         raise typer.Exit(code=1)

monoco/features/i18n/core.py

@@ -1,9 +1,17 @@
 import os
 import fnmatch
 from pathlib import Path
-from typing import List, Set, Dict, Any
+from typing import List, Set, Dict, Any, Optional
+import re
 
-DEFAULT_EXCLUDES = [".git", ".reference", "dist", "build", "node_modules", "__pycache__", ".agent", ".mono", ".venv", "venv", "ENV", "Issues"]
+DEFAULT_EXCLUDES = [
+    ".git", ".reference", "dist", "build", "node_modules", "__pycache__", 
+    ".agent", ".mono", ".venv", "venv", "ENV",
+    # Agent Integration Directories
+    ".claude", ".gemini", ".qwen", ".openai", ".cursor", ".vscode", ".idea", ".fleet",
+    # System Prompts & Agent Configs
+    "AGENTS.md", "CLAUDE.md", "GEMINI.md", "QWEN.md", "SKILL.md"
+]
 
 def load_gitignore_patterns(root: Path) -> List[str]:
     """Load patterns from .gitignore file."""
@@ -25,13 +33,15 @@ def load_gitignore_patterns(root: Path) -> List[str]:
         pass
     return patterns
 
-def is_excluded(path: Path, root: Path, patterns: List[str]) -> bool:
+def is_excluded(path: Path, root: Path, patterns: List[str], excludes: Optional[List[str]] = None) -> bool:
     """Check if a path should be excluded based on patterns and defaults."""
     rel_path = str(path.relative_to(root))
     
+    final_excludes = excludes if excludes is not None else DEFAULT_EXCLUDES
+
     # 1. Check default excludes (exact match for any path component, case-insensitive)
     for part in path.parts:
-        if part.lower() in [e.lower() for e in DEFAULT_EXCLUDES]:
+        if part.lower() in [e.lower() for e in final_excludes]:
             return True
             
     # 2. Check gitignore patterns
@@ -55,15 +65,19 @@ def is_excluded(path: Path, root: Path, patterns: List[str]) -> bool:
 
     return False
 
-def discover_markdown_files(root: Path) -> List[Path]:
+def discover_markdown_files(root: Path, include_issues: bool = False) -> List[Path]:
     """Recursively find markdown files while respecting exclusion rules."""
     patterns = load_gitignore_patterns(root)
     all_md_files = []
     
+    excludes = list(DEFAULT_EXCLUDES)
+    if not include_issues:
+        excludes.append("Issues")
+
     # We walk to ensure we can skip directories early if needed, 
     # but for now rglob + filter is simpler.
     for p in root.rglob("*.md"):
-        if p.is_file() and not is_excluded(p, root, patterns):
+        if p.is_file() and not is_excluded(p, root, patterns, excludes=excludes):
             all_md_files.append(p)
             
     return sorted(all_md_files)
@@ -77,6 +91,12 @@ def is_translation_file(path: Path, target_langs: List[str]) -> bool:
     for lang in normalized_langs:
         if stem_upper.endswith(f"_{lang.upper()}"):
             return True
+
+    # Generic Suffix Check: Detect any _XX suffix where XX is 2-3 letters
+    # This prevents files like README_ZH.md from being treated as source files
+    # even if 'zh' is not in target_langs (e.g. when scanning for 'en' gaps).
+    if re.search(r'_[A-Z]{2,3}$', stem_upper):
+        return True
             
     # Subdir check (case-insensitive)
     path_parts_lower = [p.lower() for p in path.parts]
@@ -86,29 +106,32 @@ def is_translation_file(path: Path, target_langs: List[str]) -> bool:
             
     return False
 
-def get_target_translation_path(path: Path, root: Path, lang: str) -> Path:
+def get_target_translation_path(path: Path, root: Path, lang: str, source_lang: str = "en") -> Path:
     """Calculate the expected translation path for a specific language."""
     lang = lang.lower()
     
     # Parallel Directory Mode: docs/en/... -> docs/zh/...
-    # We assume 'en' is the source language for now.
     path_parts = list(path.parts)
-    # Search for 'en' component to replace
-    # We iterate from root relative parts to be safe, but simple replacement of the first 'en' 
-    # component (if not part of filename) is a good heuristic for docs structure.
+    # Search for source_lang component to replace
     for i, part in enumerate(path_parts):
-        if part.lower() == 'en':
+        if part.lower() == source_lang.lower():
             path_parts[i] = lang
             return Path(*path_parts)
 
-    # Suffix Mode: for root files
+    # Suffix Mode:
+    # If stem ends with _{SOURCE_LANG}, strip it.
+    stem = path.stem
+    source_suffix = f"_{source_lang.upper()}"
+    if stem.upper().endswith(source_suffix):
+         stem = stem[:-len(source_suffix)]
+         
     if path.parent == root:
-        return path.with_name(f"{path.stem}_{lang.upper()}{path.suffix}")
+        return path.with_name(f"{stem}_{lang.upper()}{path.suffix}")
     
     # Subdir Mode: for documentation directories (fallback)
     return path.parent / lang / path.name
 
-def check_translation_exists(path: Path, root: Path, target_langs: List[str]) -> List[str]:
+def check_translation_exists(path: Path, root: Path, target_langs: List[str], source_lang: str = "en") -> List[str]:
     """
     Verify which target languages have translations.
     Returns a list of missing language codes.
@@ -116,12 +139,85 @@ def check_translation_exists(path: Path, root: Path, target_langs: List[str]) ->
     if is_translation_file(path, target_langs):
         return [] # Already a translation, skip
     
+    # Special handling for standard files: always treat as EN source
+    effective_source_lang = source_lang
+    if path.name.upper() in ["README.MD", "CHANGELOG.MD", "CODE_OF_CONDUCT.MD", "CONTRIBUTING.MD", "LICENSE.MD", "SECURITY.MD"]:
+        effective_source_lang = "en"
+    
     missing = []
     for lang in target_langs:
-        target = get_target_translation_path(path, root, lang)
+        # Skip if target language matches the effective source language
+        if lang.lower() == effective_source_lang.lower():
+            continue
+
+        target = get_target_translation_path(path, root, lang, effective_source_lang)
         if not target.exists():
             missing.append(lang)
     return missing
+
+def detect_language(content: str) -> str:
+    """
+    Detect the language of the content using simple heuristics.
+    Returns: 'zh', 'en', or 'unknown'
+    """
+    if not content:
+        return 'unknown'
+        
+    # Strip YAML Frontmatter if present
+    # Matches --- at start, followed by anything, followed by ---
+    frontmatter_pattern = re.compile(r'^---\n.*?\n---\n', re.DOTALL)
+    content = frontmatter_pattern.sub('', content)
+    
+    if not content.strip():
+        return 'unknown'
+
+    # 1. Check for CJK characters (Chinese/Japanese/Korean)
+    # Range: \u4e00-\u9fff (Common CJK Unified Ideographs)
+    # Heuristic: If CJK count > threshold, it's likely Asian (we assume ZH for now in this context)
+    total_chars = len(content)
+    cjk_count = sum(1 for c in content if '\u4e00' <= c <= '\u9fff')
+    
+    # If > 5% chars are CJK, highly likely to be Chinese document
+    if total_chars > 0 and cjk_count / total_chars > 0.05:
+        return 'zh'
+        
+    # 2. Check for English
+    # Heuristic: High ASCII ratio and low CJK
+    non_ascii = sum(1 for c in content if ord(c) > 127)
+    
+    # If < 10% non-ASCII, likely English (or code)
+    if total_chars > 0 and non_ascii / total_chars < 0.1:
+        return 'en'
+        
+    return 'unknown'
+
+def is_content_source_language(path: Path, source_lang: str = "en") -> bool:
+    """
+    Check if file content appears to be in the source language.
+    """
+    try:
+        # Special handling for README/CHANGELOG
+        if path.name.upper() in ["README.MD", "CHANGELOG.MD"]:
+            source_lang = "en"
+
+        content = path.read_text(encoding="utf-8")
+        detected = detect_language(content)
+        
+        # 'unknown' is leniently accepted as valid to avoid false positives on code-heavy files
+        if detected == 'unknown':
+            return True
+            
+        # Normalize source_lang
+        expected = source_lang.lower()
+        if expected == 'zh' or expected == 'cn':
+            return detected == 'zh'
+        elif expected == 'en':
+            return detected == 'en'
+            
+        # For other languages, we don't have detectors yet
+        return True
+    except Exception:
+        return True # Assume valid on error
 # ... (Existing code) ...
 
 SKILL_CONTENT = """---
@@ -154,25 +250,15 @@ i18n is a "first-class citizen" in Monoco.
 - Run `monoco i18n scan` to verify coverage.
 """
 
-PROMPT_CONTENT = """### Documentation I18n
-Manage internationalization.
-- **Scan**: `monoco i18n scan` (Check for missing translations)
-- **Structure**:
-  - Root files: `FILE_ZH.md`
-  - Subdirs: `folder/zh/file.md`"""
 
 def init(root: Path):
     """Initialize I18n environment (No-op currently as it relies on config)."""
     # In future, could generate i18n config section if missing.
     pass
 
-def get_resources() -> Dict[str, Any]:
     return {
         "skills": {
             "i18n": SKILL_CONTENT
         },
-        "prompts": {
-            "i18n": PROMPT_CONTENT
-        }
+        "prompts": {} # Handled by adapter via resource files
     }
-

monoco/features/i18n/resources/en/AGENTS.md

@@ -0,0 +1,8 @@
+### Documentation I18n
+
+Manage internationalization.
+
+- **Scan**: `monoco i18n scan` (Check for missing translations)
+- **Structure**:
+  - Root files: `FILE_ZH.md`
+  - Subdirs: `folder/zh/file.md`

monoco/features/i18n/resources/en/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: monoco-i18n
+description: Internationalization quality control for documentation. Ensures multi-language documentation stays synchronized.
+---
+
+# Documentation I18n
+
+Manage internationalization for Monoco project documentation.
+
+## Overview
+
+The I18n feature provides:
+
+- **Automatic scanning** for missing translations
+- **Standardized structure** for multi-language documentation
+- **Quality control** to maintain documentation parity
+
+## Key Commands
+
+### Scan for Missing Translations
+
+```bash
+monoco i18n scan
+```
+
+Scans the project for markdown files and reports missing translations.
+
+**Output**:
+
+- Lists source files without corresponding translations
+- Shows which target languages are missing
+- Respects `.gitignore` and default exclusions
+
+## Configuration
+
+I18n settings are configured in `.monoco/config.yaml`:
+
+```yaml
+i18n:
+  source_lang: en # Source language code
+  target_langs: # Target language codes
+    - zh
+    - ja
+```
+
+## Documentation Structure
+
+### Root Files (Suffix Pattern)
+
+For files in the project root:
+
+- Source: `README.md`
+- Chinese: `README_ZH.md`
+- Japanese: `README_JA.md`
+
+### Subdirectory Files (Directory Pattern)
+
+For files in `docs/` or other directories:
+
+```
+docs/
+├── en/
+│   ├── guide.md
+│   └── api.md
+├── zh/
+│   ├── guide.md
+│   └── api.md
+└── ja/
+    ├── guide.md
+    └── api.md
+```
+
+## Exclusion Rules
+
+The following are automatically excluded from i18n scanning:
+
+- `.gitignore` patterns (respected automatically)
+- `.references/` directory
+- Build artifacts (`dist/`, `build/`, `node_modules/`)
+- `Issues/` directory
+
+## Best Practices
+
+1. **Create English First**: Write documentation in the source language first
+2. **Follow Naming Convention**: Use the appropriate pattern (suffix or directory)
+3. **Run Scan Regularly**: Use `monoco i18n scan` to verify coverage
+4. **Commit All Languages**: Keep translations in version control
+
+## Workflow
+
+1. Write documentation in source language (e.g., English)
+2. Create translation files following the naming convention
+3. Run `monoco i18n scan` to verify all translations exist
+4. Fix any missing translations reported by the scan

monoco/features/i18n/resources/zh/AGENTS.md

@@ -0,0 +1,8 @@
+### 文档国际化
+
+管理国际化。
+
+- **扫描**: `monoco i18n scan` (检查缺失的翻译)
+- **结构**:
+  - 根文件: `FILE_ZH.md`
+  - 子目录: `folder/zh/file.md`

monoco/features/i18n/resources/zh/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: monoco-i18n
+description: 文档国际化质量控制。确保多语言文档保持同步。
+---
+
+# 文档国际化
+
+管理 Monoco 项目文档的国际化。
+
+## 概述
+
+I18n 功能提供：
+
+- **自动扫描**缺失的翻译
+- **标准化结构**用于多语言文档
+- **质量控制**以维护文档一致性
+
+## 核心命令
+
+### 扫描缺失的翻译
+
+```bash
+monoco i18n scan
+```
+
+扫描项目中的 markdown 文件并报告缺失的翻译。
+
+**输出**:
+
+- 列出没有对应翻译的源文件
+- 显示缺少哪些目标语言
+- 遵循 `.gitignore` 和默认排除规则
+
+## 配置
+
+I18n 设置在 `.monoco/config.yaml` 中配置：
+
+```yaml
+i18n:
+  source_lang: en # 源语言代码
+  target_langs: # 目标语言代码
+    - zh
+    - ja
+```
+
+## 文档结构
+
+### 根文件（后缀模式）
+
+对于项目根目录中的文件：
+
+- 源文件: `README.md`
+- 中文: `README_ZH.md`
+- 日文: `README_JA.md`
+
+### 子目录文件（目录模式）
+
+对于 `docs/` 或其他目录中的文件：
+
+```
+docs/
+├── en/
+│   ├── guide.md
+│   └── api.md
+├── zh/
+│   ├── guide.md
+│   └── api.md
+└── ja/
+    ├── guide.md
+    └── api.md
+```
+
+## 排除规则
+
+以下内容会自动从 i18n 扫描中排除：
+
+- `.gitignore` 模式（自动遵循）
+- `.references/` 目录
+- 构建产物（`dist/`, `build/`, `node_modules/`）
+- `Issues/` 目录
+
+## 最佳实践
+
+1. **先创建英文版**: 首先用源语言编写文档
+2. **遵循命名约定**: 使用适当的模式（后缀或目录）
+3. **定期运行扫描**: 使用 `monoco i18n scan` 验证覆盖率
+4. **提交所有语言**: 将翻译保存在版本控制中
+
+## 工作流程
+
+1. 用源语言（如英语）编写文档
+2. 按照命名约定创建翻译文件
+3. 运行 `monoco i18n scan` 验证所有翻译是否存在
+4. 修复扫描报告的任何缺失翻译

monoco/features/issue/adapter.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+from typing import Dict
+from monoco.core.feature import MonocoFeature, IntegrationData
+from monoco.features.issue import core
+
+class IssueFeature(MonocoFeature):
+    @property
+    def name(self) -> str:
+        return "issue"
+
+    def initialize(self, root: Path, config: Dict) -> None:
+        issues_path = root / config.get("paths", {}).get("issues", "Issues")
+        core.init(issues_path)
+
+    def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        # Determine language from config, default to 'en'
+        lang = config.get("i18n", {}).get("source_lang", "en")
+        
+        # Current file is in monoco/features/issue/adapter.py
+        # Resource path: monoco/features/issue/resources/{lang}/AGENTS.md
+        base_dir = Path(__file__).parent / "resources"
+        
+        # Try specific language, fallback to 'en'
+        prompt_file = base_dir / lang / "AGENTS.md"
+        if not prompt_file.exists():
+            prompt_file = base_dir / "en" / "AGENTS.md"
+            
+        content = ""
+        if prompt_file.exists():
+            content = prompt_file.read_text(encoding="utf-8").strip()
+            
+        return IntegrationData(
+            system_prompts={"Issue Management": content}
+        )