{"id":19017470,"url":"https://github.com/junkdog/sift","last_synced_at":"2026-03-03T18:02:11.895Z","repository":{"id":66027400,"uuid":"561870959","full_name":"junkdog/sift","owner":"junkdog","description":"A CLI tool to analyze and reverse model software system designs from JVM bytecode.","archived":false,"fork":false,"pushed_at":"2025-05-22T13:42:50.000Z","size":14724,"stargazers_count":61,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-11T21:57:46.791Z","etag":null,"topics":["cli","introspection","java-bytecode","jvm-bytecode","kotlin","project-analysis","reverse-engineering","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/junkdog.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2022-11-04T17:20:28.000Z","updated_at":"2025-08-01T14:37:32.000Z","dependencies_parsed_at":"2023-11-20T21:29:54.752Z","dependency_job_id":"ade98065-253e-4212-8989-970f467cd28e","html_url":"https://github.com/junkdog/sift","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/junkdog/sift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fsift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fsift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fsift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fsift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/junkdog","download_url":"https://codeload.github.com/junkdog/sift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fsift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30053999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T17:46:22.538Z","status":"ssl_error","status_checked_at":"2026-03-03T17:46:22.036Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cli","introspection","java-bytecode","jvm-bytecode","kotlin","project-analysis","reverse-engineering","static-analysis"],"created_at":"2024-11-08T19:47:07.504Z","updated_at":"2026-03-03T18:02:11.857Z","avatar_url":"https://github.com/junkdog.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sift\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.onedaybeard.sift/sift/badge.png)](https://maven-badges.herokuapp.com/maven-central/net.onedaybeard.sift/sift/badge.png)\n[![DSL docs](https://badgen.net/badge/docs/DSL/orange?icon=github)](https://junkdog.github.io/sift/)\n\nSift is a command-line tool that analyzes and reverse models software system designs from JVM bytecode.\nIt operates by processing .class or .jar files using predefined templates known as System Model\nTemplates. These templates provide knowledge about technology stacks or project-specific constructs,\nwhich enables the tool to generate a comprehensive model of the system.\n\nThe resulting system model is composed of entities that describe the system's structure and behavior.\n\n## Use Cases\n- **Refactoring**: Simplify refactoring by identifying dependencies and isolating components.\n- **Onboarding**: Help new team members understand the system's architecture quickly.\n- **Impact Analysis**: Use the `--diff` option to analyze the impact of new features or changes.\n- **Documentation**: Generate graphical or textual representations of your system for documentation purposes.\n- **Microservice Analysis**: Quickly understand interactions in a microservices environment.\n \n## Features\n- CLI tool for building, querying, and [comparing][diff] system models from parsed .class files.\n- Declarative DSL for writing user-defined templates, optionally extending or combining existing templates.\n- JSON serialization of templates for easy reuse and sharing.\n- Render system representations using Graphviz. Inline rendering for [kitty][kitty] supported via sift.sh|zsh.\n- Optionally built as a native binary using GraalVM's native-image, allowing for much faster execution times.\n  This means that Sift can typically analyze most microservice-sized projects in under 0.5 seconds.\n\n\n![sift spring-boot axon framework][orders-graph]\n\n\n_Spring-Boot with Axon Framework [template][spring-axon] in action; filtering on shipped and confirmed orders\nin https://github.com/eugenp/tutorials/tree/master/axon._\n\n[![][orders-t]][orders] [![][system-render-t]][system-render] [![][dump-sm-t]][dump-sm] [![][sift-dsl-t]][sift-dsl]\n\n [kitty]: https://sw.kovidgoyal.net/kitty/\n\n [spring-axon]: templates/spring-boot-axon-cqrs/src/main/kotlin/sift/template/sbacqrs/SpringBootAxonCqrsTemplate.kt#L124:L240\n [diff]: docs/images/sift-spring-axon-diff.png\n [graphviz]: docs/images/sift-spring-axon-render.png\n\n [orders]: https://raw.githubusercontent.com/junkdog/sift/main/docs/images/sift-spring-axon-orders.png\n [orders-t]: docs/images/sift-spring-axon-orders_thumbnail.png\n\n [orders-graph]: docs/images/sift-spring-axon-orders-render.png\n [orders-graph-t]: docs/images/sift-spring-axon-orders-render_thumbnail.png\n\n [system-render]: https://raw.githubusercontent.com/junkdog/sift/main/docs/images/sift-spring-axon-render.png\n [system-render-t]: docs/images/sift-spring-axon-render_thumbnail.png\n\n [dump-sm]: https://raw.githubusercontent.com/junkdog/sift/main/docs/images/sift-spring-axon-dump-system-model.png\n [dump-sm-t]: docs/images/sift-spring-axon-dump-system-model_thumbnail.png\n\n [sift-dsl]: https://raw.githubusercontent.com/junkdog/sift/dev/docs/images/sift-diff-maven-coords.png\n [sift-dsl-t]: docs/images/sift-diff-maven-coords_thumbnail.png\n\n## CLI options\n\n```\nUsage: sift [OPTIONS]\n\n  Sift is a command-line tool that analyzes and reverse models software system designs\n  from JVM bytecode.\n\nTemplate options:\n  -t, --template TEMPLATE               The template producing the system model.\n  -l, --list-templates                  Print all installed templates.\n  -T, --list-entity-types               Lists entity types defined by template.\n  -f, --class-dir, --classes PATH|URI|MAVEN_COORD\n                                        Provide class input as a directory, JAR file, URI\n                                        (pointing to a JAR), or Maven coordinate.\n  -d, --diff FILE_JSON|URI|MAVEN_COORD  Compare the system model from '-f' with another,\n                                        specified as a JSON file (previously saved System\n                                        Model), class input as a directory, JAR file, URI\n                                        (pointing to a JAR), or Maven coordinate.\n  --profile                             Print execution times and input/output for the\n                                        executed template.\n  -D, --dump-system-model               Print all entities along with their properties and\n                                        metadata.\n\nEntity tree/graph options:\n  -L, --max-depth INT                   Max display depth of the tree.\n  -F, --filter REGEX                    Filter nodes by label. (repeatable)\n  -S, --filter-context REGEX            Filter nodes by label, while also including\n                                        sibling nodes. (repeatable)\n  -e, --exclude REGEX                   Exclude nodes when label matches REGEX.\n                                        (repeatable)\n  -c, --column [all|element-id|element-type|entity-type]\n                                        Columns to display. (repeatable)\n  -E, --exclude-type ENTITY_TYPE        Exclude entity types from tree. (repeatable)\n  -r, --tree-root ENTITY_TYPE           Tree built around requested entity type.\n                                        (repeatable)\n  --no-emoji                            Disables printing emoji in entity labels.\n\nVisualization options:\n  -R, --render                          Render entities with graphviz's DOT language.\n  --edge-layout [spline|polyline|ortho]\n                                        Sets the layout for the lines between nodes.\n                                        (default: spline)\n\nSerialization options:\n  -s, --save FILE_JSON  Save the resulting system model as json.\n  --load FILE_JSON      Load a previously saved system model.\n\nDebug options:\n  --debug                               Print log/logCount statements from the executed\n                                        template.\n  -X, --debug-inverse-trace             Print the inverse element trace for the elements\n                                        specified with --debug-element-traces\n  -x, --debug-element-trace ELEMENT_ID  Print all element traces leading to the specified\n                                        elements\n\nMiscellaneous options:\n  -a, --ansi [none|ansi16|ansi256|truecolor]\n                                        Override automatically detected ANSI support.\n  --stacktrace                          Print stacktrace to stderr if an error occurs\n  --version                             Print version and release date.\n  -m, --maven-repository VALUE          Additional maven repositories to use for\n                                        downloading artifacts. Maven central\n                                        (https://repo1.maven.org/maven2/) and local user\n                                        repositories are always included.\n  --statistics                          Print internal statistics about the system model\n                                        template context.\n  --generate-completion [bash|zsh|fish]\n  -h, --help                            Show this message and exit\n\nExamples:\n  sift --template spring-axon -f my-spring-project\n  Model the system using the \"spring-axon\" template on the classes in the\n  \"my-spring-project\" directory.\n\n  sift -t spring-axon -f . -F \"Order(Created|Shipped)\"\n  Model the system using the \"spring-axon\" template on the current directory's\n  classes, filter nodes containing the regular expression \"Order(Created|Shipped)\".\n\n  sift -t spring-axon -f . --diff feature-01.json\n  Compare the current design of the system using the \"spring-axon\" template on\n  the classes in the current directory against a previously saved system model\n  from \"feature-01.json\" and show the differences.\n\n  sift -t sift -f \"net.onedaybeard.sift:core:0.13.0\" --diff \"net.onedaybeard.sift:core:0.9.0\"\n  Compare two different versions of the DSL API using the 'sift' template, specified\n  by their maven coordinates.\n```\n\n## System Model Templates and Entities\n\nThe system model describes the structure and relationships of entities within a system.\nAn entity is an object or component within the system, uniquely identified by a class,\nmethod, field, parameter or generic signature. \n\nEntities are categorized by their `Entity.Type`. An entity type represents any\nnoteworthy part of the system. For example, types can include REST controllers, HTTP\nendpoints, inbound/outbound messages, RDS, repositories and more.\n\n```bash\n$ sift --template spring-axon -f target/classes --list-entity-types \nentity types of spring-axon\n  1 aggregate\n  2 aggregate-ctor\n  1 aggregate-member\n  6 command\n  6 command-handler\n  1 controller\n 13 endpoint\n  7 event\n  7 event-handler\n  7 event-sourcing-handler\n  1 projection\n  3 query\n  4 query-handler\n ```\nSystem Model Templates describe how entities are identified within a given technology stack\nand/or project-specific constructs. The templates are written in a declarative DSL and are\nused to produce the system model from input classes. The DSL provides high-level abstractions\nfor identifying and interrelating entities from class structure or usage.\n\nThe code below shows a simple System Model Template that identifies REST controllers and\nHTTP endpoints within a system and associates the two entities.\n\n```kotlin\nval controller = Entity.Type(\"controller\")\nval endpoint = Entity.Type(\"endpoint\")\n\ntemplate {\n    // iterate over all input classes\n    classes {                                                      \n        annotatedBy\u003cRestController\u003e() // filter classes \n        entity(controller)            // mark remaining as 'controller'  \n        methods {                     // iterate all controller methods\n            annotatedBy\u003cEndpoint\u003e()   // filter @Endpoint methods\n            entity(endpoint)\n\n            // associate controllers with their endpoints  \n            controller[\"endpoints\"] = endpoint\n        }\n    }\n}\n```\nInput elements (classes, methods, parameters, fields, generic signatures) are processed in batches,\nline-by-line. The execution of a System Model Template can be introspected with the `--profile` option.\n\n![sift profile JPA template](docs/images/sift-profile-jpa.png)\n\nA typical template can be expressed in about 100-200 lines of code. Some templates,\nsuch as those for [JPA][jpa] and [JDBI][jdbi], are notably shorter. User-defined templates\ncan include multiple existing templates to better describe the underlying system while also\nkeeping the resulting DSL concise.\n\n [jpa]: templates/jpa/src/main/kotlin/sift/template/jpa/JpaTemplate.kt#L55:L79\n [jdbi]: templates/jdbi/src/main/kotlin/sift/template/jdbi/Jdbi3Template.kt#L50:L66\n\n\n\n## Installation\n\nSift requires a java 17 or later runtime.\n\nFor window users, it is recommended to to run sift under WSL, until proper windows\npaths are in place.\n\nThe easiest way to install sift is to clone the repository and run `mvn install`, and\nthen copy sift.zsh|sh to a location on the `$PATH`, e.g.:\n\n- `mvn install` from project root. This installs sift to `~/.local/share/sift/bin`\n- copy either `sift.zsh` or `sift.sh` to `~/.local/bin/sift`\n\nThe `main` branch always points to the latest release commit.\n\n\n### Building a native binary on linux using GraalVM\n\nIf GraalVM and native-image is installed, a native binary can be built with the `native-image`\nmaven profile: `mvn install -P native-image`. The resulting binary will be located in\n`~/.local/share/sift/bin/sift`. `sift.zsh` and `sift.sh` first checks if the native binary\nis available, otherwise it tries to run the jar.\n\nThe native binary is considerably faster than the jar, but it can cause issues if it needs\nto deserialize a system model (via `--load` or `--diff`) or system model template containing\nunknown types (e.g. from `withValue()`).\n\n\n## Caveats and limitations\n- no flow analysis making precise entity identification difficult for e.g. dispatcher-like \n  methods dealing with multiple entity types.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunkdog%2Fsift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjunkdog%2Fsift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunkdog%2Fsift/lists"}