labull-framework 0.1.26__tar.gz → 0.1.28__tar.gz

{labull_framework-0.1.26/labull_framework.egg-info → labull_framework-0.1.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 0.1.26
+Version: 0.1.28
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT

{labull_framework-0.1.26 → labull_framework-0.1.28}/labull_framework/canvas/data.py

@@ -456,9 +456,12 @@ def _enums_of(model: Any) -> dict[str, dict[str, Any]]:
 def payload() -> dict[str, Any]:
     """画布整包：当前形状 + 与 git 那份比出来的三态 + 头部那行 git 信息 + 布局。
 
+    🔴 **基线是"算出来的"**（开发者明确要的）：拿基线那一版提交里的 `models.py` 用 `ast`
+       解析出形状，与进程内这一份做差 —— **不需要任何人导出 / 提交一份平行产物**。
+       口径与兜底见 `gitinfo.baseline_tables()`；"哪一种来源"单独给一列 `baselineSource`。
     🔴 **被删掉的表也要带上**（`deletedTables`）：不然页面上只有"删除 N"这个数字，
        看不到删掉的是哪张、原来有哪些列 —— 那正是重构时最需要看的东西。
-       它们从基线那份契约里取，列结构与当前形状同形（老契约里没有的新字段按缺省补）。
+       它们从基线那份形状里取，列结构与当前形状同形（老契约里没有的新字段按缺省补）。
     """
     from . import gitinfo
 
@@ -487,6 +490,10 @@ def payload() -> dict[str, Any]:
         'deletedRelations': _deleted_relations(baseline, relation_diff),
         'git': gitinfo.head(),
         'baseline': 'none' if baseline is None else 'present',
+        # 🔴 **这份基线是怎么来的**（`code` = 从那个提交的源码算的 / `contract` = 提交里那份
+        #    JSON / `none` = 没有可比基线）：必须写到页面上 —— 人得能分清
+        #    "这里全清"是"真没改"还是"基线没取到"（见 `gitinfo.baseline_source()`）。
+        'baselineSource': gitinfo.baseline_source(),
         'layout': read_layout(),
     }
 
