@popoverai/dotrequirements 0.23.0 → 0.24.1

package/dist/requirements/style-guide.js

@@ -0,0 +1,299 @@
+/**
+ * Style-guide template generator. Produces the markdown document that both
+ * the MCP `create_requirement_document` tool and the CLI
+ * `dotreq create-requirement-document` verb return.
+ *
+ * The output is a full ready-to-paste-into-a-PR markdown document that
+ * describes the requirements format, embeds a worked example, and includes
+ * style principles for writing requirements and tests. Discovered label /
+ * key patterns from the calling workspace and (optional) project-owner-
+ * supplied custom guidance are interpolated into the body.
+ *
+ * If the project has a `.requirements/STYLE.md`, callers can pass its
+ * contents via `localStyleGuide` to use that body in place of the bundled
+ * defaults. See {@link readLocalStyleGuide} for the lookup helper.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Conventional location of a project's STYLE.md, relative to the workspace
+ * root. Exported so callers (init, push/pull, tests) can reference one place.
+ */
+export const STYLE_MD_PATH = ".requirements/STYLE.md";
+/**
+ * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
+ * contents on success, `null` if the file is absent. Empty / whitespace-only
+ * files are treated as absent so the bundled defaults still apply.
+ */
+export function readLocalStyleGuide(workspaceRoot) {
+    const fullPath = join(workspaceRoot, STYLE_MD_PATH);
+    if (!existsSync(fullPath)) {
+        return null;
+    }
+    const contents = readFileSync(fullPath, "utf-8");
+    return contents.trim().length > 0 ? contents : null;
+}
+/**
+ * Build the body of the bundled default style guide. This is the content
+ * that lives inside the "# Requirements File Template" preamble — the
+ * format syntax, key/label conventions, style principles, and example
+ * requirements — with discovered patterns and custom guidance interpolated.
+ *
+ * Exposed separately from {@link generateStyleGuide} so callers can:
+ * - scaffold `.requirements/STYLE.md` with the bundled defaults at init time
+ * - swap the body wholesale (via `localStyleGuide`) without losing the
+ *   wrapping preamble + "Next Steps" footer
+ */
+export function generateStyleGuideBody(params) {
+    const { requirements, customStyleGuidance } = params;
+    const labels = new Set();
+    const keyPrefixes = new Set();
+    for (const req of requirements) {
+        if (req.label?.trim()) {
+            labels.add(req.label);
+        }
+        if (req.path.length === 0 && req.id) {
+            const lastDashIndex = req.id.lastIndexOf("-");
+            if (lastDashIndex > 0) {
+                keyPrefixes.add(req.id.substring(0, lastDashIndex));
+            }
+        }
+    }
+    const discoveredLabels = Array.from(labels).sort();
+    const discoveredPrefixes = Array.from(keyPrefixes).sort();
+    let labelGuidance;
+    if (discoveredLabels.length > 0) {
+        const labelList = discoveredLabels
+            .slice(0, 10)
+            .map((l) => `"${l}"`)
+            .join(", ");
+        const more = discoveredLabels.length > 10
+            ? ` (and ${discoveredLabels.length - 10} more)`
+            : "";
+        labelGuidance = `**Existing labels in this codebase:** ${labelList}${more}
+
+**Use these existing labels** to maintain consistency. If you're unsure which labels to use for a new requirement, ask the user.`;
+    }
+    else {
+        labelGuidance = `**No existing requirements found in this codebase.**
+
+**Default to unlabeled requirements** (\`0. → content\`). If the user wants labels, ask them which format they prefer. Do not choose an opinionated framework like Given/When/Then without explicit user consent.`;
+    }
+    let keyGuidance;
+    if (discoveredPrefixes.length > 0) {
+        const prefixList = discoveredPrefixes.map((p) => `"${p}"`).join(", ");
+        keyGuidance = `**Existing requirement key prefixes in this codebase:** ${prefixList}
+
+**Match the existing pattern** when creating new requirement keys. Use the same domain prefixes and sequential numbering style.`;
+    }
+    else {
+        keyGuidance = `**No existing requirements found in this codebase.**
+
+**Use concise domain prefixes** like \`AUTH-1\`, \`LOGIN-1\`, etc. Start numbering at 1 and increment sequentially.`;
+    }
+    let userStyleGuidance = "";
+    if (customStyleGuidance?.trim()) {
+        userStyleGuidance = `
+
+## User-Provided Style Guidelines
+
+The following style guidelines were provided by the project owner. When these conflict with the defaults above, prioritize the user's guidelines.
+
+${customStyleGuidance.trim()}`;
+    }
+    const template = `---
+document:
+  title: "Example Requirements"
+---
+
+# Example Requirements
+
+This template demonstrates the dotrequirements Markdown format and style guidelines.
+
+## Syntax Overview
+
+**File naming:** Use \`*.requirements.md\` pattern (colocated: \`auth.requirements.md\` or centralized: \`.requirements/auth.requirements.md\`)
+
+**Block format:**
+\`\`\`dotrequirements
+KEY: Root requirement content
+  0. → First criterion (unlabeled)
+  1. Label → Second criterion (with label)
+    1.0. → Nested criterion (unlabeled)
+\`\`\`
+
+- First line: \`KEY: content\` (requirement key and description)
+- Criteria: \`position. Label → content\` or \`position. → content\` (unlabeled)
+- Position: \`0\`, \`1\`, \`2\` (top-level) or \`0.0\`, \`1.0\` (nested) - defines hierarchy
+- Delimiter: \`→\` or \`->\` separates optional label from content
+
+## Requirement Keys: Concise and Sequential
+
+${keyGuidance}
+
+**Key format:** \`DOMAIN-FEATURE-N\` where N is sequential (1, 2, 3...)
+
+**Best practices:**
+1. **Concise domains** - Use short, clear prefixes
+   - ✅ \`AUTHZ-1\` (authorization)
+   - ✅ \`AUTH-1\` (authentication)
+   - ❌ \`AUTHORIZATION-1\` (too verbose)
+   - ❌ \`REQ-IDENTITY-ACCESS-AUTHZ-1\` (too nested)
+
+2. **Sequential, 1-indexed numbering** - Start at 1, no padding
+   - ✅ \`LOGIN-1\`, \`LOGIN-2\`, \`LOGIN-3\`
+   - ❌ \`LOGIN-0\` (don't use 0-indexing for requirement IDs)
+   - ❌ \`LOGIN-001\` (no zero-padding)
+
+3. **Unique across project** - Each key must be unique in the entire project
+
+4. **Match existing patterns** - Check existing requirements first and follow their convention
+
+## Labels: Match Your Codebase or Ask the User
+
+${labelGuidance}
+
+## Style Principles for Requirements
+
+**1. Use Concrete Examples**: Replace vague language with specific, testable conditions.
+- ❌ "users can log in" or "works properly"
+- ✅ "When a registered user provides valid credentials, they are authenticated"
+
+**2. Write Natural, Concise Prose**: Avoid terseness and verbosity. Use declarative style (not "should").
+- ❌ "registered user with valid credentials is authenticated" (too terse)
+- ❌ "A registered user, whose account was created on Tuesday and whose life story is as follows..." (too verbose)
+- ✅ "When a registered user provides valid credentials, they are authenticated"
+
+**3. Keep Arrange/Act/Assert in Mind**: Well-written requirements describe preconditions, trigger, and result.
+- ✅ "When [preconditions:] a registered user [trigger:] provides valid credentials, [result:] they are authenticated"
+
+**4. Be Framework Neutral**: Don't prescribe Given/When/Then vs AC vs other formats - focus on content quality.
+
+**5. Use Named Personas**: Establish personas in parent requirements, reuse in children.
+- ✅ Parent: "A registered user, Jamie, can log in normally" → Child: "When Jamie provides valid credentials, they are authenticated"
+
+**6. Use User-Centric Language**: Describe user experience, not technical internals.
+- ❌ "they are redirected to app.dotrequirements.io/redirect/dashboard"
+- ✅ "they are automatically brought to the dashboard"
+
+**7. Single Action Per Requirement**: Don't chain multiple actions with "and then".
+- ❌ "When Robin provides credentials, requests an OTP, then provides the OTP..."
+- ✅ Break into separate requirements for each action
+
+**8. Each Requirement Should Be Independent**: Requirements within a block should be independently testable. If they share preconditions or form a sequence, either nest them or restate context.
+- ❌ "0. → When Jordan submits signup, an account is created" / "1. → Welcome email is sent" / "2. → Dashboard appears"
+- ✅ Option A: Restate context - "1. → When Jordan submits signup, a welcome email is sent"
+- ✅ Option B: Use nesting - "0. When → Jordan submits signup" / "  0.0. Then → an account is created"
+- Test: Can you understand what's being tested by reading just one requirement, or do you need to read its siblings?
+
+**9. Focus on Behavior, Not Design**: Describe what happens, not UI specifics.
+- ❌ "enters valid credentials into two single-line input fields and presses a green button"
+- ✅ "provides valid credentials"
+
+**10. Focus on Outcomes, Not Implementation**: User perspective, even for technical requirements.
+- ❌ "When the app requests that Twilio send Casey an OTP from /email/POST endpoint..."
+- ✅ "When Casey requests an email OTP..."
+- Note: Even technical requirements can be user-centric: "95 percent of users experience under 1 second of delay"
+
+**11. Decompose Large Requirements**: If it can't be validated with a single test, break it down.
+${userStyleGuidance}
+
+## Example Requirements
+
+**Unlabeled (recommended default):**
+\`\`\`dotrequirements
+AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
+  0. → When Jamie provides their registered email and correct password, they are authenticated and brought to their dashboard
+  1. → When Jamie provides an incorrect password, they see an error message and remain on the login page
+  2. → When Jamie's account has been deactivated, they see a message explaining their account status
+\`\`\`
+
+**With labels (example only - DO NOT use opinionated formats like Given/When/Then without asking the user first):**
+\`\`\`dotrequirements
+PAYMENT-REFUND-1: A customer, Alex, receives a refund after returning an item
+  0. Given → Alex purchased a laptop from the store 10 days ago
+  1. Given → Alex initiates a return through their order history
+  2. When → Alex's returned laptop is received and inspected at the warehouse
+  3. Then → Alex receives a refund to their original payment method within 5 business days
+  4. Then → Alex receives an email confirmation with the refund amount and expected timeline
+\`\`\`
+
+## Referencing Requirements in Tests
+
+**Use \`requirement()\` as the test description** - it returns a string:
+
+\`\`\`typescript
+import { describe, it, expect } from 'vitest';
+import { requirement } from '@popoverai/dotrequirements/test';
+
+describe(requirement('AUTH-LOGIN-1'), () => {
+  describe(requirement('AUTH-LOGIN-1.given'), () => {
+    // Arrange: Create Jamie's account
+  });
+
+  describe(requirement('AUTH-LOGIN-1.when'), () => {
+    // Act: Submit login with valid credentials
+
+    it(requirement('AUTH-LOGIN-1.then'), () => {
+      // Assert: Jamie is authenticated
+    });
+  });
+});
+\`\`\`
+
+**Test Style Principles:**
+
+**1. Use requirement() AS the description**: Don't put requirement() inside test body or in comments.
+- ✅ \`test(requirement('AUTH-LOGIN-1'), () => { /* test code */ })\`
+- ✅ \`it(requirement('LOGIN-1.then'), () => { /* assert */ })\`
+- ❌ \`test("user can log in", () => { requirement('AUTH-LOGIN-1'); /* test code */ })\`
+- ❌ \`// LOGIN-1: User can log in\` (comment instead of using requirement() as description)
+
+**2. Comments describe the TEST, not the requirement**: Don't copy requirement text verbatim.
+- ✅ \`describe(requirement('REQ-1.0'), () => { // registered user, valid credentials\`
+- ❌ \`describe(requirement('REQ-1.0'), () => { // 0. When a registered user provides valid credentials, they are authenticated\` (verbatim copy is a red flag)
+- Note: Comments should reflect what the test actually does, not just repeat what the requirement says
+
+**3. Structure tests to match requirements**: Nest describe/it blocks for structured requirements.
+- ✅ For structured requirements: \`describe(requirement('LOGIN-1.given'))\` nested with \`describe(requirement('LOGIN-1.when'))\` and \`it(requirement('LOGIN-1.then'))\`
+- ✅ For simple requirements: \`test(requirement('AUTH-LOGIN-1'), () => { /* arrange, act, assert all in one */ })\`
+
+**Path formats:**
+- \`requirement('AUTH-LOGIN-1')\` - root requirement
+- \`requirement('AUTH-LOGIN-1.0')\` - by numeric position
+- \`requirement('AUTH-LOGIN-1.given')\` - by label (case-insensitive)
+- \`requirement('AUTH-LOGIN-1.given#1')\` - disambiguate duplicate labels`;
+    return template;
+}
+/**
+ * Build a complete style-guide document for the calling workspace.
+ * Returns a single markdown string suitable for printing to stdout or
+ * wrapping in an MCP text response.
+ *
+ * When `localStyleGuide` is provided and non-empty, that content replaces
+ * the bundled default body. The preamble and "Next Steps" footer are
+ * always applied.
+ */
+export function generateStyleGuide(params) {
+    const { filePath = ".requirements/example.requirements.md", localStyleGuide, } = params;
+    const body = localStyleGuide?.trim()
+        ? localStyleGuide
+        : generateStyleGuideBody(params);
+    return `# Requirements File Template
+
+Here's a comprehensive template for \`${filePath}\` with format and style guidance:
+
+\`\`\`markdown
+${body}
+\`\`\`
+
+## Next Steps
+
+1. **Create file**: Save this template as \`${filePath}\` and edit it for your feature
+2. **Refine style** (optional): Run \`style-check\` (or call the \`style_check\` MCP tool) for AI feedback
+3. **Validate syntax**: Run \`validate\` (or call the \`validate\` MCP tool) to verify format
+4. **Push to cloud**: Run \`dotrequirements push\` (or call the \`push_requirements\` MCP tool) to sync
+
+**Note**: Requirements files can be colocated with code (\`src/auth.requirements.md\`) or centralized in \`.requirements/\` directory.`;
+}
+//# sourceMappingURL=style-guide.js.map

