sqa 0.0.32 → 0.0.38

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ce65f3dece761390257e68d4b3ddaf878e27e0b932b6b4dbd2dfecac2244c5f
-  data.tar.gz: 4dc160dda96a433049aeb06898a8a3cbfe1ecec439e1a9942d8272593658be14
+  metadata.gz: 830fbff0a1f2441e67e9781a2996774575cf021440c787804d308cde4b1fd7d5
+  data.tar.gz: be89088467543c775860ba3eee54a68c9998c50a1043ade62334678bc9175b05
 SHA512:
-  metadata.gz: 3194aaf4f55f8b2e388af48012ad71b5e282e4a69505f59dae78b29d30d2cb38c74ea06a25eff4b0323644a5b05581562b1c846c80ae0f7a39b2bc2210a58e1b
-  data.tar.gz: 5f5c72d9cbb21e508d85318a2d4173a6ea0e77cbe10f866131a90004b7fe8cb7278422f033038477dcd215cc46fd2738a841d3217b61da6e7ac8f05c18b149dc
+  metadata.gz: 3b592a70012e50b0199d70f7511c02bda585b9c5a410a142d2945ba7af2e85565d06ebbcd7d26ecdb540c203f00dec3f6e7234df6b53bb73c597d780ebaf371d
+  data.tar.gz: eab323c5c1c7531042729a952a3f66e1ed21d6da872a92fa8ffe3a68cf63e3ebf50f7d4b47fe436d1301b5573530ee4acc9d477bce9f969bfd077fbaa2b53918

data/CHANGELOG.md

@@ -1,6 +1,159 @@
 ## [Unreleased]
 
