@stupify/cli 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,55 @@
+# @stupify/cli
+
+Local-only diagnostic CLI for checking whether AI is making you dumber.
+
+Stupify has one analysis path:
+
+```text
+sem diff -> counter scout -> Repomix context -> local search model
+```
+
+It emits search `matches`, not audit findings.
+
+```sh
+npx @stupify/cli --staged
+npx @stupify/cli --since "2 weeks ago"
+npx @stupify/cli --commit HEAD
+npx @stupify/cli --commits 20
+git diff HEAD~1..HEAD | npx @stupify/cli --stdin
+```
+
+Install the warn-only pre-commit hook:
+
+```sh
+stupify hook install
+```
+
+The hook runs `stupify --staged` and exits 0.
+
+Check local setup:
+
+```sh
+stupify doctor
+```
+
+Default search enables the checks that currently pass the local hook-safety
+bench: `duplicated_schema`, `unnecessary_complexity`, `over_commenting`,
+`lint_bypass`, and `reinvented_utils`. Other registry patterns can be opted in
+with `--checks`.
+
+```sh
+stupify --staged --checks over_commenting
+```
+
+Large search inputs are skipped rather than truncated:
+
+```sh
+stupify --staged --max-search-input-tokens 24000
+```
+
+The package is prepared for the public `@stupify` npm scope. Publishing should
+run the TypeScript build first so the executable points at `dist/stupify.js`.
+
+This iteration intentionally does not run findings audit, validators, judges,
+baselines, hosted LLM APIs, GitHub integration, dashboards, or repo-wide
+crawling.

package/dist/analysis.d.ts

@@ -0,0 +1,16 @@
+import type { LocalModel } from "./model.ts";
+import type { SearchMatch, SemChangeSet, SemContext, SemContextPack, StupifyCheck } from "./types.ts";
+export declare function runSearch(model: LocalModel, request: SearchRequest): Promise<readonly SearchMatch[]>;
+export type SearchRequest = Readonly<{
+    prompt: string;
+    schema: unknown;
+    contexts: readonly SemContext[];
+}>;
+export declare function searchRequest(input: Readonly<{
+    changeSet: SemChangeSet;
+    contexts: readonly SemContext[];
+    pack: SemContextPack;
+    patterns: readonly StupifyCheck[];
+    includeCounterReasonInPrompt?: boolean;
+}>): SearchRequest;
+export declare function countPromptTokens(model: LocalModel, prompt: string): Promise<number>;

package/dist/analysis.js

