@visulima/vis 1.0.0-alpha.8 → 1.0.0

package/dist/overrides.d.ts

@@ -1,82 +0,0 @@
-/**
- * Package manager override and resolution management.
- *
- * Handles the correct override location for each package manager:
- * - **pnpm v10+**: top-level `overrides` in `pnpm-workspace.yaml`
- * - **pnpm v9-**: `pnpm.overrides` in `package.json`
- * - **npm**: `overrides` in `package.json` (uses `$<name>` references
- *   for direct dependencies to avoid EOVERRIDE errors)
- * - **yarn / bun**: `resolutions` in `package.json`
- *
- * All overrides are root-level — no PM supports per-workspace overrides.
- * @see https://pnpm.io/settings — pnpm v10+ workspace settings
- * @see https://docs.npmjs.com/cli/v10/configuring-npm/package-json#overrides
- * @see https://yarnpkg.com/configuration/manifest#resolutions
- * @see https://bun.sh/docs/pm/overrides
- */
-/** Supported package manager names. */
-type PackageManagerName = "bun" | "npm" | "pnpm" | "yarn";
-/** Package manager identity with version for PM-specific behavior. */
-interface PmInfo {
-    name: PackageManagerName;
-    version: string;
-}
-/** A single override entry mapping an original package to its replacement spec. */
-interface OverrideEntry {
-    /** The original package name being overridden (e.g., `"is-regex"`). */
-    original: string;
-    /** The npm alias spec (e.g., `"npm:@socketregistry/is-regex@^1"`). */
-    spec: string;
-}
-/** Result of reading existing overrides from the project. */
-interface OverridesResult {
-    /** Current overrides — values may be strings or nested objects (npm supports nested overrides). */
-    overrides: Record<string, string | Record<string, string>>;
-    /** The file where overrides are stored. */
-    source: "package.json" | "pnpm-workspace.yaml";
-}
-/** Result of applying override entries. */
-interface ApplyOverridesResult {
-    /** Package names that were newly added. */
-    added: string[];
-    /** Package names whose specs were changed. */
-    updated: string[];
-}
-/**
- * Reads existing overrides for the detected package manager, choosing
- * `pnpm-workspace.yaml` for pnpm v10+ and `package.json` for everything else.
- */
-declare const readOverrides: (workspaceRoot: string, pkgJson: Record<string, unknown>, pm: PmInfo) => OverridesResult;
-/**
- * Applies override entries to the correct config file for the package manager.
- *
- * For npm, direct dependencies use `$&lt;name>` reference syntax to avoid
- * npm's EOVERRIDE error when an override conflicts with a direct dep range.
- * @param workspaceRoot Absolute path to the workspace root directory.
- * @param pkgJsonPath Absolute path to the root `package.json`.
- * @param entries Override entries to apply.
- * @param pm Package manager name and version.
- * @returns Lists of added and updated package names.
- */
-declare const applyOverrides: (workspaceRoot: string, pkgJsonPath: string, entries: OverrideEntry[], pm: PmInfo) => ApplyOverridesResult;
-/**
- * Reads the lockfile text for a workspace root.
- *
- * Returns the raw text content for regex-based package name scanning.
- * Falls back to an empty string if the lockfile is missing or unreadable.
- * @param workspaceRoot Absolute path to the workspace root.
- * @param pm Package manager name (determines lockfile name).
- */
-declare const readLockfileText: (workspaceRoot: string, pm: PackageManagerName) => string;
-/**
- * Checks if a package name appears in the lockfile text using PM-specific string patterns.
- *
- * This avoids parsing the entire lockfile — a single `string.includes()` is
- * sufficient for presence checks.
- * @param lockText Raw lockfile content.
- * @param packageName Package name to search for.
- * @param pm Package manager name (determines the search pattern).
- */
-declare const lockfileContainsPackage: (lockText: string, packageName: string, pm: PackageManagerName) => boolean;
-export type { ApplyOverridesResult, OverrideEntry, OverridesResult, PackageManagerName, PmInfo };
-export { applyOverrides, lockfileContainsPackage, readLockfileText, readOverrides };

