xirang-kernel 0.2.0

Registry, transaction, contracts, grafts, and diagnostics for XiRang
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
//! Face parser and reference-scan tests.
//! 注册面解析与引用扫描的测试。

use super::{ParentSyntax, is_face_source, parse_face, replace_face_macro, source_references};

/// Cheap exclusion preserves marker trust and lets the parser decide every candidate.
/// 廉价排除保留标记信任,并让解析器裁决全部候选。
#[test]
fn face_detection_keeps_markers_aliases_and_syntax_boundaries() {
    let marker = "// fixture generated face";
    for source in [
        marker,
        "crate::root_object /* comment */ ! { kind: Widget }",
        "crate::nested_object! { kind: Widget }",
        "crate::__external_object! { kind: Widget }",
    ] {
        assert!(is_face_source(source, marker), "{source}");
    }
    for source in [
        "pub fn ordinary() {}",
        "fn broken(",
        "// crate::root_object! { kind: Fake }",
        "fn text() { let _ = \"nested_object! { kind: Fake }\"; }",
        "crate::root_object! { kind: }",
    ] {
        assert!(!is_face_source(source, marker), "{source}");
    }
}

#[test]
fn parses_multiline_registration_tokens_and_locations() {
    let source = r#"
crate::control_object! {
    kind: Button,
    name: { zh: "按钮", en: "Button" },
    requires: [
        "layout.viewport" => "ControlRegistry",
        "draw.basic" => "BasicDrawing",
    ],
    parent: crate::NodeId::from_path("control/control.rs", "ControlRegistry"),
    getting_from_other_registry: Some("engine"),
}
"#;
    let face = parse_face(source).unwrap().unwrap();

    assert_eq!(face.path("kind").as_deref(), Some("Button"));
    assert_eq!(face.localized("name", "zh").as_deref(), Some("按钮"));
    assert_eq!(face.field_location("requires").unwrap().line, 5);
    assert_eq!(
        face.requirements("requires").unwrap(),
        [
            ("layout.viewport".to_owned(), "ControlRegistry".to_owned()),
            ("draw.basic".to_owned(), "BasicDrawing".to_owned())
        ]
    );
    assert_eq!(
        face.parent(),
        Some(ParentSyntax::FromPath {
            source: "control/control.rs".to_owned(),
            kind: "ControlRegistry".to_owned(),
        })
    );
    assert_eq!(
        face.option_string("getting_from_other_registry"),
        Some(Some("engine".to_owned()))
    );
}

#[test]
fn parses_namespaced_package_root_parent() {
    let source = r#"
crate::control_object! {
    kind: Workspace,
    parent: crate::root_node_id(env!("CARGO_PKG_NAME")),
}
"#;
    let face = parse_face(source).unwrap().unwrap();

    assert_eq!(face.parent(), Some(ParentSyntax::Root));
}

/// A parent path is matched at a path-segment boundary, not by suffix: `crate::NOT_ROOT_NODE_ID`
/// is a different constant, `my_root_node_id` a different function, and `OwnNodeId::from_path` a
/// different type's constructor. Suffix matching classified all three as the parent the face
/// declared (audit `KN6`).
/// 父路径在**路径段边界**上匹配,而不是按后缀:`crate::NOT_ROOT_NODE_ID` 是另一个常量、
/// `my_root_node_id` 是另一个函数、`OwnNodeId::from_path` 是另一个类型的构造函数。按后缀匹配会
/// 把三者都判成该面声明的那个父级(审计 `KN6`)。
#[test]
fn a_parent_look_alike_is_not_the_parent() {
    let cases = [
        (
            "crate::NOT_ROOT_NODE_ID",
            "a different constant is not the root",
        ),
        ("my_root_node_id(1)", "a different function is not the root"),
        (
            "OwnNodeId::from_path(\"control/control.rs\", \"ControlRegistry\")",
            "another type's constructor is not this one",
        ),
    ];
    for (parent, why) in cases {
        let source = format!("crate::control_object! {{ kind: Workspace, parent: {parent} }}");
        let face = parse_face(&source).unwrap().unwrap();
        assert_eq!(face.parent(), None, "{why}: {parent}");
    }

    // The spellings the tree does use still classify, so the boundary rule narrows the match
    // rather than breaking it.
    // 树里真正使用的拼法仍然分类成功——边界规则是收紧匹配,而不是弄坏它。
    let real_root = "crate::control_object! { kind: Workspace, parent: crate::ROOT_NODE_ID }";
    assert_eq!(
        parse_face(real_root).unwrap().unwrap().parent(),
        Some(ParentSyntax::Root)
    );
    let own_node = "crate::control_object! { kind: Widget, parent: crate::NODE_ID }";
    assert_eq!(
        parse_face(own_node).unwrap().unwrap().parent(),
        Some(ParentSyntax::NodePath("crate".to_owned()))
    );
}

