@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-rules-explanation-why-this-package-exists.md

@@ -0,0 +1,43 @@
+# Why this package exists
+
+Firestore Security Rules is a small DSL that sits between every read and write your app makes. In Pyric we have two distinct needs around that DSL:
+
+1. A **data-plane** for the app code (`getDoc`, `setDoc`, `onSnapshot`, the modular Web SDK shape) that can be swapped between production Firestore and an in-process sandbox. This lives in `pyric/firestore`.
+
+2. **Tooling around the rules themselves**: parsing them, linting them, simulating them, testing them. This is `pyric/rules`.
+
+The split looks bureaucratic at first. Why not put both in one package? Two reasons:
+
+## The swap-in surface must stay minimal
+
+`pyric/firestore` is meant to be a drop-in replacement for `firebase/firestore`. Any host that imports it should see exactly the surface area that the upstream modular Web SDK exposes. No more, no less. Adding rules tooling to that import path would either pollute the swap-in surface (making the package look bigger than the production package it mirrors) or force consumers to import from non-standard sub-paths (which break tree-shaking and make TypeScript editor completion noisier than it needs to be).
+
+The same reasoning shapes `pyric/rules` internally: the public front door (`firestoreRules`, `rtdbRules`, `lint`, the assertion adapters) is small on purpose, but the engine underneath it (the parser, `parseToAST`; the linter, `lintFirestoreRules`; the validator, `validateFirestoreRules`; the simulator, `SimulateFirestoreRulesHandler`; seven value wrappers; and a sentinel expression engine) is bigger than the production data-plane surface. Bundling all of that onto `pyric/firestore`'s root would dominate the swap-in package, which is why it stays behind `pyric/rules/internal` instead.
+
+## The audiences are different
+
+Most apps using `pyric/firestore` will never call any function in `pyric/rules`. The data-plane is consumed by feature code: components, hooks, server actions. The rules tooling is consumed by tooling code: CI scripts, lint hooks, deploy pipelines, agent runtimes. These audiences have different bundle-size sensitivities (a feature-code package has to pay for every dependency in every consumer's bundle; a tooling package only loads in CI) and different release cadences (the data plane changes when the Firestore Web SDK does; the rules tooling changes when we discover a new agent failure mode).
+
+A clean split lets each side evolve at its own speed without burdening the other.
+
+## What ends up here
+
+Anything *about* rules:
+
+- The parser that turns rules text into an AST.
+- The linter that catches compilation limits, runtime-budget risks, and security anti-patterns.
+- The validator that emits the `SEC` / `SEM` / `QUA` / `STR` finding codes.
+- The modules resolver and stdlib.
+- The local simulator (used by the sandbox and by agents).
+- The Rules Test API client (used by CI and by agents).
+- The value wrappers that model `Timestamp`, `Path`, `Bytes`, etc.
+- The sentinel expression engine used by `pyric/sandbox` for declarative writes.
+- The tool factories that wrap all of the above as `@inbrowser/agent` tool handlers.
+
+## What stays out
+
+The Firestore Web SDK surface stays in `pyric/firestore`. Production shipping stays with `firebase-tools` / Console. Credentials for the Rules Test API live in `@pyric/cli/credentials/node`. The sandbox itself (the `LocalEnvironment` that holds documents and listeners) stays in `pyric/sandbox`. These packages form a loose hexagon: data plane, rules tooling, sandbox, and local CLI verify — none depends on a kitchen-sink control-plane package.
+
+## Tradeoffs
+
+The cost of the split is duplication risk: a value wrapper used by both the sandbox (for type coercion at read-time) and the rules simulator (for expression evaluation) has to live in exactly one of the two packages, and the other has to import it. We chose to put the wrappers here because the rules simulator is the source of truth for "what does Firestore think this value is". The sandbox imports `Timestamp`, `Vector`, `Reference` from `pyric/rules/internal` as a result, which creates a runtime cycle in workspace terms. The cycle is benign at build time (the two packages export non-overlapping symbols and TypeScript handles the resolution), but it does mean both have to be built in a specific order. We accepted that complexity over the alternatives: duplicating the wrapper classes, which would make `instanceof Timestamp` start lying, or shipping a third `pyric/firestore-values` package, which would split the wrappers from their evaluator and make the evaluation logic harder to reason about.

package/dist/serve/docs-ui/docs/pyric-rules-how-to-compare-rulesets-for-weakening/index.html

@@ -0,0 +1,55 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to compare two rulesets for weakening · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Compare rulesets</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-compare-two-rulesets-for-weakening">How to compare two rulesets for weakening</h1>
+<p>When you ship a rules change, the most dangerous mistake is silently removing a security predicate to make a failing test pass. Here’s how to catch that before it deploys.</p>
+<p><code>RULES_WEAKENED</code> needs the previously-deployed source to diff against. The public <code>lint(source)</code> and <code>firestoreRules(source).lint()</code> take no options, so this check is reached through the engine-internal <code>lintFirestoreRules</code>, imported from <code>pyric/rules/internal</code>: not part of the public contract, but the mechanism this guide relies on.</p>
+<h2 id="lint-with-the-previous-source">Lint with the previous source</h2>
+<p>Pass the previously-deployed source as <code>options.previousSource</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">lintFirestoreRules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> lintFirestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">newSource</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">previousSource</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">oldSource</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> weakened</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">warnings</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">w</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">rule</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'RULES_WEAKENED'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> w</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> weakened</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">  console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`[WEAKENED] </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The linter walks both rulesets, normalises every match path, and diffs the predicates conjunct-by-conjunct on each allow rule. Every conjunct that existed in <code>previousSource</code> but is missing from the current source produces one <code>RULES_WEAKENED</code> warning.</p>
+<h2 id="what-it-detects">What it detects</h2>
+<p>Three weakening shapes are surfaced:</p>
+<ul>
+<li><strong>Removed match block</strong>: <code>match /admin/{x} { allow … }</code> existed before; it’s gone now. Only reported if the previous block had <code>allow</code> rules. Empty parent shells disappearing is silent.</li>
+<li><strong>Removed allow rule</strong>: same match path, but <code>allow update: …</code> was deleted.</li>
+<li><strong>Removed conjunct</strong>: same match path and same allow op-set, but a conjunct was dropped. For example, <code>auth.uid == ownerId &#x26;&#x26; status == 'open'</code> becoming just <code>auth.uid == ownerId</code>.</li>
+</ul>
+<h2 id="what-it-does-not-detect">What it does not detect</h2>
+<p>By design:</p>
+<ul>
+<li><strong>Added conjuncts</strong>: refinement is fine.</li>
+<li><strong>Changed conjuncts</strong>: replacing <code>status == 'open'</code> with <code>status in ['open', 'pending']</code> is treated as a removal (the old conjunct is gone) plus an addition (silent). The removal warning is the actionable signal.</li>
+<li><strong><code>||</code> rearrangements inside a conjunct</strong>: the linter doesn’t descend into <code>||</code> sub-trees, because splitting an OR would change semantics. The entire OR is one conjunct.</li>
+<li><strong>Function-body changes</strong>: the linter compares the predicate that appears in the <code>allow</code> statement. If you weaken a helper function used by that predicate, the predicate string is unchanged and the warning does not fire. Run the simulator to catch behavioural regressions of that shape.</li>
+</ul>
+<h2 id="wire-it-into-ci">Wire it into CI</h2>
+<p>Pull the live ruleset before linting the candidate:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">firebase</span><span style="color:#98C379"> firestore:rules:get</span><span style="color:#ABB2BF"> > </span><span style="color:#98C379">previous.rules</span></span></code></pre>
+<p>Then in your check script:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">readFileSync</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'node:fs'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">lintFirestoreRules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> previousSource</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> readFileSync</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'previous.rules'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'utf-8'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> newSource</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> readFileSync</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'firestore.rules'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'utf-8'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> lintFirestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">newSource</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">previousSource</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> weakened</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">warnings</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">w</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">rule</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'RULES_WEAKENED'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">weakened</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">length</span><span style="color:#56B6C2"> ></span><span style="color:#D19A66"> 0</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">  console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`Refusing to deploy: </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">weakened</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">length</span><span style="color:#C678DD">}</span><span style="color:#98C379"> predicate(s) removed.`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> w</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> weakened</span><span style="color:#ABB2BF">) </span><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`  · </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">  process</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">exit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">1</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>RULES_WEAKENED</code> is a <code>warning</code>, not an <code>error</code>. The deploy gate stays under your control: require human ack, or treat it as a hard block as above.</p>
+<h2 id="when-the-previous-source-is-malformed">When the previous source is malformed</h2>
+<p>If <code>previousSource</code> fails to parse, the linter silently skips the diff and the rest of the lint continues. A broken prior should not block a clean candidate.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For why this check exists, see <a href="../pyric-rules-explanation-agent-failure-modes/#silently-removing-predicates">Agent failure modes</a>.</li>
+<li>For the conjunct-extraction algorithm, see <a href="../pyric-rules-reference-lint-rules/#rules_weakened"><code>RULES_WEAKENED</code> in the lint rules reference</a>.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#lint-with-the-previous-source">Lint with the previous source</a> </li><li data-depth="2"> <a href="#what-it-detects">What it detects</a> </li><li data-depth="2"> <a href="#what-it-does-not-detect">What it does not detect</a> </li><li data-depth="2"> <a href="#wire-it-into-ci">Wire it into CI</a> </li><li data-depth="2"> <a href="#when-the-previous-source-is-malformed">When the previous source is malformed</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look next</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-rules-how-to-compare-rulesets-for-weakening.md

