@wrtnlabs/evidence 0.0.0

package/lib/adapters/prisma/PrismaModelLoader.js

@@ -0,0 +1,268 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrismaModelLoader = void 0;
+const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
+const node_crypto_1 = require("node:crypto");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const typia_1 = __importDefault(require("typia"));
+const CanonicalJson_1 = require("../../internal/CanonicalJson");
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/gu;
+const CACHE_LIMIT = 16;
+const cache = new Map();
+/**
+ * Loads Prisma's resolved schema model through a consumer-compatible WASM bridge.
+ *
+ * The loader resolves the parser from the consumer first, caches complete
+ * schema-set outcomes by parser identity and content digest, and returns detached
+ * records that can outlive the WASM call.
+ */
+var PrismaModelLoader;
+(function (PrismaModelLoader) {
+    async function load(root, files) {
+        const parser = resolve(root);
+        const digest = schemaDigest(files);
+        const key = `${parser.origin}\0${parser.version}\0${digest}`;
+        const remembered = cache.get(key);
+        if (remembered !== undefined && remembered.models !== undefined)
+            return { models: structuredClone(remembered.models), digest };
+        if (remembered !== undefined && remembered.problem !== undefined)
+            throw new Error(remembered.problem);
+        let payload;
+        try {
+            payload = parser.getDatamodel(JSON.stringify({
+                prismaSchema: files.map((file) => [file.name, file.source.content]),
+            }));
+        }
+        catch (cause) {
+            const problem = `${failure(cause)} (parsed by @prisma/prisma-schema-wasm@${parser.version} resolved from the ${parser.origin})`;
+            remember(key, { problem });
+            throw new Error(problem);
+        }
+        let datamodel;
+        try {
+            datamodel = (() => {
+                const _ip0 = input => "string" === typeof input["name"];
+                const _ip1 = input => null === input["documentation"] || undefined === input["documentation"] || "string" === typeof input["documentation"];
+                const _ap0 = (input, _path, _exceptionable = true) => "string" === typeof input["name"] || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".name",
+                    expected: "string",
+                    value: input["name"]
+                }, _errorFactory);
+                const _ap1 = (input, _path, _exceptionable = true) => null === input["documentation"] || undefined === input["documentation"] || "string" === typeof input["documentation"] || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".documentation",
+                    expected: "(null | string | undefined)",
+                    value: input["documentation"]
+                }, _errorFactory);
+                const _ao0 = (input, _path, _exceptionable = true) => (Array.isArray(input.models) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".models",
+                    expected: "Array<IPrismaDatamodelModel>",
+                    value: input.models
+                }, _errorFactory)) && input.models.every((elem, _index3) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".models[" + _index3 + "]",
+                    expected: "IPrismaDatamodelModel",
+                    value: elem
+                }, _errorFactory)) && _ao1(elem, _path + ".models[" + _index3 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".models[" + _index3 + "]",
+                    expected: "IPrismaDatamodelModel",
+                    value: elem
+                }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".models",
+                    expected: "Array<IPrismaDatamodelModel>",
+                    value: input.models
+                }, _errorFactory);
+                const _ao1 = (input, _path, _exceptionable = true) => _ap0(input, _path, true && _exceptionable) && _ap1(input, _path, true && _exceptionable) && ((Array.isArray(input.fields) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".fields",
+                    expected: "Array<IPrismaDatamodelField>",
+                    value: input.fields
+                }, _errorFactory)) && input.fields.every((elem, _index4) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".fields[" + _index4 + "]",
+                    expected: "IPrismaDatamodelField",
+                    value: elem
+                }, _errorFactory)) && _ao2(elem, _path + ".fields[" + _index4 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".fields[" + _index4 + "]",
+                    expected: "IPrismaDatamodelField",
+                    value: elem
+                }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".fields",
+                    expected: "Array<IPrismaDatamodelField>",
+                    value: input.fields
+                }, _errorFactory));
+                const _ao2 = (input, _path, _exceptionable = true) => _ap0(input, _path, true && _exceptionable) && ("string" === typeof input.kind || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.json.assertParse",
+                    path: _path + ".kind",
+                    expected: "string",
+                    value: input.kind
+                }, _errorFactory)) && _ap1(input, _path, true && _exceptionable);
+                const _io0 = input => Array.isArray(input.models) && input.models.every(elem => "object" === typeof elem && null !== elem && _io1(elem));
+                const _io1 = input => _ip0(input) && _ip1(input) && (Array.isArray(input.fields) && input.fields.every(elem => "object" === typeof elem && null !== elem && _io2(elem)));
+                const _io2 = input => _ip0(input) && "string" === typeof input.kind && _ip1(input);
+                const __is = input => "object" === typeof input && null !== input && _io0(input);
+                let _errorFactory;
+                const __assert = (input, errorFactory) => {
+                    if (false === __is(input)) {
+                        _errorFactory = errorFactory;
+                        ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input || _assertGuard_1._assertGuard(true, {
+                            method: "typia.json.assertParse",
+                            path: _path + "",
+                            expected: "IPrismaDatamodel",
+                            value: input
+                        }, _errorFactory)) && _ao0(input, _path + "", true) || _assertGuard_1._assertGuard(true, {
+                            method: "typia.json.assertParse",
+                            path: _path + "",
+                            expected: "IPrismaDatamodel",
+                            value: input
+                        }, _errorFactory))(input, "$input", true);
+                    }
+                    return input;
+                };
+                return (input, errorFactory) => __assert(JSON.parse(input), errorFactory);
+            })()(payload);
+        }
+        catch (cause) {
+            throw new Error(`The Prisma parser returned an incompatible datamodel payload: ${message(cause)}`);
+        }
+        const models = datamodel.models.map(model);
+        remember(key, { models });
+        return { models: structuredClone(models), digest };
+    }
+    PrismaModelLoader.load = load;
+    function model(input) {
+        return {
+            name: input.name,
+            documentation: input.documentation ?? "",
+            digest: CanonicalJson_1.CanonicalJson.digest(CanonicalJson_1.CanonicalJson.without(input, ["documentation", "fields"])),
+            fields: input.fields.map((field) => ({
+                name: field.name,
+                symbol: field.kind === "object" ? "relation" : "column",
+                documentation: field.documentation ?? "",
+                digest: CanonicalJson_1.CanonicalJson.digest(CanonicalJson_1.CanonicalJson.without(field, ["documentation"])),
+            })),
+        };
+    }
+    function resolve(root) {
+        const failures = [];
+        for (const origin of ["project", "package"]) {
+            try {
+                const resolver = origin === "project"
+                    ? (0, node_module_1.createRequire)(node_path_1.default.join(root, "package.json"))
+                    : (0, node_module_1.createRequire)(__filename);
+                const manifest = resolver("@prisma/prisma-schema-wasm/package.json");
+                const module = resolver("@prisma/prisma-schema-wasm");
+                if (typeof module !== "object" ||
+                    module === null ||
+                    !("get_datamodel" in module) ||
+                    typeof module.get_datamodel !== "function")
+                    throw new Error("the module exposes no get_datamodel function");
+                const getDatamodel = module.get_datamodel;
+                return {
+                    getDatamodel(parameters) {
+                        const output = getDatamodel(parameters);
+                        if (typeof output !== "string")
+                            throw new Error("the parser returned a non-string payload");
+                        return output;
+                    },
+                    version: version(manifest),
+                    origin,
+                };
+            }
+            catch (cause) {
+                failures.push(`${origin}: ${message(cause)}`);
+            }
+        }
+        throw new Error(`No Prisma schema parser could be resolved (${failures.join("; ")}).`);
+    }
+    function version(manifest) {
+        if (typeof manifest === "object" &&
+            manifest !== null &&
+            "version" in manifest &&
+            typeof manifest.version === "string")
+            return manifest.version;
+        return "unknown";
+    }
+    function schemaDigest(files) {
+        const hash = (0, node_crypto_1.createHash)("sha256");
+        for (const file of files) {
+            hash.update(file.name);
+            hash.update("\0");
+            hash.update(file.source.digest);
+            hash.update("\n");
+        }
+        return hash.digest("hex");
+    }
+    function remember(key, entry) {
+        if (cache.has(key))
+            return;
+        while (cache.size >= CACHE_LIMIT) {
+            const oldest = cache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            cache.delete(oldest);
+        }
+        cache.set(key, structuredClone(entry));
+    }
+    function failure(cause) {
+        const raw = message(cause);
+        try {
+            const envelope = JSON.parse(raw);
+            if (typeof envelope === "object" &&
+                envelope !== null &&
+                "message" in envelope &&
+                typeof envelope.message === "string")
+                return envelope.message.replace(ANSI_PATTERN, "").trim();
+        }
+        catch {
+            // A non-JSON error already is the complete parser message.
+        }
+        return raw.replace(ANSI_PATTERN, "").trim();
+    }
+    function message(cause) {
+        return cause instanceof Error ? cause.message : String(cause);
+    }
+})(PrismaModelLoader || (exports.PrismaModelLoader = PrismaModelLoader = {}));

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

