jekyll-agent-audit 0.1.0

data/lib/jekyll/agent_audit/extractor.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "set"
+require "nokogiri"
+
+module Jekyll
+  module AgentAudit
+    class InputError < StandardError; end unless const_defined?(:InputError)
+
+    class Extractor
+      MAX_NAME_BYTES = 512
+      MAX_EXCERPT_BYTES = 4_096
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def extract(entry)
+        html = entry[:html] || read_artifact(entry[:absolute_path], entry[:destination_root])
+        raise InputError, "HTML exceeds max_html_bytes" if html.bytesize > limit(:max_html_bytes, 5 * 1024 * 1024)
+
+        doc = Nokogiri::HTML5.parse(html, nil, "UTF-8")
+        content = content_node(doc, entry)
+        id_nodes = doc.css("[id]")
+        id_index = id_nodes.each_with_object({}) { |node, index| index[node["id"].to_s] ||= node unless node["id"].to_s.empty? }
+        result = entry.dup.merge(
+          title: compact_text(node_text(doc.at_css("title"))),
+          ids: Set.new(id_index.keys), duplicate_ids: duplicate_ids(id_nodes), duplicate_id_locations: duplicate_id_locations(id_nodes),
+          links: [], canonicals: [], headings: [], base_href: doc.at_css("head base[href]")&.[]("href"),
+          content_basis: content[:basis], content_confident: content[:confident], redirect: redirect?(doc),
+          jsonld_scripts: [], metadata_nodes: Hash.new { |h, k| h[k] = [] }, diagnostics: content[:diagnostics]
+        )
+
+        doc.css("a[href]").each do |node|
+          result[:links] << occurrence(node, accessible_name(node, id_index), :navigation, content[:basis])
+        end
+        doc.css("[cite]").each do |node|
+          href = node["cite"].to_s.strip
+          next if href.empty?
+          result[:links] << {href: href, line: node.line, name: compact_text(node_text(node)), name_supported: true,
+            hidden: hidden?(node), kind: :citation, region: :other}
+        end
+        doc.css("head link[href]").each do |node|
+          rels = node["rel"].to_s.split.map(&:downcase)
+          next if rels.include?("canonical")
+          kind = rels.include?("citation") ? :citation : (rels.include?("alternate") ? :alternate : nil)
+          next unless kind
+          result[:links] << {href: node["href"].to_s, line: node.line, name: compact_text(node["title"]),
+            name_supported: true, hidden: false, kind: kind, region: :other}
+        end
+
+        content[:node]&.css("h1,h2,h3,h4,h5,h6,[role='heading']")&.each do |node|
+          next if excluded?(node) || decorative?(node)
+          level = node.name =~ /h([1-6])/ ? Regexp.last_match(1).to_i : node["aria-level"].to_i
+          next unless (1..6).cover?(level)
+          name = accessible_name(node, id_index)
+          result[:headings] << {level: level, name: name[:name], name_supported: name[:supported], hidden: hidden?(node), line: node.line}
+        end
+        doc.css("head link[rel]").each do |node|
+          rels = node["rel"].to_s.split.map(&:downcase)
+          result[:canonicals] << {href: node["href"], line: node.line} if rels.include?("canonical")
+        end
+        doc.css("script[type]").each do |node|
+          next unless node["type"].to_s.downcase == "application/ld+json"
+          raise InputError, "JSON-LD exceeds max_jsonld_bytes" if node.text.bytesize > limit(:max_jsonld_bytes, 1024 * 1024)
+          result[:jsonld_scripts] << {text: node.text, line: node.line}
+        end
+        result[:content_text] = compact_text(content_text(content[:node]), MAX_EXCERPT_BYTES)
+        extract_metadata(doc, result)
+        result
+      rescue Errno::ENOENT, Errno::EACCES => e
+        raise InputError, e.message
+      rescue Nokogiri::XML::SyntaxError, ArgumentError => e
+        raise InputError, "HTML could not be parsed: #{e.message}"
+      end
+
+      private
+
+      def content_node(doc, entry)
+        selector = page_selector(entry) || config_value(:content, :selector)
+        diagnostics = []
+        if selector
+          matches = doc.css(selector.to_s)
+          return {node: matches.first, basis: :configured, confident: true, diagnostics: diagnostics} if matches.length == 1
+          diagnostics << {code: :content_selector_ambiguous, selector: selector.to_s, matches: matches.length}
+          return {node: nil, basis: :configured, confident: false, diagnostics: diagnostics}
+        end
+        mains = doc.css("main")
+        return {node: mains.first, basis: :main, confident: true, diagnostics: diagnostics} if mains.length == 1
+        landmarks = doc.css("[role='main']")
+        return {node: landmarks.first, basis: :main_role, confident: true, diagnostics: diagnostics} if landmarks.length == 1
+        articles = doc.css("article")
+        return {node: articles.first, basis: :article, confident: true, diagnostics: diagnostics} if articles.length == 1
+        {node: doc.at_css("body"), basis: :body, confident: false, diagnostics: diagnostics}
+      end
+
+      def page_selector(entry)
+        data = entry[:data] || {}
+        page = data["page"] || data[:page] || {}
+        audit = page["agent_audit"] || page[:agent_audit] || {}
+        content = audit["content"] || audit[:content] || {}
+        content["selector"] || content[:selector]
+      end
+
+      def content_text(node)
+        return "" unless node
+        copy = Nokogiri::HTML5.fragment(node.to_html)
+        exclusion_selectors.each do |selector|
+          copy.css(selector).each do |excluded|
+            excluded.add_previous_sibling(" ")
+            excluded.remove
+          end
+        end
+        copy.text.to_s
+      end
+
+      def exclusion_selectors
+        configured = config_value(:content, :exclude_selectors)
+        configured.nil? ? %w[nav footer aside script style template] : Array(configured)
+      end
+
+      def occurrence(node, name, kind, basis)
+        {href: node["href"].to_s, line: node.line, name: name[:name], name_supported: name[:supported],
+          hidden: hidden?(node), kind: kind, region: region(node, basis)}
+      end
+
+      def duplicate_ids(nodes)
+        counts = Hash.new(0)
+        nodes.each { |node| counts[node["id"].to_s] += 1 unless node["id"].to_s.empty? }
+        counts.map { |id, count| id if count > 1 }.compact
+      end
+
+      def duplicate_id_locations(nodes)
+        locations = Hash.new { |hash, key| hash[key] = [] }
+        nodes.each do |node|
+          id = node["id"].to_s
+          locations[id] << node.line unless id.empty?
+        end
+        duplicate_ids(nodes).each_with_object({}) { |id, result| result[id] = locations[id] }
+      end
+
+      def read_artifact(path, destination_root = nil)
+        raise InputError, "missing artifact path" unless path && File.file?(path)
+        if destination_root
+          real = File.realpath(path)
+          root = File.realpath(destination_root)
+          raise InputError, "artifact escapes destination" unless real == root || real.start_with?(root + File::SEPARATOR)
+        end
+        File.binread(path)
+      rescue Errno::ELOOP, Errno::ENOENT, Errno::EACCES => e
+        raise InputError, e.message
+      end
+
+      def extract_metadata(doc, result)
+        selectors = config_value(:metadata, :selectors) || {}
+        {published: :published, modified: :modified, author: :author, publisher: :publisher}.each do |field, key|
+          selector = selectors[key] || selectors[key.to_s]
+          next unless selector
+          nodes = doc.css(selector.to_s)
+          result[:diagnostics] << {code: :metadata_selector_ambiguous, field: field, matches: nodes.length} if %i[published modified].include?(field) && nodes.length > 1
+          nodes.each do |node|
+            value = node["datetime"].to_s.strip
+            next if value.empty?
+            result[:metadata_nodes][field] << {value: compact_text(value), line: node.line, origin: :rendered}
+          end
+        end
+        doc.css("head meta[property]").each do |node|
+          field = {"article:published_time" => :published, "article:modified_time" => :modified}[node["property"].to_s.downcase]
+          next unless field && !node["content"].to_s.strip.empty?
+          result[:metadata_nodes][field] << {value: compact_text(node["content"].to_s.strip), line: node.line, origin: :open_graph}
+        end
+      end
+
+      def accessible_name(node, id_index)
+        label = node["aria-label"].to_s.strip
+        return {name: compact_text(label), supported: true} unless label.empty?
+        if node["aria-labelledby"]
+          ids = node["aria-labelledby"].split
+          return {name: "", supported: false} if ids.empty? || ids.any? { |id| !id_index.key?(id) }
+          return {name: compact_text(ids.map { |id| node_text(id_index[id]) }.join(" ")), supported: true}
+        end
+        image_alt = node.at_css("img[alt]")&.[]("alt").to_s.strip
+        return {name: compact_text(image_alt), supported: true} unless image_alt.empty?
+        {name: compact_text(node_text(node)), supported: true}
+      end
+
+      def excluded?(node)
+        exclusion_selectors.any? do |selector|
+          node.document.css(selector.to_s).any? { |candidate| candidate == node || node.ancestors.include?(candidate) }
+        end
+      end
+
+      def decorative?(node)
+        %w[presentation none].include?(node["role"].to_s.downcase)
+      end
+
+      def node_text(node)
+        node&.text.to_s.gsub(/\s+/, " ").strip
+      end
+
+      def compact_text(value, max_bytes = MAX_NAME_BYTES)
+        text = value.to_s.unicode_normalize(:nfc).gsub(/\s+/, " ").strip
+        return text if text.bytesize <= max_bytes
+        text.byteslice(0, max_bytes).scrub.rstrip + "…"
+      end
+
+      def hidden?(node)
+        node.ancestors.any? { |ancestor| ancestor.key?("hidden") || ancestor["aria-hidden"].to_s.downcase == "true" } ||
+          node.key?("hidden") || node["aria-hidden"].to_s.downcase == "true"
+      end
+
+      def region(node, basis)
+        return :main if basis != :body && node.ancestors.any? { |n| n.name == "main" || n["role"] == "main" }
+        node.ancestors.any? { |n| n.name == "nav" } ? :navigation : :other
+      end
+
+      def redirect?(doc)
+        doc.css("meta[http-equiv]").any? { |node| node["http-equiv"].to_s.casecmp("refresh").zero? }
+      end
+
+      def config_value(*keys)
+        keys.reduce(@configuration.respond_to?(:to_h) ? @configuration.to_h : @configuration) { |v, key| v.is_a?(Hash) ? (v[key] || v[key.to_s]) : nil }
+      end
+
+      def limit(key, default)
+        config_value(:limits, key) || default
+      end
+    end
+  end
+end

