hanna/fabrica

feat(git): resolve .gitattributes from tree blobs

b5815a0 · hanna committed on 2026-07-25

Add an own attribute resolver (§3.5): for a tree, collect every
.gitattributes blob with its directory prefix, parse each into ordered
rules, and match paths with globset. Precedence follows git — a deeper
directory wins over a shallower one and a later line wins within a file —
implemented by applying files shallowest-first into a map. `!key`
unspecifies (clearing a less-specific value), distinct from `-key`.

libgit2's own lookup is working-tree oriented and unreliable against a
bare repo, hence resolving from the object database directly. The moka
cache (AttributesCache) is a standalone type the web layer holds rather
than a field on the per-operation Repo handle.

Typed accessors surface the attributes fabrica consults: the highlight
language override, binary/-text, -diff, linguist/fabrica-generated, and
linguist-vendored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

Cargo.lock +264 −12

Cargo.toml +9 −0

crates/git/Cargo.toml +2 −0

crates/git/src/attributes.rs +512 −0

crates/git/src/lib.rs +2 −0

crates/git/src/repo.rs +7 −1

crates/highlight/Cargo.toml +4 −0

crates/highlight/src/classes.rs +88 −0

crates/highlight/src/lang.rs +313 −0

crates/highlight/src/lib.rs +282 −0

flake.nix +4 −0

 rand_core = { version = "0.6", features = ["getrandom"] }
 # Interactive, non-echoing password entry for the CLI.
 rpassword = "7"
+# Glob matching for the `.gitattributes` resolver (gitignore-style patterns).
+globset = "0.4"
+# Bounded, concurrent caches (attribute rule sets, highlight output, signatures).
+moka = { version = "0.12", features = ["sync"] }
+# Syntax highlighting over tree-sitter, with bundled grammars. Default features
+# carry all grammars plus the constants table we map onto our `hl-*` classes.
+inkjet = "0.11.1"
+# Snapshot testing.
+insta = "1"
 [workspace.lints.rust]
 unsafe_code = "forbid"

 [dependencies]
 model = { workspace = true }
 git2 = { workspace = true }
+globset = { workspace = true }
+moka = { workspace = true }
 thiserror = { workspace = true }
 # Pin the libgit2 bindings to a build that requires libgit2 <= the version
 # nixpkgs ships (1.9.4). git2 0.20's default libgit2-sys (0.18.7, bundling 1.9.6)

 //! name, so renames and group moves are metadata-only. The database is the sole
 //! name→path authority; [`repo_path`] is the one place that mapping is computed.
+mod attributes;
 mod repo;
 mod types;
 use git2::{Repository, RepositoryInitOptions};
+pub use crate::attributes::{AttrValue, Attributes, AttributesCache, AttributesSet};
 pub use crate::repo::Repo;
 pub use crate::types::{
     Blob, BranchInfo, CommitDetail, CommitSummary, DeltaStatus, DiffLine, DiffOpts, EntryKind,

+        }
+    }
+    /// The underlying libgit2 handle, for sibling modules in this crate (e.g. the
+    /// attributes resolver). Never exposed outside the crate.
+    pub(crate) fn raw(&self) -> &Repository {
+        &self.inner
+    }
     /// Look up a commit by our [`Oid`], mapping a miss to [`GitError::RevNotFound`].
-    fn commit_at(&self, oid: &Oid) -> Result<Commit<'_>, GitError> {
+    pub(crate) fn commit_at(&self, oid: &Oid) -> Result<Commit<'_>, GitError> {
         let parsed = git2::Oid::from_str(oid.as_str())
             .map_err(|_| GitError::RevNotFound(oid.to_string()))?;
         self.inner

 publish.workspace = true
 [dependencies]
+inkjet = { workspace = true }
+[dev-dependencies]
+insta = { workspace = true }
 [lints]
 workspace = true

 version = 4
 [[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom 0.3.4",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+[[package]]
 name = "allocator-api2"
 version = "0.2.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
  "serde",
  "serde_json",
  "sha2 0.10.9",
- "thiserror",
+ "thiserror 2.0.19",
+]
 [[package]]
+]
 [[package]]
+name = "bstr"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f7dc094d718f2e1c1559ad110e27eeaae14a5465d3d56dd6dbd793079fbd530"
+dependencies = [
+ "memchr",
+ "serde_core",
+]
+[[package]]
 name = "bumpalo"
 version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "figment",
  "serde",
- "thiserror",
+ "thiserror 2.0.19",
  "toml",
  "url",
+]
 [[package]]
+name = "console"
+version = "0.16.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fe5f465a4f6fee88fad41b85d990f84c835335e85b5d9e6e63e0d06d28cba7c"
+dependencies = [
+ "encode_unicode",
+ "libc",
+ "windows-sys 0.61.2",
+]
+[[package]]
 name = "cpufeatures"
 version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "217698eaf96b4a3f0bc4f3662aaa55bdf913cd54d7204591faa790070c6d0853"
 [[package]]
+name = "crossbeam-channel"
+version = "0.5.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d85363c37faeca707aef026efa9f3b34d077bce547e48f770770625c6013679e"
+dependencies = [
+ "crossbeam-utils",
+]
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
+dependencies = [
+ "crossbeam-utils",
+]
+[[package]]
 name = "crossbeam-queue"
 version = "0.3.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "encode_unicode"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
+[[package]]
 name = "equivalent"
 version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 version = "0.1.0"
 dependencies = [
  "git2",
+ "globset",
  "libgit2-sys",
  "model",
+ "moka",
  "tempfile",
- "thiserror",
+ "thiserror 2.0.19",
+]
 [[package]]
+]
 [[package]]
+name = "globset"
+version = "0.4.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e47d37d2ae4464254884b60ab7071be2b876a9c35b696bd018ddcc76847309cd"
+dependencies = [
+ "aho-corasick",
+ "bstr",
+ "log",
+ "regex-automata",
+ "regex-syntax",
+]
+[[package]]
 name = "hashbrown"
 version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 [[package]]
 name = "highlight"
 version = "0.1.0"
+dependencies = [
+ "inkjet",
+ "insta",
+]
 [[package]]
 name = "hkdf"
+]
 [[package]]
+name = "inkjet"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56b828db0cd62bd220b32745e71f5cf8818af2e20d8cb499a7e221dd91cb323a"
+dependencies = [
+ "ahash",
+ "anyhow",
+ "cc",
+ "serde",
+ "thiserror 1.0.69",
+ "toml",
+ "tree-sitter",
+ "tree-sitter-highlight",
+ "v_htmlescape",
+]
+[[package]]
 name = "inlinable_string"
 version = "0.1.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8fae54786f62fb2918dcfae3d568594e50eb9b5c25bf04371af6fe7516452fb"
 [[package]]
