domainforge 0.13.0

package/domainforge-core/src/typescript/error.rs

@@ -0,0 +1,146 @@
+/// TypeScript-native error handling for domainforge
+///
+/// This module provides error conversion that creates native JavaScript/TypeScript
+/// Error objects with typed properties. TypeScript users should never see Rust errors.
+use crate::validation_error::ValidationError;
+use napi::bindgen_prelude::*;
+
+/// Convert ValidationError to napi Error with custom properties
+pub fn to_napi_error(err: ValidationError) -> Error {
+    let code = err.error_code().as_str().to_string();
+    let error_type = match &err {
+        ValidationError::SyntaxError { .. } => "SyntaxError",
+        ValidationError::TypeError { .. } => "TypeError",
+        ValidationError::UnitError { .. } => "UnitError",
+        ValidationError::UndefinedReference { .. } => "ReferenceError",
+        ValidationError::ScopeError { .. } => "ScopeError",
+        ValidationError::DuplicateDeclaration { .. } => "DuplicateDeclaration",
+        ValidationError::DeterminismError { .. } => "DeterminismError",
+        ValidationError::InvalidExpression { .. } => "InvalidExpression",
+    };
+
+    let message = err.to_string();
+    let mut error = Error::from_reason(message);
+
+    // Add error-specific properties based on variant
+    match err {
+        ValidationError::SyntaxError {
+            line,
+            column,
+            end_line,
+            end_column,
+            ..
+        } => {
+            // Store as JSON string since napi Error doesn't support arbitrary properties directly
+            let metadata = serde_json::json!({
+                "code": code,
+                "errorType": error_type,
+                "line": line,
+                "column": column,
+                "endLine": end_line,
+                "endColumn": end_column,
+            });
+            attach_metadata(&mut error, metadata);
+        }
+        ValidationError::TypeError {
+            expected_type,
+            found_type,
+            suggestion,
+            ..
+        } => {
+            let metadata = serde_json::json!({
+                "code": code,
+                "errorType": error_type,
+                "expected": expected_type,
+                "found": found_type,
+                "suggestion": suggestion,
+            });
+            attach_metadata(&mut error, metadata);
+        }
+        ValidationError::UnitError {
+            expected,
+            found,
+            suggestion,
+            ..
+        } => {
+            let metadata = serde_json::json!({
+                "code": code,
+                "errorType": error_type,
+                "expectedDimension": format!("{}", expected),
+                "foundDimension": format!("{}", found),
+                "suggestion": suggestion,
+            });
+            attach_metadata(&mut error, metadata);
+        }
+        ValidationError::UndefinedReference {
+            reference_type,
+            name,
+            suggestion,
+            ..
+        } => {
+            let metadata = serde_json::json!({
+                "code": code,
+                "errorType": error_type,
+                "referenceType": reference_type.to_string(),
+                "name": name,
+                "suggestion": suggestion,
+            });
+            attach_metadata(&mut error, metadata);
+        }
+        ValidationError::ScopeError {
+            variable,
+            available_in,
+            suggestion,
+            ..
+        } => {
+            let metadata = serde_json::json!({
+                "code": code,
+                "errorType": error_type,
+                "variable": variable,
+                "availableIn": available_in,
+                "suggestion": suggestion,
+            });
+            attach_metadata(&mut error, metadata);
+        }
+        ValidationError::DuplicateDeclaration {
+            name,
+            first_location,
+            second_location,
+        } => {
+            let metadata = serde_json::json!({
+                "code": code,
+                "errorType": error_type,
+                "name": name,
+                "firstLocation": first_location,
+                "secondLocation": second_location,
+            });
+            attach_metadata(&mut error, metadata);
+        }
+        ValidationError::DeterminismError { hint, .. } => {
+            let metadata = serde_json::json!({
+                "code": code,
+                "errorType": error_type,
+                "hint": hint,
+            });
+            attach_metadata(&mut error, metadata);
+        }
+        ValidationError::InvalidExpression { suggestion, .. } => {
+            let metadata = serde_json::json!({
+                "code": code,
+                "errorType": error_type,
+                "suggestion": suggestion,
+            });
+            attach_metadata(&mut error, metadata);
+        }
+    }
+
+    error
+}
+
+fn attach_metadata(error: &mut Error, metadata: serde_json::Value) {
+    error.reason = format!(
+        "{}\n__metadata__: {}",
+        error.reason,
+        serde_json::to_string(&metadata).unwrap_or_else(|e| format!("serialization_error: {}", e))
+    );
+}

