feat: add ts-source-parser package (#218)

* feat: create TsSourceParser

* docs: create doc

* test: add CI for ts-source-parser

* fix: blank line typo

* fix: add workspace to root package.json

* fix: name CI ->  TsSourceParser CI

* fix:add --workspace flag to test run

* fix: package.json indentation

* fix: add last blank line package.json

* fix: add --workspace CI run test flag to other workspaces

Author: jean-michelet

.github/workflows/estree-ast-utils.yml

@@ -38,4 +38,4 @@ jobs:
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm install
-    - run: npm test
+    - run: npm run test --workspace=workspaces/estree-ast-utils

.github/workflows/sec-literal.yml

@@ -23,7 +23,5 @@ jobs:
         uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: ${{ matrix.node-version }}
-      - name: Install dependencies
-        run: npm install
-      - name: Run tests
-        run: npm run test
+      - run: npm install
+      - run: npm run test --workspace=workspaces/sec-literal

.github/workflows/ts-source-parser.yml

@@ -0,0 +1,41 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: TsSourceParser CI
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - workspaces/ts-source-parser/**
+  pull_request:
+    paths:
+      - workspaces/ts-source-parser/**
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - name: Harden Runner
+      uses: step-security/harden-runner@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+      with:
+        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
+
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install
+    - run: npm run test --workspace=workspaces/ts-source-parser

package.json

@@ -20,7 +20,8 @@
   },
   "workspaces": [
     "workspaces/estree-ast-utils",
-    "workspaces/sec-literal"
+    "workspaces/sec-literal",
+    "workspaces/ts-source-parser"
   ],
   "keywords": [
     "ast",

workspaces/ts-source-parser/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 NodeSecure
+
+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.

workspaces/ts-source-parser/README.md

@@ -0,0 +1,43 @@
+# ts-source-parser
+[![version](https://img.shields.io/github/package-json/v/NodeSecure/js-x-ray?filename=workspaces%2Fts-source-parser%2Fpackage.json&style=for-the-badge)](https://www.npmjs.com/package/@nodesecure/ts-source-parser)
+[![maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg?style=for-the-badge)](https://github.com/NodeSecure/js-x-ray/blob/master/workspaces/ts-source-parser/graphs/commit-activity)
+[![OpenSSF
+Scorecard](https://api.securityscorecards.dev/projects/github.com/NodeSecure/js-x-ray/badge?style=for-the-badge)](https://api.securityscorecards.dev/projects/github.com/NodeSecure/js-x-ray)
+[![mit](https://img.shields.io/github/license/NodeSecure/js-x-ray?style=for-the-badge)](https://github.com/NodeSecure/js-x-ray/blob/master/workspaces/ts-source-parser/LICENSE)
+[![build](https://img.shields.io/github/actions/workflow/status/NodeSecure/js-x-ray/ts-source-parser.yml?style=for-the-badge)](https://github.com/NodeSecure/js-x-ray/actions?query=workflow%3A%22sec+literal+CI%22)
+
+This package provide a TypeScript source parser for the `@nodesecure/js-x-ray` project.
+
+## Getting Started
+
+This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
+
+```bash
+$ npm i @nodesecure/ts-source-parser
+# or
+$ yarn add @nodesecure/ts-source-parser
+```
+
+## Usage example
+```js
+import { TsSourceParser } from "@nodesecure/ts-source-parser";
+
+const parser = new TsSourceParser();
+const body = parser.parse("const x: number = 5;");
+
+console.log(body);
+```
+
+## Usage with `js-x-ray` 
+```js
+import { runASTAnalysis } from "@nodesecure/js-x-ray";
+import { readFileSync } from "node:fs";
+
+const { warnings, dependencies } = runASTAnalysis(
+    readFileSync("./file.ts", "utf-8"),
+    { customParser: new TsSourceParser() }
+);
+
+console.log(dependencies);
+console.dir(warnings, { depth: null });
+```

workspaces/ts-source-parser/index.d.ts

@@ -0,0 +1,8 @@
+import { tsParsingOptions } from "./src/TsSourceParser";
+
+declare class TsSourceParser {
+  parse(
+    code: string,
+    options = tsParsingOptions,
+  ): TSESTree.Program;
+}

workspaces/ts-source-parser/index.js

@@ -0,0 +1 @@
+export { TsSourceParser } from "./src/TsSourceParser.js";

workspaces/ts-source-parser/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nodesecure/ts-source-parser",
+  "version": "1.0.0",
+  "description": "TypeScript parser for AST XRay analysis",
+  "type": "module",
+  "exports": "./index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "lint": "eslint src test",
+    "prepublishOnly": "pkg-ok",
+    "test-only": "glob -c \"node --test-reporter=spec --test\" \"./test/**/*.spec.js\"",
+    "test": "c8 --all --src ./src -r html npm run test-only",
+    "check": "cross-env npm run lint && npm run test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NodeSecure/js-x-ray.git"
+  },
+  "keywords": [
+    "typescript",
+    "estree",
+    "ast",
+    "utils"
+  ],
+  "files": [
+    "src"
+  ],
+  "author": "Michelet Jean <[email protected]>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/NodeSecure/js-x-ray/issues"
+  },
+  "homepage": "https://github.com/NodeSecure/js-x-ray/tree/master/workspaces/ts-source-parser#readme",
+  "dependencies": {
+    "@typescript-eslint/typescript-estree": "^6.19.1"
+  }
+}

