feat(language)!: switch to import directive and remove unused LSP warning

Author: pchalamet

CHANGELOG.md

@@ -4,7 +4,10 @@ All notable changes to FScript are documented in this file.
 
 ## [Unreleased]
 
-- _No entries yet._
+- Replaced `#include` with `import` and removed script-level `module` declarations.
+- Imported files are now exposed through filename-derived modules (for example `shared.fss` -> `shared.*`).
+- Updated parser/runtime/LSP/docs/tests for the new import/module semantics.
+- Removed `unused` top-level binding diagnostics from LSP.
 
 ## [0.31.0]
 

docs/guides/fsharp-ocaml-differences.md

@@ -6,7 +6,7 @@ This document is a quick comparison guide. It highlights intentional differences
 ## Scope of the language
 - FScript is a small interpreted subset, not a full compiler language.
 - FScript supports a focused core: `let`, `let rec` (functions), `if/elif/else`, `for`, `match`, lists, tuples, options, records, discriminated unions, pipelines, and extern calls.
-- Many F#/OCaml features are intentionally absent today (classes, interfaces, computation expressions, etc.). `module` declarations are supported only in included files.
+- Many F#/OCaml features are intentionally absent today (classes, interfaces, computation expressions, etc.). Script composition uses `import`, and imported files are exposed through filename-derived modules.
 
 ## Syntax differences
 

docs/guides/getting-started-tutorial.md

@@ -7,7 +7,7 @@ You will learn:
 - how to run a script,
 - how to model data with records/lists/maps/options/unions,
 - how to use pattern matching,
-- how to split scripts with `#include`,
+- how to split scripts with `import`,
 - how to expose host-callable functions with `[<export>]`.
 
 ## Get FScript
@@ -33,7 +33,7 @@ make build
 Then run scripts with:
 
 ```bash
-dotnet run --project src/FScript -- your-script.fss
+./src/FScript/bin/Debug/net10.0/fscript your-script.fss
 ```
 
 ## 1. Run your first script
@@ -324,28 +324,26 @@ let hasA = m |> Map.containsKey "a"
 Full reference:
 - [`docs/specs/stdlib-functions.md`](../specs/stdlib-functions.md)
 
-## 10. Includes and modules
-You can split scripts using `#include`.
+## 10. Imports and file modules
+You can split scripts using `import`.
 
 `main.fss`:
 
 ```fsharp
-#include "shared/math.fss"
-print $"{sum 20 22}"
+import "shared/math.fss"
+print $"{math.sum 20 22}"
 ```
 
 `shared/math.fss`:
 
 ```fsharp
-module Math
-
 let sum a b = a + b
 ```
 
 Notes:
-- included files are `.fss`,
-- include cycles are fatal,
-- modules are supported in included files.
+- imported files are `.fss`,
+- import cycles are fatal,
+- imported files are namespaced by filename stem (`math.sum`, `common.join`, ...).
 
 ## 11. Hosting, exports, and sandboxing (advanced)
 FScript is designed to be embedded.

docs/specs/README.md

@@ -24,4 +24,4 @@ Normative behavior for the language, runtime surface, hosting model, and editor/
 - LSP inlay hints: [`lsp-inlay-hints.md`](./lsp-inlay-hints.md)
 - LSP uses runtime extern schemes for typing/signatures and resolves navigation to included-file declarations.
 - LSP injected stdlib functions show named-argument signatures when available and resolve definition to readonly virtual stdlib sources (`fscript-stdlib:///...`).
-- Definition/type-definition from record field labels in function return record literals resolves to the declared return type (including include-provided types).
+- Definition/type-definition from record field labels in function return record literals resolves to the declared return type (including import-provided types).

docs/specs/embedding-fscript-language.md

@@ -188,8 +188,8 @@ Each error contains:
 
 ## Embedding cookbook
 
-### 1. Parse/eval a file with `#include`
-Use include-aware parsing when executing scripts from disk.
+### 1. Parse/eval a file with `import`
+Use import-aware parsing when executing scripts from disk.
 
 ```fsharp
 open FScript.Language

docs/specs/sandbox-and-security.md

@@ -13,9 +13,9 @@ This document defines the security model for running FScript programs with host
   - `RootDirectory : string`
 - The CLI defaults `RootDirectory` to the script file directory.
 - The CLI allows overriding root with `--root <path>` (or `-r <path>`).
-- `#include` file resolution is constrained to `RootDirectory`.
-- Include paths are resolved relative to the current script file.
-- Include cycles are rejected.
+- `import` file resolution is constrained to `RootDirectory`.
+- Import paths are resolved relative to the current script file.
+- Import cycles are rejected.
 
 Filesystem extern behavior:
 - `Fs.readText` and `Fs.enumerateFiles` resolve candidate paths through `HostCommon.tryResolvePath`.

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:
-  - `#include "relative/path/file.fss"` directives
+  - `import "relative/path/file.fss"` directives
   - `type` / `type rec` declarations
   - `let` / `let rec` bindings
   - `[<export>] let` / `[<export>] let rec` bindings
