@wrtnlabs/evidence 0.0.0

package/lib/adapters/markdown/MarkdownSyntax.js

@@ -0,0 +1,234 @@
+"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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,38 @@
+"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/EvidenceMatlabAdapter.d.ts

@@ -0,0 +1,15 @@
+import { MatlabAdapter } from "./MatlabAdapter";
+/**
+ * Extracts textual MATLAB classes and primary functions with class-folder ownership.
+ *
+ * Snapshot-wide ownership attaches external methods to their class and merges
+ * accessors with declared properties. Package and class segments remain explicit
+ * in public paths. Eligible percent-line help comments provide source-mapped
+ * evidence rather than treating arbitrary executable strings as documentation.
+ *
+ * Runtime path mutation, dynamic properties, legacy classes, inherited or generated
+ * members, Octave extensions, and binary or live scripts are outside the supported
+ * text-source population.
+ */
+export declare class EvidenceMatlabAdapter extends MatlabAdapter {
+}

package/lib/adapters/matlab/EvidenceMatlabAdapter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceMatlabAdapter = void 0;
+const MatlabAdapter_1 = require("./MatlabAdapter");
+/**
+ * Extracts textual MATLAB classes and primary functions with class-folder ownership.
+ *
+ * Snapshot-wide ownership attaches external methods to their class and merges
+ * accessors with declared properties. Package and class segments remain explicit
+ * in public paths. Eligible percent-line help comments provide source-mapped
+ * evidence rather than treating arbitrary executable strings as documentation.
+ *
+ * Runtime path mutation, dynamic properties, legacy classes, inherited or generated
+ * members, Octave extensions, and binary or live scripts are outside the supported
+ * text-source population.
+ */
+class EvidenceMatlabAdapter extends MatlabAdapter_1.MatlabAdapter {
+}
+exports.EvidenceMatlabAdapter = EvidenceMatlabAdapter;

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

@@ -0,0 +1,103 @@
+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/IMatlabDeclaration.js

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

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

@@ -0,0 +1,35 @@
+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/IMatlabDocumentation.js

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

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

@@ -0,0 +1,20 @@
+/**
+ * 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/IMatlabDocumentationAttachment.js

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

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

@@ -0,0 +1,43 @@
+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/IMatlabFileAnalysis.js

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

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

@@ -0,0 +1,104 @@
+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;
+}