Merge pull request #8 from hawkeyexl/llm

Add instruction validation and model management

Author: hawkeyexl

README.md

@@ -30,11 +30,18 @@ A tool to validate Markdown document structure against specified templates, ensu
 npx doc-structure-lint --file-path path/to/doc.md --template path/to/template.yaml
 ```
 
+Doc Structure Lint uses a _local_ language model to evaluate some parts of your templates and content. This model only takes about 2 GB of storage, and it's only downloaded once. When you run the tool for the first time, it may take a few minutes to download the language model. If you don't want to download the model during installation, set the `DOC_STRUCTURE_LINT_PRELOAD` environment variable to `0`. However, if you specify an `instructions` property in your template, the model will be downloaded regardless of the `DOC_STRUCTURE_LINT_PRELOAD` variable value.
+
+```bash
+export DOC_STRUCTURE_LINT_PRELOAD=0 && npx doc-structure-lint --file-path path/to/doc.md --template path/to/template.yaml
+```
+
 ### Options
 
 - `--file-path` or `-f`: Path to the Markdown document to validate
 - `--template-path` or `-p`: Path to the YAML template file (default: `./template.yaml`)
 - `--template` or `-t`: Name of the template to use
+- `--json`: Output results in JSON format
 
 ## Usage (as a package)
 
@@ -47,56 +54,207 @@ npm install doc-structure-lint
 ### API Usage
 
 ```javascript
-import { lintDocument } from 'doc-structure-lint';
+import { lintDocument } from "doc-structure-lint";
 
 async function validateDocument() {
-    const result = await lintDocument({
-      file: "path/to/doc.md",
-      templatePath: "path/to/template.yaml",
-      template: "Template name",
-    });
+  const result = await lintDocument({
+    file: "path/to/doc.md",
+    templatePath: "path/to/template.yaml",
+    template: "Template name",
+  });
 }
 ```
 
 ## Template Format
 
-Templates are defined in YAML and can specify:
+Templates are defined in YAML and specify the structure and content requirements for your documents. Each template can contain multiple sections with various validation rules.
+
+Template definitions also support referencing with the `$ref` key, allowing you to reuse common section definitions across multiple templates.
+
+### Basic Structure
+
+```yaml
+templates:
+  template-name: # Must be alphanumeric, can include hyphens and underscores
+    sections: # Required - contains section definitions
+      section-name: # Must be alphanumeric, can include hyphens and underscores
+        # Section properties go here
+```
+
+### Section Properties
+
+```yml
+description: Description of the section's purpose
+instructions: # List of instructions that a section must follow, evaluated by a local language model. Doesn't evaluate content from subsections.
+  - Instruction 1
+  - Instruction 2
+required: true # Whether the section must be present (default: true)
+heading:
+  const: Exact heading text # Exact heading text match
+  pattern: ^Regex pattern$ # Regex pattern for heading text
+sections: # Nested subsection definitions
+  nested-section:
+    # Nested section properties
+additionalSections: false # Allow undefined subsections (default: false)
+```
+
+### Content Validation Rules
+
+#### Paragraphs
+
+```yaml
+paragraphs:
+  min: 0 # Minimum number of paragraphs
+  max: 10 # Maximum number of paragraphs
+  patterns: # Array of regex patterns applied sequentially
+    - "^Start with.*"
+    - ".*end with this$"
+```
+
+#### Code Blocks
+
+```yaml
+code_blocks:
+  min: 0 # Minimum number of code blocks
+  max: 5 # Maximum number of code blocks
+```
+
+#### Lists
+
+```yaml
+lists:
+  min: 0 # Minimum number of lists
+  max: 5 # Maximum number of lists
+  items: # Requirements for list items
+    min: 1 # Minimum items per list
+    max: 10 # Maximum items per list
+    paragraphs: # Paragraph requirements within items
+      min: 0
+      max: 2
+    code_blocks: # Code block requirements within items
+      min: 0
+      max: 1
+    lists: # Nested list requirements
+      min: 0
+      max: 2
+```
+
+#### Content Sequence
+
+Use `sequence` to specify a strict order of content elements:
+
+```yaml
+sequence:
+  - paragraphs:
+      min: 1 # Must start with at least one paragraph
+      max: 3 # But a maximum of three paragraphs
+  - code_blocks:
+      max: 1 # Followed by at most one code block
+  - lists:
+      min: 1 # Then at least one list
+  - paragraphs:
+      min: 1 # And ending with at least one paragraph
+```
+
+### Example Template
+
+The following definition includes templates for a "How To" guide and an "API Operation" reference. Note that the `parameters` component is used in multiple sections with the `$ref` key.
 
 ```yaml
 templates:
-  how-to-guide: # Template name
+  how-to:
     sections:
-      introduction: # Section name
-        paragraphs: # Paragraph count requirements for the whole section
+      title:
+        instructions:
+          - Must mention the intent of the document
+        paragraphs:
+          min: 1
+        sections:
+          overview:
+            heading:
+              const: Overview
+            paragraphs:
+              min: 1
+          before you start:
+            heading:
+              const: Before you start
+            paragraphs:
+              min: 1
+          task:
+            paragraphs:
+              min: 1
+            additionalSections: true
+            sections:
+              Sub-task:
+                paragraphs:
+                  min: 1
+          see also:
+            heading:
+              const: See also
+            paragraphs:
+              min: 1
+  api-operation:
+    sections:
+      overview:
+        heading:
+          const: "Overview"
+        paragraphs:
           min: 1
           max: 3
-      prerequisites:
-        sequence:    # Specific sequence of elements in the section
-            - paragraphs:
-               min: 1
-            - lists:
-               min: 1
-               items:
-                  min: 2
-      usage:
+      request-parameters:
+        $ref: "#/components/parameters"
+      response-parameters:
+        $ref: "#/components/parameters"
+      examples:
+        required: true
         code_blocks:
           min: 1
         sections:
-          advanced_features: # Subsection name
+          success:
+            heading:
+              const: "Success Response"
+            sequence:
+              - paragraphs:
+                  min: 1
+              - code_blocks:
+                  min: 1
+          error:
             required: false
-          troubleshooting:
+            heading:
+              const: "Error Response"
+
+components:
+  parameters:
+    required: false
+    heading:
+      pattern: "^Parameters|Request Parameters$"
+    lists:
+      min: 1
+      items:
+        min: 1
 ```
 
-> **Note:** Comprehensive rules reference coming soon.
+To use this template, save it to a file (like the default `templates.yaml`) and specify the template name that matches the key you set in your definition:
+
+```bash how-to
+npx doc-structure-lint --file-path path/to/doc.md --template-path path/to/templates.yaml --template how-to
+```
+
+```bash api-operation
+npx doc-structure-lint --file-path path/to/operation.md --template-path path/to/templates.yaml --template api-operation
+```
 
 ## Development
 
 1. Clone the repository
 2. Install dependencies:
+
    ```bash
    npm install
    ```
+
 3. Run tests:
+
    ```bash
    npm test
    ```