@@ -0,0 +1,9 @@
+/**
+ * Shared lexical rules that do not determine Prisma schema semantics.
+ *
+ * Target and position helpers use these checks for safe identifier spelling;
+ * the Prisma WASM parser remains the authority on whether a schema is valid.
+ */
+export declare namespace PrismaSyntax {
+    function identifier(value: string): boolean;
+}

package/lib/adapters/prisma/PrismaSyntax.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrismaSyntax = void 0;
+const LETTER = /^\p{L}$/u;
+const NUMBER = /^\p{N}$/u;
+/**
+ * Shared lexical rules that do not determine Prisma schema semantics.
+ *
+ * Target and position helpers use these checks for safe identifier spelling;
+ * the Prisma WASM parser remains the authority on whether a schema is valid.
+ */
+var PrismaSyntax;
+(function (PrismaSyntax) {
+    function identifier(value) {
+        const characters = Array.from(value);
+        const first = characters[0];
+        return (first !== undefined &&
+            initial(first) &&
+            characters
+                .slice(1)
+                .every((character) => initial(character) || character === "_" || character === "-"));
+    }
+    PrismaSyntax.identifier = identifier;
+    function initial(character) {
+        return LETTER.test(character) || NUMBER.test(character);
+    }
+})(PrismaSyntax || (exports.PrismaSyntax = PrismaSyntax = {}));

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

