knownissues

Documentation

Overview

Package knownissues reads a file of documented findings — known issues, TODOs, a baseline of unresolved calls — and turns each into an editor diagnostic.

The format is one finding per line:

path:line: message
path:line:col: message

A message may start with a tag naming its code, and its severity ahead of that, for a finding from a tool with rule IDs:

path:line:col: [warning CFQUERYPARAM_REQ] <cfquery> should use <cfqueryparam/>
path:line: [TODO] move this to the service

A tagged entry's diagnostic carries that code, where an untagged one's is known-issue, and its severity overrides the file's.

Blank lines and lines starting with # are ignored. A path is relative to the directory holding the file, and never absolute: an absolute path is ignored, since the file is committed to a project and read on other machines, where it would not name the same file. A "../" path is kept — it reaches a sibling project the way a .cfmleditor.json's workspacePaths do, and holds wherever the projects are checked out side by side. It is the format `cfmleditor-lsp unresolved --known-issues` writes, and it is short enough to write by hand.

Index

• func DeepestTarget(file string, targets []string) string
• func Diagnostic(e Entry, lines []string, severity protocol.DiagnosticSeverity, source string) protocol.Diagnostic
• func Severity(name string) protocol.DiagnosticSeverity
• func SeverityName(sev protocol.DiagnosticSeverity) string
• func Write(w io.Writer, header []string, rows []Row)
• type Entry
  • func Parse(content, baseDir string) []Entry
• type Row

Functions

func DeepestTarget

func DeepestTarget(file string, targets []string) string

DeepestTarget is the one of targets, generated report files, whose directory holds file: the deepest when directories nest, empty when none does. It is how a report split across several files decides where a finding goes.

func Diagnostic

func Diagnostic(e Entry, lines []string, severity protocol.DiagnosticSeverity, source string) protocol.Diagnostic

Diagnostic builds the diagnostic for e over the file's lines (nil when the file cannot be read, which leaves the entry on its recorded line).

An entry in the unresolved format, `svc.method (reason)`, is underlined at the method on its line, and found again within reanchorWindow lines when an edit has moved it. Anything else covers the line's text.

func Severity

func Severity(name string) protocol.DiagnosticSeverity

Severity maps a config severity name to the LSP value. Unknown or empty is warning, the least severe level every editor's problems panel lists: Zed's lists only errors and warnings, and VS Code's leaves out hints. Information was the default, and its entries showed inline in Zed but not in the panel.

func SeverityName

func SeverityName(sev protocol.DiagnosticSeverity) string

SeverityName is the tag word for an LSP severity, the inverse of Severity.

func Write

func Write(w io.Writer, header []string, rows []Row)

Write writes rows under header, each header line as a # comment, sorted by path, line and column. A row's severity and code become its [tag].

Types

type Entry

type Entry struct {
	Path     string // the file's path joined to the known-issues file's directory
	Line     int    // 0-based
	Col      int    // 0-based, -1 when the entry names none
	Message  string
	Code     string // from the message's [tag], empty when it has none
	Severity string // from the message's [severity CODE] tag, empty when it names none
}

Entry is one finding from a known-issues file.

func Parse

func Parse(content, baseDir string) []Entry

Parse reads the entries in content. baseDir anchors relative paths.

type Row

type Row struct {
	Path     string // relative, with forward slashes
	Line     int
	Col      int
	Severity string
	Code     string
	Message  string
}

Row is one entry to write: 1-based line, and column (0 for none).