@async/pipeline 0.2.4 → 0.4.0

package/dist/internal/core/index.js

@@ -1,10 +1,14 @@
 import { assertCacheStore, defaultPipelineCache, defineCache, isCacheDirective, mergeWithDefaultCacheStores, parseCacheRef } from "./cache.js";
+import { assertSupportedDeclaration, brandDeclaration, hasDeclarationKind, readDeclaration } from "./declaration.js";
 import { pipelineError } from "./errors.js";
 export * from "./cache.js";
+export * from "./declaration.js";
 export * from "./errors.js";
+export const DEFAULT_PIPELINE_CONFIG_FILES = ["pipeline.ts", "pipeline.js", "pipeline.mjs", "pipeline.mts"];
+const SOURCE_PIPELINE_DEFAULTED = Symbol.for("@async/pipeline.source.pipeline.defaulted");
 export function sh(first, ...values) {
     if (typeof first === "function") {
-        return { kind: "deferred-shell", command: first };
+        return brandDeclaration({ kind: "deferred-shell", command: first }, "deferred-shell");
     }
     let command = "";
     for (let index = 0; index < first.length; index += 1) {
@@ -13,9 +17,11 @@ export function sh(first, ...values) {
             command += String(values[index]);
         }
     }
-    return { kind: "shell", command };
+    return brandDeclaration({ kind: "shell", command }, "shell");
 }
 const AGENT_STEP_FIELDS = new Set(["use", "prompt", "model", "stdoutTo"]);
+const DECLARED_AGENT_STEP_FIELDS = new Set(["kind", ...AGENT_STEP_FIELDS]);
+const SHELL_STEP_FIELDS = new Set(["kind", "command"]);
 export function agent(options) {
     rejectUnknownFields(AGENT_STEP_FIELDS, options, "agent() step");
     const use = options.use;
@@ -33,7 +39,7 @@ export function agent(options) {
             throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", 'agent() "stdoutTo" must be a relative path inside the task\'s working directory; absolute paths and ".." segments are rejected.');
         }
     }
-    const step = { kind: "agent", use, prompt: options.prompt };
+    const step = brandDeclaration({ kind: "agent", use, prompt: options.prompt }, "agent");
     if (options.model !== undefined)
         step.model = options.model;
     if (options.stdoutTo !== undefined)
