{"id":13472405,"url":"https://github.com/scottrogowski/code2flow","last_synced_at":"2025-05-14T00:09:37.471Z","repository":{"id":37430834,"uuid":"10259118","full_name":"scottrogowski/code2flow","owner":"scottrogowski","description":"Pretty good call graphs for dynamic languages","archived":false,"fork":false,"pushed_at":"2024-06-21T13:15:25.000Z","size":4055,"stargazers_count":4262,"open_issues_count":33,"forks_count":315,"subscribers_count":79,"default_branch":"master","last_synced_at":"2025-05-11T12:20:32.250Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/scottrogowski.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"scottrogowski"}},"created_at":"2013-05-24T04:17:43.000Z","updated_at":"2025-05-11T06:52:03.000Z","dependencies_parsed_at":"2024-04-28T01:51:35.044Z","dependency_job_id":"3aa8925e-4aff-4998-9583-8356d68d3377","html_url":"https://github.com/scottrogowski/code2flow","commit_stats":{"total_commits":121,"total_committers":11,"mean_commits":11.0,"dds":"0.14876033057851235","last_synced_commit":"c2c22afe5e12f969cc256373bf8f4eec592dc762"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottrogowski%2Fcode2flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottrogowski%2Fcode2flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottrogowski%2Fcode2flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottrogowski%2Fcode2flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottrogowski","download_url":"https://codeload.github.com/scottrogowski/code2flow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254044189,"owners_count":22005099,"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":[],"created_at":"2024-07-31T16:00:54.411Z","updated_at":"2025-05-14T00:09:32.461Z","avatar_url":"https://github.com/scottrogowski.png","language":"Python","readme":"![code2flow logo](https://raw.githubusercontent.com/scottrogowski/code2flow/master/assets/code2flowlogo.png)\n\n![Version 2.5.1](https://img.shields.io/badge/version-2.5.1-brightgreen) ![Build passing](https://img.shields.io/badge/build-passing-brightgreen) ![Coverage 100%](https://img.shields.io/badge/coverage-100%25-brightgreen) ![License MIT](https://img.shields.io/badge/license-MIT-green])\n\nCode2flow generates [call graphs](https://en.wikipedia.org/wiki/Call_graph) for dynamic programming language. Code2flow supports Python, JavaScript, Ruby, and PHP.\n\nThe basic algorithm is simple:\n\n1. Translate your source files into ASTs.\n1. Find all function definitions.\n1. Determine where those functions are called.\n1. Connect the dots.\n\nCode2flow is useful for:\n- Untangling spaghetti code.\n- Identifying orphaned functions.\n- Getting new developers up to speed.\n\nCode2flow provides a *pretty good estimate* of your project's structure. No algorithm can generate a perfect call graph for a [dynamic language](https://en.wikipedia.org/wiki/Dynamic_programming_language) – even less so if that language is [duck-typed](https://en.wikipedia.org/wiki/Duck_typing). See the known limitations in the section below.\n\n*(Below: Code2flow running against a subset of itself `code2flow code2flow/engine.py code2flow/python.py --target-function=code2flow --downstream-depth=3`)*\n\n![code2flow running against a subset of itself](https://raw.githubusercontent.com/scottrogowski/code2flow/master/assets/code2flow_output.png)\n\nInstallation\n------------\n\n```bash\npip3 install code2flow\n```\n\nIf you don't have it already, you will also need to install graphviz. Installation instructions can be found [here](https://graphviz.org/download/).\n\nAdditionally, depending on the language you want to parse, you may need to install additional dependencies:\n- JavaScript: [Acorn](https://www.npmjs.com/package/acorn)\n- Ruby: [Parser](https://github.com/whitequark/parser)\n- PHP: [PHP-Parser](https://github.com/nikic/PHP-Parser)\n- Python: No extra dependencies needed\n\nUsage\n-----\n\nTo generate a DOT file, run something like:\n\n```bash\ncode2flow mypythonfile.py\n```\n\nOr, for Javascript:\n\n```bash\ncode2flow myjavascriptfile.js\n```\n\nYou can specify multiple files or import directories:\n\n```bash\ncode2flow project/directory/source_a.js project/directory/source_b.js\n```\n\n```bash\ncode2flow project/directory/*.js\n```\n\n```bash\ncode2flow project/directory --language js\n```\n\nTo pull out a subset of the graph, try something like:\n\n```bash\ncode2flow mypythonfile.py --target-function my_func --upstream-depth=1 --downstream-depth=1\n```\n\n\nThere are a ton of command line options, to see them all, run:\n\n```bash\ncode2flow --help\n```\n\nHow code2flow works\n------------\n\nCode2flow approximates the structure of projects in dynamic languages. It is *not possible* to generate a perfect callgraph for a dynamic language.\n\nDetailed algorithm:\n\n1. Generate an AST of the source code\n2. Recursively separate groups and nodes. Groups are files, modules, or classes. More precisely, groups are namespaces where functions live. Nodes are the functions themselves.\n3. For all nodes, identify function calls in those nodes.\n4. For all nodes, identify in-scope variables. Attempt to connect those variables to specific nodes and groups. This is where there is some ambiguity in the algorithm because it is impossible to know the types of variables in dynamic languages. So, instead, heuristics must be used.\n5. For all calls in all nodes, attempt to find a match from the in-scope variables. This will be an edge.\n6. If a definitive match from in-scope variables cannot be found, attempt to find a single match from all other groups and nodes.\n7. Trim orphaned nodes and groups.\n8. Output results.\n\nWhy is it impossible to generate a perfect call graph?\n----------------\n\nConsider this toy example in Python\n```python\ndef func_factory(param):\n    if param \u003c .5:\n        return func_a\n    else:\n        return func_b\n\nfunc = func_factory(important_variable)\nfunc()\n```\n\nWe have no way of knowing whether `func` will point to `func_a` or `func_b` until runtime. In practice, ambiguity like this is common and is present in most non-trivial applications.\n\nKnown limitations\n-----------------\n\nCode2flow is internally powered by ASTs. Most limitations stem from a token not being named what code2flow expects it to be named.\n\n* All functions without definitions are skipped. This most often happens when a file is not included.\n* Functions with identical names in different namespaces are (loudly) skipped. E.g. If you have two classes with identically named methods, code2flow cannot distinguish between these and skips them.\n* Imported functions from outside your project directory (including from standard libraries) which share names with your defined functions may not be handled correctly. Instead, when you call the imported function, code2flow will link to your local functions. For example, if you have a function `search()` and call, `import searcher; searcher.search()`, code2flow may link (incorrectly) to your defined function.\n* Anonymous or generated functions are skipped. This includes lambdas and factories.\n* If a function is renamed, either explicitly or by being passed around as a parameter, it will be skipped.\n\n\nAs an imported library\n-----------------\n\nYou can work with code2flow as an imported Python library in much the same way as you work with it\nfrom the CLI.\n\n```python\nimport code2flow\ncode2flow.code2flow(['path/to/filea', 'path/to/fileb'], 'path/to/outputfile')\n```\n\nThe keyword arguments to `code2flow.code2flow` are roughly the same as the CLI\nparameters. To see all available parameters, refer to the code2flow function in [engine.py](https://github.com/scottrogowski/code2flow/blob/master/code2flow/engine.py).\n\n\nHow to contribute\n-----------------------\n\n1. **Open an issue**: Code2flow is not perfect and there is a lot that can be improved. If you find a problem parsing your source that you can identify with a simplified example, please open an issue.\n2. **Create a PR**: Even better, if you have a fix for the issue you identified that passes unit tests, please open a PR.\n3. **Add a language**: While dense, each language implementation is between 250-400 lines of code including comments. If you want to implement another language, the existing implementations can be your guide.\n\n\nUnit tests\n------------------\n\nTest coverage is 100%. To run:\n\n```bash\n    pip install -r requirements_dev.txt\n    make test\n```\n\nLicense\n-----------------------------\n\nCode2flow is licensed under the MIT license.\nPrior to the rewrite in April 2021, code2flow was licensed under LGPL. The last commit under that license was 24b2cb854c6a872ba6e17409fbddb6659bf64d4c.\nThe April 2021 rewrite was substantial, so it's probably reasonable to treat code2flow as completely MIT-licensed.\n\n\nAcknowledgements\n-----------------------------\n\n\n* In mid 2021, Code2flow was rewritten, and two new languages were added. This was prompted and financially supported by the [Sider Corporation](https://siderlabs.com/).\n* The code2flow pip name was graciously transferred to this project from [Dheeraj Nair](https://github.com/Dheeraj1998). He was using it for his own (unrelated) [code2flow](https://github.com/Dheeraj1998/code2flow) project.\n* Many others have contributed through bug fixes, cleanups, and identifying issues. Thank you!!!\n\n\nUnrelated projects\n-----------------------\n\nThe name, \"code2flow\", has been used for several unrelated projects. Specifically, the domain, code2flow.com, has no association with this project. I've never heard anything from them and it doesn't appear like they use anything from here.\n\n\nFeedback / Issues / Contact\n-----------------------------\n\nIf you have an issue using code2flow or a feature request, please post it in the issues tab. In general, I don't provide help over email. Answering a question publicly helps way more people. For everything else, please do email! scottmrogowski@gmail.com\n\n\nFeature Requests\n----------------\n\nEmail me. Usually, I'm spread thin across a lot of projects, so I will, unfortunately, turn down most requests. However, I am open to paid development for compelling features.\n","funding_links":["https://github.com/sponsors/scottrogowski"],"categories":["Code Analysis","Python","资源列表","JavaScript","代码分析和 Lint 工具","Code Analysis and Linter","代码分析","others","Code Analysis [🔝](#readme)","Awesome Python"],"sub_categories":["代码分析和 Lint 工具","Code Analysis"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottrogowski%2Fcode2flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottrogowski%2Fcode2flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottrogowski%2Fcode2flow/lists"}