@wrtnlabs/evidence 0.0.0

package/lib/adapters/ecmascript/EcmaScriptModuleMode.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Static module surface selected for one ECMAScript-family source file.
+ *
+ * Explicit file extensions or the nearest package metadata select this mode
+ * before scanning, which determines the supported import and export forms.
+ */
+export type EcmaScriptModuleMode = "esm" | "commonjs";

package/lib/adapters/ecmascript/EcmaScriptModuleMode.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/ecmascript/EcmaScriptModuleResolver.d.ts

@@ -0,0 +1,70 @@
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEcmaScriptModuleResolution } from "./IEcmaScriptModuleResolution";
+/**
+ * Selects JavaScript module mode for every selected source file.
+ *
+ * `EcmaScriptAdapter` uses this resolver before scanning JavaScript because
+ * `.js` and `.jsx` files inherit ESM or CommonJS semantics from the nearest
+ * package metadata. The resolver also records consulted manifests as watch
+ * dependencies and turns unreadable or conflicting package scopes into
+ * inventory diagnostics.
+ */
+export declare class EcmaScriptModuleResolver {
+    /**
+     * Creates a resolver whose package-scope lookups are isolated to one analysis.
+     *
+     * The lazy cache reads each package directory at most once. Missing manifests
+     * delegate to the parent directory, matching Node's nearest-package scope rule.
+     */
+    constructor();
+    /**
+     * Resolves module modes and watched package manifests for selected sources.
+     *
+     * Every logical address of one source must select the same mode. A mismatch is
+     * reported because parsing one file with either mode alone would make export
+     * semantics depend on an arbitrary alias.
+     */
+    resolve(sources: IEvidenceSourceFile[]): Promise<IEcmaScriptModuleResolution>;
+    /**
+     * Package manifests consulted while resolving selected source modes.
+     *
+     * The final resolution exposes these records as watch dependencies.
+     */
+    private readonly dependencies;
+    /**
+     * Failures that prevent a complete and reliable module-mode selection.
+     *
+     * `resolve` returns them to the adapter, which incorporates them into the
+     * inventory and derives its completeness flag from their presence.
+     */
+    private readonly diagnostics;
+    private mode;
+    /**
+     * Memoizes package metadata lookup by normalized directory.
+     *
+     * Its callback also records the manifest before reading it, ensuring watch can
+     * rerun analysis when a missing, changed, or repaired package boundary changes.
+     */
+    private readonly packages;
+    /**
+     * Identifies a missing package manifest without suppressing other read errors.
+     *
+     * Only ENOENT permits parent-scope fallback; permissions and malformed metadata
+     * must leave a diagnostic because their intended module mode is unknown.
+     */
+    private absent;
+    /**
+     * Converts an unknown read failure into diagnostic text.
+     *
+     * Error messages retain filesystem context while non-Error throws still produce
+     * a useful, deterministic string for the inventory diagnostic.
+     */
+    private message;
+    /**
+     * Appends a package-resolution failure for the adapter to materialize.
+     *
+     * Each call represents a distinct encountered failure; unlike export traversal,
+     * package lookup is memoized so this method does not need an extra deduplication key.
+     */
+    private problem;
+}

package/lib/adapters/ecmascript/EcmaScriptModuleResolver.js

