@ai-guide/core

Single source of truth for ID generation across the AI Guide system. This Rust library provides deterministic, stable ID generation that can be used from both Rust (SWC plugin) and JavaScript/TypeScript (Node.js backend) via WebAssembly.

Purpose

Ensures consistent ID generation across:

• SWC Plugin (Rust): Build-time AST analysis
• Backend (Node.js): Runtime query processing
• Webpack Plugin (Node.js): Manifest generation

Architecture

• Language: Rust
• Output: WebAssembly (WASM) + Native library
• Interop: wasm-bindgen for JavaScript/TypeScript
• Algorithm: MD5 hashing for deterministic IDs

Build Outputs

cargo build --release

Produces:

• target/release/libai_guide_core.dylib - Native library (macOS)
• target/release/libai_guide_core.so - Native library (Linux)
• target/release/ai_guide_core.dll - Native library (Windows)
• target/wasm32-unknown-unknown/release/ai_guide_core.wasm - WebAssembly module

API Functions

generate_semantic_id(file_path, parent_path, node_type, node_name, sibling_index, attrs_hash)

Generate stable ID based on component hierarchy and semantic structure.

Formula: MD5(file_path:parent_path:node_type:node_name:sibling_index:attrs_hash).substring(0, 12)

Returns: 12-character hex hash

generate_stable_id(file_path, element_name, line_number)

LEGACY: Generate stable ID based on line number.

Formula: MD5(file_path:element_name:line_number).substring(0, 12)

Returns: 12-character hex hash

generate_component_id(file_path, component_name)

Generate component ID from file path and name.

Formula: MD5(file_path:component_name).substring(0, 8)

Returns: 8-character hex hash

generate_action_id(component_id, label, selector)

Generate action ID linked to a component.

Formula: MD5(component_id:label:selector).substring(0, 8)

Returns: 8-character hex hash

hash_stable_attributes(attrs_json)

Generate hash from stable attributes (id, data-testid, key, etc.).

Returns: 8-character hex hash or empty string

Usage

From Rust (SWC Plugin)

use ai_guide_core::generate_semantic_id;

let id = generate_semantic_id(
    "src/components/Button.tsx",
    "App>Layout",
    "component",
    "Button",
    0,
    "id=submit"
);
// Returns: "a1b2c3d4e5f6"

From Node.js (after WASM compilation)

import * as core from '@ai-guide/core';

const id = core.generate_semantic_id(
    "src/components/Button.tsx",
    "App>Layout",
    "component",
    "Button",
    0,
    "id=submit"
);
// Returns: "a1b2c3d4e5f6"

Testing

cargo test

All ID generation functions include unit tests to verify:

• Deterministic output (same input = same ID)
• Correct hash length
• Empty input handling

Why MD5?

• Fast: Optimized for build-time performance
• Deterministic: Same input always produces same output
• Collision-resistant: For our namespace, collisions are extremely rare
• Compact: Short IDs (8-12 chars) are human-readable

Development

Build for Development

cargo build

Build for Production

cargo build --release

Run Tests

cargo test

Build for WebAssembly (Node.js)

wasm-pack build --target nodejs

Integration Status

• [x] Core implementation
• [ ] WASM build configuration
• [ ] Node.js package wrapper
• [ ] SWC plugin integration
• [ ] Backend migration