@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/lua/IEvidenceLuaDocumentation.d.ts

@@ -0,0 +1,40 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceLuaDocumentationAttachment } from "./IEvidenceLuaDocumentationAttachment";
+/**
+ * Represents a Lua documentation carrier or tag-bearing unsupported carrier.
+ *
+ * LuaDoc is retained independently of static value resolution so annotations on
+ * dynamic or detached source can be reported truthfully rather than discarded.
+ */
+export interface IEvidenceLuaDocumentation {
+    /**
+     * Identifies this physical Lua documentation carrier within the scanned file.
+     *
+     * Attachments and generated hosts use this scanner-local ID, which does not
+     * name a semantic declaration.
+     */
+    id: string;
+    /**
+     * Locates the carrier's original half-open UTF-16 source span.
+     *
+     * The adapter preserves this range for diagnostics and annotation-range
+     * exclusion.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Defines the delimiters and annotation-reading rules for this comment
+     * carrier.
+     *
+     * Documentation parsing uses the syntax instead of guessing from raw Lua
+     * source text.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Lists declaration sites that accept this carrier as attached LuaDoc.
+     *
+     * The scanner establishes attachment from source adjacency before static
+     * value reconciliation.
+     */
+    attachments: IEvidenceLuaDocumentationAttachment[];
+}

package/lib/adapters/lua/IEvidenceLuaDocumentationAttachment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Connects a LuaDoc carrier to one extracted Lua declaration site.
+ *
+ * EvidenceLuaFileScanner records this source-adjacent pair before static value
+ * handling, so the documentation pass can evaluate annotations without giving
+ * comments ownership of the declaration's semantic unit.
+ */
+export interface IEvidenceLuaDocumentationAttachment {
+    /**
+     * Identifies the declaration extraction record that receives the LuaDoc.
+     *
+     * Consumers use this stable scanner-local ID to locate the declaration whose
+     * annotation needs evaluation.
+     */
+    declarationId: string;
+    /**
+     * Identifies the physical declaration site covered by the LuaDoc.
+     *
+     * This keeps an attachment at its adjacent source occurrence when aliases or
+     * table members cause one semantic unit to have several sites.
+     */
+    siteId: string;
+}

package/lib/adapters/lua/IEvidenceLuaFileAnalysis.d.ts

@@ -0,0 +1,48 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceLuaDeclaration } from "./IEvidenceLuaDeclaration";
+import type { IEvidenceLuaDocumentation } from "./IEvidenceLuaDocumentation";
+/**
+ * Holds the node-free Lua extraction retained after a parse session closes.
+ *
+ * Static initialization is interpreted only while scanning; this record carries
+ * the resulting public-value candidates into inventory materialization.
+ */
+export interface IEvidenceLuaFileAnalysis {
+    /**
+     * Retains the selected Lua source file that produced this analysis.
+     *
+     * Its physical identity and configured addresses are used when units and
+     * comment hosts are materialized.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Lists declarations and alias projections established by supported static
+     * initialization.
+     *
+     * `EvidenceLuaAdapter` reconciles these node-free records into public units
+     * after scanning ends.
+     */
+    declarations: IEvidenceLuaDeclaration[];
+    /**
+     * Lists classified LuaDoc and unsupported annotation carriers from this file.
+     *
+     * Tagged unsupported carriers remain available for diagnostics instead of
+     * silently disappearing.
+     */
+    documentation: IEvidenceLuaDocumentation[];
+    /**
+     * Lists failures encountered while establishing the static public surface.
+     *
+     * The adapter forwards them into the inventory together with the `complete`
+     * boundary.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether static extraction understood every relevant source form.
+     *
+     * A false value keeps unsupported dynamic behavior visible to callers rather
+     * than treating an incomplete table projection as an empty public surface.
+     */
+    complete: boolean;
+}

package/lib/adapters/lua/IEvidenceLuaValue.d.ts

