doc(book): describe the content of the Mabo.toml project files

Explain the need for the project files as well as all the possible
settings that can be set as content.

book/.vitepress/config.mts

@@ -85,6 +85,11 @@ export default defineConfig({
               { text: "Attributes", link: "/reference/schema/attributes" },
             ],
           },
+          {
+            text: "Project Files",
+            link: "/reference/project/",
+            items: [{ text: "Packages", link: "/reference/project/packages" }],
+          },
           {
             text: "Wire Format",
             link: "/reference/wire-format",

book/biome.json

@@ -11,6 +11,7 @@
 	},
 	"formatter": {
 		"indentStyle": "space",
-		"indentWidth": 2
+		"indentWidth": 2,
+		"lineWidth": 100
 	}
 }

book/src/reference/project/index.md

@@ -0,0 +1,15 @@
+# Project Files
+
+Each Mabo project is identified by a `Mabo.toml` file, usually located at the root of a project. For example, if this is a Rust project, the file would be located next to the `Cargo.toml`.
+
+Currently the project file is fairly basic, only allowing to define a single project with the schema files that it uses and some metadata.
+
+Future iterations will involve distribution and consumption of schema collections.
+
+The file must contain a single [package](./packages) declaration and at least have a name and list of files to include:
+
+```toml
+[package]
+name = "my_schemas"
+files = ["schemas/**/*.mabo"]
+```

book/src/reference/project/packages.md

@@ -0,0 +1,57 @@
+# Packages
+
+The `[package]` section defines a single collection of Mabo schema files. It defines additional metadata that will be useful in future features that involve sharing and consumption of schema collections.
+
+## `name`
+
+- Type `string`
+- **Required**
+
+The package name is an identifier used to refer to the package.
+
+## `description`
+
+- Type `string`
+- Optional
+
+The description is a short explanation about content of the package.
+
+Usually not too extensive, as the schema files can contain their own root-level description which will be carried over into the generated source code.
+
+## `license`
+
+- Type `string`
+- Optional
+
+The license under which a package is distributed. This is either a single [SPDX](https://spdx.org/) license or an expression that combines multiple licenses.
+
+Expressions are usually `AND` and `OR` which define how multiple licenses are to be combined. Further details about all the features of this expression language are available in the [SPDX Specification](https://spdx.github.io/spdx-spec/v2.3/).
+
+This is a simple example of the common combination of the `MIT` and `Apache-2.0` license:
+
+```toml
+[package]
+# ...
+license = "MIT OR Apache-2.0"
+```
+
+## `files`
+
+- Type `array<string>`
+- **Required**
+
+The list of files that form the collection of schemas making up the package content. These are [Glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) which allow for easy inclusion of whole file trees.
+
+For example, the likely most common pattern would be `schemas/**/*.mabo`. This pattern recurses into all the sub-directories of the `schemas` folder look for all files with the `.mabo` extension.
+
+::: info
+Regardless of the glob patterns defined, files are filtered by the `.mabo` extension in the end, as these are the only files considered valid schema files.
+:::
+
+This is an example described above as part of the `Mabo.toml` file:
+
+```toml
+[package]
+# ...
+files = ["schemas/**/*.mabo"]
+```

vscode-extension/biome.json

@@ -11,6 +11,7 @@
 	},
 	"formatter": {
 		"indentStyle": "space",
-		"indentWidth": 2
+		"indentWidth": 2,
+		"lineWidth": 100
 	}
 }

vscode-extension/package.json

@@ -122,7 +122,7 @@
     "esbuild": "esbuild src/extension.ts --outfile=dist/extension.js --external:vscode --format=cjs --platform=node --bundle",
     "watch": "bun run esbuild --watch",
     "build": "bun run esbuild --minify",
-    "lint": "biome check --apply src/**/*.ts",
+    "lint": "biome check --apply src/*.ts",
     "schemas": "js-yaml schemas/mabo.yaml > schemas/mabo.json",
     "syntaxes": "js-yaml syntaxes/mabo.tmLanguage.yaml > syntaxes/mabo.tmLanguage.json",
     "vscode:prepublish": "bun run schemas && bun run syntaxes && bun run build",

vscode-extension/schemas/mabo.json

