Ruff ann

.github/workflows/docs-quality.yml

@@ -24,8 +24,9 @@ jobs:
         run: uv run python tools/check_doc_images_policy.py
       - name: Check spelling
         run: uv run codespell ./docs
+      # pymarkdown has no configuration key for path exclusions, so .venv must be excluded on the command line.
       - name: Lint markdown
-        run: uv run pymarkdown scan -r ./docs
+        run: uv run pymarkdown scan -r --respect-gitignore .
 
   ci-passed:
     name: Docs CI passed

CHANGELOG.md

@@ -1,21 +1,21 @@
-## Breaking changes
+# Change Log
 
-- Removed the nominal AST hierarchy in `renaissance.integrations.types`, including `ast_type`, `KIND_MAP`, and class-based kind finder APIs.
-- Use `NodeProtocol`, `SemanticKind`, `PatternKind`, `parser_kind`, and parser-local predicates instead.
+## Breaking changes
 
-Plan for next sprints:
+* Removed the nominal AST hierarchy in `renaissance.integrations.types`, including `ast_type`, `KIND_MAP`, and class-based kind finder APIs.
+* Use `NodeProtocol`, `SemanticKind`, `PatternKind`, `parser_kind`, and parser-local predicates instead.
 
+## Plan for next sprints
 
 11-05-2026
 
 * [X] use type hierarchy to find type concisely instead of regexp
 * [X] use hypothesis instead of parameterized test to get better coverage
 * [X] convert more complex cases of TAUT test case and reviewed the conversion by Harry
-* [X] restructure with root namespace so that it can be packaged 
+* [X] restructure with root namespace so that it can be packaged
 * [X] apply ASTProtocol to Python and ~~Clang Node~~
 * [X] add ADR and set up ADR discussion process
 * [X] update test to pytest using python refactoring
 * [X] created a package with callable cli
 * [X] expand matcher and other utils to use lst nodes
 * [X] convert simple case of TAUT test case and reviewed the conversion by Harry
-

CLA.md

@@ -6,65 +6,65 @@ By submitting any Contribution to this Project, you agree to the following terms
 
 1. Definitions
 
-   "Project" means the software project maintained by the Maintainer.
+    "Project" means the software project maintained by the Maintainer.
 
-   "Maintainer" means the copyright holder(s) and any entity designated by them to manage the Project.
+    "Maintainer" means the copyright holder(s) and any entity designated by them to manage the Project.
 
-   "Contribution" means any source code, object code, documentation, configuration files, test material, designs,
-  bug fixes, enhancements, or other material intentionally submitted to the Project.
+    "Contribution" means any source code, object code, documentation, configuration files, test material, designs,
+    bug fixes, enhancements, or other material intentionally submitted to the Project.
 
 2. Authority
 
-   You represent and warrant that:
+    You represent and warrant that:
 
-   (a) you are the sole author of the Contribution, or otherwise have sufficient rights to grant the permissions described in this Agreement;
+    (a) you are the sole author of the Contribution, or otherwise have sufficient rights to grant the permissions described in this Agreement;
 
-   (b) the Contribution does not knowingly infringe any third-party intellectual property rights; and
+    (b) the Contribution does not knowingly infringe any third-party intellectual property rights; and
 
-   (c) you are legally entitled to enter into this Agreement.
+    (c) you are legally entitled to enter into this Agreement.
 
 3. Contribution License
 
-   You agree that all Contributions are submitted under either:
-   - the MIT License; or
-   - the BSD 3-Clause License.
+    You agree that all Contributions are submitted under either:
+    - the MIT License; or
+    - the BSD 3-Clause License.
 
-   By submitting a Contribution, you grant the Maintainer a perpetual, worldwide, non-exclusive, irrevocable,
-   royalty-free license to use, reproduce, modify, prepare derivative works of, publicly display, publicly perform,
-   sublicense, distribute, and otherwise exploit the Contribution.
+    By submitting a Contribution, you grant the Maintainer a perpetual, worldwide, non-exclusive, irrevocable,
+    royalty-free license to use, reproduce, modify, prepare derivative works of, publicly display, publicly perform,
+    sublicense, distribute, and otherwise exploit the Contribution.
 
 4. Right to Re-License
 
