验收 Ruby 六类别候选档案并完成 OpenSpec 8.16

Author: loong10k

README.md

@@ -679,3 +679,5 @@ Source builds add `codeguard lint ruby FILE.rb --ruby-tool /absolute/path/to/rub
 Ruby edit feedback: source builds of `hook execute` / `hook claude post-tool-use` accept `--ruby-tool ABS_PATH` or select Ruby from the caller's absolute PATH entries. Only confirmed edited files are parsed under the event deadline. Selected failures do not fall back; absence retains WASM candidates. Bounded dialogue carries current line positions and real stable tasks without source/tool-message echoes or invented columns, and asks agents to verify project Ruby compatibility first. `repair_ready` rechecks using the selected tool and retains real evidence references; zero diagnostics do not close tasks. New closed protocols are edit feedback 0.19 (inner 0.10) and recheck feedback 0.20 (inner 0.6); old schemas are preserved. Actual installed-host triggering, complete RuboCop coverage, and public npm release remain unverified.
 
 Ruby version declaration guard: source builds read the nearest `.ruby-version` between the source and project root, bounded to 64 ancestor levels and 4096 bytes. Only `2.6.10`, `2.6.10p210` and their `ruby-` forms match the fixed parser. Other explicit versions yield `ruby_project_version_mismatch`; aliases/ambiguity yield `ruby_project_version_unresolved`; unsafe links/read failures yield `ruby_project_version_unreadable`. None starts the old Ruby or falls back to WASM. Declaration bytes and nearer missing declarations are rechecked after parsing; changes withdraw diagnostics. Saved positions are also withdrawn when a new declaration is incompatible. Standalone lint locates a `.codeguard` workspace before a Git root or Gemfile, so nested Gemfiles cannot hide the workspace pin; the nearest module version declaration remains authoritative. Absence retains an unapproved preliminary observation. Gemfile constraints, JRuby/RVM, complete project profiling and release remain pending. See [version guard acceptance](tests/acceptance/ruby-project-version.md).
+
+The Ruby six-category candidate profile now records runtime dialects, project-lock version selection and conditional tool scopes. Native rules, full project coverage and platform qualification remain unverified. See [profile acceptance](tests/acceptance/ruby-candidate-baseline.md).

README.zh-CN.md

@@ -662,3 +662,5 @@ codeguard task verify --help
 Ruby 编辑快检接线：源码构建的 `hook execute` / `hook claude post-tool-use` 可选择 `--ruby-tool ABS_PATH` 或调用方绝对 PATH 的 Ruby。只检查确认编辑的文件，共用事件截止时间；选定工具失败不回退，缺工具保留 WASM 候选。原生行号与稳定任务进入有界对话，不回显源码/工具消息或猜列号；先核对项目 Ruby 版本适用性。`repair_ready` 用同一工具复检并保存真实证据引用，零诊断仍不关闭任务。编辑反馈 0.19（内层 0.10）、复检反馈 0.20（内层 0.6）新增封闭 schema，旧协议不改。实际宿主自动触发、完整 RuboCop 与公开 npm 版本尚未验收。
 
 Ruby 版本声明约束：源码构建在原生解析前有界读取源码祖先至项目根最近的 `.ruby-version`（最多 64 层、4096 字节），只接受 `2.6.10`、`2.6.10p210` 及对应 `ruby-` 前缀。其它明确版本返回 `ruby_project_version_mismatch`，别名/歧义返回 `ruby_project_version_unresolved`，链接或读取失败返回 `ruby_project_version_unreadable`；均不启动旧 Ruby，也不回退 WASM。解析前后复核声明字节及更近目录的缺项，变化撤回诊断；已保存诊断遇到不适用的新声明也会撤回。单文件入口优先定位 `.codeguard` 工作区、再定位 Git 根和 Gemfile，模块 Gemfile 不能遮蔽工作区版本，模块自身最近版本声明仍优先。无声明继续提供未批准的初步观察；Gemfile 运行时约束、JRuby/RVM、完整项目版本识别及发行仍待实现。见[版本约束验收](tests/acceptance/ruby-project-version.md)。
+
+Ruby 六类别候选档案已独立固化运行时方言、项目锁版本策略和条件性工具范围；原生规则、完整项目和平台资格仍待验收。见[档案验收](tests/acceptance/ruby-candidate-baseline.md)。

crates/codeguard-adapters/src/lib.rs

@@ -72,6 +72,10 @@ mod eslint_json;
 mod eslint_message_report;
 mod eslint_parsed;
 mod go_candidate;
+mod ruby_candidate;
+mod ruby_candidate_profile;
+mod ruby_candidate_slot;
+mod ruby_candidate_tool;
 mod grammar_asset_manifest;
 mod legacy_dylink_compat;
 mod zig_wasm_compat;
@@ -399,3 +403,8 @@ pub use kotlin_parsed::KotlinParsed;
 
 mod kotlin_native_observation;
 pub use kotlin_native_observation::valid_kotlin_native_observation;
+
+pub use ruby_candidate::{bundled_ruby_candidate_profile, parse_ruby_candidate_profile};
+pub use ruby_candidate_profile::RubyCandidateProfile;
+pub use ruby_candidate_slot::RubyCandidateSlot;
+pub use ruby_candidate_tool::RubyCandidateTool;

crates/codeguard-adapters/src/ruby_candidate.rs

@@ -0,0 +1,172 @@
+//! Ruby 原生六类别研究档案的严格读者；不启动原生进程，也不注册已验收能力。
+use crate::{parse_unique_json, ruby_candidate_profile::RubyCandidateProfile};
+use codeguard_core::{CANDIDATE_PLATFORMS, CHECK_CATEGORIES};
+use std::collections::BTreeSet;
+
+/// 读取内置 Ruby 档案并核对六类别、工具对应、方言、版本和条件；返回研究档案或错误。
+pub fn bundled_ruby_candidate_profile() -> Result<RubyCandidateProfile, String> {
+    parse_ruby_candidate_profile(include_str!(
+        "../../../rulepacks/ruby_static_candidate_v1.json"
+    ))
+}
+/// 消费外部候选 JSON；最多 64KiB，拒绝重复键、未知字段、类别缺项及虚报能力。
+pub fn parse_ruby_candidate_profile(raw: &str) -> Result<RubyCandidateProfile, String> {
+    if raw.len() > 64 * 1024 {
+        return Err("Ruby 候选档案超出字节预算".into());
+    }
+    let value = parse_unique_json(raw.as_bytes()).map_err(str::to_string)?;
+    let profile: RubyCandidateProfile = serde_json::from_value(value).map_err(|e| e.to_string())?;
+    if profile.schema_version != "1.0.0"
+        || profile.language != "ruby"
+        || profile.runtime_validation != "unverified"
+        || profile.platform_validation != "unverified"
+        || !exact_set(&profile.runtime_dialects, &["mri", "jruby", "truffleruby"])
+        || !exact_set(&profile.platforms, &CANDIDATE_PLATFORMS)
+        || !exact_set(
+            &profile.target_version_inputs,
+            &[
+                ".ruby-version",
+                ".tool-versions",
+                "mise.toml",
+                "Gemfile",
+                "Gemfile.lock",
+                "*.gemspec",
+                ".rubocop.yml",
+            ],
+        )
+        || !valid_gaps(&profile.version_gaps)
+    {
+        return Err("Ruby 档案版本、方言、版本输入或平台集合未验证/缺失".into());
+    }
+    let names: Vec<String> = profile
+        .categories
+        .iter()
+        .map(|s| s.category.clone())
+        .collect();
+    if !exact_set(&names, &CHECK_CATEGORIES) {
+        return Err("Ruby 档案必须恰有六个不重复类别".into());
+    }
+    for slot in &profile.categories {
+        let expected: &[&str] = match slot.category.as_str() {
+            "lint" => &["rubocop"],
+            "comments" => &["rubocop_documentation", "rubocop_documentation_method"],
+            "dependencies" => &["bundle_list"],
+            "cve" => &["bundler_audit"],
+            "security" => &["rubocop_security", "brakeman"],
+            "build" => &["gem_build"],
+            _ => return Err("Ruby 类别未知".into()),
+        };
+        let ids: Vec<String> = slot.tools.iter().map(|t| t.tool_id.clone()).collect();
+        if slot.status != "gap"
+            || !exact_set(&ids, expected)
+            || slot.applicability
+                != if slot.category == "build" {
+                    "project_dependent"
+                } else {
+                    "applicable"
+                }
+            || slot.requires_database_freshness != (slot.category == "cve")
+            || !valid_gaps(&slot.coverage_gaps)
+        {
+            return Err(format!(
+                "Ruby {} 的类别适用性、工具或缺口无效",
+                slot.category
+            ));
+        }
+        for tool in &slot.tools {
+            let (argv, scope): (&[&str], &str) = match tool.tool_id.as_str() {
+                "rubocop" => (
+                    &["bundle", "exec", "rubocop", "--format", "json"],
+                    "ruby_project",
+                ),
+                "rubocop_documentation" => (
+                    &[
+                        "bundle",
+                        "exec",
+                        "rubocop",
+                        "--only",
+                        "Style/Documentation",
+                        "--format",
+                        "json",
+                    ],
+                    "ruby_project",
+                ),
+                "rubocop_documentation_method" => (
+                    &[
+                        "bundle",
+                        "exec",
+                        "rubocop",
+                        "--only",
+                        "Style/DocumentationMethod",
+                        "--format",
+                        "json",
+                    ],
+                    "ruby_project",
+                ),
+                "bundle_list" => (&["bundle", "list"], "bundler_project"),
+                "bundler_audit" => (
+                    &["bundle-audit", "check", "--no-update", "--format", "json"],
+                    "bundler_project",
+                ),
+                "rubocop_security" => (
+                    &[
+                        "bundle", "exec", "rubocop", "--only", "Security", "--format", "json",
+                    ],
+                    "ruby_project",
+                ),
+                "brakeman" => (
+                    &[
+                        "bundle",
+                        "exec",
+                        "brakeman",
+                        "--format",
+                        "json",
+                        "--no-pager",
+                    ],
+                    "rails_project",
+                ),
+                "gem_build" => (&["gem", "build", "SELECTED_GEMSPEC"], "gem_project"),
+                _ => return Err("Ruby 工具未知".into()),
+            };
+            if tool.candidate_version != "project_locked"
+                || tool.version_status != "unvalidated_project_lock_required"
+                || tool.scope != scope
+                || tool
+                    .candidate_argv
+                    .iter()
+                    .map(String::as_str)
+                    .collect::<Vec<_>>()
+                    != argv
+                || tool.sources.is_empty()
+                || tool.sources.len() > 8
+                || tool.sources.iter().any(|s| {
+                    !s.starts_with("https://")
+                        || s.len() > 512
+                        || s.bytes().any(|b| b.is_ascii_whitespace())
+                })
+            {
+                return Err(format!(
+                    "Ruby {} 的版本、命令、范围或来源无效",
+                    tool.tool_id
+                ));
+            }
+        }
+    }
+    Ok(profile)
+}
+fn exact_set(actual: &[String], expected: &[&str]) -> bool {
+    actual.len() == expected.len()
+        && actual.iter().map(String::as_str).collect::<BTreeSet<_>>()
+            == expected.iter().copied().collect()
+}
+fn valid_gaps(gaps: &[String]) -> bool {
+    !gaps.is_empty()
+        && gaps.len() <= 32
+        && gaps.iter().collect::<BTreeSet<_>>().len() == gaps.len()
+        && gaps.iter().all(|s| {
+            !s.is_empty()
+                && s.len() <= 256
+                && s.bytes()
+                    .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_')
+        })
+}

crates/codeguard-adapters/src/ruby_candidate_profile.rs

@@ -0,0 +1,25 @@
+use crate::ruby_candidate_slot::RubyCandidateSlot;
+use serde::Deserialize;
+/// Ruby 运行时方言、版本输入和六类别候选档案；对应 OpenSpec 8.16。
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RubyCandidateProfile {
+    /// 版本化档案协议。
+    pub schema_version: String,
+    /// 固定语言 ID。
+    pub language: String,
+    /// 需要分别验证的运行时，不证明当前原生探针支持这些运行时。
+    pub runtime_dialects: Vec<String>,
+    /// 运行时组合尚未验收。
+    pub runtime_validation: String,
+    /// 候选平台集合。
+    pub platforms: Vec<String>,
+    /// 平台验收状态。
+    pub platform_validation: String,
+    /// 版本约束可能来自这些输入；此档案不读取或执行它们。
+    pub target_version_inputs: Vec<String>,
+    /// 版本兼容性剩余缺口。
+    pub version_gaps: Vec<String>,
+    /// 六类别的完整候选集合。
+    pub categories: Vec<RubyCandidateSlot>,
+}

crates/codeguard-adapters/src/ruby_candidate_slot.rs

@@ -0,0 +1,19 @@
+use crate::ruby_candidate_tool::RubyCandidateTool;
+use serde::Deserialize;
+/// Ruby 六类别适用性和缺口；对应 OpenSpec 8.16，缺工具不等于类别不适用。
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RubyCandidateSlot {
+    /// 检查类别。
+    pub category: String,
+    /// 全语言适用或需项目构建目标判定。
+    pub applicability: String,
+    /// 完整能力验收仍缺失。
+    pub status: String,
+    /// 有明确范围限制的原生工具候选。
+    pub tools: Vec<RubyCandidateTool>,
+    /// CVE 必须单独核验数据库身份和时效。
+    pub requires_database_freshness: bool,
+    /// 尚未验收的配置、报告、身份及覆盖条件。
+    pub coverage_gaps: Vec<String>,
+}

crates/codeguard-adapters/src/ruby_candidate_tool.rs

@@ -0,0 +1,18 @@
+use serde::Deserialize;
+/// Ruby 原生候选工具契约；对应 OpenSpec 8.16，仅供研究，不可执行或签发能力。
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RubyCandidateTool {
+    /// 原生工具和检查族的固定标识。
+    pub tool_id: String,
+    /// 需由项目锁解析的版本，尚未通过制品及兼容性验收。
+    pub candidate_version: String,
+    /// 候选版本状态。
+    pub version_status: String,
+    /// 研究命令示例；包含占位符时必须由未来批准计划显式绑定。
+    pub candidate_argv: Vec<String>,
+    /// Ruby、Bundler、Rails、YARD 或 gem 项目的具体适用条件。
+    pub scope: String,
+    /// 核对过的原生一手文档。
+    pub sources: Vec<String>,
+}