@dforge-core/metadata 0.0.22 → 0.0.23

package/CHANGELOG.md

@@ -5,6 +5,140 @@ All notable changes to `@dforge-core/metadata` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.23] — 2026-09-14
+
+### Added
+
+- **`@dforge-core/metadata/dsl` — the action-DSL analyzer**, as a second entry point:
+  a lexer, a parser and the static rules for `logic/actions/*.dsl`. It was implemented
+  twice — once in the language server (token-based, module-aware, drawing squiggles) and
+  once in the module validator (regex-based, module-blind, gating a pack) — with only
+  three rules in common, so an editor hint and a pre-pack failure disagreed about the
+  same script.
+
+  The rules take what they know about the module through a small injected `DslContext`
+  (module code, the action, and the columns of the entity behind the record context)
+  rather than a loader, so the same rule serves a language server and a file-walking
+  validator. Every context field is optional and every rule that reads one fails open:
+  with an empty context the text-only rules still run and the rest stand down silently.
+  A false "unknown column" underlines working code and blocks a pack; a missed one costs
+  an install round trip.
+
+  `checkDsl(text, ctx)` returns `DslIssue[]` carrying both byte offsets and a 1-indexed
+  line/column, so a range-based host and a `file.dsl:12` reporter each get what they
+  need without re-deriving it. `parseDsl`, `tokenize` and the built-in catalog are
+  exported too, for completion, hover and go-to-definition. `sendEmail` in that
+  catalog is `sendEmail(to, subjectOrTemplate, dataOrBody?)` — three arguments,
+  the second choosing template or raw mode, as `ScriptContext.sendEmail` does;
+  the fourth argument it used to advertise never existed. `applyProfile` is
+  `applyProfile(json, profile)`, taking the inline `{ map, lines? }` object the
+  runtime demands — the profile code it used to advertise throws, profile-by-code
+  being a later slice. `ocrExtract` states the return type its mode decides: a
+  JSON string to `JSON.parse()` without `opts.mode`, a parsed object with it.
+  And `download` sets a URL on the action result rather than fetching anything
+  into storage, which is what it used to claim.
+
+  Deliberately **not** in the root barrel: the root export is registries and types that
+  the web app and the VS Code webview pull into a browser bundle, and importing it must
+  not drag a tokenizer in behind it. The package also declares `sideEffects: false` now.
+
+  The two existing implementations live in other repos; the duplication ends when
+  the language server and the module validator import this entry point, not when
+  it ships.
+
+  Recognising a block the way `ActionDslCompiler.ParseBlocks` recognises one:
+  five kinds including `schema:`, anchored at column 0, matched case-insensitively,
+  with a leading BOM stripped and `execute:` running to end-of-file. The anchor is
+  the load-bearing part — an indented `params:` is an object key inside a block
+  body, and treating it as a header fragmented the document and fabricated a
+  param list. A header that *is* indented is now reported (`dsl/indented-block-header`),
+  since the compiler reads it as body text and runs the block it meant to open
+  as empty.
+
+  `[field]` detection is the compiler's `(?<!\w)\[(\w+)\]`, character for
+  character rather than by previous token: the lookbehind does not skip
+  whitespace, so a read that opens a line is a read however the line above
+  ended. Column and param names match case-insensitively, as `EntityColumnLookup`
+  and `ValidateParamUsages` do.
+
+  A rule is scoped to the block whose compiler actually imposes it. Single-hop
+  ref navigation is the DSL's `RxRefNav`, so `canExecute:` — handed to the
+  formula engine verbatim, where a chain has no depth limit — is exempt. The
+  batch-mode "no current record" rule is `execute:` alone, since
+  `onBeforeStart:` is compiled per-record in every mode. And `records[0][field]`
+  is one indexed read, matching `RxRecordsFieldRead`, which runs ahead of the
+  generic `[field]` rewrite: its column is still checked, but it is not a
+  current-record read.
+
+  What the single-hop rule refuses is a second **bracketed** hop, not a second
+  hop: the compiler rewrites the first one and then throws on a surviving `.[`,
+  so `[vehicle].plate.length` is one hop followed by ordinary JavaScript on the
+  value it returned. Batch mode applies no `[field]` rewrite at all, so
+  `var ids = [id]` is the array literal it looks like — the same local-name
+  disambiguation the column rule uses. And a param declared inline with its
+  header (`params: qty: number required`) is declared: `^params:\s*` swallows
+  the newline, making the header's own line the block's first.
+
+  The column check covers every way the compiler reaches a column, not only the
+  bare `[field]`: `old[field]` and a batch loop variable's `x[field]` are fed
+  into the same `fieldRefs` set server-side, so a typo in either is the same
+  compile error. A template literal is tokenized as prose and holes rather than
+  as one opaque token, so `${…}` is analyzed and the text around it is not.
+  A param may be named after a block (`execute: number` is a legal `RxParamDecl`
+  line) without being read as a header — though its type has to share its line,
+  as that single-line regex requires. Nothing inside `params:` is a field read
+  at all: `RxKeyValue` takes a bracketed option list, so `options=[cash]` is an
+  option list.
+
+  Case is folded on both sides of the column lookup — the names once per check
+  when the lookup can enumerate them, which `Set` and `Map` both can, and the
+  reference on the way in — so a mixed-case column name matches whichever case
+  the script spells it in. `ColumnLookup` gained an optional `keys()` for that.
+
+  `dsl/top-level-return` reads function scope rather than brace depth, and is
+  an error rather than a warning: both blocks compile to a bare script, and
+  Esprima's `ParseScript` refuses a return outside a function wherever it sits,
+  so `if (x) { return }` and `if (x) return` fail exactly as a return on its own
+  line does. `return` is reserved, so it is a statement unless it is being used
+  as a name — a property, an object key, or a method shorthand, told from
+  `return (expr)` by the body brace after the parameter list. `function`, function expressions, arrows and method shorthand all
+  open a scope where it is legal; an `if` or `for` body does not.
+
+  A regex literal is one token, so `/return/` and `/[^0-9]/` carry no statement
+  and no field read. The `/` is read as division after a value and as a regex
+  after an operator or a keyword. `)` and `}` each depend on what they closed —
+  a control condition and a statement block leave a statement position, so
+  `if (x) /re/.test(s)` and `if (x) {}` then `/re/` are regexes, while
+  `(a + b) / 2` and `{ a: 1 }` then `/` divide — and a template chunk on whether
+  it stopped at `${` or ran to the backtick.
+
+  A keyword literal is never a column: in batch `execute:`, which applies no
+  `[field]` rewrite at all, `[true]`, `[false]` and `[NULL]` are the array
+  elements they look like. In every other block the compiler does rewrite them,
+  so the check stands there.
+
+  `locals` covers function parameters as well as `var`/`let`/`const` and `for`
+  heads — declarations, expressions, arrows and method shorthand alike — since a
+  parameter binds a name the same way, and `function wrap(value) { return [value] }`
+  holds an array literal rather than a field read.
+
+  Local-name disambiguation is confined to the bare bracket that needs it.
+  `var ids = [orderId]` is ambiguous with a field read and only the name tells
+  them apart, but `r[stauts]` and `records[0][stauts]` name a column outright —
+  the compiler rewrites each to `.get('stauts')` with the literal name — so a
+  same-named local no longer hides the typo.
+
+  Checked against every action in the module tree — 70 actions, each against its
+  own trait-expanded entity: no false positives.
+
+## [0.0.22] — 2026-08-28
+
+### Changed
+
+- `entity.schema.json` — per-constraint validation: `expression` is check-only,
+  and a `unique` constraint needs its key. Shipped with the DB-enforced stock
+  availability work (`54622c5c`).
+
 ## [0.0.21] — 2026-08-24
 
 ### Changed

