Architecture
Design decisions are recorded as architecture decision records in
adrs/. Read them before proposing a change in
direction.
Crates
Section titled “Crates”| Crate | Role |
|---|---|
skif-cli |
The command line: argument parsing, exit codes, install step after fixes. |
skif |
Embeddable facade: discover a workspace, lint it and plan fixes without IO side effects. |
skif-config |
skif.toml model, loading, CLI overrides and the JSON Schema. |
skif-core |
Diagnostic, fix, report and filesystem types shared by the other crates. |
skif-workspace |
Workspace discovery for npm, pnpm, yarn and bun: packages, manifests and catalogs. |
skif-lint |
Rule engine: rule registry, diagnostic emitter and parallel runner. |
skif-rules |
Built-in manifest, workspace, policy and catalog rules. |
skif-specifier |
npm dependency specifier parsing and comparison, vendored from syncpack. |
skif-edit |
Format-preserving JSON and YAML edits used by autofixes. |
skif-report |
Human, JSON, TOON, SARIF, GitHub, Code Climate, compact, Markdown and CODEOWNERS renderers. |
skif-js |
JavaScript and TypeScript module graph and dependency rules, built on oxc. |
skif-js-syntax |
oxc-based module facts and static config extraction; never executes code. |
skif-js-plugins |
package.json script parsing and the declarative plugin table. |
skif-migrate |
The translation behind skif migrate: sherif, syncpack and knip configuration to skif.toml. |
skif-node |
The Node-API addon behind the npm package. |
Key decisions
Section titled “Key decisions”- Mission, scope and non-goals: what skif is, what it never does, and its speed targets
- Crates, library API and upstream code: layering, publishing, the pure-function contract and borrowed code
- Configuration, suppressions, baselines and migration: layered
skif.toml, ignore reasons, baselines andskif migrate - Workspaces, roots and package managers: discovery, multi-root runs and per-manager semantics
- Rules, diagnostics and fixes: stable rule ids, severities and format-preserving fixes
- Version policies, lockfiles, toolchains and updates: syncpack-style policies, lockfile and toolchain rules,
skif update - JS analysis core on oxc: module graph, resolution, file discovery and the parse cache
- Plugins, config evaluation and commands: the declarative plugin table, static config evaluation and script parsing
- What counts as a use: export, member, dependency and template usage
- No type-aware analysis: why skif has no type checker, and what was measured
- Nx, Lerna and Bazel: projects, task layouts and Starlark read as text
- CLI contract and reporting: commands, flags, output formats, JSON contract and exit codes
- Editors, agents and git hooks:
skif lsp,skif mcp,--watchand hook launchers - Benchmarks and the comparison harness: pinned corpus, parity with knip and syncpack, published numbers
- Distribution, release and supported versions: channels, release workflow and the support policy
The full list is the ADR index.
Pipeline
Section titled “Pipeline”skif-configresolves defaults, then theskif.tomlfiles from the root up to the ceiling (merged farthest first), then CLI overrides.skif-workspacediscovers packages and reports facts; it never decides that a fact is a problem. A run over several roots discovers each root and gives it its own configuration.skif-lintbuilds a registry from the rule providers, validates every rule’s options, and runs the providers concurrently. Rules emit diagnostics, optionally with fixes.- The JS analysis (
skif-js, withskif-js-syntaxandskif-js-plugins) is one of those providers. It parses the sources, builds the module graph, applies the plugin table and emits thejsrules. skif-editturns fixes into aFixPlanof format-preserving edits; the CLI writes the plan.skif-reportrenders the report as human, JSON, TOON, SARIF, GitHub, Code Climate, compact, Markdown or CODEOWNERS output.