@human-synthesis/norns 0.0.8 → 0.0.10

package/bin/norns.js

@@ -11,6 +11,8 @@ import {
 	applyMigrations,
 	createMigration
 } from '../src/migrate.js';
+import { nornsLint, printFindings } from '../src/lint.js';
+import { nornsDiag } from '../src/diag.js';
 
 const FRAMEWORK_PKGS = ['@human-synthesis/norns-core', '@human-synthesis/norns'];
 
@@ -271,6 +273,29 @@ function openTargetDb(cwd) {
 	return openSqliteDb(cwd, target.path);
 }
 
+function lintCommand() {
+	const findings = nornsLint(process.cwd());
+	const { errors } = printFindings(findings);
+	process.exit(errors > 0 ? 1 : 0);
+}
+
+async function diagCommand(rest) {
+	const file = rest[0];
+	if (!file) {
+		console.error('Usage: norns diag <file.c | file.civet | file.n>');
+		process.exit(1);
+	}
+	try {
+		const js = await nornsDiag(file);
+		process.stdout.write(js);
+		if (!js.endsWith('\n')) process.stdout.write('\n');
+	} catch (err) {
+		console.error(`norns diag: ${err.message}`);
+		if (err.stack) console.error(err.stack);
+		process.exit(1);
+	}
+}
+
 const [, , cmd = 'dev', ...rest] = process.argv;
 
 switch (cmd) {
@@ -284,6 +309,12 @@ switch (cmd) {
 	case 'migrate':
 		migrateCommand(rest);
 		break;
+	case 'lint':
+		lintCommand();
+		break;
+	case 'diag':
+		diagCommand(rest);
+		break;
 	case '-h':
 	case '--help':
 		console.log(`norns <command>
@@ -295,6 +326,8 @@ Commands:
   migrate status                     list applied + pending migrations
   migrate up                         apply pending migrations
   migrate create <feature>/<name>    scaffold a new SQL migration
+  lint                               scan .c/.civet/.n + vite.config for known AI pitfalls
+  diag <file>                        print the compiled JS for a .c/.civet/.n file
 
 Migration db is read from \$DATABASE_URL (default: file:./data/app.db).
 Only file: (better-sqlite3) is supported in v1; for D1 use \`wrangler d1 migrations apply\`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@human-synthesis/norns",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Norns — SvelteKit with Civet, Pug, and the .n / .civet / .c file extensions",
   "license": "MIT",
   "author": "Daniel Teodoroiu (https://humansynthesis.ai)",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@danielx/civet": "^0.11.0",
-    "@human-synthesis/norns-core": "^0.0.7"
+    "@human-synthesis/norns-core": "^0.0.9"
   },
   "engines": {
     "node": ">=18"

package/src/auto-import.js

@@ -6,8 +6,18 @@ import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 // distinct client / server variants — most importantly `page`, which is
 // exported by both `$app/state` (client) and `@human-synthesis/norns/server`
 // (server) with completely different shapes.
-const SERVER_PATH_RE = /(\.server\.|\/server\/|\+server\.)/;
-const NON_SERVER_PATH_RE = /^(?!.*(?:\.server\.|\/server\/|\+server\.))/;
+//
+// The same predicate is reused (`isServerPath`) to classify project-utility
+// exports: an export from a server-path file is invisible to client importers.
+// That's the structural guarantee that prevents `db` / `bcrypt` / `repo.c`
+// internals from being silently auto-imported into `.n` components and
+// dragged into the client bundle.
+const SERVER_PATH_RE = /(\.server\.|\/server\/|\+server\.|hooks\.server\.)/;
+const NON_SERVER_PATH_RE = /^(?!.*(?:\.server\.|\/server\/|\+server\.|hooks\.server\.))/;
+
+function isServerPath(file) {
+	return SERVER_PATH_RE.test(file.replace(/\\/g, '/'));
+}
 
 const DEFAULT_HELPERS = [
 	{
@@ -216,39 +226,158 @@ function extractExports(source) {
 // auto-import a random route's load function. Excluded by basename.
 const ROUTE_FILE_RE = /^(\+|hooks\.)/;
 
+// Glob → regex. Supports `**`, `*`, `?`, and brace alternation `{a,b}`.
+// Patterns are matched against project-relative paths (POSIX-style separators).
+//
+//   src/lib/**/public.{c,civet}   → src/lib/(?:.*/)?public\.(?:c|civet)
+//   src/**/store.c                → src/(?:.*/)?store\.c
+//
+// Substitutions cascade: an early `**/` → `(?:.*/)?` expansion contains `*`,
+// which a later single-`*` rule would clobber. Every regex expansion is
+// stashed in a multi-char placeholder first; placeholders are swapped for
+// their final regex form once all glob meta has been consumed.
+function compileGlob(pattern) {
+	const PH_Q = '__NORNS_GLOB_Q__';
+	const PH_AS = '__NORNS_GLOB_AS__';
+	const PH_NS = '__NORNS_GLOB_NS__';
+
+	let p = pattern.replace(/[.+()^$|]/g, '\\$&');
+	p = p.replace(/\?/g, PH_Q);
+	p = p.replace(/\{([^}]+)\}/g, (_, inner) =>
+		'(?:' +
+		inner
+			.split(',')
+			.map((s) => s.trim().replace(/[.+()^$|?]/g, '\\$&'))
+			.join('|') +
+		')'
+	);
+	p = p.replace(/\*\*\//g, `(?:${PH_AS}/)?`);
+	p = p.replace(/\/\*\*/g, `(?:/${PH_AS})?`);
+	p = p.replace(/\*\*/g, PH_AS);
+	p = p.replace(/\*/g, PH_NS);
+	p = p.replace(new RegExp(PH_AS, 'g'), '.*');
+	p = p.replace(new RegExp(PH_NS, 'g'), '[^/]*');
+	p = p.replace(new RegExp(PH_Q, 'g'), '[^/]');
+	return new RegExp('^' + p + '$');
+}
+
+const EXPORT_WALK_SKIP = new Set([
+	'node_modules',
+	'.svelte-kit',
+	'.git',
+	'build',
+	'dist',
+	'.cache',
+	'.turbo'
+]);
+
+/** Walk `root` and return absolute paths of files matching any of `globs`. */
+function walkGlobs(root, globs) {
+	if (globs.length === 0) return [];
+	const regexes = globs.map(compileGlob);
+	/** @type {string[]} */
+	const out = [];
+	const stack = [root];
+	while (stack.length > 0) {
+		const cur = /** @type {string} */ (stack.pop());
+		let entries;
+		try {
+			entries = readdirSync(cur, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith('.') && entry.name !== '.') continue;
+			if (EXPORT_WALK_SKIP.has(entry.name)) continue;
+			const full = join(cur, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(full);
+			} else if (entry.isFile()) {
+				const rel = relative(root, full).replace(/\\/g, '/');
+				if (regexes.some((re) => re.test(rel))) out.push(full);
+			}
+		}
+	}
+	return out;
+}
+
 /**
- * Walk `dirs` and build a name → absolute-file-path map of every named
- * value export found. First-match-wins on collisions (same as the component
- * scanner) — silent because warnings would noise up the dev server on
- * intentional re-exports. SvelteKit route/hook files are excluded by
- * basename so framework-consumed exports don't leak into the map.
+ * Walk files matching `globs` and build a name → candidate map.
+ *
+ * Each candidate carries its `isServer` classification. Resolution at
+ * import time picks the right candidate based on the importer's scope.
+ * SvelteKit route/hook files are excluded by basename so framework-consumed
+ * exports (`load`, `actions`, `handle`) don't enter the map.
  *
  * @param {string} root
- * @param {string[]} dirs
- * @param {string[]} exts
- * @returns {Map<string, string>}
+ * @param {string[]} globs   project-relative glob patterns
+ * @param {string[]} exts    file extensions accepted (defence-in-depth)
+ * @returns {Map<string, Array<{ file: string; isServer: boolean }>>}
  */
-function buildExportMap(root, dirs, exts) {
-	/** @type {Map<string, string>} */
+function buildExportMap(root, globs, exts) {
+	/** @type {Map<string, Array<{ file: string; isServer: boolean }>>} */
 	const map = new Map();
-	for (const d of dirs) {
-		const abs = resolve(root, d);
-		for (const file of walk(abs, exts)) {
-			if (ROUTE_FILE_RE.test(basename(file))) continue;
-			let source;
-			try {
-				source = readFileSync(file, 'utf8');
-			} catch {
-				continue;
-			}
-			for (const name of extractExports(source)) {
-				if (!map.has(name)) map.set(name, file);
+	const files = walkGlobs(root, globs);
+	for (const file of files) {
+		if (ROUTE_FILE_RE.test(basename(file))) continue;
+		if (!exts.includes(extname(file))) continue;
+		let source;
+		try {
+			source = readFileSync(file, 'utf8');
+		} catch {
+			continue;
+		}
+		const rel = relative(root, file).replace(/\\/g, '/');
+		const isServer = isServerPath(rel);
+		for (const name of extractExports(source)) {
+			let list = map.get(name);
+			if (!list) {
+				list = [];
+				map.set(name, list);
 			}
+			list.push({ file, isServer });
 		}
 	}
 	return map;
 }
 
+/**
+ * Collapse a raw candidate map into one server-scope and one client-scope
+ * candidate per name. If a single scope has multiple candidates, that's a
+ * conflict — log it and exclude that scope. Mixed scopes (one server + one
+ * client) are kept and resolved dynamically by importer scope.
+ *
+ * @param {Map<string, Array<{ file: string; isServer: boolean }>>} raw
+ * @param {(msg: string) => void} [log]
+ * @returns {Map<string, { server?: string; client?: string }>}
+ */
+function resolveExportConflicts(raw, log = console.warn) {
+	/** @type {Map<string, { server?: string; client?: string }>} */
+	const out = new Map();
+	for (const [name, candidates] of raw) {
+		const servers = candidates.filter((c) => c.isServer);
+		const clients = candidates.filter((c) => !c.isServer);
+		/** @type {{ server?: string; client?: string }} */
+		const entry = {};
+		if (servers.length === 1) entry.server = servers[0].file;
+		else if (servers.length > 1) {
+			log(
+				`[norns-auto-import] conflict: \`${name}\` exported from multiple server files — not auto-imported, use explicit imports:`
+			);
+			for (const c of servers) log(`  - ${c.file}`);
+		}
+		if (clients.length === 1) entry.client = clients[0].file;
+		else if (clients.length > 1) {
+			log(
+				`[norns-auto-import] conflict: \`${name}\` exported from multiple client files — not auto-imported, use explicit imports:`
+			);
+			for (const c of clients) log(`  - ${c.file}`);
+		}
+		if (entry.server || entry.client) out.set(name, entry);
+	}
+	return out;
+}
+
 /**
  * Resolve the import specifier for a project-utility file. Same path logic
  * as `resolveComponentPath`, but strips the file extension so imports use
@@ -347,8 +476,8 @@ function collectDeclared(script) {
  * @param {string} [filename]
  * @param {{ root?: string, libRoot?: string, libAlias?: string }} [ctx]
  * @param {Record<string, string> | null} [componentSpecs]  name → bare specifier (from user `components` map). Resolved AFTER the dir-scan map so user folders override silently.
- * @param {Map<string, string> | null} [exports]      name → absolute file path (from project-utility scan). Resolved LAST.
- * @returns {Array<{ name: string, from: string, kind: 'named' | 'default' }>}
+ * @param {Map<string, { server?: string; client?: string }> | null} [exports]   name → scoped candidate map. Resolved LAST and gated by importer scope (`isServerPath`).
+ * @returns {Array<{ name: string, from: string, kind: 'named' | 'default', annotate?: boolean }>}
  */
 function computeImports(
 	referenced,
@@ -404,16 +533,24 @@ function computeImports(
 		}
 	}
 
