From 57f41d25a22810e5c06172fdd5ec48bb310c1d63 Mon Sep 17 00:00:00 2001 From: seo1nk Date: Tue, 28 Nov 2023 03:04:35 +0900 Subject: [PATCH 1/6] doc(ja): translate `Architecture` into Japanese --- .../docs/ja/internals/architecture.mdx | 160 ++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 website/src/content/docs/ja/internals/architecture.mdx diff --git a/website/src/content/docs/ja/internals/architecture.mdx b/website/src/content/docs/ja/internals/architecture.mdx new file mode 100644 index 000000000000..64b87aa1392b --- /dev/null +++ b/website/src/content/docs/ja/internals/architecture.mdx @@ -0,0 +1,160 @@ +--- +title: Architecture +description: Biome の内部動作 +--- + +このドキュメントでは Biome の内部機能の一部と、それらがプロジェクト内でどのように利用されているかについて説明します。 + +## パーサーと CST + +パーサーのアーキテクチャは [rowan] の内部フォークによって更新されています。 +これは [Green and Red tree] パターンを実装したライブラリです。 + +CST (Concrete Syntax Tree) は、 トリビアを含むプログラム内のすべての情報を追跡する AST (Abstract Syntax Tree) によく似たデータ構造です。 + +**トリビア** は、プログラムを実行するために不可欠な情報を含んでいます: +- スペース +- タブ +- コメント + +トリビアは各ノードに関連付けられ、それぞれのノードは前方トリビアと後方トリビアを持ちます。 +コードを左から右へ読む場合、前方トリビアはキーワード前に、後方トリビアはキーワード後に現れるものです。 + +前方トリビアと後方トリビアは、それぞれ以下のように分類されます: +- **前方トリビア**: トークン/キーワードまでのすべてのトリビア（改行を含む） +- **後方トリビア**: 次の改行までのすべてのトリビア（その改行自体は含まない） + + +次の JavaScript のスニペットでは、`// comment 1` はトークン `;` に対する後方トリビアで、`// comment 2` はキーワード `const` に対する前方トリビアです。 +下部は、Biome によって表現された CST の簡略版です: + +```js +const a = "foo"; // comment 1 +// comment 2 +const b = "bar"; +``` + +``` +0: JS_MODULE@0..55 + ... + 1: SEMICOLON@15..27 ";" [] [Whitespace(" "), Comments("// comment 1")] + 1: JS_VARIABLE_STATEMENT@27..55 + ... + 1: CONST_KW@27..45 "const" [Newline("\n"), Comments("// comment 2"), Newline("\n")] [Whitespace(" ")] + 3: EOF@55..55 "" [] [] +``` + +設計上、CST は直接アクセスできないようになっていますが、言語の文法から自動生成されたAPIによって、開発者は Red tree からその情報を取得できます。 + + +#### 頑健かつ回復可能なパーサー + +CST を構築するためには、パーサーはエラーに対して頑健かつ回復可能である必要があります: +- 頑健性: 言語の構文エラーに遭遇した後でも解析を再開できるパーサー +- 回復可能性: エラーが発生した箇所を理解でき、正しい情報を生成することで解析を再開できるパーサー + +パーサーの回復可能な部分は科学的なルールに基づかず、厳格なルールは存在しません。 +これは、解析対象やエラー発生箇所によって予測された方法で、パーサーが自己回復できる可能性があることを示します。 + +パーサーは誤った構文を処理することから利用者を保護するため、 `Bogus` ノードも使用します。 +このノードは、構文エラーに起因する破損コードを装飾するのに利用されます。 + +以下の例では `while` の括弧が抜けていますが、パーサーは上手く回復し、適切な CST でコードを表現できています。 +ループの条件や括弧が欠落しているとしてマークされ、かつコードブロックは正しく解析されます: + + +```js +while {} +``` + +``` +JsModule { + interpreter_token: missing (optional), + directives: JsDirectiveList [], + items: JsModuleItemList [ + JsWhileStatement { + while_token: WHILE_KW@0..6 "while" [] [Whitespace(" ")], + l_paren_token: missing (required), + test: missing (required), + r_paren_token: missing (required), + body: JsBlockStatement { + l_curly_token: L_CURLY@6..7 "{" [] [], + statements: JsStatementList [], + r_curly_token: R_CURLY@7..8 "}" [] [], + }, + }, + ], + eof_token: EOF@8..8 "" [] [], +} +``` + +これは、解析中に発生したエラーです: + +``` +main.tsx:1:7 parse ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + ✖ expected `(` but instead found `{` + + > 1 │ while {} + │ ^ + + ℹ Remove { +``` + +次のスニペットは同様ではありません。 +パーサーは回復フェーズの間に構文を適切に理解することができず、`Bogus` ノードに頼って一部の構文をエラーとしてマークする必要があります。 +`JsBogusStatement` に注目してください: + +```js +function} +``` + +``` +JsModule { + interpreter_token: missing (optional), + directives: JsDirectiveList [], + items: JsModuleItemList [ + TsDeclareFunctionDeclaration { + async_token: missing (optional), + function_token: FUNCTION_KW@0..8 "function" [] [], + id: missing (required), + type_parameters: missing (optional), + parameters: missing (required), + return_type_annotation: missing (optional), + semicolon_token: missing (optional), + }, + JsBogusStatement { + items: [ + R_CURLY@8..9 "}" [] [], + ], + }, + ], + eof_token: EOF@9..9 "" [] [], +} +``` + +これは、解析フェーズ中に発生したエラーです: + +``` +main.tsx:1:9 parse ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + ✖ expected a name for the function in a function declaration, but found none + + > 1 │ function} + │ ^ +``` + +## フォーマッター (WIP) + +## リンター (WIP) + +## デーモン (WIP) + +Biome は、タスク実行のためにサーバークライアントアーキテクチャを使用しています。 + +[daemon] は、Biome をバッググラウンドで起動し、エディターや CLI からのリクエストを処理するために長時間実行されるサーバーです。 + + +[rowan]: https://github.com/rust-analyzer/rowan +[Green and Red tree]: https://learn.microsoft.com/en-us/archive/blogs/ericlippert/persistence-facades-and-roslyns-red-green-trees +[daemon]: https://ja.wikipedia.org/wiki/%E3%83%87%E3%83%BC%E3%83%A2%E3%83%B3_(%E3%82%BD%E3%83%95%E3%83%88%E3%82%A6%E3%82%A7%E3%82%A2) From c2bc7b9d4da406deaa431a787d3bbb04f8d02b37 Mon Sep 17 00:00:00 2001 From: seo1nk Date: Tue, 28 Nov 2023 03:20:01 +0900 Subject: [PATCH 2/6] doc(ja): fix some translation --- website/src/content/docs/ja/internals/architecture.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/src/content/docs/ja/internals/architecture.mdx b/website/src/content/docs/ja/internals/architecture.mdx index 64b87aa1392b..6562d7c380a2 100644 --- a/website/src/content/docs/ja/internals/architecture.mdx +++ b/website/src/content/docs/ja/internals/architecture.mdx @@ -53,14 +53,14 @@ CST を構築するためには、パーサーはエラーに対して頑健か - 頑健性: 言語の構文エラーに遭遇した後でも解析を再開できるパーサー - 回復可能性: エラーが発生した箇所を理解でき、正しい情報を生成することで解析を再開できるパーサー -パーサーの回復可能な部分は科学的なルールに基づかず、厳格なルールは存在しません。 +パーサーの回復可能性は科学的なルールに基づかず、厳格なルールは存在しません。 これは、解析対象やエラー発生箇所によって予測された方法で、パーサーが自己回復できる可能性があることを示します。 パーサーは誤った構文を処理することから利用者を保護するため、 `Bogus` ノードも使用します。 このノードは、構文エラーに起因する破損コードを装飾するのに利用されます。 以下の例では `while` の括弧が抜けていますが、パーサーは上手く回復し、適切な CST でコードを表現できています。 -ループの条件や括弧が欠落しているとしてマークされ、かつコードブロックは正しく解析されます: +ループの条件や括弧が欠落しているとしてマークされ、そしてコードブロックは正しく解析されます: ```js @@ -102,7 +102,7 @@ main.tsx:1:7 parse ━━━━━━━━━━━━━━━━━━━━ ``` 次のスニペットは同様ではありません。 -パーサーは回復フェーズの間に構文を適切に理解することができず、`Bogus` ノードに頼って一部の構文をエラーとしてマークする必要があります。 +パーサーは回復フェーズ中に構文を適切に理解することができず、`Bogus` ノードに頼って一部の構文をエラーとしてマークする必要があります。 `JsBogusStatement` に注目してください: ```js @@ -152,7 +152,7 @@ main.tsx:1:9 parse ━━━━━━━━━━━━━━━━━━━━ Biome は、タスク実行のためにサーバークライアントアーキテクチャを使用しています。 -[daemon] は、Biome をバッググラウンドで起動し、エディターや CLI からのリクエストを処理するために長時間実行されるサーバーです。 +[daemon] は、エディターや CLI からのリクエストを処理するために Biome をバッググラウンドで起動し、長時間実行されるサーバーです。 [rowan]: https://github.com/rust-analyzer/rowan From 62727e6644db7389c60ea65ea568730db5e6f795 Mon Sep 17 00:00:00 2001 From: seo1nk <39511416+seo1nk@users.noreply.github.com> Date: Tue, 28 Nov 2023 21:36:02 +0900 Subject: [PATCH 3/6] Update website/src/content/docs/ja/internals/architecture.mdx Co-authored-by: Takayuki Maeda --- website/src/content/docs/ja/internals/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/content/docs/ja/internals/architecture.mdx b/website/src/content/docs/ja/internals/architecture.mdx index 6562d7c380a2..4554d72a928f 100644 --- a/website/src/content/docs/ja/internals/architecture.mdx +++ b/website/src/content/docs/ja/internals/architecture.mdx @@ -3,7 +3,7 @@ title: Architecture description: Biome の内部動作 --- -このドキュメントでは Biome の内部機能の一部と、それらがプロジェクト内でどのように利用されているかについて説明します。 +このドキュメントでは、 Biome の内部機能の一部と、それらがプロジェクト内でどのように利用されているかについて説明します。 ## パーサーと CST From a5bfd6ebada7bdbd920c27b88ebaa757abb2c1ea Mon Sep 17 00:00:00 2001 From: seo1nk <39511416+seo1nk@users.noreply.github.com> Date: Tue, 28 Nov 2023 21:36:33 +0900 Subject: [PATCH 4/6] Update website/src/content/docs/ja/internals/architecture.mdx Co-authored-by: Takayuki Maeda --- website/src/content/docs/ja/internals/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/content/docs/ja/internals/architecture.mdx b/website/src/content/docs/ja/internals/architecture.mdx index 4554d72a928f..2343df009e6e 100644 --- a/website/src/content/docs/ja/internals/architecture.mdx +++ b/website/src/content/docs/ja/internals/architecture.mdx @@ -59,7 +59,7 @@ CST を構築するためには、パーサーはエラーに対して頑健か パーサーは誤った構文を処理することから利用者を保護するため、 `Bogus` ノードも使用します。 このノードは、構文エラーに起因する破損コードを装飾するのに利用されます。 -以下の例では `while` の括弧が抜けていますが、パーサーは上手く回復し、適切な CST でコードを表現できています。 +以下の例では、 `while` の括弧が抜けていますが、パーサーは上手く回復し、適切な CST でコードを表現できています。 ループの条件や括弧が欠落しているとしてマークされ、そしてコードブロックは正しく解析されます: From 74adc0cb0f1a47d20c815b9402b9246080269fd8 Mon Sep 17 00:00:00 2001 From: seo1nk <39511416+seo1nk@users.noreply.github.com> Date: Tue, 28 Nov 2023 21:36:45 +0900 Subject: [PATCH 5/6] Update website/src/content/docs/ja/internals/architecture.mdx Co-authored-by: Takayuki Maeda --- website/src/content/docs/ja/internals/architecture.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/src/content/docs/ja/internals/architecture.mdx b/website/src/content/docs/ja/internals/architecture.mdx index 2343df009e6e..1f164e69e187 100644 --- a/website/src/content/docs/ja/internals/architecture.mdx +++ b/website/src/content/docs/ja/internals/architecture.mdx @@ -56,8 +56,8 @@ CST を構築するためには、パーサーはエラーに対して頑健か パーサーの回復可能性は科学的なルールに基づかず、厳格なルールは存在しません。 これは、解析対象やエラー発生箇所によって予測された方法で、パーサーが自己回復できる可能性があることを示します。 -パーサーは誤った構文を処理することから利用者を保護するため、 `Bogus` ノードも使用します。 -このノードは、構文エラーに起因する破損コードを装飾するのに利用されます。 +パーサーは誤った構文を処理することからコンシューマーを保護するため、 `Bogus` ノードも使用します。 +このノードは、構文エラーに起因する破損したコードを装飾するのに利用されます。 以下の例では、 `while` の括弧が抜けていますが、パーサーは上手く回復し、適切な CST でコードを表現できています。 ループの条件や括弧が欠落しているとしてマークされ、そしてコードブロックは正しく解析されます: From a97335400b135a851d0221e4a4cc117fe5816c5e Mon Sep 17 00:00:00 2001 From: seo1nk <39511416+seo1nk@users.noreply.github.com> Date: Wed, 29 Nov 2023 14:49:25 +0900 Subject: [PATCH 6/6] Update website/src/content/docs/ja/internals/architecture.mdx Co-authored-by: Takayuki Maeda --- website/src/content/docs/ja/internals/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/content/docs/ja/internals/architecture.mdx b/website/src/content/docs/ja/internals/architecture.mdx index 1f164e69e187..623ffe7b4680 100644 --- a/website/src/content/docs/ja/internals/architecture.mdx +++ b/website/src/content/docs/ja/internals/architecture.mdx @@ -1,5 +1,5 @@ --- -title: Architecture +title: アーキテクチャ description: Biome の内部動作 ---