@visulima/vis 1.0.0-alpha.5 → 1.0.0-alpha.7

package/dist/workspace.d.ts

@@ -1,5 +1,15 @@
-import type { ConstraintsConfig, ProjectGraph, TargetConfiguration, WorkspaceConfiguration } from "@visulima/task-runner";
-import type { Configuration as StagedConfig } from "lint-staged";
+import type { ConstraintsConfig, NamedInputs, ProjectConfiguration, ProjectGraph, TargetConfiguration, WorkspaceConfiguration } from "@visulima/task-runner";
+import type { VisPlugin } from "./hooks.d.ts";
+import type { StagedConfig } from "./staged/index.d.ts";
+import type { VisTargetConfiguration } from "./target-options.d.ts";
+export interface CodeownersConfig {
+    /** Workspace-level paths that apply outside any project (e.g., `.github/**`). */
+    globalPaths?: Record<string, string[]>;
+    /** Sort order for generated entries — mirrors moon's `orderBy`. */
+    orderBy?: "file-source" | "project-id";
+    /** Provider determines whether `channel` is emitted (GitHub supports it via comment). */
+    provider?: "bitbucket" | "github" | "gitlab" | "other";
+}
 interface PackageJson {
     bin?: Record<string, string> | string;
     dependencies?: Record<string, string>;
@@ -12,6 +22,77 @@ interface PackageJson {
         packages?: string[];
     };
 }
