feat: add architecture docs, fix code issues from review, add analyze_lint script

Architecture docs (docs/architecture/):
- overview.md: package purpose, exports, terminology, design decisions, gaps
- metagraph.md: core graph model, schema types, SchemaBuilder, validation
- sqlite-host.md: SQLite tables, common columns, relations, concurrency model
- encrypted-data.md: encrypted data as a node type, AES-256-GCM crypto utility design

Code fixes from architecture review:
- Remove ConfigSchema duplication in graphTypes.ts (import GraphConfig from types.ts)
- Add missing SelectNodeSchema/SelectNode to nodes.ts
- Fix InsertEdge.key to be Optional (match nullable DB column)
- Replace TypeScript enums with as const objects (GRAPH_STATUS, GRAPH_BASE_TYPE)
- Add verbatim-module-syntax to lint exclusions (TypeBox false positive)
- Add @std/flags and @std/path to deno.json imports

Infrastructure:
- Add scripts/analyze_lint.ts from @ade for grouped lint analysis
- Add deno task lint:analyze
- Update AGENTS.md with architecture doc references, enum convention, crypto todo
This commit is contained in:
2026-05-28 13:18:56 +00:00
parent 351fc98ec1
commit b0298663dc
13 changed files with 1311 additions and 37 deletions

View File

@@ -35,7 +35,7 @@ This design ensures consumers don't bundle database drivers they don't use.
1. **Deno-first, npm-second via JSR**: Package is published to JSR (`deno publish`). npm compatibility is automatic via JSR's npm layer (`@jsr/alkdev__storage`). No separate dnt build step.
2. **No comments in code**: Per project convention across @alkdev packages.
3. **JSR slow types excluded from lint**: Drizzle's deeply inferred generics (`sqliteTable`, `createInsertSchema`, `relations`) make explicit type annotations impractical. We use `--allow-slow-types` on publish and `"exclude": ["no-slow-types"]` in lint config. This is a known technical debt item — can be tightened iteratively.
3. **JSR slow types excluded from lint**: Drizzle's deeply inferred generics (`sqliteTable`, `createInsertSchema`, `relations`) make explicit type annotations impractical. We use `--allow-slow-types` on publish and `"exclude": ["no-slow-types"]` in lint config. Additionally, `"verbatim-module-syntax"` is excluded because TypeBox schemas are runtime values used as `typeof` type references, which the linter misidentifies as type-only imports. This is known technical debt — can be tightened iteratively.
4. **Injectable clients**: `createSqliteDatabase(client)` takes a client, not env vars. Module-level side effects are forbidden.
5. **Dependencies**: `@alkdev/typebox` and `@alkdev/drizzlebox` are npm deps (not yet on JSR). This works fine — JSR handles npm dependencies natively.
@@ -43,7 +43,8 @@ This design ensures consumers don't bundle database drivers they don't use.
```bash
deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts # Type check
deno lint # Lint (slow-types excluded)
deno lint # Lint (slow-types, verbatim-module-syntax excluded)
deno task lint:analyze # Analyze lint issues by code/file grouping
deno fmt # Format
deno test --allow-all test/ # Run tests
deno publish --allow-slow-types --dry-run # Dry-run publish
@@ -58,6 +59,7 @@ The `graphs/` and `sqlite/` modules were adapted from `@ade/ade-v0/packages/core
- `@ade/core` imports → relative imports within `src/graphs/`
- `import type { GraphConfig }``import { GraphConfig }` (TypeBox schemas are both values and types)
- `Relation` type alias removed (JSR slow type)
- TypeScript enums replaced with `as const` objects (`EnumGraphStatus``GRAPH_STATUS`)
- `client.ts` refactored to be injectable
- Module-level `db` and `client` exports removed
@@ -68,10 +70,23 @@ The `graphs/` and `sqlite/` modules were adapted from `@ade/ade-v0/packages/core
- TypeBox schemas are named with PascalCase (`NodeType`, `GraphConfig`)
- Drizzle table objects are named with camelCase (`graphTypes`, `nodeTypes`)
- Schema objects from drizzlebox are named with PascalCase (`InsertGraph`, `SelectGraph`)
- Enum constants use `SCREAMING_SNAKE_CASE` objects (`GRAPH_STATUS`, `ACTOR_TYPE`)
## Architecture Docs
See `docs/architecture/` for detailed specifications:
- `overview.md` — Package purpose, exports, design decisions, open questions
- `metagraph.md` — Core graph model, schema types, SchemaBuilder, attribute storage
- `sqlite-host.md` — SQLite tables, relations, client factory, porting notes
- `encrypted-data.md` — Encrypted data design (planned), crypto utility, node type modeling
These docs describe what the package is AND what it's becoming. Items marked ⚠️ are not yet implemented.
## What's Not Done Yet
- `src/pg/` — PostgreSQL host (same table shapes, `pgTable` + `jsonb` + `timestamp` + `pgEnum`)
- `src/graphs/crypto.ts` — Crypto utility (`encrypt`, `decrypt`, `generateEncryptionKey`, `EncryptedDataSchema`)
- Tests
- Repository/CRUD layer (currently only table definitions, no typed query functions)
- Hub-specific tables (sessions, messages, parts, call graphs, tasks, etc.)