@dusted/anqst 0.1.1 → 0.1.3

package/dist/src/project.js

@@ -5,189 +5,272 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ANQST_GENERATE_TARGETS = void 0;
 exports.readProjectPackage = readProjectPackage;
+exports.resolveAnQstSettings = resolveAnQstSettings;
 exports.resolveAnQstSpecPath = resolveAnQstSpecPath;
 exports.resolveAnQstGenerateTargets = resolveAnQstGenerateTargets;
 exports.resolveAnQstWidgetCategory = resolveAnQstWidgetCategory;
+exports.resolveAnQstWidgetName = resolveAnQstWidgetName;
 exports.buildSpecScaffold = buildSpecScaffold;
 exports.runInstill = runInstill;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const errors_1 = require("./errors");
-exports.DEFAULT_ANQST_GENERATE_TARGETS = ["QWidget", "AngularService", "//DOM", "//node_express_ws"];
-const ANQST_DSL_IMPORT_LINE = 'import { AnQst } from "anqst";';
+const layout_1 = require("./layout");
+exports.DEFAULT_ANQST_GENERATE_TARGETS = ["QWidget", "AngularService", "node_express_ws"];
+const ANQST_DSL_IMPORT_LINE = 'import type { AnQst } from "@dusted/anqst";';
+const ANQST_BUILD_HOOK = "npx anqst build";
 function readJsonFile(filePath) {
-    const raw = node_fs_1.default.readFileSync(filePath, "utf8");
-    return JSON.parse(raw);
+    try {
+        const raw = node_fs_1.default.readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new errors_1.VerifyError(`Unable to parse JSON file '${(0, layout_1.normalizeSlashes)(filePath)}': ${message}`);
+    }
+}
+function ensureObject(value, errorMessage) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new errors_1.VerifyError(errorMessage);
+    }
+    return value;
 }
