@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/matlab/EvidenceMatlabFileScanner.js

@@ -0,0 +1,467 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceMatlabFileScanner = void 0;
+const node_path_1 = require("node:path");
+const EvidenceSourceText_1 = require("../../internal/EvidenceSourceText");
+/**
+ * Extracts declared MATLAB surfaces without evaluating application code.
+ *
+ * The scanner keeps class-folder facts, external signatures, and property
+ * accessors separate because their public owner may be established in another
+ * file.
+ */
+class EvidenceMatlabFileScanner {
+    session;
+    source;
+    /**
+     * Serializable declarations including private ownership boundaries.
+     *
+     * `scan` returns this ordered collection to the adapter, which reconciles
+     * public visibility and external owners before materializing Evidence units.
+     */
+    declarations = [];
+    /**
+     * Language-defined help carriers eligible for later attachment.
+     *
+     * The scanner records only placements MATLAB defines as help, allowing the
+     * adapter to reject annotation-looking text at unsupported positions.
+     */
+    documentation = [];
+    /**
+     * Surface failures retained in incomplete inventories.
+     *
+     * Unsupported dynamic or ambiguous constructs append diagnostics here so a
+     * scan cannot silently shrink the graph population into a passing result.
+     */
+    diagnostics = [];
+    /**
+     * Physical path normalized independently of the host operating system.
+     *
+     * Ownership and package-folder lookup use this slash-normalized path so
+     * MATLAB identities remain stable across Windows and POSIX hosts.
+     */
+    file;
+    /**
+     * Package-folder identity segments extracted from the physical path.
+     *
+     * Declared names include these `+` folder segments when the scanner
+     * constructs a MATLAB public address for a class, function, or member.
+     */
+    packages;
+    /**
+     * Original UTF-16 source mapper for this source snapshot.
+     *
+     * Scanner ranges are translated through this object so sites and diagnostics
+     * use the shared one-based coordinate contract for the original content.
+     */
+    text;
+    /**
+     * Borrows a live syntax tree only during extraction.
+     *
+     * The constructor normalizes the source path and derives package segments
+     * once, so later ownership reconciliation has platform-independent physical
+     * identity.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+        this.file = source.physicalPath.replaceAll("\\", "/");
+        this.packages = this.file
+            .split("/")
+            .filter((part) => part.startsWith("+"))
+            .map((part) => part.slice(1));
+        this.text = new EvidenceSourceText_1.EvidenceSourceText(source.content);
+    }
+    /**
+     * Selects the primary declaration and recognizes dynamic-source boundaries.
+     *
+     * MATLAB file layout determines ownership, so unsupported leading forms
+     * become diagnostics instead of being skipped and shrinking the public
+     * population.
+     */
+    scan() {
+        const nodes = this.session.root.namedChildren.filter((node) => node.type !== "comment" && node.type !== "line_continuation");
+        const primary = nodes[0];
+        if (primary?.type === "class_definition") {
+            const owner = this.add(primary, primary.childForFieldName("name"), "type", undefined, true);
+            if (owner !== undefined) {
+                this.attributes(primary);
+                this.filename(owner, primary);
+                const bases = primary.namedChildren.find((node) => node.type === "superclasses");
+                if (bases !== undefined &&
+                    bases
+                        .descendantsOfType("property_name")
+                        .some((node) => node.text === "dynamicprops"))
+                    this.problem("dynamic-surface", "A dynamicprops superclass permits runtime-created properties.", bases);
+                for (const block of primary.namedChildren) {
+                    if (["properties", "methods", "enumeration", "events"].includes(block.type))
+                        this.members(block, owner);
+                    else if (![
+                        "identifier",
+                        "attributes",
+                        "superclasses",
+                        "comment",
+                        "line_continuation",
+                    ].includes(block.type))
+                        this.problem("source-form", `Unsupported class declaration form '${block.type}'.`, block);
+                }
+            }
+        }
+        else if (primary?.type === "function_definition") {
+            const ownerFolder = node_path_1.posix.basename(node_path_1.posix.dirname(this.file));
+            const declaration = this.add(primary, primary.childForFieldName("name"), "function", undefined, true);
+            if (declaration !== undefined) {
+                this.filename(declaration, primary);
+                if (ownerFolder.startsWith("@")) {
+                    declaration.externalOwner = node_path_1.posix.join(node_path_1.posix.dirname(this.file), `${ownerFolder.slice(1)}.m`);
+                }
+            }
+        }
+        else if (primary !== undefined)
+            this.problem("script", "Executable script files have no statically declared primary function surface.", primary);
+        for (const node of nodes.slice(1))
+            if (node.type !== "function_definition")
+                this.problem("source-form", "Only file-local functions may follow a primary declaration.", node);
+        for (const node of this.session.root.descendantsOfType([
+            "function_call",
+            "command",
+            "handle_operator",
+        ])) {
+            const name = node.childForFieldName("name")?.text ??
+                node.namedChildren[0]?.text ??
+                "";
+            if (node.type === "command" && name === "endfunction")
+                this.problem("octave", "Octave endfunction is outside configured MATLAB syntax.", node);
+            const argumentsNode = node.namedChildren.find((child) => child.type === "arguments");
+            const legacyClass = name === "class" &&
+                (node.type === "command"
+                    ? node.namedChildren.filter((child) => child.type === "command_argument").length > 1
+                    : argumentsNode !== undefined &&
+                        argumentsNode.namedChildren.length > 1);
+            if ([
+                "addprop",
+                "addpath",
+                "rmpath",
+                "path",
+                "eval",
+                "evalin",
+                "assignin",
+                "schema",
+                "feval",
+                "str2func",
+            ].includes(name) ||
+                name.endsWith(".addprop") ||
+                legacyClass)
+                this.problem("dynamic-surface", `Call '${name}' can alter or conceal the declared surface and requires runtime analysis.`, node);
+        }
+        for (const node of this.session.root.descendantsOfType("function_definition"))
+            if (node.children.some((child) => child.text === "endfunction"))
+                this.problem("octave", "Octave endfunction is outside configured MATLAB syntax.", node);
+        return {
+            source: this.source,
+            declarations: this.declarations,
+            documentation: this.documentation,
+            diagnostics: this.diagnostics,
+            complete: this.diagnostics.length === 0,
+        };
+    }
+    /**
+     * Maps explicit class members and independent read/write visibility.
+     *
+     * MATLAB property access can make either accessor public, so this phase
+     * records the combined public surface without treating a private accessor as
+     * a new unit.
+     */
+    members(block, owner) {
+        const attributes = this.attributes(block);
+        const access = attributes.get("Access") ?? "public";
+        const getPublic = (attributes.get("GetAccess") ?? access) === "public";
+        const setPublic = (attributes.get("SetAccess") ?? access) === "public";
+        const eventPublic = (attributes.get("ListenAccess") ?? access) === "public" ||
+            (attributes.get("NotifyAccess") ?? access) === "public";
+        for (const node of block.namedChildren) {
+            if (["attributes", "comment", "line_continuation"].includes(node.type))
+                continue;
+            const method = node.type === "function_definition" ||
+                node.type === "function_signature";
+            const property = node.type === "property" ||
+                node.type === "enum" ||
+                (block.type === "events" && node.type === "identifier");
+            if (!method && !property) {
+                this.problem("source-form", `Unsupported member form '${node.type}'.`, node);
+                continue;
+            }
+            const accessor = node.children.find((child) => child.text === "get." || child.text === "set.")?.text;
+            const name = node.childForFieldName("name") ??
+                (node.type === "identifier" ? node : (node.namedChildren[0] ?? null));
+            const declaration = this.add(node, name, method && accessor === undefined ? "function" : "property", owner, owner.public &&
+                (method
+                    ? access === "public"
+                    : block.type === "properties"
+                        ? getPublic || setPublic
+                        : block.type === "events"
+                            ? eventPublic
+                            : true));
+            if (declaration === undefined)
+                continue;
+            const attributesNode = block.namedChildren.find((child) => child.type === "attributes");
+            if (attributesNode !== undefined) {
+                const attributesRange = this.session.range(attributesNode);
+                declaration.site.range = {
+                    start: attributesRange.start,
+                    end: declaration.site.range.end,
+                };
+                declaration.site.content.unshift(attributesRange);
+            }
+            if (node.type === "property") {
+                declaration.getPublic = getPublic;
+                declaration.setPublic = setPublic;
+            }
+            if (accessor !== undefined) {
+                declaration.accessor = accessor === "get." ? "get" : "set";
+            }
+            if (node.type === "function_signature" &&
+                attributes.get("Abstract") !== "true") {
+                declaration.implementation = node_path_1.posix.join(node_path_1.posix.dirname(this.file), `${declaration.name}.m`);
+                if (!node_path_1.posix.basename(node_path_1.posix.dirname(this.file)).startsWith("@"))
+                    this.problem("external-method", "Nonabstract method prototypes require a classdef file in its @Class folder and selected method files.", node);
+            }
+        }
+    }
+    /**
+     * Reads known static class metadata and rejects unknown surface-changing
+     * attributes.
+     *
+     * Attribute interpretation controls visibility and ownership; unsupported
+     * attributes become incomplete-analysis diagnostics instead of guessed
+     * policy.
+     */
+    attributes(node) {
+        const result = new Map();
+        const attributes = node.namedChildren.find((child) => child.type === "attributes");
+        for (const attribute of attributes?.namedChildren ?? []) {
+            const nameNode = attribute.namedChildren[0];
+            const name = nameNode?.type === "not_operator"
+                ? nameNode.namedChildren[0]?.text
+                : nameNode?.text;
+            if (name === undefined)
+                continue;
+            const valueNode = attribute.namedChildren[1];
+            const value = valueNode === undefined
+                ? nameNode?.type === "not_operator"
+                    ? "false"
+                    : "true"
+                : valueNode.text.replace(/^['"]|['"]$/gu, "");
+            if (![
+                "Access",
+                "GetAccess",
+                "SetAccess",
+                "ListenAccess",
+                "NotifyAccess",
+                "Static",
+                "Constant",
+                "Dependent",
+                "Abstract",
+                "Hidden",
+                "Sealed",
+                "Transient",
+                "NonCopyable",
+                "AbortSet",
+                "GetObservable",
+                "SetObservable",
+                "ConstructOnLoad",
+                "HandleCompatible",
+                "InferiorClasses",
+                "AllowedSubclasses",
+                "RestrictsSubclassing",
+            ].includes(name))
+                this.problem("attribute", `Attribute '${name}' has no established static visibility semantics.`, attribute);
+            if (/Access$/u.test(name) &&
+                !["public", "private", "protected", "immutable"].includes(value)) {
+                const friends = value.startsWith("{") && value.endsWith("}")
+                    ? value
+                        .slice(1, -1)
+                        .trim()
+                        .split(/[,\s]+/u)
+                    : [value];
+                if (!friends.every((friend) => /^\?[A-Za-z][A-Za-z0-9_.]*$/u.test(friend)))
+                    this.problem("attribute", `Access attribute '${name}' is not a static access designation.`, attribute);
+            }
+            else if (!/Access$/u.test(name) &&
+                !["InferiorClasses", "AllowedSubclasses"].includes(name) &&
+                !["true", "false"].includes(value))
+                this.problem("attribute", `Attribute '${name}' requires a literal logical value.`, attribute);
+            result.set(name, value);
+        }
+        return result;
+    }
+    /**
+     * Creates a declaration site before attaching the appropriate MATLAB help
+     * placement.
+     *
+     * Separating site creation from documentation attachment keeps physical
+     * content ownership intact when help belongs after a signature or beside a
+     * member.
+     */
+    add(node, nameNode, symbol, owner, visible) {
+        if (nameNode === null || !/^[A-Za-z][A-Za-z0-9_]*$/u.test(nameNode.text)) {
+            this.problem("declaration-name", "A declaration has no supported literal MATLAB identifier.", node);
+            return undefined;
+        }
+        const name = nameNode.text;
+        const address = [...(owner?.address ?? this.packages), name];
+        const range = this.session.range(node);
+        const id = `matlab:${this.source.id}:site:${node.startIndex}:${node.endIndex}`;
+        const declaration = {
+            id,
+            name,
+            symbol,
+            identity: address,
+            address,
+            anchor: this.file,
+            public: visible && !this.file.split("/").includes("private"),
+            site: { id, file: this.source.physicalPath, range, content: [range] },
+            ...(owner === undefined ? {} : { ownerDeclarationId: owner.id }),
+        };
+        this.declarations.push(declaration);
+        this.attach(node, declaration);
+        return declaration;
+    }
+    /**
+     * Rejects source names that depend on MATLAB runtime name shadowing.
+     *
+     * The static inventory cannot determine which shadowed function MATLAB will
+     * invoke, so the scanner preserves this ambiguity as an actionable
+     * diagnostic.
+     */
+    filename(declaration, node) {
+        if (node_path_1.posix.basename(this.file, ".m") !== declaration.name)
+            this.problem("filename", "The primary declaration name must match its selected .m file name; runtime name shadowing is not resolved.", node);
+        const folder = node_path_1.posix.basename(node_path_1.posix.dirname(this.file));
+        if (declaration.symbol === "type" &&
+            folder.startsWith("@") &&
+            folder.slice(1) !== declaration.name)
+            this.problem("class-folder", "The classdef name must match its @Class folder.", node);
+    }
+    /**
+     * Attaches post-signature class/function help and preceding-or-inline member
+     * help.
+     *
+     * MATLAB placement rules differ by declaration form; this method records only
+     * eligible carriers and leaves unsupported nearby comments visible for
+     * diagnostics.
+     */
+    attach(node, declaration) {
+        const after = node.type === "class_definition" || node.type === "function_definition";
+        let comments = [];
+        if (after) {
+            const name = node.childForFieldName("name");
+            const lastHeader = node.namedChildren
+                .filter((child) => [
+                "identifier",
+                "function_output",
+                "function_arguments",
+                "attributes",
+                "superclasses",
+            ].includes(child.type) &&
+                child.startIndex <=
+                    (node.namedChildren.find((child) => child.type === "comment" || child.type === "block")?.startIndex ?? node.endIndex))
+                .at(-1) ?? name;
+            if (lastHeader !== null && lastHeader !== undefined) {
+                const candidate = node.namedChildren.find((child) => child.type === "comment" && child.startIndex >= lastHeader.endIndex);
+                if (candidate !== undefined &&
+                    /^[ \t]*[\r\n]+[ \t]*$/u.test(this.source.content.slice(lastHeader.endIndex, candidate.startIndex)))
+                    comments = [candidate];
+            }
+        }
+        else {
+            const previous = node.previousNamedSibling;
+            if (previous?.type === "comment" &&
+                !previous.text.startsWith("%{") &&
+                /^[ \t]*\r?\n[ \t]*$/u.test(this.source.content.slice(previous.endIndex, node.startIndex)) &&
+                this.lineStart(previous)) {
+                comments = [previous];
+                let before = previous.previousNamedSibling;
+                while (before?.type === "comment" &&
+                    !before.text.startsWith("%{") &&
+                    this.lineStart(before) &&
+                    /^[ \t]*\r?\n[ \t]*$/u.test(this.source.content.slice(before.endIndex, comments[0]?.startIndex))) {
+                    comments.unshift(before);
+                    before = before.previousNamedSibling;
+                }
+            }
+            else {
+                const next = node.nextNamedSibling;
+                if (next?.type === "comment" &&
+                    /^[ \t]*$/u.test(this.source.content.slice(node.endIndex, next.startIndex)))
+                    comments = [next];
+            }
+        }
+        if (comments.length === 0)
+            return;
+        let last = comments.at(-1);
+        if (after)
+            while (last?.nextNamedSibling?.type === "comment" &&
+                /^[ \t]*\r?\n[ \t]*$/u.test(this.source.content.slice(last.endIndex, last.nextNamedSibling.startIndex))) {
+                comments.push(last.nextNamedSibling);
+                last = comments.at(-1);
+            }
+        const first = comments[0];
+        if (first === undefined || last === undefined)
+            return;
+        // MATLAB help uses percent lines; block comments remain ordinary inert source.
+        if (first.text.startsWith("%{"))
+            return;
+        else {
+            const blockIndex = comments.findIndex((comment) => comment.text.startsWith("%{"));
+            if (blockIndex > 0)
+                last = comments[blockIndex - 1] ?? first;
+        }
+        const range = this.text.range(first.startIndex, last.endIndex);
+        this.documentation.push({
+            id: `${declaration.id}:documentation:${first.startIndex}`,
+            range,
+            syntax: {
+                opening: "%",
+                closing: "",
+                linePrefix: "%",
+                tagBoundaries: true,
+                allowWithdrawal: true,
+            },
+            attachments: [
+                { declarationId: declaration.id, siteId: declaration.site.id },
+            ],
+        });
+    }
+    /**
+     * Distinguishes standalone help lines from a preceding property's inline
+     * help.
+     *
+     * Property declarations can carry MATLAB help on the same physical line, so
+     * attachment needs this boundary before it creates a documentation range.
+     */
+    lineStart(node) {
+        const start = this.source.content.lastIndexOf("\n", node.startIndex - 1) + 1;
+        return /^[ \t]*$/u.test(this.source.content.slice(start, node.startIndex));
+    }
+    /**
+     * Preserves unsupported source constructs as actionable incomplete analysis.
+     *
+     * Each diagnostic records the source range and failure code, ensuring callers
+     * see a failed population rather than an inventory missing uncertain
+     * members.
+     */
+    problem(code, message, node) {
+        this.diagnostics.push({
+            code: `matlab-${code}`,
+            severity: "error",
+            message,
+            repair: "Select static MATLAB classdef/function sources and their ownership files, or implement the unsupported construct before checking coverage.",
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.EvidenceMatlabFileScanner = EvidenceMatlabFileScanner;

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

@@ -0,0 +1,19 @@
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceMatlabFileAnalysis } from "./IEvidenceMatlabFileAnalysis";
+/**
+ * Reconciles selected class folders, external implementations, and property
+ * accessors.
+ *
+ * MATLAB distributes one public class surface across files, so semantic
+ * ownership must be proven from class-folder paths before units and annotation
+ * hosts exist.
+ */
+export declare namespace EvidenceMatlabOwnership {
+    /**
+     * Resolves all ownership before any public identities or hosts are published.
+     *
+     * This order lets a missing external implementation remain an observable
+     * dependency and prevents an accessor from becoming a second property unit.
+     */
+    function resolve(analyses: IEvidenceMatlabFileAnalysis[], inventory: IEvidenceInventory): void;
+}

package/lib/adapters/matlab/EvidenceMatlabOwnership.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceMatlabOwnership = void 0;
+const node_path_1 = require("node:path");
+/**
+ * Reconciles selected class folders, external implementations, and property
+ * accessors.
+ *
+ * MATLAB distributes one public class surface across files, so semantic
+ * ownership must be proven from class-folder paths before units and annotation
+ * hosts exist.
+ */
+var EvidenceMatlabOwnership;
+(function (EvidenceMatlabOwnership) {
+    /**
+     * Resolves all ownership before any public identities or hosts are published.
+     *
+     * This order lets a missing external implementation remain an observable
+     * dependency and prevents an accessor from becoming a second property unit.
+     */
+    function resolve(analyses, inventory) {
+        const files = new Map(analyses.map((analysis) => [
+            analysis.source.physicalPath.replaceAll("\\", "/"),
+            analysis,
+        ]));
+        for (const analysis of analyses) {
+            const directory = node_path_1.posix.dirname(analysis.source.physicalPath.replaceAll("\\", "/"));
+            if (node_path_1.posix.basename(directory).startsWith("@"))
+                inventory.dependencies.push({ path: directory, recursive: true });
+            for (const declaration of analysis.declarations) {
+                if (declaration.externalOwner === undefined)
+                    continue;
+                inventory.dependencies.push({
+                    path: declaration.externalOwner,
+                    recursive: false,
+                });
+                const ownerAnalysis = files.get(declaration.externalOwner);
+                const owner = ownerAnalysis === undefined
+                    ? undefined
+                    : ownerAnalysis.declarations.find((candidate) => candidate.symbol === "type" &&
+                        candidate.ownerDeclarationId === undefined);
+                if (owner === undefined || ownerAnalysis === undefined) {
+                    problem(analysis, declaration, "class-folder", "An external method requires its selected @Class/Class.m classdef; legacy classes are not inferred.");
+                    declaration.public = false;
+                    continue;
+                }
+                const prototype = ownerAnalysis.declarations.find((candidate) => candidate.ownerDeclarationId === owner.id &&
+                    candidate.name === declaration.name &&
+                    candidate.symbol === "function");
+                if (prototype !== undefined && prototype.implementation === undefined)
+                    problem(analysis, declaration, "method-conflict", "An external method duplicates an inline or abstract class method.");
+                declaration.ownerDeclarationId = owner.id;
+                declaration.anchor = owner.anchor;
+                declaration.address = [...owner.address, declaration.name];
+                declaration.identity = declaration.address;
+                declaration.public &&= owner.public && (prototype?.public ?? true);
+                declaration.publicFiles = ownerAnalysis.source.addresses.map((address) => address.absolute);
+                inventory.dependencies.push({
+                    path: node_path_1.posix.dirname(declaration.externalOwner),
+                    recursive: true,
+                });
+            }
+            for (const declaration of analysis.declarations) {
+                if (declaration.implementation === undefined)
+                    continue;
+                inventory.dependencies.push({
+                    path: declaration.implementation,
+                    recursive: false,
+                });
+                const externalAnalysis = files.get(declaration.implementation);
+                const external = externalAnalysis === undefined
+                    ? undefined
+                    : externalAnalysis.declarations.find((candidate) => candidate.externalOwner === declaration.anchor &&
+                        candidate.name === declaration.name);
+                if (external === undefined)
+                    problem(analysis, declaration, "external-method", "A nonabstract external method prototype has no selected implementation; include its @Class method file.");
+            }
+        }
+        for (const analysis of analyses)
+            for (const declaration of analysis.declarations) {
+                if (declaration.accessor === undefined)
+                    continue;
+                const property = analyses
+                    .flatMap((item) => item.declarations)
+                    .find((candidate) => candidate.accessor === undefined &&
+                    candidate.getPublic !== undefined &&
+                    candidate.anchor === declaration.anchor &&
+                    candidate.ownerDeclarationId === declaration.ownerDeclarationId &&
+                    candidate.name === declaration.name);
+                if (property === undefined) {
+                    problem(analysis, declaration, "accessor", "A property accessor has no declared property in its selected class.");
+                    declaration.public = false;
+                }
+                else {
+                    declaration.public =
+                        property.public &&
+                            (declaration.accessor === "get"
+                                ? property.getPublic === true
+                                : property.setPublic === true);
+                }
+            }
+        const seen = new Map();
+        for (const analysis of analyses)
+            for (const declaration of analysis.declarations) {
+                if (!declaration.public)
+                    continue;
+                const identity = JSON.stringify([
+                    declaration.anchor,
+                    declaration.symbol,
+                    declaration.identity,
+                    declaration.accessor ??
+                        (declaration.implementation === undefined
+                            ? "definition"
+                            : "prototype"),
+                ]);
+                if (seen.has(identity))
+                    problem(analysis, declaration, "declaration-conflict", "Two declarations expose the same MATLAB owner and name.");
+                seen.set(identity, declaration);
+            }
+    }
+    EvidenceMatlabOwnership.resolve = resolve;
+    /**
+     * Records unresolved source ownership without shrinking a passing population.
+     *
+     * The ownership pass retains this diagnostic when class-folder or external
+     * declarations cannot be paired, preserving an incomplete result for
+     * recovery.
+     */
+    function problem(analysis, declaration, code, message) {
+        analysis.complete = false;
+        analysis.diagnostics.push({
+            code: `matlab-${code}`,
+            severity: "error",
+            message,
+            repair: "Select a unique classdef and its external implementations, or correct the conflicting declaration.",
+            location: {
+                file: analysis.source.physicalPath,
+                range: declaration.site.range,
+            },
+        });
+    }
+})(EvidenceMatlabOwnership || (exports.EvidenceMatlabOwnership = EvidenceMatlabOwnership = {}));