@oprt/cli 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,37 +1,144 @@
-import { C as Command, a as Contract, R as Registry, b as RegistryEntry, A as AddOptions, I as InstallResult } from './read-8a9euzJx.cjs';
-export { c as CliError, d as ComponentDetail, D as DetailProp, e as IndexEntry, f as InstallFile, S as SearchResult, g as applyBlock, h as blockVersion, i as componentDetail, j as componentIndex, r as removeBlock, k as renderAgentBlock, l as renderComponent, s as search } from './read-8a9euzJx.cjs';
+import { C as Contract, a as ComponentDetail, b as Command, R as Registry, c as RegistryEntry, A as AddOptions, I as InstallResult } from './read-C7rE5UlY.cjs';
+export { d as CliError, D as DetailProp, e as IndexEntry, f as InstallFile, S as SearchResult, g as applyBlock, h as blockVersion, i as componentDetail, j as componentIndex, r as removeBlock, k as renderAgentBlock, l as renderComponent, s as search } from './read-C7rE5UlY.cjs';
 
-/** The envelope every `--json` answer comes in. `type` says what `data` holds. */
-interface Envelope {
+/** This program's version: the package's. The contract has its own (`Contract.version`). */
+declare const VERSION: string;
+/**
+ * The version of the result model: the envelope and the data of every `--json` answer and MCP
+ * structured result. It rises when a field is removed or changes meaning; adding a field does not
+ * raise it. The envelope's `apiVersion` is the same number, kept for the readers that branch on it.
+ */
+declare const RESULT_SCHEMA_VERSION = 1;
+interface Identity {
+    /** This program: the `@oprt/cli` package version. */
+    cli_version: string;
+    /** The contract it carries: the `@oprt/react` version the contract describes. */
+    contract_version: string;
+    /**
+     * `sha256:` and the hash of the contract as `dist/contract.json` holds it (the file's bytes, so
+     * `shasum -a 256 dist/contract.json` gives the same). Two answers with one digest read one contract.
+     */
+    contract_digest: string;
+    /** The result model's version. */
+    schema_version: number;
+}
+/** What an answer can say about itself when the contract could not be read. */
+interface ErrorIdentity {
+    cli_version: string;
+    schema_version: number;
+    contract_version?: string;
+    contract_digest?: string;
+}
+/** The contract's digest. Computed once per contract: it is one hash of about 160 KB. */
+declare function contractDigest(contract: Contract): string;
+declare function identityOf(contract: Contract): Identity;
+
+/**
+ * The `typescript` module as the project has it. It is opaque in the installer's own types, so
+ * that using those types does not require TypeScript to be installed.
+ */
+type TypeScript = object;
+/** Where the parser came from, for a person or an agent deciding whether to trust the answer. */
+interface ParserInfo {
+    name: "typescript";
+    version: string;
+    /**
+     * `project`: resolved from the directory being checked. `installer`: found beside this program
+     * instead, because the project has none of its own. `provided`: handed in by a caller of the
+     * library.
+     */
+    source: "project" | "installer" | "provided";
+}
+interface ParserResolution extends ParserInfo {
+    /** The folder of the `typescript` package that was loaded. */
+    resolved_from: string;
+}
+/** Why checking cannot run, as a stable word. */
+type ParserBlock = "typescript_missing" | "typescript_unusable";
+type ParserProbe = {
+    ready: true;
+    typescript: TypeScript;
+    resolution: ParserResolution;
+} | {
+    ready: false;
+    reason: ParserBlock;
+    detail: string;
+};
+
+declare const RESULT_TYPES: readonly ["check", "search", "component.detail", "component.batch", "component.list", "init", "doctor", "add", "list", "instructions"];
+type ResultType = (typeof RESULT_TYPES)[number];
+/** The envelope every `--json` answer and every structured tool result comes in. */
+interface Envelope<T = unknown> {
+    /** The result model's version (same number as `identity.schema_version`), for readers that branch on it. */
     apiVersion: 1;
-    type: string;
-    data: unknown;
+    /** What `data` holds. */
+    type: ResultType;
+    identity: Identity;
+    data: T;
 }
+/** What a failure comes in. `code` is stable and only ever added to. */
+interface ErrorEnvelope {
+    apiVersion: 1;
+    error: string;
+    code: string;
+    suggestions?: string[];
+    identity: ErrorIdentity;
+}
+declare const envelope: <T>(type: ResultType, data: T, contract: Contract) => Envelope<T>;
+/**
+ * A failure as the model carries it. The contract is optional: a failure can come before the
+ * contract was read, and the answer still says which program it came from.
+ */
+declare function errorEnvelope(error: unknown, contract?: Contract): ErrorEnvelope;
+type ComponentDetailData = Omit<ComponentDetail, "description"> & {
+    /** Absent from the compact form. */
+    description?: string;
+    /** True for the compact form: no component description, one sentence per prop. */
+    dense: boolean;
+};
+type Schema = Record<string, unknown>;
+/** The schema of one kind of answer: `schemaFor("check")`, or `schemaFor("error")` for a failure. */
+declare function schemaFor(type: ResultType | "error"): Schema;
+/**
+ * The schema an MCP tool declares as its `outputSchema`: one object that is either the answer for
+ * its type (`type` and `data`) or the failure (`error` and `code`), since a tool that could not
+ * run returns the failure in the same place, and the client checks structured content whether or
+ * not the call failed. One object with two ways to be complete is smaller than two schemas under
+ * `anyOf`, which repeated the envelope in every tool.
+ */
+declare function outputSchemaFor(type: ResultType): Schema;
+/** Every schema, by name: what the library exports for a client that wants to check an answer. */
+declare const RESULT_SCHEMAS: Readonly<Record<ResultType | "error", Schema>>;
+
 interface Answer {
     /** What a person reads. */
     text: string;
-    /** What `--json` prints. */
+    /** What `--json` prints: the result model, the same object an MCP tool returns. */
     json: Envelope;
     exitCode: number;
 }
 type AgentCommand = Extract<Command, {
-    command: "component" | "search" | "init" | "doctor" | "check";
+    command: "component" | "search" | "init" | "doctor" | "check" | "list" | "add";
 }>;
-/** Runs one of the commands an agent reads the contract with, and returns both forms of the answer. */
+/**
+ * Runs one of the commands that answers with data, and returns both forms of the answer: the text a
+ * person reads and the envelope `--json` prints. The MCP server builds its structured results from
+ * the same functions, so the two cannot disagree.
+ */
 declare function runAgentCommand(command: AgentCommand, context: {
     cwd: string;
     contract: Contract;
     registry: Registry;
+    /** For doctor: the TypeScript resolution to report, when the caller already has it. */
+    parser?: ParserProbe;
 }): Answer;
 
-/**
- * The `typescript` module as the project has it. It is opaque in the installer's own types, so
- * that using those types does not require TypeScript to be installed.
- */
-type TypeScript = object;
+/** Every code a finding can carry. Stable, and only ever added to: branch on these, not on messages. */
+declare const FINDING_CODES: readonly ["INVALID_PROP_VALUE", "UNKNOWN_EXPORT", "DOT_NOTATION", "INVALID_NESTING", "INVALID_CHILD", "MISSING_REQUIRED_PROP", "UNKNOWN_PROP", "RAW_COLOR", "ARBITRARY_SIZE", "ROUNDED_CORNER", "NATIVE_CONTROL", "SYNTAX_ERROR"];
+declare const LIMITATION_CODES: readonly ["UNRESOLVED_SPREAD", "UNRESOLVED_VALUE"];
 interface Finding {
     /** Stable, and only ever added to. Branch on this, not on the message. */
-    code: "INVALID_PROP_VALUE" | "UNKNOWN_EXPORT" | "DOT_NOTATION" | "INVALID_NESTING" | "INVALID_CHILD" | "MISSING_REQUIRED_PROP" | "UNKNOWN_PROP" | "RAW_COLOR" | "ARBITRARY_SIZE" | "ROUNDED_CORNER" | "NATIVE_CONTROL";
+    code: (typeof FINDING_CODES)[number];
     /** An error breaks the contract. A warning breaks a house rule, or may be a native attribute. */
     severity: "error" | "warning";
     file: string;
@@ -43,17 +150,92 @@ interface Finding {
     valid_values?: string[];
     suggestions?: string[];
 }
+/**
+ * Something the check could not read, so it did not judge it. Recorded with its place, never
+ * guessed: the code may be right or wrong there, and this says only that it was not looked at.
+ */
+interface Limitation {
+    /** Stable, and only ever added to. */
+    code: (typeof LIMITATION_CODES)[number];
+    file: string;
+    line: number;
+    column: number;
+    component: string;
+    prop?: string;
+    message: string;
+}
+/**
+ * What happened to one file. `evaluated`: read in full. `partial`: checked, with limits the
+ * report records. `not_evaluated`: it does not parse, so nothing about the contract was checked.
+ */
+interface SourceEvaluation {
+    file: string;
+    status: "evaluated" | "partial" | "not_evaluated";
+    findings: Finding[];
+    limitations: Limitation[];
+}
+type EvaluationStatus = "evaluated_clean" | "evaluated_with_findings" | "partially_evaluated" | "not_evaluated" | "no_files_evaluated";
+/** An input that was named but not read, and why. */
+interface SkippedInput {
+    path: string;
+    reason: "unsupported_extension" | "test_or_story_file" | "excluded_folder";
+}
 interface CheckReport {
-    /** How many files were read. */
+    /**
+     * `evaluated_clean` means every file was read in full and nothing was found. Anything less is
+     * named: findings, limits, files that did not parse, or no file read at all.
+     */
+    evaluation_status: EvaluationStatus;
+    /** How many files were read (found and opened). */
     files: number;
     findings: Finding[];
     summary: {
         errors: number;
         warnings: number;
     };
+    coverage: {
+        files_found: number;
+        /** Parsed and checked, including those with limits. */
+        files_evaluated: number;
+        /** Of those evaluated, the ones with a limit. */
+        files_partial: number;
+        /** Did not parse. */
+        files_not_evaluated: number;
+    };
+    /** Everything that was not read, each with its place. Empty only when nothing was skipped over. */
+    limitations: Limitation[];
+    /** Inputs that were named and not read, with the reason. */
+    skipped_inputs: SkippedInput[];
+    /** What this check covers, and what it leaves to other tools. The same on every run. */
+    scope: {
+        checked: string[];
+        not_checked: string[];
+    };
+    parser: ParserInfo;
 }
-/** Check one file's source. `file` is only the name the findings carry. */
-declare function checkSource(typescript: TypeScript, contract: Contract, file: string, text: string): Finding[];
+/**
+ * Check one file's source. `file` is only the name the findings carry. A file that does not parse
+ * is not checked at all (`not_evaluated`, with the syntax errors as findings): what TypeScript
+ * recovers from broken code is a guess, and the contract is not judged on a guess.
+ */
+declare function checkSource(typescript: TypeScript, contract: Contract, file: string, text: string): SourceEvaluation;
+/**
+ * The report for a set of evaluated files. The status is `evaluated_clean` only when every file
+ * was read in full and nothing was found; everything short of that has its own name.
+ */
+declare function buildCheckReport(evaluations: readonly SourceEvaluation[], context: {
+    parser: ParserInfo;
+    skipped?: SkippedInput[];
+}): CheckReport;
+/**
+ * The exit code of `oprt check`. 0: every file that was read has no errors (and, when strict, no
+ * warnings); limits are shown and do not fail the run. 1: an error was found, a file did not
+ * parse, or no file was read at all (nothing was checked, which is not a pass). Usage mistakes
+ * and a path that is not there exit 2, and a missing TypeScript exits 1, before any report.
+ */
+declare function checkExitCode(report: CheckReport, { strict }: {
+    strict: boolean;
+}): number;
 /**
  * Check every .tsx and .jsx file under the given paths. `typescript` is found in the project when
  * it is not passed; null stands for "there is none".
@@ -63,6 +245,11 @@ declare function checkPaths(paths: string[], context: {
     contract: Contract;
     typescript?: TypeScript | null;
 }): CheckReport;
+/**
+ * A check as text, for a terminal or a tool result. Findings first, then the limits, then one
+ * line that says how much was read: the same words the JSON status carries.
+ */
+declare function renderCheckText(report: CheckReport): string;
 
 interface DoctorCheck {
     id: string;
@@ -70,7 +257,31 @@ interface DoctorCheck {
     message: string;
     fix?: string;
 }
+/**
+ * Whether one thing oprt does can run here. Lookups (search, component, list) read the contract
+ * that ships inside oprt, so they always can. Checking code needs a parser, which is the
+ * project's own TypeScript: without it that operation is blocked, with the reason as a word.
+ */
+interface DoctorOperations {
+    lookup: {
+        status: "ready";
+        message: string;
+        contract_version: string;
+    };
+    check_code: {
+        status: "ready" | "blocked";
+        message: string;
+        reason?: ParserBlock;
+        fix?: string;
+        /** The parser that checking will use, when it is ready. */
+        typescript?: Pick<ParserResolution, "version" | "resolved_from" | "source">;
+    };
+}
 interface DoctorReport {
+    /** The directory every answer here is about: where the project's packages are looked for. */
+    consumer_directory: string;
+    /** What can run here, one operation at a time. */
+    operations: DoctorOperations;
     checks: DoctorCheck[];
     summary: {
         ok: number;
@@ -78,11 +289,31 @@ interface DoctorReport {
         fail: number;
     };
 }
-declare function doctor({ cwd, contract }: {
+declare function doctor({ cwd, contract, parser, }: {
     cwd: string;
     contract: Contract;
+    /** What resolving TypeScript from `cwd` found. Resolved here when it is not passed. */
+    parser?: ParserProbe;
 }): DoctorReport;
 
+interface InputSchema {
+    type: "object";
+    properties: Record<string, PropertySchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    description?: string;
+}
+interface PropertySchema {
+    type: "string" | "number" | "integer" | "boolean";
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+}
+
 interface McpContext {
     contract: Contract;
     registry: Registry;
@@ -90,78 +321,17 @@ interface McpContext {
     typescript?: TypeScript | null;
     cwd?: string;
 }
-declare const TOOLS: ({
+interface ToolDefinition {
     name: string;
     description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            query: {
-                type: string;
-                description: string;
-            };
-            limit: {
-                type: string;
-                description: string;
-            };
-            name?: never;
-            dense?: never;
-            code?: never;
-        };
-        required: string[];
+    inputSchema: InputSchema;
+    /** The result model for this tool's answers; a failure comes in the same place. */
+    outputSchema: object;
+    annotations: {
+        readOnlyHint: true;
     };
-} | {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            name: {
-                type: string;
-                description: string;
-            };
-            dense: {
-                type: string;
-                description: string;
-            };
-            query?: never;
-            limit?: never;
-            code?: never;
-        };
-        required: string[];
-    };
-} | {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            query?: never;
-            limit?: never;
-            name?: never;
-            dense?: never;
-            code?: never;
-        };
-        required?: never;
-    };
-} | {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            code: {
-                type: string;
-                description: string;
-            };
-            query?: never;
-            limit?: never;
-            name?: never;
-            dense?: never;
-        };
-        required: string[];
-    };
-})[];
+}
+declare const TOOLS: readonly ToolDefinition[];
 /**
  * Answer one message. Returns the response to write, or null for a notification, which gets none.
  * `raw` is a parsed message, or the line itself when it could not be parsed.
@@ -197,7 +367,6 @@ declare function parseArgs(args: string[]): Command;
 
 declare function resolveEntries(names: string[], registry: Registry): RegistryEntry[];
 
-declare const VERSION: string;
 declare const registry: Registry;
 /** The contract this installer carries, read from beside it the first time it is asked for. */
 declare const contract: () => Contract;
