feat: add where-used portal inventory workflow#130
Merged
Conversation
…, structures, templates and ADTs New `portal inventory where-used` subcommand walks every page in scope and reports which ones reference a given resource. Supports fragments, widgets (by name or portletId), structures (by ddmStructureKey, contentStructureId or content-structure summary), web content templates and ADTs (display-page templates). Multi-key OR-search via repeatable --key, optional --site scoping, optional --include-private to also scan private layouts, and parallelised page fetches via --concurrency. The matcher is a pure function operating on the existing LiferayInventoryPageResult shape, so no new portal data sources are needed — it reuses the same metadata that `inventory page` already exposes.
There was a problem hiding this comment.
Pull request overview
Adds a new reverse-lookup (“where-used”) workflow to ldev portal inventory, built on normalized “page evidence” extracted during page inspection to support consistent matching across regular pages and display pages.
Changes:
- Introduces
ldev portal inventory where-usedwith schema/formatting, candidate collection (layouts + display pages), and evidence-to-query matching/normalization. - Adds “page evidence” generation for regular pages and display pages, plus new fragment field resource extraction (mapped template/structure keys) and journal article ref resolution/dedup improvements.
- Improves gateway error messages to include the failing request path; updates docs/AI templates and expands unit test coverage for the new workflow.
Reviewed changes
Copilot reviewed 40 out of 40 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/liferay-inventory-where-used.test.ts | Adds unit coverage for query validation, evidence matching, display-page candidate handling, and where-used formatting/schema. |
| tests/unit/liferay-inventory-page.test.ts | Updates page inventory tests for new evidence/mapped keys and display-page URL-title decoding behavior. |
| tests/unit/liferay-inventory-page-fetch-journal.test.ts | Adds targeted tests for journal article reference dedupe/merge behavior during page inspection. |
| tests/unit/liferay-inventory-journal-article-resolver.test.ts | Adds unit tests for the new journal article reference resolver behavior and fallback paths. |
| tests/unit/liferay-gateway.test.ts | Verifies gateway errors include the request path. |
| templates/ai/workspace-rules/ldev-portal-discovery.md | Documents where-used as the preferred reverse lookup workflow and recommends --site. |
| templates/ai/skills/liferay-expert/SKILL.md | Adds where-used to the Liferay discovery command sequence for agents. |
| templates/ai/skills/developing-liferay/SKILL.md | Adds where-used to the pre-edit portal discovery flow for developers/agents. |
| src/features/liferay/liferay-gateway.ts | Wraps JSON success validation to append path=... to gateway errors. |
| src/features/liferay/inventory/liferay-inventory-where-used.ts | Implements the where-used scan orchestration (site resolution, candidate scan, matching, summarization). |
| src/features/liferay/inventory/liferay-inventory-where-used-schema.ts | Adds zod schema validation for where-used result contracts. |
| src/features/liferay/inventory/liferay-inventory-where-used-pages.ts | Adds page tree flattening and constructs where-used page match output (incl. display-page rendering heuristics). |
| src/features/liferay/inventory/liferay-inventory-where-used-page-candidates.ts | Collects/dedupes page candidates from layouts and structured-content display pages with skippable-source handling. |
| src/features/liferay/inventory/liferay-inventory-where-used-normalize.ts | Normalizes evidence for structure queries to suppress redundant matches. |
| src/features/liferay/inventory/liferay-inventory-where-used-match.ts | Matches normalized page evidence against where-used queries and dedupes match output. |
| src/features/liferay/inventory/liferay-inventory-where-used-format.ts | Adds human-readable formatting for where-used output. |
| src/features/liferay/inventory/liferay-inventory-where-used-display-pages.ts | Adds display-page candidate enumeration via headless structured contents and JSONWS journal fallbacks with caching. |
| src/features/liferay/inventory/liferay-inventory-url.ts | Introduces buildPortalAbsoluteUrl and re-exports display-page URL building. |
| src/features/liferay/inventory/liferay-inventory-page.ts | Extends inventory page results and JSON projection to include optional normalized evidence and mapped keys. |
| src/features/liferay/inventory/liferay-inventory-page-url.ts | Reuses shared display-page URL-title extraction (now decoding percent-encoded titles). |
| src/features/liferay/inventory/liferay-inventory-page-schema.ts | Updates validated page result schema to accept evidence and mapped fragment resource keys. |
| src/features/liferay/inventory/liferay-inventory-page-json-schema.ts | Updates JSON schema to accept evidence and mapped fragment resource keys. |
| src/features/liferay/inventory/liferay-inventory-page-fragment-fields.ts | Extracts fragment editable fields plus mapped structure/template keys from fragment field mappings. |
| src/features/liferay/inventory/liferay-inventory-page-fetch.ts | Generates page evidence during fetch; updates journal article collection to include headless page element inspection. |
| src/features/liferay/inventory/liferay-inventory-page-fetch-journal.ts | Refactors article reference extraction/dedup and uses the new article resolver for structured content + article resolution. |
| src/features/liferay/inventory/liferay-inventory-page-fetch-fragments.ts | Minor formatting/spacing adjustments around fragment entry link fetch. |
| src/features/liferay/inventory/liferay-inventory-page-fetch-article.ts | Extends ArticleRef to include structuredContentId. |
| src/features/liferay/inventory/liferay-inventory-page-evidence.ts | Implements evidence extraction/builders for fragments, widgets/portlets, journal article structure/template usage, and display page article structure id. |
| src/features/liferay/inventory/liferay-inventory-page-evidence-detail.ts | Centralizes human-readable evidence detail strings and journal article evidence context. |
| src/features/liferay/inventory/liferay-inventory-page-assemble.ts | Integrates fragment field resource extraction (editable fields + mapped keys) into page element assembly. |
| src/features/liferay/inventory/liferay-inventory-journal-article-resolver.ts | Adds reusable resolver to fetch/derive article + structured content + resolved article id. |
| src/features/liferay/inventory/liferay-inventory-evidence-contract.ts | Defines evidence/where-used contract enums + zod schemas (resource types, kinds, sources, context). |
| src/features/liferay/inventory/liferay-inventory-display-page-url.ts | Centralizes display-page URL/title parsing and building (incl. percent-decoding). |
| src/features/liferay/content/liferay-content-journal-shared.ts | Extends JSONWS journal row type to include url title fields used for display page candidate building. |
| src/commands/liferay/inventory.command.ts | Adds the inventory where-used CLI command with options and help text. |
| docs/workflows/explore-portal.md | Documents reverse lookup workflow and recommends scoped scans (--site). |
| docs/core-concepts/discovery.md | Adds where-used to discovery/impact analysis guidance. |
| docs/commands/discovery.md | Adds command docs for ldev portal inventory where-used. |
| docs/agentic/index.md | Adds where-used to the agent discovery flow guidance. |
| CONTEXT.md | Introduces the “Page evidence” term in the shared glossary and updates a markdown table layout. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a new
portal inventory where-usedworkflow, expands inventory evidence so template usage can also be found from rendered journal HTML, exposes the new reverse lookup through MCP, and hardens CLI JSON output for UTF-8-safe machine consumption.What changed
ldev portal inventory where-usedfor fragment, widget, portlet, structure, template, and ADT reverse lookupwhere-used, including repeatable--site,--exclude-site,--site-limit,--site-order, and--planliferay_inventory_where_usedand added direct MCP tool coverageValidation
npx vitest run tests/unit/liferay-inventory-where-used.test.ts --reporter=verbosenpx vitest run tests/unit/mcp-server-tools.test.ts tests/unit/liferay-inventory-where-used.test.ts --reporter=verbosenpx vitest run tests/unit/tool-liferay-inventory-where-used.test.ts tests/unit/mcp-server-tools.test.ts --reporter=verboseNotes