@codesema/speccov 0.0.0-stage → 0.2.1

package/bin/speccov.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Runs speccov on the runtime the project already has.
+//
+// The rules pass imports the user's TypeScript, and this package ships its own sources as
+// they are. Bun runs TypeScript by itself. Node only strips the types, and stops at the
+// first import without an extension, the first path alias, the first enum or decorator.
+// So under Node the TypeScript compiler speccov already depends on does that work, file
+// by file, with the options of the tsconfig nearest to each file.
+import { readFileSync } from 'node:fs';
+import nodeModule from 'node:module';
+import { dirname, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import ts from 'typescript';
+
+const TYPESCRIPT_FILE = /\.[cm]?tsx?$/u;
+const DECLARATION_FILE = /\.d\.[cm]?ts$/u;
+
+// Reading a tsconfig also lists the files it includes. Only its options matter here.
+const configHost = { ...ts.sys, readDirectory: () => [], onUnRecoverableConfigFileDiagnostic: () => {} };
+const optionsByConfig = new Map();
+
+function optionsFor(fileName) {
+    // A dependency was not written under the project's tsconfig: it gets the defaults.
+    const config = fileName.includes(`${sep}node_modules${sep}`)
+        ? undefined
+        : ts.findConfigFile(dirname(fileName), ts.sys.fileExists);
+    const key = config ?? '';
+    let options = optionsByConfig.get(key);
+    if (options === undefined) {
+        const parsed = config === undefined ? undefined : ts.getParsedCommandLineOfConfigFile(config, undefined, configHost);
+        // TODO(ceiling): every file comes out as an ES module, so a project that relies on
+        // `require` or `__dirname` in its TypeScript does not load: emit CommonJS for those.
+        options = {
+            ...parsed?.options,
+            module: ts.ModuleKind.ESNext,
+            importHelpers: false,
+            sourceMap: false,
+            inlineSourceMap: true,
+            inlineSources: true,
+        };
+        optionsByConfig.set(key, options);
+    }
+    return options;
+}
+
+function resolve(specifier, context, nextResolve) {
+    try {
+        return nextResolve(specifier, context);
+    } catch (error) {
+        if (context.parentURL?.startsWith('file:') !== true) {
+            throw error;
+        }
+        const parent = fileURLToPath(context.parentURL);
+        const found = ts.resolveModuleName(specifier, parent, optionsFor(parent), ts.sys).resolvedModule;
+        if (found === undefined || DECLARATION_FILE.test(found.resolvedFileName)) {
+            throw error;
+        }
+        return { url: pathToFileURL(found.resolvedFileName).href, shortCircuit: true };
+    }
+}
+
+function load(url, context, nextLoad) {
+    if (!url.startsWith('file:') || !TYPESCRIPT_FILE.test(url)) {
+        return nextLoad(url, context);
+    }
+    const fileName = fileURLToPath(url);
+    const { outputText } = ts.transpileModule(readFileSync(fileName, 'utf8'), {
+        compilerOptions: optionsFor(fileName),
+        fileName,
+    });
+    return { format: 'module', source: outputText, shortCircuit: true };
+}
+
+if (process.versions.bun === undefined) {
+    // The inlined source maps keep an error raised by a rule on the line the user wrote.
+    process.setSourceMapsEnabled(true);
+    nodeModule.registerHooks({ resolve, load });
+}
+
+await import('../src/cli.ts');

package/package.json

@@ -1,6 +1,64 @@
 {
-  "name": "@codesema/speccov",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@codesema/speccov",
+    "version": "0.2.1",
+    "description": "Finds the behaviours no rule guarantees, and puts them as questions.",
+    "type": "module",
+    "license": "MIT",
+    "author": "Hasan TASKIN",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/getCodesema/speccov.git"
+    },
+    "keywords": [
+        "ast",
+        "codesema",
+        "hardening",
+        "n-plus-one",
+        "property-based-testing",
+        "static-analysis",
+        "typescript"
+    ],
+    "engines": {
+        "node": ">=22.15.0",
+        "bun": ">=1.3.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "bin": {
+        "speccov": "bin/speccov.mjs"
+    },
+    "exports": {
+        ".": "./src/index.ts",
+        "./typeorm": "./src/adapters/typeorm.ts"
+    },
+    "files": [
+        "bin",
+        "src",
+        "!src/**/*.test.ts",
+        "!src/scan/virtual-program.ts"
+    ],
+    "scripts": {
+        "prepare": "lefthook install || echo \"WARNING: lefthook install failed — git hooks are NOT active (no secret scan, no format or lint on commit). Run `bun run prepare` again once git and lefthook are available.\"",
+        "test": "bun test",
+        "typecheck": "tsc --noEmit",
+        "lint": "oxlint",
+        "format": "prettier --write . --cache",
+        "format:check": "prettier --check . --cache",
+        "verify": "bun run typecheck && bun run lint && bun test"
+    },
+    "dependencies": {
+        "typescript": "^6.0.3"
+    },
+    "devDependencies": {
+        "@commitlint/cli": "^21.2.3",
+        "@commitlint/config-conventional": "^21.2.3",
+        "@types/bun": "latest",
+        "better-sqlite3": "^13.0.3",
+        "lefthook": "^2.2.2",
+        "oxlint": "^1.88.0",
+        "pg": "^8.23.1",
+        "prettier": "^3.9.10",
+        "typeorm": "^1.1.2"
+    }
+}

