@wrtnlabs/evidence 0.0.0

package/lib/programmers/EvidenceTagProgrammer.d.ts

@@ -0,0 +1,25 @@
+import type { IEvidenceTagContext } from "../contexts/IEvidenceTagContext";
+import type { IEvidenceTagParseResult } from "../structures/IEvidenceTagParseResult";
+/**
+ * Parses Evidence annotations from documentation already mapped to a source host.
+ *
+ * Adapters own comment syntax and provide a normalized documentation map; this
+ * namespace owns only Evidence tag semantics. Its mutable context carries a
+ * pending multiline tag, fenced-code state, and parse result so every emitted
+ * annotation can retain coordinates in the original source file.
+ *
+ * @example
+ *   const result = EvidenceTagProgrammer.parse(context);
+ *   // result.declarations contains valid @evidence and @link annotations.
+ */
+export declare namespace EvidenceTagProgrammer {
+    /**
+     * Parses valid Evidence tags and diagnostics from one mapped documentation block.
+     *
+     * The function consumes no text outside {@link IEvidenceTagContext.documentation}.
+     * It preserves multiline tag bodies, ignores apparent tags inside fenced code,
+     * and flushes a pending annotation at every boundary that makes continuation
+     * impossible. Invalid tags become diagnostics rather than aborting sibling tags.
+     */
+    function parse(context: IEvidenceTagContext): IEvidenceTagParseResult;
+}

