# 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.

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

Contents
- Overview
- Responsibilities
- Public surface & key types
- Quickstart (host usage)
- Logging and diagnostics
- Licensing (Aspose.GIS)
- Testing guidance
- Extending the library (adding formats)
- Packaging & compatibility
- Troubleshooting
- Contribution guidance

## Overview

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

## Responsibilities

- Implement format-specific converters (Aspose.GIS-backed or lightweight implementations).
- Provide utilities for:
  - Input validation and directory preparation (`ConverterUtils`).
  - Archive inspection and safe extraction (zip-slip protection).
  - JSON format detection heuristics (`JsonFormatDetector`) for GeoJSON, EsriJSON, TopoJSON and GeoJSON Sequence (NDJSON).
  - Mapping of canonical option strings to drivers and file extension helpers.
- Expose a lightweight logging abstraction (`IAppLogger` / `Log`) so tests and hosts capture diagnostics.
- Centralize license application (`AsposeLicenseManager`) so converters are license-aware without embedding licensing logic.

## Public surface & key types

- `IConverter` — converter contract. Main method:
  - `ConversionResult Convert(string gisInputFilePath, string gisSourceFormatOption, string gisTargetFormatOption, string outputFolderPath, string tempFolderPath)`
- `IConverterFactory` / `ConverterFactory` — resolve converters by friendly display keys. Use `TryCreate` for non-throwing flows and `Create` when you want an exception with suggestion on unknown keys.
- `ConverterUtils` — path validation, archive listing, safe extraction, output path construction and temp cleanup helpers.
- `JsonFormatDetector` — heuristics and bounded-header sniffers for JSON formats.
- `ConversionResult` / `ConversionStatus` — uniform result carrier for converters.
- `FileExtension` / `FileExtensionHelpers` — canonical extension mappings used to build output file names.
- `AsposeLicenseManager` — centralized license application helper.

## Quickstart (host usage)

Typical flow for a host (ConsoleApp or service):

1. Configure logging early (see `GitConverter.Lib.Logging.Log`).
2. Optionally apply Aspose license: `AsposeLicenseManager.ApplyLicense()` and fail gracefully if required.
3. Construct or obtain a `ConverterFactory` instance.
4. Validate inputs using `ConverterUtils.ValidateInputs` and prepare output/temp folders with `ConverterUtils.PreparePaths`.
5. Resolve a converter using `TryCreate(sourceOrTargetOption, out var converter)` and call `converter.Convert(...)`.
6. Inspect `ConversionResult` and map to exit codes or UI messages.

Example (pseudocode):

```csharp
Log.SetFile("logs/app.log");
Log.Enable();
if (!AsposeLicenseManager.ApplyLicense()) return ConversionResult.Failure("License not applied");
var factory = new ConverterFactory();
if (!factory.TryCreate("GeoJson", out var converter)) return ConversionResult.Failure("Unsupported format");
var validation = ConverterUtils.ValidateInputs(inputPath, outDir, tempDir);
if (validation != null) return validation;
var prep = ConverterUtils.PreparePaths(outDir, tempDir);
if (prep != null) return prep;
return converter.Convert(inputPath, "GeoJson", "Shapefile", outDir, tempDir);
```

## Logging and diagnostics

- Use the `Log` façade (`Log.Debug`, `Log.Info`, `Log.Warn`, `Log.Error`) everywhere in library code.
- Default logger is a `NullLogger` (no-op). Configure file logging with `Log.SetFile(path, level)` and call `Log.Enable()` to forward to log4net.
- In tests set `Log.Current` to a `TestLogger` instance to capture messages for assertions using `LogAssert` helpers.

Important tokens to look for while diagnosing failures:
- Parameter traces and `starting conversion (option='...')`.
- `Conversion succeeded: <path>` or `Conversion failed: <message>`.
- Archive extraction and zip-slip warnings.
- Factory registration summary and lookup misses.

## Licensing (Aspose.GIS)

- `AsposeLicenseManager.ApplyLicense()` attempts to apply an Aspose license via embedded resource or configured file path and returns `true` on success. It logs diagnostic details and returns `false` on failure (does not throw).
- Do not embed vendor license files in source control. Provision licenses through CI secrets or secure mechanisms for licensed integration runs.
- Tests that require licensing should check for the license and skip when it is not present.

## Testing guidance

- Unit tests
  - Inject a small `registrations` dictionary and a `TestLogger` into `ConverterFactory` to avoid creating heavy converters.
  - Test `ConverterUtils`, `FactoryHelpers`, and `JsonFormatDetector` with small inputs.
  - Use `TestLogger` and `LogAssert` for logging assertions.

- Integration tests
  - Place small samples under `TestsApp/TestData/<format>` and mark with `<CopyToOutputDirectory>PreserveNewest`.
  - Gate licensed or expensive integration tests using environment flags (for example `GITCONVERTER_ENABLE_INTEGRATION=1`).

- Assertions
  - Prefer substring checks for messages and log tokens to avoid brittleness. Use `FileExtensionHelpers` to compute expected extensions for file assertions.

## Extending the library (adding formats)

1. Implement an `IConverter` or reuse `UniversalGisConverter` when appropriate.
2. Add mapping for the new option in `ConverterFactory` and driver mapping in `ConverterUtils.ConversionOptionToDriver`.
3. Add extension mapping in `FileExtensionHelpers` and update required component lists (for multi-file formats).
4. Add unit tests for detection and factory mapping; add a small integration sample and a gated integration test when feasible.

## Packaging & compatibility

- The library targets .NET Standard 2.1 to remain usable by .NET 9 hosts.
- Avoid exposing platform-specific APIs on the public surface to preserve portability.

## Troubleshooting

- Missing converter / lookup failures: verify normalization rules in `FactoryHelpers.NormalizeKey` and review factory startup logs for supported keys.
- Archive extraction problems: inspect archive listing helpers and zip-slip warnings; ensure test zips include expected entry paths.
- License-related failures: confirm embedded resource name or configured path and file permissions.

## Contribution guidance

- Open issues for bugs, missing formats or flaky tests. Provide failing test names, stack traces, captured console & log output, and sample artifacts when possible.
- When contributing converters include unit tests for edge cases (ambiguous JSON, KMZ detection, zipped FileGDB) and minimal integration samples.

## API documentation

Per-type XML remarks are available in source files and are used by IDE IntelliSense. For quick reference consult the following types:
- `GitConverter.Lib.Converters.IConverter`
- `GitConverter.Lib.Factories.ConverterFactory`
- `GitConverter.Lib.Utils.ConverterUtils`
- `GitConverter.Lib.Logging.Log`

---

If you want I can also add a short Quickstart or an examples folder showing a minimal host wiring and common conversion scenarios.