Files
Codeman/test/story-plain-words.ts
T
Codeman maintainer b98deebafc feat(story-mode): a plain Simple caption on every panel
Story Mode gets a third reading level for someone who has never seen a
terminal (a parent, a manager). Every panel now carries caption.simple:
one short sentence in everyday words, with no file name, command, tool
name, flag or jargon. The sentences are templates only, so nothing from
the transcript (a path, a commit message, a branch) can reach them, and
they are written from the same facts as the story caption: a failed
check never reads as a pass, a failure you asked for says so, and a
check that fails after one passed is a failure again.

The final panel's simple caption is a plain summary: how the turn ended
and roughly how long it took, how many files changed, whether the checks
pass, whether the work is saved (only claimed "not saved" where saving
is in play: you asked for it, or the turn used git), and what the reader
must not miss (a problem left, a note, a question for them).

test/story-plain-words.ts is the guard: the corpus test runs it over
every panel of every page of the eleven sessions, and the unit tests
cover the honest endings (failed check, catch, note, question, stopped,
not done, to be continued, done for now) and the guard itself. The
corpus expectations only gain "simple" lines.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-19 05:17:31 +02:00

102 lines
2.3 KiB
TypeScript

/**
* @fileoverview The Simple reading level's promise, as a check: a caption a reader who has never seen a
* terminal can read. No path, code or file name, no tool name, no flag and no developer jargon. Used by
* test/story-mode.test.ts and test/story-corpus.test.ts (helper only, no tests of its own).
*/
/** Claude Code's tool names: matched case-sensitively, so "Claude reads" is fine and "Read" is not. */
const TOOL_NAMES = [
'Bash',
'BashOutput',
'KillShell',
'Edit',
'MultiEdit',
'Write',
'Read',
'Grep',
'Glob',
'LS',
'Task',
'Agent',
'WebFetch',
'WebSearch',
'TodoWrite',
'NotebookEdit',
'NotebookRead',
'EnterPlanMode',
'ExitPlanMode',
'ToolSearch',
'AskUserQuestion',
'SlashCommand',
'SendMessage',
'Skill',
'Advisor',
];
/** Words a developer reads past and a parent stops at. Whole words, any case. */
const JARGON = [
'test suite',
'tests?',
'lint(?:s|er|ers|ing)?',
'commits?',
'committed',
'repo(?:s|sitory|sitories)?',
'branch(?:es)?',
'diffs?',
'API',
'dependency',
'dependencies',
'builds?',
'deploy(?:s|ed|ment)?',
'terminal',
'commands?',
'scripts?',
'code',
'git',
'push(?:es|ed)?',
'pull request',
'merge[sd]?',
'compiles?',
'server',
'functions?',
'JSON',
'CLI',
'shell',
'flags?',
'tool calls?',
'exit code',
'stdout',
'stderr',
'prompts?',
'sessions?',
'background',
'mode',
'context',
'tokens?',
'refactor\\w*',
'modules?',
'packages?',
'install\\w*',
'npm',
'pytest',
'node',
];
const JARGON_RE = new RegExp(`\\b(?:${JARGON.join('|')})\\b`, 'i');
const TOOL_RE = new RegExp(`\\b(?:${TOOL_NAMES.join('|')})\\b`);
/** A file name or extension (`a.py`, `README.md`, `.gitignore`): in prose a full stop is followed by a space. */
const FILE_RE = /\S*\.[A-Za-z0-9]\S*/;
/** A command-line flag: `-q`, `--json`. */
const FLAG_RE = /(?:^|\s)-{1,2}[A-Za-z]/;
/** What makes `text` unfit for the Simple level (the offending part), or null when it reads plainly. */
export function plainWordsProblem(text: string): string | null {
if (!text.trim()) return '(empty)';
for (const ch of ['/', '\\', '`', '|', '{', '}', '<', '>', '=', '_', '#', '$', '~', '*'])
if (text.includes(ch)) return ch;
for (const re of [FILE_RE, FLAG_RE, TOOL_RE, JARGON_RE]) {
const m = re.exec(text);
if (m) return m[0];
}
return null;
}