inclean 0.1.0__tar.gz

inclean-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,199 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - v*.*.*
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  CARGO_TERM_COLOR: always
+  BIN_NAME: inclean
+
+jobs:
+  check-tag:
+    name: validate SemVer tag
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: validate tag format and Cargo.toml version match
+        shell: bash
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          # SemVer 2.0.0 with required leading "v":
+          # vMAJOR.MINOR.PATCH[-prerelease][+build]
+          semver_re='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\+([0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*))?$'
+          if [[ ! "$REF_NAME" =~ $semver_re ]]; then
+            echo "::error::tag '$REF_NAME' is not valid SemVer (expected vMAJOR.MINOR.PATCH[-prerelease][+build])"
+            exit 1
+          fi
+
+          tag_version="${REF_NAME#v}"
+          cargo_version=$(awk -F'"' '/^version = "/ { print $2; exit }' Cargo.toml)
+
+          if [[ -z "$cargo_version" ]]; then
+            echo "::error::could not extract version from Cargo.toml"
+            exit 1
+          fi
+
+          if [[ "$tag_version" != "$cargo_version" ]]; then
+            echo "::error::tag version '$tag_version' does not match Cargo.toml version '$cargo_version' — bump Cargo.toml before tagging"
+            exit 1
+          fi
+
+          echo "tag '$REF_NAME' matches Cargo.toml version '$cargo_version'"
+
+  verify:
+    needs: check-tag
+    name: verify
+    uses: ./.github/workflows/test.yml
+
+  publish-crate:
+    name: publish to crates.io
+    needs: [verify, check-tag]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: cargo publish
+        run: cargo publish --token "${{ secrets.CARGO_REGISTRY_TOKEN }}"
+
+  build:
+    name: build ${{ matrix.triple }}
+    needs: [verify, check-tag]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64
+            triple: x86_64-unknown-linux-gnu
+            archive: tar.gz
+          - os: ubuntu-latest
+            target: aarch64
+            triple: aarch64-unknown-linux-gnu
+            archive: tar.gz
+          - os: macos-latest
+            target: x86_64
+            triple: x86_64-apple-darwin
+            archive: tar.gz
+          - os: macos-latest
+            target: aarch64
+            triple: aarch64-apple-darwin
+            archive: tar.gz
+          - os: windows-latest
+            target: x64
+            triple: x86_64-pc-windows-msvc
+            archive: zip
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          manylinux: auto
+          sccache: "true"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.triple }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+      - name: package binary (tar.gz)
+        if: matrix.archive == 'tar.gz'
+        shell: bash
+        run: |
+          set -euo pipefail
+          stage="${BIN_NAME}-${{ matrix.triple }}"
+          mkdir -p "bins/${stage}"
+          cp "target/${{ matrix.triple }}/release/${BIN_NAME}" "bins/${stage}/"
+          cp README.md LICENSE "bins/${stage}/"
+          tar -czf "bins/${stage}.tar.gz" -C bins "${stage}"
+          rm -rf "bins/${stage}"
+
+      - name: package binary (zip)
+        if: matrix.archive == 'zip'
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $stage = "$env:BIN_NAME-${{ matrix.triple }}"
+          New-Item -ItemType Directory -Force -Path "bins/$stage" | Out-Null
+          Copy-Item "target/${{ matrix.triple }}/release/$env:BIN_NAME.exe" "bins/$stage/"
+          Copy-Item README.md, LICENSE "bins/$stage/"
+          Compress-Archive -Path "bins/$stage/*" -DestinationPath "bins/$stage.zip"
+          Remove-Item -Recurse -Force "bins/$stage"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: bins-${{ matrix.triple }}
+          path: bins/*
+          if-no-files-found: error
+
+  sdist:
+    name: sdist
+    needs: [verify, check-tag]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  gh-release:
+    name: create GitHub Release
+    needs: [build, publish-crate]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: bins-*
+          path: dist
+          merge-multiple: true
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          fail_on_unmatched_files: true

inclean-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,56 @@
+name: test
+
+on:
+  workflow_call:
+  pull_request:
+    paths-ignore: &non-src-code-paths
+      - "**/*.md"
+      - "LICENSE"
+      - ".gitignore"
+  push:
+    branches: [main]
+    paths-ignore: *non-src-code-paths
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -D warnings
+
+jobs:
+  lint:
+    name: fmt + clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: cargo fmt --check
+        run: cargo fmt --all -- --check
+
+      - name: cargo clippy
+        run: cargo clippy --all-targets --all-features
+
+  test:
+    needs: lint
+    name: test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: cargo test
+        run: cargo test --all-features

