@cplieger/deadset-ts 3.7.0 → 3.8.0

package/dist/src/suppress-inline.js

@@ -0,0 +1,259 @@
+/**
+ * The inline directive: `deadset:ignore`, the first token of a `//` line comment, naming
+ * one or more codes and a reason, and binding to every declaration that begins on the line
+ * below it.
+ */
+import { SyntaxKind } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+import { byPosition, positionKey, renderPosition } from "./position.js";
+import { SUPPRESSION_WITHOUT_REASON, SuppressionError, siteText, } from "./suppress.js";
+/**
+ * The three expressions the grammar applies to the text of each line comment, in this
+ * order: a comment in the namespace, a well-formed directive, and a directive that lacks
+ * only its reason. A test pins each to the line the grammar page carries.
+ */
+export const DIRECTIVE_EXPRESSIONS = {
+    candidate: String.raw `^//[ \t]*deadset:`,
+    wellFormed: String.raw `^//[ \t]*deadset:ignore[ \t]+(?<codes>DS[0-9]{4}(?:,DS[0-9]{4})*)[ \t]+--[ \t]+(?<reason>[^ \t\r\n][^\r\n]*?)[ \t]*$`,
+    noReason: String.raw `^//[ \t]*deadset:ignore[ \t]+(?<codes>DS[0-9]{4}(?:,DS[0-9]{4})*)(?:[ \t]+--)?[ \t]*$`,
+};
+const CANDIDATE = new RegExp(DIRECTIVE_EXPRESSIONS.candidate);
+const WELL_FORMED = new RegExp(DIRECTIVE_EXPRESSIONS.wellFormed);
+const NO_REASON = new RegExp(DIRECTIVE_EXPRESSIONS.noReason);
+/** The form a malformed directive is told to take. */
+const DIRECTIVE_FORM = "// deadset:ignore DS0000[,DS0000...] -- <reason>";
+/** Applies the grammar's three expressions to the text of one comment, in order. */
+export function classifyComment(text) {
+    if (!CANDIDATE.test(text)) {
+        return { is: "none" };
+    }
+    const groups = WELL_FORMED.exec(text)?.groups;
+    if (groups !== undefined) {
+        return {
+            is: "directive",
+            codes: (groups["codes"] ?? "").split(","),
+            reason: groups["reason"] ?? "",
+        };
+    }
+    const bare = NO_REASON.exec(text)?.groups;
+    if (bare !== undefined) {
+        return { is: "no-reason", codes: (bare["codes"] ?? "").split(",") };
+    }
+    return { is: "malformed" };
+}
+/** The literal tokens whose text may hold `//` or `/*` without starting a comment. */
+const LITERALS = new Set([
+    SyntaxKind.StringLiteral,
+    SyntaxKind.NoSubstitutionTemplateLiteral,
+    SyntaxKind.TemplateHead,
+    SyntaxKind.TemplateMiddle,
+    SyntaxKind.TemplateTail,
+    SyntaxKind.RegularExpressionLiteral,
+    SyntaxKind.JsxText,
+]);
+/** Whether one character ends a line, under the language's line terminators. */
+function endsLine(char) {
+    return char === "\n" || char === "\r" || char === "\u2028" || char === "\u2029";
+}
+/** The offset where the line holding `from` ends. */
+function lineEnd(text, from) {
+    let at = from;
+    while (at < text.length && !endsLine(text[at])) {
+        at += 1;
+    }
+    return at;
+}
+/**
+ * The offset of the first token at or after `from`: whitespace, comments and a leading
+ * hashbang are trivia.
+ */
+export function tokenStart(text, from) {
+    let at = from;
+    if (at === 0 && text.startsWith("#!")) {
+        at = lineEnd(text, 0);
+    }
+    for (;;) {
+        if (/\s/u.test(text[at] ?? "")) {
+            at += 1;
+        }
+        else if (text.startsWith("//", at)) {
+            at = lineEnd(text, at);
+        }
+        else if (text.startsWith("/*", at)) {
+            const close = text.indexOf("*/", at + 2);
+            at = close < 0 ? text.length : close + 2;
+        }
+        else {
+            return at;
+        }
+    }
+}
+/**
+ * Every `//` line comment of one file, in file order. The text between tokens is read as
+ * the language reads it: a block comment holds no line comment, and the literal tokens the
+ * syntax tree holds are skipped, so a `//` inside a string, a template or a regular
+ * expression starts nothing.
+ */
+export function lineComments(file) {
+    const text = file.text;
+    const spans = [];
+    const visit = (node) => {
+        if (LITERALS.has(node.kind)) {
+            spans.push({ start: tokenStart(text, node.pos), end: node.end });
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    spans.sort((a, b) => a.start - b.start);
+    const found = [];
+    let next = 0;
+    let at = 0;
+    while (at < text.length) {
+        while (next < spans.length && (spans[next]?.start ?? 0) < at) {
+            next += 1;
+        }
+        const span = spans[next];
+        if (span?.start === at) {
+            at = Math.max(span.end, at + 1);
+        }
+        else if (text.startsWith("//", at)) {
+            const end = lineEnd(text, at);
+            found.push({ offset: at, text: text.slice(at, end) });
+            at = end;
+        }
+        else if (text.startsWith("/*", at)) {
+            const close = text.indexOf("*/", at + 2);
+            at = close < 0 ? text.length : close + 2;
+        }
+        else {
+            at += 1;
+        }
+    }
+    return found;
+}
+/**
+ * The declarations of one file by the line each begins on, the line of its first token: a
+ * decorator, a modifier or the keyword. A variable's first token is its statement's
+ * keyword, and a variable written on a later line of the statement also begins there.
+ */
+function declarationLines(file, held, symbols) {
+    const below = new Map();
+    const add = (offset, one) => {
+        const line = file.getLineAndCharacterOfPosition(tokenStart(file.text, offset)).line + 1;
+        const at = below.get(line) ?? [];
+        if (!at.some((known) => known.id === one.id)) {
+            at.push(one);
+        }
+        below.set(line, at);
+    };
+    const visit = (node) => {
+        const id = held.declarations.get(nodeKey(file, node));
+        const one = id === undefined ? undefined : symbols.get(id);
+        if (one !== undefined) {
+            add(node.pos, one);
+            const list = node.parent;
+            if (node.kind === SyntaxKind.VariableDeclaration &&
+                list.kind === SyntaxKind.VariableDeclarationList &&
+                list.parent.kind === SyntaxKind.VariableStatement) {
+                add(list.parent.pos, one);
+            }
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return below;
+}
+/**
+ * Every comment in the namespace one project's own files hold, each with the declarations
+ * it binds, read while the project's view is open.
+ */
+export function inlineDirectives(project, held, targetRoot) {
+    const symbols = new Map(held.symbols
+        .filter((symbol) => symbol.kind !== "file")
+        .map((symbol) => [symbol.id, { id: symbol.id, ref: symbol.ref, position: symbol.position }]));
+    const found = [];
+    for (const file of project.ownSourceFiles()) {
+        const comments = lineComments(file).filter((comment) => CANDIDATE.test(comment.text));
+        if (comments.length === 0) {
+            continue;
+        }
+        const below = declarationLines(file, held, symbols);
+        for (const comment of comments) {
+            const site = renderPosition(file, targetRoot, comment.offset);
+            found.push({
+                site,
+                text: comment.text,
+                directive: classifyComment(comment.text),
+                bound: [...(below.get(site.line + 1) ?? [])],
+            });
+        }
+    }
+    return found;
+}
+/**
+ * The inline directives of a run's projects, each bound to the declarations that begin on
+ * the line below it, one directive binding the union of what each project holding its file
+ * declares there. A directive that lacks only its reason is one {@link Refusal} per code;
+ * any other malformed comment in the namespace ends the read with a
+ * {@link SuppressionError} naming the first one written.
+ */
+export function inlineSuppressions(perProject) {
+    const merged = new Map();
+    for (const written of perProject.flat()) {
+        const key = positionKey(written.site);
+        const known = merged.get(key);
+        if (known === undefined) {
+            merged.set(key, { ...written, bound: [...written.bound] });
+            continue;
+        }
+        for (const one of written.bound) {
+            if (!known.bound.some((other) => other.id === one.id)) {
+                known.bound.push(one);
+            }
+        }
+    }
+    const ordered = [...merged.values()].sort((a, b) => byPosition(a.site, b.site));
+    const records = [];
+    const refusals = [];
+    for (const { site, text, directive, bound } of ordered) {
+        switch (directive.is) {
+            case "none":
+                break;
+            case "malformed":
+                throw new SuppressionError("inline", siteText(site), JSON.stringify(text), DIRECTIVE_FORM);
+            case "no-reason":
+                for (const code of directive.codes) {
+                    refusals.push({
+                        reported: SUPPRESSION_WITHOUT_REASON,
+                        code,
+                        symbol: "",
+                        path: site.path,
+                        reason: "",
+                        site,
+                        mechanism: "inline",
+                    });
+                }
+                break;
+            case "directive": {
+                const declared = [...bound].sort((a, b) => byPosition(a.position, b.position));
+                for (const code of directive.codes) {
+                    const base = {
+                        code,
+                        path: site.path,
+                        reason: directive.reason,
+                        site,
+                        mechanism: "inline",
+                    };
+                    if (declared.length === 0) {
+                        records.push({ ...base, symbol: "", bound: "" });
+                    }
+                    for (const one of declared) {
+                        records.push({ ...base, symbol: one.ref, bound: one.id });
+                    }
+                }
+                break;
+            }
+        }
+    }
+    return { records, refusals };
+}

package/dist/src/suppress.js

@@ -0,0 +1,148 @@
+/**
+ * The suppression grammar's records, and the ledger that decides what each one did. A
+ * record is one code bound to one site with its reason, from an inline directive, an
+ * ignore entry or a baseline row. A bound record marks its declaration live before the
+ * sweep, and is in effect when it withholds the finding its code would have produced
+ * there, dormant when the configuration withholds that finding anyway, and stale otherwise.
+ */
+import { ConfigError } from "./config.js";
+import { positionKey } from "./position.js";
+import { isRef } from "./ref.js";
+/** The code a suppression that carries no reason is reported under. */
+export const SUPPRESSION_WITHOUT_REASON = "DS1701";
+/** The code an ignore entry or a baseline row that names no path is reported under. */
+export const UNSCOPED_ENTRY = "DS1702";
+/** The code a suppression that withholds nothing is reported under. */
+export const STALE_SUPPRESSION = "DS1703";
+/** A target that carries no suppression. */
+export const NO_SUPPRESSIONS = { records: [], refusals: [] };
+/**
+ * A directive, an entry or a document the grammar refuses before any finding exists: an
+ * instruction the analysis cannot carry out. It is a malformed input, so the command line
+ * answers it with the usage code.
+ */
+export class SuppressionError extends ConfigError {
+    constructor(mechanism, at, text, want) {
+        super("malformed", at, `${mechanism} ${at}: ${text}: want ${want}`);
+        this.name = "SuppressionError";
+    }
+}
+/** Where a position is written, as an error names it. */
+export function siteText(site) {
+    return site.line > 0 ? positionKey(site) : site.path;
+}
+/** An issue-kind code: `DS` and four digits. */
+export const CODE_FORM = /^DS[0-9]{4}$/u;
+/**
+ * A path inside the target: relative to the target root, the solidus as separator, no
+ * leading `./`, no trailing solidus, no `.` or `..` segment, never absolute.
+ */
+export const PATH_EXPRESSION = String.raw `^(?:[^/\\.\r\n][^/\\\r\n]*|\.[^/\\.\r\n][^/\\\r\n]*|\.\.[^/\\\r\n]+)(?:/(?:[^/\\.\r\n][^/\\\r\n]*|\.[^/\\.\r\n][^/\\\r\n]*|\.\.[^/\\\r\n]+))*$`;
+const PATH_FORM = new RegExp(PATH_EXPRESSION, "u");
+/** Whether one value is a path in the form an entry's `path` takes. */
+export function isEntryPath(value) {
+    return PATH_FORM.test(value);
+}
+const GO_IDENT = String.raw `(?:[A-Za-z_]|[^\x00-\x7F])(?:[A-Za-z0-9_]|[^\x00-\x7F])*`;
+const GO_PATH = String.raw `[A-Za-z0-9._~-]+(?:/[A-Za-z0-9._~-]+)*`;
+const GO_VERSION = String.raw `[A-Za-z0-9.+-]+`;
+const GO_FILE = String.raw `[^/\\:#\r\n]+\.go`;
+/**
+ * The reference forms of the Go analyzer's grammar. One target holds one ignore file,
+ * whose entries may name a symbol of either language, so an entry naming a Go symbol is
+ * well formed here and binds nothing.
+ */
+export const GO_REF_EXPRESSIONS = [
+    `^go://${GO_PATH}#$`,
+    `^go://${GO_PATH}#${GO_IDENT}$`,
+    `^go://${GO_PATH}#${GO_IDENT}(?:\\.${GO_IDENT})+$`,
+    `^go://${GO_PATH}#${GO_IDENT}(?:\\.${GO_IDENT})?\\[${GO_IDENT}\\]$`,
+    `^go://${GO_PATH}#${GO_FILE}:file$`,
+    `^go://${GO_PATH}#${GO_PATH}(?:@${GO_VERSION})?:require$`,
+    `^go://${GO_PATH}#${GO_PATH}(?:@${GO_VERSION})?:replace$`,
+];
+const GO_REF_FORMS = GO_REF_EXPRESSIONS.map((expression) => new RegExp(expression, "u"));
+/** Whether one value is a stable symbol reference of either language's grammar. */
+export function isSymbolRef(value) {
+    return isRef(value) || GO_REF_FORMS.some((form) => form.test(value));
+}
+/** Whether a reason is absent, empty or whitespace only, which the grammar reads as none. */
+export function blankReason(reason) {
+    return reason === undefined || /^[ \t\r\n]*$/u.test(reason);
+}
+/**
+ * The subject kinds that are a row of a document rather than a declaration of the program.
+ * A record binds to a declaration, so nothing withholds a finding about one.
+ */
+const ROW_SUBJECTS = new Set([
+    "file",
+    "dependency",
+    "module-directive",
+    "root",
+    "suppression",
+    "edge",
+]);
+/** Whether a finding's subject is a row of a document, which no record can withhold. */
+export function isRowSubject(kind) {
+    return ROW_SUBJECTS.has(kind);
+}
+/** One finding's identity: its code and the position of the thing it names. */
+function claimKey(finding) {
+    return `${finding.code}\u0000${positionKey(finding.position)}`;
+}
+/**
+ * Whether one record names one finding. A record reaches a finding in two ways: it bound
+ * the declaration at the finding's position, or it names the finding's reference and the
+ * file the finding is reported in, each exactly. The second is how an entry copied from a
+ * finding about a part of a declaration reaches the part.
+ */
+export function pairs(record, finding) {
+    if (record.code !== finding.code || ROW_SUBJECTS.has(finding.symbol.kind)) {
+        return false;
+    }
+    if (record.bound !== "" && record.bound === positionKey(finding.position)) {
+        return true;
+    }
+    return record.symbol === finding.symbol.ref && record.path === finding.position.path;
+}
+/**
+ * Decides every record against `would`, the findings the run would produce were no record
+ * there: swept with no mark, where a kind about liveness reports the marked declaration,
+ * and as swept, where a kind whose subject the sweep holds live reports it. The first
+ * record in reading order claims a finding, so a second naming it is stale. A record whose
+ * code the dials withhold from its declaration, or whose claimed finding they withhold, is
+ * dormant.
+ */
+export function ledgerOf(records, would, dials) {
+    const taken = new Set();
+    const verdicts = [];
+    const claims = [];
+    for (const record of records) {
+        if (record.bound !== "" && dials.withholdsCode(record.code, record.bound)) {
+            verdicts.push("dormant");
+            claims.push(undefined);
+            continue;
+        }
+        const claimed = would.find((finding) => !taken.has(claimKey(finding)) && pairs(record, finding));
+        claims.push(claimed);
+        if (claimed === undefined) {
+            verdicts.push("stale");
+            continue;
+        }
+        taken.add(claimKey(claimed));
+        verdicts.push(dials.withholds(claimed) ? "dormant" : "in-effect");
+    }
+    return {
+        verdicts,
+        claims,
+        withheld: (finding) => taken.has(claimKey(finding)) && !ROW_SUBJECTS.has(finding.symbol.kind),
+    };
+}
+/** The suppression counts of one run's records and the ledger over them. */
+export function suppressionCounts(records, ledger) {
+    const sites = new Set(records.map((record) => `${record.mechanism}\u0000${positionKey(record.site)}`));
+    return {
+        inEffect: ledger.verdicts.filter((verdict) => verdict === "in-effect").length,
+        reasonsRecorded: sites.size,
+    };
+}

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",