Switch import syntax to path-as-alias and align LSP alias display

Author: pchalamet

CHANGELOG.md

@@ -5,6 +5,9 @@ All notable changes to FScript are documented in this file.
 ## [Unreleased]
 
 - Fixed LSP completion insertion for dotted prefixes so selecting `Option.map` after `Option.` no longer duplicates the qualifier.
+- Switched import syntax to `import "path.fss" as Alias` and removed `from` import grammar.
+- Updated LSP type display/navigation to hide internal import prefixes and use source aliases (for example `Common.ProjectInfo`).
+- Renamed sample `includes-and-exports.fss` to `imports-and-exports.fss` and updated docs links.
 
 ## [0.34.0]
 

README.md

@@ -88,7 +88,7 @@ Useful samples:
 - [`samples/patterns-and-collections.fss`](samples/patterns-and-collections.fss)
 - [`samples/tree.fss`](samples/tree.fss)
 - [`samples/mutual-recursion.fss`](samples/mutual-recursion.fss)
-- [`samples/includes-and-exports.fss`](samples/includes-and-exports.fss)
+- [`samples/imports-and-exports.fss`](samples/imports-and-exports.fss)
 
 ## Interpreter Architecture
 

docs/guides/getting-started-tutorial.md

@@ -330,8 +330,8 @@ You can split scripts using `import`.
 `main.fss`:
 
 ```fsharp
-import "shared/math.fss"
-print $"{math.sum 20 22}"
+import "shared/math.fss" as Math
+print $"{Math.sum 20 22}"
 ```
 
 `shared/math.fss`:
@@ -343,7 +343,7 @@ let sum a b = a + b
 Notes:
 - imported files are `.fss`,
 - import cycles are fatal,
-- imported files are namespaced by filename stem (`math.sum`, `common.join`, ...).
+- imported symbols must be accessed through the explicit alias (`Math.sum`, `Common.join`, ...).
 
 ## 11. Hosting, exports, and sandboxing (advanced)
 FScript is designed to be embedded.
@@ -379,7 +379,7 @@ When embedding, keep this mindset:
   - [`samples/types-showcase.fss`](../../samples/types-showcase.fss)
   - [`samples/patterns-and-collections.fss`](../../samples/patterns-and-collections.fss)
   - [`samples/map-matching.fss`](../../samples/map-matching.fss)
-  - [`samples/includes-and-exports.fss`](../../samples/includes-and-exports.fss)
+  - [`samples/imports-and-exports.fss`](../../samples/imports-and-exports.fss)
 - Specifications index: [`docs/specs/README.md`](../specs/README.md)
 - Architecture index: [`docs/architecture/README.md`](../architecture/README.md)
 - [`samples/`](../../samples/)

docs/specs/syntax-and-indentation.md

@@ -6,7 +6,7 @@ This document describes the concrete syntax accepted by the interpreter and the
 ## File and program structure
 - A program is a sequence of top-level statements.
 - Top-level statements are:
-  - `import "relative/path/file.fss"` directives
+  - `import "relative/path/file.fss" as Alias` directives
   - `type` / `type rec` declarations
   - `let` / `let rec` bindings
   - `[<export>] let` / `[<export>] let rec` bindings
@@ -206,16 +206,16 @@ All of the following map literal layouts are valid:
 - Inline record annotation fields are `;`-separated in single-line form.
 
 ## Import directive
-- Import uses preprocessor-style syntax:
-  - `import "shared/helpers.fss"`
+- Import uses explicit alias syntax:
+  - `import "shared/helpers.fss" as Helpers`
 - Imports are top-level only.
-- Imported files are wrapped in an implicit module derived from the imported file name.
-  - `import "shared/helpers.fss"` exposes symbols under `helpers.*`.
+- Imported symbols are available only through the alias selected by the importer.
+  - `import "shared/helpers.fss" as Helpers` exposes symbols under `Helpers.*`.
 - Import loading is recursive.
 - Cycles are fatal and reported as parse errors.
 - File paths in imports must be `.fss`.
 - Import resolution is file-relative:
-  - `import "x.fss"` resolves from the directory of the file containing the directive.
+  - `import "x.fss" as X` resolves from the directory of the file containing the directive.
 - Paths are normalized before loading:
   - relative segments like `.` and `..` are collapsed.
 - Resolved files must stay inside the configured sandbox root (`RootDirectory`).

samples/imports-and-exports.fss

@@ -0,0 +1,14 @@
+import "includes/common.fss" as Common
+
+[<export>] let extension_name = "demo"
+
+[<export>] let summary (project: Common.ProjectInfo) =
+    let steps = [ "build"; "test"; "publish" ] |> List.map Common.describe_command
+    $"{Common.describe_project project}: {Common.join_with_comma steps}"
+
+let main =
+    let project = { Name = "Terrabuild"; Language = "F#" }
+    print (summary project)
+    print $"Extension: {extension_name}"
+
+main

