Merge branch 'main' into geospatialStatsAndBboxMetadataSupport

Author: mghildiy

.claude/settings.local.json

@@ -118,7 +118,10 @@
       "Bash(git reset *)",
       "Bash(git ls-tree *)",
       "Bash(git fetch *)",
-      "Bash(gh label *)"
+      "Bash(gh label *)",
+      "Bash(git tag *)",
+      "Bash(git apply *)",
+      "Bash(gh run *)"
     ]
   }
 }

.github/workflows/docs-publish.yml

@@ -0,0 +1,61 @@
+#
+#  SPDX-License-Identifier: Apache-2.0
+#
+#  Copyright The original authors
+#
+#  Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+#
+
+name: Publish versioned documentation
+
+# Manual follow-up to a release: fires the publish-docs repository_dispatch
+# at the site repo for a specific version. Run this once any post-release
+# touch-ups (blog post link, errata) have landed on a `-docs` tag, so the
+# release tag itself stays immutable.
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Git ref to build from (tag, branch, or SHA — e.g. v1.0.0.Beta2-docs)'
+        required: true
+      version:
+        description: 'Version label on the site (e.g. 1.0.0.Beta2)'
+        required: true
+      update-latest:
+        description: 'Point the site''s "latest" alias at this version (uncheck for back-ports)'
+        required: true
+        type: boolean
+        default: true
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Resolve ref to a commit SHA'
+        id: resolve
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          REF: ${{ inputs.ref }}
+        run: |
+          SHA=$(gh api "repos/$GH_REPO/commits/$REF" --jq '.sha')
+          if [ -z "$SHA" ]; then
+            echo "Could not resolve $REF to a commit"
+            exit 1
+          fi
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+
+      - name: 'Fire repository_dispatch to site repo'
+        env:
+          GH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }}
+          SHA: ${{ steps.resolve.outputs.sha }}
+          VERSION: ${{ inputs.version }}
+          UPDATE_LATEST: ${{ inputs.update-latest }}
+        run: |
+          jq -n \
+            --arg ref "$SHA" \
+            --arg ver "$VERSION" \
+            --argjson latest "$UPDATE_LATEST" \
+            '{event_type: "publish-docs", client_payload: {source_ref: $ref, version: $ver, update_latest: $latest}}' \
+          | gh api repos/hardwood-hq/hardwood-hq.github.io/dispatches --input -

.github/workflows/docs-trigger.yml

@@ -8,9 +8,11 @@
 
 name: Trigger documentation publish
 
+# Refreshes the `dev` docs after a successful Main Build on main. Versioned
+# release docs are published manually via docs-publish.yml once any post-
+# release follow-ups (blog post link, etc.) have been added.
+
 on:
-  push:
-    tags: ['v*']
   workflow_run:
     workflows: [Main Build]
     types: [completed]
@@ -19,29 +21,15 @@ on:
 jobs:
   dispatch:
     runs-on: ubuntu-latest
-    if: >-
-      github.event_name == 'push'
-      || github.event.workflow_run.conclusion == 'success'
+    if: github.event.workflow_run.conclusion == 'success'
 
     steps:
       - name: Fire repository_dispatch to site repo
         env:
           GH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
         run: |
-          if [ "${{ github.event_name }}" = "push" ]; then
-            REF="${{ github.ref_name }}"
-            SHA="${{ github.sha }}"
-          else
-            REF="${{ github.event.workflow_run.head_branch }}"
-            SHA="${{ github.event.workflow_run.head_sha }}"
-          fi
-          if [[ "$REF" == v* ]]; then
-            VERSION_LABEL="${REF#v}"
-          else
-            VERSION_LABEL="dev"
-          fi
           jq -n \
             --arg ref "$SHA" \
-            --arg ver "$VERSION_LABEL" \
-            '{event_type: "publish-docs", client_payload: {source_ref: $ref, version: $ver, update_latest: true}}' \
+            '{event_type: "publish-docs", client_payload: {source_ref: $ref, version: "dev", update_latest: false}}' \
           | gh api repos/hardwood-hq/hardwood-hq.github.io/dispatches --input -