package/README.md

@@ -32,6 +32,7 @@ pnpm add @dforge-core/metadata
 | **Scalar enums** | `FieldTypeCd`, `BaseDatatypeCd`, `ColumnTypeCd`, `FlagCd`, `AlignType` |
 | **Module-file types** | `ManifestDef`, `EntityDef`, `DataViewsFile`, `ReportsFile`, `MenusFile`, `FoldersFile`, `RolesFile`, `SettingsFile`, `JobsFile`, `TriggersFile`, `WebhooksFile`, `PrintTemplatesFile`, `SeedDataFile`, `ActionsFile`, … |
 | **Filter expression** | `Filter`, `FilterCondition`, `FilterGroup`, `SortClause` |
+| **DSL analyzer** | `./dsl` — `checkDsl`, `parseDsl`, `tokenize`, `BUILTINS` (see [Action DSL](#action-dsl)) |
 | **JSON schemas** | `./schemas/<name>.schema.json` (see [Schemas](#json-schemas)) |
 
 ## Registries & derivation
@@ -94,6 +95,50 @@ const entity: EntityDef = {
 > returned by the API (`metadata.getModel`) is a different contract — see
 > `@dforge/sdk`'s `Model*` types, which reuse the scalar enums from this package.
 
+## Action DSL
+
+`@dforge-core/metadata/dsl` is a separate entry point holding the lexer, parser
+and static rules for an action body (`logic/actions/*.dsl`). One implementation
+serves both hosts that check these files: the language server, which turns
+issues into squiggles, and the module validator, which gates a pack.
+
+```ts
+import { checkDsl } from "@dforge-core/metadata/dsl";
+
+const issues = checkDsl(source, {
+  moduleCode: "wms",
+  action: { code: "transfer_stock", executionMode: "single" },
+  currentEntity: { qualified: "wms.stock_movement", columns: entityColumns },
+});
+// → [{ rule: "dsl/unknown-column", severity: "error", message, start, end, line, column }]
+```
+
+What a rule knows about the module arrives through that context — a module code,
+the action, and a column lookup (any `Set` or `Map` will do) — rather than
+through a module loader, which is what lets the same rule run in an editor and
+in a file walker. **Every field is optional and every rule that reads one fails
+open**: with an empty context the text-only rules still run and the rest stand
+down silently. A false "unknown column" underlines working code and blocks a
+pack; a missed one costs an install round trip.
+
+One obligation comes with `currentEntity`: `columns` must be **trait-expanded**,
+built-in traits and the module's own `traits.json` alike, because the identity
+PK and `[status]` live in traits rather than in `fields`. An unexpanded set
+turns the rule into a wall of false errors. When the entity can't be resolved —
+a bridge module acting on another module's entity — pass `null` rather than the
+fragment you do have.
+
+Issues carry both byte offsets and a 1-indexed `line`/`column`, so a
+range-based host and a `file.dsl:12` reporter each get what they need.
+
+The blocks, the `[field]` lookbehind and the case rules follow
+`ActionDslCompiler` rather than the prose docs: five block kinds including
+`schema:`, headers anchored at column 0 (an indented one is body text, and is
+reported), and `execute:` running to end-of-file.
+
+It is not re-exported from the package root: importing `@dforge-core/metadata`
+in a browser bundle must not pull a tokenizer in behind it.
+
 ## JSON schemas
 
 The 14 canonical schemas are shipped alongside the types and stay byte-identical

package/dist/actions-DvYTrCbP.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Execution mode. 'single' (default) and 'each' run the DSL per selected record;
+ * 'batch' runs once with all records exposed as `__records`.
+ */
+type ActionExecutionMode = "single" | "each" | "batch";
+/** A single action declaration (value in the `ui/actions.json` map). */
+interface ActionDef {
+    /** Human-readable description. */
+    description: string;
+    /** Button label. */
+    label: string;
+    /** Bootstrap icon class (e.g. 'bi-telephone-check'). */
+    icon: string;
+    /** Entity code this action targets. */
+    entityCode: string;
+    /** Per-record vs. batch execution. */
+    executionMode: ActionExecutionMode;
+    /** DSL script name (file under `logic/actions/<script>.dsl`). */
+    script: string;
+    /**
+     * Run the whole selection in one transaction, so a failure on any record
+     * rolls back the records already processed. **Defaults to `true`** when
+     * omitted (`ActionDef.IsTransacted` in the installer is a non-nullable
+     * `bool` initialised to `true`), so omit it only when you want atomicity.
+     *
+     * `false` opens no transaction, and what follows a failure depends on
+     * {@link ActionDef.executionMode}: `single` / `each` report it and continue
+     * with the next record, so use that for independent per-record work that
+     * should process as many records as pass; `batch` is a single script
+     * invocation with no loop to continue, so the run simply ends with its
+     * earlier writes committed.
+     *
+     * On a run queued to the background the **rollback** guarantee is lost
+     * outright — the worker opens no transaction, so nothing is ever undone. What
+     * remains of the flag there depends on the mode: the worker's `single`/`each`
+     * loop still reads it for control flow (stop after the first failed record vs.
+     * continue), while its `batch` path never reads it at all — one invocation,
+     * which ends on failure under either value.
+     */
+    isTransacted?: boolean;
+    /** Display order. */
+    orderNum?: number;
+    /**
+     * @deprecated Not read by the installer — use {@link ActionDef.isAsync}.
+     * The module manifest model binds `isAsync` only, so this key is silently
+     * ignored and the action installs as synchronous.
+     */
+    async?: boolean;
+    /**
+     * Permit background execution. It does not force it: `action.execute`
+     * carries its own `async` argument and the server branches on that, so an
+     * action with parameters is offered to the user as both "Run" (inline) and
+     * "Run in Background". A parameterless `isAsync` action is queued directly.
+     */
+    isAsync?: boolean;
+}
+/** A `ui/actions.json` file: action code → definition. */
+type ActionsFile = Record<string, ActionDef>;
+
+export type { ActionExecutionMode as A, ActionDef as a, ActionsFile as b };

package/dist/dsl/index.d.ts

@@ -0,0 +1,223 @@
+import { A as ActionExecutionMode } from '../actions-DvYTrCbP.js';
+
+type TokenKind = "ident" | "number" | "string" | "template" | "regex" | "punct" | "comment";
+interface Token {
+    kind: TokenKind;
+    /** Source text, verbatim — quotes included for strings. */
+    text: string;
+    start: number;
+    end: number;
+    line: number;
+    character: number;
+    /** True when a line break sits between this token and the previous one. */
+    startsLine: boolean;
+}
+declare function tokenize(text: string): Token[];
+/** Strip the surrounding quotes from a string token's text. */
+declare function stringValue(token: Token): string;
+
+type BlockKind = "params" | "canExecute" | "schema" | "onBeforeStart" | "execute";
+/** In the order `ActionDslCompiler.ParseBlocks` expects them in a file. */
+declare const BLOCK_KINDS: BlockKind[];
+interface Span {
+    start: number;
+    end: number;
+}
+interface DslBlock {
+    kind: BlockKind;
+    label: Span;
+    /** Span of the block body — label end to the next label (or EOF). */
+    body: Span;
+}
+interface DslParam {
+    name: string;
+    nameSpan: Span;
+    /** fieldTypeCd, or the referenced entity code when `isRef`. */
+    type: string;
+    typeSpan: Span;
+    isRef: boolean;
+    required: boolean;
+    label?: string;
+}
+/**
+ * A `[field]` read. `navigation` holds the property hops that follow it, each
+ * remembering whether it was written `.[target]` or `.target`: the compiler
+ * rewrites the FIRST hop either way, and then only a surviving `.[` is the
+ * multi-hop compile error. A dotted tail is plain JavaScript on the value the
+ * hop returned, so `[customer].[code]`, `[a].b.c` and `[plate].length` all
+ * compile.
+ */
+interface FieldRef {
+    name: string;
+    span: Span;
+    /** Span including the brackets. */
+    outerSpan: Span;
+    navigation: Array<{
+        name: string;
+        span: Span;
+        bracketed: boolean;
+    }>;
+    block: BlockKind | null;
+    /**
+     * False when the read is bound to a numbered record rather than the current
+     * one — `records[0][status]`, which `RxRecordsFieldRead` rewrites ahead of
+     * the generic `[field]` pass. The name is still a column of the entity, so
+     * the column rules apply; the batch-mode rule does not.
+     */
+    isCurrentRecord: boolean;
+    /** Index of the token that opens this read — the `[`. */
+    startIndex: number;
+    /**
+     * Index of the last token this read consumes, navigation included. A hop is
+     * 2 tokens as `.prop` but 4 as `.[prop]`, so callers that need the token
+     * after the read cannot compute it from `navigation.length`.
+     */
+    endIndex: number;
+}
+/** `params[x]` / `old[x]` — subscript reads off a DSL global. */
+interface GlobalRef {
+    global: "params" | "old" | "records";
+    property: string;
+    span: Span;
+    block: BlockKind | null;
+}
+interface CallRef {
+    name: string;
+    nameSpan: Span;
+    /** First argument when it is a string literal — the entity code, usually. */
+    firstStringArg?: {
+        value: string;
+        span: Span;
+    };
+    block: BlockKind | null;
+}
+interface DslDocument {
+    blocks: DslBlock[];
+    params: DslParam[];
+    fieldRefs: FieldRef[];
+    globalRefs: GlobalRef[];
+    calls: CallRef[];
+    tokens: Token[];
+    /**
+     * Every mention of `records`, subscript (`records[x]`) or bare
+     * (`for x in records`). `globalRefs` only holds the subscript form, so a
+     * rule that needs to point at the batch loop has nothing to anchor to.
+     */
+    recordsRefs: Span[];
+    /** Names bound by `var`/`let`/`const` or a `for` head, plus declared params. */
+    locals: Set<string>;
+    /**
+     * Loop variables bound by `for x in records {` — `RxForLoop` and nothing
+     * else, so an ordinary `for (var x of xs)` is not one. Their `x[field]`
+     * subscripts read the entity's columns, which is why they come back as
+     * field reads.
+     */
+    recordsLoopVars: Set<string>;
+}
+declare function parseDsl(text: string): DslDocument;
+
+interface Builtin {
+    name: string;
+    signature: string;
+    returns: string;
+    doc: string;
+    /**
+     * Index of the argument that names an entity, when the built-in takes one.
+     * Drives entity-code completion and the qualify-your-codes diagnostic.
+     */
+    entityArg?: number;
+}
+declare const BUILTINS: Builtin[];
+declare const BUILTIN_BY_NAME: Map<string, Builtin>;
+/** Bare identifiers the runtime injects — no parentheses. */
+declare const BUILTIN_VALUES: Record<string, string>;
+
+type DslSeverity = "error" | "warning" | "info";
+/** One reported problem. `rule` is stable — hosts filter and suppress on it. */
+interface DslIssue {
+    /** Stable rule id, namespaced: `dsl/unknown-column`. */
+    rule: string;
+    severity: DslSeverity;
+    message: string;
+    /** Byte offsets into the source, for range-based hosts. */
+    start: number;
+    end: number;
+    /** 1-indexed position of `start`, for line-based reporters. */
+    line: number;
+    column: number;
+}
+/**
+ * Column membership test. Structurally satisfied by both `Set<string>` and
+ * `Map<string, unknown>`, so a host that already holds a column map passes it
+ * straight in rather than copying it into a set on every check.
+ */
+interface ColumnLookup {
+    has(name: string): boolean;
+    readonly size: number;
+    /**
+     * The column names, if the lookup can enumerate them — `Set` and `Map` both
+     * can. Matching is case-insensitive at the other end (`EntityColumnLookup`
+     * builds an OrdinalIgnoreCase set) and a mixed-case column name is legal, so
+     * the checker folds case itself when it can read the keys.
+     *
+     * Without it, a lookup that is not already case-insensitive will report a
+     * spelling the server accepts. A host that cannot expose keys should make
+     * `has` case-insensitive instead.
+     */
+    keys?(): Iterable<string>;
+}
+/** The resolved entity a script's record context refers to. */
+interface EntityShape {
+    /** Module-qualified, e.g. `fin.invoice` — used in messages. */
+    qualified: string;
+    /**
+     * Every declared name on the entity, **trait-expanded** — built-in traits
+     * and the module's own `traits.json` alike — and including the virtual
+     * columns (reference, set, formula), exactly as `EntityColumnLookup` builds
+     * the compiler's set.
+     *
+     * Handing over an unexpanded set is the one mistake that turns this rule
+     * into a wall of false errors: the identity PK and `[status]` live in
+     * traits, not in `fields`. When in doubt pass `currentEntity: null` — a
+     * skipped check costs an install round trip, a wrong one blocks a pack.
+     */
+    columns: ColumnLookup;
+}
+/**
+ * What the checker knows about the script's surroundings. Every field is
+ * optional and every rule that reads one FAILS OPEN: with an empty context the
+ * text-only rules still run and the rest stand down silently.
+ *
+ * That is deliberate. A false "unknown column" on a correct script is far more
+ * damaging than a missed one — an editor would underline working code, and a
+ * validator would block a pack — so a rule that cannot resolve what it needs
+ * reports nothing.
+ */
+interface DslContext {
+    /** Owning module code, for the qualify-your-entity-codes message. */
+    moduleCode?: string;
+    /** The action this script implements, from `ui/actions.json`. */
+    action?: {
+        code: string;
+        executionMode?: ActionExecutionMode;
+    };
+    /**
+     * Entity behind the record context (`[field]`). `null` or absent when it
+     * can't be resolved — a bridge module acting on another module's entity —
+     * and then every column rule stands down. A partial set is worse than
+     * none: pass `null`, not the fragment. See `EntityShape.columns`.
+     */
+    currentEntity?: EntityShape | null;
+}
+
+/**
+ * Check a DSL body. Returns [] for a clean script.
+ *
+ * Issues come back in source-feature order (field reads, params, execution
+ * mode, block spelling, built-ins, top-level returns, inline assignments)
+ * rather than sorted by position — a host that wants them in file order can
+ * sort on `start`.
+ */
+declare function checkDsl(text: string, ctx?: DslContext): DslIssue[];
+
+export { BLOCK_KINDS, BUILTINS, BUILTIN_BY_NAME, BUILTIN_VALUES, type BlockKind, type Builtin, type CallRef, type ColumnLookup, type DslBlock, type DslContext, type DslDocument, type DslIssue, type DslParam, type DslSeverity, type EntityShape, type FieldRef, type GlobalRef, type Span, type Token, type TokenKind, checkDsl, parseDsl, stringValue, tokenize };