@sriinnu/runic 2.0.0 → 2.11.2

package/Packages/Helix/Sources/Helix/Binding.swift

@@ -1,111 +0,0 @@
-import Foundation
-
-// Internal binding layer that connects ParsedValues to property wrappers.
-// This intentionally avoids Swift SPI/private reflection by using box-backed
-// wrapper storage. Mirror copies can still mutate shared box instances.
-
-protocol _HelixOptionBinding {
-    mutating func _helixBindOption(label: String, values: [String]?, environment: [String: String]) throws
-}
-
-protocol _HelixArgumentBinding {
-    mutating func _helixBindArgument(label: String, positional: [String], index: inout Int, isLast: Bool) throws
-}
-
-protocol _HelixFlagBinding {
-    mutating func _helixBindFlag(label: String, flags: Set<String>)
-}
-
-protocol _HelixOptionGroupBinding {
-    mutating func _helixBindGroup(parsed: ParsedValues, environment: [String: String]) throws
-}
-
-enum _HelixBinder {
-    static func bindCommand<Command>(
-        _ command: inout Command,
-        parsed: ParsedValues,
-        environment: [String: String]
-    ) throws {
-        var argumentBinders: [(label: String, bind: (inout Int, Bool) throws -> Void)] = []
-
-        try walk(
-            command,
-            parsed: parsed,
-            environment: environment,
-            allowArguments: true,
-            argumentBinders: &argumentBinders
-        )
-
-        var index = 0
-        for i in 0..<argumentBinders.count {
-            let isLast = (i == argumentBinders.count - 1)
-            try argumentBinders[i].bind(&index, isLast)
-        }
-
-        if index < parsed.positional.count {
-            let extras = parsed.positional[index...].joined(separator: " ")
-            throw HelixError.parsingError("Unexpected arguments: \(extras)")
-        }
-    }
-
-    static func bindGroupValue<Group>(
-        _ group: Group,
-        parsed: ParsedValues,
-        environment: [String: String]
-    ) throws {
-        var argumentBinders: [(label: String, bind: (inout Int, Bool) throws -> Void)] = []
-        try walk(
-            group,
-            parsed: parsed,
-            environment: environment,
-            allowArguments: false,
-            argumentBinders: &argumentBinders
-        )
-    }
-
-    private static func walk<Value>(
-        _ value: Value,
-        parsed: ParsedValues,
-        environment: [String: String],
-        allowArguments: Bool,
-        argumentBinders: inout [(label: String, bind: (inout Int, Bool) throws -> Void)]
-    ) throws {
-        let mirror = Mirror(reflecting: value)
-        for child in mirror.children {
-            guard let rawLabel = child.label else { continue }
-            let label = sanitize(rawLabel)
-
-            if var option = child.value as? _HelixOptionBinding {
-                try option._helixBindOption(label: label, values: parsed.options[label], environment: environment)
-                continue
-            }
-
-            if var flag = child.value as? _HelixFlagBinding {
-                flag._helixBindFlag(label: label, flags: parsed.flags)
-                continue
-            }
-
-            if let argument = child.value as? _HelixArgumentBinding {
-                if !allowArguments {
-                    throw HelixError.parsingError("Positional arguments are not supported in option groups")
-                }
-                argumentBinders.append(
-                    (label: label, bind: { index, isLast in
-                        var local = argument
-                        try local._helixBindArgument(label: label, positional: parsed.positional, index: &index, isLast: isLast)
-                    })
-                )
-                continue
-            }
-
-            if var group = child.value as? _HelixOptionGroupBinding {
-                try group._helixBindGroup(parsed: parsed, environment: environment)
-                continue
-            }
-        }
-    }
-
-    private static func sanitize(_ label: String) -> String {
-        label.hasPrefix("_") ? String(label.dropFirst()) : label
-    }
-}

package/Packages/Helix/Sources/Helix/CommandParser.swift

