fastscript 1.0.0 → 2.0.0

package/src/fs-diagnostics.mjs

@@ -0,0 +1,70 @@
+import { formatDiagnostic, parseFastScript } from "./fs-parser.mjs";
+
+function displayPath(file) {
+  return file || "<memory>";
+}
+
+function safeLine(lines, line) {
+  const index = Math.max(0, Math.min(lines.length - 1, line - 1));
+  return lines[index] ?? "";
+}
+
+function renderPrimarySnippet(diagnostic, source) {
+  if (!source || !diagnostic) return "";
+  const lines = String(source).split(/\r?\n/);
+  const lineText = safeLine(lines, diagnostic.line);
+  const markerStart = Math.max(1, diagnostic.column || 1);
+  const markerEnd = Math.max(markerStart, diagnostic.endColumn || markerStart);
+  const width = Math.max(1, markerEnd - markerStart);
+  const pointer = `${" ".repeat(markerStart - 1)}${"^".repeat(width)}`;
+  return `${String(diagnostic.line).padStart(4, " ")} | ${lineText}\n     | ${pointer}`;
+}
+
+export function formatDiagnosticsReport(diagnostics, { source = "" } = {}) {
+  if (!diagnostics?.length) return "";
+  const ordered = [...diagnostics].sort((a, b) => {
+    const startA = a.span?.start ?? 0;
+    const startB = b.span?.start ?? 0;
+    if (startA !== startB) return startA - startB;
+    return a.code.localeCompare(b.code);
+  });
+
+  return ordered
+    .map((diagnostic) => {
+      const details = [formatDiagnostic(diagnostic)];
+      const snippet = renderPrimarySnippet(diagnostic, source);
+      if (snippet) details.push(snippet);
+      for (const related of diagnostic.related || []) {
+        details.push(
+          `  related ${displayPath(related.file)}:${related.line}:${related.column} ${related.message}`,
+        );
+      }
+      for (const fix of diagnostic.fixes || []) {
+        const text = String(fix.text ?? "").replace(/\n/g, "\\n");
+        details.push(`  fix ${fix.message || "Apply fix"} -> ${text}`);
+      }
+      return details.join("\n");
+    })
+    .join("\n\n");
+}
+
+export function analyzeFastScript(source, { file = "", mode = "lenient" } = {}) {
+  const ast = parseFastScript(source, { file, mode, recover: true });
+  return ast.diagnostics;
+}
+
+export function assertFastScript(source, { file = "", mode = "strict" } = {}) {
+  const diagnostics = analyzeFastScript(source, { file, mode: "lenient" });
+  if (!diagnostics.length) return;
+  const blocking = diagnostics.filter((diagnostic) => diagnostic.severity !== "warning");
+  if (!blocking.length && mode !== "strict") return;
+
+  const primary = (blocking.length ? blocking : diagnostics)[0];
+  const report = formatDiagnosticsReport(diagnostics, { source });
+  const path = displayPath(primary.file);
+  const error = new Error(`${path}:${primary.line}:${primary.column} ${primary.code} ${primary.message}\n${report}`);
+  error.status = 1;
+  error.details = diagnostics;
+  error.report = report;
+  throw error;
+}

package/src/fs-error-codes.mjs

