@gspothq/cli 0.0.0-stage → 0.1.0

package/configurations/language/python/rules/DESIGN.md

@@ -0,0 +1,136 @@
+# Python Design
+
+## Functions
+
+I/O never hides in a helper that looks like a pure transformation. Declare an ordinary no-result case in the return type and return an explicit `None`; input that
+violates the API contract raises a specific exception. A generator owns its resource lifetime
+explicitly and documents its yielded values and cleanup contract. A partially consumed
+generator never holds a resource implicitly. A generator expression serves a consumer that
+only needs a lazy projection. Comprehensions serve one mapping or one filter; nested
+logic, several conditions, mutation, or a transformation that needs explanation gets an ordinary loop so
+its ordering stays visible.
+
+### Function conventions
+
+<!-- level: all -->
+
+A function owns one responsibility. Name it for its action and domain concept, except required framework callback names. Make side effects clear in its name or docstring. Plain
+functions and explicit data flow come before classes. When a function passes a limit, split
+out a step with a real name. If the limit does not fit the code, ask the user to raise it:
+
+```python
+"""Select recent message text under a validated nonnegative limit."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def trim_history_messages(messages: Sequence[str], max_messages: int) -> list[str]:
+    """Return at most the requested number of recent messages."""
+    if max_messages == 0:
+        return []
+    if len(messages) <= max_messages:
+        return list(messages)
+    return list(messages[-max_messages:])
+
+
+__all__ = ["trim_history_messages"]
+```
+
+A nested function closes over a local value to make the outer function clearer, keeping its
+captured state and lifetime explicit. It never exists to
+hide a helper from users or to turn a directly usable expression into a local call. A
+module-level private helper serves reusable logic that a nested function hides. A conversion that a named helper only
+forwards has its body placed directly at the call site.
+
+Write a lambda as a one-line expression at its consumer, such as
+a sorting key `lambda item: item.name`. Prefer a generator expression or `operator` function over
+`map()` or `filter()` with a lambda. Use a `def` for anything longer. A conditional expression
+holds one binary choice, `"stream" if is_streaming else "batch"`, and a path with several
+operations gets `if` branches.
+
+## Classes
+
+A class exists for real state, invariants, or behavior. Keep a coordinating function without
+polymorphism as a function. Never group static functions into a class. Related
+classes that form one contract, such as schemas, exceptions, protocols, and their records,
+stay together, and modules split by independent responsibility rather than class count. Plain
+data has public attributes, internal attributes carry one leading
+underscore, and a double underscore only protects a base class from subclass collisions.
+
+`__init__` stays small, takes the values the class needs rather than the external objects
+that carry them, and validates invariants. Keep it separate from database rows, object-relational mapping (ORM) objects,
+API payloads, CLI namespaces, or provider responses. An external representation enters
+through a classmethod named constructor such as `from_row` or `from_payload` when the class
+owns that conversion. Neither `ClassName(**external_attributes)` nor a
+constructor that only renames the initializer handles that conversion.
+
+Loading, serialization, and validation systems stay outside the
+business object. Keep a derived attribute cheap and deterministic. Build it from initialized
+fields; a named constructor handles derivation through I/O or complex parsing.
+
+Use a dataclass as a typed plain data record with methods only from the data contract. Mutable
+defaults use `field(default_factory=...)`, and `__post_init__` holds cheap invariants and
+derived fields. A named constructor serves construction that needs parsing, I/O, or
+alternate sources. Never use it to disguise a mutable global configuration object. A frozen dataclass
+expresses a value fixed after construction. A project on `attrs` applies the same principles
+through its factories, validators, and converters, and do not introduce `attrs` to avoid a
+small dataclass or a function.
+
+```python
+"""Represent an independently owned batch of prompt text."""
+
+from dataclasses import field, dataclass
+
+@dataclass
+class Batch:
+    """Prompt text owned by one processing batch.
+
+    Attributes:
+        prompts: The text items assigned to this batch.
+
+    """
+
+    prompts: list[str] = field(default_factory=list)
+
+
+__all__ = ["Batch"]
+```
+
+### Dataclass conventions
+
+<!-- level: all -->
+
+Document public dataclass fields in the configured docstring convention: Google style
+uses `Attributes:`, NumPy style an underlined `Attributes` heading.
+
+A property provides cheap, unsurprising attribute access with no side effects. Never use it as a
+getter and setter over an internal attribute, expensive work, a rename of a stored attribute,
+or a computation subclasses must override. `@property` beats a hand-written descriptor unless
+the public interface requires descriptor behavior.
+
+## Inheritance and decorators
+
+Design a class for inheritance or forbid inheritance. Composition shares code, and
+protocols or small abstract base classes define interfaces. Reserve specialization for a
+subclass that adds to the base class and works wherever callers expect the base class. A
+hierarchy never mixes code sharing, interface definition, and specialization, stays shallow,
+and lives physically together. Do not default to the template method pattern: a base class
+that defines control flow and calls subclass hooks takes more work to read than a function with
+explicit delegation.
+
+Do not put variants in one class with a type field and optional fields that apply to some values.
+Make invalid states unrepresentable. Behavior varying on more than one axis uses composition.
+Cross-cutting behavior such as tracking, caching, timing, or logging uses a wrapper that
+records completion only after the wrapped operation succeeds. An operation that varies by
+type without a clear owner may use `functools.singledispatch`. A class meant for subclassing
+documents its public API and its subclass API separately when the distinction matters.
+
+A decorator removes real repetition or expresses a framework contract. It behaves
+unsurprisingly and preserves function metadata. Because it runs at import time, it never
+depends on files, sockets, databases, or network calls. `classmethod` marks named constructors and
+class-specific routines.

