domainforge 0.13.0

package/justfile

@@ -0,0 +1,200 @@
+default := "ai-validate"
+cargo := `if command -v cargo >/dev/null 2>&1; then printf 'cargo'; elif command -v devbox >/dev/null 2>&1; then printf 'devbox run -- cargo'; else printf 'cargo'; fi`
+
+# Run all validation checks required for CI and AI agents
+ai-validate:
+    {{cargo}} test -p domainforge-core --features cli
+
+# Test tasks - run per-language test suites
+rust-test:
+    @echo "Running Rust tests..."
+    {{cargo}} test -p domainforge-core --features cli
+
+# Test all CLI commands
+cli-test:
+    {{cargo}} test -p domainforge-core --test cli_tests --features cli
+
+# Run CLI validation examples
+cli-validate:
+    cd domainforge-core/examples/cli && ./validate_example.sh
+
+# Run CLI import/export workflow
+cli-workflow:
+    cd domainforge-core/examples/cli && ./import_export_workflow.sh
+
+build-rust-tests:
+    @echo "Build Rust tests without running them (to prepare debug binaries)"
+    {{cargo}} test -p domainforge-core --features cli --no-run
+
+python-test:
+    @echo "Running Python tests..."
+    # Prefer the virtualenv python if it exists to avoid system site-packages and PEP 668 restrictions
+    if [ -x ".venv/bin/python" ]; then \
+        .venv/bin/python -m pytest -q; \
+    else \
+        python3 -m pytest -q || python -m pytest -q; \
+    fi
+
+ts-test:
+    @echo "Running TypeScript tests (Vitest)..."
+    if command -v bun >/dev/null 2>&1; then \
+        bun test; \
+    else \
+        npm run test:node --silent; \
+    fi
+
+all-tests:
+    @echo "Running all tests (Rust, Python, TypeScript)..."
+    just rust-test
+    just python-test
+    just ts-test
+prepare-rust-debug:
+    @echo "Prepare a Rust test binary for codelldb debugging (build & symlink)"
+    if [ -z "${RUST_TEST_NAME-}" ]; then RUST_TEST_NAME="entity_tests"; fi
+    echo "Using RUST_TEST_NAME=${RUST_TEST_NAME}"
+    ./scripts/prepare_rust_debug.sh "${RUST_TEST_NAME}"
+clear-rust-debug:
+    @echo "Clear symlink created for rust debug binary"
+    ./scripts/clear_debug_test.sh || true
+python-setup:
+    @echo "Setting up Python virtualenv and installing dev dependencies..."
+    rm -rf .venv
+    python -m venv .venv || python3 -m venv .venv || (echo "Python 3 is required; please install python."; exit 1)
+    .venv/bin/python -m pip install --upgrade pip
+    # Install runtime requirements if present
+    if [ -f requirements.txt ]; then .venv/bin/python -m pip install -r requirements.txt || true; fi
+    # Install development requirements if present
+    if [ -f requirements-dev.txt ]; then .venv/bin/python -m pip install -r requirements-dev.txt || true; fi
+    # Install dev/test tooling
+    .venv/bin/python -m pip install -U pytest maturin
+    # Build & install the Python bindings into the venv.
+    # pyproject.toml lives in domainforge-python/ and declares manifest-path, features,
+    # and module-name under [tool.maturin]. Do NOT pass --manifest-path on the CLI:
+    # maturin resolves the pyproject from the manifest dir when it's given, which makes
+    # it ignore [tool.maturin] (features/module-name) and fall back to cffi. Invoke from
+    # domainforge-python/ so maturin reads the pyproject next to it.
+    cd domainforge-python && ../.venv/bin/maturin develop --release || (cd domainforge-python && ../.venv/bin/maturin develop)
+
+install-just:
+    @echo "Checking if 'just' is already installed..."
+    if command -v just >/dev/null 2>&1; then \
+        echo "just is already installed: $(just --version)"; exit 0; \
+    fi
+    @echo "Attempting to install 'just' via OS package manager..."
+    if command -v winget >/dev/null 2>&1; then \
+        echo "Installing via winget..."; winget install --id Just -e || true; \
+    fi;
+    if command -v scoop >/dev/null 2>&1; then \
+        echo "Installing via scoop..."; scoop install just || true; \
+    fi;
+    if command -v brew >/dev/null 2>&1; then \
+        brew install just || true; \
+    fi;
+    if command -v apt-get >/dev/null 2>&1; then \
+        sudo apt-get update && sudo apt-get install -y just || true; \
+    fi;
+    if command -v dnf >/dev/null 2>&1; then \
+        sudo dnf install -y just || true; \
+    fi;
+    if command -v pacman >/dev/null 2>&1; then \
+        sudo pacman -S --noconfirm just || true; \
+    fi;
+    @echo "Fallback: attempt to install via cargo..."
+    cargo install just --locked || (echo "cargo install just failed; please install manually using your OS package manager (brew, apt, dnf, pacman) or visit https://github.com/casey/just#installation"; exit 1)
+
+setup:
+    @echo "Installing TypeScript dependencies and Python dev dependencies..."
+    npm ci || npm install
+    # Install Git hooks if lefthook is available from local dependencies or PATH
+    npx --yes lefthook install || true
+    # Prepare a Python virtualenv and install dev dependencies if possible
+    just python-setup || true
+
+python-clean:
+    @echo "Removing Python virtual environment (.venv)"
+    if [ -d .venv ]; then rm -rf .venv || true; fi
+
+audit:
+    cargo audit
+    cargo deny check
+
+smoke-test-npm:
+    @echo "Running npm pack smoke test..."
+    @output=$(cd domainforge-typescript && npm pack --dry-run 2>&1); \
+    echo "$output"; \
+    echo "$output" | grep -q "index\.js" || { echo "ERROR: index.js missing from pack"; exit 1; }; \
+    echo "$output" | grep -q "index\.d\.ts" || { echo "ERROR: index.d.ts missing from pack"; exit 1; }; \
+    echo "$output" | grep -q "domainforge-core.*\.node" || { echo "ERROR: native .node binary missing from pack"; exit 1; }; \
+    echo "$output" | grep -q "README\.md" || { echo "ERROR: README.md missing from pack"; exit 1; }; \
+    echo "$output" | grep -q "LICENSE" || { echo "ERROR: LICENSE missing from pack"; exit 1; }; \
+    echo "npm pack smoke test passed"
+
+smoke-test-wasm:
+    @echo "Running WASM pkg smoke test..."
+    test -d target/wasm-pkg || { echo "ERROR: WASM pkg not built. Run scripts/build-wasm.sh first"; exit 1; }
+    for f in domainforge_core.js domainforge_core.d.ts domainforge_core_bg.wasm domainforge_core_bg.wasm.d.ts package.json; do \
+        test -f target/wasm-pkg/$f || { echo "ERROR: missing $f"; exit 1; }; \
+    done
+    @echo "WASM smoke test passed"
+
+enterprise-verify:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    echo "=== Enterprise Release Verification ==="
+    echo "1/6: Format check..."
+    cargo fmt --all --check
+    echo "2/6: Clippy..."
+    cargo clippy --workspace --all-targets --all-features -- -D warnings
+    echo "3/6: Rust tests..."
+    cargo test --workspace --all-targets --all-features
+    echo "4/6: Doctests..."
+    cargo test -p domainforge-core --features cli --doc
+    echo "5/6: All language tests..."
+    just all-tests
+    echo "6/6: Audit..."
+    just audit
+    echo "=== Enterprise Verification PASSED ==="
+
+# ============================================================================
+# CI-specific recipes (used by GitHub Actions)
+# ============================================================================
+
+# Run Rust tests (CI variant)
+ci-test-rust:
+    @echo "Running Rust tests (CI)..."
+    {{cargo}} test --verbose --workspace --features cli
+
+# Run Python tests (CI variant)
+ci-test-python:
+    @echo "Running Python tests (CI)..."
+    .venv/bin/python -m pytest tests/
+
+# Run TypeScript tests (CI variant)
+ci-test-ts:
+    @echo "Running TypeScript tests (CI)..."
+    npm test
+
+# Verify CLI binary can execute
+ci-verify-binary BINARY_PATH:
+    @echo "Verifying CLI binary: {{BINARY_PATH}}"
+    python3 scripts/ci_tasks.py verify-cli --binary "{{BINARY_PATH}}"
+
+# Check CLI binary size
+ci-check-binary-size BINARY_PATH MAX_BYTES="52428800":
+    @echo "Checking binary size: {{BINARY_PATH}}"
+    python3 scripts/ci_tasks.py check-size --file "{{BINARY_PATH}}" --max-bytes {{MAX_BYTES}} --label "CLI binary"
+
+# Package CLI binary for release
+ci-package-binary BINARY_PATH OUTPUT_PATH:
+    @echo "Packaging binary: {{BINARY_PATH}} -> {{OUTPUT_PATH}}"
+    python3 scripts/ci_tasks.py package --input "{{BINARY_PATH}}" --output "{{OUTPUT_PATH}}"
+
+# Verify packaged archive
+ci-verify-package ARCHIVE_PATH BINARY_NAME="domainforge":
+    @echo "Verifying packaged archive: {{ARCHIVE_PATH}}"
+    python3 scripts/ci_tasks.py unpack-verify --archive "{{ARCHIVE_PATH}}" --binary-name "{{BINARY_NAME}}"
+
+# Check packaged artifact size
+ci-check-package-size ARCHIVE_PATH MAX_BYTES="73400320":
+    @echo "Checking package size: {{ARCHIVE_PATH}}"
+    python3 scripts/ci_tasks.py check-size --file "{{ARCHIVE_PATH}}" --max-bytes {{MAX_BYTES}} --label "Packaged artifact"

