pinky-tools 0.1.0.dev1__tar.gz

pinky_tools-0.1.0.dev1/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ scripts/
+
+      - name: Format check
+        run: ruff format --check src/ scripts/
+
+      - name: Type check
+        run: mypy src/pinky_tools/
+
+      - name: Security scan
+        run: bandit -r src/pinky_tools/ -ll

pinky_tools-0.1.0.dev1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.dev*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    permissions:
+      contents: read
+      id-token: write  # required for trusted publishing (OIDC)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pinky_tools-0.1.0.dev1/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+on:
+  push:
+    branches: [main]
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Read version
+        id: version
+        run: echo "version=$(grep '^version' pyproject.toml | cut -d'"' -f2)" >> $GITHUB_OUTPUT
+      - name: Guard — no .dev version on main
+        run: |
+          if [[ "${{ steps.version.outputs.version }}" == *".dev"* ]]; then
+            echo "❌ version .dev sur main — bumper la version avant de merger"
+            exit 1
+          fi
+      - name: Create tag
+        run: |
+          git tag "v${{ steps.version.outputs.version }}"
+          git push origin "v${{ steps.version.outputs.version }}"
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build
+        run: pip install build
+      - name: Build
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pinky_tools-0.1.0.dev1/.gitignore

@@ -0,0 +1,19 @@
+# MkDocs
+docs/assets/
+site/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# macOS
+.DS_Store

pinky_tools-0.1.0.dev1/.pre-commit-config.yaml

@@ -0,0 +1,116 @@
+---
+# =============================================================================
+# .pre-commit-config.yaml — pinky-tools
+# =============================================================================
+# Install:
+#   pip install pre-commit
+#   pre-commit install
+#   pre-commit install --hook-type commit-msg
+#
+# Update standard hooks:
+#   pre-commit autoupdate
+# =============================================================================
+default_install_hook_types: [pre-commit, commit-msg]
+
+repos:
+  # ── Formatting: trailing spaces + newline ─────────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  # ── Formatting: Markdown ──────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: mdformat
+        name: mdformat
+        entry: mdformat
+        language: system
+        files: ^README\.md$
+
+  # ── Security: secrets & forbidden files ──────────────────────────────────
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  # ── Security: alternative secret detection ────────────────────────────────
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ["--baseline", ".secrets.baseline"]
+        exclude: ^docs/
+
+  # ── Python: ruff lint + format ────────────────────────────────────────────
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.9
+    hooks:
+      - id: ruff-check
+        args: [--no-fix]
+      - id: ruff-format
+        args: [--check]
+
+  # ── Python: type checking ─────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: system
+        types: [python]
+        args: [--ignore-missing-imports]
+        files: ^src/
+
+  # ── Python: security ─────────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: bandit
+        name: bandit
+        entry: bandit
+        language: system
+        pass_filenames: false
+        args: [-r, src/, -ll]
+
+  # ── Zero-width spaces (copy-paste from Outlook/Teams) ────────────────────
+  - repo: local
+    hooks:
+      - id: check-zws
+        name: "[ZWS] Invisible characters (zero-width)"
+        entry: python scripts/hooks/check_zws.py
+        language: system
+        pass_filenames: true
+
+  # ── Typed API guard ──────────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: check-typed-api
+        name: "[TYPED-API] No raw dict/tuple/set in public annotations"
+        entry: python scripts/hooks/check_typed_api.py
+        language: system
+        types: [python]
+        files: ^src/
+
+  # ── Snowpark / Core API conventions ──────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: check-snowpark-api
+        name: "[SNOWPARK-API] No session.sql(), canonical method names"
+        entry: python scripts/hooks/check_snowpark_api.py
+        language: system
+        types: [python]
+        files: ^src/
+
+  # ── Employer reference guard ──────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: check-forbidden-keywords
+        name: "[FORBIDDEN] Employer references"
+        entry: python scripts/hooks/check_forbidden_keywords.py
+        language: system
+        pass_filenames: true

pinky_tools-0.1.0.dev1/.secrets.baseline

@@ -0,0 +1,127 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {},
+  "generated_at": "2026-06-04T22:13:47Z"
+}

pinky_tools-0.1.0.dev1/AGENT.md

