devabhasha 1.0.0

package/src/symbols.js

@@ -0,0 +1,194 @@
+// symbols.js — a scope-aware symbol table over the AST.
+//
+// Powers go-to-definition and rename in the language server. It walks the AST
+// tracking lexical scopes: every binding (चर/नियत/कार्य/भाव/रूपनाम, function
+// parameters, प्रत्येकम् loop variables) records its name and source position,
+// and every Identifier reference is resolved to the binding it sees under
+// normal shadowing rules. The result lets us answer:
+//   • definitionOf(line, col)  → where the name at this position is bound
+//   • referencesOf(binding)    → every occurrence bound to THAT binding
+//
+// Positions are 1-based (line, col), matching the lexer/parser.
+
+import { tokenize } from './lexer.js';
+import { parse } from './parser.js';
+
+// A Scope maps a name → binding record. Bindings live in the scope where the
+// declaration appears; lookups walk outward to enclosing scopes.
+function makeScope(parent) {
+  return { parent, names: new Map() };
+}
+function declare(scope, name, binding) {
+  scope.names.set(name, binding);
+}
+function resolve(scope, name) {
+  for (let s = scope; s; s = s.parent) {
+    if (s.names.has(name)) return s.names.get(name);
+  }
+  return null;
+}
+
+// Build the symbol table. Returns { bindings, references }:
+//   bindings   — array of { name, line, col, id }
+//   references — array of { name, line, col, binding|null }
+export function buildSymbols(source) {
+  let ast;
+  try { ast = parse(tokenize(source)); }
+  catch { return { bindings: [], references: [], ok: false }; }
+
+  const bindings = [];
+  const references = [];
+  let nextId = 0;
+
+  const addBinding = (name, pos, scope) => {
+    if (!pos) return null;
+    const b = { name, line: pos.line, col: pos.col, id: nextId++ };
+    bindings.push(b);
+    declare(scope, name, b);
+    return b;
+  };
+  const addRef = (name, pos, scope) => {
+    if (!pos) return;
+    references.push({ name, line: pos.line, col: pos.col, binding: resolve(scope, name) });
+  };
+
+  // walk an expression, recording references
+  function walkExpr(node, scope) {
+    if (!node || typeof node !== 'object') return;
+    switch (node.type) {
+      case 'Identifier':
+        addRef(node.name, { line: node.line, col: node.col }, scope);
+        return;
+      case 'FuncExpr': {
+        const fscope = makeScope(scope);
+        (node.params || []).forEach((p, i) =>
+          addBinding(p, node.params.__pos && node.params.__pos[i], fscope));
+        walkBlock(node.body, fscope);
+        return;
+      }
+      case 'Member':
+        walkExpr(node.object, scope);
+        if (node.computed) walkExpr(node.property, scope);
+        // non-computed property is not a reference to a binding
+        return;
+      default:
+        // generic structural walk over child nodes/arrays
+        for (const k of Object.keys(node)) {
+          if (k === 'line' || k === 'col' || k === 'namePos' || k === 'paramPos') continue;
+          const v = node[k];
+          if (Array.isArray(v)) v.forEach(c => walkExpr(c, scope));
+          else if (v && typeof v === 'object' && v.type) walkExpr(v, scope);
+        }
+    }
+  }
+
+  // walk a block/body (array of statements or a {body:[]} node) in a NEW scope
+  function walkBlock(block, scope) {
+    const body = Array.isArray(block) ? block : (block && block.body) || [];
+    for (const s of body) walkStmt(s, scope);
+  }
+
+  function walkStmt(node, scope) {
+    if (!node || typeof node !== 'object') return;
+    switch (node.type) {
+      case 'VarDecl':
+        if (node.init) walkExpr(node.init, scope);  // init sees the OUTER scope
+        addBinding(node.name, node.namePos, scope);
+        return;
+      case 'StateDecl':
+        if (node.init) walkExpr(node.init, scope);
+        addBinding(node.name, node.namePos, scope);
+        return;
+      case 'StyleDecl':
+        addBinding(node.name, node.namePos, scope);
+        (node.pairs || []).forEach(p => p.value && p.value.kind === 'expr' && walkExpr(p.value.value, scope));
+        return;
+      case 'FuncDecl': {
+        addBinding(node.name, node.namePos, scope);   // function name in outer scope
+        const fscope = makeScope(scope);
+        (node.params || []).forEach((p, i) =>
+          addBinding(p, node.paramPos && node.paramPos[i], fscope));
+        walkBlock(node.body, fscope);
+        return;
+      }
+      case 'ForOf': {
+        walkExpr(node.iterable, scope);
+        const lscope = makeScope(scope);
+        addBinding(node.item, node.namePos, lscope);
+        walkBlock(node.body, lscope);
+        return;
+      }
+      case 'Block':
+        walkBlock(node.body, makeScope(scope));
+        return;
+      case 'If':
+        walkExpr(node.test, scope);
+        node.consequent && walkBlock(node.consequent.body || node.consequent, makeScope(scope));
+        node.alternate && walkBlock(node.alternate.body || node.alternate, makeScope(scope));
+        return;
+      case 'While':
+        walkExpr(node.test, scope);
+        node.body && walkBlock(node.body.body || node.body, makeScope(scope));
+        return;
+      case 'Export':
+        walkStmt(node.decl, scope);
+        return;
+      case 'View':
+        node.container && walkExpr(node.container, scope);
+        node.body && walkBlock(node.body.body || node.body, makeScope(scope));
+        return;
+      case 'ExpressionStatement':
+        walkExpr(node.expression, scope);
+        return;
+      default:
+        // structural fallback: walk children as expressions
+        for (const k of Object.keys(node)) {
+          if (k === 'line' || k === 'col' || k === 'namePos' || k === 'paramPos') continue;
+          const v = node[k];
+          if (Array.isArray(v)) v.forEach(c => c && c.type && walkExpr(c, scope));
+          else if (v && typeof v === 'object' && v.type) walkExpr(v, scope);
+        }
+    }
+  }
+
+  const top = makeScope(null);
+  walkBlock(ast, top);
+  // compound assignment (x += y) desugars to x = x + y, which visits the
+  // target identifier twice; dedup references sharing an exact position.
+  const seen = new Set();
+  const deduped = references.filter(r => {
+    const key = r.name + '@' + r.line + ':' + r.col;
+    if (seen.has(key)) return false;
+    seen.add(key); return true;
+  });
+  return { bindings, references: deduped, ok: true };
+}
+
+// Find the binding referenced at (line, col): either a reference sitting on
+// that position, or a binding declared there. Returns the binding record.
+export function definitionAt(source, line, col) {
+  const { bindings, references } = buildSymbols(source);
+  // a reference whose span covers the position?
+  const ref = references.find(r => r.line === line && col >= r.col && col < r.col + r.name.length);
+  if (ref) return ref.binding || null;
+  // already on a binding?
+  const b = bindings.find(b => b.line === line && col >= b.col && col < b.col + b.name.length);
+  return b || null;
+}
+
+// All occurrences (the binding + every reference bound to it) for the symbol
+// at (line, col). Returns an array of { line, col, name } edit locations.
+export function occurrencesAt(source, line, col) {
+  const { bindings, references } = buildSymbols(source);
+  // resolve the target binding from the cursor
+  let target = null;
+  const ref = references.find(r => r.line === line && col >= r.col && col < r.col + r.name.length);
+  if (ref) target = ref.binding;
+  if (!target) target = bindings.find(b => b.line === line && col >= b.col && col < b.col + b.name.length);
+  if (!target) return [];
+  const out = [{ line: target.line, col: target.col, name: target.name }];
+  for (const r of references) {
+    if (r.binding && r.binding.id === target.id) out.push({ line: r.line, col: r.col, name: r.name });
+  }
+  return out;
+}

