19 KiB
19 KiB
Relations
Recording an edge between two tickets, and drawing the block that reports them.
Relating Tickets
- The Relations section is
relate's alone.RELATIONSis in the section table but deliberately out ofsection_args, sosetandappendcannot reach it: a relation names a target that has to be resolved to a uuid first, and a prose flag would let an unresolvable line into the one section that is read back by machine. Same rule as Owner and Status, one field one writer relate --clear <kind> <target>is the removal, and it is onrelaterather than onsetfor the same reason the section is absent fromsection_args: one writer owns both directions, the waychownowns setting an owner and clearing one. It names the target and not just the kind, because a ticket can hold several relations of one kind and emptying all of them is not what anybody is asking for. That is also why it is not spelled likeset --clear, which names a field and empties the whole of it- The two values are one flag, so clap cannot type them apart.
num_args = 2is per occurrence, which is what makes an odd number a usage error and every chunk a full pair;RelateArgs::clearedsplits the pairs and parses the kind, so a bad kind is refused before the ticket is resolved. It exits 1 rather than clap's 2, which is the price of a two-value flag and the reasonRelationKind::parse_valuenames the three in its message - Both spellings of the kind are accepted,
blocked-byfrom the flag andblocked byfrom the label. Both are in front of the reader: the flag is what recorded the relation and the label is whatshowprints and what the file stores, so refusing the printed form would be a trap for anyone clearing a row they just read.RelationKind::flagis a match rather thanlabel().replace(' ', "-"), so the flag, the--clearvalue and the completion list cannot drift apart find_relationsearches the ticket's own edges before the board, and that order is the feature. A dangling edge is the case most likely to need clearing, and no search of the board can reach a target whose ticket is gone, so the id-prefix tier over the stored targets is the only one that finds it.MIN_ID_SEARCHis the floorresolve_inputs under its own id tier and the comparison is case insensitive for the same reason. Two stored targets under one prefix name the candidates rather than guessing, which is what an ambiguous ticket search already does- An edge the ticket does not hold reports no change; a target naming nothing at all is an error. The two are different facts: the first is the state the caller asked for, and the second is a typo that reporting no change would swallow. The resolver's own reason is carried through, so an ambiguous search says so instead of being reported as nothing found
- Recording and clearing the same relation in one call is refused, and the check runs on what was asked for.
itemsdrops the additions already in the file, so comparing against that would let--blocked-by X --clear blocked-by Xquietly remove an existing X.requestedis the full list for exactly that reason. The refusal isset --clear's: nothing is written rather than one direction silently winning - Removals rewrite the section and additions are appended to the result, in that order. Two passes rather than one rebuild, so a call with no
--cleartakes exactly the path it always took andappend_section_bodygoes on deciding where a new line lands. Rewriting from the parsed relations is lossless because a line that is not a relation is already an error. The last edge leavesclear_section_body's placeholder, which is the lineappendtreats as no content, so the nextrelatereplaces it instead of writing under it - A relation is not logged, either direction.
relatewrites no history entry and neither does--clear, which keeps the two consistent; per the history rule, an edge that matters enough to explain gets a comment. Do not add an entry for the removal alone: a log that recorded only the destructive half would read as though the additions had never happened adddoes not write the section. The plan on 4179958 asked for it in the ticket writer; it is out on purpose. A_No relations._block in every new ticket is noise in everyshow, and the insertion path has to exist regardless for every ticket written before the section did, so leaving it out means one path that is always exercised rather than two- The full uuid is stored, not the seven characters
lsprints. It resolves without a scan and cannot turn ambiguous as the board grows.showrenders the short id and the target's title instead: the file is the machine's copy, the output is the reader's - One direction is stored and the inverse is derived.
blocked bygoes on the gated ticket rather thanblockson the blocker, because the gated ticket is the one whose move is refused and whose author knows about the dependency.relates tois symmetric and is written once, on whichever end the caller ran it from.RelationIndex::inboundfinds the far end by scanning, which is what keepsrelatea single-file write - A derived row that reads exactly like a stored one is dropped, and the stored one is kept. Both ends of a symmetric relation could hold a line, since nothing stopped it until 03bdc76, and the block then drew the same neighbour twice under the same label. The stored row survives because it is the line
relate --clearcan address; the derived one is on a file this ticket does not own - The dedupe keys on the label and the target, not the kind and the target. Two tickets each blocking the other is two facts and the block says both,
blocked byfrom this end andblocksfrom the other; keying on the kind would fold them into one row and lose half of what the ticket says. Only a symmetric kind can collide with its own stored line, andRelationKind::is_symmetricderives that fromlabel() == inverse_label()rather than namingRelatesTo, so a kind added later answers by construction relatealso refuses to store the mirror, which is the other half of the same fix. The dedupe repairs a board that already holds both directions; the refusal stops it recurring.mirroredincmd_relatereads the target's own relations and reports no change, gated onis_symmetricbecause a target holdingblocked by <this>is a cycle rather than a duplicate. 4179958 decidedrelates tois written once and not onto both files; for six months nothing enforced it- A symmetric edge is cleared from the end that stores it. With both ends holding a line,
--clearon one leaves the other's, which then draws as the derived row: correct, since the far end still asserts the relation, and the reason the dedupe keeps the stored row rather than the derived one - A line in the section that is not a relation is an error naming the ticket, not a line quietly dropped. Nothing but
relatewrites there, so a bad line means a hand-edited file. The TUI is the deliberate exception:detail_offalls back to no block, since one corrupt ticket must not take the whole board down - The block is built outside
content_trimand passed in. Half of it comes from other tickets andcontent_trimhas only the body. It is spliced over the stored lines where the file has the section, and injected ahead of the metadata where it does not, because a ticket that is only pointed at has no section of its own and still has relations to show ensure_sectioninserts againstSECTION_ORDER, before the first following section that is actually in the file, and adds no blank line that was not already there. A handwritten## Notesbetween the plan and the metadata therefore keeps its place, and Metadata is in that list as an anchor rather than as something anything appends to- The blocker check runs on every move, after the already-in-that-status return and behind
force. An open blocker is a reason not to start and a reason not to finish, and one rule is easier to hold than a table of which transitions care. A move to the status the ticket is already in is not a move, so it is not refused.-fnow bypasses three rules, which is the right home for it: each one is a deliberate override of something the board would otherwise keep true - A blocker that is not on the board warns and allows the move. Refusing would wedge the ticket with no way out but
-f, and a uuid nothing carries is a bookkeeping fault rather than a dependency. The refusal names every open blocker, since clearing the one that happened to be printed would leave the ticket blocked - Left out on purpose: removing a relation, which 4179958 assigns to 74904dc. The blocked marker on the card landed in b8ce18c, and it cost no scan of the board: the blockers ride along on the read that already builds the cards. See The Board View
The Relations Block
- One builder, two painters.
relation_rowsdecides which edges there are, what they are called and which direction comes first;relation_cellsdecides the layout, the mark and the colours;paint_cellsturns cells into escapes for the CLI andspan_ofturns the same cells into ratatui spans for the board. Two builders producing one block in two shapes is a pair free to disagree about ordering or padding, which is what this shape exists to prevent Cellis the unit both renderers take: a run of text, the colour it is drawn in and the modifier it carries,Nonefor the default foreground and for text drawn as it stands. The same trick as the palette itself, whereColor::ansi()andFrom<Color> for ratatui::style::Colorkeep one colour from existing for one renderer and not the other, andModifieris that trick a second time for the styles that are not coloursModifieris the first style on a cell that is not a colour, and it is an enum with one variant for the reason the palette is one:Modifier::ansi()is SGR 9 andFrom<Modifier> for ratatui::style::ModifierisCROSSED_OUT, so a style that exists for one renderer and not the other is a compile error. Bold is not in it, because bold rides insideColor::Magenta.ansi()andspan_fromadds it back from the colour alone; a second modifier goes here beside the strike. It is independent of the colour, so a struck run keeps whatever colour its column already gave itCell::struckis a builder, not a third constructor. The strike is decided a whole row at a time and the cells of that row are built by the layout that already chose their colours, sorelation_cellsmaps it over the row it has just finished rather than threading the decision through every cell it makesRESETis a constant both writers share.paintopens a colour andpaint_cellmay open a modifier ahead of one, and a reset that only knew about the colour would leave the strike running to the end of the lineBody::push_cellmerges on the whole style, not the colour alone. Nothing outside the relations block carries a modifier today, and a merge keyed on the colour would silently strike a plain run through the moment one didreference_cellsis the one spelling of a cross reference. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown. There was areference_cellbeside it that painted the cells for the CLI; once the whole body became cells the Campaign field stopped needing a string and it was the last caller, so it is gone- A row carries two marks, kind then status: what sort of edge this is, then how far the ticket at the other end has got.
blocked by × ◐ (6ce2c47) Title. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished - The status went through one bad shape first. It was a rising bar,
▁▄▆█, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer - Both directions of a kind carry one mark.
blocked byandblocksare the same edge read from two ends, and the label is what says which end you are on.both_directions_of_a_kind_carry_one_markpins it ×isBLOCKED_MARK, the same constant a held-up card draws, in the same brightred. On a card it says this ticket is held up and in the block it says this edge is what holds one, which is one word, so one glyph and one definition. It lives inutil.rsfor that reason, not intui.rswhere the card is- The kind marks stay out of the priority vocabulary, which owns
●◐○·, andno_relation_mark_is_a_priority_glyphpins that against every level. They are the arrows the footer already draws, so they render wherever it does - The status marks are those very circles, and what keeps them from reading as a level is width: the meter is always two cells and a status mark is one.
the_status_mark_is_one_cell_where_the_meter_is_twopins both halves. A card carries the meter and never a status mark, and the block carries the status mark and never a meter, so the two never sit in one column - Both marks go ahead of the id, where they describe the target rather than the row. Every row carries both, so nothing is pushed out of line the way the card's blocked mark would have been, which is why that one sits after the id and these before it
- The kind mark survives a target the board cannot find and the status mark cannot, since a kind is read from the ticket's own file and a status from the board.
?holds the column so the id does not move, and_missing_in grey is what says the target is gone - Committed and reviewing are told apart by colour alone, both being
◐, so a pipe cannot tell them apart:should_use_colorsis false and both read as under way. Accepted, because●and○are the two answers usually wanted andshowon the target settles the rest, andassets/SKILL.mdsays so outright rather than leaving an agent to infer it. Do not fix this by giving one of them a colour that means something else RelationTargetcarries the title and the status in oneOption, because they come from the same lookup and are absent together. It was taken out when the mark keyed on the kind alone and put back one commit later, which is the cost of a field nothing reads: correct at the time, and churn either wayshowand the board carry the same mark, decided rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minorResolved.relationsis rows, not a rendered block, andResolved.campaignis cells for the same reason. An escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so nothing inResolvedcan arrive pre-painted. This was the asymmetry the two renderers needed while the rest of the body was a painted string; there is no asymmetry left, sincecontent_partspaints nothing at allBodyPartsplits the body rather than building it twice. It isCellsorRelations: everything outside the block is laid out once, bycontent_parts, andcontent_trimis that run throughpaint_cellswhile the board is the same cells run throughspan_from.Bodyis the accumulator, so a caller pushes cells and rows without tracking which it pushed last, and it merges a run into the trailing cell when the colour matches, because the board draws a span per cell and the body is pushed a character at a time in placesDetail.bodyis aText, and it is the only thing measured.last_offsetand theParagraphboth take it, so the clamp cannot wrap the body differently from the draw.Detail::plain()flattens it for the suite and is#[cfg(test)]: a second representation carried alongside the spans is a second thing to disagreedetail_bodycloses a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end. It now splits per cell rather than per part, since aCellspart holds many runs and a newline can fall inside any of them- The whole overlay body is coloured now, and
content_partspaints nothing. The block used to be the only coloured part, because it arrived as rows while everything else arrived as a painted string; e4d0bb7 gave the rest the sameCelltreatment. So the headings, the plan numbers, the criteria numbers and marks, the bold runs, the field names, the priority glyph, the tags and the grey unset values are one layout thatshowpaints and the board styles. Do not reintroduce apaintcall incontent_parts: the flat overlay was exactly that, a renderer forced to ask for the unpainted string because the painted one held escapes coloredstill reachescontent_parts, and it no longer means paint. It says whether this renderer can carry a colour at all, and one thing turns on it:**bold**gives its markers up to the colour that replaces them, so a renderer with none has to keep them or the emphasis is lost rather than moved. The board passestrue,content_trimpasses the CLI's decision, and a pipedshowstill reads its markers. Nothing else in the body consults it- Magenta means bold, and
span_fromis where the board learns that.Color::Magenta.ansi()is\x1b[1;35m, so the CLI draws every bold run bold as well as magenta, andFrom<Color>can carry only the colour. Without the modifier added on the board's side the same cell would be painted two ways, which is the one thing the shared layout exists to prevent - The conversion is pinned from both ends.
show_prints_the_same_body_it_printed_before_the_cells_conversionholds a body with one of every painted run and asserts the CLI's output byte for byte, written from what it printed before the change, so the risk in sharing a layout, the CLI's output drifting to suit the board, fails the suite.the_whole_body_is_styled_in_the_overlay_and_no_escape_reached_itis the other end and is paired the way the guideline demands: a renderer that dropped every colour passes the absence, and one that went back to painting strings passes the presence - The history block arrives as segments too, so nothing in the overlay is flat.
history_partssplits the entries into flow runs and quoted runs in one walk;history_cellsis their flatten, which is what makes the CLI's bytes a property of the segmentation rather than a second walker free to drift from it, and the board reads the same parts and lays each out itself. Pinned from both ends the way the body is: the pins overformat_historyhold the flatten byte for byte, andthe_block_splits_into_flow_and_quoted_partspins which runs are whose