Code architecture

{ #dev-architecture-code }

Stable ID: ARCH-CODE

  1. We have chosen Python as the programming language for our implementation.

    1. We have chosen the latest released version, currently 3.14, and when a new version is released we intend to follow within three months, given that resources permit.

    2. We have chosen to use typing on all functions and their parameters. We use pyright as type checker.

    3. Our code should adhere to the conventions of Python, such as philosophy, style, and documentation. We use ruff as code formatter and linter.

  2. We enable analyses purely based on the AST as being insensitive to layout and comments signanficantly simplifies the development and maintenance of these analyses.

  3. We do not limit analyses and transformations to the AST, as knowledge about the token and trivia is often also needed.

  4. We defined AST Node as a Protocol (a.k.a. statically duck typing), with basic functionality and a back door: get_original_node to obtain the AST node as provided by the parser.

  5. AST Nodes are read only and immutable.

  6. AST Nodes are navigable, so parent must be present (except for the ATU / top node) and children are always present (although it might be an empty list).

  7. Standard 'semantic' functions must be provided that when given a code snippet will return the variables read or written. Based on the output of these functions dependencies between code snippets are determined.

  8. We enable syntax pattern matching and semantic filtering, see the Find, Filter, and Modify steps for details. In most cases, standard filter functions (as describe before) are enough, but we enable user specific filter functions that access the original AST.

  9. We collect multiple transformations, we are syntax aware - to handle shared text boundaries, and then in one step rewrite the code text.

  10. For general purpose, we don't mandate that the final text should be parsable. When chaining changes, all intermediate texts must be parsable - in case of transpilation, different parsers can be involved.

  11. The project is kept as a single repository (archive), rather than being split into separate repositories per component, so that users and contributors have one place to clone, install, and version, instead of having to discover and align several small repositories.

    1. Layers that are meant to be extended by third parties (currently: parser integrations, under src/renaissance/integrations/) use an extendable directory structure: one subdirectory per contribution (e.g., one per parser), added alongside the existing ones without modifying the core or other contributions.

    2. A contribution subdirectory may carry its own license, distinct from the repository's overall license (via a LICENSE file and/or SPDX headers scoped to that subdirectory) - e.g., for an integration that wraps a GPL or proprietary parser.

    3. See ADR 14 for the full rationale and the directory layout (renaissance core, integrations/<parser>, recipes/<language>, rejuvenation/<language>).