woods 1.6.1 → 2.0.0.beta2

data/lib/woods/notion/mappers/column_mapper.rb

@@ -12,34 +12,63 @@ module Woods
       #
       # @example
       #   mapper = ColumnMapper.new
-      #   properties = mapper.map(column, model_identifier: "User", validations: [...], parent_page_id: "page-123")
+      #   properties = mapper.map(column, model_identifier: "User", validations: [...], parent_page_ids: ["page-123"])
       #
       class ColumnMapper
         include Shared
 
         # Map a single column to Notion Columns page properties.
         #
+        # The page title is qualified as "<table>.<column>" (e.g. "users.id")
+        # when a table name is given. Every Rails model shares id/created_at/
+        # updated_at, and the Columns database is upserted by title — a bare
+        # column-name title made every model overwrite every other model's
+        # shared-name column pages (#149). The qualifier must come from
+        # {ModelMapper.table_name_for} so it agrees with the Data Models page
+        # the Table relation points at.
+        #
+        # A physical table can be owned by several models (STI, or a shared
+        # +self.table_name=+), and the column page is one page per physical
+        # column — so the Table relation lists *every* owner's Data Models
+        # page. A single-owner relation made the two models fight over the
+        # page's parent claim on every run (EXP-1); Notion relations are lists,
+        # so naming them all is both accurate and stable.
+        #
         # @param column [Hash] Column hash from metadata["columns"] (name, type, null, default)
         # @param model_identifier [String] Parent model name (for context)
+        # @param table_name [String, nil] Owning table name used to qualify the page title
         # @param validations [Array<Hash>] Model-level validations to match against this column
-        # @param parent_page_id [String, nil] Notion page ID of the Data Models parent page
+        # @param parent_page_ids [Array<String>] Notion page IDs of the owning
+        #   Data Models pages, in a caller-fixed (deterministic) order
         # @return [Hash] Notion page properties hash
-        def map(column, model_identifier: nil, validations: [], parent_page_id: nil) # rubocop:disable Lint/UnusedMethodArgument
+        def map(column, model_identifier: nil, table_name: nil, validations: [], parent_page_ids: []) # rubocop:disable Lint/UnusedMethodArgument
           properties = {
-            'Column Name' => { title: [{ text: { content: column['name'] } }] },
+            'Column Name' => { title: [{ text: { content: qualified_title(column['name'], table_name) } }] },
             'Data Type' => { select: { name: column['type'] } },
             'Nullable' => { checkbox: column['null'] == true },
             'Default Value' => rich_text_property(column['default'].to_s),
             'Validation Rules' => rich_text_property(format_validation_rules(column['name'], validations))
           }
 
-          properties['Table'] = { relation: [{ id: parent_page_id }] } if parent_page_id
+          related = Array(parent_page_ids).compact
+          properties['Table'] = { relation: related.map { |id| { id: id } } } if related.any?
 
           properties
         end
 
         private
 
+        # Build the column page title, qualified by table when known.
+        #
+        # @param column_name [String]
+        # @param table_name [String, nil]
+        # @return [String] "<table>.<column>", or the bare name without a table
+        def qualified_title(column_name, table_name)
+          return column_name.to_s if table_name.nil? || table_name.to_s.empty?
+
+          "#{table_name}.#{column_name}"
+        end
+
         # Find and format validations matching this column name.
         #
         # @param column_name [String]

data/lib/woods/notion/mappers/migration_mapper.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'time'
+
 module Woods
   module Notion
     module Mappers
@@ -13,25 +15,47 @@ module Woods
       #   # => { "users" => "2026-02-20T10:00:00Z", "posts" => "2026-01-15T09:00:00Z" }
       #
       class MigrationMapper