-function prependScript(existing, prefix) {
-    if (!existing || existing.trim().length === 0)
-        return prefix;
+function ensureBuildHook(existing) {
+    if (!existing || existing.trim().length === 0) {
+        return ANQST_BUILD_HOOK;
+    }
     const trimmed = existing.trim();
-    if (trimmed === prefix || trimmed.startsWith(`${prefix} &&`))
+    if (trimmed === ANQST_BUILD_HOOK || trimmed.startsWith(`${ANQST_BUILD_HOOK} &&`) || trimmed.includes(ANQST_BUILD_HOOK)) {
         return trimmed;
-    return `${prefix} && ${trimmed}`;
+    }
+    return `${ANQST_BUILD_HOOK} && ${trimmed}`;
+}
+function normalizeAnQstImport(sourceText) {
+    const importPattern = /^\s*import\s+(?:type\s+)?\{\s*AnQst\s*\}\s+from\s+["'][^"']+["'];\s*$/m;
+    if (importPattern.test(sourceText)) {
+        const nextText = sourceText.replace(importPattern, ANQST_DSL_IMPORT_LINE);
+        return { nextText, changed: nextText !== sourceText };
+    }
+    return {
+        nextText: `${ANQST_DSL_IMPORT_LINE}\n\n${sourceText}`,
+        changed: true
+    };
+}
+function isSubPath(parentPath, childPath) {
+    const relative = node_path_1.default.relative(parentPath, childPath);
+    if (relative === "") {
+        return true;
+    }
+    return !relative.startsWith("..") && !node_path_1.default.isAbsolute(relative);
+}
+function readAnQstSettingsFromPath(cwd, settingsPath) {
+    if (!node_fs_1.default.existsSync(settingsPath)) {
+        throw new errors_1.VerifyError(`Missing AnQst settings file '${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, settingsPath))}'. Run 'anqst instill <WidgetName>' first.`);
+    }
+    const raw = readJsonFile(settingsPath);
+    const settingsObject = ensureObject(raw, `Invalid AnQst settings file '${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, settingsPath))}': expected JSON object.`);
+    const layoutVersion = settingsObject.layoutVersion;
+    if (layoutVersion !== layout_1.ANQST_LAYOUT_VERSION) {
+        throw new errors_1.VerifyError(`Invalid AnQst settings file '${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, settingsPath))}': expected layoutVersion ${layout_1.ANQST_LAYOUT_VERSION}.`);
+    }
+    const widgetName = settingsObject.widgetName;
+    if (typeof widgetName !== "string" || widgetName.trim().length === 0) {
+        throw new errors_1.VerifyError(`Invalid AnQst settings file '${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, settingsPath))}': expected non-empty string 'widgetName'.`);
+    }
+    const spec = settingsObject.spec;
+    if (typeof spec !== "string" || spec.trim().length === 0) {
+        throw new errors_1.VerifyError(`Invalid AnQst settings file '${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, settingsPath))}': expected non-empty string 'spec'.`);
+    }
+    const generate = settingsObject.generate;
+    if (generate !== undefined && (!Array.isArray(generate) || generate.some((entry) => typeof entry !== "string"))) {
+        throw new errors_1.VerifyError(`Invalid AnQst settings file '${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, settingsPath))}': expected string array 'generate'.`);
+    }
+    const widgetCategory = settingsObject.widgetCategory;
+    if (widgetCategory !== undefined) {
+        if (typeof widgetCategory !== "string" || widgetCategory.trim().length === 0) {
+            throw new errors_1.VerifyError(`Invalid AnQst settings file '${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, settingsPath))}': expected non-empty string 'widgetCategory'.`);
+        }
+    }
+    const resolvedSpecPath = node_path_1.default.resolve(cwd, spec.trim());
+    const anqstRoot = (0, layout_1.anqstRootDir)(cwd);
+    if (!isSubPath(anqstRoot, resolvedSpecPath)) {
+        throw new errors_1.VerifyError(`Invalid AnQst settings file '${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, settingsPath))}': 'spec' must resolve inside './AnQst'.`);
+    }
+    return {
+        layoutVersion,
+        widgetName: widgetName.trim(),
+        spec: spec.trim(),
+        generate: Array.isArray(generate) ? [...generate] : undefined,
+        widgetCategory: typeof widgetCategory === "string" ? widgetCategory.trim() : undefined
+    };
+}
+function resolveSettingsPathFromPackage(cwd, packageJson) {
+    const settingsRef = packageJson.AnQst;
+    if (settingsRef === undefined) {
+        throw new errors_1.VerifyError("Missing package.json key 'AnQst'. Run 'anqst instill <WidgetName>' first.");
+    }
+    if (typeof settingsRef !== "string" || settingsRef.trim().length === 0) {
+        throw new errors_1.VerifyError("Invalid package.json key 'AnQst': expected non-empty string path to settings JSON.");
+    }
+    return node_path_1.default.resolve(cwd, settingsRef.trim());
+}
+function buildAnQstDirectoryReadme(widgetName) {
+    return [
+        "# AnQst Project Directory",
+        "",
+        "This directory is owned by the AnQst CLI for this project.",
+        "",
+        "## Files",
+        "",
+        `- \`${(0, layout_1.anqstSpecFileName)(widgetName)}\`: AnQst widget spec source.`,
+        `- \`${(0, layout_1.anqstSettingsFileName)(widgetName)}\`: project-local AnQst configuration used by \`anqst build\`.`,
+        "- `generated/`: deterministic build output roots managed by `anqst build`.",
+        "",
+        "## Regeneration",
+        "",
+        "- `npx anqst build` refreshes generated outputs under `generated/`.",
+        "- Build hooks in package.json (`postinstall`, `prebuild`, `prestart`) call `npx anqst build`.",
+        "",
+        "Do not hand-edit generated files under `generated/`; they are overwritten by design.",
+        ""
+    ].join("\n");
+}
+function updateTsConfig(cwd, widgetName) {
+    const tsConfigPath = node_path_1.default.join(cwd, "tsconfig.json");
+    if (!node_fs_1.default.existsSync(tsConfigPath)) {
+        return;
+    }
+    const tsConfigRaw = readJsonFile(tsConfigPath);
+    const tsConfig = ensureObject(tsConfigRaw, "Invalid tsconfig.json: expected top-level object.");
+    const compilerOptions = tsConfig.compilerOptions === undefined
+        ? {}
+        : ensureObject(tsConfig.compilerOptions, "Invalid tsconfig.json: expected object at 'compilerOptions'.");
+    tsConfig.compilerOptions = compilerOptions;
+    if (compilerOptions.baseUrl === undefined) {
+        compilerOptions.baseUrl = ".";
+    }
+    const pathsObject = compilerOptions.paths === undefined
+        ? {}
+        : ensureObject(compilerOptions.paths, "Invalid tsconfig.json: expected object at 'compilerOptions.paths'.");
+    compilerOptions.paths = pathsObject;
+    const generatedAliasPath = `AnQst/generated/frontend/${(0, layout_1.generatedFrontendDirName)(widgetName)}/*`;
+    const existingAlias = pathsObject["anqst-generated/*"];
+    const aliasList = Array.isArray(existingAlias)
+        ? existingAlias.filter((entry) => typeof entry === "string")
+        : [];
+    if (!aliasList.includes(generatedAliasPath)) {
+        aliasList.unshift(generatedAliasPath);
+    }
+    pathsObject["anqst-generated/*"] = [...new Set(aliasList)];
+    if (Array.isArray(tsConfig.include)) {
+        const includeList = tsConfig.include.filter((entry) => typeof entry === "string");
+        const generatedTypesPattern = `AnQst/generated/frontend/${(0, layout_1.generatedFrontendDirName)(widgetName)}/**/*.d.ts`;
+        if (!includeList.includes(generatedTypesPattern)) {
+            includeList.push(generatedTypesPattern);
+        }
+        tsConfig.include = includeList;
+    }
+    node_fs_1.default.writeFileSync(tsConfigPath, `${JSON.stringify(tsConfig, null, 2)}\n`, "utf8");
+}
+function validateWidgetName(widgetName) {
+    const trimmed = widgetName.trim();
+    if (trimmed.length === 0) {
+        throw new errors_1.VerifyError("Usage: anqst instill <WidgetName>");
+    }
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(trimmed)) {
+        throw new errors_1.VerifyError("Invalid widget name: expected a TypeScript identifier for namespace generation.");
+    }
+    return trimmed;
 }
 function readProjectPackage(cwd) {
     const packagePath = node_path_1.default.join(cwd, "package.json");
     if (!node_fs_1.default.existsSync(packagePath)) {
-        throw new errors_1.VerifyError("No package.json: Can only instill AnQst inside an npm project.");
+        throw new errors_1.VerifyError("No package.json: AnQst commands must run inside an npm project.");
     }
     return {
         packagePath,
         packageJson: readJsonFile(packagePath)
     };
 }
