:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import type { z } from 'zod'
import { wrapError } from '@/lib/errors'
import { PathCleaningRulesUpdateSchema } from '@/schema/tool-inputs'
import type { Context, ToolBase } from '@/tools/types'
const schema = PathCleaningRulesUpdateSchema
type Params = z.infer<typeof schema>
type Operation = Params['operations'][number]
/** A path cleaning rule as the LLM works with it — order is managed by this tool, not the caller. */
export type PathCleaningRule = { alias: string; regex: string }
/** A rule as stored on the project (`Team.path_cleaning_filters`), with an explicit order. */
export type StoredPathCleaningRule = PathCleaningRule & { order: number }
type SamplePreview = { path: string; before: string; after: string }
type Result = {
applied: boolean
message: string
changes: string[]
resulting_rules: StoredPathCleaningRule[]
sample_preview?: SamplePreview[]
settings_url: string
}
/**
* Coerce the raw `path_cleaning_filters` value (typed `unknown` in the API schema) into a
* clean list. Preserves the stored ARRAY order: the backend (`apply_path_cleaning` →
* `Team.path_cleaning_filter_models`) applies rules in array order and ignores the `order`
* field for sequencing, so re-sorting by `order` here could silently resequence untouched
* rules on save. The `order` field is carried through only as display metadata.
*/
export function normalizePathCleaningFilters(raw: unknown): StoredPathCleaningRule[] {
if (!Array.isArray(raw)) {
return []
}
return (
raw
.map((entry, index) => {
const rule = (entry ?? {}) as Record<string, unknown>
const alias = typeof rule.alias === 'string' ? rule.alias : ''
const regex = typeof rule.regex === 'string' ? rule.regex : ''
const order = typeof rule.order === 'number' ? rule.order : index
return { alias, regex, order }
})
// An empty `alias` is a valid rule (it deletes the matched text), so only drop
// entries with no `regex` to match on — keeping an existing empty-alias rule
// instead of silently deleting it on the next confirmed edit.
.filter((rule) => rule.regex !== '')
)
}
/** Reassign contiguous `order` values 0..n-1 so the caller never has to manage them. */
export function renumber(rules: PathCleaningRule[]): StoredPathCleaningRule[] {
return rules.map((rule, index) => ({ ...rule, order: index }))
}
function assertValidRegex(regex: string): void {
// The backend compiles these as re2; JS RegExp is only a best-effort typo check to fail
// fast on obviously-broken patterns (e.g. unbalanced parens). Strip a leading re2 inline
// flag group like `(?i)` first — it's valid re2 (and documented for path cleaning) but
// throws in JS. Patterns valid in re2 but not JS still save fine; the backend is the
// authority and rejects genuinely invalid ones on write.
const withoutLeadingInlineFlags = regex.replace(/^\(\?[imsUx]+\)/, '')
try {
new RegExp(withoutLeadingInlineFlags)
} catch (error) {
throw new Error(`Invalid regex "${regex}": ${(error as Error).message}`)
}
}
/**
* Apply the ordered operations to a copy of the current rules, returning the new list and a
* human-readable change log. Throws with an actionable message on any invalid operation
* (unknown target alias, bad regex, non-permutation reorder) so nothing is half-applied.
*/
export function applyOperations(
current: PathCleaningRule[],
operations: Operation[]
): { rules: PathCleaningRule[]; changes: string[] } {
const rules: PathCleaningRule[] = current.map((rule) => ({ ...rule }))
const changes: string[] = []
// Aliases are NOT guaranteed unique (two regexes can map to the same alias), so an
// alias-targeted op is only safe when exactly one rule carries it — otherwise we'd
// silently edit an arbitrary one. Reject the ambiguous case rather than guess.
const resolveSingle = (alias: string, verb: string): number => {
const matches = rules.reduce<number[]>((acc, rule, i) => {
if (rule.alias === alias) {
acc.push(i)
}
return acc
}, [])
if (matches.length === 0) {
throw new Error(
`Cannot ${verb}: no rule with alias "${alias}". Existing aliases: ${rules.map((rule) => rule.alias).join(', ')}`
)
}
if (matches.length > 1) {
throw new Error(
`Cannot ${verb}: alias "${alias}" matches ${matches.length} rules, so targeting it is ambiguous. Make the aliases distinct first, or edit the full list via project-settings-update.`
)
}
return matches[0]!
}
for (const op of operations) {
switch (op.action) {
case 'append': {
assertValidRegex(op.regex)
rules.push({ alias: op.alias, regex: op.regex })
changes.push(`Appended "${op.alias}" (${op.regex}) — runs last`)
break
}
case 'insert': {
assertValidRegex(op.regex)
const index = Math.min(op.index, rules.length)
rules.splice(index, 0, { alias: op.alias, regex: op.regex })
changes.push(`Inserted "${op.alias}" (${op.regex}) at position ${index}`)
break
}
case 'replace': {
const index = resolveSingle(op.target_alias, 'replace')
if (op.regex !== undefined) {
assertValidRegex(op.regex)
}
const previous = rules[index]!
const next = { alias: op.alias ?? previous.alias, regex: op.regex ?? previous.regex }
rules[index] = next
changes.push(`Replaced "${op.target_alias}" → alias "${next.alias}", regex ${next.regex}`)
break
}
case 'remove': {
const index = resolveSingle(op.target_alias, 'remove')
rules.splice(index, 1)
changes.push(`Removed "${op.target_alias}"`)
break
}
case 'reorder': {
// Group rules by alias so duplicate aliases are handled without loss: the
// permutation check is a true multiset comparison, and the rebuild consumes
// same-alias rules in their original relative order.
const groups = new Map<string, PathCleaningRule[]>()
for (const rule of rules) {
const list = groups.get(rule.alias)
if (list) {
list.push(rule)
} else {
groups.set(rule.alias, [rule])
}
}
const requestedCounts = new Map<string, number>()
for (const alias of op.ordered_aliases) {
requestedCounts.set(alias, (requestedCounts.get(alias) ?? 0) + 1)
}
const isPermutation =
op.ordered_aliases.length === rules.length &&
[...requestedCounts].every(([alias, count]) => (groups.get(alias)?.length ?? 0) === count)
if (!isPermutation) {
throw new Error(
`Cannot reorder: ordered_aliases must be exactly the current aliases, once each (including duplicates). Current: ${rules
.map((rule) => rule.alias)
.join(', ')}`
)
}
const queues = new Map([...groups].map(([alias, list]) => [alias, [...list]]))
const reordered = op.ordered_aliases.map((alias) => queues.get(alias)!.shift()!)
rules.splice(0, rules.length, ...reordered)
changes.push(`Reordered to: ${op.ordered_aliases.join(' → ')}`)
break
}
}
}
return { rules, changes }
}
/**
* Compile a re2 pattern into a JS RegExp for the approximate preview. Translates a leading
* re2 inline-flag group (e.g. `(?i)`) into JS flags so patterns accepted by the tool don't
* silently drop out of the preview. Returns null for patterns JS can't represent.
*/
function compileForPreview(regex: string): RegExp | null {
const match = regex.match(/^\(\?([imsUx]+)\)/)
const inlineFlags = match ? match[1]! : ''
const pattern = match ? regex.slice(match[0].length) : regex
// Map the re2 flags JS supports; ignore U/x (no JS equivalent, and rare in path cleaning).
let flags = 'g'
if (inlineFlags.includes('i')) {
flags += 'i'
}
if (inlineFlags.includes('m')) {
flags += 'm'
}
if (inlineFlags.includes('s')) {
flags += 's'
}
try {
return new RegExp(pattern, flags)
} catch {
// A rule using re2-only syntax may not compile under JS RegExp — skip it in the
// approximate preview rather than failing the whole call.
return null
}
}
/**
* Expand an alias against one regex match, so the preview substitutes capture groups the same way
* the real query does. The alias is re2 replacement syntax: `\0` is the whole match, `\1` to `\9`
* are capture groups, `\\` is a literal backslash, and everything else is literal.
*
* Expanding against the match here, rather than translating to a `$1`-style replacement string,
* keeps three re2 rules JavaScript would otherwise break: `$` stays literal, `\10` is group 1
* followed by `0` rather than group 10, and an unfilled group substitutes as empty.
*/
export function expandAlias(alias: string, groups: (string | undefined)[]): string {
let out = ''
for (let i = 0; i < alias.length; i++) {
const char = alias[i]
if (char !== '\\') {
out += char
continue
}
const next = alias[i + 1]
if (next === '\\') {
out += '\\'
i++
} else if (next !== undefined && next >= '0' && next <= '9') {
out += groups[Number(next)] ?? ''
i++
} else {
out += '\\'
}
}
return out
}
/** Chain a path through every rule in order, mirroring ClickHouse `replaceRegexpAll` per rule. */
function applyChain(path: string, rules: PathCleaningRule[]): string {
let out = path
for (const rule of rules) {
const re = compileForPreview(rule.regex)
if (re === null) {
continue
}
out = out.replace(re, (match: string, ...rest: unknown[]): string => {
// Replacer arguments run (match, p1…pN, offset, whole string, named groups?). A group
// the pattern didn't fill arrives as undefined, so the first number is the offset and
// marks where the capture values stop.
const offsetIndex = rest.findIndex((arg) => typeof arg === 'number')
const captures = (offsetIndex === -1 ? [] : rest.slice(0, offsetIndex)) as (string | undefined)[]
return expandAlias(rule.alias, [match, ...captures])
})
}
return out
}
function buildSamplePreview(
before: PathCleaningRule[],
after: PathCleaningRule[],
samplePaths: string[]
): SamplePreview[] {
return samplePaths.map((path) => ({
path,
before: applyChain(path, before),
after: applyChain(path, after),
}))
}
export const updatePathCleaningHandler: ToolBase<typeof schema, Result>['handler'] = async (
context: Context,
params: Params
) => {
const projectId = await context.stateManager.getProjectId()
const projectResult = await context.api.projects().get({ projectId })
if (!projectResult.success) {
throw wrapError(
`Failed to read current path cleaning rules: ${projectResult.error.message}`,
projectResult.error
)
}
const currentStored = normalizePathCleaningFilters(
(projectResult.data as { path_cleaning_filters?: unknown }).path_cleaning_filters
)
const currentRules: PathCleaningRule[] = currentStored.map(({ alias, regex }) => ({ alias, regex }))
const { rules, changes } = applyOperations(currentRules, params.operations)
const resultingRules = renumber(rules)
const samplePreview = params.sample_paths?.length
? buildSamplePreview(currentRules, rules, params.sample_paths)
: undefined
const settingsUrl = `${context.api.getProjectBaseUrl(projectId)}/settings/project#path-cleaning`
if (!params.confirm) {
return {
applied: false,
message: `Preview only — nothing saved. ${changes.length} change(s) would apply, leaving ${resultingRules.length} rule(s). Re-run with confirm:true to save.`,
changes,
resulting_rules: resultingRules,
sample_preview: samplePreview,
settings_url: settingsUrl,
}
}
const updateResult = await context.api.projects().updatePathCleaningFilters({
projectId,
filters: resultingRules,
})
if (!updateResult.success) {
throw wrapError(`Failed to save path cleaning rules: ${updateResult.error.message}`, updateResult.error)
}
const saved = normalizePathCleaningFilters(
(updateResult.data as { path_cleaning_filters?: unknown }).path_cleaning_filters
)
return {
applied: true,
message: `Saved ${saved.length} path cleaning rule(s). These apply globally wherever path cleaning is enabled and can change historical numbers.`,
changes,
resulting_rules: saved,
sample_preview: samplePreview,
settings_url: settingsUrl,
}
}
const tool = (): ToolBase<typeof schema, Result> => ({
name: 'path-cleaning-rules-update',
schema,
handler: updatePathCleaningHandler,
})
export default tool