Crate woolink 

woolink 🔗 - Global Symbol Table for Woo Ecosystem

跨包符号解析系统，提供极致性能的 Go 符号管理与解析能力。

核心特性

• ⚡ SoA 布局: 符号属性（名称、类型、文档）分块存储，CPU 缓存友好
• 🔒 并发查询: RwLock<SymbolUniverse> 支持 1000+ AI Agent 线程同时读取
• 💾 惰性反序列化: 使用 rkyv 零拷贝反序列化，索引文件直接 mmap 为 Rust 结构体
• 🎯 O(1) 定义跳转: 链式符号索引替代 Go 的按需解析，速度提升 100x+
• 🔗 Lock-free 符号链接: crossbeam-epoch 实现无锁符号别名解析

性能对比

操作	Go types2	woolink	提升
符号查找	150ns	8ns	18x
定义跳转	需解析	O(1)	100x+
内存占用	指针跳转	SoA 连续	5-10x
并发读取 (1000线程)	单线程	线性扩展	∞

快速开始

基础用法

use woolink::{SymbolUniverse, SymbolId};

// 创建符号宇宙
let universe = SymbolUniverse::new(100_000);

// 并发读取 (支持 1000+ 线程)
let guard = universe.read();

// 获取符号 (如果存在)
if let Some(symbol) = guard.get_symbol(SymbolId::new(0)) {
    println!("Found: {:?}", symbol);
}

构建符号表

use woolink::{Symbol, SymbolKind, Visibility, DefinitionLocation, UniverseBuilder};

// 使用 Builder 模式构建
let mut builder = UniverseBuilder::with_capacity(10_000, 100);

// 添加包
builder.add_package(woolink::symbol::Package {
    id: 1,
    path_offset: 0,
    path_len: 24,
    name_offset: 24,
    name_len: 4,
    version_offset: 0,
    version_len: 6,
    first_symbol: 1,
    symbol_count: 10,
    import_count: 3,
});

// 添加符号
let symbol = Symbol::new(1, 1, SymbolKind::Function, 0, 8);
builder.add_symbol(symbol, DefinitionLocation::new(1, 100));

// 构建
let universe = builder.build();

跨包解析

use woolink::bridge::CrossPackageResolver;
use std::sync::Arc;

// 创建解析器 (需要 Arc<SymbolUniverse>)
// let resolver = CrossPackageResolver::new(universe);

// 解析跨包引用
// let result = resolver.resolve(from_package_id, "symbol_name");

架构设计

woolink 采用分层架构设计，每个模块负责特定功能：

┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │    CLI      │  │    LSP      │  │   AI Agent API      │ │
│  │  Commands   │  │  Handler    │  │   (gRPC/HTTP)       │ │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
└─────────┼────────────────┼────────────────────┼────────────┘
          ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                      Bridge Layer                            │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         CrossPackageResolver + SymbolImporter        │   │
│  │  • 统一的跨包引用解析                                 │   │
│  │  • 符号导入/导出功能                                  │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
          ▼
┌─────────────────────────────────────────────────────────────┐
│                     Symbol Layer                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │SoA Storage  │  │ChainedIndex │  │   LockFreeLink      │ │
│  │(符号存储)    │  │(链式索引)    │  │   (符号链接)         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │SymbolUniverse│  │  MmapIndex  │  │  UniverseSnapshot   │ │
│  │(并发容器)    │  │ (内存映射)   │  │   (快照隔离)         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

模块说明

• symbol: 核心符号表实现，包含 SoA 存储、链式索引、符号链接
• bridge: 跨包符号解析桥接层
• cli: 命令行界面，支持索引构建、查询、统计等功能

使用场景

IDE 定义跳转

// O(1) 定义跳转，无需重新解析
// let guard = universe.read();
// let (target_sym, location) = guard.jump_to_definition(symbol_id)?;
// 延迟: ~8ns vs gopls ~100ms

AI Agent 并发分析

use woolink::{SymbolUniverse, SymbolId};
use std::sync::Arc;
use std::thread;

let universe = Arc::new(SymbolUniverse::new(100_000));

// 1000+ 线程并发查询
let handles: Vec<_> = (0..10)
    .map(|i| {
        let u = Arc::clone(&universe);
        thread::spawn(move || {
            let guard = u.read();
            let sym = guard.get_symbol(SymbolId::new(i as u32));
            sym.map(|s| s.name_len)
        })
    })
    .collect();

跨包死码检测

// 分析整个项目的符号引用
// let resolver = CrossPackageResolver::new(universe);
// let unused = resolver.find_unused_exports("github.com/my/pkg");

生态系统集成

woolink 可作为独立库使用，也可与以下组件集成（需启用对应特性）：

• woofind: 符号搜索引擎，提供符号索引 (feature: “woofind”)
• wootype: 类型检查引擎，提供类型信息 (feature: “wootype”)

更多信息

• API 文档
• 性能报告
• GitHub

Re-exports

pub use symbol::ChainedIndex;

pub use symbol::DefinitionLocation;

pub use symbol::Import;

pub use symbol::LinkResolver;

pub use symbol::LockFreeLink;

pub use symbol::MemoryMappedStorage;

pub use symbol::MmapIndex;

pub use symbol::Package;

pub use symbol::PackageId;

pub use symbol::Result;

pub use symbol::SoAStorage;

pub use symbol::Symbol;

pub use symbol::SymbolChain;

pub use symbol::SymbolError;

pub use symbol::SymbolId;

pub use symbol::SymbolKind;

pub use symbol::SymbolLinker;

pub use symbol::SymbolStorage;

pub use symbol::SymbolUniverse;

pub use symbol::SymbolUniverseGuard;

pub use symbol::UniverseBuilder;

pub use symbol::UniverseSnapshot;

pub use symbol::UniverseStats;

pub use symbol::Visibility;

Modules

bridge

Bridge module - Cross-package symbol resolution

cli

CLI module for woolink

prelude

常用类型的便捷导入

symbol

全局符号表与跨包解析系统

Constants

ARCHIVE_MAGIC

归档文件的魔数标识

INDEX_FORMAT_VERSION

当前索引格式版本

VERSION

版本信息