circle-ir 4.17.0 → 4.18.1

package/dist/remedy-class/match.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Remedy-class matcher: for every sink of a path that a version pair closed,
+ * report which row of a caller-supplied `safe-construct-table@0.1` the fixed
+ * code matches, or that none does, or that the matcher could not observe a
+ * row. Facts only: `class` and `remedyClass` are copied from the table, and
+ * nothing here judges whether a fix is adequate.
+ *
+ * Steps are looked for in the same declaration at the fix version as the
+ * baseline sink, on the IR circle-ir already produces: calls (receiver,
+ * receiver type, arguments, imports), DFG defs, uses and def-to-def chains,
+ * and the fix version's taint sources.
+ *
+ * Observed: `call` (type, methods, arg, ctor, static), `arg-is: tainted |
+ * untainted | from-allowlist`, `arg-literal-in`, `role: sink-replacement |
+ * binder | sanitizer | guard | normalizer`, `on`, `name` / `order`, `any`,
+ * `all`, `missing`, `sink-removed`. A guard needs branch facts
+ * (`deriveBranchFacts`) for the fix version's files. Not observed:
+ * `template` and `receiver-from` on a step. A row that needs a step it
+ * cannot observe **abstains**; it is never reported as unmatched.
+ *
+ * Pure: IR in, values out. Browser and Node compatible.
+ */
+import { type BranchFact } from '../path-set/branches.js';
+import type { TemplateFact } from '../path-set/templates.js';
+import { type OutputContext } from './output-context.js';
+import type { DeclRef, PathChange, PathSetDiff } from '../path-set/types.js';
+import type { StableIdFile } from '../stable-ids/types.js';
+import type { ProjectAnalysis } from '../types/index.js';
+import type { ConstructClass, LoadTableResult, TableProblem } from './table.js';
+/** How a call's type was matched to a table type, strongest first. */
+/** `template`: the sink hands its value to a view, and the label comes from the template construct that renders it. */
+export type TypeMatch = 'fqn' | 'import' | 'simple-name' | 'unresolved' | 'any' | 'template';
+export interface StepObservation {
+    /** Location of the step in the row, e.g. `/match/all/1`. */
+    path: string;
+    holds: boolean;
+    /** Where the step held (the first witness call), at the fix version. */
+    at?: {
+        file: string;
+        line: number;
+    };
+    typeMatch?: TypeMatch;
+}
+export interface MatchedRow {
+    id: string;
+    class: ConstructClass;
+    remedyClass: string;
+    context?: string;
+    steps: StepObservation[];
+}
+export type RemedyMatch = string | 'multiple' | 'unrecognized' | 'abstained';
+export type RemedyReason = 'sink-not-in-table' | 'no-row-holds' | 'step-outside-declaration' | 'declaration-not-found';
+export interface RemedySinkObservation {
+    /** `<path key>:sink` */
+    anchor: string;
+    pathKey: string;
+    /**
+     * `unchanged`: the path is still open in code at the fix version — observed
+     * under `scope: 'all'`, or when `templateChanged` (the fix is in the view).
+     */
+    change: Extract<PathChange, 'removed' | 'sanitized' | 'guarded' | 'unchanged'>;
+    /** The baseline sink. */
+    sink: {
+        /** Table sink id, or `unlisted` when no table sink has its call shape. */
+        tableSink: string;
+        tableSinkMatch?: TypeMatch;
+        /** `call`: the sink call itself; `receiver-def`: the call that made its receiver (a constructor). */
+        via?: 'call' | 'receiver-def' | 'template';
+        /**
+         * Only with `outputContext: true`: where in the HTML document the value lands
+         * at the fix version, read from the markup written before it; `unknown` when
+         * not read or not one context.
+         */
+        outputContext?: OutputContext;
+        file: string;
+        line: number;
+        decl: DeclRef;
+    };
+    /** The view this path hands to renders it differently at the fix version. */
+    templateChanged?: true;
+    match: RemedyMatch;
+    /** Copied from the table, and only when exactly one row matched. */
+    class?: ConstructClass;
+    /** Every matched row, in table order. */
+    rows: MatchedRow[];
+    /**
+     * Only with `outputContext: true`: rows whose match held but whose `context`
+     * is not the observed output context. They are not in `rows`.
+     */
+    contextExcludedRows?: {
+        id: string;
+        context: string;
+    }[];
+    /** Applicable rows the matcher could not observe, with why. */
+    abstainedRows: {
+        id: string;
+        reason: string;
+    }[];
+    reason?: RemedyReason;
+    /** Taint seeds used for `arg-is` at the fix version. */
+    taintSeeds: 'sources' | 'sources+parameters';
+    table: {
+        format: string;
+        cwe: number;
+        language: string;
+        version: string;
+        digest: string;
+    };
+}
+export interface RemedyClassResult {
+    table: RemedySinkObservation['table'];
+    /** Sorted by anchor. */
+    sinks: RemedySinkObservation[];
+}
+/** Thrown when the table was refused by the reader: no observation exists on a refused table. */
+export declare class TableRefused extends Error {
+    readonly problems: TableProblem[];
+    readonly digest: string;
+    constructor(digest: string, problems: TableProblem[]);
+}
+export interface RemedyClassOptions {
+    /** `ids@0.1` per file at each version, as given to `pathSetDiff`. */
+    stableIds?: {
+        before?: Record<string, StableIdFile>;
+        after?: Record<string, StableIdFile>;
+    };
+    /** Branch facts per file at the fix version (`deriveBranchFacts`); guard steps need them. */
+    branches?: {
+        after?: Record<string, BranchFact[]>;
+    };
+    /**
+     * Template facts per template file at each version (`deriveTemplateFacts`).
+     * With them, a sink that hands its value to a view is labelled by the table's
+     * template sinks and `template` steps are evaluated; without them those rows
+     * abstain (`template-not-read`).
+     */
+    templates?: {
+        before?: Record<string, TemplateFact[]>;
+        after?: Record<string, TemplateFact[]>;
+    };
+    /**
+     * `closed` (default): sinks of paths the fix closed (`removed`, `sanitized`,
+     * `guarded`), and of paths whose view now renders them differently
+     * (`templateChanged`). `all`: also sinks of paths still open at the fix version
+     * (`unchanged`), so a fix that left the path open can be described by the row
+     * it used (a weak construct). An open path's observation is a description,
+     * not a closed sink.
+     */
+    scope?: 'closed' | 'all';
+    /**
+     * Observe the output context at writer sinks (`sink.outputContext`) and hold
+     * a row with a `context` only where it is that context; rows that held in
+     * another context go to `contextExcludedRows`. Off by default: without it the
+     * result is exactly what it was.
+     */
+    outputContext?: boolean;
+}
+/**
+ * Observe, for every sink of a path `diff` reports `removed` or `sanitized`,
+ * which row of `table` the fix version matches.
+ *
+ * `table` is the reader's result; a refused table throws `TableRefused`.
+ */
+export declare function remedyClassOf(diff: PathSetDiff, before: ProjectAnalysis, after: ProjectAnalysis, loaded: LoadTableResult, options?: RemedyClassOptions): RemedyClassResult;
+//# sourceMappingURL=match.d.ts.map

package/dist/remedy-class/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/remedy-class/match.ts"],"names":[],"mappings":"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"}