SPB Git

Repository Public

PortfolioImport.swift 20.7 KB 371 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Core/Analytics/PortfolioImport.swift3// Description: Pure portfolio logic: reading a CSV of holdings (parsing, column mapping guess, row validation, replace or merge), valuation by currency without any implicit conversion, quote batching and the arithmetic of a rebalancing proposal.4import Foundation56// MARK: - CSV reading78public enum CSVReader {9    /// The delimiter of a file, read from its first line: the candidate that splits it into the most cells10    /// (quotes respected). A comma when nothing else is found.11    public static func delimiter(of text: String) -> Character {12        let first = text.split(omittingEmptySubsequences: true, whereSeparator: { $0 == "\n" || $0 == "\r" }).first.map(String.init) ?? ""13        var best: (Character, Int) = (",", 0)14        for d in [",", ";", "\t", "|"] as [Character] {15            let n = parse(first, delimiter: d).first?.count ?? 016            if n > best.1 { best = (d, n) }17        }18        return best.019    }2021    /// RFC 4180 records: quoted fields, doubled quotes, line breaks inside quotes, CRLF or LF. A leading byte-order22    /// mark is dropped; lines that are entirely empty are skipped.23    public static func parse(_ text: String, delimiter: Character? = nil) -> [[String]] {24        var s = Substring(text)25        if s.first == "\u{FEFF}" { s = s.dropFirst() }26        let d = delimiter ?? self.delimiter(of: String(s))27        var records: [[String]] = []28        var record: [String] = []29        var field = ""30        var quoted = false, wasQuoted = false31        var i = s.startIndex32        func endField() { record.append(wasQuoted ? field : field.trimmingCharacters(in: .whitespaces)); field = ""; wasQuoted = false }33        func endRecord() {34            endField()35            if !(record.count == 1 && record[0].isEmpty) { records.append(record) }36            record = []37        }38        while i < s.endIndex {39            let c = s[i]40            if quoted {41                if c == "\"" {42                    let next = s.index(after: i)43                    if next < s.endIndex, s[next] == "\"" { field.append("\""); i = next } else { quoted = false }44                } else { field.append(c) }45            } else if c == "\"", field.trimmingCharacters(in: .whitespaces).isEmpty {46                quoted = true; wasQuoted = true; field = ""47            } else if c == d {48                endField()49            } else if c == "\n" || c == "\r" || c == "\r\n" {50                endRecord()51            } else { field.append(c) }52            i = s.index(after: i)53        }54        if !field.isEmpty || !record.isEmpty || wasQuoted { endRecord() }55        return records56    }57}5859// MARK: - Import of holdings6061/// A CSV of holdings on its way into a portfolio: the records as read, a column mapping (guessed, then corrected by62/// the person) and the rows that mapping yields, each one valid or flagged with the reason.63public struct PortfolioImport: Sendable, Equatable {64    public enum Field: String, Sendable, CaseIterable, Identifiable {65        case symbol, quantity, costBasis, currency, openedAt, note66        public var id: String { rawValue }67        public var title: String {68            switch self { case .symbol: "Symbol"; case .quantity: "Quantity"; case .costBasis: "Cost basis"; case .currency: "Currency"; case .openedAt: "Opened"; case .note: "Note" }69        }70        public var isRequired: Bool { self == .symbol || self == .quantity }71        /// Header words (lower-case, letters and digits only) that name this field, by decreasing confidence.72        var aliases: [String] {73            switch self {74            case .symbol: ["symbol", "ticker", "symbole", "titre", "security", "instrument", "code", "asset"]75            case .quantity: ["quantity", "qty", "quantite", "shares", "units", "nombre", "position", "amount", "holding", "parts", "actions"]76            case .costBasis: ["costbasis", "cost", "avgcost", "averagecost", "averageprice", "avgprice", "purchaseprice", "prixmoyen", "coutmoyen", "cout", "prixdachat", "bookprice", "price", "prix"]77            case .currency: ["currency", "ccy", "devise", "cur", "monnaie"]78            case .openedAt: ["openedat", "opened", "date", "purchasedate", "tradedate", "opendate", "acquired", "dateachat", "datedachat", "ouverture"]79            case .note: ["note", "notes", "comment", "comments", "commentaire", "description", "memo", "remarque"]80            }81        }82    }8384    public enum Mode: String, Sendable, CaseIterable, Identifiable {85        case merge, replace86        public var id: String { rawValue }87    }8889    public struct Row: Sendable, Equatable, Identifiable {90        /// 1-based line among the data records (the header is not counted).91        public var line: Int92        public var symbol: String93        public var quantity: Double?94        public var costBasis: Double?95        public var currency: String?96        public var openedAt: Date?97        public var note: String?98        /// Why the row cannot be imported (empty = valid).99        public var issues: [String]100        /// What was dropped from an otherwise valid row.101        public var warnings: [String]102        public var id: Int { line }103        public var isValid: Bool { issues.isEmpty }104    }105106    public var hasHeader: Bool107    public var header: [String]108    public var records: [[String]]109    public var mapping: [Field: Int]110111    public var columnCount: Int { max(header.count, records.map(\.count).max() ?? 0) }112    /// "Symbol" or "Column 3" when the file has no header.113    public func columnTitle(_ index: Int) -> String {114        hasHeader && index < header.count && !header[index].isEmpty ? header[index] : "Column \(index + 1)"115    }116117    public init(csv: String) {118        let all = CSVReader.parse(csv)119        let first = all.first ?? []120        let guessed = Self.guess(header: first)121        // a first line that names a symbol or a quantity column is a header; otherwise the columns are positional122        if guessed[.symbol] != nil || guessed[.quantity] != nil {123            hasHeader = true; header = first; records = Array(all.dropFirst()); mapping = guessed124        } else {125            hasHeader = false; header = []; records = all126            mapping = Self.positional(sample: first)127        }128    }129130    static func key(_ s: String) -> String {131        String(s.folding(options: [.diacriticInsensitive, .caseInsensitive], locale: Locale(identifier: "en_US_POSIX")).lowercased().unicodeScalars.filter { CharacterSet.alphanumerics.contains($0) })132    }133134    /// Exact alias first, then an alias contained in the header word; a column is given to one field only.135    public static func guess(header: [String]) -> [Field: Int] {136        let keys = header.map(key)137        var out: [Field: Int] = [:]138        var used = Set<Int>()139        for exact in [true, false] {140            for f in Field.allCases where out[f] == nil {141                search: for alias in f.aliases {142                    for (i, k) in keys.enumerated() where !used.contains(i) && !k.isEmpty {143                        if exact ? k == alias : (k.contains(alias) && alias.count >= 4) { out[f] = i; used.insert(i); break search }144                    }145                }146            }147        }148        return out149    }150151    /// No header: symbol, quantity, cost in that order when the first record looks like it.152    static func positional(sample: [String]) -> [Field: Int] {153        var out: [Field: Int] = [:]154        guard sample.count >= 2, normalizeSymbol(sample[0]) != nil, number(sample[0]) == nil, number(sample[1]) != nil else { return out }155        out[.symbol] = 0; out[.quantity] = 1156        if sample.count >= 3, number(sample[2]) != nil { out[.costBasis] = 2 }157        return out158    }159160    /// "1,234.56", "1 234,56", "(120)", "$45.10", "12,5": the decimal mark is the last of `.`/`,` when both appear;161    /// a lone comma followed by exactly three digits is read as a thousands separator only when another group precedes162    /// it ("1,234,567"), otherwise as a decimal comma… except "1,234" which is ambiguous and read as 1234.163    public static func number(_ raw: String) -> Double? {164        var s = raw.trimmingCharacters(in: .whitespaces)165        guard !s.isEmpty else { return nil }166        var negative = false167        if s.hasPrefix("("), s.hasSuffix(")") { negative = true; s = String(s.dropFirst().dropLast()) }168        s = String(s.filter { !($0 == " " || $0 == "\u{00A0}" || $0 == "\u{202F}" || $0 == "$" || $0 == "€" || $0 == "£" || $0 == "'") })169        if s.hasPrefix("-") || s.hasPrefix("−") { negative.toggle(); s = String(s.dropFirst()) } else if s.hasPrefix("+") { s = String(s.dropFirst()) }170        guard !s.isEmpty, s.allSatisfy({ $0.isASCII && ($0.isNumber || $0 == "." || $0 == ",") }) else { return nil }171        let dots = s.filter { $0 == "." }.count, commas = s.filter { $0 == "," }.count172        if dots > 0, commas > 0 {173            let decimal: Character = s.lastIndex(of: ".")! > s.lastIndex(of: ",")! ? "." : ","174            let group: Character = decimal == "." ? "," : "."175            guard s.filter({ $0 == decimal }).count == 1 else { return nil }176            s = String(s.filter { $0 != group }).replacingOccurrences(of: String(decimal), with: ".")177        } else if commas > 1 || dots > 1 {178            // several identical separators: thousands groups179            let sep: Character = commas > 1 ? "," : "."180            let parts = s.split(separator: sep, omittingEmptySubsequences: false)181            guard parts.dropFirst().allSatisfy({ $0.count == 3 }), let head = parts.first, !head.isEmpty, head.count <= 3 else { return nil }182            s = parts.joined()183        } else if commas == 1 {184            let parts = s.split(separator: ",", omittingEmptySubsequences: false)185            if parts.count == 2, parts[1].count == 3, !parts[0].isEmpty, parts[0].count <= 3, parts[0] != "0" { s = parts.joined() }   // 1,234186            else { s = s.replacingOccurrences(of: ",", with: ".") }187        }188        guard let v = Double(s), v.isFinite else { return nil }189        return negative ? -v : v190    }191192    /// ISO dates only (`2024-03-15`, `2024/03/15`, an ISO date-time): day-first and month-first forms cannot be told193    /// apart, so they are refused rather than guessed. The date is read as noon UTC of that day.194    public static func date(_ raw: String) -> Date? {195        let s = raw.trimmingCharacters(in: .whitespaces)196        let head = s.prefix(10).replacingOccurrences(of: "/", with: "-")197        let parts = head.split(separator: "-")198        guard parts.count == 3, parts[0].count == 4, let y = Int(parts[0]), let m = Int(parts[1]), let d = Int(parts[2]), (1...12).contains(m), (1...31).contains(d), (1900...2200).contains(y) else { return nil }199        if s.count > 10, !(s.dropFirst(10).first == "T" || s.dropFirst(10).first == " ") { return nil }200        var cal = Calendar(identifier: .gregorian); cal.timeZone = TimeZone(identifier: "UTC")!201        guard let date = cal.date(from: DateComponents(year: y, month: m, day: d, hour: 12)), cal.component(.day, from: date) == d else { return nil }202        return date203    }204205    /// Upper-case ticker of at most 24 characters among letters, digits and `. - ^ = /` (the server's own rule is the authority).206    public static func normalizeSymbol(_ raw: String) -> String? {207        let s = raw.trimmingCharacters(in: .whitespaces).uppercased()208        guard !s.isEmpty, s.count <= 24, s.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || ".-^=/".contains($0)) }), s.contains(where: { $0.isLetter }) else { return nil }209        return s210    }211212    /// The records read through the current mapping. A symbol that appears twice is valid once: later lines are flagged.213    public var rows: [Row] {214        var seen: [String: Int] = [:]215        func cell(_ r: [String], _ f: Field) -> String { mapping[f].flatMap { $0 < r.count ? r[$0] : nil } ?? "" }216        return records.enumerated().map { i, r in217            var row = Row(line: i + 1, symbol: cell(r, .symbol), quantity: nil, costBasis: nil, currency: nil, openedAt: nil, note: nil, issues: [], warnings: [])218            if mapping[.symbol] == nil { row.issues.append("no symbol column") }219            else if let s = Self.normalizeSymbol(row.symbol) {220                row.symbol = s221                if let first = seen[s] { row.issues.append("duplicate of line \(first)") } else { seen[s] = i + 1 }222            } else { row.issues.append(row.symbol.isEmpty ? "symbol missing" : "not a ticker symbol") }223            let q = cell(r, .quantity)224            if mapping[.quantity] == nil { row.issues.append("no quantity column") }225            else if let v = Self.number(q) { if v == 0 { row.issues.append("quantity is zero") } else { row.quantity = v } }226            else { row.issues.append(q.isEmpty ? "quantity missing" : "quantity “\(q)” is not a number") }227            let c = cell(r, .costBasis)228            if !c.isEmpty { if let v = Self.number(c), v >= 0 { row.costBasis = v } else { row.issues.append("cost “\(c)” is not a positive number") } }229            let cur = cell(r, .currency).uppercased()230            if !cur.isEmpty { if cur.count == 3, cur.allSatisfy({ $0.isASCII && $0.isLetter }) { row.currency = cur } else { row.warnings.append("currency “\(cur)” ignored (3-letter code expected)") } }231            let d = cell(r, .openedAt)232            if !d.isEmpty { if let v = Self.date(d) { row.openedAt = v } else { row.warnings.append("date “\(d)” ignored (YYYY-MM-DD expected)") } }233            let n = cell(r, .note)234            if !n.isEmpty { row.note = n }235            return row236        }237    }238239    public var validRows: [Row] { rows.filter(\.isValid) }240241    /// What the import does to the symbols already held: counts for the confirmation line.242    public func effect(on existing: [String], mode: Mode) -> (added: Int, updated: Int, removed: Int, kept: Int) {243        let incoming = Set(validRows.map(\.symbol)), held = Set(existing)244        let updated = incoming.intersection(held).count, added = incoming.subtracting(held).count245        let untouched = held.subtracting(incoming).count246        return mode == .replace ? (added, updated, untouched, 0) : (added, updated, 0, untouched)247    }248}249250// MARK: - Valuation by currency251252public struct HoldingInput: Sendable, Equatable {253    public var symbol: String254    public var quantity: Double255    public var costBasis: Double?256    /// The currency recorded on the position, if any (the quote's currency has priority: it is what the price is in).257    public var currency: String?258    public init(symbol: String, quantity: Double, costBasis: Double? = nil, currency: String? = nil) { self.symbol = symbol; self.quantity = quantity; self.costBasis = costBasis; self.currency = currency }259}260261public struct HoldingQuote: Sendable, Equatable {262    public var price: Double?263    public var change: Double?264    /// Percentage points.265    public var changePct: Double?266    public var currency: String?267    public var asOf: Date?268    public init(price: Double?, change: Double? = nil, changePct: Double? = nil, currency: String? = nil, asOf: Date? = nil) { self.price = price; self.change = change; self.changePct = changePct; self.currency = currency; self.asOf = asOf }269}270271/// Market value of holdings from quotes, **grouped by currency**: amounts in different currencies are never added.272/// A position without a price is listed as unpriced and left out of every total. Cost and P&L totals of a group273/// exist only when each of its priced lines has a cost basis (otherwise the total would mix scopes).274public struct HoldingsValuation: Sendable, Equatable {275    public static let unknownCurrency = "—"276277    public struct Line: Sendable, Equatable, Identifiable {278        public var holding: HoldingInput279        public var quote: HoldingQuote?280        public var currency: String281        public var id: String { holding.symbol }282        public var marketValue: Double? { quote?.price.map { $0 * holding.quantity } }283        public var cost: Double? { holding.costBasis.map { $0 * holding.quantity } }284        public var pnl: Double? { if let mv = marketValue, let c = cost { mv - c } else { nil } }285        public var pnlPercent: Double? { if let p = pnl, let c = cost, c != 0 { p / abs(c) * 100 } else { nil } }286        public var dayChange: Double? { quote?.change.map { $0 * holding.quantity } }287        /// Share of the gross market value of the positions **of the same currency**, in percent.288        public var weight: Double?289    }290291    public struct Group: Sendable, Equatable, Identifiable {292        public var currency: String293        public var marketValue: Double294        public var cash: Double295        public var cost: Double?296        public var pnl: Double?297        public var dayChange: Double?298        public var positions: Int299        public var id: String { currency }300        public var total: Double { marketValue + cash }301        public var pnlPercent: Double? { if let p = pnl, let c = cost, c != 0 { p / abs(c) * 100 } else { nil } }302        /// Day change against the value at the previous close, in percentage points.303        public var dayChangePercent: Double? { if let d = dayChange, marketValue - d != 0 { d / abs(marketValue - d) * 100 } else { nil } }304    }305306    public var lines: [Line]307    /// The base currency first, then by decreasing value.308    public var groups: [Group]309    public var unpriced: [String]310    /// The oldest quote timestamp among priced lines.311    public var asOf: Date?312    public var isSingleCurrency: Bool { groups.count <= 1 }313314    public init(holdings: [HoldingInput], quotes: [String: HoldingQuote], cash: [(currency: String, amount: Double)] = [], baseCurrency: String = "USD") {315        var lines = holdings.map { h -> Line in316            let q = quotes[h.symbol]317            return Line(holding: h, quote: q, currency: (q?.currency ?? h.currency).flatMap { $0.isEmpty ? nil : $0.uppercased() } ?? Self.unknownCurrency)318        }319        var gross: [String: Double] = [:]320        for l in lines { if let mv = l.marketValue { gross[l.currency, default: 0] += abs(mv) } }321        for i in lines.indices { if let mv = lines[i].marketValue, let g = gross[lines[i].currency], g != 0 { lines[i].weight = abs(mv) / g * 100 } }322        self.lines = lines323        unpriced = lines.filter { $0.marketValue == nil }.map(\.holding.symbol)324        asOf = lines.compactMap { $0.marketValue == nil ? nil : $0.quote?.asOf }.min()325326        var cashBy: [String: Double] = [:]327        for c in cash where c.amount != 0 { cashBy[c.currency.uppercased(), default: 0] += c.amount }328        var order: [String] = []329        for l in lines where l.marketValue != nil && !order.contains(l.currency) { order.append(l.currency) }330        for c in cashBy.keys.sorted() where !order.contains(c) { order.append(c) }331        var groups = order.map { cur -> Group in332            let priced = lines.filter { $0.currency == cur && $0.marketValue != nil }333            let mv = priced.compactMap(\.marketValue).reduce(0, +)334            var g = Group(currency: cur, marketValue: mv, cash: cashBy[cur] ?? 0, cost: nil, pnl: nil, dayChange: nil, positions: priced.count)335            if !priced.isEmpty, priced.allSatisfy({ $0.cost != nil }) { let c = priced.compactMap(\.cost).reduce(0, +); g.cost = c; g.pnl = mv - c }336            if !priced.isEmpty, priced.allSatisfy({ $0.dayChange != nil }) { g.dayChange = priced.compactMap(\.dayChange).reduce(0, +) }337            return g338        }339        let base = baseCurrency.uppercased()340        groups.sort { a, b in a.currency == base ? b.currency != base : (b.currency == base ? false : abs(a.total) > abs(b.total)) }341        self.groups = groups342    }343}344345// MARK: - Batching and proposals346347public enum Batching {348    /// Unique, order-preserving chunks of at most `size` elements (`/api/v2/data/quotes` takes at most 60 symbols).349    public static func chunks(_ items: [String], size: Int) -> [[String]] {350        var seen = Set<String>()351        let unique = items.filter { !$0.isEmpty && seen.insert($0).inserted }352        guard size > 0 else { return unique.isEmpty ? [] : [unique] }353        return stride(from: 0, to: unique.count, by: size).map { Array(unique[$0..<min(unique.count, $0 + size)]) }354    }355}356357public enum RebalanceMath {358    /// Quantities after the suggested trades (signed units: negative = sell). A holding sold down to nothing359    /// (|quantity| below `epsilon`) disappears; a symbol not held yet is appended. The order of the holdings is kept.360    public static func apply(units: [String: Double], to holdings: [(symbol: String, quantity: Double)], epsilon: Double = 1e-9) -> [(symbol: String, quantity: Double)] {361        var out: [(symbol: String, quantity: Double)] = []362        var left = units363        for h in holdings {364            let q = h.quantity + (left.removeValue(forKey: h.symbol) ?? 0)365            if abs(q) > epsilon { out.append((h.symbol, q)) }366        }367        for (s, u) in left.sorted(by: { $0.key < $1.key }) where abs(u) > epsilon { out.append((s, u)) }368        return out369    }370}371
Files main
Menu

Theme