Skip to content

en: KCL tools #125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 20, 2022
Merged

en: KCL tools #125

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/reference/cli/kcl/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# KCL 语言工具
# KCL Language Tools

KCL 作为 Kusion 的配置策略语言，不仅仅提供了 kcl 命令编译和执行配置程序，还提供了 fmt、lint、test、vet、docgen 等配套的辅助工具。
As the configuration policy language of Kusion, KCL not only provides the command `kcl` to compile and execute configuration programs but also provides fmt, lint, test, vet, docgen and other supporting tools.
76 changes: 36 additions & 40 deletions docs/reference/cli/kcl/lint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@
sidebar_position: 3
---

# Lint 检查代码风格
# Lint Check

KCL 支持通过内置的命令行工具对 KCL 代码进行检查，并支持多种输出格式。本文档展示 KCL Lint 工具的使用方式。
KCL supports checking KCL code style through built-in command line tool and supports multiple output formats. This document shows how to use the KCL Lint tool.

## 示例
## Example

### 工程结构
### Project Struct

```text
.
Expand All @@ -22,27 +22,27 @@ KCL 支持通过内置的命令行工具对 KCL 代码进行检查，并支持
└── test.k
```

其中，`.kcllint` 文件为配置参数文件，非必需项，`a.k`,`b.k`,`c.k`,`test.k` 为测试的 kcl 文件。
`.kcllint` is the configuration file of lint. It is optional. `a.k`, `b.k`, `c.k` and `test.k` are the kcl file to be checked.

命令：
Args：

```shell
kcl-lint your_config.k
```

或
or

```shell
kcl-lint your_config_path
```

lint 配置文件
lint configuration file

```shell
kcl-lint --config abspath/.kcllint your_config.k
```

输出结果示例：
Output:

```shell
/Users/../test.k:12:1: E0501 line too long (122 > 120 characters)
Expand All @@ -60,9 +60,9 @@ Check total 1 files:
KCL Lint: 2 problems
```

## KCL Lint 工具使用方式
## KCL Lint Tool

### CLI 参数
### Args

```shell
usage: kcl-lint [-h] [--config file] [file]
Expand All @@ -75,30 +75,30 @@ optional arguments:
--config file KCL lint config path
```

+ --config : lint 配置文件 `.kcllint` 的路径
+ file : 需要检查的单个 `.k` 文件路径或路径目录下的所有 `.k` 文件，支持绝对路径或当前目录的相对路径
+ --config : path of `.kcllint`
+ file: the path of a single `*.k` file or directory to be checked. Support the absolute path or relative path of the current directory.

### Lint 配置参数
### Lint Configuration

#### 优先级
#### Priority

Lint 的配置参数的优先级如下：
The priority of Lint's configuration is as follows:

1. CLI 参数中的 `--config file` 路径的 `.kcllint` 文件
2. 被检查 `.k` 文件所在目录或被检查目录下的 `.kcllint` 文件
3. 默认配置
1. the `.kcllint` set in CLI Args
2. the `.kcllint` under directory of checked `.k` file or checked directory
3. default configuration

#### .kcllint

`.kcllint` 文件以 yaml 格式书写。其内容包括：
The file `.kcllint` is written in YAML. Its contents include:

- check_list 用于选择检查的 checker，可选项为 `"import"` 和 `"misc"`
- ignore 用于选择忽略的检查项，可选项见错误代码
- max_line_length 为检查的参数，即单行代码最大长度
- output 用于选择输出流和输出格式，可选项为 `"stdout"`、`"file"`、`"sarif"`
- output_path 为可选项，当 output 选择了“file”或"sarif"，则必须设置输出文件的路径
+ check_list: kinds of checks, including `"import"` and `"misc"`
+ ignore: ignored check items. See the `Error Code` for optional items.
+ max_line_length: the parameter of check, that is, the maximum length of code
+ output: output streams and formats, including `"stdout"`、`"file"` and `"sarif"`
+ output_path: The path of output file. It is optional, but it is required when the `output` set as `"file"` or `"sarif"`

示例：
Example:

```yaml
check_list: ["import","misc"]
Expand All @@ -108,7 +108,7 @@ output: ["stdout"]
output_path:
```

#### 默认配置
Default Configuration:

```yaml
check_list: ["import", "misc"]
Expand All @@ -117,17 +117,13 @@ max_line_length: 200
output: ["stdout"]
```

### 检查项及错误代码
### Error Code

目前提供 import_checker 和 misc_checker

- import_checker

- E0401: Unable to import.
- W0401: Reimport.
- E0406: Module import itself.
- W0411: Import but unused.
- E0413: ImportStmt is not at the top of the file
- misc_checker

