@kernlang/review 3.3.9 → 3.4.0

package/dist/policy.d.ts

@@ -0,0 +1,22 @@
+import type { ReviewConfig, ReviewPolicy } from './types.js';
+export interface ReviewPolicyProfile {
+    policy: ReviewPolicy;
+    crossStackMode: 'guard' | 'audit';
+    minConfidence: number;
+    maxErrors?: number;
+    maxWarnings?: number;
+    strict?: false | 'inline' | 'all';
+    strictParse?: boolean;
+    description: string;
+}
+export interface ReviewPolicyExplicitOptions {
+    crossStackMode?: boolean;
+    minConfidence?: boolean;
+    maxErrors?: boolean;
+    maxWarnings?: boolean;
+    strict?: boolean;
+    strictParse?: boolean;
+}
+export declare function getReviewPolicyProfile(policy: ReviewPolicy): ReviewPolicyProfile;
+export declare function inferReviewPolicy(config?: Pick<ReviewConfig, 'policy' | 'crossStackMode'>): ReviewPolicy;
+export declare function applyReviewPolicyDefaults(config: ReviewConfig, explicit?: ReviewPolicyExplicitOptions): ReviewConfig;

package/dist/policy.js

@@ -0,0 +1,47 @@
+const REVIEW_POLICY_PROFILES = {
+    guard: {
+        policy: 'guard',
+        crossStackMode: 'guard',
+        minConfidence: 0,
+        description: 'Low-noise review posture for local guardrails and PR feedback.',
+    },
+    ci: {
+        policy: 'ci',
+        crossStackMode: 'guard',
+        minConfidence: 0.75,
+        maxErrors: 0,
+        maxWarnings: 0,
+        strict: 'inline',
+        strictParse: true,
+        description: 'Strict CI posture: high-confidence findings only, no warnings by default, strict parsing.',
+    },
+    audit: {
+        policy: 'audit',
+        crossStackMode: 'audit',
+        minConfidence: 0,
+        description: 'Broad exploratory posture for local investigations and rule calibration.',
+    },
+};
+export function getReviewPolicyProfile(policy) {
+    return REVIEW_POLICY_PROFILES[policy];
+}
+export function inferReviewPolicy(config) {
+    if (config?.policy)
+        return config.policy;
+    return config?.crossStackMode === 'audit' ? 'audit' : 'guard';
+}
+export function applyReviewPolicyDefaults(config, explicit = {}) {
+    const policy = inferReviewPolicy(config);
+    const profile = getReviewPolicyProfile(policy);
+    return {
+        ...config,
+        policy,
+        crossStackMode: explicit.crossStackMode ? config.crossStackMode : profile.crossStackMode,
+        minConfidence: explicit.minConfidence ? config.minConfidence : profile.minConfidence,
+        maxErrors: explicit.maxErrors ? config.maxErrors : (profile.maxErrors ?? config.maxErrors),
+        maxWarnings: explicit.maxWarnings ? config.maxWarnings : (profile.maxWarnings ?? config.maxWarnings),
+        strict: explicit.strict ? config.strict : (profile.strict ?? config.strict),
+        strictParse: explicit.strictParse ? config.strictParse : (profile.strictParse ?? config.strictParse),
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAsBA,MAAM,sBAAsB,GAA8C;IACxE,KAAK,EAAE;QACL,MAAM,EAAE,OAAO;QACf,cAAc,EAAE,OAAO;QACvB,aAAa,EAAE,CAAC;QAChB,WAAW,EAAE,gEAAgE;KAC9E;IACD,EAAE,EAAE;QACF,MAAM,EAAE,IAAI;QACZ,cAAc,EAAE,OAAO;QACvB,aAAa,EAAE,IAAI;QACnB,SAAS,EAAE,CAAC;QACZ,WAAW,EAAE,CAAC;QACd,MAAM,EAAE,QAAQ;QAChB,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,2FAA2F;KACzG;IACD,KAAK,EAAE;QACL,MAAM,EAAE,OAAO;QACf,cAAc,EAAE,OAAO;QACvB,aAAa,EAAE,CAAC;QAChB,WAAW,EAAE,0EAA0E;KACxF;CACF,CAAC;AAEF,MAAM,UAAU,sBAAsB,CAAC,MAAoB;IACzD,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAwD;IACxF,IAAI,MAAM,EAAE,MAAM;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IACzC,OAAO,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,MAAoB,EACpB,WAAwC,EAAE;IAE1C,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAE/C,OAAO;QACL,GAAG,MAAM;QACT,MAAM;QACN,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc;QACxF,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa;QACpF,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC;QAC1F,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,CAAC;QACpG,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC;QAC3E,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,CAAC;KACrG,CAAC;AACJ,CAAC"}

package/dist/project-context.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Project-Context — repo-level signals for the review pipeline.
+ *
+ * Reads project configs (tsconfig.json, package.json) and .gitignore so rules
+ * can gate on what the user already enforces elsewhere. Designed to be SAFE on
+ * adversarial inputs:
+ *
+ *  - **JSON-only.** No executable config readers (no eslint.config.js eval).
+ *    Phase 2 may add YAML/TOML but only via safeLoad; never `require()` of a
+ *    user-controlled file.
+ *  - **Realpath containment.** Any path resolved from a config (extends, etc.)
+ *    must live under the project root after `realpathSync` — otherwise it is
+ *    ignored. Defends against `extends: '../../../etc/passwd'` and symlink
+ *    traversal attacks surfaced by the Phase 1 red-team.
+ *  - **Content-hash cache.** Cache key is hashed file content + extends chain
+ *    (reuses the cache.ts pattern). mtime is unsound on second-resolution
+ *    filesystems and on TOCTOU windows where bytes change but mtime does not.
+ *  - **LRU eviction.** Max 128 cached project roots — defense against the
+ *    long-running Guard bot accumulating per-PR worktree paths until OOM.
+ *  - **Pattern-length cap on .gitignore.** Discards any individual pattern
+ *    longer than 256 chars. Defense against ReDoS via crafted negation +
+ *    quantifier patterns from the red-team.
+ */
+/** What `getProjectContext` returns. Extended in later phases. */
+export interface ProjectContext {
+    /** Absolute, realpath-resolved project root. */
+    root: string;
+    /** Parsed root package.json — restricted to fields we care about. */
+    packageJson?: ProjectPackageJson;
+    /** Parsed tsconfig (top-level only — extends chain is hashed but not deep-merged here). */
+    tsconfig?: ProjectTsconfig;
+    /** Compiled .gitignore matchers, in walk order (root first, deeper later). */
+    gitignore: GitignoreMatchers;
+    /**
+     * External linter configurations — used to demote kern findings that overlap
+     * with rules the project already enforces. Phase 2 is intentionally limited
+     * to JSON-only readers: `.eslintrc.json`, `package.json` `eslintConfig`, and
+     * `biome.json`. `eslint.config.js` is **never** evaluated (RCE risk surfaced
+     * by Phase 1 red-team). Per-file `overrides` resolution requires the async
+     * ESLint API and is left to callers via a future pre-warm path.
+     */
+    external: ExternalLinterConfig;
+    /**
+     * Set of POSIX-relative paths that `git ls-files` reports as tracked. A file
+     * being tracked overrides .gitignore for skip-list purposes — published
+     * artifacts (e.g. packages/sdk/dist/client.gen.ts) get reviewed even when
+     * the directory matches `.gitignore`. Empty set if not a git repo.
+     */
+    gitTrackedFiles: Set<string>;
+    /**
+     * Stable hash of every config input that contributed to this context. Used as
+     * the cache key; if any config file changes, the hash changes and the entry
+     * is recomputed.
+     */
+    contentHash: string;
+}
+export interface ProjectPackageJson {
+    name?: string;
+    type?: 'module' | 'commonjs';
+    workspaces?: string[];
+    bin?: Record<string, string> | string;
+    exports?: unknown;
+    private?: boolean;
+}
+export interface ProjectTsconfig {
+    /** True iff `compilerOptions.strict === true` is set on the resolved config. */
+    strict?: boolean;
+    /** Per-flag — overrides composite `strict`. Future phases dial confidence per flag. */
+    strictNullChecks?: boolean;
+    noImplicitAny?: boolean;
+    noUnusedLocals?: boolean;
+    noUnusedParameters?: boolean;
+}
+/** External linter rule IDs that are enabled at error/warn. */
+export interface ExternalLinterConfig {
+    /** Rule IDs from `.eslintrc.json` / `package.json` eslintConfig that are at error or warn. */
+    eslintEnabledRules: Set<string>;
+    /** Rule IDs from `biome.json` linter.rules that are at error or warn. */
+    biomeEnabledRules: Set<string>;
+}
+/** Compiled gitignore matchers. Use `isPathIgnored` to query. */
+export interface GitignoreMatchers {
+    /** Patterns from the project root's .gitignore, in declaration order. */
+    rootPatterns: GitignorePattern[];
+}
+export interface GitignorePattern {
+    /** Original line as written, post-trim. */
+    raw: string;
+    /** Compiled regex. Pattern-length capped at 256 to avoid ReDoS. */
+    regex: RegExp;
+    /** Negation rule (`!foo`) — re-includes a previously-ignored path. */
+    negate: boolean;
+    /** Pattern is anchored to repo root (no slash in middle of pattern). */
+    matchDirsOnly: boolean;
+}
+/**
+ * Walk up from a starting directory looking for the nearest `package.json`.
+ * Returns undefined if none is found before the filesystem root. Used by
+ * per-file review entry points that need a project context but only have a
+ * file path.
+ */
+export declare function findProjectRoot(startDir: string): string | undefined;
+/**
+ * Get the project context for a project root. Cached by content hash —
+ * a config file edit invalidates the entry on next call.
+ */
+export declare function getProjectContext(projectRoot: string): ProjectContext;
+/** Test-only: clear cache between tests. */
+export declare function _resetProjectContextCache(): void;
+/** Test-only: report current cache size. */
+export declare function _projectContextCacheSize(): number;
+/**
+ * Returns true iff the file is matched by the project's .gitignore. Use
+ * `isReviewable` for the full skip-list semantics — this is the gitignore
+ * predicate alone.
+ */
+export declare function isPathIgnored(filePath: string, ctx: ProjectContext): boolean;
+/**
+ * Per-flag tsconfig strictness — phase 2.3 from the red-team. The composite
+ * `strict: true` is shorthand for several flags; users frequently enable
+ * `strictNullChecks` alone without the umbrella. Rules should query the
+ * specific flag they depend on, not `strict`, so that `strict:false` does
+ * not over-debuff a finding whose underlying guarantee is in fact present.
+ */
+export declare function isStrictFlagEffective(flag: keyof Required<ProjectTsconfig>, ctx: ProjectContext): boolean;
+/**
+ * The full skip-list predicate. A file is reviewable iff it is NOT
+ * (gitignored AND not git-tracked).
+ *
+ * This is the Phase 1 red-team's finding #4 fix: a tracked artifact that lives
+ * inside a gitignored directory (the classic `packages/sdk/dist/client.gen.ts`
+ * case) must remain reviewable. Suppression-by-skip-list is reserved for
+ * truly-untracked outputs.
+ */
+export declare function isReviewable(filePath: string, ctx: ProjectContext): boolean;