tree-sitter-arkts 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,122 @@
+# tree-sitter-arkts
+
+ArkTS 语言的 tree-sitter 解析器，用于语法高亮、代码分析、VSCode 插件等场景。
+
+## 特性
+
+- ✅ 完整的 ArkTS 语法支持
+- ✅ 支持 ArkUI 组件语法（component_statement, style_statement）
+- ✅ 支持 struct 声明
+- ✅ 支持装饰器
+- ✅ TypeScript 类型定义
+- ✅ 跨平台支持（Windows, macOS, Linux）
+
+## 安装
+
+```bash
+npm install tree-sitter-arkts
+```
+
+## 使用方法
+
+### TypeScript/JavaScript
+
+```typescript
+import { Parser, createParser, parse } from 'tree-sitter-arkts';
+
+// 方法 1: 使用便捷函数
+const tree = parse('@Entry()\nstruct MyComponent {\n  build() {}\n}');
+
+// 方法 2: 创建解析器实例
+const parser = createParser();
+const tree2 = parser.parse(sourceCode);
+
+// 方法 3: 手动创建
+import { Parser, ArkTS } from 'tree-sitter-arkts';
+const parser = new Parser();
+parser.setLanguage(ArkTS);
+const tree3 = parser.parse(sourceCode);
+```
+
+## 开发
+
+### 构建
+
+```bash
+# 生成解析器代码并构建原生模块
+npm run build
+
+# 仅生成解析器代码
+npm run generate
+
+# 仅编译 TypeScript
+npm run build:ts
+```
+
+### 测试
+
+```bash
+# 完整功能测试（需要 tree-sitter 原生模块）
+npm test
+
+# 仅验证包结构（不需要 tree-sitter 原生模块）
+npm run test:structure
+```
+
+**注意**: 
+- 完整功能测试需要 tree-sitter 原生模块
+- **Node.js 版本兼容性**: 
+  - ✅ **Node.js v24**: 已支持（需要 C++20 编译器，如 GCC 12+）
+  - ✅ **Node.js v18/v20/v22**: 完全支持
+  - 安装时会自动修复 tree-sitter 的构建配置以支持 Node.js v24
+
+## Windows 构建说明
+
+在 Windows 上构建原生模块需要：
+
+1. **安装构建工具**：
+   - 安装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) 或 Visual Studio（包含 C++ 工作负载）
+   - 或者安装 [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools): `npm install -g windows-build-tools`
+
+2. **安装 Python**：
+   - 确保已安装 Python 2.7 或 3.x
+   - node-gyp 需要 Python 来构建原生模块
+
+3. **安装依赖并构建**：
+   ```bash
+   npm install
+   ```
+   这会自动运行 `node-gyp rebuild` 来构建原生模块。
+
+## VSCode 插件使用示例
+
+```typescript
+import { createParser } from 'tree-sitter-arkts';
+import * as vscode from 'vscode';
+
+export function activate(context: vscode.ExtensionContext) {
+  const parser = createParser();
+  
+  const disposable = vscode.workspace.onDidChangeTextDocument(event => {
+    const tree = parser.parse(event.document.getText());
+    // 使用语法树进行代码分析、高亮等
+  });
+  
+  context.subscriptions.push(disposable);
+}
+```
+
+## 项目结构
+
+- `grammar.js` - ArkTS 语法定义文件
+- `binding.gyp` - Node.js 原生模块构建配置
+- `index.ts` - TypeScript 入口文件
+- `bindings/node/binding.cc` - Node.js 绑定代码
+- `src/` - 由 tree-sitter generate 生成的 C 代码
+
+## 依赖
+
+- `tree-sitter` - Tree-sitter 核心库
+- `nan` - Node.js 原生模块开发工具
+- `tree-sitter-typescript` - TypeScript 语法基础（grammar.js 中引用）
+

package/binding.gyp

@@ -0,0 +1,50 @@
+{
+  "targets": [
+    {
+      "target_name": "tree_sitter_arkts_binding",
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "src"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "defines": [
+        "NAPI_DISABLE_CPP_EXCEPTIONS",
+        "NAPI_VERSION=<!(node -p \"process.versions.napi\")"
+      ],
+      "sources": [
+        "src/parser.c",
+        "src/scanner.c",
+        "bindings/node/binding.cc"
+      ],
+      "cflags_c": [
+        "-std=c99"
+      ],
+      "cflags_cc": [
+        "-std=c++20"
+      ],
+      "xcode_settings": {
+        "OTHER_CPLUSPLUSFLAGS": ["-std=c++20", "-stdlib=libc++"],
+        "OTHER_CFLAGS": ["-std=c99"]
+      },
+      "conditions": [
+        ["OS=='mac'", {
+          "xcode_settings": {
+            "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+            "CLANG_CXX_LIBRARY": "libc++",
+            "MACOSX_DEPLOYMENT_TARGET": "10.7"
+          }
+        }],
+        ["OS=='win'", {
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "ExceptionHandling": 1
+            }
+          }
+        }]
+      ]
+    }
+  ]
+}
+

