handlemyfile 0.1.0__tar.gz

handlemyfile-0.1.0/.gemini/rules/anti-overfitting-layout-invariants.md

@@ -0,0 +1,27 @@
+# Rule: Anti-Overfitting & Continuous Geometric Layout Invariants
+
+## 1. Absolute Prohibition on Single-Document Hyper-Analysis
+- NEVER inspect or micro-tune code against the coordinate idiosyncrasies of a single document in isolation.
+- Do NOT write temporary scripts to inspect single-document bounding boxes and then hardcode thresholds tailored to that document.
+- Single-document tailoring is an anti-pattern that guarantees regressions on other document types. All algorithms must be derived from universal mathematical and typographic principles.
+
+## 2. Prohibition of Discrete If-Else Thresholds on Continuous 2D Space
+- Document layout is a continuous 2D spatial domain ($x, y, w, h$, font metrics, density). 
+- NEVER use discrete integer count thresholds (e.g., `left_count >= 1 && right_count >= 1`) to make global layout decisions (such as Single-Column vs Multi-Column).
+- Structural layout classification must be governed by continuous mathematical models:
+  1. **Text Mass Symmetry Ratio**:
+     $$\mathcal{S}_{\text{mass}} = \frac{\min(M_L, M_R)}{\max(M_L, M_R)} \ge 0.40$$
+     Where $M_L$ and $M_R$ are the aggregated text masses (character counts or total glyph area) of non-wide blocks on each side of the page center. Isolated marginal metadata (e.g. right-aligned resume dates, line numbers, page numbers) represent $< 15\%$ of total text mass and must NEVER trigger multi-column mode.
+  2. **Baseline Pairing for Tab Stops**:
+     When two blocks share the same vertical baseline ($|\Delta y| \le 2.0\text{ pt}$), they belong to the same logical line and must be modeled as Tab Stops (`<w:tab/>`), not parallel column partitions.
+  3. **Scale-Invariant Font Proportions**:
+     All whitespace decision boundaries (Docstrum word clustering, gutter thresholds, line leading) must be strictly proportional to local font em-size ($0.18 - 0.32\text{ em}$), never fixed point constants (`16.0 pt`, `54.0 pt`).
+
+## 3. Mandatory Multi-Class Corpus Verification
+- Any modification to layout analysis, clustering, or DOCX generation must be validated across a diverse multi-class corpus:
+  1. Single-page table-dense documents (e.g. exam papers, forms).
+  2. Single-column ATS resumes/CVs with right-aligned dates.
+  3. Multi-column academic papers (IEEE/ACM) with spanning titles and figures.
+  4. Standard narrative documents / reports.
+- If an algorithm works for Document A but breaks Document B, the mathematical abstraction is incomplete and must be redesigned, never patched with another `if-else`.
+

handlemyfile-0.1.0/.gemini/rules/empirical-user-validation.md

@@ -0,0 +1,13 @@
+# Rule: Empirical User Validation & Ban on Self-Adulatory AI Benchmarks
+
+1. **No Synthetic "Victory Lap" Benchmarks**:
+   - Never present self-generated statistical tables claiming "100% fixed", "0 errors", or "perfect accuracy" as proof of task completion.
+   - Internal script checks are intermediate sanity checks for the agent's internal development loop only, NOT authoritative proof of correctness for the user.
+
+2. **User is the Sole Empirical Ground Truth**:
+   - The user's inspection of the rendered document in Microsoft Word is the only valid acceptance test.
+   - When presenting fixes, describe the specific architectural and geometric root cause that was addressed, explain what visual defects it resolves, and invite the user to verify the actual output.
+
+3. **Holistic Visual & Document Layout Respect**:
+   - Never consider a feature "fixed" by looking at isolated metrics (such as alignment tag counts) when adjacent structural integrity (e.g., vertical slicing across math formulas, footnote contamination into body sentences) remains broken.
+

handlemyfile-0.1.0/.gemini/rules/pdf-page-boundary-preservation.md