samples/includes-and-exports.fss

@@ -266,6 +266,18 @@ module LspHandlers =
         else
             typeText
 
+    let private displayTypeName (doc: DocumentState) (name: string) =
+        if String.IsNullOrWhiteSpace(name) then name
+        else
+            let parts = name.Split('.') |> Array.toList
+            match parts with
+            | head :: tail when doc.ImportInternalToAlias.ContainsKey(head) ->
+                let alias = doc.ImportInternalToAlias[head]
+                match tail with
+                | [] -> alias
+                | _ -> alias + "." + (String.concat "." tail)
+            | _ -> name
+
     let private formatFunctionSignature (doc: DocumentState) (sym: TopLevelSymbol) =
         let paramNames = doc.FunctionParameters |> Map.tryFind sym.Name |> Option.defaultValue []
 
@@ -276,7 +288,7 @@ module LspHandlers =
                 let effectiveParts =
                     match sym.TypeTargetName with
                     | Some returnName when parts.Length > 0 ->
-                        (parts |> List.take (parts.Length - 1)) @ [ returnName ]
+                        (parts |> List.take (parts.Length - 1)) @ [ displayTypeName doc returnName ]
                     | _ -> parts
                 let arrowText =
                     if effectiveParts.Length = (paramNames.Length + 1) then
@@ -298,6 +310,7 @@ module LspHandlers =
                     doc.FunctionDeclaredReturnTargets
                     |> Map.tryFind sym.Name
                     |> Option.defaultValue "unknown"
+                    |> displayTypeName doc
                 let parts = annotated @ [ returnType ]
                 let arrowText =
                     if parts.Length = (paramNames.Length + 1) then

src/FScript.CSharpInterop/LanguageServer/LspHandlers.fs

@@ -74,6 +74,8 @@ module LspModel =
           InjectedFunctionSignatures: Map<string, string>
           InjectedFunctionParameterNames: Map<string, string list>
           InjectedFunctionDefinitions: Map<string, (string * Span)>
+          ImportAliasToInternal: Map<string, string>
+          ImportInternalToAlias: Map<string, string>
           // Variable occurrences keyed by identifier, sourced from AST spans.
           // This avoids text-based false positives (for example record field labels).
           VariableOccurrences: Map<string, Span list> }

src/FScript.CSharpInterop/LanguageServer/LspModel.fs

@@ -3,6 +3,7 @@ namespace FScript.LanguageServer
 open System
 open System.Collections.Generic
 open System.IO
+open System.Text.RegularExpressions
 open System.Text.Json.Nodes
 open FScript.Language
 open FScript.CSharpInterop
@@ -146,6 +147,71 @@ module LspSymbols =
             |> String.concat "; "
             |> sprintf "{| %s |}"
 
+    let private tryBuildImportAliasMaps (sourcePath: string) (text: string) : Map<string, string> * Map<string, string> =
+        try
+            let parsed = Parser.parseProgramWithSourceName (Some sourcePath) text
+            let imports =
+                parsed
+                |> List.takeWhile (function | SImport _ -> true | _ -> false)
+                |> List.choose (function | SImport(alias, importPath, _) -> Some (alias, importPath) | _ -> None)
+
+            let sourceDirectory =
+                try
+                    match Path.GetDirectoryName(sourcePath) with
+                    | null
+                    | "" -> Directory.GetCurrentDirectory()
+                    | dir -> dir
+                with _ ->
+                    Directory.GetCurrentDirectory()
+
+            let pathToPrefix = Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+            let mutable prefixCounter = 0
+            let mutable aliasToInternal = Map.empty<string, string>
+            let mutable internalToAlias = Map.empty<string, string>
+
+            for (alias, importPath) in imports do
+                let resolvedPath =
+                    if Path.IsPathRooted(importPath) then
+                        Path.GetFullPath(importPath)
+                    else
+                        Path.GetFullPath(Path.Combine(sourceDirectory, importPath))
+
+                let internalPrefix =
+                    match pathToPrefix.TryGetValue(resolvedPath) with
+                    | true, existing -> existing
+                    | false, _ ->
+                        prefixCounter <- prefixCounter + 1
+                        let created = $"__imp{prefixCounter}"
+                        pathToPrefix[resolvedPath] <- created
+                        created
+
+                aliasToInternal <- aliasToInternal |> Map.add alias internalPrefix
+                if not (internalToAlias.ContainsKey(internalPrefix)) then
+                    internalToAlias <- internalToAlias |> Map.add internalPrefix alias
+
+            aliasToInternal, internalToAlias
+        with _ ->
+            Map.empty, Map.empty
+
+    let private mapInternalQualifiedName (internalToAlias: Map<string, string>) (name: string) =
+        if String.IsNullOrWhiteSpace(name) then name
+        else
+            match name.Split('.') |> Array.toList with
+            | head :: tail when internalToAlias.ContainsKey(head) ->
+                let alias = internalToAlias[head]
+                match tail with
+                | [] -> alias
+                | _ -> alias + "." + (String.concat "." tail)
+            | _ -> name
+
+    let private mapTypeTextForDisplay (internalToAlias: Map<string, string>) (typeText: string) =
+        if Map.isEmpty internalToAlias then typeText
+        else
+            internalToAlias
+            |> Map.fold (fun current internalPrefix alias ->
+                let pattern = @"\b" + Regex.Escape(internalPrefix) + @"\b"
+                Regex.Replace(current, pattern, alias)) typeText
+
     let private canonicalRecordSignatureFromFields (fields: (string * string) list) =
         fields
         |> List.sortBy fst