package/dist/package-manager.d.ts

@@ -1,23 +0,0 @@
-interface UpdateCommandOptions {
-    dev: boolean;
-    filters: string[];
-    global: boolean;
-    interactive: boolean;
-    latest: boolean;
-    noOptional: boolean;
-    noSave: boolean;
-    packages: string[];
-    prod: boolean;
-    recursive: boolean;
-    workspaceRoot: boolean;
-}
-interface ResolvedCommand {
-    args: string[];
-    bin: string;
-}
-declare const resolveUpdateCommand: (packageManager: "bun" | "npm" | "pnpm" | "yarn", version: string, options: UpdateCommandOptions) => {
-    command: ResolvedCommand;
-    warnings: string[];
-};
-export type { ResolvedCommand, UpdateCommandOptions };
-export { resolveUpdateCommand };

package/dist/packem_shared/otelPlugin-CJLkguJ8.js

@@ -1 +0,0 @@
-import{otelPlugin as l}from"../config.js";export{l as otelPlugin};

package/dist/plugins/config-loader.d.ts

@@ -1,3 +0,0 @@
-import type { Plugin } from "@visulima/cerebro";
-declare const configLoaderPlugin: Plugin;
-export default configLoaderPlugin;

package/dist/plugins/otel.d.ts

@@ -1,63 +0,0 @@
-import type { Task } from "@visulima/task-runner";
-import type { VisPlugin } from "../hooks.d.ts";
-/**
- * Minimal OTel-shaped span. Deliberately structural so users can pass
- * an `@opentelemetry/api` Tracer, an `@opentelemetry/sdk-node` one, or
- * a custom implementation without the plugin depending on any
- * particular OTel package.
- */
-export interface OtelSpan {
-    end: () => void;
-    recordException?: (error: unknown) => void;
-    setAttribute?: (key: string, value: boolean | number | string) => void;
-    setStatus?: (status: {
-        code: number;
-        message?: string;
-    }) => void;
-}
-/**
- * Minimal Tracer contract. Accepts the real
- * `@opentelemetry/api`'s `Tracer.startSpan(name, options?)` shape —
- * the plugin only calls the two methods it strictly needs.
- */
-export interface OtelTracer {
-    startSpan: (name: string, options?: {
-        attributes?: Record<string, string | number | boolean>;
-    }) => OtelSpan;
-}
-export interface OtelPluginOptions {
-    /**
-     * Rename incoming `project:target` IDs before they become OTel
-     * span names. Defaults to passing the id through unchanged.
-     */
-    renameSpan?: (task: Task) => string;
-    /** Tracer used to emit spans. Required — pass the one from `@opentelemetry/api`'s `trace.getTracer("vis")`. */
-    tracer: OtelTracer;
-}
-/**
- * Reference plugin that maps vis hook lifecycle events to OTel spans.
- *
- * Emits:
- * - one **root span** named `vis.run` spanning `run:before` → `run:after`
- * - one **child span** per task spanning `task:before` → `task:after`
- *   with attributes `vis.task.id`, `vis.task.project`, `vis.task.target`,
- *   `vis.task.cache_status`, `vis.task.exit_code`
- * - `task:failure` sets span status to ERROR and records the exit code
- *
- * Streaming stdout/stderr events are intentionally **not** emitted as
- * span events — high-frequency chunks would blow up OTel backends. Use
- * a log exporter if you need stream-level visibility.
- * @example
- * ```ts
- * import { trace } from "@opentelemetry/api";
- * import { defineConfig } from "@visulima/vis/config";
- * import { otelPlugin } from "@visulima/vis/plugins/otel";
- *
- * const tracer = trace.getTracer("vis", "1.0.0");
- *
- * export default defineConfig({
- *     plugins: [otelPlugin({ tracer })],
- * });
- * ```
- */
-export declare const otelPlugin: (options: OtelPluginOptions) => VisPlugin;

