sublime_node_tools/lib.rs
1//! # `sublime_node_tools`
2//!
3//! Node.js bindings for Sublime Workspace CLI Tools via napi-rs.
4//!
5//! ## What
6//!
7//! This crate provides Node.js bindings via napi-rs for the workspace-tools CLI,
8//! exposing 23 execute functions as native JavaScript/TypeScript functions. It enables
9//! Node.js and TypeScript applications to use workspace-tools functionality
10//! programmatically without spawning CLI processes.
11//!
12//! ## How
13//!
14//! The crate uses `#[napi]` macros to:
15//! - Define async functions callable from Node.js
16//! - Convert Rust types to JavaScript objects via `#[napi(object)]`
17//! - Generate TypeScript definitions automatically
18//!
19//! ### Architecture Overview
20//!
21//! ```text
22//! ┌─────────────────────────────────────────────────────────────────────┐
23//! │ JavaScript/TypeScript │
24//! │ │
25//! │ const result = await status({ root: "/path/to/project" }); │
26//! │ │
27//! │ if (result.success) { │
28//! │ console.log(result.data.packages); // ← Native JS objects │
29//! │ } else { │
30//! │ console.error(result.error.code); // ← "EVALIDATION" │
31//! │ } │
32//! └────────────────────────────────┬────────────────────────────────────┘
33//! │
34//! ▼
35//! ┌─────────────────────────────────────────────────────────────────────┐
36//! │ NAPI Layer (crates/node/) │
37//! │ │
38//! │ 1. Parameter validation (validation.rs) │
39//! │ 2. Conversion JS → Rust structs │
40//! │ 3. Call execute_* functions from CLI │
41//! │ 4. Capture JSON output │
42//! │ 5. Parse and convert to NAPI structs │
43//! │ 6. Return ApiResponse<T> │
44//! └────────────────────────────────┬────────────────────────────────────┘
45//! │
46//! ▼
47//! ┌─────────────────────────────────────────────────────────────────────┐
48//! │ CLI Layer (crates/cli/) │
49//! │ │
50//! │ execute_status(), execute_init(), execute_changeset_add(), ... │
51//! └─────────────────────────────────────────────────────────────────────┘
52//! ```
53//!
54//! ### Module Structure
55//!
56//! - **`error`**: Error handling with Node.js-style error codes (EVALIDATION, EGIT, etc.)
57//! - **`validation`**: Parameter validation before CLI execution
58//! - **`response`**: `ApiResponse<T>` wrapper for consistent success/error responses
59//! - **`types`**: NAPI-compatible structs for parameters and responses
60//! - **`commands`**: Implementation of all 23 NAPI functions
61//!
62//! ## Why
63//!
64//! Enables Node.js/TypeScript applications to use workspace-tools functionality
65//! programmatically without spawning CLI processes, with:
66//!
67//! - **Full type safety**: TypeScript definitions are auto-generated
68//! - **Native performance**: Direct function calls instead of process spawning
69//! - **Structured responses**: `ApiResponse<T>` with success/error handling
70//! - **Node.js-style errors**: Familiar error codes like ENOENT, EVALIDATION
71//!
72//! ## Examples
73//!
74//! ### Basic Usage
75//!
76//! ```typescript
77//! import { status, changesetAdd, bumpPreview } from '@websublime/workspace-tools';
78//!
79//! // Get workspace status
80//! const result = await status({ root: '.' });
81//! if (result.success) {
82//! console.log(result.data.packages);
83//! } else {
84//! console.error(`Error [${result.error.code}]: ${result.error.message}`);
85//! }
86//! ```
87//!
88//! ### Error Handling
89//!
90//! ```typescript
91//! import { changesetAdd } from '@websublime/workspace-tools';
92//!
93//! const result = await changesetAdd({
94//! root: '.',
95//! packages: ['@scope/pkg1'],
96//! bumpType: 'minor',
97//! message: 'Add new feature'
98//! });
99//!
100//! if (!result.success) {
101//! switch (result.error.code) {
102//! case 'EVALIDATION':
103//! console.error('Invalid parameters:', result.error.message);
104//! break;
105//! case 'EGIT':
106//! console.error('Git error:', result.error.message);
107//! break;
108//! default:
109//! console.error('Unexpected error:', result.error.message);
110//! }
111//! }
112//! ```
113
114#![warn(missing_docs)]
115#![warn(rustdoc::missing_crate_level_docs)]
116#![deny(unused_must_use)]
117#![deny(clippy::unwrap_used)]
118#![deny(clippy::expect_used)]
119#![deny(clippy::todo)]
120#![deny(clippy::unimplemented)]
121#![deny(clippy::panic)]
122
123#[macro_use]
124extern crate napi_derive;
125
126pub(crate) mod commands;
127pub(crate) mod error;
128pub(crate) mod response;
129pub(crate) mod types;
130pub(crate) mod validation;
131
132// Re-export NAPI functions from commands module
133// TODO: will be implemented on story 3.2 (status command)
134// TODO: will be implemented on story 3.4 (init command)
135// TODO: will be implemented on story 4.2-4.8 (changeset commands)
136// TODO: will be implemented on story 5.2-5.4 (bump commands)
137// TODO: will be implemented on story 6.3 (execute command)
138// TODO: will be implemented on story 7.2-7.3 (config commands)
139// TODO: will be implemented on story 8.2-8.4 (upgrade commands)
140// TODO: will be implemented on story 9.1-9.3 (remaining commands)
141
142/// Version of the crate.
143pub const VERSION: &str = env!("CARGO_PKG_VERSION");
144
145/// Returns the version of the crate.
146///
147/// This function is exposed to Node.js and returns the current version
148/// of the `sublime_node_tools` crate.
149///
150/// # Returns
151///
152/// A string containing the semantic version of the crate.
153///
154/// # Examples
155///
156/// ```typescript
157/// import { getVersion } from '@websublime/workspace-tools';
158///
159/// console.log(`Using workspace-tools version: ${getVersion()}`);
160/// ```
161#[napi]
162#[must_use]
163pub fn get_version() -> String {
164 VERSION.to_string()
165}
166
167#[cfg(test)]
168mod tests;