Function history on the file page 65be9f9c3074

//! Function boundaries on file pages (hub spec §6.6): tree-sitter finds

//! the functions and methods of a Rust, TypeScript, Python or shell file,

//! with the lines they span, so a function's history (Oxygen spec §27) is

//! one click away.

/// A function or method and the lines it spans (1-based, inclusive).

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Function {

    /// Qualified by its enclosing type or class where there is one: `Repo::log`.

    pub name: String,

    pub start: usize,

    pub end: usize,

}

/// The grammar for a path, by its extension, and the node kinds that are

/// functions in it.

fn grammar(path: &str) -> Option<(tree_sitter::Language, &'static [&'static str])> {

    let ext = path.rsplit_once('.').map(|(_, e)| e.to_ascii_lowercase())?;

    Some(match ext.as_str() {

        "rs" => (tree_sitter_rust::LANGUAGE.into(), &["function_item"][..]),

        "ts" | "mts" | "cts" => (

            tree_sitter_typescript::LANGUAGE_TYPESCRIPT.into(),

            &["function_declaration", "method_definition", "generator_function_declaration"][..],

        ),

        "tsx" => (

            tree_sitter_typescript::LANGUAGE_TSX.into(),

            &["function_declaration", "method_definition", "generator_function_declaration"][..],

        ),

        "py" => (tree_sitter_python::LANGUAGE.into(), &["function_definition"][..]),

        "sh" | "bash" => (tree_sitter_bash::LANGUAGE.into(), &["function_definition"][..]),

        _ => return None,

    })

}

/// Node kinds whose name qualifies the functions inside them.

const CONTAINERS: &[&str] = &["impl_item", "trait_item", "class_declaration", "class_definition", "mod_item"];

/// The functions of `text`, in file order; empty for a language without a

/// grammar here or text that does not parse.

pub fn functions(path: &str, text: &str) -> Vec<Function> {

    let Some((language, kinds)) = grammar(path) else { return vec![] };

    let mut parser = tree_sitter::Parser::new();

    if parser.set_language(&language).is_err() {

        return vec![];

    }

    let Some(tree) = parser.parse(text, None) else { return vec![] };

    let mut out = Vec::new();

    walk(tree.root_node(), text.as_bytes(), kinds, &mut Vec::new(), &mut out);

    out

}

fn name_of(node: tree_sitter::Node, src: &[u8]) -> Option<String> {

    let n = node.child_by_field_name("name").or_else(|| node.child_by_field_name("type"))?;

    n.utf8_text(src).ok().map(|s| s.split_whitespace().collect::<Vec<_>>().join(" "))

}

fn walk(node: tree_sitter::Node, src: &[u8], kinds: &[&str], scope: &mut Vec<String>, out: &mut Vec<Function>) {

    let kind = node.kind();

    let mut pushed = false;

    if kinds.contains(&kind) {

        if let Some(name) = name_of(node, src) {

            let mut full = scope.clone();

            full.push(name);

            out.push(Function { name: full.join("::"), start: node.start_position().row + 1, end: node.end_position().row + 1 });

        }

    } else if CONTAINERS.contains(&kind) {

        if let Some(name) = name_of(node, src) {

            scope.push(name);

            pushed = true;

        }

    }

    let mut cursor = node.walk();

    for child in node.children(&mut cursor) {

        walk(child, src, kinds, scope, out);

    }

    if pushed {

        scope.pop();

    }

}

#[cfg(test)]

mod tests {

    use super::*;

    fn names(path: &str, text: &str) -> Vec<(String, usize, usize)> {

        functions(path, text).into_iter().map(|f| (f.name, f.start, f.end)).collect()

    }

    #[test]

    fn rust_functions_and_methods() {

        let src = "use x;\n\nfn free() {\n    a();\n}\n\nimpl Repo {\n    pub fn log(&self) -> u8 {\n        1\n    }\n}\n\ntrait T {\n    fn t(&self);\n}\n";

        assert_eq!(names("src/lib.rs", src), [("free".to_string(), 3, 5), ("Repo::log".to_string(), 8, 10)]);

        let generic = "impl<T> Wrap<T> {\n    fn get(&self) {}\n}\n";

        assert_eq!(names("a.rs", generic), [("Wrap<T>::get".to_string(), 2, 2)]);

    }

