@agentxm/extension-discovery 0.28.4-bootstrap.0

package/dist/src/packaging/opam.js

@@ -0,0 +1,287 @@
+/**
+ * opam (OCaml) package detector and reader for package-compatibility discovery.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+// Intentional escape hatch: node:os homedir() has no @effect/platform equivalent.
+import * as os from "node:os";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { PackageURL } from "packageurl-js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, decodePurl, readFileOptional } from "./reader-io.js";
+const opamType = Schema.decodeUnknownSync(PackageTypeSchema)("opam");
+/** Build-tooling dependencies to skip. */
+const SKIP_DEPS = new Set(["ocaml", "dune"]);
+/**
+ * Parse opam depends field content.
+ * Format: depends: [ "pkg1" {>= "ver"} "pkg2" ... ]
+ * The constraint syntax uses { } for version constraints.
+ */
+const parseOpamDepends = (content, source) => {
+    const results = [];
+    // Find the depends field - it starts with "depends:" and contains a [ ... ] block
+    const dependsRegex = /depends:\s*\[([^\]]*)\]/s;
+    const match = dependsRegex.exec(content);
+    if (match === null || match[1] === undefined)
+        return [];
+    // Extract quoted package names and their optional version constraints
+    // Pattern: "name" {constraint} or just "name"
+    const entryRegex = /"([^"]+)"(?:\s*\{([^}]*)\})?/g;
+    let entryMatch;
+    while ((entryMatch = entryRegex.exec(match[1])) !== null) {
+        const name = entryMatch[1];
+        const constraint = entryMatch[2]?.trim();
+        if (name === undefined)
+            continue;
+        if (SKIP_DEPS.has(name))
+            continue;
+        // Check for exact version: = "version"
+        let version;
+        if (constraint !== undefined) {
+            const exactMatch = /^=\s*"([^"]+)"$/.exec(constraint);
+            if (exactMatch?.[1]) {
+                version = exactMatch[1];
+            }
+        }
+        const purl = new PackageURL("opam", null, name, version ?? null, null, null);
+        const purlParts = decodePurl(purl.toString());
+        results.push({ purl: purlParts, type: opamType, source });
+    }
+    return results;
+};
+/**
+ * Extract the contents of a top-level `(depends ...)` s-expression
+ * by finding the opening `(depends` and then walking to the matching
+ * closing `)` while counting nested parentheses.
+ */
+const extractDependsBlock = (content) => {
+    const idx = content.indexOf("(depends");
+    if (idx === -1)
+        return undefined;
+    // Move past "(depends"
+    let i = idx + "(depends".length;
+    let depth = 1;
+    const start = i;
+    while (i < content.length && depth > 0) {
+        if (content[i] === "(")
+            depth++;
+        else if (content[i] === ")")
+            depth--;
+        i++;
+    }
+    // depth === 0 means we found the matching close paren
+    if (depth !== 0)
+        return undefined;
+    // Return everything between "(depends" and the matching ")"
+    return content.slice(start, i - 1);
+};
+/**
+ * Parse dune-project (depends ...) s-expression.
+ * Format: (depends (ocaml (>= 5.0)) (lwt (>= 5.0)) yojson)
+ */
+const parseDuneProjectDepends = (content, source) => {
+    const results = [];
+    const depsBlock = extractDependsBlock(content);
+    if (depsBlock === undefined)
+        return [];
+    const depsContent = depsBlock;
+    // Extract dependency entries: (name constraint) or bare name
+    // A dependency can be: bare_name, (name constraint_expr)
+    const entries = [];
+    // Parse the s-expression content to extract dependency names
+    let i = 0;
+    while (i < depsContent.length) {
+        // Skip whitespace
+        while (i < depsContent.length && /\s/.test(depsContent[i] ?? ""))
+            i++;
+        if (i >= depsContent.length)
+            break;
+        if (depsContent[i] === "(") {
+            // Parenthesized entry - extract the name (first atom)
+            i++; // skip (
+            // Skip whitespace
+            while (i < depsContent.length && /\s/.test(depsContent[i] ?? ""))
+                i++;
+            // Read the name
+            let name = "";
+            while (i < depsContent.length && !/[\s)]/.test(depsContent[i] ?? "")) {
+                name += depsContent[i];
+                i++;
+            }
+            // Check for exact version constraint: (= version)
+            let version;
+            const remaining = depsContent.slice(i);
+            const exactMatch = /^\s*\(\s*=\s*(\S+)\s*\)/.exec(remaining);
+            if (exactMatch?.[1]) {
+                version = exactMatch[1];
+            }
+            if (name !== "") {
+                entries.push(name);
+                if (version !== undefined && !SKIP_DEPS.has(name)) {
+                    const purl = new PackageURL("opam", null, name, version, null, null);
+                    const purlParts = decodePurl(purl.toString());
+                    results.push({ purl: purlParts, type: opamType, source });
+                    // Skip to closing paren
+                    let depth = 1;
+                    while (i < depsContent.length && depth > 0) {
+                        if (depsContent[i] === "(")
+                            depth++;
+                        else if (depsContent[i] === ")")
+                            depth--;
+                        i++;
+                    }
+                    continue;
+                }
+            }
+            // Skip to closing paren
+            let depth = 1;
+            while (i < depsContent.length && depth > 0) {
+                if (depsContent[i] === "(")
+                    depth++;
+                else if (depsContent[i] === ")")
+                    depth--;
+                i++;
+            }
+            if (name !== "" && !SKIP_DEPS.has(name) && version === undefined) {
+                const purl = new PackageURL("opam", null, name, null, null, null);
+                const purlParts = decodePurl(purl.toString());
+                results.push({ purl: purlParts, type: opamType, source });
+            }
+        }
+        else {
+            // Bare name
+            let name = "";
+            while (i < depsContent.length && !/[\s)]/.test(depsContent[i] ?? "")) {
+                name += depsContent[i];
+                i++;
+            }
+            if (name !== "" && !SKIP_DEPS.has(name)) {
+                const purl = new PackageURL("opam", null, name, null, null, null);
+                const purlParts = decodePurl(purl.toString());
+                results.push({ purl: purlParts, type: opamType, source });
+            }
+        }
+    }
+    return results;
+};
+/**
+ * opam package detector.
+ *
+ * Scans `*.opam` files for `depends` fields and `dune-project` for
+ * `(depends ...)` s-expressions. Skips `ocaml` and `dune` build tooling.
+ * Dependencies are deduplicated by name.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const opamDetector = {
+    type: opamType,
+    detect: Effect.fn("detect.opam")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const fs = yield* FileSystem.FileSystem;
+        const allDeps = [];
+        const seenNames = new Set();
+        const addDeps = (deps) => {
+            for (const dep of deps) {
+                if (!seenNames.has(dep.purl.name)) {
+                    seenNames.add(dep.purl.name);
+                    allDeps.push(dep);
+                }
+            }
+        };
+        // Scan for *.opam files
+        const entries = yield* fs.readDirectory(projectDir).pipe(Effect.option);
+        if (Option.isSome(entries)) {
+            const opamFiles = entries.value.filter((e) => e.endsWith(".opam"));
+            for (const opamFile of opamFiles) {
+                const filePath = path.join(projectDir, opamFile);
+                const content = yield* readFileOptional(filePath);
+                if (Option.isSome(content)) {
+                    const deps = parseOpamDepends(content.value, filePath);
+                    if (deps.length === 0 && content.value.trim().length > 0) {
+                        if (!content.value.includes("opam-version:") && !content.value.includes("name:")) {
+                            yield* Effect.logWarning(`Malformed opam file: ${opamFile}, skipping`);
+                        }
+                    }
+                    addDeps(deps);
+                }
+            }
+        }
+        // Parse dune-project
+        const dunePath = path.join(projectDir, "dune-project");
+        const duneContent = yield* readFileOptional(dunePath);
+        if (Option.isSome(duneContent)) {
+            const duneDeps = parseDuneProjectDepends(duneContent.value, dunePath);
+            addDeps(duneDeps);
+        }
+        return allDeps;
+    }, Effect.annotateLogs({ detector: "opam" }), Effect.withSpan("detect.opam")),
+};
+/**
+ * Parse x-axm custom fields from opam file content.
+ * Returns a record mapping field names (without x-axm- prefix) to values.
+ */
+const parseXAxmFields = (content) => {
+    const fields = {};
+    const regex = /^x-axm-(\S+)\s*:\s*(.+)$/gim;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const fieldName = match[1];
+        const rawValue = match[2]?.trim();
+        if (fieldName === undefined || rawValue === undefined)
+            continue;
+        // Try to parse as JSON value (for arrays, etc.)
+        try {
+            fields[fieldName] = JSON.parse(rawValue);
+        }
+        catch {
+            fields[fieldName] = rawValue;
+        }
+    }
+    return fields;
+};
+/**
+ * opam package reader.
+ *
+ * Reads `x-axm` prefixed custom fields from `.opam` files in the
+ * opam switch at `~/.opam/<switch>/lib/<pkg>/opam`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const opamReader = {
+    type: opamType,
+    read: Effect.fn("read.opam")(function* (pkg) {
+        const path = yield* Path.Path;
+        const fs = yield* FileSystem.FileSystem;
+        const pkgName = pkg.purl.name;
+        const home = os.homedir();
+        const opamDir = path.join(home, ".opam");
+        // List available switches
+        const switches = yield* fs.readDirectory(opamDir).pipe(Effect.option);
+        if (Option.isNone(switches))
+            return Option.none();
+        // Check each switch for the package
+        for (const switchName of switches.value) {
+            const opamFilePath = path.join(opamDir, switchName, "lib", pkgName, "opam");
+            const content = yield* readFileOptional(opamFilePath);
+            if (Option.isNone(content))
+                continue;
+            const xAxmFields = parseXAxmFields(content.value);
+            if (Object.keys(xAxmFields).length === 0)
+                continue;
+            const metaResult = decodeAxmMeta(xAxmFields);
+            if (Result.isFailure(metaResult)) {
+                yield* Effect.logWarning(`Invalid axm metadata in ${pkgName}: schema validation failed`);
+                return Option.none();
+            }
+            return Option.some(metaResult.success.extensions);
+        }
+        return Option.none();
+    }, Effect.annotateLogs({ reader: "opam" }), Effect.withSpan("read.opam")),
+};
+//# sourceMappingURL=opam.js.map

package/dist/src/packaging/pub.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Dart/Flutter pub package detector and reader for package-compatibility discovery.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { PackageDetector, PackageReader } from "./types.js";
+/**
+ * Pub package detector.
+ *
+ * Scans `pubspec.yaml` in the project directory and extracts dependencies
+ * from `dependencies` and `dev_dependencies`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const pubDetector: PackageDetector;
+/**
+ * Pub package reader.
+ *
+ * Reads `.dart_tool/package_config.json` to locate the package root,
+ * then reads `pubspec.yaml` from that root and extracts the `axm` field.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const pubReader: PackageReader;
+//# sourceMappingURL=pub.d.ts.map

package/dist/src/packaging/pub.js

@@ -0,0 +1,357 @@
+/**
+ * Dart/Flutter pub package detector and reader for package-compatibility discovery.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+// Intentional escape hatch: node:url URL <-> path conversion has no @effect/platform equivalent.
+import { fileURLToPath, pathToFileURL } from "node:url";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { PackageURL } from "packageurl-js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, decodePurl, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const pubType = Schema.decodeUnknownSync(PackageTypeSchema)("pub");
+/** Pub package names must be lowercase `[a-z0-9_]` only. */
+const VALID_PUB_NAME = /^[a-z0-9_]+$/;
+/**
+ * Returns true if the specifier is an exact semver version (no range operators).
+ * Exact versions match: digits and dots only, e.g. "1.2.0", "1.0.0+1".
+ */
+const isExactVersion = (specifier) => /^\d+\.\d+\.\d+(?:[+][a-zA-Z0-9._+-]*)?$/.test(specifier);
+/**
+ * Minimal line-based YAML parser for pubspec.yaml dependency sections.
+ * Extracts `dependencies:` and `dev_dependencies:` maps.
+ *
+ * Returns a record of dependency name -> value string (version or structured).
+ * Only handles flat key-value pairs and detects structured entries (path/git/sdk).
+ */
+const parsePubspecDeps = (content) => {
+    const lines = content.split("\n");
+    const deps = [];
+    let inDepSection = false;
+    let currentDepName;
+    let currentDepIsStructured = false;
+    for (const line of lines) {
+        // Skip comments
+        if (line.trimStart().startsWith("#"))
+            continue;
+        // Detect top-level section headers (no leading whitespace)
+        if (!line.startsWith(" ") && !line.startsWith("\t") && line.trim().length > 0) {
+            const trimmed = line.trim();
+            if (trimmed === "dependencies:" || trimmed === "dev_dependencies:") {
+                inDepSection = true;
+                currentDepName = undefined;
+                currentDepIsStructured = false;
+                continue;
+            }
+            // Any other top-level key ends the section
+            if (trimmed.endsWith(":") || trimmed.includes(":")) {
+                inDepSection = false;
+                currentDepName = undefined;
+                currentDepIsStructured = false;
+                continue;
+            }
+        }
+        if (!inDepSection)
+            continue;
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        // Determine indentation level
+        const indent = line.length - line.trimStart().length;
+        // dep-level entry (typically 2 spaces or 1 tab)
+        if (indent > 0 && indent <= 4 && !trimmed.startsWith("-")) {
+            const colonIdx = trimmed.indexOf(":");
+            if (colonIdx === -1)
+                continue;
+            const name = trimmed.slice(0, colonIdx).trim();
+            const value = trimmed.slice(colonIdx + 1).trim();
+            currentDepName = name;
+            currentDepIsStructured = false;
+            if (value.length === 0) {
+                // Structured dependency follows on next lines
+                currentDepIsStructured = true;
+                continue;
+            }
+            // Simple version string: `http: ^1.0.0` or `http: 1.2.0` or `http: any`
+            deps.push({ name, version: value, isSkipped: false });
+            currentDepName = undefined;
+        }
+        else if (indent > 4 && currentDepName !== undefined && currentDepIsStructured) {
+            // Sub-key of a structured dependency
+            const colonIdx = trimmed.indexOf(":");
+            if (colonIdx === -1)
+                continue;
+            const subKey = trimmed.slice(0, colonIdx).trim();
+            if (subKey === "path" || subKey === "git" || subKey === "sdk") {
+                deps.push({ name: currentDepName, version: undefined, isSkipped: true });
+                currentDepName = undefined;
+                currentDepIsStructured = false;
+            }
+            else if (subKey === "version") {
+                const subValue = trimmed.slice(colonIdx + 1).trim();
+                // Hosted dependency with explicit version
+                deps.push({ name: currentDepName, version: subValue, isSkipped: false });
+                currentDepName = undefined;
+                currentDepIsStructured = false;
+            }
+        }
+    }
+    return { deps };
+};
+/**
+ * Convert a parsed pub dependency to a DetectedPackage, or undefined if skipped.
+ */
+const depToPurl = (name, version, isSkipped, source) => {
+    if (isSkipped)
+        return undefined;
+    if (!VALID_PUB_NAME.test(name))
+        return undefined;
+    const resolvedVersion = version !== undefined && isExactVersion(version) ? version : undefined;
+    const purl = new PackageURL("pub", null, name, resolvedVersion ?? null, null, null);
+    const purlParts = decodePurl(purl.toString());
+    return { purl: purlParts, type: pubType, source };
+};
+/**
+ * Pub package detector.
+ *
+ * Scans `pubspec.yaml` in the project directory and extracts dependencies
+ * from `dependencies` and `dev_dependencies`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const pubDetector = {
+    type: pubType,
+    detect: Effect.fn("detect.pub")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const manifestPath = path.join(projectDir, "pubspec.yaml");
+        const content = yield* readFileOptional(manifestPath);
+        if (Option.isNone(content))
+            return [];
+        // Basic validation: check if it looks like YAML
+        const trimmed = content.value.trim();
+        if (trimmed.length === 0)
+            return [];
+        // Check for obviously malformed YAML
+        if (trimmed.startsWith("{") && !trimmed.includes(":")) {
+            yield* Effect.logWarning("Malformed pubspec.yaml, skipping");
+            return [];
+        }
+        const { deps } = parsePubspecDeps(content.value);
+        const results = [];
+        for (const dep of deps) {
+            const detected = depToPurl(dep.name, dep.version, dep.isSkipped, manifestPath);
+            if (detected !== undefined)
+                results.push(detected);
+        }
+        return results;
+    }, Effect.annotateLogs({ detector: "pub" }), Effect.withSpan("detect.pub")),
+};
+/**
+ * Schema for package_config.json package entries.
+ */
+const PackageConfigEntrySchema = Schema.Struct({
+    name: Schema.String,
+    rootUri: Schema.String,
+});
+const PackageConfigSchema = Schema.Struct({
+    packages: Schema.optional(Schema.Array(PackageConfigEntrySchema)),
+});
+const decodePackageConfig = Schema.decodeUnknownResult(PackageConfigSchema);
+/**
+ * Resolve a `package_config.json` `rootUri` to an absolute filesystem path.
+ *
+ * `rootUri` is a URI reference resolved against the location of
+ * `package_config.json` (the `.dart_tool/` directory). A real `dart pub get`
+ * writes absolute `file://` URIs for hosted packages, while path dependencies
+ * and hand-written configs may use relative paths; resolving as a URL handles
+ * both and decodes any percent-encoding. `path.resolve` cannot be used here —
+ * it has no notion of URI schemes and mangles `file://` values into garbage
+ * paths. Returns `Option.none` for a `rootUri` that is not a resolvable
+ * `file:` location.
+ */
+const resolvePackageRoot = (dartToolDir, rootUri) => {
+    try {
+        const baseUrl = new URL(`${pathToFileURL(dartToolDir).href}/`);
+        return Option.some(fileURLToPath(new URL(rootUri, baseUrl)));
+    }
+    catch {
+        return Option.none();
+    }
+};
+const parseYamlInlineObject = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+        return trimmed.replace(/^["']|["']$/g, "");
+    }
+    const body = trimmed.slice(1, -1);
+    const entry = {};
+    for (const part of body.split(",")) {
+        const pair = /^\s*([A-Za-z0-9_-]+)\s*:\s*["']([^"']+)["']\s*$/.exec(part);
+        const key = pair?.[1];
+        const rawValue = pair?.[2];
+        if (key === undefined || rawValue === undefined)
+            continue;
+        entry[key] = rawValue;
+    }
+    return Object.keys(entry).length > 0 ? entry : value;
+};
+const parseYamlInlineArray = (value) => {
+    const inner = value.slice(1, value.lastIndexOf("]")).trim();
+    if (inner === "")
+        return [];
+    const objectMatches = Array.from(inner.matchAll(/\{[^{}]*\}/g), (match) => match[0]);
+    if (objectMatches.length > 0)
+        return objectMatches.map(parseYamlInlineObject);
+    return inner
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0)
+        .map((item) => item.replace(/^["']|["']$/g, ""));
+};
+/**
+ * Extract the `axm` field from a pubspec.yaml content string using line-based parsing.
+ * Returns the axm field value as a simple JSON-like structure, or undefined if not found.
+ */
+const extractAxmFromPubspec = (content) => {
+    const lines = content.split("\n");
+    let inAxmSection = false;
+    const axmLines = [];
+    let baseIndent = 0;
+    for (const line of lines) {
+        if (line.trimStart().startsWith("#"))
+            continue;
+        // Detect "axm:" at the top level
+        if (!line.startsWith(" ") && !line.startsWith("\t") && line.trim() === "axm:") {
+            inAxmSection = true;
+            baseIndent = 0;
+            continue;
+        }
+        if (inAxmSection) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            const indent = line.length - line.trimStart().length;
+            // If we hit another top-level key, stop
+            if (indent === 0 && trimmed.length > 0) {
+                break;
+            }
+            if (baseIndent === 0)
+                baseIndent = indent;
+            if (indent >= baseIndent) {
+                axmLines.push(line);
+            }
+            else {
+                break;
+            }
+        }
+    }
+    if (axmLines.length === 0)
+        return undefined;
+    // Parse the axm section: extract extensions list
+    const result = {};
+    let currentKey;
+    const currentList = [];
+    let inList = false;
+    for (const line of axmLines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("#"))
+            continue;
+        // Check for key: value or key:
+        const colonIdx = trimmed.indexOf(":");
+        if (colonIdx > 0 && !trimmed.startsWith("-")) {
+            // Save previous list if any
+            if (inList && currentKey !== undefined) {
+                result[currentKey] = currentList.slice();
+                currentList.length = 0;
+            }
+            const key = trimmed.slice(0, colonIdx).trim();
+            const value = trimmed.slice(colonIdx + 1).trim();
+            currentKey = key;
+            if (value.length > 0 && !value.startsWith("[")) {
+                // Simple scalar value
+                result[key] = value;
+                inList = false;
+            }
+            else if (value.startsWith("[")) {
+                result[key] = parseYamlInlineArray(value);
+                inList = false;
+            }
+            else {
+                // List follows on next lines
+                inList = true;
+            }
+        }
+        else if (trimmed.startsWith("- ") && inList && currentKey !== undefined) {
+            const item = parseYamlInlineObject(trimmed.slice(2));
+            currentList.push(item);
+        }
+    }
+    // Save final list
+    if (inList && currentKey !== undefined) {
+        result[currentKey] = currentList.slice();
+    }
+    return result;
+};
+/**
+ * Pub package reader.
+ *
+ * Reads `.dart_tool/package_config.json` to locate the package root,
+ * then reads `pubspec.yaml` from that root and extracts the `axm` field.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const pubReader = {
+    type: pubType,
+    read: Effect.fn("read.pub")(function* (pkg) {
+        const path = yield* Path.Path;
+        // Derive project directory from the source manifest path
+        const projectDir = path.dirname(pkg.source);
+        // Read .dart_tool/package_config.json
+        const packageConfigPath = path.join(projectDir, ".dart_tool", "package_config.json");
+        const configContent = yield* readFileOptional(packageConfigPath);
+        if (Option.isNone(configContent))
+            return Option.none();
+        const configParsed = yield* parseJsonOptional(configContent.value, "package_config.json");
+        if (Option.isNone(configParsed))
+            return Option.none();
+        const configResult = decodePackageConfig(configParsed.value);
+        if (Result.isFailure(configResult))
+            return Option.none();
+        const packages = configResult.success.packages;
+        if (packages === undefined)
+            return Option.none();
+        // Find the package entry matching our detected package name
+        const pkgEntry = packages.find((p) => p.name === pkg.purl.name);
+        if (pkgEntry === undefined)
+            return Option.none();
+        // Resolve rootUri against the .dart_tool/ directory. package_config.json
+        // entries are URI references — a real `dart pub get` writes absolute
+        // `file://` URIs for hosted packages — so resolve as a URL, not a path.
+        const dartToolDir = path.resolve(projectDir, ".dart_tool");
+        const packageRoot = resolvePackageRoot(dartToolDir, pkgEntry.rootUri);
+        if (Option.isNone(packageRoot))
+            return Option.none();
+        // Read pubspec.yaml from package root
+        const pubspecPath = path.join(packageRoot.value, "pubspec.yaml");
+        const pubspecContent = yield* readFileOptional(pubspecPath);
+        if (Option.isNone(pubspecContent))
+            return Option.none();
+        // Extract axm field from pubspec
+        const axmRaw = extractAxmFromPubspec(pubspecContent.value);
+        if (axmRaw === undefined)
+            return Option.none();
+        // Validate axm metadata structure
+        const metaResult = decodeAxmMeta(axmRaw);
+        if (Result.isFailure(metaResult)) {
+            yield* Effect.logWarning(`Invalid axm metadata in ${pkg.purl.name}: schema validation failed`);
+            return Option.none();
+        }
+        return Option.some(metaResult.success.extensions);
+    }, Effect.annotateLogs({ reader: "pub" }), Effect.withSpan("read.pub")),
+};
+//# sourceMappingURL=pub.js.map

package/dist/src/packaging/pypi.d.ts

@@ -0,0 +1,23 @@
+/**
+ * pypi package detector and reader for package-compatibility discovery.
+ *
+ * Parses Python dependency files (pyproject.toml, requirements.txt,
+ * setup.cfg, Pipfile) and reads axm metadata from installed packages.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { PackageDetector, PackageReader } from "./types.js";
+/**
+ * pypi package detector. Parses Python dependency files in priority order.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const pypiDetector: PackageDetector;
+/**
+ * pypi package reader. Reads axm metadata from installed Python packages.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const pypiReader: PackageReader;
+//# sourceMappingURL=pypi.d.ts.map