Add check and normalise CLI commands for .issues files (Task-12, Task-13)

- issues-fs check: validates .issues files (duplicates, broken refs, parse errors)
- issues-fs normalise: exports .issues to JSON issue.json structure (--dry-run supported)
- 14 new tests, 108 total CLI tests passing

https://claude.ai/code/session_01Sk3ihGTCicEo3dHVs6iXXW

Author: claude

issues_fs_cli/cli/cli__check.py

@@ -0,0 +1,72 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# CLI Check Command - Validate .issues files
+# ═══════════════════════════════════════════════════════════════════════════════
+
+import os
+import typer
+
+from issues_fs.issues.issues_file.Issues_File__Check__Service               import Issues_File__Check__Service
+from issues_fs_cli.cli.CLI__Output                                          import CLI__Output
+
+
+def check(file      : str  = typer.Argument(None                           , help="Specific .issues file to check"     ),
+          for_agent : bool = typer.Option   (False, "--for-agent"          , help="Agent-optimized output"              )
+     ) -> None:                                                             # Validate .issues files
+    issues_dir = find_issues_dir()
+    if issues_dir is None:
+        CLI__Output.error("No .issues/ directory found. "
+                          "Run 'issues-fs init' to create one.", for_agent)
+        raise typer.Exit(code=1)
+
+    if file:
+        file_path = os.path.join(issues_dir, file) if not os.path.isabs(file) else file
+        if not os.path.exists(file_path):
+            CLI__Output.error(f"File not found: {file_path}", for_agent)
+            raise typer.Exit(code=1)
+        files = [file_path]
+    else:
+        files = discover_issues_files(issues_dir)
+
+    if not files:
+        CLI__Output.success("No .issues files found.")
+        raise typer.Exit(code=0)
+
+    checker      = Issues_File__Check__Service()
+    files_data   = []
+
+    for path in files:
+        with open(path, 'r') as f:
+            content = f.read()
+        filename = os.path.basename(path)
+        files_data.append((content, filename))
+
+    if len(files_data) == 1:
+        summary = checker.check_content(files_data[0][0], files_data[0][1])
+    else:
+        summary = checker.check_multiple(files_data)
+
+    report = checker.format_report(summary)
+    print(report)
+
+    if summary.is_valid is False:
+        raise typer.Exit(code=1)
+
+
+def find_issues_dir() -> str:                                               # Walk up from cwd to find .issues/
+    current = os.getcwd()
+    while True:
+        candidate = os.path.join(current, '.issues')
+        if os.path.isdir(candidate):
+            return candidate
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def discover_issues_files(issues_dir: str) -> list:                         # Find all *.issues files in directory
+    result = []
+    for entry in os.listdir(issues_dir):
+        if entry.endswith('.issues'):
+            result.append(os.path.join(issues_dir, entry))
+    return sorted(result)

issues_fs_cli/cli/cli__main.py

@@ -13,6 +13,8 @@
 from issues_fs_cli.cli.cli__comment     import comment, comments
 from issues_fs_cli.cli.cli__types       import types_app, link_types_app
 from issues_fs_cli.cli.cli__init        import init
