@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/postgresql/IEvidencePostgresqlFileAnalysis.d.ts

@@ -0,0 +1,19 @@
+import type { IEvidenceSqlFileAnalysis } from "../sql/IEvidenceSqlFileAnalysis";
+import type { IEvidencePostgresqlReference } from "./IEvidencePostgresqlReference";
+/**
+ * Extends SQL analysis with PostgreSQL declarations that need an existing
+ * owner.
+ *
+ * ALTER and COMMENT statements can contribute sites in a different file from
+ * the declaration whose semantic identity they extend.
+ */
+export interface IEvidencePostgresqlFileAnalysis extends IEvidenceSqlFileAnalysis {
+    /**
+     * Lists declarations whose owner must be resolved after all files are
+     * scanned.
+     *
+     * Omission means this file has no ALTER or COMMENT sites needing cross-file
+     * ownership.
+     */
+    references?: IEvidencePostgresqlReference[];
+}

package/lib/adapters/postgresql/IEvidencePostgresqlReference.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Requests ownership resolution for a PostgreSQL declaration site.
+ *
+ * The adapter uses this record after scanning all files to merge ALTER and
+ * COMMENT sites with the declaration identified by their SQL identity.
+ */
+export interface IEvidencePostgresqlReference {
+    /**
+     * Identifies the local declaration that receives the resolved owner.
+     *
+     * This ID remains stable while resolution replaces its provisional identity.
+     */
+    declarationId: string;
+    /**
+     * Names the schema-qualified table or column to resolve.
+     *
+     * Table identities have two segments, while column identities have three.
+     */
+    identity: string[];
+    /**
+     * Distinguishes a COMMENT site from an ALTER TABLE extension.
+     *
+     * Comment sites retain a separate physical address after ownership
+     * resolution.
+     */
+    comment: boolean;
+}

package/lib/adapters/prisma/EvidencePrismaAdapter.d.ts

@@ -1,28 +1,30 @@
 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 Prisma models, columns, relations, and declaration documentation.
  *
  * Selected files form one schema for the Prisma model loader, while a separate
- * source scan retains exact declaration and comment coordinates. Materialization
- * joins those views so semantic schema units remain tied to their physical hosts.
- * A schema-loading failure produces incomplete analysis instead of an empty pass.
+ * source scan retains exact declaration and comment coordinates.
+ * Materialization joins those views so semantic schema units remain tied to
+ * their physical hosts. A schema-loading failure produces incomplete analysis
+ * instead of an empty pass.
  */
