create-nola-lang 0.1.3 → 0.1.4

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).

package/skills/nola/references/syntax.md

@@ -0,0 +1,377 @@
+# Nola syntax reference
+
+Everything valid in TypeScript is valid in a `.tsi` file. This file documents
+only the additions. `ask` and `with` are reserved words in `.tsi` (`ask` stays
+legal as a member/property name); `infer` is a keyword only directly before
+`function` at statement or export position, so `T extends infer U` in a
+conditional type is untouched.
+
+## `infer function`
+
+An `infer function` declares an LLM-backed function. Calling one runs NOTHING:
+it returns a lazy, thenable `Intent<T>`. The work happens when the intent is
+resolved — with `ask` inside another infer function, or with `await` from
+plain TS.
+
+```tsi
+// plain
+infer function summarize(.text: string) {
+  return ask ..`a one-sentence summary`<string>;
+}
+
+// exported
+export infer function classify(.message: string) {
+  return ask ..`the category of the message`<string>;
+}
+
+// with an instruction marker between the name and the parameter list
+export infer function triage`triage the ticket like a support lead`(.ticket: string) {
+  return ask ..`the severity: low, medium or high`<"low" | "medium" | "high">;
+}
+```
+
+Rules:
+
+- Top-level function declarations only. `infer` on a method, arrow function,
+  or function expression is a "reserved for a future Nola version" error.
+- `async infer function` is a parse error — an infer function is never `async`
+  in source; it is implicitly awaitable through `Intent`.
+- The instruction marker is a template literal. `${expr}` holes interpolate
+  lexical values into the instruction; a `${.member}` hole makes the marker a
+  prompt TEMPLATE for the function's CONTEXT block (see "Prompt templates").
+- `export default infer function` does NOT parse. Export by name
+  (`export infer function f(...)`) and let consumers import the name.
+- `ask` is legal only DIRECTLY inside an infer function body — not at module
+  level, not inside a nested closure (NOLA2001).
+- `await` IS legal inside the body, for ordinary promises (fetch, DB, any
+  library):
+
+```tsi
+export infer function enrich(.handle: string, fetchProfile: (h: string) => Promise<string>) {
+  const profile = await fetchProfile(handle);       // ordinary promise
+  return ask ..`the person's job title from: ${profile}`<string>;
+}
+```
+
+### Return type annotation
+
+Leave the return type off and let it infer — that is what every example in
+this repo does. When you do annotate, the annotation is `Intent<T>` (the body
+returns `T`, the way an `async` function body returns `T` under `Promise<T>`):
+
+```tsi
+import type { Intent } from "@nola-lang/runtime";
+
+interface User {
+  name: string;
+}
+
+export infer function getUser(.message: string): Intent<User> {
+  const user = ask ..`the user described in the message`<User>;
+  return user;
+}
+```
+
+Do NOT annotate it `Promise<T>`: `Intent<T>` is `PromiseLike<T>`, not a
+`Promise`, so `nola check` reports TS2739 (missing `catch`, `finally`,
+`[Symbol.toStringTag]`).
+
+## `.` contextual parameters
+
+A parameter prefixed with ONE dot is a CONTEXT parameter: its name, type and
+runtime VALUE are composed into the prompt of every `ask` in that invocation.
+A plain parameter is an ordinary JS argument — its name and type reach the
+LLM, its value does not. Mnemonic: one dot IN (`.name`), two dots OUT
+(`` ..`prompt` ``). Writing `..name` on a parameter is NOLA1013.
+
+```tsi
+export type Issue = { id: string; description: string };
+
+// `issue` is visible to the LLM; `fallback` is a normal JS value only.
+export infer function classifyIssue(.issue: Issue, fallback: string) {
+  const kind = ask ..`the kind of this issue`<string>;
+  return kind || fallback;
+}
+```
+
+- `.` is legal ONLY on infer-function parameters. On any other function it is
+  NOLA1010.
+- A contextual parameter's TYPE must be derivable to an inference schema:
+  strings, numbers, booleans, `Date`, arrays, plain object/interface/type-alias
+  shapes, string-literal unions, string enums, and same-file or imported
+  references to those. `Map`, `Set` and other ambient lib types are NOT
+  derivable and raise NOLA2008 under the default policy.
+- Several contextual parameters are fine; they compose into one context block:
+
+```tsi
+export infer function nextQuery(.question: string, .notes: string[]) {
+  return ask ..`the single best search query to advance the research`<string>;
+}
+```
+- `const .x = …` (a contextual BINDING inside the body) is reserved for a
+  future Nola version — NOLA1014 today.
+
+## Extractors — `` ..`instruction`<T> ``
+
+An extractor is the request itself: instruction text in backticks plus an
+optional type argument.
+
+```tsi
+export infer function parse(.doc: string) {
+  const id = ask ..`the ticket id`<string>;             // typed
+  const count = ask ..`how many line items`<number>;
+  const free = ask ..`think step by step about the document`;  // untyped
+  return { id, count, free };
+}
+```
+
+- `${expr}` interpolation is legal inside the backticks and is evaluated at
+  intent-construction time. Strings splice as-is; anything else is
+  JSON-stringified. A hole starting with a single dot (`${.type}`) is NOT a
+  lexical value — it reads the extractor's prompt scope and turns the
+  backticks into a prompt template (see "Prompt templates"):
+
+```tsi
+interface Person {
+  name: string;
+  age: number;
+}
+
+export infer function lookup(text: string) {
+  return ask ..`the person described in: ${text}`<Person>;
+}
+```
+
+- With no `<T>`, the extractor asks for free text: the wire schema is a plain
+  string and the static TS type is `any`. Give every extractor an explicit
+  `<T>` unless you deliberately want unconstrained prose.
+- `<T>` accepts scalars, `Date`, arrays, inline object literals, same-file
+  and imported non-generic aliases/interfaces, string-literal unions and
+  string enums. JSDoc comments on members become schema descriptions:
+
+```tsi
+export interface Conclusion {
+  answer: string;
+  /** the collected notes that directly support the answer */
+  evidence: string[];
+}
+```
+
+- An extractor may be CONSTRUCTED anywhere in a `.tsi` file, module level
+  included — construction needs no context. Only `ask` is position-restricted:
+
+```tsi
+export const nameIntent = ..`the user's full name`<string>;   // legal, inert
+```
+
+## The `ask` operator
+
+`ask` is a unary prefix operator with `await`'s precedence. It resolves any
+`Askable` — an extractor, a call intent, or the `Intent` returned by calling
+an infer function — to its value.
+
+```tsi
+import { getUserById } from "./users.tsi";
+
+type User = { name: string };
+
+export infer function report(.text: string) {
+  const user = ask ..`the user named in the text`<User>;   // extractor
+  const record = ask getUserById(user.name);               // another infer function
+  return record;
+}
+```
+
+### `ask with <name>` — pin one ask to a provider
+
+```tsi
+export infer function summarize(.text: string) {
+  const draft = ask with fast ..`a rough summary`<string>;
+  const final = ask with careful ..`a polished summary of: ${draft}`<string>;
+  return final;
+}
+```
+
+- `<name>` must be a STATIC identifier naming a key of the `providers` map in
+  `nola.config.ts`. An extractor, a parenthesized expression, a string literal
+  or anything else after `with` is NOLA1009 — use `.withProvider(...)` for a
+  dynamic provider.
+- The name is matched against the config at ask time, not compile time; an
+  unknown name is a runtime `NolaConfigError` (NOLA3004).
+- `ask without` is a plain ask of the identifier `without`, not a pin.
+
+## Call intents
+
+A call intent lets the LLM fill some of a function's arguments, then calls the
+function with them. All slots of one call intent resolve in ONE provider call.
+
+Three spellings:
+
+```tsi
+declare function createTicket(title: string, priority: number): Promise<string>;
+
+export infer function file(.request: string) {
+  // 1. sigil-less — a plain call whose arguments contain an extractor
+  const a = ask createTicket(..`a short ticket title`<string>, 2);
+
+  // 2. empty marker — identical lowering; the only spelling for a call
+  //    intent whose arguments are all plain
+  const b = ask createTicket``("fallback title", 3);
+
+  // 3. hint marker — the ONLY carrier of instruction text for the call
+  const c = ask createTicket`file the ticket the customer asked for`(
+    ..`a short ticket title`<string>,
+    ..`priority 1-5, 1 is most urgent`<number>,
+  );
+
+  return { a, b, c };
+}
+```
+
+Detection rule for the sigil-less form — BOTH must hold:
+
+- the callee is an `Identifier` or a `MemberExpression` (any nesting, computed
+  included), and
+- at least one well-formed extractor appears in a slot position: a direct
+  argument, or nested at any depth inside plain object/array literals.
+
+```tsi
+declare const api: { save(order: { qty: number; note: string }): Promise<string> };
+
+export infer function place(.request: string) {
+  // member callee + extractor nested in an object literal → call intent
+  return ask api.save({ qty: 1, note: ..`a one-line note for the warehouse`<string> });
+}
+```
+
+These stay PLAIN calls (the extractor is just a value argument): an extractor
+inside a ternary, logical expression, spread element or template substitution;
+a nested call (in `` outer(inner(..`x`<T>)) `` the INNER call is the intent and
+`outer` receives an `Askable`); `new Foo(...)`, `super(...)`, `import(...)`,
+optional calls (`fn?.(...)`, `a?.b(...)`); and exotic callees (`getFn()(...)`,
+IIFEs) — use the marker form if you want a call intent on one of those.
+
+Parenthesizing an extractor does NOT opt out. To pass an intent as a plain
+value, bind it to a variable first:
+
+```tsi
+const i = ..`a short title`<string>;
+helper(i);                       // plain call — helper receives the Askable
+```
+
+Every extractor used as a call-intent slot must carry an explicit `<T>`
+(NOLA2004). The bare derive-all form `fn(..)` is reserved (NOLA1004).
+
+### Result of a call intent — async callees are awaited
+
+`ask fn(...)` yields the callee's SETTLED value, exactly like `await fn(...)`
+would: if the function returns a promise (or any thenable), the intent awaits
+it before resolving. Its static type is `Awaited<ReturnType<typeof fn>>`. Never
+write `await ask fn(...)` — the extra `await` is a no-op.
+
+```tsi
+declare function createTicket(title: string, priority: number): Promise<string>;
+
+export infer function file(.request: string) {
+  const id = ask createTicket(..`a short ticket title`<string>, 2); // id: string, not Promise<string>
+  return id;
+}
+```
+
+Two consequences to keep in mind:
+
+- The callee runs INSIDE the ask, so a rejected promise fails the ask at the
+  call site (NolaResolutionError with the intent's location) — and
+  `.withRetry(n)` re-runs the WHOLE ask, including the callee. Do not put
+  `.withRetry` on a call intent whose target is not idempotent.
+- The invocation timeout (`ask.timeoutMs` / `.withTimeout`) bounds provider
+  round trips only. Once the arguments are filled, the callee's own promise
+  runs to completion, the same as a plain `await fn()` in your code.
+
+## Prompt templates — `${.member}`
+
+Every instruction literal (infer-function marker, extractor prompt, call-intent
+hint) can act as a TEMPLATE for the prompt block that intent contributes. One
+rule: a substitution hole whose expression starts with a single dot reads the
+intent's prompt scope; every other hole is ordinary lexical JavaScript.
+
+```tsi
+infer function analyze`${.default}
+Rules: answer only from the arguments above; never invent ids.`(.ticket: Ticket) {
+  const id = ask ..`ticket id, comply with ${.type}`<string>;
+  return id;
+}
+
+// A full custom CONTEXT block — everything after the dot is plain TypeScript
+infer function triage`
+CONTEXT — inside ${.signature}, ${.file}
+${.args.map(a => `- ${a.name} (${a.type}): ${JSON.stringify(a.value)}`)}
+
+TASK
+${.next}
+`(.ticket: string) { … }
+```
+
+- Override rule (static): a literal with at least ONE `${.x}` hole is a
+  template — its rendered text REPLACES that intent's block (CONTEXT for an
+  infer function, TASK for an extractor / call hint). A literal with no scope
+  hole is an instruction, exactly as before (`Purpose:` / `<request>` inside
+  the built-in block), even when it has lexical `${}` holes.
+- Function scope (`FunctionPromptScope`): `.fn`, `.signature`, `.file`,
+  `.args[]` (`name`, `type` — native type text, `value`, `contextual`),
+  `.nested`, `.hasContext`, `.default` (the built-in CONTEXT block, no
+  Purpose line), `.next` (the rest of the prompt: callee blocks + TASK).
+- Extractor / call-hint scope (`ExtractPromptScope`): `.type` (native type
+  text of the target), `.schema` (the JSON Schema, serialized),
+  `.hasContext`, `.default` (the built-in TASK block), `.format` (the JSON
+  response rules).
+- Safe by default: a function template that never reads `.next` gets the
+  rest of the prompt appended after it; an extractor template that never
+  reads `.format` gets the JSON response rules appended. Read them only to
+  choose WHERE they go (wrapping). `.next`/`.default`/`.format` are
+  getters, memoized — reading twice does not compose twice.
+- Rendering: arrays render one item per line (no `.join` needed),
+  `undefined`/`null` render as nothing, objects as JSON, `Date` as ISO.
+  Templates render when the ask composes its prompt — lexical values inside
+  a TEMPLATE are read then, not at construction (the only observable
+  difference from an instruction's eager `${}`).
+- Nested holes follow the same rule: `${.file}` inside a `.map` callback's
+  own template literal still reads the scope. Keyword members work
+  (`${.default}`).
+- Editor: completion, hover and precise TS errors work inside the backticks
+  (an unknown member is a TS2339 at the member).
+- Errors: `${.x}` in a template literal that is not a Nola instruction is
+  NOLA2009; a Nola construct (`..`, call intent, `ask`) inside a marker /
+  call-hint hole is NOLA2010; a template that throws or renders empty fails
+  the ask with NOLA3014 (definitive).
+
+## Intent methods
+
+Every intent (extractor, call intent, infer-function result) accepts:
+
+```tsi
+export infer function tuned(.text: string) {
+  const a = ask (..`the title`<string>).withRetry(2);
+  const b = ask (..`the body`<string>).withProvider("careful");
+  const c = ask (..`a creative tagline`<string>).withParams({ temperature: 0.9, maxOutputTokens: 200 });
+  return { a, b, c };
+}
+```
+
+- `.withRetry(n)` — `n` extra whole-ask attempts, flat, no backoff.
+- `.withProvider(nameOrProvider)` — the dynamic form of `ask with`.
+- `.withParams({ temperature, maxOutputTokens, providerOptions })` — wire knobs,
+  merged per field with anything already set.
+
+Two more exist ONLY on the `Intent` an infer function returns (they act when
+the intent roots an invocation), and are typically used from plain TS:
+
+```ts
+import { extractPerson } from "./person.tsi";
+
+const person = await extractPerson(text).withTimeout(30_000);
+const loose = await extractPerson(text).detached();   // do not inherit the caller frame's context
+```
+
+All of these CLONE the intent — the original stays unstarted, and an intent
+resolves at most once.

package/templates/starter/_gitignore

@@ -1,2 +1,4 @@
 node_modules/
 dist/
+
+.env