M0.3: xtask ci, layers, assets, cleanroom, ui-licences, dev, fixtures

layers reads cargo metadata and rejects upward, sideways and tool-crate
dependencies and any path to Tauri below L6. assets checks ASSETS.md rows
and rejects committed fonts. cleanroom rejects JetBrains copyright notices,
exported IDE configuration and .idea/.jar/.icls files. deny.toml mirrors
the licence allow list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-13 20:32:00 +02:00
parent ec1c72d9ac
commit 3bd95343cc
8 changed files with 1130 additions and 2 deletions

27
deny.toml Normal file
View file

@ -0,0 +1,27 @@
# cargo deny configuration. Only the licence check is part of the quality
# gate (`cargo deny check licenses`, run by `cargo xtask ci`).
#
# The allow list mirrors AGENTS.md. Adding a licence outside it is the
# owner's decision. Keep it in step with xtask/src/licences.rs.
[graph]
all-features = true
[licenses]
confidence-threshold = 0.9
unused-allowed-license = "allow"
allow = [
"MIT",
"MIT-0",
"Apache-2.0",
"Apache-2.0 WITH LLVM-exception",
"BSD-2-Clause",
"BSD-3-Clause",
"0BSD",
"ISC",
"Zlib",
"MPL-2.0",
]
[licenses.private]
ignore = true

137
xtask/src/assets.rs Normal file
View file

@ -0,0 +1,137 @@
//! `cargo xtask assets`: every asset file in the repository must have a row
//! in `ASSETS.md`, and font files must not be committed at all.
//!
//! An asset is any file under `assets/` except placeholders and licence texts,
//! plus any file elsewhere whose extension marks it as an image, icon, font,
//! sound or video.
use std::collections::BTreeSet;
use std::fs;
use crate::util::{TaskResult, repo_files, repo_root};
/// Extensions of image, icon, sound and video files.
const MEDIA_EXTENSIONS: &[&str] = &[
"png", "jpg", "jpeg", "gif", "webp", "bmp", "ico", "icns", "svg", "cur", "ani", "tif", "tiff",
"avif", "mp3", "wav", "ogg", "mp4", "webm", "mov",
];
/// Extensions of font files, which are never committed.
const FONT_EXTENSIONS: &[&str] = &["ttf", "otf", "woff", "woff2", "eot", "ttc"];
/// Runs the check on the repository.
///
/// # Errors
/// Fails with one line per unlisted asset or committed font.
pub fn check_repo() -> TaskResult {
let root = repo_root()?;
let table =
fs::read_to_string(root.join("ASSETS.md")).map_err(|e| format!("ASSETS.md: {e}"))?;
let files = repo_files(&root)?;
let problems = check(&files, &table);
if problems.is_empty() {
let count = files.iter().filter(|f| is_asset(f)).count();
println!("assets: {count} asset files, all attributed");
Ok(())
} else {
Err(format!("asset problems:\n {}", problems.join("\n ")))
}
}
/// Checks a file list against the contents of `ASSETS.md`.
pub fn check(files: &[String], assets_md: &str) -> Vec<String> {
let listed = listed_paths(assets_md);
let mut problems = Vec::new();
for file in files {
if FONT_EXTENSIONS.contains(&extension(file).as_str()) {
problems.push(format!(
"{file}: font files are never committed; use an @fontsource package"
));
} else if is_asset(file) && !listed.contains(file.as_str()) {
problems.push(format!("{file}: no row in ASSETS.md"));
}
}
problems
}
/// Whether a repository path counts as an asset that needs attribution.
pub fn is_asset(path: &str) -> bool {
let name = path.rsplit('/').next().unwrap_or(path);
if path.starts_with("assets/") {
let lower = name.to_ascii_lowercase();
let licence_text = lower.starts_with("license")
|| lower.starts_with("licence")
|| lower.starts_with("notice")
|| lower.starts_with("readme");
return name != ".gitkeep" && !licence_text;
}
let ext = extension(path);
MEDIA_EXTENSIONS.contains(&ext.as_str()) || FONT_EXTENSIONS.contains(&ext.as_str())
}
/// Lower-case extension of a path, or an empty string.
fn extension(path: &str) -> String {
let name = path.rsplit('/').next().unwrap_or(path);
name.rsplit_once('.')
.map(|(_, e)| e.to_ascii_lowercase())
.unwrap_or_default()
}
/// Paths in the first column of the table rows of `ASSETS.md`, with
/// surrounding backticks removed.
pub fn listed_paths(assets_md: &str) -> BTreeSet<&str> {
assets_md
.lines()
.map(str::trim)
.filter(|l| l.starts_with('|'))
.filter_map(|l| l.trim_start_matches('|').split('|').next())
.map(|cell| cell.trim().trim_matches('`'))
.filter(|cell| !cell.is_empty() && *cell != "Asset" && !cell.starts_with("---"))
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
const TABLE: &str = "| Asset | Author | Source | Licence | Notes |\n|---|---|---|---|---|\n| `assets/icons/lt-class.svg` | A | original | MIT OR Apache-2.0 | |\n";
fn files(list: &[&str]) -> Vec<String> {
list.iter().map(|s| s.to_string()).collect()
}
#[test]
fn listed_assets_pass() {
let f = files(&[
"assets/icons/lt-class.svg",
"assets/icons/.gitkeep",
"assets/icons/LICENSE.txt",
"src/main.rs",
]);
assert!(check(&f, TABLE).is_empty());
}
#[test]
fn unlisted_assets_fail_anywhere() {
let f = files(&["assets/icons/lt-trait.svg", "ui/src/logo.png"]);
let p = check(&f, TABLE);
assert_eq!(p.len(), 2);
assert!(p[0].contains("lt-trait.svg"));
assert!(p[1].contains("logo.png"));
}
#[test]
fn fonts_always_fail() {
let f = files(&["ui/public/Inter.woff2"]);
assert!(check(&f, TABLE)[0].contains("font files are never committed"));
}
#[test]
fn header_and_separator_are_not_paths() {
let listed = listed_paths(TABLE);
assert_eq!(
listed.into_iter().collect::<Vec<_>>(),
vec!["assets/icons/lt-class.svg"]
);
}
}