package/dist/{mcp → requirements}/testCodeExtractor.js

@@ -4,30 +4,32 @@
  * Finds requirement() call references and extracts the enclosing
  * meaningful code block (function, describe, test, etc.)
  */
-import { parse } from '@babel/parser';
-import traverse from '@babel/traverse';
-import * as t from '@babel/types';
-import * as fs from 'fs';
+import * as fs from "node:fs";
+import { parse } from "@babel/parser";
+import traverse from "@babel/traverse";
+import * as t from "@babel/types";
 /**
  * Find all test code blocks that reference a specific requirement
  */
 export function findTestCodeForRequirement(filePath, requirementId) {
     try {
-        const code = fs.readFileSync(filePath, 'utf-8');
+        const code = fs.readFileSync(filePath, "utf-8");
         const results = [];
         // Parse with TypeScript and JSX support
         const ast = parse(code, {
-            sourceType: 'module',
-            plugins: ['typescript', 'jsx'],
+            sourceType: "module",
+            plugins: ["typescript", "jsx"],
             errorRecovery: true,
         });
         // Handle both ES module and CommonJS exports
-        const traverseFunc = typeof traverse === 'function' ? traverse : traverse.default;
+        const traverseFunc = 
+        // biome-ignore lint/suspicious/noExplicitAny: @babel/traverse CJS default-export interop (callable function vs namespace import)
+        typeof traverse === "function" ? traverse : traverse.default;
         traverseFunc(ast, {
             CallExpression(path) {
                 // Check if this is a requirement('ID', ...) call
                 const callee = path.node.callee;
-                if (t.isIdentifier(callee) && callee.name === 'requirement') {
+                if (t.isIdentifier(callee) && callee.name === "requirement") {
                     const args = path.node.arguments;
                     // Extract all string literal arguments (supports multi-requirement calls)
                     const refIds = [];
@@ -39,12 +41,11 @@ export function findTestCodeForRequirement(filePath, requirementId) {
                     // Check if any argument matches the requirement we're looking for
                     // Match exact ID or if it's a child (e.g., searching for REQ-123 matches REQ-123.0)
                     for (const refId of refIds) {
-                        const isMatch = refId === requirementId ||
-                            refId.startsWith(`${requirementId}.`);
+                        const isMatch = refId === requirementId || refId.startsWith(`${requirementId}.`);
                         if (isMatch) {
                             // Find the meaningful enclosing block
                             const contextNode = findMeaningfulParent(path);
-                            if (contextNode && contextNode.node.loc) {
+                            if (contextNode?.node.loc) {
                                 const { start, end } = contextNode.node.loc;
                                 const nodeStart = contextNode.node.start ?? 0;
                                 const nodeEnd = contextNode.node.end ?? code.length;
@@ -91,15 +92,15 @@ function findMeaningfulParent(path) {
             const callee = node.callee;
             // Common test framework function names
             const testFunctionNames = [
-                'describe',
-                'it',
-                'test',
-                'suite',
-                'context',
-                'beforeEach',
-                'afterEach',
-                'beforeAll',
-                'afterAll',
+                "describe",
+                "it",
+                "test",
+                "suite",
+                "context",
+                "beforeEach",
+                "afterEach",
+                "beforeAll",
+                "afterAll",
             ];
             if (t.isIdentifier(callee) && testFunctionNames.includes(callee.name)) {
                 return current;
@@ -125,7 +126,7 @@ export function findFilesWithRequirement(files, requirementId) {
     const matchingFiles = [];
     for (const file of files) {
         try {
-            const code = fs.readFileSync(file, 'utf-8');
+            const code = fs.readFileSync(file, "utf-8");
             // Check for exact match or child references (e.g., AUTH-VALID-LOGIN or AUTH-VALID-LOGIN.0)
             // Simple string search first for performance
             // Patterns match both single and multi-arg calls:
@@ -142,10 +143,7 @@ export function findFilesWithRequirement(files, requirementId) {
                 matchingFiles.push(file);
             }
         }
-        catch (error) {
-            // Skip files that can't be read
-            continue;
-        }
+        catch { }
     }
     return matchingFiles;
 }

package/dist/schema/browser.d.ts

@@ -3,12 +3,12 @@
  * This file excludes Node.js-specific functionality (file I/O, fs module).
  * Use this entry point when importing from browser/web environments.
  */
-export { MetadataSchema, RequirementNodeSchema, RequirementsFileSchema, ParsedCriterionSchema, RequirementPrefixSchema, RequirementKeySchema, REQUIREMENT_PREFIX_PATTERN, REQUIREMENT_KEY_PATTERN, ValidationError, validateMetadata, validateRequirementNode, validateRequirementsFile, validatePrefix, validateKey, normalizePrefix, parseRequirementKey, buildRequirementKey, } from './schemas.js';
-export type { Metadata, RequirementNode, RequirementsFile, ParsedCriterion, RequirementPrefix, RequirementKey, } from './schemas.js';
-export { DEFAULT_DELIMITER, buildRequirementsMarkdown, buildRequirementMarkdown, } from './builder.js';
-export type { ConvexRequirement, } from './conversions.js';
-export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
-export { DELIMITER_PATTERN, parseCriterionLine, parseRootLine, parseRequirementBlock, extractRequirementBlocks, parseRequirementBlocksFromMarkdown, flattenRequirementTree, findRequirementById, getAllRequirements, } from './parser-core.js';
-export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
-export type { Scenario, ScenarioStep, ScenarioAssertionSource, BuildScenarioOptions, } from './scenario.js';
+export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER, } from "./builder.js";
+export type { ConvexRequirement } from "./conversions.js";
+export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
+export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, } from "./parser-core.js";
+export type { Metadata, ParsedCriterion, RequirementKey, RequirementNode, RequirementPrefix, RequirementsFile, } from "./schemas.js";
+export { buildRequirementKey, MetadataSchema, normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
+export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioStep, } from "./scenario.js";
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 //# sourceMappingURL=browser.d.ts.map

package/dist/schema/browser.js

@@ -3,24 +3,22 @@
  * This file excludes Node.js-specific functionality (file I/O, fs module).
  * Use this entry point when importing from browser/web environments.
  */
+// Building (uses yaml package - browser-safe)
+export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER, } from "./builder.js";
+export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
+// Parser core (pure TypeScript - browser-safe, no fs dependency)
+// These functions parse markdown strings directly without file I/O
+export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, } from "./parser-core.js";
 // Schemas and types (uses zod - browser-safe)
-export { 
+export { buildRequirementKey, 
 // Zod schemas
-MetadataSchema, RequirementNodeSchema, RequirementsFileSchema, ParsedCriterionSchema, RequirementPrefixSchema, RequirementKeySchema, 
+MetadataSchema, 
+// Prefix/key utilities
+normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, 
 // Patterns (for external validation)
-REQUIREMENT_PREFIX_PATTERN, REQUIREMENT_KEY_PATTERN, 
+REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, 
 // Validation
-ValidationError, validateMetadata, validateRequirementNode, validateRequirementsFile, validatePrefix, validateKey, 
-// Prefix/key utilities
-normalizePrefix, parseRequirementKey, buildRequirementKey, } from './schemas.js';
-// Building (uses yaml package - browser-safe)
-export { DEFAULT_DELIMITER, buildRequirementsMarkdown, buildRequirementMarkdown, } from './builder.js';
-export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
-// Parser core (pure TypeScript - browser-safe, no fs dependency)
-// These functions parse markdown strings directly without file I/O
-export { DELIMITER_PATTERN, parseCriterionLine, parseRootLine, parseRequirementBlock, extractRequirementBlocks, parseRequirementBlocksFromMarkdown, flattenRequirementTree, findRequirementById, getAllRequirements, } from './parser-core.js';
-// NOTE: parser.ts and resolver.ts are excluded because they use Node.js 'fs' module.
-// Use parser-core.ts functions above for browser/Convex environments.
+ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
 // Scenario building (pure TypeScript - browser-safe, used by Convex Node actions)
-export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 //# sourceMappingURL=browser.js.map

package/dist/schema/builder.d.ts

@@ -1,7 +1,7 @@
 /**
  * Build Markdown requirements files from structured data.
  */
-import { RequirementNode, Metadata } from './schemas.js';
+import type { Metadata, RequirementNode } from "./schemas.js";
 /**
  * Default delimiter for requirements.
  * Can be overridden for organization-specific preferences.

package/dist/schema/builder.js

@@ -1,12 +1,12 @@
 /**
  * Build Markdown requirements files from structured data.
  */
-import YAML from 'yaml';
+import YAML from "yaml";
 /**
  * Default delimiter for requirements.
  * Can be overridden for organization-specific preferences.
  */
-export const DEFAULT_DELIMITER = '→';
+export const DEFAULT_DELIMITER = "→";
 /**
  * Build YAML frontmatter from metadata.
  */
@@ -17,51 +17,20 @@ function buildFrontmatter(metadata) {
     });
     return `---\n${yamlStr.trim()}\n---`;
 }
-/**
- * Build a dotrequirements block from a requirement node.
- * Formats children with explicit position paths and proper indentation.
- */
-function buildRequirementBlock(node, delimiter = DEFAULT_DELIMITER) {
-    // First line: root requirement with delimiter
-    // Include label if it's not empty (empty string means unlabeled)
-    const rootLabel = node.label
-        ? `${node.label.charAt(0).toUpperCase() + node.label.slice(1)} `
-        : '';
-    let block = `${rootLabel}${delimiter} ${node.content}\n`;
-    // Recursively build criteria lines
-    function addCriteria(children, parentPosition = '') {
-        children.forEach((child, index) => {
-            const position = parentPosition === '' ? `${index}` : `${parentPosition}.${index}`;
-            const depth = position.split('.').length - 1;
-            const indent = '  '.repeat(depth + 1); // 2 spaces per level
-            // Include label if present, otherwise just delimiter
-            const labelPart = child.label
-                ? `${child.label.charAt(0).toUpperCase() + child.label.slice(1)} `
-                : '';
-            block += `${indent}${position}. ${labelPart}${delimiter} ${child.content}\n`;
-            // Recursively add grandchildren
-            if (child.children && child.children.length > 0) {
-                addCriteria(child.children, position);
-            }
-        });
-    }
-    addCriteria(node.children);
-    return block.trimEnd();
-}
 /**
  * Build the children portion of a requirement block (without the root line).
  */
 function buildChildrenBlock(children) {
-    let block = '';
-    function addChildren(nodes, parentPosition = '') {
+    let block = "";
+    function addChildren(nodes, parentPosition = "") {
         nodes.forEach((child, index) => {
-            const position = parentPosition === '' ? `${index}` : `${parentPosition}.${index}`;
-            const depth = position.split('.').length - 1;
-            const indent = '  '.repeat(depth + 1); // 2 spaces per level
+            const position = parentPosition === "" ? `${index}` : `${parentPosition}.${index}`;
+            const depth = position.split(".").length - 1;
+            const indent = "  ".repeat(depth + 1); // 2 spaces per level
             // Include label if present, otherwise just delimiter
             const labelPart = child.label
                 ? `${child.label.charAt(0).toUpperCase() + child.label.slice(1)} `
-                : '';
+                : "";
             block += `${indent}${position}. ${labelPart}→ ${child.content}\n`;
             // Recursively add grandchildren
             if (child.children && child.children.length > 0) {
@@ -79,14 +48,14 @@ function buildRequirementSection(node, title) {
     const displayTitle = title || node.content;
     // Heading now just has the title, no key
     let section = `## ${displayTitle}\n\n`;
-    section += '```dotrequirements\n';
+    section += "```dotrequirements\n";
     // First line of block has the key
     section += `${node.id}: ${node.content}\n`;
     // Then add children
     if (node.children && node.children.length > 0) {
         section += buildChildrenBlock(node.children);
     }
-    section += '\n```\n';
+    section += "\n```\n";
     return section;
 }
 /**
@@ -94,7 +63,7 @@ function buildRequirementSection(node, title) {
  */
 export function buildRequirementsMarkdown(metadata, requirements, documentTitle) {
     let markdown = buildFrontmatter(metadata);
-    markdown += '\n\n';
+    markdown += "\n\n";
     // Add document title if provided
     if (documentTitle) {
         markdown += `# ${documentTitle}\n\n`;
@@ -102,9 +71,9 @@ export function buildRequirementsMarkdown(metadata, requirements, documentTitle)
     // Add each requirement section
     for (const req of requirements) {
         markdown += buildRequirementSection(req);
-        markdown += '\n';
+        markdown += "\n";
     }
-    return markdown.trimEnd() + '\n';
+    return `${markdown.trimEnd()}\n`;
 }
 /**
  * Build Markdown for a single requirement (for testing/debugging).

package/dist/schema/conversions.d.ts

@@ -1,7 +1,7 @@
 /**
  * Convert between Convex flat representation and hierarchical RequirementNode trees.
  */
-import { RequirementNode, Metadata } from './schemas.js';
+import type { Metadata, RequirementNode } from "./schemas.js";
 /**
  * Convex requirement type (flat structure with position paths).
  * This mirrors the Convex database schema.
@@ -16,7 +16,7 @@ export interface ConvexRequirement {
     projectId: string;
     rootId?: string;
     position?: string;
-    metadata?: any;
+    metadata?: unknown;
     externalLinks?: {
         jira?: string;
         notion?: string;