woods 1.5.0 → 1.6.1

data/lib/woods/obsidian/note_builder.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'yaml'
+require 'woods/export/unit_facts'
+
+module Woods
+  module Obsidian
+    # Renders one extracted unit into a single Obsidian note: flat YAML
+    # frontmatter (the machine-queryable surface) followed by a Markdown body
+    # with wikilinks (the human surface).
+    #
+    # Two invariants from the design:
+    # - **Edges come from the graph, not the unit.** The authoritative "Depends
+    #   on" / "Used by" sections are rendered from +depends_on+/+used_by+ passed
+    #   in by the exporter (derived from the dependency graph). The "Associations"
+    #   section is an explicit, human-only nicety read from unit metadata and is
+    #   not part of the machine edge contract.
+    # - **Frontmatter is flat.** Obsidian's Properties UI cannot represent nested
+    #   objects, so only scalars and flat lists go in YAML; structured edges live
+    #   in the +_woods/+ sidecar. Frontmatter is emitted via Psych so any
+    #   identifier (quotes, colons, hashes, newlines) is escaped correctly.
+    class NoteBuilder
+      # Cap on how many "Used by" links a single note renders before summarizing,
+      # so a hub with hundreds of dependents doesn't dominate the note or graph.
+      USED_BY_DISPLAY_CAP = 50
+
+      ASSOCIATION_ORDER = %w[belongs_to has_one has_many has_and_belongs_to_many].freeze
+
+      # @param name_mapper [NameMapper] resolves ids to wikilinks/paths
+      # @param nodes [Hash] graph nodes ({ id => { 'type' => , ... } }) for edge-endpoint types
+      # @param pagerank [Hash{String=>Float}] persisted pagerank scores
+      # @param analysis [Hash, nil] parsed graph_analysis.json (hubs/cycles/orphans/bridges) or nil
+      # @param include_source [Boolean] embed scrubbed source code
+      # @param scanner [#scan, nil] credential scanner (required when include_source)
+      def initialize(name_mapper:, nodes:, pagerank: {}, analysis: nil, include_source: false, scanner: nil)
+        @mapper = name_mapper
+        @nodes = nodes || {}
+        @pagerank = pagerank || {}
+        @include_source = include_source
+        @scanner = scanner
+        @hubs = identifier_set(analysis, 'hubs')
+        @bridges = identifier_set(analysis, 'bridges')
+        @orphans = plain_set(analysis, 'orphans')
+        @cycle_members = cycle_member_set(analysis)
+      end
+
+      # @param id [String] bare unit identifier (graph node key)
+      # @param unit [Hash] parsed unit JSON (used only for body facts)
+      # @param depends_on [Array<Hash>] [{ target:, via: }] filtered to the emitted set
+      # @param used_by [Array<String>] unique dependent ids filtered to the emitted set
+      # @return [String] the rendered note. A failed source scrub omits the source
+      #   section (the note is still written); build never returns nil.
+      def build(id:, unit:, depends_on:, used_by:)
+        sections = [
+          frontmatter(id, unit, depends_on, used_by),
+          heading(id, unit),
+          meta_line(unit),
+          callout(id, used_by),
+          depends_section(depends_on),
+          used_by_section(used_by),
+          associations_section(unit),
+          schema_section(unit),
+          source_section(unit)
+        ].compact
+
+        "#{sections.join("\n\n")}\n"
+      end
+
+      private
+
+      # ── Frontmatter ──────────────────────────────────────────────────
+
+      def frontmatter(id, unit, depends_on, used_by)
+        fm = {
+          'woods_managed' => true,
+          'id' => id,
+          'type' => unit['type'],
+          'file' => unit['file_path'],
+          'source_hash' => unit['source_hash'],
+          'pagerank' => pagerank_for(id),
+          'dependency_count' => depends_on.size,
+          'dependent_count' => used_by.size,
+          'tags' => tags_for(id, unit),
+          'aliases' => [id]
+        }.compact
+        "#{fm.to_yaml}---"
+      end
+
+      def pagerank_for(id)
+        score = @pagerank[id]
+        score&.round(6)
+      end
+
+      def tags_for(id, unit)
+        tags = ['woods/unit', "woods/#{unit['type']}"]
+        tags << 'woods/hub' if @hubs.include?(id)
+        tags << 'woods/orphan' if @orphans.include?(id)
+        tags << 'woods/cycle' if @cycle_members.include?(id)
+        tags << 'woods/bridge' if @bridges.include?(id)
+        tags
+      end
+
+      # ── Body ─────────────────────────────────────────────────────────
+
+      def heading(id, unit)
+        "# #{unit['identifier'] || id}"
+      end
+
+      def meta_line(unit)
+        meta = unit['metadata'] || {}
+        parts = []
+        parts << "**File:** `#{unit['file_path']}`" if unit['file_path']
+        parts << "**LOC:** #{meta['loc']}" if meta['loc']
+        parts << table_part(meta) if meta['table_name']
+        parts.empty? ? nil : parts.join(' | ')
+      end
+
+      def table_part(meta)
+        cols = meta['column_count'] || (meta['columns'] || []).size
+        part = "**Table:** #{meta['table_name']}"
+        part += " (#{cols} columns)" if cols.is_a?(Integer) && cols.positive?
+        part
+      end
+
+      def callout(id, used_by)
+        if @hubs.include?(id)
+          pr = pagerank_for(id)
+          suffix = pr ? " (PageRank #{format('%.4f', pr)})" : ''
+          "> [!warning] Hub — high blast radius\n> #{used_by.size} units depend on this#{suffix}."
+        elsif @cycle_members.include?(id)
+          "> [!warning] Part of a dependency cycle\n> This unit participates in a circular dependency."
+        end
+      end
+
+      def depends_section(depends_on)
+        rows = depends_on.filter_map do |dep|
+          target = dep[:target] || dep['target']
+          via = dep[:via] || dep['via']
+          link = @mapper.wikilink(target)
+          next unless link
+
+          [target.to_s, via.to_s, "- #{link}#{" — *#{via}*" if via}"]
+        end
+        return nil if rows.empty?
+
+        lines = rows.sort_by { |target, via, _| [target, via] }.map(&:last)
+        (['## Depends on'] + lines).join("\n")
+      end
+
+      def used_by_section(used_by)
+        return nil if used_by.empty?
+
+        shown = used_by.sort.first(USED_BY_DISPLAY_CAP)
+        lines = ["## Used by (#{used_by.size})"]
+        shown.group_by { |sid| @nodes.dig(sid, 'type') || 'other' }.sort.each do |type, sids|
+          links = sids.sort.filter_map { |sid| @mapper.wikilink(sid) }
+          lines << "**#{pluralize(type)}:** #{links.join(', ')}" unless links.empty?
+        end
+        more = used_by.size - shown.size
+        lines << "*…and #{more} more (see graph)*" if more.positive?
+        lines.join("\n")
+      end
+
+      def associations_section(unit)
+        return nil unless unit['type'] == 'model'
+
+        by_type = Woods::Export::UnitFacts.new(unit).associations_by_type
+        return nil if by_type.empty?
+
+        lines = ['## Associations']
+        ASSOCIATION_ORDER.each do |macro|
+          rendered = render_associations(by_type[macro])
+          lines << "**#{macro}:** #{rendered.join(', ')}" unless rendered.empty?
+        end
+        lines.size > 1 ? lines.join("\n") : nil
+      end
+
+      # +items+ are UnitFacts association entries: { target:, dependent: }.
+      def render_associations(items)
+        return [] unless items
+
+        items.filter_map do |assoc|
+          link = @mapper.wikilink(assoc[:target])
+          next unless link
+
+          assoc[:dependent] ? "#{link} (dependent: #{assoc[:dependent]})" : link
+        end.sort
+      end
+
+      # Human-readable schema highlights (model only) — enums, scopes, concerns,
+      # callbacks — formatted from the shared UnitFacts.
+      def schema_section(unit)
+        return nil unless unit['type'] == 'model'
+
+        highlights = Woods::Export::UnitFacts.new(unit).schema_highlights
+        parts = []
+        parts << "**Enums:** #{highlights[:enums].keys.sort.join(', ')}" if highlights[:enums].any?
+        parts << "**Scopes:** #{highlights[:scopes].sort.join(', ')}" if highlights[:scopes].any?
+        parts << "**Concerns:** #{highlights[:concerns].sort.join(', ')}" if highlights[:concerns].any?
+        parts << "**Callbacks:** #{format_callbacks(highlights[:callbacks])}" if highlights[:callbacks].any?
+
+        parts.empty? ? nil : (['## Schema'] + parts).join("\n")
+      end
+
+      def format_callbacks(callbacks)
+        callbacks.map { |cb| [cb[:type], cb[:filter]].compact.join(' ') }.sort.join(', ')
+      end
+
+      # Renders the source block when enabled. If the credential scrub fails it
+      # returns nil (omit the section) rather than shipping unscrubbed source —
+      # the note is still written, just without its source block.
+      def source_section(unit)
+        return nil unless @include_source
+
+        code = unit['source_code']
+        return nil if code.nil? || code.to_s.empty?
+
+        scrubbed = scrub(code)
+        return nil if scrubbed.nil?
+
+        "## Source\n\n```ruby\n#{scrubbed.chomp}\n```"
+      end
+
+      def scrub(code)
+        return code unless @scanner
+
+        scanned, = @scanner.scan(code)
+        scanned
+      rescue StandardError
+        nil
+      end
+
+      # ── Analysis sets ────────────────────────────────────────────────
+
+      def identifier_set(analysis, key)
+        entries = analysis && analysis[key]
+        return Set.new unless entries.is_a?(Array)
+
+        entries.filter_map { |e| e.is_a?(Hash) ? e['identifier'] : e }.to_set
+      end
+
+      def plain_set(analysis, key)
+        entries = analysis && analysis[key]
+        entries.is_a?(Array) ? entries.to_set : Set.new
+      end
+
+      def cycle_member_set(analysis)
+        cycles = analysis && analysis['cycles']
+        return Set.new unless cycles.is_a?(Array)
+
+        cycles.flatten.to_set
+      end
+
+      def pluralize(type)
+        type.end_with?('y') ? "#{type[0..-2]}ies" : "#{type}s"
+      end
+    end
+  end
+end

data/lib/woods/obsidian/vault_assets.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module Obsidian
+    # Generates the static-ish vault configuration files: the `.obsidian/`
+    # settings Obsidian reads (app.json, types.json, graph.json) and the
+    # `Units.base` Obsidian Bases view.
+    #
+    # Grounded in Steph Ango's published vault conventions and the official
+    # Obsidian docs:
+    # - `app.json` only governs links Obsidian *generates*; our authored
+    #   `[[path|alias]]` links resolve regardless. We still set absolute-path
+    #   wikilinks as a courtesy for the user's future edits.
+    # - We deliberately do NOT ship `core-plugins.json` — graph and Bases are
+    #   enabled by default, and a partial plugin list could disable other
+    #   defaults.
+    # - `types.json` types the properties so Bases columns sort numerically
+    #   (pagerank/counts) and tags render as tags.
+    # - `graph.json` color groups apply to the *global* graph only (local-graph
+    #   colors live in volatile workspace.json, which must not be shipped).
+    module VaultAssets
+      module_function
+
+      # Palette of 24-bit RGB ints assigned to type tags in sorted order so the
+      # graph coloring is deterministic across runs.
+      PALETTE = [
+        0xE5_5A_5A, 0x5A_9B_E5, 0x5A_E5_8B, 0xE5_C8_5A, 0xB4_5A_E5,
+        0x5A_E5_D6, 0xE5_8B_5A, 0x8B_E5_5A, 0xE5_5A_B4, 0x5A_6B_E5
+      ].freeze
+
+      PROPERTY_TYPES = {
+        'id' => 'text', 'type' => 'text', 'file' => 'text', 'source_hash' => 'text',
+        'pagerank' => 'number', 'dependency_count' => 'number', 'dependent_count' => 'number',
+        'tags' => 'tags', 'aliases' => 'aliases'
+      }.freeze
+
+      # @return [String] .obsidian/app.json
+      def app_json
+        pretty(
+          'newLinkFormat' => 'absolute',
+          'useMarkdownLinks' => false,
+          'alwaysUpdateLinks' => true
+        )
+      end
+
+      # @return [String] .obsidian/types.json (property -> type registry)
+      def types_json
+        pretty('types' => PROPERTY_TYPES)
+      end
+
+      # @param types [Array<String>] singular unit types present in the vault
+      # @return [String] .obsidian/graph.json with per-type color groups
+      def graph_json(types)
+        groups = Array(types).uniq.sort.each_with_index.map do |type, i|
+          { 'query' => "tag:#woods/#{type}", 'color' => { 'a' => 1, 'rgb' => PALETTE[i % PALETTE.size] } }
+        end
+        pretty('colorGroups' => groups, 'showTags' => true, 'showAttachments' => false)
+      end
+
+      # @return [String] Units.base — an Obsidian Bases view (YAML)
+      def units_base
+        <<~YAML
+          filters:
+            and:
+              - 'file.hasTag("woods/unit")'
+          properties:
+            type:
+              displayName: Type
+            pagerank:
+              displayName: PageRank
+            dependent_count:
+              displayName: Used by
+            dependency_count:
+              displayName: Depends on
+          views:
+            - type: table
+              name: All units
+              groupBy: type
+              order:
+                - file.name
+                - type
+                - pagerank
+                - dependent_count
+                - dependency_count
+            - type: table
+              name: Hubs
+              filters:
+                and:
+                  - 'file.hasTag("woods/hub")'
+              order:
+                - file.name
+                - dependent_count
+                - pagerank
+        YAML
+      end
+
+      def pretty(hash)
+        "#{JSON.pretty_generate(hash)}\n"
+      end
+    end
+  end
+end