# GisConverter.Lib.Models

Canonical model types and small helpers used across the conversion library. This README documents intent, key types, usage patterns, testing guidance, extension steps and troubleshooting for model types such as `ConversionResult`, `ConversionStatus`, `FileExtension`, `FileExtensionHelpers` and `SupportedFormats`.

Targets
- Library: .NET Standard 2.1 (consumable by .NET 9 hosts)

Overview
- Centralize domain value types and deterministic helpers so converters and orchestration code rely on stable semantics for:
  - file extension mapping,
  - conversion result reporting, and
  - lightweight option passing.
- Keep models small, immutable where appropriate, and easy to reason about in unit and integration tests.

Key types
- `ConversionResult`
  - Immutable carrier returned by converters to represent success or failure.
  - Create via helpers: `ConversionResult.Success(string?)` and `ConversionResult.Failure(string?)`.
  - Contains: `Status` (`ConversionStatus`), `Message` (human-readable), and `TimestampUtc` (diagnostic).
  - Logical equality excludes `TimestampUtc` so comparisons in tests remain stable.

- `ConversionStatus`
  - Enum representing the outcome: `Success` or `Failure`.

- `FileExtension` (enum) and `FileExtensionHelpers`
  - `FileExtension` enumerates canonical output types (examples: `GeoJson`, `Shapefile`, `Csv`, `Kml`).
  - `FileExtensionHelpers.FromOption(string option)` maps a canonical option string (case-insensitive) to `FileExtension?`.
  - `FileExtensionHelpers.ToDotExtension(FileExtension ext)` returns the dot-prefixed extension (for example `.geojson`).
  - Prefer these helpers as the authoritative source when constructing or asserting filenames.

- `SupportedFormats`
  - Immutable collection of friendly target option keys used by the library, host and tests.
  - Use `SupportedFormats.Values` for iteration and `SupportedFormats.Contains(option)` for membership tests.

Usage patterns
- Returning results from converters
- if (error) return ConversionResult.Failure("Missing companion files (.shx/.dbf)"); return ConversionResult.Success($"Converted to {targetOption}; output: {outputPath}");
- Building canonical filenames
- var maybeExt = FileExtensionHelpers.FromOption(gisTargetFormatOption); var extDot = FileExtensionHelpers.ToDotExtension(maybeExt ?? FileExtension.Shapefile); var fileName = $"output_{DateTime.UtcNow:yyyyMMdd_HHmmss}{extDot}";
- Validating supported targets
-if (!SupportedFormats.Contains(candidateOption)) { /* handle unknown option */ }
- 
Testing guidance
- Prefer logical assertions
  - Assert `ConversionResult.Status` and use case-insensitive substring checks for `ConversionResult.Message` rather than exact whole-message equality or timestamps.
- Use helpers in tests
  - Compute expected suffixes with `FileExtensionHelpers.ToDotExtension(...)` instead of hard-coding.
  - Iterate supported targets with `SupportedFormats.Values` for parameterized integration coverage.
- Stable tokens
  - When asserting messages or logs prefer stable tokens (e.g., `"Did you mean"`, `"missing"`, `"archive"`) rather than full sentences.

Extending the model surface
When adding a new `FileExtension`:
1. Add the enum member to `FileExtension`.
2. Update `FileExtensionHelpers.FromOption` and `FileExtensionHelpers.ToDotExtension`.
3. Update `ConverterUtils.ConversionOptionToDriver` if driver mapping is required.
4. Add unit tests for mappings and any downstream behavior.
5. Add or update `TestsApp/TestData/<format>` samples and integration tests if applicable.

When updating `SupportedFormats`:
- Update callers, test data folders and documentation in the same change to avoid transient breakage.

Troubleshooting
- `ConversionResult` inequality
  - Ensure `Message` content matches expected text (use substring checks for variable data). `TimestampUtc` is intentionally excluded from equality.
- Missing output files in integration tests
  - Use `FileExtensionHelpers.ToDotExtension(...)` to compute expected suffixes and search the output folder rather than asserting exact filenames.
- Mapping changes
  - After changing extension or driver mappings update `FileExtensionHelpers`, `ConverterUtils`, tests and README entries.

Maintenance and compatibility
- Keep the model surface minimal. If more metadata is required, prefer adding a wrapper or DTO rather than expanding `ConversionResult`.
- Target remains `.NET Standard 2.1` for compatibility with `.NET 9` hosts. Follow project nullable and coding conventions for new files.

Contact & contribution
- When changing model semantics (equality, added fields, extension mappings) update unit tests and this README with the rationale and migration guidance.
- Open issues or PRs that describe the change, include test coverage and a short migration note for consumers.

License & legal
- Some converters use third-party drivers (for example Aspose.GIS). Do not commit license files to source control. Provision licenses via CI secrets or secure provisioning for licensed integration runs.