建立JavaScript模块return的有界AST事实与模式对照验收

Author: loong10k

crates/codeguard-runtime/src/lib.rs

@@ -238,3 +238,12 @@ pub use wasm_form_terminator::WasmFormTerminator;
 mod wasm_form_terminator_scan;
 #[cfg(feature = "wasm-precheck")]
 pub use wasm_form_terminator_scan::scan_wasm_form_terminators;
+
+#[cfg(feature = "wasm-precheck")]
+mod wasm_outer_return;
+#[cfg(feature = "wasm-precheck")]
+pub use wasm_outer_return::WasmOuterReturn;
+#[cfg(feature = "wasm-precheck")]
+mod wasm_outer_return_scan;
+#[cfg(feature = "wasm-precheck")]
+pub use wasm_outer_return_scan::{WasmOuterReturnScan, scan_wasm_outer_returns};

crates/codeguard-runtime/src/wasm_outer_return.rs

@@ -0,0 +1,18 @@
+/// 函数边界之外的return节点字节事实；不自行认定模块模式或源码违规。
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct WasmOuterReturn {
+    /// 当前AST节点类型。
+    pub syntax_kind: String,
+    /// 原始字节起点。
+    pub start_byte: usize,
+    /// 原始字节终点。
+    pub end_byte: usize,
+    /// 零基起始行。
+    pub start_row: usize,
+    /// 零基起始字节列。
+    pub start_column_byte: usize,
+    /// 零基结束行。
+    pub end_row: usize,
+    /// 零基结束字节列。
+    pub end_column_byte: usize,
+}

crates/codeguard-runtime/src/wasm_outer_return_scan.rs

@@ -0,0 +1,85 @@
+use crate::WasmOuterReturn;
+use tree_sitter::Tree;
+
+/// 有界AST函数外return事实集合；是否适用模块规则由调用者证明。
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct WasmOuterReturnScan {
+    /// 已观察到的原始节点位置，不输出源码文本。
+    pub returns: Vec<WasmOuterReturn>,
+    /// 记录或访问预算耗尽，不得解释为完整清洁结果。
+    pub truncated: bool,
+}
+
+/// 在固定根节点内线性遍历，跳过调用者列出的完整函数子树。
+/// 参数为同字节树/源码、根/return类型、函数边界及记录/访问预算；
+/// 返回仅AST事实或参数错误，不决定module/CommonJS/未知模式的语言语义。
+pub fn scan_wasm_outer_returns(
+    tree: &Tree,
+    source: &[u8],
+    kinds: [&str; 2],
+    function_kinds: &[&str],
+    max_records: usize,
+    max_visits: usize,
+) -> Result<WasmOuterReturnScan, String> {
+    let root = tree.root_node();
+    let [root_kind, return_kind] = kinds;
+    let valid_kind =
+        |kind: &&str| !kind.is_empty() && kind.len() <= 128 && !kind.chars().any(char::is_control);
+    if !(1..=128).contains(&max_records)
+        || !(1..=200_000).contains(&max_visits)
+        || !(1..=32).contains(&function_kinds.len())
+        || !kinds.iter().all(valid_kind)
+        || !function_kinds.iter().all(valid_kind)
+        || function_kinds.contains(&root_kind)
+        || function_kinds.contains(&return_kind)
+        || root_kind == return_kind
+        || source.len() > 1024 * 1024
+        || std::str::from_utf8(source).is_err()
+        || root.kind() != root_kind
+        || root.end_byte() > source.len()
+    {
+        return Err("函数外return事实参数或源码边界无效".into());
+    }
+    let mut cursor = root.walk();
+    let mut returns = Vec::new();
+    let mut visited = 0usize;
+    let mut truncated = false;
+    loop {
+        // 每个游标节点只处理一次；函数子树整体跳过，不做递归或反复祖先查找。
+        if visited == max_visits {
+            truncated = true;
+            break;
+        }
+        visited += 1;
+        let node = cursor.node();
+        if node.kind() == return_kind {
+            if returns.len() == max_records {
+                truncated = true;
+                break;
+            }
+            let start = node.start_position();
+            let end = node.end_position();
+            returns.push(WasmOuterReturn {
+                syntax_kind: node.kind().to_owned(),
+                start_byte: node.start_byte(),
+                end_byte: node.end_byte(),
+                start_row: start.row,
+                start_column_byte: start.column,
+                end_row: end.row,
+                end_column_byte: end.column,
+            });
+        }
+        if !function_kinds.contains(&node.kind()) && cursor.goto_first_child() {
+            continue;
+        }
+        loop {
+            if cursor.goto_next_sibling() {
+                break;
+            }
+            if !cursor.goto_parent() {
+                return Ok(WasmOuterReturnScan { returns, truncated });
+            }
+        }
+    }
+    Ok(WasmOuterReturnScan { returns, truncated })
+}

