create-nola-lang 0.1.2 → 0.1.4

package/skills/nola/references/patterns.md

@@ -0,0 +1,277 @@
+# Nola patterns — worked examples
+
+## The starter project, end to end
+
+This is the shape every Nola project takes: `.tsi` files hold the infer
+functions, a plain `.ts` entry point calls them, and `nola run` executes the
+entry with the loader and `nola.config.ts` in place.
+
+```
+my-app/
+  nola.config.ts        # providers
+  package.json          # nola-lang in devDependencies
+  tsconfig.json         # include: ["src"]
+  src/
+    person.tsi          # the Nola source
+    main.ts             # a plain TypeScript consumer
+```
+
+`src/person.tsi` — the type and the infer function live together:
+
+```tsi
+export interface Person {
+  name: string;
+  age: number;
+  employer: string;
+  job: string;
+}
+
+export infer function extractPerson(.message: string) {
+  const person = ask ..`the person described in the text`<Person>;
+  return person;
+}
+```
+
+`src/main.ts` — plain TypeScript. Note the literal `.tsi` extension in the
+import, and that `await` on the returned `Intent` is what runs the inference:
+
+```ts
+import { extractPerson } from "./person.tsi";
+
+const person = await extractPerson(
+  "Alice Smith, 32, is a staff engineer at Acme Corp working on distributed systems.",
+);
+console.log(JSON.stringify(person));
+```
+
+Run it:
+
+```bash
+nola run src/main.ts        # or: npm start
+nola check                  # type-checks .tsi and .ts together
+nola build                  # dist/ — plain JS + source maps + .d.ts
+```
+
+## Composing several asks in one invocation
+
+Every `ask` in one invocation shares that invocation's context — the `..`
+contextual parameters and the function's instruction marker. That is what lets
+you split one big prompt into several small, individually-typed asks instead of
+demanding everything at once.
+
+What is NOT shared is the answers. Earlier results are recorded on the
+invocation's frame, but history does not compose into later prompts yet: a
+later ask does NOT see what an earlier ask returned. When it needs an earlier
+answer, pass it forward explicitly with `${}` interpolation.
+
+```tsi
+export infer function solve(.problem: string) {
+  // Both asks see `problem` (the contextual parameter). They do NOT see each
+  // other's answers automatically — the reasoning is handed to the second ask
+  // explicitly through `${}`.
+  const reasoning = ask ..`think step by step about the problem before answering`;
+  const answer = ask ..`the final numeric answer, given this reasoning: ${reasoning}`<number>;
+  return { reasoning, answer };
+}
+```
+
+Once an `ask` returns, its result is an ORDINARY typed value — branch on it,
+pass it to plain functions, put it in an object literal, interpolate it into a
+later prompt:
+
+```tsi
+export type Category = "billing" | "refund" | "fraud" | "other";
+
+export infer function classifyMessage(.message: string) {
+  const category = ask ..`the category of the customer message`<Category>;
+  const urgent = ask ..`does the message need urgent attention`<"yes" | "no">;
+
+  // plain TS from here on
+  if (category === "fraud") return { category, urgent: true, escalate: true };
+  return { category, urgent: urgent === "yes", escalate: false };
+}
+```
+
+Plain TypeScript orchestrates the loop; the infer functions stay small:
+
+```tsi
+// src/research.tsi
+export interface Conclusion {
+  answer: string;
+  /** the collected notes that directly support the answer */
+  evidence: string[];
+}
+
+export infer function nextQuery(.question: string, .notes: string[]) {
+  return ask ..`the single best search query to advance the research; keywords only`<string>;
+}
+
+export infer function conclude(.question: string, .notes: string[]) {
+  return ask ..`answer the research question using only the collected notes`<Conclusion>;
+}
+```
+
+```ts
+// src/main.ts
+import { conclude, nextQuery } from "./research.tsi";
+import { search } from "./search.js";
+
+const question = "who maintains the project?";
+const notes: string[] = [];
+for (let i = 0; i < 3; i++) {
+  const query = await nextQuery(question, notes);
+  notes.push(await search(query));
+}
+const conclusion = await conclude(question, notes);
+```
+
+## Call intents — let the LLM fill a function's arguments
+
+When you already have a function that DOES something, do not extract its
+arguments one at a time and then call it. Make the call itself the intent: the
+LLM fills every extractor-shaped argument in one provider call, and the
+function runs with the results.
+
+`src/tickets.ts` — an ordinary TypeScript helper, nothing Nola about it:
+
+```ts
+export async function createTicket(title: string, priority: number): Promise<string> {
+  const res = await fetch("https://example.test/tickets", {
+    method: "POST",
+    body: JSON.stringify({ title, priority }),
+  });
+  return (await res.json()).id as string;
+}
+```
+
+`src/file-ticket.tsi` — the helper is imported with the NodeNext `.js`
+specifier, and the call gets extractor arguments:
+
+```tsi
+import { createTicket } from "./tickets.js";
+
+export infer function fileTicket(.request: string) {
+  // Sigil-less: the extractor argument makes this call an intent. `2` is a
+  // plain argument and is passed through untouched.
+  const id = ask createTicket(..`a short ticket title for the request`<string>, 2);
+  return id;
+}
+```
+
+Add instruction text for the call with the marker form — it is the only
+spelling that carries a hint:
+
+```tsi
+export infer function fileTicketCarefully(.request: string) {
+  return ask createTicket`file the ticket exactly as the customer described it`(
+    ..`a short ticket title`<string>,
+    ..`priority 1-5, where 1 is most urgent`<number>,
+  );
+}
+```
+
+Every extractor slot needs an explicit `<T>`, and all slots of one call
+resolve together in a single provider round trip.
+
+`createTicket` is async, but `id` is a `string`, not a `Promise<string>` — a
+call intent awaits a promise-returning callee itself (`ask` ≈ `await`), so
+`await ask createTicket(...)` is redundant. Because the callee runs inside the
+ask, `.withRetry(n)` on a call intent re-invokes it on failure — only use it
+when the target is idempotent.
+
+## Typing the answers
+
+Prefer a NAMED, exported `type` or `interface` for `<T>` over an inline object
+literal: it documents the contract, it is reusable from plain TS, and JSDoc
+comments on its members become descriptions in the schema the LLM sees.
+
+```tsi
+export interface LineItem {
+  description: string;
+  quantity: number;
+  /** price per unit in USD */
+  unitPrice: number;
+}
+
+export interface Invoice {
+  invoiceNumber: string;
+  issuedTo: string;
+  lineItems: LineItem[];
+  /** grand total in USD */
+  total: number;
+  /** ISO date; omit when the document has none */
+  dueDate?: string;
+}
+
+export infer function extractInvoice(.document: string) {
+  return ask ..`the invoice data from the document`<Invoice>;
+}
+```
+
+Closed label sets keep the model on-rails — a string-literal union, a string
+enum, or an inline union all work:
+
+```tsi
+export type Category = "billing" | "refund" | "fraud" | "other";
+
+export enum Sentiment {
+  Positive = "positive",
+  Neutral = "neutral",
+  Negative = "negative",
+}
+
+export infer function triage(.message: string) {
+  const category = ask ..`the category of the customer message`<Category>;
+  const sentiment = ask ..`the overall sentiment of the message`<Sentiment>;
+  const urgent = ask ..`does the message need urgent attention`<"yes" | "no">;
+  return { category, sentiment, urgent: urgent === "yes" };
+}
+```
+
+### Types from another file
+
+Cross-file types are supported. Import the type from a plain `.ts` file with a
+type-only import and the NodeNext `.js` specifier; the toolchain derives the
+schema for you:
+
+```ts
+// src/models.ts
+export interface Person {
+  name: string;
+  age: number;
+}
+```
+
+```tsi
+// src/report.tsi
+import type { Person } from "./models.js";
+
+export infer function extractPerson(.text: string) {
+  return ask ..`the person described in the text`<Person>;
+}
+```
+
+Recursive types are legal too:
+
+```tsi
+export type TreeNode = {
+  label: string;
+  children?: TreeNode[];
+};
+
+export infer function parseTree(.input: string) {
+  return ask ..`the tree structure described in the input`<TreeNode>;
+}
+```
+
+`Date` fields work and come back as real `Date` instances:
+
+```tsi
+export type CalendarEvent = { title: string; at: Date };
+
+export infer function nextEvent(.calendar: string) {
+  const event = ask ..`the next event on the calendar`<CalendarEvent>;
+  const when: Date = event.at;   // a Date, not a string
+  return when;
+}
+```

