@joshuafolkken/kit 1.3000.0 → 1.3041.0

package/scripts/rules/rule-value-cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { cost_transcript, type SessionFile } from '#scripts/cost-runtime/cost-transcript'
+import { hook_ledger_read } from '#scripts/hooks/hook-ledger-read'
+import { lane_stats_request } from '#scripts/lane/lane-stats-request'
 import { stamped_memo } from '#scripts/lib/stamped-memo'
 import { delivered_rules } from './delivered-rules'
 import { piped_verification_shapes } from './piped-verification-shapes'
@@ -10,6 +12,7 @@ import { rule_value_cache, type FreshReading } from './rule-value-cache'
 import { rule_value_candidates } from './rule-value-candidates'
 import { rule_value_prose } from './rule-value-prose'
 import { rule_value_runs, type RunSummary } from './rule-value-runs'
+import { rule_value_trend } from './rule-value-trend'
 
 // `josh rule:value` — what each delivered rule earns on the channel that carries it, one row per rule.
 // `rule_value.measure` was public but had no caller outside its own test, so
@@ -25,6 +28,8 @@ const ARGV_OFFSET = 2
 const REFRESH_FLAG = '--refresh'
 const FRESH_FLAG = '--fresh'
 const PROSE_FLAG = '--prose'
+const PERIOD_FLAG = '--period'
+const PERIOD_USAGE = 'usage: josh rule:value --period <days> — a positive number of days'
 const CACHED_NOTE = 'cached reading taken at'
 const PERCENT_SIGN = '%'
 const COLUMN_GAP = '  '
@@ -67,6 +72,19 @@ function gather_summaries(cwd: string): Array<RunSummary> {
 	return summaries
 }
 
+// The runs of the transcripts last written at or after `since_ms`.
+function window_runs(cwd: string, since_ms: number): Map<string, Array<SessionFile>> {
+	const files = cost_transcript.list_sessions_across(cost_transcript.transcript_directories(cwd))
+
+	return group_by_run(files.filter((file) => file.modified_ms >= since_ms))
+}
+
+// `--period`: the window's runs read into a memo of its own — the stored per-run counts hold whole
+// runs, so a window must neither read nor evict them.
+function gather_window(cwd: string, since_ms: number): Array<RunSummary> {
+	return rule_value_runs.summaries_of(window_runs(cwd, since_ms), stamped_memo.create())
+}
+
 function* summarized(runs: Iterable<ReadonlyArray<string>>): Generator<RunSummary> {
 	for (const texts of runs) yield rule_value_runs.summarize(texts)
 }
@@ -148,12 +166,64 @@ function cached_text(fresh: FreshReading): string {
 	return `${fresh.text.trimEnd()}\n\n${CACHED_NOTE} ${taken_at} — ${FRESH_FLAG} to measure now, with candidates`
 }
 