@@ -0,0 +1,80 @@
+# AGENT.md — pinky-tools
+*Update date : 2026-05-31 12:10*
+
+Local dev CLI for Snowflake data engineers.
+Part of the pinky suite.
+
+---
+
+## What this repo is
+
+`pinky-tools` is the developer-side CLI — it covers the local dev loop that
+`pinky-provider` does not: run a stored procedure locally, generate the README
+from AST, compare outputs across versions, and validate naming conventions.
+
+The CLI entry point is `pinky`. See [`CONTEXT.md`](CONTEXT.md) for naming.
+
+> **Status: design phase.** See [`docs/INDEX.md`](docs/INDEX.md) for the full design.
+
+---
+
+## Repository structure (target)
+
+```
+pinky-tools/
+├── src/
+│   └── pinky_tools/
+│       ├── cli.py             ← click entry point
+│       ├── run.py             ← local SP runner
+│       ├── readme.py          ← README generator (AST + live enrichment)
+│       ├── regression.py      ← output comparator (CSV / XLSX)
+│       └── validate_name.py   ← naming convention validator
+├── docs/                      ← see docs/INDEX.md for the full map
+│   ├── explanation/           ← design.md · features.md
+│   └── adr/
+├── tests/
+├── pyproject.toml
+└── AGENT.md                   ← this file
+```
+
+---
+
+## Stack
+
+- Python 3.11
+- `click` + `rich-click` — CLI
+- `rich` — terminal output
+- `snowflake-snowpark-python` — session for `run` command
+- `openpyxl` — XLSX support for `regression`
+
+---
+
+## CLI commands
+
+| Command | What it does |
+|---------|-------------|
+| `pinky run <file>` | Execute a Snowpark `.py` file against a live Snowflake connection |
+| `pinky readme` | Generate README from Python AST extraction |
+| `pinky regression <f1> <f2>` | Compare two output files (CSV / XLSX) |
+| `pinky validate-name <name>` | Validate a schema/repo name against the naming convention |
+
+---
+
+## Commit convention
+
+Format: `<emoji> <type>(<scope>): <description>`
+
+Scopes: `setup` | `cli` | `run` | `readme` | `regression` | `validate` | `docs` | `ci`
+
+See workspace-level CLAUDE.md for the full emoji ↔ type table.
+
+---
+
+## Branch strategy
+
+```
+main        ← stable, PR required
+develop     ← integration, PR required from feature/*
+feature/*   ← one task = one branch
+hotfix/*    ← urgent fix from main
+```

pinky_tools-0.1.0.dev1/CONTEXT.md

@@ -0,0 +1,18 @@
+# CONTEXT.md — pinky-tools
+*Update date : 2026-05-31 12:10*
+
+Single source of truth for naming in this repo.
+
+| Term (preferred) | Avoid | Definition |
+|---|---|---|
+| `pinky` | `pythia`, `snowflake-tools` | CLI entry point — the `pinky <command>` invocation |
+| `run` | `runner`, `local_runner` | Command that executes a Snowpark `.py` file against a live Snowflake connection |
+| `readme` | `generate-readme`, `ast-readme` | Command that generates a README from Python AST extraction |
+| `regression` | `compare`, `diff` | Command that compares two output files (CSV / XLSX) |
+| `validate-name` | `check-name`, `name-check` | Command that validates a schema/repo name against the naming convention |
+| SP | stored procedure | A Snowpark Python stored procedure |
+| project | repo, pipeline | A data project following the 1-schema = 1-repo convention |
+
+## Flagged ambiguities
+
+- **`pinky` vs `pythia`**: the CLI entry point is `pinky`. `pythia` appears in legacy docs and the rename is being applied progressively — always use `pinky` in new code and docs.

