@wrtnlabs/evidence 0.0.0

package/lib/adapters/python/PythonAdapter.js

@@ -0,0 +1,488 @@
+"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.PythonAdapter = void 0;
+const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
+const typia_1 = __importDefault(require("typia"));
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+const EvidenceInventory_1 = require("../../graph/EvidenceInventory");
+const EvidenceParser_1 = require("../../parsers/EvidenceParser");
+const EvidenceParserError_1 = require("../../parsers/EvidenceParserError");
+const EvidenceTagParser_1 = require("../../parsers/EvidenceTagParser");
+const PythonExportResolver_1 = require("./PythonExportResolver");
+const PythonFileScanner_1 = require("./PythonFileScanner");
+/**
+ * Extracts Python declarations through bounded static export and re-export analysis.
+ *
+ * File scanning records candidate units, bindings, and docstring ownership before
+ * PythonExportResolver determines which identities are publicly reachable. Only
+ * published owners receive eligible documentation hosts; parser and export
+ * failures remain incomplete inventory diagnostics instead of shrinking coverage.
+ */
+class PythonAdapter {
+    /**
+     * Artifact family selecting Python parsing and public-surface rules.
+     *
+     * The common adapter contract uses this discriminator independently of query selectors.
+     */
+    type = "python";
+    /**
+     * Builds an owned inventory from the supplied Python source snapshot.
+     *
+     * The method validates and clones input, scans with a bounded parser runtime,
+     * resolves public exports, and materializes annotations on their published owners.
+     * Native resources close in cleanup even when extraction fails.
+     */
+    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 _ap0 = (input, _path, _exceptionable = true) => "string" === typeof input["absolute"] || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".absolute",
+                expected: "string",
+                value: input["absolute"]
+            }, _errorFactory);
+            const _ap1 = (input, _path, _exceptionable = true) => "string" === typeof input["display"] || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".display",
+                expected: "string",
+                value: input["display"]
+            }, _errorFactory);
+            const _ap2 = (input, _path, _exceptionable = true) => "string" === typeof input["path"] || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".path",
+                expected: "string",
+                value: input["path"]
+            }, _errorFactory);
+            const _ae0 = "(\"case-mismatch\" | \"invalid-encoding\" | \"not-file\" | \"path-unreadable\" | \"root-unreadable\" | \"source-changed\" | \"symlink-cycle\")";
+            const _ao0 = (input, _path, _exceptionable = true) => (("object" === typeof input.root && null !== input.root || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".root",
+                expected: "IEvidenceSourceRoot",
+                value: input.root
+            }, _errorFactory)) && _ao1(input.root, _path + ".root", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".root",
+                expected: "IEvidenceSourceRoot",
+                value: input.root
+            }, _errorFactory)) && ((Array.isArray(input.files) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".files",
+                expected: "Array<IEvidenceSourceFile>",
+                value: input.files
+            }, _errorFactory)) && input.files.every((elem, _index5) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".files[" + _index5 + "]",
+                expected: "IEvidenceSourceFile",
+                value: elem
+            }, _errorFactory)) && _ao2(elem, _path + ".files[" + _index5 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".files[" + _index5 + "]",
+                expected: "IEvidenceSourceFile",
+                value: elem
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".files",
+                expected: "Array<IEvidenceSourceFile>",
+                value: input.files
+            }, _errorFactory)) && ((Array.isArray(input.dependencies) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".dependencies",
+                expected: "Array<IEvidenceSourceDependency>",
+                value: input.dependencies
+            }, _errorFactory)) && input.dependencies.every((elem, _index6) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".dependencies[" + _index6 + "]",
+                expected: "IEvidenceSourceDependency",
+                value: elem
+            }, _errorFactory)) && _ao4(elem, _path + ".dependencies[" + _index6 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".dependencies[" + _index6 + "]",
+                expected: "IEvidenceSourceDependency",
+                value: elem
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".dependencies",
+                expected: "Array<IEvidenceSourceDependency>",
+                value: input.dependencies
+            }, _errorFactory)) && ((Array.isArray(input.diagnostics) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".diagnostics",
+                expected: "Array<IEvidenceSourceDiagnostic>",
+                value: input.diagnostics
+            }, _errorFactory)) && input.diagnostics.every((elem, _index7) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".diagnostics[" + _index7 + "]",
+                expected: "IEvidenceSourceDiagnostic",
+                value: elem
+            }, _errorFactory)) && _ao5(elem, _path + ".diagnostics[" + _index7 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".diagnostics[" + _index7 + "]",
+                expected: "IEvidenceSourceDiagnostic",
+                value: elem
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".diagnostics",
+                expected: "Array<IEvidenceSourceDiagnostic>",
+                value: input.diagnostics
+            }, _errorFactory)) && ("boolean" === typeof input.complete || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".complete",
+                expected: "boolean",
+                value: input.complete
+            }, _errorFactory));
+            const _ao1 = (input, _path, _exceptionable = true) => ("string" === typeof input.declared || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".declared",
+                expected: "string",
+                value: input.declared
+            }, _errorFactory)) && _ap0(input, _path, true && _exceptionable) && (undefined === input.physical || "string" === typeof input.physical || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".physical",
+                expected: "(string | undefined)",
+                value: input.physical
+            }, _errorFactory)) && _ap1(input, _path, true && _exceptionable);
+            const _ao2 = (input, _path, _exceptionable = true) => ("string" === typeof input.id || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".id",
+                expected: "string",
+                value: input.id
+            }, _errorFactory)) && ("string" === typeof input.physicalPath || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".physicalPath",
+                expected: "string",
+                value: input.physicalPath
+            }, _errorFactory)) && ("string" === typeof input.content || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".content",
+                expected: "string",
+                value: input.content
+            }, _errorFactory)) && ("string" === typeof input.digest || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".digest",
+                expected: "string",
+                value: input.digest
+            }, _errorFactory)) && ((Array.isArray(input.addresses) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".addresses",
+                expected: "Array<IEvidenceSourceAddress>",
+                value: input.addresses
+            }, _errorFactory)) && input.addresses.every((elem, _index8) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".addresses[" + _index8 + "]",
+                expected: "IEvidenceSourceAddress",
+                value: elem
+            }, _errorFactory)) && _ao3(elem, _path + ".addresses[" + _index8 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".addresses[" + _index8 + "]",
+                expected: "IEvidenceSourceAddress",
+                value: elem
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".addresses",
+                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, {
+                method: "typia.assert",
+                path: _path + ".relative",
+                expected: "string",
+                value: input.relative
+            }, _errorFactory)) && _ap1(input, _path, true && _exceptionable) && (undefined === input.selected || "boolean" === typeof input.selected || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".selected",
+                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, {
+                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, {
+                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, {
+                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 _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 __is = input => "object" === typeof input && null !== input && _io0(input);
+            let _errorFactory;
+            return (input, errorFactory) => {
+                if (false === __is(input)) {
+                    _errorFactory = errorFactory;
+                    ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input || _assertGuard_1._assertGuard(true, {
+                        method: "typia.assert",
+                        path: _path + "",
+                        expected: "IEvidenceSourceSnapshot",
+                        value: input
+                    }, _errorFactory)) && _ao0(input, _path + "", true) || _assertGuard_1._assertGuard(true, {
+                        method: "typia.assert",
+                        path: _path + "",
+                        expected: "IEvidenceSourceSnapshot",
+                        value: input
+                    }, _errorFactory))(input, "$input", true);
+                }
+                return input;
+            };
+        })()(snapshot));
+        const inventory = {
+            schemaVersion: 1,
+            sources: input.files,
+            annotationRanges: [],
+            units: [],
+            addresses: [],
+            hosts: [],
+            declarations: [],
+            reviews: [],
+            diagnostics: input.diagnostics.map((diagnostic) => ({
+                code: `source-${diagnostic.code}`,
+                severity: "error",
+                message: diagnostic.message,
+                repair: "Restore access to the selected Python source before evaluating coverage.",
+                location: { file: diagnostic.path },
+            })),
+            dependencies: input.dependencies,
+            complete: input.complete,
+        };
+        const parser = new EvidenceParser_1.EvidenceParser();
+        try {
+            const analyses = await Promise.all(input.files.map((source) => this.scan(parser, source)));
+            for (const analysis of analyses) {
+                inventory.units.push(...analysis.units.map((entry) => entry.unit));
+                inventory.diagnostics.push(...analysis.diagnostics);
+                inventory.complete &&= analysis.complete;
+            }
+            // Public reachability must be settled before docstrings become eligible
+            // hosts; merely scanning a local declaration cannot make it public evidence.
+            const published = new PythonExportResolver_1.PythonExportResolver(analyses, inventory, input.root).publish();
+            inventory.units = inventory.units.filter((unit) => published.has(unit.id));
+            this.materializeDocumentation(inventory, analyses, published);
+            return new EvidenceInventory_1.EvidenceInventory([inventory]).snapshot();
+        }
+        finally {
+            await parser.close();
+        }
+    }
+    /**
+     * Copies one Python file's declarations and bindings out of a borrowed parse session.
+     *
+     * A parse failure returns an explicitly incomplete analysis with its source
+     * location, preserving the failure when other files can still be scanned.
+     */
+    async scan(parser, source) {
+        const file = source.addresses[0]?.relative ?? source.physicalPath;
+        try {
+            return await parser.parse({ type: "python", file, content: source.content }, (session) => new PythonFileScanner_1.PythonFileScanner(session, source).scan());
+        }
+        catch (cause) {
+            const parserError = cause instanceof EvidenceParserError_1.EvidenceParserError ? cause : undefined;
+            return {
+                source,
+                all: { state: "absent", names: [] },
+                bindings: [],
+                units: [],
+                positions: [],
+                documentation: [],
+                diagnostics: [
+                    {
+                        code: `python-${parserError?.code ?? "parse-failed"}`,
+                        severity: "error",
+                        message: parserError?.message ??
+                            `Python parsing failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+                        repair: "Correct the source or add adapter support before evaluating coverage.",
+                        location: {
+                            file: source.physicalPath,
+                            ...(parserError?.range === undefined
+                                ? {}
+                                : { range: parserError.range }),
+                        },
+                    },
+                ],
+                complete: false,
+            };
+        }
+    }
+    /**
+     * Attaches parsed documentation only after exported identity selection is known.
+     *
+     * Withdrawal directives are collected before visible hosts are finalized, so
+     * hidden parents cannot leave descendants as eligible evidence carriers.
+     */
+    materializeDocumentation(inventory, analyses, published) {
+        const units = new Map(inventory.units.map((unit) => [unit.id, unit]));
+        for (const analysis of analyses)
+            for (const documentation of analysis.documentation) {
+                const attachments = documentation.attachments.filter((entry) => published.has(entry.unitId));
+                if (attachments.length === 0 &&
+                    !this.annotation(analysis, documentation))
+                    continue;
+                inventory.annotationRanges.push({
+                    file: analysis.source.physicalPath,
+                    range: documentation.range,
+                });
+                const siteId = attachments[0]?.siteId;
+                const unitIds = Array.from(new Set(attachments.map((entry) => entry.unitId)));
+                const candidate = this.host(analysis.source, documentation, siteId, unitIds);
+                if (candidate.attachment === "attached") {
+                    const parsed = this.parse(analysis.source, documentation, candidate);
+                    for (const unitId of unitIds) {
+                        const unit = units.get(unitId);
+                        if (unit !== undefined)
+                            unit.withdrawals.push(...parsed.withdrawals);
+                    }
+                }
+            }
+        const hidden = new Set();
+        for (const unit of inventory.units)
+            if (this.withdrawn(unit.id, units, new Set()))
+                hidden.add(unit.id);
+        for (const analysis of analyses)
+            for (const documentation of analysis.documentation) {
+                const publishedAttachments = documentation.attachments.filter((entry) => published.has(entry.unitId));
+                const attachments = publishedAttachments.filter((entry) => !hidden.has(entry.unitId));
+                if (attachments.length === 0 &&
+                    publishedAttachments.length !== 0 &&
+                    !this.claimAnnotation(analysis, documentation))
+                    continue;
+                if (attachments.length === 0 &&
+                    !this.annotation(analysis, documentation))
+                    continue;
+                const siteId = attachments[0]?.siteId;
+                const positionId = attachments[0]?.positionId;
+                const unitIds = Array.from(new Set(attachments
+                    .filter((entry) => entry.positionId === positionId && entry.siteId === siteId)
+                    .map((entry) => entry.unitId)));
+                const host = this.host(analysis.source, documentation, siteId, unitIds);
+                inventory.hosts.push(host);
+                const parsed = this.parse(analysis.source, documentation, host);
+                inventory.declarations.push(...parsed.declarations);
+                inventory.reviews.push(...parsed.reviews);
+                inventory.diagnostics.push(...parsed.diagnostics);
+            }
+        this.materializeUndocumentedHosts(inventory, analyses, published, hidden);
+    }
+    materializeUndocumentedHosts(inventory, analyses, published, hidden) {
+        const documented = new Set(analyses.flatMap((analysis) => analysis.documentation.flatMap((documentation) => documentation.attachments.flatMap((attachment) => published.has(attachment.unitId) && !hidden.has(attachment.unitId)
+            ? [attachment.positionId]
+            : []))));
+        for (const analysis of analyses)
+            for (const position of analysis.positions) {
+                if (documented.has(position.id))
+                    continue;
+                const unitIds = position.unitIds.filter((unitId) => published.has(unitId) && !hidden.has(unitId));
+                if (unitIds.length === 0)
+                    continue;
+                inventory.hosts.push({
+                    id: `${position.id}:host`,
+                    file: analysis.source.physicalPath,
+                    range: position.range,
+                    origins: analysis.source.addresses.map((address) => address.absolute),
+                    siteId: position.siteId,
+                    unitIds,
+                    attachment: "attached",
+                });
+            }
+    }
+    host(source, documentation, siteId, unitIds) {
+        const attached = siteId !== undefined && unitIds.length !== 0;
+        return {
+            id: documentation.id,
+            file: source.physicalPath,
+            range: documentation.range,
+            origins: source.addresses.map((address) => address.absolute),
+            unitIds,
+            attachment: attached ? "attached" : "unsupported",
+            ...(attached ? { siteId } : {}),
+            ...(attached
+                ? {}
+                : {
+                    problem: "Move the annotation into a declaration docstring or an adjacent same-indent comment run on a supported public Python declaration.",
+                }),
+        };
+    }
+    parse(source, documentation, host) {
+        const mapped = this.mapping(source, documentation);
+        return EvidenceTagParser_1.EvidenceTagParser.parse(source.content, host, mapped);
+    }
+    annotation(analysis, documentation) {
+        return this.annotationPattern(this.mapping(analysis.source, documentation).text, true);
+    }
+    claimAnnotation(analysis, documentation) {
+        return this.annotationPattern(this.mapping(analysis.source, documentation).text, false);
+    }
+    annotationPattern(raw, withdrawal) {
+        return withdrawal
+            ? /(?:^|[\r\n])[ \t]*@(evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link|internal|hidden|ignore)\b/u.test(raw)
+            : /(?:^|[\r\n])[ \t]*@(evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link)\b/u.test(raw);
+    }
+    mapping(source, documentation) {
+        if (documentation.mapping !== undefined)
+            return structuredClone(documentation.mapping);
+        if (documentation.syntax === undefined)
+            throw new Error("Python documentation has no source mapping.");
+        return EvidenceDocumentation_1.EvidenceDocumentation.read(source.content, documentation.id, documentation.range, documentation.syntax);
+    }
+    withdrawn(id, units, visited) {
+        if (visited.has(id))
+            return false;
+        visited.add(id);
+        const unit = units.get(id);
+        if (unit === undefined)
+            return false;
+        if (unit.withdrawals.length !== 0)
+            return true;
+        return unit.parentId === undefined
+            ? false
+            : this.withdrawn(unit.parentId, units, visited);
+    }
+}
+exports.PythonAdapter = PythonAdapter;

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

@@ -0,0 +1,7 @@
+/**
+ * Classifies how completely the scanner can determine a module's `__all__` value.
+ *
+ * PythonExportResolver uses this state to select explicit exports or underscore
+ * visibility, while a dynamic value preserves an incomplete analysis diagnostic.
+ */
+export type PythonAllState = "absent" | "static" | "dynamic";

package/lib/adapters/python/PythonAllState.js

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

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

@@ -0,0 +1,7 @@
+/**
+ * Identifies the static form by which a name enters a Python module namespace.
+ *
+ * PythonExportResolver uses the form to decide whether it can publish a local
+ * root or must follow a named, namespace, or star import within the snapshot.
+ */
+export type PythonBindingKind = "local" | "named" | "namespace" | "star";

package/lib/adapters/python/PythonBindingKind.js

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

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

@@ -0,0 +1,146 @@
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceRoot } from "../../structures/IEvidenceSourceRoot";
+import type { IPythonFileAnalysis } from "./IPythonFileAnalysis";
+/**
+ * Resolves Python module exports across a complete source snapshot.
+ *
+ * The Python adapter records file-local declarations first, then this resolver
+ * follows imports and `__all__` so the inventory exposes the public addresses
+ * through which callers can reach each owned unit.
+ */
+export declare class PythonExportResolver {
+    private readonly inventory;
+    private readonly root;
+    /**
+     * Modules indexed by their source identities.
+     *
+     * Each record combines the scanner's local bindings with the names currently
+     * considered public while star imports are expanded.
+     */
+    private readonly modules;
+    /**
+     * Source identities grouped by normalized physical and public locations.
+     *
+     * Import resolution uses this index to reject missing and ambiguous module
+     * targets without depending on the host filesystem.
+     */
+    private readonly locations;
+    /**
+     * Memoized module targets for import specifiers, including unresolved ones.
+     *
+     * Caching `undefined` prevents duplicate diagnostics while the same import is
+     * encountered through multiple reexports.
+     */
+    private readonly targets;
+    /**
+     * Memoized binding resolutions keyed by source, name, and visibility mode.
+     *
+     * Declared and public lookup differ for star imports, so both modes form part
+     * of the cache key.
+     */
+    private readonly resolutions;
+    /**
+     * Diagnostic keys already emitted for this snapshot.
+     *
+     * A single unsupported import may be reached through several exports but must
+     * make the inventory incomplete only once.
+     */
+    private readonly reported;
+    /**
+     * Initializes the resolver from file-local Python analyses.
+     *
+     * The constructor derives each module's initial public names before expanding
+     * transitive star imports, because that fixed point defines later lookups.
+     */
+    constructor(analyses: IPythonFileAnalysis[], inventory: IEvidenceInventory, root: IEvidenceSourceRoot);
+    /**
+     * Materializes public addresses for every resolved exported binding.
+     *
+     * Returns semantic unit IDs that received at least one address. Unresolvable
+     * public names record diagnostics instead of silently shrinking coverage.
+     */
+    publish(): Set<string>;
+    /**
+     * Adds names introduced by transitive star imports until none remain.
+     *
+     * A fixed-point pass is necessary because one imported module can itself
+     * obtain public names from another star import.
+     */
+    private expandStars;
+    /**
+     * Resolves one name from a source module with memoization.
+     *
+     * Resolution mode distinguishes a module's declared bindings from the names
+     * it publicly reexports through `__all__` or star imports.
+     */
+    private resolve;
+    /**
+     * Resolves a name recursively while detecting declaration-free import cycles.
+     *
+     * Later bindings win in Python. Star bindings participate only when no later
+     * explicit binding shadows the requested name.
+     */
+    private resolveFrom;
+    /**
+     * Converts a selected binding into local units or a recursive import lookup.
+     *
+     * Namespace imports intentionally preserve only the target module so address
+     * publication can append its reachable member paths.
+     */
+    private resolveBinding;
+    /**
+     * Publishes addresses reachable through one resolved binding.
+     *
+     * Namespace bindings recurse through their public members; root bindings map
+     * matching owned units onto every public address of the entry source.
+     */
+    private publishBinding;
+    /**
+     * Finds the unique in-snapshot module selected by an import specifier.
+     *
+     * Imports leaving the configured root, missing snapshot files, and physical
+     * aliases are reported because each would make export coverage unreliable.
+     */
+    private target;
+    /**
+     * Computes the normalized filesystem base named by a Python import.
+     *
+     * Relative dot depth is resolved from the importing location; absolute names
+     * are rooted at the configured source root.
+     */
+    private importBase;
+    /**
+     * Lists source-file spellings that can implement one module base.
+     *
+     * Python permits both implementation and stub files, plus package initializers.
+     */
+    private candidates;
+    /**
+     * Checks whether a resolved source remains within the optional physical root.
+     *
+     * Public addresses can alias a source, but its physical path still defines the
+     * boundary that imports may not escape.
+     */
+    private insidePhysicalRoot;
+    /**
+     * Returns normalized physical and public locations for one source file.
+     *
+     * De-duplication preserves valid aliases while preventing one source from
+     * making an import appear ambiguous by itself.
+     */
+    private sourceLocations;
+    /**
+     * Normalizes a location for platform-independent module matching.
+     *
+     * Drive and UNC locations are case-insensitive, while other paths retain case
+     * so the resolver does not invent Windows behavior on POSIX snapshots.
+     */
+    private locationKey;
+    /**
+     * Records one export-resolution failure and marks the inventory incomplete.
+     *
+     * The supplied key suppresses repeated reports from reexport paths that reach
+     * the same underlying import or binding failure.
+     */
+    private problem;
+}