Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
fix(ui): explain configuration and text files by their facts only (K12)
Bernhard Jackiewiczc46b3b22b99d
diff --git a/graph-ui/src/browser-ai/BrowserChatDock.test.tsx b/graph-ui/src/browser-ai/BrowserChatDock.test.tsxindex fe0d94ab2..140e0bb82 100644--- a/graph-ui/src/browser-ai/BrowserChatDock.test.tsx+++ b/graph-ui/src/browser-ai/BrowserChatDock.test.tsx@@ -1425,21 +1425,58 @@ describe('grounded automatic explanations (K14, K7)', () => {expect(card().textContent).toContain('Listed from the indexed graph; not generated by the model.');});- it('lists the jobs, triggers and actions of a workflow file above the model text (K12)', async () => {+ it('lists the jobs, triggers and actions of a workflow file without a model sentence, and asks the model only on request (K12)', async () => {vi.useFakeTimers(); const { props, runtime } = fixture();runtime.chat.mockResolvedValueOnce('This workflow greets new contributors on their first pull request.');const text = 'name: New contributor message\n\non:\n pull_request_target:\n types: [opened]\n\njobs:\n build:\n name: Hello new contributor\n runs-on: ubuntu-latest\n steps:\n - uses: actions/first-interaction@v1\n';await render({ ...props, proactive: true, selectionScope: 'django-demo:explore', readerContext: reader(text, 'file', '.github/workflows/new_contributor_pr.yml') });await click('Download & load'); await settle();+ // The automatic card is the file's facts: the model is not asked.+ expect(runtime.countTokens).not.toHaveBeenCalled();+ expect(runtime.chat).not.toHaveBeenCalled();+ expect(card().textContent).toContain('1 job: build ("Hello new contributor", runs on ubuntu-latest, 1 step).');+ expect(card().textContent).toContain('Actions used: actions/first-interaction@v1.');+ expect(card().textContent).toContain('Read from the file; not generated by the model.');+ expect(card().textContent).not.toContain('greets');+ // "Ask the model" asks it, and its text stays marked as generated.+ await act(async () => [...card().querySelectorAll('button')].find(item => item.textContent === 'Ask the model')!.click()); await settle();+ expect(runtime.chat).toHaveBeenCalledOnce();const prompt = runtime.chat.mock.calls[0][0].map(message => message.content).join('\n');expect(prompt).toContain('Facts read from the file (counted, not guessed):');expect(prompt).toContain('1 job: `build`');expect(card().textContent).toContain('1 job: build ("Hello new contributor", runs on ubuntu-latest, 1 step).');- expect(card().textContent).toContain('Actions used: actions/first-interaction@v1.');expect(card().textContent).toContain('This workflow greets new contributors on their first pull request.');expect(card().textContent).toContain('Facts read from the file; the text after them is generated by the model.');});+ it.each([+ ['docker-compose.yml', 'version: "3"\nservices:\n web:\n image: nginx\n db:\n image: postgres\n', 'Top-level keys (2): `version`, `services` (2 keys: `web`, `db`).'],+ ['package.json', '{"name": "demo", "scripts": {"build": "tsc", "test": "vitest"}}', 'Top-level keys (2): `name` (text), `scripts` (2 keys: `build`, `test`).'],+ ['pyproject.toml', '[project]\nname = "demo"\nversion = "1.0"\n\n[tool.ruff]\nline-length = 88\n', 'Tables (2): `[project]` (2 keys), `[tool.ruff]` (1 key).'],+ ['setup.cfg', '[metadata]\nname = demo\n\n[flake8]\nmax-line-length = 119\n', 'Sections (2): `[metadata]` (1 key), `[flake8]` (1 key).'],+ ['README.md', '# Demo\n\nA demo.\n\n## Install\n\n```sh\n# not a heading\npip install demo\n```\n\n## Usage\n', 'Sections (2): `Install`, `Usage`.'],+ ])('shows only the facts read from %s in the automatic card (K12)', async (path, text, fact) => {+ vi.useFakeTimers(); const { props, runtime } = fixture();+ await render({ ...props, proactive: true, selectionScope: 'django-demo:explore', readerContext: reader(text, 'file', path) });+ await click('Download & load'); await settle();+ expect(runtime.countTokens).not.toHaveBeenCalled();+ expect(runtime.chat).not.toHaveBeenCalled();+ expect(card().textContent).toContain(fact.replace(/`/g, ''));+ expect(card().textContent).toContain('Read from the file; not generated by the model.');+ expect([...card().querySelectorAll('button')].map(item => item.textContent)).toContain('Ask the model');+ });++ it('keeps the names-not-in check when the model is asked about a configuration file (K12)', async () => {+ vi.useFakeTimers(); const { props, runtime } = fixture();+ runtime.chat.mockResolvedValueOnce('This file configures `flake8` for the Python sources.');+ await render({ ...props, proactive: true, selectionScope: 'django-demo:explore', readerContext: reader('[metadata]\nname = demo\n', 'file', 'setup.cfg') });+ await click('Download & load'); await settle();+ await act(async () => [...card().querySelectorAll('button')].find(item => item.textContent === 'Ask the model')!.click()); await settle();+ expect(runtime.chat).toHaveBeenCalledOnce();+ expect(card().textContent).not.toContain('flake8');+ expect(card().textContent).toContain("Read from the file. The model's text named something the file does not show and was left out.");+ });+it('explains an Architecture area from readable facts without reading source', async () => {vi.useFakeTimers(); const { props, runtime } = fixture();const readSource = vi.fn(async () => snippet);diff --git a/graph-ui/src/browser-ai/BrowserChatDock.tsx b/graph-ui/src/browser-ai/BrowserChatDock.tsxindex 9b260e5f7..ed8f32a5f 100644--- a/graph-ui/src/browser-ai/BrowserChatDock.tsx+++ b/graph-ui/src/browser-ai/BrowserChatDock.tsx@@ -16,7 +16,7 @@ import ChatMarkdown from './ChatMarkdown';import AgentSettingsDialog from './AgentSettingsDialog';import { useChatHistory } from './use-chat-history';import { chatTopic, followedTopic, missingContextAnswer, topicHistory } from './chat-context';-import { readerFacts } from './workflow-facts';+import { isDataFile, readerFacts } from './file-facts';import './browser-chat.css';export type { BrowserChatAttachment, BrowserChatContext, BrowserChatReaderContext, BrowserChatSource } from './chat-model';@@ -51,7 +51,9 @@ export interface BrowserChatDockProps {type Phase = 'off' | 'preparing' | 'ready' | 'counting' | 'generating' | 'removing';type ChatTurn = BrowserChatTurn & { evidence?: PreparedExplanationContext };/** `grounded`: the facts are listed in the card, so the prompt's name budget is not the reader's limit. */-type Explanation = { key: string; label: string; answer: string; status: string; error?: string; packet?: PreparedExplanationContext; citation?: ReturnType<typeof citedInterpretation>; mode?: 'interpretation'; shortened?: boolean; limit?: TokenLimits; evidence?: string; grounded?: boolean };+type Explanation = { key: string; label: string; answer: string; status: string; error?: string; packet?: PreparedExplanationContext; citation?: ReturnType<typeof citedInterpretation>; mode?: 'interpretation'; shortened?: boolean; limit?: TokenLimits; evidence?: string; grounded?: boolean;+ /** The facts of a configuration or text file, which the model was not asked about (K12). */+ askable?: boolean };/** Finished explanations per selection, so returning to one does not run the model again. */const EXPLANATION_CACHE_SIZE = 32;const initialModel = BROWSER_MODELS.find(model => model.availability === 'available')!;@@ -163,6 +165,8 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "const [questionQueued, setQuestionQueued] = useState(false);const [newExplanation, setNewExplanation] = useState(false);const lastAttempt = useRef<string | undefined>(undefined);+ /** Files whose card the reader asked the model to write about ("Ask the model", K12). */+ const modelAsked = useRef(new Set<string>());const selected = useMemo(() => explanationInput(selectionScope, readerContext, proactiveSelection), [selectionScope, readerContext, proactiveSelection]);const selectionRef = useRef(selected); selectionRef.current = selected;const settingsSeen = useRef(settingsRequest);@@ -362,6 +366,16 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "const explain = async (snapshot: ExplanationInput): Promise<void> => {const currentRuntime = runtime.current;if (!historyReady || !currentRuntime || pending.current || manualRequest.current || selectionRef.current?.key !== snapshot.key) return;+ // A configuration or text file is explained by what is read from it. The model writes+ // about it only when asked, here or in the chat (K12).+ if (snapshot.reader?.source && isDataFile(snapshot.reader.source.path) && !modelAsked.current.has(snapshot.key)) {+ lastAttempt.current = snapshot.key;+ const complete: Explanation = { key: snapshot.key, label: snapshot.label, answer: groundedExplanation(readerFacts(snapshot.reader), undefined, false, 'file'), status: 'complete',+ packet: prepareExplanationContext(snapshot.reader, snapshot.graph, 3200), grounded: true, askable: true };+ remember(complete); setExplanation(complete);+ if (!followExplanation.current) setNewExplanation(true);+ return;+ }pending.current = true; stopRequested.current = false; setStopping(false);const ticket = ++epoch.current;let settle!: () => void;@@ -781,8 +795,9 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "{explanation.status !== 'generating' && <AnswerNotes shortened={limitNote(explanation.shortened, explanation.limit, true)} packet={explanation.grounded ? undefined : explanation.packet} model={model.displayName} />}{explanation.error && <p className="cbm-chat-turn-error" role="alert">{explanation.error}</p>}{explanation.status !== 'generating' && <button type="button" className="cbm-chat-retry" disabled={phase !== 'ready' || !!selected.waiting} onClick={() => {+ if (explanation.askable) modelAsked.current.add(selected.key);lastAttempt.current = undefined; explanations.current.delete(selected.key); setRetryExplanation(value => value + 1);- }}>Explain again</button>}+ }}>{explanation.askable ? relationshipWords.en.askModel : 'Explain again'}</button>}</> : <p>{selected.waiting === 'loading' ? browserChatText.waitingForScope : selected.waiting === 'partial' ? browserChatText.partialScope: manualRequest.current ? 'This selection will be explained after your answer.' : 'Preparing explanation…'}</p>}</section>}diff --git a/graph-ui/src/browser-ai/chat-model.test.ts b/graph-ui/src/browser-ai/chat-model.test.tsindex 9fc9f26e7..dfae7512c 100644--- a/graph-ui/src/browser-ai/chat-model.test.ts+++ b/graph-ui/src/browser-ai/chat-model.test.ts@@ -132,9 +132,11 @@ describe('browser chat context', () => {project: 'django-demo', path: '.github/workflows/new_contributor_pr.yml', text } };const [system] = buildChatMessages([], 'Wie viele Jobs gibt es?', undefined, [], workflow);expect(system.content).toContain('Facts read from the file (counted, not guessed):\n- Workflow name: `New contributor message`.\n- Trigger: `pull_request_target` (types: opened).\n- 1 job: `build`');- // A marked part of the file is not the whole workflow: nothing is counted from it.+ // A marked part of the file is not the whole workflow: its jobs are not counted, the part is named as a part.const marked = { ...workflow, source: { ...workflow.source, kind: 'selection' as const } };- expect(buildChatMessages([], 'Wie viele Jobs gibt es?', undefined, [], marked)[0].content).not.toContain('Facts read from the file');+ const part = buildChatMessages([], 'Wie viele Jobs gibt es?', undefined, [], marked)[0].content;+ expect(part).toContain('- Selected lines 3-5 of the file.');+ expect(part).not.toContain('1 job');});});diff --git a/graph-ui/src/browser-ai/chat-model.ts b/graph-ui/src/browser-ai/chat-model.tsindex 418d4a54d..9e48f9f8b 100644--- a/graph-ui/src/browser-ai/chat-model.ts+++ b/graph-ui/src/browser-ai/chat-model.ts@@ -1,7 +1,7 @@import type { BrowserChatMessage } from './browser-ai-runtime';import type { ChatTopic } from './chat-context';import { fileKind } from './file-kind';-import { readerFacts } from './workflow-facts';+import { readerFacts } from './file-facts';import { workflowWords } from './strings';/** An immutable snapshot, not a live reference to the reader selection. */diff --git a/graph-ui/src/browser-ai/explanation-context.ts b/graph-ui/src/browser-ai/explanation-context.tsindex 77becb5a5..aec18bc9c 100644--- a/graph-ui/src/browser-ai/explanation-context.ts+++ b/graph-ui/src/browser-ai/explanation-context.ts@@ -2,7 +2,7 @@ import { snapshotReaderContext, type BrowserChatContext, type BrowserChatReaderCimport { fairShares, readGalaxyEvidence, relationshipLine, scopeSentence, selectionSentence, sideLoaded, type GalaxyEvidence } from './galaxy-evidence';import { relationshipWords } from './strings';import { architectureFacts } from './architecture-evidence';-import { readerFacts } from './workflow-facts';+import { readerFacts } from './file-facts';export interface ExplanationEvidence {id: string;diff --git a/graph-ui/src/browser-ai/file-facts.test.ts b/graph-ui/src/browser-ai/file-facts.test.tsnew file mode 100644index 000000000..482c6dc6f--- /dev/null+++ b/graph-ui/src/browser-ai/file-facts.test.ts@@ -0,0 +1,86 @@+import { describe, expect, it } from 'vitest';+import { fileFactLines, isDataFile, readerFacts } from './file-facts';+import type { BrowserChatReaderContext } from './chat-model';++/*+ * K12: the automatic Explore card of a configuration or text file shows what is read from+ * the file, counted, and nothing the model would have to guess.+ */++const reader = (path: string, text: string, kind: 'file' | 'selection' = 'file', lines?: [number, number], partial?: string): BrowserChatReaderContext => ({+ project: 'demo', path, status: 'ready',+ source: { id: 'r', text, path, project: 'demo', startLine: lines?.[0] ?? 1, startColumn: 1, endLine: lines?.[1] ?? text.split('\n').length, endColumn: 1, sourceVersion: 'sha256:1', kind,+ ...partial ? { partial } : {} },+});++describe('facts read from a configuration or text file (K12)', () => {+ it('tells data and text files from program code by their name', () => {+ for (const path of ['a.yml', 'b.yaml', 'package.json', 'pyproject.toml', 'setup.cfg', 'tox.ini', 'nginx.conf', '.env', 'app.properties', 'README.md', 'docs/index.rst',+ 'LICENSE.txt', 'pom.xml', '.gitignore', '.editorconfig', '.github/workflows/ci.yml']) expect(isDataFile(path), path).toBe(true);+ for (const path of ['src/main.c', 'manage.py', 'app.ts', 'Makefile', 'run.sh', 'index.html']) expect(isDataFile(path), path).toBe(false);+ });++ it('lists the top-level keys of a YAML file with the keys right below them', () => {+ expect(fileFactLines('docker-compose.yml', 'version: "3"\nservices:\n web:\n image: nginx\n db:\n image: postgres\nvolumes:\n data: {}\n')).toEqual([+ 'File kind: YAML configuration, not program code; 8 lines.',+ 'Top-level keys (3): `version`, `services` (2 keys: `web`, `db`), `volumes` (1 key: `data`).',+ ]);+ });++ it('reads a JSON file with JSON.parse: keys and what their values are', () => {+ expect(fileFactLines('package.json', '{"name": "demo", "private": true, "scripts": {"build": "tsc", "test": "vitest"}, "files": ["dist", "src"]}')).toEqual([+ 'File kind: JSON data, not program code; 1 line.',+ 'Top-level keys (4): `name` (text), `private` (true or false), `scripts` (2 keys: `build`, `test`), `files` (list of 2).',+ ]);+ expect(fileFactLines('data.json', '[1, 2, 3]')).toEqual(['File kind: JSON data, not program code; 1 line.', 'A list of 3 items.']);+ expect(fileFactLines('broken.json', '{"name": ')).toEqual(['File kind: JSON data, not program code; 1 line.', 'The text is not valid JSON, so no keys are counted.']);+ });++ it('lists the tables of a TOML file and the keys before the first one', () => {+ expect(fileFactLines('pyproject.toml', 'requires-python = ">=3.10"\n\n[project]\nname = "demo"\nversion = "1.0"\n\n[tool.ruff]\nline-length = 88\n\n[[tool.mypy.overrides]]\nmodule = "a"\n')).toEqual([+ 'File kind: TOML configuration, not program code; 11 lines.',+ 'Top-level keys (1): `requires-python`.',+ 'Tables (3): `[project]` (2 keys), `[tool.ruff]` (1 key), `[[tool.mypy.overrides]]` (1 key).',+ ]);+ });++ it('lists the sections of an INI file, and the keys of a file without sections', () => {+ expect(fileFactLines('setup.cfg', '[metadata]\nname = demo\nversion = 1\n\n; a comment\n[options]\npackages = find:\n')).toEqual([+ 'File kind: INI configuration, not program code; 7 lines.',+ 'Sections (2): `[metadata]` (2 keys), `[options]` (1 key).',+ ]);+ expect(fileFactLines('.env', '# local\nDEBUG=1\nSECRET_KEY=x\n')).toContain('Keys (2): `DEBUG`, `SECRET_KEY`.');+ });++ it('names the title and sections of a Markdown file, not the lines of its code blocks', () => {+ expect(fileFactLines('README.md', '# Demo\n\nA demo.\n\n## Install\n\n```sh\n# not a heading\npip install demo\n```\n\n## Usage\n\n### Options\n')).toEqual([+ 'File kind: Markdown text, not program code; 14 lines.',+ 'Title: `Demo`.',+ 'Sections (2): `Install`, `Usage`.',+ '1 code block.',+ ]);+ });++ it('counts the patterns of an ignore file and names the root element of an XML file', () => {+ expect(fileFactLines('.gitignore', '*.pyc\n# comment\n\n/build\n')).toEqual(['File kind: ignore patterns, not program code; 4 lines.', '2 patterns: `*.pyc`, `/build`.']);+ expect(fileFactLines('pom.xml', '<?xml version="1.0"?>\n<!-- c -->\n<project>\n <modelVersion>4</modelVersion>\n</project>\n')).toContain('Root element: `<project>`.');+ });++ it('says nothing about program code and keeps the workflow facts for a workflow', () => {+ expect(fileFactLines('manage.py', 'import os\n')).toEqual([]);+ const workflow = 'name: CI\non: [push]\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - run: make\n';+ expect(fileFactLines('.github/workflows/ci.yml', workflow)).toEqual(['Workflow name: `CI`.', 'Trigger: `push`.', '1 job: `test` (runs on ubuntu-latest, 1 step).']);+ });++ it('describes a marked part or a cut excerpt as what it is', () => {+ expect(readerFacts(reader('docker-compose.yml', 'services:\n web:\n image: nginx\n', 'selection', [2, 4]))).toEqual([+ 'Selected lines 2-4 of the file.',+ 'Top-level keys (1): `services` (1 key: `web`).',+ ]);+ expect(readerFacts(reader('big.json', '{"a": 1', 'file', [1, 1], 'Only the first 6,000 characters were read.'))).toEqual([+ 'File kind: JSON data, not program code.',+ 'Only the first 6,000 characters were read.',+ ]);+ expect(readerFacts(reader('manage.py', 'import os\n'))).toEqual([]);+ });+});diff --git a/graph-ui/src/browser-ai/file-facts.ts b/graph-ui/src/browser-ai/file-facts.tsnew file mode 100644index 000000000..0ebaa12d6--- /dev/null+++ b/graph-ui/src/browser-ai/file-facts.ts@@ -0,0 +1,157 @@+import type { BrowserChatReaderContext } from './chat-model';+import { fileKind, isDataFile, isGithubWorkflow } from './file-kind';+import { fileWords as words } from './strings';+import { workflowFactLines, yamlOutline } from './workflow-facts';++/** A configuration or text file as facts read from its text (K12). The automatic Explore card+ * of such a file is these facts and nothing else: a small model wrote "allows us to interact+ * with GitHub repositories from the command line" and "a simple shell script that greets"+ * next to the counted facts of a workflow. Each kind is read as far as its plain layout goes,+ * without a parser library; what cannot be read is left out, never guessed. */+export { isDataFile } from './file-kind';++const LISTED = 12;+const CHILDREN = 6;+const quote = (value: string) => `\`${value.replace(/`/g, "'").replace(/\s+/g, ' ').trim().slice(0, 120)}\``;+const extension = (path: string) => (path.split('/').pop() ?? path).split('.').slice(1).pop()?.toLowerCase() ?? '';+const lineCount = (text: string) => text ? text.split(/\r?\n/).length - (/\r?\n$/.test(text) ? 1 : 0) : 0;+const rows = (text: string) => text.split(/\r?\n/);++function yamlFacts(text: string): string[] {+ const outline = yamlOutline(text);+ if (!outline.length) return [];+ return [words.topKeys(outline.length, outline.slice(0, LISTED).map(item => `${quote(item.key)}${item.keys.length+ ? ` (${words.children(item.keys.length, item.keys.slice(0, CHILDREN).map(quote))})` : item.items ? ` (${words.list(item.items)})` : ''}`))];+}++function jsonValue(value: unknown): string {+ if (Array.isArray(value)) return words.list(value.length);+ if (value !== null && typeof value === 'object') { const keys = Object.keys(value); return words.children(keys.length, keys.slice(0, CHILDREN).map(quote)); }+ return typeof value === 'string' ? words.value.text : typeof value === 'number' ? words.value.number : typeof value === 'boolean' ? words.value.boolean : words.value.empty;+}+function jsonFacts(text: string): string[] {+ let data: unknown;+ try { data = JSON.parse(text); } catch { return [words.invalidJson]; }+ if (Array.isArray(data)) return [words.items(data.length)];+ if (data === null || typeof data !== 'object') return [];+ const entries = Object.entries(data);+ return [words.topKeys(entries.length, entries.slice(0, LISTED).map(([key, value]) => `${quote(key)} (${jsonValue(value)})`))];+}++/** TOML: the keys before the first table and each table with its number of keys. */+function tomlFacts(text: string): string[] {+ const top: string[] = [];+ const tables: { name: string; keys: number }[] = [];+ let quoted: string | undefined;+ for (const raw of rows(text)) {+ const line = raw.trim();+ // A multi-line string may hold lines that look like keys.+ if (quoted) { if (line.split(quoted).length % 2 === 0) quoted = undefined; continue; }+ if (!line || line.startsWith('#')) continue;+ const table = /^(\[\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/.exec(line);+ if (table) { tables.push({ name: `${table[1]}${table[2]}${table[1] === '[[' ? ']]' : ']'}`, keys: 0 }); continue; }+ const key = /^([A-Za-z0-9_\-."']+)\s*=/.exec(line);+ if (!key) continue;+ const delimiter = ['"""', "'''"].find(mark => line.split(mark).length === 2);+ if (delimiter) quoted = delimiter;+ if (tables.length) tables[tables.length - 1].keys += 1; else top.push(key[1]);+ }+ return [...top.length ? [words.topKeys(top.length, top.slice(0, LISTED).map(quote))] : [],+ ...tables.length ? [words.tables(tables.length, tables.slice(0, LISTED).map(table => `${quote(table.name)} (${words.keyCount(table.keys)})`))] : []];+}++/** INI and its relatives: sections with their number of keys, or the keys of a file without sections. */+function iniFacts(text: string): string[] {+ const sections: { name: string; keys: number }[] = [];+ const loose: string[] = [];+ for (const raw of rows(text)) {+ const line = raw.trim();+ if (!line || line.startsWith('#') || line.startsWith(';')) continue;+ const section = /^\[([^\]]+)\]$/.exec(line);+ if (section) { sections.push({ name: `[${section[1].trim()}]`, keys: 0 }); continue; }+ const key = /^(?:export\s+)?([^=:\s][^=:]*?)\s*[=:]/.exec(line);+ if (!key || /^\s/.test(raw)) continue;+ if (sections.length) sections[sections.length - 1].keys += 1; else loose.push(key[1]);+ }+ if (sections.length) return [words.sections(sections.length, sections.slice(0, LISTED).map(section => `${quote(section.name)} (${words.keyCount(section.keys)})`))];+ return loose.length ? [words.keys(loose.length, loose.slice(0, LISTED).map(quote))] : [];+}++/** Markdown: the title, the second-level sections and the code blocks; lines inside a code block are code. */+function markdownFacts(text: string): string[] {+ let title: string | undefined, fence: string | undefined, blocks = 0;+ const sections: string[] = [];+ const lines = rows(text);+ lines.forEach((raw, index) => {+ const mark = /^\s{0,3}(`{3,}|~{3,})/.exec(raw);+ if (mark) {+ if (!fence) { fence = mark[1][0]; blocks += 1; } else if (mark[1][0] === fence) fence = undefined;+ return;+ }+ if (fence) return;+ const heading = /^\s{0,3}(#{1,6})\s+(.+?)\s*#*\s*$/.exec(raw);+ const underline = /^\s{0,3}(=+|-+)\s*$/.exec(lines[index + 1] ?? '');+ const level = heading ? heading[1].length : underline && raw.trim() && !/^\s{0,3}[-*+>]/.test(raw) ? underline[1][0] === '=' ? 1 : 2 : 0;+ const name = heading ? heading[2] : raw.trim();+ if (level === 1 && !title) title = name;+ else if (level === 2) sections.push(name);+ });+ return [...title ? [words.title(quote(title))] : [], ...sections.length ? [words.sections(sections.length, sections.slice(0, LISTED).map(quote))] : [],+ ...blocks ? [words.codeBlocks(blocks)] : []];+}++/** reStructuredText: a title line is underlined with one repeated punctuation mark. */+function restructuredFacts(text: string): string[] {+ const lines = rows(text);+ const headings = lines.flatMap((line, index) => {+ const below = lines[index + 1] ?? '';+ return line.trim() && /^([=\-~^*#"'+`:.])\1+\s*$/.test(below) && below.trim().length >= line.trim().length ? [line.trim()] : [];+ });+ if (!headings.length) return [];+ const [first, ...rest] = headings;+ return [words.title(quote(first)), ...rest.length ? [words.sections(rest.length, rest.slice(0, LISTED).map(quote))] : []];+}++function patternFacts(text: string): string[] {+ const patterns = rows(text).map(line => line.trim()).filter(line => line && !line.startsWith('#'));+ return patterns.length ? [words.patterns(patterns.length, patterns.slice(0, LISTED).map(quote))] : [];+}++function xmlFacts(text: string): string[] {+ const root = /<([A-Za-z_][\w:.-]*)[\s>/]/.exec(text.replace(/<\?[\s\S]*?\?>|<!--[\s\S]*?-->|<![^>]*>/g, ''));+ return root ? [words.root(quote(`<${root[1]}>`))] : [];+}++/** The structure of the text, by the kind its name gives. */+function structureFacts(path: string, text: string): string[] {+ switch (extension(path)) {+ case 'yml': case 'yaml': return yamlFacts(text);+ case 'json': return jsonFacts(text);+ case 'toml': return tomlFacts(text);+ case 'ini': case 'cfg': case 'conf': case 'env': case 'properties': case 'editorconfig': return iniFacts(text);+ case 'md': return markdownFacts(text);+ case 'rst': return restructuredFacts(text);+ case 'gitignore': case 'dockerignore': case 'gitattributes': return patternFacts(text);+ case 'xml': return xmlFacts(text);+ default: return [];+ }+}++/** The facts of a whole configuration or text file; a workflow keeps its own (jobs, triggers,+ * actions). Program code has none: there the source and the graph speak. */+export function fileFactLines(path: string, text: string): string[] {+ if (!isDataFile(path)) return [];+ const workflow = isGithubWorkflow(path) ? workflowFactLines(path, text) : [];+ if (workflow.length) return workflow;+ return [words.kind(fileKind(path)!, lineCount(text)), ...structureFacts(path, text)];+}++/** What the open file shows: a whole file in full, a marked part as that part, a cut+ * excerpt only by its kind and the note on what was left out. */+export function readerFacts(reader: BrowserChatReaderContext | undefined): string[] {+ const source = reader?.source;+ if (!source || !isDataFile(source.path)) return [];+ if (source.kind === 'selection') return [words.selected(source.startLine, source.endLine), ...structureFacts(source.path, source.text)];+ if (source.partial) return [words.kind(fileKind(source.path)!), source.partial];+ return fileFactLines(source.path, source.text);+}diff --git a/graph-ui/src/browser-ai/file-kind.ts b/graph-ui/src/browser-ai/file-kind.tsindex 1d957b609..c02924312 100644--- a/graph-ui/src/browser-ai/file-kind.ts+++ b/graph-ui/src/browser-ai/file-kind.ts@@ -9,8 +9,14 @@ const KINDS: Readonly<Record<string, string>> = {mjs: 'JavaScript source file', jsx: 'JavaScript source file', c: 'C source file', h: 'C header file', cc: 'C++ source file', cpp: 'C++ source file',hpp: 'C++ header file', go: 'Go source file', rs: 'Rust source file', java: 'Java source file', rb: 'Ruby source file', sh: 'shell script',html: 'HTML document', css: 'CSS stylesheet', sql: 'SQL script', xml: 'XML data, not program code',+ conf: 'configuration file, not program code', env: 'environment settings, not program code', properties: 'Java properties, not program code',+ editorconfig: 'EditorConfig settings, not program code', gitignore: 'ignore patterns, not program code', dockerignore: 'ignore patterns, not program code',+ gitattributes: 'Git attribute patterns, not program code',};+/** Configuration, data and text files: what they say is read from them, not guessed by a model (K12). */+export const isDataFile = (path: string): boolean => /not program code/.test(fileKind(path) ?? '');+/** A GitHub Actions workflow, by where GitHub reads it from. */export const isGithubWorkflow = (path: string): boolean => /(?:^|\/)\.github\/workflows\/[^/]+\.ya?ml$/i.test(path);diff --git a/graph-ui/src/browser-ai/strings.ts b/graph-ui/src/browser-ai/strings.tsindex eb02c72a4..4933a0241 100644--- a/graph-ui/src/browser-ai/strings.ts+++ b/graph-ui/src/browser-ai/strings.ts@@ -235,3 +235,25 @@ export const workflowWords = {`${id} (${[name ? `"${name}"` : '', runsOn ? `runs on ${runsOn}` : '', counted(steps, 'step', 'steps')].filter(Boolean).join(', ')})`,uses: (items: readonly string[]) => `Actions used: ${items.join(', ')}.`,};++const listed = (items: readonly string[], total: number) => `${items.join(', ')}${total > items.length ? `, +${(total - items.length).toLocaleString('en-US')} more` : ''}`;+/** A configuration or text file as facts read from its text: for the prompt and the explanation card (K12). */+export const fileWords = {+ kind: (kind: string, lines?: number) => `File kind: ${kind}${lines === undefined ? '' : `; ${counted(lines, 'line', 'lines')}`}.`,+ selected: (start: number, end: number) => start === end ? `Selected line ${start} of the file.` : `Selected lines ${start}-${end} of the file.`,+ topKeys: (total: number, items: readonly string[]) => `Top-level keys (${total.toLocaleString('en-US')}): ${listed(items, total)}.`,+ keys: (total: number, items: readonly string[]) => `Keys (${total.toLocaleString('en-US')}): ${listed(items, total)}.`,+ /** What a key holds: "(2 keys: `web`, `db`)", "(list of 2)", "(text)". */+ children: (total: number, items: readonly string[]) => total ? `${counted(total, 'key', 'keys')}: ${listed(items, total)}` : 'no keys',+ keyCount: (total: number) => counted(total, 'key', 'keys'),+ list: (total: number) => `list of ${total.toLocaleString('en-US')}`,+ value: { text: 'text', number: 'number', boolean: 'true or false', empty: 'null' },+ items: (total: number) => `A list of ${counted(total, 'item', 'items')}.`,+ invalidJson: 'The text is not valid JSON, so no keys are counted.',+ tables: (total: number, items: readonly string[]) => `Tables (${total.toLocaleString('en-US')}): ${listed(items, total)}.`,+ sections: (total: number, items: readonly string[]) => `Sections (${total.toLocaleString('en-US')}): ${listed(items, total)}.`,+ title: (title: string) => `Title: ${title}.`,+ codeBlocks: (total: number) => `${counted(total, 'code block', 'code blocks')}.`,+ patterns: (total: number, items: readonly string[]) => `${counted(total, 'pattern', 'patterns')}: ${listed(items, total)}.`,+ root: (name: string) => `Root element: ${name}.`,+};diff --git a/graph-ui/src/browser-ai/workflow-facts.ts b/graph-ui/src/browser-ai/workflow-facts.tsindex f46e94470..67bd35005 100644--- a/graph-ui/src/browser-ai/workflow-facts.ts+++ b/graph-ui/src/browser-ai/workflow-facts.ts@@ -1,4 +1,3 @@-import type { BrowserChatReaderContext } from './chat-model';import { isGithubWorkflow } from './file-kind';import { workflowWords as words } from './strings';@@ -66,6 +65,20 @@ function children(lines: readonly Line[], at: number): number[] {return found.filter(index => lines[index].keyIndent === level);}+/** The top-level keys of a YAML file in block layout, each with the keys right below it or+ * the length of the list it holds (K12). Keys inside block values are text, not keys. */+export function yamlOutline(text: string): { key: string; keys: string[]; items: number }[] {+ const lines = linesOf(text);+ if (!lines.length) return [];+ const level = Math.min(...lines.map(line => line.keyIndent));+ return lines.flatMap((line, index) => {+ if (line.keyIndent !== level || line.dash || !line.key) return [];+ const below = line.value ? [] : children(lines, index);+ return [{ key: line.key, keys: below.flatMap(child => !lines[child].dash && lines[child].key ? [lines[child].key!] : []),+ items: below.filter(child => lines[child].dash).length }];+ });+}+export function workflowFacts(text: string): WorkflowFacts | undefined {const lines = linesOf(text);if (!lines.length) return undefined;@@ -106,9 +119,3 @@ export function workflowFactLines(path: string, text: string): string[] {if (facts.uses.length) lines.push(words.uses(facts.uses.slice(0, LISTED).map(quote)));return lines;}--/** Only a whole open file is counted: a marked part or a cut excerpt is not the workflow. */-export function readerFacts(reader: BrowserChatReaderContext | undefined): string[] {- const source = reader?.source;- return source?.kind === 'file' && !source.partial ? workflowFactLines(source.path, source.text) : [];-}