npm package: @style3d/lt-insight
Description: a code dependency analysis tool for style3d
Author: 1506690444@qq.com
Latest version: 1.0.0-alpha.6

# Insight

Insight 是一款前端代码依赖分析工具，用于实现分析前端代码的调用关系。支持CLI/API两种使用模式，可快速集成到前端工程化体系中，用于解决大型web应用的前端依赖治理难题。


## Install

```javascript
npm install @style3d/insight --save-dev
// or
yarn add @style3d/insight --dev    
```
## Config

新建 insight.config.js 配置文件:

```javascript
const { resolve } = require('path');

module.exports = {
    // 扫描
    scan: {
        name: 'main', // 必填，项目名称
        include: '**/*.{js,ts,vue,jsx,tsx}', // 必填，需要扫描的文件路径（遵循 glob 语法）
        exclude: ['.nuxt/**', 'node_modules/**', 'internals/**', 'assets/**', 'configs/**', 'locales/**', 'public/**'], // 要排除的文件路径（遵循 glob 语法）
        alias: {
            '@domains': resolve(__dirname, './domains'),
            '@dam/components': resolve(__dirname, './domains/configuration/interactive-config/component/plugins'),
            '@tools': resolve(__dirname, './tools'),
            '@assets': resolve(__dirname, './assets'),
            '@': resolve(__dirname, './'),
        },
    },
    // 分析
    analysis: {
        plugins: [], // 可选，自定义分析插件，默认为空数组，一般不需要配置
        blackList: [], // 可选，需要标记的黑名单api，默认为空数组
    },
    // 生成报告（仅以 Cli 形态运行时会在本地生成报告）
    report: {
        reportDir: 'docs', // 可选，生成代码分析报告的目录，默认为'report',不支持多级目录配置
        reportTitle: 'Insight 代码分析报告', // 可选，代码分析报告标题，默认为'Insight 代码依赖分析报告'
    },
};
```
## Mode

### 1. cli

```javascript
// package.json 片段，添加bin command到npm script
...
"scripts": {
    "insight": "insight analysis"
}
...

$ npm run insight
// or
$ yarn insight        
```
### 2. api

```javascript
const insight = require('@style3d/insight');                                   // 代码分析包
const { execSync } = require('child_process');                                  // 子进程操作

async function run() {
    try{
        const { report, diagnosisInfos } = await insight({
            // 扫描
            scan: {
                name: 'main', // 必填，项目名称
                include: '**/*.{js,ts,vue,jsx,tsx}', // 必填，需要扫描的文件路径（遵循 glob 语法）
                exclude: ['.nuxt/**', 'node_modules/**', 'internals/**', 'assets/**', 'configs/**', 'locales/**', 'public/**'], // 要排除的文件路径（遵循 glob 语法）
                alias: {
                    '@domains': resolve(__dirname, './domains'),
                    '@dam/components': resolve(__dirname, './domains/configuration/interactive-config/component/plugins'),
                    '@tools': resolve(__dirname, './tools'),
                    '@assets': resolve(__dirname, './assets'),
                    '@': resolve(__dirname, './'),
                },
            },
            // 分析
            analysis: {
                plugins: [], // 可选，自定义分析插件，默认为空数组，一般不需要配置
                blackList: [], // 可选，需要标记的黑名单api，默认为空数组
            },
            // 生成报告（仅以 Cli 形态运行时会在本地生成报告）
            report: {
                reportDir: 'docs', // 可选，生成代码分析报告的目录，默认为'report',不支持多级目录配置
                reportTitle: 'Insight 代码分析报告', // 可选，代码分析报告标题，默认为'Insight 代码依赖分析报告'
            },
        });                                                                          
    }catch(e){
        console.log(e);
    }
};

run();
```

## insightPlugin 说明

自定义分析插件，如果开发者有更多分析指标的诉求，可以开发特定分析插件(比如分析Class类型的api，分析用于三目运算符表达式中的api,分析导入再导出api等场景)，开发分析插件需要对源码和分析工具架构及生命周期有一定的理解。

## diagnosisInfos诊断日志说明

诊断日志是在代码分析过程中插件及关键节点产生的错误信息记录，可以帮助开发者调试自定义插件，快速定位代码文件，代码行，AST节点等相关错误信息。

## 调试

调试方式推荐本地直接引用 `@style3d/insight` 进行调试，具体步骤如下：

1. 前往待分析项目根目录，完善 `insight.config.js` 配置文件。
2. 配置 package.json scripts `"insight": "ts-node D:\dachui\bedrock\lt-insight\cli\index.ts analysis"`。

# TODO
- [ ] 支持从分析报告中跳转到代码文件(本地跳转至本地代码，线上跳转到 gitlab)
- [ ] 脏调用拦截
- [ ] 目前仅支持 Dam 的依赖分析，其他项目的还需要完善
- [ ] 整体架构需要重新设计，目前架构比较混乱
- [ ] 需要支持插件化