@peterhauge/apiops-cli 0.1.3-alpha.0

package/dist/lib/parallel-runner.js

@@ -0,0 +1,70 @@
+/**
+ * T018: Parallel execution runner with concurrency control.
+ *
+ * Custom implementation (no external dependencies such as p-limit) to limit
+ * concurrent APIM REST API calls and avoid 429 rate limiting. Azure APIM has
+ * strict per-second request limits, so unbounded Promise.all() would fire all
+ * requests simultaneously, triggering throttling. Bounded concurrency is a
+ * requirement from research.md R8 and justified in tasks.md T018.
+ *
+ * Built-in implementation without external dependencies (no p-limit).
+ */
+/**
+ * Executes tasks in parallel with bounded concurrency.
+ * Uses Promise.allSettled for fault tolerance.
+ */
+export class ParallelRunner {
+    concurrency;
+    constructor(options) {
+        this.concurrency = options.concurrency;
+    }
+    /**
+     * Run tasks in parallel with bounded concurrency.
+     * Returns results for all tasks, including failures.
+     */
+    async runAll(tasks) {
+        const results = [];
+        const executing = new Map();
+        const completed = new Set();
+        for (let i = 0; i < tasks.length; i++) {
+            const task = tasks[i];
+            if (!task)
+                continue;
+            const promise = this.executeTask(task, i, results).then(() => {
+                completed.add(i);
+            });
+            executing.set(i, promise);
+            // When we hit concurrency limit, wait for one to finish
+            if (executing.size >= this.concurrency) {
+                await Promise.race(executing.values());
+                // Remove completed promises
+                for (const idx of completed) {
+                    executing.delete(idx);
+                }
+            }
+        }
+        // Wait for remaining tasks to complete
+        await Promise.allSettled(executing.values());
+        return results;
+    }
+    async executeTask(task, index, results) {
+        try {
+            const value = await task();
+            results[index] = { status: 'fulfilled', value };
+        }
+        catch (error) {
+            results[index] = {
+                status: 'rejected',
+                reason: error instanceof Error ? error : new Error(String(error))
+            };
+        }
+    }
+}
+/**
+ * Helper function to run tasks with default concurrency.
+ */
+export async function runParallel(tasks, concurrency = 5) {
+    const runner = new ParallelRunner({ concurrency });
+    return runner.runAll(tasks);
+}
+//# sourceMappingURL=parallel-runner.js.map

package/dist/lib/parallel-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-runner.js","sourceRoot":"","sources":["../../src/lib/parallel-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH;;;GAGG;AACH,MAAM,OAAO,cAAc;IACjB,WAAW,CAAS;IAE5B,YAAY,OAA8B;QACxC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAI,KAA2B;QACzC,MAAM,OAAO,GAAoB,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;QACnD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;QAEpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,CAAC,IAAI;gBAAE,SAAS;YAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;gBAC3D,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;YAEH,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAE1B,wDAAwD;YACxD,IAAI,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACvC,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;gBACvC,4BAA4B;gBAC5B,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;oBAC5B,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC;QACH,CAAC;QAED,uCAAuC;QACvC,MAAM,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;QAE7C,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,KAAK,CAAC,WAAW,CACvB,IAAsB,EACtB,KAAa,EACb,OAAwB;QAExB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,CAAC;YAC3B,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,GAAG;gBACf,MAAM,EAAE,UAAU;gBAClB,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aAClE,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAA2B,EAC3B,WAAW,GAAG,CAAC;IAEf,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/dist/lib/resource-path.d.ts