-function print_measured(cwd: string): void {
-	const { table, candidates } = render_summaries(gather_summaries(cwd))
+function print_summaries(summaries: Iterable<RunSummary>): void {
+	const { table, candidates } = render_summaries(summaries)
 
 	process.stdout.write(`${[table, candidates].filter(Boolean).join('\n\n')}\n`)
 }
 
+function print_measured(cwd: string): void {
+	print_summaries(gather_summaries(cwd))
+}
+
+// The start of the `--period` window, or `undefined` when its value is not a positive number of days.
+function period_since(argv: ReadonlyArray<string>): number | undefined {
+	const period_days = lane_stats_request.positive(argv[argv.indexOf(PERIOD_FLAG) + 1])
+
+	return period_days === undefined
+		? undefined
+		: hook_ledger_read.period_start(period_days, new Date())
+}
+
+function refuse(usage: string): number {
+	process.stderr.write(`${usage}\n`)
+
+	return 1
+}
+
+// The cache holds the all-time reading, so a period always measures and never stores.
+function print_period(argv: ReadonlyArray<string>, cwd: string): number {
+	const since_ms = period_since(argv)
+
+	if (since_ms === undefined) return refuse(PERIOD_USAGE)
+
+	print_summaries(gather_window(cwd, since_ms))
+
+	return 0
+}
+
+// `--weekly` reads every transcript unless `--period` narrows it.
+function weekly_since(argv: ReadonlyArray<string>): number | undefined {
+	return argv.includes(PERIOD_FLAG) ? period_since(argv) : 0
+}
+
+// Like `--period`, the trend always measures and never touches the cache (`rule-value-trend.ts`).
+function print_weekly(argv: ReadonlyArray<string>, cwd: string): number {
+	const ids = rule_value_trend.requested_ids(argv)
+
+	if (ids === undefined) return refuse(rule_value_trend.WEEKLY_USAGE)
+
+	const since_ms = weekly_since(argv)
+
+	if (since_ms === undefined) return refuse(PERIOD_USAGE)
+
+	const weeks = rule_value_trend.tallies(window_runs(cwd, since_ms))
+
+	process.stdout.write(`${rule_value_trend.render(weeks, ids) ?? NO_TARGETS}\n`)
+
+	return 0
+}
+
 function print_reading(argv: ReadonlyArray<string>, cwd: string): void {
 	const fresh = argv.includes(FRESH_FLAG) ? undefined : rule_value_cache.read_fresh(cwd)
 
@@ -173,15 +243,25 @@ function print_transcripts(argv: ReadonlyArray<string>, cwd: string): void {
 	} else print_reading(argv, cwd)
 }
 
+function print_windowed(argv: ReadonlyArray<string>, cwd: string): number {
+	if (argv.includes(rule_value_trend.WEEKLY_FLAG)) return print_weekly(argv, cwd)
+	if (argv.includes(PERIOD_FLAG)) return print_period(argv, cwd)
+
+	print_transcripts(argv, cwd)
+
+	return 0
+}
+
 // `--refresh` is the detached measurement the `backlogrun` loop head starts: the table goes to the
 // cache `backlog:offer` prints from, never to stdout (`rule-value-cache.ts`). The candidates are read
 // when a rule is retired, not at the loop head, so they print to stdout only and the cache keeps its
 // shape. Bare, a reading cached inside the refresh interval is printed instead of measuring again —
 // the measurement re-reads every transcript and takes minutes (joshuafolkken/kit#5186); `--fresh`
-// measures regardless.
+// measures regardless. `--period <days>` counts only the transcripts of that trailing window;
+// `--weekly <rule-id>...` prints those rules week by week, inside that window when one is given.
 function run_rule_value(argv: ReadonlyArray<string> = [], cwd: string = process.cwd()): number {
 	if (argv.includes(PROSE_FLAG)) print_prose(cwd)
-	else print_transcripts(argv, cwd)
+	else return print_windowed(argv, cwd)
 
 	return 0
 }
@@ -199,6 +279,7 @@ const rule_value_cli = {
 	run_rule_value,
 	CACHED_NOTE,
 	NO_TARGETS,
+	PERIOD_USAGE,
 	UNMEASURED,
 	UNREACHED,
 }

package/scripts/rules/rule-value-trend.ts

@@ -0,0 +1,108 @@
+import type { SessionFile } from '#scripts/cost-runtime/cost-transcript'
+import { stamped_memo } from '#scripts/lib/stamped-memo'
+import { delivered_rules } from './delivered-rules'
+import { rule_rephrase } from './rule-rephrase'
+import { rule_value_runs, type Tally } from './rule-value-runs'
+
+// `josh rule:value --weekly <rule-id>...` — the named rules' reached / refused / rephrased, one line per
+// week, so a rule's refusals read before and after the week it was changed (joshuafolkken/kit#7332).
+//
+// **A run is never split across weeks**: it counts in the week its newest file was last written, the
+// same run unit the cumulative table reads. Weeks open on Monday 00:00 UTC.
+
+const WEEKLY_FLAG = '--weekly'
+const WEEKLY_USAGE =
+	'usage: josh rule:value --weekly <rule-id>... [--period <days>] — one or more measured rule ids'
+const FLAG_PREFIX = '--'
+const MS_PER_DAY = 86_400_000
+const DAYS_PER_WEEK = 7
+// The Unix epoch fell on a Thursday, three days after the Monday that opens its week.
+const EPOCH_AFTER_MONDAY_DAYS = 3
+const WEEK_MS = DAYS_PER_WEEK * MS_PER_DAY
+const EPOCH_OFFSET_MS = EPOCH_AFTER_MONDAY_DAYS * MS_PER_DAY
+const DATE_LENGTH = 'YYYY-MM-DD'.length
+const INDENT = '  '
+const COLUMN_GAP = '  '
+
+type Runs = ReadonlyMap<string, ReadonlyArray<SessionFile>>
+
+interface WeekTally {
+	label: string
+	tally: Tally
+}
+
+function week_start(ms: number): number {
+	return ms - ((ms + EPOCH_OFFSET_MS) % WEEK_MS)
+}
+
+// The ids following `--weekly` up to the next flag, or `undefined` when there are none or one is not
+// a measured rule — a misspelt id would otherwise print a trend of zeros.
+function requested_ids(argv: ReadonlyArray<string>): Array<string> | undefined {
+	const start = argv.indexOf(WEEKLY_FLAG) + 1
+	const end = argv.findIndex((value, index) => index >= start && value.startsWith(FLAG_PREFIX))
+	const ids = argv.slice(start, end === -1 ? undefined : end)
+	const known = new Set(delivered_rules.MEASURED_RULES.map((rule) => rule.id))
+
+	return ids.length > 0 && ids.every((id) => known.has(id)) ? ids : undefined
+}
+
+function run_week(files: ReadonlyArray<SessionFile>): number {
+	return week_start(Math.max(...files.map((file) => file.modified_ms)))
+}
+
+// The runs grouped by week, oldest first.
+function by_week(runs: Runs): Array<[number, Map<string, ReadonlyArray<SessionFile>>]> {
+	const weeks = new Map<number, Map<string, ReadonlyArray<SessionFile>>>()
+
+	for (const [owner, files] of runs) {
+		const week = run_week(files)
+		const owned = weeks.get(week) ?? new Map<string, ReadonlyArray<SessionFile>>()
+
+		owned.set(owner, files)
+		weeks.set(week, owned)
+	}
+
+	return [...weeks].toSorted(([left], [right]) => left - right)
+}
+
+// Each week's tally, read into a memo of its own as `--period` is: the stored counts hold whole runs.
+function tallies(runs: Runs): Array<WeekTally> {
+	return by_week(runs)
+		.map(([week, owned]) => ({
+			label: new Date(week).toISOString().slice(0, DATE_LENGTH),
+			tally: rule_value_runs.tally(rule_value_runs.summaries_of(owned, stamped_memo.create())),
+		}))
+		.filter((week) => week.tally.runs > 0)
+}
+
+function week_line(id: string, { label, tally }: WeekTally): string {
+	const reading = tally.readings.find((candidate) => candidate.id === id)
+	const counts: Array<[string, number]> = [
+		['reached', reading?.sessions ?? 0],
+		['refused', reading?.refusals ?? 0],
+		['rephrased', rule_rephrase.rephrased_of(id, tally.rephrased)],
+	]
+	const columns = counts.map(([name, count]) => `${name} ${String(count)}`)
+
+	return INDENT + [label, ...columns].join(COLUMN_GAP)
+}
+
+// One block per rule: its id, then a line per week. `undefined` when no week holds a read run.
+function render(weeks: ReadonlyArray<WeekTally>, ids: ReadonlyArray<string>): string | undefined {
+	if (weeks.length === 0) return undefined
+
+	return ids.map((id) => [id, ...weeks.map((week) => week_line(id, week))].join('\n')).join('\n\n')
+}
+
+const rule_value_trend = {
+	by_week,
+	render,
+	requested_ids,
+	tallies,
+	week_start,
+	WEEKLY_FLAG,
+	WEEKLY_USAGE,
+}
+
+export { rule_value_trend }
+export type { WeekTally }

package/scripts/rules/shell-redirects.ts

@@ -1,11 +1,13 @@
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { nested_commands } from './nested-commands'
+import { shell_tokens, type ShellToken } from './shell-tokens'
 
 // The files a shell segment's redirects name, used by `protected-files.ts` to detect secrets read or
 // written.
 //
-// Each `<` of a redirect operator is spaced out to the read mark and each `>` (the clobber `>|` whole)
-// to the write mark, so the word after the last mark of `<`, `>`, `>>`, `2>` or `&>` is the file it
+// The segment's words are the shared tokenizer's (`shell_tokens.words_of`). Within each word, each `<`
+// of a redirect operator is cut out as the read mark and each `>` (the clobber `>|` whole) as the
+// write mark, so the piece after the last mark of `<`, `>`, `>>`, `2>` or `&>` is the file it
 // reads or writes. A quoted `>` is text (`git commit -m "x >> .env"`), so the marks are read on the
 // quote-blanked segment, whose offsets match the original; a shell's quoted script
 // (`sh -c "echo x > .env"`) runs, so its marks are read as written, as is a heredoc line, which
@@ -16,7 +18,8 @@ const READ_MARK = '\u{1}read'
 const WRITE_MARK = '\u{1}write'
 const READ_OPERATOR = '<'
 const REDIRECT = />\||[<>]/gu
-const WHITESPACE = /\s+/u
+// Cuts a word around its marks; like the marks, no command line carries it.
+const PIECE_END = '\u{0}'
 const NEXT = 1
 const ANY_MARK: ReadonlySet<string> = new Set([READ_MARK, WRITE_MARK])
 const { SHELLS } = nested_commands
@@ -31,13 +34,22 @@ function mark_of(operator: string): string {
 	return operator === READ_OPERATOR ? READ_MARK : WRITE_MARK
 }
 
+// One word's pieces: each operator the reading marks becomes a piece of its own, so `2>&1` is `2`, a
+// write mark and `&1`, and `cat<in.txt` reads `in.txt`.
+function marked_pieces(word: ShellToken, marks: string): Array<string> {
+	const pieced = word.text.replaceAll(REDIRECT, (operator, offset: number) =>
+		marks.startsWith(operator, word.begin + offset)
+			? `${PIECE_END}${mark_of(operator)}${PIECE_END}`
+			: operator,
+	)
+
+	return pieced.split(PIECE_END).filter((piece) => piece !== '')
+}
+
 function marked_words(segment: string, program: string | undefined): Array<string> {
 	const marks = redirect_marks_of(segment, program)
-	const spaced = segment.replaceAll(REDIRECT, (operator, offset: number) =>
-		marks.startsWith(operator, offset) ? ` ${mark_of(operator)} ` : operator,
-	)
 
-	return spaced.split(WHITESPACE).filter((word) => word !== '')
+	return shell_tokens.words_of(segment).flatMap((word) => marked_pieces(word, marks))
 }
 
 // Every file the segment's redirects read or write.

package/scripts/rules/shell-segments.ts

@@ -1,5 +1,6 @@
 import { time_josh_names } from '#scripts/time-runtime/time-josh-names'
 import { time_shell } from '#scripts/time-runtime/time-shell'
+import { shell_tokens, type ShellToken } from './shell-tokens'
 
 // **A shell line carries several commands, and each has to be judged on its own.** Every trigger in
 // this directory that reads a command string needs the same cut, so the cut lives here rather than
@@ -14,28 +15,153 @@ import { time_shell } from '#scripts/time-runtime/time-shell'
 // **`early-heartbeat.ts` keeps its own separator on purpose** and is not a caller here: it adds `&`,
 // because `sleep 1200 &` is an armed timer sent to the background and has to be seen as one. That is
 // a different question about a different character, not a second copy of this answer.
-const SEGMENT_SEPARATOR = /&&|\|\||;|\n/u
-const SEGMENT_PARTS = new RegExp(`(${SEGMENT_SEPARATOR.source})`, 'u')
+const SEGMENT_OPERATORS: ReadonlySet<string> = new Set(['&&', '||', ';', ';;', ';;&', ';&', '\n'])
 
 // **The rows that read a segment as argv cut at the pipe and the background `&` as well.** Their
 // question is which program a segment launches, and `true | git push -f` or `x & git push -f`
 // launches git all the same; a `--jq` fragment cut off by a `|` begins with no program word, so it
-// launches nothing they look for. A `&` that belongs to a redirection (`2>&1`, `&>file`, `<&3`) does
-// not cut, nor does the `|` of the clobber redirect `>|`.
-const COMMAND_SEPARATOR = /&&|\|\||;|\n|(?<!>)\|&?|(?<![<>])&(?!>)/u
+// launches nothing they look for. A `&` that belongs to a redirection (`2>&1`, `&>file`, `<&3`) is
+// part of a word, not an operator, and so is the `|` of the clobber redirect `>|` (`shell-tokens.ts`).
+const COMMAND_OPERATORS: ReadonlySet<string> = new Set([...SEGMENT_OPERATORS, '|', '|&', '&'])
+
+// **A compound command's opening word is a cut too** (joshuafolkken/kit#7334): the command after it
+// starts a segment of its own, so `f() { rm -rf x; }` yields `rm -rf x` for a rule anchored at `^rm`,
+// and `case $x in a) rm -rf x;; esac` does the same past the arm's pattern. A `{` opens a group or a
+// function body only at a command's start, after `name()` or after `function name`; a pattern closes
+// with `)` right after `case … in` or after the previous arm's `;;`.
+const CASE_ARM_ENDS: ReadonlySet<string> = new Set([';;', ';;&', ';&'])
+const GROUP_OPENER = '{'
+const FUNCTION_HEAD_END = '()'
+const FUNCTION_KEYWORD = 'function'
+const FUNCTION_NAME_OFFSET = 2
+const PATTERN_END = ')'
+const NEWLINE = '\n'
+// joshuafolkken/kit#7340: the pattern's words and the `|` between its alternatives stand between the
+// arm's start and its `)`, so `a|b)` and a `)` standing apart (`a )`) end the pattern too. Newlines
+// stand only before the pattern, so `esac` and a newline do not start one.
+const PATTERN_LINK = '|'
+const ARM_START = 'in'
+// The command may touch the `)` (`b)git push`), so the cut ends at the word's first `)` past its quoting:
+// `'a)'` closes nothing.
+const QUOTING = /['"]|\\[\s\S]?/gu
+
+type Cut = Pick<ShellToken, 'begin' | 'end'>
+
+function is_function_head(tokens: ReadonlyArray<ShellToken>, index: number): boolean {
+	const previous = tokens[index - 1]
+
+	if (previous?.text.endsWith(FUNCTION_HEAD_END) === true) return true
+
+	return tokens[index - FUNCTION_NAME_OFFSET]?.text === FUNCTION_KEYWORD
+}
+
+function is_group_opener(tokens: ReadonlyArray<ShellToken>, index: number): boolean {
+	if (tokens[index]?.text !== GROUP_OPENER) return false
+
+	const previous = tokens[index - 1]
+
+	return previous?.kind !== 'word' || is_function_head(tokens, index)
+}
+
+function follows_case_head(tokens: ReadonlyArray<ShellToken>, index: number): boolean {
+	return tokens.slice(0, index).some((token) => token.text === 'case')
+}
+
+function quoting_end(text: string): number {
+	const quoting = [...text.matchAll(QUOTING)].at(-1)
+
+	return quoting === undefined ? 0 : quoting.index + quoting[0].length
+}
+
+// The offset just past the word's pattern-closing `)`, or -1 when it closes none.
+function close_end(text: string): number {
+	const close = text.indexOf(PATTERN_END, quoting_end(text))
+
+	return close === -1 ? close : close + 1
+}
+
+function is_pattern_part(token: ShellToken): boolean {
+	if (token.kind === 'operator') return token.text === PATTERN_LINK
+
+	return token.text !== ARM_START && close_end(token.text) < 0
+}
+
+// The token the arm's pattern follows, past the pattern's own words and the newlines before them.
+function lead_index(tokens: ReadonlyArray<ShellToken>, index: number): number {
+	const start = tokens.slice(0, index).findLastIndex((token) => !is_pattern_part(token)) + 1
+
+	return tokens.slice(0, start).findLastIndex((token) => token.text !== NEWLINE)
+}
+
+function is_arm_lead(tokens: ReadonlyArray<ShellToken>, lead_at: number): boolean {
+	const lead = tokens[lead_at]
+
+	if (lead === undefined) return false
+	if (CASE_ARM_ENDS.has(lead.text)) return true
+
+	return lead.text === ARM_START && follows_case_head(tokens, lead_at)
+}
+
+function pattern_cut(
+	tokens: ReadonlyArray<ShellToken>,
+	index: number,
+	token: ShellToken,
+): Cut | undefined {
+	const close = close_end(token.text)
+
+	if (close < 0 || !is_arm_lead(tokens, lead_index(tokens, index))) return undefined
+
+	return { begin: token.begin, end: token.begin + close }
+}
+
+function word_cut(
+	tokens: ReadonlyArray<ShellToken>,
+	index: number,
+	token: ShellToken,
+): Cut | undefined {
+	return is_group_opener(tokens, index) ? token : pattern_cut(tokens, index, token)
+}
+
+function cut_of(
+	tokens: ReadonlyArray<ShellToken>,
+	index: number,
+	operators: ReadonlySet<string>,
+): Cut | undefined {
+	const token = tokens[index]
+
+	if (token === undefined) return undefined
+	if (token.kind === 'word') return word_cut(tokens, index, token)
+
+	return operators.has(token.text) ? token : undefined
+}
+
+function cuts_of(reading: string, operators: ReadonlySet<string>): Array<Cut> {
+	const tokens = shell_tokens.tokens_of(reading)
+
+	return tokens.flatMap((_token, index) => cut_of(tokens, index, operators) ?? [])
+}
+
+// The typed line between the cuts, untrimmed; the cuts were found on a reading with the same offsets.
+function pieces_of(command: string, cuts: ReadonlyArray<Cut>): Array<string> {
+	const starts = [0, ...cuts.map((cut) => cut.end)]
+
+	return starts.map((start, index) => command.slice(start, cuts[index]?.begin ?? command.length))
+}
+
+function trimmed(pieces: ReadonlyArray<string>): Array<string> {
+	return pieces.map((piece) => piece.trim())
+}
 
 /** The line's commands, trimmed. Empty segments are kept: a caller anchoring at `^` rejects them. */
 function segments_of(command: string): Array<string> {
-	return command.split(SEGMENT_SEPARATOR).map((segment) => segment.trim())
+	return trimmed(pieces_of(command, cuts_of(command, SEGMENT_OPERATORS)))
 }
 
 /** The line's commands as separate programs: the `segments_of` cut plus a pipe and a background `&`. */
 function commands_of(command: string): Array<string> {
-	return command.split(COMMAND_SEPARATOR).map((segment) => segment.trim())
+	return trimmed(pieces_of(command, cuts_of(command, COMMAND_OPERATORS)))
 }
 
-const COMMAND_SEPARATORS = new RegExp(COMMAND_SEPARATOR.source, 'gu')
-
 /**
  * The `commands_of` cut taken where the quote-blanked line puts each separator, so a `|` or `;`
  * inside a quoted argument does not cut it; a heredoc line falls back to `commands_of`.
@@ -45,14 +171,7 @@ function quote_aware_commands_of(command: string): Array<string> {
 
 	if (plain === undefined) return commands_of(command)
 
-	const cuts = [...plain.matchAll(COMMAND_SEPARATORS)].map((match) => ({
-		begin: match.index,
-		end: match.index + match[0].length,
-	}))
-	const starts = [0, ...cuts.map((cut) => cut.end)]
-	const stops = cuts.map((cut) => cut.begin)
-
-	return starts.map((start, index) => command.slice(start, stops[index] ?? command.length).trim())
+	return trimmed(pieces_of(command, cuts_of(plain, COMMAND_OPERATORS)))
 }
 
 const LINE_CONTINUATION = /\\\n/gu
@@ -64,7 +183,13 @@ function joined_continuations(command: string): string {
 
 /** The same cut, untrimmed and with each separator kept between its commands, so the parts join back to the line. */
 function parts_of(command: string): Array<string> {
-	return command.split(SEGMENT_PARTS)
+	const cuts = cuts_of(command, SEGMENT_OPERATORS)
+
+	return pieces_of(command, cuts).flatMap((piece, index) => {
+		const cut = cuts[index]
+
+		return cut === undefined ? piece : [piece, command.slice(cut.begin, cut.end)]
+	})
 }
 
 /**
@@ -76,9 +201,9 @@ function first_of(command: string): string | undefined {
 
 	if (plain === undefined) return undefined
 
-	const cut = plain.search(SEGMENT_SEPARATOR)
+	const [cut] = cuts_of(plain, SEGMENT_OPERATORS)
 
-	return (cut === -1 ? command : command.slice(0, cut)).trim()
+	return command.slice(0, cut?.begin ?? command.length).trim()
 }
 
 // **Both spellings match, and the expansion is not this file's.** `time_josh_names` expands the alias

package/scripts/rules/shell-tokens.ts

@@ -0,0 +1,66 @@
+// **One reading of a shell line's words and control operators, shared by the guards** (joshuafolkken/kit#7334).
+// A guard that cuts the line with a separator pattern of its own can read the same line differently
+// from the next one, so the cut starts here. The tokenizer is hand-written rather than a parser package: the guards slice the
+// typed line at a token's offsets, and the candidate packages return argv with the quotes removed and
+// the variables expanded, so no offset survives (`docs/maintainers/shell-tokenizer.md`).
+//
+// **Quoting is the caller's reading, not this file's.** A caller that must not cut inside quotes hands
+// in the quote-blanked line (`time_shell.blanked`), whose offsets are the typed line's; a caller that
+// reads quoted text as commands too hands in the line as typed. `words_of` is the one reading of a
+// command's words for the guards that read arguments rather than cut commands.
+
+import { time_shell } from '#scripts/time-runtime/time-shell'
+
+type ShellTokenKind = 'operator' | 'word'
+
+interface ShellToken {
+	begin: number
+	end: number
+	kind: ShellTokenKind
+	text: string
+}
+
+// Longest first, so `;;&` and `;;` (a `case` arm's end) are one operator, not two `;`. A `|` after `>`
+// is the clobber redirect, and a `&` beside `<` or `>` belongs to a redirection (`2>&1`, `&>f`, `<&3`).
+const OPERATOR = String.raw`;;&?|;&|&&|\|\||(?<!>)\|&?|;|\n|(?<![<>])&(?!>)`
+const WORD = String.raw`(?:[^\s;&|]|(?<=[<>])&|&(?=>)|(?<=>)\|)+`
+const TOKEN_PATTERN = new RegExp(`(?<operator>${OPERATOR})|${WORD}`, 'gu')
+// A separator character the quote-held reading turns into a word character where a quote holds it.
+const SEPARATOR = /[;&|]/gu
+const HELD = '_'
+const BLANK = ' '
+
+/** The line's tokens in order, each with its offsets; whitespace other than a newline separates them. */
+function tokens_of(reading: string): Array<ShellToken> {
+	return [...reading.matchAll(TOKEN_PATTERN)].map((match) => ({
+		begin: match.index,
+		end: match.index + match[0].length,
+		kind: match.groups?.['operator'] === undefined ? 'word' : 'operator',
+		text: match[0],
+	}))
+}
+
+// The line with each `;`, `&` or `|` a quote or a backslash holds made a word character; the quote-blanked
+// line has the typed line's offsets. A heredoc line, which `blanked` does not read, stays as typed.
+function quote_held(line: string): string {
+	const plain = time_shell.blanked(line)
+	if (plain === undefined) return line
+
+	return line.replaceAll(SEPARATOR, (character, offset: number) =>
+		plain[offset] === BLANK ? HELD : character,
+	)
+}
+
+/**
+ * The line's words, each with its typed text: whitespace cuts a word as it does unquoted, but a
+ * separator inside quotes stays in its word (`rg "a|b" f` is three words).
+ */
+function words_of(line: string): Array<ShellToken> {
+	return tokens_of(quote_held(line))
+		.filter((token) => token.kind === 'word')
+		.map((token) => ({ ...token, text: line.slice(token.begin, token.end) }))
+}
+
+const shell_tokens = { tokens_of, words_of }
+
+export { shell_tokens, type ShellToken }

package/scripts/rules/standalone-gh-call.ts

@@ -0,0 +1,63 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+
+// A Bash line that is one `gh issue <action> <N> …` call and nothing else, which a refusing row can
+// rewrite to its `pnpm josh` command (joshuafolkken/kit#7330): every word is plain, so nothing is
+// piped, chained, redirected, quoted or expanded, and the one issue number is split from the flags the
+// row reads. Shared by `direct-issue-read.ts` and `direct-issue-comment.ts`.
+
+interface StandaloneCall {
+	issue: string
+	// The words that are not the issue number, joined by one space.
+	flags: string
+}
+
+const WORD_SEPARATOR = ' '
+// A word with no shell syntax in it, so a line of them is one call with nothing chained or redirected.
+const PLAIN_WORD = /^[\w./=-]+$/u
+
+function line_of(words: ReadonlyArray<string>): string {
+	return words.join(WORD_SEPARATOR)
+}
+
+function is_plain_word(word: string): boolean {
+	return PLAIN_WORD.test(word)
+}
+
+function split_issue(rest: ReadonlyArray<string>): StandaloneCall | undefined {
+	const issues = rest.filter((word) => issue_number_shape.is_issue_number(word))
+	const [issue] = issues
+	const flags = line_of(rest.filter((word) => !issue_number_shape.is_issue_number(word)))
+
+	return issue !== undefined && issues.length === 1 ? { issue, flags } : undefined
+}
+
+// The issue and flags after `lead` on a line that is that one call alone, else `undefined`.
+function call_of(line: string, lead: ReadonlyArray<string>): StandaloneCall | undefined {
+	const words = line.trim().split(WORD_SEPARATOR)
+	const is_lead = line_of(words.slice(0, lead.length)) === line_of(lead)
+
+	return is_lead && words.every((word) => is_plain_word(word))
+		? split_issue(words.slice(lead.length))
+		: undefined
+}
+
+// The Bash input with its command replaced by `command_of`'s answer, else `undefined`.
+function input_of(
+	call: GuardedCall,
+	command_of: (command: string) => string | undefined,
+): Record<string, unknown> | undefined {
+	if (call.name !== cost_blocks.BASH_TOOL || !json_value.is_record(call.input)) return undefined
+
+	const command = command_of(time_shell.bash_command(call.input))
+
+	return command === undefined ? undefined : { ...call.input, command }
+}
+
+const standalone_gh_call = { call_of, input_of, is_plain_word, line_of }
+
+export type { StandaloneCall }
+export { standalone_gh_call }