@agentxm/extension-discovery 0.28.4-bootstrap.0

package/dist/src/packaging/npm.js

@@ -0,0 +1,190 @@
+/**
+ * npm package detector and reader for package-compatibility discovery.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+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 { makeDetectedPackage } from "./detected-package.js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const npmType = Schema.decodeUnknownSync(PackageTypeSchema)("npm");
+/** Schema to extract the optional "axm" field from a package.json object. */
+const AxmContainerSchema = Schema.Struct({
+    axm: Schema.optional(Schema.Unknown),
+});
+const decodeAxmContainer = Schema.decodeUnknownResult(AxmContainerSchema);
+/** Prefixes that indicate non-registry specifiers to skip. */
+const SKIP_PREFIXES = ["file:", "link:", "workspace:", "git+", "git:", "github:"];
+/** Returns true if the specifier should be skipped (non-registry). */
+const isSkippedSpecifier = (specifier) => {
+    if (SKIP_PREFIXES.some((prefix) => specifier.startsWith(prefix)))
+        return true;
+    // URL-based specifiers
+    if (specifier.startsWith("http://") || specifier.startsWith("https://"))
+        return true;
+    return false;
+};
+/**
+ * Returns true if the specifier is an exact semver version (no range operators).
+ * Exact versions match: digits and dots only, e.g. "18.2.0", "1.0.0-beta.1".
+ */
+const isExactVersion = (specifier) => /^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9._+-]*)?$/.test(specifier);
+/**
+ * Parse an npm alias specifier like "npm:real-name@version" or "npm:@scope/name@version".
+ * Returns { name, specifier } where name is the real package name and specifier is the version part.
+ */
+const parseNpmAlias = (specifier) => {
+    if (!specifier.startsWith("npm:"))
+        return undefined;
+    const rest = specifier.slice(4); // Remove "npm:" prefix
+    // Handle scoped: npm:@scope/name@version
+    if (rest.startsWith("@")) {
+        const atIdx = rest.indexOf("@", 1);
+        if (atIdx === -1)
+            return { name: rest, specifier: "*" };
+        return { name: rest.slice(0, atIdx), specifier: rest.slice(atIdx + 1) };
+    }
+    // Handle unscoped: npm:name@version
+    const atIdx = rest.indexOf("@");
+    if (atIdx === -1)
+        return { name: rest, specifier: "*" };
+    return { name: rest.slice(0, atIdx), specifier: rest.slice(atIdx + 1) };
+};
+/**
+ * Parse a package name into namespace and name parts.
+ * "@scope/name" -> { namespace: "@scope", name: "name" }
+ * "name" -> { name: "name" }
+ */
+const parsePackageName = (pkgName) => {
+    if (pkgName.startsWith("@")) {
+        const slashIdx = pkgName.indexOf("/");
+        if (slashIdx > 0) {
+            return { namespace: pkgName.slice(0, slashIdx), name: pkgName.slice(slashIdx + 1) };
+        }
+    }
+    return { name: pkgName };
+};
+/**
+ * Convert a single dependency entry to a DetectedPackage, or undefined if skipped.
+ */
+const depToPurl = (depName, specifier, source) => {
+    if (isSkippedSpecifier(specifier))
+        return undefined;
+    // Resolve npm aliases to real package name
+    const alias = parseNpmAlias(specifier);
+    const resolvedName = alias ? alias.name : depName;
+    const resolvedSpecifier = alias ? alias.specifier : specifier;
+    const { namespace, name } = parsePackageName(resolvedName);
+    const version = isExactVersion(resolvedSpecifier) ? resolvedSpecifier : undefined;
+    return Option.getOrUndefined(makeDetectedPackage({
+        type: npmType,
+        ...(namespace === undefined ? {} : { namespace }),
+        name,
+        ...(version === undefined ? {} : { version }),
+        source,
+    }));
+};
+/**
+ * Schema to loosely decode the dependency-relevant shape of package.json.
+ * Accepts any object shape and extracts the three dependency sections
+ * as optional string-to-string records.
+ */
+const DependencySectionsSchema = Schema.Struct({
+    dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    peerDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+});
+const decodeDependencySections = Schema.decodeUnknownResult(DependencySectionsSchema);
+/**
+ * Extract dependencies from a parsed package.json value.
+ */
+const extractDeps = (manifest, source) => {
+    const decoded = decodeDependencySections(manifest);
+    if (Result.isFailure(decoded))
+        return [];
+    const sections = [
+        decoded.success.dependencies,
+        decoded.success.devDependencies,
+        decoded.success.peerDependencies,
+    ];
+    const results = [];
+    for (const deps of sections) {
+        if (deps === undefined)
+            continue;
+        for (const [name, specifier] of Object.entries(deps)) {
+            const detected = depToPurl(name, specifier, source);
+            if (detected !== undefined)
+                results.push(detected);
+        }
+    }
+    return results;
+};
+/**
+ * npm package detector.
+ *
+ * Scans `package.json` in the project directory and extracts dependencies
+ * from `dependencies`, `devDependencies`, and `peerDependencies`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const npmDetector = {
+    type: npmType,
+    detect: Effect.fn("detect.npm")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const manifestPath = path.join(projectDir, "package.json");
+        const content = yield* readFileOptional(manifestPath);
+        if (Option.isNone(content))
+            return [];
+        const parsed = yield* parseJsonOptional(content.value, "package.json");
+        if (Option.isNone(parsed))
+            return [];
+        return extractDeps(parsed.value, manifestPath);
+    }, Effect.annotateLogs({ detector: "npm" }), Effect.withSpan("detect.npm")),
+};
+/**
+ * npm package reader.
+ *
+ * Reads `node_modules/<name>/package.json` for each detected npm package
+ * and extracts the `"axm"` field containing recommendation metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const npmReader = {
+    type: npmType,
+    read: Effect.fn("read.npm")(function* (pkg) {
+        const path = yield* Path.Path;
+        // Derive project directory from the source manifest path
+        const projectDir = path.dirname(pkg.source);
+        // Reconstruct the package name from purl parts
+        const pkgName = pkg.purl.namespace ? `${pkg.purl.namespace}/${pkg.purl.name}` : pkg.purl.name;
+        const pkgJsonPath = path.join(projectDir, "node_modules", pkgName, "package.json");
+        const content = yield* readFileOptional(pkgJsonPath);
+        if (Option.isNone(content))
+            return Option.none();
+        const parsed = yield* parseJsonOptional(content.value, pkgName);
+        if (Option.isNone(parsed))
+            return Option.none();
+        // Extract and validate the "axm" field using schema
+        const axmContainerResult = decodeAxmContainer(parsed.value);
+        if (Result.isFailure(axmContainerResult)) {
+            // No valid axm field present (or missing entirely)
+            return Option.none();
+        }
+        const axmRaw = axmContainerResult.success.axm;
+        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 ${pkgName}: schema validation failed`);
+            return Option.none();
+        }
+        return Option.some(metaResult.success.extensions);
+    }, Effect.annotateLogs({ reader: "npm" }), Effect.withSpan("read.npm")),
+};
+//# sourceMappingURL=npm.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * NuGet 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";
+/**
+ * NuGet package detector.
+ *
+ * Scans `.csproj`, `.fsproj`, `.vbproj`, `Directory.Packages.props`,
+ * and `packages.config` files in the project directory.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const nugetDetector: PackageDetector;
+/**
+ * NuGet package reader.
+ *
+ * Reads `axm.json` from `~/.nuget/packages/{id}/{version}/` for each
+ * detected NuGet package and extracts recommendation metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const nugetReader: PackageReader;
+//# sourceMappingURL=nuget.d.ts.map

package/dist/src/packaging/nuget.js

@@ -0,0 +1,240 @@
+/**
+ * NuGet 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 { readEnv } from "../internal/environment.js";
+import { makeDetectedPackage } from "./detected-package.js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const nugetType = Schema.decodeUnknownSync(PackageTypeSchema)("nuget");
+/**
+ * Returns true if the version string is a NuGet version range.
+ * Ranges use brackets/parens like [1.0,2.0), (,1.0], etc.
+ */
+const isNugetVersionRange = (version) => /^[[(]/.test(version) || /[)\]]$/.test(version);
+/**
+ * Returns true if the version string is a floating version (e.g., "1.0.*").
+ */
+const isFloatingVersion = (version) => version.includes("*");
+/**
+ * Returns true if the version is an exact version (not a range or floating).
+ */
+const isExactVersion = (version) => !isNugetVersionRange(version) && !isFloatingVersion(version) && version.trim() !== "";
+/**
+ * Create a DetectedPackage from a NuGet package name and optional version.
+ * Names are lowercased per NuGet case-insensitivity.
+ */
+const makeNugetPackage = (name, version, source) => {
+    const loweredName = name.toLowerCase();
+    const resolvedVersion = version !== undefined && isExactVersion(version) ? version : undefined;
+    return Option.getOrUndefined(makeDetectedPackage({
+        type: nugetType,
+        name: loweredName,
+        ...(resolvedVersion === undefined ? {} : { version: resolvedVersion }),
+        source,
+    }));
+};
+const appendNugetPackage = (results, name, version, source) => {
+    const detected = makeNugetPackage(name, version, source);
+    if (detected !== undefined)
+        results.push(detected);
+};
+/**
+ * Extract an XML attribute value from a tag string.
+ */
+const extractAttribute = (tag, attrName) => {
+    const regex = new RegExp(`${attrName}\\s*=\\s*"([^"]*)"`, "i");
+    const match = regex.exec(tag);
+    return match?.[1];
+};
+/**
+ * Parse .csproj/.fsproj/.vbproj content and extract PackageReference elements.
+ */
+const parseProjectFile = (content, source) => {
+    const results = [];
+    // Match self-closing PackageReference tags
+    const selfClosingRegex = /<PackageReference\s+[^>]*\/>/gi;
+    let match;
+    while ((match = selfClosingRegex.exec(content)) !== null) {
+        const tag = match[0];
+        const name = extractAttribute(tag, "Include");
+        if (name === undefined)
+            continue;
+        const version = extractAttribute(tag, "Version");
+        appendNugetPackage(results, name, version, source);
+    }
+    // Match PackageReference with child elements (e.g. <Version> child)
+    const blockRegex = /<PackageReference\s+([^>]*)>([\s\S]*?)<\/PackageReference>/gi;
+    while ((match = blockRegex.exec(content)) !== null) {
+        const attrs = match[1];
+        const body = match[2];
+        if (attrs === undefined)
+            continue;
+        const name = extractAttribute(attrs, "Include");
+        if (name === undefined)
+            continue;
+        // Try attribute first, then child element
+        let version = extractAttribute(attrs, "Version");
+        if (version === undefined && body !== undefined) {
+            const versionMatch = /<Version>\s*(.*?)\s*<\/Version>/i.exec(body);
+            version = versionMatch?.[1];
+        }
+        appendNugetPackage(results, name, version, source);
+    }
+    return results;
+};
+/**
+ * Parse Directory.Packages.props content and extract PackageVersion elements.
+ */
+const parseDirectoryPackagesProps = (content, source) => {
+    const results = [];
+    const pkgVersionRegex = /<PackageVersion\s+[^>]*\/>/gi;
+    let match;
+    while ((match = pkgVersionRegex.exec(content)) !== null) {
+        const tag = match[0];
+        const name = extractAttribute(tag, "Include");
+        if (name === undefined)
+            continue;
+        const version = extractAttribute(tag, "Version");
+        appendNugetPackage(results, name, version, source);
+    }
+    return results;
+};
+/**
+ * Parse packages.config content and extract package elements.
+ */
+const parsePackagesConfig = (content, source) => {
+    const results = [];
+    const pkgRegex = /<package\s+[^>]*\/>/gi;
+    let match;
+    while ((match = pkgRegex.exec(content)) !== null) {
+        const tag = match[0];
+        const name = extractAttribute(tag, "id");
+        if (name === undefined)
+            continue;
+        const version = extractAttribute(tag, "version");
+        appendNugetPackage(results, name, version, source);
+    }
+    return results;
+};
+/**
+ * Deduplicate packages by lowercased name.
+ */
+const deduplicatePackages = (packages) => {
+    const seen = new Set();
+    const results = [];
+    for (const pkg of packages) {
+        const key = pkg.purl.name.toLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            results.push(pkg);
+        }
+    }
+    return results;
+};
+/**
+ * NuGet package detector.
+ *
+ * Scans `.csproj`, `.fsproj`, `.vbproj`, `Directory.Packages.props`,
+ * and `packages.config` files in the project directory.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const nugetDetector = {
+    type: nugetType,
+    detect: Effect.fn("detect.nuget")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const fs = yield* FileSystem.FileSystem;
+        const allPackages = [];
+        // Find and parse project files (*.csproj, *.fsproj, *.vbproj)
+        const entries = yield* fs.readDirectory(projectDir).pipe(Effect.option);
+        if (Option.isSome(entries)) {
+            const projectFiles = entries.value.filter((e) => e.endsWith(".csproj") || e.endsWith(".fsproj") || e.endsWith(".vbproj"));
+            for (const file of projectFiles) {
+                const filePath = path.join(projectDir, file);
+                const content = yield* readFileOptional(filePath);
+                if (Option.isSome(content)) {
+                    if (content.value.includes("<")) {
+                        const deps = parseProjectFile(content.value, filePath);
+                        allPackages.push(...deps);
+                    }
+                    else {
+                        yield* Effect.logWarning(`Malformed ${file}: not valid XML, skipping`);
+                    }
+                }
+            }
+        }
+        // Parse Directory.Packages.props
+        const propsPath = path.join(projectDir, "Directory.Packages.props");
+        const propsContent = yield* readFileOptional(propsPath);
+        if (Option.isSome(propsContent)) {
+            if (propsContent.value.includes("<")) {
+                const propsDeps = parseDirectoryPackagesProps(propsContent.value, propsPath);
+                allPackages.push(...propsDeps);
+            }
+            else {
+                yield* Effect.logWarning("Malformed Directory.Packages.props: not valid XML, skipping");
+            }
+        }
+        // Parse packages.config
+        const packagesConfigPath = path.join(projectDir, "packages.config");
+        const packagesConfigContent = yield* readFileOptional(packagesConfigPath);
+        if (Option.isSome(packagesConfigContent)) {
+            if (packagesConfigContent.value.includes("<")) {
+                const configDeps = parsePackagesConfig(packagesConfigContent.value, packagesConfigPath);
+                allPackages.push(...configDeps);
+            }
+            else {
+                yield* Effect.logWarning("Malformed packages.config: not valid XML, skipping");
+            }
+        }
+        return deduplicatePackages(allPackages);
+    }, Effect.annotateLogs({ detector: "nuget" }), Effect.withSpan("detect.nuget")),
+};
+/**
+ * Resolve the NuGet packages folder path.
+ */
+const resolveNugetPackagesFolder = () => Effect.sync(() => readEnv("NUGET_PACKAGES") ?? `${os.homedir()}/.nuget/packages`);
+/**
+ * NuGet package reader.
+ *
+ * Reads `axm.json` from `~/.nuget/packages/{id}/{version}/` for each
+ * detected NuGet package and extracts recommendation metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const nugetReader = {
+    type: nugetType,
+    read: Effect.fn("read.nuget")(function* (pkg) {
+        const path = yield* Path.Path;
+        const packagesFolder = yield* resolveNugetPackagesFolder();
+        // NuGet uses lowercased package IDs in directory names
+        const pkgId = pkg.purl.name.toLowerCase();
+        const version = pkg.purl.version ?? "0.0.0";
+        const axmJsonPath = path.join(packagesFolder, pkgId, version, "axm.json");
+        const content = yield* readFileOptional(axmJsonPath);
+        if (Option.isNone(content))
+            return Option.none();
+        const parsed = yield* parseJsonOptional(content.value, `${pkgId}@${version}/axm.json`);
+        if (Option.isNone(parsed))
+            return Option.none();
+        // Validate axm metadata structure
+        const metaResult = decodeAxmMeta(parsed.value);
+        if (Result.isFailure(metaResult)) {
+            yield* Effect.logWarning(`Invalid axm metadata in ${pkgId}@${version}: schema validation failed`);
+            return Option.none();
+        }
+        return Option.some(metaResult.success.extensions);
+    }, Effect.annotateLogs({ reader: "nuget" }), Effect.withSpan("read.nuget")),
+};
+//# sourceMappingURL=nuget.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * opam (OCaml) 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";
+/**
+ * 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 declare const opamDetector: PackageDetector;
+/**
+ * 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 declare const opamReader: PackageReader;
+//# sourceMappingURL=opam.d.ts.map