package/bindings/node/binding.cc

@@ -0,0 +1,57 @@
+#include "tree_sitter/parser.h"
+#include <napi.h>
+
+using namespace Napi;
+
+extern "C" TSLanguage * tree_sitter_arkts();
+
+namespace {
+
+/*
+  tstag() {
+    b2sum -l64 <(printf tree-sitter) <(printf "$1") | \
+    awk '{printf "0x" toupper($1) (NR == 1 ? ", " : "\n")}'
+  }
+  tstag language # => 0x8AF2E5212AD58ABF, 0xD5006CAD83ABBA16
+*/
+const napi_type_tag LANGUAGE_TYPE_TAG = {
+  0x8AF2E5212AD58ABF, 0xD5006CAD83ABBA16
+};
+
+Object Init(Env env, Object exports) {
+  const TSLanguage *language = tree_sitter_arkts();
+  
+  // 创建 External（不使用 finalizer）
+  napi_value external_value;
+  napi_status status = napi_create_external(
+    env,
+    const_cast<TSLanguage *>(language),
+    nullptr,  // finalizer
+    nullptr,  // finalizer_hint
+    &external_value
+  );
+  
+  if (status != napi_ok) {
+    Error::New(env, "Failed to create language external").ThrowAsJavaScriptException();
+    return exports;
+  }
+  
+  // 设置类型标签
+  status = napi_type_tag_object(env, external_value, &LANGUAGE_TYPE_TAG);
+  if (status != napi_ok) {
+    Error::New(env, "Failed to set language type tag").ThrowAsJavaScriptException();
+    return exports;
+  }
+  
+  // 创建语言对象，包含 language 属性和 name 属性
+  Object language_obj = Object::New(env);
+  language_obj.Set("language", external_value);
+  language_obj.Set("name", String::New(env, "arkts"));
+  
+  return language_obj;
+}
+
+NODE_API_MODULE(tree_sitter_arkts_binding, Init)
+
+}  // namespace
+

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import Parser = require('tree-sitter');
+import { Tree } from 'tree-sitter';
+/**
+ * ArkTS 语言对象
+ */
+export declare const ArkTS: any;
+/**
+ * 创建并配置一个解析器实例
+ * @returns 配置好的 Parser 实例
+ */
+export declare function createParser(): Parser;
+/**
+ * 解析 ArkTS 源代码
+ * @param sourceCode 要解析的源代码
+ * @param oldTree 可选的旧语法树，用于增量解析
+ * @returns 解析后的语法树
+ */
+export declare function parse(sourceCode: string, oldTree?: Tree): Tree;
+export { Tree };
+export { Parser };

package/dist/index.js

@@ -0,0 +1,85 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Parser = exports.ArkTS = void 0;
+exports.createParser = createParser;
+exports.parse = parse;
+const Parser = require("tree-sitter");
+exports.Parser = Parser;
+const path = __importStar(require("path"));
+// 动态加载原生绑定模块（优先使用预编译版本）
+let ParserBinding;
+try {
+    // 尝试使用 node-gyp-build 加载预编译版本
+    ParserBinding = require('node-gyp-build')(path.join(__dirname, '..'));
+}
+catch (err) {
+    // 回退到本地构建版本
+    const rootDir = path.resolve(__dirname, '..');
+    try {
+        ParserBinding = require(path.join(rootDir, 'build/Release/tree_sitter_arkts_binding.node'));
+    }
+    catch (err2) {
+        try {
+            ParserBinding = require(path.join(rootDir, 'build/Debug/tree_sitter_arkts_binding.node'));
+        }
+        catch (err3) {
+            throw new Error('tree-sitter-arkts 原生模块未找到。请运行 npm install 或 npm run build 来构建模块。');
+        }
+    }
+}
+/**
+ * ArkTS 语言对象
+ */
+exports.ArkTS = ParserBinding;
+/**
+ * 创建并配置一个解析器实例
+ * @returns 配置好的 Parser 实例
+ */
+function createParser() {
+    const parser = new Parser();
+    parser.setLanguage(exports.ArkTS);
+    return parser;
+}
+/**
+ * 解析 ArkTS 源代码
+ * @param sourceCode 要解析的源代码
+ * @param oldTree 可选的旧语法树，用于增量解析
+ * @returns 解析后的语法树
+ */
+function parse(sourceCode, oldTree) {
+    const parser = createParser();
+    return parser.parse(sourceCode, oldTree);
+}

package/grammar.js

