xirang-kernel 0.2.2

Registry, transaction, contracts, grafts, and diagnostics for XiRang
Documentation
//! Shared MIR vocabulary: parsed candidates, evidence-aware relations, errors.
//! 共享 MIR 词汇:已解析候选、带证据等级的关系、错误。
//!
//! The parsers live beside this page: `super::text` reads rustc
//! `-Zunpretty=mir` text, `super::jsonl` reads the compact JSONL artifact,
//! `super::render` writes both artifacts back, and `super::merge` merges
//! static candidates with live edges.
//! 解析器位于本页旁边:`super::text` 读取 rustc `-Zunpretty=mir` 文本,
//! `super::jsonl` 读取紧凑 JSONL artifact,`super::render` 把两种 artifact 写回,
//! `super::merge` 将静态候选与 live 边归并。

use std::collections::BTreeSet;
use std::fmt;

use crate::registry_core::declaration::{EvidenceKind, SourceLocation};
use crate::registry_core::identity::NodeId;

/// One direct call sighting extracted from a MIR artifact.
/// 从 MIR artifact 中提取到的一条直接调用观测。
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct MirCall {
    /// Function symbol the call appears in.
    /// 调用所在的函数符号。
    pub caller: String,
    /// Function symbol being called.
    /// 被调用的函数符号。
    pub callee: String,
    /// 1-based position of this record within the parsed MIR, not a source line: the JSONL
    /// reader fills it with a synthesized record index, while the text reader fills it with
    /// the real MIR line it read. The name says "MIR line" for both spellings, so read the
    /// parser that produced the value before comparing two of them (audit `KRN-C-10`).
    /// 该记录在已解析 MIR 内以 1 起始的位置,不是源码行号:JSONL 读取器填入的是合成的记录序号,
    /// 文本读取器填入的是它读到的真实 MIR 行。名字对两种拼法都说"MIR line",因此比较两个值时先看清
    /// 是哪个解析器产出的(审计 `KRN-C-10`)。
    pub mir_line: usize,
}

/// One local binding sighting extracted from a MIR artifact.
/// 从 MIR artifact 中提取到的一条局部绑定观测。
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct MirLocal {
    /// Function symbol owning the local.
    /// 拥有该局部变量的函数符号。
    pub function: String,
    /// Local binding name as written in MIR, such as `_1`.
    /// MIR 中书写的局部绑定名,例如 `_1`。
    pub name: String,
    /// Declared type text of the binding.
    /// 该绑定的声明类型文本。
    pub type_name: String,
    /// 1-based position of this record within the parsed MIR, not a source line: the JSONL
    /// reader fills it with a synthesized record index, while the text reader fills it with
    /// the real MIR line it read. The name says "MIR line" for both spellings, so read the
    /// parser that produced the value before comparing two of them; `CallRelation`'s field of
    /// the same name inherits this meaning verbatim (audit `KRN-C-10`).
    /// 该记录在已解析 MIR 内以 1 起始的位置,不是源码行号:JSONL 读取器填入的是合成的记录序号,
    /// 文本读取器填入的是它读到的真实 MIR 行。名字对两种拼法都说"MIR line",因此比较两个值时先看清
    /// 是哪个解析器产出的(审计 `KRN-C-10`;`CallRelation` 的同名字段逐字继承这一含义)。
    pub mir_line: usize,
}

/// Unified evidence attached to one logical call relation.
/// 一条逻辑调用关系携带的统一证据等级。
pub type CallEvidence = EvidenceKind;

/// One call edge normalized across runtime, MIR, and source evidence.
/// 跨运行时、MIR、源码证据统一表示的一条调用边。
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CallRelation {
    /// Function symbol making the call.
    /// 发起调用的函数符号。
    pub caller: String,
    /// Function symbol being called.
    /// 被调用的函数符号。
    pub callee: String,
    /// Strongest evidence supporting this relation: live over MIR.
    /// 支持该关系的最高证据等级:Live 优先于 MIR。
    pub evidence: EvidenceKind,
    /// Source location of the callee, when known.
    /// 已知时,被调用方的源码位置。
    pub source: Option<SourceLocation>,
    /// MIR record position for a MIR-only relation; `None` for a live edge.
    /// 仅由 MIR 支持时为 MIR 记录位置;live 边为 `None`。
    pub mir_line: Option<usize>,
    /// Runtime frame id of the caller; `None` for a static-only relation.
    /// 调用方的运行期帧 id;仅静态关系为 `None`。
    pub caller_frame: Option<u64>,
    /// Runtime frame id of the callee; `None` for a static-only relation.
    /// 被调用方的运行期帧 id;仅静态关系为 `None`。
    pub callee_frame: Option<u64>,
}