.github/workflows/release.yml

@@ -97,6 +97,8 @@ jobs:
   release-cli:
     if: inputs.release-cli
     needs: release
+    permissions:
+      contents: write
     uses: ./.github/workflows/release-cli.yml
     with:
       release-version: ${{ inputs.release-version }}

.gitignore

@@ -42,12 +42,17 @@ nb-configuration.xml
 .venv
 .docker-venv
 .release-env
+__pycache__/
 docs/hooks/__pycache__/
 
 # JReleaser
 out/
 release-output.log
 
+# `hardwood dive --log-file` defaults
+dive.log
+dive.log.lck
+
 # Extracted CLI distribution artifacts
 hardwood-cli-early-access-*/
 

CLAUDE.md

@@ -63,6 +63,13 @@ Before starting new work, check whether a corresponding GitHub issue exists. If
 Commit messages must begin with the GitHub issue key (e.g. `#90 Include file name in all exceptions raised during reading`). This applies to every commit, including fixups and amendments.
 Focus the body on **why**, not **what** — the diff already shows the what. A short paragraph is usually enough; do not restate the change as a bullet list. See [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages).
 
+# Dive TUI
+
+When changing visual styling in the `hardwood dive` TUI (any code under `cli/src/main/java/dev/hardwood/cli/dive/`), follow the visual-hierarchy decision tree in [_designs/DIVE_THEME.md](_designs/DIVE_THEME.md). Style spans through one of `Theme.primary()` / `Theme.accent()` / `Theme.selection()` / `Theme.dim()`, or leave them at default fg via `Style.EMPTY`. Direct use of `Color.*` constants or literal `Style.EMPTY.bold()` / `Style.EMPTY.fg(...)` outside `Theme.java` is a smell — review against the decision tree before introducing any.
+
+List-shaped screens must build `Row` objects only for the visible viewport, never for the whole collection. Use `RowWindow.bottomPinned(selection, total, viewport)` to derive the slice and pass `window.selectionInWindow()` to `TableState.select(...)`. Building rows for the entire list is invisible on small inputs but turns navigation O(N) on dictionaries with hundreds of thousands of entries, page lists with thousands of pages, or wide-schema files. See [_designs/DIVE_LIST_VIEWPORT_VIRTUALIZATION.md](_designs/DIVE_LIST_VIEWPORT_VIRTUALIZATION.md).
+
 # Code Reviews
 
 When reviewing a pull request, make sure the principles described here are applied.
+When asked to review a PR, write the findings to a Markdown file with a `[ ]` checkbox in front of each actionable item. When subsequently asked to address those review remarks, check the items off (`[x]`) as they are resolved.

README.md

@@ -10,7 +10,7 @@ Goals of the project are:
 * Be fast: Be as fast or faster as parquet-java
 * Be complete: Add a Parquet file writer (after 1.0)
 
-Latest version: 1.0.0.Beta1, 2026-04-02
+Latest version: 1.0.0.Beta2, 2026-04-29
 
 ## Documentation
 
