@inventarch/cli 0.0.0-stage → 1.0.0

package/dist/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;AAClD,KAAK,OAAO,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7C,eAAO,MAAM,WAAW,2BAA2B,CAAC;AACpD,eAAO,MAAM,QAAQ,mBAAmB,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AACD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,SAAS,OAAO,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AACD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AASD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,WAAW,CAsBzE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAOxD;AAED,mHAAmH;AACnH,eAAO,MAAM,WAAW,GAAI,MAAM,WAAW,KAAG,CAAC,GAAG,CAAgD,CAAC;AAErG,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAuDzF;AA0BD,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAmBnD"}

package/dist/compile.js

@@ -0,0 +1,136 @@
+/**
+ * `ia compile`: docs/specs/consumer-cli-contract/README.md §2.4.
+ *
+ * One deterministic document, `ia.compiled.v1`. Determinism is a requirement on this writer, not a hope: records
+ * are sorted by canonical identity, diagnostics by (path, line, code, message), object keys are emitted sorted and
+ * the document ends in exactly one newline — which is what the distribution's own `json()` serializer does, so it
+ * is the function called rather than a second encoder beside it.
+ *
+ * No product-quality claim. Compilation establishes that records parse, that references resolve and that declared
+ * structural obligations are satisfied. Where a semantic evaluator is unavailable the compiler carries
+ * IA-COMP-NOT-EVALUATED through into `diagnostics` and `counts.notEvaluated`; that result is never rolled into a
+ * pass, never suppressed and never omitted from --json.
+ */
+import { resolve } from 'node:path';
+import { createFile, json, LANGUAGE_IDENTITY, replace, sha256, workOutputPath, } from '@inventarch/distribution/services';
+import { Refusal, requireRoot } from './consumer.js';
+import { codeOf, openSession } from './session.js';
+import { NOT_EVALUATED } from './validate.js';
+import { atom, document, entry, headerLine, sectionLabel, truncateDigest, words } from './render.js';
+export const DEFAULT_OUT = '.ia/work/compiled.json';
+export const ARTIFACT = 'ia.compiled.v1';
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** The ordering the compliance layer already applies, reused rather than reinvented. */
+const orderFindings = (findings) => [...findings].sort((a, b) => compare(a.path, b.path) || a.line - b.line || compare(a.code, b.code) || compare(a.message, b.message));
+export function buildArtifact(root, session) {
+    const admission = session.admission();
+    const records = [...session.reader.records()].sort((a, b) => compare(a.identity, b.identity));
+    const diagnostics = orderFindings(admission.findings);
+    const artifact = {
+        formatVersion: 1,
+        artifact: ARTIFACT,
+        language: LANGUAGE_IDENTITY.language,
+        kernelDigest: LANGUAGE_IDENTITY.kernelDigest,
+        root,
+        revision: admission.revision,
+        records,
+        diagnostics,
+        counts: {
+            records: records.length,
+            errors: diagnostics.filter((finding) => finding.severity === 'error').length,
+            warnings: diagnostics.filter((finding) => finding.severity === 'warning').length,
+            notEvaluated: diagnostics.filter((finding) => NOT_EVALUATED.has(finding.code)).length,
+        },
+    };
+    const text = json(artifact);
+    return { artifact, text, digest: sha256(text) };
+}
+export function collectCompile(root) {
+    const session = openSession(root);
+    try {
+        return buildArtifact(root, session);
+    }
+    finally {
+        session.close();
+    }
+}
+/** §2.4: the artifact is written even when the compilation produced errors; the exit class carries the verdict. */
+export const compileExit = (view) => (view.artifact.counts.errors === 0 ? 0 : 1);
+export function compileEnvelope(view, path) {
+    return {
+        version: 1,
+        artifact: path,
+        revision: view.artifact.revision,
+        digest: view.digest,
+        counts: view.artifact.counts,
+    };
+}
+export function renderCompile(view, path, caps) {
+    const counts = view.artifact.counts;
+    const facts = [
+        words(`${counts.records} records, ${counts.errors} errors, ${counts.warnings} warnings, ${counts.notEvaluated} not evaluated.`),
+    ];
+    if (counts.notEvaluated > 0)
+        facts.push(words(`${counts.notEvaluated} checks had no evaluator, so this artifact records a not-evaluated result rather than a pass.`));
+    facts.push(words('Compilation establishes that records parse, that references resolve and that declared structural obligations are satisfied. It is not a claim that a design is good.'));
+    return document([
+        headerLine('Compile', ARTIFACT, [{ text: `revision ${truncateDigest(view.artifact.revision, caps.ascii)}`, column: 50 }], caps),
+        entry(facts, { depth: 1, symbol: counts.errors === 0 ? 'success' : 'error' }, caps),
+        [
+            sectionLabel('Artifact', caps),
+            ...entry([
+                [atom(path, 'cyan', 0)],
+                [
+                    atom(`sha256 ${truncateDigest(view.digest, caps.ascii)}`, null, 0),
+                    ...words(`${Buffer.byteLength(view.text)} bytes`, 'dim', 2),
+                ],
+            ], { depth: 1, symbol: 'info' }, caps),
+        ],
+        entry([
+            words(counts.errors > 0
+                ? 'Run "ia validate" for the located findings, fix them, then compile again.'
+                : 'Compare two artifacts byte for byte: identical sources on one language version compile identically.'),
+        ], { depth: 0, symbol: 'step' }, caps),
+    ], { leadingBlank: true });
+}
+/**
+ * §2.4: running `ia compile` twice is the ordinary case, so refusing by default is stated rather than discovered.
+ * `createFile` raises IA-DIST-LOCAL-MODIFICATION on an existing entry; the code is carried through unchanged and
+ * only the next action is added, because a refusal whose remedy is one flag must name that flag.
+ */
+function publish(root, path, content, force) {
+    if (force) {
+        replace(root, path, content);
+        return;
+    }
+    try {
+        createFile(root, path, content);
+    }
+    catch (error) {
+        if (codeOf(error, '') !== 'IA-DIST-LOCAL-MODIFICATION')
+            throw error;
+        throw new Refusal('IA-DIST-LOCAL-MODIFICATION', `${path} already exists`, 3, { path }, 'Pass --force to overwrite it, or choose another --out under .ia/work/.');
+    }
+}
+export function runCompile(context) {
+    const { args, caps, json: machine } = context;
+    const root = requireRoot(context);
+    // Placement is decided before the workspace is read, so an unsafe --out never costs a compilation.
+    const path = args.flag('stdout')
+        ? null
+        : workOutputPath({
+            root,
+            path: args.value('out') ?? DEFAULT_OUT,
+            refusal: 'A compiled artifact is written under .ia/work/',
+        });
+    const view = collectCompile(root);
+    const exitCode = compileExit(view);
+    // §2.4: with --stdout the artifact is the single value on stdout, so nothing else may be written there.
+    if (path === null)
+        return { exitCode, stdout: view.text, stderr: '' };
+    publish(root, path, Buffer.from(view.text, 'utf8'), args.flag('force'));
+    return machine
+        ? { exitCode, stdout: JSON.stringify(compileEnvelope(view, resolve(root, path))) + '\n', stderr: '' }
+        : { exitCode, stdout: renderCompile(view, path, caps), stderr: '' };
+}
+//# sourceMappingURL=compile.js.map

