@chilts/weave 0.5.0 → 0.7.0

package/dist/cli/index.js

@@ -1,8 +1,8 @@
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, watch } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync, unlinkSync, rmdirSync, rmSync, watch, } from 'node:fs';
 import path from 'node:path';
-import { compile, compileWithSourceMap } from '../codegen/index.js';
-import { LexerError } from '../lexer/index.js';
-import { ParserError } from '../parser/index.js';
+import { compile, compileWithSourceMap, definedMixins } from '../codegen/index.js';
+import { lex, LexerError } from '../lexer/index.js';
+import { parse, ParserError } from '../parser/index.js';
 import { CodegenError } from '../codegen/index.js';
 export class UsageError extends Error {
     constructor(message) {
@@ -44,6 +44,9 @@ export function usage() {
         '  <input>   A .weave file or directory containing .weave files',
         '  <output>  Output .ts file or directory for compiled output',
         '',
+        '  In directory mode the output directory belongs to weave: a .ts (and its',
+        '  .ts.map) whose .weave source no longer exists is removed.',
+        '',
         'Options:',
         '  --watch, -w     Watch for changes and recompile (directory mode only)',
         '  --no-sourcemap  Disable source map generation',
@@ -70,6 +73,68 @@ function walk(dir, base, results) {
         }
     }
 }
+// Map a file in the output tree back to the .weave that would have produced it.
+// Anything that is not a compiled artefact returns undefined and is left alone.
+function sourceForOutput(relPath) {
+    if (relPath.endsWith('.ts.map'))
+        return relPath.slice(0, -'.ts.map'.length) + '.weave';
+    if (relPath.endsWith('.ts'))
+        return relPath.slice(0, -'.ts'.length) + '.weave';
+    return undefined;
+}
+function walkAll(dir, base, files, dirs) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const rel = base ? path.join(base, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+            dirs.push(rel);
+            walkAll(path.join(dir, entry.name), rel, files, dirs);
+        }
+        else {
+            files.push(rel);
+        }
+    }
+}
+// The output tree belongs to weave: a .ts (or .ts.map) whose .weave source has
+// gone is an orphan and is removed, so a deleted template stops being compiled
+// into the app. Files weave never emits — anything that is not .ts/.ts.map — are
+// left where they are, as are directories that still hold one of them.
+export function pruneOrphans(inputDir, outputDir) {
+    const files = [];
+    const dirs = [];
+    try {
+        walkAll(outputDir, '', files, dirs);
+    }
+    catch {
+        // Nothing compiled here yet — no output tree to prune.
+        return;
+    }
+    for (const relPath of files) {
+        const sourceRel = sourceForOutput(relPath);
+        if (sourceRel === undefined)
+            continue;
+        if (existsSync(path.join(inputDir, sourceRel)))
+            continue;
+        const outFile = path.join(outputDir, relPath);
+        try {
+            unlinkSync(outFile);
+            console.log(`${outFile} (removed)`);
+        }
+        catch {
+            // Already gone, or not ours to delete.
+        }
+    }
+    // Deepest first, so a directory emptied by the pass above goes with its
+    // parent. rmdir refuses a non-empty directory, which is exactly the guard
+    // we want — anything still holding a file survives.
+    for (const rel of dirs.sort((a, b) => b.length - a.length)) {
+        try {
+            rmdirSync(path.join(outputDir, rel));
+        }
+        catch {
+            // Not empty, or already removed.
+        }
+    }
+}
 export function formatElapsed(ms) {
     if (ms < 1)
         return `${Math.round(ms * 1000)}µs`;
@@ -108,6 +173,69 @@ export function formatError(filePath, err, source) {
     }
     return result;
 }
