@kernlang/review 2.0.0 → 3.1.0

package/dist/suppression/parse-directives.js

@@ -0,0 +1,161 @@
+/**
+ * Parse kern-ignore directives from source text.
+ *
+ * Supported syntax:
+ *   // kern-ignore <rule-id>[, <rule-id>...]       — suppress on same or next non-comment line
+ *   // kern-ignore-file <rule-id>[, <rule-id>...]   — suppress for entire file (first 5 lines)
+ *   # kern-ignore <rule-id>[, <rule-id>...]         — Python variant
+ *   # kern-ignore-file <rule-id>[, <rule-id>...]    — Python variant
+ */
+import { createFingerprint } from '../types.js';
+/** Known concept rule IDs — these only support file-level suppression */
+const CONCEPT_RULE_IDS = new Set([
+    'unguarded-effect',
+    'unrecovered-effect',
+    'ignored-error',
+    'boundary-mutation',
+    'illegal-dependency',
+]);
+/** Matches: // kern-ignore[-file] rule1, rule2 */
+const TS_DIRECTIVE = /\/\/\s*kern-ignore(?:-(file))?\s+([\w-][\w,-\s]*)/;
+/** Matches: # kern-ignore[-file] rule1, rule2 */
+const PY_DIRECTIVE = /#\s*kern-ignore(?:-(file))?\s+([\w-][\w,-\s]*)/;
+/** Matches bare: // kern-ignore (no rule IDs) */
+const TS_BARE = /\/\/\s*kern-ignore\s*$/;
+const PY_BARE = /#\s*kern-ignore\s*$/;
+export function isConceptRule(ruleId) {
+    return CONCEPT_RULE_IDS.has(ruleId);
+}
+/**
+ * Parse all suppression directives from source text.
+ * Returns directives + any warnings (e.g., bare kern-ignore, concept rule on line-level).
+ */
+export function parseDirectives(source, filePath) {
+    const lines = source.split('\n');
+    const isPython = filePath.endsWith('.py');
+    const directivePattern = isPython ? PY_DIRECTIVE : TS_DIRECTIVE;
+    const barePattern = isPython ? PY_BARE : TS_BARE;
+    const isCommentLine = isPython
+        ? (line) => line.trimStart().startsWith('#')
+        : (line) => line.trimStart().startsWith('//');
+    const directives = [];
+    const warnings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        // Check for bare kern-ignore (no rule ID) — emit warning
+        if (barePattern.test(line)) {
+            warnings.push({
+                source: 'kern',
+                ruleId: 'kern-ignore-bare',
+                severity: 'warning',
+                category: 'style',
+                message: `Bare kern-ignore without rule ID — specify rules: // kern-ignore <rule-id>`,
+                primarySpan: { file: filePath, startLine: lineNum, startCol: 1, endLine: lineNum, endCol: line.length },
+                fingerprint: createFingerprint('kern-ignore-bare', lineNum, 1),
+            });
+            continue;
+        }
+        const match = directivePattern.exec(line);
+        if (!match)
+            continue;
+        const isFileLevel = match[1] === 'file';
+        const ruleIds = match[2].split(',').map(r => r.trim()).filter(Boolean);
+        if (ruleIds.length === 0)
+            continue;
+        // File-level directives must appear in the first 5 lines
+        if (isFileLevel && lineNum > 5) {
+            warnings.push({
+                source: 'kern',
+                ruleId: 'kern-ignore-position',
+                severity: 'warning',
+                category: 'style',
+                message: `kern-ignore-file must appear in the first 5 lines of the file (found at line ${lineNum})`,
+                primarySpan: { file: filePath, startLine: lineNum, startCol: 1, endLine: lineNum, endCol: line.length },
+                fingerprint: createFingerprint('kern-ignore-position', lineNum, 1),
+            });
+            continue;
+        }
+        // Concept rules with line-level suppression — emit warning, suggest file-level
+        if (!isFileLevel) {
+            const conceptRules = ruleIds.filter(isConceptRule);
+            if (conceptRules.length > 0) {
+                warnings.push({
+                    source: 'kern',
+                    ruleId: 'kern-ignore-concept',
+                    severity: 'warning',
+                    category: 'style',
+                    message: `'${conceptRules.join(', ')}' ${conceptRules.length === 1 ? 'is a' : 'are'} concept rule${conceptRules.length === 1 ? '' : 's'} — use '// kern-ignore-file ${conceptRules.join(', ')}' at the top of the file instead`,
+                    primarySpan: { file: filePath, startLine: lineNum, startCol: 1, endLine: lineNum, endCol: line.length },
+                    fingerprint: createFingerprint('kern-ignore-concept', lineNum, 1),
+                });
+                // Still process non-concept rules on this line
+                const nonConcept = ruleIds.filter(r => !isConceptRule(r));
+                if (nonConcept.length === 0)
+                    continue;
+                // Fall through with non-concept rules only
+                ruleIds.length = 0;
+                ruleIds.push(...nonConcept);
+            }
+        }
+        if (isFileLevel) {
+            directives.push({
+                type: 'file',
+                ruleIds,
+                file: filePath,
+                source: 'inline',
+                commentLine: lineNum,
+            });
+        }
+        else {
+            // Same-line: check if the directive is on a line with actual code
+            // If the line is comment-only, it applies to the next non-comment, non-blank line
+            const trimmed = line.trimStart();
+            const isCommentOnly = isPython
+                ? trimmed.startsWith('#') && !trimmed.replace(/#.*/, '').trim()
+                : trimmed.startsWith('//');
+            let targetLine;
+            if (isCommentOnly) {
+                // Find next non-comment, non-blank line
+                targetLine = lineNum; // fallback
+                for (let j = i + 1; j < lines.length; j++) {
+                    const nextLine = lines[j].trim();
+                    if (nextLine === '')
+                        continue;
+                    if (isCommentLine(nextLine))
+                        continue;
+                    targetLine = j + 1;
+                    break;
+                }
+            }
+            else {
+                // Inline comment on same line as code — suppress this line
+                targetLine = lineNum;
+            }
+            directives.push({
+                type: 'line',
+                ruleIds,
+                file: filePath,
+                line: targetLine,
+                source: 'inline',
+                commentLine: lineNum,
+            });
+        }
+    }
+    return { directives, warnings };
+}
+/**
+ * Create config-level suppression directives from disabledRules.
+ * These apply to all files (file field is '*').
+ */
+export function configDirectives(disabledRules) {
+    if (disabledRules.length === 0)
+        return [];
+    return [{
+            type: 'file',
+            ruleIds: disabledRules,
+            file: '*',
+            source: 'config',
+        }];
+}
+//# sourceMappingURL=parse-directives.js.map

