Skip to content

Added instructions for AI-assisted development workflows #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bradpenney wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Added instructions for AI-assisted development workflows #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
42 changes: 42 additions & 0 deletions .github/instructions/python.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`).
93 changes: 86 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading