@qiun/eslint-plugin-ucharts 1.0.0

package/README.md

@@ -0,0 +1,223 @@
+# @qiun/eslint-plugin-ucharts
+
+[!\[npm version\](https://img.shields.io/npm/v/@qiun/eslint-plugin-ucharts.svg null)](https://www.npmjs.com/package/@qiun/eslint-plugin-ucharts)
+[!\[license\](https://img.shields.io/npm/l/@qiun/eslint-plugin-ucharts.svg null)](https://github.com/qiun/ucharts/blob/main/LICENSE)
+
+> ESLint plugin enforcing **Safe TS Subset** rules for uCharts cross-platform compatibility (Swift / Kotlin / ArkTS)
+
+## Background
+
+uCharts v4 的 `core/` 目录代码会被自动转译为 **Swift(iOS)**、**Kotlin(Android)**、**ArkTS(HarmonyOS)** 原生代码。为了确保转译成功，`core/` 中的 TypeScript 代码必须遵守 **Safe TS Subset** 规范——只使用三种目标语言都支持的语法子集。
+
+本插件提供 **11 条 ESLint 规则**，在编码阶段自动检测违反 Safe TS Subset 的语法，避免转译时出错。
+
+## Installation
+
+```bash
+npm install -D @qiun/eslint-plugin-ucharts
+```
+
+## Usage
+
+### Basic: Use recommended config
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  extends: ['plugin:@qiun/ucharts/recommended']
+};
+```
+
+### Strict mode (all rules as error)
+
+```javascript
+module.exports = {
+  extends: ['plugin:@qiun/ucharts/strict']
+};
+```
+
+### Manual configuration
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  plugins: ['@qiun/eslint-plugin-ucharts'],
+  rules: {
+    '@qiun/no-destructuring': 'error',
+    '@qiun/no-object-spread': 'error',
+    // ... see Rules below
+  }
+};
+```
+
+## Rules
+
+| Rule                          | Description                           | Default | Why                     |
+| ----------------------------- | ------------------------------------- | ------- | ----------------------- |
+| `no-destructuring`            | 禁止解构赋值/解构参数                           | `error` | ArkTS 完全禁止解构            |
+| `no-object-spread`            | 禁止对象展开 `{...obj}`                     | `error` | ArkTS 不支持对象展开           |
+| `no-dynamic-property-access`  | 禁止动态属性访问 `obj[key]`                   | `error` | ArkTS 不支持变量键访问          |
+| `no-index-signature`          | 禁止 Index Signature `[key: string]: T` | `error` | ArkTS 不支持索引签名           |
+| `no-for-in`                   | 禁止 `for...in` 循环                      | `error` | UTS/ArkTS 不支持           |
+| `no-with-statement`           | 禁止 `with` 语句                          | `error` | 三平台均不支持                 |
+| `no-nested-function`          | 禁止嵌套函数声明                              | `error` | ArkTS 禁止函数内声明函数         |
+| `require-null-over-undefined` | 要求用 `null` 替代 `undefined`             | `error` | UTS/ArkTS 不支持 undefined |
+| `no-web-api-direct`           | 禁止直接调用 Web API                        | `error` | 需使用 platform 抽象接口       |
+| `no-weakmap-proxy`            | 禁止 WeakMap / Proxy                    | `warn`  | 各平台行为不一致                |
+
+### Rule Details
+
+#### `@qiun/no-destructuring`
+
+Detects and reports all forms of destructuring:
+
+```typescript
+const { a, b } = obj;        // Object destructuring ❌
+const [x, y] = arr;         // Array destructuring ❌
+function foo({ name }) {}    // Parameter destructuring ❌
+```
+
+**Fix:** Use explicit property access:
+
+```typescript
+const a = obj.a;
+const b = obj.b;
+const x = arr[0];
+function foo(param) { const name = param.name; }
+```
+
+#### `@qiun/no-object-spread`
+
+```typescript
+const merged = { ...obj1, ...obj2 };   // ❌
+```
+
+**Fix:** Use a merge utility function:
+
+```typescript
+const merged = merge(obj1, obj2);
+```
+
+#### `@qiun/no-dynamic-property-access`
+
+```typescript
+const key = 'name';
+obj[key] = value;       // ❌ dynamic key
+```
+
+**Fix:** Use Map for dynamic keys:
+
+```typescript
+const map = new Map<string, any>();
+map.set(key, value);
+```
+
+#### `@qiun/no-index-signature`
+
+```typescript
+interface Dict {
+  [key: string]: any;    // ❌ Index Signature
+}
+```
+
+**Fix:** Use explicit fields or Map:
+
+```typescript
+interface Dict {
+  name: string;
+  value: number;
+}
+```
+
+#### `@qiun/no-nested-function`
+
+```typescript
+function outer() {
+  function inner() {}     // ❌ nested function declaration
+}
+```
+
+**Fix:** Extract to module level or use arrow functions assigned to variables.
+
+#### `@qiun/require-null-over-undefined`
+
+```typescript
+let x = undefined;        // ❌
+if (x === undefined) {}   // ❌
+return undefined;          // ❌
+```
+
+**Fix:** Use `null` consistently:
+
+```typescript
+let x = null;
+if (x == null) {}
+return null;
+```
+
+#### `@qiun/no-web-api-direct`
+
+Forbids direct calls to platform-specific APIs that must go through abstraction layer:
+
+```typescript
+console.log('msg');              // ❌ use Logger from core/platform/logger.ts
+requestAnimationFrame(cb);        // ❌ use getAnimationScheduler()
+performance.now();               // ❌ use getAnimationScheduler().now()
+setTimeout(fn, 100);              // ❌ use getAnimationScheduler().setTimeout()
+```
+
+**Fix:** Import from platform abstraction modules in `core/platform/`.
+
+#### `@qiun/no-weakmap-proxy`
+
+```typescript
+const wm = new WeakMap();        // ⚠️ warn: behavior differs across platforms
+const p = new Proxy(target, {}); // ⚠️ warn: not supported in ArkTS
+```
+
+**Fix:** Use `Map` instead of `WeakMap`; use explicit adapter class instead of `Proxy`.
+
+## Config Presets
+
+### `recommended`
+
+Balanced strictness suitable for most projects. All rules at `error` except:
+
+- `no-web-api-direct`: allows configurable forbidden API list
+- `no-weakmap-proxy`: `warn` (not error)
+
+### `strict`
+
+All rules set to `error`. Recommended for code that **must** pass cross-platform transpilation.
+
+## Integration with uCharts Project
+
+In the uCharts v4 monorepo, this plugin is configured in two ESLint configs:
+
+1. **`.eslintrc.js`** — Full project lint (core/, adapters/) with per-file overrides for exempt files like `core/util/merge.ts`
+2. **`.eslintrc.subset.js`** — Strict subset validation for `core/` only
+
+Example override pattern (for files that legitimately need exceptions):
+
+```javascript
+overrides: [
+  {
+    files: ['core/util/merge.ts'],
+    rules: {
+      '@qiun/no-dynamic-property-access': 'off',
+      '@qiun/no-index-signature': 'off'
+    }
+  },
+  {
+    files: ['core/platform/**/*.ts'],
+    rules: {
+      '@qiun/no-web-api-direct': 'off',
+      '@qiun/require-null-over-undefined': 'off'
+    }
+  }
+]
+```
+
+## License
+
+[Apache-2.0](LICENSE)

package/index.js

@@ -0,0 +1,65 @@
+const noObjectSpread = require('./lib/rules/no-object-spread');
+const noDestructuring = require('./lib/rules/no-destructuring');
+const noDynamicPropertyAccess = require('./lib/rules/no-dynamic-property-access');
+const noIndexSignature = require('./lib/rules/no-index-signature');
+const noForIn = require('./lib/rules/no-for-in');
+const noWithStatement = require('./lib/rules/no-with-statement');
+const noNestedFunction = require('./lib/rules/no-nested-function');
+const requireNullOverUndefined = require('./lib/rules/require-null-over-undefined');
+const noWebApiDirect = require('./lib/rules/no-web-api-direct');
+const noWeakMapProxy = require('./lib/rules/no-weakmap-proxy');
+
+module.exports = {
+  rules: {
+    'no-object-spread': noObjectSpread,
+    'no-destructuring': noDestructuring,
+    'no-dynamic-property-access': noDynamicPropertyAccess,
+    'no-index-signature': noIndexSignature,
+    'no-for-in': noForIn,
+    'no-with-statement': noWithStatement,
+    'no-nested-function': noNestedFunction,
+    'require-null-over-undefined': requireNullOverUndefined,
+    'no-web-api-direct': noWebApiDirect,
+    'no-weakmap-proxy': noWeakMapProxy,
+  },
+
+  configs: {
+    recommended: {
+      plugins: {
+        '@ucharts': require('.')
+      },
+      rules: {
+        '@ucharts/no-object-spread': 'error',
+        '@ucharts/no-destructuring': 'error',
+        '@ucharts/no-dynamic-property-access': 'error',
+        '@ucharts/no-index-signature': 'error',
+        '@ucharts/no-for-in': 'error',
+        '@ucharts/no-with-statement': 'error',
+        '@ucharts/no-nested-function': 'error',
+        '@ucharts/require-null-over-undefined': 'error',
+        '@ucharts/no-web-api-direct': ['error', {
+          forbiddenApis: ['console.log', 'console.warn', 'console.error', 'console.info', 'requestAnimationFrame', 'cancelAnimationFrame', 'performance.now']
+        }],
+        '@ucharts/no-weakmap-proxy': 'warn',
+      }
+    },
+
+    strict: {
+      plugins: {
+        '@ucharts': require('.')
+      },
+      rules: {
+        '@ucharts/no-object-spread': 'error',
+        '@ucharts/no-destructuring': 'error',
+        '@ucharts/no-dynamic-property-access': 'error',
+        '@ucharts/no-index-signature': 'error',
+        '@ucharts/no-for-in': 'error',
+        '@ucharts/no-with-statement': 'error',
+        '@ucharts/no-nested-function': 'error',
+        '@ucharts/require-null-over-undefined': 'error',
+        '@ucharts/no-web-api-direct': 'error',
+        '@ucharts/no-weakmap-proxy': 'error',
+      }
+    }
+  }
+};

package/lib/rules/no-destructuring.js

@@ -0,0 +1,62 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow destructuring patterns in Safe TS subset (ArkTS completely forbids them)',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [],
+    messages: {
+      objectDestructuring: 'Object destructuring is not allowed. Use explicit property access: const a = obj.a;',
+      arrayDestructuring: 'Array destructuring is not allowed. Use index access: const a = arr[0];',
+      paramDestructuring: 'Parameter destructuring is not allowed. Accept object and access properties explicitly.'
+    }
+  },
+
+  create(context) {
+    function reportDestructuring(node) {
+      if (node.type === 'ObjectPattern') {
+        context.report({ node, messageId: 'objectDestructuring' });
+      } else if (node.type === 'ArrayPattern') {
+        if (node.parent && node.parent.type !== 'ForOfStatement') {
+          context.report({ node, messageId: 'arrayDestructuring' });
+        }
+      }
+    }
+
+    return {
+      VariableDeclarator(node) {
+        if (node.id) reportDestructuring(node.id);
+      },
+      AssignmentExpression(node) {
+        if (node.left) reportDestructuring(node.left);
+      },
+      FunctionDeclaration(node) {
+        if (node.params) {
+          for (var i = 0; i < node.params.length; i++) {
+            var param = node.params[i];
+            if (param && param.type === 'ObjectPattern') {
+              context.report({ node: param, messageId: 'paramDestructuring' });
+            }
+          }
+        }
+      },
+      ArrowFunctionExpression(node) {
+        if (node.params) {
+          for (var j = 0; j < node.params.length; j++) {
+            var param2 = node.params[j];
+            if (param2 && param2.type === 'ObjectPattern') {
+              context.report({ node: param2, messageId: 'paramDestructuring' });
+            }
+          }
+        }
+      },
+      CatchClause(node) {
+        if (node.param && node.param.type === 'ObjectPattern') {
+          context.report({ node: node.param, messageId: 'objectDestructuring' });
+        }
+      }
+    };
+  }
+};

package/lib/rules/no-dynamic-property-access.js

@@ -0,0 +1,48 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow dynamic property access obj[variableKey] in Safe TS subset',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [{
+      type: 'object',
+      properties: {
+        allowStringLiteral: { type: 'boolean', default: false },
+        allowKnownTypes: { type: 'array', items: { type: 'string' }, default: ['Array'] }
+      },
+      additionalProperties: false
+    }],
+    messages: {
+      dynamicAccess: 'Dynamic property access on "{{objectName}}" with non-literal key is not allowed. Use Map.get() instead.'
+    }
+  },
+
+  create(context) {
+    var options = context.options[0] || {};
+    var allowStringLiteral = options.allowStringLiteral !== false;
+    var allowKnownTypes = new Set(options.allowKnownTypes || ['Array']);
+
+    return {
+      MemberExpression(node) {
+        if (node.computed === true) {
+          if (allowStringLiteral && node.property.type === 'Literal') return;
+          if (allowKnownTypes.has('Array')) {
+            var sourceCode = context.getSourceCode();
+            var text = sourceCode.getText(node.object);
+            if (text === 'arr' || text.endsWith('s') || text.endsWith('list')) return;
+          }
+
+          var sourceCode2 = context.getSourceCode();
+          var objectName = sourceCode2.getText(node.object);
+          context.report({
+            node,
+            messageId: 'dynamicAccess',
+            data: { objectName: objectName }
+          });
+        }
+      }
+    };
+  }
+};

