jeseki-code-quality 0.1.0__tar.gz

jeseki_code_quality-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+tmp/
+
+# Virtual environments
+.venv
+.env

jeseki_code_quality-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

jeseki_code_quality-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: jeseki-code-quality
+Version: 0.1.0
+Summary: Generate an offline HTML code quality report.
+Requires-Python: >=3.13
+Requires-Dist: typer>=0.26.8
+Description-Content-Type: text/markdown
+
+# code-quality
+
+生成离线 HTML 代码质量报告的自用 CLI。
+
+```bash
+uv tool install jeseki-code-quality
+```
+
+```bash
+uv run code-quality
+uv run cq
+uv run code-quality --root /path/to/project --output /path/to/report.html
+uv run cq -r /path/to/project -o /path/to/report.html -t
+```
+
+默认扫描当前工作目录下的 `src/server` 和 `src/client`，并输出到
+`<root>/tmp/code_quality_report.html`。

jeseki_code_quality-0.1.0/README.md

@@ -0,0 +1,17 @@
+# code-quality
+
+生成离线 HTML 代码质量报告的自用 CLI。
+
+```bash
+uv tool install jeseki-code-quality
+```
+
+```bash
+uv run code-quality
+uv run cq
+uv run code-quality --root /path/to/project --output /path/to/report.html
+uv run cq -r /path/to/project -o /path/to/report.html -t
+```
+
+默认扫描当前工作目录下的 `src/server` 和 `src/client`，并输出到
+`<root>/tmp/code_quality_report.html`。

jeseki_code_quality-0.1.0/code_quality/__init__.py

@@ -0,0 +1,2 @@
+"""Code quality report generator."""
+

jeseki_code_quality-0.1.0/code_quality/cli.py

