Skip to content

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.

Terminal window
skif migrate --dry-run # print the skif.toml and the report, write nothing
skif migrate # write ./skif.toml for every tool found
skif migrate --from knip # one tool only
skif migrate --from sherif,knip # several tools in one run
skif migrate --merge # add the translation to an existing skif.toml

JavaScript 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.

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.

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.

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.

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

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.0 ranks below 14.2.3 and --fix --select highest rewrites the prerelease to the older stable version (QuiiBz/sherif#164). skif orders versions as npm does: a prerelease ranks below its own release only, so version-mismatch aligns on 15.0.0-rc.0 and reports 14.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-versions every specifier its parser rejects: npm ranges such as >=1.2.0 <2.0.0 or ^1.0.0 || ^2.0.0, and dist-tags such as latest. skif parses npm’s range syntax, so these take part in version-mismatch; latest or a dist-tag that differs from the other specifiers is reported as a mismatch that has no fix. Changes results: new version-mismatch errors, unless the configuration comes from skif 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 a package.json, so the directories in between are not reported as missing a manifest; QuiiBz/sherif#161), applies glob negations such as !**/test/**, and matches packages/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 .cmd shim corepack installs (QuiiBz/sherif#110). skif takes the packageManager field first, then the lockfiles of the workspace root, never asks, runs the install in the workspace root, and finds the executable through PATHEXT.
  • CI detection. sherif refuses --fix whenever CI is set, including CI=false. skif refuses it only when CI is truthy: set, not empty, and not 0, false, no or off.
  • Exit codes. sherif exits 1 both for findings and when it cannot run (no workspace declaration, an invalid package.json, a failed install). skif exits 1 for findings only and 2 when it cannot run (see Exit codes). Changes results: a script that tests for exit 1 misses a run that failed.
  • No workspace declaration. sherif stops with an error when the root has neither workspaces nor pnpm-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 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:

  1. its own comment: on the lines directly above the entry, or after it on the line where it ends;
  2. 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;
  3. 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 image
ignoreBinaries: ['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.

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.

--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:

Terminal window
skif migrate --from sherif
skif migrate --from knip --merge

The 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.

A repository rarely starts clean. Record what is there as a baseline, fix it over time, and keep CI from accepting new findings:

Terminal window
skif baseline write # record every error and warning in skif.baseline.toml
skif # clean: skif.toml now extends the baseline
skif baseline prune # after fixing some findings, drop the entries that match nothing
skif baseline check --base origin/main # in CI: fail when the baseline gained entries

write 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.

  • Values that are only known at run time, and everything the report marks H or X.
  • Severities: syncpack’s severity and knip’s configuration hints are not carried over one to one.
  • Fixtures: knip reports files and exports in fixtures and __fixtures__ directories as unused, skif does not. Set [js] include-fixtures = true to keep knip’s behaviour; the command does not write it.
  • The scripts and CI jobs that still run the old tools: replace them with skif once the report is clean. The command does not edit them.