API semântica (experimental)
Esta API pode mudar entre versões do ZPA sem aviso. As suas classes são marcadas com ZpaExperimentalApi: regras em Java
podem usá-las diretamente; regras em Kotlin precisam aderir com @OptIn(ZpaExperimentalApi::class).
Além da árvore sintática, uma regra pode perguntar ao ZPA o que o código significa: a qual declaração um nome se refere, se uma variável é usada, qual coluna um nome em SQL lê, qual o tipo de um valor. O ZPA responde a partir da sua análise semântica do arquivo, das declarações do projeto inteiro e, quando configurados, dos metadados do banco de dados.
symbolTable e currentScope do contexto do visitor, Symbol, Scope, SymbolTable, PlSqlType, as classes
*Datatype e SemanticAstNode estão depreciados desde o ZPA 4.3.0 e serão removidos no ZPA 5.0. Migre as regras que os
usam para as consultas abaixo; veja Migrando do modelo de símbolos legado.
Respostas certas e incertas
O código PL/SQL frequentemente depende de coisas que o ZPA não vê: um package em outro schema, uma tabela fora dos
metadados do banco, um texto montado em tempo de execução. Por isso cada consulta responde com um tipo que diz o quão
certa é a resposta. Por exemplo, usageEvidence retorna Used, Unused, Unknown (com os motivos) ou Unavailable.
Uma regra deve reportar um problema apenas quando a resposta comprova o problema: para uma regra sobre declarações não
usadas, Unused. Unknown significa que algo que o ZPA não enxerga pode usar a declaração, e Unavailable significa
que o ZPA não tem resposta para aquele nó, então nenhuma das duas justifica um problema. Uma regra que reporta nesses
casos gera falsos positivos em código que depende de objetos fora da análise.
Exemplo
Esta regra reporta exceções declaradas, mas nunca levantadas nem tratadas:
import org.sonar.plugins.plsqlopen.api.PlSqlGrammar;
import org.sonar.plugins.plsqlopen.api.semantics.UsageEvidence;
@Override
public void init() {
subscribeTo(PlSqlGrammar.EXCEPTION_DECLARATION);
}
@Override
public void visitNode(AstNode node) {
if (getContext().usageEvidence(node) == UsageEvidence.Unused.INSTANCE) {
addIssue(node, "Remove this unused exception.");
}
}
Uma regra real também precisa decidir o que está fora do seu alcance. A regra nativa UnusedVariable, por exemplo, ignora as declarações de especificações de package, porque outras unidades podem usá-las.
Consultas
As consultas são métodos do contexto do visitor (getContext() em Java, context em Kotlin). Cada uma recebe um nó da
árvore sintática; o Javadoc lista os nós que cada uma aceita e todas
as respostas possíveis. As regras nativas são exemplos que funcionam.
Nomes: a que um nome se refere
| Consulta | Responde | Usada por |
|---|---|---|
nameBinding | A qual declaração do arquivo se refere um nome lido em PL/SQL ou SQL. Para chamadas e cursores, callBinding e cursorBinding dão a resposta completa. | VariableInCount, ColumnHidesPlSqlName, ColumnsShouldHaveTableName |
callBinding | Qual subprograma uma chamada liga, no arquivo ou no projeto, incluindo o overload escolhido pelos tipos dos argumentos. | FunctionWithoutReturn |
cursorBinding | Qual cursor OPEN, FETCH, CLOSE ou um FOR de cursor usa, e como os argumentos se ligam aos seus parâmetros. | |
fieldBinding | A qual campo de record ou atributo de objeto se refere o nome de um membro, ou que o tipo não tem esse campo. | |
typeBinding | A qual declaração de tipo se refere o nome de um tipo de dado. | |
exceptionBinding | Qual exceção um RAISE ou WHEN nomeia. | UnhandledUserDefinedException |
Declarações: como uma declaração é usada
| Consulta | Responde | Usada por |
|---|---|---|
usageEvidence | Se uma variável, exceção, cursor ou parâmetro é usado. | UnusedVariable, UnusedParameter, UnusedCursor |
hidingEvidence | Qual declaração externa uma variável ou exceção esconde. | VariableHiding |
regionUncertainty | O que a análise não enxerga em um bloco, subprograma ou trigger, como código sob compilação condicional. | UnhandledUserDefinedException |
Tipos: qual o tipo de um valor ou declaração
| Consulta | Responde | Usada por |
|---|---|---|
valueCategory | A categoria do tipo de um valor, seguindo subtipos e %TYPE. | InsertWithoutColumns, ImplicitColumnConversion, SelectAllColumns |
declaredType | O que um tipo de dado, ou o nome de um tipo record ou coleção do arquivo, declara: um tipo nativo com as suas restrições, os campos de um record, o elemento de uma coleção, uma âncora %TYPE ou %ROWTYPE. Toda resposta também traz a sua categoria. | ColumnIntoSmallerVariable, FunctionShouldBeDeterministic |
SQL: o que um comando lê
| Consulta | Responde | Usada por |
|---|---|---|
columnBinding | Qual coluna um nome em SQL estático lê. | NullTestOnNotNullColumn, ColumnIntoSmallerVariable, ImplicitColumnConversion |
mayBeOuterJoined | Se um outer join pode tornar nulas as colunas de uma origem. Só false é uma prova: nenhum outer join torna. | NullTestOnNotNullColumn |
isOuterJoined | Se está provado que um outer join torna nulas as colunas de uma origem. Só true é uma prova. | OuterJoinDiscardedByCondition, NotInWithNull |
dynamicSql | O texto SQL que EXECUTE IMMEDIATE, OPEN … FOR ou DBMS_SQL.PARSE monta, analisado como um comando. As outras consultas de SQL também respondem dentro dele. | ParameterInDynamicSql |
Projeto: outras unidades
As declarações do projeto inteiro estão disponíveis por projectAnalysis(), para perguntas sobre outras unidades. Esta
regra reporta parâmetros declarados NOCOPY na especificação do package, mas não no body:
import org.sonar.plugins.plsqlopen.api.project.PackageParameter;
import org.sonar.plugins.plsqlopen.api.project.PackageSpecificationResolution;
PackageSpecificationResolution resolution = projectAnalysis().resolvePackageSpecification(node);
if (resolution.getStatus() == PackageSpecificationResolution.Status.RESOLVED) {
var body = resolution.getBody().orElseThrow();
var specification = resolution.getSpecification().orElseThrow();
var specificationByOrdinal = new java.util.HashMap<Integer, PackageParameter>();
for (PackageParameter parameter : specification.getParameters()) {
specificationByOrdinal.put(parameter.getOrdinal(), parameter);
}
for (PackageParameter bodyParameter : body.getParameters()) {
PackageParameter specificationParameter = specificationByOrdinal.get(bodyParameter.getOrdinal());
if (specificationParameter == null) {
return;
}
if (specificationParameter.isNocopy() && !bodyParameter.isNocopy()) {
addIssue(node, "Add NOCOPY to this parameter to match its package specification.");
}
}
}
A mesma regra sobre certeza vale aqui: aja apenas com RESOLVED, que significa que o ZPA encontrou exatamente uma
especificação correspondente. NOT_FOUND, AMBIGUOUS, INCOMPLETE, NOT_APPLICABLE e NOT_PREPARED significam que o
ZPA não consegue responder com certeza.
Migrando do modelo de símbolos legado
| Código legado | Substituto |
|---|---|
Procurar um símbolo em symbolTable ou currentScope para saber a que um nome se refere | nameBinding, typeBinding, columnBinding, callBinding |
Verificar os usos de um Symbol | usageEvidence |
| Comparar escopos para encontrar declarações escondidas | hidingEvidence |
Ler um PlSqlType ou um tipo de dado de SemanticAstNode | valueCategory, declaredType |
MethodMatcher.addParameter(PlSqlType) | MethodMatcher.addParameter(Predicate) sobre o nó do argumento, por exemplo MethodMatcher.nullLiteral() |
Testes
PlSqlCheckVerifier.verify executa a regra como uma análise real, com um projeto preparado a partir do arquivo de teste,
para que as consultas respondam como em produção:
verify(path, check, metadata, conditionalCompilation, errorRecovery, prepared): passeprepared = falsepara executar a regra como em uma análise sem projeto.verifyWithExternalContext(path, check, externalContext): fornece metadados do banco e o schema de compilação, para regras que dependem deles.ProjectPlSqlCheckVerifier: recebe umProjectTestSourcepor arquivo, para regras que olham mais de um arquivo. Todos os arquivos são lidos como um projeto antes de a regra executar, e os problemas esperados são verificados em cada arquivo.