goatlint-parser 0.125.0

package/README.md

@@ -0,0 +1,167 @@
+# Oxc Parser
+
+See [usage instructions](https://goatlint.dev/docs/guide/usage/parser).
+
+## Features
+
+### Supports WASM
+
+See https://stackblitz.com/edit/oxc-parser for usage example.
+
+### ESTree
+
+When parsing JS or JSX files, the AST returned is fully conformant with the
+[ESTree standard](https://github.com/estree/estree), the same as produced by
+[Acorn](https://npmx.dev/package/acorn).
+
+When parsing TypeScript, the AST conforms to [@typescript-eslint/typescript-estree](https://npmx.dev/package/@typescript-eslint/typescript-estree)'s TS-ESTree format.
+
+If you need all ASTs in the same with-TS-properties format, use the `astType: 'ts'` option.
+
+The only differences between Oxc's AST and ESTree / TS-ESTree are:
+
+- Support for Stage 3 [decorators](https://github.com/tc39/proposal-decorators).
+- Support for Stage 3 ECMA features [`import defer`](https://github.com/tc39/proposal-defer-import-eval)
+  and [`import source`](https://github.com/tc39/proposal-source-phase-imports).
+- In TS-ESTree AST, `import.defer(...)` and `import.source(...)` are represented as an `ImportExpression`
+  with `'defer'` or `'source'` in `phase` field (as in ESTree spec), where TS-ESLint represents these
+  as a `CallExpression` with `MetaProperty` as its `callee`.
+- Addition of a non-standard `hashbang` field to `Program`.
+
+That aside, the AST should completely align with Acorn's ESTree AST or TS-ESLint's TS-ESTree.
+Any deviation would be considered a bug.
+
+### AST Types
+
+[@goat-project/types](https://npmx.dev/package/@goat-project/types) can be used. For example:
+
+```typescript
+import { Statement } from "@goat-project/types";
+```
+
+### Visitor
+
+An AST visitor is provided. See example below.
+
+This package also exports visitor keys which can be used with any other ESTree walker.
+
+```js
+import { visitorKeys } from "oxc-parser";
+```
+
+### Fast Mode
+
+By default, Oxc parser does not produce semantic errors where symbols and scopes are needed.
+
+To enable semantic errors, apply the option `showSemanticErrors: true`.
+
+For example,
+
+```js
+let foo;
+let foo;
+```
+
+Does not produce any errors when `showSemanticErrors` is `false`, which is the default behavior.
+
+Fast mode is best suited for parser plugins, where other parts of your build pipeline has already checked for errors.
+
+Please note that turning off fast mode ​incurs​ a small performance overhead.
+
+### Returns ESM information.
+
+It is likely that you are writing a parser plugin that requires ESM information.
+
+To avoid walking the AST again, Oxc Parser returns ESM information directly.
+
+This information can be used to rewrite import and exports with the help of [`magic-string`](https://npmx.dev/package/magic-string),
+without any AST manipulations.
+
+```ts
+export interface EcmaScriptModule {
+  /**
+   * Has ESM syntax.
+   *
+   * i.e. `import` and `export` statements, and `import.meta`.
+   *
+   * Dynamic imports `import('foo')` are ignored since they can be used in non-ESM files.
+   */
+  hasModuleSyntax: boolean;
+  /** Import statements */
+  staticImports: Array<StaticImport>;
+  /** Export statements */
+  staticExports: Array<StaticExport>;
+  /** Dynamic import expressions */
+  dynamicImports: Array<DynamicImport>;
+  /** Span positions of `import.meta` */
+  importMetas: Array<Span>;
+}
+```
+
+## API
+
+### Functions
+
+```typescript
+// Synchronous parsing
+parseSync(filename: string, sourceText: string, options?: ParserOptions): ParseResult
+
+// Asynchronous parsing
+parse(filename: string, sourceText: string, options?: ParserOptions): Promise<ParseResult>
+```
+
+Use `parseSync` for synchronous parsing. Use `parse` for asynchronous parsing, which can be beneficial in I/O-bound or concurrent scenarios, though it adds async overhead.
+
+### Example
+
+```javascript
+import { parseSync, Visitor } from "oxc-parser";
+
+const code = "const url: String = /* 🤨 */ import.meta.url;";
+
+// File extension is used to determine which dialect to parse source as.
+const filename = "test.tsx";
+
+const result = parseSync(filename, code);
+// Or use async version: const result = await parse(filename, code);
+
+// An array of errors, if any.
+console.log(result.errors);
+
+// AST and comments.
+console.log(result.program, result.comments);
+
+// ESM information - imports, exports, `import.meta`s.
+console.log(result.module);
+
+// Visit the AST
+const visitations = [];
+
+const visitor = new Visitor({
+  VariableDeclaration(decl) {
+    visitations.push(`enter ${decl.kind}`);
+  },
+  "VariableDeclaration:exit"(decl) {
+    visitations.push(`exit ${decl.kind}`);
+  },
+  Identifier(ident) {
+    visitations.push(ident.name);
+  },
+});
+
+visitor.visit(result.program);
+
+// Logs: [ 'enter const', 'url', 'String', 'import', 'meta', 'url', 'exit const' ]
+console.log(visitations);
+```
+
+### Options
+
+All options are optional.
+
+- `lang`: `'js'` | `'jsx'` | `'ts'` | `'tsx'`. Set language of source. If omitted, language is deduced from file extension.
+- `sourceType`: `'script'` | `'module'` | `'unambiguous'`. Set source type. Defaults to `'module'`.
+- `astType`: `'js'` | `'ts'`. Set to `'ts'` if you want ASTs of plain JS/JSX files to contain TypeScript-specific properties.
+- `range`: `true` | `false`. If `true`, AST nodes contain a `range` field. Defaults to `false`.
+- `preserveParens`: `true` | `false`. If `true`, parenthesized expressions are represented by (non-standard) `ParenthesizedExpression` and `TSParenthesizedType` AST nodes. Defaults to `true`.
+- `showSemanticErrors`: `true` | `false`. If `true`, check file for semantic errors which parser does not otherwise emit e.g. `let x; let x;`. Has a small performance cost. Defaults to `false`.

package/package.json

@@ -0,0 +1,129 @@
+{
+  "name": "goatlint-parser",
+  "version": "0.125.0",
+  "description": "Oxc Parser Node API",
+  "keywords": [
+    "ast",
+    "estree",
+    "javascript",
+    "goat",
+    "parser",
+    "typescript"
+  ],
+  "homepage": "https://goatlint.dev/docs/guide/usage/parser",
+  "bugs": "https://github.com/goat-project/oxc/issues",
+  "license": "MIT",
+  "author": "Boshen and oxc contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goat-project/oxc.git",
+    "directory": "napi/parser"
+  },
+  "funding": {
+    "url": "https://github.com/sponsors/Boshen"
+  },
+  "files": [
+    "src-js/bindings.js",
+    "src-js/index.d.ts",
+    "src-js/index.js",
+    "src-js/wasm.js",
+    "src-js/webcontainer-fallback.cjs",
+    "src-js/wrap.js",
+    "src-js/generated/constants.js",
+    "src-js/raw-transfer/common.js",
+    "src-js/raw-transfer/eager.js",
+    "src-js/raw-transfer/lazy-common.js",
+    "src-js/raw-transfer/lazy.js",
+    "src-js/raw-transfer/node-array.js",
+    "src-js/raw-transfer/supported.js",
+    "src-js/raw-transfer/visitor.js",
+    "src-js/visit/index.js",
+    "src-js/visit/visitor.js",
+    "src-js/generated/deserialize/js.js",
+    "src-js/generated/deserialize/js_range.js",
+    "src-js/generated/deserialize/ts.js",
+    "src-js/generated/deserialize/ts_range.js",
+    "src-js/generated/lazy/constructors.js",
+    "src-js/generated/lazy/type_ids.js",
+    "src-js/generated/lazy/walk.js",
+    "src-js/generated/visit/keys.js",
+    "src-js/generated/visit/type_ids.js",
+    "src-js/generated/visit/visitor.d.ts",
+    "src-js/generated/visit/walk.js"
+  ],
+  "type": "module",
+  "main": "src-js/index.js",
+  "browser": "src-js/wasm.js",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build-dev": "napi build --esm --platform --js bindings.js --dts index.d.ts --output-dir src-js",
+    "build-test": "pnpm run build-dev --profile coverage",
+    "build": "pnpm run build-dev --features allocator --release",
+    "postbuild": "publint",
+    "postbuild-dev": "node scripts/patch.js",
+    "build-wasi": "napi build --target wasm32-wasip1-threads",
+    "build-wasm": "pnpm run build-wasm-dev --release",
+    "build-wasm-dev": "pnpm run build-dev --target wasm32-wasip1-threads",
+    "build-npm-dir": "rm -rf npm-dir && napi create-npm-dirs --npm-dir npm-dir && pnpm napi artifacts --npm-dir npm-dir --output-dir src-js",
+    "build-browser-bundle": "node scripts/build-browser-bundle.js",
+    "test": "pnpm run test-node run",
+    "test-node": "vitest --dir ./test",
+    "test-browser": "vitest -c vitest.config.browser.ts",
+    "bench": "vitest bench --run ./bench.bench.js"
+  },
+  "dependencies": {
+    "goatlint-types": "^0.125.0"
+  },
+  "devDependencies": {
+    "@codspeed/vitest-plugin": "^5.0.0",
+    "@napi-rs/cli": "catalog:",
+    "@napi-rs/wasm-runtime": "catalog:",
+    "@types/node": "catalog:",
+    "@typescript-eslint/visitor-keys": "^8.54.0",
+    "@vitest/browser": "4.1.2",
+    "@vitest/browser-playwright": "4.1.2",
+    "esbuild": "^0.28.0",
+    "playwright": "^1.51.0",
+    "publint": "catalog:",
+    "tinypool": "^2.0.0",
+    "vitest": "catalog:"
+  },
+  "napi": {
+    "binaryName": "parser",
+    "dtsHeaderFile": "src-js/header.d.ts",
+    "packageName": "@goatlint-parser/binding",
+    "targets": [
+      "aarch64-apple-darwin",
+      "aarch64-linux-android",
+      "aarch64-pc-windows-msvc",
+      "aarch64-unknown-linux-gnu",
+      "aarch64-unknown-linux-musl",
+      "aarch64-unknown-linux-ohos",
+      "armv7-linux-androideabi",
+      "armv7-unknown-linux-gnueabihf",
+      "armv7-unknown-linux-musleabihf",
+      "i686-pc-windows-msvc",
+      "powerpc64le-unknown-linux-gnu",
+      "riscv64gc-unknown-linux-gnu",
+      "riscv64gc-unknown-linux-musl",
+      "s390x-unknown-linux-gnu",
+      "wasm32-wasip1-threads",
+      "x86_64-apple-darwin",
+      "x86_64-pc-windows-msvc",
+      "x86_64-unknown-freebsd",
+      "x86_64-unknown-linux-gnu",
+      "x86_64-unknown-linux-musl"
+    ],
+    "wasm": {
+      "browser": {
+        "fs": false
+      }
+    }
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}