update document

MeilCli · May 10, 2021 · a90d121 · a90d121
1 parent 5438af6
commit a90d121
Show file tree

Hide file tree

Showing 14 changed files with 698 additions and 10 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -0,0 +1 @@
+*.md
diff --git a/README.md b/README.md
@@ -1,20 +1,85 @@
 # common-lint-reporter
-
 This is generalized lint reporter action
 
+Focuses on:
+- Many lint file format support
+- Flexible extendable reporting
+- Multiple report format support, as check-run, comment or inline-comment
+
+### Specification
+Current supporting lint file format:
+- eslint(JSON)
+- checkstyle
+- junit
+  - compatibility: eslint
+
+### Feature request
+Now, this action is WIP. Features are not enough and should improve about transformer and operator. If you have nice idea, please send as issue:heart:
+
 ## Usage
+### Basic information
+This action have 3 steps. Flexible and extendable are realized by separating step
 
-ToDo
+1. Transform lint report file to common lint format file
+1. Operate converting common lint file
+1. Report common lint to GitHub
 
-## License
+### Quick usage
+```yml
+name: CI
 
+on:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 12
+      - run: npm install
+      - run: npm run build
+      - run: npm run lint
+        continue-on-error: true
+      - uses: MeilCli/common-lint-reporter/transformer/eslint@0
+        with:
+          # your output path
+          report_files: |
+            eslint_report.json
+      - uses: MeilCli/common-lint-reporter/operator/filter-by-file-changed@v0
+      - uses: MeilCli/common-lint-reporter@v0
+        with:
+          report_type: 'check_run'
+          report_name: 'Lint Report'
+```
+
+### Detail information
+- General
+  - [Usage of oss or using dependabot repository](documents/oss-or-dependabot-usage.md)
+  - [Report lint result](documents/report-lint-result.md)
+- Transformer
+  - [eslint](documents/transformer/eslint.md)
+  - [checkstyle](documents/transformer/checkstyle.md)
+  - [junit](documents/transformer/junit.md)
+- Operator
+  - [add](documents/operator/add.md)
+  - [distinct](documents/operator/distinct.md)
+  - [filter](documents/operator/filter.md)
+  - [filter-by-file-changed](documents/operator/filter-by-file-changed.md)
+  - [map](documents/operator/map.md)
+- Reference
+  - [Lint result file format](documents/lint-result.md)
+  - [Operator context](documents/operator/context.md)
+
+## License
 MIT License
 
 ### Using