#[test]
fn rejects_duplicate_fields() {
    let source = "crate::control_object! { kind: First, kind: Second }";
    let error = parse_face(source).unwrap_err();
    assert!(error.message.contains("duplicate field `kind`"));
}

#[test]
fn replacing_a_face_preserves_its_rust_implementation() {
    let source = r#"pub struct Button;
impl Button { pub fn paint(&self) -> u32 { 7 } }
crate::control_object! {
    kind: Button,
    stable_name: "button",
}
#[test] fn paints() { assert_eq!(Button.paint(), 7); }
"#;
    let replacement = r#"crate::control_object! {
    kind: Button,
    stable_name: "button_graft",
}"#;

    let copied = replace_face_macro(source, replacement).unwrap();

    assert!(copied.contains("pub fn paint(&self) -> u32 { 7 }"));
    assert!(copied.contains("stable_name: \"button_graft\""));
    assert!(!copied.contains("stable_name: \"button\","));
    assert!(copied.contains("#[test] fn paints()"));
}

#[test]
fn source_references_ignore_imports_strings_comments_and_registration_data() {
    let source = r#"
use crate::unused::Thing;
fn run_button() {
    crate::control::object::button::dispatch_action("unused::fake()", true);
    // crate::comment::fake();
    crate::control_object! { kind: Fake, parent: crate::hidden::NODE_ID }
}
"#;
    let references = source_references(source).unwrap();
    assert!(
        references
            .paths
            .contains("crate::control::object::button::dispatch_action")
    );
    assert!(!references.paths.iter().any(|path| path.contains("unused")));
    assert!(!references.paths.iter().any(|path| path.contains("hidden")));
    assert!(!references.conservative);
}

/// A macro invocation's tokens are read for paths rather than ignored.
/// 宏调用的 token 会被读出路径,而不是被忽略。
///
/// The build used to walk into no macro body at all, so a face named only as
/// `vec![crate::control::object::dial::NODE_ID]` was pruned while `check` reported
/// ok and the host's `cargo check` failed with `E0433`.
/// 构建过去完全不进入宏内容,因此只被 `vec![crate::control::object::dial::NODE_ID]`
/// 命名的注册面会被剪掉,而 `check` 报 ok、宿主的 `cargo check` 以 `E0433` 失败。
#[test]
fn a_macro_invocation_is_read_for_the_paths_it_spells() {
    let referenced = "pub fn build() { let _ = vec![crate::control::object::dial::NODE_ID]; }";
    let references = source_references(referenced).unwrap();
    assert!(
        references
            .paths
            .contains("crate::control::object::dial::NODE_ID"),
        "a path inside a macro is a reference like any other: {:?}",
        references.paths
    );

    // The same file without the macro keeps the scan narrow, so this is not a
    // blanket widening.
    // 同一份文件去掉宏之后扫描仍然收窄,因此这不是无脑放宽。
    let narrow = "pub fn build() -> u8 { crate::control::dial::NODE_ID }";
    assert!(!source_references(narrow).unwrap().conservative);

    // The build's own wiring is read by its own scanners, and an invocation whose
    // tokens are only literals cannot name a node: neither may widen the scope, or
    // the automatic scope would be off for every real project (an entry always
    // contains `host!()`, and a declaration macro's contents are metadata).
    // 本构建自己的接线由各自的扫描器读取,而 token 全是字面量的调用不可能命名节点:两者都不得
    // 放宽作用域,否则每个真实工程都会失去自动作用域(入口总有 `host!()`,声明宏的内容是元数据)。
    for transparent in [
        "xirang_toolchain::run_method::host!();",
        "static_graft_plan!(crate::FRAMEWORK, cut \"root/a\");",
        "fn f() { crate::control_object! { kind: Fake } }",
        "const NAME: &str = env!(\"CARGO_PKG_NAME\");",
        "const TWO: &str = concat!(\"a\", \"b\");",
    ] {
        assert!(
            !source_references(transparent).unwrap().conservative,
            "`{transparent}` must not widen the scope"
        );
    }
}

