@rigour-labs/core 6.2.5 → 6.3.0

package/dist/semantic/learn/types.d.ts

@@ -0,0 +1,468 @@
+/**
+ * Rules learned from a fix: a before/after pair turned into a check.
+ *
+ * A learned rule is data (`.rigour/rules/<id>.json`), reviewed in pull
+ * requests like code. It is kept only when it fires on the code before the
+ * fix, is silent on the fixed code, and fires on few other places in the
+ * repository; the validation that proved this is stored with it.
+ */
+import { z } from 'zod';
+/** How a call is recognised: by its name, the declaration it resolves to, or its exact text. */
+export declare const CalleeMatcherSchema: z.ZodObject<{
+    level: z.ZodEnum<["name", "declaration", "text"]>;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    level: "name" | "text" | "declaration";
+}, {
+    key: string;
+    level: "name" | "text" | "declaration";
+}>;
+/** Narrows a rule to one function in one file: a regression guard for the fixed code. */
+export declare const ScopeSchema: z.ZodObject<{
+    file: z.ZodString;
+    fn: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    fn: string;
+}, {
+    file: string;
+    fn: string;
+}>;
+export declare const RequireOptionSchema: z.ZodObject<{
+    template: z.ZodLiteral<"require-option">;
+    callee: z.ZodObject<{
+        level: z.ZodEnum<["name", "declaration", "text"]>;
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        level: "name" | "text" | "declaration";
+    }, {
+        key: string;
+        level: "name" | "text" | "declaration";
+    }>;
+    argIndex: z.ZodNumber;
+    property: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodObject<{
+        file: z.ZodString;
+        fn: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        fn: string;
+    }, {
+        file: string;
+        fn: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    template: "require-option";
+    callee: {
+        key: string;
+        level: "name" | "text" | "declaration";
+    };
+    argIndex: number;
+    property: string;
+    value?: string | undefined;
+    scope?: {
+        file: string;
+        fn: string;
+    } | undefined;
+}, {
+    template: "require-option";
+    callee: {
+        key: string;
+        level: "name" | "text" | "declaration";
+    };
+    argIndex: number;
+    property: string;
+    value?: string | undefined;
+    scope?: {
+        file: string;
+        fn: string;
+    } | undefined;
+}>;
+export declare const RequireGuardSchema: z.ZodObject<{
+    template: z.ZodLiteral<"require-guard">;
+    callee: z.ZodObject<{
+        level: z.ZodEnum<["name", "declaration", "text"]>;
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        level: "name" | "text" | "declaration";
+    }, {
+        key: string;
+        level: "name" | "text" | "declaration";
+    }>;
+    property: z.ZodString;
+    guard: z.ZodString;
+    /** Apply only where the call's other arguments mention `guard` (e.g. the body carries it). */
+    appliesWhenArgsMention: z.ZodBoolean;
+    scope: z.ZodOptional<z.ZodObject<{
+        file: z.ZodString;
+        fn: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        fn: string;
+    }, {
+        file: string;
+        fn: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    template: "require-guard";
+    callee: {
+        key: string;
+        level: "name" | "text" | "declaration";
+    };
+    property: string;
+    guard: string;
+    appliesWhenArgsMention: boolean;
+    scope?: {
+        file: string;
+        fn: string;
+    } | undefined;
+}, {
+    template: "require-guard";
+    callee: {
+        key: string;
+        level: "name" | "text" | "declaration";
+    };
+    property: string;
+    guard: string;
+    appliesWhenArgsMention: boolean;
+    scope?: {
+        file: string;
+        fn: string;
+    } | undefined;
+}>;
+export declare const LearnedPatternSchema: z.ZodDiscriminatedUnion<"template", [z.ZodObject<{
+    template: z.ZodLiteral<"require-option">;
+    callee: z.ZodObject<{
+        level: z.ZodEnum<["name", "declaration", "text"]>;
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        level: "name" | "text" | "declaration";
+    }, {
+        key: string;
+        level: "name" | "text" | "declaration";
+    }>;
+    argIndex: z.ZodNumber;
+    property: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodObject<{
+        file: z.ZodString;
+        fn: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        fn: string;
+    }, {
+        file: string;
+        fn: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    template: "require-option";
+    callee: {
+        key: string;
+        level: "name" | "text" | "declaration";
+    };
+    argIndex: number;
+    property: string;
+    value?: string | undefined;
+    scope?: {
+        file: string;
+        fn: string;
+    } | undefined;
+}, {
+    template: "require-option";
+    callee: {
+        key: string;
+        level: "name" | "text" | "declaration";
+    };
+    argIndex: number;
+    property: string;
+    value?: string | undefined;
+    scope?: {
+        file: string;
+        fn: string;
+    } | undefined;
+}>, z.ZodObject<{
+    template: z.ZodLiteral<"require-guard">;
+    callee: z.ZodObject<{
+        level: z.ZodEnum<["name", "declaration", "text"]>;
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        level: "name" | "text" | "declaration";
+    }, {
+        key: string;
+        level: "name" | "text" | "declaration";
+    }>;
+    property: z.ZodString;
+    guard: z.ZodString;
+    /** Apply only where the call's other arguments mention `guard` (e.g. the body carries it). */
+    appliesWhenArgsMention: z.ZodBoolean;
+    scope: z.ZodOptional<z.ZodObject<{
+        file: z.ZodString;
+        fn: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        fn: string;
+    }, {
+        file: string;
+        fn: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    template: "require-guard";
+    callee: {
+        key: string;
+        level: "name" | "text" | "declaration";
+    };
+    property: string;
+    guard: string;
+    appliesWhenArgsMention: boolean;
+    scope?: {
+        file: string;
+        fn: string;
+    } | undefined;
+}, {
+    template: "require-guard";
+    callee: {
+        key: string;
+        level: "name" | "text" | "declaration";
+    };
+    property: string;
+    guard: string;
+    appliesWhenArgsMention: boolean;
+    scope?: {
+        file: string;
+        fn: string;
+    } | undefined;
+}>]>;
+export declare const LearnedRuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodLiteral<1>;
+    pattern: z.ZodDiscriminatedUnion<"template", [z.ZodObject<{
+        template: z.ZodLiteral<"require-option">;
+        callee: z.ZodObject<{
+            level: z.ZodEnum<["name", "declaration", "text"]>;
+            key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            key: string;
+            level: "name" | "text" | "declaration";
+        }, {
+            key: string;
+            level: "name" | "text" | "declaration";
+        }>;
+        argIndex: z.ZodNumber;
+        property: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodObject<{
+            file: z.ZodString;
+            fn: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            file: string;
+            fn: string;
+        }, {
+            file: string;
+            fn: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        template: "require-option";
+        callee: {
+            key: string;
+            level: "name" | "text" | "declaration";
+        };
+        argIndex: number;
+        property: string;
+        value?: string | undefined;
+        scope?: {
+            file: string;
+            fn: string;
+        } | undefined;
+    }, {
+        template: "require-option";
+        callee: {
+            key: string;
+            level: "name" | "text" | "declaration";
+        };
+        argIndex: number;
+        property: string;
+        value?: string | undefined;
+        scope?: {
+            file: string;
+            fn: string;
+        } | undefined;
+    }>, z.ZodObject<{
+        template: z.ZodLiteral<"require-guard">;
+        callee: z.ZodObject<{
+            level: z.ZodEnum<["name", "declaration", "text"]>;
+            key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            key: string;
+            level: "name" | "text" | "declaration";
+        }, {
+            key: string;
+            level: "name" | "text" | "declaration";
+        }>;
+        property: z.ZodString;
+        guard: z.ZodString;
+        /** Apply only where the call's other arguments mention `guard` (e.g. the body carries it). */
+        appliesWhenArgsMention: z.ZodBoolean;
+        scope: z.ZodOptional<z.ZodObject<{
+            file: z.ZodString;
+            fn: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            file: string;
+            fn: string;
+        }, {
+            file: string;
+            fn: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        template: "require-guard";
+        callee: {
+            key: string;
+            level: "name" | "text" | "declaration";
+        };
+        property: string;
+        guard: string;
+        appliesWhenArgsMention: boolean;
+        scope?: {
+            file: string;
+            fn: string;
+        } | undefined;
+    }, {
+        template: "require-guard";
+        callee: {
+            key: string;
+            level: "name" | "text" | "declaration";
+        };
+        property: string;
+        guard: string;
+        appliesWhenArgsMention: boolean;
+        scope?: {
+            file: string;
+            fn: string;
+        } | undefined;
+    }>]>;
+    message: z.ZodString;
+    severity: z.ZodEnum<["low", "medium", "high"]>;
+    source: z.ZodObject<{
+        commit: z.ZodOptional<z.ZodString>;
+        file: z.ZodString;
+        function: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        function: string;
+        file: string;
+        commit?: string | undefined;
+    }, {
+        function: string;
+        file: string;
+        commit?: string | undefined;
+    }>;
+    validation: z.ZodObject<{
+        firesBefore: z.ZodNumber;
+        firesAfter: z.ZodNumber;
+        maxHits: z.ZodNumber;
+        repoHits: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        firesBefore: number;
+        firesAfter: number;
+        maxHits: number;
+        repoHits: string[];
+    }, {
+        firesBefore: number;
+        firesAfter: number;
+        maxHits: number;
+        repoHits: string[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    validation: {
+        firesBefore: number;
+        firesAfter: number;
+        maxHits: number;
+        repoHits: string[];
+    };
+    version: 1;
+    id: string;
+    severity: "high" | "medium" | "low";
+    source: {
+        function: string;
+        file: string;
+        commit?: string | undefined;
+    };
+    pattern: {
+        template: "require-option";
+        callee: {
+            key: string;
+            level: "name" | "text" | "declaration";
+        };
+        argIndex: number;
+        property: string;
+        value?: string | undefined;
+        scope?: {
+            file: string;
+            fn: string;
+        } | undefined;
+    } | {
+        template: "require-guard";
+        callee: {
+            key: string;
+            level: "name" | "text" | "declaration";
+        };
+        property: string;
+        guard: string;
+        appliesWhenArgsMention: boolean;
+        scope?: {
+            file: string;
+            fn: string;
+        } | undefined;
+    };
+}, {
+    message: string;
+    validation: {
+        firesBefore: number;
+        firesAfter: number;
+        maxHits: number;
+        repoHits: string[];
+    };
+    version: 1;
+    id: string;
+    severity: "high" | "medium" | "low";
+    source: {
+        function: string;
+        file: string;
+        commit?: string | undefined;
+    };
+    pattern: {
+        template: "require-option";
+        callee: {
+            key: string;
+            level: "name" | "text" | "declaration";
+        };
+        argIndex: number;
+        property: string;
+        value?: string | undefined;
+        scope?: {
+            file: string;
+            fn: string;
+        } | undefined;
+    } | {
+        template: "require-guard";
+        callee: {
+            key: string;
+            level: "name" | "text" | "declaration";
+        };
+        property: string;
+        guard: string;
+        appliesWhenArgsMention: boolean;
+        scope?: {
+            file: string;
+            fn: string;
+        } | undefined;
+    };
+}>;
+export type CalleeMatcher = z.infer<typeof CalleeMatcherSchema>;
+export type LearnedPattern = z.infer<typeof LearnedPatternSchema>;
+export type LearnedRule = z.infer<typeof LearnedRuleSchema>;

package/dist/semantic/learn/types.js

@@ -0,0 +1,55 @@
+/**
+ * Rules learned from a fix: a before/after pair turned into a check.
+ *
+ * A learned rule is data (`.rigour/rules/<id>.json`), reviewed in pull
+ * requests like code. It is kept only when it fires on the code before the
+ * fix, is silent on the fixed code, and fires on few other places in the
+ * repository; the validation that proved this is stored with it.
+ */
+import { z } from 'zod';
+/** How a call is recognised: by its name, the declaration it resolves to, or its exact text. */
+export const CalleeMatcherSchema = z.object({
+    level: z.enum(['name', 'declaration', 'text']),
+    key: z.string().min(1),
+});
+/** Narrows a rule to one function in one file: a regression guard for the fixed code. */
+export const ScopeSchema = z.object({
+    file: z.string().min(1),
+    fn: z.string().min(1),
+});
+export const RequireOptionSchema = z.object({
+    template: z.literal('require-option'),
+    callee: CalleeMatcherSchema,
+    argIndex: z.number().int().min(0),
+    property: z.string().min(1),
+    value: z.string().optional(),
+    scope: ScopeSchema.optional(),
+});
+export const RequireGuardSchema = z.object({
+    template: z.literal('require-guard'),
+    callee: CalleeMatcherSchema,
+    property: z.string().min(1),
+    guard: z.string().min(1),
+    /** Apply only where the call's other arguments mention `guard` (e.g. the body carries it). */
+    appliesWhenArgsMention: z.boolean(),
+    scope: ScopeSchema.optional(),
+});
+export const LearnedPatternSchema = z.discriminatedUnion('template', [RequireOptionSchema, RequireGuardSchema]);
+export const LearnedRuleSchema = z.object({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    version: z.literal(1),
+    pattern: LearnedPatternSchema,
+    message: z.string(),
+    severity: z.enum(['low', 'medium', 'high']),
+    source: z.object({
+        commit: z.string().optional(),
+        file: z.string(),
+        function: z.string(),
+    }),
+    validation: z.object({
+        firesBefore: z.number().int(),
+        firesAfter: z.number().int(),
+        maxHits: z.number().int(),
+        repoHits: z.array(z.string()),
+    }),
+});

package/dist/semantic/origins.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where can an expression's value come from?
+ *
+ * Traces identifiers back through declarations (const/let initializers and
+ * reassignments), destructuring (including an element of `Promise.all([...])`),
+ * conditionals and `??`/`||`, using checker symbols rather than names. The
+ * result is a set of origins: a call, a parameter, an object literal, another
+ * literal, or unknown. Unknown origins are kept so rules can stay silent.
+ */
+import ts from 'typescript';
+import { type FunctionLike } from './ast.js';
+export type Origin = {
+    kind: 'call';
+    node: ts.CallExpression;
+} | {
+    kind: 'param';
+    fn: FunctionLike;
+    index: number;
+    node: ts.ParameterDeclaration;
+} | {
+    kind: 'object';
+    node: ts.ObjectLiteralExpression;
+} | {
+    kind: 'literal';
+    node: ts.Expression;
+} | {
+    kind: 'unknown';
+    node: ts.Node;
+};
+export declare function originsOf(checker: ts.TypeChecker, expr: ts.Expression, depth?: number, seen?: Set<ts.Node>): Origin[];
+/** Elements of `Promise.all([...])` / `Promise.allSettled([...])`, else undefined. */
+export declare function promiseAllItems(expr: ts.Expression): ts.NodeArray<ts.Expression> | undefined;
+export interface PropertyValues {
+    /** Direct values for the property. */
+    values: ts.Expression[];
+    /** Spreads whose object could not be resolved; the property may come from them. */
+    unresolvedSpreads: ts.Expression[];
+    /** Spread expressions that were resolved, in source order. */
+    spreads: ts.Expression[];
+}
+/** Values an object literal gives to `key`, following `...spread` of other object literals. */
+export declare function propertyValues(checker: ts.TypeChecker, obj: ts.ObjectLiteralExpression, key: string, depth?: number): PropertyValues;