@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/programmers/EvidenceQueryProgrammer.js

@@ -9,15 +9,15 @@ const EvidenceFileTarget_1 = require("../targets/EvidenceFileTarget");
 const EvidenceFingerprint_1 = require("../graph/EvidenceFingerprint");
 const EvidenceLanguageRegistry_1 = require("../parsers/EvidenceLanguageRegistry");
 const EvidenceTargetResolver_1 = require("../targets/EvidenceTargetResolver");
-const InventoryMerge_1 = require("../internal/InventoryMerge");
+const EvidenceInventoryMerge_1 = require("../internal/EvidenceInventoryMerge");
 const EvidenceQueryPopulationContext_1 = require("../contexts/EvidenceQueryPopulationContext");
-const MarkdownTarget_1 = require("../adapters/markdown/MarkdownTarget");
+const EvidenceMarkdownTarget_1 = require("../adapters/markdown/EvidenceMarkdownTarget");
 /**
  * Projects one completed checker analysis into query-command reports.
  *
  * Query operations never re-evaluate graph policy or mutate inventories. They
- * retain the claim/reference coordinates established during checking, so a list,
- * target inspection, and exported graph all describe the same independent
+ * retain the claim/reference coordinates established during checking, so a
+ * list, target inspection, and exported graph all describe the same independent
  * obligation boundaries and diagnostic set.
  *
  * @example
@@ -30,12 +30,14 @@ const MarkdownTarget_1 = require("../adapters/markdown/MarkdownTarget");
 var EvidenceQueryProgrammer;
 (function (EvidenceQueryProgrammer) {
     /**
-     * Lists configured identities and the structural ancestors needed to address them.
+     * Lists configured identities and the structural ancestors needed to address
+     * them.
      *
-     * Language and symbol filters apply after each population is projected, so they
-     * do not change configured selection or graph coverage. Rows are sorted by
-     * stable query identity, and checker diagnostics are passed through unchanged
-     * because a list command is an observation of the existing analysis.
+     * Language and symbol filters apply after each population is projected, so
+     * they do not change configured selection or graph coverage. Rows are sorted
+     * by stable query identity, and checker diagnostics are passed through
+     * unchanged because a list command is an observation of the existing
+     * analysis.
      */
     function list(context, language, kind) {
         const { analysis } = context;
@@ -61,12 +63,14 @@ var EvidenceQueryProgrammer;
     }
     EvidenceQueryProgrammer.list = list;
     /**
-     * Inspects one CLI-relative target across the populations that can interpret it.
+     * Inspects one CLI-relative target across the populations that can interpret
+     * it.
      *
-     * Exact indexed spellings take precedence over grammar inference, preventing a
-     * target alias from being hidden by a broad file-extension match. Resolution is
-     * isolated per population; the report is resolved only when every selected
-     * boundary resolves, and preserves incomplete checker state as exit code 2.
+     * Exact indexed spellings take precedence over grammar inference, preventing
+     * a target alias from being hidden by a broad file-extension match.
+     * Resolution is isolated per population; the report is resolved only when
+     * every selected boundary resolves, and preserves incomplete checker state as
+     * exit code 2.
      */
     async function inspect(context, target) {
         const { analysis } = context;
@@ -108,7 +112,8 @@ var EvidenceQueryProgrammer;
     }
     EvidenceQueryProgrammer.inspect = inspect;
     /**
-     * Exports the evaluated graph as boundaries, nodes, acknowledgement edges, and reviews.
+     * Exports the evaluated graph as boundaries, nodes, acknowledgement edges,
+     * and reviews.
      *
      * Each claim/reference pair receives its own boundary even when it reuses an
      * inventory. Nodes are keyed by boundary and role so coverage cannot visually
@@ -206,8 +211,9 @@ var EvidenceQueryProgrammer;
      * Lists artifact adapters that the installed runtime can actually analyze.
      *
      * Registry entries without an adapter remain parser metadata and are omitted.
-     * Language and database entries are combined then ordered by type, providing a
-     * stable capability report without depending on registry declaration order.
+     * Language and database entries are combined then ordered by type, providing
+     * a stable capability report without depending on registry declaration
+     * order.
      */
     function languages() {
         const languages = [
@@ -243,9 +249,10 @@ var EvidenceQueryProgrammer;
     /**
      * Builds a query context for every configured claim and reference entry.
      *
-     * The context list preserves graph-input order and gives each reference its own
-     * wrapper, even when several entries share the same inventory. This preserves
-     * obligation-specific selection, policies, and coverage during later queries.
+     * The context list preserves graph-input order and gives each reference its
+     * own wrapper, even when several entries share the same inventory. This
+     * preserves obligation-specific selection, policies, and coverage during
+     * later queries.
      */
     function populations(analysis) {
         const output = [];
@@ -281,11 +288,13 @@ var EvidenceQueryProgrammer;
     }
     EvidenceQueryProgrammer.populations = populations;
     /**
-     * Lists one population's selected identities and visible structural ancestors.
+     * Lists one population's selected identities and visible structural
+     * ancestors.
      *
      * Visibility is owned by {@link EvidenceQueryPopulationContext}; this helper
-     * only turns visible units into public rows. Units without a public address are
-     * excluded because list output must contain targets that inspect can accept.
+     * only turns visible units into public rows. Units without a public address
+     * are excluded because list output must contain targets that inspect can
+     * accept.
      */
     function listPopulation(population, cwd) {
         const visible = population.visible;
@@ -325,7 +334,8 @@ var EvidenceQueryProgrammer;
         };
     }
     /**
-     * Resolves a target and gathers its query evidence within one population boundary.
+     * Resolves a target and gathers its query evidence within one population
+     * boundary.
      *
      * A synthetic attached host gives the shared resolver a CLI-relative source
      * context without pretending that the query came from a real documentation
@@ -345,7 +355,7 @@ var EvidenceQueryProgrammer;
         return {
             scope: population.scope,
             status: resolution.status,
-            addresses: InventoryMerge_1.InventoryMerge.unique(resolution.addresses.flatMap((address) => formatAddress(population, address.file, address.segments, cwd)), (address) => address).sort(compare),
+            addresses: EvidenceInventoryMerge_1.EvidenceInventoryMerge.unique(resolution.addresses.flatMap((address) => formatAddress(population, address.file, address.segments, cwd)), (address) => address).sort(compare),
             units,
             withdrawals: resolution.withdrawals,
             obligations: inspectedObligations(population, unitIds),
@@ -357,9 +367,10 @@ var EvidenceQueryProgrammer;
     /**
      * Builds the detailed inspection record for one resolved unit.
      *
-     * Only direct children are included so recursive client views can choose their
-     * own expansion. A fingerprint is exposed only from a complete inventory: an
-     * incomplete parse cannot safely provide a stable review identity.
+     * Only direct children are included so recursive client views can choose
+     * their own expansion. A fingerprint is exposed only from a complete
+     * inventory: an incomplete parse cannot safely provide a stable review
+     * identity.
      */
     function inspectedUnit(population, unit, cwd) {
         const item = listItem(population, unit, cwd);
@@ -385,7 +396,8 @@ var EvidenceQueryProgrammer;
         };
     }
     /**
-     * Reports the reference obligations that govern inspected selected identities.
+     * Reports the reference obligations that govern inspected selected
+     * identities.
      *
      * Claim populations own no coverage obligation, and unselected resolved units
      * must not imply coverage. Missing graph policy data returns no rows so an
@@ -424,7 +436,8 @@ var EvidenceQueryProgrammer;
      *
      * The search joins graph results to the matching claim input by configured
      * coordinates, preserving duplicate reference obligations. Broken graph links
-     * are omitted here because checker construction already owns their diagnostics.
+     * are omitted here because checker construction already owns their
+     * diagnostics.
      */
     function inspectedAcknowledgements(analysis, population, unitIds) {
         if (population.scope.role !== "reference" ||
@@ -505,7 +518,8 @@ var EvidenceQueryProgrammer;
         }));
     }
     /**
-     * Narrows target inspection to populations whose artifact grammar can accept it.
+     * Narrows target inspection to populations whose artifact grammar can accept
+     * it.
      *
      * Prisma and Swagger have unmistakable target forms; file targets consult the
      * installed registry. When inference finds no type, every population remains
@@ -547,21 +561,25 @@ var EvidenceQueryProgrammer;
         return population.visible.has(unitId) ? "ancestor" : "unselected";
     }
     /**
-     * Formats the public aliases for one semantic identity in deterministic order.
+     * Formats the public aliases for one semantic identity in deterministic
+     * order.
      *
      * Inventory aliases may render to the same artifact target, so deduplication
-     * occurs after formatting. The sorted result supplies the canonical list target
-     * and makes exact-target matching stable across adapter traversal order.
+     * occurs after formatting. The sorted result supplies the canonical list
+     * target and makes exact-target matching stable across adapter traversal
+     * order.
      */
     function targets(population, unitId, cwd) {
-        return InventoryMerge_1.InventoryMerge.unique((population.addresses.get(unitId) ?? []).flatMap((address) => formatAddress(population, address.file, address.segments, cwd)), (target) => target).sort(compare);
+        return EvidenceInventoryMerge_1.EvidenceInventoryMerge.unique((population.addresses.get(unitId) ?? []).flatMap((address) => formatAddress(population, address.file, address.segments, cwd)), (target) => target).sort(compare);
     }
     /**
-     * Tests whether a configured identity exposes the exact requested target spelling.
+     * Tests whether a configured identity exposes the exact requested target
+     * spelling.
      *
      * Only configured addresses participate because an ancestor's visible address
      * must not override grammar inference for a target that names no obligation.
-     * A match is used solely to choose populations; resolution remains authoritative.
+     * A match is used solely to choose populations; resolution remains
+     * authoritative.
      */
     function populationHasTarget(population, target, cwd) {
         const configured = population.configured;
@@ -573,7 +591,8 @@ var EvidenceQueryProgrammer;
      *
      * Prisma and Swagger do not use file-qualified accessors, while Markdown must
      * preserve selected logical aliases for a physical file. Other artifacts are
-     * made CLI-relative; an unrenderable Swagger address is omitted from query output.
+     * made CLI-relative; an unrenderable Swagger address is omitted from query
+     * output.
      */
     function formatAddress(population, file, segments, cwd) {
         if (population.scope.type === "prisma")
@@ -590,8 +609,8 @@ var EvidenceQueryProgrammer;
                 : []));
             const files = logical.length === 0 ? [file] : logical;
             return files.map((candidate) => segments.length === 0
-                ? MarkdownTarget_1.MarkdownTarget.normalize(candidate)
-                : `${MarkdownTarget_1.MarkdownTarget.normalize(candidate)}#${segments.join("#")}`);
+                ? EvidenceMarkdownTarget_1.EvidenceMarkdownTarget.normalize(candidate)
+                : `${EvidenceMarkdownTarget_1.EvidenceMarkdownTarget.normalize(candidate)}#${segments.join("#")}`);
         }
         return [
             EvidenceFileTarget_1.EvidenceFileTarget.format({
@@ -601,11 +620,13 @@ var EvidenceQueryProgrammer;
         ];
     }
     /**
-     * Creates the attached synthetic host used for command-line target resolution.
+     * Creates the attached synthetic host used for command-line target
+     * resolution.
      *
-     * Its file anchors relative paths at the query working directory without adding
-     * a document to any inventory. The fixed identity prevents command hosts from
-     * being confused with authored annotation hosts in resolver diagnostics.
+     * Its file anchors relative paths at the query working directory without
+     * adding a document to any inventory. The fixed identity prevents command
+     * hosts from being confused with authored annotation hosts in resolver
+     * diagnostics.
      */
     function commandHost(cwd) {
         const file = node_path_1.default.join(cwd, ".evidence-inspect");
@@ -621,9 +642,9 @@ var EvidenceQueryProgrammer;
     /**
      * Creates the zero-width coordinate assigned to a synthetic command host.
      *
-     * Query input has no authored source span, but downstream diagnostics require a
-     * complete location. Line and column one with offset zero provides that boundary
-     * without claiming a real character exists in the synthetic file.
+     * Query input has no authored source span, but downstream diagnostics require
+     * a complete location. Line and column one with offset zero provides that
+     * boundary without claiming a real character exists in the synthetic file.
      */
     function zeroLocation(file) {
         return {
@@ -637,9 +658,10 @@ var EvidenceQueryProgrammer;
     /**
      * Projects an addressable query row into a boundary-specific graph unit node.
      *
-     * The caller supplies coverage state because it differs by reference obligation
-     * even when the underlying inventory unit is shared. The generated node carries
-     * the public target and source locations needed by graph consumers.
+     * The caller supplies coverage state because it differs by reference
+     * obligation even when the underlying inventory unit is shared. The generated
+     * node carries the public target and source locations needed by graph
+     * consumers.
      */
     function graphUnitNode(boundaryId, role, item, isCovered, isMissing) {
         return {
@@ -661,7 +683,8 @@ var EvidenceQueryProgrammer;
      *
      * Hosts attached to units reuse claim nodes, preserving unit-level edges. A
      * detached-from-selection host becomes a dedicated node so evidence remains
-     * visible without inventing a claim unit; absent hosts fail the graph invariant.
+     * visible without inventing a claim unit; absent hosts fail the graph
+     * invariant.
      */
     function graphSourceNodes(nodes, boundaryId, population, hostId, unitIds, cwd) {
         if (unitIds.length !== 0) {
@@ -685,9 +708,9 @@ var EvidenceQueryProgrammer;
     /**
      * Ensures a boundary-specific graph node exists for a referenced identity.
      *
-     * Existing nodes are retained to preserve their coverage state. An absent unit
-     * or missing public address is an invalid graph projection, so this throws
-     * instead of exporting an edge that a consumer cannot inspect.
+     * Existing nodes are retained to preserve their coverage state. An absent
+     * unit or missing public address is an invalid graph projection, so this
+     * throws instead of exporting an edge that a consumer cannot inspect.
      */
     function ensureUnitNode(nodes, boundaryId, role, population, unitId, cwd) {
         const id = graphUnitNodeId(boundaryId, role, unitId);
@@ -723,9 +746,9 @@ var EvidenceQueryProgrammer;
     /**
      * Tests whether a reference unit exposes missing coverage in its obligation.
      *
-     * Direct missing identities and ancestors with any missing selected descendant
-     * are both marked missing. Without an obligation, the population owns no
-     * coverage state and therefore returns false.
+     * Direct missing identities and ancestors with any missing selected
+     * descendant are both marked missing. Without an obligation, the population
+     * owns no coverage state and therefore returns false.
      */
     function missing(population, unitId) {
         const obligation = population.obligation;
@@ -741,8 +764,9 @@ var EvidenceQueryProgrammer;
      * Retrieves the query population at an exact claim/reference coordinate.
      *
      * Role is part of the key because one inventory can serve both sides of an
-     * obligation. A missing entry means analysis and query context lost positional
-     * alignment, so graph export throws rather than relabelling its data.
+     * obligation. A missing entry means analysis and query context lost
+     * positional alignment, so graph export throws rather than relabelling its
+     * data.
      */
     function requirePopulation(entries, role, claim, reference) {
         const population = entries.find((entry) => entry.scope.role === role &&
@@ -755,9 +779,9 @@ var EvidenceQueryProgrammer;
     /**
      * Retrieves graph reference policy input from a reference population.
      *
-     * Only reference contexts own this data. Its absence signals a context assembly
-     * invariant failure, and throwing prevents a graph report from silently using
-     * fabricated defaults.
+     * Only reference contexts own this data. Its absence signals a context
+     * assembly invariant failure, and throwing prevents a graph report from
+     * silently using fabricated defaults.
      */
     function requirePopulationReference(population) {
         if (population.reference === undefined)
@@ -767,9 +791,9 @@ var EvidenceQueryProgrammer;
     /**
      * Projects effective reference policy flags into a public graph boundary.
      *
-     * Optional graph-input flags become explicit booleans so report consumers need
-     * not reproduce configuration defaults. Severity is retained unchanged because
-     * it controls the consequence of coverage diagnostics.
+     * Optional graph-input flags become explicit booleans so report consumers
+     * need not reproduce configuration defaults. Severity is retained unchanged
+     * because it controls the consequence of coverage diagnostics.
      */
     function graphPolicy(reference) {
         return {
@@ -784,9 +808,9 @@ var EvidenceQueryProgrammer;
     /**
      * Retrieves the checker report claim at a graph-input position.
      *
-     * Graph export joins report labels by construction order. A missing row exposes
-     * a broken checker-analysis invariant and throws before coordinates can be
-     * assigned to a wrong boundary.
+     * Graph export joins report labels by construction order. A missing row
+     * exposes a broken checker-analysis invariant and throws before coordinates
+     * can be assigned to a wrong boundary.
      */
     function requireReportClaim(analysis, position) {
         const claim = analysis.report.claims[position];
@@ -797,9 +821,9 @@ var EvidenceQueryProgrammer;
     /**
      * Retrieves the evaluated graph claim at a graph-input position.
      *
-     * This preserves the checker’s positional join with its input and report. A
-     * missing result is an internal invariant failure, not an empty claim suitable
-     * for graph serialization.
+     * This preserves the checker?셲 positional join with its input and report. A
+     * missing result is an internal invariant failure, not an empty claim
+     * suitable for graph serialization.
      */
     function requireResultClaim(analysis, position) {
         const claim = analysis.graph.claims[position];
@@ -810,8 +834,8 @@ var EvidenceQueryProgrammer;
     /**
      * Retrieves the report obligation for exact claim and reference positions.
      *
-     * The returned row supplies public coordinates for graph export. Throwing on a
-     * missing position prevents edges and policies from being emitted under an
+     * The returned row supplies public coordinates for graph export. Throwing on
+     * a missing position prevents edges and policies from being emitted under an
      * unrelated reference label.
      */
     function requireReportObligation(analysis, claim, reference) {
@@ -823,8 +847,8 @@ var EvidenceQueryProgrammer;
     /**
      * Retrieves the evaluated obligation for exact claim and reference positions.
      *
-     * Graph export uses its coverage, edges, and completion state together with the
-     * matching report row. Missing positional state is fatal because an empty
+     * Graph export uses its coverage, edges, and completion state together with
+     * the matching report row. Missing positional state is fatal because an empty
      * substitute could falsely make a boundary look complete.
      */
     function requireResultObligation(analysis, claim, reference) {
@@ -836,9 +860,10 @@ var EvidenceQueryProgrammer;
     /**
      * Retrieves an acknowledgement by its inventory-local identity.
      *
-     * Graph edges retain only this identity, while export needs the authored target,
-     * reason, and location. A missing record breaks that graph-to-inventory link and
-     * throws instead of emitting an unverifiable edge.
+     * Graph edges retain only this identity, while export needs the authored
+     * target, reason, and location. A missing record breaks that
+     * graph-to-inventory link and throws instead of emitting an unverifiable
+     * edge.
      */
     function requireDeclaration(inventory, id) {
         const declaration = inventory.declarations.find((candidate) => candidate.id === id);
@@ -849,9 +874,9 @@ var EvidenceQueryProgrammer;
     /**
      * Retrieves a review by its inventory-local identity.
      *
-     * Review resolutions refer back to the authored annotation through this value.
-     * A missing record indicates invalid graph input and is fatal because the public
-     * report cannot accurately represent the review without it.
+     * Review resolutions refer back to the authored annotation through this
+     * value. A missing record indicates invalid graph input and is fatal because
+     * the public report cannot accurately represent the review without it.
      */
     function requireReview(inventory, id) {
         const review = inventory.reviews.find((candidate) => candidate.id === id);
@@ -873,11 +898,12 @@ var EvidenceQueryProgrammer;
         return host;
     }
     /**
-     * Adds the query population’s configured coordinates to a diagnostic.
+     * Adds the query population?셲 configured coordinates to a diagnostic.
      *
      * Resolver diagnostics are inventory-local; query output must identify the
-     * independent claim and reference obligation that produced them. Claim scope is
-     * always present, while reference scope remains absent for claim populations.
+     * independent claim and reference obligation that produced them. Claim scope
+     * is always present, while reference scope remains absent for claim
+     * populations.
      */
     function scopedDiagnostic(diagnostic, scope) {
         return {
@@ -890,18 +916,19 @@ var EvidenceQueryProgrammer;
      * Deduplicates diagnostics whose complete public content is identical.
      *
      * Inspection combines checker and per-population diagnostics, which can reach
-     * the same error through several compatible populations. Serialization includes
-     * coordinates and repair text, preserving distinct actionable failures.
+     * the same error through several compatible populations. Serialization
+     * includes coordinates and repair text, preserving distinct actionable
+     * failures.
      */
     function uniqueDiagnostics(diagnostics) {
-        return InventoryMerge_1.InventoryMerge.unique(diagnostics, (diagnostic) => JSON.stringify(diagnostic));
+        return EvidenceInventoryMerge_1.EvidenceInventoryMerge.unique(diagnostics, (diagnostic) => JSON.stringify(diagnostic));
     }
     /**
      * Formats the stable key for a claim scope or one of its reference scopes.
      *
-     * The key is internal to query ordering and exact-population selection. Omitting
-     * the reference segment for claims preserves the distinct coordinate shape and
-     * prevents a claim from colliding with its first reference.
+     * The key is internal to query ordering and exact-population selection.
+     * Omitting the reference segment for claims preserves the distinct coordinate
+     * shape and prevents a claim from colliding with its first reference.
      */
     function scopeId(scope) {
         return scope.reference === undefined
@@ -911,9 +938,9 @@ var EvidenceQueryProgrammer;
     /**
      * Formats the graph boundary identity for one claim/reference obligation.
      *
-     * Boundary IDs are intentionally coordinate-based, even when populations share
-     * an inventory, so exported nodes and edges cannot leak coverage across policy
-     * boundaries.
+     * Boundary IDs are intentionally coordinate-based, even when populations
+     * share an inventory, so exported nodes and edges cannot leak coverage across
+     * policy boundaries.
      */
     function boundary(claim, reference) {
         return `claim:${claim}:reference:${reference}`;
@@ -921,9 +948,9 @@ var EvidenceQueryProgrammer;
     /**
      * Formats a graph node identity for one unit within a boundary and role.
      *
-     * Claim and reference nodes need separate IDs because the same semantic unit can
-     * appear on both sides of an obligation with different selection and coverage
-     * state.
+     * Claim and reference nodes need separate IDs because the same semantic unit
+     * can appear on both sides of an obligation with different selection and
+     * coverage state.
      */
     function graphUnitNodeId(boundaryId, role, unitId) {
         return `${boundaryId}:${role}:${unitId}`;
@@ -931,9 +958,10 @@ var EvidenceQueryProgrammer;
     /**
      * Extracts the decoded file portion from a possibly qualified target.
      *
-     * Type inference examines only the physical-looking file prefix, leaving accessor
-     * syntax untouched. Invalid percent encoding is retained verbatim so inference
-     * can fail normally and the resolver can report the authored target.
+     * Type inference examines only the physical-looking file prefix, leaving
+     * accessor syntax untouched. Invalid percent encoding is retained verbatim so
+     * inference can fail normally and the resolver can report the authored
+     * target.
      */
     function targetFile(target) {
         const separator = target.indexOf("#");
@@ -961,8 +989,9 @@ var EvidenceQueryProgrammer;
     /**
      * Orders query identities and rendered targets by code-unit comparison.
      *
-     * Avoiding locale collation makes list, inspection, and graph output reproducible
-     * across operating systems and independent of the invoking process locale.
+     * Avoiding locale collation makes list, inspection, and graph output
+     * reproducible across operating systems and independent of the invoking
+     * process locale.
      */
     function compare(left, right) {
         return left < right ? -1 : left > right ? 1 : 0;

package/lib/programmers/EvidenceTagProgrammer.d.ts

@@ -1,7 +1,8 @@
 import type { IEvidenceTagContext } from "../contexts/IEvidenceTagContext";
 import type { IEvidenceTagParseResult } from "../structures/IEvidenceTagParseResult";
 /**
- * Parses Evidence annotations from documentation already mapped to a source host.
+ * 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
@@ -14,12 +15,15 @@ import type { IEvidenceTagParseResult } from "../structures/IEvidenceTagParseRes
  */
 export declare namespace EvidenceTagProgrammer {
     /**
-     * Parses valid Evidence tags and diagnostics from one mapped documentation block.
+     * 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.
+     * The function consumes no text outside
+     * {@link IEvidenceTagContext.documentation}. It preserves multiline tag
+     * bodies, ignores apparent tags inside fenced code or HTML comments, 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;
 }