/// The build has to follow a declaration's `cfg` gate, so the parser keeps
/// it exactly as written.
/// 构建需要跟随声明的 `cfg` 门控,因此解析器按原文保留它。
#[test]
fn a_declaration_keeps_its_cfg_gate() {
    let face = parse_face(
        "// generated-by=XiRang\n#[cfg(feature = \"optional-face\")]\n\
             crate::root_object! {\n    kind: Widget,\n}\n",
    )
    .expect("parse")
    .expect("face");
    assert_eq!(face.cfg(), Some("feature = \"optional-face\""));
}

/// A `*_object!` macro that is not a registration declaration is refused for its own
/// reason, instead of being taken for a face that is missing `parent:`.
/// 并非注册声明的 `*_object!` 宏按它自己的理由被拒,而不是被当成缺少 `parent:` 的注册面。
///
/// Red before the fix: the field reader accepted `name: "x", size: 3` as one value (the
/// splitter only starts a field at a name the vocabulary knows), so the macro became a face
/// whose `size` was silently absorbed, and the build then reported a `parent-macro` error
/// for a macro that is not part of the registration mechanism (audit `KRN-K-23`).
/// 修前为红:字段读取器把 `name: "x", size: 3` 收成一个取值(切分器只在词表认识的键处开始
/// 字段),于是该宏成了一个面、`size` 被静默吞掉,随后构建为这个根本不属于注册机制的宏报出
/// `parent-macro` 错误(审计 `KRN-K-23`)。
#[test]
fn a_non_registration_object_macro_is_refused_with_its_own_reason() {
    let error = parse_face("widget_object! { name: \"x\", size: 3 }")
        .expect_err("this body is not a registration declaration");
    let message = error.to_string();
    assert!(
        message.contains("size"),
        "the reason names the text left over: {message}"
    );
    assert!(
        !message.contains("parent"),
        "it is not a missing parent: {message}"
    );

    // The registration vocabulary itself still parses, including a value written with a
    // top-level-looking closure inside brackets.
    // 注册词表本身仍可解析,包括括号内写出、看起来像顶层的闭包取值。
    let face = parse_face(
        "crate::control_object! {\n    kind: Button,\n    needs_registry: true,\n    flow: |a: u32| a,\n}\n",
    )
    .expect("a canonical body parses")
    .expect("one face");
    assert_eq!(face.macro_name, "control_object");
}

/// The struct-literal form is the **same face** as the macro block it replaces (`docs/open-work-2026-10-08.md`
/// H, ruling A2e). Identity is what "same" means here: `NodeId = hash(namespace, relative path, kind)`, and
/// the new form does not write `kind` at all — the **type name is the kind** — so the one thing this must
/// prove is that the two forms hash to the same identity. If that ever stops holding, every face in a
/// migrated repository changes identity at once, and the on-disk graft records stop resolving.
/// 结构体字面量形与它取代的宏块是**同一个面**(`docs/open-work-2026-10-08.md` H,裁定 A2e)。这里的"同一个"
/// 指身份:`NodeId = hash(命名空间, 相对路径, kind)`,而新形**根本不写 `kind`**——**类型名就是 kind**——因此
/// 这条钉子要证的就是两形哈希到同一个身份。它一旦不成立,被迁移的仓库里**所有面同时换身份**,而落盘的嫁接
/// 记录会不再解析。
#[test]
fn the_struct_literal_form_is_the_same_face_as_the_macro_block() {
    let macro_form = "crate::root_object! {\n    kind: Card,\n    parent: crate::board::NODE_ID,\n    needs_registry: true,\n}\n";
    let literal_form = "pub struct Card;\n\nimpl Card {\n    pub const REGISTRATION: Registration = Registration {\n        parent: crate::board::NODE_ID,\n        needs_registry: true,\n    };\n}\n";
    let by_macro = parse_face(macro_form)
        .expect("the macro form parses")
        .expect("a face");
    let by_literal = parse_face(literal_form)
        .expect("the struct-literal form parses")
        .expect("a face");

    assert_eq!(
        by_literal.path("kind").as_deref(),
        Some("Card"),
        "the type name is the kind, synthesized so every reader downstream sees the same field the macro form carries"
    );
    assert_eq!(by_macro.path("kind"), by_literal.path("kind"));
    assert_eq!(by_macro.parent(), by_literal.parent());
    assert_eq!(
        by_macro.boolean("needs_registry"),
        by_literal.boolean("needs_registry")
    );
    // The kernel's own namespaced constructor: `NodeId = hash(namespace, relative path, kind)`. The
    // toolchain's `package_node_id` is the same function with this checkout's namespace filled in.
    // 内核自己的命名空间构造器:`NodeId = hash(命名空间, 相对路径, kind)`。工具链的 `package_node_id`
    // 就是同一个函数、填上本检出的命名空间。
    let identity = |kind: &str| {
        crate::registry_core::identity::NodeId::from_namespaced_path(
            "test-namespace",
            "board/card/card.rs",
            kind,
        )
    };
    assert_eq!(
        identity("Card"),
        identity(by_literal.path("kind").expect("a kind").as_str()),
        "and the two forms hash to one identity"
    );
}

