ioc-manifest 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ioc-manifest contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,350 @@
+# ioc-manifest
+
+**Build-time discovery and codegen for Awilix (PROXY mode).** This package generates a typed registration manifest from your TypeScript sources. It is **not** an IoC container and **does not replace Awilix** — you still create an Awilix container and call `registerIocFromManifest` so discovered factories are registered with correct keys and lifetimes.
+
+At a glance:
+
+- **Discovers** `build*` (configurable) factory exports under `discovery.scanDirs`
+- **Infers** contracts from return types and dependency parameters
+- **Emits** `ioc-manifest.ts` (data for registration) and `ioc-registry.types.ts` (typed cradle)
+- **Registers** everything into Awilix via the small runtime helper in this package
+
+---
+
+## What this is / is not
+
+| This package | Not this package |
+| --- | --- |
+| Codegen + conventions + validation | A general-purpose DI container |
+| Works with **Awilix PROXY** mode and flat resolvers | Class/decorator frameworks (NestJS, Inversify, …) |
+| **Production policy** in **`ioc.config` only** | Per-factory registration metadata in source files |
+
+**Factories must stay plain exports** (typically arrow functions). **Do not** attach `lifetime`, `scope`, `name`, `accessKey`, or other registration options to factory definitions. Those belong only in **`ioc.config.ts`** (`registrations`, `discovery.scanDirs[].scope`, groups, etc.). The generator does not look for a `{ factory, lifetime }` object pattern in your codebase.
+
+---
+
+## Mental model
+
+```
+Factory export → inferred contract → registration plan (config + conventions)
+  → generated manifest → Awilix container (your app)
+```
+
+You write small **factory functions**. The TypeScript program is analyzed at codegen time. The output manifest lists modules, registration keys, lifetimes, and defaults; the runtime applies that list to Awilix.
+
+---
+
+## Conventions
+
+### Factory shape
+
+Use a **function** (named `build…` by default) with an explicit or inferable return type. Dependencies are taken by **parameter destructuring** in PROXY mode; after registration, Awilix passes a cradle object whose properties match your generated keys.
+
+**Good — plain export, policy in `ioc.config`:**
+
+```ts
+import type { UserRepository } from "./UserRepository.js";
+import type { UserService } from "./UserService.js";
+import type { IocGeneratedCradle } from "../generated/ioc-registry.types.js";
+
+export const buildUserService = ({
+  userRepository,
+}: IocGeneratedCradle): UserService => {
+  return {
+    getUser: (id) => userRepository.findById(id),
+  };
+};
+```
+
+**Not documented or supported — registration data on the factory:**
+
+```ts
+// Do not do this. Lifetime, scope, and keys belong in ioc.config only.
+export const buildThing = {
+  lifetime: "scoped",
+  factory: () => {
+    /* … */
+  },
+};
+```
+
+Class-based constructor injection is out of scope for the intended workflow; you can use classes as *return values*, but the primary pattern is factories + PROXY cradle.
+
+### Key derivation
+
+For a factory `buildHttpClient` returning `MyService`:
+
+- **Contract** → `MyService` (return type symbol name)
+- **Implementation id** → `httpClient` (export name with prefix stripped, first char lowercased)
+- **Default access key** → `myService` (camel-cased contract name)
+
+Resolvers:
+
+- `container.resolve("myService")` — default implementation for that contract (unless overridden)
+- `container.resolve("httpClient")` — this implementation by registration key
+- `container.resolve("myServices")` — array when multiple implementations exist and a plural collection key applies
+
+Exact keys and lifetimes can be overridden in **`ioc.config`** (see below).
+
+---
+
+## `ioc.config` — single source of policy
+
+Put **`ioc.config.ts`** at the package root or under `src/` (see path resolution below). Export **`defineIocConfig({...})`** or a plain object (validation is the same).
+
+Only these top-level keys are allowed: `discovery`, `registrations`, `groups`. Unknown keys fail validation with `[ioc-config]`.
+
+### `discovery`
+
+| Field | Purpose |
+| --- | --- |
+| `scanDirs` | **Required.** Non-empty string, string array, or array of objects `{ path, importPrefix?, importMode?, scope? }` (see below). Paths are relative to the **package root** (parent of `src/` when config lives in `src/`), unless absolute. |
+| `includes` / `excludes` | Optional glob lists for discovery (defaults exist when omitted — tighten for your repo). |
+| `factoryPrefix` | Prefix for factory exports (default `build`). |
+| `generatedDir` | Where `ioc-manifest.ts` and `ioc-registry.types.ts` are written (default `generated`). |
+| `workspacePackageImportBases` | Optional `{ root, importBase }[]` so contract types emitted under a package root use a **public** bare specifier instead of deep relative paths. Each entry allows only `root` and `importBase`; both must be non-empty strings. |
+
+#### Discovery roots and `scanDirs`
+
+Each entry defines a **discovery root**: factories under that tree are discovered using the same TS program as your app. If you use **object** entries:
+
+- **`scope`** — default Awilix lifetime (`singleton` \| `scoped` \| `transient`) for factories whose source file resolves to this root. Per-implementation `registrations[Contract][impl].lifetime` wins. If one file could match multiple roots with different `scope` values, generation fails with an actionable error.
+- **`importPrefix` + `importMode`** — control how **generated imports** refer to factory modules. When `importPrefix` is set, `importMode` must be `root` (emit exactly that prefix) or `subpath` (emit `${importPrefix}/${pathFromScanRoot}`). `importPrefix` cannot be used without `importMode`. `importMode: "root"` without `importPrefix` is rejected.
+
+Relative imports in generated files are always written so consumers depend on **supported** paths (package root, aliases you configured) — not on private paths inside `node_modules`.
+
+### `registrations`
+
+Override **defaults**, **lifetimes**, **Awilix registration keys** (`name`), and **contract-level** settings.
+
+- Keys at `registrations[ContractName]` are **implementation names** from discovery (`buildX` → `x`), except the reserved **`$contract`** object for contract-level options.
+- Under each implementation, only **`name`**, **`lifetime`**, **`default`** are allowed.
+- Under **`$contract`**, only **`accessKey`** is allowed (non-empty string; cannot be `"$contract"`).
+
+**`accessKey`** — cradle / default-slot property for the contract when it should differ from the camel-cased contract name (e.g. singular `database` while the type is `Knex`).
+
+**`$contract` example:**
+
+```ts
+registrations: {
+  Knex: {
+    $contract: { accessKey: "database" },
+    pg: { default: true, lifetime: "singleton" },
+  },
+},
+```
+
+### Default implementation when multiple factories share a contract
+
+Order of precedence:
+
+1. **`default: true`** on exactly one implementation under `registrations[Contract]` (after merges).
+2. **Convention** — implementation whose registration key equals the camel-cased contract name (e.g. `myService` for `MyService`).
+3. **Single implementation** — if only one exists, it becomes the default.
+
+If more than one row is marked `default: true`, or the choice is otherwise ambiguous, generation fails with a clear error. **Defaults are configured only in `ioc.config`**, not in factory source files.
+
+### Groups
+
+Optional `groups` map names to `{ kind: "collection" \| "object", baseType: "SomeType" }` so multiple contracts assignable to `SomeType` appear as an array (`collection`) or object (`object`) on the cradle. Only `kind` and `baseType` are allowed per entry.
+
+---
+
+## Generated files
+
+| File | Role |
+| --- | --- |
+| `ioc-manifest.ts` | Imports factory modules and exports `iocManifest` consumed by `registerIocFromManifest` |
+| `ioc-registry.types.ts` | `IocGeneratedCradle` and related types for `container.resolve` |
+
+Treat them as build artifacts: **do not edit by hand**. Regenerate after changing factories or config.
+
+Imports in generated modules use types from the **`ioc-manifest`** package (`IocGeneratedContainerManifest`, etc.) — not deep imports into this repo’s `src/`.
+
+---
+
+## Quick start
+
+### 1. Configure
+
+```ts
+// src/ioc.config.ts
+import { defineIocConfig } from "ioc-manifest";
+
+export default defineIocConfig({
+  discovery: {
+    scanDirs: "src",
+    includes: ["**/*.{ts,tsx}"],
+    excludes: ["**/*.test.ts", "generated/**/*"],
+    factoryPrefix: "build",
+    generatedDir: "generated",
+  },
+});
+```
+
+### 2. Factories
+
+```ts
+import type { MyService } from "./MyService.js";
+
+export const buildHttpClient = (): MyService => {
+  return { doThing: () => "hello" };
+};
+```
+
+### 3. Generate
+
+Programmatic:
+
+```ts
+import { generateManifest } from "ioc-manifest";
+
+await generateManifest();
+```
+
+Or run your own script that calls `generateManifest({ iocConfigPath: "…" })` when needed. The repo uses `tsx` to run an internal generator script; consumers typically wire `generateManifest` into a `package.json` script.
+
+To debug the generator CLI with full stack traces, run with **`IOC_DEBUG=1`** (otherwise only the error message is printed to stderr).
+
+### 4. Bootstrap Awilix
+
+```ts
+import { createContainer, InjectionMode } from "awilix";
+import { registerIocFromManifest } from "ioc-manifest";
+import { iocManifest } from "./generated/ioc-manifest.js";
+import type { IocGeneratedCradle } from "./generated/ioc-registry.types.js";
+
+const container = createContainer<IocGeneratedCradle>({
+  injectionMode: InjectionMode.PROXY,
+});
+
+registerIocFromManifest(container, iocManifest);
+
+const svc = container.resolve("myService");
+```
+
+(Use your project’s actual `InjectionMode` import from `awilix`.)
+
+---
+
+## CLI: `ioc`
+
+The `ioc` binary is included for inspecting manifests and discovery. **Help** (exit **0**):
+
+```bash
+npx ioc
+npx ioc --help          # same as -h
+npx ioc -h
+npx ioc inspect --help
+npx ioc inspect -h
+```
+
+**Inspect** (same flags as always):
+
+```bash
+npx ioc inspect
+npx ioc inspect --discovery
+npx ioc inspect --config ./src/ioc.config.ts --project ./packages/api
+# Equivalent: ... -c ./src/ioc.config.ts
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--discovery` | Re-run factory discovery / registration planning; do **not** read the generated manifest. |
+| `--config PATH` , `-c PATH` | Explicit `ioc.config.ts` path. |
+| `--project PATH` | Directory used to resolve config (default: current directory). |
+
+- **`ioc inspect`** — loads the **generated** `ioc-manifest.ts` from disk (same path resolution as generation), prints a contract/implementation summary.
+- **`ioc inspect --discovery`** — re-runs discovery and registration planning without reading the manifest (good for “why didn’t this register?”).
+
+Malformed CLI usage (wrong command / unknown flag) exits **1** with a short message plus a usage hint; **help** and successful **inspect** exit **0**. Manifest or environment failures from Node loaders also exit **1** unless you set **`IOC_DEBUG=1`** for full stack traces.
+
+---
+
+## Larger example (repositories / services / routes)
+
+**`src/repos/buildUserRepository.ts`**
+
+```ts
+import type { UserRepository } from "./UserRepository.js";
+
+export const buildUserRepository = (): UserRepository => ({
+  findById: async () => undefined,
+});
+```
+
+**`src/services/buildUserService.ts`**
+
+```ts
+import type { UserRepository } from "../repos/UserRepository.js";
+import type { UserService } from "./UserService.js";
+import type { IocGeneratedCradle } from "../../generated/ioc-registry.types.js";
+
+export const buildUserService = ({
+  userRepository,
+}: IocGeneratedCradle): UserService => ({
+  get: (id) => userRepository.findById(id),
+});
+```
+
+**`ioc.config.ts`** (lifetimes and defaults here, not in the files above):
+
+```ts
+export default defineIocConfig({
+  discovery: { scanDirs: "src", generatedDir: "generated" },
+  registrations: {
+    UserService: {
+      userService: { default: true, lifetime: "scoped" },
+    },
+    UserRepository: {
+      userRepository: { lifetime: "singleton" },
+    },
+  },
+});
+```
+
+---
+
+## Error handling and exit codes
+
+- Messages for config problems are prefixed **`[ioc-config]`**.
+- Messages for discovery / planning / manifest issues are prefixed **`[ioc]`**.
+- CLI **`ioc`** exits **`0`** for **`-h` / `--help`** and successful **`inspect`**; exits **`1`** on invalid CLI usage or failed inspect/discovery runs.
+- Runtime resolution errors (`IocResolutionError`) include dependency chains for debugging.
+
+---
+
+## Pitfalls and troubleshooting
+
+- **Manifest out of date** — Regenerate after editing factories or `ioc.config`.
+- **Contract not discovered** — Return type must resolve to a named type; contract symbol must be in scope (imported or declared in the same file).
+- **Duplicate registration keys or implementation names** — Rename exports or use `registrations` `name` overrides so Awilix keys stay globally unique.
+- **Overlapping `scanDirs` with different `scope`** — Narrow roots or set lifetimes per implementation in `registrations`.
+- **`registrations` for unknown contracts** — Keys must match discovered contract type names; typos fail with a list of discovered contracts.
+- **Inspect shows `lifetimeSource: factory-config`** — That label means the lifetime came from **`ioc.config`**, not from a factory file (historical identifier in inspect output).
+
+---
+
+## Installation
+
+```bash
+npm install ioc-manifest
+```
+
+Peer expectation: your app already uses **Awilix** (this package lists `awilix` as a dependency for types/runtime alignment).
+
+---
+
+## Scripts (this repo)
+
+- **`npm run build`** — compile `src/` to `dist/`
+- **`npm test`** — unit and integration tests
+- **`npm run pack:dev`** — build and `npm pack` for a dry-run tarball
+
+Consumers normally depend on the published package; only `dist/`, `bin/`, `LICENSE`, and `README.md` are intended for the registry artifact.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/ioc.cjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const pkgRoot = path.join(__dirname, "..");
+const cliJs = path.join(pkgRoot, "dist", "cli", "ioc.js");
+
+const result = spawnSync(
+  process.execPath,
+  [cliJs, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+
+if (result.error) {
+  throw result.error;
+}
+process.exit(result.status === null ? 1 : result.status);

package/dist/cli/ioc.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=ioc.d.ts.map

package/dist/cli/ioc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ioc.d.ts","sourceRoot":"","sources":["../../src/cli/ioc.ts"],"names":[],"mappings":""}

package/dist/cli/ioc.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview `ioc` CLI: inspects a **generated** manifest on disk (`iocManifest` export).
+ *
+ * - `ioc inspect` — human-readable contract / implementation summary + manifest validation.
+ * - `ioc inspect --discovery` — re-runs source discovery (no manifest read) for drift analysis.
+ *
+ * Resolves config like generation (`tryLoadIocConfig`, optional `--config`), walking up from cwd
+ * (or `--project`) to find `ioc.config.ts` in a monorepo.
+ */
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { IOC_CLI_HELP_TEXT, parseIocCliArgv, } from "./parseIocCli.js";
+import { resolveIocConfigPath, resolveProjectRootFromIocConfigPath, tryLoadIocConfig, } from "../config/loadIocConfig.js";
+import { mergeManifestOptionsWithIocConfig, resolveManifestOptions, } from "../generator/manifestOptions.js";
+import { buildDiscoveryReport, buildInspectionReport, formatDiscoveryReport, formatInspectionReport, formatRegistrationLifetimeInspect, } from "../inspection/index.js";
+import { resolveDiscoveryManifestContext, runDiscoveryAnalysis, } from "../inspection/runDiscoveryAnalysis.js";
+const formatResolvedScanDir = (e) => {
+    let base = e.absPath;
+    if (e.scope !== undefined) {
+        base = `${base} [scope=${e.scope}]`;
+    }
+    if (e.importPrefix !== undefined && e.importMode !== undefined) {
+        return `${base} → ${e.importPrefix} (${e.importMode})`;
+    }
+    return base;
+};
+const logInspectContext = (cfgPath, scanDirs) => {
+    console.error(`[ioc inspect] resolved config: ${cfgPath}`);
+    console.error(`[ioc inspect] resolved discovery scanDirs: ${scanDirs.map(formatResolvedScanDir).join("; ")}`);
+};
+const loadGeneratedManifestModule = async (iocConfigPath, searchStartDir) => {
+    const searchStart = path.resolve(searchStartDir ?? process.cwd());
+    const cfgPath = resolveIocConfigPath(searchStart, iocConfigPath);
+    const config = await tryLoadIocConfig(cfgPath);
+    const projectRoot = config
+        ? resolveProjectRootFromIocConfigPath(cfgPath)
+        : searchStart;
+    const base = resolveManifestOptions({
+        paths: { projectRoot },
+    });
+    const options = config
+        ? mergeManifestOptionsWithIocConfig(base, config)
+        : base;
+    logInspectContext(cfgPath, options.paths.scanDirs);
+    const manifestPath = path.resolve(options.paths.manifestOutPath);
+    const main = (await import(pathToFileURL(manifestPath).href));
+    return main;
+};
+const main = async () => {
+    const parsed = parseIocCliArgv(process.argv);
+    if (parsed.kind === "help") {
+        console.log(IOC_CLI_HELP_TEXT.trimEnd());
+        return;
+    }
+    const cli = parsed.options;
+    const searchStart = path.resolve(cli.projectDir ?? process.cwd());
+    if (cli.discovery) {
+        const resolved = await resolveDiscoveryManifestContext({
+            iocConfigPath: cli.iocConfigPath,
+            searchStartDir: searchStart,
+        });
+        logInspectContext(resolved.cfgPath, resolved.options.paths.scanDirs);
+        const analysis = await runDiscoveryAnalysis({
+            reuseResolution: resolved,
+        });
+        const report = buildDiscoveryReport(analysis);
+        console.log(formatDiscoveryReport(report));
+        console.log("");
+        console.log(formatRegistrationLifetimeInspect(analysis.registrationPlan));
+        return;
+    }
+    const mainMod = await loadGeneratedManifestModule(cli.iocConfigPath, searchStart);
+    const report = buildInspectionReport(mainMod.iocManifest.contracts);
+    console.log(formatInspectionReport(report));
+};
+main().catch((error) => {
+    if (process.env.IOC_DEBUG === "1") {
+        console.error(error);
+    }
+    else {
+        console.error(error instanceof Error ? error.message : error);
+    }
+    process.exit(1);
+});
+//# sourceMappingURL=ioc.js.map

package/dist/cli/ioc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ioc.js","sourceRoot":"","sources":["../../src/cli/ioc.ts"],"names":[],"mappings":"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"}

package/dist/cli/parseIocCli.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Minimal argv parsing for the `ioc` CLI (`inspect` command and `-h/--help`).
+ */
+/** Printed for `-h`, `--help`, or bare `ioc` — successful exit 0 */
+export declare const IOC_CLI_HELP_TEXT = "ioc \u2014 inspect Awilix manifests produced by ioc-manifest\n\nUsage:\n  ioc [--help|-h]\n  ioc inspect [--discovery] [--config <path> | -c <path>] [--project <path>]\n  ioc inspect [--help|-h]\n\nCommands:\n  ioc inspect    Load generated ioc-manifest.ts (unless --discovery), print summary.\n\nOptions:\n  --discovery           Re-run discovery and registration planning; do not read manifest.\n  --config PATH   -c    Path to ioc.config.ts\n  --project PATH       Directory to resolve config from (default: cwd)\n\nErrors:\n  Set IOC_DEBUG=1 for stack traces alongside messages.\n";
+export type IocInspectCliOptions = {
+    iocConfigPath?: string;
+    projectDir?: string;
+    discovery: boolean;
+};
+export type ParseIocCliArgvResult = {
+    kind: "help";
+} | {
+    kind: "inspect";
+    options: IocInspectCliOptions;
+};
+/**
+ * Parses `process.argv`-style arrays (starts with executable and script paths).
+ */
+export declare const parseIocCliArgv: (argv: readonly string[]) => ParseIocCliArgvResult;
+//# sourceMappingURL=parseIocCli.d.ts.map

package/dist/cli/parseIocCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseIocCli.d.ts","sourceRoot":"","sources":["../../src/cli/parseIocCli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,6kBAiB7B,CAAC;AAQF,MAAM,MAAM,oBAAoB,GAAG;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAKvD;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,SAAS,MAAM,EAAE,KACtB,qBAsDF,CAAC"}

package/dist/cli/parseIocCli.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Minimal argv parsing for the `ioc` CLI (`inspect` command and `-h/--help`).
+ */
+/** Printed for `-h`, `--help`, or bare `ioc` — successful exit 0 */
+export const IOC_CLI_HELP_TEXT = `ioc — inspect Awilix manifests produced by ioc-manifest
+
+Usage:
+  ioc [--help|-h]
+  ioc inspect [--discovery] [--config <path> | -c <path>] [--project <path>]
+  ioc inspect [--help|-h]
+
+Commands:
+  ioc inspect    Load generated ioc-manifest.ts (unless --discovery), print summary.
+
+Options:
+  --discovery           Re-run discovery and registration planning; do not read manifest.
+  --config PATH   -c    Path to ioc.config.ts
+  --project PATH       Directory to resolve config from (default: cwd)
+
+Errors:
+  Set IOC_DEBUG=1 for stack traces alongside messages.
+`;
+const isHelpFlag = (s) => s === "--help" || s === "-h";
+const conciseUsageTail = () => '\nUsage: ioc (--help|-h) | ioc inspect [--discovery] [--config <path>|-c <path>] [--project <path>] | ioc inspect (--help|-h)';
+const cliParseError = (detail) => new Error(`${detail}${conciseUsageTail()}`);
+/**
+ * Parses `process.argv`-style arrays (starts with executable and script paths).
+ */
+export const parseIocCliArgv = (argv) => {
+    const args = argv.slice(2);
+    if (args.length === 0 || (args.length === 1 && isHelpFlag(args[0] ?? ""))) {
+        return { kind: "help" };
+    }
+    if (args[0] === "inspect" && args.slice(1).some(isHelpFlag)) {
+        return { kind: "help" };
+    }
+    const command = args[0];
+    if (command !== "inspect") {
+        throw cliParseError(`Unknown command ${JSON.stringify(command)}. Supported: inspect.`);
+    }
+    let iocConfigPath;
+    let projectDir;
+    let discovery = false;
+    for (let i = 1; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === undefined) {
+            break;
+        }
+        if (a === "--discovery") {
+            discovery = true;
+            continue;
+        }
+        if ((a === "--config" || a === "-c") && args[i + 1]) {
+            iocConfigPath = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--project" && args[i + 1]) {
+            projectDir = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a.startsWith("-")) {
+            throw cliParseError(`Unknown flag ${JSON.stringify(a)}.`);
+        }
+    }
+    return {
+        kind: "inspect",
+        options: {
+            ...(iocConfigPath !== undefined ? { iocConfigPath } : {}),
+            ...(projectDir !== undefined ? { projectDir } : {}),
+            discovery,
+        },
+    };
+};
+//# sourceMappingURL=parseIocCli.js.map

package/dist/cli/parseIocCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseIocCli.js","sourceRoot":"","sources":["../../src/cli/parseIocCli.ts"],"names":[],"mappings":"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"}