@cplieger/deadset-ts 1.1.0 → 2.0.0

package/dist/src/paths.js

@@ -0,0 +1,86 @@
+/**
+ * Filesystem paths, as the supported platform spells them: a solidus separates
+ * segments and a leading solidus makes a path absolute.
+ *
+ * They are written here rather than taken from the platform's own library because
+ * every module below the command line stays free of the platform, and because the
+ * supported platform set is one, so a second spelling would be a rule nothing
+ * exercises.
+ */
+const SEPARATOR = "/";
+/** Whether one path names a place without a directory to resolve it against. */
+export function isAbsolutePath(path) {
+    return path.startsWith(SEPARATOR);
+}
+/**
+ * One path with `.` removed, `..` applied to the segment before it, and repeated
+ * separators collapsed. A `..` that walks past the root of an absolute path is
+ * dropped, because the root has no parent; one at the head of a relative path is
+ * kept, because the path names a place above its own start.
+ */
+export function normalizePath(path) {
+    const absolute = isAbsolutePath(path);
+    const segments = [];
+    for (const segment of path.split(SEPARATOR)) {
+        if (segment === "" || segment === ".") {
+            continue;
+        }
+        if (segment !== "..") {
+            segments.push(segment);
+            continue;
+        }
+        const last = segments[segments.length - 1];
+        if (last !== undefined && last !== "..") {
+            segments.pop();
+            continue;
+        }
+        if (!absolute) {
+            segments.push("..");
+        }
+    }
+    const joined = segments.join(SEPARATOR);
+    if (absolute) {
+        return SEPARATOR + joined;
+    }
+    return joined === "" ? "." : joined;
+}
+/** One path below another, normalized. */
+export function joinPath(...parts) {
+    const joined = parts.filter((part) => part !== "").join(SEPARATOR);
+    return joined === "" ? "." : normalizePath(joined);
+}
+/**
+ * The directory one path sits in. A path with one segment sits in the directory it
+ * is resolved against, which is `.`; the root sits in itself.
+ */
+export function dirnamePath(path) {
+    const normalized = normalizePath(path);
+    const cut = normalized.lastIndexOf(SEPARATOR);
+    if (cut < 0) {
+        return ".";
+    }
+    return cut === 0 ? SEPARATOR : normalized.slice(0, cut);
+}
+/** One path resolved against a directory, absolute where that directory is. */
+export function resolvePath(against, path) {
+    return isAbsolutePath(path) ? normalizePath(path) : joinPath(against, path);
+}
+/**
+ * One path as it reads below a root, or undefined when it is not below the root.
+ * Both are normalized first, so a root written with a trailing separator or a `.`
+ * segment reaches the same answer, and the comparison is then lexical, so a root
+ * and a path spelled through different symbolic links name nothing in common. The
+ * root itself is not below itself.
+ *
+ * The caller resolves both against the same directory before calling: a relative
+ * root and an absolute path are two spellings this cannot reconcile.
+ */
+export function relativePath(root, path) {
+    const at = normalizePath(root);
+    const prefix = at.endsWith(SEPARATOR) ? at : at + SEPARATOR;
+    const under = normalizePath(path);
+    if (!under.startsWith(prefix) || under.length === prefix.length) {
+        return undefined;
+    }
+    return under.slice(prefix.length);
+}

package/dist/src/position.js

@@ -0,0 +1,52 @@
+import { relativePath } from "./paths.js";
+/**
+ * A file the program holds whose path is not below the target root, which leaves
+ * the analysis unable to name a declaration it found. It ends the run rather than
+ * being passed over, so a position that does not render is never silently dropped.
+ */
+export class PositionError extends Error {
+    /** The file as the program named it. */
+    file;
+    constructor(file, root) {
+        super(`${file} is not below ${root}`);
+        this.name = "PositionError";
+        this.file = file;
+    }
+}
+/**
+ * The position of one offset of one file, rendered against the target root.
+ *
+ * `offset` is a UTF-16 code unit offset into the file's text, which is what every
+ * node of the tree carries.
+ */
+export function renderPosition(file, root, offset) {
+    const path = relativePath(root, file.fileName);
+    if (path === undefined) {
+        throw new PositionError(file.fileName, root);
+    }
+    const { line, character } = file.getLineAndCharacterOfPosition(offset);
+    return { path, line: line + 1, column: character + 1 };
+}
+/**
+ * The identifier of the declaration written at one position: the path, the line and
+ * the column joined by colons. It is what the graph keys on inside one run, and
+ * what the configuration intersection compares across projects, because a handle is
+ * meaningful only inside the program that produced it while a rendered position is
+ * meaningful anywhere.
+ */
+export function positionKey(position) {
+    return `${position.path}:${String(position.line)}:${String(position.column)}`;
+}
+/**
+ * Two positions ordered by file, line and column, which is the order the inventory
+ * reads in and the order every set of a run is reported in.
+ */
+export function byPosition(a, b) {
+    if (a.path !== b.path) {
+        return a.path < b.path ? -1 : 1;
+    }
+    if (a.line !== b.line) {
+        return a.line - b.line;
+    }
+    return a.column - b.column;
+}

