justdocs v1.0.0

justdocs 1.0.0

• release tag: v1.0.0
• target commit: 701348cace66329a42a4e744462402e777021cd5
• previous release: v0.1.0

Included commits

• 4452ad9 fix: harden PR artifact cleanup and release preparation

  Extend PR distribution handling with closed-PR cleanup, run-bound comment
  identity, stale-run artifact deletion, and repository-bound pull-request
  validation. Correct initial release bumping, remove local release-note output,
  and strengthen concurrent GitHub release reads and recovery.

  PR distribution lifecycle:

  • Add a pinned pull_request_target workflow for closed PR cleanup.
  • Restrict lifecycle permissions to actions deletion, repository reads, and PR comment writes.
  • Serialize cleanup per pull request without cancellation.
  • Validate pull-request number, closed state, head SHA, and base repository identity.
  • Delete only justdocs-python-dist artifacts bound to the managed workflow run.
  • Preserve unrelated artifacts during cleanup.
  • Replace the managed bot comment with a terminal unavailable message after closure.
  • Reject multiple managed comments and incomplete comment identities.
  • Encode workflow run ID, attempt, and head SHA in the managed comment marker.
  • Remove stale artifacts when a workflow run targets an outdated PR head.
  • Remove failed-run artifacts before synchronizing unavailable comments.
  • Reconcile older run identities while preventing older runs from replacing newer comments.
  • Extend workflow contract tests for pinned actions, permissions, checkout safety, and cleanup arguments.

  Release preparation:

  • Apply the requested SemVer bump when no stable tag exists.
  • Preserve latest-tag and project-version equality checks for established releases.
  • Stop writing local release-note artifacts during release preparation.
  • Support -- argument forwarding for Just recipe dispatch.
  • Update README and bundled reference documentation with initial-bump and runner-generated release behavior.
  • Document closed-PR artifact deletion and terminal comment synchronization.

  GitHub release transactions:

  • Compare the second release metadata snapshot against all fields except is_latest.
  • Preserve the second metadata snapshot when only latest-release binding changes during asset retrieval.
  • Continue rejecting disappearance or concurrent mutation of every other release field.
  • Return verified post-query metadata with the independently queried asset inventory.
  • Treat committed transactions as idempotent only when published state still matches the journal.
  • Reject committed transaction recovery when published release state diverges.

  Tests:

  • Verify initial major release creation updates pyproject.toml, changelog headings, commit subject, and annotated tag.
  • Verify initial and subsequent release preparation writes no artifacts directory.
  • Verify forwarded patch-bump arguments create the next stable tag.
  • Verify stale PR workflow runs delete their bound artifact and preserve newer comment ownership.
  • Verify closed PR cleanup deletes the bound artifact, preserves unrelated artifacts, and patches one terminal comment.
  • Verify concurrent is_latest mutation during release querying remains accepted while other mutations remain rejected.
  • Extend package workflow assertions to include the lifecycle workflow and its pinned action set.

  Checks:

  • git diff --cached --check passes with no output.
  • PYTHONDONTWRITEBYTECODE=1 PYTHONHASHSEED=0 PYTHONPATH=. python3 -m unittest tests.test_package.ThemePackageTest.test_create_next_release_applies_initial_major_bump_without_artifacts tests.test_package.ThemePackageTest.test_pr_distribution_comment_binds_event_artifact_and_bot_comment tests.test_package.ThemePackageTest.test_pr_distribution_close_removes_artifact_and_terminates_comment tests.test_package.ThemePackageTest.test_release_transaction_rejects_release_race_tag_cas_and_nonmonotonic passes: 4 tests in 2.317 seconds.

  Measurements:

  • Staged scope: 8 files, 420 insertions, 48 deletions.

• 4184429 fix: harden workflow concurrency and release tag isolation

  Scope CI cancellation to each workflow and pull request, cancel superseded
  latest publication runs, and add dependency review for pull requests. Refresh
  pinned security actions, shorten distribution retention, and fetch only
  version-prefixed release tags so a moving latest alias cannot block
  next-release preparation.

  Workflow coordination:

  • group CI runs by workflow and pull-request number or full ref
  • cancel an in-progress latest-main run when a newer run enters the group
  • retain justdocs-python-dist for 30 days instead of 90
  • synchronize the README artifact-retention contract

  Security and provenance:

  • add a pull-request-only dependency-review job on Ubuntu 24.04
  • check out review inputs with the pinned checkout v7 action
  • pin dependency review to an immutable action commit
  • refresh CodeQL initialization and analysis pins within v4
  • refresh the build-provenance attestation pin within v4

  Release preparation:

  • replace broad --tags fetching with --no-tags and explicit refspecs
  • force-refresh every remote branch tracking ref while pruning stale branches
  • fetch only refs/tags/v* into matching local version-tag refs
  • leave moving nonversion tags such as latest outside release preparation

  Tests:

  • extend the security action allowlist for dependency review and refreshed pins
  • require 30-day CI artifact retention and cancellable latest publication
  • create and advance a remote latest tag before next-release preparation
  • require latest to remain intact while the next v* release tag is created