inclean-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+### OS files
+.DS_Store
+Thumbs.db
+*:Zone.Identifier
+
+### Editor files
+.idea/
+.vscode/
+.claude/
+
+### Build artifacts
+/target

inclean-0.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- **Breaking:** `trailing_comment` schema redesigned to mirror include
+  action handling. The four `policy` values (`prepend` / `append` /
+  `replace` / `fill_if_absent`) and the `text` field are gone; the new
+  shape is `{ match, to, form, spacing }` where `match` is a regex
+  over the stripped existing comment body, `to` is the new comment
+  body template (with new `${comment.N}` / `${comment.text}`
+  placeholders), `form` switches between `"line"` / `"block"` /
+  `"preserve"`, and `spacing` controls the gutter before the
+  delimiter. `to = ""` removes the trailing comment entirely. See
+  `docs/configuration.md` for the migration table and the idempotent
+  prepend / append idioms in the Rust `regex` dialect.
+
+## [0.1.0] — 2026-05-21
+
+Initial release. Feature-complete for v1.
+
+### Added
+
+- Hierarchical `inclean.toml` configuration: one root config plus
+  optional sub-directory configs.
+- Pure rule tree with single inheritance via `extends`; globally unique
+  rule names; AND-combined field merge at match time.
+- Five-layer matching engine: `paths`, `extensions`, `forms`, `match`
+  (layer-4 regex on stripped include content), and `match_resolved`
+  (layer-5 constraint on the resolved physical file with ambiguity
+  detection against `original_include_dirs`).
+- `@std.*` built-in constants for C/C++ extensions and standard
+  headers (C89–C23, C++98–C++23), with list-spread and `_or`
+  regex-alternation forms.
+- Four action types: `auto` (resolve + relativize against
+  `allowed_include_dirs` or the source file's directory), `rewrite`,
+  `keep`, `error`. `${...}` placeholder substitution including
+  `${resolved.*}` for layer-5 matches.
+- Rule-tree invariant enforcement at source-scan time:
+  `child ⊆ parent` and cross-chain disjointness, reported per-include.
+- Post-action `allowed_include_dirs` validation; empty list is the
+  explicit opt-out for system-header rules.
+- Five CLI subcommands: `init`, `check` (three-level via
+  `-l/--level config|rules|full`), `diff`, `apply`, `explain`.
+- Per-file processing parallelized with `rayon`; deterministic output
+  via post-sort.
+- Distinct exit codes: `0` clean, `2` user-defined `action.error`,
+  `3` for any of rule-tree conflict, layer-5 ambiguity, action
+  evaluation failure, or `allowed_include_dirs` validation failure.
+
+[Unreleased]: https://example.com/compare/0.1.0...HEAD
+[0.1.0]: https://example.com/releases/0.1.0

inclean-0.1.0/CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md — Notes for Claude Code working in this repo
+
+## What this project is
+
+inclean is a Rust CLI that rewrites `#include` directives in C/C++ source
+trees so the library can be consumed with a clean, minimal `-I` list. The
+canonical use case: take an old library whose internal source uses
+`#include "bar.h"` (resolving via `-Isrc/internal`) and rewrite every
+such line so the consumer only needs `-Ipath/to/lib/include`.
+
+For the module map and pipeline narrative, see
+[docs/architecture.md](docs/architecture.md); for the full `inclean.toml`
+schema (layers, actions, placeholders, `@std.*` constants), see
+[docs/configuration.md](docs/configuration.md). This file keeps only
+Claude-facing guidance.
+
+## Design source of truth
+
+The original design plan lives in
+`/home/inaku/.claude/plans/c-c-inclean-iterative-tome.md` (local to the
+maintainer's machine, not committed). Read it before making non-trivial
+changes. Key design choices that drive the code shape:
+
+- **Configuration**: TOML, hierarchical (`inclean.toml` at project root,
+  optional `inclean.toml` in any sub-directory). The root config **must**
+  declare `[project]` with `root` set; sub-configs **must not** declare
+  `[project]` at all.
+- **Rule model**: pure rule tree with single inheritance via `extends`. Rule
+  `name` is globally unique across all configs in the project. There is
+  **no `[defaults]` block** — users write a `base` rule and others extend it.
+- **`[project]` block is minimal**: only `root`. Everything else
+  (`allowed_include_dirs`, `original_include_dirs`) lives on rules.
+- **Five-layer matching** (each layer has a default if unspecified):
+  1. `paths` — gitignore-style file globs
+  2. `extensions` — file extension filter (skipped if layer 1 is an exact path)
+  3. `forms` — set of `"quote"` / `"angle"` / `"macro"`; `"macro"` always errors in v1
+  4. `match` — regex on the stripped include content (no quotes/angles)
+  5. `match_resolved` — only runs when the rule sets it. Resolves the
+     include via `original_include_dirs` (must be unique — duplicate hits
+     surface as `Layer5Ambiguous` per-include, exit 3); then enforces
+     optional `under` (path-prefix) and `match` (path regex) constraints.
+     When layer 5 runs, the action gets `${resolved.path}` /
+     `${resolved.dir}` / `${resolved.basename}` placeholders.
+- **Inheritance semantics**: runtime AND-combination merges fields; the
+  rule-tree invariants ("child's match set ⊆ parent's" + "cross-chain
+  disjoint") are enforced at source-scan time by
+  `tree::check_chain(match_all(...))`. There is no static lint module —
+  the source-level check supersedes it (also covers layer-4 regex).
+- **Mode-dependent winner**: under `CheckMode::Full`, the action runs on
+  the deepest rule in the matched chain (the leaf), not the first-by-
+  declaration. This makes apply behavior independent of rule declaration
+  order.
+- **Action default**: `{ type = "auto", relative_to = "allowed", form = "quote" }`.
+- **`@std.*` built-in constants** (e.g. `@std.cpp.extensions`, `@std.cpp17.system_headers`)
+  spread in any string-list field via `@name` syntax.
+
+## Module layout & pipeline data flow
+
+Moved to [docs/architecture.md](docs/architecture.md). Read that doc
+for the per-module responsibilities, the six-step pipeline walkthrough
+inside `pipeline::run::run`, and the full list of `IncludeOutcome`
+variants and exit-code semantics.
+
+## Dev workflow
+
+```sh
+cargo check     # fast type-check
+cargo test      # unit + integration tests
+cargo clippy    # lints
+cargo fmt       # format
+```
+
+Integration fixtures live under `tests/fixtures/` (small fake libraries).
+Add a new fixture for any non-trivial behavior change.
+
+## Conventions
+
+- Use `anyhow::Result` for high-level error returns; `thiserror` for typed
+  errors at module boundaries.
+- Rule-set / config errors should pinpoint the offending `inclean.toml`
+  path and rule name in the message.
+- Keep `cli/*` files thin — they parse flags and call into `pipeline::run`.
+- The `auto` action requires the resolved file to live under one of the
+  matched rule's `allowed_include_dirs`; failure is a hard error and aborts
+  the file's apply.
+
+## Things to avoid
+
+- Don't introduce a `[defaults]` block or any project-level fallback for
+  `allowed_include_dirs` / `original_include_dirs`. The deliberate design
+  is "rule tree with explicit `base`".
+- Don't widen the rule subset invariant — child rules should never match
+  more than the parent.
+- Don't attempt to formally check regex containment for layer 4. Runtime
+  AND-combination is the enforcement; static lint covers layers 1/2/3 only.
+- Don't add file-moving, umbrella-header generation, or `extern "C"`
+  wrapping. Out of scope for v1.

inclean-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to inclean
+
+Thanks for your interest in inclean. This is a small project — the
+process is correspondingly light.
+
+## Toolchain
+
+- **Rust 1.91+** (2021 edition).
+- **`rustfmt`** and **`clippy`** — install via
+  `rustup component add rustfmt clippy` if your toolchain doesn't
+  already have them.
+
+No other system dependencies are required.
+
+## Build and test
+
+```sh
+cargo build                # debug build
+cargo check                # fast type-check
+cargo test                 # unit + integration tests
+cargo clippy --all-targets # lints
+cargo fmt                  # format
+```
+
+All four of `cargo test`, `cargo clippy --all-targets`, and
+`cargo fmt --check` should pass cleanly before a change is submitted.
+
+## Repository layout
+
+See [docs/architecture.md](docs/architecture.md) for the
+module-by-module map. In short:
+
+- `src/cli/*.rs` — clap subcommand handlers (thin).
+- `src/pipeline/run.rs` — the orchestrator that every subcommand
+  calls into.
+- `src/config/*`, `src/lex/*`, `src/rule/*`, `src/index/*`,
+  `src/validate/*` — the matching pipeline's building blocks.
+- `tests/integration.rs` + `tests/fixtures/` — end-to-end tests.
+
+## Adding a feature or fixing a bug
+
+1. **Add (or extend) a fixture.** If the change alters observable
+   behavior, add a tiny `inclean.toml` + source-file fixture under
+   `tests/fixtures/<name>/`. Fixtures should be the smallest possible
+   reproduction of the scenario you're testing.
+2. **Add an integration test** in `tests/integration.rs` that drives
+   the fixture and asserts on the outcome you care about (exit code,
+   conflicts, rewritten text).
+3. **Run `cargo test` + `cargo clippy --all-targets` + `cargo fmt`**
+   clean.
+4. **Open a PR** with a brief description of what changed and why.
+   Link the fixture/test that demonstrates the new behavior.
+
+## Code conventions
+
+- **Errors.** Use `anyhow::Result` for high-level errors and
+  `.with_context(…)` for I/O and parsing boundaries. `thiserror` is
+  reserved for future typed errors at internal module boundaries.
+- **Error messages.** When a config or rule-set error references a
+  specific rule or `inclean.toml` file, the message must include the
+  rule name and the source path so the user can locate the problem.
+- **CLI is thin.** `src/cli/*.rs` files parse flags and call
+  `pipeline::run`. Don't put pipeline logic in CLI handlers.
+- **Comments.** Default to none. Add one when the _why_ is non-
+  obvious: a hidden constraint, a subtle invariant, a workaround. Do
+  not narrate what code already says.
+- **No `unsafe`.** There is none today; keep it that way.
+
+## Things outside v1 scope
+
+These have been considered and explicitly excluded. Please discuss
+in an issue before submitting a PR for any of them:
+
+- A `[defaults]` block or any project-level fallback for
+  `allowed_include_dirs` / `original_include_dirs`. The deliberate
+  design is "rule tree with explicit `base`".
+- Widening the child-subset invariant. Child rules must never match
+  more than their parent.
+- Formally checking regex containment between layer-4 patterns.
+  Runtime AND-combination is the enforcement.
+- File-moving, umbrella-header generation, `extern "C"` wrapping,
+  or any other source transformation beyond `#include` rewriting.
+
+## Reporting bugs
+
+Open an issue with the smallest possible reproduction:
+
+- the offending `inclean.toml` (or its relevant rules),
+- a one-or-two-file source snippet,
+- what `inclean check` printed and what you expected.
+
+If the bug is in `cargo test`, please also include the test name and
+the output of `cargo test -- --nocapture <test_name>`.