@kurotako/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,435 @@
+import { IrIssue, IR, SourceIR } from '@kurotako/ir';
+
+/**
+ * `TakoError` hierarchy. Every failure in the pipeline is fail-fast and carries
+ * enough context to name the offending source or generator. The CLI maps any
+ * `TakoError` to a formatted message + non-zero exit; a non-`TakoError` throw is
+ * a bug and surfaces as a stack trace.
+ *
+ * Error table: `backlog/features/core-pipeline/technical.md` §Error model.
+ */
+
+declare class TakoError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class NamespaceMismatchError extends TakoError {
+    readonly namespace: string;
+    readonly returned: string;
+    constructor(namespace: string, returned: string);
+}
+declare class IrValidationError extends TakoError {
+    readonly issues: IrIssue[];
+    readonly namespace?: string;
+    constructor(issues: IrIssue[], namespace?: string);
+}
+declare class DuplicateNamespaceError extends TakoError {
+    readonly namespace: string;
+    constructor(namespace: string);
+}
+declare class UnknownDependencyError extends TakoError {
+    readonly generator: string;
+    readonly missing: string;
+    constructor(generator: string, missing: string);
+}
+declare class InvalidDependencyError extends TakoError {
+    readonly generator: string;
+    readonly dependency: string;
+    constructor(generator: string, dependency: string);
+}
+declare class DependencyCycleError extends TakoError {
+    readonly cycle: string[];
+    constructor(cycle: string[]);
+}
+declare class OutputCollisionError extends TakoError {
+    readonly path: string;
+    readonly generators: [string, string];
+    constructor(path: string, generators: [string, string], hint?: string);
+}
+declare class InvalidOutputPathError extends TakoError {
+    readonly path: string;
+    readonly generator: string;
+    constructor(path: string, generator: string);
+}
+declare class UnsupportedOutputModeError extends TakoError {
+    readonly mode: string;
+    constructor(mode: string);
+}
+declare class OutputPeerConflictError extends TakoError {
+    readonly namespace: string;
+    readonly package: string;
+    readonly ranges: string[];
+    readonly generators: string[];
+    constructor(namespace: string, pkg: string, ranges: string[], generators: string[]);
+}
+declare class PackageBuildError extends TakoError {
+    readonly namespace: string;
+    constructor(namespace: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class MissingPackageWorkspaceFilesError extends TakoError {
+    readonly workspaceRoot: string;
+    readonly missing: string[];
+    constructor(workspaceRoot: string, missing: string[]);
+}
+declare class OutputNotGeneratedError extends TakoError {
+    readonly path: string;
+    constructor(path: string);
+}
+declare class PackageInstallError extends TakoError {
+    readonly pm: string;
+    constructor(pm: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class DriverError extends TakoError {
+    readonly role: 'parser' | 'generator';
+    readonly driverName: string;
+    readonly namespace?: string;
+    constructor(role: 'parser' | 'generator', driverName: string, options?: {
+        cause?: unknown;
+        namespace?: string;
+    });
+}
+declare class HookError extends TakoError {
+    readonly hook: string;
+    constructor(hook: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * The Writer seam. `run()` aggregates a virtual tree and hands it to the writer
+ * selected by `output.mode`. Mode A (`directoryWriter`) and mode B
+ * (`packageWriter`) both live in this directory.
+ */
+
+interface WriteInput {
+    files: VirtualFile[];
+    output: OutputConfig;
+    /**
+     * Generator short name -> artifact. Mode B reads `peerDependencies` from it;
+     * mode A ignores it. Optional so a bare `directoryWriter.write({ files,
+     * output })` call still type-checks.
+     */
+    artifacts?: Record<string, GeneratorArtifact>;
+    /** Mode B logs the manual install command here when no pm is resolved. */
+    logger?: Logger;
+}
+/**
+ * One file a `write()` would emit, resolved to its absolute on-disk path with
+ * the exact bytes it would serialise (banner already applied by the caller, as
+ * for `write`). `plan()` computes these without any disk I/O; `write()` is
+ * `plan()` plus materialisation, so the two never drift.
+ */
+interface PlannedFile {
+    /** Absolute. */
+    path: string;
+    content: string;
+}
+interface Writer {
+    write(input: WriteInput): Promise<string[]>;
+    /**
+     * Same layout as `write()`, no disk I/O: the exact set of files `write()`
+     * would produce (mode B: `<pkgDir>/src/…` remap + synthesized manifest, but
+     * no `dist/`, no `pm install`).
+     */
+    plan(input: WriteInput): Promise<PlannedFile[]>;
+}
+
+/**
+ * Public type surface of `@kurotako/core`. Runtime-code free: every export here
+ * is a type or an interface. The orchestrator (`run.ts`), the error hierarchy
+ * (`errors.ts`) and the writer seam (`writer/`) build on these.
+ *
+ * Product decisions: `backlog/features/core-pipeline/technical.md`. The IR types
+ * come from `@kurotako/ir`; core owns config, driver contracts, contexts,
+ * artifacts, hooks, the logger and the `run()` option / result shapes.
+ */
+
+/**
+ * Structured logger. Core ships a no-op default (`logger.ts`); the CLI injects a
+ * real one. Contexts receive a child logger tagged with the namespace /
+ * generator name.
+ */
+interface Logger {
+    debug(msg: string, meta?: unknown): void;
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error(msg: string, meta?: unknown): void;
+}
+/**
+ * The already-resolved, already-validated configuration `run()` consumes.
+ * Construction, file format and driver-option validation belong to
+ * `@kurotako/config`; core only declares the shape it needs.
+ */
+interface ResolvedConfig {
+    /**
+     * Absolute path of the directory holding the config file. Anchor for relative
+     * output paths and for `ParseContext.cwd`.
+     */
+    rootDir: string;
+    /** Key === namespace (ADR-0003). */
+    sources: Record<string, SourceConfig>;
+    /** Key === `Generator.name` (short name). */
+    generators: Record<string, GeneratorConfig>;
+    outputs: OutputConfig[];
+    hooks?: Hooks;
+}
+interface SourceConfig {
+    parser: Parser;
+    /** Opaque seam kept for `--emit` / debugging; core does not read it. */
+    options?: unknown;
+}
+interface GeneratorConfig {
+    generator: Generator;
+    /** Opaque seam kept for `--emit` / debugging; core does not read it. */
+    options?: unknown;
+    /** Restrict this generator to a subset of namespaces; default = all. */
+    namespaces?: string[];
+}
+interface OutputConfig {
+    /** Default `'dir'`. */
+    mode?: 'dir' | 'package';
+    /** Mode A; resolved absolute by config-system. */
+    dir?: string;
+    /** Mode B. */
+    packagesDir?: string;
+    /** Mode B (required for mode B — config-system enforces). */
+    scope?: string;
+    /** Mode B, optional — consumed by output-modes. */
+    packageManager?: 'bun' | 'pnpm' | 'yarn' | 'npm';
+    /** Restrict this destination to a subset of `config.generators`; default = all. */
+    generators?: string[];
+}
+interface Parser {
+    name: string;
+    parse(ctx: ParseContext): Promise<SourceIR> | SourceIR;
+    /**
+     * Metadata for `cli --watch` — the set of paths a watcher should observe.
+     * `run()` never calls it.
+     */
+    watchPaths?(ctx: ParseContext): string[] | Promise<string[]>;
+    /**
+     * The directory this source is anchored at, for toolchain-dependency
+     * resolution. Already curried (options bound). `run()` calls it before
+     * `parse()` and passes the result as `ParseContext.anchorDir`. Return
+     * `undefined` (or omit the hook) to anchor on `rootDir`. Must not throw for an
+     * ordinary "not found" case — a bad path is the parser's problem to surface
+     * during `parse()`.
+     */
+    anchor?(rootDir: string): string | undefined | Promise<string | undefined>;
+}
+interface ParseContext {
+    namespace: string;
+    /** Absolute; the config-file directory. Base for `options.schema` and output paths. */
+    cwd: string;
+    /**
+     * Absolute; the directory this source is anchored at — where its schema lives.
+     * A parser resolves the source's own toolchain dependencies (`@prisma/internals`
+     * and equivalents) from here, letting Node walk up `node_modules` to `cwd` and
+     * beyond. Absent (⇒ treat as `cwd`) when the parser declares no `anchor` hook.
+     */
+    anchorDir?: string;
+    logger: Logger;
+}
+interface Generator {
+    name: string;
+    /** Hard dependency: absent from the config => error. Constrains order. */
+    dependsOn?: string[];
+    /** Optional dependency: used if present, else ignored. Constrains order. */
+    optionalDependsOn?: string[];
+    generate(ctx: GenerateContext): Promise<GenOutput> | GenOutput;
+}
+interface GenerateContext {
+    /** Namespace-filtered deep clone of the merged IR. */
+    ir: IR;
+    /** Only declared deps (`dependsOn ∪ optionalDependsOn`) that actually ran. */
+    dependencies: Record<string, GeneratorArtifact>;
+    logger: Logger;
+}
+interface GenOutput {
+    files: VirtualFile[];
+    artifact: GeneratorArtifact;
+}
+interface VirtualFile {
+    /**
+     * POSIX, relative to the output root. The generator owns the
+     * `<namespace>/<generatorName>/` prefix (one sub-tree per generator; core
+     * synthesizes `<namespace>/index.ts`).
+     */
+    path: string;
+    content: string;
+}
+interface GeneratorArtifact {
+    /** Key === `${namespace}.${entity}`. */
+    entities: Record<string, EntitySymbols>;
+    /**
+     * Package -> semver range the emitted code imports. Mode B: core aggregates
+     * per namespace (output-modes).
+     */
+    peerDependencies?: Record<string, string>;
+    /** Generator-defined; the consumer casts to the producer's published type. */
+    extra?: unknown;
+}
+interface EntitySymbols {
+    /** Module specifier a sibling generator imports from. */
+    module: string;
+    /** Role -> exported identifier, e.g. `{ schema: "UserSchema", type: "User" }`. */
+    symbols: Record<string, string>;
+}
+interface Hooks {
+    afterEmit?(ctx: AfterEmitContext): Promise<void> | void;
+}
+interface AfterEmitContext {
+    /** Absolute; the directory the Writer just populated. */
+    outputDir: string;
+    /** Absolute paths actually written, sorted. */
+    files: string[];
+    logger: Logger;
+}
+interface RunOptions {
+    /** Default: no-op. */
+    logger?: Logger;
+    /** Cooperative cancellation between steps (watch mode). */
+    signal?: AbortSignal;
+    /** Default `true`; `false` => run everything, skip the Writer. */
+    write?: boolean;
+    /**
+     * Default `false`. `true` => run everything up to (not including) emission,
+     * then ask each output's Writer for the files a `generate` would write
+     * (absolute path + exact bytes) via `Writer.plan()`, returned as
+     * `RunResult.plan`. No disk I/O, `afterEmit` does not fire. Wins over
+     * `write`: `{ plan: true, write: true }` still writes nothing.
+     */
+    plan?: boolean;
+}
+interface RunResult {
+    /** Merged, validated IR (for `--emit-ir`, drift-guard). */
+    ir: IR;
+    /** Generator short names, in execution order. */
+    order: string[];
+    /** Aggregated virtual tree, sorted by path. */
+    files: VirtualFile[];
+    /** Generator short name -> its artifact. */
+    artifacts: Record<string, GeneratorArtifact>;
+    /** One entry per `config.outputs[]`, in order; `[]` when `write: false`. */
+    written: {
+        output: OutputConfig;
+        files: string[];
+    }[];
+    /**
+     * Present iff `opts.plan === true`: the files a fresh `generate` would write
+     * across every `config.outputs[]` entry, absolute paths, sorted by `path`.
+     * Basis of `tako check` (drift-guard).
+     */
+    plan?: PlannedFile[];
+}
+
+/**
+ * The no-op `Logger` default and a `childLogger` wrapper that merges a
+ * `{ namespace }` / `{ generator }` tag into every call's `meta`.
+ */
+
+/** Default logger: swallows everything. The CLI injects a real one. */
+declare const noopLogger: Logger;
+/**
+ * Wrap `base` so every message carries `prefixMeta` (e.g. `{ namespace }` or
+ * `{ generator }`) merged into its `meta` argument.
+ */
+declare function childLogger(base: Logger, prefixMeta: Record<string, unknown>): Logger;
+
+/**
+ * `run()` — the single public entry point. Sequential, fail-fast: parse ->
+ * merge -> order -> generate -> collect -> write -> afterEmit. `opts.signal` is
+ * checked at each step boundary; `opts.write === false` runs everything but
+ * skips the Writer (basis of `--dry-run`). `opts.plan === true` also stops
+ * before emission but calls `Writer.plan()` per output and returns the planned
+ * tree as `RunResult.plan` — no disk I/O, no `afterEmit` (basis of `tako check`
+ * / drift-guard); it wins over `opts.write`.
+ *
+ * Steps 5b/5c (synthesize root barrels, apply banner) are added to this file by
+ * the output-modes feature; they are not part of the core-pipeline tasks.
+ */
+
+declare function run(config: ResolvedConfig, opts?: RunOptions): Promise<RunResult>;
+
+/**
+ * The generated-file banner. `run.ts` calls `applyBanner` once, after barrel
+ * synthesis and before the writer, so every `.ts` file — generator output and
+ * synthesized barrels alike — carries the marker. `.json` files have no comment
+ * syntax: `packageWriter` sets a `"//"` key on `package.json` instead.
+ *
+ * Design: `backlog/features/output-modes/technical.md` §Banner.
+ */
+
+declare const BANNER = "// Generated by tako. Do not edit.\n";
+declare const GITATTRIBUTES = "* linguist-generated=true\n";
+/**
+ * Prepend `BANNER` to every `.ts` / `.tsx` file (and `tsconfig.json`). Pure,
+ * and idempotent-safe: a file that already starts with the banner is left
+ * untouched. `package.json` and other `.json` files pass through unchanged.
+ */
+declare function applyBanner(files: VirtualFile[]): VirtualFile[];
+
+/**
+ * Root-barrel synthesis. Each generator owns `<namespace>/<generatorName>/` and
+ * emits its own barrel there; `tako` synthesizes `<namespace>/index.ts` so
+ * `import … from '<scope>/<namespace>'` resolves regardless of how many
+ * generators ran. Mode-independent — mode A and mode B both get the barrel.
+ *
+ * Design: `backlog/features/output-modes/technical.md` §New orchestration step.
+ */
+
+/**
+ * One `VirtualFile { path: '<ns>/index.ts' }` per namespace present in `files`,
+ * its content one sorted `export * from './<generatorName>';` line per
+ * generator that contributed a file under `<ns>/<generatorName>/`. A
+ * single-generator namespace still gets a barrel.
+ *
+ * When `artifactsByGenerator` is supplied, `logger?.warn(...)` fires if the same
+ * exported identifier appears in two contributing artifacts for one namespace
+ * (an ambiguous star re-export TypeScript/ESM silently drops). Never throws.
+ */
+declare function synthesizeRootBarrels(files: VirtualFile[], artifactsByGenerator?: Record<string, GeneratorArtifact>, logger?: Logger): VirtualFile[];
+
+declare const directoryWriter: Writer;
+
+declare const packageWriter: Writer;
+
+declare function selectWriter(output: OutputConfig): Writer;
+
+/**
+ * Namespace -> (package -> semver range). Per namespace, union the
+ * `peerDependencies` of every generator that emitted a file under
+ * `<namespace>/<generatorName>/`. Identical ranges de-duplicate; the same
+ * package with two different ranges from two generators throws
+ * `OutputPeerConflictError` (fail-fast). Namespace and package keys are sorted.
+ */
+declare function collectPeerDependencies(artifactsByGenerator: Record<string, GeneratorArtifact>, files: VirtualFile[]): Record<string, Record<string, string>>;
+
+type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm';
+/**
+ * Resolve the package manager to run `install` with, in order:
+ *   1. `configured` (from `output.packageManager`) — used verbatim;
+ *   2. lockfile walk-up from `startDir` (`bun.lock` / `bun.lockb` -> `bun`,
+ *      `pnpm-lock.yaml` -> `pnpm`, `yarn.lock` -> `yarn`,
+ *      `package-lock.json` -> `npm`), stopping at a `.git` marker or the root;
+ *   3. nearest ancestor `package.json` `packageManager` field (name before `@`);
+ *   4. `null` — do not guess.
+ */
+declare function resolvePackageManager(opts: {
+    configured?: PackageManager;
+    startDir: string;
+}): PackageManager | null;
+/**
+ * Run `<pm> install` in `cwd`. No `--frozen-lockfile` — the generated packages
+ * are new, the lockfile must change. A non-zero exit becomes
+ * `PackageInstallError { pm, cause }`.
+ */
+declare function runInstall(pm: PackageManager, cwd: string): Promise<void>;
+
+export { type AfterEmitContext, BANNER, DependencyCycleError, DriverError, DuplicateNamespaceError, type EntitySymbols, GITATTRIBUTES, type GenOutput, type GenerateContext, type Generator, type GeneratorArtifact, type GeneratorConfig, HookError, type Hooks, InvalidDependencyError, InvalidOutputPathError, IrValidationError, type Logger, MissingPackageWorkspaceFilesError, NamespaceMismatchError, OutputCollisionError, type OutputConfig, OutputNotGeneratedError, OutputPeerConflictError, PackageBuildError, PackageInstallError, type PackageManager, type ParseContext, type Parser, type PlannedFile, type ResolvedConfig, type RunOptions, type RunResult, type SourceConfig, TakoError, UnknownDependencyError, UnsupportedOutputModeError, type VirtualFile, type WriteInput, type Writer, applyBanner, childLogger, collectPeerDependencies, directoryWriter, noopLogger, packageWriter, resolvePackageManager, run, runInstall, selectWriter, synthesizeRootBarrels };