@@ -11,56 +11,52 @@
   "definitions": {
     "Package": {
       "title": "Package",
-      "description": "The only fields required by Cargo are [`name`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) and\n[`version`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field). If publishing to a registry, the registry may\nrequire additional fields. See the notes below and [the publishing chapter](https://doc.rust-lang.org/cargo/reference/publishing.html) for requirements for publishing to [crates.io](https://crates.io/).\n",
+      "description": "Single named collection of schema files that form a package.",
       "type": "object",
       "required": [
         "name",
         "files"
       ],
       "properties": {
         "name": {
-          "description": "The package name is an identifier used to refer to the package. It is used\nwhen listed as a dependency in another package, and as the default name of\ninferred lib and bin targets.\n\nThe name must use only [alphanumeric](https://doc.rust-lang.org/std/primitive.char.html#method.is_alphanumeric) characters or `-` or `_`, and cannot be empty.\nNote that [`cargo new`](https://doc.rust-lang.org/cargo/commands/cargo-new.html) and [`cargo init`](https://doc.rust-lang.org/cargo/commands/cargo-init.html) impose some additional restrictions on\nthe package name, such as enforcing that it is a valid Rust identifier and not\na keyword. [crates.io](https://crates.io) imposes even more restrictions, such as\nenforcing only ASCII characters, not a reserved name, not a special Windows\nname such as \"nul\", is not too long, etc.\n",
-          "type": "string"
-        },
-        "authors": {
-          "$ref": "#/definitions/Authors"
+          "$ref": "#/definitions/Name"
         },
         "description": {
           "$ref": "#/definitions/Description"
         },
         "license": {
           "$ref": "#/definitions/License"
         },
-        "readme": {
-          "$ref": "#/definitions/Readme"
+        "files": {
+          "$ref": "#/definitions/Files"
         }
       }
     },
-    "Readme": {
-      "title": "Readme",
-      "description": "The `readme` field should be the path to a file in the package root (relative\nto this `Cargo.toml`) that contains general information about the package.\nThis file will be transferred to the registry when you publish. [crates.io](https://crates.io)\nwill interpret it as Markdown and render it on the crate's page.\n\n```toml\n[package]\n# ...\nreadme = \"README.md\"\n```\n\nIf no value is specified for this field, and a file named `README.md`,\n`README.txt` or `README` exists in the package root, then the name of that\nfile will be used. You can suppress this behavior by setting this field to\n`false`. If the field is set to `true`, a default value of `README.md` will\nbe assumed.\n",
+    "Name": {
+      "title": "Name",
+      "description": "The package name is an identifier used to refer to the package.",
       "type": "string"
     },
-    "Authors": {
-      "title": "Authors",
-      "description": "The `authors` field lists people or organizations that are considered the\n\"authors\" of the package. The exact meaning is open to interpretation — it may\nlist the original or primary authors, current maintainers, or owners of the\npackage. These names will be listed on the crate's page on\n[crates.io](https://crates.io). An optional email address may be included within angled\nbrackets at the end of each author.\n\n> **Note**: [crates.io](https://crates.io) requires at least one author to be listed.\n",
-      "type": "array",
-      "items": [
-        {
-          "type": "string",
-          "description": "The `authors` field lists people or organizations that are considered the\n\"authors\" of the package. The exact meaning is open to interpretation — it may\nlist the original or primary authors, current maintainers, or owners of the\npackage. These names will be listed on the crate's page on\n[crates.io](https://crates.io). An optional email address may be included within angled\nbrackets at the end of each author.\n\n> **Note**: [crates.io](https://crates.io) requires at least one author to be listed.\n"
-        }
-      ]
-    },
     "Description": {
       "title": "Description",
-      "description": "The description is a short blurb about the package. [crates.io](https://crates.io) will display\nthis with your package. This should be plain text (not Markdown).\n\n```toml\n[package]\n# ...\ndescription = \"A short description of my package\"\n```\n\n> **Note**: [crates.io](https://crates.io) requires the `description` to be set.\n",
+      "description": "The description is a short explanation about content of the package.",
       "type": "string"
     },
     "License": {
       "title": "License",
-      "description": "The `license` field contains the name of the software license that the package\nis released under.\n\n[crates.io](https://crates.io/) interprets the `license` field as an [SPDX 2.1 license\nexpression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). The name must be a known license\nfrom the [SPDX license list 3.6](https://github.com/spdx/license-list-data/tree/v3.6). Parentheses are not\ncurrently supported. See the [SPDX site](https://spdx.org/license-list) for more information.\n\nSPDX license expressions support AND and OR operators to combine multiple\nlicenses.\n\n```toml\n[package]\n# ...\nlicense = \"MIT OR Apache-2.0\"\n```\n\nUsing `OR` indicates the user may choose either license. Using `AND` indicates\nthe user must comply with both licenses simultaneously. The `WITH` operator\nindicates a license with a special exception. Some examples:\n\n* `MIT OR Apache-2.0`\n* `LGPL-2.1 AND MIT AND BSD-2-Clause`\n* `GPL-2.0+ WITH Bison-exception-2.2`\n\nIf a package is using a nonstandard license, then the `license-file` field may\nbe specified in lieu of the `license` field.\n",
+      "description": "The license defines the software license that this package is released under. It can be a single\n[SPDX](https://spdx.dev/) license, or multiple combined with `AND` and `OR` into an expression.\n\nSee the [SPDX Specification](https://spdx.github.io/spdx-spec/v2.3/) for more details about the exact expression\nsyntax.\n\n## Example\n\n```toml\n[package]\n# ...\nlicense = \"MIT OR Apache-2.0\"\n```\n",
       "type": "string"
+    },
+    "Files": {
+      "title": "Files",
+      "description": "List of files that make up the schema package. These are not regular file paths but glob patterns, meaning that\nfile trees can be defined in a consise way like `schemas/**/*.mabo`.\n\nRegardless of the [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) defined the final file list is\nalways filtered by the `.mabo` file extension.\n",
+      "type": "array",
+      "items": [
+        {
+          "type": "string",
+          "description": "List of files that make up the schema package. These are not regular file paths but glob patterns, meaning that\nfile trees can be defined in a consise way like `schemas/**/*.mabo`.\n\nRegardless of the [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) defined the final file list is\nalways filtered by the `.mabo` file extension.\n"
+        }
+      ]
     }
   }
 }

vscode-extension/schemas/mabo.yaml

@@ -29,7 +29,7 @@ definitions:
     type: string
   Description:
     title: Description
-    description: The description is a short description about the package.
+    description: The description is a short explanation about content of the package.
     type: string
   License:
     title: License

vscode-extension/src/extension.ts

@@ -44,12 +44,7 @@ export function activate(context: ExtensionContext) {
     },
   };
 
-  client = new LanguageClient(
-    "mabo",
-    "Mabo Schema",
-    serverOptions,
-    clientOptions,
-  );
+  client = new LanguageClient("mabo", "Mabo Schema", serverOptions, clientOptions);
 
   client.start();
 }