@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/loaders/EvidenceConfigLoader.js

@@ -49,25 +49,27 @@ const validateEvidenceConfig_1 = require("../internal/validateEvidenceConfig");
 /**
  * Loads and validates Evidence configuration before artifact I/O begins.
  *
- * JSON is read as data; TypeScript is evaluated through the consumer's ttsx with
- * output isolated from report stdout. Validation covers disabled declarations too.
- * Call load to retain authored configuration or plan to resolve inherited policy
- * and remove inactive populations before source discovery.
+ * JSON is read as data; TypeScript is evaluated through the consumer's ttsx
+ * with output isolated from report stdout. Validation covers disabled
+ * declarations too. Call load to retain authored configuration or plan to
+ * resolve inherited policy and remove inactive populations before source
+ * discovery.
  *
  * @example
- * const plan: IEvidenceConfigPlan = await EvidenceConfigLoader.plan(
- *   "./config/evidence.config.ts",
- * );
- * // Population roots are anchored to the resolved configuration file.
+ *   const plan: IEvidenceConfigPlan = await EvidenceConfigLoader.plan(
+ *     "./config/evidence.config.ts",
+ *   );
+ *   // Population roots are anchored to the resolved configuration file.
  */
 var EvidenceConfigLoader;
 (function (EvidenceConfigLoader) {
     /**
      * Loads authored configuration and validates every claim and reference.
      *
-     * JSON data and TypeScript default exports share artifact and shape validation.
-     * Evaluation output goes to stderr, and failures reject rather than returning
-     * partially validated configuration. Inactive declarations are still checked.
+     * JSON data and TypeScript default exports share artifact and shape
+     * validation. Evaluation output goes to stderr, and failures reject rather
+     * than returning partially validated configuration. Inactive declarations are
+     * still checked.
      *
      * @param file Configuration path, relative to the current working directory.
      */
@@ -95,7 +97,8 @@ var EvidenceConfigLoader;
  * Resolves a supported configuration path to an existing physical file.
  *
  * Both logical and resolved spellings must use a supported format. Evaluation
- * follows the resolved filename, and a symlink to an unsupported target is rejected.
+ * follows the resolved filename, and a symlink to an unsupported target is
+ * rejected.
  */
 async function resolveConfigFile(file) {
     EvidenceConfigFormat_1.EvidenceConfigFormat.get(file);
@@ -110,7 +113,8 @@ async function resolveConfigFile(file) {
  *
  * Artifact identifiers receive a focused certification diagnostic before the
  * generated shape validator handles the remaining contract. JSON BOM removal
- * permits ordinary UTF-8 files without treating their strings as executable imports.
+ * permits ordinary UTF-8 files without treating their strings as executable
+ * imports.
  */
 async function evaluateResolvedConfig(filename) {
     const value = EvidenceConfigFormat_1.EvidenceConfigFormat.get(filename) === "json"
@@ -490,8 +494,9 @@ async function evaluateResolvedConfig(filename) {
 /**
  * Attributes unsupported artifact identifiers to exact claim/reference paths.
  *
- * This preflight only traverses recognizable containers. General malformed shapes
- * remain the generated validator's responsibility rather than being accepted here.
+ * This preflight only traverses recognizable containers. General malformed
+ * shapes remain the generated validator's responsibility rather than being
+ * accepted here.
  */
 function validateArtifactTypes(value) {
     if (!isRecord(value))
@@ -516,8 +521,9 @@ function validateArtifactTypes(value) {
 /**
  * Rejects a string discriminator with no shipped certified adapter.
  *
- * Non-string values are left for shape validation so this check reports only the
- * artifact-availability problem it can diagnose with a precise configuration path.
+ * Non-string values are left for shape validation so this check reports only
+ * the artifact-availability problem it can diagnose with a precise
+ * configuration path.
  */
 function validateArtifactType(value, path) {
     if (typeof value !== "string" || EvidenceArtifactTypes_1.EvidenceArtifactTypes.isSupported(value))
@@ -525,15 +531,18 @@ function validateArtifactType(value, path) {
     throw new Error(`Invalid Evidence configuration at ${path}: artifact type '${value}' has no certified Evidence adapter. Supported types: ${EvidenceArtifactTypes_1.EvidenceArtifactTypes.supported().join(", ")}.`);
 }
 /**
- * Narrows a value enough to inspect named configuration fields during preflight.
+ * Narrows a value enough to inspect named configuration fields during
+ * preflight.
  *
- * This only establishes safe object access; full shape validity is checked by typia.
+ * This only establishes safe object access; full shape validity is checked by
+ * typia.
  */
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
 /**
- * Exposes array entries for artifact preflight without assuming their element shape.
+ * Exposes array entries for artifact preflight without assuming their element
+ * shape.
  *
  * Non-arrays return undefined so single-reference handling or shape validation
  * can decide the appropriate interpretation.
@@ -542,10 +551,12 @@ function unknownArray(value) {
     return Array.isArray(value) ? value : undefined;
 }
 /**
- * Converts generated shape-validation details into an author-facing configuration error.
+ * Converts generated shape-validation details into an author-facing
+ * configuration error.
  *
  * The message removes the validator's synthetic root name and distinguishes a
- * missing value from a wrong type without serializing arbitrary configuration data.
+ * missing value from a wrong type without serializing arbitrary configuration
+ * data.
  */
 function configurationShapeError(props) {
     const path = (props.path ?? "$input").replace(/^\$input\.?/u, "");

package/lib/loaders/EvidenceSourceLoader.d.ts

@@ -3,33 +3,35 @@ import type { IEvidenceSourceSnapshot } from "../structures/IEvidenceSourceSnaps
 /**
  * Loads source snapshots that adapter analysis can classify and parse.
  *
- * Configuration planning supplies a selection, then the checker uses this boundary
- * to preserve both discovered files and recoverable filesystem failures. The
- * loader does not decide language support: selected unsupported files remain in
- * the snapshot so the applicable adapter can produce its own diagnostic.
+ * Configuration planning supplies a selection, then the checker uses this
+ * boundary to preserve both discovered files and recoverable filesystem
+ * failures. The loader does not decide language support: selected unsupported
+ * files remain in the snapshot so the applicable adapter can produce its own
+ * diagnostic.
  *
  * @example
- * const snapshot: IEvidenceSourceSnapshot = await EvidenceSourceLoader.glob(
- *   "evidence.config.ts",
- *   { files: ["src/*.ts"] },
- * );
+ *   const snapshot: IEvidenceSourceSnapshot =
+ *     await EvidenceSourceLoader.glob("evidence.config.ts", {
+ *       files: ["src/*.ts"],
+ *     });
  */
 export declare namespace EvidenceSourceLoader {
     /**
      * Discovers every path selected by one enabled population.
      *
-     * Relative patterns and the optional root are anchored to `configFile`. Invalid
-     * selector syntax rejects before scanning, while read, traversal, and snapshot
-     * failures are collected in an incomplete result. This distinction lets graph
-     * evaluation fail safely without losing paths needed for watch recovery.
+     * Relative patterns and the optional root are anchored to `configFile`.
+     * Invalid selector syntax rejects before scanning, while read, traversal, and
+     * snapshot failures are collected in an incomplete result. This distinction
+     * lets graph evaluation fail safely without losing paths needed for watch
+     * recovery.
      */
     function glob(configFile: string, selection: IEvidenceSourceSelection): Promise<IEvidenceSourceSnapshot>;
     /**
      * Captures one exact local file for an operation that names a path directly.
      *
      * The file may be outside `root`, unlike a glob population. Its resolved root
-     * still supplies configuration-relative identity and location context, and any
-     * filesystem failure is retained in the returned incomplete snapshot.
+     * still supplies configuration-relative identity and location context, and
+     * any filesystem failure is retained in the returned incomplete snapshot.
      */
     function file(configFile: string, file: string, root?: string): Promise<IEvidenceSourceSnapshot>;
 }

package/lib/loaders/EvidenceSourceLoader.js

@@ -1,35 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceSourceLoader = void 0;
-const FileGlob_1 = require("../internal/FileGlob");
-const SourceCollector_1 = require("../internal/SourceCollector");
+const EvidenceFileGlob_1 = require("../internal/EvidenceFileGlob");
+const EvidenceSourceCollector_1 = require("../internal/EvidenceSourceCollector");
 /**
  * Loads source snapshots that adapter analysis can classify and parse.
  *
- * Configuration planning supplies a selection, then the checker uses this boundary
- * to preserve both discovered files and recoverable filesystem failures. The
- * loader does not decide language support: selected unsupported files remain in
- * the snapshot so the applicable adapter can produce its own diagnostic.
+ * Configuration planning supplies a selection, then the checker uses this
+ * boundary to preserve both discovered files and recoverable filesystem
+ * failures. The loader does not decide language support: selected unsupported
+ * files remain in the snapshot so the applicable adapter can produce its own
+ * diagnostic.
  *
  * @example
- * const snapshot: IEvidenceSourceSnapshot = await EvidenceSourceLoader.glob(
- *   "evidence.config.ts",
- *   { files: ["src/*.ts"] },
- * );
+ *   const snapshot: IEvidenceSourceSnapshot =
+ *     await EvidenceSourceLoader.glob("evidence.config.ts", {
+ *       files: ["src/*.ts"],
+ *     });
  */
 var EvidenceSourceLoader;
 (function (EvidenceSourceLoader) {
     /**
      * Discovers every path selected by one enabled population.
      *
-     * Relative patterns and the optional root are anchored to `configFile`. Invalid
-     * selector syntax rejects before scanning, while read, traversal, and snapshot
-     * failures are collected in an incomplete result. This distinction lets graph
-     * evaluation fail safely without losing paths needed for watch recovery.
+     * Relative patterns and the optional root are anchored to `configFile`.
+     * Invalid selector syntax rejects before scanning, while read, traversal, and
+     * snapshot failures are collected in an incomplete result. This distinction
+     * lets graph evaluation fail safely without losing paths needed for watch
+     * recovery.
      */
     async function glob(configFile, selection) {
-        const globs = new FileGlob_1.FileGlob(selection.files);
-        const collector = new SourceCollector_1.SourceCollector(configFile, selection.root ?? ".");
+        const globs = new EvidenceFileGlob_1.EvidenceFileGlob(selection.files);
+        const collector = new EvidenceSourceCollector_1.EvidenceSourceCollector(configFile, selection.root ?? ".");
         await collector.scan(globs);
         return collector.snapshot();
     }
@@ -38,11 +40,11 @@ var EvidenceSourceLoader;
      * Captures one exact local file for an operation that names a path directly.
      *
      * The file may be outside `root`, unlike a glob population. Its resolved root
-     * still supplies configuration-relative identity and location context, and any
-     * filesystem failure is retained in the returned incomplete snapshot.
+     * still supplies configuration-relative identity and location context, and
+     * any filesystem failure is retained in the returned incomplete snapshot.
      */
     async function file(configFile, file, root = ".") {
-        const collector = new SourceCollector_1.SourceCollector(configFile, root);
+        const collector = new EvidenceSourceCollector_1.EvidenceSourceCollector(configFile, root);
         await collector.exact(file);
         return collector.snapshot();
     }

package/lib/loaders/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Configuration and local-source loading boundaries.
+ *
+ * EvidenceChecker composes these loaders for normal checks, while integrations
+ * can call them directly when they need validated configuration or snapshots.
+ */
+export * from "./EvidenceConfigLoader";
+export * from "./EvidenceSourceLoader";

package/lib/loaders/index.js

@@ -0,0 +1,24 @@
+"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 });
+/**
+ * Configuration and local-source loading boundaries.
+ *
+ * EvidenceChecker composes these loaders for normal checks, while integrations
+ * can call them directly when they need validated configuration or snapshots.
+ */
+__exportStar(require("./EvidenceConfigLoader"), exports);
+__exportStar(require("./EvidenceSourceLoader"), exports);

package/lib/parsers/EvidenceDocumentation.d.ts

@@ -4,17 +4,19 @@ import type { IEvidenceSourceRange } from "../structures/IEvidenceSourceRange";
 /**
  * Normalizes adapter-identified comments without losing source coordinates.
  *
- * The adapter owns comment classification and attachment. This helper only removes
- * the supplied delimiters and line prefixes, retaining mappings that let the tag
- * parser report exact spans and exclude accepted annotations from fingerprints.
+ * The adapter owns comment classification and attachment. This helper only
+ * removes the supplied delimiters and line prefixes, retaining mappings that
+ * let the tag parser report exact spans and exclude accepted annotations from
+ * fingerprints.
  */
 export declare namespace EvidenceDocumentation {
     /**
      * Reads a validated comment span into mapped annotation text.
      *
-     * The range must belong to the supplied content and match the declared opening
-     * and closing delimiters. Invalid spans throw instead of mapping unrelated text.
-     * Adapters must establish comment identity and declaration ownership beforehand.
+     * The range must belong to the supplied content and match the declared
+     * opening and closing delimiters. Invalid spans throw instead of mapping
+     * unrelated text. Adapters must establish comment identity and declaration
+     * ownership beforehand.
      */
     function read(content: string, hostId: string, range: IEvidenceSourceRange, syntax: IEvidenceCommentSyntax): IEvidenceDocumentation;
 }

package/lib/parsers/EvidenceDocumentation.js

@@ -1,25 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceDocumentation = void 0;
-const SourceText_1 = require("../internal/SourceText");
+const EvidenceSourceText_1 = require("../internal/EvidenceSourceText");
 /**
  * Normalizes adapter-identified comments without losing source coordinates.
  *
- * The adapter owns comment classification and attachment. This helper only removes
- * the supplied delimiters and line prefixes, retaining mappings that let the tag
- * parser report exact spans and exclude accepted annotations from fingerprints.
+ * The adapter owns comment classification and attachment. This helper only
+ * removes the supplied delimiters and line prefixes, retaining mappings that
+ * let the tag parser report exact spans and exclude accepted annotations from
+ * fingerprints.
  */
 var EvidenceDocumentation;
 (function (EvidenceDocumentation) {
     /**
      * Reads a validated comment span into mapped annotation text.
      *
-     * The range must belong to the supplied content and match the declared opening
-     * and closing delimiters. Invalid spans throw instead of mapping unrelated text.
-     * Adapters must establish comment identity and declaration ownership beforehand.
+     * The range must belong to the supplied content and match the declared
+     * opening and closing delimiters. Invalid spans throw instead of mapping
+     * unrelated text. Adapters must establish comment identity and declaration
+     * ownership beforehand.
      */
     function read(content, hostId, range, syntax) {
-        if (!new SourceText_1.SourceText(content).contains(range))
+        if (!new EvidenceSourceText_1.EvidenceSourceText(content).contains(range))
             throw new Error("The documentation range does not match the source.");
         const raw = content.slice(range.start.offset, range.end.offset);
         if (raw.length < syntax.opening.length + syntax.closing.length ||

package/lib/parsers/EvidenceDocumentationExamples.d.ts

@@ -0,0 +1,55 @@
+import type { IEvidenceDocumentationFence } from "./IEvidenceDocumentationFence";
+/**
+ * Coordinates example masking shared by programming-language documentation
+ * readers.
+ *
+ * Several documentation syntaxes permit both Markdown code and HTML example
+ * elements. Their precedence must be decided across the whole comment before an
+ * adapter looks for Evidence Graph tags; otherwise a literal `<pre>` in one
+ * fence can consume real prose and annotations after that fence.
+ */
+export declare namespace EvidenceDocumentationExamples {
+    /**
+     * Finds the least indentation shared by nonempty documentation lines.
+     *
+     * Comment-prefix removal can leave one ordinary padding column. Fence and
+     * indented-code decisions must measure from that baseline rather than from
+     * the physical source column or fully trimmed text.
+     */
+    function baseline(input: string): number;
+    /**
+     * Recognizes one Markdown fence within three columns of a document baseline.
+     *
+     * Four-column indentation denotes an indented code line and cannot open or
+     * close a fence. Backtick info text containing another backtick is likewise
+     * rejected by Markdown's fence grammar.
+     */
+    function fence(line: string, documentBaseline: number): IEvidenceDocumentationFence | undefined;
+    /**
+     * Masks HTML example regions without changing source coordinates.
+     *
+     * Tags inside Markdown fences or closed inline-code spans are literals and do
+     * not participate in pairing. In the default HTML mode, slash syntax does not
+     * self-close supported non-void elements; C# selects XML mode so its true
+     * self-closing elements mask only their tag. Matched regions and openings
+     * that remain active through the host end become spaces while CR/LF bytes
+     * remain intact, preserving the source map already owned by the adapter.
+     */
+    function maskHtml(characters: string[], input: string, names: readonly string[], xmlSelfClosing?: boolean): void;
+    /**
+     * Masks HTML comments before Evidence Graph tag lines are classified.
+     *
+     * Comment delimiters inside Markdown code remain literal. Closed and unclosed
+     * real comments retain their newline bytes and source length so every visible
+     * annotation after a close keeps its original mapping.
+     */
+    function maskHtmlComments(characters: string[], input: string): void;
+    /**
+     * Identifies Markdown fenced, indented, and closed inline code coordinates.
+     *
+     * Adapter-native documentation syntax consults this map before opening its
+     * own example state, preventing literal native delimiters from spanning real
+     * documentation outside a Markdown example.
+     */
+    function markdownCode(input: string): readonly boolean[];
+}