boba/obfuskator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

structure-check: gate counts code lines, docs and comments in English

Browse source 
Gate ignores blank and full-line comment lines so the 250-line limit
measures code bulk, not documentation weight; docs/README.md synced.
Translate code comments to English in classfile, core config, namegen,
rename assign, constants forms. Expand Plausible word bank with
client-ecosystem terms (Module, Setting, Mixin, ...). cargo fmt clean,
check.sh green.
This commit is contained in:
Loki 2026-10-09 10:31:02 +02:00
parent ec28ec82e3
commit 39178420e4
Signed by: boba
GPG key ID: 253067914055423B
42 changed files with 532 additions and 437 deletions
Download patch file Download diff file Expand all files Collapse all files

4
crates/noxis-classfile/src/error.rs
View file

@ -1,6 +1,6 @@
//! Ошибки разбора/записи классовых файлов.
//! Errors from class-file parsing/writing.
/// Ошибка на уровне одного классового файла.
/// An error at the level of a single class file.
#[derive(Debug, thiserror::Error)]
pub enum ClassfileError {
#[error("не удалось разобрать классовый файл: {0}")]

25
crates/noxis-classfile/src/format/frames/emit.rs
View file

@ -1,8 +1,9 @@
//! Эмиссия компактных кадров в точках, где их ждёт верификатор.
//! Emitting compact frames at the points where the verifier expects them.
//!
//! Вид кадра выбирается сравнением с предыдущим кадром (`Same`/`Append`/
//! `Chop`/`SameLocals`, иначе `Full`) — как у `javac`. Хвостовые `Top`
//! при сравнении и записи отрезаются: пустой слот — не тип.
//! A frame's kind is chosen by comparing with the previous frame
//! (`Same`/`Append`/`Chop`/`SameLocals`, otherwise `Full`) — like `javac`.
//! Trailing `Top`s are trimmed both when comparing and when writing: an empty
//! slot is not a type.
use std::collections::BTreeSet;
@ -11,10 +12,10 @@ use super::xfer::State;
use super::{StackMapFrame, VerificationType};
use crate::error::ClassfileError;
/// Кадры во всех точках `targets` (отсортированы — дельты по порядку).
/// Frames at every point in `targets` (sorted — deltas in order).
///
/// Дельты — в номерах инструкций (как backend после чтения); writer сам
/// пересчитает их в байты.
/// Deltas are in instruction numbers (like the backend after reading); the writer
/// recomputes them into bytes itself.
pub(super) fn emit_frames(
states: &[Option<State>],
targets: &BTreeSet<u32>,
@ -49,8 +50,8 @@ fn select(
previous: &[VerificationType],
stack: &[VerificationType],
) -> StackMapFrame {
// Сравнение — на гранулярности переменных (`long` — одна запись,
// как у `javac`): иначе половины пар дают `Append{[Top, Long]}`.
// Comparison is at variable granularity (`long` — one entry, like `javac`);
// otherwise halves would produce `Append{[Top, Long]}`.
let current = vars(locals);
let base = vars(previous);
if current == base {
@ -93,10 +94,10 @@ fn select(
}
}
/// Слоты → переменные: `[Long, Top]` — одна запись; хвостовые `Top` — прочь.
/// Slots → variables: `[Long, Top]` — one entry; trailing `Top`s — gone.
///
/// Одиночные `Top` внутри (дыры) сохраняются: в `Full` это легальный тип,
/// а в `Append` мы их не пускаем (см. `select`).
/// Single `Top`s inside (holes) are kept: in `Full` they are a legal type, and we
/// don't allow them in `Append` (see `select`).
fn vars(locals: &[VerificationType]) -> Vec<VerificationType> {
let mut out = Vec::with_capacity(locals.len());
let mut index = 0;

18
crates/noxis-classfile/src/format/frames/flow.rs
View file

@ -1,4 +1,4 @@
//! CFG тела метода: метки, рёбра, точки кадров, диапазоны handler'ов.
//! A method body's CFG: labels, edges, frame points, handler ranges.
use std::collections::{BTreeMap, BTreeSet};
@ -7,7 +7,7 @@ use crate::error::ClassfileError;
use crate::insn::{Insn, Label};
use crate::model::ExceptionHandler;
/// Метки → номера инструкций без маркеров.
/// Labels → instruction numbers, without the markers.
pub(super) fn strip_marks<'a>(
insns: &'a [Insn],
merger: &Merger<'_>,
@ -31,7 +31,7 @@ pub(super) fn strip_marks<'a>(
Ok((labels, bare))
}
/// Рёбра CFG без исключений: продолжение + цели переходов.
/// CFG edges without exceptions: fallthrough + branch targets.
pub(super) fn successors(
insn: &Insn,
index: u32,
@ -40,8 +40,8 @@ pub(super) fn successors(
merger: &Merger<'_>,
) -> Result<Vec<u32>, ClassfileError> {
let mut out = Vec::new();
// Без продолжения: переходы без возврата и выходы из метода.
// `Jsr`/`Ret` сюда не доходят (их отвергает `transfer`), но рёбра есть.
// No fallthrough: jumps that don't return and method exits.
// `Jsr`/`Ret` never reach here (rejected by `transfer`), but the edges exist.
let terminal = matches!(
insn,
Insn::Goto(..)
@ -67,7 +67,7 @@ pub(super) fn successors(
Ok(out)
}
/// Точки, где верификатор требует кадры: цели переходов + входы handler'ов.
/// Points where the verifier requires frames: branch targets + handler entries.
pub(super) fn frame_targets(
bare: &[&Insn],
labels: &BTreeMap<Label, u32>,
@ -91,12 +91,12 @@ pub(super) fn frame_targets(
Ok(targets)
}
/// Точка handler'а в номерах инструкций: `(start, end, handler, тип перехвата)`.
/// A handler point in instruction numbers: `(start, end, handler, catch type)`.
///
/// Диапазоны полуоткрытые `[start, end)`, как в JVMS.
/// Ranges are half-open `[start, end)`, as in the JVMS.
pub(super) type HandlerRange = (u32, u32, u32, Option<String>);
/// Handler'ы в номерах инструкций для рёбер исключений.
/// Handlers in instruction numbers, for exception edges.
pub(super) fn handler_ranges(
table: &[ExceptionHandler],
labels: &BTreeMap<Label, u32>,

16
crates/noxis-classfile/src/format/frames/merge/descs.rs
View file

@ -1,12 +1,12 @@
//! Разбор дескрипторов типов (`(...)V`, `[L...;`).
//! Descriptor parsing (`(...)V`, `[L...;`).
use super::super::VerificationType;
/// Ошибка разбора дескриптора (контекст добавляет вызывающий код).
/// Descriptor parse error (context is added by the caller).
#[derive(Debug)]
pub(crate) struct DescError(pub String);
/// Уложить слоты значения в locals с позиции; вернуть следующую позицию.
/// Write value slots into `locals` at position; return next position.
pub(crate) fn write_local(
locals: &mut [VerificationType],
slot: usize,
@ -22,7 +22,7 @@ pub(crate) fn write_local(
Ok(slot + width)
}
/// Разобрать дескриптор массива на (глубина, элемент без `;`).
/// Parse an array descriptor into (depth, element without `;`).
pub(crate) fn split_array(descriptor: &str) -> Option<(usize, &str)> {
let dims = descriptor.bytes().take_while(|&b| b == b'[').count();
if dims == 0 {
@ -31,7 +31,7 @@ pub(crate) fn split_array(descriptor: &str) -> Option<(usize, &str)> {
Some((dims, descriptor[dims..].trim_end_matches(';')))
}
/// Слоты одного полевого дескриптора (`long`/`double` — парой с `Top`).
/// Slots for a single field descriptor (`long`/`double` — pair with `Top`).
pub(crate) fn field_slots(descriptor: &str) -> Result<Vec<VerificationType>, DescError> {
let mut chars = descriptor.chars();
match chars.next() {
@ -57,10 +57,10 @@ pub(crate) fn field_slots(descriptor: &str) -> Result<Vec<VerificationType>, Des
}
}
/// Слоты параметров и возврата (`None` — `void`).
/// Parameter and return slots (`None` — `void`).
type MethodSlots = (Vec<Vec<VerificationType>>, Option<Vec<VerificationType>>);
/// Дескриптор метода: слоты параметров и слоты возврата (`None` — `void`).
/// Method descriptor: parameter slots and return slots (`None` — `void`).
pub(crate) fn method_slots(descriptor: &str) -> Result<MethodSlots, DescError> {
let (params, ret) = descriptor
.split_once('(')
@ -128,7 +128,7 @@ pub(crate) fn method_slots(descriptor: &str) -> Result<MethodSlots, DescError> {
Ok((out, ret))
}
/// Тип элемента по дескриптору массива в стеке.
/// Element type from an array descriptor on the stack.
pub(crate) fn array_element(
array: &VerificationType,
kind: crate::insn::ArrayKind,

38
crates/noxis-classfile/src/format/frames/merge/mod.rs
View file

@ -1,12 +1,12 @@
//! Слияние типов (LUB) и разбор дескрипторов.
//! Type merging (LUB) and descriptor parsing.
//!
//! Решётка: `Top` — «пусто» (берётся сосед), `Null` впитывается в ссылку,
//! одинаковые — сами в себя, ссылки — наименьший общий предок по иерархии.
//! Несочетаемые инициализированные типы (`int` vs ссылка после `astore`
//! в handler'е) дают `Top`, как обрезанные кадры `javac`: `Top` в кадре
//! принимает любое фактическое значение, поэтому это всегда sound.
//! Исключение — неинициализированные типы: их слияние означает сломанный
//! поток конструирования, здесь честная ошибка, а не молчаливый `Top`.
//! The lattice: `Top` is "empty" (the neighbour wins), `Null` is absorbed into a
//! reference, equal types map to themselves, references take the least upper
//! bound over the hierarchy. Incompatible initialized types (`int` vs a reference
//! after `astore` in a handler) yield `Top`, like `javac`'s truncated frames: a
//! `Top` in a frame accepts any actual value, so this is always sound. The
//! exception is uninitialized types: merging them means a broken construction
//! flow — here an honest error, not a silent `Top`.
pub(super) mod descs;
@ -17,13 +17,13 @@ use crate::model::Method;
use descs::write_local;
/// Иерархия классов для LUB: достаточно цепочки суперклассов.
/// The class hierarchy for LUB: the superclass chain is enough.
pub trait Hierarchy {
/// Прямой суперкласс (`None` — `java/lang/Object` или неизвестный).
/// The direct superclass (`None` — `java/lang/Object` or unknown).
fn superclass(&self, class: &str) -> Option<String>;
}
/// Контекст слияния: имена для ошибок + иерархия для LCA.
/// Merge context: names for errors + hierarchy for LCA.
pub(super) struct Merger<'h> {
pub class: String,
pub method: String,
@ -38,7 +38,7 @@ impl Merger<'_> {
}
}
/// Влить входящее состояние; `true` — слот изменился.
/// Merge an incoming state; `true` — the slot changed.
pub fn merge_into(
&self,
slot: &mut Option<State>,
@ -61,7 +61,7 @@ impl Merger<'_> {
}
}
/// Начальное состояние: параметры (+ `this`) поверх `Top`.
/// The initial state: parameters (+ `this`) over `Top`.
pub fn initial(&self, method: &Method, max_locals: u16) -> Result<State, ClassfileError> {
let is_static = method.access_flags & 0x0008 != 0;
let (params, _) =
@ -127,19 +127,19 @@ impl Merger<'_> {
Ok(first.clone())
}
(Object(a), Object(b)) => Ok(Object(self.common_superclass(a, b))),
// Одинаковые уже разобраны выше; здесь неинициализированные
// всегда разные — это сломанный поток конструирования.
// Equal ones are handled above; here uninitialized are always
// different — that's a broken construction flow.
(VerificationType::UninitializedThis | VerificationType::Uninitialized(_), _)
| (_, VerificationType::UninitializedThis | VerificationType::Uninitialized(_)) => {
Err(self.invalid("слияние неинициализированных типов"))
}
// Несочетаемые инициализированные (например, `int` из тела `try`
// и `Throwable` из handler'а в одном слоте): `Top`, как у `javac`.
// Incompatible initialized (e.g. `int` from the `try` body and
// `Throwable` from a handler in one slot): `Top`, like `javac`.
_ => Ok(Top),
}
}
/// Наименьший общий предок: подъём по цепочкам, запасной — `Object`.
/// Least common ancestor: climb the chains, fallback — `Object`.
fn common_superclass(&self, first: &str, second: &str) -> String {
if first == second {
return first.to_string();
@ -176,7 +176,7 @@ impl Merger<'_> {
"java/lang/Object".to_string()
}
/// LCA массивов: та же размерность + LCA элементов, иначе `Object`.
/// Arrays' LCA: same dimensionality + element LCA, otherwise `Object`.
fn array_lca(&self, first: &str, second: &str) -> String {
let (dims_a, elem_a) = descs::split_array(first).unwrap_or((0, first));
let (dims_b, elem_b) = descs::split_array(second).unwrap_or((0, second));

41
crates/noxis-classfile/src/format/frames/mod.rs
View file

@ -1,12 +1,12 @@
//! `StackMapTable`: представление фреймов и вычисление после трансформаций.
//! `StackMapTable`: frame representation and computation after transformations.
//!
//! Фреймы — самая дорогая часть любого обфускатора на Rust: JVM-верификатор
//! (class version ≥ 50) требует точного `StackMapTable`, иначе класс не грузится.
//! Варианты реализации и их цены — `docs/stack.md`.
//! Frames are the most expensive part of any Rust obfuscator: the JVM verifier
//! (class version ≥ 50) demands an exact `StackMapTable`, or the class won't load.
//! Implementation options and their costs — `docs/stack.md`.
//!
//! Метод: CFG по меткам → worklist с типами (`xfer`) → слияние LUB (`merge`)
//! → эмиссия компактных кадров (`emit`). Байтовые смещения берутся тем же
//! преобразованием, что использует writer, — иначе кадры разъедутся с байтами.
//! Method: CFG over labels → worklist with types (`xfer`) → LUB merge (`merge`)
//! → emit compact frames (`emit`). Byte offsets come from the same encoding the
//! writer uses — otherwise frames would drift apart from the bytes.
mod emit;
mod flow;
@ -27,7 +27,7 @@ pub use merge::Hierarchy;
use merge::Merger;
use xfer::{State, transfer};
/// Тип верификации из JVMS §4.10.1.
/// A verification type from JVMS §4.10.1.
#[derive(Debug, Clone, PartialEq)]
pub enum VerificationType {
Top,
@ -37,14 +37,14 @@ pub enum VerificationType {
Long,
Null,
UninitializedThis,
/// Внутреннее имя класса (`java/lang/Object`) или дескриптор массива.
/// The class's internal name (`java/lang/Object`) or an array descriptor.
Object(String),
/// Байтовое смещение инструкции `new`.
/// The byte offset of the `new` instruction.
Uninitialized(u16),
}
impl VerificationType {
/// Тип, соответствующий примитиву.
/// The type matching a primitive.
pub fn of_prim(p: Prim) -> Self {
match p {
Prim::Int => VerificationType::Integer,
@ -55,7 +55,7 @@ impl VerificationType {
}
}
/// Запись `StackMapTable` (JVMS §4.7.4).
/// A `StackMapTable` entry (JVMS §4.7.4).
#[derive(Debug, Clone, PartialEq)]
pub enum StackMapFrame {
Same {
@ -80,10 +80,11 @@ pub enum StackMapFrame {
},
}
/// Вычислить фреймы для тела метода после всех трансформаций.
/// Compute the frames for a method body after all transformations.
///
/// Кадры нужны только классам версии ≥ 50; `jsr`/`ret` отвергаются (такие
/// классы старше и кадры им не нужны). Иерархия — для LUB ссылочных типов.
/// Frames are needed only for version ≥ 50 classes; `jsr`/`ret` are rejected
/// (such classes are older and need no frames). The hierarchy is for the LUB of
/// reference types.
pub fn compute_frames(
class: &str,
method: &Method,
@ -112,7 +113,7 @@ pub fn compute_frames(
emit::emit_frames(&states, &targets, &initial.locals, &merger)
}
/// Байтовое смещение каждой инструкции — тем же кодированием, что в writer'е.
/// The byte offset of each instruction — using the same encoding as the writer.
fn layout(
bare: &[&Insn],
labels: &BTreeMap<Label, u32>,
@ -144,7 +145,7 @@ fn layout(
.collect()
}
/// Основной цикл: состояния текут по рёбрам CFG до неподвижной точки.
/// Main loop: states flow along CFG edges to a fixed point.
fn run_worklist(
merger: &Merger<'_>,
bare: &[&Insn],
@ -187,7 +188,7 @@ fn run_worklist(
Ok(())
}
/// Влить состояние в инструкцию; `true` — изменилось, продолжить обход.
/// Merge a state into an instruction; `true` — changed, keep walking.
fn flow_into(
merger: &Merger<'_>,
states: &mut [Option<State>],
@ -218,8 +219,8 @@ fn flow_into(
Ok(())
}
/// Рёбра CFG без исключений: продолжение + цели переходов.
/// Тип исключения на входе в handler (`catch-all` — любое throwable).
/// CFG edges without exceptions: fallthrough + branch targets.
/// The exception type at a handler's entry (`catch-all` — any throwable).
fn catch_type(catch: &Option<String>) -> VerificationType {
match catch {
Some(name) => VerificationType::Object(name.clone()),

16
crates/noxis-classfile/src/format/mod.rs
View file

@ -1,5 +1,6 @@
//! Чтение/запись бинарного формата `.class` (JVMS §4) через backend
//! `ristretto_classfile`: обзор кандидатов и решение — `docs/stack.md`.
//! Reading/writing the binary `.class` format (JVMS §4) through the
//! `ristretto_classfile` backend: candidate review and decision in
//! `docs/stack.md`.
mod frames;
mod parse;
@ -10,20 +11,21 @@ pub use frames::{Hierarchy, StackMapFrame, VerificationType, compute_frames};
use crate::error::ClassfileError;
use crate::model::ClassFile;
/// Разобрать один `.class` в [`ClassFile`].
/// Parse one `.class` into a [`ClassFile`].
pub fn parse(bytes: &[u8]) -> Result<ClassFile, ClassfileError> {
parse::class::parse_class(bytes)
}
/// Записать [`ClassFile`] в байты, включая пересчёт `Code`/`StackMapTable`.
/// Write a [`ClassFile`] to bytes, including `Code`/`StackMapTable` recompute.
pub fn write(class: &ClassFile) -> Result<Vec<u8>, ClassfileError> {
write::write_class(class)
}
/// Классы, которые не изменялись, должны уезжать в выходной архив «как есть».
/// Classes that were not modified must go to the output archive "as-is".
///
/// Это дешевле и безопаснее, чем round-trip через наш IR: нет риска потерять
/// неизвестный атрибут. Реализация зависит от решения по backend (P1).
/// This is cheaper and safer than a round-trip through our IR: no risk of
/// losing an unknown attribute. The implementation depends on the backend
/// decision (P1).
pub fn passthrough_needed(class: &ClassFile) -> bool {
class.methods.is_empty() && class.fields.is_empty()
}

22
crates/noxis-classfile/src/format/parse/attrs.rs
View file

@ -1,10 +1,10 @@
//! Атрибуты backend'а → атрибуты нашего IR.
//! Backend attributes → our IR attributes.
//!
//! `BootstrapMethods`, `EnclosingMethod`, `MethodParameters` и `ConstantValue`
//! моделируются явно (в них лежат ссылки пула, переживающие пересборку);
//! остальное структурированное, но нам ненужное, уезжает в `Raw` как есть.
//! `Code` и `StackMapTable` здесь не обрабатываются — их разбирает вызывающий
//! код метода (см. `super::class`).
//! `BootstrapMethods`, `EnclosingMethod`, `MethodParameters` and `ConstantValue`
//! are modeled explicitly (they hold pool references that survive rebuilding);
//! everything else that is structured but unneeded by us goes to `Raw` as-is.
//! `Code` and `StackMapTable` are not handled here — the calling method code
//! parses them (see `super::class`).
use ristretto_classfile::ConstantPool;
use ristretto_classfile::attributes::Attribute as RtAttr;
@ -15,7 +15,7 @@ use super::pool::{
use crate::error::ClassfileError;
use crate::model::{Attribute, BootstrapMethod, InnerClass, MethodParameter, RecordComponent};
/// Один атрибут backend'а → наш атрибут (кроме `Code`/`StackMapTable`).
/// One backend attribute → our attribute (except `Code`/`StackMapTable`).
pub(super) fn convert(attr: &RtAttr, pool: &ConstantPool<'_>) -> Result<Attribute, ClassfileError> {
Ok(match attr {
RtAttr::SourceFile {
@ -105,7 +105,7 @@ pub(super) fn convert(attr: &RtAttr, pool: &ConstantPool<'_>) -> Result<Attribut
})
}
/// Несмоделированный атрибут → `Raw`: имя + байты `info` (без заголовка).
/// An unmodeled attribute → `Raw`: name + `info` bytes (without the header).
pub(super) fn raw(attr: &RtAttr) -> Result<Attribute, ClassfileError> {
let mut bytes = Vec::new();
attr.to_bytes(&mut bytes)
@ -131,7 +131,7 @@ fn inner(
})
}
/// Метод объемлющего класса (`0` — только класс, без метода).
/// The enclosing class's method (`0` — class only, no method).
fn enclosing_method(
pool: &ConstantPool<'_>,
index: u16,
@ -194,7 +194,7 @@ fn bootstrap(
})
}
/// Индекс пула, где `0` означает отсутствие значения.
/// A pool index where `0` means the value is absent.
fn optional_class(pool: &ConstantPool<'_>, index: u16) -> Result<Option<String>, ClassfileError> {
if index == 0 {
Ok(None)
@ -203,7 +203,7 @@ fn optional_class(pool: &ConstantPool<'_>, index: u16) -> Result<Option<String>,
}
}
/// Индекс `CONSTANT_Utf8`, где `0` означает отсутствие значения.
/// A `CONSTANT_Utf8` index where `0` means the value is absent.
fn optional_utf8(pool: &ConstantPool<'_>, index: u16) -> Result<Option<String>, ClassfileError> {
if index == 0 {
Ok(None)

6
crates/noxis-classfile/src/format/parse/class.rs
View file

@ -1,4 +1,4 @@
//! Класс целиком: backend `ClassFile` → наш [`ClassFile`](crate::model::ClassFile).
//! The whole class: backend `ClassFile` → our [`ClassFile`](crate::model::ClassFile).
use ristretto_classfile::attributes::Attribute as RtAttr;
use ristretto_classfile::{
@ -11,7 +11,7 @@ use super::pool::{class_name, utf8};
use crate::error::ClassfileError;
use crate::model::{Attribute, ClassFile, Code, Field, Method, Version};
/// Разобрать байты `.class` в наш IR.
/// Parse `.class` bytes into our IR.
pub(crate) fn parse_class(bytes: &[u8]) -> Result<ClassFile, ClassfileError> {
let rt = RtClass::from_bytes(bytes).map_err(|e| ClassfileError::Parse(e.to_string()))?;
let pool = &rt.constant_pool;
@ -99,7 +99,7 @@ fn convert_attrs(
.collect()
}
/// Индекс суперкласса, где `0` — его отсутствие (`java/lang/Object`).
/// The superclass index, where `0` means absent (`java/lang/Object`).
fn optional_class(pool: &ConstantPool<'_>, index: u16) -> Result<Option<String>, ClassfileError> {
if index == 0 {
Ok(None)

15
crates/noxis-classfile/src/format/parse/code/frames.rs
View file

@ -1,7 +1,8 @@
//! Кадры `StackMapTable` при чтении: вариант в вариант, дельты как есть.
//! `StackMapTable` frames on read: variant to variant, deltas as-is.
//!
//! Backend хранит кадры в номерах инструкций (см. `from_bytes_code_attributes`),
//! наш IR — тоже: writer сам пересчитает их в байты при `to_bytes`.
//! The backend stores frames in instruction indices (see
//! `from_bytes_code_attributes`), and so does our IR: the writer recomputes them
//! into bytes on `to_bytes`.
use ristretto_classfile::ConstantPool;
use ristretto_classfile::attributes::{StackFrame, VerificationType as RtType};
@ -10,7 +11,7 @@ use super::super::pool::class_name;
use crate::error::ClassfileError;
use crate::format::{StackMapFrame, VerificationType};
/// Кадры backend'а → наши (индексные дельты — как есть).
/// Backend frames → ours (index deltas — as-is).
pub(super) fn to_frames(
frames: &[StackFrame],
pool: &ConstantPool<'_>,
@ -66,7 +67,7 @@ fn to_frame(frame: &StackFrame, pool: &ConstantPool<'_>) -> Result<StackMapFrame
})
}
/// Единственный элемент стека кадра (`same_locals_1_stack_item`).
/// The frame's single stack element (`same_locals_1_stack_item`).
fn single(stack: &[RtType], pool: &ConstantPool<'_>) -> Result<VerificationType, ClassfileError> {
let mut types = types(stack, pool)?.into_iter();
match (types.next(), types.next()) {
@ -84,7 +85,7 @@ fn types(
values.iter().map(|value| vtype(value, pool)).collect()
}
/// Тип верификации backend'а → наш тип (имя класса берётся из constant pool).
/// Backend verification type → our type (the class name comes from the constant pool).
fn vtype(value: &RtType, pool: &ConstantPool<'_>) -> Result<VerificationType, ClassfileError> {
Ok(match value {
RtType::Top => VerificationType::Top,
@ -99,7 +100,7 @@ fn vtype(value: &RtType, pool: &ConstantPool<'_>) -> Result<VerificationType, Cl
})
}
/// Тип перехвата (`0` — catch-all для `finally`/`any`).
/// The catch type (`0` — catch-all for `finally`/`any`).
pub(super) fn catch_type(
pool: &ConstantPool<'_>,
index: u16,

28
crates/noxis-classfile/src/format/parse/code/labels.rs
View file

@ -1,7 +1,7 @@
//! Метки тела метода: где обязаны стоять и как резолвятся.
//! Method-body labels: where they must stand and how they resolve.
//!
//! Backend нумерует инструкции по порядку — метки ставятся прямо на номера,
//! без байтовых смещений.
//! The backend numbers instructions in order — labels are placed directly on the
//! numbers, without byte offsets.
use std::collections::{BTreeMap, BTreeSet};
@ -11,10 +11,10 @@ use ristretto_classfile::attributes::{ExceptionTableEntry, Instruction};
use crate::error::ClassfileError;
use crate::insn::Label;
/// Номера инструкций, на которых обязана стоять метка.
/// Instruction numbers that must carry a label.
///
/// `extra` — позиции отладочных таблиц (уже номерами): вставки пассов
/// не должны оставлять их без меток.
/// `extra` — debug-table positions (already as numbers): pass insertions must
/// not leave them without a label.
pub(super) fn label_indexes(
code: &[Instruction],
exception_table: &[ExceptionTableEntry],
@ -36,7 +36,7 @@ pub(super) fn label_indexes(
Ok(indexes)
}
/// Цели ветвлений backend'а: для `if*`/`goto` — абсолютный номер, для `switch` — дельта.
/// Backend branch targets: for `if*`/`goto` an absolute number, for `switch` a delta.
fn branch_indexes(instruction: &Instruction, index: u16) -> Vec<i32> {
let base = i32::from(index);
match instruction {
@ -73,7 +73,7 @@ fn once(value: i32) -> std::iter::Once<i32> {
std::iter::once(value)
}
/// Превратить отсортированный набор номеров в последовательные метки.
/// Turn a sorted set of numbers into sequential labels.
pub(super) fn assign(indexes: &BTreeSet<u32>) -> BTreeMap<u32, Label> {
indexes
.iter()
@ -82,7 +82,7 @@ pub(super) fn assign(indexes: &BTreeSet<u32>) -> BTreeMap<u32, Label> {
.collect()
}
/// Метка для номера инструкции.
/// The label for an instruction number.
pub(super) fn lookup(labels: &BTreeMap<u32, Label>, index: u16) -> Result<Label, ClassfileError> {
labels
.get(&u32::from(index))
@ -90,7 +90,7 @@ pub(super) fn lookup(labels: &BTreeMap<u32, Label>, index: u16) -> Result<Label,
.ok_or_else(|| ClassfileError::Parse(format!("нет метки для инструкции {index}")))
}
/// Позиции отладочных таблиц, которым нужны метки.
/// Debug-table positions that need labels.
pub(super) fn collect_debug_labels(
attributes: &[RtAttr],
starts: &[u16],
@ -122,7 +122,7 @@ pub(super) fn collect_debug_labels(
Ok(())
}
/// Байт → номер инструкции (только границы инструкций).
/// Byte → instruction number (instruction boundaries only).
pub(super) fn byte_to_index(starts: &[u16], byte: u16) -> Result<u32, ClassfileError> {
starts
.iter()
@ -131,7 +131,7 @@ pub(super) fn byte_to_index(starts: &[u16], byte: u16) -> Result<u32, ClassfileE
.ok_or_else(|| ClassfileError::Parse(format!("смещение {byte} мимо инструкции")))
}
/// Конец диапазона `[start, start+length)`: индекс за концом.
/// End of the range `[start, start+length)`: the index past the end.
fn end_index(
starts: &[u16],
start: u16,
@ -148,7 +148,7 @@ fn end_index(
byte_to_index(starts, end)
}
/// Метка для байтового смещения отладочной таблицы.
/// The label for a debug table's byte offset.
pub(super) fn resolve_byte(
labels: &BTreeMap<u32, Label>,
starts: &[u16],
@ -161,7 +161,7 @@ pub(super) fn resolve_byte(
.ok_or_else(|| ClassfileError::Parse(format!("нет метки для смещения {byte}")))
}
/// Метка конца диапазона отладочной таблицы.
/// The end label of a debug table's range.
pub(super) fn resolve_end(
labels: &BTreeMap<u32, Label>,
starts: &[u16],

16
crates/noxis-classfile/src/format/parse/code/mod.rs
View file

@ -1,10 +1,10 @@
//! `Code` backend'а → тело метода нашего IR: метки, исключения, кадры.
//! Backend `Code` → our IR method body: labels, exceptions, frames.
//!
//! Backend уже перевёл байтовые смещения в номера инструкций — конвертеры
//! работают прямо с ними: метки ставятся на целях переходов, границах
//! try-блоков и позициях отладочных таблиц; кадры переносятся как есть
//! (индексные дельты). Позиции `LineNumberTable`/`LocalVariableTable` —
//! тоже метки, поэтому вставки пассов их не ломают (байты досчитает writer).
//! The backend already turned byte offsets into instruction indices — the
//! converters work directly with them: labels are placed on branch targets,
//! try-block boundaries and debug-table positions; frames are carried over as-is
//! (index deltas). `LineNumberTable`/`LocalVariableTable` positions are labels
//! too, so pass insertions don't break them (the writer recomputes the bytes).
mod frames;
mod labels;
@ -27,7 +27,7 @@ use crate::model::{
use frames::{catch_type, to_frames};
use labels::{assign, collect_debug_labels, label_indexes, lookup, resolve_byte, resolve_end};
/// Тело метода целиком: backend `Code` → наш [`Code`].
/// The whole method body: backend `Code` → our [`Code`].
pub(super) fn convert_code(
max_stack: u16,
max_locals: u16,
@ -150,7 +150,7 @@ pub(super) fn convert_code(
})
}
/// Байтовые смещения инструкций и длина тела метода.
/// Instruction byte offsets and the method body length.
fn layout(code: &[Instruction]) -> Result<(Vec<u16>, u16), ClassfileError> {
let mut cursor = Cursor::new(Vec::new());
let mut offsets = Vec::with_capacity(code.len());

4
crates/noxis-classfile/src/format/parse/insns/basic.rs
View file

@ -1,4 +1,4 @@
//! Простые инструкции без ссылок на пул (кроме `ldc`) и без ветвлений.
//! Simple instructions with no pool references (except `ldc`) and no branches.
use ristretto_classfile::ConstantPool;
use ristretto_classfile::attributes::Instruction;
@ -7,7 +7,7 @@ use super::super::pool::const_from;
use crate::error::ClassfileError;
use crate::insn::{Arith, ArrayKind, Const, Convert, Insn, Prim, SlotKind};
/// `Some` — инструкция покрыта, `None` — отдать следующим конвертерам.
/// `Some` — the instruction is covered; `None` — hand it to the next converters.
pub(super) fn convert_basic(
instruction: &Instruction,
pool: &ConstantPool<'_>,

6
crates/noxis-classfile/src/format/parse/insns/flow.rs
View file

@ -1,4 +1,4 @@
//! Ветвления, `switch` и возвраты: абсолютные/относительные цели → метки.
//! Branches, `switch` and returns: absolute/relative targets → labels.
use ristretto_classfile::attributes::{Instruction, LookupSwitch, TableSwitch};
@ -6,7 +6,7 @@ use super::Resolver;
use crate::error::ClassfileError;
use crate::insn::{BranchCond, Cond, Insn, Label, Prim};
/// `Some` — инструкция покрыта, `None` — отдать следующим конвертерам.
/// `Some` — the instruction is covered; `None` — hand it to the next converters.
pub(super) fn convert_flow(
instruction: &Instruction,
index: u16,
@ -52,7 +52,7 @@ fn branch(cond: BranchCond, target: u16, resolve: &Resolver<'_>) -> Result<Insn,
Ok(Insn::Branch(cond, resolve(target)?))
}
/// Цель `switch` — номер инструкции: база плюс относительная дельта backend'а.
/// A `switch` target — an instruction number: base plus the backend's relative delta.
fn abs(index: u16, delta: i32, resolve: &Resolver<'_>) -> Result<Label, ClassfileError> {
let absolute = i32::from(index)
.checked_add(delta)

13
crates/noxis-classfile/src/format/parse/insns/mod.rs
View file

@ -1,9 +1,8 @@
//! `Instruction` backend'а → [`Insn`](crate::insn::Insn) нашего IR.
//! Backend `Instruction` → [`Insn`](crate::insn::Insn) of our IR.
//!
//! Смещения ветвлений приходят из backend'а (абсолютные для `if*`/`goto`,
//! относительные от начала инструкции для `switch`), поэтому конвертация
//! принимает резолвер смещения в [`Label`](crate::insn::Label) — метки
//! назначает вызывающий код.
//! Branch offsets come from the backend (absolute for `if*`/`goto`, relative to
//! the instruction start for `switch`), so conversion takes a resolver from an
//! offset to a [`Label`](crate::insn::Label) — the calling code assigns labels.
mod basic;
mod flow;
@ -15,10 +14,10 @@ use ristretto_classfile::attributes::Instruction;
use crate::error::ClassfileError;
use crate::insn::{Insn, Label};
/// Резолвит абсолютное смещение байткода в метку.
/// Resolves an absolute bytecode offset into a label.
pub(super) type Resolver<'a> = dyn Fn(u16) -> Result<Label, ClassfileError> + 'a;
/// Конвертировать одну инструкцию. `index` — её номер в теле метода (нужно `switch`).
/// Convert one instruction. `index` — its number in the method body (`switch` needs it).
pub(super) fn convert(
instruction: &Instruction,
index: u16,

4
crates/noxis-classfile/src/format/parse/insns/refs.rs
View file

@ -1,4 +1,4 @@
//! Поля, вызовы и создание объектов: индексы пула → строки IR.
//! Fields, calls and object creation: pool indices → IR strings.
use ristretto_classfile::ConstantPool;
use ristretto_classfile::attributes::{ArrayType, Instruction};
@ -7,7 +7,7 @@ use super::super::pool::{class_name, dynamic_parts, expect_kind, is_interface, r
use crate::error::ClassfileError;
use crate::insn::{ArrayKind, Insn, InvokeKind};
/// `Some` — инструкция покрыта, `None` — отдать следующим конвертерам.
/// `Some` — the instruction is covered; `None` — hand it to the next converters.
pub(super) fn convert_ref(
instruction: &Instruction,
pool: &ConstantPool<'_>,

10
crates/noxis-classfile/src/format/parse/mod.rs
View file

@ -1,9 +1,9 @@
//! Backend `ristretto_classfile` → наш IR: пул, инструкции, тела методов.
//! Backend `ristretto_classfile` → our IR: pool, instructions, method bodies.
//!
//! Пока ниоткуда не подключён (P1): `format` вернёт `Unimplemented`, пока не
//! будут готовы `parse`/`write` классового уровня поверх этих конвертеров.
//! Дерево уже разбито по ответственностям, чтобы подключение было одним
//! `mod parse` без рефакторинга.
//! Not wired in from anywhere yet (P1): `format` returns `Unimplemented` until
//! class-level `parse`/`write` are ready on top of these converters. The tree
//! is already split by responsibility so wiring is a single `mod parse` with no
//! refactoring.
pub(super) mod attrs;
pub(super) mod class;

26
crates/noxis-classfile/src/format/parse/pool.rs
View file

@ -1,11 +1,11 @@
//! Разрешение индексов constant pool в строки нашего IR.
//! Resolving constant-pool indices into strings of our IR.
use ristretto_classfile::{Constant, ConstantPool, ReferenceKind};
use crate::error::ClassfileError;
use crate::insn::{Const, InvokeKind};
/// Имя класса по `CONSTANT_Class`.
/// The class name from a `CONSTANT_Class`.
pub(super) fn class_name(pool: &ConstantPool<'_>, index: u16) -> Result<String, ClassfileError> {
let name = pool
.try_get_class(index)
@ -13,7 +13,7 @@ pub(super) fn class_name(pool: &ConstantPool<'_>, index: u16) -> Result<String,
Ok(name.to_string())
}
/// `(owner, name, descriptor)` для `CONSTANT_Fieldref`/`_Methodref`.
/// `(owner, name, descriptor)` for a `CONSTANT_Fieldref`/`_Methodref`.
pub(super) fn ref_parts(
pool: &ConstantPool<'_>,
index: u16,
@ -45,7 +45,7 @@ pub(super) fn ref_parts(
Ok((owner, name, descriptor))
}
/// `(name, descriptor)` для `CONSTANT_NameAndType`.
/// `(name, descriptor)` for a `CONSTANT_NameAndType`.
pub(super) fn name_and_type(
pool: &ConstantPool<'_>,
index: u16,
@ -58,7 +58,7 @@ pub(super) fn name_and_type(
Ok((name, descriptor))
}
/// Строка из `CONSTANT_Utf8`.
/// The string from a `CONSTANT_Utf8`.
pub(super) fn utf8(pool: &ConstantPool<'_>, index: u16) -> Result<String, ClassfileError> {
let value = pool
.try_get_utf8(index)
@ -66,7 +66,7 @@ pub(super) fn utf8(pool: &ConstantPool<'_>, index: u16) -> Result<String, Classf
Ok(value.to_string())
}
/// Константа для `ldc`/`ldc_w`/`ldc2_w`.
/// The constant for `ldc`/`ldc_w`/`ldc2_w`.
pub(super) fn const_from(pool: &ConstantPool<'_>, index: u16) -> Result<Const, ClassfileError> {
let constant = pool
.try_get(index)
@ -111,7 +111,7 @@ pub(super) fn const_from(pool: &ConstantPool<'_>, index: u16) -> Result<Const, C
})
}
/// `(name, descriptor, bootstrap)` для `CONSTANT_InvokeDynamic`.
/// `(name, descriptor, bootstrap)` for a `CONSTANT_InvokeDynamic`.
pub(super) fn dynamic_parts(
pool: &ConstantPool<'_>,
index: u16,
@ -134,12 +134,12 @@ pub(super) fn dynamic_parts(
Ok((name, descriptor, bootstrap))
}
/// Вид вызова по индексу ссылки: интерфейсная или обычная.
/// Call kind by reference index: interface or regular.
pub(super) fn is_interface(pool: &ConstantPool<'_>, index: u16) -> bool {
matches!(pool.try_get(index), Ok(Constant::InterfaceMethodRef { .. }))
}
/// JVMS §5.4.3.5: номер `reference_kind` для `CONSTANT_MethodHandle`.
/// JVMS §5.4.3.5: the `reference_kind` number for a `CONSTANT_MethodHandle`.
pub(super) fn kind_code(kind: &ReferenceKind) -> u8 {
match kind {
ReferenceKind::GetField => 1,
@ -154,11 +154,11 @@ pub(super) fn kind_code(kind: &ReferenceKind) -> u8 {
}
}
/// Проверка, что `Invoke` действительно ссылается на ожидаемый вид.
/// Checks that an `Invoke` really refers to the expected kind.
///
/// JVM принимает `Methodref` и `InterfaceMethodref` для всех видов вызова,
/// кроме `invokeinterface` (там только интерфейсная); строгость сверх JVM
/// ломает чтение реальных классов (статические методы интерфейсов).
/// The JVM accepts both `Methodref` and `InterfaceMethodref` for every call
/// kind except `invokeinterface` (interface reference only there); being
/// stricter than the JVM breaks reading real classes (interface static methods).
pub(super) fn expect_kind(
pool: &ConstantPool<'_>,
index: u16,

16
crates/noxis-classfile/src/format/write/attrs.rs
View file

@ -1,7 +1,7 @@
//! Атрибуты нашего IR → атрибуты backend'а.
//! Our IR attributes → backend attributes.
//!
//! Имена атрибутов (`SourceFile`, …) интернируются в пул здесь же — backend
//! хранит только `name_index`, строка восстанавливается при чтении.
//! Attribute names (`SourceFile`, …) are interned into the pool right here — the
//! backend stores only `name_index`, and the string is recovered on read.
use ristretto_classfile::attributes::{
Attribute as RtAttr, LineNumber as RtLine, LocalVariableTable as RtLocal,
@ -14,13 +14,13 @@ use crate::error::ClassfileError;
use crate::insn::Label;
use crate::model::{Attribute, LineNumber, LocalVariable, LocalVariableType};
/// Позиции таблиц кода: метки → байты текущего layout.
/// Code-table positions: labels → bytes of the current layout.
pub(super) struct Positions<'a> {
pub resolve: &'a dyn Fn(Label) -> Result<u32, ClassfileError>,
pub byte_of: &'a dyn Fn(u32) -> Result<u16, ClassfileError>,
}
/// `LineNumberTable`: backend хранит номера инструкций и маппит сам.
/// `LineNumberTable`: the backend stores instruction numbers and maps them itself.
pub(super) fn line_number_table(
lines: &[LineNumber],
pool: &mut Pool,
@ -43,7 +43,7 @@ pub(super) fn line_number_table(
})
}
/// `LocalVariableTable`/`TypeTable` с пересчётом диапазона.
/// `LocalVariableTable`/`TypeTable` with the range recomputed.
pub(super) fn local_table(
vars: &[LocalVariable],
pool: &mut Pool,
@ -66,7 +66,7 @@ pub(super) fn local_table(
.collect::<Result<_, ClassfileError>>()?,
})
}
/// Та же таблица для типов (`signature` вместо дескриптора).
/// The same table for types (`signature` instead of a descriptor).
pub(super) fn local_type_table(
vars: &[LocalVariableType],
pool: &mut Pool,
@ -103,7 +103,7 @@ fn range(
Ok((first, length))
}
/// Один наш атрибут → атрибут backend'а.
/// One of our attributes → a backend attribute.
pub(super) fn convert(attr: &Attribute, pool: &mut Pool) -> Result<RtAttr, ClassfileError> {
Ok(match attr {
Attribute::SourceFile(name) => RtAttr::SourceFile {

22
crates/noxis-classfile/src/format/write/code/frames.rs
View file

@ -1,9 +1,9 @@
//! Кадры `StackMapTable` при записи: вариант в вариант, дельты по инструкциям.
//! `StackMapTable` frames on write: variant to variant, deltas per instruction.
//!
//! Наш IR хранит `offset_delta` в номерах инструкций; backend при `to_bytes`
//! сам пересчитает их в байты. Компактный формат (`Same`/`SameLocals`) годен
//! только когда **байтовая** дельта ≤ 63 — иначе нужен расширенный вариант.
//! Выбор делаем по байтовой дельте: байты считаются от layout текущего метода.
//! Our IR stores `offset_delta` in instruction numbers; the backend recomputes
//! them into bytes on `to_bytes`. The compact form (`Same`/`SameLocals`) is valid
//! only when the **byte** delta is ≤ 63 — otherwise the extended form is needed.
//! We choose by the byte delta: bytes are computed from the current method's layout.
use ristretto_classfile::attributes::{StackFrame as RtFrame, VerificationType as RtType};
@ -11,10 +11,10 @@ use super::super::pool::Pool;
use crate::error::ClassfileError;
use crate::format::{StackMapFrame, VerificationType};
/// Байтовое смещение начала инструкции (для расчёта дельт кадров).
/// The byte offset of an instruction's start (for computing frame deltas).
type ByteOf<'a> = &'a (dyn Fn(u32) -> Result<u16, ClassfileError> + 'a);
/// Кадры IR → кадры backend'а (индексные дельты — как есть).
/// IR frames → backend frames (index deltas — as-is).
pub(super) fn convert_frames(
frames: &[StackMapFrame],
pool: &mut Pool,
@ -32,7 +32,7 @@ pub(super) fn convert_frames(
last_instruction + delta + 1
};
let byte = byte_of(instruction)?;
// Байтовая дельта относительно конца предыдущего кадра.
// Byte delta relative to the end of the previous frame.
let byte_delta = if first {
byte
} else {
@ -48,7 +48,7 @@ pub(super) fn convert_frames(
Ok(out)
}
/// `byte_delta` — истинная байтовая дельта; компактный вид годен лишь при ≤ 63.
/// `byte_delta` is the true byte delta; the compact form is valid only when ≤ 63.
fn build_frame(
frame: &StackMapFrame,
pool: &mut Pool,
@ -60,8 +60,8 @@ fn build_frame(
Ok(match frame {
StackMapFrame::Same { .. } => {
if byte_delta <= 63 {
// Backend при verify()/to_bytes читает frame_type как дельту по
// ИНСТРУКЦИЯМ и сам пересчитает её в байты (≤ 63 — влезает).
// The backend, in verify()/to_bytes, reads frame_type as a delta by
// INSTRUCTION and recomputes it into bytes itself (≤ 63 fits).
RtFrame::SameFrame {
frame_type: delta as u8,
}

14
crates/noxis-classfile/src/format/write/code/insns.rs
View file

@ -1,8 +1,8 @@
//! Наш [`Insn`](crate::insn::Insn) → `Instruction` backend'а.
//! Our [`Insn`](crate::insn::Insn) → the backend's `Instruction`.
//!
//! Обратная сторона `super::super::parse::insns`: метки резолвятся в
//! абсолютные номера инструкций (`switch` — в дельты от себя), константы
//! и ссылки уходят в пул через [`Pool`](super::super::pool::Pool).
//! The reverse side of `super::super::parse::insns`: labels resolve into
//! absolute instruction numbers (`switch` — into deltas from itself), constants
//! and references go to the pool via [`Pool`](super::super::pool::Pool).
use indexmap::IndexMap;
use ristretto_classfile::attributes::{Instruction as RtInsn, LookupSwitch, TableSwitch};
@ -13,9 +13,9 @@ use super::{branch, delta, fit_index, ret_op};
use crate::error::ClassfileError;
use crate::insn::{Insn, Label, SlotKind};
/// Одна инструкция IR → инструкция backend'а (`None` — маркер метки).
/// One IR instruction → a backend instruction (`None` — a label marker).
///
/// `index` — номер инструкции в методе (нужен `switch`-дельтам).
/// `index` — the instruction's number in the method (needed for `switch` deltas).
pub(crate) fn convert(
insn: &Insn,
index: u32,
@ -178,7 +178,7 @@ fn store(slot: u16, kind: SlotKind) -> RtInsn {
}
}
/// Короткая форма при слоте ≤255, иначе `wide`-форма.
/// The short form when the slot is ≤255, otherwise the `wide` form.
fn narrow(slot: u16, short: fn(u8) -> RtInsn, wide: fn(u16) -> RtInsn) -> RtInsn {
u8::try_from(slot).map(short).unwrap_or_else(|_| wide(slot))
}

26
crates/noxis-classfile/src/format/write/code/mod.rs
View file

@ -1,7 +1,7 @@
//! Тело метода нашего IR → атрибут `Code` backend'а.
//! Our IR method body → the backend `Code` attribute.
//!
//! Метки резолвятся в номера инструкций один раз здесь; дальше backend сам
//! пересчитывает номера в байтовые смещения при `to_bytes`.
//! Labels resolve into instruction numbers once, here; then the backend
//! recomputes numbers into byte offsets on `to_bytes`.
mod frames;
pub(crate) mod insns;
@ -22,7 +22,7 @@ use crate::model::{Attribute, Code, ExceptionHandler};
use frames::convert_frames;
/// Тело метода → готовый атрибут `Code` (с логическими номерами инструкций).
/// Method body → a ready `Code` attribute (with logical instruction numbers).
pub(super) fn convert_code(code: &Code, pool: &mut Pool) -> Result<RtAttr, ClassfileError> {
let (labels, bare) = split_marks(&code.insns)?;
let resolve = |label: Label| -> Result<u32, ClassfileError> {
@ -59,7 +59,7 @@ pub(super) fn convert_code(code: &Code, pool: &mut Pool) -> Result<RtAttr, Class
let mut attributes = Vec::with_capacity(code.attributes.len() + 1);
for attr in &code.attributes {
attributes.push(match attr {
// Backend хранит номера строк в индексах и маппит сам.
// The backend stores line numbers as indices and maps them itself.
Attribute::LineNumberTable(lines) => attrs::line_number_table(lines, pool, &positions)?,
Attribute::LocalVariableTable(vars) => attrs::local_table(vars, pool, &positions)?,
Attribute::LocalVariableTypeTable(vars) => {
@ -84,7 +84,7 @@ pub(super) fn convert_code(code: &Code, pool: &mut Pool) -> Result<RtAttr, Class
})
}
/// Метки → номера инструкций; сами маркеры из потока убираются.
/// Labels → instruction numbers; the markers themselves are removed from the stream.
fn split_marks(insns: &[Insn]) -> Result<(BTreeMap<Label, u32>, Vec<&Insn>), ClassfileError> {
let mut labels = BTreeMap::new();
let mut bare = Vec::with_capacity(insns.len());
@ -108,10 +108,10 @@ fn split_marks(insns: &[Insn]) -> Result<(BTreeMap<Label, u32>, Vec<&Insn>), Cla
Ok((labels, bare))
}
/// Номер инструкции → байтовое смещение (замер с заглушками целей).
/// Instruction number → byte offset (measured with placeholder targets).
///
/// В карту входит и конец кода (`len` → длина): концы диапазонов указывают
/// за последнюю инструкцию.
/// The map also includes the code end (`len` → length): range ends point past
/// the last instruction.
pub(crate) fn measure(insns: &[RtInsn]) -> Result<BTreeMap<u32, u16>, ClassfileError> {
let mut map = BTreeMap::new();
let mut cursor = Cursor::new(Vec::new());
@ -132,7 +132,7 @@ pub(crate) fn measure(insns: &[RtInsn]) -> Result<BTreeMap<u32, u16>, ClassfileE
Ok(map)
}
/// Цели ветвлений не влияют на размер — подменяем текущей позицией для замера.
/// Branch targets don't affect size — substitute the current position for sizing.
fn smash_targets(insn: &mut RtInsn, position: u16) {
match insn {
RtInsn::Ifeq(target)
@ -178,7 +178,7 @@ fn entry(
})
}
/// Условный переход IR → `if*` backend'а.
/// An IR conditional branch → the backend's `if*`.
fn branch(cond: BranchCond, target: u32) -> Result<RtInsn, ClassfileError> {
let target = fit_index(target)?;
Ok(match cond {
@ -211,13 +211,13 @@ fn ret_op(prim: Option<Prim>) -> RtInsn {
}
}
/// Номер инструкции обязан влезать в `u16` (метод < 64 КБ кода).
/// The instruction number must fit in `u16` (method < 64 KB of code).
fn fit_index(index: u32) -> Result<u16, ClassfileError> {
u16::try_from(index)
.map_err(|_| ClassfileError::Write(format!("номер инструкции {index} вне u16")))
}
/// Дельта `switch`: цель минус позиция самого `switch`.
/// A `switch` delta: the target minus the `switch` instruction's own position.
fn delta(index: u32, target: u32) -> Result<i32, ClassfileError> {
let (index, target) = (to_i32(index)?, to_i32(target)?);
target

8
crates/noxis-classfile/src/format/write/code/ops.rs
View file

@ -1,4 +1,4 @@
//! Операнды: константы, арифметика, массивы, вызовы.
//! Operands: constants, arithmetic, arrays, calls.
use ristretto_classfile::attributes::{ArrayType, Instruction as RtInsn};
@ -6,7 +6,7 @@ use super::super::pool::Pool;
use crate::error::ClassfileError;
use crate::insn::{Arith, ArrayKind, Const, Convert, InvokeKind, Prim};
/// Константа: короткие формы (`iconst`, `bipush`) + `ldc_w`/`ldc2_w` через пул.
/// A constant: short forms (`iconst`, `bipush`) + `ldc_w`/`ldc2_w` through the pool.
pub(super) fn int_const(value: &Const, pool: &mut Pool) -> Result<RtInsn, ClassfileError> {
Ok(match value {
Const::Int(v) => match *v {
@ -188,7 +188,7 @@ pub(super) fn invoke(
})
}
/// Байт `count` для `invokeinterface`: слоты аргументов + `objectref`.
/// The `count` byte for `invokeinterface`: argument slots + `objectref`.
fn arg_count(descriptor: &str) -> Result<u8, ClassfileError> {
let params = descriptor
.split_once('(')
@ -229,7 +229,7 @@ fn arg_count(descriptor: &str) -> Result<u8, ClassfileError> {
.map_err(|_| ClassfileError::Write(format!("слишком много аргументов в {descriptor}")))
}
/// Пропустить символы до разделителя (включительно); `false` — строка кончилась.
/// Skip characters up to the separator (inclusive); `false` — the string ended.
fn skip_to(chars: &mut std::str::Chars<'_>, end: char) -> bool {
for char in chars {
if char == end {

11
crates/noxis-classfile/src/format/write/helpers.rs
View file

@ -1,8 +1,9 @@
//! Хелперы сборки `InnerClasses`/`BootstrapMethods`/`MethodParameters`.
//! Helpers building `InnerClasses`/`BootstrapMethods`/`MethodParameters`.
//!
//! Вынесены из `attrs`, чтобы тот держался в лимите 250 строк; логика не
//! изменилась — только место. Каждый строит запись backend'а из элемента IR,
//! интернируя имена/дескрипторы и резолвя индексы `CONSTANT_Class` через пул.
//! Moved out of `attrs` so it stays within the 250-line limit; the logic is
//! unchanged — only the location. Each builds a backend entry from an IR
//! element, interning names/descriptors and resolving `CONSTANT_Class` indices
//! through the pool.
use ristretto_classfile::MethodAccessFlags;
use ristretto_classfile::attributes::{
@ -50,7 +51,7 @@ pub(super) fn bootstrap(
})
}
/// Аргумент bootstrap-метода: те же константы, что в `ldc`, плюс `Dynamic`.
/// A bootstrap-method argument: the same constants as in `ldc`, plus `Dynamic`.
fn bootstrap_arg(arg: &Const, pool: &mut Pool) -> Result<u16, ClassfileError> {
match arg {
Const::Dynamic {

8
crates/noxis-classfile/src/format/write/mod.rs
View file

@ -1,7 +1,7 @@
//! Наш IR → байты `.class` через backend `ristretto_classfile`.
//! Our IR → `.class` bytes through the `ristretto_classfile` backend.
//!
//! Пул собирается с нуля детерминированным обходом; backend сам пересчитывает
//! номера инструкций в байтовые смещения и проверяет результат (`verify`).
//! The pool is built from scratch by a deterministic walk; the backend recomputes
//! instruction numbers into byte offsets and verifies the result (`verify`).
mod attrs;
pub(crate) mod code;
@ -16,7 +16,7 @@ use ristretto_classfile::{
use crate::error::ClassfileError;
use crate::model::{ClassFile, Field, Method};
/// Класс нашего IR → байты `.class`.
/// Our IR class → `.class` bytes.
pub(crate) fn write_class(class: &ClassFile) -> Result<Vec<u8>, ClassfileError> {
let mut pool = pool::Pool::new();
let version = RtVersion::from(class.version.major, class.version.minor)

28
crates/noxis-classfile/src/format/write/pool/mod.rs
View file

@ -1,15 +1,15 @@
//! Сборка constant pool при записи: строки нашего IR → индексы backend'а.
//! Building the constant pool on write: our IR strings → backend indices.
//!
//! Пул строится с нуля детерминированным обходом (классы, поля, методы,
//! атрибуты, код), поэтому одинаковый IR даёт одинаковые байты. Индексы
//! `Raw`-атрибутов при этом не переносятся — см. `super::attrs`.
//! The pool is built from scratch by a deterministic walk (classes, fields,
//! methods, attributes, code), so identical IR yields identical bytes. `Raw`
//! attribute indices are not carried over — see `super::attrs`.
//!
//! Backend не дедуплицирует: `add_*` всегда толкает новый элемент. Кэшируем
//! семантические ключи сами — иначе `LocalVariableTable` и
//! `LocalVariableTypeTable` получат разные `name_index` для одного имени, и
//! HotSpot отвергнет класс (`LVTT entry ... does not match any LVT entry`).
//! Порядок обхода детерминирован, поэтому кэш меняет только компактность пула.
//! Референсы (поле/метод/хендл/динамик) — в [`refs`].
//! The backend does not deduplicate: `add_*` always pushes a new entry. We cache
//! semantic keys ourselves — otherwise `LocalVariableTable` and
//! `LocalVariableTypeTable` would get different `name_index` values for the same
//! name, and HotSpot would reject the class (`LVTT entry ... does not match any
//! LVT entry`). The walk order is deterministic, so the cache only changes pool
//! compactness. References (field/method/handle/dynamic) live in [`refs`].
use std::collections::HashMap;
@ -20,7 +20,7 @@ use crate::insn::Const;
mod refs;
/// Строитель пула; живёт только внутри одного `write`.
/// The pool builder; lives only within a single `write`.
pub(crate) struct Pool {
pub(super) pool: ConstantPool<'static>,
pub(super) utf8s: HashMap<String, u16>,
@ -68,8 +68,8 @@ impl Pool {
if let Some(&index) = self.name_types.get(&key) {
return Ok(index);
}
// Собираем из примитивов, а не `add_name_and_type`: последний толкает
// собственные `Utf8`-строки мимо нашего кэша (дубли в пуле).
// Build from primitives, not `add_name_and_type`: the latter pushes its
// own `Utf8` strings past our cache (pool duplicates).
let name_index = self.utf8(name)?;
let descriptor_index = self.utf8(descriptor)?;
let index = self
@ -96,7 +96,7 @@ impl Pool {
Ok(index)
}
/// Константа для `ldc`/`ldc2_w`; `dynamic` запрещён (только через bootstrap).
/// A constant for `ldc`/`ldc2_w`; `dynamic` is forbidden (bootstrap only).
pub(super) fn constant(&mut self, value: &Const) -> Result<u16, ClassfileError> {
match value {
Const::Int(v) => self.pool.add_integer(*v).map_err(write_err),

12
crates/noxis-classfile/src/format/write/pool/refs.rs
View file

@ -1,10 +1,10 @@
//! Референсы constant pool: `Fieldref`/`Methodref`/`MethodHandle`/`Dynamic`.
//! Constant-pool references: `Fieldref`/`Methodref`/`MethodHandle`/`Dynamic`.
//!
//! Это `impl Pool` из [`super`]; вынесено отдельно, чтобы материнский файл
//! держался в лимите структуры. Каждый билдер мемоизирован по семантическому
//! ключу (owner/name/descriptor/…) — одинаковая ссылка всегда получает один
//! индекс, а пул не раздувается дублями (раздувание иначе расширяет `ldc`
//! в `ldc_w` и меняет длину кода при переносе).
//! This is an `impl Pool` from [`super`], split out so the parent file stays
//! within the structure limit. Each builder is memoized by a semantic key
//! (owner/name/descriptor/…) — an identical reference always gets the same index,
//! and the pool doesn't bloat with duplicates (bloat would otherwise widen `ldc`
//! into `ldc_w` and change code length on relocation).
use ristretto_classfile::{Constant, ReferenceKind};

32
crates/noxis-classfile/src/insn/kinds.rs
View file

@ -1,9 +1,9 @@
//! Типы операндов инструкций: константы, примитивы, условия, вызовы.
//! Instruction operand types: constants, primitives, conditions, calls.
/// Идентификатор метки внутри одного метода.
/// A label identifier within a single method.
pub type Label = u32;
/// Константа для `ldc`/`ldc_w`/`ldc2_w`.
/// A constant for `ldc`/`ldc_w`/`ldc2_w`.
#[derive(Debug, Clone, PartialEq)]
pub enum Const {
Int(i32),
@ -11,7 +11,7 @@ pub enum Const {
Float(f32),
Double(f64),
String(String),
/// Внутреннее имя класса (`java/lang/String`).
/// The class's internal name (`java/lang/String`).
Class(String),
MethodType(String),
MethodHandle {
@ -21,7 +21,7 @@ pub enum Const {
descriptor: String,
itf: bool,
},
/// `CONSTANT_Dynamic`: имя, дескриптор, индекс bootstrap-метода.
/// `CONSTANT_Dynamic`: name, descriptor, bootstrap-method index.
Dynamic {
name: String,
descriptor: String,
@ -29,7 +29,7 @@ pub enum Const {
},
}
/// Размер операнда/результата арифметики.
/// Operand/result size of an arithmetic operation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Prim {
Int,
@ -38,7 +38,7 @@ pub enum Prim {
Double,
}
/// Арифметическая/битовая операция; тип берётся из [`Prim`].
/// An arithmetic/bitwise operation; the type comes from [`Prim`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Arith {
Add,
@ -55,7 +55,7 @@ pub enum Arith {
Ushr,
}
/// Условие перехода.
/// A branch condition.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Cond {
Eq,
@ -66,10 +66,10 @@ pub enum Cond {
Ge,
}
/// Вид условного перехода (соответствует семействам `if*`).
/// Kind of conditional branch (matches the `if*` families).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BranchCond {
/// `if<cond>` относительно нуля.
/// `if<cond>` against zero.
Zero(Cond),
/// `if_icmp<cond>`.
Int(Cond),
@ -79,7 +79,7 @@ pub enum BranchCond {
Null { is_null: bool },
}
/// Вид вызова.
/// Kind of call.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum InvokeKind {
Virtual,
@ -88,7 +88,7 @@ pub enum InvokeKind {
Interface,
}
/// Конверсия типов (`i2l`, `f2b`, ... — JVMS §6.5.i2<b|c|s|l|f|d>).
/// Type conversion (`i2l`, `f2b`, ... — JVMS §6.5.i2<b|c|s|l|f|d>).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Convert {
I2L,
@ -108,7 +108,7 @@ pub enum Convert {
D2F,
}
/// Тип элемента массива для `newarray`/`*aload`/`*astore`.
/// Array element type for `newarray`/`*aload`/`*astore`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ArrayKind {
Boolean,
@ -122,10 +122,10 @@ pub enum ArrayKind {
Reference,
}
/// Тип слота локальной переменной для `*load*`/`*store*`.
/// Local-variable slot type for `*load*`/`*store*`.
///
/// Хранится явно: выбор опкода (`iload` vs `aload`) — подсказка верификатору,
/// потерять её при round-trip нельзя.
/// Stored explicitly: the opcode choice (`iload` vs `aload`) is a hint to the
/// verifier, and losing it on a round-trip is not acceptable.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SlotKind {
Int,

40
crates/noxis-classfile/src/insn/mod.rs
View file

@ -1,7 +1,7 @@
//! Инструкции IR: смещения отсутствуют, ветвления адресуют [`Label`].
//! IR instructions: no offsets, branches address a [`Label`].
//!
//! Это принципиально: любой пасс, меняющий порядок/длину инструкций, не обязан
//! пересчитывать jump-офсеты — это делает writer один раз в конце пайплайна.
//! This is fundamental: any pass that changes instruction order/length need not
//! recompute jump offsets — the writer does that once at the end of the pipeline.
mod kinds;
@ -9,32 +9,32 @@ pub use kinds::{
Arith, ArrayKind, BranchCond, Cond, Const, Convert, InvokeKind, Label, Prim, SlotKind,
};
/// Мнемоника одной инструкции.
/// Mnemonic of a single instruction.
#[derive(Debug, Clone, PartialEq)]
pub enum Insn {
/// Маркер метки. Ветвления указывают на [`Label`], writer вычисляет смещения.
/// Label marker. Branches point at a [`Label`]; the writer computes offsets.
Mark(Label),
Nop,
AconstNull,
Const(Const),
/// Загрузка локальной переменной (`iload`, `aload`, ...).
/// Load a local variable (`iload`, `aload`, ...).
Load {
slot: u16,
kind: SlotKind,
},
/// Сохранение локальной переменной.
/// Store a local variable.
Store {
slot: u16,
kind: SlotKind,
},
/// `iinc` — увеличение локальной переменной на константу.
/// `iinc` — increase a local variable by a constant.
Iinc {
index: u16,
delta: i32,
},
/// Загрузка элемента массива.
/// Load an array element.
ArrayLoad(ArrayKind),
/// Сохранение элемента массива.
/// Store an array element.
ArrayStore(ArrayKind),
Pop,
Pop2,
@ -45,23 +45,23 @@ pub enum Insn {
Dup2X1,
Dup2X2,
Swap,
/// `iadd`, `lmul`, `lneg`, ... — тип + операция.
/// `iadd`, `lmul`, `lneg`, ... — type + operation.
Binary {
prim: Prim,
op: Arith,
},
/// Сравнение длин (`lcmp`) и плавающих (`fcmpl`/`fcmpg`).
/// Comparison of longs (`lcmp`) and floats (`fcmpl`/`fcmpg`).
Cmp {
prim: Prim,
nan_great: bool,
},
/// Конверсия типов (`i2l`, `d2f`, ...).
/// Type conversion (`i2l`, `d2f`, ...).
Convert(Convert),
Branch(BranchCond, Label),
Goto(Label),
/// `jsr` — вызов подпрограммы (только классы версии ≤ 50).
/// `jsr` — subroutine call (only version ≤ 50 classes).
Jsr(Label),
/// `ret` — возврат из подпрограммы (`jsr`/`ret` парны).
/// `ret` — return from a subroutine (`jsr`/`ret` come in pairs).
Ret(u16),
TableSwitch {
default: Label,
@ -73,9 +73,9 @@ pub enum Insn {
default: Label,
pairs: Vec<(i32, Label)>,
},
/// `return`/`ireturn`/...; `None` — пустой возврат.
/// `return`/`ireturn`/...; `None` — void return.
Return(Option<Prim>),
/// `areturn` — возврат ссылки (у [`Prim`] нет ссылочного типа).
/// `areturn` — return a reference ([`Prim`] has no reference type).
AReturn,
GetStatic {
owner: String,
@ -112,7 +112,7 @@ pub enum Insn {
New(String),
NewArray(ArrayKind),
ANewArray(String),
/// `multianewarray` — массив любого измерения; `dims` — сколько измерений со стека.
/// `multianewarray` — array of any dimension; `dims` — how many dimensions from the stack.
MultiANewArray {
descriptor: String,
dims: u8,
@ -126,7 +126,7 @@ pub enum Insn {
}
impl Insn {
/// Метки, на которые ссылается инструкция (для построения CFG).
/// Labels the instruction references (for building the CFG).
pub fn targets(&self) -> Vec<Label> {
match self {
Insn::Branch(_, label) | Insn::Goto(label) | Insn::Jsr(label) => vec![*label],
@ -154,7 +154,7 @@ impl Insn {
}
}
/// Незакодированный переход (для вставки opaque-предикатов и перестройки CFG).
/// An encoded jump target (for inserting opaque predicates and rebuilding the CFG).
pub fn branch_target_mut(&mut self) -> Option<&mut Label> {
match self {
Insn::Branch(_, label) | Insn::Goto(label) => Some(label),

12
crates/noxis-classfile/src/lib.rs
View file

@ -1,13 +1,13 @@
//! # noxis-classfile
//!
//! Собственный IR для классовых файлов JVM: разбор, представление, запись.
//! Own IR for JVM class files: parsing, representation, writing.
//!
//! Почему свой IR, а не работа напрямую с крейтом-парсером: пассам нужна
//! стабильная модель (метки вместо смещений, осознанный набор атрибутов),
//! а не API третьей стороны, который меняется между версиями.
//! Why a custom IR instead of working directly with a parser crate: passes
//! need a stable model (labels instead of offsets, a deliberate attribute
//! set), not a third-party API that changes between versions.
//!
//! Статус: модель и билдер готовы, бинарный parse/write — этап P1
//! (см. `docs/stack.md`).
//! Status: model and builder are ready; binary parse/write is stage P1
//! (see `docs/stack.md`).
pub mod error;
pub mod format;

26
crates/noxis-classfile/src/model/builder.rs
View file

@ -1,8 +1,8 @@
//! Сборка классов «с нуля»: junk-классы, рантайм-декодеры, аннотации-шум.
//! Building classes "from scratch": junk classes, runtime decoders, noise annotations.
use crate::model::{Attribute, ClassFile, Code, Field, Method, Version};
/// Строитель класса без бинарного представления на входе.
/// A class builder with no binary representation on input.
#[derive(Debug, Clone)]
pub struct ClassBuilder {
version: Version,
@ -16,8 +16,8 @@ pub struct ClassBuilder {
}
impl ClassBuilder {
/// Новый класс `public` с указанным суперклассом (`None` = `java/lang/Object`,
/// кроме самого `java/lang/Object` — у него суперкласса нет).
/// A new `public` class with the given superclass (`None` = `java/lang/Object`,
/// except for `java/lang/Object` itself — it has no superclass).
pub fn new(this_class: impl Into<String>, super_class: Option<&str>) -> Self {
let this_class = this_class.into();
let super_class = match super_class {
@ -37,25 +37,25 @@ impl ClassBuilder {
}
}
/// Задать версию классового файла.
/// Set the class-file version.
pub fn version(mut self, version: Version) -> Self {
self.version = version;
self
}
/// Задать флаги доступа (перезаписывает `ACC_PUBLIC|ACC_SUPER`).
/// Set access flags (overwrites `ACC_PUBLIC|ACC_SUPER`).
pub fn access_flags(mut self, flags: u16) -> Self {
self.access_flags = flags;
self
}
/// Добавить интерфейс.
/// Add an interface.
pub fn interface(mut self, name: impl Into<String>) -> Self {
self.interfaces.push(name.into());
self
}
/// Добавить поле.
/// Add a field.
pub fn field(mut self, name: impl Into<String>, descriptor: impl Into<String>) -> Self {
self.fields.push(Field {
access_flags: 0x0001, // ACC_PUBLIC
@ -66,7 +66,7 @@ impl ClassBuilder {
self
}
/// Добавить метод без тела (`abstract`/`native` должны выставить флаги сами).
/// Add a method without a body (`abstract`/`native` must set their own flags).
pub fn method(
mut self,
access_flags: u16,
@ -83,7 +83,7 @@ impl ClassBuilder {
self
}
/// Добавить метод с телом.
/// Add a method with a body.
pub fn method_with_code(
mut self,
access_flags: u16,
@ -101,13 +101,13 @@ impl ClassBuilder {
self
}
/// Добавить атрибут уровня класса.
/// Add a class-level attribute.
pub fn attribute(mut self, attribute: Attribute) -> Self {
self.attributes.push(attribute);
self
}
/// Собрать класс.
/// Build the class.
pub fn build(self) -> ClassFile {
ClassFile {
version: self.version,
@ -122,7 +122,7 @@ impl ClassBuilder {
}
}
/// Пустое тело метода (`return`), для junk-методов.
/// An empty method body (`return`), for junk methods.
pub fn empty_code(max_locals: u16) -> Code {
Code {
max_stack: 0,

68
crates/noxis-classfile/src/model/mod.rs
View file

@ -1,4 +1,4 @@
//! Структура «программы» — единица работы пайплайна.
//! The "program" structure — the unit of work for the pipeline.
pub mod builder;
pub mod version;
@ -8,7 +8,7 @@ pub use version::Version;
use crate::format::StackMapFrame;
use crate::insn::{Const, Insn, Label};
/// Неизвестные/специфичные атрибуты хранятся байтами — round-trip без потерь.
/// Unknown/specific attributes are stored as bytes — lossless round-trip.
#[derive(Debug, Clone, PartialEq)]
pub enum Attribute {
SourceFile(String),
@ -19,26 +19,26 @@ pub enum Attribute {
Deprecated,
Synthetic,
InnerClasses(Vec<InnerClass>),
/// `NestHost`: класс, служащий nest-хостом (JVMS §4.7.28).
/// `NestHost`: the class acting as nest host (JVMS §4.7.28).
NestHost(String),
/// `NestMembers`: классы-члены этого nest-хоста (JVMS §4.7.29).
/// `NestMembers`: the member classes of this nest host (JVMS §4.7.29).
NestMembers(Vec<String>),
/// `ConstantValue` поля (`static final`): значение из пула.
/// A field's `ConstantValue` (`static final`): a value from the pool.
ConstantValue(Const),
/// `BootstrapMethods` для `invokedynamic` (лямбды): метод + аргументы.
/// `BootstrapMethods` for `invokedynamic` (lambdas): method + arguments.
BootstrapMethods(Vec<BootstrapMethod>),
/// `EnclosingMethod`: класс и опциональный метод, содержащие локальный класс.
/// `EnclosingMethod`: the class and optional method enclosing a local class.
EnclosingMethod {
class: String,
method: Option<(String, String)>,
},
/// `MethodParameters`: имена формальных параметров (`None` — безымянный).
/// `MethodParameters`: formal parameter names (`None` — unnamed).
MethodParameters(Vec<MethodParameter>),
/// `Record`: компоненты record-класса.
/// `Record`: the record class's components.
Record(Vec<RecordComponent>),
/// `LocalVariableTypeTable`: сигнатуры generic-локальных (как LVT).
/// `LocalVariableTypeTable`: generic local signatures (like LVT).
LocalVariableTypeTable(Vec<LocalVariableType>),
/// Всё остальное: имя + сырые байты `info` (осторожно с индексами пула).
/// Everything else: name + raw `info` bytes (careful with pool indices).
Raw {
name: String,
data: Vec<u8>,
@ -47,14 +47,14 @@ pub enum Attribute {
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct LineNumber {
/// Метка начала (байты вычисляет writer — переживает вставки пассов).
/// Start label (the writer computes bytes — survives pass insertions).
pub start: Label,
pub line: u16,
}
#[derive(Debug, Clone, PartialEq)]
pub struct LocalVariable {
/// Метки диапазона видимости (writer пересчитает в байты).
/// Visibility-range labels (the writer recomputes them into bytes).
pub start: Label,
pub end: Label,
pub name: String,
@ -70,10 +70,10 @@ pub struct InnerClass {
pub access_flags: u16,
}
/// Один `bootstrap`-метод: ссылка вида `MethodHandle` + аргументы-константы.
/// One `bootstrap` method: a `MethodHandle`-style reference + const arguments.
#[derive(Debug, Clone, PartialEq)]
pub struct BootstrapMethod {
/// Номер `reference_kind` (JVMS §5.4.3.5).
/// The `reference_kind` number (JVMS §5.4.3.5).
pub kind: u8,
pub owner: String,
pub name: String,
@ -82,14 +82,14 @@ pub struct BootstrapMethod {
pub args: Vec<Const>,
}
/// Формальный параметр метода (`MethodParameters`).
/// A method's formal parameter (`MethodParameters`).
#[derive(Debug, Clone, PartialEq)]
pub struct MethodParameter {
pub name: Option<String>,
pub access_flags: u16,
}
/// Компонент `Record`: поле record-класса с атрибутами.
/// A `Record` component: a record class field with attributes.
#[derive(Debug, Clone, PartialEq)]
pub struct RecordComponent {
pub name: String,
@ -97,10 +97,10 @@ pub struct RecordComponent {
pub attributes: Vec<Attribute>,
}
/// Строка `LocalVariableTypeTable` (как `LocalVariable`, но с сигнатурой).
/// A `LocalVariableTypeTable` entry (like `LocalVariable`, but with a signature).
#[derive(Debug, Clone, PartialEq)]
pub struct LocalVariableType {
/// Метки диапазона видимости (writer пересчитает в байты).
/// Visibility-range labels (the writer recomputes them into bytes).
pub start: Label,
pub end: Label,
pub name: String,
@ -126,18 +126,18 @@ pub struct Method {
}
impl Method {
/// `native`/`abstract` тела не имеют.
/// `native`/`abstract` methods have no body.
pub fn has_code(&self) -> bool {
self.code.is_some()
}
}
/// Тело метода.
/// A method body.
#[derive(Debug, Clone, PartialEq)]
pub struct Code {
pub max_stack: u16,
pub max_locals: u16,
/// Маркеры меток + инструкции; ветвления указывают на [`Label`].
/// Label markers + instructions; branches point at a [`Label`].
pub insns: Vec<Insn>,
pub exception_table: Vec<ExceptionHandler>,
pub frames: Vec<StackMapFrame>,
@ -145,7 +145,7 @@ pub struct Code {
}
impl Code {
/// Все метки, объявленные в теле метода.
/// All labels declared in the method body.
pub fn labels(&self) -> Vec<Label> {
self.insns
.iter()
@ -163,11 +163,11 @@ pub struct ExceptionHandler {
pub start: Label,
pub end: Label,
pub handler: Label,
/// Внутреннее имя класса или `None` для `any`.
/// The class's internal name, or `None` for `any`.
pub catch_type: Option<String>,
}
/// Один `.class` в нормализованном виде.
/// One `.class` in normalized form.
#[derive(Debug, Clone, PartialEq)]
pub struct ClassFile {
pub version: Version,
@ -181,34 +181,34 @@ pub struct ClassFile {
}
impl ClassFile {
/// Ищет метод по имени и дескриптору.
/// Finds a method by name and descriptor.
pub fn method(&self, name: &str, descriptor: &str) -> Option<&Method> {
self.methods
.iter()
.find(|m| m.name == name && m.descriptor == descriptor)
}
/// Ищет метод по имени и дескриптору (мутирующий доступ).
/// Finds a method by name and descriptor (mutating access).
pub fn method_mut(&mut self, name: &str, descriptor: &str) -> Option<&mut Method> {
self.methods
.iter_mut()
.find(|m| m.name == name && m.descriptor == descriptor)
}
/// Признак `ACC_INTERFACE`.
/// The `ACC_INTERFACE` flag.
pub fn is_interface(&self) -> bool {
self.access_flags & 0x0200 != 0
}
}
/// Ресурс внутри архива (JSON, properties, картинки, ...).
/// A resource inside the archive (JSON, properties, images, ...).
#[derive(Debug, Clone, PartialEq)]
pub struct Resource {
pub path: String,
pub data: Vec<u8>,
}
/// Вся входная программа: классы + ресурсы.
/// The whole input program: classes + resources.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Program {
pub classes: Vec<ClassFile>,
@ -216,24 +216,24 @@ pub struct Program {
}
impl Program {
/// Класс по внутреннему имени (`pkg/Class`).
/// A class by internal name (`pkg/Class`).
pub fn class(&self, internal_name: &str) -> Option<&ClassFile> {
self.classes.iter().find(|c| c.this_class == internal_name)
}
/// Класс по внутреннему имени (мутирующий доступ).
/// A class by internal name (mutating access).
pub fn class_mut(&mut self, internal_name: &str) -> Option<&mut ClassFile> {
self.classes
.iter_mut()
.find(|c| c.this_class == internal_name)
}
/// Ресурс по пути внутри архива.
/// A resource by its path inside the archive.
pub fn resource(&self, path: &str) -> Option<&Resource> {
self.resources.iter().find(|r| r.path == path)
}
/// Пустая ли программа.
/// Whether the program is empty.
pub fn is_empty(&self) -> bool {
self.classes.is_empty() && self.resources.is_empty()
}

4
crates/noxis-classfile/src/model/version.rs
View file

@ -1,6 +1,6 @@
//! Версия классового файла (major/minor).
//! Class-file version (major/minor).
/// Версия классового файла.
/// The class-file version.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Version {
pub minor: u16,

89
crates/noxis-core/src/config/sections.rs
View file

@ -1,49 +1,50 @@
//! Секции конфигурации: стили имён и настройки отдельных пассов.
//! Config sections: name styles and per-pass settings.
use serde::{Deserialize, Serialize};
/// Стиль генерации имён.
/// Name generation style.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum NameStyle {
/// `a`, `b`, ... `aa` — короткие латинские.
/// `a`, `b`, ... `aa` — short Latin.
ShortLatin,
/// `I`, `l`, `O`, `0` — визуально одинаковые.
/// `I`, `l`, `O`, `0` — visually identical.
IlO0,
/// Случайные unicode-имена (суррогаты допустимы в modified UTF-8).
/// Random Unicode names (surrogates are valid in modified UTF-8).
Unicode,
/// Смешанная латиница средней длины.
/// Medium-length mixed-case Latin.
#[default]
MixedLatin,
/// Псевдосмысленные слова из другого проекта (дезориентация).
/// Pseudo-meaningful words from another project (misdirection).
DecoyWords,
/// Правдоподобные имена: `TextureCache`, `resolveToken` — вместо
/// явного мусора маскируется под обычный прикладной код.
/// Plausible names: `TextureCache`, `resolveToken` — blends in as
/// ordinary application code instead of obvious noise.
Plausible,
}
/// Настройки переименования.
/// Rename pass settings.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RenameConfig {
/// Переименовывать пакеты в случайные пути.
/// Scatter packages into random paths.
pub spread_packages: bool,
/// Размер пула случайных пакетов.
/// Size of the random package pool.
pub package_pool: usize,
/// Стиль имён классов.
/// Name style for classes.
pub class_style: NameStyle,
/// Стиль имён полей и методов.
/// Name style for fields and methods.
pub member_style: NameStyle,
/// Стиль имён локальных переменных и параметров.
/// Name style for local variables and parameters.
pub local_style: NameStyle,
/// Делать члены `public` (чтобы не ломать inheritance между пакетами).
/// Widen members to `public` (so moving to a new package doesn't break
/// inheritance).
pub widen_access: bool,
/// Переименовывать enum-константы.
/// Rename enum constants.
pub rename_enum_constants: bool,
/// Переименовывать локальные переменные и параметры.
/// Rename local variables and parameters.
pub rename_locals: bool,
/// Переименовывать и не-private члены (агрессивно: безопасно для приложений,
/// опасно для библиотек и кода с рефлексией).
/// Also rename non-private members (aggressive: safe for applications,
/// dangerous for libraries and reflection-heavy code).
pub rename_public_members: bool,
}
@ -63,19 +64,20 @@ impl Default for RenameConfig {
}
}
/// Настройки шифрования строк.
/// String encryption settings.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct StringsConfig {
/// Схемы шифра, между которыми перемешиваются строки.
/// Cipher schemes strings are rotated across.
pub schemes: Vec<String>,
/// Строки короче этого не шифруются.
/// Strings shorter than this are not encrypted.
pub min_len: usize,
/// Дробить длинные строки на чанки (меньше похоже на пул).
/// Split long strings into chunks (looks less like a string pool).
pub split_above: usize,
/// Не шифровать строки, совпадающие с этими паттернами.
/// Don't encrypt strings matching these patterns.
pub skip: Vec<String>,
/// Вычислять ключ из KDF(class, method, index), а не класть рядом с текстом.
/// Derive the key from KDF(class, method, index) instead of placing it
/// next to the ciphertext.
pub derive_key: bool,
}
@ -91,15 +93,15 @@ impl Default for StringsConfig {
}
}
/// Настройки обфускации контрольного потока.
/// Control-flow obfuscation settings.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct FlowConfig {
/// Схемы, между которыми выбирается случайно по методу.
/// Schemes picked randomly per method.
pub schemes: Vec<String>,
/// Не трогать методы больше этого числа инструкций (бюджет размера).
/// Don't touch methods larger than this many instructions (size budget).
pub max_insns: usize,
/// Вплетать opaque-предикаты в тела блоков.
/// Weave opaque predicates into block bodies.
pub encrypt_block_bodies: bool,
}
@ -118,15 +120,15 @@ impl Default for FlowConfig {
}
}
/// Настройки шифрования констант.
/// Constant encryption settings.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct ConstantsConfig {
/// Схемы разбиения (`xor`, `add`, `shift`), выбор по RNG на константу.
/// Splitting schemes (`xor`, `add`, `shift`), picked by RNG per constant.
pub schemes: Vec<String>,
/// Вставлять opaque-предикаты (не больше этого на метод).
/// Insert opaque predicates (at most this many per method).
pub max_predicates: usize,
/// Не трогать константы в этих классах (префиксы внутренних имён).
/// Don't touch constants in these classes (internal-name prefixes).
pub skip: Vec<String>,
}
@ -140,15 +142,16 @@ impl Default for ConstantsConfig {
}
}
/// Настройки шума.
/// Noise pass settings.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct NoiseConfig {
/// Сколько junk-классов на каждый настоящий (0 = выключено).
/// How many junk classes per real one (0 = disabled).
pub junk_ratio: usize,
/// Число junk-аннотаций на класс.
/// Number of junk annotations per class.
pub junk_annotations: usize,
/// Вплетать junk-классы в граф достижимости (обязательно для осмысленности).
/// Weave junk classes into the reachability graph (required for them to
/// make sense).
pub weave_reachable: bool,
}
@ -162,17 +165,17 @@ impl Default for NoiseConfig {
}
}
/// Настройки отладочной информации.
/// Debug info pass settings.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct DebugConfig {
/// Удалять `LineNumberTable`.
/// Strip `LineNumberTable`.
pub strip_line_numbers: bool,
/// Удалять `LocalVariableTable`.
/// Strip `LocalVariableTable`.
pub strip_local_variables: bool,
/// Подменять `SourceFile` на ложное имя.
/// Replace `SourceFile` with a fake name.
pub spoof_source_file: bool,
/// Удалять `Signature`/`InnerClasses`/`EnclosingMethod`.
/// Strip `Signature`/`InnerClasses`/`EnclosingMethod`.
pub strip_signatures: bool,
}

33
crates/noxis-passes/src/constants/forms.rs
View file

@ -1,14 +1,13 @@
//! Схемы разбиения констант и opaque-предикаты.
//! Constant-splitting schemes and opaque predicates.
//!
//! Целые константы вне `iconst`-диапазона заменяются тройками (`x^k`,
//! `a+b`, сдвиг); opaque-предикат — всегда истинное условие с мёртвой
//! ветвью из одного `nop` (валидно, не исполняется, ломает линейный
//! дисассемблирование).
//! Integer constants outside the `iconst` range are replaced by triples
//! (`x^k`, `a+b`, shift); an opaque predicate is an always-true condition with
//! a one-`nop` dead branch (valid, never executed, breaks linear disassembly).
use noxis_classfile::{Arith, BranchCond, Cond, Const, Insn, Prim};
use noxis_core::Rng;
/// Схема разбиения (имена из `ConstantsConfig::schemes`).
/// Splitting scheme (names from `ConstantsConfig::schemes`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum Scheme {
Xor,
@ -27,7 +26,7 @@ impl Scheme {
}
}
/// Разбить `int`-константу на вычисляющую её тройку.
/// Split an `int` constant into a triple that computes it.
pub(super) fn encrypt_int(value: i32, scheme: Scheme, rng: &mut Rng) -> Vec<Insn> {
let (first, second) = match scheme {
Scheme::Xor => {
@ -50,7 +49,7 @@ pub(super) fn encrypt_int(value: i32, scheme: Scheme, rng: &mut Rng) -> Vec<Insn
}
}
/// Разбить `long`-константу (те же три схемы на `l*`-опкодах).
/// Split a `long` constant (the same three schemes on `l*` opcodes).
pub(super) fn encrypt_long(value: i64, scheme: Scheme, rng: &mut Rng) -> Vec<Insn> {
let (first, second) = match scheme {
Scheme::Xor => {
@ -73,7 +72,7 @@ pub(super) fn encrypt_long(value: i64, scheme: Scheme, rng: &mut Rng) -> Vec<Ins
}
}
/// `(a, b, op)` как три инструкции.
/// `(a, b, op)` as three instructions.
fn binary(first: i32, second: i32, op: Arith, prim: Prim) -> Vec<Insn> {
vec![
Insn::Const(Const::Int(first)),
@ -93,7 +92,7 @@ fn binary_long(first: i64, second: i64, op: Arith) -> Vec<Insn> {
]
}
/// `v = ((v >> 1) << 1) | (v & 1)` — работает для любых, включая отрицательные.
/// `v = ((v >> 1) << 1) | (v & 1)` — works for any value, including negatives.
fn shift_form(value: i32) -> Vec<Insn> {
vec![
Insn::Const(Const::Int(value >> 1)),
@ -110,7 +109,7 @@ fn shift_form(value: i32) -> Vec<Insn> {
]
}
/// То же для `long` (величина сдвига — всегда `int`!).
/// The same for `long` (the shift amount is always an `int`!).
fn shift_form_long(value: i64) -> Vec<Insn> {
vec![
Insn::Const(Const::Long(value >> 1)),
@ -127,13 +126,18 @@ fn shift_form_long(value: i64) -> Vec<Insn> {
]
}
/// Opaque-предикат `(C*C + C) & 1 == 0` (истина для любого `C`):
/// `[pred, ifne DEAD, goto MERGE, DEAD: nop, MERGE:]`, дальше — оригинал.
/// Opaque predicate `(C*C + C) & 1 == 0` (true for any `C`).
///
/// Метки выдаёт вызывающий код (свободные номера метода).
/// Stack-neutral and leaves control flow unchanged: the computed value is
/// consumed by a branch that never fires; the dead `DEAD: nop` branch only
/// bloats linear disassembly.
///
/// Pattern: `[pred..., ifne DEAD, goto MERGE, DEAD: nop, MERGE:]`.
/// Labels come from the calling code (free method numbers).
pub(super) fn opaque_true(dead: u32, merge: u32, rng: &mut Rng) -> Vec<Insn> {
let constant = rng.next_u64() as i32;
vec![
// P = ((C*C) + C) & 1 — even, so always 0.
Insn::Const(Const::Int(constant)),
Insn::Dup,
Insn::Binary {
@ -150,6 +154,7 @@ pub(super) fn opaque_true(dead: u32, merge: u32, rng: &mut Rng) -> Vec<Insn> {
prim: Prim::Int,
op: Arith::And,
},
// P != 0 never holds — the branch into DEAD is not taken, value popped.
Insn::Branch(BranchCond::Zero(Cond::Ne), dead),
Insn::Goto(merge),
Insn::Mark(dead),

77
crates/noxis-passes/src/namegen/alphabet.rs
View file

@ -1,9 +1,9 @@
//! Алфавиты, ключевые слова и запрещённые имена.
//! Alphabets, keywords and forbidden names.
//!
//! Списки вынесены отдельно: к ним обращаются и генератор, и пасс
//! переименования (резервирование keep-имён).
//! Kept in their own file because both the generator and the rename pass
//! reach into them (reserving keep-listed names before generation starts).
/// Жёсткие ключевые слова Java: имя класса/метода не может им совпадать.
/// Hard Java keywords: a class/method name can never collide with these.
pub(super) const KEYWORDS: &[&str] = &[
"abstract",
"assert",
@ -66,8 +66,8 @@ pub(super) const KEYWORDS: &[&str] = &[
"yield",
];
/// Имена, которые не стоит затирать: мешают читать/логировать и ловятся
/// инструментами до любой деобфускации.
/// Names not worth overwriting: they'd hurt readability/logging and get
/// flagged by tooling before any deobfuscation even starts.
pub(super) const AVOID_CLASS: &[&str] = &[
"Object",
"String",
@ -101,9 +101,9 @@ pub(super) const AVOID_MEMBER: &[&str] = &[
pub(super) const LATIN_LOWER: &[u8] = b"abcdefghijklmnopqrstuvwxyz";
pub(super) const LATIN_UPPER: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ";
/// Визуально неразличимые символы — ядро стиля `IlO0`.
/// Visually indistinguishable characters: the core of the `IlO0` style.
pub(super) const CONFUSABLE: &[u8] = b"IlO01";
/// Unicode-буквы, валидные как Java-идентификаторы (Cyrillic/Greek/CJK).
/// Unicode letters valid in a Java identifier (Cyrillic/Greek/CJK).
pub(super) const UNICODE_LETTERS: &[char] = &[
'а', 'б', 'в', 'г', 'д', 'е', 'ж', 'з', 'и', 'к', 'л', 'м', 'н', 'п', 'р', 'с', 'т', 'у', 'ф',
'х', 'ц', 'ч', 'ш', 'щ', 'э', 'ю', 'я', 'α', 'β', 'γ', 'δ', 'ε', 'ζ', 'η', 'θ', 'λ', 'μ', 'π',
@ -118,15 +118,58 @@ pub(super) const DECOY_RIGHT: &[&str] = &[
"ripple",
];
/// Стиль `Plausible`: домен-нейтральные существительные для классов/полей —
/// похожи на обычный прикладной код, не привязаны к конкретному проекту.
/// `Plausible` style word bank. Mixes domain-neutral software nouns with
/// terms that are boring, structural scaffolding in the client/mod
/// ecosystem noxis is actually used on (see
/// `/storage/project/jvm/LoVisual/ref/clients/*`: `Module`, `Setting`,
/// `Event`, `Mixin`, `Manager`, `Component`, `Accessor`, `Hud`, `Overlay`,
/// `Theme`, `Timer`, `Animation`, `Rotation` all show up dozens of times
/// across real client codebases). Deliberately excludes anything that
/// itself reads as a "feature flag" worth an analyst's attention (no
/// `Esp`/`Aimbot`/`KillAura`/`Chams`): a decoy name that announces
/// "interesting code lives here" defeats the point of blending in.
pub(super) const PLAUSIBLE_NOUN: &[&str] = &[
"Texture", "Event", "State", "Render", "Asset", "Config", "Session", "Cache", "Buffer",
"Socket", "Stream", "Widget", "Layout", "Theme", "Profile", "Metric", "Token", "Handle",
"Context", "Registry", "Request", "Response", "Payload", "Resource", "Snapshot", "Pipeline",
"Queue", "Slot", "Frame", "Entry",
"Texture",
"Event",
"State",
"Render",
"Asset",
"Config",
"Session",
"Cache",
"Buffer",
"Socket",
"Stream",
"Widget",
"Layout",
"Theme",
"Profile",
"Metric",
"Token",
"Handle",
"Context",
"Registry",
"Request",
"Response",
"Payload",
"Resource",
"Snapshot",
"Pipeline",
"Queue",
"Slot",
"Frame",
"Entry",
"Module",
"Setting",
"Overlay",
"Hud",
"Component",
"Accessor",
"Timer",
"Animation",
"Rotation",
];
/// Суффиксы ролей для классов (`NounSuffix`, напр. `TextureCache`).
/// Role suffixes for classes (`NounSuffix`, e.g. `TextureCache`).
pub(super) const PLAUSIBLE_SUFFIX: &[&str] = &[
"Manager",
"Handler",
@ -148,8 +191,10 @@ pub(super) const PLAUSIBLE_SUFFIX: &[&str] = &[
"Processor",
"Context",
"Listener",
"Mixin",
"Component",
];
/// Глаголы для методов/полей (`verbNoun`, напр. `resolveToken`).
/// Verbs for methods/fields (`verbNoun`, e.g. `resolveToken`).
pub(super) const PLAUSIBLE_VERB: &[&str] = &[
"get", "set", "update", "process", "handle", "compute", "resolve", "load", "build", "parse",
"fetch", "apply", "validate", "clear", "reset", "sync", "flush", "bind", "attach", "detach",

24
crates/noxis-passes/src/namegen/mod.rs
View file

@ -1,4 +1,4 @@
//! Генерация имён: стили, анти-ключевые слова, уникальность в scope.
//! Name generation: styles, anti-keyword checks, uniqueness within a scope.
pub mod alphabet;
#[cfg(test)]
@ -13,18 +13,18 @@ use self::alphabet::{
LATIN_UPPER, PLAUSIBLE_NOUN, PLAUSIBLE_SUFFIX, PLAUSIBLE_VERB, UNICODE_LETTERS,
};
/// Генератор имён с гарантированной уникальностью в пределах одного scope.
/// Name generator with guaranteed uniqueness within a single scope.
pub struct NameGenerator {
rng: Rng,
style: NameStyle,
used: HashSet<String>,
/// Счётчик-страховка, если случайные варианты исчерпаны.
/// Fallback counter for when the random pool is exhausted.
fallback: u64,
avoid_class: bool,
}
impl NameGenerator {
/// Генератор для указанного стиля.
/// Generator for the given style.
pub fn new(rng: Rng, style: NameStyle) -> Self {
Self {
rng,
@ -35,18 +35,18 @@ impl NameGenerator {
}
}
/// Режим «имена классов»: дополнительно избегаем имён из JDK/аннотаций.
/// "Class name" mode: additionally avoid names from the JDK/annotations.
pub fn for_classes(mut self) -> Self {
self.avoid_class = true;
self
}
/// Занять конкретное имя (защита от коллизий с keep-именами).
/// Reserve a specific name (protects against collisions with keep-listed names).
pub fn reserve(&mut self, name: impl Into<String>) {
self.used.insert(name.into());
}
/// Следующее свободное имя.
/// The next free name.
pub fn next_name(&mut self) -> String {
for _ in 0..64 {
let candidate = self.candidate();
@ -55,7 +55,7 @@ impl NameGenerator {
return candidate;
}
}
// Страховка: детерминированный счётчик, гарантированно уникален.
// Fallback: a deterministic counter, guaranteed unique.
loop {
self.fallback += 1;
let candidate = format!("{}{}", self.style_prefix(), self.fallback);
@ -95,7 +95,7 @@ impl NameGenerator {
};
let idx = self.rng.below(alpha.len() as u64) as usize;
let ch = alpha[idx] as char;
// Первый символ — только буква (не цифра).
// First character must be a letter, not a digit.
if i == 0 && !ch.is_ascii_alphabetic() {
out.push('a');
} else {
@ -123,9 +123,9 @@ impl NameGenerator {
}
name
}
// Маскируется под обычный прикладной код, а не под мусор:
// классы — `NounSuffix` (`TextureCache`), члены — `verbNoun`
// (`resolveToken`) camelCase.
// Blends in as ordinary application code instead of obvious
// noise: classes get `NounSuffix` (`TextureCache`), members get
// camelCase `verbNoun` (`resolveToken`).
NameStyle::Plausible => {
let noun = PLAUSIBLE_NOUN[self.rng.below(PLAUSIBLE_NOUN.len() as u64) as usize];
if self.avoid_class {

6
crates/noxis-passes/src/namegen/tests.rs
View file

@ -1,4 +1,4 @@
//! Тесты генератора имён: уникальность, валидность, форма по стилю.
//! Name generator tests: uniqueness, validity, per-style shape.
#![allow(clippy::expect_used, clippy::unwrap_used)]
@ -15,7 +15,7 @@ fn names_are_unique_and_valid() {
let mut seen = HashSet::new();
for _ in 0..500 {
let name = names.next_name();
assert!(seen.insert(name.clone()), "повтор имени {name}");
assert!(seen.insert(name.clone()), "duplicate name {name}");
assert!(!KEYWORDS.contains(&name.as_str()));
assert!(name.starts_with(|c: char| c.is_ascii_alphabetic()));
}
@ -57,7 +57,7 @@ fn plausible_class_names_look_like_noun_suffix() {
for _ in 0..50 {
let name = names.next_name();
assert!(name.starts_with(|c: char| c.is_ascii_uppercase()), "{name}");
// Два слова подряд слиплись в CamelCase без разделителей.
// Two words run together in CamelCase with no separator.
assert!(
name.chars().filter(|c| c.is_ascii_uppercase()).count() >= 2,
"{name}"

29
crates/noxis-passes/src/rename/assign.rs
View file

@ -1,5 +1,5 @@
//! Назначение новых имён: карты, семейства виртуальных методов,
//! пул пакетов и финальное ширинирование доступа.
//! Assigning new names: maps, virtual method families, the package pool,
//! and final access widening.
use std::collections::{BTreeMap, BTreeSet};
@ -10,11 +10,11 @@ use noxis_core::{Config, Context, NameStyle, Rng};
use super::{ACC_PRIVATE, ACC_PROTECTED, ACC_PUBLIC, ACC_STATIC};
use crate::namegen::NameGenerator;
/// `(owner, name, descriptor)` — как в JVM-ссылке.
/// `(owner, name, descriptor)` — matches a JVM reference.
pub(super) type MemberKey = (String, String, String);
/// Карты переименований одного прогона: `declared` — где объявлено,
/// `alias` — наследники, которые наследуют это имя без своего объявления.
/// Rename maps for one run: `declared` is where a member was declared,
/// `alias` is subclasses that inherit the name without declaring it themselves.
#[derive(Debug, Default)]
pub(super) struct RenameMaps {
pub(super) classes: BTreeMap<String, String>,
@ -41,7 +41,7 @@ impl RenameMaps {
.cloned()
}
/// Псевдоними: наследник вызывает член, объявленный в предке.
/// Aliases: a subclass calls a member declared on a parent class.
pub(super) fn expand(&mut self, hierarchy: &ClassHierarchy, owners: &[String]) {
let methods: Vec<(MemberKey, String)> = self
.methods
@ -85,8 +85,8 @@ impl RenameMaps {
}
}
/// Переименование виртуальных методов «семейством»: одно имя на всю иерархию,
/// включая мостовые методы с ковариантным возвратом.
/// Rename virtual methods as a "family": one name for the whole hierarchy,
/// including bridge methods with covariant returns.
pub(super) fn rename_virtual_families(
program: &Program,
analysis: &Analysis,
@ -94,8 +94,8 @@ pub(super) fn rename_virtual_families(
cfg: &Config,
ctx: &mut Context,
) -> usize {
// Семейство = (имя, параметры): возврат игнорируем — так захватываем
// ковариантные возвраты и мостовые методы (`ACC_BRIDGE`) разом.
// Family = (name, params): the return type is ignored, so covariant
// returns and bridge methods (`ACC_BRIDGE`) are captured together.
let mut families: BTreeMap<(String, String), Vec<MemberKey>> = BTreeMap::new();
let mut locked_families: BTreeSet<(String, String)> = BTreeSet::new();
@ -149,7 +149,7 @@ pub(super) fn rename_virtual_families(
renamed
}
/// `(<params>)<ret>` → `(<params>)`, либо `None`, если дескриптор кривой.
/// `(<params>)<ret>` → `(<params>)`, or `None` if the descriptor is malformed.
fn params_of(descriptor: &str) -> Option<String> {
let close = descriptor.find(')')?;
if !descriptor.starts_with('(') {
@ -172,7 +172,8 @@ pub(super) fn simple_name(internal: &str) -> String {
}
}
/// Пул случайных пакетов (2–3 сегмента); при выключенном разбросе — один пустой.
/// Pool of random packages (2-3 segments); a single empty one when spreading
/// is turned off.
pub(super) fn generate_packages(cfg: &Config, rng: &mut Rng) -> Vec<String> {
if !cfg.rename.spread_packages {
return vec![String::new()];
@ -194,7 +195,7 @@ pub(super) fn generate_packages(cfg: &Config, rng: &mut Rng) -> Vec<String> {
.collect()
}
/// Переписать дескриптор/сигнатуру: `Lpkg/Class;` → новое имя класса.
/// Rewrite a descriptor/signature: `Lpkg/Class;` → the new class name.
pub(super) fn rewrite_descriptor(desc: &str, classes: &BTreeMap<String, String>) -> String {
if !desc.contains('L') {
return desc.to_string();
@ -220,7 +221,7 @@ pub(super) fn rewrite_descriptor(desc: &str, classes: &BTreeMap<String, String>)
out
}
/// Расширить доступ до `public`, чтобы переезд в другой пакет не ломал вызовы.
/// Widen access to `public` so moving to a different package doesn't break calls.
pub(super) fn widen_all(program: &mut Program) {
for class in program.classes.iter_mut() {
class.access_flags = widen(class.access_flags);

27
crates/noxis-structure-check/src/lib.rs
View file

@ -1,7 +1,8 @@
//! Compile-time gate for the project structure rules.
//!
//! Every crate calls [`check`] from its `build.rs`, so a file that grows past
//! 250 lines or a directory that fills up with a fifth file fails the build.
//! 250 *code* lines (comments and blank lines excluded) or a directory that
//! fills up with a fifth file fails the build.
mod rules;
@ -48,6 +49,26 @@ mod tests {
assert!(found[0].contains("lines >"), "{found:?}");
}
#[test]
fn ignores_comments_and_blank_lines() {
// A file padded with comment and blank lines stays under the limit:
// only real code counts toward `MAX_FILE_LINES`.
let tmp = TempDir::new("comments");
let mut body = String::new();
for _ in 0..super::MAX_FILE_LINES * 2 {
body.push_str("// a comment line\n");
body.push_str("/// a doc line\n");
body.push_str("//! a module line\n");
body.push('\n');
}
for index in 0..40 {
body.push_str(&format!("pub fn f{index}() {{}}\n"));
}
fs::write(tmp.0.join("lib.rs"), body).expect("write");
let found = violations(&tmp.0);
assert!(found.is_empty(), "{found:?}");
}
#[test]
fn rejects_directory_over_file_limit() {
let tmp = TempDir::new("many");
@ -79,8 +100,8 @@ mod tests {
#[test]
fn ignores_markdown_size_and_count() {
// Правила — только про Rust-код: `.md` не лимитирован ни по
// строкам, ни в счётчике файлов директории.
// Rules cover Rust code only: `.md` is bounded neither by the line
// limit nor by the per-directory file count.
let tmp = TempDir::new("md");
for index in 0..super::MAX_DIR_FILES + 3 {
fs::write(tmp.0.join(format!("doc{index}.md")), "line\n".repeat(300)).expect("write");

45
crates/noxis-structure-check/src/rules.rs
View file

@ -1,7 +1,8 @@
//! Project structure rules, invoked from every crate's `build.rs`.
//!
//! Rules apply to Rust code only, not to documentation:
//! * every `.rs` file is at most [`MAX_FILE_LINES`] lines long;
//! * every `.rs` file holds at most [`MAX_FILE_LINES`] *code* lines — blank
//! lines and full-line comments (`//`, `///`, `//!`) are not counted;
//! * every directory inside a crate's `src/`, `tests/` or `benches/` holds
//! at most [`MAX_DIR_FILES`] files — subdirectories are unlimited.
//!
@ -13,7 +14,10 @@ use std::ffi::OsStr;
use std::fs;
use std::path::{Path, PathBuf};
/// Maximum number of lines in a Rust source file.
/// Maximum number of code lines in a Rust source file.
///
/// Comment and blank lines are excluded (see [`count_code_lines`]) so the
/// gate measures real code bulk, not documentation weight.
pub const MAX_FILE_LINES: usize = 250;
/// Maximum number of files per directory; subdirectories are not counted.
@ -35,9 +39,9 @@ pub fn check() {
let manifest = manifest_dir();
let mut violations = Vec::new();
// `src/` обязателен; `tests/` и `benches/` проверяются, если созданы —
// иначе правило «250 строк» обходится выносом кода в тесты. `docs/` вне
// гейта: правила — только про Rust-код.
// `src/` is required; `tests/` and `benches/` are checked only when they
// exist — otherwise the line rule is bypassed by moving code into tests.
// `docs/` stays out of the gate: the rules are about Rust code only.
let roots = [
manifest.join("src"),
manifest.join("tests"),
@ -124,25 +128,34 @@ pub fn scan(root: &Path, violations: &mut Vec<String>) {
}
fn check_line_limit(path: &Path, violations: &mut Vec<String>) {
let lines = count_lines(path);
let lines = count_code_lines(path);
if lines > MAX_FILE_LINES {
violations.push(format!(
"{}: {lines} lines > {MAX_FILE_LINES}",
"{}: {lines} code lines > {MAX_FILE_LINES}",
path.display()
));
}
}
/// Counts lines without requiring the file to be valid UTF-8.
fn count_lines(path: &Path) -> usize {
let Ok(bytes) = fs::read(path) else {
return 0;
/// Counts *code* lines, skipping blanks and full-line comments.
///
/// A line is code when, after leading whitespace is stripped, it is non-empty
/// and does not start with `//` (which also covers `///` and `//!`). A line
/// that carries code followed by a trailing comment still counts once. Falls
/// back to a raw newline count when the file is not valid UTF-8.
fn count_code_lines(path: &Path) -> usize {
let Ok(text) = fs::read_to_string(path) else {
let Ok(bytes) = fs::read(path) else {
return 0;
};
return bytes.iter().filter(|&&byte| byte == b'\n').count();
};
if bytes.is_empty() {
return 0;
}
let newlines = bytes.iter().filter(|&&b| b == b'\n').count();
newlines + usize::from(bytes.last() != Some(&b'\n'))
text.lines()
.filter(|line| {
let trimmed = line.trim_start();
!trimmed.is_empty() && !trimmed.starts_with("//")
})
.count()
}
fn manifest_dir() -> PathBuf {

4
docs/README.md
View file

@ -25,7 +25,9 @@
искусственно. Не учитываются также `Cargo.lock`, `.gitignore`, корень крейта
(в нём всегда лежат `Cargo.toml` + `build.rs`).
1. **Не больше 250 строк** в одном `.rs` файле.
1. **Не больше 250 строк кода** в одном `.rs` файле. Пустые строки и
полно-строчные комментарии (`//`, `///`, `//!`) не считаются —
измеряется объём кода, а не документации.
2. **Не больше 4 `.rs`-файлов** в одной директории. Подпапки не ограничены:
`src/` может содержать `lib.rs` и три модуля-директории, каждая из которых
в свою очередь содержит не больше четырёх файлов.