@@ -50,138 +56,159 @@ export function task(definition, run) {
     if (definition.run !== undefined && run !== undefined) {
         throw pipelineError("ASYNC_PIPELINE_TASK_ARGUMENT_CONFLICT", "Do not pass a second task argument when config.run is defined.");
     }
-    return run === undefined ? definition : { ...definition, run };
+    return brandDeclaration(run === undefined ? definition : { ...definition, run }, "task");
 }
 export function job(definition) {
-    return definition;
+    return brandDeclaration(definition, "job");
 }
 function envVar(name, valuesOrOptions, options = {}) {
     if (!valuesOrOptions)
-        return { kind: "async-pipeline.env.var", name };
+        return brandDeclaration({ kind: "async-pipeline.env.var", name }, "env.var");
     if (isDefaultOnlyEnvOptions(valuesOrOptions) && Object.keys(valuesOrOptions).length === 1) {
-        return { kind: "async-pipeline.env.var", name, default: valuesOrOptions.default };
+        return brandDeclaration({ kind: "async-pipeline.env.var", name, default: valuesOrOptions.default }, "env.var");
     }
-    return {
+    return brandDeclaration({
         kind: "async-pipeline.env.var",
         name,
         values: { ...valuesOrOptions },
         default: options.default
-    };
+    }, "env.var");
 }
 export const env = {
     secret(name) {
-        return { kind: "async-pipeline.env.secret", name };
+        return brandDeclaration({ kind: "async-pipeline.env.secret", name }, "env.secret");
     },
     var: envVar
 };
 export const sandbox = {
     host() {
-        return { kind: "host" };
+        return brandDeclaration({ kind: "host" }, "sandbox.host");
     },
     lima(options = {}) {
-        return { kind: "lima", vm: options.vm };
+        return brandDeclaration({ kind: "lima", vm: options.vm }, "sandbox.lima");
     },
     docker(options) {
-        return {
+        return brandDeclaration({
             kind: "docker",
             image: options.image,
             workdir: options.workdir,
             volumes: options.volumes ? options.volumes.map((volume) => ({ ...volume })) : undefined
-        };
+        }, "sandbox.docker");
     },
     container(options) {
-        return {
+        return brandDeclaration({
             kind: "container",
             image: options.image,
             workdir: options.workdir,
             volumes: options.volumes ? options.volumes.map((volume) => ({ ...volume })) : undefined
-        };
+        }, "sandbox.container");
     }
 };
 export const execution = {
     local(options = {}) {
-        return {
+        return brandDeclaration({
             kind: "local",
             sandbox: options.sandbox,
             provider: options.provider
-        };
+        }, "execution.local");
     },
     github(options) {
-        return {
+        return brandDeclaration({
             kind: "github",
             sandbox: options.sandbox,
             provider: options.provider,
             runsOn: options.runsOn ? cloneRunsOnEntry(options.runsOn) : undefined,
             runsOnMatrix: options.runsOnMatrix ? options.runsOnMatrix.map(cloneRunsOnEntry) : undefined
-        };
+        }, "execution.github");
     }
 };
 export const command = {
     policy(options = {}) {
-        return {
+        return brandDeclaration({
             rules: options.rules ? options.rules.map(cloneCommandRule) : [],
             fallback: options.fallback ? cloneCommandAction(options.fallback) : undefined,
             record: options.record,
             output: options.output ? { ...options.output } : undefined,
             shims: options.shims ? [...options.shims] : undefined
-        };
+        }, "command.policy");
     },
     rule(options) {
-        return cloneCommandRule(options);
+        return brandDeclaration(cloneCommandRule(options), "command.rule");
     },
     allow(options = {}) {
-        return { kind: "async-pipeline.command.allow", output: options.output ? { ...options.output } : undefined };
+        return brandDeclaration({ kind: "async-pipeline.command.allow", output: options.output ? { ...options.output } : undefined }, "command.allow");
     },
     deny(options = {}) {
-        return { kind: "async-pipeline.command.deny", message: options.message, output: options.output ? { ...options.output } : undefined };
+        return brandDeclaration({ kind: "async-pipeline.command.deny", message: options.message, output: options.output ? { ...options.output } : undefined }, "command.deny");
     },
     mock(options = {}) {
-        return {
+        return brandDeclaration({
             kind: "async-pipeline.command.mock",
             code: options.code,
             stdout: options.stdout,
             stderr: options.stderr,
             output: options.output ? { ...options.output } : undefined
-        };
+        }, "command.mock");
     },
     requireApproval(options = {}) {
-        return { kind: "async-pipeline.command.requireApproval", message: options.message, output: options.output ? { ...options.output } : undefined };
+        return brandDeclaration({ kind: "async-pipeline.command.requireApproval", message: options.message, output: options.output ? { ...options.output } : undefined }, "command.requireApproval");
     },
     requireEnvironment(options) {
-        return { kind: "async-pipeline.command.requireEnvironment", name: options.name, output: options.output ? { ...options.output } : undefined };
+        return brandDeclaration({ kind: "async-pipeline.command.requireEnvironment", name: options.name, output: options.output ? { ...options.output } : undefined }, "command.requireEnvironment");
     }
 };
 export const trigger = {
     manual() {
-        return { type: "manual" };
+        return brandDeclaration({ type: "manual" }, "trigger.manual");
     },
     github(options) {
-        return {
+        return brandDeclaration({
             type: "github",
             events: [...options.events],
             branches: options.branches ? [...options.branches] : undefined,
             paths: options.paths ? [...options.paths] : undefined,
             tags: options.tags ? [...options.tags] : undefined
-        };
+        }, "trigger.github");
     },
     cron(cron, options = {}) {
-        return { type: "schedule", cron, timezone: options.timezone };
+        return brandDeclaration({ type: "schedule", cron, timezone: options.timezone }, "trigger.cron");
     },
     schedule(cron) {
-        return { type: "schedule", cron };
+        return brandDeclaration({ type: "schedule", cron }, "trigger.schedule");
     }
 };
 export function dependsOn(...taskIds) {
-    return { kind: "async-pipeline.directive.dependsOn", taskIds };
+    return brandDeclaration({ kind: "async-pipeline.directive.dependsOn", taskIds }, "directive.dependsOn");
 }
 export const source = {
     git(definition) {
-        return { ...definition, type: "git" };
+        return brandDeclaration({ ...definition, type: "git" }, "source.git");
     },
     path(definition) {
-        return { ...definition, type: "path" };
+        return brandDeclaration({ ...definition, type: "path" }, "source.path");
     }
 };
