direct-cli 0.2.5__tar.gz → 0.2.7__tar.gz

direct_cli-0.2.7/.github/workflows/api-coverage.yml

@@ -0,0 +1,152 @@
+name: API Coverage
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+jobs:
+  test-and-report:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run fast coverage suites
+        run: |
+          pytest -q tests/test_api_coverage.py tests/test_dry_run.py tests/test_cli.py tests/test_comprehensive.py tests/test_reports_drift.py
+
+      - name: Build API coverage report
+        run: |
+          python scripts/build_api_coverage_report.py > api_coverage_report.json
+
+      - name: Publish API coverage summary
+        run: |
+          python - <<'PY' >> "$GITHUB_STEP_SUMMARY"
+          import json
+          from pathlib import Path
+
+          report = json.loads(Path("api_coverage_report.json").read_text())
+          summary = report["summary"]
+          print("## API coverage summary")
+          print()
+          print(f"- Services checked: {summary['services_checked']}")
+          print(f"- Missing methods: {summary['missing_service_methods']}")
+          print(f"- Unexpected methods: {summary['unexpected_service_methods']}")
+          print(f"- Strict parity OK: {summary['strict_parity_ok']}")
+          print(f"- Non-WSDL services: {len(report['non_wsdl_services'])}")
+          print(f"- CLI helpers: {len(report['cli_helpers'])}")
+          PY
+
+      - name: Upload API coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-coverage-report-py${{ matrix.python-version }}
+          path: api_coverage_report.json
+
+  monitor-live-wsdl:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check live WSDL drift
+        run: |
+          python scripts/check_wsdl_drift.py > wsdl_drift_report.json
+
+      - name: Publish WSDL drift summary
+        if: always()
+        run: |
+          python - <<'PY' >> "$GITHUB_STEP_SUMMARY"
+          import json
+          from pathlib import Path
+
+          report = json.loads(Path("wsdl_drift_report.json").read_text())
+          print("## WSDL drift summary")
+          print()
+          print(f"- Services checked: {report['services_checked']}")
+          print(f"- Missing cache files: {report['missing_cache_count']}")
+          print(f"- Drifted services: {report['drift_count']}")
+          for item in report["drift"][:10]:
+              print(f"- Drift: {item['service']}")
+          PY
+
+      - name: Upload WSDL drift report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: wsdl-drift-report
+          path: wsdl_drift_report.json
+
+  monitor-live-reports:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check live reports drift
+        run: |
+          python scripts/check_reports_drift.py > reports_drift_report.json
+
+      - name: Publish reports drift summary
+        if: always()
+        run: |
+          python - <<'PY' >> "$GITHUB_STEP_SUMMARY"
+          import json
+          from pathlib import Path
+
+          report = json.loads(Path("reports_drift_report.json").read_text())
+          print("## Reports drift summary")
+          print()
+          print(f"- Sources checked: {report.get('sources_checked', 0)}")
+          print(f"- Missing cache files: {report.get('missing_cache_count', 0)}")
+          print(f"- Drifted sections: {report.get('drift_count', 0)}")
+          for item in report.get("drift", [])[:10]:
+              print(f"- Drift: {item['section']}")
+          PY
+
+      - name: Upload reports drift report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: reports-drift-report
+          path: reports_drift_report.json

{direct_cli-0.2.5 → direct_cli-0.2.7}/AGENTS.md

@@ -6,6 +6,122 @@ This document provides essential information for AI coding agents working on the
 
 Direct CLI is a command-line interface for the Yandex Direct API, built with Python and Click. It provides commands for managing campaigns, ad groups, ads, keywords, reports, and other Yandex Direct resources.
 
+## CLI Convention
+
+The current CLI convention is defined as follows.
+
+### CLI Contract
+
+The canonical command shape is:
+
+```bash
+direct <group> <command> [flags]
+```
+
+Naming rules:
+
+- `group`:
+  - lowercase ASCII only
+  - no underscores
+  - multiword groups are concatenated
+  - examples: `dynamicads`, `smartadtargets`, `negativekeywordsharedsets`
+
+- `command`:
+  - lowercase only
+  - multiword commands use kebab-case
+  - examples: `get`, `set-bids`, `check-campaigns`, `has-search-volume`
+
+### Input Rules
+
+- All user-facing input must be passed only through typed CLI flags.
+- `--json` is not part of the public CLI contract.
+- User-facing parameters must not be passed through `--json`.
+- The CLI must not accept `SelectionCriteria`, nested payloads, update payloads, bidding rules, or any other user-facing command input through `--json`.
+- Typed flags and JSON blobs must not be mixed as part of one public command contract.
+- If the API requires a complex object, the CLI must expose explicit flags or subcommands instead of forwarding raw JSON.
+
+### Command Formatting Rules
+
+- Every canonical CLI command must be written strictly on a single line.
+- Multi-line command formatting is not allowed.
+- Shell line continuation using `\` is forbidden in canonical documentation, help text, tests, and examples.
+
+Allowed:
+
+```bash
+direct dictionaries get-geo-regions --region-ids 225,187 --fields GeoRegionId,GeoRegionName
+```
+
+Not allowed:
+
+```bash
+direct dictionaries get-geo-regions \
+  --region-ids 225,187 \
+  --fields GeoRegionId,GeoRegionName
+```
+
+### Flag Design Rules
+
+- List inputs use comma-separated CLI syntax where appropriate.
+- Money and bid values stay human-readable in CLI input and are converted internally to the API wire format.
+- Selector fields remain explicit flags, for example:
+  - `--id`
+  - `--campaign-id`
+  - `--adgroup-id`
+- Nested API structures must be projected into typed flags instead of blob JSON.
+- Help text must not advertise JSON as an alternative input path.
+
+### Datetime Rules
+
+- Datetime parameters must be passed in the format `YYYY-MM-DDTHH:MM:SS`.
+- Datetime values must be passed as a single shell token.
+- Canonical examples must not use timezone suffixes like `Z`.
+- Canonical examples must not use quoted space-separated datetime values.
+
+Use:
+
+```bash
+direct changes check-campaigns --timestamp 2026-04-14T00:00:00
+```
+
+Do not use:
+
+```bash
+direct changes check-campaigns --timestamp 2026-04-14T00:00:00Z
+direct changes check-campaigns --timestamp "2026-04-14 00:00:00"
+```
+
+### Documentation Contract
+
+- `README` must use only canonical syntax.
+- `README` must use only single-line command examples.
+- Canonical examples must not contain `--json`.
+- Help output and tests must enforce the same contract.
+
+### Examples
+
+Valid canonical examples:
+
+```bash
+direct campaigns get --ids 1,2,3
+direct changes check-campaigns --timestamp 2026-04-14T00:00:00
+direct keywordsresearch has-search-volume --keywords "buy laptop,buy desktop"
+direct dynamicads set-bids --id 789 --bid 12.5
+direct dictionaries get-geo-regions --region-ids 225 --fields GeoRegionId,GeoRegionName
+```
+
+Invalid examples:
+
+```bash
+direct dictionaries get-geo-regions --json '{"GeoRegionIds":[225]}' --fields GeoRegionId,GeoRegionName
+direct dynamicads set-bids --id 789 --bid 12.5 --json '{"StrategyPriority":"HIGH"}'
+direct dictionaries get-geo-regions \
+  --region-ids 225 \
+  --fields GeoRegionId,GeoRegionName
+direct changes check-campaigns --timestamp 2026-04-14T00:00:00Z
+direct changes check-campaigns --timestamp "2026-04-14 00:00:00"
+```
+
 ## Build, Test, and Lint Commands
 
 ### Installation