ondc-code-generator 0.9.0 → 1.0.1

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

@@ -2,184 +2,230 @@ 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/.
+ * RagGenerator — produces one richly structured Markdown file per API action
+ * under `./rag-docs/`, designed for direct RAG pipeline ingestion.
  *
- * Each file is a self-contained, richly structured document intended to be
- * fed directly into a Retrieval-Augmented Generation (RAG) pipeline.
- *
- * Layout per file:
+ * Format:
+ *   ---
+ *   YAML frontmatter (action, codeName, numTests, generated, domain, version)
  *   ---
- *   YAML frontmatter (action, codeName, numTests, generated date)
+ *   # Heading + context paragraph
+ *
+ *   ## TOP_LEVEL_GROUP
+ *   Prose intro listing child names, scope, skip condition.
  *   ---
- *   # <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.
+ *   ### CHILD_GROUP
+ *   **LEAF_NAME**
+ *   `group: PATH | type: leaf | error_code: X`
+ *
+ *   - bullet description lines
+ *   - Skipped if ...
  */
 export class RagGenerator extends CodeGenerator {
     constructor() {
         super(...arguments);
-        this.generateValidationCode = async () => {
-            // Driven by generateCode
-        };
+        this.generateValidationCode = async () => { };
         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);
+                const md = this.buildActionMarkdown(action, codeName, testArray, codeConfig);
                 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) {
+    buildActionMarkdown(action, codeName, testArray, codeConfig) {
         const leafCount = this.countLeafTests(testArray);
+        const topCount = testArray.length;
         const dateStr = new Date().toISOString().split("T")[0];
-        // YAML front-matter — picked up as metadata by most RAG loaders
-        const frontmatter = [
+        const domainText = Array.isArray(codeConfig.domain)
+            ? codeConfig.domain.join(", ")
+            : (codeConfig.domain ?? "");
+        const fmLines = [
             "---",
             `action: ${action}`,
             `codeName: ${codeName}`,
             `numTests: ${leafCount}`,
             `generated: ${dateStr}`,
-            "---",
-        ].join("\n");
-        // Human-readable header
+        ];
+        if (domainText)
+            fmLines.push(`domain: ${domainText}`);
+        if (codeConfig.version)
+            fmLines.push(`version: ${codeConfig.version}`);
+        fmLines.push("---");
+        const frontmatter = fmLines.join("\n");
         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.`,
+            `These are the validation rules applied when processing the \`${action}\` API call in the ${codeName} flow.`,
+            `There are **${leafCount}** validation rules organized into **${topCount}** top-level group(s).`,
             "",
             "---",
             "",
         ].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");
+            .map((test) => this.buildTopLevelSection(test))
+            .join("\n\n---\n\n");
         return `${frontmatter}\n\n${header}${sections}\n`;
     }
-    /** Count only leaf (non-group) tests recursively. */
+    /** Counts 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);
-            }
+        for (const t of tests) {
+            const ret = t[TestObjectSyntax.Return];
+            count +=
+                typeof ret === "string"
+                    ? 1
+                    : this.countLeafTests(ret);
         }
         return count;
     }
+    /** Formats a list of names as English prose: "A, B, and C". */
+    englishList(names) {
+        if (names.length === 0)
+            return "";
+        if (names.length === 1)
+            return names[0];
+        if (names.length === 2)
+            return `${names[0]} and ${names[1]}`;
+        return (names.slice(0, -1).join(", ") + ", and " + names[names.length - 1]);
+    }
     /**
-     * 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.
+     * Top-level `##` section.
+     * - Leaf  → `## NAME` + metadata line + body
+     * - Group → `## NAME` + prose intro + `---` + children
      */
