docspec 0.1.0 → 0.3.0

package/dist/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAYA,sDAKC;AAMD,sDASC;AAKD,sCAKC;AA1CD,2CAA6B;AAE7B,MAAM,WAAW,GAAG,UAAU,CAAC;AAC/B,MAAM,WAAW,GAAG,aAAa,CAAC;AAClC,MAAM,MAAM,GAAG,KAAK,CAAC;AAErB;;;;;GAKG;AACH,SAAgB,qBAAqB,CAAC,MAAc;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IAClF,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChF,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,WAAW,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,WAAmB;IACvD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACnE,MAAM,aAAa,GAAG,UAAU,CAAC,UAAU,CAAC,WAAW,GAAG,GAAG,CAAC;QAC5D,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,WAAW,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC;QAC9C,CAAC,CAAC,UAAU,CAAC;IACf,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACzC,OAAO,UAAU,CAAC,CAAC,mCAAmC;IACxD,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAC9D,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,QAAgB;IAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAChE,OAAO,CACL,UAAU,CAAC,UAAU,CAAC,WAAW,GAAG,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,CAC7E,CAAC;AACJ,CAAC"}

package/dist/template.d.ts

@@ -0,0 +1,20 @@
+interface ParsedSection {
+    name: string;
+    boilerplate: string;
+    number: number;
+}
+export interface ParsedFormat {
+    sections: ParsedSection[];
+    template: string;
+    agentInstructions?: string;
+}
+/**
+ * Parse the docspec template file (.docspec/docspec.md) into structure and sections.
+ */
+export declare function parseFormatFile(formatFilePath: string): ParsedFormat;
+/**
+ * Path to the template file (.docspec/docspec.md). Seeds from bundled default if missing.
+ */
+export declare function getFormatFilePath(): string;
+export {};
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAGA,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,CAGpE;AA4GD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C"}

package/dist/template.js

@@ -0,0 +1,151 @@
+"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 });
+exports.parseFormatFile = parseFormatFile;
+exports.getFormatFilePath = getFormatFilePath;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Parse the docspec template file (.docspec/docspec.md) into structure and sections.
+ */
+function parseFormatFile(formatFilePath) {
+    const content = fs.readFileSync(formatFilePath, "utf-8");
+    return parseFormatContent(content);
+}
+function parseFormatContent(content) {
+    const lines = content.split("\n");
+    // Look for AGENT INSTRUCTIONS section first
+    let agentInstructions;
+    let agentInstructionsStart = -1;
+    let agentInstructionsEnd = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === "## AGENT INSTRUCTIONS") {
+            agentInstructionsStart = i;
+            break;
+        }
+    }
+    if (agentInstructionsStart >= 0) {
+        for (let i = agentInstructionsStart + 1; i < lines.length; i++) {
+            const trimmedLine = lines[i].trim();
+            if (trimmedLine.match(/^##\s+/)) {
+                agentInstructionsEnd = i;
+                break;
+            }
+        }
+        if (agentInstructionsEnd < 0)
+            agentInstructionsEnd = lines.length;
+        const agentLines = lines.slice(agentInstructionsStart + 1, agentInstructionsEnd);
+        let agentContent = agentLines.join("\n");
+        agentContent = agentContent
+            .split("\n")
+            .filter((line) => line.trim() !== "---")
+            .join("\n")
+            .trim();
+        if (agentContent)
+            agentInstructions = agentContent;
+    }
+    // Find all section headers: ## N. Section Name
+    const sectionHeaderRegex = /^##\s+(\d+)\.\s+(.+)$/;
+    const sectionHeaders = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === "## AGENT INSTRUCTIONS")
+            continue;
+        const match = lines[i].match(sectionHeaderRegex);
+        if (match) {
+            sectionHeaders.push({
+                lineIndex: i,
+                number: parseInt(match[1], 10),
+                name: match[2].trim(),
+            });
+        }
+    }
+    if (sectionHeaders.length === 0) {
+        throw new Error("No section headers found in template. Expected format: ## N. Section Name");
+    }
+    const firstSectionLine = sectionHeaders[0].lineIndex;
+    const templateBeforeSections = agentInstructionsStart >= 0 && agentInstructionsStart < firstSectionLine
+        ? lines.slice(0, agentInstructionsStart).join("\n").trim()
+        : lines.slice(0, firstSectionLine).join("\n").trim();
+    const template = templateBeforeSections + "\n\n{{AGENT_INSTRUCTIONS}}\n\n{{SECTIONS}}\n";
+    const sections = [];
+    for (let i = 0; i < sectionHeaders.length; i++) {
+        const header = sectionHeaders[i];
+        const nextHeaderLine = i < sectionHeaders.length - 1 ? sectionHeaders[i + 1].lineIndex : lines.length;
+        const sectionLines = lines.slice(header.lineIndex + 1, nextHeaderLine);
+        let sectionContent = sectionLines.join("\n");
+        sectionContent = sectionContent
+            .split("\n")
+            .filter((line) => line.trim() !== "---")
+            .join("\n")
+            .trim();
+        sections.push({
+            name: header.name,
+            boilerplate: sectionContent,
+            number: header.number,
+        });
+    }
+    sections.sort((a, b) => a.number - b.number);
+    return {
+        sections,
+        template,
+        agentInstructions,
+    };
+}
+/**
+ * Seed .docspec/docspec.md from the bundled docspec-format.md if it doesn't exist.
+ */
+function seedDefaultFormatFile() {
+    const cwd = process.cwd();
+    const userPath = path.join(cwd, ".docspec", "docspec.md");
+    const defaultPath = path.join(__dirname, "..", "docspec-format.md");
+    if (!fs.existsSync(defaultPath)) {
+        throw new Error(`Default template not found at ${defaultPath}. ` +
+            `Create .docspec/docspec.md in your project or ensure the docspec package is installed correctly.`);
+    }
+    fs.mkdirSync(path.join(cwd, ".docspec"), { recursive: true });
+    fs.copyFileSync(defaultPath, userPath);
+    return userPath;
+}
+/**
+ * Path to the template file (.docspec/docspec.md). Seeds from bundled default if missing.
+ */
+function getFormatFilePath() {
+    const cwd = process.cwd();
+    const userPath = path.join(cwd, ".docspec", "docspec.md");
+    if (fs.existsSync(userPath))
+        return userPath;
+    return seedDefaultFormatFile();
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

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

package/dist/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAkB,MAAM,SAAS,CAAC;AAG3D;;;GAGG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+CjF"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAkB,MAAM,SAAS,CAAC;AAI3D;;;GAGG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmEjF"}