178
xtask/src/cleanroom.rs Normal file
View file

@ -0,0 +1,178 @@
//! `cargo xtask cleanroom`: guards the clean-room rule of AGENTS.md.
//!
//! Fails on files that carry a JetBrains copyright notice, on files that look
//! like exported JetBrains configuration (keymaps, colour schemes, live
//! templates, inspection profiles, `.idea` project files) and on archives that
//! could hold IDE internals (`.jar`, `.icls`, `.jfr`).
//!
//! The checker's own source necessarily contains the patterns it looks for,
//! so this file is exempt from the content scan.
use std::fs;
use crate::util::{TaskResult, repo_files, repo_root};
/// This file, exempt from the content scan because it holds the patterns.
const SELF_PATH: &str = "xtask/src/cleanroom.rs";
/// Extensions that are rejected outright.
const FORBIDDEN_EXTENSIONS: &[&str] = &["jar", "icls", "jfr", "ipr", "iml", "iws"];
/// Markers of exported IDE configuration XML, matched case-sensitively.
/// A file is flagged when it contains any one of them.
const CONFIG_MARKERS: &[&str] = &[
"<keymap version=",
"<templateSet group=",
"<component name=\"InspectionProjectProfileManager\"",
"<component name=\"ProjectRootManager\"",
"<profile version=\"1.0\">",
"<scheme name=\"",
];
/// Largest file scanned for text, in bytes; larger files are skipped.
const MAX_SCAN_BYTES: u64 = 4 * 1024 * 1024;
/// Runs the check on the repository.
///
/// # Errors
/// Fails with one line per suspicious file.
pub fn check_repo() -> TaskResult {
let root = repo_root()?;
let files = repo_files(&root)?;
let mut problems = Vec::new();
for file in &files {
problems.extend(check_path(file));
if file == SELF_PATH {
continue;
}
let path = root.join(file);
let small = fs::metadata(&path)
.map(|m| m.len() <= MAX_SCAN_BYTES)
.unwrap_or(false);
if !small {
continue;
}
if let Ok(bytes) = fs::read(&path) {
problems.extend(check_content(file, &String::from_utf8_lossy(&bytes)));
}
}
if problems.is_empty() {
println!(
"cleanroom: {} files scanned, nothing suspicious",
files.len()
);
Ok(())
} else {
Err(format!("clean-room problems:\n {}", problems.join("\n ")))
}
}
/// Checks a repository path by name alone.
pub fn check_path(path: &str) -> Vec<String> {
let mut problems = Vec::new();
if path.split('/').any(|part| part == ".idea") {
problems.push(format!("{path}: .idea project files are never committed"));
}
let ext = path
.rsplit_once('.')
.map(|(_, e)| e.to_ascii_lowercase())
.unwrap_or_default();
if FORBIDDEN_EXTENSIONS.contains(&ext.as_str()) {
problems.push(format!(
"{path}: .{ext} files may contain JetBrains material"
));
}
problems
}
/// Whether a line holds a copyright notice in the name of JetBrains: a
/// marker (`copyright`, `(c)` or `©`), then only further markers, years and
/// punctuation, then `jetbrains`, in any case. Mentions such as "JetBrains
/// copyright notices" don't match.
pub fn is_jetbrains_notice(line: &str) -> bool {
let lower = line.to_lowercase();
["copyright", "(c)", "©"].iter().any(|marker| {
lower.match_indices(marker).any(|(at, word)| {
let mut rest = lower.get(at + word.len()..).unwrap_or_default();
loop {
let trimmed = rest.trim_start_matches(|c: char| {
c.is_ascii_digit() || matches!(c, ' ' | '-' | ',')
});
let stripped = trimmed
.strip_prefix("copyright")
.or_else(|| trimmed.strip_prefix("(c)"))
.or_else(|| trimmed.strip_prefix('©'));
match stripped {
Some(next) => rest = next,
None => return trimmed.starts_with("jetbrains"),
}
}
})
})
}
/// Checks the text of one file.
pub fn check_content(path: &str, text: &str) -> Vec<String> {
let mut problems = Vec::new();
for (n, line) in text.lines().enumerate() {
if is_jetbrains_notice(line) {
problems.push(format!("{path}:{}: JetBrains copyright notice", n + 1));
}
}
for marker in CONFIG_MARKERS {
if text.contains(marker) {
problems.push(format!(
"{path}: looks like exported JetBrains configuration ({marker})"
));
}
}
problems
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn flags_copyright_notices() {
let text = "// Copyright 2000-2026 JetBrains s.r.o. and contributors.\nfn main() {}";
assert_eq!(check_content("a.rs", text).len(), 1);
assert!(is_jetbrains_notice("Copyright (c) JetBrains s.r.o."));
assert!(is_jetbrains_notice("(c) 2010-2024 JetBrains"));
assert!(is_jetbrains_notice("Copyright © 2024 JETBRAINS"));
}
#[test]
fn ignores_mentions_of_notices() {
assert!(!is_jetbrains_notice("fails on JetBrains copyright notices"));
assert!(!is_jetbrains_notice(
"cleanroom check for JetBrains copyright notices"
));
}
#[test]
fn allows_trademark_disclaimers_and_plain_mentions() {
let text = "PhpStorm and JetBrains are trademarks of JetBrains s.r.o.\nCopyright (c) 2026 Daniel Diekert\nNever launch a JetBrains IDE.";
assert!(check_content("NOTICE", text).is_empty());
}
#[test]
fn flags_exported_configuration() {
assert_eq!(
check_content("k.xml", "<keymap version=\"1\" name=\"x\">").len(),
1
);
assert_eq!(
check_content("t.xml", "<templateSet group=\"PHP\">").len(),
1
);
}
#[test]
fn flags_forbidden_paths() {
assert_eq!(check_path(".idea/workspace.xml").len(), 1);
assert_eq!(check_path("lib/platform.jar").len(), 1);
assert_eq!(check_path("themes/dark.icls").len(), 1);
assert!(check_path("crates/engine/src/lib.rs").is_empty());
}
}