/// The narrow parts of the form, each one a way a reader could mistake an ordinary constant for a face.
/// 这个形**有意写窄**的几处;每一处都是"读者可能把普通常量误读成面"的一条路。
#[test]
fn only_a_registration_literal_is_read_as_a_face() {
    for source in [
        // not `REGISTRATION`
        "pub struct Card;\nimpl Card { pub const OTHER: Registration = Registration { parent: crate::x::NODE_ID }; }\n",
        // the declared type is not `Registration`
        "pub struct Card;\nimpl Card { pub const REGISTRATION: Something = Registration { parent: crate::x::NODE_ID }; }\n",
        // the literal is not `Registration`
        "pub struct Card;\nimpl Card { pub const REGISTRATION: Registration = Something { parent: crate::x::NODE_ID }; }\n",
        // not a struct literal at all
        "pub struct Card;\nimpl Card { pub const REGISTRATION: Registration = REGISTRATION; }\n",
    ] {
        assert!(
            parse_face(source).expect("parses").is_none(),
            "not a face: {source}"
        );
    }
}

/// **Step ① of H/A2e is about *two* readers, and this is the second one.** The authoring executor reads a
/// face through the same kernel parser, so it accepts the struct-literal form for free — but its
/// **writer** splices text and does not know the new form yet, so a rewrite that would cross the two
/// spellings is refused by name rather than attempted. Measured: crossing them spliced a macro block into
/// an `impl`, which does not compile.
/// **H/A2e 的第①步说的是*两个*读者,这就是第二个。** 作者面执行器经同一个内核解析器读面,因此它**免费**
/// 拿到新形;但它的**写者**拼的是文本、还不认识新形,所以"跨两形"的重写**按名拒绝**而不是去试。实测:跨形
/// 会把宏块拼进 `impl`,编译不过。
#[test]
fn the_two_readers_take_both_forms_and_the_writer_refuses_to_cross_them() {
    let macro_form =
        "crate::root_object! {\n    kind: Card,\n    parent: crate::board::NODE_ID,\n}\n";
    let literal_form = "pub struct Card;\n\nimpl Card {\n    pub const REGISTRATION: Registration = Registration {\n        parent: crate::board::NODE_ID,\n    };\n}\n";
    // Reading: the executor's own entry point, one layer up from the parser.
    let read = |source: &str| {
        let face = parse_face(source).expect("parses").expect("a face");
        face.is_struct_literal()
    };
    assert!(!read(macro_form));
    assert!(read(literal_form), "the second reader takes the new form");

    // Writing: same form ⇒ fine (the identity case is step ③'s business, not this step's).
    assert!(
        replace_face_macro(macro_form, macro_form).is_ok(),
        "a macro file is rewritten with a macro"
    );
    assert!(
        replace_face_macro(literal_form, literal_form).is_ok(),
        "and a literal file with a literal"
    );

    // Writing across the forms: refused, by name, with the step that will lift it.
    for (source, replacement, from, into) in [
        (literal_form, macro_form, "struct-literal", "macro"),
        (macro_form, literal_form, "macro", "struct-literal"),
    ] {
        let error = replace_face_macro(source, replacement)
            .expect_err("crossing the forms is refused, not attempted");
        assert!(
            error.to_string().contains(from) && error.to_string().contains(into),
            "the refusal names both spellings: {error}"
        );
    }
}