+/** Resolves `include` paths against the including file and reads their mixins. */
+export function includeResolver(inputFile) {
+    return includePath => {
+        const file = path.resolve(path.dirname(inputFile), includePath + '.weave');
+        let source;
+        try {
+            source = readFileSync(file, 'utf-8');
+        }
+        catch (err) {
+            if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+                throw new Error(`${path.relative(process.cwd(), file)}: no such file`);
+            }
+            throw err;
+        }
+        return definedMixins(parse(lex(source)));
+    };
+}
+/**
+ * Absolute paths of the .weave files a template includes. A template that does
+ * not lex or parse includes nothing as far as the watcher is concerned — its
+ * own compile reports the error.
+ */
+export function includedFiles(inputFile, source) {
+    if (!/^include\s/m.test(source))
+        return [];
+    let doc;
+    try {
+        doc = parse(lex(source));
+    }
+    catch {
+        return [];
+    }
+    return doc.children.flatMap(c => c.type === 'Include' ? [path.resolve(path.dirname(inputFile), c.path + '.weave')] : []);
+}
+/**
+ * Templates under inputDir (relative paths) that include relPath. An includer's
+ * import line is built from the mixins its includes define, so it must be
+ * recompiled when one of them changes. Includes do not re-export, so only
+ * direct includers are affected.
+ */
+export function findIncluders(inputDir, relPath) {
+    const target = path.resolve(inputDir, relPath);
+    let files;
+    try {
+        files = discoverFiles(inputDir);
+    }
+    catch {
+        return [];
+    }
+    return files.filter(file => {
+        if (file === relPath)
+            return false;
+        const inFile = path.join(inputDir, file);
+        let source;
+        try {
+            source = readFileSync(inFile, 'utf-8');
+        }
+        catch {
+            return false;
+        }
+        return includedFiles(inFile, source).includes(target);
+    });
+}
 function writeCompiled(inputFile, outputFile, source, sourcemap) {
     const start = performance.now();
     if (sourcemap) {
@@ -116,15 +244,19 @@ function writeCompiled(inputFile, outputFile, source, sourcemap) {
         const { code, sourceMap } = compileWithSourceMap(source, {
             file: basename,
             sourceFile: sourceRelPath,
+            resolveInclude: includeResolver(inputFile),
         });
         mkdirSync(path.dirname(outputFile), { recursive: true });
         writeFileSync(outputFile, code + `//# sourceMappingURL=${basename}.map\n`);
         writeFileSync(outputFile + '.map', JSON.stringify(sourceMap));
     }
     else {
-        const result = compile(source);
+        const result = compile(source, { resolveInclude: includeResolver(inputFile) });
         mkdirSync(path.dirname(outputFile), { recursive: true });
         writeFileSync(outputFile, result);
+        // A map from an earlier sourcemap build no longer matches this .ts,
+        // and pruning keeps it because the .weave still exists.
+        rmSync(outputFile + '.map', { force: true });
     }
     return performance.now() - start;
 }
@@ -165,24 +297,200 @@ export function compileDir(inputDir, outputDir, sourcemap = true) {
             hasErrors = true;
         }
     }
+    pruneOrphans(inputDir, outputDir);
     return hasErrors;
 }
