Yichus / Guides / Organization Lenses 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 Enable JavaScript to load the source and browser runner.
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) -> Bool Demo/Forum::member_String (items: List[String], target: String) -> Bool L0 used-above 3 also used from outside the focus by:
Demo/Forum::grant_plan
is_moderator (List[String], String) -> Bool Demo/Forum::is_moderator (roster: List[String], uid: String) -> Bool L1 used-above 3 also used from outside the focus by:
Demo/Forum::can_edit
Demo/Forum::grant_plan
can_see (String, List[String], Thread) -> Bool Demo/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], Strin g) -> 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[R esponse]
(String, List[String], _) -> Bool
(String, String, Int) -> List[Is sue]
(_, _) -> Response
_
(Db, Principal) -> IO[Response]
(Db, Principal, _) -> IO[Response]
(Db, Principal, _) -> IO[Response]
(Db, Principal, _) -> IO[Resp onse]
_
post_id_is Demo/Forum::post_id_is (post: Post, target: String) -> Bool L0 used-above 2
member_String Demo/Forum::member_String (items: List[String], target: String) -> Bool L0 used-above 3
roster_rows Demo/Forum::roster_rows forall a: *. Yichus/Transaction::TxTable[a, List[String]] L0 used-above 3
posts_rows Demo/Forum::posts_rows forall a: *. Yichus/Transaction::TxTable[a, Posts] L0 used-above 2
thread_rows Demo/Forum::thread_rows forall a: *. Yichus/Transaction::TxTable[a, Thread] L0 used-above 2
answer Demo/Forum::answer (status: Int, view: String, fields: List[(String, Yichus/Json::Json)]) -> Yichus/Service::Response L0 used-above 7
roster_key Demo/Forum::roster_key String L0 used-above 5
jstrings Demo/Forum::jstrings (items: List[String]) -> Yichus/Json::Json L0 used-above 2
render_post Demo/Forum::render_post (post: Post) -> Yichus/Json::Json L0 used-above 1
render_issue Demo/Forum::render_issue (issue: Issue) -> Yichus/Json::Json L0 used-above 1
jint Demo/Forum::jint (value: Int) -> Yichus/Json::Json L0 used-above 4
render_profile Demo/Forum::render_profile (profile: Profile) -> Yichus/Json::Json L0 used-above 2
posts_table Demo/Forum::posts_table (db: Yichus/Data::Db) -> Yichus/Data::Table[Posts] L0 used-above 1
threads_table Demo/Forum::threads_table (db: Yichus/Data::Db) -> Yichus/Data::Table[Thread] L0 used-above 3
profiles_table Demo/Forum::profiles_table (db: Yichus/Data::Db) -> Yichus/Data::Table[Profile] L0 used-above 2
moderators_table Demo/Forum::moderators_table (db: Yichus/Data::Db) -> Yichus/Data::Table[List[String]] L0 used-above 2
render_visibility Demo/Forum::render_visibility (v: Visibility) -> String L0 used-above 1
int_lt Demo/Forum::int_lt (a: Int, b: Int) -> Bool L0 used-above 2
int_gt Demo/Forum::int_gt (a: Int, b: Int) -> Bool L0 used-above 1
outcome_of Demo/Forum::outcome_of (issues: List[Issue], value: b) -> Demo/Forum::Outcome[b] L0 used-above 1
visibility_of Demo/Forum::visibility_of (members_only: Bool) -> Visibility L0 used-above 1
flag_if Demo/Forum::flag_if (cond: Bool, field: String, code: String, hint: String) -> List[Issue] L0 used-above 3
merge_issues Demo/Forum::merge_issues (batches: List[List[Issue]]) -> List[Issue] L0 used-above 2
is_blank Demo/Forum::is_blank (s: String) -> Bool L0 used-above 1
access_rules Demo/Forum::access_rules Yichus/Access::AccessSpec L0 used-above 0
forum_reading Demo/Forum::forum_reading Yichus/Organize::ReadingOrder L0 used-above 0
forum_shape Demo/Forum::forum_shape Yichus/Organize::FamilySpec L0 used-above 0
forum_systems Demo/Forum::forum_systems Yichus/Systems::SystemSpec L0 used-above 0
forum_tables Demo/Forum::forum_tables Yichus/Organize::FamilySpec L0 used-above 0
edited_since Demo/Forum::edited_since Yichus/Service::Response L1 used-above 1
find_post Demo/Forum::find_post (posts: List[Post], target: String) -> Option[Post] L1 used-above 1
replace_post Demo/Forum::replace_post (posts: List[Post], edited: Post) -> List[Post] L1 used-above 1
is_moderator Demo/Forum::is_moderator (roster: List[String], uid: String) -> Bool L1 used-above 3
forbid Demo/Forum::forbid (rule: String, message: String) -> Yichus/Service::Response L1 used-above 4
not_found Demo/Forum::not_found (what: String) -> Yichus/Service::Response L1 used-above 3
reject Demo/Forum::reject (issues: List[Issue]) -> Yichus/Service::Response L1 used-above 5
respond Demo/Forum::respond (view: String, fields: List[(String, Yichus/Json::Json)]) -> Yichus/Service::Response L1 used-above 6
render_thread Demo/Forum::render_thread (thread: Thread) -> Yichus/Json::Json L1 used-above 3
has_room Demo/Forum::has_room (thread: Thread, replies: List[Post]) -> Bool L1 used-above 1
check_max_len Demo/Forum::check_max_len (field: String, value: String, limit: Int) -> List[Issue] L1 used-above 1
check_blank Demo/Forum::check_blank (field: String, value: String) -> List[Issue] L1 used-above 1
grant_plan Demo/Forum::grant_plan (p: Yichus/Access::Principal, target: String) -> Yichus/Transaction::Txn[c, Yichus/Service::Response, List[String]] L2 used-above 1
can_edit Demo/Forum::can_edit (uid: String, roster: List[String], post: Post) -> Bool L2 used-above 1
can_see Demo/Forum::can_see (uid: String, roster: List[String], thread: Thread) -> Bool L2 used-above 4
thread_view Demo/Forum::thread_view (thread: Thread, posts: Posts) -> Yichus/Service::Response L2 used-above 2
members_only Demo/Forum::members_only Yichus/Service::Response L2 used-above 2
full_thread Demo/Forum::full_thread Yichus/Service::Response L2 used-above 1
get_profile Demo/Forum::get_profile (db: Yichus/Data::Db, p: Yichus/Access::Principal) -> Yichus/IO::IO[Yichus/Service::Response] L2 used-above 1
check_text Demo/Forum::check_text (field: String, value: String, limit: Int) -> List[Issue] L2 used-above 4
grant_outcome Demo/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
saved Demo/Forum::saved (outcome: Yichus/Transaction::Outcome[Yichus/Service::Response, (Thread, Posts)]) -> Yichus/Service::Response L3 used-above 2
put_profile Demo/Forum::put_profile (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: PutProfileRequest) -> Yichus/IO::IO[Yichus/Service::Response] L3 used-above 1
read_thread Demo/Forum::read_thread (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: ReadThreadRequest) -> Yichus/IO::IO[Yichus/Service::Response] L3 used-above 1
list_threads Demo/Forum::list_threads (db: Yichus/Data::Db, p: Yichus/Access::Principal) -> Yichus/IO::IO[Yichus/Service::Response] L3 used-above 1
thread_request_issues Demo/Forum::thread_request_issues (req: OpenThreadRequest) -> List[Issue] L3 used-above 1
edit_post Demo/Forum::edit_post (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: EditPostRequest) -> Yichus/IO::IO[Yichus/Service::Response] L4 used-above 1
grant_moderator Demo/Forum::grant_moderator (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: GrantModeratorRequest) -> Yichus/IO::IO[Yichus/Service::Response] L4 used-above 1
post_reply Demo/Forum::post_reply (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: ReplyRequest) -> Yichus/IO::IO[Yichus/Service::Response] L4 used-above 1
parse_thread Demo/Forum::parse_thread (uid: String, fresh_id: String, req: OpenThreadRequest) -> Demo/Forum::Outcome[Thread] L4 used-above 1
open_thread Demo/Forum::open_thread (db: Yichus/Data::Db, p: Yichus/Access::Principal, req: OpenThreadRequest) -> Yichus/IO::IO[Yichus/Service::Response] L5 used-above 1
forum_api Demo/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.