@@ -0,0 +1,41 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { IEvidenceLuaDeclaration } from "./IEvidenceLuaDeclaration";
+/**
+ * Represents a statically understood Lua value during file scanning.
+ *
+ * EvidenceLuaFileScanner keeps these records for bindings, table fields,
+ * aliases, and final module returns so it can construct public declarations
+ * without evaluating Lua; they are internal scanner state rather than
+ * serialized output.
+ */
+export interface IEvidenceLuaValue {
+    /**
+     * Classifies the statically supported value without executing Lua.
+     *
+     * The scanner traverses `table` fields, emits `function` and `literal` values
+     * as declarations, and omits `nil` values from the public surface.
+     */
+    kind: "table" | "function" | "literal" | "nil";
+    /**
+     * Points to the source node that establishes this value's declaration site.
+     *
+     * EvidenceLuaFileScanner derives a stable declaration ID and diagnostic
+     * location from this node, including a copied site for scalar alias
+     * assignments.
+     */
+    node: EvidenceNode;
+    /**
+     * Maps statically named table fields to their understood values.
+     *
+     * Only `table` values populate this map; scalar, callable, and nil values use
+     * an empty map so table traversal has one uniform representation.
+     */
+    fields: Map<string, IEvidenceLuaValue>;
+    /**
+     * Stores the declaration first published for this value's public path.
+     *
+     * Omission means the value is not yet public. Once set, aliases reuse this
+     * declaration to preserve one semantic identity across multiple addresses.
+     */
+    declaration?: IEvidenceLuaDeclaration;
+}

package/lib/adapters/markdown/EvidenceMarkdownAdapter.d.ts

@@ -1,28 +1,28 @@
 import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
 import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
 import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
-import type { EvidenceArtifactType } from "../../typings/EvidenceArtifactType";
 /**
  * Extracts Markdown file and heading units with HTML-comment annotation hosts.
  *
  * Every supplied source is interpreted as Markdown regardless of its extension.
- * MarkdownScanner owns heading hierarchy, fenced-content boundaries, and comment
- * attachment; this adapter combines those records with discovery diagnostics and
- * validates the resulting shared inventory.
+ * EvidenceMarkdownScanner owns heading hierarchy, fenced-content boundaries,
+ * and comment attachment; this adapter combines those records with discovery
+ * diagnostics and validates the resulting shared inventory.
  */