package/skills/nola/references/pitfalls.md

@@ -0,0 +1,289 @@
+# Common Nola errors and their fixes
+
+Diagnostic codes are stable: `NOLA1xxx` parse, `NOLA2xxx` compile, `NOLA3xxx`
+run time.
+
+## NOLA1009 — `ask with` needs a static provider name
+
+> expected a provider name after `ask with` — for a dynamic provider use
+> `.withProvider(...)` on the intent.
+
+The alias after `with` must be a bare identifier naming a key of the
+`providers` map in `nola.config.ts`. A string literal, a variable expression or
+a parenthesized expression will not parse.
+
+```tsi
+export infer function summarize(.text: string, useFast: boolean) {
+  // WRONG
+  const a = ask with "fast" ..`a rough summary`<string>;
+  const b = ask with providers.fast ..`a rough summary`<string>;
+
+  // RIGHT — name it in nola.config.ts, then use that name
+  const c = ask with fast ..`a rough summary`<string>;
+
+  // RIGHT — dynamic choice
+  const d = ask (..`a rough summary`<string>).withProvider(useFast ? "fast" : "careful");
+
+  return { a, b, c, d };
+}
+```
+
+```ts
+// nola.config.ts
+export default defineConfig({
+  providers: {
+    default: openai({ model: "gpt-5-mini" }),
+    fast: openai({ model: "gpt-5-nano" }),
+  },
+});
+```
+
+## NOLA1010 — `.` on a non-infer function
+
+> `.` context parameters are only allowed on infer function parameters.
+
+```tsi
+// WRONG — a plain function has no inference context to put the value in
+function summarize(.text: string) {
+  return text.slice(0, 10);
+}
+
+// RIGHT
+export infer function summarize(.text: string) {
+  return ask ..`a one-sentence summary`<string>;
+}
+```
+
+If the function is genuinely plain TypeScript, drop the `.`; the parameter is
+an ordinary argument.
+
+## NOLA2001 — `ask` outside an infer function body
+
+> `ask` is only allowed directly inside an infer function body.
+
+`ask` is not legal at module level, and not inside a nested closure — not even
+one written inside an infer function.
+
+```tsi
+// WRONG
+const kind = ask ..`the kind`<string>;                  // module level
+
+export infer function f(.t: string) {
+  const g = () => ask ..`the kind`<string>;             // nested closure
+  return g();
+}
+
+// RIGHT — ask directly in the body; from plain TS, await the infer function
+export infer function f(.t: string) {
+  return ask ..`the kind`<string>;
+}
+```
+
+Constructing an extractor outside a body is fine — only resolving it is
+restricted:
+
+```tsi
+export const nameIntent = ..`the user's full name`<string>;   // legal, inert
+```
+
+## NOLA2002 — a type the compiler cannot turn into a schema
+
+> unsupported type for intent schema: …
+
+An extractor's `<T>` must describe a JSON-shaped value: strings, numbers,
+booleans, `Date`, arrays, plain object/interface/type-alias shapes,
+string-literal unions, string enums, and references to those (same-file or
+imported). Ambient lib types like `Map`, `Set`, `RegExp`, functions and
+generics are not derivable.
+
+```tsi
+export infer function tally(.doc: string) {
+  // WRONG
+  const wrong = ask ..`counts per label`<Map<string, number>>;
+
+  // RIGHT — a JSON-shaped type; convert afterwards in plain TS
+  const counts = ask ..`counts per label`<{ label: string; count: number }[]>;
+  const asMap = new Map(counts.map((c) => [c.label, c.count]));
+  return asMap;
+}
+```
+
+Always give an extractor a concrete `<T>` in an expression position. An
+extractor is a value-producing expression; it is not a statement, a type, or a
+declaration.
+
+## NOLA2008 — an underivable `.` contextual parameter type
+
+> contextual parameter 'm' has a type that cannot be derived for inference:
+> unsupported type for intent schema: Map<string, number>. Set
+> compiler.underivableContextType to "prune" or "omit" in nola.config.ts to
+> allow it.
+
+The same derivability rules apply to contextual parameters, because their
+values are serialized into the prompt.
+
+```tsi
+// WRONG
+export infer function topLabel(.index: Map<string, number>) {
+  return ask ..`the label with the highest count`<string>;
+}
+
+// RIGHT — pass a JSON-shaped view as the contextual parameter
+export infer function topLabel(.index: { label: string; count: number }[]) {
+  return ask ..`the label with the highest count`<string>;
+}
+
+// RIGHT — keep the exotic value, but as a PLAIN parameter (the LLM never
+// sees its value, so nothing needs deriving)
+export infer function topLabel(.summary: string, index: Map<string, number>) {
+  const label = ask ..`the label with the highest count`<string>;
+  return { label, count: index.get(label) ?? 0 };
+}
+```
+
+If you must keep an underivable member on a contextual type, relax the policy
+in `nola.config.ts` — `"prune"` drops just the underivable members and keeps
+the rest of the type; `"omit"` drops the whole type silently:
+
+```ts
+export default defineConfig({
+  providers: { default: openai({ model: "gpt-5-mini" }) },
+  compiler: { underivableContextType: "prune" },   // default is "error"
+});
+```
+
+Keep that value a literal — the editor reads it statically and never executes
+your config.
+
+## NOLA2004 — a call-intent slot with no `<T>`
+
+> an extractor used as a call-intent argument must have an explicit `<T>`.
+
+```tsi
+declare function createTicket(title: string, priority: number): Promise<string>;
+
+export infer function fileTicket(.request: string) {
+  // WRONG — the slot has no type
+  const wrong = ask createTicket(..`a short ticket title`, 2);
+
+  // RIGHT
+  const id = ask createTicket(..`a short ticket title`<string>, 2);
+  return id;
+}
+```
+
+## NOLA3010 — bare `await` on a raw extract or call intent
+
+> extract/call intents carry no construction scope — only `ask` supplies their
+> frame.
+
+A raw extractor or call intent has no context of its own; it borrows the frame
+of the `ask` that resolves it. Awaiting one directly (typically from plain TS,
+or after storing it in a variable) throws at run time.
+
+```ts
+// WRONG — nothing supplies the inference context
+import { nameIntent } from "./person.tsi";
+const name = await nameIntent;
+```
+
+```tsi
+// RIGHT — resolve it with `ask` inside an infer function
+import { nameIntent } from "./person.tsi";
+
+export infer function whoIsIt(.text: string) {
+  return ask nameIntent;
+}
+```
+
+```ts
+// RIGHT — from plain TS, await the INFER FUNCTION's result (that is an
+// Intent, which does open its own invocation)
+import { whoIsIt } from "./person.tsi";
+
+const name = await whoIsIt("Alice Smith, 32, works at Acme Corp.");
+```
+
+## Import mistakes
+
+- `.tsi` imports keep the LITERAL extension:
+
+```ts
+import { extractPerson } from "./person.tsi";     // RIGHT
+import { extractPerson } from "./person";         // WRONG — unresolved
+import { extractPerson } from "./person.js";      // WRONG — no such file
+```
+
+- Plain TypeScript imports use the NodeNext `.js` specifier, even though the
+  file on disk is `.ts`:
+
+```ts
+import { createTicket } from "./tickets.js";      // RIGHT
+import { createTicket } from "./tickets.ts";      // WRONG — TS5097
+import { createTicket } from "./tickets";         // WRONG — TS2835
+```
+
+- Never import a `*.nola.*` module. Those are internal companion modules the
+  compiler generates for cross-file types; only generated code imports them,
+  and a hand-written file with such a name is NOLA2006.
+
+```ts
+import { Person } from "./models.nola.js";        // WRONG — internal
+import type { Person } from "./models.js";        // RIGHT
+```
+
+## Never write generated-code names
+
+`__nola` and any identifier starting with `__nola` are reserved in `.tsi`.
+`__nola.ask(...)`, `__nola.intents.ExtractIntent(...)`, `__nola.types.string()`
+and `__nola_file_ctx()` are what the compiler EMITS — they are not an API you
+call, and writing them by hand is an error.
+
+```tsi
+export infer function read(.doc: string) {
+  // WRONG — this is emitted code, not a user-facing API
+  const wrong = await __nola.ask(
+    __nola.intents.ExtractIntent({ instruction: "the value", type: __nola.types.string(), loc: "1:1" }),
+    __frame,
+  );
+
+  // RIGHT
+  const v = ask ..`the value`<string>;
+  return v;
+}
+```
+
+## NOLA2009 — `${.member}` outside a Nola instruction
+
+`${.x}` is prompt-scope access and only means something inside an
+infer-function marker, an extractor's backticks, or a call-intent hint. In a
+plain template literal it is an error — use a lexical value there.
+
+## NOLA2010 — a Nola construct inside a marker / call-hint hole
+
+Marker and call-hint literals are re-emitted from source, so `..`, call
+intents and `ask` cannot appear in their holes. Compute the value first and
+interpolate the result, or move the ask into the function body.
+
+## NOLA3014 — a prompt template rendered nothing (or threw)
+
+A `${.member}` template must produce text. An empty result usually means the
+template only read members that were undefined; a throw is a bug in the
+template's own JS. Fixed at the template — there is no retry.
+
+## NOLA3015 — running `.tsi` under Bun or Deno
+
+The loader is Node's module-hooks API; Bun and Deno do not run it. Any package
+manager is fine (`bun install`, `bun run start`, `pnpm start`, `yarn start` —
+the `nola` bin is a Node script), but `bun --bun`, `bun src/main.ts` and
+`deno run` cannot load `.tsi`. Run on Node: `nola run` or
+`node --import nola-lang/register src/main.ts`.
+
+## Other things that will not parse
+
+- `async infer function f(...)` — an infer function is never `async` in source;
+  `await` is already legal in its body.
+- `export default infer function f(...)` — export by name instead.
+- `infer` on a method, arrow function or function expression — top-level
+  function declarations only.
+- `fn(..)` — the bare derive-all call form is reserved (NOLA1004).