ondc-code-generator 0.8.9 → 1.0.0

package/dist/generator/generators/rag/rag-generator.js

@@ -0,0 +1,185 @@
+import { ConfigSyntax, TestObjectSyntax } from "../../../constants/syntax.js";
+import { CodeGenerator, } from "../classes/abstract-generator.js";
+import { writeFileWithFsExtra } from "../../../utils/fs-utils.js";
+import { markdownMessageGenerator } from "../documentation/markdown-message-generator.js";
+import { buildAstFromInput } from "../../../services/return-complier/combined.js";
+import { CompileToMarkdownForSkip } from "../../../services/return-complier/ast-functions/compile-to-markdown.js";
+import { addBlockquoteToMarkdown, ConvertArrayToStringsInTestObject, } from "../../../utils/general-utils/string-utils.js";
+import Mustache from "mustache";
+/**
+ * RagGenerator — produces one Markdown file per API action under ./rag-docs/.
+ *
+ * Each file is a self-contained, richly structured document intended to be
+ * fed directly into a Retrieval-Augmented Generation (RAG) pipeline.
+ *
+ * Layout per file:
+ *   ---
+ *   YAML frontmatter (action, codeName, numTests, generated date)
+ *   ---
+ *   # <codeName> — <action> Validations
+ *   Short context paragraph
+ *   Numbered list of every test with its human-readable description,
+ *   error code, scope, and (indented) skip condition when present.
+ */
+export class RagGenerator extends CodeGenerator {
+    constructor() {
+        super(...arguments);
+        this.generateValidationCode = async () => {
+            // Driven by generateCode
+        };
+        this.generateCode = async (codeConfig) => {
+            const testConfig = this.validationConfig[ConfigSyntax.Tests];
+            const { codeName } = codeConfig;
+            for (const action of Object.keys(testConfig)) {
+                const testArray = testConfig[action];
+                const md = this.buildActionMarkdown(action, codeName, testArray);
+                writeFileWithFsExtra(this.rootPath, `./rag-docs/${action}.md`, md);
+            }
+        };
+    }
+    generateSessionDataCode() {
+        // Session-data code not needed for RAG output
+        return Promise.resolve();
+    }
+    generateUnitTestingCode() {
+        // Unit-test code not needed for RAG output
+        return Promise.resolve();
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    buildActionMarkdown(action, codeName, testArray) {
+        const leafCount = this.countLeafTests(testArray);
+        const dateStr = new Date().toISOString().split("T")[0];
+        // YAML front-matter — picked up as metadata by most RAG loaders
+        const frontmatter = [
+            "---",
+            `action: ${action}`,
+            `codeName: ${codeName}`,
+            `numTests: ${leafCount}`,
+            `generated: ${dateStr}`,
+            "---",
+        ].join("\n");
+        // Human-readable header
+        const header = [
+            `# ${codeName} — \`${action}\` Validations`,
+            "",
+            `This document describes the **${leafCount}** validation rule(s) that are`,
+            `applied when the \`${action}\` API call is processed in the **${codeName}** flow.`,
+            `Each rule maps to a single test object and is evaluated sequentially against the`,
+            `request/response payload.`,
+            "",
+            "---",
+            "",
+        ].join("\n");
+        // One numbered ## section per top-level test object only.
+        // Group nodes embed their children as ### sub-sections inside themselves.
+        const sections = testArray
+            .map((test, idx) => this.buildTestSection(test, idx + 1))
+            .join("\n\n");
+        return `${frontmatter}\n\n${header}${sections}\n`;
+    }
+    /** Count only leaf (non-group) tests recursively. */
+    countLeafTests(tests) {
+        let count = 0;
+        for (const test of tests) {
+            const ret = test[TestObjectSyntax.Return];
+            if (typeof ret === "string") {
+                count++;
+            }
+            else {
+                count += this.countLeafTests(ret);
+            }
+        }
+        return count;
+    }
+    /**
+     * Renders a numbered top-level section (##) for a test object.
+     *
+     * - Leaf test  → full human-readable description + metadata badges
+     * - Group node → brief intro line + all children rendered as ### sub-sections
+     *                (recursing further for deeply nested groups)
+     *
+     * This preserves the parent→child relationship in the output so RAG
+     * consumers can see exactly which sub-validations belong to which group.
+     */
+    buildTestSection(test, index) {
+        const name = test[TestObjectSyntax.Name] ?? `test_${index}`;
+        const ret = test[TestObjectSyntax.Return];
+        if (typeof ret === "string") {
+            return this.renderLeaf(test, name, `## ${index}. ${name}`);
+        }
+        // Group node — render intro + skip (before children) then nest children
+        const childSections = ret
+            .map((child, i) => this.renderChildSection(child, i + 1, "###"))
+            .join("\n\n");
+        const groupSkip = this.renderSkipBlock(test);
+        return [
+            `## ${index}. ${name}`,
+            "",
+            `Group of **${ret.length}** sub-validation(s). **All** of the following must pass:`,
+            ...(groupSkip ? ["", groupSkip] : []),
+            "",
+            childSections,
+        ].join("\n");
+    }
+    /**
+     * Renders a child/nested section at the given heading level.
+     * Recurses deeper (####, #####, …) for nested groups.
+     */
+    renderChildSection(test, index, headingLevel) {
+        const name = test[TestObjectSyntax.Name] ?? `sub_test_${index}`;
+        const ret = test[TestObjectSyntax.Return];
+        const heading = `${headingLevel} ${index}. ${name}`;
+        if (typeof ret === "string") {
+            return this.renderLeaf(test, name, heading);
+        }
+        // Nested group — go one heading level deeper
+        const nextLevel = headingLevel + "#";
+        const childSections = ret
+            .map((child, i) => this.renderChildSection(child, i + 1, nextLevel))
+            .join("\n\n");
+        const groupSkip = this.renderSkipBlock(test);
+        return [
+            heading,
+            "",
+            `Group of **${ret.length}** sub-validation(s). **All** of the following must pass:`,
+            ...(groupSkip ? ["", groupSkip] : []),
+            "",
+            childSections,
+        ].join("\n");
+    }
+    /**
+     * Renders the skip block for a group node as a blockquote.
+     * Returns an empty string when there is no _CONTINUE_ on this node.
+     */
+    renderSkipBlock(test) {
+        const skip = test[TestObjectSyntax.Continue];
+        if (!skip)
+            return "";
+        let skipMarkdown = `**Skip if:**\n`;
+        const skAst = buildAstFromInput(skip);
+        const skBlock = CompileToMarkdownForSkip(skAst, false, 2, false);
+        skipMarkdown += `\n${skBlock}`;
+        const rendered = Mustache.render(skipMarkdown, ConvertArrayToStringsInTestObject(test));
+        return addBlockquoteToMarkdown(rendered);
+    }
+    /** Renders a leaf test's heading, metadata badges, and compiled description. */
+    renderLeaf(test, name, heading) {
+        const scope = test[TestObjectSyntax.Scope];
+        const errorCode = test[TestObjectSyntax.ErrorCode];
+        const successCode = test[TestObjectSyntax.SuccessCode];
+        const skip = test[TestObjectSyntax.Continue];
+        const ret = test[TestObjectSyntax.Return];
+        const badges = [];
+        if (scope)
+            badges.push(`**Scope:** \`${scope}\``);
+        if (errorCode !== undefined)
+            badges.push(`**Error Code:** \`${errorCode}\``);
+        if (successCode !== undefined)
+            badges.push(`**Success Code:** \`${successCode}\``);
+        const badgeLine = badges.length > 0 ? badges.join(" · ") + "\n\n" : "";
+        const body = markdownMessageGenerator(ret, test, name, skip ? [skip] : undefined);
+        return `${heading}\n\n${badgeLine}${body}`;
+    }
+}

package/dist/generator/generators/rag/rag-table-generator.d.ts

@@ -0,0 +1,55 @@
+import { TestObject } from "../../../types/config-types.js";
+import { CodeGenerator, CodeGeneratorProps } from "../classes/abstract-generator.js";
+/**
+ * RagTableGenerator — produces one Markdown **table** file per API action
+ * under `./rag-table-docs/`.
+ *
+ * Each file contains:
+ *   - YAML front-matter (action, codeName, numTests, generated date)
+ *   - A short summary paragraph
+ *   - A single GFM table
+ *
+ * Columns: # | Type | Test Name | Group | Scope | Description | Skip If | Error Code
+ *
+ * Group nodes ARE rendered as their own rows. Their Description cell lists
+ * the immediate child test names and their Skip If cell shows the group's own
+ * _CONTINUE_ condition.  Child leaf rows follow immediately after, with the
+ * Group column showing their parent's name — making hierarchy fully visible.
+ *
+ * This format is complementary to `RagGenerator` (heading-based): use it
+ * when you need a dense, scannable overview of all rules at once.
+ */
+export declare class RagTableGenerator extends CodeGenerator {
+    generateSessionDataCode(): Promise<void>;
+    generateUnitTestingCode(): Promise<void>;
+    generateValidationCode: () => Promise<void>;
+    generateCode: (codeConfig: CodeGeneratorProps) => Promise<void>;
+    /** Collects rows and returns structured JSON for one action. */
+    private buildActionJson;
+    buildActionMarkdown(action: string, codeName: string, testArray: TestObject[], codeConfig: CodeGeneratorProps): string;
+    /**
+     * Walks the test tree depth-first.
+     *
+     * - **Group node** → emits one summary row whose Description lists the
+     *   immediate child names, and whose Skip If shows the group's own
+     *   _CONTINUE_. Then recurses so children follow immediately after.
+     * - **Leaf node** → emits one row with the compiled description and its
+     *   own _CONTINUE_ only (no skip inheritance from parents).
+     */
+    private collectRows;
+    /**
+     * Renders the GFM table with all rows.
+     *
+     * Columns shown depend on whether *any* row has a value:
+     * - `Group` column hidden when no tests have a group (flat config)
+     * - `Scope`, `Skip If`, `Error Code`, `Success Code` similarly pruned
+     */
+    private renderTable;
+    /**
+     * Sanitises a string for safe use inside a GFM table cell:
+     * - Collapses newlines and excess whitespace to a single space
+     * - Escapes pipe characters
+     * - Strips any leading `####` heading markers left by the compiler
+     */
+    private sanitizeCell;
+}

package/dist/generator/generators/rag/rag-table-generator.js

@@ -0,0 +1,269 @@
+import { ConfigSyntax, TestObjectSyntax } from "../../../constants/syntax.js";
+import { CodeGenerator, } from "../classes/abstract-generator.js";
+import { writeFileWithFsExtra } from "../../../utils/fs-utils.js";
+import { markdownMessageGenerator } from "../documentation/markdown-message-generator.js";
+/**
+ * RagTableGenerator — produces one Markdown **table** file per API action
+ * under `./rag-table-docs/`.
+ *
+ * Each file contains:
+ *   - YAML front-matter (action, codeName, numTests, generated date)
+ *   - A short summary paragraph
+ *   - A single GFM table
+ *
+ * Columns: # | Type | Test Name | Group | Scope | Description | Skip If | Error Code
+ *
+ * Group nodes ARE rendered as their own rows. Their Description cell lists
+ * the immediate child test names and their Skip If cell shows the group's own
+ * _CONTINUE_ condition.  Child leaf rows follow immediately after, with the
+ * Group column showing their parent's name — making hierarchy fully visible.
+ *
+ * This format is complementary to `RagGenerator` (heading-based): use it
+ * when you need a dense, scannable overview of all rules at once.
+ */
+export class RagTableGenerator extends CodeGenerator {
+    constructor() {
+        super(...arguments);
+        this.generateValidationCode = async () => {
+            // Driven by generateCode
+        };
+        this.generateCode = async (codeConfig) => {
+            const testConfig = this.validationConfig[ConfigSyntax.Tests];
+            const { codeName } = codeConfig;
+            const rawJson = {};
+            for (const action of Object.keys(testConfig)) {
+                const testArray = testConfig[action];
+                const md = this.buildActionMarkdown(action, codeName, testArray, codeConfig);
+                writeFileWithFsExtra(this.rootPath, `./rag-table-docs/${action}.md`, md);
+                rawJson[action] = this.buildActionJson(action, codeName, testArray);
+            }
+            writeFileWithFsExtra(this.rootPath, `./rag-table-docs/raw_table.json`, JSON.stringify(rawJson, null, 2));
+        };
+    }
+    generateSessionDataCode() {
+        return Promise.resolve();
+    }
+    generateUnitTestingCode() {
+        return Promise.resolve();
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /** Collects rows and returns structured JSON for one action. */
+    buildActionJson(action, codeName, testArray) {
+        const rows = [];
+        this.collectRows(testArray, rows, "");
+        rows.forEach((r, i) => (r.index = i + 1));
+        return {
+            action,
+            codeName,
+            numLeafTests: rows.filter((r) => r.rowType === "leaf").length,
+            generated: new Date().toISOString().split("T")[0],
+            rows: rows.map(({ index: _idx, ...rest }) => rest),
+        };
+    }
+    buildActionMarkdown(action, codeName, testArray, codeConfig) {
+        const rows = [];
+        this.collectRows(testArray, rows, "");
+        // Re-index after collection so numbering is clean
+        rows.forEach((r, i) => (r.index = i + 1));
+        const dateStr = new Date().toISOString().split("T")[0];
+        const domainText = Array.isArray(codeConfig.domain)
+            ? codeConfig.domain.join(", ")
+            : (codeConfig.domain ?? "-");
+        const frontmatter = [
+            "---",
+            `action: ${action}`,
+            `codeName: ${codeName}`,
+            `numTests: ${rows.length}`,
+            `generated: ${dateStr}`,
+            `domain: ${domainText}`,
+            `version: ${codeConfig.version ?? "-"}`,
+            "---",
+        ].join("\n");
+        const leafCount = rows.filter((r) => r.rowType === "leaf").length;
+        const header = [
+            `# ${codeName} — \`${action}\` Validations (Table View)`,
+            "",
+            `**${leafCount}** leaf validation rule(s) applied to \`${action}\` in the **${codeName}** flow.`,
+            `Domain: \`${domainText}\`, Version: \`${codeConfig.version ?? "-"}\``,
+            `Group rows (GRP) list their immediate sub-tests. Leaf rows (LF) show the actual validation logic.`,
+            "",
+            "---",
+            "",
+        ].join("\n");
+        const table = this.renderTable(rows);
+        return `${frontmatter}\n\n${header}${table}\n`;
+    }
+    /**
+     * Walks the test tree depth-first.
+     *
+     * - **Group node** → emits one summary row whose Description lists the
+     *   immediate child names, and whose Skip If shows the group's own
+     *   _CONTINUE_. Then recurses so children follow immediately after.
+     * - **Leaf node** → emits one row with the compiled description and its
+     *   own _CONTINUE_ only (no skip inheritance from parents).
+     */
+    collectRows(tests, acc, parentPath) {
+        for (const test of tests) {
+            const name = test[TestObjectSyntax.Name] ?? "unknown";
+            const ret = test[TestObjectSyntax.Return];
+            const ownSkip = test[TestObjectSyntax.Continue];
+            if (typeof ret === "string") {
+                // ── Leaf row ──────────────────────────────────────────────
+                const scope = test[TestObjectSyntax.Scope] ?? "";
+                const errorCode = test[TestObjectSyntax.ErrorCode] ?? "30000";
+                const successCode = test[TestObjectSyntax.SuccessCode];
+                let description;
+                try {
+                    description = markdownMessageGenerator(ret, test, name, undefined)
+                        .replace(/^#{1,6}\s+\*\*[^*]+\*\*\s*\n\n?/, "")
+                        .trim();
+                }
+                catch {
+                    description = ret;
+                }
+                let skipText = "";
+                if (ownSkip) {
+                    try {
+                        skipText = markdownMessageGenerator(ownSkip, test, name, undefined)
+                            .replace(/^#{1,6}\s+\*\*[^*]+\*\*\s*\n\n?/, "")
+                            .trim();
+                    }
+                    catch {
+                        skipText = ownSkip;
+                    }
+                }
+                acc.push({
+                    index: acc.length + 1,
+                    rowType: "leaf",
+                    name,
+                    group: parentPath,
+                    scope: scope ? `\`${scope}\`` : "",
+                    description: this.sanitizeCell(description),
+                    skipIf: this.sanitizeCell(skipText),
+                    errorCode: errorCode !== undefined ? String(errorCode) : "",
+                    successCode: successCode !== undefined ? String(successCode) : "",
+                });
+            }
+            else {
+                // ── Group row ─────────────────────────────────────────────
+                const childNames = ret
+                    .map((c) => c[TestObjectSyntax.Name] ?? "?")
+                    .join(", ");
+                let skipText = "";
+                if (ownSkip) {
+                    try {
+                        skipText = markdownMessageGenerator(ownSkip, test, name, undefined)
+                            .replace(/^#{1,6}\s+\*\*[^*]+\*\*\s*\n\n?/, "")
+                            .trim();
+                    }
+                    catch {
+                        skipText = ownSkip;
+                    }
+                }
+                acc.push({
+                    index: acc.length + 1,
+                    rowType: "group",
+                    name: `**${name}**`,
+                    group: parentPath,
+                    scope: "",
+                    description: this.sanitizeCell(`Sub-tests: ${childNames}`),
+                    skipIf: this.sanitizeCell(skipText),
+                    errorCode: "",
+                    successCode: "",
+                });
+                // Recurse — children follow immediately after the group row
+                const newPath = parentPath ? `${parentPath} > ${name}` : name;
+                this.collectRows(ret, acc, newPath);
+            }
+        }
+    }
+    /**
+     * Renders the GFM table with all rows.
+     *
+     * Columns shown depend on whether *any* row has a value:
+     * - `Group` column hidden when no tests have a group (flat config)
+     * - `Scope`, `Skip If`, `Error Code`, `Success Code` similarly pruned
+     */
+    renderTable(rows) {
+        const hasGroup = rows.some((r) => r.group !== "");
+        const hasScope = rows.some((r) => r.scope !== "");
+        const hasSkip = rows.some((r) => r.skipIf !== "");
+        const hasSuccess = rows.some((r) => r.successCode !== "");
+        const cols = [
+            { header: "#", align: "r", value: (r) => String(r.index) },
+            {
+                header: "Type",
+                align: "c",
+                value: (r) => (r.rowType === "group" ? "GRP" : "LF"),
+            },
+            {
+                header: "Test Name",
+                align: "l",
+                // Group rows already have **bold** markers; leaf rows get backticks
+                value: (r) => r.rowType === "group" ? r.name : `\`${r.name}\``,
+            },
+            ...(hasGroup
+                ? [
+                    {
+                        header: "Group",
+                        align: "l",
+                        value: (r) => r.group,
+                    },
+                ]
+                : []),
+            ...(hasScope
+                ? [
+                    {
+                        header: "Scope",
+                        align: "l",
+                        value: (r) => r.scope,
+                    },
+                ]
+                : []),
+            { header: "Description", align: "l", value: (r) => r.description },
+            ...(hasSkip
+                ? [
+                    {
+                        header: "Skip If",
+                        align: "l",
+                        value: (r) => r.skipIf,
+                    },
+                ]
+                : []),
+            {
+                header: "Error Code",
+                align: "c",
+                value: (r) => r.errorCode,
+            },
+            ...(hasSuccess
+                ? [
+                    {
+                        header: "Success Code",
+                        align: "c",
+                        value: (r) => r.successCode,
+                    },
+                ]
+                : []),
+        ];
+        const alignChar = (a) => a === "r" ? "---:" : a === "c" ? ":---:" : ":---";
+        const headerRow = `| ${cols.map((c) => c.header).join(" | ")} |`;
+        const sepRow = `| ${cols.map((c) => alignChar(c.align)).join(" | ")} |`;
+        const dataRows = rows.map((r) => `| ${cols.map((c) => c.value(r) || "—").join(" | ")} |`);
+        return [headerRow, sepRow, ...dataRows].join("\n");
+    }
+    /**
+     * Sanitises a string for safe use inside a GFM table cell:
+     * - Collapses newlines and excess whitespace to a single space
+     * - Escapes pipe characters
+     * - Strips any leading `####` heading markers left by the compiler
+     */
+    sanitizeCell(text) {
+        return text
+            .replace(/\r?\n/g, " ")
+            .replace(/\s{2,}/g, " ")
+            .replace(/\|/g, "\\|")
+            .trim();
+    }
+}

package/dist/generator/generators/typescript/ts-generator.js

@@ -100,7 +100,7 @@ export class TypescriptGenerator extends CodeGenerator {
             await this.generateValidationCode();
             await writeAndFormatCode(this.rootPath, "error.ts", this.generateErrorFile(this.errorCodes), "typescript");
             await writeAndFormatCode(this.rootPath, "index.ts", this.generateIndexFile(Object.keys(this.validationConfig[ConfigSyntax.Tests]), codeConfig.codeName), "typescript");
-            await new MarkdownDocGenerator(this.validationConfig, this.errorCodes, this.rootPath).generateCode();
+            await new MarkdownDocGenerator(this.validationConfig, this.errorCodes, this.rootPath).generateCode(codeConfig);
             await this.generateSessionDataCode();
         };
         this.generateTestFunction = async (testObject) => {

package/dist/index.test.js

@@ -14,15 +14,24 @@ const main = async () => {
     await compiler.initialize(buildYaml);
     const validPaths = await compiler.generateValidPaths();
     writeFileSync(path.resolve(__dirname, "../alpha/possible-json-paths.json"), JSON.stringify(validPaths, null, 2), "utf-8");
-    await compiler.generateCode(valConfig, "L1_validations", false, "./alpha/python/");
+    await compiler.generateCode(valConfig, {
+        codeName: "L1_validations",
+        outputPath: "./alpha/python/",
+    });
     const compilerTy = new ConfigCompiler(SupportedLanguages.Typescript);
     await compilerTy.initialize(buildYaml);
-    await compilerTy.generateCode(valConfig, "L1_validations", false, "./alpha/typescript/");
+    await compilerTy.generateCode(valConfig, {
+        codeName: "L1_validations",
+        outputPath: "./alpha/typescript/",
+    });
     await compilerTy.generateL0Schema("./alpha/typescript/L0_schema/");
     await compilerTy.generateL0Schema("./alpha/json/", "json");
     const compilerGo = new ConfigCompiler(SupportedLanguages.Golang);
     await compilerGo.initialize(buildYaml);
-    await compilerGo.generateCode(valConfig, "L1_validations", false, "./alpha/golang/");
+    await compilerGo.generateCode(valConfig, {
+        codeName: "L1_validations",
+        outputPath: "./alpha/golang/",
+    });
     // JavaScript generation example
     // const compilerJs = new ConfigCompiler(SupportedLanguages.Javascript);
     // await compilerJs.initialize(buildYaml);

package/dist/types/build.d.ts

@@ -41,6 +41,10 @@ export type BuildPath = {
 };
 export interface BUILD_TYPE {
     paths: BuildPath;
+    info: {
+        domain?: string | string[];
+        version?: string;
+    };
     "x-enum": any;
     "x-attributes": Xattributes;
     "x-errorcodes": {

package/dist/types/compiler-types.d.ts

@@ -3,5 +3,7 @@ export declare enum SupportedLanguages {
     Python = "python",
     Javascript = "javascript",
     Golang = "go",
-    Markdown = "md"
+    Markdown = "md",
+    RAG = "rag",
+    RAG_TABLE = "rag_table"
 }

package/dist/types/compiler-types.js

@@ -5,4 +5,6 @@ export var SupportedLanguages;
     SupportedLanguages["Javascript"] = "javascript";
     SupportedLanguages["Golang"] = "go";
     SupportedLanguages["Markdown"] = "md";
+    SupportedLanguages["RAG"] = "rag";
+    SupportedLanguages["RAG_TABLE"] = "rag_table";
 })(SupportedLanguages || (SupportedLanguages = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ondc-code-generator",
-    "version": "0.8.9",
+    "version": "1.0.0",
     "description": "generate code from build.yaml ",
     "main": "dist/index.js",
     "type": "module",