-	// 4. Project-utility named exports — `notes` from `$lib/notes/public`,
-	// `scheduleAiMove` from sibling `./ai`, etc. Imports emit extension-less
-	// paths (`'./store'`, `'$lib/notes/public'`) to match the convention
-	// already used in user code; Vite resolves via configured `extensions`.
+	// 4. Project-utility named exports — `notes` from `$lib/notes/public`, etc.
+	// Importer scope decides which candidate is allowed:
+	//   - Server importer  → server candidate preferred, falls back to client.
+	//   - Client importer  → ONLY a client-safe candidate; server-only exports
+	//     are invisible (prevents bundling server code into the client).
+	// Auto-injected imports get an `annotate` flag so `renderImports` can mark
+	// them with a `// auto-import` comment.
 	if (exports) {
-		for (const [name, file] of exports) {
+		const importerIsServer = isServerPath(filename);
+		for (const [name, scoped] of exports) {
 			if (!wants(name)) continue;
-			const from = resolveExportPath(file, filename, root, libRoot, libAlias);
+			const chosenFile = importerIsServer
+				? (scoped.server ?? scoped.client)
+				: scoped.client;
+			if (!chosenFile) continue;
+			const from = resolveExportPath(chosenFile, filename, root, libRoot, libAlias);
 			if (from) {
-				out.push({ name, from, kind: 'named' });
+				out.push({ name, from, kind: 'named', annotate: true });
 				added.add(name);
 			}
 		}
@@ -423,27 +560,29 @@ function computeImports(
 }
 
 /**
- * @param {Array<{ name: string, from: string, kind: 'named' | 'default' }>} entries
+ * @param {Array<{ name: string, from: string, kind: 'named' | 'default', annotate?: boolean }>} entries
  * @returns {string}
  */
 function renderImports(entries) {
-	/** @type {Map<string, { default: string | null, named: string[] }>} */
+	/** @type {Map<string, { default: string | null, named: string[], annotate: boolean }>} */
 	const byFrom = new Map();
-	for (const { name, from, kind } of entries) {
+	for (const { name, from, kind, annotate } of entries) {
 		let g = byFrom.get(from);
 		if (!g) {
-			g = { default: null, named: [] };
+			g = { default: null, named: [], annotate: false };
 			byFrom.set(from, g);
 		}
 		if (kind === 'default') g.default = name;
 		else g.named.push(name);
+		if (annotate) g.annotate = true;
 	}
 	const lines = [];
-	for (const [from, { default: def, named }] of byFrom) {
+	for (const [from, { default: def, named, annotate }] of byFrom) {
 		const parts = [];
 		if (def) parts.push(def);
 		if (named.length > 0) parts.push(`{ ${named.join(', ')} }`);
-		lines.push(`import ${parts.join(', ')} from '${from}';`);
+		const stmt = `import ${parts.join(', ')} from '${from}';`;
+		lines.push(annotate ? `${stmt} // auto-import` : stmt);
 	}
 	return lines.join('\n');
 }
@@ -500,19 +639,36 @@ function renderImports(entries) {
  *   the library's `Btn` silently (first-match-wins). The string is used as
  *   the import source verbatim — no `$lib` aliasing or relative-path
  *   computation.
+ * @param {string[] | false} [options.exportGlobs]
+ *   Glob patterns (project-relative, POSIX separators) matched against files
+ *   to scan for named-value exports. The recommended convention is barrel-file
+ *   scope — `['src/lib/**\/public.c']` exposes only each feature's intentional
+ *   API surface and leaves repo/service/module internals invisible to
+ *   auto-import. Supports `**`, `*`, `?`, and `{a,b}` alternation.
+ *
+ *   Path-based safety is enforced at resolution time: a file under
+ *   `/server/` / `*.server.*` / `+server.*` / `hooks.server.*` is classified
+ *   server-only and is NEVER auto-imported into a client (non-server) file.
+ *   Name collisions inside the same scope are detected at startup, logged,
+ *   and excluded from auto-import — forcing an explicit import to disambiguate.
+ *
+ *   Default `[]` (off; explicit imports for service-layer code).
  * @param {string[] | false} [options.exportDirs]
- *   Project-relative dirs to scan for named-value exports (think `store.c`'s
- *   `export { board, play, … }` or `public.c`'s `export notes := …`).
- *   Off by default — opt in with e.g. `['src/lib', 'src/routes']`. Files
- *   inside `libRoot` import as `$lib/...`, files outside import via paths
- *   relative to the importer. Default `false`.
+ *   DEPRECATED. Equivalent to `exportGlobs: dirs.map(d => '${d}/**\/*.{c,civet,js}')`,
+ *   which scans every file under those dirs. Path-scoping is still applied,
+ *   so server exports won't leak into client files — but the broad scan
+ *   surfaces every internal export as a potential auto-import. Migrate to
+ *   `exportGlobs: ['src/lib/**\/public.c']` for an intentional API surface.
  * @param {string[]} [options.exportExtensions]
- *   File extensions scanned for exports. Default `['.c', '.civet', '.js']`
- *   — `.ts` is excluded by default because regex-scanned `.ts` can't reliably
- *   distinguish value exports from type-only exports.
+ *   File extensions accepted for exports (defence-in-depth on top of the
+ *   glob). Default `['.c', '.civet', '.js']` — `.ts` excluded because
+ *   regex-scanned `.ts` can't reliably distinguish value vs type-only exports.
  * @param {string} [options.libRoot]   Default `'src/lib'`.
  * @param {string} [options.libAlias]  Default `'$lib'`.
  * @param {string} [options.root]      Default `process.cwd()`.
+ * @param {(msg: string) => void} [options.log]
+ *   Channel for conflict / deprecation warnings. Default `console.warn`.
+ *   Tests pass a stub to assert behavior without polluting output.
  */
 export function nornsAutoImport(options = {}) {
 	const root = options.root ?? process.cwd();
@@ -520,19 +676,37 @@ export function nornsAutoImport(options = {}) {
 	const componentDirs =
 		options.componentDirs === false ? [] : (options.componentDirs ?? DEFAULT_COMPONENT_DIRS);
 	const componentExts = options.componentExtensions ?? DEFAULT_COMPONENT_EXTS;
-	const exportDirs =
-		options.exportDirs === false || options.exportDirs == null ? [] : options.exportDirs;
 	const exportExts = options.exportExtensions ?? DEFAULT_EXPORT_EXTS;
 	const libRoot = options.libRoot ?? DEFAULT_LIB_ROOT;
 	const libAlias = options.libAlias ?? DEFAULT_LIB_ALIAS;
 	const componentSpecs = options.components ?? null;
+	const log = options.log ?? console.warn;
+
+	// Build the effective glob list. `exportGlobs` is the new API;
+	// `exportDirs` is shimmed in for backward compatibility with a one-time
+	// deprecation notice per init.
+	const explicitGlobs =
+		options.exportGlobs === false || options.exportGlobs == null ? [] : options.exportGlobs;
+	const legacyDirs =
+		options.exportDirs === false || options.exportDirs == null ? [] : options.exportDirs;
+	let effectiveGlobs = [...explicitGlobs];
+	if (legacyDirs.length > 0) {
+		log(
+			'[norns-auto-import] `exportDirs` is deprecated. Migrate to `exportGlobs`, e.g. ' +
+				"`exportGlobs: ['src/lib/**/public.c']` — barrel-file scope is the safe default."
+		);
+		effectiveGlobs = effectiveGlobs.concat(
+			legacyDirs.map((d) => `${d.replace(/\\/g, '/').replace(/\/+$/, '')}/**/*.{c,civet,js}`)
+		);
+	}
 
 	const components =
 		componentDirs.length === 0
 			? new Map()
 			: buildComponentMap(root, componentDirs, componentExts);
-	const exportsMap =
-		exportDirs.length === 0 ? null : buildExportMap(root, exportDirs, exportExts);
+	const rawExports =
+		effectiveGlobs.length === 0 ? null : buildExportMap(root, effectiveGlobs, exportExts);
+	const exportsMap = rawExports ? resolveExportConflicts(rawExports, log) : null;
 	const componentCtx = { root, libRoot, libAlias };
 
 	/** @type {Map<string, string>} */
@@ -642,7 +816,10 @@ export {
 	buildExportMap as _buildExportMap,
 	collectDeclared as _collectDeclared,
 	collectIdentifiers as _collectIdentifiers,
+	compileGlob as _compileGlob,
 	computeImports as _computeImports,
 	extractExports as _extractExports,
-	renderImports as _renderImports
+	isServerPath as _isServerPath,
+	renderImports as _renderImports,
+	resolveExportConflicts as _resolveExportConflicts
 };

package/src/diag.js

@@ -0,0 +1,38 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { compile as compileCivet } from '@danielx/civet';
+
+/**
+ * Compile a `.c` / `.civet` file (or the `<script lang="civet">` block of a
+ * `.n` / `.svelte` file) to plain JS so callers can inspect what Civet
+ * actually produced. The diagnosis recipe is:
+ *
+ *   bun norns diag path/to/file.c
+ *
+ * Use it when a Civet error message is unhelpful — the compiled output
+ * proves whether the source is correct and the bug is downstream.
+ *
+ * @param {string} file path (relative or absolute)
+ * @returns {Promise<string>} compiled JS
+ */
+export async function nornsDiag(file) {
+	const abs = resolve(file);
+	if (!existsSync(abs)) throw new Error(`No such file: ${file}`);
+
+	const content = readFileSync(abs, 'utf8');
+	let source = content;
+
+	if (abs.endsWith('.n') || abs.endsWith('.svelte')) {
+		const m = content.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
+		if (!m) throw new Error(`No <script> block in ${file}`);
+		source = m[1];
+	}
+
+	const result = await compileCivet(source, {
+		js: true,
+		filename: abs
+	});
+	// Civet returns a plain string when no sourceMap option is supplied,
+	// otherwise an object with `.code`. Handle both.
+	return typeof result === 'string' ? result : result.code;
+}

package/src/lint.js

@@ -0,0 +1,294 @@
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const SKIP_DIRS = new Set([
+	'node_modules',
+	'.svelte-kit',
+	'.git',
+	'build',
+	'dist',
+	'static',
+	'.next',
+	'.cache',
+	'.turbo',
+	'data',
+	'coverage'
+]);
+
+/**
+ * @typedef {{ file: string; line: number; severity: 'error' | 'warning'; rule: string; msg: string }} Finding
+ */
+
+function walk(dir, filter, out = []) {
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		if (entry.name.startsWith('.') && entry.name !== '.') continue;
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (SKIP_DIRS.has(entry.name)) continue;
+			walk(full, filter, out);
+		} else if (entry.isFile() && filter(entry.name)) {
+			out.push(full);
+		}
+	}
+	return out;
+}
+
+/** Remove string and template literals from a line so regexes don't match inside them. */
+function stripStrings(line) {
+	let out = '';
+	let mode = 0; // 0=code, 1=', 2=", 3=`
+	for (let i = 0; i < line.length; i++) {
+		const c = line[i];
+		const prev = line[i - 1];
+		if (mode === 0) {
+			if (c === "'") mode = 1;
+			else if (c === '"') mode = 2;
+			else if (c === '`') mode = 3;
+			else out += c;
+		} else if (mode === 1 && c === "'" && prev !== '\\') mode = 0;
+		else if (mode === 2 && c === '"' && prev !== '\\') mode = 0;
+		else if (mode === 3 && c === '`' && prev !== '\\') mode = 0;
+	}
+	return out;
+}
+
+/**
+ * @param {string} file
+ * @param {string} content
+ * @returns {Finding[]}
+ */
+function lintCivetFile(file, content) {
+	/** @type {Finding[]} */
+	const out = [];
+	const lines = content.split('\n');
+
+	for (let i = 0; i < lines.length; i++) {
+		const ln = lines[i];
+		const lineNo = i + 1;
+		const trimmed = ln.trim();
+		if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('#')) continue;
+
+		const codeOnly = stripStrings(ln);
+
+		// `isnt` compiles to an undefined identifier reference at runtime.
+		if (/\bisnt\b/.test(codeOnly)) {
+			out.push({
+				file,
+				line: lineNo,
+				severity: 'error',
+				rule: 'civet/no-isnt',
+				msg: '`isnt` compiles to a bare identifier reference. Use `!==`.'
+			});
+		}
+
+		// `async *name(` as class method shorthand — Civet parser rejects it.
+		// Match indented lines (likely inside a class) where the next token after
+		// `async *` is an identifier followed by `(`.
+		if (/^\s+async\s*\*\s*\w+\s*\(/.test(ln)) {
+			out.push({
+				file,
+				line: lineNo,
+				severity: 'error',
+				rule: 'civet/no-async-generator-method',
+				msg: 'Civet rejects `async *name()` as class method shorthand. Use a callback API or top-level `async function*`.'
+			});
+		}
+
+		// `:= $state` (const) then later reassignment of the same name.
+		const stateConst = codeOnly.match(/(?:^|[\s,({[])(\w+)\s*:=\s*\$state\b/);
+		if (stateConst) {
+			const name = stateConst[1];
+			const reassignRe = new RegExp(`^\\s*${name}\\s*=(?!=|>)`);
+			for (let j = i + 1; j < lines.length; j++) {
+				if (reassignRe.test(lines[j])) {
+					out.push({
+						file,
+						line: lineNo,
+						severity: 'error',
+						rule: 'civet/state-const-reassign',
+						msg: `\`${name}\` uses \`:=\` ($state const) but is reassigned at line ${j + 1}. Use \`.=\` for $state values you reassign.`
+					});
+					break;
+				}
+			}
+		}
+
+	}
+
+	return out;
+}
+
+/**
+ * @param {string} file
+ * @param {string} content
+ * @returns {Finding[]}
+ */
+function lintNornFile(file, content) {
+	/** @type {Finding[]} */
+	const out = [];
+
+	// Identify <script> / <style> ranges so we lint only template lines.
+	const blockRanges = [];
+	const blockRe = /<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi;
+	let m;
+	while ((m = blockRe.exec(content)) !== null) {
+		blockRanges.push([m.index, m.index + m[0].length]);
+	}
+
+	// Map line index → starting offset
+	const lineStart = [0];
+	for (let i = 0; i < content.length; i++) {
+		if (content[i] === '\n') lineStart.push(i + 1);
+	}
+	const inBlock = (lineNo) => {
+		const s = lineStart[lineNo - 1];
+		return blockRanges.some(([a, b]) => s >= a && s < b);
+	};
+
+	const lines = content.split('\n');
+	for (let i = 0; i < lines.length; i++) {
+		const ln = lines[i];
+		const lineNo = i + 1;
+		if (inBlock(lineNo)) continue;
+		const trimmed = ln.trim();
+		if (!trimmed || trimmed.startsWith('//')) continue;
+
+		// `{@html ...}` / `{#each}` etc. at start of pug line without `| ` prefix.
+		if (/^\s*\{[@#:/]/.test(ln)) {
+			out.push({
+				file,
+				line: lineNo,
+				severity: 'error',
+				rule: 'pug/svelte-block-needs-pipe',
+				msg: 'Leading `{` is parsed by Pug as a tag. Prefix with `| ` to emit as text.'
+			});
+		}
+
+		// `#{expr}` Pug interpolation — evaluates at preprocess time, not runtime.
+		// Allow `\#{` escaped form.
+		if (/(^|[^\\])#\{/.test(ln)) {
+			out.push({
+				file,
+				line: lineNo,
+				severity: 'error',
+				rule: 'pug/no-pug-interpolation',
+				msg: 'Pug `#{expr}` evaluates at preprocess time. Use Svelte `{expr}` for runtime data.'
+			});
+		}
+
+	}
+
+	return out;
+}
+
+/**
+ * @param {string} file
+ * @param {string} content
+ * @returns {Finding[]}
+ */
+function lintViteConfig(file, content) {
+	/** @type {Finding[]} */
+	const out = [];
+	if (!/allowedHosts\s*:\s*(true|\[)/.test(content)) {
+		out.push({
+			file,
+			line: 1,
+			severity: 'warning',
+			rule: 'vite/allowed-hosts',
+			msg: 'Set `server.allowedHosts: true` (or an explicit list) so Vite accepts reverse-proxied Host headers in dev.'
+		});
+	}
+	return out;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Finding[]}
+ */
+export function nornsLint(cwd) {
+	/** @type {Finding[]} */
+	const findings = [];
+
+	const srcDir = existsSync(join(cwd, 'src')) ? join(cwd, 'src') : cwd;
+	const civetFiles = walk(
+		srcDir,
+		(n) => n.endsWith('.c') || n.endsWith('.civet')
+	);
+	const nornFiles = walk(srcDir, (n) => n.endsWith('.n'));
+
+	for (const f of civetFiles) {
+		try {
+			findings.push(...lintCivetFile(f, readFileSync(f, 'utf8')));
+		} catch (e) {
+			findings.push({
+				file: f,
+				line: 1,
+				severity: 'warning',
+				rule: 'lint/read-error',
+				msg: `Could not read: ${e.message}`
+			});
+		}
+	}
+	for (const f of nornFiles) {
+		try {
+			findings.push(...lintNornFile(f, readFileSync(f, 'utf8')));
+		} catch (e) {
+			findings.push({
+				file: f,
+				line: 1,
+				severity: 'warning',
+				rule: 'lint/read-error',
+				msg: `Could not read: ${e.message}`
+			});
+		}
+	}
+
+	const viteCfg = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs']
+		.map((n) => join(cwd, n))
+		.find(existsSync);
+	if (viteCfg) {
+		findings.push(...lintViteConfig(viteCfg, readFileSync(viteCfg, 'utf8')));
+	}
+
+	return findings.map((f) => ({ ...f, file: relative(cwd, f.file) }));
+}
+
+/**
+ * Pretty-print findings. Returns the number of errors.
+ * @param {Finding[]} findings
+ * @returns {{ errors: number; warnings: number }}
+ */
+export function printFindings(findings) {
+	let errors = 0;
+	let warnings = 0;
+	if (findings.length === 0) {
+		console.log('norns lint: no issues found.');
+		return { errors: 0, warnings: 0 };
+	}
+	// Group by file for readability.
+	/** @type {Map<string, Finding[]>} */
+	const byFile = new Map();
+	for (const f of findings) {
+		if (!byFile.has(f.file)) byFile.set(f.file, []);
+		byFile.get(f.file).push(f);
+	}
+	for (const [file, items] of byFile) {
+		console.log(`\n${file}`);
+		for (const it of items) {
+			const tag = it.severity === 'error' ? 'error' : 'warn ';
+			if (it.severity === 'error') errors++;
+			else warnings++;
+			console.log(`  ${it.line.toString().padStart(4)}  ${tag}  ${it.rule}  ${it.msg}`);
+		}
+	}
+	console.log(
+		`\nnorns lint: ${errors} error(s), ${warnings} warning(s) across ${byFile.size} file(s).`
+	);
+	return { errors, warnings };
+}

package/src/vite.js

@@ -1,4 +1,4 @@
-import { readFile, stat, realpath } from 'node:fs/promises';
+import { readFile, stat, realpath, readdir, mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { compile as compileCivet } from '@danielx/civet';
@@ -140,3 +140,153 @@ export function nornsCivetPlugin() {
 		}
 	};
 }
+
+/* === pugTailwindExtract ==================================================
+ *
+ * Tailwind v4's content extractor tokenizes candidates against a fixed
+ * non-class alphabet. Pug class-shorthand chains followed directly by an
+ * attribute paren — `.grid.gap-6(class="…")` — fail that tokenizer: the
+ * substring `.gap-6(` reads as one non-class token, so `gap-6` never
+ * reaches the candidate set and the CSS rule is never generated.
+ *
+ * Because the `tag.cls.cls(attrs)` form is idiomatic Pug, asking authors
+ * to either move every utility into `class="…"` or hand-maintain a
+ * safelist is a paper cut on every page they touch.
+ *
+ * This plugin walks every `.n` file under `root`, extracts each `.cls`
+ * segment via a permissive regex, and writes the deduplicated set into a
+ * single sidecar HTML file. Consumers reference the file from their CSS
+ * via `@source "./.tailwind-pug-classes.html";` so Tailwind picks it up
+ * like any other content source.
+ *
+ * The regex is permissive on purpose — it captures every `.candidate`
+ * segment in the source, including occasional false positives like
+ * `.svelte` inside template text. Those are free: Tailwind's own
+ * candidate-validation step drops anything that isn't a real utility, so
+ * the only cost is a few extra bytes in the sidecar.
+ *
+ * Runs with `enforce: 'pre'` so the scan sees the raw Pug source, not the
+ * Svelte output that the rest of the chain emits.
+ * ========================================================================
+ */
+
+/**
+ * Match every `.candidate` segment. Class names may contain Tailwind's
+ * full alphabet — letters, digits, `-`, `_`, `:`, `/`, and arbitrary-value
+ * brackets `[...]`. Pug shorthand never contains a `.` inside a class
+ * (the dot is the delimiter), so `text-[1.5rem]`-style values never appear
+ * in shorthand — those always live inside `class="…"`, which Tailwind
+ * extracts directly.
+ */
+const SEGMENT_RE = /\.([A-Za-z][\w\-:/]*(?:\[[^\]]*\])?)/g;
+
+function extractPugClasses(source) {
+	const out = new Set();
+	let m;
+	SEGMENT_RE.lastIndex = 0;
+	while ((m = SEGMENT_RE.exec(source))) {
+		if (m[1]) out.add(m[1]);
+	}
+	return out;
+}
+
+async function walkNFiles(dir, ext, out = []) {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+			await walkNFiles(full, ext, out);
+		} else if (entry.isFile() && full.endsWith(ext)) {
+			out.push(full);
+		}
+	}
+	return out;
+}
+
+/**
+ * Vite plugin that extracts Tailwind class candidates from Pug shorthand
+ * in `.n` files and writes them to a sidecar file Tailwind can scan.
+ *
+ * @param {object} [options]
+ * @param {string} [options.root]     Directory to scan (default `src`).
+ * @param {string} [options.ext]      File extension (default `.n`).
+ * @param {string} [options.outFile]  Sidecar path relative to root
+ *                                    (default `.tailwind-pug-classes.html`).
+ *                                    Reference it from your CSS with:
+ *                                      @source "./.tailwind-pug-classes.html";
+ *
+ * @returns {import('vite').Plugin}
+ */
+export function pugTailwindExtract({
+	root = 'src',
+	ext = '.n',
+	outFile = '.tailwind-pug-classes.html'
+} = {}) {
+	let projectRoot = process.cwd();
+	const fileClasses = new Map(); // absolute path -> Set<string>
+
+	async function writeSidecar() {
+		const all = new Set();
+		for (const set of fileClasses.values()) {
+			for (const c of set) all.add(c);
+		}
+		const sorted = [...all].sort();
+		const html =
+			'<!-- AUTO-GENERATED by @human-synthesis/norns/vite pugTailwindExtract. Do not edit. -->\n' +
+			`<div class="${sorted.join(' ')}"></div>\n`;
+		const out = join(projectRoot, root, outFile);
+		await mkdir(dirname(out), { recursive: true });
+		await writeFile(out, html, 'utf8');
+	}
+
+	async function scanFile(abs) {
+		try {
+			const content = await readFile(abs, 'utf8');
+			fileClasses.set(abs, extractPugClasses(content));
+		} catch {
+			fileClasses.delete(abs);
+		}
+	}
+
+	async function scanAll() {
+		const dir = join(projectRoot, root);
+		const files = await walkNFiles(dir, ext);
+		await Promise.all(files.map(scanFile));
+		await writeSidecar();
+	}
+
+	return {
+		name: 'norns:pug-tailwind-extract',
+		// Run before the Civet/Pug transform so the scan sees raw shorthand.
+		enforce: 'pre',
+		configResolved(config) {
+			projectRoot = config.root || process.cwd();
+		},
+		async buildStart() {
+			await scanAll();
+		},
+		async handleHotUpdate({ file }) {
+			if (!file.endsWith(ext)) return;
+			await scanFile(file);
+			await writeSidecar();
+		},
+		configureServer(server) {
+			server.watcher.on('add', async (file) => {
+				if (!file.endsWith(ext)) return;
+				await scanFile(file);
+				await writeSidecar();
+			});
+			server.watcher.on('unlink', async (file) => {
+				if (!file.endsWith(ext)) return;
+				fileClasses.delete(file);
+				await writeSidecar();
+			});
+		}
+	};
+}