@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/dart/DartDocumentation.js

@@ -1,73 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DartDocumentation = void 0;
-const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
-/**
- * Reads Dart documentation while preserving source mappings and masking code examples.
- *
- * DartAdapter uses the mapped text before Evidence tags are parsed for each host.
- */
-var DartDocumentation;
-(function (DartDocumentation) {
-    /**
-     * Maps a classified carrier and removes ineligible example text without moving offsets.
-     *
-     * Stable offsets keep tag diagnostics aligned with the original Dart source.
-     */
-    function read(source, documentation, hostId) {
-        const parsed = EvidenceDocumentation_1.EvidenceDocumentation.read(source.content, hostId, documentation.range, documentation.syntax);
-        return {
-            ...parsed,
-            text: mask(parsed.text),
-        };
-    }
-    DartDocumentation.read = read;
-    /**
-     * Masks HTML examples and Markdown indented code while shared tag parsing handles fences.
-     *
-     * Only visible characters are replaced, preserving source line and UTF-16 positions.
-     */
-    function mask(input) {
-        const characters = input.split("");
-        const htmlCode = /<(pre|code)\b[^>]*>[\s\S]*?<\/\1\s*>/giu;
-        for (const match of input.matchAll(htmlCode))
-            hide(characters, match.index, match.index + match[0].length);
-        const lines = input.split("\n");
-        const indents = lines.filter((line) => line.trim() !== "").map(indentation);
-        const baseline = indents.reduce((minimum, indent) => Math.min(minimum, indent), Infinity);
-        let offset = 0;
-        for (const line of lines) {
-            if (indentation(line) >= baseline + 4)
-                hide(characters, offset, offset + line.length);
-            offset += line.length + 1;
-        }
-        return characters.join("");
-    }
-    /**
-     * Counts Markdown indentation after the documentation delimiter is removed.
-     *
-     * Tabs advance to the next four-column boundary before code-block comparison.
-     */
-    function indentation(line) {
-        let spaces = 0;
-        for (const character of line) {
-            if (character === " ")
-                ++spaces;
-            else if (character === "\t")
-                spaces += 4 - (spaces % 4);
-            else
-                break;
-        }
-        return spaces;
-    }
-    /**
-     * Replaces example characters with spaces while retaining original line boundaries.
-     *
-     * Newlines remain available for the caller's source-offset mapping.
-     */
-    function hide(characters, start, end) {
-        for (let index = start; index < end; ++index)
-            if (characters[index] !== "\n" && characters[index] !== "\r")
-                characters[index] = " ";
-    }
-})(DartDocumentation || (exports.DartDocumentation = DartDocumentation = {}));

package/lib/adapters/dart/DartFileScanner.d.ts

@@ -1,112 +0,0 @@
-import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { IDartFileAnalysis } from "./IDartFileAnalysis";
-/**
- * Extracts explicit Dart declarations while leaving library topology to snapshot resolution.
- *
- * The scanner owns parser-bound nodes for one source only. It emits declarations,
- * directives, and documentation as independent records so parts and exported
- * aliases can be reconciled across the selected snapshot.
- */
-export declare class DartFileScanner {
-    private readonly session;
-    private readonly source;
-    /**
-     * Retains node-free declarations beyond the parser session.
-     *
-     * The adapter consumes these records after the parser callback has closed.
-     */
-    private readonly declarations;
-    /**
-     * Stores documentation keyed by the final comment node of each group.
-     *
-     * Group identity lets adjacent DartDoc lines become one source carrier.
-     */
-    private readonly documentation;
-    /**
-     * Stores unsupported source boundaries that prevent complete analysis.
-     *
-     * These diagnostics preserve failed extraction rather than omitting declarations.
-     */
-    private readonly diagnostics;
-    /**
-     * Stores static part and export relationships.
-     *
-     * DartLibraries resolves this topology after every selected file is scanned.
-     */
-    private readonly directives;
-    /**
-     * Borrows the active parser session and immutable source.
-     *
-     * The session supplies syntax and ranges, while source identity is copied into
-     * records that remain valid after the parser callback closes.
-     */
-    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
-    /**
-     * Establishes physical declarations, documentation ownership, and source boundaries.
-     *
-     * Documentation is collected first so adjacency is decided from original
-     * source positions before directives and declarations consume the tree.
-     */
-    scan(): IDartFileAnalysis;
-    /**
-     * Visits library and nominal scopes without entering initializers or function bodies.
-     *
-     * Executable code cannot add a stable declaration to the static public surface.
-     */
-    private scope;
-    /**
-     * Gives named extensions their own owner while unnamed extensions remain library-local.
-     *
-     * This preserves Dart's distinct public address rules for extension members.
-     */
-    private nominal;
-    /**
-     * Unwraps class members while preserving metadata and documentation on the whole declaration.
-     *
-     * Attachments must remain on the declaration that defines the public unit.
-     */
-    private member;
-    /**
-     * Treats getters and setters as one property and explicit constructors or operators as functions.
-     *
-     * The classification determines the public selector emitted for the declaration.
-     */
-    private signature;
-    /**
-     * Reads only declarator lists, never identifiers nested in initializer expressions.
-     *
-     * This prevents referenced names from becoming false variable declarations.
-     */
-    private variables;
-    /**
-     * Records an explicit declaration and its original UTF-16 content range.
-     *
-     * Later documentation attachment needs the physical declaration site.
-     */
-    private add;
-    /**
-     * Copies static URI relationships and ordered export filters.
-     *
-     * Library resolution applies filters in source order to determine exported names.
-     */
-    private directive;
-    /**
-     * Normalizes a named library from identifier segments rather than source whitespace.
-     *
-     * Segment-based identity keeps comments and formatting out of the semantic name.
-     */
-    private qualifiedName;
-    /**
-     * Groups adjacent DartDoc comments and retains unsupported annotation carriers.
-     *
-     * Detached carriers remain available for a truthful host diagnostic.
-     */
-    private collectDocumentation;
-    /**
-     * Preserves unsupported source as an actionable incomplete inventory.
-     *
-     * A failed scan cannot make coverage pass with a reduced public population.
-     */
-    private problem;
-}