package/src/adapters/typeorm.ts

@@ -0,0 +1,90 @@
+import type { Counter } from '../counter';
+
+/**
+ * Structural subset of TypeORM's `Logger` interface. Declared here rather than
+ * imported: speccov depends on no ORM.
+ */
+export type TypeOrmLogger = {
+    logQuery(query: string, parameters?: unknown[], queryRunner?: unknown): void;
+    logQueryError(error: string | Error, query: string, parameters?: unknown[], queryRunner?: unknown): void;
+    logQuerySlow(time: number, query: string, parameters?: unknown[], queryRunner?: unknown): void;
+    logSchemaBuild(message: string, queryRunner?: unknown): void;
+    logMigration(message: string, queryRunner?: unknown): void;
+    log(level: 'log' | 'info' | 'warn', message: unknown, queryRunner?: unknown): void;
+};
+
+export type CountingLoggerOptions = {
+    /** Decides whether a query counts. Defaults to {@link isDataQuery}. */
+    readonly counts?: (query: string) => boolean;
+};
+
+/** Transaction boundaries: TypeORM hands them to the logger like any other query. */
+const TRANSACTION_CONTROL = ['START TRANSACTION', 'BEGIN', 'COMMIT', 'ROLLBACK', 'SAVEPOINT', 'RELEASE'];
+
+/**
+ * Connection introspection functions. TypeORM calls them in several shapes
+ * (`SELECT version()`, `SELECT current_schema() AS "currentSchema"`, `SELECT * FROM
+ * current_schema()`): they are recognised by the function, not by the whole query.
+ */
+const CONNECTION_FUNCTIONS = ['VERSION()', 'CURRENT_SCHEMA()', 'CURRENT_DATABASE()'];
+
+/** `FROM pg_tables`, `JOIN pg_namespace`… Postgres reserves the `pg_` prefix: never a business table. */
+const SYSTEM_RELATION = /\s(?:FROM|JOIN)\s+PG_/u;
+
+/** A query that reads no table, or only a system function. */
+const NO_USER_TABLE = /\sFROM\s+(?!CURRENT_)/u;
+
+/** Schema definition verbs: `synchronize` and the migrations, not the business code. */
+const SCHEMA_VERBS = ['CREATE ', 'ALTER ', 'DROP ', 'TRUNCATE '];
+
+/** Introspection catalogues, read by `synchronize`. */
+const CATALOGS = ['INFORMATION_SCHEMA.', 'OBJ_DESCRIPTION('];
+
+/**
+ * True if the query is a read or a write of data, and not of infrastructure.
+ *
+ * Deliberately conservative: under-counting would *miss* N+1s, and that is the dangerous
+ * direction. When in doubt, a query counts.
+ */
+export function isDataQuery(query: string): boolean {
+    // Quotes are stripped: TypeORM writes `"information_schema"."tables"`, and the dot is
+    // then no longer flush against the catalogue name.
+    const normalised = query.trim().replaceAll(/\s+/gu, ' ').replaceAll('"', '').toUpperCase();
+    if (TRANSACTION_CONTROL.some((keyword) => normalised === keyword || normalised.startsWith(`${keyword} `))) {
+        return false;
+    }
+    const callsConnectionFunction = CONNECTION_FUNCTIONS.some((name) => normalised.includes(name));
+    if (callsConnectionFunction && !NO_USER_TABLE.test(normalised)) {
+        return false;
+    }
+    if (SCHEMA_VERBS.some((verb) => normalised.startsWith(verb))) {
+        return false;
+    }
+    if (SYSTEM_RELATION.test(normalised)) {
+        return false;
+    }
+    return !CATALOGS.some((catalog) => normalised.includes(catalog));
+}
+
+/**
+ * A TypeORM logger that does nothing but count. Pass it as the DataSource `logger` option.
+ *
+ * `logQueryError` counts too: a query that fails did reach the database, it weighs as much as
+ * any other in an N+1.
+ */
+export function countingLogger(counter: Counter, options: CountingLoggerOptions = {}): TypeOrmLogger {
+    const counts = options.counts ?? isDataQuery;
+    const hit = (query: string): void => {
+        if (counts(query)) {
+            counter.hit();
+        }
+    };
+    return {
+        logQuery: (query) => hit(query),
+        logQueryError: (_error, query) => hit(query),
+        logQuerySlow: () => {},
+        logSchemaBuild: () => {},
+        logMigration: () => {},
+        log: () => {},
+    };
+}

package/src/answers.ts

