newo-dsl-analyzer

Static-analysis engine for the Newo DSL (NSL / Guidance / Jinja). This is the shared engine consumed by the newo CLI (newo lint, newo format, newo check) and the newo-dsl-lsp language server.

Install

npm install newo-dsl-analyzer

Public API

High-level: createLinter

import { createLinter } from 'newo-dsl-analyzer';

const linter = createLinter({
  // Optional. Defaults to 'bundled' (platform actions + builtins).
  schemas: 'bundled',
  // Optional. Override rule severity.
  rules: { W101: 'off' },
  // Optional. Load plugins.
  plugins: [],
});

// Lint a single in-memory source.
const result = linter.lint(source, '/abs/path/file.jinja');
console.log(result.diagnostics);
// [{ severity: 'warning', code: 'W101', message: 'Unknown function: Foo', range: {...} }]

// Lint a project tree.
const report = linter.lintProject('/abs/path/to/project', {
  extensions: ['.jinja', '.guidance', '.nsl', '.nslg'],
  ignore: ['/abs/path/to/project/archived'],
});
console.log(report.errorCount, report.warningCount);

// Introspect rules.
linter.listRules().forEach(r => console.log(r.id, r.meta?.title));

High-level: createFormatter

import { createFormatter } from 'newo-dsl-analyzer';

const formatter = createFormatter({ indent: 2, insertFinalNewline: true });
const { formatted, changed } = formatter.format(source, filePath);
if (changed) await fs.writeFile(filePath, formatted);

Config loading: loadConfig

import { loadConfig } from 'newo-dsl-analyzer';

// Walks up from cwd looking for .neworc.yaml / .neworc.yml / .neworc.json
const config = loadConfig(process.cwd());
// { rules?: { [ruleId]: 'off' | 'warning' | 'error' }, plugins?: string[], ignore?: string[] }

Low-level: NewoDslAnalyzer

The LSP server consumes this directly for completions / hover / go-to-definition. Most users should prefer createLinter.

import { NewoDslAnalyzer } from 'newo-dsl-analyzer';

const analyzer = new NewoDslAnalyzer();
analyzer.loadSchemas();       // bundled schemas
// or:
analyzer.loadSchemas('/path/to/schemas');   // directory with *.schema.yaml files
// or:
analyzer.loadInlineSchemas({                 // programmatic, e.g. from NEWO API
  skills: [...],
  actions: [...],
  attributes: [...],
  events: [...],
});

const result = analyzer.parseTemplate(source, filePath);
const diagnostics = analyzer.getDiagnostics(source, filePath);
const completions = analyzer.getCompletions(source, filePath, line, column);
const hover = analyzer.getHover(source, filePath, line, column);
const definition = analyzer.getDefinition(source, filePath, line, column);

Schemas

The analyzer needs a catalog of known skills / actions / attributes / events to validate references. There are three ways to supply it:

| Source | When | How | |--------|------|-----| | Bundled (default) | You want zero setup and only need platform-level ACTIONS + Jinja builtins validated. | createLinter() with default schemas: 'bundled'. | | Directory | You have generated YAML files from your NEWO account and want offline linting with your full catalog. | createLinter({ schemas: { kind: 'dir', path: '/path/to/schemas' } }). Files must match *.schema.yaml names. | | Inline | You want to inject live API data (typical for newo lint --live). | createLinter({ schemas: { kind: 'inline', skills, actions, attributes, events } }). |

To generate customer-specific schemas, see newo-dsl-spec-generator (internal tool) or run newo lint --live from the newo CLI to cache your account's current catalog into .newo/{customer}/actions.json.

Diagnostic codes

| Code | Severity | Description | |------|----------|-------------| | E001 | error | Unbalanced expression braces {{ }} | | E002 | error | Unbalanced statement braces {% %} | | E003 | error | Unbalanced comment braces {# #} | | E010-E012 | error | Guidance block mismatch (unclosed / misnamed {{#name}} {{/name}}) | | E100 | error | Unknown skill (not in registered catalog) | | E101 | error | Required skill parameter missing | | W001 | warning | Style: missing whitespace in control structures | | W010 | warning | Unknown Guidance block name | | W100 | warning | Unknown Jinja builtin | | W101 | warning | Unknown function (not a skill or builtin, excluded from common utility prefixes) | | W102 | warning | Unknown parameter name for a known function | | W103 | warning | Unknown customer attribute |

Disable rules in .neworc.yaml:

rules:
  W101: off
  W102: warning
  E100: error

Types

All type exports are re-exported from newo-dsl-core for plugin authors. You do not need to install newo-dsl-core separately - importing from newo-dsl-analyzer works for both runtime and types.

License

Proprietary - Newo AI. All rights reserved.