+from issues_fs_cli.cli.cli__check       import check
+from issues_fs_cli.cli.cli__normalise   import normalise
 
 
 app = typer.Typer(name            = "issues-fs"                                 ,
@@ -32,6 +34,14 @@
 app.command("delete"  )(delete     )
 
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# .issues File Commands
+# ═══════════════════════════════════════════════════════════════════════════════
+
+app.command("check"    )(check     )
+app.command("normalise")(normalise )
+
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # Link Commands
 # ═══════════════════════════════════════════════════════════════════════════════

issues_fs_cli/cli/cli__normalise.py

@@ -0,0 +1,94 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# CLI Normalise Command - Export .issues files to JSON issue structure
+# ═══════════════════════════════════════════════════════════════════════════════
+
+import json
+import os
+import typer
+
+from issues_fs.issues.issues_file.Issues_File__Normalise__Service           import Issues_File__Normalise__Service
+from issues_fs_cli.cli.CLI__Output                                          import CLI__Output
+
+
+def normalise(file      : str  = typer.Argument(None                       , help="Specific .issues file to normalise" ),
+              dry_run   : bool = typer.Option   (False, "--dry-run"        , help="Show what would be written"          ),
+              for_agent : bool = typer.Option   (False, "--for-agent"      , help="Agent-optimized output"              )
+         ) -> None:                                                         # Export .issues to JSON
+    issues_dir = find_issues_dir()
+    if issues_dir is None:
+        CLI__Output.error("No .issues/ directory found. "
+                          "Run 'issues-fs init' to create one.", for_agent)
+        raise typer.Exit(code=1)
+
+    if file:
+        file_path = os.path.join(issues_dir, file) if not os.path.isabs(file) else file
+        if not os.path.exists(file_path):
+            CLI__Output.error(f"File not found: {file_path}", for_agent)
+            raise typer.Exit(code=1)
+        files = [file_path]
+    else:
+        files = discover_issues_files(issues_dir)
+
+    if not files:
+        CLI__Output.success("No .issues files found.")
+        raise typer.Exit(code=0)
+
+    normaliser = Issues_File__Normalise__Service()
+    files_data = []
+
+    for path in files:
+        with open(path, 'r') as f:
+            content = f.read()
+        filename = os.path.basename(path)
+        files_data.append((content, filename))
+
+    if len(files_data) == 1:
+        file_map, errors = normaliser.normalise_to_dict(files_data[0][0], files_data[0][1])
+    else:
+        file_map, errors = normaliser.normalise_multiple(files_data)
+
+    if dry_run:
+        print(f"Would write {len(file_map)} files:")
+        for path in sorted(file_map.keys()):
+            print(f"  {path}")
+        if errors:
+            print(f"\nErrors ({len(errors)}):")
+            for error in errors:
+                print(f"  {error}")
+        return
+
+    written = 0
+    for rel_path, content in file_map.items():
+        abs_path = os.path.join(issues_dir, rel_path)
+        os.makedirs(os.path.dirname(abs_path), exist_ok=True)
+        with open(abs_path, 'w') as f:
+            f.write(content)
+        written += 1
+
+    print(f"Normalised: {written} issue files written to {issues_dir}/")
+
+    if errors:
+        print(f"Errors ({len(errors)}):")
+        for error in errors:
+            print(f"  {error}")
+        raise typer.Exit(code=1)
+
+
+def find_issues_dir() -> str:                                               # Walk up from cwd to find .issues/
+    current = os.getcwd()
+    while True:
+        candidate = os.path.join(current, '.issues')
+        if os.path.isdir(candidate):
+            return candidate
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def discover_issues_files(issues_dir: str) -> list:                         # Find all *.issues files in directory
+    result = []
+    for entry in os.listdir(issues_dir):
+        if entry.endswith('.issues'):
+            result.append(os.path.join(issues_dir, entry))
+    return sorted(result)

tests/unit/cli/test_cli__check.py

@@ -0,0 +1,119 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# test_cli__check - Tests for the check CLI command
+# ═══════════════════════════════════════════════════════════════════════════════
+
+import os
+import tempfile
+import shutil
+
+from unittest                                                                   import TestCase
+from typer.testing                                                              import CliRunner
+
+from issues_fs_cli.cli.cli__main                                                import app
+
+
+class test_cli__check(TestCase):
+
+    @classmethod
+    def setUpClass(cls):
+        cls.runner       = CliRunner()
+        cls.temp_dir     = tempfile.mkdtemp()
+        cls.issues_dir   = os.path.join(cls.temp_dir, '.issues')
+        os.makedirs(cls.issues_dir)
+        cls.original_cwd = os.getcwd()
+        os.chdir(cls.temp_dir)
+
+    @classmethod
+    def tearDownClass(cls):
+        os.chdir(cls.original_cwd)
+        shutil.rmtree(cls.temp_dir)
+
+    def setUp(self):
+        for f in os.listdir(self.issues_dir):
+            if f.endswith('.issues'):
+                os.remove(os.path.join(self.issues_dir, f))
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Basic Check
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    def test__check__no_files(self):
+        result = self.runner.invoke(app, ["check"])
+        assert result.exit_code == 0
+        assert "No .issues files" in result.output
+
+    def test__check__valid_file(self):
+        path = os.path.join(self.issues_dir, 'tasks.issues')
+        with open(path, 'w') as f:
+            f.write('Task-1 | todo | First task\nTask-2 | done | Second task')
+
+        result = self.runner.invoke(app, ["check"])
+        assert result.exit_code == 0
+        assert 'PASS' in result.output
+        assert 'Issues: 2' in result.output
+
+    def test__check__invalid_file(self):
+        path = os.path.join(self.issues_dir, 'bad.issues')
+        with open(path, 'w') as f:
+            f.write('Task-1 | todo | Good\nbad line\nalso bad')
+
+        result = self.runner.invoke(app, ["check"])
+        assert result.exit_code == 1
+        assert 'FAIL' in result.output
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Specific File
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    def test__check__specific_file(self):
+        path = os.path.join(self.issues_dir, 'specific.issues')
+        with open(path, 'w') as f:
+            f.write('Bug-1 | confirmed | A bug')
+
+        result = self.runner.invoke(app, ["check", "specific.issues"])
+        assert result.exit_code == 0
+        assert 'PASS' in result.output
+
+    def test__check__missing_file(self):
+        result = self.runner.invoke(app, ["check", "ghost.issues"])
+        assert result.exit_code == 1
+        assert 'not found' in result.output.lower()
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Validation Errors
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    def test__check__duplicate_labels(self):
+        path = os.path.join(self.issues_dir, 'dups.issues')
+        with open(path, 'w') as f:
+            f.write('Task-1 | todo | First\nTask-1 | done | Duplicate')
+
+        result = self.runner.invoke(app, ["check"])
+        assert result.exit_code == 1
+        assert 'Duplicate' in result.output
+        assert 'Task-1'    in result.output
+
+    def test__check__broken_refs(self):
+        path = os.path.join(self.issues_dir, 'refs.issues')
+        with open(path, 'w') as f:
+            f.write('Task-1 | todo | Needs -> Ghost-1')
+
+        result = self.runner.invoke(app, ["check"])
+        assert result.exit_code == 1
+        assert 'Broken'   in result.output
+        assert 'Ghost-1'  in result.output
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Multiple Files
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    def test__check__multiple_files(self):
+        with open(os.path.join(self.issues_dir, 'a.issues'), 'w') as f:
+            f.write('Task-1 | todo | First')
+        with open(os.path.join(self.issues_dir, 'b.issues'), 'w') as f:
+            f.write('Bug-1 | confirmed | A bug')
+
+        result = self.runner.invoke(app, ["check"])
+        assert result.exit_code == 0
+        assert 'PASS'       in result.output
+        assert 'Issues: 2'  in result.output