Library usage
The skif crate is a facade that never prints, prompts, exits, reads the environment or the working directory,
or writes files. Everything is read through a FileSystem: OsFs on disk, MemoryFs for tests, BufferFs for an
editor’s unsaved buffers over another file system. Diagnostics are relative to the workspace root, and fixes come back as a FixPlan for the caller to show,
merge or write. Poly is the first host.
use std::path::Path;use std::sync::Arc;use skif::{ConfigOverrides, Linter, MemoryFs, Workspace, find_workspace_root, load_config};
let fs = MemoryFs::new() .with_file("/repo/package.json", r#"{"name": "root", "private": true, "workspaces": ["packages/*"]}"#) .with_file("/repo/packages/a/package.json", r#"{"name": "a", "version": "1.0.0"}"#);
let root = find_workspace_root(Path::new("/repo/packages/a"), &fs)?;let config = load_config(&root, &fs, &ConfigOverrides::default())?;let workspace = Workspace::discover_with_fs(&root, &config, &fs)?;let report = Linter::with_fs(&config, Arc::new(fs.clone()))?.run(&workspace)?;# Ok::<(), skif::Error>(())Cargo features
Section titled “Cargo features”| Feature | Default | Brings in |
|---|---|---|
manifest |
yes | the built-in rules: manifest rules, version and semver group policies and catalog rules |
js-analysis |
no | the oxc based JS and TypeScript analysis and the plugin table |
fix |
no | apply_fixes and FixPlan |
yaml-fix |
no | YAML edits for pnpm-workspace.yaml (implies fix) |
report |
no | the renderers (human, JSON, TOON, SARIF, GitHub, Code Climate, compact, Markdown, CODEOWNERS), as skif::render |
schema |
no | config_schema |
update |
no | skif::update: newer published versions through a registry the host supplies (implies manifest and fix) |
js-analysis is off by default so a host that already embeds oxc keeps its own copy. No oxc or rayon type
appears in a public signature; a host that lints often passes an Executor (a reusable thread pool) in
RunOptions. The data model is part of the contract: serde (the derives of the data model), serde_json (fix
values and manifest values), toml (rule options), indexmap (the ordered maps of Config) and nodejs_semver (parsed specifier ranges). A major release of
any of them is a breaking release of skif.
Registry updates
Section titled “Registry updates”skif::update plans skif update without touching the network: the host implements the Registry trait (one
fetch(name) returning a Packument of published versions, and optionally a concurrent fetch_all), passes the
current time in UpdateOptions, and gets an UpdateReport back from plan_updates. apply_updates turns the report
into a FixPlan, as apply_fixes does for fixes. Packument::from_json reads an npm registry document, so a host that
does its own HTTP only has to fetch the text. The command line’s HTTP client is not part of the library.
Configuration from a host
Section titled “Configuration from a host”load_config(root, fs, overrides) reads skif.toml or .skif.toml through the FileSystem, never through
std::fs. A host builds ConfigOverrides directly instead of command-line flags, and skif-config exposes a
builder for constructing a Config without a file. Option validation happens when the Linter is built, so a
host must build it to catch a misspelled rule option.
Several roots and layered configuration
Section titled “Several roots and layered configuration”discover_targets(start, fs, overrides) finds every workspace and standalone package at or below start and loads
each as a Target: its root, its Workspace, and the configuration that governs it. A root that cannot be loaded is
a RootFailure in Discovery::failures; the others still load. discover_all is the same call that fails with the
first failing root. A root’s configuration is every skif.toml or .skif.toml from the root up to the ceiling (the
git repository root, or the start directory outside one), merged farthest first, with what they extend; the
files below a root that no configuration was built from are listed by unapplied_config_files.
resolve_config(root, ceiling, fs, overrides, cache) is the same resolution for one root. It returns a
ResolvedConfig: the merged Config, the sources that were applied, and the origins of every key, which is
what skif config --explain prints. ConfigLoader is the type behind it, for hosts that load package-level files
(add_package_files) themselves. Share one ConfigCache between the roots of a run, from several threads if you
like: each file is read once.
use std::path::{Path, PathBuf};use std::sync::Arc;use skif::{Ceiling, ConfigCache, ConfigOverrides, Linter, MemoryFs, RunOptions, discover_targets, resolve_config};
let fs = MemoryFs::new() .with_file("/r/skif.toml", "[lint]\nfail-on-warnings = true\n") .with_file("/r/a/package.json", r#"{"name": "a", "version": "1.0.0"}"#) .with_file("/r/b/skif.toml", "") .with_file("/r/b/package.json", r#"{"name": "b", "version": "1.0.0"}"#);
// Layered configuration: every skif.toml from the root up to the ceiling, merged farthest first. The cache is// shared by the roots of a run so each file is read once; `origins` says which file set which key.let cache = ConfigCache::new();let ceiling = Ceiling::VcsOr(PathBuf::from("/r"));let resolved = resolve_config(Path::new("/r/a"), &ceiling, &fs, &ConfigOverrides::default(), &cache)?;assert!(resolved.config.lint.fail_on_warnings);assert_eq!(resolved.sources.len(), 1);assert!(resolved.origins.last("lint.fail-on-warnings").is_some());
// Multi-root: every workspace and standalone package below a directory, each with its own configuration.let discovery = discover_targets(Path::new("/r"), &fs, &ConfigOverrides::default())?;assert!(discovery.failures.is_empty());assert_eq!(discovery.targets.len(), 2);// One linter per root; with `js-analysis` they share one module cache for the run.let linters = Linter::for_targets(&discovery.targets, Arc::new(fs.clone()))?;for (target, linter) in discovery.targets.iter().zip(&linters) { let config_path = target.config_path(); let mut options = RunOptions::default(); if let Some(path) = &config_path { options = options.with_config_path(path); } let report = linter.run_with(&target.workspace, &options)?; assert!(report.summary.packages >= 1);}# Ok::<(), Box<dyn std::error::Error>>(())A root can lie inside another (a standalone build/package.json below the repository root). A file of the inner
root that only the outer root imports is unused as far as the inner root alone can tell. skif -r therefore lints
every root at once, then lints again, by nesting depth, each inner root that its enclosing roots hand files: those
their reports list in Report::other_project_files (absolute), made relative to the inner root, go to
RunOptions::with_extra_entries of the inner root’s run. The files their reports list in
Report::other_project_build_sources (a Bazel srcs naming a file of the inner root) go to
RunOptions::with_extra_build_sources the same way: they are used, but unlike entries their exports are judged.
Once every root is linted it goes the other way: Report::ancestor_dependency_uses of the inner root lists the
dependencies its code uses that only a manifest above it lists (that manifest’s directory and the name), and the
CLI drops the matching unused-dependencies and unused-dev-dependencies findings of the root that owns the manifest
with Report::retain. Report::other_project_files also lists the files outside the root that its code reaches
(../tools/detect.js and what that imports); the CLI drops the unused-files findings of the root that holds each of
them the same way, and Report::ancestor_dependency_uses lists the packages those files import with the manifest that
lists them. Every path in both lists is absolute.
Roots can read one configuration file (a --config file, or a skif.toml above them), and each root’s
stale-js-config judges its settings on its own, so each would report a stale entry of that file. Pass the root and
report of every target, in the order of Discovery::targets, to settle_shared_config last: after any lint that
follows fixing (of every root whose configuration file a fix wrote) and after narrowing the reports to what you show.
A stale entry is then reported once, by the first root that still reports it and at the highest severity among the
roots, and only when no root used it; Report::config_judgements holds what each root judged. Record a baseline from
the reports before this step, so each root’s baseline covers what that root reports.
A host that lints repeatedly, such as an editor, passes the same ModuleCache to every
Linter::with_module_cache (feature js-analysis; MemoryModuleCache keeps it in memory), so only changed files
are parsed again. The cache never changes a report.
Linter::for_targets builds the linters of a multi-root run over the module cache of the run (feature
js-analysis). It holds the files more than one root can reach: those outside the root parsing them, such as a
directory of shared code outside every root, and those of a root nested in it. Such a file is parsed once for the run
rather than once per root, also while the roots are linted in parallel; each root parses its own files without the
cache, and the entries are freed with the linters. One target gets no shared cache. A host with a cache of its own
passes it to Linter::for_targets_with_cache, which parses every file through it. With several targets, a lookup of a
file another root is parsing waits for that parse instead of parsing it again. A host that builds its linters itself,
say one per distinct configuration, gets the same policy from Linter::shared_modules(targets, host_cache) and
passes the SharedModules it returns to each Linter::with_shared_modules.
A ModuleCache only stores and returns results: coalescing concurrent parses is done beside it, so a cache that
wraps another implements get and put and nothing else. The design is recorded in
ADR 0007.
A Linter built with Linter::with_fs remembers directory listings, existence checks and small configuration
files read through the file system for one run and starts every run_with from an empty cache, so a host that edits
files between runs sees the edits. discover_targets, find_target and find_workspace_root do the same for
the duration of one call.
Writing a rule provider
Section titled “Writing a rule provider”Hosts can add rules through RuleProvider. A provider receives the toml::Table of its rule options and reports
through an Emitter. See architecture and the
ADR index.