markback 0.1.1__tar.gz → 0.1.2__tar.gz

markback-0.1.2/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m pytest:*)",
+      "Bash(npm test:*)",
+      "Bash(npm install)",
+      "Bash(npm run build:*)",
+      "Bash(echo:*)",
+      "Bash(python -m markback lint:*)",
+      "Bash(python:*)"
+    ]
+  }
+}

{markback-0.1.1 → markback-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markback
-Version: 0.1.1
+Version: 0.1.2
 Summary: A compact, human-writable format for storing content paired with feedback/labels
 Project-URL: Homepage, https://github.com/dandriscoll/markback
 Project-URL: Repository, https://github.com/dandriscoll/markback

{markback-0.1.1 → markback-0.1.2}/SPEC.md

@@ -127,6 +127,27 @@ References an item that precedes the source material. For example, if the source
 - `@prior` does not affect content handling (inline content or `@source` rules still apply)
 - Parsers SHOULD verify referenced files exist (warning if missing)
 
+#### 3.1.4 Line Range Specification
+
+Both `@source` and `@prior` headers support optional line range specifications using colon notation. This allows referencing specific lines within a file.
+
+**Syntax:** `<path-or-uri>:<start>` or `<path-or-uri>:<start>-<end>`
+
+```
+@source ./code.py:42
+@source ./code.py:42-50
+@prior ./prompts/template.txt:1-20
+@source https://example.com/file.txt:100-150
+```
+
+**Rules:**
+- Line numbers are 1-indexed (first line is line 1)
+- Single line: `:N` references line N only
+- Line range: `:N-M` references lines N through M (inclusive)
+- End line must be greater than or equal to start line (E011 error otherwise)
+- Line ranges are informational metadata; parsers do not validate that referenced lines exist in the file
+- Windows drive letters (e.g., `C:\path`) are not confused with line ranges because scheme detection requires length > 1
+
 ### 3.2 Content Block
 
 Content is everything between headers and the `<<<` feedback delimiter.
@@ -575,6 +596,7 @@ Each line is classified as one of:
 | E008 | Unclosed quote in structured attribute value (only in `structured` parse mode) |
 | E009 | Empty feedback (nothing after `<<< `) |
 | E010 | Missing blank line before inline content (content starts with `@`) |
+| E011 | Invalid line range (end line less than start line) |
 
 ### 7.2 Warnings (SHOULD fix)
 
@@ -863,8 +885,10 @@ feedback-content = *VCHAR             ; no LF allowed
 compact-record  = [uri-line] source-feedback-line
 compact-list    = compact-record *(1*blank-line compact-record)
 uri-line        = "@uri" SP value LF
-source-feedback-line = "@source" SP path SP "<<<" SP feedback-content LF
-path            = 1*VCHAR             ; ends at space before <<<
+source-feedback-line = "@source" SP path-with-range SP "<<<" SP feedback-content LF
+path-with-range = path [line-range]   ; path with optional line range
+path            = 1*VCHAR             ; ends at space before <<< or line-range
+line-range      = ":" 1*DIGIT ["-" 1*DIGIT]
 
 LOWER           = %x61-7A  ; a-z
 SP              = %x20     ; space

{markback-0.1.1 → markback-0.1.2}/markback/linter.py

@@ -137,6 +137,42 @@ def lint_prior_exists(
     return diagnostics
 
 
+def lint_line_range(
+    record: Record,
+    record_idx: int,
+) -> list[Diagnostic]:
+    """Check if line ranges are valid (end >= start)."""
+    diagnostics: list[Diagnostic] = []
+
+    # Check @source line range
+    if record.source and record.source.start_line is not None:
+        if record.source.end_line is not None and record.source.end_line < record.source.start_line:
+            diagnostics.append(Diagnostic(
+                file=record._source_file,
+                line=record._start_line,
+                column=None,
+                severity=Severity.ERROR,
+                code=ErrorCode.E011,
+                message=f"Invalid line range in @source: end line {record.source.end_line} is less than start line {record.source.start_line}",
+                record_index=record_idx,
+            ))
+
+    # Check @prior line range
+    if record.prior and record.prior.start_line is not None:
+        if record.prior.end_line is not None and record.prior.end_line < record.prior.start_line:
+            diagnostics.append(Diagnostic(
+                file=record._source_file,
+                line=record._start_line,
+                column=None,
+                severity=Severity.ERROR,
+                code=ErrorCode.E011,
+                message=f"Invalid line range in @prior: end line {record.prior.end_line} is less than start line {record.prior.start_line}",
+                record_index=record_idx,
+            ))
+
+    return diagnostics
+
+
 def lint_canonical_format(
     records: list[Record],
     original_text: str,
@@ -206,6 +242,9 @@ def lint_string(
             result.diagnostics.extend(lint_source_exists(record, base_path, idx))
             result.diagnostics.extend(lint_prior_exists(record, base_path, idx))
 
+        # Check line range validity
+        result.diagnostics.extend(lint_line_range(record, idx))
+
     # Check canonical format
     if check_canonical and result.records and not result.has_errors:
         result.diagnostics.extend(lint_canonical_format(

{markback-0.1.1 → markback-0.1.2}/markback/types.py

@@ -1,5 +1,6 @@
 """Core types for MarkBack format."""
 
+import re
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
@@ -25,6 +26,7 @@ class ErrorCode(Enum):
     E008 = "E008"  # Unclosed quote in structured attribute value
     E009 = "E009"  # Empty feedback (nothing after <<< )
     E010 = "E010"  # Missing blank line before inline content
+    E011 = "E011"  # Invalid line range (end < start)
 
 
 class WarningCode(Enum):
@@ -76,29 +78,67 @@ class Diagnostic:
         }
 
 
+# Regex to parse line range from a path: path:start or path:start-end
+_LINE_RANGE_PATTERN = re.compile(r'^(.+?):(\d+)(?:-(\d+))?$')
+
+
 @dataclass
 class SourceRef:
     """Reference to external content (file path or URI)."""
     value: str
     is_uri: bool = False
+    start_line: Optional[int] = None
+    end_line: Optional[int] = None
+    _path_only: str = ""
 
     def __post_init__(self):
-        # Determine if this is a URI or file path
+        # Parse line range if present
+        self._parse_line_range()
+
+        # Determine if this is a URI or file path (using path without line range)
         if not self.is_uri:
-            parsed = urlparse(self.value)
+            parsed = urlparse(self._path_only)
             # Consider it a URI if it has a scheme that's not a Windows drive letter
             self.is_uri = bool(parsed.scheme) and len(parsed.scheme) > 1
 
+    def _parse_line_range(self):
+        """Parse optional line range from value."""
+        match = _LINE_RANGE_PATTERN.match(self.value)
+        if match:
+            self._path_only = match.group(1)
+            self.start_line = int(match.group(2))
+            if match.group(3):
+                self.end_line = int(match.group(3))
+            else:
+                # Single line reference: start and end are the same
+                self.end_line = self.start_line
+        else:
+            self._path_only = self.value
+
+    @property
+    def path(self) -> str:
+        """Return path without line range."""
+        return self._path_only
+
+    @property
+    def line_range_str(self) -> Optional[str]:
+        """Return formatted line range string, or None if no range."""
+        if self.start_line is None:
+            return None
+        if self.start_line == self.end_line:
+            return f":{self.start_line}"
+        return f":{self.start_line}-{self.end_line}"
+
     def resolve(self, base_path: Optional[Path] = None) -> Path:
         """Resolve to a file path (relative paths resolved against base_path)."""
         if self.is_uri:
-            parsed = urlparse(self.value)
+            parsed = urlparse(self._path_only)
             if parsed.scheme == "file":
                 # file:// URI
                 return Path(parsed.path)
             raise ValueError(f"Cannot resolve non-file URI to path: {self.value}")
 
-        path = Path(self.value)
+        path = Path(self._path_only)
         if path.is_absolute():
             return path
         if base_path:

{markback-0.1.1 → markback-0.1.2}/packages/markbackjs/src/linter.ts

@@ -138,6 +138,46 @@ function lintPriorExists(record: MarkbackRecord, basePath: string | null, record
   return diagnostics;
 }
 
+function lintLineRange(record: MarkbackRecord, recordIdx: number): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+
+  // Check @source line range
+  if (record.source && record.source.startLine !== null) {
+    if (record.source.endLine !== null && record.source.endLine < record.source.startLine) {
+      diagnostics.push(
+        new Diagnostic({
+          file: record._sourceFile ?? null,
+          line: record._startLine ?? null,
+          column: null,
+          severity: Severity.ERROR,
+          code: ErrorCode.E011,
+          message: `Invalid line range in @source: end line ${record.source.endLine} is less than start line ${record.source.startLine}`,
+          recordIndex: recordIdx,
+        }),
+      );
+    }
+  }
+
+  // Check @prior line range
+  if (record.prior && record.prior.startLine !== null) {
+    if (record.prior.endLine !== null && record.prior.endLine < record.prior.startLine) {
+      diagnostics.push(
+        new Diagnostic({
+          file: record._sourceFile ?? null,
+          line: record._startLine ?? null,
+          column: null,
+          severity: Severity.ERROR,
+          code: ErrorCode.E011,
+          message: `Invalid line range in @prior: end line ${record.prior.endLine} is less than start line ${record.prior.startLine}`,
+          recordIndex: recordIdx,
+        }),
+      );
+    }
+  }
+
+  return diagnostics;
+}
+
 function lintCanonicalFormat(records: MarkbackRecord[], originalText: string, file?: string | null): Diagnostic[] {
   const diagnostics: Diagnostic[] = [];
 
@@ -199,6 +239,9 @@ export function lintString(text: string, options: LintOptions = {}): ParseResult
       result.diagnostics.push(...lintSourceExists(record, basePath, idx));
       result.diagnostics.push(...lintPriorExists(record, basePath, idx));
     }
+
+    // Check line range validity
+    result.diagnostics.push(...lintLineRange(record, idx));
   });
 
   if (checkCanonical && result.records.length > 0 && !result.hasErrors) {

{markback-0.1.1 → markback-0.1.2}/packages/markbackjs/src/types.ts

@@ -17,6 +17,7 @@ export enum ErrorCode {
   E008 = "E008",
   E009 = "E009",
   E010 = "E010",
+  E011 = "E011",
 }
 
 export enum WarningCode {
@@ -99,39 +100,81 @@ function extractScheme(value: string): string | null {
   return match ? match[1] : null;
 }
 
+// Regex to parse line range from a path: path:start or path:start-end
+const LINE_RANGE_PATTERN = /^(.+?):(\d+)(?:-(\d+))?$/;
+
 export class SourceRef {
   value: string;
   isUri: boolean;
+  startLine: number | null;
+  endLine: number | null;
+  private _pathOnly: string;
 
   constructor(value: string, isUri = false) {
     this.value = value;
+    this.startLine = null;
+    this.endLine = null;
+    this._pathOnly = value;
+
+    // Parse line range if present
+    this._parseLineRange();
+
     if (isUri) {
       this.isUri = true;
       return;
     }
 
-    const scheme = extractScheme(value);
+    // Determine if this is a URI (using path without line range)
+    const scheme = extractScheme(this._pathOnly);
     this.isUri = !!scheme && scheme.length > 1;
   }
 
+  private _parseLineRange(): void {
+    const match = LINE_RANGE_PATTERN.exec(this.value);
+    if (match) {
+      this._pathOnly = match[1];
+      this.startLine = parseInt(match[2], 10);
+      if (match[3]) {
+        this.endLine = parseInt(match[3], 10);
+      } else {
+        // Single line reference: start and end are the same
+        this.endLine = this.startLine;
+      }
+    }
+  }
+
+  get path(): string {
+    return this._pathOnly;
+  }
+
+  get lineRangeStr(): string | null {
+    if (this.startLine === null) {
+      return null;
+    }
+    if (this.startLine === this.endLine) {
+      return `:${this.startLine}`;
+    }
+    return `:${this.startLine}-${this.endLine}`;
+  }
+
   resolve(basePath?: string | null): string {
     if (this.isUri) {
-      const scheme = extractScheme(this.value);
+      const scheme = extractScheme(this._pathOnly);
       if (scheme && scheme.toLowerCase() === "file") {
-        return fileURLToPath(new URL(this.value));
+        return fileURLToPath(new URL(this._pathOnly));
       }
       throw new Error(`Cannot resolve non-file URI to path: ${this.value}`);
     }
 
-    if (path.isAbsolute(this.value)) {
-      return this.value;
+    if (path.isAbsolute(this._pathOnly)) {
+      return this._pathOnly;
     }
 
     if (basePath) {
-      return path.join(basePath, this.value);
+      return path.join(basePath, this._pathOnly);
     }
 
-    return this.value;
+    return this._pathOnly;
   }
 
   toString(): string {

{markback-0.1.1 → markback-0.1.2}/packages/markbackjs/test/linter.test.js

@@ -105,3 +105,57 @@ test("lintString: @prior URI not checked", () => {
   // Should not have W009 for URI-based @prior
   assert.equal(findCode(result.diagnostics, WarningCode.W009).length, 0);
 });
+
+// Line range support tests
+
+test("lintString: @source with single line", () => {
+  const text = "@source ./code.py:42 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.path, "./code.py");
+  assert.equal(result.records[0].source.startLine, 42);
+  assert.equal(result.records[0].source.endLine, 42);
+});
+
+test("lintString: @source with line range", () => {
+  const text = "@source ./code.py:10-20 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.path, "./code.py");
+  assert.equal(result.records[0].source.startLine, 10);
+  assert.equal(result.records[0].source.endLine, 20);
+});
+
+test("lintString: @prior with line range", () => {
+  const text = "@prior ./prompts/template.txt:1-20\n@source ./output.txt\n<<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].prior.path, "./prompts/template.txt");
+  assert.equal(result.records[0].prior.startLine, 1);
+  assert.equal(result.records[0].prior.endLine, 20);
+});
+
+test("lintString: compact record with line range", () => {
+  const text = "@uri local:item-001\n@source ./file.txt:100-150 <<< feedback\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.path, "./file.txt");
+  assert.equal(result.records[0].source.startLine, 100);
+  assert.equal(result.records[0].source.endLine, 150);
+});
+
+test("lintString: invalid line range end < start", () => {
+  const text = "@source ./code.py:50-10 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, true);
+  assert.equal(findCode(result.diagnostics, ErrorCode.E011).length, 1);
+});
+
+test("lintString: source without line range still works", () => {
+  const text = "@source ./code.py <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.path, "./code.py");
+  assert.equal(result.records[0].source.startLine, null);
+  assert.equal(result.records[0].source.endLine, null);
+});

{markback-0.1.1 → markback-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "markback"
-version = "0.1.1"
+version = "0.1.2"
 description = "A compact, human-writable format for storing content paired with feedback/labels"
 readme = "README.md"
 license = "MIT"

{markback-0.1.1 → markback-0.1.2}/tests/test_linter.py

@@ -245,3 +245,84 @@ class TestSummarizeResults:
         assert "records" in summary
         assert "errors" in summary
         assert "warnings" in summary
+
+
+class TestLineRangeSupport:
+    """Tests for line range support in @source and @prior."""
+
+    def test_source_with_single_line(self):
+        """Test @source with single line reference."""
+        text = "@source ./code.py:42 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.path == "./code.py"
+        assert result.records[0].source.start_line == 42
+        assert result.records[0].source.end_line == 42
+
+    def test_source_with_line_range(self):
+        """Test @source with line range reference."""
+        text = "@source ./code.py:10-20 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.path == "./code.py"
+        assert result.records[0].source.start_line == 10
+        assert result.records[0].source.end_line == 20
+
+    def test_prior_with_line_range(self):
+        """Test @prior with line range reference."""
+        text = "@prior ./prompts/template.txt:1-20\n@source ./output.txt\n<<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].prior is not None
+        assert result.records[0].prior.path == "./prompts/template.txt"
+        assert result.records[0].prior.start_line == 1
+        assert result.records[0].prior.end_line == 20
+
+    def test_compact_record_with_line_range(self):
+        """Test compact record with line range in @source."""
+        text = "@uri local:item-001\n@source ./file.txt:100-150 <<< feedback\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.path == "./file.txt"
+        assert result.records[0].source.start_line == 100
+        assert result.records[0].source.end_line == 150
+
+    def test_uri_with_line_range(self):
+        """Test URI source with line range."""
+        text = "@source https://example.com/file.txt:100-150 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.path == "https://example.com/file.txt"
+        assert result.records[0].source.start_line == 100
+        assert result.records[0].source.end_line == 150
+        assert result.records[0].source.is_uri
+
+    def test_invalid_line_range_end_less_than_start(self):
+        """Test E011: Invalid line range (end < start)."""
+        text = "@source ./code.py:50-10 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert result.has_errors
+        errors = [d for d in result.diagnostics if d.code == ErrorCode.E011]
+        assert len(errors) == 1
+        assert "end line 10 is less than start line 50" in errors[0].message
+
+    def test_source_without_line_range(self):
+        """Test @source without line range still works."""
+        text = "@source ./code.py <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.path == "./code.py"
+        assert result.records[0].source.start_line is None
+        assert result.records[0].source.end_line is None

markback-0.1.1/.claude/settings.local.json

@@ -1,9 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(python -m pytest:*)",
-      "Bash(npm test:*)",
-      "Bash(npm install)"
-    ]
-  }
-}