clearancewatch 0.1.0__py3-none-any.whl

clearancewatch/__init__.py

@@ -0,0 +1,16 @@
+"""clearancewatch — per-job subcontractor compliance: clearances, insurance, licences.
+
+Not legal advice. Rules modelled from official sources (see README), verified
+October 2026: WSIB clearances are valid up to 90 days and a principal must hold
+a valid clearance for the whole job; WCB Alberta clearance letters cover work up
+to the date of the letter.
+"""
+
+from .model import Clearance, Insurance, Job, Licence, Subcontractor
+from .audit import Finding, audit, renewals
+
+__version__ = "0.1.0"
+__all__ = [
+    "Job", "Subcontractor", "Clearance", "Insurance", "Licence",
+    "audit", "renewals", "Finding", "__version__",
+]

clearancewatch/audit.py

@@ -0,0 +1,140 @@
+"""Audit a job's subcontractors against the job calendar.
+
+Severity model: things that expose the principal to deeming/penalty risk are
+errors (missing or expired clearance, lapsed coverage, expired insurance or
+licence); things that are still legal today but will bite soon are warnings
+(expiring during the job, renewal horizon).
+"""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+from typing import List
+
+from .model import Job, Subcontractor, WSIB_DEFAULT_VALID_DAYS
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: str  # error | warn
+    code: str
+    subject: str   # "job / sub"
+    detail: str
+
+    def as_dict(self):
+        return {"severity": self.severity, "code": self.code,
+                "subject": self.subject, "detail": self.detail}
+
+
+def _issuer_family(issuer: str) -> str:
+    u = (issuer or "").upper()
+    if "WSIB" in u:
+        return "ON"
+    if u.startswith("WCB") or "WORKERS" in u:
+        return "AB" if ("AB" in u or "ALBERTA" in u) else "WCB"
+    return ""
+
+
+def _check_clearance(f: List[Finding], sub: Subcontractor, job: Job,
+                     on: dt.date, horizon: int, valid_days: int) -> None:
+    who = f"{job.name} / {sub.name}"
+    c = sub.clearance
+    if c is None or (not c.issuer and not c.issued and not c.expires):
+        f.append(Finding("error", "clearance_missing", who,
+                         "no clearance certificate on file"))
+        return
+
+    family = _issuer_family(c.issuer)
+    if job.province and family and family not in (job.province, "WCB"):
+        f.append(Finding("warn", "issuer_mismatch", who,
+                         f"job is in {job.province} but clearance issuer is {c.issuer!r}"))
+
+    if family == "AB" or c.covered_until is not None:
+        # Alberta letters: cover work done up to the letter date
+        cover = c.covered_until or c.issued
+        if cover is None:
+            f.append(Finding("error", "clearance_no_coverage_dates", who,
+                             "Alberta-style clearance needs issued/covered_until dates"))
+            return
+        horizon_date = job.end or on
+        if horizon_date > cover:
+            f.append(Finding("warn", "clearance_cover_lapsed", who,
+                             f"letter covers work up to {cover.isoformat()}; work continues past it "
+                             "(request a fresh clearance at the next installment)"))
+        return
+
+    expiry = c.effective_expiry(valid_days)
+    if expiry is None:
+        f.append(Finding("error", "clearance_no_expiry", who,
+                         "clearance has neither expiry nor issue date"))
+        return
+    if expiry < on:
+        f.append(Finding("error", "clearance_expired", who,
+                         f"clearance expired {expiry.isoformat()}"))
+    elif job.end and expiry < job.end:
+        f.append(Finding("error", "clearance_expires_during_job", who,
+                         f"clearance expires {expiry.isoformat()} before job end {job.end.isoformat()}; "
+                         "a principal must hold valid clearance for the whole job"))
+    elif (expiry - on).days <= horizon:
+        f.append(Finding("warn", "renewal_due", who,
+                         f"clearance expires {expiry.isoformat()} (within {horizon} days)"))
+
+
+def _check_insurance(f: List[Finding], sub: Subcontractor, job: Job,
+                     on: dt.date, horizon: int) -> None:
+    who = f"{job.name} / {sub.name}"
+    ins = sub.insurance
+    if ins is None or not (ins.provider or ins.policy):
+        f.append(Finding("error", "insurance_missing", who, "no insurance on file"))
+        return
+    if ins.expires is None:
+        f.append(Finding("warn", "insurance_no_expiry", who, "insurance has no expiry date recorded"))
+        return
+    if ins.expires < on:
+        f.append(Finding("error", "insurance_expired", who,
+                         f"insurance expired {ins.expires.isoformat()}"))
+    elif job.end and ins.expires < job.end:
+        f.append(Finding("warn", "insurance_expires_during_job", who,
+                         f"insurance expires {ins.expires.isoformat()} before job end"))
+    elif (ins.expires - on).days <= horizon:
+        f.append(Finding("warn", "insurance_renewal_due", who,
+                         f"insurance expires {ins.expires.isoformat()} (within {horizon} days)"))
+
+
+def _check_licences(f: List[Finding], sub: Subcontractor, job: Job, on: dt.date, horizon: int) -> None:
+    who = f"{job.name} / {sub.name}"
+    for lic in sub.licences:
+        label = lic.name or "licence"
+        if lic.expires is None:
+            f.append(Finding("warn", "licence_no_expiry", who, f"{label}: no expiry recorded"))
+            continue
+        if lic.expires < on:
+            f.append(Finding("error", "licence_expired", who,
+                             f"{label} expired {lic.expires.isoformat()}"))
+        elif job.end and lic.expires < job.end:
+            f.append(Finding("warn", "licence_expires_during_job", who,
+                             f"{label} expires {lic.expires.isoformat()} before job end"))
+        elif (lic.expires - on).days <= horizon:
+            f.append(Finding("warn", "licence_renewal_due", who,
+                             f"{label} expires {lic.expires.isoformat()} (within {horizon} days)"))
+
+
+def audit(job: Job, on: dt.date | None = None, horizon: int = 30,
+          valid_days: int = WSIB_DEFAULT_VALID_DAYS) -> List[Finding]:
+    """All compliance findings for one job as of ``on`` (default: today)."""
+    on = on or dt.date.today()
+    out: List[Finding] = []
+    for sub in job.subs:
+        _check_clearance(out, sub, job, on, horizon, valid_days)
+        _check_insurance(out, sub, job, on, horizon)
+        _check_licences(out, sub, job, on, horizon)
+    return out
+
+
+def renewals(jobs: List[Job], within: int = 30, on: dt.date | None = None) -> List[Finding]:
+    """Everything across jobs that needs a renewal touch within ``within`` days."""
+    on = on or dt.date.today()
+    out: List[Finding] = []
+    for job in jobs:
+        out.extend(f for f in audit(job, on=on, horizon=within) if "due" in f.code or "lapsed" in f.code)
+    return out