pinky_tools-0.1.0.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pinky-and-co
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pinky_tools-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: pinky-tools
+Version: 0.1.0.dev1
+Summary: Local dev CLI for Snowflake data engineers
+Project-URL: Homepage, https://github.com/pinky-and-co/pinky-tools
+Project-URL: Repository, https://github.com/pinky-and-co/pinky-tools
+Project-URL: Issues, https://github.com/pinky-and-co/pinky-tools/issues
+Author: pinky-and-co
+License: MIT License
+        
+        Copyright (c) 2026 pinky-and-co
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,data-engineering,snowflake,snowpark
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: click
+Requires-Dist: openpyxl
+Requires-Dist: rich
+Requires-Dist: rich-click
+Requires-Dist: snowflake-snowpark-python
+Provides-Extra: dev
+Requires-Dist: bandit; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pinky-tools
+
+*Update date : 2026-05-31 12:10*
+
+Local dev CLI for Snowflake data engineers — run stored procedures locally, generate README docs, and validate naming conventions.
+
+Part of the [pinky-and-co](https://github.com/pinky-and-co) suite.
+
+## Install
+
+```bash
+pip install pinky-tools
+```
+
+## Quick start
+
+```bash
+pinky run resources/procedure/my_sp.py
+pinky readme
+pinky validate-name "financial__workday_to_altaix__compensation"
+```
+
+## Docs
+
+- [Design](docs/explanation/design.md)
+- [Features & roadmap](docs/explanation/features.md)
+- [ADRs](docs/adr/)
+
+______________________________________________________________________
+
+MIT License

pinky_tools-0.1.0.dev1/README.md

@@ -0,0 +1,31 @@
+# pinky-tools
+
+*Update date : 2026-05-31 12:10*
+
+Local dev CLI for Snowflake data engineers — run stored procedures locally, generate README docs, and validate naming conventions.
+
+Part of the [pinky-and-co](https://github.com/pinky-and-co) suite.
+
+## Install
+
+```bash
+pip install pinky-tools
+```
+
+## Quick start
+
+```bash
+pinky run resources/procedure/my_sp.py
+pinky readme
+pinky validate-name "financial__workday_to_altaix__compensation"
+```
+
+## Docs
+
+- [Design](docs/explanation/design.md)
+- [Features & roadmap](docs/explanation/features.md)
+- [ADRs](docs/adr/)
+
+______________________________________________________________________
+
+MIT License

pinky_tools-0.1.0.dev1/docs/adr/0001-click-over-argparse.md

@@ -0,0 +1,18 @@
+# ADR-0001 — click over argparse
+Status: accepted
+Date: 2026-05-31
+
+## Context
+
+The CLI commands migrated from legacy use `argparse`. `pinky-provider` had the
+same choice and already decided on `click` (see pinky-provider ADR-0002).
+
+## Decision
+
+Use `click` + `rich-click` for all CLI commands — same decision as `pinky-provider`.
+
+## Consequences
+
+Consistent CLI experience across the suite. `rich-click` adds automatic Rich
+formatting to help text with zero extra effort. Aligns with `pinky-provider`
+so conventions and patterns are shared.

pinky_tools-0.1.0.dev1/docs/adr/0002-i18n-env-var-from-day-one.md

@@ -0,0 +1,25 @@
+# ADR-0002 — i18n via env var from day one
+Status: accepted
+Date: 2026-05-31
+
+## Context
+
+CLI output strings need to be consistent and localizable. The suite is open-source
+and may be used in both English and French contexts.
+
+## Decision
+
+All CLI-facing strings are defined as keyed templates in `i18n/en.py` and `i18n/fr.py`.
+Locale is resolved in order: `locale` argument → `SNOWFLAKE_TOOLS_LOCALE` env var → `en`.
+Unsupported locales fall back silently to `en`. Missing keys return the key itself — no crash.
+
+```python
+t = get_translator()          # uses env var or "en"
+t = get_translator("fr")      # force French
+print(t("export.done", path="/tmp/out.xlsx"))
+```
+
+## Consequences
+
+Zero hardcoded output strings in command implementations. Adding a new locale = adding
+one file in `i18n/`. Applies to all commands, not just `pinky export`.

pinky_tools-0.1.0.dev1/docs/adr/0003-export-last-select-wins.md

@@ -0,0 +1,21 @@
+# ADR-0003 — `pinky export`: last-SELECT-wins execution model
+Status: accepted
+Date: 2026-05-31
+
+## Context
+
+A `.sql` file passed to `pinky export` may contain multiple statements: session
+variable SETs, intermediate CTEs, DML warm-ups, and a final SELECT to export.
+Only one result is exported to xlsx.
+
+## Decision
+
+The last statement in the file is the one exported. All preceding statements are
+executed for side effects (SET, DML, intermediate SELECTs). If the last statement
+is not a SELECT, the command fails immediately with a clear error message.
+
+## Consequences
+
+Forces good SQL hygiene — the export query is always the last and most visible
+thing in the file. No silent partial exports. Callers know exactly which result
+they will get without reading the implementation.