@algosail/parser 0.0.1

package/prototype.js

@@ -0,0 +1,459 @@
+import { Query } from 'web-tree-sitter'
+
+// symbol-table.js
+//
+// Transforms a tree-sitter AST (from @algosail/tree-sitter) into a symbol
+// table that mirrors the output of the hand-written parser in parser.js.
+//
+// Visitor pattern: instead of walking a flat token array with a pos counter,
+// we dispatch on node.type and read structured children via the tree-sitter
+// node API.
+//
+// Key tree-sitter node APIs used here:
+//   node.type                        — the grammar rule name
+//   node.text                        — raw source text of the node
+//   node.namedChildren               — array of named child nodes (no anonymous punctuation)
+//   node.childForFieldName('name')   — get the child bound to a field() in grammar.js
+//   node.startPosition / .endPosition — { row, column }
+//   node.hasError()                  — true if any descendant is an ERROR node
+//   node.isError                     — true if this node itself is an ERROR
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Get the child node bound to a named field, or null. */
+const field = (node, name) => node.childForFieldName(name) ?? null
+
+/** Get the text of a named field, or null. */
+const fieldText = (node, name) => field(node, name)?.text ?? null
+
+/** Get all named children of a specific type. */
+const childrenOfType = (node, type) => node.namedChildren.filter((c) => c.type === type)
+
+/** Get the first named child of a specific type, or null. */
+const firstOfType = (node, type) => node.namedChildren.find((c) => c.type === type) ?? null
+
+/**
+ * Extract plain text from a comment node.
+ * comment → '(' optional(comment_content) ')'
+ * comment_content → repeat1(choice(/[^()]+/, comment))
+ * We return the inner text trimmed, with nested parens preserved.
+ */
+const commentText = (commentNode) => {
+  if (!commentNode) return null
+  const content = firstOfType(commentNode, 'comment_content')
+  if (!content) return null
+  return content.text.trim()
+}
+
+/** Convert a tree-sitter position to a range object matching the existing spec. */
+const toRange = (node) => ({
+  startLine: node.startPosition.row,
+  startCol: node.startPosition.column,
+  endLine: node.endPosition.row,
+  endCol: node.endPosition.column,
+})
+
+// ─── Import types ────────────────────────────────────────────────────────────
+
+export const IMPORT_TYPE = {
+  FFI: 'FFI', // ./path or ../path or /absolute
+  NPM: 'NPM', // npm:package-name
+  MODULE: 'MODULE', // bare module name
+}
+
+const detectImportType = (path) => {
+  if (!path) return IMPORT_TYPE.MODULE
+  if (path.startsWith('./') || path.startsWith('../') || path.startsWith('/'))
+    return IMPORT_TYPE.FFI
+  if (path.startsWith('npm:')) return IMPORT_TYPE.NPM
+  return IMPORT_TYPE.MODULE
+}
+
+const cleanImportPath = (path) => {
+  if (!path) return null
+  return path.startsWith('npm:') ? path.slice(4) : path
+}
+
+// ─── Visitors ────────────────────────────────────────────────────────────────
+
+/**
+ * import_decl
+ *   path:  import_path   — raw path text (e.g. "./lib/io.js", "npm:pkg")
+ *   alias: module_alias  — e.g. "~Io"
+ */
+function visitImport(node) {
+  const rawPath = fieldText(node, 'path')
+  return {
+    type: detectImportType(rawPath),
+    path: cleanImportPath(rawPath),
+    alias: fieldText(node, 'alias'),
+    range: toRange(node),
+  }
+}
+
+/**
+ * tag_group
+ *   name:              tag_group_name   — e.g. "&Maybe"
+ *   (unnamed)          type_variable*   — type parameters
+ *   (unnamed optional) comment          — doc comment
+ *   (unnamed)          tag_def*         — tag cases
+ */
+function visitTagGroup(node) {
+  return {
+    name: fieldText(node, 'name')?.slice(1) ?? null, // strip leading &
+    doc: commentText(firstOfType(node, 'comment')),
+    params: childrenOfType(node, 'type_variable').map((n) => n.text),
+    tags: childrenOfType(node, 'tag_def').map(visitTagDef),
+    range: toRange(node),
+  }
+}
+
+/**
+ * tag_def
+ *   name:     tag_name       — e.g. ">Just"
+ *   (unnamed) type_variable* — per-case type parameters
+ *   (unnamed) comment?       — doc comment
+ */
+function visitTagDef(node) {
+  return {
+    name: fieldText(node, 'name')?.slice(1) ?? null, // strip leading >
+    doc: commentText(firstOfType(node, 'comment')),
+    params: childrenOfType(node, 'type_variable').map((n) => n.text),
+  }
+}
+
+/**
+ * map_def
+ *   name:     map_name    — e.g. "$Person"
+ *   (unnamed) map_field*  — struct fields
+ *   (unnamed) comment?    — doc comment
+ */
+function visitMapDef(node) {
+  return {
+    name: fieldText(node, 'name')?.slice(1) ?? null, // strip leading $
+    doc: commentText(firstOfType(node, 'comment')),
+    fields: childrenOfType(node, 'map_field').map(visitMapField),
+    range: toRange(node),
+  }
+}
+
+/**
+ * map_field
+ *   key:  map_field_name — e.g. ".name"
+ *   type: type_name      — e.g. "Str"
+ */
+function visitMapField(node) {
+  return {
+    key: fieldText(node, 'key')?.slice(1) ?? null, // strip leading .
+    type: fieldText(node, 'type'),
+    doc: commentText(firstOfType(node, 'comment')),
+  }
+}
+
+/**
+ * word_def
+ *   name: word_name  — e.g. "@createPerson"
+ *   sig:  signature  — the ( inputs -- outputs effects ) block
+ *   body: _expr*     — expressions; first comment is treated as doc
+ */
+/**
+ * @param {import('web-tree-sitter').SyntaxNode} node
+ * @param {{ tagIndex: Map, mapIndex: Map, moduleIndex: Map, errors: Array }} ctx
+ *   Pass the type context collected in passes 1–2 so we can resolve and
+ *   validate references inside the word body.
+ */
+function visitWordDef(node, ctx = {}) {
+  const nameNode = field(node, 'name')
+  const sigNode = field(node, 'sig')
+
+  // Doc comment: first comment among the body expressions (after sig)
+  const docNode = node.namedChildren
+    .filter((c) => c !== nameNode && c !== sigNode)
+    .find((c) => c.type === 'comment')
+
+  return {
+    name: fieldText(node, 'name')?.slice(1) ?? null, // strip leading @
+    doc: commentText(docNode),
+    signature: sigNode ? visitSignature(sigNode) : null,
+    refs: collectRefs(node, ctx),
+    range: toRange(node),
+  }
+}
+
+/**
+ * Walk the body of a word_def and collect all outbound references
+ * (word calls, module calls, tag constructors, map accesses).
+ * Unknown references are reported into ctx.errors.
+ *
+ * @param {import('web-tree-sitter').SyntaxNode} wordNode
+ * @param {{ tagIndex: Map, mapIndex: Map, moduleIndex: Map, errors: Array }} ctx
+ * @returns {{ words: string[], modules: string[], tags: string[], maps: string[] }}
+ */
+/**
+ * Collect outbound references from a word body using pre-compiled queries.
+ * tree-sitter automatically searches the entire subtree, so nested
+ * quotations [ ... ] are covered without manual recursion.
+ *
+ * @param {import('web-tree-sitter').SyntaxNode} wordNode
+ * @param {{ tagIndex: Map, mapIndex: Map, moduleIndex: Map, errors: Array, queries: object }} ctx
+ */
+function collectRefs(wordNode, ctx) {
+  const {
+    tagIndex = new Map(),
+    mapIndex = new Map(),
+    moduleIndex = new Map(),
+    errors = [],
+    queries = {},
+  } = ctx
+  const refs = { words: [], modules: [], tags: [], maps: [] }
+
+  // /wordName — local word call (regex token, no fields — strip leading /)
+  for (const { captures } of queries.wordCalls.matches(wordNode)) {
+    const name = capture(captures, 'ref')?.text?.slice(1)
+    if (name) refs.words.push(name)
+  }
+
+  // #TagName — local tag constructor
+  for (const { captures } of queries.tagRefs.matches(wordNode)) {
+    const name = capture(captures, 'name')?.text
+    if (!name) continue
+    refs.tags.push(name)
+    if (!tagIndex.has(name))
+      errors.push({ message: `Unknown tag: "${name}"`, range: toRange(capture(captures, 'ref')) })
+  }
+
+  // _TagName — tag match arm
+  for (const { captures } of queries.tagPatterns.matches(wordNode)) {
+    const name = capture(captures, 'name')?.text
+    if (!name) continue
+    refs.tags.push(name)
+    if (!tagIndex.has(name))
+      errors.push({
+        message: `Unknown tag pattern: "${name}"`,
+        range: toRange(capture(captures, 'ref')),
+      })
+  }
+
+  // $Map.field — local map accessor
+  for (const { captures } of queries.mapRefs.matches(wordNode)) {
+    const name = capture(captures, 'map_name')?.text
+    if (!name) continue
+    refs.maps.push(name)
+    if (!mapIndex.has(name))
+      errors.push({ message: `Unknown map: "${name}"`, range: toRange(capture(captures, 'ref')) })
+  }
+
+  // ~Module/word  ~Module#Tag  ~Module$Map.field
+  for (const { captures } of queries.moduleRefs.matches(wordNode)) {
+    const moduleName = capture(captures, 'module')?.text
+    if (!moduleName) continue
+    const alias = '~' + moduleName
+    refs.modules.push(alias)
+    if (!moduleIndex.has(alias))
+      errors.push({
+        message: `Unknown module: "${alias}"`,
+        range: toRange(capture(captures, 'ref')),
+      })
+  }
+
+  return refs
+}
+
+/**
+ * signature  (also used for sig_quotation — same structure)
+ *   Sequence:  '(' _sig_item* sig_arrow _sig_item* ')'
+ *
+ * We split named children at the sig_arrow node to separate inputs/outputs,
+ * then partition effects (+IO, -FAIL) out of the output items.
+ */
+function visitSignature(node) {
+  const items = node.namedChildren // includes sig_arrow + all sig items
+  const arrowIdx = items.findIndex((c) => c.type === 'sig_arrow')
+
+  const inputItems = arrowIdx >= 0 ? items.slice(0, arrowIdx) : items
+  const outputItems = arrowIdx >= 0 ? items.slice(arrowIdx + 1) : []
+
+  const isEffect = (n) => n.type === 'effect_add' || n.type === 'effect_remove'
+
+  return {
+    inputs: inputItems.filter((n) => !isEffect(n)).map(visitSigItem),
+    outputs: outputItems.filter((n) => !isEffect(n)).map(visitSigItem),
+    effects: outputItems.filter((n) => n.type === 'effect_add').map((n) => n.text.slice(1)), // strip leading +
+    negatedEffects: outputItems
+      .filter((n) => n.type === 'effect_remove')
+      .map((n) => n.text.slice(1)), // strip leading -
+  }
+}
+
+/**
+ * Map a single _sig_item node to a plain object.
+ * Mirrors signatureTypeAST / signatureRowVarAST / etc. from the hand-written parser.
+ */
+function visitSigItem(node) {
+  switch (node.type) {
+    case 'type_name':
+      return { kind: 'type', name: node.text }
+
+    case 'type_variable':
+      return { kind: 'var', name: node.text }
+
+    case 'spread': {
+      // "..name" — row variable or spread type
+      const name = node.text.slice(2)
+      const isLower = name[0] === name[0].toLowerCase()
+      return { kind: 'spread', name, isType: !isLower }
+    }
+
+    case 'sig_list':
+      // [ Type Type ... ] — list/tuple type inside a signature
+      return {
+        kind: 'list',
+        items: node.namedChildren.map(visitSigItem),
+      }
+
+    case 'sig_quotation':
+      // ( a b -- c d ) — higher-order function type (nested signature)
+      return { kind: 'quotation', ...visitSignature(node) }
+
+    default:
+      return { kind: 'unknown', text: node.text }
+  }
+}
+
+// ─── Query strings ────────────────────────────────────────────────────────────
+// Written in tree-sitter's S-expression query language.
+// Each @capture-name marks a node that will be extracted from a match result.
+// Queries are compiled once per language object and reused across calls.
+
+const QUERY_SOURCES = {
+  // ── Pass 1 ──
+  imports: `
+    (import_decl
+      path:  (import_path)  @path
+      alias: (module_alias) @alias) @decl`,
+
+  // ── Pass 2 ──
+  tags: `(tag_group name_def: (tag_group_name name: (tag_ref))) @group`,
+  maps: `(map_def    name_def: (map_name name: (map_ref))) @map`,
+
+  // ── Pass 3 ──
+  words: `
+    (word_def
+      name_def: (word_name name: (word_ref)) @name
+      sig:  (signature) @sig) @word`,
+
+  // ── Reference queries (scoped to a word node in collectRefs) ──
+  // word_call is still a regex token — no sub-fields, capture the whole node.
+  wordCalls: `(word_call) @ref`,
+
+  tagRefs: `(tag_constructor  name: (_) @name) @ref`,
+  tagPatterns: `(tag_pattern      name: (_) @name) @ref`,
+  mapRefs: `(map_access       map:  (_) @map_name) @ref`,
+
+  // Alternation [...] matches any of the three module-qualified constructs.
+  moduleRefs: `[
+    (module_word_call        module: (_) @module)
+    (module_tag_constructor  module: (_) @module)
+    (module_map_access       module: (_) @module)
+  ] @ref`,
+
+  // Syntax errors inserted by tree-sitter's error recovery
+  errors: `(ERROR) @error`,
+}
+
+// ─── Query helper ─────────────────────────────────────────────────────────────
+
+/**
+ * Get a captured node by name from a single match's captures array.
+ *
+ * @param {Array<{name: string, node: import('web-tree-sitter').SyntaxNode}>} captures
+ * @param {string} name  The @capture-name from the query string.
+ */
+const capture = (captures, name) => captures.find((c) => c.name === name)?.node ?? null
+
+// ─── Entry point ─────────────────────────────────────────────────────────────
+
+/**
+ * Build a symbol table from the root node of a tree-sitter parse tree.
+ *
+ * Uses three passes so that word bodies can be resolved against already-
+ * collected type and map definitions:
+ *
+ *   Pass 1 — imports:  build the module alias → path index
+ *   Pass 2 — types:    collect tag_group and map_def, build name indexes
+ *   Pass 3 — words:    visit word_def bodies with full type context
+ *
+ * @param {import('web-tree-sitter').SyntaxNode} rootNode
+ * @param {import('web-tree-sitter').Language}   language
+ *   The compiled Sail language object — needed to compile query strings.
+ * @returns {{ imports, tags, maps, words, errors, moduleIndex, tagIndex, mapIndex, wordIndex }}
+ */
+export function buildSymbolTable(rootNode, language) {
+  // Compile all queries once — this is cheap but not free, so callers that
+  // call buildSymbolTable repeatedly should cache the result themselves.
+  const queries = Object.fromEntries(
+    Object.entries(QUERY_SOURCES).map(([key, src]) => [key, new Query(language, src)]),
+  )
+
+  const errors = []
+
+  // ── Pass 0: syntax errors ─────────────────────────────────────────────────
+  // Collect ERROR nodes inserted by tree-sitter's error-recovery mechanism.
+  for (const { captures } of queries.errors.matches(rootNode)) {
+    const node = capture(captures, 'error')
+    if (node)
+      errors.push({ message: `Syntax error: unexpected "${node.text}"`, range: toRange(node) })
+  }
+
+  // ── Pass 1: imports ───────────────────────────────────────────────────────
+  const imports = []
+  const moduleIndex = new Map() // alias "~Io" → import record
+
+  for (const { captures } of queries.imports.matches(rootNode)) {
+    const node = capture(captures, 'decl')
+    if (!node) continue
+    const imp = visitImport(node)
+    imports.push(imp)
+    if (imp.alias) moduleIndex.set(imp.alias, imp)
+  }
+
+  // ── Pass 2: types (tag groups + maps) ────────────────────────────────────
+  const tags = []
+  const maps = []
+  const tagIndex = new Map() // "Maybe"  → tag group record
+  const mapIndex = new Map() // "Person" → map def record
+
+  for (const { captures } of queries.tags.matches(rootNode)) {
+    const node = capture(captures, 'group')
+    if (!node) continue
+    const tag = visitTagGroup(node)
+    tags.push(tag)
+    if (tag.name) tagIndex.set(tag.name, tag)
+  }
+
+  for (const { captures } of queries.maps.matches(rootNode)) {
+    const node = capture(captures, 'map')
+    if (!node) continue
+    const map = visitMapDef(node)
+    maps.push(map)
+    if (map.name) mapIndex.set(map.name, map)
+  }
+
+  // ── Pass 3: words ─────────────────────────────────────────────────────────
+  // Pass pre-compiled reference queries via context so collectRefs can use
+  // them without recompiling on every word.
+  const typeContext = { tagIndex, mapIndex, moduleIndex, errors, queries }
+
+  const words = []
+  const wordIndex = new Map()
+
+  for (const { captures } of queries.words.matches(rootNode)) {
+    const node = capture(captures, 'word')
+    if (!node) continue
+    const word = visitWordDef(node, typeContext)
+    words.push(word)
+    if (word.name) wordIndex.set(word.name, word)
+  }
+
+  return { imports, tags, maps, words, errors, moduleIndex, tagIndex, mapIndex, wordIndex }
+}