@alloy-js/core 0.1.0

package/src/code.ts

@@ -0,0 +1,220 @@
+// this code is split into a tokenizer and a parser of sorts because I feel like
+// it should be psosible to share logic between this and the babel transform, but
+// this is an exercise for the future.
+import { Child, Indent } from "@alloy-js/core";
+
+interface IndentLevelData {
+  kind: "indent";
+  children: (string | Child | IndentLevelData)[];
+  pendingLines: string[];
+}
+export function code(
+  template: TemplateStringsArray,
+  ...substitutions: Child[]
+) {
+  const indentNodes: IndentLevelData[] = [
+    {
+      kind: "indent",
+      children: [],
+      pendingLines: [],
+    },
+  ];
+
+  for (const child of childTokens(template, substitutions)) {
+    if (child.indentationLevel > indentNodes.length - 1) {
+      // indentation level increased (can only ever increase by 1)
+      pushIndent();
+    } else if (child.indentationLevel < indentNodes.length - 1) {
+      popIndent(child);
+    }
+
+    const currentIndent = indentNodes.at(-1)!;
+    if (child.kind === "line") {
+      currentIndent.pendingLines.push(child.line);
+    } else {
+      flushLines();
+      currentIndent.children.push(child.value);
+    }
+  }
+  popIndent();
+  flushLines();
+
+  function childNodesFor(indentNode: IndentLevelData): Child[] {
+    return indentNode.children.map((child) => {
+      if (
+        typeof child === "object" &&
+        child !== null &&
+        (child as any).kind === "indent"
+      ) {
+        return () =>
+          Indent({ children: childNodesFor(child as IndentLevelData) });
+      } else {
+        return child as Child;
+      }
+    });
+  }
+
+  return childNodesFor(indentNodes[0]);
+
+  function pushIndent() {
+    flushLines();
+    const newIndent: IndentLevelData = {
+      kind: "indent",
+      children: [],
+      pendingLines: [""],
+    };
+    indentNodes.at(-1)!.children.push(newIndent as any);
+    indentNodes.push(newIndent);
+  }
+
+  function popIndent(child?: ChildToken) {
+    // indentation level decreased (can decrease by many)
+    const times =
+      child ?
+        indentNodes.length - child.indentationLevel - 1
+      : indentNodes.length - 1;
+    for (let i = 0; i < times; i++) {
+      flushLines();
+      indentNodes.pop();
+    }
+    if (child) {
+      // need a linebreak after dedenting
+      indentNodes.at(-1)!.pendingLines.push("");
+    }
+  }
+  function flushLines() {
+    const currentIndent = indentNodes.at(-1)!;
+    currentIndent.children.push(currentIndent.pendingLines.join("\n"));
+    currentIndent.pendingLines = [];
+  }
+}
+
+type ChildToken = LineToken | OtherToken;
+interface ChildTokenBase {
+  kind: string;
+  indentationLevel: number;
+  newline: boolean;
+}
+
+interface LineToken extends ChildTokenBase {
+  kind: "line";
+  line: string;
+}
+
+interface OtherToken extends ChildTokenBase {
+  kind: "other";
+  value: Child;
+}
+
+function* childTokens(
+  template: TemplateStringsArray,
+  substitutions: Child[],
+): IterableIterator<ChildToken> {
+  let newline = false;
+  const indentStack: { level: number; literalIndent: string }[] = [
+    {
+      level: -1,
+      literalIndent: "",
+    },
+  ];
+
+  yield* processLiteralString(
+    template[0],
+    substitutions.length === 0 ? "only" : "first",
+  );
+  newline = false;
+  for (let i = 0; i < substitutions.length; i++) {
+    const indentationLevel = currentIndent().level;
+    yield {
+      kind: "other",
+      value: substitutions[i],
+      indentationLevel: indentationLevel < 0 ? 0 : indentationLevel,
+      newline,
+    };
+    yield* processLiteralString(
+      template[i + 1],
+      i === substitutions.length - 1 ? "last" : undefined,
+    );
+    newline = false;
+  }
+
+  function processLiteralString(
+    child: string,
+    pos?: "first" | "last" | "only",
+  ) {
+    const lines = child.split("\n");
+    const lineTokens: LineToken[] = [];
+    if ((pos === "first" || pos === "only") && lines[0].match(/^\s*$/)) {
+      // remove leading whitespace.
+      lines.shift();
+      newline = true;
+    }
+
+    if (
+      (pos === "last" || pos === "only") &&
+      lines[lines.length - 1].match(/^\s*$/)
+    ) {
+      // remove trailing whitespace
+      lines.pop();
+      if (lines.length === 1 && lines[0].trimStart() === "") {
+        // an empty line following a component most likely
+        return [];
+      }
+    }
+
+    // eslint-disable-next-line prefer-const
+    for (let [lineNum, line] of lines.entries()) {
+      if (lineNum > 0) {
+        newline = true;
+      }
+
+      if (newline) {
+        if (line === "" && currentIndent().level > -1) {
+          // for empty lines we want to just continue with the current indentation
+          lineTokens.push({
+            kind: "line",
+            line: "",
+            indentationLevel: currentIndent().level,
+            newline,
+          });
+          continue;
+        }
+        const lineIndent = line.match(/^\s+/)?.[0] ?? "";
+        const startIndent = currentIndent();
+        if (lineIndent.length > startIndent.literalIndent.length) {
+          indentStack.push({
+            level: startIndent.level + 1,
+            literalIndent: lineIndent,
+          });
+        } else {
+          while (currentIndent().literalIndent.length > lineIndent.length) {
+            indentStack.pop();
+          }
+        }
+        line = line.trimStart();
+
+        const indentationLevel = currentIndent().level;
+        lineTokens.push({
+          kind: "line",
+          line,
+          indentationLevel: indentationLevel < 0 ? 0 : indentationLevel,
+          newline,
+        });
+      } else {
+        const indentationLevel = currentIndent().level;
+        lineTokens.push({
+          kind: "line",
+          line,
+          indentationLevel: indentationLevel < 0 ? 0 : indentationLevel,
+          newline,
+        });
+      }
+    }
+
+    return lineTokens;
+  }
+
+  function currentIndent() {
+    return indentStack.at(-1)!;
+  }
+}

