Reuse RSS/Podcast feeds if possible (#16)

This change makes Publish reuse any previously generated RSS and podcast
feeds in case no new items have been added, no existing ones have been
modified, and the configuration for generating the given feed hasn’t
changed.

This is made possible by series of other changes:

- `PodcastFeedConfiguration` is no longer a subclass of its RSS counterpart,
  instead, both are separate structs that share a new `FeedConfiguration`
  protocol - in order to be able to enforce some degree of consistency.
- Both feed configuration types have been made `Equatable` and `Codable`
  in order to persist and compare them to previous configs.
- `PublishingContext` now has a `lastGenerationDate` API, which is used to
  compare the last modified item against when the website was last generated.
- `PublishingContext` now also enables any step to create cache files, which
  is used by `RSSFeedGenerator` and `PodcastFeedGenerator` to store caches of
  their previous configs + feeds.
- An error is now thrown if there are no runnable publishing steps, in order
  to be able to associate each `PublishingContext` with a current step name.
- Publish’s internal string normalization code is now available to all strings,
  rather than just tags, and used when creating cache files.
- Plot has been bumped to version `0.4.0`.

The main motivation for this change is to not cause each new publishing
process to mark all RSS and podcast feeds as changed, which makes it harder
to track actual changes using version control.

Author: JohnSundell

Package.resolved

@@ -16,7 +16,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/johnsundell/ink.git", from: "0.2.0"),
-        .package(url: "https://github.com/johnsundell/plot.git", from: "0.3.0"),
+        .package(url: "https://github.com/johnsundell/plot.git", from: "0.4.0"),
         .package(url: "https://github.com/johnsundell/files.git", from: "4.0.0"),
         .package(url: "https://github.com/johnsundell/codextended.git", from: "0.1.0"),
         .package(url: "https://github.com/johnsundell/shellout.git", from: "2.2.0"),

Package.swift

@@ -0,0 +1,21 @@
+/**
+*  Publish
+*  Copyright (c) John Sundell 2020
+*  MIT license, see LICENSE file for details
+*/
+
+import Foundation
+import Plot
+
+/// Protocol that acts as a shared API for configuring various feed
+/// generation steps, such as `generateRSSFeed` and `generatePodcastFeed`.
+public protocol FeedConfiguration: Codable, Equatable {
+    /// The path that the feed should be generated at.
+    var targetPath: Path { get }
+    /// The feed's TTL (or "Time to live") time interval.
+    var ttlInterval: TimeInterval { get }
+    /// The maximum number of items that the feed should contain.
+    var maximumItemCount: Int { get }
+    /// How the feed should be indented.
+    var indentation: Indentation.Kind? { get }
+}

Sources/Publish/API/FeedConfiguration.swift

@@ -7,7 +7,7 @@
 import Foundation
 
 /// Type used to describe the author of a podcast.
-public struct PodcastAuthor {
+public struct PodcastAuthor: Codable, Equatable {
     /// The author's full name.
     public var name: String
     /// The author's email address.

Sources/Publish/API/PodcastAuthor.swift

@@ -10,7 +10,11 @@ import Plot
 /// Configuration type used to customize how a podcast feed is generated when
 /// using the `generatePodcastFeed` step. To use a default implementation,
 /// use `PodcastFeedConfiguration.default`.
-public final class PodcastFeedConfiguration<Site: Website>: RSSFeedConfiguration {
+public struct PodcastFeedConfiguration<Site: Website>: FeedConfiguration {
+    public var targetPath: Path
+    public var ttlInterval: TimeInterval
+    public var maximumItemCount: Int
+    public var indentation: Indentation.Kind?
     /// The type of the podcast. See `PodcastType`.
     public var type: PodcastType
     /// A URL that points to the podcast's main image.
@@ -64,6 +68,10 @@ public final class PodcastFeedConfiguration<Site: Website>: RSSFeedConfiguration
         newFeedURL: URL? = nil,
         indentation: Indentation.Kind? = nil
     ) {
+        self.targetPath = targetPath
+        self.ttlInterval = ttlInterval
+        self.maximumItemCount = maximumItemCount
+        self.indentation = indentation
         self.type = type
         self.imageURL = imageURL
         self.copyrightText = copyrightText
@@ -74,10 +82,5 @@ public final class PodcastFeedConfiguration<Site: Website>: RSSFeedConfiguration
         self.subcategory = subcategory
         self.isExplicit = isExplicit
         self.newFeedURL = newFeedURL
-
-        super.init(targetPath: targetPath,
-                   ttlInterval: ttlInterval,
-                   maximumItemCount: maximumItemCount,
-                   indentation: indentation)
     }
 }

Sources/Publish/API/PodcastFeedConfiguration.swift

@@ -31,13 +31,19 @@ public struct PublishingContext<Site: Website> {
     public private(set) var pages = [Path : Page]()
     /// A set containing all tags that are currently being used website-wide.
     public var allTags: Set<Tag> { tagCache.tags ?? gatherAllTags() }
+    /// Any date when the website was last generated.
+    public private(set) var lastGenerationDate: Date?
 
     private let folders: Folder.Group
     private var tagCache = TagCache()
+    private var stepName: String
 
-    internal init(site: Site, folders: Folder.Group) {
+    internal init(site: Site,
+                  folders: Folder.Group,
+                  firstStepName: String) {
         self.site = site
         self.folders = folders
+        self.stepName = firstStepName
 
         let dateFormatter = DateFormatter()
         dateFormatter.dateFormat = "yyyy-MM-dd HH:mm"
@@ -160,6 +166,18 @@ public extension PublishingContext {
         }
     }
 
+    /// Return either an existing or newly created cache file for the
+    /// current publishing step. Cache files are scoped to the step
+    /// that they're created within, and can't be shared among steps.
+    /// Cache files aren't deleted in between publishing processes.
+    /// - parameter name: The name of the cache file to return.
+    /// - throws: An error in case a new file couldn't be created.
+    func cacheFile(named name: String) throws -> File {
+        let folderName = stepName.normalized()
+        let folder = try folders.caches.createSubfolderIfNeeded(withName: folderName)
+        return try folder.createFileIfNeeded(withName: name.normalized())
+    }
+
     /// Return all items within this website, sorted by a given key path.
     /// - parameter sortingKeyPath: The key path to sort the items by.
     /// - parameter order: The order to use when sorting the items.
@@ -249,6 +267,14 @@ public extension PublishingContext {
 }
 
 internal extension PublishingContext {
+    mutating func generationWillBegin() {
+        try? updateLastGenerationDate()
+    }
+
+    mutating func prepareForStep(named name: String) {
+        stepName = name
+    }
+
     func makeMarkdownContentFactory() -> MarkdownContentFactory<Site> {
         MarkdownContentFactory(
             parser: markdownParser,
@@ -280,6 +306,24 @@ private extension PublishingContext {
         var tags: Set<Tag>?
     }
 
+    mutating func updateLastGenerationDate() throws {
+        let fileName = "lastGenerationDate"
+        let newString = String(Date().timeIntervalSince1970)
+
+        if let file = try? folders.internal.file(named: fileName) {
+            let oldInterval = try TimeInterval(file.readAsString())
+
+            lastGenerationDate = oldInterval.map {
+                Date(timeIntervalSince1970: $0)
+            }
+
+            try file.write(newString)
+        } else {
+            let file = try folders.internal.createFile(named: fileName)
+            try file.write(newString)
+        }
+    }
+
     func gatherAllTags() -> Set<Tag> {
         var tags = Set<Tag>()
 

Sources/Publish/API/PublishingContext.swift

@@ -331,17 +331,21 @@ public extension PublishingStep {
     /// - parameter includedSectionIDs: The IDs of the sections which items
     ///   to include when generating the feed.
     /// - parameter config: The configuration to use when generating the feed.
+    /// - parameter date: The date that should act as the build and publishing
+    ///   date for the generated feed (default: the current date).
     static func generateRSSFeed(
         including includedSectionIDs: Set<Site.SectionID>,
-        config: RSSFeedConfiguration = .default
+        config: RSSFeedConfiguration = .default,
+        date: Date = Date()
     ) -> Self {
         guard !includedSectionIDs.isEmpty else { return .empty }
 
         return step(named: "Generate RSS feed") { context in
             let generator = RSSFeedGenerator(
                 includedSectionIDs: includedSectionIDs,
                 config: config,
-                context: context
+                context: context,
+                date: date
             )
 
             try generator.generate()
@@ -373,15 +377,19 @@ public extension PublishingStep where Site.ItemMetadata: PodcastCompatibleWebsit
     /// and `audio` metadata, or an error will be thrown.
     /// - parameter section: The section to generate a podcast feed for.
     /// - parameter config: The configuration to use when generating the feed.
+    /// - parameter date: The date that should act as the build and publishing
+    ///   date for the generated feed (default: the current date).
     static func generatePodcastFeed(
         for section: Site.SectionID,
-        config: PodcastFeedConfiguration<Site>
+        config: PodcastFeedConfiguration<Site>,
+        date: Date = Date()
     ) -> Self {
         step(named: "Generate podcast feed") { context in
             let generator = PodcastFeedGenerator(
                 sectionID: section,
                 config: config,
-                context: context
+                context: context,
+                date: date
             )
 
             try generator.generate()
@@ -407,7 +415,7 @@ public extension PublishingStep {
 // MARK: - Implementation details
 
 internal extension PublishingStep {
-    enum Kind {
+    enum Kind: String {
         case system
         case generation
         case deployment

Sources/Publish/API/PublishingStep.swift

@@ -10,14 +10,10 @@ import Plot
 /// Configuration type used to customize how an RSS feed is generated
 /// when using the `generateRSSFeed` step. To use a default implementation,
 /// use `RSSFeedConfiguration.default`.
-public class RSSFeedConfiguration {
-    /// The path that the feed should be generated at.
+public struct RSSFeedConfiguration: FeedConfiguration {
     public var targetPath: Path
-    /// The feed's TTL (or "Time to live") time interval.
     public var ttlInterval: TimeInterval
-    /// The maximum number of items that the feed should contain.
     public var maximumItemCount: Int
-    /// How the feed should be indented.
     public var indentation: Indentation.Kind?
 
     /// Initialize a new configuration instance.

Sources/Publish/API/RSSFeedConfiguration.swift

@@ -20,16 +20,6 @@ public extension Tag {
     /// Return a normalized string representation of this tag, which can
     /// be used to form URLs or identifiers.
     func normalizedString() -> String {
-        String(string.lowercased().compactMap { character in
-            if character.isWhitespace {
-                return "-"
-            }
-
-            if character.isLetter || character.isNumber {
-                return character
-            }
-
-            return nil
-        })
+        string.normalized()
     }
 }

Sources/Publish/API/Tag.swift

@@ -11,5 +11,6 @@ internal extension Folder {
         let root: Folder
         let output: Folder
         let `internal`: Folder
+        let caches: Folder
     }
 }