dbml-sharepoint 0.4.0__py3-none-any.whl

dbml_sharepoint/__init__.py

@@ -0,0 +1,43 @@
+"""DBML -> SharePoint Online list provisioning via browser-console deploy.js.
+
+Every name an extension author needs is imported from the module that defines
+it, and no module here declares another module's name as its own. An
+aggregator would need an export list, or a redundant `import X as X`, to
+survive `mypy --strict`, and either gives a name a second home to be kept in
+step with the first.
+
+An old path such as `dbml_sharepoint.analysis.validator.Finding` does still
+resolve at RUNTIME: a normal `from x import Y` binds `Y` in the importing
+module and Python offers no way to unbind it. `mypy --strict` refuses it
+("does not explicitly export attribute", checked 2026-08-17), which is what
+makes the paths below the supported ones rather than merely the preferred
+ones.
+
+The paths below are the canonical ones. `test/test_public_api.py` imports each
+of them, so a name that moves fails there rather than in a reader's editor.
+
+The extension protocol, in `dbml_sharepoint.extension`:
+
+- `dbml_sharepoint.extension.DeploymentExtension` is the protocol: hook names,
+  parameter order, return types.
+- `dbml_sharepoint.extension.BaseExtension` is the no-op base to subclass.
+- `dbml_sharepoint.extension.SiteContext` is the per-build input `seed_lists`
+  receives.
+- `dbml_sharepoint.extension.ManifestExtras` is what `manifest_extras` returns.
+
+What a hook reports, in `dbml_sharepoint.analysis.findings`:
+
+- `dbml_sharepoint.analysis.findings.Finding` is one reported problem.
+- `dbml_sharepoint.analysis.findings.FindingCode` is its stable code.
+- `dbml_sharepoint.analysis.findings.Severity` is "error" or "warning"; an
+  error aborts the build.
+- `dbml_sharepoint.analysis.findings.Location` is where the finding was found.
+
+What a hook is given, from the parsed inputs:
+
+- `dbml_sharepoint.model.mapping_types.MappingBundle` is the loaded mapping.
+- `dbml_sharepoint.model.parser.Schema`, `dbml_sharepoint.model.parser.Table`
+  and `dbml_sharepoint.model.parser.Column` are the parsed DBML.
+"""
+
+__version__ = "0.4.0"  # x-release-please-version

dbml_sharepoint/analysis/__init__.py

@@ -0,0 +1 @@
+"""Analysis layer: fail-closed build-time rules, ordering, and SP projections."""

dbml_sharepoint/analysis/checks/__init__.py

@@ -0,0 +1,44 @@
+# src/dbml_sharepoint/analysis/checks/__init__.py
+"""Mapping checks, one module per family.
+
+``validate_against_mapping`` was a single function of about 1,200 lines
+covering eighteen unrelated concerns. Each family now lives in its own
+module behind the same ``check(vc) -> list[Finding]`` signature, so a
+reader looking for one rule opens one file.
+
+CHECK_FAMILIES is ordered, and the order is part of the contract: findings
+are reported in it, and tests assert on the sequence. Later families also
+rely on earlier ones having reported structural problems. The formatting
+checks skip an unknown entity rather than re-report it, because _structure
+has already errored on it. Append rather than reorder.
+"""
+
+from collections.abc import Callable
+
+from dbml_sharepoint.analysis.checks import (
+    _demo,
+    _formatting,
+    _naming,
+    _permissions,
+    _provenance,
+    _renames,
+    _retirement,
+    _sources,
+    _structure,
+    _views,
+)
+from dbml_sharepoint.analysis.checks.context import ValidationContext
+from dbml_sharepoint.analysis.findings import Finding
+
+CHECK_FAMILIES: tuple[Callable[[ValidationContext], list["Finding"]], ...] = (
+    _structure.check,
+    _views.check,
+    _demo.check,
+    _formatting.check,
+    _retirement.check,
+    _naming.check,
+    _sources.check,
+    _permissions.check,
+    _provenance.check,
+    _renames.check,
+)

dbml_sharepoint/analysis/checks/_demo.py

