Files
gbrain/test/import-file-content-sanity.test.ts
T
fa2c7a6990 v0.40.10.0 feat: content sanity defense — junk-pattern throw + oversize-skip-embed (#1351)
* 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>
2026-05-24 10:49:56 -07:00

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);
});
});
});