- E0501: Line too long
+ import_checker
+ E0401: Unable to import.
+ W0401: Reimport.
+ E0406: Module import itself.
+ W0411: Import but unused.
+ E0413: ImportStmt is not at the top of the file
+ misc_checker
+ E0501: Line too long
28 changes: 14 additions & 14 deletions docs/reference/cli/kcl/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@
sidebar_position: 1
---

# 概览
# Overview

KCL 工具链是 KCL 语言的工具集合，旨在提升 KCL 的批量迁移、编写、编译和测试的效率。
KCL toolchain is a toolset of KCL language, which aims to improve the efficiency of batch migration, writing, compiling and testing of KCL.

| 类别 | 工具名称 | 说明 |
| -------------- | --------------- | -------------------------------------------------------------------------------- |
| 主工具集 | **kcl** | kcl 命令行工具提供对基于 KCL 语言的配置编写、编译和测试。 |
| | kcl build | （未支持）kcl build 子命令提供对 KCL 代码的构建 |
| | kcl test | kcl 测试工具，对 KCL 的单元测试（未支持）及集成测试 |
| | kcl fmt | kcl-fmt 工具提供对 KCL 代码的格式化 |
| | kcl list | （目前为 kcl list-options 及 kcl list-attributes 子命令形态）kcl-list 工具解析 KCL 代码，并列表展示 option 参数/schema attributes 信息。 |
| 自动化工具集 | kcl-lint | kcl-lint 工具提供对 KCL 代码的 lint 检查和自动修复 |
| | kcl-doc | kcl-doc 工具提供对 KCL 代码的文档解析和生成 |
| | kcl-fmt | 等同于 kcl fmt 子命令 |
| ide 插件集 | IntelliJ IDEA KCL 插件 | 提供 IntelliJ IDEA 平台的 KCL 编写、编译辅助 |
| | VS Code KCL 插件 | 提供 VS Code 平台的 KCL 编写、编译辅助 |
| | Name | Description |
| ---------------- | ------------------------ | ----------------------------------------------------------------------- |
| Main Toolset | **kcl** | Provide support for KCL in coding, compiling and testing |
| | kcl build | Build KCL code(not support) |
| | kcl test | KCL test tool, provide unit test(not support) and integration test |
| | kcl fmt | Formoat KCL code |
| | kcl list | Parses the KCL code and lists the option parameter/schema attributes information. （kcl list-options and kcl list-attributes)|
|Automation Toolset| kcl-lint | Check code style for KCL code |
| | kcl-doc | Parses the KCL code and generate documents |
| | kcl-fmt | Same as `kcl fmt` |
| IDE Plugin | IntelliJ IDEA KCL plugin | Provide KCL compilation and compilation assistance for IntelliJ IDEA |
| | VS Code KCL plugin | Provide KCL compilation and compilation assistance for VS Code |
53 changes: 24 additions & 29 deletions docs/reference/cli/kcl/test.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
sidebar_position: 5
---

# 测试工具
# Test Tool

## 简介
## Intro

KCL 支持通过内置的 `kcl-test` 命令行工具和 `testing` 包提供了简易的测试框架。每个目录下的全部 KCL 文件是一个测试整体，每个 `_test.k` 中 `Test` 开头的 schema 是一个测试案例。
KCL provides a simple testing framework through the built-in 'kcl-test' command line tool and 'testing' package. All KCL files in each directory are a set of tests, and each schema begins with 'Test' in each 'test.k' is a test case.

## 使用方式
## How to use

假设有 hello.k 文件，代码如下:
There is a KCL file `hello.k`:

```python
schema Person:
Expand All @@ -23,7 +23,7 @@ hello = Person {
}
```

构造 hello_test.k 测试文件，内容如下：
Build a test file `hello_test.k`:

```python
schema TestPerson:
Expand All @@ -40,17 +40,17 @@ schema TestPerson_ok:
assert a.age == 1
```

然后再目录下执行 `kcl-test` 命令:
Execute the following command:

```
$ kcl-test
ok /pkg/to/app [365.154142ms]
$
```

## 失败的测试
## Failed Test Case

将 hello_test.k 测试代码修改如下，构造失败的测试：
Modify `hello_test.k` to the following code to build failed test case:

```python
# Copyright 2021 The KCL Authors. All rights reserved.
Expand All @@ -71,7 +71,7 @@ schema TestPerson_ok:
assert a.age == 1
```

测试输出的错误如下：
Output:

```
$ kcl-test
Expand All @@ -91,9 +91,8 @@ FAIL /pkg/to/app [354.153775ms]
$
```

## 配置 option 参数

可以通过 testing 包指定面值类型的命令行参数：
## Option Args
Literal type command line arguments can be specified via the testing package:

```python
schema TestOptions:
Expand All @@ -116,9 +115,9 @@ schema TestOptions:
assert option("bool-false") == False
```

