feat(docs): compilation report

CHANGELOG.md

@@ -71,6 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed links in Chinese translation: PR [#1206](https://github.com/tact-lang/tact/pull/1206)
 - Added a note on 255 being the maximum number of messages that can be sent during action phase: PR [#1237](https://github.com/tact-lang/tact/pull/1237)
 - Added onchain metadata creation for NFTs and Jettons to the cookbook: PR [#1236](https://github.com/tact-lang/tact/pull/1236)
+- Added a compilation-related page with the description of the compilation report: PR [#1309](https://github.com/tact-lang/tact/pull/1309)
 
 ### Release contributors
 

docs/astro.config.mjs

@@ -180,10 +180,11 @@ export default defineConfig({
 							label: 'Going places',
 							translations: { 'zh-CN': '前往各地' },
 							attrs: { class: 'sidebar-separator' },
-							link: 'book/deploy#',
+							link: 'book/compile#',
 						},
-						{ slug: 'book/deploy' },
+						{ slug: 'book/compile' },
 						{ slug: 'book/debug' },
+						{ slug: 'book/deploy' },
 						{ slug: 'book/upgrades' },
 						{ slug: 'book/import' },
 						{ slug: 'book/config' },

docs/src/content/docs/book/compile.mdx

@@ -0,0 +1,116 @@
+---
+title: Compilation
+description: "How to compile Tact smart contracts, as well as details on the build artifacts that are provided."
+prev:
+  link: /book/message-mode
+  label: Message mode
+---
+
+import { Badge } from '@astrojs/starlight/components';
+
+:::note
+
+  This page is still being written as per [#1136](https://github.com/tact-lang/tact/issues/1136).
+
+:::
+
+The Tact compiler can produce various outputs, ranging from the [BoC](/book/cells#cells-boc) of the compiled contract to various supplementary files, such as the [compilation report](#report) or the [contract package](/ref/evolution/otp-006), which is the JSON file with the `.pkg` extension that one can use to [verify the smart contract's origin](https://verifier.ton.org).
+
+With the proper [configuration settings](/book/config), you can customize the behavior of the compiler to skip the generation of some or all the [build artifacts](#artifacts), and even control the addition or exclusion of [getters for supported interfaces](/book/contracts#interfaces).
+
+Since the Tact compiler is a command-line program, some of the configuration settings can be set directly. When inside a folder with a Tact-based project, such as one created using the [Blueprint](https://github.com/ton-org/blueprint) or from the [tact-template](https://github.com/tact-lang/tact-template), refer to the `npx tact --help{:shell}` command for further instructions.
+
+## Build artifacts {#artifacts}
+
+A number of build artifacts can be produced per compilation of each contract. Some of the artifacts can be omitted using [configuration settings](/book/config).
+
+The location of the artifacts depends on the [`output`](/book/config#projects-output) field of the [`tact.config.json`](/book/config). In [Blueprint][bp]-based projects, `output` is not used and all generated files are always placed in `build/ProjectName/`.
+
+### Compilation report, `.md` {#report}
+
+Every markdown compilation report first features the name of the contract that it was prepared for and then the byte size of the contract compiled to [BoC](/book/cells#cells-boc).
+
+The following sub-headings describe the respective sections of the `.md` report.
+
+#### Structures {#structures}
+
+<Badge text="Written as '# Types' prior to Tact 1.6" variant="tip" size="medium"/><p/>
+
+The first section introduces the present structures, i.e. some of the [composite types](/book/types#composite-types), [Structs and Messages](/book/structs-and-messages) that are declared or imported directly in the contract code, as well as those exposed from the Core standard library.
+
+Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective [TL-B schemas][tlb] and signatures.
+
+For example:
+
+```md
+Total structures: 10
+
+### StateInit
+TL-B: `_ code:^cell data:^cell = StateInit`
+Signature: `StateInit{code:^cell,data:^cell}`
+
+### StdAddress
+TL-B: `_ workchain:int8 address:uint256 = StdAddress`
+Signature: `StdAddress{workchain:int8,address:uint256}`
+
+...etc.
+```
+
+[TL-B schema][tlb] of each [Message][message] contains its opcode, which is handy for looking up the auto-generated opcodes as well as confirming the [manually provided ones](/book/structs-and-messages#message-opcodes). For example:
+
+```md
+### Deploy
+TL-B: `deploy#946a98b6 queryId:uint64 = Deploy`
+Signature: `Deploy{queryId:uint64}`
+
+### Seven
+TL-B: `seven#00000007 = Seven`
+Signature: `Seven{}`
+```
+
+#### Get methods {#getters}
+
+This section specifies the number of available get methods or [getter functions](/book/functions#getter-functions) and outlines them with their argument names, if any.
+
+For example:
+
+```md
+Total get methods: 2
+
+## lshift
+Argument: x
+
+## gas
+```
+
+There, the `lshift(){:tact}` getter has a single argument `x`, whereas the `gas(){:tact}` getter has no arguments.
+
+#### Exit codes {#exit-codes}
+
+This section lists all default [exit codes](/book/exit-codes), as well as those generated from the error messages of the [`require(){:tact}`](/ref/core-debug#require), along with those messages for your convenience.
+
+For example:
+
+```md
+* 2: Stack underflow
+* 3: Stack overflow
+...etc.
+* 135: Code of a contract was not found
+* 42933: Hey, I'm the error message of require()
+```
+
+There, the [exit codes](/book/exit-codes) in the range from $0$ to $255$ are those reserved by TON Blockchain or Tact compiler, while the exit code of $42933$ is produced by the respective call to the [`require(){:tact}`](/ref/core-debug#require) function.
+
+#### Trait inheritance diagram {#trait-diagram}
+
+This section shows a [Mermaid][mm] diagram of inherited [traits](/book/types#traits), including the [`BaseTrait{:tact}`](/ref/core-base).
+
+#### Contract inheritance diagram {#contract-diagram}
+
+This section shows a [Mermaid][mm] diagram of [contract](/book/contracts) dependencies, i.e. the [traits](/book/types#traits) that it depends upon.
+
+[struct]: /book/structs-and-messages#structs
+[message]: /book/structs-and-messages#messages
+
+[tlb]: https://docs.ton.org/develop/data-formats/tl-b-language
+[mm]: https://mermaid.js.org/

docs/src/content/docs/book/debug.mdx

@@ -1,6 +1,6 @@
 ---
-title: Debugging Tact contracts
-description: "Various ways to reveal problems or bugs in Tact code"
+title: Debugging and testing
+description: "Various ways to reveal and prevent problems or bugs in Tact code"
 ---
 
 import { LinkCard, CardGrid, Steps, Tabs, TabItem } from '@astrojs/starlight/components';

docs/src/content/docs/book/deploy.mdx

@@ -1,9 +1,6 @@
 ---
 title: Deployment
 description: "Common ways to deploy Tact contracts to testnet or mainnet of TON Blockchain"
-prev:
-  link: /book/message-mode
-  label: Message mode
 ---
 
 Tact Deployer is a small library that integrates with [TON Verifier](https://verifier.ton.org) that allows you to deploy your contracts safely using your favorite wallet without needing to manage keys or deploy contracts manually. Tact Deployer also automatically verifies your contract's source code and you can be sure that your compiler is not compromised.

docs/src/content/docs/ref/core-common.mdx

@@ -98,7 +98,7 @@ Field     | Type                  | Description
 `bounced` | [`Bool{:tact}`][bool] | [Bounced](https://ton.org/docs/learn/overviews/addresses#bounceable-vs-non-bounceable-addresses) flag of the incoming message.
 `sender`  | [`Address{:tact}`][p] | Internal address of the sender on the TON blockchain.
 `value`   | [`Int{:tact}`][int]   | Amount of [nanoToncoins](/book/integers#nanotoncoin) in a message.
-`raw`     | [`Slice{:tact}`][slice]   | The remainder of the message as a [`Slice{:tact}`][slice]. It follows [internal message layout](https://docs.ton.org/develop/smart-contracts/messages#message-layout) of TON starting from the destination [`Address{:tact}`][p] (`dest:MsgAddressInt ` in [TL-B notation](https://docs.ton.org/develop/data-formats/tl-b-language)).
+`raw`     | [`Slice{:tact}`][slice]   | The remainder of the message as a [`Slice{:tact}`][slice]. It follows [internal message layout](https://docs.ton.org/develop/smart-contracts/messages#message-layout) of TON starting from the destination [`Address{:tact}`][p] (`MsgAddressInt` in [TL-B notation](https://docs.ton.org/develop/data-formats/tl-b-language)).
 
 Usage example:
 

src/generator/writeReport.ts

@@ -9,41 +9,45 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) {
     const w = new Writer();
     const abi = JSON.parse(pkg.abi) as ContractABI;
     w.write(`
-        # TACT Compilation Report
+        # Tact compilation report
         Contract: ${pkg.name}
-        BOC Size: ${Buffer.from(pkg.code, "base64").length} bytes
+        BoC Size: ${Buffer.from(pkg.code, "base64").length} bytes
     `);
     w.append();
 
-    // Types
-    w.write(`# Types`);
-    w.write("Total Types: " + abi.types!.length);
+    // Structures
+    w.write(`## Structures (Structs and Messages)`);
+    w.write("Total structures: " + abi.types!.length);
     w.append();
     for (const t of abi.types!) {
         const tt = getType(
             ctx,
             t.name.endsWith("$Data") ? t.name.slice(0, -5) : t.name,
         );
-        w.write(`## ${t.name}`);
-        w.write(`TLB: \`${tt.tlb!}\``);
+        w.write(`### ${t.name}`);
+        w.write(`TL-B: \`${tt.tlb!}\``);
         w.write(`Signature: \`${tt.signature!}\``);
         w.append();
     }
 
     // Get methods
-    w.write(`# Get Methods`);
-    w.write("Total Get Methods: " + abi.getters!.length);
+    w.write(`## Get methods`);
+    w.write("Total get methods: " + abi.getters!.length);
     w.append();
     for (const t of abi.getters!) {
         w.write(`## ${t.name}`);
-        for (const arg of t.arguments!) {
-            w.write(`Argument: ${arg.name}`);
+        if (t.arguments!.length === 0) {
+            w.write(`This getter has no arguments`);
+        } else {
+            for (const arg of t.arguments!) {
+                w.write(`Argument: ${arg.name}`);
+            }
         }
         w.append();
     }
 
-    // Error Codes
-    w.write(`# Error Codes`);
+    // Exit codes
+    w.write(`## Exit codes`);
     Object.entries(abi.errors!).forEach(([t, abiError]) => {
         w.write(`* ${t}: ${abiError.message}`);
     });
@@ -52,8 +56,8 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) {
     const t = getType(ctx, pkg.name);
     const writtenEdges: Set<string> = new Set();
 
-    // Trait Inheritance Diagram
-    w.write(`# Trait Inheritance Diagram`);
+    // Trait inheritance diagram
+    w.write(`## Trait inheritance diagram`);
     w.append();
     w.write("```mermaid");
     w.write("graph TD");
@@ -75,8 +79,8 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) {
 
     writtenEdges.clear();
 
-    // Contract Dependency Diagram
-    w.write(`# Contract Dependency Diagram`);
+    // Contract dependency diagram
+    w.write(`## Contract dependency diagram`);
     w.append();
     w.write("```mermaid");
     w.write("graph TD");