@cplieger/deadset-ts 5.2.2 → 6.0.0

package/dist/src/module-declarations.js

@@ -0,0 +1,180 @@
+/**
+ * The imports that name a `declare module` declaration whose name is a string literal: an
+ * augmentation or an ambient module, a wildcard one included. An import names it when its
+ * specifier equals the name, matches it with the one `*` standing for any run, or resolves
+ * to the same module. One that names it by name or pattern also reads the members it
+ * imports, whatever file the specifier resolves to, as a compiler reading no such file does.
+ */
+import { isCallExpression, isExportDeclaration, isExternalModuleReference, isImportDeclaration, isImportEqualsDeclaration, isImportTypeNode, isLiteralTypeNode, isModuleDeclaration, isNamespaceExport, isNamespaceImport, isNoSubstitutionTemplateLiteral, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+import { renderPosition } from "./position.js";
+import { UNANSWERED } from "./query.js";
+import { nameComponent } from "./ref.js";
+/** Whether a node is a specifier's text: a string literal or a template with no substitution. */
+function literalText(node) {
+    return node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node));
+}
+/** The specifier one node writes, where it is an import of any form. */
+function specifierOf(node) {
+    if (isImportDeclaration(node) || isExportDeclaration(node)) {
+        const specifier = node.moduleSpecifier;
+        return literalText(specifier) ? specifier : undefined;
+    }
+    if (isImportEqualsDeclaration(node)) {
+        const reference = node.moduleReference;
+        return isExternalModuleReference(reference) && literalText(reference.expression)
+            ? reference.expression
+            : undefined;
+    }
+    if (isCallExpression(node) && node.expression.kind === SyntaxKind.ImportKeyword) {
+        const [argument] = node.arguments;
+        return literalText(argument) ? argument : undefined;
+    }
+    if (isImportTypeNode(node) && isLiteralTypeNode(node.argument)) {
+        const literal = node.argument.literal;
+        return literalText(literal) ? literal : undefined;
+    }
+    return undefined;
+}
+/**
+ * The export names an import or a re-export reads from the module it names: none for a
+ * namespace, a star or a bare form.
+ */
+export function namesImported(node) {
+    if (isImportDeclaration(node)) {
+        const clause = node.importClause;
+        const bindings = clause?.namedBindings;
+        return [
+            ...(clause?.name === undefined ? [] : ["default"]),
+            ...(bindings === undefined || isNamespaceImport(bindings)
+                ? []
+                : bindings.elements.map((one) => (one.propertyName ?? one.name).text)),
+        ];
+    }
+    const clause = isExportDeclaration(node) ? node.exportClause : undefined;
+    return clause === undefined || isNamespaceExport(clause)
+        ? []
+        : clause.elements.map((one) => (one.propertyName ?? one.name).text);
+}
+/**
+ * Whether a specifier matches a declaration's name, the name's one `*` standing for any run.
+ * A relative name is resolved against its own file, so no specifier names it by its text.
+ */
+function namesModule(specifier, name) {
+    if (/^(?:\.{1,2}(?:\/|$)|\/)/u.test(name)) {
+        return false;
+    }
+    const star = name.indexOf("*");
+    if (star < 0 || name.slice(star + 1).includes("*")) {
+        return specifier === name;
+    }
+    const prefix = name.slice(0, star);
+    const suffix = name.slice(star + 1);
+    return (specifier.length >= prefix.length + suffix.length &&
+        specifier.startsWith(prefix) &&
+        specifier.endsWith(suffix));
+}
+/**
+ * The module declarations of an inventory a specifier names by name or pattern, each with
+ * the members that hold the export names given.
+ */
+export function namedBy(held) {
+    if (held.modules.size === 0) {
+        return () => [];
+    }
+    const refs = new Map();
+    const children = new Map();
+    for (const symbol of held.symbols) {
+        if (held.modules.has(symbol.id)) {
+            refs.set(symbol.id, symbol.ref);
+        }
+        if (held.modules.has(symbol.parent)) {
+            const siblings = children.get(symbol.parent) ?? [];
+            siblings.push(symbol);
+            children.set(symbol.parent, siblings);
+        }
+    }
+    return (specifier, names) => [...held.modules].flatMap(([id, name]) => {
+        if (!namesModule(specifier, name)) {
+            return [];
+        }
+        // A member is named by its declaration's reference, or an export alias's.
+        const ref = refs.get(id) ?? "";
+        const scope = ref.slice(0, ref.indexOf("#"));
+        const wanted = new Set(names.flatMap((one) => [
+            `${ref}.${nameComponent(one)}`,
+            `${scope}#${nameComponent(one)}:alias`,
+        ]));
+        const members = (children.get(id) ?? []).filter((child) => wanted.has(child.ref));
+        return [{ id, members: members.map((child) => child.id) }];
+    });
+}
+/**
+ * The references the imports of one project's own files make to the module declarations
+ * they name, each at the import's specifier.
+ */
+export function moduleDeclarationReferences(project, held, root, testFiles) {
+    const imports = [];
+    const declared = [];
+    for (const file of project.ownSourceFiles()) {
+        const fileId = held.declarations.get(nodeKey(file, file));
+        if (fileId === undefined) {
+            continue;
+        }
+        const visit = (node, from) => {
+            const own = held.declarations.get(nodeKey(file, node));
+            if (isModuleDeclaration(node) && literalText(node.name) && own !== undefined) {
+                declared.push({ id: own, name: node.name });
+            }
+            const specifier = specifierOf(node);
+            if (specifier !== undefined) {
+                imports.push({ file, from, specifier, names: namesImported(node) });
+            }
+            node.forEachChild((child) => {
+                visit(child, own ?? from);
+            });
+        };
+        file.forEachChild((child) => {
+            visit(child, fileId);
+        });
+    }
+    if (declared.length === 0 || imports.length === 0) {
+        return [];
+    }
+    const asked = [...declared.map((one) => one.name), ...imports.map((one) => one.specifier)];
+    const answers = project.symbolsAt(asked.map((node) => project.handle(node)));
+    const moduleOf = (at) => {
+        const symbol = answers[at];
+        return symbol === undefined || symbol === UNANSWERED ? undefined : symbol.id;
+    };
+    const named = namedBy(held);
+    const found = [];
+    imports.forEach((one, index) => {
+        const resolved = moduleOf(declared.length + index);
+        const position = renderPosition(one.file, root, one.specifier.getStart());
+        const read = (to, resolution) => {
+            found.push({
+                from: one.from,
+                to,
+                position,
+                use: "read",
+                resolution,
+                test: testFiles.has(position.path),
+            });
+        };
+        const same = new Set(declared
+            .filter((_, at) => resolved !== undefined && resolved === moduleOf(at))
+            .map((declaration) => declaration.id));
+        for (const id of same) {
+            read(id, "batch");
+        }
+        for (const declaration of named(one.specifier.text, one.names)) {
+            if (!same.has(declaration.id)) {
+                for (const to of [declaration.id, ...declaration.members]) {
+                    read(to, "syntax");
+                }
+            }
+        }
+    });
+    return found;
+}

