# Development

## Repository Layout

Main folders:

- `VirtualFS/`
- `VirtualFS/Implementation/`
- `VirtualFS/Physical/`
- `VirtualFS/Memory/`
- `VirtualFS/Compressed/`
- `VirtualFS/EmbeddedResource/`
- `VirtualFS.Tests/`

Important files:

- `VirtualFS.sln`
- `VirtualFS/VirtualFS.csproj`
- `VirtualFS.Tests/VirtualFS.Tests.csproj`
- `Dockerfile`
- `.github/workflows/docker.yml`

## Target Frameworks

Library targets:

- `netstandard2.0`
- `net472`
- `net6.0`
- `net8.0`
- `net10.0`

Tests target:

- `net10.0`

## Build and Test

The repository uses a Docker-based build/test flow with the official .NET 10 SDK image.

Run the full containerized verification:

```bash
docker build --target test -t virtualfs:test .
```

This performs:

- restore
- build
- test

## Test Stack

The test project currently uses:

- xUnit v3
- `Microsoft.NET.Test.Sdk`
- `coverlet.collector`

## CI

The repository workflow is:

- `.github/workflows/docker.yml`

It runs the same Docker build/test path on:

- pushes
- pull requests

## Adding a New Backend

The expected implementation approach is:

1. derive from `BaseFileSystem`
2. implement the abstract operations required by `IFileSystem`
3. return `VirtualStream` for open file handles
4. populate entry metadata consistently
5. respect read-only semantics
6. add focused tests for backend-specific behavior

Backend responsibilities generally include:

- existence checks
- metadata lookup
- enumeration
- create/delete
- read/write stream opening
- rename/move/copy where backend-specific optimization is useful

## Design Characteristics to Keep in Mind

These are important when changing the library:

- path semantics are custom and intentionally `/`-based
- directory vs file is determined by trailing slash
- `RootFileSystem` composes mounted backends but is not itself writable
- `Entry.Path` is backend-local, `Entry.FullPath` is root-visible
- `EntryRealPath` may be unavailable for some backends
- unmounting depends on `IsBusy`
- generic copy/move logic may be correct but not optimal for remote backends

## Documentation Structure

Current documentation:

- top-level overview: `README.md`
- architecture details: `docs/architecture.md`
- usage examples: `docs/usage.md`
- backend summary: `docs/backends.md`
- development notes: `docs/development.md`