@@ -207,21 +207,22 @@ All of the following map literal layouts are valid:
   - declared-type-by-shape: `let say_hello (person: { Name: string }) = ...`
 - Inline record annotation fields are `;`-separated in single-line form.
 
-## Include directive
-- Include uses preprocessor-style syntax:
-  - `#include "shared/helpers.fss"`
-- Includes are top-level only.
-- Included files are merged into the same global namespace as the current script.
-- Include loading is recursive.
+## Import directive
+- Import uses preprocessor-style syntax:
+  - `import "shared/helpers.fss"`
+- 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.*`.
+- Import loading is recursive.
 - Cycles are fatal and reported as parse errors.
-- File paths in includes must be `.fss`.
-- Include resolution is file-relative:
-  - `#include "x.fss"` resolves from the directory of the file containing the directive.
+- 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.
 - Paths are normalized before loading:
   - relative segments like `.` and `..` are collapsed.
 - Resolved files must stay inside the configured sandbox root (`RootDirectory`).
   - escaping the root is a parse error.
-- A file already loaded once in the include graph is skipped on subsequent includes.
-  - includes are effectively deduplicated.
-- `#include` must appear before module declarations and executable/type code in a file.
-- Parse/type/eval errors include file-aware spans (`file`, `line`, `column`) so failures in included files point to the offending source.
+- A file already loaded once in the import graph is skipped on subsequent imports.
+  - imports are effectively deduplicated.
+- `import` must appear before executable/type code in a file.
+- Parse/type/eval errors include file-aware spans (`file`, `line`, `column`) so failures in imported files point to the offending source.

samples/includes-and-exports.fss

@@ -1,10 +1,10 @@
-#include "includes/common.fss"
+import "includes/common.fss"
 
 [<export>] let extension_name = "demo"
 