package/dist/compile.js.map

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

package/dist/consumer.d.ts

@@ -0,0 +1,137 @@
+import type { Arguments } from './args.js';
+import type { CommandSpec } from './commands.js';
+import type { Capabilities, Terminal } from './render.js';
+/**
+ * §2.8 rule 3's one question, described rather than performed — the same move `render.ts` makes for the terminal.
+ * The reader and the writer arrive from the entry point, so the decision is a pure function of a string and a test
+ * observes the exact bytes the question put on the wire. Unlike a rendered result this cannot be returned as text:
+ * the prompt has to be written before the answer can be read.
+ */
+export interface Interaction {
+    /** §2.8 rule 3: both stdin and stdout are terminals. A question that cannot be answered is never asked. */
+    readonly interactive: boolean;
+    /** §5 keeps every prompt off stdout, so the entry point points this at stderr. */
+    readonly write: (text: string) => void;
+    /** One line of input, or null at EOF, on a closed stdin, or where stdin cannot be read at all. */
+    readonly read: () => Promise<string | null>;
+}
+/** §2.8 rule 3: `y` or `yes`, in any case and ignoring surrounding space. Everything else, EOF included, declines. */
+export declare const consents: (answer: string | null) => boolean;
+/**
+ * Shows the change summary, asks once, and reports the answer. What a declined answer means belongs to the caller:
+ * §2.8 rule 3 makes declining an answer to the question, not a failure of the command.
+ */
+export declare function confirm(interaction: Interaction, summary: string, question: string): Promise<boolean>;
+export interface Host {
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly stdout: Terminal;
+    readonly stderr: Terminal;
+    /** §2.8 rule 3: `--apply` may prompt only when a question can actually be asked and answered. */
+    readonly interaction: Interaction;
+    readonly version: string;
+    /** The directory holding `assets/`, so §2.2's catalogue travels with the package rather than the workspace. */
+    readonly packageRoot: string;
+    readonly signal?: AbortSignal;
+    /**
+     * Called once, only when §1.2 step 5 has selected a consumer verb. §3 forbids a SIGINT handler on the legacy
+     * route's path, so the entry point installs its cleanup here rather than at startup.
+     */
+    readonly onConsumerRoute?: () => void | (() => void);
+}
+export interface Result {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface Context {
+    readonly host: Host;
+    readonly command: CommandSpec;
+    readonly args: Arguments;
+    readonly caps: Capabilities;
+    readonly json: boolean;
+}
+/** §4: a refusal carries the service's own code unchanged, its exit class, and where it happened. */
+export declare class Refusal extends Error {
+    readonly code: string;
+    readonly exit: number;
+    readonly where: {
+        readonly path?: string;
+        readonly line?: number;
+        readonly identity?: string;
+    } | null;
+    readonly next: string | null;
+    /** §6.5 element 1 when there is no `where`: the invocation that was refused, rendered but never serialized. */
+    readonly at: string | null;
+    constructor(code: string, message: string, exit: number, where?: {
+        readonly path?: string;
+        readonly line?: number;
+        readonly identity?: string;
+    } | null, next?: string | null, 
+    /** §6.5 element 1 when there is no `where`: the invocation that was refused, rendered but never serialized. */
+    at?: string | null);
+}
+/**
+ * §5's first signal, raised by a verb that had already written when it observed the signal. The JSON result stays
+ * §5's fixed object; the one stderr line gains the rerun that finishes the work, which M5.2 §5 requires `ia init`
+ * to name once it has written anything.
+ */
+export declare class Interrupted extends Error {
+    readonly next: string;
+    constructor(next: string);
+}
+/**
+ * §4.1: the consumer never rewrites a service's code. Class 4 is unreachable from the three verbs this release
+ * implements, because none of them acquires anything over a network, so every unmapped failure is class 3.
+ */
+export declare function refusalOf(error: unknown): Refusal;
+/** §4.3 and §6.5. Human mode renders the block on stderr; `--json` emits the one object on stdout. */
+export declare function renderRefusal(refusal: Refusal, caps: Capabilities, json: boolean): Result;
+/** §6.5's strip rule applied to the serializer as well as the renderer, so both carry the same message. */
+export declare const stripFor: (message: string, code: string, location: string | null, identity: string | null) => string;
+export declare const optionLabel: (name: string, short: string | undefined, placeholder: string | undefined) => string;
+export interface Namespace {
+    readonly token: string;
+    readonly summary: string;
+}
+/**
+ * §1.2 step 1 and §7.1. The nine legacy operations are listed verbatim under their own heading, together with
+ * their own usage line, because the consumer help is the only place a reader learns that the machine protocol
+ * exists and is unchanged. One row points at each operation's own help (spec-0012 CLI-04). Private namespaces are
+ * supplied by the caller so that a tree without them prints a help text that does not mention them.
+ */
+export declare function renderHelp(host: Host, caps: Capabilities, namespaces: readonly Namespace[]): string;
+export declare function renderCommandHelp(command: CommandSpec, caps: Capabilities): string;
+/**
+ * §2.0: walk from cwd toward the filesystem root and take the first directory containing `.ia/src`. Host plugin
+ * distribution spec §3: a directory whose `.ia` is the IA home is never a workspace, even if src/ appeared there.
+ */
+export declare function discoverRoot(start: string, iaHome?: string): string | undefined;
+/** The IA home for discovery, or undefined when its variable is malformed; the verb that needs the home refuses then. */
+export declare function iaHomeOf(env: Readonly<Record<string, string | undefined>>, home?: string): string | undefined;
+/**
+ * §2.0: the real path of the resolved absolute root, because `workspace()` refuses a relative root and any link on the
+ * way to one (`apps/distribution/src/files.ts:51`). A failed discovery is exit 3 with IA-DB-ROOT-INVALID.
+ */
+export declare function requireRoot(context: Context): string;
+export declare const HELP_TOKENS: ReadonlySet<string>;
+/** §1.2 step 5. Parse, then run; every class-2 check has already happened when a handler is entered. */
+export declare function runCommand(command: CommandSpec, argv: readonly string[], host: Host): Promise<Result>;
+export interface Extension extends Namespace {
+    readonly run: (args: readonly string[]) => Promise<{
+        readonly exitCode: number;
+        readonly stdout: string;
+    }>;
+}
+export interface Legacy {
+    (args: readonly string[]): {
+        readonly exitCode: number;
+        readonly stdout: string;
+    };
+}
+/**
+ * §1.2's ordered table. The first match wins and the order is normative: step 4 precedes step 5 unconditionally,
+ * so a legacy operation can never be shadowed by a consumer verb.
+ */
+export declare function dispatch(argv: readonly string[], host: Host, legacy: Legacy, extensions: readonly Extension[]): Promise<Result>;
+//# sourceMappingURL=consumer.d.ts.map

package/dist/consumer.d.ts.map

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