@curiousnerd/keel 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Core data shapes for keel.
+ *
+ * `Facts` is the deterministic ground truth extracted from the codebase.
+ * `Claims` is what the context file (CLAUDE.md / AGENTS.md) says is true.
+ * The analyze engines compare the two and emit `Finding`s.
+ */
+/** A single `import`/`require` occurrence in a file. */
+export interface ImportFact {
+    /** The raw module specifier, e.g. "zod", "./utils", "@scope/pkg/sub". */
+    specifier: string;
+    /** True when the specifier resolves to an external package (not relative/absolute local). */
+    external: boolean;
+    /**
+     * The npm package name for external specifiers, with subpaths stripped:
+     * "axios/lib/foo" -> "axios", "@scope/pkg/sub" -> "@scope/pkg".
+     * Null for local imports.
+     */
+    packageName: string | null;
+    /** Named bindings imported, e.g. ["z"] for `import { z } from "zod"`. */
+    named: string[];
+    /** 1-based line of the import statement. */
+    line: number;
+}
+/** A function/method declaration with the data needed for duplication detection. */
+export interface FunctionFact {
+    /** Declared name, or null for anonymous functions. */
+    name: string | null;
+    /** Owning file, relative to the scan root. */
+    filePath: string;
+    /** 1-based start line. */
+    startLine: number;
+    /** 1-based end line. */
+    endLine: number;
+    /**
+     * Hash of the normalized function body (comments/whitespace stripped,
+     * locals renamed to placeholders). Equal hashes => exact duplicates.
+     * Null when the body is too trivial to consider (below the token gate).
+     */
+    bodyHash: string | null;
+    /** Count of significant tokens in the normalized body (the complexity gate). */
+    tokenCount: number;
+    /**
+     * Winnowing fingerprints of the normalized body, for near-duplicate
+     * similarity. Empty when the body is below the complexity gate.
+     */
+    fingerprints: number[];
+    /** Normalized signature string, used later for semantic-dup shortlisting. */
+    signature: string;
+}
+/** Identifier casing tally for a file, used for naming-convention drift. */
+export interface NamingStats {
+    /** Single all-lowercase word (e.g. `count`) — valid camelCase *and* snake_case. */
+    lower: number;
+    /** Multi-word camelCase with an internal capital (e.g. `formatDate`). */
+    camelCase: number;
+    PascalCase: number;
+    snake_case: number;
+    CONSTANT_CASE: number;
+    other: number;
+}
+/** Source language of a file. */
+export type Language = "javascript" | "python";
+/** Everything extracted from one source file. */
+export interface FileFacts {
+    /** Path relative to the scan root. */
+    path: string;
+    /** Content hash, used as the cache key. */
+    hash: string;
+    /** Source language this file was parsed as. */
+    language: Language;
+    imports: ImportFact[];
+    functions: FunctionFact[];
+    naming: NamingStats;
+    /** 1-based lines carrying an inline `keel-ignore` marker. */
+    ignoreLines: number[];
+}
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun" | "unknown";
+/** Facts derived from package.json + lockfiles. */
+export interface PackageFacts {
+    name: string | null;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    /** Union of dependency + devDependency names. */
+    allDeps: string[];
+    /** Inferred from the lockfile present in the repo root. */
+    packageManager: PackageManager;
+}
+/** The complete deterministic picture of a repository. */
+export interface Facts {
+    /** Absolute scan root. */
+    root: string;
+    files: FileFacts[];
+    /** Null when no package.json was found. */
+    pkg: PackageFacts | null;
+}
+/** A single machine-checkable assertion from CLAUDE.md / AGENTS.md. */
+export interface Claim {
+    /** Normalized key, e.g. "validation", "database", "packageManager", "naming". */
+    key: string;
+    /** Raw value as written, e.g. "Zod", "PostgreSQL", "camelCase". */
+    value: string;
+    /** Which file the claim came from. */
+    source: string;
+    /** 1-based line in the source file. */
+    line: number;
+}
+export interface Claims {
+    stack: Claim[];
+    constraints: Claim[];
+}
+export type FindingKind = "drift" | "conflict" | "dup" | "dup-near";
+/** Confidence tier — drives severity styling and whether it can fail CI. */
+export type Confidence = "high" | "medium" | "low";
+export interface Finding {
+    kind: FindingKind;
+    confidence: Confidence;
+    /** Short headline, e.g. `HTTP: axios (4 files), ky (1 file)`. */
+    title: string;
+    /** Optional longer explanation (templated; LLM-enriched later). */
+    detail?: string;
+    /** Optional plain-language explanation from the LLM (advisory; never affects the score). */
+    explanation?: string;
+    /** Primary file/location this finding points at, when applicable. */
+    location?: string;
+    /** Point penalty applied to the Coherence Score. */
+    penalty: number;
+}
+export interface ScoreBreakdown {
+    drift: number;
+    conflict: number;
+    duplication: number;
+}
+export interface Report {
+    score: number;
+    breakdown: ScoreBreakdown;
+    findings: Finding[];
+    stats: {
+        filesScanned: number;
+        durationMs: number;
+        /** Always 0 in v0 (no LLM). */
+        costUsd: number;
+    };
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Core data shapes for keel.
+ *
+ * `Facts` is the deterministic ground truth extracted from the codebase.
+ * `Claims` is what the context file (CLAUDE.md / AGENTS.md) says is true.
+ * The analyze engines compare the two and emit `Finding`s.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/util/fingerprint.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compute a document fingerprint for a normalized token stream using winnowing
+ * (the MOSS algorithm). Returns a sorted, de-duplicated set of k-gram hashes —
+ * a compact signature that survives small edits, so two near-identical bodies
+ * share most of their fingerprints.
+ */
+export declare function computeFingerprints(tokens: string[], k?: number, w?: number): number[];
+/**
+ * Jaccard similarity of two fingerprint sets (each already unique): the share
+ * of fingerprints they have in common. 1 = identical, 0 = nothing in common.
+ */
+export declare function jaccard(a: number[], b: number[]): number;

package/dist/util/fingerprint.js

@@ -0,0 +1,60 @@
+import { fnv1a } from "./hash.js";
+/** k-gram size: how many consecutive tokens form one fingerprint unit. */
+const K = 5;
+/** Winnowing window: guarantees any shared run of >= K + W - 1 tokens is caught. */
+const W = 4;
+/**
+ * Compute a document fingerprint for a normalized token stream using winnowing
+ * (the MOSS algorithm). Returns a sorted, de-duplicated set of k-gram hashes —
+ * a compact signature that survives small edits, so two near-identical bodies
+ * share most of their fingerprints.
+ */
+export function computeFingerprints(tokens, k = K, w = W) {
+    if (tokens.length === 0)
+        return [];
+    if (tokens.length < k)
+        return [fnv1a(tokens.join("
"))];
+    const grams = [];
+    for (let i = 0; i + k <= tokens.length; i++) {
+        grams.push(fnv1a(tokens.slice(i, i + k).join("
")));
+    }
+    return winnow(grams, w);
+}
+/** Select fingerprints: in each window of `w` k-grams, keep the minimum hash. */
+function winnow(hashes, w) {
+    const fps = new Set();
+    if (hashes.length <= w) {
+        fps.add(Math.min(...hashes));
+        return [...fps].sort((a, b) => a - b);
+    }
+    let lastIdx = -1;
+    for (let i = 0; i + w <= hashes.length; i++) {
+        let minIdx = i;
+        for (let j = i + 1; j < i + w; j++) {
+            if (hashes[j] <= hashes[minIdx])
+                minIdx = j; // rightmost-min on ties
+        }
+        if (minIdx !== lastIdx) {
+            fps.add(hashes[minIdx]);
+            lastIdx = minIdx;
+        }
+    }
+    return [...fps].sort((a, b) => a - b);
+}
+/**
+ * Jaccard similarity of two fingerprint sets (each already unique): the share
+ * of fingerprints they have in common. 1 = identical, 0 = nothing in common.
+ */
+export function jaccard(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 1;
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const setA = new Set(a);
+    let intersection = 0;
+    for (const x of b)
+        if (setA.has(x))
+            intersection += 1;
+    return intersection / (a.length + b.length - intersection);
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/util/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/util/fingerprint.ts"],"names":[],"mappings":"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"}

package/dist/util/hash.d.ts

@@ -0,0 +1,4 @@
+/** Stable short hash of a string, used for file-content and body-normalization keys. */
+export declare function sha1(text: string): string;
+/** Fast 32-bit FNV-1a hash, used for k-gram fingerprints (non-cryptographic). */
+export declare function fnv1a(text: string): number;

package/dist/util/hash.js

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+/** Stable short hash of a string, used for file-content and body-normalization keys. */
+export function sha1(text) {
+    return createHash("sha1").update(text).digest("hex");
+}
+/** Fast 32-bit FNV-1a hash, used for k-gram fingerprints (non-cryptographic). */
+export function fnv1a(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+//# sourceMappingURL=hash.js.map

package/dist/util/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/util/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,wFAAwF;AACxF,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,KAAK,CAAC,IAAY;IAChC,IAAI,CAAC,GAAG,UAAU,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@curiousnerd/keel",
+  "version": "0.1.0",
+  "description": "A local-first verifier that keeps an AI coding agent honest: catches drift, library conflicts, and duplication across JS/TS and Python.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aditya",
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "static-analysis",
+    "drift",
+    "duplication",
+    "code-quality",
+    "mcp",
+    "claude",
+    "linter",
+    "typescript",
+    "python"
+  ],
+  "bin": {
+    "keel": "dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "data"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^12.1.0",
+    "ignore": "^5.3.2",
+    "picocolors": "^1.1.1",
+    "tree-sitter-wasms": "^0.1.13",
+    "ts-morph": "^23.0.0",
+    "web-tree-sitter": "^0.20.8",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}