• 701348c release: v1.0.0

justdocs v0.1.0

justdocs 0.1.0

• release tag: v0.1.0
• target commit: 4b579aa74001c955dba511550e364ee196db60d0
• previous release: none

Included commits

• 13a2fd8 Initial commit
• dc28c39 Add justdocs MkDocs theme package

  • Package justdocs 0.1.0 with setuptools metadata, Python 3.10+ support,
    MkDocs >=1.6,<3, console script, theme entry point, and linker plugin entry
    point.
  • Include theme templates, static CSS/JS assets, Mermaid license text, and the
    project Justfile template as setuptools package data.
  • Add justdocs theme-dir to validate and print the bundled MkDocs theme path.
  • Add justdocs init to write project-local Justfiles with root, MkDocs config,
    bind address, package spec, and forced overwrite controls.
  • Add typed asset errors for incomplete theme and project template bundles.
  • Add project Justfile generation with frozen config, address-derived port,
    placeholder replacement, existing-file preservation, forced regeneration, and
    editable install flag rejection.
  • Add source Justfile recipes for package install, theme path lookup, unit tests,
    generated example Justfile refresh, strict example build, serve, and aggregate
    check.
  • Add generated project recipes for install, check/build, serve, serve-clean,
    free-port, clean, dist-clean, env overrides, local source install locking via
    flock, and pymdown-extensions==10.12.
  • Add MkDocs theme config extending stock MkDocs with 404 template, navigation
    depth, primary nav style, color mode, and user color mode toggle.
  • Add base, main, and 404 templates for topbar, left navigation, right TOC,
    pagination, mobile navigation, search, theme toggle, preferences, sidebar
    controls, sidebar resizers, sidebar restore buttons, and drawer scrim.
  • Inject extra.justdocs palette, typography, shape, layout, preference,
    feature, sidebar, breakpoint, and search values into CSS tokens and
    window.JUSTDOCS.
  • Add theme CSS for responsive grid layout, drawer/mobile states, collapsible
    sidebars, resizable rails, preferences, search results, light/dark tokens,
    table labels, mobile table cards, code blocks, linked inline code, Mermaid
    blocks, reduced motion, and print output.
  • Add theme JS for viewport state, topbar height sync, sidebar width clamping,
    localStorage sidebar state, pointer and keyboard resizing, preferences
    persistence, preferences reset, local search loading, result scoring, snippet
    highlighting, navigation scroll persistence, theme switching, table labels,
    Highlight.js setup, code copy setup, and Mermaid render/re-render.
  • Bundle Highlight.js v11.9.0 GitHub Dark CSS/JS, copy-button CSS/JS with
    browser global export, Mermaid JS, and Mermaid MIT license text.
  • Add justdocs-linker to collect heading, page-stem, and action-ID targets;
    remove stop phrases and ambiguous targets; normalize whitespace, dashes, and
    case; compute relative URLs; protect fences, links, reference definitions,
    tags, headings, and inline code; and bound links per page and per target.
  • Link inline action IDs matching P\d+-\d{4} while preserving fenced code and
    existing Markdown links.
  • Add an executable example site with search, justdocs-linker,
    pymdownx.highlight, Mermaid superfences, TOC permalinks, complete
    extra.justdocs configuration, and pages covering Service Discovery,
    Deployment Guide, Traffic Policy, tables, code, and Mermaid.
  • Add reference content recording theme, search, smart-link, and complexity
    contracts, including O(n), O(p * q), and O(p * t * s) operation bounds.
  • Expand README from a stub into package, configuration, CLI, generated recipe,
    source command, and runtime behavior reference.
  • Add audit artifact mapping project Justfile generation files, flows, guards,
    deterministic invariants, scope completion, and verification evidence.
  • Ignore generated examples/**/site/ outputs.
  • Add 23 unittest cases covering packaged assets, template availability,
    Justfile rendering, overwrite refusal, forced overwrite, editable package spec
    rejection, theme metadata, template assets, sidebar controls, preferences,
    Mermaid, code copy, feature gates, CSS layout contracts, example config,
    relative URLs, prose/table smart links, and inline action-ID links.