package/lib/adapters/dart/DartFileScanner.js

@@ -1,415 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DartFileScanner = void 0;
-/**
- * Extracts explicit Dart declarations while leaving library topology to snapshot resolution.
- *
- * The scanner owns parser-bound nodes for one source only. It emits declarations,
- * directives, and documentation as independent records so parts and exported
- * aliases can be reconciled across the selected snapshot.
- */
-class DartFileScanner {
-    session;
-    source;
-    /**
-     * Retains node-free declarations beyond the parser session.
-     *
-     * The adapter consumes these records after the parser callback has closed.
-     */
-    declarations = [];
-    /**
-     * Stores documentation keyed by the final comment node of each group.
-     *
-     * Group identity lets adjacent DartDoc lines become one source carrier.
-     */
-    documentation = new Map();
-    /**
-     * Stores unsupported source boundaries that prevent complete analysis.
-     *
-     * These diagnostics preserve failed extraction rather than omitting declarations.
-     */
-    diagnostics = [];
-    /**
-     * Stores static part and export relationships.
-     *
-     * DartLibraries resolves this topology after every selected file is scanned.
-     */
-    directives = [];
-    /**
-     * Borrows the active parser session and immutable source.
-     *
-     * The session supplies syntax and ranges, while source identity is copied into
-     * records that remain valid after the parser callback closes.
-     */
-    constructor(session, source) {
-        this.session = session;
-        this.source = source;
-    }
-    /**
-     * Establishes physical declarations, documentation ownership, and source boundaries.
-     *
-     * Documentation is collected first so adjacency is decided from original
-     * source positions before directives and declarations consume the tree.
-     */
-    scan() {
-        this.collectDocumentation();
-        this.scope(this.session.root, undefined);
-        if (this.directives.some((directive) => directive.kind === "part-of"))
-            for (const node of this.session.root.namedChildren)
-                if (node.type === "import_or_export" || node.type === "library_name")
-                    this.problem("part-directives", "A part cannot contain import, export, or library directives.", node);
-        const library = this.session.root.namedChildren.find((node) => node.type === "library_name");
-        const libraryNode = library === undefined
-            ? undefined
-            : library.namedChildren.find((node) => node.type === "dotted_identifier_list");
-        const libraryName = libraryNode === undefined ? undefined : this.qualifiedName(libraryNode);
-        return {
-            source: this.source,
-            library: this.source.physicalPath,
-            ...(libraryName === undefined ? {} : { libraryName }),
-            declarations: this.declarations,
-            documentation: [...new Set(this.documentation.values())],
-            directives: this.directives,
-            diagnostics: this.diagnostics,
-            complete: this.diagnostics.length === 0,
-        };
-    }
-    /**
-     * Visits library and nominal scopes without entering initializers or function bodies.
-     *
-     * Executable code cannot add a stable declaration to the static public surface.
-     */
-    scope(body, owner) {
-        for (const node of body.namedChildren) {
-            switch (node.type) {
-                case "comment":
-                case "documentation_comment":
-                case "script_tag":
-                    break;
-                case "library_name":
-                    if (node.children.some((child) => child.text === "augment"))
-                        this.problem("augmentation", "Library augmentation requires generated-source ownership resolution.", node);
-                    break;
-                case "import_or_export": {
-                    const exported = node.namedChildren.find((child) => child.type === "library_export");
-                    if (exported !== undefined)
-                        this.directive(exported, "export");
-                    break;
-                }
-                case "part_directive":
-                    this.directive(node, "part");
-                    break;
-                case "part_of_directive":
-                    this.directive(node, "part-of");
-                    break;
-                case "class_declaration":
-                case "mixin_declaration":
-                case "enum_declaration":
-                case "extension_declaration":
-                case "extension_type_declaration":
-                    this.nominal(node, owner);
-                    break;
-                case "type_alias":
-                    this.add(node, node.namedChildren.find((child) => child.type === "type_identifier")
-                        ?.text, "type", owner, "alias");
-                    break;
-                case "enum_constant":
-                    this.add(node, node.childForFieldName("name")?.text, "property", owner, "field");
-                    break;
-                case "class_member":
-                    this.member(node, owner);
-                    break;
-                case "function_declaration":
-                case "getter_declaration":
-                case "setter_declaration":
-                case "external_function_declaration":
-                case "external_getter_declaration":
-                case "external_setter_declaration":
-                    this.signature(node, node.childForFieldName("signature"), owner);
-                    break;
-                case "top_level_variable_declaration":
-                case "external_variable_declaration":
-                    this.variables(node, node, owner);
-                    break;
-                default:
-                    if (owner?.public !== false)
-                        this.problem("source-form", `Unsupported declaration-scope syntax '${node.type}' can change the public surface.`, node);
-            }
-        }
-    }
-    /**
-     * Gives named extensions their own owner while unnamed extensions remain library-local.
-     *
-     * This preserves Dart's distinct public address rules for extension members.
-     */
-    nominal(node, owner) {
-        let name = node.childForFieldName("name");
-        if (name?.type === "extension_type_name")
-            name =
-                name.namedChildren.find((child) => child.type === "identifier") ?? null;
-        const application = node.namedChildren.find((child) => child.type === "mixin_application_class");
-        if (application !== undefined)
-            name =
-                application.namedChildren.find((child) => child.type === "identifier") ?? null;
-        if (node.type === "extension_declaration" && name === null)
-            return;
-        const declaration = this.add(node, name?.text, "type", owner, "nominal");
-        if (declaration === undefined)
-            return;
-        const representation = node.childForFieldName("representation");
-        if (representation !== null)
-            this.add(representation, representation.childForFieldName("name")?.text, "property", declaration, "field");
-        const body = node.childForFieldName("body");
-        if (body !== null)
-            this.scope(body, declaration);
-    }
-    /**
-     * Unwraps class members while preserving metadata and documentation on the whole declaration.
-     *
-     * Attachments must remain on the declaration that defines the public unit.
-     */
-    member(node, owner) {
-        const declaration = node.namedChildren.find((child) => child.type === "declaration" || child.type === "method_declaration");
-        if (declaration === undefined) {
-            this.problem("member", "A class member has no recognized declaration.", node);
-            return;
-        }
-        let signature = declaration.childForFieldName("signature");
-        if (signature?.type === "method_signature")
-            signature =
-                signature.namedChildren.find((child) => child.type.endsWith("_signature")) ?? null;
-        if (signature === null)
-            signature =
-                declaration.namedChildren.find((child) => child.type.endsWith("_signature")) ?? null;
-        if (signature !== null)
-            this.signature(node, signature, owner);
-        else
-            this.variables(node, declaration, owner);
-    }
-    /**
-     * Treats getters and setters as one property and explicit constructors or operators as functions.
-     *
-     * The classification determines the public selector emitted for the declaration.
-     */
-    signature(node, signature, owner) {
-        if (signature === null) {
-            this.problem("signature", "A callable has no recognized signature.", node);
-            return;
-        }
-        const getter = signature.type === "getter_signature";
-        // The pinned grammar also parses an omitted-return-type setter as a function returning `set`.
-        const setter = signature.type === "setter_signature" ||
-            (signature.type === "function_signature" &&
-                signature.childForFieldName("return_type")?.text === "set");
-        let name = signature.childForFieldName("name")?.text;
-        if (signature.type.includes("constructor")) {
-            const identifiers = signature.namedChildren.filter((child) => child.type === "identifier");
-            name = identifiers[1]?.text ?? "new";
-        }
-        if (signature.type === "operator_signature")
-            name = `operator ${signature.childForFieldName("operator")?.text ?? ""}`;
-        this.add(node, name, getter || setter ? "property" : "function", owner, getter ? "getter" : setter ? "setter" : "callable");
-    }
-    /**
-     * Reads only declarator lists, never identifiers nested in initializer expressions.
-     *
-     * This prevents referenced names from becoming false variable declarations.
-     */
-    variables(node, declaration, owner) {
-        const list = declaration.namedChildren.find((child) => [
-            "initialized_identifier_list",
-            "static_final_declaration_list",
-            "identifier_list",
-        ].includes(child.type));
-        if (list === undefined) {
-            if (owner?.public !== false)
-                this.problem("variables", "A field declaration has no recognized static declarator list.", node);
-            return;
-        }
-        for (const variable of list.namedChildren.filter((child) => child.type !== "comment"))
-            this.add(node, variable.type === "identifier"
-                ? variable.text
-                : variable.childForFieldName("name")?.text, "property", owner, "field");
-    }
-    /**
-     * Records an explicit declaration and its original UTF-16 content range.
-     *
-     * Later documentation attachment needs the physical declaration site.
-     */
-    add(node, name, symbol, owner, role) {
-        if (name === undefined) {
-            this.problem("declaration-name", "A declaration has no statically addressable name.", node);
-            return undefined;
-        }
-        const visible = owner?.public !== false && !name.startsWith("_");
-        if (visible &&
-            (node.children.some((child) => child.text === "augment") ||
-                node.namedChildren.some((child) => child.children.some((part) => part.text === "augment"))))
-            this.problem("augmentation", "Augmented declarations require generated-source ownership resolution.", node);
-        const address = [...(owner?.address ?? []), name];
-        const range = this.session.range(node);
-        const siteId = `dart:${this.source.id}:site:${node.startIndex}:${node.endIndex}`;
-        const declaration = {
-            id: `${siteId}:${symbol}:${name}`,
-            name,
-            symbol,
-            role,
-            library: this.source.physicalPath,
-            identity: address,
-            address,
-            public: visible,
-            site: {
-                id: siteId,
-                file: this.source.physicalPath,
-                range,
-                content: [range],
-            },
-            ...(owner === undefined ? {} : { ownerDeclarationId: owner.id }),
-        };
-        this.declarations.push(declaration);
-        const previous = node.previousNamedSibling;
-        if (previous !== null &&
-            /^\s*$/u.test(this.source.content.slice(previous.endIndex, node.startIndex))) {
-            const documentation = this.documentation.get(previous.startIndex);
-            if (documentation !== undefined && documentation.syntax.allowWithdrawal)
-                documentation.attachments.push({
-                    declarationId: declaration.id,
-                    siteId,
-                });
-        }
-        return declaration;
-    }
-    /**
-     * Copies static URI relationships and ordered export filters.
-     *
-     * Library resolution applies filters in source order to determine exported names.
-     */
-    directive(node, kind) {
-        const named = node.namedChildren.find((child) => child.type === "dotted_identifier_list");
-        const targetNode = node.childForFieldName("uri") ??
-            node.namedChildren.find((child) => child.type === "uri");
-        const uri = targetNode === undefined
-            ? undefined
-            : targetNode.descendantsOfType("string_literal")[0];
-        const raw = uri?.text;
-        if (node.descendantsOfType("configuration_uri").length !== 0 ||
-            (raw !== undefined && !/^(?:'[^'\\$]*'|"[^"\\$]*")$/u.test(raw))) {
-            this.problem("directive-uri", "Conditional, interpolated, or escaped library URIs need resolution beyond the static selected snapshot.", node);
-            return;
-        }
-        const target = named === undefined
-            ? raw === undefined
-                ? undefined
-                : raw.slice(1, -1)
-            : this.qualifiedName(named);
-        if (target === undefined) {
-            this.problem("directive-uri", "A library directive has no static target.", node);
-            return;
-        }
-        this.directives.push({
-            kind,
-            target,
-            named: named !== undefined,
-            filters: node.namedChildren
-                .filter((child) => child.type === "combinator")
-                .map((child) => ({
-                kind: child.children[0]?.text === "show" ? "show" : "hide",
-                names: child.namedChildren
-                    .filter((part) => part.type === "identifier")
-                    .map((part) => part.text),
-            })),
-            range: this.session.range(node),
-        });
-    }
-    /**
-     * Normalizes a named library from identifier segments rather than source whitespace.
-     *
-     * Segment-based identity keeps comments and formatting out of the semantic name.
-     */
-    qualifiedName(node) {
-        return node.namedChildren
-            .filter((child) => child.type === "identifier")
-            .map((child) => child.text)
-            .join(".");
-    }
-    /**
-     * Groups adjacent DartDoc comments and retains unsupported annotation carriers.
-     *
-     * Detached carriers remain available for a truthful host diagnostic.
-     */
-    collectDocumentation() {
-        const nodes = this.session.root.descendantsOfType([
-            "comment",
-            "documentation_comment",
-            "string_literal",
-        ]);
-        for (const node of nodes) {
-            const line = node.text.startsWith("///");
-            const block = node.text.startsWith("/**");
-            if (!line &&
-                !block &&
-                !/@(?:evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link|internal|hidden|ignore)\b/u.test(node.text))
-                continue;
-            const previous = node.previousNamedSibling;
-            const prior = previous === null
-                ? undefined
-                : this.documentation.get(previous.startIndex);
-            if (line &&
-                previous !== null &&
-                previous.text.startsWith("///") &&
-                prior !== undefined &&
-                /^[ \t]*\r?\n[ \t]*$/u.test(this.source.content.slice(previous.endIndex, node.startIndex))) {
-                prior.range.end = this.session.range(node).end;
-                this.documentation.set(node.startIndex, prior);
-                continue;
-            }
-            const opening = line
-                ? "///"
-                : block
-                    ? "/**"
-                    : node.text.startsWith("//")
-                        ? "//"
-                        : node.text.startsWith("/*")
-                            ? "/*"
-                            : (node.text.match(/^(?:r)?(?:'''|"""|'|")/u)?.[0] ?? "");
-            this.documentation.set(node.startIndex, {
-                id: `dart:${this.source.id}:documentation:${node.startIndex}`,
-                range: this.session.range(node),
-                syntax: {
-                    opening,
-                    closing: opening.startsWith("/*")
-                        ? "*/"
-                        : opening.startsWith("//")
-                            ? ""
-                            : opening.replace(/^r/u, ""),
-                    ...(opening.startsWith("/*")
-                        ? { linePrefix: "*" }
-                        : line
-                            ? { linePrefix: "///" }
-                            : {}),
-                    tagBoundaries: true,
-                    allowWithdrawal: line || block,
-                },
-                attachments: [],
-            });
-        }
-    }
-    /**
-     * Preserves unsupported source as an actionable incomplete inventory.
-     *
-     * A failed scan cannot make coverage pass with a reduced public population.
-     */
-    problem(code, message, node) {
-        this.diagnostics.push({
-            code: `dart-${code}`,
-            severity: "error",
-            message,
-            repair: "Select supported explicit Dart declarations or implement the reported source boundary before checking coverage.",
-            location: {
-                file: this.source.physicalPath,
-                range: this.session.range(node),
-            },
-        });
-    }
-}
-exports.DartFileScanner = DartFileScanner;

package/lib/adapters/dart/DartLibraries.d.ts

@@ -1,24 +0,0 @@
-import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
-import type { IDartFileAnalysis } from "./IDartFileAnalysis";
-/**
- * Resolves selected Dart library ownership and export aliases without executing package tooling.
- *
- * Physical scans cannot decide whether a part belongs to a library or whether an
- * exported spelling denotes an existing unit, so this pass establishes those
- * relationships before inventory publication and documentation attachment.
- */
-export declare namespace DartLibraries {
-    /**
-     * Validates reciprocal part ownership and retains missing URI paths for watch invalidation.
-     *
-     * A missing or conflicting part makes the analysis incomplete because treating
-     * it as absent could remove public declarations from the coverage denominator.
-     */
-    function resolve(analyses: IDartFileAnalysis[], inventory: IEvidenceInventory): void;
-    /**
-     * Projects library and transitive show or hide export addresses without duplicating semantic units.
-     *
-     * One declaration can have several public paths while retaining a single unit identity.
-     */
-    function publish(analyses: IDartFileAnalysis[], inventory: IEvidenceInventory, published: Map<string, string>): void;
-}