crates/codeguard-runtime/tests/wasm_outer_return_scan.rs

@@ -0,0 +1,230 @@
+#![cfg(feature = "wasm-precheck")]
+use codeguard_runtime::{WasmGrammar, scan_wasm_outer_returns};
+
+fn javascript() -> WasmGrammar {
+    WasmGrammar::load(
+        "javascript",
+        include_bytes!("../../../grammars/javascript/parser.wasm"),
+        "7978e62bcc851ab1d1f6dcd4678f9eda79df2b3b3490e75f81dd819d9bccccfa",
+        15,
+    )
+    .unwrap()
+}
+fn scan(
+    tree: &tree_sitter::Tree,
+    source: &[u8],
+    records: usize,
+    visits: usize,
+) -> codeguard_runtime::WasmOuterReturnScan {
+    scan_wasm_outer_returns(
+        tree,
+        source,
+        ["program", "return_statement"],
+        &[
+            "function_declaration",
+            "function_expression",
+            "generator_function_declaration",
+            "generator_function",
+            "arrow_function",
+            "method_definition",
+        ],
+        records,
+        visits,
+    )
+    .unwrap()
+}
+#[test]
+fn outside_function_returns_include_control_flow_and_byte_positions() {
+    let mut grammar = javascript();
+    for source in [
+        "return 1;",
+        "if (ready) { return 1; }",
+        "while (ready) { return 2; }",
+        "try { return 1; } catch (e) { return 2; }",
+        "const 名字=1;\r\nif (名字) { return 名字; }",
+    ] {
+        let tree = grammar.parse(source.as_bytes()).unwrap();
+        assert!(!tree.root_node().has_error(), "{source}");
+        let facts = scan(&tree, source.as_bytes(), 128, 200_000);
+        assert!(!facts.returns.is_empty(), "{source}");
+        assert!(!facts.truncated);
+        for fact in &facts.returns {
+            assert!(source[fact.start_byte..fact.end_byte].starts_with("return"));
+            assert_eq!(fact.syntax_kind, "return_statement");
+            let prefix = &source.as_bytes()[..fact.start_byte];
+            assert_eq!(
+                fact.start_row,
+                prefix.iter().filter(|b| **b == b'\n').count()
+            );
+            assert_eq!(
+                fact.start_column_byte,
+                prefix.rsplit(|b| *b == b'\n').next().unwrap().len()
+            );
+        }
+    }
+}
+#[test]
+fn every_function_boundary_and_comment_text_is_skipped() {
+    let mut grammar = javascript();
+    for source in [
+        "function f(){if(true){return 1;}}",
+        "const f = function(){return 1;};",
+        "function* f(){return 1;}",
+        "const f = function*(){return 1;};",
+        "const f = () => {return 1;};",
+        "class C { f(){return 1;} get x(){return 2;} }",
+        "const o = {f(){return 1;}};",
+        "async function f(){return 1;}",
+        "const f = async () => {return 1;};",
+        "const x = 'return 1;'; // return 2;\n",
+    ] {
+        let tree = grammar.parse(source.as_bytes()).unwrap();
+        assert!(!tree.root_node().has_error(), "{source}");
+        let facts = scan(&tree, source.as_bytes(), 128, 200_000);
+        assert!(facts.returns.is_empty(), "{source}");
+        assert!(!facts.truncated);
+    }
+    let source = b"function f(){return 1;} if(true){return 2;}";
+    let tree = grammar.parse(source).unwrap();
+    let facts = scan(&tree, source, 128, 200_000);
+    assert_eq!(facts.returns.len(), 1);
+    assert_eq!(
+        &source[facts.returns[0].start_byte..facts.returns[0].end_byte],
+        b"return 2;"
+    );
+}
+#[test]
+fn exhausted_scan_retains_facts_and_invalid_bounds_are_rejected() {
+    let mut grammar = javascript();
+    let source = b"return 1; return 2;";
+    let tree = grammar.parse(source).unwrap();
+    let facts = scan(&tree, source, 1, 200_000);
+    assert_eq!(facts.returns.len(), 1);
+    assert!(facts.truncated);
+    let facts = scan(&tree, source, 128, 1);
+    assert!(facts.returns.is_empty());
+    assert!(facts.truncated);
+    for (root, ret, scopes, records, visits, bytes) in [
+        (
+            "program",
+            "return_statement",
+            &["function_declaration"][..],
+            0,
+            10,
+            &source[..],
+        ),
+        (
+            "program",
+            "return_statement",
+            &["function_declaration"][..],
+            1,
+            0,
+            &source[..],
+        ),
+        (
+            "wrong",
+            "return_statement",
+            &["function_declaration"][..],
+            1,
+            10,
+            &source[..],
+        ),
+        (
+            "program",
+            "",
+            &["function_declaration"][..],
+            1,
+            10,
+            &source[..],
+        ),
+        ("program", "return_statement", &[][..], 1, 10, &source[..]),
+        (
+            "program",
+            "return_statement",
+            &["function_declaration"][..],
+            1,
+            10,
+            &b""[..],
+        ),
+    ] {
+        assert!(
+            scan_wasm_outer_returns(&tree, bytes, [root, ret], scopes, records, visits).is_err()
+        );
+    }
+}
+
+#[test]
+#[ignore = "需显式已有Node24.18.0，验证module/CommonJS模式边界，不批准语言资格"]
+fn actual_node_modes_confirm_outer_return_facts_without_commonjs_findings() {
+    use codeguard_runtime::{ProcessSpec, Termination, run_process};
+    use std::{
+        collections::BTreeMap,
+        ffi::OsString,
+        path::{Path, PathBuf},
+        sync::atomic::AtomicBool,
+        time::{Duration, Instant},
+    };
+    let input = PathBuf::from(std::env::var_os("CODEGUARD_NODE_BIN").expect("显式指定Node"));
+    assert!(input.is_absolute());
+    let executable = input.canonicalize().unwrap();
+    let before = std::fs::read(&executable).unwrap();
+    let deadline = Instant::now() + Duration::from_secs(30);
+    let cancelled = AtomicBool::new(false);
+    let invoke = |args: &[&str], stdin| {
+        run_process(
+            &ProcessSpec {
+                executable: executable.clone(),
+                args: args.iter().map(OsString::from).collect(),
+                cwd: Path::new("/").to_path_buf(),
+                env: BTreeMap::new(),
+                stdin,
+                deadline,
+                output_limit_bytes: 65536,
+            },
+            &cancelled,
+        )
+    };
+    let version = invoke(&["--version"], None);
+    assert_eq!(version.termination, Termination::Exited(0));
+    assert_eq!(version.stdout, b"v24.18.0\n");
+    assert!(version.stderr.is_empty());
+    let mut grammar = javascript();
+    for source in [
+        "return 1;",
+        "if(true){return 1;}",
+        "while(false){return 1;}",
+        "function f(){return 1;}",
+        "const f=function(){return 1;};",
+        "function* f(){return 1;}",
+        "const f=function*(){return 1;};",
+        "const f=()=>{return 1;};",
+        "class C {f(){return 1;}}",
+        "const o={f(){return 1;}};",
+        "const s='return 1;';",
+    ] {
+        let tree = grammar.parse(source.as_bytes()).unwrap();
+        assert!(!tree.root_node().has_error());
+        let facts = scan(&tree, source.as_bytes(), 128, 200_000);
+        assert!(!facts.truncated);
+        for (mode, module) in [
+            ("--input-type=module", true),
+            ("--input-type=commonjs", false),
+        ] {
+            let outcome = invoke(&["--check", mode], Some(source.as_bytes().to_vec()));
+            let invalid = module && !facts.returns.is_empty();
+            assert_eq!(
+                outcome.termination,
+                Termination::Exited(i32::from(invalid)),
+                "{mode} {source}"
+            );
+            assert!(outcome.stdout.is_empty());
+            if invalid {
+                assert!(String::from_utf8_lossy(&outcome.stderr).contains("SyntaxError"));
+            } else {
+                assert!(outcome.stderr.is_empty());
+            }
+        }
+    }
+    assert_eq!(input.canonicalize().unwrap(), executable);
+    assert_eq!(std::fs::read(executable).unwrap(), before);
+}