workspaces/ts-source-parser/src/TsSourceParser.js

@@ -0,0 +1,25 @@
+// Import Third-party Dependencies
+import { parse } from "@typescript-eslint/typescript-estree";
+
+// CONSTANTS
+export const tsParsingOptions = {
+  jsDocParsingMode: "none",
+  jsx: true,
+  loc: true,
+  range: false
+};
+
+export class TsSourceParser {
+  /**
+   * @param {object} options
+   */
+  parse(source, options = {}) {
+    const { body } = parse(source, {
+      ...tsParsingOptions,
+      ...options
+    });
+
+    return body;
+  }
+}
+

workspaces/ts-source-parser/test/TsSourceParser.spec.js

@@ -0,0 +1,54 @@
+// Import Node.js Dependencies
+import { describe, it } from "node:test";
+import assert from "assert/strict";
+
+// Import Internal Dependencies
+import { TsSourceParser } from "../src/TsSourceParser.js";
+
+describe("TsSourceParser", () => {
+  describe("parse", () => {
+    const parser = new TsSourceParser();
+
+    it("should correctly parse with default options", () => {
+      const source = "const x: number = 5;";
+      const body = parser.parse(source);
+
+      assert.strictEqual(body[0].type, "VariableDeclaration");
+      assert.ok(body[0].loc);
+      assert.ok(body[0].range === undefined);
+    });
+
+    it("should correctly parse with custom options", () => {
+      const source = "const x: number = 5;";
+      const body = parser.parse(source, { loc: false, range: true });
+
+      assert.strictEqual(body[0].type, "VariableDeclaration");
+      assert.ok(body[0].loc === undefined);
+      assert.ok(body[0].range);
+    });
+
+    it("should not crash parsing JSX by default", () => {
+      const source = `const Dropzone = forwardRef(({ children, ...params }, ref) => {
+            const { open, ...props } = useDropzone(params);
+            useImperativeHandle(ref, () => ({ open }), [open]);
+            return <Fragment>{children({ ...props, open })}</Fragment>;
+        });`;
+
+      assert.doesNotThrow(() => {
+        parser.parse(source);
+      });
+    });
+
+    it("should crash parsing JSX if jsx: false", () => {
+      const source = `const Dropzone = forwardRef(({ children, ...params }, ref) => {
+            const { open, ...props } = useDropzone(params);
+            useImperativeHandle(ref, () => ({ open }), [open]);
+            return <Fragment>{children({ ...props, open })}</Fragment>;
+        });`;
+
+      assert.throws(() => {
+        parser.parse(source, { jsx: false });
+      });
+    });
+  });
+});