-    buildTestSection(test, index) {
-        const name = test[TestObjectSyntax.Name] ?? `test_${index}`;
+    buildTopLevelSection(test) {
+        const name = test[TestObjectSyntax.Name] ?? "unknown";
         const ret = test[TestObjectSyntax.Return];
         if (typeof ret === "string") {
-            return this.renderLeaf(test, name, `## ${index}. ${name}`);
+            const body = this.renderLeafBody(test, "top-level", false);
+            return [`## ${name}`, "", body].join("\n");
         }
-        // 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");
+        return this.renderGroupSection(test, name, "##", "###", []);
     }
     /**
-     * Renders a child/nested section at the given heading level.
-     * Recurses deeper (####, #####, …) for nested groups.
+     * Renders a group section recursively.
+     * @param headingLevel  Markdown heading for this group node (e.g. "##")
+     * @param childLevel    Markdown heading for its direct children (e.g. "###")
+     * @param ancestorPath  Names of ancestor groups, used to build breadcrumbs
      */
-    renderChildSection(test, index, headingLevel) {
-        const name = test[TestObjectSyntax.Name] ?? `sub_test_${index}`;
+    renderGroupSection(test, name, headingLevel, childLevel, ancestorPath) {
         const ret = test[TestObjectSyntax.Return];
-        const heading = `${headingLevel} ${index}. ${name}`;
-        if (typeof ret === "string") {
-            return this.renderLeaf(test, name, heading);
+        const skip = test[TestObjectSyntax.Continue];
+        const scope = test[TestObjectSyntax.Scope];
+        const childNames = ret.map((c) => c[TestObjectSyntax.Name] ?? "?");
+        const leafCount = this.countLeafTests(ret);
+        const allLeaves = ret.every((c) => typeof c[TestObjectSyntax.Return] === "string");
+        // Prose intro sentence
+        const introParts = [];
+        if (allLeaves) {
+            introParts.push(`This is a group of **${leafCount}** sub-validation(s) that all must pass: ` +
+                `${this.englishList(childNames)}.`);
+        }
+        else {
+            introParts.push(`This group contains **${ret.length}** sub-group(s)/validation(s): ` +
+                `${this.englishList(childNames)}.`);
+        }
+        if (scope) {
+            introParts.push(`It validates the \`${scope}\` path in the payload.`);
         }
-        // Nested group — go one heading level deeper
-        const nextLevel = headingLevel + "#";
+        const introLine = introParts.join(" ");
+        // Skip block for the group itself (blockquote, before children)
+        let skipBlock = "";
+        if (skip) {
+            skipBlock = this.renderSkipInlineBullet(test, skip);
+        }
+        // Render children
+        const currentPath = [...ancestorPath, name];
+        const grandChildLevel = childLevel + "#";
         const childSections = ret
-            .map((child, i) => this.renderChildSection(child, i + 1, nextLevel))
+            .map((child) => {
+            const childName = child[TestObjectSyntax.Name] ?? "unknown";
+            const childRet = child[TestObjectSyntax.Return];
+            if (typeof childRet === "string") {
+                return this.renderLeafBody(child, currentPath.join(" > "));
+            }
+            return this.renderGroupSection(child, childName, childLevel, grandChildLevel, currentPath);
+        })
             .join("\n\n");
-        const groupSkip = this.renderSkipBlock(test);
         return [
-            heading,
+            `${headingLevel} ${name}`,
             "",
-            `Group of **${ret.length}** sub-validation(s). **All** of the following must pass:`,
-            ...(groupSkip ? ["", groupSkip] : []),
+            introLine,
+            ...(skipBlock ? ["", skipBlock] : []),
+            "",
+            "---",
             "",
             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.
+     * Renders a leaf node's full content block:
+     *   **NAME**
+     *   `group: PATH | type: leaf | error_code: X`
+     *
+     *   - bullet description lines
+     *   - Skipped if ...  (inline, from markdownMessageGenerator)
      */
-    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) {
+    renderLeafBody(test, groupPath, showBoldName = true) {
+        const name = test[TestObjectSyntax.Name] ?? "unknown";
         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 = [];
+        // Metadata inline-code line
+        const metaParts = [`group: ${groupPath}`, `type: leaf`];
         if (scope)
-            badges.push(`**Scope:** \`${scope}\``);
+            metaParts.push(`scope: ${scope}`);
         if (errorCode !== undefined)
-            badges.push(`**Error Code:** \`${errorCode}\``);
+            metaParts.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}`;
+            metaParts.push(`success_code: ${successCode}`);
+        const metaLine = `\`${metaParts.join(" | ")}\``;
+        // Get bullet-point body from compiler; strip the "#### **name**\n\n" heading.
+        let bodyContent;
+        try {
+            const full = markdownMessageGenerator(ret, test, name, skip ? [skip] : undefined);
+            bodyContent = full
+                .replace(/^#{1,6}\s+\*\*[^*]+\*\*\s*\n\n?/, "")
+                .trim();
+        }
+        catch {
+            bodyContent = `- ${ret}`;
+            if (skip)
+                bodyContent += `\n- Skipped if: ${skip}`;
+        }
+        return showBoldName
+            ? [`**${name}**`, metaLine, "", bodyContent].join("\n")
+            : [metaLine, "", bodyContent].join("\n");
+    }
+    /**
+     * Renders a group's skip condition as a blockquote paragraph.
+     * Uses markdownMessageGenerator to compile the JVAL expression.
+     */
+    renderSkipInlineBullet(test, skip) {
+        try {
+            const full = markdownMessageGenerator(skip, test, "skip", undefined);
+            const body = full
+                .replace(/^#{1,6}\s+\*\*[^*]+\*\*\s*\n\n?/, "")
+                .trim();
+            return `> **Skip if:**\n> ${body.replace(/\n/g, "\n> ")}`;
+        }
+        catch {
+            return `> **Skip if:** ${skip}`;
+        }
     }
 }

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

@@ -26,7 +26,7 @@ export declare class RagTableGenerator extends CodeGenerator {
     generateCode: (codeConfig: CodeGeneratorProps) => Promise<void>;
     /** Collects rows and returns structured JSON for one action. */
     private buildActionJson;
-    buildActionMarkdown(action: string, codeName: string, testArray: TestObject[]): string;
+    buildActionMarkdown(action: string, codeName: string, testArray: TestObject[], codeConfig: CodeGeneratorProps): string;
     /**
      * Walks the test tree depth-first.
      *
@@ -45,6 +45,12 @@ export declare class RagTableGenerator extends CodeGenerator {
      * - `Scope`, `Skip If`, `Error Code`, `Success Code` similarly pruned
      */
     private renderTable;
+    /**
+     * Compiles a JVAL skip expression to plain text suitable for a table cell.
+     * Uses CompileToMarkdownForSkip (not CompileToMarkdown) so the output
+     * correctly renders conditional/negation skip logic.
+     */
+    private compileSkipToText;
     /**
      * Sanitises a string for safe use inside a GFM table cell:
      * - Collapses newlines and excess whitespace to a single space

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

@@ -2,6 +2,10 @@ 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 { ConvertArrayToStringsInTestObject } from "../../../utils/general-utils/string-utils.js";
+import Mustache from "mustache";
 /**
  * RagTableGenerator — produces one Markdown **table** file per API action
  * under `./rag-table-docs/`.
@@ -33,7 +37,7 @@ export class RagTableGenerator extends CodeGenerator {
             const rawJson = {};
             for (const action of Object.keys(testConfig)) {
                 const testArray = testConfig[action];
-                const md = this.buildActionMarkdown(action, codeName, testArray);
+                const md = this.buildActionMarkdown(action, codeName, testArray, codeConfig);
                 writeFileWithFsExtra(this.rootPath, `./rag-table-docs/${action}.md`, md);
                 rawJson[action] = this.buildActionJson(action, codeName, testArray);
             }
@@ -62,18 +66,23 @@ export class RagTableGenerator extends CodeGenerator {
             rows: rows.map(({ index: _idx, ...rest }) => rest),
         };
     }
-    buildActionMarkdown(action, codeName, testArray) {
+    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;
@@ -81,6 +90,7 @@ export class RagTableGenerator extends CodeGenerator {
             `# ${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.`,
             "",
             "---",
@@ -120,9 +130,7 @@ export class RagTableGenerator extends CodeGenerator {
                 let skipText = "";
                 if (ownSkip) {
                     try {
-                        skipText = markdownMessageGenerator(ownSkip, test, name, undefined)
-                            .replace(/^#{1,6}\s+\*\*[^*]+\*\*\s*\n\n?/, "")
-                            .trim();
+                        skipText = this.compileSkipToText(ownSkip, test);
                     }
                     catch {
                         skipText = ownSkip;
@@ -148,9 +156,7 @@ export class RagTableGenerator extends CodeGenerator {
                 let skipText = "";
                 if (ownSkip) {
                     try {
-                        skipText = markdownMessageGenerator(ownSkip, test, name, undefined)
-                            .replace(/^#{1,6}\s+\*\*[^*]+\*\*\s*\n\n?/, "")
-                            .trim();
+                        skipText = this.compileSkipToText(ownSkip, test);
                     }
                     catch {
                         skipText = ownSkip;
@@ -247,6 +253,16 @@ export class RagTableGenerator extends CodeGenerator {
         const dataRows = rows.map((r) => `| ${cols.map((c) => c.value(r) || "—").join(" | ")} |`);
         return [headerRow, sepRow, ...dataRows].join("\n");
     }
+    /**
+     * Compiles a JVAL skip expression to plain text suitable for a table cell.
+     * Uses CompileToMarkdownForSkip (not CompileToMarkdown) so the output
+     * correctly renders conditional/negation skip logic.
+     */
+    compileSkipToText(skipExpr, test) {
+        const skAst = buildAstFromInput(skipExpr);
+        const skBlock = CompileToMarkdownForSkip(skAst, false, 2, false);
+        return Mustache.render(skBlock, ConvertArrayToStringsInTestObject(test));
+    }
     /**
      * Sanitises a string for safe use inside a GFM table cell:
      * - Collapses newlines and excess whitespace to a single space

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/package.json

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