/// A list field written in the **new spelling** carries the field's real Rust type, so `exports` is
/// written `&["…"]` there and `["…"]` in the macro spellings. Both are the same list, and the difference
/// is the borrow, not the shape — the readers absorb it in one place.
/// 用**新拼法**写的列表字段带着字段真实的 Rust 类型,因此那里的 `exports` 写成 `&["…"]`,而宏那两种拼法写
/// `["…"]`。两者是同一份列表,差别只在那个引用符号、不在形状——读取器在一处吸收它。
#[test]
fn a_list_field_reads_the_same_with_or_without_a_leading_borrow() {
    let by_macro = "crate::root_object! {\n    kind: Card,\n    parent: crate::board::NODE_ID,\n    exports: [\"control.render\"],\n}\n";
    let by_literal = "pub struct Card;\n\nimpl Card {\n    pub const REGISTRATION: Registration = Registration {\n        exports: &[\"control.render\"],\n        ..Registration::DEFAULT\n    };\n}\n";

    let macro_face = parse_face(by_macro).expect("parses").expect("a face");
    let literal_face = parse_face(by_literal).expect("parses").expect("a face");

    assert_eq!(
        macro_face.string_list("exports"),
        Some(vec!["control.render".to_owned()]),
        "the macro spelling"
    );
    assert_eq!(
        literal_face.string_list("exports"),
        macro_face.string_list("exports"),
        "and the literal spelling reads the same list"
    );
    assert!(
        literal_face.is_struct_literal(),
        "the two are still two spellings of one face"
    );
}

/// The type-like half of a face written in the new spelling lives in the `impl FaceContract` beside it,
/// and every downstream reader asks for it by the same field names the macro spellings use.
/// 用新拼法写的面,其类型类那一半住在它旁边的 `impl FaceContract` 里;下游每个读者都用与宏那两种拼法相同的
/// 字段名索取它。
#[test]
fn a_literal_form_face_reads_its_type_like_half_from_the_contract_block() {
    let source = r#"// generated-by=XiRang
pub struct Card;

impl FaceContract for Card {
    type Preset = crate::board::CardPreset;
    type Parts = crate::board::CardParts;
    const HANDLE_TRAITS: &'static [&'static str] = &["ControlHandle"];
    const PART_TRAITS: &'static [&'static str] = &["CardParts"];
}

xirang_toolchain::assert_contracts!(Card: crate::board::ControlHandle, crate::board::CardParts);

impl Card {
    pub const REGISTRATION: Registration = Registration {
        name: LocalizedText { zh: "卡片", en: "Card" },
        ..Registration::DEFAULT
    };
}
"#;
    let face = parse_face(source).expect("parses").expect("a face");
    assert!(face.is_struct_literal(), "read as the literal spelling");
    assert_eq!(
        face.string_list("handle_traits"),
        Some(vec!["ControlHandle".to_owned()]),
        "the labels the runtime reads"
    );
    // A type-like field holds a **path**, not a string literal: ask for it the way the build does.
    // 类型类字段装的是**路径**而不是字符串字面量:按构建的读法索取它。
    assert_eq!(
        face.path("preset").as_deref(),
        Some("crate::board::CardPreset"),
        "the preset type, as the declaration spells it"
    );
    assert_eq!(
        face.path("parts").as_deref(),
        Some("crate::board::CardParts"),
        "and the parts type"
    );
}

/// The labels and the `assert_contracts!` line are two statements of one fact, and the build refuses a
/// face where they disagree: a rule that requires a label would otherwise find a face that never claimed
/// that trait.
/// 标签与 `assert_contracts!` 那一行是同一件事实的两种陈述;两者不一致时构建拒绝这个面,否则某条要求某个
/// 标签的规则会找到一个从未声称过那个 trait 的面。
#[test]
fn labels_that_disagree_with_the_assertion_are_refused() {
    let source = r#"// generated-by=XiRang
pub struct Card;

impl FaceContract for Card {
    const HANDLE_TRAITS: &'static [&'static str] = &["SomethingElse"];
}

xirang_toolchain::assert_contracts!(Card: crate::board::ControlHandle);

impl Card {
    pub const REGISTRATION: Registration = Registration {
        ..Registration::DEFAULT
    };
}
"#;
    let error = parse_face(source).expect_err("the mismatch is refused");
    assert!(
        error.message.contains("handle_traits"),
        "the refusal names the field: {}",
        error.message
    );
}