package/src/components/Declaration.tsx

@@ -0,0 +1,53 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+import { OutputSymbol } from "../binder.js";
+import { useContext } from "../context.js";
+import { BinderContext } from "../context/binder.js";
+import { DeclarationContext } from "../context/declaration.js";
+import { Refkey, refkey } from "../refkey.js";
+
+export interface DeclarationProps {
+  name?: string;
+  refkey?: Refkey;
+  symbol?: OutputSymbol;
+  children?: Children;
+}
+
+/**
+ * Declares a symbol in the current scope for this component's children.
+ *
+ * @remarks
+ *
+ * This component must be called in one of two ways: with a name and an optional
+ * refkey, or else passing in the symbol. When called with a name and refkey, a
+ * symbol will be created in the current scope (provided by
+ * {@link ScopeContext}) with that name and refkey. If a refkey is not provided,
+ * `refkey(props.name)` is used.
+ *
+ * When called with a symbol, that symbol is merely exposed via
+ * {@link DeclarationContext }. It is assumed that the caller of this component
+ * has created the symbol with the `createSymbol` API on the
+ * {@link BinderContext }.
+ *
+ * @see {@link BinderContext}
+ */
+export function Declaration(props: DeclarationProps) {
+  const binder = useContext(BinderContext);
+  if (!binder) {
+    throw new Error("Need binder context to create declarations");
+  }
+
+  let declaration;
+  if (props.symbol) {
+    declaration = props.symbol;
+  } else {
+    const rk = props.refkey ? props.refkey : refkey(props.name);
+    declaration = binder.createSymbol({
+      name: props.name!,
+      refkey: rk,
+    });
+  }
+
+  return <DeclarationContext.Provider value={declaration}>
+    {props.children}
+  </DeclarationContext.Provider>;
+}

package/src/components/Indent.tsx

@@ -0,0 +1,33 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+import { useContext } from "../context.js";
+import { IndentContext } from "../context/indent.js";
+
+export interface IndentProps {
+  children?: Children;
+  indent?: string;
+}
+
+export interface IndentState {
+  level: number;
+  indent: string;
+  indentString: string; // awful name
+  noLeading?: boolean;
+}
+
+export function Indent(props: IndentProps) {
+  const previousIndent = useContext(IndentContext) ?? {
+    level: 0,
+    indent: props.indent ?? "  ",
+    indentString: "",
+  };
+
+  const level = previousIndent.level + 1;
+
+  const currentIndent = {
+    level,
+    indent: props.indent ?? previousIndent.indent,
+    indentString: (props.indent ?? previousIndent.indent).repeat(level),
+  };
+
+  return <IndentContext.Provider value={currentIndent}>{props.children}</IndentContext.Provider>;
+}