package/lefthook.yml

@@ -0,0 +1,13 @@
+pre-commit:
+  commands:
+    cargo-fmt:
+      glob: "**/*.rs"
+      run: cargo fmt --all -- --check
+    cargo-clippy:
+      glob: "**/*.rs"
+      run: cargo clippy --all-targets --all-features -- -D warnings
+
+commit-msg:
+  commands:
+    commitlint:
+      run: ./scripts/run_commitlint.sh {1}

package/lib/validate_native_exports.d.ts

@@ -0,0 +1,4 @@
+export function validateNativeExports(
+  nativeBinding: Record<string, unknown> | null | undefined,
+  requiredExports: string[],
+): void;

package/lib/validate_native_exports.js

@@ -0,0 +1,12 @@
+// validate_native_exports.js
+// Helper to verify native binding exports and throw a descriptive error when missing.
+"use strict";
+
+function validateNativeExports(nativeBinding, requiredExports) {
+    const missing = requiredExports.filter((name) => !nativeBinding || !Object.prototype.hasOwnProperty.call(nativeBinding, name));
+    if (missing.length > 0) {
+        throw new Error(`Native binding missing required export(s): ${missing.join(', ')}. Ensure the native addon was built and exposes these symbol(s).`);
+    }
+}
+
+module.exports = { validateNativeExports };

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "domainforge",
+  "version": "0.13.0",
+  "private": false,
+  "workspaces": [
+    "domainforge-typescript"
+  ],
+  "scripts": {
+    "test": "bun vitest run",
+    "test:node": "npx vitest run",
+    "test:types": "tsc --noEmit --strict --skipLibCheck false -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "lefthook": "^2.1.9"
+  },
+  "engines": {
+    "node": ">= 18",
+    "bun": ">= 1.1.0"
+  }
+}

