pdfh 3.3.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e6f4e14950562b2b4f308dabe361ac5fb73191dd456523aeb6469e7c97cdf00
-  data.tar.gz: ce3523404e6a5bf37613b281afb8957d35f3b843dc301996377057a79a65da1b
+  metadata.gz: 3bfbea6779583e5ac915303ce31e9e7460003ba7703a7e90977abf12feb98fa5
+  data.tar.gz: a74428a0ba54acb17ee6195c2d6e84fd728a1e509009ed940099c34d56bbdabb
 SHA512:
-  metadata.gz: 8e44d1c076c9825555e6c4c9ac3c5ec8efa0e03612aca314d4c7fc5f17980590b0b38fb1c3fd77573912edeeb5d7ae11bb06749eeffe7e3c031536125c1f99e3
-  data.tar.gz: 68643552fd0d663acb8fb9a107ba6c52938a0e42adc77e19ef877b603656cf81633abe1bb36d1dcf2d4df73b68a401b86ae55c050eea35640afc132c3240365a
+  metadata.gz: aa97de92e612928c87c6d23df517be4168b8805adea2cd9006953ec00dc738cd6f62d83919e845868244322bd2c0e187df8b0a6402ac078a5d037e8f4851b664
+  data.tar.gz: de145b9b13f5f78d3203519e811ad43d124a50a23408583215656a65f06679db2a700ddf2948e0521198c5a387ad464d8cce9caf01a771e5d90d169ab0162826

data/.editorconfig

@@ -12,20 +12,5 @@ max_line_length = 120
 [*.py]
 indent_size = 4
 
-[*.rb]
-indent_size = 2
-
 [*.md]
 trim_trailing_whitespace = false
-
-[*.yml]
-indent_size = 2
-
-[*.yaml]
-indent_size = 2
-
-[*.json]
-indent_size = 2
-
-[*.{js,jsx,ts,tsx}]
-indent_size = 2

data/.gitignore

@@ -8,6 +8,9 @@ spec/reports/
 spec/coverage/
 tmp/
 
+# IDE
+.idea/
+
 # rspec failure tracking
 .rspec_status
 

data/.rubocop.yml

@@ -7,7 +7,7 @@ plugins:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
   Exclude:
     - doc/**/*
     - pkg/**/*
@@ -30,3 +30,7 @@ Style/StringLiteralsInInterpolation:
 
 Layout/HashAlignment:
   EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-04-19 20:15:39 UTC using RuboCop version 1.75.2.
+# on 2026-03-21 12:40:43 UTC using RuboCop version 1.85.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -9,28 +9,15 @@
 # Offense count: 10
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 38
+  Max: 57
 
-# Offense count: 16
+# Offense count: 1
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 131
+  Max: 26
 
 # Offense count: 6
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 33
-
-# Offense count: 1
-# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
-# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
-Naming/MethodParameterName:
-  Exclude:
-    - 'lib/pdfh/utils/console.rb'
-
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-Style/RedundantStringEscape:
-  Exclude:
-    - 'lib/pdfh/settings_template.rb'
+  Max: 26

data/.simplecov

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "English"
+
+SimpleCov.start do
+  # Basic configuration
+  enable_coverage :branch
+  minimum_coverage line: 75, branch: 40
+
+  # Filters to exclude files that don't need coverage
+  add_filter "/spec/"
+  add_filter "/bin/"
+  add_filter "/exe/"
+  add_filter "/vendor/"
+
+  # HTML formatter only - no console noise
+  formatter SimpleCov::Formatter::HTMLFormatter
+
+  # Groups to organize the report
+  add_group "Models", "lib/pdfh/models"
+  add_group "Services", "lib/pdfh/services"
+  add_group "Utils", "lib/pdfh/utils"
+
+  # Track files
+  track_files "lib/**/*.rb"
+
+  # Show clearer messages on failure
+  at_exit do
+    # Only run if there is no other error
+    SimpleCov.result.format! if $ERROR_INFO.nil? || ($ERROR_INFO.is_a?(SystemExit) && $ERROR_INFO.success?)
+  end
+end

data/AGENTS.md

