@agentxm/extension-discovery 0.28.4-bootstrap.0

package/dist/src/packaging/docker.js

@@ -0,0 +1,256 @@
+/**
+ * Docker image 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 { PackageURL } from "packageurl-js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, decodePurl, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const dockerType = Schema.decodeUnknownSync(PackageTypeSchema)("docker");
+/**
+ * Parse a Docker image reference into namespace, name, and version components.
+ *
+ * Image references can be:
+ * - `name` (e.g. `nginx`)
+ * - `name:tag` (e.g. `nginx:alpine`)
+ * - `org/name:tag` (e.g. `library/nginx:1.25`)
+ * - `registry/org/name:tag` (e.g. `ghcr.io/org/myapp:latest`)
+ */
+const parseImageRef = (ref) => {
+    const trimmed = ref.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    // Split on : to get name part and tag part
+    const colonIdx = trimmed.lastIndexOf(":");
+    let namePart;
+    let tag;
+    if (colonIdx > 0 && !trimmed.slice(colonIdx).includes("/")) {
+        namePart = trimmed.slice(0, colonIdx);
+        tag = trimmed.slice(colonIdx + 1);
+    }
+    else {
+        namePart = trimmed;
+        tag = undefined;
+    }
+    // Remove @sha256 digest if present
+    const digestIdx = namePart.indexOf("@");
+    if (digestIdx > 0) {
+        namePart = namePart.slice(0, digestIdx);
+    }
+    // Split namespace and name
+    const lastSlash = namePart.lastIndexOf("/");
+    let namespace;
+    let name;
+    if (lastSlash > 0) {
+        namespace = namePart.slice(0, lastSlash);
+        name = namePart.slice(lastSlash + 1);
+    }
+    else {
+        namespace = undefined;
+        name = namePart;
+    }
+    if (name.length === 0)
+        return undefined;
+    // `latest` tag or no tag → versionless
+    const version = tag !== undefined && tag !== "latest" && tag.length > 0 ? tag : undefined;
+    return { namespace, name, version };
+};
+/**
+ * Convert a parsed image reference to a DetectedPackage.
+ */
+const imageToPurl = (ref, source) => {
+    const parsed = parseImageRef(ref);
+    if (parsed === undefined)
+        return undefined;
+    const purl = new PackageURL("docker", parsed.namespace ?? null, parsed.name, parsed.version ?? null, null, null);
+    const purlParts = decodePurl(purl.toString());
+    return { purl: purlParts, type: dockerType, source };
+};
+/**
+ * Parse ARG directives from Dockerfile content.
+ * Returns a map of variable name to default value (or undefined if no default).
+ */
+const parseDockerArgs = (content) => {
+    const args = new Map();
+    const lines = content.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.toUpperCase().startsWith("ARG "))
+            continue;
+        const rest = trimmed.slice(4).trim();
+        const eqIdx = rest.indexOf("=");
+        if (eqIdx > 0) {
+            const name = rest.slice(0, eqIdx).trim();
+            const value = rest.slice(eqIdx + 1).trim();
+            args.set(name, value);
+        }
+        else {
+            args.set(rest, undefined);
+        }
+    }
+    return args;
+};
+/**
+ * Resolve a variable reference like `${VARIABLE}` using ARG defaults.
+ * Returns the resolved string, or undefined if unresolvable.
+ */
+const resolveVariable = (imageRef, args) => {
+    // Check if the entire reference or parts contain variables
+    const varPattern = /\$\{([^}]+)\}/g;
+    let resolved = imageRef;
+    let match = varPattern.exec(imageRef);
+    while (match !== null) {
+        const varName = match[1];
+        if (varName === undefined)
+            return undefined;
+        // Check for ${VAR:-default} syntax
+        const colonIdx = varName.indexOf(":-");
+        const defaultValue = colonIdx > 0 ? varName.slice(colonIdx + 2) : args.get(varName);
+        if (defaultValue === undefined)
+            return undefined;
+        resolved = resolved.replace(match[0], defaultValue);
+        match = varPattern.exec(imageRef);
+    }
+    return resolved;
+};
+/**
+ * Parse FROM directives from Dockerfile content.
+ */
+const parseDockerfile = (content, source) => {
+    const args = parseDockerArgs(content);
+    const lines = content.split("\n");
+    const results = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.toUpperCase().startsWith("FROM "))
+            continue;
+        const rest = trimmed.slice(5).trim();
+        // Remove AS alias
+        const parts = rest.split(/\s+/);
+        let imageRef = parts[0];
+        if (imageRef === undefined || imageRef.length === 0)
+            continue;
+        // Resolve variables
+        if (imageRef.includes("${")) {
+            const resolved = resolveVariable(imageRef, args);
+            if (resolved === undefined)
+                continue;
+            imageRef = resolved;
+        }
+        // Skip scratch
+        if (imageRef === "scratch")
+            continue;
+        const detected = imageToPurl(imageRef, source);
+        if (detected !== undefined)
+            results.push(detected);
+    }
+    return results;
+};
+/**
+ * Parse docker-compose YAML using line-based parsing.
+ * Extracts `image:` values from service definitions.
+ */
+const parseDockerCompose = (content, source) => {
+    const lines = content.split("\n");
+    const results = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("#"))
+            continue;
+        // Match `image: value` lines
+        if (trimmed.startsWith("image:")) {
+            const value = trimmed.slice(6).trim();
+            // Remove quotes if present
+            const cleaned = value.replace(/^["']|["']$/g, "");
+            if (cleaned.length > 0) {
+                const detected = imageToPurl(cleaned, source);
+                if (detected !== undefined)
+                    results.push(detected);
+            }
+        }
+    }
+    return results;
+};
+/**
+ * Docker package detector.
+ *
+ * Scans `Dockerfile`, `docker-compose.yml`, and `docker-compose.yaml`
+ * for image dependencies.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const dockerDetector = {
+    type: dockerType,
+    detect: Effect.fn("detect.docker")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const results = [];
+        // Parse Dockerfile
+        const dockerfilePath = path.join(projectDir, "Dockerfile");
+        const dockerfileContent = yield* readFileOptional(dockerfilePath);
+        if (Option.isSome(dockerfileContent)) {
+            const deps = parseDockerfile(dockerfileContent.value, dockerfilePath);
+            results.push(...deps);
+        }
+        // Parse docker-compose.yml
+        const composeYmlPath = path.join(projectDir, "docker-compose.yml");
+        const composeYmlContent = yield* readFileOptional(composeYmlPath);
+        if (Option.isSome(composeYmlContent)) {
+            const deps = parseDockerCompose(composeYmlContent.value, composeYmlPath);
+            results.push(...deps);
+        }
+        // Parse docker-compose.yaml
+        const composeYamlPath = path.join(projectDir, "docker-compose.yaml");
+        const composeYamlContent = yield* readFileOptional(composeYamlPath);
+        if (Option.isSome(composeYamlContent)) {
+            const deps = parseDockerCompose(composeYamlContent.value, composeYamlPath);
+            results.push(...deps);
+        }
+        return results;
+    }, Effect.annotateLogs({ detector: "docker" }), Effect.withSpan("detect.docker")),
+};
+/**
+ * Docker package reader.
+ *
+ * Inspects local Docker image metadata for `sh.axm.recommended-extensions`
+ * annotation. Since inspecting Docker images requires the Docker CLI,
+ * this reader returns Option.none when Docker is not available.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const dockerReader = {
+    type: dockerType,
+    read: Effect.fn("read.docker")(function* (pkg) {
+        const path = yield* Path.Path;
+        // Reconstruct the image name from purl parts
+        const imageName = pkg.purl.namespace
+            ? `${pkg.purl.namespace}/${pkg.purl.name}`
+            : pkg.purl.name;
+        const imageRef = pkg.purl.version ? `${imageName}:${pkg.purl.version}` : imageName;
+        // Derive project directory from source
+        const projectDir = path.dirname(pkg.source);
+        // Check for a local .axm-docker-annotations/<image>.json file
+        // This is a simplified approach that checks for sidecar annotation files
+        const safeImageName = imageRef.replace(/[/:]/g, "_");
+        const annotationPath = path.join(projectDir, ".axm-docker-annotations", `${safeImageName}.json`);
+        const content = yield* readFileOptional(annotationPath);
+        if (Option.isNone(content))
+            return Option.none();
+        const parsed = yield* parseJsonOptional(content.value, `docker annotations for ${imageRef}`);
+        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 docker image ${imageRef}: schema validation failed`);
+            return Option.none();
+        }
+        return Option.some(metaResult.success.extensions);
+    }, Effect.annotateLogs({ reader: "docker" }), Effect.withSpan("read.docker")),
+};
+//# sourceMappingURL=docker.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Ruby gem 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";
+/**
+ * Gem package detector.
+ *
+ * Scans `Gemfile` and `*.gemspec` files in the project directory and extracts
+ * gem dependencies. Deduplicates gems that appear in both sources.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const gemDetector: PackageDetector;
+/**
+ * Gem package reader.
+ *
+ * Reads gemspec metadata from `<gem-dir>/specifications/<gem>.gemspec`
+ * and extracts `axm_`-prefixed metadata keys.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const gemReader: PackageReader;
+//# sourceMappingURL=gem.d.ts.map

package/dist/src/packaging/gem.js

@@ -0,0 +1,234 @@
+/**
+ * Ruby gem 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 { envWithDefault } from "../internal/environment.js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, decodePurl, readFileOptional } from "./reader-io.js";
+const gemType = Schema.decodeUnknownSync(PackageTypeSchema)("gem");
+/** Range operators that indicate non-exact version constraints. */
+const RANGE_OPERATORS = ["~>", ">=", "<=", ">", "<", "!="];
+/**
+ * Returns true if the version specifier is an exact version (no range operators).
+ * Exact versions are bare numeric strings like "5.6.7".
+ */
+const isExactVersion = (specifier) => {
+    const trimmed = specifier.trim();
+    if (RANGE_OPERATORS.some((op) => trimmed.startsWith(op)))
+        return false;
+    return /^\d+(\.\d+)*$/.test(trimmed);
+};
+/**
+ * Regex to match `gem 'name'` or `gem "name"` directives in a Gemfile.
+ * Captures: gem name, optional version string, optional options.
+ */
+const GEMFILE_GEM_RE = /^\s*gem\s+['"]([^'"]+)['"]\s*(?:,\s*['"]([^'"]*)['"]\s*)?(?:,\s*(.*))?$/;
+/** Patterns for path/git/github options that indicate non-registry sources. */
+const SKIP_OPTIONS_RE = /\b(?:path|git|github)\s*:/;
+/**
+ * Parse a Gemfile line into a gem name and optional version, or undefined if skipped.
+ */
+const parseGemfileLine = (line, source) => {
+    const match = GEMFILE_GEM_RE.exec(line);
+    if (match === null)
+        return undefined;
+    const name = match[1];
+    const versionStr = match[2];
+    const options = match[3];
+    if (name === undefined)
+        return undefined;
+    // Check for path/git/github options - skip non-registry sources
+    if (options !== undefined && SKIP_OPTIONS_RE.test(options))
+        return undefined;
+    // Also check the full line for options that might come after the version
+    const afterName = line.slice(line.indexOf(name) + name.length);
+    if (SKIP_OPTIONS_RE.test(afterName))
+        return undefined;
+    const version = versionStr !== undefined && isExactVersion(versionStr) ? versionStr : undefined;
+    const purl = new PackageURL("gem", null, name, version ?? null, null, null);
+    const purlParts = decodePurl(purl.toString());
+    return { purl: purlParts, type: gemType, source };
+};
+/**
+ * Parse Gemfile content and extract gem dependencies.
+ */
+const parseGemfile = (content, source) => {
+    const lines = content.split("\n");
+    const results = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const detected = parseGemfileLine(trimmed, source);
+        if (detected !== undefined)
+            results.push(detected);
+    }
+    return results;
+};
+/**
+ * Regex to match add_dependency, add_runtime_dependency, add_development_dependency
+ * in gemspec files.
+ */
+const GEMSPEC_DEP_RE = /\.\s*add_(?:runtime_|development_)?dependency\s*\(?\s*['"]([^'"]+)['"]\s*(?:,\s*['"]([^'"]*)['"]\s*)?/;
+/**
+ * Parse a gemspec file and extract dependency declarations.
+ */
+const parseGemspec = (content, source) => {
+    const lines = content.split("\n");
+    const results = [];
+    for (const line of lines) {
+        const match = GEMSPEC_DEP_RE.exec(line);
+        if (match === null)
+            continue;
+        const name = match[1];
+        if (name === undefined)
+            continue;
+        const versionStr = match[2];
+        const version = versionStr !== undefined && isExactVersion(versionStr) ? versionStr : undefined;
+        const purl = new PackageURL("gem", null, name, version ?? null, null, null);
+        const purlParts = decodePurl(purl.toString());
+        results.push({ purl: purlParts, type: gemType, source });
+    }
+    return results;
+};
+/**
+ * Gem package detector.
+ *
+ * Scans `Gemfile` and `*.gemspec` files in the project directory and extracts
+ * gem dependencies. Deduplicates gems that appear in both sources.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const gemDetector = {
+    type: gemType,
+    detect: Effect.fn("detect.gem")(function* (projectDir) {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const results = [];
+        const seen = new Set();
+        const addUnique = (deps) => {
+            for (const dep of deps) {
+                const key = dep.purl.name;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    results.push(dep);
+                }
+            }
+        };
+        // Parse Gemfile
+        const gemfilePath = path.join(projectDir, "Gemfile");
+        const gemfileContent = yield* readFileOptional(gemfilePath);
+        if (Option.isSome(gemfileContent)) {
+            const deps = parseGemfile(gemfileContent.value, gemfilePath);
+            addUnique(deps);
+        }
+        // Parse *.gemspec files
+        const dirEntries = yield* fs.readDirectory(projectDir).pipe(Effect.option);
+        if (Option.isSome(dirEntries)) {
+            for (const entry of dirEntries.value) {
+                if (entry.endsWith(".gemspec")) {
+                    const gemspecPath = path.join(projectDir, entry);
+                    const gemspecContent = yield* readFileOptional(gemspecPath);
+                    if (Option.isSome(gemspecContent)) {
+                        const deps = parseGemspec(gemspecContent.value, gemspecPath);
+                        addUnique(deps);
+                    }
+                }
+            }
+        }
+        return results;
+    }, Effect.annotateLogs({ detector: "gem" }), Effect.withSpan("detect.gem")),
+};
+/**
+ * Resolve the GEM_HOME or default gem installation directory.
+ * Uses GEM_HOME env var, falling back to the default Ruby gems directory.
+ */
+const resolveGemDir = () => envWithDefault("GEM_HOME", `${os.homedir()}/.gem/ruby`);
+/**
+ * Parse the `axm_extensions` value from a gemspec metadata string.
+ * The value format is a JSON-stringified array of extension declaration objects.
+ */
+const parseAxmMetadataFromGemspec = (content) => {
+    const match = /"axm_extensions"\s*=>\s*"((?:\\.|[^"\\])*)"/.exec(content);
+    if (match === null || match[1] === undefined)
+        return undefined;
+    const rawValue = match[1];
+    try {
+        const decodedValue = JSON.parse(`"${rawValue}"`);
+        if (typeof decodedValue !== "string")
+            return undefined;
+        return { extensions: JSON.parse(decodedValue) };
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Gem package reader.
+ *
+ * Reads gemspec metadata from `<gem-dir>/specifications/<gem>.gemspec`
+ * and extracts `axm_`-prefixed metadata keys.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const gemReader = {
+    type: gemType,
+    read: Effect.fn("read.gem")(function* (pkg) {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const gemDir = yield* resolveGemDir();
+        const gemName = pkg.purl.name;
+        const version = pkg.purl.version;
+        // Try to find the gemspec in the specifications directory.
+        // Gemspec filename format: <name>-<version>.gemspec
+        const specsDir = path.join(gemDir, "specifications");
+        // If no version, try to find any matching gemspec
+        if (version !== undefined) {
+            const gemspecPath = path.join(specsDir, `${gemName}-${version}.gemspec`);
+            const content = yield* readFileOptional(gemspecPath);
+            if (Option.isNone(content))
+                return Option.none();
+            const axmMeta = parseAxmMetadataFromGemspec(content.value);
+            if (axmMeta === undefined)
+                return Option.none();
+            const metaResult = decodeAxmMeta(axmMeta);
+            if (Result.isFailure(metaResult)) {
+                yield* Effect.logWarning(`Invalid axm metadata in ${gemName}-${version}: schema validation failed`);
+                return Option.none();
+            }
+            return Option.some(metaResult.success.extensions);
+        }
+        // No version - scan specs directory for matching gemspec
+        const dirEntries = yield* fs.readDirectory(specsDir).pipe(Effect.option);
+        if (Option.isNone(dirEntries))
+            return Option.none();
+        const matchingSpec = dirEntries.value.find((entry) => entry.startsWith(`${gemName}-`) && entry.endsWith(".gemspec"));
+        if (matchingSpec === undefined)
+            return Option.none();
+        const gemspecPath = path.join(specsDir, matchingSpec);
+        const content = yield* readFileOptional(gemspecPath);
+        if (Option.isNone(content))
+            return Option.none();
+        const axmMeta = parseAxmMetadataFromGemspec(content.value);
+        if (axmMeta === undefined)
+            return Option.none();
+        const metaResult = decodeAxmMeta(axmMeta);
+        if (Result.isFailure(metaResult)) {
+            yield* Effect.logWarning(`Invalid axm metadata in ${gemName}: schema validation failed`);
+            return Option.none();
+        }
+        return Option.some(metaResult.success.extensions);
+    }, Effect.annotateLogs({ reader: "gem" }), Effect.withSpan("read.gem")),
+};
+//# sourceMappingURL=gem.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Go module 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";
+/**
+ * Go module package detector.
+ *
+ * Scans `go.mod` in the project directory and extracts direct dependencies
+ * from `require` directives, filtering out `// indirect` entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const golangDetector: PackageDetector;
+/**
+ * Go module package reader.
+ *
+ * Reads `axm.json` from `$GOPATH/pkg/mod/<module>@<version>/` for each
+ * detected Go module and extracts recommendation metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const golangReader: PackageReader;
+//# sourceMappingURL=golang.d.ts.map