+/**
+ * Declared code-owner assignment for a path glob within a project.
+ * Mirrors moon's `owners` shape so migrations can round-trip cleanly.
+ */
+export interface OwnersEntry {
+    /** Optional notification channel (e.g. Slack, Teams). */
+    channel?: string;
+    /** Owner handles (e.g. `@visulima/core-team`). */
+    owners: string[];
+    /** File/glob pattern relative to the project root. */
+    path: string;
+}
+/**
+ * Per-project metadata surfaced by `project.json`. Extended beyond the
+ * minimal `projectType` / `tags` / `sourceRoot` fields we historically
+ * parsed to include targets, owners, and layer/stack classification.
+ */
+export interface ProjectJson {
+    /** Implicit dependencies on other projects. */
+    implicitDependencies?: string[];
+    /** Primary language — informational and query-able. */
+    language?: string;
+    /** Project layer, used for constraint inheritance and query filtering. */
+    layer?: "application" | "automation" | "configuration" | "library" | "scaffolding" | "tool";
+    /** Code owners for paths inside this project. */
+    owners?: OwnersEntry[];
+    /** Project-level metadata. */
+    project?: {
+        channel?: string;
+        description?: string;
+        maintainers?: string[];
+        owner?: string;
+        title?: string;
+    };
+    /** Project type — library or application. */
+    projectType?: "application" | "library";
+    /** Source root, used for display and language inference. */
+    sourceRoot?: string;
+    /** Tech stack. */
+    stack?: "backend" | "data" | "frontend" | "infrastructure" | "systems";
+    /** Filterable tags. */
+    tags?: string[];
+    /** Vis-style target definitions (merged on top of package.json scripts). */
+    targets?: Record<string, VisTargetConfiguration>;
+}
+/**
+ * A scope predicate used by {@link VisConfig.taskDefaults}.
+ * All listed constraints must match for the block to apply.
+ */
+export interface TaskDefaultsScope {
+    /** Match on primary language. */
+    language?: string | string[];
+    /** Match on project layer. */
+    layer?: ProjectJson["layer"] | ProjectJson["layer"][];
+    /** Match on project type. */
+    projectType?: "application" | "library";
+    /** Match on project stack. */
+    stack?: ProjectJson["stack"] | ProjectJson["stack"][];
+    /** Match projects tagged with any of these tags. */
+    tags?: string[];
+}
+/**
+ * A single task-defaults block — a set of target defaults gated by an
+ * optional scope predicate.
+ */
+export interface TaskDefaultsBlock {
+    /** Optional scope predicate; if omitted, the block applies universally. */
+    scope?: TaskDefaultsScope;
+    /** Target default configurations. */
+    targets: Record<string, Partial<VisTargetConfiguration>>;
+}
 interface VisConfig {
     /** AI analysis configuration */
     ai?: {
@@ -22,6 +103,23 @@ interface VisConfig {
         /** Use a specific provider instead of auto-detecting (e.g., `"claude"`, `"gemini"`). */
         provider?: string;
     };
+    /**
+     * Scope the task-runner cache directory by the current git branch.
+     * When `true`, caches are stored under `&lt;cacheDir>/branches/&lt;slug>`
+     * so `main` and feature branches stop thrashing each other —
+     * generated artefacts (schemas, `.d.ts` snapshots) that legitimately
+     * differ across branches no longer oscillate the cache contents.
+     *
+     * Falls back to the unscoped path on detached HEAD, non-git
+     * workspaces, or when git isn't available.
+     * @default false
+     */
+    branchScopedCache?: boolean;
+    /**
+     * Code ownership configuration. Controls how `vis sync codeowners`
+     * renders the generated CODEOWNERS file.
+     */
+    codeowners?: CodeownersConfig;
     /**
      * Project dependency constraints.
      * Enforced after building the project graph, before running tasks.
@@ -93,8 +191,117 @@ interface VisConfig {
          */
         templates?: Record<string, string>;
     };
+    /**
+     * Named file-group patterns, reusable from target `inputs` via the
+     * `@filegroup:&lt;name>` token. File groups are resolved relative to each
+     * project root at discovery time.
+     * @example
+     * ```
+     * fileGroups: {
+     *   sources: ["src/**\/*.ts", "!src/**\/*.test.ts"],
+     *   tests: ["**\/*.test.ts"],
+     * }
+     * ```
+     */
+    fileGroups?: Record<string, string[]>;
+    /**
+     * Configuration for the `vis generate` in-repo scaffolding command.
+     * Points at additional template directories beyond the defaults
+     * (`.vis/templates/` and `.moon/templates/`).
+     */
+    generator?: {
+        /**
+         * Authorization token forwarded to giget when fetching
+         * `git://`/`npm://` remote templates. Falls back to
+         * `GIGET_AUTH` / `GITHUB_TOKEN` / `GH_TOKEN` env vars.
+         */
+        auth?: string;
+        /**
+         * Prefer locally cached remote templates over re-downloading.
+         * Overridable per invocation via `--prefer-offline`.
+         * @default false
+         */
+        preferOffline?: boolean;
+        /**
+         * Extra directories to scan for templates. Each directory is
+         * checked for both native templates (`&lt;name>.ts`) and
+         * moon-format directories (containing `template.yml`).
+         * @example
+         * ```
+         * generator: {
+         *   templates: ["./tools/generators", "./packages/scaffolding/templates"],
+         * }
+         * ```
+         */
+        templates?: string[];
+    };
+    /**
+     * Named input patterns inherited by every project target. Equivalent
+     * to task-runner's `namedInputs` but configurable from the vis config.
+     */
+    namedInputs?: NamedInputs;
     /** Package override mappings applied during migration (e.g., `{ "lodash": "lodash-es" }`) */
     overrides?: Record<string, string>;
+    /**
+     * Plugins — each plugin registers typed hooks that fire at run /
+     * task / cache boundaries. See {@link VisPlugin} for the contract.
+     * Prefer plugins over per-target shell hooks when behaviour needs
+     * access to task metadata, results, or cache state.
+     */
+    plugins?: VisPlugin[];
+    /**
+     * Default options for `vis secrets`. CLI flags always take precedence;
+     * this block provides workspace-wide defaults so teams can commit config
+     * once and every invocation picks it up.
+     */
+    secrets?: {
+        /** Path to a baseline of previously-triaged findings (relative to workspace root). */
+        baseline?: string;
+        /** Where the ruleset comes from. Omit for the bundled gitleaks default. */
+        config?: {
+            /** Layer the user's rules on top of the bundled ruleset. Default: `true`. */
+            extendBundled?: boolean;
+            /** Inline rule overrides. Wins over `path` when both are set. */
+            inline?: {
+                allowlist?: unknown;
+                allowlists?: unknown[];
+                description?: string;
+                rules?: unknown[];
+                title?: string;
+            };
+            /** Path to a JSON config (gitleaks-compatible). */
+            path?: string;
+            /** Bundled presets layered on top of the default ruleset (e.g. `"weak-passwords"`). */
+            presets?: string[];
+        };
+        /** Redact secret values in findings. */
+        redact?: boolean;
+        /** Rule-id filters applied after scanning. */
+        rules?: {
+            /** Drop findings whose ruleId matches. */
+            exclude?: string[];
+            /** Only report findings whose ruleId matches. */
+            include?: string[];
+        };
+        /** Walker / filesystem traversal. */
+        walk?: {
+            /**
+             * Paths to additional `.gitignore`-syntax files (e.g. `.secretsignore`).
+             */
+            excludeFromFiles?: string[];
+            /**
+             * Gitignore-syntax patterns (supports negation, directory markers, leading `/`).
+             * Applied on top of `.gitignore`.
+             */
+            excludePatterns?: string[];
+            /** Respect `.gitignore`. Default: `true`. */
+            gitignore?: boolean;
+            /** Include hidden (dotfile) entries. Default: `false`. */
+            includeHidden?: boolean;
+            /** Max file size in bytes. Default 10 MiB. */
+            maxFileSize?: number;
+        };
+    };
     /**
      * Supply chain security settings.
      * These settings are inspired by pnpm's security features and are applied
@@ -259,7 +466,36 @@ interface VisConfig {
      */
     staged?: StagedConfig;
     /** Target default configurations */
-    targetDefaults?: Record<string, Partial<TargetConfiguration>>;
+    targetDefaults?: Record<string, Partial<VisTargetConfiguration>>;
+    /**
+     * Cascading task-default blocks. Each block may scope its targets to a
+     * subset of projects via `scope`. Blocks are evaluated in order; later
+     * blocks override earlier ones when the same field is set.
+     *
+     * Scope matching is additive — if `scope` is omitted, the block applies
+     * to every project.
+     * @example
+     * ```
+     * taskDefaults: [
+     *   { scope: { tags: ["frontend"] }, targets: { build: { cache: true } } },
+     *   { scope: { projectType: "library" }, targets: { lint: { cache: true } } },
+     * ]
+     * ```
+     */
+    taskDefaults?: TaskDefaultsBlock[];
+    /**
+     * Named bundles of target dependencies, referenceable from any task's
+     * `dependsOn`. `dependsOn: [{ group: "lint" }]` expands to every entry
+     * in the named group; nested groups are resolved recursively and a
+     * cycle raises during discovery.
+     */
+    taskGroups?: Record<string, (string | {
+        dependencies?: boolean;
+        projects?: string | string[];
+        target: string;
+    } | {
+        group: string;
+    })[]>;
     /** Task runner options */
     taskRunnerOptions?: Record<string, unknown>;
     /** Terminal UI configuration */
@@ -329,6 +565,15 @@ interface VisConfig {
         security?: boolean;
         target?: "latest" | "minor" | "patch";
     };
+    /**
+     * Minimum vis CLI version required by this workspace. When the
+     * running vis binary is older than this constraint, vis exits with
+     * an actionable error before executing any command.
+     *
+     * Accepts a semver range string (e.g. `">=1.0.0"`, `"^1.2.0"`).
+     * @example ">=1.0.0"
+     */
+    versionConstraint?: string;
 }
 /**
  * Resolves glob-like workspace patterns to actual directories.
@@ -338,18 +583,93 @@ declare const resolveWorkspacePatterns: (workspaceRoot: string, patterns: string
 /**
  * Reads workspace patterns from pnpm-workspace.yaml (simple parser).
  */
