@synergenius/flow-weaver 0.17.0 → 0.17.2

package/dist/{validation/cicd-rules.js → extensions/cicd/rules.js}

@@ -2,26 +2,23 @@
  * CI/CD-Specific Validation Rules
  *
  * Custom TValidationRule implementations for CI/CD pipeline workflows.
- * These run AFTER the built-in validator via the api/validate.ts custom rules injection.
+ * Registered through the ValidationRuleRegistry by the CI/CD extension.
  *
  * Rules:
  * 1. CICD_SECRET_NOT_DECLARED - secret:X referenced but no @secret X declared
  * 2. CICD_SECRET_UNUSED - @secret X declared but never wired
- * 3. CICD_TRIGGER_MISSING - No trigger annotations — pipeline would never run
- * 4. CICD_JOB_MISSING_RUNNER - Job has no runner (uses workflow default or none)
- * 5. CICD_ARTIFACT_CROSS_JOB - Data flows between jobs without @artifact declaration
- * 6. CICD_CIRCULAR_JOB_DEPS - Job dependency cycle detected
- * 7. CICD_MATRIX_WITH_ENVIRONMENT - Matrix + environment = N approval prompts
+ * 3. CICD_TRIGGER_MISSING - No trigger annotations
+ * 4. CICD_JOB_MISSING_RUNNER - Job has no runner
+ * 5. CICD_ARTIFACT_CROSS_JOB - Data flows between jobs without @artifact
+ * 6. CICD_CIRCULAR_JOB_DEPS - Job dependency cycle
+ * 7. CICD_MATRIX_WITH_ENVIRONMENT - Matrix + environment = N approvals
+ * 8. CICD_JOB_CONFIG_ORPHAN - @job config references non-existent job
+ * 9. CICD_STAGE_ORPHAN - @stage has no matching jobs
  */
-import { getDeclaredSecrets, getReferencedSecrets, getJobNames, } from './cicd-detection.js';
+import { getDeclaredSecrets, getReferencedSecrets, getJobNames, } from './detection.js';
 // ---------------------------------------------------------------------------
 // Rule 1: Secret Not Declared
 // ---------------------------------------------------------------------------