-
--   [actions/toolkit](https://github.com/actions/toolkit), published by [MIT License](https://github.com/actions/toolkit/blob/master/LICENSE.md)
--   [apollo-client](https://github.com/apollographql/apollo-client), published by [MIT License](https://github.com/apollographql/apollo-client/blob/main/LICENSE)
--   [cross-fetch](https://github.com/lquixada/cross-fetch), published by [MIT License](https://github.com/lquixada/cross-fetch/blob/main/LICENSE)
--   [graphql](https://github.com/graphql/graphql-js), published by [MIT License](https://github.com/graphql/graphql-js/blob/main/LICENSE)
--   [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser), published by [MIT License](https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/LICENSE)
--   [he](https://github.com/mathiasbynens/he), published by [MIT License](https://github.com/mathiasbynens/he/blob/master/LICENSE-MIT.txt)
+- [actions/toolkit](https://github.com/actions/toolkit), published by [MIT License](https://github.com/actions/toolkit/blob/master/LICENSE.md)
+- [apollo-client](https://github.com/apollographql/apollo-client), published by [MIT License](https://github.com/apollographql/apollo-client/blob/main/LICENSE)
+- [cross-fetch](https://github.com/lquixada/cross-fetch), published by [MIT License](https://github.com/lquixada/cross-fetch/blob/main/LICENSE)
+- [graphql](https://github.com/graphql/graphql-js), published by [MIT License](https://github.com/graphql/graphql-js/blob/main/LICENSE)
+- [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser), published by [MIT License](https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/LICENSE)
+- [he](https://github.com/mathiasbynens/he), published by [MIT License](https://github.com/mathiasbynens/he/blob/master/LICENSE-MIT.txt)
diff --git a/documents/lint-result.md b/documents/lint-result.md
@@ -0,0 +1,19 @@
+# Lint result file format
+Lint result file format is simply JSON
+
+```ts
+type LintResultLevel = "notice" | "warning" | "failure";
+
+interface LintResult {
+    path: string;
+    rule: string;
+    message: string;
+    startLine: number | undefined;
+    endLine: number | undefined;
+    startColumn: number | undefined;
+    endColumn: number | undefined;
+    level: LintResultLevel;
+}
+```
+
+Lint result json is array of `LintResult`
diff --git a/documents/operator/add.md b/documents/operator/add.md
@@ -0,0 +1,63 @@
+# Operator of add
+A action for manually add lint result
+```yml
+- uses: MeilCli/common-lint-reporter/operator/add@v0
+  with:
+    function: |
+      () => add({path: "test/path3.txt", rule: "test-rule-ext", message: "hello", level: "notice"})
+```
+
+## Option
+### Input
+- `github_token`:
+  - github app token, using to read and write repository
+  - required
+  - default: `${{ github.token }}`
+- `workspace_path`:
+  - workspace path, using to convert relative path from absolute path
+- `repository`:
+  - running repository, format: owner/repository
+- `pull_request`:
+  - running pull request number
+- `commit_sha`:
+  - running commit sha
+- `report_files`:
+  - report file glob pattern
+  - required
+  - default: `common_lint.json`
+- `report_files_follow_symbolic_links`:
+  - report file glob pattern option
+  - value: `true` or `false`
+- `use_api_context`
+  - if this option is enabled, set information to context using api
+  - more information? see [this](context.md)
+  - value: `true` or `false`
+  - default: `false`
+- `function`:
+  - the function of this action
+  - required
+- `output_path`:
+  - output path
+  - required
+  - default: `common_lint.json`
+
+## function input
+`function` must be JavaScript's function, such as named-function, no-named-function or lambda-function
+
+example:
+```js
+function run() { 
+    add({
+        path: "test/file.txt",
+        message: "test message",
+        rule: "test_rule_1",
+        startLine: 1,
+        startColumn: 10,
+        endLine: 1,
+        endColumn: 20,
+        level: "failure",
+    })
+}
+```
+
+`add` function argument? see [this](../lint-result.md)
diff --git a/documents/operator/context.md b/documents/operator/context.md
@@ -0,0 +1,35 @@
+# Operator context
+Some functional operator can use context information
+
+Example:
+```yml
+- uses: MeilCli/common-lint-reporter/operator/...
+  with:
+    function: |
+      () => github.repository
+```
+
+## Context specification
+```ts
+interface GitHubContext {
+    workspacePath: string;
+    trimPath: (filePath: string) => string;
+    owner: string;
+    repository: string;
+    pullRequest: number | null;
+    commitSha: string;
+    api: ApiContext | null;
+}
+
+interface ApiContext {
+    changedFiles: ChangedFile[];
+}
+
+interface ChangedFile {
+    path: string;
+    additions: number;
+    deletions: number;
+}
+```
+
+`github.api` is only usable when `use_api_context` option is `true`
diff --git a/documents/operator/distinct.md b/documents/operator/distinct.md
@@ -0,0 +1,54 @@
+# Operator of distinct
+A action for distinct duplicated lint result
+```yml
+- uses: MeilCli/common-lint-reporter/operator/distinct@v0
+  with:
+    function: |
+      (x) => x.path + x.startLine
+```
+
+## Option
+### Input
+- `github_token`:
+  - github app token, using to read and write repository
+  - required
+  - default: `${{ github.token }}`
+- `workspace_path`:
+  - workspace path, using to convert relative path from absolute path
+- `repository`:
+  - running repository, format: owner/repository
+- `pull_request`:
+  - running pull request number
+- `commit_sha`:
+  - running commit sha
+- `report_files`:
+  - report file glob pattern
+  - required
+  - default: `common_lint.json`
+- `report_files_follow_symbolic_links`:
+  - report file glob pattern option
+  - value: `true` or `false`
+- `use_api_context`
+  - if this option is enabled, set information to context using api
+  - more information? see [this](context.md)
+  - value: `true` or `false`
+  - default: `false`
+- `function`:
+  - the function of this action
+  - required
+- `output_path`:
+  - output path
+  - required
+  - default: `common_lint.json`
+
+## function input
+`function` must be JavaScript's function, such as named-function, no-named-function or lambda-function
+
+example:
+```js
+function distinct(x) {
+     return x.path + x.startLine
+}
+```
+
+Returning value is key of deduplication. If return same key, output first value to lint-result
diff --git a/documents/operator/filter-by-file-changed.md b/documents/operator/filter-by-file-changed.md
@@ -0,0 +1,34 @@
+# Operator of filter-by-file-changed
+A action for filter lint result by PullRequest's changed files
+```yml
+- uses: MeilCli/common-lint-reporter/operator/filter-by-file-changed@v0
+```
+
+**If you use `workflow_run` workflow, must set `pull_request` input. see [this document](../oss-or-dependabot-usage.md)**
+
+## Option
+### Input
+
+- `github_token`:
+  - github app token, using to read and write repository
+  - required
+  - default: `${{ github.token }}`
+- `workspace_path`:
+  - workspace path, using to convert relative path from absolute path
+- `repository`:
+  - running repository, format: owner/repository
+- `pull_request`:
+  - running pull request number
+- `commit_sha`:
+  - running commit sha
+- `report_files`:
+  - report file glob pattern
+  - required
+  - default: `common_lint.json`
+- `report_files_follow_symbolic_links`:
+  - report file glob pattern option
+  - value: `true` or `false`
+- `output_path`:
+  - output path
+  - required
+  - default: `common_lint.json`
diff --git a/documents/operator/filter.md b/documents/operator/filter.md
@@ -0,0 +1,52 @@
+# Operator of filter
+A action for filter lint result
+```yml
+- uses: MeilCli/common-lint-reporter/operator/filter@v0
+  with:
+    function: |
+      (x) => x.path != "test/path1.txt"
+```
+
+## Option
+### Input
+- `github_token`:
+  - github app token, using to read and write repository
+  - required
+  - default: `${{ github.token }}`
+- `workspace_path`:
+  - workspace path, using to convert relative path from absolute path
+- `repository`:
+  - running repository, format: owner/repository
+- `pull_request`:
+  - running pull request number
+- `commit_sha`:
+  - running commit sha
+- `report_files`:
+  - report file glob pattern
+  - required
+  - default: `common_lint.json`
+- `report_files_follow_symbolic_links`:
+  - report file glob pattern option
+  - value: `true` or `false`
+- `use_api_context`
+  - if this option is enabled, set information to context using api
+  - more information? see [this](context.md)
+  - value: `true` or `false`
+  - default: `false`
+- `function`:
+  - the function of this action
+  - required
+- `output_path`:
+  - output path
+  - required
+  - default: `common_lint.json`
+
+## function input
+`function` must be JavaScript's function, such as named-function, no-named-function or lambda-function
+
+example:
+```js
+function filter(x) { 
+    return x.level == 'failure' 
+}
+```