@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -0,0 +1,86 @@
+import type { EvidenceMarkdownSymbol } from "../../typings/EvidenceMarkdownSymbol";
+import type { IEvidenceMarkdownFence } from "./IEvidenceMarkdownFence";
+import type { IEvidenceMarkdownHeading } from "./IEvidenceMarkdownHeading";
+/**
+ * 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.
+ */
+export declare namespace EvidenceMarkdownSyntax {
+    /**
+     * Recognizes a CommonMark fenced-code boundary on one source line.
+     *
+     * Up to three leading spaces are allowed. The returned marker, run length,
+     * and remainder let the scanner apply the opening and closing rules without
+     * discarding the line's original spelling.
+     */
+    function fence(line: string): IEvidenceMarkdownFence | undefined;
+    /**
+     * Parses one supported ATX heading and its stable anchor identity.
+     *
+     * Explicit `{#anchor}` suffixes win over generated slugs. Unsupported depth,
+     * indentation, or missing marker separation leaves the line as ordinary
+     * prose.
+     */
+    function heading(line: string): IEvidenceMarkdownHeading | undefined;
+    /**
+     * Derives Evidence's deterministic anchor for an unanchored heading title.
+     *
+     * Letters, numbers, and underscores remain significant; punctuation and
+     * whitespace collapse only into the hyphen separators admitted by this
+     * adapter.
+     */
+    function slug(title: string): string;
+    /**
+     * Finds a supported Evidence marker after Markdown container prefixes.
+     *
+     * The marker must occupy the complete line or be followed by whitespace, so a
+     * longer prose token cannot be misreported as an unreadable annotation.
+     */
+    function annotation(line: string): string | undefined;
+    /**
+     * Removes repeated blockquote and list prefixes from one annotation line.
+     *
+     * Tag recognition consumes this logical content while source ranges continue
+     * to use the unchanged physical line owned by the scanner.
+     */
+    function lineContent(line: string): string;
+    /**
+     * Reports whether one physical line belongs to an indented code block.
+     *
+     * Four spaces or one leading tab make headings and annotation syntax inert at
+     * the top-level Markdown boundary supported by this scanner.
+     */
+    function indentedCode(line: string): boolean;
+    /**
+     * 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: string, column: number): boolean;
+    /**
+     * Detects whitespace that prevents a path from forming one target token.
+     *
+     * Markdown public addresses preserve literal path spelling, so callers reject
+     * any Unicode whitespace instead of silently escaping or normalizing it.
+     */
+    function hasWhitespace(value: string): boolean;
+    /**
+     * 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: number): EvidenceMarkdownSymbol;
+    /**
+     * Reports whether Markdown backslash escaping neutralizes a token boundary.
+     *
+     * An odd immediately preceding slash run escapes the next punctuation token;
+     * an even run represents literal slashes and leaves that token active.
+     */
+    function escaped(line: string, offset: number): boolean;
+}

package/lib/adapters/markdown/EvidenceMarkdownSyntax.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceMarkdownSyntax = 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 EvidenceMarkdownSyntax;
+(function (EvidenceMarkdownSyntax) {
+    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",
+    ];
+    /**
+     * Recognizes a CommonMark fenced-code boundary on one source line.
+     *
+     * Up to three leading spaces are allowed. The returned marker, run length,
+     * and remainder let the scanner apply the opening and closing rules without
+     * discarding the line's original spelling.
+     */
+    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 };
+    }
+    EvidenceMarkdownSyntax.fence = fence;
+    /**
+     * Parses one supported ATX heading and its stable anchor identity.
+     *
+     * Explicit `{#anchor}` suffixes win over generated slugs. Unsupported depth,
+     * indentation, or missing marker separation leaves the line as ordinary
+     * prose.
+     */
+    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) };
+    }
+    EvidenceMarkdownSyntax.heading = heading;
+    /**
+     * Derives Evidence's deterministic anchor for an unanchored heading title.
+     *
+     * Letters, numbers, and underscores remain significant; punctuation and
+     * whitespace collapse only into the hyphen separators admitted by this
+     * adapter.
+     */
+    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(/-$/, "");
+    }
+    EvidenceMarkdownSyntax.slug = slug;
+    /**
+     * Finds a supported Evidence marker after Markdown container prefixes.
+     *
+     * The marker must occupy the complete line or be followed by whitespace, so a
+     * longer prose token cannot be misreported as an unreadable annotation.
+     */
+    function annotation(line) {
+        const content = lineContent(line);
+        return markers.find((marker) => content === marker ||
+            content.startsWith(marker + " ") ||
+            content.startsWith(marker + "\t"));
+    }
+    EvidenceMarkdownSyntax.annotation = annotation;
+    /**
+     * Removes repeated blockquote and list prefixes from one annotation line.
+     *
+     * Tag recognition consumes this logical content while source ranges continue
+     * to use the unchanged physical line owned by the scanner.
+     */
+    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;
+    }
+    EvidenceMarkdownSyntax.lineContent = lineContent;
+    /**
+     * Reports whether one physical line belongs to an indented code block.
+     *
+     * Four spaces or one leading tab make headings and annotation syntax inert at
+     * the top-level Markdown boundary supported by this scanner.
+     */
+    function indentedCode(line) {
+        return line.startsWith("    ") || line.startsWith("\t");
+    }
+    EvidenceMarkdownSyntax.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;
+    }
+    EvidenceMarkdownSyntax.inlineCode = inlineCode;
+    /**
+     * Detects whitespace that prevents a path from forming one target token.
+     *
+     * Markdown public addresses preserve literal path spelling, so callers reject
+     * any Unicode whitespace instead of silently escaping or normalizing it.
+     */
+    function hasWhitespace(value) {
+        for (const character of value)
+            if (character.trim() === "")
+                return true;
+        return false;
+    }
+    EvidenceMarkdownSyntax.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.`);
+        }
+    }
+    EvidenceMarkdownSyntax.symbol = symbol;
+    /**
+     * Measures one supported Markdown list prefix at the start of logical text.
+     *
+     * Annotation parsing removes bullet and ordered-list containers repeatedly;
+     * zero means the current text begins with neither supported form.
+     */
+    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;
+    }
+    /**
+     * Measures one contiguous backtick run from its opening column.
+     *
+     * Inline spans close only with a run of the same length, so the caller uses
+     * this value both for comparison and for advancing beyond a delimiter.
+     */
+    function delimiterLength(line, opening) {
+        let cursor = opening;
+        while (line[cursor] === "`")
+            ++cursor;
+        return cursor - opening;
+    }
+    /**
+     * Reports whether Markdown backslash escaping neutralizes a token boundary.
+     *
+     * An odd immediately preceding slash run escapes the next punctuation token;
+     * an even run represents literal slashes and leaves that token active.
+     */
+    function escaped(line, offset) {
+        let slashes = 0;
+        for (let index = offset - 1; index >= 0 && line[index] === "\\"; --index)
+            ++slashes;
+        return slashes % 2 === 1;
+    }
+    EvidenceMarkdownSyntax.escaped = escaped;
+})(EvidenceMarkdownSyntax || (exports.EvidenceMarkdownSyntax = EvidenceMarkdownSyntax = {}));

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