其中 `testing.arguments` 定义一组 key-value 参数，只有在当前的测试中有效。
`testing.arguments` defines a set of key-value arguments, valid only in the current test.

option 参数也可以从 settings.yaml 文件读取。假设有 `./settings.yaml` 文件如下：
The option arguments can also be load from the `settings.yaml`. There is a file `settings.yaml`:

```yaml
- key: app-name
Expand All @@ -129,7 +128,7 @@ option 参数也可以从 settings.yaml 文件读取。假设有 `./settings.yam
value: reg.docker.inc.com/test-image
```

然后可以通过 `testing.setting_file("./settings.yaml")` 方式配置参数。同时依然支持 `testing.arguments()` 覆盖配置文件中的参数：
Parameters can then be configured via `testing.setting_file("./settings.yaml")`. At the same time, `testing.arguments()` is still supported to override the parameters in the configuration file:

```py
schema TestOptions_setting:
Expand All @@ -140,25 +139,21 @@ schema TestOptions_setting:
assert option("file") == "settings.yaml"
```

testing.setting_file("settings.yaml") 则是从 yaml 文件加载对应的 key-value 参数。

## 测试插件

如果要测试的目录含有 `plugin.py` 和测试文件，自动切换到插件模式。那么将测试前设置 `KCL_PLUGINS_ROOT` 环境变量（不能再访问其他目录的插件）用于测试当前插件，测试完成之后恢复之前的 `KCL_PLUGINS_ROOT` 环境变量。
## Plugin Test

## 集成测试
Automatically switch to plugin mode if the directory to be tested contains `plugin.py` and test files. Then set the environment variable `KCL_PLUGINS_ROOT` before the test (plugins in other directories can no longer be accessed) to test the current plugin, and restore the previous `KCL_PLUGINS_ROOT` after the test is completed.

目录含有 `*.k` 时自动执行集成测试，如果有 `stdout.golden` 则验证输出的结果，如果有 `stderr.golden` 则验证错误。支持 `settings.yaml` 文件定义命令行参数。
## Integration Test

如果有 k 文件含有 `# kcl-test: ignore` 标注注释将忽略测试。
Automatically execute integration tests when the directory contains `*.k`. If there is `stdout.golden` then verify the output. If there is `stderr.golden` then verify the error. Supports the `settings.yaml` file to define command line arguments.

## 批量测试
## Batch Test

- `kcl-test path` 执行指定目录的测试, 当前目录可以省略该参数
- `kcl-test -run=regexp` 可以执行匹配模式的测试
- `kcl-test ./...` 递归执行子目录的单元测试
+ `kcl-test path` Execute the test of the specified directory. It can be omitted if is the current directory
+ `kcl-test -run=regexp` Execute the test which matches patterns
+ `kcl-test ./...` Execute unit tests recursively

## 命令行参数
## Args

```
$ kcl-test -h
Expand Down
20 changes: 10 additions & 10 deletions docs/reference/cli/kcl/vet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
sidebar_position: 4
---

# Validation 校验代码
# Validation Code

## 简介
## Intro

KCL 支持通过内置的 `kcl-vet` 命令行工具提供了基本的配置数据校验能力，可以编写 KCL schema 对输入的 JSON/YAML 格式文件进行类型以及数值的校验。
KCL supports basic configuration data verification capabilities through the built-in `kcl-vet` command line tool. You can write a KCL schema to verify the type and value of the input JSON/YAML files.

## 使用方式
## How to use

假设有 data.json 文件，代码如下:
There is a JSON format file `data.json`:

```json
{
Expand All @@ -28,7 +28,7 @@ KCL 支持通过内置的 `kcl-vet` 命令行工具提供了基本的配置数
}
```

构造 schema.k 校验文件，内容如下：
Build a validate KCL file `schema.k`:

```py
schema User:
Expand All @@ -47,22 +47,22 @@ schema Data:
value: str
```

在目录下执行如下命令
Execute the following command:

```
$ kcl-vet data.json schema.k
Validate succuss!
```

## 指定校验的 schema
## Specify the schema for validation

当教研的 KCL 文件中存在多个 schema 定义时，kcl-vet 工具会默认取第一个 schema 定义进行校验，如果需要指定校验的 schema，可以使用 `-d|--schema` 参数
When multiple schema definitions exist in the KCL file, by default, the `kcl-vet` tool will use the first schema to check. If you need to specify a schema for verification, you can use the '- d | -- schema' parameter

```
$kcl-vet data.json schema.k -d User
```

## 命令行参数
## Args

```
$ kcl-vet -h
Expand Down
3 changes: 3 additions & 0 deletions i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/cli/kcl/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# KCL 语言工具

KCL 作为 Kusion 的配置策略语言，不仅仅提供了 kcl 命令编译和执行配置程序，还提供了 fmt、lint、test、vet、docgen 等配套的辅助工具。
Loading