Skip to content

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>(())
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.

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.

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.

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.

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.