okf 1.12.0 → 2.0.0

data/lib/okf/bundle/folder.rb

@@ -54,10 +54,30 @@ module OKF
         @bundle.hubs
       end
 
+      def directories
+        @bundle.directories
+      end
+
       def directory_index
         @bundle.directory_index
       end
 
+      def stats
+        @bundle.stats
+      end
+
+      def tag_groups(by:, entries: nil)
+        @bundle.tag_groups(by: by, entries: entries)
+      end
+
+      # The §6.3 inventory — this handle's half is the disk: the reader models
+      # only markdown, so listing `references/` here is how a .py attester or a
+      # .sql computation becomes visible at all. The pure model gets the
+      # manifest and answers the rest (citers, dangling pointers).
+      def references
+        Bundle::References.build(@bundle, files: reference_files)
+      end
+
       # Every log.md with its content, root scope first — read live from disk so a
       # just-appended entry shows without a reload; the reserved snapshot is the
       # fallback if the file has since vanished. Shared by `okf render`'s bake
@@ -104,7 +124,18 @@ module OKF
         Concept::File.read(root: @root, path: path)
       end
 
-      # Materialize the in-memory bundle to disk (Writer validates §9 before
+      # The raw markdown bytes for one concept id — read once through the same
+      # containment guard as #concept, but without the parse #concept pays for,
+      # so a caller that wants the file verbatim (never a re-serialized copy)
+      # does one read, not a read plus a discarded frontmatter parse. nil when no
+      # concept has that id; raises Path::Error if the file has become a symlink
+      # escaping the root, and the reader's own SystemCallError if it has gone.
+      def concept_source(id)
+        path = @bundle.paths_by_id[id] or return nil
+        Concept::File.new(root: @root, path: path).read
+      end
+
+      # Materialize the in-memory bundle to disk (Writer validates §11 before
       # publishing, so a malformed bundle is never written).
       def save(overwrite: false)
         Writer.call(
@@ -124,6 +155,16 @@ module OKF
 
       private
 
+      # Bundle-relative paths of every file under references/, sorted. A glob
+      # on a directory that does not exist is simply empty — no references/ and
+      # an empty references/ are the same inventory.
+      def reference_files
+        Dir.glob(File.join(@root, "references", "**", "*"))
+           .select { |path| File.file?(path) }
+           .map { |path| Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s }
+           .sort
+      end
+
       def reserved_hash(basename)
         @bundle.reserved
                .select { |entry| File.basename(entry.path) == basename }
@@ -131,8 +172,12 @@ module OKF
       end
 
       def log_content(path)
-        File.read(File.join(@root, path), encoding: "UTF-8")
-      rescue SystemCallError
+        # Live, but through the same containment as every other read: a log.md
+        # that was a real file at boot and is a symlink out of the root now falls
+        # back to the boot snapshot rather than serving the target — the same
+        # answer a vanished file gets, since an escape is a file we must not read.
+        SafeRead.read!(@root, File.join(@root, path))
+      rescue SystemCallError, Path::Error
         @bundle.reserved_content(path)
       end
     end

data/lib/okf/bundle/graph.rb

@@ -20,7 +20,7 @@ module OKF
       attr_reader :nodes, :edges, :type_index, :tag_index
 
       def self.build(bundle, minimal: false, body: true)
-        # Best-effort (§9): a malformed concept never reaches here — the reader keeps
+        # Best-effort (§11): a malformed concept never reaches here — the reader keeps
         # it in bundle.unparseable — so the rest of the bundle still renders. Inspect
         # bundle.unparseable to detect skips.
         concepts = bundle.concepts
@@ -51,10 +51,19 @@ module OKF
       # Edges resolve by *path* — a markdown link is a file path — then map that path
       # to the concept living there and use its id, so a frontmatter `id` that differs
       # from the path still lands the edge on the right node.
+      # Body links and sources[].resource entries feed the same resolver: §5.1
+      # says a `resource` naming another concept is a derivation edge that
+      # "already exists in the bundle graph", and this is what makes that true —
+      # it is also what keeps a migrated bundle's graph equal to its v0.1 twin's,
+      # since a `# Citations` in-bundle link stops being a body link the moment
+      # it is lifted into frontmatter. URLs and scope descriptors resolve to
+      # nothing; an unresolvable path is broken_source's to report.
       def self.edges_for(concepts, id_by_path, root)
         seen = Set.new
         concepts.each_with_object([]) do |concept, edges|
-          Markdown::Links.extract(concept.body).each do |raw|
+          targets = Markdown::Links.extract(concept.body) +
+                    concept.sources.map { |source| source["resource"] }.compact
+          targets.each do |raw|
             resolved = Markdown::Links.resolve(raw, from: concept.path, bundle: root)
             next if resolved.nil?
 
@@ -86,7 +95,7 @@ module OKF
         concept.tags.is_a?(Array) ? concept.tags : []
       end
 
-      # Blank, not just nil: §9.2 makes a whitespace-only `type` as non-conformant
+      # Blank, not just nil: §11 condition 2 makes a whitespace-only `type` as non-conformant
       # as a missing one (the validator says so with the same OKF.blank?), so the
       # index must not sort them into different buckets. Otherwise `type: "  "`
       # earns its own row, labelled with spaces, next to Untyped.