-/**
- * A `secret:X` pseudo-node is referenced in @connect but no `@secret X` is declared.
- * This means the export target won't know about the secret and can't generate
- * proper environment variable references.
- */
 export const secretNotDeclaredRule = {
     name: 'CICD_SECRET_NOT_DECLARED',
     validate(ast) {
@@ -43,10 +40,6 @@ export const secretNotDeclaredRule = {
 // ---------------------------------------------------------------------------
 // Rule 2: Secret Unused
 // ---------------------------------------------------------------------------
-/**
- * A `@secret X` is declared but never wired via `@connect secret:X -> ...`.
- * The secret might be intentional (used in a shell-command step) or a leftover.
- */
 export const secretUnusedRule = {
     name: 'CICD_SECRET_UNUSED',
     validate(ast) {
@@ -68,15 +61,10 @@ export const secretUnusedRule = {
 // ---------------------------------------------------------------------------
 // Rule 3: Trigger Missing
 // ---------------------------------------------------------------------------
-/**
- * A CI/CD workflow with no trigger annotations would never run automatically.
- * Needs at least one @trigger (push, pull_request, schedule, dispatch, or tag).
- */
 export const triggerMissingRule = {
     name: 'CICD_TRIGGER_MISSING',
     validate(ast) {
         const triggers = ast.options?.cicd?.triggers || [];
-        // Also check for FW-style triggers (event=, cron=)
         const fwTrigger = ast.options?.trigger;
         if (triggers.length === 0 && !fwTrigger) {
             return [
@@ -93,21 +81,14 @@ export const triggerMissingRule = {
 // ---------------------------------------------------------------------------
 // Rule 4: Job Missing Runner
 // ---------------------------------------------------------------------------
-/**
- * A job (group of nodes with same [job: "name"]) has no explicit runner
- * and the workflow has no default @runner. The export target will use a
- * platform default, which may not be what the user expects.
- */
 export const jobMissingRunnerRule = {
     name: 'CICD_JOB_MISSING_RUNNER',
     validate(ast) {
         const errors = [];
         const defaultRunner = ast.options?.cicd?.runner;
         const jobNames = getJobNames(ast);
-        // If there's a default runner, all jobs are covered
         if (defaultRunner)
             return [];
-        // If there are jobs but no default runner, warn
         if (jobNames.length > 0) {
             errors.push({
                 type: 'warning',
@@ -121,26 +102,18 @@ export const jobMissingRunnerRule = {
 // ---------------------------------------------------------------------------
 // Rule 5: Artifact Cross-Job
 // ---------------------------------------------------------------------------
-/**
- * Data flows between nodes in different jobs via connections, but no @artifact
- * is declared. In CI/CD, each job runs in a fresh environment — data must be
- * explicitly passed via artifacts.
- */
 export const artifactCrossJobRule = {
     name: 'CICD_ARTIFACT_CROSS_JOB',
     validate(ast) {
         const errors = [];
         const artifacts = ast.options?.cicd?.artifacts || [];
-        // Build node -> job map
         const nodeJob = new Map();
         for (const inst of ast.instances) {
             if (inst.job)
                 nodeJob.set(inst.id, inst.job);
         }
-        // Check connections between nodes in different jobs
         const crossJobPairs = new Set();
         for (const conn of ast.connections) {
-            // Skip secret: pseudo-nodes and Start/Exit
             if (conn.from.node.startsWith('secret:'))
                 continue;
             if (conn.from.node === 'Start' || conn.to.node === 'Exit')
@@ -154,7 +127,6 @@ export const artifactCrossJobRule = {
                 }
             }
         }
-        // If there are cross-job data flows but no artifacts declared, warn
         if (crossJobPairs.size > 0 && artifacts.length === 0) {
             const pairs = Array.from(crossJobPairs);
             errors.push({
@@ -169,21 +141,15 @@ export const artifactCrossJobRule = {
 // ---------------------------------------------------------------------------
 // Rule 6: Circular Job Dependencies
 // ---------------------------------------------------------------------------
-/**
- * Job dependencies (derived from @path connections between jobs) form a cycle.
- * CI/CD platforms reject circular job dependencies.
- */
 export const circularJobDepsRule = {
     name: 'CICD_CIRCULAR_JOB_DEPS',
     validate(ast) {
         const errors = [];
-        // Build node -> job map
         const nodeJob = new Map();
         for (const inst of ast.instances) {
             if (inst.job)
                 nodeJob.set(inst.id, inst.job);
         }
-        // Build job dependency graph from connections
         const jobDeps = new Map();
         for (const conn of ast.connections) {
             if (conn.from.node.startsWith('secret:'))
@@ -198,7 +164,6 @@ export const circularJobDepsRule = {
                 jobDeps.get(toJob).add(fromJob);
             }
         }
-        // Detect cycles using DFS
         const visited = new Set();
         const inStack = new Set();
         function hasCycle(job) {
@@ -226,7 +191,7 @@ export const circularJobDepsRule = {
                     code: 'CICD_CIRCULAR_JOB_DEPS',
                     message: `Circular dependency detected involving job '${job}'. CI/CD platforms require a directed acyclic graph of job dependencies.`,
                 });
-                break; // Report once
+                break;
             }
         }
         return errors;
@@ -235,10 +200,6 @@ export const circularJobDepsRule = {
 // ---------------------------------------------------------------------------
 // Rule 7: Matrix with Environment
 // ---------------------------------------------------------------------------
-/**
- * Using @matrix with @environment protection means each matrix combination
- * triggers an approval prompt. For a 3x2 matrix, that's 6 prompts.
- */
 export const matrixWithEnvironmentRule = {
     name: 'CICD_MATRIX_WITH_ENVIRONMENT',
     validate(ast) {
@@ -246,7 +207,6 @@ export const matrixWithEnvironmentRule = {
         const matrix = ast.options?.cicd?.matrix;
         const environments = ast.options?.cicd?.environments || [];
         if (matrix && environments.length > 0) {
-            // Calculate matrix size
             const dimensions = matrix.include
                 ? matrix.include.length
                 : Object.values(matrix.dimensions || {}).reduce((acc, vals) => acc * vals.length, 1);
@@ -262,9 +222,55 @@ export const matrixWithEnvironmentRule = {
     },
 };
 // ---------------------------------------------------------------------------
+// Rule 8: Job Config Orphan
+// ---------------------------------------------------------------------------
+export const jobConfigOrphanRule = {
+    name: 'CICD_JOB_CONFIG_ORPHAN',
+    validate(ast) {
+        const errors = [];
+        const jobConfigs = ast.options?.cicd?.jobs || [];
+        const actualJobs = new Set(getJobNames(ast));
+        for (const jc of jobConfigs) {
+            if (!actualJobs.has(jc.id)) {
+                errors.push({
+                    type: 'warning',
+                    code: 'CICD_JOB_CONFIG_ORPHAN',
+                    message: `@job '${jc.id}' is configured but no node uses [job: "${jc.id}"]. Check for typos or add a node with that job attribute.`,
+                });
+            }
+        }
+        return errors;
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 9: Stage Orphan
+// ---------------------------------------------------------------------------
+export const stageOrphanRule = {
+    name: 'CICD_STAGE_ORPHAN',
+    validate(ast) {
+        const errors = [];
+        const stages = ast.options?.cicd?.stages || [];
+        if (stages.length === 0)
+            return [];
+        const jobNames = getJobNames(ast);
+        if (jobNames.length === 0)
+            return [];
+        for (const stage of stages) {
+            const hasMatch = jobNames.some(j => j === stage.name || j.startsWith(stage.name + '-') || j.startsWith(stage.name + '_'));
+            if (!hasMatch && jobNames.length > 0) {
+                errors.push({
+                    type: 'warning',
+                    code: 'CICD_STAGE_ORPHAN',
+                    message: `Stage '${stage.name}' has no jobs matching by name prefix. Jobs will be assigned by dependency depth.`,
+                });
+            }
+        }
+        return errors;
+    },
+};
+// ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
-/** All CI/CD validation rules */
 export const cicdValidationRules = [
     secretNotDeclaredRule,
     secretUnusedRule,
@@ -273,12 +279,10 @@ export const cicdValidationRules = [
     artifactCrossJobRule,
     circularJobDepsRule,
     matrixWithEnvironmentRule,
+    jobConfigOrphanRule,
+    stageOrphanRule,
 ];
-/**
- * Get all CI/CD validation rules.
- * Convenience function for passing to validateWorkflow().
- */
 export function getCICDValidationRules() {
     return cicdValidationRules;
 }
-//# sourceMappingURL=cicd-rules.js.map
+//# sourceMappingURL=rules.js.map

package/dist/extensions/cicd/tag-handler.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CI/CD tag handler for the TagHandlerRegistry.
+ *
+ * Handles all CI/CD annotation tags: @secret, @runner, @cache, @artifact,
+ * @environment, @matrix, @service, @concurrency, @job, @stage, @variables,
+ * @before_script, @tags, @includes, plus the synthetic _cicdTrigger tag
+ * for CI/CD trigger variants of @trigger.
+ *
+ * Each parser writes to ctx.deploy (the 'cicd' namespace slot) using the
+ * same structures as the former jsdoc-parser.ts private methods.
+ */
+import type { TTagHandlerFn } from '../../parser/tag-registry.js';
+export declare const cicdTagHandler: TTagHandlerFn;
+//# sourceMappingURL=tag-handler.d.ts.map