package/src/components/MemberDeclaration.tsx

@@ -0,0 +1,62 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+import { OutputSymbol, OutputSymbolFlags } from "../binder.js";
+import { useContext } from "../context.js";
+import { BinderContext } from "../context/binder.js";
+import { MemberDeclarationContext } from "../context/member-declaration.js";
+import { Refkey, refkey } from "../refkey.js";
+
+export interface MemberDeclarationProps {
+  name?: string;
+  refkey?: Refkey;
+  symbol?: OutputSymbol;
+  children?: Children;
+  static?: boolean;
+}
+
+/**
+ * Declares a symbol in the current member scope for this component's children.
+ *
+ * @remarks
+ *
+ * This component must be called in one of two ways: with a name and an optional
+ * refkey, or else passing in the symbol. When called with a name and refkey, a
+ * symbol will be created in the current scope (provided by
+ * {@link MemberDeclarationContext}) with that name and refkey. If a refkey is not
+ * provided, `refkey(props.name)` is used.
+ *
+ * When called with a symbol, that symbol is merely exposed via
+ * {@link MemberDeclarationContext}. It is assumed that the caller of this component
+ * has created the symbol with the `createSymbol` API on the
+ * {@link BinderContext}.
+ *
+ * @see {@link BinderContext}
+ */
+export function MemberDeclaration(props: MemberDeclarationProps) {
+  const binder = useContext(BinderContext);
+  if (!binder) {
+    throw new Error("Need binder context to create declarations");
+  }
+
+  let declaration;
+  if (props.symbol) {
+    declaration = props.symbol;
+  } else {
+    if (!props.name) {
+      throw new Error(
+        "Must provide a member name, or else provide a member symbol",
+      );
+    }
+    const rk = props.refkey ? props.refkey : refkey(props.name);
+    declaration = binder.createSymbol({
+      name: props.name!,
+      refkey: rk,
+      flags: props.static ?
+        OutputSymbolFlags.StaticMember
+      : OutputSymbolFlags.InstanceMember,
+    });
+  }
+
+  return <MemberDeclarationContext.Provider value={declaration}>
+    {props.children}
+  </MemberDeclarationContext.Provider>;
+}

package/src/components/MemberName.tsx

@@ -0,0 +1,11 @@
+import { useContext } from "../context.js";
+import { MemberDeclarationContext } from "../context/member-declaration.js";
+
+export function MemberName() {
+  const declSymbol = useContext(MemberDeclarationContext);
+  if (!declSymbol) {
+    return "(no member declaration context)";
+  }
+
+  return <>{declSymbol.name}</>;
+}

package/src/components/MemberScope.tsx

@@ -0,0 +1,40 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+import { OutputSymbol } from "../binder.js";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { OutputSymbolFlags } from "../binder.js";
+import { MemberScopeContext } from "../context/member-scope.js";
+export interface MemberScopeProps {
+  /**
+   * The name of the member scope.
+   */
+  name?: string;
+
+  /**
+   * The symbol that owns these members. This symbol must have either
+   * {@link OutputSymbolFlags.InstanceMemberContainer} or
+   * {@link OutputSymbolFlags.StaticMemberContainer}.
+   */
+  owner: OutputSymbol;
+  children?: Children;
+}
+
+/**
+ * Declare a member scope, which is a scope that holds instance and static
+ * members. This scope is then used for nested instance or static member
+ * declarations and resolution of instance members.
+ *
+ * @remarks
+ *
+ * The member scope contains scopes for both instance and static members.
+ * However, it does not affect the resolution of static members.
+ */
+export function MemberScope(props: MemberScopeProps) {
+  const context: MemberScopeContext = {
+    instanceMembers: props.owner.instanceMemberScope,
+    staticMembers: props.owner.staticMemberScope,
+  };
+  return <MemberScopeContext.Provider value={context}>
+      {props.children}
+    </MemberScopeContext.Provider>;
+}

package/src/components/Name.tsx