@@ -0,0 +1,66 @@
+"""Typer CLI for generating code quality reports."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from code_quality.report import build_report, format_score, write_report
+
+
+app = typer.Typer(
+    add_completion=False,
+    help="生成代码质量 HTML 报告。",
+)
+
+
+@app.command()
+def main(
+    root: Annotated[
+        Path,
+        typer.Option(
+            "--root",
+            "-r",
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+            help="项目根目录；默认扫描当前工作目录。",
+        ),
+    ] = Path.cwd(),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            file_okay=True,
+            dir_okay=False,
+            writable=True,
+            resolve_path=True,
+            help="HTML 报告输出路径；默认写入 <root>/tmp/code_quality_report.html。",
+        ),
+    ] = None,
+    include_tests: Annotated[
+        bool,
+        typer.Option(
+            "--include-tests",
+            "-t",
+            help="让测试文件参与评分；默认仅展示测试文件但不参与平均分。",
+        ),
+    ] = False,
+) -> None:
+    output_path = output or root / "tmp" / "code_quality_report.html"
+    report = build_report(root, include_tests=include_tests)
+    written_path = write_report(report, output_path)
+
+    typer.echo(f"代码质量报告已生成: {written_path}")
+    typer.echo(
+        f"系统分数: {format_score(report.system.score)} | "
+        f"后端: {format_score(report.backend.score)} | "
+        f"前端: {format_score(report.frontend.score)}"
+    )
+
+
+if __name__ == "__main__":
+    app()

jeseki_code_quality-0.1.0/code_quality/report.py

@@ -0,0 +1,835 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Generate an offline HTML code quality report based on effective LOC."""
+
+from __future__ import annotations
+
+import ast
+import html
+import io
+import json
+import tokenize
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from statistics import mean
+from typing import Iterable, Literal
+
+
+GroupName = Literal["backend", "frontend"]
+ScoreStatus = Literal["healthy", "warning", "danger"]
+
+FRONTEND_EXTENSIONS = {".ts", ".tsx", ".js", ".jsx", ".css"}
+IGNORED_DIR_NAMES = {
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "data",
+    "dist",
+    "dist-ssr",
+    "logs",
+    "node_modules",
+    "venv",
+}
+
+
+@dataclass(frozen=True)
+class FileScore:
+    path: Path
+    relative_path: str
+    group: GroupName
+    effective_lines: int
+    score: float
+    status: ScoreStatus
+    included_in_score: bool
+    is_test: bool
+    warning: str | None = None
+
+
+@dataclass(frozen=True)
+class GroupScore:
+    name: GroupName | Literal["system"]
+    label: str
+    score: float | None
+    file_count: int
+    included_count: int
+    healthy_count: int
+    warning_count: int
+    danger_count: int
+    total_effective_lines: int
+
+
+@dataclass(frozen=True)
+class QualityReport:
+    root: Path
+    generated_at: datetime
+    include_tests: bool
+    files: list[FileScore]
+    backend: GroupScore
+    frontend: GroupScore
+    system: GroupScore
+
+
+def has_ignored_parent(path: Path) -> bool:
+    return any(part in IGNORED_DIR_NAMES or part.startswith("tmp") for part in path.parts)
+
+
+def is_test_file(path: Path) -> bool:
+    name = path.name
+    return (
+        "tests" in path.parts
+        or "__tests__" in path.parts
+        or name.startswith("test_")
+        or name.endswith("_test.py")
+        or ".test." in name
+        or ".spec." in name
+    )
+
+
+def python_docstring_lines(source: str) -> set[int]:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+
+    spans: set[int] = set()
+
+    for node in ast.walk(tree):
+        if not isinstance(
+            node, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+        ):
+            continue
+        body = getattr(node, "body", [])
+        if not body:
+            continue
+        first = body[0]
+        if not isinstance(first, ast.Expr):
+            continue
+        value = first.value
+        if not (isinstance(value, ast.Constant) and isinstance(value.value, str)):
+            continue
+        end_lineno = getattr(first, "end_lineno", first.lineno)
+        spans.update(range(first.lineno, end_lineno + 1))
+
+    return spans
+
+
+def count_python_effective_lines(path: Path) -> tuple[int, str | None]:
+    source = path.read_text(encoding="utf-8")
+    docstring_lines = python_docstring_lines(source)
+    lines: set[int] = set()
+    warning = None
+
+    try:
+        tokens = tokenize.generate_tokens(io.StringIO(source).readline)
+        for token in tokens:
+            if token.type in {
+                tokenize.COMMENT,
+                tokenize.DEDENT,
+                tokenize.ENCODING,
+                tokenize.ENDMARKER,
+                tokenize.INDENT,
+                tokenize.NL,
+                tokenize.NEWLINE,
+            }:
+                continue
+            start_line, _ = token.start
+            end_line, _ = token.end
+            for line_number in range(start_line, end_line + 1):
+                if line_number not in docstring_lines:
+                    lines.add(line_number)
+    except (SyntaxError, tokenize.TokenError, UnicodeDecodeError) as exc:
+        warning = f"Python tokenization fallback: {exc}"
+        return count_simple_effective_lines(source.splitlines()), warning
+
+    return len(lines), warning
+
+
+def count_simple_effective_lines(lines: Iterable[str]) -> int:
+    return sum(1 for line in lines if line.strip() and not line.lstrip().startswith("#"))
+
+
+def count_web_effective_lines(path: Path) -> tuple[int, str | None]:
+    source = path.read_text(encoding="utf-8")
+    line_has_code = [False for _ in source.splitlines()]
+    if source and source.endswith("\n"):
+        # splitlines() intentionally omits the final empty line.
+        pass
+
+    line_index = 0
+    in_block_comment = False
+    in_string: str | None = None
+    escaped = False
+    line_comment_enabled = path.suffix != ".css"
+    i = 0
+
+    while i < len(source):
+        char = source[i]
+        next_char = source[i + 1] if i + 1 < len(source) else ""
+
+        if char == "\n":
+            line_index += 1
+            if in_string != "`":
+                in_string = None
+                escaped = False
+            i += 1
+            continue
+
+        if line_index >= len(line_has_code):
+            line_has_code.append(False)
+
+        if in_block_comment:
+            if char == "*" and next_char == "/":
+                in_block_comment = False
+                i += 2
+            else:
+                i += 1
+            continue
+
+        if in_string:
+            if not char.isspace():
+                line_has_code[line_index] = True
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == in_string:
+                in_string = None
+            i += 1
+            continue
+
+        if char == "/" and next_char == "*":
+            in_block_comment = True
+            i += 2
+            continue
+
+        if line_comment_enabled and char == "/" and next_char == "/":
+            while i < len(source) and source[i] != "\n":
+                i += 1
+            continue
+
+        if char in {"'", '"', "`"}:
+            in_string = char
+            line_has_code[line_index] = True
+            i += 1
+            continue
+
+        if not char.isspace():
+            line_has_code[line_index] = True
+
+        i += 1
+
+    return sum(1 for has_code in line_has_code if has_code), None
+
+
+def linear_score(effective_lines: int, healthy_limit: int, danger_limit: int) -> float:
+    if effective_lines <= healthy_limit:
+        return 100
+    if effective_lines >= danger_limit:
+        return 0
+
+    score = (danger_limit - effective_lines) / (danger_limit - healthy_limit) * 100
+    return round(score, 1)
+
+
+def score_file(group: GroupName, effective_lines: int) -> tuple[float, ScoreStatus]:
+    if group == "backend":
+        score = linear_score(effective_lines, healthy_limit=300, danger_limit=600)
+    else:
+        score = linear_score(effective_lines, healthy_limit=600, danger_limit=1000)
+
+    if score >= 100:
+        return score, "healthy"
+    if score <= 0:
+        return score, "danger"
+    return score, "warning"
+
+
+def iter_source_files(root: Path) -> Iterable[tuple[Path, GroupName]]:
+    backend_root = root / "src" / "server"
+    frontend_root = root / "src" / "client"
+
+    if backend_root.exists():
+        for path in sorted(backend_root.rglob("*.py")):
+            if not has_ignored_parent(path.relative_to(root)):
+                yield path, "backend"
+
+    if frontend_root.exists():
+        for path in sorted(frontend_root.rglob("*")):
+            if (
+                path.is_file()
+                and path.suffix in FRONTEND_EXTENSIONS
+                and not has_ignored_parent(path.relative_to(root))
+            ):
+                yield path, "frontend"
+
+
+def build_file_score(root: Path, path: Path, group: GroupName, include_tests: bool) -> FileScore:
+    if group == "backend":
+        effective_lines, warning = count_python_effective_lines(path)
+    else:
+        effective_lines, warning = count_web_effective_lines(path)
+
+    score, status = score_file(group, effective_lines)
+    test_file = is_test_file(path.relative_to(root))
+
+    return FileScore(
+        path=path,
+        relative_path=path.relative_to(root).as_posix(),
+        group=group,
+        effective_lines=effective_lines,
+        score=score,
+        status=status,
+        included_in_score=include_tests or not test_file,
+        is_test=test_file,
+        warning=warning,
+    )
+
+
+def summarize_group(
+    name: GroupName | Literal["system"],
+    label: str,
+    files: list[FileScore],
+) -> GroupScore:
+    included = [file for file in files if file.included_in_score]
+    score = mean(file.score for file in included) if included else None
+    return GroupScore(
+        name=name,
+        label=label,
+        score=score,
+        file_count=len(files),
+        included_count=len(included),
+        healthy_count=sum(1 for file in included if file.status == "healthy"),
+        warning_count=sum(1 for file in included if file.status == "warning"),
+        danger_count=sum(1 for file in included if file.status == "danger"),
+        total_effective_lines=sum(file.effective_lines for file in included),
+    )
+
+
+def build_report(root: Path, include_tests: bool = False) -> QualityReport:
+    root = root.resolve()
+    files = [
+        build_file_score(root, path, group, include_tests)
+        for path, group in iter_source_files(root)
+    ]
+    backend_files = [file for file in files if file.group == "backend"]
+    frontend_files = [file for file in files if file.group == "frontend"]
+
+    return QualityReport(
+        root=root,
+        generated_at=datetime.now(),
+        include_tests=include_tests,
+        files=files,
+        backend=summarize_group("backend", "后端", backend_files),
+        frontend=summarize_group("frontend", "前端", frontend_files),
+        system=summarize_group("system", "系统", files),
+    )
+
+
+def format_score(score: float | int | None) -> str:
+    if score is None:
+        return "N/A"
+    if float(score).is_integer():
+        return str(int(score))
+    return f"{score:.1f}"
+
+
+def score_class(score: float | None) -> str:
+    if score is None:
+        return "na"
+    if score >= 90:
+        return "healthy"
+    if score >= 60:
+        return "warning"
+    return "danger"
+
+
+def group_to_dict(group: GroupScore) -> dict[str, object]:
+    return {
+        "score": None if group.score is None else round(group.score, 1),
+        "fileCount": group.file_count,
+        "includedCount": group.included_count,
+        "healthyCount": group.healthy_count,
+        "warningCount": group.warning_count,
+        "dangerCount": group.danger_count,
+        "totalEffectiveLines": group.total_effective_lines,
+    }
+
+
+def render_metric_card(group: GroupScore) -> str:
+    score = format_score(group.score)
+    css_class = score_class(group.score)
+    score_value = "null" if group.score is None else f"{group.score:.1f}"
+    return f"""
+        <section class="score-card {css_class}">
+          <div class="score-card__meta">
+            <span>{html.escape(group.label)}</span>
+            <strong>{group.included_count}</strong>
+          </div>
+          <div class="score-card__score" data-score="{score_value}">{score}</div>
+          <div class="score-card__bar"><span style="--target:{0 if group.score is None else group.score}%"></span></div>
+          <dl class="score-card__details">
+            <div><dt>健康</dt><dd>{group.healthy_count}</dd></div>
+            <div><dt>警告</dt><dd>{group.warning_count}</dd></div>
+            <div><dt>危险</dt><dd>{group.danger_count}</dd></div>
+            <div><dt>有效行</dt><dd>{group.total_effective_lines}</dd></div>
+          </dl>
+        </section>
+    """
+
+
+def render_file_rows(files: list[FileScore]) -> str:
+    rows = []
+    for file in sorted(files, key=lambda item: (-item.effective_lines, item.relative_path)):
+        rows.append(
+            f"""
+            <tr class="{file.status}{'' if file.included_in_score else ' excluded'}" data-status="{file.status}">
+              <td><code>{html.escape(file.relative_path)}</code></td>
+              <td>{'后端' if file.group == 'backend' else '前端'}</td>
+              <td>{file.effective_lines}</td>
+              <td>{format_score(file.score)}</td>
+              <td><span class="pill {file.status}">{status_label(file.status)}</span></td>
+              <td>{'计分' if file.included_in_score else '测试文件'}</td>
+            </tr>
+            """
+        )
+    return "\n".join(rows)
+
+
+def status_label(status: ScoreStatus) -> str:
+    return {"healthy": "健康", "warning": "警告", "danger": "危险"}[status]
+
+
+def render_top_files(files: list[FileScore]) -> str:
+    included = [file for file in files if file.included_in_score]
+    ranked_files = sorted(included, key=lambda item: (-item.effective_lines, item.relative_path))
+    if not ranked_files:
+        return '<p class="empty">没有可计分文件。</p>'
+
+    items = []
+    max_lines = max(file.effective_lines for file in ranked_files) or 1
+    for file in ranked_files:
+        width = round(file.effective_lines / max_lines * 100, 2)
+        items.append(
+            f"""
+            <li data-group="{file.group}">
+              <div>
+                <strong>{html.escape(file.relative_path)}</strong>
+                <span>{file.effective_lines} 行 · {format_score(file.score)} 分</span>
+              </div>
+              <div class="rank-bar {file.status}"><span style="--target:{width}%"></span></div>
+            </li>
+            """
+        )
+    return f"""
+      <ol class="top-list" data-top-list>{''.join(items)}</ol>
+      <p class="empty is-hidden" data-top-empty>没有匹配的文件。</p>
+    """
+
+
+def render_warnings(files: list[FileScore]) -> str:
+    warnings = [file for file in files if file.warning]
+    if not warnings:
+        return ""
+
+    items = "".join(
+        f"<li><code>{html.escape(file.relative_path)}</code>: {html.escape(file.warning or '')}</li>"
+        for file in warnings
+    )
+    return f"""
+      <section class="panel warnings">
+        <h2>解析警告</h2>
+        <ul>{items}</ul>
+      </section>
+    """
+
+
+def render_html(report: QualityReport) -> str:
+    report_json = json.dumps(
+        {
+            "system": group_to_dict(report.system),
+            "backend": group_to_dict(report.backend),
+            "frontend": group_to_dict(report.frontend),
+        },
+        ensure_ascii=False,
+    )
+    generated_at = report.generated_at.strftime("%Y-%m-%d %H:%M:%S")
+    test_policy = "参与评分" if report.include_tests else "默认排除"
+
+    return f"""<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>代码质量报告</title>
+  <style>
+    :root {{
+      color-scheme: light;
+      --bg: #f5f7fb;
+      --surface: #ffffff;
+      --surface-strong: #101828;
+      --muted: #667085;
+      --line: #d9e2ec;
+      --green: #169b62;
+      --green-soft: #e7f7ef;
+      --amber: #c97706;
+      --amber-soft: #fff4dc;
+      --red: #d33f49;
+      --red-soft: #ffeaec;
+      --blue: #276ef1;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }}
+    * {{ box-sizing: border-box; }}
+    body {{
+      margin: 0;
+      min-height: 100vh;
+      background:
+        linear-gradient(135deg, rgba(39, 110, 241, 0.08), transparent 28rem),
+        linear-gradient(315deg, rgba(22, 155, 98, 0.08), transparent 30rem),
+        var(--bg);
+      color: #172033;
+    }}
+    main {{
+      width: min(1440px, calc(100% - 48px));
+      margin: 0 auto;
+      padding: 32px 0 48px;
+    }}
+    header {{
+      display: grid;
+      grid-template-columns: 1fr auto;
+      gap: 24px;
+      align-items: end;
+      margin-bottom: 24px;
+    }}
+    h1, h2 {{ margin: 0; letter-spacing: 0; }}
+    h1 {{ font-size: 32px; line-height: 1.15; color: var(--surface-strong); }}
+    h2 {{ font-size: 18px; }}
+    .subtitle {{ margin: 10px 0 0; color: var(--muted); max-width: 820px; line-height: 1.7; }}
+    .meta {{
+      display: grid;
+      gap: 8px;
+      min-width: 260px;
+      padding: 14px 16px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: rgba(255,255,255,0.76);
+    }}
+    .meta span {{ color: var(--muted); font-size: 13px; }}
+    .meta strong {{ font-size: 14px; color: #24304a; }}
+    .score-grid {{
+      display: grid;
+      grid-template-columns: 1.1fr 1fr 1fr;
+      gap: 16px;
+      margin-bottom: 16px;
+    }}
+    .score-card, .panel {{
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: rgba(255,255,255,0.9);
+      box-shadow: 0 18px 40px rgba(16, 24, 40, 0.08);
+    }}
+    .score-card {{ padding: 20px; overflow: hidden; }}
+    .score-card__meta {{
+      display: flex;
+      justify-content: space-between;
+      gap: 16px;
+      color: var(--muted);
+      font-size: 14px;
+    }}
+    .score-card__meta strong {{ color: #24304a; }}
+    .score-card__score {{
+      margin-top: 12px;
+      font-size: 56px;
+      line-height: 1;
+      font-weight: 760;
+      color: var(--surface-strong);
+    }}
+    .score-card.healthy .score-card__score {{ color: var(--green); }}
+    .score-card.warning .score-card__score {{ color: var(--amber); }}
+    .score-card.danger .score-card__score {{ color: var(--red); }}
+    .score-card__bar, .rank-bar {{
+      height: 9px;
+      margin-top: 16px;
+      overflow: hidden;
+      border-radius: 999px;
+      background: #edf1f7;
+    }}
+    .score-card__bar span, .rank-bar span {{
+      display: block;
+      width: var(--target);
+      height: 100%;
+      transform-origin: left;
+      animation: grow 880ms cubic-bezier(.2,.8,.2,1) both;
+    }}
+    .score-card.healthy .score-card__bar span, .rank-bar.healthy span {{ background: var(--green); }}
+    .score-card.warning .score-card__bar span, .rank-bar.warning span {{ background: var(--amber); }}
+    .score-card.danger .score-card__bar span, .rank-bar.danger span {{ background: var(--red); }}
+    .score-card.na .score-card__bar span {{ background: var(--muted); }}
+    .score-card__details {{
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 10px;
+      margin: 18px 0 0;
+    }}
+    .score-card__details div {{
+      min-width: 0;
+      padding: 10px;
+      border-radius: 8px;
+      background: #f7f9fc;
+    }}
+    dt {{ color: var(--muted); font-size: 12px; }}
+    dd {{ margin: 3px 0 0; font-weight: 720; color: #24304a; }}
+    .content-grid {{
+      display: grid;
+      grid-template-columns: 0.92fr 1.08fr;
+      gap: 16px;
+      align-items: start;
+    }}
+    .panel {{ padding: 18px; }}
+    .panel__header {{
+      display: flex;
+      justify-content: space-between;
+      gap: 16px;
+      align-items: center;
+      margin-bottom: 14px;
+    }}
+    .panel h2 {{ margin-bottom: 0; }}
+    .segmented {{
+      display: inline-flex;
+      flex-wrap: wrap;
+      gap: 4px;
+      padding: 4px;
+      border: 1px solid #dfe7f0;
+      border-radius: 8px;
+      background: #f7f9fc;
+    }}
+    .segmented button {{
+      min-height: 30px;
+      border: 0;
+      border-radius: 6px;
+      padding: 5px 10px;
+      background: transparent;
+      color: var(--muted);
+      cursor: pointer;
+      font: inherit;
+      font-size: 12px;
+      font-weight: 720;
+    }}
+    .segmented button:hover {{ color: #24304a; background: #edf2f8; }}
+    .segmented button.active {{
+      color: #ffffff;
+      background: var(--surface-strong);
+      box-shadow: 0 6px 14px rgba(16, 24, 40, 0.16);
+    }}
+    .top-list {{
+      display: grid;
+      gap: 13px;
+      margin: 0;
+      padding: 0;
+      list-style: none;
+    }}
+    .top-list li {{
+      display: grid;
+      gap: 8px;
+      padding: 12px;
+      border: 1px solid #e8edf4;
+      border-radius: 8px;
+      background: #fbfcfe;
+    }}
+    .top-list div:first-child {{
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      gap: 12px;
+      align-items: center;
+    }}
+    .top-list strong {{
+      min-width: 0;
+      overflow-wrap: anywhere;
+      font-size: 13px;
+    }}
+    .top-list span {{ color: var(--muted); font-size: 12px; white-space: nowrap; }}
+    .table-wrap {{ overflow-x: auto; border: 1px solid var(--line); border-radius: 8px; }}
+    table {{ width: 100%; border-collapse: collapse; min-width: 860px; background: #fff; }}
+    th, td {{ padding: 11px 12px; border-bottom: 1px solid #edf1f7; text-align: left; font-size: 13px; }}
+    th {{ position: sticky; top: 0; background: #f7f9fc; color: #344054; font-weight: 720; }}
+    td:nth-child(3), td:nth-child(4) {{ font-variant-numeric: tabular-nums; }}
+    tr:last-child td {{ border-bottom: 0; }}
+    tr.warning {{ background: var(--amber-soft); }}
+    tr.danger {{ background: var(--red-soft); }}
+    tr.excluded {{ opacity: .58; }}
+    code {{
+      color: #18243a;
+      font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+      overflow-wrap: anywhere;
+    }}
+    .pill {{
+      display: inline-flex;
+      min-width: 44px;
+      justify-content: center;
+      border-radius: 999px;
+      padding: 3px 8px;
+      font-size: 12px;
+      font-weight: 700;
+    }}
+    .pill.healthy {{ background: var(--green-soft); color: var(--green); }}
+    .pill.warning {{ background: #ffe8b3; color: var(--amber); }}
+    .pill.danger {{ background: #ffd6da; color: var(--red); }}
+    .warnings {{ margin-top: 16px; }}
+    .warnings ul {{ margin: 0; padding-left: 18px; color: var(--muted); }}
+    .empty {{ color: var(--muted); margin: 0; }}
+    .is-hidden {{ display: none !important; }}
+    @keyframes grow {{
+      from {{ transform: scaleX(0); }}
+      to {{ transform: scaleX(1); }}
+    }}
+    @media (max-width: 960px) {{
+      main {{ width: min(100% - 28px, 1440px); padding-top: 22px; }}
+      header, .content-grid, .score-grid {{ grid-template-columns: 1fr; }}
+      .meta {{ min-width: 0; }}
+      .score-card__score {{ font-size: 46px; }}
+      .panel__header {{ align-items: flex-start; flex-direction: column; }}
+    }}
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <div>
+        <h1>代码质量报告</h1>
+        <p class="subtitle">基于有效代码行数评分：后端 300 行以内满分，300 到 600 行线性降至 0 分；前端 600 行以内满分，600 到 1000 行线性降至 0 分。系统分数按所有参与评分文件平均。</p>
+      </div>
+      <div class="meta">
+        <span>生成时间</span><strong>{html.escape(generated_at)}</strong>
+        <span>项目根目录</span><strong>{html.escape(str(report.root))}</strong>
+        <span>测试文件</span><strong>{test_policy}</strong>
+      </div>
+    </header>
+
+    <section class="score-grid">
+      {render_metric_card(report.system)}
+      {render_metric_card(report.backend)}
+      {render_metric_card(report.frontend)}
+    </section>
+
+    <section class="content-grid">
+      <section class="panel">
+        <div class="panel__header">
+          <h2>最大文件排行</h2>
+          <div class="segmented" data-filter-group="top">
+            <button type="button" class="active" data-filter-value="all">全部</button>
+            <button type="button" data-filter-value="backend">后端</button>
+            <button type="button" data-filter-value="frontend">前端</button>
+          </div>
+        </div>
+        {render_top_files(report.files)}
+      </section>
+      <section class="panel">
+        <div class="panel__header">
+          <h2>文件明细</h2>
+          <div class="segmented" data-filter-group="details">
+            <button type="button" class="active" data-filter-value="all">全部</button>
+            <button type="button" data-filter-value="healthy">健康</button>
+            <button type="button" data-filter-value="warning">警告</button>
+            <button type="button" data-filter-value="danger">危险</button>
+          </div>
+        </div>
+        <div class="table-wrap">
+          <table>
+            <thead>
+              <tr>
+                <th>文件</th>
+                <th>分组</th>
+                <th>有效行</th>
+                <th>分数</th>
+                <th>状态</th>
+                <th>范围</th>
+              </tr>
+            </thead>
+            <tbody>{render_file_rows(report.files)}</tbody>
+          </table>
+        </div>
+        <p class="empty is-hidden" data-detail-empty>没有匹配的文件。</p>
+      </section>
+    </section>
+
+    {render_warnings(report.files)}
+  </main>
+  <script type="application/json" id="quality-data">{html.escape(report_json)}</script>
+  <script>
+    const setActiveButton = (button) => {{
+      const group = button.closest('[data-filter-group]');
+      for (const item of group.querySelectorAll('button')) item.classList.remove('active');
+      button.classList.add('active');
+    }};
+
+    const applyTopFilter = (value) => {{
+      const list = document.querySelector('[data-top-list]');
+      const empty = document.querySelector('[data-top-empty]');
+      if (!list) return;
+      let shown = 0;
+      for (const item of list.querySelectorAll('li')) {{
+        const matchesGroup = value === 'all' || item.dataset.group === value;
+        const visible = matchesGroup && shown < 8;
+        item.classList.toggle('is-hidden', !visible);
+        if (visible) shown += 1;
+      }}
+      if (empty) empty.classList.toggle('is-hidden', shown > 0);
+    }};
+
+    const applyDetailFilter = (value) => {{
+      let shown = 0;
+      for (const row of document.querySelectorAll('tbody tr[data-status]')) {{
+        const visible = value === 'all' || row.dataset.status === value;
+        row.classList.toggle('is-hidden', !visible);
+        if (visible) shown += 1;
+      }}
+      const empty = document.querySelector('[data-detail-empty]');
+      if (empty) empty.classList.toggle('is-hidden', shown > 0);
+    }};
+
+    for (const button of document.querySelectorAll('[data-filter-group="top"] button')) {{
+      button.addEventListener('click', () => {{
+        setActiveButton(button);
+        applyTopFilter(button.dataset.filterValue);
+      }});
+    }}
+
+    for (const button of document.querySelectorAll('[data-filter-group="details"] button')) {{
+      button.addEventListener('click', () => {{
+        setActiveButton(button);
+        applyDetailFilter(button.dataset.filterValue);
+      }});
+    }}
+
+    applyTopFilter('all');
+    applyDetailFilter('all');
+
+    for (const el of document.querySelectorAll('[data-score]')) {{
+      const raw = el.dataset.score;
+      if (raw === 'null') continue;
+      const target = Number(raw);
+      const duration = 760;
+      const startedAt = performance.now();
+      const tick = (now) => {{
+        const progress = Math.min((now - startedAt) / duration, 1);
+        const eased = 1 - Math.pow(1 - progress, 3);
+        const value = target * eased;
+        el.textContent = Number.isInteger(target) ? String(Math.round(value)) : value.toFixed(1);
+        if (progress < 1) requestAnimationFrame(tick);
+        else el.textContent = Number.isInteger(target) ? String(target) : target.toFixed(1);
+      }};
+      requestAnimationFrame(tick);
+    }}
+  </script>
+</body>
+</html>
+"""
+
+
+def write_report(report: QualityReport, output_path: Path) -> Path:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(render_html(report), encoding="utf-8")
+    return output_path