@@ -0,0 +1,126 @@
+export const FS_ERROR_CODES = Object.freeze({
+  FS1001: {
+    severity: "error",
+    message: "Invalid reactive declaration.",
+    hint: "Reactive declarations must be `~name = expression`.",
+  },
+  FS1002: {
+    severity: "error",
+    message: "Invalid state declaration.",
+    hint: "State declarations must be `state name = expression`.",
+  },
+  FS1003: {
+    severity: "error",
+    message: "Invalid function declaration.",
+    hint: "Function declarations must use `fn name(...) { ... }` or `export fn ...`.",
+  },
+  FS1004: {
+    severity: "error",
+    message: "Type declarations are not valid runtime FastScript syntax.",
+    hint: "Move `type`, `interface`, and `enum` definitions to `.d.ts` files or remove them from `.fs` files.",
+  },
+  FS1005: {
+    severity: "error",
+    message: "FastScript parse error.",
+    hint: "Check punctuation and statement structure near the reported location.",
+  },
+  FS1006: {
+    severity: "error",
+    message: "Invalid identifier.",
+    hint: "Identifiers must start with a letter, `_`, or `$`.",
+  },
+  FS1007: {
+    severity: "warning",
+    message: "Suspicious `TODO_ERROR` token found.",
+    hint: "Remove placeholder tokens before shipping.",
+  },
+  FS1010: {
+    severity: "error",
+    message: "Unterminated token.",
+    hint: "Close the string, template, regex, or comment that starts near this location.",
+  },
+  FS1101: {
+    severity: "warning",
+    message: "Unsupported language directive.",
+    hint: "Use directives listed in the FastScript language specification.",
+  },
+  FS2001: {
+    severity: "warning",
+    message: "Prefer `const` when a binding is never reassigned.",
+    hint: "Use lint autofix to rewrite `let` to `const` when safe.",
+  },
+  FS2002: {
+    severity: "warning",
+    message: "Avoid inline `<script>` tags in templates.",
+    hint: "Move script behavior into module functions or hydration handlers.",
+  },
+  FS3001: {
+    severity: "error",
+    message: "`TODO_ERROR` token is not allowed in committed code.",
+    hint: "Delete placeholder tokens before merging.",
+  },
+  FS3002: {
+    severity: "warning",
+    message: "`var` is discouraged in FastScript modules.",
+    hint: "Replace `var` with `let` or `const`.",
+  },
+  FS3003: {
+    severity: "warning",
+    message: "Inline `<script>` tag detected in template literal.",
+    hint: "Use external module code instead of embedding scripts in markup strings.",
+  },
+  FS3004: {
+    severity: "warning",
+    message: "Binding can be `const`.",
+    hint: "Apply the autofix to preserve intent and reduce accidental reassignment.",
+  },
+  FS4001: {
+    severity: "error",
+    message: "Duplicate route mapping detected.",
+    hint: "Ensure each route path+slot pair is unique.",
+  },
+  FS4002: {
+    severity: "warning",
+    message: "Route param is declared but not referenced.",
+    hint: "Use `params.<name>` or remove the dynamic segment.",
+  },
+  FS4101: {
+    severity: "error",
+    message: "Unknown symbol.",
+    hint: "Declare the symbol before use or import it from another module.",
+  },
+  FS4102: {
+    severity: "error",
+    message: "Cannot reassign `const` binding.",
+    hint: "Change the declaration to `let` or remove the assignment.",
+  },
+  FS4103: {
+    severity: "error",
+    message: "Type mismatch in assignment.",
+    hint: "Align assigned expression type with the declared/inferred variable type.",
+  },
+  FS4104: {
+    severity: "error",
+    message: "Incorrect function argument count.",
+    hint: "Pass the required number of arguments or update the function signature.",
+  },
+  FS4105: {
+    severity: "error",
+    message: "Incompatible return type.",
+    hint: "Ensure all return paths in the function resolve to compatible types.",
+  },
+  FS4106: {
+    severity: "error",
+    message: "Attempted to call a non-function value.",
+    hint: "Ensure the callee resolves to a function.",
+  },
+  FS4107: {
+    severity: "error",
+    message: "Invalid operand types for operator.",
+    hint: "Use operands compatible with the operator semantics.",
+  },
+});
+
+export function resolveErrorMeta(code) {
+  return FS_ERROR_CODES[code] || { severity: "error", message: "FastScript compiler error." };
+}

package/src/fs-formatter.mjs

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { generate } from "astring";
+import { parseFastScript } from "./fs-parser.mjs";
+
+function walk(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) out.push(...walk(full));
+    else if (st.isFile()) out.push(full);
+  }
+  return out;
+}
+
+function shouldThrowForFormat(diagnostics) {
+  return diagnostics.some((diagnostic) => diagnostic.severity !== "warning");
+}
+
+export function formatFastScriptSource(source, { file = "" } = {}) {
+  const parsed = parseFastScript(source, { file, mode: "lenient", recover: true });
+  if (!parsed.estree || shouldThrowForFormat(parsed.diagnostics)) {
+    return String(source ?? "");
+  }
+
+  const formatted = generate(parsed.estree, {
+    comments: false,
+    indent: "  ",
+    lineEnd: "\n",
+  });
+
+  return formatted.endsWith("\n") ? formatted : `${formatted}\n`;
+}
+
+export async function runFormat(args = []) {
+  let target = "app";
+  let write = true;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--path") target = args[i + 1] || target;
+    if (args[i] === "--check") write = false;
+    if (args[i] === "--write") write = true;
+  }
+
+  const base = resolve(target);
+  const files = walk(base).filter((file) => extname(file) === ".fs");
+  let changed = 0;
+
+  for (const file of files) {
+    const current = readFileSync(file, "utf8");
+    const next = formatFastScriptSource(current, { file });
+    if (current !== next) {
+      changed += 1;
+      if (write) writeFileSync(file, next, "utf8");
+    }
+  }
+
+  if (!write && changed > 0) {
+    const error = new Error(`format check failed: ${changed} file(s) need formatting`);
+    error.status = 1;
+    throw error;
+  }
+
+  console.log(`format ${write ? "write" : "check"} complete: ${files.length} file(s), ${changed} changed`);
+}

