Integrations
GitHub Action
Section titled “GitHub Action”- uses: actions/checkout@v7- uses: polylint/skif@v0.8 with: fail-on-warnings: true| Input | Meaning |
|---|---|
version |
skif version to install. Defaults to the version this release of the action was published with, whatever ref (tag, floating tag or commit SHA) uses it. |
args |
Extra skif arguments: one line is split on spaces; several lines are one argument per line, so an argument may contain spaces. |
working-directory |
Directory to run skif in. |
fail-on-warnings |
Exit non-zero on any warning. Not added when args starts with a subcommand such as baseline or migrate. |
from-sherif |
true or false (default): migration aid that lints with the translated sherif settings of a project that has no skif configuration yet (below). |
install-only |
Put skif on PATH without running it. |
token |
Token for the GitHub API and the release download. Defaults to the workflow’s GITHUB_TOKEN. |
repository |
Advanced: the owner/repo the release assets come from. Defaults to polylint/skif. |
verify-attestation |
Verify the archive’s build provenance with gh attestation verify (default true). |
A job that replaces sherif can keep its settings with from-sherif: true, a migration aid that is off by default.
With it, when no skif.toml or .skif.toml is found (in the working directory,
above it up to the repository root, or anywhere git tracks one) and the root package.json has a sherif key or a
script that runs sherif ("lint:deps": "sherif -i react -r unordered-dependencies"), the action runs
skif migrate --from sherif --profile full into a temporary file and lints with --config <that file>. The flags are
translated as skif migrate translates them, and skif’s default rules stay on. A setting that
needs a human is reported as a warning and the rest still applies; a translation that fails is a warning and skif runs
without it. The action does not do this for a skif subcommand in args (rules, update, …), when args has
--config or --no-config. The translation is done by the action, not by skif: the skif binary never reads sherif
configuration while linting (ADR 0003). Commit the output of
skif migrate to settle the configuration and drop the input; from then on the action reads skif.toml.
skif baseline write, prune and check get the translation too, through a temporary file that extends it and then
the baseline file (--file, or skif.baseline.toml), since a baseline applies only through a configuration that
extends it.
A release moves a floating tag: @vN for a stable major N from 1 on, and @v0.M for a 0.x line. @v0 itself never
moves, because a 0.x minor release may break; pin @v0.7 to take every 0.7.x patch and nothing else. Every release of the action installs the skif version it was
published with, so a full tag such as @v0.7.0 or a commit SHA never changes the installed version. The action
downloads the release archive for the runner and verifies it against the release’s checksums.txt (again on every
cache hit) and, where the gh CLI has the attestation command, against its build-provenance attestation.
The attestation must come from the repository’s publish.yaml workflow (gh attestation verify --signer-workflow), so an
attestation made by any other workflow does not pass. A release up to v0.6.0 is also accepted when attested by
Goldziher/skif, the repository before the move to polylint. Outputs are version and path.
Code scanning with SARIF:
- uses: polylint/skif@v0.8 with: args: --format sarif --output skif.sarif- uses: github/codeql-action/upload-sarif@v4 if: always() with: sarif_file: skif.sarifWhen GITHUB_ACTIONS=true and no --format is given, skif prints the human report plus GitHub annotations.
--format markdown (or disclosure, with each rule folded in a <details> section) renders a report to post as a
pull request comment, and --format codeowners groups the findings by the owners in the repository’s CODEOWNERS file.
GitLab CI
Section titled “GitLab CI”--format codeclimate writes the Code Climate JSON that GitLab Code Quality reads, so findings appear in the merge
request widget and diff:
skif: image: node:lts script: - npx @polylint/skif --format codeclimate --output gl-code-quality.json artifacts: when: always reports: codequality: gl-code-quality.jsonExit code 1 fails the job when errors remain; add allow_failure: true to report without blocking the pipeline.
One run can write several reports. Each --format FORMAT=FILE goes to its own file and at most one format goes to
stdout, so this job keeps the human report in the job log, the JSON report as an artifact for scripts and the Code
Quality report for the merge request:
skif: image: node:lts script: - npx @polylint/skif --format human --format json=skif.json --format codeclimate=gl-code-quality.json artifacts: when: always paths: - skif.json reports: codequality: gl-code-quality.jsonA run that fails before writing (a broken configuration, a rendering that fails) writes and replaces no file. A write that fails partway can leave the files written before it in place.
Git hooks
Section titled “Git hooks”skif belongs in a pre-commit hook: a mismatched version or an unsorted dependency map is cheapest to fix before
it is committed. Both hooks lint the whole workspace (pass_filenames: false) and pass --no-js, because
JavaScript analysis reads every source file and belongs in CI. The fix hook also passes --no-install, so a
commit never runs a package manager, and it is refused when CI is set.
pre-commit and prek
Section titled “pre-commit and prek”repos: - repo: https://github.com/polylint/skif rev: v0.8.0 # use the latest release tag hooks: - id: skif # skif --no-js - id: skif-fix # skif --fix --no-install --no-prompt --no-js (opt-in, rewrites manifests)Both hooks run scripts/pre-commit/run-skif.sh, which needs neither Rust nor Node. It uses, in order,
SKIF_BINARY (an error if it is not executable), skif on PATH, then the release pinned by the hook revision,
downloaded once into ~/.cache/skif/pre-commit and verified against checksums.txt (and its build attestation, as the action checks it, when an authenticated gh is
available).
The hooks run when package.json, pnpm-workspace.yaml, skif.toml or .skif.toml change. A configuration file
that is only reached through extends can have any name and does not trigger them; add its path to the hook’s
files pattern, or run skif yourself after changing it.
Add skif as a managed source in poly.toml:
[[hooks.sources]]id = "skif"git = "https://github.com/polylint/skif.git"revision = "v0.8.0" # use the latest release taghooks = ["skif"]poly-hooks.toml also provides skif-fix. Each hook has a system channel (skif on PATH) and an npm
channel pinned to the release version (pnpm dlx @polylint/skif@<version>). Then:
poly hooks updategit add poly.toml poly-hooks.lockpoly hooks installLefthook
Section titled “Lefthook”Lefthook is configured on the consumer side, so nothing ships from the skif repository:
pre-commit: commands: skif: glob: "{package.json,**/package.json,pnpm-workspace.yaml,skif.toml,.skif.toml}" run: skif --no-jsWrap the skif binary in a native_binary target and run bazel run //:skif, or bazel run //:skif -- --fix.
Under bazel run the binary, and the npm package’s skif bin, first change to the directory you ran Bazel from, so
relative paths resolve against the source tree instead of the runfiles tree. Under bazel test, --cache keeps its
store in $TEST_TMPDIR/skif/. The Bazel guide covers fetching the release archives, bazel test
inputs, what skif reads from BUILD and MODULE.bazel files, and its limits.
Turborepo, Nx and Lerna
Section titled “Turborepo, Nx and Lerna”Run skif once at the workspace root, as a root script or a root task, not as a task of every package. See Turborepo, Nx and Lerna.
npm and Bun
Section titled “npm and Bun”The @polylint/skif package is a native addon built with napi-rs for the Node.js lines that are not end-of-life (22, 24 and 26; see the Node.js release schedule) and Bun 1.x; older versions may work but are not supported. It is ESM only (from CommonJS use import(), or require() on Node 22.12+), has no install script,
and downloads nothing at install time: one platform package per target is an optional dependency, so your package
manager installs only the one that matches the machine: macOS, Linux (glibc and musl) and Windows, each on x64 and arm64.
import { lint, lintAsync, run } from "@polylint/skif";
const report = JSON.parse(lint("./my-monorepo", { production: true }));console.log(report.summary);
const outcome = await lintAsync("./my-monorepo");if (outcome.error) console.error(outcome.error.kind, outcome.error.message, outcome.error.path);else console.log(JSON.parse(outcome.report).summary);
const exitCode = run(["--format", "json", "./my-monorepo"]);lint(path, options?)lints the project containingpathand returns the JSON report as a string. With{ recursive: true }it lints every workspace and standalone package at or belowpath, likeskif -r, and the report gains arootsarray. It applies the CLI’s configuration checks ([lint] require-ignore-reasons,[js] tsconfig), writes no files and prints only the CLI’s warnings, to stderr. It blocks the event loop, so uselintAsyncin a server. The options mirror the flags of the same name:noJs,production,failOnWarnings,ignoreRules,ignorePackages,ignoreDependencies,recursive,config(use that file and the files it extends instead of discoveringskif.tomlfiles) andnoConfig(read no file). The optionstypeAwareandnoTypeAwarewere removed in 0.9.0 with type-aware analysis and are rejected with the message of the removed flags.lintAsync(path, options?)does the same on a worker thread and resolves with{ report }or, when the lint cannot run,{ error: { kind, message, path? } }.kindisconfig,workspace,io,usage,ci-refusalorinternal.run(argv)runs the full command line (argvexcludes the program name) and returns its exit code. Output streams to the process’s stdout and stderr. It never changes the process’s current directory, also underbazel run; the package’sskifbin does that before it callsrun(Bazel).
Types ship in index.d.ts. Both lint and lintAsync read the configuration file the way the command line does.