package/configurations/language/python/rules/FLOW.md

@@ -0,0 +1,124 @@
+# Python Flow
+
+## Exceptions and error handling
+
+Use explicit validation for external inputs and required preconditions. Avoid exceptions for
+ordinary branching when code can check the value directly.
+
+The following module accepts only bounded positive decimal integers and preserves the original
+conversion error.
+
+Good:
+
+```python
+"""Validate limits supplied by a command or environment variable."""
+
+MAX_BATCH_SIZE = 1000
+
+
+def parse_batch_limit(raw: str) -> int:
+    """Return a positive batch limit within the supported range."""
+    try:
+        value = int(raw)
+    except ValueError as error:
+        message = "Batch limit must be a decimal integer."
+        raise ValueError(message) from error
+    if not 1 <= value <= MAX_BATCH_SIZE:
+        message = f"Batch limit must be between 1 and {MAX_BATCH_SIZE}."
+        raise ValueError(message)
+    return value
+```
+
+### Exception message conventions
+
+<!-- level: all -->
+
+Keep the exception's public contract stable when changing its message.
+
+## Exception contracts
+
+A custom exception inherits from `Exception`, describes its condition in the docstring, and
+lives beside the behavior that raises it rather than in a one-declaration file.
+
+Do not substitute a built-in exception for an external API's declared error type. Follow a
+library's public error contract when callers depend on it.
+
+## Assertions
+
+Keep assertions in tests. Use explicit validation for required application checks.
+
+## Boolean logic and comparisons
+
+Compare singleton values with `is None`, `is not None`, `is True`, or `is False` when the check concerns
+identity. Use truth-value testing only when all falsy values mean the same thing.
+Do not treat an empty collection, zero, and a missing value as interchangeable by default.
+
+Use `==` for value equality. Use membership tests for supported containers, and avoid chained
+comparisons whose repeated values have side effects. Keep evaluation order and short-circuit
+behavior intact when simplifying a condition.
+
+### Control-flow conventions
+
+<!-- level: all -->
+
+Prefer direct predicates and early exits when they reduce nesting. Keep multi-step branches
+as statements.
+
+## Iteration and collections
+
+Iterate containers through their supported interfaces. Do not mutate a collection in a way
+that invalidates the current iteration.
+
+Read file objects as iterators instead of loading all lines when the operation can stream them.
+Use `yield from` to delegate an iterator, and `any()` or `all()` for short-circuit predicate checks.
+Keep comprehensions limited to transformations whose order and side effects remain clear.
+
+Choose concrete return values or lazy iteration according to the caller's resource and reuse
+requirements, not solely to shorten the implementation.
+
+## Strings and output
+
+Use f-strings for ordinary value interpolation. Preserve formatting required by an external API,
+and keep logging arguments separate from the message when the logging API formats them lazily.
+Use efficient joining for a sequence of strings instead of repeatedly growing a large string.
+
+Formatting neither validates nor escapes values. Use parameterized database queries, argument arrays
+for subprocesses, and the appropriate encoder for HTML, JSON, or another output format.
+
+## Files and stateful resources
+
+Use context managers for resources with an explicit lifetime. Close files and network resources
+on both success and failure. Declare text encoding when opening a text file. Use binary mode
+for bytes instead of relying on an implicit conversion.
+
+A generator can keep a resource open while suspended. Make that lifetime clear to callers,
+especially when they can stop consuming it early. This command reads the path supplied as its
+first argument and closes the input before printing the collected records.
+
+Good:
+
+```python
+"""Read normalized, nonempty records from a text file."""
+
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    """Read the first argument as a path and print its normalized records."""
+    path = Path(sys.argv[1])
+    with path.open(encoding="utf-8") as source:
+        records = [record for line in source if (record := line.strip())]
+    _ = sys.stdout.write("\n".join(records))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+```
+
+For large inputs, provide an explicit streaming interface whose caller owns the open resource
+or uses a context manager. Do not materialize the full input merely to avoid documenting its
+lifetime.
+
+Write to a temporary file in the same folder, validate it, then rename it over the target. Clean up only paths and resources owned by the current operation.

