Skip to content

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.

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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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 BrowserChatReaderC
import { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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) : [];
-}