okf 1.0.0

data/lib/okf/concept/file.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module OKF
+  class Concept
+    # A single concept file on disk — the ActiveRecord-style handle over one `.md`.
+    # Wraps a pure OKF::Concept with load/save/delete/reload side effects. Part of
+    # the shell (it does I/O); the pure Concept knows nothing about it.
+    #
+    #   file = OKF::Concept::File.read(root: "docs", path: "tables/orders.md")
+    #   file.concept              # => OKF::Concept (pure)
+    #   file.concept.links        # interrogate it in memory
+    #   file.save                 # write concept.to_markdown back to disk
+    #   file.delete
+    #
+    # NOTE: this class is named File, which shadows Ruby's File inside the
+    # OKF::Concept namespace — every filesystem call here uses ::File explicitly.
+    class File
+      attr_reader :root, :path, :concept
+
+      # Read a concept file from disk into a handle.
+      def self.read(root:, path:)
+        new(root: root, path: path).reload
+      end
+
+      # Write a concept's markdown to disk under +root+ and return the handle.
+      def self.write(root:, concept:)
+        new(root: root, path: concept.path, concept: concept).save
+      end
+
+      def initialize(root:, path:, concept: nil)
+        @root = ::File.expand_path(root.to_s)
+        @path = Path.normalize_relative!(path)
+        @concept = concept
+      end
+
+      # Absolute on-disk path, guarded so it cannot escape the bundle root.
+      def absolute_path
+        Path.join_under!(@root, @path)
+      end
+
+      def save
+        raise Error, "no concept to save" if @concept.nil?
+
+        target = absolute_path
+        ::FileUtils.mkdir_p(::File.dirname(target))
+        ::File.write(target, @concept.to_markdown, encoding: "UTF-8")
+        self
+      end
+
+      def delete
+        ::FileUtils.rm_f(absolute_path)
+        self
+      end
+
+      def reload
+        content = ::File.read(absolute_path, encoding: "UTF-8")
+        frontmatter, body = Markdown::Frontmatter.parse(content)
+        @concept = Concept.new(path: @path, frontmatter: frontmatter, body: body)
+        self
+      end
+    end
+  end
+end

data/lib/okf/concept.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module OKF
+  class Concept
+    # Reserved filenames (spec §3.1): defined at any level of the hierarchy and
+    # never concept documents. The single source of truth for "concept vs
+    # reserved" — OKF::Bundle and OKF::Bundle::Validator ask through Concept.reserved?.
+    RESERVED_FILENAMES = %w[index.md log.md].freeze
+
+    # The lint checks that apply to a single concept out of bundle context. The
+    # rest (orphan, backlog, duplicate_title, …) need the whole bundle.
+    CONCEPT_SCOPED_CHECKS = %i[
+      stub missing_title missing_description missing_timestamp
+      uncited_external self_link unused_reference_def undefined_reference
+    ].freeze
+
+    # Whether a bundle-relative path names a reserved file rather than a concept.
+    # `::File` is explicit: OKF::Concept::File (the on-disk handle) shadows Ruby's
+    # File inside this namespace.
+    def self.reserved?(path)
+      RESERVED_FILENAMES.include?(::File.basename(path))
+    end
+
+    attr_reader :path, :frontmatter, :body
+
+    def initialize(path:, frontmatter:, body:)
+      @path = Path.normalize_relative!(path)
+      @frontmatter = Markdown::Frontmatter.stringify_keys(frontmatter)
+      @body = body.to_s
+    end
+
+    # Stable node identity. A concept may pin an explicit `id` in its frontmatter
+    # (any scalar; blank is ignored); otherwise it is the bundle-relative path with
+    # the `.md` suffix stripped — i.e. "folder/filename". Because cross-links are
+    # file paths, OKF::Bundle maps a resolved link path back to the concept there
+    # and uses *its* id, so a custom id still resolves edges correctly.
+    def id
+      explicit = frontmatter["id"].to_s.strip
+      explicit.empty? ? path.sub(/\.md\z/, "") : explicit
+    end
+
+    def type
+      frontmatter["type"]
+    end
+
+    def title
+      frontmatter["title"]
+    end
+
+    def description
+      frontmatter["description"]
+    end
+
+    # Canonical URI of the underlying asset (spec §4.1), when the concept is bound
+    # to one. Absent for concepts describing purely abstract ideas.
+    def resource
+      frontmatter["resource"]
+    end
+
+    def tags
+      frontmatter["tags"]
+    end
+
+    def timestamp
+      frontmatter["timestamp"]
+    end
+
+    def reserved?
+      self.class.reserved?(path)
+    end
+
+    # ── analysis (pure; the same primitives the graph/linter use) ──
+
+    # Raw markdown cross-link targets in the body, in document order (spec §5).
+    def links
+      Markdown::Links.extract(body)
+    end
+
+    # Citation link targets under the `# Citations` section (spec §8), or [].
+    def citations
+      Markdown::Citations.targets(body)
+    end
+
+    # Body links that point outside the bundle — external URLs and mailto:.
+    def external_links
+      links.select { |raw| raw.match?(Markdown::Links::SCHEME) || raw.start_with?("mailto:") }
+    end
+
+    # Serialize back to a markdown document (frontmatter + body) — the inverse of
+    # Markdown::Frontmatter.parse.
+    def to_markdown
+      Markdown::Frontmatter.dump(frontmatter, body)
+    end
+
+    # Lint this concept in isolation: the concept-scoped checks only (a lone
+    # concept has no bundle to judge reachability, backlog, or duplicate titles).
+    def lint(**options)
+      Bundle.new(concepts: [ self ]).lint(only: CONCEPT_SCOPED_CHECKS, **options)
+    end
+  end
+end