@@ -0,0 +1,123 @@
+/* eslint-disable valid-jsdoc */
+const tsGrammar = require('tree-sitter-typescript/typescript/grammar.js');
+
+// extend
+module.exports = grammar(tsGrammar, {
+  name: 'arkts',
+
+  precedences: ($, previous) => previous.concat([
+    [$.call_expression, $.component_statement],
+    [$.style_expression, $.statement],
+    [$.style_expression, $.statement_block],
+  ]),
+
+  rules: {
+    // method_signature add decorator
+    method_signature: ($) => seq(
+      repeat(field('decorator', $.decorator)),
+      optional($.accessibility_modifier),
+      optional('static'),
+      optional($.override_modifier),
+      optional('readonly'),
+      optional('async'),
+      optional(choice('get', 'set', '*')),
+      field('name', $._property_name),
+      optional('?'),
+      $._call_signature,
+    ),
+
+    // struct declaration
+    struct_declaration: ($) => prec('literal', seq(
+      repeat(field('decorator', $.decorator)),
+      'struct',
+      field('name', optional($._type_identifier)),
+      field('body', $.class_body),
+    )),
+
+    declaration: ($, previous) => choice(
+      previous,
+      $.struct_declaration,
+    ),
+
+    // ambient add decorator
+    ambient_declaration: ($) => seq(
+      repeat(field('decorator', $.decorator)),
+      'declare',
+      choice(
+        $.declaration,
+        seq('global', $.statement_block),
+        seq('module', '.', alias($.identifier, $.property_identifier), ':', $._type, $._semicolon),
+      ),
+    ),
+
+    // function add decorator
+    function_declaration: ($) => prec.right('declaration', seq(
+      repeat(field('decorator', $.decorator)),
+      optional('async'),
+      'function',
+      field('name', $.identifier),
+      $._call_signature,
+      field('body', $.statement_block),
+      optional($._automatic_semicolon),
+    )),
+
+    /**
+     * ArkUI component statement
+     *
+     * @example:
+     * XXXX('test') {
+     *   Row()
+     * }
+     * .width(10)
+     */
+    component_statement: ($) => prec.right(seq(
+      field('function', $.expression),
+      field('arguments', $.arguments),
+      optional($.statement_block),
+      optional($.style_statement),
+    )),
+
+    /**
+     * ArkUI style statement
+     *
+     * @example:
+     * .width(10)
+     * .height(10)
+     */
+    style_statement: ($) => prec.right(repeat1(seq(
+      '.',
+      field('function', $.identifier),
+      field('arguments', $.arguments),
+    ))),
+
+    /**
+     * match stateStyles
+     *
+     * @example:
+     * Button()
+     *   .normal: {
+     *     .backgroundColor(Color.Yellow)
+     *   }
+     *   focused: {
+     *     .backgroundColor(Color.Pink)
+     *   }
+     */
+    style_expression: ($) => prec.left(1, seq(
+      '{',
+      $.style_statement,
+      '}',
+    )),
+
+    primary_expression: ($, previous) => choice(
+      previous,
+      $.style_expression,
+    ),
+
+    statement: ($, previous) => choice(
+      previous,
+      $.component_statement,
+      $.style_statement,
+    ),
+  },
+});
+

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "tree-sitter-arkts",
+  "version": "1.0.0",
+  "description": "ArkTS grammar for tree-sitter",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "tree-sitter",
+    "arkts",
+    "parser",
+    "harmonyos",
+    "arkui"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "prebuilds",
+    "src",
+    "bindings/node/binding.cc",
+    "binding.gyp",
+    "grammar.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "node-addon-api": "^8.5.0",
+    "node-gyp-build": "^4.8.0",
+    "tree-sitter": "^0.25.0",
+    "tree-sitter-javascript": "^0.20.4",
+    "tree-sitter-typescript": "^0.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "node-gyp-build": "^4.8.0",
+    "prebuildify": "^6.0.1",
+    "tree-sitter-cli": "^0.20.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "generate": "npx tree-sitter generate",
+    "build": "npx tree-sitter generate && node-gyp rebuild && npm run build:ts",
+    "build:ts": "tsc",
+    "prebuild": "npm run generate && prebuildify --napi",
+    "prebuild:win32": "npm run generate && prebuildify --napi --platform win32",
+    "prebuild:linux": "npm run generate && prebuildify --napi --platform linux",
+    "prebuild:darwin": "npm run generate && prebuildify --napi --platform darwin",
+    "install": "node-gyp-build || npm run install:fallback",
+    "install:fallback": "npm run fix-tree-sitter && node-gyp rebuild",
+    "fix-tree-sitter": "node fix-tree-sitter.js",
+    "postinstall": "npm run fix-tree-sitter && (npm rebuild tree-sitter || true)",
+    "test": "node test.js",
+    "test:structure": "node test-structure.js",
+    "prepublishOnly": "npm run generate && npm run build:ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "gypfile": true,
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}