@@ -0,0 +1,126 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { EPSILON } from './growth';
+import type { Lacuna, Verdict } from './rule';
+
+/**
+ * A human answer to a gap, made mechanisable.
+ *
+ * Accepting is writing a rule: `magnitude` is the accepted threshold. Past it, this is no
+ * longer the question someone answered — it is a violation.
+ */
+export type Answer = {
+    readonly rule: string;
+    readonly magnitude: number;
+    /** What was being measured at the moment of acceptance. */
+    readonly detail: string;
+    /** Date of the acceptance. */
+    readonly at: string;
+    /** Why it is intended. Optional, but it is what gets reread in six months. */
+    readonly why?: string;
+};
+
+export const DEFAULT_ANSWERS_PATH = '.speccov/answers.json';
+
+type AnswerFile = {
+    readonly version: 1;
+    readonly answers: readonly Answer[];
+};
+
+/**
+ * Loads the answers. A missing file is normal — it is the first pass.
+ *
+ * An unreadable file **throws**: taking it for an empty file would make everything noisy,
+ * taking it for "everything accepted" would make it blind. Both are worse than a halt.
+ */
+export async function loadAnswers(path: string): Promise<readonly Answer[]> {
+    let raw: string;
+    try {
+        raw = await readFile(path, 'utf8');
+    } catch (cause) {
+        if ((cause as NodeJS.ErrnoException).code === 'ENOENT') {
+            return [];
+        }
+        throw cause;
+    }
+    return parseAnswers(JSON.parse(raw), path);
+}
+
+export async function saveAnswers(path: string, answers: readonly Answer[]): Promise<void> {
+    const file: AnswerFile = { version: 1, answers: [...answers].sort((left, right) => left.rule.localeCompare(right.rule)) };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(file, null, 4)}\n`, 'utf8');
+}
+
+export function parseAnswers(value: unknown, path: string): readonly Answer[] {
+    const file = value as Partial<AnswerFile> | null;
+    if (file === null || typeof file !== 'object' || file.version !== 1 || !Array.isArray(file.answers)) {
+        throw new Error(`speccov: ${path} is not a valid answers file (expected { version: 1, answers: [] }).`);
+    }
+    return file.answers.map((answer, index) => parseAnswer(answer, path, index));
+}
+
+function parseAnswer(value: unknown, path: string, index: number): Answer {
+    const answer = value as Partial<Answer> | null;
+    const valid =
+        answer !== null &&
+        typeof answer === 'object' &&
+        typeof answer.rule === 'string' &&
+        typeof answer.magnitude === 'number' &&
+        Number.isFinite(answer.magnitude) &&
+        typeof answer.detail === 'string' &&
+        typeof answer.at === 'string';
+    if (!valid) {
+        throw new Error(`speccov: answer ${index} is unreadable in ${path}.`);
+    }
+    return typeof answer.why === 'string'
+        ? { ...(answer as Answer) }
+        : { rule: answer.rule, magnitude: answer.magnitude, detail: answer.detail, at: answer.at };
+}
+
+export type Applied = {
+    readonly verdicts: readonly Verdict[];
+    /** Gaps kept quiet because a human already answered. Counted, never invisible. */
+    readonly accepted: readonly Lacuna[];
+};
+
+/**
+ * Applies the known answers.
+ *
+ * An accepted gap disappears from the report but stays counted. An accepted gap whose
+ * magnitude has passed the threshold becomes visible again — as a violation, because a
+ * human had ruled on it and the fact changed under them.
+ */
+export function applyAnswers(verdicts: readonly Verdict[], answers: readonly Answer[]): Applied {
+    const byRule = new Map(answers.map((answer) => [answer.rule, answer]));
+    const kept: Verdict[] = [];
+    const accepted: Lacuna[] = [];
+
+    for (const verdict of verdicts) {
+        const answer = verdict.kind === 'lacuna' ? byRule.get(verdict.rule.name) : undefined;
+        if (answer === undefined || verdict.kind !== 'lacuna') {
+            kept.push(verdict);
+        } else if (verdict.magnitude <= answer.magnitude + EPSILON) {
+            accepted.push(verdict);
+        } else {
+            kept.push({
+                kind: 'infraction',
+                rule: verdict.rule,
+                measurements: verdict.measurements,
+                magnitude: verdict.magnitude,
+                detail: `${verdict.detail}. Accepted on ${answer.at} at a magnitude of ${round(answer.magnitude)}; the threshold is exceeded.`,
+            });
+        }
+    }
+    return { verdicts: kept, accepted };
+}
+
+/** Turns a gap into a "this is intended" answer, at the threshold measured today. */
+export function accept(lacuna: Lacuna, at: string, why?: string): Answer {
+    const answer = { rule: lacuna.rule.name, magnitude: lacuna.magnitude, detail: lacuna.detail, at };
+    return why === undefined || why.trim() === '' ? answer : { ...answer, why: why.trim() };
+}
+
+function round(value: number): number {
+    return Math.round(value * 100) / 100;
+}