-   You expressly agree that the Maintainer may:
+    You expressly agree that the Maintainer may:
 
-   (a) distribute the Contribution as part of the Project under the Eclipse Public License 2.0 (EPL-2.0);
+    (a) distribute the Contribution as part of the Project under the Eclipse Public License 2.0 (EPL-2.0);
 
-   (b) distribute the Contribution under any future version of the EPL;
+    (b) distribute the Contribution under any future version of the EPL;
 
-   (c) distribute the Contribution under any other open source license; and
+    (c) distribute the Contribution under any other open source license; and
 
-   (d) distribute, license, sublicense, or otherwise exploit the Contribution under commercial, proprietary,
-   closed-source, or other licensing terms.
+    (d) distribute, license, sublicense, or otherwise exploit the Contribution under commercial, proprietary,
+    closed-source, or other licensing terms.
 
-   No additional permission from the Contributor shall be required for such licensing activities.
+    No additional permission from the Contributor shall be required for such licensing activities.
 
 5. Retention of Copyright
 
-   Except for the rights granted under this Agreement, ownership of copyright in the Contribution remains with the Contributor.
+    Except for the rights granted under this Agreement, ownership of copyright in the Contribution remains with the Contributor.
 
 6. No Obligation
 
-   Nothing in this Agreement obligates the Maintainer to use, distribute, or accept any Contribution.
+    Nothing in this Agreement obligates the Maintainer to use, distribute, or accept any Contribution.
 
 7. Disclaimer
 
-   The Contribution is provided "AS IS", without warranties or conditions of any kind, express or implied,
-   including without limitation any warranties of merchantability, fitness for a particular purpose, title,
-   or non-infringement.
+    The Contribution is provided "AS IS", without warranties or conditions of any kind, express or implied,
+    including without limitation any warranties of merchantability, fitness for a particular purpose, title,
+    or non-infringement.
 
 8. Governing Law
 
-   This Agreement shall be governed by the substantive laws of the Netherlands.
+    This Agreement shall be governed by the substantive laws of the Netherlands.
 
-   By submitting a Contribution to the Project, you acknowledge that you have read and
-   agree to the terms of this Agreement.
+    By submitting a Contribution to the Project, you acknowledge that you have read and
+    agree to the terms of this Agreement.

README.md

@@ -37,78 +37,117 @@ Contributions that are subject to additional restrictions or incompatible licens
 
 This project is experimental in nature and aims to explore
 various concepts and techniques to apply renaissance pattern matching
-in a generic way using multiple abstract syntax trees. 
+in a generic way using multiple abstract syntax trees.
+
+## Prerequisites
+
+The Python dependencies, including the pinned `libclang` library used by `ClangASTNode`, are installed by `uv sync`.
+
+The `clang` compiler driver is a separate, external requirement: `ClangJsonASTNode` runs it as a subprocess to obtain a JSON AST dump.
+It should have the same LLVM major version as the bundled library. Print the version to install:
+
+```powershell
+uv run python -c "from importlib.metadata import version; print('.'.join(version('libclang-ng').split('.')[:3]))"
+```
+
+Then install that version. `winget` requires the exact version, while the other installers take the major version:
+
+```powershell
+winget install LLVM.LLVM --version 22.1.4
+```
+
+```bash
+# Debian, Ubuntu, or WSL
+wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 22
+```
 
-## Setup for WSL
 ```bash
-sudo apt-get install -y build-essential clang
+# macOS
+brew install llvm@22
 ```
 