package/configurations/language/python/rules/NAMING.md

@@ -0,0 +1,53 @@
+# Python Naming
+
+Python naming follows Python Enhancement Proposal (PEP) 8, with the rules below.
+
+## Command inputs and external names
+
+<!-- level: all -->
+
+- CLI flags use lowercase kebab case, such as `--account-name` and
+  `--output-dir`.
+- Avoid single-letter names except loop counters and math notation.
+- Preserve provider capitalization in external names such as `AWS_REGION` and
+  provider resource IDs.
+
+## Python modules and imports
+
+<!-- level: all -->
+
+- Do not create package-level re-export layers only to preserve old names.
+- Keep `__all__` names accurate and ordered according to local lint rules.
+
+Import `AccountSettings` under its declared name. An alias such as `Thing`
+hides the contract and provides no collision information.
+
+## Python types and dataclasses
+
+<!-- level: all -->
+
+- Dataclass names describe the domain value they represent.
+- Field names describe the value inside the owning type without repeating the
+  type name.
+- Use `Path` variables with names that reveal whether they point to a directory,
+  file, report, output, or repository root.
+- Use `*_path` for filesystem paths and `*_dir` only for directories.
+- Use `*_id` only for real identifiers, not arbitrary names, or labels.
+- Use `*_name` for display or provider names.
+- Use `*_key` for dictionary keys and supported variant keys.
+
+| Avoid                    | Prefer           | Meaning             |
+| ------------------------ | ---------------- | ------------------- |
+| `Invoice.invoice_number` | `Invoice.number` | The invoice number. |
+| `Shipment.shipment_date` | `Shipment.date`  | The shipment date.  |
+
+## Python boundary names
+
+<!-- level: all -->
+
+- Keep raw provider or CLI names at the boundary.
+- Translate external names into domain names before passing values inward when
+  the external name differs from the domain concept.
+- Keep path construction with the code that owns the resource instead of repeating it in
+  unrelated operations.
+- Name functions that cross boundaries for the operation they perform.

