@aid-framework/cli 0.0.0 → 0.1.48

package/dist/commands/ingest.js

@@ -0,0 +1,238 @@
+/**
+ * `aid ingest` -- run the generated ingest entry point for a retriever's corpus.
+ *
+ * **What this shells out to, and why.** Indexing is a batch job, not a request, so the
+ * generator emits one runnable module per declared retriever at
+ * `app/generated/retrieval/ingest/<id>.py`, with a `main()` that chunks, embeds and writes
+ * the corpus. That module is the interface: it already knows the chunking and the store the
+ * spec declared, and re-deriving either here would be a second implementation of the
+ * runtime's rules. So the command runs `python -m app.generated.retrieval.ingest.<id>` from
+ * the project root, which is also what a person would type by hand.
+ *
+ * **The flag shape is a usage error, not a project verdict.** `--retriever` and `--all` are
+ * the two ways to say what to ingest; passing both, or neither, is a mistake in the
+ * invocation and exits 2 before the spec is even read. An id the spec does not declare is
+ * the same kind of mistake, and its message names the ids that do exist -- a typo should
+ * not require opening the spec.
+ *
+ * **A missing module is a failure, not a usage error.** `--retriever handbook` in a project
+ * that has never been generated is a well-formed command that cannot do its job; it exits 1
+ * and points at `aid gen`. Exit 2 would tell a script that it passed the wrong arguments,
+ * which is false and hides the one action that fixes it.
+ *
+ * **`--dry-run` is forwarded, not implemented here.** The generated module already grows
+ * its own `--dry-run`, which applies the chunker and reports the counts a real run would
+ * write without opening a store or calling an embedder. Answering the same question in
+ * the CLI would mean re-chunking the corpus, and a second dry run that drifted from the
+ * one the module performs is worse than no dry run at all.
+ *
+ * **Idempotence is the runtime's, not a rescan this command performs.** A chunk id is a
+ * content hash, and the store upserts on it, so a second run over unchanged documents
+ * replaces rather than appends. The CLI adds no diffing of its own: it would have to
+ * reimplement the chunker to know what changed.
+ */
+import { existsSync } from 'node:fs';
+import { sortDiagnostics } from '@aid-framework/spec';
+import { CLI_DIAGNOSTIC_CODES, cliError, cliWarning } from '../diagnostics.js';
+import { EXIT_FAILURE, EXIT_OK, EXIT_USAGE } from '../exit.js';
+import { outcome } from '../output.js';
+import { absolutePath } from '../paths.js';
+import { lowerSpec, readSpec } from '../pipeline.js';
+import { discoverInterpreter, INTERPRETERS, interpreterCommand, invoke } from '../python.js';
+import { resolveTarget, unknownTargetDiagnostic } from '../targets.js';
+/** `Declared retrievers: a, b.`, or the truth when there are none. */
+function declaredHint(ids) {
+    return ids.length > 0
+        ? `Declared retrievers: ${ids.join(', ')}.`
+        : 'The spec declares no retrievers.';
+}
+/**
+ * The human rendering. One retriever prints the module's own report; several get a heading
+ * each, because two unlabelled "wrote N chunks" lines cannot be told apart.
+ */
+function render(results, stdout) {
+    const blocks = results.map((result, index) => {
+        const body = stdout[index]?.trimEnd() ?? '';
+        if (results.length === 1)
+            return body;
+        return [`==> ${result.retriever}`, body].filter((line) => line !== '').join('\n');
+    });
+    return blocks.filter((block) => block !== '').join('\n');
+}
+/** The `--retriever`/`--all` shape, which is decided without reading the project. */
+function checkFlagShape(options) {
+    if (options.retriever !== undefined && options.all) {
+        return cliError({
+            code: CLI_DIAGNOSTIC_CODES.retrieverConflict,
+            message: '`--retriever` and `--all` say two different things; pass one of them.',
+            hint: 'Use `--retriever <id>` for one retriever, or `--all` for every retriever the spec declares.',
+        });
+    }
+    if (options.retriever === undefined && !options.all) {
+        return cliError({
+            code: CLI_DIAGNOSTIC_CODES.retrieverRequired,
+            message: '`aid ingest` needs `--retriever <id>` or `--all`.',
+            hint: 'Use `--all` to ingest every retriever the spec declares.',
+        });
+    }
+    return undefined;
+}
+export function ingest(context, options) {
+    const command = 'ingest';
+    const target = resolveTarget(options.target);
+    if (target === undefined) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            diagnostics: [unknownTargetDiagnostic(options.target ?? '')],
+        });
+    }
+    // The flag shape is judged before the project is touched: an invocation that asks two
+    // contradictory things is wrong whether or not the spec happens to be readable, and
+    // reporting a spec problem instead would bury the actual mistake.
+    const malformed = checkFlagShape(options);
+    if (malformed !== undefined) {
+        return outcome({ command, exitCode: EXIT_USAGE, diagnostics: [malformed] });
+    }
+    const specPath = options.spec ?? target.specPath;
+    const fields = { target: target.name, spec: specPath };
+    const read = readSpec(context, specPath);
+    if (!read.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: read.diagnostics });
+    }
+    const lowered = lowerSpec(read.text, specPath);
+    if (!lowered.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: lowered.diagnostics });
+    }
+    const declared = lowered.ir.retrievers.map((entry) => entry.id);
+    if (options.retriever !== undefined && !declared.includes(options.retriever)) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            fields: { ...fields, retrievers: declared },
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.retrieverNotFound,
+                    message: `No retriever named "${options.retriever}" in ${specPath}.`,
+                    path: [specPath],
+                    hint: declaredHint(declared),
+                }),
+            ],
+        });
+    }
+    // `--all` over a project that declares none is a well-formed request with nothing to do.
+    // It is not an error: a generated app with no retrieval is a legitimate app, and making
+    // its CI fail would force a `--retriever` that does not exist.
+    const selected = options.all || options.retriever === undefined ? declared : [options.retriever];
+    const scoped = { ...fields, retrievers: selected };
+    if (selected.length === 0) {
+        return outcome({
+            command,
+            exitCode: EXIT_OK,
+            fields: { ...scoped, results: [] },
+            diagnostics: sortDiagnostics(lowered.diagnostics),
+            text: 'No retrievers are declared; nothing to ingest.',
+        });
+    }
+    // A declared retriever whose module is absent is a project that has not been generated,
+    // not a misuse of the command. Checked before discovery so the message is about the
+    // missing artefact rather than about the interpreter that would have run it.
+    const missing = selected.filter((id) => !existsSync(absolutePath(context.cwd, target.retrievalIngestModuleFile(id))));
+    if (missing.length > 0) {
+        return outcome({
+            command,
+            exitCode: EXIT_FAILURE,
+            fields: scoped,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.ingestModulesMissing,
+                    message: `No generated ingest module for ${missing.map((id) => `"${id}"`).join(', ')}.`,
+                    path: missing.map((id) => target.retrievalIngestModuleFile(id)),
+                    hint: 'Run `aid gen`: the ingest entry points are the modules the generator emits.',
+                }),
+            ],
+        });
+    }
+    if (target.runner !== 'python') {
+        return outcome({
+            command,
+            // Exit 2, not 1: this command has no runner for this target, so nothing was
+            // ingested and the corpus was not judged.
+            exitCode: EXIT_USAGE,
+            fields: scoped,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.runnerUnsupported,
+                    message: `\`aid ingest\` runs generated Python modules, and ${target.name} emits TypeScript.`,
+                    hint: 'The emitted ingest module exports `ingest()`; run it with Node.',
+                }),
+            ],
+        });
+    }
+    const interpreter = discoverInterpreter(context);
+    if (interpreter === undefined) {
+        return outcome({
+            command,
+            // Exit 2, not 1: nothing about the project was judged. Ingest has no verdict when the
+            // thing that would run it cannot start, and `1` would read as "the corpus was wrong".
+            exitCode: EXIT_USAGE,
+            fields: scoped,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.pythonMissing,
+                    message: `No interpreter could import aid_runtime (tried ${INTERPRETERS.join(', ')}).`,
+                    hint: 'Install the runtime into the interpreter you run with, or run the generated ingest modules yourself.',
+                }),
+            ],
+        });
+    }
+    const base = interpreterCommand(interpreter);
+    const results = [];
+    const stdout = [];
+    const spoken = [];
+    const diagnostics = [...lowered.diagnostics];
+    for (const id of selected) {
+        const module = target.retrievalIngestModule(id);
+        // Appended after the module name so it lands as an argument to the module, which owns
+        // what a dry run means -- see the header note.
+        const run = invoke(context, [...base, '-m', module, ...(options.dryRun ? ['--dry-run'] : [])]);
+        if (run === undefined) {
+            return outcome({
+                command,
+                exitCode: EXIT_USAGE,
+                fields: { ...scoped, interpreter },
+                diagnostics: [
+                    cliError({
+                        code: CLI_DIAGNOSTIC_CODES.runnerFailed,
+                        message: `Could not start ${interpreter} to run "${module}".`,
+                    }),
+                ],
+            });
+        }
+        results.push({ retriever: id, module, status: run.status ?? EXIT_FAILURE });
+        stdout.push(run.stdout);
+        // The module reports what it could not ingest on stderr. It is surfaced rather than
+        // swallowed, and on the CLI's stderr even under `--json`, because that is where the
+        // process that wrote it wrote it.
+        if (run.stderr.trim() !== '') {
+            spoken.push(run.stderr.trimEnd());
+            diagnostics.push(cliWarning({
+                code: CLI_DIAGNOSTIC_CODES.runnerWarned,
+                message: `"${id}" wrote to stderr.`,
+            }));
+        }
+    }
+    // A non-zero exit from a generated module is that module's verdict, so it propagates.
+    // Every selected retriever still runs: one corpus that could not be built should not
+    // hide the state of the others.
+    const failed = results.some((result) => result.status !== 0);
+    return outcome({
+        command,
+        exitCode: failed ? EXIT_FAILURE : EXIT_OK,
+        fields: { ...scoped, interpreter, results },
+        diagnostics: sortDiagnostics(diagnostics),
+        text: render(results, stdout),
+        stderr: spoken.join('\n'),
+    });
+}
+//# sourceMappingURL=ingest.js.map

