{"id":33914916,"url":"https://github.com/ducks/yaml-janitor","last_synced_at":"2026-04-09T00:02:24.554Z","repository":{"id":323973354,"uuid":"1095454794","full_name":"ducks/yaml-janitor","owner":"ducks","description":"YAML linter that preserves comments using psych-pure. Detects issues and fixes formatting without destroying documentation.","archived":false,"fork":false,"pushed_at":"2026-04-06T17:36:47.000Z","size":49,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T19:23:57.025Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ducks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-13T04:27:46.000Z","updated_at":"2026-04-06T17:36:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ducks/yaml-janitor","commit_stats":null,"previous_names":["ducks/yaml-janitor"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/ducks/yaml-janitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fyaml-janitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fyaml-janitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fyaml-janitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fyaml-janitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ducks","download_url":"https://codeload.github.com/ducks/yaml-janitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fyaml-janitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31579058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-12T06:44:10.114Z","updated_at":"2026-04-09T00:02:24.549Z","avatar_url":"https://github.com/ducks.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# yaml-janitor\n\nA YAML linter and formatter built on psych-pure that preserves comments while\nformatting files.\n\n## Why?\n\nTraditional YAML tools destroy comments when editing files. yaml-janitor uses\npsych-pure's comment-preserving parser to format YAML files without losing\nvaluable documentation.\n\n## Installation\n\n```bash\ngem install yaml-janitor\n```\n\nOr in your Gemfile:\n\n```ruby\ngem 'yaml-janitor'\n```\n\n## Usage\n\n### CLI\n\nCheck a single file (reports formatting issues):\n```bash\nyaml-janitor config.yml\n```\n\nCheck all YAML files in a directory:\n```bash\nyaml-janitor containers/\n```\n\nFormat files in-place:\n```bash\nyaml-janitor --fix config.yml\n```\n\nFormat with custom indentation:\n```bash\nyaml-janitor --fix --indentation 4 config.yml\n```\n\nShow diff of formatting changes:\n```bash\nyaml-janitor --diff config.yml\n```\n\n### Ruby API\n\n```ruby\nrequire 'yaml_janitor'\n\n# Check a file for formatting issues\nresult = YamlJanitor.lint_file(\"config.yml\")\nresult[:violations].each do |violation|\n  puts \"#{violation.file}: #{violation.message}\"\nend\n\n# Format a file in-place\nresult = YamlJanitor.format_file(\"config.yml\")\nif result[:fixed]\n  puts \"Formatted!\"\nend\n\n# Format a string\nyaml_string = File.read(\"config.yml\")\nresult = YamlJanitor.format(yaml_string)\nputs result[:output]\n\n# Use custom config\nconfig = YamlJanitor::Config.new(overrides: { indentation: 4 })\nlinter = YamlJanitor::Linter.new(config: config)\nresult = linter.lint_file(\"config.yml\", fix: true)\n```\n\n## Configuration\n\nCreate a `.yaml-janitor.yml` file in your project root:\n\n```yaml\n# Formatting options\nindentation: 2\nline_width: 80\n```\n\n### Configuration Options\n\n- `indentation`: Number of spaces for indentation (default: 2)\n- `line_width`: Maximum line width before wrapping (default: 80, not yet implemented)\n\n### Command Line Overrides\n\n```bash\n# Override config file settings\nyaml-janitor --indentation 4 --line-width 100 config.yml\n\n# Use a specific config file\nyaml-janitor --config production.yml containers/\n```\n\n## How It Works\n\nyaml-janitor uses a two-phase approach:\n\n1. **Parse**: Load YAML with psych-pure, preserving comment metadata\n2. **Format**: Emit YAML using custom formatter with full control over style\n\nWhen you run `yaml-janitor --fix`, it:\n- Loads your YAML file with comments preserved\n- Formats it according to configuration (indentation, line width, etc.)\n- Verifies semantics are unchanged (paranoid mode)\n- Writes the formatted output back to the file\n\n### Formatting Rules\n\nThe formatter enforces:\n- **Consistent indentation** (default: 2 spaces)\n- **Block style for arrays and mappings** (never flow style like `[a, b, c]`)\n- **Normalized string quoting** (only quotes when necessary)\n- **Proper line breaks** between top-level keys\n\n### Comment Preservation\n\nComments are preserved in most locations:\n- Leading comments (before keys)\n- Trailing comments (after values)\n- Mid-document comments (between keys)\n\nKnown limitation: Inline comments on mapping keys (e.g., `servers: # comment`)\nmay be repositioned as leading comments on the next key due to psych-pure's\ncomment tracking.\n\n### Safety\n\nAll formatting changes are verified with paranoid mode: the original YAML and\nformatted YAML are both parsed and compared for semantic equality. If they\ndiffer, the tool errors out instead of writing the file.\n\n## Development\n\n### Running Tests\n\n```bash\n# Run integration tests\nruby -I lib test/integration_test.rb\n\n# Or with rake (if configured)\nbundle install\nbundle exec rake test\n```\n\n### Test Coverage\n\nIntegration tests verify:\n- Comment preservation during formatting\n- Indentation normalization\n- Paranoid mode (semantic verification)\n- Config loading and overrides\n- Parse error detection\n- Idempotent formatting (clean files pass without violations)\n\n## Background\n\nBuilt on top of Kevin Newton's psych-pure gem, which provides a pure Ruby YAML\nparser with comment preservation.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fducks%2Fyaml-janitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fducks%2Fyaml-janitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fducks%2Fyaml-janitor/lists"}