{"id":30104206,"url":"https://github.com/squareslab/codealign","last_synced_at":"2026-02-27T04:05:17.516Z","repository":{"id":277243016,"uuid":"923810501","full_name":"squaresLab/codealign","owner":"squaresLab","description":"A tool for finding instruction-level equivalence between two functions.","archived":false,"fork":false,"pushed_at":"2025-08-26T15:56:00.000Z","size":99,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-26T19:38:35.459Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/squaresLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-01-28T21:26:55.000Z","updated_at":"2025-08-26T15:56:04.000Z","dependencies_parsed_at":"2025-08-09T22:31:18.322Z","dependency_job_id":"f4da04b3-422c-4829-9b10-c74608e6852f","html_url":"https://github.com/squaresLab/codealign","commit_stats":null,"previous_names":["squareslab/codealign"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/squaresLab/codealign","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2Fcodealign","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2Fcodealign/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2Fcodealign/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2Fcodealign/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/squaresLab","download_url":"https://codeload.github.com/squaresLab/codealign/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2Fcodealign/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29884515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"online","status_checked_at":"2026-02-27T02:00:06.759Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-08-09T22:31:08.387Z","updated_at":"2026-02-27T04:05:17.510Z","avatar_url":"https://github.com/squaresLab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\nCodealign is a tool for evaluating neural decompilers that computes equivalence between two input functions at the instruction level.\nThe intended use case is comparing the predictions of a neural decompiler with a reference correct answer like the original source code.\n\nThis work was introduced in [Fast, Fine-Grained Equivalence Checking for Neural Decompilers](https://arxiv.org/abs/2501.04811)\n\nFor the artifacts used to evaluate Codealign, see the [companion evaluation repository](https://github.com/squaresLab/codealigneval).\n\n# Installation\n\nCodealign is a python package.\n```\ngit clone https://github.com/squaresLab/codealign.git\ncd codealign\npip install .\n```\nthen optionally\n```\npython -m unittest\n```\n\n# Usage\n\n```python\nfrom codealign import align, Alignment\n\nprediction = \"\"\"\nint write_response(int fd, char *buf, int len) {\n\tint\ti;\n\tfor (i = 0; i \u003c len; i += len) {\n\t\tif ((i = write(fd, buf + i, len - i)) \u003c= 0)\n\t\t\treturn 0;\n\t}\n    return 1;\n}\n\"\"\"\n\nreference = \"\"\"\nint write_response(int fd, char *response, int len) {\n\tint\tretval;\n\tint\tbyteswritten = 0;\n\twhile (byteswritten \u003c len) {\n\t\tretval = write(fd, response + byteswritten, len - byteswritten);\n\t\tif (retval \u003c= 0) {\n\t\t\treturn 0;\n\t\t}\n        byteswritten += retval;\n\t}\n    return 1;\n}\n\"\"\"\n\nalignment: Alignment = align(prediction, reference, 'c', partial_loops=True)\n\nprint(alignment)\n```\nWill yield\n```\nAlignment(candidate=write_response, reference=write_response)\n\n  %1 = phi 0 %7\n  %1 = phi 0 %8\n\n  %2 = \u003c %1 len\n  %3 = \u003c %1 len\n\n  loop %2\n  loop %3\n\n  %7 = + %5 len\n\n  %3 = + buf %1\n  %4 = + response %1\n\n  %4 = - len %1\n  %5 = - len %1\n\n  %5 = write(fd, %3, %4)\n  %6 = write(fd, %4, %5)\n\n  %6 = \u003c= %5 0\n  %7 = \u003c= %6 0\n\n  if %6\n  if %7\n\n  return 0\n  return 0\n\n  return 1\n  return 1\n\n  %8 = + %1 %6\n```\nEquivalent instructions are grouped together.\n\nAlignment objects and be interacted with programmatically via several methods.\n#### IR representations\n```python\nalignment.candidate_ir\nalignment.reference_ir\n```\nThese allow for access to individual functions in terms of codealign's internal representation.\n\n#### Alignment List Representation\n```python\nalignment.alignment_list\n```\nRepresents the alignment as pairs of instructions in the order `(candidate_instruction, reference_instruction)`.\nIf an instruction does not align with anything the corresponding value will be `None`.\nExcept in injective mode, an instruction can occur in more than one pair if it aligns with multiple other instructions.\n\n#### Alignment Lookup Representation\n```python\nalignment[instruction] # read-only\n```\nReturns the instruction(s) with which a given instruction is aligned.\nInstructions in codealign IR can be found in the `.candidate_ir` and `.reference_ir` attributes.\n\n\n## Object Model\n\nCodealign describes code in term of an internal object model.\nThese can be imported from `codealign.ir`.\nThe codealign object model includes, but is not limited to\n- `Function`\n- `BasicBlock`\n- `SSAOperator`\n- `VarOperator`\n- `Variable`\n\n#### Accessing the Original AST\nWhere possible, codealign provides references to the `tree-sitter` AST nodes from which a given instruction was derived.\nTo access this, use\n```\nfrom codealign.ir import SSAOperator\ninstruction: SSAOperator\ninstruction.ast_node\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquareslab%2Fcodealign","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquareslab%2Fcodealign","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquareslab%2Fcodealign/lists"}