@@ -0,0 +1,174 @@
+# AGENTS.md
+
+Guide for agentic coding assistants working in this repository.
+
+## Quick Facts
+
+- Project: `pdfh` (Ruby gem + CLI)
+- Runtime Ruby: 4.0 via `mise` (`mise.toml`); gemspec minimum `>= 3.2.0`
+- Linting: RuboCop (TargetRubyVersion 3.2); plugins: `rubocop-performance`, `rubocop-factory_bot`, `rubocop-rake`
+- Tests: RSpec with `expect` syntax and no monkey patching
+- Key runtime deps: `colorize ~> 1.1` (logging colors)
+
+## Build, Lint, Test
+
+Run from repo root. Prefer `mise` tasks when available.
+
+```bash
+# Tests
+bundle exec rspec
+mise run test
+
+# Single test file or example
+bundle exec rspec spec/pdfh/models/document_spec.rb
+bundle exec rspec spec/pdfh/models/document_spec.rb:42
+
+# Lint
+bundle exec rubocop
+mise run lint
+
+# Auto-fix linting issues
+bundle exec rubocop -a
+
+# Build gem
+rake build
+
+# Interactive console
+bin/console
+```
+
+Useful `mise` tasks (`mise.toml`):
+
+- `mise run lint`
+- `mise run test` (runs `bundle exec rspec --order random --format documentation`)
+- `mise run check` (runs lint + test)
+- `mise run bump[major|minor|tiny]`
+- `mise run pre` (runs `pre-commit run --all-files`)
+- `mise run update` (runs `bundle update`)
+- `mise run release` (builds gem + pushes to RubyGems)
+
+## Repository Layout
+
+- `exe/pdfh` CLI entrypoint
+- `lib/pdfh` gem code
+- `lib/pdfh/services` service objects
+- `lib/pdfh/models` domain models
+- `lib/pdfh/utils` shared utilities
+- `spec/` RSpec tests, mirrors `lib/` structure
+
+## Processing Flow (High Level)
+
+```text
+exe/pdfh → Main.start → OptParser → SettingsBuilder → SettingsValidator
+                                                            ↓
+                                         DirectoryScanner.scan (finds *.pdf)
+                                                            ↓
+                                          PdfTextExtractor.call
+                                                            ↓
+                                          DocumentMatcher.match
+                                                            ↓
+                                          DocumentManager.call
+```
+
+Key service objects in `lib/pdfh/services/`:
+
+- `DirectoryScanner` — globs `*.pdf` from configured `lookup_dirs`
+- `PdfTextExtractor` — shells out `pdftotext -enc UTF-8 -layout`
+- `DocumentMatcher` — iterates `DocumentType`s; matches `re_id` then `re_date`
+- `DocumentManager` — creates dest dir, copies/renames PDF, copies companion files
+- `SettingsBuilder` — locates and parses `pdfh.yml`
+- `SettingsValidator` — validates settings; raises `ArgumentError` on fatal errors, warns and skips on soft errors (e.g. missing lookup dirs)
+- `OptParser` — parses `ARGV` into `RunOptions`
+
+## Code Style and Conventions
+
+General:
+
+- Always include `# frozen_string_literal: true` at the top of Ruby files.
+- Use double-quoted strings (RuboCop enforces this).
+- Max line length is 120 characters (see `.rubocop.yml`).
+- Prefer small, focused classes and service objects for side effects.
+- Avoid global state except for `Pdfh.logger` (centralized logger).
+
+Imports / requires:
+
+- Use `require` for gem dependencies and `require_relative` for local files in tests.
+- In specs, `spec/spec_helper.rb` loads SimpleCov and shared config; do not load it twice.
+
+Formatting:
+
+- RuboCop is authoritative; follow alignment and formatting it enforces.
+- Hash alignment uses table style for hash rockets.
+
+Types and documentation:
+
+- All methods must have YARD documentation.
+- `@return` is mandatory and must describe the return value.
+- Add `@param` tags with types and names for each parameter.
+- For complex methods, add a short explanatory comment block and an `@example`.
+
+Naming:
+
+- Use descriptive names; classes and modules are `CamelCase`, methods and variables are `snake_case`.
+- Prefer explicit domain names (e.g., `DocumentManager`, `SettingsBuilder`).
+- Keep abbreviations consistent with existing code (e.g., `pdf`, `dir`).
+
+Error handling:
+
+- Use `Pdfh.logger` for user-facing errors and verbose debug output.
+- `Main.start` rescues `SettingsIOError` and `StandardError` and exits with status 1.
+- Custom exceptions defined in `lib/pdfh.rb`: `SettingsIOError` (config not found), `ReDateError` (date regex no match).
+- `SettingsValidator` raises `ArgumentError` for fatal config errors; warns and skips for recoverable ones (e.g. a lookup dir that doesn't exist).
+- Favor raising domain-specific errors in services and handle them in entrypoints.
+- Avoid rescuing broadly in inner layers unless re-raising with context.
+
+Side effects and IO:
+
+- File system changes are centralized in `DocumentManager`.
+- Respect `dry_run` / `--dry` to avoid writing files.
+- When copying/moving files, preserve metadata if possible (`FileUtils` with `preserve: true`).
+
+Testing:
+
+- RSpec uses `expect` syntax and disables monkey patching.
+- Specs mirror the `lib/` structure; keep tests close to the corresponding module.
+- Use FactoryBot factories in `spec/factories/` when needed.
+
+## Configuration and Templates
+
+- Configuration is loaded from `$PDFH_CONFIG_FILE`, then CWD, `~/.config/`, then `~/`.
+- Document templates use `{placeholder}` tokens defined in `Document#rename_data`.
+- Date regex supports named captures `(?<m>...)` / `(?<y>...)` / `(?<d>...)` or positional captures.
+
+## Dependency Checks
+
+- External tools: `pdftotext` (required) and `qpdf` (declared but not actively called in v4) must be available; checked via `DependencyValidator`.
+
+## Pitfalls
+
+- **v4 breaking change**: Config format changed in v4.0.0 — old configs are incompatible. `re_id` matches PDF *text content* (not filename). New placeholders: `{day}`, `{quarter}`, `{bimester}`, `{name}`.
+- **Multi-match behavior**: PDFs matching more than one `DocumentType` are silently skipped (see `Main.start`).
+- **`_unlocked` suffix**: `DocumentManager` strips `_unlocked` when locating companion files — legacy pattern from `qpdf` unlocking.
+- **Config search path**: `$PDFH_CONFIG_FILE` → CWD → `~/.config/` → `~/`. Error message does not list paths checked.
+- **Colorize in tests**: Logging output is colored via `colorize`; specs mock `Console` with shared context `"with silent console"` to suppress output.
+
+## Suggested Workflow for Agents
+
+- Read existing classes/services before adding new ones to match patterns.
+- Prefer minimal changes; update specs alongside behavior changes.
+- Run `mise run lint` and `mise run test` before finalizing changes.
+- Keep changes localized; avoid touching unrelated files.
+
+## Examples
+
+Run a single spec:
+
+```bash
+bundle exec rspec spec/pdfh/models/document_spec.rb:42
+```
+
+Run lint + test:
+
+```bash
+mise run check
+```

data/CHANGELOG.md

@@ -1,40 +1,105 @@
-## v3.0.2
+# Changelog
+
+## v4.0.0 - 2026-03-21
+
+### Breaking
+
+- Old settings file is not compatible with this version; update to the new format described in README.
+- Drop password/Base64 handling; require only `pdftotext` command.
+- Remove subtypes and ZIP processing support.
+
+### Added
+
+- New name template placeholders: `{day}`, `{quarter}`, `{bimester}`, `{name}`.
+
+### Changed
+
+- Remove `{extra}` and `{type}` placeholders from name template.
+- Refactor processing flow into services (scanner, extractor, matcher, manager).
+- Drop document identification by file name; identify documents by content with `re_id`.
+- Improve logging and error handling with a global logger.
+- Update README usage and configuration docs.
+
+## v3.3.1 - 2026-03-06
+
+- Add document type required fields validation
+- Upgrade to Ruby 4
+- Upgrade gems and mise tasks
+
+## v3.3.0 - 2025-05-06
+
+- Add zip file pre-processing and zip_type model
+- Decouple main and opt_parser from ARGV
+- Add PasswordDecodable module and move dependency check to utils
+- Add pre-commit config and update RuboCop config
+- Update Ruby version and dependencies; improve coverage and docs
+
+## v3.2.0 - 2025-04-01
+
+- Change document_type to a class and add re_date support for sub types
+- Add more config file locations
+- Remove undocumented print_cmd field
+- Add backtrace console output
+- Migrate to mise and upgrade Ruby/dependencies
+
+## v3.1.0 - 2024-05-03
+
+- Handle store_path placeholders as name_template
+
+## v3.0.3 - 2024-03-15
+
+- Move document rename to its own object
+- Add debug gem
+- Fix minor documentation issues
+
+## v3.0.2 - 2024-01-10
+
 - Fix `undefined method` when an invalid option is provided
 - Fix and add tests to get above 90% coverage
 
-## v3.0.1
+## v3.0.1 - 2024-01-09
+
 - Refactor classes for better readability
 - Upgrade to Ruby v3.3.0 and require at least Ruby 3.0.0
 - Upgrade gem dependencies
 
-## v3.0.0
+## v3.0.0 - 2022-08-01
+
 - Migrate to `asdf` from `rvm`
 - Upgrade old gems
 - Bump to v3 (as this is project's third iteration)
 
-## v0.2.0
+## v0.2.0 - 2021-05-14
+
 - Major gem refactoring
 - Change setting `base_path` to `destination_base_path`
 - Add DocumentType listing option on executable file
 - Add process individual documents providing type and files
+
     ```bash
     pdfh -t document_type_id path/to_files.pdf
     ```
+
 - Add `settings.yml` template in order to create a sample file
 
-## v0.1.9
+## v0.1.9 - 2021-03-02
+
 - Add dependencies validation at run
 
-## v0.1.5
+## v0.1.5 - 2019-04-01
+
 - Add `print_cmd` field in config file for information purposes
 - Settings now validates an unexisting directory
 - Refactor for easier maintenance
 
-## v0.1.4
+## v0.1.4 - 2019-01-28
+
 - Add titleize format when writing new file
 
-## v0.1.3
+## v0.1.3 - 2019-01-18
+
 - Fixed copy companion files, which was not copying the files.
 
-## v0.1.2
+## v0.1.2 - 2019-01-10
+
 - Initial Release

data/Gemfile

@@ -9,15 +9,11 @@ gem "bundler", "~> 4.0"
 gem "code-scanning-rubocop", "~> 0.5"
 gem "debug", "~> 1.8"
 gem "factory_bot", "~> 6.2"
-gem "pry", "~> 0.14"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.12"
-gem "rspec_junit_formatter", "~> 0.4"
 gem "rubocop", "~> 1.81"
 gem "rubocop-factory_bot", "~> 2.27"
 gem "rubocop-performance", "~> 1.18"
 gem "rubocop-rake", "~> 0.5"
 gem "rubocop-rspec", "~> 3.7"
 gem "simplecov", "~> 0.22"
-gem "simplecov-console", "~> 0.9"
-gem "versionomy", "~> 0.5"

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    pdfh (3.3.1)
+    pdfh (4.0.0)
       colorize (~> 1.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.1.1)
+    activesupport (8.1.2)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
@@ -20,14 +20,13 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    ansi (1.5.0)
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
     bigdecimal (4.0.1)
-    blockenspiel (0.5.0)
     code-scanning-rubocop (0.6.1)
       rubocop (~> 1.0)
-    coderay (1.1.3)
     colorize (1.1.0)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
@@ -38,42 +37,45 @@ GEM
     diff-lcs (1.6.2)
     docile (1.4.1)
     drb (2.2.3)
-    erb (6.0.1)
+    erb (6.0.2)
     factory_bot (6.5.6)
       activesupport (>= 6.1.0)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     io-console (0.8.2)
-    irb (1.16.0)
+    irb (1.17.0)
       pp (>= 0.6.0)
+      prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.18.0)
+    json (2.19.2)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    method_source (1.1.0)
-    minitest (6.0.1)
+    mcp (0.9.0)
+      json-schema (>= 4.1)
+    minitest (6.0.2)
+      drb (~> 2.0)
       prism (~> 1.5)
     parallel (1.27.0)
-    parser (3.3.10.0)
+    parser (3.3.10.2)
       ast (~> 2.4.1)
       racc
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.7.0)
-    pry (0.16.0)
-      coderay (~> 1.1)
-      method_source (~> 1.0)
-      reline (>= 0.6.0)
+    prism (1.9.0)
     psych (5.3.1)
       date
       stringio
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
-    rdoc (7.0.3)
+    rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
@@ -89,24 +91,23 @@ GEM
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.7)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.6)
-    rspec_junit_formatter (0.6.0)
-      rspec-core (>= 2, < 4, != 2.12.0)
-    rubocop (1.82.1)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.48.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-factory_bot (2.28.0)
@@ -128,15 +129,9 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-console (0.9.4)
-      ansi
-      simplecov
-      terminal-table
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
     stringio (3.2.0)
-    terminal-table (4.0.0)
-      unicode-display_width (>= 1.1.1, < 4)
     tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
@@ -144,8 +139,6 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     uri (1.1.1)
-    versionomy (0.5.0)
-      blockenspiel (~> 0.5)
 
 PLATFORMS
   ruby
@@ -156,18 +149,14 @@ DEPENDENCIES
   debug (~> 1.8)
   factory_bot (~> 6.2)
   pdfh!
-  pry (~> 0.14)
   rake (~> 13.0)
   rspec (~> 3.12)
-  rspec_junit_formatter (~> 0.4)
   rubocop (~> 1.81)
   rubocop-factory_bot (~> 2.27)
   rubocop-performance (~> 1.18)
   rubocop-rake (~> 0.5)
   rubocop-rspec (~> 3.7)
   simplecov (~> 0.22)
-  simplecov-console (~> 0.9)
-  versionomy (~> 0.5)
 
 BUNDLED WITH
-  4.0.3
+  4.0.8