@dowel/dowel 0.3.0 → 0.3.1

package/README.md

@@ -1,12 +1,72 @@
 # dowel
 
-A compiled, opinionated **architecture linter**. Rules surface diagnostics +
-intent; the agent reading them applies the fix. Unlike a type-checker it also
-validates raw SQL against a real schema — it builds a shadow Postgres from your
-migrations and `PREPARE`s every query against it.
+**A deterministic harness for coding agents.** dowel compiles your
+architecture into rules and checks the *whole codebase* on every run, so an AI
+agent — or a human — gets the same non-negotiable feedback every time: what's
+allowed, what isn't, and *why*.
 
-This package ships the Rust engine as a native Node addon plus a TypeScript
-authoring API, so you write your codebase's architecture rules in TypeScript:
+```bash
+npm i -D @dowel/dowel && npx dowel setup
+```
+
+---
+
+## Why
+
+Coding agents amplify whatever patterns already exist in a repo — including the
+uneven ones. Boundaries with exceptions get copied as exceptions; the codebase
+drifts. The usual answer is more prose — `CLAUDE.md`, `AGENTS.md`, `.cursorrules`
+— but prose is **non-deterministic**: the model may read it, may not, and it
+rots as the codebase grows.
+
+> *"Agents write the code; linters write the law. Agents iterate against
+> deterministic feedback far better than they iterate against vibes."*
+
+dowel moves the gate **into the structure of the codebase**. Architecture
+becomes compiled, checkable law:
+
+- **Deterministic** — the same diagnostics every run, not a suggestion the model
+  weighs. Exit code is non-zero on any `error`, so it gates CI and agent loops.
+- **Whole-codebase, every time** — no context window to overflow, no
+  `AGENTS.md` to keep in sync. The rules *are* the spec.
+- **Diagnostics + intent** — every finding states the rule's intent, so the
+  agent reading it learns the pattern and fixes it, then carries the pattern
+  forward. The codebase teaches the next agent.
+
+## What it checks that a type-checker can't
+
+- **Architecture boundaries** — vertical-slice structure, cross-slice imports,
+  layer purity (no SQL in services, no `Response` in repos, Result at write
+  boundaries), folder vocabulary, ownership.
+- **Raw SQL against a real schema** — dowel builds a **shadow database** from
+  your migrations (Postgres *or* SQLite/D1) and `PREPARE`s every query against
+  it, catching drift, missing indexes, and N+1s a type-checker never sees. If
+  the shadow is unreachable it says so, loudly — never a silent pass.
+
+## Quickstart
+
+```bash
+npm i -D @dowel/dowel
+npx dowel setup          # detects stack/DB/structure, picks a profile,
+                         # writes arch-lint.toml, scaffolds rules/
+npm run lint:arch        # or: npx dowel
+```
+
+`dowel setup` reads your repo and recommends a **profile** — a curated rule set
+for your stack:
+
+| Profile | For |
+|---------|-----|
+| `node-postgres` | Node/Hono + Postgres |
+| `cloudflare-d1` | Cloudflare Workers + D1 (SQLite) |
+| `sanity-nextjs` | Next.js + Sanity (no SQL) |
+| `generic` / `portable` | any TypeScript / any language baseline |
+
+## Authoring rules
+
+Portable rules ship in the packs. Codebase-specific rules live *with your
+codebase* as TypeScript — type-checked by your own `tsc`, scaffolded by
+`dowel new-rule`:
 
 ```ts
 // rules/no-sql-outside-repos.ts
@@ -15,41 +75,34 @@ import { defineRule } from "@dowel/dowel";
 export default defineRule({
   id: "NO_SQL_OUTSIDE_REPOS",
   intent: "raw SQL lives only in repos/ — services compose, repos query",
-  check(project) {
-    return project
-      .files()
+  check(project, ctx) {
+    return project.files()
       .filter((f) => /\bselect\b/i.test(f.text) && !f.relPath.includes("/repos/"))
-      .map((f) => ({ severity: "error", file: f.path, line: 1, message: "move SQL into a repo" }));
+      .map((f) => ({ severity: "error", file: f.path, line: 1,
+                     message: "move SQL into a repo" }));
   },
 });
 ```
 
-## Install
-
 ```bash
-npm i -D @dowel/dowel
+dowel new-rule NO_SQL_OUTSIDE_REPOS   # scaffolds the rule + passing/violation fixtures
 ```
 
