figurelint 0.1.0__tar.gz

figurelint-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q
+      - name: CLI smoke test
+        run: figurelint --help
+
+  package:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install release tooling
+        run: python -m pip install ".[release]"
+      - name: Build wheel and source distribution
+        run: python -m build
+      - name: Validate package metadata
+        run: python -m twine check dist/*
+      - name: Install built wheel in a clean virtual environment
+        run: |
+          python -m venv /tmp/figurelint-wheel
+          /tmp/figurelint-wheel/bin/python -m pip install dist/*.whl
+          /tmp/figurelint-wheel/bin/figurelint --help
+          /tmp/figurelint-wheel/bin/figurelint presets
+
+
+  action-smoke:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run FigureLint as a local composite action
+        uses: ./
+        with:
+          path: examples/svg/before.svg
+          preset: default
+          strict: "false"

figurelint-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build release distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and source distribution
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/figurelint/
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: release-dists
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

figurelint-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

figurelint-0.1.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to FigureLint will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows Semantic Versioning.
+
+## [Unreleased]
+
+### Planned
+- PDF font-size and vector stroke checks
+- color accessibility checks
+- stronger editable-text / outlined-text analysis
+- additional source-verified publisher presets
+
+## [0.1.0] - 2026-09-19
+
+### Added
+- initial FigureLint command-line interface
+- PNG and JPEG inspection
+- unreadable image detection
+- missing / low DPI warnings
+- raster dimension and transparency checks
+- JPEG lossy-format notice
+- SVG file discovery and inspection
+- malformed SVG detection
+- editable-text detection
+- configurable lower and upper SVG font-size checks
+- configurable lower and upper SVG stroke-width checks
+- simple embedded CSS, inline-style, and presentation-attribute resolution
+- PDF file discovery and inspection
+- malformed, encrypted, empty, and multi-page PDF checks
+- PDF page-size guardrails
+- PDF editable-text and font-embedding checks
+- effective DPI checks for embedded PDF raster images
+- PDF raster soft-mask / alpha detection
+- recursive folder scanning
+- strict mode and CI-friendly exit codes
+- native GitHub Actions workflow annotations
+- reusable composite GitHub Action with preset, strict-mode, and threshold inputs
+- preset engine shared across raster, SVG, and PDF checks
+- built-in convenience presets: `default`, `high-resolution`, `presentation`, and `journal-generic`
+- source-verified `nature` preset with official provenance metadata
+- Nature 5–7 pt ordinary SVG text range
+- Nature 0.25–1 pt SVG stroke range
+- conservative Nature multi-panel label recognition with 8 pt bold/upright validation
+- Nature SVG font-family consistency and Arial/Helvetica preference guidance
+- automated tests across Python 3.10, 3.11, and 3.12
+- package build validation for wheel and source distributions
+- PyPI Trusted Publishing workflow using GitHub Actions OIDC
+- official black-cat visual identity and README demo assets
+
+[Unreleased]: https://github.com/coocoomaomao/FigureLint/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/coocoomaomao/FigureLint/releases/tag/v0.1.0

figurelint-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to FigureLint
+
+Thanks for helping improve FigureLint. Contributions from researchers, students, designers, and developers are welcome.
+
+## Good first contributions
+
+Useful beginner-friendly contributions include:
+
+- adding test images for edge cases
+- improving documentation
+- reporting figure-export problems seen in real workflows
+- proposing deterministic checks for SVG or PDF files
+- improving accessibility and color-safety checks
+
+## Development setup
+
+~~~bash
+git clone https://github.com/coocoomaomao/FigureLint.git
+cd FigureLint
+python -m venv .venv
+pip install -e ".[dev]"
+pytest
+~~~
+
+## Design principles
+
+FigureLint should:
+
+1. report verifiable technical properties
+2. avoid pretending one journal rule fits every publication
+3. keep thresholds configurable
+4. explain warnings clearly
+5. remain useful from both the CLI and CI
+
+## Pull requests
+
+Please keep pull requests focused. Add or update tests when behavior changes, and explain the problem the change is intended to solve.
+
+## Issues
+
+Bug reports and feature ideas are welcome. When possible, include the file format, export tool, expected behavior, and a minimal example.
+
+## Brand
+
+Please follow the project visual system documented in [docs/BRAND.md](docs/BRAND.md) when adding public-facing graphics.

figurelint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 coocoomaomao
+
+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.

figurelint-0.1.0/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.5
+Name: figurelint
+Version: 0.1.0
+Summary: Lint academic figures before submission.
+Project-URL: Homepage, https://github.com/coocoomaomao/FigureLint
+Project-URL: Repository, https://github.com/coocoomaomao/FigureLint
+Project-URL: Issues, https://github.com/coocoomaomao/FigureLint/issues
+Project-URL: Changelog, https://github.com/coocoomaomao/FigureLint/blob/main/CHANGELOG.md
+Author: coocoomaomao
+License: MIT License
+        
+        Copyright (c) 2026 coocoomaomao
+        
+        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.
+License-File: LICENSE
+Keywords: academic,figures,lint,pdf,publication,research,svg,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10.3
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=5.1; extra == 'release'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/figurelint-banner.svg" alt="FigureLint — ESLint for academic figures" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/coocoomaomao/FigureLint/actions/workflows/ci.yml">
+    <img src="https://github.com/coocoomaomao/FigureLint/actions/workflows/ci.yml/badge.svg" alt="CI">
+  </a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
+  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status Alpha">
+</p>
+
+> **ESLint for academic figures.**
+
+**FigureLint** is an open-source linter for academic figures. It helps researchers and students catch common technical quality issues before submission.
+
+## Why
+
+A figure can look fine on screen and still cause trouble during submission or production: low effective resolution, missing DPI metadata, tiny raster dimensions, accidental transparency, text converted to outlines, tiny labels, or strokes that become too thin in print.
+
+FigureLint turns those checks into a repeatable command.
+
+## See it in action
+
+<table>
+  <tr>
+    <th>Before — easy-to-miss problems</th>
+    <th>After — publication-safer export</th>
+  </tr>
+  <tr>
+    <td><img src="examples/svg/before.svg" alt="Problematic academic SVG example" width="100%"></td>
+    <td><img src="examples/svg/after.svg" alt="Improved academic SVG example" width="100%"></td>
+  </tr>
+</table>
+
+Run FigureLint on the deliberately problematic example:
+
+~~~bash
+figurelint check examples/svg/before.svg
+~~~
+
+Typical findings:
+
+~~~text
+warning  SVG_FONT_SMALL
+Found 5 text element(s) below 7 pt; smallest resolved size is 5.00 pt.
+
+warning  SVG_STROKE_THIN
+Found 3 stroked element(s) below 0.5 pt; thinnest resolved stroke is 0.30 pt.
+~~~
+
+Now check the improved version:
+
+~~~bash
+figurelint check examples/svg/after.svg
+~~~
+
+It passes the current font-size and stroke-width checks with the default thresholds.
+
+> The demo files are intentionally simple and fully editable so you can inspect exactly what FigureLint is measuring.
+
+## Current checks
+
+### PNG / JPEG
+
+- unreadable/corrupt image files
+- missing or low DPI metadata
+- suspiciously small raster dimensions
+- transparency that may need flattening for some workflows
+- JPEG usage (informational, because it is lossy)
+
+### SVG
+
+- malformed/unreadable SVG files
+- whether editable `<text>` elements are present
+- suspiciously small or large resolvable font sizes
+- suspiciously thin or thick resolvable strokes
+- simple CSS resolution for tag, class, id, and `tag.class` selectors
+- inline style and SVG presentation-attribute resolution
+
+See [SVG inspection details and assumptions](docs/SVG_CHECKS.md).
+
+### PDF
+
+- malformed/unreadable and password-protected PDF detection
+- multi-page figure warnings
+- unusually small or large page-size warnings
+- editable-text detection
+- font embedding checks
+- effective DPI checks for embedded raster images
+- raster soft-mask / alpha-channel detection
+
+See [PDF inspection details and assumptions](docs/PDF_CHECKS.md).
+
+### Presets
+
+FigureLint can apply named threshold profiles across raster, SVG, and PDF checks.
+
+~~~bash
+figurelint presets
+figurelint check figure.svg --preset high-resolution
+figurelint check figures/ --preset journal-generic
+figurelint check figure.pdf --preset nature
+~~~
+
+Explicit threshold options override the selected preset, so you can start from a profile and change only one value.
+
+Most built-in profiles are FigureLint convenience presets — **not publisher policies**. The `nature` profile is source-verified against Nature's official guidance and checks 5–7 pt ordinary SVG text, 8 pt bold upright panel labels, 0.25–1 pt SVG strokes, font-family consistency/preference, 300 dpi raster imagery, and a 247 mm PDF page-depth guardrail.
+
+See [preset engine details](docs/PRESETS.md) and [Nature preset provenance](docs/NATURE.md).
+
+### GitHub Actions
+
+FigureLint can emit native GitHub workflow annotations and can be used as a reusable composite action.
+
+~~~yaml
+- uses: coocoomaomao/FigureLint@main
+  with:
+    path: figures/
+    preset: nature
+    strict: "true"
+~~~
+
+After the first tagged release, pin to `@v0.1.0` instead of `@main`.
+
+See [GitHub Action usage](docs/GITHUB_ACTION.md).
+
+### Workflow
+
+- recursive folder scanning
+- CI-friendly exit codes
+- optional strict mode
+- configurable thresholds and named presets
+- native GitHub Actions annotations
+
+Planned next:
+
+- PDF font-size and vector stroke checks
+- color contrast and color-blind safety
+- stronger editable-text / outlined-text analysis
+- additional source-verified publisher presets
+
+## Install
+
+Requires Python 3.10+.
+
+### PyPI
+
+The v0.1.0 release is prepared for PyPI Trusted Publishing. Once the first public release is published:
+
+~~~bash
+pip install figurelint
+~~~
+
+### From source
+
+~~~bash
+git clone https://github.com/coocoomaomao/FigureLint.git
+cd FigureLint
+python -m venv .venv
+pip install -e .
+~~~
+
+For development:
+
+~~~bash
+pip install -e ".[dev]"
+pytest
+~~~
+
+Maintainer release instructions are documented in [docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+## Usage
+
+Check one figure:
+
+~~~bash
+figurelint check path/to/figure.svg
+~~~
+
+Check a whole folder:
+
+~~~bash
+figurelint check figures/
+~~~
+
+Use a preset:
+
+~~~bash
+figurelint check figures/ --preset high-resolution
+figurelint check figure.pdf --preset nature
+~~~
+
+List available presets:
+
+~~~bash
+figurelint presets
+~~~
+
+Use stricter CI behavior so warnings fail the command:
+
+~~~bash
+figurelint check figures/ --strict
+~~~
+
+Emit native GitHub Actions annotations:
+
+~~~bash
+figurelint check figures/ --preset nature --github-annotations
+~~~
+
+Customize raster thresholds:
+
+~~~bash
+figurelint check figure.png --min-dpi 300 --min-short-side 600
+~~~
+
+Customize SVG thresholds:
+
+~~~bash
+figurelint check figure.svg \
+  --min-font-size-pt 5 \
+  --max-font-size-pt 7 \
+  --min-stroke-width-pt 0.25 \
+  --max-stroke-width-pt 1
+~~~
+
+Check a PDF figure:
+
+~~~bash
+figurelint check figure.pdf
+~~~
+
+Customize PDF page-size guardrails:
+
+~~~bash
+figurelint check figure.pdf --min-pdf-short-side-in 1 --max-pdf-long-side-in 20
+~~~
+
+The existing `--min-dpi` option is also used for embedded raster images inside PDFs.
+
+Example output:
+
+~~~text
+┏━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ File       ┃ Severity ┃ Code            ┃ Message                      ┃
+┡━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ figure.svg │ warning  │ SVG_FONT_SMALL  │ Found text below 7 pt.       │
+└────────────┴──────────┴─────────────────┴──────────────────────────────┘
+~~~
+
+## Exit codes
+
+- `0`: no errors; warnings are allowed unless `--strict` is used
+- `1`: warnings found in strict mode
+- `2`: one or more errors were found
+
+## Brand assets
+
+The official FigureLint visual system uses a **black cat + magnifying glass + check mark** in navy, teal, orange, and soft gray.
+
+- [README banner](assets/figurelint-banner.svg)
+- [Primary logo](assets/figurelint-logo.svg)
+- [Icon / favicon source](assets/figurelint-icon.svg)
+- [Dark-background logo](assets/figurelint-logo-dark.svg)
+- [Social preview artwork](assets/figurelint-social-preview.svg)
+- [Brand guide](docs/BRAND.md)
+
+## Philosophy
+
+FigureLint should flag **verifiable technical properties**, not pretend that every journal has the same rules. Thresholds are configurable, and future journal presets will be documented with their source guidelines.
+
+## Release
+
+The first public release is **v0.1.0**. See the [v0.1.0 release notes](docs/releases/v0.1.0.md).
+
+## Contributing
+
+Ideas, bug reports, and pull requests are welcome. The first milestones are tracked in GitHub Issues.
+
+## License
+
+MIT