package/lib/rules/no-for-in.js

@@ -0,0 +1,25 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow for...in loop in Safe TS subset',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [],
+    messages: {
+      forbidden: 'for...in loop is not allowed. Use for...of Object.keys(obj) instead.'
+    }
+  },
+
+  create(context) {
+    return {
+      ForInStatement(node) {
+        context.report({
+          node,
+          messageId: 'forbidden'
+        });
+      }
+    };
+  }
+};

package/lib/rules/no-index-signature.js

@@ -0,0 +1,25 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow Index Signature [key: string]: T in Safe TS subset',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [],
+    messages: {
+      forbidden: 'Index signature is not allowed in Safe TS subset (ArkTS forbids it). Use Map<string, T> or explicit fields instead.'
+    }
+  },
+
+  create(context) {
+    return {
+      TSIndexSignature(node) {
+        context.report({
+          node,
+          messageId: 'forbidden'
+        });
+      }
+    };
+  }
+};

package/lib/rules/no-nested-function.js

@@ -0,0 +1,47 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow nested function declarations in Safe TS subset (ArkTS forbids them)',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [{
+      type: 'object',
+      properties: {
+        allowArrowFunctions: { type: 'boolean', default: true },
+        allowMethods: { type: 'boolean', default: true }
+      },
+      additionalProperties: false
+    }],
+    messages: {
+      nestedFunction: 'Nested function declaration is not allowed in Safe TS subset. Extract to module level or use an arrow function.'
+    }
+  },
+
+  create(context) {
+    var options = context.options[0] || {};
+    var allowArrowFunctions = options.allowArrowFunctions !== false;
+    var allowMethods = options.allowMethods !== false;
+
+    return {
+      FunctionDeclaration(node) {
+        var parent = node.parent;
+        if (!parent) return;
+
+        if (parent.type === 'Program' ||
+            parent.type === 'ExportNamedDeclaration' ||
+            parent.type === 'ExportDefaultDeclaration') return;
+
+        if (allowMethods &&
+            (parent.type === 'MethodDefinition' ||
+             parent.type === 'PropertyDefinition')) return;
+
+        context.report({
+          node,
+          messageId: 'nestedFunction'
+        });
+      }
+    };
+  }
+};

