waterplane 0.0.1 → 0.1.6

package/node_modules/@waterplane/shared/dist/naming.d.ts

@@ -0,0 +1,391 @@
+/**
+ * What a machine may call somebody else's words.
+ *
+ * ── Why this file exists ───────────────────────────────────────────────────
+ *
+ * A headline is the one string in this app that a MODEL writes FOR a person,
+ * over words the person wrote themselves. Everything else a model produces here
+ * either runs (a prompt), cites (evidence) or explains (a note); a headline sits
+ * on top of a row in a list and is the thing a reader scans instead of the
+ * sentence underneath it. That makes it the one string that can quietly replace
+ * somebody's own writing in the only place they look.
+ *
+ * So three rules, and each is enforced here rather than asked for politely:
+ *
+ *   • **It never stands in for them.** `itemHeadline` is the ONE display rule
+ *     for both ends: a title a person typed wins, always, and a derived headline
+ *     is what a row falls back to. Two copies of that rule is two answers to
+ *     "whose words are on this row".
+ *   • **It never replaces a name they typed.** Every headline and every kind
+ *     carries an AUTHOR (`NameAuthor`) and is stored with it or not at all — a
+ *     title that cannot say who wrote it cannot say whether a person may be
+ *     overwritten, so the pair travels together and is dropped together.
+ *   • **It is never guessed.** `cleanCategory` knows four words and no
+ *     synonyms: `"bugfix"` is `undefined`, never `chore`. A synonym table is a
+ *     second vocabulary, and a second vocabulary is how "no kind" becomes
+ *     "chore" for every row nobody looked at.
+ *
+ * And a fourth, which is the shape of the caps: a headline is a LABEL, so it is
+ * CLIPPED rather than dropped for length — the opposite of `assess.ts`'s
+ * prompts, which are dropped rather than cut, because half a title is still a
+ * title and half an instruction is a different instruction.
+ *
+ * ── What is deliberately NOT here ──────────────────────────────────────────
+ *
+ * No filesystem, no clock, no host imports, and — deliberately — no import of
+ * `assess.ts`, which imports THIS. The vocabulary has to be nameable by the
+ * module that judges it, so it lives one level below it.
+ */
+/**
+ * What KIND of thing one item is, in four words and no more.
+ *
+ * Four because the list is read as a filter on a phone, and a taxonomy a person
+ * has to learn is a taxonomy they will not use. Absent is a real answer here:
+ * it means NOBODY SAID, which is different from every one of these four.
+ */
+export type ItemCategory = "bug" | "feature" | "enhancement" | "chore";
+export declare const ITEM_CATEGORIES: readonly ItemCategory[];
+/**
+ * Who wrote the title or the kind on a row.
+ *
+ * `hand` is a person — the one value that makes a title un-overwritable, which
+ * is the entire reason this field exists. `assess` is a verdict a person
+ * applied; `name` is a naming run, whose whole job is titles.
+ *
+ * Stored with the value it describes and never separately: an author with no
+ * value names nothing, and a value with no author is a title that cannot say
+ * whether it may be replaced — both are dropped rather than defaulted, because
+ * defaulting either way is a claim about who typed something.
+ */
+export type NameAuthor = "hand" | "assess" | "name";
+export declare const NAME_AUTHORS: readonly NameAuthor[];
+/**
+ * A headline is a LABEL, so it is clipped, never dropped for length. 80 =
+ * `cleanIntentRow`'s label cap, so the prompt and the store name one number.
+ */
+export declare const MAX_HEADLINE_CHARS = 80;
+/**
+ * How many refusal notes a naming document may produce.
+ *
+ * The same number as `MAX_ASSESS_NOTES`, for the same reason and kept here
+ * rather than imported because `assess.ts` imports this module and a cycle over
+ * one integer is not a trade worth making. It is nearly unreachable by
+ * construction: the notes below are AGGREGATED — one per kind of drop, with a
+ * count — so a run that mis-names two hundred rows produces four sentences, not
+ * two hundred.
+ */
+export declare const MAX_NAMING_NOTES = 40;
+/** The word a row shows when nothing said what kind of thing it is. Absent is
+ *  an answer, and this is how that answer is spelled — never a fifth category,
+ *  and never "chore". */
+export declare const NO_CATEGORY_LABEL = "no kind";
+/**
+ * A title a model wrote about `text`, or nothing.
+ *
+ * Tolerant about shape — a quoted string, a trailing full stop, ragged
+ * whitespace and a run-on past the cap are all cosmetics, and refusing a whole
+ * naming run over punctuation just means the user pays for it twice. Strict
+ * about ONE thing: a "title" that is merely the first words of its own item is
+ * not a title.
+ *
+ * ── Why the test here is ONE-directional, and `typedName`'s is two ──────────
+ *
+ * `typedName` answers a different question: *is the string in the name slot a
+ * name, or is it the derivation this app itself wrote there?* Both ends fill
+ * that slot with `text.slice(0, sliceLen)` when nobody typed one, so it has to
+ * refuse in both directions — the text starting with the name (the ordinary
+ * case) AND the name starting with the text's own leading slice, which is what
+ * a multi-line prompt shorter than the slice looks like.
+ *
+ * A HEADLINE has no such derivation behind it. Nothing in this app ever writes
+ * one out of the prompt, so the only shape worth refusing is the one that means
+ * *this is a truncation of the item*: `text` starts with the headline. Borrowing
+ * the second clause refused a whole class of perfectly good titles — for any
+ * prompt under 40 characters, EVERY title that opens with the whole prompt.
+ * Text `dark mode`, title `dark mode toggle for settings`: dropped, and (before
+ * `edit()` learned to say so) dropped in silence.
+ *
+ * Both sides are whitespace-collapsed before the comparison, because `s` above
+ * already is: without it a prompt that wraps between two of its own opening
+ * words would read as a different string and the truncation would go through.
+ *
+ * `text` may be empty — a build or a capture has no prose — and an empty text is
+ * "there is nothing to be a truncation of", never "everything is one".
+ */
+export declare function cleanHeadline(raw: unknown, text: string): string | undefined;
+/**
+ * **Why a title somebody typed was not written**, in one sentence.
+ *
+ * Here, beside the rule that refuses it, because the refusal and its wording
+ * are the same fact: `cleanHeadline` returning `undefined` used to be a silent
+ * drop — the editor closed, the row kept its old title, and the words a person
+ * had just typed were gone with nothing on any screen about it. CLAUDE.md's
+ * *never overwrite typed words with words nobody typed* has a quieter twin, and
+ * this is it: never DROP typed words without saying so.
+ *
+ * It names what was refused, because a sentence about "the title" on a screen
+ * with two of them is a sentence the reader has to guess at.
+ */
+export declare function headlineRefusedText(headline: string): string;
+/** The same, for a kind that is not one of the four. No synonym table here and
+ *  none in the sentence: it says the four words rather than guessing which was
+ *  meant (`cleanCategory`). */
+export declare function categoryRefusedText(category: string): string;
+/**
+ * One of the four words, or nothing at all.
+ *
+ * Case and surrounding space are cosmetics. Everything else is refused: there
+ * is no synonym table here and there must not be one, because the cost of a
+ * wrong kind is a row filed under a heading its author never chose and would
+ * never think to look under.
+ */
+export declare function cleanCategory(raw: unknown): ItemCategory | undefined;
+/** Who wrote it — one of three, or nothing. Same posture as `cleanCategory`:
+ *  an author this app does not know is not an author. */
+export declare function cleanAuthor(raw: unknown): NameAuthor | undefined;
+/** What a run concluded a row should be CALLED. Either half may be absent —
+ *  a title with no kind and a kind with no title are both honest answers. */
+export interface ItemName {
+    headline?: string;
+    category?: ItemCategory;
+}
+/**
+ * One row of the document, as the caller knows it.
+ *
+ * A bare id is enough to accept a name; the `text` is what lets the prefix rule
+ * run, and a caller that has the words should pass them — without them a
+ * headline that is just the first line of its own item cannot be recognised as
+ * one. `readonly string[]` is therefore still a valid argument, and a caller
+ * that upgrades to objects loses nothing.
+ */
+export type NamingTarget = string | {
+    id: string;
+    text?: string;
+};
+/** The finished sentences, so both drops are worded once. `assess.ts` says the
+ *  same two things about its own rows and must not word them differently. */
+export declare function headlineDropNote(n: number): string;
+export declare function categoryDropNote(n: number): string;
+/**
+ * Whatever a naming run wrote, plus the rows it was asked about, in — one name
+ * per KNOWN row, out.
+ *
+ * `cleanAssessment`'s posture, for `cleanAssessment`'s reasons. Tolerant about
+ * SHAPE: a bare array, `{items:[…]}` and `{rows:[…]}` are all the same
+ * document, because the difference is the model's and the cost is the user's.
+ * Strict about CLAIMS: a name for an id nobody asked about is dropped, and an
+ * id named TWICE loses both names — two titles for one row say two things about
+ * what it is, neither is trustworthy, and picking the first is picking at
+ * random.
+ *
+ * The notes are AGGREGATED — one sentence per kind of drop, carrying the count.
+ * A naming run touches every row in a repo, so one note per row would be a
+ * scroll nobody reads, and the fact worth showing is "eleven of these were
+ * thrown away", not which eleven.
+ */
+export declare function cleanNamingDoc(raw: unknown, ids: readonly NamingTarget[]): {
+    names: Record<string, ItemName>;
+    notes: string[];
+};
+/**
+ * **The ONE display rule**: what this row is CALLED, on both ends.
+ *
+ * A `label` is what a person typed, so it wins — but only when it is a name and
+ * not a slice of the row's own prose, which is what `typedName` is for and what
+ * the backlog's own 40-character derivation makes the common case. A `headline`
+ * is the machine's, and stands only where a person put nothing.
+ *
+ * `null`, never the text, when neither: the caller decides whether a nameless
+ * row shows its first line or shows nothing, and that decision differs by
+ * screen. What must not differ by screen is which of the two strings wins.
+ */
+export declare function itemHeadline(it: {
+    label?: string;
+    text: string;
+    headline?: string;
+}): string | null;
+/**
+ * The ONE place a kind becomes a word.
+ *
+ * The four words are their own labels today, which is exactly why this is a
+ * function: `assessVerdictLabel`'s rule — when a heading is re-worded it has to
+ * be re-worded once, and a `switch` is what makes the compiler say so when a
+ * fifth kind appears.
+ */
+export declare function categoryLabel(c: ItemCategory): string;
+/**
+ * How many words a tab title may be, and how many characters that is allowed to
+ * cost.
+ *
+ * Four words, and the strip is sized for three tabs by default — the two
+ * numbers moved together, because they are the same trade seen from each end:
+ * how much of a name there is to read, and how much room there is to read it
+ * in. The words are what the SESSION SCREEN shows in full when you open it
+ * (`App.tsx`'s header), so the cap is set by what is worth having there rather
+ * than by what fits a 90 px tab, which clips to its own width regardless.
+ *
+ * The character cap is the second half of the same fact — four words can still
+ * be four long ones, and the cap is what stops one name from being the whole
+ * strip. It is a REFUSAL boundary, not a clip: see below.
+ */
+export declare const MAX_TAB_WORDS = 4;
+export declare const MAX_TAB_CHARS = 30;
+/**
+ * The ≤4-word title a model wrote for a session tab, or nothing.
+ *
+ * `cleanHeadline`'s tolerance about shape, with two differences that are both
+ * about the strip this lands in:
+ *
+ *  - **Words are CUT, never joined with an ellipsis.** A tab is a label, and
+ *    "fix the auth…" in 90 px reads as a truncation of something longer, which
+ *    is exactly what it is not: the model was asked for four words and this
+ *    keeps the first four it wrote.
+ *  - **It refuses rather than guesses.** An empty answer, a refusal sentence
+ *    ("I cannot"), or anything past the character cap once the words are cut,
+ *    comes back `undefined` — and the tab then wears the repo and branch it
+ *    always had. CLAUDE.md's rule for every heuristic here: degrade to absent,
+ *    never to a wrong number, and a wrong TITLE is the version of that which a
+ *    person taps.
+ *
+ * Deliberately not `cleanHeadline` with a smaller cap: that one clips mid-word
+ * on purpose (a headline is prose and a cut word still reads), and it also
+ * refuses a title that is how its own text starts — a rule about backlog rows
+ * that has no meaning for a terminal session, which has no "text" to be a
+ * truncation of.
+ */
+export declare function cleanTabTitle(raw: unknown): string | undefined;
+/**
+ * The branch names that mean "the ordinary place", and so say nothing.
+ *
+ * Two, and no pattern. `main` and `master` are the two names git itself
+ * creates; anything else was CHOSEN, and a chosen name is information. A repo
+ * whose default really is `develop` keeps seeing `develop` — which is the safe
+ * direction for a guess about somebody else's repo: the failure mode of this
+ * list is showing a word that could have been hidden, never hiding one that
+ * had to be read.
+ *
+ * There is no default-branch field on the wire to ask instead: `RepoTarget`
+ * carries the branch a worktree is ON, not the branch the repo considers home.
+ */
+export declare const DEFAULT_BRANCH_NAMES: readonly string[];
+/** Whether a branch name is one of the two git makes on its own. */
+export declare function isDefaultBranch(raw: unknown): boolean;
+/**
+ * What a row should SAY about the branch it is on — or nothing.
+ *
+ * `undefined` means "saying this adds nothing", and every caller falls back to
+ * the repo's own name rather than drawing a blank. On a phone the session list
+ * is one row of ~30 characters per session, and on a desktop where every repo
+ * sits on `main` that word was the FIRST thing on every row, pushing the
+ * derived name, the status tags and the age off the end of the line — the same
+ * space that now carries what the session is actually about.
+ *
+ * **Only on the PRIMARY worktree.** A worktree's branch is its whole identity —
+ * `RepoPicker` titles it with nothing else — so a worktree that happens to be
+ * on `main` still says so, or the row loses the only thing that tells it from
+ * its siblings. Pass `isPrimary: false` (or nothing) for those.
+ *
+ * This is display only. `GitView` and `BranchPicker` are ABOUT branches and
+ * never call this: hiding the current branch on the screen you switch branches
+ * from is not tidiness, it is a missing fact.
+ */
+export declare function branchLabel(r: {
+    branch?: string;
+    isPrimary?: boolean;
+}): string | undefined;
+/** "<repo> · <branch>", with the branch dropped when it says nothing. */
+export declare function repoBranchLabel(r: {
+    repoName: string;
+    branch?: string;
+    isPrimary?: boolean;
+}): string;
+/**
+ * A STORED session title with a trailing default branch taken off.
+ *
+ * New sessions are named `repoBranchLabel`-style and never carry the word, but
+ * a title is persisted with the session and every conversation opened before
+ * this rule still reads `myapp · main`. Trimming at the point it is DRAWN fixes
+ * those without rewriting anybody's stored title — including the ones a person
+ * renamed by hand, where an edit would be exactly the overwrite this file
+ * exists to refuse.
+ *
+ * Only the LAST segment, only when something is left in front of it: a session
+ * somebody called `main` is called `main`.
+ */
+export declare function trimDefaultBranch(title: unknown): string;
+/**
+ * **The desktop's own ≤4-word name for a session, or "".**
+ *
+ * `SessionInfo.tabTitle` is derived once per conversation by the host and is
+ * the only string in this app that says what a session is ABOUT — `s.title` is
+ * `<repo> · <branch>`, which four sessions open in one repo all share. The tab
+ * strip wears the name, the session header wears it and the launcher row wears
+ * it; every surface that asks *which session?* was still offering the repo
+ * name four times and the answer never.
+ *
+ * One reader, here beside `branchLabel` and `trimDefaultBranch`, because it is
+ * the same question those two answer: which part of a session's name a row has
+ * to SAY. Trimmed, and "" when the host has derived nothing — never an invented
+ * name, and never the repo wearing the derived name's clothes.
+ */
+export declare function sessionName(s: {
+    tabTitle?: string;
+}): string;
+/**
+ * What a sentence calls a session it is WAITING on ("waiting for 'fix webkit
+ * sync'") — the derived name, else the item it was opened for, else its first
+ * prompt, and only then the title. Five hand sessions in one repo all wear
+ * `myrepo` as their title, so "waiting for 'myrepo'" named none of them; the first
+ * prompt is at least something a person recognises. Clipped by the sentence,
+ * not here. `undefined` when there is nothing to say.
+ */
+export declare function waitedSessionName(s: {
+    tabTitle?: string;
+    title?: string;
+    firstPrompt?: string;
+}, itemLabel?: string): string | undefined;
+/**
+ * A session named where there is room for exactly one string — a `<select>`
+ * option, a group head, a toast.
+ *
+ * Repo and branch FIRST, the derived name after: the first part is what tells
+ * two sessions in different repos apart and the second is what tells two in
+ * the SAME repo apart, and a picker read top to bottom needs them in that
+ * order. A row with room for two spans draws them side by side instead
+ * (`web/SessionName.tsx`), which is what the launcher does.
+ */
+export declare function sessionPickLabel(s: {
+    title: string;
+    tabTitle?: string;
+}): string;
+/**
+ * How long a suggested commit message may be, subject and whole.
+ *
+ * The subject cap is a REFUSAL boundary, not a clip — same rule as
+ * `cleanTabTitle`'s. A subject is the one line every `git log` shows, and
+ * cutting one mid-thought produces a sentence nobody wrote; a model that came
+ * back with a 200-character first line ignored its contract, and the honest
+ * answer is to say so and leave the box alone.
+ *
+ * The WHOLE cap is a different kind of edge and is enforced differently: body
+ * lines come OFF THE END until it fits, because a message's first paragraph is
+ * the part that was asked for and the rest is elaboration. The subject alone is
+ * never dropped — if it does not fit on its own, the message is refused.
+ */
+export declare const MAX_COMMIT_SUBJECT = 100;
+export declare const MAX_COMMIT_CHARS = 1200;
+/**
+ * The commit message a model wrote for a diff, or nothing.
+ *
+ * Tolerant about the wrapper a model puts around prose — a code fence, quotes
+ * around the whole thing, `Subject:` labels, ragged blank lines — because those
+ * are cosmetics and refusing over one means the call is paid for twice. Strict
+ * about the two things that would put words nobody wrote into a commit: a
+ * refusal sentence dressed as a message, and an attribution trailer.
+ *
+ * Degrades to `undefined`, never to something approximate. The caller then says
+ * so and the box keeps whatever was typed in it — CLAUDE.md's rule that a draft
+ * is the last copy of somebody's words, and a suggestion that could not be made
+ * must never be a delete.
+ */
+export declare function cleanCommitMessage(raw: unknown): string | undefined;