ts2famix 1.0.1

package/.eslintrc.json

@@ -0,0 +1,24 @@
+{
+    "env": {
+        "browser": true,
+        "es2021": true
+    },
+    "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/recommended"
+    ],
+    "overrides": [
+    ],
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": "latest",
+        "sourceType": "module"
+    },
+    "plugins": [
+        "@typescript-eslint"
+    ],
+    "rules": {
+        "@typescript-eslint/no-namespace": "off",
+        "semi": [1, "always"]
+    }
+}

package/.github/workflows/node.js.yml

@@ -0,0 +1,60 @@
+# This workflow will do a clean install of node dependencies, cache/restore them, and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Node.js CI
+
+permissions: write-all
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+  
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        # node-version: [12.x, 14.x, 16.x]
+        node-version: [16.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ts-graphviz/setup-graphviz@v1
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+      - run: npm run uml
+
+      - name: Init new repo in doc-uml folder and commit generated files
+        run: |
+          cd doc-uml/
+          git init
+          git add -A
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git commit -m 'update doc'
+
+      # Careful, this can kill your project, because it force pushes to the destination branch
+      - name: Force push to destination branch
+        uses: ad-m/github-push-action@master
+        with:
+          # Token for the repo. Can be passed in using $\{{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          force: true
+          # Destination branch to push changes
+          branch: v1/doc
+          # We have to push from the folder where files were generated.
+          # Same were the new repo was initialized in the previous step
+          directory: ./doc-uml

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2021 Arezoo Nasrollah Zadeh
+Copyright (c) 2021 Christopher Fuhrman
+Copyright (c) 2023 Maël Paul
+
+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,111 @@
+# FamixTypeScriptImporter
+
+[![Node.js CI](https://github.com/maelpaul/FamixTypeScriptImporter/actions/workflows/node.js.yml/badge.svg)](https://github.com/maelpaul/FamixTypeScriptImporter/actions/workflows/node.js.yml)
+
+Create a [FamixTypeScript](https://github.com/fuhrmanator/FamixTypeScript) model in JSON of TypeScript files.
+
+## Installation
+
+```sh
+npm install
+```
+
+## Usage
+
+Instructions for using the command-line importer :
+
+```sh
+ts-node src/ts2famix-tsconfig.ts --help
+```
+or
+```sh
+ts-node src/ts2famix-cli.ts --help
+```
+
+Run tests :
+```sh
+npm test
+```
+
+Generate coverage :
+```sh
+npm run coverage
+```
+
+Then, open "```coverage/lcov-report/index.html```" with your favorite browser : 
+```sh
+firefox coverage/lcov-report/index.html &
+```
+
+Generate documentation :
+```sh
+npm run doc
+```
+
+Then, open "```docs/index.html```" with your favorite browser : 
+```sh
+firefox docs/index.html &
+```
+
+Generate plantuml and svg of the metamodel :
+```sh
+npm run uml
+```
+
+Then, open "```doc-uml/metamodel.svg```" with your favorite image viewer :
+```sh
+eog doc-uml/metamodel.svg &
+```
+
+## Parse a full project
+
+```sh
+ts-node src/ts2famix-tsconfig.ts -i ../path/to/project/tsconfig.json -o JSONModels/projectName.json
+```
+or
+```sh
+ts-node src/ts2famix-cli.ts -i "../path/to/project/**/*.ts" -o JSONModels/projectName.json
+```
+
+## Generate an object diagram of the JSON model
+
+```sh
+ts-node src/famix2puml.ts -i JSONModels/projectName.json -o PUMLModels/projectName.puml
+```
+
+## Import the JSON model into Moose 🫎
+
+You need to copy the "```JSONModels/projectName.json```" into your "```Pharo/images/[imageName]```" directory.
+
+For a Moose Suite 10 (stable) user with the Pharo directory in the root directory, do : 
+```sh
+cp JSONModels/projectName.json ~/Pharo/images/Moose\ Suite\ 10\ \(stable\)/.
+```
+
+Then, in a Moose Playground, do :
+```st
+Metacello new 
+  githubUser: 'fuhrmanator' project: 'FamixTypeScript' commitish: 'master' path: 'src';
+  baseline: 'FamixTypeScript';
+  load
+```
+
+This command installs the TypeScript metamodel into Moose.
+
+Then, generate the metamodel with :  
+```Library > Famix > Manage metamodels > Regenerate all metamodels```
+
+Then, in a Moose Playground, do :
+```st
+'projectName.json' asFileReference readStreamDo:
+  [ :stream | model := FamixTypeScriptModel new 
+    importFromJSONStream: stream. model install ].
+```
+
+This command imports the JSON model into Moose.
+
+## TypeScript Metamodel API documentation (visualization)
+
+The following was generated by CI using [tplant](https://github.com/bafolts/tplant), in a similar fashion described [here](https://modularmoose.org/2021/07/19/automatic-metamodel-documentation-generation.html).
+
+![FamixTypeScript API Metamodel](https://raw.githubusercontent.com/maelpaul/FamixTypeScriptImporter/v1/doc/metamodel.svg)

package/doc-metamodel/skins.include.puml

@@ -0,0 +1,2 @@
+' put skinparam customizations here
+hide members

package/jest.config.ts

@@ -0,0 +1,199 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+export default {
+  // All imported modules in your tests should be mocked automatically
+  // automock: false,
+
+  // Stop running tests after `n` failures
+  // bail: 0,
+
+  // The directory where Jest should store its cached dependency information
+  // cacheDirectory: "",
+
+  // Automatically clear mock calls and instances between every test
+  // clearMocks: false,
+
+  // Indicates whether the coverage information should be collected while executing the test
+  collectCoverage: false,
+
+  // An array of glob patterns indicating a set of files for which coverage information should be collected
+  // collectCoverageFrom: undefined,
+
+  // The directory where Jest should output its coverage files
+  coverageDirectory: "coverage",
+
+  // An array of regexp pattern strings used to skip coverage collection
+  // coveragePathIgnorePatterns: [
+  //   "\\\\node_modules\\\\"
+  // ],
+
+  // Indicates which provider should be used to instrument code for coverage
+  coverageProvider: "babel",
+
+  // A list of reporter names that Jest uses when writing coverage reports
+  // coverageReporters: [
+  //   "json",
+  //   "text",
+  //   "lcov",
+  //   "clover"
+  // ],
+
+  // An object that configures minimum threshold enforcement for coverage results
+  // coverageThreshold: undefined,
+
+  // A path to a custom dependency extractor
+  // dependencyExtractor: undefined,
+
+  // Make calling deprecated APIs throw helpful error messages
+  // errorOnDeprecated: false,
+
+  // Force coverage collection from ignored files using an array of glob patterns
+  // forceCoverageMatch: [],
+
+  // A path to a module which exports an async function that is triggered once before all test suites
+  // globalSetup: undefined,
+
+  // A path to a module which exports an async function that is triggered once after all test suites
+  // globalTeardown: undefined,
+
+  // A set of global variables that need to be available in all test environments
+  // globals: {},
+
+  // The maximum amount of workers used to run your tests. Can be specified as % or a number. E.g. maxWorkers: 10% will use 10% of your CPU amount + 1 as the maximum worker number. maxWorkers: 2 will use a maximum of 2 workers.
+  // maxWorkers: 1,
+
+  // An array of directory names to be searched recursively up from the requiring module's location
+  // moduleDirectories: [
+  //   "node_modules"
+  // ],
+
+  // An array of file extensions your modules use
+  // moduleFileExtensions: [
+  //   "js",
+  //   "jsx",
+  //   "ts",
+  //   "tsx",
+  //   "json",
+  //   "node"
+  // ],
+
+  // A map from regular expressions to module names or to arrays of module names that allow to stub out resources with a single module
+  // moduleNameMapper: {},
+
+  // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
+  // modulePathIgnorePatterns: [],
+
+  // Activates notifications for test results
+  // notify: false,
+
+  // An enum that specifies notification mode. Requires { notify: true }
+  // notifyMode: "failure-change",
+
+  // A preset that is used as a base for Jest's configuration
+  // preset: undefined,
+
+  // Run tests from one or more projects
+  // projects: undefined,
+
+  // Use this configuration option to add custom reporters to Jest
+  // reporters: undefined,
+
+  // Automatically reset mock state between every test
+  // resetMocks: false,
+
+  // Reset the module registry before running each individual test
+  // resetModules: false,
+
+  // A path to a custom resolver
+  // resolver: undefined,
+
+  // Automatically restore mock state between every test
+  // restoreMocks: false,
+
+  // The root directory that Jest should scan for tests and modules within
+  // rootDir: undefined,
+
+  // A list of paths to directories that Jest should use to search for files in
+  // roots: [
+  //   "<rootDir>"
+  // ],
+
+  // Allows you to use a custom runner instead of Jest's default test runner
+  // runner: "jest-runner",
+
+  // The paths to modules that run some code to configure or set up the testing environment before each test
+  // setupFiles: [],
+
+  // A list of paths to modules that run some code to configure or set up the testing framework before each test
+  // setupFilesAfterEnv: [],
+
+  // The number of seconds after which a test is considered as slow and reported as such in the results.
+  // slowTestThreshold: 5,
+
+  // A list of paths to snapshot serializer modules Jest should use for snapshot testing
+  // snapshotSerializers: [],
+
+  // The test environment that will be used for testing
+  testEnvironment: "jest-environment-node",
+
+  // Options that will be passed to the testEnvironment
+  // testEnvironmentOptions: {},
+
+  // Adds a location field to test results
+  // testLocationInResults: false,
+
+  // The glob patterns Jest uses to detect test files
+  // testMatch: [
+  //   "**/__tests__/**/*.[jt]s?(x)",
+  //   "**/?(*.)+(spec|test).[tj]s?(x)"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
+  // testPathIgnorePatterns: [
+  //   "\\\\node_modules\\\\"
+  // ],
+
+  // The regexp pattern or array of patterns that Jest uses to detect test files
+  // testRegex: [],
+
+  // This option allows the use of a custom results processor
+  // testResultsProcessor: undefined,
+
+  // This option allows use of a custom test runner
+  // testRunner: "jest-circus/runner",
+
+  // This option sets the URL for the jsdom environment. It is reflected in properties such as location.href
+  // testURL: "http://localhost",
+
+  // Setting this value to "fake" allows the use of fake timers for functions such as "setTimeout"
+  // timers: "real",
+
+  // A map from regular expressions to paths to transformers
+  // transform: undefined,
+  transform: {
+    "^.+\\.tsx?$": ["ts-jest", {
+      isolatedModules: true
+    }]
+  },
+  
+  // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
+  // transformIgnorePatterns: [
+  //   "\\\\node_modules\\\\",
+  //   "\\.pnp\\.[^\\\\]+$"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
+  // unmockedModulePathPatterns: undefined,
+
+  // Indicates whether each individual test should be reported during the run
+  verbose: true,
+
+  // An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
+  // watchPathIgnorePatterns: [],
+
+  // Whether to use watchman for file crawling
+  // watchman: true,
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ts2famix",
+  "version": "1.0.1",
+  "description": "Examples of the TypeScript compiler API usage",
+  "main": "dist/ts2famix-cli.js",
+  "scripts": {
+    "dev": "ts-node src/ts2famix-cli.ts",
+    "debug": "node --inspect-brk node_modules/.bin/ts-node",
+    "build": "tsc",
+    "test": "jest --colors --silent",
+    "local": "sudo npm i -g && ts2famix",
+    "refresh": "rm -rf ./node_modules ./package-lock.json && npm install",
+    "doc": "typedoc && touch docs/.gitkeep",
+    "coverage": "jest --colors --silent --coverage --coverageDirectory=coverage",
+    "uml": "./src/generate_uml.sh"
+  },
+  "bin": {
+    "ts2famix": "dist/ts2famix-cli.js"
+  },
+  "keywords": [],
+  "author": "",
+  "nodemonConfig": {
+    "ignore": [
+      "dist/*"
+    ]
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.4",
+    "@types/node": "^20.6.0",
+    "@types/yargs": "^17.0.24",
+    "@typescript-eslint/eslint-plugin": "^6.6.0",
+    "@typescript-eslint/parser": "^6.6.0",
+    "eslint": "^8.49.0",
+    "jest": "^29.6.4",
+    "tplant": "^3.1.2",
+    "ts-jest": "^29.1.1",
+    "ts-morph": "^19.0.0",
+    "typedoc": "^0.25.1",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "ts-node": "^10.9.1",
+    "tsutils": "^3.21.0",
+    "yargs": "^17.7.2"
+  }
+}

package/src/analyze.ts

@@ -0,0 +1,90 @@
+import { Project } from "ts-morph";
+import * as fs from 'fs';
+import { FamixRepository } from "./lib/famix/src/famix_repository";
+import { FamixFunctions } from "./famix_functions/famix_functions";
+import { ProcessFiles } from "./analyze_functions/processFiles";
+import { ProcessAccesses } from "./analyze_functions/processAccesses";
+import { ProcessInvocations } from "./analyze_functions/processInvocations";
+import { ProcessInheritances } from "./analyze_functions/processInheritances";
+import { ProcessImportClauses } from "./analyze_functions/processImportClauses";
+
+/**
+ * This class is used to build a Famix model from a TypeScript source code
+ */
+export class Importer {
+
+    private project = new Project(); // The project containing the source files to analyze
+    private famixFunctions = new FamixFunctions(); // FamixFunctions object, it contains all the functions needed to create Famix entities
+    private processFiles = new ProcessFiles(this.famixFunctions); // ProcessFiles object, it contains all the functions needed to process the source files
+    private processAccesses = new ProcessAccesses(this.famixFunctions); // ProcessAccesses object, it contains all the functions needed to process the accesses
+    private processInvocations = new ProcessInvocations(this.famixFunctions); // ProcessInvocations object, it contains all the functions needed to process the invocations
+    private processInheritances = new ProcessInheritances(this.famixFunctions); // ProcessInheritances object, it contains all the functions needed to process the inheritances
+    private processImportClauses = new ProcessImportClauses(this.famixFunctions); // ProcessImportClauses object, it contains all the functions needed to process the import clauses
+
+    /**
+     * Main method
+     * @param paths An array of paths to the source files to analyze
+     * @returns The Famix repository containing the Famix model
+     */
+    public famixRepFromPaths(paths: Array<string>): FamixRepository {
+        let famixRep: FamixRepository;
+
+        try {
+            console.info(`famixRepFromPaths: paths: ${paths}`);
+
+            const sourceFiles = this.project.addSourceFilesAtPaths(paths);
+            this.processFiles.processFiles(sourceFiles);
+
+            const accesses = this.processFiles.getAccesses();
+            const methodsAndFunctionsWithId = this.processFiles.getMethodsAndFunctionsWithId();
+            const classes = this.processFiles.getClasses();
+            const interfaces = this.processFiles.getInterfaces();
+            const modules = this.processFiles.getModules();
+            const exports = this.processFiles.getExports();
+
+            this.processImportClauses.processImportClauses(modules, exports);
+            this.processAccesses.processAccesses(accesses);
+            this.processInvocations.processInvocations(methodsAndFunctionsWithId);
+            this.processInheritances.processInheritances(classes, interfaces);
+
+            famixRep = this.famixFunctions.getFamixRepository();
+        }
+        catch (error) {
+            console.error(`> ERROR: got exception ${error}. Exiting...`);
+            console.error(error.message);
+            console.error(error.stack);
+            process.exit(1);
+        }
+
+        return famixRep;
+    }
+
+    /**
+     * Main method for tests
+     * @param filename The name of the file to analyze
+     * @param source A TypeScript source code
+     * @returns The Famix repository containing the Famix model
+     */
+    public famixRepFromSource(filename: string, source: string): FamixRepository {
+        const filePath = `./test_src/${filename}.ts`;
+
+        fs.writeFileSync(filePath, source, 'utf-8');
+
+        const famixRep = this.famixRepFromPaths([filePath]);
+
+        return famixRep;
+    }
+
+    /**
+     * Main method for a ts-morph project
+     * @param project A ts-morph project
+     * @returns The Famix repository containing the Famix model
+     */
+    public famixRepFromProject(project: Project): FamixRepository {
+        const sourceFileNames = project.getSourceFiles().map(f => f.getFilePath()) as Array<string>;
+
+        const famixRep = this.famixRepFromPaths(sourceFileNames);
+
+        return famixRep;
+    }
+}

package/src/analyze_functions/processAccesses.ts

@@ -0,0 +1,50 @@
+import { Identifier, ParameterDeclaration, VariableDeclaration, PropertyDeclaration, EnumMember } from "ts-morph";
+import { FamixFunctions } from "../famix_functions/famix_functions";
+
+/**
+ * This class is used to build a Famix model for the accesses
+ */
+export class ProcessAccesses {
+
+    private famixFunctions: FamixFunctions; // FamixFunctions object, it contains all the functions needed to create Famix entities
+
+    /**
+     * Initializes the ProcessAccesses object
+     * @param famixFunctions FamixFunctions object, it contains all the functions needed to create Famix entities
+     */
+    constructor(famixFunctions: FamixFunctions) {
+        this.famixFunctions = famixFunctions;
+    }
+
+    /**
+     * Builds a Famix model for the accesses on the parameters, variables, properties and enum members of the source files
+     * @param accesses A map of parameters, variables, properties and enum members with their id
+     */
+    public processAccesses(accesses: Map<number, ParameterDeclaration | VariableDeclaration | PropertyDeclaration | EnumMember>): void {
+        console.info(`processAccesses: Creating accesses:`);
+        accesses.forEach((v, id) => {
+            console.info(`processAccesses: Accesses to ${v.getName()}`);
+            try {
+                const temp_nodes = v.findReferencesAsNodes() as Array<Identifier>;
+                temp_nodes.forEach(node => this.processNodeForAccesses(node, id));
+            } catch (error) {
+                console.error(`> WARNING: got exception ${error}. Continuing...`);
+            }
+        });
+    }
+
+    /**
+     * Builds a Famix model for an access on a parameter, variable, property or enum member
+     * @param n A node
+     * @param id An id of a parameter, a variable, a property or an enum member
+     */
+    private processNodeForAccesses(n: Identifier, id: number): void {
+        try {
+            this.famixFunctions.createFamixAccess(n, id);
+
+            console.info(`processNodeForAccesses: node: node, (${n.getType().getText()})`);
+        } catch (error) {
+            console.error(`> WARNING: got exception ${error}. ScopeDeclaration invalid for ${n.getSymbol().getFullyQualifiedName()}. Continuing...`);
+        }
+    }
+}