Querying Code and Metadata with deduce

aer deduce answers questions about how the Apex code and metadata in a source tree relate to each other: which methods nothing calls, which custom fields nothing references, which methods a trigger reaches, which test methods touch records without System.runAs. It loads the source, records each relationship as a fact, evaluates a Mangle (Datalog) program you write over those facts, and prints the facts the program derives.

deduce is the declarative counterpart to the development server’s Explorer. In the Explorer you browse the relationships between components interactively. With deduce you write rules that describe what to find, and aer returns every match in the source tree.

A first program

This program lists the fields that custom report types expose but no report uses:

aer deduce force-app -e '
  used_by_report(F) :- type(R, "Report"), usesField(R, F).
  unused(RT, F) :- type(RT, "ReportType"), usesField(RT, F), !used_by_report(F).'

Each line is a rule. used_by_report(F) holds for every field F that some report R uses. unused(RT, F) holds for every field a report type exposes for which used_by_report does not hold. aer prints each predicate the program defines, headed by its number of facts. On a small sample project:

# used_by_report(X0): 10 facts
used_by_report("Field:Project_Task__c.Assignee__c")
used_by_report("Field:Project_Task__c.Estimate_Hours__c")
...
# unused(X0,X1): 0 facts

Running programs

# Program text on the command line
aer deduce force-app -e 'program'

# Program in a file, or on standard input with -p -
aer deduce force-app -p unused-fields.mg
aer deduce force-app -p - < unused-fields.mg

# Print only some predicates
aer deduce force-app -p unused-fields.mg --query unused

# Tab-separated output, one fact per line, no header
aer deduce force-app -p unused-fields.mg --query 'unused(RT, F)' --format tsv
  • Source. Pass the same source directories you pass to aer test. --package and --package-dir load .pkg files, and source loaded with a namespace (path@ns or --default-namespace) contributes its objects and fields under that namespace.
  • --query. Without it, every predicate the program defines is printed. With it, only the named predicates are printed. --query can be repeated, and it can name a predicate the program does not define, such as --query triggersOn, to print facts aer loaded.
  • Fixing an argument. A query written as an atom with a constant prints only the matching facts: --query 'field_use(User, How, "Field:Account.Rating")' lists the uses of one field.
  • Errors. A program that does not parse, or that names a predicate that does not exist, is reported with its position or clause, and the command exits with status 1.

The facts

Every component is a string made of its type and its API name:

"ApexClass:InvoiceService"
"ApexMethod:InvoiceService.post"
"ApexTrigger:AccountTrigger"
"SObject:Account"
"Field:Opportunity.Amount"
"Report:Open_Opportunities"

Standard library classes and methods are components too ("ApexMethod:Map.values"), so a program can follow calls into them.

A relationship between two components is a fact named after the relationship:

calls("ApexMethod:InvoiceService.post", "ApexMethod:Ledger.record")
usesField("Report:Open_Opportunities", "Field:Opportunity.Amount")
triggersOn("ApexTrigger:AccountTrigger", "SObject:Account")

These predicates describe each component:

PredicateHolds
type(Component, Type)The component’s type, such as "ApexMethod", "TestMethod", "CustomField", or "Report"
isa(Component, Type)The component’s type is Type or a subtype of it, so isa(F, "Field") includes custom fields
name(Component, Name)The component without its type, for every component, such as "Map.values"
apiName(Component, Name)The API name of a component defined in the source or schema; standard library classes and methods have none
label(Component, Label)The component’s label
namespace(Component, Namespace)The component’s namespace, when it has one
modifier(Method, Modifier)Each keyword modifier of an Apex method, in lowercase, such as "global" or "static"
apiVersion(Component, Version)The API version of a class or trigger
subClassOf(Type, Supertype)The type hierarchy that isa follows
triple(Subject, Relationship, Object)Every fact in one predicate