@@ -208,4 +377,4 @@ declare function install(options: AddOptions, context?: {
     registry?: Registry;
 }): InstallResult;
 
-export { AddOptions, type Answer, type CheckReport, Command, Contract, DEFAULT_OUT, type DoctorCheck, type DoctorReport, type Envelope, type Finding, type InitFile, type InitOptions, type InitResult, InstallResult, type McpContext, Registry, RegistryEntry, TOOLS, type TypeScript, VERSION, checkPaths, checkSource, contract, doctor, handleMessage, init, install, parseArgs, registry, resolveEntries, runAgentCommand, serve };
+export { AddOptions, type Answer, type CheckReport, Command, ComponentDetail, type ComponentDetailData, Contract, DEFAULT_OUT, type DoctorCheck, type DoctorReport, type Envelope, type ErrorEnvelope, type ErrorIdentity, type EvaluationStatus, type Finding, type Identity, type InitFile, type InitOptions, type InitResult, InstallResult, type Limitation, type McpContext, RESULT_SCHEMAS, RESULT_SCHEMA_VERSION, RESULT_TYPES, Registry, RegistryEntry, type ResultType, type SkippedInput, type SourceEvaluation, TOOLS, type TypeScript, VERSION, buildCheckReport, checkExitCode, checkPaths, checkSource, contract, contractDigest, doctor, envelope, errorEnvelope, handleMessage, identityOf, init, install, outputSchemaFor, parseArgs, registry, renderCheckText, resolveEntries, runAgentCommand, schemaFor, serve };