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

package/dist/commands/migrate/shared.d.ts

@@ -0,0 +1,29 @@
+import type { MigrateLogger, MigrationReport } from "./types.d.ts";
+/**
+ * Serialises a config object to a pretty-printed TypeScript string with
+ * unquoted keys (idiomatic TS style).
+ * @param obj The configuration object to serialise.
+ * @returns A JSON string with keys unquoted for TS readability.
+ */
+export declare const serializeConfigObject: (obj: Record<string, unknown>) => string;
+/**
+ * Writes (or previews) a rendered `vis.config.ts`. Guards against
+ * overwriting an existing file and logs the outcome.
+ * @param workspaceRoot Absolute workspace root path.
+ * @param rendered The full file content to write.
+ * @param options Migration options (`dryRun` controls preview mode).
+ * @param logger Logger for user feedback.
+ * @param report Migration report to append warnings to.
+ * @returns `true` if written (or previewed in dry-run), `false` if skipped.
+ */
+export declare const writeVisConfig: (workspaceRoot: string, rendered: string, options: {
+    dryRun?: boolean;
+}, logger: MigrateLogger, report: MigrationReport) => boolean;
+/**
+ * Reads and parses a JSON config file from the workspace root.
+ * @param workspaceRoot Absolute workspace root path.
+ * @param fileName File name relative to the workspace root.
+ * @returns The parsed object, or `undefined` if the file doesn't exist.
+ * @throws On JSON parse errors.
+ */
+export declare const readJsonConfig: <T>(workspaceRoot: string, fileName: string) => T | undefined;

package/dist/commands/migrate/turborepo.d.ts

@@ -0,0 +1,11 @@
+import type { MigrateLogger, MigrationReport } from "./types.d.ts";
+/**
+ * Translates a `turbo.json` into a `vis.config.ts`.
+ * @param workspaceRoot Absolute workspace root path.
+ * @param options Migration options.
+ * @param logger Logger for user feedback.
+ * @param report Migration report to append manual steps and warnings.
+ */
+export declare const migrateTurborepo: (workspaceRoot: string, options: {
+    dryRun?: boolean;
+}, logger: MigrateLogger, report: MigrationReport) => void;

package/dist/commands/migrate/types.d.ts