jeseki_code_quality-0.1.0/main.py

@@ -0,0 +1,5 @@
+from code_quality.cli import app
+
+
+if __name__ == "__main__":
+    app()

jeseki_code_quality-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "jeseki-code-quality"
+version = "0.1.0"
+description = "Generate an offline HTML code quality report."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "typer>=0.26.8",
+]
+
+[project.scripts]
+code-quality = "code_quality.cli:app"
+cq = "code_quality.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["code_quality"]

jeseki_code_quality-0.1.0/uv.lock

@@ -0,0 +1,99 @@
+version = 1
+revision = 3
+requires-python = ">=3.13"
+
+[[package]]
+name = "annotated-doc"
+version = "0.0.4"
+source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4" }
+wheels = [
+    { url = "https://mirrors.aliyun.com/pypi/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44" }
+wheels = [
+    { url = "https://mirrors.aliyun.com/pypi/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6" },
+]
+
+[[package]]
+name = "jeseki-code-quality"
+version = "0.1.0"
+source = { editable = "." }
+dependencies = [
+    { name = "typer" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "typer", specifier = ">=0.26.8" }]
+
+[[package]]
+name = "markdown-it-py"
+version = "4.2.0"
+source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49" }
+wheels = [
+    { url = "https://mirrors.aliyun.com/pypi/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a" },
+]
+
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba" }
+wheels = [
+    { url = "https://mirrors.aliyun.com/pypi/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.20.0"
+source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f" }
+wheels = [
+    { url = "https://mirrors.aliyun.com/pypi/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176" },
+]
+
+[[package]]
+name = "rich"
+version = "15.0.0"
+source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
+dependencies = [
+    { name = "markdown-it-py" },
+    { name = "pygments" },
+]
+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36" }
+wheels = [
+    { url = "https://mirrors.aliyun.com/pypi/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb" },
+]
+
+[[package]]
+name = "shellingham"
+version = "1.5.4"
+source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de" }
+wheels = [
+    { url = "https://mirrors.aliyun.com/pypi/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686" },
+]
+
+[[package]]
+name = "typer"
+version = "0.26.8"
+source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "rich" },
+    { name = "shellingham" },
+]
+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/7c/f7/68adc395201b20b872d68e975386832e8005ffeacedd43a1d837a32815be/typer-0.26.8.tar.gz", hash = "sha256:c244a6bd558886fe3f8780efb6bdd28bb9aff005a94eedebaa5cb32926fe2f7e" }
+wheels = [
+    { url = "https://mirrors.aliyun.com/pypi/packages/80/87/b9fd69c92c6102a066e1b86a35243f53e70bd4c709f2a26d9f4fee4f4dc0/typer-0.26.8-py3-none-any.whl", hash = "sha256:3512ca79ac5c11113414b36e80281b872884477722440691c89d1112e321a49c" },
+]