package/configurations/language/python/rules/PACKAGING.md

@@ -0,0 +1,49 @@
+# Python Packaging
+
+Deployment installs and lockfiles.
+
+## Package installation security
+
+Install from the uv lockfile:
+
+```bash
+uv sync --frozen
+```
+
+At level `all`, justify pip use with `gspot ignore python/pip-installs`. Update lockfiles only
+when the task includes dependency maintenance.
+
+## Import correctness
+
+- Respect the import-linter contracts the project declares.
+- Run entrypoints through the configured environment, installation, or module entrypoint.
+- Ensure packaged imports work outside the repository root. Do not depend on an accidental
+  current-directory import path.
+
+## Packages and architecture
+
+<!-- level: all -->
+
+- Keep packages shallow and purposeful.
+- Flatten packages that contain only `__init__.py` and one other module.
+- Do not use package `__init__.py` files to hide expensive imports.
+- Keep `__init__.py` files small and import-stable.
+- Barrel `__init__.py` files may contain imports and `__all__`.
+- Keep lower-level packages independent of higher-level workflow packages.
+
+## Source layout
+
+<!-- level: all -->
+
+Keep the layout the project has. A new package puts its code under `src/`:
+
+```text
+pyproject.toml
+src/
+  order_service/
+    __init__.py
+    orders.py
+    accounts.py
+```
+
+Keep helper scripts that nobody imports outside the package import path.

package/configurations/language/python/rules/PYTHON.md

