jekyll-agent-audit 0.1.0

data/schema/report-1.0.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "jekyll-agent-audit report 1.0",
+  "type": "object",
+  "required": ["schema_version", "tool", "run", "policy", "summary", "coverage", "findings", "diagnostics"],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "tool": {
+      "type": "object", "required": ["name", "version"],
+      "properties": {"name": {"const": "jekyll-agent-audit"}, "version": {"type": "string"}}
+    },
+    "run": {
+      "type": "object", "required": ["mode", "complete", "site_url", "baseurl", "environment", "reference_time", "ruleset_version"],
+      "properties": {
+        "mode": {"const": "local_build"}, "complete": {"type": "boolean"},
+        "site_url": {"type": "string"}, "baseurl": {"type": "string"},
+        "environment": {"type": "string"}, "reference_time": {"type": "string"},
+        "ruleset_version": {"type": "string"}
+      }
+    },
+    "policy": {
+      "type": "object", "required": ["fail_on", "passed", "exit_code"],
+      "properties": {"fail_on": {"enum": ["error", "warning", "none"]}, "passed": {"type": "boolean"}, "exit_code": {"enum": [0, 1, 2, 130]}}
+    },
+    "summary": {
+      "type": "object", "required": ["documents_inspected", "active", "suppressed", "affected_documents"],
+      "properties": {
+        "documents_inspected": {"$ref": "#/$defs/count"}, "suppressed": {"$ref": "#/$defs/count"}, "affected_documents": {"$ref": "#/$defs/count"},
+        "active": {
+          "type": "object", "required": ["error", "warning", "info", "experimental"],
+          "properties": {"error": {"$ref": "#/$defs/count"}, "warning": {"$ref": "#/$defs/count"}, "info": {"$ref": "#/$defs/count"}, "experimental": {"$ref": "#/$defs/count"}}
+        }
+      }
+    },
+    "coverage": {
+      "type": "object", "required": ["discovery", "rules"],
+      "properties": {
+        "discovery": {"type": "object", "required": ["status", "owner"], "properties": {"status": {"const": "not_assessed"}, "owner": {"const": "jekyll-agent-discovery"}}},
+        "rules": {"type": "object", "additionalProperties": {"$ref": "#/$defs/coverage"}}
+      }
+    },
+    "findings": {"type": "array", "items": {"$ref": "#/$defs/finding"}},
+    "diagnostics": {"type": "array", "items": {"type": "object", "required": ["code"], "properties": {"code": {"type": "string"}}}}
+  },
+  "$defs": {
+    "count": {"type": "integer", "minimum": 0},
+    "location": {"type": "object", "required": ["path", "line"], "properties": {"path": {"type": ["string", "null"]}, "line": {"type": ["integer", "null"], "minimum": 1}}},
+    "coverage": {
+      "type": "object", "required": ["candidate", "evaluated", "not_applicable", "skipped"],
+      "properties": {"candidate": {"$ref": "#/$defs/count"}, "evaluated": {"$ref": "#/$defs/count"}, "not_applicable": {"$ref": "#/$defs/count"}, "skipped": {"$ref": "#/$defs/count"}, "status": {"type": "string"}}
+    },
+    "finding": {
+      "type": "object",
+      "required": ["rule_id", "rule_version", "category", "severity", "evidence_level", "confidence", "message", "document_url", "source_path", "source_line", "rendered_location", "observation", "remediation", "evidence_urls", "related_locations", "fingerprint", "suppression"],
+      "properties": {
+        "rule_id": {"type": "string"}, "rule_version": {"type": "string"}, "category": {"type": "string"},
+        "severity": {"enum": ["error", "warning", "info", "experimental"]}, "evidence_level": {"enum": ["A", "B", "C", "D"]}, "confidence": {"enum": ["direct", "heuristic"]},
+        "message": {"type": "string"}, "document_url": {"type": ["string", "null"]}, "source_path": {"type": ["string", "null"]}, "source_line": {"type": ["integer", "null"], "minimum": 1},
+        "rendered_location": {"$ref": "#/$defs/location"}, "observation": {"type": "object"}, "remediation": {"type": "string"},
+        "evidence_urls": {"type": "array", "items": {"type": "string"}}, "related_locations": {"type": "array", "items": {"type": "object"}},
+        "fingerprint": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+        "suppression": {"type": ["object", "null"], "required": ["reason"], "properties": {"reason": {"type": "string", "minLength": 1}, "until": {"type": ["string", "null"]}}}
+      }
+    }
+  }
+}

