typespun-codegen 0.0.4 → 0.0.8

package/README.md

@@ -4,92 +4,215 @@
 
 # typespun-codegen
 
-The TypeScript analyzer and `typespun` CLI that generate deterministic
-configuration loaders.
+The TypeScript compiler and `typespun` command-line tool for
+[Typespun](https://github.com/omkar273/typespun). It initializes a project,
+analyzes one TypeScript configuration declaration, and emits a deterministic
+loader for the separate [`typespun`](https://www.npmjs.com/package/typespun)
+runtime package.
 
 [![npm](https://img.shields.io/npm/v/typespun-codegen.svg)](https://www.npmjs.com/package/typespun-codegen)
 [![license](https://img.shields.io/npm/l/typespun-codegen.svg)](LICENSE)
 
-Install this package as a development dependency beside the runtime:
+The package name is `typespun-codegen`; the executable it provides is
+`typespun`. There is no supported programmatic compiler API in version 0.1.
+
+## Start with `init`
+
+Run initialization from the root of an existing TypeScript project. The
+project must already contain a valid `package.json` and a usable
+`tsconfig.json`.
+
+Install the runtime and generator, then invoke the local executable:
 
 ```sh
 bun add typespun
 bun add --dev typespun-codegen
+bun typespun init --env-prefix APP
 ```
 
-The npm package is named `typespun-codegen`; the executable it installs is named
-`typespun`. The package root intentionally has no programmatic compiler API in
-version 0.1.
+Using npm:
 
-## Generate your first loader
+```sh
+npm install typespun
+npm install --save-dev typespun-codegen
+npx typespun init --env-prefix APP
+```
 
-Add local scripts:
+The default initialization creates, when missing:
 
-```json
-{
-  "scripts": {
-    "config:generate": "typespun generate",
-    "config:check": "typespun check"
-  }
-}
+- `src/config.ts`, containing an `@typespun` interface with a numeric `port`
+  field;
+- `config.yaml`, containing `port: 3000` for a new starter schema or an empty
+  object when adopting an existing schema;
+- `typespun.json`, pointing from `src/config.ts` to
+  `src/generated/typespun.ts`, with commented examples for every optional
+  setting and allowed policy value; and
+- `config:generate` and `config:check` scripts in `package.json`.
+
+When both `typespun` and `typespun-codegen` resolve from the project or an
+ancestor `node_modules`, `init` also creates the first generated loader at
+`src/generated/typespun.ts`.
+
+You can scaffold before installing either package with a package-qualified
+zero-install command:
+
+```sh
+bunx --package typespun-codegen typespun init
+npx --package=typespun-codegen typespun init
+```
+
+In that case, `init` creates the project files and exits successfully but does
+not generate output, because the dependencies are not installed in the project.
+It prints install commands for the manager selected by `packageManager` or a
+recognized lockfile, falling back to npm. It never runs an installer. Install
+both packages and generate:
+
+```sh
+bun add typespun
+bun add --dev typespun-codegen
+bun run config:generate
 ```
 
-Declare one exported root in `src/config.ts`:
+The installed `bun typespun init` and `npx typespun init` flows are shorter and
+generate immediately because both dependencies are already present.
+
+`init` preserves existing scripts and initialized files. Re-running it is
+byte-stable. It refuses conflicting options, input/output aliases, and an
+existing output file or symlink that is not recognizable as Typespun-generated;
+there is no force-overwrite option.
+
+## Customize initialization
+
+```text
+typespun init [--style interface|class] [--input <path>]
+              [--output <path>] [--env-prefix <prefix>]
+```
+
+| Option                     | Effect                                                                      |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `--style interface\|class` | Creates an annotated interface (the default) or a decorated class.          |
+| `--input <path>`           | Selects the schema path. It must end in `.ts`, `.mts`, or `.cts`.           |
+| `--output <path>`          | Selects the generated module path. It must end in `.ts`, `.mts`, or `.cts`. |
+| `--env-prefix <prefix>`    | Stores the environment-variable prefix in `typespun.json`.                  |
+
+For example:
+
+```sh
+bun typespun init \
+  --style class \
+  --input config/app.mts \
+  --output config/generated.mts \
+  --env-prefix APP
+```
+
+Without explicit paths, `init` adopts one existing conventional schema at
+`src/config.ts`, `src/config.mts`, or `src/config.cts`; otherwise it creates
+`src/config.ts`. The output defaults to `src/generated/typespun` with the same
+extension as the input. Multiple conventional schemas require `--input`.
+
+## Use the generated loader
+
+After the default initialization, expand `src/config.ts` into your application
+schema:
 
 ```ts
 /** @typespun */
 export interface AppConfig {
   server: { host: string; port: number };
   /** @secret */
-  token: string;
+  databaseUrl: string;
 }
 ```
 
-Then generate:
+Regenerate and import the generated module:
 
 ```sh
 bun run config:generate
-# Generated src/generated/typespun.ts.
 ```
 
-The generated module exports the declaration-backed `Config` type and a
-`loadConfig()` function. Commit the file, then keep it current in CI:
+```ts
+import { loadConfig } from './generated/typespun.js';
+
+const config = loadConfig({
+  source: {
+    SERVER_HOST: '127.0.0.1',
+    SERVER_PORT: '3000',
+    DATABASE_URL: 'postgres://localhost/example',
+  },
+});
+
+console.log(config.server.port); // 3000, typed as number
+```
+
+The generated module exports the declaration-backed `Config` type and
+`loadConfig()`. Commit that module: output is deterministic for the same
+declaration, resolved configuration, defaults, and generator version.
+
+## Generate and check
+
+Initialization adds these scripts:
+
+```json
+{
+  "scripts": {
+    "config:generate": "typespun generate",
+    "config:check": "typespun check"
+  }
+}
+```
+
+Use them locally and in CI:
 
 ```sh
+bun run config:generate
 bun run config:check
 ```
 
-## CLI
+The underlying commands are:
 
 ```text
-typespun init [--style interface|class] [--input <path>]
-              [--output <path>] [--env-prefix <prefix>]
 typespun generate [--config <path>]
 typespun check [--config <path>]
 ```
 
-- `init` creates missing schema/config files and package scripts without
-  overwriting application-owned output.
-- `generate` statically analyzes TypeScript, validates optional JSON/YAML
-  defaults, and atomically writes canonical output when it changes.
-- `check` performs the same analysis without writing and exits nonzero for
-  missing or stale output.
-
-With no explicit configuration, the CLI expects exactly one conventional
-`src/config.ts`, `.mts`, or `.cts` file and discovers at most one conventional
-JSON/YAML defaults file. Use `typespun.json` for explicit paths, an environment
-prefix, defaults policies, and secret-default policy.
-
-## Why a separate package?
-
-Generation uses the TypeScript compiler and YAML parser during development.
-Keeping them in `typespun-codegen` lets applications depend on the smaller
-`typespun` runtime while CI and schema authors retain the compiler. Generated
-output is deterministic for the same declaration, settings, defaults, and
-generator version.
-
-Read the [getting-started guide](https://github.com/omkar273/typespun/blob/main/docs/getting-started.md),
-[CLI reference](https://github.com/omkar273/typespun/blob/main/docs/api/cli.md),
-and [`typespun.json` reference](https://github.com/omkar273/typespun/blob/main/docs/reference/configuration.md).
+`generate` reads `typespun.json`, the schema, the resolved `tsconfig.json`, and
+an optional JSON or YAML defaults file. It writes atomically only when the
+canonical output differs, reporting either `Generated` or `Unchanged`.
+
+`check` performs the same analysis but never writes. It exits nonzero when the
+output is missing or stale and tells you to run `typespun generate`. Pass
+`--config <path>` once to either command to use a configuration file other than
+`typespun.json`; relative paths inside it resolve from that file's directory.
+
+## Errors and exit status
+
+- Exit `0`: help or success. For `init`, this also includes the safe
+  dependency-installation handoff described above.
+- Exit `1`: schema, defaults, output, or stale-output failure.
+- Exit `2`: invalid CLI usage or unusable project/TypeScript configuration.
+
+Warnings and diagnostics are written to stderr. Secret-default warnings identify
+the field path without printing the received secret value. `generate` and
+`check` accept only `--config`; unknown options, duplicate options, and missing
+option values are usage errors.
+
+Run `bun typespun --help`, `bun typespun generate --help`, or
+`bun typespun check --help` for the built-in command summary.
+
+## Package role
+
+`typespun-codegen` carries the TypeScript compiler and YAML parser needed while
+authoring and checking configuration. Applications import the generated loader,
+which delegates runtime loading and validation to `typespun`; they do not import
+compiler internals from this package. Keeping code generation separate lets the
+compiler remain a development dependency.
+
+Further documentation:
+
+- [Getting started](https://github.com/omkar273/typespun/blob/main/docs/getting-started.md)
+- [CLI reference](https://github.com/omkar273/typespun/blob/main/docs/api/cli.md)
+- [`typespun.json` reference](https://github.com/omkar273/typespun/blob/main/docs/reference/configuration.md)
+- [Declaration syntax](https://github.com/omkar273/typespun/blob/main/docs/concepts/declarations.md)
+- [Generated loader API](https://github.com/omkar273/typespun/blob/main/docs/api/generated-loader.md)
 
 MIT © Typespun contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespun-codegen",
-  "version": "0.0.4",
+  "version": "0.0.8",
   "description": "TypeScript schema analyzer, generator, and CLI for Typespun",
   "license": "MIT",
   "type": "module",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "typescript": "6.0.3",
-    "typespun": "^0.0.4",
+    "typespun": "^0.0.8",
     "yaml": "2.9.1"
   }
 }

package/dist/analyzer/analyze.d.ts

@@ -1,4 +0,0 @@
-import ts from 'typescript';
-import type { AnalyzeResult } from '../contracts.js';
-export declare function analyzeProgram(program: ts.Program, inputPath: string, envPrefix?: string): AnalyzeResult;
-//# sourceMappingURL=analyze.d.ts.map

package/dist/analyzer/analyze.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/analyzer/analyze.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B,OAAO,KAAK,EACV,aAAa,EAId,MAAM,iBAAiB,CAAC;AASzB,wBAAgB,cAAc,CAC5B,OAAO,EAAE,EAAE,CAAC,OAAO,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,SAAK,GACb,aAAa,CAqmBf"}