package/dist/commands/ingest.js.map

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

package/dist/commands/init.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `aid init` — scaffold a project: a starter spec and a README.
+ *
+ * It does not generate. `aid gen` generates, and `--gen` is the convenience for the one
+ * thing a person types next; keeping the two apart is what makes "scaffold" and "compile"
+ * separately testable and separately re-runnable.
+ *
+ * Two deliberate refusals, because scaffolding is the command most likely to be pointed at
+ * a directory that already has something in it:
+ *
+ * - An existing spec is not overwritten without `--force`. That file is the project's
+ *   source of truth; replacing it silently is the worst thing this command could do.
+ * - An existing README is left exactly as it is, and reported as skipped -- under `--force`
+ *   too. A README is the file a directory is most likely to already have, its contents are
+ *   the author's, and `--force` here is usually aimed at the spec.
+ *
+ * `--from <spec>` imports a spec rather than copying one: the imported text has to lower to
+ * an IR and pass the gates before anything is written, so `aid init --from` cannot produce a
+ * project that `aid validate` immediately rejects.
+ */
+import type { CliContext } from '../context.js';
+import type { CommandOutcome } from '../output.js';
+export interface InitOptions {
+    readonly dir: string | undefined;
+    readonly from: string | undefined;
+    readonly target: string | undefined;
+    readonly force: boolean;
+    readonly gen: boolean;
+}
+/**
+ * A `project.name` from a directory name. The spec's pattern is `^[a-z][a-z0-9-]{0,63}$`,
+ * and a directory called `My App` or `2024-prototype` is not a reason to fail `aid init`
+ * with a schema error about a field the caller never wrote.
+ */
+export declare function projectNameFor(directory: string): string;
+export declare function starterSpec(target: string, projectName: string): string;
+export declare function init(context: CliContext, options: InitOptions): CommandOutcome;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AA0BD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAYvE;AA+CD,wBAAgB,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,cAAc,CA8F9E"}

