npm - @salesforce/afv-skills - Versions diffs - 1.22.0 → 1.24.0 - Mend

@salesforce/afv-skills 1.22.0 → 1.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1675) hide show

package/skills/querying-soql/SKILL.md DELETED Viewed

@@ -1,142 +0,0 @@
----
-name: querying-soql
-description: "SOQL query generation, optimization, and analysis with 100-point scoring. Use this skill when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance or safety improvements for Salesforce queries. TRIGGER when: user writes, optimizes, or debugs SOQL/SOSL queries, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER when: bulk data operations (use handling-sf-data), Apex DML logic (use generating-apex), or report/dashboard queries."
-metadata:
-  version: "1.1"
----
-# querying-soql: Salesforce SOQL Query Expert
-Use this skill when the user needs **SOQL/SOSL authoring or optimization**: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance/safety improvements for Salesforce queries.
-## When This Skill Owns the Task
-Use `querying-soql` when the work involves:
-- `.soql` files
-- query generation from natural language
-- relationship queries and aggregate queries
-- query optimization and selectivity analysis
-- SOQL/SOSL syntax and governor-aware design
-Delegate elsewhere when the user is:
-- performing bulk data operations → [handling-sf-data](../handling-sf-data/SKILL.md)
-- embedding query logic inside broader Apex implementation → [generating-apex](../generating-apex/SKILL.md)
-- debugging via logs rather than query shape → [debugging-apex-logs](../debugging-apex-logs/SKILL.md)
----
-## Required Context to Gather First
-Ask for or infer:
-- target object(s)
-- fields needed
-- filter criteria
-- sort / limit requirements
-- whether the query is for display, automation, reporting-like analysis, or Apex usage
-- whether performance / selectivity is already a concern
----
-## Recommended Workflow
-### 1. Generate the simplest correct query
-Prefer:
-- only needed fields
-- clear WHERE criteria
-- reasonable LIMIT when appropriate
-- relationship depth only as deep as necessary
-### 2. Choose the right query shape
-| Need | Default pattern |
-|---|---|
-| parent data from child | child-to-parent traversal |
-| child rows from parent | subquery |
-| counts / rollups | aggregate query |
-| records with / without related rows | semi-join / anti-join |
-| text search across objects | SOSL |
-### 3. Optimize for selectivity and safety
-Check:
-- indexed / selective filters
-- no unnecessary fields
-- no avoidable wildcard or scan-heavy patterns
-- security enforcement expectations
-### 4. Validate execution path if needed
-If the user wants runtime verification, hand off execution to:
-- [handling-sf-data](../handling-sf-data/SKILL.md)
----
-## High-Signal Rules
-- never use `SELECT *` style thinking; query only required fields
-- do not query inside loops in Apex contexts
-- prefer filtering in SOQL rather than post-filtering in Apex
-- use aggregates for counts and grouped summaries instead of loading unnecessary records
-- evaluate wildcard usage carefully; leading wildcards often defeat indexes
-- account for security mode / field access requirements when queries move into Apex
----
-## Output Format
-When finishing, report in this order:
-1. **Query purpose**
-2. **Final SOQL/SOSL**
-3. **Why this shape was chosen**
-4. **Optimization or security notes**
-5. **Execution suggestion if needed**
-Suggested shape — use `references/soql-syntax-reference.md` for exact syntax:
-```
-Query goal: <summary>
-Query: <soql or sosl>
-Design: <relationship / aggregate / filter choices>
-Notes: <selectivity, limits, security, governor awareness>
-Next step: <run in handling-sf-data or embed in Apex>
-```
----
-## Cross-Skill Integration
-| Need | Delegate to | Reason |
-|---|---|---|
-| run the query against an org | [handling-sf-data](../handling-sf-data/SKILL.md) | execution and export |
-| embed the query in services/selectors | [generating-apex](../generating-apex/SKILL.md) | implementation context |
-| analyze slow-query symptoms from logs | [debugging-apex-logs](../debugging-apex-logs/SKILL.md) | runtime evidence |
-| wire query-backed UI | [generating-lwc-components](../generating-lwc-components/SKILL.md) | frontend integration |
----
-## Score Guide
-| Score | Meaning |
-|---|---|
-| 90+ | production-optimized query |
-| 80–89 | good query with minor improvements possible |
-| 70–79 | functional but performance concerns remain |
-| < 70 | needs revision before production use |
----
-## Reference File Index
-| File | When to read |
-|------|-------------|
-| `references/soql-syntax-reference.md` | Syntax, operators, date literals, relationship query patterns |
-| `references/query-optimization.md` | Selectivity rules, indexing strategy, governor limits, security patterns |
-| `references/soql-reference.md` | Quick reference — operators, date functions, aggregate functions, WITH clauses |
-| `references/anti-patterns.md` | Common SOQL mistakes and their fixes — read before finalizing any query |
-| `references/selector-patterns.md` | Apex selector layer patterns — read when embedding queries in Apex classes |
-| `references/field-coverage-rules.md` | Field coverage validation — read when generating SOQL used inside Apex code |
-| `references/cli-commands.md` | sf CLI query execution, bulk export, query plan commands |
-| `assets/basic-queries.soql` | Starter query examples for common objects |
-| `assets/relationship-queries.soql` | Parent-to-child and child-to-parent relationship query patterns |
-| `assets/aggregate-queries.soql` | COUNT, SUM, GROUP BY, ROLLUP query patterns |
-| `assets/optimization-patterns.soql` | Selective filter and index-aware query patterns |
-| `assets/bulkified-query-pattern.cls` | Apex Map-based bulk query pattern for trigger contexts |
-| `assets/selector-class.cls` | Full selector class implementation template |
-| `scripts/post-tool-validate.py` | Post-write hook — runs static SOQL validation and live query plan analysis after `.soql` file edits |