-export declare class EvidenceMarkdownAdapter implements IEvidenceAdapter {
+export declare class EvidenceMarkdownAdapter implements IEvidenceAdapter<"markdown"> {
     /**
      * Artifact discriminator selecting Markdown structure and target grammar.
      *
-     * Population symbol policies can select files or supported exact heading levels.
+     * Population symbol policies can select files or supported exact heading
+     * levels.
      */
-    readonly type: EvidenceArtifactType;
+    get type(): "markdown";
     /**
      * Scans captured Markdown contents into an owned normalized inventory.
      *
      * Input is validated and cloned before scanners append units and annotations.
-     * Discovery failures remain attached to the result, preventing unreadable files
-     * from silently reducing the coverage population.
+     * Discovery failures remain attached to the result, preventing unreadable
+     * files from silently reducing the coverage population.
      */
     analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
 }

package/lib/adapters/markdown/EvidenceMarkdownAdapter.js

@@ -40,34 +40,39 @@ exports.EvidenceMarkdownAdapter = void 0;
 const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
 const typia_1 = __importDefault(require("typia"));
 const EvidenceInventory_1 = require("../../graph/EvidenceInventory");
-const MarkdownScanner_1 = require("./MarkdownScanner");
+const EvidenceMarkdownScanner_1 = require("./EvidenceMarkdownScanner");
 /**
  * Extracts Markdown file and heading units with HTML-comment annotation hosts.
  *
  * Every supplied source is interpreted as Markdown regardless of its extension.
- * MarkdownScanner owns heading hierarchy, fenced-content boundaries, and comment
- * attachment; this adapter combines those records with discovery diagnostics and
- * validates the resulting shared inventory.
+ * EvidenceMarkdownScanner owns heading hierarchy, fenced-content boundaries,
+ * and comment attachment; this adapter combines those records with discovery
+ * diagnostics and validates the resulting shared inventory.
  */
 class EvidenceMarkdownAdapter {
     /**
      * Artifact discriminator selecting Markdown structure and target grammar.
      *
-     * Population symbol policies can select files or supported exact heading levels.
+     * Population symbol policies can select files or supported exact heading
+     * levels.
      */
-    type = "markdown";
+    get type() {
+        return "markdown";
+    }
     /**
      * Scans captured Markdown contents into an owned normalized inventory.
      *
      * Input is validated and cloned before scanners append units and annotations.
-     * Discovery failures remain attached to the result, preventing unreadable files
-     * from silently reducing the coverage population.
+     * Discovery failures remain attached to the result, preventing unreadable
+     * files from silently reducing the coverage population.
      */
     async analyze(snapshot) {
         const input = structuredClone((() => {
             const _ip0 = input => "string" === typeof input["absolute"];
             const _ip1 = input => "string" === typeof input["display"];
-            const _ip2 = input => "string" === typeof input["path"];
+            const _ip2 = input => "string" === typeof input["physicalPath"];
+            const _ip3 = input => "string" === typeof input["fingerprintPath"];
+            const _ip4 = input => "string" === typeof input["path"];
             const _ap0 = (input, _path, _exceptionable = true) => "string" === typeof input["absolute"] || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".absolute",
@@ -80,7 +85,19 @@ class EvidenceMarkdownAdapter {
                 expected: "string",
                 value: input["display"]
             }, _errorFactory);
-            const _ap2 = (input, _path, _exceptionable = true) => "string" === typeof input["path"] || _assertGuard_1._assertGuard(_exceptionable, {
+            const _ap2 = (input, _path, _exceptionable = true) => "string" === typeof input["physicalPath"] || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".physicalPath",
+                expected: "string",
+                value: input["physicalPath"]
+            }, _errorFactory);
+            const _ap3 = (input, _path, _exceptionable = true) => "string" === typeof input["fingerprintPath"] || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".fingerprintPath",
+                expected: "string",
+                value: input["fingerprintPath"]
+            }, _errorFactory);
+            const _ap4 = (input, _path, _exceptionable = true) => "string" === typeof input["path"] || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".path",
                 expected: "string",
@@ -127,7 +144,7 @@ class EvidenceMarkdownAdapter {
                 path: _path + ".dependencies[" + _index6 + "]",
                 expected: "IEvidenceSourceDependency",
                 value: elem
-            }, _errorFactory)) && _ao4(elem, _path + ".dependencies[" + _index6 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+            }, _errorFactory)) && _ao5(elem, _path + ".dependencies[" + _index6 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".dependencies[" + _index6 + "]",
                 expected: "IEvidenceSourceDependency",
@@ -147,7 +164,7 @@ class EvidenceMarkdownAdapter {
                 path: _path + ".diagnostics[" + _index7 + "]",
                 expected: "IEvidenceSourceDiagnostic",
                 value: elem
-            }, _errorFactory)) && _ao5(elem, _path + ".diagnostics[" + _index7 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+            }, _errorFactory)) && _ao6(elem, _path + ".diagnostics[" + _index7 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".diagnostics[" + _index7 + "]",
                 expected: "IEvidenceSourceDiagnostic",
@@ -179,11 +196,16 @@ class EvidenceMarkdownAdapter {
                 path: _path + ".id",
                 expected: "string",
                 value: input.id
-            }, _errorFactory)) && ("string" === typeof input.physicalPath || _assertGuard_1._assertGuard(_exceptionable, {
+            }, _errorFactory)) && _ap2(input, _path, true && _exceptionable) && _ap3(input, _path, true && _exceptionable) && (undefined === input.fingerprintRoot || ("object" === typeof input.fingerprintRoot && null !== input.fingerprintRoot || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
-                path: _path + ".physicalPath",
-                expected: "string",
-                value: input.physicalPath
+                path: _path + ".fingerprintRoot",
+                expected: "(IEvidenceSourceFingerprintRoot | undefined)",
+                value: input.fingerprintRoot
+            }, _errorFactory)) && _ao3(input.fingerprintRoot, _path + ".fingerprintRoot", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".fingerprintRoot",
+                expected: "(IEvidenceSourceFingerprintRoot | undefined)",
+                value: input.fingerprintRoot
             }, _errorFactory)) && ("string" === typeof input.content || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".content",
@@ -204,7 +226,7 @@ class EvidenceMarkdownAdapter {
                 path: _path + ".addresses[" + _index8 + "]",
                 expected: "IEvidenceSourceAddress",
                 value: elem
-            }, _errorFactory)) && _ao3(elem, _path + ".addresses[" + _index8 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+            }, _errorFactory)) && _ao4(elem, _path + ".addresses[" + _index8 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".addresses[" + _index8 + "]",
                 expected: "IEvidenceSourceAddress",
@@ -215,7 +237,8 @@ class EvidenceMarkdownAdapter {
                 expected: "Array<IEvidenceSourceAddress>",
                 value: input.addresses
             }, _errorFactory));
