erdscope 0.7.0__tar.gz → 0.7.1__tar.gz

{erdscope-0.7.0/erdscope.egg-info → erdscope-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: erdscope
-Version: 0.7.0
+Version: 0.7.1
 Summary: Interactive, self-contained ER-diagram HTML and Excel table definitions from a MySQL, PostgreSQL, or SQLite database and/or application code (Rails / Prisma / Django) — single file, zero required dependencies
 Author: tas6
 License-Expression: MIT
@@ -196,6 +196,7 @@ explicit CLI argument wins.
 | `--emit-json FILE.json` | Also write a canonical JSON schema snapshot with a content fingerprint (`-` for stdout) |
 | `--emit-config FILE.yml\|.json` | Also write the schema as a config-authoring file, re-importable via `--config` (`-` for stdout, always JSON) |
 | `--diff SNAPSHOT.json` | Compare this run against a saved `--emit-json` snapshot and exit 0/1/2 instead of generating output (CI drift gate) |
+| `--emit-digest FILE.md` | Also write a token-efficient Markdown digest of the schema, with design notes, for LLMs/agents (`-` for stdout; `--digest-verbose` adds nullable/default/sql_type) |
 | `--only 'user*,order*'` | Generate only matching tables |
 | `--exclude '*_logs'` | Leave matching tables out |
 | `--infer-fk` | Add clearly marked relation guesses from `*_id` columns |

{erdscope-0.7.0 → erdscope-0.7.1}/README.md

@@ -162,6 +162,7 @@ explicit CLI argument wins.
 | `--emit-json FILE.json` | Also write a canonical JSON schema snapshot with a content fingerprint (`-` for stdout) |
 | `--emit-config FILE.yml\|.json` | Also write the schema as a config-authoring file, re-importable via `--config` (`-` for stdout, always JSON) |
 | `--diff SNAPSHOT.json` | Compare this run against a saved `--emit-json` snapshot and exit 0/1/2 instead of generating output (CI drift gate) |
+| `--emit-digest FILE.md` | Also write a token-efficient Markdown digest of the schema, with design notes, for LLMs/agents (`-` for stdout; `--digest-verbose` adds nullable/default/sql_type) |
 | `--only 'user*,order*'` | Generate only matching tables |
 | `--exclude '*_logs'` | Leave matching tables out |
 | `--infer-fk` | Add clearly marked relation guesses from `*_id` columns |

{erdscope-0.7.0 → erdscope-0.7.1}/erd.py

@@ -8959,6 +8959,197 @@ def render_text(diff) -> str:
         lines.append('')
 
     return '\n'.join(lines).rstrip('\n') + '\n'
+# ---------------------------------------------------------------------------
+# --emit-digest — token-efficient Markdown digest of the schema, WITH design
+# notes, for LLM/agent consumption (backlog #3). Reuses emit.py's
+# canonical_schema (same allowlist/pruning/deterministic order --emit-json and
+# --emit-config already share) — render_digest never re-derives what survives
+# or how it's ordered, only how it's RENDERED. Pure and non-destructive:
+# canonical_schema already deep-copies, and nothing here mutates its result.
+#
+# Differentiator (the digest's whole reason to exist, per EMIT_DIGEST_SPEC.md
+# §0): design intent a machine cannot re-derive from the raw schema — notes
+# (table/relation/global) — survives. provenance/sources, the legacy db_fk/
+# inferred/manual/schema_fk flags, and (by default) nullable/default/extra are
+# all dropped to keep the token budget on MEANING, not on every column detail
+# an LLM can usually infer or doesn't need. `groups` is dropped entirely: it
+# is a viewer-cosmetic layout aid (which tables get drawn inside a rounded
+# frame together), not schema semantics — nothing an LLM reading this digest
+# would need to reason about the data model.
+# ---------------------------------------------------------------------------
+
+
+def _oneline(s):
+    """Collapse a free-text field (comment/note text) to one line — a
+    literal newline inside a bullet or heading would break the Markdown
+    structure (turn one bullet into what looks like two, or one table
+    heading into a heading plus stray body text)."""
+    return ' '.join(s.split())
+
+
+def _notes_by_scope(notes_data):
+    """Split canonical `notes` (already id-sorted by emit.py's
+    _canonical_notes) into (global list, {table -> [note, ...]},
+    {relation identity -> [note, ...]}). A relation identity is
+    `(source_table, type, name, foreign_key, through, polymorphic)` — exactly
+    the fields a resolved relation note carries (providers.py's
+    resolve_and_validate_notes) — so a table's Rel: line can look its own
+    associations up against this dict in O(1) instead of re-scanning every
+    note per association."""
+    global_notes = []
+    table_notes = {}
+    relation_notes = {}
+    for n in notes_data or []:
+        if n['scope'] == 'global':
+            global_notes.append(n)
+        elif n['scope'] == 'table':
+            table_notes.setdefault(n['table'], []).append(n)
+        else:  # relation
+            key = (n['source_table'], n['type'], n.get('name'), n.get('foreign_key'),
+                   n.get('through'), bool(n.get('polymorphic')))
+            relation_notes.setdefault(key, []).append(n)
+    return global_notes, table_notes, relation_notes
+
+
+def _note_text(n):
+    """One note -> a short inline rendering: `title: text` when titled, else
+    bare `text`. Links are never rendered here (in verbose mode either) — a
+    URL is low value per token for an LLM reader and the digest already
+    keeps notes themselves regardless of --digest-verbose (G-1's verbosity
+    knob is about column metadata density, not about which notes survive)."""
+    text = _oneline(n['text'])
+    return f'{n["title"]}: {text}' if n.get('title') else text
+
+
+def _fk_targets(associations):
+    """`{foreign_key_column -> target_table}` for every single-column FK
+    association on a table, so each column line can show `fk→<target>`
+    without re-scanning associations per column. Association `foreign_key`
+    is always single-column (AssociationFragment contract, header.py §4.2);
+    on a rare duplicate the deterministically-last (canonical order) wins —
+    harmless, since this is an informational cross-reference, not identity."""
+    return {a['foreign_key']: a['target'] for a in associations if a.get('foreign_key')}
+
+
+def _render_column(c, fk_targets, verbose):
+    """One canonical column -> its digest bullet line:
+    `- name: type[, pk][, fk→target][, null][, default=...][, sql_type][, "comment"]`.
+    nullable/default/sql_type only show under --digest-verbose (G-1) —
+    dropped by default to keep the per-column token cost to what's needed to
+    reconstruct the shape of the table, not every DB-level nuance."""
+    bits = [c.get('type', '')]
+    if c.get('primary'):
+        bits.append('pk')
+    target = fk_targets.get(c['name'])
+    if target:
+        bits.append(f'fk→{target}')
+    if verbose:
+        if c.get('nullable'):
+            bits.append('null')
+        if c.get('default'):
+            bits.append(f'default={c["default"]}')
+        if c.get('sql_type'):
+            bits.append(c['sql_type'])
+    comment = c.get('comment')
+    if comment:
+        bits.append(f'"{_oneline(comment)}"')
+    return f'- {c["name"]}: ' + ', '.join(bits)
+
+
+def _assoc_token(a):
+    """One canonical association -> its compact Rel: token:
+    `type target[ as name][ fk=foreign_key][ through X][ (poly)]`. `as name`
+    is included only when the association name differs from its target
+    (e.g. belongs_to :user on target `users` needs no `as`; a polymorphic
+    belongs_to whose target IS the synthetic association name never adds
+    one either, since target already equals name in that case)."""
+    bits = [a['type'], a['target']]
+    name = a.get('name')
+    if name and name != a['target']:
+        bits.append(f'as {name}')
+    if a.get('foreign_key'):
+        bits.append(f'fk={a["foreign_key"]}')
+    if a.get('through'):
+        bits.append(f'through {a["through"]}')
+    if a.get('polymorphic'):
+        bits.append('(poly)')
+    return ' '.join(bits)
+
+
+def _relation_note_key(a, table_name):
+    return (table_name, a['type'], a.get('name'), a.get('foreign_key'),
+            a.get('through'), bool(a.get('polymorphic')))
+
+
+def _render_rel_line(table_name, associations, relation_notes):
+    """The table's one-line association summary (spec §2's `Rel:` line),
+    each association compressed to _assoc_token and any relation note(s)
+    that resolve to it appended as `— "note text"`. Omitted entirely (returns
+    None) when the table has no associations — no reason to spend a line on
+    an empty summary."""
+    if not associations:
+        return None
+    tokens = []
+    for a in associations:
+        token = _assoc_token(a)
+        notes = relation_notes.get(_relation_note_key(a, table_name))
+        if notes:
+            token += ' — ' + '; '.join(f'"{_note_text(n)}"' for n in notes)
+        tokens.append(token)
+    return 'Rel: ' + ', '.join(tokens)
+
+
+def render_digest(schema, title=None, verbose=False):
+    """Render a canonical `schema` (emit.py's canonical_schema shape:
+    {tables, notes?, groups?}) to the --emit-digest Markdown. Pure and
+    deterministic: the same schema always renders the same text, since every
+    input list is already canonically ordered (emit.py) and this function
+    adds no further data-dependent ordering of its own — only `sorted(tables)`
+    for the one thing canonical_schema does NOT itself sort (its `tables` is
+    a dict keyed by name, in whatever order the caller built it; ordering it
+    here, rather than relying on json.dumps(sort_keys=True) the way
+    --emit-json/--emit-config's file writers do, is what makes THIS text
+    itself byte-deterministic, not just a JSON encoding of it)."""
+    global_notes, table_notes, relation_notes = _notes_by_scope(schema.get('notes'))
+    tables = schema.get('tables', {})
+    names = sorted(tables)
+
+    lines = [f'# {title} — schema digest' if title else '# Schema digest', '']
+    if global_notes:
+        lines.append('\n\n'.join(_note_text(n) for n in global_notes))
+        lines.append('')
+    lines.append(f'## Tables ({len(names)})')
+    lines.append('')
+
+    for name in names:
+        t = tables[name]
+        heading = f'### {name}'
+        comment = t.get('comment')
+        if comment:
+            heading += f'  — {_oneline(comment)}'
+        lines.append(heading)
+        for n in table_notes.get(name, []):
+            lines.append(f'_{_note_text(n)}_')
+        fk_targets = _fk_targets(t.get('associations', []))
+        for c in t.get('columns', []):
+            lines.append(_render_column(c, fk_targets, verbose))
+        rel_line = _render_rel_line(name, t.get('associations', []), relation_notes)
+        if rel_line:
+            lines.append(rel_line)
+        lines.append('')
+
+    return '\n'.join(lines).rstrip('\n') + '\n'
+
+
+def emit_digest_document(tables, notes_data, groups_data, title=None, verbose=False):
+    """Build the --emit-digest document (as a Markdown string): project the
+    final merged IR through the SAME canonical_schema --emit-json/--emit-config
+    already share, then render it. `groups_data` is accepted (mirroring the
+    other two emitters' signatures, and cli.py already has it in hand at the
+    same call site) but intentionally unused here — see the module docstring
+    on why groups carry no schema meaning for a digest."""
+    schema = canonical_schema(tables, notes_data, groups_data)
+    return render_digest(schema, title=title, verbose=verbose)
 def main():
     p = argparse.ArgumentParser(
         description='Generate an interactive ER diagram (and optional Excel table definitions) '
@@ -9004,6 +9195,14 @@ def main():
                         'byte-identical) round trip; dispatches on extension — .yml/.yaml '
                         'for YAML (needs PyYAML installed) or .json for JSON; use - for '
                         'stdout, which is always JSON. The HTML is still generated')
+    p.add_argument('--emit-digest', metavar='FILE.md', default=argparse.SUPPRESS,
+                   help='Also write a token-efficient Markdown digest of the schema '
+                        '(with design notes) for LLMs/agents, alongside the HTML; use '
+                        '- for stdout. Drops provenance and (by default) nullable/'
+                        'default/sql_type — see --digest-verbose')
+    p.add_argument('--digest-verbose', action='store_true',
+                   help='With --emit-digest, also include nullable/default/sql_type '
+                        'per column (omitted by default to keep the digest small)')
     p.add_argument('--excel-template', metavar='FILE.xlsx', default=argparse.SUPPRESS,
                    help="Override the workbook's colors/fonts/borders from a template "
                         '.xlsx — see excel-template.xlsx and its Styles sheet for the '
@@ -9392,6 +9591,7 @@ def _finish(tables, args, title_name, notes=None, notes_label='config',
     if getattr(args, 'diff', None) is not None:
         for _flag, _val in (('--emit-json', getattr(args, 'emit_json', None)),
                             ('--emit-config', getattr(args, 'emit_config', None)),
+                            ('--emit-digest', getattr(args, 'emit_digest', None)),
                             ('--excel', getattr(args, 'excel', None))):
             if _val:
                 _diff_fail(f'--diff cannot be combined with {_flag} '
@@ -9445,6 +9645,7 @@ def _finish(tables, args, title_name, notes=None, notes_label='config',
     for _flag, _val in (('-o/--output', getattr(args, 'output', None)),
                         ('--emit-json', getattr(args, 'emit_json', None)),
                         ('--emit-config', getattr(args, 'emit_config', None)),
+                        ('--emit-digest', getattr(args, 'emit_digest', None)),
                         ('--excel', getattr(args, 'excel', None))):
         if not _val or _val == '-':
             continue
@@ -9478,6 +9679,15 @@ def _finish(tables, args, title_name, notes=None, notes_label='config',
         emit_config_text = (config_yaml_text(emit_config_doc) if emit_config_fmt == 'yaml'
                             else config_json_text(emit_config_doc))
 
+    # --emit-digest (backlog #3): same provenance-preserving-IR timing as
+    # --emit-json/--emit-config above (built before serialize_for_viewer) —
+    # render_digest reads notes/associations straight off canonical_schema,
+    # same as the other two emitters.
+    emit_digest_val = getattr(args, 'emit_digest', None)
+    emit_digest_text = (emit_digest_document(tables, notes_data, groups_data, title=title_name,
+                                             verbose=getattr(args, 'digest_verbose', False))
+                        if emit_digest_val is not None else None)
+
     # §9.3 serialize boundary: convert the internal provenance/sources IR to
     # today's legacy-flag shape (a no-op pass-through for the already-legacy demo
     # IR), so BOTH the HTML DATA_JSON and the Excel export below see exactly the
@@ -9519,6 +9729,13 @@ def _finish(tables, args, title_name, notes=None, notes_label='config',
             Path(emit_config_val).write_text(emit_config_text, encoding='utf-8')
             print(f'Generated: {emit_config_val}', file=sys.stderr)
 
+    if emit_digest_text is not None:
+        if emit_digest_val == '-':
+            sys.stdout.write(emit_digest_text)
+        else:
+            Path(emit_digest_val).write_text(emit_digest_text, encoding='utf-8')
+            print(f'Generated: {emit_digest_val}', file=sys.stderr)
+
     if getattr(args, 'excel', None):
         write_excel(tables, Path(args.excel), title_name,
                     template_path=getattr(args, 'excel_template', None), notes=notes_data,

{erdscope-0.7.0 → erdscope-0.7.1/erdscope.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: erdscope
-Version: 0.7.0
+Version: 0.7.1
 Summary: Interactive, self-contained ER-diagram HTML and Excel table definitions from a MySQL, PostgreSQL, or SQLite database and/or application code (Rails / Prisma / Django) — single file, zero required dependencies
 Author: tas6
 License-Expression: MIT
@@ -196,6 +196,7 @@ explicit CLI argument wins.
 | `--emit-json FILE.json` | Also write a canonical JSON schema snapshot with a content fingerprint (`-` for stdout) |
 | `--emit-config FILE.yml\|.json` | Also write the schema as a config-authoring file, re-importable via `--config` (`-` for stdout, always JSON) |
 | `--diff SNAPSHOT.json` | Compare this run against a saved `--emit-json` snapshot and exit 0/1/2 instead of generating output (CI drift gate) |
+| `--emit-digest FILE.md` | Also write a token-efficient Markdown digest of the schema, with design notes, for LLMs/agents (`-` for stdout; `--digest-verbose` adds nullable/default/sql_type) |
 | `--only 'user*,order*'` | Generate only matching tables |
 | `--exclude '*_logs'` | Leave matching tables out |
 | `--infer-fk` | Add clearly marked relation guesses from `*_id` columns |

{erdscope-0.7.0 → erdscope-0.7.1}/erdscope.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ tests/test_demo.py
 tests/test_diff.py
 tests/test_e2e.py
 tests/test_emit_config.py
+tests/test_emit_digest.py
 tests/test_emit_json.py
 tests/test_erd.py
 tests/test_golden_format1.py

{erdscope-0.7.0 → erdscope-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "erdscope"
-version = "0.7.0"
+version = "0.7.1"
 description = "Interactive, self-contained ER-diagram HTML and Excel table definitions from a MySQL, PostgreSQL, or SQLite database and/or application code (Rails / Prisma / Django) — single file, zero required dependencies"
 readme = "README.md"
 license = "MIT"

erdscope-0.7.1/tests/test_emit_digest.py

@@ -0,0 +1,401 @@
+"""--emit-digest (backlog #3) — token-efficient Markdown digest of the
+schema, with design notes, for LLM/agent consumption.
+
+Covers the new src/erdscope/digest.py surface (render_digest,
+emit_digest_document) as direct unit tests against hand-built canonical
+schemas (mirrors tests/test_emit_json.py's style — no need to route through
+merge_ir/canonical_schema for tests that are purely about rendering), plus
+CLI-level wiring tests (--emit-digest alongside --excel/--emit-json/HTML, `-`
+for stdout, output-collision guard, --only/--exclude reflected,
+--digest-verbose, --diff rejecting the combination) driven through main() the
+same way tests/test_emit_json.py's _EmitJsonDriver does.
+
+Run from the repository root:
+    python3 -m unittest tests.test_emit_digest -v
+"""
+import copy
+import importlib.util
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+spec = importlib.util.spec_from_file_location('erd', ROOT / 'erd.py')
+erd = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(erd)
+
+
+def _col(name, type_='integer', nullable=False, **extra):
+    c = {'name': name, 'type': type_, 'nullable': nullable}
+    c.update(extra)
+    return c
+
+
+def _schema():
+    """A hand-built canonical schema (already the emit.py output shape) —
+    users (1) <- posts (N) belongs_to on user_id, plus one note of each
+    scope. Mirrors test_emit_json.py's _merged_tables fixture but already
+    post-canonical_schema, since render_digest consumes that shape directly."""
+    return {
+        'tables': {
+            'users': {
+                'comment': 'App users',
+                'columns': [
+                    _col('id', primary=True),
+                    _col('email', type_='string', comment='Unique login'),
+                ],
+                'indexes': [],
+                'associations': [
+                    {'type': 'has_many', 'name': 'posts', 'target': 'posts',
+                     'provenance': 'declared'},
+                ],
+            },
+            'posts': {
+                'columns': [
+                    _col('id', primary=True),
+                    _col('user_id', nullable=True, default='0', sql_type='bigint unsigned'),
+                ],
+                'indexes': [],
+                'associations': [
+                    {'type': 'belongs_to', 'name': 'user', 'target': 'users',
+                     'foreign_key': 'user_id', 'provenance': 'db_fk'},
+                ],
+            },
+        },
+        'notes': [
+            {'id': 'n1', 'scope': 'global', 'text': 'Simple blog schema.'},
+            {'id': 'n2', 'scope': 'table', 'table': 'users', 'title': 'PII',
+             'text': 'email is personal data'},
+            {'id': 'n3', 'scope': 'relation', 'source_table': 'posts', 'target': 'users',
+             'type': 'belongs_to', 'name': 'user', 'foreign_key': 'user_id',
+             'through': None, 'polymorphic': False, 'text': 'cascade on delete'},
+        ],
+        'groups': [{'id': 'g1', 'tables': ['users', 'posts'], 'title': 'Core'}],
+    }
+
+
+# ---------------------------------------------------------------------------
+# structure / headings
+# ---------------------------------------------------------------------------
+class TestStructure(unittest.TestCase):
+    def test_title_in_heading(self):
+        out = erd.render_digest(_schema(), title='blogdb')
+        self.assertEqual(out.splitlines()[0], '# blogdb — schema digest')
+
+    def test_no_title_falls_back_to_generic_heading(self):
+        out = erd.render_digest(_schema())
+        self.assertEqual(out.splitlines()[0], '# Schema digest')
+
+    def test_table_count_in_heading(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('## Tables (2)', out)
+
+    def test_tables_sorted_alphabetically_regardless_of_dict_order(self):
+        schema = _schema()
+        reversed_schema = {**schema,
+                           'tables': {k: schema['tables'][k]
+                                     for k in reversed(list(schema['tables']))}}
+        out1 = erd.render_digest(schema)
+        out2 = erd.render_digest(reversed_schema)
+        self.assertEqual(out1, out2)
+        self.assertLess(out1.index('### posts'), out1.index('### users'))
+
+    def test_table_comment_on_heading_line(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('### users  — App users', out)
+
+    def test_table_without_comment_has_bare_heading(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('### posts\n', out)
+
+    def test_ends_with_single_trailing_newline(self):
+        out = erd.render_digest(_schema())
+        self.assertTrue(out.endswith('\n'))
+        self.assertFalse(out.endswith('\n\n'))
+
+
+# ---------------------------------------------------------------------------
+# columns
+# ---------------------------------------------------------------------------
+class TestColumns(unittest.TestCase):
+    def test_pk_marker(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('- id: integer, pk', out)
+
+    def test_fk_arrow_to_target(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('- user_id: integer, fk→users', out)
+
+    def test_comment_quoted(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('- email: string, "Unique login"', out)
+
+    def test_nullable_default_sql_type_omitted_by_default(self):
+        out = erd.render_digest(_schema())
+        line = [l for l in out.splitlines() if l.startswith('- user_id:')][0]
+        self.assertNotIn('null', line)
+        self.assertNotIn('default=', line)
+        self.assertNotIn('bigint unsigned', line)
+
+    def test_verbose_adds_nullable_default_sql_type(self):
+        out = erd.render_digest(_schema(), verbose=True)
+        line = [l for l in out.splitlines() if l.startswith('- user_id:')][0]
+        self.assertIn('null', line)
+        self.assertIn('default=0', line)
+        self.assertIn('bigint unsigned', line)
+
+    def test_verbose_does_not_affect_non_nullable_no_default_column(self):
+        out_plain = erd.render_digest(_schema())
+        out_verbose = erd.render_digest(_schema(), verbose=True)
+        id_line_plain = [l for l in out_plain.splitlines() if l.startswith('- id:')][0]
+        id_line_verbose = [l for l in out_verbose.splitlines() if l.startswith('- id:')][0]
+        self.assertEqual(id_line_plain, id_line_verbose)
+
+
+# ---------------------------------------------------------------------------
+# associations (Rel: line)
+# ---------------------------------------------------------------------------
+class TestAssociations(unittest.TestCase):
+    def test_belongs_to_token_with_as_and_fk(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('Rel: belongs_to users as user fk=user_id', out)
+
+    def test_has_many_token_without_as_when_name_matches_target(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('Rel: has_many posts', out)
+
+    def test_through_and_polymorphic_markers(self):
+        schema = _schema()
+        schema['tables']['posts']['associations'] = [
+            {'type': 'has_many', 'name': 'tags', 'target': 'tags', 'through': 'taggings'},
+            {'type': 'belongs_to', 'name': 'commentable', 'target': 'commentable',
+             'polymorphic': True},
+        ]
+        out = erd.render_digest(schema)
+        self.assertIn('Rel: has_many tags through taggings, '
+                      'belongs_to commentable (poly)', out)
+
+    def test_no_associations_omits_rel_line(self):
+        schema = _schema()
+        schema['tables']['users']['associations'] = []
+        out = erd.render_digest(schema)
+        users_block = out.split('### users')[1].split('### ')[0]
+        self.assertNotIn('Rel:', users_block)
+
+
+# ---------------------------------------------------------------------------
+# notes
+# ---------------------------------------------------------------------------
+class TestNotes(unittest.TestCase):
+    def test_global_note_appears_before_tables_section(self):
+        out = erd.render_digest(_schema())
+        self.assertLess(out.index('Simple blog schema.'), out.index('## Tables'))
+
+    def test_table_note_rendered_with_title(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('_PII: email is personal data_', out)
+
+    def test_table_note_appears_under_its_table(self):
+        out = erd.render_digest(_schema())
+        users_block = out.split('### users')[1].split('### ')[0]
+        self.assertIn('PII: email is personal data', users_block)
+
+    def test_relation_note_attached_to_matching_rel_token(self):
+        out = erd.render_digest(_schema())
+        self.assertIn('Rel: belongs_to users as user fk=user_id — "cascade on delete"', out)
+
+    def test_multiple_relation_notes_joined(self):
+        schema = _schema()
+        schema['notes'].append(
+            {'id': 'n4', 'scope': 'relation', 'source_table': 'posts', 'target': 'users',
+             'type': 'belongs_to', 'name': 'user', 'foreign_key': 'user_id',
+             'through': None, 'polymorphic': False, 'text': 'second note'})
+        out = erd.render_digest(schema)
+        self.assertIn('"cascade on delete"; "second note"', out)
+
+    def test_no_notes_key_renders_without_error(self):
+        schema = _schema()
+        del schema['notes']
+        out = erd.render_digest(schema)  # must not raise
+        self.assertIn('## Tables (2)', out)
+
+    def test_links_never_rendered(self):
+        schema = _schema()
+        schema['notes'][0]['links'] = [{'url': 'https://example.com', 'label': 'ADR'}]
+        out = erd.render_digest(schema)
+        self.assertNotIn('example.com', out)
+
+
+# ---------------------------------------------------------------------------
+# groups — intentionally dropped (viewer-cosmetic, no schema meaning)
+# ---------------------------------------------------------------------------
+class TestGroupsDropped(unittest.TestCase):
+    def test_group_title_never_appears(self):
+        out = erd.render_digest(_schema())
+        self.assertNotIn('Core', out)
+
+
+# ---------------------------------------------------------------------------
+# determinism / purity
+# ---------------------------------------------------------------------------
+class TestDeterminism(unittest.TestCase):
+    def test_same_schema_same_output(self):
+        schema = _schema()
+        self.assertEqual(erd.render_digest(schema), erd.render_digest(copy.deepcopy(schema)))
+
+    def test_emit_digest_document_matches_render_digest_of_canonical_schema(self):
+        tables = {
+            'users': {'columns': [_col('id', primary=True)], 'indexes': [], 'associations': [],
+                      'fk_columns': []},
+        }
+        expected = erd.render_digest(erd.canonical_schema(tables, None, None), title='t')
+        actual = erd.emit_digest_document(tables, None, None, title='t')
+        self.assertEqual(expected, actual)
+
+
+class TestPurity(unittest.TestCase):
+    def test_schema_unchanged_after_render(self):
+        schema = _schema()
+        before = copy.deepcopy(schema)
+        erd.render_digest(schema)
+        self.assertEqual(schema, before)
+
+
+# ---------------------------------------------------------------------------
+# CLI wiring — driven through main(), mirroring test_emit_json.py's
+# _EmitJsonDriver technique (stubbed parse_mysql, a temp cwd, sys.argv
+# juggling).
+# ---------------------------------------------------------------------------
+def _dbcol(t, name, dtype, ctype, null='YES', key='', default='', extra='', comment=''):
+    return (t, name, dtype, ctype, null, key, default, extra, comment)
+
+
+TABLE_ROWS = [('users', ''), ('posts', '')]
+COL_ROWS = [
+    _dbcol('users', 'id', 'bigint', 'bigint', 'NO', 'PRI', '', 'auto_increment'),
+    _dbcol('users', 'email', 'varchar', 'varchar(255)', 'NO', 'UNI'),
+    _dbcol('posts', 'id', 'bigint', 'bigint', 'NO', 'PRI', '', 'auto_increment'),
+    _dbcol('posts', 'user_id', 'bigint', 'bigint', 'NO', 'MUL'),
+    _dbcol('posts', 'title', 'varchar', 'varchar(255)', 'NO'),
+]
+FK_ROWS = [('posts', 'user_id', 'users')]
+INDEX_ROWS = [('users', 'PRIMARY', 0, 1, 'id')]
+
+
+class _EmitDigestDriver(unittest.TestCase):
+    def setUp(self):
+        self._orig_parse = erd.parse_mysql
+        self._orig_argv = sys.argv
+        self._orig_cwd = os.getcwd()
+        self.addCleanup(lambda: setattr(erd, 'parse_mysql', self._orig_parse))
+        self.addCleanup(lambda: setattr(sys, 'argv', self._orig_argv))
+        self.addCleanup(os.chdir, self._orig_cwd)
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        os.chdir(self.tmp.name)
+        erd.parse_mysql = lambda url: erd.mysql_ir(TABLE_ROWS, COL_ROWS, FK_ROWS, INDEX_ROWS)
+
+    def _run(self, *cli_args, capture_stdout=False, capture_stderr=False):
+        sys.argv = ['erd.py', 'mysql://x@localhost/testdb', *cli_args]
+        out_buf, err_buf = io.StringIO(), io.StringIO()
+        with redirect_stdout(out_buf), redirect_stderr(err_buf):
+            erd.main()
+        return out_buf.getvalue(), err_buf.getvalue()
+
+
+class TestCLIFileOutput(_EmitDigestDriver):
+    def test_emit_digest_writes_alongside_html(self):
+        self._run('--emit-digest', 'digest.md')
+        self.assertTrue((Path(self.tmp.name) / 'erd.html').exists())
+        text = (Path(self.tmp.name) / 'digest.md').read_text()
+        self.assertTrue(text.startswith('# testdb — schema digest'))
+        self.assertIn('### posts', text)
+        self.assertIn('### users', text)
+
+    def test_emit_digest_reports_generated_path_on_stderr(self):
+        _, err = self._run('--emit-digest', 'digest.md')
+        self.assertIn('Generated: digest.md', err)
+
+    def test_emit_digest_coexists_with_excel_and_emit_json(self):
+        self._run('--emit-digest', 'digest.md', '--excel', 'defs.xlsx', '--emit-json', 'snap.json')
+        self.assertTrue((Path(self.tmp.name) / 'erd.html').exists())
+        self.assertTrue((Path(self.tmp.name) / 'defs.xlsx').exists())
+        self.assertTrue((Path(self.tmp.name) / 'snap.json').exists())
+        self.assertTrue((Path(self.tmp.name) / 'digest.md').exists())
+
+
+class TestCLIOutputCollision(_EmitDigestDriver):
+    def test_emit_digest_colliding_with_html_output_errors(self):
+        with self.assertRaises(SystemExit):
+            self._run('-o', 'same.md', '--emit-digest', 'same.md')
+
+    def test_emit_digest_colliding_with_emit_json_errors(self):
+        with self.assertRaises(SystemExit):
+            self._run('--emit-digest', 'same.out', '--emit-json', 'same.out')
+
+    def test_distinct_paths_and_stdout_do_not_collide(self):
+        out, _ = self._run('-o', 'erd.html', '--emit-digest', '-')
+        self.assertTrue(out.startswith('# testdb'))
+
+
+class TestCLIStdout(_EmitDigestDriver):
+    def test_emit_digest_dash_writes_to_stdout_and_still_generates_html(self):
+        out, _ = self._run('--emit-digest', '-')
+        self.assertIn('### users', out)
+        self.assertTrue((Path(self.tmp.name) / 'erd.html').exists())
+
+
+class TestCLIFiltering(_EmitDigestDriver):
+    def test_only_reflected_including_dangling_association_pruning(self):
+        self._run('--emit-digest', 'digest.md', '--only', 'posts')
+        text = (Path(self.tmp.name) / 'digest.md').read_text()
+        self.assertIn('### posts', text)
+        self.assertNotIn('### users', text)
+        # 'users' filtered out -> posts' belongs_to :user must be pruned as
+        # dangling, so no Rel: line (and no dangling fk→users column note).
+        self.assertNotIn('Rel:', text)
+
+    def test_exclude_reflected(self):
+        self._run('--emit-digest', 'digest.md', '--exclude', 'posts')
+        text = (Path(self.tmp.name) / 'digest.md').read_text()
+        self.assertIn('### users', text)
+        self.assertNotIn('### posts', text)
+
+
+class TestCLIVerbose(_EmitDigestDriver):
+    def test_digest_verbose_has_no_effect_without_emit_digest(self):
+        # accepted but inert with no --emit-digest (mirrors --excel-template's
+        # own "has no effect" pattern) -- just must not error.
+        self._run('--digest-verbose')
+
+    def test_digest_verbose_changes_output(self):
+        plain, _ = self._run('--emit-digest', '-')
+        verbose, _ = self._run('--emit-digest', '-', '--digest-verbose')
+        self.assertNotEqual(plain, verbose)
+
+
+class TestCLIDiffRejectsCombination(_EmitDigestDriver):
+    def test_diff_with_emit_digest_exits_2(self):
+        snap_path = Path(self.tmp.name) / 'snap.json'
+        self._run('--emit-json', str(snap_path))
+        with self.assertRaises(SystemExit) as cm:
+            self._run('--diff', str(snap_path), '--emit-digest', 'digest.md')
+        self.assertEqual(cm.exception.code, 2)
+
+
+class TestByteEquality(_EmitDigestDriver):
+    def test_html_byte_identical_with_and_without_emit_digest(self):
+        self._run('-o', 'a.html')
+        self._run('-o', 'b.html', '--emit-digest', 'digest.md')
+        self.assertEqual((Path(self.tmp.name) / 'a.html').read_bytes(),
+                         (Path(self.tmp.name) / 'b.html').read_bytes())
+
+
+if __name__ == '__main__':
+    unittest.main()