Run aer deduce force-app --predicates to list every predicate with its number of facts for your source. Print a predicate’s facts with --query <name> to see what it holds. The predicates cover these areas:

  • Apex structure: hasMethod, containsMember, extends, implements, implementsMethod, overrides, declaresLocal, readsLocal, readsApexField, writesApexField, throws, comment
  • Calls: calls, callsFuture, instantiates, enqueues, startsBatch, schedules, makesCallout, runsFlow
  • Records: queries, creates, updates, deletes, upserts, undeletes, merges, readsSObjectField, writesSObjectField, accessesSObject, usesRunAs
  • Objects and automation: hasField, hasTrigger, triggersOn, hasValidationRule, hasWorkflowRule, updatesField, rollsUp, referencesField, exposesField
  • Configuration: usesCustomMetadata, usesCustomSetting, usesLabel, usesNamedCredential, usesStaticResource
  • Reports: usesField, usesReportType, reportTypeForObject, joinsObject
  • User interface: usesComponent, hasController, controllerFor, controllerExtensionFor, callsApex, usesWire, importsModule, hasTab, tabForObject, tabForPage, tabForComponent, hasActionOverride
  • Events and messages: publishesEvent, subscribesToEvent, firesEvent, handlesEvent, sendsMessage, receivesMessage

readsSObjectField and writesSObjectField cover field expressions on any SObject value (variables, method results, list and map elements, casts), the fields and relationship paths of inline SOQL, and the name=value arguments of SObject constructors. For a flow they cover the fields its record elements filter, query, sort, and set, its trigger’s entry criteria, and the fields its conditions, assignments, inputs, formulas, and text templates reach through resource references such as $Record.Name. A page layout usesField the fields its sections and mini layout place.

The facts come from the source as written. Dynamic SOQL and SObject.get or SObject.put with a field name string produce no facts, so a program that looks for unused fields lists a field that only those use. In the same way, a class created only with Type.forName has no fact for the call to its constructor, and a method called only from outside the source, such as the HTTP method of an @RestResource class or a global method called by another package, has no caller in the facts. Check each result of a program that looks for unused components before deleting anything.

Writing programs

Mangle programs are made of rules of the form head :- body., read as “head holds when every item of the body holds.”

  • Variables start with an uppercase letter. _ matches any value and is not reused.

  • Constants are strings in double quotes: type(M, "TestMethod").

  • Negation. !p(X) holds when p(X) has no fact. Bind the negated item’s variables in an earlier item of the body, as F is bound by usesField(RT, F) in unused above.

  • Several rules for one predicate combine as “or”:

    data_access(Code) :- queries(Code, _).
    data_access(Code) :- creates(Code, _).
  • Recursion. A rule can use its own predicate, which follows chains of any length:

    reaches(T, M) :- type(T, "ApexTrigger"), calls(T, M).
    reaches(T, M) :- reaches(T, Caller), calls(Caller, M).
  • Functions in the body filter on strings: name(M, N), :string:starts_with(N, "System.Database.").

  • Aggregation groups and counts with a transform after |>:

    reports_per_type(ReportType, Count) :-
        usesReportType(_, ReportType)
        |> do fn:group_by(ReportType), let Count = fn:count().
  • Comments start with #.

See the Mangle documentation for the full language.

Example programs

aer deduce --help-examples prints these programs, each with the command that runs it and an explanation of what it counts and what it leaves out:

  1. Fields that custom report types expose but no report uses
  2. Test methods that query or perform DML, directly or through the methods they call, without System.runAs
  3. Apex methods that nothing calls, counting calls from Apex, Lightning components, and Visualforce pages, and methods the platform calls through an interface or override
  4. Custom fields that nothing references in Apex, flows, layouts, reports, report types, Lightning pages, formulas, validation rules, rollup summaries, or workflow field updates
  5. Everything that reads, writes, or uses one field
  6. Methods a trigger reaches through calls, including overriding and implementing methods of the classes the trigger creates instances of
  7. The number of reports built on each report type

Save one to a file and adapt it to your project.

Using deduce in CI

A program can check a rule your team follows. aer deduce exits with status 0 whether or not the program derives facts, so check the output. With --query and --format tsv, the output is one line per fact and nothing else:

violations=$(aer deduce force-app -p checks/test-run-as.mg \
	--query 'test_method_without_run_as(Method)' --format tsv)
if [ -n "$violations" ]; then
	echo "Test methods that touch records without System.runAs:"
	echo "$violations"
	exit 1
fi

In the development server

aer server serves the same programs at /dev/deduce, listed under Inspect on the landing page. Enter a program and, optionally, queries one per line, then press Run or Ctrl+Enter. Each query’s facts are shown in a table with one column per argument, or as Mangle atoms, up to 5,000 facts per query with the total count above the table. The example programs are listed with a Load button, which puts the program and its queries in the editor, and a Run button. The sidebar lists the predicates with their fact counts; clicking one lists its facts.

The facts are generated from the server’s loaded metadata on every run, so they include metadata deployed since the server started. See Development Server.