@@ -3,10 +3,16 @@ interface MigrateLogger {
     warn: (message: string) => void;
 }
 interface MigrationReport {
+    backupsCreated: string[];
     gitHooksConfigured: boolean;
     inlinedLintStagedConfigCount: number;
     manualSteps: string[];
     mergedStagedConfigCount: number;
+    perMigration: Record<string, {
+        removedConfigCount: number;
+        removedPackageCount: number;
+        rewrittenScriptCount: number;
+    }>;
     removedConfigCount: number;
     removedPackageCount: number;
     rewrittenScriptCount: number;
@@ -15,6 +21,7 @@ interface MigrationReport {
 declare const createMigrationReport: () => MigrationReport;
 declare const addMigrationWarning: (report: MigrationReport | undefined, warning: string) => void;
 declare const addManualStep: (report: MigrationReport | undefined, step: string) => void;
+declare const bumpPerMigration: (report: MigrationReport, migration: string, field: "removedConfigCount" | "removedPackageCount" | "rewrittenScriptCount", delta?: number) => void;
 type PackageManagerType = "bun" | "npm" | "pnpm" | "yarn";
 export type { MigrateLogger, MigrationReport, PackageManagerType };
-export { addManualStep, addMigrationWarning, createMigrationReport };
+export { addManualStep, addMigrationWarning, bumpPerMigration, createMigrationReport };

package/dist/commands/migrate/verify.d.ts

@@ -0,0 +1,12 @@
+import type { MigrateLogger } from "./types.d.ts";
+export interface VerificationIssue {
+    detail: string;
+    kind: "config" | "script" | "hook" | "devDep";
+    location: string;
+}
+/**
+ * Check that a prior `vis migrate gitleaks` / `secretlint` run was complete:
+ * no stray scripts, devDependencies, hooks, or configs referencing the old
+ * tools. Safe to run repeatedly — purely read-only.
+ */
+export declare const verifyMigration: (root: string, logger: MigrateLogger) => VerificationIssue[];

package/dist/commands/run.d.ts

@@ -1,3 +1,16 @@
 import type { Command } from "@visulima/cerebro";
+/**
+ * Shared counter for the global `--retry-budget` flag. Tasks consult
+ * `claim(requested)` at launch to grab up to `requested` retries; the
+ * budget is decremented conservatively by the claim (not by actual
+ * retries consumed) to keep the bound simple to reason about. Once
+ * the budget is exhausted, subsequent tasks run with no retries —
+ * surfacing flakiness instead of silently burning CI time.
+ */
+export interface RetryBudget {
+    claim: (requested: number) => number;
+    readonly remaining: number;
+}
+export declare const createRetryBudget: (limit: number) => RetryBudget;
 declare const run: Command;
 export default run;

package/dist/commands/sbom.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "@visulima/cerebro";
+/**
+ * `vis sbom` — CycloneDX 1.6 Software Bill of Materials generator.
+ *
+ * Mirrors `vis docker scaffold` in shape: accepts an optional `--focus`
+ * list, walks the workspace graph, and writes the result to disk
+ * (or stdout).
+ */
+declare const sbom: Command;
+export default sbom;

package/dist/commands/secrets.d.ts

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

package/dist/commands/staged.d.ts

@@ -1,3 +1,10 @@
 import type { Command } from "@visulima/cerebro";
+import type { RunOptions, StagedConfig } from "../index.d.ts";
+/**
+ * Translates the cerebro-parsed CLI options (kebab-case keys, string/boolean values)
+ * into a strongly-typed `RunOptions` object. Only the flags the user passed are
+ * forwarded — the rest fall through to `runStaged`'s own defaults.
+ */
+export declare const buildRunOptions: (raw: Record<string, unknown>, stagedConfig: StagedConfig | undefined) => RunOptions;
 declare const staged: Command;
 export default staged;

package/dist/commands/status.d.ts

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

package/dist/commands/sync.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from "@visulima/cerebro";
+/**
+ * `vis sync <kind>` performs workspace-wide synchronisations that
+ * cannot be derived from a task graph alone.
+ *
+ * Currently supported kinds:
+ *
+ *  - `codeowners`: aggregates `owners` entries from every project's
+ *    project.json into a single CODEOWNERS file at the repo root
+ *    (or `.github/CODEOWNERS` when the target flag is set).
+ *
+ * Additional kinds will land alongside their features (for example:
+ * `tsconfig-references`, `package-json` sort, `hooks`).
+ */
+declare const sync: Command;
+export default sync;

package/dist/commands/task-why.d.ts

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

package/dist/config.d.ts

@@ -1,5 +1,6 @@
+import type { VisPlugin } from "./hooks.d.ts";
 import type { VisConfig } from "./workspace.d.ts";
-/** Supported config file names, checked in order. */
+/** Supported config file names, checked in priority order. */
 declare const CONFIG_FILES: string[];
 /**
  * Secure-by-default security settings based on npm supply chain best practices.
@@ -16,6 +17,11 @@ declare const SECURITY_DEFAULTS: Required<Pick<NonNullable<VisConfig["security"]
 declare const applyDefaults: (config: VisConfig) => VisConfig;
 /**
  * Find the vis config file in a directory.
+ *
+ * Reads the directory listing once and intersects it with the known
+ * config filenames rather than `stat`-ing each candidate — one syscall
+ * instead of up to six. Priority order is preserved via
+ * `CONFIG_FILES` so `.ts` still wins over `.mjs` when both exist.
  * @param directory The directory to search in.
  * @returns The absolute path to the config file, or `undefined` if not found.
  */
@@ -64,4 +70,13 @@ declare const loadVisConfig: (workspaceRoot: string) => Promise<VisConfig>;
  * ```
  */
 declare const defineConfig: (config: VisConfig) => VisConfig;
-export { applyDefaults, CONFIG_FILES, defineConfig, findVisConfigFile, loadVisConfig, SECURITY_DEFAULTS };
+/**
+ * Type-safe helper for defining a vis plugin. Pure identity — exists
+ * only so plugin authors get inference from the `VisPlugin` contract
+ * without needing a `satisfies` annotation.
+ */
+declare const definePlugin: (plugin: VisPlugin) => VisPlugin;
+export type { VisHooks, VisPlugin } from "./hooks.d.ts";
+export type { OtelPluginOptions, OtelSpan, OtelTracer } from "./plugins/otel.d.ts";
+export { otelPlugin } from "./plugins/otel.d.ts";
+export { applyDefaults, CONFIG_FILES, defineConfig, definePlugin, findVisConfigFile, loadVisConfig, SECURITY_DEFAULTS };

package/dist/config.js

@@ -1 +1 @@
-var m=Object.defineProperty;var u=(e,t)=>m(e,"name",{value:t,configurable:!0});import{createRequire as C}from"node:module";import{findCacheDirSync as w}from"@visulima/find-cache-dir";import{ensureDirSync as p,isAccessibleSync as D,readJsonSync as x,writeJsonSync as E}from"@visulima/fs";import{join as o,dirname as I}from"@visulima/path";import{createJiti as P}from"jiti";const v=C(import.meta.url),r=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,d=u(e=>{if(typeof r<"u"&&r.versions&&r.versions.node){const[t,s]=r.versions.node.split(".").map(Number);if(t>22||t===22&&s>=3||t===20&&s>=16)return r.getBuiltinModule(e)}return v(e)},"__cjs_getBuiltinModule"),{createHash:_}=d("node:crypto"),{existsSync:y,readFileSync:S,copyFileSync:j,unlinkSync:b}=d("node:fs"),{tmpdir:F}=d("node:os");var T=Object.defineProperty,n=u((e,t)=>T(e,"name",{value:t,configurable:!0}),"e");const A=["vis.config.ts","vis.config.mts","vis.config.cts","vis.config.js","vis.config.mjs","vis.config.cjs"],J={blockExoticSubdeps:!0,strictDepBuilds:!0,trustPolicy:"no-downgrade",trustPolicyIgnoreAfter:43200},V=n(e=>({...J,...e}),"mergeSecurityDefaults"),l=n(e=>({...e,security:V(e.security),update:{security:!0,target:"minor",...e.update}}),"applyDefaults"),k=n(e=>{for(const t of A){const s=o(e,t);if(y(s))return s}},"findVisConfigFile"),q=n(e=>_("sha256").update(S(e)).digest("hex"),"hashFileContents"),B=n(e=>{const t=o(e,"node_modules");if(y(t)){const i=o(t,".cache","vis");return p(i),o(i,"vis-config-cache.json")}const s=w("vis",{create:!0,cwd:e});return s?o(s,"vis-config-cache.json"):void 0},"getConfigCachePath"),N=n((e,t)=>{if(D(e))try{const s=x(e);if(s.hash===t)return s.config}catch{}},"readConfigCache"),O=n((e,t,s)=>{try{p(I(e)),E(e,{config:s,hash:t})}catch{}},"writeConfigCache"),H=n(async e=>{const t=k(e);if(!t)return l({});const s=q(t),i=B(e);if(i){const g=N(i,s);if(g)return g}const h=t.slice(t.lastIndexOf(".")),a=o(F(),`vis-config-${s}${h}`);j(t,a);let c;try{c=await P(e,{fsCache:!1,moduleCache:!1}).import(a,{default:!0,try:!0})??{}}finally{try{b(a)}catch{}}let f;return f=l(typeof c=="function"?await c()??{}:c),i&&O(i,s,f),f},"loadVisConfig"),Y=n(e=>l(e),"defineConfig");export{A as CONFIG_FILES,J as SECURITY_DEFAULTS,l as applyDefaults,Y as defineConfig,k as findVisConfigFile,H as loadVisConfig};
+var b=Object.defineProperty;var l=(e,t)=>b(e,"name",{value:t,configurable:!0});import{createRequire as k}from"node:module";import{findCacheDirSync as D}from"@visulima/find-cache-dir";import{isAccessibleSync as y,ensureDirSync as m,readJsonSync as T,writeJsonSync as x}from"@visulima/fs";import{join as f,dirname as E}from"@visulima/path";import{createJiti as I}from"jiti";const _=k(import.meta.url),d=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,v=l(e=>{if(typeof d<"u"&&d.versions&&d.versions.node){const[t,n]=d.versions.node.split(".").map(Number);if(t>22||t===22&&n>=3||t===20&&n>=16)return d.getBuiltinModule(e)}return _(e)},"__cjs_getBuiltinModule"),{createHash:C}=v("node:crypto"),{readdirSync:j,copyFileSync:w,unlinkSync:P,readFileSync:A}=v("node:fs"),{tmpdir:F}=v("node:os");var O=Object.defineProperty,u=l((e,t)=>O(e,"name",{value:t,configurable:!0}),"a");const $=1,g=2,X=u(e=>{const{renameSpan:t,tracer:n}=e;let s;const a=new Map;return z({hooks:{"run:after":u(r=>{if(!s)return;const i=[...r.values()].filter(o=>o.status==="failure").length;s.setAttribute?.("vis.run.tasks_total",r.size),s.setAttribute?.("vis.run.tasks_failed",i),i>0?s.setStatus?.({code:g,message:`${String(i)} task(s) failed`}):s.setStatus?.({code:$}),s.end(),s=void 0;for(const o of a.values())o.end();a.clear()},"run:after"),"run:before":u(r=>{s&&(s.setStatus?.({code:g,message:"run:before fired while previous run was still active"}),s.end());for(const i of a.values())i.end();a.clear(),s=n.startSpan("vis.run",{attributes:{"vis.run.task_count":r.tasks.length,"vis.workspace_root":r.workspaceRoot}})},"run:before"),"task:after":u((r,i)=>{const o=a.get(r.id);o&&(o.setAttribute?.("vis.task.exit_code",i.code??0),o.setAttribute?.("vis.task.cache_status",i.status),o.end(),a.delete(r.id))},"task:after"),"task:before":u(r=>{const i=a.get(r.id);i&&(i.setStatus?.({code:g,message:"retried — superseded by new attempt"}),i.end());const o=n.startSpan(t?t(r):r.id,{attributes:{"vis.task.id":r.id,"vis.task.project":r.target.project,"vis.task.target":r.target.target}});a.set(r.id,o)},"task:before"),"task:failure":u((r,i)=>{const o=a.get(r.id);o&&o.setStatus?.({code:g,message:`Task failed with exit code ${String(i.code??-1)}`})},"task:failure")},name:"otel"})},"otelPlugin");var J=Object.defineProperty,c=l((e,t)=>J(e,"name",{value:t,configurable:!0}),"s");const S=["vis.config.ts","vis.config.mts","vis.config.cts","vis.config.js","vis.config.mjs","vis.config.cjs"],R=new Set(S),V={blockExoticSubdeps:!0,strictDepBuilds:!0,trustPolicy:"no-downgrade",trustPolicyIgnoreAfter:43200},q=c(e=>({...V,...e}),"mergeSecurityDefaults"),p=c(e=>({...e,security:q(e.security),update:{security:!0,target:"minor",...e.update}}),"applyDefaults"),B=c(e=>{let t;try{t=j(e)}catch{return}const n=new Set(t.filter(s=>R.has(s)));for(const s of S)if(n.has(s))return f(e,s)},"findVisConfigFile"),M=c(e=>C("sha256").update(A(e)).digest("hex"),"hashFileContents"),N=c(e=>{const t=f(e,"node_modules");if(y(t)){const s=f(t,".cache","vis");return m(s),f(s,"vis-config-cache.json")}const n=D("vis",{create:!0,cwd:e});return n?f(n,"vis-config-cache.json"):void 0},"getConfigCachePath"),L=c((e,t)=>{if(y(e))try{const n=T(e);if(n.hash===t)return n.config}catch{}},"readConfigCache"),U=c((e,t,n)=>{try{m(E(e)),x(e,{config:n,hash:t})}catch{}},"writeConfigCache"),Z=c(async e=>{const t=B(e);if(!t)return p({});const n=M(t),s=N(e);if(s){const h=L(s,n);if(h)return h}const a=t.slice(t.lastIndexOf(".")),r=f(F(),`vis-config-${n}${a}`);w(t,r);let i;try{i=await I(e,{fsCache:!1,moduleCache:!1}).import(r,{default:!0,try:!0})??{}}finally{try{P(r)}catch{}}let o;return o=p(typeof i=="function"?await i()??{}:i),s&&U(s,n,o),o},"loadVisConfig"),ee=c(e=>p(e),"defineConfig"),z=c(e=>e,"definePlugin");export{S as CONFIG_FILES,V as SECURITY_DEFAULTS,p as applyDefaults,ee as defineConfig,z as definePlugin,B as findVisConfigFile,Z as loadVisConfig,X as otelPlugin};

package/dist/docker.d.ts

@@ -0,0 +1,73 @@
+import type { ProjectGraph, WorkspaceConfiguration } from "@visulima/task-runner";
+/**
+ * Minimal Docker scaffold: copies the set of files Docker's layer
+ * cache benefits from keeping stable (manifests + lockfiles) so an
+ * image build can `COPY` them first and install dependencies before
+ * source code arrives.
+ *
+ * Computes the set of projects a focus project depends on and copies
+ * only their `package.json` + `project.json` + root manifests, not
+ * the whole source tree. Compare with moon's `moon docker scaffold`.
+ */
+/** Name of the manifest file written by scaffold and read by prune. */
+export declare const DOCKER_MANIFEST_FILENAME = "vis-docker-manifest.json";
+export interface ScaffoldOptions {
+    /** Project names to focus on — transitive deps are pulled in automatically. */
+    focus: string[];
+    /**
+     * Include the full source tree for the focus project(s). Used for the
+     * `sources` stage so the build can actually compile code after deps
+     * are installed.
+     */
+    includeSources?: boolean;
+    /** Output directory, typically `.vis/docker/workspace`. */
+    outDir: string;
+    /** Project graph used to compute the transitive dependency closure. */
+    projectGraph: ProjectGraph;
+    /** Workspace configuration with resolved project roots. */
+    workspace: WorkspaceConfiguration;
+    /** Workspace root on disk. */
+    workspaceRoot: string;
+}
+/**
+ * Computes the full set of projects that must exist in the Docker context
+ * to build a given focus set: the focus projects themselves plus every
+ * project reachable from them in the workspace dependency graph.
+ * @param focus Project names to focus on.
+ * @param projectGraph The workspace project graph.
+ * @returns A set containing every project in the transitive closure.
+ */
+export declare const resolveFocusProjects: (focus: string[], projectGraph: ProjectGraph) => Set<string>;
+/**
+ * Build a minimal Docker context at {@link ScaffoldOptions.outDir}.
+ *
+ * Creates two directories:
+ * - `&lt;outDir>/workspace/` — root manifests + per-project manifests for the
+ *   focus closure. `COPY` this BEFORE `pnpm install` for layer caching.
+ * - `&lt;outDir>/sources/` — full source trees for the focus projects (only
+ *   when {@link ScaffoldOptions.includeSources} is true).
+ * @param options Scaffold configuration.
+ * @returns The list of project names included in the scaffold.
+ */
+export declare const scaffoldDockerContext: (options: ScaffoldOptions) => {
+    projects: string[];
+};
+export interface PruneOptions {
+    /** Root of the scaffolded context (containing `vis-docker-manifest.json`). */
+    contextRoot: string;
+    workspace: WorkspaceConfiguration;
+    workspaceRoot: string;
+}
+/**
+ * Removes every workspace project that is not in the focus closure.
+ *
+ * Intended to run inside a Docker build stage after installing
+ * dependencies, so unfocused workspace symlinks are stripped from
+ * the final image.
+ * @param options Prune configuration.
+ * @returns The list of project root paths that were removed.
+ * @throws If no `vis-docker-manifest.json` exists at the context root.
+ */
+export declare const pruneDockerContext: (options: PruneOptions) => {
+    removed: string[];
+};

package/dist/flakiness.d.ts

@@ -0,0 +1,40 @@
+import type { LoadedRunSummary } from "./run-report.d.ts";
+/**
+ * Per-task flakiness statistics aggregated across multiple run summaries.
+ */
+export interface TaskFlakiness {
+    /** Number of runs where this task failed (exitCode !== 0). */
+    failures: number;
+    /** Flakiness rate: failures / totalRuns. */
+    flakinessRate: number;
+    /** Most recent failure time (ISO 8601), if any. */
+    lastFailure?: string;
+    project: string;
+    /** Number of runs where this task succeeded. */
+    successes: number;
+    target: string;
+    taskId: string;
+    /** Total number of times this task appeared in runs. */
+    totalRuns: number;
+}
+/**
+ * Reads all run summary files from `.task-runner/runs/` and computes
+ * per-task flakiness statistics.
+ *
+ * Pass `summaries` (from {@link loadRunSummaries}) when the caller
+ * already loaded the history — avoids re-reading every JSON off disk
+ * just to get the same data.
+ * @param workspaceRoot Absolute path to the workspace root.
+ * @param options Filtering options.
+ * @returns Flakiness stats sorted by rate (most flaky first).
+ */
+export declare const analyzeFlakiness: (workspaceRoot: string, options?: {
+    minRuns?: number;
+    since?: string;
+}, summaries?: LoadedRunSummary[]) => TaskFlakiness[];
+/**
+ * Formats flakiness stats as an ASCII table.
+ * @param stats Flakiness statistics to format.
+ * @returns Lines of formatted output (including header).
+ */
+export declare const formatFlakinessTable: (stats: TaskFlakiness[]) => string[];

package/dist/generate/discover.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Template discovery for `vis generate`.
+ *
+ * Discovery sources, in priority order:
+ *   1. Native templates in `<workspace>/.vis/templates/<name>.{ts,js,mjs}`.
+ *   2. Moon-format directories in `<workspace>/.vis/templates/<name>/`
+ *      (any directory with a `template.yml`).
+ *   3. Moon-format directories in `<workspace>/.moon/templates/<name>/`
+ *      (zero-config import for users mid-migration from moon).
+ *   4. Extra directories listed in `vis.config.ts` `generator.templates`.
+ *
+ * Native templates win over moon templates with the same name; a
+ * warning is printed at discovery time so the conflict is visible.
+ */
+import type { DiscoveredTemplate } from "./types.d.ts";
+interface DiscoverOptions {
+    /** Extra template directories from `vis.config.ts` `generator.templates`. */
+    extraDirectories?: string[];
+    /** Logger callback for conflict warnings. */
+    onWarning?: (message: string) => void;
+    /** Workspace root — `.vis/templates/` and `.moon/templates/` are resolved against this. */
+    workspaceRoot: string;
+}
+/**
+ * Discover templates across the workspace. Returns a deduplicated list
+ * with native sources winning over moon when names collide.
+ */
+export declare const discoverTemplates: (options: DiscoverOptions) => DiscoveredTemplate[];
+export {};

package/dist/generate/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Public surface for `vis generate` template authors.
+ *
+ * Native templates live at `<workspace>/.vis/templates/<name>.{ts,js,mjs}`
+ * and import `createTemplate` from this module.
+ * @example
+ * ```typescript
+ * import { createTemplate } from "@visulima/vis/generate";
+ *
+ * export default createTemplate({
+ *     about: { name: "package", description: "Scaffold a new package" },
+ *     options: {
+ *         name: { type: "string", required: true, prompt: "Package name?" },
+ *     },
+ *     async produce({ options }) {
+ *         return {
+ *             files: {
+ *                 [`packages/${options.name}/package.json`]: JSON.stringify({ name: options.name }, null, 2),
+ *                 [`packages/${options.name}/src/index.ts`]: "export {};\n",
+ *             },
+ *         };
+ *     },
+ * });
+ * ```
+ */
+import type { Template } from "./types.d.ts";
+/**
+ * Identity helper for type inference. Authors get autocomplete + checks
+ * without having to annotate the export.
+ */
+export declare const createTemplate: (template: Template) => Template;
+export type { ArrayVariable, BooleanVariable, BuiltinVars, Creation, CreationDirectory, CreationFile, DiscoveredTemplate, EnumVariable, FileMeta, NumberVariable, Options, Script, ScriptObject, StringVariable, Template, TemplateAbout, TemplateContext, Variable, VariableMap, VariableType, } from "./types.d.ts";

package/dist/generate/index.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var r=(e,a)=>t(e,"name",{value:a,configurable:!0});var c=Object.defineProperty,l=r((e,a)=>c(e,"name",{value:a,configurable:!0}),"a");const o=l(e=>e,"createTemplate");export{o as createTemplate};

package/dist/generate/loader.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Native template loader.
+ *
+ * Native templates live as `.ts`/`.js`/`.mjs` modules under
+ * `<workspace>/.vis/templates/<name>.<ext>` and export a `Template` as
+ * their default export. We use jiti so TypeScript and ESM/CJS
+ * interop both work without a separate build step.
+ */
+import type { Template } from "./types.d.ts";
+/**
+ * Load a native template module from disk and return its default export.
+ * The directory containing the file is used as jiti's working dir so
+ * relative imports inside the template resolve as the author expects.
+ */
+export declare const loadNativeTemplate: (path: string) => Promise<Template>;

package/dist/generate/moon-adapter/filename-interp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Filename interpolation for moon-format templates.
+ *
+ * Bracket syntax inside any path segment:
+ *   `[var]`            → value of `var` from the variable map
+ *   `[var | filter]`   → filter applied to the value
+ *   `[var | filter(arg)]` → filter with a string argument
+ *
+ * Suffixes `.tera` and `.twig` are stripped from the final segment
+ * (they exist only for editor syntax highlighting).
+ */
+/**
+ * Interpolate a single path segment or an entire path. Variables are
+ * looked up in `vars`; missing keys raise an error so typos surface
+ * during render rather than producing surprising filenames.
+ *
+ * `.tera` / `.twig` extensions are stripped from the result.
+ */
+export declare const interpolateFilename: (filename: string, vars: Record<string, unknown>) => string;
+/**
+ * Strip the trailing `.tera` / `.twig` marker from **every** path
+ * segment. moon strips them per segment (not just the final one) so a
+ * template at `src/.tera/file.ts.tera` renders to `src/file.ts`, not
+ * `src/.tera/file.ts`.
+ */
+export declare const stripTeraSuffix: (filename: string) => string;
+/**
+ * Strip the trailing `.raw` extension. moon adopters ship binary or
+ * Tera-conflicting files with `.raw` suffix; renderers must skip them
+ * but the suffix itself is removed on write.
+ */
+export declare const stripRawSuffix: (filename: string) => string;
+/**
+ * True when the file is a partial — matched by *either* a basename
+ * starting with `_` (moon's primary convention) or a path segment
+ * equal to `partials` (moon's "folder of partials" convention).
+ *
+ * The earlier substring match on `"partial"` swallowed any file whose
+ * name contained those letters (e.g. `PartialResult.ts`,
+ * `partially-applied.ts`), silently dropping them from the output.
+ */
+export declare const isPartialPath: (path: string) => boolean;

package/dist/generate/moon-adapter/filters.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Built-in filter functions used by the Tera-subset renderer and
+ * the filename interpolator. Names match moon's filter set.
+ *
+ * Case helpers come from `@visulima/string/case` (better Unicode and
+ * acronym handling than the bare `change-case` package; same package
+ * powers the rest of the visulima toolchain). Path filters use
+ * `@visulima/path` so behaviour matches the rest of vis.
+ */
+export type FilterFn = (value: unknown, ...args: unknown[]) => unknown;
+/**
+ * Map of filter name → function. Unknown filter names raise an error
+ * at render time so typos in templates don't silently no-op.
+ */
+export declare const FILTERS: Record<string, FilterFn>;
+export declare const isKnownFilter: (name: string) => boolean;
+/**
+ * Apply a filter by name with optional arguments. Throws when the
+ * filter name is unknown — callers should phrase the error with a
+ * file:line reference.
+ */
+export declare const applyFilter: (name: string, value: unknown, args?: unknown[]) => unknown;

package/dist/generate/moon-adapter/frontmatter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Per-file YAML frontmatter splitter for moon-format templates.
+ *
+ * Frontmatter is a YAML block delimited by `---` on its own line at
+ * the very top of a file. Recognised keys (moon parity):
+ *   - `to`: override the destination path (interpolation supported)
+ *   - `force`: overwrite without prompting (default false)
+ *   - `if`: include the file only when the condition is truthy
+ *   - `skip`: skip rendering entirely when truthy
+ *
+ * Frontmatter is parsed via `@visulima/fs` `readYaml`-compatible YAML
+ * dialect. The parser is exposed as a callback to keep this module
+ * dependency-free for unit tests.
+ */
+export interface Frontmatter {
+    /** Allow extra keys without losing them on round-trip. */
+    [key: string]: unknown;
+    /** Overwrite an existing file at the destination without prompting. */
+    force?: boolean;
+    /** Truthy expression / value gate — file is emitted only when truthy. */
+    if?: unknown;
+    /** Truthy expression / value gate — file is skipped when truthy. */
+    skip?: unknown;
+    /** Override destination path; supports `{{ var }}` interpolation. */
+    to?: string;
+}
+export interface SplitResult {
+    /** File body with the frontmatter block removed. */
+    body: string;
+    /** Parsed frontmatter, or `undefined` when the file has no `---` block. */
+    frontmatter?: Frontmatter;
+}
+/**
+ * Split the frontmatter block from the file body.
+ * @param source The file contents.
+ * @param parseYaml YAML parser callback; pass `(s) => parseYaml(s)` from
+ * `@visulima/fs/yaml` at the call site to avoid a runtime dep here.
+ */
+export declare const splitFrontmatter: (source: string, parseYaml: (yaml: string) => unknown) => SplitResult;

package/dist/generate/moon-adapter/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Moon-format template adapter.
+ *
+ * Loads a directory matching moon's template layout
+ * (`template.yml` + a tree of files / partials / assets) and synthesises
+ * a `Template` (the same shape native vis templates export).
+ *
+ * The adapter pre-reads every template file at load time and parses
+ * the AST once. Per-run the renderer evaluates the AST against the
+ * resolved options scope — no further disk I/O.
+ */
+import type { Template } from "../types.d.ts";
+/**
+ * Load a moon-format template directory into a `Template`.
+ * @param templateDir Absolute path to the directory containing `template.yml`.
+ * @param name Stable name used by `vis generate <name>` (used as a fallback
+ * when `template.yml` omits `title`).
+ */
+export declare const loadMoonTemplate: (templateDir: string, name: string) => Template;

package/dist/generate/moon-adapter/tera-subset.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tera-subset renderer for moon-format template content.
+ *
+ * Supported constructs (intersection of moon's most-used features):
+ *   - `{{ var }}` and `{{ var | filter }}` and `{{ var | filter(arg) }}`
+ *     with chained filters: `{{ var | snake_case | upper_case }}`
+ *   - `{% if expr %} ... {% else %} ... {% endif %}`
+ *     where `expr` is `var`, `not var`, `var == "lit"`, `var != "lit"`
+ *   - `{% for x in collection %} ... {% endfor %}`
+ *     where `collection` is a variable holding an array
+ *   - `{% include "name" %}` — pulls the rendered output of a partial
+ *
+ * Explicitly UNSUPPORTED, with a clear `file:line` error message:
+ *   - `{% set x = ... %}`
+ *   - `{% extends "..." %}`
+ *   - `{% block ... %}` / `{% endblock %}`
+ *   - `{% macro ... %}` / `{% endmacro %}`
+ *   - Custom whitespace control (`{%- -%}`)
+ *
+ * The parser is a single-pass tokenizer feeding a tree-walking
+ * evaluator. Errors carry the original 1-based line number for the
+ * source file, threaded through from the moon adapter via `filename`.
+ */
+type Node = {
+    type: "text";
+    value: string;
+} | {
+    expression: string;
+    line: number;
+    type: "expr";
+} | {
+    alternate?: Node[];
+    condition: string;
+    consequent: Node[];
+    line: number;
+    type: "if";
+} | {
+    binding: string;
+    body: Node[];
+    collection: string;
+    line: number;
+    type: "for";
+} | {
+    line: number;
+    name: string;
+    type: "include";
+};
+/**
+ * Recursive-descent condition evaluator with precedence:
+ *   `or` (lowest) → `and` → `not` → comparison (`==` / `!=`) → primary.
+ * Parentheses override precedence.
+ *
+ * Exported so the moon adapter can reuse the same grammar on
+ * frontmatter `if:` / `skip:` strings.
+ */
+export declare const evaluateConditionExpression: (condition: string, scope: Record<string, unknown>, filename: string, line: number) => boolean;
+interface RenderOptions {
+    /** Source filename — used in error messages. */
+    filename: string;
+    /**
+     * Internal: set of partial names currently on the include stack.
+     * Used to detect cycles — if an include re-enters a partial that's
+     * already resolving, we throw instead of stack-overflowing.
+     */
+    includeStack?: Set<string>;
+    /** Map of partial name → already-resolved AST. */
+    partials?: Map<string, Node[]>;
+    /** Variable scope (built-in vars merged with user options). */
+    scope: Record<string, unknown>;
+}
+/**
+ * Parse a template source into an AST. Used by the moon adapter to
+ * pre-parse partials once and reuse them across files.
+ */
+export declare const parseTemplate: (source: string, filename: string) => Node[];
+/**
+ * Render a parsed AST with the given scope.
+ */
+export declare const renderAst: (nodes: Node[], options: RenderOptions) => string;
+/**
+ * Convenience: parse + render in one call. Prefer `parseTemplate` +
+ * `renderAst` when a template is rendered repeatedly (e.g. in loops).
+ */
+export declare const renderTemplate: (source: string, options: RenderOptions) => string;
+export type { Node };

package/dist/generate/moon-adapter/util.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Split on `,` at the top level — outside quotes and parentheses.
+ *
+ * Used by both `parseFilterCall` in `filename-interp.ts` and
+ * `tera-subset.ts` so `path_join("a,b", "c")` and
+ * `[var | path_join("a,b", "c")]` produce the same two args.
+ */
+export declare const splitCommaOutsideQuotes: (input: string) => string[];
+/**
+ * Strip matching single- or double-quote wrappers. Returns `undefined`
+ * when the input isn't a quoted literal so callers can fall through to
+ * variable lookup or number parsing.
+ */
+export declare const stripQuotes: (input: string) => string | undefined;