@@ -0,0 +1,136 @@
+# Python
+
+## Python scope
+
+Write readable Python before clever Python: explicit data flow, clear names, small functions,
+and the formatter's layout.
+Importing a module does no I/O, starts no work, and parses no arguments. Prefer the project's rules to generic style guides, and consistency with the
+surrounding module where a guide allows more than one style.
+
+## Runtime and files
+
+Use the syntax of the declared Python version, stated once in the runtime pin, and name
+version requirements in examples whose syntax depends on them. Use `.py` for source and
+`.pyi` for stubs.
+
+### Comment language
+
+<!-- level: all -->
+
+Comments and docstrings use the project's declared language, and valid user content
+never restricts names to ASCII.
+
+## Environment and configuration
+
+An importable module never depends on an active shell, a virtual environment, the working directory, or a
+globally installed package. Imports resolve through project configuration, editable
+installs, `python -m`, or the configured environment. Virtual environments and package caches
+stay out of commits.
+
+The configuration owner takes the environment as a mapping, so a test passes its own:
+
+```python
+
+def get_config(environ: Mapping[str, str]) -> AppConfig:
+    """Parse an item limit, using 100 when the setting is absent.
+
+    Args:
+        environ: Environment values supplied by the application boundary.
+
+    Returns:
+        Settings containing a positive item limit.
+
+    Raises:
+        ValueError: The supplied limit is not an integer greater than zero.
+
+    """
+    max_items = int(environ.get("MAX_ITEMS", "100"))
+    if max_items < 1:
+        message = "MAX_ITEMS must be greater than zero"
+        raise ValueError(message)
+    return AppConfig(max_items=max_items)
+```
+
+## Module structure
+
+<!-- level: all -->
+
+Every runtime module has a docstring describing its present purpose.
+
+## Imports
+
+Imports resolve in the declared project environment, never through the script directory on
+`sys.path`, and break cycles by moving shared data or interfaces into a lower-level module.
+
+### Import conventions
+
+<!-- level: all -->
+
+Imports sit at the top after the docstring and future imports, one per line, with typing and
+`collections.abc` symbols imported directly. Use absolute cross-package imports; explicit
+relative imports serve siblings inside a package where surrounding code does that. Never an
+implicit relative import, a wildcard import, an import inside a function, method, or class
+body in runtime code, or a dynamic import through `importlib.import_module`, `__import__`, or
+`builtins.__import__`.
+
+Direct symbol imports keep call sites readable; use a module import when
+its prefix identifies the module, as `logging.getLogger(__name__)` does. Give every alias a reason. Two modules can share a final name, a module can collide with a local
+name, or a name can have too many words for the call site. A standard abbreviation such as `np` and a
+disambiguated generic name provide the other reasons.
+
+## Docstrings
+
+Docstrings match their signatures and behavior at both levels, in the project's declared
+convention. Use the explicit pydoclint style when the settings define one. Otherwise, follow the Google
+or NumPy convention that Ruff carries, and failing that the pydoclint default. The examples
+here follow Google style.
+
+### Docstring conventions
+
+<!-- level: all -->
+
+- A class docstring says what an instance represents, never `Class that...`.
+- A function that mutates an argument says so.
+
+## Constants, globals, and mutable state
+
+Prefer module constants. Do not expose mutable global state, lazy singletons, or mutable globals as
+public API. Required mutable state stays internal with its design reason documented,
+and no ordinary call mutates a module global as a hidden side effect. Validated configuration
+passes into the client or operation that consumes it, without a renaming wrapper.
+
+### Constant naming
+
+<!-- level: all -->
+
+Name constants `UPPER_SNAKE`, private ones with one leading underscore, and retained module
+state takes a name for its concept.
+
+## Main programs
+
+An executable module puts its behavior in `main()`, runs it under the `__main__` guard, and
+prefers `raise SystemExit(main())` when `main()` returns an exit code.
+Repository entrypoints run as `python -m package.module`, and shell scripts call Python
+modules rather than inline snippets. A shebang appears only on a file meant to execute
+directly.
+
+Never execute untrusted input as Python code, and dynamic execution never replaces input
+validation.
+
+## Power features
+
+<!-- level: all -->
+
+Avoid power features unless the project has a clear local pattern and the feature serves
+necessary. That covers custom metaclasses, bytecode manipulation, dynamic inheritance, object
+reparenting, import hooks, runtime monkeypatching, and reflection-heavy designs. It also
+covers interpreter internals, `__del__` cleanup, manual descriptors, and dynamic code
+generation. A power feature never makes code shorter or hides a dependency cycle; ordinary
+functions, dataclasses, explicit imports, and explicit data structures come first.
+
+## Threading
+
+Built-in types and variable assignment do not synchronize threads: use `queue.Queue` for thread
+communication and locks or conditions for shared state, which stays small and explicit.
+
+Name Python test files `test_<behavior>.py`, grouped by behavior.

package/configurations/language/python/rules/TYPING.md

