feat: linting edge-case gap remediation v5.1 by luandro · Pull Request #28 · digidem/comapeo-category-spreadsheet-plugin

luandro · 2026-04-13T01:20:11Z

Summary

Expand spreadsheet linting diagnostics to achieve full parity with the plugin's actual export/build behavior, closing high-impact gaps across Categories, Details, Metadata, Translations, and Icons sheets.

Context

The existing linting system (src/lint.ts) only covered basic validation — duplicate names, required fields, and simple type checking. Many conditions that cause build failures or silent data loss during config export were invisible to users until they hit "Generate Config". This implementation aligns lint diagnostics with the real workflows used by the export pipeline (payloadBuilder.ts) and strict validation (importService.ts).

Plan: plans/2026-04-12-linting-edge-case-gaps-v5.1.md

Changes

Phase 1 — Lint infrastructure and artifact lifecycle

Expanded managed color/font palette for consistent clearing
Added setLintNote() (standardized severity-based note writer), clearLintArtifacts() (combined clearing helper), inspectRawIds() (pre-cleanup whitespace detection)

Phase 2 — Categories and Details build-parity checks

Duplicate explicit/generated ID checks for column E (both sheets)
Slug-collision warnings when names produce identical fallback IDs
Full Applies column validation (observation/track coverage, missing column warning)
Empty-sheet error annotations
Manual ID hygiene (whitespace-only, non-slug-safe IDs)

Phase 3 — Field-reference, option, and type parity

Reuses normalizeFieldTokens() from builder for consistent delimiter handling (commas, semicolons, newlines, bullets, fullwidth punctuation)
Field resolution against both names AND explicit IDs from Details col E
parseCanonicalOptions() mirrors builder's parseOptions() (first-colon value:label split)
Ambiguous colon detection, type clarity advisories, ignored-options warnings on text/number fields

Phase 4 — Locale, Metadata, and translation parity

Primary language validation at Categories!A1 using validateLanguageName()
Metadata sheet lint for unsafe characters in name/version/primaryLanguage
Duplicate resolved locale detection in translation headers
Translation source overwrite warnings
Option-count delimiter alignment with builder (/[;,，、]/)

Phase 5 — Icon workflow and Icons sheet coverage

New lintIconsSheet() validates the Icons sheet (missing/duplicate IDs, unsupported formats)
Cross-sheet icon ID collision detection between Categories and Icons
Plain-text icon workflow-aware warnings (distinguishes "Generate Category Icons" from direct export)
Icon ID normalization warnings for .svg/.png suffixes

Phase 6 — Strict-validation advisory parity

Inline SVG size checks: warning >300KB, error >2MB
Per-locale translation payload size: error >1MB
Total entity count: error >10,000

Phase 7 — UI summary and regression coverage

Updated completion summary text describing all diagnostic categories
Clearing lifecycle fixes ensuring re-lint removes prior annotations
Parity test functions: testFieldTokenParity(), testCanonicalOptionParity(), testTranslationDelimiterParity()

Severity Matrix

Condition	Severity	Display
Build-blocking invalid value or collision	Error	`#FFC7CE` background + red font
Workflow-dependent or lossy behavior	Warning	`#FFF2CC` background + orange font
Advisory / quality guidance	Advisory	`#FFFFCC` background
Translation source/primary-column mismatch	Critical	Bright red + white text (preserved)

Testing

Open the Google Spreadsheet and run Lint Sheets from the CoMapeo menu
Verify the expanded summary alert describes all diagnostic categories
Introduce test issues and verify correct severity annotations:
- Duplicate a category name → slug collision warning on col A
- Enter whitespace-only ID in col E → hygiene warning
- Remove all "observation" from Applies column → error on header
- Add plain text icon → workflow-aware warning
- Add oversized inline SVG → size warning/error
Fix issues and re-lint → verify all prior annotations are cleared
Run parity tests from Apps Script editor: runPhase7ParityTests()

Files Changed

src/lint.ts — +1,791 / -232 lines (primary implementation, all 7 phases)

Greptile Summary

This PR expands the spreadsheet linting system across 7 phases to achieve build-parity with the export pipeline, closing high-impact diagnostic gaps in Categories, Details, Metadata, Translation, and Icons sheets. It also fixes a blank-type defaulting bug in payloadBuilder.ts (|| "text" → || "").

New lint infrastructure: setLintNote/appendLintNote/clearLintArtifacts helpers with severity-based styling and prefix-scoped clearing; all per-column clearing in lintSheet now includes clearRangeLintNoteLinesWithPrefix so stale notes are removed on re-lint.
Build-parity checks: duplicate effective-ID detection for col E, slug-collision warnings, Applies column coverage, field-reference resolution, option deduplication, locale/metadata validation, inline SVG size limits, entity-count guard, and a new lintIconsSheet() with cross-sheet collision detection.
Lifecycle fixes: note accumulation and overwrite bugs addressed via appendLintNote; Drive icon info cached at module level to avoid redundant API calls.

