From a1aba54d472cdbc3acfe89c2adfba1808183df3b Mon Sep 17 00:00:00 2001 From: Philippe Matray Date: Fri, 27 Feb 2026 17:43:32 +0100 Subject: [PATCH] docs: standardize README following org template --- README.md | 406 +++++++++++++++++++++++++++++------------------------- 1 file changed, 222 insertions(+), 184 deletions(-) diff --git a/README.md b/README.md index 20e507f..998409d 100644 --- a/README.md +++ b/README.md @@ -1,263 +1,301 @@ -# Virtual File System [![Sparkline](https://stars.medv.io/Atypical-Consulting/VirtualFileSystem.svg)](https://stars.medv.io/Atypical-Consulting/VirtualFileSystem) -A virtual file system implementation in modern C# with comprehensive demo applications. +# Virtual File System ---- +> **Test filesystem code without touching the real disk — fast, deterministic, and disposable.** + [![Atypical-Consulting - VirtualFileSystem](https://img.shields.io/static/v1?label=Atypical-Consulting&message=VirtualFileSystem&color=blue&logo=github)](https://github.com/Atypical-Consulting/VirtualFileSystem "Go to GitHub repo") [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) +[![.NET](https://img.shields.io/badge/.NET-9.0%20%7C%2010.0-purple?logo=dotnet)](https://dotnet.microsoft.com/) [![stars - VirtualFileSystem](https://img.shields.io/github/stars/Atypical-Consulting/VirtualFileSystem?style=social)](https://github.com/Atypical-Consulting/VirtualFileSystem) [![forks - VirtualFileSystem](https://img.shields.io/github/forks/Atypical-Consulting/VirtualFileSystem?style=social)](https://github.com/Atypical-Consulting/VirtualFileSystem) + [![GitHub tag](https://img.shields.io/github/tag/Atypical-Consulting/VirtualFileSystem?include_prereleases=&sort=semver&color=blue)](https://github.com/Atypical-Consulting/VirtualFileSystem/releases/) [![issues - VirtualFileSystem](https://img.shields.io/github/issues/Atypical-Consulting/VirtualFileSystem)](https://github.com/Atypical-Consulting/VirtualFileSystem/issues) [![GitHub pull requests](https://img.shields.io/github/issues-pr/Atypical-Consulting/VirtualFileSystem)](https://github.com/Atypical-Consulting/VirtualFileSystem/pulls) -[![GitHub contributors](https://img.shields.io/github/contributors/Atypical-Consulting/VirtualFileSystem)](https://github.com/Atypical-Consulting/VirtualFileSystem/graphs/contributors) -[![GitHub last commit](https://img.shields.io/github/last-commit/Atypical-Consulting/VirtualFileSystem)](https://github.com/Atypical-Consulting/VirtualFileSystem/commits/master) +[![GitHub last commit](https://img.shields.io/github/last-commit/Atypical-Consulting/VirtualFileSystem)](https://github.com/Atypical-Consulting/VirtualFileSystem/commits/main) + + [![Build](https://github.com/Atypical-Consulting/VirtualFileSystem/actions/workflows/dotnet.yml/badge.svg)](https://github.com/Atypical-Consulting/VirtualFileSystem/actions/workflows/dotnet.yml) [![codecov](https://codecov.io/gh/Atypical-Consulting/VirtualFileSystem/branch/main/graph/badge.svg?token=041C4QKW6O)](https://codecov.io/gh/Atypical-Consulting/VirtualFileSystem) + [![NuGet](https://img.shields.io/nuget/v/Atypical.VirtualFileSystem.svg)](https://www.nuget.org/packages/Atypical.VirtualFileSystem) [![NuGet](https://img.shields.io/nuget/dt/Atypical.VirtualFileSystem.svg)](https://www.nuget.org/packages/Atypical.VirtualFileSystem) --- -## 📝 Table of Contents - - - * [📝 Table of Contents](#-table-of-contents) - * [📖 Introduction](#-introduction) - * [🧐 What is a virtual file system and why should I use it?](#-what-is-a-virtual-file-system-and-why-should-i-use-it) - * [📌 Features](#-features) - * [🎮 Demo Applications](#-demo-applications) - * [🌐 Blazor Server Demo](#-blazor-server-demo) - * [🖥️ Console Demo](#️-console-demo) - * [📄 Documentation](#-documentation) - * [📥 Installation](#-installation) - * [📋 Prerequisites](#-prerequisites) - * [🚀 We use the latest C# features](#-we-use-the-latest-c-features) - * [📦 NuGet](#-nuget) - * [📁 From source](#-from-source) - * [📚 Use cases](#-use-cases) - * [Creating a virtual file system, add some files and print the content as an ASCII tree](#creating-a-virtual-file-system-add-some-files-and-print-the-content-as-an-ascii-tree) - * [🤝 Contributing](#-contributing) - * [📜 License](#-license) - * [📬 Contact](#-contact) - * [🙌 Acknowledgements](#-acknowledgements) - * [🎉 Change log](#-change-log) - * [✨ Contributors](#-contributors) - - -## 📖 Introduction - -When writing applications in .NET, you often need to write or read the contents of a file. .NET provides `System.IO` -namespace dedicated to this purpose. But how do we deal with the filesystem when testing our code? - -**Virtual File System** is an attempt to solve this problem. This library provides a comprehensive virtual file system implementation with full CRUD operations, event-driven architecture, and undo/redo functionality. - -> 🎮 **New!** Check out our [interactive Blazor demo application](#-blazor-server-demo) that showcases all VFS features in a professional web interface! - -### 🧐 What is a virtual file system and why should I use it? - -A virtual file system is a data structure that represents a file system in memory. It is used to simulate a file system -on a computer. It is useful for testing purposes, for example, when you want to test a file system without actually -creating files on the hard drive. - -## 📌 Features +## Table of Contents + +- [The Problem](#the-problem) +- [The Solution](#the-solution) +- [Features](#features) +- [Tech Stack](#tech-stack) +- [Getting Started](#getting-started) +- [Usage](#usage) +- [Demo Applications](#demo-applications) +- [Architecture](#architecture) +- [Project Structure](#project-structure) +- [Documentation](#documentation) +- [Roadmap](#roadmap) +- [Contributing](#contributing) +- [License](#license) +- [Acknowledgments](#acknowledgments) + +## The Problem + +When writing .NET applications, you often need to read or write files. The standard `System.IO` namespace handles this well at runtime, but testing becomes painful. Unit tests that depend on the real filesystem are slow, brittle, leave temp files behind, and break in CI when paths differ across machines. Mocking `System.IO` is verbose and error-prone — you end up testing mock wiring instead of actual logic. + +## The Solution + +**Virtual File System** provides a complete in-memory filesystem that's fast, deterministic, and disposable. Create files and directories, read and write content, subscribe to change events, and even undo/redo operations — all without touching the real disk. + +```csharp +// Create a virtual file system and add some files +IVirtualFileSystem vfs = new VFS() + .CreateFile("src/Program.cs", "Console.WriteLine(\"Hello!\");") + .CreateFile("src/Utils.cs") + .CreateFile("tests/ProgramTests.cs"); + +// Print the tree +Console.WriteLine(vfs.GetTree()); +// vfs:// +// ├── src +// │ ├── Program.cs +// │ └── Utils.cs +// └── tests +// └── ProgramTests.cs +``` + +## Features - [x] Create a virtual file system -- [x] Create a virtual file or directory +- [x] Create, read, update, and delete virtual files and directories - [x] Print the contents of a virtual file system as a tree -- [x] Delete a virtual file or directory -- [x] Move a virtual file or directory -- [x] Rename a virtual file or directory -- [x] Read and write content to a virtual file +- [x] Move and rename virtual files and directories - [x] Check if a virtual file or directory exists (`TryGetFile`, `TryGetDirectory`) -- [x] Get the size of a virtual file or directory (via `Content.Length` and enumeration) -- [x] Get the creation, access, and modification times of a virtual file or directory -- [x] Support for events (file created, file deleted, etc.) -- [x] Support for undo/redo operations with change history +- [x] Get the size of a virtual file or directory +- [x] Get the creation, access, and modification times +- [x] Event-driven architecture (file created, deleted, moved, etc.) +- [x] Undo/redo operations with change history - [x] Advanced search capabilities (by name, content, regex patterns) - [x] File system analytics and insights -- [ ] Copy a virtual file or directory (planned) -- [ ] Support for custom metadata on files and directories (planned) -- [ ] Support for file and directory permissions (planned) -- [ ] Support for symbolic links (planned) -- ... +- [x] GitHub repository loading extension (via `Atypical.VirtualFileSystem.GitHub`) -## 🎮 Demo Applications +## Tech Stack -The Virtual File System library includes comprehensive demo applications that showcase its capabilities in real-world scenarios. +| Layer | Technology | +|-------|-----------| +| Language | C# 13 | +| Runtime | .NET 9.0 / .NET 10.0 | +| UI (Demo) | Blazor Server + Tailwind CSS | +| GitHub Integration | Octokit 14.x | +| DI | Microsoft.Extensions.DependencyInjection | +| CLI (Demo) | Spectre.Console | +| Testing | xUnit | +| Build | dotnet CLI / Nuke | -### 🌐 Blazor Server Demo +## Getting Started -A professional, full-featured web application built with **Blazor Server** and **MudBlazor** that provides an interactive demonstration of all VFS features. +### Prerequisites -#### 🚀 Getting Started with the Demo +- .NET 9.0 or higher (.NET 10.0 recommended) +- A C# IDE (Visual Studio, Rider, VS Code) -```bash -# Navigate to the demo application -cd src/Atypical.VirtualFileSystem.DemoBlazorApp +### Installation -# Run the demo application -dotnet run +**Option 1 — NuGet** *(recommended)* -# Open your browser to https://localhost:5040 +```bash +dotnet add package Atypical.VirtualFileSystem ``` -#### ✨ Demo Features - -The Blazor demo application includes: +Or add a package reference to your project file: -- **📊 Dashboard** - Welcome page with file system overview and quick actions -- **📁 File Operations** - Create, modify, delete files and directories with real-time feedback -- **🔍 Advanced Search** - Multi-criteria search (name, content, regex patterns, file extensions) -- **✏️ File Editor** - Full-featured text editor with find/replace, save/reload functionality -- **📈 Analytics** - Comprehensive file system analysis with metrics and insights -- **🕐 History Management** - Visual undo/redo operations with operation tracking -- **📋 Event Monitoring** - Real-time event stream with categorized statistics -- **💡 Responsive Design** - Mobile-friendly interface with professional UI/UX -- **🎨 Modern UI** - Built with MudBlazor components and Material Design principles - -#### 🏗️ Architecture Highlights - -- **Event-driven architecture** with real-time updates -- **State management** across components with proper synchronization -- **Professional UX** with loading states, error handling, and user feedback -- **Accessibility support** with ARIA labels and keyboard navigation -- **Responsive design** that works seamlessly on desktop and mobile devices - -### 🖥️ Console Demo +```xml + +``` -A command-line interface demonstration showcasing basic VFS operations: +**Option 2 — From Source** ```bash -# Navigate to the CLI demo -cd src/Atypical.VirtualFileSystem.DemoCli - -# Run the CLI demo -dotnet run +git clone https://github.com/Atypical-Consulting/VirtualFileSystem.git +cd VirtualFileSystem +dotnet build ``` -The CLI demo demonstrates file system operations, tree visualization, and event handling in a console environment. - -## 📄 Documentation +## Usage -**Virtual File System** provides a [COMPLETE DOCUMENTATION](https://github.com/Atypical-Consulting/VirtualFileSystem/blob/main/docs/README.md) of the library. +### Basic Example -All summaries are written in English. If you want to help us translate the documentation, please open an issue to -discuss it. +```csharp +// Create a virtual file system and populate it +IVirtualFileSystem vfs = new VFS() + .CreateFile("superheroes/batman.txt") + .CreateFile("superheroes/superman.txt") + .CreateFile("superheroes/wonderwoman.txt") + .CreateFile("villains/joker.txt") + .CreateFile("villains/lexluthor.txt") + .CreateFile("villains/penguin.txt") + .CreateFile("world/gotham.txt") + .CreateFile("world/metropolis.txt") + .CreateFile("world/themyscira.txt"); -> **Note:** The documentation is generated using [Doraku/DefaultDocumentation]() tool. It is generated automatically when the project is built. +// Get the string representation of the virtual file system +string tree = vfs.GetTree(); +``` -## 📥 Installation +Expected output: -### 📋 Prerequisites +``` +vfs:// +├── superheroes +│ ├── batman.txt +│ ├── superman.txt +│ └── wonderwoman.txt +├── villains +│ ├── joker.txt +│ ├── lexluthor.txt +│ └── penguin.txt +└── world + ├── gotham.txt + ├── metropolis.txt + └── themyscira.txt +``` -- .NET 6.0 or higher (supported versions: 6.x to 9.x) -- For the Blazor demo: .NET 9.0 or higher -- A C# IDE (Visual Studio, Rider, etc.) -- A C# compiler (dotnet CLI, etc.) +## Demo Applications -### 🚀 We use the latest C# features +The library includes comprehensive demo applications that showcase its capabilities. -This library targets .NET 8.0 and uses the latest C# features. It is written in C# 12.0 and uses the new `init` -properties, `record` types, `switch` expressions, `using` declarations and more. +### Blazor Server Demo -The Blazor demo application showcases modern .NET 9 features and demonstrates real-world usage patterns. +A full-featured web application built with **Blazor Server** and **Tailwind CSS** providing an interactive demonstration of all VFS features. -I invite you to read the [C# 12.0 documentation](https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-12) to -learn more about these features. +```bash +cd src/Atypical.VirtualFileSystem.DemoBlazorApp +dotnet run +# Open your browser to https://localhost:5040 +``` -### 📦 NuGet +**Demo features:** Dashboard with file system overview, file operations with real-time feedback, advanced multi-criteria search, full-featured file editor, analytics and insights, undo/redo history management, real-time event monitoring, and responsive design. -VirtualFileSystem is available on [NuGet](https://www.nuget.org/packages/Atypical.VirtualFileSystem). +### Console Demo -You can install it using the .NET CLI: +A command-line demonstration showcasing basic VFS operations: ```bash -dotnet add package Atypical.VirtualFileSystem +cd src/Atypical.VirtualFileSystem.DemoCli +dotnet run ``` -or by adding a package reference to your project file: +## Architecture -```xml - +``` +┌─────────────────────────────────────────────────────┐ +│ Consumer Code │ +│ (Your app / tests / demos) │ +└──────────────────────┬──────────────────────────────┘ + │ + ┌─────────────▼─────────────┐ + │ IVirtualFileSystem │ + │ (Core Interface) │ + └─────────────┬─────────────┘ + │ + ┌─────────────▼─────────────┐ + │ VFS (Implementation) │ + │ │ + │ ┌─────────────────────┐ │ + │ │ VirtualDirectory │ │ + │ │ VirtualFile │ │ + │ │ (Node Tree) │ │ + │ └─────────────────────┘ │ + │ │ + │ ┌─────────────────────┐ │ + │ │ UndoRedo Manager │ │ + │ │ (Change History) │ │ + │ └─────────────────────┘ │ + │ │ + │ ┌─────────────────────┐ │ + │ │ Event System │ │ + │ │ (Change Notifications)│ + │ └─────────────────────┘ │ + └─────────────┬─────────────┘ + │ + ┌──────────────────▼──────────────────┐ + │ Extensions │ + │ ┌──────────────────────────────┐ │ + │ │ VirtualFileSystem.GitHub │ │ + │ │ (Load repos into VFS) │ │ + │ └──────────────────────────────┘ │ + └─────────────────────────────────────┘ ``` -### 📁 From source - -You can also clone the repository and build the project yourself. +### Project Structure -```bash -git clone -cd VirtualFileSystem -dotnet build +``` +VirtualFileSystem/ +├── src/ +│ ├── Atypical.VirtualFileSystem.Core/ # Core library (IVirtualFileSystem, VFS, models) +│ │ ├── Contracts/ # Interfaces and abstractions +│ │ ├── Models/ # VirtualFile, VirtualDirectory, paths +│ │ ├── Services/ # Search, analytics services +│ │ ├── SystemOperations/ # File system operations +│ │ ├── UndoRedo/ # Undo/redo infrastructure +│ │ └── Extensions/ # Extension methods +│ ├── Atypical.VirtualFileSystem.GitHub/ # GitHub repo loader extension +│ ├── Atypical.VirtualFileSystem.DemoBlazorApp/ # Blazor Server demo +│ └── Atypical.VirtualFileSystem.DemoCli/ # Console demo +├── tests/ +│ ├── Atypical.VirtualFileSystem.UnitTests/ # Unit tests +│ ├── Atypical.VirtualFileSystem.GitHub.Tests/ # GitHub extension tests +│ └── Atypical.VirtualFileSystem.Benchmarks/ # Performance benchmarks +├── docs/ # Auto-generated API documentation +├── build/ # Build scripts +└── .github/workflows/ # CI/CD pipelines ``` -## 📚 Use cases +## Documentation -### Creating a virtual file system, add some files and print the content as an ASCII tree +**Virtual File System** provides [complete API documentation](https://github.com/Atypical-Consulting/VirtualFileSystem/blob/main/docs/README.md) generated automatically using [DefaultDocumentation](https://github.com/Doraku/DefaultDocumentation). -```csharp -// sample output (the order of the files is alphabetical) -string expected = """ - vfs:// - ├── superheroes - │ ├── batman.txt - │ ├── superman.txt - │ └── wonderwoman.txt - ├── villains - │ ├── joker.txt - │ ├── lexluthor.txt - │ └── penguin.txt - └── world - ├── gotham.txt - ├── metropolis.txt - └── themyscira.txt - """; - -// create a virtual file system -IVirtualFileSystem vfs = new VFS() - // add some files (directories are created automatically) - .CreateFile("superheroes/batman.txt") - .CreateFile("superheroes/superman.txt") - .CreateFile("superheroes/wonderwoman.txt") - .CreateFile("villains/joker.txt") - .CreateFile("villains/lexluthor.txt") - .CreateFile("villains/penguin.txt") - .CreateFile("world/gotham.txt") - .CreateFile("world/metropolis.txt") - .CreateFile("world/themyscira.txt"); +## Roadmap -// get the string representation of the virtual file system -string tree = vfs.GetTree(); -``` +- [ ] Copy a virtual file or directory +- [ ] Support for custom metadata on files and directories +- [ ] Support for file and directory permissions +- [ ] Support for symbolic links -## 🤝 Contributing +> Want to contribute? Pick any roadmap item and open a PR! -Contributions are welcome! Please read the [CONTRIBUTION GUIDELINES](https://github.com/Atypical-Consulting/VirtualFileSystem/blob/main/CONTRIBUTING.md) first. +## Stats -## 📜 License + + -This project is licensed under the terms of the BSD-3-Clause license. -If you use this library in your project, please consider adding a link to this repository in your project's README. +## Contributing -This project is maintained by [Atypical Consulting](https://www.atypical.consulting/). If you need help with this -project, please contact us from this repository by opening an issue. +Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first. -## 📬 Contact +1. Fork the repository +2. Create your feature branch (`git checkout -b feature/amazing-feature`) +3. Commit using [conventional commits](https://www.conventionalcommits.org/) (`git commit -m 'feat: add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request -You can contact us by opening an issue on this repository. +## License -## 🙌 Acknowledgements +[BSD-3-Clause](LICENSE) © 2022-2025 [Atypical Consulting](https://atypical.garry-ai.cloud) -* [All Contributors](../../contributors) -* [Atypical Consulting](https://www.atypical.consulting/) +## Acknowledgments -## 🎉 Change log +- [All Contributors](../../contributors) +- [Atypical Consulting](https://www.atypical.consulting/) +- [DefaultDocumentation](https://github.com/Doraku/DefaultDocumentation) for API doc generation +- [Spectre.Console](https://spectreconsole.net/) for beautiful CLI output +- [Octokit](https://github.com/octokit/octokit.net) for GitHub integration -Please see [RELEASES](https://github.com/Atypical-Consulting/VirtualFileSystem/releases) for more information what has changed recently. +--- -## ✨ Contributors +Built with care by [Atypical Consulting](https://atypical.garry-ai.cloud) — opinionated, production-grade open source. -[![Contributors](https://contrib.rocks/image?repo=Atypical-Consulting/VirtualFileSystem)](http://contrib.rocks) +[![Contributors](https://contrib.rocks/image?repo=Atypical-Consulting/VirtualFileSystem)](https://github.com/Atypical-Consulting/VirtualFileSystem/graphs/contributors)