-export declare class EvidencePrismaAdapter implements IEvidenceAdapter {
+export declare class EvidencePrismaAdapter implements IEvidenceAdapter<"prisma"> {
     /**
      * Artifact discriminator selecting Prisma schema extraction.
      *
-     * Prisma target spelling and database selectors apply to the resulting inventory.
+     * Prisma target spelling and database selectors apply to the resulting
+     * inventory.
      */
-    readonly type: EvidenceArtifactType;
+    get type(): "prisma";
     /**
      * Loads one combined schema from a validated, cloned source snapshot.
      *
-     * Incomplete discovery is returned without attempting to certify partial schema
-     * content. Complete input is deduplicated by physical identity, parsed for models,
-     * and joined to source locations before annotations are materialized.
+     * Incomplete discovery is returned without attempting to certify partial
+     * schema content. Complete input is deduplicated by physical identity, parsed
+     * for models, and joined to source locations before annotations are
+     * materialized.
      */
     analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
     /**
@@ -33,11 +35,12 @@ export declare class EvidencePrismaAdapter implements IEvidenceAdapter {
      */
     private inventory;
     /**
-     * Deduplicates physical schema files and chooses deterministic logical parser names.
+     * Deduplicates physical schema files and chooses deterministic logical parser
+     * names.
      *
-     * Multiple selected link spellings must not submit the same declarations twice.
-     * All addresses are retained while the first sorted selected relative path names
-     * the schema input supplied to the model loader.
+     * Multiple selected link spellings must not submit the same declarations
+     * twice. All addresses are retained while the first sorted selected relative
+     * path names the schema input supplied to the model loader.
      */
     private schemaFiles;
     private units;

package/lib/adapters/prisma/EvidencePrismaAdapter.js

@@ -41,37 +41,44 @@ const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
 const typia_1 = __importDefault(require("typia"));
 const EvidenceInventory_1 = require("../../graph/EvidenceInventory");
 const EvidenceTagParser_1 = require("../../parsers/EvidenceTagParser");
-const InventoryMerge_1 = require("../../internal/InventoryMerge");
-const PrismaFileScanner_1 = require("./PrismaFileScanner");
-const PrismaModelLoader_1 = require("./PrismaModelLoader");
-const SourceText_1 = require("../../internal/SourceText");
+const EvidenceInventoryMerge_1 = require("../../internal/EvidenceInventoryMerge");
+const EvidencePrismaFileScanner_1 = require("./EvidencePrismaFileScanner");
+const EvidencePrismaModelLoader_1 = require("./EvidencePrismaModelLoader");
+const EvidenceSourceText_1 = require("../../internal/EvidenceSourceText");
 /**
  * Extracts Prisma models, columns, relations, and declaration documentation.
  *
  * Selected files form one schema for the Prisma model loader, while a separate
- * source scan retains exact declaration and comment coordinates. Materialization
- * joins those views so semantic schema units remain tied to their physical hosts.
- * A schema-loading failure produces incomplete analysis instead of an empty pass.
+ * source scan retains exact declaration and comment coordinates.
+ * Materialization joins those views so semantic schema units remain tied to
+ * their physical hosts. A schema-loading failure produces incomplete analysis
+ * instead of an empty pass.
  */
 class EvidencePrismaAdapter {
     /**
      * Artifact discriminator selecting Prisma schema extraction.
      *
-     * Prisma target spelling and database selectors apply to the resulting inventory.
+     * Prisma target spelling and database selectors apply to the resulting
+     * inventory.
      */
-    type = "prisma";
+    get type() {
+        return "prisma";
+    }
     /**
      * Loads one combined schema from a validated, cloned source snapshot.
      *
-     * Incomplete discovery is returned without attempting to certify partial schema
-     * content. Complete input is deduplicated by physical identity, parsed for models,
-     * and joined to source locations before annotations are materialized.
+     * Incomplete discovery is returned without attempting to certify partial
+     * schema content. Complete input is deduplicated by physical identity, parsed
+     * for models, and joined to source locations before annotations are
+     * materialized.
      */
     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",
@@ -84,7 +91,19 @@ class EvidencePrismaAdapter {
                 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",
@@ -131,7 +150,7 @@ class EvidencePrismaAdapter {
                 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",
@@ -151,7 +170,7 @@ class EvidencePrismaAdapter {
                 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",
@@ -183,11 +202,16 @@ class EvidencePrismaAdapter {
                 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",
@@ -208,7 +232,7 @@ class EvidencePrismaAdapter {
                 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",
@@ -219,7 +243,8 @@ class EvidencePrismaAdapter {
                 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",
@@ -230,29 +255,30 @@ class EvidencePrismaAdapter {
                 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) => {
@@ -279,8 +305,7 @@ class EvidencePrismaAdapter {
         const files = this.schemaFiles(input.files);
         let models;
         try {
-            models = (await PrismaModelLoader_1.PrismaModelLoader.load(input.root.absolute, files))
-                .models;
+            models = (await EvidencePrismaModelLoader_1.EvidencePrismaModelLoader.load(input.root.absolute, files)).models;
         }
         catch (cause) {
             inventory.complete = false;
@@ -298,7 +323,7 @@ class EvidencePrismaAdapter {
         // The model parser owns schema semantics; the source scanner owns exact
         // spans. Join both before attaching tags so normalized models do not invent
         // comment coordinates or erase the original declaration boundaries.
-        const analyses = files.map((file) => new PrismaFileScanner_1.PrismaFileScanner(file.source).scan());
+        const analyses = files.map((file) => new EvidencePrismaFileScanner_1.EvidencePrismaFileScanner(file.source).scan());
         const owned = this.units(inventory, models, analyses, files);
         this.materialize(inventory, analyses, owned);
         return new EvidenceInventory_1.EvidenceInventory([inventory]).snapshot();
@@ -331,11 +356,12 @@ class EvidencePrismaAdapter {
         };
     }
     /**
-     * Deduplicates physical schema files and chooses deterministic logical parser names.
+     * Deduplicates physical schema files and chooses deterministic logical parser
+     * names.
      *
-     * Multiple selected link spellings must not submit the same declarations twice.
-     * All addresses are retained while the first sorted selected relative path names
-     * the schema input supplied to the model loader.
+     * Multiple selected link spellings must not submit the same declarations
+     * twice. All addresses are retained while the first sorted selected relative
+     * path names the schema input supplied to the model loader.
      */
     schemaFiles(sources) {
         const records = new Map();
@@ -348,16 +374,16 @@ class EvidencePrismaAdapter {
         }
         return Array.from(records.values())
             .map((source) => {
-            source.addresses = InventoryMerge_1.InventoryMerge.sourceAddresses(source.addresses);
+            source.addresses = EvidenceInventoryMerge_1.EvidenceInventoryMerge.sourceAddresses(source.addresses);
             return {
                 name: source.addresses
                     .filter((address) => address.selected !== false)
                     .map((address) => address.relative)
-                    .sort(InventoryMerge_1.InventoryMerge.compare)[0] ?? source.physicalPath,
+                    .sort(EvidenceInventoryMerge_1.EvidenceInventoryMerge.compare)[0] ?? source.physicalPath,
                 source,
             };
         })
-            .sort((x, y) => InventoryMerge_1.InventoryMerge.compare(x.name, y.name));
+            .sort((x, y) => EvidenceInventoryMerge_1.EvidenceInventoryMerge.compare(x.name, y.name));
     }
     units(inventory, models, analyses, files) {
         const locations = new Map(analyses.flatMap((analysis) => analysis.locations.map((location) => [
@@ -382,7 +408,7 @@ class EvidencePrismaAdapter {
         const source = found === undefined ? fallback : found.analysis.source;
         if (source === undefined)
             throw new Error("A parsed Prisma unit has no selected source file.");
-        const text = new SourceText_1.SourceText(source.content);
+        const text = new EvidenceSourceText_1.EvidenceSourceText(source.content);
         const range = found === undefined ? text.range(0, 0) : found.location.range;
         const id = `prisma:${key}`;
         const site = {
@@ -567,7 +593,7 @@ class EvidencePrismaAdapter {
         return /(?:^|\n)[ \t]*(?:[/*]+[ \t]*)?@(evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link)\b/u.test(text);
     }
     reportBuried(inventory, source, run) {
-        const sourceText = new SourceText_1.SourceText(source.content);
+        const sourceText = new EvidenceSourceText_1.EvidenceSourceText(source.content);
         let offset = 0;
         for (const line of run.text.split("\n")) {
             const trimmed = line.trim();

package/lib/adapters/prisma/EvidencePrismaCommentForm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Prisma comment syntax relevant to documentation attachment.
+ *
+ * The position scanner classifies comment runs with these forms before adapter
+ * attachment determines whether they are eligible carriers for Evidence tags.
+ */
+export type EvidencePrismaCommentForm = "doc" | "line" | "block";

package/lib/adapters/prisma/EvidencePrismaFileScanner.d.ts

@@ -0,0 +1,82 @@
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidencePrismaFileAnalysis } from "./IEvidencePrismaFileAnalysis";
+/**
+ * Locates physical Prisma declarations and documentation without parsing
+ * semantics.
+ *
+ * The whole-schema parser remains responsible for deciding which declarations
+ * exist. This scanner supplies its source spans and comment-coordinate maps so
+ * those semantic declarations can own accurate sites and documentation.
+ */
+export declare class EvidencePrismaFileScanner {
+    private readonly source;
+    /**
+     * Holds raw source lines in scan order, preserving a final empty line.
+     *
+     * Parallel coordinate arrays translate each line's local positions back to
+     * the immutable source snapshot.
+     */
+    private readonly lines;
+    /**
+     * Stores the UTF-16 offset at which each source line begins.
+     *
+     * Missing defensive entries fall back to the source boundary when malformed
+     * line state is encountered.
+     */
+    private readonly lineStarts;
+    /**
+     * Stores the UTF-16 offset immediately after each line's content.
+     *
+     * Carriage returns are excluded because declaration ranges use content-only
+     * line boundaries.
+     */
+    private readonly lineEnds;
+    /**
+     * Stores the offset of each line's newline character or line terminus.
+     *
+     * Comment-run maps use these positions for newlines introduced between
+     * fragments on different source lines.
+     */
+    private readonly newlineOffsets;
+    /**
+     * Translates scanner offsets into Evidence source ranges.
+     *
+     * All locations and comment carriers use this one coordinate authority.
+     */
+    private readonly text;
+    /**
+     * Initializes line and coordinate indexes for one immutable source snapshot.
+     *
+     * The scanner borrows no parser session because it deliberately recognizes
+     * only structural Prisma positions and comments.
+     */
+    constructor(source: IEvidenceSourceFile);
+    /**
+     * Scans declaration positions and contiguous comment runs for the source.
+     *
+     * It flushes pending comments whenever syntax breaks adjacency, preserving
+     * detached carriers instead of attaching them to a later declaration.
+     */
+    scan(): IEvidencePrismaFileAnalysis;
+    /**
+     * Separates code from a line comment while carrying block-comment state.
+     *
+     * Quotes suppress comment delimiters so URL-like and escaped string content
+     * cannot alter declaration scanning or comment attachment.
+     */
+    private parts;
+    /**
+     * Converts pending fragments into attached and detached documentation runs.
+     *
+     * Ordinary or trailing line comments remain separate carriers, while
+     * non-trailing documentation forms are grouped for one eligible key.
+     */
+    private runs;
+    /**
+     * Builds one mapped run from source-order comment fragments.
+     *
+     * Explicit newline entries preserve a continuous documentation string even
+     * when adjacent source comments occur on different lines.
+     */
+    private run;
+}