# GitConverter.Lib

`GitConverter.Lib` is the core library that implements GIS conversion logic, detection heuristics and supporting infrastructure used by the ConsoleApp and test projects. This README summarizes the library responsibilities, public surface, usage patterns, testing guidance, extension steps and operational notes for maintainers.

Table of contents
- Overview
- Responsibilities
- Public surface & key types
- Typical host usage
- Logging and diagnostics
- Licensing (Aspose.GIS)
- Testing guidance
- Extending the library
- Packaging & compatibility notes
- Troubleshooting
- Contact / contribution

## Overview

The library provides a small, focused API to convert between GIS formats (CSV, Shapefile, GML, GeoJSON and others) while keeping file-system safety, archive handling and detection logic centralized. Converters are implemented as `IConverter` instances and resolved by a registry-style `ConverterFactory`.

## Responsibilities

- Implement converters that perform format-specific conversions using Aspose.GIS or other drivers.
- Provide helpers for:
  - Input validation and directory preparation (`ConverterUtils`).
  - Archive inspection and safe extraction with zip-slip protection.
  - JSON format detection heuristics (`JsonFormatDetector`) for GeoJSON, EsriJSON, TopoJSON and NDJSON/GeoJsonSeq.
  - Mapping of canonical option strings to driver instances and file extension helpers.
- Offer a lightweight logging abstraction (`IAppLogger` / `Log`) so tests and hosts can capture diagnostics.
- Centralize licensing application (`AsposeLicenseManager`) so licensing concerns are isolated from converters.

## Public surface & key types

- `IConverter` — contract for converter implementations. Method:
  - `ConversionResult Convert(string gisInputFilePath, string gisSourceFormatOption, string gisTargetFormatOption, string outputFolderPath, string tempFolderPath)`
- `IConverterFactory` / `ConverterFactory` — registry-based factory to obtain `IConverter` instances from human-friendly display keys. Supports `TryCreate` (non-throwing) and `Create` (throws with suggestion when unknown).
- `ConverterUtils` — path validation, archive listing, safe extraction, output path construction and cleanup helpers.
- `JsonFormatDetector` — heuristics and bounded-header sniffers for JSON formats.
- `ConversionResult` / `ConversionStatus` — uniform result carrier for converters.
- `FileExtension` / `FileExtensionHelpers` — canonical extension mappings and helpers used to compose output names.
- `AsposeLicenseManager` — centralized license application helper.

## Typical host usage

1. Initialize logging in the host (file or console logger implementing `IAppLogger`).
2. Optionally apply Aspose license early: `AsposeLicenseManager.ApplyLicense()` and fail gracefully when required.
3. Create/obtain a `ConverterFactory` instance.
4. Validate and prepare paths using `ConverterUtils.ValidateInputs` / `ConverterUtils.PreparePaths`.
5. Resolve a converter using `TryCreate` (preferred for CLI flows) and call `Convert(...)`.
6. Inspect `ConversionResult` and map to exit codes or user-facing messages.

Example (pseudocode)

```csharp
var logger = MyLogger.Configure(...);
if (!AsposeLicenseManager.ApplyLicense())
    return Failure("Aspose license not applied");
var factory = new ConverterFactory();
if (!factory.TryCreate(targetOption, out var converter))
    return Failure("Unsupported format");
var validation = ConverterUtils.ValidateInputs(input, outputDir, tempDir);
if (validation != null) return validation;
var prep = ConverterUtils.PreparePaths(outputDir, tempDir);
if (prep != null) return prep;
var result = converter.Convert(input, sourceOption, targetOption, outputDir, tempDir);
```

## Logging and diagnostics

- The library emits `Debug`, `Info`, `Warn` and `Error` messages through `IAppLogger`.
- Important diagnostic tokens to look for when troubleshooting:
  - Parameter traces (conversion start) — useful to capture CLI arg repair behavior.
  - `starting conversion (option='...')` and `Conversion succeeded: <path>` / `Conversion failed: <msg>` messages.
  - Archive extraction logs and zip-slip warnings.
  - `ConverterFactory` registration summary and lookup misses for factory resolution problems.

## Licensing (Aspose.GIS)

- License application is centralized in `AsposeLicenseManager`.
- `ApplyLicense()` returns a boolean and logs diagnostic details. It does not throw; callers decide how to handle missing license (typically return `ConversionResult.Failure`).
- Recommended approaches:
  - Production: embed the Aspose license as an `EmbeddedResource` and ensure the resource name matches the helper's expectation.
  - CI/local licensed runs: provision license files via environment variables or pipeline secrets and gate licensed tests.

## Testing guidance

- Unit tests
  - Prefer injecting a small registration dictionary and a `TestLogger` into `ConverterFactory` to avoid instantiating heavy converters.
  - Test `ConverterUtils`, `FactoryHelpers` and `JsonFormatDetector` with small synthetic inputs.
  - Use fakes/ stubs for `IConverter` to validate routing and error handling.

- Integration tests
  - Put sample artifacts under `TestsApp/TestData/<format>` and mark them with `CopyToOutputDirectory=PreserveNewest`.
  - Integration tests should skip gracefully when sample data is missing to keep CI non-fatal.
  - For CLI tests that invoke `Program.Run`, ensure `Program.Run` returns an exit code and does not call `Environment.Exit`.

## Extending the library

To add a new format:
1. Implement `IConverter` for the format (or reuse `UniversalGisConverter` when Aspose drivers suffice).
2. Add file-extension mappings in `FileExtensionHelpers` and required archive components in `ConverterUtils.GetRequiredFileExtensions` when needed.
3. Register the converter in `ConverterFactory` or provide it via the constructor's `registrations` map for test injection.
4. Add unit tests for detection/mapping and minimal integration tests with small sample files.

## Packaging & compatibility notes

- Targets `.NET Standard 2.1` to be compatible with `.NET 9` hosts used by the ConsoleApp and test projects.
- Avoid exposing platform-specific types in the public surface to preserve portability.

## Troubleshooting

- Missing converter / lookup failures
  - Check `FactoryHelpers.NormalizeKey` for unexpected normalization behavior and review `_displayKeys` logged by `ConverterFactory` at startup.

- Archive extraction problems
  - Inspect `TryListArchiveEntries` and extraction logs; ensure archives are not corrupted and that zip-slip warnings are not suppressing extraction.

- License-related failures
  - Verify embedded resource presence or file path configured via environment variables and ensure proper file permissions.

## Contact / contribution

- Open issues for bugs, missing formats, flaky tests or improvements. Include reproducible steps, captured console/log outputs and sample artifacts if possible.
- When contributing new converters or detection logic include unit tests that cover edge cases (ambiguous JSON, zipped FileGDB, KMZ doc.kml detection) and small integration samples.

For API reference consult the XML remarks in source files which provide per-type documentation used by IDE IntelliSense.