Architecture

Project Overview

List is built as a modular Swift package with clear separation of concerns. The project is organized into three main modules that work together to provide a fast, feature-rich file listing tool.

sls

Executable TargetEntry point for the CLI application

SwiftListCLI

CLI ModuleCommand-line interface and argument parsing

SwiftListCore

Core LibraryBusiness logic and file system operations

Module Structure

Dependency Graph

Module Responsibilities

sls (Executable)
SwiftListCLI
SwiftListCore

Location: Sources/SwiftList/main.swiftThe minimal entry point that launches the CLI application:

import SwiftListCLI

ListCommand.main()

Purpose:

Single responsibility: bootstrap the application
Depends only on SwiftListCLI
Keeps the executable target simple and focused

Location: Sources/SwiftListCLI/Handles all command-line interface concerns:Key Components:

ListCommand.swift - Main command implementation using ArgumentParser

Responsibilities:

Parse command-line arguments and flags
Define CLI options (—long, —all, —sort, etc.)
Coordinate between user input and core functionality
Format and display output to the terminal

Dependencies:

SwiftListCore (business logic)
ArgumentParser (CLI framework)

Location: Sources/SwiftListCore/Contains the core business logic and file system operations:Directory Structure:

SwiftListCore/
├── Configuration/
│   ├── DisplayOptions.swift
│   └── SortOption.swift
├── Models/
│   └── FileRepresentation.swift
└── Utilities/
    ├── FileManagerHelper.swift
    └── TerminalColors.swift

Responsibilities:

File system operations and traversal
Formatting and colorization logic
Sorting and filtering algorithms
Platform-specific file attribute handling

Dependencies:

ArgumentParser (for SortOption enum)
Foundation (file system access)
Darwin/Glibc (platform-specific operations)

Core Components

ListCommand

File: Sources/SwiftListCLI/ListCommand.swift The main command that ties everything together:

public struct ListCommand: ParsableCommand {
    public static let configuration = CommandConfiguration(
        commandName: "sls",
        version: "1.5.0"
    )
    
    // Flags and options...
    @Flag(name: .shortAndLong) var all = false
    @Flag(name: .shortAndLong) var long = false
    @Option(name: [.customShort("L"), .long]) var depthLimit: Int?
    @Argument var paths: [String] = []
    
    public func run() throws {
        // Build DisplayOptions from flags
        // Call FileManagerHelper.contents()
        // Print results
    }
}

Key Features:

Uses Swift ArgumentParser for declarative CLI definition
Supports 13+ command-line flags and options
Handles multiple path arguments
Translates CLI flags into DisplayOptions

DisplayOptions

File: Sources/SwiftListCore/Configuration/DisplayOptions.swift Configuration struct that controls how files are displayed:

public struct DisplayOptions {
    var location: URL?
    var all: Bool = false              // Show hidden files
    var long: Bool = false             // Long format
    var recurse: Bool = false          // Recursive listing
    var color: Bool = false            // Colorized output
    var icons: Bool = false            // Show file icons
    var oneLine: Bool = false          // One file per line
    var humanReadable: Bool = false    // Human-readable sizes
    var directoryOnly: Bool = false    // List dir itself
    var classify: Bool = false         // Append indicators
    var sortBy: SortOption = .name     // Sort method
    var depthLimit: Int?               // Recursion limit
}

FileManagerHelper

File: Sources/SwiftListCore/Utilities/FileManagerHelper.swift The workhorse class that handles all file system operations: Key Methods:

Method	Purpose
`contents(with:currentDepth:)`	Main entry point - lists directory contents
`fileAttributes(at:with:)`	Retrieves and formats file attributes
`determineType(of:attributes:)`	Determines file type (directory, symlink, executable, file)
`terminalWidth()`	Gets terminal width for formatting

Features:

Handles symbolic links correctly (uses lstat)
Supports recursive directory traversal with depth limiting
Intelligent terminal width wrapping
Platform-specific file attribute handling (Darwin/Glibc)
Sorts files by name, size, or modification time

FileManagerHelper uses lstat for symbolic links to get the link’s own attributes rather than following the link to its target.

FileRepresentation

File: Sources/SwiftListCore/Models/FileRepresentation.swift Model for file visual representation:

public struct FileRepresentation {
    let icon: String        // "📁", "📄", "🔗", "⚙️"
    let color: String       // ANSI color code
    let destination: String? // For symlinks
}

File Type Mapping:

📁 Directories (blue)
📄 Regular files (white)
🔗 Symbolic links (yellow) - shows destination
⚙️ Executable files (red)

SortOption

File: Sources/SwiftListCore/Configuration/SortOption.swift Enum defining sort methods:

