@intentius/chant-lexicon-github 0.124.31 → 0.124.33

package/dist/codegen/parse.js

@@ -0,0 +1,595 @@
+/**
+ * GitHub Actions Workflow JSON Schema parser.
+ *
+ * Parses the single workflow schema into multiple entity results — one
+ * per resource/property entity (Workflow, Job, Step, triggers, etc.).
+ */
+import { extractConstraints as coreExtractConstraints, constraintsIsEmpty as coreConstraintsIsEmpty, primaryType, } from "@intentius/chant/codegen/json-schema";
+export { coreConstraintsIsEmpty as constraintsIsEmpty };
+// ── Entity extraction mapping ──────────────────────────────────────
+const RESOURCE_ENTITIES = [
+    {
+        typeName: "GitHub::Actions::Workflow",
+        source: "root",
+        description: "A GitHub Actions workflow definition",
+    },
+    {
+        typeName: "GitHub::Actions::Job",
+        source: "#/definitions/normalJob",
+        description: "A standard CI job",
+    },
+    {
+        typeName: "GitHub::Actions::ReusableWorkflowCallJob",
+        source: "#/definitions/reusableWorkflowCallJob",
+        description: "A reusable workflow call job (uses: workflow reference)",
+    },
+];
+const PROPERTY_ENTITIES = [
+    { typeName: "GitHub::Actions::Step", source: "normalJob:steps:item", description: "A workflow step" },
+    { typeName: "GitHub::Actions::Strategy", source: "normalJob:strategy", description: "Job strategy configuration" },
+    { typeName: "GitHub::Actions::Permissions", source: "#/definitions/permissions", description: "Workflow or job permissions" },
+    { typeName: "GitHub::Actions::Concurrency", source: "#/definitions/concurrency", description: "Concurrency control" },
+    { typeName: "GitHub::Actions::Container", source: "#/definitions/container", description: "Container configuration for a job" },
+    { typeName: "GitHub::Actions::Service", source: "service", description: "Service container configuration" },
+    { typeName: "GitHub::Actions::Environment", source: "#/definitions/environment", description: "Deployment environment" },
+    { typeName: "GitHub::Actions::Defaults", source: "#/definitions/defaults", description: "Default settings for all jobs" },
+    { typeName: "GitHub::Actions::PushTrigger", source: "event:push", description: "Push event trigger" },
+    { typeName: "GitHub::Actions::PullRequestTrigger", source: "event:pull_request", description: "Pull request event trigger" },
+    { typeName: "GitHub::Actions::PullRequestTargetTrigger", source: "event:pull_request_target", description: "Pull request target event trigger" },
+    { typeName: "GitHub::Actions::ScheduleTrigger", source: "event:schedule", description: "Schedule event trigger" },
+    { typeName: "GitHub::Actions::WorkflowDispatchTrigger", source: "event:workflow_dispatch", description: "Workflow dispatch event trigger" },
+    { typeName: "GitHub::Actions::WorkflowCallTrigger", source: "event:workflow_call", description: "Workflow call event trigger" },
+    { typeName: "GitHub::Actions::WorkflowRunTrigger", source: "event:workflow_run", description: "Workflow run event trigger" },
+    { typeName: "GitHub::Actions::RepositoryDispatchTrigger", source: "event:repository_dispatch", description: "Repository dispatch event trigger" },
+    { typeName: "GitHub::Actions::WorkflowInput", source: "workflow_call:input", description: "Reusable workflow input parameter" },
+    { typeName: "GitHub::Actions::WorkflowOutput", source: "workflow_call:output", description: "Reusable workflow output" },
+    { typeName: "GitHub::Actions::WorkflowSecret", source: "workflow_call:secret", description: "Reusable workflow secret" },
+];
+// ── Parser ─────────────────────────────────────────────────────────
+/**
+ * Parse the GitHub Actions Workflow JSON Schema into multiple entity results.
+ */
+export function parseWorkflowSchema(data) {
+    const schema = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
+    const results = [];
+    for (const entity of RESOURCE_ENTITIES) {
+        const result = extractEntity(schema, entity, false);
+        if (result)
+            results.push(result);
+    }
+    for (const entity of PROPERTY_ENTITIES) {
+        const result = extractEntity(schema, entity, true);
+        if (result) {
+            result.isProperty = true;
+            results.push(result);
+        }
+    }
+    return results;
+}
+function extractEntity(schema, entity, isProperty) {
+    const def = resolveSource(schema, entity.source);
+    if (!def) {
+        // Create minimal entry for entities we know exist but can't resolve from schema
+        return {
+            resource: {
+                typeName: entity.typeName,
+                description: entity.description,
+                properties: addCommentProperty(entity.typeName, buildFallbackProperties(entity.typeName)),
+                attributes: [],
+                deprecatedProperties: [],
+            },
+            propertyTypes: [],
+            enums: [],
+        };
+    }
+    const objectDef = findObjectVariant(def, schema);
+    const properties = objectDef?.properties
+        ? parseProperties(objectDef.properties, new Set(objectDef.required ?? []), schema)
+        : buildFallbackProperties(entity.typeName);
+    const overrides = PROPERTY_OVERRIDES[entity.typeName];
+    if (overrides) {
+        for (const prop of properties) {
+            if (overrides[prop.name]) {
+                prop.tsType = overrides[prop.name];
+            }
+        }
+    }
+    addCommentProperty(entity.typeName, properties);
+    return {
+        resource: {
+            typeName: entity.typeName,
+            description: entity.description ?? objectDef?.description ?? def.description,
+            properties,
+            attributes: [],
+            deprecatedProperties: mineDeprecatedProperties(properties),
+        },
+        propertyTypes: [],
+        enums: [],
+    };
+}
+// ── Source resolution ──────────────────────────────────────────────
+function resolveSource(schema, source) {
+    if (source === "root") {
+        return { properties: schema.properties, required: schema.required };
+    }
+    if (source.startsWith("#/definitions/")) {
+        const defName = source.slice("#/definitions/".length);
+        return schema.definitions?.[defName] ?? null;
+    }
+    // normalJob:property — resolve from normalJob definition
+    if (source.startsWith("normalJob:")) {
+        const segments = source.slice("normalJob:".length).split(":");
+        let current = schema.definitions?.normalJob ?? null;
+        for (const seg of segments) {
+            if (!current)
+                return null;
+            if (seg === "item") {
+                if (!current.items)
+                    return null;
+                return findObjectVariant(current.items, schema);
+            }
+            if (!current.properties?.[seg])
+                return null;
+            const prop = current.properties[seg];
+            current = prop.$ref ? resolveRef(prop.$ref, schema) : prop;
+        }
+        return current;
+    }
+    // event:name — resolve trigger event type
+    if (source.startsWith("event:")) {
+        const eventName = source.slice("event:".length);
+        return resolveEventTrigger(schema, eventName);
+    }
+    // workflow_call:input/output/secret
+    if (source.startsWith("workflow_call:")) {
+        const part = source.slice("workflow_call:".length);
+        return resolveWorkflowCallPart(schema, part);
+    }
+    // service — from container definitions
+    if (source === "service") {
+        // Services are containers with additional properties
+        const containerDef = schema.definitions?.container;
+        return containerDef ?? null;
+    }
+    return null;
+}
+function resolveEventTrigger(schema, eventName) {
+    // Try to find in definitions like eventObject, or under "on" properties
+    const defName = `eventObject`;
+    const eventDef = schema.definitions?.[defName];
+    if (eventDef?.properties?.[eventName]) {
+        const prop = eventDef.properties[eventName];
+        if (prop.$ref)
+            return resolveRef(prop.$ref, schema);
+        return prop;
+    }
+    // Try direct definition names
+    const directNames = [
+        eventName,
+        `${eventName}Event`,
+    ];
+    for (const name of directNames) {
+        if (schema.definitions?.[name]) {
+            return schema.definitions[name];
+        }
+    }
+    return null;
+}
+function resolveWorkflowCallPart(schema, part) {
+    // Look in workflow_call trigger definition
+    const wcDef = schema.definitions?.["eventObject"]?.properties?.workflow_call;
+    if (!wcDef)
+        return null;
+    const resolved = wcDef.$ref ? resolveRef(wcDef.$ref, schema) : wcDef;
+    if (!resolved)
+        return null;
+    const objectDef = findObjectVariant(resolved, schema);
+    if (!objectDef?.properties)
+        return null;
+    const mapping = {
+        input: "inputs",
+        output: "outputs",
+        secret: "secrets",
+    };
+    const propName = mapping[part] ?? part;
+    const prop = objectDef.properties[propName];
+    if (!prop)
+        return null;
+    // Get the "additionalProperties" or "patternProperties" to find the item schema
+    const resolvedProp = prop.$ref ? resolveRef(prop.$ref, schema) : prop;
+    if (!resolvedProp)
+        return null;
+    if (resolvedProp.patternProperties) {
+        const first = Object.values(resolvedProp.patternProperties)[0];
+        if (first)
+            return first;
+    }
+    if (typeof resolvedProp.additionalProperties === "object") {
+        return resolvedProp.additionalProperties;
+    }
+    return resolvedProp;
+}
+function resolveRef(ref, schema) {
+    const prefix = "#/definitions/";
+    if (!ref.startsWith(prefix))
+        return null;
+    const defName = ref.slice(prefix.length);
+    return schema.definitions?.[defName] ?? null;
+}
+function findObjectVariant(def, schema) {
+    if (def.properties)
+        return def;
+    const variants = def.oneOf ?? def.anyOf;
+    if (!variants)
+        return null;
+    const objectVariants = [];
+    for (const v of variants) {
+        let resolved = v;
+        if (v.$ref && schema) {
+            const r = resolveRef(v.$ref, schema);
+            if (r)
+                resolved = r;
+            else
+                continue;
+        }
+        else if (v.$ref) {
+            continue;
+        }
+        if (resolved.properties) {
+            objectVariants.push(resolved);
+        }
+    }
+    if (objectVariants.length === 0)
+        return null;
+    if (objectVariants.length === 1)
+        return objectVariants[0];
+    // Merge: pick variant with most properties as base
+    let best = objectVariants[0];
+    let bestCount = Object.keys(best.properties).length;
+    for (let i = 1; i < objectVariants.length; i++) {
+        const count = Object.keys(objectVariants[i].properties).length;
+        if (count > bestCount) {
+            best = objectVariants[i];
+            bestCount = count;
+        }
+    }
+    const mergedProperties = { ...best.properties };
+    for (const variant of objectVariants) {
+        if (variant === best)
+            continue;
+        for (const [propName, propDef] of Object.entries(variant.properties)) {
+            if (!(propName in mergedProperties)) {
+                mergedProperties[propName] = propDef;
+            }
+        }
+    }
+    return { ...best, properties: mergedProperties };
+}
+// ── Property parsing ──────────────────────────────────────────────
+function parseProperties(properties, requiredSet, schema) {
+    const result = [];
+    for (const [name, prop] of Object.entries(properties)) {
+        const tsType = resolvePropertyType(prop, schema);
+        result.push({
+            name,
+            tsType,
+            required: requiredSet.has(name),
+            description: prop.description,
+            enum: prop.enum,
+            constraints: coreExtractConstraints(prop),
+        });
+    }
+    return result;
+}
+function resolvePropertyType(prop, schema) {
+    if (!prop)
+        return "any";
+    if (prop.$ref) {
+        const def = resolveRef(prop.$ref, schema);
+        if (def) {
+            if (def.enum && def.enum.length > 0 && !def.properties) {
+                return def.enum.map((v) => JSON.stringify(v)).join(" | ");
+            }
+            if (def.type && !def.properties) {
+                return jsonTypeToTs(primaryType(def.type));
+            }
+            if (def.properties)
+                return "Record<string, any>";
+        }
+        return "any";
+    }
+    if (prop.enum && prop.enum.length > 0) {
+        return prop.enum.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    if (prop.oneOf || prop.anyOf) {
+        const variants = prop.oneOf ?? prop.anyOf ?? [];
+        const types = new Set();
+        for (const v of variants) {
+            types.add(resolvePropertyType(v, schema));
+        }
+        const uniqueTypes = [...types].filter((t) => t !== "any");
+        if (uniqueTypes.length === 0)
+            return "any";
+        if (uniqueTypes.length === 1)
+            return uniqueTypes[0];
+        return uniqueTypes.join(" | ");
+    }
+    const pt = primaryType(prop.type);
+    switch (pt) {
+        case "string": return "string";
+        case "integer":
+        case "number": return "number";
+        case "boolean": return "boolean";
+        case "array":
+            if (prop.items) {
+                const itemType = resolvePropertyType(prop.items, schema);
+                if (itemType.includes(" | "))
+                    return `(${itemType})[]`;
+                return `${itemType}[]`;
+            }
+            return "any[]";
+        case "object": return "Record<string, any>";
+        default: return "any";
+    }
+}
+function jsonTypeToTs(type) {
+    switch (type) {
+        case "string": return "string";
+        case "integer":
+        case "number": return "number";
+        case "boolean": return "boolean";
+        case "array": return "any[]";
+        case "object": return "Record<string, any>";
+        default: return "any";
+    }
+}
+// ── Property overrides ────────────────────────────────────────────
+const PROPERTY_OVERRIDES = {
+    "GitHub::Actions::Workflow": {
+        on: "Record<string, any>",
+        jobs: "Record<string, any>",
+        permissions: "Permissions | string",
+        concurrency: "Concurrency | string",
+        defaults: "Defaults",
+        env: "Record<string, string>",
+    },
+    "GitHub::Actions::Job": {
+        steps: "Step[]",
+        strategy: "Strategy",
+        permissions: "Permissions | string",
+        concurrency: "Concurrency | string",
+        container: "Container | string",
+        services: "Record<string, Service>",
+        environment: "Environment | string",
+        defaults: "Defaults",
+        env: "Record<string, string>",
+        needs: "string[]",
+        outputs: "Record<string, string>",
+        "runs-on": "string | string[]",
+        "timeout-minutes": "number",
+        "continue-on-error": "boolean",
+        "if": "string",
+    },
+    "GitHub::Actions::Step": {
+        env: "Record<string, string>",
+        with: "Record<string, string | number | boolean>",
+        "if": "string",
+        "timeout-minutes": "number",
+        "continue-on-error": "boolean",
+    },
+    "GitHub::Actions::Strategy": {
+        matrix: "Record<string, any>",
+    },
+};
+// ── Comments ──────────────────────────────────────────────────────
+/**
+ * Entities that carry a `comment`: not a workflow key, but `# ...` lines the
+ * serializer writes above the entry (above `name:` for a workflow, the file's
+ * header), so the reasons a hand-written workflow keeps as YAML comments
+ * reach the rendered file (#3667).
+ */
+const COMMENTED_ENTITIES = {
+    "GitHub::Actions::Workflow": "YAML comment lines written at the top of the file, above `name:`. Not a workflow key; each line of the string becomes a `#` line",
+    "GitHub::Actions::Job": "YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line",
+    "GitHub::Actions::ReusableWorkflowCallJob": "YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line",
+    "GitHub::Actions::Step": "YAML comment lines written above the step. Not a step key; each line of the string becomes a `#` line",
+};
+function addCommentProperty(typeName, properties) {
+    const description = COMMENTED_ENTITIES[typeName];
+    if (description && !properties.some((p) => p.name === "comment")) {
+        properties.push({ name: "comment", tsType: "string", required: false, description, constraints: {} });
+    }
+    return properties;
+}
+// ── Fallback properties ───────────────────────────────────────────
+/**
+ * Provide fallback properties for entities that can't be resolved from the schema.
+ */
+function buildFallbackProperties(typeName) {
+    const fallbacks = {
+        "GitHub::Actions::Workflow": [
+            { name: "name", tsType: "string", required: false, description: "The name of the workflow" },
+            { name: "on", tsType: "Record<string, any>", required: true, description: "Event triggers" },
+            { name: "jobs", tsType: "Record<string, any>", required: true, description: "Jobs in the workflow" },
+            { name: "permissions", tsType: "Permissions | string", required: false, description: "Permissions for the workflow" },
+            { name: "env", tsType: "Record<string, string>", required: false, description: "Environment variables" },
+            { name: "concurrency", tsType: "Concurrency | string", required: false, description: "Concurrency settings" },
+            { name: "defaults", tsType: "Defaults", required: false, description: "Default settings" },
+            { name: "run-name", tsType: "string", required: false, description: "Dynamic name for workflow runs" },
+        ],
+        "GitHub::Actions::Job": [
+            { name: "name", tsType: "string", required: false, description: "Job display name" },
+            { name: "runs-on", tsType: "string | string[]", required: true, description: "Runner label(s)" },
+            { name: "steps", tsType: "Step[]", required: false, description: "Job steps" },
+            { name: "needs", tsType: "string[]", required: false, description: "Job dependencies" },
+            { name: "if", tsType: "string", required: false, description: "Conditional expression" },
+            { name: "permissions", tsType: "Permissions | string", required: false, description: "Permissions" },
+            { name: "environment", tsType: "Environment | string", required: false, description: "Deployment environment" },
+            { name: "concurrency", tsType: "Concurrency | string", required: false, description: "Concurrency settings" },
+            { name: "outputs", tsType: "Record<string, string>", required: false, description: "Job outputs" },
+            { name: "env", tsType: "Record<string, string>", required: false, description: "Environment variables" },
+            { name: "defaults", tsType: "Defaults", required: false, description: "Default settings" },
+            { name: "strategy", tsType: "Strategy", required: false, description: "Strategy (matrix, etc.)" },
+            { name: "container", tsType: "Container | string", required: false, description: "Container to run in" },
+            { name: "services", tsType: "Record<string, Service>", required: false, description: "Service containers" },
+            { name: "timeout-minutes", tsType: "number", required: false, description: "Timeout in minutes" },
+            { name: "continue-on-error", tsType: "boolean", required: false, description: "Continue on error" },
+        ],
+        "GitHub::Actions::ReusableWorkflowCallJob": [
+            { name: "uses", tsType: "string", required: true, description: "Reusable workflow reference" },
+            { name: "with", tsType: "Record<string, any>", required: false, description: "Inputs for the reusable workflow" },
+            { name: "secrets", tsType: "Record<string, any> | string", required: false, description: "Secrets to pass" },
+            { name: "needs", tsType: "string[]", required: false, description: "Job dependencies" },
+            { name: "if", tsType: "string", required: false, description: "Conditional expression" },
+            { name: "permissions", tsType: "Permissions | string", required: false, description: "Permissions" },
+            { name: "concurrency", tsType: "Concurrency | string", required: false, description: "Concurrency settings" },
+        ],
+        "GitHub::Actions::Step": [
+            { name: "name", tsType: "string", required: false, description: "Step display name" },
+            { name: "uses", tsType: "string", required: false, description: "Action reference" },
+            { name: "run", tsType: "string", required: false, description: "Shell command" },
+            { name: "with", tsType: "Record<string, string | number | boolean>", required: false, description: "Action inputs. The runner reads each as a string; a number or boolean renders as written (`fetch-depth: 0`)" },
+            { name: "env", tsType: "Record<string, string>", required: false, description: "Environment variables" },
+            { name: "if", tsType: "string", required: false, description: "Conditional expression" },
+            { name: "id", tsType: "string", required: false, description: "Step ID for output references" },
+            { name: "shell", tsType: "string", required: false, description: "Shell to use" },
+            { name: "working-directory", tsType: "string", required: false, description: "Working directory" },
+            { name: "timeout-minutes", tsType: "number", required: false, description: "Timeout in minutes" },
+            { name: "continue-on-error", tsType: "boolean", required: false, description: "Continue on error" },
+        ],
+        "GitHub::Actions::Strategy": [
+            { name: "matrix", tsType: "Record<string, any>", required: false, description: "Matrix configuration" },
+            { name: "fail-fast", tsType: "boolean", required: false, description: "Cancel all jobs if one fails" },
+            { name: "max-parallel", tsType: "number", required: false, description: "Max parallel jobs" },
+        ],
+        "GitHub::Actions::Permissions": [
+            { name: "actions", tsType: '"read" | "write" | "none"', required: false },
+            { name: "checks", tsType: '"read" | "write" | "none"', required: false },
+            { name: "contents", tsType: '"read" | "write" | "none"', required: false },
+            { name: "deployments", tsType: '"read" | "write" | "none"', required: false },
+            { name: "id-token", tsType: '"write" | "none"', required: false },
+            { name: "issues", tsType: '"read" | "write" | "none"', required: false },
+            { name: "packages", tsType: '"read" | "write" | "none"', required: false },
+            { name: "pages", tsType: '"read" | "write" | "none"', required: false },
+            { name: "pull-requests", tsType: '"read" | "write" | "none"', required: false },
+            { name: "security-events", tsType: '"read" | "write" | "none"', required: false },
+            { name: "statuses", tsType: '"read" | "write" | "none"', required: false },
+        ],
+        "GitHub::Actions::Concurrency": [
+            { name: "group", tsType: "string", required: true, description: "Concurrency group name" },
+            { name: "cancel-in-progress", tsType: "boolean", required: false, description: "Cancel in-progress runs" },
+        ],
+        "GitHub::Actions::Container": [
+            { name: "image", tsType: "string", required: true, description: "Docker image" },
+            { name: "credentials", tsType: "Record<string, string>", required: false, description: "Registry credentials" },
+            { name: "env", tsType: "Record<string, string>", required: false, description: "Environment variables" },
+            { name: "ports", tsType: "(number | string)[]", required: false, description: "Exposed ports: a container port (published on a random host port) or \"host:container\"" },
+            { name: "volumes", tsType: "string[]", required: false, description: "Volume mounts" },
+            { name: "options", tsType: "string", required: false, description: "Docker options" },
+        ],
+        "GitHub::Actions::Service": [
+            { name: "image", tsType: "string", required: true, description: "Docker image" },
+            { name: "credentials", tsType: "Record<string, string>", required: false },
+            { name: "env", tsType: "Record<string, string>", required: false },
+            { name: "ports", tsType: "(number | string)[]", required: false, description: "Exposed ports: a container port (published on a random host port) or \"host:container\", which a step on the runner reaches at localhost:<host>" },
+            { name: "volumes", tsType: "string[]", required: false },
+            { name: "options", tsType: "string", required: false },
+        ],
+        "GitHub::Actions::Environment": [
+            { name: "name", tsType: "string", required: true, description: "Environment name" },
+            { name: "url", tsType: "string", required: false, description: "Environment URL" },
+        ],
+        "GitHub::Actions::Defaults": [
+            { name: "run", tsType: "Record<string, string>", required: false, description: "Default run settings" },
+        ],
+        "GitHub::Actions::PushTrigger": [
+            { name: "branches", tsType: "string[]", required: false },
+            { name: "branches-ignore", tsType: "string[]", required: false },
+            { name: "tags", tsType: "string[]", required: false },
+            { name: "tags-ignore", tsType: "string[]", required: false },
+            { name: "paths", tsType: "string[]", required: false },
+            { name: "paths-ignore", tsType: "string[]", required: false },
+        ],
+        "GitHub::Actions::PullRequestTrigger": [
+            { name: "branches", tsType: "string[]", required: false },
+            { name: "branches-ignore", tsType: "string[]", required: false },
+            { name: "paths", tsType: "string[]", required: false },
+            { name: "paths-ignore", tsType: "string[]", required: false },
+            { name: "types", tsType: "string[]", required: false },
+        ],
+        "GitHub::Actions::PullRequestTargetTrigger": [
+            { name: "branches", tsType: "string[]", required: false },
+            { name: "branches-ignore", tsType: "string[]", required: false },
+            { name: "paths", tsType: "string[]", required: false },
+            { name: "paths-ignore", tsType: "string[]", required: false },
+            { name: "types", tsType: "string[]", required: false },
+        ],
+        "GitHub::Actions::ScheduleTrigger": [
+            { name: "cron", tsType: "string", required: true, description: "POSIX cron expression" },
+        ],
+        "GitHub::Actions::WorkflowDispatchTrigger": [
+            { name: "inputs", tsType: "Record<string, any>", required: false },
+        ],
+        "GitHub::Actions::WorkflowCallTrigger": [
+            { name: "inputs", tsType: "Record<string, any>", required: false },
+            { name: "outputs", tsType: "Record<string, any>", required: false },
+            { name: "secrets", tsType: "Record<string, any>", required: false },
+        ],
+        "GitHub::Actions::WorkflowRunTrigger": [
+            { name: "workflows", tsType: "string[]", required: false },
+            { name: "types", tsType: "string[]", required: false },
+            { name: "branches", tsType: "string[]", required: false },
+            { name: "branches-ignore", tsType: "string[]", required: false },
+        ],
+        "GitHub::Actions::RepositoryDispatchTrigger": [
+            { name: "types", tsType: "string[]", required: false },
+        ],
+        "GitHub::Actions::WorkflowInput": [
+            { name: "description", tsType: "string", required: false },
+            { name: "required", tsType: "boolean", required: false },
+            { name: "default", tsType: "string", required: false },
+            { name: "type", tsType: '"string" | "boolean" | "number" | "choice" | "environment"', required: false },
+            { name: "options", tsType: "string[]", required: false },
+        ],
+        "GitHub::Actions::WorkflowOutput": [
+            { name: "description", tsType: "string", required: false },
+            { name: "value", tsType: "string", required: true },
+        ],
+        "GitHub::Actions::WorkflowSecret": [
+            { name: "description", tsType: "string", required: false },
+            { name: "required", tsType: "boolean", required: false },
+        ],
+    };
+    const props = fallbacks[typeName];
+    if (!props)
+        return [];
+    return props.map((p) => ({
+        ...p,
+        constraints: {},
+    }));
+}
+// ── Helpers ───────────────────────────────────────────────────────
+const DEPRECATION_RE = /\bDeprecated\b|\bdeprecated\b|\blegacy\b|no longer (available|recommended|used|supported)/i;
+function mineDeprecatedProperties(properties) {
+    const deprecated = [];
+    for (const prop of properties) {
+        if (prop.description && DEPRECATION_RE.test(prop.description)) {
+            deprecated.push(prop.name);
+        }
+    }
+    return deprecated;
+}
+/**
+ * Extract short name: "GitHub::Actions::Job" → "Job"
+ */
+export function githubShortName(typeName) {
+    const parts = typeName.split("::");
+    return parts[parts.length - 1];
+}
+/**
+ * Extract service name: "GitHub::Actions::Job" → "Actions"
+ */
+export function githubServiceName(typeName) {
+    const parts = typeName.split("::");
+    return parts.length >= 2 ? parts[1] : "Actions";
+}

package/dist/codegen/patches.js

@@ -0,0 +1,36 @@
+/**
+ * Schema augmentation patches for GitHub Actions Workflow JSON Schema.
+ */
+/**
+ * Registry of known schema patches.
+ * Currently empty — the SchemaStore workflow schema is well-maintained.
+ */
+export const schemaPatches = [];
+/**
+ * Apply all registered patches to a parsed schema.
+ */
+export function applyPatches(schema) {
+    const applied = [];
+    const skipped = [];
+    for (const patch of schemaPatches) {
+        const segments = patch.path.split(".");
+        let target = schema;
+        for (const segment of segments) {
+            if (target && typeof target === "object" && segment in target) {
+                target = target[segment];
+            }
+            else {
+                target = undefined;
+                break;
+            }
+        }
+        if (target) {
+            patch.apply(target);
+            applied.push(patch.description);
+        }
+        else {
+            skipped.push(`${patch.description} (path "${patch.path}" not found)`);
+        }
+    }
+    return { applied, skipped };
+}

package/dist/components/ci-jobs.d.ts

@@ -35,6 +35,13 @@ export declare function jobTokenEnv(gh?: boolean): Record<string, string>;
  * names none).
  */
 export declare function onTrigger(trigger: OpTrigger): Record<string, unknown>;