@@ -0,0 +1,211 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EcmaScriptModuleResolver = void 0;
+const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const typia_1 = __importDefault(require("typia"));
+const tstl_1 = require("tstl");
+const SourcePath_1 = require("../../internal/SourcePath");
+/**
+ * Selects JavaScript module mode for every selected source file.
+ *
+ * `EcmaScriptAdapter` uses this resolver before scanning JavaScript because
+ * `.js` and `.jsx` files inherit ESM or CommonJS semantics from the nearest
+ * package metadata. The resolver also records consulted manifests as watch
+ * dependencies and turns unreadable or conflicting package scopes into
+ * inventory diagnostics.
+ */
+class EcmaScriptModuleResolver {
+    /**
+     * Creates a resolver whose package-scope lookups are isolated to one analysis.
+     *
+     * The lazy cache reads each package directory at most once. Missing manifests
+     * delegate to the parent directory, matching Node's nearest-package scope rule.
+     */
+    constructor() {
+        this.packages = new tstl_1.VariadicSingleton(async (directory) => {
+            const manifest = SourcePath_1.SourcePath.slash(node_path_1.default.join(directory, "package.json"));
+            this.dependencies.set(manifest, { path: manifest, recursive: false });
+            try {
+                const content = await (0, promises_1.readFile)(manifest, "utf8");
+                const metadata = (() => {
+                    const _ao0 = (input, _path, _exceptionable = true) => undefined === input.type || "string" === typeof input.type || _assertGuard_1._assertGuard(_exceptionable, {
+                        method: "typia.json.assertParse",
+                        path: _path + ".type",
+                        expected: "(string | undefined)",
+                        value: input.type
+                    }, _errorFactory);
+                    const _io0 = input => undefined === input.type || "string" === typeof input.type;
+                    const __is = input => "object" === typeof input && null !== input && false === Array.isArray(input) && _io0(input);
+                    let _errorFactory;
+                    const __assert = (input, errorFactory) => {
+                        if (false === __is(input)) {
+                            _errorFactory = errorFactory;
+                            ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input && false === Array.isArray(input) || _assertGuard_1._assertGuard(true, {
+                                method: "typia.json.assertParse",
+                                path: _path + "",
+                                expected: "IJavaScriptPackageJson",
+                                value: input
+                            }, _errorFactory)) && _ao0(input, _path + "", true) || _assertGuard_1._assertGuard(true, {
+                                method: "typia.json.assertParse",
+                                path: _path + "",
+                                expected: "IJavaScriptPackageJson",
+                                value: input
+                            }, _errorFactory))(input, "$input", true);
+                        }
+                        return input;
+                    };
+                    return (input, errorFactory) => __assert(JSON.parse(input), errorFactory);
+                })()(content.replace(/^\uFEFF/u, ""));
+                if (metadata.type === undefined || metadata.type === "commonjs")
+                    return "commonjs";
+                if (metadata.type === "module")
+                    return "esm";
+                this.problem("javascript-package-type", `Package metadata declares unsupported JavaScript module type '${metadata.type}'.`, "Use 'module' or 'commonjs' for the package.json type field.", manifest);
+                return "commonjs";
+            }
+            catch (cause) {
+                if (this.absent(cause)) {
+                    // A directory without a manifest inherits its parent package scope.
+                    // Reaching the filesystem root supplies JavaScript's CommonJS default.
+                    const parent = node_path_1.default.dirname(directory);
+                    return parent === directory
+                        ? "commonjs"
+                        : this.packages.get(SourcePath_1.SourcePath.slash(parent));
+                }
+                this.problem("javascript-package-json", `Could not read JavaScript module metadata: ${this.message(cause)}`, "Correct the nearest package.json before evaluating JavaScript coverage.", manifest);
+                return "commonjs";
+            }
+        });
+    }
+    /**
+     * Resolves module modes and watched package manifests for selected sources.
+     *
+     * Every logical address of one source must select the same mode. A mismatch is
+     * reported because parsing one file with either mode alone would make export
+     * semantics depend on an arbitrary alias.
+     */
+    async resolve(sources) {
+        const modes = new Map();
+        await Promise.all(sources.map(async (source) => {
+            const addresses = source.addresses.length === 0
+                ? [source.physicalPath]
+                : source.addresses.map((address) => address.absolute);
+            const selected = new Set(await Promise.all(addresses.map((file) => this.mode(file))));
+            if (selected.size !== 1)
+                this.problem("javascript-module-mode", "Logical aliases of one JavaScript source select different module modes.", "Keep aliases under package scopes with the same type or select one logical file.", source.physicalPath);
+            modes.set(source.id, selected.values().next().value ?? "commonjs");
+        }));
+        return {
+            modes,
+            dependencies: Array.from(this.dependencies.values()),
+            diagnostics: this.diagnostics,
+            complete: this.diagnostics.length === 0,
+        };
+    }
+    /**
+     * Package manifests consulted while resolving selected source modes.
+     *
+     * The final resolution exposes these records as watch dependencies.
+     */
+    dependencies = new Map();
+    /**
+     * Failures that prevent a complete and reliable module-mode selection.
+     *
+     * `resolve` returns them to the adapter, which incorporates them into the
+     * inventory and derives its completeness flag from their presence.
+     */
+    diagnostics = [];
+    /**
+     * Selects a file's explicit or package-inherited JavaScript module mode.
+     *
+     * `.mjs` and `.cjs` always determine their own mode; other extensions consult
+     * the nearest cached package directory after converting the path to a stable key.
+     */
+    async mode(file) {
+        const extension = node_path_1.default.extname(file).toLowerCase();
+        if (extension === ".mjs")
+            return "esm";
+        if (extension === ".cjs")
+            return "commonjs";
+        return this.packages.get(SourcePath_1.SourcePath.slash(node_path_1.default.dirname(node_path_1.default.resolve(file))));
+    }
+    /**
+     * Memoizes package metadata lookup by normalized directory.
+     *
+     * Its callback also records the manifest before reading it, ensuring watch can
+     * rerun analysis when a missing, changed, or repaired package boundary changes.
+     */
+    packages;
+    /**
+     * Identifies a missing package manifest without suppressing other read errors.
+     *
+     * Only ENOENT permits parent-scope fallback; permissions and malformed metadata
+     * must leave a diagnostic because their intended module mode is unknown.
+     */
+    absent(cause) {
+        return cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+    }
+    /**
+     * Converts an unknown read failure into diagnostic text.
+     *
+     * Error messages retain filesystem context while non-Error throws still produce
+     * a useful, deterministic string for the inventory diagnostic.
+     */
+    message(cause) {
+        return cause instanceof Error ? cause.message : String(cause);
+    }
+    /**
+     * Appends a package-resolution failure for the adapter to materialize.
+     *
+     * Each call represents a distinct encountered failure; unlike export traversal,
+     * package lookup is memoized so this method does not need an extra deduplication key.
+     */
+    problem(code, message, repair, file) {
+        this.diagnostics.push({
+            code,
+            severity: "error",
+            message,
+            repair,
+            location: { file },
+        });
+    }
+}
+exports.EcmaScriptModuleResolver = EcmaScriptModuleResolver;

