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>
162 lines
5.9 KiB
TypeScript
162 lines
5.9 KiB
TypeScript
import { describe, test, expect } from 'bun:test';
|
|
import { lintContent } from '../src/commands/lint.ts';
|
|
|
|
const MINIMAL_FRONTMATTER = `---
|
|
title: Test Page
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
`;
|
|
|
|
describe('lint — huge-page rule', () => {
|
|
test('does not fire below warn threshold', () => {
|
|
const content = MINIMAL_FRONTMATTER + 'a'.repeat(40_000);
|
|
const issues = lintContent(content, 'test.md');
|
|
expect(issues.find((i) => i.rule === 'huge-page')).toBeUndefined();
|
|
});
|
|
|
|
test('fires when body exceeds warn threshold (default 50K)', () => {
|
|
const content = MINIMAL_FRONTMATTER + 'a'.repeat(60_000);
|
|
const issues = lintContent(content, 'test.md');
|
|
const huge = issues.find((i) => i.rule === 'huge-page');
|
|
expect(huge).toBeDefined();
|
|
expect(huge!.message).toContain('60');
|
|
expect(huge!.fixable).toBe(false);
|
|
expect(huge!.line).toBe(1);
|
|
});
|
|
|
|
test('fires with block-threshold language when body exceeds block', () => {
|
|
const content = MINIMAL_FRONTMATTER + 'a'.repeat(600_000);
|
|
const issues = lintContent(content, 'test.md');
|
|
const huge = issues.find((i) => i.rule === 'huge-page');
|
|
expect(huge).toBeDefined();
|
|
expect(huge!.message).toContain('block');
|
|
});
|
|
|
|
test('respects custom bytes_warn override', () => {
|
|
const content = MINIMAL_FRONTMATTER + 'a'.repeat(1000);
|
|
const issues = lintContent(content, 'test.md', {
|
|
contentSanity: { bytes_warn: 500, bytes_block: 50_000 },
|
|
});
|
|
expect(issues.find((i) => i.rule === 'huge-page')).toBeDefined();
|
|
});
|
|
|
|
test('disabled kill-switch suppresses huge-page rule', () => {
|
|
const content = MINIMAL_FRONTMATTER + 'a'.repeat(600_000);
|
|
const issues = lintContent(content, 'test.md', {
|
|
contentSanity: { disabled: true },
|
|
});
|
|
expect(issues.find((i) => i.rule === 'huge-page')).toBeUndefined();
|
|
});
|
|
});
|
|
|
|
describe('lint — scraper-junk rule', () => {
|
|
test('does not fire on clean content', () => {
|
|
const content = MINIMAL_FRONTMATTER + 'This is a thoughtful essay about software design.';
|
|
const issues = lintContent(content, 'test.md');
|
|
expect(issues.find((i) => i.rule === 'scraper-junk')).toBeUndefined();
|
|
});
|
|
|
|
test('fires when title matches cloudflare_attention_required pattern', () => {
|
|
const content = `---
|
|
title: 'Attention Required! | Cloudflare'
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
Body content.`;
|
|
const issues = lintContent(content, 'test.md');
|
|
const junk = issues.find((i) => i.rule === 'scraper-junk');
|
|
expect(junk).toBeDefined();
|
|
expect(junk!.message).toContain('cloudflare_attention_required');
|
|
});
|
|
|
|
test('fires on access_denied body pattern', () => {
|
|
const content = MINIMAL_FRONTMATTER + 'Access denied\n\nYou do not have permission.';
|
|
const issues = lintContent(content, 'test.md');
|
|
expect(issues.find((i) => i.rule === 'scraper-junk')).toBeDefined();
|
|
});
|
|
|
|
test('operator literal hits also surface', () => {
|
|
const content = MINIMAL_FRONTMATTER + "You're being blocked from accessing this site.";
|
|
const issues = lintContent(content, 'test.md', {
|
|
contentSanity: {
|
|
operator_literals: [{ name: 'reddit_blocked', substring: "you're being blocked from accessing" }],
|
|
},
|
|
});
|
|
const junk = issues.find((i) => i.rule === 'scraper-junk');
|
|
expect(junk).toBeDefined();
|
|
expect(junk!.message).toContain('reddit_blocked');
|
|
});
|
|
|
|
test('junk_patterns_enabled=false suppresses operator literals AND built-ins via consumer wiring', () => {
|
|
// The assessor honors junk_patterns_enabled implicitly via the
|
|
// operator_literals=[] passed by runLintCore. Lint here tests the
|
|
// direct call path: when caller passes junk_patterns_enabled=false,
|
|
// operator_literals should already be empty (production resolver
|
|
// handles that gate). This test pins built-in patterns still fire
|
|
// even when junk_patterns_enabled flag is on the opts but no
|
|
// literals are passed — i.e., the flag is informational at this
|
|
// layer; the resolver consults it before constructing opts.
|
|
const content = `---
|
|
title: 'Attention Required! | Cloudflare'
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
body`;
|
|
const issues = lintContent(content, 'test.md', {
|
|
contentSanity: { junk_patterns_enabled: false, operator_literals: [] },
|
|
});
|
|
// Built-in pattern still fires here (resolver doesn't strip
|
|
// built-ins; only operator literals are gated by the flag).
|
|
expect(issues.find((i) => i.rule === 'scraper-junk')).toBeDefined();
|
|
});
|
|
|
|
test('disabled kill-switch suppresses scraper-junk rule', () => {
|
|
const content = `---
|
|
title: 'Access Denied'
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
body`;
|
|
const issues = lintContent(content, 'test.md', {
|
|
contentSanity: { disabled: true },
|
|
});
|
|
expect(issues.find((i) => i.rule === 'scraper-junk')).toBeUndefined();
|
|
});
|
|
});
|
|
|
|
describe('lint — bytes parity with doctor (D2)', () => {
|
|
test('lint measures body-only bytes (not file bytes)', () => {
|
|
// A page with large frontmatter but small body should NOT trip
|
|
// huge-page — the rule keys on body bytes only, matching what the
|
|
// doctor `oversized_pages` check sees via octet_length(compiled_truth + timeline).
|
|
const fm = '---\ntitle: Test\ntype: note\ncreated: 2026-05-24\nbig_meta: ' + 'x'.repeat(60_000) + '\n---\n\n';
|
|
const content = fm + 'small body';
|
|
const issues = lintContent(content, 'test.md');
|
|
// The body is "small body" → ~10 bytes. Should NOT trip warn.
|
|
expect(issues.find((i) => i.rule === 'huge-page')).toBeUndefined();
|
|
});
|
|
});
|
|
|
|
describe('lint — existing rules unaffected by content-sanity extension', () => {
|
|
test('LLM preamble rule still fires', () => {
|
|
// The LLM_PREAMBLES regex anchors on `^Of course\.?\s*Here is` so
|
|
// we use the period form (not exclamation) for an exact match.
|
|
const content = `---
|
|
title: T
|
|
type: note
|
|
created: 2026-05-24
|
|
---
|
|
|
|
Of course. Here is the brain page.
|
|
|
|
Real content.`;
|
|
const issues = lintContent(content, 'test.md');
|
|
expect(issues.find((i) => i.rule === 'llm-preamble')).toBeDefined();
|
|
});
|
|
});
|