impl CallRelation {
    /// A relation whose two ends are known but whose provenance is only the text
    /// of the call site: no MIR record, no runtime frame.
    /// 两端已知、但来源只是调用点文本的关系:没有 MIR 记录,也没有运行期帧。
    ///
    /// Studio's source scan produces these, which is why the type has to be
    /// constructible without inventing a MIR line or a frame id.
    /// Studio 的源码扫描产生的正是它们,因此该类型必须能在不编造 MIR 行号或帧 id 的情况下构造。
    pub fn from_symbols(
        caller: impl Into<String>,
        callee: impl Into<String>,
        evidence: EvidenceKind,
    ) -> Self {
        Self {
            caller: caller.into(),
            callee: callee.into(),
            evidence,
            source: None,
            mir_line: None,
            caller_frame: None,
            callee_frame: None,
        }
    }
}

/// Every candidate one MIR artifact offered, before any merge.
/// 一份 MIR artifact 提供的全部候选,尚未归并。
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct MirGraph {
    /// Function symbols the artifact declared.
    /// artifact 声明过的函数符号。
    pub functions: BTreeSet<String>,
    /// Direct call sightings, in artifact order.
    /// 直接调用观测,按 artifact 顺序。
    pub calls: Vec<MirCall>,
    /// Local binding sightings, in artifact order.
    /// 局部绑定观测,按 artifact 顺序。
    pub locals: Vec<MirLocal>,
    /// The tree this artifact is a snapshot of, when its producer named one.
    /// 本 artifact 作为快照所描述的那棵树;生产者点名了它时才有值。
    pub snapshot: Option<MirSnapshot>,
}

/// The tree one MIR artifact describes, when its producer named it.
/// 一份 MIR artifact 描述的那棵树;生产者点名了它时。
///
/// A MIR dump is only a snapshot of *some* tree, and rustc's own text format
/// cannot say which: two dumps of two different packages are byte-comparable and
/// a delta between them would be a plausible, wrong answer. This is the header
/// that makes the identification possible — the same convention the trace
/// artifact carries — and it is optional because a `-Zunpretty=mir` text dump
/// arrives without one and is still readable. An artifact that names its tree
/// can be refused by name; one that does not is reported as unidentified rather
/// than silently trusted.
/// MIR 转储只是**某棵**树的快照,而 rustc 自己的文本格式说不出是哪一棵:两个不同包的两份转储
/// 可以逐字节比较,而它们之间的 delta 会是一个看似合理、实则错误的答案。这个表头让识别成为可能
/// ——与 trace artifact 携带的是同一种约定——它可选,因为 `-Zunpretty=mir` 文本转储到来时没有它,
/// 却仍然可读。点名了自己那棵树的 artifact 可以被按名字拒绝;没有点名的会被报成"未标识",而不是
/// 被默默信任。
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct MirSnapshot {
    /// The identity namespace the artifact was produced under.
    /// 产出该 artifact 时所在的身份命名空间。
    pub namespace: String,
    /// The registration-tree root that namespace implies.
    /// 该命名空间蕴含的注册树根。
    pub root: NodeId,
}

/// Why one line of a MIR artifact could not be read.
/// MIR artifact 某一行无法读取的原因。
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct MirParseError {
    /// 1-based line of the offending input.
    /// 出错输入以 1 起始的行号。
    pub line: usize,
    /// Description of what the line got wrong.
    /// 对该行错误之处的描述。
    pub message: String,
}

impl fmt::Display for MirParseError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "MIR graph line {}: {}", self.line, self.message)
    }
}

impl std::error::Error for MirParseError {}