Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Request: Fail-closed offline Theme Check API with reliable scan completion reporting

Abierto
  • ¿Algo no está bien?
#1,367 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
20/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
node.js, typescript
Área
developer-experience, tooling

Línea de trabajo

Start by tracing the themeCheckRun API in @shopify/theme-check-node and the common runner's check pipeline, then follow graph construction and documentation setup. The issue does not name repository files or tests, so locate the API entry points and existing coverage for error handling and offline documentation. Done means maintainers identify a supported approach or the project adds a way to report completion and failures for every applicable check.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Summary

I'm requesting maintainer guidance on a supported way to run Shopify Theme Check as a fully offline, read-only, fail-closed quality gate using its Node.js API.

Our goal is to verify that all selected checks completed successfully, rather than treating a returned list of offenses as proof that the scan was complete.

We have inspected the installed source and completed isolated configuration and theme-content loading tests. However, we have not established a completed lint scan.

Environment

  • Operating system: Windows
  • Node.js: 26.12.1
  • @shopify/theme-check-node: 3.30.1
  • @shopify/theme-check-common: 3.30.1
  • @shopify/theme-check-docs-updater: 3.30.1
  • glob: 8.1.0
  • vscode-uri: 3.2.0
  • Project: Shopify Online Store 2.0 theme development
  • Execution requirements: offline, read-only theme analysis, with narrowly scoped filesystem permissions

What we have verified

  • The recommended configuration selects 83 canonical check IDs and 85 built-in check definitions.
  • Standalone file discovery identified 156 Liquid/JSON paths.
  • loadConfig() completed successfully.
  • getTheme() successfully returned 156 SourceCode objects in a bounded diagnostic after an additional theme-specific filesystem read grant was supplied.
  • No source modifications were observed during that diagnostic.
  • A complete Theme Check lint run has not been established or accepted.

On Windows with Node's permission model enabled, we also observed a drive-letter representation mismatch during theme loading. The installed URI formatting path lowercases the Windows drive letter, and the lowercase namespaced filesystem resource was denied under the original read grants. An additional narrow, lowercase-drive read grant allowed content loading in our specific experiment.

We are not assuming that this experimental grant is a general or permanent solution.

Concerns identified in the installed API

1. Check pipeline failures

The common runner appears to ignore rejected check pipelines by default when config.onError is not provided.

The normal themeCheckRun(root, configPath?, log?) API does not appear to expose a supported way to provide that callback.

Question: How can an API consumer reliably detect and fail on every rejected check pipeline?

2. Theme graph failures

The Node wrapper catches graph-construction errors and can continue with degraded cross-file information.

Question: Is there a supported way to require successful graph construction and abort if it fails?

3. Documentation loading failures

The documentation manager may catch setup errors, while loaders can return fallback or empty documentation data.

Question: How can a consumer verify that all required Liquid documentation, schemas, and references loaded correctly without silent degradation?

4. Offline documentation and cache writes

We found that SHOPIFY_TLD_ROOT can select local documentation files.

However, documentation setup may still create cache directories and write files such as latest.json, even when documentation is available locally.

Question: Is there a supported way to use strictly local documentation while redirecting all required cache writes into one explicitly controlled temporary directory?

5. Trustworthy scan completion

The API can return offenses in memory, but we could not establish a supported completion record confirming that every applicable selected check ran successfully.

Question: Is there a supported API or execution mode that distinguishes:

  • Check completed successfully with zero offenses
  • Check completed with offenses
  • Check failed internally
  • Check was skipped
  • Theme graph failed
  • Required documentation failed to initialize

Requested maintainer guidance

Could you recommend an officially supported API or implementation approach that can:

  1. Run all applicable recommended Liquid, JSON, and whole-theme checks.
  2. Surface internal check errors rather than silently swallowing them.
  3. Require successful theme-graph construction.
  4. Detect missing or incompatible documentation resources.
  5. Use local documentation with a controlled cache location.
  6. Return diagnostics and reliable completion status in memory.
  7. Avoid modifying theme source files or invoking autofix.
  8. Work offline with network, child-process, and worker permissions denied.

If these guarantees are not available in version 3.30.1, is there a maintainer-recommended version, API, or documented approach that provides them?

A reference implementation or documentation link would be especially helpful.

Additional notes

We are seeking guidance on the supported API contract, not claiming that every observed fallback is necessarily a bug.

We have intentionally excluded private filesystem paths, credentials, commercial source code, and live-store details.

No live Shopify theme or production store was modified.

Thank you for your guidance.

Lenguaje dominante
TypeScript
Estrellas
240
Forks
106
Merge medio
1 d 2 h
PR fusionados (30 d)
23

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Shopify/theme-tools

Todos los issues de Shopify/theme-tools

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.