refactor: concise comments in schemaJson and symbols

Author: huydo862003

packages/dbml-parse/src/core/types/schemaJson.ts

@@ -11,35 +11,16 @@ export interface TokenPosition {
   filepath: Filepath;
 }
 
-// A reference to an element imported via `use` or `reuse`.
-// `name` + `schemaName` identify the original element in the source file.
-// `visibleNames` lists every local name under which the element is reachable
-// in this file (original name if directly imported, alias name if `as` used,
-// multiple entries when re-exported under several names).
+// Reference to an imported element. Resolved by exportSchemaJson.
 export interface ElementRef {
-  // Canonical name of the element in its source file.
-  name: string;
+  name: string;                    // canonical name in source file
   schemaName: string | null;
-
-  // All names this element is visible under in the importing file.
-  // Priority during export:
-  //   visibleNames[0] becomes the PRIMARY name in the reconciled Database.
-  //   visibleNames[1..] become Alias entries pointing at the primary.
-  // If an alias was used (`use { table users as u }`), the alias appears
-  // first, so `u` becomes the primary and `users` is dropped. The alias
-  // also strips schemaName (schemaName: null) so the element appears
-  // unqualified in the importing file's namespace.
-  visibleNames: {
-    schemaName: string | null;
-    name: string;
-  }[];
+  // [0] = primary name in exported JSON, [1..] = aliases.
+  // Alias strips schemaName to null.
+  visibleNames: { schemaName: string | null; name: string }[];
 }
 
-// Elements imported into this file via `use` / `reuse` declarations.
-// These are NOT the elements themselves — they are references pointing at
-// elements that live in other files. `exportSchemaJson` resolves each ref
-// into an actual element from the MasterDatabase and inserts it into the
-// reconciled Database under the local visible name.
+// Imported elements - refs to other files, resolved by exportSchemaJson.
 export interface DatabaseExternals {
   tables: ElementRef[];
   enums: ElementRef[];
@@ -71,11 +52,8 @@ export interface DiagramView {
   token: TokenPosition;
 }
 
-// Per-file interpreted schema. Contains both local elements (declared in
-// this file) and `externals` (references to elements imported from other
-// files). After `exportSchemaJson` reconciliation, the externals are
-// resolved into real elements and merged into the top-level arrays, so the
-// output looks like a single-file Database to downstream consumers.
+// Per-file schema. Local elements + externals (import refs).
+// After exportSchemaJson, externals are merged in and output looks single-file.
 export interface Database {
   schemas: [];
   tables: Table[];
@@ -87,18 +65,12 @@ export interface Database {
   project?: Project;
   tablePartials: TablePartial[];
   records: TableRecord[];
-  // Imported elements — populated by interpretNode, consumed by exportSchemaJson.
-  externals: DatabaseExternals;
+  externals: DatabaseExternals; // populated by interpretNode, consumed by exportSchemaJson
   diagramViews: DiagramView[];
   token?: TokenPosition;
 }
 
-// The full project view produced by `interpretProject()`.
-// - `files`: one Database per source file (keyed by absolute filepath).
-//   Each contains only that file's own elements + its externals list.
-// - `items`: a flat merge of ALL files' elements (no externals, no dedup).
-//   Used by `exportSchemaJson` to look up canonical elements by name
-//   when resolving a file's imports.
+// Full project: files = per-file Database, items = flat merge for canonical lookup.
 export interface MasterDatabase {
   files: Record<string, Database>;
   items: Database;

packages/dbml-parse/src/core/types/symbol/symbols.ts

@@ -156,7 +156,7 @@ export class NodeSymbol implements Internable<InternedNodeSymbol> {
 export class AliasSymbol extends NodeSymbol {
   declare declaration: ElementDeclarationNode;
   declare name: string;
-  // The symbol this alias points at (may itself be an alias — use
+  // The symbol this alias points at (may itself be an alias - use
   // `originalSymbol` to reach the root).
   aliasedSymbol: NodeSymbol;
 
@@ -192,7 +192,7 @@ export class AliasSymbol extends NodeSymbol {
 
 // A symbol created by a `use`/`reuse` import specifier.
 // `usedSymbol` points at the imported symbol in the source file.
-// `canBeImported` is true only for `reuse` (re-exported) — plain `use`
+// `canBeImported` is true only for `reuse` (re-exported) - plain `use`
 // imports are non-transitive and invisible to further importers.
 export class UseSymbol extends NodeSymbol {
   // The `UseSpecifierNode` or `WildcardNode` that produced this symbol.
@@ -309,4 +309,3 @@ export class SchemaSymbol extends NodeSymbol {
     return this.qualifiedName.join('.') === DEFAULT_SCHEMA_NAME;
   }
 }
-