Pular para o conteúdo principal

API semântica (experimental)

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.

Modelo de símbolos legado

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​

ConsultaRespondeUsada por
nameBindingA 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
callBindingQual subprograma uma chamada liga, no arquivo ou no projeto, incluindo o overload escolhido pelos tipos dos argumentos.FunctionWithoutReturn
cursorBindingQual cursor OPEN, FETCH, CLOSE ou um FOR de cursor usa, e como os argumentos se ligam aos seus parâmetros.
fieldBindingA qual campo de record ou atributo de objeto se refere o nome de um membro, ou que o tipo não tem esse campo.
typeBindingA qual declaração de tipo se refere o nome de um tipo de dado.
exceptionBindingQual exceção um RAISE ou WHEN nomeia.UnhandledUserDefinedException

Declarações: como uma declaração é usada​

ConsultaRespondeUsada por
usageEvidenceSe uma variável, exceção, cursor ou parâmetro é usado.UnusedVariable, UnusedParameter, UnusedCursor
hidingEvidenceQual declaração externa uma variável ou exceção esconde.VariableHiding
regionUncertaintyO 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​

ConsultaRespondeUsada por
valueCategoryA categoria do tipo de um valor, seguindo subtipos e %TYPE.InsertWithoutColumns, ImplicitColumnConversion, SelectAllColumns
declaredTypeO 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ê​

ConsultaRespondeUsada por
columnBindingQual coluna um nome em SQL estático lê.NullTestOnNotNullColumn, ColumnIntoSmallerVariable, ImplicitColumnConversion
mayBeOuterJoinedSe um outer join pode tornar nulas as colunas de uma origem. Só false é uma prova: nenhum outer join torna.NullTestOnNotNullColumn
isOuterJoinedSe está provado que um outer join torna nulas as colunas de uma origem. Só true é uma prova.OuterJoinDiscardedByCondition, NotInWithNull
dynamicSqlO 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 legadoSubstituto
Procurar um símbolo em symbolTable ou currentScope para saber a que um nome se referenameBinding, typeBinding, columnBinding, callBinding
Verificar os usos de um SymbolusageEvidence
Comparar escopos para encontrar declarações escondidashidingEvidence
Ler um PlSqlType ou um tipo de dado de SemanticAstNodevalueCategory, 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): passe prepared = false para 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 um ProjectTestSource por 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.