yidafu · yidafu · Nov 23, 2025 · Nov 21, 2025 · Nov 21, 2025 · Nov 23, 2025
diff --git a/README.md b/README.md
@@ -28,16 +28,16 @@
       - [Available Async Methods](#available-async-methods)
       - [Threading Model](#threading-model)
   - [API](#api)
-    - [parseSync](#parsesync)
-    - [parseFileSync](#parsefilesync)
-    - [transformSync](#transformsync)
-    - [transformFileSync](#transformfilesync)
-    - [printSync](#printsync)
-    - [minifySync](#minifysync)
+  - [Development](#development)
+    - [Building](#building)
+    - [Testing](#testing)
+    - [Publishing](#publishing)
   - [AST DSL](#ast-dsl)
     - [Build AST segment](#build-ast-segment)
     - [Boolean | T options](#boolean--t-options)
   - [Article](#article)
+  - [Known Issues](#known-issues)
+    - [externalHelpers Configuration](#externalhelpers-configuration)
   - [License](#license)
 
 ## Installation
@@ -55,7 +55,8 @@ implementation("dev.yidafu.swc:swc-binding:0.7.0")
 
 ## Documentation
 
-[SWC Binding - Kotlin Doc](https://yidafu.github.io/swc-binding/docs/)
+- [API Documentation - Kotlin Doc](https://yidafu.github.io/swc-binding/docs/)
+- [Project Wiki - Complete Guide](docs/wiki.md) - Auto-generated from repo wiki, includes architecture, usage guides, and detailed explanations
 
 ## Quick Start
 
@@ -307,6 +308,91 @@ Native method
 fun minifySync(program: String, options: String): String
 ```
 
+## Development
+
+### Building
+
+To build the entire project:
+
+```bash
+./gradlew build
+```
+
+### Testing
+
+Run all tests:
+
+```bash
+./gradlew test
+```
+
+Run tests for a specific module:
+
+```bash
+./gradlew :swc-binding:test
+```
+
+### Publishing
+
+This project uses the NMCP (New Maven Central Publisher) plugin for publishing to Maven Central.
+
+#### Prerequisites
+
+1. **Maven Central Account**: Create an account at [Maven Central Portal](https://central.sonatype.com/)
+2. **Namespace Verification**: Verify your namespace (`dev.yidafu.swc`) in the portal
+3. **GPG Key**: Set up a GPG key for signing artifacts
+
+#### Configuration
+
+Create a `local.properties` file in the project root:
+
+```properties
+# Maven Central Portal credentials
+centralUsername=your-portal-username
+centralPassword=your-portal-password
+
+# GPG signing credentials
+signing.key=your-gpg-private-key
+signing.password=your-gpg-password
+```
+
+Or use environment variables:
+
+```bash
+export CENTRAL_USERNAME=your-portal-username
+export CENTRAL_PASSWORD=your-portal-password
+export SIGNING_KEY=your-gpg-private-key
+export SIGNING_PASSWORD=your-gpg-password
+```
+
+#### Publishing to Maven Central
+
+To publish to Maven Central Portal:
+
+```bash
+./gradlew :swc-binding:publishSonatypePublicationToCentralPortal
+```
+
+Or publish all publications:
+
+```bash
+./gradlew :swc-binding:publishAllPublicationsToCentralPortal
+```
+
+#### Publishing to Local Repository
+
+For testing, you can publish to your local Maven repository:
+
+```bash
+./gradlew :swc-binding:publishToMavenLocal
+```
+
+#### Important Notes
+
+- **Version Requirements**: Central Portal does NOT support SNAPSHOT versions. Only release versions are allowed
+- **Publication Type**: Currently configured as `USER_MANAGED`, which requires manual approval in the Central Portal UI
+- **Namespace**: Make sure your namespace (`dev.yidafu.swc`) is verified in the Central Portal before publishing
+
 ## AST DSL
 
 ```js
@@ -413,6 +499,25 @@ options {
 
 [How to implement SWC JVM binding -- English translation](docs/how-to-implement-swc-jvm-binding.md) -- [中文原文](docs/how-to-implement-swc-jvm-binding.zh-CN.md)
 
+## Known Issues
+
+### externalHelpers Configuration
+
+When using `externalHelpers = false`, SWC should inline helper functions directly into the output code instead of importing them from `@swc/helpers`. However, the current Rust implementation of SWC used in this project does not respect this configuration correctly.
+
+**Current Behavior:**
+- With `externalHelpers = false`: SWC still generates imports from `@swc/helpers`
+- With `externalHelpers = true`: SWC generates imports from `@swc/helpers`
+
+**Expected Behavior:**
+- With `externalHelpers = false`: SWC should inline helper functions (no imports from `@swc/helpers`)
+- With `externalHelpers = true`: SWC should generate imports from `@swc/helpers`
+
+This is a known difference between the Rust and Node.js versions of SWC. The configuration is correctly parsed and passed to SWC, but the Rust implementation does not inline helpers even when `external_helpers` is set to `false`.
+
+**Workaround:**
+For now, tests have been updated to match the actual Rust behavior rather than the expected behavior. This issue may be addressed in a future update when the Rust implementation is fixed or when a workaround is identified.
+
 ## License
 
 MIT
diff --git a/build-plugin/libs.versions.toml b/build-plugin/libs.versions.toml
@@ -2,8 +2,9 @@
 kotlin = "2.2.10"
 ksp = "1.9.21-1.0.15"
 ktlint = "11.6.1"
-dokka = "1.8.20"
+dokka = "2.1.0"
 publisher = "1.8.10-dev-43"
+nmcp = "0.0.8"
 kotlinxSerialization = "1.7.3"
 kotest = "5.9.1"
 coroutines = "1.7.3"
@@ -56,5 +57,6 @@ publisher = { id = "org.jetbrains.kotlin.libs.publisher", version.ref= "publishe
 dokka = { id = "org.jetbrains.dokka", version.ref = "dokka"}
 ktlint = {id = "org.jlleitschuh.gradle.ktlint", version.ref = "ktlint"}
 kotlin_serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+nmcp = { id = "com.gradleup.nmcp", version.ref = "nmcp" }
 signing = { id = "org.gradle.signing" }
 mavenPublish = { id = "org.gradle.maven-publish"}
diff --git a/build-plugin/src/main/kotlin/dev/yidafu/plugin/LibraryPlugin.kt b/build-plugin/src/main/kotlin/dev/yidafu/plugin/LibraryPlugin.kt
@@ -19,6 +19,7 @@ import org.gradle.plugin.use.PluginDependency
 import org.gradle.plugins.signing.SigningExtension
 import org.jetbrains.dokka.gradle.DokkaTask
 import java.net.URI
+import java.util.Properties
 
 fun Project.getLibPlugin(name: String): PluginDependency {
     val catalogs = extensions.getByType<VersionCatalogsExtension>()
@@ -46,7 +47,8 @@ class LibraryPlugin : Plugin<Project> {
                 "dokka",
                 "signing",
                 "mavenPublish",
-                "ktlint"
+                "ktlint",
+                "nmcp"
             )
                 .map { project.getLibPlugin(it) }
                 .forEach {
@@ -56,98 +58,5 @@ class LibraryPlugin : Plugin<Project> {
         project.configure<org.jlleitschuh.gradle.ktlint.KtlintExtension> {
             disabledRules.set(setOf("final-newline", "no-wildcard-imports", "filename"))
         }
-        project.extensions.create("publishMan", PublishManExtension::class)
-
-        val dokkaJavadoc = project.tasks.findByName("dokkaJavadoc") as DokkaTask
-        val dokkaJavadocJar = project.tasks.register<Jar>("dokkaJavadocJar") {
-            dependsOn(dokkaJavadoc.path)
-            from(dokkaJavadoc.outputDirectory)
-            archiveClassifier.set("javadoc")
-        }
-        val kotlinSourcesJar = project.tasks.findByName("kotlinSourcesJar") as Jar
-
-        val publishing = project.extensions.getByType<PublishingExtension>()
-        publishing.repositories {
-            maven {
-                url = URI("https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/")
-                // 这里就是之前在issues.sonatype.org注册的账号
-                credentials {
-                    username = if (project.hasProperty("sonatypeUsername")) {
-                        project.property("sonatypeUsername") as String
-                    } else {
-                        "placeholder"
-                    }
-                    password = if (project.hasProperty("sonatypePassword")) {
-                        project.property("sonatypePassword") as String
-                    } else {
-                        "placeholder"
-                    }
-                }
-            }
-        }
-
-        publishing.publications {
-            create<MavenPublication>(PUBLICATION_NAME) {
-                pom {
-//                    artifactId = "jupyter-js"
-                    from(project.components["java"])
-                    artifact(kotlinSourcesJar)
-                    artifact(dokkaJavadocJar)
-
-                    versionMapping {
-                        usage("java-api") {
-                            fromResolutionOf("runtimeClasspath")
-                        }
-                        usage("java-runtime") {
-                            fromResolutionResult()
-                        }
-                    }
-
-                    url.set("https://github.com/yidafu/kotlin-jupyter-js/")
-//                properties.set(mapOf(
-//                    "myProp" to "value",
-//                    "prop.with.dots" to "anotherValue"
-//                ))
-
-                    licenses {
-                        license {
-                            name.set("The MIT License")
-                            url.set("https://opensource.org/licenses/MIT")
-                        }
-                    }
-                    developers {
-                        developer {
-                            id.set("dovyih")
-                            name.set("Dov Yih")
-                            email.set("me@yidafu.dev")
-                        }
-                    }
-                    scm {
-                        connection.set("scm:git:git://github.com:yidafu/kotlin-jupyter-js.git")
-                        developerConnection.set("scm:git:ssh://github.com:yidafu/kotlin-jupyter-js.git")
-                        url.set("https://github.com:yidafu/kotlin-jupyter-js/")
-                    }
-                }
-//                pom.withXml {
-//                    val configurationNames = arrayOf("implementation", "api")
-//                    val deps = configurationNames.map { configurationName ->
-//                        project.configurations[configurationName].allDependencies.toList()
-//                    }.flatten()
-//                    if (deps.isNotEmpty()) {
-//                        val dependenciesNode = asNode().appendNode("dependencies")
-//                        deps.forEach {
-//                            if (it.group != null) {
-//                                val dependencyNode = dependenciesNode.appendNode("dependency")
-//                                dependencyNode.appendNode("groupId", it.group)
-//                                dependencyNode.appendNode("artifactId", it.name)
-//                                dependencyNode.appendNode("version", it.version)
-//                            }
-//                        }
-//                    }
-//                }
-            }
-        }
-
-        // Signing configuration can be added later if needed
     }
 }
diff --git a/build-plugin/src/main/kotlin/dev/yidafu/plugin/PublishManExtension.kt b/build-plugin/src/main/kotlin/dev/yidafu/plugin/PublishManExtension.kt
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -1,6 +1,16 @@
+import java.util.Properties
+
 plugins {
     alias(libs.plugins.jvm) apply false
     alias(libs.plugins.kotlin.serialization) apply false
+    alias(libs.plugins.nmcp) apply false
+}
+
+// Load local.properties
+val localPropertiesFile = rootProject.file("local.properties")
+val localProperties = Properties()
+if (localPropertiesFile.exists()) {
+    localPropertiesFile.inputStream().use { localProperties.load(it) }
 }
 
 subprojects {

diff --git a/swc-binding/README.md b/swc-binding/README.md
@@ -771,6 +771,26 @@ All AST nodes require a `span` field. Use `emptySpan()` to create a default span
 span = emptySpan() // Creates a span with start=0, end=0, ctxt=0
 ```
 
+#### Automatic `ctxt` Field Fixing
+
+When parsing AST JSON from Rust/SWC, the `ctxt` field in `span` objects may be missing because Rust's serde skips serializing default values (ctxt = 0). This can cause deserialization failures in polymorphic scenarios where `coerceInputValues` doesn't work properly.
+
+**The library automatically fixes this issue** by adding missing `ctxt: 0` fields to all span objects before deserialization. This happens transparently when you use `parseAstTree()` or `SwcJson.parseAstTree()`:
+
+```kotlin
+// JSON from Rust may be missing ctxt field:
+val jsonFromRust = """{"type":"Module","span":{"start":0,"end":0},"body":[]}"""
+
+// parseAstTree automatically fixes it:
+val program = parseAstTree(jsonFromRust) // ✅ Works! ctxt is automatically added
+
+// After deserialization, ctxt field will be present when serializing again:
+val serialized = astJson.encodeToString(program)
+// serialized contains: {"type":"Module","span":{"start":0,"end":0,"ctxt":0},...}
+```
+
+This automatic fixing ensures compatibility with JSON generated by Rust/SWC that omits default-valued fields, especially in polymorphic serialization scenarios (e.g., `MemberExpression.property` which uses `Node?` type).
+
 #### Boolean Fields
 
 When manually constructing AST nodes, it's **recommended** to explicitly set boolean fields for clarity and to ensure compatibility. While many boolean fields have `@EncodeDefault` annotations and may work without explicit values, setting them explicitly makes your code more maintainable and avoids potential serialization issues.