+/**
+ * A push Op's concurrency group (#4169): one per commit under `build:
+ * "every"`, so no push cancels or replaces another's run; one per ref under
+ * `newest`, so the newest push waits and each build request's tag runs on its
+ * own; and the Op's own name otherwise, one run at a time.
+ */
+export declare function opConcurrencyGroup(jobName: string, trigger: OpTrigger): string;
 /**
  * A workflow document before emission. Every generator's document is one of
  * these; each leaves out the sections it has no use for.

package/dist/components/ci-jobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci-jobs.d.ts","sourceRoot":"","sources":["../../src/components/ci-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAG1D,qGAAqG;AACrG,eAAO,MAAM,eAAe,+BAA+B,CAAC;AAC5D,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AAEhE,iIAAiI;AACjI,wBAAgB,YAAY,CAAC,WAAW,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEjF;AAED,oDAAoD;AACpD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1G;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOpG;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5F;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,EAAE,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASrE;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,qGAAqG;IACrG,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAW/D"}
+{"version":3,"file":"ci-jobs.d.ts","sourceRoot":"","sources":["../../src/components/ci-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAG1D,qGAAqG;AACrG,eAAO,MAAM,eAAe,+BAA+B,CAAC;AAC5D,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AAEhE,iIAAiI;AACjI,wBAAgB,YAAY,CAAC,WAAW,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEjF;AAED,oDAAoD;AACpD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1G;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOpG;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5F;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,EAAE,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYrE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,MAAM,CAG9E;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,qGAAqG;IACrG,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAW/D"}