@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/markdown/MarkdownSyntax.js

@@ -1,234 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MarkdownSyntax = void 0;
-/**
- * Markdown syntax shared by unit materialization and unreadable-tag diagnostics.
- *
- * The Markdown adapter uses these lexical helpers before it creates units or
- * reports annotations that appear in non-readable source regions.
- */
-var MarkdownSyntax;
-(function (MarkdownSyntax) {
-    const explicitAnchor = /\s*\{#([A-Za-z0-9][A-Za-z0-9._:-]*)\}\s*$/;
-    const letterOrNumber = /^(?:\p{L}|\p{N})$/u;
-    const markers = [
-        "@evidenceExcludeReview",
-        "@evidenceReview",
-        "@evidenceExclude",
-        "@evidence",
-        "@link",
-    ];
-    function fence(line) {
-        let indent = 0;
-        while (indent < line.length && line[indent] === " ")
-            ++indent;
-        if (indent > 3)
-            return undefined;
-        const marker = line[indent];
-        if (marker !== "`" && marker !== "~")
-            return undefined;
-        let cursor = indent;
-        while (line[cursor] === marker)
-            ++cursor;
-        const length = cursor - indent;
-        if (length < 3)
-            return undefined;
-        const remainder = line.slice(cursor);
-        if (marker === "`" && remainder.includes("`"))
-            return undefined;
-        return { marker, length, remainder };
-    }
-    MarkdownSyntax.fence = fence;
-    function heading(line) {
-        let cursor = 0;
-        while (cursor < line.length && line[cursor] === " " && cursor < 4)
-            ++cursor;
-        if (cursor > 3 || line[cursor] !== "#")
-            return undefined;
-        const marker = cursor;
-        while (line[cursor] === "#")
-            ++cursor;
-        const level = cursor - marker;
-        if (level > 6)
-            return undefined;
-        if (cursor < line.length && line[cursor] !== " " && line[cursor] !== "\t")
-            return undefined;
-        let title = line.slice(cursor).trim();
-        const withoutHashes = title.replace(/#+$/, "");
-        if (withoutHashes !== title &&
-            (withoutHashes === "" ||
-                withoutHashes.endsWith(" ") ||
-                withoutHashes.endsWith("\t")))
-            title = withoutHashes.trim();
-        const match = explicitAnchor.exec(title);
-        if (match !== null) {
-            const anchor = match[1];
-            if (anchor !== undefined)
-                return {
-                    level,
-                    title: title.slice(0, match.index).trim(),
-                    anchor,
-                };
-        }
-        return { level, title, anchor: slug(title) };
-    }
-    MarkdownSyntax.heading = heading;
-    function slug(title) {
-        let output = "";
-        let separated = false;
-        for (const character of title.toLowerCase()) {
-            if (letterOrNumber.test(character) || character === "_") {
-                output += character;
-                separated = false;
-            }
-            else if ((character === "-" || character.trim() === "") &&
-                output !== "" &&
-                !separated) {
-                output += "-";
-                separated = true;
-            }
-        }
-        return output.replace(/-$/, "");
-    }
-    MarkdownSyntax.slug = slug;
-    function annotation(line) {
-        const content = lineContent(line);
-        return markers.find((marker) => content === marker ||
-            content.startsWith(marker + " ") ||
-            content.startsWith(marker + "\t"));
-    }
-    MarkdownSyntax.annotation = annotation;
-    function lineContent(line) {
-        let content = line.trim();
-        let changed = true;
-        while (changed) {
-            changed = false;
-            if (content.startsWith(">")) {
-                content = content.slice(1).trim();
-                changed = true;
-                continue;
-            }
-            const marker = listMarker(content);
-            if (marker !== 0) {
-                content = content.slice(marker).trim();
-                changed = true;
-            }
-        }
-        return content;
-    }
-    MarkdownSyntax.lineContent = lineContent;
-    function renderedEdge(line) {
-        const lower = line.toLowerCase();
-        if (lower.includes("<pre"))
-            return lower.includes("</pre>") ? "both" : "open";
-        if (lower.includes("</pre>"))
-            return "close";
-        if (line.includes("={`"))
-            return line.includes("`}") ? "both" : "open";
-        if (line.includes("`}"))
-            return "close";
-        return "none";
-    }
-    MarkdownSyntax.renderedEdge = renderedEdge;
-    function indentedCode(line) {
-        return line.startsWith("    ") || line.startsWith("\t");
-    }
-    MarkdownSyntax.indentedCode = indentedCode;
-    /**
-     * Reports whether a column lies inside a closed backtick code span.
-     *
-     * Annotation scanning uses this result to reject tags in inline examples while
-     * ignoring unmatched delimiters that do not establish a Markdown code region.
-     */
-    function inlineCode(line, column) {
-        let cursor = 0;
-        while (cursor < line.length) {
-            const opening = line.indexOf("`", cursor);
-            if (opening < 0)
-                return false;
-            const length = delimiterLength(line, opening);
-            if (escaped(line, opening)) {
-                cursor = opening + length;
-                continue;
-            }
-            let closing = opening + length;
-            let closed = false;
-            while (closing < line.length) {
-                closing = line.indexOf("`", closing);
-                if (closing < 0)
-                    return false;
-                const candidate = delimiterLength(line, closing);
-                if (candidate === length && !escaped(line, closing)) {
-                    closed = true;
-                    break;
-                }
-                closing += candidate;
-            }
-            if (!closed)
-                return false;
-            if (column >= opening && column < closing + length)
-                return true;
-            cursor = closing + length;
-        }
-        return false;
-    }
-    MarkdownSyntax.inlineCode = inlineCode;
-    function hasWhitespace(value) {
-        for (const character of value)
-            if (character.trim() === "")
-                return true;
-        return false;
-    }
-    MarkdownSyntax.hasWhitespace = hasWhitespace;
-    /**
-     * Maps one supported ATX depth to its public Markdown selector.
-     *
-     * Only headings that Evidence materializes as units have selectors; other
-     * depths fail here instead of silently receiving a public symbol.
-     */
-    function symbol(level) {
-        switch (level) {
-            case 1:
-                return "h1";
-            case 2:
-                return "h2";
-            case 3:
-                return "h3";
-            case 4:
-                return "h4";
-            default:
-                throw new Error(`Markdown H${level} is not an Evidence unit.`);
-        }
-    }
-    MarkdownSyntax.symbol = symbol;
-    function listMarker(content) {
-        for (const marker of ["- ", "* ", "+ "])
-            if (content.startsWith(marker))
-                return marker.length;
-        let cursor = 0;
-        while (cursor < content.length) {
-            const character = content[cursor];
-            if (character === undefined || character < "0" || character > "9")
-                break;
-            ++cursor;
-        }
-        if (cursor === 0 ||
-            cursor + 1 >= content.length ||
-            (content[cursor] !== "." && content[cursor] !== ")") ||
-            content[cursor + 1] !== " ")
-            return 0;
-        return cursor + 2;
-    }
-    function delimiterLength(line, opening) {
-        let cursor = opening;
-        while (line[cursor] === "`")
-            ++cursor;
-        return cursor - opening;
-    }
-    function escaped(line, offset) {
-        let slashes = 0;
-        for (let index = offset - 1; index >= 0 && line[index] === "\\"; --index)
-            ++slashes;
-        return slashes % 2 === 1;
-    }
-})(MarkdownSyntax || (exports.MarkdownSyntax = MarkdownSyntax = {}));

package/lib/adapters/markdown/MarkdownTarget.d.ts

@@ -1,17 +0,0 @@
-import type { IEvidenceAddress } from "../../structures/IEvidenceAddress";
-/**
- * Parses one root-relative Markdown path and optional literal anchor.
- *
- * Target resolution uses this grammar for Markdown references, retaining the
- * anchor as one accessor segment because Markdown headings are not nested paths.
- */
-export declare namespace MarkdownTarget {
-    function parse(target: string): IEvidenceAddress;
-    /**
-     * Preserves authored path text except portable separators and leading `./`.
-     *
-     * This makes equivalent relative spellings compare consistently without
-     * resolving dot segments or changing the case-sensitive public file address.
-     */
-    function normalize(file: string): string;
-}

package/lib/adapters/markdown/MarkdownTarget.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MarkdownTarget = void 0;
-/**
- * Parses one root-relative Markdown path and optional literal anchor.
- *
- * Target resolution uses this grammar for Markdown references, retaining the
- * anchor as one accessor segment because Markdown headings are not nested paths.
- */
-var MarkdownTarget;
-(function (MarkdownTarget) {
-    function parse(target) {
-        const hash = target.indexOf("#");
-        if (hash === target.length - 1)
-            throw new Error("Name a Markdown anchor after '#', or omit '#' when citing the file unit itself.");
-        const file = normalize(hash < 0 ? target : target.slice(0, hash));
-        if (file === "")
-            throw new Error("Name the Markdown file before '#'.");
-        return {
-            file,
-            segments: hash < 0 ? [] : [target.slice(hash + 1)],
-        };
-    }
-    MarkdownTarget.parse = parse;
-    /**
-     * Preserves authored path text except portable separators and leading `./`.
-     *
-     * This makes equivalent relative spellings compare consistently without
-     * resolving dot segments or changing the case-sensitive public file address.
-     */
-    function normalize(file) {
-        let output = file.replaceAll("\\", "/");
-        while (output.startsWith("./"))
-            output = output.slice(2);
-        return output;
-    }
-    MarkdownTarget.normalize = normalize;
-})(MarkdownTarget || (exports.MarkdownTarget = MarkdownTarget = {}));

package/lib/adapters/matlab/IMatlabDeclaration.d.ts

@@ -1,103 +0,0 @@
-import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
-import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
-/**
- * Represents a MATLAB declaration before class-folder and accessor reconciliation.
- *
- * MATLAB can separate a public signature, implementation file, and property
- * accessors, so this record retains those physical facts until ownership is known.
- */
-export interface IMatlabDeclaration {
-    /**
-     * Identifies this physical declaration extracted from the selected source.
-     *
-     * Documentation attachments and later ownership links use it before unit IDs exist.
-     */
-    id: string;
-    /**
-     * Stores the literal MATLAB identifier from the declaration.
-     *
-     * The resolver appends it to its owner path when creating a public unit address.
-     */
-    name: string;
-    /**
-     * Classifies the declaration in Evidence's shared programming selector model.
-     *
-     * This distinguishes types, functions, and properties during graph selection.
-     */
-    symbol: EvidenceProgrammingSymbol;
-    /**
-     * Names package and lexical-owner segments that define semantic identity.
-     *
-     * Ownership reconciliation may replace this path for an external class method.
-     */
-    identity: string[];
-    /**
-     * Names the public accessor segments projected from a selected source file.
-     *
-     * The array remains distinct from identity because external methods have class-file aliases.
-     */
-    address: string[];
-    /**
-     * Identifies the physical file that establishes this declaration's ownership.
-     *
-     * The resolver uses this anchor to match external members with their class definition.
-     */
-    anchor: string;
-    /**
-     * States whether static MATLAB visibility exposes this declaration publicly.
-     *
-     * Ownership and accessor reconciliation can further restrict an initially visible record.
-     */
-    public: boolean;
-    /**
-     * Names the class-folder owner required by an external method declaration.
-     *
-     * The resolver uses this physical relationship to reject same-named methods
-     * from an unrelated class before assigning a semantic parent.
-     */
-    externalOwner?: string;
-    /**
-     * Identifies the selected implementation required by a nonabstract signature.
-     *
-     * Keeping the required file explicit lets incomplete input fail instead of
-     * silently shrinking the population to only declarations with bodies.
-     */
-    implementation?: string;
-    /**
-     * Identifies a getter or setter that contributes to an existing property unit.
-     *
-     * Omission means this declaration is independently materialized rather than an accessor.
-     */
-    accessor?: "get" | "set";
-    /**
-     * Records whether the declared property has public read access.
-     *
-     * It determines whether a matching getter can remain on the public surface.
-     */
-    getPublic?: boolean;
-    /**
-     * Records whether the declared property has public write access.
-     *
-     * It determines whether a matching setter can remain on the public surface.
-     */
-    setPublic?: boolean;
-    /**
-     * Lists additional public class-file projections for an external method.
-     *
-     * Each file supplies an address for the same semantic unit, rather than a
-     * duplicate declaration that would inflate coverage.
-     */
-    publicFiles?: string[];
-    /**
-     * References the scanner-local parent declaration when one exists.
-     *
-     * Omission denotes a top-level function or class before ownership reconciliation.
-     */
-    ownerDeclarationId?: string;
-    /**
-     * Holds physical declaration and content spans for hosts and fingerprints.
-     *
-     * Materialized units retain these ranges even when ownership joins several files.
-     */
-    site: IEvidenceUnitSite;
-}

package/lib/adapters/matlab/IMatlabDocumentation.d.ts

@@ -1,35 +0,0 @@
-import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-import type { IMatlabDocumentationAttachment } from "./IMatlabDocumentationAttachment";
-/**
- * Represents a MATLAB documentation carrier or tag-bearing unsupported carrier.
- *
- * MATLAB help placement has language-specific attachment rules, so this record
- * preserves both accepted help and tagged text that needs an actionable failure.
- */
-export interface IMatlabDocumentation {
-    /**
-     * Identifies this physical documentation carrier within one source analysis.
-     *
-     * Attachments use the key before ownership maps declarations to public units.
-     */
-    id: string;
-    /**
-     * Locates the half-open UTF-16 source span occupied by the help text.
-     *
-     * Inventory fingerprints exclude this range when reviewing documented declarations.
-     */
-    range: IEvidenceSourceRange;
-    /**
-     * Describes comment delimiters and annotation rules used to parse this carrier.
-     *
-     * MatlabDocumentation relies on the syntax to preserve source offsets while masking examples.
-     */
-    syntax: IEvidenceCommentSyntax;
-    /**
-     * Lists physical declaration sites that directly own this help text.
-     *
-     * Unsupported tagged carriers remain unattached so the adapter can report their placement.
-     */
-    attachments: IMatlabDocumentationAttachment[];
-}

package/lib/adapters/matlab/IMatlabDocumentationAttachment.d.ts

@@ -1,20 +0,0 @@
-/**
- * Connects one MATLAB help carrier to a physical declaration site.
- *
- * The pair distinguishes source attachment from a unit's semantic identity;
- * later ownership reconciliation may merge several sites into that one unit.
- */
-export interface IMatlabDocumentationAttachment {
-    /**
-     * Identifies the scanner-local declaration receiving this help carrier.
-     *
-     * Materialization resolves it to a semantic unit after class-folder ownership is known.
-     */
-    declarationId: string;
-    /**
-     * Identifies the physical declaration site owned by the eventual semantic unit.
-     *
-     * This keeps a shared class unit's source hosts distinct across selected files.
-     */
-    siteId: string;
-}

package/lib/adapters/matlab/IMatlabFileAnalysis.d.ts

@@ -1,43 +0,0 @@
-import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { IMatlabDeclaration } from "./IMatlabDeclaration";
-import type { IMatlabDocumentation } from "./IMatlabDocumentation";
-/**
- * Holds the node-free MATLAB extraction retained after a parse session closes.
- *
- * Class-folder ownership is resolved from selected files after scanning, so the
- * intermediate record retains physical declarations and diagnostics together.
- */
-export interface IMatlabFileAnalysis {
-    /**
-     * Retains the selected source snapshot represented by this extraction.
-     *
-     * Its physical path participates in class-folder ownership and diagnostic locations.
-     */
-    source: IEvidenceSourceFile;
-    /**
-     * Lists extracted declarations, including non-public ownership boundaries.
-     *
-     * The resolver needs hidden records to determine whether descendants can be published.
-     */
-    declarations: IMatlabDeclaration[];
-    /**
-     * Lists classified help text and unsupported annotation carriers.
-     *
-     * MatlabAdapter creates hosts only after ownership reconciliation establishes eligible units.
-     */
-    documentation: IMatlabDocumentation[];
-    /**
-     * Collects failures found while establishing the static public surface.
-     *
-     * These diagnostics propagate to the inventory rather than removing ambiguous declarations.
-     */
-    diagnostics: IEvidenceDiagnostic[];
-    /**
-     * States whether the scanner classified every relevant MATLAB form.
-     *
-     * A false value remains a failed analysis through ownership reconciliation,
-     * preventing unsupported class layout from shrinking the selected surface.
-     */
-    complete: boolean;
-}

package/lib/adapters/matlab/MatlabAdapter.d.ts

@@ -1,104 +0,0 @@
-import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
-import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
-import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
-/**
- * Extracts MATLAB public units after resolving file and class-folder ownership.
- *
- * Snapshot-wide ownership connects declarations that lexical scanning alone
- * cannot place under their final public owner. Unit materialization then precedes
- * documentation attachment, preserving shared identities, physical sites, and
- * incomplete-analysis diagnostics across the selected source population.
- */
-export declare class MatlabAdapter implements IEvidenceAdapter {
-    /**
-     * Artifact discriminator selecting MATLAB source interpretation.
-     *
-     * It disambiguates .m sources from other languages that accept the same suffix.
-     */
-    readonly type = "matlab";
-    /**
-     * Builds an owned MATLAB inventory and closes the bounded parser runtime.
-     *
-     * Ownership resolution runs across file analyses before publishing units and
-     * comment hosts. Failed source discovery or parsing remains an incomplete result.
-     */
-    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
-    private scan;
-    /**
-     * Reconciles class member sites and retains each physical declaration address.
-     *
-     * Materialization joins scanner declarations under their resolved class owner
-     * while preserving each physical implementation site for fingerprints and tags.
-     */
-    private materializeUnits;
-    /**
-     * Resolves withdrawals before publishing attached annotation hosts.
-     *
-     * A withdrawn declaration must not expose a host that could satisfy coverage,
-     * so this phase establishes effective withdrawal before tag parsing proceeds.
-     */
-    private materializeDocumentation;
-    /**
-     * Retains public declaration sites even when they carry no documentation.
-     *
-     * Site preservation keeps the complete public population and its fingerprint
-     * boundary independent of whether a declaration currently has a tag carrier.
-     */
-    private materializeUndocumentedHosts;
-    /**
-     * Groups published semantic owners by their physical declaration site.
-     *
-     * One site can represent several owners through MATLAB accessors and external
-     * implementations, so later annotation attachment needs this retained grouping.
-     */
-    private attachmentGroups;
-    /**
-     * Creates an attached or explicitly unsupported documentation carrier.
-     *
-     * This preserves valid MATLAB help for parsing and reports annotation-looking
-     * text whose placement cannot legally document the surrounding declaration.
-     */
-    private host;
-    /**
-     * Parses Evidence tags only after the adapter establishes their host.
-     *
-     * Host-first parsing prevents a comment from gaining coverage semantics until
-     * its declaration scope, physical site, and withdrawal state are known.
-     */
-    private parse;
-    /**
-     * Detects Evidence or withdrawal annotations outside masked examples.
-     *
-     * The adapter uses this precheck to distinguish an unsupported carrier from
-     * ordinary prose before it produces a placement diagnostic.
-     */
-    private annotation;
-    /**
-     * Detects acknowledgements and reviews on withdrawn carriers.
-     *
-     * Withdrawal may coexist with prose, but acknowledgement and review tags on
-     * that carrier are rejected because a withdrawn host cannot provide evidence.
-     */
-    private claimAnnotation;
-    /**
-     * Recognizes supported annotation names at documentation line boundaries.
-     *
-     * Boundary-aware matching avoids treating ordinary prose containing a marker
-     * substring as an Evidence declaration or a withdrawal instruction.
-     */
-    private annotationPattern;
-    /**
-     * Follows explicit parent ownership to propagate withdrawal.
-     *
-     * A child inherits a withdrawn semantic owner only through the resolved parent
-     * chain, keeping unrelated sites from losing their eligible annotation hosts.
-     */
-    private withdrawn;
-    /**
-     * Separates programming kinds while unifying class-folder implementation identities.
-     *
-     * This mapping gives MATLAB declarations stable public identities while class
-     * folders and external method files continue to represent the same semantic owner.
-     */
-    private unitId;
-}