    #[test]

    fn typescript_python_and_shell() {

        let ts = "export function activate(ctx: X): void {\n  go();\n}\nclass Repo {\n  refresh(): void {\n    x();\n  }\n}\n";

        assert_eq!(names("src/extension.ts", ts), [("activate".to_string(), 1, 3), ("Repo::refresh".to_string(), 5, 7)]);

        let py = "def top():\n    pass\n\nclass Recipe:\n    def main(self):\n        return 1\n";

        assert_eq!(names("images/rust/recipe.py", py), [("top".to_string(), 1, 2), ("Recipe::main".to_string(), 5, 6)]);

        let sh = "#!/bin/sh\nbuild() {\n  cargo build\n}\n";

        assert_eq!(names("build.sh", sh), [("build".to_string(), 2, 4)]);

    }

    #[test]

    fn other_files_have_none() {

        assert!(functions("README.md", "# fn main() {}\n").is_empty());

        assert!(functions("Makefile", "all:\n").is_empty());

    }

}

{% extends "base.html" %}

{% import "repo_tabs.html" as m %}

{% block title %}History of {% if name.is_empty() %}lines {{ start }}–{{ end }}{% else %}{{ name }}{% endif %} · {{ path }} · {{ repo.owner }}/{{ repo.name }}{% endblock %}

{% block bodyattrs %} data-repo="{{ repo.url }}"{% endblock %}

{% block tabs %}{% call m::tabs(repo, "code") %}{% endblock %}

{% block content %}

<div class="head"><h1>History of <code>{% if name.is_empty() %}lines {{ start }}–{{ end }}{% else %}{{ name }}{% endif %}</code> <small>{{ entries.len() }} change{% if entries.len() != 1 %}s{% endif %}</small></h1>

<p class="small mute">In <a href="{{ repo.url }}/file/{{ r }}/{{ path }}#L{{ start }}">{{ path }}</a>, lines {{ start }}–{{ end }} on {{ r }}. Every change that wrote or deleted one of these lines, or deleted a line from between them. Exact, because each line keeps its identity across edits; edits elsewhere in the file are not here. Also: <code>oxy log -L {{ start }},{{ end }}:{{ path }}</code>.</p></div>

{% if entries.is_empty() %}<p class="empty">No changes.</p>{% else %}

<div class="hist" style="--lanes: {{ lanes }}">

{% for c in entries %}

  {% let row = rows[loop.index0] %}

  <div class="hrow">

    <svg class="lanes" width="{{ lanes * 18 + 4 }}" height="100%" viewBox="0 0 {{ lanes * 18 + 4 }} 60" preserveAspectRatio="none" aria-hidden="true">

      {% for l in row.through %}<line x1="{{ l * 18 + 10 }}" y1="0" x2="{{ l * 18 + 10 }}" y2="60" class="lane"/>{% endfor %}

      {% for e in row.edges %}<path d="M{{ e.0 * 18 + 10 }} 30 L{{ e.0 * 18 + 10 }} 44 L{{ e.1 * 18 + 10 }} 60" class="lane"/>{% endfor %}

      <line x1="{{ row.lane * 18 + 10 }}" y1="0" x2="{{ row.lane * 18 + 10 }}" y2="30" class="lane{% if loop.first %} none{% endif %}"/>

      <circle cx="{{ row.lane * 18 + 10 }}" cy="30" r="4" class="node{% if c.resolution %} res{% endif %}"/>

    </svg>

    {% call m::change_row(repo, c) %}

  </div>

{% endfor %}

</div>

{% endif %}

{% endblock %}

    rootfs "cas://blob/9d76e1aef3ab096c57dfdab6ed2cfb4de1dc70e67ca0e7f299e087f7abb7e61a"

    rootfs "cas://blob/9d76e1aef3ab096c57dfdab6ed2cfb4de1dc70e67ca0e7f299e087f7abb7e61a"

 "tree-sitter",

 "tree-sitter-bash",

 "tree-sitter-python",

 "tree-sitter-rust",

 "tree-sitter-typescript",

 "indexmap",

[[package]]

name = "streaming-iterator"

version = "0.1.9"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "2b2231b7c3057d5e4ad0156fb3dc807d900806020c5ffa3ee6ff2c8c76fb8520"

]

[[package]]

name = "tree-sitter"