package/lib/programmers/EvidenceTagProgrammer.js

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceTagProgrammer = void 0;
+const EvidenceTargetBody_1 = require("../internal/EvidenceTargetBody");
+/**
+ * Parses Evidence annotations from documentation already mapped to a source host.
+ *
+ * Adapters own comment syntax and provide a normalized documentation map; this
+ * namespace owns only Evidence tag semantics. Its mutable context carries a
+ * pending multiline tag, fenced-code state, and parse result so every emitted
+ * annotation can retain coordinates in the original source file.
+ *
+ * @example
+ *   const result = EvidenceTagProgrammer.parse(context);
+ *   // result.declarations contains valid @evidence and @link annotations.
+ */
+var EvidenceTagProgrammer;
+(function (EvidenceTagProgrammer) {
+    /**
+     * Parses valid Evidence tags and diagnostics from one mapped documentation block.
+     *
+     * The function consumes no text outside {@link IEvidenceTagContext.documentation}.
+     * It preserves multiline tag bodies, ignores apparent tags inside fenced code,
+     * and flushes a pending annotation at every boundary that makes continuation
+     * impossible. Invalid tags become diagnostics rather than aborting sibling tags.
+     */
+    function parse(context) {
+        validate(context);
+        let cursor = 0;
+        for (const rawLine of context.documentation.text.split("\n")) {
+            const line = rawLine.trim();
+            // Coordinates must point at trimmed annotation text while cursor advances
+            // across the untrimmed mapped documentation, including blank-line bytes.
+            const start = cursor + rawLine.indexOf(line);
+            const end = start + line.length;
+            cursor += rawLine.length + 1;
+            const delimiter = /^(`{3,}|~{3,})(.*)$/.exec(line);
+            if (delimiter !== null) {
+                const marker = delimiter[1] ?? "";
+                // Closing fences must use the opening marker character and at least its
+                // length; a shorter marker remains literal code inside the fenced block.
+                if (context.fence === "") {
+                    context.fence = marker[0] ?? "";
+                    context.fenceLength = marker.length;
+                }
+                else if (marker[0] === context.fence &&
+                    marker.length >= context.fenceLength &&
+                    (delimiter[2] ?? "").trim() === "")
+                    context.fence = "";
+                if (context.pending !== undefined) {
+                    context.pending.body += "\n" + line;
+                    context.pending.end = end;
+                }
+                continue;
+            }
+            if (context.fence !== "") {
+                if (context.pending !== undefined) {
+                    context.pending.body += "\n" + line;
+                    context.pending.end = end;
+                }
+                continue;
+            }
+            const marker = /^@(evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link)(?:[ \t]|$)/.exec(line);
+            if (marker !== null) {
+                flush(context);
+                const kind = marker[1];
+                if (kind === "evidenceExcludeReview" ||
+                    kind === "evidenceReview" ||
+                    kind === "evidenceExclude" ||
+                    kind === "evidence" ||
+                    kind === "link")
+                    context.pending = {
+                        kind,
+                        body: line.slice(marker[0].length).trim(),
+                        start,
+                        end,
+                    };
+                continue;
+            }
+            const hidden = /^@(internal|hidden|ignore)(?:[ \t]|$)/.exec(line);
+            if (hidden !== null && context.documentation.allowWithdrawal) {
+                flush(context);
+                const tag = hidden[1];
+                if (context.host.attachment === "attached" &&
+                    (tag === "internal" || tag === "hidden" || tag === "ignore"))
+                    context.result.withdrawals.push({
+                        tag,
+                        location: location(context, start, end),
+                    });
+                continue;
+            }
+            if (line.startsWith("@") &&
+                (context.documentation.tagBoundaries ||
+                    context.pending?.kind === "evidenceReview" ||
+                    context.pending?.kind === "evidenceExcludeReview")) {
+                flush(context);
+                continue;
+            }
+            if (context.pending !== undefined) {
+                context.pending.body += "\n" + line;
+                context.pending.end = end;
+            }
+        }
+        flush(context);
+        return context.result;
+    }
+    EvidenceTagProgrammer.parse = parse;
+    /**
+     * Verifies that a documentation map belongs to its declared source host.
+     *
+     * Offset and end arrays must cover the normalized text exactly and remain
+     * monotonic inside the host range. The source lookup also validates that every
+     * retained boundary can be converted into a public line-and-column location.
+     * Violations are adapter bugs, so this function throws instead of producing a
+     * user-facing annotation diagnostic.
+     */
+    function validate(context) {
+        if (context.documentation.hostId !== context.host.id ||
+            context.documentation.offsets.length !==
+                context.documentation.text.length + 1 ||
+            context.documentation.ends.length !== context.documentation.text.length ||
+            !context.source.contains(context.host.range))
+            throw new Error("The documentation map does not belong to its host or text.");
+        let previous = context.host.range.start.offset;
+        for (const [index, offset] of context.documentation.offsets.entries()) {
+            if (offset < previous || offset > context.host.range.end.offset)
+                throw new Error("The documentation map escapes its source host.");
+            context.source.position(offset);
+            const end = context.documentation.ends[index] ?? offset;
+            if (end < offset || end > context.host.range.end.offset)
+                throw new Error("The documentation character escapes its source host.");
+            context.source.position(end);
+            previous = end;
+        }
+    }
+    /**
+     * Converts a half-open documentation-text span to an original source location.
+     *
+     * The documentation map can omit or transform syntax such as comment prefixes,
+     * so source offsets cannot be derived from character counts. The final character
+     * uses its mapped end boundary; an empty span uses its mapped start boundary.
+     */
+    function location(context, start, end) {
+        const from = context.documentation.offsets[start];
+        const until = end === start ? from : context.documentation.ends[end - 1];
+        if (from === undefined || until === undefined)
+            throw new Error("Missing documentation source boundary.");
+        return {
+            file: context.host.file,
+            range: context.source.range(from, until),
+        };
+    }
+    /**
+     * Appends a source-located tag diagnostic for the current host.
+     *
+     * Centralizing this projection guarantees parser errors carry the same severity
+     * and host identity as later graph diagnostics, while callers supply the
+     * actionable repair text appropriate to the failed tag rule.
+     */
+    function problem(context, code, message, repair, where) {
+        context.result.diagnostics.push({
+            code,
+            severity: "error",
+            message,
+            repair,
+            location: where,
+            hostId: context.host.id,
+        });
+    }
+    /**
+     * Finalizes the pending tag, appending an annotation or an explanatory diagnostic.
+     *
+     * Pending state is cleared before validation so a failing tag cannot be emitted
+     * again at a later boundary. Attachment, inline-link, target, review-fingerprint,
+     * and reason requirements are checked in that order because each later rule
+     * assumes the preceding source and target interpretation is valid.
+     */
+    function flush(context) {
+        if (context.pending === undefined)
+            return;
+        const tag = context.pending;
+        context.pending = undefined;
+        const where = location(context, tag.start, tag.end);
+        // Detached comments never provide evidence, even if their tag syntax is valid.
+        if (context.host.attachment !== "attached") {
+            problem(context, "unsupported-annotation-host", "The annotation has no eligible declaration host.", context.host.problem ??
+                "Attach the citation to documentation owned by the declaration that supplies the evidence, or remove it if stale.", where);
+            return;
+        }
+        if (/^\s*\{@link(?:code|plain)?\b/u.test(tag.body)) {
+            problem(context, "unsupported-inline-link", "Compiler import-scoped inline links are unavailable in standalone Evidence.", "Use an explicit target such as @evidence ../calculator.ts#add Implements the arithmetic contract.", where);
+            return;
+        }
+        const body = EvidenceTargetBody_1.EvidenceTargetBody.split(tag.body);
+        try {
+            EvidenceTargetBody_1.EvidenceTargetBody.check(body.target, tag.kind === "link");
+        }
+        catch (cause) {
+            problem(context, "malformed-target", "The annotation has a malformed target.", cause instanceof Error
+                ? cause.message
+                : "Use a valid artifact target or file-qualified accessor.", where);
+            return;
+        }
+        const id = JSON.stringify([
+            context.host.id,
+            context.documentation.offsets[tag.start],
+            tag.kind,
+        ]);
+        if (tag.kind === "evidenceReview" || tag.kind === "evidenceExcludeReview") {
+            let description = body.remainder;
+            let fingerprint;
+            if (description.startsWith("#")) {
+                const token = description.split(/\s/u)[0] ?? "";
+                const prose = description.slice(token.length).trim();
+                // A fingerprint is only consumed when it has the precise short-hash form;
+                // ordinary prose beginning with '#' remains part of the review description.
+                if (/^#[0-9a-f]{7}$/.test(token)) {
+                    fingerprint = token.slice(1);
+                    description = prose;
+                }
+                else if (prose === "") {
+                    problem(context, "malformed-fingerprint", "The review contains only an invalid fingerprint-like token.", "Write a seven-character lowercase hexadecimal fingerprint after '#', followed by a description of the review.", where);
+                    return;
+                }
+            }
+            if (description === "") {
+                problem(context, "missing-review-description", "The review does not explain what was checked.", "Describe the verification after the target and optional fingerprint.", where);
+                return;
+            }
+            context.result.reviews.push({
+                id,
+                hostId: context.host.id,
+                reviews: tag.kind === "evidenceReview" ? "evidence" : "evidenceExclude",
+                target: body.target,
+                description,
+                location: where,
+                ...(fingerprint === undefined ? {} : { fingerprint }),
+            });
+        }
+        else if (body.remainder === "")
+            problem(context, "missing-evidence-reason", "The acknowledgement does not state a reason.", "Explain how the host supplies the cited evidence or why the target does not apply.", where);
+        else
+            context.result.declarations.push({
+                id,
+                hostId: context.host.id,
+                kind: tag.kind === "evidenceExclude" ? "evidenceExclude" : "evidence",
+                target: body.target,
+                reason: body.remainder,
+                location: where,
+            });
+    }
+})(EvidenceTagProgrammer || (exports.EvidenceTagProgrammer = EvidenceTagProgrammer = {}));

package/lib/reporters/EvidenceGraphReporter.d.ts

@@ -0,0 +1,39 @@
+import type { IEvidenceGraphReport } from "../structures/IEvidenceGraphReport";
+import type { EvidenceGraphFormat } from "../typings/EvidenceGraphFormat";
+/**
+ * Serializes the authoritative graph report as JSON, Mermaid, or DOT.
+ *
+ * Visual formats escape authored labels before embedding them in their respective
+ * grammars. They are projections of an already evaluated graph and never change
+ * graph membership, coverage, or review resolution.
+ */
+export declare namespace EvidenceGraphReporter {
+    /**
+     * Chooses the requested graph serialization.
+     *
+     * JSON preserves the report object, while Mermaid and DOT encode its boundaries,
+     * nodes, evidence edges, and review edges for visualization tools.
+     */
+    function render(report: IEvidenceGraphReport, format: EvidenceGraphFormat): string;
+    /**
+     * Serializes the complete graph report as indented JSON.
+     *
+     * This format keeps stable identifiers and every exported property available to
+     * programmatic consumers without visual-format escaping.
+     */
+    function json(report: IEvidenceGraphReport): string;
+    /**
+     * Emits a Mermaid flowchart with one subgraph per configured boundary.
+     *
+     * Synthetic node names avoid treating semantic IDs as Mermaid syntax; labels
+     * carry the authored values after escaping text-sensitive characters.
+     */
+    function mermaid(report: IEvidenceGraphReport): string;
+    /**
+     * Emits a DOT directed graph with clusters for configuration boundaries.
+     *
+     * Evidence exclusion and review relations use distinct line styles so their
+     * meaning remains visible when a viewer does not expose edge metadata.
+     */
+    function dot(report: IEvidenceGraphReport): string;
+}

package/lib/reporters/EvidenceGraphReporter.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceGraphReporter = void 0;
+/**
+ * Serializes the authoritative graph report as JSON, Mermaid, or DOT.
+ *
+ * Visual formats escape authored labels before embedding them in their respective
+ * grammars. They are projections of an already evaluated graph and never change
+ * graph membership, coverage, or review resolution.
+ */
+var EvidenceGraphReporter;
+(function (EvidenceGraphReporter) {
+    /**
+     * Chooses the requested graph serialization.
+     *
+     * JSON preserves the report object, while Mermaid and DOT encode its boundaries,
+     * nodes, evidence edges, and review edges for visualization tools.
+     */
+    function render(report, format) {
+        if (format === "json")
+            return json(report);
+        return format === "mermaid" ? mermaid(report) : dot(report);
+    }
+    EvidenceGraphReporter.render = render;
+    /**
+     * Serializes the complete graph report as indented JSON.
+     *
+     * This format keeps stable identifiers and every exported property available to
+     * programmatic consumers without visual-format escaping.
+     */
+    function json(report) {
+        return JSON.stringify(report, null, 2) + "\n";
+    }
+    EvidenceGraphReporter.json = json;
+    /**
+     * Emits a Mermaid flowchart with one subgraph per configured boundary.
+     *
+     * Synthetic node names avoid treating semantic IDs as Mermaid syntax; labels
+     * carry the authored values after escaping text-sensitive characters.
+     */
+    function mermaid(report) {
+        const names = nodeNames(report.nodes);
+        const lines = ["flowchart LR"];
+        report.boundaries.forEach((entry, index) => {
+            lines.push(`  subgraph b${index}["${mermaidText(boundaryLabel(entry))}"]`);
+            for (const node of report.nodes.filter((candidate) => candidate.boundaryId === entry.id))
+                lines.push(`    ${requireNodeName(names, node.id)}["${mermaidText(nodeLabel(node))}"]`);
+            lines.push("  end");
+        });
+        for (const edge of report.edges)
+            for (const source of edge.sourceNodeIds)
+                lines.push(`  ${requireNodeName(names, source)} ${edge.kind === "evidence" ? "-->" : "-.->"}|${mermaidText(edgeLabel(edge))}| ${requireNodeName(names, edge.targetNodeId)}`);
+        for (const review of report.reviews)
+            for (const source of review.sourceNodeIds)
+                for (const target of review.targetNodeIds)
+                    lines.push(`  ${requireNodeName(names, source)} -.->|${mermaidText(reviewLabel(review))}| ${requireNodeName(names, target)}`);
+        return lines.join("\n") + "\n";
+    }
+    EvidenceGraphReporter.mermaid = mermaid;
+    /**
+     * Emits a DOT directed graph with clusters for configuration boundaries.
+     *
+     * Evidence exclusion and review relations use distinct line styles so their
+     * meaning remains visible when a viewer does not expose edge metadata.
+     */
+    function dot(report) {
+        const names = nodeNames(report.nodes);
+        const lines = ["digraph Evidence {", "  rankdir=LR;"];
+        report.boundaries.forEach((entry, index) => {
+            lines.push(`  subgraph cluster_${index} {`, `    label="${dotText(boundaryLabel(entry))}";`);
+            for (const node of report.nodes.filter((candidate) => candidate.boundaryId === entry.id))
+                lines.push(`    ${requireNodeName(names, node.id)} [label="${dotText(nodeLabel(node))}"];`);
+            lines.push("  }");
+        });
+        for (const edge of report.edges)
+            for (const source of edge.sourceNodeIds)
+                lines.push(`  ${requireNodeName(names, source)} -> ${requireNodeName(names, edge.targetNodeId)} [label="${dotText(edgeLabel(edge))}"${edge.kind === "evidenceExclude" ? ', style="dashed"' : ""}];`);
+        for (const review of report.reviews)
+            for (const source of review.sourceNodeIds)
+                for (const target of review.targetNodeIds)
+                    lines.push(`  ${requireNodeName(names, source)} -> ${requireNodeName(names, target)} [label="${dotText(reviewLabel(review))}", style="dotted"];`);
+        lines.push("}");
+        return lines.join("\n") + "\n";
+    }
+    EvidenceGraphReporter.dot = dot;
+})(EvidenceGraphReporter || (exports.EvidenceGraphReporter = EvidenceGraphReporter = {}));
+/**
+ * Assigns syntax-safe local names to graph nodes in report order.
+ *
+ * Exported node IDs may contain target punctuation, so formats refer to these
+ * generated names and reserve IDs for labels and lookup only.
+ */
+function nodeNames(nodes) {
+    return new Map(nodes.map((node, index) => [node.id, `n${index}`]));
+}
+/**
+ * Retrieves a generated node name and detects an inconsistent graph export.
+ *
+ * An edge without a listed endpoint is a report-construction failure, not an
+ * opportunity to emit invalid visualization syntax.
+ */
+function requireNodeName(names, id) {
+    const name = names.get(id);
+    if (name === undefined)
+        throw new Error(`Graph edge names missing node '${id}'.`);
+    return name;
+}
+/**
+ * Summarizes a claim/reference boundary and its resolved policy state.
+ *
+ * The label makes inactive and incomplete boundaries visible even when they have
+ * no ordinary evidence edges in the graph export.
+ */
+function boundaryLabel(boundary) {
+    const policies = [
+        boundary.policy.noEvidenceExclude ? "no-exclude" : undefined,
+        boundary.policy.uniqueEvidence ? "unique" : undefined,
+        boundary.policy.singleEvidencePerSymbol ? "single" : undefined,
+        boundary.policy.checklist ? "checklist" : undefined,
+        boundary.policy.requireReview ? "review" : undefined,
+    ].filter((value) => value !== undefined);
+    const status = !boundary.active
+        ? "inactive"
+        : boundary.complete
+            ? "complete"
+            : "incomplete";
+    return `claim[${boundary.claim.claim}] (${boundary.claim.type}) -> reference[${boundary.reference.reference ?? -1}] (${boundary.reference.type}); ${status}, ${boundary.policy.severity}${policies.length === 0 ? "" : `, ${policies.join(", ")}`}`;
+}
+/**
+ * Produces a concise label for a graph node.
+ *
+ * Hosts identify their physical source location; unit nodes identify their role,
+ * target, symbol, and selection or coverage state.
+ */
+function nodeLabel(node) {
+    if (node.role === "host")
+        return `host ${node.location.file}:${node.location.range?.start?.line ?? 1}`;
+    const state = node.missing
+        ? "missing"
+        : node.covered
+            ? "covered"
+            : node.selection;
+    return `${node.role} ${node.symbol} ${node.target} (${state})`;
+}
+/**
+ * Labels an acknowledgement edge with its tag kind and fingerprint.
+ *
+ * Fingerprints connect rendered edges to their persistent review identifiers.
+ */
+function edgeLabel(edge) {
+    return `@${edge.kind} #${edge.fingerprint}`;
+}
+/**
+ * Labels a review relation with its review-tag spelling and optional fingerprint.
+ *
+ * Missing fingerprints remain explicit because their absence affects review
+ * matching rather than meaning that the review edge has no source data.
+ */
+function reviewLabel(review) {
+    const marker = review.reviews === "evidence"
+        ? "@evidenceReview"
+        : "@evidenceExcludeReview";
+    return `${marker}${review.review.fingerprint === undefined ? "" : ` #${review.review.fingerprint}`}`;
+}
+/**
+ * Escapes text embedded inside Mermaid quoted labels and edge labels.
+ *
+ * Entity encodings prevent authored markup, quotes, separators, and line breaks
+ * from changing the surrounding flowchart grammar.
+ */
+function mermaidText(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll('"', """)
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("|", "&#124;")
+        .replaceAll("\r", "&#13;")
+        .replaceAll("\n", "&#10;");
+}
+/**
+ * Escapes text embedded in a DOT quoted string literal.
+ *
+ * Backslashes are handled first so later quote and line-break substitutions cannot
+ * create an escape sequence with a different meaning.
+ */
+function dotText(value) {
+    return value
+        .replaceAll("\\", "\\\\")
+        .replaceAll('"', '\\"')
+        .replaceAll("\r", "\\r")
+        .replaceAll("\n", "\\n");
+}

package/lib/reporters/EvidenceQueryReporter.d.ts

@@ -0,0 +1,33 @@
+import type { EvidenceQueryReport } from "../typings/EvidenceQueryReport";
+import type { EvidenceReportFormat } from "../typings/EvidenceReportFormat";
+/**
+ * Serializes query projections for people and automation.
+ *
+ * Query commands share their analysis boundary with checks, but expose selected
+ * targets, one target's explanation, or the shipped language catalog. These
+ * renderers preserve that structured data without triggering configuration or
+ * source I/O.
+ */
+export declare namespace EvidenceQueryReporter {
+    /**
+     * Selects the text or JSON representation for a query result.
+     *
+     * Every representation ends with a newline so callers can write it directly to
+     * stdout or a report file. The command discriminator selects the text layout.
+     */
+    function render(report: EvidenceQueryReport, format: EvidenceReportFormat): string;
+    /**
+     * Serializes the complete query report as indented JSON.
+     *
+     * JSON retains all diagnostics and inspection details for tools that should not
+     * infer structure from terminal-oriented text.
+     */
+    function json(report: EvidenceQueryReport): string;
+    /**
+     * Renders the human-readable layout appropriate to the query command.
+     *
+     * Language discovery has no project configuration, list reports enumerate
+     * filtered units, and inspection reports retain every applicable population.
+     */
+    function text(report: EvidenceQueryReport): string;
+}