自動生成檔案管理完整指南：從識別到治理的最佳實踐

# 自動生成檔案識別與管理工具
# 提供掃描、標記、驗證與報告功能

import os
import re
import json
import hashlib
from pathlib import Path
from typing import List, Dict, Set, Optional
from dataclasses import dataclass, asdict
from datetime import datetime
import fnmatch

@dataclass
class GeneratedFileInfo:
    """
    自動生成檔案的資訊結構
    """
    path: str  # 檔案路徑
    generator: str  # 生成工具名稱
    source_file: Optional[str]  # 來源檔案（如果可識別）
    last_modified: str  # 最後修改時間
    file_hash: str  # 檔案內容雜湊值
    warning_found: bool  # 是否包含警告標記
    is_in_gitignore: bool  # 是否在.gitignore中

class AutogeneratedFileManager:
    """
    自動生成檔案管理器
    提供識別、追蹤與驗證功能
    """
    
    # 常見的自動生成檔案警告標記模式
    WARNING_PATTERNS = [
        r'WARNING.*AUTOGENERATED.*FILE',
        r'DO\s+NOT\s+EDIT',
        r'AUTO-?GENERATED',
        r'GENERATED\s+BY',
        r'@generated',
        r'Code generated by',
        r'This file is automatically generated',
        r'自動生成',
        r'請勿手動編輯',
        r'由.*自動產生',
    ]
    
    # 常見的生成工具識別模式
    GENERATOR_PATTERNS = {
        'protobuf': r'Generated by the protocol buffer compiler',
        'swagger-codegen': r'Swagger Codegen',
        'openapi-generator': r'OpenAPI Generator',
        'prisma': r'Generated by Prisma',
        'typeorm': r'Auto-generated by TypeORM',
        'entity-framework': r'Auto-generated by Entity Framework',
        'graphql-codegen': r'Generated by graphql-code-generator',
        'webpack': r'webpack',
        'vite': r'vite',
        'typescript': r'TypeScript',
        'babel': r'Babel',
        'maven': r'Maven',
        'gradle': r'Gradle',
    }
    
    # 常見的生成檔案路徑模式
    GENERATED_PATH_PATTERNS = [
        '*/build/*',
        '*/dist/*',
        '*/target/*',
        '*/out/*',
        '*/bin/*',
        '*.generated.*',
        '*_generated.*',
        '*.g.*',
        '*pb.py',  # Protocol Buffers
        '*pb.go',
        '*.pb.h',
        '*.pb.cc',
        '*_pb2.py',
        'node_modules/*',
        '__pycache__/*',
        '*.pyc',
        '*.class',
        '*.o',
        '*.so',
        '*.dll',
    ]
    
    def __init__(self, root_dir: str):
        """
        初始化管理器
        
        參數:
            root_dir: 專案根目錄路徑
        """
        self.root_dir = Path(root_dir)
        self.generated_files: List[GeneratedFileInfo] = []
        self.gitignore_patterns: Set[str] = set()
        self._load_gitignore()
        
        print(f"自動生成檔案管理器已初始化")
        print(f"專案根目錄: {self.root_dir}")
    
    def _load_gitignore(self):
        """
        載入.gitignore檔案內容
        """
        gitignore_path = self.root_dir / '.gitignore'
        
        if gitignore_path.exists():
            with open(gitignore_path, 'r', encoding='utf-8') as f:
                for line in f:
                    line = line.strip()
                    # 忽略註解與空行
                    if line and not line.startswith('#'):
                        self.gitignore_patterns.add(line)
            
            print(f"已載入 {len(self.gitignore_patterns)} 個.gitignore規則")
    
    def _is_ignored_by_gitignore(self, file_path: Path) -> bool:
        """
        檢查檔案是否被.gitignore規則忽略
        
        參數:
            file_path: 檔案路徑
            
        回傳:
            是否被忽略
        """
        relative_path = str(file_path.relative_to(self.root_dir))
        
        for pattern in self.gitignore_patterns:
            # 處理目錄模式
            if pattern.endswith('/'):
                if relative_path.startswith(pattern[:-1]):
                    return True
            # 處理萬用字元模式
            elif fnmatch.fnmatch(relative_path, pattern):
                return True
            # 處理全域模式
            elif pattern.startswith('**/'):
                if fnmatch.fnmatch(relative_path, pattern[3:]):
                    return True
        
        return False
    
    def _matches_path_pattern(self, file_path: Path) -> bool:
        """
        檢查檔案路徑是否符合生成檔案模式
        
        參數:
            file_path: 檔案路徑
            
        回傳:
            是否符合模式
        """
        relative_path = str(file_path.relative_to(self.root_dir))
        
        for pattern in self.GENERATED_PATH_PATTERNS:
            if fnmatch.fnmatch(relative_path, pattern):
                return True
        
        return False
    
    def _detect_generator(self, content: str) -> Optional[str]:
        """
        從檔案內容檢測生成工具
        
        參數:
            content: 檔案內容
            
        回傳:
            生成工具名稱，若未檢測到則回傳None
        """
        for generator, pattern in self.GENERATOR_PATTERNS.items():
            if re.search(pattern, content, re.IGNORECASE):
                return generator
        
        return None
    
    def _has_warning_marker(self, content: str) -> bool:
        """
        檢查檔案內容是否包含警告標記
        
        參數:
            content: 檔案內容
            
        回傳:
            是否包含警告標記
        """
        for pattern in self.WARNING_PATTERNS:
            if re.search(pattern, content, re.IGNORECASE):
                return True
        
        return False
    
    def _calculate_file_hash(self, file_path: Path) -> str:
        """
        計算檔案內容的SHA-256雜湊值
        
        參數:
            file_path: 檔案路徑
            
        回傳:
            雜湊值（十六進制字串）
        """
        sha256_hash = hashlib.sha256()
        
        with open(file_path, "rb") as f:
            # 分塊讀取避免記憶體問題
            for byte_block in iter(lambda: f.read(4096), b""):
                sha256_hash.update(byte_block)
        
        return sha256_hash.hexdigest()
    
    def scan_directory(self, 
                      extensions: Optional[List[str]] = None,
                      exclude_dirs: Optional[List[str]] = None) -> int:
        """
        掃描目錄識別自動生成檔案
        
        參數:
            extensions: 要掃描的檔案副檔名列表（如['.py', '.java']）
                       若為None則掃描所有文字檔案
            exclude_dirs: 要排除的目錄名稱列表
            
        回傳:
            發現的自動生成檔案數量
        """
        print(f"\n開始掃描目錄: {self.root_dir}")
        
        if exclude_dirs is None:
            exclude_dirs = ['.git', 'node_modules', '__pycache__', 
                          'venv', '.venv', '.tox']
        
        self.generated_files = []
        scanned_count = 0
        
        for file_path in self.root_dir.rglob('*'):
            # 跳過目錄
            if file_path.is_dir():
                continue
            
            # 跳過排除的目錄
            if any(excluded in file_path.parts for excluded in exclude_dirs):
                continue
            
            # 檢查副檔名過濾
            if extensions and file_path.suffix not in extensions:
                continue
            
            # 檢查路徑模式
            matches_path = self._matches_path_pattern(file_path)
            
            try:
                # 讀取檔案內容（僅文字檔案）
                with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
                    content = f.read(10000)  # 只讀前10KB檢查標記
                
                scanned_count += 1
                
                # 檢查警告標記
                has_warning = self._has_warning_marker(content)
                
                # 檢測生成工具
                generator = self._detect_generator(content)
                
                # 如果符合任一條件則標記為自動生成檔案
                if has_warning or generator or matches_path:
                    # 計算完整檔案雜湊
                    file_hash = self._calculate_file_hash(file_path)
                    
                    # 取得檔案修改時間
                    mtime = datetime.fromtimestamp(
                        file_path.stat().st_mtime
                    ).isoformat()
                    
                    # 檢查是否在.gitignore中
                    is_ignored = self._is_ignored_by_gitignore(file_path)
                    
                    info = GeneratedFileInfo(
                        path=str(file_path.relative_to(self.root_dir)),
                        generator=generator or "unknown",
                        source_file=None,  # 目前無法自動檢測
                        last_modified=mtime,
                        file_hash=file_hash,
                        warning_found=has_warning,
                        is_in_gitignore=is_ignored
                    )
                    
                    self.generated_files.append(info)
            
            except (UnicodeDecodeError, PermissionError):
                # 無法讀取的檔案（二進位檔案或權限問題）
                continue
        
        print(f"掃描完成: 檢查了 {scanned_count} 個檔案")
        print(f"發現 {len(self.generated_files)} 個自動生成檔案")
        
        return len(self.generated_files)
    
    def generate_report(self, output_path: Optional[str] = None) -> Dict:
        """
        生成分析報告
        
        參數:
            output_path: 報告輸出路徑（JSON格式），若為None則不儲存
            
        回傳:
            報告資料字典
        """
        print(f"\n生成分析報告...")
        
        # 統計資訊
        stats = {
            'total_generated_files': len(self.generated_files),
            'files_with_warning': sum(1 for f in self.generated_files 
                                     if f.warning_found),
            'files_in_gitignore': sum(1 for f in self.generated_files 
                                     if f.is_in_gitignore),
            'files_not_in_gitignore': sum(1 for f in self.generated_files 
                                         if not f.is_in_gitignore),
        }
        
        # 按生成工具分組
        by_generator = {}
        for file_info in self.generated_files:
            generator = file_info.generator
            if generator not in by_generator:
                by_generator[generator] = []
            by_generator[generator].append(file_info.path)
        
        # 潛在問題：未被忽略且無警告標記的檔案
        potential_issues = [
            f.path for f in self.generated_files
            if not f.is_in_gitignore and not f.warning_found
        ]
        
        report = {
            'scan_time': datetime.now().isoformat(),
            'project_root': str(self.root_dir),
            'statistics': stats,
            'by_generator': by_generator,
            'potential_issues': potential_issues,
            'all_files': [asdict(f) for f in self.generated_files]
        }
        
        # 輸出統計資訊
        print(f"\n統計摘要:")
        print(f"  總自動生成檔案數: {stats['total_generated_files']}")
        print(f"  包含警告標記: {stats['files_with_warning']}")
        print(f"  在.gitignore中: {stats['files_in_gitignore']}")
        print(f"  不在.gitignore中: {stats['files_not_in_gitignore']}")
        
        print(f"\n按生成工具分類:")
        for generator, files in by_generator.items():
            print(f"  {generator}: {len(files)} 個檔案")
        
        if potential_issues:
            print(f"\n⚠️  潛在問題:")
            print(f"  {len(potential_issues)} 個自動生成檔案未被.gitignore忽略且缺少警告標記")
            for path in potential_issues[:10]:  # 只顯示前10個
                print(f"    - {path}")
            if len(potential_issues) > 10:
                print(f"    ... 還有 {len(potential_issues) - 10} 個")
        
        # 儲存報告
        if output_path:
            with open(output_path, 'w', encoding='utf-8') as f:
                json.dump(report, f, indent=2, ensure_ascii=False)
            print(f"\n報告已儲存至: {output_path}")
        
        return report
    
    def add_warning_markers(self, 
                          file_paths: Optional[List[str]] = None,
                          dry_run: bool = True) -> int:
        """
        為自動生成檔案添加警告標記
        
        參數:
            file_paths: 要處理的檔案路徑列表，若為None則處理所有發現的檔案
            dry_run: 是否只模擬不實際修改檔案
            
        回傳:
            處理的檔案數量
        """
        print(f"\n{'模擬' if dry_run else '執行'}添加警告標記...")
        
        # 警告標記模板
        warning_template = """
/*
 * ⚠️  WARNING: THIS IS AN AUTOGENERATED FILE
 * 
 * This file is automatically generated and should NOT be edited manually.
 * Any manual changes will be lost when the file is regenerated.
 * 
 * To make changes:
 * 1. Modify the source template or configuration file
 * 2. Regenerate this file using the appropriate build tool
 * 
 * Generated at: {timestamp}
 */

"""
        
        if file_paths is None:
            # 處理所有未標記的檔案
            files_to_process = [
                f for f in self.generated_files 
                if not f.warning_found
            ]
        else:
            # 處理指定的檔案
            files_to_process = [
                f for f in self.generated_files 
                if f.path in file_paths
            ]
        
        processed_count = 0
        
        for file_info in files_to_process:
            file_path = self.root_dir / file_info.path
            
            try:
                # 讀取原始內容
                with open(file_path, 'r', encoding='utf-8') as f:
                    original_content = f.read()
                
                # 生成警告標記
                warning = warning_template.format(
                    timestamp=datetime.now().isoformat()
                )
                
                # 組合新內容
                new_content = warning + original_content
                
                if not dry_run:
                    # 寫入檔案
                    with open(file_path, 'w', encoding='utf-8') as f:
                        f.write(new_content)
                
                processed_count += 1
                print(f"  {'將處理' if dry_run else '已處理'}: {file_info.path}")
            
            except Exception as e:
                print(f"  ❌ 處理失敗 {file_info.path}: {e}")
        
        print(f"\n{'將處理' if dry_run else '已處理'} {processed_count} 個檔案")
        
        if dry_run:
            print("這是模擬執行，使用 dry_run=False 實際修改檔案")
        
        return processed_count
    
    def generate_gitignore_rules(self) -> List[str]:
        """
        生成建議的.gitignore規則
        
        回傳:
            .gitignore規則列表
        """
        print(f"\n生成.gitignore建議規則...")
        
        # 收集未被忽略的自動生成檔案路徑
        unignored_paths = [
            f.path for f in self.generated_files 
            if not f.is_in_gitignore
        ]
        
        # 分析路徑模式
        suggested_rules = set()
        
        for path in unignored_paths:
            path_obj = Path(path)
            
            # 如果在特定目錄下，建議忽略整個目錄
            if 'build' in path_obj.parts:
                suggested_rules.add('build/')
            elif 'dist' in path_obj.parts:
                suggested_rules.add('dist/')
            elif 'target' in path_obj.parts:
                suggested_rules.add('target/')
            # 根據副檔名建議規則
            elif path.endswith('.generated.ts'):
                suggested_rules.add('*.generated.ts')
            elif path.endswith('_generated.py'):
                suggested_rules.add('*_generated.py')
        
        rules = sorted(list(suggested_rules))
        
        print(f"建議的.gitignore規則:")
        for rule in rules:
            print(f"  {rule}")
        
        return rules

# 使用範例
if __name__ == "__main__":
    # 初始化管理器（替換為實際專案路徑）
    manager = AutogeneratedFileManager(root_dir="./my_project")
    
    print("="*70)
    print("自動生成檔案識別與管理工具")
    print("="*70)
    
    # 掃描專案目錄
    manager.scan_directory(
        extensions=['.py', '.ts', '.java', '.go', '.proto'],
        exclude_dirs=['.git', 'node_modules', 'venv']
    )
    
    # 生成分析報告
    report = manager.generate_report(output_path="generated_files_report.json")
    
    # 生成.gitignore建議
    gitignore_rules = manager.generate_gitignore_rules()
    
    # 模擬添加警告標記
    manager.add_warning_markers(dry_run=True)
    
    print("\n" + "="*70)
    print("分析完成！")
    print("="*70)