package/lib/rules/no-object-spread.js

@@ -0,0 +1,29 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow object spread expression {...obj} in Safe TS subset',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [],
+    messages: {
+      forbidden: 'Object spread "{{expr}}" is not allowed in Safe TS subset (ArkTS only allows array spread). Use merge() from core/util/merge.ts instead.'
+    }
+  },
+
+  create(context) {
+    return {
+      SpreadElement(node) {
+        if (node.argument && node.argument.type === 'ObjectExpression') {
+          const sourceCode = context.getSourceCode();
+          context.report({
+            node,
+            messageId: 'forbidden',
+            data: { expr: sourceCode.getText(node) }
+          });
+        }
+      }
+    };
+  }
+};

package/lib/rules/no-weakmap-proxy.js

@@ -0,0 +1,30 @@
+module.exports = {
+  meta: {
+    type: 'warning',
+    docs: {
+      description: 'Discourage WeakMap and Proxy usage in Safe TS subset',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'warn'
+    },
+    schema: [],
+    messages: {
+      weakMap: 'WeakMap has inconsistent behavior across platforms. Use Map instead (note memory management implications).',
+      proxy: 'Proxy handler restrictions differ across platforms (especially ArkTS). Use an explicit adapter class instead.'
+    }
+  },
+
+  create(context) {
+    return {
+      NewExpression(node) {
+        var sourceCode = context.getSourceCode();
+        var callee = sourceCode.getText(node.callee);
+
+        if (callee === 'WeakMap' || callee === 'WeakSet') {
+          context.report({ node, messageId: 'weakMap' });
+        } else if (callee === 'Proxy') {
+          context.report({ node, messageId: 'proxy' });
+        }
+      }
+    };
+  }
+};

