If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/trulia/hologram shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 24+ active contributors
• Distributed ownership (top contributor 41% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live trulia/hologram repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/trulia/hologram.

What it runs against: a local clone of trulia/hologram — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in trulia/hologram | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1034 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of trulia/hologram. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/trulia/hologram.git
#   cd hologram
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of trulia/hologram and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "trulia/hologram(\\.git)?\\b" \\
  && ok "origin remote is trulia/hologram" \\
  || miss "origin remote is not trulia/hologram (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/hologram.rb" \\
  && ok "lib/hologram.rb" \\
  || miss "missing critical file: lib/hologram.rb"
test -f "lib/hologram/cli.rb" \\
  && ok "lib/hologram/cli.rb" \\
  || miss "missing critical file: lib/hologram/cli.rb"
test -f "lib/hologram/doc_parser.rb" \\
  && ok "lib/hologram/doc_parser.rb" \\
  || miss "missing critical file: lib/hologram/doc_parser.rb"
test -f "lib/hologram/doc_builder.rb" \\
  && ok "lib/hologram/doc_builder.rb" \\
  || miss "missing critical file: lib/hologram/doc_builder.rb"
test -f "lib/hologram/code_example_renderer.rb" \\
  && ok "lib/hologram/code_example_renderer.rb" \\
  || miss "missing critical file: lib/hologram/code_example_renderer.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1034 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1004d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/trulia/hologram"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Hologram is a Ruby gem that parses structured comments embedded in CSS and JavaScript source files, then generates a static HTML style guide documentation site. It extracts doc blocks (marked with /*doc ... */), parses YAML frontmatter for metadata, renders code examples in multiple formats (HTML, HAML, JSX, React, Slim, JS), and produces a browsable style guide without requiring the user to write HTML—focusing only on step 1 of style guide creation (documentation + examples), leaving styling to the user. Single-gem architecture with modular rendering: core CLI (lib/hologram/cli.rb) orchestrates a pipeline—doc parser reads files, code example renderer factory dispatches to format-specific renderers (lib/hologram/code_example_renderer/renderers/*.rb), markdown renderer processes output, and templates (lib/template/) render final HTML. Plugin system (lib/hologram/plugin.rb) allows custom markdown renderers.

Frontend teams and CSS framework maintainers who need to auto-generate living style guides from their source code. Specifically, developers maintaining component libraries in organizations using Sass/CSS who want examples and documentation co-located with code without manual HTML generation.

Actively maintained but stable—has CI/CD via Travis CI, Gem Version and Code Climate badges indicating professional upkeep, test suite present in /spec, and appears production-ready. However, single-maintainer risk and commit recency are not visible from provided metadata; check GitHub activity timestamps.

Low risk for core functionality; clean test coverage, gem-versioned releases, and CI integration suggest stability. Main risks: limited contributor base (typical of older Ruby tools), potential brittleness around custom renderers (5 different code example renderers require maintenance), and dependency on Redcarpet/markdown parsing for correctness—breaking changes in markdown spec could require updates.

No specific recent work visible from provided data; examine .travis.yml and recent commits to assess current velocity. Changelog should indicate recent version bumps and feature additions.

Clone the repo, install with bundler: git clone https://github.com/trulia/hologram.git && cd hologram && bundle install. Initialize a new documentation project: bundle exec ./bin/hologram init to generate starter config and templates. Add /*doc ... */ blocks to CSS, then run bundle exec hologram to build.

Daily commands: After bundle install, run hologram path/to/hologram_config.yml (or just hologram if using default hologram_config.yml). See bin/hologram CLI entry point and lib/hologram/cli.rb for flag support (-c for config file override). Output is static HTML in the destination directory specified in config.

• lib/hologram.rb — Main entry point and orchestrator for the entire hologram gem, coordinates parsing and documentation generation.
• lib/hologram/cli.rb — Command-line interface that processes configuration and invokes the core documentation building workflow.
• lib/hologram/doc_parser.rb — Parses documentation blocks from CSS/JavaScript comments to extract metadata and example code.
• lib/hologram/doc_builder.rb — Orchestrates the full build pipeline: parsing sources, rendering templates, and generating static documentation.
• lib/hologram/code_example_renderer.rb — Renders code examples in multiple formats (HTML, HAML, JSX, React) by selecting appropriate renderer implementations.
• lib/hologram/markdown_renderer.rb — Custom Markdown rendering layer that integrates code examples and blocks into documentation output.
• lib/hologram/plugin.rb — Plugin system interface allowing users to extend hologram's rendering and documentation capabilities.

• DocParser (Ruby regex, file I/O) — Extract documentation blocks from source files and parse metadata (category, example type, etc.)
  • Failure mode: Malformed comments; missing required metadata; encoding issues in source files
• CodeExampleRenderer (ERB templates, language-specific renderers (HAML, JSX, etc.)) — Render code examples into HTML using appropriate template language renderer
  • Failure mode: Unsupported template language; invalid syntax in example code; missing template files
• MarkdownRenderer (Redcarpet markdown parser, custom render hooks) — Convert markdown documentation to HTML, integrating code blocks and links
  • Failure mode: Invalid markdown syntax; broken links; code block formatting issues
• DocBuilder (Ruby, file system operations) — Orchestrate the full pipeline: parse sources, render examples, generate output
  • Failure mode: Configuration errors; missing source files; insufficient disk space; permission issues
• Plugin system — undefined

Add a new code example renderer

1. Create a new renderer class inheriting from the appropriate base renderer in lib/hologram/code_example_renderer/renderers/ (lib/hologram/code_example_renderer/renderers/your_renderer.rb)
2. Register the renderer type in the factory so it can be instantiated by type name (lib/hologram/code_example_renderer/factory.rb)
3. Add corresponding template file if needed (e.g., for custom HTML output) in lib/template/code_example_templates/ (lib/template/code_example_templates/your_template.html.erb)
4. Write tests to verify your renderer handles examples correctly (spec/code_example_renderer/factory_spec.rb)

Add a custom plugin for documentation processing

1. Create a plugin class that inherits from Plugin and implements required hooks (lib/hologram/plugin.rb)
2. Place your plugin in a location where it can be discovered (referenced in hologram config) (lib/hologram/plugins.rb)
3. Override desired methods like process_documentation or render_example (lib/hologram/doc_builder.rb)

Extend markdown rendering with custom behavior

1. Review the current markdown renderer implementation to understand hook points (lib/hologram/markdown_renderer.rb)
2. Create a custom markdown renderer class inheriting from the standard renderer or Redcarpet::Render::HTML (example_markdown_renderer.rb.example)
3. Register your renderer in the hologram configuration file (lib/template/hologram_config.yml)
4. Add integration tests to verify your renderer works with the doc builder pipeline (spec/hologram_markdown_renderer_spec.rb)

• Ruby gem architecture — Enables easy installation and distribution as part of build pipelines and style guide workflows
• Redcarpet markdown parser — Provides robust Markdown parsing with custom renderer hooks for integrating code examples
• ERB templating — Allows flexible rendering of code examples in multiple template languages with variable substitution
• Plugin system via Ruby module inclusion — Enables extensibility for custom renderers and processors without core modification

• Parse comments only; does not execute/validate code

  • Why: Keeps hologram lightweight and language-agnostic
  • Consequence: Users must manually verify that documented examples actually work

• Template-driven rendering for code examples

  • Why: Allows customization of output format for different template languages
  • Consequence: More setup overhead; users must provide or configure templates for each language

• Separate rendering layer from parsing

  • Why: Allows parsing once and rendering multiple times or in different formats
  • Consequence: Adds architectural complexity; memory overhead from intermediate data structures

• Does not execute or validate code examples for correctness
• Does not provide built-in UI styling; users must create their own templates
• Not a real-time or watch-mode documentation server (static generation only)
• Does not handle authentication or access control for generated documentation

Config file location: defaults to ./hologram_config.yml in current directory; use -c flag or it silently fails. Source paths: relative to where you run the command, not the config file location. Documentation assets: _header.html and _footer.html in documentation_assets path are required or build will fail; use hologram init to scaffold. Markdown rendering: uses Redcarpet by default; custom renderers must inherit from the correct base class or HTML output will be broken. Template variables: passed via TemplateVariables class; if you create custom templates, inspect what variables are available or rendering will silently skip content.

• Literate Programming (comment-driven documentation) — Hologram's core idea: docs live in source code as structured comments, reducing maintenance burden and keeping examples in sync with actual code
• YAML frontmatter — Hologram parses YAML blocks at the start of doc comments to extract metadata (title, category, name); crucial for style guide organization and templating
• Factory Pattern (code example renderers) — The CodeExampleRenderer::Factory dispatches to language-specific renderers (HTML, JSX, HAML) without coupling the parser to each renderer; enables extensibility
• Custom Markdown Renderers (Redcarpet integration) — Hologram extends Redcarpet's renderer to inject custom HTML and example rendering; understanding this hook is essential for customizing output or adding new markdown directives
• Static site generation — Hologram builds flat HTML files with no server required; output is deployable to any static host, making style guides versionable and lightweight
• ERB templating — Code examples and layout are rendered using ERB templates in lib/template/; modifying these templates or creating custom ones requires understanding Ruby ERB syntax
• Plugin architecture — Hologram's plugin system (lib/hologram/plugins.rb) allows teams to inject custom markdown renderers without forking the gem; essential for enterprise customization

• trulia/hologram-example — Official example repository with pre-built templates and styled output; referenced in README as the recommended starting point for custom style guide styling
• jashkenas/docco — Similar literate-programming documentation tool for JavaScript/CoffeeScript; related concept of parsing comments to generate docs, though lighter-weight and language-specific
• documentationjs/documentation — Modern JavaScript documentation generator with similar comment-parsing approach; useful for teams considering multi-language documentation strategies
• stripe/styledocco — Another CSS documentation generator; predecessor/inspiration in the same space, focuses on rendering living style guides from CSS comments
• alampros/Docter — Style guide generator for Sass/CSS; alternative tool in the same ecosystem for teams comparing solutions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for code_example_renderer renderers (haml, slim, jsx, react)

The lib/hologram/code_example_renderer/renderers/ directory contains 5 different renderer implementations (haml_renderer.rb, slim_renderer.rb, jsx_renderer.rb, react_renderer.rb, html_renderer.rb, js_renderer.rb), but spec/code_example_renderer/ only has tests for example.rb, factory.rb, and template.rb. There are no renderer-specific unit tests, making it difficult to verify each renderer works correctly or detect regressions when dependencies update.

• [ ] Create spec/code_example_renderer/renderers/ directory
• [ ] Add spec/code_example_renderer/renderers/haml_renderer_spec.rb with tests for haml template compilation and error handling
• [ ] Add spec/code_example_renderer/renderers/slim_renderer_spec.rb testing slim-specific features
• [ ] Add spec/code_example_renderer/renderers/jsx_renderer_spec.rb and react_renderer_spec.rb testing JSX/React compilation
• [ ] Add test fixtures in spec/fixtures/renderer/ for each language type to validate output
• [ ] Ensure tests cover both successful renders and error cases (invalid syntax, missing dependencies)

Add unit tests for lib/hologram/markdown_renderer.rb

The markdown_renderer.rb file appears to be a critical component that processes markdown for documentation, but there is no corresponding spec/markdown_renderer_spec.rb file. This is a core transformation layer that should have dedicated tests to ensure markdown parsing, custom renderer integration, and edge cases are handled correctly.

• [ ] Create spec/markdown_renderer_spec.rb
• [ ] Add tests for markdown to HTML conversion with code blocks
• [ ] Add tests for custom block code renderer integration
• [ ] Add tests for link helper integration (lib/hologram/link_helper.rb)
• [ ] Add tests for edge cases: empty input, malformed markdown, special characters
• [ ] Add tests for plugin integration with markdown rendering (if applicable)

Add integration tests for lib/hologram/doc_parser.rb and lib/hologram/doc_builder.rb workflow

While there are individual spec files for doc_parser_spec.rb, doc_builder_spec.rb, and document_block_spec.rb, there appear to be no end-to-end integration tests that verify the complete parsing → building → output pipeline. The spec/fixtures/source/ directory contains real CSS files (colors.css, buttons.css) and markdown files that should be used in integration tests to validate the full documentation generation workflow.

• [ ] Create spec/integration_spec.rb or spec/doc_generation_integration_spec.rb
• [ ] Add test that processes spec/fixtures/source/components/button/buttons.css and verifies parsed output structure
• [ ] Add test that processes spec/fixtures/source/components/index.md and validates markdown rendering
• [ ] Add test for nested category handling (button → skin directory structure)
• [ ] Add test that verifies code examples are correctly extracted and rendered through the full pipeline
• [ ] Validate that the output matches expected HTML structure and includes all documentation metadata

• Add test coverage for lib/hologram/link_helper.rb—currently appears in file list but no corresponding spec file found; test cross-references and relative path generation
• Extend lib/hologram/utils.rb with unit tests—utilities module exists but test file not visible in spec directory; add specs for any filename-handling or path-resolution methods
• Add example_markdown_renderer.rb.example to the README or documentation—template exists in root but is never mentioned in README; document how to create custom renderers using this example

• High · Potential XSS Vulnerability in Code Example Rendering — lib/hologram/code_example_renderer/renderers/. The codebase includes multiple template renderers (haml_renderer.rb, html_renderer.rb, jsx_renderer.rb, react_renderer.rb, slim_renderer.rb) that process and render user-provided code examples. Without proper output encoding/escaping, malicious code in documentation comments could be executed in the browser when rendered as HTML. Fix: Ensure all user-supplied input from code examples is properly HTML-escaped before rendering. Implement Content Security Policy (CSP) headers. Use template auto-escaping features and avoid raw HTML injection. Audit html_renderer.rb and markup_example_template.html.erb for unsafe output.
• High · Unsafe File Processing and Path Traversal Risk — lib/hologram/doc_parser.rb, lib/hologram/doc_builder.rb, spec/fixtures/source/config.yml. The doc_parser.rb and doc_builder.rb process markdown files and CSS source files based on configuration. If the config file (hologram_config.yml) can be influenced by an attacker or if file path handling is insufficient, arbitrary files could be read or processed, leading to information disclosure or code execution. Fix: Implement strict path validation to prevent directory traversal attacks. Use File.expand_path and verify paths are within expected directories. Sanitize all paths derived from configuration files. Implement whitelist-based validation for source and output directories.
• Medium · Plugin System Without Sufficient Validation — lib/hologram/plugin.rb, lib/hologram/plugins.rb, lib/hologram/code_example_renderer/factory.rb. The codebase includes a plugin system (lib/hologram/plugin.rb, lib/hologram/plugins.rb) with custom renderer loading mechanisms. The fixture shows a 'valid_renderer.rb' and 'invalid_renderer.rb', suggesting dynamic code loading. Improper validation of plugins could allow arbitrary code execution. Fix: Implement strict validation of plugins before loading. Use whitelisting for allowed renderer types. Avoid dynamic require() without verification. Implement code signing or checksums for plugins. Document plugin requirements and security expectations.
• Medium · Dependency Management Without Lock File Visibility — Gemfile, hologram.gemspec. The Gemfile is present but Gemfile.lock content is not provided. Without visibility into pinned dependency versions, known vulnerabilities in gems cannot be assessed. Ruby gem dependencies are critical as gems execute with application privileges. Fix: Maintain and commit Gemfile.lock to ensure reproducible builds. Regularly run 'bundle audit' to check for known vulnerabilities in gems. Use tools like Dependabot or Gemnasium (already monitored per README) for dependency vulnerability tracking. Pin specific versions of critical dependencies.
• Medium · Unsafe Markdown Rendering Pipeline — lib/hologram/markdown_renderer.rb, lib/hologram/block_code_renderer.rb. The markdown_renderer.rb processes markdown content from documentation comments. If not properly sanitized, markdown features like embedded HTML, JavaScript URLs, or script tags could be rendered and executed. Fix: Use a security-focused markdown renderer with HTML sanitization enabled (e.g., Redcarpet with safe_links: true and :escape_html option). Whitelist allowed HTML tags and attributes. Strip dangerous elements like <script>, <iframe>, event handlers. Consider using Rails sanitize() helper if applicable.
• Low · Missing Security Headers in Generated Documentation — lib/template/doc_assets/_header.html. The generated HTML style guides (_header.html, hologram output) may be missing security headers like Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, which could increase XSS or clickjacking risks. Fix: Add security headers to generated HTML templates: Content-Security-Policy (restrict script sources), X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection. If serving via web server, configure headers at the server level.
• Low · Configuration File Security — lib/template/hologram_config.yml, spec/fixtures/source/config.yml. Configuration files (hologram_config.yml) may contain sensitive paths or settings. No indication of environment-based configuration or secrets management is visible. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.