Commit `2d92459d2a`

2d92459d2a2588994fff5b0a415e8775cfb6aed8

parent: 578d60d689

Verified · cmc

cmc <hello@cleberg.net> · 2026-10-08 03:57 UTC

Backlinks include links before a file's first heading

DocumentModel and FileRecord keep the file's own links; the index stores them in a new file_links table (migration v2 reindexes every file). Their source is the file, a HeadingLocation with ordinal -1 titled by the file name, shown at the file's start.

Layout: unified · split

Sources/OrgApp/DocumentSession.swift +2

         let offset: Int
         if !isDirty, hash == location.contentHash {
             offset = location.start
+        } else if location.ordinal == HeadingLocation.fileOrdinal {
+            offset = 0
         } else if location.ordinal < outline.count, outline[location.ordinal].title == location.title {
             offset = outline[location.ordinal].start
         } else if let entry = outline.first(where: { $0.title == location.title }) {

Sources/OrgCore/Semantic/DocumentModel.swift +3 −1

     public private(set) var fileProperties: [Property] = []
     public private(set) var tables: [TableModel] = []
     public private(set) var srcBlocks: [SrcBlockInfo] = []
+    /// Link targets before the first heading, as `HeadingInfo.links` has a heading's.
+    public private(set) var links: [String] = []
     /// Always inherited, whatever the inheritance setting.
     static let alwaysInherited: Set<String> = ["CATEGORY", "ARCHIVE", "COLUMNS", "LOGGING"]
             case .timestamp:
                 if let heading, let stamp = Timestamp.parse(child.text) { headings[heading].timestamps.append(stamp) }
             case .link:
-                if let heading { headings[heading].links.append(linkTarget(child)) }
+                if let heading { headings[heading].links.append(linkTarget(child)) } else { links.append(linkTarget(child)) }
             case .keyword:
                 fileKeyword(child)
             case .table:

Sources/OrgIndex/FileRecord.swift +14 −8

     public let hash: String
     public let settingsVersion: Int
     public let headings: [HeadingRecord]
+    /// Links before the first heading, the file's own.
+    public let links: [LinkRow]
     public static func hash(_ bytes: [UInt8]) -> String {
         SHA256.hash(data: Data(bytes)).map { String(format: "%02x", $0) }.joined()
         var resolved = settings
         resolved.org = settings.org.resolvingSetupFiles(in: source.text, path: path, read: OrgSettings.readFile)
         self.settingsVersion = Self.settingsVersion(settings, text: source.text, setupKeywords: resolved.org.setupKeywords)
-        headings = kind == .conflict ? [] : Self.headings(source.text, settings: resolved)
+        (headings, links) = kind == .conflict ? ([], []) : Self.rows(source.text, settings: resolved)
     }
     /// The settings version a file's rows are built under: the index's, with the keywords of
         self.hash = Self.unreadHash(size: size, mtime: mtime)
         self.settingsVersion = settings.version
         headings = []
+        links = []
     }
     public static func unreadHash(size: Int, mtime: Double) -> String { "unread:\(size):\(mtime)" }
-    static func headings(_ text: String, settings: IndexSettings) -> [HeadingRecord] {
+    static func rows(_ text: String, settings: IndexSettings) -> (headings: [HeadingRecord], links: [LinkRow]) {
         let model = DocumentModel(tree: OrgParser.parse(text, defaults: settings.org), settings: settings.semantic)
         let utf16 = text.utf16
         func slice(_ range: Range<Int>) -> String {
             if let parent = heading.parent, firstChild[parent] == nil { firstChild[parent] = index }
         }
-        return model.headings.enumerated().map { index, heading in
+        let headings = model.headings.enumerated().map { index, heading in
             let bodyEnd = firstChild[index].map { model.headings[$0].sectionRange.lowerBound } ?? heading.sectionRange.upperBound
             let tags = model.tags(of: index)
             return HeadingRecord(
                 clocks: heading.clocks.map {
                     ClockRow(start: format($0.start), end: $0.end.map(format), minutes: $0.minutes)
                 },
-                links: heading.links.map { target in
+                links: heading.links.map(linkRow)
-                    let scheme = target.prefix { $0 != ":" }
-                    let isScheme = scheme.count < target.count && !scheme.isEmpty && scheme.allSatisfy { $0.isLetter || $0 == "-" }
-                    return LinkRow(type: isScheme ? scheme.lowercased() : "fuzzy", target: target)
-                }
             )
         }
+        return (headings, model.links.map(linkRow))
+    }
+    static func linkRow(_ target: String) -> LinkRow {
+        let scheme = target.prefix { $0 != ":" }
+        let isScheme = scheme.count < target.count && !scheme.isEmpty && scheme.allSatisfy { $0.isLetter || $0 == "-" }
+        return LinkRow(type: isScheme ? scheme.lowercased() : "fuzzy", target: target)
     }
     /// Own properties, plus inherited ones for keys that inherit.

Sources/OrgIndex/IndexStore.swift +36 −4

 public struct HeadingLocation: Sendable, Hashable {
     public let path: String
+    /// `fileOrdinal` for the file itself, before its first heading.
     public let ordinal: Int
     public let title: String
     public let start: Int
         self.start = start
         self.contentHash = contentHash
     }
+    public static let fileOrdinal = -1
+    /// The file before its first heading, titled by its name.
+    public static func file(_ path: String, contentHash: String) -> HeadingLocation {
+        HeadingLocation(path: path, ordinal: fileOrdinal, title: (path as NSString).lastPathComponent, start: 0, contentHash: contentHash)
+    }
 }
 /// One reconciliation's worth of changes, applied in a single transaction.
                 END;
                 """)
         }
+        migrator.registerMigration("v2") { db in
+            // Links before a file's first heading; files are read again to fill it.
+            try db.execute(sql: """
+                CREATE TABLE file_links (
+                    file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+                    type TEXT NOT NULL,
+                    target TEXT NOT NULL
+                );
+                CREATE INDEX file_links_file ON file_links(file_id);
+                UPDATE files SET settings_version = -1;
+                """)
+        }
         return migrator
     }
                         record.settingsVersion, Date().timeIntervalSince1970]
         )
         let fileID = db.lastInsertedRowID
+        for link in record.links {
+            try db.execute(sql: "INSERT INTO file_links VALUES (?, ?, ?)", arguments: [fileID, link.type, link.target])
+        }
         for heading in record.headings {
             try db.execute(
                 sql: """
         return indexed.filter { overlay[$0.path] == nil } + live
     }