420
xtask/src/layers.rs Normal file
View file

@ -0,0 +1,420 @@
//! `cargo xtask layers`: enforces the crate layering of docs/architecture.md.
//!
//! Every workspace crate declares `[package.metadata.lutra] layer = N` (or
//! `"tool"`). A crate may depend only on workspace crates of a lower layer,
//! must not depend on tool crates outside dev-dependencies, and nothing below
//! layer 6 may reach a Tauri package through its normal dependencies.
use std::collections::{BTreeMap, BTreeSet, VecDeque};
use serde_json::Value;
use crate::util::{TaskResult, capture, repo_root};
/// The layer at and above which crates may depend on Tauri.
const UI_LAYER: u8 = 6;
/// Layer of a workspace crate.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Layer {
/// A shipped crate in layer `N`.
Level(u8),
/// A development tool (`testkit`, `xtask`), outside the layering.
Tool,
}
/// Kind of a dependency edge.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DepKind {
/// A `[dependencies]` entry.
Normal,
/// A `[build-dependencies]` entry.
Build,
/// A `[dev-dependencies]` entry.
Dev,
}
/// A workspace crate and its direct dependencies on other workspace crates.
#[derive(Debug, Clone)]
pub struct Crate {
/// Package id from `cargo metadata`, the key into [`Workspace::graph`].
pub id: String,
/// Package name.
pub name: String,
/// Declared layer, `None` if the manifest has none or an invalid one.
pub layer: Option<Layer>,
/// Direct dependencies on workspace crates, by package name.
pub deps: Vec<(String, DepKind)>,
}
/// The facts the layer check needs from `cargo metadata`.
#[derive(Debug, Clone, Default)]
pub struct Workspace {
/// The workspace members.
pub crates: Vec<Crate>,
/// Normal-dependency edges of the whole resolved graph, by package id.
pub graph: BTreeMap<String, Vec<String>>,
/// Package name of every package id in the graph.
pub names: BTreeMap<String, String>,
}
/// Runs the check on the current workspace.
///
/// # Errors
/// Fails with one line per violation, or if `cargo metadata` fails.
pub fn check_workspace() -> TaskResult {
let root = repo_root()?;
let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".into());
let json = capture(&root, &cargo, &["metadata", "--format-version", "1"])?;
let metadata: Value =
serde_json::from_str(&json).map_err(|e| format!("cargo metadata: {e}"))?;
let workspace = parse_metadata(&metadata)?;
let violations = check(&workspace);
if violations.is_empty() {
println!("layers: {} crates OK", workspace.crates.len());
Ok(())
} else {
Err(format!("layer violations:\n {}", violations.join("\n ")))
}
}
/// Extracts a [`Workspace`] from `cargo metadata --format-version 1` output.
///
/// # Errors
/// Fails if the JSON lacks the `packages`, `workspace_members` or `resolve`
/// fields.
pub fn parse_metadata(metadata: &Value) -> TaskResult<Workspace> {
let packages = metadata
.get("packages")
.and_then(Value::as_array)
.ok_or("cargo metadata: no packages")?;
let members: BTreeSet<&str> = metadata
.get("workspace_members")
.and_then(Value::as_array)
.ok_or("cargo metadata: no workspace_members")?
.iter()
.filter_map(Value::as_str)
.collect();
let member_names: BTreeSet<&str> = packages
.iter()
.filter(|p| {
p.get("id")
.and_then(Value::as_str)
.is_some_and(|id| members.contains(id))
})
.filter_map(|p| p.get("name").and_then(Value::as_str))
.collect();
let mut workspace = Workspace::default();
for package in packages {
let id = str_field(package, "id");
let name = str_field(package, "name");
workspace.names.insert(id.clone(), name.clone());
if !members.contains(id.as_str()) {
continue;
}
let layer = package
.get("metadata")
.and_then(|m| m.get("lutra"))
.and_then(|l| l.get("layer"))
.and_then(|l| match l {
Value::String(s) if s == "tool" => Some(Layer::Tool),
Value::Number(n) => n
.as_u64()
.and_then(|n| u8::try_from(n).ok())
.map(Layer::Level),
_ => None,
});
let deps = package
.get("dependencies")
.and_then(Value::as_array)
.map(|deps| {
deps.iter()
.filter_map(|d| {
let dep_name = d.get("name").and_then(Value::as_str)?;
if !member_names.contains(dep_name) {
return None;
}
let kind = match d.get("kind").and_then(Value::as_str) {
Some("dev") => DepKind::Dev,
Some("build") => DepKind::Build,
_ => DepKind::Normal,
};
Some((dep_name.to_string(), kind))
})
.collect()
})
.unwrap_or_default();
workspace.crates.push(Crate {
id,
name,
layer,
deps,
});
}
let nodes = metadata
.get("resolve")
.and_then(|r| r.get("nodes"))
.and_then(Value::as_array)
.ok_or("cargo metadata: no resolve graph")?;
for node in nodes {
let id = str_field(node, "id");
let deps = node
.get("deps")
.and_then(Value::as_array)
.map(|deps| {
deps.iter()
.filter(|d| {
d.get("dep_kinds")
.and_then(Value::as_array)
.is_some_and(|kinds| {
kinds
.iter()
.any(|k| k.get("kind").is_none_or(Value::is_null))
})
})
.map(|d| str_field(d, "pkg"))
.collect()
})
.unwrap_or_default();
workspace.graph.insert(id, deps);
}
Ok(workspace)
}
/// Returns a string field of a JSON object, or an empty string.
fn str_field(value: &Value, key: &str) -> String {
value
.get(key)
.and_then(Value::as_str)
.unwrap_or_default()
.to_string()
}
/// Checks the layering rules and returns one message per violation.
pub fn check(workspace: &Workspace) -> Vec<String> {
let layers: BTreeMap<&str, Option<Layer>> = workspace
.crates
.iter()
.map(|c| (c.name.as_str(), c.layer))
.collect();
let mut violations = Vec::new();
for krate in &workspace.crates {
let Some(layer) = krate.layer else {
violations.push(format!(
"{} has no [package.metadata.lutra] layer (a number or \"tool\")",
krate.name
));
continue;
};
let Layer::Level(own) = layer else {
continue;
};
for (dep, kind) in &krate.deps {
if *kind == DepKind::Dev {
continue;
}
match layers.get(dep.as_str()).copied().flatten() {
Some(Layer::Level(other)) if other >= own => violations.push(format!(
"{} (L{own}) depends on {dep} (L{other}); dependencies must be in a lower layer",
krate.name
)),
Some(Layer::Tool) => violations.push(format!(
"{} depends on the tool crate {dep} outside dev-dependencies",
krate.name
)),
_ => {}
}
}
if own < UI_LAYER
&& let Some(path) = tauri_path(workspace, &krate.id)
{
violations.push(format!(
"{} (L{own}) reaches Tauri: {}",
krate.name,
path.join(" -> ")
));
}
}
violations
}
/// Finds a chain of normal dependencies from `start` to a `tauri` or
/// `tauri-*` package, returned as package names.
fn tauri_path(workspace: &Workspace, start: &str) -> Option<Vec<String>> {
let mut parent: BTreeMap<&str, &str> = BTreeMap::new();
let mut queue = VecDeque::from([start]);
let mut seen = BTreeSet::from([start]);
while let Some(id) = queue.pop_front() {
let name = workspace.names.get(id).map(String::as_str).unwrap_or(id);
if id != start && (name == "tauri" || name.starts_with("tauri-")) {
let mut chain = vec![name.to_string()];
let mut cur = id;
while let Some(prev) = parent.get(cur) {
chain.push(
workspace
.names
.get(*prev)
.cloned()
.unwrap_or_else(|| (*prev).to_string()),
);
cur = prev;
}
chain.reverse();
return Some(chain);
}
for next in workspace.graph.get(id).into_iter().flatten() {
if seen.insert(next.as_str()) {
parent.insert(next.as_str(), id);
queue.push_back(next.as_str());
}
}
}
None
}
#[cfg(test)]
mod tests {
use super::*;
fn krate(name: &str, layer: Option<Layer>, deps: &[(&str, DepKind)]) -> Crate {
Crate {
id: name.into(),
name: name.into(),
layer,
deps: deps.iter().map(|(n, k)| (n.to_string(), *k)).collect(),
}
}
fn workspace(crates: Vec<Crate>, edges: &[(&str, &str)]) -> Workspace {
let mut ws = Workspace {
crates,
..Default::default()
};
for c in &ws.crates {
ws.names.insert(c.id.clone(), c.name.clone());
ws.graph.entry(c.id.clone()).or_default();
}
for (from, to) in edges {
ws.names
.entry(to.to_string())
.or_insert_with(|| to.to_string());
ws.graph
.entry(from.to_string())
.or_default()
.push(to.to_string());
}
ws
}
#[test]
fn accepts_downward_dependencies() {
let ws = workspace(
vec![
krate("text", Some(Layer::Level(0)), &[]),
krate(
"engine",
Some(Layer::Level(4)),
&[("text", DepKind::Normal), ("testkit", DepKind::Dev)],
),
krate("testkit", Some(Layer::Tool), &[("engine", DepKind::Normal)]),
],
&[("engine", "text")],
);
assert!(check(&ws).is_empty());
}
#[test]
fn rejects_upward_and_sideways_dependencies() {
let ws = workspace(
vec![
krate(
"text",
Some(Layer::Level(0)),
&[("engine", DepKind::Normal)],
),
krate("vfs", Some(Layer::Level(2)), &[("index", DepKind::Build)]),
krate("index", Some(Layer::Level(2)), &[]),
krate("engine", Some(Layer::Level(4)), &[]),
],
&[],
);
let v = check(&ws);
assert_eq!(v.len(), 2, "{v:?}");
assert!(v[0].contains("text (L0) depends on engine (L4)"));
assert!(v[1].contains("vfs (L2) depends on index (L2)"));
}
#[test]
fn rejects_tool_crates_as_normal_dependencies() {
let ws = workspace(
vec![
krate(
"engine",
Some(Layer::Level(4)),
&[("testkit", DepKind::Normal)],
),
krate("testkit", Some(Layer::Tool), &[]),
],
&[],
);
assert!(check(&ws)[0].contains("tool crate testkit"));
}
#[test]
fn rejects_missing_layer() {
let ws = workspace(vec![krate("stray", None, &[])], &[]);
assert!(check(&ws)[0].contains("stray has no"));
}
#[test]
fn rejects_transitive_tauri_below_ui_layer() {
let ws = workspace(
vec![
krate("engine", Some(Layer::Level(4)), &[]),
krate("desktop", Some(Layer::Level(6)), &[]),
],
&[
("engine", "helper"),
("helper", "tauri-runtime"),
("desktop", "tauri"),
],
);
let v = check(&ws);
assert_eq!(v.len(), 1, "{v:?}");
assert!(v[0].contains("engine -> helper -> tauri-runtime"));
}
#[test]
fn parses_cargo_metadata() {
let json = serde_json::json!({
"packages": [
{"id": "a 0.0.0", "name": "a", "metadata": {"lutra": {"layer": 1}},
"dependencies": [{"name": "b", "kind": null}, {"name": "serde", "kind": null}, {"name": "t", "kind": "dev"}]},
{"id": "b 0.0.0", "name": "b", "metadata": {"lutra": {"layer": 0}}, "dependencies": []},
{"id": "t 0.0.0", "name": "t", "metadata": {"lutra": {"layer": "tool"}}, "dependencies": []},
{"id": "serde 1.0.0", "name": "serde", "metadata": null, "dependencies": []}
],
"workspace_members": ["a 0.0.0", "b 0.0.0", "t 0.0.0"],
"resolve": {"nodes": [
{"id": "a 0.0.0", "deps": [
{"pkg": "b 0.0.0", "dep_kinds": [{"kind": null}]},
{"pkg": "t 0.0.0", "dep_kinds": [{"kind": "dev"}]}
]}
]}
});
let ws = parse_metadata(&json).unwrap();
assert_eq!(ws.crates.len(), 3);
assert_eq!(
ws.crates[0].deps,
vec![
("b".to_string(), DepKind::Normal),
("t".to_string(), DepKind::Dev)
]
);
assert_eq!(ws.crates[2].layer, Some(Layer::Tool));
assert_eq!(ws.graph["a 0.0.0"], vec!["b 0.0.0".to_string()]);
assert!(check(&ws).is_empty());
}
}