@@ -0,0 +1,10 @@
+import type { IEvidenceAddress } from "../../structures/IEvidenceAddress";
+/**
+ * Parses one file-independent Prisma model or member target.
+ *
+ * Prisma references use the `prisma:` prefix because their parser-established
+ * identities can span files, leaving the returned file key as a fixed namespace.
+ */
+export declare namespace PrismaTarget {
+    function parse(target: string): IEvidenceAddress;
+}

package/lib/adapters/prisma/PrismaTarget.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrismaTarget = void 0;
+const PrismaSyntax_1 = require("./PrismaSyntax");
+/**
+ * Parses one file-independent Prisma model or member target.
+ *
+ * Prisma references use the `prisma:` prefix because their parser-established
+ * identities can span files, leaving the returned file key as a fixed namespace.
+ */
+var PrismaTarget;
+(function (PrismaTarget) {
+    function parse(target) {
+        if (!target.startsWith("prisma:"))
+            throw new Error("Start a Prisma target with 'prisma:'.");
+        const segments = target.slice("prisma:".length).split(".");
+        if ((segments.length !== 1 && segments.length !== 2) ||
+            segments.some((segment) => !PrismaSyntax_1.PrismaSyntax.identifier(segment)))
+            throw new Error("Use prisma:Model or prisma:Model.member with valid Prisma identifiers.");
+        return { file: "prisma:", segments };
+    }
+    PrismaTarget.parse = parse;
+})(PrismaTarget || (exports.PrismaTarget = PrismaTarget = {}));

package/lib/adapters/python/EvidencePythonAdapter.d.ts

@@ -0,0 +1,15 @@
+import { PythonAdapter } from "./PythonAdapter";
+/**
+ * Extracts statically declared Python exports with bounded import and __all__ resolution.
+ *
+ * The adapter reconciles selected modules before publishing file-qualified paths.
+ * Docstrings and eligible adjacent comments supply mapped evidence text. Instance
+ * members use a prototype segment; class members remain directly under their
+ * owner, preserving the difference between the two public surfaces.
+ *
+ * Module execution, dynamic __all__ mutation, and decorator- or metaclass-generated
+ * members are not evaluated. These mechanisms cannot justify omitting unknown
+ * declarations while reporting complete coverage.
+ */
+export declare class EvidencePythonAdapter extends PythonAdapter {
+}

package/lib/adapters/python/EvidencePythonAdapter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidencePythonAdapter = void 0;
+const PythonAdapter_1 = require("./PythonAdapter");
+/**
+ * Extracts statically declared Python exports with bounded import and __all__ resolution.
+ *
+ * The adapter reconciles selected modules before publishing file-qualified paths.
+ * Docstrings and eligible adjacent comments supply mapped evidence text. Instance
+ * members use a prototype segment; class members remain directly under their
+ * owner, preserving the difference between the two public surfaces.
+ *
+ * Module execution, dynamic __all__ mutation, and decorator- or metaclass-generated
+ * members are not evaluated. These mechanisms cannot justify omitting unknown
+ * declarations while reporting complete coverage.
+ */
+class EvidencePythonAdapter extends PythonAdapter_1.PythonAdapter {
+}
+exports.EvidencePythonAdapter = EvidencePythonAdapter;

