@dsh-cc/tools 0.5.0

package/lib/presentation.d.ts

@@ -0,0 +1,367 @@
+/**
+ * Tool render-intent vocabulary: the provider-neutral types a tool declares via
+ * `ToolDefinition.presentCall`/`ToolDefinition.presentResult` to say how one of its calls
+ * renders in a UI (an editor's tool-call card, a CLI log line).
+ * @module @dsh-cc/tools/src/presentation
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+/**
+ * Category of a tool call, used by a UI to pick an icon or treatment. The
+ * provider-neutral vocabulary lets tools describe themselves without depending
+ * on a particular client; `other` is the default.
+ */
+export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';
+/**
+ * A file location a tool reads or modifies, so a capable UI can "follow along" —
+ * highlight or jump to the file (and line) as the tool runs. `path` is what the
+ * tool operated on (the model-facing path); `line` is an optional 1-based line
+ * to focus (e.g. a read's offset).
+ */
+export interface FileLocation {
+    path: string;
+    line?: number;
+}
+/**
+ * A single-file change a tool is about to make, for a UI that renders inline
+ * diffs. `oldText` is `null` for a new-file create (nothing to diff against);
+ * an overwrite also uses `null`, because a call-time presenter has no access to
+ * the file's prior content.
+ */
+export interface FileDiff {
+    path: string;
+    /** Prior content, or `null` for a new file / an overwrite (no prior content available at call time). */
+    oldText: string | null;
+    /** Content after the change. */
+    newText: string;
+}
+/**
+ * Provider-neutral pending-call presentation. Tools declare one tagged intent;
+ * UI bridges map it without special-casing tool names.
+ */
+export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;
+/**
+ * The default card: a titled tool-call row with an optional category icon, a
+ * salient raw input, extra content blocks, and follow-along file locations. Any
+ * tool whose call is not a terminal or a diff uses this.
+ */
+export interface GenericCallView {
+    card: 'generic';
+    /**
+     * Human-readable, always-visible label describing what THIS call does. Keep it
+     * short — a UI shows it as a card header / log line.
+     */
+    title: string;
+    /** Category for icon/treatment; defaults to `other` when omitted. */
+    kind?: ToolCallKind;
+    /**
+     * The salient input to show in a detail/expanded view (e.g. a background
+     * job id). Omit to show nothing; a string renders as-is, an object as pretty
+     * JSON. NOT the full raw args object unless that is genuinely what a reader wants.
+     */
+    rawInput?: unknown;
+    /**
+     * UI-facing content blocks to show on the pending call alongside the title.
+     * Omit to show none. A UI maps these to its own content blocks.
+     */
+    content?: ContentBlock[];
+    /** Files this call reads/modifies, for editor follow-along. Omit for a call that touches no file. */
+    locations?: FileLocation[];
+}
+/**
+ * A call that IS a shell command running in a working directory: a capable UI
+ * renders it as a terminal card (cwd-headed, with the command as the title and
+ * live/afterward output from the {@link TerminalResultView}); an incapable UI
+ * falls back to a generic card whose body is the fenced command output. Set by a
+ * tool whose call is a foreground command (e.g. `bash`).
+ */
+export interface TerminalCallView {
+    card: 'terminal';
+    /** The command, shown as the terminal card's title / header line. */
+    title: string;
+    /**
+     * A human-readable one-line summary of what the command does, rendered ABOVE
+     * the terminal card (the card itself has no description slot). Omit for none.
+     */
+    description?: string;
+    /**
+     * Working directory the command runs in, shown as the terminal header. An
+     * ABSOLUTE path is used as-is; a RELATIVE path is resolved by the UI bridge
+     * against the session workspace (the pure presenter can't see the session cwd).
+     * Omit entirely to let the bridge use the session workspace.
+     */
+    cwd?: string;
+}
+/**
+ * A call that creates or modifies files, rendered as an inline diff card by a
+ * capable UI. Set by a tool whose call writes/edits a file (e.g. `write`,
+ * `edit`). The diffs are derived from the call ARGUMENTS (a create's `oldText` is
+ * `null`); the tool emits a separate {@link DiffResultView} after `execute` — the
+ * applied change (an edit/overwrite hunk with context, or a whole-file diff for a
+ * create).
+ */
+export interface DiffCallView {
+    card: 'diff';
+    /** Card header (e.g. `Write foo.txt`). */
+    title: string;
+    /** One entry per file the call changes. */
+    diffs: FileDiff[];
+    /** Files this call modifies, for editor follow-along (usually the diffs' paths). */
+    locations?: FileLocation[];
+}
+/**
+ * One numbered line of a file, the unit a {@link ReadResultView} carries so a
+ * capable UI can render a syntax-highlighted, line-numbered code view. `number`
+ * is the 1-based line number in the file (a window past `offset` keeps the file's
+ * own numbering, not a 1-based re-count); `text` is the line without its trailing
+ * newline, already truncated to the read tool's per-line cap.
+ */
+export interface ReadFileLine {
+    number: number;
+    text: string;
+}
+/**
+ * How a tool wants the COMPLETED call shown — the *result* state, after `execute`
+ * returns. A `card`-tagged union mirroring {@link ToolCallView}: a UI switches on
+ * `card`. Lets the tool reformat its result for a UI distinctly from the
+ * model-facing text it returned from `execute`. Returned by
+ * `ToolDefinition.presentResult`; omitting the method keeps the pending
+ * title and renders the raw result content.
+ */
+export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;
+/**
+ * The default completed card: an optional replacement title and reformatted
+ * content. Omit a field to keep the pending title / render the raw result content.
+ */
+export interface GenericResultView {
+    card: 'generic';
+    /** Replacement title for the completed call. Omit to keep the pending-state title. */
+    title?: string;
+    /**
+     * UI-facing result content (harness {@link ContentBlock}s), reformatted from
+     * the model-facing result. Omit to let the UI render the raw result content.
+     */
+    content?: ContentBlock[];
+}
+/**
+ * The completed state of a {@link TerminalCallView}: the captured output and exit
+ * status. A capable UI renders `output` in the terminal card and shows an
+ * exit-status pill; an incapable UI gets a fenced ```console fallback the BRIDGE
+ * derives from `output` (the tool does not double-encode it).
+ */
+export interface TerminalResultView {
+    card: 'terminal';
+    /** Replacement title for the completed call. Omit to keep the pending-state title. */
+    title?: string;
+    /** Captured command output (stdout+stderr as the tool chooses to combine them). */
+    output?: string;
+    /**
+     * Process exit code, when the run ended by exiting (not a signal). Lets a
+     * capable UI show an exit-status pill. Omit when killed by a signal or unknown.
+     */
+    exitCode?: number;
+    /** Signal name that killed the process (e.g. `SIGTERM`). Mutually exclusive with `exitCode`. */
+    signal?: string;
+}
+/**
+ * A completed file mutation rendered as an inline diff card, the result-time
+ * analogue of {@link DiffCallView}. Because a completed UI update replaces the
+ * pending card content, mutation tools return this even when it repeats the
+ * call-time diff; otherwise raw result text would replace the diff.
+ */
+export interface DiffResultView {
+    card: 'diff';
+    /** Replacement title for the completed call. Omit to keep the pending-state title. */
+    title?: string;
+    /** The change to show, in file order — applied contextual hunks, or a whole-file diff when there is no before-image. */
+    diffs: FileDiff[];
+}
+/** One matched line inside a {@link SearchFileMatches} group: its 1-based line number and text. */
+export interface SearchLineMatch {
+    /** 1-based line number of the match within its file. */
+    lineNumber: number;
+    /** The matched line text, as the tool surfaced it (the per-line preview budget already applied). */
+    line: string;
+}
+/** One file's grouped content matches for a {@link SearchMatchesResultView}, in first-seen file order. */
+export interface SearchFileMatches {
+    /** The file the matches belong to (the model-facing display path). */
+    path: string;
+    /** The file's matched lines, in output order. */
+    matches: SearchLineMatch[];
+}
+/**
+ * A completed content search (`grep`) rendered as a search card whose matches are
+ * grouped by file, so a capable UI can list each file as an expandable group of
+ * its matched lines. `shape: 'matches'` discriminates this variant from the path
+ * variant ({@link SearchPathsResultView}) within {@link SearchResultView}. The
+ * discriminant is `shape`, not `kind`, so it never collides with the
+ * {@link ToolCallKind} `kind` an icon-picking bridge reads off a call view.
+ */
+export interface SearchMatchesResultView {
+    card: 'search';
+    shape: 'matches';
+    /** Replacement title for the completed call. Omit to keep the pending-state title. */
+    title?: string;
+    /** Matched lines grouped by file, in first-seen file order. */
+    files: SearchFileMatches[];
+    /**
+     * Whether the tool capped the inline result: `files` carries only the retained
+     * matches, not every match the search found. A UI shows a capped indicator so it
+     * never presents a partial group as complete.
+     */
+    truncated: boolean;
+    /** Total matches the search found before capping (equals the retained count when not `truncated`). */
+    total: number;
+}
+/**
+ * A completed path search (`glob`) rendered as a search card whose result is a flat
+ * path list. `shape: 'paths'` discriminates this variant from the grouped-matches
+ * variant ({@link SearchMatchesResultView}) within {@link SearchResultView}.
+ */
+export interface SearchPathsResultView {
+    card: 'search';
+    shape: 'paths';
+    /** Replacement title for the completed call. Omit to keep the pending-state title. */
+    title?: string;
+    /** The discovered paths, in the tool's result order (the retained page when `truncated`). */
+    paths: string[];
+    /**
+     * Whether the tool capped the inline result: `paths` carries only the retained
+     * page, not every path the search found. A UI shows a capped indicator so it
+     * never presents a partial list as complete.
+     */
+    truncated: boolean;
+    /** Total paths the search found before capping (equals `paths.length` when not `truncated`). */
+    total: number;
+}
+/**
+ * A completed search rendered as a search card, the result-time view a discovery
+ * tool (`grep`, `glob`) returns from `presentResult`. One `card: 'search'` view
+ * with two `shape`-discriminated variants: grouped-by-file content matches
+ * ({@link SearchMatchesResultView}) and a flat path list
+ * ({@link SearchPathsResultView}). Both carry a `truncated`/`total` signal so a UI
+ * never presents a capped result as complete. The view carries no result text: a
+ * UI without a search card falls back to the raw `tool/result` content. There is
+ * no call-time analogue: a search call stays a {@link GenericCallView}
+ * (`kind: 'search'`) because the pending state has no matches or paths to show —
+ * the structured shape exists only after `execute`.
+ */
+export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;
+/**
+ * A completed file read rendered as a line-numbered, optionally syntax-highlighted
+ * code view by a capable UI. Set by a tool whose call reads file text (e.g.
+ * `read`); the pending state stays a {@link GenericCallView} (`kind: 'read'`)
+ * because a call carries no content until `execute` returns. The structured
+ * `lines`/`path`/`lang`/`totalLines` fields cannot be reconstructed from the
+ * model-facing result text alone, so the read tool projects them through its
+ * `output.presentationMeta` (persisted with the session log) and `presentResult`
+ * narrows that metadata back into this view on live and replay paths alike. A UI
+ * without the read capability falls back to `content` (the model-facing text with
+ * its envelope stripped), so this view degrades to the generic text card.
+ */
+export interface ReadResultView {
+    card: 'read';
+    /** Replacement title for the completed call. Omit to keep the pending-state title. */
+    title?: string;
+    /** The read file's path (the model-facing path; the bridge relativizes it). */
+    path: string;
+    /**
+     * The 1-based first line the window requested, preserved even when `lines` is
+     * empty (a byte cap below the first selected line yields an empty window) so a
+     * UI knows where the window starts and where a continuation resumes.
+     */
+    offset: number;
+    /** The returned window's lines, in file order, each keeping its file line number. */
+    lines: ReadFileLine[];
+    /** Exact total line count in the file, so a UI can show a "showing N of M" affordance. */
+    totalLines: number;
+    /**
+     * A syntax-highlighting language hint derived from the file extension (e.g.
+     * `ts`, `py`), or omitted when the extension maps to no known language so a UI
+     * renders the lines as plain text.
+     */
+    lang?: string;
+    /**
+     * The model-facing result content with its envelope stripped, for a UI without
+     * the read capability. Omit to let such a UI render the raw result content.
+     */
+    content?: ContentBlock[];
+}
+/**
+ * One citeable source in a completed {@link WebSearchResultView}, the faithful
+ * projection of one web-search source. The presentation projection of `dsh-web`'s
+ * `WebSearchSource`: that Service Definition type is authoritative (core cannot depend
+ * on the web Service Definition, so the two are declared separately and MUST evolve together).
+ * A web tool projects this shape through `output.presentationMeta` because the
+ * render text cannot losslessly carry it (see the web-result-card Agent Note); its
+ * `presentResult` reads it back.
+ */
+export interface WebSource {
+    /** The source URL. */
+    url: string;
+    /** The source title, when the provider returned one. */
+    title?: string;
+    /** A short excerpt or summary, when the provider returned one. */
+    snippet?: string;
+    /** Publication/crawl timestamp as a provider-supplied ISO-8601 string, when present. */
+    publishedAt?: string;
+}
+/**
+ * A completed web retrieval rendered as a structured card by a capable UI. Set
+ * by a web tool whose call retrieves from the web (`web_search`, `web_fetch`).
+ * One `kind`-tagged union carries both shapes because both are web retrieval and
+ * a UI renders them with one component family; a UI switches on `kind`. An
+ * incapable UI falls back to the raw `tool/result` content (this view carries no
+ * `content` copy — see the web-result-card Agent Note). This is the result-time
+ * analogue of the `web_search`/`web_fetch` calls' generic call views
+ * (`kind: 'search'`/`'fetch'`); those tools keep their generic pending card and
+ * add only this completed card.
+ *
+ * The `kind` field here is this union's own discriminant, NOT a
+ * {@link ToolCallKind}: the two values deliberately match the tools' pending
+ * `ToolCallKind` (`'search'`/`'fetch'`) so a call and its result read as one
+ * category, but a new arm is a union edit plus a consumer branch, not any
+ * arbitrary `ToolCallKind` value.
+ */
+export type WebResultView = WebSearchResultView | WebFetchResultView;
+/**
+ * The completed state of a `web_search` call: the structured sources the model
+ * cited, an optional provider answer, and whether the source list was cut to the
+ * result cap. A capable UI renders the sources as a citation list; a UI without
+ * the `web` capability falls back to the raw `tool/result` content.
+ */
+export interface WebSearchResultView {
+    card: 'web';
+    kind: 'search';
+    /** Replacement title for the completed call. Omit to keep the pending-state title. */
+    title?: string;
+    /** The faithful, structured sources — the field render text cannot losslessly carry. */
+    sources: WebSource[];
+    /** The provider-generated answer text, when any. */
+    answer?: string;
+    /** True when the web service cut the source list to honor the result cap. */
+    truncated: boolean;
+}
+/**
+ * The completed state of a `web_fetch` call: the fetched URL, its HTTP status,
+ * and whether the content was cut. The body itself is already markdown in the
+ * raw `tool/result` content, so this card carries only the retrieval summary and
+ * a UI without the `web` capability falls back to that content.
+ */
+export interface WebFetchResultView {
+    card: 'web';
+    kind: 'fetch';
+    /** Replacement title for the completed call. Omit to keep the pending-state title. */
+    title?: string;
+    /** The final URL after allowed redirects. */
+    url: string;
+    /** HTTP status code of the fetched response. */
+    statusCode: number;
+    /**
+     * True when the provider capped the decoded body, or the output cap or a
+     * pre-conversion source cut trimmed the rendered text (the effective
+     * truncation the model-facing text also reflects).
+     */
+    truncated: boolean;
+}
+//# sourceMappingURL=presentation.d.ts.map