data/script/benchmark.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Run from the gem checkout: ruby script/benchmark.rb [document_count]
+# Linux /proc reports whole-process peak RSS, a conservative upper bound on
+# analyzer memory. On macOS use /usr/bin/time -l ruby script/benchmark.rb.
+require "tmpdir"
+require "fileutils"
+require "json"
+require "rbconfig"
+require_relative "../lib/jekyll-agent-audit"
+
+module AuditBuildMeasurement
+  class << self
+    attr_accessor :seconds, :finished_at
+  end
+
+  def process
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    super
+  ensure
+    AuditBuildMeasurement.finished_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    AuditBuildMeasurement.seconds = AuditBuildMeasurement.finished_at - started
+  end
+end
+
+Jekyll::Site.prepend(AuditBuildMeasurement)
+count = Integer(ARGV.fetch(0, "1000"), 10)
+abort "document_count must be positive" unless count.positive?
+bytes_per_document = 50 * 1024
+
+Dir.mktmpdir("agent-audit-benchmark-") do |source|
+  File.write(File.join(source, "_config.yml"), "url: https://benchmark.example\n")
+  count.times do |number|
+    links = 20.times.map do |offset|
+      target = (number + offset + 1) % count
+      "<a href='/#{target.zero? ? 'index' : target}.html'>Page #{target}</a>"
+    end.join
+    shell = "<!doctype html><html><head><title>Page #{number}</title></head><body><main><h1>Page #{number}</h1>#{links}<p></p></main></body></html>"
+    padding = "x" * (bytes_per_document - shell.bytesize)
+    html = shell.sub("<p></p>", "<p>#{padding}</p>")
+    name = number.zero? ? "index" : number.to_s
+    File.write(File.join(source, "#{name}.html"), html)
+  end
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  report = Jekyll::AgentAudit::Runner.new("source" => source).run
+  finished = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  peak_kib = if File.file?("/proc/self/status")
+    File.read("/proc/self/status")[/^VmHWM:\s+(\d+)/, 1]&.to_i
+  end
+  puts JSON.pretty_generate(
+    ruby: RUBY_DESCRIPTION,
+    platform: RbConfig::CONFIG.fetch("host"),
+    jekyll: Jekyll::VERSION,
+    nokogiri: Nokogiri::VERSION,
+    documents: count,
+    html_bytes_per_document: bytes_per_document,
+    navigation_links_per_document: 20,
+    build_seconds: AuditBuildMeasurement.seconds,
+    analysis_and_report_seconds: AuditBuildMeasurement.finished_at && finished - AuditBuildMeasurement.finished_at,
+    total_seconds: finished - started,
+    whole_process_peak_rss_kib: peak_kib,
+    memory_measurement: peak_kib ? "Linux VmHWM; whole process including build" : "Unavailable in Ruby; use external time utility",
+    exit_code: report.exit_code,
+    summary: report.to_h.fetch("summary"),
+    diagnostics: report.to_h.fetch("diagnostics")
+  )
+  exit report.exit_code
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-agent-audit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lucian Ghinda
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+description: Offline, deterministic checks for links, identity, structure, and provenance
+  in Jekyll output.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- doc/Jekyll.md
+- doc/Jekyll/AgentAudit.md
+- doc/Jekyll/AgentAudit/BuildInventory.md
+- doc/Jekyll/AgentAudit/Configuration.md
+- doc/Jekyll/AgentAudit/ConfigurationError.md
+- doc/Jekyll/AgentAudit/Error.md
+- doc/Jekyll/AgentAudit/Extractor.md
+- doc/Jekyll/AgentAudit/Finding.md
+- doc/Jekyll/AgentAudit/InputError.md
+- doc/Jekyll/AgentAudit/LinkGraph.md
+- doc/Jekyll/AgentAudit/Registry.md
+- doc/Jekyll/AgentAudit/Report.md
+- doc/Jekyll/AgentAudit/ReportError.md
+- doc/Jekyll/AgentAudit/Reporters.md
+- doc/Jekyll/AgentAudit/Reporters/Console.md
+- doc/Jekyll/AgentAudit/Reporters/JSON.md
+- doc/Jekyll/AgentAudit/Rules.md
+- doc/Jekyll/AgentAudit/Rules/Provenance.md
+- doc/Jekyll/AgentAudit/Rules/Publication.md
+- doc/Jekyll/AgentAudit/Runner.md
+- doc/Jekyll/AgentAudit/UrlResolver.md
+- doc/Jekyll/Commands.md
+- doc/Jekyll/Commands/AgentAudit.md
+- doc/Jekyll/Commands/AgentAudit/CommandParser.md
+- doc/Jekyll/Commands/AgentAudit/ParserErrors.md
+- doc/README.md
+- doc/index.csv
+- docs/example-report.json
+- docs/implementation-plan.md
+- docs/limitations.md
+- docs/verification.md
+- lib/jekyll-agent-audit.rb
+- lib/jekyll/agent_audit/build_inventory.rb
+- lib/jekyll/agent_audit/command.rb
+- lib/jekyll/agent_audit/configuration.rb
+- lib/jekyll/agent_audit/errors.rb
+- lib/jekyll/agent_audit/extractor.rb
+- lib/jekyll/agent_audit/finding.rb
+- lib/jekyll/agent_audit/link_graph.rb
+- lib/jekyll/agent_audit/registry.rb
+- lib/jekyll/agent_audit/report.rb
+- lib/jekyll/agent_audit/reporters/console.rb
+- lib/jekyll/agent_audit/reporters/json.rb
+- lib/jekyll/agent_audit/rules/provenance.rb
+- lib/jekyll/agent_audit/rules/publication.rb
+- lib/jekyll/agent_audit/runner.rb
+- lib/jekyll/agent_audit/url_resolver.rb
+- lib/jekyll/agent_audit/version.rb
+- llms.txt
+- schema/report-1.0.json
+- script/benchmark.rb
+homepage: https://github.com/lucianghinda/jekyll-agent-audit
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/lucianghinda/jekyll-agent-audit
+  source_code_uri: https://github.com/lucianghinda/jekyll-agent-audit/tree/main
+  changelog_uri: https://github.com/lucianghinda/jekyll-agent-audit/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Audit rendered Jekyll publications for local quality defects
+test_files: []