Confidence Score: 5/5

Safe to merge — all previously flagged blocking issues have been addressed and no new functional defects were found.

All prior review cycle issues are resolved: blank-type defaulting is fixed in both payloadBuilder.ts and the lint metrics builder, appendLintNote is used consistently to prevent note overwrites, checkDuplicateTranslationSlugs is now wired in, Drive icon MIME handling is correct, and validateSheetConsistency clears only data rows. The two remaining findings are a dead filter constant and a minor mismatch between the completion alert text and the actual version key behaviour — neither affects runtime correctness.

No files require special attention; src/lint.ts carries the bulk of the change but is well-structured and the critical call-ordering constraints are consistently applied.

Important Files Changed

Filename	Overview
src/lint.ts	Primary change (+1,791/-232 lines): adds 7 phases of build-parity lint checks, new helper infrastructure, and clears fixes from previous review cycles. A dead filter on LINT_WARNING_FONT_COLORS_WITHOUT_WHITE and a misleading version advisory note are minor issues.
src/builders/payloadBuilder.ts	Two-line fix: blank type now defaults to "" (selectOne) instead of "text", and parseTokens gets a stronger type annotation — both safe changes.
src/importService.ts	Widens mapFieldTypeToChar parameter from FieldType to string; safe refactor for flexibility.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[lintAllSheets] --> B[lintCategoriesSheet]
    A --> C[lintDetailsSheet]
    A --> D[lintIconsSheet]
    A --> E[checkCrossSheetIconCollisions]
    A --> F[checkInlineSvgSizes]
    A --> G[lintTranslationSheets]
    A --> H[collectStrictLintMetrics]
    A --> I[checkTranslationPayloadSizes]
    A --> J[lintMetadataSheet]
    A --> K[checkTotalEntityCounts]
    B --> B1[validatePrimaryLanguageInA1]
    B --> B2[lintSheet - cols A,B,C]
    B --> B3[validateCategoryIcons]
    B --> B4[checkDuplicateCategoryIds - col E]
    B --> B5[checkSlugCollisions - col A]
    B --> B6[validateAppliesColumn - col D]
    B --> B7[checkManualIdHygiene - col E]
    C --> C1[lintSheet - cols A-F]
    C --> C2[checkUnreferencedDetails]
    C --> C3[checkDuplicateDetailIds - col E]
    C --> C4[checkSlugCollisions - col A]
    C --> C5[checkManualIdHygiene - col E]
    G --> G1[validateTranslationHeaders]
    G --> G2[validateTranslationSheetConsistency]
    G --> G3[checkTranslationSourceOverwrites]
    G --> G4[checkDuplicateTranslationSlugs]

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
src/lint.ts:35-38
`LINT_WARNING_FONT_COLORS_WITHOUT_WHITE` always equals `LINT_WARNING_FONT_COLORS` because `"#FFFFFF"` is never in `["red", "orange", "#FF0000"]`. The filter is a no-op, so the variable name misleads future readers into thinking white text is being excluded from cleanup. The actual protection for white-on-red critical cells comes from the narrow `SOURCE_OVERWRITE_LINT_NOTE_PREFIX` scope and the fact that those cells carry no `[Lint]` note — not from this filter.

```suggestion
const LINT_WARNING_FONT_COLORS = ["red", "orange", "#FF0000"];
// Alias kept for clarity: white (#FFFFFF) is never in LINT_WARNING_FONT_COLORS,
// so source-overwrite cleanup already never clears white text. No filter needed.
const LINT_WARNING_FONT_COLORS_WITHOUT_WHITE = LINT_WARNING_FONT_COLORS;
```

### Issue 2 of 2
src/lint.ts:4145-4162
**`version` validation diverges from PR description**

The PR description, the summary in `lintAllSheets`, and the completion alert all state "Unsafe characters in name/version/primaryLanguage", implying `version` is checked for slashes/backslashes/ellipses like `name` and `primaryLanguage` are. The actual implementation gives an advisory when the value doesn't match the `yy.MM.dd` auto-generated pattern — not an unsafe-character error. The in-code comment explains why (builder always overwrites `version`), which is correct reasoning, but the mismatch with the documented behavior could confuse users who read the alert and expect their slash-containing version string to be flagged as an error. Consider updating the completion alert text to replace "name/version/primaryLanguage" with "name/primaryLanguage" and mention the `version` overwrite advisory separately.

