Guide

Reading the organization lenses

A large program is hard to see whole. What concepts is it written in? What are its building blocks, and which are shared? Where does it copy logic instead of reusing it? Usually you learn this from someone who knows the code, then build your own picture over months.

Here we built lenses that answer each of those questions from the compiled program. Your agent runs them and tells you what they show, so ask it which lens fits your question. Each lens reports facts about the program; whether its organization is useful stays your call.

Code & run Experiment with the stock rule

The lenses and the question each answers

  • vocabulary: What concepts is it written in, and what plays which role?
  • stack: What are the building blocks, in the order a reader learns them?
  • conventions: How does it write each recurring shape, and where does it disagree with itself?
  • map: What is built from what?
  • abstractions: Which definitions act as shared rules or wrappers, and do declared rules hold?
  • structure: Where does each handle and record of functions come from, and what does each caller do with a shared result?
  • flow: What happens when it runs, against which backing system?
  • effects: What can each route do, and what surrounds each effect it reaches?
  • diff: What changed between two snapshots?
  • page: What are this program's measured properties?
  • aid: I cannot judge from the conventions page; where should I look?
  • layers: How do packages depend on each other? (layers, composition)

The stack, drawn

This is the stack lens around one forum rule, can_see, and the definitions it is built from.

L0 L1 L2 L3 L4 L5 L6 Demo/Forum::can_see -> Demo/Forum::is_moderator; 1 layer(s); keeps working on it Demo/Forum::is_moderator -> Demo/Forum::member_String; 1 layer(s); hands it back (List[String], String) -> Bool (List[String], String) -> Bool (String, List[String], _) -> Bool member_String(List[String], String) -> BoolDemo/Forum::member_String (items: List[String], target: String) -> Bool L0 used-above 3also used from outside the focus by: Demo/Forum::grant_plan is_moderator(List[String], String) -> BoolDemo/Forum::is_moderator (roster: List[String], uid: String) -> Bool L1 used-above 3also used from outside the focus by: Demo/Forum::can_edit Demo/Forum::grant_plan can_see(String, List[String], Thread) -> BoolDemo/Forum::can_see (uid: String, roster: List[String], thread: Thread) -> Bool L2 used-above 4 Demo/Forum::can_see -> Demo/Forum::member_String; 2 layer(s); keeps working on it stack picture forum.bosatsu blocks 3 of 61 layers 7 edges 3 of 112 layer skips 1 (1 reach under another block they use) families 2 focus on Demo/Forum::can_see: the blocks it is built from, transitively; 58 blocks and 109 edges outside its cone are not drawn each box gives its checked signature under its name, types bare (the whole signature on hover); a family's shape under a run is what its members share, with types as _; Demo/Forum::can_see is not the only way in: 2 blocks under it are also used by code this picture leaves out (a black corner at the top left of a box; those users on hover); arrows point to dependencies, and every wire's title names its endpoints; rows say what is built from what, not the order steps run; dashed boxes are framework declarations; a box widens with the wires that meet it; a wire says what the block above does with the result: blue, hands it back; grey, keeps working on it; a wire that skips layers is dotted and drawn over the boxes between; layout is a display choice, not a verdict; how to read it: organize-guide.html#stack-picture
The whole forum program as a stack
L0 L1 L2 L3 L4 L5 L6 Demo/Forum::can_edit -> Demo/Forum::is_moderator; 1 layer(s); keeps working on it Demo/Forum::can_see -> Demo/Forum::is_moderator; 1 layer(s); keeps working on it Demo/Forum::check_blank -> Demo/Forum::flag_if; 1 layer(s); hands it back Demo/Forum::check_blank -> Demo/Forum::is_blank; 1 layer(s); keeps working on it Demo/Forum::check_max_len -> Demo/Forum::flag_if; 1 layer(s); hands it back Demo/Forum::check_max_len -> Demo/Forum::int_gt; 1 layer(s); keeps working on it Demo/Forum::check_text -> Demo/Forum::check_blank; 1 layer(s); keeps working on it Demo/Forum::check_text -> Demo/Forum::check_max_len; 1 layer(s); keeps working on it Demo/Forum::edit_post -> Demo/Forum::saved; 1 layer(s); hands it back Demo/Forum::edited_since -> Demo/Forum::answer; 1 layer(s); hands it back Demo/Forum::find_post -> Demo/Forum::post_id_is; 1 layer(s); branches on it Demo/Forum::forbid -> Demo/Forum::answer; 1 layer(s); hands it back Demo/Forum::forum_api -> Demo/Forum::open_thread; 1 layer(s); refers to it without calling it Demo/Forum::full_thread -> Demo/Forum::reject; 1 layer(s); hands it back Demo/Forum::get_profile -> Demo/Forum::respond; 1 layer(s); hands it back Demo/Forum::grant_moderator -> Demo/Forum::grant_outcome; 1 layer(s); keeps working on it Demo/Forum::grant_outcome -> Demo/Forum::grant_plan; 1 layer(s); hands it back Demo/Forum::grant_plan -> Demo/Forum::forbid; 1 layer(s); keeps working on it Demo/Forum::grant_plan -> Demo/Forum::is_moderator; 1 layer(s); branches on it Demo/Forum::has_room -> Demo/Forum::int_lt; 1 layer(s); hands it back Demo/Forum::is_moderator -> Demo/Forum::member_String; 1 layer(s); hands it back Demo/Forum::list_threads -> Demo/Forum::can_see; 1 layer(s); hands it back Demo/Forum::members_only -> Demo/Forum::forbid; 1 layer(s); hands it back Demo/Forum::not_found -> Demo/Forum::answer; 1 layer(s); hands it back Demo/Forum::open_thread -> Demo/Forum::parse_thread; 1 layer(s); branches on it Demo/Forum::parse_thread -> Demo/Forum::thread_request_issues; 1 layer(s); keeps working on it Demo/Forum::post_reply -> Demo/Forum::saved; 1 layer(s); hands it back Demo/Forum::put_profile -> Demo/Forum::check_text; 1 layer(s); branches on it Demo/Forum::read_thread -> Demo/Forum::can_see; 1 layer(s); branches on it Demo/Forum::read_thread -> Demo/Forum::thread_view; 1 layer(s); hands it back Demo/Forum::reject -> Demo/Forum::answer; 1 layer(s); hands it back Demo/Forum::reject -> Demo/Forum::jint; 1 layer(s); keeps working on it Demo/Forum::reject -> Demo/Forum::render_issue; 1 layer(s); refers to it without calling it Demo/Forum::render_thread -> Demo/Forum::jint; 1 layer(s); keeps working on it Demo/Forum::render_thread -> Demo/Forum::jstrings; 1 layer(s); keeps working on it Demo/Forum::render_thread -> Demo/Forum::render_visibility; 1 layer(s); keeps working on it Demo/Forum::replace_post -> Demo/Forum::post_id_is; 1 layer(s); branches on it Demo/Forum::respond -> Demo/Forum::answer; 1 layer(s); hands it back Demo/Forum::saved -> Demo/Forum::thread_view; 1 layer(s); hands it back Demo/Forum::thread_request_issues -> Demo/Forum::check_text; 1 layer(s); hands it back Demo/Forum::thread_view -> Demo/Forum::render_thread; 1 layer(s); keeps working on it Demo/Forum::thread_view -> Demo/Forum::respond; 1 layer(s); hands it back (Db) -> Table[_] (Int, Int) -> Bool (List[String], String) -> Bool (List[_]) -> _ (String) -> _ (_) -> Json TxTable[v0][_] _ (List[Post], _) -> _[Post] (List[String], String) -> Bool (List[_]) -> _ (String) -> _ (String, String, Int) -> List[Issue] (_) -> Json (_, _) -> Response _ (Db, Principal) -> IO[Response] (String, List[String], _) -> Bool (String, String, Int) -> List[Issue] (_, _) -> Response _ (Db, Principal) -> IO[Response] (Db, Principal, _) -> IO[Response] (Db, Principal, _) -> IO[Response] (Db, Principal, _) -> IO[Response] _ post_id_isDemo/Forum::post_id_is (post: Post, target: String) -> Bool L0 used-above 2 member_StringDemo/Forum::member_String (items: List[String], target: String) -> Bool L0 used-above 3 roster_rowsDemo/Forum::roster_rows forall a: *. Yichus/Transaction::TxTable[a, List[String]] L0 used-above 3 posts_rowsDemo/Forum::posts_rows forall a: *. Yichus/Transaction::TxTable[a, Posts] L0 used-above 2 thread_rowsDemo/Forum::thread_rows forall a: *. Yichus/Transaction::TxTable[a, Thread] L0 used-above 2 answerDemo/Forum::answer (status: Int, view: String, fields: List[(String, Yichus/Json::Json)]) -> Yichus/Service::Response L0 used-above 7 roster_keyDemo/Forum::roster_key String L0 used-above 5 jstringsDemo/Forum::jstrings (items: List[String]) -> Yichus/Json::Json L0 used-above 2 render_postDemo/Forum::render_post (post: Post) -> Yichus/Json::Json L0 used-above 1 render_issueDemo/Forum::render_issue (issue: Issue) -> Yichus/Json::Json L0 used-above 1 jintDemo/Forum::jint (value: Int) -> Yichus/Json::Json L0 used-above 4 render_profileDemo/Forum::render_profile (profile: Profile) -> Yichus/Json::Json L0 used-above 2 posts_tableDemo/Forum::posts_table (db: Yichus/Data::Db) -> Yichus/Data::Table[Posts] L0 used-above 1 threads_tableDemo/Forum::threads_table (db: Yichus/Data::Db) -> Yichus/Data::Table[Thread] L0 used-above 3 profiles_tableDemo/Forum::profiles_table (db: Yichus/Data::Db) -> Yichus/Data::Table[Profile] L0 used-above 2 moderators_tableDemo/Forum::moderators_table (db: Yichus/Data::Db) -> Yichus/Data::Table[List[String]] L0 used-above 2 render_visibilityDemo/Forum::render_visibility (v: Visibility) -> String L0 used-above 1 int_ltDemo/Forum::int_lt (a: Int, b: Int) -> Bool L0 used-above 2 int_gtDemo/Forum::int_gt (a: Int, b: Int) -> Bool L0 used-above 1 outcome_ofDemo/Forum::outcome_of (issues: List[Issue], value: b) -> Demo/Forum::Outcome[b] L0 used-above 1 visibility_ofDemo/Forum::visibility_of (members_only: Bool) -> Visibility L0 used-above 1 flag_ifDemo/Forum::flag_if (cond: Bool, field: String, code: String, hint: String) -> List[Issue] L0 used-above 3 merge_issuesDemo/Forum::merge_issues (batches: List[List[Issue]]) -> List[Issue] L0 used-above 2 is_blankDemo/Forum::is_blank (s: String) -> Bool L0 used-above 1 access_rulesDemo/Forum::access_rules Yichus/Access::AccessSpec L0 used-above 0 forum_readingDemo/Forum::forum_reading Yichus/Organize::ReadingOrder L0 used-above 0 forum_shapeDemo/Forum::forum_shape Yichus/Organize::FamilySpec L0 used-above 0 forum_systemsDemo/Forum::forum_systems Yichus/Systems::SystemSpec L0 used-above 0 forum_tablesDemo/Forum::forum_tables Yichus/Organize::FamilySpec L0 used-above 0 edited_sinceDemo/Forum::edited_since Yichus/Service::Response L1 used-above 1 find_postDemo/Forum::find_post (posts: List[Post], target: String) -> Option[Post] L1 used-above 1 replace_postDemo/Forum::replace_post (posts: List[Post], edited: Post) -> List[Post] L1 used-above 1 is_moderatorDemo/Forum::is_moderator (roster: List[String], uid: String) -> Bool L1 used-above 3 forbidDemo/Forum::forbid (rule: String, message: String) -> Yichus/Service::Response L1 used-above 4 not_foundDemo/Forum::not_found (what: String) -> Yichus/Service::Response L1 used-above 3 rejectDemo/Forum::reject (issues: List[Issue]) -> Yichus/Service::Response L1 used-above 5 respondDemo/Forum::respond (view: String, fields: List[(String, Yichus/Json::Json)]) -> Yichus/Service::Response L1 used-above 6 render_threadDemo/Forum::render_thread (thread: Thread) -> Yichus/Json::Json L1 used-above 3 has_roomDemo/Forum::has_room (thread: Thread, replies: List[Post]) -> Bool L1 used-above 1 check_max_lenDemo/Forum::check_max_len (field: String, value: String, limit: Int) -> List[Issue] L1 used-above 1 check_blankDemo/Forum::check_blank (field: String, value: String) -> List[Issue] L1 used-above 1 grant_planDemo/Forum::grant_plan (p: Yichus/Access::Principal, target: String) -> Yichus/Transaction::Txn[c, Yichus/Service::Response, List[String]] L2 used-above 1 can_editDemo/Forum::can_edit (uid: String, roster: List[String], post: Post) -> Bool L2 used-above 1 can_seeDemo/Forum::can_see (uid: String, roster: List[String], thread: Thread) -> Bool L2 used-above 4 thread_viewDemo/Forum::thread_view (thread: Thread, posts: Posts) -> Yichus/Service::Response L2 used-above 2 members_onlyDemo/Forum::members_only Yichus/Service::Response L2 used-above 2 full_threadDemo/Forum::full_thread Yichus/Service::Response L2 used-above 1 get_profileDemo/Forum::get_profile (db: Yichus/Data::Db, p: Yichus/Access::Principal) -> Yichus/IO::IO[Yichus/Service::Response] L2 used-above 1 check_textDemo/Forum::check_text (field: String, value: String, limit: Int) -> List[Issue] L2 used-above 4 grant_outcomeDemo/Forum::grant_outcome (db: Yichus/Data::Db, p: Yichus/Access::Principal, target: String) -> Yichus/IO::IO[Yichus/Transaction::Outcome[Yichus/Service::Response, List[String]]] L3 used-above 1 savedDemo/Forum::saved (outcome: Yichus/Transaction::Outcome[Yichus/Service::Response, (Thread, Posts)]) -> Yichus/Service::Response L3 used-above 2 put_profileDemo/Forum::put_profile (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: PutProfileRequest) -> Yichus/IO::IO[Yichus/Service::Response] L3 used-above 1 read_threadDemo/Forum::read_thread (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: ReadThreadRequest) -> Yichus/IO::IO[Yichus/Service::Response] L3 used-above 1 list_threadsDemo/Forum::list_threads (db: Yichus/Data::Db, p: Yichus/Access::Principal) -> Yichus/IO::IO[Yichus/Service::Response] L3 used-above 1 thread_request_issuesDemo/Forum::thread_request_issues (req: OpenThreadRequest) -> List[Issue] L3 used-above 1 edit_postDemo/Forum::edit_post (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: EditPostRequest) -> Yichus/IO::IO[Yichus/Service::Response] L4 used-above 1 grant_moderatorDemo/Forum::grant_moderator (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: GrantModeratorRequest) -> Yichus/IO::IO[Yichus/Service::Response] L4 used-above 1 post_replyDemo/Forum::post_reply (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: ReplyRequest) -> Yichus/IO::IO[Yichus/Service::Response] L4 used-above 1 parse_threadDemo/Forum::parse_thread (uid: String, fresh_id: String, req: OpenThreadRequest) -> Demo/Forum::Outcome[Thread] L4 used-above 1 open_threadDemo/Forum::open_thread (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: OpenThreadRequest) -> Yichus/IO::IO[Yichus/Service::Response] L5 used-above 1 forum_apiDemo/Forum::forum_api Yichus/Service::ServiceDef L6 used-above 0 Demo/Forum::can_see -> Demo/Forum::member_String; 2 layer(s); keeps working on it Demo/Forum::check_text -> Demo/Forum::merge_issues; 2 layer(s); hands it back Demo/Forum::edit_post -> Demo/Forum::can_edit; 2 layer(s); branches on it Demo/Forum::edit_post -> Demo/Forum::can_see; 2 layer(s); branches on it Demo/Forum::edit_post -> Demo/Forum::check_text; 2 layer(s); branches on it Demo/Forum::edit_post -> Demo/Forum::edited_since; 3 layer(s); refers to it without calling it Demo/Forum::edit_post -> Demo/Forum::find_post; 3 layer(s); branches on it Demo/Forum::edit_post -> Demo/Forum::forbid; 3 layer(s); keeps working on it Demo/Forum::edit_post -> Demo/Forum::members_only; 2 layer(s); refers to it without calling it Demo/Forum::edit_post -> Demo/Forum::not_found; 3 layer(s); keeps working on it Demo/Forum::edit_post -> Demo/Forum::posts_rows; 4 layer(s); refers to it without calling it Demo/Forum::edit_post -> Demo/Forum::reject; 3 layer(s); hands it back Demo/Forum::edit_post -> Demo/Forum::replace_post; 3 layer(s); keeps working on it Demo/Forum::edit_post -> Demo/Forum::roster_key; 4 layer(s); refers to it without calling it Demo/Forum::edit_post -> Demo/Forum::roster_rows; 4 layer(s); refers to it without calling it Demo/Forum::edit_post -> Demo/Forum::thread_rows; 4 layer(s); refers to it without calling it Demo/Forum::forum_api -> Demo/Forum::edit_post; 2 layer(s); refers to it without calling it Demo/Forum::forum_api -> Demo/Forum::get_profile; 4 layer(s); refers to it without calling it Demo/Forum::forum_api -> Demo/Forum::grant_moderator; 2 layer(s); refers to it without calling it Demo/Forum::forum_api -> Demo/Forum::list_threads; 3 layer(s); refers to it without calling it Demo/Forum::forum_api -> Demo/Forum::post_reply; 2 layer(s); refers to it without calling it Demo/Forum::forum_api -> Demo/Forum::put_profile; 3 layer(s); refers to it without calling it Demo/Forum::forum_api -> Demo/Forum::read_thread; 3 layer(s); refers to it without calling it Demo/Forum::get_profile -> Demo/Forum::profiles_table; 2 layer(s); keeps working on it Demo/Forum::get_profile -> Demo/Forum::render_profile; 2 layer(s); refers to it without calling it Demo/Forum::grant_moderator -> Demo/Forum::answer; 4 layer(s); hands it back Demo/Forum::grant_moderator -> Demo/Forum::jstrings; 4 layer(s); keeps working on it Demo/Forum::grant_moderator -> Demo/Forum::respond; 3 layer(s); hands it back Demo/Forum::grant_plan -> Demo/Forum::member_String; 2 layer(s); branches on it Demo/Forum::grant_plan -> Demo/Forum::roster_key; 2 layer(s); refers to it without calling it Demo/Forum::grant_plan -> Demo/Forum::roster_rows; 2 layer(s); refers to it without calling it Demo/Forum::list_threads -> Demo/Forum::jint; 3 layer(s); keeps working on it Demo/Forum::list_threads -> Demo/Forum::moderators_table; 3 layer(s); keeps working on it Demo/Forum::list_threads -> Demo/Forum::render_thread; 2 layer(s); refers to it without calling it Demo/Forum::list_threads -> Demo/Forum::respond; 2 layer(s); hands it back Demo/Forum::list_threads -> Demo/Forum::roster_key; 3 layer(s); refers to it without calling it Demo/Forum::list_threads -> Demo/Forum::threads_table; 3 layer(s); keeps working on it Demo/Forum::open_thread -> Demo/Forum::reject; 4 layer(s); hands it back Demo/Forum::open_thread -> Demo/Forum::render_thread; 4 layer(s); keeps working on it Demo/Forum::open_thread -> Demo/Forum::respond; 4 layer(s); hands it back Demo/Forum::open_thread -> Demo/Forum::threads_table; 5 layer(s); keeps working on it Demo/Forum::parse_thread -> Demo/Forum::outcome_of; 4 layer(s); hands it back Demo/Forum::parse_thread -> Demo/Forum::visibility_of; 4 layer(s); keeps working on it Demo/Forum::post_reply -> Demo/Forum::can_see; 2 layer(s); branches on it Demo/Forum::post_reply -> Demo/Forum::check_text; 2 layer(s); branches on it Demo/Forum::post_reply -> Demo/Forum::full_thread; 2 layer(s); refers to it without calling it Demo/Forum::post_reply -> Demo/Forum::has_room; 3 layer(s); branches on it Demo/Forum::post_reply -> Demo/Forum::members_only; 2 layer(s); refers to it without calling it Demo/Forum::post_reply -> Demo/Forum::not_found; 3 layer(s); keeps working on it Demo/Forum::post_reply -> Demo/Forum::posts_rows; 4 layer(s); refers to it without calling it Demo/Forum::post_reply -> Demo/Forum::reject; 3 layer(s); hands it back Demo/Forum::post_reply -> Demo/Forum::roster_key; 4 layer(s); refers to it without calling it Demo/Forum::post_reply -> Demo/Forum::roster_rows; 4 layer(s); refers to it without calling it Demo/Forum::post_reply -> Demo/Forum::thread_rows; 4 layer(s); refers to it without calling it Demo/Forum::put_profile -> Demo/Forum::profiles_table; 3 layer(s); keeps working on it Demo/Forum::put_profile -> Demo/Forum::reject; 2 layer(s); hands it back Demo/Forum::put_profile -> Demo/Forum::render_profile; 3 layer(s); keeps working on it Demo/Forum::put_profile -> Demo/Forum::respond; 2 layer(s); hands it back Demo/Forum::read_thread -> Demo/Forum::forbid; 2 layer(s); hands it back Demo/Forum::read_thread -> Demo/Forum::moderators_table; 3 layer(s); keeps working on it Demo/Forum::read_thread -> Demo/Forum::not_found; 2 layer(s); hands it back Demo/Forum::read_thread -> Demo/Forum::posts_table; 3 layer(s); keeps working on it Demo/Forum::read_thread -> Demo/Forum::roster_key; 3 layer(s); refers to it without calling it Demo/Forum::read_thread -> Demo/Forum::threads_table; 3 layer(s); keeps working on it Demo/Forum::saved -> Demo/Forum::answer; 3 layer(s); hands it back Demo/Forum::thread_request_issues -> Demo/Forum::flag_if; 3 layer(s); keeps working on it Demo/Forum::thread_request_issues -> Demo/Forum::int_lt; 3 layer(s); keeps working on it Demo/Forum::thread_request_issues -> Demo/Forum::merge_issues; 3 layer(s); hands it back Demo/Forum::thread_view -> Demo/Forum::jint; 2 layer(s); keeps working on it Demo/Forum::thread_view -> Demo/Forum::render_post; 2 layer(s); refers to it without calling it stack picture forum.bosatsu blocks 61 layers 7 edges 112 layer skips 70 (10 reach under another block they use) families 14 arrows point to dependencies, and every wire's title names its endpoints; rows say what is built from what, not the order steps run; dashed boxes are framework declarations; a box widens with the wires that meet it; a wire says what the block above does with the result: red, branches on it; blue, hands it back; grey, keeps working on it; light grey, refers to it without calling it; a wire that skips layers is dotted and drawn over the boxes between; layout is a display choice, not a verdict; how to read it: organize-guide.html#stack-picture

Ask your agent about anything here; it has the detail.

Where this fits

What this is about: Lenses and Diagrams