public enum SortOption: String, ExpressibleByArgument {
    case name  // Alphabetical (default)
    case time  // Most recent first
    case size  // Largest first
}

TerminalColors

File: Sources/SwiftListCore/Utilities/TerminalColors.swift Provides ANSI color codes for terminal output:

Blue for directories
Yellow for symbolic links
Red for executables
White for regular files
Reset code to clear formatting

Data Flow

User Input

User runs sls --long --color /path in terminal

Argument Parsing

ListCommand (ArgumentParser) parses flags and arguments

Options Building

CLI flags are converted into a DisplayOptions struct

File System Query

FileManagerHelper.contents() is called with options:

Lists directory contents
Gets file attributes for each item
Determines file type (icon & color)
Sorts according to sortBy option

Formatting

Files are formatted based on display options:

Long format: permissions, owner, size, date
Icons: file type emoji
Colors: ANSI escape codes
Wrapping: terminal width calculation

Output

Formatted string is printed to stdout

Design Patterns

Separation of Concerns

CLI Layer

SwiftListCLI handles user interaction

Argument parsing
Command definitions
User-facing error messages

Business Logic

SwiftListCore handles implementation

File system operations
Sorting and filtering
Formatting logic

Benefits:

Core library can be reused in other projects
Easy to test business logic independently
Clear boundaries between layers

Configuration Object

DisplayOptions acts as a configuration object passed through the system:

Immutable options (struct semantics)
Single source of truth for display behavior
Easy to extend with new options
Testable configurations

Platform Abstraction

Platform-specific code is isolated:

#if canImport(Darwin)
import Darwin
#elseif canImport(Glibc)
import Glibc
#endif

Enables cross-platform support (macOS/Linux) without code duplication.

Testing Architecture

Location: Tests/SwiftListTests.swift Test suite using the modern Swift Testing framework:

Tests both SwiftListCore and SwiftListCLI modules
Uses swift-testing (0.11.0+) for modern test syntax
Validates file operations and formatting logic

The project uses Swift Testing instead of XCTest for a more modern testing experience with better ergonomics.

External Dependencies

swift-argument-parser (1.0.0+)

Purpose: Command-line argument parsingUsed by:

SwiftListCLI (ListCommand definition)
SwiftListCore (SortOption enum)

Features utilized:

@Flag, @Option, @Argument property wrappers
ParsableCommand protocol
CommandConfiguration for metadata
Automatic help generation

swift-docc-plugin (1.4.3+)

Purpose: Documentation generationEnables:

swift package generate-documentation command
API documentation from doc comments
Interactive documentation browsing

swift-testing (0.11.0+)

Purpose: Modern testing frameworkUsed in:

SwiftListTests target

Benefits:

Modern Swift syntax
Better error messages
Improved test organization

Code Organization Best Practices

The project follows Swift best practices:

Modular design - Clear module boundaries
Protocol-oriented - Uses Swift protocols (ParsableCommand)
Value types - Structs for DisplayOptions, FileRepresentation
Documentation - Comprehensive doc comments
Type safety - Enums for SortOption
Cross-platform - Conditional compilation for Darwin/Glibc

Get Started

Command Reference

Configuration

Library API

Development

Project Overview

sls

SwiftListCLI

SwiftListCore

Module Structure

Dependency Graph

Module Responsibilities

Core Components

ListCommand

DisplayOptions

FileManagerHelper

FileRepresentation

SortOption

TerminalColors

Data Flow

Design Patterns

Separation of Concerns

CLI Layer

Business Logic

Configuration Object

Platform Abstraction

Testing Architecture

External Dependencies

Code Organization Best Practices

Next Steps

Building

Contributing

Build docs developers (and LLMs) love

Get Started

Command Reference

Configuration

Library API

Development

​Project Overview

sls

SwiftListCLI

SwiftListCore

​Module Structure

​Dependency Graph

​Module Responsibilities

​Core Components

​ListCommand

​DisplayOptions

​FileManagerHelper

​FileRepresentation

​SortOption

​TerminalColors

​Data Flow

​Design Patterns

​Separation of Concerns

CLI Layer

Business Logic

​Configuration Object

​Platform Abstraction

​Testing Architecture

​External Dependencies

​Code Organization Best Practices

​Next Steps

Building

Contributing

Build docs developers (and LLMs) love

Project Overview

Module Structure

Dependency Graph

Module Responsibilities

Core Components

ListCommand

DisplayOptions

FileManagerHelper

FileRepresentation

SortOption

TerminalColors

Data Flow

Design Patterns

Separation of Concerns

Configuration Object

Platform Abstraction

Testing Architecture

External Dependencies

Code Organization Best Practices

Next Steps