@@ -0,0 +1,18 @@
+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 EvidenceMarkdownTarget {
+    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/EvidenceMarkdownTarget.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceMarkdownTarget = 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 EvidenceMarkdownTarget;
+(function (EvidenceMarkdownTarget) {
+    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)],
+        };
+    }
+    EvidenceMarkdownTarget.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;
+    }
+    EvidenceMarkdownTarget.normalize = normalize;
+})(EvidenceMarkdownTarget || (exports.EvidenceMarkdownTarget = EvidenceMarkdownTarget = {}));

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

@@ -0,0 +1,33 @@
+/**
+ * One closed HTML comment accepted as Markdown documentation.
+ *
+ * Offsets and lines let attachment rules distinguish adjacent documentation
+ * from comments that belong to fenced content or another structural region.
+ */
+export interface IEvidenceMarkdownComment {
+    /**
+     * Marks the UTF-16 start offset of the complete HTML comment.
+     *
+     * The scanner uses this offset to preserve the carrier's original source
+     * range.
+     */
+    start: number;
+    /**
+     * Marks the exclusive UTF-16 end offset of the complete HTML comment.
+     *
+     * Together with `start`, this bounds the full delimiter-inclusive carrier.
+     */
+    end: number;
+    /**
+     * Identifies the zero-based line containing the opening delimiter.
+     *
+     * Attachment classification begins at this physical source line.
+     */
+    startLine: number;
+    /**
+     * Identifies the zero-based line containing the closing delimiter.
+     *
+     * Multi-line comments remain one carrier through this line.
+     */
+    endLine: number;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * One valid Markdown fence delimiter after its allowed indentation.
+ *
+ * Fence records prevent heading and comment-like text inside examples from
+ * becoming public Markdown structure or annotation hosts.
+ */
+export interface IEvidenceMarkdownFence {
+    /**
+     * Stores the fence character shared by a matching opener and closer.
+     *
+     * Markdown requires matching backtick or tilde fence families.
+     */
+    marker: "`" | "~";
+    /**
+     * Stores the number of consecutive marker characters in the delimiter.
+     *
+     * A closing fence must be at least this long to close the example region.
+     */
+    length: number;
+    /**
+     * Retains remaining delimiter text used to validate closing fences.
+     *
+     * Nonblank suffixes prevent a fence-like line from closing the region.
+     */
+    remainder: string;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * One ATX heading and its public anchor candidate.
+ *
+ * The scanner keeps normalized heading data separate from source positions so
+ * hierarchy and duplicate-anchor handling can decide public unit ownership.
+ */
+export interface IEvidenceMarkdownHeading {
+    /**
+     * Stores the ATX depth used to establish structural containment.
+     *
+     * Only supported depths can create nested public Markdown units.
+     */
+    level: number;
+    /**
+     * Stores visible heading text after marker normalization.
+     *
+     * The adapter exposes this text as the human-readable unit name.
+     */
+    title: string;
+    /**
+     * Stores the candidate anchor before duplicate disambiguation.
+     *
+     * Later materialization uses it to form a stable public address.
+     */
+    anchor: string;
+}

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

@@ -1,15 +1,115 @@
-import { MatlabAdapter } from "./MatlabAdapter";
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
 /**
- * Extracts textual MATLAB classes and primary functions with class-folder ownership.
+ * Extracts MATLAB public units after resolving file and 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.
+ * 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 EvidenceMatlabAdapter extends MatlabAdapter {
+export declare class EvidenceMatlabAdapter implements IEvidenceAdapter<"matlab"> {
+    /**
+     * Artifact discriminator selecting MATLAB source interpretation.
+     *
+     * It disambiguates .m sources from other languages that accept the same
+     * suffix.
+     */
+    get 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;
 }