@@ -1395,6 +1461,11 @@ module LspSymbols =
                 Uri(uri).LocalPath
             else
                 uri
+        let importAliasToInternal, importInternalToAlias =
+            if uri.StartsWith("file://", StringComparison.OrdinalIgnoreCase) then
+                tryBuildImportAliasMaps sourceName text
+            else
+                Map.empty, Map.empty
         let runtimeExterns = LspRuntimeExterns.forSourcePath sourceName
 
         let diagnostics = ResizeArray<JsonNode>()
@@ -1511,6 +1582,39 @@ module LspSymbols =
         | ParseException err ->
             diagnostics.Add(diagnostic 1 "parse" err.Span err.Message)
 
+        let displayTypeText (typeText: string) = mapTypeTextForDisplay importInternalToAlias typeText
+
+        let symbols =
+            symbols
+            |> List.map (fun sym ->
+                { sym with
+                    TypeText = sym.TypeText |> Option.map displayTypeText })
+
+        let recordParamFields =
+            recordParamFields
+            |> Map.map (fun _ fields ->
+                fields |> List.map (fun (fieldName, fieldType) -> fieldName, displayTypeText fieldType))
+
+        let functionAnnotationTypes =
+            functionAnnotationTypes
+            |> Map.map (fun _ typeTexts -> typeTexts |> List.map displayTypeText)
+
+        let parameterTypeHints =
+            parameterTypeHints
+            |> List.map (fun (span, label) -> span, displayTypeText label)
+
+        let functionReturnTypeHints =
+            functionReturnTypeHints
+            |> List.map (fun (span, label) -> span, displayTypeText label)
+
+        let patternTypeHints =
+            patternTypeHints
+            |> List.map (fun (span, label) -> span, displayTypeText label)
+
+        let localVariableTypeHints =
+            localVariableTypeHints
+            |> List.map (fun (span, name, typeText) -> span, name, displayTypeText typeText)
+
         documents[uri] <-
             { SourcePath = sourceName
               Text = text
@@ -1529,6 +1633,8 @@ module LspSymbols =
               InjectedFunctionSignatures = injectedFunctionSignatures
               InjectedFunctionParameterNames = injectedFunctionParameterNames
               InjectedFunctionDefinitions = injectedFunctionDefinitions
+              ImportAliasToInternal = importAliasToInternal
+              ImportInternalToAlias = importInternalToAlias
               VariableOccurrences = occurrences }
         publishDiagnostics uri (diagnostics |> Seq.toList)
 
@@ -1853,7 +1959,12 @@ module LspSymbols =
                 let idx = word.LastIndexOf('.')
                 if idx > 0 then
                     let qualifier = word.Substring(0, idx)
-                    tryResolveTypeNameForQualifier doc qualifier
+                    let memberName = word.Substring(idx + 1)
+                    match doc.ImportAliasToInternal |> Map.tryFind qualifier with
+                    | Some internalPrefix when not (String.IsNullOrWhiteSpace(memberName)) ->
+                        Some $"{internalPrefix}.{memberName}"
+                    | _ ->
+                        tryResolveTypeNameForQualifier doc qualifier
                 else
                     None
             | Some word ->

src/FScript.CSharpInterop/LanguageServer/LspSymbols.fs

@@ -82,7 +82,7 @@ and MapEntry =
 
 and Stmt =
     | SType of TypeDef
-    | SImport of string * Span
+    | SImport of string * string * Span
     | SLet of string * Param list * Expr * bool * bool * Span
     | SLetRecGroup of (string * Param list * Expr * Span) list * bool * Span
     | SExpr of Expr