{"id":16391795,"url":"https://github.com/williamfzc/srctx","last_synced_at":"2025-03-31T07:09:39.588Z","repository":{"id":151693718,"uuid":"621393075","full_name":"williamfzc/srctx","owner":"williamfzc","description":"A library for extracting and analyzing definition/reference graphs from your codebase. Powered by tree-sitter and LSIF/SCIP.","archived":false,"fork":false,"pushed_at":"2024-11-24T03:22:48.000Z","size":356,"stargazers_count":46,"open_issues_count":15,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-22T18:39:47.051Z","etag":null,"topics":["callgraph","diff","golang","lsif","lsp","sourcegraph","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/williamfzc.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2023-03-30T15:12:59.000Z","updated_at":"2025-01-13T09:21:08.000Z","dependencies_parsed_at":"2023-05-20T08:30:22.903Z","dependency_job_id":"8419f712-8a88-49f3-a313-6440efa7212b","html_url":"https://github.com/williamfzc/srctx","commit_stats":{"total_commits":208,"total_committers":3,"mean_commits":69.33333333333333,"dds":0.009615384615384581,"last_synced_commit":"91713286c671742e9a3fae54f77a7d7c39e93d6f"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamfzc%2Fsrctx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamfzc%2Fsrctx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamfzc%2Fsrctx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamfzc%2Fsrctx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamfzc","download_url":"https://codeload.github.com/williamfzc/srctx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246429487,"owners_count":20775807,"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":["callgraph","diff","golang","lsif","lsp","sourcegraph","static-analysis"],"created_at":"2024-10-11T04:47:22.149Z","updated_at":"2025-03-31T07:09:39.566Z","avatar_url":"https://github.com/williamfzc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!TIP]\n\u003e Now we have another more powerful alternative in Rust, \n\u003e which offering a more general solution for building relationships between source files, \n\u003e without runtime indexing (like LSIF/SCIP).\n\u003e \n\u003e See: https://github.com/williamfzc/gossiphs\n\n---\n\n\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/williamfzc/srctx/assets/13421694/e99b5cf6-07d7-49fb-a70a-862deab83e49\" width=\"400\" height=\"300\"\u003e\n\u003c/h1\u003e\n\n\u003ch3 align=\"center\"\u003esrctx: source context\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n    \u003cem\u003eA library for extracting and analyzing definition/reference graphs from your codebase. Powered by tree-sitter and LSIF/SCIP.\u003c/em\u003e\n\u003c/p\u003e\n\n| Name           | Status                                                                                                                                            |\n|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------|\n| Latest Version | ![GitHub release (latest by date)](https://img.shields.io/github/v/release/williamfzc/srctx)                                                      |\n| Unit Tests     | [![Go](https://github.com/williamfzc/srctx/actions/workflows/ci.yml/badge.svg)](https://github.com/williamfzc/srctx/actions/workflows/ci.yml)     |\n| Code Coverage  | [![codecov](https://codecov.io/github/williamfzc/srctx/branch/main/graph/badge.svg?token=1DuAXh12Ys)](https://codecov.io/github/williamfzc/srctx) |\n| Code Style     | [![Go Report Card](https://goreportcard.com/badge/github.com/williamfzc/srctx)](https://goreportcard.com/report/github.com/williamfzc/srctx)      |\n\n## About this tool\n\nThis library processes your code into precise function-level graphs, seamlessly integrated with Git, and then you can apply some analysis to them.\n\n\u003cimg width=\"1389\" alt=\"image\" src=\"https://github.com/williamfzc/srctx/assets/13421694/e48a51c7-e95b-4da7-994f-f5fe1f461477\"\u003e\n\nWith this lib developers can know exactly what happened in every lines of your code. Such as definition, reference. And understand the actual impacts of your git commits.\n\nSome \"dangerous\" line changes can be found automatically.\n\n\u003cimg width=\"843\" alt=\"image\" src=\"https://github.com/williamfzc/srctx/assets/13421694/e6e48e67-35b1-4c52-aa6a-99b1ba2f02db\"\u003e\n\nYou can see a dangerous change in file `cmd/srctx/diff/cmd.go#L29-#143`, .\n\nIn addition, as a library, it also provides convenient APIs for secondary development, allowing you to freely access the content in the graph.\n\n```golang\nsrc := filepath.Dir(filepath.Dir(curFile))\nlsif := \"../dump.lsif\"\nlang := core.LangGo\n\nfuncGraph, _ := function.CreateFuncGraphFromDirWithLSIF(src, lsif, lang)\n\nfunctions := funcGraph.GetFunctionsByFile(\"cmd/srctx/main.go\")\nfor _, each := range functions {\n    // about this function\n    log.Infof(\"func: %v\", each.Id())\n    log.Infof(\"decl location: %v\", each.FuncPos.Repr())\n    log.Infof(\"func name: %v\", each.Name)\n\n    // context of this function\n    outVs := funcGraph.DirectReferencedIds(each)\n    log.Infof(\"this function reached by %v other functions\", len(outVs))\n    for _, eachOutV := range outVs {\n        outV, _ := funcGraph.GetById(eachOutV)\n        log.Infof(\"%v directly reached by %v\", each.Name, outV.Name)\n    }\n}\n```\n\nOutput:\n\n```text\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"func: cmd/srctx/main.go:#16-#26:main||mainFunc|[]string|\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"decl location: cmd/srctx/main.go#16-26\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"func name: mainFunc\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"this function reached by 7 other functions\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"mainFunc directly reached by TestDiffDir\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"mainFunc directly reached by TestDiffNoDiff\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"mainFunc directly reached by TestRenderHtml\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"mainFunc directly reached by TestDiffRaw\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"mainFunc directly reached by TestDiffSpecificLang\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"mainFunc directly reached by TestDiff\"\ntime=\"2023-06-17T19:48:52+08:00\" level=info msg=\"mainFunc directly reached by main\"\n```\n\n\u003e Currently, srctx is still in an active development phase. \n\u003e If you're interested in its iteration direction and vision, you can check out [our roadmap page](https://github.com/williamfzc/srctx/issues/31).\n\n# Usage\n\n## Quick Start\n\nWe provide a one-click script for quickly deploying srctx anywhere. Common parameters include:\n\n- SRCTX_LANG: Required, specifies the language, such as GOLANG/JAVA/KOTLIN.\n- SRCTX_BUILD_CMD: Optional, specifies the compilation command.\n\n### For Golang\n\n```bash\ncurl https://raw.githubusercontent.com/williamfzc/srctx/main/scripts/quickstart.sh \\\n| SRCTX_LANG=GOLANG bash\n```\n\n### For Java/Kotlin\n\nAs there is no unique compilation toolchain for Java (it could be Maven or Gradle, for example), \nso at the most time, you also need to specify the compilation command to obtain the invocation information.\n\nYou should replace the `SRCTX_BUILD_CMD` with your own one.\n\nJava:\n\n```bash\ncurl https://raw.githubusercontent.com/williamfzc/srctx/main/scripts/quickstart.sh \\\n| SRCTX_LANG=JAVA SRCTX_BUILD_CMD=\"clean package -DskipTests\" bash\n```\n\nKotlin:\n\nChange the `SRCTX_LANG=JAVA` to `SRCTX_LANG=KOTLIN`.\n\n## In Production\n\nIn proudction, it is generally recommended to separate the indexing process from the analysis process, rather than using a one-click script to complete the entire process. This can make the entire process easier to maintain.\n\n### 1. Generate LSIF file\n\nTools can be found in https://lsif.dev/ .\n\nYou will get a `dump.lsif` file after that.\n\n### 2. Run `srctx`\n\nDownload our prebuilt binaries from [release page](https://github.com/williamfzc/srctx/releases).\n\nFor example, diff from `HEAD~1` to `HEAD`:\n\n```bash\n./srctx diff \\\n  --before HEAD~1 \\\n  --after HEAD \\\n  --lsif dump.lsif \\\n  --outputCsv output.csv \\\n  --outputDot output.dot \\\n  --outputHtml output.html\n```\n\nSee details with `./srctx diff --help`.\n\n### Prefer a real world sample?\n\n[Our CI](https://github.com/williamfzc/srctx/blob/main/.github/workflows/ci.yml) is a good start.\n\n## Usage as Github Action (Recommendation)\n\nBecause LSIF files require dev env heavily, it's really hard to provide a universal solution in a single binary file for\nall the repos.\n\n\u003cimg width=\"697\" alt=\"image\" src=\"https://user-images.githubusercontent.com/13421694/236666915-5d403e4a-9cc1-4364-afbe-363cf82e5e49.png\"\u003e\n\nWe are currently working on [diffctx](https://github.com/williamfzc/diffctx), which will provide a GitHub Actions plugin\nthat allows users to use it directly in a Pull Request.\n\n## Usage as Lib\n\n### API\n\nThis API allows developers accessing the data of FuncGraph.\n\n- Start up example: [example/api_test.go](example/api_test.go)\n- Real world example: [cmd/srctx/diff/cmd.go](cmd/srctx/diff/cmd.go)\n\n### Low level API\n\nLow level API allows developers consuming LSIF file directly.\n\nSee [example/api_base_test.go](example/api_base_test.go) for details.\n\n# Correctness / Accuracy\n\n\u003cimg width=\"1159\" alt=\"image\" src=\"https://github.com/williamfzc/srctx/assets/13421694/6cfa72c2-787a-4ae6-8cef-e77c1985d307\"\u003e\n\nWe wanted it to provide detection capabilities as accurate as an IDE.\n\n# Roadmap\n\nSee [Roadmap Issue](https://github.com/williamfzc/srctx/issues/31).\n\n# Contribution\n\n[Issues and PRs](https://github.com/williamfzc/srctx/issues) are always welcome.\n\n# References\n\nLSIF is a standard format for persisted code analyzer output.\nToday, several companies are working to support its growth, including Sourcegraph and GitHub/Microsoft.\nThe LSIF defines a standard format for language servers or other programming tools to emit their knowledge about a code\nworkspace.\n\n- https://lsif.dev/\n- https://microsoft.github.io/language-server-protocol/overviews/lsif/overview/\n- https://code.visualstudio.com/blogs/2019/02/19/lsif#_how-to-get-started\n\n# Thanks\n\n- SCIP/LSIF toolchains from https://github.com/sourcegraph\n- LSIF from Microsoft\n- LSIF parser from GitLab\n- IDE support from JetBrains\n\n# License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamfzc%2Fsrctx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamfzc%2Fsrctx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamfzc%2Fsrctx/lists"}