# GisConverter ConsoleApp

Lightweight command-line front-end that dispatches GIS conversion requests to the library converters in this repository.

## Overview
The ConsoleApp exposes a single command, `gis_convert`, which accepts a GIS input artifact (single file or archive), a canonical target format option, and output/temp paths. The CLI attempts to detect the input format, validates inputs, invokes the appropriate converter and prints a concise result to console. Optional file logging can be enabled.

This README documents usage, examples, debug helpers, exit codes and guidance for tests.

---

## Usage

Syntax:
GISConverter.Cli.exe gis_convert <gis_input_file_path> <gis_target_format_option> <output_folder_path> <temp_folder_path> [Log <log_file_path> [level]]

Parameters
- `<gis_input_file_path>` — path to a single GIS file (e.g., `.csv`, `.gml`) or an archive containing the format's required files (e.g., shapefile `.7z`/`.zip` containing `.shp`/`.shx`/`.dbf`).
- `<gis_target_format_option>` — canonical option string (case-insensitive) such as `Shapefile`, `GeoJson`, `Csv`, `Gml`, etc.
- `<output_folder_path>` — destination directory where the converter writes output files.
- `<temp_folder_path>` — temporary working folder for extraction and intermediate files. Converters create it if missing and attempt best-effort cleanup of what they created.
- Optional `Log <log_file_path> [level]` — enable file logging; `level` may be `ALL`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, or `OFF`.

Examples
- Convert a CSV to GeoJSON:
- GISConverter.Cli.exe gis_convert "C:\data\features.csv" GeoJson "C:\out" "C:\temp" Log "C:\logs\run.log"


- Convert a Shapefile archive to GeoPackage:- Convert a zipped Shapefile to GML with debug logging:
GISConverter.Cli.exe gis_convert "C:\data\shapefile.7z" GeoPackage "C:\out" "C:\temp"
- 
Notes
- Quote paths containing spaces. In Debug builds the CLI includes tolerant logic to repair some unquoted inputs (it can join adjacent tokens into a single input path).
- Converters expect specific inputs for some formats:
- Shapefile: archive containing `.shp`, `.shx`, `.dbf`.
- Csv/Gml/GeoJson: single file or an archive containing the file.

---

## Supported Target Options

Supported canonical options are registered in `ConverterFactory`. Typical names:
- Shapefile, GeoJson, GeoJsonSeq, EsriJson, Kml, Kmz, Gml, Csv, GeoPackage, Osm, Gpx, MapInfoTab, MapInfoInterchange, TopoJson, Gdb

See `ConverterFactory` for the definitive list.

---

## Exit Codes

`Program.Run` returns an integer exit code:
- `0` — Success
- `1` — App error (invalid args, unknown command, usage displayed)
- `2` — Conversion failed (converter returned Failure)
- `3` — Unexpected exception

Scripts should inspect the exit code and capture console output for diagnostics.

---

## Logging

To enable file logging pass `Log <log_file_path> [level]`. Initialization failures are non-fatal and are reported to `stderr`.

Example:
gis_convert input.7z Shapefile outDir tempDir Log "C:\logs\convert.txt" DEBUG

Logging is best-effort — invalid or inaccessible paths will disable logging and print a warning.

---

## Temp folder and cleanup behavior

- `temp_folder_path` is used for extraction and intermediate files.
- Converters create the folder if it does not exist and try to clean up what they created. If the caller supplies an existing folder, converters avoid deleting it unless they created it during the run.

---

## Debugging (Visual Studio)

To run with a debug scenario without typing full CLI args:
1. Right-click the ConsoleApp project → __Properties__ → __Debug__.
2. Add an environment variable: `GISCONVERTER_DEBUG_TARGET` with a predefined scenario (examples: `Shapefile1`, `Csv1`, `Gml1`).
3. Start debugging — the debug args are applied only in Debug builds.

This helper is for developer convenience and does not affect Release builds or CI.

---

## Automated tests

Unit and integration tests invoke the entry point via the public `Program.Run(string[] args)` method rather than spawning a new process. Tests therefore require `Program.Run` to return exit codes and not call `Environment.Exit` (which would terminate the test runner).

Typical test expectations:
- No-argument invocation prints help/usage and returns exit code `1`.
- Unknown/invalid format options produce diagnostic/usage output and return exit code `1`.

When you change CLI behavior, update tests to match the new contract or adjust the implementation so tests remain deterministic.

---

## Detection vs filesystem validation

### Overview
The ConsoleApp performs format detection (resolve a converter from the provided input token) before performing the filesystem existence check on the input path. This ordering preserves tolerant repair logic (joining adjacent tokens for unquoted paths) and produces richer diagnostic messages when parsing or detection fails.

### Why this matters for tests
- Tests sometimes pass synthetic/non-existent input paths to exercise parsing and detection logic. Because detection runs before existence checks, such tests may observe detection-related messages (`Unable to auto-detect converter from input`, `Detector reason`) instead of an immediate `input path not found` message.
- Tests asserting negative/parse-error flows should accept either detection/usage output OR an `input path not found` diagnostic.

### Recommended test assertion pattern
Combine stdout and stderr and assert the combined output contains one of the expected diagnostics. Example:
var combined = stdout + "\n" + stderr; Assert.True( combined.Contains("Unable to auto-detect converter from input", StringComparison.OrdinalIgnoreCase) || combined.Contains("Detector reason", StringComparison.OrdinalIgnoreCase) || combined.Contains("Usage", StringComparison.OrdinalIgnoreCase) || combined.Contains("input path not found", StringComparison.OrdinalIgnoreCase), $"Unexpected CLI output:\n{combined}");

### When deterministic path validation is required
If a test must verify path-existence rejection specifically, create the necessary filesystem state (create or remove files/directories) before calling `Program.Run`.

### CLI guidance for consumers
Detect-then-validate improves developer ergonomics and helps provide actionable guidance. If your callers rely on immediate filesystem validation, supply valid paths or adjust callers/tests for the new order.

---

## Running Integration Tests

- Place small sample files under `TestsApp/TestData\<format>` (e.g., `TestData\Shapefile`, `TestData\Csv`, `TestData\Gml`) and set `<CopyToOutputDirectory>PreserveNewest` in the test project.
- Integration tests are defensive and skip when samples are absent.

---

## Implementation notes

- The ConsoleApp delegates format resolution to `ConverterFactory` and conversion work to library converters (CsvConverter, GmlConverter, ShapefileConverter, etc.).
- The entry point exposes `Run(string[] args)` which returns an exit code without calling `Environment.Exit` (used by tests via reflection).

---

## Troubleshooting

- Conversion failure: inspect stdout/stderr and the optional log file.
- Missing `Program` type in tests: ensure ConsoleApp is built and its assembly is present in probed output directories.
- Missing samples: verify `CopyToOutputDirectory` and that files exist in test output.
- Aspose license: supply via CI secrets or ensure `AsposeLicenseManager.ApplyLicense()` succeeds for licensed runs.

---

## Contact / Contributing

- Open issues for defects, missing sample data or flaky tests.
- Add small representative test samples under `TestsApp/TestData` and update `IntegrationTestConstants` when adding scenarios.

---

## License & Attribution

This project follows the repository license. Third‑party converters and drivers may have separate licenses (for example, Aspose); consult vendor documentation.