package/skills/querying-soql/assets/aggregate-queries.soql DELETED Viewed

@@ -1,242 +0,0 @@
-/**
- * AGGREGATE QUERY PATTERNS
- *
- * SOQL aggregate functions:
- * - COUNT(), COUNT(field), COUNT_DISTINCT(field)
- * - SUM(field), AVG(field), MIN(field), MAX(field)
- *
- * Use with GROUP BY for grouping results.
- */
-// ═══════════════════════════════════════════════════════════════════════════
-// BASIC COUNT
-// ═══════════════════════════════════════════════════════════════════════════
--- Count all records
-SELECT COUNT() FROM Account
--- Count with filter
-SELECT COUNT() FROM Contact WHERE Email != null
--- Count with field alias
-SELECT COUNT(Id) total FROM Account
--- Count distinct values
-SELECT COUNT_DISTINCT(Industry) FROM Account
-// ═══════════════════════════════════════════════════════════════════════════
-// SUM, AVG, MIN, MAX
-// ═══════════════════════════════════════════════════════════════════════════
--- Sum of amounts
-SELECT SUM(Amount) totalAmount FROM Opportunity WHERE IsClosed = true
--- Average amount
-SELECT AVG(Amount) avgAmount FROM Opportunity WHERE StageName = 'Closed Won'
--- Min and Max
-SELECT MIN(Amount) smallest, MAX(Amount) largest
-FROM Opportunity
-WHERE IsClosed = true
--- Combined aggregates
-SELECT
-    COUNT(Id) totalOpps,
-    SUM(Amount) totalAmount,
-    AVG(Amount) avgAmount,
-    MIN(Amount) minAmount,
-    MAX(Amount) maxAmount
-FROM Opportunity
-WHERE StageName = 'Closed Won'
-AND CALENDAR_YEAR(CloseDate) = 2024
-// ═══════════════════════════════════════════════════════════════════════════
-// GROUP BY
-// ═══════════════════════════════════════════════════════════════════════════
--- Count by single field
-SELECT Industry, COUNT(Id)
-FROM Account
-GROUP BY Industry
--- Count by multiple fields
-SELECT Industry, Type, COUNT(Id)
-FROM Account
-GROUP BY Industry, Type
--- Sum by category
-SELECT StageName, SUM(Amount)
-FROM Opportunity
-GROUP BY StageName
--- Average by owner
-SELECT OwnerId, AVG(Amount)
-FROM Opportunity
-GROUP BY OwnerId
--- Aggregate by date part
-SELECT CALENDAR_MONTH(CloseDate), SUM(Amount)
-FROM Opportunity
-WHERE CALENDAR_YEAR(CloseDate) = 2024
-GROUP BY CALENDAR_MONTH(CloseDate)
-ORDER BY CALENDAR_MONTH(CloseDate)
--- Year and Month grouping
-SELECT CALENDAR_YEAR(CloseDate) yr, CALENDAR_MONTH(CloseDate) mn, SUM(Amount)
-FROM Opportunity
-GROUP BY CALENDAR_YEAR(CloseDate), CALENDAR_MONTH(CloseDate)
-ORDER BY CALENDAR_YEAR(CloseDate), CALENDAR_MONTH(CloseDate)
-// ═══════════════════════════════════════════════════════════════════════════
-// HAVING CLAUSE
-// ═══════════════════════════════════════════════════════════════════════════
--- Filter groups by aggregate result
-SELECT Industry, COUNT(Id) cnt
-FROM Account
-GROUP BY Industry
-HAVING COUNT(Id) > 10
--- Multiple HAVING conditions
-SELECT OwnerId, SUM(Amount) total, COUNT(Id) cnt
-FROM Opportunity
-WHERE StageName = 'Closed Won'
-GROUP BY OwnerId
-HAVING SUM(Amount) > 100000
-AND COUNT(Id) >= 5
--- HAVING with different aggregate than SELECT
-SELECT LeadSource, COUNT(Id)
-FROM Lead
-GROUP BY LeadSource
-HAVING AVG(NumberOfEmployees) > 100
-// ═══════════════════════════════════════════════════════════════════════════
-// GROUP BY ROLLUP (Subtotals)
-// ═══════════════════════════════════════════════════════════════════════════
--- Single rollup
-SELECT Industry, COUNT(Id)
-FROM Account
-GROUP BY ROLLUP(Industry)
--- Returns: individual industries + grand total (null Industry row)
--- Multiple field rollup
-SELECT Industry, Type, COUNT(Id)
-FROM Account
-GROUP BY ROLLUP(Industry, Type)
--- Returns: Industry+Type combos, Industry subtotals, grand total
--- With SUM
-SELECT StageName, CALENDAR_MONTH(CloseDate), SUM(Amount)
-FROM Opportunity
-WHERE CALENDAR_YEAR(CloseDate) = 2024
-GROUP BY ROLLUP(StageName, CALENDAR_MONTH(CloseDate))
-// ═══════════════════════════════════════════════════════════════════════════
-// GROUP BY CUBE (All Combinations)
-// ═══════════════════════════════════════════════════════════════════════════
--- All dimension combinations
-SELECT Industry, Type, COUNT(Id)
-FROM Account
-GROUP BY CUBE(Industry, Type)
--- Returns: Industry+Type, Industry only, Type only, grand total
-// ═══════════════════════════════════════════════════════════════════════════
-// DATE FUNCTIONS IN AGGREGATES
-// ═══════════════════════════════════════════════════════════════════════════
--- By calendar year
-SELECT CALENDAR_YEAR(CreatedDate) yr, COUNT(Id)
-FROM Account
-GROUP BY CALENDAR_YEAR(CreatedDate)
--- By calendar quarter
-SELECT CALENDAR_YEAR(CloseDate), CALENDAR_QUARTER(CloseDate), SUM(Amount)
-FROM Opportunity
-GROUP BY CALENDAR_YEAR(CloseDate), CALENDAR_QUARTER(CloseDate)
--- By fiscal year (if fiscal year defined)
-SELECT FISCAL_YEAR(CloseDate), SUM(Amount)
-FROM Opportunity
-GROUP BY FISCAL_YEAR(CloseDate)
--- By week
-SELECT WEEK_IN_YEAR(CreatedDate), COUNT(Id)
-FROM Lead
-WHERE CALENDAR_YEAR(CreatedDate) = 2024
-GROUP BY WEEK_IN_YEAR(CreatedDate)
--- By day of week
-SELECT DAY_IN_WEEK(CreatedDate), COUNT(Id)
-FROM Case
-WHERE CreatedDate = THIS_MONTH
-GROUP BY DAY_IN_WEEK(CreatedDate)
--- 1=Sunday, 2=Monday, etc.
-// ═══════════════════════════════════════════════════════════════════════════
-// COMMON AGGREGATE PATTERNS
-// ═══════════════════════════════════════════════════════════════════════════
--- Sales by rep this year
-SELECT Owner.Name, SUM(Amount) totalSales, COUNT(Id) dealCount
-FROM Opportunity
-WHERE StageName = 'Closed Won'
-AND CloseDate = THIS_YEAR
-GROUP BY Owner.Name
-ORDER BY SUM(Amount) DESC
--- Lead conversion rate by source
-SELECT LeadSource, COUNT(Id) total, SUM(CASE WHEN IsConverted = true THEN 1 ELSE 0 END) converted
-FROM Lead
-GROUP BY LeadSource
--- Note: CASE not supported in SOQL. Calculate in Apex.
--- Cases by status and priority
-SELECT Status, Priority, COUNT(Id)
-FROM Case
-WHERE CreatedDate = THIS_MONTH
-GROUP BY Status, Priority
--- Average deal size by industry
-SELECT Account.Industry, AVG(Amount)
-FROM Opportunity
-WHERE StageName = 'Closed Won'
-GROUP BY Account.Industry
-HAVING AVG(Amount) > 50000
--- Top accounts by opportunity count
-SELECT AccountId, Account.Name, COUNT(Id) oppCount
-FROM Opportunity
-GROUP BY AccountId, Account.Name
-ORDER BY COUNT(Id) DESC
-LIMIT 20
--- Pipeline by stage and month
-SELECT StageName, CALENDAR_MONTH(CloseDate) closeMonth, SUM(Amount)
-FROM Opportunity
-WHERE IsClosed = false
-AND CloseDate = THIS_QUARTER
-GROUP BY StageName, CALENDAR_MONTH(CloseDate)
-ORDER BY CALENDAR_MONTH(CloseDate), StageName
-// ═══════════════════════════════════════════════════════════════════════════
-// AGGREGATE IN APEX
-// ═══════════════════════════════════════════════════════════════════════════
-/*
-// In Apex, aggregate results are returned as AggregateResult[]
-List<AggregateResult> results = [
-    SELECT Industry, COUNT(Id) cnt, SUM(AnnualRevenue) total
-    FROM Account
-    GROUP BY Industry
-];
-for (AggregateResult ar : results) {
-    String industry = (String) ar.get('Industry');
-    Integer count = (Integer) ar.get('cnt');
-    Decimal total = (Decimal) ar.get('total');
-}
-*/