docs/Codeguard-Grammar-Evaluation.md

@@ -165,3 +165,7 @@ Java differential acceptance now checks truncated_files before treating empty re
 ## JavaScript native differential uses project structure candidates
 
 The development differential now shares the project's direct duplicate-binding worker. Report0.9 separates raw parser recovery from combined structure metrics. Actual Node24.18.0 over18 additional module cases gives raw5TP/11TN/0FP/2FN and combined6TP/11TN/0FP/1FN: duplicate binding has rule evidence, while module-level return remains missed. The schema constrains rule digests and language scope; existing protocols remain unchanged and0.4 consumers reject the new version. This measurement correction does not change the fixed358-case metrics or grant grammar qualification. CommonJS or unknown modes must not receive unconditional module-return findings. Independent holdout and formal qualification remain open. See [limited acceptance](../tests/acceptance/javascript-native-project-binding.md).
+
+## AST facts for a module-only return candidate
+
+The runtime now traverses bounded AST nodes outside function/generator/arrow/method subtrees, including outer control flow. It retains UTF-8 byte locations and explicit budget truncation. Actual Node24.18.0 compared11 source samples in module and CommonJS modes (22 syntax checks), confirming the need for explicit module context. This is only the fact layer; public worker/probe, project mode and differential wiring remain open. The existing module_return false negative and0/32 qualification are unchanged. See [limited acceptance](../tests/acceptance/javascript-module-return-ast.md).