version = "0.27.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "2038684e0058edba0d17302619f62eabce4a8e11c6ac59506996a8d79848851d"

dependencies = [

 "cc",

 "regex",

 "serde_json",

 "streaming-iterator",

 "tree-sitter-language",

]

[[package]]

name = "tree-sitter-bash"

version = "0.25.1"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "9e5ec769279cc91b561d3df0d8a5deb26b0ad40d183127f409494d6d8fc53062"

dependencies = [

 "cc",

 "tree-sitter-language",

]

[[package]]

name = "tree-sitter-language"

version = "0.1.8"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "ca0d1bf6fdd806e43ae5198f82f527056d359def39e54e67a0f478ac09dac081"

[[package]]

name = "tree-sitter-python"

version = "0.25.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "6bf85fd39652e740bf60f46f4cda9492c3a9ad75880575bf14960f775cb74a1c"

dependencies = [

 "cc",

 "tree-sitter-language",

]

[[package]]

name = "tree-sitter-rust"

version = "0.24.2"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "439e577dbe07423ec2582ac62c7531120dbfccfa6e5f92406f93dd271a120e45"

dependencies = [

 "cc",

 "tree-sitter-language",

]

[[package]]

name = "tree-sitter-typescript"

version = "0.23.2"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "6c5f76ed8d947a75cc446d5fccd8b602ebf0cde64ccf2ffa434d873d7a575eff"

dependencies = [

 "cc",

 "tree-sitter-language",

# Function boundaries on file pages (hub spec §6.6): the grammars of the

# languages the Oxygen projects are written in.

tree-sitter = "0.27"

tree-sitter-rust = "0.24"

tree-sitter-typescript = "0.23"

tree-sitter-python = "0.25"

tree-sitter-bash = "0.25"

pub mod functions;

#[derive(Deserialize)]

pub struct FunctionQuery {

    start: usize,

    end: usize,

    #[serde(default)]

    name: String,

}

#[derive(Template)]

#[template(path = "function.html")]

pub struct FunctionPage {

    shell: Shell,

    repo: RepoShell,

    r: String,

    path: String,

    name: String,

    start: usize,

    end: usize,

    entries: Vec<view::ChangeView>,

    rows: Vec<graph::Row>,

    lanes: usize,

}

/// `GET /{owner}/{name}/function/{ref}/{path}?start=…&end=…&name=…`: the

/// history of a function (hub spec §6.6): every change that wrote or

/// deleted one of its lines, exactly (Oxygen spec §27), with a graph of how

/// those changes depend on each other.

pub async fn function(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, r, path)): Path<(String, String, String, String)>,

    Query(q): Query<FunctionQuery>,

) -> Result<Page<FunctionPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/function/{r}/{path}"), &viewer);

    let (repo, row, role) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    let (spec, p, start, end) = (r.clone(), path.clone(), q.start, q.end);

    let mut entries = app

        .repos

        .read(&repo, move |repo, cache| {

            let target = view::resolve(repo, cache, &spec)?;

            let history = repo.line_history(&target.heads, &p, start, end)?;

            let labels = view::head_labels(repo)?;

            Ok(history.iter().map(|e| view::change_view_pub(repo, &e.hash, &e.change, e.is_head, &labels)).collect::<Vec<_>>())

        })

        .await

        .map_err(|e| Error::from_repo(shell.clone(), e))?;

    // The graph shows how these changes depend on one another.

    let listed: std::collections::HashSet<String> = entries.iter().map(|c| c.hash.clone()).collect();

    for c in &mut entries {

        c.deps.retain(|d| listed.contains(d));

    }

    super::attribute(&app, &mut entries.iter_mut().collect::<Vec<_>>()).await;

    let graph_input: Vec<(String, Vec<String>)> = entries.iter().map(|c| (c.hash.clone(), c.deps.clone())).collect();

    let rows = graph::layout(&graph_input);

    let lanes = graph::width(&rows);

    Ok(Page(FunctionPage {

        shell,

        repo: RepoShell::new(&app, &row, "code").with_role(role),

        r,

        path,

        name: q.name,

        start,

        end,

        entries,

        rows,

        lanes,

    }))

}

        .route("/{owner}/{name}/function/{r}/{*path}", get(history::function))

    /// Functions found in the file, each linking to its history.

    functions: Vec<crate::repos::functions::Function>,

    let functions = match &f.body {

        FileBody::Text(text) if !is_image => crate::repos::functions::functions(&f.path, text),

        _ => vec![],

    };

    Ok(Page(FilePage { shell, repo: rs, f, lines, language, markdown_html, is_image, is_markdown, blame, permalink, functions })

        .into_response())

/// Function history (hub spec §6.6): the file page lists a file's

/// functions, and a function's page lists exactly the changes to its lines.

#[tokio::test(flavor = "multi_thread")]

async fn a_function_has_its_own_history() {

    let h = hub().await;

    let app = &h.app;

    let andy = call(app, "POST", "/register", None, None, None, Some("username=andy&email=a%40example.com&password=correct-horse-battery"))

        .await

        .cookie

        .unwrap();

    let page = call(app, "GET", "/new", None, Some(&andy), None, None).await;

    call(app, "POST", "/new", None, Some(&andy), None, Some(&format!("_csrf={}&owner=andy&name=demo", csrf_of(&page.body)))).await;

    let url = format!("{}/andy/demo", h.base);

    let work = tempfile::tempdir().unwrap();

    let w = work.path().to_path_buf();

    tokio::task::spawn_blocking(move || {

        let mut c = Repo::init(&w).unwrap();

        c.config.set("remote.origin.url", &url).unwrap();

        c.config.set("remote.origin.token", "site").unwrap();

        c.save_config().unwrap();

        let steps = [

            ("add lib", "use x;\n\nimpl Repo {\n    fn log(&self) {\n        one();\n    }\n}\n"),

            ("change the import", "use y;\n\nimpl Repo {\n    fn log(&self) {\n        one();\n    }\n}\n"),

            ("log twice", "use y;\n\nimpl Repo {\n    fn log(&self) {\n        one();\n        one();\n    }\n}\n"),

        ];

        for (msg, text) in steps {

            write(&w, "src/lib.rs", text.as_bytes());

            c.commit(msg, &[]).unwrap();

        }

        assert!(c.push("origin", false).unwrap()[0].ok);

    })

    .await

    .unwrap();

    let file = call(app, "GET", "/andy/demo/file/main/src/lib.rs", None, None, None, None).await.body;

    assert!(file.contains("Functions") && file.contains("/andy/demo/function/main/src/lib.rs?start=4&end=7&name=Repo%3A%3Alog"), "{file}");

    let r = call(app, "GET", "/andy/demo/function/main/src/lib.rs?start=4&end=7&name=Repo%3A%3Alog", None, None, None, None).await;

    assert_eq!(r.status, StatusCode::OK, "{}", r.body);

    assert!(r.body.contains("History of <code>Repo::log</code>") && r.body.contains("2 changes"), "{}", r.body);

    assert!(r.body.contains("log twice") && r.body.contains("add lib") && !r.body.contains("change the import"));

    let bad = call(app, "GET", "/andy/demo/function/main/src/lib.rs?start=4&end=99", None, None, None, None).await;

    assert_ne!(bad.status, StatusCode::OK);

}

**Function history.** For Rust, TypeScript, Python and shell files, tree-sitter finds the functions and methods (qualified by their impl, trait or class, as `Repo::log`) and the file page's sidebar lists them. Each links to `/{owner}/{name}/function/{ref}/{path}?start=…&end=…&name=…`: every change that wrote or deleted one of the function's lines, or deleted a line from between them (Oxygen spec §27, the query `oxy log -L` runs), newest first, with a graph of how those changes depend on one another. It is exact because lines keep their identity across edits; changes elsewhere in the file are not listed. A cross-file semantic graph (callers, callees) is future work.

  {% if !functions.is_empty() %}

  <p class="side-root" id="functions">Functions</p>

  <ul class="functions">

  {% for fnc in functions %}

    <li><a href="{{ repo.url }}/function/{{ f.target.label }}/{{ f.path }}?start={{ fnc.start }}&end={{ fnc.end }}&name={{ fnc.name|urlencode }}" title="History of {{ fnc.name }}, lines {{ fnc.start }}–{{ fnc.end }}">{{ fnc.name }}</a> <a class="small mute" href="#L{{ fnc.start }}">L{{ fnc.start }}</a></li>

  {% endfor %}

  </ul>

  {% endif %}