@safegres/test 0.0.2 → 1.30.7

package/esm/report/view.js

@@ -0,0 +1,126 @@
+/**
+ * Selection: the layer between analysis and rendering.
+ *
+ * A `Report` is what the audit found — pure data, the same for everybody. A
+ * `ReportView` is what one reader should see: which planes, which dimensions,
+ * which sections, how much detail. Renderers consume the view and decide only
+ * how it *looks*, so "the team wants the perf score and their direct-role
+ * planes in the PR comment" is answered once here, rather than four times in
+ * four renderers that drift apart.
+ */
+export const ALL_SECTIONS = [
+    'scores',
+    'delta',
+    'findings',
+    'planes',
+    'scorecards',
+    'role-access',
+    'call-graph'
+];
+/** Glob match over plane names: `*` matches any run of characters. */
+export function matchPlane(pattern, name) {
+    if (pattern === name)
+        return true;
+    const rx = new RegExp(`^${pattern.split('*').map(escapeRegExp).join('.*')}$`);
+    return rx.test(name);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Everything presentation-adjacent about a report, decided once.
+ *
+ * Selection never edits the report: `exposedOnly` narrows what the view
+ * exposes, and the underlying `report.findings` stays whole so a JSON dump
+ * beside a pretty print is still the full picture.
+ */
+export function selectView(report, config = {}) {
+    const detail = config.detail ?? 'normal';
+    const dimensions = new Set(config.dimensions ?? ['security', 'perf']);
+    const sections = new Set(config.sections ?? ALL_SECTIONS);
+    const scores = [];
+    if (report.score && dimensions.has('security')) {
+        scores.push({
+            id: 'security',
+            label: 'Security',
+            dimension: 'security',
+            score: report.score,
+            ...(report.comparison?.security ? { delta: report.comparison.security } : {})
+        });
+    }
+    if (report.perf && dimensions.has('perf')) {
+        scores.push({
+            id: 'perf',
+            label: 'Performance',
+            dimension: 'perf',
+            score: report.perf.score,
+            ...(report.comparison?.perf ? { delta: report.comparison.perf } : {})
+        });
+    }
+    const secondary = (report.planes ?? []).filter((p) => !p.primary);
+    const patterns = config.planes ?? [];
+    const expandedPlanes = secondary.filter((p) => patterns.some((q) => matchPlane(q, p.name)));
+    for (const plane of expandedPlanes) {
+        if (plane.skipped)
+            continue;
+        scores.push({
+            id: `plane:${plane.name}`,
+            label: plane.name,
+            dimension: 'security',
+            score: plane.score,
+            plane
+        });
+    }
+    const scorecards = (report.scorecards ?? []).filter((c) => c.name !== 'default');
+    const securityAll = report.perf
+        ? report.findings.filter((f) => f.dimension !== 'perf')
+        : report.findings;
+    return {
+        report,
+        detail,
+        scores,
+        planes: secondary,
+        expandedPlanes,
+        scorecards,
+        security: partition(securityAll, config),
+        ...(report.perf && dimensions.has('perf')
+            ? { perf: partition(report.perf.findings, config) }
+            : {}),
+        has(section) {
+            if (!sections.has(section))
+                return false;
+            switch (section) {
+                case 'delta':
+                    return report.comparison != null;
+                case 'planes':
+                    return secondary.length > 0;
+                case 'scorecards':
+                    return scorecards.length > 0;
+                case 'role-access':
+                    return (report.roleAccess?.roles.length ?? 0) > 0;
+                case 'call-graph':
+                    return report.callGraph != null || report.callGraphDiff != null;
+                case 'findings':
+                    return detail !== 'summary';
+                default:
+                    return true;
+            }
+        }
+    };
+}
+function partition(findings, config) {
+    const exposed = findings.filter((f) => f.exposed !== false);
+    return {
+        exposed,
+        internal: config.exposedOnly ? [] : findings.filter((f) => f.exposed === false)
+    };
+}
+/** The config-file half of a view: `report.planes` / `report.dimensions`. */
+export function viewConfigFromReportConfig(config) {
+    if (!config)
+        return {};
+    return {
+        ...(config.planes ? { planes: config.planes } : {}),
+        ...(config.dimensions ? { dimensions: config.dimensions } : {})
+    };
+}

package/esm/rules/registry.d.ts

@@ -0,0 +1,66 @@
+import type { Dimension, Direction, Finding, Severity } from '../types';
+/**
+ * Static metadata for every rule safegres can emit. Severity here is the
+ * *default* — the resolved config (presets, rc files, CLI flags) can retune
+ * or disable any rule.
+ */
+export interface RuleMeta {
+    /** Stable rule code, e.g. `A1`, `P1b`. */
+    code: string;
+    category: Finding['category'];
+    defaultSeverity: Severity;
+    /**
+     * Leak vs deny vs directionless. `fail-closed` findings are hygiene
+     * concerns — the operation is *denied* at runtime — and contribute nothing
+     * to the score by default. `fail-open` findings are actual exposure.
+     */
+    direction: Direction;
+    /**
+     * Scoring axis. `security` rules drive the audit score; `perf` rules drive
+     * the optional performance score and are only collected when the perf
+     * dimension is enabled. Defaults to `security` when omitted.
+     */
+    dimension?: Dimension;
+    title: string;
+    /**
+     * Rules with `scope: 'policy-ast'` require parsing policy expressions.
+     * When every one of them is disabled the audit skips AST work entirely.
+     * `function-src` rules are the source-level convention linter (`C*`): they
+     * read function definitions rather than the catalog, and run their own pass.
+     */
+    scope: 'table' | 'policy-ast' | 'index' | 'stats' | 'function-src';
+    /**
+     * What the finding is *about*, which decides how its exposure is judged.
+     *
+     * A `relation` finding is exposed when its table is on the API surface. A
+     * `routine` finding is exposed when an untrusted role can *call the
+     * function* — schema USAGE plus EXECUTE — which is a different question and
+     * frequently a different answer: a definer function in a private schema is
+     * off the API surface and still one grant away from anonymous.
+     *
+     * Judging routine findings by relation reach is why a real audit reported
+     * every `C*` and `L19` finding as `exposed: false`, and therefore scored
+     * them at zero. Defaults to `relation`.
+     */
+    subject?: 'relation' | 'routine';
+    /**
+     * The finding's unit of repair, as a dotted path into the finding
+     * (`context.function`). The score counts *distinct* units, not findings,
+     * so a rule that emits one finding per (relation × function) pair moves the
+     * score by how much work it represents rather than by its own fan-out.
+     *
+     * L19 is the case that forced this: 568 findings over 166 functions, where
+     * promoting the rule one notch took the audit from A+ to F on multiplicity
+     * alone. Omitted means one finding is one unit.
+     */
+    dedupBy?: string;
+}
+/** The scoring axis a rule belongs to (`security` unless declared otherwise). */
+export declare function dimensionOf(meta: RuleMeta): Dimension;
+/** What a rule's findings are about (`relation` unless declared otherwise). */
+export declare function subjectOf(meta: RuleMeta): 'relation' | 'routine';
+export declare const RULES: RuleMeta[];
+export declare const RULES_BY_CODE: Map<string, RuleMeta>;
+export declare function isKnownRule(code: string): boolean;
+/** Expand a rule selector: an exact code (`P1b`) or a prefix wildcard (`P*`, `*`). */
+export declare function expandRuleSelector(selector: string): string[];