+Open a new terminal and check that `clang --version` reports the expected version.
+On Windows the installer does not add LLVM to `PATH`, so add `C:\Program Files\LLVM\bin` to it yourself.
+See [Clang prerequisites](docs/developer/modules/parser-and-ast.md#clang-prerequisites) for selecting a specific driver
+when it is not on `PATH`.
 
 The code for the experiments is located in the [src](./src) folder.
 
-# Description
+## Description
+
 This project is a generic approach to refactor code bases with a generic AST structure.
 It uses `TNO Renaissance` pattern matching.
 Currently, clang native and clang python bindings are supported.
 
-# How to add a different binding
+## How to add a different binding
+
 You'll need to implement a concrete class for syntax_tree.ASTNode.
 Follow the implementations of `ClangASTNode` and `ClangJsonASTNode` as an example.
 If the concrete AST has a different language then also a `PatternFactory` must be added. See `CPatternFactory` for inspiration.
 
 ## Installation Procedure
-To install the necessary dependencies, follow these steps:
 
-1. **Run the Installation Script**
-    - Navigate to the project directory.
-    - Execute the `install.bat` script by double-clicking it or running the following command in the terminal:
-      ```sh
-      ./install.bat
-      ```
+The project is managed with [uv](https://docs.astral.sh/uv/). From the project directory:
+
+```sh
+uv sync --group dev
+```
+
+This creates the virtual environment, installs the interpreter pinned by `requires-python`, and installs the development tools.
 
 ## Configuration and Verification
 
-1. **Configure the Environment**
-    - Open Visual Studio Code (VSCode).
-    - Ensure that the Python extension is installed.
-    - Open the project folder in VSCode.
-    - alternatively in shell goto <root>/python folder and
-      ```sh
-      code .
-      ```
+Two steps are needed.
+By following these steps, you will have configured, installed, and verified the installation for the project.
+
+### Configure the Environment
+
+- Open Visual Studio Code (VSCode).
+- Ensure that the Python extension is installed.
+- Open the project folder in VSCode, or run the following command in the project directory:
+
+  ```sh
+  code .
+  ```
 
-2. **Verify the Installation**
-    - Open the integrated terminal in VSCode.
-    - Run the following command to execute the tests:
-      ```sh
-      python -m unittest discover
-      ```
-    - Check the output to ensure all tests pass successfully.
+- Select the interpreter from the `.venv` directory.
 
-By following these steps, you will have installed and verified the setup for the project.
+### Verify the Installation
 
+- Open the integrated terminal in VSCode.
+- Run the following command to execute the tests:
+
+  ```sh
+  uv run pytest
+  ```
+
+- Check the output to ensure all tests pass successfully.
+  Failing `clang_json` tests indicate that the `clang` driver is missing from `PATH`; see [Prerequisites](#prerequisites).
 
 ## TODO
 
 An incomplete list of todo's:
 
-* The get_properties methods of both `ClangASTNode` and `ClangJsonASTNode` are not complete yet. This might cause mismatches in the `Match_Finder`
-* C++ constructs have not been tested yet
-* An example of how to use includes in a `Pattern` must be added
-* Tests need to be added for macro handling
-* The methods `get_references` and `referred_by` must be added to `ASTNode` and implemented in the concrete classes
-* Test cases for multiple match patterns need to be added. Currently, there is only one working case in the examples
-* Comments in Clang appear incorrectly in the `ASTShower`. This seems to be a Clang issue, which is surprising
+- The get_properties methods of both `ClangASTNode` and `ClangJsonASTNode` are not complete yet. This might cause mismatches in the `Match_Finder`
+- C++ constructs have not been tested yet
+- An example of how to use includes in a `Pattern` must be added
+- Tests need to be added for macro handling
+- The methods `get_references` and `referred_by` must be added to `ASTNode` and implemented in the concrete classes
+- Test cases for multiple match patterns need to be added. Currently, there is only one working case in the examples
+- Comments in Clang appear incorrectly in the `ASTShower`. This seems to be a Clang issue, which is surprising
 
 ## Usage
 
+```bash
 cli <command> <src> <other-args>
+```
 
 ### Inspect
 
 Inspect the AST of a source file.
+
 ```bash
 cli inspect features/targets/demo.py pass
 ```
+
 it will show ast of demo.py and focus on 'pass' statements