@ohos-rs/oxk 0.4.1 → 0.6.0

package/README.md

@@ -1,31 +1,133 @@
 # `@ohos-rs/oxk`
 
-> This is forked from [package-template-pnpm](https://github.com/napi-rs/package-template-pnpm).
+ArkTS/ArkUI parser, formatter, and lint tooling based on OXC and oxlint.
 
-## Usage
-
-Install with npm
+## Install
 
 ```bash
 npm install @ohos-rs/oxk
 ```
 
-### Run with cli
+For CLI usage, install it in your project and run it through your package
+manager, or install it globally:
 
 ```bash
-oxk format xxx.ets
+npm install -g @ohos-rs/oxk
+oxk --help
 ```
 
-### Run with code
+The npm package requires Node.js `^20.19.0 || >=22.18.0`.
+
+## Format
+
+```bash
+oxk format src/index.ets
+oxk format "src/**/*.{ts,ets}"
+```
+
+Formatter config is loaded from `.oxfmtrc.json` or `.oxfmtrc.jsonc`.
+
+## Lint
+
+```bash
+oxk lint src --threads 1
+oxk lint src/index.ets --format json
+oxk lint --config .oxlintrc.jsonc "src/**/*.ets"
+```
+
+`oxk lint` embeds `oxlint::CliRunner`; it does not shell out to an external
+`oxlint` binary. The npm CLI includes the oxlint JavaScript runtime for:
+
+- `.oxlintrc.json` and `.oxlintrc.jsonc`
+- `oxlint.config.ts`
+- oxlint built-in plugin configuration, such as `plugins: ["react"]`
+- JavaScript plugins configured with `jsPlugins`
+- plugin settings and globals
+
+The cargo CLI keeps a pure Rust runner. Use JSON or JSONC config files there;
+the JavaScript runtime and `oxlint.config.ts` are npm-only.
 
-Using napi-native module format.
+## ArkTS Rules
+
+ArkTS migration rules are built in as the virtual `arkts` plugin. See
+[Built-in Lint](../../crates/lint/README.md) for the rule list, configuration
+examples, `arkts/system-api-version`, and the SDK sync workflow.
+
+Example:
+
+```ts
+// index.ets
+const key = Symbol('id')
+let marker: symbol
+```
+
+```bash
+oxk lint index.ets --threads 1 --format json
+```
+
+## JavaScript API
+
+Use the formatter wrapper:
 
 ```js
-const oxk = require('@ohos-rs/oxk')
+const { format } = require('@ohos-rs/oxk/format')
 ```
 
-Using wrapper module format.
+Use the lint wrapper with oxlint-compatible CLI arguments:
 
 ```js
-const oxk = require('@ohos-rs/oxk/format')
+const { lint } = require('@ohos-rs/oxk/lint')
+
+const ok = await lint(['src/index.ets', '--threads', '1'])
+process.exitCode = ok ? 0 : 1
+```
+
+The native module is also available from the package root:
+
+```js
+const oxk = require('@ohos-rs/oxk')
+```
+
+For linting from JavaScript, prefer `@ohos-rs/oxk/lint`; it wires the oxlint JS
+runtime callbacks for plugins and JavaScript config files.
+
+## WASI
+
+Build the WASI artifact locally:
+
+```bash
+pnpm build --target wasm32-wasip1-threads
+pnpm run test:wasi
+```
+
+`test:wasi` forces `NAPI_RS_FORCE_WASI=1` and verifies the generated WASI
+binding can load and execute `parse` and `format`. Linting is intentionally not
+available from the WASI build because the oxlint runner and JavaScript plugin
+runtime are native-only; use the native npm package or cargo CLI for linting.
+
+## Local Development
+
+Build the local NAPI binary before running npm CLI tests:
+
+```bash
+pnpm --filter @ohos-rs/oxk run build:debug
+pnpm --filter @ohos-rs/oxk test
+pnpm --filter @ohos-rs/oxk run build --target wasm32-wasip1-threads
+pnpm --filter @ohos-rs/oxk run test:wasi
+```
+
+Update the bundled oxlint JavaScript runtime after changing the upstream source
+or dependency versions:
+
+```bash
+pnpm --filter @ohos-rs/oxk run build:oxlint-runtime
+```
+
+Run the Rust checks:
+
+```bash
+cargo check -p lint -p oxk
+cargo check -p oxk-napi
+cargo test -p lint -p oxk
+git diff --check
 ```

package/bin/oxk.js

@@ -2,6 +2,8 @@
 
 const VERSION = require('../package.json').version
 const { formatFiles } = require('./format.js')
+const { formatLsp } = require('../index.js')
+const { lint } = require('../lint.js')
 
 function parseBoolean(value, flagName) {
   if (value === 'true') {
@@ -43,12 +45,18 @@ Usage:
 
 Commands:
   format    Format files
+  lint      Lint files
 
 Global Options:
   --help, -h     Show help
   --version, -v  Show version
 
+Lint Options:
+  Supports oxlint-compatible options, configuration files, built-in plugins, and JS plugins.
+  Run "oxk lint --help" for the full lint option list.
+
 Format Options:
+  --lsp
   --config PATH
   --thread, -t THREAD
   --exclude PATTERN
@@ -72,6 +80,9 @@ Format Options:
 Examples:
   oxk format src/**/*.ets
   oxk format --exclude dist/** --config .oxfmtrc.json "src/**/*.{ts,ets}"
+  oxk lint src
+  oxk lint --config .oxlintrc.json --react-plugin "src/**/*.{ts,tsx,ets}"
+  oxk lint --config .oxlintrc.json "src/**/*.ets"
 `)
 }
 
@@ -85,6 +96,7 @@ function parseFormatArgs(args) {
     excludes: [],
     threadCount: 1,
     configPath: undefined,
+    lsp: false,
     cliOptions: {},
   }
 
@@ -101,6 +113,10 @@ function parseFormatArgs(args) {
     }
 
     switch (token.split('=')[0]) {
+      case '--lsp': {
+        formatArgs.lsp = true
+        break
+      }
       case '--config': {
         const { value, nextIndex } = parseOptionValue(args, index, token)
         formatArgs.configPath = value
@@ -268,19 +284,35 @@ async function main() {
     process.exit(0)
   }
 
-  if (command !== 'format') {
+  if (command !== 'format' && command !== 'lint') {
     console.error(`Unknown command: ${command}`)
     console.error("Run 'oxk --help' for usage information")
     process.exit(1)
   }
 
   try {
+    if (command === 'lint') {
+      const success = await lint(args.slice(1))
+      if (!success) {
+        process.exit(1)
+      }
+      return
+    }
+
     const { help, formatArgs } = parseFormatArgs(args.slice(1))
     if (help) {
       showHelp()
       process.exit(0)
     }
 
+    if (formatArgs.lsp) {
+      if (typeof formatLsp !== 'function') {
+        throw new Error('oxk format --lsp requires the native oxk binding')
+      }
+      await formatLsp()
+      return
+    }
+
     await formatFiles(formatArgs)
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))