docs/Codeguard-Grammar-Evaluation.zh_CN.md

@@ -177,3 +177,7 @@ Java差分验收先核对truncated_files，隐藏恢复保留unknown，避免空
 ## JavaScript 原生差分对齐项目结构候选
 
 开发差分现在复用项目检查的重复直接绑定 worker，报告0.9分别保留原始恢复与组合结构指标。真实 Node24.18.0 的18个额外 module 样例：原始5TP/11TN/0FP/2FN，组合6TP/11TN/0FP/1FN；重复绑定得到结构规则证据，顶层 module return 仍漏检。规则摘要和语言范围受 schema 约束；旧协议保持不变，旧0.4消费者拒绝新版本。此修正不新增发行资格、不改变固定358例指标，也不能对 CommonJS/未知模式无条件报顶层 return。独立holdout及正式资格仍未完成。见[局部验收](../tests/acceptance/javascript-native-project-binding.md)。
+
+## 模块 return 候选的 AST 事实基础
+
+runtime新增有界函数外return扫描：覆盖顶层控制流、跳过函数/生成器/箭头/方法子树、保留UTF-8字节位置和预算截断。真实Node24.18.0对11份源码在module/CommonJS下共22次对照，证明规则必须带模块模式条件。当前仅有事实层，公开worker/probe/项目模式/差分尚未接线，因此module_return仍漏检、资格0/32。见[局部验收](../tests/acceptance/javascript-module-return-ast.md)。

openspec/changes/introduce-rust-codeguard-cli/specs/syntax-precheck/spec.md

@@ -858,3 +858,13 @@ The native differential SHALL use the same frozen JavaScript binding worker as p
 #### Scenario: Native-invalid duplicate declaration has a combined candidate
 - **WHEN** a frozen direct lexical duplicate is rejected by the selected Node syntax observer but has no parser recovery
 - **THEN** the raw comparison remains false_negative, the combined comparison is true_positive with the project rule evidence, and no grammar qualification or delivery permission is issued
+
+### Requirement: Module-only return candidates SHALL use bounded AST facts and explicit mode
+
+The implementation SHALL derive return-outside-function facts from bounded AST traversal, including returns nested in control-flow blocks, and SHALL skip function declarations, expressions, generators, arrows and methods. Facts SHALL retain byte locations and incomplete traversal. The presence of these facts alone SHALL NOT classify CommonJS or unknown-mode input as invalid. Activation of a module-only candidate SHALL require an explicit applicable module context.
+
+#### Scenario: Returns in functions remain legal candidates
+- **WHEN** a JavaScript AST contains function, generator, arrow or method returns and an outer control-flow return
+- **THEN** only the return outside function boundaries is retained as an AST fact
+- **AND** record or traversal exhaustion remains visibly truncated
+- **AND** no grammar qualification, native completion or project delivery permission is granted

openspec/changes/introduce-rust-codeguard-cli/tasks.md

@@ -1936,3 +1936,7 @@ next/task show在已核验当前原生零诊断、原grammar引用及同一源
 ## 2026-10-06 JavaScript 原生差分复用项目绑定候选
 
 延续12.11/14.17/14.19，父任务不勾选。JavaScript原生差分复用项目直接重复绑定worker，raw与combined分开；报告0.9按语言/规则摘要约束，旧协议不变。受控RED→GREEN，相关四目标15通过/6条件忽略，真实Node24.18.0显式1通过：18例raw5TP/11TN/0FP/2FN，combined6TP/11TN/0FP/1FN。module_return仍漏检，不扩大到CommonJS/未知模式；固定358指标不变。实际schema与三种篡改/旧消费者拒绝、严格Clippy修复后通过。见tests/acceptance/javascript-native-project-binding.md。独立holdout/正式资格0/32及完整发布验收仍缺。
+
+## 2026-10-06 JavaScript 模块 return 的 AST 事实基础
+
+延续12.11/14.17/14.19，父任务不勾选。runtime新增有界函数外return事实，覆盖顶层控制流并跳过函数/生成器/箭头/方法子树；预算截断和字节位置真实保留。新API缺失RED后实现，四目标16通过/2条件忽略，实际Node24.18.0显式1通过（11源码、22次module/CommonJS对照），严格WASM runtime/all-targets Clippy通过。公共worker/probe/项目模式/差分尚未接线，module_return漏检统计不变；禁止未知模式自启。见tests/acceptance/javascript-module-return-ast.md。40cc624 CI37431391905仍失败于固定插件证据源码checkout，后续门禁未运行。