data/lib/jekyll/agent_audit/finding.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Jekyll
+  module AgentAudit
+    class Finding
+      SEVERITY_ORDER = {"error" => 0, "warning" => 1, "info" => 2, "experimental" => 3}.freeze
+      attr_reader :data
+
+      def initialize(draft = nil, registry: Registry, **attributes)
+        draft ||= attributes
+        draft = draft.transform_keys(&:to_sym)
+        rule = registry[draft.fetch(:rule_id)] || {}
+        observation = draft.fetch(:observation, {}).transform_keys(&:to_s)
+        @data = {
+          "rule_id" => draft.fetch(:rule_id).to_s, "rule_version" => rule.fetch(:version, "1"),
+          "category" => draft.fetch(:category, rule.fetch(:category, "unknown")).to_s,
+          "severity" => draft.fetch(:severity, rule.fetch(:default_severity, "info")).to_s,
+          "evidence_level" => draft.fetch(:evidence_level, rule.fetch(:evidence_level, "D")).to_s,
+          "confidence" => draft.fetch(:confidence, rule.fetch(:default_confidence, rule.fetch(:evidence_level, "A") == "A" ? "direct" : "heuristic")).to_s, "message" => draft.fetch(:message, "").to_s,
+          "extraction_basis" => draft[:extraction_basis],
+          "document_url" => draft[:document_url], "source_path" => draft[:source_path], "source_line" => draft[:source_line],
+          "rendered_location" => draft[:rendered_location] || {"path" => nil, "line" => draft[:line]}, "observation" => observation,
+          "remediation" => draft[:remediation] || rule[:remediation] || "", "evidence_urls" => Array(draft[:evidence_urls] || rule[:source_urls]),
+          "related_locations" => Array(draft[:related_locations]), "fingerprint" => draft[:fingerprint] || fingerprint(observation, draft),
+          "suppression" => draft[:suppression]
+        }
+      end
+
+      def [](key) = @data[key.to_s]
+      def to_h = @data.dup
+      def severity_rank = SEVERITY_ORDER.fetch(self["severity"], 99)
+      def suppressed? = !self["suppression"].nil?
+
+      private
+
+      def fingerprint(observation, draft)
+        stable = [draft[:rule_id], draft[:rule_version] || "1", draft[:document_identity] || draft[:document_url], stable_observation(observation)].to_json
+        Digest::SHA256.hexdigest(stable)
+      end
+
+      def stable_observation(value, key = nil)
+        case value
+        when Hash
+          value.keys.sort.each_with_object({}) do |child_key, result|
+            next if %w[line source_line rendered_location absolute_path].include?(child_key.to_s)
+            result[child_key.to_s] = stable_observation(value[child_key], child_key)
+          end
+        when Array then value.map { |item| stable_observation(item) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/agent_audit/link_graph.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "set"
+require "uri"
+
+module Jekyll
+  module AgentAudit
+    class LinkGraph
+      attr_reader :diagnostics
+
+      def initialize(documents, resolver, configuration, site_config = {})
+        @documents, @resolver, @configuration, @site_config = Array(documents), resolver, configuration, site_config || {}
+        @incoming, @edges, @by_source, @diagnostics = Hash.new { |h, k| h[k] = Set.new }, [], Hash.new { |h, k| h[k] = [] }, []
+        build
+      end
+
+      def incoming(document)
+        @incoming[document[:identity]]
+      end
+      def edges
+        @edges.dup
+      end
+      def edges_for(document)
+        @by_source[document[:identity]].dup
+      end
+
+      def reachable
+        roots = roots_config
+        found, queue = Set.new, roots.map { |root| @documents.find { |d| root_match?(d, root) } }.compact
+        until queue.empty?
+          current = queue.shift
+          next if found.include?(current[:identity])
+          found << current[:identity]
+          @edges.select { |edge| edge[:source][:identity] == current[:identity] && edge[:target] }.each { |edge| queue << edge[:target] }
+        end
+        found
+      end
+
+      private
+
+      def build
+        @documents.each do |document|
+          Array(document[:links]).each do |link|
+            resolution = @resolver.resolve(link[:href], document)
+            edge = {source: document, occurrence: link, resolution: resolution, target: resolution[:target], kind: link[:kind]}
+            @edges << edge
+            @by_source[document[:identity]] << edge
+            if resolution[:target] && link[:kind] == :navigation && resolution[:target][:identity] != document[:identity]
+              @incoming[resolution[:target][:identity]] << document
+            end
+          end
+        end
+        roots_config.each { |root| @diagnostics << {code: :invalid_graph_root, root: root} unless @documents.any? { |d| root_match?(d, root) } }
+        limit = config_limit(:max_edges, 1_000_000)
+        @diagnostics << {code: :edge_limit, limit: limit, value: @edges.length} if @edges.length > limit
+      end
+
+      def roots_config
+        config = @configuration.respond_to?(:to_h) ? @configuration.to_h : @configuration
+        graph = config[:graph] || config["graph"] || {}
+        Array(graph[:roots] || graph["roots"] || ["/"]).map(&:to_s)
+      end
+
+      def root_match?(document, root)
+        base = @site_config.fetch("baseurl", @site_config[:baseurl]).to_s.sub(%r{/\z}, "")
+        route = root == "/" && !base.empty? ? "#{base}/" : root
+        return true if document[:route].to_s == route || (root == "/" && document[:route].to_s == "/index.html")
+        begin
+          URI.parse(document[:url].to_s).path == route
+        rescue URI::InvalidURIError
+          false
+        end
+      end
+
+      def config_limit(key, default)
+        config = @configuration.respond_to?(:to_h) ? @configuration.to_h : @configuration
+        limits = config[:limits] || config["limits"] || {}
+        limits[key] || limits[key.to_s] || default
+      end
+    end
+  end
+end

data/lib/jekyll/agent_audit/registry.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AgentAudit
+    module Registry
+      SEVERITIES = %w[error warning info experimental].freeze
+      SOURCE_URLS = {
+        "G-AI" => "https://developers.google.com/search/docs/appearance/ai-features",
+        "G-DATE" => "https://developers.google.com/search/docs/appearance/publication-dates",
+        "G-ARTICLE" => "https://developers.google.com/search/docs/appearance/structured-data/article",
+        "G-WHO" => "https://developers.google.com/search/docs/fundamentals/creating-helpful-content",
+        "G-LINK" => "https://developers.google.com/search/docs/crawling-indexing/links-crawlable",
+        "G-CAN" => "https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls",
+        "URI" => "https://www.rfc-editor.org/rfc/rfc3986",
+        "JSON" => "https://www.rfc-editor.org/rfc/rfc8259",
+        "CAN" => "https://www.rfc-editor.org/rfc/rfc6596.txt",
+        "HEAD" => "https://www.w3.org/WAI/tutorials/page-structure/headings/",
+        "LINK" => "https://www.w3.org/WAI/WCAG22/Techniques/html/H80",
+        "TABLE" => "https://www.w3.org/WAI/tutorials/tables/one-header/",
+        "G-2026" => "https://developers.google.com/search/docs/fundamentals/ai-optimization-guide",
+        "GEO" => "https://arxiv.org/abs/2311.09735",
+        "CSEO" => "https://arxiv.org/abs/2506.11097",
+        "AGEO" => "https://arxiv.org/abs/2603.09296"
+      }.freeze
+
+      MVP_RULES = %w[
+        architecture.output_collision links.target_missing links.fragment_missing architecture.orphan
+        identity.canonical_invalid identity.canonical_multiple identity.canonical_target_missing
+        structure.title_missing structure.h1_absent structure.heading_empty structure.heading_jump
+        structure.id_duplicate structure.link_unnamed provenance.jsonld_invalid provenance.date_invalid
+        provenance.date_order provenance.metadata_conflict
+      ].freeze
+
+      DEFERRED_RULES = %w[
+        architecture.unreachable architecture.weak_connections duplicates.exact_body duplicates.near_body
+        identity.canonical_review identity.canonical_chain identity.canonical_absent structure.link_generic
+        structure.table_headers structure.long_section structure.main_landmark provenance.author_absent
+        provenance.author_profile_absent provenance.publication_absent provenance.modification_absent
+        provenance.publisher_absent citations.quote_attribution citations.sources_inventory representations.identity_conflict
+        retrieval.definition_candidates retrieval.concrete_fact_candidates retrieval.numeric_context
+        retrieval.comparison_candidates retrieval.procedure_candidates retrieval.example_candidates
+        retrieval.subject_context citations.claim_source_alignment provenance.originality_evidence
+      ].freeze
+
+      # [category, evidence, severity, source keys, applicability, required inputs, limitations, remediation]
+      DETAILS = {
+        "architecture.output_collision" => ["architecture", "A", "error", %w[URI], "site inventory and output ownership", %w[inventory output_paths public_routes], %w[aliases and directory_indexes can be intentional], "Give each distinct emitter a unique destination or document the ownership boundary."],
+        "links.target_missing" => ["architecture", "A", "error", %w[URI G-LINK], "rendered links and managed local targets", %w[html_links complete_manifest url_resolver], %w[external and deployment_owned targets are unverified], "Correct the href or declare the target outside the managed build."],
+        "links.fragment_missing" => ["architecture", "A", "error", %w[URI], "managed local HTML links with fragments", %w[html_links target_ids named_anchors], %w[empty/top/text_fragments and unsupported targets are skipped], "Correct the fragment or add the referenced ID/name anchor."],
+        "architecture.orphan" => ["architecture", "B", "warning", %w[G-LINK], "non-root rendered content pages", %w[html_navigation_links complete_inventory], %w[self_links redirects and explicit_exemptions are excluded], "Add an incoming rendered navigation link or declare the page exemption."],
+        "identity.canonical_invalid" => ["identity", "A", "error", %w[URI CAN], "head canonical declarations", %w[canonical_hrefs uri_parser], %w[valid relative empty_self external or unsupported_iri cases are not rejected], "Remove the malformed canonical or replace it with a valid URI reference."],
+        "identity.canonical_multiple" => ["identity", "A", "error", %w[CAN G-CAN], "documents with canonical declarations", %w[all_canonical_hrefs url_resolver], %w[identical repeated declarations collapse], "Keep one canonical URL, or make repeated declarations identical."],
+        "identity.canonical_target_missing" => ["identity", "A", "error", %w[CAN], "managed local canonical targets", %w[canonical_uri local_inventory], %w[external targets remain unverified], "Correct the canonical target or publish the managed target."],
+        "structure.title_missing" => ["structure", "B", "warning", %w[G-AI], "rendered HTML documents", %w[rendered_title], %w[front_matter alone does not satisfy the rendered check], "Render a nonempty title for the document."],
+        "structure.h1_absent" => ["structure", "C", "info", %w[HEAD], "confidently extracted content pages", %w[content_extraction heading_tree], %w[ambiguous or body_fallback extraction skips the content-sensitive check], "Review the content selector or render a level-one heading."],
+        "structure.heading_empty" => ["structure", "B", "warning", %w[HEAD], "content headings", %w[heading_text accessible_name visibility], %w[decorative hidden and complex naming cases are skipped], "Give the heading text or a supported accessible name."],
+        "structure.heading_jump" => ["structure", "C", "info", %w[HEAD], "confidently extracted heading sequences", %w[ordered_content_headings], %w[closing subsections and ambiguous extraction are excluded], "Review the heading hierarchy around the reported pair."],
+        "structure.id_duplicate" => ["structure", "A", "error", %w[URI], "rendered documents", %w[element_ids named_anchors], %w[only repeated nonempty identifiers are reported], "Make each fragment identifier unique within the document."],
+        "structure.link_unnamed" => ["structure", "B", "warning", %w[LINK G-LINK], "navigational anchors", %w[anchor_text image_alt aria_name], %w[complex unsupported accessible naming is skipped], "Add link text, an image alt, or a supported accessible name."],
+        "provenance.jsonld_invalid" => ["provenance", "A", "error", %w[JSON], "application/ld+json scripts", %w[script_text json_parser script_line], %w[valid unsupported JSON-LD is not an error], "Fix the JSON syntax in the reported structured-data script."],
+        "provenance.date_invalid" => ["provenance", "B", "warning", %w[G-DATE G-ARTICLE], "recognized explicit publication/modification fields", %w[explicit_data rendered_metadata primary_article machine_dates], %w[natural_language and unrelated Event dates are excluded], "Replace the value with a valid ISO date or timezone-aware timestamp."],
+        "provenance.date_order" => ["provenance", "B", "warning", %w[G-DATE G-ARTICLE], "an unambiguous primary Article with comparable dates", %w[article_identity publication_date modification_date], %w[date_only uncertainty intervals and timezone_free timestamps without configured timezone skip], "Check the metadata sources and correct the modification/publication ordering."],
+        "provenance.metadata_conflict" => ["provenance", "B", "warning", %w[G-DATE G-ARTICLE], "equivalent mapped provenance fields with at least two comparable sources", %w[explicit_data rendered_metadata primary_article], %w[aliases brand_suffixes unrelated_graph_nodes unresolved_references and compatible_precision are excluded], "Reconcile the conflicting declarations or remove the unsupported claim."],
+        "architecture.unreachable" => ["architecture", "B", "warning", %w[G-LINK], "complete directed HTML graph", %w[graph_roots complete_inventory navigation_edges], %w[deferred until graph reachability and root validity are shipped], "Add a path from a configured root or document the page as intentionally outside navigation."],
+        "architecture.weak_connections" => ["architecture", "C", "info", %w[G-LINK], "opt-in graph connection analysis", %w[incoming_navigation contextual_edges], %w[no minimum link count or ranking cutoff], "Review contextual links if the observed connection is unintended."],
+        "duplicates.exact_body" => ["duplicates", "C", "info", %w[G-CAN], "distinct page identities with comparable content", %w[normalized_main_content representation_exclusions], %w[duplicate text is an observation, not an automatic harmfulness claim], "Review whether the pages should remain distinct or declare an equivalent representation."],
+        "duplicates.near_body" => ["duplicates", "D", "experimental", %w[GEO CSEO AGEO], "explicitly configured lexical similarity analysis", %w[tokenizer threshold bounded_candidate_comparison], %w[heuristic candidates can miss pairs and do not imply plagiarism], "Review the reported overlap and its configured algorithm; do not auto-merge pages."],
+        "identity.canonical_review" => ["identity", "C", "info", %w[CAN G-CAN], "opt-in content pages with canonical declarations", %w[public_url canonical_url expected_canonical], %w[an external or superseding canonical is valid and difference alone is not a defect], "Confirm that the differing canonical expresses the intended syndication or consolidation."],
+        "identity.canonical_chain" => ["identity", "B", "warning", %w[CAN], "opt-in managed canonical graph", %w[local_canonical_edges cycle_detection], %w[external canonical edges are outside the local chain], "Point the page directly at the intended canonical target and remove the cycle."],
+        "identity.canonical_absent" => ["identity", "C", "info", %w[G-CAN], "opted-in content pages", %w[rendered_canonical_declarations], %w[HTTP-header canonicals are unknown], "Add a canonical if the publication contract calls for one."],
+        "structure.link_generic" => ["structure", "C", "info", %w[LINK G-LINK], "opt-in rendered navigational links", %w[link_label locale context], %w[locale-specific detection is contextual and not an accessibility failure], "Use a link label that identifies the destination in context."],
+        "structure.table_headers" => ["structure", "B", "warning", %w[TABLE], "opt-in author-declared data tables", %w[table_structure header_relationships], %w[layout and ambiguous tables are skipped], "Add explicit header relationships to the data table."],
+        "structure.long_section" => ["structure", "D", "experimental", %w[G-2026], "opt-in sections with an author-configured threshold", %w[section_boundaries tokenizer threshold], %w[no universal threshold or forced_chunking recommendation], "Review the measured section size and threshold as an editorial choice."],
+        "structure.main_landmark" => ["structure", "C", "info", %w[G-2026], "opt-in rendered pages without a confident content landmark", %w[main_landmarks content_selector], %w[the observation does not claim invalid HTML], "Configure the content selector or provide an unambiguous main landmark."],
+        "provenance.author_absent" => ["provenance", "C", "info", %w[G-WHO], "opted-in article profiles", %w[rendered_author_evidence explicit_vs_rendered_provenance], %w[front_matter_only evidence is reported as not rendered], "Render a recognized person or organization author when the profile contract requires one."],
+        "provenance.author_profile_absent" => ["provenance", "C", "info", %w[G-ARTICLE], "opted-in profiles with recognized authors", %w[author_profile_url sameAs linked_byline], %w[organizations and pseudonyms are valid; social links are not required], "Add a profile URL, sameAs relation, or linked byline where appropriate."],
+        "provenance.publication_absent" => ["provenance", "C", "info", %w[G-DATE], "opted-in article profiles", %w[explicit_publication_evidence], %w[generic pages and inferred collection timestamps are excluded], "Publish explicit publication date evidence if the profile requires it."],
+        "provenance.modification_absent" => ["provenance", "C", "info", %w[G-ARTICLE], "profiles explicitly opting into update metadata", %w[explicit_update_intent rendered_modification_field], %w[no default check for every article], "Render an explicit modification date or remove the update-metadata declaration."],
+        "provenance.publisher_absent" => ["provenance", "C", "info", %w[G-WHO], "opted-in profiles", %w[recognized_publisher configured_visible_site_identity], %w[do not infer a publisher from a domain or arbitrary site title], "Provide a recognized publisher identity when the profile requires one."],
+        "citations.quote_attribution" => ["citations", "C", "info", %w[G-WHO], "opt-in marked-up quotations", %w[quotation_markup cite_url visible_attribution exemptions], %w[attribution detection cannot prove correctness], "Add a source link or visible attribution where appropriate."],
+        "citations.sources_inventory" => ["citations", "C", "info", %w[G-LINK], "opt-in rendered documents", %w[reference_links citation_markup external_link_classification], %w[zero references is an observation, never unsupported_claims proof], "Review the source inventory as an editorial observation."],
+        "representations.identity_conflict" => ["representations", "B", "warning", %w[URI], "recognized sibling metadata representations", %w[advertised_sibling equivalent_identity_date_fields], %w[raw Markdown without metadata and unadvertised siblings are skipped], "Reconcile the sibling representation's explicit identity or date metadata."],
+        "retrieval.definition_candidates" => ["retrieval", "D", "experimental", %w[GEO CSEO AGEO], "opt-in semantic candidate inventory", %w[passage_text lexical_candidate_detector], %w[no definition quota or semantic-understanding claim], "Review candidates editorially; do not add definitions to satisfy a quota."],
+        "retrieval.concrete_fact_candidates" => ["retrieval", "D", "experimental", %w[GEO CSEO AGEO], "opt-in semantic candidate inventory", %w[passage_text candidate_detector], %w[cannot establish factuality or distinguish fiction without context], "Review candidates editorially; the detector does not verify facts."],
+        "retrieval.numeric_context" => ["retrieval", "D", "experimental", %w[GEO CSEO AGEO], "opt-in numeric-context inventory", %w[numbers units dates nearby_prose], %w[more numbers are not inherently better; preserve scope and uncertainty], "Review numerical context and scope editorially."],
+        "retrieval.comparison_candidates" => ["retrieval", "D", "experimental", %w[GEO CSEO AGEO], "opt-in comparison candidate inventory", %w[comparison_passage dimensions], %w[no comparison-section or table requirement], "Review whether the comparison is useful for readers."],
+        "retrieval.procedure_candidates" => ["retrieval", "D", "experimental", %w[GEO CSEO AGEO], "opt-in procedure candidate inventory", %w[ordered_instruction_candidates], %w[nonprocedural pages need no numbered list], "Review procedure candidates editorially."],
+        "retrieval.example_candidates" => ["retrieval", "D", "experimental", %w[GEO CSEO AGEO], "opt-in example/code candidate inventory", %w[labeled_examples code_samples], %w[no minimum example count], "Review whether examples clarify the subject."],
+        "retrieval.subject_context" => ["retrieval", "D", "experimental", %w[GEO CSEO AGEO], "opt-in passage context inventory", %w[passages heading_ancestry pronoun_candidates], %w[do not force repetition or an answer-first template], "Review isolated passages with their heading context."],
+        "citations.claim_source_alignment" => ["citations", "D", "experimental", %w[GEO CSEO AGEO], "opt-in claim/source candidate inventory", %w[claims nearby_links citation_context], %w[link proximity is not entailment or verification], "Review whether the cited source supports the claim."],
+        "provenance.originality_evidence" => ["provenance", "D", "experimental", %w[GEO CSEO AGEO], "opt-in declared originality evidence inventory", %w[declared_methods datasets observations], %w[declarations do not prove first-party origin; no originality score], "Review the declaration and supporting evidence editorially."]
+      }.freeze
+
+      class << self
+        def all
+          @all ||= begin
+            records = MVP_RULES.map { |id| build(id, "M") }
+            records.concat(DEFERRED_RULES.map { |id| build(id, "D") })
+            records.to_h { |entry| [entry[:id], entry] }.freeze
+          end
+        end
+
+        def mvp_ids
+          MVP_RULES.freeze
+        end
+
+        def known?(id)
+          all.key?(id.to_s)
+        end
+
+        def deferred?(id)
+          all.fetch(id.to_s, {})[:release] == "D"
+        end
+
+        def [](id)
+          all[id.to_s]
+        end
+
+        private
+
+        def build(id, release)
+          category, evidence, severity, source_keys, applicability, inputs, limits, remediation = DETAILS.fetch(id)
+          {
+            id: id, version: "1.0", category: category, default_severity: severity,
+            evidence_level: evidence, source_urls: source_keys.map { |key| SOURCE_URLS.fetch(key) },
+            applicability: applicability, required_inputs: inputs, limitations: limits,
+            remediation: remediation, release: release
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/agent_audit/report.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Jekyll
+  module AgentAudit
+    class Report
+      SCHEMA_VERSION = "1.0"
+      attr_reader :data
+
+      def initialize(findings: [], coverage: {}, diagnostics: [], documents_inspected: 0, options: {}, site_config: {}, complete: true,
+                     reference_time: Time.now.utc, operational_error: false, effective_configuration: nil, build: nil)
+        @findings = findings.map { |f| f.is_a?(Finding) ? f : Finding.new(f) }
+        @coverage = coverage
+        @diagnostics = diagnostics
+        @documents_inspected = documents_inspected
+        @options = options
+        @complete = complete
+        @site_config = site_config
+        @reference_time = reference_time
+        @operational_error = operational_error
+        @effective_configuration = effective_configuration
+        @build = build
+        @data = build_data
+      end
+
+      def findings = @findings
+      def to_h = deep_dup(@data)
+      def exit_code
+        return 2 if @operational_error || !@complete
+        fail_on = @options.fetch("fail_on", "error")
+        return 0 if fail_on == "none"
+        return 1 if @findings.any? { |f| !f.suppressed? && f["severity"] == "error" }
+        return 1 if fail_on == "warning" && @findings.any? { |f| !f.suppressed? && f["severity"] == "warning" }
+        0
+      end
+
+      private
+
+      def build_data
+        active = Hash.new(0)
+        suppressed = 0
+        affected = {}
+        @findings.each do |finding|
+          if finding.suppressed?
+            suppressed += 1
+          else
+            active[finding["severity"]] += 1
+            affected[finding["document_url"]] = true
+          end
+        end
+        {
+          "schema_version" => SCHEMA_VERSION, "tool" => {"name" => "jekyll-agent-audit", "version" => VERSION},
+          "run" => {"mode" => "local_build", "complete" => @complete, "site_url" => @site_config["url"].to_s,
+                    "baseurl" => @site_config["baseurl"].to_s, "environment" => ENV.fetch("JEKYLL_ENV", "development"),
+                    "reference_time" => @reference_time.iso8601, "ruleset_version" => VERSION,
+                    "effective_configuration" => @effective_configuration, "build" => @build},
+          "policy" => {"fail_on" => @options.fetch("fail_on", "error"), "passed" => exit_code.zero?, "exit_code" => exit_code},
+          "summary" => {"documents_inspected" => @documents_inspected, "active" => %w[error warning info experimental].to_h { |s| [s, active[s]] },
+                         "suppressed" => suppressed, "affected_documents" => affected.length},
+          "coverage" => {"discovery" => {"status" => "not_assessed", "owner" => "jekyll-agent-discovery"}, "rules" => @coverage},
+          "findings" => sorted_findings.map(&:to_h), "diagnostics" => @diagnostics
+        }
+      end
+
+      def sorted_findings
+        @findings.sort_by { |f| [f["source_path"].to_s, f.severity_rank, f["rule_id"], f["rendered_location"].to_h["line"].to_i] }
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash then value.to_h { |k, v| [k, deep_dup(v)] }
+        when Array then value.map { |v| deep_dup(v) }
+        else value
+        end
+      end
+    end
+  end
+end