@@ -1,160 +0,0 @@
-import Foundation
-
-/// Parsed representation of `argv` after running `CommandParser`.
-public struct ParsedValues: Sendable, Equatable {
-    public var positional: [String]
-    public var options: [String: [String]]
-    public var flags: Set<String>
-
-    public init(positional: [String], options: [String: [String]], flags: Set<String>) {
-        self.positional = positional
-        self.options = options
-        self.flags = flags
-    }
-}
-
-/// Consumes tokenized arguments using a `CommandSignature`.
-public struct CommandParser {
-    let signature: CommandSignature
-
-    public init(signature: CommandSignature) {
-        self.signature = signature
-    }
-
-    public func parse(arguments: [String]) throws -> ParsedValues {
-        let tokens = CommandLineTokenizer.tokenize(arguments)
-        var positional: [String] = []
-        var options: [String: [String]] = [:]
-        var flags = Set<String>()
-
-        let optionLookup = Self.buildOptionLookup(self.signature.options)
-        let flagLookup = Self.buildFlagLookup(self.signature.flags)
-
-        var index = 0
-        while index < tokens.count {
-            let token = tokens[index]
-            index += 1
-            switch token {
-            case let .option(name):
-                if let definition = optionLookup[name] {
-                    guard index < tokens.count else {
-                        throw HelixError.parsingError("Missing value for option \(name)")
-                    }
-                    if case let .argument(value) = tokens[index] {
-                        options[definition.label, default: []].append(value)
-                        index += 1
-                    } else {
-                        throw HelixError.parsingError("Missing value for option \(name)")
-                    }
-                } else if let flagLabel = flagLookup[name] {
-                    flags.insert(flagLabel)
-                } else {
-                    throw HelixError.parsingError("Unknown option --\(name)")
-                }
-            case let .optionWithValue(name, value):
-                if let definition = optionLookup[name] {
-                    options[definition.label, default: []].append(value)
-                } else {
-                    throw HelixError.parsingError("Unknown option --\(name)")
-                }
-            case let .flag(name):
-                guard let flagLabel = flagLookup[name] else {
-                    throw HelixError.parsingError("Unknown option -\(name)")
-                }
-                flags.insert(flagLabel)
-            case let .argument(value):
-                positional.append(value)
-            case .terminator:
-                while index < tokens.count {
-                    if case let .argument(value) = tokens[index] {
-                        positional.append(value)
-                    }
-                    index += 1
-                }
-            }
-        }
-
-        return ParsedValues(positional: positional, options: options, flags: flags)
-    }
-
-    private static func buildOptionLookup(_ definitions: [OptionDefinition]) -> [String: OptionDefinition] {
-        var lookup: [String: OptionDefinition] = [:]
-        for definition in definitions {
-            for name in definition.names {
-                if let longName = name.longComponent {
-                    lookup[longName] = definition
-                } else if let shortName = name.shortComponent {
-                    lookup[String(shortName)] = definition
-                }
-            }
-        }
-        return lookup
-    }
-
-    private static func buildFlagLookup(_ definitions: [FlagDefinition]) -> [String: String] {
-        var lookup: [String: String] = [:]
-        for definition in definitions {
-            for name in definition.names {
-                if let longName = name.longComponent {
-                    lookup[longName] = definition.label
-                } else if let shortName = name.shortComponent {
-                    lookup[String(shortName)] = definition.label
-                }
-            }
-        }
-        return lookup
-    }
-
-}
-
-enum Token: Equatable, Sendable {
-    case option(name: String)
-    case optionWithValue(name: String, value: String)
-    case flag(name: String)
-    case argument(String)
-    case terminator
-}
-
-enum CommandLineTokenizer {
-    static func tokenize(_ argv: [String]) -> [Token] {
-        var result: [Token] = []
-        var iterator = argv.makeIterator()
-        while let segment = iterator.next() {
-            if segment == "--" {
-                result.append(.terminator)
-                result.append(contentsOf: iterator.map { .argument($0) })
-                break
-            } else if segment.hasPrefix("--") {
-                let name = String(segment.dropFirst(2))
-                if let equalsIndex = name.firstIndex(of: "=") {
-                    let option = String(name[..<equalsIndex])
-                    let value = String(name[name.index(after: equalsIndex)...])
-                    result.append(.optionWithValue(name: option, value: value))
-                } else {
-                    result.append(.option(name: name))
-                }
-            } else if segment.hasPrefix("-"), segment.count > 1 {
-                let body = segment.dropFirst()
-                if body.count == 1 {
-                    result.append(.option(name: String(body)))
-                } else if let equalsIndex = body.firstIndex(of: "=") {
-                    let name = String(body[..<equalsIndex])
-                    let value = String(body[body.index(after: equalsIndex)...])
-                    if name.count == 1 {
-                        result.append(.optionWithValue(name: name, value: value))
-                    } else {
-                        // Not a supported form (only -o=value is supported).
-                        result.append(.argument(segment))
-                    }
-                } else {
-                    for char in body {
-                        result.append(.flag(name: String(char)))
-                    }
-                }
-            } else {
-                result.append(.argument(segment))
-            }
-        }
-        return result
-    }
-}