@@ -0,0 +1,11 @@
+import { useContext } from "../context.js";
+import { DeclarationContext } from "../context/declaration.js";
+
+export function Name() {
+  const declSymbol = useContext(DeclarationContext);
+  if (!declSymbol) {
+    return "";
+  }
+
+  return <>{declSymbol.name}</>;
+}

package/src/components/Output.tsx

@@ -0,0 +1,69 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+import {
+  createOutputBinder,
+  getSymbolCreator,
+  SymbolCreator,
+} from "../binder.js";
+import { BinderContext } from "../context/binder.js";
+import { NamePolicyContext } from "../context/name-policy.js";
+import { NamePolicy } from "../name-policy.js";
+import { SourceDirectory } from "./SourceDirectory.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { SourceFile } from "./SourceFile.js";
+
+export interface OutputProps {
+  children?: Children;
+  /**
+   * External libraries whose symbols should be available for reference.
+   */
+  externals?: SymbolCreator[];
+
+  /**
+   * Name policy to use for this output.
+   */
+  namePolicy?: NamePolicy<string>;
+
+  /**
+   * Policy for handling multiple symbols declared with the same name.
+   */
+  nameConflictResolver?: (name: string, symbols: any[]) => void;
+
+  /**
+   * The base path for the output contents. Defaults to "."
+   */
+  basePath?: string;
+}
+
+/**
+ * This component is the root component for all your emitted output. Place your
+ * various {@link SourceDirectory} and {@link SourceFile} components inside
+ * `Output` to create directories and files in your output directory.
+ *
+ * @see {@link NamePolicyContext}
+ */
+export function Output(props: OutputProps) {
+  const basePath = props.basePath ?? "./";
+  const binder = createOutputBinder({
+    nameConflictResolver: props.nameConflictResolver,
+  });
+  const dir =
+    <SourceDirectory path={basePath}>
+    {props.children}
+  </SourceDirectory>;
+
+  if (props.externals) {
+    for (const global of props.externals) {
+      getSymbolCreator(global)(binder);
+    }
+  }
+
+  return <BinderContext.Provider value={binder}>
+    {
+      props.namePolicy ?
+        <NamePolicyContext.Provider value={props.namePolicy}>
+          {dir}
+        </NamePolicyContext.Provider> :
+        dir
+    }
+  </BinderContext.Provider>;
+}

package/src/components/Scope.tsx

@@ -0,0 +1,27 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+import { OutputScope } from "../binder.js";
+import { useContext } from "../context.js";
+import { BinderContext } from "../context/binder.js";
+import { ScopeContext } from "../context/scope.js";
+
+export interface ScopeProps {
+  kind?: string;
+  name?: string;
+  value?: OutputScope;
+  children?: Children;
+}
+
+export function Scope(props: ScopeProps) {
+  let scope: OutputScope;
+  if (props.value) {
+    scope = props.value;
+  } else {
+    const kind = props.kind ?? "file";
+    const binder = useContext(BinderContext)!;
+    scope = binder.createScope({ kind, name: props.name! });
+  }
+
+  return <ScopeContext.Provider value={scope}>
+      {props.children}
+    </ScopeContext.Provider>;
+}

package/src/components/SourceDirectory.tsx

@@ -0,0 +1,43 @@
+import { Children, getContext } from "@alloy-js/core/jsx-runtime";
+import { shallowReactive } from "@vue/reactivity";
+import { join } from "pathe";
+import { useContext } from "../context.js";
+import { SourceDirectoryContext } from "../context/source-directory.js";
+
+export interface SourceDirectoryProps {
+  path: string;
+  children?: Children[];
+}
+
+export function SourceDirectory(props: SourceDirectoryProps) {
+  const parentDir = useContext(SourceDirectoryContext);
+  // todo: this can probably just use context.
+  const sdPath = parentDir ? join(parentDir.path, props.path) : props.path;
+  const nodeContext = getContext()!;
+  const context = createSourceDirectoryContext(props.path, parentDir);
+
+  nodeContext.meta ??= {};
+  nodeContext.meta.directory = {
+    path: sdPath,
+  };
+  return <SourceDirectoryContext.Provider value={context}>{props.children}</SourceDirectoryContext.Provider>;
+}
+
+function createSourceDirectoryContext(
+  path: string = "./",
+  parentDir?: SourceDirectoryContext,
+): SourceDirectoryContext {
+  const contents = shallowReactive([] as any);
+  const context: SourceDirectoryContext = {
+    path: parentDir ? join(parentDir.path, path) : path,
+    contents,
+    addContent(content) {
+      contents.push(content);
+    },
+  };
+  if (parentDir) {
+    parentDir.addContent(context);
+  }
+
+  return context;
+}

