{"id":18498341,"url":"https://github.com/softdevteam/depub","last_synced_at":"2025-04-09T00:31:14.637Z","repository":{"id":47359719,"uuid":"351891029","full_name":"softdevteam/depub","owner":"softdevteam","description":"Reduce the visibility of elements in a Rust code base","archived":false,"fork":false,"pushed_at":"2023-11-09T14:43:25.000Z","size":18,"stargazers_count":17,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-23T19:44:51.562Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softdevteam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","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}},"created_at":"2021-03-26T19:28:58.000Z","updated_at":"2024-02-10T15:30:20.000Z","dependencies_parsed_at":"2023-11-09T15:49:47.833Z","dependency_job_id":null,"html_url":"https://github.com/softdevteam/depub","commit_stats":{"total_commits":9,"total_committers":1,"mean_commits":9.0,"dds":0.0,"last_synced_commit":"81e22fcec8e964f8eeed8c76e23a649f08e69ced"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softdevteam%2Fdepub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softdevteam%2Fdepub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softdevteam%2Fdepub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softdevteam%2Fdepub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softdevteam","download_url":"https://codeload.github.com/softdevteam/depub/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247623007,"owners_count":20968574,"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","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":"2024-11-06T13:38:49.570Z","updated_at":"2025-04-09T00:31:09.628Z","avatar_url":"https://github.com/softdevteam.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# depub: minimise visibility\n\n## Overview\n\nWhen working on medium or large sized Rust code bases, it can be hard to know\nwhether the visibility of functions, structs, and so on are still at the\nminimum required. For example, sometimes functions that once needed to be `pub`\nnow only need to be `pub(crate)`, `pub(super)`, or simply private.\n\n`depub` minimises the visibility of such items in files passed to it, using a\nuser-specified command (e.g. `cargo check`) as an oracle to tell if its\nreduction of an item's visibility is valid or not. Note that `depub` is\nentirely guided by the oracle command: if the code it compiles happens not to\nuse part of an intentionally public interface, then `depub` is likely to\nsuggest reducing its visibility even though that's not what you want. The\nbroader the coverage of your oracle, the less this is an issue.\n\nIn essence, `depub` does a string search for `pub`, replaces it with `pub\ncrate` and sees if a test command still succeeds. If it does, it keeps that\nvisibility, otherwise it replaces with the original and tries the next item.\nNote that `depub` is inherently destructive: it overwrites files as it\noperates, so do not run it on source code that you do not want altered!\n\nThe list of visibilities that `depub` considers is, in order: `pub`,\n`pub(crate)`, `pub(super)`, and private (i.e. no `pub` keyword at all). `depub`\nsearches for `pub`/`pub(crate)`/`pub(super)` instances, reduces their\nvisibility by one level, and tries the oracle command. If it succeeds, it tries\nthe next lower level until private visibility has been reached.\n\nSince reducing the visibility of one item can enable other items' visibility to\nbe reduced, `depub` keeps running \"rounds\" until a fixed point has been\nreached. The maximum number of rounds is equal to the number of visible items\nin the code base, though in practise 2 or 3 rounds are likely to be all that is\nneeded.\n\n\n## Usage\n\n`depub`'s usage is as follows:\n\n```\ndepub -c \u003ccommand\u003e file_1 [... file_n]\n```\n\nwhere `\u003ccommand\u003e` is a string to be passed to `/bin/sh -c` for execution to\ndetermine whether the altered source code is still valid.\n\nTo reduce the visibility of a normal Rust project, `cd` to your Rust code base\nand execute:\n\n```\n$ find . -name \"*.rs\" | \\\n    xargs /path/to/depub -c \"cargo check \u0026\u0026 cargo check --test\"\n```\n\n`depub` informs you of its progress. After it is finished, `diff` your code\nbase, and accept those of its recommendations you think appropriate. Note that\n`depub` currently uses string search and replace, so it will merrily change the\nstring `pub` in a comment into `pub(crate)` -- you should not expect to accept\nits recommendations without at least a cursory check.\n\n\n## Using with libraries\n\nRunning `depub` on a library will tend to reduce all its intentionally `pub`\nfunctions to private visibility. You can weed these out manually after `depub`\nhas run, but this can be tedious, and may also have reduced the visibility of a\ncascade of other items.\n\nTo avoid this, use one or more users of the library in the oracle command as part\nof your oracle. Temporarily alter their `Cargo.toml` to point to the local\nversion of your libary and use a command such as:\n\n```\n$ find . -name \"*.rs\" | \\\n    xargs /path/to/depub -c \" \\\n      cargo check \u0026\u0026 cargo check --test \u0026\u0026 \\\n      cd /path/to/lib \u0026\u0026 cargo check \u0026\u0026 cargo check --test\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftdevteam%2Fdepub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftdevteam%2Fdepub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftdevteam%2Fdepub/lists"}