package/src/vibhakti.js

@@ -0,0 +1,87 @@
+// vibhakti.js — the kāraka/case engine.
+//
+// Given an inflected Devanagari noun, detect its vibhakti (case ending),
+// recover the stem, and map the case to a kāraka (semantic role).
+//
+// SCOPE (honest): full Sanskrit declension is stem-class- and gender-
+// dependent and very large. We implement the अकारान्त पुंल्लिङ्ग/नपुंसकलिङ्ग
+// (a-stem masc/neut) singular paradigm robustly — this covers the great
+// majority of coined technical vocabulary — plus a particle-style escape
+// hatch. Extending to other stems = adding rows to PARADIGMS.
+
+// The six kārakas + two non-kāraka relations we also accept (sambandha =
+// genitive "of", which is structurally useful for property access).
+export const KARAKA = {
+  KARTR:      'kartr',       // agent      — nominative   (प्रथमा)
+  KARMAN:     'karman',      // patient    — accusative   (द्वितीया)
+  KARANA:     'karana',      // instrument — instrumental (तृतीया)
+  SAMPRADANA: 'sampradana',  // recipient  — dative       (चतुर्थी)
+  APADANA:    'apadana',     // source     — ablative     (पञ्चमी)
+  SAMBANDHA:  'sambandha',   // relation   — genitive     (षष्ठी)
+  ADHIKARANA: 'adhikarana',  // locus      — locative     (सप्तमी)
+};
+
+// a-stem singular endings (after the stem, which ends in the inherent 'अ').
+// We express each ending as the sequence that REPLACES the stem-final 'अ'.
+// Written in Devanagari as the surface suffix on a consonant-final stem.
+// Example stem: रक्त (rakta) → रक्तः (nom), रक्तम् (acc), रक्तेन (instr)…
+//
+// We store endings as the trailing string of the FULL word so the matcher
+// can do longest-suffix matching. Order longest-first.
+const A_STEM_SINGULAR = [
+  // [ surface ending, case, kāraka,  stemEndsWith ]
+  // The stem is recovered by removing `ending` and restoring final 'अ'
+  // where the paradigm fuses it.
+  { end: 'स्मिन्', case: 'locative',     karaka: KARAKA.ADHIKARANA, restore: 'अ' }, // rare pronominal; keep before others
+  { end: 'ेषु',   case: 'locative_pl',  karaka: KARAKA.ADHIKARANA, restore: 'अ' },
+  { end: 'ेन',    case: 'instrumental', karaka: KARAKA.KARANA,      restore: 'अ' }, // रक्तेन
+  { end: 'ाय',    case: 'dative',       karaka: KARAKA.SAMPRADANA,  restore: 'अ' }, // रक्ताय
+  { end: 'ात्',   case: 'ablative',     karaka: KARAKA.APADANA,     restore: 'अ' }, // रक्तात्
+  { end: 'स्य',   case: 'genitive',     karaka: KARAKA.SAMBANDHA,   restore: 'अ' }, // रक्तस्य
+  { end: 'े',     case: 'locative',     karaka: KARAKA.ADHIKARANA,  restore: 'अ' }, // रक्ते
+  { end: 'म्',    case: 'accusative',   karaka: KARAKA.KARMAN,      restore: 'अ' }, // रक्तम्
+  { end: 'ः',     case: 'nominative',   karaka: KARAKA.KARTR,       restore: 'अ' }, // रक्तः
+];
+
+// Virama / halant and the inherent vowel handling.
+const VIRAMA = '\u094D';
+const INHERENT = 'अ';
+
+// Some words are written with an explicit final consonant+virama in the
+// stem (e.g. अङ्गम् the keyword). For nominal arguments we expect the
+// surface forms above.
+
+// Detect: returns { stem, case, karaka } or null if no case ending found.
+export function analyze(word) {
+  for (const row of A_STEM_SINGULAR) {
+    if (word.endsWith(row.end)) {
+      let stem = word.slice(0, word.length - row.end.length);
+      // The a-stem fuses the stem-final inherent 'अ' with the ending.
+      // After stripping the ending, `stem` ends in a bare consonant
+      // (no virama shown because the inherent vowel was consumed by the
+      // ending). We restore the citation form by appending nothing —
+      // the consonant already implies 'अ' in Devanagari. So `stem` IS
+      // the dictionary stem in surface form.
+      if (stem.length === 0) continue;
+      return { stem, case: row.case, karaka: row.karaka, ending: row.end };
+    }
+  }
+  return null;
+}
+
+// Map a kāraka role-name (used by codegen) from a detected analysis.
+export function karakaOf(word) {
+  const a = analyze(word);
+  return a ? a.karaka : null;
+}
+
+// For diagnostics / REPL: pretty Sanskrit name of a kāraka.
+export const KARAKA_NAME_SA = {
+  [KARAKA.KARTR]:      'कर्तृ',
+  [KARAKA.KARMAN]:     'कर्म',
+  [KARAKA.KARANA]:     'करण',
+  [KARAKA.SAMPRADANA]: 'सम्प्रदान',
+  [KARAKA.APADANA]:    'अपादान',
+  [KARAKA.SAMBANDHA]:  'सम्बन्ध',
+  [KARAKA.ADHIKARANA]: 'अधिकरण',
+};