package/dist/plugins/post-command.d.ts

@@ -1,3 +0,0 @@
-import type { Plugin } from "@visulima/cerebro";
-declare const postCommandPlugin: (upgradeCheckCallback?: () => void) => Plugin;
-export default postCommandPlugin;

package/dist/plugins/security-enforcement.d.ts

@@ -1,3 +0,0 @@
-import type { Plugin } from "@visulima/cerebro";
-declare const securityEnforcementPlugin: Plugin;
-export default securityEnforcementPlugin;

package/dist/pm-runner.d.ts

@@ -1,44 +0,0 @@
-/**
- * Shared helper for executing package manager commands via native Rust bindings.
- * Falls back to JS-based detection when native bindings are unavailable.
- */
-import type { AddOptions, DlxOptions, ExecOptions, InstallOptions, OutdatedOptions, RemoveOptions, ResolvedCommand, WhyOptions } from "./native-binding.d.ts";
-interface PmInfo {
-    name: "bun" | "npm" | "pnpm" | "yarn";
-    version: string;
-}
-declare const detectPm: (cwd: string) => PmInfo;
-declare const runInstall: (pm: PmInfo, options: InstallOptions, cwd: string, logger: Console) => number;
-declare const runAdd: (pm: PmInfo, options: AddOptions, cwd: string, logger: Console) => number;
-declare const runRemove: (pm: PmInfo, options: RemoveOptions, cwd: string, logger: Console) => number;
-declare const runDedupe: (pm: PmInfo, check: boolean, cwd: string, logger: Console) => number;
-declare const runWhy: (pm: PmInfo, options: WhyOptions, cwd: string, logger: Console) => number;
-declare const runOutdated: (pm: PmInfo, options: OutdatedOptions, cwd: string, logger: Console) => number;
-interface InfoOptions {
-    fields: string[];
-    json: boolean;
-    package: string;
-}
-/**
- * Resolves a registry metadata lookup to a runnable command. Built in TS
- * rather than the Rust resolver because bun needs `pm view` (two-word
- * subcommand) and yarn berry needs `yarn npm info` — both shapes the existing
- * `resolve_pm_command` view branch gets wrong.
- *
- * Pure function — exported for unit testing.
- */
-declare const resolveInfo: (pm: PmInfo, options: InfoOptions) => ResolvedCommand;
-declare const runInfo: (pm: PmInfo, options: InfoOptions, cwd: string, logger: Console) => number;
-/**
- * Resolves and runs a PM `link` operation. Passes `pm.version` to the native
- * resolver so it can warn about pnpm v11 restrictions (arg-less link and
- * global-store name resolution were removed). `target` is `null` for arg-less
- * link, or a package name / path string.
- */
-declare const runLink: (pm: PmInfo, target: string | null, cwd: string, logger: Console) => number;
-declare const runUnlink: (pm: PmInfo, packages: string[], recursive: boolean, cwd: string, logger: Console) => number;
-declare const runDlx: (pm: PmInfo, options: DlxOptions, cwd: string, logger: Console) => number;
-declare const runExec: (pm: PmInfo, options: ExecOptions, cwd: string, logger: Console) => number;
-declare const runPmSubcommand: (pm: PmInfo, subcommand: string, args: string[], cwd: string, logger: Console) => number;
-export type { InfoOptions, PmInfo };
-export { detectPm, resolveInfo, runAdd, runDedupe, runDlx, runExec, runInfo, runInstall, runLink, runOutdated, runPmSubcommand, runRemove, runUnlink, runWhy };

package/dist/run-report.d.ts

