diff --git a/STABILITY.md b/STABILITY.md new file mode 100644 index 00000000..a4f13d76 --- /dev/null +++ b/STABILITY.md @@ -0,0 +1,128 @@ +# Sephera Stability Policy + +**Version:** 2.0.0 +**Status:** The 2.0.0 stability promise. + +This document states what Sephera 2.0.0 guarantees to its users. It is the +contract behind the version number. If a change would break something listed +here, it is a breaking change and needs a major version bump. + +## Scope + +Sephera is a **CLI tool**. The stability promise covers: + +1. **The CLI** — 24 commands, their flags, their JSON output shapes, their exit codes. +2. **The MCP server** — 21 tools, their input schemas, their wire protocol. + +It does **not** cover: + +- The Rust library API. All library crates are `publish = false`; they are + implementation detail. The `sephera` binary is distributed in GitHub + release archives, not published to crates.io. +- Human-readable output formats (tables, markdown reports). These are for + humans and may change cosmetically. The JSON output is the machine contract. + +## CLI contract + +### Commands and flags + +The 24 commands and their flags are stable. Removing a command, removing a +flag, or changing a flag's meaning is a breaking change. Adding a new command +or a new optional flag is not. + +### JSON output + +The JSON output of every command that supports `--format json` (20 of the +24 commands) is a frozen contract from 2.0.0 onward. `guard`, `skill`, +`watch`, and `mcp` have no `--format` flag and are outside this contract. +Specifically: +- Top-level keys will not be removed or renamed. +- Field types will not change (a string stays a string, a number stays a number). +- New keys may be added (additive changes are not breaking). +- Key order is not guaranteed (JSON objects are unordered). + +Every command's JSON output is pinned by an insta snapshot test in +`crates/sephera_cli/tests/`. If a snapshot changes, it is a breaking change +until proven otherwise. + +### Exit codes + +- `0` — success. The analysis ran; any gate thresholds were not crossed. +- `1` — failure. The analysis could not run. An `error:` line is printed to stderr. +- `2` — gate violated. The analysis ran and a `--fail-on` threshold was crossed. +- `64` — usage error. The command line could not be parsed (unknown flag, + missing required argument). The run never started, so this cannot be + confused with a gate violation. +- `130` — interrupted. The user pressed Ctrl+C. Distinct from failure by design. + +These codes are stable. A script that checks `== 2` for gate violations will +keep working. + +### Error format + +Errors are printed to stderr as `error: `. The message text may change; +the `error:` prefix and the stderr stream are stable. + +One case is not an error report and carries no prefix: running `sephera` +with no arguments prints the help text to stderr and exits 64 (a missing +required argument), because the output is help, not an error message. + +## MCP contract + +### Tools + +The 21 tools and their names are stable. Removing a tool or renaming it is a +breaking change. Adding a new tool is not. + +### Input schemas + +Each tool's input parameters are stable. Removing a parameter or changing its +type is a breaking change. Adding a new optional parameter is not. + +### Wire protocol + +The MCP server speaks JSON-RPC 2.0 over stdio with newline-delimited JSON +framing: one JSON message per line, each terminated by `\n`. This framing is +stable. The protocol version is negotiated at initialization: the server +supports `2024-11-05`, `2025-03-26`, and `2025-06-18` (rmcp 1.3.0) and +answers with the version the client requested when it supports it, +otherwise its latest (`2025-06-18`). `2024-11-05` is the oldest +supported version, not the negotiated one. + +### Output format + +Tool outputs follow the same JSON contract as the CLI: top-level keys are +stable, new keys may be added, key order is not guaranteed. + +## What "breaking" means + +A change is **breaking** if it would require a user to change their scripts, +their MCP client configuration, or their parsing code. Specifically: + +- Removing/renaming a CLI command, flag, or MCP tool: **breaking** +- Removing/renaming a JSON key in any output: **breaking** +- Changing a JSON field's type: **breaking** +- Changing an exit code's meaning: **breaking** +- Adding a new command, flag (optional), tool, or JSON key: **not breaking** +- Changing human-readable table formatting: **not breaking** +- Changing an error message's wording (keeping the `error:` prefix): **not breaking** + +## Versioning + +Sephera follows semantic versioning for the CLI and MCP contract: + +- **Major** (3.0.0): breaking changes to the contract above. +- **Minor** (2.1.0): new commands, new tools, new optional flags, new JSON keys. +- **Patch** (2.0.1): bug fixes that do not change the contract. + +The Rust library crates are `publish = false` and do not follow semver; they +change freely with the CLI. + +## Enforcement + +- `cargo insta test --check --workspace` in CI fails on any snapshot mismatch. +- The `mcp_wire` CI job drives the MCP server over real stdio and verifies + the wire protocol. +- This document is the human-readable counterpart. When code and this document + disagree, the code's behavior (as pinned by snapshots) wins, and this + document must be updated. diff --git a/crates/sephera_cli/Cargo.toml b/crates/sephera_cli/Cargo.toml index cd6c5214..bd3c4558 100644 --- a/crates/sephera_cli/Cargo.toml +++ b/crates/sephera_cli/Cargo.toml @@ -1,4 +1,9 @@ [package] +# Not published to crates.io: Sephera ships as GitHub release archives +# (see .github/workflows/release.yml), and `cargo install --git` works +# regardless. The library crates are also publish=false; this is a CLI, +# not a library. +publish = false name = "sephera" version.workspace = true edition = "2024" @@ -8,7 +13,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Know what breaks before you touch it. Reverse dependency analysis and cycle detection for 8 languages, token-budgeted context packs, and a built-in MCP server." -documentation = "https://docs.rs/sephera" readme = "README.crates-io.md" keywords = ["loc", "context", "mcp", "llm", "tree-sitter"] categories = ["command-line-utilities", "development-tools"] diff --git a/crates/sephera_cli/src/configure.rs b/crates/sephera_cli/src/configure.rs index 5913bc66..33fc6719 100644 --- a/crates/sephera_cli/src/configure.rs +++ b/crates/sephera_cli/src/configure.rs @@ -273,11 +273,22 @@ fn discover(anchor: &Path) -> Option { } /// The value after `flag`, if present. +/// +/// A following token that looks like a flag is not a value: clap would +/// report the flag as missing its value, and swallowing the next flag +/// here would both hide that error and misread the flag as a path +/// (`loc --config --format json` read `--format` as the config filename +/// and exited 1 for a missing file instead of 64 for a missing +/// argument). A lone `-` is a value, not a flag, and `--flag=value` +/// still supplies its value directly. fn flag_value(argv: &[String], flag: &str) -> Option { let mut arguments = argv.iter(); while let Some(argument) = arguments.next() { if argument == flag { - return arguments.next().cloned(); + return match arguments.next() { + Some(value) if is_flag_like(value) => None, + value => value.cloned(), + }; } // `--flag=value` is the other spelling of the same thing. if let Some(value) = argument.strip_prefix(&format!("{flag}=")) { @@ -287,6 +298,12 @@ fn flag_value(argv: &[String], flag: &str) -> Option { None } +/// Whether a token reads as a flag rather than a value: it starts with +/// `-` and is more than the lone `-`, which clap treats as a value. +fn is_flag_like(token: &str) -> bool { + token.len() > 1 && token.starts_with('-') +} + /// The command name the user asked for, before `clap` sees it. fn requested_command<'argv>( argv: &'argv [String], diff --git a/crates/sephera_cli/src/gate.rs b/crates/sephera_cli/src/gate.rs index f21c0e57..e0745095 100644 --- a/crates/sephera_cli/src/gate.rs +++ b/crates/sephera_cli/src/gate.rs @@ -15,6 +15,7 @@ //! | 0 | analysed, nothing crossed a threshold | //! | 1 | the analysis could not run | //! | 2 | analysed, something crossed a threshold | +//! | 64 | the command line could not be parsed (usage error, sysexits `EX_USAGE`) | //! //! Merging 1 and 2 into a single non-zero would mean a broken install and a //! violated rule look identical in a log, which is the situation where someone diff --git a/crates/sephera_cli/src/run.rs b/crates/sephera_cli/src/run.rs index cc99bffb..2c946b65 100644 --- a/crates/sephera_cli/src/run.rs +++ b/crates/sephera_cli/src/run.rs @@ -59,7 +59,16 @@ use crate::{ untested, watch, why, }; -#[must_use] +/// Exit code for a command-line usage error (sysexits `EX_USAGE`). +/// +/// Distinct from [`crate::gate::GATE_VIOLATED`] (2), which means the +/// analysis ran and a `--fail-on` threshold was crossed, and from +/// [`ExitCode::FAILURE`] (1), which means the analysis could not run. +/// A usage error means the run never started: an unknown flag, a +/// missing required argument, a value that fails validation. +const USAGE_ERROR: i32 = 64; + +#[must_use = "dropping the exit code would report success for a failed run"] pub fn main_exit_code() -> ExitCode { match run() { Ok(exit) => exit, @@ -95,7 +104,25 @@ pub fn run() -> Result { // typed flag still wins. See `configure` for why this is a pre-pass rather // than a second source of defaults. let expanded = configure::expand(std::env::args().collect(), None)?; - let cli = Cli::parse_from(&expanded.argv); + // Clap's default usage-error code is 2, which the stability contract + // reserves for gate violations (`gate::GATE_VIOLATED`): a script + // checking `== 2` could not tell "you mistyped a flag" from "a + // threshold was crossed". Usage errors are `EX_USAGE` (64) instead — + // the sysexits convention for a command-line usage error — while + // `--help` and `--version` still exit 0: their error carries exit + // code 0 and is passed through unchanged. + let cli = match Cli::try_parse_from(&expanded.argv) { + Ok(cli) => cli, + Err(error) => { + let code = if error.exit_code() == 0 { + 0 + } else { + USAGE_ERROR + }; + let _ = error.print(); + std::process::exit(code); + } + }; progress::set_mode(cli.progress); // `watch` keeps a blocking loop over `notify`'s synchronous receiver, so it diff --git a/crates/sephera_cli/tests/json_contracts.rs b/crates/sephera_cli/tests/json_contracts.rs new file mode 100644 index 00000000..1e0a07b5 --- /dev/null +++ b/crates/sephera_cli/tests/json_contracts.rs @@ -0,0 +1,778 @@ +//! JSON output contract snapshots for the 2.0.0 stability promise. +//! +//! Every command with `--format json` has its output shape pinned here. +//! If a snapshot changes, it is a breaking change until proven otherwise. +//! See STABILITY.md for the full contract. +//! +//! Commands without a `--format` flag (`guard`, `skill`, `watch`, `mcp`) +//! are not part of the JSON contract: `guard` and `skill` have no JSON +//! output, and `watch`/`mcp` cannot run in tests (indefinite/server +//! mode). Commands requiring git history (`review`, `risk`, `coupling`, +//! `breaking`, `merge`, `diff`, `archaeology`, `behavior`, +//! `schema-impact`) build a minimal git repo with fixed dates, so SHAs +//! and dates in the output are deterministic. + +use std::process::Command; + +use insta::{assert_snapshot, with_settings}; +use tempfile::tempdir; + +/// The end of the JSON string value starting at the drive letter at +/// `drive` in `out`, if the drive letter opens a string value: the +/// closing `"` of the value, skipping `\"` escapes. `None` when the +/// drive letter does not open a value or no closing quote exists, so +/// the caller falls back to the old terminators (a path ending in a +/// backslash collapses ambiguously against its closing quote; temp +/// paths never end in one, and the fallback is the old behavior). +fn json_string_value_end(out: &str, drive: usize) -> Option { + if drive == 0 || out.as_bytes()[drive - 1] != b'"' { + return None; + } + let bytes = &out.as_bytes()[drive..]; + let mut idx = 0; + while idx < bytes.len() { + match bytes[idx] { + b'\\' => idx += 2, + b'"' => return Some(idx), + _ => idx += 1, + } + } + None +} + +/// Normalize JSON output for stable snapshots: absolute paths, timestamps, +/// and other environment-specific values become placeholders. +fn normalize_json(stdout: &str) -> String { + // Validate before surgery: the `elapsed_ms` pin below rewrites the + // digits after the key, so invalid JSON such as `"elapsed_ms": 00` + // would silently become valid `0` and the snapshot would pin output + // no consumer can parse. Parsing validates without reserializing, + // so key order (and every snapshot) is unchanged. Empty output — a + // command that failed before printing — is not JSON at all and + // stays unvalidated, as before. + if !stdout.trim().is_empty() { + serde_json::from_str::(stdout).unwrap_or_else( + |error| { + panic!("snapshot input is not valid JSON: {error}\n{stdout}") + }, + ); + } + // Windows paths are JSON-escaped with doubled backslashes + // (`C:\\Users\\...\\Temp\\...`), so a single-backslash pattern never + // matches them and the user-specific prefix survives into the + // snapshot. Collapse `\\` to `\` first: a no-op on Unix output, + // which has no backslashes, and the escaped form becomes the plain + // path the scans below expect. + let mut out = stdout.replace("\\\\", "\\"); + // Replace any `X:\...` or `X:/...` span (a drive letter through the + // end of the path) with `[PATH]`. The letter before the colon keeps a + // time like `12:30` or a key like `a: b` from matching: only a letter + // followed by `:` and a slash is a drive. + let mut search_from = 0; + loop { + let backslash = + out[search_from..].find(":\\").map(|idx| search_from + idx); + let slash = out[search_from..].find(":/").map(|idx| search_from + idx); + let Some(colon) = [backslash, slash].into_iter().flatten().min() else { + break; + }; + if colon == 0 || !out.as_bytes()[colon - 1].is_ascii_alphabetic() { + search_from = colon + 1; + continue; + } + let drive = colon - 1; + let rest = &out[drive..]; + // The path is usually the whole JSON string value (`"base_path": + // "C:\Users\Jane Doe\..."`): the value ends at its closing quote, + // and stopping at the space inside `Jane Doe` would leave `Doe` + // in the snapshot. Match the complete value when the drive letter + // opens one; otherwise keep the old terminators. + let end = json_string_value_end(&out, drive).unwrap_or_else(|| { + rest.find(|c: char| { + c == '"' || c == '\'' || c == ',' || c == '\n' || c == ' ' + }) + .unwrap_or(rest.len()) + }); + let path = &rest[..end]; + out = out.replacen(path, "[PATH]", 1); + search_from = drive + "[PATH]".len(); + } + // Replace temp dir paths: find the pattern and replace + // This handles Unix (/tmp/xxx) and Windows paths + let temp_patterns = + ["/tmp/", "/private/var/folders/", "\\AppData\\Local\\Temp\\"]; + for pattern in temp_patterns { + while let Some(idx) = out.find(pattern) { + // Find the end of the path (quote, whitespace, or comma) + let rest = &out[idx..]; + let end = rest + .find(|c: char| { + c == '"' || c == '\'' || c == ',' || c == '\n' || c == ' ' + }) + .unwrap_or(rest.len()); + let path = &rest[..end]; + out = out.replacen(path, "[PATH]", 1); + } + } + // `loc --format json` reports a measured `elapsed_ms`, which varies with + // machine speed (CI can report 1 where this laptop reports 0) and would + // make the snapshot flaky. Pin the number to 0 while keeping the type, + // so the contract still proves the field exists as a number. This is + // deliberate string surgery on the pretty-printed `"elapsed_ms": N` line: + // re-serializing the whole document through `serde_json::Value` would + // re-sort struct-serialized keys (only `loc`'s `json!` payload is already + // alphabetical) and churn every snapshot. + const KEY: &str = "\"elapsed_ms\""; + if let Some(key_idx) = out.find(KEY) { + let after_key = &out[key_idx + KEY.len()..]; + if let Some(colon) = after_key.find(':') { + let mut num_start = key_idx + KEY.len() + colon + 1; + // Skip the whitespace between the colon and the number. + while out[num_start..].starts_with(char::is_whitespace) { + num_start += 1; + } + let digits: usize = out[num_start..] + .char_indices() + .take_while(|(_, c)| c.is_ascii_digit() || *c == '-') + .map(|(i, _)| i + 1) + .last() + .unwrap_or(0); + if digits > 0 { + out.replace_range(num_start..num_start + digits, "0"); + } + } + } + out +} + +fn sephera() -> String { + env!("CARGO_BIN_EXE_sephera").to_string() +} + +fn write_fixture(dir: &std::path::Path) { + // `main.rs` imports `helper.rs`, so impact/why/affected-tests + // exercise non-empty paths. A plain `mod helper;` does not resolve + // in a flat fixture (the resolver only finds the module through an + // explicit `#[path]` or a `src/` layout), so the import is spelled + // with `#[path]`: without it `impact helper.rs` reports no + // dependents and the snapshots pin empty answers. + std::fs::write( + dir.join("main.rs"), + b"#[path = \"helper.rs\"]\nmod helper;\n\nfn main() {\n helper::helper();\n}\n", + ) + .unwrap(); + std::fs::write(dir.join("helper.rs"), b"pub fn helper() {}\n").unwrap(); + // The test file lives under `tests/`, which is what makes it a test + // file for affected-tests/untested: a root-level `test_main.rs` is + // not one (the Rust name rule is the exact name `tests.rs`). Its + // `#[path]` import makes `main.rs` reachable from a test. + std::fs::create_dir(dir.join("tests")).unwrap(); + std::fs::write( + dir.join("tests").join("test_main.rs"), + b"#[path = \"../main.rs\"]\nmod main;\n\n#[test]\nfn t() {}\n", + ) + .unwrap(); +} + +/// Run a git command for a fixture and fail loudly when it fails: a +/// silent failure (e.g. `commit.gpgsign` enabled with no key, which +/// makes `git commit` exit 128) would leave the fixture without its +/// history and the snapshot test would fail somewhere confusing. +/// Commits carry `--no-gpg-sign` so a developer's signing config +/// cannot break the fixtures at all. +fn run_git(dir: &std::path::Path, args: &[&str], envs: &[(&str, &str)]) { + let mut command = Command::new("git"); + command.args(args).current_dir(dir); + for (key, value) in envs { + command.env(key, value); + } + let output = command.output().unwrap(); + assert!( + output.status.success(), + "git {args:?} failed in {}: {}", + dir.display(), + String::from_utf8_lossy(&output.stderr) + ); +} + +fn git_commit(dir: &std::path::Path, message: &str) { + run_git(dir, &["add", "."], &[]); + run_git(dir, &["commit", "-qm", message, "--no-gpg-sign"], &[]); +} + +fn init_git_repo(dir: &std::path::Path) { + run_git(dir, &["init", "-q"], &[]); + run_git(dir, &["config", "user.email", "t@t"], &[]); + run_git(dir, &["config", "user.name", "t"], &[]); + git_commit(dir, "init"); +} + +fn run_json(args: &[&str], dir: &std::path::Path) -> String { + let output = Command::new(sephera()) + .args(args) + .arg("--path") + .arg(dir) + .arg("--format") + .arg("json") + .output() + .unwrap(); + assert!( + output.status.success(), + "command failed: {}", + String::from_utf8_lossy(&output.stderr) + ); + normalize_json(&String::from_utf8(output.stdout).unwrap()) +} + +/// Like [`run_json`], but the command takes its own arguments before +/// `--path` (a target file, `--from`, `--symbol`, `--ours`/`--theirs`). +fn run_json_args(args: &[&str], dir: &std::path::Path) -> String { + let output = Command::new(sephera()) + .args(args) + .arg("--path") + .arg(dir) + .arg("--format") + .arg("json") + .output() + .unwrap(); + assert!( + output.status.success(), + "command {args:?} failed: {}", + String::from_utf8_lossy(&output.stderr) + ); + normalize_json(&String::from_utf8(output.stdout).unwrap()) +} + +fn git_init(dir: &std::path::Path) { + run_git(dir, &["init", "-q"], &[]); + run_git(dir, &["config", "user.email", "t@t"], &[]); + run_git(dir, &["config", "user.name", "t"], &[]); +} + +/// A commit with fixed author/committer dates, so SHAs and any dates in +/// the output are identical on every run and every machine. The date is +/// arbitrary; what matters is that it never varies. +fn git_commit_fixed(dir: &std::path::Path, message: &str) { + run_git(dir, &["add", "."], &[]); + run_git( + dir, + &["commit", "-qm", message, "--no-gpg-sign"], + &[ + ("GIT_AUTHOR_DATE", "2026-01-01T00:00:00+00:00"), + ("GIT_COMMITTER_DATE", "2026-01-01T00:00:00+00:00"), + ], + ); +} + +/// Shared two-ref Rust history for the two-ref commands. v1 declares +/// `helper`, `removed_fn`, `LIMIT = 10` and `get_limit`; v2 renames +/// `helper` to `helper2`, drops `removed_fn`, and moves `LIMIT` to 20. +/// `get_limit` reads `LIMIT` in its own file: `behavior` only sees a +/// constant change when the constant is used where it is declared, not +/// when it is merely named from another file. +fn history_repo(dir: &std::path::Path) { + git_init(dir); + std::fs::write( + dir.join("helper.rs"), + b"pub fn helper() {}\npub fn removed_fn() {}\npub const LIMIT: u32 = 10;\npub fn get_limit() -> u32 {\n LIMIT\n}\n", + ) + .unwrap(); + std::fs::write( + dir.join("main.rs"), + b"mod helper;\nfn main() {\n helper::helper();\n let _ = helper::get_limit();\n}\n", + ) + .unwrap(); + git_commit_fixed(dir, "v1: helper, removed_fn, LIMIT=10"); + run_git(dir, &["tag", "v1"], &[]); + std::fs::write( + dir.join("helper.rs"), + b"pub fn helper2() {}\npub const LIMIT: u32 = 20;\npub fn get_limit() -> u32 {\n LIMIT\n}\n", + ) + .unwrap(); + std::fs::write( + dir.join("main.rs"), + b"mod helper;\nfn main() {\n helper::helper2();\n let _ = helper::get_limit();\n}\n", + ) + .unwrap(); + git_commit_fixed(dir, "v2: helper->helper2, removed_fn gone, LIMIT=20"); +} + +/// A symbol born, renamed, then moved, with the same consumer +/// throughout: `old_name` in `lib.py`, renamed to `new_name`, then the +/// file moved to `new.py`. The shape is from `archaeology_cli.rs` +/// (`repo_with_rename_and_move`). +fn archaeology_repo(dir: &std::path::Path) { + git_init(dir); + std::fs::write( + dir.join("lib.py"), + b"def old_name(a, b):\n return a - b\n", + ) + .unwrap(); + std::fs::write( + dir.join("user.py"), + b"from lib import old_name\n\n\nprint(old_name(x, y))\n", + ) + .unwrap(); + git_commit_fixed(dir, "born"); + std::fs::write( + dir.join("lib.py"), + b"def new_name(a, b):\n return a - b\n", + ) + .unwrap(); + std::fs::write( + dir.join("user.py"), + b"from lib import new_name\n\n\nprint(new_name(x, y))\n", + ) + .unwrap(); + git_commit_fixed(dir, "renamed"); + std::fs::rename(dir.join("lib.py"), dir.join("new.py")).unwrap(); + std::fs::write( + dir.join("user.py"), + b"from new import new_name\n\n\nprint(new_name(x, y))\n", + ) + .unwrap(); + git_commit_fixed(dir, "moved"); +} + +/// Base on `main` declares `add` and `keep`; `ours` removes `add` +/// while `theirs` adds a new consumer of it, so the merge has exactly +/// one `removed_vs_new_consumer` conflict. The default branch after +/// `git init` varies by machine, so the fixture names `main` itself. +fn merge_repo(dir: &std::path::Path) { + run_git(dir, &["init", "-q", "-b", "main"], &[]); + run_git(dir, &["config", "user.email", "t@t"], &[]); + run_git(dir, &["config", "user.name", "t"], &[]); + std::fs::write( + dir.join("lib.py"), + b"def add(x):\n return x\n\ndef keep(x):\n return x\n", + ) + .unwrap(); + git_commit_fixed(dir, "base"); + run_git(dir, &["checkout", "-qb", "ours"], &[]); + std::fs::write(dir.join("lib.py"), b"def keep(x):\n return x\n") + .unwrap(); + git_commit_fixed(dir, "ours removes add"); + run_git(dir, &["checkout", "-q", "main"], &[]); + run_git(dir, &["checkout", "-qb", "theirs"], &[]); + std::fs::write( + dir.join("new.py"), + b"from lib import add\n\nprint(add(1))\n", + ) + .unwrap(); + git_commit_fixed(dir, "theirs adds a consumer"); +} + +/// A proto message with a generated-code marker and a Python consumer: +/// v1 declares `api.User` with `name` and `age`; the working tree +/// removes `name`. Without the generated `user_pb2.py` marker the +/// break would be unproven, so the marker is part of the fixture. +fn schema_repo(dir: &std::path::Path) { + git_init(dir); + std::fs::create_dir(dir.join("api")).unwrap(); + std::fs::write( + dir.join("api").join("user.proto"), + b"syntax = \"proto3\";\npackage api;\nmessage User {\n string name = 1;\n int32 age = 2;\n}\n", + ) + .unwrap(); + std::fs::write( + dir.join("api").join("user_pb2.py"), + b"# Generated by the protocol buffer compiler. DO NOT EDIT!\n", + ) + .unwrap(); + std::fs::write( + dir.join("consumer.py"), + b"from api.user_pb2 import User\n\n\ndef make():\n return User(name=\"Ada\", age=36)\n", + ) + .unwrap(); + git_commit_fixed(dir, "v1"); + run_git(dir, &["tag", "v1"], &[]); + std::fs::write( + dir.join("api").join("user.proto"), + b"syntax = \"proto3\";\npackage api;\nmessage User {\n int32 age = 2;\n}\n", + ) + .unwrap(); +} + +#[test] +fn json_contract_loc() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let out = run_json(&["loc"], dir.path()); + with_settings!({ snapshot_suffix => "loc" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_symbols() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let out = run_json(&["symbols"], dir.path()); + with_settings!({ snapshot_suffix => "symbols" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_context() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let out = run_json(&["context"], dir.path()); + with_settings!({ snapshot_suffix => "context" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_graph() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let out = run_json(&["graph"], dir.path()); + with_settings!({ snapshot_suffix => "graph" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_dead() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let out = run_json(&["dead"], dir.path()); + with_settings!({ snapshot_suffix => "dead" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_untested() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let out = run_json(&["untested"], dir.path()); + with_settings!({ snapshot_suffix => "untested" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_impact() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let output = Command::new(sephera()) + .args(["impact", "--path"]) + .arg(dir.path()) + .arg("--format") + .arg("json") + .arg("helper.rs") + .output() + .unwrap(); + assert!(output.status.success()); + let out = normalize_json(&String::from_utf8(output.stdout).unwrap()); + with_settings!({ snapshot_suffix => "impact" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_why() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let output = Command::new(sephera()) + .args(["why", "--path"]) + .arg(dir.path()) + .arg("--format") + .arg("json") + .arg("main.rs") + .arg("helper.rs") + .output() + .unwrap(); + // why may fail if no path exists; that's fine, we snapshot the shape + let stdout = String::from_utf8(output.stdout).unwrap(); + let out = normalize_json(&stdout); + with_settings!({ snapshot_suffix => "why" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_affected_tests() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let output = Command::new(sephera()) + .args(["affected-tests", "--path"]) + .arg(dir.path()) + .arg("--format") + .arg("json") + .arg("main.rs") + .output() + .unwrap(); + let out = normalize_json(&String::from_utf8(output.stdout).unwrap()); + with_settings!({ snapshot_suffix => "affected_tests" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_test_priority() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + // test-priority reads git history; initialize a minimal repo + init_git_repo(dir.path()); + let out = run_json(&["test-priority"], dir.path()); + with_settings!({ snapshot_suffix => "test_priority" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_simulate() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + let output = Command::new(sephera()) + .args(["simulate", "--path"]) + .arg(dir.path()) + .arg("--format") + .arg("json") + .arg("--symbol") + .arg("helper") + .arg("--to") + .arg("helper2") + .arg("helper.rs") + .output() + .unwrap(); + let out = normalize_json(&String::from_utf8(output.stdout).unwrap()); + with_settings!({ snapshot_suffix => "simulate" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_coupling() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + init_git_repo(dir.path()); + // A real pair: `alpha.rs` and `beta.rs` never import each other, so + // no graph edge excludes them, and they change together in four + // commits (added together, then three joint edits), for 4 co-changes + // against the default `min_co_changes` of 3 -- 3 even if the commit + // that adds them does not count. (`main.rs`, `helper.rs`) can never + // appear as a pair: `main.rs` imports `helper.rs`, and linked pairs + // are excluded by design. + let alpha = dir.path().join("alpha.rs"); + let beta = dir.path().join("beta.rs"); + for n in 1..=4 { + let suffix = "// v2\n".repeat(n - 1); + std::fs::write(&alpha, format!("pub fn alpha() {{}}\n{suffix}")) + .unwrap(); + std::fs::write(&beta, format!("pub fn beta() {{}}\n{suffix}")).unwrap(); + git_commit(dir.path(), &format!("couple {n}")); + } + let out = run_json(&["coupling"], dir.path()); + with_settings!({ snapshot_suffix => "coupling" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_risk() { + let dir = tempdir().unwrap(); + write_fixture(dir.path()); + init_git_repo(dir.path()); + let out = run_json(&["risk"], dir.path()); + with_settings!({ snapshot_suffix => "risk" }, { + assert_snapshot!(out); + }); +} + +/// Invalid JSON must fail here, not be silently repaired: the old +/// `elapsed_ms` surgery rewrote `"elapsed_ms": 00` to `0`, so a +/// snapshot could pin output no consumer can parse. +#[test] +#[should_panic(expected = "not valid JSON")] +fn normalize_json_rejects_invalid_json() { + normalize_json(r#"{"elapsed_ms": 00}"#); +} + +/// Valid JSON still normalizes: the validation above must not break +/// the `elapsed_ms` pin it guards. +#[test] +fn normalize_json_pins_elapsed_ms_on_valid_json() { + let normalized = normalize_json("{\n \"elapsed_ms\": 42\n}"); + assert!( + normalized.contains("\"elapsed_ms\": 0"), + "elapsed_ms was not pinned: {normalized}" + ); +} + +/// A Windows JSON-escaped path must not leak its user-specific prefix +/// into a snapshot. Before the fix the doubled backslashes meant no +/// pattern matched, so `C:\Users\runner\...` survived verbatim; on the +/// old normalizer this test fails with `runner` still present. +#[test] +fn normalize_json_handles_windows_escaped_paths() { + let windows = r#"{"base_path": "C:\\Users\\runner\\AppData\\Local\\Temp\\.tmpAbC123\\main.rs", "file": "helper.rs"}"#; + let normalized = normalize_json(windows); + assert!( + !normalized.contains("runner"), + "user-specific prefix survived: {normalized}" + ); + assert!( + !normalized.contains("C:"), + "drive letter survived: {normalized}" + ); + assert!( + normalized.contains("[PATH]"), + "no [PATH] placeholder: {normalized}" + ); + assert_eq!( + normalized, r#"{"base_path": "[PATH]", "file": "helper.rs"}"#, + "windows path not fully replaced" + ); + // A time or a `key: value` pair is not a drive letter. + let plain = r#"{"elapsed_ms": 12, "note": "ran at 12:30"}"#; + let normalized = normalize_json(plain); + assert!( + normalized.contains("12:30"), + "non-path colon text was mangled: {normalized}" + ); + // A profile directory with a space (`Jane Doe`) must not leak its + // second half: the old drive scan stopped at the space, so `Doe` + // survived in the snapshot and it varied by user. + let spaced = r#"{"base_path": "C:\\Users\\Jane Doe\\AppData\\Local\\Temp\\.tmpAbC123\\main.rs"}"#; + let normalized = normalize_json(spaced); + assert_eq!( + normalized, r#"{"base_path": "[PATH]"}"#, + "spaced Windows path not fully replaced: {normalized}" + ); + // The Unix form still normalizes. + let unix = r#"{"base_path": "/tmp/.tmpAbC123/main.rs"}"#; + let normalized = normalize_json(unix); + assert!( + !normalized.contains("/tmp/"), + "unix temp path survived: {normalized}" + ); + assert!(normalized.contains("[PATH]")); +} + +#[test] +fn json_contract_review() { + let dir = tempdir().unwrap(); + history_repo(dir.path()); + // A clean tree reviews to an empty `changed` list, which pins + // nothing; dirty the tree so the snapshot proves the shape of a + // real changed file. + std::fs::write( + dir.path().join("main.rs"), + b"mod helper;\nfn main() {\n helper::helper2();\n let _ = helper::get_limit();\n}\n\n// dirty\n", + ) + .unwrap(); + let out = run_json_args(&["review"], dir.path()); + with_settings!({ snapshot_suffix => "review" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_breaking() { + let dir = tempdir().unwrap(); + history_repo(dir.path()); + let out = run_json_args(&["breaking", "--from", "v1"], dir.path()); + with_settings!({ snapshot_suffix => "breaking" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_merge() { + let dir = tempdir().unwrap(); + merge_repo(dir.path()); + let out = run_json_args( + &["merge", "--ours", "ours", "--theirs", "theirs"], + dir.path(), + ); + with_settings!({ snapshot_suffix => "merge" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_diff() { + let dir = tempdir().unwrap(); + history_repo(dir.path()); + let out = run_json_args(&["diff", "--from", "v1"], dir.path()); + with_settings!({ snapshot_suffix => "diff" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_archaeology() { + let dir = tempdir().unwrap(); + archaeology_repo(dir.path()); + let out = run_json_args( + &["archaeology", "new.py", "--symbol", "new_name"], + dir.path(), + ); + with_settings!({ snapshot_suffix => "archaeology" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_behavior() { + let dir = tempdir().unwrap(); + history_repo(dir.path()); + let out = run_json_args(&["behavior", "--from", "v1"], dir.path()); + with_settings!({ snapshot_suffix => "behavior" }, { + assert_snapshot!(out); + }); +} + +#[test] +fn json_contract_schema_impact() { + let dir = tempdir().unwrap(); + schema_repo(dir.path()); + let out = run_json_args(&["schema-impact", "--from", "v1"], dir.path()); + with_settings!({ snapshot_suffix => "schema_impact" }, { + assert_snapshot!(out); + }); +} + +/// A `commit.gpgsign` config with no key must not silently empty the +/// fixture: commits carry `--no-gpg-sign`, so this commit lands and +/// `git log` proves it. On the unfixed helpers the commit failed +/// silently (exit 128, "gpg failed to sign the data") and the fixture +/// had no history. +#[test] +fn git_commit_lands_when_signing_is_configured() { + let dir = tempdir().unwrap(); + git_init(dir.path()); + Command::new("git") + .args(["config", "commit.gpgsign", "true"]) + .current_dir(dir.path()) + .output() + .unwrap(); + std::fs::write(dir.path().join("a.rs"), b"pub fn a() {}\n").unwrap(); + git_commit(dir.path(), "signed-config commit"); + let output = Command::new("git") + .args(["log", "--oneline"]) + .current_dir(dir.path()) + .output() + .unwrap(); + let log = String::from_utf8(output.stdout).unwrap(); + assert!( + log.contains("signed-config commit"), + "commit did not land: {log}" + ); +} + +/// A failed fixture command must fail loudly, not silently continue: +/// committing with nothing staged exits 1, and the helper asserts. +/// On the unfixed helpers the commit failed silently and the test +/// would pass with no history at all. +#[test] +#[should_panic(expected = "git [\"commit\"")] +fn git_commit_fails_loudly_when_it_fails() { + let dir = tempdir().unwrap(); + git_init(dir.path()); + git_commit(dir.path(), "nothing to commit"); +} diff --git a/crates/sephera_cli/tests/mcp_cli.rs b/crates/sephera_cli/tests/mcp_cli.rs index 00f09e57..ddbce20a 100644 --- a/crates/sephera_cli/tests/mcp_cli.rs +++ b/crates/sephera_cli/tests/mcp_cli.rs @@ -83,11 +83,18 @@ impl Mcp { /// other way round gets the connection dropped with no explanation. That is /// the same trap the last test in this file pins from the other side. fn handshake(&mut self) -> Value { + self.handshake_with("2024-11-05") + } + + /// Like [`Self::handshake`], but the client requests `version`: the + /// server answers with the requested version when it supports it, + /// otherwise its latest. + fn handshake_with(&mut self, version: &str) -> Value { let result = self .call( "initialize", json!({ - "protocolVersion": "2024-11-05", + "protocolVersion": version, "capabilities": {}, "clientInfo": { "name": "sephera-cli-tests", "version": "0" }, }), @@ -456,6 +463,21 @@ fn the_server_identifies_itself_after_the_handshake() { ); } +/// The negotiated version is the one the client asked for, when the +/// server supports it — not a fixed `2024-11-05`. STABILITY.md used to +/// state the old version as the negotiated one; a client requesting +/// the latest gets the latest. +#[test] +fn the_server_negotiates_the_requested_protocol_version() { + let mut mcp = Mcp::start(); + let result = mcp.handshake_with("2025-06-18"); + + assert_eq!( + result["result"]["protocolVersion"], "2025-06-18", + "the server must answer with the requested version: {result}" + ); +} + #[test] fn every_documented_tool_is_discoverable_over_the_protocol() { // The crate doc lists the tools and a unit test checks the list against the diff --git a/crates/sephera_cli/tests/regressions.rs b/crates/sephera_cli/tests/regressions.rs index b3ebedc8..80826ff0 100644 --- a/crates/sephera_cli/tests/regressions.rs +++ b/crates/sephera_cli/tests/regressions.rs @@ -5,6 +5,8 @@ //! file is the single target that pulls the `regressions/` modules //! in. Add a new area with one `#[path]` line. +#[path = "regressions/exit_codes.rs"] +mod exit_codes; #[path = "regressions/multirepo_multi.rs"] mod multirepo_multi; #[path = "regressions/sarif.rs"] diff --git a/crates/sephera_cli/tests/regressions/exit_codes.rs b/crates/sephera_cli/tests/regressions/exit_codes.rs new file mode 100644 index 00000000..d7b9cf5a --- /dev/null +++ b/crates/sephera_cli/tests/regressions/exit_codes.rs @@ -0,0 +1,140 @@ +//! Regression tests: exit codes are part of the stability contract. +//! +//! The contract reserves 2 for gate violations (the analysis ran and a +//! `--fail-on` threshold was crossed). Clap's default usage-error code +//! is also 2, so before the fix a mistyped flag and a crossed threshold +//! were indistinguishable to a script. Usage errors are `EX_USAGE` +//! (64) instead; `--help` still exits 0 and a crossed gate still exits +//! 2. Each test drives the real binary, because the claim is about +//! which code a caller sees. + +use std::path::Path; +use std::process::{Command, Output}; + +use tempfile::tempdir; + +fn sephera() -> String { + env!("CARGO_BIN_EXE_sephera").to_string() +} + +fn run(args: &[&str]) -> Output { + Command::new(sephera()).args(args).output().unwrap() +} + +/// A usage error must exit 64, not 2. On the unfixed code this fails: +/// clap's default parse-error exit is 2. +#[test] +fn usage_error_exits_64_not_2() { + let output = run(&["--nonexistent-flag"]); + assert_eq!( + output.status.code(), + Some(64), + "stderr: {}", + String::from_utf8_lossy(&output.stderr) + ); +} + +/// A flag left without its value must exit 64, not 1. Before the fix the +/// config pre-pass swallowed the next flag as the config filename +/// (`loc --config --format json` read `--format` as the file and exited 1 +/// for a missing file); now the pre-pass leaves it for clap, which +/// reports the missing value as a usage error. A genuinely missing file +/// is still a failure (1), not a usage error: the flag had its value, +/// the file is what is wrong. +#[test] +fn flag_missing_its_value_exits_64() { + let dir = tempdir().unwrap(); + let missing_value = Command::new(sephera()) + .args(["loc", "--config", "--format", "json"]) + .current_dir(dir.path()) + .output() + .unwrap(); + assert_eq!( + missing_value.status.code(), + Some(64), + "stderr: {}", + String::from_utf8_lossy(&missing_value.stderr) + ); + let missing_file = Command::new(sephera()) + .args(["loc", "--config", "missing.toml"]) + .current_dir(dir.path()) + .output() + .unwrap(); + assert_eq!( + missing_file.status.code(), + Some(1), + "stderr: {}", + String::from_utf8_lossy(&missing_file.stderr) + ); +} + +/// Bare `sephera` prints help to stderr and exits 64, with no `error:` +/// prefix: the output is help, not an error report, so STABILITY.md +/// explicitly excludes this case from the prefix promise. A real usage +/// error (unknown flag) still carries the prefix. +#[test] +fn no_arguments_prints_help_without_error_prefix() { + let dir = tempdir().unwrap(); + let output = Command::new(sephera()) + .current_dir(dir.path()) + .output() + .unwrap(); + assert_eq!(output.status.code(), Some(64)); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!( + stderr.contains("Usage:"), + "expected help text on stderr: {stderr}" + ); + assert!( + !stderr.contains("error:"), + "help output must not carry the error prefix: {stderr}" + ); +} + +/// `--help` and `--version` still exit 0: their clap error carries exit +/// code 0 and is passed through unchanged by the remap. +#[test] +fn help_and_version_still_exit_0() { + let help = run(&["--help"]); + assert_eq!(help.status.code(), Some(0)); + let version = run(&["--version"]); + assert_eq!(version.status.code(), Some(0)); +} + +/// A crossed gate still exits 2: the remap must not have moved gate +/// violations. `main.rs` imports `helper.rs`, so `impact helper.rs +/// --fail-on 1` crosses with one dependent. +#[test] +fn gate_violation_still_exits_2() { + let dir = tempdir().unwrap(); + let path = dir.path(); + write_fixture(path); + let output = Command::new(sephera()) + .args(["impact", "--path"]) + .arg(path) + .arg("--fail-on") + .arg("1") + .arg("helper.rs") + .output() + .unwrap(); + assert_eq!( + output.status.code(), + Some(2), + "stdout: {}\nstderr: {}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) + ); +} + +fn write_fixture(dir: &Path) { + // A plain `mod helper;` does not resolve in a flat fixture (the + // resolver only finds the module through an explicit `#[path]` or a + // `src/` layout), so the import is spelled with `#[path]`: without + // it `impact` reports no dependents and the gate never fires. + std::fs::write( + dir.join("main.rs"), + b"#[path = \"helper.rs\"]\nmod helper;\n\nfn main() {\n helper::helper();\n}\n", + ) + .unwrap(); + std::fs::write(dir.join("helper.rs"), b"pub fn helper() {}\n").unwrap(); +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_affected_tests@affected_tests.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_affected_tests@affected_tests.snap new file mode 100644 index 00000000..b4ffc940 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_affected_tests@affected_tests.snap @@ -0,0 +1,26 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "targets": [ + { + "target": "main.rs", + "affected_test_count": 1, + "depth": null, + "tests": [ + { + "file": "tests/test_main.rs", + "distance": 1, + "imports": [ + "../main.rs" + ] + } + ] + } + ], + "run_plan": [ + "cargo test --test test_main" + ], + "manual": [] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_archaeology@archaeology.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_archaeology@archaeology.snap new file mode 100644 index 00000000..65c30321 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_archaeology@archaeology.snap @@ -0,0 +1,45 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "file": "new.py", + "symbol": "new_name", + "origin_found": true, + "note": null, + "steps": [ + { + "kind": "born", + "commit": "f4db620f9546a9a97323c2abde5a16020786461d", + "author": "t", + "date": "2026-01-01", + "message": "born", + "from_file": null, + "from_name": null, + "to_file": "lib.py", + "to_name": "old_name" + }, + { + "kind": "renamed", + "commit": "16873de625173174ca6128e8a331777d6cb7c126", + "author": "t", + "date": "2026-01-01", + "message": "renamed", + "from_file": "lib.py", + "from_name": "old_name", + "to_file": "lib.py", + "to_name": "new_name" + }, + { + "kind": "moved", + "commit": "e9c53c6a9e1c3251692c058452aa2631f244191a", + "author": "t", + "date": "2026-01-01", + "message": "moved", + "from_file": "lib.py", + "from_name": "new_name", + "to_file": "new.py", + "to_name": "new_name" + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_behavior@behavior.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_behavior@behavior.snap new file mode 100644 index 00000000..91db157b --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_behavior@behavior.snap @@ -0,0 +1,17 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "from": "v1", + "to": "working tree", + "changes": [ + { + "kind": "constant_changed", + "file": "helper.rs", + "name": "LIMIT", + "old_value": "10", + "new_value": "20" + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_breaking@breaking.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_breaking@breaking.snap new file mode 100644 index 00000000..67e506c1 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_breaking@breaking.snap @@ -0,0 +1,34 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "from": "v1", + "to": "working tree", + "broken": [ + { + "file": "helper.rs", + "symbol": "helper", + "kind": "function", + "change": { + "type": "removed" + }, + "suggestion": null, + "direct": [], + "namespace_users": [], + "downstream": [] + }, + { + "file": "helper.rs", + "symbol": "removed_fn", + "kind": "function", + "change": { + "type": "removed" + }, + "suggestion": null, + "direct": [], + "namespace_users": [], + "downstream": [] + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_context@context.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_context@context.snap new file mode 100644 index 00000000..79bd22e2 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_context@context.snap @@ -0,0 +1,98 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "metadata": { + "base_path": "[PATH]", + "focus_paths": [], + "compression_mode": "none", + "budget_tokens": 128000, + "metadata_budget_tokens": 12800, + "excerpt_budget_tokens": 115200, + "estimated_tokens": 252, + "estimated_metadata_tokens": 216, + "estimated_excerpt_tokens": 36, + "files_considered": 3, + "files_selected": 3, + "truncated_files": 0, + "closure_pulled_files": 0 + }, + "dominant_languages": [ + { + "language": "Rust", + "files": 3, + "size_bytes": 142 + } + ], + "groups": [ + { + "group": "entrypoints", + "label": "Entrypoints", + "files": 1, + "estimated_tokens": 18, + "truncated_files": 0 + }, + { + "group": "testing", + "label": "Testing", + "files": 1, + "estimated_tokens": 13, + "truncated_files": 0 + }, + { + "group": "general", + "label": "General", + "files": 1, + "estimated_tokens": 5, + "truncated_files": 0 + } + ], + "files": [ + { + "relative_path": "main.rs", + "language": "Rust", + "size_bytes": 71, + "estimated_tokens": 18, + "truncated": false, + "compressed": false, + "group": "entrypoints", + "selection_class": "entrypoint", + "excerpt": { + "line_start": 1, + "line_end": 6, + "content": "#[path = \"helper.rs\"]\nmod helper;\n\nfn main() {\n helper::helper();\n}" + } + }, + { + "relative_path": "tests/test_main.rs", + "language": "Rust", + "size_bytes": 52, + "estimated_tokens": 13, + "truncated": false, + "compressed": false, + "group": "testing", + "selection_class": "adjacent-test", + "excerpt": { + "line_start": 1, + "line_end": 5, + "content": "#[path = \"../main.rs\"]\nmod main;\n\n#[test]\nfn t() {}" + } + }, + { + "relative_path": "helper.rs", + "language": "Rust", + "size_bytes": 19, + "estimated_tokens": 5, + "truncated": false, + "compressed": false, + "group": "general", + "selection_class": "general", + "excerpt": { + "line_start": 1, + "line_end": 1, + "content": "pub fn helper() {}" + } + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_coupling@coupling.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_coupling@coupling.snap new file mode 100644 index 00000000..8dffa111 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_coupling@coupling.snap @@ -0,0 +1,18 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "commits_scanned": 5, + "commits_counted": 5, + "pairs": [ + { + "first": "alpha.rs", + "second": "beta.rs", + "co_changes": 4, + "first_commits": 4, + "second_commits": 4, + "containment": 1.0 + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_dead@dead.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_dead@dead.snap new file mode 100644 index 00000000..71c559af --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_dead@dead.snap @@ -0,0 +1,13 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "total": 3, + "reachable": 3, + "roots": [ + "main.rs", + "tests/test_main.rs" + ], + "dead": [] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_diff@diff.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_diff@diff.snap new file mode 100644 index 00000000..e97b12ac --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_diff@diff.snap @@ -0,0 +1,34 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "from": "v1", + "to": "working tree", + "changes": [ + { + "file": "helper.rs", + "symbol": "helper", + "kind": "function", + "change": { + "type": "removed" + } + }, + { + "file": "helper.rs", + "symbol": "helper2", + "kind": "function", + "change": { + "type": "added" + } + }, + { + "file": "helper.rs", + "symbol": "removed_fn", + "kind": "function", + "change": { + "type": "removed" + } + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_graph@graph.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_graph@graph.snap new file mode 100644 index 00000000..7644a3cb --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_graph@graph.snap @@ -0,0 +1,85 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "base_path": "[PATH]", + "focus_paths": [], + "depth": null, + "query": null, + "nodes": [ + { + "file_path": "helper.rs", + "language": "Rust", + "imports_count": 0, + "imported_by_count": 1 + }, + { + "file_path": "main.rs", + "language": "Rust", + "imports_count": 1, + "imported_by_count": 1 + }, + { + "file_path": "tests/test_main.rs", + "language": "Rust", + "imports_count": 1, + "imported_by_count": 0 + } + ], + "edges": [ + { + "from": "main.rs", + "to": "helper.rs", + "import_path": "helper.rs", + "resolved": true, + "local_gap": false, + "cfg_gated": false, + "kind": "module_declaration" + }, + { + "from": "tests/test_main.rs", + "to": "main.rs", + "import_path": "../main.rs", + "resolved": true, + "local_gap": false, + "cfg_gated": false, + "kind": "module_declaration" + } + ], + "metrics": { + "total_files": 3, + "total_internal_edges": 2, + "self_references": 0, + "total_external_edges": 0, + "unresolved_local_edges": 0, + "unresolved_local_samples": [], + "cfg_gated_edges": 0, + "dependencies": [], + "declared_dependency_edges": 0, + "local_crate_edges": 0, + "builtin_edges": 0, + "circular_dependencies": 0, + "most_importing": [ + { + "file_path": "main.rs", + "count": 1 + }, + { + "file_path": "tests/test_main.rs", + "count": 1 + } + ], + "most_imported": [ + { + "file_path": "helper.rs", + "count": 1 + }, + { + "file_path": "main.rs", + "count": 1 + } + ], + "cycles": [] + } +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_impact@impact.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_impact@impact.snap new file mode 100644 index 00000000..19150fe8 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_impact@impact.snap @@ -0,0 +1,25 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "targets": [ + { + "target": "helper.rs", + "dependent_count": 2, + "depth": null, + "dependents": [ + { + "file": "main.rs", + "imports": [ + "helper.rs" + ] + }, + { + "file": "tests/test_main.rs", + "imports": [] + } + ] + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_loc@loc.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_loc@loc.snap new file mode 100644 index 00000000..009ed6c8 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_loc@loc.snap @@ -0,0 +1,25 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "base_path": "[PATH]", + "by_language": [ + { + "code_lines": 10, + "comment_lines": 0, + "empty_lines": 2, + "language": "Rust", + "size_bytes": 142 + } + ], + "elapsed_ms": 0, + "files_scanned": 3, + "languages_detected": 1, + "totals": { + "code_lines": 10, + "comment_lines": 0, + "empty_lines": 2, + "size_bytes": 142 + } +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_merge@merge.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_merge@merge.snap new file mode 100644 index 00000000..b35826ea --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_merge@merge.snap @@ -0,0 +1,23 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "base": "035d7c670ca01fde236058f36b662fa8653dff0e", + "ours": "ours", + "theirs": "theirs", + "conflicts": [ + { + "file": "lib.py", + "symbol": "add", + "kind": { + "type": "removed_vs_new_consumer" + }, + "contract_side": "ours", + "consumers": [ + "new.py" + ], + "suggestion": null + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_review@review.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_review@review.snap new file mode 100644 index 00000000..80d2edc8 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_review@review.snap @@ -0,0 +1,24 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "against": "HEAD", + "commits_scanned": 2, + "commits_counted": 2, + "changed": [ + { + "file": "main.rs", + "present": true, + "direct_dependents": [], + "dependent_count": 0, + "tests": [] + } + ], + "breaking": { + "from": "HEAD", + "to": "working tree", + "broken": [] + }, + "warnings": [] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_risk@risk.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_risk@risk.snap new file mode 100644 index 00000000..6f4df52c --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_risk@risk.snap @@ -0,0 +1,24 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "commits_scanned": 1, + "commits_counted": 1, + "files": [ + { + "file": "helper.rs", + "dependents": 2, + "churn": 1, + "coupled_partners": 0, + "score": 2 + }, + { + "file": "main.rs", + "dependents": 1, + "churn": 1, + "coupled_partners": 0, + "score": 1 + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_schema_impact@schema_impact.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_schema_impact@schema_impact.snap new file mode 100644 index 00000000..cd69c72d --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_schema_impact@schema_impact.snap @@ -0,0 +1,26 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "from_ref": "v1", + "to_ref": "working tree", + "breaks": [ + { + "schema_file": "api/user.proto", + "element": "api.User.name", + "change": "removed", + "note": null, + "proven": [ + { + "file": "consumer.py", + "via": "constructor_kwarg" + } + ], + "named": [], + "downstream": [] + } + ], + "added": [], + "coverage": [] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_simulate@simulate.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_simulate@simulate.snap new file mode 100644 index 00000000..baed733d --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_simulate@simulate.snap @@ -0,0 +1,15 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "file": "helper.rs", + "symbol": "helper", + "new_name": "helper2", + "new_file": "helper.rs", + "blocked": false, + "direct": [], + "namespace_users": [], + "downstream": [], + "collisions": [] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_symbols@symbols.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_symbols@symbols.snap new file mode 100644 index 00000000..e5f7eba4 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_symbols@symbols.snap @@ -0,0 +1,63 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "report": { + "base_path": "[PATH]", + "by_language": [ + { + "language": "Rust", + "files": 3, + "counts": { + "functions": 3, + "types": 2 + } + } + ], + "totals": { + "functions": 3, + "types": 2 + }, + "files_scanned": 3, + "files_skipped": 0, + "languages_detected": 1 + }, + "symbols": [ + { + "file_path": "helper.rs", + "name": "helper", + "kind": "functions", + "line": 1, + "end_line": 1 + }, + { + "file_path": "main.rs", + "name": "helper", + "kind": "types", + "line": 2, + "end_line": 2 + }, + { + "file_path": "main.rs", + "name": "main", + "kind": "functions", + "line": 4, + "end_line": 6 + }, + { + "file_path": "tests/test_main.rs", + "name": "main", + "kind": "types", + "line": 2, + "end_line": 2 + }, + { + "file_path": "tests/test_main.rs", + "name": "t", + "kind": "functions", + "line": 5, + "end_line": 5 + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_test_priority@test_priority.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_test_priority@test_priority.snap new file mode 100644 index 00000000..909e053d --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_test_priority@test_priority.snap @@ -0,0 +1,40 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "symbols": [ + { + "file": "helper.rs", + "symbol": "helper", + "kind": "function", + "downstream": 0, + "churn": 1, + "coupled_partners": 0, + "score": 0 + }, + { + "file": "main.rs", + "symbol": "helper", + "kind": "module", + "downstream": 0, + "churn": 1, + "coupled_partners": 0, + "score": 0 + }, + { + "file": "main.rs", + "symbol": "main", + "kind": "function", + "downstream": 0, + "churn": 1, + "coupled_partners": 0, + "score": 0 + } + ], + "untested_total": 3, + "tested_direct": 0, + "tested_indirect": 0, + "commits_scanned": 1, + "commits_counted": 1 +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_untested@untested.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_untested@untested.snap new file mode 100644 index 00000000..213759f1 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_untested@untested.snap @@ -0,0 +1,28 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "test_files": [ + "tests/test_main.rs" + ], + "tested_direct": 0, + "tested_indirect": 0, + "untested": [ + { + "file": "helper.rs", + "symbol": "helper", + "kind": "function" + }, + { + "file": "main.rs", + "symbol": "helper", + "kind": "module" + }, + { + "file": "main.rs", + "symbol": "main", + "kind": "function" + } + ] +} diff --git a/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_why@why.snap b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_why@why.snap new file mode 100644 index 00000000..e1090da4 --- /dev/null +++ b/crates/sephera_cli/tests/snapshots/json_contracts__json_contract_why@why.snap @@ -0,0 +1,23 @@ +--- +source: crates/sephera_cli/tests/json_contracts.rs +expression: out +--- +{ + "from": "main.rs", + "to": "helper.rs", + "connected": true, + "hop_count": 1, + "direct": true, + "hops": [ + { + "file": "main.rs", + "via": [] + }, + { + "file": "helper.rs", + "via": [ + "helper.rs" + ] + } + ] +} diff --git a/crates/sephera_cli/tests/watch_cli.rs b/crates/sephera_cli/tests/watch_cli.rs index 7dda8792..295cafb4 100644 --- a/crates/sephera_cli/tests/watch_cli.rs +++ b/crates/sephera_cli/tests/watch_cli.rs @@ -34,12 +34,14 @@ fn stdout(output: &Output) -> String { /// passed" — while `--once` was exactly what had been passed. The /// target is now required outright, so clap rejects the invocation /// with its standard missing-argument error and no self-contradiction. +/// The rejection is a usage error, so it exits 64 (`EX_USAGE`), not 2: +/// 2 is reserved for gate violations by the stability contract. #[test] fn regression_once_without_target_is_a_parse_error() { let dir = tempdir().unwrap(); let path = dir.path().to_str().unwrap(); let output = sephera(&["watch", "--once", "--path", path]); - assert_eq!(output.status.code(), Some(2), "{}", stderr(&output)); + assert_eq!(output.status.code(), Some(64), "{}", stderr(&output)); let text = stderr(&output); assert!(text.contains("--target"), "{text}"); assert!( diff --git a/crates/sephera_compression/Cargo.toml b/crates/sephera_compression/Cargo.toml index 290882b2..5bab9767 100644 --- a/crates/sephera_compression/Cargo.toml +++ b/crates/sephera_compression/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_compression" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Tree-sitter AST compression: skeleton, signatures, and structure extraction." -documentation = "https://docs.rs/sephera_compression" readme = "README.md" keywords = ["tree-sitter", "compression", "ast", "llm-context"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_context/Cargo.toml b/crates/sephera_context/Cargo.toml index ba090f27..76df8ba2 100644 --- a/crates/sephera_context/Cargo.toml +++ b/crates/sephera_context/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_context" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Deterministic, token-budgeted context pack building for LLM prompts." -documentation = "https://docs.rs/sephera_context" readme = "README.md" keywords = ["context", "llm", "token-budget", "repository"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_core/Cargo.toml b/crates/sephera_core/Cargo.toml index 40eba1ba..11612205 100644 --- a/crates/sephera_core/Cargo.toml +++ b/crates/sephera_core/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_core" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Shared analysis engine behind the Sephera CLI for LOC metrics, context building, and Tree-sitter AST compression." -documentation = "https://docs.rs/sephera_core" readme = "README.crates-io.md" keywords = ["loc", "context", "tree-sitter", "compression", "scanner"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_graph/Cargo.toml b/crates/sephera_graph/Cargo.toml index 2746ff53..24e40282 100644 --- a/crates/sephera_graph/Cargo.toml +++ b/crates/sephera_graph/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_graph" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Dependency graph core: resolver, declarations, blast radius, rendering." -documentation = "https://docs.rs/sephera_graph" readme = "README.md" keywords = ["graph", "dependencies", "blast-radius", "resolver", "tree-sitter"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_graph/src/archaeology.rs b/crates/sephera_graph/src/archaeology.rs index 0b8f4189..a8c493a5 100644 --- a/crates/sephera_graph/src/archaeology.rs +++ b/crates/sephera_graph/src/archaeology.rs @@ -498,7 +498,7 @@ pub fn trace_symbol( break; } let older = build(&older_commit)?; - examined.insert(older_commit.hash.clone()); + examined.insert(older_commit.hash); examined_count += 1; match classify_older(&newer, &older, &tracked_file, &tracked_name) { OlderOutcome::Continuous => { diff --git a/crates/sephera_graph/src/resolver.rs b/crates/sephera_graph/src/resolver.rs index 3c032eaf..e67a02b2 100644 --- a/crates/sephera_graph/src/resolver.rs +++ b/crates/sephera_graph/src/resolver.rs @@ -2292,7 +2292,7 @@ fn detect_cycles(node_map: &NodeMap) -> Vec> { .iter() .map(|(n, _)| n.clone()) .collect(); - cycle.push(child.clone()); + cycle.push(child); if seen_cycle_keys.insert(cycle_key(&cycle)) { cycles.push(cycle); diff --git a/crates/sephera_graph/src/schema.rs b/crates/sephera_graph/src/schema.rs index a22d69fe..4cef4a18 100644 --- a/crates/sephera_graph/src/schema.rs +++ b/crates/sephera_graph/src/schema.rs @@ -2223,7 +2223,7 @@ fn build_go_module( continue; } let mut gen_message = GenMessage { - go_name: go_name.clone(), + go_name, ..Default::default() }; for field in message.by_number.values() { diff --git a/crates/sephera_graph_cpp/Cargo.toml b/crates/sephera_graph_cpp/Cargo.toml index 672ee0f4..0bec2abb 100644 --- a/crates/sephera_graph_cpp/Cargo.toml +++ b/crates/sephera_graph_cpp/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_graph_cpp" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "C/C++ dependency extraction for Sephera graph." -documentation = "https://docs.rs/sephera_graph_cpp" readme = "README.md" keywords = ["c", "cpp", "dependencies", "tree-sitter", "header"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_graph_go/Cargo.toml b/crates/sephera_graph_go/Cargo.toml index e1eb4f21..32ed70f0 100644 --- a/crates/sephera_graph_go/Cargo.toml +++ b/crates/sephera_graph_go/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_graph_go" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Go dependency extraction for Sephera graph." -documentation = "https://docs.rs/sephera_graph_go" readme = "README.md" keywords = ["go", "golang", "dependencies", "tree-sitter", "go-mod"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_graph_java/Cargo.toml b/crates/sephera_graph_java/Cargo.toml index c37f97e3..7e46a66b 100644 --- a/crates/sephera_graph_java/Cargo.toml +++ b/crates/sephera_graph_java/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_graph_java" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Java dependency extraction for Sephera graph." -documentation = "https://docs.rs/sephera_graph_java" readme = "README.md" keywords = ["java", "dependencies", "tree-sitter", "maven", "gradle"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_graph_javascript/Cargo.toml b/crates/sephera_graph_javascript/Cargo.toml index d48c9000..b3d9181f 100644 --- a/crates/sephera_graph_javascript/Cargo.toml +++ b/crates/sephera_graph_javascript/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_graph_javascript" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "JavaScript/TypeScript dependency extraction for Sephera graph." -documentation = "https://docs.rs/sephera_graph_javascript" readme = "README.md" keywords = ["javascript", "typescript", "dependencies", "tree-sitter", "package-json"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_graph_python/Cargo.toml b/crates/sephera_graph_python/Cargo.toml index 9be85a9e..c0fd1632 100644 --- a/crates/sephera_graph_python/Cargo.toml +++ b/crates/sephera_graph_python/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_graph_python" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Python dependency extraction for Sephera graph." -documentation = "https://docs.rs/sephera_graph_python" readme = "README.md" keywords = ["python", "dependencies", "tree-sitter", "pip", "pyproject"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_graph_rust/Cargo.toml b/crates/sephera_graph_rust/Cargo.toml index 5369d3be..a4735818 100644 --- a/crates/sephera_graph_rust/Cargo.toml +++ b/crates/sephera_graph_rust/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_graph_rust" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Rust dependency extraction for Sephera graph." -documentation = "https://docs.rs/sephera_graph_rust" readme = "README.md" keywords = ["rust", "dependencies", "tree-sitter", "cargo"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_ignore/Cargo.toml b/crates/sephera_ignore/Cargo.toml index 26d0293e..4ba6b077 100644 --- a/crates/sephera_ignore/Cargo.toml +++ b/crates/sephera_ignore/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_ignore" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Git-aware ignore rules (.gitignore, .sepheraignore) with globset matching." -documentation = "https://docs.rs/sephera_ignore" readme = "README.md" keywords = ["gitignore", "glob", "ignore", "filesystem"] categories = ["development-tools", "filesystem"] diff --git a/crates/sephera_mcp/Cargo.toml b/crates/sephera_mcp/Cargo.toml index 687bedcc..60ea8400 100644 --- a/crates/sephera_mcp/Cargo.toml +++ b/crates/sephera_mcp/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_mcp" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "MCP server for Sephera — exposes LOC analysis, context packs, and dependency graphs to AI agents over the Model Context Protocol." -documentation = "https://docs.rs/sephera_mcp" keywords = ["mcp", "ai", "context", "llm", "tree-sitter"] categories = ["command-line-utilities", "development-tools"] diff --git a/crates/sephera_runtime/Cargo.toml b/crates/sephera_runtime/Cargo.toml index 28c1e468..976dda7a 100644 --- a/crates/sephera_runtime/Cargo.toml +++ b/crates/sephera_runtime/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_runtime" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Source resolution: local paths, git clones (shallow), remote URLs, config loading." -documentation = "https://docs.rs/sephera_runtime" readme = "README.md" keywords = ["git", "clone", "url", "source", "config"] categories = ["development-tools", "command-line-utilities"] diff --git a/crates/sephera_scan/Cargo.toml b/crates/sephera_scan/Cargo.toml index bc503d15..28385c13 100644 --- a/crates/sephera_scan/Cargo.toml +++ b/crates/sephera_scan/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_scan" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Fast line-of-code counting with language-aware comment detection." -documentation = "https://docs.rs/sephera_scan" readme = "README.md" keywords = ["loc", "code-metrics", "tree-sitter", "scanner"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_symbols/Cargo.toml b/crates/sephera_symbols/Cargo.toml index 7e5fbe77..40735d2e 100644 --- a/crates/sephera_symbols/Cargo.toml +++ b/crates/sephera_symbols/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "sephera_symbols" version.workspace = true edition.workspace = true @@ -8,7 +9,6 @@ repository.workspace = true homepage.workspace = true rust-version.workspace = true description = "Symbol extraction and declaration analysis across languages." -documentation = "https://docs.rs/sephera_symbols" readme = "README.md" keywords = ["symbols", "ast", "tree-sitter", "declarations", "imports"] categories = ["development-tools", "text-processing"] diff --git a/crates/sephera_tools/src/language_data/validate.rs b/crates/sephera_tools/src/language_data/validate.rs index a6fcb518..eb2456f4 100644 --- a/crates/sephera_tools/src/language_data/validate.rs +++ b/crates/sephera_tools/src/language_data/validate.rs @@ -94,7 +94,7 @@ pub fn validate_registry( let extension_key = extension.trim_start_matches('.').to_owned(); if let Some(previous_language) = - seen_extensions.insert(extension_key.clone(), name.to_owned()) + seen_extensions.insert(extension_key, name.to_owned()) { bail!( "extension `{extension}` is defined by both `{previous_language}` and `{name}`" diff --git a/pyrightconfig.json b/pyrightconfig.json index 806dd45c..75749b8f 100644 --- a/pyrightconfig.json +++ b/pyrightconfig.json @@ -5,9 +5,7 @@ "benchmarks/benchmark_harness.py", "benchmarks/benchmark_model.py", "benchmarks/benchmark_render.py", - "scripts/make_graph_demo.py", "scripts/pr_report.py", - "scripts/probe_symbol_node_kinds.py", "scripts/verify_mcp_graph_formats.py", "scripts/verify_mcp_symbols.py", "scripts/check_doc_links.py", diff --git a/scripts/check_publish_order.py b/scripts/check_publish_order.py index 063ed21a..5ea7f5cf 100644 --- a/scripts/check_publish_order.py +++ b/scripts/check_publish_order.py @@ -293,6 +293,9 @@ def readme(crate: str, summary: str, wanted: str, deps: list[str]) -> str: def write_readmes(names: dict[str, pathlib.Path], paths: dict[str, set[str]]) -> int: written = 0 for crate, (summary, wanted) in CRATE_NOTES.items(): + if crate not in names: + # Not publishable (publish = false): no crates.io README needed. + continue target = names[crate] / "README.md" if target.exists(): continue diff --git a/scripts/check_version.py b/scripts/check_version.py new file mode 100644 index 00000000..c5cd2347 --- /dev/null +++ b/scripts/check_version.py @@ -0,0 +1,104 @@ +#!/usr/bin/env python3 +"""Verify the three version declarations stay in step. + +The workspace version lives in the root Cargo.toml. The Tauri host +(gui/src-tauri/) is outside the workspace (to keep Node/GTK out of +`cargo test --workspace`), so it carries its own version in two places: +gui/src-tauri/Cargo.toml and gui/src-tauri/tauri.conf.json. This script +asserts all three agree. + +Versions are read structurally (tomllib / json), never by regex: a +`^version` scan cannot tell `[workspace.package]` from a dependency's +inline `version = ...` key, and would silently read the wrong one if a +`[package]` section were ever added to the root manifest. + +Run from the repo root. Exits 0 when in sync, 1 with a message when not. +""" + +import json +import sys +import tomllib +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent + + +def _load_toml(path: Path) -> dict: + try: + return tomllib.loads(path.read_text(encoding="utf-8")) + except tomllib.TOMLDecodeError as error: + print(f"error: {path} is not valid TOML: {error}", file=sys.stderr) + sys.exit(1) + + +def _version_at(table: dict, *keys: str, source: str) -> str: + value: object = table + for key in keys: + if not isinstance(value, dict) or key not in value: + print( + f"error: no version at {'.'.join(keys)} in {source}", + file=sys.stderr, + ) + sys.exit(1) + value = value[key] + if not isinstance(value, str) or not value: + print(f"error: version at {'.'.join(keys)} in {source} is not a string", + file=sys.stderr) + sys.exit(1) + return value + + +def workspace_version() -> str: + return _version_at( + _load_toml(ROOT / "Cargo.toml"), + "workspace", + "package", + "version", + source="root Cargo.toml", + ) + + +def tauri_cargo_version() -> str: + return _version_at( + _load_toml(ROOT / "gui" / "src-tauri" / "Cargo.toml"), + "package", + "version", + source="gui/src-tauri/Cargo.toml", + ) + + +def tauri_conf_version() -> str: + conf = json.loads( + (ROOT / "gui" / "src-tauri" / "tauri.conf.json").read_text(encoding="utf-8") + ) + version = conf.get("version") + if not version: + print("error: no version in gui/src-tauri/tauri.conf.json", file=sys.stderr) + sys.exit(1) + return str(version) + + +def main() -> int: + root = workspace_version() + cargo = tauri_cargo_version() + conf = tauri_conf_version() + problems = [] + if cargo != root: + problems.append( + f"gui/src-tauri/Cargo.toml has {cargo!r}, root has {root!r}" + ) + if conf != root: + problems.append( + f"gui/src-tauri/tauri.conf.json has {conf!r}, root has {root!r}" + ) + if problems: + print("version mismatch:", file=sys.stderr) + for p in problems: + print(f" - {p}", file=sys.stderr) + return 1 + print(f"versions agree on {root}.") + return 0 + + +if __name__ == "__main__": + sys.exit(main())