mxready 1.0.0__py3-none-any.whl

mxready/reporting/markdown.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import html
+from collections import defaultdict
+
+from mxready.models import Finding, FindingOccurrence, ScanReport, Severity
+
+_SEVERITY_HEADINGS = {
+    Severity.BLOCKER: "阻塞项",
+    Severity.WARNING: "警告",
+    Severity.INFO: "提示",
+}
+_MARKDOWN_CONTROL_CHARACTERS = "\\`*_{}[]()#+-.!|>"
+
+
+def render_markdown(report: ScanReport) -> str:
+    """Render a deterministic, portable report with untrusted text escaped."""
+    lines = [
+        f"# MXReady 适配体检报告：{_markdown_text(report.repository.name)}",
+        "",
+        "## 扫描元数据",
+        "",
+        "| 字段 | 值 |",
+        "| --- | --- |",
+        f"| 仓库 | {_table_cell(report.repository.url)} |",
+        f"| 提交 | `{report.repository.commit}` |",
+        f"| MXReady 版本 | {_table_cell(report.tool_version)} |",
+        f"| 规则集版本 | {_table_cell(report.ruleset_version)} |",
+        f"| 规则集摘要 | {_table_cell(report.ruleset_digest or '未记录')} |",
+        f"| 扩展规则版本 | {_table_cell(report.extra_ruleset_version or '无')} |",
+        f"| 分析配置 | {_table_cell(str(report.analysis_config))} |",
+        f"| 扫描时间 | {_table_cell(report.scanned_at.isoformat())} |",
+        f"| 静态状态 | `{report.static_status.value}` |",
+        f"| 硬件验证状态 | `{report.verification_status.value}` |",
+        "",
+        "## 结果摘要",
+        "",
+        "| 阻塞项 | 警告 | 提示 | 总计 |",
+        "| ---: | ---: | ---: | ---: |",
+        (
+            f"| {report.summary.blocker_count} | {report.summary.warning_count} "
+            f"| {report.summary.info_count} | {report.summary.total_count} |"
+        ),
+        "",
+    ]
+
+    lines.extend(["## 扫描范围", ""])
+    if report.coverage:
+        c = report.coverage
+        lines.extend(
+            [
+                f"分析文件：{c.analyzed_files}；字节：{c.analyzed_bytes}；排除目录：{c.excluded_directories}（未遍历内容）。",
+                f"文件类型：{_markdown_text(str(c.files_by_type))}",
+                f"跳过原因：{_markdown_text(str(c.skipped_by_reason))}",
+                "",
+            ]
+        )
+    else:
+        lines.extend(["旧报告未记录扫描范围，请重新扫描。", ""])
+    lines.extend(["仅表示支持的文件类型与限制内的扫描范围，不是完整仓库覆盖率。", ""])
+    grouped: defaultdict[Severity, list[Finding]] = defaultdict(list)
+    for finding in report.findings:
+        grouped[finding.severity].append(finding)
+
+    for severity in (Severity.BLOCKER, Severity.WARNING, Severity.INFO):
+        lines.extend([f"## {_SEVERITY_HEADINGS[severity]}", ""])
+        findings = grouped[severity]
+        if not findings:
+            lines.extend(["无。", ""])
+            continue
+        for finding in findings:
+            lines.extend(_render_finding(finding))
+
+    lines.extend(["## 迁移清单", ""])
+    if report.migration_checklist:
+        for item in report.migration_checklist:
+            files = "、".join(_inline_code(path) for path in item.affected_files)
+            lines.append(
+                f"- [ ] `{item.rule_id}` {_markdown_text(item.title)}："
+                f"{_markdown_text(item.action)}"
+            )
+            lines.append(f"  - 涉及文件：{files or '无'}")
+    else:
+        lines.append("当前没有由阻塞项或警告生成的迁移任务。")
+    lines.append("")
+
+    lines.extend(["## 分析警告", ""])
+    if report.analysis_warnings:
+        for warning in report.analysis_warnings:
+            location = f"（{_inline_code(warning.relative_path)}）" if warning.relative_path else ""
+            lines.append(f"- `{warning.code}`{location}：{_markdown_text(warning.message)}")
+    else:
+        lines.append("无。")
+    lines.extend(
+        [
+            "",
+            "## 说明",
+            "",
+            (
+                "静态扫描不能替代真实沐曦 GPU 上的构建、功能和性能验证，"
+                "也不能作为项目安全性或完整兼容性的证明。"
+            ),
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _render_finding(finding: Finding) -> list[str]:
+    lines = [
+        f"### `{finding.rule_id}` — {_markdown_text(finding.title)}",
+        "",
+        (
+            f"- 位置：{_inline_code(finding.relative_path)}，"
+            f"第 {finding.line_start}–{finding.line_end} 行"
+        ),
+        f"- 分类：`{_markdown_text(finding.category)}`",
+        f"- 说明：{_markdown_text(finding.message)}",
+        f"- 建议：{_markdown_text(finding.recommendation)}",
+        "- 证据：",
+        "",
+    ]
+    for occurrence in finding.occurrences or [
+        FindingOccurrence(
+            line_start=finding.line_start, line_end=finding.line_end, evidence=finding.evidence
+        )
+    ]:
+        lines.extend([f"- 第 {occurrence.line_start}–{occurrence.line_end} 行", ""])
+        lines.extend(
+            f"    {html.escape(line, quote=False)}"
+            for line in occurrence.evidence.splitlines() or [""]
+        )
+        lines.append("")
+    if not finding.occurrences and finding.count > 1:
+        lines.append("旧报告仅保留聚合证据，无法恢复所有命中位置。")
+    if finding.references:
+        lines.extend(["", "- 参考："])
+        for reference in finding.references:
+            lines.append(f"  - [{_markdown_text(reference.title)}]({reference.url})")
+    lines.extend(["", ""])
+    return lines
+
+
+def _markdown_text(value: str) -> str:
+    escaped = html.escape(value, quote=False)
+    for character in _MARKDOWN_CONTROL_CHARACTERS:
+        escaped = escaped.replace(character, f"\\{character}")
+    return escaped.replace("\r", " ").replace("\n", " ")
+
+
+def _table_cell(value: str) -> str:
+    return _markdown_text(value)
+
+
+def _inline_code(value: str) -> str:
+    escaped = html.escape(value, quote=False).replace("`", "`")
+    return f"`{escaped.replace(chr(10), ' ').replace(chr(13), ' ')}`"

mxready/reporting/sarif.py

@@ -0,0 +1,94 @@
+"""Portable SARIF 2.1.0 export of static findings (never hardware certification)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+from mxready.models import FindingOccurrence, ScanReport, Severity
+
+
+def render_sarif(report: ScanReport) -> str:
+    rules: dict[str, Any] = {}
+    results = []
+    levels = {Severity.BLOCKER: "error", Severity.WARNING: "warning", Severity.INFO: "note"}
+    for finding in report.findings:
+        rules.setdefault(
+            finding.rule_id,
+            {
+                "id": finding.rule_id,
+                "shortDescription": {"text": finding.title},
+                "help": {"text": finding.recommendation},
+                "properties": {"ruleVersion": finding.rule_version},
+            },
+        )
+        occurrences = finding.occurrences or [
+            FindingOccurrence(
+                line_start=finding.line_start,
+                line_end=finding.line_end,
+                evidence=finding.evidence,
+            )
+        ]
+        for occurrence in occurrences:
+            results.append(
+                {
+                    "ruleId": finding.rule_id,
+                    "level": levels[finding.severity],
+                    "message": {"text": finding.message + "\n" + finding.recommendation},
+                    "locations": [
+                        {
+                            "physicalLocation": {
+                                "artifactLocation": {
+                                    "uri": quote(finding.relative_path, safe="/"),
+                                    "uriBaseId": "%SRCROOT%",
+                                },
+                                "region": {
+                                    "startLine": occurrence.line_start,
+                                    "endLine": occurrence.line_end,
+                                    "snippet": {"text": occurrence.evidence},
+                                },
+                            }
+                        }
+                    ],
+                    "properties": {
+                        "aggregateCount": finding.count,
+                        "occurrencesComplete": len(finding.occurrences) == finding.count,
+                    },
+                }
+            )
+    return (
+        json.dumps(
+            {
+                "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+                "version": "2.1.0",
+                "runs": [
+                    {
+                        "tool": {
+                            "driver": {
+                                "name": "MXReady",
+                                "version": report.tool_version,
+                                "rules": list(rules.values()),
+                            }
+                        },
+                        "versionControlProvenance": [
+                            {
+                                "repositoryUri": report.repository.url,
+                                "revisionId": report.repository.commit,
+                            }
+                        ],
+                        "results": results,
+                        "properties": {
+                            "scanId": str(report.scan_id),
+                            "coverage": report.coverage.model_dump() if report.coverage else None,
+                            "analysisWarnings": [w.model_dump() for w in report.analysis_warnings],
+                            "scope": "Static analysis only; hardware verification is separate.",
+                        },
+                    }
+                ],
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+        + "\n"
+    )

mxready/reporting/terminal.py

@@ -0,0 +1,75 @@
+"""终端极简结果摘要：一行状态 + 前若干条命中 + 报告文件位置。
+
+中文输出只用 GBK 可编码字符（中文、…、—、·、ASCII）；``english=True`` 时
+输出纯 ASCII，供 cp1252 等无法编码中文的旧代码页回退使用。
+"""
+
+from __future__ import annotations
+
+from mxready.models import ScanReport, Severity
+
+_MAX_LISTED_FINDINGS = 5
+_SEVERITY_LABELS = {
+    Severity.BLOCKER: "阻断",
+    Severity.WARNING: "警告",
+    Severity.INFO: "提示",
+}
+_SEVERITY_LABELS_EN = {
+    Severity.BLOCKER: "BLOCKER",
+    Severity.WARNING: "WARNING",
+    Severity.INFO: "INFO",
+}
+
+
+def render_terminal_summary(
+    report: ScanReport,
+    *,
+    output_note: str | None = None,
+    max_listed: int = _MAX_LISTED_FINDINGS,
+    english: bool = False,
+) -> str:
+    """渲染适合直接阅读的极简检查结果；命中按严重程度排序，只列前若干条。
+
+    英文模式省略规则标题，避免中文标题在 cp1252 等旧代码页中无法输出。
+    """
+    summary = report.summary
+    if english:
+        labels = _SEVERITY_LABELS_EN
+        lines = [
+            f"MXReady: {report.static_status.value} | "
+            f"blockers {summary.blocker_count}, "
+            f"warnings {summary.warning_count}, "
+            f"info {summary.info_count}"
+        ]
+    else:
+        labels = _SEVERITY_LABELS
+        lines = [
+            f"MXReady: {report.static_status.value} | "
+            f"阻断 {summary.blocker_count} · "
+            f"警告 {summary.warning_count} · "
+            f"提示 {summary.info_count}"
+        ]
+    if report.findings:
+        for finding in report.findings[:max_listed]:
+            count = f" x{finding.count}" if finding.count > 1 else ""
+            if english:
+                lines.append(
+                    f"  {labels[finding.severity]} {finding.rule_id}"
+                    f" ({finding.relative_path}:{finding.line_start}{count})"
+                )
+            else:
+                lines.append(
+                    f"  {labels[finding.severity]} {finding.rule_id}"
+                    f" {finding.title} ({finding.relative_path}:{finding.line_start}{count})"
+                )
+        hidden = len(report.findings) - max_listed
+        if hidden > 0:
+            if english:
+                lines.append(f"  ... {hidden} more in the report file")
+            else:
+                lines.append(f"  … 其余 {hidden} 项见报告文件")
+    else:
+        lines.append("  No rule matches" if english else "  未命中任何规则")
+    if output_note:
+        lines.append(f"Report: {output_note}" if english else f"报告: {output_note}")
+    return "\n".join(lines)

mxready/repository/__init__.py

@@ -0,0 +1,14 @@
+from mxready.repository.git_client import GitClient, RepositoryLimits
+from mxready.repository.identity import (
+    RepositoryIdentity,
+    parse_repository_url,
+    validate_git_ref,
+)
+
+__all__ = [
+    "GitClient",
+    "RepositoryIdentity",
+    "RepositoryLimits",
+    "parse_repository_url",
+    "validate_git_ref",
+]

mxready/repository/git_client.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from subprocess import CompletedProcess, TimeoutExpired
+from typing import Protocol
+
+from mxready.errors import MxReadyError
+from mxready.repository.identity import RepositoryIdentity, validate_git_ref
+
+_COMMIT = re.compile(r"[0-9a-fA-F]{40}")
+
+
+class CommandRunner(Protocol):
+    def __call__(
+        self,
+        args: Sequence[str],
+        *,
+        cwd: Path | None,
+        env: Mapping[str, str],
+        timeout: float,
+    ) -> CompletedProcess[str]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class RepositoryLimits:
+    clone_timeout_seconds: float = 60
+    max_bytes: int = 52_428_800
+    max_files: int = 10_000
+
+    def __post_init__(self) -> None:
+        if self.clone_timeout_seconds <= 0 or self.max_bytes <= 0 or self.max_files <= 0:
+            raise ValueError("repository limits must be positive")
+
+
+def run_command(
+    args: Sequence[str],
+    *,
+    cwd: Path | None,
+    env: Mapping[str, str],
+    timeout: float,
+) -> CompletedProcess[str]:
+    return subprocess.run(
+        list(args),
+        cwd=cwd,
+        env=dict(env),
+        timeout=timeout,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+
+
+class GitClient:
+    def __init__(
+        self,
+        *,
+        command_runner: CommandRunner = run_command,
+        limits: RepositoryLimits | None = None,
+    ) -> None:
+        self._command_runner = command_runner
+        self.limits = limits or RepositoryLimits()
+
+    def clone(
+        self,
+        identity: RepositoryIdentity,
+        requested_ref: str | None,
+        destination: Path,
+    ) -> str:
+        reference = validate_git_ref(requested_ref)
+        destination = Path(destination)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        environment = self._git_environment()
+
+        if reference is not None and _COMMIT.fullmatch(reference):
+            self._clone_commit(identity, reference, destination, environment)
+        else:
+            self._clone_branch_or_default(
+                identity,
+                reference,
+                destination,
+                environment,
+            )
+
+        self._enforce_repository_limits(destination)
+        result = self._run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=destination,
+            environment=environment,
+        )
+        commit = result.stdout.strip().lower()
+        if _COMMIT.fullmatch(commit) is None:
+            raise MxReadyError(
+                "SCAN_INTERNAL_ERROR",
+                "Git 未能返回有效的提交编号，请稍后重试。",
+            )
+        return commit
+
+    def _clone_branch_or_default(
+        self,
+        identity: RepositoryIdentity,
+        reference: str | None,
+        destination: Path,
+        environment: Mapping[str, str],
+    ) -> None:
+        args = [
+            "git",
+            "clone",
+            "--depth",
+            "1",
+            "--single-branch",
+            "--no-tags",
+        ]
+        if reference is not None:
+            args.extend(["--branch", reference])
+        args.extend([identity.clone_url, str(destination)])
+        self._run(args, cwd=destination.parent, environment=environment)
+
+    def _clone_commit(
+        self,
+        identity: RepositoryIdentity,
+        reference: str,
+        destination: Path,
+        environment: Mapping[str, str],
+    ) -> None:
+        self._run(
+            ["git", "init", str(destination)],
+            cwd=destination.parent,
+            environment=environment,
+        )
+        self._run(
+            ["git", "remote", "add", "origin", identity.clone_url],
+            cwd=destination,
+            environment=environment,
+        )
+        self._run(
+            [
+                "git",
+                "fetch",
+                "--depth",
+                "1",
+                "--no-tags",
+                "origin",
+                reference,
+            ],
+            cwd=destination,
+            environment=environment,
+        )
+        self._run(
+            ["git", "checkout", "--detach", "FETCH_HEAD"],
+            cwd=destination,
+            environment=environment,
+        )
+
+    def _run(
+        self,
+        args: Sequence[str],
+        *,
+        cwd: Path,
+        environment: Mapping[str, str],
+    ) -> CompletedProcess[str]:
+        try:
+            result = self._command_runner(
+                args,
+                cwd=cwd,
+                env=environment,
+                timeout=self.limits.clone_timeout_seconds,
+            )
+        except TimeoutExpired as error:
+            raise MxReadyError(
+                "CLONE_TIMEOUT",
+                "仓库获取超时，请确认仓库可公开访问或稍后重试。",
+            ) from error
+        except OSError as error:
+            raise MxReadyError(
+                "SCAN_INTERNAL_ERROR",
+                "无法启动 Git，请检查服务环境后重试。",
+            ) from error
+
+        if result.returncode != 0:
+            raise self._map_git_failure(result.stderr)
+        return result
+
+    def _enforce_repository_limits(self, destination: Path) -> None:
+        total_bytes = 0
+        total_files = 0
+        pending = [destination]
+
+        try:
+            while pending:
+                directory = pending.pop()
+                with os.scandir(directory) as entries:
+                    for entry in entries:
+                        if entry.is_symlink():
+                            continue
+                        if entry.is_dir(follow_symlinks=False):
+                            pending.append(Path(entry.path))
+                            continue
+                        if not entry.is_file(follow_symlinks=False):
+                            continue
+
+                        total_files += 1
+                        if total_files > self.limits.max_files:
+                            raise MxReadyError(
+                                "TOO_MANY_FILES",
+                                f"仓库文件数超过 {self.limits.max_files} 个限制。",
+                            )
+                        total_bytes += entry.stat(follow_symlinks=False).st_size
+                        if total_bytes > self.limits.max_bytes:
+                            raise MxReadyError(
+                                "REPOSITORY_TOO_LARGE",
+                                f"仓库内容超过 {self.limits.max_bytes} 字节限制。",
+                            )
+        except MxReadyError:
+            raise
+        except OSError as error:
+            raise MxReadyError(
+                "SCAN_INTERNAL_ERROR",
+                "无法安全读取克隆后的仓库。",
+            ) from error
+
+    @staticmethod
+    def _git_environment() -> dict[str, str]:
+        environment = os.environ.copy()
+        environment.update(
+            {
+                "GIT_TERMINAL_PROMPT": "0",
+                "GIT_LFS_SKIP_SMUDGE": "1",
+                "GIT_CONFIG_COUNT": "1",
+                "GIT_CONFIG_KEY_0": "credential.helper",
+                "GIT_CONFIG_VALUE_0": "",
+                "LANG": "C.UTF-8",
+                "LC_ALL": "C.UTF-8",
+            }
+        )
+        return environment
+
+    @staticmethod
+    def _map_git_failure(stderr: str) -> MxReadyError:
+        normalized = stderr.casefold()
+        access_markers = (
+            "authentication failed",
+            "access denied",
+            "permission denied",
+            "could not read username",
+            "terminal prompts disabled",
+        )
+        not_found_markers = (
+            "repository not found",
+            "does not exist",
+            "couldn't find remote ref",
+            "could not find remote ref",
+            "not found",
+        )
+
+        if any(marker in normalized for marker in access_markers):
+            return MxReadyError(
+                "REPOSITORY_ACCESS_DENIED",
+                "仓库拒绝访问；MXReady 的 MVP 只支持无需登录的公开仓库。",
+            )
+        if any(marker in normalized for marker in not_found_markers):
+            return MxReadyError(
+                "REPOSITORY_NOT_FOUND",
+                "未找到仓库或指定分支、标签、提交，请检查输入。",
+            )
+        return MxReadyError(
+            "SCAN_INTERNAL_ERROR",
+            "Git 获取仓库失败，请稍后重试。",
+        )