+/**
+ * Expands every `{ group: "name" }` entry in a target's `dependsOn`
+ * into the group's declared members, recursively resolving nested
+ * groups and detecting cycles.
+ *
+ * Runs once per workspace discovery so task-runner's graph builder
+ * only ever sees bare dependency entries — groups are pure vis sugar.
+ */
+export declare const expandTaskGroups: (dependsOn: (string | {
+    dependencies?: boolean;
+    projects?: string | string[];
+    target: string;
+} | {
+    group: string;
+})[] | undefined, groups: VisConfig["taskGroups"], seen?: Set<string>) => (string | {
+    dependencies?: boolean;
+    projects?: string | string[];
+    target: string;
+})[];
+/**
+ * Validates the root `package.json` `workspaces` field and returns the
+ * resolved pattern array. Throws a clear diagnostic when the field is
+ * malformed (empty array, wrong type, object without `packages`)
+ * instead of falling through to a vague "no workspace configuration
+ * found" error that hides the real problem.
+ */
+declare const validateWorkspacesField: (raw: PackageJson["workspaces"]) => string[];
 declare const readPnpmWorkspacePatterns: (workspaceRoot: string) => string[] | undefined;
+/**
+ * Returns true if the named {@link TaskDefaultsBlock} scope matches the
+ * given project metadata. Missing scope fields are treated as "any".
+ */
+declare const scopeMatches: (scope: TaskDefaultsScope | undefined, projectJson: ProjectJson | undefined, projectType: "application" | "library") => boolean;
+/**
+ * Returns the merged target defaults that apply to a project, combining
+ * the flat `config.targetDefaults` with all matching `config.taskDefaults`
+ * blocks in declaration order. Later entries override earlier ones.
+ */
+declare const collectTargetDefaults: (config: VisConfig, projectJson: ProjectJson | undefined, projectType: "application" | "library") => Record<string, Partial<VisTargetConfiguration>>;
+/**
+ * Extended project configuration exposed on the discovered workspace.
+ * Adds vis-specific metadata (layer, stack, language, owners) on top of
+ * the task-runner `ProjectConfiguration`.
+ */
+export interface VisProjectConfiguration extends ProjectConfiguration {
+    /** Primary language identifier. */
+    language?: string;
+    /** Project layer classification (matches moon's layer hierarchy). */
+    layer?: ProjectJson["layer"];
+    /** Owners entries declared in project.json. */
+    owners?: OwnersEntry[];
+    /** Human-readable metadata block. */
+    project?: ProjectJson["project"];
+    /** Project stack classification. */
+    stack?: ProjectJson["stack"];
+    /** Raw targets with vis-specific options retained. */
+    targets?: Record<string, TargetConfiguration>;
+}
+/**
+ * Per-project options cache indexed by project name. Used by the run
+ * command to read vis-specific target options without reparsing.
+ */
+export type ProjectOptionsIndex = Map<string, Record<string, VisTargetConfiguration>>;
+/**
+ * Parsed `package.json` files from the discovery pass, keyed by
+ * project name. {@link buildProjectGraph} consumes this to avoid
+ * re-parsing every `package.json` just to extract dependency info.
+ */
+export type PackageJsonIndex = Map<string, PackageJson>;
 /**
  * Discovers all projects in the workspace and builds a WorkspaceConfiguration.
  */
 declare const discoverWorkspace: (workspaceRoot: string, config?: VisConfig) => {
     config: VisConfig;
+    packageJsons: PackageJsonIndex;
+    projectOptions: ProjectOptionsIndex;
     workspace: WorkspaceConfiguration;
 };
 /**
  * Builds the project dependency graph from package.json dependencies.
+ *
+ * If `packageJsons` is provided (e.g. from {@link discoverWorkspace}),
+ * each project's `package.json` is reused from memory instead of
+ * re-read + re-parsed off disk — on a 40-project monorepo that's 40
+ * fewer reads per `vis run`.
  */
-declare const buildProjectGraph: (workspaceRoot: string, workspace: WorkspaceConfiguration) => ProjectGraph;
+declare const buildProjectGraph: (workspaceRoot: string, workspace: WorkspaceConfiguration, packageJsons?: PackageJsonIndex) => ProjectGraph;
 export type { PackageJson, VisConfig };
-export { buildProjectGraph, discoverWorkspace, readPnpmWorkspacePatterns, resolveWorkspacePatterns };
-export { type Configuration as StagedConfig } from "lint-staged";
+export { buildProjectGraph, collectTargetDefaults, discoverWorkspace, readPnpmWorkspacePatterns, resolveWorkspacePatterns, scopeMatches, validateWorkspacesField, };
+export { type StagedConfig } from "./staged/index.d.ts";