@pyric/ui/rules

Interfaces

Denial

One denied Firestore request, enriched with the simulator trace.

The live denial event carries only debugMessages; the rich trace (evaluation / pathResolution) is produced by re-running the simulator (tracing always on) against the captured request. Build one with useDenialTrace(request, rulesSource) then spread the captured request fields alongside.

Properties

DenialInspectorProps

Properties

Methods

onRerunAs()?

optional onRerunAs(uid: string): void;

Re-run the request under { mode: 'as', uid }.

Parameters

Returns

void

onSelectCluster()?

optional onSelectCluster(d: Denial): void;

A cluster sibling was selected.

Parameters

Returns

void

onTestEditedRule()?

optional onTestEditedRule(): void;

Re-run against an edited ruleset (a branch).

Returns

void

DenialRequest

The captured request a host re-runs through the simulator to produce a Denial. A subset of the simulator’s TestCase — no expectation / description (those are test-runner concerns); the host already knows the request was denied.

Properties

DenialTrace

Properties

RuleLine

Properties

ScopeVar

The set of scope variable roots whose deciding values appear in the trace — request.auth, request.resource.data, resource.data. Used to underline the values the rule actually read.

Properties

Type Aliases

DenialLens

type DenialLens =
  | "admin"
  | {
  as: string;
}
  | "app-session";

The lens a request was issued under, mirroring the Studio’s identity model:

• 'admin' — the admin handle (bypasses rules in production, shown here for provenance only)
• { as: uid } — acting as a specific signed-in user
• 'app-session' — the ambient app session (whoever is signed in in the running preview)

LineVerdict

type LineVerdict = "deny" | "allow" | "skip";

Per-line verdict for the rule-source view. deny is the deciding allow line; skip is an allow line whose operations don’t include the request method (“not checked”); allow is any other allow line. Non-allow lines (match/braces/comments) get no verdict.

Functions

decidingEvaluation()

function decidingEvaluation(evaluation: RuleEvaluation[]): RuleEvaluation;

The allow rule that decided the denial: the last rule actually evaluated (DENY/ERROR). Under OR semantics the simulator stops at the first ALLOW; on a denial no rule allowed, so the deciding rule is the last evaluated one — the closest miss the user should reason about.

Parameters

Returns

RuleEvaluation

DenialInspector()

function DenialInspector(__namedParameters: DenialInspectorProps): Element;

Headless inspector for a single denied Firestore request. Renders, per the denial-inspector-spec:

• the plain-language reason (data-pyric-denial-reason)
• the rule source, line-marked (data-pyric-rule-source, per-line data-pyric-line-verdict="deny|allow|skip")
• the expression step-through (data-pyric-trace + per-node hooks)
• data in scope (data-pyric-scope, -scope-var, -scope-hit)
• the re-run / verify loop (data-pyric-rerun)
• the cluster of sibling denials (data-pyric-denial-cluster)
• path resolution for no-match denials (data-pyric-path-resolution)

Zero styling — every visual decision is a consumer’s via the data-pyric-* hooks. mocks/c-debug.html is the CSS spec.

Parameters

Returns

Element

denialReason()

function denialReason(
   evaluation: RuleEvaluation[],
   method: "delete" | "get" | "list" | "create" | "update",
   path: string): string;

A plain-language reason for the denial, derived from the deciding RuleEvaluation. Falls back to a no-match explanation when no allow rule was evaluated.

Parameters

Returns

string

formatValue()

function formatValue(value: unknown): string;

Render a trace value the way the mock shows it: JSON-ish, quoted strings, false/true/null bare.

Parameters

Returns

string

markRuleLines()

function markRuleLines(
   rulesSource: string,
   evaluation: RuleEvaluation[],
   method: "delete" | "get" | "list" | "create" | "update"): RuleLine[];

Split the rules source into numbered lines and mark each allow line with a verdict per the spec:

• the deciding rule’s line → deny
• an allow line whose operations don’t include the method → skip
• any other allow line → allow

Verdicts are matched to source lines via RuleEvaluation.line (1-indexed allow keyword). Lines without a matching evaluation entry get no verdict.

Parameters

Returns

RuleLine[]

methodOperations()

function methodOperations(method: "delete" | "get" | "list" | "create" | "update"): string[];

Operations a request method satisfies — update matches update and write, etc. Mirrors the simulator’s methodToOperations.

Parameters

Returns

string[]

scopeVars()

function scopeVars(denial: Denial): ScopeVar[];

Build the “data in scope” rows for a denial: request.auth, request.resource.data, and resource.data — each present only when the denial carries that payload. hits marks the leaf keys the deciding rule actually read.

Parameters

Returns

ScopeVar[]

traceDepth()

function traceDepth(entries: ExprTraceEntry[], index: number): number;

Depth of a trace node from its parent chain (0 for roots).

Parameters

Returns

number

useDenialTrace()

function useDenialTrace(request: DenialRequest, rulesSource: string): DenialTrace;

Re-run a captured (denied) Firestore request through the local rules simulator — tracing is always on there — and return the structured trace a DenialInspector renders.

Memoized on (request, rulesSource); the simulator is pure and in-process, so this is cheap to call on every render. A host produces a Denial by spreading the request fields alongside the result:

const { evaluation, pathResolution } = useDenialTrace(req, rules);
const denial: Denial = { ...req, decision: 'DENY', rulesSource: rules,
                         at, evaluation, pathResolution };

Parameters

Returns

DenialTrace

References

ExprTraceEntry

Re-exports ExprTraceEntry

FirestoreMethod

Re-exports FirestoreMethod

PathResolutionEntry

Re-exports PathResolutionEntry

PathResolutionTrace

Re-exports PathResolutionTrace

RuleEvaluation

Re-exports RuleEvaluation