Code graph and memory for your coding agents, in one Rust program. For Claude Code, Codex, Cursor and any MCP client.
Rust agent-memoryai-agentsclaude-codecode-analysiscode-graphcode-intelligencecode-searchcodexcoding-agentscontext-engineeringcursordeveloper-toolsgraphragknowledge-graphlocal-firstmcpmcp-servermodel-context-protocolrusttree-sitter
New-release notice, SignPath prep, privacy, qualification and upgrade docs
VikramLexbc3174c20cb3
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex d42cea4..fbede59 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -132,9 +132,85 @@ jobs:if-no-files-found: erroroverwrite: true- release:+ sign-windows:+ # Code signing of graphicle.exe and graphicle-graph.exe through SignPath+ # (docs/code-signing.md). It signs only when the SIGNPATH_API_TOKEN secret+ # is set; without it every step after the first is skipped and the release+ # ships the unsigned archive, as before. With it, the Windows archive goes+ # to SignPath as an artifact of this run, an approver approves the request+ # there, and the signed archive and its new .sha256 replace the+ # dist-x86_64-pc-windows-msvc artifact, so the release job's SHA256SUMS+ # covers the signed archive. The repository variables name the SignPath+ # organization, project, signing policy and artifact configuration.needs: buildruns-on: ubuntu-latest+ permissions:+ actions: read+ contents: read+ outputs:+ signed: ${{ steps.token.outputs.present }}+ steps:+ - name: Token+ id: token+ env:+ SIGNPATH_API_TOKEN: ${{ secrets.SIGNPATH_API_TOKEN }}+ run: |+ if [ -n "$SIGNPATH_API_TOKEN" ]; then+ echo "present=true" >> "$GITHUB_OUTPUT"+ else+ echo "present=false" >> "$GITHUB_OUTPUT"+ echo "::notice::SIGNPATH_API_TOKEN is not set: the Windows archive stays unsigned"+ fi+ - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1+ if: steps.token.outputs.present == 'true'+ with:+ name: dist-x86_64-pc-windows-msvc+ path: dist+ - name: Upload the unsigned archive+ id: unsigned+ if: steps.token.outputs.present == 'true'+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1+ with:+ name: windows-unsigned+ path: dist/graphicle-*-x86_64-pc-windows-msvc.zip+ if-no-files-found: error+ overwrite: true+ - name: Sign with SignPath+ if: steps.token.outputs.present == 'true'+ uses: signpath/github-action-submit-signing-request@f6d04783b4569d051e0c80105fe66e82819d0092 # v3.0+ with:+ api-token: ${{ secrets.SIGNPATH_API_TOKEN }}+ organization-id: ${{ vars.SIGNPATH_ORGANIZATION_ID }}+ project-slug: ${{ vars.SIGNPATH_PROJECT_SLUG }}+ signing-policy-slug: ${{ vars.SIGNPATH_POLICY_SLUG }}+ artifact-configuration-slug: ${{ vars.SIGNPATH_ARTIFACT_CONFIGURATION_SLUG }}+ github-artifact-id: ${{ steps.unsigned.outputs.artifact-id }}+ wait-for-completion: true+ # The approval is manual, so allow an hour.+ wait-for-completion-timeout-in-seconds: 3600+ output-artifact-directory: signed+ - name: Put the signed archive in place+ if: steps.token.outputs.present == 'true'+ run: |+ set -- dist/graphicle-*-x86_64-pc-windows-msvc.zip+ name="${1##*/}"+ test -f "signed/$name" || { echo "::error::SignPath returned no $name"; exit 1; }+ if cmp -s "dist/$name" "signed/$name"; then echo "::error::SignPath returned $name unchanged"; exit 1; fi+ # The signed archive must hold the same files as the unsigned one.+ diff <(unzip -Z1 "dist/$name" | grep -v '/$' | sort) <(unzip -Z1 "signed/$name" | grep -v '/$' | sort)+ mv -f "signed/$name" "dist/$name"+ cd dist && sha256sum "$name" > "$name.sha256" && cat "$name.sha256"+ - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1+ if: steps.token.outputs.present == 'true'+ with:+ name: dist-x86_64-pc-windows-msvc+ path: dist/+ if-no-files-found: error+ overwrite: true++ release:+ needs: [build, sign-windows]+ runs-on: ubuntu-latestpermissions:contents: writeoutputs:@@ -178,6 +254,7 @@ jobs:env:VERSION: ${{ steps.version.outputs.version }}PRERELEASE: ${{ steps.version.outputs.prerelease }}+ SIGNED: ${{ needs.sign-windows.outputs.signed }}run: |python3 packaging/homebrew/fill_formula.py --version "$VERSION" --sums dist/SHA256SUMS --out dist/graphicle.rbcp install.sh dist/install.sh@@ -207,6 +284,10 @@ jobs:printf '$env:GRAPHICLE_VERSION = '"'"'%s'"'"'; irm https://github.com/%s/releases/download/v%s/install.ps1 | iex\n' \"$VERSION" "$GITHUB_REPOSITORY" "$VERSION"printf '```\n\nEach archive'"'"'s SHA-256 sum is in SHA256SUMS and beside it in a .sha256 file.\n'+ if [ "$SIGNED" = true ]; then+ printf '\nThe Windows programs are signed through SignPath: [Code signing policy](https://github.com/%s/blob/%s/docs/code-signing.md).\n' \+ "$GITHUB_REPOSITORY" "$GITHUB_REF_NAME"+ fi} >> "$RUNNER_TEMP/notes.md"cp "$RUNNER_TEMP/notes.md" dist/RELEASE_NOTES.mdls -l distdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex b2b1467..db65c47 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,8 +11,10 @@ Every crate is at 0.1.1, and `graphicle --version` prints### Code graph- The engine follows Graphify 0.9.91 (0.1.0 followed 0.9.88): the three- releases 0.9.89 to 0.9.91 are ported, and the comparison checks pass- against 0.9.91. What changes in the graph:+ releases 0.9.89 to 0.9.91 are ported. Against 0.9.91 the comparison checks+ have run on Linux, where the only checks that do not pass stop for reasons+ of that host; the full run on macOS is still to be made+ (`docs/benchmarks.md`). What changes in the graph:- Go: a package type whose methods span several files is one node, andthe methods of a generic receiver (`func (b *Box[T])`) attach to `Box`.Member calls on a typed receiver are bound; when the receiver's type is@@ -167,9 +169,21 @@ token or accuracy claim; it trims that text.- On Windows, the memory library reads a source named in a graph only whenits path stays inside the project folder: no drive, network-share, rootedor `..` paths.+- The Windows programs are not code-signed yet. `docs/code-signing.md` is the+ code signing policy for the planned signing through the SignPath+ Foundation; the release workflow's signing job stays off until then.### Other changes+- A new-release notice, like the GitHub CLI's. Once a day, when you run a+ command in a terminal, `graphicle` asks GitHub's releases API for the+ latest release. That is one GET request, with no code or data in it; when+ GitHub has not answered by the time the command ends, the request is made+ again with the next command. When the release is newer, `graphicle` prints the version, the upgrade+ command for your install and the release page on standard error. It never+ checks from the MCP server, `serve`, hooks, session capture, `update`,+ CI, or JSON or piped output. `GRAPHICLE_NO_UPDATE_NOTIFIER=1` or+ `graphicle config set update_notifier false` turns it off.- The repository's `.gitattributes` checks text files out with LF lineendings on every system.diff --git a/README.md b/README.mdindex 73d4acd..cda59e2 100644--- a/README.md+++ b/README.md@@ -92,7 +92,7 @@ then run `graphicle setup --yes` in this repository and list every file it chang- **Cited context, within a budget you set.** Your agent asks Graphicle and gets the relevant code, docs and decisions as cited excerpts, within a token budget you set. In our tests it tied grep on finding code, and we do not claim it saves tokens ([what we measured](#benchmarks)).- **Answers you can check.** Every excerpt names its file and lines. Memories an agent proposes wait for your approval.- **One program, not a stack.** The code graph, the memory, one MCP server, the web app and the command line come in one install, with one SQLite file. No Python, Docker or database server.-- **Local and private.** No account and no telemetry. Nothing leaves your machine unless you ask.+- **Local and private.** No account and no telemetry. Your code and data leave your machine only when you ask. The only automatic request is a daily check for a new release, which `GRAPHICLE_NO_UPDATE_NOTIFIER=1` turns off.<p align="center"><picture>@@ -171,8 +171,9 @@ Every figure is labelled, and [docs/benchmarks.md](docs/benchmarks.md) has the f- **One data folder.** Your sources, memories and the code graph that setup builds live in one SQLite store: `~/Library/Application Support/Graphicle` on macOS, `~/.local/share/graphicle` on Linux. `graphicle graph extract` writes its graph file to `.graphicle/` in the project.- **Loopback by default.** The app and its HTTP and MCP endpoints listen on 127.0.0.1.-- **No telemetry, no account.** Graphicle connects to the network only when you ask it to: a model or a connector you configure, a full `graphicle graph extract`- (it sends documents and images to the LLM whose API key it finds), the GitHub CLI for `graphicle graph add`, `clone` and the graph server's pull-request tools, and `graphicle update` with a feed you name.+- **No telemetry, no account.** Graphicle connects to the network only in these cases: a model or a connector you configure, a full `graphicle graph extract`+ (it sends documents and images to the LLM whose API key it finds), the GitHub CLI for `graphicle graph add`, `clone` and the graph server's pull-request tools, `graphicle update` with a feed you name, and a daily check for a new release.+ That check is on by default: a command you run in a terminal asks GitHub for the latest release, with no code or data, to tell you about a new one (`GRAPHICLE_NO_UPDATE_NOTIFIER=1` turns it off).A build from source also downloads the parser sources once. [Details](docs/faq.md)- **Careful sync.** `sync` respects `.gitignore` and skips `.env` files, keys and credentials. Session capture drops `<private>…</private>` spans and redacts credentials.- **Forgetting with a receipt.** Deleting a memory or a captured session also removes what was derived from it, and you get a hash-chained deletion receipt.@@ -233,6 +234,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). To report a security problem, follow [SEGraphicle is licensed under the [Apache License 2.0](LICENSE). Copyright 2026 KarLex AI, Inc.+[Code signing policy](docs/code-signing.md): the Windows programs are not code-signed yet; signing through the SignPath Foundation is planned.+The code-graph engine is a Rust port of [Graphify](https://github.com/Graphify-Labs/graphify) by Safi Shamsi and the Graphifycontributors, licensed under Apache-2.0, with portions that remain available under the MIT License. Thank you.[NOTICE](NOTICE), [NOTICE.md](NOTICE.md) and the `licenses/` folders hold the attributions and the licences of every adapted project and third-party component.diff --git a/crates/graphicle/src/cli.rs b/crates/graphicle/src/cli.rsindex ec93eb2..04515ba 100644--- a/crates/graphicle/src/cli.rs+++ b/crates/graphicle/src/cli.rs@@ -626,13 +626,18 @@ pub fn main_with(extensions: Extensions) -> i32 {}crate::extension::install(extensions);crate::fresh::allow_background_builds();+ crate::update_notice::allow();tokio::runtime::Builder::new_multi_thread().enable_all().build().expect("Failed building the Runtime").block_on(async {let code = match run(std::env::args_os()).await {- Ok(()) => 0,+ Ok(()) => {+ // The new-release notice, when one is due.+ crate::update_notice::finish();+ 0+ }Err(error) => {// The common errors name the command that fixes them.eprintln!("graphicle: {}", crate::terminal::explain(&error.message));@@ -685,6 +690,36 @@ fn unread_environment(read: &[&str], set: impl Fn(&str) -> bool) -> Option<&'sta.copied().find(|name| set(name) && !read.contains(name))}+/// Whether the new-release notice ([`crate::update_notice`]) may follow+/// `command` (`None`: `graphicle` alone): a command people run at a terminal+/// that prints its readable view. Never the servers (`mcp`, `serve`, `open`),+/// hooks, session capture, workers, `update`, `uninstall`, a quiet sync or+/// JSON output.+fn notice_allowed(command: Option<&Command>) -> bool {+ use crate::terminal::ConfigAction;+ let json = match command {+ None+ | Some(Command::Config {+ action: None | Some(ConfigAction::Show { json: false }),+ }) => false,+ Some(+ Command::Setup { json, .. }+ | Command::Connect { json, .. }+ | Command::Disconnect { json, .. }+ | Command::Status { json, .. }+ | Command::Doctor { json, .. }+ | Command::Context { json, .. }+ | Command::Ask { json, .. }+ | Command::WorkState { json, .. }+ | Command::Config {+ action: Some(ConfigAction::Set { json, .. }),+ },+ ) => *json,+ Some(Command::Sync { json, quiet, .. }) => *json || *quiet,+ _ => return false,+ };+ crate::terminal::human(json)+}/// Run one command line (`args` includes the program name). Usage errors,/// `--help` and `--version` print and end the process, as clap does.pub async fn run<I, T>(args: I) -> Result<()>@@ -712,6 +747,15 @@ whereOk(cli) => cli,Err(error) => error.format(&mut interface.clone()).exit(),};+ // The new-release check runs beside an interactive command (it does+ // nothing in a test's process); `main_with` prints the notice after it.+ crate::update_notice::start(+ notice_allowed(cli.command.as_ref()),+ &crate::terminal::config_path(+ cli.config.as_deref(),+ &cli.data_dir.clone().unwrap_or_else(local::data_dir),+ ),+ );// `graphicle` alone: this project's short status, or how to start. It// creates nothing (earlier builds opened the app).let Some(command) = cli.command else {diff --git a/crates/graphicle/src/lib.rs b/crates/graphicle/src/lib.rsindex e955fcc..79892b6 100644--- a/crates/graphicle/src/lib.rs+++ b/crates/graphicle/src/lib.rs@@ -63,6 +63,7 @@ pub mod structured_memory;pub mod symbols;pub mod temporal_graph;pub mod terminal;+pub mod update_notice;pub mod vault;pub mod vector;pub mod work_state;diff --git a/crates/graphicle/src/model.rs b/crates/graphicle/src/model.rsindex 7761c21..743ca91 100644--- a/crates/graphicle/src/model.rs+++ b/crates/graphicle/src/model.rs@@ -85,6 +85,11 @@ pub struct Config {/// `GRAPHICLE_MAX_*` environment variables win over these.#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]pub limits: BTreeMap<String, Value>,+ /// The new-release notice after interactive commands+ /// ([`crate::update_notice`]): `false` turns it off, as the environment+ /// variable `GRAPHICLE_NO_UPDATE_NOTIFIER` does.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub update_notifier: Option<bool>,}fn concurrency_default() -> usize {1@@ -102,6 +107,7 @@ impl Default for Config {max_queued_bytes_per_repository: None,freshness: None,limits: BTreeMap::new(),+ update_notifier: None,}}}diff --git a/crates/graphicle/src/terminal.rs b/crates/graphicle/src/terminal.rsindex b250d2a..574331b 100644--- a/crates/graphicle/src/terminal.rs+++ b/crates/graphicle/src/terminal.rs@@ -2969,6 +2969,9 @@ pub fn config_command(} else if key == "freshness" {// GRAPHICLE_FRESHNESS overrides the file (ux-fresh).Some(json!(crate::fresh::mode(&load()?)))+ } else if key == crate::update_notice::SETTING {+ // GRAPHICLE_NO_UPDATE_NOTIFIER overrides the file.+ Some(json!(crate::update_notice::on(&path)))} else if let Some(name) = key.strip_prefix("limits.")&& crate::limits::SETTINGS.iter()diff --git a/crates/graphicle/src/update_notice.rs b/crates/graphicle/src/update_notice.rsnew file mode 100644index 0000000..ed4d854--- /dev/null+++ b/crates/graphicle/src/update_notice.rs@@ -0,0 +1,828 @@+//! The new-release notice. After a command people run at a terminal, at most+//! once a day, Graphicle asks GitHub for its latest release and, when that+//! release is newer than this program, prints on standard error:+//!+//! ```text+//! A new release of graphicle is available: 0.1.1 → 0.1.2+//! To upgrade, run: brew upgrade graphicle+//! https://github.com/graphicle-ai/graphicle/releases/tag/v0.1.2+//! ```+//!+//! - **What is sent.** One GET of [`LATEST`] (GitHub's releases API), with+//! the User-Agent `graphicle` and nothing else: no code, project data,+//! version or credentials. The answer's `tag_name` and `html_url` are kept+//! in `update-check.json` in the cache folder ([`state_path`]).+//! - **When.** The check runs on its own thread while the command runs, with+//! a 2-second timeout ([`TIMEOUT`]). After the command, the program waits+//! for it at most [`WAIT`]; a check that has not finished by then is+//! dropped and runs again after the next command. A failed check counts+//! as a check and prints nothing. The notice itself is printed at most once+//! a day, from the last answer.+//! - **Never** ([`allowed`]): when standard error is not a terminal, on CI+//! ([`CI_ENV`]), with [`OPT_OUT_ENV`] set to any non-empty value, with+//! `update_notifier: false` in the configuration ([`SETTING`]), in a+//! development build, and after any command `crate::cli` does not call+//! interactive: never after the servers (`mcp`, `serve`, `open`), hooks,+//! session capture, workers, JSON output, `graphicle graph …` or `update`.+//!+//! Nothing is checked in a test's process (only [`crate::cli::main_with`]+//! calls [`allow`]), nor by an edition other than Core: GitHub's releases+//! are Core's.+use crate::{local, platform::CanonicalExt, terminal::Install};+use serde::{Deserialize, Serialize};+use serde_json::Value;+use std::{+ cmp::Ordering,+ ffi::OsString,+ io::{IsTerminal, Read as _, Write as _},+ path::{Path, PathBuf},+ sync::{+ Mutex,+ atomic::{AtomicBool, Ordering as AtomicOrdering},+ mpsc,+ },+ time::Duration,+};++/// GitHub's latest-release endpoint for Graphicle (drafts and pre-releases+/// are never the latest release there).+pub const LATEST: &str = "https://api.github.com/repos/Graphicle-AI/graphicle/releases/latest";+/// Any non-empty value turns the check and the notice off.+pub const OPT_OUT_ENV: &str = "GRAPHICLE_NO_UPDATE_NOTIFIER";+/// The configuration key: `graphicle config set update_notifier false`.+pub const SETTING: &str = "update_notifier";+/// Environment variables that mark a CI run (any non-empty value).+pub const CI_ENV: &[&str] = &[+ "CI",+ "CONTINUOUS_INTEGRATION",+ "BUILD_NUMBER",+ "RUN_ID",+ "GITHUB_ACTIONS",+ "GITLAB_CI",+ "BUILDKITE",+ "CIRCLECI",+ "TRAVIS",+ "JENKINS_URL",+ "TEAMCITY_VERSION",+ "TF_BUILD",+ "CODEBUILD_BUILD_ID",+ "BITBUCKET_BUILD_NUMBER",+ "APPVEYOR",+ "DRONE",+];+/// The whole request's time limit.+pub const TIMEOUT: Duration = Duration::from_secs(2);+/// The most a command waits for an unfinished check after it is done.+pub const WAIT: Duration = Duration::from_millis(200);+/// How long a check, and a printed notice, last.+const DAY: i64 = 24 * 60 * 60;+/// The state file's name in the cache folder.+const STATE_FILE: &str = "update-check.json";++static ALLOWED: AtomicBool = AtomicBool::new(false);+static PENDING: Mutex<Option<Pending>> = Mutex::new(None);++/// What [`start`] leaves for [`finish`].+struct Pending {+ path: PathBuf,+ /// The configuration file, read again after the command.+ config: PathBuf,+ /// The state before the command.+ state: State,+ /// The check's state, when [`start`] began one.+ check: Option<mpsc::Receiver<State>>,+}++/// A release: its version (without the tag's `v`) and its page.+#[derive(Clone, Debug, PartialEq, Eq)]+pub struct Release {+ pub version: String,+ pub url: String,+}++impl Release {+ /// The release in GitHub's answer: `tag_name` a version, `html_url` a page+ /// on github.com, both plain printable text; never a draft or a+ /// pre-release.+ pub fn from_api(value: &Value) -> Option<Self> {+ if value["draft"] == true || value["prerelease"] == true {+ return None;+ }+ let tag = value["tag_name"].as_str()?;+ let version = tag.strip_prefix('v').unwrap_or(tag);+ parse(version)?;+ let url = value["html_url"].as_str()?;+ if url.len() > 300+ || !url.starts_with("https://github.com/")+ || !url.bytes().all(|b| b.is_ascii_graphic())+ {+ return None;+ }+ Some(Self {+ version: version.to_string(),+ url: url.to_string(),+ })+ }+}++/// `update-check.json`.+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]+pub struct State {+ /// When the latest release was last asked for (Unix seconds), answered+ /// or not.+ #[serde(default)]+ pub checked_at: i64,+ /// The latest release's version then.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub latest: Option<String>,+ /// Its page.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub url: Option<String>,+ /// When the notice was last printed (Unix seconds).+ #[serde(default)]+ pub notified_at: i64,+}++// ------------------------------------------------------------- versions++/// `major.minor.patch` with its pre-release identifiers (build metadata+/// dropped).+#[derive(Debug, PartialEq, Eq)]+struct Version {+ core: (u64, u64, u64),+ pre: Vec<String>,+}++impl Ord for Version {+ /// Semantic Versioning's order: a pre-release comes before its release;+ /// numeric identifiers compare as numbers and before alphanumeric ones.+ fn cmp(&self, other: &Self) -> Ordering {+ self.core+ .cmp(&other.core)+ .then_with(|| match (self.pre.is_empty(), other.pre.is_empty()) {+ (true, true) => Ordering::Equal,+ (true, false) => Ordering::Greater,+ (false, true) => Ordering::Less,+ (false, false) => {+ for (a, b) in self.pre.iter().zip(&other.pre) {+ let order = match (a.parse::<u64>(), b.parse::<u64>()) {+ (Ok(a), Ok(b)) => a.cmp(&b),+ (Ok(_), Err(_)) => Ordering::Less,+ (Err(_), Ok(_)) => Ordering::Greater,+ (Err(_), Err(_)) => a.cmp(b),+ };+ if order != Ordering::Equal {+ return order;+ }+ }+ self.pre.len().cmp(&other.pre.len())+ }+ })+ }+}++impl PartialOrd for Version {+ fn partial_cmp(&self, other: &Self) -> Option<Ordering> {+ Some(self.cmp(other))+ }+}++/// `major.minor.patch[-pre][+build]`, a leading `v` allowed.+fn parse(text: &str) -> Option<Version> {+ let text = text.strip_prefix('v').unwrap_or(text);+ if text.is_empty()+ || text.len() > 64+ || !text+ .bytes()+ .all(|b| b.is_ascii_alphanumeric() || b".-+".contains(&b))+ {+ return None;+ }+ let text = text.split_once('+').map_or(text, |(version, _)| version);+ let (core, pre) = match text.split_once('-') {+ Some((core, pre)) => (core, Some(pre)),+ None => (text, None),+ };+ let numbers: Vec<u64> = core+ .split('.')+ .map(|part| part.parse().ok())+ .collect::<Option<_>>()?;+ let [major, minor, patch] = numbers[..] else {+ return None;+ };+ let pre: Vec<String> = pre+ .map(|pre| pre.split('.').map(str::to_string).collect())+ .unwrap_or_default();+ if pre.iter().any(String::is_empty) {+ return None;+ }+ Some(Version {+ core: (major, minor, patch),+ pre,+ })+}++/// Whether `latest` is a release (no pre-release suffix) newer than+/// `current`. False when either does not parse.+pub fn newer(latest: &str, current: &str) -> bool {+ match (parse(latest), parse(current)) {+ (Some(latest), Some(current)) => latest.pre.is_empty() && latest > current,+ _ => false,+ }+}++/// A development build: a debug build, or a version that does not parse,+/// is 0.0.0 or names `dev`.+pub fn development(version: &str, debug_build: bool) -> bool {+ debug_build+ || parse(version).is_none_or(|v| v.core == (0, 0, 0))+ || version.to_ascii_lowercase().contains("dev")+}++// ---------------------------------------------------------------- gates++/// What decides whether a command may check ([`allowed`]).+pub struct Gates<'a> {+ /// The command prints its readable view for people (`crate::cli`+ /// decides; never a server, hook, capture, worker, JSON or `update`).+ pub interactive: bool,+ pub stderr_terminal: bool,+ /// The environment.+ pub env: &'a dyn Fn(&str) -> Option<OsString>,+ /// `update_notifier` in the configuration ([`setting`]), read only when+ /// the other gates pass.+ pub setting: &'a dyn Fn() -> Option<bool>,+ /// This program's version.+ pub version: &'a str,+ pub debug_build: bool,+}++/// Whether the check, and the notice, may run.+pub fn allowed(gates: &Gates) -> bool {+ let set = |name: &str| (gates.env)(name).is_some_and(|value| !value.is_empty());+ gates.interactive+ && gates.stderr_terminal+ && !set(OPT_OUT_ENV)+ && !CI_ENV.iter().any(|&name| set(name))+ && !development(gates.version, gates.debug_build)+ && (gates.setting)() != Some(false)+}++/// `update_notifier` in the configuration file at `path`: `None` when the+/// file or the key is missing; `Some(false)` when the value is not `true`+/// or the file cannot be read as JSON, so nothing is checked then.+pub fn setting(path: &Path) -> Option<bool> {+ match crate::terminal::read_config(path) {+ Ok(document) => document+ .get(SETTING)+ .map(|value| value.as_bool().unwrap_or(false)),+ Err(_) => Some(false),+ }+}++/// Whether the notice is on for the configuration file at `path` in this+/// environment (`graphicle config get update_notifier`).+pub fn on(path: &Path) -> bool {+ std::env::var_os(OPT_OUT_ENV).is_none_or(|value| value.is_empty())+ && setting(path) != Some(false)+}++// ---------------------------------------------------------------- state++/// `update-check.json` in Graphicle's cache folder: `$XDG_CACHE_HOME`+/// (an absolute path), else `.cache` in the home folder, then `graphicle`;+/// the graph engine keeps its caches there too.+pub fn state_path() -> Option<PathBuf> {+ let base = std::env::var_os("XDG_CACHE_HOME")+ .map(PathBuf::from)+ .filter(|path| path.is_absolute())+ .or_else(|| {+ crate::platform::home_dir()+ .filter(|home| home.is_absolute())+ .map(|home| home.join(".cache"))+ })?;+ Some(base.join("graphicle").join(STATE_FILE))+}++/// The state at `path`; empty when it is missing, larger than 4 KiB or not+/// valid.+pub fn read_state(path: &Path) -> State {+ let mut bytes = Vec::new();+ let read = std::fs::File::open(path).and_then(|file| file.take(4097).read_to_end(&mut bytes));+ if read.is_err() || bytes.len() > 4096 {+ return State::default();+ }+ serde_json::from_slice(&bytes).unwrap_or_default()+}++fn write_state(path: &Path, state: &State) {+ if let Ok(bytes) = serde_json::to_vec(state) {+ let _ = local::write_private(path, &bytes);+ }+}++/// Whether the state's check is a day old, or later than `now` (the clock+/// moved back).+pub fn due(state: &State, now: i64) -> bool {+ state.checked_at <= 0 || now - state.checked_at >= DAY || state.checked_at > now + 60+}++/// One check of the state at `path`: when it is [`due`], ask `fetch` for the+/// latest release and record the answer. A failed fetch is recorded as a+/// check that keeps the last known release. Returns the state after it.+pub fn check(path: &Path, now: i64, fetch: &dyn Fn() -> Option<Release>) -> State {+ let mut state = read_state(path);+ if !due(&state, now) {+ return state;+ }+ if let Some(release) = fetch() {+ state.latest = Some(release.version);+ state.url = Some(release.url);+ }+ state.checked_at = now;+ // A notice another command printed meanwhile.+ state.notified_at = state.notified_at.max(read_state(path).notified_at);+ write_state(path, &state);+ state+}++// --------------------------------------------------------------- notice++/// The command that upgrades this program, from `graphicle update`'s+/// install method: `brew upgrade graphicle`, the install script's line+/// (install.sh, or install.ps1 in PowerShell on Windows), else `graphicle+/// update`, which lists the steps (source, cargo and container installs).+pub fn upgrade_command(install: &Install) -> String {+ match (install.method, install.commands.as_slice()) {+ ("homebrew", _) => "brew upgrade graphicle".into(),+ ("script", [line]) => line.clone(),+ _ => "graphicle update".into(),+ }+}++/// The notice for `state`, when its latest release is newer than `current`+/// and no notice was printed in the last day.+pub fn notice(state: &State, current: &str, now: i64, upgrade: &str) -> Option<String> {+ let latest = state.latest.as_deref()?;+ if !newer(latest, current) {+ return None;+ }+ let printed = state.notified_at;+ if printed > 0 && printed <= now + 60 && now - printed < DAY {+ return None;+ }+ let mut text = format!(+ "\nA new release of graphicle is available: {current} → {latest}\nTo upgrade, run: {upgrade}\n"+ );+ if let Some(url) = &state.url {+ text.push_str(url);+ text.push('\n');+ }+ Some(text)+}++// ------------------------------------------------------------- the run++/// Lets this process check ([`crate::cli::main_with`] calls it): only the+/// program itself, never a test running the command line in-process.+pub fn allow() {+ ALLOWED.store(true, AtomicOrdering::Relaxed);+}++fn now() -> i64 {+ std::time::SystemTime::now()+ .duration_since(std::time::UNIX_EPOCH)+ .map_or(0, |elapsed| elapsed.as_secs() as i64)+}++/// Before a command runs: when [`allowed`], start a check on its own thread+/// if one is [`due`]. `interactive`: the command prints its readable view+/// for people (`crate::cli` decides); `config`: the configuration file.+pub fn start(interactive: bool, config: &Path) {+ // GitHub's releases are Graphicle Core's; another edition updates its own way.+ if !ALLOWED.load(AtomicOrdering::Relaxed) || crate::core_capabilities::edition() != "core" {+ return;+ }+ let gates = Gates {+ interactive,+ stderr_terminal: std::io::stderr().is_terminal(),+ env: &|name| std::env::var_os(name),+ setting: &|| setting(config),+ version: env!("CARGO_PKG_VERSION"),+ debug_build: cfg!(debug_assertions),+ };+ if !allowed(&gates) {+ return;+ }+ let Some(path) = state_path() else {+ return;+ };+ let now = now();+ let state = read_state(&path);+ let check = if due(&state, now) {+ spawn_check(path.clone(), now)+ } else {+ None+ };+ if let Ok(mut pending) = PENDING.lock() {+ *pending = Some(Pending {+ path,+ config: config.to_path_buf(),+ state,+ check,+ });+ }+}++/// The check on its own thread with its own small runtime, so that the+/// program never waits for it at exit: a request (or a name lookup) still+/// running then ends with the process.+fn spawn_check(path: PathBuf, now: i64) -> Option<mpsc::Receiver<State>> {+ let (send, receive) = mpsc::channel();+ std::thread::Builder::new()+ .name("graphicle-update-check".into())+ .spawn(move || {+ let Ok(runtime) = tokio::runtime::Builder::new_current_thread()+ .enable_all()+ .build()+ else {+ return;+ };+ let state = check(&path, now, &|| runtime.block_on(latest_release()));+ let _ = send.send(state);+ runtime.shutdown_background();+ })+ .ok()?;+ Some(receive)+}++/// GitHub's latest release of Graphicle, or `None` on any error.+async fn latest_release() -> Option<Release> {+ let response = crate::model::client_with_timeout(TIMEOUT)+ .ok()?+ .get(LATEST)+ .header(reqwest::header::USER_AGENT, "graphicle")+ .header(reqwest::header::ACCEPT, "application/vnd.github+json")+ .send()+ .await+ .ok()?;+ Release::from_api(&crate::model::bounded_json(response).await.ok()?)+}++/// After a command that succeeded: wait at most [`WAIT`] for the check+/// [`start`] began, then print the notice on standard error when one is due,+/// and record when. Silent on any error.+pub fn finish() {+ let Some(pending) = PENDING.lock().ok().and_then(|mut pending| pending.take()) else {+ return;+ };+ // The command may have turned the notice off (`config set update_notifier false`).+ if setting(&pending.config) == Some(false) {+ return;+ }+ let state = match pending.check {+ Some(check) => check.recv_timeout(WAIT).unwrap_or(pending.state),+ None => pending.state,+ };+ let now = now();+ let exe = std::env::current_exe()+ .ok()+ .map(|exe| exe.canonical().unwrap_or(exe))+ .unwrap_or_default();+ let upgrade = upgrade_command(&crate::terminal::installed(&exe));+ let Some(text) = notice(&state, env!("CARGO_PKG_VERSION"), now, &upgrade) else {+ return;+ };+ if std::io::stderr().lock().write_all(text.as_bytes()).is_err() {+ return;+ }+ let mut saved = read_state(&pending.path);+ if saved.checked_at < state.checked_at {+ saved = state;+ }+ saved.notified_at = now;+ write_state(&pending.path, &saved);+}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;+ use std::cell::Cell;++ const NOW: i64 = 1_792_000_000;++ fn release(version: &str) -> Release {+ Release {+ version: version.into(),+ url: format!("https://github.com/graphicle-ai/graphicle/releases/tag/v{version}"),+ }+ }++ #[test]+ fn versions_compare_as_semantic_versions_with_pre_releases() {+ assert!(newer("0.1.2", "0.1.1"));+ assert!(newer("v1.2.0", "1.1.9"));+ assert!(newer("0.1.10", "0.1.9"), "numbers, not text");+ assert!(newer("1.0.0", "0.99.99"));+ assert!(!newer("0.1.1", "0.1.1"));+ assert!(!newer("0.1.0", "0.1.1"));+ assert!(+ !newer("0.1.1+build.7", "0.1.1"),+ "build metadata is ignored"+ );+ // A release is newer than its own pre-release; a pre-release is never+ // offered.+ assert!(newer("0.1.2", "0.1.2-rc.1"));+ assert!(!newer("0.1.2-rc.1", "0.1.1"));+ assert!(!newer("0.1.3-rc.1", "0.1.2-rc.1"));+ // Semantic Versioning's own example order.+ let order = [+ "1.0.0-alpha",+ "1.0.0-alpha.1",+ "1.0.0-alpha.beta",+ "1.0.0-beta",+ "1.0.0-beta.2",+ "1.0.0-beta.11",+ "1.0.0-rc.1",+ "1.0.0",+ ];+ for pair in order.windows(2) {+ assert!(parse(pair[0]) < parse(pair[1]), "{} < {}", pair[0], pair[1]);+ }+ for bad in [+ "",+ "1.2",+ "1.2.3.4",+ "1.2.x",+ "1.2.3-",+ "1.2.3-a..b",+ "1.2.3\x1b[0m",+ ] {+ assert!(parse(bad).is_none(), "{bad:?}");+ assert!(!newer(bad, "0.1.1") && !newer("9.9.9", bad), "{bad:?}");+ }+ }++ #[test]+ fn development_builds_are_recognised() {+ assert!(!development("0.1.1", false));+ assert!(!development("0.1.2-rc.1", false));+ assert!(development("0.1.1", true), "a debug build");+ assert!(development("0.1.2-dev", false));+ assert!(development("0.1.2-dev.3", false));+ assert!(development("0.1.2+dev", false));+ assert!(development("0.0.0", false));+ assert!(development("main", false));+ }++ #[test]+ fn each_gate_turns_the_check_off() {+ fn gates_with(+ env: &[(&str, &str)],+ change: impl FnOnce(&mut (bool, bool, Option<bool>, &'static str, bool)),+ ) -> bool {+ let mut values = (true, true, None, "0.1.1", false);+ change(&mut values);+ let (interactive, stderr_terminal, setting, version, debug_build) = values;+ let env: Vec<(String, OsString)> = env+ .iter()+ .map(|(name, value)| (name.to_string(), OsString::from(value)))+ .collect();+ allowed(&Gates {+ interactive,+ stderr_terminal,+ env: &|name| {+ env.iter()+ .find(|(set, _)| set == name)+ .map(|(_, value)| value.clone())+ },+ setting: &|| setting,+ version,+ debug_build,+ })+ }+ assert!(gates_with(&[], |_| {}), "every gate open");+ assert!(gates_with(&[("HOME", "/home/me")], |_| {}));+ assert!(!gates_with(&[], |g| g.0 = false), "not interactive");+ assert!(!gates_with(&[], |g| g.1 = false), "stderr not a terminal");+ assert!(!gates_with(&[], |g| g.2 = Some(false)), "setting off");+ assert!(gates_with(&[], |g| g.2 = Some(true)));+ assert!(+ !gates_with(&[], |g| g.3 = "0.1.2-dev"),+ "development version"+ );+ assert!(!gates_with(&[], |g| g.4 = true), "debug build");+ for value in ["1", "0", "true", "no"] {+ assert!(!gates_with(&[(OPT_OUT_ENV, value)], |_| {}), "{value}");+ }+ assert!(gates_with(&[(OPT_OUT_ENV, "")], |_| {}), "empty is unset");+ for name in CI_ENV {+ assert!(!gates_with(&[(*name, "true")], |_| {}), "{name}");+ assert!(gates_with(&[(*name, "")], |_| {}), "{name} empty");+ }+ // The configuration is read only when every other gate passes.+ let read = Cell::new(false);+ let closed = allowed(&Gates {+ interactive: false,+ stderr_terminal: true,+ env: &|_| None,+ setting: &|| {+ read.set(true);+ None+ },+ version: "0.1.1",+ debug_build: false,+ });+ assert!(!closed && !read.get());+ }++ #[test]+ fn the_setting_is_read_from_the_configuration_file() {+ let folder = tempfile::tempdir().unwrap();+ let path = folder.path().join("models.json");+ assert_eq!(setting(&path), None, "no file");+ std::fs::write(&path, r#"{"freshness":"off"}"#).unwrap();+ assert_eq!(setting(&path), None, "no key");+ std::fs::write(&path, r#"{"update_notifier":false}"#).unwrap();+ assert_eq!(setting(&path), Some(false));+ std::fs::write(&path, r#"{"update_notifier":true}"#).unwrap();+ assert_eq!(setting(&path), Some(true));+ std::fs::write(&path, r#"{"update_notifier":"yes"}"#).unwrap();+ assert_eq!(setting(&path), Some(false), "not a boolean");+ std::fs::write(&path, "{not json").unwrap();+ assert_eq!(setting(&path), Some(false), "unreadable: no check");+ // `graphicle config set update_notifier false` writes a valid file.+ let config: crate::model::Config =+ serde_json::from_value(json!({"update_notifier": false})).unwrap();+ assert_eq!(config.update_notifier, Some(false));+ assert!(+ serde_json::from_value::<crate::model::Config>(json!({"update_notifier": "off"}))+ .is_err()+ );+ let plain = serde_json::to_value(crate::model::Config::default()).unwrap();+ assert!(plain.get(SETTING).is_none());+ }++ #[test]+ fn a_check_runs_at_most_once_a_day_and_failures_are_recorded() {+ let folder = tempfile::tempdir().unwrap();+ let path = folder.path().join("cache/graphicle").join(STATE_FILE);+ let calls = Cell::new(0);+ let answer = |release: Option<Release>| {+ let calls = &calls;+ move || {+ calls.set(calls.get() + 1);+ release.clone()+ }+ };+ // The first check asks and records the answer (creating the folder).+ let state = check(&path, NOW, &answer(Some(release("0.1.2"))));+ assert_eq!(calls.get(), 1);+ assert_eq!(state.latest.as_deref(), Some("0.1.2"));+ assert_eq!(state.checked_at, NOW);+ assert_eq!(read_state(&path), state);+ // Within a day: the cached answer, no request.+ let again = check(&path, NOW + DAY - 1, &answer(Some(release("0.1.3"))));+ assert_eq!(calls.get(), 1);+ assert_eq!(again.latest.as_deref(), Some("0.1.2"));+ // A day later: asked again; a failure counts as the check and keeps+ // the last answer.+ let failed = check(&path, NOW + DAY, &answer(None));+ assert_eq!(calls.get(), 2);+ assert_eq!(failed.latest.as_deref(), Some("0.1.2"));+ assert_eq!(failed.checked_at, NOW + DAY);+ check(&path, NOW + DAY + 10, &answer(Some(release("0.1.3"))));+ assert_eq!(calls.get(), 2, "the failure counted as the day's check");+ // A check recorded in the future (the clock moved back) is due.+ assert!(due(&read_state(&path), NOW));+ assert!(!due(&read_state(&path), NOW + DAY + 1));+ // A damaged or oversized file is a missing one.+ std::fs::write(&path, "{").unwrap();+ assert_eq!(read_state(&path), State::default());+ std::fs::write(&path, vec![b' '; 5000]).unwrap();+ assert_eq!(read_state(&path), State::default());+ let fresh = check(&path, NOW, &answer(Some(release("0.1.3"))));+ assert_eq!(calls.get(), 3);+ assert_eq!(fresh.latest.as_deref(), Some("0.1.3"));+ }++ #[test]+ fn the_notice_names_both_versions_the_upgrade_command_and_the_page() {+ let state = State {+ checked_at: NOW,+ latest: Some("0.1.2".into()),+ url: Some("https://github.com/graphicle-ai/graphicle/releases/tag/v0.1.2".into()),+ notified_at: 0,+ };+ assert_eq!(+ notice(&state, "0.1.1", NOW, "brew upgrade graphicle").as_deref(),+ Some(+ "\nA new release of graphicle is available: 0.1.1 → 0.1.2\n\+ To upgrade, run: brew upgrade graphicle\n\+ https://github.com/graphicle-ai/graphicle/releases/tag/v0.1.2\n"+ )+ );+ // Not for the same or an older version, nor without an answer.+ assert_eq!(notice(&state, "0.1.2", NOW, "x"), None);+ assert_eq!(notice(&state, "0.1.3", NOW, "x"), None);+ assert_eq!(notice(&State::default(), "0.1.1", NOW, "x"), None);+ // At most once a day.+ let printed = |at| State {+ notified_at: at,+ ..state.clone()+ };+ assert_eq!(notice(&printed(NOW - 3600), "0.1.1", NOW, "x"), None);+ assert!(notice(&printed(NOW - DAY), "0.1.1", NOW, "x").is_some());+ assert!(+ notice(&printed(NOW + 3600), "0.1.1", NOW, "x").is_some(),+ "clock moved back"+ );+ }++ #[test]+ fn the_upgrade_command_follows_the_install_method() {+ let install = |exe: &str| {+ crate::terminal::install_method(+ Path::new(exe),+ Some(Path::new("/home/me")),+ Some(Path::new("/home/me/.cargo/bin")),+ false,+ )+ };+ assert_eq!(+ upgrade_command(&install(+ "/opt/homebrew/Cellar/graphicle/0.1.1/bin/graphicle"+ )),+ "brew upgrade graphicle"+ );+ assert_eq!(+ upgrade_command(&install("/home/linuxbrew/.linuxbrew/bin/graphicle")),+ "brew upgrade graphicle"+ );+ if cfg!(not(windows)) {+ assert_eq!(+ upgrade_command(&install("/home/me/.local/bin/graphicle")),+ "curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh"+ );+ }+ let powershell = Install {+ method: "script",+ how: String::new(),+ commands: vec![+ "irm https://github.com/graphicle-ai/graphicle/releases/latest/download/install.ps1 | iex"+ .into(),+ ],+ };+ assert_eq!(upgrade_command(&powershell), powershell.commands[0]);+ assert_eq!(+ upgrade_command(&install("/home/me/.cargo/bin/graphicle")),+ "graphicle update"+ );+ let docker = crate::terminal::install_method(+ Path::new("/usr/local/bin/graphicle"),+ None,+ None,+ true,+ );+ assert_eq!(upgrade_command(&docker), "graphicle update");+ }++ #[test]+ fn only_a_github_release_with_a_version_and_a_page_is_taken() {+ let page = "https://github.com/graphicle-ai/graphicle/releases/tag/v0.1.2";+ assert_eq!(+ Release::from_api(+ &json!({"tag_name":"v0.1.2","html_url":page,"draft":false,"prerelease":false})+ ),+ Some(release("0.1.2"))+ );+ assert_eq!(+ Release::from_api(&json!({"tag_name":"0.1.2","html_url":page})).map(|r| r.version),+ Some("0.1.2".into())+ );+ for bad in [+ json!({"tag_name":"v0.1.2"}),+ json!({"html_url":page}),+ json!({"tag_name":"latest","html_url":page}),+ json!({"tag_name":"v0.1.2\u{1b}[31m","html_url":page}),+ json!({"tag_name":"v0.1.2","html_url":"http://github.com/x"}),+ json!({"tag_name":"v0.1.2","html_url":"https://example.com/graphicle"}),+ json!({"tag_name":"v0.1.2","html_url":"https://github.com/x\u{1b}]8;;"}),+ json!({"tag_name":"v0.1.2","html_url":"https://github.com/a b"}),+ json!({"tag_name":"v0.1.2","html_url":page,"draft":true}),+ json!({"tag_name":"v0.1.2","html_url":page,"prerelease":true}),+ ] {+ assert_eq!(Release::from_api(&bad), None, "{bad}");+ }+ }++ #[test]+ fn nothing_is_checked_or_printed_unless_the_program_allows_it() {+ // A test's process never called `allow`: start and finish do nothing.+ assert!(!ALLOWED.load(AtomicOrdering::Relaxed));+ start(true, Path::new("/nonexistent/models.json"));+ assert!(PENDING.lock().unwrap().is_none());+ finish();+ }+}diff --git a/docs/benchmarks.md b/docs/benchmarks.mdindex 7aaa34b..d8078b8 100644--- a/docs/benchmarks.md+++ b/docs/benchmarks.md@@ -9,7 +9,7 @@ endorsement is implied.| Area | Status | Result ||---|---|---|-| Code-graph engine: parity | Graphify 0.9.91: run on Linux, 15 October 2026; the full run on macOS is pending. Graphify 0.9.88: done, 13 October 2026; widened 14 October 2026 | Against Graphify 0.9.91, 89 of the 96 comparison checks pass on Linux; the other 7 stop on that host, as they did against 0.9.88 (IPv4 loopback, ffmpeg and one layout tolerance). Against Graphify 0.9.88, 96 of 96 pass, with reviewed upstream fixes applied to nine of the reference's modules; widened on 14 October, they run 354 of its 402 test files against the engine: 350 pass and 4 have known differences (7 tests). The limits are [below](#parity-with-graphify) |+| Code-graph engine: parity | Graphify 0.9.91: run on Linux, 15 October 2026; the full run on macOS is pending. Graphify 0.9.88: done, 13 October 2026; widened 14 October 2026 | Against Graphify 0.9.91, 89 of the 96 comparison checks pass on Linux; the other 7 stop on that host, as they did against 0.9.88 (IPv4 loopback, a speech recording and ffmpeg, and one layout tolerance). Against Graphify 0.9.88, 96 of 96 pass, with reviewed upstream fixes applied to nine of the reference's modules; widened on 14 October, they run 354 of its 402 test files against the engine: 350 pass and 4 have known differences (7 tests). The limits are [below](#parity-with-graphify) || Code-graph engine: speed | Done, on a pre-release build that followed Graphify 0.9.77. The 0.1.0 engine: an exploratory survey, 14 October 2026; its registered quiet-host repeat is pending. Updates after commits: Graphicle 0.1.0 against Graphify 0.9.91, registered before the first update, 15 October 2026 | Django (pre-release build): code-only extract 7.5 s against 72.8 s for Graphify 0.9.77. Kubernetes v1.37.1 (the 0.1.0 engine, which follows Graphify 0.9.88; exploratory, one run each on one Linux host, the same 16 CPUs, 8 workers, with four recorded deviations): code-only extract 198.4 s against 1,597.9 s for Graphify 0.9.88, the same graph. [Details](#speed-on-kubernetes). Updates after each of 30 commits on prometheus, tokio and poetry (one Linux node, 4 CPUs per run): 6 to 8 times less time than Graphify 0.9.91, with the same differences from a fresh build in both. [Details](#updates-after-commits) || Code-graph engine: peak memory | A pre-release build with 0.1.1's changes to how the engine holds its data, against Graphify 0.9.91, 15 October 2026; five cells rechecked on a build of the merged 0.1.1 source | Less peak memory than Graphify 0.9.91 in all 39 cells (13 repositories; extract, priming update and update with no change), from 0.29 to 0.97 times Graphify's figure; Kubernetes extract 2,091.5 against 2,767 MiB. One Linux node (its 8 H100 GPUs not used), 8 workers; Graphicle's peak RSS against Graphify's peak PSS. [Details](#peak-memory-against-graphify-0991) || Coding agents: Claude Code with Graphicle, Graphify or neither | Four task sets, each test registered before any answer was scored; Claude Code with Opus 5.5, and one set repeated with Haiku 5.5 | Graphicle tied plain Claude Code on finding files and facts in every test, and no token saving is claimed against it. Against Graphify 0.9.91, Graphicle found more facts on Graphify's showcase corpus and used fewer tokens in all four task sets (on SWE-bench Verified, a secondary comparison); in two of them, Graphicle's arm included a prototype that does not ship. [Details](#coding-agents-with-graphicle-graphify-or-neither) |@@ -30,30 +30,37 @@ for reasons of that host (below); the full run on macOS, which records everymodule's receipt, is still to be made for 0.9.91. That is the parity claim,with these limits:-- **Graphify 0.9.91 (15 October 2026).** The qualified release build of the- 0.1.1 source (binary SHA-256 `adf81bb2…`) ran against the pinned archive of- Graphify 0.9.91 (`10130e79`, archive SHA-256 `f4916b0c…`, with `graphifyy`- 0.9.91 from PyPI) on Linux (x86_64). Of the 96 checks, 89 pass:- `tools/qualify_all.py` passed 88, and `check_detect` passed when run on its- own (in the full run, one upstream test could not bind a Unix socket- because the run's temporary path was longer than the system allows). The- other 7 stop on that host, as they did against 0.9.88: 5 need IPv4- loopback connections, which the host refuses (4 of them pass with their- test servers on the host's own address; in `check_native_workflows` the- reference's own client then fails to set up TLS on that host),- `check_transcribe` needs ffmpeg, which the host lacks, and in+- **Graphify 0.9.91 (15 October 2026).** A qualified build of the 0.1.1+ source (binary SHA-256 `f212d846…`) ran `tools/qualify_all.py` against the+ pinned archive of Graphify 0.9.91 (`10130e79`, archive SHA-256+ `f4916b0c…`, with `graphifyy` 0.9.91 from PyPI) on Linux (x86_64). Of the+ 96 checks, 89 pass in that full run, `check_detect` among them. The other+ 7 stop on that host, as they did against 0.9.88: 5 need IPv4 loopback+ connections, which the host refuses, `check_transcribe` needs a speech+ recording (`jfk.wav`) and ffmpeg, which the host lacks, and in`check_export` a graph layout position differs from NetworkX's by 2.2e-9,- against a tolerance of 2e-9. Of the 19 test files that 0.9.89 to 0.9.91+ against a tolerance of 2e-9. Since that run, the engine has changed only in+ one test file. Before the merge, the port branch's own build (binary+ SHA-256 `adf81bb2…`) also reached 89: `tools/qualify_all.py` passed 88,+ and `check_detect` passed when run on its own (in that full run, one+ upstream test could not bind a Unix socket because the run's temporary+ path was longer than the system allows). On that build, 4 of the 5+ loopback checks passed with their test servers on the host's own address;+ in `check_native_workflows` the reference's own client then failed to set+ up TLS on that host. Of the 19 test files that 0.9.89 to 0.9.91add and the 25 they change, the checks run all but five: two testGraphify's skill text and skill generator, one patches the reference'sown subprocess call (the engine's equivalent has a Rust test), and the twoOllama files drive mocked Python clients, so `check_llm` compares theengine's Ollama requests with the reference's instead. On- Kubernetes, prometheus and tokio, the engine's `update --force- --no-cluster` gives the same nodes and edges as Graphify 0.9.91's on the- same folder, record for record and in the same order; the files differ- only in where some edges place their `context` key, as 0.1.0's did. The- items below describe the 0.9.88 runs unless they say otherwise.+ Kubernetes, prometheus and tokio, the port branch's engine's `update+ --force --no-cluster` gave the same nodes and edges as Graphify 0.9.91's on+ the same folder, record for record and in the same order; the files differ+ only in where some edges place their `context` key, as 0.1.0's did. A+ build of the 0.1.1 source gives the same graphs as the port branch's+ engine in all 30 extracts and priming updates compared, on 13+ repositories, Kubernetes, prometheus and tokio among them. The items below+ describe the 0.9.88 runs unless they say otherwise.- **What the checks do.** Each check runs upstream tests and comparisonsagainst the Rust engine and compares the engine's results with the pinnedPython release. Together they run 354 of Graphify 0.9.88's 402 test filesdiff --git a/docs/code-signing.md b/docs/code-signing.mdnew file mode 100644index 0000000..a15189c--- /dev/null+++ b/docs/code-signing.md@@ -0,0 +1,66 @@+# Code signing policy++**Not in effect yet.** Graphicle's Windows programs are not code-signed+today. We plan to have them signed through the SignPath Foundation, which+signs open-source projects for free, and this policy applies once our+application is approved. Until then, Windows releases are unsigned+([Windows signing](install.md#windows-signing)).++Once the application is approved:++> Free code signing provided by [SignPath.io](https://about.signpath.io), certificate by [SignPath Foundation](https://signpath.org)++## What is signed++- `graphicle.exe` and `graphicle-graph.exe` in the Windows release archive,+ `graphicle-<version>-x86_64-pc-windows-msvc.zip`. The macOS and Linux+ archives are not covered.+- Only programs that the [release workflow](../.github/workflows/release.yml)+ builds from this repository's source on GitHub-hosted runners. SignPath+ checks that the archive it signs comes from that workflow's run.+- Each release is signed only after an approver approves its signing request+ in SignPath. The signed archive replaces the unsigned one before the+ release's checksums (`SHA256SUMS` and the `.sha256` files) are written.++## Team roles++- Committers and reviewers: [Graphicle-AI maintainers](https://github.com/orgs/graphicle-ai/people)+- Approvers: [VikramLex](https://github.com/VikramLex)++A maintainer reviews every change from someone outside the team, such as a+pull request, before it is merged. The approver decides whether a release is+signed. Team members must use multi-factor authentication on GitHub and on+SignPath.++## Privacy policy++Graphicle has no telemetry and no account. It contacts the network only in+these cases:++- **The update check, which is on by default.** Once a day, when you run a+ command in a terminal, `graphicle` sends one GET request to GitHub's+ releases API (`api.github.com/repos/Graphicle-AI/graphicle/releases/latest`)+ to learn the latest version, and tells you when a newer one exists. If+ GitHub has not answered by the time the command ends, the request is sent+ again with your next command. The request carries no code, project data,+ version or credentials; like any web request, it shows GitHub your IP+ address. Agents' MCP servers and hooks, CI runs, and commands whose output+ is JSON or not a terminal never check. To turn it off, set+ `GRAPHICLE_NO_UPDATE_NOTIFIER=1` or run+ `graphicle config set update_notifier false`.+- **A model, only when you configure one.** The model you set for answers,+ memory proposals or embeddings receives the text it works on.+- **A connector, only when you configure one.** It reads from the service you+ connect.+- **A full `graphicle graph extract`** (without `--code-only`) sends+ documents, papers and images to the LLM whose API key it finds in your+ environment. `--dry-run` shows what it would send.+- **The GitHub CLI**, which `graphicle graph add`, `clone` and the+ pull-request tools run.+- **`graphicle update`** with a feed you name.+- **A build from source** downloads the parser sources once.++The services that Graphicle contacts for you have their own privacy policies:+[GitHub's](https://docs.github.com/site-policy/privacy-policies/github-general-privacy-statement)+for the update check and the GitHub CLI, and those of the model provider and+the services you connect.diff --git a/docs/configuration.md b/docs/configuration.mdindex 3208443..cc54453 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -363,6 +363,14 @@ scripts. `--json` asks for JSON on a terminal, and `GRAPHICLE_OUTPUT=text` oroff. `GRAPHICLE_NO_BROWSER=1` makes `graphicle open` print the app's addressinstead of starting a browser.+When a newer release is out, a command you run in a terminal ends with a+three-line notice on standard error: the new version, the upgrade command and+the release page. Graphicle asks GitHub for the latest release once a day,+and asks again with the next command when GitHub has not answered by the time+a command ends. It prints the notice at most once a day.+`GRAPHICLE_NO_UPDATE_NOTIFIER=1` or `graphicle config set update_notifier false`+turns both off.+## Code graph| Setting | Effect |diff --git a/docs/faq.md b/docs/faq.mdindex dbc7c98..22fde64 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -41,6 +41,18 @@ finds through an API key in your environment. Run `--dry-run` first to see whatit would send. The README's [privacy section](../README.md#privacy-and-local-first)lists every case.+One of them is on by default: once a day, when you run a command in a+terminal, `graphicle` asks GitHub's releases API for its latest release.+That is one GET request to api.github.com, with no code, project data or+version in it. If GitHub has not answered by the time the command ends, the+request is made again with your next command. The answer is kept in+`~/.cache/graphicle/update-check.json`.+When a newer release exists, `graphicle` prints the new version and the+upgrade command for your install. It never checks from an agent's MCP+server or hooks, on CI, or when its output goes to a pipe or is JSON. To turn+it off, set `GRAPHICLE_NO_UPDATE_NOTIFIER=1` or run+`graphicle config set update_notifier false`.+## Is Graphicle a fork of Graphify?The code-graph engine is a Rust port of Graphify, which isdiff --git a/docs/install.md b/docs/install.mdindex d063828..8445504 100644--- a/docs/install.md+++ b/docs/install.md@@ -93,6 +93,14 @@ Notes for the preview:- The optional features under [Build from source](#build-from-source) areuntested on Windows.+### Windows signing++The Windows programs are not code-signed yet, so Windows may warn before it+runs them (see **SmartScreen or Smart App Control** below). We plan to have+them signed through the SignPath Foundation, which signs open-source projects+for free; the [Code signing policy](code-signing.md) says what will be signed+and who approves each signed release.+### Troubleshooting on Windows- **SmartScreen or Smart App Control.** The preview programs are not@@ -257,6 +265,18 @@ or `graphicle graph hook install` again. `graphicle update` says how toupgrade for the way you installed Graphicle. On Windows, run the PowerShellinstall line from [Windows (preview)](#windows-preview) again.+Upgrading from 0.1.0: run `graphicle setup` again in each repository. It+switches Claude Code to 0.1.1's lighter defaults: five tools and no guard+hooks. To keep 0.1.0's setup, with every tool and the guard hooks, run+`graphicle setup --tools all --guards` instead; the+[CHANGELOG](../CHANGELOG.md) lists the two small differences that remain.++You do not have to watch for releases: once a day, when you run a command in+a terminal, `graphicle` asks GitHub for the latest release. When it is+newer, `graphicle` prints the version and the upgrade command for your install.+`GRAPHICLE_NO_UPDATE_NOTIFIER=1` or `graphicle config set update_notifier false`+turns this off.+## Uninstall1. Remove what Graphicle added to your agents and repositories:diff --git a/docs/quickstart.md b/docs/quickstart.mdindex 5e23a82..10fe821 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -2,7 +2,7 @@This page takes you from nothing to your first answer in three steps. You needmacOS or Linux and a code repository on your machine. Nothing here needs an-account, and setup sends nothing over the network.+account, and setup sends none of your code or data over the network.## 1. Install