104
xtask/src/licences.rs Normal file
View file

@ -0,0 +1,104 @@
//! `cargo xtask ui-licences`: the frontend counterpart of `cargo deny check
//! licenses`. Every production dependency of `ui/` must carry a licence from
//! the permissive list in AGENTS.md.
use serde_json::Value;
use crate::util::{TaskResult, capture, repo_root};
/// SPDX identifiers allowed for shipped dependencies. Keep in step with the
/// `allow` list in `deny.toml`; adding one outside AGENTS.md needs the owner.
pub const ALLOWED: &[&str] = &[
"MIT",
"MIT-0",
"Apache-2.0",
"BSD-2-Clause",
"BSD-3-Clause",
"0BSD",
"ISC",
"Zlib",
"MPL-2.0",
];
/// Runs the check on the production dependencies of `ui/`.
///
/// # Errors
/// Fails with one line per package whose licence is not allowed, or if
/// `pnpm licenses list` fails.
pub fn check_ui() -> TaskResult {
let ui = repo_root()?.join("ui");
let json = capture(&ui, "pnpm", &["licenses", "list", "--prod", "--json"])?;
let problems = check_pnpm_report(&json)?;
if problems.is_empty() {
println!("ui-licences: all production dependencies are permissively licensed");
Ok(())
} else {
Err(format!(
"frontend licence problems:\n {}",
problems.join("\n ")
))
}
}
/// Checks the JSON printed by `pnpm licenses list --json`, an object keyed
/// by licence expression whose values are arrays of packages.
///
/// # Errors
/// Fails if the report is not a JSON object.
pub fn check_pnpm_report(json: &str) -> TaskResult<Vec<String>> {
if json.trim().is_empty() {
return Ok(Vec::new());
}
let report: Value = serde_json::from_str(json).map_err(|e| format!("pnpm licenses: {e}"))?;
let groups = report
.as_object()
.ok_or("pnpm licenses: expected an object")?;
let mut problems = Vec::new();
for (licence, packages) in groups {
if is_allowed(licence) {
continue;
}
for package in packages.as_array().into_iter().flatten() {
let name = package.get("name").and_then(Value::as_str).unwrap_or("?");
problems.push(format!("{name}: {licence}"));
}
}
Ok(problems)
}
/// Evaluates a flat SPDX expression: alternatives joined by `OR`, each a
/// conjunction joined by `AND`, where `X WITH exception` counts as `X`.
pub fn is_allowed(expression: &str) -> bool {
let flat = expression.replace(['(', ')'], " ");
flat.split(" OR ").any(|alternative| {
alternative.split(" AND ").all(|term| {
let id = term.split(" WITH ").next().unwrap_or(term).trim();
ALLOWED.contains(&id)
})
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn evaluates_expressions() {
assert!(is_allowed("MIT"));
assert!(is_allowed("(MIT OR GPL-3.0)"));
assert!(is_allowed("Apache-2.0 WITH LLVM-exception"));
assert!(is_allowed("MIT AND ISC"));
assert!(!is_allowed("MIT AND GPL-2.0"));
assert!(!is_allowed("LGPL-3.0-or-later"));
assert!(!is_allowed("Unknown"));
}
#[test]
fn reads_pnpm_report() {
let json = r#"{"MIT":[{"name":"vue"}],"GPL-3.0":[{"name":"bad"}]}"#;
assert_eq!(
check_pnpm_report(json).unwrap(),
vec!["bad: GPL-3.0".to_string()]
);
}
}

View file

@ -3,7 +3,12 @@
//! Every subcommand prints what it checks and exits with status 1 and a
//! message when the check fails.
mod assets;
mod cleanroom;
mod layers;
mod licences;
mod lints;
mod tasks;
mod util;
use std::process::ExitCode;
@ -12,17 +17,39 @@ use std::process::ExitCode;
const USAGE: &str = "usage: cargo xtask <command>
commands:
lints-selftest prove that shipped unwrap() fails clippy and test unwrap() passes";
ci [--skip-ui] the full quality gate (run before every commit)
layers check the crate layering
assets check that every asset has a row in ASSETS.md
cleanroom check for JetBrains copyright notices and exported configuration
ui-licences check the licences of the frontend's production dependencies
lints-selftest prove that shipped unwrap() fails clippy and test unwrap() passes
dev [-- ARGS] run the desktop app in development mode, ARGS go to the app
fixtures create Symfony and Laravel reference projects in target/fixtures/";
/// Dispatches to the subcommand named by the first argument.
fn main() -> ExitCode {
let args: Vec<String> = std::env::args().skip(1).collect();
let Some(command) = args.first() else {
let Some((command, rest)) = args.split_first() else {
println!("{USAGE}");
return ExitCode::SUCCESS;
};
let result = match command.as_str() {
"ci" => tasks::ci(rest.iter().any(|a| a == "--skip-ui")),
"layers" => layers::check_workspace(),
"assets" => assets::check_repo(),
"cleanroom" => cleanroom::check_repo(),
"ui-licences" => licences::check_ui(),
"lints-selftest" => lints::selftest(),
"dev" => {
let app_args: Vec<String> = rest
.iter()
.skip_while(|a| *a != "--")
.skip(1)
.cloned()
.collect();
tasks::dev(&app_args)
}
"fixtures" => tasks::fixtures(),
"help" | "--help" | "-h" => {
println!("{USAGE}");
Ok(())

152
xtask/src/tasks.rs Normal file
View file

@ -0,0 +1,152 @@
//! The composite and launcher subcommands: `ci`, `dev` and `fixtures`.
use std::path::Path;
use std::time::Instant;
use crate::util::{TaskResult, program, repo_root, run};
use crate::{assets, cleanroom, layers, licences, lints};
/// Runs the full quality gate of AGENTS.md, stopping at the first failure.
///
/// `skip_ui` leaves out the frontend steps, for machines without pnpm.
///
/// # Errors
/// Fails with the name of the first step that failed.
pub fn ci(skip_ui: bool) -> TaskResult {
let root = repo_root()?;
let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".into());
let ui = root.join("ui");
type Step<'a> = (&'a str, Box<dyn Fn() -> TaskResult + 'a>);
let mut steps: Vec<Step> = vec![
(
"fmt",
Box::new(|| run(&root, &cargo, &["fmt", "--all", "--check"])),
),
(
"clippy",
Box::new(|| {
run(
&root,
&cargo,
&[
"clippy",
"--workspace",
"--all-targets",
"--",
"-D",
"warnings",
],
)
}),
),
(
"test",
Box::new(|| run(&root, &cargo, &["test", "--workspace"])),
),
("lints-selftest", Box::new(lints::selftest)),
("layers", Box::new(layers::check_workspace)),
("assets", Box::new(assets::check_repo)),
("cleanroom", Box::new(cleanroom::check_repo)),
(
"deny",
Box::new(|| run(&root, &cargo, &["deny", "check", "licenses"])),
),
];
if !skip_ui {
steps.extend::<Vec<Step>>(vec![
(
"pnpm install",
Box::new(|| run(&ui, "pnpm", &["install", "--frozen-lockfile"])),
),
("ui lint", Box::new(|| run(&ui, "pnpm", &["lint"]))),
(
"ui typecheck",
Box::new(|| run(&ui, "pnpm", &["typecheck"])),
),
("ui test", Box::new(|| run(&ui, "pnpm", &["test"]))),
("ui licences", Box::new(licences::check_ui)),
]);
}
let start = Instant::now();
for (name, step) in &steps {
println!("==> {name}");
step().map_err(|e| format!("ci step `{name}` failed: {e}"))?;
}
println!(
"ci: {} steps passed in {:.0?}",
steps.len(),
start.elapsed()
);
Ok(())
}
/// Starts the desktop app in development mode (Vite dev server plus a debug
/// build of the Tauri shell) through `cargo tauri dev`. Arguments after `--`
/// are passed to the app, e.g. `cargo xtask dev -- --control 7979 .`.
///
/// # Errors
/// Fails if the Tauri CLI is missing or the app exits with an error.
pub fn dev(app_args: &[String]) -> TaskResult {
let root = repo_root()?;
let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".into());
if !root.join("ui").join("node_modules").is_dir() {
run(&root.join("ui"), "pnpm", &["install"])?;
}
let mut args = vec!["tauri", "dev"];
if !app_args.is_empty() {
args.push("--");
args.push("--");
args.extend(app_args.iter().map(String::as_str));
}
run(&root.join("apps").join("lutra-desktop"), &cargo, &args).map_err(|e| {
format!("{e}\n(install the Tauri CLI with `cargo install tauri-cli --locked`)")
})
}
/// Creates the reference projects (a Symfony and a Laravel skeleton) in
/// `target/fixtures/` with Composer. Existing fixtures are kept.
///
/// # Errors
/// Fails if Composer is missing or a project cannot be created.
pub fn fixtures() -> TaskResult {
let root = repo_root()?;
let dir = root.join("target").join("fixtures");
std::fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
if std::process::Command::new(program("composer"))
.arg("--version")
.output()
.is_err()
{
return Err("Composer is not on the PATH; install PHP and Composer first".into());
}
for (name, package) in [
("symfony", "symfony/skeleton"),
("laravel", "laravel/laravel"),
] {
if dir.join(name).join("composer.json").is_file() {
println!("fixtures: {name} exists");
continue;
}
create_project(&dir, package, name)?;
}
println!("fixtures: ready in {}", dir.display());
Ok(())
}
/// Runs `composer create-project` for one fixture.
///
/// # Errors
/// Fails if Composer fails.
fn create_project(dir: &Path, package: &str, name: &str) -> TaskResult {
run(
dir,
"composer",
&[
"create-project",
"--no-interaction",
"--prefer-dist",
package,
name,
],
)
}

View file

@ -2,6 +2,7 @@
//! child processes and listing the files that belong to the repository.
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
/// Result type of every xtask step; the error is a message for the console.
pub type TaskResult<T = ()> = Result<T, String>;
@ -17,3 +18,85 @@ pub fn repo_root() -> TaskResult<PathBuf> {
.map(Path::to_path_buf)
.ok_or_else(|| "xtask is not inside the workspace".to_string())
}
/// Resolves the name of a program for spawning.
///
/// On Windows, Node-based tools such as `pnpm` are batch shims (`pnpm.cmd`)
/// that `Command` does not find by their bare name.
pub fn program(name: &str) -> String {
if cfg!(windows) && matches!(name, "pnpm" | "npm" | "npx" | "composer") {
format!("{name}.cmd")
} else {
name.to_string()
}
}
/// Runs a program to completion with inherited stdio.
///
/// # Errors
/// Fails if the program cannot be started or exits unsuccessfully.
pub fn run(dir: &Path, name: &str, args: &[&str]) -> TaskResult {
let status = Command::new(program(name))
.args(args)
.current_dir(dir)
.status()
.map_err(|e| format!("cannot start `{name}`: {e}"))?;
if status.success() {
Ok(())
} else {
Err(format!("`{name} {}` failed ({status})", args.join(" ")))
}
}
/// Runs a program and captures its standard output as UTF-8 text.
///
/// Standard error is passed through to the console.
///
/// # Errors
/// Fails if the program cannot be started, exits unsuccessfully or prints
/// output that is not UTF-8.
pub fn capture(dir: &Path, name: &str, args: &[&str]) -> TaskResult<String> {
let output = Command::new(program(name))
.args(args)
.current_dir(dir)
.stderr(Stdio::inherit())
.output()
.map_err(|e| format!("cannot start `{name}`: {e}"))?;
if !output.status.success() {
return Err(format!(
"`{name} {}` failed ({})",
args.join(" "),
output.status
));
}
String::from_utf8(output.stdout).map_err(|e| format!("`{name}` printed non-UTF-8 output: {e}"))
}
/// Lists the repository files that are tracked or would be added by
/// `git add -A` (untracked but not ignored), as paths relative to the root
/// with forward slashes.
///
/// # Errors
/// Fails if `git` is not available or the root is not a Git repository.
pub fn repo_files(root: &Path) -> TaskResult<Vec<String>> {
let out = capture(
root,
"git",
&[
"ls-files",
"--cached",
"--others",
"--exclude-standard",
"-z",
],
)?;
let mut files: Vec<String> = out
.split('\0')
.filter(|f| !f.is_empty())
.filter(|f| root.join(f).is_file())
.map(str::to_string)
.collect();
files.sort();
files.dedup();
Ok(files)
}