Conversation
…nization - Added HerettoUploader class to handle file uploads to Heretto CMS. - Integrated uploader into the existing upload process for changed screenshots. - Enhanced screenshot saving logic to track changes and source integration metadata. - Created documentation for Heretto screenshot sync feature, detailing the upload process and architecture. - Updated resolver to build file mappings and handle Heretto-specific configurations. - Introduced utility functions to find Heretto integrations based on file paths. - Added error handling and logging for upload operations to improve reliability.
- Update `saveScreenshot.js` to mark new screenshots as changed for upload. - Add a new test file `screenshot.test.js` to verify sourceIntegration preservation and changed status for screenshots. - Create a new test file `upload.test.js` to validate the upload module, including collecting changed files and integration configuration. - Modify `package-lock.json` to link to local `doc-detective-common` instead of a versioned package. - Enhance `heretto.js` to retrieve resource dependencies from the Heretto REST API, including detailed logging and XML parsing.
- Modify resolve function to return heretto: URIs unchanged. - Update comments to reflect new URI handling in path resolution.
- Upgrade chai from 6.2.1 to 6.2.2 - Upgrade sinon from 21.0.0 to 21.0.1 - Update sinon's fake-timers and samsam dependencies
WalkthroughThis PR introduces Heretto CMS source integration support by adding a new Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (6)
src/schemas/src_schemas/screenshot_v3.schema.json (1)
214-248: Consider adding an example demonstrating the sourceIntegration property.While the existing examples are valid, adding one that includes the
sourceIntegrationproperty would help users understand its structure and usage, even though it's typically set automatically.📝 Example with sourceIntegration
{ "path": "image.png", "directory": "static/images", "maxVariation": 0.1, "overwrite": "aboveVariation", "crop": { "selector": "#elementToScreenshot", "elementText": "Element text", "padding": { "top": 0, "right": 0, "bottom": 0, "left": 0 } - } + }, + "sourceIntegration": { + "type": "heretto", + "integrationName": "my-heretto", + "fileId": "8f3ed200-cbba-11e1-ac51-c82a1446d15c", + "filePath": "/db/organizations/example/repositories/docs/images/screenshot.png" + } }src/schemas/src_schemas/sourceIntegration_v3.schema.json (1)
18-21: Consider adding UUID format validation for fileId.The description indicates
fileIdshould be a UUID, but the schema only validates it as astring. Adding format validation would ensure stricter compliance with the documented structure.🔎 Proposed enhancement
"fileId": { "type": "string", + "format": "uuid", "description": "The unique identifier (UUID) of the file in the source CMS. If not provided, the file will be looked up by path." },src/schemas/output_schemas/step_v3.schema.json (2)
4802-4851: sourceIntegration object is well-structured; consider requiring a locator fieldThe new
sourceIntegrationschema looks coherent and aligned with the Heretto use case (cleartypeenum,integrationName, and optional IDs/paths). One thing to consider: as written, it's valid for all offileId,filePath, andcontentPathto be omitted, which may leave the uploader without a reliable way to locate the remote asset.If, in practice, you always need at least a
fileIdorfilePathto perform an upload, you could tighten this with ananyOfconstraint:Optional schema tightening for locator requirements
"properties": { "type": { "type": "string", "description": "The type of integration. Currently supported: 'heretto'. Additional types may be added in the future.", "enum": [ "heretto" ] }, "integrationName": { "type": "string", "description": "The name of the integration configuration in the config file. Used to look up authentication credentials." }, "fileId": { "type": "string", "description": "The unique identifier (UUID) of the file in the source CMS. If not provided, the file will be looked up by path." }, "filePath": { "type": "string", "description": "The path of the file in the source CMS. Used for lookup if fileId is not available." }, "contentPath": { "type": "string", "description": "The local path to the file that references this source. Used for resolving relative paths." } - }, + }, + "anyOf": [ + { + "required": [ + "fileId" + ] + }, + { + "required": [ + "filePath" + ] + } + ], "examples": [If you adopt this, mirror the same
anyOfblock in the secondsourceIntegrationdefinition below to keep them consistent.
5048-5097: Avoid future drift between duplicated sourceIntegration schemasThis second
sourceIntegrationblock mirrors the one above under the mainscreenshotproperties, which matches existing duplication patterns in this schema. However, with a dedicatedsourceIntegration_v3.schema.jsonin the PR, you now have three places that must stay in sync.To reduce future maintenance risk, consider (on a follow-up pass) refactoring these to reuse a shared definition (e.g., via a local
components.schemas.sourceIntegrationor a$refto the shared schema before dereferencing), so changes to fields or examples only need to be made once.src/schemas/src_schemas/config_v3.schema.json (1)
280-284: Consider adding an example demonstratinguploadOnChange: true.The
uploadOnChangeproperty is correctly configured as a user-settable boolean with a sensible default. To improve discoverability and documentation, consider adding an example in theexamplesarray that shows this property set totrue, helping users understand how to enable automatic uploads of changed screenshots back to Heretto CMS.📋 Suggested example addition
Add this example to the
examplesarray (after line 631):{ "integrations": { "heretto": [ { "name": "example-with-upload", "organizationId": "your-organization-id", "username": "your-username", "apiToken": "your-api-token", "uploadOnChange": true } ] } }src/schemas/output_schemas/report_v3.schema.json (1)
6021-6069: Schema additions look correct; consider consolidating with$ref.The
sourceIntegrationschema is well-structured with appropriate required/optional fields, strict validation viaadditionalProperties: false, and helpful examples. The same ~50-line definition is repeated across all 4 hunks.Since
sourceIntegration_v3.schema.jsonexists per the PR summary, you could reduce duplication and simplify future maintenance by referencing it:"sourceIntegration": { "$ref": "sourceIntegration_v3.schema.json" }This is optional—the current approach works correctly.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (9)
dist/schemas/config_v3.schema.jsonis excluded by!**/dist/**dist/schemas/report_v3.schema.jsonis excluded by!**/dist/**dist/schemas/resolvedTests_v3.schema.jsonis excluded by!**/dist/**dist/schemas/screenshot_v3.schema.jsonis excluded by!**/dist/**dist/schemas/sourceIntegration_v3.schema.jsonis excluded by!**/dist/**dist/schemas/spec_v3.schema.jsonis excluded by!**/dist/**dist/schemas/step_v3.schema.jsonis excluded by!**/dist/**dist/schemas/test_v3.schema.jsonis excluded by!**/dist/**package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (15)
package.jsonsrc/resolvePaths.jssrc/schemas/dereferenceSchemas.jssrc/schemas/output_schemas/config_v3.schema.jsonsrc/schemas/output_schemas/report_v3.schema.jsonsrc/schemas/output_schemas/resolvedTests_v3.schema.jsonsrc/schemas/output_schemas/screenshot_v3.schema.jsonsrc/schemas/output_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/output_schemas/spec_v3.schema.jsonsrc/schemas/output_schemas/step_v3.schema.jsonsrc/schemas/output_schemas/test_v3.schema.jsonsrc/schemas/schemas.jsonsrc/schemas/src_schemas/config_v3.schema.jsonsrc/schemas/src_schemas/screenshot_v3.schema.jsonsrc/schemas/src_schemas/sourceIntegration_v3.schema.json
🧰 Additional context used
📓 Path-based instructions (4)
src/schemas/src_schemas/*.json
📄 CodeRabbit inference engine (AGENTS.md)
src/schemas/src_schemas/*.json: Always include examples array in all schemas (required for test generation)
In source schemas, use relative $ref paths like "$ref": "context_v3.schema.json#/properties/example"
Files:
src/schemas/src_schemas/screenshot_v3.schema.jsonsrc/schemas/src_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/src_schemas/config_v3.schema.json
**/*.{js,ts}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{js,ts}: Always clone objects using JSON.parse(JSON.stringify(object)) before validation to avoid mutations
validate() returns { valid, errors, object } and never throws; handle errors via return object
transformToSchemaKey() throws on incompatible schemas or invalid results; catch exceptions when calling this function
readFile() returns null on errors and logs warnings to console; do not assume errors throw exceptions
resolvePaths() throws on invalid object types or missing nested object types; validate inputs before calling
Do not assume validation mutates objects; always handle the returned validated object
Files:
src/resolvePaths.jssrc/schemas/dereferenceSchemas.js
src/**/*.js
📄 CodeRabbit inference engine (AGENTS.md)
Use escapeRegExp() helper when converting user strings to regex patterns in transformToSchemaKey()
Files:
src/resolvePaths.jssrc/schemas/dereferenceSchemas.js
src/resolvePaths.js
📄 CodeRabbit inference engine (AGENTS.md)
src/resolvePaths.js: Path resolution respects config.relativePathBase setting: 'file' (relative to file location) or 'cwd' (relative to working directory)
Skip path resolution for HTTP(S) URLs, already-absolute paths, and user data properties (e.g., requestData)
Resolve path property relative to directory if directory is absolute (special case in resolvePaths)
For new config path properties, add to configPaths in resolvePaths.js; for spec properties, add to specPaths
Files:
src/resolvePaths.js
🧠 Learnings (19)
📚 Learning: 2025-05-29T16:54:47.192Z
Learnt from: hawkeyexl
Repo: doc-detective/common PR: 117
File: src/schemas/output_schemas/resolvedTests_v3.schema.json:24-30
Timestamp: 2025-05-29T16:54:47.192Z
Learning: In doc-detective/common schemas, `$schema` properties within object definitions are intentionally added to allow described JSON objects to be self-describing for linting purposes. This enables JSON linters and validators to automatically validate objects against the referenced schema. The version information is embedded in the filename using the pattern `<schema>_v3.schema.json`.
Applied to files:
src/schemas/output_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/src_schemas/screenshot_v3.schema.jsonsrc/schemas/src_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/output_schemas/spec_v3.schema.jsonsrc/schemas/output_schemas/test_v3.schema.jsonsrc/schemas/output_schemas/config_v3.schema.jsonsrc/schemas/output_schemas/resolvedTests_v3.schema.jsonsrc/schemas/output_schemas/report_v3.schema.jsonsrc/schemas/output_schemas/step_v3.schema.jsonsrc/schemas/output_schemas/screenshot_v3.schema.jsonsrc/schemas/src_schemas/config_v3.schema.jsonsrc/schemas/dereferenceSchemas.jspackage.json
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/schemas/src_schemas/*.json : Always include examples array in all schemas (required for test generation)
Applied to files:
src/schemas/output_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/src_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/output_schemas/test_v3.schema.jsonsrc/schemas/output_schemas/resolvedTests_v3.schema.jsonsrc/schemas/output_schemas/report_v3.schema.jsonsrc/schemas/dereferenceSchemas.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: When adding new schemas, update the files array in dereferenceSchemas.js and add to published list if creating v3 schema
Applied to files:
src/schemas/output_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/src_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/src_schemas/config_v3.schema.jsonsrc/schemas/dereferenceSchemas.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/schemas/src_schemas/*.json : In source schemas, use relative $ref paths like "$ref": "context_v3.schema.json#/properties/example"
Applied to files:
src/schemas/output_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/src_schemas/screenshot_v3.schema.jsonsrc/schemas/src_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/output_schemas/test_v3.schema.jsonsrc/schemas/output_schemas/config_v3.schema.jsonsrc/schemas/output_schemas/resolvedTests_v3.schema.jsonsrc/schemas/dereferenceSchemas.js
📚 Learning: 2025-08-22T20:01:21.087Z
Learnt from: hawkeyexl
Repo: doc-detective/common PR: 134
File: src/schemas/output_schemas/report_v3.schema.json:5695-5921
Timestamp: 2025-08-22T20:01:21.087Z
Learning: The report_v3.schema.json includes dragAndDrop via inclusion in the spec schema, which includes the test and step schemas, creating a chain of schema inclusions.
Applied to files:
src/schemas/output_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/src_schemas/screenshot_v3.schema.jsonsrc/schemas/src_schemas/sourceIntegration_v3.schema.jsonsrc/schemas/output_schemas/spec_v3.schema.jsonsrc/schemas/output_schemas/test_v3.schema.jsonsrc/schemas/output_schemas/config_v3.schema.jsonsrc/schemas/output_schemas/resolvedTests_v3.schema.jsonsrc/schemas/output_schemas/report_v3.schema.jsonsrc/schemas/output_schemas/step_v3.schema.jsonsrc/schemas/dereferenceSchemas.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/validate.js : All step_v3 schemas must accept 12 different v2 action schemas (checkLink_v2, find_v2, etc.) via compatibleSchemas map
Applied to files:
src/schemas/output_schemas/spec_v3.schema.jsonsrc/schemas/output_schemas/test_v3.schema.jsonsrc/schemas/output_schemas/report_v3.schema.jsonsrc/schemas/dereferenceSchemas.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/validate.js : Handle schema property transformations: typeKeys.delay → type.inputDelay, maxVariation (0-100) → (0-1), and app → browsers structure changes
Applied to files:
src/schemas/output_schemas/test_v3.schema.jsonsrc/schemas/output_schemas/resolvedTests_v3.schema.json
📚 Learning: 2025-08-22T20:01:21.087Z
Learnt from: hawkeyexl
Repo: doc-detective/common PR: 134
File: src/schemas/output_schemas/report_v3.schema.json:5695-5921
Timestamp: 2025-08-22T20:01:21.087Z
Learning: In the doc-detective/common project, dragAndDrop schema doesn't need to be explicitly added to report_v3.schema.json because all schemas in schema.json are dynamically loaded and dragAndDrop is included through that mechanism.
Applied to files:
src/schemas/output_schemas/report_v3.schema.jsonsrc/schemas/dereferenceSchemas.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/resolvePaths.js : Skip path resolution for HTTP(S) URLs, already-absolute paths, and user data properties (e.g., requestData)
Applied to files:
src/resolvePaths.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/resolvePaths.js : Resolve path property relative to directory if directory is absolute (special case in resolvePaths)
Applied to files:
src/resolvePaths.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/resolvePaths.js : For new config path properties, add to configPaths in resolvePaths.js; for spec properties, add to specPaths
Applied to files:
src/resolvePaths.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/resolvePaths.js : Path resolution respects config.relativePathBase setting: 'file' (relative to file location) or 'cwd' (relative to working directory)
Applied to files:
src/resolvePaths.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to **/*.{js,ts} : resolvePaths() throws on invalid object types or missing nested object types; validate inputs before calling
Applied to files:
src/resolvePaths.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Do not add schemas without updating the files array in dereferenceSchemas.js
Applied to files:
src/schemas/dereferenceSchemas.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to src/validate.js : When creating new schema version (e.g., v4), update compatibleSchemas map and add transformation logic in transformToSchemaKey()
Applied to files:
src/schemas/dereferenceSchemas.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Do not edit generated files directly: build/, output_schemas/, or schemas.json (regenerated on npm run build)
Applied to files:
src/schemas/dereferenceSchemas.js
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Do not modify package.json version in PRs; auto-dev-release workflow handles version bumps automatically
Applied to files:
package.json
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to test/*.test.js : Test structure uses Mocha + Chai; validate schema examples in test/schema.test.js (auto-generated from schemas)
Applied to files:
package.json
📚 Learning: 2025-11-25T23:59:43.235Z
Learnt from: CR
Repo: doc-detective/common PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T23:59:43.235Z
Learning: Applies to test/*.test.js : Use dynamic import for Chai in test files for ESM compatibility
Applied to files:
package.json
🔇 Additional comments (16)
src/resolvePaths.js (2)
81-85: LGTM! Heretto URI handling follows the established pattern.The implementation correctly treats
heretto:URIs the same way as HTTP(S) URLs, returning them unchanged during path resolution. This is consistent with the existing pattern and appropriate for CMS URI schemes.
192-200: LGTM! Consistent handling in string property skip logic.The
heretto:prefix is correctly added to the skip list for string properties, ensuring these URIs are preserved as-is throughout the resolution process.src/schemas/dereferenceSchemas.js (1)
47-47: LGTM! Schema correctly registered for processing.The
sourceIntegration_v3.schema.jsonis properly added to the v3 schemas list and will be automatically included in the dereferencing and publishing pipelines. Based on learnings, this follows the required pattern for new schema registration.src/schemas/src_schemas/screenshot_v3.schema.json (1)
72-75: LGTM! SourceIntegration property correctly integrated.The property uses a relative
$refpath as required by coding guidelines for source schemas. The description clearly explains its automatic population during test resolution.src/schemas/src_schemas/sourceIntegration_v3.schema.json (1)
1-30: LGTM! Schema structure is well-defined.The schema correctly:
- Includes the
$schemaproperty for self-describing JSON (per project patterns)- Defines required and optional properties appropriately
- Sets
additionalProperties: falseto prevent invalid fields- Includes comprehensive property descriptions
- Has examples demonstrating valid usage (required per coding guidelines)
package.json (1)
23-25: The package versions are valid and free from known security vulnerabilities. Both chai@6.2.2 and sinon@21.0.1 are current versions with no reported security advisories.src/schemas/output_schemas/sourceIntegration_v3.schema.json (1)
1-50: Well-structured schema with comprehensive examples.The sourceIntegration schema is well-designed with:
- Clear required vs. optional fields
- Strict validation via
additionalProperties: false- Two examples demonstrating different lookup strategies (UUID-based vs. path-based)
- Future-proof design acknowledging additional integration types
The schema correctly follows the project conventions with
$schemafor linting and includes examples as required.src/schemas/output_schemas/screenshot_v3.schema.json (1)
191-240: The source schemasrc/schemas/src_schemas/screenshot_v3.schema.jsoncorrectly uses$ref": "sourceIntegration_v3.schema.json#"at line 72-74. The duplication in the output schemasrc/schemas/output_schemas/screenshot_v3.schema.jsonis expected behavior from the dereferencing process, which expands all$refreferences into full inline definitions. Both schemas are properly configured in thedereferenceSchemas.jsfiles array. No action needed.Likely an incorrect or invalid review comment.
src/schemas/output_schemas/resolvedTests_v3.schema.json (3)
5600-5650: Schema structure is well-defined.The
sourceIntegrationschema appropriately:
- Requires
typeandintegrationNameas essential identifiers- Provides examples covering both UUID-based (
fileId) and path-based lookup scenarios- Uses
additionalProperties: falsefor strict validation- Includes
$schemafor self-describing JSON objects (consistent with project conventions)The same schema is correctly inlined across all "Capture screenshot (detailed)" contexts as part of the dereferencing process.
8643-8692: Heretto integration schema extensions are appropriate.Good design choices:
readOnly: truecorrectly marks auto-populated fields (fileMapping,resourceDependencies)uploadOnChangedefaults tofalse, requiring explicit opt-in for the upload feature- The
additionalPropertiesschemas provide clear structure for the metadata mappingsThe nested object schemas within
fileMappingandresourceDependenciesdon't specifyrequiredoradditionalProperties: false, allowing flexibility for partial metadata. This is acceptable for auto-generated content, though you may want to tighten validation if stricter guarantees are needed.
5846-5896: Duplicate schema definitions expected from dereferencing.The remaining
sourceIntegrationdefinitions in hunks 2, 4–9 are identical copies inlined at different "Capture screenshot (detailed)" contexts. This duplication is the expected result of the dereferencing process from the source schema.Also applies to: 13703-13753, 13949-13999, 22495-22545, 22741-22791, 30072-30122, 30318-30368
src/schemas/output_schemas/test_v3.schema.json (2)
5401-5451: Well-structured sourceIntegration schema addition.The
sourceIntegrationproperty is correctly defined with:
- Required
type(restricted to "heretto" enum) andintegrationNamefor integration identification- Optional
fileId,filePath, andcontentPathfor flexible file lookup strategies- Clear descriptions and representative examples covering both UUID-based and path-based lookups
additionalProperties: falsefor strict validationThe embedded
$schemaproperty aligns with the project's convention for self-describing JSON objects. Based on learnings, this enables JSON linters to automatically validate objects against the referenced schema.
5647-5697: Consistent sourceIntegration definitions across step contexts.The identical
sourceIntegrationdefinitions at these locations maintain consistency across all screenshot step types in the dereferenced output schema. This duplication is expected: the source schemas (screenshot_v3.schema.json, etc.) properly use$ref": "sourceIntegration_v3.schema.json#"to avoid manual duplication, and the dereference build process inlines these references into the final output schemas.Also applies to: 12978-13028, 13224-13274
src/schemas/output_schemas/spec_v3.schema.json (1)
6002-6052: LGTM! Well-structured sourceIntegration schema.The
sourceIntegrationproperty is consistently added across all screenshot action variants with a well-defined schema. The structure appropriately requirestypeandintegrationNamewhile keepingfileId,filePath, andcontentPathoptional for flexibility. The examples clearly demonstrate both identification patterns (UUID-based withfileIdand path-based with relative resolution viacontentPath).The inline duplication across all four hunks is expected for a dereferenced schema file. The inclusion of the
$schemaproperty is intentional for self-describing JSON objects, as per project conventions.Also applies to: 6248-6298, 13579-13629, 13825-13875
src/schemas/output_schemas/config_v3.schema.json (2)
5588-5636: Well-designed sourceIntegration schema.The sourceIntegration schema is consistently defined across all locations with appropriate required fields (type, integrationName) and flexible optional fields (fileId, filePath, contentPath). The examples clearly demonstrate usage patterns, and the description accurately explains the automatic population during test resolution. The enum restriction to "heretto" with extensibility notes is forward-thinking.
Also applies to: 5834-5882, 13691-13739, 13937-13985
8631-8678: Solid Heretto integration enhancements.The new properties for the Heretto integration config are well-structured. The readOnly markers on fileMapping and resourceDependencies correctly indicate they're auto-populated, and the uploadOnChange flag with a safe default of false provides appropriate control. The additionalProperties patterns accurately define the structure of mapped values, and descriptions clearly explain when each property is populated.
| "fileMapping": { | ||
| "type": "object", | ||
| "description": "Mapping of local file paths to Heretto file metadata. Set automatically during content loading.", | ||
| "readOnly": true, | ||
| "additionalProperties": { | ||
| "type": "object", | ||
| "properties": { | ||
| "fileId": { | ||
| "type": "string", | ||
| "description": "The UUID of the file in Heretto." | ||
| }, | ||
| "filePath": { | ||
| "type": "string", | ||
| "description": "The path of the file in Heretto." | ||
| } | ||
| } | ||
| } | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for fileMapping usage patterns in the codebase
rg -nP -C5 'fileMapping\s*[=:]' --type=js --type=tsRepository: doc-detective/common
Length of output: 46
🏁 Script executed:
#!/bin/bash
# Check if dereferenceSchemas.js was updated for this new schema
git ls-files | grep -i dereferenceRepository: doc-detective/common
Length of output: 97
🏁 Script executed:
#!/bin/bash
# Verify the examples array in config_v3.schema.json includes the new properties
sed -n '519,632p' src/schemas/src_schemas/config_v3.schema.json | head -150Repository: doc-detective/common
Length of output: 2340
🏁 Script executed:
#!/bin/bash
# Check if config_v3.schema.json is in dereferenceSchemas.js files array
cat src/schemas/dereferenceSchemas.jsRepository: doc-detective/common
Length of output: 7023
🏁 Script executed:
#!/bin/bash
# Search for where fileMapping is actually assigned (broader pattern)
rg -nP 'fileMapping' --type=js --type=ts -C3Repository: doc-detective/common
Length of output: 46
🏁 Script executed:
#!/bin/bash
# Check if uploadOnChange appears in examples (user-configurable property)
rg -n 'uploadOnChange' src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 101
🏁 Script executed:
#!/bin/bash
# Get the full Heretto example entry to see what's documented
sed -n '604,632p' src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 575
🏁 Script executed:
#!/bin/bash
# Verify uploadOnChange is NOT marked readOnly (user-configurable)
sed -n '280,290p' src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 682
Add uploadOnChange property to the Heretto integration example.
The new uploadOnChange property is user-configurable (not readOnly) with a default value, but it's missing from the Heretto integration example in the schema's examples array. Update the example to include uploadOnChange to align with the coding guideline that all schemas must include examples (required for test generation).
The fileMapping and resourceDependencies properties are correctly marked readOnly as system-generated, so they don't require examples.
🤖 Prompt for AI Agents
In src/schemas/src_schemas/config_v3.schema.json around lines 262 to 279, the
Heretto integration example in the schema's "examples" array is missing the
user-configurable uploadOnChange property (which is not readOnly and has a
default), so update the relevant example object to include "uploadOnChange":
<defaultValue> (use the schema's default, e.g., true or false as appropriate for
this project) alongside the existing fields; keep fileMapping and
resourceDependencies as-is (readOnly) and ensure the examples array remains
valid JSON after the addition.
| "resourceDependencies": { | ||
| "type": "object", | ||
| "description": "Mapping of Heretto file paths to their UUIDs and metadata. Set automatically during content loading by fetching ditamap resource dependencies.", | ||
| "readOnly": true, | ||
| "additionalProperties": { | ||
| "type": "object", | ||
| "properties": { | ||
| "uuid": { | ||
| "type": "string", | ||
| "description": "The UUID of the file in Heretto." | ||
| }, | ||
| "fullPath": { | ||
| "type": "string", | ||
| "description": "The full xmldb path of the file in Heretto." | ||
| }, | ||
| "name": { | ||
| "type": "string", | ||
| "description": "The file name." | ||
| }, | ||
| "parentFolderId": { | ||
| "type": "string", | ||
| "description": "The UUID of the parent folder in Heretto." | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, find and examine the schema file
find . -name "config_v3.schema.json" -type fRepository: doc-detective/common
Length of output: 199
🏁 Script executed:
# Read the schema file to check current state, especially around resourceDependencies
# and verify if examples array exists
cat -n src/schemas/src_schemas/config_v3.schema.json | head -320 | tail -100Repository: doc-detective/common
Length of output: 5105
🏁 Script executed:
# Search for resourceDependencies usage in the codebase
rg -n "resourceDependencies" --type=js --type=ts -A3 -B3Repository: doc-detective/common
Length of output: 46
🏁 Script executed:
# Search more broadly for resourceDependencies in all file types
rg -n "resourceDependencies" --type=jsonRepository: doc-detective/common
Length of output: 672
🏁 Script executed:
# Read the full schema file to see structure and check for examples array
wc -l src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 113
🏁 Script executed:
# Read the beginning of the schema file to understand structure
head -50 src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 1912
🏁 Script executed:
# Check if examples array exists anywhere in the config_v3 schema
rg -n "examples" src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 83
🏁 Script executed:
# Check the examples array location and structure
sed -n '519,570p' src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 1315
🏁 Script executed:
# Check if the schema follows the coding guideline about examples
# Look at the end of the file to see the structure
tail -100 src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 2023
🏁 Script executed:
# Search for code that actually populates resourceDependencies
rg -n "resourceDependencies" --type=js --type=tsRepository: doc-detective/common
Length of output: 46
🏁 Script executed:
# Broader search for resourceDependencies in all files
rg -n "resourceDependencies" --type=tsRepository: doc-detective/common
Length of output: 212
🏁 Script executed:
# Check if there's a heretto integration module that sets resourceDependencies
find . -name "*heretto*" -type fRepository: doc-detective/common
Length of output: 46
🏁 Script executed:
# Look for any code that mentions ditamap or resource dependencies
rg -n "ditamap|resource.*depend" --type=ts --type=js -iRepository: doc-detective/common
Length of output: 46
🏁 Script executed:
# Look at the heretto section structure in examples to see if resourceDependencies is shown
grep -n "heretto" -A 20 src/schemas/src_schemas/config_v3.schema.json | grep -A 20 "examples"Repository: doc-detective/common
Length of output: 46
🏁 Script executed:
# Check the heretto items schema definition more carefully
sed -n '226,312p' src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 3990
🏁 Script executed:
# Look for any TypeScript/JavaScript files in src directory (check actual type)
find src -type f \( -name "*.ts" -o -name "*.js" \) | head -20Repository: doc-detective/common
Length of output: 180
🏁 Script executed:
# Check if there's implementation code that populates resourceDependencies
rg -n "resourceDependencies" src/files.js -A 5 -B 5Repository: doc-detective/common
Length of output: 46
🏁 Script executed:
# Also check if there's a need for required fields in nested objects
# Look at fileMapping to compare - does it have a required array?
sed -n '262,279p' src/schemas/src_schemas/config_v3.schema.jsonRepository: doc-detective/common
Length of output: 794
🏁 Script executed:
# Check the actual heretto integration usage/implementation
cat src/files.js | head -100Repository: doc-detective/common
Length of output: 2533
🏁 Script executed:
# Check if there are other source schemas and if they have examples arrays
find src/schemas/src_schemas -name "*.json" -type f -exec basename {} \;Repository: doc-detective/common
Length of output: 1446
🏁 Script executed:
# Verify examples array presence in another source schema
rg -l "examples" src/schemas/src_schemas/Repository: doc-detective/common
Length of output: 2838
🏁 Script executed:
# Check the output schema to see if it's different from source schema
diff src/schemas/src_schemas/config_v3.schema.json src/schemas/output_schemas/config_v3.schema.json | head -50Repository: doc-detective/common
Length of output: 1308
🏁 Script executed:
# Check if the coding guideline about examples applies - look at a simpler schema
cat src/schemas/src_schemas/wait_v3.schema.json | head -40Repository: doc-detective/common
Length of output: 750
🏁 Script executed:
# Check context_v3.schema.json to understand the examples pattern
cat src/schemas/src_schemas/context_v3.schema.json | head -80Repository: doc-detective/common
Length of output: 2556
🏁 Script executed:
# Verify the exact coding guideline - look for any schema-level references to examples
rg -n "examples" src/schemas/src_schemas/wait_v3.schema.jsonRepository: doc-detective/common
Length of output: 82
Add examples for resourceDependencies and verify if nested properties require explicit required array.
The resourceDependencies structure lacks examples in the schema. Per coding guidelines, all schemas must include examples for test generation. Add an example showing a populated resourceDependencies object (e.g., with a uuid, fullPath, name, and parentFolderId entry).
Additionally, since resourceDependencies is automatically populated during content loading by fetching ditamap resource dependencies, verify whether all four nested properties (uuid, fullPath, name, parentFolderId) are always present. If they are, add a required array to the nested object definition to improve schema validation accuracy.
🤖 Prompt for AI Agents
In src/schemas/src_schemas/config_v3.schema.json around lines 285-310, the
resourceDependencies schema is missing an example and may lack an explicit
required array for its nested properties; add an "examples" (or "example") entry
showing a sample mapping (e.g., a file path key mapping to an object with uuid,
fullPath, name, parentFolderId populated) directly under the
resourceDependencies definition, and if those four nested properties are always
present at runtime, add a "required":
["uuid","fullPath","name","parentFolderId"] to the nested object definition
inside additionalProperties so validation reflects that all fields must exist.
|
📝 Documentation updates detected! Updated existing suggestion: Document Heretto CMS integration for DITA content testing |
There was a problem hiding this comment.
Pull request overview
This PR implements a Heretto CMS uploader feature to enable screenshot synchronization with an external CMS. The changes add metadata tracking for source integration through new JSON schemas and update path resolution logic to handle Heretto-specific URI schemes.
- Introduces a new
sourceIntegration_v3schema to track file metadata from CMS integrations - Extends screenshot and config schemas to support source integration metadata
- Updates path resolution to recognize and preserve
heretto:URI schemes - Upgrades development dependencies (chai, sinon) to latest versions
Reviewed changes
Copilot reviewed 14 out of 24 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/schemas/src_schemas/sourceIntegration_v3.schema.json | Defines new schema for CMS source integration metadata |
| src/schemas/src_schemas/screenshot_v3.schema.json | Adds sourceIntegration property to screenshot schema |
| src/schemas/src_schemas/config_v3.schema.json | Adds Heretto configuration properties for file mapping and upload settings |
| src/schemas/schemas.json | Consolidated schema file with sourceIntegration additions |
| src/schemas/output_schemas/*.json | Output versions of updated schemas with sourceIntegration support |
| src/schemas/dereferenceSchemas.js | Registers new sourceIntegration schema for dereferencing |
| src/resolvePaths.js | Updates path resolution to handle heretto: URI scheme |
| package.json | Updates chai and sinon dev dependencies |
| package-lock.json | Dependency lock file updates with transitive dependency changes |
| dist/schemas/*.json | Distribution versions of updated schemas |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Introduce a HerettoUploader class to automate screenshot uploads to Heretto CMS, enhancing the existing upload process. Update path resolution to support heretto: URIs and improve error handling for upload operations. Add documentation and tests to ensure functionality and reliability. Upgrade dependencies as needed.
Summary by CodeRabbit
New Features
Chores
✏️ Tip: You can customize this high-level summary in your review settings.