package/dist/suppression/parse-directives.js.map

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

package/dist/suppression/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Types for the review suppression system.
+ */
+import type { ReviewFinding } from '../types.js';
+/** A parsed suppression directive from source comments or config */
+export interface SuppressionDirective {
+    /** 'line' = suppress on a specific line, 'file' = suppress entire file */
+    type: 'line' | 'file';
+    /** Rule IDs to suppress (always explicit — no blanket suppression) */
+    ruleIds: string[];
+    /** File this directive applies to */
+    file: string;
+    /** Target line (for 'line' type — the line whose findings are suppressed) */
+    line?: number;
+    /** Where this directive came from */
+    source: 'inline' | 'config';
+    /** The raw line number where the comment was found (for unused-directive warnings) */
+    commentLine?: number;
+}
+/** Result of applying suppression to a set of findings */
+export interface SuppressionResult {
+    /** Findings that passed (not suppressed) */
+    findings: ReviewFinding[];
+    /** Findings that were suppressed */
+    suppressed: ReviewFinding[];
+    /** All parsed directives */
+    directives: SuppressionDirective[];
+    /** Directives that matched no findings (potential stale comments) */
+    unusedDirectives: SuppressionDirective[];
+}
+/** Strict mode levels for CI */
+export type StrictMode = false | 'inline' | 'all';

package/dist/suppression/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types for the review suppression system.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/suppression/types.js.map

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

