#1830 https://github.com/mosip/commons/issues/1830 Move release-1.3.x changes to develop #74
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| # AGENTS.md | ||
|
|
||
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | ||
|
|
||
| ## Project Overview | ||
|
|
||
| MOSIP Demo SDK is a Java library implementing demographic authentication for the [MOSIP ID-Authentication](https://github.com/mosip/id-authentication) subsystem. It is consumed as a Maven dependency — it has no runnable entry point of its own. | ||
|
|
||
| The SDK implements two interfaces from `kernel-demographics-api`: | ||
| - `IDemoApi` — demographic data matching (exact, partial, phonetic) | ||
| - `IDemoNormalizer` — name and address string normalization driven by Spring Environment properties | ||
|
|
||
| ## Build Commands | ||
|
|
||
| All commands run from the `demosdk/` subdirectory (where `pom.xml` lives): | ||
|
|
||
| ```bash | ||
| # Build and install to local Maven repo (skip GPG signing and Javadoc for local dev) | ||
| mvn clean install -Dmaven.javadoc.skip=true -Dgpg.skip=true | ||
|
|
||
| # Run all tests | ||
| mvn test | ||
|
|
||
| # Run a single test class | ||
| mvn test -Dtest=ClientV1UnitTest | ||
| mvn test -Dtest=NormalizerV1UnitTest | ||
| mvn test -Dtest=TextMatcherUtilTest | ||
|
|
||
| # Run Sonar analysis (requires sonar credentials) | ||
| mvn verify -Psonar | ||
| ``` | ||
|
|
||
| The surefire plugin passes `--enable-preview` and several `--add-opens` flags automatically — no extra JVM args are needed when running tests through Maven. | ||
|
|
||
| ## Architecture | ||
|
|
||
| ``` | ||
| demosdk/src/main/java/io/mosip/demosdk/client/ | ||
| ├── impl/spec_1_0/ | ||
| │ ├── Client_V_1_0.java # IDemoApi implementation | ||
| │ └── Normalizer_V_1_0.java # IDemoNormalizer implementation | ||
| ├── utils/ | ||
| │ └── TextMatcherUtil.java # Phonetic matching (BeiderMorse + Soundex) | ||
| └── config/ | ||
| └── LoggerConfig.java # MOSIP rolling-file logger setup | ||
| ``` | ||
|
|
||
| ### Matching Logic (`Client_V_1_0`) | ||
|
|
||
| All three match methods return an integer 0–100: | ||
|
|
||
| - **Exact match**: tokenizes both strings by whitespace (lowercased), returns 100 only if token sets are equal (order-insensitive). | ||
| - **Partial match**: `matchedTokens * 100 / (entityTokenCount + unmatchedRefTokenCount)`. Single-character ref tokens may match any entity token that starts with that character. | ||
| - **Phonetic match**: delegates to `TextMatcherUtil.phoneticsMatch`, which encodes both strings with Apache BeiderMorse (`PhoneticEngine`) then scores the Soundex difference: `(soundexDifference + 1) * 20` → range 20–100. | ||
|
|
||
| ### Normalization (`Normalizer_V_1_0`) | ||
|
|
||
| Patterns are loaded lazily from Spring `Environment` properties using the key template: | ||
|
|
||
| ``` | ||
| ida.demo.<type>.normalization.regex.<language>[<index>] | ||
| ``` | ||
|
|
||
| where `type` is `name`, `address`, or `common`; `language` is the BCP 47 tag or `any`. Each value is `<regex>=<replacement>` (separator configurable via `ida.norm.sep`, default `=`). Indices are iterated 0–999 and stop at the first missing key. | ||
|
|
||
| `normalizeName` additionally strips title prefixes (e.g., "Mr", "Dr") supplied by the caller before applying regex patterns. `normalizeWithCommonAttributes` always merges patterns for the specific language + `any` + `common/<language>` + `common/any`. | ||
|
|
||
| ### Testing Patterns | ||
|
|
||
| Tests use JUnit 4 + Mockito 5. Because `Normalizer_V_1_0.environment` is `@Autowired` (private field), tests inject a mocked `Environment` via reflection — see `NormalizerV1UnitTest.setUp()`. Static methods in `TextMatcherUtil` are mocked with `mockStatic` from Mockito's `MockedStatic` API. | ||
|
|
||
| ## Key Dependencies | ||
|
|
||
| | Artifact | Purpose | | ||
| |---|---| | ||
| | `kernel-demographics-api:1.3.0` | `IDemoApi` and `IDemoNormalizer` interfaces | | ||
| | `kernel-logger-logback:1.3.0` | MOSIP Logback wrapper (`Logfactory`) | | ||
| | `commons-codec` | Soundex and BeiderMorse phonetic encoding | | ||
| | `spring-web` / `spring-core` | `Environment` injection in normalizer | | ||
| | `jackson-databind`, `jackson-dataformat-xml` | JSON/XML support pulled in transitively | | ||
|
|
||
| ## Configuration Properties | ||
|
|
||
| The normalizer reads from whatever Spring `Environment` is active (typically `id-authentication-default.properties` in the consuming service). Relevant property keys: | ||
|
|
||
| - `ida.demo.<type>.normalization.regex.<language>[<n>]` — normalization pattern at index `n` | ||
| - `ida.norm.sep` — separator between regex and replacement (default `=`) | ||
|
|
||
| ## Release / Publishing | ||
|
|
||
| Artifacts are signed with GPG (key in `.github/keys/`) and published to Maven Central via `central-publishing-maven-plugin`. The `autoPublish` flag is `false`, so promotion to release must be done manually in the Sonatype portal. Snapshot builds go to `https://central.sonatype.com/repository/maven-snapshots`. |
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,69 @@ | ||
| # MOSIP Demo SDK | ||
|
|
||
| [](https://github.com/mosip/demosdk/actions/workflows/push-trigger.yml) | ||
| [](https://sonarcloud.io/dashboard&id=mosip_demosdk) | ||
|
|
||
| ## Overview | ||
|
|
||
| The **Demo SDK** provides core demographic authentication capabilities used by the **ID Authentication subsystem**. | ||
| It includes: | ||
|
|
||
| - Demographic data matching logic | ||
| - Name and address normalization utilities | ||
| - Support functions required for demographic authentication workflows | ||
|
|
||
| This SDK is referenced by **ID-Authentication**, available here: | ||
| https://github.com/mosip/id-authentication/tree/master/authentication | ||
|
|
||
| ## Installation | ||
|
|
||
| ### Local Setup (for Development or Contribution) | ||
|
|
||
| 1. Clone the repository: | ||
|
|
||
| ```text | ||
| git clone <repo-url> | ||
| cd demosdk | ||
| ``` | ||
|
|
||
| 2. Build the project: | ||
|
|
||
| ```text | ||
| mvn clean install -Dmaven.javadoc.skip=true -Dgpg.skip=true | ||
| ``` | ||
|
|
||
| This will compile the SDK and install it into your local Maven repository. | ||
|
|
||
| ## Usage | ||
|
|
||
| It's used as a library dependency in the **ID-Authentication** project. | ||
| To include Demo SDK in your Maven project: | ||
|
|
||
| ```xml | ||
| <dependency> | ||
| <groupId>io.mosip.demosdk</groupId> | ||
| <artifactId>demosdk</artifactId> | ||
| <version>1.3.0</version><!-- use latest released version --> | ||
| </dependency> | ||
| ``` | ||
|
|
||
| (Replace **1.3.0** with the appropriate released version.) | ||
|
|
||
| For detailed usage examples and integration steps, refer to the **ID-Authentication repository**. | ||
|
|
||
| ## Documentation | ||
|
|
||
| Additional documentation and design references are available in the main MOSIP documentation portal: | ||
| https://github.com/mosip/documentation/tree/1.2.0/docs | ||
|
|
||
| ## Contribution & Community | ||
|
|
||
| • To learn how you can contribute code to this application, [click here](https://docs.mosip.io/community/code-contributions). | ||
|
|
||
| • If you have questions or encounter issues, visit the [MOSIP Community](https://community.mosip.io/) for support. | ||
|
|
||
| • For any GitHub issues: [Report here](https://github.com/mosip/demosdk/issues) | ||
|
|
||
| ## License | ||
|
|
||
| This project is licensed under the [Mozilla Public License 2.0](LICENSE). | ||
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
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
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,128 @@ | ||||||
| THIRD-PARTY-NOTICES | ||||||
|
|
||||||
| This project includes third-party packages that are distributed under various open-source licenses. Below is a list of packages and their associated licenses. | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Spring Framework | ||||||
| (includes: spring-web, spring-boot-test-autoconfigure, spring-security-test) | ||||||
| Version: Not specified in SBOM | ||||||
| License: Apache License 2.0 (Inferred from project’s official repository) | ||||||
| Homepage: https://spring.io/projects/spring-framework | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Spring Boot Maven Plugin | ||||||
| Version: 3.2.3 | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://spring.io/projects/spring-boot | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Jackson JSON Processor | ||||||
| (includes: jackson-databind, jackson-module-jaxb-annotations, jackson-dataformat-xml) | ||||||
| Version: Not specified in SBOM | ||||||
| License: Apache License 2.0 (Inferred from official FasterXML repository) | ||||||
| Homepage: https://github.com/FasterXML/jackson | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Google Gson | ||||||
| Version: Not specified in SBOM | ||||||
| License: Apache License 2.0 (Inferred from official project repository) | ||||||
| Homepage: https://github.com/google/gson | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: JSON.simple | ||||||
| Version: Not specified in SBOM | ||||||
| License: Apache License 2.0 (Inferred from official project repository) | ||||||
| Homepage: https://github.com/fangyidong/json-simple | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Apache Commons Lang (commons-lang3) | ||||||
| Version: Not specified in SBOM | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://commons.apache.org/proper/commons-lang/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Apache Commons Codec (commons-codec) | ||||||
| Version: Not specified in SBOM | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://commons.apache.org/proper/commons-codec/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Apache HttpClient | ||||||
| Version: Not specified in SBOM | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://hc.apache.org/httpcomponents-client-5.0.x/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: MOSIP Kernel Libraries | ||||||
| (includes: kernel-core, kernel-bom, kernel-demographics-api, kernel-logger-logback) | ||||||
| Version: 1.4.0-SNAPSHOT | ||||||
| License: Mozilla Public License 2.0 (Inferred from MOSIP official repository) | ||||||
| Homepage: https://github.com/mosip | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Project Lombok | ||||||
| Version: Not specified in SBOM | ||||||
| License: MIT License | ||||||
| Homepage: https://projectlombok.org/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: JUnit 4 | ||||||
| Version: Not specified in SBOM | ||||||
| License: Eclipse Public License 1.0 (Inferred from project’s official repository) | ||||||
| Homepage: https://junit.org/junit4/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: SLF4J | ||||||
| (includes: jul-to-slf4j, jcl-over-slf4j) | ||||||
| Version: Not specified in SBOM | ||||||
| License: MIT License (Inferred from project’s official repository) | ||||||
| Homepage: http://www.slf4j.org/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Maven GPG Plugin | ||||||
| Version: 1.5 | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://maven.apache.org/plugins/maven-gpg-plugin/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Maven Source Plugin | ||||||
| Version: 2.2.1 | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://maven.apache.org/plugins/maven-source-plugin/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Maven Javadoc Plugin | ||||||
| Version: 3.2.0 | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://maven.apache.org/plugins/maven-javadoc-plugin/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Maven Compiler Plugin | ||||||
| Version: 3.8.0 | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://maven.apache.org/plugins/maven-compiler-plugin/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| ================================================================================ | ||||||
| Package: Maven Assembly Plugin | ||||||
| Version: 3.3.0 | ||||||
| License: Apache License 2.0 | ||||||
| Homepage: https://maven.apache.org/plugins/maven-assembly-plugin/ | ||||||
| ================================================================================ | ||||||
|
|
||||||
| Full license texts and additional details for each of the above packages are available in the license/ directory of this repository. Please refer to those files or the original source of each package for complete legal terms and conditions. | ||||||
|
There was a problem hiding this comment. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
# Check for license directory naming
fd -t d -d 1 '^licens' .Repository: mosip/demosdk Length of output: 69 🏁 Script executed: #!/bin/bash
set -euo pipefail
ls -1
echo "----"
# confirm license dir presence
ls -1 | rg -n '^licenses/?$' || true
ls -1 | rg -n '^license/?$' || true
echo "---- THIRD-PARTY-NOTICES.txt excerpt ----"
# show the exact lines around the reported location
sed -n '115,140p' THIRD-PARTY-NOTICES.txt | nl -baRepository: mosip/demosdk Length of output: 273 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "---- license dir check ----"
ls -1 | rg -n '^licenses/?$' || true
ls -1 | rg -n '^license/?$' || true
echo "---- THIRD-PARTY-NOTICES.txt lines 120-135 ----"
awk 'NR>=120 && NR<=135 {printf "%d:%s\n", NR, $0}' THIRD-PARTY-NOTICES.txt
echo "---- occurrences of 'Footer' ----"
rg -n --fixed-string "Footer" THIRD-PARTY-NOTICES.txt || true
echo "---- occurrences of 'license/' ----"
rg -n --fixed-string "license/" THIRD-PARTY-NOTICES.txt || true
echo "---- occurrences of 'licenses/' ----"
rg -n --fixed-string "licenses/" THIRD-PARTY-NOTICES.txt || trueRepository: mosip/demosdk Length of output: 2194 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "---- THIRD-PARTY-NOTICES.txt line count ----"
wc -l THIRD-PARTY-NOTICES.txt
echo "---- THIRD-PARTY-NOTICES.txt last 20 lines ----"
tail -n 20 THIRD-PARTY-NOTICES.txt | nl -ba || tail -n 20 THIRD-PARTY-NOTICES.txt
echo "---- occurrences of 'Footer' (plain) ----"
rg -n "Footer" THIRD-PARTY-NOTICES.txt || true
echo "---- occurrences of 'license/' ----"
rg -n "license/" THIRD-PARTY-NOTICES.txt || true
echo "---- occurrences of 'licenses/' ----"
rg -n "licenses/" THIRD-PARTY-NOTICES.txt || trueRepository: mosip/demosdk Length of output: 1634 Fix incorrect Proposed fix-Full license texts and additional details for each of the above packages are available in the license/ directory of this repository. Please refer to those files or the original source of each package for complete legal terms and conditions.
+Full license texts and additional details for each of the above packages are available in the licenses/ directory of this repository. Please refer to those files or the original source of each package for complete legal terms and conditions.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Update documentation link to current version.
The documentation link references version
1.2.0, which is outdated given the upgrade to1.4.0-SNAPSHOT. Consider updating to the current documentation version or using a version-agnostic URL if available.🤖 Prompt for AI Agents