feat(ui): saved trails — a walk you named, kept, and still true after a re-index (CG-60)
Save trail on the trail bar writes the walk to .codegraph/ui/trails/ as one JSON file, listed on the empty screen and on Entry points above the derived suggestions, reopened at the symbol you left with the whole path restored. A hop is stored by qualified name, kind and file — never by node id, which contains a start line and so changes the first time anybody edits above the symbol. Every hop is re-resolved against the current index on the way out and each row says what became of it: still here, moved to another file, now ambiguous, or gone. A hole is never stitched over: the row opens the longest run of CONSECUTIVE resolved hops and says which ones those are, because the trail is a path and a skipped hop would draw a call that does not exist. This is the first write the viewer makes, and the boundary moved with it: POST/DELETE answer under /api/ only, must carry X-CodeGraph-UI and application/json (neither of which a cross-origin form can produce without a preflight this server answers none of), and --read-only refuses both while still listing what is there. The blanket "read-only" claim is retired from the banner, the README, the CLI help and the docs site in favour of the narrower true one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Colby McHenry
co-authored by
Claude Opus 5
Claude Opus 5
parent
55a33055ee
commit
47576b392e
@@ -28,6 +28,7 @@ import {
|
||||
FlowStrip,
|
||||
SearchPalette,
|
||||
SymbolView,
|
||||
SavedTrails,
|
||||
TrailBar,
|
||||
TypeHierarchy,
|
||||
createHttpAdapter,
|
||||
@@ -406,8 +407,22 @@ function mockAdapter(): { adapter: GraphAdapter; calls: string[] } {
|
||||
corroborated: true,
|
||||
timing: { elapsedMs: 1 },
|
||||
}),
|
||||
// Deliberately no `events`: a host without a live channel is the normal
|
||||
// case, and nothing may poll in its absence.
|
||||
trails: () =>
|
||||
seen('trails', {
|
||||
trails: [],
|
||||
// A host with nowhere to keep trails still ANSWERS the question — it
|
||||
// says it is read-only rather than omitting the method, so the screens
|
||||
// show the section explained instead of showing a Save that does
|
||||
// nothing.
|
||||
readOnly: true,
|
||||
readOnlyReason: 'This host does not store trails.',
|
||||
directory: '.codegraph/ui/trails',
|
||||
skipped: 0,
|
||||
bounded: false,
|
||||
}),
|
||||
// Deliberately no `events`, `saveTrail` or `deleteTrail`: a host without a
|
||||
// live channel and without anywhere to write is the normal case, and
|
||||
// nothing may poll or offer to save in their absence.
|
||||
};
|
||||
return { adapter, calls };
|
||||
}
|
||||
@@ -601,6 +616,27 @@ describe('@colbymchenry/codegraph-ui — a host renders the package', () => {
|
||||
expect(host.querySelector('input[role="combobox"]')).not.toBeNull();
|
||||
});
|
||||
|
||||
it('offers no Save when the adapter cannot write, and says why in the list', async () => {
|
||||
const { adapter } = mockAdapter();
|
||||
setGraphAdapter(adapter);
|
||||
|
||||
trail.push({ id: SYMBOL.node.id, name: 'parseToken', kind: 'function', dir: 'start' });
|
||||
await render(TrailBar, {});
|
||||
// The one screen affordance that must never appear against a read-only
|
||||
// host: an adapter with no `saveTrail` has no button, not a button that
|
||||
// fails.
|
||||
expect(host.textContent ?? '').not.toContain('Save trail');
|
||||
|
||||
void unmount(mounted as Record<string, unknown>);
|
||||
mounted = null;
|
||||
host.innerHTML = '';
|
||||
|
||||
await render(SavedTrails, { hideWhenEmpty: false });
|
||||
const text = host.textContent ?? '';
|
||||
expect(text).toContain('Saved trails');
|
||||
expect(text).toContain('This host does not store trails.');
|
||||
});
|
||||
|
||||
it('CodegraphUi installs the adapter before its children ask for data', async () => {
|
||||
const { adapter, calls } = mockAdapter();
|
||||
// NOT installed by hand — the provider is the only thing that installs it.
|
||||
|
||||
@@ -258,7 +258,10 @@ afterAll(async () => {
|
||||
describe('GET /api', () => {
|
||||
it('lists the endpoints it answers', async () => {
|
||||
const body = await getJson('/api');
|
||||
expect(body.readOnly).toBe(true);
|
||||
// Not a blanket claim any more (CG-60): saved trails are the one thing
|
||||
// this server writes, and it names it rather than implying there is none.
|
||||
expect(body.readOnly).toBe(false);
|
||||
expect(body.writes).toEqual(['POST /api/trails', 'DELETE /api/trails/<id>']);
|
||||
const paths = body.endpoints.map((e: any) => e.path);
|
||||
expect(paths).toEqual(
|
||||
expect.arrayContaining([
|
||||
|
||||
@@ -266,14 +266,44 @@ describe('codegraph ui server', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('read-only', () => {
|
||||
it('refuses every method that is not GET or HEAD', async () => {
|
||||
for (const method of ['POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']) {
|
||||
describe('methods', () => {
|
||||
it('refuses every method it has never answered', async () => {
|
||||
for (const method of ['PUT', 'PATCH', 'OPTIONS', 'TRACE']) {
|
||||
const res = await request(server.port, '/', { method });
|
||||
expect(res.status, method).toBe(405);
|
||||
expect(res.headers['allow']).toBe('GET, HEAD, POST, DELETE');
|
||||
}
|
||||
});
|
||||
|
||||
/**
|
||||
* The static side stayed a pure reader when `/api/trails` gained a write
|
||||
* (CG-60). A POST at an asset path is 405 with `Allow: GET, HEAD` — the
|
||||
* narrower answer, since nothing under the viewer bundle will ever take
|
||||
* one.
|
||||
*/
|
||||
it('refuses a write outside /api/, whatever it carries', async () => {
|
||||
for (const method of ['POST', 'DELETE']) {
|
||||
const res = await request(server.port, '/', {
|
||||
method,
|
||||
headers: { 'X-CodeGraph-UI': '1' },
|
||||
});
|
||||
expect(res.status, method).toBe(405);
|
||||
expect(res.headers['allow']).toBe('GET, HEAD');
|
||||
}
|
||||
});
|
||||
|
||||
/**
|
||||
* Under `/api/` a write is answered as JSON even when refused — the viewer
|
||||
* parses these, and a text/plain body surfaces as a parse error rather than
|
||||
* the refusal it is. No API is mounted on this server, so the refusal is
|
||||
* the boundary's own and not an endpoint's.
|
||||
*/
|
||||
it('refuses an unmarked write under /api/ as JSON', async () => {
|
||||
const res = await request(server.port, '/api/trails', { method: 'POST' });
|
||||
expect(res.status).toBe(403);
|
||||
expect(res.headers['content-type']).toContain('application/json');
|
||||
expect(JSON.parse(res.body).code).toBe('refused');
|
||||
});
|
||||
});
|
||||
|
||||
describe('paths outside the asset root', () => {
|
||||
|
||||
@@ -0,0 +1,179 @@
|
||||
/**
|
||||
* What a saved trail's row says, without a browser (CG-60).
|
||||
*
|
||||
* The endpoint's own behaviour is pinned in `ui-trails.test.ts` against a real
|
||||
* index; this is the wording layer, and the rule it exists to protect is that
|
||||
* **a trail that has decayed never reads as intact**. A saved trail is somebody's
|
||||
* explanation of a codebase that has since moved underneath it, and a row that
|
||||
* prints "6 hops" while two of them are gone is a lie by omission at exactly the
|
||||
* moment the trail needs fixing.
|
||||
*/
|
||||
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
hopStatusWord,
|
||||
isOpenable,
|
||||
replacedTrail,
|
||||
trailDecay,
|
||||
trailExport,
|
||||
trailMeta,
|
||||
trailNameProblem,
|
||||
trailOpens,
|
||||
trailTitle,
|
||||
} from '../ui/src/lib/trails-model';
|
||||
import type { WireTrail, WireTrailHop, WireTrailHopStatus } from '../ui/src/lib/wire';
|
||||
|
||||
function hop(
|
||||
name: string,
|
||||
status: WireTrailHopStatus = 'ok',
|
||||
dir: WireTrailHop['dir'] = 'down'
|
||||
): WireTrailHop {
|
||||
const alive = status !== 'missing';
|
||||
return {
|
||||
dir,
|
||||
name,
|
||||
qualifiedName: name,
|
||||
kind: 'function',
|
||||
savedFile: 'src/a.ts',
|
||||
savedLine: 10,
|
||||
status,
|
||||
id: alive ? `function:${name}` : null,
|
||||
file: alive ? 'src/a.ts' : null,
|
||||
line: alive ? 10 : null,
|
||||
note: status === 'ok' ? null : `${name} ${status}`,
|
||||
};
|
||||
}
|
||||
|
||||
function trail(hops: WireTrailHop[], over: Partial<WireTrail> = {}): WireTrail {
|
||||
const resolved = hops.filter((h) => h.id !== null);
|
||||
return {
|
||||
id: 'a-walk',
|
||||
name: 'A walk',
|
||||
note: '',
|
||||
author: 'Ada',
|
||||
createdAt: '2026-08-01T00:00:00.000Z',
|
||||
updatedAt: '2026-08-02T00:00:00.000Z',
|
||||
hops,
|
||||
resolved: resolved.length,
|
||||
intact: hops.every((h) => h.status === 'ok'),
|
||||
encoded: resolved.length > 0 ? resolved.map((h) => `d${h.id}`).join(',') : null,
|
||||
openFrom: 1,
|
||||
openCount: resolved.length,
|
||||
openId: resolved.length > 0 ? (resolved[resolved.length - 1] as WireTrailHop).id : null,
|
||||
...over,
|
||||
};
|
||||
}
|
||||
|
||||
describe('trailMeta', () => {
|
||||
it('reports the SAVED length, whatever became of the hops', () => {
|
||||
const decayed = trail([hop('a', 'ok', 'start'), hop('b', 'missing'), hop('c')]);
|
||||
expect(trailMeta(decayed)).toBe('3 hops · Ada');
|
||||
});
|
||||
|
||||
it('drops the author when there is not one', () => {
|
||||
expect(trailMeta(trail([hop('a', 'ok', 'start')], { author: '' }))).toBe('1 hop');
|
||||
});
|
||||
});
|
||||
|
||||
describe('trailDecay', () => {
|
||||
it('is null for a trail nothing has happened to', () => {
|
||||
expect(trailDecay(trail([hop('a', 'ok', 'start'), hop('b')]))).toBeNull();
|
||||
});
|
||||
|
||||
it('warns about hops that are gone, naming them', () => {
|
||||
const decay = trailDecay(trail([hop('a', 'ok', 'start'), hop('gone', 'missing')]));
|
||||
expect(decay?.tone).toBe('warn');
|
||||
expect(decay?.text).toContain('1 hop moved or renamed');
|
||||
expect(decay?.text).toContain('gone');
|
||||
});
|
||||
|
||||
it('caps how many it names', () => {
|
||||
const hops = ['a', 'b', 'c', 'd', 'e'].map((n) => hop(n, 'missing'));
|
||||
const decay = trailDecay(trail(hops));
|
||||
expect(decay?.text).toContain('and 2 more');
|
||||
});
|
||||
|
||||
it('notes a move without warning about it — a moved hop still opens', () => {
|
||||
const decay = trailDecay(trail([hop('a', 'ok', 'start'), hop('b', 'moved')]));
|
||||
expect(decay?.tone).toBe('note');
|
||||
expect(decay?.text).toContain('moved to another file');
|
||||
});
|
||||
|
||||
it('puts a missing hop ahead of a merely moved one', () => {
|
||||
const decay = trailDecay(trail([hop('m', 'moved'), hop('g', 'missing')]));
|
||||
expect(decay?.text).toContain('moved or renamed');
|
||||
});
|
||||
|
||||
it('warns about an ambiguous hop — the trail may no longer mean what it said', () => {
|
||||
const decay = trailDecay(trail([hop('a', 'ok', 'start'), hop('b', 'ambiguous')]));
|
||||
expect(decay?.tone).toBe('warn');
|
||||
expect(decay?.text).toContain('more than one symbol');
|
||||
});
|
||||
});
|
||||
|
||||
describe('trailOpens', () => {
|
||||
it('says nothing when the whole trail opens', () => {
|
||||
expect(trailOpens(trail([hop('a', 'ok', 'start'), hop('b')]))).toBeNull();
|
||||
});
|
||||
|
||||
it('names the range when only part of it does', () => {
|
||||
const partial = trail([hop('a'), hop('b'), hop('c')], {
|
||||
openFrom: 2,
|
||||
openCount: 2,
|
||||
});
|
||||
expect(trailOpens(partial)).toBe('Opens hops 2–3 of 3.');
|
||||
});
|
||||
|
||||
it('says so plainly when nothing resolves', () => {
|
||||
const dead = trail([hop('a', 'missing')], { encoded: null, openCount: 0, openId: null });
|
||||
expect(trailOpens(dead)).toContain('None of this trail resolves');
|
||||
expect(isOpenable(dead)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('trailTitle', () => {
|
||||
it('draws the whole walk with its arrows, and when it was saved', () => {
|
||||
const walked = trail([hop('a', 'ok', 'start'), hop('b', 'ok', 'down'), hop('c', 'ok', 'up')]);
|
||||
expect(trailTitle(walked)).toBe('a → b ← c — saved 2026-08-02');
|
||||
});
|
||||
});
|
||||
|
||||
describe('saving', () => {
|
||||
it('refuses an empty or over-long name before the round-trip', () => {
|
||||
expect(trailNameProblem(' ', 120)).toContain('name');
|
||||
expect(trailNameProblem('x'.repeat(121), 120)).toContain('too long');
|
||||
expect(trailNameProblem('ok', 120)).toBeNull();
|
||||
});
|
||||
|
||||
it('spots the trail a name would replace, whitespace and all', () => {
|
||||
const list = [trail([hop('a', 'ok', 'start')], { name: 'A walk' })];
|
||||
expect(replacedTrail(' A walk ', list)?.name).toBe('A walk');
|
||||
expect(replacedTrail('Another walk', list)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('trailExport', () => {
|
||||
it('exports the SAVED identity of each hop, not today’s resolution', () => {
|
||||
const moved = trail([hop('a', 'ok', 'start'), hop('b', 'moved')]);
|
||||
const raw = JSON.parse(trailExport(moved));
|
||||
expect(raw.version).toBe(1);
|
||||
// `savedFile`, so dropping the file into another checkout re-runs the same
|
||||
// resolution rather than baking this index's answer in.
|
||||
expect(raw.hops[1].file).toBe('src/a.ts');
|
||||
expect(raw.hops[1].qualifiedName).toBe('b');
|
||||
expect(raw.hops.map((h: { dir: string }) => h.dir)).toEqual(['start', 'down']);
|
||||
});
|
||||
|
||||
it('survives a hop with no id at all', () => {
|
||||
const raw = JSON.parse(trailExport(trail([hop('gone', 'missing')])));
|
||||
expect(raw.hops[0].id).toBe('');
|
||||
});
|
||||
});
|
||||
|
||||
describe('hopStatusWord', () => {
|
||||
it('has a word for every status', () => {
|
||||
for (const status of ['ok', 'moved', 'ambiguous', 'missing'] as const) {
|
||||
expect(hopStatusWord(status)).toBeTruthy();
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,562 @@
|
||||
/**
|
||||
* Saved trails (CG-60) — the viewer's only write.
|
||||
*
|
||||
* Two things are worth a real end-to-end fixture rather than a unit test, and
|
||||
* they are the two the feature exists for:
|
||||
*
|
||||
* 1. **A trail survives a re-index.** The suite indexes a project, saves a
|
||||
* trail, then EDITS the files so every node id changes (a symbol shifts down
|
||||
* a file, another moves to a different file, a third is deleted), re-indexes,
|
||||
* and asserts the trail still opens and says what became of each hop. That
|
||||
* cannot be faked: node ids contain a start line, so the ids really do all
|
||||
* change.
|
||||
* 2. **The write boundary.** `POST` without the marker header, from a foreign
|
||||
* `Origin`, or against a `--read-only` server has to be refused — by a real
|
||||
* loopback server, because the refusals live in the request handler and not
|
||||
* in the endpoint.
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
|
||||
import * as http from 'http';
|
||||
import * as fs from 'fs';
|
||||
import * as os from 'os';
|
||||
import * as path from 'path';
|
||||
import CodeGraph from '../src/index';
|
||||
import { createGraphApi, startUiServer, type GraphApi, type UiServerHandle } from '../src/ui-server';
|
||||
import {
|
||||
encodeResolvedRun,
|
||||
isTrailId,
|
||||
parseTrail,
|
||||
slugify,
|
||||
TRAILS_RELATIVE_DIR,
|
||||
type WireTrailHop,
|
||||
} from '../src/ui-server/api';
|
||||
|
||||
interface Res {
|
||||
status: number;
|
||||
headers: http.IncomingHttpHeaders;
|
||||
body: any;
|
||||
}
|
||||
|
||||
let tempDir: string;
|
||||
let projectRoot: string;
|
||||
let viewerDir: string;
|
||||
let api: GraphApi;
|
||||
let server: UiServerHandle;
|
||||
let readOnlyApi: GraphApi;
|
||||
let readOnlyServer: UiServerHandle;
|
||||
|
||||
interface CallOptions {
|
||||
method?: string;
|
||||
body?: unknown;
|
||||
/** Send the write marker header. On by default for a write. */
|
||||
marker?: boolean;
|
||||
contentType?: string | null;
|
||||
origin?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* One request against a live server.
|
||||
*
|
||||
* `http.request` rather than `fetch` so `Host` is ours to set — undici treats
|
||||
* it as a forbidden header, and the `Host` allowlist is half of what is being
|
||||
* tested here.
|
||||
*/
|
||||
function callOn(port: number, requestPath: string, opts: CallOptions = {}): Promise<Res> {
|
||||
const method = opts.method ?? 'GET';
|
||||
const isWrite = method === 'POST' || method === 'DELETE';
|
||||
const payload = opts.body === undefined ? null : Buffer.from(JSON.stringify(opts.body), 'utf-8');
|
||||
const headers: Record<string, string> = { Host: `127.0.0.1:${port}` };
|
||||
if (isWrite && (opts.marker ?? true)) headers['X-CodeGraph-UI'] = '1';
|
||||
if (opts.origin) headers['Origin'] = opts.origin;
|
||||
if (payload) {
|
||||
const type = opts.contentType === undefined ? 'application/json' : opts.contentType;
|
||||
if (type !== null) headers['Content-Type'] = type;
|
||||
headers['Content-Length'] = String(payload.length);
|
||||
}
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
const req = http.request(
|
||||
{ host: '127.0.0.1', port, path: requestPath, method, headers, setHost: false },
|
||||
(res) => {
|
||||
const chunks: Buffer[] = [];
|
||||
res.on('data', (c: Buffer) => chunks.push(c));
|
||||
res.on('end', () => {
|
||||
const text = Buffer.concat(chunks).toString('utf-8');
|
||||
let parsed: unknown = text;
|
||||
try {
|
||||
parsed = JSON.parse(text);
|
||||
} catch {
|
||||
/* a text/plain refusal is a legitimate answer on the static side */
|
||||
}
|
||||
resolve({ status: res.statusCode ?? 0, headers: res.headers, body: parsed });
|
||||
});
|
||||
}
|
||||
);
|
||||
req.on('error', reject);
|
||||
if (payload) req.write(payload);
|
||||
req.end();
|
||||
});
|
||||
}
|
||||
|
||||
function call(requestPath: string, opts: CallOptions = {}): Promise<Res> {
|
||||
return callOn(server.port, requestPath, opts);
|
||||
}
|
||||
|
||||
/** The id of a fixture symbol, looked up through the API itself. */
|
||||
async function idOf(name: string): Promise<string> {
|
||||
const res = await call(`/api/search?q=${encodeURIComponent(name)}`);
|
||||
const hit = res.body.results.items.find((r: any) => r.name === name);
|
||||
expect(hit, `no symbol named ${name}`).toBeTruthy();
|
||||
return hit.id as string;
|
||||
}
|
||||
|
||||
function trailsDir(): string {
|
||||
return path.join(projectRoot, TRAILS_RELATIVE_DIR);
|
||||
}
|
||||
|
||||
/** Re-index in place, the way a `codegraph sync` would after an edit. */
|
||||
async function reindex(): Promise<void> {
|
||||
const cg = CodeGraph.openSync(projectRoot);
|
||||
await cg.sync();
|
||||
cg.resolveReferences();
|
||||
cg.close();
|
||||
}
|
||||
|
||||
const SRC = () => path.join(projectRoot, 'src');
|
||||
|
||||
beforeAll(async () => {
|
||||
tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-trails-'));
|
||||
projectRoot = path.join(tempDir, 'project');
|
||||
fs.mkdirSync(SRC(), { recursive: true });
|
||||
|
||||
fs.writeFileSync(
|
||||
path.join(SRC(), 'handler.ts'),
|
||||
`import { load } from './service';
|
||||
|
||||
export function handleRequest(key: string): string {
|
||||
return load(key);
|
||||
}
|
||||
`
|
||||
);
|
||||
fs.writeFileSync(
|
||||
path.join(SRC(), 'service.ts'),
|
||||
`import { read } from './cache';
|
||||
|
||||
export function load(key: string): string {
|
||||
return read(key);
|
||||
}
|
||||
|
||||
export function retired(): string {
|
||||
return 'nothing calls me after the edit';
|
||||
}
|
||||
`
|
||||
);
|
||||
fs.writeFileSync(
|
||||
path.join(SRC(), 'cache.ts'),
|
||||
`export function read(key: string): string {
|
||||
return key;
|
||||
}
|
||||
`
|
||||
);
|
||||
|
||||
const cg = CodeGraph.initSync(projectRoot, {
|
||||
config: { include: ['src/**/*.ts'], exclude: [] },
|
||||
});
|
||||
await cg.indexAll();
|
||||
cg.resolveReferences();
|
||||
cg.close();
|
||||
|
||||
viewerDir = path.join(tempDir, 'viewer');
|
||||
fs.mkdirSync(viewerDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(viewerDir, 'index.html'), '<!doctype html><div id="app"></div>');
|
||||
|
||||
api = createGraphApi({ projectRoot });
|
||||
server = await startUiServer({ projectRoot, viewerDir, port: 0, api: api.handler });
|
||||
|
||||
readOnlyApi = createGraphApi({
|
||||
projectRoot,
|
||||
readOnly: true,
|
||||
readOnlyReason: 'This viewer was started with --read-only, so trails cannot be saved.',
|
||||
});
|
||||
readOnlyServer = await startUiServer({
|
||||
projectRoot,
|
||||
viewerDir,
|
||||
port: 0,
|
||||
api: readOnlyApi.handler,
|
||||
});
|
||||
}, 120_000);
|
||||
|
||||
afterAll(async () => {
|
||||
api?.close();
|
||||
readOnlyApi?.close();
|
||||
await server?.close();
|
||||
await readOnlyServer?.close();
|
||||
if (tempDir && fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
/* ------------------------------------------------------------- pure bits -- */
|
||||
|
||||
describe('trail ids', () => {
|
||||
it('slugs a name into something that is a filename and not a path', () => {
|
||||
expect(slugify('How a request reaches the handler')).toBe(
|
||||
'how-a-request-reaches-the-handler'
|
||||
);
|
||||
expect(slugify(' Spaces and --- dashes ')).toBe('spaces-and-dashes');
|
||||
expect(slugify('../../etc/passwd')).toBe('etc-passwd');
|
||||
// A name with no ASCII word characters still has to produce a valid id.
|
||||
expect(slugify('日本語')).toBe('trail');
|
||||
expect(isTrailId(slugify('../../etc/passwd'))).toBe(true);
|
||||
});
|
||||
|
||||
it('refuses anything that is not a slug', () => {
|
||||
for (const bad of ['..', 'a/b', 'A', 'has.dot', '-leading', '', 'a b']) {
|
||||
expect(isTrailId(bad), bad).toBe(false);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('parseTrail', () => {
|
||||
it('rejects a file that is not a trail rather than half-reading it', () => {
|
||||
expect(parseTrail('x', 'not json')).toBeNull();
|
||||
expect(parseTrail('x', '[]')).toBeNull();
|
||||
expect(parseTrail('x', '{"name":"a"}')).toBeNull();
|
||||
expect(parseTrail('x', '{"name":"a","hops":[]}')).toBeNull();
|
||||
expect(parseTrail('x', '{"name":"","hops":[{"qualifiedName":"a"}]}')).toBeNull();
|
||||
});
|
||||
|
||||
it('takes its id from the FILE, not from the field inside it', () => {
|
||||
const trail = parseTrail('on-disk', '{"name":"a","id":"remembered","hops":[{"name":"f"}]}');
|
||||
expect(trail?.id).toBe('on-disk');
|
||||
});
|
||||
});
|
||||
|
||||
describe('encodeResolvedRun', () => {
|
||||
const hop = (id: string | null, dir: 'start' | 'down' | 'up' = 'down'): WireTrailHop => ({
|
||||
dir,
|
||||
name: id ?? 'gone',
|
||||
qualifiedName: id ?? 'gone',
|
||||
kind: 'function',
|
||||
savedFile: 'src/a.ts',
|
||||
savedLine: 1,
|
||||
status: id ? 'ok' : 'missing',
|
||||
id,
|
||||
file: id ? 'src/a.ts' : null,
|
||||
line: id ? 1 : null,
|
||||
note: null,
|
||||
});
|
||||
|
||||
it('never stitches across a hole — it takes the longest consecutive run', () => {
|
||||
const run = encodeResolvedRun([hop('a', 'start'), hop(null), hop('c'), hop('d')]);
|
||||
expect(run.encoded).toBe('sc,dd');
|
||||
expect(run.openFrom).toBe(3);
|
||||
expect(run.openCount).toBe(2);
|
||||
expect(run.openId).toBe('d');
|
||||
});
|
||||
|
||||
it('writes the run’s first hop as a start, whatever it was saved as', () => {
|
||||
const run = encodeResolvedRun([hop(null), hop('b', 'up')]);
|
||||
expect(run.encoded).toBe('sb');
|
||||
});
|
||||
|
||||
it('answers nothing when nothing resolves', () => {
|
||||
expect(encodeResolvedRun([hop(null), hop(null)])).toEqual({
|
||||
encoded: null,
|
||||
openFrom: 0,
|
||||
openCount: 0,
|
||||
openId: null,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
/* ----------------------------------------------------------- the endpoint -- */
|
||||
|
||||
describe('GET /api/trails', () => {
|
||||
it('is an empty list, not an error, before anything is saved', async () => {
|
||||
const res = await call('/api/trails');
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body.trails).toEqual([]);
|
||||
expect(res.body.readOnly).toBe(false);
|
||||
expect(res.body.directory).toBe(TRAILS_RELATIVE_DIR);
|
||||
});
|
||||
|
||||
it('is listed by GET /api', async () => {
|
||||
const res = await call('/api');
|
||||
expect(res.body.endpoints.some((e: any) => e.path === '/api/trails')).toBe(true);
|
||||
// The old blanket claim is gone: the server writes exactly one thing.
|
||||
expect(res.body.readOnly).toBe(false);
|
||||
expect(res.body.writes).toContain('POST /api/trails');
|
||||
});
|
||||
});
|
||||
|
||||
describe('POST /api/trails', () => {
|
||||
it('saves the walk and answers with the whole list', async () => {
|
||||
const hops = [
|
||||
{ dir: 'start', id: await idOf('handleRequest') },
|
||||
{ dir: 'down', id: await idOf('load') },
|
||||
{ dir: 'down', id: await idOf('read') },
|
||||
];
|
||||
const res = await call('/api/trails', {
|
||||
method: 'POST',
|
||||
body: { name: 'How a request is served', note: 'the whole path', hops },
|
||||
});
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body.saved).toBe('how-a-request-is-served');
|
||||
expect(res.body.replaced).toBe(false);
|
||||
expect(res.body.trails).toHaveLength(1);
|
||||
|
||||
const trail = res.body.trails[0];
|
||||
expect(trail.name).toBe('How a request is served');
|
||||
expect(trail.note).toBe('the whole path');
|
||||
expect(trail.intact).toBe(true);
|
||||
expect(trail.resolved).toBe(3);
|
||||
expect(trail.openCount).toBe(3);
|
||||
expect(trail.hops.map((h: any) => h.name)).toEqual(['handleRequest', 'load', 'read']);
|
||||
// The identity that survives an edit, recorded beside the id hint.
|
||||
expect(trail.hops[1].qualifiedName).toBe('load');
|
||||
expect(trail.hops[1].savedFile).toBe('src/service.ts');
|
||||
});
|
||||
|
||||
it('writes one readable JSON file into .codegraph/ui/trails', () => {
|
||||
const file = path.join(trailsDir(), 'how-a-request-is-served.json');
|
||||
expect(fs.existsSync(file)).toBe(true);
|
||||
const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
|
||||
expect(raw.version).toBe(1);
|
||||
expect(raw.hops).toHaveLength(3);
|
||||
expect(raw.hops[0].qualifiedName).toBe('handleRequest');
|
||||
expect(typeof raw.createdAt).toBe('string');
|
||||
// Nothing but trails lands there — no temp file survives the rename.
|
||||
expect(fs.readdirSync(trailsDir())).toEqual(['how-a-request-is-served.json']);
|
||||
});
|
||||
|
||||
it('replaces a trail saved under the same name, keeping its createdAt', async () => {
|
||||
const before = (await call('/api/trails')).body.trails[0];
|
||||
const res = await call('/api/trails', {
|
||||
method: 'POST',
|
||||
body: {
|
||||
name: 'How a request is served',
|
||||
hops: [{ dir: 'start', id: await idOf('handleRequest') }],
|
||||
},
|
||||
});
|
||||
expect(res.body.replaced).toBe(true);
|
||||
expect(res.body.trails).toHaveLength(1);
|
||||
expect(res.body.trails[0].createdAt).toBe(before.createdAt);
|
||||
expect(res.body.trails[0].hops).toHaveLength(1);
|
||||
expect(res.body.trails[0].note).toBe('');
|
||||
});
|
||||
|
||||
it('gives a different name its own file rather than colliding', async () => {
|
||||
const res = await call('/api/trails', {
|
||||
method: 'POST',
|
||||
body: { name: 'How a request is served!', hops: [{ dir: 'start', id: await idOf('load') }] },
|
||||
});
|
||||
expect(res.body.saved).toBe('how-a-request-is-served-2');
|
||||
expect(res.body.trails).toHaveLength(2);
|
||||
});
|
||||
|
||||
it('refuses a hop the index does not hold', async () => {
|
||||
const res = await call('/api/trails', {
|
||||
method: 'POST',
|
||||
body: { name: 'invented', hops: [{ dir: 'start', id: 'function:not-a-real-id' }] },
|
||||
});
|
||||
expect(res.status).toBe(400);
|
||||
expect(res.body.error).toContain('Hop 1 is not in the index');
|
||||
});
|
||||
|
||||
it('refuses a nameless or hopless trail', async () => {
|
||||
const noName = await call('/api/trails', { method: 'POST', body: { name: ' ', hops: [] } });
|
||||
expect(noName.status).toBe(400);
|
||||
const noHops = await call('/api/trails', { method: 'POST', body: { name: 'x', hops: [] } });
|
||||
expect(noHops.status).toBe(400);
|
||||
expect(noHops.body.error).toContain('at least one hop');
|
||||
});
|
||||
});
|
||||
|
||||
describe('DELETE /api/trails/<id>', () => {
|
||||
it('removes the file and answers with the list that is left', async () => {
|
||||
const res = await call('/api/trails/how-a-request-is-served-2', { method: 'DELETE' });
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body.deleted).toBe('how-a-request-is-served-2');
|
||||
expect(res.body.trails).toHaveLength(1);
|
||||
expect(fs.existsSync(path.join(trailsDir(), 'how-a-request-is-served-2.json'))).toBe(false);
|
||||
});
|
||||
|
||||
it('is a 404 for a trail that is not there', async () => {
|
||||
const res = await call('/api/trails/never-existed', { method: 'DELETE' });
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
|
||||
it('refuses an id shaped like a path before it is joined to anything', async () => {
|
||||
const res = await call('/api/trails/..%2f..%2fetc%2fpasswd', { method: 'DELETE' });
|
||||
// The `..` segments are caught on the RAW url, before WHATWG parsing folds
|
||||
// them away — a traversal attempt is a 404, never the app shell.
|
||||
expect([400, 404]).toContain(res.status);
|
||||
expect(res.headers['content-type']).toContain('application/json');
|
||||
});
|
||||
});
|
||||
|
||||
/* ------------------------------------------------------- the write boundary */
|
||||
|
||||
describe('the write boundary', () => {
|
||||
it('refuses a POST without the marker header', async () => {
|
||||
const res = await call('/api/trails', {
|
||||
method: 'POST',
|
||||
marker: false,
|
||||
body: { name: 'forged', hops: [] },
|
||||
});
|
||||
expect(res.status).toBe(403);
|
||||
expect(res.body.code).toBe('refused');
|
||||
expect(String(res.body.error)).toContain('x-codegraph-ui');
|
||||
});
|
||||
|
||||
it('refuses a POST whose body claims to be a form', async () => {
|
||||
const res = await call('/api/trails', {
|
||||
method: 'POST',
|
||||
contentType: 'application/x-www-form-urlencoded',
|
||||
body: { name: 'forged', hops: [] },
|
||||
});
|
||||
expect(res.status).toBe(403);
|
||||
expect(String(res.body.error)).toContain('application/json');
|
||||
});
|
||||
|
||||
it('refuses a POST from a foreign origin even with the marker', async () => {
|
||||
const res = await call('/api/trails', {
|
||||
method: 'POST',
|
||||
origin: 'https://evil.example',
|
||||
body: { name: 'forged', hops: [] },
|
||||
});
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it('refuses a write anywhere but /api/, and still serves the asset on GET', async () => {
|
||||
const post = await call('/index.html', { method: 'POST', body: { a: 1 } });
|
||||
expect(post.status).toBe(405);
|
||||
expect(post.headers.allow).toBe('GET, HEAD');
|
||||
const get = await call('/index.html');
|
||||
expect(get.status).toBe(200);
|
||||
});
|
||||
|
||||
it('still refuses a method it has never answered', async () => {
|
||||
const res = await call('/api/trails', { method: 'PUT' });
|
||||
expect(res.status).toBe(405);
|
||||
});
|
||||
|
||||
it('refuses every write under --read-only, but still lists what is there', async () => {
|
||||
const list = await callOn(readOnlyServer.port, '/api/trails');
|
||||
expect(list.status).toBe(200);
|
||||
expect(list.body.readOnly).toBe(true);
|
||||
expect(list.body.readOnlyReason).toContain('--read-only');
|
||||
expect(list.body.trails.length).toBeGreaterThan(0);
|
||||
|
||||
const save = await callOn(readOnlyServer.port, '/api/trails', {
|
||||
method: 'POST',
|
||||
body: { name: 'nope', hops: [{ dir: 'start', id: 'x' }] },
|
||||
});
|
||||
expect(save.status).toBe(403);
|
||||
expect(save.body.code).toBe('refused');
|
||||
|
||||
const remove = await callOn(readOnlyServer.port, '/api/trails/how-a-request-is-served', {
|
||||
method: 'DELETE',
|
||||
});
|
||||
expect(remove.status).toBe(403);
|
||||
});
|
||||
});
|
||||
|
||||
/* ------------------------------------------------- surviving a re-index --- */
|
||||
|
||||
describe('a saved trail survives a re-index', () => {
|
||||
it('re-resolves hops by qualified name once every node id has changed', async () => {
|
||||
// Save the three-hop walk again, plus a fourth hop that is about to be
|
||||
// deleted outright, so one trail exercises every outcome at once.
|
||||
const saved = await call('/api/trails', {
|
||||
method: 'POST',
|
||||
body: {
|
||||
name: 'The whole walk',
|
||||
hops: [
|
||||
{ dir: 'start', id: await idOf('handleRequest') },
|
||||
{ dir: 'down', id: await idOf('load') },
|
||||
{ dir: 'down', id: await idOf('read') },
|
||||
{ dir: 'down', id: await idOf('retired') },
|
||||
],
|
||||
},
|
||||
});
|
||||
const before = saved.body.trails.find((t: any) => t.id === 'the-whole-walk');
|
||||
expect(before.intact).toBe(true);
|
||||
const idsBefore = before.hops.map((h: any) => h.id);
|
||||
|
||||
// Now move the world underneath it:
|
||||
// - `handleRequest` shifts down its file (a node id contains its start
|
||||
// line, so its id changes while it is the same symbol);
|
||||
// - `read` moves to a different file entirely;
|
||||
// - `retired` is deleted.
|
||||
fs.writeFileSync(
|
||||
path.join(SRC(), 'handler.ts'),
|
||||
`import { load } from './service';
|
||||
|
||||
// A comment inserted above the symbol. This alone renames it.
|
||||
// Another line.
|
||||
// And another.
|
||||
|
||||
export function handleRequest(key: string): string {
|
||||
return load(key);
|
||||
}
|
||||
`
|
||||
);
|
||||
fs.writeFileSync(
|
||||
path.join(SRC(), 'service.ts'),
|
||||
`import { read } from './store';
|
||||
|
||||
export function load(key: string): string {
|
||||
return read(key);
|
||||
}
|
||||
`
|
||||
);
|
||||
fs.writeFileSync(path.join(SRC(), 'cache.ts'), `export const unused = 1;\n`);
|
||||
fs.writeFileSync(
|
||||
path.join(SRC(), 'store.ts'),
|
||||
`export function read(key: string): string {
|
||||
return key;
|
||||
}
|
||||
`
|
||||
);
|
||||
await reindex();
|
||||
|
||||
const after = (await call('/api/trails')).body.trails.find(
|
||||
(t: any) => t.id === 'the-whole-walk'
|
||||
);
|
||||
|
||||
// Every id really did change — otherwise this test proves nothing.
|
||||
const idsAfter = after.hops.map((h: any) => h.id);
|
||||
expect(idsAfter[0]).not.toBe(idsBefore[0]);
|
||||
expect(idsAfter[0]).toBeTruthy();
|
||||
|
||||
const [handle, load, read, retired] = after.hops;
|
||||
expect(handle.status).toBe('ok');
|
||||
expect(handle.file).toBe('src/handler.ts');
|
||||
expect(handle.line).toBeGreaterThan(handle.savedLine);
|
||||
|
||||
expect(load.status).toBe('ok');
|
||||
|
||||
// Moved to another file: still resolved, and the row says where from.
|
||||
expect(read.status).toBe('moved');
|
||||
expect(read.savedFile).toBe('src/cache.ts');
|
||||
expect(read.file).toBe('src/store.ts');
|
||||
expect(read.note).toContain('src/cache.ts');
|
||||
expect(read.note).toContain('src/store.ts');
|
||||
|
||||
// Deleted: named honestly, with no invented target.
|
||||
expect(retired.status).toBe('missing');
|
||||
expect(retired.id).toBeNull();
|
||||
expect(retired.note).toContain('moved or renamed');
|
||||
|
||||
// And it still opens — the first three hops, not the fourth.
|
||||
expect(after.intact).toBe(false);
|
||||
expect(after.resolved).toBe(3);
|
||||
expect(after.openFrom).toBe(1);
|
||||
expect(after.openCount).toBe(3);
|
||||
expect(after.openId).toBe(idsAfter[2]);
|
||||
expect(after.encoded?.split(',')).toHaveLength(3);
|
||||
expect(after.encoded?.startsWith('s')).toBe(true);
|
||||
}, 120_000);
|
||||
});
|
||||
Reference in New Issue
Block a user