• ba6433b Refresh Justdocs docs and example contract coverage

  • Expand the README into a complete Justdocs reference for package metadata,
    Python and MkDocs requirements, console script binding, theme entry point,
    plugin entry point, packaged theme assets, and the project Justfile template.
  • Document the full MkDocs integration surface with search,
    justdocs-linker, tables, pymdownx.highlight, Mermaid superfences, TOC
    permalinks, and the complete extra.justdocs config shape.
  • Define every documented theme config default for title, favicon, palette,
    typography, shape, content width, density, motion, breakpoints, sidebars,
    preferences, feature gates, and client search limits.
  • Add browser runtime contracts for viewport datasets, compact topbar state,
    small viewport state, theme, density, content width, motion, sidebar state,
    sidebar widths, nav scroll storage, search index resolution, search scoring,
    Mermaid initialization, and sidebar resizing keys.
  • Document justdocs theme-dir and justdocs init CLI behavior, including
    asset validation, generated Justfile output, init flags, overwrite policy, and
    typed failure classes.
  • Document generated project recipes for install, check, build, serve,
    serve-clean, free-port, clean, and dist-clean, including every
    JUSTDOCS_* environment override.
  • Record local source install locking through flock, lock directory layout,
    extra package installation with pymdown-extensions==10.12, and editable
    install rejection.
  • Add source-repo recipe docs for local package install, theme path lookup,
    example Justfile regeneration, unit tests, strict example build, example
    serve, and aggregate check.
  • Define justdocs-linker plugin config defaults for enabled state, minimum
    phrase length, per-page link cap, and per-target link cap.
  • Document smart-link target generation from page H1s, ATX headings, file
    stems, action stems, and action IDs.
  • Document smart-link filtering for stop phrases, ambiguous phrases, phrase
    eligibility, deterministic ordering, and current-page exclusions.
  • Document protected Markdown ranges for fenced code, existing links, reference
    definitions, HTML tags, ATX headings, inline code, and linkable inline action
    IDs.
  • Add complexity bounds for target collection, target dedupe, protected range
    merging, smart-link passes, theme asset validation, template rendering, and
    search scoring.
  • Add packaged asset and runtime error reference tables covering required theme
    files, Highlight.js assets, copy-button assets, Mermaid assets, template
    files, search failures, missing controls, and missing browser globals.
  • Replace the example service-topic docs with Justdocs-specific pages for
    Theme Configuration, Project Setup, Smart Links, and Reference.
  • Update the example index to exercise the current docs graph, runtime feature
    table, required MkDocs plugins, Mermaid rendering, Python API snippet, and
    mobile table label behavior.
  • Add explicit example nav entries for Theme Configuration, Project Setup,
    Smart Links, and Reference in examples/basic/mkdocs.yml.
  • Remove obsolete Service Discovery, Deployment Guide, and Traffic Policy
    example pages from the staged docs surface.
  • Extend docs tests to require the new example nav entries, verify README and
    example docs both cover current contract terms, and reject stale service-topic
    terms from the example docs.
  • Update smart-link table/prose tests to use current Justdocs page targets while
    preserving coverage for tables, prose, inline code protection, existing link
    preservation, and Mermaid fenced code protection.
  • Keep staged scope to 11 files with 648 insertions and 117 deletions across
    README, example docs, example nav, and docs coverage tests.

• 15edb7e perf: compile smart-link targets into one match graph

  Build a compiled smart-link graph during MkDocs file discovery and reuse it
  while each page is linked, replacing repeated per-target regex scans with one
  aggregate matcher plus normalized-key lookup.

  Smart-link compilation:

  • Replace per-target compiled regex storage with normalized target keys and
    reusable pattern text.
  • Add CompiledLinkGraph for compiled targets, exact-key target lookup, and an
    optional aggregate regex.
  • Build empty target sets as pattern=None so link segments return unchanged
    without regex work.

  Linking behavior:

  • Change _link_segment() to search the aggregate regex from each cursor
    position instead of scanning every target pattern.
  • Resolve matches through normalized match.group(0) keys before applying
    self-link and per-target cap checks.
  • Keep unmatched, current-page, and cap-exhausted matches as plain t...

Latest Nightly Build (701348cace66)

justdocs latest

• branch: main
• target commit: 701348cace66329a42a4e744462402e777021cd5
• base stable release: v1.0.0

Included commits

• No commits beyond the previous release boundary.