package/dist/validator.js

@@ -36,41 +36,61 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateDocspec = validateDocspec;
 const fs = __importStar(require("fs/promises"));
 const constants_1 = require("./constants");
+const logger_1 = require("./logger");
 /**
  * Validate a docspec file
  * @param filePath Path to the docspec file to validate
  */
 async function validateDocspec(filePath) {
     const errors = [];
+    logger_1.logger.debug(`Reading file: ${filePath}`);
     try {
         const content = await fs.readFile(filePath, "utf-8");
+        logger_1.logger.debug(`File read successfully, ${content.length} characters`);
+        logger_1.logger.debug("Parsing sections from content");
         const sections = parseSections(content);
+        logger_1.logger.debug(`Found ${sections.length} section(s)`);
         // Check for all required sections
         const foundSections = new Set();
         for (const section of sections) {
             foundSections.add(section.name);
+            logger_1.logger.debug(`Found section: "${section.name}" (line ${section.lineNumber})`);
         }
+        logger_1.logger.debug(`Checking for ${constants_1.REQUIRED_SECTIONS.length} required section(s)`);
         // Check for missing sections
         for (const requiredSection of constants_1.REQUIRED_SECTIONS) {
             if (!foundSections.has(requiredSection)) {
+                logger_1.logger.debug(`Missing required section: "${requiredSection}"`);
                 errors.push(`Missing required section: "${requiredSection}"`);
             }
+            else {
+                logger_1.logger.debug(`✓ Required section found: "${requiredSection}"`);
+            }
         }
         // Validate each section's content
+        logger_1.logger.debug("Validating section content");
         for (const section of sections) {
             if (constants_1.REQUIRED_SECTIONS.includes(section.name)) {
+                logger_1.logger.debug(`Validating content for section: "${section.name}"`);
                 const validationError = validateSectionContent(section);
                 if (validationError) {
+                    logger_1.logger.debug(`Validation error for "${section.name}": ${validationError}`);
                     errors.push(validationError);
                 }
+                else {
+                    logger_1.logger.debug(`✓ Section "${section.name}" content is valid`);
+                }
             }
         }
+        const isValid = errors.length === 0;
+        logger_1.logger.debug(`Validation ${isValid ? "passed" : "failed"} with ${errors.length} error(s)`);
         return {
-            valid: errors.length === 0,
+            valid: isValid,
             errors,
         };
     }
     catch (error) {
+        logger_1.logger.debug(`Error reading file: ${error instanceof Error ? error.message : String(error)}`);
         if (error instanceof Error) {
             return {
                 valid: false,
@@ -89,6 +109,7 @@ async function validateDocspec(filePath) {
 function parseSections(content) {
     const sections = [];
     const lines = content.split("\n");
+    logger_1.logger.debug(`Parsing ${lines.length} lines for sections`);
     let currentSection = null;
     let lineNumber = 1;
     for (let i = 0; i < lines.length; i++) {
@@ -99,12 +120,20 @@ function parseSections(content) {
         if (headerMatch) {
             // Save previous section if exists
             if (currentSection) {
+                logger_1.logger.debug(`Closing section "${currentSection.name}" with ${currentSection.content.length} characters`);
                 sections.push(currentSection);
             }
             // Extract section name (remove section number if present)
             let sectionName = headerMatch[1].trim();
+            // Skip AGENT INSTRUCTIONS section - don't validate it
+            if (sectionName === "AGENT INSTRUCTIONS") {
+                logger_1.logger.debug("Skipping AGENT INSTRUCTIONS section");
+                currentSection = null;
+                continue;
+            }
             // Remove leading number and period (e.g., "1. Purpose" -> "Purpose")
             sectionName = sectionName.replace(/^\d+\.\s*/, "");
+            logger_1.logger.debug(`Found section header: "${sectionName}" at line ${i + 1}`);
             currentSection = {
                 name: sectionName,
                 content: "",
@@ -122,6 +151,7 @@ function parseSections(content) {
     }
     // Add the last section
     if (currentSection) {
+        logger_1.logger.debug(`Closing final section "${currentSection.name}" with ${currentSection.content.length} characters`);
         sections.push(currentSection);
     }
     return sections;
@@ -132,8 +162,10 @@ function parseSections(content) {
 function validateSectionContent(section) {
     const boilerplate = constants_1.SECTION_BOILERPLATE[section.name];
     if (!boilerplate) {
+        logger_1.logger.debug(`No boilerplate found for section "${section.name}", skipping content validation`);
         return null; // Not a required section, skip validation
     }
+    logger_1.logger.debug(`Validating content for "${section.name}" (boilerplate length: ${boilerplate.length})`);
     // Clean content: remove separator lines (---) and trim
     let content = section.content
         .split("\n")
@@ -141,24 +173,30 @@ function validateSectionContent(section) {
         .join("\n")
         .trim();
     const boilerplateTrimmed = boilerplate.trim();
+    logger_1.logger.debug(`Section content length: ${content.length} characters`);
     // Check if content is empty
     if (!content) {
+        logger_1.logger.debug(`Section "${section.name}" is empty`);
         return `Section "${section.name}" (line ${section.lineNumber}) is empty`;
     }
     // Check if content matches boilerplate exactly
     if (content === boilerplateTrimmed) {
+        logger_1.logger.debug(`Section "${section.name}" matches boilerplate exactly`);
         return `Section "${section.name}" (line ${section.lineNumber}) contains only boilerplate text and has not been customized`;
     }
     // Check if content is too similar to boilerplate (only whitespace differences)
     const normalizedContent = normalizeWhitespace(content);
     const normalizedBoilerplate = normalizeWhitespace(boilerplateTrimmed);
     if (normalizedContent === normalizedBoilerplate) {
+        logger_1.logger.debug(`Section "${section.name}" is too similar to boilerplate (only whitespace differences)`);
         return `Section "${section.name}" (line ${section.lineNumber}) is too similar to boilerplate (only whitespace differences)`;
     }
     // Check if content is just a subset of boilerplate (very short)
     if (content.length < 50) {
+        logger_1.logger.debug(`Section "${section.name}" is too short (${content.length} < 50 characters)`);
         return `Section "${section.name}" (line ${section.lineNumber}) appears to be incomplete (too short)`;
     }
+    logger_1.logger.debug(`Section "${section.name}" content validation passed`);
     return null;
 }
 /**

package/dist/validator.js.map

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

package/docspec-format.md

@@ -0,0 +1,45 @@
+# DOCSPEC: [{{TARGET_FILE}}](/{{TARGET_FILE}})
+
+> A specification that defines how the target document should be maintained by agents.
+
+## AGENT INSTRUCTIONS
+
+**Target document:** `{{TARGET_FILE}}`
+
+**Your task:**
+
+* Compare the target document against this docspec.  
+* Update the target document to satisfy this docspec.  
+* Make the smallest changes necessary.  
+* Preserve existing content that already complies.  
+* Do not invent content, sections, or facts not implied by this docspec or the repository.
+
+## 1. Document Purpose
+
+What this document exists to explain or enable.  
+What questions it must reliably answer.  
+What kind of doc it is (overview, agent guide, spec, tutorial, etc.).
+
+## 2. Update Triggers
+
+What kinds of changes should cause this document to be updated.  
+Describe in terms of detectable changes (structure, APIs, workflows, behavior).  
+Also note changes that **should not** trigger updates.
+
+## 3. Expected Structure
+
+The sections this document should contain.  
+For each section: what it covers at a high level and any constraints
+(e.g., "high-level only", "no exhaustive lists", "link out instead of duplicating").
+
+## 4. Editing Guidelines
+
+How edits to this document should be made.  
+Local rules for tone, level of detail, and scope.  
+Explicit do/don't guidance to avoid drift, speculation, or redundancy.
+
+## 5. Intentional Omissions
+
+What this document deliberately does not cover.  
+Where that information lives instead, if applicable.
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docspec",
-  "version": "0.1.0",
-  "description": "Generate and validate docspec files (*.docspec.md) with standardized format",
+  "version": "0.3.0",
+  "description": "Docspec is a specification format and toolchain for documentation that is maintained by agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -23,7 +23,8 @@
   "license": "MIT",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docspec-format.md"
   ],
   "devDependencies": {
     "@types/jest": "^30.0.0",