package/lib/adapters/python/IPythonAll.d.ts

@@ -0,0 +1,24 @@
+import type { PythonAllState } from "./PythonAllState";
+/**
+ * Records the statically known portion of a module's `__all__` declaration.
+ *
+ * PythonExportResolver uses this state to choose between explicit exports and
+ * Python's underscore convention. Dynamic mutation stays incomplete because
+ * executing module code would make coverage depend on runtime state.
+ */
+export interface IPythonAll {
+    /**
+     * Whether `__all__` is absent, fully static, or changed dynamically.
+     *
+     * A dynamic state suppresses inference from arbitrary runtime mutations while
+     * allowing the scanner to retain the failure diagnostic.
+     */
+    state: PythonAllState;
+    /**
+     * Export names recovered from supported literal assignment and concatenation.
+     *
+     * The array preserves declaration order; the resolver later converts it to a
+     * set when it combines explicit exports with imported bindings.
+     */
+    names: string[];
+}

package/lib/adapters/python/IPythonAll.js

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

package/lib/adapters/python/IPythonBinding.d.ts

@@ -0,0 +1,52 @@
+import type { PythonBindingKind } from "./PythonBindingKind";
+/**
+ * Describes one source-ordered module binding used for static export resolution.
+ *
+ * The resolver selects the latest compatible binding for a name and follows
+ * imports without executing Python. Unsupported or ambiguous paths become
+ * diagnostics rather than silently reducing the public population.
+ */
+export interface IPythonBinding {
+    /**
+     * Binding form that determines how the resolver follows this entry.
+     *
+     * Local bindings point at scanned declaration roots; import forms require a
+     * source-snapshot module target.
+     */
+    kind: PythonBindingKind;
+    /**
+     * Source-order key for Python's later-binding-wins behavior.
+     *
+     * It is derived from the statement position with a local tie-breaker for
+     * entries in the same import statement.
+     */
+    order: number;
+    /**
+     * Name introduced in the containing module namespace.
+     *
+     * Omission represents an unusable or incomplete binding and prevents it from
+     * being selected as a public export.
+     */
+    localName?: string;
+    /**
+     * Declaration root selected by a local binding.
+     *
+     * Imports omit this field because their target must be resolved against
+     * another module before a declaration can be materialized.
+     */
+    root?: string;
+    /**
+     * Name requested from an imported module by a named import.
+     *
+     * Namespace and star imports omit it: their member name comes from the
+     * subsequent attribute lookup or the requesting public name.
+     */
+    importedName?: string;
+    /**
+     * Static absolute or relative module spelling from the import statement.
+     *
+     * Omission keeps an incomplete binding from resolving outside the scanned
+     * source snapshot.
+     */
+    specifier?: string;
+}

package/lib/adapters/python/IPythonBinding.js

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

package/lib/adapters/python/IPythonClassContext.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Carries the structural ownership needed while scanning one Python class body.
+ *
+ * Nested functions and properties inherit these segments to keep their unit IDs
+ * stable, while exported addresses can still distinguish a class member from an
+ * instance member through the suffix selected by the scanner.
+ */
+export interface IPythonClassContext {
+    /**
+     * Full semantic path used to construct child unit identities.
+     *
+     * Every element names one enclosing declaration, in source nesting order.
+     */
+    identity: string[];
+    /**
+     * Public-address segments preceding a member declared in this class.
+     *
+     * The scanner appends a member's own segments without using this path as its
+     * semantic identity, because aliases may publish that identity elsewhere.
+     */
+    suffix: string[];
+    /**
+     * Module-level root binding under which this class is declared.
+     *
+     * Export resolution associates the root with a local binding before it emits
+     * public file-qualified addresses.
+     */
+    root: string;
+    /**
+     * Unit ID of the enclosing class declaration.
+     *
+     * Members use this parent so ancestor withdrawal directives hide the complete
+     * class surface during documentation materialization.
+     */
+    parentId: string;
+}

package/lib/adapters/python/IPythonClassContext.js

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

package/lib/adapters/python/IPythonDocumentation.d.ts