package/pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+minversion = 7.4
+testpaths = tests
+python_files = test_*.py
+addopts = -q

package/python/tests/test_registry.py

@@ -0,0 +1,75 @@
+import pytest
+import textwrap
+
+import domainforge
+
+
+def test_registry_discover_and_resolve(tmp_path):
+    # Skip this test if runtime package isn't built with python FFI enabled
+    if not hasattr(domainforge, "NamespaceRegistry"):
+        return
+    base = tmp_path
+    domains = base / "domains" / "logistics"
+    domains.mkdir(parents=True)
+    file_path = domains / "warehouse.sea"
+    file_path.write_text('Entity "Warehouse"')
+
+    registry_path = base / ".sea-registry.toml"
+    registry_content = textwrap.dedent("""\
+        version = 1
+        [[namespaces]]
+        namespace = "logistics"
+        patterns = ["domains/logistics/**/*.sea"]
+    """)
+    registry_path.write_text(registry_content)
+
+    reg = domainforge.NamespaceRegistry.from_file(str(registry_path))
+    assert reg is not None
+    files = reg.resolve_files()
+    assert len(files) == 1
+    assert files[0].path.endswith("warehouse.sea")
+    assert files[0].namespace == "logistics"
+    # fail_on_ambiguity for trivial case should still succeed (no ambiguity)
+    files = reg.resolve_files(False)
+    assert len(files) == 1
+
+
+def test_registry_precedence_long_and_tie(tmp_path):
+    # Skip if not installed with FFI bindings
+    if not hasattr(domainforge, "NamespaceRegistry"):
+        return
+    base = tmp_path
+    domains = base / "domains" / "logistics"
+    domains.mkdir(parents=True)
+    file_path = domains / "warehouse.sea"
+    file_path.write_text('Entity "Warehouse"')
+
+    # long prefix precedence
+    registry_path = base / ".sea-registry.toml"
+    registry_content = (
+        "version = 1\n"
+        'default_namespace = "default"\n\n'
+        '[[namespaces]]\nnamespace = "short"\npatterns = ["domains/**/*.sea"]\n\n'
+        '[[namespaces]]\nnamespace = "long"\npatterns = ["domains/logistics/**/*.sea"]\n'
+    )
+    registry_path.write_text(registry_content)
+    reg = domainforge.NamespaceRegistry.from_file(str(registry_path))
+    assert reg.namespace_for(str(file_path)) == "long"
+
+    # alphabetical tie-breaker
+    registry_content = (
+        "version = 1\n"
+        'default_namespace = "default"\n\n'
+        '[[namespaces]]\nnamespace = "logistics"\npatterns = ["domains/*/warehouse.sea"]\n\n'
+        '[[namespaces]]\nnamespace = "finance"\npatterns = ["domains/*/warehouse.sea"]\n'
+    )
+    registry_path.write_text(registry_content)
+    reg = domainforge.NamespaceRegistry.from_file(str(registry_path))
+    assert reg.namespace_for(str(file_path)) == "finance"
+
+    # When asking to fail on ambiguity, an exception should be raised
+    with pytest.raises(Exception):
+        reg.namespace_for(str(file_path), True)
+    # resolve_files should raise when fail_on_ambiguity True
+    with pytest.raises(Exception):
+        reg.resolve_files(True)