/// The two spellings of one face file must mention the same modules: the struct-literal form keeps its
/// declaration in an `impl`, and reading those fields as references would widen the build's source scope
/// the moment a face is migrated — while its plan stayed byte-identical.
/// 同一份面文件的两种拼法必须提及同一批模块:字面量形把声明放在 `impl` 里,而那些字段一旦被读成引用,构建的
/// 源码作用域就会在面迁移的那一刻放宽——而它的计划是逐字不变的。
#[test]
fn both_face_spellings_mention_the_same_modules() {
    let macro_form = r#"
use crate::control::{ControlFrame, ControlHandle};
#[xirang_toolchain::soil]
pub const SOIL: xirang_toolchain::Soil = xirang_toolchain::Soil::of::<Slider>()
    .exports(&["control.render"])
    .under(crate::control::NODE_ID)
    .handle_contracts(xirang_toolchain::contracts!(Slider: crate::control::ControlHandle));

pub fn refresh() { crate::control::object::slider::dispatch(); }
"#;
    let literal_form = r#"
use crate::control::{ControlFrame, ControlHandle};
pub const NODE_ID: NodeId = NodeId::from_raw([1; 16]);
pub struct Slider;
impl FaceContract for Slider {
    type Preset = NoPreset;
    const HANDLE_TRAITS: &'static [&'static str] = &["ControlHandle"];
}
xirang_toolchain::assert_contracts!(Slider: crate::control::ControlHandle);
impl Slider {
    pub const REGISTRATION: Registration = Registration {
        parent: crate::control::NODE_ID,
        exports: &["control.render"],
        ..Registration::DEFAULT
    };
}

pub fn refresh() { crate::control::object::slider::dispatch(); }
"#;
    let described = |source: &str| {
        let references = source_references(source).unwrap();
        let mut paths = references
            .paths
            .iter()
            .filter(|path| path.contains("control"))
            .cloned()
            .collect::<Vec<_>>();
        paths.sort();
        paths
    };
    assert_eq!(
        described(literal_form),
        described(macro_form),
        "the declaration's own paths are metadata in both spellings; only real code counts"
    );
    assert!(
        described(literal_form)
            .iter()
            .any(|path| path.contains("dispatch")),
        "and a genuine call in the same file is still a reference: {:?}",
        described(literal_form)
    );
}