package/Packages/Helix/Sources/Helix/CommandSignature.swift

@@ -1,117 +0,0 @@
-import Foundation
-
-/// Declarative description of all options, flags, and positional arguments.
-public struct CommandSignature: Sendable {
-    public private(set) var arguments: [ArgumentDefinition]
-    public private(set) var options: [OptionDefinition]
-    public private(set) var flags: [FlagDefinition]
-    public private(set) var optionGroups: [CommandSignature]
-
-    public init(
-        arguments: [ArgumentDefinition] = [],
-        options: [OptionDefinition] = [],
-        flags: [FlagDefinition] = [],
-        optionGroups: [CommandSignature] = [])
-    {
-        self.arguments = arguments
-        self.options = options
-        self.flags = flags
-        self.optionGroups = optionGroups
-    }
-
-    mutating func append(_ component: CommandComponent) {
-        switch component {
-        case let .argument(definition):
-            self.arguments.append(definition)
-        case let .option(definition):
-            self.options.append(definition)
-        case let .flag(definition):
-            self.flags.append(definition)
-        case let .group(signature):
-            self.optionGroups.append(signature)
-        }
-    }
-
-    /// Uses reflection to discover Helix property wrappers and build a signature.
-    public static func describe(_ command: some Any) -> CommandSignature {
-        var signature = CommandSignature()
-        Self.inspect(value: command, into: &signature)
-        return signature
-    }
-
-    private static func inspect(value: Any, into signature: inout CommandSignature) {
-        let mirror = Mirror(reflecting: value)
-        for child in mirror.children {
-            guard let label = child.label else { continue }
-            if let registrable = child.value as? HelixMetadata {
-                registrable.register(label: label, signature: &signature)
-            } else if let optionGroup = child.value as? HelixOptionGroup {
-                optionGroup.register(label: label, signature: &signature)
-            }
-        }
-    }
-
-    /// Returns a copy where nested option groups are merged into a single signature.
-    public func flattened() -> CommandSignature {
-        var combined = CommandSignature(
-            arguments: self.arguments,
-            options: self.options,
-            flags: self.flags)
-        for group in self.optionGroups {
-            let flattenedGroup = group.flattened()
-            combined.arguments.append(contentsOf: flattenedGroup.arguments)
-            combined.options.append(contentsOf: flattenedGroup.options)
-            combined.flags.append(contentsOf: flattenedGroup.flags)
-        }
-        return combined
-    }
-}
-
-/// Internal helper used by property wrappers.
-public enum CommandComponent: Sendable {
-    case argument(ArgumentDefinition)
-    case option(OptionDefinition)
-    case flag(FlagDefinition)
-    case group(CommandSignature)
-}
-
-/// Canonical description of an option.
-public struct OptionDefinition: Sendable, Equatable {
-    public let label: String
-    public let names: [HelixName]
-    public let help: String?
-    public let envVar: String?
-
-    public init(label: String, names: [HelixName], help: String?, envVar: String? = nil) {
-        self.label = label
-        self.names = names
-        self.help = help
-        self.envVar = envVar
-    }
-}
-
-/// Canonical description of a positional argument.
-public struct ArgumentDefinition: Sendable, Equatable {
-    public let label: String
-    public let help: String?
-    public let isOptional: Bool
-
-    public init(label: String, help: String?, isOptional: Bool) {
-        self.label = label
-        self.help = help
-        self.isOptional = isOptional
-    }
-}
-
-/// Canonical description of a boolean flag.
-public struct FlagDefinition: Sendable, Equatable {
-    public let label: String
-    public let names: [HelixName]
-    public let help: String?
-
-    public init(label: String, names: [HelixName], help: String?) {
-        self.label = label
-        self.names = names
-        self.help = help
-    }
-}