package/dist/src/print.js

@@ -0,0 +1,56 @@
+import { renderOrigin } from "./config.js";
+/**
+ * The resolved configuration and its provenance as one JSON object, indented,
+ * ending in a newline.
+ *
+ * The output is an instance of the closed key list, so reading it back as a
+ * repository configuration resolves to the same configuration: the provenance
+ * object is a declared key resolution ignores. Keys are written in the schema's
+ * order and the severity and provenance objects in ascending key order, so one
+ * configuration renders to one string whatever order a source named its settings
+ * in.
+ */
+export function printConfig(config, provenance) {
+    const document = {
+        contract_version: config.contractVersion,
+        target: { kind: config.targetKind },
+        analysis: {
+            languages: config.analysis.languages,
+            min_confidence: config.analysis.minConfidence,
+            generated_files: config.analysis.generatedFiles,
+            consumer_tests: config.analysis.consumerTests,
+            configurations: config.analysis.configurations.map((entry) => ({
+                id: entry.id,
+                os: entry.os,
+                arch: entry.arch,
+                tags: entry.tags,
+            })),
+            matrix: { complete: config.analysis.matrixComplete },
+            template_dirs: config.analysis.templateDirs,
+            template_delimiters: {
+                left: config.analysis.templateDelimiters.left,
+                right: config.analysis.templateDelimiters.right,
+            },
+        },
+        consumers: { complete: config.consumersComplete },
+        roots: { patterns: config.rootPatterns },
+        severity: Object.fromEntries([...config.severity].sort(([a], [b]) => (a < b ? -1 : 1))),
+        exemptions: { disabled: config.exemptionsDisabled },
+        reporters: {
+            formats: config.reporters.formats,
+            sort: config.reporters.sort,
+            cascade: config.reporters.cascade,
+            max_findings: config.reporters.maxFindings,
+            fail_on: config.reporters.failOn,
+        },
+        go: {},
+        ts: {
+            test_files: config.ts.testFiles,
+            entry_files: config.ts.entryFiles,
+        },
+        provenance: Object.fromEntries([...provenance]
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([path, origin]) => [path, renderOrigin(origin)])),
+    };
+    return `${JSON.stringify(document, undefined, 2)}\n`;
+}

package/dist/src/ref.js