-            const _ao3 = (input, _path, _exceptionable = true) => _ap0(input, _path, true && _exceptionable) && ("string" === typeof input.relative || _assertGuard_1._assertGuard(_exceptionable, {
+            const _ao3 = (input, _path, _exceptionable = true) => _ap2(input, _path, true && _exceptionable) && _ap3(input, _path, true && _exceptionable);
+            const _ao4 = (input, _path, _exceptionable = true) => _ap0(input, _path, true && _exceptionable) && ("string" === typeof input.relative || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".relative",
                 expected: "string",
@@ -226,29 +249,30 @@ class EvidenceMarkdownAdapter {
                 expected: "(boolean | undefined)",
                 value: input.selected
             }, _errorFactory));
-            const _ao4 = (input, _path, _exceptionable = true) => _ap2(input, _path, true && _exceptionable) && ("boolean" === typeof input.recursive || _assertGuard_1._assertGuard(_exceptionable, {
+            const _ao5 = (input, _path, _exceptionable = true) => _ap4(input, _path, true && _exceptionable) && ("boolean" === typeof input.recursive || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".recursive",
                 expected: "boolean",
                 value: input.recursive
             }, _errorFactory));
-            const _ao5 = (input, _path, _exceptionable = true) => ("case-mismatch" === input.code || "invalid-encoding" === input.code || "not-file" === input.code || "path-unreadable" === input.code || "root-unreadable" === input.code || "source-changed" === input.code || "symlink-cycle" === input.code || _assertGuard_1._assertGuard(_exceptionable, {
+            const _ao6 = (input, _path, _exceptionable = true) => ("case-mismatch" === input.code || "invalid-encoding" === input.code || "not-file" === input.code || "path-unreadable" === input.code || "root-unreadable" === input.code || "source-changed" === input.code || "symlink-cycle" === input.code || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".code",
                 expected: _ae0,
                 value: input.code
-            }, _errorFactory)) && _ap2(input, _path, true && _exceptionable) && ("string" === typeof input.message || _assertGuard_1._assertGuard(_exceptionable, {
+            }, _errorFactory)) && _ap4(input, _path, true && _exceptionable) && ("string" === typeof input.message || _assertGuard_1._assertGuard(_exceptionable, {
                 method: "typia.assert",
                 path: _path + ".message",
                 expected: "string",
                 value: input.message
             }, _errorFactory));
-            const _io0 = input => "object" === typeof input.root && null !== input.root && _io1(input.root) && (Array.isArray(input.files) && input.files.every(elem => "object" === typeof elem && null !== elem && _io2(elem))) && (Array.isArray(input.dependencies) && input.dependencies.every(elem => "object" === typeof elem && null !== elem && _io4(elem))) && (Array.isArray(input.diagnostics) && input.diagnostics.every(elem => "object" === typeof elem && null !== elem && _io5(elem))) && "boolean" === typeof input.complete;
+            const _io0 = input => "object" === typeof input.root && null !== input.root && _io1(input.root) && (Array.isArray(input.files) && input.files.every(elem => "object" === typeof elem && null !== elem && _io2(elem))) && (Array.isArray(input.dependencies) && input.dependencies.every(elem => "object" === typeof elem && null !== elem && _io5(elem))) && (Array.isArray(input.diagnostics) && input.diagnostics.every(elem => "object" === typeof elem && null !== elem && _io6(elem))) && "boolean" === typeof input.complete;
             const _io1 = input => "string" === typeof input.declared && _ip0(input) && (undefined === input.physical || "string" === typeof input.physical) && _ip1(input);
-            const _io2 = input => "string" === typeof input.id && "string" === typeof input.physicalPath && "string" === typeof input.content && "string" === typeof input.digest && (Array.isArray(input.addresses) && input.addresses.every(elem => "object" === typeof elem && null !== elem && _io3(elem)));
-            const _io3 = input => _ip0(input) && "string" === typeof input.relative && _ip1(input) && (undefined === input.selected || "boolean" === typeof input.selected);
-            const _io4 = input => _ip2(input) && "boolean" === typeof input.recursive;
-            const _io5 = input => ("case-mismatch" === input.code || "invalid-encoding" === input.code || "not-file" === input.code || "path-unreadable" === input.code || "root-unreadable" === input.code || "source-changed" === input.code || "symlink-cycle" === input.code) && _ip2(input) && "string" === typeof input.message;
+            const _io2 = input => "string" === typeof input.id && _ip2(input) && _ip3(input) && (undefined === input.fingerprintRoot || "object" === typeof input.fingerprintRoot && null !== input.fingerprintRoot && _io3(input.fingerprintRoot)) && "string" === typeof input.content && "string" === typeof input.digest && (Array.isArray(input.addresses) && input.addresses.every(elem => "object" === typeof elem && null !== elem && _io4(elem)));
+            const _io3 = input => _ip2(input) && _ip3(input);
+            const _io4 = input => _ip0(input) && "string" === typeof input.relative && _ip1(input) && (undefined === input.selected || "boolean" === typeof input.selected);
+            const _io5 = input => _ip4(input) && "boolean" === typeof input.recursive;
+            const _io6 = input => ("case-mismatch" === input.code || "invalid-encoding" === input.code || "not-file" === input.code || "path-unreadable" === input.code || "root-unreadable" === input.code || "source-changed" === input.code || "symlink-cycle" === input.code) && _ip4(input) && "string" === typeof input.message;
             const __is = input => "object" === typeof input && null !== input && _io0(input);
             let _errorFactory;
             return (input, errorFactory) => {
@@ -289,7 +313,7 @@ class EvidenceMarkdownAdapter {
             complete: input.complete,
         };
         for (const source of input.files)
-            new MarkdownScanner_1.MarkdownScanner(inventory, source).scan();
+            new EvidenceMarkdownScanner_1.EvidenceMarkdownScanner(inventory, source).scan();
         return new EvidenceInventory_1.EvidenceInventory([inventory]).snapshot();
     }
 }

package/lib/adapters/markdown/EvidenceMarkdownScanner.d.ts

@@ -0,0 +1,224 @@
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+/**
+ * Materializes one Markdown source as a file unit and its heading units.
+ *
+ * The scanner also maps HTML-comment annotations while excluding rendered and
+ * example content that must remain ordinary Markdown text.
+ */
+export declare class EvidenceMarkdownScanner {
+    private readonly inventory;
+    private readonly source;
+    /**
+     * Maps UTF-16 offsets in the original source content to Evidence ranges.
+     *
+     * All sites, content ranges, and diagnostics use this source-preserving
+     * mapper.
+     */
+    private readonly text;
+    /**
+     * Start offset of each physical source line.
+     *
+     * The first line always begins at zero; parallel line-state arrays use the
+     * same index so classification never depends on normalized line endings.
+     */
+    private readonly lineStarts;
+    /**
+     * End offset of each physical source line, excluding its line terminator.
+     *
+     * Content extraction uses these offsets while ranges retain the original
+     * source positions recorded in {@link lineStarts}.
+     */
+    private readonly lineEnds;
+    /**
+     * Marks lines owned by a CommonMark fenced-code region.
+     *
+     * Fenced lines cannot create headings or active annotation hosts.
+     */
+    private readonly fenced;
+    /**
+     * Marks lines owned by a rendered-code region such as HTML `pre`.
+     *
+     * These regions remain part of Markdown content but are structurally inert to
+     * the Evidence scanner.
+     */
+    private readonly rendered;
+    /**
+     * Marks lines whose semantic text consists entirely of HTML comments.
+     *
+     * Closed comment ranges are refined after discovery so prose beside a comment
+     * remains fingerprinted and eligible for Markdown structure.
+     */
+    private readonly commentOnly;
+    /**
+     * Closed HTML-comment carriers discovered outside example regions.
+     *
+     * Each record preserves exact source offsets for tag mapping and for removing
+     * annotations from semantic fingerprints.
+     */
+    private readonly comments;
+    /**
+     * Column-preserving HTML-comment spans grouped by physical source line.
+     *
+     * Structural Markdown parsing replaces these spans with spaces so invisible
+     * comment text cannot alter heading names, anchors, or rendered-prose
+     * checks.
+     */
+    private readonly commentMasks;
+    /**
+     * Semantic fingerprint owner selected for each source line.
+     *
+     * Heading depth transitions update this array before content ranges are
+     * assigned to the owning file or heading unit.
+     */
+    private readonly owners;
+    /**
+     * Annotation host unit selected for each source line.
+     *
+     * Unsupported headings clear this value so nearby comments cannot attach to a
+     * targetable ancestor by accident.
+     */
+    private readonly hostUnits;
+    /**
+     * Physical site paired with each selected annotation host.
+     *
+     * Host construction needs both semantic unit ownership and the exact site
+     * that contains the comment.
+     */
+    private readonly hostSites;
+    /**
+     * Repair explanation for lines that have no valid annotation host.
+     *
+     * Comment materialization uses this parallel state to emit the structural
+     * failure at the comment location.
+     */
+    private readonly hostProblems;
+    /**
+     * Materialized sites indexed by their stable site identity.
+     *
+     * Later range-closing and fingerprint-content phases mutate the same records
+     * already published through the destination inventory.
+     */
+    private readonly sites;
+    /**
+     * Primary site identity for each Markdown unit.
+     *
+     * A Markdown file or heading currently has one site, and content assignment
+     * resolves that site without rescanning the inventory.
+     */
+    private readonly unitSites;
+    /**
+     * Binds the destination inventory and one physical Markdown source.
+     *
+     * Scan mutates only the supplied inventory with units, hosts, and diagnostics
+     * from this source.
+     */
+    constructor(inventory: IEvidenceInventory, source: IEvidenceSourceFile);
+    /**
+     * Scans Markdown structure, materializes units, and parses attached
+     * annotations.
+     *
+     * The phases run in source order because unit and host ownership depend on
+     * line classification.
+     */
+    scan(): void;
+    /**
+     * Indexes physical source lines and initializes their classification state.
+     *
+     * Carriage returns are excluded from line content while offsets remain tied
+     * to the original source.
+     */
+    private splitLines;
+    /**
+     * Marks examples and records real HTML comments before heading parsing.
+     *
+     * Comment, HTML `pre`, and MDX transitions share one ordered line scan so a
+     * close followed by another opener cannot expose later example content.
+     */
+    private markExamples;
+    /**
+     * Finds the next quote-aware HTML token on one physical line.
+     *
+     * Generic tags are returned as one span so comment and `pre` text inside
+     * quoted attributes cannot become Markdown boundaries. An incomplete
+     * line-start `pre` tag remains an opening token under the adapter's
+     * CommonMark boundary.
+     */
+    private markup;
+    /**
+     * Locates the close belonging to the active rendered-region grammar.
+     *
+     * HTML and MDX terminators are not interchangeable. The returned offset
+     * points after the matching delimiter so the caller can continue scanning the
+     * suffix for another ordered region transition.
+     */
+    private renderedClosing;
+    /**
+     * Returns one physical line with only real HTML-comment spans removed.
+     *
+     * Heading syntax is established from the authored line first. This second
+     * view supplies its visible title and anchor without collapsing whitespace or
+     * joining tokens that were not an ATX heading in the original source.
+     */
+    private visibleLine;
+    /**
+     * Returns one physical line with comment spans replaced by equal-width
+     * spaces.
+     *
+     * Rendered-annotation diagnostics need comment text to stay inert while their
+     * marker columns continue to map to the original source line.
+     */
+    private maskedLine;
+    /**
+     * Distinguishes full-comment lines from comments beside semantic prose.
+     *
+     * Example marking conservatively suppresses every line inside a comment so
+     * headings cannot escape it. Once exact closed ranges are known, this pass
+     * restores lines with non-whitespace prefix or suffix content. Fingerprinting
+     * can then remove the comment range without losing its surrounding prose.
+     */
+    private refineCommentLines;
+    /**
+     * Materializes file and supported heading units for every targetable address.
+     *
+     * Heading ownership is maintained by structural depth so content and
+     * annotations attach consistently.
+     */
+    private materializeUnits;
+    /**
+     * Assigns non-comment source lines to their current semantic unit sites.
+     *
+     * Annotation-only lines do not contribute to fingerprints of their
+     * documentation host.
+     */
+    private assignContent;
+    /**
+     * Creates annotation hosts and parses each recognized HTML comment.
+     *
+     * Unsupported attachment positions remain hosts so diagnostics retain their
+     * original location.
+     */
+    private materializeComments;
+    /**
+     * Diagnoses annotation markers rendered as ordinary Markdown prose.
+     *
+     * A visible marker is not an Evidence annotation until wrapped in an HTML
+     * comment.
+     */
+    private reportRenderedAnnotations;
+    /**
+     * Finds the nearest structural heading ancestor for a newly materialized
+     * unit.
+     *
+     * The file unit is the fallback owner when no prior heading level remains
+     * open.
+     */
+    private parent;
+    /**
+     * Returns one indexed line without its line-ending characters.
+     *
+     * Classification helpers use this normalized view while source ranges retain
+     * original offsets.
+     */
+    private line;
+}