data/lib/okf/markdown/citations.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OKF
+  module Markdown
+    # Parses the conventional `# Citations` section of a concept body (spec §8): the
+    # block of external sources listed at the bottom of a document. Pure and
+    # fence-aware, mirroring Links; it reuses Links.extract to pull the citation link
+    # targets so citations and cross-links agree on what counts as a link.
+    module Citations
+      # A markdown ATX heading line: 1–6 `#`, whitespace, then the heading text.
+      HEADING = /\A(\#{1,6})\s+(.*?)\s*\z/.freeze
+      CITATIONS = /\ACitations\z/i.freeze
+
+      module_function
+
+      # The body text under a `# Citations` heading, up to the next heading at the
+      # same or higher level, or nil when there is no Citations section.
+      def section(body)
+        lines = []
+        level = nil
+        in_fence = false
+        body.to_s.each_line do |line|
+          if Links::FENCE.match?(line.strip)
+            in_fence = !in_fence
+            lines << line unless level.nil?
+            next
+          end
+
+          heading = in_fence ? nil : HEADING.match(line.strip)
+          if level.nil?
+            next unless heading && CITATIONS.match?(heading[2])
+
+            level = heading[1].length
+          elsif heading && heading[1].length <= level
+            break
+          else
+            lines << line
+          end
+        end
+        lines.join unless level.nil?
+      end
+
+      # Citation link targets within the `# Citations` section (empty when absent).
+      def targets(body)
+        Links.extract(section(body).to_s)
+      end
+    end
+  end
+end

data/lib/okf/markdown/frontmatter.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module OKF
+  # Primitives for parsing structure out of a markdown document — the format layer
+  # (§4 frontmatter, §5 links, §8 citations) shared by Concept, Bundle, and the
+  # analyzers. Pure string-in/string-out; no disk, no domain knowledge.
+  module Markdown
+    module Frontmatter
+      class ParseError < Error
+      end
+
+      FRONTMATTER_PATTERN = /\A---[ \t]*\n(.*?)\n---[ \t]*(?:\n|\z)/m.freeze
+
+      # Psych gained keyword arguments for safe_load in 3.1 (Ruby 2.6); older
+      # versions take the permitted classes positionally.
+      PSYCH_KEYWORDS = Gem::Version.new(Psych::VERSION) >= Gem::Version.new("3.1.0")
+
+      module_function
+
+      def parse(content)
+        text = content.to_s
+        raise ParseError, "content is not valid UTF-8" unless text.encoding == Encoding::UTF_8 && text.valid_encoding?
+
+        match = FRONTMATTER_PATTERN.match(text)
+        raise ParseError, "missing YAML frontmatter" unless match
+
+        data = load_yaml(match[1])
+        raise ParseError, "frontmatter must be a mapping" unless data.nil? || data.is_a?(Hash)
+
+        body = text[match.end(0)..-1] || ""
+        [ stringify_keys(data || {}), body.sub(/\A\n/, "") ]
+      rescue Psych::SyntaxError => e
+        raise ParseError, "invalid YAML frontmatter: #{e.message}"
+      end
+
+      def dump(frontmatter, body)
+        attrs = stringify_keys(frontmatter || {})
+        yaml = YAML.dump(attrs).sub(/\A---[ \t]*\n/, "")
+        "---\n#{yaml}---\n\n#{body}"
+      end
+
+      def stringify_keys(hash)
+        hash.to_h.map { |key, value| [ key.to_s, value ] }.to_h
+      end
+
+      def load_yaml(text)
+        if PSYCH_KEYWORDS
+          YAML.safe_load(text, permitted_classes: [ Date, Time ], aliases: false)
+        else
+          YAML.safe_load(text, [ Date, Time ], [], false)
+        end
+      end
+    end
+  end
+end

data/lib/okf/markdown/links.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module OKF
+  module Markdown
+    # Markdown cross-link extraction and resolution — the single source of truth for
+    # "which concepts does this body point at". Shared by OKF::Bundle::Graph (to build edges)
+    # and OKF::Bundle::Validator (to warn on broken cross-links, §5.3), so both agree on what
+    # counts as a link and where it resolves.
+    module Links
+      FENCE = /\A(```|~~~)/.freeze
+      # Inline code span: a run of N backticks, the shortest content (which may hold
+      # shorter backtick runs, per CommonMark), then a matching run of N backticks.
+      # Links inside inline code render as literal text, not edges, so these are
+      # blanked before scanning — the inline analogue of FENCE.
+      CODE_SPAN = /(`+).*?\1/.freeze
+      # Inline link [text](target) or [text](target "title"); (?<!!) skips images.
+      INLINE_LINK = /(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/.freeze
+      # Reference-style use: full [text][label] or collapsed [label][]; (?<!!) skips
+      # images. group 1 = text/label, group 2 = the explicit label (empty if collapsed).
+      REFERENCE_LINK = /(?<!!)\[([^\]]*)\]\[([^\]]*)\]/.freeze
+      # Reference definition: [label]: target  (optionally followed by a "title").
+      DEFINITION = /\A[ \t]{0,3}\[([^\]]+)\]:[ \t]*(\S+)/.freeze
+      SCHEME = %r{\A[a-z][a-z0-9+.-]*://}.freeze
+
+      module_function
+
+      # Raw link targets in +body+, in document order, skipping fenced code blocks
+      # and image links. Handles both inline links and standard reference-style links
+      # (resolving [text][label] against its [label]: target definition). Targets
+      # keep any +#anchor+ — {resolve} strips it.
+      def extract(body)
+        text = body.to_s
+        definitions = reference_definitions(text)
+        found = []
+        each_prose_line(text) do |line|
+          found.concat(line.scan(INLINE_LINK).flatten)
+          line.scan(REFERENCE_LINK).each do |label, explicit|
+            key = (explicit.empty? ? label : explicit).strip.downcase
+            target = definitions[key]
+            found << target if target
+          end
+        end
+        found
+      end
+
+      # Map every reference definition (+[label]: target+) to its target, keyed by
+      # the lowercased label. Definitions may appear anywhere, so they are collected
+      # before uses are resolved.
+      def reference_definitions(text)
+        definitions = {}
+        each_prose_line(text) do |line|
+          match = DEFINITION.match(line)
+          definitions[match[1].strip.downcase] = match[2] if match
+        end
+        definitions
+      end
+
+      # Yield each line outside a fenced code block, with inline code spans blanked.
+      # Both exclusions mirror the rendered document: fenced and inline code are
+      # literal text, so a link written inside them is not a cross-link.
+      def each_prose_line(text)
+        in_fence = false
+        text.each_line do |line|
+          if FENCE.match?(line.strip)
+            in_fence = !in_fence
+            next
+          end
+          yield line.gsub(CODE_SPAN, " ") unless in_fence
+        end
+      end
+
+      # Resolve a raw link target to a bundle-relative +.md+ path, or +nil+ when the
+      # target is not an in-scope markdown cross-link (external scheme, mailto,
+      # non-+.md+, directory, or empty). A relative link that escapes the bundle root
+      # is returned verbatim, so the validator can flag it "not found" and the graph
+      # can drop it.
+      #
+      # @param from   [String] bundle-relative path of the source file, e.g. "features/x.md"
+      # @param bundle [String] path to the bundle root
+      def resolve(raw, from:, bundle:)
+        target = raw.to_s.split("#", 2).first.to_s
+        return nil if target.empty? || target.end_with?("/")
+        return nil if target.match?(SCHEME) || target.start_with?("mailto:")
+        return nil unless target.end_with?(".md")
+        return target.sub(%r{\A/+}, "") if target.start_with?("/")
+
+        bundle_abs = File.expand_path(bundle)
+        source_dir = File.dirname(File.expand_path(from, bundle_abs))
+        candidate = File.expand_path(target, source_dir)
+        if candidate == bundle_abs || candidate.start_with?("#{bundle_abs}/")
+          Pathname.new(candidate).relative_path_from(Pathname.new(bundle_abs)).to_s
+        else
+          target
+        end
+      end
+    end
+  end
+end

data/lib/okf/path.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OKF
+  module Path
+    class Error < OKF::Error
+    end
+
+    def self.normalize_relative!(path)
+      value = path.to_s
+      raise Error, "path is blank" if value.empty?
+      raise Error, "path contains null byte" if value.include?("\0")
+      raise Error, "path must be relative" if value.start_with?("/")
+      raise Error, "path must use forward slashes" if value.include?("\\")
+
+      parts = value.split("/")
+      if parts.any? { |part| part.empty? || part == "." || part == ".." }
+        raise Error, "path contains unsafe segment"
+      end
+
+      parts.join("/")
+    end
+
+    def self.join_under!(root, path)
+      relative = normalize_relative!(path)
+      expanded_root = File.expand_path(root.to_s)
+      expanded_path = File.expand_path(File.join(expanded_root, relative))
+      unless expanded_path == expanded_root || expanded_path.start_with?("#{expanded_root}#{File::SEPARATOR}")
+        raise Error, "path escapes bundle root"
+      end
+
+      expanded_path
+    end
+  end
+end

data/lib/okf/server/app.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "rack"
+
+require "okf/server/graph"
+
+module OKF
+  module Server
+    # HTTP access to a bundle's knowledge graph — a Rack app, so it runs under any
+    # Rack server (WEBrick, via `okf server`) and can be mounted in a Rails app:
+    #
+    #   mount OKF::Server::App.new(folder) => "/knowledge"
+    #
+    # The page (OKF::Server::Graph) boots from a *minimal* graph (id + title + edges
+    # + type/tag indexes) and pulls each concept's markdown body and description from
+    # here on demand, so the initial payload stays small and bodies are read live
+    # from disk (edits show without a restart). Part of the shell — it does I/O.
+    #
+    #   GET /               the interactive graph page (text/html)
+    #   GET /node?id=…      the concept's raw markdown body (text/markdown)
+    #   GET /node/meta?id=… its description, as an escaped HTML fragment
+    #   GET /catalog        rich per-concept metadata for the catalog/files/stats
+    #                       views: { concepts: [ {id, title, type, description,
+    #                       tags, timestamp, status, area, dir, links_*} ] } (JSON)
+    #   GET /tags           the tag index  { tag  => [id, …] } (JSON)
+    #   GET /types          the type index { type => [id, …] } (JSON)
+    class App
+      def initialize(folder, title: nil, link: nil, layout: "cose")
+        @folder = folder
+        @title = title
+        @link = link
+        @layout = layout
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        return not_found unless request.get?
+
+        case request.path_info
+        when "", "/" then respond("text/html; charset=utf-8", page)
+        when "/node" then node_body(request.params["id"])
+        when "/node/meta" then node_meta(request.params["id"])
+        when "/catalog" then respond_json(catalog)
+        when "/tags" then respond_json(graph.tag_index)
+        when "/types" then respond_json(graph.type_index)
+        else not_found
+        end
+      end
+
+      private
+
+      # The minimal graph snapshot taken at boot — drives the page and the indexes.
+      def graph
+        @graph ||= @folder.graph(minimal: true)
+      end
+
+      # Rich per-concept metadata the Catalog, Files and Stats views need but the
+      # lean graph payload deliberately omits — descriptions, tags, timestamps,
+      # status, folder, and in/out link degree. Fetched once, lazily, by the client
+      # so the graph's first paint stays minimal. The shape is built by the pure
+      # OKF::Bundle#catalog, shared with the `okf catalog/files/tags/stats` CLI views.
+      def catalog
+        { concepts: @folder.catalog }
+      end
+
+      def page
+        @page ||= Graph.new(graph, title: @title || @folder.name, link: @link, layout: @layout).render
+      end
+
+      def node_body(id)
+        concept = concept_for(id)
+        return not_found if concept.nil?
+
+        respond("text/markdown; charset=utf-8", concept.body)
+      end
+
+      def node_meta(id)
+        concept = concept_for(id)
+        return not_found if concept.nil?
+
+        respond("text/html; charset=utf-8", description_fragment(concept))
+      end
+
+      # Resolve an id to its concept, read live from disk. The id is only ever a key
+      # into the bundle's id→path map, so it cannot name a file outside the bundle
+      # (and Concept::File re-guards the path); an unknown id, a since-deleted file,
+      # or one that no longer parses all map to 404.
+      def concept_for(id)
+        return nil if id.nil? || id.empty?
+
+        @folder.concept(id)&.concept
+      rescue OKF::Error, SystemCallError
+        nil
+      end
+
+      def description_fragment(concept)
+        description = concept.description.to_s
+        return %(<span class="empty">no description</span>) if description.strip.empty?
+
+        html_escape(description)
+      end
+
+      def respond(content_type, body)
+        [ 200, { "content-type" => content_type }, [ body.to_s ] ]
+      end
+
+      def respond_json(object)
+        respond("application/json; charset=utf-8", JSON.generate(object))
+      end
+
+      def not_found
+        [ 404, { "content-type" => "text/plain; charset=utf-8" }, [ "not found\n" ] ]
+      end
+
+      def html_escape(str)
+        str.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/okf/server/graph.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module OKF
+  module Server
+    # Renders an OKF::Bundle::Graph as the interactive graph page served by
+    # OKF::Server::App. The markup lives in templates/graph.html.erb; #render
+    # returns the HTML string.
+    #
+    # The page boots from a *minimal* payload — nodes carry only id + title, plus
+    # compact TYPES/TAGS inverted indexes for colouring and filtering — and pulls
+    # each concept's markdown body (and metadata) from the server on demand via
+    # fetch, rendering it client-side with marked. Node bodies are therefore NOT
+    # embedded here.
+    #
+    # NOTE (trust boundary): the page loads Cytoscape + marked from a CDN and
+    # renders concept markdown without sanitization, so only serve bundles you
+    # trust. The inline-<script> data is </script>-escaped by #json_for_script
+    # (stdlib ERB does not auto-escape).
+    class Graph
+      TEMPLATE = File.expand_path("templates/graph.html.erb", __dir__)
+      LAYOUTS = %w[cose concentric breadthfirst circle grid].freeze
+
+      # Node-diameter range in px; the template scales within it by node degree.
+      MIN_SIZE = 24
+      MAX_SIZE = 70
+
+      # The 6-character JSON unicode escape for `<` (backslash, u, 0, 0, 3, c),
+      # built from the backslash code point so no literal escape appears here.
+      LT_ESCAPE = (92.chr(Encoding::UTF_8) + "u003c").freeze
+
+      # +node_endpoint+/+meta_endpoint+ are the (mount-relative) URLs the page
+      # fetches a concept's raw markdown and metadata fragment from — relative so
+      # the page works whether served at "/" or mounted under a Rails prefix.
+      def initialize(graph, title: nil, link: nil, layout: "cose", node_endpoint: "node", meta_endpoint: "node/meta")
+        @graph = graph
+        @title = title
+        @link = link
+        @layout = layout
+        @node_endpoint = node_endpoint
+        @meta_endpoint = meta_endpoint
+      end
+
+      def render
+        ERB.new(File.read(TEMPLATE, encoding: "UTF-8")).result(binding)
+      end
+
+      private
+
+      def graph_name
+        @title.to_s.empty? ? "OKF Knowledge Graph" : @title
+      end
+
+      def escaped_name
+        html_escape(graph_name)
+      end
+
+      def og_title
+        html_escape("OKF — #{graph_name}")
+      end
+
+      def og_desc
+        html_escape("#{@graph.nodes.length} concepts · interactive Open Knowledge Format knowledge graph")
+      end
+
+      def source_link
+        return "" if @link.to_s.empty?
+
+        %( <a class="src" href="#{html_escape(@link)}" target="_blank" rel="noopener">source ↗</a>)
+      end
+
+      def nodes_json
+        json_for_script(@graph.nodes)
+      end
+
+      def edges_json
+        json_for_script(@graph.edges)
+      end
+
+      # { type => [id, …] } — the client builds an id→type map for node colour.
+      def types_json
+        json_for_script(@graph.type_index)
+      end
+
+      # { tag => [id, …] } — the client derives a node's tags and offers filters.
+      def tags_json
+        json_for_script(@graph.tag_index)
+      end
+
+      # JSON-encode for safe embedding in an inline <script>: escaping every `<` to
+      # its JSON unicode escape neutralizes </script>, <!-- and <script in one
+      # stroke, and the result stays valid JSON *and* JavaScript.
+      def json_for_script(obj)
+        JSON.generate(coerce(obj)).gsub("<") { LT_ESCAPE }
+      end
+
+      # Coerce any non-JSON-native scalar (e.g. a YAML Date/Time in tags) to a
+      # string, leaving numbers/booleans/nil native.
+      def coerce(obj)
+        case obj
+        when Hash then obj.transform_values { |value| coerce(value) }
+        when Array then obj.map { |value| coerce(value) }
+        when String, Integer, Float, true, false, nil then obj
+        else obj.to_s
+        end
+      end
+
+      def html_escape(str)
+        str.to_s.gsub("&", "&amp;").gsub('"', "&quot;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+    end
+  end
+end