-[<export>] let summary (project: ProjectInfo) =
-    let steps = [ "build"; "test"; "publish" ] |> List.map describe_command
-    $"{describe_project project}: {join_with_comma steps}"
+[<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#" }

src/FScript.Language/Ast.fs

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

src/FScript.Language/IncludeResolver.fs

@@ -13,28 +13,28 @@ module IncludeResolver =
 
     let private ensureFssPath (path: string) (span: Span) =
         if not (path.EndsWith(".fss", StringComparison.OrdinalIgnoreCase)) then
-            raise (ParseException { Message = "Only '.fss' files can be used with '#include'"; Span = span })
+            raise (ParseException { Message = "Only '.fss' files can be used with 'import'"; Span = span })
 
     let private ensureWithinRoot (rootDirectoryWithSeparator: string) (path: string) (span: Span) =
         let fullPath = Path.GetFullPath(path)
         let fullRoot = rootDirectoryWithSeparator.TrimEnd(Path.DirectorySeparatorChar)
         let isRootItself = String.Equals(fullPath, fullRoot, StringComparison.OrdinalIgnoreCase)
         let isUnderRoot = fullPath.StartsWith(rootDirectoryWithSeparator, StringComparison.OrdinalIgnoreCase)
         if not (isRootItself || isUnderRoot) then
-            raise (ParseException { Message = $"Included file '{fullPath}' is outside of sandbox root"; Span = span })
+            raise (ParseException { Message = $"Imported file '{fullPath}' is outside of sandbox root"; Span = span })
         fullPath
 
-    let private resolveIncludePath (currentFile: string) (includePath: string) (rootDirectoryWithSeparator: string) (span: Span) =
-        if String.IsNullOrWhiteSpace(includePath) then
-            raise (ParseException { Message = "Include path cannot be empty"; Span = span })
+    let private resolveImportPath (currentFile: string) (importPath: string) (rootDirectoryWithSeparator: string) (span: Span) =
+        if String.IsNullOrWhiteSpace(importPath) then
+            raise (ParseException { Message = "Import path cannot be empty"; Span = span })
 
-        ensureFssPath includePath span
+        ensureFssPath importPath span
 
         let currentDirectory = Path.GetDirectoryName(currentFile)
         let candidate =
-            if Path.IsPathRooted(includePath) then includePath
-            elif String.IsNullOrEmpty(currentDirectory) then includePath
-            else Path.Combine(currentDirectory, includePath)
+            if Path.IsPathRooted(importPath) then importPath
+            elif String.IsNullOrEmpty(currentDirectory) then importPath
+            else Path.Combine(currentDirectory, importPath)
 
         ensureWithinRoot rootDirectoryWithSeparator candidate span
 
@@ -66,6 +66,23 @@ module IncludeResolver =
 
     let private qualifyName (moduleName: string) (name: string) = $"{moduleName}.{name}"
 
+    let private isValidModuleName (name: string) =
+        let startsValid c = Char.IsLetter(c) || c = '_'
+        let partValid c = Char.IsLetterOrDigit(c) || c = '_'
+        not (String.IsNullOrWhiteSpace(name))
+        && startsValid name[0]
+        && (name |> Seq.forall partValid)
+
+    let private deriveModuleNameFromFilePath (filePath: string) (span: Span) =
+        let stem = Path.GetFileNameWithoutExtension(filePath)
+        if isValidModuleName stem then
+            stem
+        else
+            raise (ParseException {
+                Message = $"Imported filename stem '{stem}' is not a valid module name. Rename the file to a valid identifier."
+                Span = span
+            })
+
     let private rewriteModuleScopedStatements (moduleName: string) (statements: Stmt list) : Stmt list =
         let topLevelNames =
             statements
@@ -185,70 +202,73 @@ module IncludeResolver =
     let private expandProgram
         (rootDirectoryWithSeparator: string)
         (fileSpan: string -> Span)
+        (moduleToFile: System.Collections.Generic.Dictionary<string, string>)
         (loadFileRef: (string list -> bool -> string -> Program) ref)
         (stack: string list)
         (isMainFile: bool)
         (currentFile: string)
         (program: Program)
         : Program =
         let mutable seenCode = false
-        let mutable moduleDecl: (string * Span) option = None
-        let includes = ResizeArray<string * Span>()
+        let imports = ResizeArray<string * Span>()
         let localCode = ResizeArray<Stmt>()
 
         for stmt in program do
             match stmt with
-            | SInclude(includePath, span) ->
-                if seenCode || moduleDecl.IsSome then
-                    raise (ParseException { Message = "'#include' directives must appear before module declaration and code"; Span = span })
-                includes.Add(includePath, span)
-            | SModuleDecl(moduleName, span) ->
-                if isMainFile then
-                    raise (ParseException { Message = "'module' is not allowed in the main script"; Span = span })
+            | SImport(importPath, span) ->
                 if seenCode then
-                    raise (ParseException { Message = "'module' declaration must appear before code"; Span = span })
-                match moduleDecl with
-                | Some (_, previousSpan) ->
-                    raise (ParseException { Message = "Only one 'module' declaration is allowed per file"; Span = previousSpan })
-                | None ->
-                    moduleDecl <- Some(moduleName, span)
+                    raise (ParseException { Message = "'import' directives must appear before code"; Span = span })
+                imports.Add(importPath, span)
             | _ ->
                 seenCode <- true
                 localCode.Add(stmt)
 
-        let includedStatements =
-            includes
+        let importedStatements =
+            imports
             |> Seq.toList
-            |> List.collect (fun (includePath, span) ->
-                let resolvedPath = resolveIncludePath currentFile includePath rootDirectoryWithSeparator span
+            |> List.collect (fun (importPath, span) ->
+                let resolvedPath = resolveImportPath currentFile importPath rootDirectoryWithSeparator span
                 (!loadFileRef) stack false resolvedPath)
 
         let localStatements = localCode |> Seq.toList
         let rewrittenLocalStatements =
-            match moduleDecl with
-            | Some (moduleName, _) -> rewriteModuleScopedStatements moduleName localStatements
-            | None -> localStatements
+            if isMainFile then
+                localStatements
+            else
+                let span = fileSpan currentFile
+                let moduleName = deriveModuleNameFromFilePath currentFile span
+                match moduleToFile.TryGetValue(moduleName) with
+                | true, existingPath when not (String.Equals(existingPath, currentFile, StringComparison.OrdinalIgnoreCase)) ->
+                    raise (ParseException {
+                        Message = $"Module name collision: '{moduleName}' is derived from both '{existingPath}' and '{currentFile}'"
+                        Span = span
+                    })
+                | _ ->
+                    moduleToFile[moduleName] <- currentFile
+                    rewriteModuleScopedStatements moduleName localStatements
 
-        includedStatements @ rewrittenLocalStatements
+        importedStatements @ rewrittenLocalStatements
 
     let parseIncludedSource (sourceName: string) (source: string) : Program =
         let program = Parser.parseProgramWithSourceName (Some sourceName) source
         let dummyRoot = normalizeDirectoryPath "."
         let fileSpan path =
             let p = Span.posInFile path 1 1
             Span.mk p p
+        let moduleToFile = System.Collections.Generic.Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
         let loadRef = ref (fun (_: string list) (_: bool) (_: string) -> ([]: Program))
-        if program |> List.exists (function | SInclude _ -> true | _ -> false) then
-            let includeSpan =
+        if program |> List.exists (function | SImport _ -> true | _ -> false) then
+            let importSpan =
                 program
-                |> List.choose (function | SInclude(_, span) -> Some span | _ -> None)
+                |> List.choose (function | SImport(_, span) -> Some span | _ -> None)
                 |> List.head
-            raise (ParseException { Message = "Embedded stdlib source does not support '#include'"; Span = includeSpan })
-        expandProgram dummyRoot fileSpan loadRef [] false sourceName program
+            raise (ParseException { Message = "Embedded stdlib source does not support 'import'"; Span = importSpan })
+        expandProgram dummyRoot fileSpan moduleToFile loadRef [] false sourceName program
 
     let parseProgramFromFile (rootDirectory: string) (entryFile: string) : Program =
         let rootDirectoryWithSeparator = normalizeDirectoryPath rootDirectory
         let visited = System.Collections.Generic.HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        let moduleToFile = System.Collections.Generic.Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
         let fileSpan path =
             let p = Span.posInFile path 1 1
             Span.mk p p
@@ -261,7 +281,7 @@ module IncludeResolver =
 
             if stack |> List.exists (fun p -> String.Equals(p, sandboxedPath, StringComparison.OrdinalIgnoreCase)) then
                 let cycleChain = (sandboxedPath :: stack |> List.rev) @ [ sandboxedPath ]
-                let message = sprintf "Include cycle detected: %s" (String.concat " -> " cycleChain)
+                let message = sprintf "Import cycle detected: %s" (String.concat " -> " cycleChain)
                 raise (ParseException { Message = message; Span = fileSpan sandboxedPath })
 
             if visited.Contains(sandboxedPath) then
@@ -271,13 +291,14 @@ module IncludeResolver =
                 let source = File.ReadAllText(sandboxedPath)
                 let program = Parser.parseProgramWithSourceName (Some sandboxedPath) source
                 let loadRef = ref loadFile
-                expandProgram rootDirectoryWithSeparator fileSpan loadRef (sandboxedPath :: stack) isMainFile sandboxedPath program
+                expandProgram rootDirectoryWithSeparator fileSpan moduleToFile loadRef (sandboxedPath :: stack) isMainFile sandboxedPath program
 
         loadFile [] true entryFile
 
     let parseProgramFromSourceWithIncludes (rootDirectory: string) (entryFile: string) (entrySource: string) : Program =
         let rootDirectoryWithSeparator = normalizeDirectoryPath rootDirectory
         let visited = System.Collections.Generic.HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        let moduleToFile = System.Collections.Generic.Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
         let fileSpan path =
             let p = Span.posInFile path 1 1
             Span.mk p p
@@ -295,7 +316,7 @@ module IncludeResolver =
 
             if stack |> List.exists (fun p -> String.Equals(p, sandboxedPath, StringComparison.OrdinalIgnoreCase)) then
                 let cycleChain = (sandboxedPath :: stack |> List.rev) @ [ sandboxedPath ]
-                let message = sprintf "Include cycle detected: %s" (String.concat " -> " cycleChain)
+                let message = sprintf "Import cycle detected: %s" (String.concat " -> " cycleChain)
                 raise (ParseException { Message = message; Span = fileSpan sandboxedPath })
 
             if visited.Contains(sandboxedPath) then
@@ -309,6 +330,6 @@ module IncludeResolver =
                         File.ReadAllText(sandboxedPath)
                 let program = Parser.parseProgramWithSourceName (Some sandboxedPath) source
                 let loadRef = ref loadFile
-                expandProgram rootDirectoryWithSeparator fileSpan loadRef (sandboxedPath :: stack) isMainFile sandboxedPath program
+                expandProgram rootDirectoryWithSeparator fileSpan moduleToFile loadRef (sandboxedPath :: stack) isMainFile sandboxedPath program
 
         loadFile [] true entrySandboxedPath