Quality tool chain and verbosity flags

Author: debritto

.github/workflows/ci.yml

@@ -61,7 +61,6 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -e ".[dev]"
-        pip install ruff mypy
 
     - name: Run Ruff (linter)
       run: |

.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+# Pre-commit hooks for synesis (compiler).
+# Install: pip install pre-commit && pre-commit install
+# Run on all files: pre-commit run --all-files
+#
+# Note: ruff-format and mypy are intentionally NOT enforced here yet.
+# - ruff-format: deferred until the one-time style reflow lands.
+# - mypy: runs in CI (non-blocking) until the type-error backlog is cleared.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks:
+      - id: ruff
+        args: [--fix]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict

CHANGELOG.md

@@ -5,8 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.6] - 2026-06-12
+
+### Added
+
+- **Verbosity flags `-v`/`-q` on `synesis` CLI** (`synesis/cli.py`)
+  - `-v` / `--verbose` (count): raises log level to DEBUG. Repeatable.
+  - `-q` / `--quiet` (count): lowers to WARNING (`-q`) or ERROR (`-qq`). Repeatable.
+  - Implemented via `_configure_logging(verbose, quiet)` helper using `logging.basicConfig`.
+  - `Global Options:` section added to `_build_main_help()` output — consistent with synesis-coder style.
+  - No impact on compilation output; only controls Python logging channel.
+
 ## [0.5.5] - 2026-06-11
 
+### Added
+
+- **Quality toolchain and CI** (`pyproject.toml`, `.pre-commit-config.yaml`, `.github/workflows/ci.yml`)
+  - `ruff==0.15.17` and `mypy==1.15.0` added to `dev` extras (pinned, shared across ecosystem).
+  - `[tool.ruff]`: `line-length=100`, `target-version="py310"`; lint rules `["E","F","I","UP","B","SIM","C4"]`.
+  - `[tool.mypy]`: `ignore_missing_imports=true`, `disallow_untyped_defs=false` (lenient baseline).
+  - `.pre-commit-config.yaml`: `ruff` (lint + `--fix`), `ruff-format`, `mypy`, `end-of-file-fixer`, `trailing-whitespace`, `check-yaml`, `check-toml`, `check-merge-conflict`.
+  - CI workflow (3 OS × 3 Python versions): `test` (pytest + coverage), `lint` (ruff + mypy), `build` (wheel + twine check), `integration` (`synesis --help/--version`).
+
+- **CLI snapshot tests** (`tests/test_cli.py`)
+  - Subprocess-based tests asserting structural anchors in `--help` output (title, `Usage:`, `Commands:`, subcommand names) and `--version` correctness — serve as regression guard for CLI refactors.
+
 ### Changed
 
 - **CLI rewritten with Unix-style output, colors, and English-only interface** (`synesis/cli.py`)

README.md