@@ -0,0 +1,32 @@
+# Rule: 1:1 PDF Page Boundary Preservation & Geometric Spacing
+
+1. **82% Density Threshold for Page Breaks**:
+   - Insert explicit `<w:br w:type="page"/>` ONLY when:
+     a. `prev_max_y < (page_height * 0.82)`: Intentional author page termination (Thesis Cover, Lembar Pengesahan, Kata Pengantar, Daftar Isi, or chapter endings).
+     b. Next page begins with a major section/chapter title (`H1` at $y_{\min} \le 120\text{ pt}$).
+     c. Orientation change (Portrait $\leftrightarrow$ Landscape).
+   - On dense pages ($\ge 82\%$ full with continuing body/table content), do NOT insert artificial hard page breaks. Word's natural text layout flows them without creating single-line orphaned pages (which previously exploded 8-page documents into 15 pages).
+
+2. **Native Right Tab Stop for Running Headers & Footers**:
+   - Never use OOXML tables (`<w:tbl>`) in `<w:hdr>` or `<w:ftr>`. Tables in headers/footers have cell margins, borders, and row height constraints that inflate vertical footprint to $>40\text{ pt}$, pushing the footer up into body tables.
+   - Use a single-line paragraph with a native Word right tab stop (`<w:tabs><w:tab w:val="right" w:leader="none" w:pos="{printable_width}"/></w:tabs>`):
+     Left text (date/URL), tab character (`<w:tab/>`), right text / dynamic page number (`PAGE / NUMPAGES`).
+   - Takes up exactly 1 line height ($\sim 11\text{ pt}$) with zero vertical overhead.
+
+3. **Vertical Margin Clearance & Dynamic Clamping**:
+   - Always enforce `w:header="360" w:footer="360"` ($18\text{ pt}$).
+   - Body margins `w:top` and `w:bottom` must be dynamically derived from the document and clamped to safe typographic bounds: `clamp(28.0, 72.0)` points. Never force a minimum of $54\text{ pt}$ which artificially clips tight IEEE/academic margins ($\sim 36-44\text{ pt}$) and pushes content across page boundaries.
+
+4. **Zero Synthetic Spacing Inflation**:
+   - Never inject arbitrary hardcoded paragraph spacing constants (e.g. `+12pt`, `+6pt`, `+80 twips`).
+   - Derive `space_before` strictly from the visual vertical delta ($\Delta y = y_{\min}(i) - y_{\max}(i-1) - 2.0$) between bounding boxes in the PDF.
+   - Keep `space_after = 0.0` and let `space_before` faithfully represent inter-block distance.
+
+5. **Zero Natural Language Keywords (Strict Language-Agnostic Engine)**:
+   - NEVER hardcode human language keywords or strings (e.g. "DAFTAR ISI", "TABLE OF CONTENTS", "BAB", "CHAPTER", "KATA PENGANTAR", "HALAMAN", "PAGE", "LEMBAR PENGESAHAN", etc.) in any part of the engine (DLA, classifier, rxyc, table detector, or DOCX generator).
+   - The engine must operate universally across all languages and scripts (Latin, Cyrillic, CJK, Arabic, Devanagari, etc.).
+   - All structural decisions must be derived strictly from:
+     a. **Typography**: Relative font size ratios ($font \ge 1.35 \times median\_body$), font weights (`is_bold`), Unicode casing properties (`is_all_caps` via `is_alphabetic` and `is_uppercase`).
+     b. **Spatial Geometry**: Coordinates ($y_{\min} \le 160\text{ pt}$ for page-top titles), horizontal alignment (`alignment == "center"`), block length ($\le 2$ lines, $\le 80$ characters), and bounding box margins.
+     c. **Structural Leader Patterns**: Universal dot leader patterns (`..` or trailing page number with tab gap $\ge 20\text{ pt}$ or $x \ge 350\text{ pt}$) to detect TOC rows and generate native Word dot-leader tabs, completely independent of natural language strings.
+

handlemyfile-0.1.0/.gemini/rules/zero-heuristic-spatial-geometry.md

@@ -0,0 +1,28 @@
+---
+description: "Zero-Heuristic Spatial Geometry Invariants: Strict Prohibition of Discrete If-Else Branching on 2D Space"
+globs: "src/**/*.rs"
+---
+
+# Zero-Heuristic Spatial Geometry Standard
+
+## Core Invariant
+Continuous 2D spatial coordinates $(x, y, w, h)$ must NEVER be partitioned using discrete boolean `if-else` branching with arbitrary magic constants (e.g. `x <= mid + 15.0`, `left_count >= 1 && right_count >= 1`, `gap >= 7.0`).
+
+## Enforced Design Principles
+1. **Topological 1D Interval Merging for Lines**:
+   - Two bounding intervals $[y_{\min}, y_{\max}]$ and $[y'_{\min}, y'_{\max}]$ belong to the same physical text line if their vertical projection intervals overlap:
+     $$\max(y_{\min}, y'_{\min}) < \min(y_{\max}, y'_{\max})$$
+   - Horizontal gaps on the same vertical line represent **Tab Stops** (`<w:tab/>`) or paragraph indentations, NOT separate columns.
+   - Resumes, invoices, receipts, legal signatures, and exam headers with left-aligned descriptions and right-aligned dates/amounts MUST remain on the same line.
+
+2. **Continuous Projection Gutter Analysis for Columns**:
+   - A multi-column layout requires a continuous, unobstructed vertical whitespace gutter spanning across multiple paragraphs.
+   - Column classification must never be evaluated as an arbitrary page-wide boolean flag.
+
+3. **No Arbitrary Magic Numbers**:
+   - All spatial thresholds must be derived dynamically from intrinsic document metrics (median font size, inter-character docstrum spacing, page printable width).
+   - Never inject hardcoded coordinates like `15.0`, `35.0`, `75.0`, or `120`.
+
+4. **Preserve Embedded Graphics & Masks**:
+   - Image masks (`/ImageMask true`) and inverted decode tables (`/Decode [1 0]`) must be respected to prevent transparent signatures and stamps from rendering as solid black boxes.
+

handlemyfile-0.1.0/.github/workflows/publish-crates.yml

@@ -0,0 +1,19 @@
+name: Publish to Crates.io
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Publish to Crates.io
+        run: cargo publish --token ${{ secrets.CRATES_IO_TOKEN }}

handlemyfile-0.1.0/.github/workflows/publish-npm.yml

@@ -0,0 +1,38 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+
+      - name: Install wasm-pack
+        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Build WebAssembly Package
+        run: wasm-pack build --target web --out-name handlemyfile
+
+      - name: Copy License to pkg
+        run: cp LICENSE pkg/
+
+      - name: Publish to NPM
+        run: npm publish pkg --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

handlemyfile-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,108 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --features python
+          sccache: 'true'
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
+  windows:
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        target: [x64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          architecture: ${{ matrix.target }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --features python
+          sccache: 'true'
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows-${{ matrix.target }}
+          path: dist
+
+  macos:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --features python
+          sccache: 'true'
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  release:
+    name: Release to PyPI
+    runs-on: ubuntu-latest
+    needs: [linux, windows, macos, sdist]
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

handlemyfile-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+/target
+node_modules/
+tests/*.docx