@@ -1,40 +0,0 @@
-import type { TaskResults } from "@visulima/task-runner";
-/**
- * Formats a compact one-line timing summary for display after a run.
- * @param results Task execution results.
- * @param durationMs Total wall-clock duration in milliseconds.
- * @returns A formatted summary string, e.g. "3 succeeded · 1 cached · 0 failed · 2.4s"
- */
-export declare const formatTimingSummary: (results: TaskResults, durationMs: number) => string;
-/**
- * Shape of a persisted run summary — only the fields this module + the
- * flakiness analyzer consume. Kept narrow so both consumers can share
- * one loader without pulling in the full `RunSummary` type from
- * task-runner.
- */
-export interface LoadedRunSummary {
-    [key: string]: unknown;
-    duration?: number;
-    startTime?: string;
-    tasks?: unknown[];
-}
-/**
- * Reads every `.task-runner/runs/*.json` once and returns the parsed
- * array. Callers that need to iterate historical runs (timing average,
- * flakiness analysis) should call this once per command and feed the
- * result into the downstream helpers rather than re-reading the
- * directory multiple times.
- *
- * Corrupt or unreadable files are skipped silently — a single bad
- * summary shouldn't take down the whole analysis.
- */
-export declare const loadRunSummaries: (workspaceRoot: string) => LoadedRunSummary[];
-/**
- * Loads durations from historical run summaries and computes the
- * average. Returns the comparison string or `undefined` if no history.
- *
- * Pass `summaries` (from {@link loadRunSummaries}) when the caller
- * has already loaded the history for another purpose (e.g. flakiness
- * analysis on a failing run) to avoid re-reading the same files.
- */
-export declare const compareDuration: (workspaceRoot: string, currentDurationMs: number, summaries?: LoadedRunSummary[]) => string | undefined;

package/dist/runtime-check.d.ts

@@ -1,27 +0,0 @@
-/**
- * Runtime-version mismatch finding. vis doesn't manage runtimes directly,
- * but it can warn when the currently running Node/Bun/Deno doesn't match
- * whatever the repo has declared — usually a sign the user forgot to
- * switch runtimes for this workspace.
- */
-export interface RuntimeFinding {
-    actual: string;
-    expected: string;
-    kind: "node" | "packageManager";
-    message: string;
-    severity: "error" | "warning";
-}
-/**
- * Evaluates a minimal subset of semver ranges: `>=X`, `X.Y`, `X.Y.Z`,
- * and compound `>=X <Y`. Returns true if `actual` satisfies the range.
- * Falls back to "true" for unrecognised syntax rather than false so we
- * don't spam warnings on exotic ranges.
- */
-export declare const satisfiesRange: (actual: string, range: string) => boolean;
-/**
- * Checks `engines.node`, `.nvmrc`, `.node-version`, and `packageManager`
- * against the running process.
- * @param workspaceRoot Absolute path to the workspace root.
- * @returns Findings; an empty array means everything matches.
- */
-export declare const checkRuntimeVersions: (workspaceRoot: string) => RuntimeFinding[];

package/dist/sbom/cyclonedx.d.ts

@@ -1,39 +0,0 @@
-import type { ProjectGraph, WorkspaceConfiguration } from "@visulima/task-runner";
-import type { CycloneDxBom } from "./types.d.ts";
-export interface BuildSbomOptions {
-    /** If set, limit the emitted BOM to these projects + their transitive closure. */
-    focus?: string[];
-    /** Optional package.json version of vis itself — stamped into `metadata.tools`. */
-    generatorVersion?: string;
-    /** Include devDependencies in the emitted BOM (default: false — production only). */
-    includeDev?: boolean;
-    /**
-     * Override the `serialNumber`. Useful for deterministic tests; in
-     * production the builder generates one per call.
-     */
-    now?: Date;
-    /** Project graph used for resolving focus closure and dependency edges. */
-    projectGraph: ProjectGraph;
-    /** Override the `serialNumber` (defaults to a fresh UUID). */
-    serialNumber?: string;
-    /** Workspace configuration with resolved project roots. */
-    workspace: WorkspaceConfiguration;
-    /** Workspace root on disk. */
-    workspaceRoot: string;
-}
-/**
- * Builds the BOM from workspace + lockfile data. Pure function — all
- * I/O is relative to `workspaceRoot` so tests point it at a temp dir.
- */
-export declare const buildCycloneDxBom: (options: BuildSbomOptions) => CycloneDxBom;
-/**
- * Serialises a {@link CycloneDxBom} document to CycloneDX 1.6 XML.
- *
- * Delegates all escaping, indentation, and attribute serialisation to
- * the project-standard `jstoxml` library (already used elsewhere in
- * the monorepo — see `packages/api/api-platform` and
- * `packages/error-debugging/error-handler`). We only translate our
- * typed JSON-shaped BOM into jstoxml's `{ _name, _attrs, _content }`
- * tree.
- */
-export declare const serializeBomToXml: (bom: CycloneDxBom) => string;

