"""User-requested native inspection with or without an existing advertisement. An advertisement is never deleted, quarantined or called stale by this module. Exclusive access and exact project binding permit an official inspection. """ from contextlib import contextmanager, ExitStack from dataclasses import asdict, replace import json import os from pathlib import Path, PureWindowsPath import re import stat from uuid import uuid4 def assert_native_idle(target=None): from .owner_probe import query_owners from .native_management import _retained_workers from .native_export_guard import assert_retained_exports_idle from .native_engineering_identity import _OWNER_NAMES from .library_lock import _key, _owner_matches_scope library = None roots = () if target is not None: from .backup_recovery import _project_text roots = (Path(target.project).parent, Path(target.database)) try: lines = re.findall(r'^KEY CentralLibrary\b[^\r\n]*', _project_text(target.project), re.M) references = [re.fullmatch(r'KEY CentralLibrary "([^"\r\n]+)"\s*', line) for line in lines] if not references or any(match is None for match in references): raise ValueError('CentralLibrary references are missing or invalid.') libraries = {(Path(target.project).parent/match[1]).resolve(strict=True) for match in references} if len(libraries) == 1 and all(path.suffix.casefold() == '.lmc' and path.is_file() for path in libraries): library = libraries.pop() roots += (library.parent/'SymbolLibs',) except (OSError, ValueError): pass # Missing/ambiguous original references cannot narrow retained ownership. assert_retained_exports_idle(library) if any(worker.poll() is None and (library is None or not getattr(worker, 'cbb_library', None) or _key(worker.cbb_library) == _key(library)) for worker in _retained_workers): raise ValueError('MAINTENANCE_OWNER_ACTIVE: 管理工作进程尚未返回') names = ('ExpeditionPCB.exe', 'LibraryManager.exe', 'viewdraw.exe', 'iCDBProjectBackup.exe', 'ReuseBlockImporter.exe', 'CleanWGLib.exe', 'cscript.exe', 'wscript.exe', 'python.exe', 'pythonw.exe', 'CbbRefreshVerify.exe', *sorted(_OWNER_NAMES)) owners = [] for item in query_owners(names): if item['pid'] == os.getpid(): continue name, command = item['name'].casefold(), item['command'].casefold() automation = name in ('python.exe', 'pythonw.exe', 'cbbrefreshverify.exe') if not automation or not command or any(flag in command for flag in ( '--verify-worker', '--repair-worker', '--management-worker', '--native-backup-worker')): owners.append(item) if target is not None: owners = [item for item in owners if _owner_matches_scope(item, library, roots) is not False] if owners: raise ValueError(f'MAINTENANCE_OWNER_ACTIVE: 请正常关闭原生程序/操作助手:{owners}') def _assert_native_idle_for(target): """Keep test/third-party zero-argument idle probes compatible.""" import inspect if not inspect.signature(assert_native_idle).parameters: return assert_native_idle() return assert_native_idle(target) def address_snapshot(paths): from .scoped_manifest import hash_file return {str(path.resolve()): {'sha256': hash_file(path), 'size': path.stat().st_size, 'mtime_ns': path.stat().st_mtime_ns} for path in paths} def maintenance_entries(request, *, check=None): from .verify_runner import preflight from .scoped_manifest import scan_tree project, _ = preflight(request) root = Path(request.lmc_file).parent entries = scan_tree(project.parent, check=check) shared = root/'SymbolLibs/__ReusableBlocksSymb' if shared.exists(): entries.update(scan_tree(shared, check=check)) for library in root.glob('*.lmc'): info = library.lstat() if (info.st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT or not stat.S_ISREG(info.st_mode)): raise ValueError(f'不支持通过文件链接维护:{library}') entries[library] = info return entries def _scoped_addresses(request, *, check=None, entries=None): from .scoped_manifest import scan_tree root = Path(request.lmc_file).parent addresses = [] if entries is None: entries = maintenance_entries(request, check=check) if check is not None: check() for path in entries: if path.name.casefold() != 'saddress.adr': continue parts = tuple(part.casefold() for part in path.relative_to(root).parts) independent = (len(parts) >= 6 and parts[0] == 'reusableblockslp' and parts[1] != request.block_name.casefold() and parts[2] == 'work' and parts[3:] in (('database', 'cdbsvr', 'saddress.adr'), ('pcb', 'database', 'cdbsvr', 'saddress.adr'))) if not independent: # Current project and shared/unknown scopes remain visible to the # selector; only exact independent other-CBB Work stores are omitted. addresses.append(path) return addresses def maintenance_project_files(project, pcb): """A legacy linked PCB need not contain the auxiliary PCB/pcb.prj. Its explicit ProjectFile must bind back to the main project. Never guess template.prj (or another PRJ) as an alternative database repair target. """ from .backup_recovery import _project_text project, pcb = Path(project), Path(pcb) auxiliary = pcb.parent/'pcb.prj' if auxiliary.is_file(): return project, auxiliary if os.path.lexists(auxiliary): raise ValueError(f'MAINTENANCE_TARGET_UNCONFIRMED: 工程配置不是文件:{auxiliary}') references = re.findall(r'^KEY ProjectFile "([^"\r\n]+)"', _project_text(pcb), re.M) if (len(references) != 1 or (pcb.parent/references[0]).resolve() != project.resolve()): raise ValueError('MAINTENANCE_TARGET_UNCONFIRMED: 缺少辅助 pcb.prj,且 PCB 的 ProjectFile 未唯一指向当前主工程') return (project,) def select_maintenance_target(request, *, check=None, entries=None): from .verify_runner import preflight from .backup_recovery import _project_text from .native_repair import RepairTarget from .scoped_manifest import scan_tree if request.maintenance is not True: raise ValueError('MAINTENANCE_INTENT_REQUIRED') project, pcb = preflight(request) if entries is None: entries = maintenance_entries(request, check=check) candidates = [] for candidate in maintenance_project_files(project, pcb): if not candidate.is_file(): raise ValueError('MAINTENANCE_TARGET_UNCONFIRMED: 缺少工程配置') text = _project_text(candidate) values = re.findall(r'^KEY iCDBDir "([^"]*)"', text, re.M) if candidate != project and not re.search(r'^KEY iCDBDir\b', text, re.M): continue if (len(values) != 1 or not values[0] or PureWindowsPath(values[0]).drive or PureWindowsPath(values[0]).root): raise ValueError('MAINTENANCE_TARGET_UNCONFIRMED: iCDBDir 必须唯一且为工程内相对路径') database = (candidate.parent/values[0]).resolve() # The proven Project Backup route binds PRJ.parent/database; do not # guess alternate stores or route shared data through another PRJ. if database != (candidate.parent/'database').resolve() or not database.is_relative_to(project.parent.resolve()): raise ValueError('MAINTENANCE_TARGET_UNCONFIRMED: 未验证的 PRJ 数据库映射') if not (database/'icdb.dat').is_file(): raise ValueError('MAINTENANCE_TARGET_UNCONFIRMED: 缺少 icdb.dat') candidates.append(RepairTarget(candidate, candidate.parent/'database')) addresses = _scoped_addresses(request, check=check, entries=entries) if not addresses: # A crashed project may retain its internal open state after the server # advertisement disappears. Explicit maintenance must still inspect it. references = re.findall(r'^KEY ProjectFile "([^"\r\n]+)"', _project_text(pcb), re.M) if len(references) != 1 or (pcb.parent/references[0]).resolve() != project.resolve(): raise ValueError('MAINTENANCE_TARGET_UNCONFIRMED: PCB 的 ProjectFile 未唯一指向所选主工程') if len(candidates) != 1: raise ValueError('MAINTENANCE_TARGET_UNCONFIRMED: 无地址记录且存在多个工程数据库,不能推测修复目标') return candidates[0], project, pcb, addresses if len(addresses) != 1: raise ValueError('MAINTENANCE_TARGET_UNCONFIRMED: 需要唯一工程地址记录;共享或多个数据库不能推测修复') matches = [target for target in candidates if (target.database/'cdbsvr/sAddress.adr').resolve() == addresses[0].resolve()] if len(matches) != 1: raise ValueError('SHARED_DATABASE_REPAIR_UNSUPPORTED: 地址记录不属于唯一匹配的工程数据库') return matches[0], project, pcb, addresses @contextmanager def maintenance_target_guard(request, expected=None, *, stop=None): """Simultaneously hold native database files, preserving every address.""" import win32con, win32file from .scoped_manifest import scan_tree, hash_file def check(): if stop is not None and stop.is_set(): raise ValueError('MAINTENANCE_CANCELLED: 已取消占用检查') check() library_root = Path(request.lmc_file).parent # Share one complete snapshot for target/address selection and file locks. # Refresh it again while the handles are held; do not reuse across guards. entries = maintenance_entries(request, check=check) target, project, pcb, addresses = select_maintenance_target(request, check=check, entries=entries) baseline = address_snapshot(addresses) context = {'library': str(Path(request.lmc_file).resolve()), 'block': request.block_name, 'project': str(target.project.resolve()), 'database': str(target.database.resolve()), 'addresses': baseline, 'engineering_references': {str(p.resolve()): hash_file(p) for p in (pcb, *maintenance_project_files(project, pcb))}} if expected is not None and context != expected: raise ValueError('MAINTENANCE_SOURCE_CHANGED: 目标或地址记录在检查后变化') _assert_native_idle_for(target) check() def native_files(snapshot): return {path for path, info in snapshot.items() if stat.S_ISREG(info.st_mode) and ( path.suffix.casefold() == '.lmc' or path.name.casefold() in ('icdb.dat', 'layoutdb.lyt'))} files = native_files(entries) with ExitStack() as stack: for path in sorted(files): check() handle = win32file.CreateFile(str(path), win32con.GENERIC_READ, 0, None, win32con.OPEN_EXISTING, win32con.FILE_ATTRIBUTE_NORMAL, None) stack.callback(handle.Close) _assert_native_idle_for(target) current = maintenance_entries(request, check=check) if native_files(current) != files: raise ValueError('MAINTENANCE_SOURCE_CHANGED: 检查期间库文件集合发生变化') current_addresses = _scoped_addresses(request, check=check, entries=current) if address_snapshot(current_addresses) != baseline: raise ValueError('MAINTENANCE_SOURCE_CHANGED: 地址记录在检查期间变化') yield {'target': target, 'context': context, 'project': project, 'pcb': pcb} def run_icdb_check(request, *, progress=None, stop=None): """Open PCB diagnostically and classify this attempt's native error content.""" from .verify_runner import VerifyResult, run_verify from .icdb_recovery import icdb_error_content root = Path(request.evidence_dir).resolve()/('icdb-check-'+uuid4().hex[:12]) library_root = Path(request.lmc_file).resolve().parent if root.is_relative_to(library_root) or library_root.is_relative_to(root): return VerifyResult('FAIL', error_category='ICDB_INSPECTION_UNCONFIRMED', stderr='检查记录目录需位于中心库之外。') record = {'operation': 'icdb_batch_check', 'automatic_repair': False, 'library': str(request.lmc_file), 'block': request.block_name} started = False def save(result): report = root/'result.json' recorded = replace(result, evidence_path=report) try: report.write_text(json.dumps({**record, 'result': asdict(recorded)}, ensure_ascii=False, default=str, indent=2), encoding='utf-8') except OSError as error: import logging logging.getLogger(__name__).warning('icdb_check_report_unavailable path=%s error=%s', report, error) return result return recorded try: root.mkdir(parents=True, exist_ok=False) if stop is not None and stop.is_set(): return save(VerifyResult('CANCELLED', stderr='已取消 ICDB 检查。')) if progress: progress({'stage': 'icdb_startup_check', 'block': request.block_name, 'detail': '正在打开工程并检查本次错误信息'}) started = True startup = run_verify(replace(request, maintenance=False, auto_repair=False, diagnostic_only=True, native_lm_verify=False, post_repair_proof=None, evidence_dir=root/'pcb-open'), progress=progress, stop=stop) record['native_open'] = asdict(startup) if startup.status == 'CANCELLED' or stop is not None and stop.is_set(): return save(replace(startup, status='CANCELLED', recovery_attempts=())) if startup.status == 'PASS' and startup.safe_to_continue: return save(replace(startup, status='CHECKED', library_flag='UNKNOWN', stdout='工程打开正常,未发现 ICDB 错误;未执行 CBB 校验。', recovery_attempts=())) content = icdb_error_content(startup.stderr, error_message=True) if (startup.evidence_path and startup.evidence_path.resolve().is_relative_to(root/'pcb-open')): try: saved = json.loads(startup.evidence_path.with_name('diagnostics').joinpath( 'icdb-error-content.json').read_text('utf-8')) native = icdb_error_content(saved.get('native_message', '')) if native: content = '\n'.join(dict.fromkeys(filter(None, (content, native)))) record['native_error'] = saved except (OSError, ValueError, AttributeError): pass if content: return save(replace(startup, status='FAIL', library_flag='UNKNOWN', error_category='ICDB_REPAIR_REQUIRED', stderr='发现 ICDB 错误,未执行修复。\n'+content, recovery_attempts=())) category = startup.error_category if not category or category.startswith('ICDB_'): category = 'ICDB_INSPECTION_UNCONFIRMED' return save(replace(startup, status='FAIL' if startup.status=='PASS' else startup.status, error_category=category, library_flag='UNKNOWN', recovery_attempts=(), stderr=startup.stderr or '工程打开或释放未完成,尚无法确认 ICDB 状态。')) except Exception as error: return save(VerifyResult('FAIL', safe_to_continue=not started, error_category='ICDB_INSPECTION_UNCONFIRMED', stderr=f'无法确认 ICDB 状态:{error}')) def run_diagnosed_maintenance(request, *, diagnose, progress=None, stop=None): """Open PCB once; only a current matching native fault admits maintenance.""" from .verify_runner import VerifyResult from .icdb_recovery import parse_session_loss from .native_repair import select_repair_target if stop is not None and stop.is_set(): return VerifyResult('CANCELLED', stderr='已取消,未打开工程或请求修复。') if progress: progress({'stage': 'icdb_startup_check', 'block': request.block_name, 'detail': '尝试打开工程,依据本次原生报错判断是否需要 ICDB 维护'}) startup = diagnose(replace(request, maintenance=False, auto_repair=False, diagnostic_only=True, native_lm_verify=False, post_repair_proof=None)) def finish(result): if startup.evidence_path: report = startup.evidence_path.with_name('maintenance-result.json') recorded = replace(result, evidence_path=report) try: report.write_text(json.dumps({'block_name': request.block_name, 'startup_evidence': str(startup.evidence_path), **asdict(recorded)}, ensure_ascii=False, default=str, indent=2), encoding='utf-8') except OSError as error: import logging logging.getLogger(__name__).warning('maintenance_result_write_failed path=%s error=%s', report, error) else: result = recorded return result if startup.status == 'PASS' and startup.safe_to_continue: return finish(replace(startup, status='CHECKED', library_flag='UNKNOWN', stdout='工程打开正常,无需 ICDB 修复;未执行 CBB 校验。')) if startup.status == 'PASS': return finish(replace(startup, status='FAIL', stderr='工程打开后未确认会话释放,未请求 ICDB 修复。')) if startup.status != 'FAIL' or not startup.safe_to_continue: return startup # Do not search prior evidence directories or treat an error-code label, # address/checkpoint file, timeout or generic server error as a diagnosis. diagnosis = parse_session_loss(startup.stderr) if diagnosis is None: return startup try: target = select_repair_target(request, diagnosis) except (ValueError, OSError) as error: return finish(replace(startup, stderr=f'{startup.stderr}\n{error}', error_stage='icdb_target_check')) if stop is not None and stop.is_set(): return finish(replace(startup, status='CANCELLED', stderr='已取消,未请求 ICDB 修复。')) return run_existing_address_maintenance(request, diagnosed_target=target, startup_result=startup, progress=progress, stop=stop) def run_existing_address_maintenance(request, *, diagnosed_target, startup_result, progress=None, stop=None): from .library_lock import LibraryLock from .native_repair import run_native_repair, native_success_confirmed, repair_release_state from .verify_runner import VerifyResult root = Path(request.evidence_dir).resolve()/('maintenance-' + uuid4().hex[:12]) library_root = Path(request.lmc_file).resolve().parent if root.is_relative_to(library_root) or library_root.is_relative_to(root): return VerifyResult('BLOCKED', stderr='维护证据必须位于目标库之外', safe_to_continue=False) root.mkdir(parents=True, exist_ok=False) record = {'operation': 'explicit_project_maintenance', 'library': str(request.lmc_file), 'block': request.block_name, 'stage': 'preflight', 'startup_diagnosis': asdict(startup_result)} report = root/'result.json' owner_safe = False recovery = None def emit(stage, **values): record['stage'] = stage if progress: progress({'stage': stage, 'block': request.block_name, **values}) def save(result): result = replace(result, evidence_path=report) record['result'] = asdict(result) report.write_text(json.dumps(record, ensure_ascii=False, default=str, indent=2), encoding='utf-8') return result def native_event(event): emit(event['stage'], **{key: value for key, value in event.items() if key != 'stage'}) try: if stop is not None and stop.is_set(): return save(VerifyResult('CANCELLED', stderr='维护已取消,未启动原生操作')) emit('preflight', detail='正在核对工程、库文件和进程占用;可请求取消') lease = LibraryLock.for_maintenance(request.lmc_file, root/'takeover', lambda: maintenance_target_guard(request, stop=stop), safe_to_release=lambda: owner_safe) with lease: owner_safe = True # Admission completed; no native client exists yet. checked = lease.maintenance_proof target, context = checked['target'], checked['context'] record['maintenance_context'] = context if (target.project.resolve() != diagnosed_target.project.resolve() or target.database.resolve() != diagnosed_target.database.resolve()): return save(VerifyResult('FAIL', safe_to_continue=owner_safe, error_category='ICDB_TARGET_MISMATCH', error_stage='preflight', stderr='本次打开报错的数据库与维护目标不一致,未请求 ICDB 修复。')) if stop is not None and stop.is_set(): raise ValueError('MAINTENANCE_CANCELLED: 已取消,未启动原生检查') emit('icdb_ownership_check', detail='调用原生 Project Backup 检查占用及恢复要求,不执行 Repair') owner_safe = False inspection = run_native_repair(target, root/'native-inspection', mentor_bin=request.mentor_bin, timeout_seconds=min(30, request.timeout_seconds), progress=native_event, maintenance_context=context, inspection_only=True, stop=stop) record['native_inspection'] = inspection owner_safe = (inspection.get('release', {}).get('native_exited') is True or inspection.get('native_pid') is None and inspection.get('worker_pid') is None) from .native_occupancy import confirmed_inspection if not confirmed_inspection(target, inspection): return save(VerifyResult('BLOCKED', safe_to_continue=owner_safe, error_category='ICDB_INSPECTION_UNCONFIRMED', stderr='原生占用检查未确认或已取消,未请求 Repair。' + str(inspection.get('detail', inspection.get('status'))))) if inspection['status'] == 'IN_USE': return save(VerifyResult('BLOCKED', safe_to_continue=owner_safe, error_category='ICDB_DATABASE_IN_USE', stderr='原生工具确认工程正在使用,未请求 Repair。')) # Native loading may retire an old address itself. Permit only # disappearance, never a new/changed advertisement or project. with maintenance_target_guard(request, stop=stop) as refreshed: updated = refreshed['context'] if ({k: v for k, v in context.items() if k != 'addresses'} != {k: v for k, v in updated.items() if k != 'addresses'} or any(context['addresses'].get(k) != v for k, v in updated['addresses'].items())): raise ValueError('MAINTENANCE_SOURCE_CHANGED: 原生检查后工程或地址身份变化') context = updated record['post_inspection_context'] = context if not inspection['repair_required']: return save(VerifyResult('CHECKED', safe_to_continue=owner_safe, stdout='检查完成,无需修复。')) if stop is not None and stop.is_set(): raise ValueError('MAINTENANCE_CANCELLED: 已取消,未开始 Repair') emit('icdb_diagnosis_confirmed', detail='本轮原生检查明确要求修复当前数据库,且确认未占用') native_root = root/'native-repair'; native_root.mkdir() attempt = native_root/'attempt.json' with attempt.open('x', encoding='utf-8') as stream: json.dump({'intent': 'explicit_maintenance', 'target': asdict(target), 'maintenance_context': context}, stream, default=str, ensure_ascii=False) emit('native_repair_start', detail='核对占用后由官方工具检查/修复;应用不自动备份') # Repeat immediately before dispatch; the worker repeats before # launching the native process as well. with maintenance_target_guard(request, context, stop=stop): pass owner_safe = False recovery = run_native_repair(target, native_root, mentor_bin=request.mentor_bin, timeout_seconds=max(60, request.timeout_seconds), progress=native_event, maintenance_context=context, stop=stop) _assert_native_idle_for(target) recovery = {**recovery, 'native_status': recovery.get('status'), 'validation_passed': False} recovery['release'] = repair_release_state(request, target, recovery) safe = recovery['release'].get('safe_to_continue') is True confirmed = recovery.get('status') == 'REPAIRED' and safe and native_success_confirmed(target, recovery) # Release follows actual clients, not the repair/content verdict. owner_safe = safe or (recovery['release'].get('native_exited') is True and recovery['release'].get('database_exclusive') is True and recovery['release'].get('remaining_pids') == []) if confirmed: emit('native_repair_complete', detail='原生 ICDB 修复完成,CBB 待单独校验') recovery['status'] = 'REPAIRED_UNVERIFIED' return save(VerifyResult('REPAIRED', safe_to_continue=owner_safe, stdout='原生 ICDB 修复完成,CBB 待单独校验。', recovery_attempts=(recovery,))) if recovery.get('status') == 'REPAIRED': recovery['status'] = 'UNCONFIRMED'; owner_safe = False return save(VerifyResult('FAIL', stderr=f'{recovery["status"]}: {recovery.get("detail", "原生维护未确认修复")}', safe_to_continue=owner_safe, recovery_attempts=(recovery,), error_category='ICDB_MAINTENANCE_RESULT')) except Exception as error: return save(VerifyResult('BLOCKED' if recovery is None else 'FAIL', stderr=str(error), safe_to_continue=False, recovery_attempts=(recovery,) if recovery else (), error_category='ICDB_MAINTENANCE_BLOCKED', error_stage=record['stage']))