package/lib/adapters/ecmascript/EcmaScriptSyntax.d.ts

@@ -0,0 +1,24 @@
+import type { Node } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+/**
+ * Tree-sitter spelling checks shared by TypeScript and JavaScript extraction.
+ *
+ * The scanner uses these narrow syntax helpers to preserve literal names,
+ * bindings, comments, and supported static module forms without compiler evaluation.
+ */
+export declare namespace EcmaScriptSyntax {
+    function token(node: Node, value: string): boolean;
+    function name(node: Node | null): string | undefined;
+    function qualifiedName(node: Node | null): string[];
+    function modifier(node: Node, value: string): boolean;
+    function publicMember(node: Node): boolean;
+    function memberName(node: Node): string | undefined;
+    function specifierName(node: Node): string | undefined;
+    function specifierAlias(node: Node): string | undefined;
+    function functionValue(node: Node | null): boolean;
+    function functionType(node: Node | null): boolean;
+    function comment(node: Node): IEvidenceCommentSyntax;
+    function jsdoc(node: Node): boolean;
+    function module(source: Node | null): string | undefined;
+    function bindings(pattern: Node | null): Node[];
+}

package/lib/adapters/ecmascript/EcmaScriptSyntax.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EcmaScriptSyntax = void 0;
+/**
+ * Tree-sitter spelling checks shared by TypeScript and JavaScript extraction.
+ *
+ * The scanner uses these narrow syntax helpers to preserve literal names,
+ * bindings, comments, and supported static module forms without compiler evaluation.
+ */
+var EcmaScriptSyntax;
+(function (EcmaScriptSyntax) {
+    function token(node, value) {
+        return node.children.some((child) => !child.isNamed && child.type === value);
+    }
+    EcmaScriptSyntax.token = token;
+    function name(node) {
+        if (node === null)
+            return undefined;
+        switch (node.type) {
+            case "identifier":
+            case "property_identifier":
+            case "shorthand_property_identifier_pattern":
+            case "type_identifier":
+                return node.text;
+            case "number":
+                return numeric(node.text);
+            case "string":
+                return string(node.text);
+            default:
+                return undefined;
+        }
+    }
+    EcmaScriptSyntax.name = name;
+    function qualifiedName(node) {
+        if (node === null)
+            return [];
+        const direct = name(node);
+        if (direct !== undefined)
+            return [direct];
+        if (node.type !== "nested_identifier")
+            return [];
+        return node.namedChildren.flatMap(qualifiedName);
+    }
+    EcmaScriptSyntax.qualifiedName = qualifiedName;
+    function modifier(node, value) {
+        return node.children.some((child) => child.type === value ||
+            (child.type === "accessibility_modifier" && child.text === value));
+    }
+    EcmaScriptSyntax.modifier = modifier;
+    function publicMember(node) {
+        const member = memberName(node);
+        return (member !== undefined &&
+            !modifier(node, "private") &&
+            !modifier(node, "protected") &&
+            !modifier(node, "accessor"));
+    }
+    EcmaScriptSyntax.publicMember = publicMember;
+    function memberName(node) {
+        return name(node.childForFieldName("name") ??
+            node.childForFieldName("pattern") ??
+            node.childForFieldName("property"));
+    }
+    EcmaScriptSyntax.memberName = memberName;
+    function specifierName(node) {
+        const named = name(node.childForFieldName("name"));
+        if (named !== undefined)
+            return named;
+        return token(node, "default") ? "default" : undefined;
+    }
+    EcmaScriptSyntax.specifierName = specifierName;
+    function specifierAlias(node) {
+        const alias = name(node.childForFieldName("alias"));
+        if (alias !== undefined)
+            return alias;
+        const source = name(node.childForFieldName("name"));
+        return source !== undefined && token(node, "default") ? "default" : source;
+    }
+    EcmaScriptSyntax.specifierAlias = specifierAlias;
+    function functionValue(node) {
+        let current = node;
+        while (current !== null) {
+            if (current.type === "arrow_function" ||
+                current.type === "function_expression" ||
+                current.type === "generator_function")
+                return true;
+            if (current.type !== "parenthesized_expression" &&
+                current.type !== "as_expression" &&
+                current.type !== "satisfies_expression" &&
+                current.type !== "non_null_expression" &&
+                current.type !== "type_assertion")
+                return false;
+            current =
+                current.type === "type_assertion"
+                    ? (current.namedChildren.at(-1) ?? null)
+                    : (current.childForFieldName("expression") ??
+                        current.childForFieldName("value") ??
+                        current.namedChildren[0] ??
+                        null);
+        }
+        return false;
+    }
+    EcmaScriptSyntax.functionValue = functionValue;
+    function functionType(node) {
+        let current = node;
+        if (current?.type === "type_annotation")
+            current = current.namedChildren[0] ?? null;
+        while (current?.type === "parenthesized_type")
+            current = current.namedChildren[0] ?? null;
+        return current?.type === "function_type";
+    }
+    EcmaScriptSyntax.functionType = functionType;
+    function comment(node) {
+        if (node.text.startsWith("//"))
+            return {
+                opening: "//",
+                closing: "",
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        if (node.text.startsWith("/**"))
+            return {
+                opening: "/**",
+                closing: "*/",
+                linePrefix: "*",
+                tagBoundaries: true,
+                allowWithdrawal: true,
+            };
+        return {
+            opening: "/*",
+            closing: "*/",
+            linePrefix: "*",
+            tagBoundaries: true,
+            allowWithdrawal: false,
+        };
+    }
+    EcmaScriptSyntax.comment = comment;
+    function jsdoc(node) {
+        return node.type === "comment" && node.text.startsWith("/**");
+    }
+    EcmaScriptSyntax.jsdoc = jsdoc;
+    function module(source) {
+        if (source === null || source.type !== "string")
+            return undefined;
+        return string(source.text);
+    }
+    EcmaScriptSyntax.module = module;
+    function bindings(pattern) {
+        if (pattern === null)
+            return [];
+        switch (pattern.type) {
+            case "identifier":
+            case "shorthand_property_identifier_pattern":
+                return [pattern];
+            case "assignment_pattern":
+            case "rest_pattern":
+                return bindings(pattern.childForFieldName("left") ?? pattern.namedChildren[0] ?? null);
+            case "object_pattern":
+            case "array_pattern":
+                return pattern.namedChildren.flatMap((child) => {
+                    if (child.type === "pair_pattern")
+                        return bindings(child.childForFieldName("value") ??
+                            child.namedChildren.at(-1) ??
+                            null);
+                    return bindings(child);
+                });
+            default:
+                return [];
+        }
+    }
+    EcmaScriptSyntax.bindings = bindings;
+    function string(text) {
+        if (text.length < 2)
+            return undefined;
+        const quote = text[0];
+        if ((quote !== '"' && quote !== "'") || text.at(-1) !== quote)
+            return undefined;
+        let output = "";
+        for (let index = 1; index < text.length - 1; ++index) {
+            const character = text[index];
+            if (character !== "\\") {
+                output += character ?? "";
+                continue;
+            }
+            const escaped = text[++index];
+            if (escaped === undefined)
+                return undefined;
+            switch (escaped) {
+                case "n":
+                    output += "\n";
+                    break;
+                case "r":
+                    output += "\r";
+                    break;
+                case "t":
+                    output += "\t";
+                    break;
+                case "b":
+                    output += "\b";
+                    break;
+                case "f":
+                    output += "\f";
+                    break;
+                case "v":
+                    output += "\v";
+                    break;
+                case "0":
+                    output += "\0";
+                    break;
+                case "x": {
+                    const value = hexadecimal(text, index + 1, 2);
+                    if (value === undefined)
+                        return undefined;
+                    output += String.fromCharCode(value);
+                    index += 2;
+                    break;
+                }
+                case "u": {
+                    if (text[index + 1] === "{") {
+                        const closing = text.indexOf("}", index + 2);
+                        if (closing === -1)
+                            return undefined;
+                        const digits = text.slice(index + 2, closing);
+                        if (!/^[0-9a-fA-F]{1,6}$/u.test(digits))
+                            return undefined;
+                        const value = Number.parseInt(digits, 16);
+                        if (value > 0x10ffff)
+                            return undefined;
+                        output += String.fromCodePoint(value);
+                        index = closing;
+                    }
+                    else {
+                        const value = hexadecimal(text, index + 1, 4);
+                        if (value === undefined)
+                            return undefined;
+                        output += String.fromCharCode(value);
+                        index += 4;
+                    }
+                    break;
+                }
+                case "\n":
+                    break;
+                case "\r":
+                    if (text[index + 1] === "\n")
+                        ++index;
+                    break;
+                default:
+                    output += escaped;
+            }
+        }
+        return output;
+    }
+    function numeric(text) {
+        const compact = text.replaceAll("_", "");
+        const value = Number(compact);
+        return Number.isFinite(value) ? String(value) : compact;
+    }
+    function hexadecimal(text, start, length) {
+        const digits = text.slice(start, start + length);
+        return digits.length === length && /^[0-9a-fA-F]+$/u.test(digits)
+            ? Number.parseInt(digits, 16)
+            : undefined;
+    }
+})(EcmaScriptSyntax || (exports.EcmaScriptSyntax = EcmaScriptSyntax = {}));

package/lib/adapters/ecmascript/EcmaScriptType.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Programming languages that share the ECMAScript declaration and module model.
+ *
+ * The discriminator selects grammar-specific diagnostics while one scanner and
+ * export resolver handle the common JavaScript and TypeScript surface.
+ */
+export type EcmaScriptType = "typescript" | "javascript";

package/lib/adapters/ecmascript/EcmaScriptType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/ecmascript/IEcmaScriptBinding.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Resolves one public ECMAScript export to a local declaration or module namespace.
+ *
+ * The export resolver carries this intermediate record across local exports and
+ * re-export paths before it publishes public addresses for owned units.
+ */
+export interface IEcmaScriptBinding {
+    /**
+     * Identifier of the source file that owns the resolved binding.
+     *
+     * A namespace binding names this module even when it has no individual local
+     * declaration name, allowing the resolver to traverse its public exports.
+     */
+    sourceId: string;
+    /**
+     * Local root name of the declaration within {@link sourceId}.
+     *
+     * Omission represents a namespace binding, whose reachable exports must be
+     * expanded before an owned unit can be published.
+     */
+    localName?: string;
+    /**
+     * Whether the export path is restricted to TypeScript's type space.
+     *
+     * The resolver retains this restriction through re-exports and excludes
+     * value-only units when it publishes the final public addresses.
+     */
+    typeOnly: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptBinding.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/ecmascript/IEcmaScriptComment.d.ts

@@ -0,0 +1,39 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEcmaScriptCommentAttachment } from "./IEcmaScriptCommentAttachment";
+/**
+ * Retains one parsed source comment and its scanner-established JSDoc attachments.
+ *
+ * The adapter later materializes only attachments whose units become public, so a
+ * comment resembling JSDoc cannot create evidence without an eligible declaration.
+ */
+export interface IEcmaScriptComment {
+    /**
+     * Stable identifier for this parsed comment within its source snapshot.
+     *
+     * Attachment processing uses the identifier to distinguish this comment from
+     * other comments that may have the same text or nearby physical location.
+     */
+    id: string;
+    /**
+     * Physical source range occupied by the complete comment.
+     *
+     * Materialized documentation uses this range when the comment supplies a
+     * claim, while the declaration host retains its own range when no comment does.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Parsed comment syntax used to interpret its Evidence annotations.
+     *
+     * The annotation parser receives this classification so it can apply the
+     * language-appropriate JSDoc and line-comment rules.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Declaration carriers that the scanner determined this comment may document.
+     *
+     * Each entry preserves the semantic unit and physical site separately because
+     * one declaration position may affect more than one unit.
+     */
+    attachments: IEcmaScriptCommentAttachment[];
+}

package/lib/adapters/ecmascript/IEcmaScriptComment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });