{"id":15398554,"url":"https://github.com/jryans/anno","last_synced_at":"2025-03-28T00:29:37.847Z","repository":{"id":186563997,"uuid":"675371387","full_name":"jryans/anno","owner":"jryans","description":"File annotation toolkit that assists with aggregating annotations and presenting them in a `git annotate`-style sidebar view","archived":false,"fork":false,"pushed_at":"2024-07-04T15:25:52.000Z","size":93,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-02T02:27:01.321Z","etag":null,"topics":["annotate","annotation","blame","git","gutter","sidebar"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jryans.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-06T17:35:36.000Z","updated_at":"2024-07-04T15:25:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"e199e125-5998-4b2a-b722-42c3609154ed","html_url":"https://github.com/jryans/anno","commit_stats":{"total_commits":43,"total_committers":1,"mean_commits":43.0,"dds":0.0,"last_synced_commit":"aec889525d023f3b519127c239f4834cf5516913"},"previous_names":["jryans/anno"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jryans%2Fanno","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jryans%2Fanno/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jryans%2Fanno/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jryans%2Fanno/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jryans","download_url":"https://codeload.github.com/jryans/anno/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245948662,"owners_count":20698861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotate","annotation","blame","git","gutter","sidebar"],"created_at":"2024-10-01T15:44:35.223Z","updated_at":"2025-03-28T00:29:37.816Z","avatar_url":"https://github.com/jryans.png","language":"Rust","readme":"# Anno\n\nAnno is a file annotation toolkit that assists with aggregating annotations and\npresenting them in a `git annotate`-style sidebar view.\n\nAnnotations come from separate \"producer\" commands. Anno is packaged with a few\nsuch producers, but you can also write your own without needing to change Anno\nitself. Producers are just programs named `anno-\u003cproducer-name\u003e` that follow\ncertain input and output conventions.\n\n## Installation\n\nAnno is still in an initial development phase, so the only installation option\ninvolves building from source. If you have Rust's `cargo` package manager\n[installed][install-rust], you can use the following command:\n\n```\n$ cargo install --git https://github.com/jryans/anno\n```\n\n## Usage\n\nTo use Anno, you supply a file to be annotated along with one or more annotation\nproducers you are interested in. For example, the following uses the simple\n`lines` producer which adds lines numbers:\n\n```\n$ anno src/main.rs -p numbers:\nnum |\n1   | use std::{\n2   |     cmp::max,\n3   |     fs,\n4   |     path::PathBuf,\n5   |     str::{FromStr, Lines},\n6   | };\n7   |\n8   | use anyhow::{Context, Error, Ok, Result};\n9   | use clap::Parser;\n10  | use duct::cmd;\n...\n```\n\nMultiple producers can be supplied as well. The annotations from each producer\nare aggregated, with producer's data shown in a separate column:\n\n```\n$ anno src/main.rs -p debug-line-table:\u003cpath-to-debug-info\u003e -p numbers:\n...\n  | 51  |     // Read the file first to check line count\nx | 52  |     let target_path = cli.file.absolutize()?;\nx | 53  |     let target_content = fs::read_to_string(\u0026target_path).with_context(|| {\nx | 54  |         format!(\n  | 55  |             \"Unable to read file to be annotated ({})\",\nx | 56  |             cli.file.display()\n  | 57  |         )\nx | 58  |     })?;\n...\n```\n\n## Additional features\n\n- Diff mode (`--diff`)\\\n  Visually highlights differences between annotations from the first two\n  producers\n\n  \u003cimg\n    width=\"381\"\n    alt=\"Example of diff mode with visual highlighting to denote differences in annotations\"\n    src=\"https://github.com/jryans/anno/assets/279572/5fabdaac-4861-467a-adb9-b8ac139f10d8\"\u003e\n\n- Diff only mode (`--diff-only`)\\\n  Only show lines with differences between the first two producers\n\n## Included producers\n\n### Numbers\n\nUsage: `-p numbers:`\n\nThis producer numbers the lines of the annotated file in order, just like you\nmight see in an editor.\n\n### Debug line table\n\nUsage: `-p debug-line-table:\u003cpath-to-debug-info\u003e`\n\nThis producer takes a DWARF debug info file and checks whether each source line\nof the file being annotated is present in the debug info's line table.\n\n### Debug variables locatable\n\nUsage: `-p debug-vars-locatable:\u003cpath-to-debug-info\u003e`\n\nThis producer takes a DWARF debug info file and collects all variables which are\nlocatable on each source line.\n\n### Source lines with computation\n\nUsage: `-p source-computation:`\n\nThis producer analyses C source files and annotates source lines where some\nnotion of \"computation\" occurs.\n\nYou will need to have `dbgcov-cflags` from [`dbgcov`][dbgcov] in your `PATH`.\nThe `CC` environment variable (or `cc` command) will need to point to a version\nof `cc` from GCC.\n\n### Source variables may be defined\n\nUsage: `-p source-vars-may-be-defined:`\n\nThis producer analyses C source files and collects all variables which may be\ndefined on each source line.\n\nYou will need to have `dbgcov-cflags` from [`dbgcov`][dbgcov] in your `PATH`.\nThe `CC` environment variable (or `cc` command) will need to point to a version\nof `cc` from GCC.\n\n### Source variables must be defined\n\nUsage: `-p source-vars-must-be-defined:`\n\nThis producer analyses C source files and collects all variables which must be\ndefined on each source line.\n\nYou will need to have `dbgcov-cflags` from [`dbgcov`][dbgcov] in your `PATH`.\nThe `CC` environment variable (or `cc` command) will need to point to a version\nof `cc` from GCC.\n\n### KLEE coverage\n\nUsage: `-p klee-coverage:\u003cpath-to-klee-output-dir\u003e`\n\nThis produces collates all `*.istats` files produced by KLEE and checks whether\neach source line has been covered.\n\n## Producer URI syntax\n\nProducers are currently enabled via the `-p` option which accepts a URI-based\nsyntax. There may be better ways to configure this... Feel free to open an issue\nif you have a suggestion.\n\n- Producer only\\\n  `producer:`\n- Producer with data source\\\n  `producer:/path/to/data/source`\n- Producer with data source and additional arguments\\\n  `producer:/path/to/data/source?param=value`\n\nOne small oddity of this URI syntax is that you must add a trailing `:` when\nnaming only the producer. A future version of Anno may make this optional.\n\n## Producer protocol\n\n### Command\n\nFor each producer, Anno attempts to execute a command formed from the producer\nname with the prefix `anno-` added to it. So for the producer `lines`, Anno\ntries to run the command `anno-lines`.\n\nCurrently there is no way to supply the full path to a producer command, so\n`anno-\u003cproducer\u003e` must be accessible via your `PATH` environment variable.\n\n### Input\n\nProducers receive input from Anno via various `ANNO`-prefixed environment\nvariables. This is still in flux, so it's best to check the source and examples\nfor now.\n\n### Output\n\nAnno currently uses a very simple annotation format. Each producer supplies\ntheir annotation data as a line of text for each line in the file being\nannotated. Other output formats [may be added](#future-work) in the future.\n\n## Future work\n\n- [ ] Add incremental output format\n- [ ] Add editor integration with more complex output abilities\n- [ ] Add [Compiler Explorer][ce] integration\n\n[install-rust]: https://www.rust-lang.org/tools/install\n[dbgcov]: https://github.com/stephenrkell/dbgcov\n[ce]: https://github.com/compiler-explorer/compiler-explorer\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjryans%2Fanno","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjryans%2Fanno","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjryans%2Fanno/lists"}