+// How often the reconciliation pass runs (see reconcile()).
+const RECONCILE_INTERVAL_MS = 2000;
+// Watch the input tree and recompile on change. Returns a function that stops
+// watching.
+//
+// Each directory gets its own non-recursive fs.watch rather than one
+// `{ recursive: true }` watch on the root. On Linux, Node implements recursive
+// watching in JS by watching every *file*, and inotify binds a file watch to
+// the inode — so once an editor saves atomically (write a temp file, rename it
+// over the original) the watch is left on the dead inode and every later save
+// of that file goes unseen. A directory watch reports the rename itself, so it
+// survives atomic saves. New subdirectories are picked up as they appear.
 export function watchDir(inputDir, outputDir, sourcemap = true) {
     compileDir(inputDir, outputDir, sourcemap);
     console.log('\nwatching for changes...');
     const pending = new Map();
-    watch(inputDir, { recursive: true }, (_event, filename) => {
-        if (!filename || !filename.endsWith('.weave'))
-            return;
+    // Keyed by directory relative to inputDir; '' is the root.
+    const watchers = new Map();
+    const schedule = (relPath) => {
         // Debounce: fs.watch fires multiple events per save
-        const existing = pending.get(filename);
+        const existing = pending.get(relPath);
         if (existing)
             clearTimeout(existing);
-        pending.set(filename, setTimeout(() => {
-            pending.delete(filename);
-            compileWatchedFile(inputDir, outputDir, filename, sourcemap);
+        pending.set(relPath, setTimeout(() => {
+            pending.delete(relPath);
+            compileWatchedFile(inputDir, outputDir, relPath, sourcemap);
+            // Compiled directly rather than scheduled, so an include cycle
+            // cannot keep re-triggering itself. One with its own pending
+            // timer will be compiled by that.
+            for (const includer of findIncluders(inputDir, relPath)) {
+                if (!pending.has(includer))
+                    compileWatchedFile(inputDir, outputDir, includer, sourcemap);
+            }
         }, 50));
-    });
+    };
+    const isDir = (relPath) => {
+        try {
+            return statSync(path.join(inputDir, relPath)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    };
+    // Close the watcher for relDir and everything beneath it.
+    const unwatchTree = (relDir) => {
+        for (const [dir, watcher] of watchers) {
+            if (relDir === '' || dir === relDir || dir.startsWith(relDir + path.sep)) {
+                watcher.close();
+                watchers.delete(dir);
+            }
+        }
+    };
+    const watchTree = (relDir) => {
+        if (watchers.has(relDir))
+            return;
+        const absDir = path.join(inputDir, relDir);
+        let watcher;
+        try {
+            watcher = watch(absDir, (_event, filename) => onEvent(relDir, filename));
+        }
+        catch {
+            // Gone before we got to it.
+            return;
+        }
+        watcher.on('error', () => unwatchTree(relDir));
+        watchers.set(relDir, watcher);
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                watchTree(path.join(relDir, entry.name));
+        }
+    };
+    const onEvent = (relDir, filename) => {
+        if (!filename)
+            return;
+        const relPath = path.join(relDir, filename);
+        if (filename.endsWith('.weave')) {
+            schedule(relPath);
+        }
+        else if (watchers.has(relPath)) {
+            // A watched directory was removed or renamed away.
+            if (!isDir(relPath)) {
+                unwatchTree(relPath);
+                pruneOrphans(inputDir, outputDir);
+            }
+        }
+        else if (isDir(relPath)) {
+            // A new directory. Anything written into it before its watcher was
+            // attached produced no event, so compile what is already there.
+            watchTree(relPath);
+            for (const file of discoverFiles(path.join(inputDir, relPath))) {
+                schedule(path.join(relPath, file));
+            }
+        }
+    };
+    // Bring the watcher set in line with the directories on disk, in case a
+    // mkdir or rmdir event was missed.
+    const syncWatchers = () => {
+        for (const dir of watchers.keys()) {
+            if (!isDir(dir))
+                unwatchTree(dir);
+        }
+        watchTree('');
+    };
+    watchTree('');
+    // Safety net: fs.watch is not guaranteed to deliver every event. Under load
+    // the kernel's inotify queue can overflow (IN_Q_OVERFLOW) and drop events,
+    // and atomic-save renames can be coalesced away — leaving a file silently
+    // stale forever. Periodically reconcile by comparing source and output
+    // mtimes, recompiling anything the watcher missed.
+    const interval = setInterval(() => {
+        syncWatchers();
+        reconcile(inputDir, outputDir, sourcemap, pending);
+    }, RECONCILE_INTERVAL_MS);
+    return () => {
+        clearInterval(interval);
+        for (const timer of pending.values())
+            clearTimeout(timer);
+        pending.clear();
+        unwatchTree('');
+    };
+}
+// Walk the input dir and recompile any .weave whose .ts output is missing or
+// older than the source or any file it includes. Files with a pending debounce
+// timer are skipped so we never race an edit the watcher is already handling —
+// this only catches changes whose fs.watch event was dropped.
+export function reconcile(inputDir, outputDir, sourcemap, pending) {
+    let files;
+    try {
+        files = discoverFiles(inputDir);
+    }
+    catch {
+        // Input dir may be temporarily unavailable — skip this cycle.
+        return;
+    }
+    for (const relPath of files) {
+        if (pending.has(relPath))
+            continue;
+        const inFile = path.join(inputDir, relPath);
+        const outFile = path.join(outputDir, relPath.replace(/\.weave$/, '.ts'));
+        let sourceMtime;
+        try {
+            sourceMtime = statSync(inFile).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        let outMtime;
+        try {
+            outMtime = statSync(outFile).mtimeMs;
+        }
+        catch {
+            outMtime = undefined;
+        }
+        let source;
+        try {
+            source = readFileSync(inFile, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        // The output also depends on the mixins each include defines, so an
+        // include edited since the last compile makes it stale too.
+        let newestMtime = sourceMtime;
+        for (const included of includedFiles(inFile, source)) {
+            try {
+                newestMtime = Math.max(newestMtime, statSync(included).mtimeMs);
+            }
+            catch {
+                // A missing include is reported when the template compiles.
+            }
+        }
+        // Up to date — the watcher already handled this file.
+        if (outMtime !== undefined && outMtime >= newestMtime)
+            continue;
+        try {
+            const elapsed = writeCompiled(inFile, outFile, source, sourcemap);
+            console.log(`${outFile} (reconciled, ${formatElapsed(elapsed)})`);
+        }
+        catch (err) {
+            console.error(formatError(inFile, err, source));
+        }
+    }
+    // A delete event can be dropped just as an edit can, so sweep here too.
+    pruneOrphans(inputDir, outputDir);
 }
 function compileWatchedFile(inputDir, outputDir, relPath, sourcemap) {
     const inFile = path.join(inputDir, relPath);
@@ -192,7 +500,8 @@ function compileWatchedFile(inputDir, outputDir, relPath, sourcemap) {
         source = readFileSync(inFile, 'utf-8');
     }
     catch {
-        // File may have been deleted — ignore
+        // The template was deleted (or renamed away) — take its output with it.
+        pruneOrphans(inputDir, outputDir);
         return;
     }
     try {

package/dist/codegen/index.d.ts

@@ -5,22 +5,36 @@ export interface GenerateResult {
     code: string;
     mappings: Mapping[];
 }
+/**
+ * Lists the mixins defined by the `.weave` file an `include` path names.
+ * The path is exactly as written after `include`; throw if it cannot be read.
+ */
+export type IncludeResolver = (includePath: string) => string[];
+export interface GenerateOptions {
+    /**
+     * Without a resolver, a lone `include` is assumed to provide every called
+     * mixin not defined in this file, and more than one `include` is an error.
+     */
+    resolveInclude?: IncludeResolver;
+}
 export declare class CodegenError extends Error {
     readonly line: number;
     readonly col: number;
     constructor(message: string, line: number, col: number);
 }
+/** Names of the mixins a document defines at top level. */
+export declare function definedMixins(doc: DocumentNode): string[];
 /** Generate a TypeScript expression from a single AST node. */
 export declare function generateExpr(node: AstNode): string;
 /** Generate TypeScript source from a DocumentNode. */
-export declare function generate(doc: DocumentNode): GenerateResult;
+export declare function generate(doc: DocumentNode, options?: GenerateOptions): GenerateResult;
 /** Full pipeline: source string → TypeScript source. */
-export declare function compile(source: string): string;
+export declare function compile(source: string, options?: GenerateOptions): string;
 /** Full pipeline with source map generation. */
 export declare function compileWithSourceMap(source: string, opts: {
     file: string;
     sourceFile: string;
-}): {
+} & GenerateOptions): {
     code: string;
     sourceMap: SourceMap;
 };