sparqlc-cli 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# sparqlc-cli
+
+## 0.1.0
+
+### Minor Changes
+
+- 2885ca4: Add `sparqlc-cli` package containing `sparqlc-tsc` (a drop-in `tsc` replacement for SPARQL query/update imports) and `sparqlc` (a CLI SPARQL compiler).
+  Extract shared declaration generator `toDeclaration` into `sparqlc/declarations.js` and update `ts-plugin-sparqlc` to use it.
+
+### Patch Changes
+
+- Updated dependencies [2885ca4]
+- Updated dependencies [2885ca4]
+  - sparqlc@0.3.0

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# sparqlc-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI utilities for `sparqlc`:
+- **`sparqlc-tsc`**: A drop-in `tsc` replacement that provides type-checking and emit support for `.rq` and `.ru` SPARQL imports compiled with `sparqlc`.
+- **`sparqlc`**: A standalone command-line compiler to compile a SPARQL query/update file to JavaScript module code and output to stdout.
+
+## Installation
+
+```bash
+npm install --save-dev sparqlc-cli sparqlc typescript
+```
+
+---
+
+## `sparqlc-tsc`
+
+### Background
+
+While [`ts-plugin-sparqlc`](https://github.com/hypermedia-app/sparqlc/tree/master/packages/ts-plugin-sparqlc) provides rich types in IDE editors via TypeScript Language Service plugins, plain `tsc` on the command line does not load language service plugins. As a result, command-line builds and CI runs fall back to untyped generic declarations or fail with implicit-any errors.
+
+`sparqlc-tsc` wraps TypeScript's CLI entry point with a custom virtual file system that serves generated declaration files (`foo.d.rq.ts` / `foo.d.ru.ts`) from memory and copies `.rq` and `.ru` files to `outDir` when emitting JavaScript.
+
+### Peer Dependency Notice
+
+`sparqlc-tsc` relies on TypeScript 5.x or 6.x. It interfaces with TypeScript's CLI via `ts.executeCommandLine` and `program.getCommonSourceDirectory()`, which are available on the `ts` namespace in TypeScript 5 and 6.
+
+### Configuration
+
+In your `tsconfig.json`, enable `allowArbitraryExtensions`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowArbitraryExtensions": true
+  }
+}
+```
+
+`allowArbitraryExtensions` is required for TypeScript to look up virtual `foo.d.rq.ts` / `foo.d.ru.ts` declarations for `./foo.rq` / `./foo.ru` imports.
+
+### Usage
+
+Use `sparqlc-tsc` anywhere you would use `tsc`:
+
+```json
+{
+  "scripts": {
+    "build": "sparqlc-tsc",
+    "typecheck": "sparqlc-tsc --noEmit",
+    "watch": "sparqlc-tsc --watch"
+  }
+}
+```
+
+All standard `tsc` flags, project references (`-b`), incremental builds, and `--watch` are fully supported.
+
+### Query Copying
+
+When emitting JavaScript with `outDir`, `sparqlc-tsc` copies all `.rq` and `.ru` files referenced by your TypeScript program to `outDir`, mirroring the directory structure of the emitted JavaScript files.
+
+- Unchanged queries are skipped on incremental builds.
+- When `--listEmittedFiles` is passed, copied queries are logged with `TSFILE: ...`.
+- No copies are performed under `--noEmit`, `--emitDeclarationOnly`, or `noEmitOnError` with diagnostics errors.
+
+### Limitations
+
+- **Statically analysable imports only:** Only queries referenced through statically analysable imports (e.g. `import q from './query.rq'` or `import('./query.rq')` with string literals) are tracked and copied. Dynamic expressions such as ``import(`./queries/${name}.rq`)`` are not copied automatically.
+- **`tsc -b --clean`:** TypeScript's clean command does not track or remove copied `.rq` / `.ru` asset files from `outDir`.
+- **`outFile` unsupported:** Bundle output via `outFile` is not supported for query file copying; `outDir` must be used.
+- **TypeScript internal coupling:** `sparqlc-tsc` hooks into TypeScript's CLI mechanisms (`ts.executeCommandLine`, `ts.sys`, and `program.getCommonSourceDirectory`).
+
+---
+
+## `sparqlc`
+
+A command-line compiler for compiling individual SPARQL queries and updates into JavaScript module source code.
+
+### Usage
+
+```bash
+sparqlc path/to/query.rq
+```
+
+Pass `-b` or `--base <iri>` to specify a base IRI for resolving relative IRIs:
+
+```bash
+sparqlc --base http://example.org/api/ path/to/query.rq > dist/query.js
+```

package/bin/sparqlc-tsc.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../index.js'
+
+run()

package/bin/sparqlc.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCompilerCli } from '../sparqlc.js'
+
+runCompilerCli()

package/index.d.ts

@@ -0,0 +1,20 @@
+import ts from 'typescript';
+declare module 'typescript' {
+    function executeCommandLine(system: ts.System, cb: (programOrBuilder: ts.Program | ts.BuilderProgram | unknown) => void, commandLineArgs: string[]): void;
+    interface Program {
+        getCommonSourceDirectory(): string;
+    }
+}
+export declare const virtualDts: RegExp;
+export declare function toSourcePath(dtsPath: string): string;
+export interface SparqlSysOptions {
+    cache?: Map<string, {
+        mtime: number;
+        content: string;
+    }>;
+}
+export declare function createSparqlSys(tsModule: typeof ts, baseSys?: ts.System, options?: SparqlSysOptions): ts.System;
+export declare function hasSparqlImports(tsModule: typeof ts, sourceFile: ts.SourceFile): boolean;
+export declare function createCopySparqlFiles(tsModule: typeof ts, baseSys?: ts.System): (programOrBuilder: ts.Program | ts.BuilderProgram | unknown) => void;
+export declare function copySparqlFiles(tsModule: typeof ts, baseSys: ts.System, programOrBuilder: ts.Program | ts.BuilderProgram | unknown): void;
+export declare function run(args?: string[], tsModule?: typeof ts, baseSys?: ts.System): void;

package/index.js

@@ -0,0 +1,167 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import ts from 'typescript';
+import { toDeclaration } from 'sparqlc/declarations.js';
+export const virtualDts = /\.d\.r([qu])\.ts$/;
+export function toSourcePath(dtsPath) {
+    return dtsPath.replace(virtualDts, '.r$1');
+}
+export function createSparqlSys(tsModule, baseSys = tsModule.sys, options = {}) {
+    const cache = options.cache ?? new Map();
+    function readVirtual(dtsPath) {
+        const sourcePath = toSourcePath(dtsPath);
+        const mtime = baseSys.getModifiedTime?.(sourcePath)?.getTime();
+        if (mtime === undefined || !baseSys.fileExists(sourcePath))
+            return undefined;
+        const cached = cache.get(dtsPath);
+        if (cached?.mtime === mtime)
+            return cached.content;
+        let content;
+        try {
+            const source = baseSys.readFile(sourcePath);
+            if (source === undefined)
+                return undefined;
+            content = toDeclaration(source);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            baseSys.write(`[sparqlc-tsc] ${sourcePath}: ${message}${baseSys.newLine}`);
+            content = 'export {}\n';
+        }
+        cache.set(dtsPath, { mtime, content });
+        return content;
+    }
+    const sys = {
+        ...baseSys,
+        fileExists: (filePath) => (virtualDts.test(filePath) ? readVirtual(filePath) !== undefined : baseSys.fileExists(filePath)),
+        readFile: (filePath, encoding) => (virtualDts.test(filePath) ? readVirtual(filePath) : baseSys.readFile(filePath, encoding)),
+        realpath: baseSys.realpath ? (filePath) => (virtualDts.test(filePath) ? filePath : baseSys.realpath(filePath)) : undefined,
+        getModifiedTime: baseSys.getModifiedTime
+            ? (filePath) => baseSys.getModifiedTime(virtualDts.test(filePath) ? toSourcePath(filePath) : filePath)
+            : undefined,
+        readDirectory: (dirPath, extensions, excludes, includes, depth) => {
+            const files = baseSys.readDirectory(dirPath, extensions, excludes, includes, depth);
+            if (!extensions || extensions.some(ext => ext.includes('.d.ts') || ext.includes('.ts'))) {
+                const sparqlFiles = baseSys.readDirectory(dirPath, ['.rq', '.ru'], excludes, includes, depth);
+                const virtualFiles = sparqlFiles.map(f => f.replace(/\.r([qu])$/, '.d.r$1.ts'));
+                return Array.from(new Set([...files, ...virtualFiles]));
+            }
+            return files;
+        },
+        watchFile: baseSys.watchFile
+            ? (filePath, callback, pollingInterval, watchOptions) => {
+                if (virtualDts.test(filePath)) {
+                    return baseSys.watchFile(toSourcePath(filePath), (name, kind, mtime) => {
+                        cache.delete(filePath);
+                        callback(filePath, kind, mtime);
+                    }, pollingInterval, watchOptions);
+                }
+                return baseSys.watchFile(filePath, callback, pollingInterval, watchOptions);
+            }
+            : undefined,
+        watchDirectory: baseSys.watchDirectory
+            ? (dirPath, callback, recursive, watchOptions) => {
+                return baseSys.watchDirectory(dirPath, (fileName) => {
+                    callback(fileName);
+                    if (/\.r[qu]$/.test(fileName)) {
+                        const virt = fileName.replace(/\.r([qu])$/, '.d.r$1.ts');
+                        cache.delete(virt);
+                        callback(virt);
+                    }
+                }, recursive, watchOptions);
+            }
+            : undefined,
+    };
+    return sys;
+}
+export function hasSparqlImports(tsModule, sourceFile) {
+    let found = false;
+    function visit(node) {
+        if (found)
+            return;
+        if (tsModule.isImportDeclaration(node) && tsModule.isStringLiteral(node.moduleSpecifier)) {
+            if (/\.r[qu]($|\?)/.test(node.moduleSpecifier.text)) {
+                found = true;
+                return;
+            }
+        }
+        if (tsModule.isExportDeclaration(node) && node.moduleSpecifier && tsModule.isStringLiteral(node.moduleSpecifier)) {
+            if (/\.r[qu]($|\?)/.test(node.moduleSpecifier.text)) {
+                found = true;
+                return;
+            }
+        }
+        if (tsModule.isCallExpression(node)) {
+            const isImportOrRequire = node.expression.kind === tsModule.SyntaxKind.ImportKeyword
+                || (tsModule.isIdentifier(node.expression) && node.expression.text === 'require');
+            if (isImportOrRequire && node.arguments.length > 0 && tsModule.isStringLiteral(node.arguments[0])) {
+                if (/\.r[qu]($|\?)/.test(node.arguments[0].text)) {
+                    found = true;
+                    return;
+                }
+            }
+        }
+        tsModule.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return found;
+}
+export function createCopySparqlFiles(tsModule, baseSys = tsModule.sys) {
+    const warnedProjects = new Set();
+    return function copySparqlFiles(programOrBuilder) {
+        const program = programOrBuilder?.getProgram?.()
+            ?? programOrBuilder;
+        if (!program || typeof program.getSourceFiles !== 'function')
+            return;
+        const options = program.getCompilerOptions();
+        // Check allowArbitraryExtensions warning
+        if (!options.allowArbitraryExtensions) {
+            const configKey = String(options.configFilePath
+                ?? program.getRootFileNames?.()?.slice()?.sort()?.join(';')
+                ?? program.getCurrentDirectory?.()
+                ?? 'default');
+            if (!warnedProjects.has(configKey)) {
+                const hasSparql = program.getSourceFiles().some(sf => !sf.isDeclarationFile && hasSparqlImports(tsModule, sf));
+                if (hasSparql) {
+                    baseSys.write(`[sparqlc-tsc] Warning: 'allowArbitraryExtensions' is not enabled in compiler options. SPARQL imports will not use generated types and will fall back to untyped declarations.${baseSys.newLine}`);
+                    warnedProjects.add(configKey);
+                }
+            }
+        }
+        if (!options.outDir || options.noEmit || options.emitDeclarationOnly)
+            return;
+        if (options.noEmitOnError && tsModule.getPreEmitDiagnostics(program).some(d => d.category === tsModule.DiagnosticCategory.Error))
+            return;
+        const sourceDir = program.getCommonSourceDirectory();
+        const normalizedSourceDir = path.resolve(sourceDir).split(path.sep).join('/');
+        for (const file of program.getSourceFiles()) {
+            if (!virtualDts.test(file.fileName))
+                continue;
+            const source = toSourcePath(file.fileName);
+            const normalizedSource = path.resolve(source).split(path.sep).join('/');
+            const rel = path.relative(normalizedSourceDir, normalizedSource).split(path.sep).join('/');
+            if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                baseSys.write(`[sparqlc-tsc] Error: SPARQL file '${source}' is outside the common source directory ('${normalizedSourceDir}') and cannot be copied to outDir.${baseSys.newLine}`);
+                continue;
+            }
+            const target = path.resolve(options.outDir, rel).split(path.sep).join('/');
+            const content = baseSys.readFile(source);
+            if (content === undefined || baseSys.readFile(target) === content)
+                continue;
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            baseSys.writeFile(target, content);
+            if (options.listEmittedFiles) {
+                baseSys.write(`TSFILE: ${target}${baseSys.newLine}`);
+            }
+        }
+    };
+}
+export function copySparqlFiles(tsModule, baseSys, programOrBuilder) {
+    const handler = createCopySparqlFiles(tsModule, baseSys);
+    handler(programOrBuilder);
+}
+export function run(args = process.argv.slice(2), tsModule = ts, baseSys = tsModule.sys) {
+    const sys = createSparqlSys(tsModule, baseSys);
+    const copyCb = createCopySparqlFiles(tsModule, baseSys);
+    tsModule.executeCommandLine(sys, copyCb, args);
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "sparqlc-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "sparqlc-tsc": "./bin/sparqlc-tsc.js",
+    "sparqlc": "./bin/sparqlc.js"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "bin",
+    "*.js",
+    "*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "mocha",
+    "prepack": "npm run build"
+  },
+  "author": "Tomasz Pluskiewicz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hypermedia-app/sparqlc",
+    "directory": "packages/sparqlc-cli"
+  },
+  "dependencies": {
+    "commander": "13 - 15",
+    "sparqlc": "^0.3.0"
+  },
+  "peerDependencies": {
+    "typescript": "5 || 6"
+  },
+  "devDependencies": {
+    "@types/chai": "^5",
+    "@types/node": "^22.13.10",
+    "chai": "^6",
+    "typescript": "^5.9.3"
+  },
+  "mocha": {
+    "spec": "test/**/*.test.ts",
+    "require": [
+      "tsx"
+    ]
+  }
+}

package/sparqlc.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createCompilerCommand(): Command;
+export declare function runCompilerCli(argv?: string[]): void;

package/sparqlc.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import { Command } from 'commander';
+import { compile } from 'sparqlc';
+export function createCompilerCommand() {
+    const program = new Command();
+    program
+        .name('sparqlc')
+        .description('Compile a SPARQL query/update file to a JavaScript module')
+        .argument('<file>', 'SPARQL file to compile')
+        .option('-b, --base <iri>', 'Base IRI for resolving relative IRIs')
+        .action((file, options) => {
+        const source = fs.readFileSync(file, 'utf-8');
+        const compiled = compile(source, { base: options.base });
+        process.stdout.write(compiled.code);
+    });
+    return program;
+}
+export function runCompilerCli(argv = process.argv) {
+    const program = createCompilerCommand();
+    program.parse(argv);
+}