+name = "insta"
+version = "1.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "86f0f8fee8c926415c58d6ae43a08523a26faccb2323f5e6b644fe7dd4ef6b82"
+dependencies = [
+ "console",
+ "once_cell",
+ "similar",
+ "tempfile",
+]
+[[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+[[package]]
 name = "libc"
 version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 name = "model"
 version = "0.1.0"
 dependencies = [
- "thiserror",
+ "thiserror 2.0.19",
+]
+[[package]]
+name = "moka"
+version = "0.12.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "957228ad12042ee839f93c8f257b62b4c0ab5eaae1d4fa60de53b27c9d7c5046"
+dependencies = [
+ "crossbeam-channel",
+ "crossbeam-epoch",
+ "crossbeam-utils",
+ "equivalent",
+ "parking_lot",
+ "portable-atomic",
+ "smallvec",
+ "tagptr",
+ "uuid",
+]
 [[package]]
 checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
 [[package]]
+name = "portable-atomic"
+version = "1.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
+[[package]]
 name = "potential_utf"
 version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+[[package]]
+name = "regex-automata"
+version = "0.4.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+[[package]]
 name = "rpassword"
 version = "7.5.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 [[package]]
+name = "similar"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbbb5d9659141646ae647b42fe094daf6c6192d1620870b449d9557f748b2daa"
+[[package]]
 name = "slab"
 version = "0.4.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
  "serde_json",
  "sha2 0.10.9",
  "smallvec",
- "thiserror",
+ "thiserror 2.0.19",
  "tokio",
  "tokio-stream",
  "tracing",
  "sqlx-postgres",
  "sqlx-sqlite",
  "syn 2.0.119",
- "thiserror",
+ "thiserror 2.0.19",
  "tokio",
  "url",
+]
  "sha1",
  "sha2 0.11.0",
  "sqlx-core",
- "thiserror",
+ "thiserror 2.0.19",
  "tracing",
+]
  "smallvec",
  "sqlx-core",
  "stringprep",
- "thiserror",
+ "thiserror 2.0.19",
  "tracing",
  "whoami",
+]
  "percent-encoding",
  "serde",
  "sqlx-core",
- "thiserror",
+ "thiserror 2.0.19",
  "tracing",
  "url",
+]
  "model",
  "sqlx",
  "tempfile",
- "thiserror",
+ "thiserror 2.0.19",
  "tokio",
  "ulid",
+]
+]
 [[package]]
+name = "tagptr"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b2093cf4c8eb1e67749a6762251bc9cd836b6fc171623bd0a9d324d37af2417"
+[[package]]
 name = "tempfile"
 version = "3.27.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.3.4",
+ "getrandom 0.4.3",
  "once_cell",
  "rustix",
  "windows-sys 0.61.2",
 [[package]]
 name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl 1.0.69",
+]
+[[package]]
+name = "thiserror"
 version = "2.0.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
 dependencies = [
- "thiserror-impl",
+ "thiserror-impl 2.0.19",
+]
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
 [[package]]
+]
 [[package]]
+name = "tree-sitter"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0203df02a3b6dd63575cc1d6e609edc2181c9a11867a271b25cfd2abff3ec5ca"
+dependencies = [
+ "cc",
+ "regex",
+ "regex-syntax",
+ "tree-sitter-language",
+]
+[[package]]
+name = "tree-sitter-highlight"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "380a7706376fa6c52ba7bf71d1e7a93856ee8ab08a7680631dfa664fdd237d66"
+dependencies = [
+ "lazy_static",
+ "regex",
+ "thiserror 1.0.69",
+ "tree-sitter",
+]
+[[package]]
+name = "tree-sitter-language"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "009994f150cc0cd50ff54917d5bc8bffe8cad10ca10d81c34da2ec421ae61782"
+[[package]]
 name = "typenum"
 version = "1.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 [[package]]
+name = "uuid"
+version = "1.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
+dependencies = [
+ "getrandom 0.4.3",
+ "js-sys",
+ "wasm-bindgen",
+]
+[[package]]
+name = "v_htmlescape"
+version = "0.15.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e8257fbc510f0a46eb602c10215901938b5c2a7d5e70fc11483b1d3c9b5b18c"
+[[package]]
 name = "vcpkg"
 version = "0.2.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! A `.gitattributes` resolver over tree blobs.