package/domainforge-core/src/typescript/formatter.rs

@@ -0,0 +1,76 @@
+//! TypeScript bindings for the SEA formatter.
+
+use crate::formatter::{format, FormatConfig, IndentStyle};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+/// Configuration options for the formatter.
+#[napi(object)]
+pub struct FormatOptions {
+    /// Number of spaces per indent level (default: 4)
+    pub indent_width: Option<u32>,
+    /// Use tabs instead of spaces for indentation (default: false)
+    pub use_tabs: Option<bool>,
+    /// Preserve comments in output (default: true)
+    pub preserve_comments: Option<bool>,
+    /// Sort imports alphabetically (default: true)
+    pub sort_imports: Option<bool>,
+}
+
+/// Format SEA-DSL source code.
+///
+/// @param source - The SEA-DSL source code to format
+/// @param options - Optional formatting configuration
+/// @returns The formatted source code
+/// @throws Error if the source code cannot be parsed
+///
+/// @example
+/// ```typescript
+/// import { formatSource } from '@godspeedai/domainforge';
+///
+/// const formatted = formatSource('Entity   "Foo"  in    bar');
+/// console.log(formatted); // Entity "Foo" in bar
+/// ```
+#[napi]
+pub fn format_source(source: String, options: Option<FormatOptions>) -> Result<String> {
+    let opts = options.unwrap_or(FormatOptions {
+        indent_width: None,
+        use_tabs: None,
+        preserve_comments: None,
+        sort_imports: None,
+    });
+
+    let config = FormatConfig {
+        indent_width: opts.indent_width.unwrap_or(4) as usize,
+        indent_style: if opts.use_tabs.unwrap_or(false) {
+            IndentStyle::Tabs
+        } else {
+            IndentStyle::Spaces
+        },
+        preserve_comments: opts.preserve_comments.unwrap_or(true),
+        sort_imports: opts.sort_imports.unwrap_or(true),
+        ..Default::default()
+    };
+
+    format(&source, config).map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// Check if SEA-DSL source code is already formatted.
+///
+/// @param source - The SEA-DSL source code to check
+/// @param options - Optional formatting configuration
+/// @returns True if the source is already formatted, false otherwise
+/// @throws Error if the source code cannot be parsed
+///
+/// @example
+/// ```typescript
+/// import { checkFormat } from '@godspeedai/domainforge';
+///
+/// console.log(checkFormat('Entity "Foo" in bar\n')); // true
+/// console.log(checkFormat('Entity   "Foo"  in    bar')); // false
+/// ```
+#[napi]
+pub fn check_format(source: String, options: Option<FormatOptions>) -> Result<bool> {
+    let formatted = format_source(source.clone(), options)?;
+    Ok(source == formatted)
+}

package/domainforge-core/src/typescript/graph.rs

@@ -0,0 +1,391 @@
+#![allow(clippy::new_without_default, clippy::inherent_to_string)]
+
+use crate::graph::Graph as RustGraph;
+use crate::parser;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use std::str::FromStr;
+use uuid::Uuid;
+
+use super::primitives::{Entity, Flow, Relation, Resource, ResourceInstance, Role};
+
+#[napi]
+pub struct Graph {
+    inner: RustGraph,
+}
+
+/// Helper function to parse a UUID string into a ConceptId
+fn parse_concept_id(id: &str) -> Result<crate::ConceptId> {
+    let uuid =
+        Uuid::from_str(id).map_err(|e| Error::from_reason(format!("Invalid UUID: {}", e)))?;
+    Ok(crate::ConceptId::from(uuid))
+}
+
+#[napi]
+impl Graph {
+    #[napi(constructor)]
+    pub fn new() -> Self {
+        Self {
+            inner: RustGraph::new(),
+        }
+    }
+
+    #[napi]
+    pub fn add_entity(&mut self, entity: &Entity) -> Result<()> {
+        self.inner
+            .add_entity(entity.inner_ref().clone())
+            .map_err(Error::from_reason)
+    }
+
+    #[napi]
+    pub fn add_resource(&mut self, resource: &Resource) -> Result<()> {
+        self.inner
+            .add_resource(resource.inner_ref().clone())
+            .map_err(Error::from_reason)
+    }
+
+    #[napi]
+    pub fn add_flow(&mut self, flow: &Flow) -> Result<()> {
+        self.inner
+            .add_flow(flow.inner_ref().clone())
+            .map_err(Error::from_reason)
+    }
+
+    #[napi]
+    pub fn add_instance(&mut self, instance: &ResourceInstance) -> Result<()> {
+        self.inner
+            .add_instance(instance.inner_ref().clone())
+            .map_err(Error::from_reason)
+    }
+
+    #[napi]
+    pub fn add_role(&mut self, role: &Role) -> Result<()> {
+        self.inner
+            .add_role(role.inner_ref().clone())
+            .map_err(Error::from_reason)
+    }
+
+    #[napi]
+    pub fn add_relation(&mut self, relation: &Relation) -> Result<()> {
+        self.inner
+            .add_relation_type(relation.inner_ref().clone())
+            .map_err(Error::from_reason)
+    }
+
+    #[napi]
+    pub fn entity_count(&self) -> u32 {
+        self.inner.entity_count() as u32
+    }
+
+    #[napi]
+    pub fn resource_count(&self) -> u32 {
+        self.inner.resource_count() as u32
+    }
+
+    #[napi]
+    pub fn flow_count(&self) -> u32 {
+        self.inner.flow_count() as u32
+    }
+
+    #[napi]
+    pub fn instance_count(&self) -> u32 {
+        self.inner.instance_count() as u32
+    }
+
+    #[napi]
+    pub fn pattern_count(&self) -> u32 {
+        self.inner.pattern_count() as u32
+    }
+
+    #[napi]
+    pub fn role_count(&self) -> u32 {
+        self.inner.role_count() as u32
+    }
+
+    #[napi]
+    pub fn relation_count(&self) -> u32 {
+        self.inner.relation_count() as u32
+    }
+
+    #[napi]
+    pub fn has_entity(&self, id: String) -> Result<bool> {
+        let cid = parse_concept_id(&id)?;
+        Ok(self.inner.has_entity(&cid))
+    }
+
+    #[napi]
+    pub fn has_resource(&self, id: String) -> Result<bool> {
+        let cid = parse_concept_id(&id)?;
+        Ok(self.inner.has_resource(&cid))
+    }
+
+    #[napi]
+    pub fn has_flow(&self, id: String) -> Result<bool> {
+        let cid = parse_concept_id(&id)?;
+        Ok(self.inner.has_flow(&cid))
+    }
+
+    #[napi]
+    pub fn has_instance(&self, id: String) -> Result<bool> {
+        let cid = parse_concept_id(&id)?;
+        Ok(self.inner.has_instance(&cid))
+    }
+
+    #[napi]
+    pub fn get_entity(&self, id: String) -> Result<Option<Entity>> {
+        let cid = parse_concept_id(&id)?;
+        Ok(self
+            .inner
+            .get_entity(&cid)
+            .map(|e| Entity::from_rust(e.clone())))
+    }
+
+    #[napi]
+    pub fn get_resource(&self, id: String) -> Result<Option<Resource>> {
+        let cid = parse_concept_id(&id)?;
+        Ok(self
+            .inner
+            .get_resource(&cid)
+            .map(|r| Resource::from_rust(r.clone())))
+    }
+
+    #[napi]
+    pub fn get_flow(&self, id: String) -> Result<Option<Flow>> {
+        let cid = parse_concept_id(&id)?;
+        Ok(self
+            .inner
+            .get_flow(&cid)
+            .map(|f| Flow::from_rust(f.clone())))
+    }
+
+    #[napi]
+    pub fn get_instance(&self, id: String) -> Result<Option<ResourceInstance>> {
+        let cid = parse_concept_id(&id)?;
+        Ok(self
+            .inner
+            .get_instance(&cid)
+            .map(|i| ResourceInstance::from_rust(i.clone())))
+    }
+
+    #[napi]
+    pub fn find_role_by_name(&self, name: String) -> Option<String> {
+        self.inner
+            .find_role_by_name(&name)
+            .map(|uuid| uuid.to_string())
+    }
+
+    #[napi]
+    pub fn find_entity_by_name(&self, name: String) -> Option<String> {
+        self.inner
+            .find_entity_by_name(&name)
+            .map(|uuid| uuid.to_string())
+    }
+
+    #[napi]
+    pub fn find_resource_by_name(&self, name: String) -> Option<String> {
+        self.inner
+            .find_resource_by_name(&name)
+            .map(|uuid| uuid.to_string())
+    }
+
+    #[napi]
+    pub fn flows_from(&self, entity_id: String) -> Result<Vec<Flow>> {
+        let cid = parse_concept_id(&entity_id)?;
+        Ok(self
+            .inner
+            .flows_from(&cid)
+            .into_iter()
+            .map(|f| Flow::from_rust(f.clone()))
+            .collect())
+    }
+
+    #[napi]
+    pub fn flows_to(&self, entity_id: String) -> Result<Vec<Flow>> {
+        let cid = parse_concept_id(&entity_id)?;
+        Ok(self
+            .inner
+            .flows_to(&cid)
+            .into_iter()
+            .map(|f| Flow::from_rust(f.clone()))
+            .collect())
+    }
+
+    #[napi]
+    pub fn all_entities(&self) -> Vec<Entity> {
+        self.inner
+            .all_entities()
+            .into_iter()
+            .map(|e| Entity::from_rust(e.clone()))
+            .collect()
+    }
+
+    #[napi]
+    pub fn all_resources(&self) -> Vec<Resource> {
+        self.inner
+            .all_resources()
+            .into_iter()
+            .map(|r| Resource::from_rust(r.clone()))
+            .collect()
+    }
+
+    #[napi]
+    pub fn all_flows(&self) -> Vec<Flow> {
+        self.inner
+            .all_flows()
+            .into_iter()
+            .map(|f| Flow::from_rust(f.clone()))
+            .collect()
+    }
+
+    #[napi]
+    pub fn all_instances(&self) -> Vec<ResourceInstance> {
+        self.inner
+            .all_instances()
+            .into_iter()
+            .map(|i| ResourceInstance::from_rust(i.clone()))
+            .collect()
+    }
+
+    #[napi]
+    pub fn all_roles(&self) -> Vec<Role> {
+        self.inner
+            .all_roles()
+            .into_iter()
+            .map(|r| Role::from_rust(r.clone()))
+            .collect()
+    }
+
+    #[napi]
+    pub fn all_relations(&self) -> Vec<Relation> {
+        self.inner
+            .all_relations()
+            .into_iter()
+            .map(|relation| Relation::from_rust(relation.clone()))
+            .collect()
+    }
+
+    #[napi(factory)]
+    pub fn parse(source: String) -> Result<Self> {
+        let graph = parser::parse_to_graph(&source)
+            .map_err(|e| Error::from_reason(format!("Parse error: {}", e)))?;
+
+        Ok(Self { inner: graph })
+    }
+
+    #[napi]
+    pub fn export_calm(&self) -> Result<String> {
+        crate::calm::export(&self.inner)
+            .and_then(|value| {
+                serde_json::to_string_pretty(&value)
+                    .map_err(|e| format!("Serialization error: {}", e))
+            })
+            .map_err(Error::from_reason)
+    }
+
+    #[napi(factory)]
+    pub fn import_calm(calm_json: String) -> Result<Self> {
+        let value: serde_json::Value = serde_json::from_str(&calm_json)
+            .map_err(|e| Error::from_reason(format!("Invalid JSON: {}", e)))?;
+
+        let graph = crate::calm::import(value)
+            .map_err(|e| Error::from_reason(format!("Import error: {}", e)))?;
+
+        Ok(Self { inner: graph })
+    }
+
+    /// Export the graph to Protobuf .proto text format.
+    ///
+    /// @param package - The Protobuf package name (e.g., "com.example.api")
+    /// @param namespace - Optional namespace filter (undefined = all namespaces)
+    /// @param projectionName - Optional name for the projection (used in comments)
+    /// @param includeGovernance - Whether to include governance messages (PolicyViolation, MetricEvent)
+    /// @param includeServices - Whether to generate gRPC service definitions from Flow patterns
+    /// @returns The generated .proto file content as a string
+    #[napi]
+    pub fn export_protobuf(
+        &self,
+        package: String,
+        namespace: Option<String>,
+        projection_name: Option<String>,
+        include_governance: Option<bool>,
+        include_services: Option<bool>,
+    ) -> String {
+        let ns = namespace.as_deref().unwrap_or("");
+        let proj_name = projection_name.as_deref().unwrap_or("");
+        let include_gov = include_governance.unwrap_or(false);
+        let include_svc = include_services.unwrap_or(false);
+
+        let proto = crate::projection::ProtobufEngine::project_with_full_options(
+            &self.inner,
+            ns,
+            &package,
+            proj_name,
+            include_gov,
+            include_svc,
+        );
+        proto.to_proto_string()
+    }
+
+    #[napi]
+    pub fn add_policy(&mut self, policy_json: String) -> Result<()> {
+        let policy: crate::policy::Policy = serde_json::from_str(&policy_json)
+            .map_err(|e| Error::from_reason(format!("Invalid Policy JSON: {}", e)))?;
+        self.inner.add_policy(policy).map_err(Error::from_reason)
+    }
+
+    #[napi]
+    pub fn add_association(
+        &mut self,
+        owner: String,
+        owned: String,
+        rel_type: String,
+    ) -> Result<()> {
+        let owner_cid = parse_concept_id(&owner)?;
+        let owned_cid = parse_concept_id(&owned)?;
+        self.inner
+            .add_association(&owner_cid, &owned_cid, &rel_type)
+            .map_err(Error::from_reason)
+    }
+
+    /// Evaluate a Policy JSON payload against this Graph.
+    ///
+    /// The `policy_json` argument must be the JSON representation of `crate::policy::Policy`
+    /// (including fields like `id`, `name`, `modality`, `kind`, `version`, and `expression`).
+    /// Returns `EvaluationResult` exposed to TypeScript via napi, or an error if the policy JSON
+    /// is invalid or evaluation fails.
+    #[napi]
+    pub fn evaluate_policy(&self, policy_json: String) -> Result<super::policy::EvaluationResult> {
+        let policy: crate::policy::Policy = serde_json::from_str(&policy_json)
+            .map_err(|e| Error::from_reason(format!("Invalid Policy JSON: {}", e)))?;
+        let result = policy
+            .evaluate(&self.inner)
+            .map_err(|e| Error::from_reason(format!("Policy evaluation error: {}", e)))?;
+        Ok(result.into())
+    }
+
+    /// Set the evaluation mode for policy evaluation.
+    /// When `useThreeValuedLogic` is true, policies will use three-valued logic (true, false, null).
+    /// When false, policies will use strict boolean logic (true, false).
+    #[napi]
+    pub fn set_evaluation_mode(&mut self, use_three_valued_logic: bool) {
+        self.inner.set_evaluation_mode(use_three_valued_logic);
+    }
+
+    /// Get the current evaluation mode.
+    /// Returns true if three-valued logic is enabled, false otherwise.
+    #[napi]
+    pub fn use_three_valued_logic(&self) -> bool {
+        self.inner.use_three_valued_logic()
+    }
+
+    #[napi]
+    pub fn to_string(&self) -> String {
+        format!(
+            "Graph(entities={}, resources={}, flows={}, instances={})",
+            self.inner.entity_count(),
+            self.inner.resource_count(),
+            self.inner.flow_count(),
+            self.inner.instance_count()
+        )
+    }
+}

package/domainforge-core/src/typescript/mod.rs

@@ -0,0 +1,9 @@
+pub mod authority;
+pub mod error;
+pub mod formatter;
+pub mod graph;
+pub mod policy;
+pub mod primitives;
+pub mod registry;
+pub mod semantic_pack;
+pub mod units;