-npm pulls exactly one prebuilt native package for your platform
-(`@dowel/dowel-<triple>`) via `optionalDependencies` — no Rust toolchain, no
-post-install compile, no committed binary.
-
-## Use
-
-Add an `arch-lint.toml` and a `rules/` dir, then:
+Every rule declares **when it fires** (scope — e.g. exempt tests), **which
+variant** (typed options), and is toggled per-repo in `arch-lint.toml` — so
+calibration is data, not a fork of the rule.
 
-```jsonc
-// package.json
-"scripts": { "lint:arch": "dowel" }
-```
+## How it's built
 
-```bash
-npx dowel                 # lint cwd against ./arch-lint.toml + ./rules
-dowel --root ../ --config arch-lint.toml --rules rules
-```
+The Rust engine ships as a prebuilt native Node addon: `npm i` pulls exactly one
+`@dowel/dowel-<platform>` package via `optionalDependencies` — no Rust
+toolchain, no post-install compile, no committed binary. Borrows hard-won
+patterns from `ruff`/`oxc` (speed), `sqlc` (DB-checked SQL), and `Squawk`
+(migration safety).
 
-Exit code is non-zero on any `error`-severity diagnostic, so it gates CI.
+> **Platform support:** `darwin-arm64` ships today; the Linux/Windows binaries
+> land via the CI build matrix. On an unsupported platform the loader tells you.
 
 ## License
 
-MIT
+MIT OR Apache-2.0

package/bin/commands/setup.mjs

@@ -114,12 +114,16 @@ function detectArchitecture(root, featuresRoot) {
       }
     }
   }
-  const vocab = new Set();
-  for (const slice of sliceDirs) for (const b of subdirs(slice)) vocab.add(baseName(b));
+  // NOTE: we deliberately DO NOT derive slice_vocab from the folder names found
+  // inside slices — on a real repo that yields garbage (component/util names
+  // like ConditionEditor, calculate-score, …) rather than the canonical VSA
+  // buckets. The generated config omits slice_vocab so the vsa pack's default
+  // bucket vocabulary applies (contracts/public/api/services/repos/types/
+  // components/routes/hooks/workflow/client.ts). A consumer adds a genuine
+  // recurring bucket by hand if needed.
   return {
     featuresRoot,
     groups: [...groups].sort(),
-    sliceVocab: [...vocab].sort(),
     sliceCount: sliceDirs.length,
   };
 }
@@ -231,7 +235,10 @@ function renderConfig({ profile, dialect, arch, prefixes, migrationsDir }) {
   L.push("[architecture]");
   L.push(`features_root = "${arch.featuresRoot}"`);
   if (arch.groups.length) L.push(`groups = ${tomlArray(arch.groups)}`);
-  if (arch.sliceVocab.length) L.push(`slice_vocab = ${tomlArray(arch.sliceVocab)}`);
+  // slice_vocab intentionally omitted — the vsa pack default applies. Setting it
+  // from detected folder names produced garbage; declare it by hand only if your
+  // slices genuinely use a different bucket vocabulary.
+  L.push("# slice_vocab = [...]   # omitted: uses the vsa pack default bucket vocab");
   if (prefixes.length) L.push(`table_prefixes = ${tomlArray(prefixes)}`);
   L.push("");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dowel/dowel",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "dowel — a compiled, opinionated architecture linter. TS-native rule authoring over a Rust engine (Project, AST, shadow-DB SQL oracle).",
   "license": "MIT",
   "repository": {
@@ -59,12 +59,12 @@
     "@types/node": "^22.0.0"
   },
   "optionalDependencies": {
-    "@dowel/dowel-darwin-arm64": "0.3.0",
-    "@dowel/dowel-darwin-x64": "0.3.0",
-    "@dowel/dowel-linux-x64-gnu": "0.3.0",
-    "@dowel/dowel-linux-arm64-gnu": "0.3.0",
-    "@dowel/dowel-linux-x64-musl": "0.3.0",
-    "@dowel/dowel-win32-x64-msvc": "0.3.0"
+    "@dowel/dowel-darwin-arm64": "0.3.1",
+    "@dowel/dowel-darwin-x64": "0.3.1",
+    "@dowel/dowel-linux-x64-gnu": "0.3.1",
+    "@dowel/dowel-linux-arm64-gnu": "0.3.1",
+    "@dowel/dowel-linux-x64-musl": "0.3.1",
+    "@dowel/dowel-win32-x64-msvc": "0.3.1"
   },
   "publishConfig": {
     "access": "public"