mxready 1.0.0__py3-none-any.whl

mxready/resources/schemas/verification-result-v1.json

@@ -0,0 +1,259 @@
+{
+  "$defs": {
+    "VerificationCheck": {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+          "title": "Id",
+          "type": "string"
+        },
+        "command": {
+          "items": {
+            "type": "string"
+          },
+          "maxItems": 32,
+          "minItems": 1,
+          "title": "Command",
+          "type": "array"
+        },
+        "status": {
+          "enum": [
+            "passed",
+            "failed",
+            "unavailable"
+          ],
+          "title": "Status",
+          "type": "string"
+        },
+        "return_code": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Return Code"
+        },
+        "stdout": {
+          "default": "",
+          "maxLength": 16384,
+          "title": "Stdout",
+          "type": "string"
+        },
+        "stderr": {
+          "default": "",
+          "maxLength": 16384,
+          "title": "Stderr",
+          "type": "string"
+        },
+        "duration_ms": {
+          "minimum": 0,
+          "title": "Duration Ms",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "id",
+        "command",
+        "status",
+        "duration_ms"
+      ],
+      "title": "VerificationCheck",
+      "type": "object"
+    },
+    "VerificationCommand": {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+          "title": "Id",
+          "type": "string"
+        },
+        "command": {
+          "items": {
+            "type": "string"
+          },
+          "maxItems": 32,
+          "minItems": 1,
+          "title": "Command",
+          "type": "array"
+        },
+        "timeout_seconds": {
+          "maximum": 600,
+          "minimum": 1,
+          "title": "Timeout Seconds",
+          "type": "integer"
+        },
+        "status": {
+          "enum": [
+            "passed",
+            "failed",
+            "timeout",
+            "cancelled"
+          ],
+          "title": "Status",
+          "type": "string"
+        },
+        "return_code": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Return Code"
+        },
+        "stdout": {
+          "default": "",
+          "maxLength": 16384,
+          "title": "Stdout",
+          "type": "string"
+        },
+        "stderr": {
+          "default": "",
+          "maxLength": 16384,
+          "title": "Stderr",
+          "type": "string"
+        },
+        "duration_ms": {
+          "minimum": 0,
+          "title": "Duration Ms",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "id",
+        "command",
+        "timeout_seconds",
+        "status",
+        "duration_ms"
+      ],
+      "title": "VerificationCommand",
+      "type": "object"
+    },
+    "VerifiedRepositoryState": {
+      "additionalProperties": false,
+      "properties": {
+        "working_directory": {
+          "maxLength": 4096,
+          "minLength": 1,
+          "title": "Working Directory",
+          "type": "string"
+        },
+        "commit": {
+          "pattern": "^[0-9a-f]{40}$",
+          "title": "Commit",
+          "type": "string"
+        },
+        "dirty": {
+          "const": false,
+          "title": "Dirty",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "working_directory",
+        "commit",
+        "dirty"
+      ],
+      "title": "VerifiedRepositoryState",
+      "type": "object"
+    }
+  },
+  "additionalProperties": false,
+  "properties": {
+    "repository_state": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/VerifiedRepositoryState"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null
+    },
+    "schema_version": {
+      "const": "1.0",
+      "default": "1.0",
+      "title": "Schema Version",
+      "type": "string"
+    },
+    "scan_id": {
+      "format": "uuid",
+      "title": "Scan Id",
+      "type": "string"
+    },
+    "repository_commit": {
+      "pattern": "^[0-9a-f]{40}$",
+      "title": "Repository Commit",
+      "type": "string"
+    },
+    "runner_version": {
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "title": "Runner Version",
+      "type": "string"
+    },
+    "environment_fingerprint": {
+      "pattern": "^sha256:[0-9a-f]{64}$",
+      "title": "Environment Fingerprint",
+      "type": "string"
+    },
+    "checks": {
+      "items": {
+        "$ref": "#/$defs/VerificationCheck"
+      },
+      "maxItems": 64,
+      "title": "Checks",
+      "type": "array"
+    },
+    "commands": {
+      "items": {
+        "$ref": "#/$defs/VerificationCommand"
+      },
+      "maxItems": 64,
+      "title": "Commands",
+      "type": "array"
+    },
+    "started_at": {
+      "format": "date-time",
+      "title": "Started At",
+      "type": "string"
+    },
+    "finished_at": {
+      "format": "date-time",
+      "title": "Finished At",
+      "type": "string"
+    },
+    "overall_status": {
+      "enum": [
+        "passed",
+        "failed",
+        "cancelled"
+      ],
+      "title": "Overall Status",
+      "type": "string"
+    }
+  },
+  "required": [
+    "scan_id",
+    "repository_commit",
+    "runner_version",
+    "environment_fingerprint",
+    "checks",
+    "commands",
+    "started_at",
+    "finished_at",
+    "overall_status"
+  ],
+  "title": "VerificationRun",
+  "type": "object",
+  "$schema": "https://json-schema.org/draft/2020-12/schema"
+}