-function resolveAnQstSpecPath(cwd) {
+function resolveAnQstSettings(cwd) {
     const { packageJson } = readProjectPackage(cwd);
-    const spec = packageJson.AnQst?.spec;
-    if (!spec || spec.trim().length === 0) {
-        throw new errors_1.VerifyError("Missing package.json key 'AnQst.spec'. Run 'anqst instill <WidgetName>' first.");
-    }
-    return node_path_1.default.resolve(cwd, spec);
+    const settingsPath = resolveSettingsPathFromPackage(cwd, packageJson);
+    return {
+        settingsPath,
+        settings: readAnQstSettingsFromPath(cwd, settingsPath)
+    };
+}
+function resolveAnQstSpecPath(cwd) {
+    const { settings } = resolveAnQstSettings(cwd);
+    return node_path_1.default.resolve(cwd, settings.spec);
 }
 function resolveAnQstGenerateTargets(cwd) {
-    const { packageJson } = readProjectPackage(cwd);
-    const configured = packageJson.AnQst?.generate;
-    if (configured === undefined) {
+    const { settings } = resolveAnQstSettings(cwd);
+    if (!settings.generate) {
         return [...exports.DEFAULT_ANQST_GENERATE_TARGETS];
     }
-    if (!Array.isArray(configured) || configured.some((value) => typeof value !== "string")) {
-        throw new errors_1.VerifyError("Invalid package.json key 'AnQst.generate': expected string array.");
-    }
-    return [...configured];
+    return [...settings.generate];
 }
 function resolveAnQstWidgetCategory(cwd) {
-    const { packageJson } = readProjectPackage(cwd);
-    const configured = packageJson.AnQst?.widgetCategory;
-    if (configured === undefined) {
-        return undefined;
-    }
-    if (typeof configured !== "string") {
-        throw new errors_1.VerifyError("Invalid package.json key 'AnQst.widgetCategory': expected string.");
-    }
-    const trimmed = configured.trim();
-    if (trimmed.length === 0) {
-        throw new errors_1.VerifyError("Invalid package.json key 'AnQst.widgetCategory': expected non-empty string.");
-    }
-    return trimmed;
+    const { settings } = resolveAnQstSettings(cwd);
+    return settings.widgetCategory;
+}
+function resolveAnQstWidgetName(cwd) {
+    const { settings } = resolveAnQstSettings(cwd);
+    return settings.widgetName;
 }
 function buildSpecScaffold(widgetName) {
     return `${ANQST_DSL_IMPORT_LINE}
 
-declare namespace ${widgetName} {
+` +
+        `declare namespace ${widgetName} {
 
-}
+` +
+        `}
 `;
 }
-function normalizeAnQstImport(sourceText) {
-    const importPattern = /^\s*import\s+\{\s*AnQst\s*\}\s+from\s+["'][^"']+["'];\s*$/m;
-    if (importPattern.test(sourceText)) {
-        const nextText = sourceText.replace(importPattern, ANQST_DSL_IMPORT_LINE);
-        return { nextText, changed: nextText !== sourceText };
-    }
-    return {
-        nextText: `${ANQST_DSL_IMPORT_LINE}\n\n${sourceText}`,
-        changed: true
-    };
-}
-function extractDeclaredNamespace(specText) {
-    const match = specText.match(/^\s*declare\s+namespace\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\{/m);
-    return match ? match[1] : null;
-}
-function readLineSync() {
-    const out = [];
-    const buf = Buffer.alloc(1);
-    while (true) {
-        const bytesRead = node_fs_1.default.readSync(0, buf, 0, 1, null);
-        if (bytesRead <= 0)
-            break;
-        const code = buf[0];
-        if (code === 10)
-            break; // \n
-        if (code === 13)
-            continue; // \r
-        out.push(code);
-    }
-    return Buffer.from(out).toString("utf8").trim();
-}
-function chooseWidgetNamePreference(argumentName, namespaceName, specFileName) {
-    const envChoice = process.env.ANQST_INSTILL_WIDGET_NAME_CHOICE;
-    if (envChoice === "argument" || envChoice === "namespace") {
-        return envChoice;
-    }
-    if (!process.stdin.isTTY) {
-        console.warn(`[AnQst] Existing template ${specFileName} declares namespace '${namespaceName}', but command used '${argumentName}'. Non-interactive session; defaulting to '${argumentName}'.`);
-        return "argument";
-    }
-    console.log(`[AnQst] Existing template ${specFileName} declares namespace '${namespaceName}'.`);
-    console.log(`Choose widget name: [1] ${argumentName} (command argument), [2] ${namespaceName} (template namespace)`);
-    while (true) {
-        process.stdout.write("Selection [1/2]: ");
-        const answer = readLineSync().toLowerCase();
-        if (answer === "1" || answer === argumentName.toLowerCase() || answer === "argument") {
-            return "argument";
-        }
-        if (answer === "2" || answer === namespaceName.toLowerCase() || answer === "namespace") {
-            return "namespace";
-        }
-        console.log("Please type 1 or 2.");
-    }
-}
 function runInstill(cwd, widgetName) {
-    if (!widgetName || widgetName.trim().length === 0) {
-        throw new errors_1.VerifyError("Usage: anqst instill <WidgetName>");
-    }
-    const cleanName = widgetName.trim();
+    const cleanName = validateWidgetName(widgetName);
     const { packagePath, packageJson } = readProjectPackage(cwd);
-    if (packageJson.AnQst) {
+    if (packageJson.AnQst !== undefined) {
         throw new errors_1.VerifyError("AnQst already instilled, did you mean to run 'npx anqst build'?");
     }
-    let resolvedWidgetName = cleanName;
-    const requestedSpecPath = node_path_1.default.join(cwd, `${cleanName}.AnQst.d.ts`);
-    const requestedSpecFileName = node_path_1.default.basename(requestedSpecPath);
-    if (node_fs_1.default.existsSync(requestedSpecPath)) {
-        const existingText = node_fs_1.default.readFileSync(requestedSpecPath, "utf8");
+    const anqstRoot = (0, layout_1.anqstRootDir)(cwd);
+    node_fs_1.default.mkdirSync(anqstRoot, { recursive: true });
+    node_fs_1.default.mkdirSync(node_path_1.default.join(anqstRoot, "generated"), { recursive: true });
+    const specPath = node_path_1.default.join(anqstRoot, (0, layout_1.anqstSpecFileName)(cleanName));
+    if (node_fs_1.default.existsSync(specPath)) {
+        const existingText = node_fs_1.default.readFileSync(specPath, "utf8");
         const normalizedImport = normalizeAnQstImport(existingText);
         if (normalizedImport.changed) {
-            node_fs_1.default.writeFileSync(requestedSpecPath, normalizedImport.nextText, "utf8");
-        }
-        const declaredNamespace = extractDeclaredNamespace(normalizedImport.nextText);
-        if (declaredNamespace && declaredNamespace !== cleanName) {
-            const choice = chooseWidgetNamePreference(cleanName, declaredNamespace, requestedSpecFileName);
-            if (choice === "namespace") {
-                resolvedWidgetName = declaredNamespace;
-            }
+            node_fs_1.default.writeFileSync(specPath, normalizedImport.nextText, "utf8");
         }
     }
-    const next = {
+    else {
+        node_fs_1.default.writeFileSync(specPath, buildSpecScaffold(cleanName), "utf8");
+    }
+    const settingsPath = node_path_1.default.join(anqstRoot, (0, layout_1.anqstSettingsFileName)(cleanName));
+    const settings = {
+        layoutVersion: layout_1.ANQST_LAYOUT_VERSION,
+        widgetName: cleanName,
+        spec: `./AnQst/${(0, layout_1.anqstSpecFileName)(cleanName)}`,
+        generate: [...exports.DEFAULT_ANQST_GENERATE_TARGETS],
+        widgetCategory: "AnQst Widgets"
+    };
+    node_fs_1.default.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+    node_fs_1.default.writeFileSync(node_path_1.default.join(anqstRoot, ".gitignore"), "/generated*\n", "utf8");
+    node_fs_1.default.writeFileSync(node_path_1.default.join(anqstRoot, "README.md"), buildAnQstDirectoryReadme(cleanName), "utf8");
+    const nextPackage = {
         ...packageJson,
         scripts: {
-            ...packageJson.scripts,
-            build: prependScript(packageJson.scripts?.build, "npx anqst build"),
-            test: prependScript(packageJson.scripts?.test, "npx anqst test")
+            ...(packageJson.scripts ?? {}),
+            postinstall: ensureBuildHook(packageJson.scripts?.postinstall),
+            prebuild: ensureBuildHook(packageJson.scripts?.prebuild),
+            prestart: ensureBuildHook(packageJson.scripts?.prestart)
         },
-        AnQst: {
-            spec: `${resolvedWidgetName}.AnQst.d.ts`,
-            generate: [...exports.DEFAULT_ANQST_GENERATE_TARGETS]
-        }
+        AnQst: (0, layout_1.anqstSettingsRelativePath)(cleanName)
     };
-    node_fs_1.default.writeFileSync(packagePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
-    const resolvedSpecPath = node_path_1.default.join(cwd, `${resolvedWidgetName}.AnQst.d.ts`);
-    let createdScaffold = false;
-    if (!node_fs_1.default.existsSync(resolvedSpecPath)) {
-        if (resolvedWidgetName !== cleanName && node_fs_1.default.existsSync(requestedSpecPath)) {
-            node_fs_1.default.renameSync(requestedSpecPath, resolvedSpecPath);
-            const movedText = node_fs_1.default.readFileSync(resolvedSpecPath, "utf8");
-            const normalizedMovedImport = normalizeAnQstImport(movedText);
-            if (normalizedMovedImport.changed) {
-                node_fs_1.default.writeFileSync(resolvedSpecPath, normalizedMovedImport.nextText, "utf8");
-            }
-        }
-        else {
-            node_fs_1.default.writeFileSync(resolvedSpecPath, buildSpecScaffold(resolvedWidgetName), "utf8");
-            createdScaffold = true;
-        }
-    }
-    const mode = createdScaffold ? "scaffolded" : "using";
-    return `Instill completed: configured package.json and ${mode} ${resolvedWidgetName}.AnQst.d.ts`;
+    node_fs_1.default.writeFileSync(packagePath, `${JSON.stringify(nextPackage, null, 2)}\n`, "utf8");
+    updateTsConfig(cwd, cleanName);
+    return `Instill completed: configured package.json and scaffolded ${(0, layout_1.normalizeSlashes)(node_path_1.default.relative(cwd, specPath))}`;
 }

package/dist/src/verify.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.verifySpec = verifySpec;
 const typescript_1 = __importDefault(require("typescript"));
 const errors_1 = require("./errors");
+const program_1 = require("./program");
 function parseTypeNodeFromText(typeText) {
     const source = typescript_1.default.createSourceFile("__inline__.ts", `type __X = ${typeText};`, typescript_1.default.ScriptTarget.Latest, true, typescript_1.default.ScriptKind.TS);
     const stmt = source.statements.find(typescript_1.default.isTypeAliasDeclaration);
@@ -170,7 +171,7 @@ function collectReachableTypeNames(spec) {
     }
     return seen;
 }
-function verifySpec(spec) {
+function verifySpecSemantics(spec) {
     checkServiceDuplicates(spec);
     for (const service of spec.services) {
         for (const member of service.members) {
@@ -193,8 +194,20 @@ function verifySpec(spec) {
         reachableGeneratedTypes: reachable.size,
         serviceCount: spec.services.length
     };
+    const warnings = [...spec.warnings];
+    const warningSummary = warnings.length === 0
+        ? ""
+        : `\nWarnings:\n${warnings.map((w) => `    [warn] ${w.loc.file}:${w.loc.line}:${w.loc.column} ${w.memberPath} - ${w.message}`).join("\n")}`;
     return {
         stats,
-        message: `AnQst spec valid:\n    ${stats.namespaceDeclaredTypes} types.\n    ${stats.serviceCount} services.`
+        message: `AnQst spec valid:\n    ${stats.namespaceDeclaredTypes} types.\n    ${stats.serviceCount} services.${warningSummary}`,
+        warnings
     };
 }
+function verifySpec(spec) {
+    const diagnostics = (0, program_1.getProgramDiagnostics)(spec.filePath);
+    if (diagnostics.length > 0) {
+        throw new errors_1.VerifyError(`TypeScript diagnostics in spec:\n    ${diagnostics.join("\n    ")}`);
+    }
+    return verifySpecSemantics(spec);
+}

package/index.d.ts

@@ -0,0 +1 @@
+export { AnQst } from "./spec/AnQst-Spec-DSL";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dusted/anqst",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Opinionated backend generator for webapps.",
   "keywords": [
     "nodejs",
@@ -21,14 +21,19 @@
   "author": "DusteD",
   "type": "commonjs",
   "main": "dist/src/app.js",
+  "types": "index.d.ts",
   "exports": {
-    ".": "./dist/src/app.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./dist/src/app.js"
+    }
   },
   "bin": {
     "anqst": "dist/src/bin/anqst.js"
   },
   "files": [
     "dist/src",
+    "index.d.ts",
     "spec/AnQst-Spec-DSL.d.ts",
     "README.md",
     "LICENSE"

package/spec/AnQst-Spec-DSL.d.ts

@@ -11,19 +11,19 @@
  *   Not for use by TypeScript application implementation.
  * @example
  * package.json:
- * - "AnQst": { "WidgetSpec": "MyUserMgmtWidget.AnQstSpec.d.ts" }
+ * - "AnQst": "./AnQst/MyUserMgmtWidget.settings.json"
  */
 
 export namespace AnQst {
 
     /**
      * Declare service `InterfaceName`
-     * 
+     *
      * @remarks
      * Multiple allowed.
      * Affords developers of advanced widgets the ability to create domain-informed categories.
      * - Duplicate method declarations with identical parameter lists are invalid in normative AnQst-Spec input.
-     * 
+     *
      * @example
      * export interface UserService extends Widget.Service { }
      * // Generates UserService.
@@ -44,6 +44,7 @@ export namespace AnQst {
      */
     interface AngularHTTPBaseServerClass extends Service { }
 
+    type CallConfig = { timeoutSeconds: number } | { timeoutMilliseconds: number } | {};
 
     /**
      * Declare non-blocking service method `MethodName`(`MethodArguments`): Promise<`MethodReturnType`>.
@@ -52,27 +53,38 @@ export namespace AnQst {
      * - Flow:
      *   - Widget: Call to service method `MethodName`(`MethodArguments`).
      *   - Widget: Returns Promise<`MethodReturnType`>.
-     *   - Parent: Registered `MethodReturnType` `MethodName`_Handler(`MethodArguments`) is called.
-     *   - Parent: Handler returns result.
-     *   - Widget: Promise resolves with result.
+     *   - Parent: Registered callback receives args and returns `T` synchronously.
+     *   - Widget: Promise resolves with payload `T` or rejects with plain error object.
+     * - Optional config supports timeout tuning:
+     *   - `AnQst.Call<T, { timeoutSeconds: N }>`
+     *   - `AnQst.Call<T, { timeoutMilliseconds: N }>`
+     * - Exactly one timeout key is allowed. Value must be integer >= 0.
+     * - Default timeout is 120s. `0` means wait forever.
      * @example
      * // AnQst spec:
      * getUserById(userId: string): AnQst.Call<User>
      * //Angular app:
      * const user: User = await this.userService.getUserById("abc");
     */
-    interface Call<T> { dummy: T }
+    interface Call<T, Config extends CallConfig = {}> { dummy: T; config?: Config }
 
-    /**
-     * Declare blocking service method onSlot.`MethodName`( handler(`MethodArguments`):`MethodReturnType` ): void
+    /**
+     * Declare blocking service method onSlot.`MethodName`( handler(`MethodArguments`):`MethodReturnType` ): void
      * @remarks
      * - **Parent** -> Widget
      * - Impl note: Autogenerated stub handler queues until handler is set (set method calls spools queue through handler)
      * - Flow:
      *   - Parent: Call to generated widget method `MethodName`(`MethodArguments`).
-     *   - Widget: Registered handler(`MethodArguments`): `MethodReturnType` is called.
-     *   - Widget: Handler returns result.
+     *   - Widget: Registered handler(`MethodArguments`) is called.
+     *   - Widget: Handler return forms:
+     *      - `T` -> success payload
+     *      - `Promise<T>` -> awaited, success payload on resolve
+     *      - `Error` -> failure
+     *      - throw -> failure
+     *      - rejected promise -> failure
      *   - Parent: `MethodName` call returns with result.
+     * - Generated C++ Slot methods do not expose `ok/error` out parameters.
+     * - Default Slot timeout is 1000ms.
      * Note: One active handler, calling will replace existing and is valid and allowed.
      * @example
      * // AnQst spec:
@@ -95,6 +107,7 @@ export namespace AnQst {
      *   - Widget: Call to service method `MethodName`(`MethodArguments`).
      *   - Widget: Returns void.
      *   - Parent: Might have something connected to the signal, might not.
+     * - If no listener is connected, event is dropped.
      * @example
      * // AnQst spec:
      * complain(whine: string): AnQst.Emitter;
@@ -144,20 +157,20 @@ export namespace AnQst {
 
     /**
      * AnQst-Spec type mapping overview and control.
-     * 
+     *
      * @remarks
      * Any Type that be mapped between TypeScript and Qt, C++ standard types or
      *     Plain Old Data (POD) types (in that order of preference) will be mapped by default.
-     * 
+     *
      * Canonical mapping directive namespace is AnQst.Type.<type>.
      * To express advisory mapping preference, use AnQst.Type.<type>.
      * Advisory means generator SHOULD honor it, but MAY fall back to inferred/default mapping and emit diagnostic.
      * Array forms are equivalent: T[] == Array<T>, and AnQst.Type.X[] == Array<AnQst.Type.X>.
-     * 
+     *
      * TypeScript definitions+classes and C++ structs are generated for each
      *     structured TypeScript type ( type = {...} or interface { ... } )
      *     referenced in an AnQst spec.
-     * 
+     *
      */
     enum Type {
         object = "JavaScript Object <-> QVariantMap (JSON.stringify/parse semantics)",
@@ -195,13 +208,13 @@ export namespace AnQst {
 
     /**
      * These are explicitly forbidden argument/return types.
-     * 
+     *
      * @remarks
      * - They may not be referenced in AnQst specs or imported types.
      * - Service methods cannot accept them as arguments
      * - Service methods cannot return them.
      * - Service properties of their type cannot be declared.
-     * 
+     *
      * - For Objects/Maps/Sets use AnQst.Type.<Type> instead.
      */
     export enum ForbiddenType {
@@ -213,5 +226,24 @@ export namespace AnQst {
         any = "Passing 'any' type across the boundary is not allowed",
     }
 
+    /**
+     * JS/TS Error instances can be returned, but they have special meaning.
+     *
+     * @remarks
+     * AnQst is opinionated, Errors are not for control flow. They are for signalling unrecoverable and unhandled circumstance.
+     * Use: To indicate unrecoverable program error/wrong use.
+     * Don't use: To communicate expected and/or ignorable/handable situations, define a domain-specific transport type instad.
+     * When else encountered: Unhandled Errors.
+     * Effect: The receiving end throws an exception with message `<service>.<member> emitted error: <WidgetStackTrace>`
+     * AnQst internal behavior:
+     * When AnQst type translation/mapping encounters a true Error object instance, the Error object is not transported, instead
+     * the sending AnQst code signals to the receiving AnQst code a message, and the receiving AnQst code throws a runtime exception on
+     * the call or callback site in the Parent.
+
+     */
+    export enum ExceptionalType {
+        Error = "AnQst will not transport an Error object, but will cause an exception to be thrown on reception site."
+    }
+
 }
 

package/dist/src/backend/ast/emit.js

@@ -1,5 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateOutputs = void 0;
-var emit_1 = require("../../emit");
-Object.defineProperty(exports, "generateOutputs", { enumerable: true, get: function () { return emit_1.generateOutputs; } });

package/dist/src/backend/ast/index.js

@@ -1,13 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.astBackend = void 0;
-const emit_1 = require("./emit");
-const parser_1 = require("./parser");
-const verify_1 = require("./verify");
-exports.astBackend = {
-    id: "ast",
-    parseSpecFile: parser_1.parseSpecFile,
-    verifySpec: verify_1.verifySpec,
-    generateOutputs: emit_1.generateOutputs,
-    emitsArtifacts: true
-};

package/dist/src/backend/ast/parser.js

@@ -1,5 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseSpecFile = void 0;
-var parser_1 = require("../../parser");
-Object.defineProperty(exports, "parseSpecFile", { enumerable: true, get: function () { return parser_1.parseSpecFile; } });