@cotal-ai/lang 0.23.0 → 0.25.0

package/dist/syntax.js

@@ -0,0 +1,178 @@
+/**
+ * The syntax table: every node type acorn can produce, sorted into the sets the language is made of.
+ *
+ * ONE TABLE, READ BY BOTH HALVES. The validator admits exactly {@link ADMITTED_NODES} and
+ * {@link STRUCTURAL_NODES}, refuses each row of {@link FORBIDDEN_NODES} with its own code, and refuses
+ * everything else with L1029. The interpreter executes exactly the admitted set. `surface.smoke`
+ * holds the two halves to this file: every admitted node type is executed by a program, every
+ * `case` label in the interpreter's node switches is on this table, and every node type acorn knows
+ * lands in exactly one set. Before this table existed the two halves were two hand-kept lists, and
+ * `x++`, `?.`, rest parameters and `**` were admitted by one and refused by the other.
+ */
+/** Node types the interpreter executes. A validated program is made of these and nothing else. */
+export const ADMITTED_NODES = new Set([
+    // statements
+    "Program",
+    "ExpressionStatement",
+    "VariableDeclaration",
+    "FunctionDeclaration",
+    "BlockStatement",
+    "IfStatement",
+    "WhileStatement",
+    "ForStatement",
+    "ForOfStatement",
+    "ReturnStatement",
+    "BreakStatement",
+    "ContinueStatement",
+    "ThrowStatement",
+    "TryStatement",
+    "SwitchStatement",
+    "EmptyStatement",
+    // expressions
+    "Literal",
+    "Identifier",
+    "TemplateLiteral",
+    "ArrayExpression",
+    "ObjectExpression",
+    "MemberExpression",
+    "ChainExpression",
+    "UnaryExpression",
+    "UpdateExpression",
+    "BinaryExpression",
+    "LogicalExpression",
+    "ConditionalExpression",
+    "AssignmentExpression",
+    "AwaitExpression",
+    "ArrowFunctionExpression",
+    "FunctionExpression",
+    "CallExpression",
+]);
+/**
+ * Node types that only occur INSIDE an admitted node and are executed as part of it: a `Property`
+ * inside an object literal, a `SwitchCase` inside a `switch`, a pattern inside a declaration.
+ */
+export const STRUCTURAL_NODES = new Set([
+    "VariableDeclarator",
+    "Property",
+    "SpreadElement",
+    "RestElement",
+    "AssignmentPattern",
+    "ObjectPattern",
+    "ArrayPattern",
+    "TemplateElement",
+    "SwitchCase",
+    "CatchClause",
+]);
+/** Node types rejected outright, with the code and the repair to suggest. */
+export const FORBIDDEN_NODES = Object.freeze({
+    ClassDeclaration: {
+        code: "L1001",
+        cause: "There are no classes in this language. State lives in records and behaviour lives in functions.",
+        fix: "Replace the class with a function that returns a record.",
+    },
+    ClassExpression: {
+        code: "L1001",
+        cause: "There are no classes in this language. State lives in records and behaviour lives in functions.",
+        fix: "Replace the class with a function that returns a record.",
+    },
+    ThisExpression: {
+        code: "L1002",
+        cause: "`this` does not exist, so nothing can capture a calling context by accident.",
+        fix: "Pass what the function needs as an argument.",
+    },
+    ForInStatement: {
+        code: "L1004",
+        cause: "`for...in` walks an unspecified order and reaches inherited names, so it cannot be deterministic.",
+        fix: "Iterate explicitly: `for (const k of keys(record)) { ... }`.",
+    },
+    YieldExpression: {
+        code: "L1005",
+        cause: "Generators suspend and resume outside the effect journal, so a resumed run could not reproduce them.",
+        fix: "Use a loop, and `await` the effects inside it.",
+    },
+    TaggedTemplateExpression: {
+        code: "L1018",
+        cause: "A tagged template runs user code during evaluation of a literal, which hides an effect inside what looks like data.",
+        fix: "Use a plain template literal, or call the function explicitly.",
+    },
+    NewExpression: {
+        code: "L1019",
+        cause: "There are no constructors, so `new` has nothing to construct.",
+        fix: "Build a record literal, or call a function that returns one.",
+    },
+    ImportDeclaration: {
+        code: "L1020",
+        cause: "A program is exactly one module, because a run pins to the content hash of its source.",
+        fix: "Define the function in this file. Shared procedures are ordinary functions.",
+    },
+    ImportExpression: {
+        code: "L1020",
+        cause: "A program is exactly one module, because a run pins to the content hash of its source; a dynamic `import()` would load code the hash does not cover.",
+        fix: "Define the function in this file. Shared procedures are ordinary functions.",
+    },
+    ExportNamedDeclaration: {
+        code: "L1020",
+        cause: "A program is exactly one module and has nothing to export to.",
+        fix: "Remove the `export`.",
+    },
+    ExportDefaultDeclaration: {
+        code: "L1020",
+        cause: "A program is exactly one module and has nothing to export to.",
+        fix: "Remove the `export`.",
+    },
+    ExportAllDeclaration: {
+        code: "L1020",
+        cause: "A program is exactly one module and has nothing to export to.",
+        fix: "Remove the `export`.",
+    },
+    DoWhileStatement: {
+        code: "L1022",
+        cause: "`do...while` is not in the language.",
+        fix: "Use `while` with the condition checked first, or a `for` loop.",
+    },
+    LabeledStatement: {
+        code: "L1017",
+        cause: "Labels turn the derived flowchart's back-edges into arbitrary jumps.",
+        fix: "Restructure with a helper function or a boolean flag.",
+    },
+    SequenceExpression: {
+        code: "L1026",
+        cause: "The comma operator evaluates several expressions and keeps only the last, which hides work inside one expression.",
+        fix: "Write one statement per expression.",
+    },
+    MetaProperty: {
+        code: "L1020",
+        cause: "`import.meta` and `new.target` describe a module system and constructors, and this language has neither.",
+        fix: "Use `run()` for this run's own metadata.",
+    },
+    DebuggerStatement: {
+        code: "L1029",
+        cause: "`debugger` addresses a host debugger, and there is no host to address.",
+        fix: "Use `log(...)` to trace a value.",
+    },
+});
+/** Node types that occur only inside a forbidden node and are reported through their parent's row. */
+export const FORBIDDEN_CHILDREN = Object.freeze([
+    "ClassBody",
+    "MethodDefinition",
+    "PropertyDefinition",
+    "StaticBlock",
+    "PrivateIdentifier",
+    "Super",
+    "ImportSpecifier",
+    "ImportDefaultSpecifier",
+    "ImportNamespaceSpecifier",
+    "ExportSpecifier",
+]);
+/**
+ * Every node type acorn 8 emits for `ecmaVersion: 2023, sourceType: "module"`, whether or not it
+ * is in the language. `surface.smoke` asserts each one lands in exactly one of the sets above, so a
+ * node type acorn adds or one this file forgets is a red suite rather than a runtime surprise.
+ */
+export const KNOWN_NODES = Object.freeze([
+    ...ADMITTED_NODES,
+    ...STRUCTURAL_NODES,
+    ...Object.keys(FORBIDDEN_NODES),
+    ...FORBIDDEN_CHILDREN,
+]);
+//# sourceMappingURL=syntax.js.map