package/dist/src/outside-tests.js

@@ -1,13 +1,15 @@
 /**
  * The test files no compiler configuration of a run holds. The runner executes them all
  * the same, so each module one names is a test reference: the own file a relative
- * specifier names, and the declarations that file exports under the names read from it.
- * Such a file is read without a program, so what its body references beyond the modules
- * it names is not known.
+ * specifier names, and the declarations that file exports under the names read from it,
+ * or a module declaration the specifier names by name or pattern and its members of
+ * those names. Such a file is read without a program, so what its body references
+ * beyond the modules it names is not known.
  */
 import { isCallExpression, isExportDeclaration, isImportDeclaration, isNamespaceExport, isNamespaceImport, isNoSubstitutionTemplateLiteral, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { RESOLVED_EXTENSIONS } from "./configuration-files.js";
 import { emittedFrom } from "./emit-map.js";
+import { namedBy, namesImported } from "./module-declarations.js";
 import { dirnamePath, joinPath, normalizePath, queriedModulePath } from "./paths.js";
 import { renderPosition } from "./position.js";
 import { nameComponent } from "./ref.js";
@@ -47,17 +49,11 @@ function modulesNamed(file) {
         if (isImportDeclaration(statement)) {
             const clause = statement.importClause;
             const bindings = clause?.namedBindings;
-            name(statement.moduleSpecifier, [
-                ...(clause?.name === undefined ? [] : ["default"]),
-                ...(bindings === undefined || isNamespaceImport(bindings)
-                    ? []
-                    : bindings.elements.map((one) => (one.propertyName ?? one.name).text)),
-            ], bindings === undefined ? clause?.name === undefined : isNamespaceImport(bindings));
+            name(statement.moduleSpecifier, namesImported(statement), bindings === undefined ? clause?.name === undefined : isNamespaceImport(bindings));
         }
         else if (isExportDeclaration(statement) && statement.moduleSpecifier !== undefined) {
             const clause = statement.exportClause;
-            const star = clause === undefined || isNamespaceExport(clause);
-            name(statement.moduleSpecifier, star ? [] : clause.elements.map((one) => (one.propertyName ?? one.name).text), star);
+            name(statement.moduleSpecifier, namesImported(statement), clause === undefined || isNamespaceExport(clause));
         }
     }
     const visit = (node) => {
@@ -106,11 +102,21 @@ export function outsideTestReferences(tests, held, targetRoot) {
             exported.set(key, [...(exported.get(key) ?? []), symbol.id]);
         }
     }
+    const declared = namedBy(held);
     const found = [];
     for (const { path, file } of tests) {
         const from = `${path}#`;
         const dir = dirnamePath(path) === "." ? "" : dirnamePath(path);
         for (const named of modulesNamed(file)) {
+            const position = renderPosition(file, targetRoot, named.specifier.getStart());
+            const read = (to, use) => {
+                found.push({ from, to, position, use, resolution: "syntax", test: true, unheld: true });
+            };
+            for (const declaration of declared(named.text, named.names)) {
+                for (const to of [declaration.id, ...declaration.members]) {
+                    read(to, "read");
+                }
+            }
             const written = named.text.includes("?") ? queriedModulePath(named.text) : named.text;
             if (written === undefined) {
                 continue;
@@ -121,10 +127,6 @@ export function outsideTestReferences(tests, held, targetRoot) {
             if (fileId === undefined) {
                 continue;
             }
-            const position = renderPosition(file, targetRoot, named.specifier.getStart());
-            const read = (to, use) => {
-                found.push({ from, to, position, use, resolution: "syntax", test: true, unheld: true });
-            };
             if (named.evaluates) {
                 read(fileId, "evaluation");
             }

package/dist/src/overrides.js

@@ -1,12 +1,14 @@
 /**
- * The overrides of the target's class members. A call through the base class, `this`
- * in the base's own body or a value typed as the base, names the base's member and
- * runs the override of whichever subclass the value is, so the base member's
- * declaration references every override as a use of it.
+ * The overrides of the target's class members. A call through the base class names the
+ * base's member and runs the override of whichever subclass the value is, so the base
+ * member's declaration references every override. A method overriding a member of a class
+ * declared outside the target, at any depth of its `extends` chain, is called by outside
+ * code holding the instance through that class, so its own class references it.
  */
 import { isClassDeclaration, isClassExpression, isExpressionWithTypeArguments, isPropertyAccessExpression, isQualifiedName, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { memberComponent } from "./class-members.js";
 import { nodeKey } from "./inventory.js";
+import { SymbolFlags } from "@typescript/native/unstable/sync";
 import { UNANSWERED } from "./query.js";
 /** The member kinds a subclass overrides. */
 const OVERRIDABLE = new Set(["method", "class-member"]);
@@ -38,9 +40,10 @@ function extending(project, held) {
 }
 /**
  * The references each base class member makes to its overrides, for the classes of one
- * project that extend another class of the target. A member a nearer base already
- * overrides is reached through that override. A private member is not overridden.
- * Each reference is placed at the override and made by its file.
+ * project that extend another class of the target, and each class makes to its methods
+ * that override a member of a class declared outside the target. A member a nearer base
+ * already overrides is reached through that override. A private member is not
+ * overridden. Each reference is placed at the override and made by its file.
  */
 export function overrideReferences(project, held, chains, testFiles) {
     const classes = extending(project, held);
@@ -62,14 +65,25 @@ export function overrideReferences(project, held, chains, testFiles) {
         members.set(symbol.parent, own);
     }
     const bases = new Map();
+    const outsideBases = new Map();
+    const own = project.ownPaths();
     const symbols = project.symbolsAt(classes.map((one) => project.handle(one.base)));
     classes.forEach(({ id }, index) => {
         const symbol = symbols[index];
         if (symbol !== undefined && symbol !== UNANSWERED) {
-            bases.set(id, chains
+            const inTarget = chains
                 .chainOf(symbol)
                 .map((target) => target.id)
-                .filter((target) => byId.get(target)?.kind === "class" && target !== id));
+                .filter((target) => byId.get(target)?.kind === "class" && target !== id);
+            bases.set(id, inTarget);
+            const declared = (symbol.flags & SymbolFlags.Alias) === 0 ? symbol : project.queries.aliased(symbol);
+            if (inTarget.length === 0 &&
+                declared !== UNANSWERED &&
+                (declared.flags & SymbolFlags.Class) !== 0 &&
+                declared.declarations.length > 0 &&
+                declared.declarations.every((handle) => !own.has(handle.path))) {
+                outsideBases.set(id, declared);
+            }
         }
     });
     /** The nearest member of one component the class or a class it extends declares. */
@@ -85,6 +99,21 @@ export function overrideReferences(project, held, chains, testFiles) {
         return (bases.get(classId) ?? []).flatMap((base) => declaredAbove(base, component, seen));
     };
     const found = [];
+    const outsideNames = outsideMemberNames(project, bases, outsideBases);
+    for (const [classId, names] of outsideNames) {
+        for (const [component, member] of members.get(classId) ?? []) {
+            if (member.kind === "method" && names.has(component)) {
+                found.push({
+                    from: classId,
+                    to: member.id,
+                    position: member.position,
+                    use: "read",
+                    resolution: "override",
+                    test: testFiles.has(member.position.path),
+                });
+            }
+        }
+    }
     for (const [classId, baseIds] of bases) {
         for (const [component, member] of members.get(classId) ?? []) {
             const seen = new Set([classId]);
@@ -102,3 +131,35 @@ export function overrideReferences(project, held, chains, testFiles) {
     }
     return found;
 }
+/**
+ * Per class of the target with a class declared outside the target in its `extends`
+ * chain, the names of the members that outside class's instances carry.
+ */
+function outsideMemberNames(project, bases, outsideBases) {
+    const direct = new Map();
+    for (const [classId, base] of outsideBases) {
+        const type = project.queries.declaredTypeOf(base);
+        const properties = type === UNANSWERED ? UNANSWERED : project.queries.propertiesOf(type);
+        if (properties !== UNANSWERED) {
+            direct.set(classId, new Set(properties.map((property) => property.escapedName)));
+        }
+    }
+    const names = new Map();
+    const above = (classId, seen) => {
+        if (seen.has(classId)) {
+            return new Set();
+        }
+        seen.add(classId);
+        return new Set([
+            ...(direct.get(classId) ?? []),
+            ...(bases.get(classId) ?? []).flatMap((base) => [...above(base, seen)]),
+        ]);
+    };
+    for (const classId of bases.keys()) {
+        const found = above(classId, new Set());
+        if (found.size > 0) {
+            names.set(classId, found);
+        }
+    }
+    return names;
+}

package/dist/src/query.js

@@ -211,10 +211,17 @@ export function queriesOf(checker, configFile, batch, log, ask = ASK_DIRECTLY) {
         targetOf: (type) => type.isTypeReference()
             ? one("getTarget", () => typeLocation(type), () => type.getTarget())
             : type,
+        constraintOf: (type) => type.isTypeParameter()
+            ? one("getConstraint", () => typeLocation(type), () => type.getConstraint())
+            : undefined,
         symbolOfType: (type) => one("getSymbol", () => typeLocation(type), () => type.getSymbol()),
         signaturesOf: (type, kind) => one("getSignaturesOfType", () => typeLocation(type), () => checker.getSignaturesOfType(type, kind)),
         resolvedSignature: (node) => one("getResolvedSignature", () => nodeLocation(node), () => checker.getResolvedSignature(node)),
         parameterType: (signature, index) => one("getParameterType", () => `signature ${String(signature.id)} parameter ${String(index)}`, () => checker.getParameterType(signature, index)),
+        genericOf: (signature) => signature.target === undefined
+            ? undefined
+            : one("getTarget", () => `signature ${String(signature.id)}`, () => signature.getTarget()),
+        typeAtPosition: (signature, index) => one("getTypeParameterAtPosition", () => `signature ${String(signature.id)} position ${String(index)}`, () => signature.getTypeParameterAtPosition(index)),
         signatureOf: (declaration) => one("getSignatureFromDeclaration", () => nodeLocation(declaration), () => checker.getSignatureFromDeclaration(declaration)),
         returnTypeOf: (signature) => one("getReturnTypeOfSignature", () => `signature ${String(signature.id)}`, () => checker.getReturnTypeOfSignature(signature)),
         typeToString: (type) => one("typeToString", () => typeLocation(type), () => checker.typeToString(type)),

package/dist/src/ref.js

@@ -52,6 +52,7 @@ export const REF_EXPRESSIONS = [
 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");
+// Stryker disable next-line Regex: its \v to \V mutant is no valid escape under the u flag, so the whole module fails to parse
 const ASCII_WHITESPACE = /[\t\n\v\f\r ]/gu;
 /**
  * The canonical spelling of one declared name as a fragment component: bare when

package/dist/src/references.js

@@ -6,6 +6,9 @@ import { specifierCandidates } from "./configuration-files.js";
 import { namespaceUses } from "./namespace-objects.js";
 import { globExpression } from "./glob.js";
 import { declarationsByName, nodeKey } from "./inventory.js";
+import { augmentationReferences } from "./augmentations.js";
+import { indexedAccessReferences } from "./indexed-access.js";
+import { moduleDeclarationReferences } from "./module-declarations.js";
 import { overrideReferences } from "./overrides.js";
 import { dirnamePath, queriedModulePath, relativePath, resolvePath } from "./paths.js";
 import { byPosition, isComponentFile, renderPosition } from "./position.js";
@@ -1069,7 +1072,10 @@ export function references(project, held, targetRoot, options) {
     }
     if (consumer === undefined) {
         found.push(...overrideReferences(project, held, chains, new Set(tests)));
+        found.push(...indexedAccessReferences(project, held, chains, root, new Set(tests)));
+        found.push(...moduleDeclarationReferences(project, held, root, new Set(tests)));
     }
+    found.push(...augmentationReferences(held, found));
     found.sort((a, b) => byPosition(a.position, b.position) ||
         compare(a.to, b.to) ||
         compare(a.from, b.from) ||

package/dist/src/report.js

@@ -4,7 +4,7 @@
  * renders this document, so no two renderings disagree about which findings exist.
  */
 /** The version of the report schema this analyzer writes a report to. */
-const SCHEMA_VERSION = "7.0.0";
+const SCHEMA_VERSION = "8.0.0";
 /** Every report schema version this analyzer reads: the one the Contract it implements admits. */
 export const SCHEMA_VERSIONS_ACCEPTED = [SCHEMA_VERSION];
 /** The name this analyzer writes every document under and mints every identifier with. */
@@ -186,6 +186,11 @@ function totalsOf(findings, result) {
         stale_suppressions: result.staleSuppressions.length,
         pending: result.totals.pending,
         omitted: 0,
+        withheld: {
+            certain: result.totals.withheld.certain,
+            probable: result.totals.withheld.probable,
+            possible: result.totals.withheld.possible,
+        },
     };
 }
 /** Builds the report of one run, every array in the order the Contract fixes for it. */

package/dist/src/reporters/sarif.js

@@ -3,6 +3,7 @@ import { KINDS } from "../kinds.js";
 import { lineHashes, symbolFingerprint } from "./fingerprint.js";
 import { RenderError } from "./reporter.js";
 import { utf8Bytes } from "./sha256.js";
+import { withheldLine } from "./text.js";
 const SCHEMA = "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json";
 const VERSION = "2.1.0";
 /** The unit a finding's column counts. */
@@ -216,6 +217,7 @@ export function sarif(report, options) {
         ...report.stale_suppressions.map((stale) => staleResult(stale, index, hashOf)),
     ];
     const languages = [...report.analyzer.languages].sort().join("+");
+    const withheld = withheldLine(report.totals);
     const log = {
         $schema: SCHEMA,
         version: VERSION,
@@ -233,7 +235,7 @@ export function sarif(report, options) {
                 columnKind: COLUMN_KIND,
                 originalUriBaseIds: { [URI_BASE_ID]: { description: { text: ROOT_DESCRIPTION } } },
                 results,
-                properties: { totals: report.totals },
+                properties: withheld === undefined ? { totals: report.totals } : { totals: report.totals, withheld },
             },
         ],
     };

package/dist/src/reporters/text.js

@@ -19,11 +19,27 @@ function summary(totals) {
         `${String(totals.omitted)} omitted`,
     ].join(", ");
 }
+/** The confidences a withheld line names, from the highest the minimum can withhold. */
+const WITHHELD_ORDER = ["probable", "possible"];
+/**
+ * The line naming what the minimum confidence withheld and the setting that shows it all,
+ * or undefined where it withheld nothing.
+ */
+export function withheldLine(totals) {
+    const named = WITHHELD_ORDER.filter((confidence) => totals.withheld[confidence] > 0);
+    const lowest = named.at(-1);
+    if (lowest === undefined) {
+        return undefined;
+    }
+    const counts = named.map((confidence) => `${String(totals.withheld[confidence])} ${confidence}`);
+    return `withheld by analysis.min_confidence: ${counts.join(", ")}, shown with analysis.min_confidence set to ${lowest}`;
+}
 /**
  * One line per finding in the report's order, then one per stale suppression, then the
- * summary. A finding line is `path:line:col: kind name: message [confidence] (CODE)`; the
- * summary is deliberately not in that shape, so a filter for finding lines yields exactly
- * them. Nothing else is written: no timestamp, duration or host detail.
+ * withheld line where the minimum withheld a finding, then the summary. A finding line is
+ * `path:line:col: kind name: message [confidence] (CODE)`; the summary is deliberately not
+ * in that shape, so a filter for finding lines yields exactly them. Nothing else is
+ * written: no timestamp, duration or host detail.
  */
 export const text = (report) => coalesced((function* lines() {
     for (const found of report.findings) {
@@ -32,5 +48,9 @@ export const text = (report) => coalesced((function* lines() {
     for (const stale of report.stale_suppressions) {
         yield `${stale.position.path}:${String(stale.position.line)}:${String(stale.position.column)}: ${STALE_KIND} ${stale.symbol}: ${stale.message} [${STALE_CONFIDENCE}] (${stale.code})\n`;
     }
+    const withheld = withheldLine(report.totals);
+    if (withheld !== undefined) {
+        yield `${withheld}\n`;
+    }
     yield `${summary(report.totals)}\n`;
 })());

package/dist/src/roots.js

@@ -7,7 +7,7 @@
  * decides; the published API only supposes a consumer, so a published export is live
  * under reachability and still a candidate under reference counting.
  */
-import { isExpressionWithTypeArguments, isFunctionLikeDeclaration, isPropertyAccessExpression, isQualifiedName, isTypeQueryNode, isTypeReferenceNode, } from "@typescript/native/unstable/ast";
+import { isExpressionWithTypeArguments, isFunctionLikeDeclaration, isPropertyAccessExpression, isQualifiedName, isTypeQueryNode, isTypeReferenceNode, isVariableStatement, } from "@typescript/native/unstable/ast";
 import { aliasChains } from "./alias-chain.js";
 import { conventionEntries } from "./conventions.js";
 import { entryPoints } from "./entry-points.js";
@@ -162,7 +162,7 @@ export function roots(project, held, targetRoot, options) {
     const enter = (file, kind, source, exports) => {
         entered.push({ file, kind, source, exports });
     };
-    const points = entryPoints(project, files, options.testFiles, options.host, targetRoot, options.parse);
+    const points = entryPoints(project, files, options.testFiles, options.host, targetRoot, options.parse, options.conventions?.selected);
     const published = [];
     const entries = [
         ...options.manifest.entries.map((entry) => ({
@@ -239,7 +239,7 @@ export function roots(project, held, targetRoot, options) {
         }
     }
     const api = options.publishedAPI
-        ? publishedAPI(project, published, exportsOf, held, files.byPath)
+        ? publishedAPI(project, published, exportsOf, held, files.byPath, releaseTagged(held, files))
         : { ids: [], guessed: [] };
     for (const id of api.ids) {
         add(id, "published-api", "");
@@ -303,17 +303,54 @@ function exportTables(project, held, wanted) {
     });
     return { tables, answered };
 }
+/** A release tag of a documentation comment: `@` and its name, between white space or the ends. */
+const RELEASE_TAG = /(?:^|\s)@(?:public|beta|alpha)(?=\s|$)/u;
+/**
+ * Whether the documentation comment of the statement that starts at `start`, the last
+ * `/** *\/` comment before it with only white space between the two, holds a release tag.
+ */
+function releaseTagIn(text, from, start) {
+    const leading = text.slice(from, start);
+    const open = leading.lastIndexOf("/**");
+    const close = open < 0 ? -1 : leading.indexOf("*/", open + 3);
+    if (close < 0 || leading.slice(close + 2).trim() !== "") {
+        return false;
+    }
+    return RELEASE_TAG.test(leading.slice(open + 3, close));
+}
+/** The exported top-level declarations of the program's files a release tag marks. */
+function releaseTagged(held, files) {
+    const exported = new Set(held.symbols.filter((symbol) => symbol.exported).map((one) => one.id));
+    const found = [];
+    for (const file of files.byPath.values()) {
+        for (const statement of file.statements) {
+            if (!releaseTagIn(file.text, statement.pos, statement.getStart())) {
+                continue;
+            }
+            const nodes = isVariableStatement(statement)
+                ? statement.declarationList.declarations
+                : [statement];
+            for (const node of nodes) {
+                const id = held.declarations.get(nodeKey(file, node));
+                if (id !== undefined && exported.has(id)) {
+                    found.push(id);
+                }
+            }
+        }
+    }
+    return found;
+}
 /** The kinds of container whose export table, not its members' visibility, says what it publishes. */
 const EXPORTING_CONTAINERS = new Set(["file", "namespace"]);
 /**
- * Every declaration a consumer of the library can name: what the published files export
- * and, below each, the members a consumer writes: a namespace's exported ones, any other
- * declaration's public and protected ones, never a private one or a type parameter. A
- * declaration a published one's type names is published too, exported or not. A type name
- * the checker leaves unanswered publishes every declaration spelled as it is, and those are
- * `guessed`. A published file is not itself published.
+ * Every declaration a consumer of the library can name: what the published files export,
+ * and below each the members a consumer writes, a namespace's exported ones and any other
+ * declaration's public and protected ones. A declaration a published one's type names is
+ * published too, and so is an exported declaration a release tag marks. A type name the
+ * checker leaves unanswered publishes every declaration spelled as it is, as `guessed`. A
+ * published file is not itself published.
  */
-function publishedAPI(project, published, exportsOf, held, byPath) {
+function publishedAPI(project, published, exportsOf, held, byPath, tagged) {
     const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
     const children = childrenOf(held);
     const nodes = declarationNodes(held, byPath);
@@ -327,6 +364,9 @@ function publishedAPI(project, published, exportsOf, held, byPath) {
             pending.push(id);
         }
     };
+    for (const id of tagged) {
+        reach(id);
+    }
     for (const file of published) {
         for (const id of exportsOf.get(file.fileName) ?? []) {
             if (byId.get(id)?.kind === "file") {

package/dist/src/version.js

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "5.3.0";
+export const CONTRACT_VERSION = "6.0.0";