package/skills/querying-soql/assets/basic-queries.soql DELETED Viewed

@@ -1,188 +0,0 @@
-/**
- * BASIC SOQL QUERY PATTERNS
- *
- * This file contains common SOQL patterns for everyday queries.
- * Each pattern includes the query and usage notes.
- */
-// ═══════════════════════════════════════════════════════════════════════════
-// SIMPLE SELECT QUERIES
-// ═══════════════════════════════════════════════════════════════════════════
--- Get accounts with specific fields
-SELECT Id, Name, Industry, AnnualRevenue, Phone
-FROM Account
-LIMIT 100
--- Get contacts with email
-SELECT Id, FirstName, LastName, Email, Phone
-FROM Contact
-WHERE Email != null
-LIMIT 100
--- Get opportunities by stage
-SELECT Id, Name, Amount, StageName, CloseDate
-FROM Opportunity
-WHERE StageName = 'Prospecting'
-ORDER BY Amount DESC
-// ═══════════════════════════════════════════════════════════════════════════
-// DATE FILTERING
-// ═══════════════════════════════════════════════════════════════════════════
--- Records created today
-SELECT Id, Name FROM Account
-WHERE CreatedDate = TODAY
--- Records created this week
-SELECT Id, Name FROM Lead
-WHERE CreatedDate = THIS_WEEK
--- Records created in last 30 days
-SELECT Id, Name, CreatedDate FROM Contact
-WHERE CreatedDate = LAST_N_DAYS:30
-ORDER BY CreatedDate DESC
--- Records modified this month
-SELECT Id, Name, LastModifiedDate FROM Account
-WHERE LastModifiedDate = THIS_MONTH
--- Opportunities closing this quarter
-SELECT Id, Name, Amount, CloseDate
-FROM Opportunity
-WHERE CloseDate = THIS_QUARTER
-AND IsClosed = false
--- Records created in specific date range
-SELECT Id, Name, CreatedDate FROM Account
-WHERE CreatedDate >= 2024-01-01T00:00:00Z
-AND CreatedDate < 2024-04-01T00:00:00Z
-// ═══════════════════════════════════════════════════════════════════════════
-// TEXT FILTERING
-// ═══════════════════════════════════════════════════════════════════════════
--- Exact match
-SELECT Id, Name FROM Account
-WHERE Name = 'Acme Corporation'
--- Case-insensitive exact match (default behavior)
-SELECT Id, Name FROM Account
-WHERE Name = 'acme corporation'
--- Starts with pattern
-SELECT Id, Name FROM Account
-WHERE Name LIKE 'Acme%'
--- Contains pattern
-SELECT Id, Name FROM Account
-WHERE Name LIKE '%Corp%'
--- Ends with pattern (NOT indexed - use sparingly)
-SELECT Id, Name FROM Account
-WHERE Name LIKE '%Inc.'
--- Multiple values
-SELECT Id, Name, Industry FROM Account
-WHERE Industry IN ('Technology', 'Finance', 'Healthcare')
--- Exclude values
-SELECT Id, Name, Industry FROM Account
-WHERE Industry NOT IN ('Other', 'Unknown')
-// ═══════════════════════════════════════════════════════════════════════════
-// NUMERIC FILTERING
-// ═══════════════════════════════════════════════════════════════════════════
--- Greater than
-SELECT Id, Name, AnnualRevenue FROM Account
-WHERE AnnualRevenue > 1000000
--- Range
-SELECT Id, Name, Amount FROM Opportunity
-WHERE Amount >= 10000 AND Amount <= 100000
--- Not equal
-SELECT Id, Name, Amount FROM Opportunity
-WHERE Amount != 0
-// ═══════════════════════════════════════════════════════════════════════════
-// NULL HANDLING
-// ═══════════════════════════════════════════════════════════════════════════
--- Find records with null value
-SELECT Id, Name FROM Contact
-WHERE Email = null
--- Find records with non-null value
-SELECT Id, Name, Email FROM Contact
-WHERE Email != null
--- Find accounts without opportunities (using NOT IN)
-SELECT Id, Name FROM Account
-WHERE Id NOT IN (SELECT AccountId FROM Opportunity)
-// ═══════════════════════════════════════════════════════════════════════════
-// SORTING
-// ═══════════════════════════════════════════════════════════════════════════
--- Sort ascending (default)
-SELECT Id, Name FROM Account
-ORDER BY Name ASC
--- Sort descending
-SELECT Id, Name, AnnualRevenue FROM Account
-ORDER BY AnnualRevenue DESC
--- Multiple sort fields
-SELECT Id, Name, Industry, AnnualRevenue FROM Account
-ORDER BY Industry ASC, AnnualRevenue DESC
--- Nulls last
-SELECT Id, Name, AnnualRevenue FROM Account
-ORDER BY AnnualRevenue DESC NULLS LAST
-// ═══════════════════════════════════════════════════════════════════════════
-// PAGINATION
-// ═══════════════════════════════════════════════════════════════════════════
--- First page (records 1-100)
-SELECT Id, Name FROM Account
-ORDER BY Name
-LIMIT 100
--- Second page (records 101-200)
-SELECT Id, Name FROM Account
-ORDER BY Name
-LIMIT 100
-OFFSET 100
--- Note: OFFSET max is 2000. For larger datasets, use query locator in Apex.
-// ═══════════════════════════════════════════════════════════════════════════
-// COMBINED PATTERNS
-// ═══════════════════════════════════════════════════════════════════════════
--- Active technology accounts with high revenue created this year
-SELECT Id, Name, Industry, AnnualRevenue, CreatedDate
-FROM Account
-WHERE Industry = 'Technology'
-AND AnnualRevenue > 500000
-AND IsActive__c = true
-AND CreatedDate = THIS_YEAR
-ORDER BY AnnualRevenue DESC
-LIMIT 50
--- Contacts with Gmail addresses at accounts in California
-SELECT Id, FirstName, LastName, Email, Account.Name
-FROM Contact
-WHERE Email LIKE '%@gmail.com'
-AND Account.BillingState = 'CA'
-ORDER BY LastName
--- Open cases older than 7 days
-SELECT Id, CaseNumber, Subject, Status, CreatedDate, Owner.Name
-FROM Case
-WHERE IsClosed = false
-AND CreatedDate < LAST_N_DAYS:7
-ORDER BY CreatedDate ASC