awsquery 0.3.2__tar.gz → 0.5.0__tar.gz

{awsquery-0.3.2 → awsquery-0.5.0}/.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(python3 -m pytest tests/ --cov=src/awsquery --cov-report=term-missing -q)",
       "Bash(mutmut show:*)",
-      "Bash(mutmut:*)"
+      "Bash(mutmut:*)",
+      "Bash(python3:*)"
     ],
     "deny": [],
     "ask": []

{awsquery-0.3.2 → awsquery-0.5.0}/.devcontainer/devcontainer.json

@@ -19,12 +19,7 @@
         "ms-python.black-formatter",
         "ms-python.pylint",
         "ms-python.isort",
-        "ms-python.mypy-type-checker",
-        "charliermarsh.ruff",
-        "littlefoxteam.vscode-python-test-adapter",
-        "tamasfe.even-better-toml",
-        "eamodio.gitlens",
-        "GitHub.vscode-pull-request-github"
+        "ms-python.mypy-type-checker"
       ],
       "settings": {
         "python.defaultInterpreter": "/usr/local/bin/python",
@@ -59,16 +54,11 @@
       }
     }
   },
-  "postCreateCommand": "pip install -e '.[dev]' && pre-commit install",
+  "postCreateCommand": "pip install -e '.[dev]'",
   "postStartCommand": "echo 'Welcome to AWSQuery development environment!'",
   "remoteUser": "vscode",
   "mounts": [
-    {
-      "source": "${localEnv:HOME}/.aws",
-      "target": "/home/vscode/.aws",
-      "type": "bind",
-      "consistency": "cached"
-    }
+    "source=${localEnv:HOME}/.aws,target=/home/vscode/.aws,type=bind,consistency=cached,readonly"
   ],
   "containerEnv": {
     "AWS_REGION": "${localEnv:AWS_REGION}",

awsquery-0.5.0/.github/workflows/multistep-validation.yml

@@ -0,0 +1,66 @@
+---
+name: Multi-Step Validation
+
+# This workflow validates multi-step AWS API call scenarios by checking which
+# operations require parameters that can be resolved from list operations.
+# Runs weekly and on main branch pushes to track API compatibility over time.
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '0 0 * * 0'  # Weekly on Sunday at midnight UTC
+  workflow_dispatch:  # Manual trigger
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    continue-on-error: true  # Don't block other CI jobs if validation fails
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run multi-step validation
+        run: |
+          python scripts/validate_multistep_functions.py
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()  # Upload report even if validation finds issues
+        with:
+          name: multistep-validation-report
+          path: multistep-validation-report.json
+          retention-days: 90
+
+      - name: Check for critical issues
+        if: always()
+        run: |
+          # Parse report and check if broken count is high
+          if [ -f multistep-validation-report.json ]; then
+            broken_count=$(jq '.statistics.multi_step_scenarios.broken' multistep-validation-report.json)
+            echo "Found $broken_count broken multi-step scenarios"
+
+            # Log warning if count is high, but don't fail
+            if [ "$broken_count" -gt 10 ]; then
+              echo "::warning::Found $broken_count broken multi-step scenarios - review may be needed"
+            fi
+          fi

{awsquery-0.3.2 → awsquery-0.5.0}/.gitignore

@@ -214,4 +214,5 @@ __marimo__/
 
 
 sample-responses
-test_env
+test_env
+awsinfo

awsquery-0.5.0/CLAUDE.md

@@ -0,0 +1,318 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`awsquery` is an advanced CLI tool for querying AWS APIs through boto3 with flexible filtering, automatic parameter resolution, and comprehensive security validation. The tool enforces ReadOnly AWS operations for security and provides intelligent response processing with automatic field discovery.
+
+## Development Philosophy
+
+**CRITICAL: ZERO BACKWARD COMPATIBILITY REQUIREMENT**
+
+This project has **ZERO EXTERNAL CONSUMERS** and **NO BACKWARD COMPATIBILITY OBLIGATIONS**. Internal APIs can and should be changed aggressively for code quality improvements.
+
+**MANDATORY PRINCIPLES:**
+- **NEVER maintain backward compatibility** - there are no external users
+- **CLI commands must remain stable** - user-facing behavior should be consistent
+- **Internal APIs are completely mutable** - change function signatures, parameters, return types freely
+- **Delete deprecated code immediately** - no deprecation periods needed
+- **Refactor aggressively** - prioritize clean code over any compatibility concerns
+- **Break internal interfaces without hesitation** - improve designs whenever beneficial
+- **Update tests to match new APIs** - test failures from API changes should be fixed by updating tests
+
+**The only stability requirement is the CLI user experience. All internal code is fair game for radical changes.**
+
+## MANDATORY AGENT USAGE
+
+**ABSOLUTE REQUIREMENT: SPECIALIZED AGENTS MUST BE USED FOR ALL DEVELOPMENT TASKS**
+
+**ZERO TOLERANCE POLICY: MANUAL WORK IS CATEGORICALLY FORBIDDEN**
+
+### Test Development - MANDATORY @agent-test-writer Usage
+- **MUST USE @agent-test-writer** for ALL test creation, modification, and enhancement
+- **NEVER write tests manually** - always delegate to the specialized test-writer agent
+- **MANDATORY for:** Unit tests, integration tests, edge case testing, test refactoring
+- **REQUIRED PROCESS:** Always use test-driven development through the agent
+- **NO EXCEPTIONS:** Any test-related work MUST go through @agent-test-writer
+
+### Python Implementation - MANDATORY @agent-python-infra-automator Usage
+- **MUST USE @agent-python-infra-automator** for ALL Python code implementation
+- **NEVER implement Python code manually** - always delegate to the specialized Python agent
+- **MANDATORY for:** New features, bug fixes, refactoring, optimization, infrastructure code
+- **REQUIRED PROCESS:** Always implement through the specialized agent for best practices
+- **NO EXCEPTIONS:** Any Python development MUST go through @agent-python-infra-automator
+
+### Code Review - MANDATORY @agent-code-reviewer Usage
+- **MUST USE @agent-code-reviewer** AUTOMATICALLY after ANY significant code changes
+- **PROACTIVE REQUIREMENT:** Agent must be invoked WITHOUT user request after commits/merges
+- **MANDATORY for:** All code quality reviews, security analysis, maintainability checks
+- **AUTOMATIC TRIGGERS:** Post-commit, post-merge, after major refactoring
+- **NO EXCEPTIONS:** ALL code changes MUST be reviewed by the specialized agent
+
+### Makefile Operations - MANDATORY @agent-makefile-optimizer Usage
+- **MUST USE @agent-makefile-optimizer** for ANY Makefile-related work
+- **AUTOMATIC TRIGGER:** ANY interaction with Makefile, makefile, GNUmakefile, *.mk files
+- **MANDATORY for:** Build automation, make targets, build system optimization
+- **PROACTIVE REQUIREMENT:** Agent MUST be used automatically when detecting Makefile work
+- **NO EXCEPTIONS:** ALL build system work MUST go through the specialized agent
+
+### Configuration Management - MANDATORY @agent-statusline-setup Usage
+- **MUST USE @agent-statusline-setup** for Claude Code status line configuration
+- **MANDATORY for:** Status line settings, configuration management
+- **NO EXCEPTIONS:** Status line work MUST go through the specialized agent
+
+### Output Styling - MANDATORY @agent-output-style-setup Usage
+- **MUST USE @agent-output-style-setup** for Claude Code output style creation
+- **MANDATORY for:** Output formatting, style configuration
+- **NO EXCEPTIONS:** Output style work MUST go through the specialized agent
+
+### General Research - MANDATORY @agent-general-purpose Usage
+- **MUST USE @agent-general-purpose** for complex multi-step research tasks
+- **MANDATORY for:** Searching keywords/files, complex questions, multi-step tasks
+- **REQUIRED WHEN:** Not confident about finding right match in first few tries
+- **NO EXCEPTIONS:** Complex research MUST go through the specialized agent
+
+### Agent Usage Protocol - ABSOLUTE ENFORCEMENT
+1. **IDENTIFY TASK TYPE:** Determine which specialized agent is required
+2. **AUTOMATIC INVOCATION:** Many agents MUST be triggered proactively/automatically
+3. **PROVIDE COMPLETE CONTEXT:** Include all relevant information for the agent
+4. **FOLLOW AGENT RECOMMENDATIONS:** Implement exactly as specified by the agent
+5. **NO MANUAL OVERRIDE:** Trust the specialized agents completely
+6. **PARALLEL EXECUTION:** Use multiple agents concurrently when possible
+
+### PROACTIVE AGENT TRIGGERS - MANDATORY AUTOMATION
+- **@agent-code-reviewer:** AUTOMATICALLY after significant code changes
+- **@agent-makefile-optimizer:** AUTOMATICALLY when detecting Makefile work
+- **@agent-test-writer:** PROACTIVELY when functions/classes lack test coverage
+- **@agent-python-infra-automator:** PROACTIVELY for infrastructure automation needs
+
+**VIOLATION OF AGENT USAGE IS STRICTLY FORBIDDEN - ALL DEVELOPMENT MUST GO THROUGH SPECIALIZED AGENTS**
+**MANUAL IMPLEMENTATION IS CATEGORICALLY PROHIBITED - AGENTS ARE MANDATORY FOR ALL WORK**
+
+## Development Commands
+
+### Core Commands
+- `make install-dev` - Install development dependencies
+- `make test` - Run all tests (MANDATORY - NO SELECTIVE EXECUTION ALLOWED)
+- `make test-unit` - Run unit tests only (directory-based, not marker-based)
+- `make test-integration` - Run integration tests only (directory-based, not marker-based)
+- `make test-critical` - Run all tests (NO SELECTIVE MARKERS PERMITTED)
+- `make coverage` - Run tests with coverage report (generates htmlcov/index.html)
+- `python3 -m pytest tests/ -v` - Direct pytest execution (NEVER with -m markers)
+
+### Code Quality
+- `make lint` - Run linting checks (flake8, pylint)
+- `make format` - Format code with black and isort
+- `make format-check` - Check code formatting without changes
+- `make type-check` - Run mypy type checking
+- `make security-check` - Run security checks (bandit, safety)
+
+### Docker Development
+- `make docker-build` - Build development container
+- `make shell` - Open interactive shell in container
+- `make test-in-docker` - Run tests in Docker container
+
+### Single Test Execution
+- `python3 -m pytest tests/test_specific.py::TestClass::test_method -v` - Run specific test
+- `python3 -m pytest -k "test_pattern" -v` - Run tests matching pattern
+- `python3 -m pytest tests/ -m "unit" -v` - Run tests with specific markers
+
+## Architecture
+
+### Core Module Structure
+- `src/awsquery/cli.py` - Main CLI interface and argument parsing
+- `src/awsquery/core.py` - Core AWS query execution logic
+- `src/awsquery/security.py` - Security policy validation (ReadOnly enforcement)
+- `src/awsquery/filters.py` - Data filtering and column selection logic
+- `src/awsquery/formatters.py` - Output formatting (table/JSON)
+- `src/awsquery/utils.py` - Utility functions and debug helpers
+
+### Key Features
+- **Smart Multi-Level Calls**: Automatically resolves missing parameters by inferring list operations
+- **Security-First Design**: All operations validated against `policy.json` ReadOnly policy
+- **Flexible Filtering**: Multi-level filtering with `--` separators for different filter types
+- **Auto-Parameter Resolution**: Handles both specific fields and standard AWS patterns (Name, Id, Arn)
+- **Intelligent Response Processing**: Clean extraction of list data, ignoring AWS metadata
+
+### Security Architecture
+The tool enforces security through a comprehensive `policy.json` file that defines allowed ReadOnly AWS operations. All API calls are validated against this policy before execution.
+
+### Testing Structure
+- Unit tests in `tests/unit/` with `@pytest.mark.unit`
+- Integration tests in `tests/integration/` with `@pytest.mark.integration`
+- Critical path tests marked with `@pytest.mark.critical`
+- AWS mocks using moto library marked with `@pytest.mark.aws`
+
+### STRICT Testing Requirements - MUST FOLLOW
+
+#### 🚫 PROHIBITED: Test Anti-Patterns
+**NEVER CREATE:**
+1. **Duplicate Test Files**: Before creating ANY test file, search for existing tests covering the same functionality
+   - Flag tests: Use `test_cli_flags.py` ONLY
+   - Parser tests: Use `test_cli_parser.py` ONLY
+   - Filter tests: Use `test_filter_implementation.py` for real tests, `test_filter_matching.py` for patterns
+2. **Over-Mocked Tests**: Tests that mock the very functions they claim to test
+3. **Mock Assertion Tests**: Tests that only verify `mock.assert_called()` without testing actual behavior
+4. **Nested Mock Contexts**: More than 2 levels of `with patch()` indicates over-mocking
+
+#### ✅ REQUIRED: Test Best Practices
+**ALWAYS:**
+1. **Test Real Implementation**:
+   ```python
+   # GOOD: Tests actual function
+   result = filter_resources(real_data, ["filter"])
+   assert len(result) == expected
+
+   # BAD: Only tests mock
+   mock_filter.return_value = []
+   mock_filter.assert_called_once()
+   ```
+
+2. **Minimal Mocking**: Only mock external dependencies (boto3, file I/O, network)
+   ```python
+   # GOOD: Only mock AWS
+   @patch("boto3.client")
+   def test_feature(mock_client):
+       # Test real code with mocked AWS
+
+   # BAD: Mock everything
+   @patch("filter_resources")
+   @patch("format_output")
+   @patch("parse_args")
+   ```
+
+3. **Consolidate Related Tests**: Group similar tests in one file
+   - All flag position tests → `test_cli_flags.py`
+   - All parser tests → `test_cli_parser.py`
+   - All filter implementation → `test_filter_implementation.py`
+
+4. **Test Edge Cases**: Include malformed input, Unicode, empty values
+   ```python
+   # Test edge cases
+   test_cases = ["", None, "^$", "ˆ", "$^", "^^$$"]
+   ```
+
+5. **Verify Actual Output**: Check real results, not mock calls
+   ```python
+   # GOOD: Verify actual JSON
+   output = format_json_output(data, filters)
+   parsed = json.loads(output)  # Ensures valid JSON
+
+   # BAD: Only check mock called
+   mock_json.assert_called_once()
+   ```
+
+#### 📋 Test Review Checklist
+Before committing ANY test:
+1. ❓ Does a test file for this feature already exist?
+2. ❓ Am I testing real code or just mocks?
+3. ❓ Do assertions verify actual behavior?
+4. ❓ Is mocking limited to external dependencies only?
+5. ❓ Are edge cases covered?
+
+#### 🔍 Finding Duplicate Tests
+```bash
+# Check for existing tests before creating new ones
+grep -r "test.*flag.*position" tests/
+grep -r "test.*parser" tests/
+grep -r "test.*filter" tests/
+```
+
+### 🚫 **ABSOLUTE PROHIBITION: VERBOSE TEST COMMENTS**
+
+**MANDATORY EDICT: UNNECESSARY TEST COMMENTS ARE CATEGORICALLY FORBIDDEN**
+
+**NEVER WRITE THESE TYPES OF COMMENTS:**
+- **TDD Placeholder Comments**: `"""Test the expected structure when -i/--input is implemented."""`
+- **Obvious Restatements**: `"""Test that function returns expected value."""`
+- **Implementation Descriptions**: `"""This test checks if the parser works correctly."""`
+- **Future Implementation Notes**: `"""TODO: implement when feature X is ready."""`
+- **Verbose Process Descriptions**: `"""First we call X, then we check Y, finally we assert Z."""`
+
+**HARD RULES FOR TEST DOCUMENTATION:**
+- **NO REDUNDANT DOCSTRINGS**: Never restate what the method name already says
+- **NO TDD PLACEHOLDERS**: Delete placeholder comments immediately after implementation
+- **NO OBVIOUS COMMENTS**: If the test name explains it, don't repeat in comments
+- **NO VERBOSE EXPLANATIONS**: Code should be self-documenting
+- **ESSENTIAL ONLY**: Comments only for complex edge cases or non-obvious logic
+
+**ACCEPTABLE COMMENTS (RARE):**
+- Complex edge case explanation: `# Unicode circumflex U+02C6 vs ASCII U+005E`
+- Non-obvious assertion: `# Must check stderr, not stdout for debug output`
+- External dependency note: `# Requires specific AWS policy format`
+
+**ENFORCEMENT:**
+- **IMMEDIATE DELETION** of any TDD placeholder comments
+- **ZERO TOLERANCE** for verbose test documentation
+- **CLEAN CODE OVER COMMENTS** - make tests readable through naming and structure
+
+### 🚫 **ABSOLUTE PROHIBITION: PYTEST MARKERS**
+
+**MANDATORY EDICT: PYTEST MARKERS ARE CATEGORICALLY FORBIDDEN AND COMPLETELY BANNED**
+
+**UNBREAKABLE RULES:**
+- **NEVER, EVER, UNDER ANY CIRCUMSTANCES** add `@pytest.mark.*` decorators to tests
+- **ZERO TOLERANCE** for selective test execution markers (`@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.slow`, `@pytest.mark.critical`, etc.)
+- **ALL TESTS MUST ALWAYS RUN** - no exceptions, no conditional execution, no selective filtering
+- **IMMEDIATE DELETION** required for any pytest markers discovered in code
+- **NO EXEMPTIONS** - this rule is immutable and non-negotiable
+
+**RATIONALE:**
+- Selective test execution leads to **INCOMPLETE COVERAGE** and **HIDDEN FAILURES**
+- Markers create **FALSE CONFIDENCE** by allowing tests to be skipped
+- **ALL TESTS ARE CRITICAL** - none should be optional or conditional
+- Complete test suite execution is **MANDATORY FOR QUALITY ASSURANCE**
+
+**ENFORCEMENT:**
+- Any pytest markers found in code must be **REMOVED IMMEDIATELY**
+- Makefile commands must **NEVER USE** `-m "marker"` syntax
+- Test discovery must be **PURELY DIRECTORY-BASED** (tests/unit/, tests/integration/)
+- **NO EXCEPTIONS** - this is an inviolable principle
+
+**ALLOWED:** `@pytest.mark.parametrize` ONLY (for test parameterization, not selection)
+**FORBIDDEN:** All other `@pytest.mark.*` decorators without exception
+
+### Configuration Files
+- `pyproject.toml` - Main project configuration with dependencies and tool settings
+- `pytest.ini` - Test configuration with coverage settings (80% minimum)
+- `Makefile` - Comprehensive development and AWS sampling commands
+
+## Git Commit Guidelines
+
+### MANDATORY: Concise Commit Messages
+
+**STRICT REQUIREMENTS:**
+- **Single-line summary ONLY** - Maximum 72 characters
+- **No multi-line descriptions** - Keep it to one concise line
+- **No bullet points** - Avoid listing multiple changes
+- **No verbose explanations** - Code speaks for itself
+- **Combine related changes** - One commit for logically grouped changes
+
+**GOOD EXAMPLES:**
+- `Fix parameter auto-wrapping for list types`
+- `Add validation script with feature coverage`
+- `Skip Tag filter validation (runtime transform)`
+- `Update tests for new parameter handling`
+
+**BAD EXAMPLES:**
+- ❌ Multi-line commits with bullets and explanations
+- ❌ "Add X, fix Y, update Z, refactor A, improve B"
+- ❌ Detailed descriptions of implementation choices
+- ❌ Multiple unrelated changes in one commit
+
+**COMMIT FORMAT:**
+```
+<short description>
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+**ENFORCEMENT:**
+- Commits MUST be atomic and focused
+- Summary line MUST be clear and complete
+- NO additional description beyond the trailer
+- Related changes MUST be combined into single commit
+- Unrelated changes MUST be separate commits

{awsquery-0.3.2 → awsquery-0.5.0}/Dockerfile

@@ -34,7 +34,6 @@ WORKDIR /app
 
 # Copy only essential files for package installation
 COPY pyproject.toml .
-COPY policy.json .
 
 # Copy source code (minimal for installation)
 COPY src/ ./src/

{awsquery-0.3.2 → awsquery-0.5.0}/Makefile

@@ -40,13 +40,13 @@ test: ## Run all tests
 	python3 -m pytest tests/ -v
 
 test-unit: ## Run unit tests only
-	python3 -m pytest tests/unit/ -v -m "unit"
+	python3 -m pytest tests/unit/ -v
 
 test-integration: ## Run integration tests only
-	python3 -m pytest tests/integration/ -v -m "integration"
+	python3 -m pytest tests/integration/ -v
 
-test-slow: ## Run slow tests
-	python3 -m pytest tests/ -v -m "slow"
+test-slow: ## Run all tests (no selective marking allowed)
+	python3 -m pytest tests/ -v
 
 test-fast: ## Run all tests with parallel execution (optimized for Python 3.8-3.10)
 	python3 -m pytest tests/ -n auto -q
@@ -57,8 +57,8 @@ test-unit-fast: ## Run unit tests with parallel execution (2-5 seconds)
 test-integration-fast: ## Run integration tests with parallel execution
 	python3 -m pytest tests/integration/ -n auto -q
 
-test-critical: ## Run critical path tests
-	python3 -m pytest tests/ -v -m "critical"
+test-critical: ## Run all tests (no selective marking allowed)
+	python3 -m pytest tests/ -v
 
 coverage: ## Run tests with coverage report
 	python3 -m pytest tests/ --cov=src/awsquery --cov-report=term-missing --cov-report=html