-## [0.0.32] 2025-11-12
+## [0.0.39] - 2025-11-24
+
+### Added
+- **YARD Documentation Examples**:
+  - Added comprehensive usage examples to 15+ critical methods across core classes
+  - `SQA::Portfolio`: Examples for `#buy`, `#sell`, `#value`, `#summary` methods
+  - `SQA::Backtest`: Examples for `#run` method showing RSI strategy, custom date ranges, and equity curve access
+  - `SQA::Stock`: Examples for `#update` method with API metadata fetching
+  - `SQA::DataFrame`: Examples for `#concat_and_deduplicate!` and `#to_csv` methods
+  - All examples demonstrate real-world usage with expected outputs
+
+- **File Formats Documentation**:
+  - Created comprehensive `docs/file_formats.md` documenting all CSV and JSON formats
+  - **Portfolio Positions CSV**: Schema and usage for `save_to_csv()` / `load_from_csv()`
+  - **Trade History CSV**: Schema and usage for `save_trades_to_csv()`
+  - **Stock Data CSV**: OHLCV format with critical TA-Lib ordering requirements
+  - **Stock Metadata JSON**: Company overview data structure
+  - **Configuration Files**: YAML/TOML format documentation
+  - Added to MkDocs navigation under User Guide > Core Concepts
+
+### Changed
+- **API Documentation Improvements**:
+  - Regenerated all 51+ API reference markdown files with new examples
+  - Examples now appear in purple Material Design admonition boxes
+  - Improved discoverability of common usage patterns
+
+## [0.0.38] - 2025-11-24
+
+### Added
+- **Integrated YARD Documentation into MkDocs**:
+  - Created `bin/generate_api_docs.rb` script to convert YARD comments to markdown
+  - Generates 51+ API reference markdown files in `docs/api-reference/`
+  - Unified Material theme across all documentation pages
+  - Auto-generated documentation includes timestamp and complete class/module information
+
+### Changed
+- **Enhanced Documentation Formatting**:
+  - Markdown generation now uses Material Design admonitions (note, info, success, example)
+  - Added emojis for visual hierarchy (📦 classes, 🔧 modules, 🏭 class methods, 🔨 instance methods, 📝 attributes, 🔢 constants)
+  - Parameters displayed in formatted tables instead of lists
+  - Return values in green success boxes with type badges
+  - Usage examples in purple example boxes with proper syntax highlighting
+  - Collapsible source location sections to reduce visual clutter
+  - Attribute access indicators (🔄 read/write, 👁️ read-only, ✍️ write-only)
+
+- **Simplified Rake Tasks**:
+  - Consolidated documentation tasks under `docs:` namespace
+  - `docs:build` - Generate API markdown from YARD + build MkDocs site
+  - `docs:serve` - Serve documentation locally with live reload
+  - `docs:clean` - Clean generated documentation files
+  - `docs:deploy` - Deploy to GitHub Pages
+  - Removed legacy tasks: `yard`, `yard_server`, `api_docs`
+
+- **Documentation Visual Improvements**:
+  - Updated `docs/index.md` with flexbox layout (logo left, features right)
+  - Converted 6 mermaid diagrams to colorful SVG images with transparent backgrounds
+  - High-contrast colors for better readability
+  - Added namespace icons (🎯 SQA, 📊 strategies) in API index
+
+### Dependencies
+- Added `yard` and `yard-markdown` gems for API documentation generation
+
+## [0.0.36] - 2025-11-24
+
+### Changed
+- **Phase 3 Architecture & Design Improvements**:
+  - Added deprecation warning for auto-initialization at require time (will be removed in v1.0)
+    - Added `SQA::Config.initialized?` class method to track initialization state
+    - Warning only shows when `$VERBOSE` is set
+  - `concat_and_deduplicate!` now enforces ascending order for TA-Lib compatibility
+    - Warns and forces `descending: false` if `descending: true` is passed
+    - Prevents silent calculation errors from incorrect data ordering
+  - Extracted Faraday connection to configurable dependency in `SQA::Stock`
+    - Added `ALPHA_VANTAGE_URL` constant
+    - Added class methods: `connection`, `connection=`, `default_connection`, `reset_connection!`
+    - Allows injection of custom connections for testing/mocking
+    - Deprecated `CONNECTION` constant (will be removed in v1.0)
+
+### Added
+- **Test Coverage for Phase 3**:
+  - Added 2 tests to `test/config_test.rb` for `initialized?` method
+  - Added 7 tests to `test/stock_test.rb` for configurable connection
+  - Updated `test/data_frame_test.rb` to verify ascending order enforcement
+
+## [0.0.35] - 2025-11-23
+
+### Changed
+- **Phase 2 Code Quality & Best Practices**:
+  - Replaced class variables (`@@var`) with class instance variables (`@var`) for thread safety
+    - `SQA::init.rb`: `@@config`, `@@av_api_key` → `@config`, `@av_api_key`
+    - `SQA::Ticker`: Restructured with `class << self` block, added `reset!` method
+    - `SQA::Stock`: `@@top` → `@top`, added `reset_top!` method
+  - Replaced `puts` statements with `debug_me` in `SQA::SectorAnalyzer`
+  - Simplified `method_missing` in `SQA::DataFrame` (no longer dynamically defines methods)
+  - Fixed type checking pattern in `SQA::Strategy#add` to use `is_a?` instead of `.class ==`
+  - Fixed `SQA::Strategy#available` to use `.name` instead of `.to_s` (avoids pretty_please gem conflict)
+  - Removed magic placeholder "xyzzy" from `SQA::Stock#create_data`
+
+### Fixed
+- **DataFrame.from_aofh**: Fixed Polars compatibility by converting to hash-of-arrays format
+- **DataFrame.from_aofh**: Now properly passes `mapping:` and `transformers:` parameters
+- **Ticker.valid?**: Now handles nil and empty string inputs gracefully
+- **Ticker.lookup**: Now handles nil and empty string inputs gracefully
+
+### Added
+- **Test Coverage for Phase 2**:
+  - New `test/ticker_test.rb` with 10 tests for Ticker class
+  - New `test/strategy_test.rb` with 10 tests for Strategy class
+  - Added 4 tests to `test/data_frame_test.rb` for `from_aofh` and `method_missing`
+  - Added 2 tests to `test/stock_test.rb` for `reset_top!` method
+
+## [0.0.34] - 2025-11-23
+
+### Fixed
+- **Test Suite**: Fixed 15+ pre-existing test failures
+  - Fixed typo in RiskManagerTest (`var` → `cvar`)
+  - Fixed Portfolio test expectations (total_cost, P&L calculation, summary keys)
+  - Fixed URL trailing slash comparisons in AlphaVantage/YahooFinance tests
+  - Fixed FPOP test expectation (implementation returns partial windows)
+  - Fixed SectorAnalyzer symbol/string comparison
+  - Fixed AlphaVantage header mapping test (timestamp, no adjusted_close)
+- **PatternMatcher**: Fixed integer division bug in `pattern_quality` method
+  - Added `.to_f` conversion to prevent truncation with integer inputs
+- **Config Coercion**: Fixed string-to-symbol coercion for `log_level` and `plotting_library`
+  - Added explicit `coerce_key` handlers
+
+### Added
+- **Portfolio**: Added `commission` to `attr_accessor` for public access
+- **Error Namespacing**: Added `SQA::BadParameterError` namespace with backwards-compatible alias
+
+### Changed
+- **Phase 1 Security & Correctness** (from improvement plan):
+  - Replaced shell injection vulnerability (`touch` backticks → `FileUtils.touch`)
+  - Replaced deprecated `has_key?` with `key?` across codebase
+  - Added `SQA::DataFetchError` and `SQA::ConfigurationError` exception classes
+  - Replaced bare `rescue` clauses with specific exception types
+
+## [0.0.33] - 2025-11-23
+
+### Removed
+- **Sinatra Example App**: Removed `examples/sinatra_app/` directory
+  - Functionality moved to separate gem: [sqa_demo-sinatra](https://github.com/MadBomber/sqa_demo-sinatra)
+  - Cleaner separation between library and demo application
+
+### Added
+- **Documentation**: Added links to sqa_demo-sinatra demo application
+  - Updated README.md with Web Demo Application section
+  - Updated docs/index.md with Demo Application section
+  - Updated examples/README.md with reference to web demo
+- **LLM Documentation**: Added llms.txt for AI assistant compatibility
+- **Improvement Plan**: Added docs/IMPROVEMENT_PLAN.md for upcoming code quality improvements
+
+## [0.0.32] - 2024-11-12
+
 ### Added
 - **CSV Updates**: Conditional CSV updates based on timestamp
   - Only updates CSV files when new data is available

data/README.md

@@ -913,6 +913,10 @@ ruby examples/strategy_generator_example.rb
 
 See `examples/README.md` for detailed documentation and integration patterns.
 
+### Web Demo Application
+
+For a complete web-based demonstration of SQA's capabilities, see the **[sqa_demo-sinatra](https://github.com/MadBomber/sqa_demo-sinatra)** gem. This Sinatra application provides a visual interface for exploring stock analysis, technical indicators, and trading strategies.
+
 ## Architecture
 
 **Core Components:**

data/Rakefile

@@ -1,25 +1,67 @@
 # frozen_string_literal: true
 
-
-
 begin
-  require "tocer/rake/register"
-rescue LoadError => error
-  puts error.message
+  require 'tocer/rake/register'
+rescue LoadError => e
+  puts e.message
 end
 
 Tocer::Rake::Register.call
 
+begin
+  require 'yard'
+
+  namespace :docs do
+    desc 'Build complete documentation site (API markdown + MkDocs)'
+    task :build do
+      puts 'Step 1: Generating API documentation from YARD comments...'
+      sh 'ruby bin/generate_api_docs.rb'
+
+      puts "\nStep 2: Building MkDocs site with Material theme..."
+      sh 'mkdocs build'
 
+      puts "\nDocumentation complete!"
+      puts '  Site: site/index.html'
+      puts '  API Reference: site/api-reference/index.html'
+      puts "\nTo preview: rake docs:serve"
+    end
+
+    desc 'Serve documentation locally with live reload'
+    task :serve do
+      puts 'Starting MkDocs development server...'
+      puts 'View at: http://127.0.0.1:8000'
+      puts 'Press Ctrl+C to stop'
+      sh 'mkdocs serve'
+    end
+
+    desc 'Clean generated documentation files'
+    task :clean do
+      puts 'Cleaning generated documentation...'
+      sh 'rm -rf docs/api-reference site .yardoc'
+      puts 'Done!'
+    end
+
+    desc 'Deploy documentation to GitHub Pages'
+    task deploy: :build do
+      puts "\nDeploying to GitHub Pages..."
+      sh 'mkdocs gh-deploy --force'
+
+      puts "\nDeployment complete!"
+      puts 'Documentation is live at: https://madbomber.github.io/sqa/'
+    end
+  end
+rescue LoadError
+  # YARD not available
+end
 
-require "bundler/gem_tasks"
-require "minitest/test_task"
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
 
 Minitest::TestTask.create(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
+  t.libs << 'test'
+  t.libs << 'lib'
   t.warning = false
-  t.test_globs = ["test/**/*_test.rb"]
+  t.test_globs = ['test/**/*_test.rb']
 end
 
 task default: %i[]

data/docs/advanced/index.md

@@ -76,19 +76,7 @@ Future Period of Performance analysis for risk/reward calculations.
 
 ## Example Workflow
 
-```mermaid
-graph LR
-    A[Historical Data] --> B[Strategy Generator]
-    B --> C[Discovered Patterns]
-    C --> D[Generated Strategies]
-    D --> E[Genetic Programming]
-    E --> F[Optimized Parameters]
-    F --> G[Backtest]
-    G --> H{Results Good?}
-    H -->|Yes| I[Live Stream]
-    H -->|No| D
-    I --> J[Portfolio Management]
-```
+![Advanced Workflow](../assets/images/advanced-workflow.svg)
 
 ## Use Cases