@@ -0,0 +1,205 @@
+/**
+ * T013: Resource descriptor ↔ artifact file path mapping
+ * Map descriptor to directory/file paths per data-model.md artifact conventions
+ */
+import { ResourceDescriptor } from '../models/types.js';
+import { ResourceType } from '../models/resource-types.js';
+/**
+ * Fills all positional `{i}` tokens in a template string with `nameParts[i]`.
+ * Throws if a placeholder index has no corresponding entry in `nameParts`.
+ *
+ * Examples:
+ *   formatTemplatePath('apis/{0}/operations/{1}', ['petstore', 'get-user'])
+ *     → 'apis/petstore/operations/get-user'
+ *   formatTemplatePath('', []) → ''
+ */
+export declare function formatTemplatePath(template: string, nameParts: string[]): string;
+/**
+ * Returns the number of positional `{i}` placeholders in a template string.
+ *
+ * Used by callers that need to validate that enough name-parts have been
+ * supplied before filling a template — without performing regex matching
+ * themselves.
+ *
+ * Example:
+ *   countTemplatePlaceholders('apis/{0}/operations/{1}') → 2
+ *   countTemplatePlaceholders('policies/policy')         → 0
+ */
+export declare function countTemplatePlaceholders(template: string): number;
+/**
+ * Ensures a path starts with a single leading slash.
+ *
+ * Example:
+ *   makeFullPath('namedValues/my-nv') → '/namedValues/my-nv'
+ *   makeFullPath('/namedValues/my-nv') → '/namedValues/my-nv'
+ */
+export declare function makeFullPath(relativePath: string): string;
+/**
+ * Strips a single leading slash from a path, if present.
+ *
+ * Example:
+ *   makeRelativePath('/namedValues/my-nv') → 'namedValues/my-nv'
+ *   makeRelativePath('namedValues/my-nv')  → 'namedValues/my-nv'
+ */
+export declare function makeRelativePath(absolutePath: string): string;
+/**
+ * Returns the resource's own name — the last element of `nameParts`.
+ *
+ * For 1-part types (e.g. Api, Product) `nameParts` contains only the own
+ * name, so this is equivalent to `nameParts[0]`.  For 2-part types (e.g.
+ * ApiOperation, ProductTag) the own name is always the final element, with
+ * the parent name preceding it.  Using this helper instead of a hard-coded
+ * index guards against future arity changes and avoids accidentally
+ * returning the parent name.
+ *
+ * Throws a `RangeError` if `nameParts` is empty.
+ *
+ * Examples:
+ *   getNameFromNameParts(['petstore'])                   → 'petstore'
+ *   getNameFromNameParts(['petstore', 'get-user'])       → 'get-user'
+ *   getNameFromNameParts([])                             → throws RangeError
+ */
+export declare function getNameFromNameParts(nameParts: string[]): string;
+/**
+ * Returns `nameParts[index]`, throwing a descriptive `RangeError` if the
+ * index is out of range.
+ *
+ * Prefer this over direct bracket access (`nameParts[0]`) so that missing
+ * name-parts surface as an explicit error rather than a silent `undefined`.
+ *
+ * Examples:
+ *   getNamePart(['petstore', 'get-user'], 0)  → 'petstore'
+ *   getNamePart(['petstore', 'get-user'], 1)  → 'get-user'
+ *   getNamePart([], 0)                        → throws RangeError
+ */
+export declare function getNamePart(nameParts: string[], index: number): string;
+/**
+ * Matches a positional template against a slash-delimited path string and
+ * returns the captured name-part values in positional order, or `undefined`
+ * if the path does not match the template.
+ *
+ * Both artifact-directory paths and ARM path suffixes use the same
+ * `{0}`, `{1}` placeholder syntax, so this single function handles both.
+ * Callers are not required to know anything about regexes.
+ *
+ * Examples:
+ *   parseTemplatePath('apis/{0}/operations/{1}', 'apis/petstore/operations/get')
+ *     → ['petstore', 'get']
+ *   parseTemplatePath('policies/policy', 'policies/policy')
+ *     → []
+ *   parseTemplatePath('apis/{0}', 'backends/b1')
+ *     → undefined
+ */
+export declare function parseTemplatePath(template: string, path: string): string[] | undefined;
+/**
+ * Builds the artifact directory path for a given descriptor.
+ * Returns the directory where this resource's files should be stored.
+ *
+ * @param baseDir - Root artifact directory
+ * @param descriptor - Resource descriptor
+ * @returns Full directory path (OS-normalized)
+ */
+export declare function buildArtifactDirectory(baseDir: string, descriptor: ResourceDescriptor): string;
+/**
+ * Builds the full artifact file path for a given descriptor.
+ * Returns the path to the info file (JSON/XML/MD).
+ *
+ * @param baseDir - Root artifact directory
+ * @param descriptor - Resource descriptor
+ * @returns Full file path (OS-normalized), or undefined if resource has no info file
+ */
+export declare function buildArtifactFilePath(baseDir: string, descriptor: ResourceDescriptor): string | undefined;
+/**
+ * Builds the policy file path for a resource that supports policies.
+ *
+ * @param baseDir - Root artifact directory
+ * @param descriptor - Resource descriptor
+ * @returns Full path to policy.xml file
+ */
+export declare function buildPolicyFilePath(baseDir: string, descriptor: ResourceDescriptor): string;
+/**
+ * Builds the API specification file path.
+ *
+ * @param baseDir - Root artifact directory
+ * @param descriptor - API descriptor
+ * @param format - Specification format (yaml, json, graphql, wsdl, wadl)
+ * @returns Full path to specification file
+ */
+export declare function buildSpecificationFilePath(baseDir: string, descriptor: ResourceDescriptor, format: 'yaml' | 'json' | 'graphql' | 'wsdl' | 'wadl'): string;
+/**
+ * Builds the association file path (apis.json or groups.json).
+ *
+ * @param baseDir - Root artifact directory
+ * @param descriptor - Product or Gateway descriptor
+ * @param associationType - Type of association (apis, groups, or tags)
+ * @returns Full path to association file
+ */
+export declare function buildAssociationFilePath(baseDir: string, descriptor: ResourceDescriptor, associationType: 'apis' | 'groups' | 'tags'): string;
+/**
+ * Derives the list URL path segment(s) from an ARM path suffix template.
+ *
+ * The list path is structurally derivable from `armPathSuffix`:
+ * - Last segment is a fixed word (no placeholder) → singleton; neither path is present.
+ * - Exactly one `{N}` placeholder and it is the last segment → top-level resource;
+ *   `listPath` = the path before the placeholder (with a leading '/').
+ * - Two or more `{N}` placeholders and the last segment is the highest-index one →
+ *   child resource; `childListPath` = the collection segment immediately before the
+ *   last placeholder (with a leading '/').
+ *
+ * Examples:
+ *   deriveListPaths('namedValues/{0}')            → { listPath: '/namedValues' }
+ *   deriveListPaths('apis/{0}/operations/{1}')    → { childListPath: '/operations' }
+ *   deriveListPaths('policies/policy')            → {}  (singleton)
+ *   deriveListPaths('apis/{0}/policies/policy')   → {}  (singleton)
+ */
+export declare function deriveListPaths(template: string): {
+    listPath?: string;
+    childListPath?: string;
+};
+/**
+ * Parses an artifact file path back into a ResourceDescriptor.
+ * Inverse of buildArtifactFilePath.
+ *
+ * @param baseDir - Root artifact directory
+ * @param filePath - Full path to artifact file
+ * @returns ResourceDescriptor or undefined if path doesn't match known patterns
+ */
+export declare function parseArtifactPath(baseDir: string, filePath: string): ResourceDescriptor | undefined;
+/**
+ * Check if a resource type is a singleton (no list, only get).
+ * Singletons have armPathSuffix ending with a fixed segment (no `{n}` placeholder).
+ * E.g., ServicePolicy (`policies/policy`), ApiWiki (`apis/{0}/wikis/default`).
+ */
+export declare function isSingletonType(type: ResourceType): boolean;
+/**
+ * Check if a resource type is a child type requiring a parent.
+ * Child types have armPathSuffix with more path segments after the first placeholder.
+ * E.g., `apis/{0}/tags/{1}` or `apis/{0}/policies/policy`.
+ */
+export declare function isChildType(type: ResourceType): boolean;
+/**
+ * Compute the publish tier for a resource type based on ARM path structure.
+ * Resources are published from lowest tier to highest; same tier runs in parallel.
+ *
+ * Tier formula: `placeholderCount * 2 + (hasSegmentsAfterLastPlaceholder ? 1 : 0)`
+ *
+ * This ensures:
+ * - Fewer placeholders = earlier tier (parents before children)
+ * - Within same placeholder count, resources ending at a placeholder come
+ *   before those with fixed segments after (e.g., operations before operation policies)
+ *
+ * Examples:
+ *   `apis/{0}`                              → tier 2 (1 placeholder, ends at placeholder)
+ *   `apis/{0}/policies/policy`              → tier 3 (1 placeholder, has suffix)
+ *   `apis/{0}/operations/{1}`               → tier 4 (2 placeholders, ends at placeholder)
+ *   `apis/{0}/operations/{1}/policies/policy` → tier 5 (2 placeholders, has suffix)
+ */
+export declare function getPublishTier(type: ResourceType): number;
+/**
+ * Check if a resource type is a "grandchild" - has path segments after the last placeholder.
+ * These types depend on an intermediate parent that must exist first.
+ *
+ * @deprecated Use getPublishTier() for N-tier ordering instead
+ */
+export declare function hasNestedParent(type: ResourceType): boolean;
+//# sourceMappingURL=resource-path.d.ts.map

package/dist/lib/resource-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-path.d.ts","sourceRoot":"","sources":["../../src/lib/resource-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAA0B,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAenF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAYhF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAStE;AAoBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAKtF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,MAAM,CAWR;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,MAAM,GAAG,SAAS,CASpB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,GAC7B,MAAM,CAGR;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GACpD,MAAM,CAiBR;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,EAC9B,eAAe,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAC1C,MAAM,CAUR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAoBA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,kBAAkB,GAAG,SAAS,CA4ChC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAK3D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CASvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAiBzD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAqB3D"}