_{Reviews (78): Last reviewed commit: "chore: stop tracking generated codesight..." | Re-trigger Greptile}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1a812ef58d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

luandro · 2026-04-13T01:58:39Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d6b4c12bb2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

luandro · 2026-04-13T08:02:37Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 76aa2bc56c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

luandro · 2026-04-13T11:46:22Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 97ba536fb7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Address 4 parity gaps flagged in PR #28 review (chatgpt-codex-connector): 1. Downgrade missing-track Applies finding to warning (was error). importService.runStrictBuildValidations() pushes no-track to warnings[], not errors[], so lint must not block users for a valid payload. 2. Align metadata unsafe-char pattern with containsUnsafeNameCharacters(). Old UNSAFE_PATTERN (/[<>"'&\x00-\x1F]/) flagged apostrophes/ampersands as errors when the actual validator only rejects slashes/backslashes/ellipsis. New STRICT_UNSAFE_PATTERN = /[\\/]|\.\.\./ 3. Reject non-SVG HTTP URLs in Icons sheet lint (P1). payloadBuilder.isSvgUrl() requires .svg in the URL; any other HTTP URL returns null from parseIconSource() and is silently dropped during build. Now emits an error for HTTP URLs without .svg, not a false-pass. 4. Use Categories icon-id column (col F) for cross-sheet collision checks. buildIconsFromSheet() uses the "icon id" column when present, overriding the category ID. Collision detection now reads col F and falls back to categoryId, avoiding false positives/negatives when icon id ≠ category id.

luandro · 2026-04-14T03:51:06Z

@codex review

…check checkTranslationSourceOverwrites() was calling setLintNote() which unconditionally overwrites any existing note and severity styling. validateTranslationSheetConsistency() runs before it and may write critical (bright-red/white-text) annotations on the same cells. Switch to appendLintNote() so source-overwrite warnings are appended to — not replaced over — existing critical mismatch styling. Closes Codex review finding (PR #28, line 2310).

luandro · 2026-04-14T04:23:41Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 05218c601b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

- checkForDuplicates: use clearLintArtifacts() to remove stale lint notes alongside backgrounds, preventing false-positive re-runs - lintIconsSheet: restrict Drive URL check to /file/d/ format only, matching payloadBuilder.isGoogleDriveLink() and preventing open?id= links from passing lint while being silently dropped during build - checkIconIdNormalization: read 6 cols and use col-F icon-id override (mirroring buildIconsFromSheet), add parseIconSource guard to skip rows the builder ignores, add Math.max column guard to avoid range errors on narrow sheets

Address 4 parity gaps flagged in PR #28 review (chatgpt-codex-connector): 1. Downgrade missing-track Applies finding to warning (was error). importService.runStrictBuildValidations() pushes no-track to warnings[], not errors[], so lint must not block users for a valid payload. 2. Align metadata unsafe-char pattern with containsUnsafeNameCharacters(). Old UNSAFE_PATTERN (/[<>"'&\x00-\x1F]/) flagged apostrophes/ampersands as errors when the actual validator only rejects slashes/backslashes/ellipsis. New STRICT_UNSAFE_PATTERN = /[\\/]|\.\.\./ 3. Reject non-SVG HTTP URLs in Icons sheet lint (P1). payloadBuilder.isSvgUrl() requires .svg in the URL; any other HTTP URL returns null from parseIconSource() and is silently dropped during build. Now emits an error for HTTP URLs without .svg, not a false-pass. 4. Use Categories icon-id column (col F) for cross-sheet collision checks. buildIconsFromSheet() uses the "icon id" column when present, overriding the category ID. Collision detection now reads col F and falls back to categoryId, avoiding false positives/negatives when icon id ≠ category id.

…check checkTranslationSourceOverwrites() was calling setLintNote() which unconditionally overwrites any existing note and severity styling. validateTranslationSheetConsistency() runs before it and may write critical (bright-red/white-text) annotations on the same cells. Switch to appendLintNote() so source-overwrite warnings are appended to — not replaced over — existing critical mismatch styling. Closes Codex review finding (PR #28, line 2310).

- checkForDuplicates: use clearLintArtifacts() to remove stale lint notes alongside backgrounds, preventing false-positive re-runs - lintIconsSheet: restrict Drive URL check to /file/d/ format only, matching payloadBuilder.isGoogleDriveLink() and preventing open?id= links from passing lint while being silently dropped during build - checkIconIdNormalization: read 6 cols and use col-F icon-id override (mirroring buildIconsFromSheet), add parseIconSource guard to skip rows the builder ignores, add Math.max column guard to avoid range errors on narrow sheets

luandro · 2026-04-14T13:28:54Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a2eed871d1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".