package/lib/presentation.d.ts.map

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

package/lib/presentation.js

@@ -0,0 +1,8 @@
+/**
+ * Tool render-intent vocabulary: the provider-neutral types a tool declares via
+ * `ToolDefinition.presentCall`/`ToolDefinition.presentResult` to say how one of its calls
+ * renders in a UI (an editor's tool-call card, a CLI log line).
+ * @module @dsh-cc/tools/src/presentation
+ */
+export {};
+//# sourceMappingURL=presentation.js.map

package/lib/presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.js","sourceRoot":"","sources":["../src/presentation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/lib/py-names.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Naming, state, and text-escaping machinery shared by the Python SDK renderers
+ * (`py-types.ts`, `py-render.ts`, `py-sdk-doc.ts`). Leaf module: imports nothing
+ * from its siblings, so any of them may depend on it without creating cycles.
+ * Split out of `py-types.ts` for the line budget.
+ * @module @dsh-cc/tools/src/py-names
+ */
+/**
+ * Whether a name can be emitted as a bare Python identifier rather than
+ * routed to the subscript/`dict[str, Any]` path.
+ *
+ * Python identifiers are not ASCII: `路径` is as legal a field name as `path`,
+ * and rejecting it would degrade the whole enclosing object, dropping every
+ * field's name, requiredness, and type — information whose only source under
+ * `mode: 'code'` is this generated text.
+ *
+ * NFKC stability is a second and separate condition, because CPython
+ * normalizes identifiers at compile time while JSON keys are compared as
+ * written: `field` would be declared and reachable as `field`, so the SDK would
+ * advertise a key under a spelling the harness never accepts, and two keys
+ * that normalize together would collapse into one declaration. Those names
+ * take the subscript path, which carries their exact bytes.
+ *
+ * `IDENTIFIER` matches `str.isidentifier()` (measured on Node 22.23.1 vs
+ * CPython 3.9.6 tables): the equivalence holds inside the two versions' shared
+ * tables, and the skew characters below are exactly where that pair diverges.
+ * The predicate as a whole is deliberately stricter than `isidentifier()`,
+ * which does not test NFKC stability: `'field'.isidentifier()` is True and
+ * this returns false.
+ *
+ * Both conditions are evaluated against the ENGINE's Unicode tables, and the
+ * two sides are versioned independently — `\p{XID_Start}`/`\p{XID_Continue}`
+ * follow the running engine (Node 22.23.1 reports Unicode 17.0) while CPython
+ * follows its own (3.9.6 reports 13.0.0). The skew is not symmetric. A CPython
+ * older than the engine is the dangerous direction: a character added to either
+ * property since its tables (U+10570 Vithkuqi and U+1E290 Toto, 14.0; U+1E4D0
+ * Nag Mundari, 15.0; U+1C89 Cyrillic TJE, 16.0 — ages per `DerivedAge.txt`; all
+ * four are NFKC-stable and accepted here, and all four are `Cn` on that 3.9.6,
+ * which rejects them) is emitted bare and its tokenizer refuses the character,
+ * taking the whole SDK block down — the same parseability invariant
+ * {@link UNPRINTABLE}, {@link LONE_SURROGATE} and {@link MAX_LIST_NESTING}
+ * exist for. Both properties carry it: a character added only to `XID_Continue`
+ * passes the trailing `\p{XID_Continue}*` in a tail position and fails the same
+ * way — U+200C ZWNJ and U+200D ZWJ are that case, gaining `XID_Continue` in UCD
+ * 15.1 and absent from it in 13.0.0, 14.0.0 and 15.0.0, so `a\u{200C}b` is
+ * emitted bare here while `isidentifier()` is False on 3.9.6 and on 3.12.13
+ * (15.0.0). A CPython newer than the engine only routes a legal name to the
+ * subscript/`dict[str, Any]` path: less readable, still correct. The NFKC
+ * condition reduces to the same skew, since normalization stability guarantees
+ * an assigned character's normalization never changes afterwards.
+ *
+ * This predicate is not the only reader of engine tables. {@link camelCase}
+ * reads them at three further points — its split set, its head test, and its
+ * `toUpperCase()` case mapping — and this predicate's verdict gates none of
+ * them: a class name derived there reaches emitted text whenever any object
+ * shape in the tool's schema declares a `TypedDict`, including for a tool this
+ * predicate rejected. A tool named `zz-\u{1E4D0}x` with such parameters never
+ * reaches the skew here (the `-` rejects it outright) yet emits `class
+ * Zz\u{1E4D0}xArgs`, which that same 3.9.6 refuses — Nag Mundari arrived two
+ * releases after its tables. The case mapping is a separate table rather than
+ * an XID membership test, and it fails on names both conditions above accept:
+ * `\u{019B}` is XID_Start and NFKC-stable, so this predicate accepts it and
+ * `async def \u{019B}` compiles on 3.9.6, but Node uppercases it to
+ * `\u{A7DC}` — unassigned in that CPython, whose own `.upper()` is the identity
+ * here — and the declared `class \u{A7DC}Args` fails with `invalid
+ * non-printable character U+A7DC`. Closing the exposure therefore covers all
+ * four read points, not this predicate alone; it needs the target interpreter's
+ * version, which the backend reporting `language: 'python'` owns; the
+ * language-dispatch Agent Note records the deferral.
+ *
+ * The `ts-types` sibling keeps its own ASCII rule rather than sharing this
+ * one: ECMAScript identifiers are a different set (`$`) and are never
+ * normalized, so one predicate cannot be correct for both. ZWJ/ZWNJ are not
+ * part of that difference — both sets carry them on the engine's tables; what
+ * separates the two there is the CPython table version above.
+ * @param name - the raw schema field or tool name.
+ * @returns whether the name can be emitted bare.
+ */
+export declare function isBareIdentifier(name: string): boolean;
+/**
+ * Python hard keywords: reserved everywhere, so a tool or field named
+ * ``class`` or ``lambda`` is legal on the wire but not as an attribute
+ * (``tools.class`` would be a SyntaxError in the model program) and not as a
+ * class-syntax `TypedDict` field. Such a tool renders under subscript access
+ * and such an object degrades to ``dict[str, Any]`` — the model still reaches
+ * every tool and field without collisions.
+ * Soft keywords (``match``, ``case``, ``type``, ``_`` — the language
+ * reference's whole set) are deliberately ABSENT: each is special in exactly
+ * one syntactic position — a statement head (``match``, ``type``), a ``match``
+ * statement's clause head (``case``), or a pattern (``_``) — so ``match: str``
+ * as a field and ``async def match(...)`` as a method are both legal, and
+ * including them would needlessly degrade common search/regex tool fields to
+ * ``dict[str, Any]``. Underscore-leading names are handled separately, not
+ * here: a non-dunder ``__token`` name-mangles, a dunder present on
+ * ``object``/``type`` resolves before the proxy hook, and implicit
+ * special-method lookup bypasses the hook.
+ */
+export declare const RESERVED: Set<string>;
+/** `indent`-deep line prefix (four spaces per level to match PEP 8 output). */
+export declare function pad(indent: number): string;
+/**
+ * Collector threaded through the type renderer: the emitted `TypedDict` class
+ * declarations (nested classes precede the parent that references them), the
+ * class names already taken (for collision suffixing), a per-base collision
+ * counter, and the `typing` symbols the render actually used.
+ */
+export interface RenderState {
+    readonly classes: string[];
+    readonly usedClassNames: Set<string>;
+    /** Next collision counter per capped base, so allocation is amortized O(1) instead of rescanning from `2`. */
+    readonly nextClassCounter: Map<string, number>;
+    readonly typing: Set<string>;
+}
+/**
+ * The collapsed one-line `description` of a schema node (byte-stable across
+ * formatting churn), or `undefined` when the node carries none. Every caller
+ * passes an object — a validated property node, the `ToolSdkSchema` itself, or
+ * the `{ description }` wrapper {@link docLines} synthesizes — so only the
+ * description field needs guarding. A description that collapses
+ * to nothing (empty, or whitespace only) is `undefined` too: it documents the
+ * node no better than an absent one, and emitting it would leave an empty
+ * `"""` docstring or a bare `#   ` line in the SDK. Only ECMAScript whitespace
+ * folds, so a description of whitespace plus one surviving control character is
+ * NOT absent: it collapses to that character's visible escape.
+ *
+ * Control characters left over after the whitespace collapse are rendered as
+ * their `\xNN` escapes (see {@link UNPRINTABLE}) and unpaired surrogates as
+ * their `\uNNNN` escapes (see {@link LONE_SURROGATE}); the escape's own backslash is
+ * emitted literally by both consumers, since {@link docLines} doubles it into a
+ * Python source escape and a `#` comment carries it verbatim.
+ */
+export declare function describe(schema: object): string | undefined;
+/**
+ * CamelCase a name into a Python type identifier: non-identifier characters
+ * split words, `_` splits too (it is `XID_Continue`, so the split set names it
+ * explicitly), and a head that cannot start an identifier takes a `Tool`
+ * prefix. Unicode survives, so a `路径` field yields `路径`-based class names
+ * instead of collapsing to the bare prefix. A character that is not
+ * `XID_Continue` splits even when it is a letter, so a name whose NFKC folding
+ * would leave the identifier set is not carried through — the split set is the
+ * grammar's, not an ASCII approximation of it.
+ *
+ * The result is NFKC-normalized: these names are generated, never matched
+ * against a JSON key, so normalizing is free here and keeps what CPython
+ * compiles identical to what is emitted — unlike {@link isBareIdentifier},
+ * which must reject unstable names outright. Normalizing AFTER the prefix
+ * decision is what makes that hold at the seam the prefix creates: `Tool` +
+ * a combining-mark head composes there (`U+0301` gives `Tooĺ`, U+013A), so
+ * normalizing only the un-prefixed part would emit a name CPython compiles to
+ * a different symbol. The second call is idempotent on the un-prefixed arm.
+ *
+ * The split set, the head test, and `toUpperCase()` all read the engine's
+ * Unicode tables, so this function carries the same version skew
+ * {@link isBareIdentifier} documents, by paths independent of it: a class name
+ * derived here reaches emitted text whenever any object shape in the tool's
+ * schema declares a `TypedDict`, and the predicate's verdict on the tool name
+ * does not gate that. The case mapping is the one that can fail on a name the
+ * predicate accepted; the worked example is there.
+ * @param raw - the schema field or tool name to derive from.
+ * @returns a class-name segment safe to emit.
+ */
+export declare function camelCase(raw: string): string;
+//# sourceMappingURL=py-names.d.ts.map

package/lib/py-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"py-names.d.ts","sourceRoot":"","sources":["../src/py-names.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,QAAQ,aASnB,CAAA;AAEF,+EAA+E;AAC/E,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;IAC1B,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACpC,8GAA8G;IAC9G,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9C,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAC7B;AAqDD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAS3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ7C"}