use std::collections::BTreeMap;
use std::io::{self, BufRead, Write};
use std::path::PathBuf;
use std::sync::Arc;
use clap::{CommandFactory, Parser};
use serde_json::{Map, Value, json};
use skif::MemoryModuleCache;
use crate::args::{ConfigArgs, ExplainUsageArgs, Format, LintArgs, RulesArgs};
use crate::error::{CliError, Kind};
use crate::explain::{self, Failure};
use crate::lint::{canonical, run_captured};
use crate::module_cache::CacheHost;
use crate::output::{error_document, stderr_line};
const PROTOCOL_VERSIONS: [&str; 4] = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
const PARSE_ERROR: i64 = -32700;
const INVALID_REQUEST: i64 = -32600;
const METHOD_NOT_FOUND: i64 = -32601;
const INVALID_PARAMS: i64 = -32602;
const MAX_LINE: usize = 64 * 1024 * 1024;
const COULD_NOT_RUN: u8 = 2;
const INSTRUCTIONS: &str = "skif lints JavaScript and TypeScript monorepos: workspace and manifest rules, version \
policies, unused dependencies, files and exports. Each tool returns the JSON of the `skif` command it names. An \
argument is the flag of the same name (`max_show_issues` is `--max-show-issues`); errors name the flags; paths are \
relative to the server's working directory. Nothing is written: apply fixes with `skif --fix`.";
#[derive(Debug, Parser)]
#[command(name = "skif", no_binary_name = true)]
struct LintCommand {
#[command(flatten)]
args: LintArgs,
}
#[derive(Debug, Parser)]
#[command(name = "skif explain-usage", no_binary_name = true)]
struct ExplainCommand {
#[command(flatten)]
args: ExplainUsageArgs,
}
#[derive(Debug, Parser)]
#[command(name = "skif config", no_binary_name = true)]
struct ConfigCommand {
#[command(flatten)]
args: ConfigArgs,
}
#[derive(Debug, Parser)]
#[command(name = "skif rules", no_binary_name = true)]
struct RulesCommand {
#[command(flatten)]
args: RulesArgs,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Shape {
Flag,
Text,
Count,
List,
}
struct Param {
name: &'static str,
id: Option<&'static str>,
shape: Shape,
description: &'static str,
}
const fn param(name: &'static str, shape: Shape, description: &'static str) -> Param {
Param {
name,
id: Some(name),
shape,
description,
}
}
struct Tool {
name: &'static str,
title: &'static str,
description: &'static str,
command: fn() -> clap::Command,
fixed: &'static [&'static str],
params: &'static [Param],
implied: &'static [&'static str],
}
const PATH: Param = param("path", Shape::Text, "A directory or file in the project; default `.`.");
const RECURSIVE: Param = param("recursive", Shape::Flag, "Every root at or below `path`.");
const CONFIG: Param = param("config", Shape::Text, "This config file instead of discovered ones.");
const NO_CONFIG: Param = param("no_config", Shape::Flag, "Read no config file.");
const INCLUDE: Param = param(
"include",
Shape::List,
"Only these rule IDs or knip issue types; enables off rules.",
);
const EXCLUDE: Param = param("exclude", Shape::List, "Not these rule IDs or knip issue types.");
const WORKSPACE: Param = param(
"workspace",
Shape::List,
"Only findings of these packages: name, directory or glob; `!` negates.",
);
const PRODUCTION: Param = param("production", Shape::Flag, "Production code only.");
const STRICT: Param = param("strict", Shape::Flag, "knip's strict mode; implies `production`.");
const NO_JS: Param = param("no_js", Shape::Flag, "Skip the JavaScript analysis.");
const TOOLS: &[Tool] = &[
Tool {
name: "lint",
title: "Lint a monorepo",
description: "`skif --format json`: the lint report. Findings are not an error.",
command: LintCommand::command,
fixed: &["--format", "json", "--no-type-aware"],
params: &[
PATH,
RECURSIVE,
CONFIG,
NO_CONFIG,
INCLUDE,
EXCLUDE,
WORKSPACE,
PRODUCTION,
STRICT,
NO_JS,
param(
"max_show_issues",
Shape::Count,
"At most N findings per rule; `summary` counts all.",
),
param(
"fix",
Shape::Flag,
"Plan safe fixes (`--dry-run`): adds `fix.changes`, unified diffs.",
),
param("fix_unsafe", Shape::Flag, "Plan unsafe fixes too."),
param(
"fix_type",
Shape::List,
"Only the fixes of these rule IDs or issue types.",
),
param("select", Shape::Text, "The version alignment fixes target."),
param("allow_remove_files", Shape::Flag, "Plan file deletions."),
],
implied: &["--dry-run"],
},
Tool {
name: "explain_usage",
title: "Explain why a file, export or dependency is used",
description: "`skif explain-usage --format json`: why a file, export or dependency counts as used.",
command: ExplainCommand::command,
fixed: &["--format", "json", "--no-type-aware"],
params: &[
Param {
name: "file",
id: Some("target"),
shape: Shape::Text,
description: "The source file.",
},
Param {
name: "export",
id: None,
shape: Shape::Text,
description: "One export of `file`.",
},
param("dependency", Shape::Text, "Explain this dependency instead of a file."),
param(
"package",
Shape::Text,
"With `dependency`: this package only (name or directory).",
),
param("path", Shape::Text, "A directory in the project; default `.`."),
param("production", Shape::Flag, "The production-only analysis."),
CONFIG,
NO_CONFIG,
],
implied: &[],
},
Tool {
name: "config",
title: "Show the effective configuration",
description: "`skif config --format json`: the config files of each root and the merged config.",
command: ConfigCommand::command,
fixed: &["--format", "json"],
params: &[
PATH,
RECURSIVE,
param(
"explain",
Shape::Text,
"Explain this key (`rules.ID.level`): its assignments and final value.",
),
param("package", Shape::Text, "With `explain`: this package's overrides too."),
CONFIG,
NO_CONFIG,
],
implied: &["--show"],
},
Tool {
name: "list_rules",
title: "List skif's rules",
description: "`skif rules --format json`: every rule with its ID, default level and fixability.",
command: RulesCommand::command,
fixed: &["--format", "json"],
params: &[],
implied: &[],
},
];
pub fn run() -> u8 {
match serve(io::stdin().lock(), io::stdout().lock()) {
Ok(()) => 0,
Err(error) => {
stderr_line(&format!("error: skif mcp: {error}"));
2
}
}
}
pub fn serve(input: impl BufRead, output: impl Write) -> io::Result<()> {
serve_limited(input, output, MAX_LINE)
}
fn serve_limited(mut input: impl BufRead, mut output: impl Write, limit: usize) -> io::Result<()> {
let mut caches = Caches::new();
loop {
let mut bytes = Vec::new();
let cap = u64::try_from(limit).unwrap_or(u64::MAX).saturating_add(1);
if io::Read::take(&mut input, cap).read_until(b'\n', &mut bytes)? == 0 {
return Ok(());
}
let reply = if bytes.len() > limit && bytes.last() != Some(&b'\n') {
skip_line(&mut input)?;
Some(error_reply(
&Value::Null,
RpcError(INVALID_REQUEST, format!("a message longer than {limit} bytes")),
))
} else {
let line = String::from_utf8(bytes).map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
if line.trim().is_empty() {
continue;
}
let reply = handle_line(&line, &mut caches);
skif_core::timing::flush_stderr();
reply
};
let Some(reply) = reply else {
continue;
};
let mut bytes = serde_json::to_vec(&reply).map_err(io::Error::other)?;
bytes.push(b'\n');
match output.write_all(&bytes).and_then(|()| output.flush()) {
Err(error) if error.kind() == io::ErrorKind::BrokenPipe => return Ok(()),
result => result?,
}
}
}
fn skip_line(input: &mut impl BufRead) -> io::Result<()> {
loop {
let buffer = input.fill_buf()?;
if buffer.is_empty() {
return Ok(());
}
if let Some(newline) = buffer.iter().position(|&byte| byte == b'\n') {
input.consume(newline + 1);
return Ok(());
}
let length = buffer.len();
input.consume(length);
}
}
struct RpcError(i64, String);
impl RpcError {
fn params(message: impl Into<String>) -> Self {
Self(INVALID_PARAMS, message.into())
}
}
fn error_reply(id: &Value, RpcError(code, message): RpcError) -> Value {
json!({ "jsonrpc": "2.0", "id": id, "error": { "code": code, "message": message } })
}
type Caches = BTreeMap<(PathBuf, bool), Arc<MemoryModuleCache>>;
fn handle_line(line: &str, caches: &mut Caches) -> Option<Value> {
let message: Value = match serde_json::from_str(line) {
Ok(message) => message,
Err(error) => {
return Some(error_reply(
&Value::Null,
RpcError(PARSE_ERROR, format!("parse error: {error}")),
));
}
};
let Value::Object(message) = message else {
return Some(error_reply(
&Value::Null,
RpcError(
INVALID_REQUEST,
"expected one JSON-RPC message object; batches are not supported".to_owned(),
),
));
};
let id = message.get("id").cloned();
let response = message.contains_key("result") || message.contains_key("error");
if !response
&& id
.as_ref()
.is_some_and(|id| !(id.is_string() || id.is_number() || id.is_null()))
{
return Some(error_reply(
&Value::Null,
RpcError(INVALID_REQUEST, "`id` must be a string, a number or null".to_owned()),
));
}
if message.get("jsonrpc").and_then(Value::as_str) != Some("2.0") {
return Some(error_reply(
id.as_ref().unwrap_or(&Value::Null),
RpcError(INVALID_REQUEST, "`jsonrpc` must be \"2.0\"".to_owned()),
));
}
let Some(method) = message.get("method").and_then(Value::as_str) else {
return match id {
Some(id) if !response => Some(error_reply(
&id,
RpcError(INVALID_REQUEST, "a request needs a `method`".to_owned()),
)),
_ => None,
};
};
let params = message.get("params").cloned().unwrap_or(Value::Null);
let id = id?;
Some(match dispatch(method, ¶ms, caches) {
Ok(result) => json!({ "jsonrpc": "2.0", "id": id, "result": result }),
Err(error) => error_reply(&id, error),
})
}
fn dispatch(method: &str, params: &Value, caches: &mut Caches) -> Result<Value, RpcError> {
match method {
"initialize" => Ok(initialize(params)),
"ping" => Ok(json!({})),
"tools/list" => Ok(json!({ "tools": tools() })),
"tools/call" => call(params, caches),
other => Err(RpcError(METHOD_NOT_FOUND, format!("method not found: {other}"))),
}
}
fn negotiate(requested: Option<&str>) -> &'static str {
PROTOCOL_VERSIONS
.iter()
.find(|version| Some(**version) == requested)
.copied()
.unwrap_or(PROTOCOL_VERSIONS[0])
}
fn initialize(params: &Value) -> Value {
json!({
"protocolVersion": negotiate(params.get("protocolVersion").and_then(Value::as_str)),
"capabilities": { "tools": { "listChanged": false } },
"serverInfo": { "name": "skif", "title": "skif", "version": env!("CARGO_PKG_VERSION") },
"instructions": INSTRUCTIONS,
})
}
fn tools() -> Value {
let read_only =
json!({ "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false });
Value::Array(
TOOLS
.iter()
.map(|tool| {
let command = (tool.command)();
let properties: Map<String, Value> = tool
.params
.iter()
.map(|param| (param.name.to_owned(), param_schema(&command, param)))
.collect();
json!({
"name": tool.name,
"title": tool.title,
"description": tool.description,
"inputSchema": { "type": "object", "properties": properties, "additionalProperties": false },
"annotations": read_only,
})
})
.collect(),
)
}
fn param_schema(command: &clap::Command, param: &Param) -> Value {
let mut schema = match param.shape {
Shape::Flag => json!({ "type": "boolean" }),
Shape::Text => json!({ "type": "string" }),
Shape::Count => json!({ "type": "integer", "minimum": 0 }),
Shape::List => json!({ "type": "array", "items": { "type": "string" } }),
};
let choices: Vec<String> = param
.id
.and_then(|id| command.get_arguments().find(|arg| arg.get_id() == id))
.map_or_else(Vec::new, |arg| {
arg.get_possible_values()
.iter()
.filter(|value| !value.is_hide_set())
.map(|value| value.get_name().to_owned())
.collect()
});
if !choices.is_empty() && param.shape != Shape::Flag {
schema["enum"] = json!(choices);
}
schema["description"] = json!(param.description);
schema
}
fn call(params: &Value, caches: &mut Caches) -> Result<Value, RpcError> {
let name = params
.get("name")
.and_then(Value::as_str)
.ok_or_else(|| RpcError::params("`tools/call` needs a tool `name`"))?;
let empty = Map::new();
let arguments = match params.get("arguments") {
None | Some(Value::Null) => &empty,
Some(Value::Object(arguments)) => arguments,
Some(_) => return Err(RpcError::params("`arguments` must be an object")),
};
let tool = TOOLS
.iter()
.find(|tool| tool.name == name)
.ok_or_else(|| RpcError::params(format!("unknown tool: {name}")))?;
if let Some(key) = arguments
.keys()
.find(|key| !tool.params.iter().any(|param| param.name == key.as_str()))
{
return Err(RpcError::params(format!("unknown argument `{key}`")));
}
let outcome = match tool.name {
"lint" => lint(tool, arguments, caches),
"explain_usage" => explain_usage(tool, arguments),
"config" => config(tool, arguments),
_ => list_rules(tool, arguments),
};
Ok(tool_result(outcome))
}
fn command_line(tool: &Tool, arguments: &Map<String, Value>, extra: &[&str]) -> Result<Vec<String>, Failure> {
let mut command = (tool.command)();
command.build();
let mut argv: Vec<String> = tool.fixed.iter().chain(extra).map(|flag| (*flag).to_owned()).collect();
let mut positionals: Vec<(usize, String)> = Vec::new();
for param in tool.params {
let Some(id) = param.id else {
continue;
};
let Some(value) = arguments.get(param.name).filter(|value| !value.is_null()) else {
continue;
};
let arg = command
.get_arguments()
.find(|arg| arg.get_id() == id)
.ok_or_else(|| plain(CliError::new(Kind::Internal, format!("`{}` has no flag", param.name))))?;
let values = match (param.shape, value) {
(Shape::Flag, Value::Bool(false)) => Vec::new(),
(Shape::Flag, Value::Bool(true)) => {
argv.push(format!("--{}", arg.get_long().unwrap_or(id)));
continue;
}
(Shape::Text, Value::String(text)) => vec![text.clone()],
(Shape::Count, Value::Number(number)) if number.is_u64() => vec![number.to_string()],
(Shape::List, Value::Array(items)) if items.iter().all(Value::is_string) => {
items.iter().filter_map(Value::as_str).map(str::to_owned).collect()
}
(shape, _) => {
let expected = match shape {
Shape::Flag => "a boolean",
Shape::Text => "a string",
Shape::Count => "a non-negative integer",
Shape::List => "an array of strings",
};
return Err(usage(format!("`{}` must be {expected}", param.name)));
}
};
match (arg.get_long(), arg.get_index()) {
(Some(long), _) => argv.extend(values.into_iter().map(|value| format!("--{long}={value}"))),
(None, index) => positionals.extend(values.into_iter().map(|value| (index.unwrap_or(usize::MAX), value))),
}
}
if !positionals.is_empty() {
positionals.sort_by_key(|(index, _)| *index);
argv.push("--".to_owned());
argv.extend(positionals.into_iter().map(|(_, value)| value));
}
Ok(argv)
}
fn folded(arguments: &Map<String, Value>) -> Result<Map<String, Value>, Failure> {
let mut arguments = arguments.clone();
match arguments.remove("export") {
None | Some(Value::Null) => {}
Some(Value::String(export)) => match arguments.get_mut("file") {
Some(Value::String(file)) => {
file.push('#');
file.push_str(&export);
}
_ => return Err(usage("`export` needs `file`")),
},
Some(_) => return Err(usage("`export` must be a string")),
}
Ok(arguments)
}
fn parse<C: Parser>(tool: &Tool, arguments: &Map<String, Value>, extra: &[&str]) -> Result<C, Failure> {
let argv = command_line(tool, &folded(arguments)?, extra)?;
let mut command = (tool.command)();
command
.try_get_matches_from_mut(argv)
.and_then(|mut matches| C::from_arg_matches_mut(&mut matches))
.map_err(|error| usage(clap_message(&error)))
}
fn clap_message(error: &clap::Error) -> String {
let rendered = error.render().to_string();
let first = rendered.lines().next().unwrap_or_default();
first.strip_prefix("error: ").unwrap_or(first).to_owned()
}
fn plain(error: CliError) -> Failure {
Box::new((error, Map::new()))
}
fn usage(message: impl Into<String>) -> Failure {
plain(CliError::new(Kind::Usage, message))
}
fn parsed(text: &[u8]) -> Result<Value, Failure> {
serde_json::from_slice(text).map_err(|error| plain(CliError::new(Kind::Internal, error.to_string())))
}
type Answer = (Value, bool);
fn tool_result(outcome: Result<Answer, Failure>) -> Value {
let (document, is_error) = outcome.unwrap_or_else(|failure| {
let (error, extra) = *failure;
let text = error_document(&error, extra).unwrap_or_default();
let document = serde_json::from_str(&text).unwrap_or_else(|_| json!({ "error": { "message": error.message } }));
(document, true)
});
let text = serde_json::to_string(&document).unwrap_or_default();
json!({
"content": [{ "type": "text", "text": text }],
"structuredContent": document,
"isError": is_error,
})
}
fn lint_args(tool: &Tool, arguments: &Map<String, Value>) -> Result<LintArgs, Failure> {
let mut args = parse::<LintCommand>(tool, arguments, &[])?.args;
args.dry_run = args.fixing();
Ok(args)
}
fn config_args(tool: &Tool, arguments: &Map<String, Value>) -> Result<ConfigArgs, Failure> {
let show = if arguments.get("explain").is_none_or(Value::is_null) {
tool.implied
} else {
&[]
};
Ok(parse::<ConfigCommand>(tool, arguments, show)?.args)
}
fn lint(tool: &Tool, arguments: &Map<String, Value>, caches: &mut Caches) -> Result<Answer, Failure> {
let args = lint_args(tool, arguments)?;
let cache = canonical(&args.path)
.ok()
.map(|start| Arc::clone(caches.entry((start, args.recursive)).or_default()));
let (stdout, code) = run_captured(&args, cache.as_ref().map(|cache| cache as &dyn CacheHost)).map_err(plain)?;
Ok((parsed(&stdout)?, code == COULD_NOT_RUN))
}
fn explain_usage(tool: &Tool, arguments: &Map<String, Value>) -> Result<Answer, Failure> {
let args = parse::<ExplainCommand>(tool, arguments, &[])?.args;
let cwd = std::env::current_dir().map_err(|error| {
plain(CliError::new(
Kind::Io,
format!("cannot read the current directory: {error}"),
))
})?;
let text = explain::render(&args, &cwd, Format::Json)?;
Ok((parsed(text.as_bytes())?, false))
}
fn config(tool: &Tool, arguments: &Map<String, Value>) -> Result<Answer, Failure> {
let args = config_args(tool, arguments)?;
let (text, failures) = crate::config::render(&args).map_err(plain)?;
Ok((parsed(text.as_bytes())?, !failures.is_empty()))
}
fn list_rules(tool: &Tool, arguments: &Map<String, Value>) -> Result<Answer, Failure> {
let args = parse::<RulesCommand>(tool, arguments, &[])?.args;
let text = crate::commands::render(&args).map_err(plain)?;
Ok((parsed(text.as_bytes())?, false))
}
#[cfg(test)]
mod parity;
#[cfg(test)]
mod tests {
use super::*;
fn exchange(lines: &[Value]) -> Vec<Value> {
let input: String = lines.iter().map(|line| line.to_string() + "\n").collect();
let mut output = Vec::new();
serve(input.as_bytes(), &mut output).unwrap();
String::from_utf8(output)
.unwrap()
.lines()
.map(|line| serde_json::from_str(line).unwrap())
.collect()
}
#[test]
fn the_version_is_negotiated() {
assert_eq!(negotiate(Some("2025-06-18")), "2025-06-18");
assert_eq!(negotiate(Some("2024-11-05")), "2024-11-05");
assert_eq!(negotiate(Some("1999-01-01")), PROTOCOL_VERSIONS[0]);
assert_eq!(negotiate(None), PROTOCOL_VERSIONS[0]);
}
#[test]
fn notifications_and_responses_get_no_answer() {
let replies = exchange(&[
json!({ "jsonrpc": "2.0", "method": "notifications/initialized" }),
json!({ "jsonrpc": "2.0", "id": 9, "result": {} }),
json!({ "jsonrpc": "2.0", "id": 1, "method": "ping" }),
]);
assert_eq!(replies, vec![json!({ "jsonrpc": "2.0", "id": 1, "result": {} })]);
}
#[test]
fn malformed_messages_get_json_rpc_errors() {
let input =
"{not json\n[]\n{\"jsonrpc\":\"1.0\",\"id\":2,\"method\":\"ping\"}\n{\"jsonrpc\":\"2.0\",\"id\":3}\n";
let mut output = Vec::new();
serve(input.as_bytes(), &mut output).unwrap();
let codes: Vec<(Value, i64)> = String::from_utf8(output)
.unwrap()
.lines()
.map(|line| {
let reply: Value = serde_json::from_str(line).unwrap();
(reply["id"].clone(), reply["error"]["code"].as_i64().unwrap())
})
.collect();
assert_eq!(
codes,
vec![
(Value::Null, PARSE_ERROR),
(Value::Null, INVALID_REQUEST),
(json!(2), INVALID_REQUEST),
(json!(3), INVALID_REQUEST),
]
);
}
#[test]
fn an_id_that_is_not_a_string_number_or_null_is_an_invalid_request() {
let replies = exchange(&[
json!({ "jsonrpc": "2.0", "id": { "a": 1 }, "method": "ping" }),
json!({ "jsonrpc": "2.0", "id": [1], "method": "ping" }),
json!({ "jsonrpc": "2.0", "id": true, "method": "ping" }),
json!({ "jsonrpc": "2.0", "id": "x", "method": "ping" }),
]);
let error = json!({ "jsonrpc": "2.0", "id": null, "error": {
"code": INVALID_REQUEST, "message": "`id` must be a string, a number or null"
} });
assert_eq!(replies[..3], [error.clone(), error.clone(), error]);
assert_eq!(replies[3], json!({ "jsonrpc": "2.0", "id": "x", "result": {} }));
}
#[test]
fn a_line_above_the_cap_is_refused_and_the_next_line_is_served() {
let long = format!(
"{{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\",\"pad\":\"{}\"}}",
"x".repeat(200)
);
let input = format!("{long}\n{}\n", json!({ "jsonrpc": "2.0", "id": 2, "method": "ping" }));
let mut output = Vec::new();
serve_limited(input.as_bytes(), &mut output, 64).unwrap();
let replies: Vec<Value> = String::from_utf8(output)
.unwrap()
.lines()
.map(|line| serde_json::from_str(line).unwrap())
.collect();
assert_eq!(replies.len(), 2, "{replies:?}");
assert_eq!(replies[0]["id"], Value::Null);
assert_eq!(replies[0]["error"]["code"], INVALID_REQUEST);
assert_eq!(replies[1], json!({ "jsonrpc": "2.0", "id": 2, "result": {} }));
}
#[test]
fn bad_arguments_are_invalid_params_or_tool_errors() {
let replies = exchange(&[
json!({ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "fix" } }),
json!({ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "lint", "arguments": { "bogus": 1 } } }),
json!({ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "lint", "arguments": { "recursive": "yes" } } }),
]);
assert_eq!(replies[0]["error"]["code"], INVALID_PARAMS);
assert_eq!(replies[1]["error"]["code"], INVALID_PARAMS);
assert_eq!(replies[2]["result"]["isError"], true);
assert_eq!(replies[2]["result"]["structuredContent"]["error"]["kind"], "usage");
}
}