package/python/tests/test_units.py

@@ -0,0 +1,18 @@
+import domainforge
+
+
+def test_dimension_parse_case_insensitive():
+    if not hasattr(domainforge, "Dimension"):
+        return
+    d1 = domainforge.Dimension.parse("currency")
+    d2 = domainforge.Dimension.parse("Currency")
+    assert str(d1) == str(d2)
+    assert str(d1) == "Currency"
+
+
+def test_unit_constructor_and_getters():
+    if not hasattr(domainforge, "Unit"):
+        return
+    u = domainforge.Unit("USD", "US Dollar", "Currency", 1.0, "USD")
+    assert u.symbol == "USD"
+    assert u.base_unit == "USD"

package/release-please-config.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "include-component-in-tag": true,
+  "tag-separator": "-",
+  "component-no-space": true,
+  "pull-request-title-pattern": "chore: release ${component} ${version}",
+  "plugins": [
+    {
+      "type": "linked-versions",
+      "groupName": "domainforge",
+      "components": ["domainforge-core", "domainforge", "domainforge-typescript"]
+    }
+  ],
+  "changelog-sections": [
+    { "type": "feat", "section": "Features" },
+    { "type": "fix", "section": "Bug Fixes" },
+    { "type": "perf", "section": "Performance" },
+    { "type": "deps", "section": "Dependencies" },
+    { "type": "revert", "section": "Reverts" },
+    { "type": "docs", "section": "Documentation", "hidden": true },
+    { "type": "refactor", "section": "Refactoring", "hidden": true },
+    { "type": "test", "section": "Tests", "hidden": true },
+    { "type": "chore", "section": "Miscellaneous", "hidden": true },
+    { "type": "build", "section": "Build System", "hidden": true },
+    { "type": "ci", "section": "Continuous Integration", "hidden": true }
+  ],
+  "packages": {
+    "domainforge-core": {
+      "release-type": "rust",
+      "package-name": "domainforge-core",
+      "component": "domainforge-core",
+      "changelog-path": "CHANGELOG.md"
+    },
+    "domainforge-python": {
+      "release-type": "python",
+      "package-name": "domainforge",
+      "component": "domainforge",
+      "changelog-path": "CHANGELOG-python.md",
+      "extra-files": ["pyproject.toml"]
+    },
+    "domainforge-typescript": {
+      "release-type": "node",
+      "package-name": "@godspeedai/domainforge",
+      "component": "domainforge-typescript",
+      "changelog-path": "CHANGELOG-typescript.md",
+      "extra-files": ["package.json"]
+    }
+  }
+}

package/requirements-dev.txt

@@ -0,0 +1,3 @@
+pytest>=7.4
+maturin>=1.7
+mypy>=1.0

package/requirements.txt

@@ -0,0 +1,3 @@
+tree-sitter==0.25.2
+tree-sitter-language-pack==0.10.0
+maturin>=1.0

package/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.92.0"
+components = ["rustfmt", "clippy"]

package/schemas/ast-v1.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SEA DSL Abstract Syntax Tree",
+  "version": "1.0.0",
+  "type": "object",
+  "properties": {
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "namespace": { "type": "string" },
+    "imports": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/Import" }
+    },
+    "entities": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/Entity" }
+    },
+    "resources": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/Resource" }
+    },
+    "flows": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/Flow" }
+    },
+    "policies": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/Policy" }
+    }
+  },
+  "definitions": {
+    "Import": {
+      "type": "object",
+      "properties": {
+        "path": { "type": "string" }
+      },
+      "required": ["path"]
+    },
+    "Entity": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" }
+      },
+      "required": ["name"]
+    },
+    "Resource": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "unit": { "type": "string" }
+      },
+      "required": ["name", "unit"]
+    },
+    "Flow": {
+      "type": "object",
+      "properties": {
+        "resource": { "type": "string" },
+        "from": { "type": "string" },
+        "to": { "type": "string" },
+        "quantity": { "type": "number" }
+      },
+      "required": ["resource", "from", "to", "quantity"]
+    },
+    "Policy": {
+      "type": "object",
+      "properties": {
+        "description": { "type": "string" },
+        "expression": { "type": "string" }
+      },
+      "required": ["description", "expression"]
+    }
+  }
+}