@@ -0,0 +1,47 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IPythonDocumentationAttachment } from "./IPythonDocumentationAttachment";
+/**
+ * Retains one Python docstring or adjacent comment run after parsing.
+ *
+ * The scanner keeps source coordinates and either a precomputed mapping or the
+ * syntax needed to derive one. PythonAdapter attaches the text only after it
+ * knows which declarations are part of the public export surface.
+ */
+export interface IPythonDocumentation {
+    /**
+     * Stable identifier for this text region within its source file.
+     *
+     * It becomes the evidence-host ID when the text is supported and attached.
+     */
+    id: string;
+    /**
+     * Byte and coordinate range occupied by the original documentation text.
+     *
+     * Annotation ranges exclude this source slice from a unit fingerprint when
+     * it contains Evidence directives.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Delimiter rules for mapping a raw docstring or comment run on demand.
+     *
+     * Omission means `mapping` already carries the normalized documentation;
+     * neither form may be absent when the adapter parses evidence tags.
+     */
+    syntax?: IEvidenceCommentSyntax;
+    /**
+     * Normalized documentation text when scanning already established its shape.
+     *
+     * The adapter clones this mapping before tag parsing because attachment and
+     * withdrawal phases must not mutate scanner-owned analysis data.
+     */
+    mapping?: IEvidenceDocumentation;
+    /**
+     * Declaration positions and candidate units that this text can document.
+     *
+     * One text region can attach to several accessors at one position; export and
+     * withdrawal filtering determine its final visible host membership.
+     */
+    attachments: IPythonDocumentationAttachment[];
+}

package/lib/adapters/python/IPythonDocumentation.js

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

package/lib/adapters/python/IPythonDocumentationAttachment.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Connects one parsed Python documentation region to a declaration position.
+ *
+ * Scanning retains this compact relationship after its Tree-sitter session
+ * closes. PythonAdapter later filters it by public reachability before creating
+ * evidence hosts, so a private declaration's docstring cannot document an
+ * exported unit by accident.
+ */
+export interface IPythonDocumentationAttachment {
+    /**
+     * Scanner-local identity of the declaration position that owns this text.
+     *
+     * Hosts use the same identity to avoid publishing a second undocumented host
+     * for a declaration that already has an attached docstring or comment run.
+     */
+    positionId: string;
+    /**
+     * Stable declaration-site identity shared by every unit at this position.
+     *
+     * A property getter and setter may have distinct units but one source site;
+     * the host records that common site once.
+     */
+    siteId: string;
+    /**
+     * Candidate unit receiving directives parsed from this documentation.
+     *
+     * The adapter discards this attachment unless export resolution publishes the
+     * unit, preserving Python's public-surface boundary.
+     */
+    unitId: string;
+}

package/lib/adapters/python/IPythonDocumentationAttachment.js

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

package/lib/adapters/python/IPythonFileAnalysis.d.ts

@@ -0,0 +1,63 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IPythonAll } from "./IPythonAll";
+import type { IPythonBinding } from "./IPythonBinding";
+import type { IPythonDocumentation } from "./IPythonDocumentation";
+import type { IPythonHostPosition } from "./IPythonHostPosition";
+import type { IPythonOwnedUnit } from "./IPythonOwnedUnit";
+/**
+ * Preserves one Python file's serializable extraction after parsing.
+ *
+ * PythonAdapter combines these records before resolving imports and exports, so
+ * parser-owned nodes never escape their session and failures remain visible.
+ */
+export interface IPythonFileAnalysis {
+    /**
+     * Selected source whose declarations and diagnostics this analysis owns.
+     *
+     * Its physical path anchors units, annotation ranges, and diagnostic locations.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Static knowledge of the module's explicit export list.
+     *
+     * The resolver falls back to underscore-based visibility only when this state permits it.
+     */
+    all: IPythonAll;
+    /**
+     * Source-ordered namespace bindings available to export resolution.
+     *
+     * Later entries may replace earlier names under Python binding semantics.
+     */
+    bindings: IPythonBinding[];
+    /**
+     * Lexically scanned declarations awaiting public-path publication.
+     *
+     * Entries can be removed when no supported export reaches their root.
+     */
+    units: IPythonOwnedUnit[];
+    /**
+     * Declaration sites that may receive a documentation host.
+     *
+     * Positions keep shared accessors from producing duplicate hosts.
+     */
+    positions: IPythonHostPosition[];
+    /**
+     * Parsed docstrings and adjacent comment runs from this file.
+     *
+     * Attachment is deferred until the exported population is known.
+     */
+    documentation: IPythonDocumentation[];
+    /**
+     * Source failures encountered while classifying this file.
+     *
+     * They are carried into the inventory so incomplete extraction cannot certify coverage.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * Whether scanning classified every surface-changing construct in this file.
+     *
+     * A false value propagates to the completed inventory even if other files succeed.
+     */
+    complete: boolean;
+}

package/lib/adapters/python/IPythonFileAnalysis.js

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