@@ -0,0 +1,292 @@
+# src/dbml_sharepoint/analysis/checks/_demo.py
+"""Demo rows seeded by ``--seed``."""
+
+import datetime as dt
+import re
+
+from dbml_sharepoint.analysis.checks.context import ValidationContext
+from dbml_sharepoint.analysis.demo_marker import DEMO_TITLE_PREFIX
+from dbml_sharepoint.analysis.findings import Finding, FindingCode, Location, Section
+from dbml_sharepoint.analysis.rendered_columns import rendered_columns
+from dbml_sharepoint.analysis.typemap import (
+    DATE_TYPES,
+    TODAY_SENTINEL,
+    choice_enum_for,
+    element_type,
+    is_hyperlink,
+    is_multi_value,
+    is_person,
+)
+
+_DEMO_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def check(vc: ValidationContext) -> list[Finding]:
+    bundle = vc.bundle
+    tables_by_name = vc.tables_by_name
+    enum_by_name = vc.enum_by_name
+    cross_site_by_entity = vc.cross_site_by_entity
+    findings: list[Finding] = []
+    # Demo rows (--seed): everything checkable at build time IS checked.
+    # A demo paste failing live in front of an audience is exactly the
+    # failure class this tool exists to prevent.
+    demo_keys: dict[str, str] = {}
+    for entity_name, demo_rows in bundle.mapping.demo_items.items():
+        if entity_name not in tables_by_name or entity_name not in bundle.mapping.entities:
+            findings.append(Finding(
+                FindingCode.UNKNOWN_ENTITY, f"demo_items[{entity_name}]: unknown entity.",
+                location=Location(Section.DEMO_ITEMS, entity=entity_name),
+            ))
+            continue
+        # A document library's items ARE files. demo-data.js POSTs to
+        # /items, and SharePoint refuses that on a library outright:
+        # HTTP 500, "To add an item to a document library, use
+        # SPFileCollection.Add()" (probed 2026-07-29,
+        # test/manual/document-library-probe.js,
+        # `library.file-vs-item.fileless-item-post`, L2 in that run).
+        #
+        # So the paste fails, loudly, in front of whoever was being shown
+        # the demo. Refusing at build turns that into a failed build.
+        # Seeding a library would mean uploading real files, which is a
+        # different feature from writing list rows and is not one this tool
+        # has.
+        if bundle.mapping.entities[entity_name].kind == "DocumentLibrary":
+            findings.append(Finding(
+                FindingCode.DEMO_ROWS_ON_DOCUMENT_LIBRARY,
+                f"demo_items[{entity_name}]: {entity_name} is a DocumentLibrary, and a "
+                f"library's items are files. Seeding posts to /items, which SharePoint "
+                f"refuses outright -- HTTP 500, \"To add an item to a document library, "
+                f"use SPFileCollection.Add()\" -- so the paste fails in front of whoever "
+                f"was being shown the demo. Seed the register list that accompanies the "
+                f"library, and upload sample documents by hand.",
+                location=Location(Section.DEMO_ITEMS, entity=entity_name),
+            ))
+            continue
+        for row in demo_rows:
+            if row.key in demo_keys:
+                findings.append(Finding(
+                    FindingCode.DUPLICATE_DEMO_KEY,
+                    f"demo_items[{entity_name}].{row.key}: duplicate demo "
+                    f"key (also declared under {demo_keys[row.key]}).",
+                    location=Location(
+                        Section.DEMO_ITEMS, entity=entity_name, sub=row.key,
+                    ),
+                ))
+            else:
+                demo_keys[row.key] = entity_name
+    for entity_name, demo_rows in bundle.mapping.demo_items.items():
+        demo_table = tables_by_name.get(entity_name)
+        if demo_table is None or entity_name not in bundle.mapping.entities:
+            continue
+        xcols = cross_site_by_entity.get(entity_name, set())
+        demo_writable = rendered_columns(demo_table, xcols) | {"Title"}
+        demo_types = {c.name: c.type for c in demo_table.columns}
+        columns = {c.name: c for c in demo_table.columns}
+        row_positions = {row.key: position for position, row in enumerate(demo_rows)}
+        for position, row in enumerate(demo_rows):
+            ctx = f"demo_items[{entity_name}].{row.key}"
+            at = Location(Section.DEMO_ITEMS, entity=entity_name, sub=row.key)
+            demo_title = row.values.get("Title")
+            if not isinstance(demo_title, str) or not demo_title.startswith(
+                DEMO_TITLE_PREFIX,
+            ):
+                findings.append(Finding(
+                    FindingCode.DEMO_TITLE_MISSING_MARKER,
+                    f"{ctx}: Title must start with '{DEMO_TITLE_PREFIX}' -- the "
+                    f"visible notice that identifies this declared row as sample "
+                    f"data. Rollback requires per-list confirmation before every delete.",
+                    location=at,
+                ))
+            for col_name, value in row.values.items():
+                col_type = demo_types.get(col_name)
+                if col_name not in demo_writable or col_name == "Id":
+                    findings.append(Finding(
+                        FindingCode.DEMO_COLUMN_NOT_WRITABLE,
+                        f"{ctx}: values references {col_name!r}, which is "
+                        f"not a writable column of {entity_name}.",
+                        location=at,
+                    ))
+                    continue
+                if isinstance(col_type, str) and col_type.startswith("calculated"):
+                    findings.append(Finding(
+                        FindingCode.DEMO_VALUE_ON_CALCULATED_COLUMN,
+                        f"{ctx}: {col_name} is a calculated column; demo "
+                        f"rows cannot write it (set its inputs instead).",
+                        location=at,
+                    ))
+                    continue
+                # ARITY IS ANSWERED FIRST, because every rule below reads one
+                # scalar and a rule handed a list reports the wrong fault.
+                if is_multi_value(col_type or ""):
+                    if not isinstance(value, list):
+                        findings.append(Finding(
+                            FindingCode.DEMO_MULTI_VALUE_NOT_A_LIST,
+                            f"{ctx}: {col_name} is a multi-value column "
+                            f"({col_type}), so its demo value must be a list of "
+                            f"members, got {value!r}. An empty list is accepted "
+                            f"and leaves the column unset.",
+                            location=at,
+                        ))
+                        continue
+                    # Compared by list rather than by set: a demo value can
+                    # hold an unhashable member, and these lists are tiny.
+                    seen: list[object] = []
+                    repeated: list[object] = []
+                    for member in value:
+                        if member not in seen:
+                            seen.append(member)
+                        elif member not in repeated:
+                            repeated.append(member)
+                    for member in repeated:
+                        findings.append(Finding(
+                            FindingCode.DEMO_MULTI_VALUE_DUPLICATE_MEMBER,
+                            f"{ctx}: {col_name} repeats {member!r}. The write "
+                            f"shape measured as M3 on 2026-08-17 is a collection "
+                            f"of choices and nothing "
+                            f"has measured what a repeat reads back as, so declare "
+                            f"each member once.",
+                            location=at,
+                        ))
+                # Hyperlinks are checked before the object-value rule below,
+                # and in BOTH authored shapes:
+                # a URL column takes a bare address or a {url, description}
+                # record. Gating this on `isinstance(value, dict)` left the
+                # scalar form unchecked, and the generator DOES refuse a
+                # non-string there, so an invalid mapping surfaced as a build
+                # traceback rather than a finding. A validator must refuse
+                # everything its generator refuses, and refuse it first.
+                if is_hyperlink(col_type):
+                    if isinstance(value, dict):
+                        unknown = set(value) - {"url", "description"}
+                        if unknown or "url" not in value:
+                            findings.append(Finding(
+                                FindingCode.DEMO_HYPERLINK_OBJECT_INVALID,
+                                f"{ctx}: {col_name} is a hyperlink; an object value "
+                                f"must be {{url: <address>, description: <label>}} "
+                                f"with 'description' optional. Got keys "
+                                f"{sorted(value)}.",
+                                location=at,
+                            ))
+                            continue
+                        address = value["url"]
+                    else:
+                        address = value
+                    # Checked as a STRING, not stringified: str(None) is
+                    # "None", which is non-empty, so a coerced emptiness test
+                    # passes a null through to become a link pointing at the
+                    # word None.
+                    if not (isinstance(address, str) and address.strip()):
+                        findings.append(Finding(
+                            FindingCode.DEMO_HYPERLINK_ADDRESS_INVALID,
+                            f"{ctx}: {col_name} is a hyperlink; its address must be "
+                            f"a non-empty string, got {address!r}.",
+                            location=at,
+                        ))
+                    continue
+                if isinstance(value, dict):
+                    if set(value) != {"demo_ref"}:
+                        findings.append(Finding(
+                            FindingCode.DEMO_OBJECT_VALUE_INVALID,
+                            f"{ctx}: {col_name} object value must be exactly "
+                            f"{{demo_ref: <key>}}.",
+                            location=at,
+                        ))
+                    elif value["demo_ref"] not in demo_keys:
+                        findings.append(Finding(
+                            FindingCode.DEMO_REF_UNKNOWN_KEY,
+                            f"{ctx}: {col_name} demo_ref "
+                            f"{value['demo_ref']!r} is not a declared demo "
+                            f"key.",
+                            location=at,
+                        ))
+                    else:
+                        column = columns.get(col_name)
+                        target_entity = demo_keys[value["demo_ref"]]
+                        if column is None or column.ref is None:
+                            findings.append(Finding(
+                                FindingCode.DEMO_REF_ON_NON_LOOKUP,
+                                f"{ctx}: {col_name} uses demo_ref but is not a lookup column.",
+                                location=at,
+                            ))
+                        elif column.ref.target_table != target_entity:
+                            findings.append(Finding(
+                                FindingCode.DEMO_REF_TARGET_MISMATCH,
+                                f"{ctx}: {col_name} targets {column.ref.target_table}, but "
+                                f"demo_ref {value['demo_ref']!r} belongs to {target_entity}.",
+                                location=at,
+                            ))
+                        elif (
+                            target_entity == entity_name
+                            and row_positions.get(value["demo_ref"], position) >= position
+                        ):
+                            findings.append(Finding(
+                                FindingCode.DEMO_REF_FORWARD_REFERENCE,
+                                f"{ctx}: {col_name} demo_ref {value['demo_ref']!r} must be "
+                                f"declared before the row that uses it.",
+                                location=at,
+                            ))
+                    continue
+                if is_person(col_type):
+                    if value != "@me":
+                        findings.append(Finding(
+                            FindingCode.DEMO_PERSON_VALUE_UNSUPPORTED,
+                            f"{ctx}: person column {col_name} accepts only "
+                            f"\"@me\" (the deploying operator).",
+                            location=at,
+                        ))
+                    continue
+                # The enum question first: `_resolve_column` resolves an enum
+                # before a scalar, so an enum named `date` is a Choice column
+                # there and has to be one here too.
+                enum_name = choice_enum_for(col_type or "", enum_by_name)
+                # Through `element_type`, because `date[]` is not a key in
+                # DATE_TYPES and the rule read as though it covered the column.
+                if enum_name is None and element_type(col_type or "") in DATE_TYPES:
+                    valid_date = False
+                    if isinstance(value, str) and TODAY_SENTINEL.match(value):
+                        valid_date = True
+                    elif isinstance(value, str) and _DEMO_ISO_DATE.match(value):
+                        try:
+                            dt.date.fromisoformat(value)
+                            valid_date = True
+                        except ValueError:
+                            pass
+                    if not valid_date:
+                        findings.append(Finding(
+                            FindingCode.DEMO_DATE_VALUE_INVALID,
+                            f"{ctx}: date column {col_name} accepts "
+                            f"'today+N'/'today-N' or a real ISO calendar date "
+                            f"(got {value!r}).",
+                            location=at,
+                        ))
+                    continue
+                # The resolver answers with the name; this rule needs the
+                # members behind it.
+                if enum_name is None:
+                    continue
+                demo_enum = enum_by_name[enum_name]
+                # Membership is the same rule per member on a multi-value
+                # column, so it keeps the same code rather than gaining a twin.
+                # The arity test stays here: on a SCALAR enum column a list is
+                # simply not a member, which is what already fires today.
+                declared = (
+                    value
+                    if is_multi_value(col_type or "") and isinstance(value, list)
+                    else [value]
+                )
+                # Distinct, so a member repeated twice is one mistake and one
+                # finding. The duplicate rule above is what reports the repeat.
+                distinct: list[object] = []
+                for member in declared:
+                    if member not in distinct:
+                        distinct.append(member)
+                for member in distinct:
+                    if member not in demo_enum.members:
+                        findings.append(Finding(
+                            FindingCode.DEMO_ENUM_VALUE_UNKNOWN,
+                            f"{ctx}: {col_name} value {member!r} is not a member "
+                            f"of enum {enum_name}.",
+                            location=at,
+                        ))
+
+    return findings