@@ -0,0 +1,77 @@
+# How to compare two rulesets for weakening
+
+When you ship a rules change, the most dangerous mistake is silently removing a security predicate to make a failing test pass. Here's how to catch that before it deploys.
+
+`RULES_WEAKENED` needs the previously-deployed source to diff against. The public `lint(source)` and `firestoreRules(source).lint()` take no options, so this check is reached through the engine-internal `lintFirestoreRules`, imported from `pyric/rules/internal`: not part of the public contract, but the mechanism this guide relies on.
+
+## Lint with the previous source
+
+Pass the previously-deployed source as `options.previousSource`:
+
+```ts
+import { lintFirestoreRules } from 'pyric/rules/internal';
+
+const result = lintFirestoreRules(newSource, { previousSource: oldSource });
+
+const weakened = result.warnings.filter((w) => w.rule === 'RULES_WEAKENED');
+for (const w of weakened) {
+  console.log(`[WEAKENED] ${w.message}`);
+}
+```
+
+The linter walks both rulesets, normalises every match path, and diffs the predicates conjunct-by-conjunct on each allow rule. Every conjunct that existed in `previousSource` but is missing from the current source produces one `RULES_WEAKENED` warning.
+
+## What it detects
+
+Three weakening shapes are surfaced:
+
+- **Removed match block**: `match /admin/{x} { allow … }` existed before; it's gone now. Only reported if the previous block had `allow` rules. Empty parent shells disappearing is silent.
+- **Removed allow rule**: same match path, but `allow update: …` was deleted.
+- **Removed conjunct**: same match path and same allow op-set, but a conjunct was dropped. For example, `auth.uid == ownerId && status == 'open'` becoming just `auth.uid == ownerId`.
+
+## What it does not detect
+
+By design:
+
+- **Added conjuncts**: refinement is fine.
+- **Changed conjuncts**: replacing `status == 'open'` with `status in ['open', 'pending']` is treated as a removal (the old conjunct is gone) plus an addition (silent). The removal warning is the actionable signal.
+- **`||` rearrangements inside a conjunct**: the linter doesn't descend into `||` sub-trees, because splitting an OR would change semantics. The entire OR is one conjunct.
+- **Function-body changes**: the linter compares the predicate that appears in the `allow` statement. If you weaken a helper function used by that predicate, the predicate string is unchanged and the warning does not fire. Run the simulator to catch behavioural regressions of that shape.
+
+## Wire it into CI
+
+Pull the live ruleset before linting the candidate:
+
+```bash
+firebase firestore:rules:get > previous.rules
+```
+
+Then in your check script:
+
+```ts
+import { readFileSync } from 'node:fs';
+import { lintFirestoreRules } from 'pyric/rules/internal';
+
+const previousSource = readFileSync('previous.rules', 'utf-8');
+const newSource = readFileSync('firestore.rules', 'utf-8');
+
+const result = lintFirestoreRules(newSource, { previousSource });
+const weakened = result.warnings.filter((w) => w.rule === 'RULES_WEAKENED');
+
+if (weakened.length > 0) {
+  console.error(`Refusing to deploy: ${weakened.length} predicate(s) removed.`);
+  for (const w of weakened) console.error(`  · ${w.message}`);
+  process.exit(1);
+}
+```
+
+`RULES_WEAKENED` is a `warning`, not an `error`. The deploy gate stays under your control: require human ack, or treat it as a hard block as above.
+
+## When the previous source is malformed
+
+If `previousSource` fails to parse, the linter silently skips the diff and the rest of the lint continues. A broken prior should not block a clean candidate.
+
+## Where to look next
+
+- For why this check exists, see [Agent failure modes](../pyric-rules-explanation-agent-failure-modes/#silently-removing-predicates).
+- For the conjunct-extraction algorithm, see [`RULES_WEAKENED` in the lint rules reference](../pyric-rules-reference-lint-rules/#rules_weakened).

package/dist/serve/docs-ui/docs/pyric-rules-how-to-inspect-rules-via-the-ast/index.html

@@ -0,0 +1,90 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to inspect rules through the AST · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Inspect rules via the AST</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-inspect-rules-through-the-ast">How to inspect rules through the AST</h1>
+<p>Parse rules into a typed AST and walk the tree for custom analysis: bespoke lint rules, generated documentation, or structural facts the built-in linter doesn’t surface.</p>
+<p>The parser (<code>parseToAST</code>, <code>parseToASTOrError</code>, <code>parseFunctions</code>), the AST types, and <code>validateFirestoreRules</code> are engine-internal, imported from <code>pyric/rules/internal</code>. That surface isn’t covered by the public <code>pyric/rules</code> contract and may change without notice. For the AST alone, <code>firestoreRules(source).toJSON()</code> on the public front door returns the same tree without touching the parser directly; reach for the internal imports below when you need to parse arbitrary fragments or run the validator standalone.</p>
+<h2 id="parse-to-ast">Parse to AST</h2>
+<p><code>parseToASTOrError</code> returns either the AST or a structured failure. Use it when you want a diagnostic on parse failure:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">parseToASTOrError</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> parseToASTOrError</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">ok</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">  console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`Line </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">error</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">line</span><span style="color:#C678DD">}</span><span style="color:#98C379">, col </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">error</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">column</span><span style="color:#C678DD">}</span><span style="color:#98C379">: </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">error</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">  process</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">exit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">1</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> ast</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">ast</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>When <code>null</code> is sufficient signal:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">parseToAST</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> ast</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> parseToAST</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E06C75">ast</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">throw</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> Error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'parse failed'</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<h2 id="walk-match-blocks">Walk match blocks</h2>
+<p><code>FirestoreRules.service.match</code> is the root match (always <code>/databases/{db}/documents</code>). Walk its <code>children</code> recursively to enumerate every nested match block:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#C678DD"> type</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">MatchBlock</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#61AFEF"> walk</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">block</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">MatchBlock</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">parentPath</span><span style="color:#56B6C2"> =</span><span style="color:#98C379"> ''</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">void</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> path</span><span style="color:#56B6C2"> =</span><span style="color:#E06C75"> parentPath</span><span style="color:#56B6C2"> +</span><span style="color:#E5C07B"> block</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">path</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">raw</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> allow</span><span style="color:#C678DD"> of</span><span style="color:#E5C07B"> block</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">allows</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">    console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`</span><span style="color:#C678DD">${</span><span style="color:#E06C75">path</span><span style="color:#C678DD">}</span><span style="color:#98C379">  allow </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">allow</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">operations</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">join</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">','</span><span style="color:#ABB2BF">)</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#C678DD">  for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> child</span><span style="color:#C678DD"> of</span><span style="color:#E5C07B"> block</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">children</span><span style="color:#ABB2BF">) </span><span style="color:#61AFEF">walk</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">child</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">walk</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">ast</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">service</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">match</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<h2 id="inspect-path-patterns">Inspect path patterns</h2>
+<p>A <code>PathPattern</code> is <code>{ raw: string, segments: PathSegment[] }</code>. Each segment is one of three shapes:</p>
+<ul>
+<li><code>{ type: 'literal', value: 'users' }</code></li>
+<li><code>{ type: 'wildcard', name: 'uid' }</code>: for <code>{uid}</code></li>
+<li><code>{ type: 'recursive', name: 'document' }</code>: for <code>{document=**}</code></li>
+</ul>
+<p>Branch on <code>seg.type</code> rather than parsing <code>raw</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> seg</span><span style="color:#C678DD"> of</span><span style="color:#E5C07B"> block</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">path</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">segments</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">seg</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">type</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'literal'</span><span style="color:#ABB2BF">) </span><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'static:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">seg</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">value</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  else</span><span style="color:#C678DD"> if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">seg</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">type</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'wildcard'</span><span style="color:#ABB2BF">) </span><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'wildcard:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">seg</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">name</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  else</span><span style="color:#E5C07B"> console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'recursive:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">seg</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">name</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="walk-expressions">Walk expressions</h2>
+<p><code>Expression</code> is a discriminated union. The discriminator is <code>type</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#C678DD"> type</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">Expression</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#61AFEF"> walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">expr</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Expression</span><span style="color:#ABB2BF">, </span><span style="color:#61AFEF">visit</span><span style="color:#ABB2BF">: (</span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Expression</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> void</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">void</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#61AFEF">  visit</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">expr</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  switch</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">type</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'binaryOp'</span><span style="color:#ABB2BF">:       </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">left</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">right</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'unaryOp'</span><span style="color:#ABB2BF">:        </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">operand</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'methodCall'</span><span style="color:#ABB2BF">:     </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">object</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">args</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">forEach</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">a</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#61AFEF"> walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">a</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">)); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'memberAccess'</span><span style="color:#ABB2BF">:   </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">object</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'bracketAccess'</span><span style="color:#ABB2BF">:  </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">object</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">index</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'ternary'</span><span style="color:#ABB2BF">:        </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">condition</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">consequent</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">alternate</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'inExpr'</span><span style="color:#ABB2BF">:         </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">element</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">collection</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'isExpr'</span><span style="color:#ABB2BF">:         </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">value</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'listLiteral'</span><span style="color:#ABB2BF">:    </span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">elements</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">forEach</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#61AFEF"> walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">e</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">)); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'mapLiteral'</span><span style="color:#ABB2BF">:     </span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">entries</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">forEach</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">en</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> { </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">en</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">key</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); </span><span style="color:#61AFEF">walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">en</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">value</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">); }); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'functionCall'</span><span style="color:#ABB2BF">:   </span><span style="color:#E5C07B">expr</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">args</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">forEach</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">a</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#61AFEF"> walkExpr</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">a</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">visit</span><span style="color:#ABB2BF">)); </span><span style="color:#C678DD">break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">    // 'literal', 'identifier', 'pathLiteral' — leaf nodes</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>See <a href="../pyric-rules-reference-ast/">AST reference</a> for every node shape.</p>
+<h2 id="run-the-validator">Run the validator</h2>
+<p>If your custom checks overlap with security or quality concerns, run the bundled validator and union the findings into your output:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">validateFirestoreRules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> findings</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> validateFirestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">ast</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> f</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> findings</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">  console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`[</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">f</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">severity</span><span style="color:#C678DD">}</span><span style="color:#98C379">] </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">f</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">code</span><span style="color:#C678DD">}</span><span style="color:#98C379"> at </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">f</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</span><span style="color:#C678DD">}</span><span style="color:#98C379">: </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">f</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The validator covers public-write detection, default-deny audit, duplicate function names, overlapping paths, and other structural issues. See <a href="../pyric-rules-reference-validator-findings/">Validator findings reference</a> for the full code list.</p>
+<h2 id="parse-just-a-function-body">Parse just a function body</h2>
+<p>Useful for editor pop-ups or function-level lint hooks:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">parseFunctions</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> fns</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> parseFunctions</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`</span></span>
+<span class="line"><span style="color:#98C379">  function isAdmin() { return request.auth.token.role == 'admin'; }</span></span>
+<span class="line"><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">fns</span><span style="color:#ABB2BF">) </span><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">fns</span><span style="color:#ABB2BF">[</span><span style="color:#D19A66">0</span><span style="color:#ABB2BF">].</span><span style="color:#E06C75">name</span><span style="color:#ABB2BF">); </span><span style="color:#7F848E;font-style:italic">// 'isAdmin'</span></span></code></pre>
+<p><code>parseFunctions</code> wraps the input in a minimal <code>rules_version='2'</code> shell and returns only the parsed <code>FunctionDef[]</code>, or <code>null</code> if parsing failed.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For every AST node shape, see <a href="../pyric-rules-reference-ast/">AST reference</a>.</li>
+<li>For the validator codes, see <a href="../pyric-rules-reference-validator-findings/">Validator findings reference</a>.</li>
+<li>For <code>parseToASTOrError</code>’s <code>ParseError</code> shape, see <a href="../pyric-rules-reference-errors/#parseerror">Errors reference</a>.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#parse-to-ast">Parse to AST</a> </li><li data-depth="2"> <a href="#walk-match-blocks">Walk match blocks</a> </li><li data-depth="2"> <a href="#inspect-path-patterns">Inspect path patterns</a> </li><li data-depth="2"> <a href="#walk-expressions">Walk expressions</a> </li><li data-depth="2"> <a href="#run-the-validator">Run the validator</a> </li><li data-depth="2"> <a href="#parse-just-a-function-body">Parse just a function body</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look next</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>