package/Packages/Helix/Sources/Helix/ExpressibleFromArgument.swift

@@ -1,72 +0,0 @@
-import Foundation
-
-/// Protocol used by Helix property wrappers to convert string arguments into typed values.
-public protocol ExpressibleFromArgument {
-    init?(argument: String)
-}
-
-extension String: ExpressibleFromArgument {
-    public init?(argument: String) { self = argument }
-}
-
-extension Substring: ExpressibleFromArgument {
-    public init?(argument: String) { self = Substring(argument) }
-}
-
-extension Int: ExpressibleFromArgument {
-    public init?(argument: String) { self.init(argument, radix: 10) }
-}
-
-extension Int32: ExpressibleFromArgument {
-    public init?(argument: String) { self.init(argument, radix: 10) }
-}
-
-extension Int64: ExpressibleFromArgument {
-    public init?(argument: String) { self.init(argument, radix: 10) }
-}
-
-extension Double: ExpressibleFromArgument {
-    public init?(argument: String) { self.init(argument) }
-}
-
-extension Float: ExpressibleFromArgument {
-    public init?(argument: String) { self.init(argument) }
-}
-
-extension Bool: ExpressibleFromArgument {
-    public init?(argument: String) {
-        let lowered = argument.lowercased()
-        switch lowered {
-        case "true", "t", "1", "yes", "y":
-            self = true
-        case "false", "f", "0", "no", "n":
-            self = false
-        default:
-            return nil
-        }
-    }
-}
-
-extension Optional: ExpressibleFromArgument where Wrapped: ExpressibleFromArgument {
-    public init?(argument: String) {
-        if let value = Wrapped(argument: argument) {
-            self = .some(value)
-        } else {
-            return nil
-        }
-    }
-}
-
-extension Array: ExpressibleFromArgument where Element: ExpressibleFromArgument {
-    public init?(argument: String) {
-        let parts = argument.split(separator: ",").map { String($0) }
-        var result: [Element] = []
-        for part in parts {
-            guard let value = Element(argument: part) else {
-                return nil
-            }
-            result.append(value)
-        }
-        self = result
-    }
-}

package/Packages/Helix/Sources/Helix/HelpGenerator.swift