package/dist/sbom/installed-package.d.ts

@@ -1,49 +0,0 @@
-/**
- * Per-version metadata lookup for installed packages.
- *
- * An SBOM needs each `name@version` component to declare its own
- * licence, description, and author — not the top-level project's.
- * Different versions of the same package can ship different licence
- * texts (common during a licence migration, e.g. `foo@4` is MIT but
- * `foo@5` is Apache-2.0), so we resolve the metadata against the
- * specific on-disk install tree rather than the lockfile or a single
- * hoisted copy.
- *
- * The helper is best-effort: we try common install-tree layouts in
- * order and return `undefined` the moment we fail to find a match. A
- * missing metadata doesn't block SBOM generation — the component is
- * just emitted without licence/author/description decoration.
- */
-import type { RawLicenseInput } from "./license.d.ts";
-/** Subset of `package.json` surfaced onto installed-package components. */
-export interface InstalledPackageMetadata extends RawLicenseInput {
-    author?: string | {
-        email?: string;
-        name?: string;
-        url?: string;
-    };
-    bugs?: string | {
-        url?: string;
-    };
-    description?: string;
-    homepage?: string;
-    name?: string;
-    repository?: string | {
-        type?: string;
-        url?: string;
-    };
-    version?: string;
-}
-/**
- * Looks up the installed `package.json` for a specific `name@version`.
- * Tries pnpm's virtual store first (exact match by construction), then
- * falls back to the hoisted `node_modules/<name>/package.json` if its
- * version matches.
- *
- * Returns `undefined` if nothing on disk matches the requested version,
- * **or if `name`/`version` contains characters that could be used for
- * path traversal**. A malicious lockfile carrying e.g.
- * `version: "../../../etc"` would otherwise escape `workspaceRoot`
- * because `join` collapses `..` segments.
- */
-export declare const readInstalledPackageMetadata: (workspaceRoot: string, name: string, version: string) => InstalledPackageMetadata | undefined;

package/dist/sbom/license.d.ts

@@ -1,31 +0,0 @@
-import type { LicenseChoice } from "./types.d.ts";
-/**
- * Case-insensitively resolves a raw licence string to its canonical
- * SPDX ID, or `undefined` if the input doesn't match anything we know
- * about.
- */
-export declare const normalizeSpdxId: (raw: string) => string | undefined;
-/** Shape we accept from raw `package.json` metadata. */
-export interface RawLicenseInput {
-    /** Legacy `license: { type: "MIT" }` form. */
-    license?: {
-        type?: string;
-    } | string;
-    /** Legacy `licenses: [{ type: "MIT" }]` array form. */
-    licenses?: {
-        type?: string;
-    }[];
-}
-/**
- * Extracts a single licence declaration from a `package.json` (or
- * similar), converting it to the CycloneDX {@link LicenseChoice}
- * shape. Supports the three encodings npm has historically blessed:
- *
- * - `license: "MIT"` (string)
- * - `license: "(MIT OR Apache-2.0)"` (SPDX expression)
- * - `license: { type: "MIT" }` (object, deprecated but common)
- * - `licenses: [{ type: "MIT" }, …]` (array, deprecated)
- *
- * Returns `undefined` if no licence was declared.
- */
-export declare const extractLicenseChoice: (input: RawLicenseInput) => LicenseChoice | undefined;

package/dist/sbom/lockfile.d.ts