-    /// Every link and the heading it's in, unsaved buffers' in place of their files'.
+    /// Every link and the heading it's in, or the file for links before its first heading,
+    /// unsaved buffers' in place of their files'.
     public func links(overlay: [String: FileRecord] = [:]) throws -> [(source: HeadingLocation, target: String)] {
         let indexed = try database.read { db in
             try Row.fetchAll(
                 db,
                 sql: """
+                    SELECT f.path, f.hash, -1 AS ordinal, '' AS title, 0 AS start_offset, l.target
+                    FROM file_links l JOIN files f ON f.id = l.file_id WHERE f.kind = 'org'
+                    UNION ALL
                     SELECT f.path, f.hash, h.ordinal, h.title, h.start_offset, l.target
                     FROM links l JOIN headings h ON h.id = l.heading_id JOIN files f ON f.id = h.file_id
-                    WHERE f.kind = 'org' ORDER BY f.path, h.ordinal
+                    WHERE f.kind = 'org' ORDER BY 1, 3
                     """
-            ).map { (source: location($0), target: $0["target"] as String) }
+            ).map { row in
+                let location = location(row)
+                return (source: location.ordinal == HeadingLocation.fileOrdinal ? .file(location.path, contentHash: location.contentHash) : location,
+                        target: row["target"] as String)
+            }
         }
         let live = overlay.values.sorted { $0.path < $1.path }.flatMap { record in
-            record.headings.flatMap { heading in heading.links.map { (source: location(record, heading), target: $0.target) } }
+            record.links.map { (source: HeadingLocation.file(record.path, contentHash: record.hash), target: $0.target) }
+                + record.headings.flatMap { heading in heading.links.map { (source: location(record, heading), target: $0.target) } }
         }
         return indexed.filter { overlay[$0.source.path] == nil } + live
     }

Tests/OrgAppTests/AppTests.swift +11 −3

         let notes = try Folder()
         try notes.write("a.org", "* Sink\n:PROPERTIES:\n:ID: s-1\n:CUSTOM_ID: sink\n:END:\nsee [[*Taps]]\n* Taps\n")
         try notes.write("b.org", "* Plumbing\n[[id:s-1][the sink]] and [[file:a.org]]\n* Other\n[[file:a.org::#sink]] [[https://x.org]]\n")
+        // Links before the first heading come from the file itself.
+        try notes.write("c.org", "#+TITLE: C\nAbout [[file:a.org::*Sink]] and [[file:a.org]].\n* Later\n")
         let model = try WorkspaceModel(directory: nil)
         try await model.addRoot(notes.url)
         let a = try #require(model.files.first { $0.path.hasSuffix("/a.org") }).path
+        let c = try #require(model.files.first { $0.path.hasSuffix("/c.org") }).path
         let sink = Backlinks.Target(path: a, title: "Sink", id: "s-1", customID: "sink")
-        #expect(model.backlinks(to: sink).map(\.title) == ["Plumbing", "Other"])
+        #expect(model.backlinks(to: sink).map(\.title) == ["Plumbing", "Other", "c.org"])
-        #expect(model.backlinks(to: Backlinks.Target(path: a)).map(\.title) == ["Plumbing"])
+        #expect(model.backlinks(to: Backlinks.Target(path: a)).map(\.title) == ["Plumbing", "c.org"])
         #expect(model.backlinks(to: Backlinks.Target(path: a, title: "Taps")).map(\.title) == ["Sink"])
-        #expect(model.backlinks(to: sink, excluding: 0).map(\.title) == ["Plumbing", "Other"])
+        #expect(model.backlinks(to: sink, excluding: 0).map(\.title) == ["Plumbing", "Other", "c.org"])
+        let fromC = try #require(model.backlinks(to: sink).last)
+        #expect(fromC == .file(c, contentHash: fromC.contentHash))
+        let session = DocumentSession(recovery: FileRecoveryStore(directory: notes.url.appendingPathComponent(".r")))
+        session.show(fromC)
+        #expect(session.path == c && session.revealRequest?.offset == 0)
     }
     @Test func createRenameAndTrashFiles() async throws {

Tests/OrgIndexTests/FileRecordTests.swift +6

         #expect(child.properties.contains(PropertyRow(key: "OWNER", value: "team", inherited: true)))
     }
+    @Test func linksBeforeTheFirstHeadingBelongToTheFile() {
+        let file = record("/notes/a.org", "#+TITLE: A\nSee [[file:b.org]] and https://x.org.\n* H\n[[id:h]]\n")
+        #expect(file.links == [LinkRow(type: "file", target: "file:b.org"), LinkRow(type: "https", target: "https://x.org")])
+        #expect(file.headings[0].links == [LinkRow(type: "id", target: "id:h")])
+    }
     @Test func archiveTag() {
         let headings = record("/notes/a.org", "* a :ARCHIVE:\n** b\n* c\n").headings
         #expect(headings.map(\.archived) == [true, true, false])

Commit 2d92459d2a

Commit `2d92459d2a`