Migrating from sherif, syncpack and knip
skif migrate reads the configuration of sherif, syncpack and knip and writes a skif.toml. It is a one-shot
translator, not a compatibility reader: skif keeps reading skif.toml only, and the old files stay where they are.
skif migrate never deletes a file.
skif migrate --dry-run # print the skif.toml and the report, write nothingskif migrate # write ./skif.toml for every tool foundskif migrate --from knip # one tool onlyskif migrate --from sherif,knip # several tools in one runskif migrate --merge # add the translation to an existing skif.tomlJavaScript and TypeScript configuration files are read statically, as skif reads every tool configuration: nothing is
executed. A value that is only known at run time (a function call, process.env, an import) is not guessed. Its key
is left out and the report names it, with the rest of the file translated.
What is read
Section titled “What is read”| Tool | Files | Also read |
|---|---|---|
| sherif | the sherif key of package.json |
the flags of the scripts that run sherif |
| syncpack | .syncpackrc, .syncpackrc.{json,yaml,yml,js,cjs,mjs,ts}, syncpack.config.{js,cjs,mjs,ts}, the syncpack key (or config.syncpack) of package.json |
the flags of the scripts that run syncpack, and a --config file they name |
| knip | knip.{json,jsonc}, .knip.{json,jsonc}, knip.{js,ts,mjs,cjs,mts,cts}, knip.config.*, the knip key of package.json |
the flags of the scripts that run knip, and a --config file they name |
The flags matter because they change what the old tool checked: knip --dependencies --production,
syncpack lint --dependency-types prod,dev and sherif --fail-on-warnings -i react are translated like configuration.
--from auto (the default) migrates every tool that has a file, a package.json key or a script in the project.
Scripts are found behind package-manager launchers (pnpm exec knip, npx knip, npm run knip -- --include files),
environment prefixes (CI=1 knip, cross-env, dotenv --), turbo run and nx exec, as the package’s entry file
(node ./node_modules/knip/bin/knip.js), and inside concurrently "knip" "syncpack lint" and sh -c. A command that
runs another script named like the tool ("ci": "pnpm run knip" next to a knip script) is not a run of its own; when
it passes arguments on (pnpm run knip -- --include files), it is a run with that script’s flags and those. A switch
given as --production=false is off. A script that names the tool in any other command is reported, because its flags were not
read. Each command of a script is one run of the old tool, but skif has one configuration: when two runs of a tool pass
different flags, the result is their union (or, for [js] production, left out) and the report names both scripts.
Profiles
Section titled “Profiles”sherif runs ten rules and stops on an invalid package.json; skif has more rules, and it enables many of them by default. The profile
decides what the migration does about the checks the old tools did not run.
| Profile | Result |
|---|---|
exact (default) |
Only the checks the old tools ran. Every other rule that skif enables by default is set to off in [rules] (each with a # skif migrate: not checked by <tools> comment), and [js] enabled = false when knip is not among the tools. |
full |
The checks of the old tools plus skif’s defaults for everything else. |
The report lists the checks skif runs that the old tools did not, so you can read the list and decide which to turn on.
knip reports everything as an error, where skif’s defaults are mostly warnings: the migration writes every rule it
enables at knip’s own severity (error unless the rules key says otherwise) in both profiles.
Which tool runs which rule
Section titled “Which tool runs which rule”The exact profile keeps a rule when a migrated tool runs it and turns off every other rule that is on by default. The
mapping is read from the sources of the tools (sherif 1.13, syncpack 15.3, knip 6) and is kept as data in
crates/skif-migrate/src; a test requires every rule to be in the table of one tool or among the rules no tool runs.
| skif rules | Run by |
|---|---|
empty-dependencies, version-mismatch, root-package-dependencies, root-package-manager-field, root-package-private-field, types-in-dependencies, unsorted-dependencies |
sherif (empty-dependencies, multiple-dependency-versions, root-package-dependencies, root-package-manager-field, root-package-private-field, types-in-dependencies, unordered-dependencies) |
unmatched-workspace-patterns, missing-package-manifest, unsynced-dependency-family, invalid-workspace-file |
sherif only (non-existant-packages, packages-without-package-json, unsync-similar-dependencies, and stopping on an invalid manifest) |
version-mismatch, semver-range-mismatch, banned-dependency, invalid-local-version, policy-conflict |
syncpack lint: the version and semver group states, IsBanned, InvalidLocalVersion and the conflict states |
catalog-mismatch |
syncpack: DiffersToCatalog, in every highest or lowest version group (skif keeps it on in every group) |
catalog-not-used, catalog-missing-entry, unresolved-catalog-references |
syncpack only with a policy: catalog version group (NotUsingCatalog, MissingFromCatalog, DependsOnMissingCatalogDefinition); knip covers unresolved-catalog-references through catalogReferences |
unsorted-dependencies |
syncpack only when sortAz names a dependency map and a script runs syncpack format |
package-json-format |
syncpack format: when a script runs syncpack format (the rule is off by default; format keys alone are written to [format] for skif format) |
| the rules of the knip issue types that stay enabled | knip (unused-files, unused-subpath-imports, unused-subpath-exports with includeSubpathExports, unused-dependencies, unused-dev-dependencies, unused-optional-peer-dependencies, unlisted-dependencies, unlisted-binaries, unresolved-imports, unused-exports, unused-types, unused-namespace-exports, unused-namespace-types, duplicate-exports, unused-enum-members, unused-namespace-members, unused-catalog-entries, unresolved-catalog-references, circular-imports) |
workspace-protocol, local-path-dependency, incompatible-peer-dependencies, member-toolchain-fields, toolchain-pin-drift, foreign-package-manager-command, stray-lockfile, nested-workspace-root, stale-lerna-config, lerna-packages-mismatch, catalog-version-divergence, stale-patched-dependencies |
none of the three |
unused-class-members |
none: knip 6 has no class-member issue type (knip 5 had classMembers) |
unparseable-files |
none: knip skips a file it cannot parse without reporting it |
stale-js-config |
none unless treatConfigHintsAsErrors is set: skif’s configuration hints differ from knip’s |
stale-mocks |
none: knip does not read the specifiers of vi.mock, jest.mock and the like, so the exact profile turns it off |
Migrated tools are combined: a rule is kept when any of them runs it. Without sherif, for example,
unmatched-workspace-patterns is turned off.
The report
Section titled “The report”Every construct that was not copied one to one has a note with the file, the key path in that file
(versionGroups[2].pinVersion, scripts.knip: --strict) and what was done. The notes fall into four groups.
| Group | Letter | Meaning |
|---|---|---|
| Translated | M, A | M: translated one to one. A: translated, but skif behaves differently in a way the note explains. |
| Covered by default | D | Nothing to translate; skif does it already or does it with a flag. |
| Needs a human | H, X | H: not translated because the value is not static or its meaning is unclear. X: skif has no equivalent. |
| Extra checks | Rules skif runs by default that the old tools did not. |
--format json prints the same report as one document. --strict exits 1 when any note needs a human. --strict-hints writes knip’s treatConfigHintsAsErrors as error instead of warn.
sherif
Section titled “sherif”| sherif | skif |
|---|---|
ignoreRule, -r |
[rules] <id> = "off", with the rule ids renamed (multiple-dependency-versions is version-mismatch, unordered-dependencies is unsorted-dependencies, …). A rule that another migrated tool still checks stays on and the report says so (H): a repository that ignores multiple-dependency-versions in sherif because syncpack owns it keeps syncpack’s version groups |
ignorePackage, -p |
[workspace] ignore-packages, a path without its ./ prefix (./apps/* is apps/*): skif matches a package’s directory relative to the root. A path written without ./ matched no package in sherif and does in skif (A) |
multiple-dependency-versions |
[policy] dependency-types = ["prod", "dev"], the sections sherif compares. sherif never compares a dependency with the version of the workspace package it names, and skif does not either without local in the list (ADR 0006). Migrated with syncpack, the list is the union of both scopes. When sherif ignores multiple-dependency-versions, no scope is written |
| specifiers sherif does not parse | the exact profile writes a last [[version-groups]] entry, not compared by sherif, with policy = "ignored" over the specifier types sherif’s semver parser rejects (latest and *, dist-tags, ||, hyphen and space-separated ranges, workspace:, npm:, git, file, link and url specifiers). A range sherif read but skif cannot classify (>= 1.0.0 with a space, 1.x) is unsupported and is left out too (A). The full profile writes no group, because policy-conflict would report it when no dependency uses such a specifier; the note shows the entry. Migrated with syncpack, which compared every specifier, no group is written |
a dependency in both dependencies and devDependencies of one package |
nothing to write, noted as approximate: sherif read only the devDependencies specifier, skif compares both entries, so two different specifiers in one package are a version-mismatch |
unsync-similar-dependencies |
unsynced-dependency-family, which reads the sections of [policy] dependency-types (dependencies and devDependencies after a sherif migration) and never compares a dependency listed in two sections with itself. A catalog: reference counts as the version of its catalog entry, which sherif left out (A) |
an empty root dependencies object |
nothing to write, noted as approximate: sherif reported it as root-package-dependencies (a warning), skif reports it as empty-dependencies (an error); remove the empty object |
ignoreDependency, -i |
[[ignore]] with rules = ["version-mismatch"], the only rule sherif applied it to |
a flag value with a comma (-i a,b) |
not written (H): sherif takes a value whole, so a,b matched nothing; pass each name with its own flag |
ignoreDependency as name@version |
the same entry, noted as approximate (below) |
failOnWarnings, --fail-on-warnings |
[lint] fail-on-warnings |
select, -s |
[policy] prefer |
fix, noInstall |
none; skif --fix and --no-install do the same |
sherif’s -i name@version leaves every instance at that version out of its comparison. skif has no ignore that does
that: an [[ignore]] entry silences diagnostics, and version groups select dependencies by name, not by version. The
closest equivalent is the [[ignore]] entry above, which silences each instance at that version. It differs when skif
aligns on the ignored version: those instances still count when skif picks the version to align on, so with
prefer = "lowest" (or when the ignored version is the highest) the other instances are reported against it, where
sherif saw no mismatch. The report says so for each such entry. Where that matters, ignore the whole dependency
(-i react) instead.
The GitHub Action applies this translation on its own to a project that has no skif configuration yet, so a job that replaces sherif keeps its flags.
Fixed relative to sherif
Section titled “Fixed relative to sherif”Porting the rules fixed these behaviours of sherif 1.13.0. The ones marked changes results can make a CI job that moves from sherif to skif report something sherif did not, or exit with a different code, on an unchanged repository.
- Prerelease ordering. sherif lets the prerelease tag decide the order before the version numbers, so
15.0.0-rc.0ranks below14.2.3and--fix --select highestrewrites the prerelease to the older stable version (QuiiBz/sherif#164). skif orders versions as npm does: a prerelease ranks below its own release only, soversion-mismatchaligns on15.0.0-rc.0and reports14.2.3. Changes results: the package reported, and the version a fix writes, can differ. - Ranges and dist-tags are compared. sherif leaves out of
multiple-dependency-versionsevery specifier its parser rejects: npm ranges such as>=1.2.0 <2.0.0or^1.0.0 || ^2.0.0, and dist-tags such aslatest. skif parses npm’s range syntax, so these take part inversion-mismatch;latestor a dist-tag that differs from the other specifiers is reported as a mismatch that has no fix. Changes results: newversion-mismatcherrors, unless the configuration comes fromskif migrate --profile exact, which leaves these specifiers out as sherif did. - Workspace patterns follow pnpm. sherif expands
**one level deep, reads a negation as a literal directory (so!**/test/**excludes nothing), and matches a name prefix below the root (packages/foo-*) against the whole pattern, so it finds nothing there. skif matches**at any depth (only directories with apackage.json, so the directories in between are not reported as missing a manifest; QuiiBz/sherif#161), applies glob negations such as!**/test/**, and matchespackages/foo-*. Changes results: packages sherif skipped are linted. - The install step. After a fix sherif picks the package manager from the lockfiles of the current directory,
asks when there is none, and runs it in the current directory; on Windows it cannot start the
.cmdshim corepack installs (QuiiBz/sherif#110). skif takes thepackageManagerfield first, then the lockfiles of the workspace root, never asks, runs the install in the workspace root, and finds the executable throughPATHEXT. - CI detection. sherif refuses
--fixwheneverCIis set, includingCI=false. skif refuses it only whenCIis truthy: set, not empty, and not0,false,nooroff. - Exit codes. sherif exits
1both for findings and when it cannot run (no workspace declaration, an invalidpackage.json, a failed install). skif exits1for findings only and2when it cannot run (see Exit codes). Changes results: a script that tests for exit1misses a run that failed. - No workspace declaration. sherif stops with an error when the root has neither
workspacesnorpnpm-workspace.yaml. skif lints such a package on its own (see Single packages). Changes results: a run that failed now reports findings.
skif also covers an open sherif request: incompatible-peer-dependencies (a warning by default) reports a
devDependencies version outside the package’s own peerDependencies range
(QuiiBz/sherif#63); with fail-on-warnings it fails the run. The rules
skif adds beyond sherif’s are listed under the report’s extra checks.
syncpack
Section titled “syncpack”| syncpack | skif |
|---|---|
versionGroups[] with label, dependencies, packages, dependencyTypes, specifierTypes |
[[version-groups]] with the same keys |
isBanned, isIgnored, pinVersion, snapTo, preferVersion, policy: sameRange, policy: sameMinor |
policy = "banned", "ignored", "pinned" with pin, "snapped-to" with snap-to, prefer, "same-range", "same-minor". As in syncpack, a policy wins over snapTo; preferVersion with policy: sameMinor is not written (A), since a skif same-minor group picks no version to align on |
policy: catalog |
[catalog] mode = "enforce" and min-packages = 1 when the group selects every dependency, with catalog-not-used, catalog-missing-entry and unresolved-catalog-references at error: like syncpack, skif then reports every instance without catalog: as an error. A group with dependencies, packages, dependencyTypes or specifierTypes is not written (H): the catalog setting is global, so writing it would check every dependency |
policy: semverRangeOnly |
policy = "semver-range-only" |
severity |
none (H): levels are set per rule |
semverGroups[] with range |
[[semver-groups]] |
semverGroups[] with isIgnored or isDisabled |
[[semver-groups]] with ignored = true |
dependencyTypes with prod, dev, peer, local, resolutions, overrides, pnpmOverrides and ! negation |
the same tokens (pnpmOverrides is pnpm-overrides) |
dependencyTypes: ["**"] |
no dependency-types key: every type (dependencies and packages of ["**"] select everything too) |
specifierTypes |
specifier-types with the types skif knows; hosted-git is git (A), ** is no filter, and a type skif does not know (delete) is dropped (A) or, when the group selects only such types, the group is not written (X) |
customTypes with strategy name@version, version, versionsByName or name~version |
[[custom-types]] with name, path and strategy ("name@version", "version", "versions-by-name", "name~version" with name-path from namePath) |
a custom type whose name is a built-in token (dev, overrides, …) |
[[custom-types]] under <name>-custom (A); groups that name the token select the built-in type |
a custom type for optionalDependencies with strategy versionsByName |
the native optional dependency type |
a custom type’s source |
"PackageJson", syncpack’s default, is translated like a type without it; "PnpmWorkspace" is not (X): skif reads custom types from package.json only |
dependencyGroups, strict, sourceMode |
none (X or H) |
source |
dropped when it lists the workspace patterns (D); otherwise H |
sortFirst, sortAz, sortExports, sortPackages, formatBugs, formatRepository, indent |
[format] sort-first, sort-az, sort-exports, sort-packages, format-bugs, format-repository, indent, and package-json-format = "error" when a script runs syncpack format. Without such a script the settings are written for skif format only and no layout rule is turned on (A): syncpack lint never checks the layout. skif sorts in byte order where syncpack uses a collator (A), by default moves only types first and default last among exports conditions, since reordering the others changes resolution; a configured sortExports naming others becomes an unsafe fix (A), collapses bugs and repository only when nothing is lost (A), and with indent also checks the layout (A). unsorted-dependencies stays on when sortAz names a dependency map and a script runs syncpack format |
a script running syncpack format |
package-json-format = "error"; run skif format or skif format --check in its place |
updateGroups[] with target or isIgnored |
[[update-groups]] with target or ignored = true, and the same selectors; a group with both, neither, or another target is not written (H) |
minimumReleaseAge, maxConcurrentRequests |
[update] minimum-release-age, max-concurrent-requests |
the override sections (pnpmOverrides, overrides, resolutions) |
[policy] override-reading = "syncpack": an override key is its own dependency, so parent@4>child is not compared with child; nested objects and pnpm.overrides of a package.json are not read, as in syncpack 15 (pnpmOverrides is the overrides of pnpm-workspace.yaml). Without it skif would compare them with the dependency they replace |
--dependency-types |
[policy] dependency-types. syncpack filters every instance by it before a group sees one, so a group’s dependencyTypes is cut to that scope, and a group left with no type is not written |
A comment above a group in a YAML or JSON-with-comments .syncpackrc (or a JavaScript config) is written as a comment
above its [[version-groups]], [[semver-groups]] or [[update-groups]] entry, after the line naming where the group
came from. Groups are matched to their comments by position, so the comment on a spread or on a group after one is not
carried over, since the spread changes the positions. sherif’s configuration is a package.json key, and JSON has no comments, so there is nothing to carry over
from it.
Without --dependency-types, [policy] dependency-types is set to the scope syncpack lints by default (prod, dev,
peer, local, resolutions, overrides, pnpm-overrides and your custom types; optional dependencies are not part
of it), because skif’s own default is narrower. --dependencies and
--specifier-types narrowed the old run; a skif.toml cannot, so they are reported. To narrow a skif run the same
way, pass --dependency (syncpack’s --dependencies; skif’s --dependencies is knip’s issue-type shortcut) and
--specifier-types on the command line. syncpack update is skif update with the same
--check, --target, --dependencies and --interactive (A).
| knip | skif |
|---|---|
entry, project, ignore |
[js] entry, project, ignore; a ! production suffix is kept on the pattern |
ignoreFiles |
[js] ignore-files, and ignore-files of the workspace table |
ignoreDependencies, ignoreBinaries |
[js] ignore-dependencies, ignore-binaries |
ignoreUnresolved |
[js] ignore-unresolved (and per workspace) |
ignoreMembers |
[js] ignore-members, or [js.workspaces."<dir>"] ignore-members inside a workspace |
ignoreExportsUsedInFile |
[js] ignore-exports-used-in-file, or [js.workspaces."<dir>"] ignore-exports-used-in-file inside a workspace |
ignoreWorkspaces |
[js] ignore-workspaces |
ignoreIssues |
[[overrides]] with files and the matching rules set to off; with --output to a file outside the project, the files start with $ROOT/ |
includeEntryExports |
[js] include-entry-exports, or per workspace |
includeSubpathExports, --include-subpath-exports |
[rules] unused-subpath-exports at the level of the subpaths issue type, next to unused-subpath-imports; a workspace-level includeSubpathExports is left to you (H), since a rule level applies to every package unless [[overrides]] narrow it. With [js] production, skif reports no unused subpaths, which knip does (A) |
--tsConfig, -t |
[js] tsconfig (knip has no configuration key for it); scripts that pass different values get a note and the last one is written |
--use-tsconfig-files |
[js] use-tsconfig-files = true |
paths |
[js.workspaces."<dir>"] paths, with "." for the root |
workspaces["<dir>"] |
[js.workspaces."<dir>"]; workspaces["."] is merged into [js] and, as in knip, replaces the top-level entry, project and paths, which are then not written; the top-level ignore and ignoreFiles still apply to every workspace and are written |
plugin keys (vitest: true, "config.ts", ["a", "b"], { config, entry, project }) |
[js.plugins], or [js.workspaces."<dir>".plugins] inside a workspace |
rules, include, exclude, and --include, --exclude, --dependencies, --exports, --files, --cycles |
a level for each rule of the issue types that stay enabled, worked out as knip 6 does (the flags override the configuration; --dependencies also covers the catalog types and the dev dependencies; an include of only nsExports or nsTypes adds the defaults); the exact profile turns the others off |
the catalog issue type, when it stays enabled |
[rules] unused-catalog-entries and [catalog] report-unused-entries = true: knip reports unused catalog entries by default, skif only with that key |
tags with -tag |
unused-exports option ignore-tags |
tags with +tag |
unused-exports option include-tags (A for +public, +beta, +alpha, +alias and +internal: knip keeps exempting those tags and reports none of their exports, skif reports the unused ones) |
cycles.allow, cycles.dynamicImports |
[js.cycles] allow (A: a cycle is matched as a set of files, not as an ordered path) and dynamic-imports |
treatConfigHintsAsErrors, --treat-config-hints-as-errors |
[rules] stale-js-config = "warn" (A), or "error" with skif migrate --strict-hints; the rule is then on and is not listed among the checks the profile turned off. skif’s hints differ from knip’s (they also flag entries skif never needed, such as a regular expression in ignoreUnresolved for an import skif does not report), so error could fail a project that knip passed |
--no-config-hints |
[rules] stale-js-config = "off" |
--fix, --fix-type, --allow-remove-files |
none in the file; skif --fix-unsafe with --fix-type and --allow-remove-files does the same on the command line (--fix-type takes knip’s issue types) |
--production, --strict |
[js] strict = true when every script runs knip with --strict, else [js] production = true when every script runs knip in production mode (otherwise H for each), and the issue types production leaves out (devDependencies, catalog, catalogReferences) are turned off. A project that wants knip’s strict isolation for its tests and configs too can set [js] isolate-workspaces = true instead, which isolates every package without production mode |
--isolate-workspaces (knip 5) |
none, without a note: it built one TypeScript program per workspace, which changes no finding, and knip 6 always does so. It is not skif’s [js] isolate-workspaces |
compilers: true, or true for mdx, vue, svelte, astro, css, pcss, scss, sass, less, styl, stylus or tsrx |
none (D): skif reads those files with built-in extractors, without a compiler; for mdx and tsrx the note suggests adding them to project, which knip does when a compiler reads them |
a compilers function for one of those extensions |
none (A): the function is never run, and the built-in extractor reads the files |
compilers for other extensions, asyncCompilers, preprocessor |
none (X): functions are never run. Translate a compiler by hand into [js.compilers]: when it extracts imports (a .html compiler that turns <script src> into import statements), write regular expressions that capture the specifiers (html = { imports = ['<script[^>]+src="([^"]+)"'] }); when it hands the file to another language’s compiler, map the extension onto that reader (page = { as = "mdx" }). The note names [js.compilers] |
ignoreGlobalBinaries |
[js] ignore-global-binaries (true is the default); a workspace-level false has no equivalent (X) |
treatTagHintsAsErrors, --treat-tag-hints-as-errors |
none (A): tag hints are part of stale-js-config, which --strict-hints makes an error |
ignoreIssues with a name that is not a knip issue type (classMembers) |
none (X): knip 6 has no such issue type |
| a plugin key skif has no plugin for | none (X), named in the report |
A string in an ignore list that knip would compile as a regular expression (it contains one of * + \ ( | { ^ $), and a
regular expression literal in a JavaScript or TypeScript config, are written as a slash-delimited string:
"/^@org\\/.+$/". The two forms with an exact glob equivalent, ^literal and ^literal$, become the glob
literal* and literal. A pattern that only ends in * (@org/*) stays a glob; knip would have compiled it as a
regular expression matching a superset of that.
A comment on an entry of an ignore list (ignoreDependencies, ignoreBinaries, ignoreUnresolved, ignoreMembers,
ignoreFiles, ignoreWorkspaces) becomes its reason, in any knip configuration file (knip.json, knip.jsonc,
.knip.json, .knip.jsonc, knip.{js,ts,mjs,cjs,mts,cts}, knip.config.*); the knip key of package.json is
JSON and has none. Each entry takes the first of:
- its own comment: on the lines directly above the entry, or after it on the line where it ends;
- its group heading: the comment above the nearest earlier entry of the same list that has one above it, so a list written as groups under one comment line each gives every entry of a group that line;
- the comment on the list’s key: on the lines directly above
ignoreDependencies: [, after the opening bracket on its line, or after the list on the line where it ends.
A list written as a top-level constant and named by the key (const deps = [...]; export default { ignoreDependencies: deps }) keeps its comments too; the entries a spread (...shared) brings in do not. Entries without a comment stay
plain strings; when other entries of the same list have one, the note of the list names them.
// installed on the CI imageignoreBinaries: ['docker', 'make'],workspaces: { 'packages/app': { ignoreDependencies: [ // false positive: loaded by the bundler from a config string 'some-loader', 'other-loader', 'left-pad', // kept for the legacy build ], },},becomes
[js]ignore-binaries = [ { name = "docker", reason = "installed on the CI image" }, { name = "make", reason = "installed on the CI image" },]
[js.workspaces."packages/app"]ignore-dependencies = [ { name = "some-loader", reason = "false positive: loaded by the bundler from a config string" }, { name = "other-loader", reason = "false positive: loaded by the bundler from a config string" }, { name = "left-pad", reason = "kept for the legacy build" },]so a configuration that explained every entry migrates to one that passes [lint] require-ignore-reasons = true (or
skif --require-ignore-reasons), which then enforces a reason on every entry. A comment separated from the entry or
the key by a blank line is not attached, a comment after an entry on its line explains that entry only and heads no
group, and tool directives such as // eslint-disable-next-line are left out.
Settings that knip scopes to one workspace stay in that workspace’s table. --workspace narrowed the old run to some
workspaces; it is not written to the configuration, and the script can pass the same --workspace to skif.
knip merges the tsconfig paths of every workspace, so a package could import through the paths of another one.
skif migrate translates configuration and does not analyse the sources, so its report cannot list such imports: in
a workspace of several packages it adds an approximate note, at tsconfig paths, that says so. The imports appear on
the first skif run as unlisted-dependencies findings with the detail ForeignTsconfigPaths, each naming the
tsconfig that declares the pattern (a config the package’s own one extends, when the paths are inherited). Add the mapping to the importing package’s tsconfig, or import the module
by its package name; adding a dependency does not fix them.
Several tools
Section titled “Several tools”Migrate every tool in one run: skif migrate --from sherif,syncpack,knip (or the default --from auto). The exact
profile then knows the checks of all of them at once, and a rule one tool ignores but another still runs stays on.
Merging into an existing file
Section titled “Merging into an existing file”--merge edits the existing skif.toml (or .skif.toml) in place, so its comments and the order of its tables stay.
Tables the file lacks are appended after its text under a banner; in a table both files define, keys it lacks are added,
lists are united, and the existing value wins over a different one (the command lists those keys). Running the same
migration again with --merge changes nothing. With --output <FILE>, the merge of the existing file and the
migration is written to FILE and the existing file is left as it is; a FILE that already exists is refused, since
--merge cannot be combined with --force.
A merge only adds what the migrated tools need: the exact profile writes no off value into a file that has content.
A rule the file does not name keeps running, whether one of its recorded sources checked it or the file (written by
hand, or for other tools) relies on skif’s default; the report lists these checks as left as the existing
configuration has them (left-as-existing in --format json). Migrating knip into a file with [js] enabled = false
sets it to true, because the knip settings are [js] settings that only take effect with the JavaScript analysis
on; the report says so (replaced-existing). Set it back to false to keep the analysis off.
Lists are united by entry name. "playground/**" and { name = "playground/**", reason = "test suites" } are one
entry: the existing reason stays, and an entry without one takes the migrated reason. In the [js] lists a trailing
! does not make another entry either:
| List | Existing and migrated entry | Merged entry |
|---|---|---|
entry, project |
x and x!, in either order |
x! |
ignore lists (ignore-dependencies, ignore-workspaces, …) |
x and x!, in either order |
x |
| any other list | x and x! |
both |
In entry and project, x and x! are the same pattern in a normal run, and in a production run only x! makes
an entry while x excludes the file from the project, so keeping both would drop the file from the production run.
When the merge adds the marker to an existing pattern, the report names the list (replaced-existing). In an ignore
list x applies in every mode and x! in production mode only, so x already covers x!. A plain pattern that only
overlaps a ! pattern (src/** next to src/main.js!) is a different entry and stays, and stale-js-config reports
it when it matches the file of the ! pattern.
Migrating the tools in steps works too, and ends with the same checks as one run:
skif migrate --from sherifskif migrate --from knip --mergeThe exact profile writes off for every rule the migrated tools did not run, each with a trailing
# skif migrate: not checked by sherif comment, and # skif migrate: sources = ["sherif"] records the tools the file
came from. Those off values are not choices of yours: the knip step replaces the ones for the rules knip checks with
knip’s levels, removes [js] enabled = false, and leaves rules the first step already runs alone. Values you wrote
yourself, and off values that came from a tool’s own configuration (ignoreRule, knip’s rules), always win. One
case is only seen in a single run: when sherif ignores a rule that syncpack keeps checking, migrate both together so the
rule stays on.
Adopting skif on an existing repository
Section titled “Adopting skif on an existing repository”A repository rarely starts clean. Record what is there as a baseline, fix it over time, and keep CI from accepting new findings:
skif baseline write # record every error and warning in skif.baseline.tomlskif # clean: skif.toml now extends the baselineskif baseline prune # after fixing some findings, drop the entries that match nothingskif baseline check --base origin/main # in CI: fail when the baseline gained entrieswrite adds one [[ignore]] entry per finding, with the rule, the package and the dependency:
[[ignore]]rules = ["version-mismatch"]packages = ["@acme/web"]dependencies = ["react@^17.0.2"]reason = "baseline"Version findings are recorded as name@specifier, so a baselined react@^17.0.2 silences that version only; a
package that moves to another version, or a new package, is reported again. Other findings about a dependency are
recorded by its name, so a version bump does not reopen them. This replaces a script that shrinks
sherif’s ignoreDependency to the variants still reported, and per-member pinVersion groups in syncpack. Edit a
reason to say why an entry stays; later runs of write and prune keep it, and --require-ignore-reasons accepts
the entries. check compares entries by what they suppress, so a reworded reason never fails it. A finding that has
no package or dependency (a finding about the workspace as a whole) is not recorded, since its entry would
turn the rule off; fix it or set the rule’s level instead. Neither is a finding in a root package.json without a
name, since no [[ignore]] package pattern selects the root alone; give the root a unique name to record it. A finding about a file
(unused-files, unused-exports) is recorded for that file, so a new unused file or export elsewhere fails the run.
Give write and prune the lint flags your CI run uses (--strict, --production, --config ci.toml), so the
baseline holds the findings that run reports; in a repository of several projects, -r gives each its own baseline.
A baseline belongs to one mode: prune in a default run removes the entries only a --strict run reports, and the
other way round. Setting the mode in the file ([js] strict, [js] isolate-workspaces) makes every run use it,
write and prune included. A project that ran knip twice, once in the default mode for the development
dependencies and once with --strict for isolation, can run skif once with [js] isolate-workspaces = true: one
mode, one baseline, and stale-js-config judges each ignore-dependencies entry against that one run.
See the CLI reference for the flags.
What stays by hand
Section titled “What stays by hand”- Values that are only known at run time, and everything the report marks
HorX. - Severities: syncpack’s
severityand knip’s configuration hints are not carried over one to one. - Fixtures: knip reports files and exports in
fixturesand__fixtures__directories as unused, skif does not. Set[js] include-fixtures = trueto keep knip’s behaviour; the command does not write it. - The scripts and CI jobs that still run the old tools: replace them with
skifonce the report is clean. The command does not edit them.