/// One declaration, both spellings: every field must reach the **consumers** as the same value.
/// 同一份声明的两种拼法:每个字段交到**消费者**手里的值必须相同。
///
/// This is the field-by-field half of A2e's acceptance. It compares what the consumers read — the
/// accessors on `FaceSyntax` and the two authoring parsers — rather than the raw token text, because the
/// raw text already differs harmlessly (`exports: &[…]` versus `.exports(&[…])` both answer the same
/// list) and a red list that mixes harmless spelling with real breakage buries the real one.
/// 这是 A2e 验收的逐字段那一半。它比的是**消费者读到的值**——`FaceSyntax` 上的访问器与那两个创作解析器
/// ——而不是裸 token 文本,因为裸文本本来就有无害的差别(`exports: &[…]` 与 `.exports(&[…])` 给出同一份
/// 列表),而把无害拼写与真实破坏混在一起的红名单会把真问题埋掉。
#[test]
fn both_face_spellings_read_the_same_field_values() {
    use crate::authoring::parse::parse_flow_expression;

    let macro_form = r#"
use crate::control::ControlHandle;
#[xirang_toolchain::soil]
pub const SOIL: xirang_toolchain::Soil = xirang_toolchain::Soil::of::<Button>()
    .name("Button", "按钮")
    .summary("A button", "一个按钮")
    .stable_name("ui.button")
    .exports(&["control.render"])
    .requires("render", "Renderer")
    .provides(&["control.render.provide"])
    .needs_registry(true)
    .runtime_checks(&[NON_EMPTY_TEXT])
    .flow(FlowContract::new(ContractId::new("control.render.v1"), 1, "ControlInput", "ControlFrame"))
    .handle_traits(&["ControlHandle"]);
"#;
    // Written the way the literal form writes it: the field types are the `Registration` struct's own
    // (`stable_name: Option<&str>`, `name: LocalizedText`, `requires: &[RequirementSpec]`, …), because that
    // is what an author of this spelling actually types.
    // 按字面量形的写法:字段类型就是 `Registration` 结构体自己的那些(`stable_name: Option<&str>`、
    // `name: LocalizedText`、`requires: &[RequirementSpec]`……),因为这一形的作者实际敲的就是这些。
    let literal_form = r#"
use crate::control::ControlHandle;
pub const NODE_ID: NodeId = NodeId::from_raw([1; 16]);
pub struct Button;
impl FaceContract for Button {
    type Preset = NoPreset;
    type Parts = NoParts;
    const HANDLE_TRAITS: &'static [&'static str] = &["ControlHandle"];
}
xirang_toolchain::assert_contracts!(Button: crate::control::ControlHandle);
impl Button {
    pub const REGISTRATION: Registration = Registration {
        parent: crate::control::NODE_ID,
        name: LocalizedText { zh: "按钮", en: "Button" },
        summary: LocalizedText { zh: "一个按钮", en: "A button" },
        stable_name: Some("ui.button"),
        exports: &["control.render"],
        requires: &[RequirementSpec { capability: "render", provider: "Renderer" }],
        provides: &["control.render.provide"],
        needs_registry: true,
        runtime_checks: &[NON_EMPTY_TEXT],
        flow: Some(FlowContract::new(ContractId::new("control.render.v1"), 1, "ControlInput", "ControlFrame")),
        ..Registration::DEFAULT
    };
}
"#;
    let read = |source: &str| {
        parse_face(source)
            .expect("both spellings parse")
            .expect("a face is declared")
    };
    let by_macro = read(macro_form);
    let by_literal = read(literal_form);
    assert!(
        by_literal.is_struct_literal(),
        "the literal form is read as such"
    );

    let mut differences = Vec::new();
    let mut compare = |what: &str, left: String, right: String| {
        if left != right {
            differences.push(format!("{what}: macro {left} vs literal {right}"));
        }
    };
    for language in ["zh", "en"] {
        for field in ["name", "summary"] {
            compare(
                &format!("{field}.{language}"),
                format!("{:?}", by_macro.localized(field, language)),
                format!("{:?}", by_literal.localized(field, language)),
            );
        }
    }
    compare(
        "stable_name",
        format!("{:?}", by_macro.string("stable_name")),
        format!("{:?}", by_literal.string("stable_name")),
    );
    compare(
        "needs_registry",
        format!("{:?}", by_macro.boolean("needs_registry")),
        format!("{:?}", by_literal.boolean("needs_registry")),
    );
    for field in ["exports", "provides", "runtime_checks", "handle_traits"] {
        compare(
            field,
            format!("{:?}", by_macro.string_list(field)),
            format!("{:?}", by_literal.string_list(field)),
        );
    }
    // The build reads `requires` through `FaceSyntax::requirements` (`registration_phase.rs`,
    // `discovery_cache.rs`), not through the authoring parser — so that is the consumer this pin has to
    // agree on. Picking the wrong consumer would have judged the two spellings by a shape no caller reads.
    // 构建经 `FaceSyntax::requirements` 读 `requires`(`registration_phase.rs`、`discovery_cache.rs`),
    // 而不是经创作解析器——因此这才是本钉子必须对齐的那个消费者。挑错消费者,等于用没人读的形状去判两形。
    compare(
        "requires",
        format!("{:?}", by_macro.requirements("requires")),
        format!("{:?}", by_literal.requirements("requires")),
    );
    compare(
        "flow",
        format!(
            "{:?}",
            by_macro
                .field("flow")
                .map(|text| parse_flow_expression(&text))
        ),
        format!(
            "{:?}",
            by_literal
                .field("flow")
                .map(|text| parse_flow_expression(&text))
        ),
    );
    assert!(
        differences.is_empty(),
        "the two spellings must hand the consumers the same value:\n{}\n\nraw text, for diagnosis:\n           name    macro {:?} literal {:?}\n  flow    macro {:?} literal {:?}\n  exports macro {:?} literal {:?}\n           requires macro {:?} literal {:?}\n  runtime_checks macro {:?} literal {:?}",
        differences.join("\n"),
        by_macro.field("name"),
        by_literal.field("name"),
        by_macro.field("flow"),
        by_literal.field("flow"),
        by_macro.field("exports"),
        by_literal.field("exports"),
        by_macro.field("requires"),
        by_literal.field("requires"),
        by_macro.field("runtime_checks"),
        by_literal.field("runtime_checks"),
    );
}