@@ -670,11 +677,12 @@ def _field_diff(
 #    于是"模型里删了一个字段"这件事保存时不报、体检全绿，一路到某个请求才 500。
 #    而"哪几个字段是这次被删掉的"画布那侧**早就算出来了**（`_field_diff`）—— 把它交给深检，
 #    一次纯文本比对就能把那条引用揪出来（不需要任何类型推断、误报率极低）。
-# 🔴 **快照按"仓库 + 提交"缓存**：`git` 一次要起一个进程（`gitinfo._run` 自己也带 5 秒超时），
-#    而全量体检会对每个块各问一次。缓存键是 `(仓库根, HEAD, 契约文件的状态)`，
-#    所以"换个项目 / 又提交了一版 / 契约文件被重新导出"都会当场失效（不会拿旧集合去比）。
-# 🔴 **一律不抛**：没有 git / 不是仓库 / 契约坏了 ⇒ 空快照（`deepcheck` 那一侧因此**一条都不报**）。
-#    基线是可选的加速度，不是判据的前置条件。
+# 🔴 **快照按"仓库 + 提交"缓存**：算一份基线要起两个 git 进程（`gitinfo._run` 自己也带 5 秒超时），
+#    而全量体检会对每个块各问一次。缓存键是 `(仓库根, HEAD, 契约文件的状态)` ——
+#    换个项目 / 又提交了一版都会当场失效；`gitinfo` 那一层自己还有一份更细的缓存
+#    （键里带"基线那一版 + 源码状态"），所以这里不必再管"基线换没换"。
+# 🔴 **一律不抛**：没有 git / 不是仓库 / 那个提交里读不出源码 ⇒ 空快照
+#    （`deepcheck` 那一侧因此**一条都不报**）。基线是可选的加速度，不是判据的前置条件。
 
 #: 快照缓存：`(仓库根, HEAD, 契约状态) → ({模型名: {deleted, renamed}}, 契约文件状态)`。
 _BASELINE_CACHE: dict[tuple[str, str, float], tuple[dict[str, dict[str, Any]], float]] = {}
@@ -733,7 +741,7 @@ def _dead_models(diff: dict[str, dict[str, Any]]) -> dict[str, dict[str, Any]]:
 def _baseline_snapshot() -> dict[str, dict[str, Any]]:
     """这一次的"死字段"快照：`{模型名: {'deleted', 'renamed'}}`（拿不到就回空）。
 
-    :return: 空字典 = 没有可比基线（不是仓库 / 提交里没有契约 / 契约坏了 / 没有 Django）。
+    :return: 空字典 = 没有可比基线（不是仓库 / 那个提交里读不出模型源码 / 没有 Django）。
     """
     from . import gitinfo
 
@@ -753,7 +761,7 @@ def _baseline_snapshot() -> dict[str, dict[str, Any]]:
     if hit is not None and hit[1] == state:
         return hit[0]
     # 🔴 **两个入参的方向**（这里写错过一次，而它不报错、只是"一条都不报"）：
-    #    第一份是**契约那一版**（= 基线），第二份是**现在这份形状**（`shape()`）。
+    #    第一份是**基线那一版**（从那个提交的源码算出来的），第二份是**现在这份形状**（`shape()`）。
     #    写成 `_field_diff(baseline, _columns_for_diff(baseline))` 就是"拿基线跟自己比" ⇒
     #    恒为空 ⇒ 整条判据静默失效（症状与"没有基线"一模一样，所以最难发现）。
     baseline = gitinfo.baseline_tables()

labull_framework-0.1.28/labull_framework/canvas/gitinfo.py

@@ -0,0 +1,521 @@
+"""画布要的 git 那一半：当前提交、那一行备注、以及**上一版**的模型形状。
+
+🔴 **上一版是"算出来的"，不是"存出来的"**（开发者明确要的："基线由代码本身推出来，
+   而不是维护一个平行产物"）：
+   老做法要人跑 `manage.py labull_contract --out .labull/contract.json` 再提交，
+   画布去 `git show` 那份 JSON。代价是一份**必须人记得更新**的平行产物 ——
+   忘了跑 / 忘了提交 / 模型改了而 JSON 没重导，画布要么满屏"新增"、要么一点差异都没有
+   （这个仓库就是这样：那份 JSON 还停在初始提交，30 张表里只有 3 张）。
+   现在改成分两步读**那个提交里的源码**（`canvas/shape_ast.py` 用 `ast` 解析）：
+   上一版长什么样，本来就在 git 里。（原话：*"上一版的模型形状本来就在 git 里"*。）
+
+🔴 **比的是 `parent`，不是 `HEAD`**：画布要回答的是"**你这次改了什么**" ——
+   一个干净的 `git commit` 之后，`HEAD` 里那份形状与工作区**逐字相同**，画布会全清；
+   而人真正想看的是"我上一笔提交动了哪些表"。两种口径各有用处，所以
+   `LABULL_BASELINE_REV` 可以切（`head` = 只看没提交的改动）。
+   ⚠️ 只有一个提交的项目 `parent` 不存在 ⇒ 退回 `HEAD`（新版全是新增，这是**正常状态**）。
+🔴 **不是仓库 / 那个提交里读不出源码 ⇒ 回 `None`**（"没有可比基线"是**正常状态**，不是错误）。
+🔴 这一层的输出只影响"差异"那几列；**当前形状完全不依赖 git**（它读的是进程内的模型元数据）。
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from django.conf import settings
+
+#: 模型形状 JSON 的落点（相对项目根）。它由 `manage.py labull_contract --out` 写出，**可选**：
+#: 现在它只是**兜底**（源码解析认不出来时才用）—— 正常情况下画布不需要它存在。
+DEFAULT_CONTRACT_PATH = '.labull/contract.json'
+
+#: git 单次调用的超时（秒）：它是画布页面的一个同步依赖，卡住就等于页面卡住。
+_TIMEOUT = 5
+
+#: 从**基线那一版**里要读的那几个文件名（每个 app 一份 `models.py` + 它的 `apps.py`）。
+#: ⚠️ `settings.py` **不在这里**：它只在"当前这一份"里读（见 `_project_settings()`）——
+#:    `INSTALLED_APPS` / `AUTH_USER_MODEL` 不参与差异判据，读提交里那一份反而会把
+#:    "某个 app 刚好叫 settings"这种形状搅进来。
+#: ⚠️ 一个 app 里模型分成多个文件的（`models/` 是个包）**今天不支持**：那种情况下
+#:    `git show <rev>:<app>/models.py` 取不到东西 ⇒ 这个 app 从基线里缺席（会报成"整张表新增"）。
+#:    要支持它就得多读一棵子树 + 认 `models/__init__.py` 的 re-export，那是另一件事。
+_SOURCE_FILES = ('models.py', 'apps.py')
+
+#: 解析结果的记忆（键是"仓库 + 那一版 + 输入的状态"，见 `_revision_tables()`）。
+#: ⚠️ **必须缓存**：画布每次请求都要这份基线，而算一次要起两个 git 进程。
+_DERIVED_CACHE: dict[tuple[str, str, str], list[dict[str, Any]] | None] = {}
+
+#: 那几个"一次请求里要问好几遍"的 git 事实（仓库根 / 当前提交 / 基线提交）。
+#:
+#: 🔴 为什么连它们也要缓存：**在 Windows 上起一个 git 进程大约 40ms**（实测），
+#:    而一份基线要问三次（仓库根、HEAD、HEAD~1）⇒ 光"问路"就 120ms。
+#:    缓存了"算出来的表"却没缓存"问路"的话，第二次请求照样要起三个进程 ——
+#:    那正是"缓存最没用的写法"（真量过：冷 92ms / 热 96ms，等于没缓存）。
+#: ⚠️ 失效靠 `_sources_state()`（项目 `settings.py` + 本模块与 `shape_ast.py` 的 mtime）：
+#:    换了仓库 / 新提交 / 改了这一层的代码都会当场重算，见 `_memo()`。
+_MEMO: dict[str, Any] = {'state': None, 'values': {}}
+
+
+def _run(args: list[str], cwd: Path) -> str | None:
+    """跑一条只读的 git 命令，返回 stdout（失败一律回 `None`）。
+
+    🔴 **必须显式 `encoding='utf-8'`**：`text=True` 在 Windows 上默认用**系统 ANSI 代码页（GBK）**
+       解码，而提交说明是中文 UTF-8 ⇒ 解码线程抛 `UnicodeDecodeError`，`stdout` 变成 `None`，
+       于是下一句 `.strip()` 报 `'NoneType' object has no attribute 'strip'` ——
+       症状是 `/canvas` 直接 500，而真因跟"模型"一个字都没关系（真踩过）。
+       `errors='replace'` 是第二道保险：真碰上编码诡异的输出，也宁可显示成问号，不要让整页崩掉。
+    """
+    try:
+        done = subprocess.run(
+            ['git', *args],
+            cwd=str(cwd),
+            capture_output=True,
+            encoding='utf-8',
+            errors='replace',
+            timeout=_TIMEOUT,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        # git 没装 / 不是仓库 / 超时：都是"这一层拿不到信息"，不是错误（差异那几列留空即可）。
+        return None
+    output = done.stdout or ''
+    return output.strip() if done.returncode == 0 else None
+
+
+def _memo(name: str, compute: Any) -> Any:
+    """把一次"要起 git 进程"的结论记下来（失效条件见 `_MEMO` 与 `_sources_state()`）。
+
+    ⚠️ `compute` 只有真的算的时候才调 —— 命中的路径上**一个进程都不起**。
+    """
+    state = _sources_state()
+    if _MEMO['state'] != state:
+        _MEMO['state'] = state
+        _MEMO['values'] = {}
+    values = _MEMO['values']
+    if name not in values:
+        values[name] = compute()
+    return values[name]
+
+
+def _root() -> Path | None:
+    """项目根（`settings.BASE_DIR`）—— 那条"相对项目"的契约路径是相对它算的。"""
+    base = getattr(settings, 'BASE_DIR', None)
+    return Path(base) if base else None
+
+
+def _repo_root() -> Path | None:
+    """**git 仓库根**（`git rev-parse --show-toplevel`）。
+
+    🔴 为什么不能拿 `BASE_DIR` 当仓库根：`BASE_DIR` 是**项目**根（示例里是 `backend/example`），
+       而 `git show HEAD:<路径>` 里的路径是**相对仓库根**的。仓库根只要在更上面一层
+       （这个仓库就是：`BASE_DIR` 在 `backend/example`，仓库根在它上两层），
+       那条命令就会失败、`baseline_tables()` 永远回 `None` ——
+       症状是画布永远显示"没有可比基线"，而"提交过契约"这件事一点错都不报（真踩过）。
+    ⚠️ 结果按 `_sources_state()` 记忆（见 `_MEMO`）：它每次请求都要被问两三遍。
+    """
+
+    def compute() -> Path | None:
+        base = _root()
+        if base is None:
+            return None
+        top = _run(['rev-parse', '--show-toplevel'], base)
+        return Path(top) if top else None
+
+    return _memo('repo_root', compute)
+
+
+def contract_path() -> str:
+    """那份 JSON 的落点（项目可用 `LABULL_CONTRACT_PATH` 覆盖）。"""
+    from .. import env
+
+    return env.read_env('LABULL_CONTRACT_PATH') or DEFAULT_CONTRACT_PATH
+
+
+def baseline_rev() -> str | None:
+    """**拿什么当"上一版"**：`HEAD` / `HEAD~1` / 项目自己指定的一个提交号。
+
+    默认 `LABULL_BASELINE_REV` 是**空**：那时自动取 `HEAD~1`（"上一次提交改了什么"），
+    没有父提交就退回 `HEAD`（第一个提交 ⇒ 全部算新增，这是正常状态）。
+    两个特殊值：`head` = 只看**还没提交**的那些改动；`off` / `none` = 不做差异。
+    ⚠️ 结果按 `_sources_state()` 记忆（见 `_MEMO`）：它每次请求都要被问两三遍。
+    """
+
+    def compute() -> str | None:
+        from .. import env
+
+        repo = _repo_root()
+        if repo is None:
+            return None
+        head = _run(['rev-parse', 'HEAD'], repo)
+        if not head:
+            return None
+        want = (env.read_env('LABULL_BASELINE_REV') or '').strip()
+        low = want.lower()
+        if low in ('off', 'none', 'no'):
+            return None
+        if not want:
+            parent = _run(['rev-parse', 'HEAD~1'], repo)
+            return (parent or head)[:12]
+        if low == 'head':
+            return head[:12]
+        resolved = _run(['rev-parse', '--verify', f'{want}^{{commit}}'], repo)
+        return (resolved or '')[:12] or None
+
+    return _memo('baseline_rev', compute)
+
+
+def baseline_source() -> str:
+    """这一版基线是**怎么来的**：`code`（从源码算的）/ `contract`（提交里那份 JSON）/ `none`。
+
+    画布头部那一行按它说人话 —— "这份差异是哪来的"必须写在页面上，
+    否则人没法判断"为什么这里全清"是"真没改"还是"基线没取到"。
+    """
+    if baseline_rev() is None:
+        return 'none'
+    if _revision_tables() is not None:
+        return 'code'
+    return 'contract' if contract_tables() is not None else 'none'
+
+
+def head() -> dict[str, Any] | None:
+    """头部那一行：提交号 / 备注 / 有没有父提交 / 这次改了哪些文件。
+
+    备注优先取中文（`备注：` 那一行，否则含中文的首行）—— 中文项目里英文的 commit 标题没什么信息量。
+    """
+    root = _root()
+    if root is None:
+        return None
+    full = _run(['rev-parse', 'HEAD'], root)
+    if not full:
+        return None
+    message = _run(['log', '-1', '--pretty=format:%s'], root) or ''
+    parent = _run(['rev-parse', f'{full}~1'], root)
+    files = (_run(['diff', '--name-only', parent, full], root) or '').splitlines() if parent else []
+    # 🔴 `baseRev` 是**基线那一版**（不是"父提交"）：页面要能说清"跟哪一版在比"。
+    return {
+        'hash': full[:8],
+        'msg': _chinese_remark(message),
+        'hasParent': bool(parent),
+        'files': [line.strip() for line in files if line.strip()],
+        'baseRev': (baseline_rev() or '')[:12],
+    }
+
+
+def _chinese_remark(message: str) -> str:
+    for line in message.splitlines():
+        head, sep, tail = line.strip().partition('：')
+        if sep and head.lower() in ('备注', 'remark') and tail.strip():
+            return tail.strip()
+    for line in message.splitlines():
+        text = line.strip()
+        if text and any('\u4e00' <= ch <= '\u9fa5' for ch in text):
+            return text
+    return message.splitlines()[0].strip() if message else ''
+
+
+def baseline_tables() -> list[dict[str, Any]] | None:
+    """**上一版**的表定义（从 git 的那个提交里**算**出来）。
+
+    三种返回值的语义不同，别混：`None` = 没有可比基线（不是仓库 / 那个提交里读不到源码 /
+    源码写坏了）；`[]` = 有基线，但基线里确实一张表都没有；有内容 = 正常逐表比。
+
+    🔴 两条来源，**顺序有意义**：
+       ① **从那个提交的源码算**（`shape_ast`）—— 它是"上一版的模型形状"的真相，
+          而且不需要任何人记得维护什么文件；
+       ② 退到提交里那份 `contract.json`（老做法）：只在①读不出来时用
+          （源码语法坏掉 / 模型写在 `models/` 包里这种今天不支持的形状）。
+    ⚠️ 有一类**已知的**假差异（装了 `django.contrib.admin` 时用户表上那条 `logentry`），
+       见 `_known_limitation()` —— 那是"从源码算"这条路的固有边界，不是可以顺手滤掉的噪声
+       （试过滤，越滤越糟）。
+    """
+    derived = _revision_tables()
+    return derived if derived is not None else contract_tables()
+
+
+def _known_limitation() -> str:
+    """这一层**已知**的一类假差异（写给下一个人看，别再去踩）。
+
+    装过 `django.contrib.admin` 的项目里，`django.contrib.admin.LogEntry` 有一条外键指向**你的**
+    用户表 ⇒ `_meta.get_fields()` 会在你的用户表上给出 `logentry` 这条反向关联，
+    而它的正向声明在 Django 自己的源码里（这个项目的 git 里一行都没有）——
+    所以"从源码算基线"这条路**永远算不出它**，画布上会常年挂着一条"新增的关联"。
+    ⚠️ 试过在基线里把它剔掉（两条路都试过：靠"差分反推来源"、靠 `origin` 标记）：
+       **越剔越糟** —— 剔掉之后基线里没有、现在这一份里有，差异恰好从"没多出来"变成"新增"。
+       要根治只能"让基线多知道一条 Django 自己那边的关联"，那是另一件事（读 Django 的源码 +
+       把它的正向声明也算进来）。今天只留这一条说明。
+    """
+    return 'labull_user.logentry（装了 admin 时）'
+
+
+def contract_tables() -> list[dict[str, Any]] | None:
+    """提交里那份 `contract.json` 的表定义（**兜底**来源；没有就是 `None`）。"""
+    repo = _repo_root()
+    if repo is None:
+        return None
+    relative = _repo_relative_contract(repo)
+    if relative is None:
+        return None
+    revision = baseline_rev()
+    if revision is None:
+        return None
+    text = _run(['show', f'{revision}:{relative}'], repo)
+    if not text:
+        return None
+    try:
+        parsed = json.loads(text)
+    except ValueError:
+        # 提交里那份坏了（手改过 / 写到一半就提交了）⇒ 当"没有基线"，
+        # 而不是拿半份数据去比（那会报出一堆假的新增 / 删除）。
+        return None
+    tables = parsed.get('tables') if isinstance(parsed, dict) else None
+    return tables if isinstance(tables, list) else None
+
+
+def _revision_tables() -> list[dict[str, Any]] | None:
+    """从基线那一版的**源码**算出来的表定义（算不出来回 `None`）。
+
+    🔴 **缓存键是"仓库 + 那一版 + 输入的状态"**（与 `data._BASELINE_CACHE` 同一套形状）：
+       算一次要起 2 个 git 进程（`ls-tree` + 批量 `cat-file`），而画布每次请求都要它、
+       全量体检还会对每个块各问一次。**先查缓存再读 git** 是这一层的全部意义所在
+       （反过来的话，每次请求都白起一轮进程 —— 那正是"缓存"最没用的写法）。
+    ⚠️ 状态取的是 `_sources_state()`（项目 `settings.py` + 这一层自己的 mtime），
+       不是"源码的 blob 号"：**源码在 git 里，由提交号管**；而"换了仓库 / 改了这一层的代码"
+       由状态管（少了后一项，开发这一层时会量到已经修掉的旧结果）。
+    """
+    repo = _repo_root()
+    revision = baseline_rev()
+    if repo is None or revision is None:
+        return None
+    state = _sources_state()
+    key = (str(repo), revision, f'{state:.6f}')
+    cached = _DERIVED_CACHE.get(key)
+    if cached is not None or key in _DERIVED_CACHE:
+        return cached
+    files = _revision_sources(repo, revision)
+    apps = _group_apps(files) if files else {}
+    tables: list[dict[str, Any]] | None = None
+    if apps:
+        try:
+            from . import shape_ast
+
+            tables = shape_ast.derive(apps) or None
+        except Exception:  # noqa: BLE001 —— 这一层出错只是"没有可比基线"，不该让画布挂掉
+            tables = None
+    # ⚠️ 一次只留最新那几份；**`None` 也缓存**（"这个提交里算不出来"是有意义的结论）。
+    if len(_DERIVED_CACHE) > 8:
+        _DERIVED_CACHE.clear()
+    _DERIVED_CACHE[key] = tables
+    return tables
+
+
+def _sources_state() -> float:
+    """这一层的输入**现在的**状态（拿不到任何文件时回 `0.0`）。
+
+    🔴 **三个东西都要算进来**，缺一个就有一类"改了没生效"：
+       · 项目那份 `settings.py`（`INSTALLED_APPS` / `AUTH_USER_MODEL` 从它来）—— 换了它就换了输入；
+       · **本模块和 `shape_ast.py` 自己**的 mtime —— 改了"怎么算基线"的代码而缓存不失效，
+         症状是"代码明明改了、量到的还是旧结果"（开发这一层时必踩；真踩过，
+         为了一个已经修掉的假差异查了半小时，而进程里的缓存还捧着旧的那份）。
+    ⚠️ 基线里的**源码**不用管：它在 git 里，由提交号管。
+    """
+    base = _root()
+    newest = 0.0
+    if base is not None:
+        for name in ('config/settings.py', 'settings.py'):
+            try:
+                path = base / name
+                if path.is_file():
+                    newest = max(newest, path.stat().st_mtime)
+            except OSError:
+                continue
+    here = Path(__file__).resolve().parent
+    for name in ('gitinfo.py', 'shape_ast.py'):
+        try:
+            newest = max(newest, (here / name).stat().st_mtime)
+        except OSError:
+            continue
+    return newest
+
+
+def _group_apps(files: list[tuple[str, str, str]]) -> dict[str, dict[str, str]]:
+    """把"仓库里的文件"归到各个 app 名下（`shape_ast.derive()` 的入参形态）。
+
+    每个 app 会多带一个 `__package__`：它是"去读这个 app 里某个类的源码"的唯一线索 ——
+    少了它，本 app 的模型继承外部基类（`AbstractUser`）时继承链会断在第一个基类上。
+
+    🔴 `__package__` 必须是**能 import 的那个模块路径**，不是仓库里的目录路径：
+       仓库根的目录名（`backend`、`all files`）未必是合法的包名，而 `find_spec()` 只认
+       `sys.path` 上的名字。判据是"往上找到第一个带 `__init__.py` 的目录" ——
+       与 Python 的包定义完全一致，所以 `backend/example/orders` 会得到 `orders`
+       （`backend/` 里没有 `__init__.py`），而 `backend/labull_framework` 得到 `labull_framework`。
+    """
+    packages = _package_of_directory(files)
+    apps: dict[str, dict[str, str]] = {}
+    for path, _blob, text in files:
+        parts = path.split('/')
+        if len(parts) < 2:
+            continue
+        directory = '/'.join(parts[:-1])
+        package = packages.get(directory, directory.replace('/', '.'))
+        app = apps.setdefault(package, {'__package__': package})
+        app[parts[-1]] = text
+    # `settings.py` 要在**每个** app 眼里都看得见（`AUTH_USER_MODEL` / `INSTALLED_APPS` 在那儿）。
+    settings_text = _project_settings()
+    if settings_text:
+        for app in apps.values():
+            app.setdefault('settings.py', settings_text)
+    return apps
+
+
+def _package_of_directory(files: list[tuple[str, str, str]]) -> dict[str, str]:
+    """仓库里的目录路径 → **可 import 的包路径**（见 `_group_apps()` 里那条说明）。
+
+    🔴 判据用**文件清单本身**里的 `__init__.py`，不去碰文件系统：
+       `git ls-tree` 已经把那一版的所有文件都列出来了，"哪个目录是包"就在那份清单里。
+       去看工作区会得出"现在是不是包"的答案，而我们要的是**那一版**的答案。
+    🔴 走法是"**从最上面那个包往下拼**"：先一路往上找到最高的那个包目录
+       （它的父目录不是包 ⇒ 那里才是 `sys.path` 的入口），再把它下面的各段拼成模块名。
+       `backend/example/orders`：`backend/example` 不是包 ⇒ 入口是它，模块名 = `orders`；
+       `backend/labull_framework/canvas`：`backend/labull_framework` 是包、它的父目录不是
+       ⇒ 入口是 `backend/`，模块名 = `labull_framework.canvas`。
+    """
+    package_dirs = {
+        path.rsplit('/__init__.py', 1)[0]
+        for path in (one[0] for one in files)
+        if path.endswith('/__init__.py')
+    }
+
+    def package_of(directory: str) -> str:
+        parts = directory.split('/') if directory else []
+        if not parts:
+            return ''
+        top = len(parts) - 1
+        while top > 0 and '/'.join(parts[:top]) in package_dirs:
+            top -= 1
+        return '.'.join(parts[top:])
+
+    return {
+        directory: package_of(directory)
+        for directory in {'/'.join(path.split('/')[:-1]) for path, _blob, _text in files}
+    }
+
+
+def _project_settings() -> str:
+    """项目自己的 `settings.py`（从**工作区**读 —— 只有 `AUTH_USER_MODEL` / `INSTALLED_APPS`
+    这两项从这里取，它们不参与差异判据，所以读当前这一份是安全的）。
+
+    🔴 **不读提交里那一份**：万一项目里真有个 app 叫 `settings`，按"哪个 app 的"归类就会造出
+       一个假的 app；而这两项本来也不该跟着提交变（换用户表是一次全局迁移，不是"这次改了什么"）。
+    ⚠️ 找不到就回空：那时 `INSTALLED_APPS` 读不出来 ⇒ `shape_ast` 一律放行（宁可多画也不要漏）。
+    """
+    base = _root()
+    if base is None:
+        return ''
+    for name in ('config/settings.py', 'settings.py'):
+        path = base / name
+        try:
+            if path.is_file():
+                # 同 `_parse_batch()` / `shape_ast._read_file_of_module()`：带 BOM 也要读得进来。
+                return path.read_text(encoding='utf-8-sig', errors='replace')
+        except OSError:
+            continue
+    return ''
+
+
+def _revision_sources(repo: Path, revision: str) -> list[tuple[str, str, str]]:
+    """基线那一版里、**每一个 app 的那几份源码**：`[(仓库相对路径, blob 号, 正文)]`。
+
+    🔴 一次 `ls-tree` + 一次批量 `git show --stdin`：**不为每个文件各起一个进程** ——
+       这一层是页面请求里的同步依赖，进程数就是延迟。
+    ⚠️ 路径一律**相对仓库根**（`git show` 只认这种）：`ls-tree` 的输出是相对**当前目录**的，
+       所以这里用 `--full-tree` 把那个坑直接绕开（两个工具的口径必须对齐，见 `_repo_root()`）。
+    """
+    listing = _run(['ls-tree', '-r', '--full-tree', revision], repo)
+    if not listing:
+        return []
+    wanted: dict[str, str] = {}
+    for line in listing.splitlines():
+        meta, _, path = line.partition('\t')
+        parts = meta.split()
+        if len(parts) < 3 or parts[1] != 'blob':
+            continue
+        name = path.rsplit('/', 1)[-1]
+        # ⚠️ `settings.py` **不从这里取**：它只在"当前这一份"里读（见 `_project_settings()`）——
+        #    `INSTALLED_APPS` / `AUTH_USER_MODEL` 不参与差异判据，而把它按"哪个 app 的"
+        #    归错类（项目里真有个 app 叫 `settings`？）反而会造出一个假的 app。
+        if name in _SOURCE_FILES:
+            wanted[path] = parts[2]
+    if not wanted:
+        return []
+    stdin = '\n'.join(f'{revision}:{path}' for path in sorted(wanted))
+    try:
+        done = subprocess.run(
+            ['git', 'cat-file', '--batch'],
+            cwd=str(repo),
+            input=stdin.encode('utf-8'),
+            capture_output=True,
+            timeout=_TIMEOUT,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if done.returncode != 0 or not done.stdout:
+        return []
+    return _parse_batch(done.stdout, wanted)
+
+
+def _parse_batch(raw: bytes, wanted: dict[str, str]) -> list[tuple[str, str, str]]:
+    """`git cat-file --batch` 的输出 → `[(路径, blob 号, 正文)]`（保持请求顺序）。
+
+    🔴 用 `cat-file --batch` 而不是 `git show --stdin`：前者是**逐对象**的
+       `<sha> blob <字节数>\\n<正文>\\n`，切起来是字节级的、没有歧义；
+       后者的输出里混着 commit 头（`Author` / `Date` / 缩进的说明），靠"第几段"对回文件名
+       —— 一旦哪个文件正文里出现一行 `commit ...` 就会切错（真踩过这种歧义）。
+    🔴 **必须按字节切**：头里的 `<字节数>` 是字节数，而这个仓库的源码是中文 UTF-8
+       （一个字三字节）—— 按字符切会越切越偏，最后把所有文件的内容错位。
+    """
+    order = sorted(wanted)
+    out: list[tuple[str, str, str]] = []
+    cursor = 0
+    for path in order:
+        line_end = raw.find(b'\n', cursor)
+        if line_end < 0:
+            break
+        header = raw[cursor:line_end].decode('utf-8', 'replace')
+        cursor = line_end + 1
+        parts = header.split()
+        if len(parts) < 3 or parts[1] != 'blob':
+            # 这个对象不在（`<rev>:<path>` 取不到）⇒ 停在这里：剩下的对不上号了。
+            break
+        try:
+            size = int(parts[2])
+        except ValueError:
+            break
+        body = raw[cursor:cursor + size]
+        cursor += size + 1
+        # 🔴 **按 `utf-8-sig` 解码**（不是 `utf-8`）：作者那份 `models.py` 可能是"UTF-8 带 BOM"
+        #    存下来的（编辑器默认就这样），而 CPython 导入源码时 BOM 是被吃掉的 ⇒ Django 那边
+        #    一切正常。我们这边留着那个 `\ufeff` 的话，`ast.parse()` 当场抛
+        #    `SyntaxError: invalid non-printable character U+FEFF` ⇒ 这个 app 从基线里缺席，
+        #    画布报"整张表新增"。见 `shape_ast._read_file_of_module()` 里同一条说明。
+        out.append((path, parts[0], body.decode('utf-8-sig', 'replace')))
+    return out
+
+
+def _repo_relative_contract(repo: Path) -> str | None:
+    """契约路径换算成**相对仓库根**的形式（`git show` / `git diff` 认这个）。
+
+    契约在仓库外面（项目根不在仓库里，或者契约被 `LABULL_CONTRACT_PATH` 指到外面）⇒ `None`：
+    那种"这份文件不受版本控制"的情况就是**没有可比基线**，不是错误。
+    """
+    base = _root()
+    if base is None:
+        return None
+    absolute = (base / contract_path()).resolve()
+    try:
+        relative = absolute.relative_to(repo.resolve())
+    except ValueError:
+        return None
+    return relative.as_posix()