package/src/fs-linter.mjs

@@ -0,0 +1,274 @@
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { parseFastScript } from "./fs-parser.mjs";
+
+function walk(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) out.push(...walk(full));
+    else if (st.isFile()) out.push(full);
+  }
+  return out;
+}
+
+function spanFromNode(node, sourceLength) {
+  const start = Math.max(0, Math.min(sourceLength, Number(node?.fsRange?.[0] ?? node?.start ?? 0)));
+  const end = Math.max(start, Math.min(sourceLength, Number(node?.fsRange?.[1] ?? node?.end ?? start)));
+  return { start, end };
+}
+
+function createIssue({ file, source, lineStarts, code, severity, message, span, fix = null }) {
+  const start = Math.max(0, Math.min(source.length, span?.start ?? 0));
+  const end = Math.max(start, Math.min(source.length, span?.end ?? start + 1));
+  const loc = lineFromOffset(lineStarts, start);
+  return {
+    file,
+    line: loc.line,
+    column: loc.column,
+    span: { start, end },
+    code,
+    severity,
+    message,
+    fix,
+  };
+}
+
+function createLineStarts(source) {
+  const out = [0];
+  for (let i = 0; i < source.length; i += 1) {
+    if (source[i] === "\n") out.push(i + 1);
+  }
+  return out;
+}
+
+function lineFromOffset(lineStarts, offset) {
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const start = lineStarts[mid];
+    const next = lineStarts[mid + 1] ?? Number.POSITIVE_INFINITY;
+    if (offset < start) hi = mid - 1;
+    else if (offset >= next) lo = mid + 1;
+    else return { line: mid + 1, column: offset - start + 1 };
+  }
+  return { line: 1, column: 1 };
+}
+
+function traverse(node, visitor, parent = null) {
+  if (!node || typeof node !== "object") return;
+  visitor(node, parent);
+  for (const value of Object.values(node)) {
+    if (!value) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item && typeof item === "object") traverse(item, visitor, node);
+      }
+    } else if (typeof value === "object" && typeof value.type === "string") {
+      traverse(value, visitor, node);
+    }
+  }
+}
+
+function collectReassignedNames(estree) {
+  const names = new Set();
+  traverse(estree, (node) => {
+    if (node.type === "AssignmentExpression" && node.left?.type === "Identifier") {
+      names.add(node.left.name);
+    }
+    if (node.type === "UpdateExpression" && node.argument?.type === "Identifier") {
+      names.add(node.argument.name);
+    }
+  });
+  return names;
+}
+
+function declarationKeywordFixSpan(source, declaration, keyword) {
+  const span = spanFromNode(declaration, source.length);
+  const window = source.slice(span.start, Math.min(span.end, span.start + 64));
+  const pattern = new RegExp(`\\b${keyword}\\b`);
+  const match = pattern.exec(window);
+  if (!match) return null;
+  return {
+    start: span.start + match.index,
+    end: span.start + match.index + keyword.length,
+  };
+}
+
+function applyFixes(source, fixes) {
+  if (!fixes.length) return source;
+  const sorted = [...fixes]
+    .filter((fix) => fix && Number.isFinite(fix.start) && Number.isFinite(fix.end) && fix.start <= fix.end)
+    .sort((a, b) => {
+      if (a.start !== b.start) return a.start - b.start;
+      return a.end - b.end;
+    });
+
+  const nonOverlapping = [];
+  let cursor = -1;
+  for (const fix of sorted) {
+    if (fix.start < cursor) continue;
+    nonOverlapping.push(fix);
+    cursor = fix.end;
+  }
+
+  let output = source;
+  for (let i = nonOverlapping.length - 1; i >= 0; i -= 1) {
+    const fix = nonOverlapping[i];
+    output = `${output.slice(0, fix.start)}${fix.text}${output.slice(fix.end)}`;
+  }
+  return output;
+}
+
+function lintSource(source, { file }) {
+  const text = String(source ?? "");
+  const lineStarts = createLineStarts(text);
+  const parsed = parseFastScript(text, { file, mode: "lenient", recover: true });
+  const issues = [];
+  const fixes = [];
+
+  for (const diagnostic of parsed.diagnostics) {
+    issues.push(
+      createIssue({
+        file,
+        source: text,
+        lineStarts,
+        code: diagnostic.code,
+        severity: diagnostic.severity || "error",
+        message: diagnostic.message,
+        span: diagnostic.span,
+      }),
+    );
+  }
+
+  const todoPattern = /\bTODO_ERROR\b/g;
+  for (const match of text.matchAll(todoPattern)) {
+    const start = match.index ?? 0;
+    issues.push(
+      createIssue({
+        file,
+        source: text,
+        lineStarts,
+        code: "FS3001",
+        severity: "error",
+        message: "Remove TODO_ERROR token.",
+        span: { start, end: start + match[0].length },
+      }),
+    );
+  }
+
+  if (!parsed.estree) return { issues, fixes };
+
+  const reassignedNames = collectReassignedNames(parsed.estree);
+  traverse(parsed.estree, (node) => {
+    if (node.type === "VariableDeclaration") {
+      if (node.kind === "var") {
+        const fixSpan = declarationKeywordFixSpan(text, node, "var");
+        const fix = fixSpan ? { ...fixSpan, text: "let" } : null;
+        issues.push(
+          createIssue({
+            file,
+            source: text,
+            lineStarts,
+            code: "FS3002",
+            severity: "warning",
+            message: "Prefer `let` or `const` over `var`.",
+            span: spanFromNode(node, text.length),
+            fix,
+          }),
+        );
+        if (fix) fixes.push(fix);
+      }
+
+      if (node.kind === "let") {
+        const names = [];
+        for (const declaration of node.declarations || []) {
+          if (declaration.id?.type === "Identifier") names.push(declaration.id.name);
+        }
+        if (names.length > 0 && names.every((name) => !reassignedNames.has(name))) {
+          const fixSpan = declarationKeywordFixSpan(text, node, "let");
+          const fix = fixSpan ? { ...fixSpan, text: "const" } : null;
+          issues.push(
+            createIssue({
+              file,
+              source: text,
+              lineStarts,
+              code: "FS3004",
+              severity: "warning",
+              message: "Binding can be `const`.",
+              span: spanFromNode(node, text.length),
+              fix,
+            }),
+          );
+          if (fix) fixes.push(fix);
+        }
+      }
+    }
+
+    if (node.type === "TemplateElement" && /<script[\s>]/i.test(node.value?.raw || "")) {
+      issues.push(
+        createIssue({
+          file,
+          source: text,
+          lineStarts,
+          code: "FS3003",
+          severity: "warning",
+          message: "Avoid inline <script> tags in template literals.",
+          span: spanFromNode(node, text.length),
+        }),
+      );
+    }
+  });
+
+  return { issues, fixes };
+}
+
+export async function runLint(args = []) {
+  let target = "app";
+  let mode = "fail";
+  let fix = false;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--path") target = args[i + 1] || target;
+    if (args[i] === "--mode") mode = (args[i + 1] || mode).toLowerCase();
+    if (args[i] === "--fix") fix = true;
+  }
+
+  const base = resolve(target);
+  const files = walk(base).filter((file) => extname(file) === ".fs");
+  const issues = [];
+
+  for (const file of files) {
+    const source = readFileSync(file, "utf8");
+    const result = lintSource(source, { file });
+    let next = source;
+    if (fix && result.fixes.length > 0) {
+      next = applyFixes(source, result.fixes);
+      if (next !== source) writeFileSync(file, next, "utf8");
+    }
+    issues.push(...result.issues);
+  }
+
+  issues.sort((a, b) => {
+    if (a.file !== b.file) return a.file.localeCompare(b.file);
+    if (a.span.start !== b.span.start) return a.span.start - b.span.start;
+    if (a.code !== b.code) return a.code.localeCompare(b.code);
+    return a.message.localeCompare(b.message);
+  });
+
+  for (const issue of issues) {
+    console.log(`${issue.file}:${issue.line}:${issue.column} ${issue.code} ${issue.severity} ${issue.message}`);
+  }
+
+  const blocking = issues.filter((issue) => issue.severity === "error");
+  if (blocking.length > 0 && mode !== "pass") {
+    const error = new Error(`lint failed: ${blocking.length} blocking issue(s)`);
+    error.status = 1;
+    error.details = blocking;
+    throw error;
+  }
+
+  console.log(`lint complete: ${files.length} file(s), ${issues.length} issue(s), mode=${mode}, fix=${fix}`);
+}