@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/parsers/EvidenceTagParser.js

@@ -1,43 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceTagParser = void 0;
-const SourceText_1 = require("../internal/SourceText");
+const EvidenceSourceText_1 = require("../internal/EvidenceSourceText");
 const EvidenceTagProgrammer_1 = require("../programmers/EvidenceTagProgrammer");
 /**
  * Coordinates annotation parsing for one documented host.
  *
- * Every parse creates fresh continuation, fence, and diagnostic state. The adapter
- * establishes host attachment and documentation mapping before construction; this
- * controller preserves those inputs while delegating the grammar to the tag programmer.
+ * Every parse creates fresh continuation, fence, and diagnostic state. The
+ * adapter establishes host attachment and documentation mapping before
+ * construction; this controller preserves those inputs while delegating the
+ * grammar to the tag programmer.
  */
 class EvidenceTagParser {
     /**
      * Original source content used to restore annotation positions.
      *
-     * Documentation stores normalized text, while diagnostics must point into this
-     * complete host source through the documentation's retained offset mapping.
+     * Documentation stores normalized text, while diagnostics must point into
+     * this complete host source through the documentation's retained offset
+     * mapping.
      */
     content;
     /**
-     * Adapter-established attachment and semantic identity of the documented host.
+     * Adapter-established attachment and semantic identity of the documented
+     * host.
      *
-     * The tag programmer uses this host for statements and diagnostics. It is copied
-     * at construction so a caller cannot redirect parsed annotations by later mutation.
+     * The tag programmer uses this host for statements and diagnostics. It is
+     * copied at construction so a caller cannot redirect parsed annotations by
+     * later mutation.
      */
     host;
     /**
      * Mapped documentation accepted for this host by its adapter.
      *
-     * Its tag boundaries and withdrawal policy define what annotation syntax is valid;
-     * the copy keeps a parse operation tied to the attachment it was created for.
+     * Its tag boundaries and withdrawal policy define what annotation syntax is
+     * valid; the copy keeps a parse operation tied to the attachment it was
+     * created for.
      */
     documentation;
     /**
      * Captures one adapter-established host and its mapped documentation.
      *
      * Callers supply the full source solely for source-coordinate conversion. The
-     * constructor does not parse tags, allowing adapters to build all host records
-     * before the independent parsing phase begins.
+     * constructor does not parse tags, allowing adapters to build all host
+     * records before the independent parsing phase begins.
      */
     constructor(content, host, documentation) {
         this.content = content;
@@ -45,15 +50,16 @@ class EvidenceTagParser {
         this.documentation = structuredClone(documentation);
     }
     /**
-     * Parses the captured documentation into statements, withdrawals, and diagnostics.
+     * Parses the captured documentation into statements, withdrawals, and
+     * diagnostics.
      *
-     * Mutable continuation and code-fence state is allocated per call. Repeated calls
-     * therefore produce independent results and cannot carry an unfinished tag from
-     * one extraction cycle into another.
+     * Mutable continuation and code-fence state is allocated per call. Repeated
+     * calls therefore produce independent results and cannot carry an unfinished
+     * tag from one extraction cycle into another.
      */
     parse() {
         const context = {
-            source: new SourceText_1.SourceText(this.content),
+            source: new EvidenceSourceText_1.EvidenceSourceText(this.content),
             host: this.host,
             documentation: this.documentation,
             result: {
@@ -69,10 +75,12 @@ class EvidenceTagParser {
         return EvidenceTagProgrammer_1.EvidenceTagProgrammer.parse(context);
     }
     /**
-     * Parses one adapter-mapped documentation attachment without retaining a controller.
+     * Parses one adapter-mapped documentation attachment without retaining a
+     * controller.
      *
-     * This convenience entry point has the same snapshot and isolation guarantees as
-     * constructing a parser and calling `parse`, and is suitable for one-off adapter work.
+     * This convenience entry point has the same snapshot and isolation guarantees
+     * as constructing a parser and calling `parse`, and is suitable for one-off
+     * adapter work.
      */
     static parse(content, host, documentation) {
         return new EvidenceTagParser(content, host, documentation).parse();

package/lib/parsers/IEvidenceDocumentationFence.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Markdown fence recognized relative to mapped documentation indentation.
+ *
+ * Tag parsing and HTML precedence share this record so an indented delimiter
+ * cannot establish different lexical state in the two passes.
+ */
+export interface IEvidenceDocumentationFence {
+    /**
+     * Backtick or tilde character that owns the fenced region.
+     *
+     * A closing line must repeat this exact character.
+     */
+    marker: "`" | "~";
+    /**
+     * Number of repeated marker characters on this boundary.
+     *
+     * A closing boundary may be longer but cannot be shorter.
+     */
+    length: number;
+    /**
+     * Text following the marker run.
+     *
+     * Opening boundaries may carry info text, while closing boundaries require
+     * this value to contain only whitespace.
+     */
+    remainder: string;
+}

package/lib/parsers/IEvidenceDocumentationFence.js

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

package/lib/parsers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parser sessions, documentation tags, and certified language registry access.
+ *
+ * Adapter implementations use these boundaries to parse supported artifacts and
+ * interpret evidence annotations without importing command execution.
+ */
+export * from "./EvidenceDocumentation";
+export * from "./EvidenceDocumentationExamples";
+export * from "./EvidenceLanguageRegistry";
+export * from "./EvidenceParser";
+export * from "./EvidenceParserError";
+export type { EvidenceParseSession } from "./EvidenceParseSession";
+export * from "./EvidenceTagParser";

package/lib/parsers/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Parser sessions, documentation tags, and certified language registry access.
+ *
+ * Adapter implementations use these boundaries to parse supported artifacts and
+ * interpret evidence annotations without importing command execution.
+ */
+__exportStar(require("./EvidenceDocumentation"), exports);
+__exportStar(require("./EvidenceDocumentationExamples"), exports);
+__exportStar(require("./EvidenceLanguageRegistry"), exports);
+__exportStar(require("./EvidenceParser"), exports);
+__exportStar(require("./EvidenceParserError"), exports);
+__exportStar(require("./EvidenceTagParser"), exports);

package/lib/programmers/EvidenceCheckProgrammer.d.ts

@@ -3,7 +3,8 @@ import type { IEvidenceCheckAnalysis } from "../structures/IEvidenceCheckAnalysi
 import type { IEvidenceConfigPlan } from "../structures/IEvidenceConfigPlan";
 import type { IEvidenceCheckContext } from "../contexts/IEvidenceCheckContext";
 /**
- * Turns a validated check plan into inventories, graph input, and a command report.
+ * Turns a validated check plan into inventories, graph input, and a command
+ * report.
  *
  * This namespace is the orchestration boundary between configuration and graph
  * evaluation. It keeps every configured reference independent, so the same
@@ -12,7 +13,10 @@ import type { IEvidenceCheckContext } from "../contexts/IEvidenceCheckContext";
  *
  * @example
  *   const claims = await EvidenceCheckProgrammer.materialize(plan);
- *   const analysis = await EvidenceCheckProgrammer.evaluate({ plan, claims });
+ *   const analysis = await EvidenceCheckProgrammer.evaluate({
+ *     plan,
+ *     claims,
+ *   });
  */
 export declare namespace EvidenceCheckProgrammer {
     /**
@@ -27,10 +31,11 @@ export declare namespace EvidenceCheckProgrammer {
     /**
      * Prepares graph input and evaluates the checker result for one execution.
      *
-     * Preparation resolves annotations against each independent reference boundary
-     * before {@link EvidenceGraph.evaluate} applies coverage policy. The returned
-     * analysis deliberately retains both graph input and graph output so query
-     * commands can explain the result without rebuilding or reloading inventories.
+     * Preparation resolves annotations against each independent reference
+     * boundary before {@link EvidenceGraph.evaluate} applies coverage policy. The
+     * returned analysis deliberately retains both graph input and graph output so
+     * query commands can explain the result without rebuilding or reloading
+     * inventories.
      */
     function evaluate(context: IEvidenceCheckContext): Promise<IEvidenceCheckAnalysis>;
 }

package/lib/programmers/EvidenceCheckProgrammer.js

@@ -7,9 +7,10 @@ const EvidenceSwaggerAdapter_1 = require("../adapters/swagger/EvidenceSwaggerAda
 const EvidenceTargetResolver_1 = require("../targets/EvidenceTargetResolver");
 const EvidenceAdapterFactory_1 = require("../internal/EvidenceAdapterFactory");
 const EvidenceTargetApplicability_1 = require("../internal/EvidenceTargetApplicability");
-const FileGlob_1 = require("../internal/FileGlob");
+const EvidenceFileGlob_1 = require("../internal/EvidenceFileGlob");
 /**
- * Turns a validated check plan into inventories, graph input, and a command report.
+ * Turns a validated check plan into inventories, graph input, and a command
+ * report.
  *
  * This namespace is the orchestration boundary between configuration and graph
  * evaluation. It keeps every configured reference independent, so the same
@@ -18,7 +19,10 @@ const FileGlob_1 = require("../internal/FileGlob");
  *
  * @example
  *   const claims = await EvidenceCheckProgrammer.materialize(plan);
- *   const analysis = await EvidenceCheckProgrammer.evaluate({ plan, claims });
+ *   const analysis = await EvidenceCheckProgrammer.evaluate({
+ *     plan,
+ *     claims,
+ *   });
  */
 var EvidenceCheckProgrammer;
 (function (EvidenceCheckProgrammer) {
@@ -37,10 +41,11 @@ var EvidenceCheckProgrammer;
     /**
      * Prepares graph input and evaluates the checker result for one execution.
      *
-     * Preparation resolves annotations against each independent reference boundary
-     * before {@link EvidenceGraph.evaluate} applies coverage policy. The returned
-     * analysis deliberately retains both graph input and graph output so query
-     * commands can explain the result without rebuilding or reloading inventories.
+     * Preparation resolves annotations against each independent reference
+     * boundary before {@link EvidenceGraph.evaluate} applies coverage policy. The
+     * returned analysis deliberately retains both graph input and graph output so
+     * query commands can explain the result without rebuilding or reloading
+     * inventories.
      */
     async function evaluate(context) {
         const graphInput = {
@@ -55,7 +60,8 @@ var EvidenceCheckProgrammer;
      *
      * All paths are resolved from the single configuration file, even though the
      * loads run concurrently. This produces selected unit identifiers only; it
-     * does not add visible structural ancestors, which are a query-layer concern.
+     * does not add visible structural ancestors, which are a query-layer
+     * concern.
      */
     async function materializeClaim(configFile, plan) {
         const [inventory, references] = await Promise.all([
@@ -82,7 +88,8 @@ var EvidenceCheckProgrammer;
         };
     }
     /**
-     * Loads one configured population through the adapter that owns its artifact grammar.
+     * Loads one configured population through the adapter that owns its artifact
+     * grammar.
      *
      * File-backed Swagger is exceptional because its adapter owns direct document
      * loading. Every other population first expands source globs relative to the
@@ -112,14 +119,15 @@ var EvidenceCheckProgrammer;
             .map((unit) => unit.id);
     }
     /**
-     * Selects documentation hosts whose source files match exclusion-carrier globs.
+     * Selects documentation hosts whose source files match exclusion-carrier
+     * globs.
      *
      * Matching starts from selected logical addresses, then maps their physical
      * files back to hosts. This lets aliases share one exclusion decision while
      * avoiding exclusions from an unselected logical source address.
      */
     function selectExclusionHosts(inventory, patterns) {
-        const globs = new FileGlob_1.FileGlob(patterns);
+        const globs = new EvidenceFileGlob_1.EvidenceFileGlob(patterns);
         const files = new Set(inventory.sources.flatMap((source) => source.addresses.some((address) => address.selected !== false && globs.matches(address.relative))
             ? [source.physicalPath]
             : []));
@@ -128,12 +136,14 @@ var EvidenceCheckProgrammer;
             .map((host) => host.id);
     }
     /**
-     * Clones a claim inventory and prepares its graph-facing reference boundaries.
+     * Clones a claim inventory and prepares its graph-facing reference
+     * boundaries.
      *
-     * The clone receives preparation diagnostics so the materialized inventory can
-     * still serve as the unmodified loading result. Declaration and review indexes
-     * record eligible reference positions before resolving targets, ensuring an
-     * annotation is only evaluated where its grammar and host can participate.
+     * The clone receives preparation diagnostics so the materialized inventory
+     * can still serve as the unmodified loading result. Declaration and review
+     * indexes record eligible reference positions before resolving targets,
+     * ensuring an annotation is only evaluated where its grammar and host can
+     * participate.
      */
     async function prepareClaim(materialized) {
         const inventory = structuredClone(materialized.inventory);
@@ -167,7 +177,8 @@ var EvidenceCheckProgrammer;
         };
     }
     /**
-     * Maps one annotation to the reference positions whose target grammar accepts it.
+     * Maps one annotation to the reference positions whose target grammar accepts
+     * it.
      *
      * Positions, rather than reference identities, preserve duplicate configured
      * references as separate obligations. The returned set is later consulted by
@@ -177,12 +188,13 @@ var EvidenceCheckProgrammer;
         return new Set(EvidenceTargetApplicability_1.EvidenceTargetApplicability.select(statement, host, references).map((selected) => references.indexOf(selected)));
     }
     /**
-     * Builds one graph reference from the claim annotations eligible for this position.
+     * Builds one graph reference from the claim annotations eligible for this
+     * position.
      *
-     * A resolver sees only this reference inventory and its selected unit IDs. That
-     * isolation is essential: the same textual target may resolve differently in
-     * another reference population, and a review remains independent of an
-     * acknowledgement that happens to cover the same identity.
+     * A resolver sees only this reference inventory and its selected unit IDs.
+     * That isolation is essential: the same textual target may resolve
+     * differently in another reference population, and a review remains
+     * independent of an acknowledgement that happens to cover the same identity.
      */
     async function prepareReference(context, materialized, position) {
         const { inventory: claim, hosts, declarations, reviews } = context;
@@ -225,9 +237,9 @@ var EvidenceCheckProgrammer;
     /**
      * Resolves one acknowledgement against a preselected reference population.
      *
-     * The wrapper keeps the source declaration identity beside the resolver output,
-     * allowing graph evaluation and inspection reports to trace every edge back to
-     * the authored annotation.
+     * The wrapper keeps the source declaration identity beside the resolver
+     * output, allowing graph evaluation and inspection reports to trace every
+     * edge back to the authored annotation.
      */
     async function resolveDeclaration(resolver, declaration, host, unitIds) {
         return {
@@ -238,9 +250,9 @@ var EvidenceCheckProgrammer;
     /**
      * Resolves one review against the same boundary used for acknowledgements.
      *
-     * Reviews are returned in a separate collection because review policy assesses
-     * their status independently; resolving one must never manufacture an evidence
-     * edge or change coverage counts.
+     * Reviews are returned in a separate collection because review policy
+     * assesses their status independently; resolving one must never manufacture
+     * an evidence edge or change coverage counts.
      */
     async function resolveReview(resolver, review, host, unitIds) {
         return {
@@ -251,9 +263,9 @@ var EvidenceCheckProgrammer;
     /**
      * Retrieves an annotation host from the claim-local host index.
      *
-     * A missing host means an inventory invariant was broken after parsing. Throwing
-     * here prevents a later resolver error from losing the statement identity that
-     * caused the invalid graph input.
+     * A missing host means an inventory invariant was broken after parsing.
+     * Throwing here prevents a later resolver error from losing the statement
+     * identity that caused the invalid graph input.
      */
     function requireHost(hosts, id) {
         const host = hosts.get(id);
@@ -265,8 +277,8 @@ var EvidenceCheckProgrammer;
      * Tests whether an indexed annotation participates in one reference position.
      *
      * Missing records are treated as nonparticipating. This keeps the caller safe
-     * when an inventory has no annotation of the requested identity while retaining
-     * position-based separation for duplicated reference entries.
+     * when an inventory has no annotation of the requested identity while
+     * retaining position-based separation for duplicated reference entries.
      */
     function selected(records, id, position) {
         const positions = records.get(id);
@@ -276,8 +288,8 @@ var EvidenceCheckProgrammer;
      * Appends diagnostics for annotations accepted by no configured reference.
      *
      * Both acknowledgement and review diagnostics retain the authored location,
-     * host, and target so a caller can repair configuration or source text without
-     * inferring which pre-resolution applicability decision failed.
+     * host, and target so a caller can repair configuration or source text
+     * without inferring which pre-resolution applicability decision failed.
      */
     function reportNonParticipating(inventory, declarations, reviews) {
         for (const declaration of inventory.declarations)
@@ -306,10 +318,10 @@ var EvidenceCheckProgrammer;
     /**
      * Converts evaluated graph state into the stable public check report.
      *
-     * Completion is stricter than diagnostic success: inactive claims are ignored,
-     * while every active claim and active obligation must be complete. Exit code 2
-     * denotes incomplete graph state, code 1 denotes a complete graph with errors,
-     * and code 0 denotes a successful execution.
+     * Completion is stricter than diagnostic success: inactive claims are
+     * ignored, while every active claim and active obligation must be complete.
+     * Exit code 2 denotes incomplete graph state, code 1 denotes a complete graph
+     * with errors, and code 0 denotes a successful execution.
      */
     function report(plan, graph) {
         const claims = checkClaims(plan, graph);
@@ -332,12 +344,13 @@ var EvidenceCheckProgrammer;
         };
     }
     /**
-     * Projects graph claims into report rows using their configuration-plan labels.
+     * Projects graph claims into report rows using their configuration-plan
+     * labels.
      *
      * Positional joins are intentional: graph input is constructed in plan order,
-     * including duplicate populations. Missing plan entries are invariant failures,
-     * not report omissions, because emitting a relabelled obligation would mislead
-     * consumers about the policy that produced it.
+     * including duplicate populations. Missing plan entries are invariant
+     * failures, not report omissions, because emitting a relabelled obligation
+     * would mislead consumers about the policy that produced it.
      */
     function checkClaims(plan, graph) {
         return graph.claims.map((result, position) => {
@@ -374,9 +387,9 @@ var EvidenceCheckProgrammer;
     /**
      * Summarizes claims, active obligations, coverage, and diagnostic severities.
      *
-     * Coverage totals include only active obligations, matching the policy used for
-     * completion. Overall claim and obligation counts remain unfiltered so callers
-     * can distinguish disabled configuration from absent configuration.
+     * Coverage totals include only active obligations, matching the policy used
+     * for completion. Overall claim and obligation counts remain unfiltered so
+     * callers can distinguish disabled configuration from absent configuration.
      */
     function checkCounts(claims, diagnostics) {
         const obligations = claims.flatMap((claim) => claim.obligations);
@@ -437,8 +450,8 @@ var EvidenceCheckProgrammer;
     /**
      * Returns the first decisive comparison result in priority order.
      *
-     * Comparator construction remains separate from execution so ordering rules can
-     * be read as a single ordered list in {@link compareDiagnostics}.
+     * Comparator construction remains separate from execution so ordering rules
+     * can be read as a single ordered list in {@link compareDiagnostics}.
      */
     function firstDifference(values) {
         return values.find((value) => value !== 0) ?? 0;

package/lib/programmers/EvidenceQueryProgrammer.d.ts

@@ -11,8 +11,8 @@ import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
  * 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
@@ -24,25 +24,30 @@ import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
  */
 export declare namespace 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: IEvidenceQueryContext, language?: EvidenceArtifactType, kind?: EvidenceSymbol): IEvidenceListReport;
     /**
-     * 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.
      */
     function inspect(context: IEvidenceQueryContext, target: string): Promise<IEvidenceInspectReport>;
     /**
-     * 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
@@ -54,16 +59,18 @@ export declare namespace 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(): IEvidenceLanguagesReport;
     /**
      * 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: IEvidenceCheckAnalysis): EvidenceQueryPopulationContext[];
 }