+export function tasks(definitions) {
+    return brandDeclaration(definitions, "section.tasks");
+}
+export function jobs(definitions) {
+    return brandDeclaration(definitions, "section.jobs");
+}
+export function triggers(definitions) {
+    return brandDeclaration(definitions, "section.triggers");
+}
+export function sources(definitions) {
+    return brandDeclaration(definitions, "section.sources");
+}
+export function taskDefaults(definitions) {
+    return brandDeclaration(definitions, "section.taskDefaults");
+}
+export function agents(definitions) {
+    return brandDeclaration(definitions, "section.agents");
+}
+export function sandboxes(definitions) {
+    return brandDeclaration(definitions, "section.sandboxes");
+}
 const PIPELINE_FIELDS = new Set(["name", "env", "commands", "agents", "sandboxes", "execution", "cache", "namedInputs", "taskDefaults", "triggers", "sync", "sources", "tasks", "jobs"]);
 const AGENT_PROFILE_FIELDS = new Set(["command", "model"]);
 const TASK_FIELDS = new Set(["description", "dependsOn", "inputs", "outputs", "cache", "retry", "timeout", "requires", "run", "steps"]);
@@ -190,6 +217,15 @@ const EXECUTION_PROFILE_FIELDS = new Set(["kind", "sandbox", "provider", "runsOn
 const GITHUB_JOB_FIELDS = new Set(["environment", "permissions", "runsOn", "runsOnMatrix"]);
 const GITHUB_PERMISSION_FIELDS = new Set(["contents", "idToken", "issues", "packages", "pullRequests"]);
 const CONTAINER_PROVIDERS = new Set(["auto", "docker", "apple-container", "lima"]);
+const SECTION_KINDS = {
+    agents: "section.agents",
+    sandboxes: "section.sandboxes",
+    taskDefaults: "section.taskDefaults",
+    triggers: "section.triggers",
+    sources: "section.sources",
+    tasks: "section.tasks",
+    jobs: "section.jobs"
+};
 function rejectUnknownFields(known, value, where) {
     for (const key of Object.keys(value)) {
         if (!known.has(key)) {
@@ -215,9 +251,6 @@ function validateDefinitionShape(definition) {
             throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", `Agent profile "${id}" requires "model": a non-empty string or env.var(...). The model is the profile's cache identity; the command is deliberately not.`);
         }
     }
-    for (const [id, taskDefinition] of Object.entries(definition.tasks ?? {})) {
-        rejectUnknownFields(TASK_FIELDS, taskDefinition, `Task "${id}"`);
-    }
     for (const [id, defaults] of Object.entries(definition.taskDefaults ?? {})) {
         rejectUnknownFields(TASK_FIELDS, defaults, `taskDefaults["${id}"]`);
     }
@@ -243,10 +276,112 @@ function validateDefinitionShape(definition) {
         }
     }
 }
+function normalizePipelineSections(definition) {
+    return {
+        ...definition,
+        agents: normalizeSection("agents", definition.agents),
+        sandboxes: normalizeSection("sandboxes", definition.sandboxes),
+        taskDefaults: normalizeSection("taskDefaults", definition.taskDefaults),
+        triggers: normalizeSection("triggers", definition.triggers),
+        sources: normalizeSection("sources", definition.sources),
+        tasks: normalizeSection("tasks", definition.tasks),
+        jobs: normalizeSection("jobs", definition.jobs)
+    };
+}
+function normalizeSection(key, value) {
+    if (value === undefined)
+        return value;
+    if (!isObjectRecord(value)) {
+        throw pipelineError("ASYNC_PIPELINE_SECTION_INVALID", `Pipeline section "${key}" must be an object.`);
+    }
+    const expectedKind = SECTION_KINDS[key];
+    const metadata = assertSupportedDeclaration(value);
+    if (metadata) {
+        if (metadata.kind !== expectedKind) {
+            throw pipelineError("ASYNC_PIPELINE_SECTION_KIND_MISMATCH", `Pipeline section "${key}" expected declaration kind "${expectedKind}", received "${metadata.kind}".`);
+        }
+        return value;
+    }
+    return brandDeclaration(value, expectedKind);
+}
+function flattenTaskDefinitions(definitions) {
+    const tasks = [];
+    const seen = new Set();
+    function visit(node, path) {
+        for (const [key, value] of Object.entries(node)) {
+            validateTaskTreeKey(key, path);
+            if (!isObjectRecord(value)) {
+                throw pipelineError("ASYNC_PIPELINE_TASK_TREE_INVALID", `Task tree entry "${[...path, key].join(".")}" must be an object.`);
+            }
+            const isTask = isTaskDefinitionNode(value, path);
+            if (isTask) {
+                const id = taskTreeId(path, key);
+                validateLocalTaskId(id);
+                if (seen.has(id)) {
+                    throw pipelineError("ASYNC_PIPELINE_TASK_ID_COLLISION", `Task group entry "${[...path, key].join(".")}" normalizes to duplicate task id "${id}".`);
+                }
+                seen.add(id);
+                rejectUnknownFields(TASK_FIELDS, value, `Task "${id}"`);
+                tasks.push({ id, definition: value, groupPath: path });
+                continue;
+            }
+            if (key.includes(".")) {
+                throw pipelineError("ASYNC_PIPELINE_TASK_GROUP_INVALID_KEY", `Task group key "${key}" cannot contain ".". Use nested objects instead.`);
+            }
+            visit(value, [...path, key]);
+        }
+    }
+    visit(definitions, []);
+    return tasks;
+}
+function validateTaskTreeKey(key, path) {
+    if (!key.trim()) {
+        throw pipelineError("ASYNC_PIPELINE_TASK_GROUP_INVALID_KEY", "Task group key cannot be empty.");
+    }
+    if (key.includes(":")) {
+        throw pipelineError("ASYNC_PIPELINE_TASK_GROUP_INVALID_KEY", `Task group key "${key}" cannot contain ":". Use source namespaces through dependsOn instead.`);
+    }
+    if (path.length > 0 && key.includes(".")) {
+        throw pipelineError("ASYNC_PIPELINE_TASK_GROUP_INVALID_KEY", `Nested task group key "${key}" cannot contain ".". Use nested objects instead.`);
+    }
+}
+function taskTreeId(path, key) {
+    const segments = path.length > 0 && (key === "default" || key === "index") ? path : [...path, key];
+    return segments.join(".");
+}
+function isTaskDefinitionNode(value, path) {
+    const metadata = assertSupportedDeclaration(value);
+    if (metadata?.kind === "task")
+        return true;
+    if (metadata?.kind.startsWith("section."))
+        return false;
+    if (metadata)
+        return false;
+    if (Object.keys(value).some((key) => TASK_FIELDS.has(key)))
+        return true;
+    return path.length === 0 && Object.keys(value).length === 0;
+}
+function resolveTaskDependencies(taskId, groupPath, dependencies, knownTaskIds) {
+    return dependencies.map((dependency) => resolveTaskDependency(taskId, groupPath, dependency, knownTaskIds));
+}
+function resolveTaskDependency(taskId, groupPath, dependency, knownTaskIds) {
+    if (isNamespacedTaskRef(dependency) || groupPath.length === 0)
+        return dependency;
+    const groupCandidate = [...groupPath, dependency].join(".");
+    const groupMatch = knownTaskIds.has(groupCandidate);
+    const rootMatch = knownTaskIds.has(dependency);
+    if (groupMatch && rootMatch && groupCandidate !== dependency) {
+        throw pipelineError("ASYNC_PIPELINE_TASK_DEPENDENCY_AMBIGUOUS", `Task "${taskId}" depends on ambiguous local task "${dependency}". Use "${groupCandidate}" or "${dependency}" explicitly.`);
+    }
+    if (groupMatch)
+        return groupCandidate;
+    return dependency;
+}
 export function definePipeline(definition) {
     return normalizePipeline(definition);
 }
 export function normalizePipeline(definition) {
+    definition = normalizePipelineSections(definition);
     validateDefinitionShape(definition);
     const namedInputs = definition.namedInputs ?? {};
     const cacheRegistry = normalizeCacheRegistry(definition.cache);
@@ -256,16 +391,18 @@ export function normalizePipeline(definition) {
         sources[id] = normalizeSource(id, sourceDefinition);
     }
     const tasks = {};
-    for (const [id, taskDefinition] of Object.entries(definition.tasks)) {
+    const flattenedTaskDefinitions = flattenTaskDefinitions(definition.tasks);
+    const knownTaskIds = new Set(flattenedTaskDefinitions.map((entry) => entry.id));
+    for (const { id, definition: taskDefinition, groupPath } of flattenedTaskDefinitions) {
         validateLocalTaskId(id);
         const defaults = definition.taskDefaults?.[id] ?? definition.taskDefaults?.[taskName(id)] ?? {};
         const merged = { ...defaults, ...taskDefinition };
         const runItems = merged.steps ? [...merged.steps] : runItemsFromDefinition(merged.run);
         const { steps, cacheDirectives, dependsOnDirectives } = partitionRunItems(runItems);
-        const liftedDependsOn = uniqueTaskIds([
+        const liftedDependsOn = resolveTaskDependencies(id, groupPath, uniqueTaskIds([
             ...(merged.dependsOn ?? []),
             ...dependsOnDirectives.flatMap((directive) => directive.taskIds)
-        ]);
+        ]), knownTaskIds);
         const cache = normalizeCache(merged.cache ?? cacheDirectives[0], cacheRegistry);
         const retry = normalizeRetry(merged.retry);
         const timeoutMs = normalizeTimeout(merged.timeout);
@@ -311,6 +448,12 @@ export function normalizePipeline(definition) {
 function isDefaultOnlyEnvOptions(value) {
     return typeof value.default === "string";
 }
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEnvVarRef(value) {
+    return isObjectRecord(value) && value.kind === "async-pipeline.env.var";
+}
 function normalizeAgents(definitions = {}) {
     const normalized = {};
     for (const [id, profile] of Object.entries(definitions)) {
@@ -655,21 +798,31 @@ function collectRequiredTasks(pipeline, targets) {
 }
 function normalizeSource(id, sourceDefinition) {
     const prepare = [...(sourceDefinition.prepare ?? [])];
-    const pipeline = sourceDefinition.pipeline ?? "pipeline.ts";
-    if (sourceDefinition.type === "git") {
-        return {
+    const pipeline = sourceDefinition.pipeline ?? DEFAULT_PIPELINE_CONFIG_FILES[0];
+    const defaulted = !sourceDefinition.pipeline;
+    const normalized = sourceDefinition.type === "git"
+        ? {
+            ...sourceDefinition,
+            id,
+            pipeline,
+            prepare
+        }
+        : {
             ...sourceDefinition,
             id,
             pipeline,
             prepare
         };
+    if (defaulted) {
+        Object.defineProperty(normalized, SOURCE_PIPELINE_DEFAULTED, {
+            value: true,
+            enumerable: false
+        });
     }
-    return {
-        ...sourceDefinition,
-        id,
-        pipeline,
-        prepare
-    };
+    return normalized;
+}
+export function sourceUsesDefaultPipelineConfig(sourceDefinition) {
+    return sourceDefinition[SOURCE_PIPELINE_DEFAULTED] === true;
 }
 function validateComposedPipeline(pipeline, loadedSources) {
     for (const taskDefinition of Object.values(pipeline.tasks)) {
@@ -908,7 +1061,8 @@ function partitionRunItems(items) {
     const steps = [];
     const cacheDirectives = [];
     const dependsOnDirectives = [];
-    for (const item of items) {
+    for (const rawItem of items) {
+        const item = normalizeDeclaredRunItem(rawItem);
         if (isCacheDirective(item)) {
             cacheDirectives.push(item);
             continue;
@@ -924,10 +1078,49 @@ function partitionRunItems(items) {
     }
     return { steps, cacheDirectives, dependsOnDirectives };
 }
+function normalizeDeclaredRunItem(item) {
+    const metadata = assertSupportedDeclaration(item);
+    if (!metadata || !isObjectRecord(item))
+        return item;
+    if (metadata.kind === "shell") {
+        rejectUnknownFields(SHELL_STEP_FIELDS, item, "shell declaration");
+        const command = item.command;
+        if (typeof command !== "string") {
+            throw pipelineError("ASYNC_PIPELINE_DECLARATION_INVALID", "Shell declaration requires a string command.");
+        }
+        return brandDeclaration({ kind: "shell", command }, "shell");
+    }
+    if (metadata.kind === "deferred-shell") {
+        rejectUnknownFields(SHELL_STEP_FIELDS, item, "deferred shell declaration");
+        const command = item.command;
+        if (typeof command !== "function") {
+            throw pipelineError("ASYNC_PIPELINE_DECLARATION_INVALID", "Deferred shell declaration requires a command function.");
+        }
+        return brandDeclaration({ kind: "deferred-shell", command: command }, "deferred-shell");
+    }
+    if (metadata.kind === "agent") {
+        rejectUnknownFields(DECLARED_AGENT_STEP_FIELDS, item, "agent declaration");
+        const use = item.use;
+        const prompt = item.prompt;
+        if ((typeof use !== "string" && !isEnvVarRef(use)) || (typeof use === "string" && use.length === 0)) {
+            throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", 'agent declaration requires "use": a non-empty profile id or env.var(...).');
+        }
+        if (typeof prompt !== "string" || prompt.length === 0) {
+            throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", 'agent declaration requires a non-empty "prompt" string.');
+        }
+        const step = brandDeclaration({ kind: "agent", use: use, prompt }, "agent");
+        if (item.model !== undefined)
+            step.model = item.model;
+        if (item.stdoutTo !== undefined)
+            step.stdoutTo = item.stdoutTo;
+        return step;
+    }
+    return item;
+}
 function isDependsOnDirective(value) {
     return Boolean(value)
         && typeof value === "object"
-        && value.kind === "async-pipeline.directive.dependsOn";
+        && (value.kind === "async-pipeline.directive.dependsOn" || hasDeclarationKind(value, "directive.dependsOn"));
 }
 function uniqueTaskIds(taskIds) {
     return [...new Set(taskIds)];