docspec 0.1.0

package/dist/__tests__/validator.test.js

@@ -0,0 +1,375 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const validator_1 = require("../validator");
+const generator_1 = require("../generator");
+const constants_1 = require("../constants");
+describe("validator", () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "docspec-test-"));
+    });
+    afterEach(async () => {
+        await fs.rm(tempDir, { recursive: true, force: true });
+    });
+    describe("validateDocspec", () => {
+        it("should validate a properly customized docspec file", async () => {
+            const filePath = path.join(tempDir, "valid.docspec.md");
+            // Create a valid docspec with customized content
+            const validContent = `---
+
+# DOCSPEC: Test Document
+
+> Short phrase: *Test document*
+
+---
+
+## 1. Purpose of This Document
+
+This document describes the test suite for the docspec validator. It provides comprehensive test coverage for all validation scenarios and edge cases that the validator needs to handle correctly.
+
+## 2. When This Document Should Be Updated
+
+Update this document when adding new test cases or when the validation logic changes. It should always reflect the current state of the test suite.
+
+## 3. Structure & Required Sections
+
+This section describes the test structure and how tests are organized. Each test file covers a specific module or functionality area of the docspec package.
+
+## 4. Style & Editing Guidelines
+
+Keep test descriptions clear and concise. Use descriptive test names that explain what is being tested. Follow the AAA pattern: Arrange, Act, Assert. Do: Write comprehensive tests that cover edge cases. Don't: Skip edge cases or write tests that are too simple. Always test both success and failure scenarios.
+
+## 5. Known Gaps or Intentional Omissions
+
+No gaps at this time. All major functionality is covered by the test suite.
+`;
+            await fs.writeFile(filePath, validContent, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(true);
+            expect(result.errors).toHaveLength(0);
+        });
+        it("should reject a file with only boilerplate content", async () => {
+            const filePath = path.join(tempDir, "boilerplate.docspec.md");
+            await (0, generator_1.generateDocspec)(filePath, "Test");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(false);
+            expect(result.errors.length).toBeGreaterThan(0);
+            expect(result.errors.some(e => e.includes("boilerplate"))).toBe(true);
+        });
+        it("should detect missing sections", async () => {
+            const filePath = path.join(tempDir, "incomplete.docspec.md");
+            const incompleteContent = `---
+
+# DOCSPEC: Test
+
+---
+
+## 1. Purpose of This Document
+
+Custom content here.
+
+## 2. When This Document Should Be Updated
+
+More custom content.
+`;
+            await fs.writeFile(filePath, incompleteContent, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(false);
+            // Should have errors for missing sections
+            expect(result.errors.some(e => e.includes("Missing required section"))).toBe(true);
+        });
+        it("should detect empty sections", async () => {
+            const filePath = path.join(tempDir, "empty-section.docspec.md");
+            let content = `---
+
+# DOCSPEC: Test
+
+---
+
+`;
+            // Add all sections but leave one empty
+            constants_1.REQUIRED_SECTIONS.forEach((section, index) => {
+                content += `## ${index + 1}. ${section}\n\n`;
+                if (index === 2) {
+                    // Leave section 3 empty
+                    content += "\n";
+                }
+                else {
+                    content += "Custom content for this section.\n";
+                }
+                content += "\n---\n\n";
+            });
+            await fs.writeFile(filePath, content, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes("empty"))).toBe(true);
+        });
+        it("should handle files with section numbers in headers", async () => {
+            const filePath = path.join(tempDir, "numbered.docspec.md");
+            const content = `---
+
+# DOCSPEC: Test
+
+---
+
+## 1. Purpose of This Document
+
+This document serves as a test case for validating docspec files with numbered section headers. It contains custom content that is different from the boilerplate template.
+
+## 2. When This Document Should Be Updated
+
+This document should be updated whenever the validation logic for numbered headers changes. It tests the parser's ability to handle section numbers correctly.
+
+## 3. Structure & Required Sections
+
+This section describes the structure of the test document. It includes all required sections with sufficient content to pass validation checks.
+
+## 4. Style & Editing Guidelines
+
+The style for this test document is straightforward and technical. It focuses on clarity and precision in describing test scenarios. Do: Ensure all sections have adequate content. Don't: Use boilerplate text or leave sections empty. Always provide meaningful test data.
+
+## 5. Known Gaps or Intentional Omissions
+
+There are no known gaps in this test document. All sections are complete and properly formatted.
+`;
+            await fs.writeFile(filePath, content, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(true);
+        });
+        it("should handle files without section numbers in headers", async () => {
+            const filePath = path.join(tempDir, "unnumbered.docspec.md");
+            const content = `---
+
+# DOCSPEC: Test
+
+---
+
+## Purpose of This Document
+
+This document serves as a test case for validating docspec files without numbered section headers. It contains custom content that differs from the boilerplate template.
+
+## When This Document Should Be Updated
+
+This document should be updated whenever the validation logic for unnumbered headers changes. It tests the parser's flexibility in handling different header formats.
+
+## Structure & Required Sections
+
+This section describes the structure of the test document. It includes all required sections with sufficient content to pass validation checks.
+
+## Style & Editing Guidelines
+
+The style for this test document is straightforward and technical. It focuses on clarity and precision in describing test scenarios. Do: Ensure all sections have adequate content. Don't: Use boilerplate text or leave sections empty. Always provide meaningful test data.
+
+## Known Gaps or Intentional Omissions
+
+There are no known gaps in this test document. All sections are complete and properly formatted.
+`;
+            await fs.writeFile(filePath, content, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(true);
+        });
+        it("should ignore separator lines (---) when validating content", async () => {
+            const filePath = path.join(tempDir, "with-separators.docspec.md");
+            const content = `---
+
+# DOCSPEC: Test
+
+---
+
+## 1. Purpose of This Document
+
+This document tests the validator's ability to handle separator lines between sections. The content here is custom and different from boilerplate.
+
+---
+
+## 2. When This Document Should Be Updated
+
+This document should be updated when testing separator line handling. The content is sufficient to pass validation.
+
+---
+
+## 3. Structure & Required Sections
+
+This section describes the document structure. It includes all required sections with adequate content length.
+
+---
+
+## 4. Style & Editing Guidelines
+
+The style rules for this test document are straightforward. Content is technical and precise. Do: Test separator handling. Don't: Skip validation of separator lines. Ensure content is meaningful.
+
+---
+
+## 5. Known Gaps or Intentional Omissions
+
+No gaps in this test document. All sections are complete with sufficient content.
+`;
+            await fs.writeFile(filePath, content, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            // Should be valid even with separators
+            expect(result.valid).toBe(true);
+        });
+        it("should reject content that only differs by whitespace from boilerplate", async () => {
+            const filePath = path.join(tempDir, "whitespace-only.docspec.md");
+            let content = `---
+
+# DOCSPEC: Test
+
+---
+
+`;
+            // Create content that's just boilerplate with different whitespace
+            constants_1.REQUIRED_SECTIONS.forEach((section, index) => {
+                content += `## ${index + 1}. ${section}\n\n`;
+                // Use boilerplate but with extra spaces
+                const boilerplate = constants_1.SECTION_BOILERPLATE[section];
+                content += boilerplate.replace(/\n/g, "  \n") + "\n";
+                content += "\n---\n\n";
+            });
+            await fs.writeFile(filePath, content, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes("too similar to boilerplate"))).toBe(true);
+        });
+        it("should reject sections that are too short", async () => {
+            const filePath = path.join(tempDir, "short-section.docspec.md");
+            let content = `---
+
+# DOCSPEC: Test
+
+---
+
+`;
+            constants_1.REQUIRED_SECTIONS.forEach((section, index) => {
+                content += `## ${index + 1}. ${section}\n\n`;
+                if (index === 0) {
+                    // Make first section too short
+                    content += "Short.\n";
+                }
+                else {
+                    content += "This is a longer section with enough content to pass validation.\n";
+                }
+                content += "\n---\n\n";
+            });
+            await fs.writeFile(filePath, content, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes("too short") || e.includes("incomplete"))).toBe(true);
+        });
+        it("should handle non-existent files gracefully", async () => {
+            const filePath = path.join(tempDir, "nonexistent.docspec.md");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            expect(result.valid).toBe(false);
+            expect(result.errors.length).toBeGreaterThan(0);
+            expect(result.errors[0]).toContain("Failed to read file");
+        });
+        it("should handle files with extra sections (non-required)", async () => {
+            const filePath = path.join(tempDir, "extra-sections.docspec.md");
+            const content = `---
+
+# DOCSPEC: Test
+
+---
+
+## 1. Purpose of This Document
+
+This document tests the validator's handling of extra sections beyond the required ones. The content is custom and sufficient to pass validation.
+
+## 2. When This Document Should Be Updated
+
+This document should be updated when testing extra section handling. The content is meaningful and not boilerplate.
+
+## 3. Structure & Required Sections
+
+This section describes the document structure including both required and optional sections. All content is customized.
+
+## 4. Style & Editing Guidelines
+
+The style rules for this test document are clear and technical. Content is sufficient in length. Do: Test extra sections. Don't: Reject valid documents with additional sections. Ensure all required sections are present.
+
+## 5. Known Gaps or Intentional Omissions
+
+No gaps in this test document. All sections are complete with adequate content.
+
+## 7. Additional Section
+
+This is an extra section that shouldn't cause validation to fail. It contains additional information beyond the required sections.
+`;
+            await fs.writeFile(filePath, content, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            // Extra sections should be allowed
+            expect(result.valid).toBe(true);
+        });
+        it("should handle case-insensitive section matching", async () => {
+            const filePath = path.join(tempDir, "case-test.docspec.md");
+            const content = `---
+
+# DOCSPEC: Test
+
+---
+
+## 1. PURPOSE OF THIS DOCUMENT
+
+Custom content.
+
+## 2. when this document should be updated
+
+Custom content.
+
+## 3. Structure & Required Sections
+
+Custom content.
+
+## 4. Style & Editing Guidelines
+
+Custom style and editing guidelines content.
+
+## 5. Known Gaps or Intentional Omissions
+
+Custom gaps content.
+`;
+            await fs.writeFile(filePath, content, "utf-8");
+            const result = await (0, validator_1.validateDocspec)(filePath);
+            // Currently the validator is case-sensitive, so this will fail
+            // This test documents current behavior - could be enhanced later
+            expect(result.valid).toBe(false);
+        });
+    });
+});
+//# sourceMappingURL=validator.test.js.map

package/dist/__tests__/validator.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.test.js","sourceRoot":"","sources":["../../src/__tests__/validator.test.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const validator_1 = require("./validator");
+const generator_1 = require("./generator");
+const program = new commander_1.Command();
+program
+    .name("docspec")
+    .description("Generate and validate docspec files (*.docspec.md)")
+    .version("0.1.0");
+program
+    .command("validate")
+    .description("Validate docspec files")
+    .argument("[paths...]", "Paths to docspec files (if not provided, finds all *.docspec.md files)")
+    .action(async (filePaths) => {
+    let filesToValidate = [];
+    if (filePaths.length > 0) {
+        // Use provided file paths (from pre-commit or user)
+        filesToValidate = filePaths;
+    }
+    else {
+        // Find all *.docspec.md files in current directory tree
+        filesToValidate = await findDocspecFiles(process.cwd());
+    }
+    if (filesToValidate.length === 0) {
+        console.log("No docspec files found to validate.");
+        process.exit(0);
+    }
+    let hasErrors = false;
+    for (const filePath of filesToValidate) {
+        const result = await (0, validator_1.validateDocspec)(filePath);
+        if (!result.valid) {
+            hasErrors = true;
+            console.error(`\n❌ ${filePath}:`);
+            for (const error of result.errors) {
+                console.error(`  - ${error}`);
+            }
+        }
+        else {
+            console.log(`✅ ${filePath}`);
+        }
+    }
+    if (hasErrors) {
+        process.exit(1);
+    }
+});
+program
+    .command("generate")
+    .description("Generate a new docspec file")
+    .argument("<path>", "Path where the docspec file should be created")
+    .option("-n, --name <name>", "Name of the document (defaults to filename)")
+    .action(async (filePath, options) => {
+    try {
+        // Ensure the path ends with .docspec.md
+        if (!filePath.endsWith(".docspec.md")) {
+            filePath = filePath + ".docspec.md";
+        }
+        await (0, generator_1.generateDocspec)(filePath, options.name);
+        console.log(`✅ Generated docspec file: ${filePath}`);
+    }
+    catch (error) {
+        console.error(`❌ Failed to generate docspec file: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});
+// Parse command line arguments
+program.parse();
+/**
+ * Recursively find all *.docspec.md files in a directory
+ */
+async function findDocspecFiles(dir) {
+    const files = [];
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            // Skip node_modules and .git directories
+            if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                const subFiles = await findDocspecFiles(fullPath);
+                files.push(...subFiles);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".docspec.md")) {
+                files.push(fullPath);
+            }
+        }
+    }
+    catch (error) {
+        // Ignore permission errors
+        if (error instanceof Error && "code" in error && error.code !== "EACCES") {
+            throw error;
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Required section headers for docspec files
+ */
+export declare const REQUIRED_SECTIONS: readonly ["Purpose of This Document", "When This Document Should Be Updated", "Structure & Required Sections", "Style & Editing Guidelines", "Known Gaps or Intentional Omissions"];
+/**
+ * Boilerplate template text for each section
+ */
+export declare const SECTION_BOILERPLATE: Record<string, string>;
+/**
+ * Generate the full docspec template
+ */
+export declare function getDocspecTemplate(name: string): string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,iBAAiB,qLAMpB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoBtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiBvD"}

package/dist/constants.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECTION_BOILERPLATE = exports.REQUIRED_SECTIONS = void 0;
+exports.getDocspecTemplate = getDocspecTemplate;
+/**
+ * Required section headers for docspec files
+ */
+exports.REQUIRED_SECTIONS = [
+    "Purpose of This Document",
+    "When This Document Should Be Updated",
+    "Structure & Required Sections",
+    "Style & Editing Guidelines",
+    "Known Gaps or Intentional Omissions",
+];
+/**
+ * Boilerplate template text for each section
+ */
+exports.SECTION_BOILERPLATE = {
+    "Purpose of This Document": `Explain **what this Markdown file is supposed to achieve**, not what it currently contains.
+
+What questions should this document always be able to answer? What *kind* of document is it (overview, spec, tutorial, ops runbook, etc.)?`,
+    "When This Document Should Be Updated": `Describe **triggers** based on code changes.
+
+Write as concrete rules that can be checked against a diff. Examples: "If new subdirectories are added, update the contents section" or "If public APIs change, update the interaction section."`,
+    "Structure & Required Sections": `Describe the **expected sections** and what belongs in each, without restating the actual content.
+
+For each section, specify: its name/role, what it should cover (conceptual, not literal), and any constraints (e.g., "Keep high-level; don't enumerate every file").`,
+    "Style & Editing Guidelines": `Rules **specific to this doc or directory**, not global writing rules.
+
+Include both style preferences (e.g., "Use non-technical language" or "Prefer bullet lists") and concrete editing guidelines (e.g., "Do: Update examples when APIs change" or "Don't: Remove placeholder sections").`,
+    "Known Gaps or Intentional Omissions": `Note things that **should not be documented yet** or are deliberately vague.
+
+Examples: "Auth design is intentionally not detailed here; see \`/security/README.md\`" or "This doc avoids internal business logic; keep it conceptual."`,
+};
+/**
+ * Generate the full docspec template
+ */
+function getDocspecTemplate(name) {
+    const sections = exports.REQUIRED_SECTIONS.map((sectionName, index) => {
+        const sectionNumber = index + 1;
+        const boilerplate = exports.SECTION_BOILERPLATE[sectionName];
+        return `## ${sectionNumber}. ${sectionName}\n\n${boilerplate}`;
+    }).join("\n\n---\n\n");
+    return `---
+
+# DOCSPEC: ${name}
+
+> Short phrase: *What this doc is for* (e.g. "Overview of this directory's purpose and structure.")
+
+---
+
+${sections}
+`;
+}
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAuCA,gDAiBC;AAxDD;;GAEG;AACU,QAAA,iBAAiB,GAAG;IAC/B,0BAA0B;IAC1B,sCAAsC;IACtC,+BAA+B;IAC/B,4BAA4B;IAC5B,qCAAqC;CAC7B,CAAC;AAEX;;GAEG;AACU,QAAA,mBAAmB,GAA2B;IACzD,0BAA0B,EAAE;;2IAE6G;IAEzI,sCAAsC,EAAE;;iMAEuJ;IAE/L,+BAA+B,EAAE;;qKAEkI;IAEnK,4BAA4B,EAAE;;qNAEqL;IAEnN,qCAAqC,EAAE;;0JAEiH;CACzJ,CAAC;AAEF;;GAEG;AACH,SAAgB,kBAAkB,CAAC,IAAY;IAC7C,MAAM,QAAQ,GAAG,yBAAiB,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE;QAC5D,MAAM,aAAa,GAAG,KAAK,GAAG,CAAC,CAAC;QAChC,MAAM,WAAW,GAAG,2BAAmB,CAAC,WAAW,CAAC,CAAC;QACrD,OAAO,MAAM,aAAa,KAAK,WAAW,OAAO,WAAW,EAAE,CAAC;IACjE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAEvB,OAAO;;aAEI,IAAI;;;;;;EAMf,QAAQ;CACT,CAAC;AACF,CAAC"}

package/dist/generator.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generate a new docspec file at the specified path
+ * @param filePath Path where the docspec file should be created
+ * @param name Name of the document (used in the header)
+ */
+export declare function generateDocspec(filePath: string, name?: string): Promise<void>;
+/**
+ * Generate docspec content as a string (for library use)
+ * @param name Name of the document
+ */
+export declare function generateDocspecContent(name: string): string;
+//# sourceMappingURL=generator.d.ts.map

package/dist/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAepF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D"}