{"id":32167142,"url":"https://github.com/kitt-ex/scapa","last_synced_at":"2025-12-11T23:37:37.925Z","repository":{"id":39648092,"uuid":"486312811","full_name":"kitt-ex/scapa","owner":"kitt-ex","description":"A static code analysis tool focused on keeping documentation up to date","archived":false,"fork":false,"pushed_at":"2023-03-14T15:02:11.000Z","size":74,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-21T15:34:08.527Z","etag":null,"topics":["ci","cicd","documentation","elixir"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/scapa/","language":"Elixir","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/kitt-ex.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2022-04-27T18:45:07.000Z","updated_at":"2023-03-06T15:44:44.000Z","dependencies_parsed_at":"2023-07-13T08:29:17.898Z","dependency_job_id":null,"html_url":"https://github.com/kitt-ex/scapa","commit_stats":null,"previous_names":["brunvez/scapa"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kitt-ex/scapa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitt-ex%2Fscapa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitt-ex%2Fscapa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitt-ex%2Fscapa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitt-ex%2Fscapa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitt-ex","download_url":"https://codeload.github.com/kitt-ex/scapa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitt-ex%2Fscapa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27672177,"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-12-11T02:00:11.302Z","response_time":56,"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":["ci","cicd","documentation","elixir"],"created_at":"2025-10-21T15:23:33.219Z","updated_at":"2025-12-11T23:37:37.850Z","avatar_url":"https://github.com/kitt-ex.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Scapa\n\n![master](https://github.com/brunvez/scapa/workflows/tests/badge.svg?branch=master)\n[![Coverage Status](https://coveralls.io/repos/github/brunvez/scapa/badge.svg?branch=master)](https://coveralls.io/github/brunvez/scapa?branch=master)\n\n**A static code analysis tool focused on keeping documentation up to date with the related code.**\n\n## Installation\n\nThe package can be installed\nby adding `scapa` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:scapa, \"~\u003e 0.1.0\", only: [:dev, :test], runtime: false}\n  ]\nend\n```\n\n## Usage\n\nThe purpose of `Scapa` is to let you know when documentation needs to be updated. It does so\nby keeping track of how a function signature changes. For example, if there's a function `get_user` defined as\n\n```elixir\n@doc \"Gets a user from a user_id\"\ndef get_user(user_id) do\n  # ...\nend\n```\n\nWhich then changes to\n\n```elixir\n@doc \"Gets a user from a user_id\"\ndef get_user(query) do\n  # ...\nend\n```\n\n`Scapa` will prompt you to revise the documentation of that function since the signature has changed.\n\nThe way it tracks what needs to be updated is by assigning versions based on the signature. These versions can be stored in two places, each\nwith their own trade offs.\n\n### Tags\n\nThe first way to store the versions is by using `@doc` tags with custom attributes. This keeps the version above the function definition:\n\n```elixir\n@doc \"Gets a user from a user_id\"\n@doc version: \"ODgwNzQxMg\"\ndef get_user(user_id) do\n  # ...\nend\n```\n\nThis setting is great to avoid merge conflicts, keep the data close to the source and be reminded of the documentation changes that need to happen. On\nthe other hand though, it can make your code \"dirty\" by adding metadata that could get in the way.\n\n### Versions file\n\nThe alternation to tags is keeping a versions file (by default `priv/doc_versions.ex`) which contains the versions of all the functions in the entire project.\nAssuming our example function belongs to the `User` module, the file would look like this:\n\n```elixir\n# priv/doc_versions.ex\n%{\n  # ...\n  {User, :get_user, 1} =\u003e \"ODgwNzQxMg\",\n  # ...\n}\n```\n\nIn this way we keep the metadata away from our code, but this can cause more merge conflicts (which we mitigate by ordering the keys alphabetically). It could also\nbecome a just a file that gets automatically updated and not really payed attention to.\n\nIt's up to your team to decide which version to use based on your preferences and project needs.\n\n### Running Scapa\n\nIn order for `Scapa` to actually do something you'll want to run a mix task. The two tasks provided are:\n\n- `scapa`\n- `scapa.gen.versions`\n\nAfter you install scapa ideally you want to configure it and run `mix scapa.gen.versions` which will scan your code for the first time, determine which functions\nneed to be versioned and then store those versions.\n\nWhen working on a feature or in the CI environment you probably want to run `mix scapa`. This task will give you a detailed output of which functions need to be\nversioned and which functions have changed so you may revise the documentation for any outdated content. Something like this:\n\n```\n...\nFile lib/your_project/config.ex is up to date.\nFile lib/your_project/user.ex has a function with a missing or outdated version number.\nlib/your_project/user.ex:16: User.get_user/1 doc version is outdated. Current docs are:\n  Gets a user from a user_id\n  Check if the documentation is up to date and then update the doc version to:\n  @doc version: \"ODgwNzQxMg\"\n  def get_user(query) do\n    # ...\n```\n\nAfter that you can either update the version manually or run `mix scapa.gen.versions` again so the tool does it for you.\n\n\n## Configuration\n\n`Scapa` allows configurations through the `.scapa.exs` file. This file must contain a keyword list with the options listed below\n\n- **include:** A list or a singular glob expression of the files you wish `Scapa` to keep track of. Defaults to `\"lib/**/*.ex\"`\n- **store:** Where the function signature versions will be stored. The possible values are `:tags`, `:file` or `{:file, file_path}`. Defaults to `:tags`\n\nThe default configuration looks like this\n\n```elixir\n# .scapa.exs\n[\n  include: \"lib/**/*.ex\",\n  store: :tags\n]\n```\n\nYou can run `mix scapa.gen.config` to have this file created automatically for you.\n\n## Contributing\n1. Fork it!\n1. Create your feature branch (`git checkout -b my-new-feature`)\n1. Fetch (`mix deps.get`)\n1. Make sure everything works correctly (`mix test`)\n1. Implement your feature!\n1. Commit your changes (git commit -am 'Add some feature')\n1. Push to the branch (git push origin my-new-feature)\n1. Create new Pull Request\n\n## License\nScapa is released under the MIT License. See the LICENSE file for further details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitt-ex%2Fscapa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitt-ex%2Fscapa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitt-ex%2Fscapa/lists"}