@@ -1,175 +0,0 @@
-import Foundation
-
-/// Generates help text for commands.
-public struct HelpGenerator {
-    /// The command descriptor to generate help for.
-    public let descriptor: CommandDescriptor
-
-    /// Creates a new help generator.
-    public init(descriptor: CommandDescriptor) {
-        self.descriptor = descriptor
-    }
-
-    /// Generates the full help text.
-    public var output: String {
-        var result = ""
-
-        // Usage line
-        result += "USAGE: \(generateUsage())\n\n"
-
-        // Abstract
-        if !descriptor.abstract.isEmpty {
-            result += "\(descriptor.abstract)\n\n"
-        }
-
-        // Discussion
-        if let discussion = descriptor.discussion, !discussion.isEmpty {
-            result += "\(discussion)\n\n"
-        }
-
-        // Options
-        let flattened = descriptor.signature.flattened()
-        if !flattened.options.isEmpty || !flattened.flags.isEmpty {
-            result += "OPTIONS:\n"
-            for option in flattened.options {
-                result += "  \(formatOption(option))\n"
-            }
-            for flag in flattened.flags {
-                result += "  \(formatFlag(flag))\n"
-            }
-            result += "\n"
-        }
-
-        // Arguments
-        if !flattened.arguments.isEmpty {
-            result += "ARGUMENTS:\n"
-            for arg in flattened.arguments {
-                result += "  \(formatArgument(arg))\n"
-            }
-            result += "\n"
-        }
-
-        // Subcommands
-        if !descriptor.subcommands.isEmpty {
-            result += "SUBCOMMANDS:\n"
-            for subcommand in descriptor.subcommands {
-                result += "  \(subcommand.name)"
-                if !subcommand.abstract.isEmpty {
-                    result += " - \(subcommand.abstract)"
-                }
-                result += "\n"
-            }
-        }
-
-        return result
-    }
-
-    private func generateUsage() -> String {
-        var parts: [String] = [descriptor.name]
-
-        // Add subcommands hint
-        if !descriptor.subcommands.isEmpty {
-            parts.append("<subcommand>")
-        }
-
-        let flattened = descriptor.signature.flattened()
-
-        // Add flags
-        for flag in flattened.flags {
-            if let flagName = preferredFlagUsageName(flag.names) {
-                parts.append("[\(flagName)]")
-            }
-        }
-
-        // Add options (simplified - just shows placeholders)
-        for option in flattened.options {
-            let optionName = preferredOptionUsageName(option.names) ?? "--\(option.label)"
-            parts.append("[\(optionName) <\(option.label)>]")
-        }
-
-        // Add required arguments
-        for arg in flattened.arguments where !arg.isOptional {
-            parts.append("<\(arg.label)>")
-        }
-
-        // Add optional arguments
-        for arg in flattened.arguments where arg.isOptional {
-            parts.append("[\(arg.label)]")
-        }
-
-        return parts.joined(separator: " ")
-    }
-
-    private func formatOption(_ option: OptionDefinition) -> String {
-        var parts: [String] = []
-
-        for name in option.names {
-            if let short = name.shortComponent {
-                parts.append("-\(short) <\(option.label)>")
-            }
-            if let long = name.longComponent {
-                parts.append("--\(long) <\(option.label)>")
-            }
-        }
-
-        let joined = parts.joined(separator: ", ")
-        return formatHelpLine(joined, help: option.help)
-    }
-
-    private func formatFlag(_ flag: FlagDefinition) -> String {
-        var parts: [String] = []
-
-        for name in flag.names {
-            if let short = name.shortComponent {
-                parts.append("-\(short)")
-            }
-            if let long = name.longComponent {
-                parts.append("--\(long)")
-            }
-        }
-
-        let joined = parts.joined(separator: ", ")
-        return formatHelpLine(joined, help: flag.help)
-    }
-
-    private func formatArgument(_ arg: ArgumentDefinition) -> String {
-        let label = arg.isOptional ? "[\(arg.label)]" : "<\(arg.label)>"
-        return formatHelpLine(label, help: arg.help)
-    }
-
-    private func formatHelpLine(_ label: String, help: String?) -> String {
-        guard let help else { return label }
-        let width = 40
-        let paddingCount = max(1, width - label.count)
-        return label + String(repeating: " ", count: paddingCount) + help
-    }
-
-    private func preferredFlagUsageName(_ names: [HelixName]) -> String? {
-        if let short = names.first(where: { $0.shortComponent != nil })?.shortComponent {
-            return "-\(short)"
-        }
-        if let long = names.first(where: { $0.longComponent != nil })?.longComponent {
-            return "--\(long)"
-        }
-        return nil
-    }
-
-    private func preferredOptionUsageName(_ names: [HelixName]) -> String? {
-        if let long = names.first(where: { $0.longComponent != nil })?.longComponent {
-            return "--\(long)"
-        }
-        if let short = names.first(where: { $0.shortComponent != nil })?.shortComponent {
-            return "-\(short)"
-        }
-        return nil
-    }
-}
-
-// MARK: - Help Text Generation Helper
-
-extension HelixError {
-    /// Generates help text for the given descriptor.
-    public static func helpText(for descriptor: CommandDescriptor) -> String {
-        HelpGenerator(descriptor: descriptor).output
-    }
-}