From baf95a67c543f392c2bf2dcac0bfd249dd219f61 Mon Sep 17 00:00:00 2001 From: Brad Penney Date: Sun, 26 Oct 2025 08:45:14 -0300 Subject: [PATCH] Added instructions for AI-assisted development workflows Signed-off-by: Brad Penney --- .github/copilot-instructions.md | 29 +++++++ .github/instructions/python.instructions.md | 42 ++++++++++ README.md | 93 +++++++++++++++++++-- 3 files changed, 157 insertions(+), 7 deletions(-) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/python.instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..9da6609 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,29 @@ +# Firestone-lib Copilot Instructions + +## Project Scope +- Firestone-lib bundles shared capabilities used across the broader Firestone ecosystem: CLI utilities, schema tooling, and lightweight helpers. +- Consumers expect stable interfaces; keep changes backward-compatible unless a coordinated release states otherwise. + +## Ecosystem Awareness +- `firestone` consumes these helpers for spec generation; validate CLI or resource-facing changes against its workflows (see `firestone/__main__.py` and `firestone/spec/`). +- `forevd` depends on `firestone_lib.cli` for logging and config parsing—document any behavior shifts so the proxy can bump in lockstep. +- If a change requires synchronized updates, land `firestone-lib` first and surface follow-up PR references in the release notes or change description. + +## Architecture Overview +- `firestone_lib/cli.py`: click-based helpers (logging bootstrap, custom param types, async wrappers). Extend here when exposing new CLI behavior. +- `firestone_lib/resource.py`: schema ingestion/validation built around `jsonref` and `jsonschema`; reuse its loaders to keep `$ref` support intact. +- `firestone_lib/utils.py`: string-centric helpers used across Firestone services. +- `firestone_lib/resources/`: packaged configuration assets (for example, logging config in `logging/cli.conf`). +- Tests mirror the package layout under `test/`. + +## Build & Automation +- Poetry drives installs, builds, and test runs (`poetry install`, `poetry build`, `poetry run pytest`). +- Continuous integration is handled via `.github/workflows/pr.yml`; expect linting and tests to run on every pull request. + +## Collaboration Notes +- Before adding new modules or resources, confirm they fit the existing structure; prefer evolving current packages. +- Keep logging messages meaningful and consistent with existing `_LOGGER` usage. +- When working on CLI or schema changes, ensure templating, environment-variable substitution, and file loading continue to behave as they do today. + +## Coding Conventions +- For language-level expectations (Python 3.9+ compatibility, mandatory type hints, pytest usage, formatting requirements), follow `.github/instructions/python.instructions.md`. diff --git a/.github/instructions/python.instructions.md b/.github/instructions/python.instructions.md new file mode 100644 index 0000000..d6ad647 --- /dev/null +++ b/.github/instructions/python.instructions.md @@ -0,0 +1,42 @@ +--- +applyTo: '**/*.py' +--- + +# Python Coding Guidelines + +These rules combine firestone-lib conventions with widely accepted Python practices. Where industry defaults differ, follow the repo-specific rule noted here. + +They intentionally mirror the upstream Firestone project so moving changes between repositories stays predictable; if you spot a divergence, flag it so we can reconcile both sides. + +## Runtime & Dependencies +- Target Python **3.9+** as defined in `pyproject.toml`; keep code compatible with the supported range (even if newer features are tempting). +- Manage dependencies through Poetry and keep `pyproject.toml` and `poetry.lock` in sync when adding or bumping packages. + +## Type Hints & Docstrings +- Annotate every function and method (including inner helpers) with precise parameter and return types. +- Prefer modern `typing` / `collections.abc` generics (`Iterator`, `Mapping`, `Sequence`, etc.) in annotations. +- Keep docstrings concise one-liners or short paragraphs consistent with existing modules; use reST-style sections only when they add value. + +## Imports & Structure +- Use absolute imports; keep them grouped stdlib → third-party → local, separated by blank lines. +- Follow existing patterns (`os`, `io`, etc.) for filesystem helpers unless there is a clear benefit to switching to `pathlib.Path`. +- Keep module-level constants in uppercase with clear names. + +## Coding Style +- Format with Black (100-character line length, already configured). +- Obey the pylint settings in `pyproject.toml`; choose descriptive identifiers within those constraints. +- Use f-strings, `Enum`/`Literal` where they clarify intent, and explicit encodings when touching files. +- Favor context managers for I/O and structured error handling (catch specific exceptions only when you can recover). + +## Testing +- Place tests under `test/` and write them using pytest idioms (`assert`, fixtures, parametrization). Migrating legacy unittest code to pytest is encouraged when you touch it. +- Include or update tests for any behavioral change and keep them deterministic (use mocks, temp dirs, or fixtures as needed). +- Validate locally with `poetry run pytest`. + +## Error Handling & Logging +- Raise specific exceptions with actionable messages. +- Log through `logging.getLogger(__name__)` (existing `_LOGGER` pattern) and keep messages concise but informative. + +## Security & Robustness +- Avoid executing untrusted input and double-check file paths or templates before use. +- Preserve json/yaml loading safeguards already present in the repo (for example, `safe_load`). diff --git a/README.md b/README.md index 96d3a61..75bd052 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,94 @@ ![PR Build](https://github.com/ebourgeois/firestone-lib/actions/workflows/pr.yml/badge.svg) - # firestone-lib -This library is primarily used by the firestone project and anyone using the firestone project. +Firestone-lib is a shared toolkit that powers Firestone services and any downstream automation that needs to load schema resources, wire up CLI utilities, or work with reusable helpers. It packages common building blocks so projects across the ecosystem can stay consistent without duplicating code. -# building and testing +## Firestone Ecosystem -``` -brew install poetry +This library supports companion projects that build on the same patterns: + +- [`firestone`](https://github.com/firestoned/firestone) turns JSON Schema resources into OpenAPI, AsyncAPI, CLI, and Streamlit artifacts. +- [`forevd`](https://github.com/firestoned/forevd) uses `firestone-lib`'s CLI and templating helpers to render Apache proxy configs with pluggable auth. + +## Features +- Schema helpers that load JSON or YAML, resolve `$ref` links with `jsonref`, and validate against canonical Firestone schemas. +- CLI utilities built on top of `click`, including rich parameter types, templated input handling, and logging bootstrap helpers. +- Lightweight string utilities (for example, `split_capitalize`) that keep naming logic consistent across projects. +- Bundled configuration assets such as default logging definitions. + +## Project Structure +- `firestone_lib/cli.py` – click helpers, logging setup, and custom parameter converters. +- `firestone_lib/resource.py` – schema loading, templating, and validation logic. +- `firestone_lib/utils.py` – general-purpose helpers shared by Firestone services. +- `firestone_lib/resources/` – packaged config files (for example, `logging/cli.conf`). +- `test/` – pytest-based regression and unit tests covering the public surface. + +## Installation + +### Prerequisites +- Python 3.9 or newer (see `pyproject.toml` for the precise compatibility range) +- [Poetry](https://python-poetry.org/docs/#installation) + +### From source +```bash poetry install -poetry build -poetry run pytest test ``` + +This installs the library and all development dependencies into Poetry's virtual environment. To enter the environment, run `poetry shell` or prefix commands with `poetry run`. + +### From PyPI (consumer projects) +```bash +pip install firestone-lib +``` + +## Quick Start +Loading and validating a resource definition: + +```python +from firestone_lib import resource + +schema = resource.get_resource_schema("path/to/resource.yaml") +# Raises jsonschema.ValidationError on failure +resource.validate({"apiVersion": "v1", "kind": "Example", "spec": {}}) +``` + +Setting up CLI logging from a packaged configuration: + +```python +from firestone_lib import cli + +cli.init_logging("firestone_lib.resources.logging", "cli.conf") +``` + +Normalizing identifiers for UI display: + +```python +from firestone_lib import utils + +print(utils.split_capitalize("firestone_resource")) # Firestone Resource +``` + +## Development Workflow +- Use type hints and reStructuredText docstrings throughout the codebase (see `.github/instructions/python.instructions.md` for the full style guide). +- Consult `.github/copilot-instructions.md` for architecture notes and expectations when planning larger changes. +- Format changes with `poetry run black .` (line length 100) only when necessary. +- Keep logging statements descriptive and consistent with existing `_LOGGER` usage. + +## Testing + +Run the test suite before submitting changes: + +```bash +poetry run pytest +``` + +CI mirrors this command through `.github/workflows/pr.yml`. + +## Contributing + +Issues and pull requests are welcome. When proposing a change, include the context, tests, and any documentation updates that ensure downstream services can adopt the update smoothly. + +## License + +Licensed under the Apache License 2.0 – see `LICENSE` for details.