From d99ad6eca703ef4067c8dfc048b8ea064f8fc949 Mon Sep 17 00:00:00 2001 From: Chris Olszewski Date: Tue, 26 Aug 2025 09:36:04 -0400 Subject: [PATCH] docs: add top level crate documentation --- crates/turbo-trace/src/lib.rs | 4 ++++ crates/turborepo-api-client/src/lib.rs | 4 ++++ crates/turborepo-cache/src/lib.rs | 6 ++++++ crates/turborepo-ci/src/lib.rs | 7 ++++++- crates/turborepo-dirs/src/lib.rs | 4 ++++ crates/turborepo-env/src/lib.rs | 2 ++ crates/turborepo-errors/src/lib.rs | 5 +++++ crates/turborepo-fixed-map/src/lib.rs | 5 +++++ crates/turborepo-frameworks/src/lib.rs | 4 ++++ crates/turborepo-fs/src/lib.rs | 4 ++++ crates/turborepo-globwalk/src/lib.rs | 5 +++++ crates/turborepo-graph-utils/src/lib.rs | 4 ++++ crates/turborepo-lockfiles/src/lib.rs | 10 ++++++++++ crates/turborepo-microfrontends/src/lib.rs | 9 +++++++++ crates/turborepo-pidlock/src/lib.rs | 4 ++++ crates/turborepo-repository/src/lib.rs | 8 ++++++++ crates/turborepo-task-id/src/lib.rs | 14 ++++++++++++++ crates/turborepo-unescape/src/lib.rs | 3 +++ crates/turborepo-vercel-api-mock/src/lib.rs | 2 ++ 19 files changed, 103 insertions(+), 1 deletion(-) diff --git a/crates/turbo-trace/src/lib.rs b/crates/turbo-trace/src/lib.rs index f6bc4c0efabeb..24ff33e0c698f 100644 --- a/crates/turbo-trace/src/lib.rs +++ b/crates/turbo-trace/src/lib.rs @@ -1,3 +1,7 @@ +//! Utilities for tracing and analyzing import dependencies in JavaScript and +//! TypeScript files. Provides functionality to discover and track module +//! imports across a codebase. Used for `turbo boundaries` + #![deny(clippy::all)] mod import_finder; mod tracer; diff --git a/crates/turborepo-api-client/src/lib.rs b/crates/turborepo-api-client/src/lib.rs index 19c8ec2e53485..5c60235a7173f 100644 --- a/crates/turborepo-api-client/src/lib.rs +++ b/crates/turborepo-api-client/src/lib.rs @@ -1,3 +1,7 @@ +//! HTTP client for interacting with the Remote Cache API. +//! Provides authentication, caching, and telemetry endpoints for Remote Cache +//! operations. By default configured for Vercel API + #![feature(error_generic_member_access)] #![feature(assert_matches)] #![deny(clippy::all)] diff --git a/crates/turborepo-cache/src/lib.rs b/crates/turborepo-cache/src/lib.rs index 0de5ae0a99fa0..70798bbe16e38 100644 --- a/crates/turborepo-cache/src/lib.rs +++ b/crates/turborepo-cache/src/lib.rs @@ -1,3 +1,9 @@ +//! Cache management for task outputs +//! Provides local and remote caching capabilities and a "multiplexed" cache +//! which operates over both. When both are in use local is preferred and remote +//! writes are done asynchronously. Under the hood cache artifacts are stored a +//! gzipped tarballs. + #![feature(error_generic_member_access)] #![feature(assert_matches)] #![feature(box_patterns)] diff --git a/crates/turborepo-ci/src/lib.rs b/crates/turborepo-ci/src/lib.rs index 511b40df9d8bb..01ce4d9a7f3ce 100644 --- a/crates/turborepo-ci/src/lib.rs +++ b/crates/turborepo-ci/src/lib.rs @@ -1,4 +1,9 @@ -#![deny(clippy::all)] +//! CI/CD vendor detection and vendor-specific behavior +//! Detects CI vendors and provides: +//! - Env var containing current commit SHA +//! - Env var containing current branch +//! - Env var containing current user +//! - Any vendor specific behavior for producing well formatted logs mod vendor_behavior; mod vendors; diff --git a/crates/turborepo-dirs/src/lib.rs b/crates/turborepo-dirs/src/lib.rs index f9d439446be76..c8c28b9cfa02b 100644 --- a/crates/turborepo-dirs/src/lib.rs +++ b/crates/turborepo-dirs/src/lib.rs @@ -1,3 +1,7 @@ +//! Platform-specific directory utilities +//! A small patch on top of `dirs_next` that makes use of turbopath and respects +//! `VERCEL_CONFIG_DIR_PATH` as an override. + use dirs_next::config_dir as dirs_config_dir; use thiserror::Error; use turbopath::{AbsoluteSystemPathBuf, PathError}; diff --git a/crates/turborepo-env/src/lib.rs b/crates/turborepo-env/src/lib.rs index 29fa9709b2e28..7354c69ccc465 100644 --- a/crates/turborepo-env/src/lib.rs +++ b/crates/turborepo-env/src/lib.rs @@ -1,3 +1,5 @@ +//! Environment variable filtering for tasks and hashing for cache keys. + #![deny(clippy::all)] use std::{ diff --git a/crates/turborepo-errors/src/lib.rs b/crates/turborepo-errors/src/lib.rs index de8075c7a36b1..65311859ada19 100644 --- a/crates/turborepo-errors/src/lib.rs +++ b/crates/turborepo-errors/src/lib.rs @@ -1,3 +1,8 @@ +//! Diagnostic utilities to preserve source for more actionable error messages +//! Used in conjunction with `miette` to include source snippets in errors. +//! Any parsing of files should attempt to produce value of `Spanned` so if +//! we need to reference where T came from the span is available. + use std::{ fmt::Display, iter, diff --git a/crates/turborepo-fixed-map/src/lib.rs b/crates/turborepo-fixed-map/src/lib.rs index 61017209de24f..9c9b6e554e30f 100644 --- a/crates/turborepo-fixed-map/src/lib.rs +++ b/crates/turborepo-fixed-map/src/lib.rs @@ -1,3 +1,8 @@ +//! A specialized map data structure with fixed keys determined at construction. +//! Provides thread-safe, one-time initialization of values for predefined keys. +//! This is exclusively used so we can lazily load `turbo.json`, cache the +//! results, and return a reference to the loaded `turbo.json`. + #![deny(clippy::all)] use std::sync::OnceLock; diff --git a/crates/turborepo-frameworks/src/lib.rs b/crates/turborepo-frameworks/src/lib.rs index eda929593441e..824f2d5db9017 100644 --- a/crates/turborepo-frameworks/src/lib.rs +++ b/crates/turborepo-frameworks/src/lib.rs @@ -1,3 +1,7 @@ +//! Framework detection and configuration inference for Turborepo. +//! Automatically identifies JavaScript frameworks and what environment +//! variables impact it. + use std::{collections::HashMap, sync::OnceLock}; use serde::Deserialize; diff --git a/crates/turborepo-fs/src/lib.rs b/crates/turborepo-fs/src/lib.rs index aa45871e2440f..2f4b62af0f470 100644 --- a/crates/turborepo-fs/src/lib.rs +++ b/crates/turborepo-fs/src/lib.rs @@ -1,3 +1,6 @@ +//! File system utilities for used by Turborepo. +//! At the moment only used for `turbo prune` to copy over package directories. + #![deny(clippy::all)] use std::{ @@ -5,6 +8,7 @@ use std::{ io, }; +// `fs_err` preserves paths in the error messages unlike `std::fs` use fs_err as fs; use ignore::WalkBuilder; use turbopath::{AbsoluteSystemPath, AnchoredSystemPathBuf}; diff --git a/crates/turborepo-globwalk/src/lib.rs b/crates/turborepo-globwalk/src/lib.rs index 9b1331298c705..9eed4c436f1d6 100644 --- a/crates/turborepo-globwalk/src/lib.rs +++ b/crates/turborepo-globwalk/src/lib.rs @@ -1,3 +1,8 @@ +//! Glob pattern matching and directory walking +//! This is a layer on top of `wax` that performs some corrections to user +//! provided globs as well as escaping characters that `wax` considers special, +//! but we do not support. + #![feature(assert_matches)] #![deny(clippy::all)] diff --git a/crates/turborepo-graph-utils/src/lib.rs b/crates/turborepo-graph-utils/src/lib.rs index 22a8ef18d5cea..f1f3f2df7199f 100644 --- a/crates/turborepo-graph-utils/src/lib.rs +++ b/crates/turborepo-graph-utils/src/lib.rs @@ -1,3 +1,7 @@ +//! Additional utilities to be used with `petgraph` +//! Provides transitive closure calculation and cycle detection with cut +//! candidates to break cycles + mod walker; use std::{collections::HashSet, fmt::Display, hash::Hash}; diff --git a/crates/turborepo-lockfiles/src/lib.rs b/crates/turborepo-lockfiles/src/lib.rs index 2fd99c3c3ae02..77568104da7e1 100644 --- a/crates/turborepo-lockfiles/src/lib.rs +++ b/crates/turborepo-lockfiles/src/lib.rs @@ -1,3 +1,13 @@ +//! Package manager lockfile parsing, analysis, and serialization +//! +//! Parsing and analysis are used to track which external packages a workspace +//! package depends on. This allows Turborepo to not perform a global +//! invalidation on a lockfile change, but instead only the packages which +//! depend on the changed external packages. +//! +//! Serialization is exclusively used by `turbo prune` and is far more error +//! prone than deserialization and analysis. + #![deny(clippy::all)] // the pest proc macro adds an empty doc comment. #![allow(clippy::empty_docs)] diff --git a/crates/turborepo-microfrontends/src/lib.rs b/crates/turborepo-microfrontends/src/lib.rs index 2b50b517334bb..d94e5ff7ce3ef 100644 --- a/crates/turborepo-microfrontends/src/lib.rs +++ b/crates/turborepo-microfrontends/src/lib.rs @@ -1,3 +1,12 @@ +//! `@vercel/microfrontends` configuration parsing +//! This crate is only concerned with parsing the minimal amount of information +//! that Turborepo needs to correctly invoke a local proxy. This allows this +//! crate to avoid being kept in lock step with `@vercel/microfrontends`. +//! +//! The information required for the local proxy is the default package and the +//! package names that are a part of microfrontend and their development task +//! names. + #![feature(assert_matches)] #![deny(clippy::all)] mod configv1; diff --git a/crates/turborepo-pidlock/src/lib.rs b/crates/turborepo-pidlock/src/lib.rs index 0ea5d94c952cc..bf0e90a97416c 100644 --- a/crates/turborepo-pidlock/src/lib.rs +++ b/crates/turborepo-pidlock/src/lib.rs @@ -1,3 +1,7 @@ +//! Process ID lock file management used by the daemon +//! Forked from the `pidlock` crate in order to add Windows support and the +//! ability to query the owner of the pidlock. + #![deny(clippy::all)] #![feature(assert_matches)] diff --git a/crates/turborepo-repository/src/lib.rs b/crates/turborepo-repository/src/lib.rs index de6b660438d60..af0e2ec859435 100644 --- a/crates/turborepo-repository/src/lib.rs +++ b/crates/turborepo-repository/src/lib.rs @@ -1,3 +1,11 @@ +//! Repository detection and package discovery for Turborepo. +//! Handles monorepo structure, package graph construction, and dependency +//! analysis. +//! +//! Primarily in a separate crate from the rest of the logic so the +//! `@turbo/repository` NPM package can avoid depending on the entire Turborepo +//! binary. + #![feature(assert_matches)] #![feature(error_generic_member_access)] #![allow(clippy::result_large_err)] diff --git a/crates/turborepo-task-id/src/lib.rs b/crates/turborepo-task-id/src/lib.rs index 93a6313ddb20c..b1166f98a0faa 100644 --- a/crates/turborepo-task-id/src/lib.rs +++ b/crates/turborepo-task-id/src/lib.rs @@ -1,3 +1,17 @@ +//! Identifiers for Turborepo tasks +//! +//! Consists of `TaskName`s and `TaskId`s +//! `TaskId`s are fully qualified tasks that include the package and the task +//! name e.g. `turbo#build` is the `build` task for the `turbo` package. +//! +//! `TaskName`s are what we accept as a user input for a "task". +//! They do not need to be fully qualified, but can be. +//! For example `dependsOn` takes `TaskName`s which allows for +//! `"dependsOn": ["build", "schema#gen"]` where the package's build task is run +//! along with the `schema` package's `gen` task. +//! +//! All `TaskId`s are valid `TaskName`s, but not vice versa. + use std::{ borrow::{Borrow, Cow}, fmt, diff --git a/crates/turborepo-unescape/src/lib.rs b/crates/turborepo-unescape/src/lib.rs index cd472ee3c7196..f44227ca03bcc 100644 --- a/crates/turborepo-unescape/src/lib.rs +++ b/crates/turborepo-unescape/src/lib.rs @@ -1,3 +1,6 @@ +//! Marker type for biome parsed JSON strings which are not escaped +//! See https://github.com/biomejs/biome/issues/1596 for more information + use std::{ fmt::{self, Display}, ops::{Deref, DerefMut}, diff --git a/crates/turborepo-vercel-api-mock/src/lib.rs b/crates/turborepo-vercel-api-mock/src/lib.rs index 0e6f20accbe76..2f787bd978bc1 100644 --- a/crates/turborepo-vercel-api-mock/src/lib.rs +++ b/crates/turborepo-vercel-api-mock/src/lib.rs @@ -1,3 +1,5 @@ +//! Mock server implementation for a subset of the Vercel API. + #![deny(clippy::all)] use std::{collections::HashMap, fs::OpenOptions, io::Write, net::SocketAddr, sync::Arc};