-        # Compute the latest migration date for each affected table.
+        # A migration filename stamp: 20260220100000.
+        VERSION_STAMP = /\A(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\z/
+
+        # Compute the latest schema-change date for each affected table.
+        #
+        # The date is the **migration's own** version stamp, not the unit's
+        # +extracted_at+ (EXP-3). `extracted_at` records when Woods ran, so a
+        # full extraction re-stamped every unit and made every table read
+        # "changed today" — and rewrote every Data Models page to say so.
+        # Units with no parseable version fall back to `extracted_at`.
         #
         # @param migration_units [Array<Hash>] Parsed migration ExtractedUnit JSONs
-        # @return [Hash<String, String>] Table name to latest extracted_at timestamp
+        # @return [Hash<String, String>] Table name to latest ISO8601 timestamp
         def latest_changes(migration_units)
           migration_units.each_with_object({}) do |unit, changes|
-            extracted_at = unit['extracted_at']
-            next unless extracted_at
+            metadata = unit['metadata'] || {}
+            changed_at = version_timestamp(metadata['migration_version']) || unit['extracted_at']
+            next unless changed_at
 
-            tables = (unit['metadata'] || {})['tables_affected'] || []
-            tables.each { |table| update_latest(changes, table, extracted_at) }
+            tables = metadata['tables_affected'] || []
+            tables.each { |table| update_latest(changes, table, changed_at) }
           end
         end
 
         private
 
+        # @param version [String, nil] a `%Y%m%d%H%M%S` migration stamp
+        # @return [String, nil] ISO8601 UTC, or nil when absent/unparseable
+        def version_timestamp(version)
+          match = VERSION_STAMP.match(version.to_s)
+          return nil unless match
+
+          Time.utc(*match.captures.map(&:to_i)).iso8601
+        rescue ArgumentError
+          # A well-shaped stamp naming an impossible date (month 13).
+          nil
+        end
+
         # @return [void]
-        def update_latest(changes, table, extracted_at)
-          changes[table] = extracted_at if changes[table].nil? || extracted_at > changes[table]
+        def update_latest(changes, table, changed_at)
+          changes[table] = changed_at if changes[table].nil? || changed_at > changes[table]
         end
       end
     end

data/lib/woods/notion/mappers/model_mapper.rb

@@ -18,6 +18,24 @@ module Woods
       class ModelMapper # rubocop:disable Metrics/ClassLength
         include Shared
 
+        # Derive the table name for a model unit — the exact value the Data
+        # Models page title is built from. Shared with the Columns sync so the
+        # column title qualifier ("<table>.<column>") and the Table relation
+        # always agree on which table a column belongs to (#149).
+        #
+        # Falls back to a naive tableized identifier when extraction produced
+        # no table_name (close enough to ActiveRecord convention for a title).
+        #
+        # @param unit_data [Hash] Parsed model ExtractedUnit JSON
+        # @return [String]
+        def self.table_name_for(unit_data)
+          metadata = unit_data['metadata'] || {}
+          return metadata['table_name'] if metadata['table_name']
+
+          identifier = unit_data['identifier'] || ''
+          "#{identifier.split('::').last.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase}s"
+        end
+
         # Map a model unit to Notion Data Models page properties.
         #
         # @param unit_data [Hash] Parsed model ExtractedUnit JSON
@@ -35,7 +53,7 @@ module Woods
         # @return [Hash] Text-based Notion properties
         def build_text_properties(unit_data, metadata)
           {
-            'Table Name' => title_property(table_name(unit_data, metadata)),
+            'Table Name' => title_property(table_name(unit_data)),
             'Model Name' => rich_text_property(unit_data['identifier']),
             'Description' => rich_text_property(extract_description(unit_data['source_code'])),
             'Associations' => rich_text_property(format_associations(metadata['associations'])),
@@ -54,11 +72,8 @@ module Woods
         end
 
         # @return [String]
-        def table_name(unit_data, metadata)
-          return metadata['table_name'] if metadata['table_name']
-
-          identifier = unit_data['identifier'] || ''
-          "#{identifier.split('::').last.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase}s"
+        def table_name(unit_data)
+          self.class.table_name_for(unit_data)
         end
 
         # @return [Integer]

data/lib/woods/notion/mappers/shared.rb

@@ -5,16 +5,58 @@ module Woods
     module Mappers
       # Shared helpers for Notion mapper classes.
       module Shared
+        # Notion's rich_text content limit, counted in **UTF-16 code units**
+        # — not Ruby characters. A character outside the BMP (an emoji, most
+        # CJK extension blocks) costs two units, so a char-count check let
+        # payloads up to twice the limit through and the API rejected them
+        # with a 400 on every run (EXP-2).
         MAX_RICH_TEXT_LENGTH = 2000
 
+        # Marks a truncated value; costs 3 UTF-16 units.
+        TRUNCATION_SUFFIX = '...'
+
         # Build a Notion rich_text property, truncating to API limits.
         #
         # @param text [String]
         # @return [Hash]
         def rich_text_property(text)
-          content = text.to_s
-          content = "#{content[0...1997]}..." if content.length > MAX_RICH_TEXT_LENGTH
-          { rich_text: [{ text: { content: content } }] }
+          { rich_text: [{ text: { content: truncate_to_utf16_limit(text.to_s) } }] }
+        end
+
+        private
+
+        # Truncate to {MAX_RICH_TEXT_LENGTH} UTF-16 code units, reserving room
+        # for {TRUNCATION_SUFFIX}.
+        #
+        # Walks whole characters, so a surrogate pair is never split — a lone
+        # surrogate is not valid UTF-8 and would fail the request differently.
+        #
+        # @param content [String]
+        # @return [String] the input unchanged when it already fits
+        def truncate_to_utf16_limit(content)
+          # UTF-8 never spends fewer bytes than UTF-16 spends units (1/2/3
+          # bytes for one unit, 4 for two), so this settles the common case
+          # without walking the string.
+          return content if content.bytesize <= MAX_RICH_TEXT_LENGTH
+          return content if utf16_length(content) <= MAX_RICH_TEXT_LENGTH
+
+          budget = MAX_RICH_TEXT_LENGTH - TRUNCATION_SUFFIX.length
+          used = 0
+          kept = +''
+          content.each_char do |char|
+            cost = char.ord >= 0x10000 ? 2 : 1
+            break if used + cost > budget
+
+            kept << char
+            used += cost
+          end
+          kept << TRUNCATION_SUFFIX
+        end
+
+        # @param content [String]
+        # @return [Integer] length in UTF-16 code units
+        def utf16_length(content)
+          content.each_char.sum { |char| char.ord >= 0x10000 ? 2 : 1 }
         end
       end
     end

data/lib/woods/notion/sync_manifest.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+
+require_relative '../atomic_file'
+
+module Woods
+  module Notion
+    # Tracks what was last written to the Notion databases so a sync can
+    # skip unchanged pages entirely (zero API calls) and PATCH changed ones
+    # by cached page id (one call, no find-by-title query). Modeled on
+    # {Woods::Unblocked::SyncManifest} (#207 / B-095).
+    #
+    # Entries are grouped by scope — one scope per Notion database
+    # ("data_models", "columns") — and keyed by the page's logical identity:
+    # the qualified title from #149 ("users.id" for columns, the table name
+    # or "<table> (<Model>)" for data models). Each entry records the Notion
+    # page_id plus a deterministic content hash of the mapped properties.
+    #
+    # The manifest is a local cache, never the source of truth: a missing,
+    # corrupt, or unreadable file degrades to "everything is new" — a
+    # correct (if expensive) full title-lookup sync that rebuilds it. Reads
+    # and writes both go through {Woods::AtomicFile} from day one — a bare
+    # +File.read+ tags bytes with the process's default external encoding
+    # (US-ASCII under +LANG=C+), which broke the Unblocked manifest's
+    # degrade contract on non-ASCII content (B-077 / #189).
+    #
+    # A stored scope is discarded when its recorded database id no longer
+    # matches the configured one (the analog of Unblocked's collection
+    # guard): cached page_ids point into the *old* database, and a PATCH by
+    # page id would silently write pages the configured database never sees.
+    #
+    # @example
+    #   manifest = SyncManifest.new(path: "tmp/woods/notion_sync_manifest.json",
+    #                               database_ids: { data_models: "db-uuid" })
+    #   hash = SyncManifest.content_hash(properties)
+    #   manifest.unchanged?("data_models", "users", hash) # => false on first run
+    #   manifest.record(scope: "data_models", key: "users", hash: hash, page_id: "page-1")
+    #   manifest.save
+    #
+    class SyncManifest
+      VERSION = 1
+
+      # Deterministic fingerprint of a mapped Notion properties payload.
+      #
+      # Hash keys are sorted recursively (after +to_s+, so a symbol-keyed and
+      # a string-keyed payload that serialize identically hash identically),
+      # so the digest never depends on insertion order. Array order is
+      # preserved — it is meaningful in Notion payloads (rich text runs,
+      # relation lists).
+      #
+      # @param properties [Hash] Mapper output (Notion page properties)
+      # @return [String] SHA-256 hex digest
+      def self.content_hash(properties)
+        Digest::SHA256.hexdigest(JSON.generate(canonicalize(properties)))
+      end
+
+      # Recursively sort hash keys so serialization is order-independent.
+      #
+      # @api private
+      # @param value [Object]
+      # @return [Object]
+      def self.canonicalize(value)
+        case value
+        when Hash
+          value.map { |k, v| [k.to_s, canonicalize(v)] }.sort_by(&:first).to_h
+        when Array
+          value.map { |element| canonicalize(element) }
+        else
+          value
+        end
+      end
+
+      # @param path [String] JSON file path for the manifest
+      # @param database_ids [Hash{Symbol,String=>String}, nil] Scope name =>
+      #   Notion database UUID currently configured. A stored scope whose
+      #   recorded database id differs is discarded on load.
+      def initialize(path:, database_ids:)
+        @path = path
+        @database_ids = normalize_database_ids(database_ids)
+        @pages = load
+      end
+
+      # @return [Boolean] true when no pages are recorded in any scope
+      def empty?
+        @pages.values.all?(&:empty?)
+      end
+
+      # @return [Integer] number of recorded pages across all scopes
+      def size
+        @pages.values.sum(&:size)
+      end
+
+      # @param scope [String] Scope name (e.g. "data_models")
+      # @param key [String] Logical page key (qualified title)
+      # @param hash [String] Content hash of the properties we would write now
+      # @return [Boolean] true when the recorded hash matches *and* a page_id
+      #   is on record (without one, a skip would leave dependent pages —
+      #   column Table relations — unable to reference the page)
+      def unchanged?(scope, key, hash)
+        entry = @pages.dig(scope, key)
+        !entry.nil? && entry['hash'] == hash && !entry['page_id'].nil?
+      end
+
+      # @param scope [String] Scope name
+      # @param key [String] Logical page key
+      # @return [String, nil] Stored Notion page_id, if known
+      def page_id_for(scope, key)
+        @pages.dig(scope, key, 'page_id')
+      end
+
+      # Record (or update) what we wrote for a page.
+      #
+      # @param scope [String] Scope name
+      # @param key [String] Logical page key (qualified title)
+      # @param hash [String] Content hash written
+      # @param page_id [String] Notion page UUID
+      # @return [void]
+      def record(scope:, key:, hash:, page_id:)
+        (@pages[scope] ||= {})[key] = { 'hash' => hash, 'page_id' => page_id }
+      end
+
+      # Drop one key from a scope (e.g. after a cached page turned out to be
+      # deleted in Notion, so the next attempt goes through find-by-title).
+      #
+      # @param scope [String] Scope name
+      # @param key [String] Logical page key
+      # @return [void]
+      def forget(scope, key)
+        @pages[scope]&.delete(key)
+      end
+
+      # Drop every key in +scope+ absent from +current_keys+ — pages whose
+      # logical identity vanished from the sync set. Only the manifest entry
+      # is dropped: the Notion page itself is deliberately left alone (there
+      # is no deletion path), pruning just keeps the manifest from growing
+      # forever. A key that later reappears goes through the find-by-title
+      # path and re-adopts the surviving page.
+      #
+      # @param scope [String] Scope name
+      # @param current_keys [Array<String>, Set] Keys that still exist this run
+      # @return [Array<String>] the pruned keys
+      def prune(scope, current_keys)
+        scoped = @pages[scope]
+        return [] unless scoped
+
+        stale = scoped.keys - current_keys.to_a
+        stale.each { |key| scoped.delete(key) }
+        stale
+      end
+
+      # Persist the manifest crash-safely ({Woods::AtomicFile} — temp file,
+      # fsync, rename) so an interrupted write never leaves a torn file.
+      #
+      # @return [void]
+      def save
+        payload = JSON.generate(
+          'version' => VERSION,
+          'databases' => @database_ids,
+          'pages' => @pages
+        )
+        AtomicFile.write(@path, payload)
+      end
+
+      private
+
+      # @param database_ids [Hash, nil]
+      # @return [Hash{String=>String}] string keys/values, nil values dropped
+      def normalize_database_ids(database_ids)
+        (database_ids || {}).each_with_object({}) do |(scope, id), normalized|
+          normalized[scope.to_s] = id.to_s unless id.nil?
+        end
+      end
+
+      # Load the persisted pages, discarding data from a different schema
+      # version or an unparseable/unreadable file, and discarding any scope
+      # recorded against a different database id. Every discard warns to
+      # stderr — the consequence (a full title-lookup re-check) is expensive
+      # enough that operators need to know why it happened.
+      #
+      # {Woods::AtomicFile.read}, not +File.read+ — see the class docs and
+      # B-077. Read failures (e.g. +Errno::EACCES+) take the same discard
+      # path: the manifest is a cache, and "everything is new" is always a
+      # correct answer.
+      #
+      # @return [Hash{String=>Hash}] scope => { key => { 'hash' =>, 'page_id' => } }
+      def load
+        return {} unless File.exist?(@path)
+
+        parsed = JSON.parse(AtomicFile.read(@path))
+        return discard('not a JSON object') unless parsed.is_a?(Hash)
+        return discard("schema version #{parsed['version'].inspect}, expected #{VERSION}") unless
+          parsed['version'] == VERSION
+
+        select_current_scopes(parsed)
+      rescue JSON::ParserError
+        discard('unparseable JSON')
+      rescue EncodingError, SystemCallError => e
+        discard("unreadable file: #{e.class}: #{e.message}")
+      end
+
+      # Keep only scopes whose recorded database id matches the configured
+      # one — cached page_ids from a different database must not be PATCHed.
+      #
+      # @param parsed [Hash] the persisted manifest document
+      # @return [Hash{String=>Hash}]
+      def select_current_scopes(parsed)
+        pages = parsed['pages']
+        return discard('malformed pages section') unless pages.is_a?(Hash)
+
+        stored_dbs = parsed['databases'].is_a?(Hash) ? parsed['databases'] : {}
+        pages.each_with_object({}) do |(scope, entries), kept|
+          scoped = load_scope(scope, entries, stored_dbs)
+          kept[scope] = scoped if scoped
+        end
+      end
+
+      # One stored scope: kept (minus individually torn entries) when it was
+      # recorded against the configured database id, dropped with a warning
+      # otherwise.
+      #
+      # @param scope [String] Scope name from the persisted manifest
+      # @param entries [Object] Persisted entries for the scope
+      # @param stored_dbs [Hash] Persisted scope => database id map
+      # @return [Hash, nil] entries to keep, or nil to drop the scope
+      def load_scope(scope, entries, stored_dbs)
+        return nil unless entries.is_a?(Hash)
+        return entries.select { |_key, entry| entry.is_a?(Hash) } if current_scope?(scope, stored_dbs)
+
+        warn_scope_discard(scope, stored_dbs[scope]) unless entries.empty?
+        nil
+      end
+
+      # @return [Boolean] true when the stored scope was recorded against the
+      #   database id configured now (and one is configured at all)
+      def current_scope?(scope, stored_dbs)
+        !@database_ids[scope].nil? && stored_dbs[scope] == @database_ids[scope]
+      end
+
+      # @param scope [String] Scope being discarded
+      # @param stored_id [String, nil] Database id the scope was recorded against
+      # @return [void]
+      def warn_scope_discard(scope, stored_id)
+        warn "WARNING: discarding notion sync manifest scope #{scope.inspect} at #{@path} (written for " \
+             "database #{stored_id.inspect}, expected #{@database_ids[scope].inspect}) — " \
+             'next sync re-checks those pages by title'
+      end
+
+      # @param reason [String] Why the persisted manifest is unusable
+      # @return [Hash] empty pages hash (degrades to a full title-lookup sync)
+      def discard(reason)
+        warn "WARNING: discarding notion sync manifest at #{@path} (#{reason}) — next sync re-checks every page"
+        {}
+      end
+    end
+  end
+end

data/lib/woods/obsidian/errors.rb

@@ -7,5 +7,11 @@ module Woods
     # Raised for recoverable Obsidian export failures (e.g. a missing extraction
     # output dir). Inherits Woods::Error so callers can rescue the gem's hierarchy.
     class ExportError < Woods::Error; end
+
+    # Raised when a computed write target resolves outside the vault root.
+    # The fail-closed counterpart to the dir_for/NameMapper sanitizers: those
+    # are expected to prevent this from ever firing, but a future regression
+    # in either one must refuse the write, not silently escape the vault.
+    class PathTraversalError < ExportError; end
   end
 end

data/lib/woods/obsidian/name_mapper.rb

@@ -32,9 +32,14 @@ module Woods
     class NameMapper
       MAX_FILENAME_BYTES = 255
       EXTENSION = '.md'
-      HASH_SUFFIX_BYTES = 9 # "-" + 8 hex chars
+      HASH_SUFFIX_HEX = 8 # hex chars per disambiguation step
       RESERVED_BASENAMES = %w[_index].freeze
 
+      # Basenames Windows refuses to create, with or without an extension.
+      # A Ruby class named +Aux+ produced "models/Aux.md", which breaks any
+      # vault synced through Windows Obsidian or OneDrive (EXP-9).
+      WINDOWS_RESERVED_BASENAMES = /\A(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])\z/i
+
       # @param id_to_dir [Hash{String=>String}] map of unit identifier -> type
       #   folder name (e.g. "User" => "models")
       def initialize(id_to_dir)
@@ -43,29 +48,12 @@ module Woods
         build(id_to_dir)
       end
 
-      # @return [Array<String>] exported identifiers, sorted
-      def ids
-        @map.keys
-      end
-
-      # @param id [String]
-      # @return [Boolean] whether this id has an emitted note
-      def known?(id)
-        @map.key?(id)
-      end
-
       # @param id [String]
       # @return [String, nil] vault-relative note path ("models/User.md")
       def path_for(id)
         @map[id]&.fetch(:path)
       end
 
-      # @param id [String]
-      # @return [String, nil] wikilink target with no extension ("models/User")
-      def target_for(id)
-        @map[id]&.fetch(:target)
-      end
-
       # @param id [String]
       # @return [String, nil] full wikilink ("[[models/User|User]]") or nil if unknown
       def wikilink(id)
@@ -93,18 +81,46 @@ module Woods
         end
       end
 
+      # Claim a free basename in this folder, case-insensitively.
+      #
+      # The hashed candidate used to be inserted without being re-checked, so
+      # a hash prefix that happened to equal an existing literal basename put
+      # two notes at one path — last writer wins, and one id silently vanished
+      # from the inverse map (EXP-9). Now the digest slice widens until the
+      # candidate is free.
       def assign_basename(id, used)
-        base = fit(sanitize(id), EXTENSION.bytesize)
-        if used.include?(base.downcase)
-          base = "#{fit(sanitize(id), EXTENSION.bytesize + HASH_SUFFIX_BYTES)}-#{Digest::SHA256.hexdigest(id)[0, 8]}"
+        candidate = fit(sanitize(id), EXTENSION.bytesize)
+        digest = Digest::SHA256.hexdigest(id)
+        attempt = 0
+
+        while used.include?(candidate.downcase)
+          attempt += 1
+          candidate = hashed_basename(id, hash_suffix(digest, attempt))
         end
-        used << base.downcase
-        base
+
+        used << candidate.downcase
+        candidate
+      end
+
+      # Widening slices of the digest (8, 16, ... 64 hex chars), then the whole
+      # digest plus a counter — so {#assign_basename} terminates even in the
+      # (unreachable, ids are unique) case that every slice is taken.
+      def hash_suffix(digest, attempt)
+        width = attempt * HASH_SUFFIX_HEX
+        return digest[0, width] if width <= digest.length
+
+        "#{digest}-#{attempt - (digest.length / HASH_SUFFIX_HEX)}"
+      end
+
+      def hashed_basename(id, suffix)
+        "#{fit(sanitize(id), EXTENSION.bytesize + 1 + suffix.bytesize)}-#{suffix}"
       end
 
       def sanitize(id)
         out = id.to_s.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
-        out.empty? ? 'unit' : out
+        return 'unit' if out.empty?
+
+        WINDOWS_RESERVED_BASENAMES.match?(out) ? "_#{out}" : out
       end
 
       # Replace only the chars that are structural inside a wikilink alias.