match TypeScript and Rust API namespaces (#475)

.changeset/afraid-cups-hear.md

@@ -0,0 +1,5 @@
+---
+"changelog": minor
+---
+
+match TypeScript and Rust API namespaces

.vscode/settings.json

@@ -5,7 +5,7 @@
   "rust-analyzer.check.allTargets": true,
   "rust-analyzer.check.features": "all",
   "rust-analyzer.server.extraEnv": {
-    // Keep in sync with the CLI environment in "$REPO_ROOT/scripts/cargo/check.sh"
+    // _CARGO_CLI_ENV_VARS_ (keep In Sync)
     "CARGO": "${workspaceFolder}/bin/cargo",
     "RUSTC": "${workspaceFolder}/bin/rustc",
     "RUSTFMT": "${workspaceFolder}/bin/rustfmt",
@@ -28,5 +28,6 @@
   "triggerTaskOnSave.tasks": {
     "Validate Solidity Grammar": ["crates/solidity/inputs/schema/grammar/**/*.yml"]
   },
+  "typescript.tsdk": "node_modules/typescript/lib",
   "yaml.validate": false // Disable LSP validation for YAML files, as it is handled by our own cargo tasks
 }

crates/solidity/outputs/cargo/crate/src/lib.rs

@@ -16,6 +16,10 @@ mod _supress_binary_dependencies_ {
 pub use public_api::*;
 
 mod public_api {
+    /*
+     * __SLANG_PUBLIC_API_SYNC__ (please keep in sync across all other instances)
+     */
+
     pub use crate::generated::language::Language;
 
     pub mod syntax {

crates/solidity/outputs/npm/crate/.cargo/config.toml

@@ -0,0 +1,5 @@
+[build]
+# The monorepo Cargo workspace builds to `$REPO_ROOT/target` by default.
+# However, it uses different settings than the one NAPI sets during the build for this crate.
+# Let's use a separate target-dir "$THIS_CRATE/target" to avoid invalidating the workspace-level cache.
+target-dir = "./target"

crates/solidity/outputs/npm/package/.gitignore

@@ -1,2 +1,4 @@
 # NAPI generated binaries:
+# Unfortunately they need to be copied to each individual sub-package directory for execution or publishing.
+# Lets hide all of them.
 *.node

crates/solidity/outputs/npm/package/package.json

@@ -23,15 +23,20 @@
       "email": "[email protected]"
     }
   ],
-  "main": "src/generated/index.js",
-  "types": "src/generated/index.d.ts",
   "files": [
-    "src/generated/index.d.ts",
-    "src/generated/index.js",
+    "src/**/*.d.ts",
+    "src/**/*.js",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
+  "__exports_comment__": "__SLANG_PUBLIC_API_SYNC__ (please keep in sync across all other instances)",
+  "exports": {
+    ".": "./src/index.js",
+    "./syntax": "./src/syntax/index.js",
+    "./syntax/nodes": "./src/syntax/nodes/index.js",
+    "./syntax/parser": "./src/syntax/parser/index.js"
+  },
   "devDependencies": {
     "@napi-rs/cli": "2.15.2",
     "prettier": "2.8.6"

crates/solidity/outputs/npm/package/src/index.js

@@ -0,0 +1,7 @@
+/*
+ * __SLANG_PUBLIC_API_SYNC__ (please keep in sync across all other instances)
+ */
+
+export { Language } from "./generated";
+
+export * as syntax from "./syntax";

crates/solidity/outputs/npm/package/src/syntax/index.js

@@ -0,0 +1,6 @@
+/*
+ * __SLANG_PUBLIC_API_SYNC__ (please keep in sync across all other instances)
+ */
+
+export * as nodes from "./nodes";
+export * as parser from "./parser";

crates/solidity/outputs/npm/package/src/syntax/nodes/index.js

@@ -0,0 +1,5 @@
+/*
+ * __SLANG_PUBLIC_API_SYNC__ (please keep in sync across all other instances)
+ */
+
+export { NodeType, RuleKind, RuleNode, TokenNode, TokenKind } from "../../generated";

crates/solidity/outputs/npm/package/src/syntax/parser/index.js

@@ -0,0 +1,5 @@
+/*
+ * __SLANG_PUBLIC_API_SYNC__ (please keep in sync across all other instances)
+ */
+
+export { ParseError, ParseOutput, ProductionKind } from "../../generated";

crates/solidity/outputs/npm/tests/src/index.spec.ts

@@ -1,6 +1,9 @@
 import test from "ava";
 
-import { Language, RuleKind, TokenKind, NodeType, RuleNode, TokenNode, ProductionKind } from "@nomicfoundation/slang";
+import * as slang from "@nomicfoundation/slang";
+import { Language } from "@nomicfoundation/slang";
+import { NodeType, RuleKind, RuleNode, TokenKind, TokenNode } from "@nomicfoundation/slang/syntax/nodes";
+import { ProductionKind } from "@nomicfoundation/slang/syntax/parser";
 
 test("parse some token", (t) => {
   const source = "5_286_981";
@@ -69,3 +72,8 @@ Error: Expected end of input.
 `.trim(),
   );
 });
+
+test("use namespace import of the API", (t) => {
+  t.is(typeof slang.syntax.nodes.RuleKind, "object");
+  t.is(typeof slang.syntax.parser.ProductionKind, "object");
+});

documentation/public/user-guide/npm-package/index.md

@@ -19,7 +19,9 @@ This allows callers to parse entire source files (`ProductionKind.SourceUnit`),
 methods (`ProductionKind.FunctionDefinition`), or any other syntax nodes.
 
 ```typescript
-import { Language, RuleKind, TokenKind, ProductionKind } from "@nomicfoundation/slang";
+import { Language } from "@nomicfoundation/slang";
+import { RuleKind, TokenKind } from "@nomicfoundation/slang/syntax/nodes";
+import { ProductionKind } from "@nomicfoundation/slang/syntax/parser";
 
 const language = new Language("0.8.0");
 const parseOutput = language.parse(ProductionKind.ContractDefinition, "contract Foo {}");

scripts/cargo/_common.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+
+source "$(dirname "${BASH_SOURCE[0]}")/../_common.sh"
+
+# _CARGO_CLI_ENV_VARS_ (keep In Sync)
+export CARGO="${REPO_ROOT}/bin/cargo"
+export RUSTC="${REPO_ROOT}/bin/rustc"
+export RUSTFMT="${REPO_ROOT}/bin/rustfmt"
+export RUSTUP="${REPO_ROOT}/bin/rustup"

scripts/cargo/check.sh

@@ -1,18 +1,12 @@
 #!/bin/bash
 set -euo pipefail
 
-source "$(dirname "${BASH_SOURCE[0]}")/../_common.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/_common.sh"
 
 (
   printf "\n\n🧪 Checking Project 🧪\n\n\n"
   cd "$REPO_ROOT"
 
-  # Keep in sync with the Rust Analyzer environment in "$REPO_ROOT/.vscode/settings.json"
-  export CARGO="${REPO_ROOT}/bin/cargo"
-  export RUSTC="${REPO_ROOT}/bin/rustc"
-  export RUSTFMT="${REPO_ROOT}/bin/rustfmt"
-  export RUSTUP="${REPO_ROOT}/bin/rustup"
-
   command=(
     cargo check
     --offline

scripts/cargo/publish.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 set -euo pipefail
 
-source "$(dirname "${BASH_SOURCE[0]}")/../_common.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/_common.sh"
 
 (
   printf "\n\n🚀 Publishing To Cargo 🚀\n\n\n"

scripts/cargo/test.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 set -euo pipefail
 
-source "$(dirname "${BASH_SOURCE[0]}")/../_common.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/_common.sh"
 
 (
   printf "\n\n🧪 Running Tests 🧪\n\n\n"

scripts/changelog/package.json

@@ -5,7 +5,7 @@
     "@actions/github": "5.1.1",
     "@changesets/changelog-github": "0.4.8",
     "@changesets/cli": "2.26.1",
-    "remark-parse": "10.0.1",
+    "remark-parse": "10.0.2",
     "remark-stringify": "10.0.2",
     "unified": "10.1.2"
   }

tsconfig.json

@@ -1,11 +1,11 @@
 {
   "exclude": [
     /* Packages and Dependencies */
-    ".hermit/",
-    "node_modules/",
+    "**/.hermit/**",
+    "**/node_modules/**",
 
     /* Generated Artifacts */
-    "target/"
+    "**/target/**"
   ],
 
   "compilerOptions": {
@@ -14,7 +14,7 @@
     "lib": ["DOM", "DOM.Iterable"],
 
     /* Modules */
-    "moduleResolution": "node",
+    "moduleResolution": "node16",
 
     /* JavaScript Support */
     "allowJs": true,