docs: Polish pass. (#99)

* First pass.

* Update readme.

* Fix icons.

* Add ts line.

* Fixes.

* Bump versions.

.moon/workspace.yml

@@ -1,7 +1,7 @@
 $schema: '../schemas/workspace.json'
 
 node:
-  version: '16.14.0'
+  version: '16.15.0'
   packageManager: 'yarn'
   yarn:
     version: '3.2.0'
@@ -10,3 +10,6 @@ node:
 projects:
   runtime: 'packages/runtime'
   website: 'website'
+
+vcs:
+  defaultBranch: 'origin/master'

.yarn/versions/13e7d2f6.yml

@@ -0,0 +1,9 @@
+releases:
+  "@moonrepo/cli": patch
+  "@moonrepo/core-linux-x64-gnu": patch
+  "@moonrepo/core-linux-x64-musl": patch
+  "@moonrepo/core-macos-x64": patch
+  "@moonrepo/core-windows-x64-msvc": patch
+
+declined:
+  - website

README.md

@@ -1,11 +1,66 @@
 # moon
 
-> Currently a work in progress!
-
 moon is a repository *m*anagement, *o*rganization, *o*rchestration, and *n*otification tool for
 JavaScript based projects, written in Rust. Many of the concepts within moon are heavily inspired
 from Bazel and other popular build systems, but tailored for the JavaScript ecosystem.
 
 - [Documentation](https://moonrepo.dev)
 - [Contributing](./CONTRIBUTING.md)
 - [Code of conduct](./CODE_OF_CONDUCT.md)
+
+## Why use moon?
+
+Working in the JavaScrip ecosystem can be very involved, especially when it comes to managing a
+repository effectively. Which package manager to use? Which Node.js version to use? How to import
+node modules? How to build packages? So on and so forth. moon aims to streamline this entire process
+and provide a first-class developer experience.
+
+- **Adopt incrementally** - moon at its core has been designed to be adopted incrementally and is
+  _not_ an "all at once adoption". Migrate project-by-project, or task-by-task, it's up to you!
+- **Avoid scripts soup** - `package.json` scripts can become unwieldy, very quickly. No more
+  duplicating the same script into every package, or reverse-engineering which root scripts to use.
+  With moon, all you need to know is the project ID, and a task ID.
+- **Ensure correct versions** - Whether it's Node.js or npm, ensure the same version of each tool is
+  the same across _every_ developer's environment. No more wasted hours of debugging.
+- **Automation built-in** - When applicable, moon will automatically install `node_modules`, or sync
+  package dependencies, or even sync TypeScript project references.
+- And the amazing list of features below!
+
+## Features
+
+> Not all features are currently supported, view the documentation for an accurate list!
+
+#### Management
+
+- **Smart hashing** - Collects inputs from multiple sources to ensure builds are deterministic and
+  reproducible.
+- **Remote caching** - Persists builds, hashes, and caches between teammates and CI/CD environments.
+- **Integrated toolchain** - Automatically downloads and installs explicit versions of Node.js and
+  other tools for consistency.
+- **Multi-platform** - Runs on common development platforms: Linux, MacOS, and Windows.
+
+#### Organization
+
+- **Project graph** - Generates a project graph for dependency and dependent relationships.
+- **Project boundaries** - Enforces boundaries to eliminate cycles and reduce indirection.
+- **Dependency workspaces** - Works alongside package manager workspaces so that projects have
+  distinct dependency trees.
+- **Ownership metadata** - Declare an owner, maintainers, support channels, and more, for LDAP or
+  another integration.
+
+#### Orchestration
+
+- **Dependency graph** - Generates a dependency graph to increase performance and reduce workloads.
+- **Action runner** - Executes actions in parallel and in order using a thread pool and our
+  dependency graph.
+- **Action distribution** - Distributes actions across multiple machines to increase throughput.
+- **Incremental builds** - With our smart hashing, only rebuild projects that have been touched
+  since the last build.
+
+#### Notification
+
+- **Flakiness detection** - Reduce flaky builds with automatic retries and passthrough settings.
+- **Webhook events** - Receive a webhook for every event in the pipeline. Useful for metrics
+  gathering.
+- **Terminal notifications** - Receives notifications in your chosen terminal when builds are
+  successful... or are not.

crates/config/src/workspace/node.rs

@@ -5,7 +5,7 @@ use std::env;
 use validator::{Validate, ValidationError};
 
 fn default_node_version() -> String {
-    env::var("MOON_NODE_VERSION").unwrap_or_else(|_| String::from("16.14.0"))
+    env::var("MOON_NODE_VERSION").unwrap_or_else(|_| String::from("16.15.0"))
 }
 
 fn default_npm_version() -> String {

crates/config/src/workspace/vcs.rs

@@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize};
 use validator::Validate;
 
 fn default_branch_default() -> String {
-    String::from("origin/master")
+    String::from("master")
 }
 
 #[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]

crates/config/templates/workspace.yml

@@ -54,6 +54,6 @@ vcs:
   manager: 'git'
 
   # OPTIONAL: The default branch (master/main/trunk) in the repository for comparing the
-  # local branch against. For git, this is is typically "origin/master" or "origin/main",
+  # local branch against. For git, this is is typically "master" or "main",
   # and must include the remote prefix (before /). For svn, this should always be "trunk".
-  defaultBranch: 'origin/master'
+  defaultBranch: 'master'

website/docs/commands/run.mdx

@@ -20,10 +20,14 @@ $ moon run :lint
 
 - `<target>` - [Target](../concepts/target) to run.
 - `[-- <args>]` - Additional arguments to
-  [pass to the underlying command](#passing-arguments-to-the-underlying-command).
+  [pass to the underlying command](../run-task#passing-arguments-to-the-underlying-command).
 
 ### Options
 
+- `--dependents` - Run downstream dependent targets (of the same task ID) as well.
+
+#### Affected
+
 - `--affected` - Only run target if affected by changed files, _otherwise_ will always run.
 - `--status <type>` - Filter affected based on a change status.
   - Types: all (default), added, deleted, modified, staged, unstaged, untracked

website/docs/concepts/project.mdx

@@ -22,16 +22,17 @@ Lastly, a project ID can be paired with a task ID to create a [target](./target)
 ## Configuration
 
 Projects can be configured with an optional [`project.yml`](../config/project) in the project root,
-or through the [`.moon/project.yml`](../config/global-project) which applies to all projects.
+or through the optional [`.moon/project.yml`](../config/global-project) which applies to all
+projects.
 
 ### `package.json`
 
 A moon project _does not require_ a `package.json`, but when one exists, the following functionality
 is enabled.
 
-- Dependency versions are included when computing cache keys.
-- Depended on projects ([`dependsOn`](../config/project#dependson)) are mapped as npm/pnpm/yarn
-  workspace dependencies (when applicable).
+- Dependency versions are included when computing cache keys and hashes.
+- Depended on projects ([`dependsOn`](../config/project#dependson)) are mapped as workspace
+  dependencies (when applicable).
 
 ### `tsconfig.json`
 

website/docs/concepts/target.mdx

@@ -46,9 +46,10 @@ $ moon run :lint
 
 > Only available when configuring a task.
 
-When you want to run a task for each project in your [`dependsOn`](../config/project#dependson)
-list, you can utilize the `^` scope. This will be expanded to _all_ depended on projects. If you do
-not want all projects, then you'll need to explicitly define them using identifiers.
+When you want to include a reference for each project in your
+[`dependsOn`](../config/project#dependson) list, you can utilize the `^` scope. This will be
+expanded to _all_ depended on projects. If you do not want all projects, then you'll need to
+explicitly define them.
 
 ```yaml title="project.yml"
 dependsOn:

website/docs/concepts/token.mdx

@@ -37,6 +37,7 @@ fileGroups:
     - 'src'
     - 'tests'
     - 'scripts'
+    - '*.config.js'
 
 # Configured as
 tasks:

website/docs/config/workspace.mdx

@@ -112,15 +112,15 @@ node:
   addEnginesConstraint: true
 ```
 
-For example, say our Node.js version is "16.14.0", and when we execute a run process through the
+For example, say our Node.js version is "16.15.0", and when we execute a run process through the
 `moon` binary, it will update the root `package.json` with the below. We pin a fixed version to
 ensure other Node.js processes outside of our toolchain are utilizing the same version.
 
 ```json title="package.json"
 {
 	// ...
 	"engines": {
-		"node": "16.14.0"
+		"node": "16.15.0"
 	}
 }
 ```
@@ -274,10 +274,10 @@ vcs:
 ### `defaultBranch`
 
 Defines the default upstream branch (master/main/trunk) in the repository for comparing differences
-against. For git, this is typically "origin/master" (default) or "origin/main", and must include the
-remote prefix (before /). For svn, this should always be "trunk".
+against. For git, this is typically "master" (default) or "main", and must include the remote prefix
+(before /). For svn, this should always be "trunk".
 
 ```yaml title=".moon/workspace.yml" {2}
 vcs:
-  defaultBranch: 'origin/master'
+  defaultBranch: 'master'
 ```

website/docs/create-project.mdx

@@ -48,7 +48,7 @@ A project can be configured in 1 of 2 ways:
 Both config files are optional, and can be used separately or together, the choice is yours!
 
 Now let's continue with our client and server example above. If we wanted to configure both
-projects, and defined config that's also share between the 2, we could do something like the
+projects, and define config that's also shared between the 2, we could do something like the
 following:
 
 <Tabs
@@ -87,10 +87,7 @@ tasks:
 tasks:
 	build:
 		command: 'babel'
-		args:
-			- 'src'
-			- '--out-dir'
-			- 'build'
+		args: 'src --out-dir build'
 		inputs:
 			- 'src/**/*'
 		outputs:
@@ -105,35 +102,26 @@ tasks:
 	format:
 		command: 'prettier'
 		args: '--write .'
-		inputs:
-			- 'src/**/*'
 	lint:
 		command: 'eslint'
 		args: '--no-error-on-unmatched-pattern .'
-		inputs:
-			- 'src/**/*'
 	test:
 		command: 'jest'
 		args: '--passWithNoTests .'
-		inputs:
-			- 'src/**/*'
-			- 'tests/**/*'
 	typecheck:
 		command: 'tsc'
 		args: '--build'
-		inputs:
-			- 'src/**/*'
-			- 'types/**/*'
 ```
 
 </TabItem>
 </Tabs>
 
 ### Adding optional metadata
 
-When utilizing moon in a large monorepo or organization, ownership becomes very important. To combat
-this problem, moon supports the [`project`](./config/project#project) field within a project's
-[`project.yml`](./config/project) config.
+When utilizing moon in a large monorepo or organization, ownership becomes very important, but also
+difficult to maintain. To combat this problem, moon supports the
+[`project`](./config/project#project) field within a project's [`project.yml`](./config/project)
+config.
 
 This field is _optional_ by default, but when defined it provides metadata about the project,
 specifically around team ownership, which developers maintain the project, where to discuss it, and

website/docs/create-task.mdx

@@ -9,18 +9,21 @@ import NextSteps from '@site/src/components/NextSteps';
 
 <HeaderLabel text="10 min" />
 
-The primary feature of moon is a build system, and for it to operate in any capacity, it requires
+The primary focus of moon is a build system, and for it to operate in any capacity, it requires
 tasks to run. In moon, a task is an npm binary or system command that is ran as a child process
 within the context of a project (is the current working directory). Tasks are defined per project
 with [`project.yml`](./config/project), or inherited by all projects with
 [`.moon/project.yml`](./config/global-project).
 
 ## Configuring a task
 
-Most, if not all projects, utilize the same core tasks: linting, testing, code formatting, and
+Most -- if not all projects -- utilize the same core tasks: linting, testing, code formatting, and
 type-checking. Because these are so universal, let's implement the type-checking task in
 [`.moon/project.yml`](./config/global-project), which will be inherited by all projects.
 
+> This section assumes that `typescript` is installed as a dependency in your root, and that all
+> `tsconfig.json` files have been setup correctly.
+
 Begin by adding a `typecheck` field to the [`tasks`](./config/project#tasks) setting. This task will
 use [TypeScript](https://www.typescriptlang.org/) and run `tsc` under the hood, since we defined the
 [`command`](./config/project#command) setting.
@@ -122,12 +125,22 @@ tasks:
 			- 'dts'
 ```
 
+```json title="tsconfig.json"
+{
+	# ...
+	"compilerOptions": {
+		# ...
+		"outDir": "dts"
+	}
+}
+```
+
 ## Using file groups
 
 Once you're familiar with configuring tasks, you may notice certain inputs being repeated
 constantly, like source files, test files, and configuration. To reduce the amount of boilerplate
-required, moon provides a feature known as file groups, which enables grouping of similar file types
-within a project using file glob patterns or literal file paths.
+required, moon provides a feature known as [file groups](./concepts/file-group), which enables
+grouping of similar file types within a project using file glob patterns or literal file paths.
 
 File groups are defined with the [`fileGroups`](./config/project#filegroups) setting, which maps a
 list of file paths/globs to a group, like so.

website/docs/guides/ci.mdx

@@ -32,16 +32,17 @@ basis through the [`runInCI`](../config/project#runinci) option.
 ```yaml
 tasks:
   dev:
-    command: webpack
-    args: server
+    command: 'webpack'
+    args: 'server'
     options:
       runInCI: false
 ```
 
 :::caution
 
-This option _must_ be set to false for tasks that spawn a long running process, like HTTP or
-development servers. To help mitigate this, tasks named `start` or `serve` are false by default.
+This option _must_ be set to false for tasks that spawn a long-running or never-ending process, like
+HTTP or development servers. To help mitigate this, tasks named `start` or `serve` are false by
+default.
 
 :::
 
@@ -55,7 +56,7 @@ into other distribution channels.
 With that being said, the following examples can be referenced for setting up moon and its CI
 workflow in popular services. The examples assume a
 [package script named `moon`](../install#adding-a-package-script) and are using Yarn 3, but feel
-free to replace with your chosen package manager.
+free to replace with your chosen setup.
 
 <Tabs groupId="ci-env">
 <TabItem value="github" label="GitHub">
@@ -74,7 +75,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
-      - run: yarn install
+      - run: yarn install --immutable
       - run: yarn moon ci
 ```
 
@@ -85,7 +86,7 @@ jobs:
 steps:
   - label: 'CI'
     commands:
-      - yarn install
+      - yarn install --immutable
       - yarn moon ci
 ```
 
@@ -136,13 +137,13 @@ configured [`vcs.defaultBranch`](../config/workspace#defaultbranch) (master, mai
 of these can be customized with the `--base` and `--head` options respectively.
 
 ```shell
-$ moon ci --base another-branch --head <SHA>
+$ moon ci --base <BRANCH> --head <SHA>
 ```
 
 ## Parallelizing tasks
 
 If your CI environment supports sharding across multiple jobs, then you can utilize moon's built in
-parallelism, by passing `--jobTotal` and `--job` options. The `--jobTotal` option is an integer of
+parallelism by passing `--jobTotal` and `--job` options. The `--jobTotal` option is an integer of
 the total number of jobs available, and `--job` is the current index (0 based) amongst the total.
 
 When these options are passed, moon will only run affected [targets](../concepts/target) based on