jekyll-agent-audit 0.1.0

data/lib/jekyll/agent_audit/reporters/console.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AgentAudit
+    module Reporters
+      module Console
+        module_function
+        SEVERITIES = %w[error warning info experimental].freeze
+        MAX_VALUE_LENGTH = 240
+
+        def render(report, verbose: false)
+          data = report.to_h
+          summary = data.fetch("summary", {})
+          lines = ["AI publishing audit — local build", "", "Documents inspected: #{safe(summary["documents_inspected"])}"]
+          lines << "Active findings: #{severity_summary(summary["active"])}"
+          lines << "Suppressed findings: #{safe(summary["suppressed"], "0")}"
+          lines << coverage_line(data.fetch("coverage", {}), data.dig("run", "complete"))
+          lines << ""
+          lines << "Discovery: Not assessed — jekyll-agent-discovery"
+          append_findings(lines, report.findings, verbose)
+          append_diagnostics(lines, data.fetch("diagnostics", []), verbose)
+          lines << ""
+          lines << result_line(report, data)
+          lines.join("\n")
+        end
+
+        def append_findings(lines, findings, verbose)
+          visible = findings.reject(&:suppressed?)
+          grouped = visible.group_by { |finding| [finding["category"].to_s, finding["rule_id"].to_s] }
+          grouped.sort_by { |(category, rule), _| [category, rule] }.each do |(category, rule), members|
+            lines << ""
+            lines << "#{label(category)} — #{escape(rule)}#{members.length > 1 ? " (#{members.length} occurrences)" : ""}"
+            members.each { |finding| append_finding(lines, finding, verbose) }
+          end
+          return unless verbose
+          findings.select(&:suppressed?).group_by { |finding| finding["rule_id"] }.each do |rule, members|
+            lines << ""
+            lines << "Suppressed — #{escape(rule)} (#{members.length})"
+            members.each { |finding| append_finding(lines, finding, true, suppressed: true) }
+          end
+        end
+
+        def append_finding(lines, finding, verbose, suppressed: false)
+          severity = finding["severity"].to_s.upcase
+          evidence = finding["evidence_level"]
+          lines << "  #{severity} #{escape(finding["rule_id"])}#{evidence.to_s.empty? ? "" : " [#{escape(evidence)}]"}"
+          lines << "    #{bounded(finding["message"])}"
+          lines << "    URL: #{bounded(finding["document_url"])}" if finding["document_url"]
+          lines << "    Source: #{location(finding["source_path"], finding["source_line"])}" if finding["source_path"] || finding["source_line"]
+          rendered = finding["rendered_location"] || {}
+          if rendered["path"] || rendered[:path]
+            lines << "    Rendered: #{location(rendered["path"] || rendered[:path], rendered["line"] || rendered[:line])}"
+          end
+          observation = finding["observation"] || {}
+          lines << "    Observation: #{bounded(format_value(observation))}" unless observation.empty?
+          lines << "    Remediation: #{bounded(finding["remediation"])}" unless finding["remediation"].to_s.empty?
+          append_related(lines, finding["related_locations"]) unless Array(finding["related_locations"]).empty?
+          if suppressed
+            lines << "    Suppression: #{bounded(format_value(finding["suppression"] || {}))}"
+          elsif verbose && !observation.empty?
+            lines << "    Metadata: #{bounded(format_value(observation))}"
+          end
+        end
+
+        def append_related(lines, locations)
+          Array(locations).each do |related|
+            related = related.transform_keys(&:to_s) if related.respond_to?(:transform_keys)
+            path = related["path"] || related["source_path"] || related["url"] || related["entity"]
+            line = related["line"] || related["source_line"]
+            origin = related["origin"] ? " (#{escape(related["origin"])})" : ""
+            lines << "    Related: #{location(path, line)}#{origin}"
+          end
+        end
+
+        def append_diagnostics(lines, diagnostics, verbose)
+          items = Array(diagnostics)
+          return if items.empty? && !verbose
+          lines << ""
+          lines << "Diagnostics#{items.empty? ? "" : " (#{items.length})"}:"
+          if items.empty?
+            lines << "  None"
+          else
+            items.each do |diagnostic|
+              diagnostic = diagnostic.transform_keys(&:to_s) if diagnostic.respond_to?(:transform_keys)
+              code = diagnostic["code"] || "diagnostic"
+              message = diagnostic["message"] || format_value(diagnostic)
+              lines << "  #{escape(code)}: #{bounded(message)}"
+            end
+          end
+        end
+
+        def coverage_line(coverage, run_complete = true)
+          rules = coverage.fetch("rules", {})
+          incomplete = rules.values.count { |item| item["status"].to_s == "incomplete" || item[:status].to_s == "incomplete" }
+          skipped = rules.values.sum { |item| (item["skipped"] || item[:skipped] || 0).to_i }
+          state = !run_complete || !incomplete.zero? ? "incomplete" : "complete"
+          "Coverage: #{state} for enabled checks; #{skipped} applications skipped"
+        end
+
+        def result_line(report, data)
+          code = Array(data["diagnostics"]).any? { |item| (item["code"] || item[:code]).to_s == "interrupted" } ? 130 : report.exit_code
+          result = {0 => "passed", 1 => "failed policy", 130 => "interrupted"}.fetch(code, "incomplete")
+          "Result: #{result} (fail_on=#{escape(data.dig("policy", "fail_on"))}). Exit #{code}."
+        end
+
+        def severity_summary(active)
+          active = active || {}
+          SEVERITIES.map { |severity| "#{safe(active[severity], "0")} #{severity}" }.join(", ")
+        end
+
+        def location(path, line_number)
+          value = bounded(path || "unknown")
+          line_number ? "#{value}:#{safe(line_number)}" : value
+        end
+
+        def label(value)
+          value.to_s.empty? ? "Findings" : value.to_s.capitalize
+        end
+
+        def bounded(value)
+          escape(value.to_s)[0, MAX_VALUE_LENGTH]
+        end
+
+        def format_value(value)
+          case value
+          when Hash then value.map { |key, item| "#{key}=#{format_value(item)}" }.join(", ")
+          when Array then value.map { |item| format_value(item) }.join(", ")
+          else value.to_s
+          end
+        end
+
+        def safe(value, fallback = "")
+          value.nil? ? fallback : escape(value)
+        end
+
+        def escape(value)
+          value.to_s.gsub(/[\x00-\x1f\x7f]/) { |char| char == "\e" ? "\\e" : "\\x%02x" % char.ord }
+        end
+        private_class_method :append_diagnostics, :append_finding, :append_findings, :append_related, :bounded,
+          :coverage_line, :escape, :format_value, :label, :location, :safe, :severity_summary
+      end
+    end
+  end
+end

data/lib/jekyll/agent_audit/reporters/json.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Jekyll
+  module AgentAudit
+    module Reporters
+      module JSON
+        module_function
+        def render(report)
+          ::JSON.generate(report.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/agent_audit/rules/provenance.rb

@@ -0,0 +1,412 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "set"
+require "time"
+
+module Jekyll
+  module AgentAudit
+    module Rules
+      module Provenance
+        ARTICLE_TYPES = %w[Article BlogPosting NewsArticle].freeze
+        INTENT_KEYS = {
+          published: [[:date], ["date"]],
+          modified: [[:seo, :date_modified], ["seo", "date_modified"], [:last_modified_at], ["last_modified_at"]],
+          author: [[:author], ["author"]]
+        }.freeze
+
+        module_function
+
+        def evaluate(id, document, context)
+          return {status: :not_applicable, findings: [], reason: "unknown rule"} unless %w[
+            provenance.jsonld_invalid provenance.date_invalid provenance.date_order provenance.metadata_conflict
+          ].include?(id)
+
+          return {status: :not_applicable, findings: [], reason: "no document"} unless document
+
+          if %w[provenance.date_order provenance.metadata_conflict].include?(id) && ambiguous_article?(document, context)
+            return {status: :skipped, findings: [], reason: "ambiguous primary Article entity"}
+          end
+          if id == "provenance.date_order"
+            dates = provenance_sources(document, context)
+            unless dates[:published].any? { |source| source[:explicit] } && dates[:modified].any? { |source| source[:explicit] }
+              return {status: :skipped, findings: [], reason: "no comparable explicit publication and modification dates"}
+            end
+          end
+          if id == "provenance.metadata_conflict" && !metadata_comparable?(document, context)
+            return {status: :skipped, findings: [], reason: "no comparable provenance metadata pair"}
+          end
+          findings = case id
+          when "provenance.jsonld_invalid" then invalid_jsonld(document)
+          when "provenance.date_invalid" then invalid_dates(document, context)
+          when "provenance.date_order" then date_order(document, context)
+          when "provenance.metadata_conflict" then metadata_conflict(document, context)
+          end
+          {status: :evaluated, findings: findings}
+        end
+
+        def invalid_jsonld(document)
+          scripts(document).map do |script|
+            JSON.parse(script[:text] || script["text"])
+            nil
+          rescue JSON::ParserError => e
+            draft(document, "Invalid JSON in an application/ld+json script.",
+              {error: e.message.to_s.gsub(/[\x00-\x1f]/, " ")[0, 200], source: :jsonld}, line(script))
+          end.compact
+        end
+
+        def invalid_dates(document, context)
+          sources = provenance_sources(document, context)
+          sources.map do |field, values|
+            values.map do |source|
+              next unless source[:explicit]
+              next if parse_date(source[:value], context)
+              next if timezone_free_timestamp?(source[:value], context)
+
+              draft(document, "#{field} contains an unparseable explicit machine date.",
+                {field: field, value: source[:value], origin: source[:origin]}, source[:line])
+            end.compact
+          end.flatten
+        end
+
+        def date_order(document, context)
+          sources = provenance_sources(document, context)
+          published = comparable_date(sources[:published], context)
+          modified = comparable_date(sources[:modified], context)
+          return [] unless published && modified
+          return [] unless interval_before?(modified[:interval], published[:interval])
+
+          [draft(document, "Explicit dateModified precedes datePublished for the primary article.", {
+            published: published[:value], modified: modified[:value],
+            published_origin: published[:origin], modified_origin: modified[:origin]
+          }, modified[:line])]
+        end
+
+        def metadata_conflict(document, context)
+          sources = provenance_sources(document, context)
+          findings = []
+          %i[published modified].each do |field|
+            parsed = sources[field].map do |source|
+              next unless source[:explicit]
+              value = parse_date(source[:value], context)
+              value && source.merge(interval: value)
+            end.compact
+            next if parsed.length < 2
+            next unless parsed.combination(2).any? { |a, b| disjoint?(a[:interval], b[:interval]) }
+
+            findings << draft(document, "Explicit #{field} metadata values conflict.", {
+              field: field, values: parsed.map { |value| source_observation(value) }
+            }, parsed.last[:line], locations_for(parsed))
+          end
+
+          author_sets = author_sources(document, context).map do |source|
+            ids = author_set(source[:value])
+            ids.empty? ? nil : source.merge(set: ids, identity_kind: author_identity_kind(source[:value]))
+          end.compact
+          if author_sets.length >= 2 && author_sets.map { |source| source[:identity_kind] }.uniq.length == 1 &&
+              author_sets.combination(2).any? { |a, b| a[:set] != b[:set] }
+            findings << draft(document, "Explicit author metadata values conflict.", {
+              field: :author, values: author_sets.map { |source| source_observation(source).merge(authors: source[:set].to_a.sort) }
+            }, author_sets.last[:line], locations_for(author_sets))
+          end
+          publisher_sets = publisher_sources(document, context).map do |source|
+            set = author_set(source[:value])
+            set.empty? ? nil : source.merge(set: set, identity_kind: author_identity_kind(source[:value]))
+          end.compact
+          if publisher_sets.length >= 2 && publisher_sets.map { |source| source[:identity_kind] }.uniq.length == 1 &&
+              publisher_sets.combination(2).any? { |a, b| a[:set] != b[:set] }
+            findings << draft(document, "Explicit publisher metadata values conflict.", {
+              field: :publisher, values: publisher_sets.map { |source| source_observation(source).merge(publishers: source[:set].to_a.sort) }
+            }, publisher_sets.last[:line], locations_for(publisher_sets))
+          end
+          findings
+        end
+
+        def metadata_comparable?(document, context)
+          sources = provenance_sources(document, context)
+          sources.values.any? { |values| values.count { |source| source[:explicit] } >= 2 } ||
+            author_sources(document, context).count { |source| source[:explicit] } >= 2 ||
+            publisher_sources(document, context).count { |source| source[:explicit] } >= 2
+        end
+
+        def provenance_sources(document, context)
+          graph = primary_article(document, context)
+          values = {published: [], modified: []}
+          values[:published].concat(explicit_sources(document, :published))
+          values[:modified].concat(explicit_sources(document, :modified))
+          values[:published].concat(metadata_sources(document, :published))
+          values[:modified].concat(metadata_sources(document, :modified))
+          if graph
+            values[:published] << source(graph["datePublished"], :jsonld, graph["@id"], graph["__audit_line"])
+            modified = source(graph["dateModified"], :jsonld, graph["@id"], graph["__audit_line"])
+            modified[:explicit] = false if modified && seo_fallback_date?(graph, document, context)
+            values[:modified] << modified
+          end
+          infer_seo_rendered_fallback!(values, document, context)
+          values.transform_values { |items| items.compact }
+        end
+
+        def infer_seo_rendered_fallback!(values, document, context)
+          return unless seo_plugin_active?(context) && explicit_sources(document, :modified).empty?
+          published = values[:published].map { |item| parse_date(item[:value], context) }.compact
+          return if published.empty?
+          values[:modified].each do |modified|
+            parsed = parse_date(modified[:value], context)
+            modified[:explicit] = false if parsed && published.any? { |interval| overlaps?(interval, parsed) }
+          end
+        end
+
+        def author_sources(document, context)
+          sources = explicit_sources(document, :author) + metadata_sources(document, :author)
+          graph = primary_article(document, context)
+          return sources unless graph
+          author_reference = graph["author"]
+          author = resolved_value(author_reference, document, context)
+          entity = author.is_a?(Hash) ? (author["@id"] || author_reference["@id"] || graph["@id"]) : graph["@id"]
+          sources << source(author, :jsonld, entity, graph["__audit_line"]) if author
+          sources
+        end
+
+        def publisher_sources(document, context)
+          sources = metadata_sources(document, :publisher)
+          graph = primary_article(document, context)
+          return sources unless graph
+          publisher_reference = graph["publisher"]
+          publisher = resolved_value(publisher_reference, document, context)
+          if publisher
+            value = publisher.is_a?(Hash) && publisher["name"] ? publisher["name"] : publisher
+            entity = publisher.is_a?(Hash) ? (publisher["@id"] || publisher_reference["@id"] || graph["@id"]) : graph["@id"]
+            sources << source(value, :jsonld, entity, graph["__audit_line"])
+          end
+          sources
+        end
+
+        def explicit_sources(document, field)
+          value, present = intent_value(document[:explicit_data] || document["explicit_data"], field)
+          return [] unless present
+          [source(value, :explicit, nil)]
+        end
+
+        def metadata_sources(document, field)
+          nodes = document[:metadata_nodes] || document["metadata_nodes"] || {}
+          candidates = Array(nodes[field] || nodes[field.to_s])
+          if field == :author && candidates.length > 1
+            values = candidates.map { |candidate| candidate.is_a?(Hash) ? (candidate[:value] || candidate["value"]) : candidate }
+            first = candidates.first
+            return [source(values, first.is_a?(Hash) ? (first[:origin] || first["origin"] || :rendered) : :rendered,
+              nil, first.is_a?(Hash) ? (first[:line] || first["line"]) : nil)]
+          end
+          candidates.map do |candidate|
+            candidate = {value: candidate} unless candidate.is_a?(Hash)
+            source(candidate[:value] || candidate["value"], candidate[:origin] || candidate["origin"] || :rendered, nil,
+              candidate[:line] || candidate["line"]).tap do |entry|
+                entry[:entity] = candidate[:entity] || candidate["entity"] if entry
+              end
+          end.compact
+        end
+
+        def primary_article(document, context)
+          nodes = jsonld_nodes(document)
+          articles = nodes.values.select { |node| article?(node) }
+          return nil if articles.empty?
+          url = document[:url] || document["url"]
+          canonical = canonical_urls(document, context)
+          matches = articles.select do |article|
+            [article["url"], article["mainEntityOfPage"]].any? do |candidate|
+              candidate = candidate["@id"] if candidate.is_a?(Hash)
+              candidate && [url, *canonical].compact.include?(candidate)
+            end
+          end
+          return matches.first if matches.length == 1
+          return nil if articles.length == 1 && (articles.first["url"] || articles.first["mainEntityOfPage"])
+          articles.length == 1 ? articles.first : nil
+        end
+
+        def ambiguous_article?(document, context)
+          nodes = jsonld_nodes(document)
+          articles = nodes.values.select { |node| article?(node) }
+          return false if articles.length < 2
+          url = document[:url] || document["url"]
+          canonical = canonical_urls(document, context)
+          articles.count do |article|
+            [article["url"], article["mainEntityOfPage"]].any? do |candidate|
+              candidate = candidate["@id"] if candidate.is_a?(Hash)
+              candidate && [url, *canonical].include?(candidate)
+            end
+          end != 1
+        end
+
+        def jsonld_nodes(document)
+          scripts(document).each_with_object({}) do |script, result|
+            begin
+              collect_nodes(JSON.parse(script[:text] || script["text"]), result, line(script))
+            rescue JSON::ParserError
+              next
+            end
+          end
+        end
+
+        def collect_nodes(value, result, line_number = nil)
+          case value
+          when Array then value.each { |item| collect_nodes(item, result, line_number) }
+          when Hash
+            if value["@graph"]
+              collect_nodes(value["@graph"], result, line_number)
+            elsif value["@id"]
+              result[value["@id"]] = value.merge("__audit_line" => line_number)
+            elsif value["@type"]
+              result["__anonymous_#{result.length}"] = value.merge("__audit_line" => line_number)
+            end
+          end
+        end
+
+        def resolved_value(value, document, context)
+          return value unless value.is_a?(Hash) && value["@id"]
+          jsonld_nodes(document)[value["@id"]]
+        end
+
+        def author_set(value)
+          authors = value.is_a?(Array) ? value : [value]
+          authors.map do |author|
+            author = author[:value] if author.is_a?(Hash) && author.key?(:value)
+            if author.is_a?(Hash)
+              author["@id"] || author["url"] || normalize_name(author["name"])
+            else
+              normalize_name(author)
+            end
+          end.compact.to_set
+        end
+
+        def author_identity_kind(value)
+          authors = value.is_a?(Array) ? value : [value]
+          authors.any? { |author| author.is_a?(Hash) && (author["@id"] || author["url"]) } ? :id : :name
+        end
+
+        def canonical_urls(document, context)
+          Array(document[:canonicals] || document["canonicals"]).map do |item|
+            href = item[:url] || item["url"] || item[:href] || item["href"]
+            next href unless href && context[:resolver]
+            resolved = context[:resolver].resolve(href, document)
+            resolved.is_a?(Hash) ? (resolved[:url] || resolved["url"]) : nil
+          end.compact
+        end
+
+        def parse_date(value, context)
+          return nil unless value.is_a?(String) || value.is_a?(Date) || value.is_a?(Time) || value.is_a?(DateTime)
+          if value.is_a?(Date) && !value.is_a?(DateTime)
+            next_date = value + 1
+            return [Time.utc(value.year, value.month, value.day), Time.utc(next_date.year, next_date.month, next_date.day)]
+          end
+          if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+            date = Date.parse(value)
+            next_date = date + 1
+            return [Time.utc(date.year, date.month, date.day), Time.utc(next_date.year, next_date.month, next_date.day)]
+          end
+          return [value.utc, value.utc] if value.respond_to?(:utc)
+          return nil unless value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}T/)
+          return nil if value.match?(/T[^Z+\-]*\z/) && timezone(context).nil?
+          timestamp = value
+          if timestamp.match?(/T[^Z+\-]*\z/)
+            offset = timezone(context)
+            return nil unless offset.is_a?(String) && offset.match?(/\A[+-]\d{2}:?\d{2}\z/)
+            timestamp = "#{timestamp}#{offset}"
+          end
+          instant = Time.iso8601(timestamp)
+          [instant, instant]
+        rescue ArgumentError, Date::Error
+          nil
+        end
+
+        def comparable_date(values, context)
+          values.map { |item| next unless item[:explicit]; parsed = parse_date(item[:value], context); parsed && item.merge(interval: parsed) }.compact.first
+        end
+
+        def disjoint?(a, b)
+          !overlaps?(a, b)
+        end
+
+        def overlaps?(a, b)
+          a_point = a[0] == a[1]
+          b_point = b[0] == b[1]
+          return a[0] == b[0] if a_point && b_point
+          return a[0] >= b[0] && a[0] < b[1] if a_point
+          return b[0] >= a[0] && b[0] < a[1] if b_point
+          a[0] < b[1] && b[0] < a[1]
+        end
+
+        def interval_before?(a, b)
+          return a[0] < b[0] if a[0] == a[1]
+          return a[1] <= b[0] if b[0] == b[1]
+          a[1] <= b[0]
+        end
+
+        def intent_value(data, field)
+          return [nil, false] unless data.is_a?(Hash)
+          paths = INTENT_KEYS[field] || []
+          paths.each do |path|
+            current = data
+            path.each do |key|
+              current = current[key] || current[key.to_s] if current.is_a?(Hash)
+            end
+            return [current, true] unless current.nil?
+          end
+          [nil, false]
+        end
+
+        def source(value, origin, entity, line = nil)
+          return nil if value.nil?
+          {value: value, origin: origin, entity: entity, line: line, explicit: true}
+        end
+
+        def seo_fallback_date?(graph, document, context)
+          return false unless seo_plugin_active?(context)
+          return false if explicit_sources(document, :modified).any?
+          graph["datePublished"] && graph["dateModified"] && graph["datePublished"] == graph["dateModified"]
+        end
+
+        def seo_plugin_active?(context)
+          plugins = context[:plugins] || context.dig(:site_config, :plugins) || context.dig(:site_config, "plugins") || []
+          Array(plugins).any? { |plugin| plugin.to_s == "jekyll-seo-tag" }
+        end
+
+        def source_observation(source)
+          {value: source[:value], origin: source[:origin], entity: source[:entity], line: source[:line]}
+        end
+
+        def locations_for(sources)
+          sources.map { |source| {line: source[:line], entity: source[:entity], origin: source[:origin]} }
+        end
+
+        def scripts(document)
+          Array(document[:jsonld_scripts] || document["jsonld_scripts"])
+        end
+
+        def line(script)
+          script[:line] || script["line"]
+        end
+
+        def article?(node)
+          Array(node["@type"]).any? { |type| ARTICLE_TYPES.include?(type) }
+        end
+
+        def normalize_name(value)
+          value.to_s.strip.gsub(/\s+/, " ") unless value.nil?
+        end
+
+        def timezone(context)
+          context.dig(:site_config, :timezone) || context.dig(:site_config, "timezone")
+        end
+
+        def timezone_free_timestamp?(value, context)
+          value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}T/) &&
+            value.match?(/T[^Z+\-]*\z/) && timezone(context).nil?
+        end
+
+        def draft(document, message, observation, line = nil, related_locations = [])
+          {document: document, message: message, observation: observation, line: line, related_locations: related_locations}
+        end
+      end
+    end
+  end
+end