/// Rewriting a face written as a `Registration` literal must own its **whole region**: the declaration
/// **and** the `impl FaceContract` / `assert_contracts!` items that carry the type-class half. Splicing only
/// the declaration leaves the old contract behind — two `impl FaceContract` for one type, which rustc rejects
/// with E0119 — or keeps stale labels after a preset/parts edit.
/// 重写一个写成 `Registration` 字面量的面,必须拥有它**整段区域**:那份声明**以及**承载类型类那一半的
/// `impl FaceContract` / `assert_contracts!` 条目。只拼接声明会把旧合同留在原处——同一类型两个
/// `impl FaceContract`,rustc 以 E0119 拒绝——或者在改了 preset/parts 之后留下过期的标签。
#[test]
fn rewriting_a_literal_face_owns_its_whole_region() {
    let source = "use xirang_toolchain::run_method::run_method_core::{\n    NoParts, NoPreset, NodeId, Registration,}\n;\nuse xirang_toolchain::run_method::FaceContract;\n\npub struct Card;\n\nimpl FaceContract for Card {\n    type Preset = NoPreset;\n    type Parts = NoParts;\n    const HANDLE_TRAITS: &'static [&'static str] = &[\"OldContract\"];\n}\n\nimpl Card {\n    pub const REGISTRATION: Registration = Registration {\n        parent: crate::root_node_id(crate::XIRANG_NAMESPACE),\n        ..Registration::DEFAULT\n    };\n}\n\nxirang_toolchain::assert_contracts!(Card: OldContract);\n";
    let replacement = "pub struct Card;\n\nimpl FaceContract for Card {\n    type Preset = NoPreset;\n    type Parts = NoParts;\n    const HANDLE_TRAITS: &'static [&'static str] = &[\"NewContract\"];\n}\n\nimpl Card {\n    pub const REGISTRATION: Registration = Registration {\n        parent: crate::root_node_id(crate::XIRANG_NAMESPACE),\n        ..Registration::DEFAULT\n    };\n}\n\nxirang_toolchain::assert_contracts!(Card: NewContract);\n";
    let rewritten = crate::registry_core::syntax::replace_face_region(source, replacement)
        .expect("the rewrite succeeds");
    assert_eq!(
        rewritten.matches("impl FaceContract for Card").count(),
        1,
        "exactly one type-class item survives:\n{rewritten}"
    );
    assert_eq!(
        rewritten.matches("assert_contracts!").count(),
        1,
        "exactly one assertion line survives:\n{rewritten}"
    );
    assert!(
        rewritten.contains("NewContract") && !rewritten.contains("OldContract"),
        "the labels are the new ones:\n{rewritten}"
    );
    assert!(
        rewritten.contains("pub struct Card;"),
        "the author's own item is not the thing being replaced:\n{rewritten}"
    );
}

/// An unknown field in an `*_object!`-named macro says it may be an application macro.
/// `*_object!` 名字的宏里出现未知字段时,报错点名"它可能是应用宏"。
///
/// The measured case: a real application reuses the historical `control_object!` spelling for its
/// own control registry, whose `handle:` field this framework deleted on 2026-09-25 (audit §14).
/// The refusal is correct — the field is not in `FACE_FIELD_ORDER` — but the reader had to say why
/// a macro with a registration-sounding name is not a registration declaration, or every census row
/// looks like a broken face.
/// 实测案例:一个真实应用把历史上的 `control_object!` 拼法用于它自己的控件注册表,其中的 `handle:`
/// 字段已被本框架在 2026-09-25 删除(审计 §14)。拒绝是对的——该字段不在 `FACE_FIELD_ORDER` 里——但
/// 读取器必须说明"为什么一个听起来像注册的宏不是注册声明",否则每条普查行都像坏面。
#[test]
fn an_unknown_field_names_the_application_macro_case() {
    let source = r#"
crate::control_object! {
    kind: ScrollBar,
    handle: ScrollBar,
}
"#;
    let error = parse_face(source).unwrap_err();
    assert!(
        error
            .message
            .contains("`handle` is not a registration face field"),
        "{}",
        error.message
    );
    assert!(
        error.message.contains("application macro"),
        "the refusal says an application macro may share the name: {}",
        error.message
    );
}