package/lib/rules/no-web-api-direct.js

@@ -0,0 +1,71 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow direct usage of Web APIs that do not exist in native environments',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [{
+      type: 'object',
+      properties: {
+        forbiddenApis: {
+          type: 'array',
+          items: { type: 'string' },
+          default: [
+            'console.log', 'console.warn', 'console.error', 'console.info',
+            'requestAnimationFrame', 'cancelAnimationFrame',
+            'performance.now', 'performance.measure'
+          ]
+        }
+      },
+      additionalProperties: false
+    }],
+    hasSuggestions: true,
+    messages: {
+      forbidden: '"{{api}}" is a Web API not available in native platforms. Use platform abstraction from core/platform/ instead.',
+      suggestion: 'Import from core/platform/logger.ts or core/platform/animation.ts'
+    }
+  },
+
+  create(context) {
+    var options = context.options[0] || {};
+    var forbiddenSet = new Set(options.forbiddenApis || []);
+    var sourceCode = context.getSourceCode();
+
+    return {
+      CallExpression(node) {
+        var expr = sourceCode.getText(node.callee);
+        if (forbiddenSet.has(expr)) {
+          context.report({
+            node,
+            messageId: 'forbidden',
+            data: { api: expr },
+            suggest: [
+              {
+                desc: 'Import from core/platform/logger.ts or core/platform/animation.ts',
+                fix(fixer) {
+                  if (expr.startsWith('console.')) {
+                    return fixer.replaceText(node.callee, 'Logger.' + expr.slice(8));
+                  }
+                  return null;
+                }
+              }
+            ]
+          });
+        }
+      },
+
+      MemberExpression(node) {
+        var fullExpr = sourceCode.getText(node);
+        if (forbiddenSet.has(fullExpr)) {
+          context.report({
+            node,
+            messageId: 'forbidden',
+            data: { api: fullExpr }
+          });
+        }
+      }
+    };
+  }
+};