+//!
+//! libgit2's attribute lookup is oriented at a working tree; against a bare
+//! repository, and for per-ref accuracy, it is unreliable. This module resolves
+//! attributes directly from the object database instead: for a given tree it
+//! collects every `.gitattributes` blob with its directory prefix, parses each
+//! into ordered rules, and answers "what attributes apply to this path?" with git's
+//! precedence — deeper directories win over shallower, and within one file a later
+//! line wins over an earlier one.
+//!
+//! Pattern matching follows gitattributes/gitignore semantics: a pattern with no
+//! slash matches the basename at any depth below its file; a pattern containing a
+//! slash is anchored to its file's directory; `**` spans directories; `!key`,
+//! `-key`, `key`, and `key=value` are the four assignment forms.
+//!
+//! Consumers (later phases): the highlight language override
+//! (`fabrica-language` / `linguist-language`), the "binary, not shown" decision
+//! (`binary` / `-text`), collapsing generated diffs (`linguist-generated` /
+//! `fabrica-generated`), and excluding vendored paths from search
+//! (`linguist-vendored`).
+use std::collections::HashMap;
+use std::sync::Arc;
+use globset::{GlobBuilder, GlobMatcher};
+use crate::GitError;
+use crate::repo::Repo;
+use crate::types::Oid;
+/// The value an attribute is assigned by a matching rule.
+///
+/// Mirrors git's four forms. Resolution keeps the last (deepest, latest) value
+/// per attribute name; [`AttrValue::Unspecified`] deliberately clears a value set
+/// by a shallower rule.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AttrValue {
+    /// `attr` — set to the implicit boolean true.
+    Set,
+    /// `-attr` — explicitly unset (boolean false).
+    Unset,
+    /// `!attr` — unspecified; removes any value a less specific rule assigned.
+    Unspecified,
+    /// `attr=value` — set to a string value.
+    Value(String),
+}
+/// The attributes resolved for one concrete path.
+///
+/// A thin wrapper over the final name→value map, with typed accessors for the
+/// attributes fabrica actually consults.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Attributes {
+    map: HashMap<String, AttrValue>,
+}
+impl Attributes {
+    /// The raw value assigned to `name`, if any rule set one.
+    #[must_use]
+    pub fn get(&self, name: &str) -> Option<&AttrValue> {
+        self.map.get(name)
+    }
+    /// Whether `name` resolves to a truthy state ([`AttrValue::Set`] or a
+    /// non-`false` [`AttrValue::Value`]).
+    #[must_use]
+    pub fn is_set(&self, name: &str) -> bool {
+        match self.map.get(name) {
+            Some(AttrValue::Set) => true,
+            Some(AttrValue::Value(v)) => v != "false",
+            _ => false,
+        }
+    }
+    /// Whether `name` was explicitly unset (`-name`).
+    #[must_use]
+    pub fn is_unset(&self, name: &str) -> bool {
+        matches!(self.map.get(name), Some(AttrValue::Unset))
+    }
+    /// The highlighting language override, honouring fabrica's own attribute over
+    /// GitHub's `linguist-language` (§8.1 precedence).
+    #[must_use]
+    pub fn language(&self) -> Option<&str> {
+        for key in ["fabrica-language", "linguist-language"] {
+            if let Some(AttrValue::Value(v)) = self.map.get(key) {
+                return Some(v.as_str());
+            }
+        }
+        None
+    }
+    /// Whether the path should be treated as binary (rendered as "binary file, not
+    /// shown"): `binary` set, or text explicitly disabled with `-text`.
+    #[must_use]
+    pub fn is_binary(&self) -> bool {
+        self.is_set("binary") || self.is_unset("text")
+    }
+    /// Whether diff rendering is suppressed for this path: `-diff`, or `binary`
+    /// (git's `binary` macro implies `-diff`).
+    #[must_use]
+    pub fn no_diff(&self) -> bool {
+        self.is_unset("diff") || self.is_set("binary")
+    }
+    /// Whether the path is machine-generated and should collapse by default.
+    #[must_use]
+    pub fn is_generated(&self) -> bool {
+        self.is_set("linguist-generated") || self.is_set("fabrica-generated")
+    }
+    /// Whether the path is vendored and should be excluded from search.
+    #[must_use]
+    pub fn is_vendored(&self) -> bool {
+        self.is_set("linguist-vendored")
+    }
+}
+/// One `.gitattributes` file: its directory prefix (`""` at the tree root) and its
+/// parsed rules in file order.
+#[derive(Debug)]
+struct AttrFile {
+    /// Directory the file lives in, without a trailing slash (`""` at the root).
+    dir: String,
+    /// The file's rules, in the order they appear.
+    rules: Vec<Rule>,
+}
+/// One parsed line of a `.gitattributes` file.
+#[derive(Debug)]
+struct Rule {
+    /// The compiled pattern.
+    matcher: GlobMatcher,
+    /// Whether the pattern floats (no slash → match the basename at any depth)
+    /// rather than being anchored to the file's directory.
+    floating: bool,
+    /// The attribute assignments this line makes, in order.
+    assigns: Vec<(String, AttrValue)>,
+}
+/// The resolved rule set for a whole tree: every `.gitattributes` file it
+/// contains, ordered shallowest-first so application order yields git's
+/// "deeper wins" precedence.
+#[derive(Debug, Default)]
+pub struct AttributesSet {
+    files: Vec<AttrFile>,
+}
+impl AttributesSet {
+    /// Resolve the attributes that apply to `path` (a repo-relative, `/`-separated
+    /// path with no leading slash).
+    #[must_use]
+    pub fn attributes(&self, path: &str) -> Attributes {
+        let path = path.trim_start_matches('/');
+        let mut map: HashMap<String, AttrValue> = HashMap::new();
+        // `files` is shallowest-first; applying in that order lets deeper files
+        // (and later lines within a file) overwrite, which is exactly git's rule.
+        for file in &self.files {
+            let Some(rel) = relative_to(path, &file.dir) else {
+                continue;
+            };
+            let rel_base = rel.rsplit('/').next().unwrap_or(rel);
+            for rule in &file.rules {
+                let hit = if rule.floating {
+                    rule.matcher.is_match(rel_base)
+                } else {
+                    rule.matcher.is_match(rel)
+                };
+                if hit {
+                    for (name, value) in &rule.assigns {
+                        match value {
+                            AttrValue::Unspecified => {
+                                map.remove(name);
+                            }
+                            other => {
+                                map.insert(name.clone(), other.clone());
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        Attributes { map }
+    }
+}
+/// Return `path` relative to directory `dir`, or `None` if `path` is not under
+/// `dir`. `dir` is `""` for the tree root (everything is under it).
+fn relative_to<'a>(path: &'a str, dir: &str) -> Option<&'a str> {
+    if dir.is_empty() {
+        return Some(path);
+    }
+    path.strip_prefix(dir)?.strip_prefix('/')
+}
+/// Parse the text of one `.gitattributes` file at directory `dir` into rules.
+/// Unparseable patterns are skipped (logged by the caller's fall-through), never
+/// fatal.
+fn parse_attr_file(dir: &str, text: &str) -> AttrFile {
+    let mut rules = Vec::new();
+    for raw in text.lines() {
+        let line = raw.trim();
+        if line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+        let mut fields = line.split_whitespace();
+        let Some(pattern) = fields.next() else {
+            continue;
+        };
+        let assigns: Vec<(String, AttrValue)> = fields.map(parse_assignment).collect();
+        if assigns.is_empty() {
+            continue;
+        }
+        if let Some((matcher, floating)) = compile_pattern(pattern) {
+            rules.push(Rule {
+                matcher,
+                floating,
+                assigns,
+            });
+        }
+    }
+    AttrFile {
+        dir: dir.to_string(),
+        rules,
+    }
+}
+/// Parse one whitespace-delimited attribute token into a name and value.
+fn parse_assignment(token: &str) -> (String, AttrValue) {
+    if let Some(name) = token.strip_prefix('!') {
+        (name.to_string(), AttrValue::Unspecified)
+    } else if let Some(name) = token.strip_prefix('-') {
+        (name.to_string(), AttrValue::Unset)
+    } else if let Some((name, value)) = token.split_once('=') {
+        (name.to_string(), AttrValue::Value(value.to_string()))
+    } else {
+        (token.to_string(), AttrValue::Set)
+    }
+}
+/// Compile a gitattributes pattern into a matcher plus whether it floats. Returns
+/// `None` for a pattern globset cannot compile.
+///
+/// Semantics: a pattern with no `/` (a trailing one aside) floats and is matched
+/// against the basename; a pattern with a slash is anchored to the file's
+/// directory. `literal_separator(true)` makes `*` stop at `/` while `**` spans
+/// directories, matching git.
+fn compile_pattern(pattern: &str) -> Option<(GlobMatcher, bool)> {
+    let trimmed = pattern.trim_end_matches('/');
+    let floating = !trimmed.contains('/');
+    let glob_src = trimmed.strip_prefix('/').unwrap_or(trimmed);
+    let glob = GlobBuilder::new(glob_src)
+        .literal_separator(!floating)
+        .build()
+        .ok()?;
+    Some((glob.compile_matcher(), floating))
+}
+impl Repo {
+    /// Collect and parse every `.gitattributes` file reachable in the tree of
+    /// commit `oid`, yielding a queryable [`AttributesSet`].
+    ///
+    /// # Errors
+    ///
+    /// Returns [`GitError::RevNotFound`] if `oid` is not a commit, or
+    /// [`GitError::Libgit2`] on a walk failure.
+    pub fn attributes_set(&self, oid: &Oid) -> Result<AttributesSet, GitError> {
+        let commit = self.commit_at(oid)?;
+        let tree = commit.tree()?;
+        // Collect (dir, blob_oid) for every `.gitattributes`, then read the blobs.
+        let mut found: Vec<(String, git2::Oid)> = Vec::new();
+        tree.walk(git2::TreeWalkMode::PreOrder, |root, entry| {
+            if entry.name() == Some(".gitattributes")
+                && entry.filemode() != i32::from(git2::FileMode::Tree)
+            {
+                // `root` is the directory prefix, e.g. "" or "src/".
+                found.push((root.trim_end_matches('/').to_string(), entry.id()));
+            }
+            git2::TreeWalkResult::Ok
+        })?;
+        let mut files: Vec<AttrFile> = Vec::with_capacity(found.len());
+        for (dir, blob_oid) in found {
+            let blob = self.raw().find_blob(blob_oid)?;
+            let text = String::from_utf8_lossy(blob.content());
+            files.push(parse_attr_file(&dir, &text));
+        }
+        // Shallowest directory first so that applying rules in order lets deeper
+        // files override.
+        files.sort_by(|a, b| {
+            depth(&a.dir)
+                .cmp(&depth(&b.dir))
+                .then_with(|| a.dir.cmp(&b.dir))
+        });
+        Ok(AttributesSet { files })
+    }
+}
+/// The nesting depth of a directory prefix (`""` → 0, `"src"` → 1, `"a/b"` → 2).
+fn depth(dir: &str) -> usize {
+    if dir.is_empty() {
+    } else {
+        dir.split('/').count()
+    }
+}
+/// A bounded cache of resolved [`AttributesSet`]s keyed by tree/commit oid.
+///
+/// [`Repo`] is opened per operation, so the cache lives here — shared across
+/// requests by the web layer — rather than on the repository handle. Resolving a
+/// tree's attributes parses every `.gitattributes` blob it contains, which is
+/// wasteful to repeat per blob view within one commit.
+#[derive(Clone)]
+pub struct AttributesCache {
+    inner: moka::sync::Cache<String, Arc<AttributesSet>>,
+}
+impl AttributesCache {
+    /// A cache holding up to `capacity` resolved sets.
+    #[must_use]
+    pub fn new(capacity: u64) -> Self {
+        Self {
+            inner: moka::sync::Cache::new(capacity),
+        }
+    }
+    /// Fetch the resolved set for `oid` in `repo`, resolving and caching on a miss.
+    ///
+    /// # Errors
+    ///
+    /// Propagates any [`GitError`] from resolution on a cache miss.
+    pub fn get(&self, repo: &Repo, oid: &Oid) -> Result<Arc<AttributesSet>, GitError> {
+        if let Some(hit) = self.inner.get(oid.as_str()) {
+            return Ok(hit);
+        }
+        let set = Arc::new(repo.attributes_set(oid)?);
+        self.inner.insert(oid.to_string(), Arc::clone(&set));
+        Ok(set)
+    }
+}
+impl Default for AttributesCache {
+    fn default() -> Self {
+        Self::new(256)
+    }
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used)]
+    use super::*;
+    /// Build an [`AttributesSet`] from `(dir, text)` pairs, mimicking what a tree
+    /// walk would collect, so the resolution logic can be tested without a repo.
+    fn set_from(files: &[(&str, &str)]) -> AttributesSet {
+        let mut parsed: Vec<AttrFile> = files
+            .iter()
+            .map(|(dir, text)| parse_attr_file(dir, text))
+            .collect();
+        parsed.sort_by(|a, b| {
+            depth(&a.dir)
+                .cmp(&depth(&b.dir))
+                .then_with(|| a.dir.cmp(&b.dir))
+        });
+        AttributesSet { files: parsed }
+    }
+    #[test]
+    fn floating_pattern_matches_basename_at_any_depth() {
+        let set = set_from(&[("", "*.rs linguist-language=Rust\n")]);
+        assert_eq!(set.attributes("src/deep/main.rs").language(), Some("Rust"));
+        assert_eq!(set.attributes("main.rs").language(), Some("Rust"));
+        assert_eq!(set.attributes("main.py").language(), None);
+    }
+    #[test]
+    fn anchored_pattern_only_matches_its_directory_level() {
+        // A leading slash anchors to the file's directory; `*` does not cross `/`.
+        let set = set_from(&[("", "/*.rs linguist-language=Rust\n")]);
+        assert_eq!(set.attributes("main.rs").language(), Some("Rust"));
+        assert_eq!(set.attributes("src/main.rs").language(), None);
+    }
+    #[test]
+    fn double_star_spans_directories() {
+        let set = set_from(&[("", "src/**/*.rs linguist-language=Rust\n")]);
+        assert_eq!(set.attributes("src/a/b/x.rs").language(), Some("Rust"));
+        assert_eq!(set.attributes("other/x.rs").language(), None);
+    }
+    #[test]
+    fn deeper_file_wins_over_shallower() {
+        // Root marks everything generated; a nested file un-marks its subtree.
+        let set = set_from(&[
+            ("", "* linguist-generated\n"),
+            ("src", "* -linguist-generated\n"),
+        ]);
+        assert!(set.attributes("README.md").is_generated());
+        assert!(!set.attributes("src/main.rs").is_generated());
+    }
+    #[test]
+    fn later_line_wins_within_a_file() {
+        let set = set_from(&[(
+            "",
+            "*.rs linguist-language=Rust\nmain.rs linguist-language=Ruby\n",
+        )]);
+        assert_eq!(set.attributes("main.rs").language(), Some("Ruby"));
+        assert_eq!(set.attributes("lib.rs").language(), Some("Rust"));
+    }
+    #[test]
+    fn negation_clears_a_value_from_a_less_specific_rule() {
+        // `!key` unspecifies, distinct from `-key` which sets false.
+        let set = set_from(&[("", "* linguist-language=Text\n*.rs !linguist-language\n")]);
+        assert_eq!(set.attributes("notes.md").language(), Some("Text"));
+        assert_eq!(set.attributes("main.rs").language(), None);
+    }
+    #[test]
+    fn binary_and_minus_text_are_binary() {
+        let set = set_from(&[("", "*.bin binary\n*.dat -text\n")]);
+        assert!(set.attributes("x.bin").is_binary());
+        assert!(set.attributes("x.dat").is_binary());
+        assert!(!set.attributes("x.txt").is_binary());
+    }
+    #[test]
+    fn minus_diff_suppresses_diff_rendering() {
+        let set = set_from(&[("", "*.lock -diff\n")]);
+        assert!(set.attributes("Cargo.lock").no_diff());
+        assert!(!set.attributes("src/main.rs").no_diff());
+        // `binary` also implies no diff.
+        let bin = set_from(&[("", "*.png binary\n")]);
+        assert!(bin.attributes("logo.png").no_diff());
+    }
+    #[test]
+    fn comments_and_blanks_are_ignored() {
+        let set = set_from(&[("", "# a comment\n\n*.rs linguist-language=Rust\n")]);
+        assert_eq!(set.attributes("main.rs").language(), Some("Rust"));
+    }
+    #[test]
+    fn fabrica_language_beats_linguist_language() {
+        let set = set_from(&[(
+            "",
+            "*.rs linguist-language=Rust\n*.rs fabrica-language=RustCustom\n",
+        )]);
+        assert_eq!(set.attributes("main.rs").language(), Some("RustCustom"));
+    }
+    #[test]
+    fn attributes_set_reads_gitattributes_from_a_real_tree() {
+        use std::path::Path;
+        use git2::{Repository, Signature, Time};
+        use crate::{create_bare, repo_path};
+        let dir = tempfile::tempdir().unwrap();
+        let id = "01hzxk9m2n8p7q6r5s4t3v2w1x";
+        create_bare(dir.path(), id, "main", Path::new("/usr/bin/fabrica")).unwrap();
+        let path = repo_path(dir.path(), id).unwrap();
+        let raw = Repository::open_bare(&path).unwrap();
+        // Root `.gitattributes` marks vendored; a nested one overrides in `src`.
+        let root_attr = raw
+            .blob(b"vendor/** linguist-vendored\n*.rs linguist-language=Rust\n")
+            .unwrap();
+        let src_attr = raw.blob(b"*.rs -linguist-vendored\n").unwrap();
+        let code = raw.blob(b"fn main() {}\n").unwrap();
+        let mut src = raw.treebuilder(None).unwrap();
+        src.insert(".gitattributes", src_attr, 0o100_644).unwrap();
+        src.insert("main.rs", code, 0o100_644).unwrap();
+        let src_tree = src.write().unwrap();
+        let mut vendor = raw.treebuilder(None).unwrap();
+        vendor.insert("lib.rs", code, 0o100_644).unwrap();
+        let vendor_tree = vendor.write().unwrap();
+        let mut root = raw.treebuilder(None).unwrap();
+        root.insert(".gitattributes", root_attr, 0o100_644).unwrap();
+        root.insert("src", src_tree, 0o040_000).unwrap();
+        root.insert("vendor", vendor_tree, 0o040_000).unwrap();
+        let root_tree = raw.find_tree(root.write().unwrap()).unwrap();
+        let sig = Signature::new("Ada", "ada@example.com", &Time::new(1, 0)).unwrap();
+        let commit = raw
+            .commit(Some("refs/heads/main"), &sig, &sig, "init", &root_tree, &[])
+            .unwrap();
+        let repo = Repo::open_path(&path).unwrap();
+        let set = repo.attributes_set(&Oid::new(commit.to_string())).unwrap();
+        // `vendor/lib.rs` is vendored; `src/main.rs` is un-vendored by the nested
+        // file but still resolves its language from the root rule.
+        assert!(set.attributes("vendor/lib.rs").is_vendored());
+        assert!(!set.attributes("src/main.rs").is_vendored());
+        assert_eq!(set.attributes("src/main.rs").language(), Some("Rust"));
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! The one table mapping tree-sitter capture names onto fabrica's stable, themeable
+//! CSS class names.
+//!
+//! Themes style code by these class names alone and never need to know tree-sitter
+//! internals; the full list is documented in `docs/theming.md`. Capture names are
+//! hierarchical and dotted (`keyword.control.return`, `constant.numeric.integer`);
+//! we map on the first component, with `constant.numeric*` special-cased to the
+//! number class. Captures with no mapping render unhighlighted (no wrapping span).
+/// The complete set of highlight classes a theme may style. Kept in sync with the
+/// `--fb-hl-*` token family in `docs/theming.md`.
+pub const HL_CLASSES: &[&str] = &[
+    "hl-keyword",
+    "hl-function",
+    "hl-type",
+    "hl-string",
+    "hl-number",
+    "hl-comment",
+    "hl-constant",
+    "hl-variable",
+    "hl-operator",
+    "hl-punctuation",
+    "hl-attribute",
+    "hl-tag",
+];
+/// Map a tree-sitter capture name to a fabrica highlight class, or `None` when the
+/// capture has no styling (it renders as plain text within its line).
+#[must_use]
+pub fn class_for(capture: &str) -> Option<&'static str> {
+    // `constant.numeric.*` is a constant in the grammar but a number to us.
+    if capture.starts_with("constant.numeric") {
+        return Some("hl-number");
+    }
+    let head = capture.split('.').next().unwrap_or(capture);
+    Some(match head {
+        "keyword" | "label" => "hl-keyword",
+        "function" | "method" => "hl-function",
+        "type" | "constructor" | "namespace" => "hl-type",
+        "string" | "escape" | "char" | "regex" => "hl-string",
+        "number" | "float" | "boolean" => "hl-number",
+        "comment" => "hl-comment",
+        "constant" => "hl-constant",
+        "variable" | "property" | "parameter" | "field" => "hl-variable",
+        "operator" => "hl-operator",
+        "punctuation" => "hl-punctuation",
+        "attribute" | "annotation" | "decorator" => "hl-attribute",
+        "tag" => "hl-tag",
+        _ => return None,
+    })
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn maps_common_captures() {
+        assert_eq!(class_for("keyword"), Some("hl-keyword"));
+        assert_eq!(class_for("keyword.control.return"), Some("hl-keyword"));
+        assert_eq!(class_for("function.macro"), Some("hl-function"));
+        assert_eq!(class_for("type.builtin"), Some("hl-type"));
+        assert_eq!(class_for("string"), Some("hl-string"));
+        assert_eq!(class_for("constant.numeric.integer"), Some("hl-number"));
+        assert_eq!(class_for("constant.builtin"), Some("hl-constant"));
+        assert_eq!(class_for("punctuation.delimiter"), Some("hl-punctuation"));
+        assert_eq!(class_for("variable.parameter"), Some("hl-variable"));
+    }
+    #[test]
+    fn unmapped_captures_are_none() {
+        assert_eq!(class_for("markup.heading"), None);
+        assert_eq!(class_for("diff.plus"), None);
+        assert_eq!(class_for("something.unknown"), None);
+    }
+    #[test]
+    fn every_class_is_documented_in_the_list() {
+        for capture in ["keyword", "function", "type", "string", "comment"] {
+            let class = class_for(capture).unwrap();
+            assert!(HL_CLASSES.contains(&class), "{class} missing from HL_CLASSES");
+        }
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! Language resolution (§8.1).
+//!
+//! Precedence, highest first: an explicit `.gitattributes` override
+//! (`fabrica-language` / `linguist-language`, resolved by the git layer and passed
+//! in), a shebang, a vim/emacs modeline, an exact filename, the longest matching
+//! extension, then plain text. Name matching is case-insensitive and defers to
+//! `inkjet`'s own token table (which already knows `rs`/`rust`, `py`/`python`, …),
+//! with a small alias table on top for names it lacks. An unknown name simply
+//! falls through rather than erroring.
+use std::path::Path;
+use inkjet::Language;
+/// A resolved language: either a concrete grammar with the token it was named by,
+/// or plain text. Opaque so callers never depend on `inkjet` directly.
+#[derive(Clone)]
+pub struct Lang {
+    language: Option<Language>,
+    name: Option<String>,
+}
+impl Lang {
+    /// The plain-text language (no highlighting).
+    #[must_use]
+    pub fn plain() -> Self {
+        Self {
+            language: None,
+            name: None,
+        }
+    }
+    /// Whether this is plain text (nothing to highlight).
+    #[must_use]
+    pub fn is_plain(&self) -> bool {
+        self.language.is_none()
+    }
+    /// The display name of the resolved language (the token it matched), if any.
+    #[must_use]
+    pub fn name(&self) -> Option<&str> {
+        self.name.as_deref()
+    }
+    /// The underlying grammar, for the highlighter.
+    pub(crate) fn language(&self) -> Option<Language> {
+        self.language
+    }
+    /// Build from a token, consulting fabrica's alias table then inkjet's.
+    fn from_token(token: &str) -> Option<Self> {
+        let token = token.trim().to_ascii_lowercase();
+        if token.is_empty() {
+            return None;
+        }
+        let canonical = ALIASES
+            .iter()
+            .find(|(alias, _)| *alias == token)
+            .map_or(token.as_str(), |(_, canonical)| *canonical);
+        Language::from_token(canonical).map(|language| Self {
+            language: Some(language),
+            name: Some(canonical.to_string()),
+        })
+    }
+}
+/// Aliases inkjet's own token table does not carry. Checked before inkjet.
+const ALIASES: &[(&str, &str)] = &[
+    ("terraform", "hcl"),
+    ("tf", "hcl"),
+    ("shell", "bash"),
+    ("sh", "bash"),
+    ("yml", "yaml"),
+    ("rs", "rust"),
+    ("md", "markdown"),
+];
+/// Exact filenames that name a language regardless of extension.
+const FILENAMES: &[(&str, &str)] = &[
+    ("dockerfile", "dockerfile"),
+    ("containerfile", "dockerfile"),
+    ("makefile", "make"),
+    ("gnumakefile", "make"),
+    ("cmakelists.txt", "cmake"),
+    ("flake.lock", "json"),
+    ("cargo.lock", "toml"),
+    ("go.mod", "gomod"),
+    ("go.sum", "gosum"),
+    ("pkgbuild", "bash"),
+    (".gitconfig", "gitconfig"),
+    (".gitattributes", "gitattributes"),
+    (".gitignore", "gitignore"),
+];
+/// Resolve the language of `path` given its `content` and any attribute override.
+///
+/// `attr_override` is the `fabrica-language`/`linguist-language` value the git
+/// attribute resolver produced (already in precedence order); an unrecognized name
+/// falls through to the content- and name-based steps rather than erroring.
+#[must_use]
+pub fn resolve(path: &Path, content: &[u8], attr_override: Option<&str>) -> Lang {
+    // 1–2. Attribute override.
+    if let Some(name) = attr_override
+        && let Some(lang) = Lang::from_token(name)
+    {
+        return lang;
+    }
+    let filename = path
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or_default();
+    // Text-derived hints (shebang, modeline) only make sense for textual content.
+    let text = std::str::from_utf8(content).ok();
+    // 4. Shebang.
+    if let Some(text) = text
+        && let Some(lang) = shebang_language(text)
+    {
+        return lang;
+    }
+    // 5. Modeline.
+    if let Some(text) = text
+        && let Some(lang) = modeline_language(text)
+    {
+        return lang;
+    }
+    // 6. Exact filename.
+    let lower = filename.to_ascii_lowercase();
+    if let Some((_, token)) = FILENAMES.iter().find(|(name, _)| *name == lower)
+        && let Some(lang) = Lang::from_token(token)
+    {
+        return lang;
+    }
+    // 7. Extension, longest compound first (`d.ts` before `ts`).
+    if let Some(lang) = extension_language(filename) {
+        return lang;
+    }
+    // 8. Plain text.
+    Lang::plain()
+}
+/// Try each dotted suffix of `filename` from longest to shortest as a language
+/// token: `archive.tar.gz` yields `tar.gz` then `gz`.
+fn extension_language(filename: &str) -> Option<Lang> {
+    let parts: Vec<&str> = filename.split('.').collect();
+    // Skip index 0 (the stem); each later index starts a candidate suffix.
+    for start in 1..parts.len() {
+        let candidate = parts[start..].join(".");
+        if let Some(lang) = Lang::from_token(&candidate) {
+            return Some(lang);
+        }
+    }
+    None
+}
+/// Extract a language from a `#!` first line, normalizing `env python3` → `python`.
+fn shebang_language(text: &str) -> Option<Lang> {
+    let first = text.lines().next()?;
+    let rest = first.strip_prefix("#!")?;
+    let mut words = rest.split_whitespace();
+    let mut interp = words.next()?;
+    // `/usr/bin/env python` → take the interpreter after `env`.
+    let base = interp.rsplit('/').next().unwrap_or(interp);
+    if base == "env" {
+        interp = words.next()?;
+    } else {
+        interp = base;
+    }
+    // Strip a trailing version suffix: `python3` → `python`, `ruby2.7` → `ruby`.
+    let name: String = interp
+        .trim_end_matches(|c: char| c.is_ascii_digit() || c == '.')
+        .to_string();
+    Lang::from_token(if name.is_empty() { interp } else { &name })
+}
+/// Extract a language from a vim (`vim: set ft=python:`) or emacs
+/// (`-*- mode: python -*-`) modeline in the first or last five lines.
+fn modeline_language(text: &str) -> Option<Lang> {
+    let lines: Vec<&str> = text.lines().collect();
+    let head = lines.iter().take(5);
+    let tail = lines.iter().rev().take(5);
+    for line in head.chain(tail) {
+        if let Some(lang) = parse_modeline(line) {
+            return Some(lang);
+        }
+    }
+    None
+}
+/// Parse one line for a vim `ft=`/`filetype=` or emacs `mode:` directive.
+fn parse_modeline(line: &str) -> Option<Lang> {
+    // vim: look for `ft=NAME` or `filetype=NAME`.
+    for key in ["filetype=", "ft="] {
+        if let Some(idx) = line.find(key) {
+            let after = &line[idx + key.len()..];
+            let value: String = after
+                .chars()
+                .take_while(|c| c.is_ascii_alphanumeric() || *c == '-' || *c == '_')
+                .collect();
+            if let Some(lang) = Lang::from_token(&value) {
+                return Some(lang);
+            }
+        }
+    }
+    // emacs: `-*- ... mode: NAME ... -*-`.
+    if line.contains("-*-")
+        && let Some(idx) = line.find("mode:")
+    {
+        let after = line[idx + "mode:".len()..].trim_start();
+        let value: String = after
+            .chars()
+            .take_while(|c| c.is_ascii_alphanumeric() || *c == '-' || *c == '_')
+            .collect();
+        if let Some(lang) = Lang::from_token(&value) {
+            return Some(lang);
+        }
+    }
+    None
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn name(path: &str, content: &str, over: Option<&str>) -> Option<String> {
+        resolve(Path::new(path), content.as_bytes(), over)
+            .name()
+            .map(str::to_string)
+    }
+    #[test]
+    fn extension_resolves_rust() {
+        assert_eq!(name("src/main.rs", "fn main() {}", None).as_deref(), Some("rust"));
+    }
+    #[test]
+    fn attribute_override_beats_extension() {
+        // A `.rs` file forced to python by an attribute.
+        assert_eq!(
+            name("weird.rs", "fn main() {}", Some("python")).as_deref(),
+            Some("python")
+        );
+    }
+    #[test]
+    fn unknown_override_falls_through_to_extension() {
+        assert_eq!(
+            name("main.rs", "fn main() {}", Some("no-such-language")).as_deref(),
+            Some("rust")
+        );
+    }
+    #[test]
+    fn shebang_resolves_and_strips_version() {
+        assert_eq!(
+            name("script", "#!/usr/bin/env python3\nprint(1)\n", None).as_deref(),
+            Some("python")
+        );
+        assert_eq!(
+            name("run", "#!/bin/bash\necho hi\n", None).as_deref(),
+            Some("bash")
+        );
+    }
+    #[test]
+    fn modeline_vim_and_emacs() {
+        assert_eq!(
+            name("notes", "# vim: set ft=ruby:\nputs 1\n", None).as_deref(),
+            Some("ruby")
+        );
+        assert_eq!(
+            name("notes", "-*- mode: python -*-\nx = 1\n", None).as_deref(),
+            Some("python")
+        );
+    }
+    #[test]
+    fn exact_filenames() {
+        assert_eq!(name("Dockerfile", "FROM x\n", None).as_deref(), Some("dockerfile"));
+        assert_eq!(name("Cargo.lock", "[[package]]\n", None).as_deref(), Some("toml"));
+        assert_eq!(name("flake.lock", "{}\n", None).as_deref(), Some("json"));
+    }
+    #[test]
+    fn compound_extension_resolves_via_a_suffix() {
+        // `types.d.ts` resolves by trying `d.ts` then `ts`; either way it is a
+        // recognized language, not plain text.
+        let lang = resolve(Path::new("types.d.ts"), b"export {}\n", None);
+        assert!(!lang.is_plain());
+    }
+    #[test]
+    fn unknown_extension_is_plain() {
+        let lang = resolve(Path::new("data.zzz"), b"noise", None);
+        assert!(lang.is_plain());
+        assert_eq!(lang.name(), None);
+    }
+    #[test]
+    fn alias_table_maps_terraform() {
+        assert_eq!(name("main.tf", "resource {}\n", None).as_deref(), Some("hcl"));
+    }
+}

 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! Syntax highlighting producing independently-valid HTML per line.
+//!
+//! Two hard requirements drive the design. First, **line-addressable output**: the
+//! blob view anchors on line numbers, so highlighting yields a `Vec<`[`Line`]`>`
+//! where each line is a `Vec<`[`Span`]`>` that a template renders into balanced
+//! markup on its own — a span that crosses a newline is split and its class
+//! reopened on the next line. Second, **per-side diff highlighting**: a diff
+//! highlights the pre- and post-image of a file as whole documents (never
+//! per-hunk, which would feed a context-dependent grammar garbage) and then zips
+//! the resulting lines with the hunks.
+//!
+//! Highlighting **must not** be able to fail a page render (§8): oversized, binary,
+//! and minified inputs skip straight to plain text, and a grammar panic is caught
+//! and degraded the same way. The output carries no colours — only the stable
+//! `hl-*` classes from [`classes`], which themes style.
+mod classes;
+mod lang;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use inkjet::Highlighter;
+use inkjet::constants::HIGHLIGHT_NAMES;
+use inkjet::tree_sitter_highlight::HighlightEvent;
+pub use crate::classes::{HL_CLASSES, class_for};
+pub use crate::lang::{Lang, resolve};
+/// Files larger than this are rendered as plain text (matches the
+/// `ui.max_highlight_bytes` default; the web layer may pre-filter with the
+/// configured value).
+pub const DEFAULT_MAX_BYTES: usize = 1_048_576;
+/// A single line longer than this marks the file minified; it is rendered plain.
+pub const MINIFIED_LINE_BYTES: usize = 5_000;
+/// Bytes sniffed from the head of the content when deciding whether it is binary.
+const BINARY_SNIFF_BYTES: usize = 8_192;
+/// One styled run of text within a line. `class` is a stable `hl-*` name or `None`
+/// for unstyled text; `text` is raw (the renderer escapes it) and never contains a
+/// newline.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Span {
+    /// The highlight class, or `None` for text with no styling.
+    pub class: Option<&'static str>,
+    /// The raw text of this run, newline-free.
+    pub text: String,
+}
+/// One rendered source line: its spans in order, without the trailing newline.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct Line {
+    /// The line's styled runs, left to right.
+    pub spans: Vec<Span>,
+}
+/// The result of highlighting a whole blob.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Highlighted {
+    /// One entry per source line.
+    pub lines: Vec<Line>,
+    /// The resolved language's display name, or `None` when rendered plain.
+    pub language: Option<String>,
+}
+/// Highlight a blob for the file at `path`, applying every guard.
+///
+/// `attr_override` is the `.gitattributes` language override the git layer
+/// resolved. Oversized, binary, minified, or unrecognized-language inputs — and any
+/// grammar failure — degrade to plain text; the call never fails.
+#[must_use]
+pub fn highlight(path: &std::path::Path, content: &[u8], attr_override: Option<&str>) -> Highlighted {
+    let lang = resolve(path, content, attr_override);
+    if lang.is_plain() || is_unhighlightable(content) {
+        return Highlighted {
+            lines: plain_lines(&String::from_utf8_lossy(content)),
+            language: None,
+        };
+    }
+    // `is_unhighlightable` already rejected non-UTF-8 (a NUL sniff), but guard the
+    // decode anyway; a lossy fallback would misalign byte offsets.
+    let Ok(source) = std::str::from_utf8(content) else {
+        return Highlighted {
+            lines: plain_lines(&String::from_utf8_lossy(content)),
+            language: None,
+        };
+    };
+    match lang.language().and_then(|inner| highlight_events(inner, source)) {
+        Some(lines) => Highlighted {
+            lines,
+            language: lang.name().map(str::to_string),
+        },
+        None => Highlighted {
+            lines: plain_lines(source),
+            language: None,
+        },
+    }
+}
+/// Highlight a whole document (one side of a diff) with an already-resolved
+/// language, for zipping with hunks. Applies the size and minified guards and falls
+/// back to plain text on anything unhighlightable.
+#[must_use]
+pub fn highlight_document(lang: &Lang, source: &str) -> Vec<Line> {
+    if lang.is_plain() || is_unhighlightable(source.as_bytes()) {
+        return plain_lines(source);
+    }
+    lang.language()
+        .and_then(|inner| highlight_events(inner, source))
+        .unwrap_or_else(|| plain_lines(source))
+}
+/// Whether `content` should skip highlighting outright: too large, binary (a NUL in
+/// the sniff window), or minified (a very long line).
+fn is_unhighlightable(content: &[u8]) -> bool {
+    if content.len() > DEFAULT_MAX_BYTES {
+        return true;
+    }
+    let window = &content[..content.len().min(BINARY_SNIFF_BYTES)];
+    if window.contains(&0) {
+        return true;
+    }
+    content.split(|b| *b == b'\n').any(|line| line.len() > MINIFIED_LINE_BYTES)
+}
+/// Run the grammar and fold its events into lines, or `None` on any grammar error
+/// or panic (the caller falls back to plain text).
+fn highlight_events(language: inkjet::Language, source: &str) -> Option<Vec<Line>> {
+    let outcome = catch_unwind(AssertUnwindSafe(|| {
+        let mut highlighter = Highlighter::new();
+        let events = highlighter.highlight_raw(language, &source).ok()?;
+        let mut lines: Vec<Line> = Vec::new();
+        let mut current: Vec<Span> = Vec::new();
+        // A stack of classes, innermost last; `None` for captures we do not style.
+        let mut stack: Vec<Option<&'static str>> = Vec::new();
+        for event in events {
+            match event.ok()? {
+                HighlightEvent::HighlightStart(highlight) => {
+                    let class = HIGHLIGHT_NAMES.get(highlight.0).copied().and_then(class_for);
+                    stack.push(class);
+                }
+                HighlightEvent::HighlightEnd => {
+                    stack.pop();
+                }
+                HighlightEvent::Source { start, end } => {
+                    let text = source.get(start..end).unwrap_or_default();
+                    let class = stack.iter().rev().flatten().next().copied();
+                    push_text(&mut lines, &mut current, text, class);
+                }
+            }
+        }
+        if !current.is_empty() {
+            lines.push(Line { spans: current });
+        }
+        Some(lines)
+    }));
+    outcome.ok().flatten()
+}
+/// Render unhighlighted `source` into one plain span per line.
+fn plain_lines(source: &str) -> Vec<Line> {
+    let mut lines: Vec<Line> = Vec::new();
+    let mut current: Vec<Span> = Vec::new();
+    push_text(&mut lines, &mut current, source, None);
+    if !current.is_empty() {
+        lines.push(Line { spans: current });
+    }
+    lines
+}
+/// Append `text` (with class `class`) to the line being built, splitting on
+/// newlines. Each embedded `\n` finishes the current line — preserving blank lines
+/// — and the class carries onto the next line, which is the crux of producing
+/// balanced per-line markup for a span that crosses a break.
+fn push_text(lines: &mut Vec<Line>, current: &mut Vec<Span>, text: &str, class: Option<&'static str>) {
+    for (i, segment) in text.split('\n').enumerate() {
+        if i > 0 {
+            lines.push(Line {
+                spans: std::mem::take(current),
+            });
+        }
+        if !segment.is_empty() {
+            current.push(Span {
+                class,
+                text: segment.to_string(),
+            });
+        }
+    }
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use std::path::Path;
+    use super::*;
+    /// Flatten a line back to its text, for assertions independent of span layout.
+    fn line_text(line: &Line) -> String {
+        line.spans.iter().map(|s| s.text.as_str()).collect()
+    }
+    #[test]
+    fn highlights_rust_and_marks_keywords() {
+        let out = highlight(Path::new("main.rs"), b"fn main() {}\n", None);
+        assert_eq!(out.language.as_deref(), Some("rust"));
+        assert_eq!(out.lines.len(), 1);
+        // `fn` should carry the keyword class somewhere on the line.
+        let classes: Vec<_> = out.lines[0].spans.iter().filter_map(|s| s.class).collect();
+        assert!(classes.contains(&"hl-keyword"), "classes: {classes:?}");
+        assert_eq!(line_text(&out.lines[0]), "fn main() {}");
+    }
+    #[test]
+    fn every_line_is_independently_balanced_across_a_multiline_string() {
+        // A multi-line string literal: the string class must reopen on each line,
+        // so every line stands alone with balanced spans.
+        let src = "fn f() -> &'static str {\n    \"line one\nline two\nline three\"\n}\n";
+        let out = highlight(Path::new("s.rs"), src.as_bytes(), None);
+        // The three literal lines each carry the string class.
+        let string_lines: Vec<usize> = out
+            .lines
+            .iter()
+            .enumerate()
+            .filter(|(_, l)| l.spans.iter().any(|s| s.class == Some("hl-string")))
+            .map(|(i, _)| i)
+            .collect();
+        assert!(
+            string_lines.len() >= 3,
+            "string spans should reopen on each continuation line: {string_lines:?}"
+        );
+        // No span text ever contains a newline.
+        for line in &out.lines {
+            for span in &line.spans {
+                assert!(!span.text.contains('\n'), "span leaked a newline: {span:?}");
+            }
+        }
+    }
+    #[test]
+    fn preserves_blank_lines_and_line_count() {
+        let out = highlight(Path::new("a.rs"), b"fn a() {}\n\nfn b() {}\n", None);
+        assert_eq!(out.lines.len(), 3);
+        assert_eq!(line_text(&out.lines[1]), "");
+    }
+    #[test]
+    fn binary_content_degrades_to_plain() {
+        let out = highlight(Path::new("x.rs"), b"fn main() {\0}\n", None);
+        assert_eq!(out.language, None, "NUL byte marks it binary → plain");
+    }
+    #[test]
+    fn minified_content_degrades_to_plain() {
+        let mut src = String::from("let x = ");
+        src.push_str(&"a".repeat(MINIFIED_LINE_BYTES + 1));
+        src.push('\n');
+        let out = highlight(Path::new("min.js"), src.as_bytes(), None);
+        assert_eq!(out.language, None);
+    }
+    #[test]
+    fn unknown_language_is_plain_but_still_line_split() {
+        let out = highlight(Path::new("notes.zzz"), b"one\ntwo\n", None);
+        assert_eq!(out.language, None);
+        assert_eq!(out.lines.len(), 2);
+        assert_eq!(line_text(&out.lines[0]), "one");
+        assert!(out.lines[0].spans.iter().all(|s| s.class.is_none()));
+    }
+    #[test]
+    fn highlight_document_matches_source_lines() {
+        let lang = resolve(Path::new("main.rs"), b"fn main() {}\n", None);
+        let lines = highlight_document(&lang, "fn main() {}\nlet x = 1;\n");
+        assert_eq!(lines.len(), 2);
+        assert_eq!(line_text(&lines[0]), "fn main() {}");
+        assert_eq!(line_text(&lines[1]), "let x = 1;");
+    }
+}

               pkgs.libgit2
               pkgs.zlib
               pkgs.openssl
+              # inkjet compiles tree-sitter grammars (some C++), whose objects link
+              # libstdc++ dynamically; keep it in the closure so the built binary
+              # rpaths it and interactive `cargo test` finds it via LD_LIBRARY_PATH.
+              pkgs.stdenv.cc.cc.lib
             ];
             # Use the system libgit2 rather than the vendored copy.
             LIBGIT2_NO_VENDOR = "1";