package/src/components/SourceFile.tsx

@@ -0,0 +1,33 @@
+import {
+  Children,
+  ComponentDefinition,
+  getContext,
+} from "@alloy-js/core/jsx-runtime";
+import { join } from "pathe";
+import { useContext } from "../context.js";
+import { SourceDirectoryContext } from "../context/source-directory.js";
+import { SourceFileContext } from "../context/source-file.js";
+import { Refkey } from "../refkey.js";
+
+export interface SourceFileProps {
+  path: string;
+  filetype: string;
+  children?: Children[];
+  reference?: ComponentDefinition<{ refkey: Refkey }>;
+}
+
+export function SourceFile(props: SourceFileProps) {
+  const parentDirectory = useContext(SourceDirectoryContext)!;
+  const context: SourceFileContext = {
+    path: join(parentDirectory ? parentDirectory.path : "", props.path),
+    filetype: props.filetype,
+    reference: props.reference,
+  };
+  parentDirectory?.addContent(context);
+  const nodeContext = getContext()!;
+  nodeContext.meta ??= {};
+  nodeContext.meta.sourceFile = context;
+  return <SourceFileContext.Provider value={context}>
+    {props.children}
+  </SourceFileContext.Provider>;
+}

package/src/components/index.tsx

@@ -0,0 +1,10 @@
+export * from "./Declaration.js";
+export * from "./Indent.js";
+export * from "./MemberDeclaration.jsx";
+export * from "./MemberName.jsx";
+export * from "./MemberScope.jsx";
+export * from "./Name.jsx";
+export * from "./Output.js";
+export * from "./Scope.js";
+export * from "./SourceDirectory.js";
+export * from "./SourceFile.js";

package/src/components/stc/index.ts

@@ -0,0 +1,9 @@
+import { stc } from "../../utils.js";
+import * as base from "../index.js";
+
+export const Declaration = stc(base.Declaration);
+export const Indent = stc(base.Indent);
+export const Output = stc(base.Output);
+export const Scope = stc(base.Scope);
+export const SourceDirectory = stc(base.SourceDirectory);
+export const SourceFile = stc(base.SourceFile);

package/src/context/assignment.ts

@@ -0,0 +1,57 @@
+import { OutputSymbol } from "../binder.js";
+import { ComponentContext, createContext, useContext } from "../context.js";
+
+export interface AssignmentContext {
+  /**
+   * The symbol that is the target of the current assignment.
+   */
+  target: OutputSymbol;
+
+  /**
+   * Whether the symbol has had a value assigned to it. Once the symbol has been
+   * assigned, subsequent assignments will have no effect.
+   */
+  isAssigned: boolean;
+}
+
+/**
+ * AssignmentContext provides the symbol that is the target of the current
+ * assignment.
+ *
+ * @remarks
+ *
+ * When a variable is declared, the symbol for the variable doesn't yet know
+ * what value it will hold, because that depends on the assignment to the
+ * variable in the variable declaration's initializer. This context provides the
+ * symbol that is the target of the current assignment, so that children of an
+ * assignment or initializer can provide additional symbol information.
+ *
+ * For example, when assigning an object value expression to a variable, the
+ * object value expression should use assignment context to provide the member
+ * symbols for the object value's properties.
+ */
+export const AssignmentContext: ComponentContext<AssignmentContext> =
+  createContext();
+
+/**
+ * Creates a new {@link (AssignmentContext:interface)}.
+ *
+ * @param target - The symbol that is the target of the current assignment.
+ * @returns A new {@link (AssignmentContext:interface)}.
+ */
+export function createAssignmentContext(
+  target: OutputSymbol,
+): AssignmentContext {
+  return {
+    isAssigned: false,
+    target,
+  };
+}
+
+export function getAssignmentSymbol() {
+  const assignmentContext = useContext(AssignmentContext);
+  if (assignmentContext) {
+    return assignmentContext.target;
+  }
+  return undefined;
+}