@@ -63,9 +63,20 @@ graph TD
 | [synesis-lsp](https://github.com/synesis-lang/synesis-lsp) | Python | Language Server — diagnostics, hover, completion, semantic tokens |
 | [synesis-explorer](https://github.com/synesis-lang/synesis-explorer) | JS/TS | VS Code extension — tree views, graph viewer, themes |
 | [zotero-synesis-export](https://github.com/synesis-lang/zotero-synesis-export) | JavaScript | Zotero 7 plugin — exports PDF highlights and tags as plain `.syn` (no chains or ontology codes) |
-| [synesis2neo4j](https://github.com/synesis-lang/synesis2neo4j) | Python | Import compiled knowledge into Neo4j / Memgraph |
+| [synesis-graph](https://github.com/synesis-lang/synesis-graph) | Python | Import compiled knowledge into Neo4j / GraphQLite, render interactive HTML graphs |
 | [synesis-coder](https://github.com/synesis-lang/synesis-coder) | Python | AI-assisted annotation — generates fully coded `.syn` files (chains, codes, fields) conforming to the project template |
 
+### Compatibility matrix
+
+Downstream tools pin to the compiler version they require:
+
+| Package | Latest version | Requires `synesis` | Python |
+|---|---|---|---|
+| synesis | 0.5.5 | — | ≥3.10 |
+| synesis-coder | 0.4.1 | ≥0.5.5 | ≥3.10 |
+| synesis-lsp | 0.15.4 | ≥0.5.5 | ≥3.10 |
+| synesis-graph | 0.2.0 | ≥0.5.5 | ≥3.10 |
+
 ---
 
 ## A Complete Example

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "synesis"
-version = "0.5.5"
+version = "0.5.6"
 description = "The confluence of information into intelligence - A DSL compiler that transforms qualitative research annotations into canonical knowledge structures"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -54,6 +54,8 @@ dev = [
     "pytest-cov >= 4.0",
     "build >= 0.10",
     "twine >= 4.0",
+    "ruff == 0.15.17",
+    "mypy == 1.15.0",
 ]
 
 [project.urls]
@@ -70,3 +72,22 @@ synesis = "synesis.cli:main"
 where = ["."]
 include = ["synesis*"]
 exclude = ["out_dir*", "davi_pesquisa*", "bibliometrics*", "examples*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+# Generated by Lark — not hand-maintained, exclude from lint/format.
+extend-exclude = ["synesis/grammar/synesis_standalone.py"]
+
+[tool.ruff.lint]
+# Lenient baseline: bug-catching rules (F) and import sorting (I) are enforced;
+# cosmetic/modernization rules are deferred (tracked, to be tightened incrementally).
+select = ["F", "I"]
+ignore = ["F541"]  # f-string-missing-placeholders (cosmetic)
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true

synesis/__init__.py

@@ -23,9 +23,10 @@
 Gerado conforme: Especificacao Synesis v1.1
 """
 
-from importlib.metadata import PackageNotFoundError, version as _pkg_version
-from pathlib import Path
 import re
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
 
 
 def _read_version_from_pyproject() -> str:
@@ -39,40 +40,40 @@ def _read_version_from_pyproject() -> str:
 
 # API em memoria (NOVO)
 from synesis.api import (
-    load,
-    compile_string,
-    MemoryCompilationResult,
     CompilationStats,
-)
-
-# Compilador tradicional
-from synesis.compiler import (
-    SynesisCompiler,
-    CompilationResult,
+    MemoryCompilationResult,
+    compile_string,
+    load,
 )
 
 # AST Nodes
 from synesis.ast.nodes import (
-    Scope,
+    ChainNode,
+    FieldSpec,
     FieldType,
-    SourceLocation,
-    ProjectNode,
-    SourceNode,
+    IncludeNode,
     ItemNode,
     OntologyNode,
-    TemplateNode,
-    FieldSpec,
-    ChainNode,
-    IncludeNode,
     OrderedValue,
+    ProjectNode,
+    Scope,
+    SourceLocation,
+    SourceNode,
+    TemplateNode,
 )
 
 # Result types
 from synesis.ast.results import (
-    Ok,
     Err,
-    ValidationResult,
+    Ok,
     ValidationError,
+    ValidationResult,
+)
+
+# Compilador tradicional
+from synesis.compiler import (
+    CompilationResult,
+    SynesisCompiler,
 )
 
 # Semantic

synesis/api.py

@@ -51,7 +51,7 @@
 from synesis.parser.lexer import parse_string
 from synesis.parser.template_loader import load_template_from_string
 from synesis.parser.transformer import SynesisTransformer
-from synesis.semantic.linker import Linker, LinkedProject
+from synesis.semantic.linker import LinkedProject, Linker
 from synesis.semantic.validator import SemanticValidator
 
 

synesis/cli.py

@@ -26,6 +26,7 @@
 
 from __future__ import annotations
 
+import logging
 import sys
 import threading
 import time
@@ -48,7 +49,6 @@
 from synesis.parser.lexer import SynesisSyntaxError, parse_file
 from synesis.parser.template_loader import TemplateLoadError, load_template
 
-
 # ---------------------------------------------------------------------------
 # Helpers de estilo
 # ---------------------------------------------------------------------------
@@ -61,6 +61,19 @@ def _c(text: str, **kwargs) -> str:
     return click.style(text, **kwargs) if _tty() else text
 
 
+def _configure_logging(verbose: int, quiet: int) -> None:
+    """Set root log level: -q → WARNING/ERROR, default → INFO, -v → DEBUG."""
+    if quiet >= 2:
+        level = logging.ERROR
+    elif quiet == 1:
+        level = logging.WARNING
+    elif verbose >= 1:
+        level = logging.DEBUG
+    else:
+        level = logging.INFO
+    logging.basicConfig(level=level, format="[%(levelname)s] %(message)s")
+
+
 def _build_main_help() -> str:
     title = _c("SYNESIS COMPILER", fg="green", bold=True) + f" (v{VERSION})"
     desc = "Semantic compiler for knowledge engineering."
@@ -79,7 +92,21 @@ def _build_main_help() -> str:
         ]),
     ]
 
-    col = max(len(name) for _, rows in groups for name, _ in rows) + 2
+    opt_rows = [
+        ("-v, --verbose",  "Increase log verbosity (DEBUG). Repeatable."),
+        ("-q, --quiet",    "Decrease log verbosity (-q WARNING, -qq ERROR). Repeatable."),
+        ("--version",      "Show version and exit"),
+        ("--help",         "Show this message and exit"),
+    ]
+
+    cmd_names_len = max(len(name) for _, rows in groups for name, _ in rows)
+    opt_names_len = max(len(name) for name, _ in opt_rows)
+    col = max(cmd_names_len, opt_names_len) + 2
+
+    options = _c("Global Options:", fg="yellow", bold=True) + "\n" + "\n".join(
+        f"  {_c(name.ljust(col), fg='cyan')}  {desc_}"
+        for name, desc_ in opt_rows
+    )
 
     def _render_group(label, rows):
         lines = [_c("  " + label, fg="yellow", bold=True)]
@@ -96,7 +123,7 @@ def _render_group(label, rows):
         fg="bright_black",
     )
 
-    return "\n\n".join([title, desc, usage, commands, hint]) + "\n"
+    return "\n\n".join([title, desc, usage, options, commands, hint]) + "\n"
 
 
 class _SynesisCommand(click.Command):
@@ -248,9 +275,14 @@ def fail(self) -> None:
 
 @click.group(cls=_SynesisGroup, invoke_without_command=True)
 @click.version_option(version=VERSION, prog_name="synesis")
+@click.option("-v", "--verbose", count=True, default=0,
+              help="Increase log verbosity (-v for DEBUG). Repeatable.")
+@click.option("-q", "--quiet", count=True, default=0,
+              help="Decrease log verbosity (-q for WARNING, -qq for ERROR). Repeatable.")
 @click.pass_context
-def main(ctx) -> None:
+def main(ctx, verbose: int, quiet: int) -> None:
     """Compilador semântico para validação e consolidação de conhecimento."""
+    _configure_logging(verbose, quiet)
     if ctx.invoked_subcommand is None:
         out = _build_main_help()
         if hasattr(sys.stdout, "buffer"):
@@ -594,7 +626,6 @@ def init() -> None:
 
 
 def _print_diagnostics(errors: Iterable, severity_label: str, base_dir: Path | None = None) -> None:
-    color = "red" if severity_label == "ERROR" else "yellow"
     label_color = "red" if severity_label == "ERROR" else "yellow"
 
     def _fmt_location(loc) -> str:

synesis/compiler.py

@@ -32,7 +32,7 @@
 from concurrent.futures import ProcessPoolExecutor
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Dict, Iterable, List, Optional
+from typing import Dict, List, Optional
 
 from synesis.ast.nodes import (
     ItemNode,
@@ -42,7 +42,6 @@
     SourceNode,
     TemplateNode,
 )
-from synesis.parser.bib_loader import BibEntry
 from synesis.ast.results import (
     DuplicateProjectBlock,
     MalformedBibliographyEntry,
@@ -58,12 +57,12 @@
 from synesis.exporters.csv_export import export_csv
 from synesis.exporters.json_export import export_json
 from synesis.exporters.xls_export import export_xls
-from synesis.parser.bib_loader import detect_malformed_entries, load_bibliography
+from synesis.parser.bib_loader import BibEntry, detect_malformed_entries, load_bibliography
 from synesis.parser.lexer import parse_file
 from synesis.parser.parse_cache import get_cached_nodes, put_cached_nodes
 from synesis.parser.template_loader import load_template, validate_template
 from synesis.parser.transformer import SynesisTransformer
-from synesis.semantic.linker import Linker, LinkedProject
+from synesis.semantic.linker import LinkedProject, Linker
 from synesis.semantic.validator import SemanticValidator
 
 
@@ -388,7 +387,7 @@ def _safe_load_template(self, project: ProjectNode) -> tuple[Optional[TemplateNo
             return None, result
         try:
             return load_template(template_path), result
-        except Exception as exc:
+        except Exception:
             result.add(MissingTemplateFile(
                 location=project.location,
                 template_path=str(project.template_path),

synesis/exporters/alpaca_export.py

@@ -40,18 +40,15 @@
     FieldSpec,
     FieldType,
     ItemNode,
-    OntologyNode,
     Scope,
-    SourceNode,
     TemplateNode,
 )
-from synesis.parser.bib_loader import BibEntry
-from synesis.semantic.linker import LinkedProject
 from synesis.exporters._helpers import (
-    _get_field_names_for_scope,
     _get_item_field_value,
     _get_ontology_field_value,
 )
+from synesis.parser.bib_loader import BibEntry
+from synesis.semantic.linker import LinkedProject
 
 AlpacaPair = Dict[str, str]
 _MIN_OUTPUT_LEN = 5