1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7
8. 8
9. 9
10. 10
11. 11
12. 12
13. 13
14. 14
15. 15
16. 16
17. 17
18. 18
19. 19
20. 20
21. 21
22. 22
23. 23
24. 24
25. 25
26. 26
27. 27
28. 28
29. 29
30. 30
31. 31
32. 32
33. 33
34. 34
35. 35
36. 36
37. 37
38. 38
39. 39
40. 40
41. 41
42. 42
43. 43
44. 44
45. 45
46. 46
47. 47
48. 48
49. 49
50. 50
51. 51
52. 52
53. 53
54. 54
55. 55
56. 56
57. 57
58. 58
59. 59
60. 60
61. 61
62. 62
63. 63
64. 64
65. 65
66. 66
67. 67
68. 68
69. 69
70. 70
71. 71
72. 72
73. 73
74. 74
75. 75
76. 76
77. 77
78. 78
79. 79
80. 80
81. 81
82. 82
83. 83
84. 84
85. 85
86. 86
87. 87

<!--
SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com>
SPDX-License-Identifier: Apache-2.0
-->

[dprint]: https://dprint.dev/
[reuse-tool]: https://github.com/fsfe/reuse-tool

# Development Guide

This guide is for whom touches this project's codebase.

## Requirements

This project uses below software tools:

- [Node.js](https://nodejs.org) Active LTS and npm for building, testing and publishing.
- [Gleam](https://gleam.run/) v1.x for testing.
- [dprint][dprint] v0.x for code formatting.
- [reuse][reuse-tool] v4 or later for copyright and license information checking.

You can install these tools other than reuse tool, by using [ASDF](https://asdf-vm.com/) or [mise](https://mise.jdx.dev/). See [`.tool-versions`](../.tool-versions) for more specific versions.

## Source code and build process

Source code is located under `src/` directory, written in TypeScript.

Those files are compiled to JavaScript by TypeScript Compiler (tsc).
You can manually compile them by running:

```
$ npm run build
```

Compiled JavaScript files are located under `esm/es2022/` directory.
That directory is ignored from VCS, and included in published tarball.

To clean the compiled files, simply delete `esm/` directory.

## Testing

Plugin's source code is type-checked by TypeScript Compiler.
If there is a type error, `npm run build` exits with non-zero code.

To test the plugin's behavior, run unit tests by running:

```
$ npm test
```

If you don't want the test runner to go interactive mode, set `CI=true` and run the command:

```
$ CI=true npm test
```

Test files are inside [`tests/`](../tests/) directory, grouped into sub-directories.
Each sub-directory simulates real-world usecase by having `gleam.toml` and `src/` files, and an unit test invokes Rollup/Vite using those files.

Do not write flaky tests: keep assertions simple and avoid timer-based wait functions as much as possible.

## Code formatting

Source code in this project should adhere to style guide defined in [`.editorconfig` file](../.editorconfig).
Use of text editor supporting EditorConfig or EditorConfig plugin is preferable.

Source code in this project should be consistently formatted using [dprint][dprint].

```
$ dprint fmt
```

**Run the above command before creating a commit**.

## Copyright and license annotation

Every checked-in files SHOULD have proper copyright and license annotation.
Annotations MUST conform [REUSE v3.3 Specification](https://reuse.software/spec-3.3/).

To check the annotations, run:

```
$ reuse lint
```

The above command requires [reuse tool][reuse-tool] to be installed on your system.
**Run the above command before creating a commit**.