mxready/scanning/__init__.py

@@ -0,0 +1,17 @@
+from mxready.scanning.facts import ProjectFacts, SourceLocation, extract_project_facts
+from mxready.scanning.indexer import (
+    FileIndex,
+    IndexedFile,
+    IndexWarning,
+    build_file_index,
+)
+
+__all__ = [
+    "FileIndex",
+    "IndexWarning",
+    "IndexedFile",
+    "ProjectFacts",
+    "SourceLocation",
+    "build_file_index",
+    "extract_project_facts",
+]

mxready/scanning/analyzer.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from mxready import __version__
+from mxready.models import (
+    AnalysisWarning,
+    Finding,
+    FindingOccurrence,
+    MigrationChecklistItem,
+    RepositorySnapshot,
+    ScanReport,
+    ScanStatus,
+    Severity,
+    VerificationStatus,
+    calculate_static_status,
+    summarize_findings,
+)
+from mxready.repository.identity import parse_repository_url
+from mxready.scanning.facts import extract_project_facts
+from mxready.scanning.indexer import build_file_index
+from mxready.scanning.path_context import apply_path_context
+from mxready.scanning.rule_engine import evaluate_rules, prefilter_status
+from mxready.scanning.rule_loader import RuleCatalog
+from mxready.scanning.toolchain import apply_toolchain_profile
+
+
+class ScanAnalyzer:
+    def __init__(
+        self,
+        catalog: RuleCatalog,
+        providers: Mapping[str, str] | None = None,
+        *,
+        max_findings: int = 10_000,
+        rule_timeout_seconds: float = 30,
+        enable_prefilter: bool = True,
+    ) -> None:
+        self.catalog = catalog
+        self.providers = providers
+        self.max_findings = max_findings
+        self.rule_timeout_seconds = rule_timeout_seconds
+        self.enable_prefilter = enable_prefilter
+
+    def analyze(
+        self,
+        repository_root: Path,
+        *,
+        repository_url: str,
+        commit: str,
+        scan_id: UUID,
+        stage_callback: Callable[[ScanStatus], None],
+    ) -> ScanReport:
+        stage_callback(ScanStatus.INDEXING)
+        index = build_file_index(repository_root)
+
+        stage_callback(ScanStatus.ANALYZING)
+        facts = extract_project_facts(index)
+        findings = _aggregate_findings(
+            evaluate_rules(
+                self.catalog,
+                index,
+                facts,
+                max_findings=self.max_findings,
+                timeout_seconds=self.rule_timeout_seconds,
+                enable_prefilter=self.enable_prefilter,
+            )
+        )
+        # 路径上下文先于工具链画像生效：测试/示例/文档路径上的命中先封顶为提示，
+        # 工具链画像随后只需处理交付路径，避免出现"从 blocker 降为 warning"
+        # 这种对一条早已是提示的 finding 的错误说明。
+        findings, path_warnings = apply_path_context(findings)
+        # 严重级别取决于"项目是否已接入 MXMACA 兼容层"这一前提；工具链画像要在
+        # 汇总之前生效，否则 summary 计数与 findings 的级别会对不上。
+        findings, toolchain_warnings = apply_toolchain_profile(findings, facts)
+        summary = summarize_findings(findings)
+        identity = parse_repository_url(repository_url, self.providers)
+
+        return ScanReport(
+            scan_id=scan_id,
+            repository=RepositorySnapshot(
+                provider=identity.provider,
+                owner=identity.owner,
+                name=identity.name,
+                url=identity.clone_url.removesuffix(".git"),
+                commit=commit,
+            ),
+            tool_version=__version__,
+            ruleset_version=self.catalog.version,
+            ruleset_digest=self.catalog.digest,
+            extra_ruleset_version=self.catalog.extra_version,
+            analysis_config={
+                "max_findings": self.max_findings,
+                "rule_timeout_seconds": self.rule_timeout_seconds,
+                "index_max_files": 10_000,
+                "index_max_file_bytes": 1_048_576,
+                # 记录实际生效状态而非配置意图：解析器探测失败时为 "unavailable"。
+                "prefilter": prefilter_status() if self.enable_prefilter else "off",
+            },
+            scanned_at=datetime.now(UTC),
+            summary=summary,
+            findings=findings,
+            coverage=index.coverage,
+            migration_checklist=_build_migration_checklist(findings),
+            analysis_warnings=[
+                AnalysisWarning(
+                    code=warning.code,
+                    relative_path=warning.relative_path,
+                    message=warning.message,
+                )
+                for warning in index.warnings
+            ]
+            + (
+                [
+                    AnalysisWarning(
+                        code="NO_ANALYZABLE_SOURCE",
+                        message="没有可分析的源码或配置文件；零命中不代表兼容性通过。",
+                    )
+                ]
+                if not index.files
+                else []
+            )
+            + path_warnings
+            + toolchain_warnings,
+            static_status=calculate_static_status(summary),
+            verification_status=VerificationStatus.NOT_RUN,
+        )
+
+
+def _aggregate_findings(findings: list[Finding]) -> list[Finding]:
+    """同一规则在同一文件多次命中时合并为一条并累计命中数，降低报告噪音。"""
+    grouped: dict[tuple[str, str], Finding] = {}
+    for finding in findings:
+        occurrences = finding.occurrences or [
+            FindingOccurrence(
+                line_start=finding.line_start,
+                line_end=finding.line_end,
+                evidence=finding.evidence,
+            )
+        ]
+        key = (finding.rule_id, finding.relative_path)
+        existing = grouped.get(key)
+        if existing is None:
+            grouped[key] = finding.model_copy(update={"occurrences": occurrences})
+            continue
+        grouped[key] = existing.model_copy(
+            update={
+                "count": existing.count + finding.count,
+                "occurrences": existing.occurrences + occurrences,
+                "line_start": min(existing.line_start, finding.line_start),
+                "line_end": max(existing.line_end, finding.line_end),
+            }
+        )
+    return list(grouped.values())
+
+
+def _build_migration_checklist(findings) -> list[MigrationChecklistItem]:
+    grouped: dict[str, dict[str, Any]] = {}
+    for finding in findings:
+        if finding.severity not in {Severity.BLOCKER, Severity.WARNING}:
+            continue
+        item = grouped.setdefault(
+            finding.rule_id,
+            {
+                "title": finding.title,
+                "action": finding.recommendation,
+                "files": set(),
+            },
+        )
+        item["files"].add(finding.relative_path)
+
+    return [
+        MigrationChecklistItem(
+            rule_id=rule_id,
+            title=item["title"],
+            action=item["action"],
+            affected_files=sorted(item["files"]),
+        )
+        for rule_id, item in grouped.items()
+    ]