@@ -0,0 +1,117 @@
+/**
+ * The stable symbol reference: the identifier that names one declaration across
+ * runs, across reports, in an ignore entry, in a configured root and in a
+ * cross-language edge. It is built from names and containers only, so an edit above
+ * a declaration leaves it unchanged, and it is compared as bytes, so there is one
+ * canonical spelling per declaration and this module is where that spelling is
+ * written.
+ *
+ * The position key of {@link ./position.ts} is the other identifier and has the
+ * other job: it locates a finding inside one run, and the two never mix.
+ */
+/** The language prefix, which namespaces every reference this analyzer emits. */
+const PREFIX = "ts://";
+/**
+ * The building blocks of the reference grammar, spelled in the intersection of the
+ * two regular-expression dialects a reference is checked in: Go's `regexp` and an
+ * ECMAScript `RegExp` with no flags. Neither dialect offers a Unicode identifier
+ * property without a flag, so a character outside ASCII is admitted as a class;
+ * the expressions check the form of a reference and never validate a name, because
+ * the compiler that accepted the declaration has already validated it.
+ */
+const TS_IDENT = String.raw `(?:[A-Za-z_$]|[^\x00-\x7F])(?:[A-Za-z0-9_$]|[^\x00-\x7F])*`;
+const TS_QUOTED = String.raw `'(?:[^'\\\r\n]|\\['\\nr])*'`;
+const TS_COMPUTED = String.raw `\[[^\]\r\n\t ]+\]`;
+const TS_HEAD = `(?:${TS_IDENT}|${TS_QUOTED})`;
+const TS_MEMBER = `(?:${TS_IDENT}|#${TS_IDENT}|${TS_QUOTED}|${TS_COMPUTED})`;
+const TS_PACKAGE = String.raw `(?:@[A-Za-z0-9._-]+/)?[A-Za-z0-9._-]+`;
+const TS_FILE = String.raw `(?:[^/#\r\n]+/)*[^/#\r\n]+(?:(?:\.d)?\.[mc]?ts|\.tsx|\.[mc]?js|\.jsx)`;
+const SCOPE = `${PREFIX}${TS_PACKAGE}/${TS_FILE}`;
+const MANIFEST_SCOPE = `${PREFIX}${TS_PACKAGE}/package\\.json`;
+/**
+ * One expression per form the grammar defines, each anchored and each the whole of
+ * a reference. Several forms share one expression because they differ in what the
+ * symbol is rather than in how the reference is spelled, so the list is the set of
+ * spellings and not the set of subjects. A reference is valid when it matches one.
+ *
+ * They are written here rather than read from the Contract at run time: the Contract
+ * is data a reader outside this program consults, and a product that read it while
+ * running would need it installed beside itself. A test compares this list against
+ * the release this analyzer is written against, so a grammar that grows a form
+ * arrives here as a failing test.
+ */
+export const REF_EXPRESSIONS = [
+    `^${SCOPE}#$`,
+    `^${SCOPE}#${TS_HEAD}$`,
+    `^${SCOPE}#${TS_HEAD}:alias$`,
+    `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+$`,
+    `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+:static$`,
+    `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})*(?::static)?<${TS_IDENT}>$`,
+    `^${MANIFEST_SCOPE}#${TS_PACKAGE}:(?:dependency|dev-dependency|peer-dependency)$`,
+];
+const REF_FORMS = REF_EXPRESSIONS.map((expression) => new RegExp(expression, "u"));
+const IDENTIFIER = new RegExp(`^${TS_IDENT}$`, "u");
+const PRIVATE_NAME = new RegExp(`^#${TS_IDENT}$`, "u");
+const ASCII_WHITESPACE = /[\t\n\v\f\r ]/gu;
+/**
+ * The canonical spelling of one declared name as a fragment component: bare when
+ * the name is an identifier name, reserved words included; with its leading number
+ * sign kept when the name is a private name, because the sign is part of the name
+ * in the language and a class may declare both spellings side by side; and in
+ * single quotes otherwise. The quotes are single so that a reference sits inside a
+ * JSON string with no escaping, which is where every document carries one.
+ */
+export function nameComponent(name) {
+    if (IDENTIFIER.test(name) || PRIVATE_NAME.test(name)) {
+        return name;
+    }
+    const escaped = name
+        .replaceAll("\\", "\\\\")
+        .replaceAll("'", "\\'")
+        .replaceAll("\n", "\\n")
+        .replaceAll("\r", "\\r");
+    return `'${escaped}'`;
+}
+/**
+ * The canonical spelling of one computed key: its source text between square
+ * brackets with every ASCII whitespace character removed. The text is compared as
+ * written, so two spellings of one well-known symbol are two references, which is
+ * right, because they are two declarations.
+ */
+export function computedComponent(text) {
+    return `[${text.replaceAll(ASCII_WHITESPACE, "")}]`;
+}
+function spell(component) {
+    return component.computed ? computedComponent(component.text) : nameComponent(component.text);
+}
+/**
+ * The reference of one symbol. The chain of a declaration fragment is read from the
+ * module-level declaration inward and is never empty; the module fragment is what
+ * names the module itself.
+ */
+export function renderRef(module, fragment) {
+    const scope = `${PREFIX}${module.package}/${module.path}`;
+    switch (fragment.of) {
+        case "module":
+            return `${scope}#`;
+        case "alias":
+            return `${scope}#${nameComponent(fragment.name)}:alias`;
+        case "dependency":
+            return `${scope}#${fragment.name}:${fragment.section}`;
+        case "declaration": {
+            const chain = fragment.chain.map(spell).join(".");
+            const isStatic = fragment.static ? ":static" : "";
+            const parameter = fragment.typeParameter === undefined ? "" : `<${fragment.typeParameter}>`;
+            return `${scope}#${chain}${isStatic}${parameter}`;
+        }
+    }
+}
+/**
+ * Whether one string is a reference of this language's grammar, in its canonical
+ * spelling. A string that is not, whether misspelled or spelled in a form the
+ * grammar does not define, matches no symbol; a reference of another language is
+ * not one of this language's either, which is what the language prefix is for.
+ */
+export function isRef(value) {
+    return REF_FORMS.some((form) => form.test(value));
+}