package/dist/commands/init.js

@@ -0,0 +1,203 @@
+/**
+ * `aid init` — scaffold a project: a starter spec and a README.
+ *
+ * It does not generate. `aid gen` generates, and `--gen` is the convenience for the one
+ * thing a person types next; keeping the two apart is what makes "scaffold" and "compile"
+ * separately testable and separately re-runnable.
+ *
+ * Two deliberate refusals, because scaffolding is the command most likely to be pointed at
+ * a directory that already has something in it:
+ *
+ * - An existing spec is not overwritten without `--force`. That file is the project's
+ *   source of truth; replacing it silently is the worst thing this command could do.
+ * - An existing README is left exactly as it is, and reported as skipped -- under `--force`
+ *   too. A README is the file a directory is most likely to already have, its contents are
+ *   the author's, and `--force` here is usually aimed at the spec.
+ *
+ * `--from <spec>` imports a spec rather than copying one: the imported text has to lower to
+ * an IR and pass the gates before anything is written, so `aid init --from` cannot produce a
+ * project that `aid validate` immediately rejects.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { CLI_DIAGNOSTIC_CODES, cliError } from '../diagnostics.js';
+import { EXIT_FAILURE, EXIT_OK, EXIT_USAGE } from '../exit.js';
+import { outcome } from '../output.js';
+import { absolutePath, parentPath } from '../paths.js';
+import { lowerSpec, readSpec } from '../pipeline.js';
+import { resolveTarget, unknownTargetDiagnostic } from '../targets.js';
+import { generate } from './gen.js';
+/**
+ * Lower-case a directory name, keep only `[a-z0-9]`, and collapse every run of anything
+ * else into a single `-`.
+ *
+ * A loop rather than a regular expression on purpose: trimming with `/^-+|-+$/g` after
+ * collapsing is quadratic on a name that is mostly separators, and the directory name is
+ * input this command does not control. Emitting the separator only between two kept
+ * characters means the result can never begin or end with one, so no trim pass is needed.
+ */
+function slugify(name) {
+    let slug = '';
+    let separatorPending = false;
+    for (const character of name.toLowerCase()) {
+        if (!((character >= 'a' && character <= 'z') || (character >= '0' && character <= '9'))) {
+            separatorPending = true;
+            continue;
+        }
+        if (separatorPending && slug !== '')
+            slug += '-';
+        separatorPending = false;
+        slug += character;
+    }
+    return slug;
+}
+/**
+ * A `project.name` from a directory name. The spec's pattern is `^[a-z][a-z0-9-]{0,63}$`,
+ * and a directory called `My App` or `2024-prototype` is not a reason to fail `aid init`
+ * with a schema error about a field the caller never wrote.
+ */
+export function projectNameFor(directory) {
+    const slug = slugify(basename(directory)).slice(0, 64);
+    if (slug === '')
+        return 'app';
+    const first = slug.charAt(0);
+    return first >= 'a' && first <= 'z' ? slug : `app-${slug}`.slice(0, 64);
+}
+export function starterSpec(target, projectName) {
+    return [
+        'specVersion: "0.1"',
+        '',
+        '# This file is the source of truth: `aid gen` compiles it into app/generated/,',
+        '# `aid validate` checks it, and `aid eval` gates the behaviour it declares.',
+        'project:',
+        `  name: ${projectName}`,
+        '  targets:',
+        `    - ${target}`,
+        '',
+    ].join('\n');
+}
+function starterReadme(projectName, target) {
+    return [
+        `# ${projectName}`,
+        '',
+        `An AID Framework project targeting \`${target.name}\`. \`${target.specPath}\` is the source`,
+        'of truth: the types, prompts, tools, pipelines and evals the application is made of.',
+        '',
+        '```bash',
+        'aid validate        # parse the spec, reduce it to the IR, run every build-time gate',
+        'aid gen             # compile the spec and reconcile the tree with it',
+        'aid gen --dry-run   # report what would change, and write nothing',
+        'aid eval            # run the eval gate',
+        '```',
+        '',
+        `\`${target.generatedDir}/\` is owned by the generator: \`aid gen\` writes it, and refuses to`,
+        'overwrite it once you have edited it, keeping the rejected bytes beside the file.',
+        `\`${target.businessDir}/\` is yours: \`aid gen\` creates a file there once and never touches it`,
+        'again.',
+        '',
+    ].join('\n');
+}
+/**
+ * Create a file, reporting whether this call is the one that created it.
+ *
+ * The exclusive flag makes the create itself the existence check, so a file that appears
+ * between a probe and a write cannot be clobbered -- a check-then-act refusal is not a
+ * refusal. Returns `false` when the path already exists, and rethrows anything else.
+ */
+function createExclusively(path, data) {
+    try {
+        writeFileSync(path, data, { encoding: 'utf8', flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (isAlreadyExists(error))
+            return false;
+        throw error;
+    }
+}
+function isAlreadyExists(error) {
+    return (typeof error === 'object' && error !== null && error.code === 'EEXIST');
+}
+export function init(context, options) {
+    const command = 'init';
+    const target = resolveTarget(options.target);
+    if (target === undefined) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            diagnostics: [unknownTargetDiagnostic(options.target ?? '')],
+        });
+    }
+    const root = options.dir === undefined ? context.cwd : resolve(context.cwd, options.dir);
+    const specPath = target.specPath;
+    const displayed = options.dir ?? '.';
+    const fields = { dir: displayed, target: target.name, spec: specPath };
+    const source = options.from === undefined
+        ? { ok: true, text: starterSpec(target.name, projectNameFor(root)) }
+        : readSpec(context, options.from);
+    if (!source.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: source.diagnostics });
+    }
+    // Checked against the path the spec will actually live at, so the diagnostics carry the
+    // file the reader will open rather than the one it was imported from.
+    const lowered = lowerSpec(source.text, specPath);
+    if (!lowered.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: lowered.diagnostics });
+    }
+    const specAbsolute = absolutePath(root, specPath);
+    const written = [];
+    const skipped = [];
+    mkdirSync(absolutePath(root, parentPath(specPath)), { recursive: true });
+    // Created exclusively so that "does it already exist" and "write it" are one syscall. The
+    // refusal holds even if the file appears between a check and a write, and no separate
+    // `existsSync` has to stay true for the guarantee to mean anything. `--force` is the one
+    // path meant to replace the file, so it writes normally; nothing else reaches the write.
+    if (!createExclusively(specAbsolute, source.text)) {
+        if (!options.force) {
+            return outcome({
+                command,
+                exitCode: EXIT_FAILURE,
+                fields,
+                diagnostics: [
+                    cliError({
+                        code: CLI_DIAGNOSTIC_CODES.refusingToOverwrite,
+                        message: `"${specPath}" already exists.`,
+                        path: [specPath],
+                        hint: 'Pass --force to overwrite it, or run `aid gen` to regenerate from the spec that is already there.',
+                    }),
+                ],
+            });
+        }
+        writeFileSync(specAbsolute, source.text, 'utf8');
+    }
+    written.push(specPath);
+    // A README is the one file written here whose contents are the caller's, so it is
+    // created once and then never replaced -- not even under `--force`, which is passed
+    // routinely just to overwrite a spec. Replacing prose a person wrote as a side effect
+    // of resetting a spec is not what `--force` was asked for.
+    const readmeAbsolute = join(root, 'README.md');
+    if (createExclusively(readmeAbsolute, starterReadme(projectNameFor(root), target))) {
+        written.push('README.md');
+    }
+    else {
+        skipped.push('README.md');
+    }
+    // The generation runs against the scaffolded project root, not the caller's working
+    // directory: `aid init sub/project --gen` must generate into `sub/project`.
+    const generation = options.gen
+        ? generate({ ...context, cwd: root }, { spec: specPath, target: target.name, dryRun: false, force: false })
+        : undefined;
+    const text = [
+        ...written.map((path) => `created ${path}`),
+        ...skipped.map((path) => `kept ${path} (already there; it is never replaced)`),
+        ...(generation === undefined ? ['next: aid validate, then aid gen'] : [generation.text]),
+    ].filter((line) => line !== '');
+    return outcome({
+        command,
+        exitCode: generation?.exitCode ?? EXIT_OK,
+        diagnostics: [...lowered.diagnostics, ...(generation?.diagnostics ?? [])],
+        text: text.join('\n'),
+        fields: { ...fields, written, skipped, generation: generation?.report ?? null },
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

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

package/dist/commands/validate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `aid validate` — parse the spec, reduce it to the IR, and run every build-time gate.
+ *
+ * This is the "is this spec buildable" question, asked without touching the tree and
+ * without asking the target to compile anything. It stops at the first stage that
+ * produced an error, because lowering a spec whose own schema did not validate reports a
+ * cascade of consequences of the first mistake and buries it. Warnings from the stages
+ * that did run are kept and printed: the eval-coverage gate warns by design, and a
+ * validation that swallowed warnings would make a deliberate signal invisible.
+ *
+ * `aid gen` asks the same question and then goes further, into the target's compiler and
+ * its plan. So a spec can pass `aid validate` and still fail `aid gen` -- that is the
+ * honest split, and it is why the two commands report their own stage rather than
+ * pretending to be one command with a flag.
+ */
+import type { CliContext } from '../context.js';
+import type { CommandOutcome } from '../output.js';
+export interface ValidateOptions {
+    readonly spec: string | undefined;
+}
+export declare function validate(context: CliContext, options: ValidateOptions): CommandOutcome;
+//# sourceMappingURL=validate.d.ts.map

package/dist/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAmCtF"}

package/dist/commands/validate.js

@@ -0,0 +1,53 @@
+/**
+ * `aid validate` — parse the spec, reduce it to the IR, and run every build-time gate.
+ *
+ * This is the "is this spec buildable" question, asked without touching the tree and
+ * without asking the target to compile anything. It stops at the first stage that
+ * produced an error, because lowering a spec whose own schema did not validate reports a
+ * cascade of consequences of the first mistake and buries it. Warnings from the stages
+ * that did run are kept and printed: the eval-coverage gate warns by design, and a
+ * validation that swallowed warnings would make a deliberate signal invisible.
+ *
+ * `aid gen` asks the same question and then goes further, into the target's compiler and
+ * its plan. So a spec can pass `aid validate` and still fail `aid gen` -- that is the
+ * honest split, and it is why the two commands report their own stage rather than
+ * pretending to be one command with a flag.
+ */
+import { countBySeverity } from '@aid-framework/spec';
+import { EXIT_FAILURE, EXIT_OK } from '../exit.js';
+import { outcome } from '../output.js';
+import { lowerSpec, readSpec } from '../pipeline.js';
+import { DEFAULT_SPEC_PATH } from '../targets.js';
+export function validate(context, options) {
+    const command = 'validate';
+    const specPath = options.spec ?? DEFAULT_SPEC_PATH;
+    const read = readSpec(context, specPath);
+    if (!read.ok) {
+        return outcome({
+            command,
+            exitCode: EXIT_FAILURE,
+            fields: { spec: specPath },
+            diagnostics: read.diagnostics,
+        });
+    }
+    const lowered = lowerSpec(read.text, specPath);
+    const counts = countBySeverity(lowered.diagnostics);
+    const fields = { spec: specPath, counts };
+    if (!lowered.ok) {
+        return outcome({
+            command,
+            exitCode: EXIT_FAILURE,
+            fields,
+            diagnostics: lowered.diagnostics,
+            text: `${specPath}: ${counts.error} error(s), ${counts.warning} warning(s)`,
+        });
+    }
+    return outcome({
+        command,
+        exitCode: EXIT_OK,
+        fields,
+        diagnostics: lowered.diagnostics,
+        text: `${specPath}: ok (${counts.error} errors, ${counts.warning} warnings)`,
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMlD,MAAM,UAAU,QAAQ,CAAC,OAAmB,EAAE,OAAwB;IACpE,MAAM,OAAO,GAAG,UAAU,CAAC;IAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,IAAI,iBAAiB,CAAC;IAEnD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACb,OAAO,OAAO,CAAC;YACb,OAAO;YACP,QAAQ,EAAE,YAAY;YACtB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC1B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAE1C,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QAChB,OAAO,OAAO,CAAC;YACb,OAAO;YACP,QAAQ,EAAE,YAAY;YACtB,MAAM;YACN,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,IAAI,EAAE,GAAG,QAAQ,KAAK,MAAM,CAAC,KAAK,cAAc,MAAM,CAAC,OAAO,aAAa;SAC5E,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;QACb,OAAO;QACP,QAAQ,EAAE,OAAO;QACjB,MAAM;QACN,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,IAAI,EAAE,GAAG,QAAQ,SAAS,MAAM,CAAC,KAAK,YAAY,MAAM,CAAC,OAAO,YAAY;KAC7E,CAAC,CAAC;AACL,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Everything the CLI touches outside of itself, behind one injectable object.
+ *
+ * A CLI is mostly side effects, and side effects are what makes a command hard to test.
+ * Naming them in one place keeps every command a pure function of its arguments and
+ * this context, so a test can run a whole command against a temporary directory and
+ * assert on what it printed, what it wrote, and what it exited with -- without a
+ * subprocess, and without a mock for the parts that are not I/O.
+ */
+export interface SpawnOptions {
+    readonly cwd: string;
+    /** `inherit` streams the child's output straight through; `pipe` captures it. */
+    readonly stdio: 'inherit' | 'pipe';
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Written to the child's stdin, then closed. Used for the baseline recipe. */
+    readonly stdin?: string;
+}
+export interface SpawnResult {
+    /** The exit status, or `null` when the child never ran or died by signal. */
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** Set when the child could not be executed at all, such as a missing binary. */
+    readonly error?: Error;
+}
+export type Spawn = (command: string, args: readonly string[], options: SpawnOptions) => SpawnResult;
+export interface CliContext {
+    /** The project root: every repository-relative path resolves against this. */
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    readonly spawn: Spawn;
+}
+/** The real world: the process streams, the process environment, and real children. */
+export declare function createContext(overrides?: Partial<CliContext>): CliContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,MAAM,MAAM,KAAK,GAAG,CAClB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,YAAY,KAClB,WAAW,CAAC;AAEjB,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAkBD,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,SAAS,GAAE,OAAO,CAAC,UAAU,CAAM,GAAG,UAAU,CAQ7E"}