Drift Engine

The split

Two things with a contract between them. The Engine measures; the Framework presents.

Drift started as a single script that did everything: walked the repos, measured them, wrote the manifest and understood how the site would render every figure. Measurement was tangled with presentation, so neither could move without the other.

It is now two things with a contract between them. The Drift Engine (scripts/check-drift.js) is a framework-agnostic Bun script: it fingerprints repos, owns the four data files and the overlay contract, and knows nothing about Svelte. The Drift Framework (src/lib/data/) is build-time SvelteKit code: it reads those files as static JSON imports and assembles the typed Project objects the site is built from. Copying just the Engine into another repo measures today, once its manifest is seeded by hand; making that copy stand alone is the next milestone, and a published package comes after that.

The contract

JSON Schema draft-07 with additionalProperties: false. A violation throws and writes nothing.

Between the Engine and the Framework sits sources.schema.json: a JSON Schema draft-07 definition with additionalProperties: false. The Engine validates every assembled record against it before writing anything. A violation is a programming error in the Engine, not a user-data problem, so the response is blunt: throw, write nothing. A half-correct manifest never reaches disk.

This makes adding a new metric a deliberate three-step act. Declare the property in the schema. Add it to the SyncedSource interface in types.ts. Return it from getFingerprint in the Engine. Miss one and the build tells you, either at bun run check or when the Engine throws on its next sync. The boundary is not a convention I am trusting myself to respect; it is enforced.

// Validate the fully-assembled manifest against the engine's public schema
// before the single sanctioned write. A violation is a programming error:
// throw and write nothing (fail-closed).
const violations = validateManifest(manifest);
if (violations.length > 0) {
	for (const v of violations) {
		process.stderr.write(`drift: schema violation: ${v}\n`);
	}
	throw new Error(
		`sources.json failed validation (${violations.length}); nothing written.`
	);
}

writeJson(sourcesPath, manifest); // the only write to sources.json

Measurement

Every figure is measured against the canonical commit, not the working tree, via a bounded concurrent worker pool.

For each repo, getFingerprint fans a set of independent git calls out via Promise.all against the resolved default branch, not whatever happens to be checked out locally. defaultBranch resolves origin/HEAD, then main, then master, falling back to bare HEAD only when none of those exist. The resolved ref is recorded as measuredRef in the manifest, excluded from drift comparisons via DRIFT_SKIP_FIELDS, so a branch rename never registers as drift.

Lines of code and languages are read straight from git blobs via git cat-file --batch, not the working tree, so the measurement is always against the canonical commit. Repos run concurrently across a bounded worker pool (cpus().length slots). A HEAD-plus-TTL cache, keyed on the measured commit's SHA and gitignored, means an unchanged repo is not re-scanned. drift sync and --no-cache bypass it.

Per repo, the fingerprint covers: commit counts on two axes (mine versus all authors, lifetime versus trailing four weeks); line churn on the same axes; lines of code; languages by file count; first and last commit dates; and the runtime, framework and database inferred from manifest files.

{
	"chirpdb": {
		"commitHead": "b7bf564",
		"commitsAny": 2177,
		"commitsAnyRecent": 541,
		"commitsMe": 913,
		"commitsMeRecent": 76,
		"commitAnyLast": "2026-09-18",
		"commitAnyRoot": "2026-06-08",
		"detectedLanguages": [
			"Python",
			"SQL",
			"HTML",
			"Shell",
			"JavaScript",
			"TypeScript",
			"CSS",
			"Svelte"
		],
		"linesAny": 125328,
		"linesMeAdded": 187860,
		"linesMeRemoved": 104765,
		"linesAnyAdded": 360248,
		"linesAnyRemoved": 146620,
		"linesMeAddedRecent": 16316,
		"linesMeRemovedRecent": 3634,
		"linesAnyAddedRecent": 90906,
		"linesAnyRemovedRecent": 14939,
		"urlRepo": "https://github.com/ZigZag-Technology/CHIRPdb",
		"detectedRuntime": [
			"bun",
			"python"
		],
		"detectedFramework": [
			"@sveltejs/kit",
			"svelte-5",
			"vite",
			"fastapi"
		],
		"measuredRef": "main",
		"detectedDatabase": [
			"supabase-py",
			"supabase-postgres"
		],
		"detectedTechFirstSeen": {
			"bun": "2026-09-18",
			"@sveltejs/kit": "2026-09-17",
			"svelte-5": "2026-09-17",
			"vite": "2026-09-17",
			"python": "2026-02-23",
			"fastapi": "2026-02-23"
		},
		"commitsHuman": 2177,
		"authorsDistinct": 9,
		"authorsDistinctHuman": 9,
		"commitMeRoot": false,
		"commitMeLast": "2026-09-18",
		"spanMonthsActive": 4,
		"spanMonthsAll": 4,
		"spanGapMaxDays": 16
	}
}

The staging pipeline

In-flight work surfaces on the site before it merges, via a self-healing three-tier precedence chain.

Work that is still on an unmerged branch has no entry in sources.json yet, but it can still surface on the site. A committed in-progress.json holds provisional metrics for in-flight projects: the branch name, a promotion pipeline (ordered merge targets), a visibility flag ('public' surfaces on the site; 'local' stays in the CLI), and per-field tracked values with their baseOnMain counterpart for context.

The Framework's withSyncedMetrics applies a three-tier precedence across every metric field. Manual overrides win; real synced figures come next; provisional values from in-progress.json are the floor. Once a branch lands and drift sync picks up real numbers, the synced value naturally shadows the provisional one. Promotion is self-healing: no stale figures leak through.

// Precedence: override > synced > provisional.
// prov(field) returns the in-progress tracked value, or undefined.
const prov = (field: keyof ProjectMetrics) =>
	provisional?.tracked?.[field]?.value;

commitsMe:
	ov?.commitsMe?.value ?? synced?.commitsMe ?? prov('commitsMe'),
linesAny:
	ov?.linesAny?.value ?? synced?.linesAny ?? prov('linesAny'),
// ...every metric field follows the same three-tier chain

// Scope stays honest: commitsAny is always all-authors and commitsMe is
// always Jason, whatever the project's role. The role-keyed figure the
// page actually shows is a separate field, so nothing reading a scoped
// fact silently gets the other scope's number.
commitsHeadline: isSolo ? synced?.commitsAny : synced?.commitsMe,
commitsHeadlineScope: isSolo ? 'any' : 'me',

The verbs

Each write verb touches exactly one file. Read-only verbs touch nothing at all.