package/dist/syntax.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax.js","sourceRoot":"","sources":["../src/syntax.ts"],"names":[],"mappings":"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"}

package/dist/transform/emit.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The emitter: one rule per admitted node type, and every rule that carries a law routes it through
+ * the seam rather than restating it.
+ *
+ * The walk order here is the walker's walk order, deliberately and line by line: a journal's step
+ * keys are occurrence counters allocated at the call, so two engines agree on a journal only if they
+ * agree on the ORDER effects are reached in. Where this file departs from the shape of
+ * `interpret.ts` it is because native JavaScript already has the meaning (block scoping, `switch`
+ * selection, `try`/`finally` completions) and re-deriving it would be a second implementation to
+ * keep in step.
+ */
+import { type AnyNode } from "./scope.js";
+import { type Names } from "./seam.js";
+export interface Emission {
+    readonly module: string;
+    /** How many times each seam member is reached. A check reports its count, not merely that it ran. */
+    readonly sites: Readonly<Record<string, number>>;
+    /** Which SURFACED-but-unruled members this emission needed. Empty is the landing condition. */
+    readonly proposed: readonly string[];
+    readonly names: Names;
+}
+export declare function emit(program: AnyNode): Emission;
+//# sourceMappingURL=emit.d.ts.map

package/dist/transform/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/transform/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAA0B,KAAK,OAAO,EAAgB,MAAM,YAAY,CAAC;AAEhF,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AASlD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAg7BD,wBAAgB,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAO/C"}