clearancewatch/cli.py

@@ -0,0 +1,71 @@
+"""clearancewatch CLI: audit jobs.json for compliance gaps."""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+from typing import List
+
+from . import __version__
+from .audit import audit, renewals
+from .model import Job
+
+
+def load_jobs(path: str) -> List[Job]:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except FileNotFoundError:
+        raise SystemExit(f"clearancewatch: not found: {path}")
+    except json.JSONDecodeError as e:
+        raise SystemExit(f"clearancewatch: invalid JSON: {e}")
+    if isinstance(data, dict):
+        data = data.get("jobs", [data])
+    return [Job.from_dict(d) for d in data]
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="clearancewatch",
+        description="Audit subcontractor clearance/insurance/licence coverage against job calendars.",
+    )
+    ap.add_argument("--version", action="version", version=f"clearancewatch {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    a = sub.add_parser("audit", help="full audit; exit 1 when any error-severity finding exists")
+    a.add_argument("jobs", help="jobs JSON file (list, or {\"jobs\": [...]})")
+    a.add_argument("--on", metavar="YYYY-MM-DD", help="audit date (default: today)")
+    a.add_argument("--within", type=int, default=30, help="renewal horizon in days (default 30)")
+    a.add_argument("--json", action="store_true")
+
+    r = sub.add_parser("renewals", help="only what's due soon; exit 1 if anything is due")
+    r.add_argument("jobs")
+    r.add_argument("--within", type=int, default=30)
+    r.add_argument("--on", metavar="YYYY-MM-DD")
+    r.add_argument("--json", action="store_true")
+
+    args = ap.parse_args(argv)
+    on = dt.date.fromisoformat(args.on) if args.on else None
+    jobs = load_jobs(args.jobs)
+
+    if args.cmd == "audit":
+        findings = [f for job in jobs for f in audit(job, on=on, horizon=args.within)]
+    else:
+        findings = renewals(jobs, within=args.within, on=on)
+
+    errors = [f for f in findings if f.severity == "error"]
+    warns = [f for f in findings if f.severity == "warn"]
+    if args.json:
+        print(json.dumps({"errors": len(errors), "warnings": len(warns),
+                          "findings": [f.as_dict() for f in findings]}, indent=2))
+    else:
+        for f in findings:
+            print(f"{f.severity.upper():5} {f.code:28} {f.subject}: {f.detail}")
+        print(f"\n{len(errors)} error(s), {len(warns)} warning(s) — "
+              f"{'FAIL' if errors else 'PASS'}")
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

clearancewatch/model.py

@@ -0,0 +1,110 @@
+"""Data model: jobs, subcontractors, and the documents that keep them legal."""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+WSIB_DEFAULT_VALID_DAYS = 90  # WSIB: clearance certificates valid up to 90 days
+
+
+def parse_date(value: Optional[str]) -> Optional[dt.date]:
+    if value in (None, ""):
+        return None
+    return dt.date.fromisoformat(str(value))
+
+
+@dataclass
+class Clearance:
+    """A workers'-compensation clearance certificate.
+
+    Ontario (WSIB): has a real expiry — ``expires``, defaulting to issued +
+    90 days when not stated.
+    Alberta (WCB): a clearance letter covers work done UP TO the date of the
+    letter — model that as ``covered_until`` (defaults to ``issued``).
+    """
+
+    issuer: str = ""            # e.g. "WSIB", "WCB-AB"
+    number: str = ""
+    issued: Optional[dt.date] = None
+    expires: Optional[dt.date] = None
+    covered_until: Optional[dt.date] = None  # Alberta-style letter coverage
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Clearance":
+        return cls(issuer=d.get("issuer", ""), number=d.get("number", ""),
+                   issued=parse_date(d.get("issued")), expires=parse_date(d.get("expires")),
+                   covered_until=parse_date(d.get("covered_until")))
+
+    def effective_expiry(self, valid_days: int = WSIB_DEFAULT_VALID_DAYS) -> Optional[dt.date]:
+        if self.expires:
+            return self.expires
+        if self.issued and self.covered_until is None:
+            return self.issued + dt.timedelta(days=valid_days)
+        return self.covered_until or self.expires
+
+
+@dataclass
+class Insurance:
+    provider: str = ""
+    policy: str = ""
+    coverage: str = ""          # e.g. "C$2M liability"
+    expires: Optional[dt.date] = None
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Insurance":
+        return cls(provider=d.get("provider", ""), policy=d.get("policy", ""),
+                   coverage=d.get("coverage", ""), expires=parse_date(d.get("expires")))
+
+
+@dataclass
+class Licence:
+    name: str = ""              # e.g. "309A electrical"
+    number: str = ""
+    authority: str = ""         # e.g. "TSSA", "ESA"
+    expires: Optional[dt.date] = None
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Licence":
+        return cls(name=d.get("name", ""), number=d.get("number", ""),
+                   authority=d.get("authority", ""), expires=parse_date(d.get("expires")))
+
+
+@dataclass
+class Subcontractor:
+    name: str
+    province: str = ""
+    trade: str = ""
+    clearance: Optional[Clearance] = None
+    insurance: Optional[Insurance] = None
+    licences: List[Licence] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Subcontractor":
+        return cls(
+            name=d.get("name", "unnamed sub"),
+            province=d.get("province", ""),
+            trade=d.get("trade", ""),
+            clearance=Clearance.from_dict(d["clearance"]) if d.get("clearance") else None,
+            insurance=Insurance.from_dict(d["insurance"]) if d.get("insurance") else None,
+            licences=[Licence.from_dict(x) for x in d.get("licences", [])],
+        )
+
+
+@dataclass
+class Job:
+    name: str
+    province: str = ""
+    start: Optional[dt.date] = None
+    end: Optional[dt.date] = None  # None = ongoing
+    subs: List[Subcontractor] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Job":
+        return cls(
+            name=d.get("name", "unnamed job"),
+            province=d.get("province", ""),
+            start=parse_date(d.get("start")),
+            end=parse_date(d.get("end")),
+            subs=[Subcontractor.from_dict(s) for s in d.get("subs", d.get("subcontractors", []))],
+        )

clearancewatch-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: clearancewatch
+Version: 0.1.0
+Summary: Track subcontractor compliance per job: WSIB/WCB clearance coverage, insurance and licence expiry against the job calendar
+Author: calasdan-sketch
+License-Expression: MIT
+Keywords: wsib,wcb,clearance,compliance,construction,trades,insurance
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# clearancewatch
+
+**A principal must hold valid workers'-comp coverage for every sub — for the whole job.** `clearancewatch` audits subcontractor compliance documents against the job calendar and tells you what's expired, what expires mid-job, and what's coming up for renewal.
+
+Rules modelled from official sources (verified October 2026):
+
+- **Ontario WSIB**: clearance certificates are valid **up to 90 days**; WSIB states a principal must ensure a valid clearance is in place for the **full length of a job**. ([wsib.ca clearances](https://www.wsib.ca/en/businesses/premiums-and-payment/clearances))
+- **Alberta WCB**: a clearance letter is valid for work done **up to the date of the letter** — WCB advises requesting one at hire and before each installment. ([wcb.ab.ca clearance letters](https://www.wcb.ab.ca/insurance-and-premiums/clearance-letters/))
+
+> **This is not legal advice.** It's a date-tracking assistant built on the rules above; confirm obligations with your broker, WSIB/WCB, or counsel.
+
+## Install
+
+```bash
+pip install clearancewatch
+```
+
+## Jobs file
+
+```json
+[
+  {
+    "name": "Kitchen reno",
+    "province": "ON",
+    "start": "2026-02-01",
+    "end": "2026-03-30",
+    "subs": [
+      {
+        "name": "Bob's Drywall",
+        "trade": "drywall",
+        "clearance": { "issuer": "WSIB", "number": "1234567", "issued": "2026-01-10", "expires": "2026-04-10" },
+        "insurance": { "provider": "Aviva", "policy": "GL-9", "coverage": "C$2M", "expires": "2026-12-31" },
+        "licences": [ { "name": "Fall protection", "expires": "2026-09-01" } ]
+      }
+    ]
+  }
+]
+```
+
+## Usage
+
+```bash
+clearancewatch audit jobs.json --on 2026-02-15 --within 30
+clearancewatch renewals jobs.json --within 30     # just what's coming due
+clearancewatch audit jobs.json --json             # machine-readable
+```
+
+```
+ERROR clearance_expires_during_job  Kitchen reno / Bob's Drywall: clearance expires 2026-03-15 before job end 2026-03-30...
+WARN  renewal_due                   Kitchen reno / Bob's Drywall: insurance expires 2026-03-05 (within 30 days)
+
+1 error(s), 1 warning(s) — FAIL
+```
+
+Exit `1` when any error-severity finding exists (missing/expired clearance, lapsed coverage, expired insurance or licence) — CI- and cron-friendly.
+
+## What it catches
+
+| Finding | Severity |
+|---|---|
+| `clearance_missing` / `clearance_expired` / `clearance_expires_during_job` | error |
+| `clearance_cover_lapsed` (Alberta letter predates ongoing work) | warn |
+| `issuer_mismatch` (ON job, WCB-AB clearance — or vice versa) | warn |
+| `insurance_missing` / `insurance_expired` | error |
+| `insurance_expires_during_job` | warn |
+| `licence_expired` | error |
+| `renewal_due` / `insurance_renewal_due` / `licence_renewal_due` (within `--within` days) | warn |
+
+## Python API
+
+```python
+import datetime as dt
+from clearancewatch import Job, audit
+
+job = Job.from_dict({...})
+for finding in audit(job, on=dt.date(2026, 2, 15), horizon=30):
+    print(finding.severity, finding.code, finding.detail)
+```
+
+`clearancewatch renewals` over a weekly cron gives you the "call these three subs" list before a gap becomes a deeming problem.
+
+## License
+
+MIT-style: use it, ship it, no warranty.

clearancewatch-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+clearancewatch/__init__.py,sha256=OuBGzzV4ee68RZyM5y_pSK4cLOGZEbPMgYwgPBCjTCg,627
+clearancewatch/audit.py,sha256=B-wK7GR_iFETVHjVD-Kvo2A-ICwqM0_J8jT-jsZPWz8,6155
+clearancewatch/cli.py,sha256=8CazgVqHAlqkiCZixYQNs9ndSlPixIw6EhcHyyrT44I,2707
+clearancewatch/model.py,sha256=O6GwtTqkmjvleUJVHIj-jEhbUutCZ9gGPuF49Q9ybKw,3837
+clearancewatch-0.1.0.dist-info/licenses/LICENSE,sha256=f409aSdfGpgy5kMR99eFaIPNwFDJfW41IpiNE_elcZ0,1072
+clearancewatch-0.1.0.dist-info/METADATA,sha256=AB-JaaqhymAfYSbGBlxhA6npXrJHT38yC2-rME90Y4k,3837
+clearancewatch-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+clearancewatch-0.1.0.dist-info/entry_points.txt,sha256=teTSw-29UThfWcYyWUsOaDe2p5u9hDACg5MiPtqFtBE,59
+clearancewatch-0.1.0.dist-info/top_level.txt,sha256=Iz8KR5GNSwQmIliEamxT7UioJPjGpleXnFY01cYB6mc,15
+clearancewatch-0.1.0.dist-info/RECORD,,

clearancewatch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clearancewatch-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clearancewatch = clearancewatch.cli:main

clearancewatch-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calasdan-sketch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clearancewatch-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clearancewatch