Metadata-Version: 2.4
Name: godot-save-schema-guard
Version: 0.1.7
Summary: Validate Godot save-game fixtures, generate schema samples, compare migration outputs, and catch compatibility drift before release.
Author: Godot Save Schema Guard contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/NonniGB/godot-production-toolkit/tree/main/godot-save-schema-guard
Project-URL: Issues, https://github.com/NonniGB/godot-production-toolkit/issues
Keywords: godot,save,schema,json,migration,fixtures,ci,gamedev
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Godot Save Schema Guard

Validate Godot save-game fixtures against explicit schemas and catch incompatible save format changes before release.

The first release focuses on JSON saves because they are deterministic to validate outside the engine. It is meant to be a release gate: do not break player saves.

## Install

```powershell
python -m pip install -e .
```

When published:

```powershell
python -m pip install godot-save-schema-guard
```

## Quick Start

```powershell
godot-save-guard generate-fixture --schema schemas\save.schema.json --fixture-output saves\fixtures\generated_v3.json --set 'player.id="pilot-1"' --format markdown
godot-save-guard validate saves\fixtures --schema schemas\save.schema.json
godot-save-guard validate examples\fixtures --schema examples\schema\save.schema.json --format markdown --output SAVE_COMPATIBILITY.md
godot-save-guard migrate saves\v1 --output-dir migrated\v2 --command "godot --headless --script tools/migrate_save.gd --input {input} --output {output}"
godot-save-guard migrate-chain saves\v1 --chain migrations.toml --output-dir migrated --schema schemas\save.schema.json --compare-original --format json --output reports\migration-chain.json
godot-save-guard migration-graph --chain migrations.toml --current 3 --supported 1 --supported 2 --format markdown
godot-save-guard redact saves\fixtures --path player.name --path players.*.email --output-dir sanitized\saves --dry-run
```

## What It Checks

- Invalid JSON fixtures.
- Missing top-level `version`.
- Missing required schema properties.
- Numeric type drift such as `"100"` where a number is expected.
- Type mismatches.
- Unexpected properties when `additionalProperties` is false.
- Generated fixture samples from required schema fields, defaults, enum values, and optional JSON overrides.
- Migration command failures.
- Migration-chain failure messages that name the failed step, fixture, expected
  output, and captured stdout/stderr snippets.
- Ordered migration chains from older save versions to the current format.
- Final migrated fixture validation after a migration chain succeeds.
- Before-and-after summaries that compare original fixtures with final migrated outputs.
- Missing migration paths from supported save versions to the current format.
- Selected-field redaction for sanitized fixture copies.
- Report metadata and plain-language rule explanations for compatibility findings.

Redaction is path-based. It only changes paths you list with `--path`, so review
sanitized fixtures before attaching them to issues, documentation, or reports.

## Documentation

- [Schema guide](docs/SCHEMA_GUIDE.md)
- [Migration workflow](docs/MIGRATIONS.md)
- [Godot JSON caveats](docs/GODOT_JSON_CAVEATS.md)
- [Rule reference](docs/RULE_REFERENCE.md)
- [CI usage](docs/CI.md)

## Development

```powershell
python -m pip install -e .
python -m unittest discover -s tests -v
godot-save-guard validate examples\fixtures --schema examples\schema\save.schema.json --fail-on none
```

Fixtures are generic and intentionally small so the repository is safe to publish.
