mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
* feat: add content-sanity assessor + embed-skip helper + audit JSONL primitives Four new core modules (pure, no engine I/O): - src/core/content-sanity.ts — assessor with 6 hand-vetted junk patterns (Cloudflare attention-required, just-a-moment, ray-id; access-denied; captcha-required; bare error-page titles). Bytes measured against compiled_truth + timeline (parseMarkdown body split, not file bytes). ContentSanityBlockError tagged with PAGE_JUNK_PATTERN code so classifyErrorCode hits via regex without a new ImportResult field. - src/core/content-sanity-literals.ts — operator literal-substring loader for ~/.gbrain/junk-substrings.txt. Comment directives for name + applies_to. ENOENT returns empty list (fail-soft); no regex parsing so no ReDoS surface. - src/core/embed-skip.ts — single source of truth for the embed-skip predicate. JS isEmbedSkipped() + filterOutEmbedSkipped() for in-memory callers; EMBED_SKIP_FILTER_FRAGMENT raw SQL string for engine-layer filters. buildEmbedSkipMarker() emits the canonical frontmatter shape. Both Postgres and PGLite use the same JSONB '?' existence operator. - src/core/audit/content-sanity-audit.ts — ISO-week JSONL at ~/.gbrain/audit/content-sanity-YYYY-Www.jsonl. Built on v0.40.4.0 audit-writer primitive. One stream for hard-block + soft-block + warn events with event_type discriminator. summarizeContentSanityEvents rolls up by type + source + pattern hits for doctor consumption. 99 unit tests across 4 new test files (207 assertions) covering boundaries, every built-in pattern, bytes-parity assertion, operator literals (regex meta-chars stay literal), audit JSONL round-trip + reader. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(embed): apply embed-skip filter at all 5 stale-chunk sites Embed sweep must skip pages with frontmatter.embed_skip set so soft-blocked pages don't get re-embedded. Five wiring sites all use the shared helper: 1. src/commands/embed.ts — --stale CLI path (delegates to embedAllStale) 2. src/commands/embed.ts — --all CLI path (JS-side filterOutEmbedSkipped on the listPages result; Codex r2 #11 caught this previously-missed surface that re-embedded soft-blocked pages on every model swap) 3. src/core/embed-stale.ts:90 — Minion helper (inherits via engine) 4. src/core/postgres-engine.ts — listStaleChunks + countStaleChunks gain 'NOT (COALESCE(p.frontmatter, ''{}''::jsonb) ? ''embed_skip'')' filter at the SQL layer. Always JOINs pages now (pre-fix bare path skipped the JOIN; D4 + D8 require it for the filter). 5. src/core/pglite-engine.ts — mirror of postgres-engine; PGLite is Postgres 17.5 in WASM so the same JSONB '?' operator works. Cross-site invariant pinned by test/embed-skip.test.ts (20 cases on the JS predicate + SQL fragment semantics). When v0.41+ promotes embed_skip to a schema column, all 5 sites get updated in one helper file. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ingest): wire content-sanity gate into importFromContent narrow waist Hard-block via thrown ContentSanityBlockError; soft-block via frontmatter marker + chunk deletion on transition (D9 invariant). Single throw point means every wrapper site (CLI, MCP put_page, sync) inherits correct exit/error semantics through existing exception flow — no per-wrapper status-vocabulary changes (Codex r2 #2). import-file.ts: - Gate runs AFTER parseMarkdown so assessor sees compiled_truth + timeline + title + frontmatter (Codex r2 #5+#7). - Kill-switch (GBRAIN_NO_SANITY=1) checked via direct process.env AS WELL AS effective config — loadConfig() returns null on bare installs (no ~/.gbrain/config.json, no DATABASE_URL) so the config-only path missed the kill-switch. Caught by test/import-file-content-sanity.test.ts. - Hard-block: throws ContentSanityBlockError. Existing import.ts catch increments errors; sync.ts:929 catch records failure with classified code. - Soft-block: sets parsed.frontmatter.embed_skip via buildEmbedSkipMarker before hash compute (so hash differs from prior version → real write). Chunking block guards on isEmbedSkipped → chunks stays empty → existing tx.deleteChunks fires (D9 transition invariant). - Audit JSONL records every assessment (hard / soft / warn + bypass-mode). sync.ts: - classifyErrorCode gains /PAGE_JUNK_PATTERN/ → 'PAGE_JUNK_PATTERN' regex. No PAGE_OVERSIZED code because oversize is now a soft state — page lands. config.ts: - New content_sanity.* field on GBrainConfig (4 keys: bytes_warn, bytes_block, junk_patterns_enabled, disabled). - loadConfig() reads GBRAIN_PAGE_WARN_BYTES, GBRAIN_PAGE_BLOCK_BYTES, GBRAIN_NO_JUNK_PATTERNS, GBRAIN_NO_SANITY env vars sparse-merged. - loadConfigWithEngine merges DB-plane content_sanity.* keys per-key sparse-merge so 'gbrain config set content_sanity.bytes_block N' takes effect uniformly (Codex r2 #6 D1 acceptance). - KNOWN_CONFIG_KEYS + KNOWN_CONFIG_KEY_PREFIXES include the new keys. cli.ts: - runImport now honors result.errors > 0 for non-zero exit. Pre-fix the CLI awaited runImport but discarded the result, so hard-blocked imports exited 0 silently (Codex r2 #3). 9 PGLite-backed unit tests pin: hard-block throws, error message contains PAGE_JUNK_PATTERN, blocked page does NOT land in DB, soft-block writes page with embed_skip set, soft-block deletes pre-existing chunks (D9 transition), kill-switch bypass works. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat: lint rules + doctor checks + 'gbrain sources audit' CLI Three operator surfaces backed by the shared content-sanity assessor: lint.ts (2 new rules): - huge-page: bytes (compiled_truth + timeline post-parse) exceeds warn or block threshold. Message names the actual byte count. - scraper-junk: built-in junk pattern OR operator literal matched. - Lint runs parseMarkdown to extract body for bytes-parity with doctor (D2 — both surfaces measure body-only, not file-with-frontmatter). - runLintCore resolves effective config once per run: file/env (sync via loadConfig) + DB-lift when ~/.gbrain/ is reachable (D1). CI without ~/.gbrain/ falls through immediately. Engine probe wrapped in try/catch so lint never blocks on engine state. - Operator literals loaded once per lint run; passed through to every page's lintContent call. doctor.ts (3 new checks + 1 flag): - oversized_pages: indexed-free table scan via octet_length(compiled_truth) + octet_length(COALESCE(timeline, '')) (Codex r2 #13: octet_length is bytes, length is chars). Status warn on 1+ rows; oversize is now a soft state so no 'fail'. - scraper_junk_pages: capped 1000 most-recent default + --content-audit opt-in for full scan (D10 mirrors --index-audit precedent from v0.14.3). Applies assessor per-page on title + 2KB body slice + frontmatter. - content_sanity_audit_recent: reads ~/.gbrain/audit/content-sanity-*.jsonl for last 7 days, aggregates by event_type + source. Warn at 10+ events, fail at 100+. Doctor message names the multi-host limitation explicitly (Codex r1 #14): 'audit reflects events on this host only; multi-host operators should share GBRAIN_AUDIT_DIR'. sources.ts (new audit subcommand): - gbrain sources audit <id> [--json] [--include-warns] - Reads sources.local_path, walks disk (via pruneDir for node_modules / .git / dotfiles), runs assessContentSanity per .md file. - Reports size distribution (p50, p99, max) + would-hard-block count + would-soft-block count + junk-pattern hit map. - Read-only: NO DB writes, NO file mutations. Operator runs this BEFORE a sync to catch junk early, or AFTER landing v0.40.9.0 to audit historical inventory. 13 unit tests on lint rules; D1 config-lift behavior pinned by lift in runLintCore + manual override via opts.contentSanity for tests. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v0.40.9.0) v0.40.9.0 — content sanity defense: junk-pattern throw + oversize-skip-embed. Plus TODOS.md entries for the 9 deferred v0.41+ follow-ups: - chunk-level embed-quarantine (Codex r1 #3 — page-level granularity wrong) - source-repo remediation CLI (gbrain sources prune-junk) - threshold validation post-deploy on real corpora - brain-score no_junk_pages_score component - pages soft-delete --where CLI (paired with prune-junk) - post-v0.45 operator-regex extensibility (needs real ReDoS story) - post-v0.45 HTML-density rule (needs fenced-code handling) - bytes-parity E2E across lint + doctor - 5-path narrow-waist E2E pin tests + doctor integration tests Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: update CLAUDE.md for v0.40.9.0 content-sanity wave Add v0.40.9.0 Key Files entries for the content-sanity defense modules: content-sanity.ts (assessor), content-sanity-literals.ts (operator loader), embed-skip.ts (5-site shared predicate), audit/content-sanity-audit.ts (JSONL writer). Extend doctor.ts, lint.ts, embed.ts, import-file.ts, and sources.ts entries with the v0.40.9.0 surfaces (3 new doctor checks, 2 new lint rules, embed-skip filter at 5 sites, importFromContent gate, sources audit subcommand). Regenerate llms-full.txt per the CLAUDE.md edit rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: rebump v0.40.9.0 → v0.40.10.0 (queue collision with #1350) PR #1350 also claimed v0.40.9.0. Advancing this PR to v0.40.10.0 so CI's version-gate doesn't reject on overlap. No functional change — same shipped content, just a different version slot. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(brain-writer): +1ms overshoot on COUNT-race timer to defeat CI boundary flake PR #1351 ship CI hit a single test failure (one in 2552): (fail) scanBrainSources partial-scan state > hanging COUNT does not exceed deadline — Promise.race timeout fires [579.01ms] Run: https://github.com/garrytan/gbrain/actions/runs/77611667786 Cause: heavily-loaded CI runners (8 parallel shards × 4 concurrent test files = ~32 concurrent bun processes) occasionally let the setTimeout race callback resolve a microsecond BEFORE the wall-clock boundary, leaving Date.now() one tick below deadline. The post-await deadline check at brain-writer.ts:512 uses Date.now() >= deadline; on that tick the check evaluated false and scanOneSource ran src-a anyway. Test then asserted firstSource.status === 'skipped' and got 'scanned'. Fix: add 1ms overshoot to the race-timer schedule: setTimeout(..., remainingMs + 1) Guarantees the timer fires past the deadline by at least one millisecond regardless of runner timer drift. Cost: 1ms additional wall-clock latency on hung COUNT queries — operationally negligible. Verified: stress-tested 5/5 passing locally. The bug class is identical to the one the existing test comment block (lines 180-187) documents (`>=` not `>` at line 512); this +1ms is the belt to that suspenders. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
207 lines
7.5 KiB
TypeScript
207 lines
7.5 KiB
TypeScript
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
|
|
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
|
|
import { resetPgliteState } from './helpers/reset-pglite.ts';
|
|
import { withEnv } from './helpers/with-env.ts';
|
|
import { mkdtempSync, rmSync } from 'fs';
|
|
import { join } from 'path';
|
|
import { tmpdir } from 'os';
|
|
import { importFromContent } from '../src/core/import-file.ts';
|
|
import { ContentSanityBlockError } from '../src/core/content-sanity.ts';
|
|
import { isEmbedSkipped, EMBED_SKIP_KEY } from '../src/core/embed-skip.ts';
|
|
|
|
let engine: PGLiteEngine;
|
|
let auditDir: string;
|
|
let gbrainHomeDir: string;
|
|
|
|
beforeAll(async () => {
|
|
engine = new PGLiteEngine();
|
|
await engine.connect({});
|
|
await engine.initSchema();
|
|
});
|
|
|
|
afterAll(async () => {
|
|
await engine.disconnect();
|
|
});
|
|
|
|
beforeEach(async () => {
|
|
await resetPgliteState(engine);
|
|
});
|
|
|
|
/** Wrap an importFromContent call with GBRAIN_HOME + GBRAIN_AUDIT_DIR
|
|
* pointed at fresh tempdirs so config and audit writes don't leak
|
|
* between tests or pollute the developer's real ~/.gbrain. */
|
|
async function withIsolatedHome<T>(fn: () => Promise<T>): Promise<T> {
|
|
gbrainHomeDir = mkdtempSync(join(tmpdir(), 'cs-gate-home-'));
|
|
auditDir = mkdtempSync(join(tmpdir(), 'cs-gate-audit-'));
|
|
try {
|
|
return await withEnv({
|
|
GBRAIN_HOME: gbrainHomeDir,
|
|
GBRAIN_AUDIT_DIR: auditDir,
|
|
}, fn);
|
|
} finally {
|
|
rmSync(gbrainHomeDir, { recursive: true, force: true });
|
|
rmSync(auditDir, { recursive: true, force: true });
|
|
}
|
|
}
|
|
|
|
const FRONTMATTER = `---
|
|
title: 'Test Page'
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
`;
|
|
|
|
describe('importFromContent — content-sanity hard-block (D6)', () => {
|
|
test('throws ContentSanityBlockError on Cloudflare junk title', async () => {
|
|
await withIsolatedHome(async () => {
|
|
const content = `---
|
|
title: 'Attention Required! | Cloudflare'
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
Body.`;
|
|
await expect(
|
|
importFromContent(engine, 'test/junk', content, { noEmbed: true })
|
|
).rejects.toThrow(ContentSanityBlockError);
|
|
});
|
|
});
|
|
|
|
test('throws with PAGE_JUNK_PATTERN-tagged message for classifyErrorCode', async () => {
|
|
await withIsolatedHome(async () => {
|
|
const content = FRONTMATTER + 'Cloudflare Ray ID: abc123';
|
|
let caught: Error | undefined;
|
|
try {
|
|
await importFromContent(engine, 'test/ray', content, { noEmbed: true });
|
|
} catch (e) {
|
|
caught = e as Error;
|
|
}
|
|
expect(caught).toBeDefined();
|
|
expect(caught!.message).toContain('PAGE_JUNK_PATTERN');
|
|
});
|
|
});
|
|
|
|
test('thrown page is NOT written to DB', async () => {
|
|
await withIsolatedHome(async () => {
|
|
// Title matches the anchored error_page_title pattern exactly
|
|
// (`^(403|404|500|...|page not found)\s*$`). "404 Not Found"
|
|
// doesn't anchor; the test needs the bare form.
|
|
const content = `---
|
|
title: '404'
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
`;
|
|
try {
|
|
await importFromContent(engine, 'test/404', content, { noEmbed: true });
|
|
} catch { /* expected */ }
|
|
const page = await engine.getPage('test/404');
|
|
expect(page).toBeNull();
|
|
});
|
|
});
|
|
});
|
|
|
|
describe('importFromContent — soft-block (D9 transition + embed_skip)', () => {
|
|
test('soft-block writes page with embed_skip frontmatter marker', async () => {
|
|
await withIsolatedHome(async () => {
|
|
// 600K of clean text → soft-block (oversize but no junk pattern).
|
|
const content = FRONTMATTER + 'a'.repeat(600_000);
|
|
const result = await importFromContent(engine, 'test/big', content, { noEmbed: true });
|
|
expect(result.status).not.toBe('error');
|
|
const page = await engine.getPage('test/big');
|
|
expect(page).not.toBeNull();
|
|
const fm = page!.frontmatter as Record<string, unknown>;
|
|
expect(isEmbedSkipped(fm)).toBe(true);
|
|
const marker = fm[EMBED_SKIP_KEY] as Record<string, unknown>;
|
|
expect(marker.reason).toBe('oversized');
|
|
expect(marker.bytes).toBeGreaterThan(500_000);
|
|
});
|
|
});
|
|
|
|
test('soft-block deletes existing chunks (D9 transition invariant)', async () => {
|
|
await withIsolatedHome(async () => {
|
|
// First write a normal page to seed some chunks.
|
|
const small = FRONTMATTER + 'Short content with multiple sentences. Plenty of words here. Enough to chunk.';
|
|
await importFromContent(engine, 'test/grow', small, { noEmbed: true });
|
|
const beforeChunks = await engine.getChunks('test/grow');
|
|
expect(beforeChunks.length).toBeGreaterThan(0);
|
|
|
|
// Now re-import with content that grew past the block threshold.
|
|
const big = FRONTMATTER + 'a'.repeat(600_000);
|
|
await importFromContent(engine, 'test/grow', big, { noEmbed: true });
|
|
const afterChunks = await engine.getChunks('test/grow');
|
|
// D9: transition to embed_skip should delete chunks.
|
|
expect(afterChunks.length).toBe(0);
|
|
});
|
|
});
|
|
|
|
test('soft-block skips chunking entirely (no new chunks created)', async () => {
|
|
await withIsolatedHome(async () => {
|
|
const content = FRONTMATTER + 'a'.repeat(600_000);
|
|
await importFromContent(engine, 'test/big2', content, { noEmbed: true });
|
|
const chunks = await engine.getChunks('test/big2');
|
|
expect(chunks.length).toBe(0);
|
|
});
|
|
});
|
|
});
|
|
|
|
describe('importFromContent — kill-switch bypass', () => {
|
|
test('GBRAIN_NO_SANITY=1 lets junk through with bypass audit + stderr', async () => {
|
|
const gbrainHomeDirLocal = mkdtempSync(join(tmpdir(), 'cs-bypass-home-'));
|
|
const auditDirLocal = mkdtempSync(join(tmpdir(), 'cs-bypass-audit-'));
|
|
try {
|
|
await withEnv({
|
|
GBRAIN_HOME: gbrainHomeDirLocal,
|
|
GBRAIN_AUDIT_DIR: auditDirLocal,
|
|
GBRAIN_NO_SANITY: '1',
|
|
}, async () => {
|
|
const content = `---
|
|
title: 'Attention Required! | Cloudflare'
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
junk body`;
|
|
const result = await importFromContent(engine, 'test/bypass', content, { noEmbed: true });
|
|
expect(result.status).not.toBe('error');
|
|
const page = await engine.getPage('test/bypass');
|
|
expect(page).not.toBeNull();
|
|
// Page lands with frontmatter unchanged (no embed_skip set on bypass).
|
|
const fm = page!.frontmatter as Record<string, unknown>;
|
|
expect(isEmbedSkipped(fm)).toBe(false);
|
|
});
|
|
} finally {
|
|
rmSync(gbrainHomeDirLocal, { recursive: true, force: true });
|
|
rmSync(auditDirLocal, { recursive: true, force: true });
|
|
}
|
|
});
|
|
});
|
|
|
|
describe('importFromContent — normal pages unaffected', () => {
|
|
test('clean page imports successfully', async () => {
|
|
await withIsolatedHome(async () => {
|
|
const content = FRONTMATTER + 'A thoughtful essay about software design.';
|
|
const result = await importFromContent(engine, 'test/clean', content, { noEmbed: true });
|
|
expect(result.status).toBe('imported');
|
|
const page = await engine.getPage('test/clean');
|
|
expect(page).not.toBeNull();
|
|
const fm = page!.frontmatter as Record<string, unknown>;
|
|
expect(isEmbedSkipped(fm)).toBe(false);
|
|
});
|
|
});
|
|
|
|
test('warn-tier page (50K-500K body) lands normally without embed_skip', async () => {
|
|
await withIsolatedHome(async () => {
|
|
const content = FRONTMATTER + 'a'.repeat(100_000);
|
|
const result = await importFromContent(engine, 'test/warn', content, { noEmbed: true });
|
|
expect(result.status).toBe('imported');
|
|
const page = await engine.getPage('test/warn');
|
|
expect(page).not.toBeNull();
|
|
const fm = page!.frontmatter as Record<string, unknown>;
|
|
expect(isEmbedSkipped(fm)).toBe(false);
|
|
});
|
|
});
|
|
});
|