{"id":31392254,"url":"https://github.com/nikcraftsapps/speclint","last_synced_at":"2026-05-07T09:35:33.547Z","repository":{"id":317079044,"uuid":"1059561754","full_name":"NikCraftsApps/SpecLint","owner":"NikCraftsApps","description":"Open-source linter for requirements and test coverage Automatically validates your specifications, risk coverage and test traceability across YAML, CSV, Markdown and JUnit XML. Generates CLI, Markdown and JSON reports – ideal for CI/CD and compliance.","archived":false,"fork":false,"pushed_at":"2025-09-28T16:53:09.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-28T18:28:47.721Z","etag":null,"topics":["csv","junit","lint","markdown","qa","requirements-engineering","traceability","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","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/NikCraftsApps.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-09-18T15:59:06.000Z","updated_at":"2025-09-28T16:53:12.000Z","dependencies_parsed_at":"2025-09-28T18:28:49.964Z","dependency_job_id":null,"html_url":"https://github.com/NikCraftsApps/SpecLint","commit_stats":null,"previous_names":["nikcraftsapps/speclint"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/NikCraftsApps/SpecLint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikCraftsApps%2FSpecLint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikCraftsApps%2FSpecLint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikCraftsApps%2FSpecLint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikCraftsApps%2FSpecLint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NikCraftsApps","download_url":"https://codeload.github.com/NikCraftsApps/SpecLint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikCraftsApps%2FSpecLint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277462598,"owners_count":25822036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-29T02:00:09.175Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["csv","junit","lint","markdown","qa","requirements-engineering","traceability","yaml"],"created_at":"2025-09-29T04:00:40.679Z","updated_at":"2025-09-29T04:02:21.931Z","avatar_url":"https://github.com/NikCraftsApps.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SpecLint\n\n**SpecLint** is an open-source linter and traceability checker for specifications, requirements and test coverage.  \nIt scans Markdown, YAML and CSV files (plus optional JUnit XML results) to automatically detect:\n\n- missing or inconsistent requirement/test links,\n- ID format violations,\n- coverage gaps by risk level,\n- ambiguous wording,\n- and more.\n\nIt outputs a clear CLI table and can also export Markdown/JSON reports — ideal for CI/CD pipelines and compliance documentation.\n\n---\n\n## Features\n\n- **Multi-format parsers**: YAML, CSV and Markdown requirements/test definitions.\n- **Traceability matrix**: automatically builds Requirement ↔ Test mappings.\n- **Risk-based coverage check**: configurable thresholds per risk level.\n- **JUnit XML integration**: verifies that declared tests actually run.\n- **Rules engine** with out-of-the-box checks:\n  - **ID format** (configurable regex),\n  - **Unique IDs**,\n  - **Sequence gaps** in IDs (warning),\n  - **Required fields**,\n  - **Missing test links**,\n  - **Orphan tests** (tests with no requirement),\n  - **Risk coverage minimum**,\n  - **Ambiguous terms** (PL/EN dictionaries),\n  - **JUnit existence**.\n- **Reporters**:\n  - CLI table (GitHub-style),\n  - Markdown summary,\n  - JSON for automated analysis.\n- **Exit code** = `1` if any `error` findings — perfect for CI/CD gates.\n\n---\n\n## 📦 Requirements\n\n- **Python 3.10+** (tested with Python 3.13)\n- `pip` to install dependencies\n\n---\n\n## Installation\n\nClone the repository and install in editable mode:\n\n```bash\ngit clone https://github.com/NikCraftsApps/SpecLint.git\ncd SpecLint\npython -m venv .venv\nsource .venv/bin/activate    # Windows: .venv\\Scripts\\Activate.ps1\npip install -e .\n````\n\nThis installs the `speclint` CLI on your PATH.\n\n---\n\n## Project Structure\n\n```\nsrc/speclint/\n  cli.py              # CLI entrypoint (Typer)\n  core/               # Config loader, discovery, data models\n  parsers/            # YAML, CSV, Markdown, JUnit XML parsers\n  rules/engine.py     # Rule engine implementing checks\n  reporters/emit.py   # CLI/Markdown/JSON outputs\n\nexamples/\n  .speclint.yml       # Default configuration file\n  requirements.yaml   # Sample YAML requirements\n  requirements.csv    # Sample CSV requirements\n  requirements.md     # Sample Markdown requirements\n  junit/              # Sample JUnit XML results\n```\n\n## Configuration\n\nSpecLint is driven by a YAML config file (default: `.speclint.yml`).\nKey sections:\n\n```yaml\ninclude:                # globs to include\nexclude:                # globs to exclude\nid_formats:             # regex for requirement/test IDs\nrules:                  # enable/disable rules, severities, thresholds\nreport:                 # output formats + directory\njunit:                  # optional JUnit XML paths\n```\n\nExample (from `examples/.speclint.yml`):\n\n```yaml\nid_formats:\n  requirement: \"^REQ-[0-9]{3,}$\"\n  test: \"^TC-[0-9]{3,}$\"\n\nrules:\n  UNIQUE_IDS: error\n  MISSING_TEST_LINKS: error\n  RISK_COVERAGE_MIN:\n    severity: error\n    min_tests:\n      high: 2\n      medium: 1\n      low: 1\n\nreport:\n  formats: [\"cli\", \"markdown\", \"json\"]\n  output_dir: \"build/speclint\"\n\njunit:\n  paths: [\"examples/junit/**/*.xml\"]\n```\n\nYou can tailor this to your project conventions.\n\n---\n\n## Input Formats\n\n### YAML Example\n\n```yaml\nrequirements:\n  - id: REQ-001\n    title: Login requires valid credentials\n    risk: high\n    tests: [TC-001, TC-002]\n```\n\n### CSV Example\n\n```csv\nid,title,risk,tests\nREQ-002,Password reset should be easy,medium,TC-003\n```\n\n### Markdown Example\n\n```md\n## REQ-003 User sessions expire after 15 minutes\nrisk: low\ntests: TC-004, TC-005\n```\n\n### JUnit XML (optional)\n\n```xml\n\u003ctestsuite name=\"auth\" tests=\"2\"\u003e\n  \u003ctestcase classname=\"login\" name=\"TC-001 login_ok\"/\u003e\n  \u003ctestcase classname=\"login\" name=\"TC-002 login_fail\"/\u003e\n\u003c/testsuite\u003e\n```\n\n---\n\n## Usage\n\nRun SpecLint against your config:\n\n```bash\nspeclint --config examples/.speclint.yml\n```\n\nOutput example:\n\n```\n| severity | rule                | message                                        |\n|----------|---------------------|------------------------------------------------|\n| error    | MISSING_TEST_LINKS  | REQ-021 has no linked tests                    |\n| warning  | SEQUENCE_GAPS       | Sequence gaps detected: ['4-9','11-19']        |\n...\nSummary: 2 errors, 5 warnings, 0 info\n```\n\nReports will be saved to `build/speclint/report.md` and `report.json`.\n\nExit code is `1` if any errors are present.\n\n---\n\n## Rules Overview (v0.1)\n\n| Rule ID                 | Severity (default) | Description                            |\n| ----------------------- | ------------------ | -------------------------------------- |\n| `REQ_ID_FORMAT`         | error              | Requirement ID matches regex           |\n| `TEST_ID_FORMAT`        | warning            | Test ID matches regex                  |\n| `UNIQUE_IDS`            | error              | Duplicate IDs detected                 |\n| `SEQUENCE_GAPS`         | warning            | Numeric gaps in requirement IDs        |\n| `REQUIRED_FIELDS`       | error              | Missing mandatory fields               |\n| `MISSING_TEST_LINKS`    | error              | Requirement with no linked tests       |\n| `ORPHAN_TESTS`          | warning            | Tests not linked to any requirement    |\n| `RISK_COVERAGE_MIN`     | error              | Test count below minimum per risk      |\n| `AMBIGUOUS_TERMS`       | warning            | “should”, “quickly”, “intuicyjne” etc. |\n| `TEST_MISSING_IN_JUNIT` | warning            | Declared tests not found in JUnit XML  |\n\n---\n\n## Reports\n\nBy default:\n\n* **CLI table** — printed to stdout.\n* **Markdown report** — `build/speclint/report.md` for upload to PRs.\n* **JSON report** — `build/speclint/report.json` for automated parsing.\n\n---\n\n## Contributing\n\n1. Fork and clone the repo.\n2. Create a virtual environment and install in editable mode:\n\n   ```bash\n   python -m venv .venv\n   source .venv/bin/activate\n   pip install -e .[dev]\n   ```\n3. Run tests with `pytest`.\n4. Submit pull requests with clear descriptions.\n\nWe welcome new rules, parsers and reporter formats.\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n## Acknowledgements\n\nSpecLint takes inspiration from tools like ESLint, Pylint and Stylelint — but for requirements engineering and QA traceability.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikcraftsapps%2Fspeclint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikcraftsapps%2Fspeclint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikcraftsapps%2Fspeclint/lists"}