package/dist/taint.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Taint Tracking — source→sink analysis on KERN IR.
+ *
+ * Phase 2 of the security pipeline. Works on InferResult[] handler bodies.
+ *
+ * Two modes:
+ *   analyzeTaint()          — intra-procedural (single file)
+ *   analyzeTaintCrossFile() — inter-procedural (follows imports across files)
+ *
+ * Also validates sanitizer sufficiency: parseInt stops SQL injection on
+ * numeric values but NOT command injection. DOMPurify stops XSS but
+ * NOT SQL injection. The sufficiency matrix catches these mismatches.
+ */
+import { type SourceFile } from 'ts-morph';
+import type { InferResult, ReviewFinding } from './types.js';
+export interface TaintSource {
+    name: string;
+    origin: string;
+    line?: number;
+}
+export interface TaintSink {
+    name: string;
+    category: 'command' | 'fs' | 'sql' | 'redirect' | 'eval' | 'template';
+    taintedArg: string;
+    line?: number;
+}
+export interface TaintPath {
+    source: TaintSource;
+    sink: TaintSink;
+    sanitized: boolean;
+    sanitizer?: string;
+    insufficientSanitizer?: string;
+}
+export interface TaintResult {
+    fnName: string;
+    filePath: string;
+    startLine: number;
+    paths: TaintPath[];
+}
+type SinkCategory = TaintSink['category'];
+/**
+ * Check if a sanitizer is actually sufficient for a given sink category.
+ * Returns true if the sanitizer protects against the sink, false if it's
+ * a mismatch (e.g., parseInt used to "sanitize" command injection).
+ */
+export declare function isSanitizerSufficient(sanitizerName: string, sinkCategory: SinkCategory): boolean;
+export interface CrossFileTaintResult {
+    callerFile: string;
+    callerFn: string;
+    callerLine: number;
+    calleeFile: string;
+    calleeFn: string;
+    taintedArgs: string[];
+    sinkInCallee: TaintSink;
+    source: TaintSource;
+}
+/** Map of exported function names → file path + param info */
+export interface ExportedFunction {
+    filePath: string;
+    fnName: string;
+    params: string;
+    hasSink: boolean;
+    sinks: TaintSink[];
+}
+/**
+ * Run taint analysis on all fn nodes in inferred results.
+ * When sourceFile is provided, uses AST-based analysis (more accurate).
+ * Falls back to regex-based analysis when no SourceFile available.
+ */
+export declare function analyzeTaint(inferred: InferResult[], filePath: string, sourceFile?: SourceFile): TaintResult[];
+/**
+ * Multi-hop taint propagation using worklist algorithm.
+ * Propagates until fixed point or configurable depth limit.
+ *
+ * Handles all assignment patterns:
+ * - const b = a
+ * - const b = a.trim()
+ * - const {x} = obj
+ * - let b; b = a
+ *
+ * @param code - Handler code string
+ * @param initialTainted - Set of initially tainted variable names
+ * @param maxDepth - Maximum propagation depth (default: 3)
+ * @returns Set of all tainted variable names after fixed point or depth limit
+ */
+export declare function propagateTaintMultiHop(code: string, initialTainted: Set<string>, maxDepth?: number): Set<string>;
+/**
+ * Convert taint results into ReviewFinding[] for the unified pipeline.
+ */
+export declare function taintToFindings(results: TaintResult[]): ReviewFinding[];
+/**
+ * Build a map of exported functions across all files.
+ * Maps "filePath::fnName" → ExportedFunction with sink info.
+ */
+export declare function buildExportMap(inferredPerFile: Map<string, InferResult[]>): Map<string, ExportedFunction>;
+/**
+ * Build import→function resolution map.
+ * Maps "importingFile::importedName" → absolute file path of the definition.
+ */
+export declare function buildImportMap(inferredPerFile: Map<string, InferResult[]>, graphImports: Map<string, string[]>): Map<string, string>;
+/**
+ * Cross-file taint analysis.
+ *
+ * For each handler function with tainted params:
+ *   1. Find calls to imported functions in the handler body
+ *   2. Check if tainted data is passed as an argument
+ *   3. Look up the target function — does it have a dangerous sink?
+ *   4. If yes and no sanitizer in between → cross-file taint path
+ */
+export declare function analyzeTaintCrossFile(inferredPerFile: Map<string, InferResult[]>, graphImports: Map<string, string[]>): CrossFileTaintResult[];
+/**
+ * Convert cross-file taint results into ReviewFinding[].
+ */
+export declare function crossFileTaintToFindings(results: CrossFileTaintResult[]): ReviewFinding[];
+export {};