package/lib/rules/no-with-statement.js

@@ -0,0 +1,25 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow with statement in Safe TS subset',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [],
+    messages: {
+      forbidden: 'with statement is not allowed. Use temporary variables instead.'
+    }
+  },
+
+  create(context) {
+    return {
+      WithStatement(node) {
+        context.report({
+          node,
+          messageId: 'forbidden'
+        });
+      }
+    };
+  }
+};

package/lib/rules/require-null-over-undefined.js

@@ -0,0 +1,52 @@
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require using null instead of undefined in Safe TS subset',
+      category: 'uCharts Safe TS Subset',
+      recommended: 'error'
+    },
+    schema: [],
+    messages: {
+      useNull: 'Use null instead of undefined (UTS/ArkTS do not support undefined).',
+      useNullCoalescing: 'Use ?? null instead of ?? undefined.',
+      useNotNull: 'Use != null instead of !== undefined.',
+      useEqualNull: 'Use == null instead of === undefined.',
+      removeOptional: 'Remove optional ? modifier and use explicit null union (T | null).'
+    }
+  },
+
+  create(context) {
+    var sourceCode = context.getSourceCode();
+
+    function checkUndefined(node) {
+      if (node.type !== 'Identifier' || node.name !== 'undefined') return;
+      context.report({ node, messageId: 'useNull' });
+    }
+
+    return {
+      Identifier: checkUndefined,
+
+      UnaryExpression(node) {
+        if (node.operator !== 'typeof') return;
+        checkUndefined(node.argument);
+      },
+
+      BinaryExpression(node) {
+        var raw = sourceCode.getText(node);
+
+        if (raw.includes('undefined')) {
+          if (node.operator === '===') {
+            context.report({ node, messageId: 'useEqualNull' });
+          } else if (node.operator === '!==') {
+            context.report({ node, messageId: 'useNotNull' });
+          } else if (raw.includes('?? undefined')) {
+            context.report({ node, messageId: 'useNullCoalescing' });
+          } else if (raw.includes('|| undefined')) {
+            context.report({ node, messageId: 'useNullCoalescing' });
+          }
+        }
+      }
+    };
+  }
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "@qiun/eslint-plugin-ucharts",
+    "version": "1.0.0",
+    "description": "ESLint plugin enforcing Safe TS Subset rules for uCharts cross-platform compatibility (Swift/Kotlin/ArkTS)",
+    "main": "index.js",
+    "keywords": [
+        "eslint",
+        "eslintplugin",
+        "eslint-plugin",
+        "ucharts",
+        "safe-ts-subset",
+        "arkts",
+        "uts",
+        "cross-platform"
+    ],
+    "license": "Apache-2.0",
+    "author": "秋云",
+    "homepage": "https://www.ucharts.cn",
+    "files": [
+        "index.js",
+        "lib/",
+        "README.md"
+    ],
+    "peerDependencies": {
+        "eslint": ">=8.0.0"
+    },
+    "engines": {
+        "node": ">=16.0.0"
+    }
+}