@@ -0,0 +1,133 @@
+import { cachedJson, fingerprint } from "./cache.js";
+import { searchPrompt } from "./prompts.js";
+export async function runSearch(model, request) {
+    const raw = await runJsonPrompt(model, request.prompt, request.schema, 0);
+    return uncheckedSearchMatches(raw, request.contexts);
+}
+export function searchRequest(input) {
+    return {
+        prompt: searchPrompt({
+            ...input,
+            includeCounterReason: input.includeCounterReasonInPrompt ?? false,
+        }),
+        schema: searchSchema(input.contexts),
+        contexts: input.contexts,
+    };
+}
+export async function countPromptTokens(model, prompt) {
+    const cached = await cachedJson("prompt-tokens", fingerprint({
+        version: 1,
+        modelId: model.id,
+        profile: model.profile,
+        prompt,
+    }), async () => {
+        const response = await fetch(`${model.baseUrl}/tokenize`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ content: prompt }),
+        });
+        if (!response.ok) {
+            throw new Error(`llama-server tokenize failed: HTTP ${response.status} ${await response.text()}`);
+        }
+        const body = await response.json();
+        if (!Array.isArray(body.tokens))
+            throw new Error("llama-server tokenize returned no tokens.");
+        return { count: body.tokens.length };
+    });
+    return cached.count;
+}
+function searchSchema(contexts) {
+    return {
+        type: "object",
+        properties: {
+            matches: {
+                type: "array",
+                maxItems: 5,
+                items: {
+                    type: "object",
+                    properties: {
+                        targetId: { type: "string", enum: contexts.map((context) => context.targetId) },
+                        reason: { type: "string" },
+                        proof: { type: "string" },
+                    },
+                    required: ["targetId", "reason", "proof"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ["matches"],
+        additionalProperties: false,
+    };
+}
+function uncheckedSearchMatches(value, contexts) {
+    const output = value;
+    const contextsByTargetId = new Map(contexts.map((context) => [context.targetId, context]));
+    return (output.matches ?? []).flatMap((match) => {
+        const targetId = match.targetId ?? "";
+        const context = contextsByTargetId.get(targetId);
+        if (!context)
+            return [];
+        return [{
+                targetId,
+                patternId: context.checkId,
+                reason: match.reason ?? "",
+                proof: match.proof ?? "",
+            }];
+    });
+}
+async function runJsonPrompt(model, prompt, schema, temperature) {
+    return cachedJson("model-json", fingerprint({
+        version: 1,
+        modelId: model.id,
+        profile: model.profile,
+        prompt,
+        schema,
+        temperature,
+    }), () => runJsonPromptUncached(model, prompt, schema, temperature));
+}
+async function runJsonPromptUncached(model, prompt, schema, temperature) {
+    const first = await complete(model, prompt, schema, temperature);
+    const parsed = parseJson(first);
+    if (parsed.ok)
+        return parsed.value;
+    const retry = await complete(model, `${prompt}
+
+Your previous response was not valid JSON. Return the requested JSON object only.`, schema, temperature);
+    const retryParsed = parseJson(retry);
+    if (retryParsed.ok)
+        return retryParsed.value;
+    console.error("Raw model output:");
+    console.error(retry);
+    throw new Error("Model returned invalid JSON.");
+}
+async function complete(model, prompt, schema, temperature) {
+    const response = await fetch(`${model.baseUrl}/v1/chat/completions`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            model: model.id,
+            messages: [{ role: "user", content: prompt }],
+            temperature,
+            response_format: {
+                type: "json_object",
+                schema,
+            },
+        }),
+    });
+    if (!response.ok)
+        throw new Error(`llama-server request failed: HTTP ${response.status} ${await response.text()}`);
+    const body = await response.json();
+    const content = body.choices?.[0]?.message?.content;
+    if (typeof content !== "string")
+        throw new Error("llama-server returned no message content.");
+    return content;
+}
+function parseJson(raw) {
+    try {
+        const value = JSON.parse(raw);
+        return { ok: true, value };
+    }
+    catch {
+        return { ok: false };
+    }
+}

package/dist/cache.d.ts

@@ -0,0 +1,2 @@
+export declare function fingerprint(value: unknown): string;
+export declare function cachedJson<T>(namespace: string, key: string, compute: () => Promise<T>): Promise<T>;

package/dist/cache.js

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import path from "node:path";
+export function fingerprint(value) {
+    const text = typeof value === "string" ? value : stableStringify(value);
+    return createHash("sha256").update(text).digest("hex");
+}
+export async function cachedJson(namespace, key, compute) {
+    const filePath = cachePath(namespace, key);
+    try {
+        const value = JSON.parse(await readFile(filePath, "utf8"));
+        console.error(`cache hit ${namespace} ${key.slice(0, 12)}`);
+        return value;
+    }
+    catch {
+        console.error(`cache miss ${namespace} ${key.slice(0, 12)}`);
+    }
+    const value = await compute();
+    await writeCache(filePath, value).catch(() => undefined);
+    return value;
+}
+function cachePath(namespace, key) {
+    return path.join(cacheRoot(), "intermediate-v1", safeNamespace(namespace), `${key}.json`);
+}
+async function writeCache(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    try {
+        await writeFile(tempPath, JSON.stringify(value), "utf8");
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+}
+function cacheRoot() {
+    if (process.env.STUPIFY_CACHE_DIR)
+        return process.env.STUPIFY_CACHE_DIR;
+    if (process.env.XDG_CACHE_HOME)
+        return path.join(process.env.XDG_CACHE_HOME, "stupify");
+    if (platform() === "darwin")
+        return path.join(homedir(), "Library", "Caches", "stupify");
+    if (platform() === "win32" && process.env.LOCALAPPDATA)
+        return path.join(process.env.LOCALAPPDATA, "stupify", "Cache");
+    return path.join(homedir(), ".cache", "stupify");
+}
+function safeNamespace(value) {
+    return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}

package/dist/checks.d.ts

@@ -0,0 +1,4 @@
+import { type StupifyCheck } from "./types.ts";
+export declare const defaultChecks: readonly StupifyCheck[];
+export declare function enabledChecks(checkIds: readonly string[] | null): readonly StupifyCheck[];
+export declare function searchChecks(checkIds: readonly string[] | null): readonly StupifyCheck[];

package/dist/checks.js

@@ -0,0 +1,218 @@
+import { checkId } from "./types.js";
+export const defaultChecks = [
+    {
+        id: checkId("duplicated_schema"),
+        name: "Duplicated schema",
+        question: "Did the change duplicate an existing type, schema, payload, or DTO shape?",
+        lookFor: [
+            "local shape mirrors existing fields and maps them one-for-one",
+            "new response, payload, schema, or DTO adds no filtering, renaming, validation, or versioning",
+        ],
+        ignoreWhen: [
+            "test fixture, mock, or intentional external contract",
+            "public API DTO filters, omits, protects, renames, or versions fields",
+        ],
+        hookMode: "warn",
+        searchPrompt: "Find only local/private payload or schema shapes that clearly copy another local shape one-for-one without creating a boundary. Do not match ordinary Input/Output/Request/Response types by name alone, public DTOs, external contracts, client types, or types that omit/protect private fields.",
+        searchExamples: {
+            match: [
+                "LocalUserPayload repeats User fields and maps id/email/displayName one-for-one.",
+            ],
+            nonMatch: [
+                "PublicWebhookDto omits privateNotes from InternalJob.",
+                "A client type describes an external dependency boundary.",
+            ],
+        },
+    },
+    {
+        id: checkId("unnecessary_complexity"),
+        name: "Unnecessary complexity",
+        question: "Did the change add structure without buying clarity?",
+        lookFor: [
+            "helper, wrapper, service, layer, or extra file around simple logic without reuse",
+        ],
+        ignoreWhen: [
+            "isolates dependency, removes duplication, or improves testability",
+        ],
+        hookMode: "warn",
+        searchPrompt: `Find staged changes where a locally simple decision is made harder to understand by new indirection.
+Only match when the staged diff clearly shows:
+- a new named helper, wrapper, service, adapter, boundary, or abstraction
+- and the surrounding change still appears locally simple
+- and the new structure makes the decision harder to see
+Do not match:
+- plain conditionals, guard clauses, skip paths, or error handling
+- normal feature structure
+- exported utilities that are part of a real feature
+- command plumbing
+- prompt/instruction files
+- domain configuration
+- refactors that make ownership clearer
+- changes where the payoff is unclear from the diff
+Prefer no match over a weak match.`,
+        searchExamples: {
+            match: [
+                "A small inline operation becomes a helper/service/wrapper with one obvious caller.",
+                "A straightforward flow is split across files in a way that hides the decision.",
+                "A new abstraction appears before there is evidence it buys clarity, correctness, reuse, or isolation.",
+            ],
+            nonMatch: [
+                "A real external dependency boundary is isolated.",
+                "A security/auth boundary becomes clearer.",
+                "A refactor removes larger complexity elsewhere.",
+                "Framework-required structure is added.",
+            ],
+        },
+    },
+    {
+        id: checkId("fake_precision_windowing"),
+        name: "Fake precision windowing",
+        question: "Did the change add fake precision around model context?",
+        lookFor: [
+            "precise-looking counts, budgets, ratios, reports, or batching fields without useful behavior",
+        ],
+        ignoreWhen: [
+            "simple fixed cap or chunking",
+            "external API requirement",
+        ],
+    },
+    {
+        id: checkId("coauthored_slop"),
+        name: "Coauthored slop",
+        question: "Does author metadata contain co-author text?",
+        lookFor: [
+            "author signal contains coauhtoried, coauthored, or co-authored text",
+        ],
+        ignoreWhen: [
+            "normal Co-authored-by trailer in the commit body",
+        ],
+    },
+    {
+        id: checkId("mega_file"),
+        name: "Mega file",
+        question: "Is a touched non-config file over 1000 LOC?",
+        lookFor: [
+            "touched non-config source file over 1000 LOC",
+        ],
+        ignoreWhen: [
+            "config, lock, generated, fixture, or vendored file",
+        ],
+    },
+    {
+        id: checkId("over_commenting"),
+        name: "Over commenting",
+        question: "Did the change add noisy comments?",
+        lookFor: [
+            "comments restate obvious code or narrate simple logic",
+        ],
+        ignoreWhen: [
+            "comment explains intent, constraint, workaround, or public API behavior",
+        ],
+        hookMode: "warn",
+        searchPrompt: "Find staged changes where comments appear to substitute for judgment rather than clarify it.",
+        searchExamples: {
+            match: [
+                "New comments narrate obvious code instead of explaining tradeoffs.",
+                "A simple change gains multiple generic comments that restate control flow.",
+                "Comments make the code look more deliberate without adding useful reasoning.",
+            ],
+            nonMatch: [
+                "Comments explain a real domain constraint.",
+                "Comments document an external API quirk.",
+                "Comments clarify a surprising edge case.",
+                "Comments are sparse and specific.",
+                "Comments explain provider, finance, reconciliation, timezone, or ledger behavior.",
+            ],
+        },
+    },
+    {
+        id: checkId("lint_bypass"),
+        name: "Lint bypass",
+        question: "Did the change bypass lint or type rules?",
+        lookFor: [
+            "adds suppressions, any, broad casts, or weakens lint/typecheck config",
+        ],
+        ignoreWhen: [
+            "narrow suppression with a reason",
+            "type-level test",
+            "generated file convention",
+        ],
+        hookMode: "warn",
+        searchPrompt: "Find only broad lint/type bypasses that hide useful feedback. Match bare @ts-ignore, bare @ts-expect-error, broad casts, any, or eslint/biome suppressions without a concrete inline reason. Do not match targeted suppressions that include a reason for a known framework, test, mock, or external-library limitation.",
+        searchExamples: {
+            match: [
+                "A bare // @ts-ignore hides property access on unknown input.",
+            ],
+            nonMatch: [
+                "// @ts-expect-error explains a known external library typing gap.",
+            ],
+        },
+    },
+    {
+        id: checkId("inconsistent_patterns"),
+        name: "Inconsistent patterns",
+        question: "Does the change clash with nearby patterns?",
+        lookFor: [
+            "same job uses different naming, errors, state, imports, or layout than nearby files",
+        ],
+        ignoreWhen: [
+            "external API requires it",
+            "change follows a newer local convention",
+        ],
+    },
+    {
+        id: checkId("reinvented_utils"),
+        name: "Reinvented utils",
+        question: "Did the change recreate an existing utility?",
+        lookFor: [
+            "new helper duplicates local utility or standard library behavior",
+        ],
+        ignoreWhen: [
+            "existing utility has wrong contract",
+            "new helper is clearer as a tiny private expression",
+            "helper is domain-specific or used by multiple local call sites",
+        ],
+        hookMode: "warn",
+        searchPrompt: "Find only tiny generic utility functions that recreate common helpers such as clamp, debounce, throttle, slugify, group, sort, pick, omit, uniq, or shuffle without domain-specific behavior. Do not match resolve/parse/format helpers, domain formatting, feature constants, or helpers with multiple obvious call sites.",
+        searchExamples: {
+            match: [
+                "clampValue returns min, max, or value.",
+            ],
+            nonMatch: [
+                "formatCurrencyHelper is used by invoice and refund labels.",
+                "Subscription tier constants encode domain configuration.",
+            ],
+        },
+    },
+    {
+        id: checkId("operator_style_mismatch"),
+        name: "Operator style mismatch",
+        question: "Does the change read unlike the surrounding code?",
+        lookFor: [
+            "generic or template-like names, abstractions, comments, or control flow clash with local style",
+        ],
+        ignoreWhen: [
+            "generated, vendored, framework-required, or newer established local style",
+        ],
+        enabledByDefault: false,
+    },
+];
+export function enabledChecks(checkIds) {
+    if (!checkIds)
+        return defaultChecks.filter((check) => check.enabledByDefault !== false);
+    return checksById(checkIds);
+}
+export function searchChecks(checkIds) {
+    if (!checkIds)
+        return defaultChecks.filter((check) => check.hookMode === "warn");
+    return checksById(checkIds);
+}
+function checksById(checkIds) {
+    const checksById = new Map(defaultChecks.map((check) => [check.id, check]));
+    return checkIds.map((id) => {
+        const check = checksById.get(id);
+        if (!check)
+            throw new Error(`Unknown check: ${id}`);
+        return check;
+    });
+}

package/dist/command.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "./types.ts";
+export declare function parseCommand(argv: readonly string[]): Command;

package/dist/command.js

@@ -0,0 +1,147 @@
+import { DEFAULT_MODEL_ID, MODEL_REGISTRY } from "./constants.js";
+const DEFAULT_SINCE = "2 weeks ago";
+const DEFAULT_MAX_CANDIDATES = 10;
+const DEFAULT_MAX_SEARCH_INPUT_TOKENS = 12_000;
+export function parseCommand(argv) {
+    if (argv.length === 1 && isHelp(argv[0]))
+        return { kind: "help" };
+    if (argv[0] === "bench") {
+        if (argv[1] !== "search" || !argv[2] || argv.length > 3) {
+            throw new Error("Usage: stupify bench search <config.json>");
+        }
+        return { kind: "bench-search", configPath: argv[2] };
+    }
+    if (argv[0] === "hook") {
+        const action = argv[1];
+        if (!action || !isHookAction(action) || argv.length > 2) {
+            throw new Error("Usage: stupify hook install|uninstall|status");
+        }
+        return { kind: "hook", action };
+    }
+    if (argv[0] === "doctor") {
+        if (argv.length > 1)
+            throw new Error("Usage: stupify doctor");
+        return { kind: "doctor" };
+    }
+    const initialState = {
+        inputMode: { kind: "since", since: DEFAULT_SINCE, source: "since" },
+        explicitInputMode: false,
+        checkIds: null,
+        json: false,
+        model: DEFAULT_MODEL_ID,
+        debugSem: false,
+        maxCandidates: DEFAULT_MAX_CANDIDATES,
+        maxSearchInputTokens: DEFAULT_MAX_SEARCH_INPUT_TOKENS,
+        searchProfilePath: null,
+        includeCounterReasonInPrompt: false,
+    };
+    const finalState = parseFrom(0, initialState);
+    return {
+        ...finalState.inputMode,
+        mode: "search",
+        checkIds: finalState.checkIds,
+        json: finalState.json,
+        model: finalState.model,
+        debugSem: finalState.debugSem,
+        maxCandidates: finalState.maxCandidates,
+        maxSearchInputTokens: finalState.maxSearchInputTokens,
+        searchProfilePath: finalState.searchProfilePath,
+        includeCounterReasonInPrompt: finalState.includeCounterReasonInPrompt,
+    };
+    function parseFrom(index, state) {
+        if (index >= argv.length)
+            return state;
+        const arg = argv[index];
+        if (arg === "--mode") {
+            const value = argv[index + 1];
+            if (value !== "search")
+                throw new Error("--mode only supports search.");
+            return parseFrom(index + 2, state);
+        }
+        if (arg === "--staged")
+            return parseFrom(index + 1, setInputMode(state, { kind: "staged", source: "staged" }));
+        if (arg === "--stdin")
+            return parseFrom(index + 1, setInputMode(state, { kind: "stdin", source: "stdin" }));
+        if (arg === "--json")
+            return parseFrom(index + 1, { ...state, json: true });
+        if (arg === "--debug-sem")
+            return parseFrom(index + 1, { ...state, debugSem: true });
+        if (arg === "--include-counter-reason-in-prompt") {
+            return parseFrom(index + 1, { ...state, includeCounterReasonInPrompt: true });
+        }
+        if (arg === "--search-profile") {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("-"))
+                throw new Error("--search-profile requires a JSON profile path.");
+            return parseFrom(index + 2, { ...state, searchProfilePath: value });
+        }
+        if (arg === "--since") {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("-"))
+                throw new Error("--since requires a git date, such as \"2 weeks ago\".");
+            return parseFrom(index + 2, setInputMode(state, { kind: "since", since: value, source: "since" }));
+        }
+        if (arg === "--commit") {
+            const value = argv[index + 1];
+            if (!value || !isSafeCommitArg(value))
+                throw new Error("Invalid commit.");
+            return parseFrom(index + 2, setInputMode(state, { kind: "commit", commit: value, source: "commit" }));
+        }
+        if (arg === "--commits") {
+            const value = argv[index + 1];
+            const count = Number(value);
+            if (!Number.isInteger(count) || count < 1)
+                throw new Error("--commits requires a positive integer.");
+            return parseFrom(index + 2, setInputMode(state, { kind: "commits", count, source: "commits" }));
+        }
+        if (arg === "--checks") {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("-"))
+                throw new Error("--checks requires a comma-separated list.");
+            const checkIds = value.split(",").map((id) => id.trim()).filter(Boolean);
+            if (checkIds.length === 0)
+                throw new Error("--checks requires at least one check id.");
+            return parseFrom(index + 2, { ...state, checkIds });
+        }
+        if (arg === "--model") {
+            const value = argv[index + 1];
+            if (!value || !isModelId(value))
+                throw new Error(`--model must be one of: ${Object.keys(MODEL_REGISTRY).join(", ")}`);
+            return parseFrom(index + 2, { ...state, model: value });
+        }
+        if (arg === "--max-candidates") {
+            const value = argv[index + 1];
+            const maxCandidates = Number(value);
+            if (!Number.isInteger(maxCandidates) || maxCandidates < 1) {
+                throw new Error("--max-candidates requires a positive integer.");
+            }
+            return parseFrom(index + 2, { ...state, maxCandidates });
+        }
+        if (arg === "--max-search-input-tokens") {
+            const value = argv[index + 1];
+            const maxSearchInputTokens = Number(value);
+            if (!Number.isInteger(maxSearchInputTokens) || maxSearchInputTokens < 1) {
+                throw new Error("--max-search-input-tokens requires a positive integer.");
+            }
+            return parseFrom(index + 2, { ...state, maxSearchInputTokens });
+        }
+        throw new Error(`Unknown option: ${arg}`);
+    }
+    function setInputMode(state, next) {
+        if (state.explicitInputMode)
+            throw new Error("Choose only one input mode: --since, --stdin, --commit, --commits, or --staged.");
+        return { ...state, inputMode: next, explicitInputMode: true };
+    }
+}
+function isSafeCommitArg(value) {
+    return value.length > 0 && !value.startsWith("-") && /^[A-Za-z0-9._/@~^:+-]+$/.test(value);
+}
+function isHelp(value) {
+    return value === "--help" || value === "-h";
+}
+function isModelId(value) {
+    return value in MODEL_REGISTRY;
+}
+function isHookAction(value) {
+    return value === "install" || value === "uninstall" || value === "status";
+}

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const VERSION = "0.0.4";
+import type { ModelConfig, ModelId } from "./types.ts";
+export declare const DEFAULT_MODEL_ID: ModelId;
+export declare const MODEL_REGISTRY: Record<ModelId, ModelConfig>;