@@ -1,34 +0,0 @@
-/**
- * Thin CycloneDX-shaped adapter over the shared lockfile parser in
- * `@visulima/package`. The cross-package parser returns a
- * package-manager-agnostic `{ name, version, integrity: { algorithm, hex } }`
- * shape; CycloneDX 1.6 expects hashes as `{ alg: "SHA-256" | …, content }`,
- * so we translate the algorithm casing here.
- */
-import type { LockFileType } from "@visulima/package";
-import type { Hash } from "./types.d.ts";
-/** Exposed so downstream callers (and tests) can stay decoupled from `@visulima/package`. */
-/** Resolved package in the shape the SBOM builder consumes. */
-export interface ResolvedPackage {
-    /**
-     * Declared runtime deps — `name → specifier[]` from the lockfile.
-     * Arrays preserve pnpm v9+ peer-context variants that resolve the
-     * same dep name to different versions.
-     */
-    dependencies?: Record<string, string[]>;
-    hash?: Hash;
-    name: string;
-    optionalDependencies?: Record<string, string[]>;
-    peerDependencies?: Record<string, string[]>;
-    version: string;
-}
-/**
- * Reads the lockfile at `workspaceRoot` (not ancestors — workspaces
- * own their lockfile) and returns entries keyed by `name@version`.
- * Returns `undefined` if no supported lockfile is present.
- */
-export declare const readLockfilePackages: (workspaceRoot: string) => {
-    packages: Map<string, ResolvedPackage>;
-    type: LockFileType;
-} | undefined;
-export { type LockFileType } from "@visulima/package";

package/dist/sbom/purl.d.ts

@@ -1,25 +0,0 @@
-/**
- * Zero-dependency implementation of the Package URL (PURL) spec, scoped
- * to the `pkg:npm/…` type — the only scheme CycloneDX 1.6 needs for
- * npm-ecosystem SBOMs.
- *
- * Reference: https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#npm
- *
- * Rules we implement:
- *
- * 1. The `name` segment is **lowercased** for `pkg:npm` (npm package
- *    names are already case-insensitive in the registry).
- * 2. Scope is carried as a PURL **namespace** (`pkg:npm/@scope/name`)
- *    with the `@` percent-encoded per RFC 3986 (→ `%40`).
- * 3. `name`, `namespace`, and `version` segments are percent-encoded
- *    using the "unreserved characters + colon/slash inside version"
- *    ruleset — we keep this small and conservative (encode anything
- *    outside `[A-Za-z0-9._~-]`).
- */
-/**
- * Builds a `pkg:npm/…` Package URL from an npm package name + version.
- * @param packageName The npm package name, scoped or unscoped.
- * @param version The resolved exact version.
- * @returns A well-formed PURL string.
- */
-export declare const toNpmPurl: (packageName: string, version: string) => string;

package/dist/sbom/resolve-specifier.d.ts

@@ -1,24 +0,0 @@
-/**
- * Resolves `name + specifier` to a concrete `name@version` install from
- * a lockfile-derived index.
- *
- * Lockfiles don't encode every edge uniformly:
- *
- * - pnpm stores **resolved** versions in each entry's `dependencies`
- *   sub-map, so the specifier is already the install's exact version.
- * - npm / yarn / bun store **semver ranges** (or dist-tags); we have
- *   to match the range against the set of versions we know exist for
- *   the given `name`.
- *
- * We try exact match first (cheap, handles pnpm), then fall back to
- * `semver.maxSatisfying` over every known version of `name`, and
- * finally to "pick one version" so a partial-lockfile input still
- * produces a best-effort edge.
- */
-/** `name → Set<version>` index built from every lockfile entry. */
-export type VersionIndex = Map<string, Set<string>>;
-/**
- * Resolves a single `name + specifier` pair to a concrete version, or
- * `undefined` if the name isn't in the lockfile at all.
- */
-export declare const resolveSpecifier: (name: string, specifier: string, index: VersionIndex) => string | undefined;