@@ -0,0 +1,132 @@
+# Python Typing
+
+## Annotations
+
+<!-- level: all -->
+
+```python
+"""Group labeled records while preserving their key types."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Iterable
+
+
+def group_records[Key: Hashable](records: Iterable[tuple[Key, str]]) -> dict[Key, list[str]]:
+    """Group record values under their original keys."""
+    grouped: dict[Key, list[str]] = {}
+    for key, value in records:
+        grouped.setdefault(key, []).append(value)
+    return grouped
+```
+
+The type parameter syntax needs Python 3.12; `Key` connects input keys to output keys, and
+`Hashable` states the dictionary-key requirement. A variable annotation appears where the
+compiler cannot infer a clear type, such as an empty collection, not on every
+intermediate value.
+
+`typing.Annotated` attaches framework or validation metadata to a real type, real type
+first. The default stays an ordinary parameter default and never repeats in the
+metadata object. Arbitrary string metadata never replaces a domain type or validator. A
+FastAPI query field reads `Annotated[str | None, Query(max_length=50)] = None`.
+
+## Any, object, and shapes
+
+Use `object` for a value of any type when the function only uses operations
+every object has, such as passing it to `str()`. Also use it for an ignored callback
+result. Reserve `Any` for a type the type system cannot express, a correct type that makes the
+API unreasonable, or a value that intentionally escapes checking. Never use it as a shortcut; a
+protocol, type variable, overload, or small value object models the contract first.
+
+Arguments take protocols and abstract collections from `collections.abc`, such as `Iterable`,
+`Sequence`, `Mapping`, or `Callable`, and `object` for any value. Concrete implementations return
+concrete types such as `list`, `dict`, or a dataclass. Protocols and abstract base classes choose
+return types by the promised interface. A union return that forces callers into an immediate
+`isinstance()` branch becomes separate functions, a tagged dataclass, a protocol, or a small
+hierarchy with a common contract.
+
+Use `float` for numeric APIs that also accept integers. Use `str` for text and `bytes` for binary data.
+`AnyStr` ties several annotations to one text or binary type.
+
+A `Path | None = None` input handles its `None` branch
+before calling path methods, and the default path belongs to the configuration owner. Generic
+types name their parameters, such as `Sequence[int]`. A bare `Sequence` or `dict` exists only when
+the element type intentionally accepts any type and says so with `Any`. A `TypeVar` connects
+input and output types when that relationship matters, as `Key` does above.
+
+## Aliases, variables, and forward references
+
+A type alias names a complex repeated type in CapWords, with a leading underscore when
+internal. It uses a `type` statement when the Python version supports it and the module
+already uses it, or `TypeAlias` where a syntax change falls outside the task. `MetricMap` for
+`Mapping[str, float]` names an alias; `Path = pathlib.Path` names a class alias and `errno.EEXIST` a
+value, and neither defines a typing interface.
+
+### Type variable naming
+
+<!-- level: all -->
+
+A private unconstrained type variable can use `_T` or `_P`; a public or constrained one has a
+descriptive name such as `Key`, with `_co` and `_contra` for variance, and no public
+single-letter `T` or `P`. `ParamSpec` forwards a callable's parameters, and declare a `Callable` with
+bound to the signature its consumer needs rather than left bare.
+
+### Forward references
+
+`from __future__ import annotations` handles forward references and stays as the project's
+convention even where newer Python defers evaluation. String annotations exist only where
+the runtime does not provide future annotations or a type-checking-only import needs them. A
+`TYPE_CHECKING` import avoids a runtime import only when the runtime does not need the
+symbol. Validators and frameworks that evaluate annotations need the real import. A type-only circular
+import signals a need to move the shared contract.
+
+```python
+@dataclass(frozen=True)
+class Node:
+    """One node whose parent chain is acyclic.
+
+    Attributes:
+        name: Display name of this node.
+        parent: Parent node, or None for a root.
+
+    """
+
+    name: str
+    parent: Node | None = None
+
+    def list_lineage(self) -> list[str]:
+        """Return names from this node toward the root."""
+        names: list[str] = []
+        current: Node | None = self
+        while current is not None:
+            names.append(current.name)
+            current = current.parent
+        return names
+```
+
+## Protocols
+
+Define a structural interface with a narrow `typing.Protocol` near the consumer, with
+only what that consumer needs; implementations satisfy it without importing or subclassing
+it. `@runtime_checkable` exists only for a real `isinstance()` need, and an abstract base
+class serves nominal identity, runtime instantiation checks, or a standard-library contract,
+never shared implementation mixed with interface definition.
+
+```python
+class Reader(Protocol):
+    """A source of one text document."""
+
+    def read(self) -> str:
+        """Return the document text."""
+        ...
+
+
+def read_unique_records(reader: Reader) -> list[str]:
+    """Read sorted unique records, omitting blank lines."""
+    records = {line.strip() for line in reader.read().splitlines()}
+    records.discard("")
+    return sorted(records)
+```