@@ -22,7 +22,7 @@ Full documentation is available at **[hardwood.dev](https://hardwood.dev/)**.
 <dependency>
     <groupId>dev.hardwood</groupId>
     <artifactId>hardwood-core</artifactId>
-    <version>1.0.0.Beta1</version>
+    <version>1.0.0.Beta2</version>
 </dependency>
 ```
 
@@ -32,7 +32,7 @@ import dev.hardwood.reader.ParquetFileReader;
 import dev.hardwood.reader.RowReader;
 
 try (ParquetFileReader fileReader = ParquetFileReader.open(InputFile.of(path));
-    RowReader rowReader = fileReader.createRowReader()) {
+    RowReader rowReader = fileReader.rowReader()) {
 
     while (rowReader.hasNext()) {
         rowReader.next();

RELEASING.md

@@ -35,16 +35,50 @@ Configure the following secrets in the repository settings:
 | `JRELEASER_MAVENCENTRAL_USERNAME` | Maven Central (Sonatype) username |
 | `JRELEASER_MAVENCENTRAL_TOKEN` | Maven Central (Sonatype) token |
 
+## Preparing the release notes
+
+Before triggering the release, land an `[release] <VERSION> release notes` commit on `main` that updates `docs/content/release-notes.md` with the new section, milestone link, and contributor list.
+
+`tools/contributors.py` produces the contributor line, alphabetised and with display names resolved from each GitHub profile:
+
+```shell
+# Two tags: contributors with commits in (<since>, <until>]
+tools/contributors.py v1.0.0.Beta1 HEAD
+
+# One tag: contributors up to and including <since> (initial release)
+tools/contributors.py v1.0.0.Alpha1
+```
+
+It reads commit authors and `Co-authored-by` trailers, skips bots, and resolves emails via `gh api` (so authentication needs to be set up — `gh auth status`). Emails on accounts with email privacy enabled may not resolve; the script reports them on stderr.
+
 ## Running the Release
 
 Trigger the `Release` workflow from the GitHub Actions UI with the following inputs:
 
 - **Release version**: The version to release (e.g., `1.0.0`)
 - **Development version**: The next snapshot version (e.g., `1.1.0-SNAPSHOT`)
-- **Stage**: `UPLOAD` to upload the release to the deploy to the Maven Central portal (you can examine it at https://central.sonatype.com/publishing/deployments then), or `PUBLISH` to publish directly to Maven Central
+- **Stage**: `UPLOAD` to upload the release to the deploy to the Maven Central portal (you can examine it at https://central.sonatype.com/publishing/deployments then), or `FULL` to publish directly to Maven Central
 
-To test a staged release, run the following:
+To test a staged release, check out the release tag and run:
 
 ```shell
-MAVEN_CENTRAL_BEARER_TOKEN=`printf "${MAVENCENTRAL_USERNAME}:${MAVENCENTRAL_TOKEN}" | base64` ./mvnw clean verify -pl :hardwood-integration-test -Pcentral.manual.testing -s release-test-settings.xml -Dhardwood.version=<VERSION>
+git checkout v<VERSION>
+MAVEN_CENTRAL_BEARER_TOKEN=`printf "${MAVENCENTRAL_USERNAME}:${MAVENCENTRAL_TOKEN}" | base64` ./mvnw clean verify -pl :hardwood-integration-test -Pcentral.manual.testing -s release-test-settings.xml
 ```
+
+## Publishing the documentation
+
+Versioned documentation is published as a manual follow-up to the release, so post-release touch-ups (announcement blog post link, release-notes errata) can be folded in without mutating the release tag itself. The convention is:
+
+1. After the release, write the announcement and add the blog post link plus any errata to `docs/content/release-notes.md` on `main`.
+2. Tag that commit `v<VERSION>-docs` and push the tag:
+   ```shell
+   git tag v<VERSION>-docs
+   git push origin v<VERSION>-docs
+   ```
+3. Run the **Publish versioned documentation** workflow from the GitHub Actions UI with:
+   - **ref**: `v<VERSION>-docs`
+   - **version**: `<VERSION>` (e.g. `1.0.0.Beta2`)
+   - **update-latest**: leave checked for forward releases; uncheck for back-ports of an earlier line that should not displace the newer one.
+
+The workflow fires a `repository_dispatch` at `hardwood-hq/hardwood-hq.github.io`, which builds the site at the resolved commit. The `dev` label is refreshed automatically on every successful Main Build of `main` and never claims `latest`.

ROADMAP.md

@@ -446,7 +446,7 @@ A from-scratch implementation of Apache Parquet reader/writer in Java with no de
 - [x] Page indexes (OffsetIndex for page scanning, ColumnIndex for page-level predicate filtering)
 - [x] Predicate pushdown (row group filtering via statistics, page filtering via ColumnIndex)
 - [x] Page-range I/O for filtered reads (only matching pages fetched from remote backends)
-- [x] Coalesced reads for remote backends (`ChunkRange`, `RowGroupIndexBuffers`)
+- [x] Coalesced reads for remote backends (`ChunkRange`, `RowGroupIndexBuffers`, cross-column `SharedRegion`)
 - [ ] Bloom filters
 - [x] **Validate**: Performance improvement with filtering